@kici-dev/orchestrator 0.17.0 → 0.19.0

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

@@ -1,20 +1,14 @@
 /**
- * Firecracker scaler backend implementation.
+ * Ephemeral agent microVMs under the Firecracker jailer. Lifecycle: prepare chroot, hardlink
+ * rootfs+kernel, create overlay drive, invoke jailer, inject MMDS metadata, destroy with cleanup.
+ * Mirrors the Docker backend's structure.
  *
- * Manages ephemeral agent microVMs using the Firecracker VMM via the jailer.
- * Handles full VM lifecycle: prepare chroot, hardlink rootfs+kernel, create overlay drive,
- * invoke jailer, inject MMDS metadata, and destroy with cleanup.
- *
- * Log capture: Firecracker backend handles log forwarding internally.
- * The jailer is spawned as a non-daemonized detached child with stdout redirected to a
- * serial console log file and VMM logs captured via --log-path. Both files are tailed
- * using fs.watchFile() and forwarded with distinct logsSource tags ('firecracker-serial',
- * 'firecracker-vmm'). The serial-console path is best-effort only: Firecracker's Rust
- * BufWriter around stdout + jailer's uid drop make sparse userspace writes unreliable,
- * so it's treated as defense-in-depth. The canonical agent log path is WS agent.log
- * (attached unconditionally by the agent; see packages/agent/src/server.ts step 6).
- *
- * Follows the Docker backend pattern closely for consistency.
+ * Log capture is internal: the jailer runs as a non-daemonized detached child with stdout
+ * redirected to a serial console log file and VMM logs captured via --log-path. Both files are
+ * tailed and forwarded with logsSource tags 'firecracker-serial' and 'firecracker-vmm'. The
+ * serial path is best-effort defense-in-depth: Firecracker's Rust BufWriter around stdout plus
+ * the jailer's uid drop make sparse userspace writes unreliable. The canonical agent log path
+ * is WS agent.log (attached unconditionally by the agent; see packages/agent/src/server.ts step 6).
  */
 import { ScalerVmTracker, type ScalerVmStopResult } from '@kici-dev/engine';
 import { type ToolRequirement } from '@kici-dev/shared';
@@ -36,17 +30,13 @@ export interface FirecrackerManagedAgent extends ManagedAgent {
     /** TAP device name for cleanup */
     tapDevice: string;
     /**
-     * The `hostAccess` policy resolved for this VM at provision time.
-     *
-     * Carried on the record because a bridge self-heal re-applies isolation for
-     * every live VM, and that path has no `orchestratorUrl` to re-derive the
-     * default from.
+     * The `hostAccess` policy resolved at provision time. Carried because a bridge self-heal
+     * re-applies isolation for every live VM and has no `orchestratorUrl` to re-derive it.
      */
     hostAccess?: string[];
     /**
-     * Set once the VM's agent registered with the orchestrator. Until then a VM
-     * that stops on its own is a failed spawn, and nothing else will tear it
-     * down; afterwards the agent's disconnect does.
+     * Set once the VM's agent registered. Until then a VM that stops on its own is a failed
+     * spawn nothing else tears down; afterwards the agent's disconnect does.
      */
     registered?: boolean;
 }
@@ -55,19 +45,15 @@ export interface FirecrackerScalerBackendOptions {
     name: string;
     /** Label sets this backend can provision */
     labelSets: LabelSetConfig[];
-    /** Maximum concurrent agents */
     maxAgents: number;
     /** Shared IP allocator instance */
     ipAllocator: IpAllocator;
     /**
-     * Extra `hostAccess` entries the orchestrator itself directed agents at —
-     * today its object-storage endpoint. Folded into the agent default so the
-     * narrowing does not cut off a host-local object store.
+     * Extra `hostAccess` entries the orchestrator itself directed agents at (its object-storage
+     * endpoint), folded into the agent default so the narrowing keeps a host-local object store.
      */
     hostServices?: string[];
-    /** Path to firecracker binary */
     firecrackerPath: string;
-    /** Path to jailer binary */
     jailerPath: string;
     /** Default kernel image path */
     kernelPath: string;
@@ -96,41 +82,39 @@ export interface FirecrackerScalerBackendOptions {
     netmask: string;
     /** nft table name for host-network diagnostics. @default 'kici' */
     table?: string;
-    /** Token store for creating ephemeral agent auth tokens. Optional -- when undefined, no token is injected. */
+    /** Token store for ephemeral agent auth tokens; when undefined, no token is injected. */
     tokenStore?: AgentTokenStore;
     /** TTL for ephemeral agent tokens in ms. Default: 1 hour. */
     tokenTtlMs?: number;
     /**
-     * Live resolver for the ephemeral agent-token TTL (ms). When set, called per
-     * spawn so the leader can serve the fleet-wide
-     * `cluster_settings.agent_token_ttl_ms` override; falls back to `tokenTtlMs`.
+     * Live per-spawn resolver for the ephemeral agent-token TTL (ms), so the leader serves the
+     * fleet-wide `cluster_settings.agent_token_ttl_ms` override; falls back to `tokenTtlMs`.
      */
     tokenTtlProvider?: () => Promise<number>;
     /**
-     * How long a spawn waits for the VM's API socket after the jailer starts, in
-     * ms. Default {@link DEFAULT_API_SOCKET_WAIT_MS}.
+     * How long (ms) a spawn waits for the VM's API socket after the jailer starts.
+     * Default {@link DEFAULT_API_SOCKET_WAIT_MS}.
      */
     apiSocketWaitMs?: number;
     /**
      * Live per-spawn resolver for the API-socket wait, so the fleet-wide
-     * `cluster_settings.firecracker_api_socket_wait_ms` applies without a
-     * restart. Falls back to `apiSocketWaitMs`.
+     * `cluster_settings.firecracker_api_socket_wait_ms` applies without a restart. Falls back
+     * to `apiSocketWaitMs`.
      */
     apiSocketWaitMsProvider?: () => Promise<number>;
     /** Agent roles for this scaler. undefined = all, [] = execution only. */
     roles?: string[];
     /**
-     * Wrap privileged commands (`ip`, `chown`) with `sudo -n`. Required when the
-     * orchestrator runs as a non-root user (e.g. user-mode systemd on edge worker
-     * nodes) and operators have set up a sudoers NOPASSWD rule for those binaries.
-     * On hosts where the orchestrator already runs as root, leave this false.
+     * Wrap privileged commands (`ip`, `chown`) with `sudo -n`. Required when the orchestrator
+     * runs as a non-root user (e.g. user-mode systemd on edge worker nodes) with a sudoers
+     * NOPASSWD rule for those binaries; leave false when it runs as root.
      * @default false
      */
     requireSudo?: boolean;
     /**
-     * When true, `ensureHostReady()` verifies and provisions this host bridge on
-     * startup (self-heal). Threaded from `firecracker.autoProvisionHost`. When
-     * false the method is a no-op. @default false (cores pass the real value)
+     * When true, `ensureHostReady()` verifies and provisions this host bridge on startup
+     * (self-heal); when false it is a no-op. Threaded from `firecracker.autoProvisionHost`.
+     * @default false (cores pass the real value)
      */
     autoProvisionHost?: boolean;
     /** Injectable bridge verifier (tests). @default host-network verifyBridge */
@@ -146,12 +130,9 @@ export declare class FirecrackerScalerBackend implements ScalerBackend, LiveVmBa
     /** AbortControllers for file tailing per managed VM (keyed by agent ID) */
     private readonly tailAbortControllers;
     /**
-     * Per-spawn `scaler.failed` emitters, keyed by agent id.
-     *
-     * The jailer's `exit` handler and the spawn-deadline abort both fire outside
-     * `spawn`'s own scope, and the manager releases a spawn reservation only on a
-     * failure event. Holding the emitter here is what lets those two paths report
-     * the failure instead of leaving the reservation held until restart.
+     * Per-spawn `scaler.failed` emitters, keyed by agent id. The jailer's `exit` handler and the
+     * spawn-deadline abort fire outside `spawn`'s scope, and the manager releases a spawn
+     * reservation only on a failure event; without this the reservation stays held until restart.
      */
     private readonly spawnFailureHandlers;
     /** Liveness probes of spawned VMs whose agent has not registered yet, by agent id. */
@@ -231,44 +212,32 @@ export declare class FirecrackerScalerBackend implements ScalerBackend, LiveVmBa
         bridgeCidr: string;
         table: string;
     };
+    /**
+     * nft options for this backend's own rules. `table` is the operator-configured one, not the
+     * literal `kici`: with two coordinators on one host, B's per-VM rules in A's `kici` table
+     * would be swept by A's next re-provision and evaluated against A's subnet-scoped baseline.
+     */
+    private nftOpts;
     /**
      * Verify and (if needed) provision this backend's host bridge on startup.
      * No-op unless autoProvisionHost is set. Throws on a real provision failure;
      * ScalerManager.ensureHostsReady catches per-backend and degrades this scaler.
      */
-    /**
-     * nft options for this backend's own rules.
-     *
-     * `table` is the operator-configured one, not the literal `kici`: with two
-     * coordinators on one host, coordinator B's baseline goes to `kici_b` while
-     * its per-VM rules used to go to `kici` — coordinator A's table. A's next
-     * re-provision then swept B's live VMs' isolation along with its own, and B's
-     * rules were evaluated against A's subnet-scoped baseline.
-     */
-    private nftOpts;
     ensureHostReady(): Promise<void>;
     /**
-     * Fail loudly on a kernel that will not honour bridge port isolation.
-     *
-     * Without the flag every concurrent tenant's VM can reach every other one at
-     * L2, and no nft rule sees that traffic — so the isolation the operator docs
-     * promise silently does not exist. The same fail-closed posture
-     * `validateNftablesAvailability` takes for a missing `nft`: better to refuse
-     * to run VMs than to run them unisolated.
+     * Fail loudly on a kernel that will not honour bridge port isolation. Without the flag every
+     * tenant VM reaches every other one at L2, unseen by nft, so the documented isolation silently
+     * does not exist. Fail-closed like `validateNftablesAvailability` for a missing `nft`.
      *
-     * The probe is an end-to-end one — create a TAP, enslave it isolated, delete
-     * it — because the flag can be rejected by the kernel, by iproute2, or by the
-     * bridge itself, and only the real command exercises all three.
+     * The probe is end-to-end (create a TAP, enslave it isolated, delete it) because the kernel,
+     * iproute2 or the bridge can each reject the flag, and only the real command exercises all three.
      */
     private assertBridgePortIsolationSupported;
     /**
-     * Re-apply per-VM isolation rules for every VM this backend still tracks.
-     *
-     * Provisioning no longer deletes the table, but it does sweep the `forward`
-     * chain of everything no live VM owns, and an old-shaped host carries its
-     * baseline there too. Re-applying is what guarantees a self-heal cannot leave
-     * a running VM fail-open. Each identifier is removed before it is re-added,
-     * so a self-heal that fires twice does not duplicate the rules.
+     * Re-apply per-VM isolation rules for every tracked VM. Provisioning sweeps the `forward`
+     * chain of everything no live VM owns (an old-shaped host carries its baseline there too), so
+     * this keeps a self-heal from leaving a running VM fail-open. Each identifier is removed
+     * before it is re-added, so a self-heal that fires twice does not duplicate the rules.
      */
     private reapplyIsolationForTrackedVms;
     markRegistered(managedId: string): void;
@@ -280,13 +249,11 @@ export declare class FirecrackerScalerBackend implements ScalerBackend, LiveVmBa
     /**
      * Keep loosening a rootless VM's chroot permissions while firecracker starts.
      *
-     * The jailer chmods the chroot root and every directory it creates (`/run`)
-     * to 0700 owned by its `--uid`, which locks out an orchestrator running as
-     * another user from `/run/firecracker.socket`. A `chmod -R go+rX` every
-     * 100 ms reopens each one as soon as it appears; it only changes the
-     * host-side view. One chmod runs at a time: on a slow disk a `sudo chmod -R`
-     * can outlast the tick, and overlapping ones would pile up for the whole
-     * wait.
+     * The jailer chmods the chroot root and every directory it creates (`/run`) to 0700 owned by
+     * its `--uid`, locking an orchestrator running as another user out of
+     * `/run/firecracker.socket`. A `chmod -R go+rX` every 100 ms reopens each one as it appears
+     * (host-side view only). One chmod runs at a time: on a slow disk a `sudo chmod -R` can
+     * outlast the tick, and overlapping ones would pile up for the whole wait.
      *
      * @returns a function that stops the loosening
      */
@@ -296,26 +263,19 @@ export declare class FirecrackerScalerBackend implements ScalerBackend, LiveVmBa
     /**
      * Tear the VM down if its process stops before its agent registers.
      *
-     * A guest whose init exits — the agent's fatal startup error, a kernel panic
-     * — reboots, and firecracker exits. Its agent will never register, and
-     * nothing else releases the VM's `maxAgents` slot, TAP, nft rules, IP and
-     * chroot until the manager's stale-spawn prune. The jailer child's own exit
-     * cannot tell this: under `--new-pid-ns` it exits 0 right after the start.
-     * So the VM's process is probed through its PID file, and the probe stops
-     * once the agent registers (its disconnect owns the teardown from then on),
-     * the VM is being destroyed, or it is no longer tracked.
+     * A guest whose init exits (fatal agent startup error, kernel panic) reboots and firecracker
+     * exits; nothing else releases its `maxAgents` slot, TAP, nft rules, IP and chroot until the
+     * manager's stale-spawn prune. The jailer child's exit cannot tell: under `--new-pid-ns` it
+     * exits 0 right after the start. So the VM's PID file is probed until the agent registers (its
+     * disconnect then owns the teardown), the VM is being destroyed, or it is no longer tracked.
      */
     private watchUntilRegistered;
     /**
-     * Whether there is positive evidence that a VM's firecracker process is
-     * gone: its PID file does not exist, the PID it names no longer exists, or
-     * that PID now belongs to a process that started after `sinceUptimeS`
-     * (seconds since boot, taken once firecracker was already running).
-     *
-     * Any other failure — an unreadable PID file, a `/proc` this user cannot
-     * see — is not evidence, so the answer is "not gone". The caller tears the
-     * VM down on a "gone", and tearing down a live VM leaves firecracker running
-     * without its TAP, IP and chroot.
+     * Whether there is positive evidence a VM's firecracker is gone: no PID file, no such PID, or
+     * the PID belongs to a process started after `sinceUptimeS` (seconds since boot, taken once
+     * firecracker was running). Any other failure (unreadable PID file, invisible `/proc`) is
+     * "not gone": the caller tears down on "gone", and tearing down a live VM leaves firecracker
+     * running without its TAP, IP and chroot.
      */
     private isVmProcessGone;
     /** Stop forwarding a VM's serial console and VMM logs. */
@@ -325,23 +285,17 @@ export declare class FirecrackerScalerBackend implements ScalerBackend, LiveVmBa
     /**
      * Force-reclaim a VM this backend no longer tracks in memory.
      *
-     * `destroy()` opens with `if (!managed) return`, so after an orchestrator
-     * restart it silently no-ops while the VM keeps running, holding its RAM and
-     * its IP. `cleanupOrphans()` cannot recover that VM either: every one of its
-     * three passes skips an id whose jailer process is alive, deliberately, since
-     * a live process is the only thing that distinguishes a healthy VM from a
-     * leaked one when you are sweeping blind.
+     * After an orchestrator restart `destroy()` no-ops (`if (!managed) return`) while the VM keeps
+     * its RAM and IP, and `cleanupOrphans()` deliberately skips any id whose jailer process is
+     * alive: sweeping blind, a live process is all that tells a healthy VM from a leaked one.
      *
-     * This is the same reclaim addressed to ONE id whose orphan status the caller
-     * already established, so the liveness check is exactly what must not apply.
-     * See `ScalerBackend.reapUnowned` for the two properties the caller relies on;
-     * the host-local half is enforced here by refusing to act unless the jailer
-     * chroot for `managedId` exists on THIS host. That directory is the only
-     * host-local artifact a VM leaves: an `ip_allocations` row is not one, because
-     * an HA pair is "two identical orchestrators sharing the same PostgreSQL,
-     * scalers, and routing key" (`docs/operator/orchestrator/clustering.md`), so a
-     * peer's live VM has a row naming this very scaler. The row is read only to
-     * finish a reclaim the chroot already authorized.
+     * This is the same reclaim for ONE id the caller already established as an orphan, so the
+     * liveness check must not apply. See `ScalerBackend.reapUnowned` for the two properties the
+     * caller relies on; the host-local half is enforced here by refusing to act unless the jailer
+     * chroot for `managedId` exists on THIS host. That directory is the only host-local artifact a
+     * VM leaves: an HA pair shares PostgreSQL, scalers and routing key
+     * (`docs/operator/orchestrator/clustering.md`), so a peer's live VM has an `ip_allocations`
+     * row naming this very scaler. The row is read only to finish a reclaim the chroot authorized.
      */
     reapUnowned(managedId: string): Promise<boolean>;
     private reapUnownedLocked;
@@ -355,15 +309,13 @@ export declare class FirecrackerScalerBackend implements ScalerBackend, LiveVmBa
     /** Whether this scaler's allocator holds the address of `vmId`. */
     ownsAllocationFor(vmId: string): Promise<boolean>;
     /**
-     * Reclaim the host resources of a VM nothing tracks, once its process is
-     * dead: forward its remaining logs, remove its isolation rules, TAP and IP,
-     * and delete its chroot.
+     * Reclaim the host resources of a dead, untracked VM: forward its remaining logs, remove its
+     * isolation rules, TAP and IP, and delete its chroot.
      *
-     * A second firecracker scaler on this host has its own IP space and its own
-     * teardown, so only a row naming THIS scaler is ours to release. With no such
-     * row (a worker's in-memory allocator forgets every row on restart) the TAP
-     * named after the VM's id is deleted: the name derives from this VM's id
-     * alone, so it cannot be another VM's.
+     * Only a row naming THIS scaler is ours to release: a second firecracker scaler on this host
+     * has its own IP space and teardown. With no such row (a worker's in-memory allocator forgets
+     * every row on restart) the TAP named after the VM's id is deleted; that name cannot be
+     * another VM's.
      */
     private teardownUntrackedVm;
     /** Whether a live VM is one this backend spawned and still tracks. */
@@ -377,15 +329,13 @@ export declare class FirecrackerScalerBackend implements ScalerBackend, LiveVmBa
     /**
      * Stop one live VM nothing on this node tracks, on an operator's request.
      *
-     * The tracked check that authorises the kill and the first `kill(2)` run in
-     * one synchronous tick: tracking only changes between ticks (a registration,
-     * a rehydrated spawn row, a new spawn), so nothing can claim the VM between
-     * the check and the signal. The kernel can still recycle the PID number in
-     * that window; `destroy` and `reapUnowned` carry the same window, and Node
-     * has no pidfd to close it.
+     * The tracked check and the first `kill(2)` run in one synchronous tick: tracking only changes
+     * between ticks (a registration, a rehydrated spawn row, a new spawn), so nothing can claim the
+     * VM in between. The kernel can still recycle the PID in that window, as in `destroy` and
+     * `reapUnowned`; Node has no pidfd to close it.
      *
-     * Runs under the host reclaim lock, so a sweep cannot release this VM's
-     * address to a new VM while the stop is still removing its rules.
+     * Runs under the host reclaim lock, so a sweep cannot release this VM's address to a new VM
+     * while the stop is still removing its rules.
      *
      * @param trackersOf what else on this node tracks the VM, read in the
      *   kill's tick; it must not await.
@@ -395,22 +345,20 @@ export declare class FirecrackerScalerBackend implements ScalerBackend, LiveVmBa
     /**
      * SIGKILL a VM's firecracker process.
      *
-     * The jailer drops firecracker to `--uid`, so an orchestrator running as
-     * another unprivileged user gets EPERM from `kill(2)`. On a rootless host
-     * (`requireSudo`) the signal goes through `sudo -n -u #<uid> kill`; anywhere
-     * else EPERM means the process lacks CAP_KILL. ESRCH means the process is
-     * already gone, which is the outcome wanted.
+     * The jailer drops firecracker to `--uid`, so another unprivileged user gets EPERM from
+     * `kill(2)`. On a rootless host (`requireSudo`) the signal goes through
+     * `sudo -n -u #<uid> kill`; elsewhere EPERM means the process lacks CAP_KILL. ESRCH (already
+     * gone) is success.
      *
-     * The first statement is the synchronous `kill(2)`: `stopUntrackedVm` relies
-     * on the signal leaving in its caller's tick.
+     * The first statement is the synchronous `kill(2)`: `stopUntrackedVm` relies on the signal
+     * leaving in its caller's tick.
      */
     private signalVmProcess;
     /** Whether `/proc/<pid>` names a process right now. */
     private procEntryExists;
     /**
-     * {@link signalVmProcess} for the teardown paths: a failure is logged, never
-     * swallowed, and reported so the caller keeps the chroot of a process that
-     * still runs.
+     * {@link signalVmProcess} for the teardown paths: a failure is logged and reported, so the
+     * caller keeps the chroot of a process that still runs.
      *
      * @returns whether the process was signalled or was already gone
      */
@@ -424,15 +372,9 @@ export declare class FirecrackerScalerBackend implements ScalerBackend, LiveVmBa
     private withHostReclaimLock;
     shutdownAll(): Promise<void>;
     /**
-     * Clear MMDS data for an agent after receiving config.ack via WS.
-     * Belt-and-suspenders: even though MMDS only contains orchestrator URL,
-     * clearing it reduces the attack surface to zero post-startup.
-     *
-     * Called by `ScalerManager.onConfigAck`, which reaches it structurally
-     * (`'clearAgentMmds' in backend`) rather than through `ScalerBackend` — no
-     * other backend has an MMDS to clear.
-     *
-     * @param agentId - The agent ID whose VM MMDS should be cleared
+     * Clear an agent's MMDS data after its config.ack arrives via WS, so nothing is left to read
+     * post-startup (belt-and-suspenders). Called by `ScalerManager.onConfigAck` structurally
+     * (`'clearAgentMmds' in backend`), not through `ScalerBackend`: no other backend has an MMDS.
      */
     clearAgentMmds(agentId: string): Promise<void>;
     reload(labelSets: LabelSetConfig[], opts?: {
@@ -440,47 +382,38 @@ export declare class FirecrackerScalerBackend implements ScalerBackend, LiveVmBa
         entry?: ScalerEntry;
     }): ValidationResult;
     /**
-     * Clean up orphaned VMs.
+     * Clean up orphaned VMs; returns the count cleaned.
      *
-     * Safe to call both at startup AND periodically while the backend is active
-     * (see startPeriodicOrphanSweep): each pass explicitly skips VMs that are
-     * currently tracked in-memory (spawning / running / destroying), and Pass 3
-     * re-reads DB allocations after listing host interfaces to close the spawn
-     * race (allocate → ip tuntap add is not atomic).
+     * Safe at startup AND periodically (startPeriodicOrphanSweep): each pass skips VMs tracked
+     * in-memory (spawning / running / destroying), and Pass 3 re-reads DB allocations after
+     * listing host interfaces to close the spawn race (allocate → ip tuntap add is not atomic).
      *
-     * Three passes:
+     * Passes:
      * 1. DB allocations: check if VM process is still running, clean dead ones
      * 2. Filesystem: scan chroot dir for directories not in DB allocations
      * 3. Network: scan host interfaces for orphan TAP devices
-     *
-     * Returns the count of cleaned orphans.
+     * 4. nftables: reap isolation rules no live VM owns
      */
     cleanupOrphans(): Promise<number>;
     private cleanupOrphansLocked;
     /**
      * Delete isolation rules for every identifier no live VM owns.
      *
-     * The live set is the VM ids the passes above established, mapped to the IPs
-     * this scaler allocated for them. An identifier the DB does not attribute to
-     * a live VM of this scaler is left alone: a second scaler on the same host
-     * writes to the same chain, and reaping its rules would cut its running jobs
-     * off the network — the mistake this whole sweep exists to stop making.
+     * The live set is the passes' live VM ids, mapped to this scaler's allocated IPs. An
+     * identifier the DB does not attribute to this scaler is left alone: a second scaler on the
+     * host writes to the same chain, and reaping its rules would cut its running jobs off.
      *
      * @returns the number of rules deleted
      */
     private reapUnownedIsolationRules;
     /**
-     * Default interval for periodic orphan sweeps (15 minutes).
-     *
-     * Long-running orchestrators need in-process orphan sweeps because a
-     * host-level cleanup job skips TAP cleanup while an orchestrator is active
-     * (to avoid racing spawns). Without this, leaked
-     * TAPs accumulate until the orchestrator restarts — which can be weeks.
+     * Default periodic orphan sweep interval (15 minutes). A host-level cleanup job skips TAP
+     * cleanup while an orchestrator is active (to avoid racing spawns), so without this sweep
+     * leaked TAPs accumulate until the orchestrator restarts, which can be weeks.
      */
     private static readonly ORPHAN_SWEEP_INTERVAL_MS;
     /**
-     * Start a periodic orphan sweep. Idempotent — calling twice has no effect
-     * beyond the first call. Use stopPeriodicOrphanSweep() to stop.
+     * Start a periodic orphan sweep. Idempotent; stopPeriodicOrphanSweep() stops it.
      *
      * @param intervalMs override the default interval (primarily for tests)
      */
@@ -494,17 +427,14 @@ export declare class FirecrackerScalerBackend implements ScalerBackend, LiveVmBa
      * Build the merged forwarded-env map for an agent's MMDS payload.
      *
      * Mirrors bare-metal/container precedence: KICI_AGENT_ENV_*-prefixed vars from the
-     * orchestrator's process.env (prefix stripped) are seeded first, then scalers.yaml
-     * `env:` overlays them (yaml wins on conflict).
+     * orchestrator's process.env (prefix stripped) first, then scalers.yaml `env:` (yaml wins).
      *
-     * Two safety filters apply:
-     * - Keys must match POSIX_ENV_NAME_PATTERN. Otherwise rejected to keep MMDS path
-     *   construction safe inside the VM and to prevent the guest from being asked to
-     *   `export` something the shell can't represent.
-     * - The cumulative byte cost (key + value + 2-byte overhead per entry) must stay
-     *   under MMDS_FORWARDED_ENV_BUDGET_BYTES. Once exceeded, remaining entries are
-     *   skipped and warnings logged. This protects the ~51 KiB MMDS data store cap
-     *   from being blown by an accidentally-huge env value.
+     * Safety filters:
+     * - Keys must match POSIX_ENV_NAME_PATTERN, keeping MMDS path construction safe and never
+     *   asking the guest to `export` something the shell can't represent.
+     * - The cumulative cost (key + value + 2 bytes per entry) must stay under
+     *   MMDS_FORWARDED_ENV_BUDGET_BYTES; entries past it are skipped with a warning, protecting
+     *   the ~51 KiB MMDS store cap from a huge env value.
      */
     buildForwardedEnv(matchedLabelSet: LabelSetConfig, agentId: string): Record<string, string>;
     /**
@@ -515,10 +445,9 @@ export declare class FirecrackerScalerBackend implements ScalerBackend, LiveVmBa
      *   2. label-set's vcpuCount/memSizeMib.
      *   3. backend-level default vcpuCount/memSizeMib.
      *
-     * Firecracker requires integer vCPUs and integer MiB. We round CPUs UP via
-     * Math.ceil to never under-provision (a 0.5-CPU request still gets a whole vCPU)
-     * and floor-divide bytes -> MiB. A debug log is emitted when rounding actually
-     * changes the value, so operators can spot frequent fractional requests.
+     * Firecracker requires integer vCPUs and MiB: CPUs round UP (a 0.5-CPU request gets a whole
+     * vCPU, never under-provisioned) and bytes floor-divide to MiB. A rounding that changes the
+     * value logs at debug, so operators can spot frequent fractional requests.
      */
     buildVmConfig(alloc: IpAllocationResult, labelSet: LabelSetConfig, effectiveLimits?: EffectiveLimits): Record<string, unknown>;
     /**
@@ -545,26 +474,15 @@ export declare class FirecrackerScalerBackend implements ScalerBackend, LiveVmBa
     /**
      * Remove a VM's jailer chroot directory.
      *
-     * On rootless nodes (requireSudo), the jailer chowns the chroot contents to
-     * the jailer uid/gid, leaving the inner directories owned by that uid with
-     * mode 0755 — so the orchestrator process (a different, non-root uid) has no
-     * write permission on them and a plain `rm` fails with EACCES. destroy() and
-     * both cleanupOrphans passes treat removal as best-effort and swallow that
-     * failure, so each spawn would otherwise leak a multi-GiB chroot until the
-     * data disk fills and the orchestrator crash-loops on ENOSPC (it can no
-     * longer write its own files to start, so the in-process orphan sweep never
-     * runs to recover). Reclaim ownership via the same sudo-wrapped `chown` path
-     * used for `ip` before the `rm` runs as ourselves. On root nodes (requireSudo
-     * false) the chown is skipped and `rm` works directly.
+     * On rootless nodes (requireSudo) the jailer leaves inner directories owned by its uid with
+     * mode 0755, so a plain `rm` by the orchestrator's uid fails with EACCES. destroy() and both
+     * cleanupOrphans passes swallow that failure, so each spawn would leak a multi-GiB chroot
+     * until the data disk fills and the orchestrator crash-loops on ENOSPC (unable to start, so
+     * its orphan sweep never recovers). Ownership is reclaimed via the sudo-wrapped `chown` first;
+     * root nodes skip it.
      */
     private removeChrootDir;
-    /**
-     * Get the API socket path for an agent's Firecracker VM.
-     */
     getSocketPath(agentId: string): string;
-    /**
-     * Get the chroot directory path for an agent.
-     */
     getChrootDir(agentId: string): string;
     /**
      * Probe the process a VM's PID file names.
@@ -585,80 +503,46 @@ export declare class FirecrackerScalerBackend implements ScalerBackend, LiveVmBa
      */
     private probeVmPid;
     /**
-     * Read a VM's PID file and return the PID only when the process it names is
-     * provably still *this* VM's firecracker process.
-     *
-     * This is the guard for acting ON the process — `destroy` and `reapUnowned`
-     * SIGKILL through it — so it fails closed: anything short of a confirmed
-     * identity yields `undefined` and nothing is signalled.
-     *
-     * @returns the PID when it is provably this VM's, otherwise `undefined`
+     * The PID from a VM's PID file, only when it is provably still *this* VM's firecracker.
+     * `destroy` and `reapUnowned` SIGKILL through it, so it fails closed: anything short of a
+     * confirmed identity yields `undefined` and nothing is signalled.
      */
     private readVmPid;
     /**
      * Whether a chroot's PID file names a process that is running right now.
      *
-     * This is the guard for the orphan reaper, which asks the opposite question
-     * from {@link readVmPid} and therefore fails closed in the opposite
-     * direction. `readVmPid` refuses to signal a PID it cannot claim; the reaper
-     * must refuse to DELETE THE ROOTFS under one. A process whose `comm` or
-     * `/proc/<pid>/root` does not match is still a process, and deleting the
-     * files it is running out of corrupts whatever it is — while sparing it costs
-     * only the disk one chroot occupies.
-     *
-     * The leak the identity checks exist to prevent is unaffected: a recycled
-     * number is detected by start time, which this guard honours, so a chroot
-     * whose VM is genuinely over is still reclaimed.
+     * The orphan reaper's guard fails closed opposite to {@link readVmPid}: that refuses to signal
+     * a PID it cannot claim; the reaper must refuse to DELETE THE ROOTFS under one. A process whose
+     * `comm` or `/proc/<pid>/root` does not match is still a process, and deleting its files
+     * corrupts it, while sparing it costs one chroot's disk. A recycled PID is still detected by
+     * start time, so a chroot whose VM is genuinely over is still reclaimed.
      */
     private isChrootPidRunning;
     /**
-     * Whether *this* VM's own firecracker process is still up.
-     *
-     * Liveness is `readVmPid` plus signal 0, so it answers the identity-bearing
-     * question — "is the VM I started still running?" — that
-     * {@link waitForProcessExit} needs. Without the identity checks a recycled
-     * PID answers signal 0 successfully and the VM is spared forever.
-     *
-     * The orphan reaper asks a different question and uses
-     * {@link isChrootPidRunning} instead: a PID it cannot claim is still a live
-     * process, and its rootfs must not be deleted underneath it.
+     * Whether *this* VM's own firecracker process is still up: `readVmPid` plus signal 0, the
+     * identity-bearing question {@link waitForProcessExit} needs. Without the identity checks a
+     * recycled PID answers signal 0 and the VM is spared forever. The orphan reaper uses
+     * {@link isChrootPidRunning} instead.
      */
     private isVmProcessAlive;
-    /**
-     * Wait for a VM's jailer process to exit within a timeout.
-     */
     private waitForProcessExit;
-    /**
-     * Clean up resources after a failed spawn attempt.
-     */
     private cleanupFailedSpawn;
     /**
-     * Start tailing serial console and VMM log files, forwarding lines directly
-     * via forwardLine() with distinct logsSource tags.
-     *
-     * Also monitors the jailer child process for early exit (boot failure detection).
-     * Forwarding is handled internally (not through ScalerManager/AgentLogForwarder)
-     * because Firecracker has two distinct log sources per VM.
+     * Tail the serial console and VMM log files, forwarding lines via forwardLine() with distinct
+     * logsSource tags, and watch the jailer child for early exit (boot failure). Forwarding is
+     * internal, not through ScalerManager/AgentLogForwarder, because each VM has two log sources.
      */
     private startLogTailing;
     /**
-     * Tail a single log file and forward each line via forwardLine().
-     * For serial console lines: non-JSON lines (kernel boot output) are wrapped
+     * Tail one log file into forwardLine(). Non-JSON serial lines (kernel boot output) are wrapped
      * as debug-level JSON; failure patterns (kernel panic, init failure) are elevated to error.
      */
     private tailAndForward;
-    /**
-     * Check if a serial console line matches known boot failure patterns.
-     */
+    /** Whether a serial console line matches a known boot failure pattern. */
     private isFailurePattern;
-    /**
-     * Read the serial console log file and detect the type of boot failure.
-     */
+    /** Classify a boot failure from the serial console log. */
     private detectFailureType;
-    /**
-     * Read and forward any remaining log file content for an orphaned/dead VM.
-     * Called during cleanupOrphans() before deleting the chroot directory.
-     */
+    /** Forward a dead VM's remaining log content before its chroot is deleted. */
     private forwardRemainingLogs;
 }
 //# sourceMappingURL=firecracker-backend.d.ts.map