@kici-dev/orchestrator 0.1.15 → 0.1.16

package/dist/cli.js

@@ -1,15 +1,17 @@
 #!/usr/bin/env node
 import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+import * as path$1 from "node:path";
+import path, { join, resolve } from "node:path";
 import { Command } from "commander";
-import { BaseColdStore, ChunkLru, chunkObjectKey, clearDispatchQueueDirect, computeChunkId, computeMigrationsHash, createDb, createDbRole, createEnvironmentTemplateDirect, createLogger, createPool, createReadOnlyDbUser, decodeChunk, deleteEnvironmentDirect, dropAndCreateDatabase, emitKiciEventDirect, encodeKeySegment, ensureDatabase, formatBytes, formatUptime, isSchemaCurrent, listEnvironmentsDirect, listExecutionRunsDirect, listQueueDirect, listRegistrationsDirect, maskDatabaseUrl, parseDatabaseUrl, parseManifest, prunePeerCredentialsDirect, purgeScopedSecretsDirect, purgeSecretBackendsDirect, purgeStaleExecutionDirect, purgeStaleSourcesDirect, registerWorkflowManualDirect, resetRaftStateDirect, seedEnvironmentBindingDirect, seedEnvironmentDirect, setEnvironmentPolicyDirect, setEnvironmentSecretDirect, sha256, showEnvironmentDirect, showExecutionRunDirect, showQueueEntryDirect, showRegistrationDirect, storeMigrationContentHash, tablePrefix, toErrorMessage } from "@kici-dev/shared";
 import * as fs$1 from "node:fs";
-import fs, { createWriteStream, promises, readFileSync } from "node:fs";
+import fs, { closeSync, createReadStream, createWriteStream, existsSync, openSync, promises, readFileSync, statSync, unwatchFile, watchFile, writeFileSync } from "node:fs";
+import { BaseColdStore, ChunkLru, addLogsToArchive, chunkObjectKey, clearDispatchQueueDirect, computeChunkId, computeMigrationsHash, createDb, createDbRole, createEnvironmentTemplateDirect, createLogger, createPool, createReadOnlyDbUser, decodeChunk, deleteEnvironmentDirect, dropAndCreateDatabase, emitKiciEventDirect, encodeKeySegment, ensureDatabase, formatBytes, formatUptime, isSchemaCurrent, listEnvironmentsDirect, listExecutionRunsDirect, listQueueDirect, listRegistrationsDirect, maskDatabaseUrl, parseDatabaseUrl, parseManifest, prunePeerCredentialsDirect, purgeScopedSecretsDirect, purgeSecretBackendsDirect, purgeStaleExecutionDirect, purgeStaleSourcesDirect, registerWorkflowManualDirect, resetRaftStateDirect, seedEnvironmentBindingDirect, seedEnvironmentDirect, setEnvironmentPolicyDirect, setEnvironmentSecretDirect, sha256, showEnvironmentDirect, showExecutionRunDirect, showQueueEntryDirect, showRegistrationDirect, storeMigrationContentHash, tablePrefix, toErrorMessage } from "@kici-dev/shared";
 import crypto, { createDecipheriv, createHash, hkdfSync, randomBytes, randomUUID } from "node:crypto";
 import { createInterface } from "node:readline";
-import { readFile, writeFile } from "node:fs/promises";
-import { stringify } from "yaml";
+import { access, chmod, constants, copyFile, link, mkdir, open, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { parse, stringify } from "yaml";
 import { z } from "zod";
-import "node:os";
 import os from "node:os";
 import { getDatabaseCollationDrift, refreshDatabaseCollationVersion, reindexDatabaseConcurrently } from "@kici-dev/shared/db-collation";
 import { sql } from "kysely";
@@ -17,17 +19,17 @@ import { Migrator } from "kysely/migration";
 import "jsonpath-plus";
 import { execFile, execFileSync, execSync, spawn } from "node:child_process";
 import { promisify } from "node:util";
-import * as path$1 from "node:path";
-import path from "node:path";
 import archiver from "archiver";
+import { confirm, input, password, select } from "@inquirer/prompts";
 import JSZip from "jszip";
-import { fileURLToPath } from "node:url";
 import { pipeline } from "node:stream/promises";
-import { confirm, input, password, select } from "@inquirer/prompts";
 import "pg";
 import { DASHBOARD_WRITE_OPERATIONS, DASHBOARD_WRITE_OPERATIONS_BY_NAME, DashboardWriteCategory, DashboardWriteSensitivity } from "@kici-dev/engine/protocol/dashboard-write-operations";
 import { CLUSTER_NAME_FORMAT_MESSAGE } from "@kici-dev/engine/protocol/cluster-name";
-import { TERMINAL_JOB_STATES, TERMINAL_RUN_STATES, WS_MAX_PAYLOAD_BYTES, accessLogWarmSqlCase, getAccessLogColdDays, getSecretAuditLogColdDays, minAccessLogWarmDays, minSecretAuditLogWarmDays, secretAuditLogWarmSqlCase } from "@kici-dev/engine";
+import { KICI_AGENT_ENV_PREFIX, KNOWN_ROLES, ScalerBackendType, ScalerEventType, TERMINAL_JOB_STATES, TERMINAL_RUN_STATES, WS_MAX_PAYLOAD_BYTES, accessLogWarmSqlCase, getAccessLogColdDays, getSecretAuditLogColdDays, minAccessLogWarmDays, minSecretAuditLogWarmDays, scalerAgentLabels, secretAuditLogWarmSqlCase } from "@kici-dev/engine";
+import http from "node:http";
+import { PassThrough } from "node:stream";
+import Docker from "dockerode";
 var __defProp = Object.defineProperty;
 var __esmMin = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
 var __exportAll = (all, no_symbols) => {
@@ -42,6 +44,13 @@ var __exportAll = (all, no_symbols) => {
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 //#endregion
 //#region src/cli/api-client.ts
+/**
+* HTTP client wrapper for the kici-admin CLI.
+*
+* Communicates with the orchestrator admin API via Bearer token authentication.
+* All methods are thin wrappers around fetch() that handle JSON serialization,
+* error formatting, and URL construction.
+*/
 var AdminApiClient = class {
 	constructor(baseUrl, token) {
 		this.baseUrl = baseUrl;
@@ -116,6 +125,27 @@ var AdminApiClient = class {
 		if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
 		return res.text();
 	}
+	/** Enumerate the cluster topology for `debug-bundle --fleet --list` / `--pick`. */
+	async getFleetTopology() {
+		return this.get("/admin/fleet-topology");
+	}
+	/**
+	* Drive the fleet fan-out and write the assembled ZIP to `outPath`. The
+	* response is an octet-stream, so it is read as bytes rather than parsed JSON.
+	*/
+	async downloadFleetBundle(body, outPath) {
+		const res = await fetch(`${this.baseUrl}/admin/fleet-bundle`, {
+			method: "POST",
+			headers: {
+				Authorization: `Bearer ${this.token}`,
+				"Content-Type": "application/json"
+			},
+			body: JSON.stringify(body)
+		});
+		if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
+		const buf = Buffer.from(await res.arrayBuffer());
+		fs$1.writeFileSync(outPath, buf);
+	}
 	async listScopes(orgId) {
 		return this.request("GET", `/api/v1/admin/secrets/scopes?orgId=${encodeURIComponent(orgId)}`);
 	}
@@ -1518,8 +1548,8 @@ var init_client = __esmMin((() => {
 //#region src/db/migrations/001_initial.ts
 init_client();
 var _001_initial_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$31,
-	up: () => up$31
+	down: () => down$33,
+	up: () => up$33
 });
 /**
 * Squashed initial migration -- creates the complete Orchestrator database schema.
@@ -2211,7 +2241,7 @@ const DDL_STATEMENTS = [
 	`ALTER TABLE ONLY public.held_runs
     ADD CONSTRAINT held_runs_environment_id_fkey FOREIGN KEY (environment_id) REFERENCES public.environments(id);`
 ];
-async function up$31(db) {
+async function up$33(db) {
 	for (const stmt of DDL_STATEMENTS) await sql.raw(stmt).execute(db);
 	await sql`
     INSERT INTO cluster_meta (key, value)
@@ -2233,7 +2263,7 @@ async function up$31(db) {
 * Rollback drops everything created above. Uses CASCADE on table drops to cut
 * through the FK graph without relying on exact topological order.
 */
-async function down$31(db) {
+async function down$33(db) {
 	for (const [trig, tbl] of [["source_secrets_change_trigger", "scoped_secrets"], ["sources_change_trigger", "sources"]]) await sql.raw(`DROP TRIGGER IF EXISTS ${trig} ON public.${tbl}`).execute(db);
 	for (const table of [
 		"workflow_registrations",
@@ -2280,8 +2310,8 @@ async function down$31(db) {
 //#endregion
 //#region src/db/migrations/002_config_versions_key_version.ts
 var _002_config_versions_key_version_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$30,
-	up: () => up$30
+	down: () => down$32,
+	up: () => up$32
 });
 /**
 * Add key_version column to config_versions so that sensitive-field encryption
@@ -2295,13 +2325,13 @@ var _002_config_versions_key_version_exports = /* @__PURE__ */ __exportAll({
 * No index is needed: rotation does a full-table scan; reads are by
 * `version` primary key and never filter on `key_version`.
 */
-async function up$30(db) {
+async function up$32(db) {
 	await sql`
     ALTER TABLE public.config_versions
       ADD COLUMN key_version integer NOT NULL DEFAULT 1
   `.execute(db);
 }
-async function down$30(db) {
+async function down$32(db) {
 	await sql`
     ALTER TABLE public.config_versions
       DROP COLUMN key_version
@@ -2310,8 +2340,8 @@ async function down$30(db) {
 //#endregion
 //#region src/db/migrations/003_access_log.ts
 var _003_access_log_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$29,
-	up: () => up$29
+	down: () => down$31,
+	up: () => up$31
 });
 /**
 * Access log: one row per read or orchestrator-admin mutation attributable
@@ -2335,7 +2365,7 @@ var _003_access_log_exports = /* @__PURE__ */ __exportAll({
 * Retention is TTL-based via expires_at; packages/orchestrator/src/queue/
 * cleanup.ts picks up the prune pass.
 */
-async function up$29(db) {
+async function up$31(db) {
 	await sql`
     CREATE TABLE public.access_log (
       id            UUID PRIMARY KEY DEFAULT gen_random_uuid(),
@@ -2373,28 +2403,28 @@ async function up$29(db) {
       ON public.access_log (actor_type, actor_id, created_at DESC)
   `.execute(db);
 }
-async function down$29(db) {
+async function down$31(db) {
 	await sql`DROP TABLE IF EXISTS public.access_log`.execute(db);
 }
 //#endregion
 //#region src/db/migrations/004_rename_bundle_to_source.ts
 var _004_rename_bundle_to_source_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$28,
-	up: () => up$28
+	down: () => down$30,
+	up: () => up$30
 });
-async function up$28(db) {
+async function up$30(db) {
 	await db.schema.alterTable("dispatch_queue").renameColumn("bundle_url", "source_tar_url").execute();
 	await db.schema.alterTable("dispatch_queue").renameColumn("bundle_hash", "source_tar_hash").execute();
 }
-async function down$28(db) {
+async function down$30(db) {
 	await db.schema.alterTable("dispatch_queue").renameColumn("source_tar_url", "bundle_url").execute();
 	await db.schema.alterTable("dispatch_queue").renameColumn("source_tar_hash", "bundle_hash").execute();
 }
 //#endregion
 //#region src/db/migrations/005_cold_store_chunk_counter.ts
 var _005_cold_store_chunk_counter_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$27,
-	up: () => up$27
+	down: () => down$29,
+	up: () => up$29
 });
 /**
 * Cold-store chunk counter table.
@@ -2411,7 +2441,7 @@ var _005_cold_store_chunk_counter_exports = /* @__PURE__ */ __exportAll({
 *
 * sections 5 and 8.
 */
-async function up$27(db) {
+async function up$29(db) {
 	await sql`
     CREATE TABLE public.cold_store_chunk_counts (
       db                TEXT        NOT NULL,
@@ -2429,14 +2459,14 @@ async function up$27(db) {
       ON public.cold_store_chunk_counts (db, table_name)
   `.execute(db);
 }
-async function down$27(db) {
+async function down$29(db) {
 	await sql`DROP TABLE IF EXISTS public.cold_store_chunk_counts`.execute(db);
 }
 //#endregion
 //#region src/db/migrations/006_runs_jobs_steps_archived_at.ts
 var _006_runs_jobs_steps_archived_at_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$26,
-	up: () => up$26
+	down: () => down$28,
+	up: () => up$28
 });
 /**
 * `execution_runs` / `execution_jobs` / `execution_steps` cold-store
@@ -2472,7 +2502,7 @@ var _006_runs_jobs_steps_archived_at_exports = /* @__PURE__ */ __exportAll({
 *   - `idx_execution_jobs_routing_key_created  (routing_key, created_at)`
 *   - `idx_execution_steps_routing_key_created (routing_key, created_at)`
 */
-async function up$26(db) {
+async function up$28(db) {
 	await sql`
     ALTER TABLE public.execution_runs
       ADD COLUMN archived_at         TIMESTAMPTZ NULL,
@@ -2517,7 +2547,7 @@ async function up$26(db) {
       ON public.execution_steps (routing_key, created_at)
   `.execute(db);
 }
-async function down$26(db) {
+async function down$28(db) {
 	await sql`DROP INDEX IF EXISTS public.idx_execution_steps_routing_key_created`.execute(db);
 	await sql`
     ALTER TABLE public.execution_steps
@@ -2542,8 +2572,8 @@ async function down$26(db) {
 //#endregion
 //#region src/db/migrations/007_audit_logs_archived_at.ts
 var _007_audit_logs_archived_at_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$25,
-	up: () => up$25
+	down: () => down$27,
+	up: () => up$27
 });
 /**
 * `secret_audit_log` and `access_log` cold-store schema additions, plus
@@ -2583,7 +2613,7 @@ var _007_audit_logs_archived_at_exports = /* @__PURE__ */ __exportAll({
 * `down()` would not have meaningful retention bounds. Acceptable for
 * staging.
 */
-async function up$25(db) {
+async function up$27(db) {
 	await sql`
     ALTER TABLE public.secret_audit_log
       ADD COLUMN archived_at         TIMESTAMPTZ NULL,
@@ -2604,7 +2634,7 @@ async function up$25(db) {
       DROP COLUMN IF EXISTS expires_at
   `.execute(db);
 }
-async function down$25(db) {
+async function down$27(db) {
 	await sql`
     ALTER TABLE public.access_log
       ADD COLUMN expires_at TIMESTAMPTZ NOT NULL DEFAULT (now() + INTERVAL '90 days')
@@ -2632,8 +2662,8 @@ async function down$25(db) {
 //#endregion
 //#region src/db/migrations/008_event_log_archived_at.ts
 var _008_event_log_archived_at_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$24,
-	up: () => up$24
+	down: () => down$26,
+	up: () => up$26
 });
 /**
 * `event_log` cold-store schema additions plus removal of the
@@ -2671,7 +2701,7 @@ var _008_event_log_archived_at_exports = /* @__PURE__ */ __exportAll({
 * — best effort; rows inserted between `up()` and a hypothetical
 * `down()` would not have meaningful retention bounds.
 */
-async function up$24(db) {
+async function up$26(db) {
 	await sql`
     ALTER TABLE public.event_log
       ADD COLUMN archived_at         TIMESTAMPTZ NULL,
@@ -2687,7 +2717,7 @@ async function up$24(db) {
       DROP COLUMN IF EXISTS expires_at
   `.execute(db);
 }
-async function down$24(db) {
+async function down$26(db) {
 	await sql`
     ALTER TABLE public.event_log
       ADD COLUMN expires_at TIMESTAMPTZ NOT NULL DEFAULT (now() + INTERVAL '30 days')
@@ -2706,8 +2736,8 @@ async function down$24(db) {
 //#endregion
 //#region src/db/migrations/009_access_log_trigram.ts
 var _009_access_log_trigram_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$23,
-	up: () => up$23
+	down: () => down$25,
+	up: () => up$25
 });
 /**
 * Trigram (pg_trgm) index on access_log.error_message for the federated
@@ -2720,7 +2750,7 @@ var _009_access_log_trigram_exports = /* @__PURE__ */ __exportAll({
 * EXISTS` are both safe to re-run. No CONCURRENTLY because Kysely runs
 * migrations inside a transaction; the lock is brief on a sampled table.
 */
-async function up$23(db) {
+async function up$25(db) {
 	await sql`CREATE EXTENSION IF NOT EXISTS pg_trgm`.execute(db);
 	await sql`
     CREATE INDEX IF NOT EXISTS access_log_error_message_trgm_idx
@@ -2729,14 +2759,14 @@ async function up$23(db) {
       WHERE error_message IS NOT NULL
   `.execute(db);
 }
-async function down$23(db) {
+async function down$25(db) {
 	await sql`DROP INDEX IF EXISTS public.access_log_error_message_trgm_idx`.execute(db);
 }
 //#endregion
 //#region src/db/migrations/010_cold_store_chunks.ts
 var _010_cold_store_chunks_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$22,
-	up: () => up$22
+	down: () => down$24,
+	up: () => up$24
 });
 /**
 * Cold-store chunk index — Phase 2 (cold-store purge).
@@ -2768,7 +2798,7 @@ var _010_cold_store_chunks_exports = /* @__PURE__ */ __exportAll({
 * forever. Adapters that don't opt into per-bucket archival via
 * `coldTtlDays` don't insert here either.
 */
-async function up$22(db) {
+async function up$24(db) {
 	await sql`
     CREATE TABLE public.cold_store_chunks (
       db              TEXT        NOT NULL,
@@ -2795,14 +2825,14 @@ async function up$22(db) {
       ON public.cold_store_chunks (db, table_name, tenant_id, archived_at DESC)
   `.execute(db);
 }
-async function down$22(db) {
+async function down$24(db) {
 	await sql`DROP TABLE IF EXISTS public.cold_store_chunks`.execute(db);
 }
 //#endregion
 //#region src/db/migrations/011_drop_source_secrets_notify.ts
 var _011_drop_source_secrets_notify_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$21,
-	up: () => up$21
+	down: () => down$23,
+	up: () => up$23
 });
 /**
 * Drop the `source_secrets_change_trigger` and the
@@ -2821,11 +2851,11 @@ var _011_drop_source_secrets_notify_exports = /* @__PURE__ */ __exportAll({
 * in `001_initial.ts`. They wake up no consumer until the `WebhookSecretManager`
 * is restored, so this migration is safe to roll back.
 */
-async function up$21(db) {
+async function up$23(db) {
 	await sql`DROP TRIGGER IF EXISTS source_secrets_change_trigger ON public.scoped_secrets`.execute(db);
 	await sql`DROP FUNCTION IF EXISTS public.notify_source_secrets_change() CASCADE`.execute(db);
 }
-async function down$21(db) {
+async function down$23(db) {
 	await sql`
     CREATE OR REPLACE FUNCTION public.notify_source_secrets_change() RETURNS trigger
       LANGUAGE plpgsql
@@ -2864,8 +2894,8 @@ async function down$21(db) {
 //#endregion
 //#region src/db/migrations/012_peer_credentials_active_uniq.ts
 var _012_peer_credentials_active_uniq_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$20,
-	up: () => up$20
+	down: () => down$22,
+	up: () => up$22
 });
 /**
 * Add a partial unique index on `peer_credentials (instance_id) WHERE
@@ -2891,7 +2921,7 @@ var _012_peer_credentials_active_uniq_exports = /* @__PURE__ */ __exportAll({
 * `down()` only drops the index; it does NOT undo the dedupe (there's no
 * safe way to recreate revoked rows, and the dedupe is monotonic).
 */
-async function up$20(db) {
+async function up$22(db) {
 	await sql`
     UPDATE public.peer_credentials
     SET revoked_at = NOW()
@@ -2909,14 +2939,14 @@ async function up$20(db) {
       WHERE revoked_at IS NULL
   `.execute(db);
 }
-async function down$20(db) {
+async function down$22(db) {
 	await sql`DROP INDEX IF EXISTS public.peer_credentials_active_uniq`.execute(db);
 }
 //#endregion
 //#region src/db/migrations/013_execution_log_bytes.ts
 var _013_execution_log_bytes_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$19,
-	up: () => up$19
+	down: () => down$21,
+	up: () => up$21
 });
 /**
 * Add `log_bytes BIGINT NOT NULL DEFAULT 0` columns to `execution_runs` and
@@ -2935,7 +2965,7 @@ var _013_execution_log_bytes_exports = /* @__PURE__ */ __exportAll({
 *
 * Idempotent (`ADD COLUMN IF NOT EXISTS`).
 */
-async function up$19(db) {
+async function up$21(db) {
 	await sql`
     ALTER TABLE public.execution_runs
       ADD COLUMN IF NOT EXISTS log_bytes BIGINT NOT NULL DEFAULT 0
@@ -2945,15 +2975,15 @@ async function up$19(db) {
       ADD COLUMN IF NOT EXISTS log_bytes BIGINT NOT NULL DEFAULT 0
   `.execute(db);
 }
-async function down$19(db) {
+async function down$21(db) {
 	await sql`ALTER TABLE public.execution_runs DROP COLUMN IF EXISTS log_bytes`.execute(db);
 	await sql`ALTER TABLE public.execution_jobs DROP COLUMN IF EXISTS log_bytes`.execute(db);
 }
 //#endregion
 //#region src/db/migrations/014_kici_events_lease_retry.ts
 var _014_kici_events_lease_retry_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$18,
-	up: () => up$18
+	down: () => down$20,
+	up: () => up$20
 });
 /**
 * Add lease + retry + DLQ columns to `kici_events` so the EventRouter can
@@ -2987,7 +3017,7 @@ var _014_kici_events_lease_retry_exports = /* @__PURE__ */ __exportAll({
 *
 * Idempotent (`ADD COLUMN IF NOT EXISTS` + `CREATE INDEX IF NOT EXISTS`).
 */
-async function up$18(db) {
+async function up$20(db) {
 	await sql`
     ALTER TABLE public.kici_events
       ADD COLUMN IF NOT EXISTS claimed_at TIMESTAMPTZ,
@@ -3018,7 +3048,7 @@ async function up$18(db) {
       WHERE dlq_at IS NOT NULL
   `.execute(db);
 }
-async function down$18(db) {
+async function down$20(db) {
 	await sql`DROP INDEX IF EXISTS public.idx_kici_events_dlq`.execute(db);
 	await sql`DROP INDEX IF EXISTS public.idx_kici_events_lease_expired`.execute(db);
 	await sql`DROP INDEX IF EXISTS public.idx_kici_events_retry_due`.execute(db);
@@ -3036,8 +3066,8 @@ async function down$18(db) {
 //#endregion
 //#region src/db/migrations/015_org_settings_customer_scoped.ts
 var _015_org_settings_customer_scoped_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$17,
-	up: () => up$17
+	down: () => down$19,
+	up: () => up$19
 });
 /**
 * Org-scope `org_settings` and qualify each glob entry by source.
@@ -3065,7 +3095,7 @@ var _015_org_settings_customer_scoped_exports = /* @__PURE__ */ __exportAll({
 * Idempotent: a re-run on an already-migrated DB sees `customer_id` exists
 * and the list columns are already jsonb, so it is a no-op.
 */
-async function up$17(db) {
+async function up$19(db) {
 	if ((await sql`
     SELECT EXISTS (
       SELECT 1 FROM information_schema.columns
@@ -3190,7 +3220,7 @@ async function up$17(db) {
 	await sql`DROP TABLE _org_settings_merged`.execute(db);
 	await sql`DROP TABLE _org_settings_stage`.execute(db);
 }
-async function down$17(db) {
+async function down$19(db) {
 	if (!(await sql`
     SELECT EXISTS (
       SELECT 1 FROM information_schema.columns
@@ -3215,8 +3245,8 @@ async function down$17(db) {
 //#endregion
 //#region src/db/migrations/016_org_settings_allow_http_npm.ts
 var _016_org_settings_allow_http_npm_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$16,
-	up: () => up$16
+	down: () => down$18,
+	up: () => up$18
 });
 /**
 * Add `org_settings.allow_http_npm_registries boolean NOT NULL DEFAULT false`.
@@ -3229,7 +3259,7 @@ var _016_org_settings_allow_http_npm_exports = /* @__PURE__ */ __exportAll({
 *
 * Idempotent: a re-run on a DB that already has the column is a no-op.
 */
-async function up$16(db) {
+async function up$18(db) {
 	if ((await sql`
     SELECT EXISTS (
       SELECT 1 FROM information_schema.columns
@@ -3243,7 +3273,7 @@ async function up$16(db) {
       ADD COLUMN allow_http_npm_registries boolean NOT NULL DEFAULT false
   `.execute(db);
 }
-async function down$16(db) {
+async function down$18(db) {
 	await sql`
     ALTER TABLE public.org_settings DROP COLUMN IF EXISTS allow_http_npm_registries
   `.execute(db);
@@ -3251,8 +3281,8 @@ async function down$16(db) {
 //#endregion
 //#region src/db/migrations/017_org_id_widen.ts
 var _017_org_id_widen_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$15,
-	up: () => up$15
+	down: () => down$17,
+	up: () => up$17
 });
 /**
 * Widen every orchestrator-side `org_id varchar(12)` column to
@@ -3292,17 +3322,17 @@ const ORG_ID_TABLES$1 = [
 	"held_runs",
 	"scoped_secrets"
 ];
-async function up$15(db) {
+async function up$17(db) {
 	for (const table of ORG_ID_TABLES$1) await sql.raw(`ALTER TABLE public.${table} ALTER COLUMN org_id TYPE varchar(16)`).execute(db);
 }
-async function down$15(db) {
+async function down$17(db) {
 	for (const table of ORG_ID_TABLES$1) await sql.raw(`ALTER TABLE public.${table} ALTER COLUMN org_id TYPE varchar(12)`).execute(db);
 }
 //#endregion
 //#region src/db/migrations/018_org_id_prefix_backfill.ts
 var _018_org_id_prefix_backfill_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$14,
-	up: () => up$14
+	down: () => down$16,
+	up: () => up$16
 });
 /**
 * Prefix every orchestrator-side tenant string with `org_` to align
@@ -3347,19 +3377,19 @@ const CUSTOMER_ID_TABLES = [
 	"workflow_registrations",
 	"org_settings"
 ];
-async function up$14(db) {
+async function up$16(db) {
 	for (const table of ORG_ID_TABLES) await sql.raw(`UPDATE public.${table} SET org_id = 'org_' || org_id WHERE org_id <> 'kici-admin' AND org_id NOT LIKE 'org\\_%' ESCAPE '\\'`).execute(db);
 	for (const table of CUSTOMER_ID_TABLES) await sql.raw(`UPDATE public.${table} SET customer_id = 'org_' || customer_id WHERE customer_id <> 'kici-admin' AND customer_id NOT LIKE 'org\\_%' ESCAPE '\\'`).execute(db);
 }
-async function down$14(db) {
+async function down$16(db) {
 	for (const table of CUSTOMER_ID_TABLES) await sql.raw(`UPDATE public.${table} SET customer_id = substring(customer_id from 5) WHERE customer_id LIKE 'org\\_%' ESCAPE '\\'`).execute(db);
 	for (const table of ORG_ID_TABLES) await sql.raw(`UPDATE public.${table} SET org_id = substring(org_id from 5) WHERE org_id LIKE 'org\\_%' ESCAPE '\\'`).execute(db);
 }
 //#endregion
 //#region src/db/migrations/019_generic_sources_change_notify.ts
 var _019_generic_sources_change_notify_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$13,
-	up: () => up$13
+	down: () => down$15,
+	up: () => up$15
 });
 /**
 * Add a Postgres trigger on `generic_webhook_sources` that emits
@@ -3382,7 +3412,7 @@ var _019_generic_sources_change_notify_exports = /* @__PURE__ */ __exportAll({
 * (`notify_sources_change()` + `sources_change_trigger`, defined in
 * `001_initial.ts`).
 */
-async function up$13(db) {
+async function up$15(db) {
 	await sql`
     CREATE FUNCTION public.notify_generic_sources_change() RETURNS trigger
       LANGUAGE plpgsql
@@ -3403,15 +3433,15 @@ async function up$13(db) {
       FOR EACH ROW EXECUTE FUNCTION public.notify_generic_sources_change()
   `.execute(db);
 }
-async function down$13(db) {
+async function down$15(db) {
 	await sql`DROP TRIGGER IF EXISTS generic_sources_change_trigger ON public.generic_webhook_sources`.execute(db);
 	await sql`DROP FUNCTION IF EXISTS public.notify_generic_sources_change()`.execute(db);
 }
 //#endregion
 //#region src/db/migrations/020_org_settings_dashboard_write_policy.ts
 var _020_org_settings_dashboard_write_policy_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$12,
-	up: () => up$12
+	down: () => down$14,
+	up: () => up$14
 });
 /**
 * Add `org_settings.dashboard_write_policy jsonb NOT NULL DEFAULT '{}'`.
@@ -3426,7 +3456,7 @@ var _020_org_settings_dashboard_write_policy_exports = /* @__PURE__ */ __exportA
 *
 * Idempotent: a re-run on a DB that already has the column is a no-op.
 */
-async function up$12(db) {
+async function up$14(db) {
 	if ((await sql`
     SELECT EXISTS (
       SELECT 1 FROM information_schema.columns
@@ -3440,7 +3470,7 @@ async function up$12(db) {
       ADD COLUMN dashboard_write_policy jsonb NOT NULL DEFAULT '{}'::jsonb
   `.execute(db);
 }
-async function down$12(db) {
+async function down$14(db) {
 	await sql`
     ALTER TABLE public.org_settings DROP COLUMN IF EXISTS dashboard_write_policy
   `.execute(db);
@@ -3448,8 +3478,8 @@ async function down$12(db) {
 //#endregion
 //#region src/db/migrations/021_check_run_tracking.ts
 var _021_check_run_tracking_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$11,
-	up: () => up$11
+	down: () => down$13,
+	up: () => up$13
 });
 /**
 * Add `check_run_tracking` table for HA-safe check-run state persistence.
@@ -3473,7 +3503,7 @@ var _021_check_run_tracking_exports = /* @__PURE__ */ __exportAll({
 *
 * Idempotent: a re-run on a DB that already has the table is a no-op.
 */
-async function up$11(db) {
+async function up$13(db) {
 	if ((await sql`
     SELECT EXISTS (
       SELECT 1 FROM information_schema.tables
@@ -3504,14 +3534,14 @@ async function up$11(db) {
       WHERE run_id IS NOT NULL
   `.execute(db);
 }
-async function down$11(db) {
+async function down$13(db) {
 	await sql`DROP TABLE IF EXISTS public.check_run_tracking`.execute(db);
 }
 //#endregion
 //#region src/db/migrations/022_scaler_manager_state.ts
 var _022_scaler_manager_state_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$10,
-	up: () => up$10
+	down: () => down$12,
+	up: () => up$12
 });
 /**
 * Add three tables persisting `ScalerManager` per-coord state:
@@ -3538,7 +3568,7 @@ var _022_scaler_manager_state_exports = /* @__PURE__ */ __exportAll({
 * Idempotent: a re-run on a DB that already has any of these tables
 * leaves the existing one alone.
 */
-async function up$10(db) {
+async function up$12(db) {
 	const tableExists = async (name) => {
 		return (await sql`
       SELECT EXISTS (
@@ -3588,7 +3618,7 @@ async function up$10(db) {
     `.execute(db);
 	}
 }
-async function down$10(db) {
+async function down$12(db) {
 	await sql`DROP TABLE IF EXISTS public.scaler_reservations`.execute(db);
 	await sql`DROP TABLE IF EXISTS public.scaler_agent_jobs`.execute(db);
 	await sql`DROP TABLE IF EXISTS public.scaler_spawning_agents`.execute(db);
@@ -3596,8 +3626,8 @@ async function down$10(db) {
 //#endregion
 //#region src/db/migrations/023_dispatch_queue_recovery_deadline.ts
 var _023_dispatch_queue_recovery_deadline_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$9,
-	up: () => up$9
+	down: () => down$11,
+	up: () => up$11
 });
 /**
 * Add `dispatch_queue.recovery_deadline TIMESTAMPTZ` and
@@ -3621,7 +3651,7 @@ var _023_dispatch_queue_recovery_deadline_exports = /* @__PURE__ */ __exportAll(
 * Idempotent: re-running on a DB that already has either column is a
 * no-op.
 */
-async function up$9(db) {
+async function up$11(db) {
 	const colExists = async (name) => {
 		return (await sql`
       SELECT EXISTS (
@@ -3646,7 +3676,7 @@ async function up$9(db) {
       WHERE recovery_deadline IS NOT NULL
   `.execute(db);
 }
-async function down$9(db) {
+async function down$11(db) {
 	await sql`DROP INDEX IF EXISTS public.idx_dispatch_queue_recovery_deadline`.execute(db);
 	await sql`
     ALTER TABLE public.dispatch_queue DROP COLUMN IF EXISTS recovery_agent_id
@@ -3658,8 +3688,8 @@ async function down$9(db) {
 //#endregion
 //#region src/db/migrations/024_dispatch_queue_provisioning_error.ts
 var _024_dispatch_queue_provisioning_error_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$8,
-	up: () => up$8
+	down: () => down$10,
+	up: () => up$10
 });
 /**
 * Add `dispatch_queue.last_provisioning_error TEXT` recording the most
@@ -3675,7 +3705,7 @@ var _024_dispatch_queue_provisioning_error_exports = /* @__PURE__ */ __exportAll
 *
 * Idempotent: re-running on a DB that already has the column is a no-op.
 */
-async function up$8(db) {
+async function up$10(db) {
 	const colExists = async (name) => {
 		return (await sql`
       SELECT EXISTS (
@@ -3691,7 +3721,7 @@ async function up$8(db) {
         ADD COLUMN last_provisioning_error TEXT
     `.execute(db);
 }
-async function down$8(db) {
+async function down$10(db) {
 	await sql`
     ALTER TABLE public.dispatch_queue DROP COLUMN IF EXISTS last_provisioning_error
   `.execute(db);
@@ -3699,8 +3729,8 @@ async function down$8(db) {
 //#endregion
 //#region src/db/migrations/025_init_failure.ts
 var _025_init_failure_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$7,
-	up: () => up$7
+	down: () => down$9,
+	up: () => up$9
 });
 /**
 * Add `init_failure jsonb` columns to `execution_runs` and `execution_jobs`.
@@ -3714,7 +3744,7 @@ var _025_init_failure_exports = /* @__PURE__ */ __exportAll({
 * Idempotent: re-running on a DB that already has either column is a no-op
 * for that column.
 */
-async function up$7(db) {
+async function up$9(db) {
 	const colExists = async (table, name) => {
 		return (await sql`
       SELECT EXISTS (
@@ -3734,7 +3764,7 @@ async function up$7(db) {
         ADD COLUMN init_failure JSONB DEFAULT NULL
     `.execute(db);
 }
-async function down$7(db) {
+async function down$9(db) {
 	await sql`
     ALTER TABLE public.execution_jobs DROP COLUMN IF EXISTS init_failure
   `.execute(db);
@@ -3745,8 +3775,8 @@ async function down$7(db) {
 //#endregion
 //#region src/db/migrations/026_event_log_lockfile_corrupt.ts
 var _026_event_log_lockfile_corrupt_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$6,
-	up: () => up$6
+	down: () => down$8,
+	up: () => up$8
 });
 /**
 * Extend the event_log.status CHECK constraint with 'lockfile_corrupt' so the
@@ -3755,7 +3785,7 @@ var _026_event_log_lockfile_corrupt_exports = /* @__PURE__ */ __exportAll({
 *
 * Idempotent: the DROP ... IF EXISTS / re-ADD pair re-runs cleanly.
 */
-async function up$6(db) {
+async function up$8(db) {
 	await sql`ALTER TABLE event_log DROP CONSTRAINT IF EXISTS event_log_status_check`.execute(db);
 	await sql`
     ALTER TABLE event_log ADD CONSTRAINT event_log_status_check
@@ -3765,7 +3795,7 @@ async function up$6(db) {
     ])))
   `.execute(db);
 }
-async function down$6(db) {
+async function down$8(db) {
 	await sql`ALTER TABLE event_log DROP CONSTRAINT IF EXISTS event_log_status_check`.execute(db);
 	await sql`
     ALTER TABLE event_log ADD CONSTRAINT event_log_status_check
@@ -3778,8 +3808,8 @@ async function down$6(db) {
 //#endregion
 //#region src/db/migrations/027_workflow_timeout.ts
 var _027_workflow_timeout_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$5,
-	up: () => up$5
+	down: () => down$7,
+	up: () => up$7
 });
 /**
 * Add `workflow_timeout_ms integer` to `execution_runs`.
@@ -3797,13 +3827,13 @@ var _027_workflow_timeout_exports = /* @__PURE__ */ __exportAll({
 *
 * Idempotent: re-running on a DB that already has the column is a no-op.
 */
-async function up$5(db) {
+async function up$7(db) {
 	await sql`
     ALTER TABLE public.execution_runs
       ADD COLUMN IF NOT EXISTS workflow_timeout_ms INTEGER DEFAULT NULL
   `.execute(db);
 }
-async function down$5(db) {
+async function down$7(db) {
 	await sql`
     ALTER TABLE public.execution_runs DROP COLUMN IF EXISTS workflow_timeout_ms
   `.execute(db);
@@ -3811,8 +3841,8 @@ async function down$5(db) {
 //#endregion
 //#region src/db/migrations/028_org_settings_user_cache.ts
 var _028_org_settings_user_cache_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$4,
-	up: () => up$4
+	down: () => down$6,
+	up: () => up$6
 });
 /**
 * Add `org_settings.user_cache_quota_bytes bigint` and
@@ -3841,7 +3871,7 @@ async function columnExists(db, column) {
     ) AS exists
   `.execute(db)).rows[0]?.exists ?? false;
 }
-async function up$4(db) {
+async function up$6(db) {
 	if (!await columnExists(db, "user_cache_quota_bytes")) await sql`
       ALTER TABLE public.org_settings
         ADD COLUMN user_cache_quota_bytes bigint
@@ -3851,7 +3881,7 @@ async function up$4(db) {
         ADD COLUMN user_cache_ttl_ms bigint
     `.execute(db);
 }
-async function down$4(db) {
+async function down$6(db) {
 	await sql`
     ALTER TABLE public.org_settings DROP COLUMN IF EXISTS user_cache_quota_bytes
   `.execute(db);
@@ -3862,8 +3892,8 @@ async function down$4(db) {
 //#endregion
 //#region src/db/migrations/029_dispatch_queue_attempts.ts
 var _029_dispatch_queue_attempts_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$3,
-	up: () => up$3
+	down: () => down$5,
+	up: () => up$5
 });
 /**
 * Add `dispatch_queue.dispatch_attempts INT NOT NULL DEFAULT 0`.
@@ -3877,7 +3907,7 @@ var _029_dispatch_queue_attempts_exports = /* @__PURE__ */ __exportAll({
 *
 * Idempotent: re-running on a DB that already has the column is a no-op.
 */
-async function up$3(db) {
+async function up$5(db) {
 	if (!((await sql`
     SELECT EXISTS (
       SELECT 1 FROM information_schema.columns
@@ -3890,7 +3920,7 @@ async function up$3(db) {
         ADD COLUMN dispatch_attempts INT NOT NULL DEFAULT 0
     `.execute(db);
 }
-async function down$3(db) {
+async function down$5(db) {
 	await sql`
     ALTER TABLE public.dispatch_queue DROP COLUMN IF EXISTS dispatch_attempts
   `.execute(db);
@@ -3898,8 +3928,8 @@ async function down$3(db) {
 //#endregion
 //#region src/db/migrations/030_held_runs_env_set_null.ts
 var _030_held_runs_env_set_null_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$2,
-	up: () => up$2
+	down: () => down$4,
+	up: () => up$4
 });
 /**
 * held_runs.environment_id becomes nullable with ON DELETE SET NULL so
@@ -3910,14 +3940,14 @@ var _030_held_runs_env_set_null_exports = /* @__PURE__ */ __exportAll({
 * Idempotent: dropping the NOT NULL and the constraint are both no-ops on a
 * re-run, and the constraint is re-created with the SET NULL action.
 */
-async function up$2(db) {
+async function up$4(db) {
 	await sql`ALTER TABLE public.held_runs ALTER COLUMN environment_id DROP NOT NULL`.execute(db);
 	await sql`ALTER TABLE public.held_runs DROP CONSTRAINT IF EXISTS held_runs_environment_id_fkey`.execute(db);
 	await sql`ALTER TABLE public.held_runs
     ADD CONSTRAINT held_runs_environment_id_fkey
     FOREIGN KEY (environment_id) REFERENCES public.environments(id) ON DELETE SET NULL`.execute(db);
 }
-async function down$2(db) {
+async function down$4(db) {
 	await sql`ALTER TABLE public.held_runs DROP CONSTRAINT IF EXISTS held_runs_environment_id_fkey`.execute(db);
 	await sql`ALTER TABLE public.held_runs
     ADD CONSTRAINT held_runs_environment_id_fkey
@@ -3927,8 +3957,8 @@ async function down$2(db) {
 //#endregion
 //#region src/db/migrations/031_dispatch_queue_ack_deadline.ts
 var _031_dispatch_queue_ack_deadline_exports = /* @__PURE__ */ __exportAll({
-	down: () => down$1,
-	up: () => up$1
+	down: () => down$3,
+	up: () => up$3
 });
 /**
 * Add `dispatch_queue.ack_deadline TIMESTAMPTZ` and
@@ -3945,7 +3975,7 @@ var _031_dispatch_queue_ack_deadline_exports = /* @__PURE__ */ __exportAll({
 *
 * Idempotent: re-running on a DB that already has either column is a no-op.
 */
-async function up$1(db) {
+async function up$3(db) {
 	const colExists = async (name) => {
 		return (await sql`
       SELECT EXISTS (
@@ -3970,7 +4000,7 @@ async function up$1(db) {
       WHERE ack_deadline IS NOT NULL
   `.execute(db);
 }
-async function down$1(db) {
+async function down$3(db) {
 	await sql`DROP INDEX IF EXISTS public.idx_dispatch_queue_ack_deadline`.execute(db);
 	await sql`ALTER TABLE public.dispatch_queue DROP COLUMN IF EXISTS ack_agent_id`.execute(db);
 	await sql`ALTER TABLE public.dispatch_queue DROP COLUMN IF EXISTS ack_deadline`.execute(db);
@@ -3978,8 +4008,8 @@ async function down$1(db) {
 //#endregion
 //#region src/db/migrations/032_org_settings_dispatch_ack_timeout.ts
 var _032_org_settings_dispatch_ack_timeout_exports = /* @__PURE__ */ __exportAll({
-	down: () => down,
-	up: () => up
+	down: () => down$2,
+	up: () => up$2
 });
 /**
 * Add `org_settings.dispatch_ack_timeout_ms BIGINT` (nullable).
@@ -3991,7 +4021,7 @@ var _032_org_settings_dispatch_ack_timeout_exports = /* @__PURE__ */ __exportAll
 *
 * Idempotent: a re-run on a DB that already has the column is a no-op.
 */
-async function up(db) {
+async function up$2(db) {
 	if ((await sql`
     SELECT EXISTS (
       SELECT 1 FROM information_schema.columns
@@ -4005,12 +4035,127 @@ async function up(db) {
       ADD COLUMN dispatch_ack_timeout_ms BIGINT
   `.execute(db);
 }
-async function down(db) {
+async function down$2(db) {
 	await sql`
     ALTER TABLE public.org_settings DROP COLUMN IF EXISTS dispatch_ack_timeout_ms
   `.execute(db);
 }
 //#endregion
+//#region src/db/migrations/033_org_settings_approval.ts
+var _033_org_settings_approval_exports = /* @__PURE__ */ __exportAll({
+	down: () => down$1,
+	up: () => up$1
+});
+/**
+* Add the two approval-policy columns to `org_settings`:
+*
+* - `approval_expiry_seconds INTEGER NOT NULL DEFAULT 86400` — how long a held
+*   approval element waits before it expires (and its run/job/step is
+*   rejected). One day by default. An SDK `requireApproval` `timeout` overrides
+*   this per element; otherwise this per-org value applies.
+* - `allow_self_approval BOOLEAN NOT NULL DEFAULT true` — whether the user who
+*   triggered a run may also approve its held elements. Operators turn it off
+*   to enforce four-eyes review.
+*
+* Both are cluster-configurable per org via `kici-admin org-settings approval`
+* and the orchestrator admin route. Idempotent: a re-run on a DB that already
+* has the columns is a no-op (each column is guarded independently).
+*/
+async function up$1(db) {
+	const colExists = async (column) => {
+		return (await sql`
+      SELECT EXISTS (
+        SELECT 1 FROM information_schema.columns
+         WHERE table_schema = 'public'
+           AND table_name = 'org_settings'
+           AND column_name = ${column}
+      ) AS exists
+    `.execute(db)).rows[0]?.exists ?? false;
+	};
+	if (!await colExists("approval_expiry_seconds")) await sql`
+      ALTER TABLE public.org_settings
+        ADD COLUMN approval_expiry_seconds INTEGER NOT NULL DEFAULT 86400
+    `.execute(db);
+	if (!await colExists("allow_self_approval")) await sql`
+      ALTER TABLE public.org_settings
+        ADD COLUMN allow_self_approval BOOLEAN NOT NULL DEFAULT true
+    `.execute(db);
+}
+async function down$1(db) {
+	await sql`
+    ALTER TABLE public.org_settings DROP COLUMN IF EXISTS approval_expiry_seconds
+  `.execute(db);
+	await sql`
+    ALTER TABLE public.org_settings DROP COLUMN IF EXISTS allow_self_approval
+  `.execute(db);
+}
+//#endregion
+//#region src/db/migrations/034_held_runs_generalize.ts
+var _034_held_runs_generalize_exports = /* @__PURE__ */ __exportAll({
+	down: () => down,
+	up: () => up
+});
+/**
+* Generalize `held_runs` from an environment-only hold into the unified
+* "held element" model that backs per-element approvals, and add the
+* `held_run_approvals` table that records each approver's decision.
+*
+* New `held_runs` columns (all idempotent, column-exists guarded):
+* - `hold_scope text NOT NULL DEFAULT 'job'` — 'workflow' | 'job' | 'step'
+*   (engine `HoldScope`). Existing rows held a single job, so they default to
+*   'job'.
+* - `step_index integer` — nullable; set only for step-scoped holds.
+* - `trigger_source text NOT NULL DEFAULT 'environment'` — 'environment' |
+*   'explicit' (engine `TriggerSource`). Existing holds came from environment
+*   protection, so they default to 'environment'.
+* - `approval_requirement jsonb` — the normalized `ApprovalRequirement`
+*   (clauses + expiresAt + reason) the hold must satisfy. Nullable for legacy
+*   rows that predate the approval model.
+*
+* New `held_run_approvals` table: one row per approver decision, FK to
+* `held_runs.id` (uuid) with ON DELETE CASCADE.
+*/
+async function up(db) {
+	const colExists = async (column) => {
+		return (await sql`
+      SELECT EXISTS (
+        SELECT 1 FROM information_schema.columns
+         WHERE table_schema = 'public'
+           AND table_name = 'held_runs'
+           AND column_name = ${column}
+      ) AS exists
+    `.execute(db)).rows[0]?.exists ?? false;
+	};
+	if (!await colExists("hold_scope")) await sql`ALTER TABLE public.held_runs ADD COLUMN hold_scope text NOT NULL DEFAULT 'job'`.execute(db);
+	if (!await colExists("step_index")) await sql`ALTER TABLE public.held_runs ADD COLUMN step_index integer`.execute(db);
+	if (!await colExists("trigger_source")) await sql`ALTER TABLE public.held_runs ADD COLUMN trigger_source text NOT NULL DEFAULT 'environment'`.execute(db);
+	if (!await colExists("approval_requirement")) await sql`ALTER TABLE public.held_runs ADD COLUMN approval_requirement jsonb`.execute(db);
+	await sql`
+    CREATE TABLE IF NOT EXISTS public.held_run_approvals (
+      id uuid DEFAULT gen_random_uuid() NOT NULL,
+      held_run_id uuid NOT NULL,
+      approver_user_id text NOT NULL,
+      decision text NOT NULL,
+      clauses_satisfied jsonb,
+      created_at timestamp with time zone DEFAULT now() NOT NULL,
+      CONSTRAINT held_run_approvals_pkey PRIMARY KEY (id),
+      CONSTRAINT held_run_approvals_held_run_id_fkey
+        FOREIGN KEY (held_run_id) REFERENCES public.held_runs(id) ON DELETE CASCADE
+    )
+  `.execute(db);
+	await sql`
+    CREATE INDEX IF NOT EXISTS held_run_approvals_held_run_id_idx
+      ON public.held_run_approvals USING btree (held_run_id)
+  `.execute(db);
+}
+async function down(db) {
+	await sql`DROP TABLE IF EXISTS public.held_run_approvals`.execute(db);
+	await sql`ALTER TABLE public.held_runs DROP COLUMN IF EXISTS approval_requirement`.execute(db);
+	await sql`ALTER TABLE public.held_runs DROP COLUMN IF EXISTS trigger_source`.execute(db);
+	await sql`ALTER TABLE public.held_runs DROP COLUMN IF EXISTS step_index`.execute(db);
+	await sql`ALTER TABLE public.held_runs DROP COLUMN IF EXISTS hold_scope`.execute(db);
+}
+//#endregion
 //#region src/db/migration-provider.ts
 function createMigrationProvider() {
 	return { async getMigrations() {
@@ -4046,7 +4191,9 @@ function createMigrationProvider() {
 			"029_dispatch_queue_attempts": _029_dispatch_queue_attempts_exports,
 			"030_held_runs_env_set_null": _030_held_runs_env_set_null_exports,
 			"031_dispatch_queue_ack_deadline": _031_dispatch_queue_ack_deadline_exports,
-			"032_org_settings_dispatch_ack_timeout": _032_org_settings_dispatch_ack_timeout_exports
+			"032_org_settings_dispatch_ack_timeout": _032_org_settings_dispatch_ack_timeout_exports,
+			"033_org_settings_approval": _033_org_settings_approval_exports,
+			"034_held_runs_generalize": _034_held_runs_generalize_exports
 		};
 	} };
 }
@@ -4058,7 +4205,7 @@ function createMigrationProvider() {
 * Uses pg_advisory_lock to ensure only one orchestrator instance runs
 * migrations at a time, preventing conflicts in multi-instance deployments.
 */
-const logger$5 = createLogger({ prefix: "migrate" });
+const logger$10 = createLogger({ prefix: "migrate" });
 const ADVISORY_LOCK_KEY = 543210001;
 /**
 * Run all pending migrations with an advisory lock for concurrency safety.
@@ -4070,21 +4217,21 @@ const ADVISORY_LOCK_KEY = 543210001;
 async function runMigrations(opts) {
 	const client = await opts.pool.connect();
 	try {
-		logger$5.info("Acquiring migration lock...");
+		logger$10.info("Acquiring migration lock...");
 		await client.query("SELECT pg_advisory_lock($1)", [ADVISORY_LOCK_KEY]);
-		logger$5.info("Migration lock acquired");
+		logger$10.info("Migration lock acquired");
 		const migrator = new Migrator({
 			db: opts.db,
 			provider: createMigrationProvider()
 		});
 		const start = Date.now();
 		const { results, error } = await migrator.migrateToLatest();
-		for (const result of results ?? []) if (result.status === "Success") logger$5.info(`${result.migrationName} ... OK (${Date.now() - start}ms)`);
-		else if (result.status === "Error") logger$5.error(`${result.migrationName} ... FAILED`);
+		for (const result of results ?? []) if (result.status === "Success") logger$10.info(`${result.migrationName} ... OK (${Date.now() - start}ms)`);
+		else if (result.status === "Error") logger$10.error(`${result.migrationName} ... FAILED`);
 		if (error) throw error;
 		const applied = (results ?? []).filter((r) => r.status === "Success");
-		if (applied.length === 0) logger$5.info("Database schema is up to date");
-		else logger$5.info(`Applied ${applied.length} migration(s)`);
+		if (applied.length === 0) logger$10.info("Database schema is up to date");
+		else logger$10.info(`Applied ${applied.length} migration(s)`);
 		const hash = await computeMigrationsHash(createMigrationProvider());
 		await storeMigrationContentHash(opts.pool, hash);
 		return results ?? [];
@@ -5989,142 +6136,6 @@ function registerDiagnoseCommand(program, getClient) {
 		}
 	});
 }
-promisify(execFile);
-//#endregion
-//#region src/diagnostics/bundle-writer.ts
-/**
-* Debug bundle writer.
-*
-* Creates a sanitized ZIP diagnostic bundle containing config (secrets redacted),
-* recent logs, system info, metrics, cluster state, and execution data.
-* This is the primary support tool -- operators run debug-bundle and share
-* the ZIP for troubleshooting.
-*/
-/** Maximum total log bytes to include in bundle (50MB). */
-const MAX_LOG_BYTES = 50 * 1024 * 1024;
-/**
-* Config field names that are safe to include unredacted.
-* Everything else gets replaced with "****".
-*/
-const SAFE_CONFIG_KEYS = new Set([
-	"mode",
-	"host",
-	"port",
-	"logLevel",
-	"region",
-	"environment",
-	"name",
-	"label",
-	"labels",
-	"enabled",
-	"disabled",
-	"timeout",
-	"interval",
-	"maxRetries",
-	"retries",
-	"workers",
-	"concurrency",
-	"maxConcurrency",
-	"batchSize",
-	"bufferSize",
-	"warmPool",
-	"cooldown",
-	"type",
-	"provider",
-	"scaler",
-	"driver",
-	"backend",
-	"protocol",
-	"scheme",
-	"path",
-	"basePath",
-	"metricsPath",
-	"healthPath",
-	"logFormat",
-	"logFile",
-	"logDir",
-	"dataDir",
-	"version",
-	"debug",
-	"verbose",
-	"quiet",
-	"tls",
-	"cors",
-	"rateLimiting",
-	"maxConnections",
-	"poolSize",
-	"minPool",
-	"maxPool",
-	"idleTimeout",
-	"connectTimeout",
-	"requestTimeout",
-	"shutdownTimeout",
-	"gracefulShutdown"
-]);
-/**
-* Redact config values using allowlist approach.
-* Only known-safe fields are preserved; everything else becomes "****".
-*/
-function redactConfig(obj, parentKey) {
-	if (obj === null || obj === void 0) return obj;
-	if (Array.isArray(obj)) return obj.map((item) => redactConfig(item, parentKey));
-	if (typeof obj === "object") {
-		const result = {};
-		for (const [key, value] of Object.entries(obj)) result[key] = redactConfig(value, key);
-		return result;
-	}
-	if (typeof obj === "string" && parentKey && !SAFE_CONFIG_KEYS.has(parentKey)) return "****";
-	if (typeof obj === "number" || typeof obj === "boolean") return obj;
-	if (typeof obj === "string" && parentKey && SAFE_CONFIG_KEYS.has(parentKey)) return obj;
-	if (typeof obj === "string") return "****";
-	return obj;
-}
-/**
-* Add log files from logDir to the archive, respecting MAX_LOG_BYTES cap
-* and the logWindow time filter. Matches any `*.log` file in the directory,
-* so the per-instance filename pattern produced by
-* `buildLogFilename()` is picked up without additional configuration.
-*
-* Exported for reuse by the `kici-admin debug-bundle` CLI command, which
-* runs outside the orchestrator process but still needs to include the
-* same log files in its locally-assembled bundle.
-*/
-async function addLogsToArchive(archive, logDir, logWindowHours) {
-	const cutoff = Date.now() - logWindowHours * 60 * 60 * 1e3;
-	const entries = fs$1.readdirSync(logDir).filter((f) => {
-		if (!f.endsWith(".log")) return false;
-		return fs$1.statSync(path$1.join(logDir, f)).mtimeMs >= cutoff;
-	});
-	entries.sort((a, b) => {
-		const aStat = fs$1.statSync(path$1.join(logDir, a));
-		return fs$1.statSync(path$1.join(logDir, b)).mtimeMs - aStat.mtimeMs;
-	});
-	let totalBytes = 0;
-	let totalLines = 0;
-	let errors = 0;
-	let warnings = 0;
-	for (const entry of entries) {
-		const filePath = path$1.join(logDir, entry);
-		const stat = fs$1.statSync(filePath);
-		if (totalBytes + stat.size > MAX_LOG_BYTES) break;
-		const content = fs$1.readFileSync(filePath, "utf-8");
-		archive.append(content, { name: `logs/${entry}` });
-		totalBytes += stat.size;
-		const lines = content.split("\n");
-		totalLines += lines.length;
-		for (const line of lines) {
-			if (/\berror\b/i.test(line)) errors++;
-			if (/\bwarn(ing)?\b/i.test(line)) warnings++;
-		}
-	}
-	const summary = {
-		totalLines,
-		errors,
-		warnings,
-		totalBytes
-	};
-	archive.append(JSON.stringify(summary, null, 2), { name: "logs/summary.json" });
-}
 //#endregion
 //#region src/cli/commands/debug-bundle.ts
 /**
@@ -6140,9 +6151,13 @@ async function addLogsToArchive(archive, logDir, logWindowHours) {
 * Register the debug-bundle command on the CLI program.
 */
 function registerDebugBundleCommand(program, getClient) {
-	program.command("debug-bundle").description("Generate a diagnostic debug bundle ZIP for troubleshooting").option("-o, --output <path>", "Output ZIP file path", `kici-debug-${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-").slice(0, 19)}.zip`).option("--log-dir <path>", "Directory with rotated *.log files to include (defaults to $KICI_LOG_DIR)").option("--log-window <hours>", "Hours of log history to include in the bundle", (value) => parseInt(value, 10), 4).action(async (opts) => {
+	program.command("debug-bundle").description("Generate a diagnostic debug bundle ZIP for troubleshooting").option("-o, --output <path>", "Output ZIP file path", `kici-debug-${(/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-").slice(0, 19)}.zip`).option("--log-dir <path>", "Directory with rotated *.log files to include (defaults to $KICI_LOG_DIR)").option("--log-window <hours>", "Hours of log history to include in the bundle", (value) => parseInt(value, 10), 4).option("--fleet", "Collect logs from every node in the cluster (server-side fan-out)").option("--list", "With --fleet: print the fleet topology and exit (no collection)").option("--json", "With --fleet --list: emit the topology as JSON").option("--pick [selectors]", "With --fleet: comma-separated selectors (id/host*/label:k=v); bare flag opens an interactive picker on a TTY").option("--fleet-timeout <seconds>", "Per-node deadline for --fleet", (value) => parseInt(value, 10), 60).action(async (opts) => {
 		try {
 			const client = getClient();
+			if (opts.fleet) {
+				await runFleetBundle(client, opts);
+				return;
+			}
 			const outputPath = path$1.resolve(opts.output);
 			console.log("Collecting diagnostic data...");
 			const [diagnoseResult, configResult, systemInfo, clusterHealth, metrics] = await Promise.allSettled([
@@ -6195,6 +6210,57 @@ async function safeRequest(fn) {
 		return null;
 	}
 }
+/**
+* Fleet mode: enumerate (`--list`), pick nodes (`--pick`), or collect the whole
+* cluster into one nested ZIP via the orchestrator's server-side fan-out.
+*/
+async function runFleetBundle(client, opts) {
+	if (opts.list) {
+		const topology = await client.getFleetTopology();
+		if (opts.json) console.log(JSON.stringify(topology, null, 2));
+		else printTopologyTable(topology);
+		return;
+	}
+	const selectors = await resolveFleetSelectors(client, opts);
+	const outputPath = path$1.resolve(opts.output);
+	console.log("Collecting fleet bundle (this fans out to every selected node)...");
+	await client.downloadFleetBundle({
+		selectors,
+		logWindowHours: opts.logWindow,
+		timeoutSeconds: opts.fleetTimeout
+	}, outputPath);
+	const stat = fs$1.statSync(outputPath);
+	console.log(`Fleet bundle written to ${outputPath} (${(stat.size / 1024).toFixed(1)} KB)`);
+}
+/**
+* Resolve the `--pick` selectors: a bare `--pick` on a TTY opens an interactive
+* checkbox over the enumerated topology; a value is split on commas; no flag
+* means "everything".
+*/
+async function resolveFleetSelectors(client, opts) {
+	if (opts.pick === void 0) return [];
+	if (typeof opts.pick === "string") return opts.pick.split(",").map((s) => s.trim()).filter(Boolean);
+	if (!process.stdout.isTTY) throw new Error("--pick with no value requires a TTY; pass comma-separated selectors instead");
+	const { checkbox } = await import("@inquirer/prompts");
+	return checkbox({
+		message: "Select nodes to collect",
+		choices: (await client.getFleetTopology()).nodes.map((n) => ({
+			name: `${n.kind === "orchestrator" ? `[${n.role ?? "orchestrator"}]` : "  agent"} ${n.id}${n.hostname ? ` @ ${n.hostname}` : ""}`,
+			value: n.id
+		}))
+	});
+}
+/** Print the fleet topology as an indented tree (orchestrators with their agents). */
+function printTopologyTable(topology) {
+	const orchestrators = topology.nodes.filter((n) => n.kind === "orchestrator");
+	console.log(`Fleet topology (${topology.nodes.length} node(s)):`);
+	for (const o of orchestrators) {
+		const root = o.parentId === null ? " (collector)" : "";
+		console.log(`  [${o.role ?? "orchestrator"}] ${o.id}${o.hostname ? ` @ ${o.hostname}` : ""}${root}`);
+		const agents = topology.nodes.filter((n) => n.kind === "agent" && n.parentId === o.id);
+		for (const a of agents) console.log(`      agent ${a.id}`);
+	}
+}
 //#endregion
 //#region src/diagnostics/bundle-reader.ts
 /**
@@ -7675,6 +7741,56 @@ var init_windows = __esmMin((() => {
 	};
 }));
 //#endregion
+//#region src/cli/service/image-digests.ts
+/**
+* Resolves the customer installer's image reference from the digest record
+* shipped with this package (installer-image-digests.json at the package root).
+*
+* Emits a manifest-list-digest-pinned ref so a `docker`/`podman pull` verifies
+* the image hash — a registry that serves substituted bits fails the pull. When
+* the record is missing (a dev tree that never ran a release) or lacks the
+* image, falls back to the moving `:latest` tag and warns.
+*
+* The record resolves relative to this module's directory and works for both
+* layouts: the source tree (`src/cli/service/` → the JSON is three dirs up at
+* the package root) and the single-file bundle (`dist/cli.js` → one dir up).
+*/
+/**
+* Climb from a starting directory looking for installer-image-digests.json.
+* Works for the source layout (src/cli/service → 3 up) and the single-file
+* bundle layout (dist → 1 up).
+*/
+function findRecordFile(startDir) {
+	let dir = startDir;
+	for (let i = 0; i < 6; i++) {
+		const candidate = path.join(dir, RECORD_FILENAME);
+		if (existsSync(candidate)) return candidate;
+		const parent = path.dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	return null;
+}
+/**
+* Resolve `quay.io/kici-dev/<name>:<version>@sha256:<digest>` for an installer
+* image. Falls back to `:latest` (with a warning) when no recorded digest exists.
+*/
+function resolveImageRef(name, opts = {}) {
+	const file = opts.filePath ?? findRecordFile(import.meta.dirname);
+	if (file && existsSync(file)) try {
+		const rec = JSON.parse(readFileSync(file, "utf8"));
+		const digest = rec.images?.[name];
+		if (digest && rec.version) return `${QUAY_PREFIX}/${name}:${rec.version}@${digest}`;
+	} catch {}
+	console.warn(`[kici] no recorded manifest-list digest for ${name}; pinning the mutable :latest tag. Reinstall from a released kici-admin to get a digest-pinned image.`);
+	return `${QUAY_PREFIX}/${name}:latest`;
+}
+var QUAY_PREFIX, RECORD_FILENAME;
+var init_image_digests = __esmMin((() => {
+	QUAY_PREFIX = "quay.io/kici-dev";
+	RECORD_FILENAME = "installer-image-digests.json";
+}));
+//#endregion
 //#region src/cli/service/compose.ts
 /**
 * Docker/Podman Compose service manager.
@@ -7691,7 +7807,7 @@ var compose_exports = /* @__PURE__ */ __exportAll({ ComposeServiceManager: () =>
 *
 * @throws When neither runtime is found.
 */
-function detectRuntime() {
+function detectRuntime$1() {
 	try {
 		execSync("podman compose version", { stdio: "pipe" });
 		return "podman";
@@ -7734,10 +7850,13 @@ function getRestartMode(config) {
 * The generated file includes the service definition with env_file,
 * restart policy, and volume mounts.
 *
-* The `image:` line points at `quay.io/kici-dev/<service-name>:latest`.
-* Source of truth for the publish targets: packages/ci/src/publish-images.ts.
-* See .claude/rules/container-publish-registry.md — Quay is the sole
-* registry for public KiCI images we publish.
+* The `image:` line is pinned by manifest-list digest via `resolveImageRef`
+* (`quay.io/kici-dev/<service-name>:<version>@sha256:<digest>`), falling back
+* to the mutable `:latest` tag only when no recorded digest ships with this
+* package. Source of truth for the publish targets:
+* packages/ci/src/publish-images.ts. See
+* .claude/rules/container-publish-registry.md — Quay is the sole registry for
+* public KiCI images we publish.
 */
 function generateComposeYaml(config) {
 	const restartMode = getRestartMode(config);
@@ -7747,7 +7866,7 @@ function generateComposeYaml(config) {
 		"",
 		"services:",
 		`  ${config.name}:`,
-		`    image: quay.io/kici-dev/${config.name}:latest`,
+		`    image: ${resolveImageRef(config.name)}`,
 		`    container_name: ${config.name}`,
 		`    restart: ${restartMode}`,
 		"    env_file:",
@@ -7764,11 +7883,12 @@ function generateComposeYaml(config) {
 }
 var ComposeServiceManager;
 var init_compose = __esmMin((() => {
+	init_image_digests();
 	ComposeServiceManager = class {
 		runtime = null;
 		/** Get the runtime binary (`podman` or `docker`), detecting it if not already done. */
 		getRuntime() {
-			if (!this.runtime) this.runtime = detectRuntime();
+			if (!this.runtime) this.runtime = detectRuntime$1();
 			return this.runtime;
 		}
 		/** Run a compose command for the given service config. */
@@ -9981,6 +10101,8 @@ function formatSettings(s, format) {
 	lines.push(`User-cache quota:      ${s.userCacheQuotaBytes === null ? "(cluster default)" : `${s.userCacheQuotaBytes} bytes`}`);
 	lines.push(`User-cache TTL:        ${s.userCacheTtlMs === null ? "(cluster default)" : `${s.userCacheTtlMs} ms`}`);
 	lines.push(`Dispatch ack timeout:  ${s.dispatchAckTimeoutMs === null ? "(cluster default)" : `${s.dispatchAckTimeoutMs} ms`}`);
+	lines.push(`Approval expiry:       ${s.approvalExpirySeconds} s`);
+	lines.push(`Allow self-approval:   ${s.allowSelfApproval}`);
 	if (s.createdAt) lines.push(`Created at:            ${s.createdAt}`);
 	if (s.updatedAt) lines.push(`Updated at:            ${s.updatedAt}`);
 	return lines.join("\n");
@@ -10057,6 +10179,64 @@ function registerOrgSettingsCommands(program, getClient) {
 	});
 	registerUserCacheCommands(orgSettings, getClient);
 	registerDispatchAckCommands(orgSettings, getClient);
+	registerApprovalCommands(orgSettings, getClient);
+}
+/**
+* `kici-admin org-settings approval <show|set-expiry|set-self-approval>`.
+*
+* The per-org held-approval policy: how long a held element waits before it
+* expires (`approval_expiry_seconds`, default 86400) and whether a run's
+* triggerer may approve its own held elements (`allow_self_approval`, default
+* true). Both have NOT NULL DB defaults, so there is no "reset to cluster
+* default" — set replaces the current value.
+*/
+function registerApprovalCommands(orgSettings, getClient) {
+	const ap = orgSettings.command("approval").description("Manage the per-org held-approval expiry + self-approval policy");
+	ap.command("show").description("Print the current per-org approval policy").option("--customer-id <id>", "Customer / org id (alias: --org)").option("--org <id>", "Alias for --customer-id").option("--format <format>", "Output format: json|table", "table").action(async (opts) => {
+		const customerId = resolveCustomerId(opts);
+		try {
+			const settings = await fetchSettings(getClient(), customerId);
+			console.log(formatSettings(settings, opts.format));
+		} catch (err) {
+			console.error(`Error: ${toErrorMessage(err)}`);
+			process.exit(1);
+		}
+	});
+	ap.command("set-expiry <seconds>").description("Set the per-org held-approval expiry (integer seconds, >= 1)").option("--customer-id <id>", "Customer / org id (alias: --org)").option("--org <id>", "Alias for --customer-id").option("--format <format>", "Output format: json|table", "table").action(async (value, opts) => {
+		const n = Number(value);
+		if (!Number.isInteger(n) || n < 1) {
+			console.error("Error: value must be an integer >= 1 (seconds)");
+			process.exit(1);
+		}
+		const customerId = resolveCustomerId(opts);
+		try {
+			const updated = await patchSettings(getClient(), {
+				customerId,
+				approvalExpirySeconds: n
+			});
+			console.log(formatSettings(updated, opts.format));
+		} catch (err) {
+			console.error(`Error: ${toErrorMessage(err)}`);
+			process.exit(1);
+		}
+	});
+	ap.command("set-self-approval <value>").description("Allow or forbid a run triggerer approving its own held elements (true|false)").option("--customer-id <id>", "Customer / org id (alias: --org)").option("--org <id>", "Alias for --customer-id").option("--format <format>", "Output format: json|table", "table").action(async (value, opts) => {
+		if (value !== "true" && value !== "false") {
+			console.error("Error: value must be \"true\" or \"false\"");
+			process.exit(1);
+		}
+		const customerId = resolveCustomerId(opts);
+		try {
+			const updated = await patchSettings(getClient(), {
+				customerId,
+				allowSelfApproval: value === "true"
+			});
+			console.log(formatSettings(updated, opts.format));
+		} catch (err) {
+			console.error(`Error: ${toErrorMessage(err)}`);
+			process.exit(1);
+		}
+	});
 }
 /**
 * `kici-admin org-settings dispatch-ack <show|set|reset>`.
@@ -12648,9 +12828,9 @@ async function build(deps) {
 				sizeOf: (v) => v.byteLength
 			}),
 			log: (level, msg, extra) => {
-				if (level === "info") logger$1.info(msg, extra);
-				else if (level === "warn") logger$1.warn(msg, extra);
-				else logger$1.error(msg, extra);
+				if (level === "info") logger$6.info(msg, extra);
+				else if (level === "warn") logger$6.warn(msg, extra);
+				else logger$6.error(msg, extra);
 			}
 		}),
 		kdb,
@@ -13092,11 +13272,11 @@ async function peekChunk(opts) {
 		await b.close();
 	}
 }
-var logger$1;
+var logger$6;
 var init_cold_store_impl = __esmMin((() => {
 	init_client();
 	init_orchestrator_cold_store();
-	logger$1 = createLogger({ prefix: "kici-admin-cold-store" });
+	logger$6 = createLogger({ prefix: "kici-admin-cold-store" });
 }));
 //#endregion
 //#region src/cli/commands/cold-store.ts
@@ -13272,91 +13452,3177 @@ function registerColdStoreCommands(program, _getClient) {
 	});
 }
 //#endregion
-//#region src/cluster/join-client.ts
+//#region src/scaler/nftables.ts
 /**
-* Join client for zero-knowledge cluster bootstrap.
+* Programmatic nftables rule management for agent network isolation.
 *
-* Provides the joiner-side logic for `kici-admin join`:
-* 1. Connect to Platform relay (WS) or direct peer (HTTP POST)
-* 2. Send join.request with the join token
-* 3. Receive join.response with encrypted config bundle
-* 4. Decrypt bundle using token-derived AES-256-GCM key
-* 5. Write decrypted config as local YAML file
+* Manages RFC1918 + cloud metadata blocking rules per-interface (Firecracker/container)
+* or per-UID (bare-metal). All operations use `nft` CLI via child_process.execFile.
 *
-* The token carries routing info (cleartext for Platform relay) and a secret
-* (used for HKDF key derivation). Only the joiner and the token creator
-* can derive the encryption key -- the Platform relay sees only ciphertext.
+* Table layout:
+*   table ip kici {
+*     chain forward { type filter hook forward priority 0; policy accept; }
+*     chain output  { type filter hook output priority 0; policy accept; }
+*   }
 */
-const logger = createLogger({ prefix: "join-client" });
+const execFile$1 = promisify(execFile);
+const logger$5 = createLogger({ prefix: "nftables" });
+/** Timeout for nft commands in milliseconds. */
+const NFT_TIMEOUT_MS = 1e4;
+/** RFC1918 private address ranges. */
+const RFC1918_RANGES = [
+	"10.0.0.0/8",
+	"172.16.0.0/12",
+	"192.168.0.0/16"
+];
+/** Cloud metadata service range (AWS/GCP/Azure link-local). */
+const METADATA_RANGE = "169.254.0.0/16";
 /**
-* Decrypt a base64-encoded encrypted config bundle using a derived encryption key.
+* Execute an nft command with timeout.
+* @returns stdout from the command
+* @throws Error on non-zero exit or timeout
 */
-function decryptAndParseBundle(encryptedB64, encryptionKey) {
-	return decryptBundle(Buffer.from(encryptedB64, "base64"), encryptionKey);
+async function nft(opts, ...args) {
+	const { stdout } = opts.requireSudo === true ? await execFile$1("sudo", [
+		"-n",
+		"nft",
+		...args
+	], { timeout: NFT_TIMEOUT_MS }) : await execFile$1("nft", args, { timeout: NFT_TIMEOUT_MS });
+	return stdout;
 }
 /**
-* Build a JoinLocalConfig from a decrypted ConfigBundle.
-* Maps bundle fields to the structure expected by loadLocalConfig().
+* Validate that nftables is available and the process has NET_ADMIN capability.
+* Attempts `nft list tables` -- if it fails:
+*   - ENOENT: nft binary not installed
+*   - EPERM: nft binary present but NET_ADMIN capability missing
+* Throws with a clear error message in both cases.
 */
-function buildLocalConfig(bundle) {
-	const config = { database: { url: bundle.databaseUrl } };
-	if (bundle.storage) config.storage = bundle.storage;
-	if (bundle.secretKey) config.secrets = { key: bundle.secretKey };
-	return config;
+async function validateNftablesAvailability(opts = {}) {
+	try {
+		await nft(opts, "list", "tables");
+	} catch (err) {
+		const message = toErrorMessage(err);
+		if (message.includes("ENOENT") || message.includes("not found")) throw new Error("nftables binary not found at /usr/sbin/nft. The orchestrator container image must include nftables (apk add nftables). Network isolation for agents cannot be established without nftables.");
+		if (message.includes("EPERM") || message.includes("Operation not permitted")) throw new Error("nftables operation denied -- missing NET_ADMIN capability. Start the orchestrator container with --cap-add=NET_ADMIN. Network isolation for agents requires this capability.");
+		throw new Error(`nftables validation failed: ${message}`);
+	}
 }
 /**
-* Write a local config object to a YAML file.
+* Ensure the `kici` nftables table and required chains exist.
+* Idempotent -- safe to call multiple times.
 */
-async function writeConfigFile(path, config) {
-	await writeFile(path, stringify(config), "utf-8");
+async function ensureKiciTable(opts = {}) {
+	try {
+		await nft(opts, "list", "table", "ip", "kici");
+		logger$5.debug("kici nftables table already exists");
+		return;
+	} catch {}
+	logger$5.info("Creating kici nftables table with forward and output chains");
+	await nft(opts, "-f", "/dev/stdin").catch(() => {});
+	await nft(opts, "add", "table", "ip", "kici");
+	try {
+		await nft(opts, "add", "chain", "ip", "kici", "forward", "{ type filter hook forward priority 0; policy accept; }");
+	} catch {
+		logger$5.debug("kici forward chain already exists");
+	}
+	try {
+		await nft(opts, "add", "chain", "ip", "kici", "output", "{ type filter hook output priority 0; policy accept; }");
+	} catch {
+		logger$5.debug("kici output chain already exists");
+	}
+	logger$5.info("kici nftables table and chains created");
 }
-var JoinClient = class {
-	constructor(options) {
-		this.options = options;
-		if (!options.platformUrl && !options.peerUrl) throw new Error("Either --platform or --peer must be specified");
-		if (options.platformUrl && options.peerUrl) throw new Error("--platform and --peer are mutually exclusive");
+/**
+* Build the per-identifier isolation rule operations.
+*
+* Placement matters because nftables is first-match-wins and the `kici`
+* forward chain is shared: it accumulates rules for every live agent plus
+* any host-level baseline (e.g. wildcard `iifname "kici-*"` RFC1918 drops
+* installed at host bootstrap). Accepts therefore go in via `insert`
+* (chain head) so they beat any pre-existing drop that also matches the
+* traffic; an appended accept after a wildcard drop is dead code. Drops go
+* in via `add` (tail) — they only need to beat the chain's accept policy.
+*
+* Effective per-identifier order: gateway + allowlist accepts (head),
+* RFC1918 / metadata / denyAll drops (tail).
+*/
+function buildIsolationRuleOps(matchClause, gatewayIp, networkPolicy) {
+	const ops = [];
+	ops.push({
+		verb: "insert",
+		tokens: [
+			...matchClause,
+			"ip",
+			"daddr",
+			gatewayIp,
+			"accept"
+		]
+	});
+	if (networkPolicy?.allowlist) for (const cidr of networkPolicy.allowlist) ops.push({
+		verb: "insert",
+		tokens: [
+			...matchClause,
+			"ip",
+			"daddr",
+			cidr,
+			"accept"
+		]
+	});
+	for (const range of RFC1918_RANGES) ops.push({
+		verb: "add",
+		tokens: [
+			...matchClause,
+			"ip",
+			"daddr",
+			range,
+			"drop"
+		]
+	});
+	ops.push({
+		verb: "add",
+		tokens: [
+			...matchClause,
+			"ip",
+			"daddr",
+			METADATA_RANGE,
+			"drop"
+		]
+	});
+	if (networkPolicy?.denyAll) ops.push({
+		verb: "add",
+		tokens: [...matchClause, "drop"]
+	});
+	return ops;
+}
+/**
+* Add network isolation rules for a specific network interface.
+* Used by Firecracker and container backends.
+*
+* Rule placement (see buildIsolationRuleOps):
+* 1. Accept gateway traffic (inserted at chain head)
+* 2. Accept allowlisted CIDRs (inserted at chain head)
+* 3. Drop RFC1918 ranges (10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16)
+* 4. Drop cloud metadata (169.254.0.0/16)
+* 5. Drop all remaining traffic (only if denyAll is true)
+*
+* @param identifier - Network interface name or source IP to match (e.g., "veth-abc123" or "172.30.0.5")
+* @param gatewayIp - Gateway IP that must remain accessible (e.g., "10.0.0.1")
+* @param networkPolicy - Optional policy with allowlist and denyAll settings
+* @param matchMode - How to match traffic: 'iifname' for interface name (default), 'saddr' for source IP
+*/
+async function addIsolationRules(identifier, gatewayIp, networkPolicy, matchMode = "iifname", opts = {}) {
+	const matchLabel = matchMode === "iifname" ? `interface ${identifier}` : `source IP ${identifier}`;
+	logger$5.info(`Adding isolation rules for ${matchLabel} (gateway: ${gatewayIp})`);
+	const matchClause = matchMode === "iifname" ? ["iifname", identifier] : [
+		"ip",
+		"saddr",
+		identifier
+	];
+	if (networkPolicy?.allowlist) for (const cidr of networkPolicy.allowlist) logger$5.debug(`Allowlisting ${cidr} for ${matchLabel}`);
+	if (networkPolicy?.denyAll) logger$5.info(`Blocking all outbound traffic for ${matchLabel} (denyAll)`);
+	for (const op of buildIsolationRuleOps(matchClause, gatewayIp, networkPolicy)) await nft(opts, op.verb, "rule", "ip", "kici", "forward", ...op.tokens);
+	logger$5.info(`Isolation rules applied for ${matchLabel}`);
+}
+/**
+* Remove all isolation rules matching a specific interface from the kici forward chain.
+* Called during agent cleanup/destruction.
+*
+* Lists all rules with handles, finds those matching the interface name, and deletes them.
+* Best-effort: logs errors but does not throw (cleanup should not block destruction).
+*
+* @param interfaceName - Network interface whose rules should be removed
+*/
+async function removeIsolationRules(interfaceName, opts = {}) {
+	logger$5.info(`Removing isolation rules for interface ${interfaceName}`);
+	try {
+		const handles = parseRuleHandles(await nft(opts, "-a", "list", "chain", "ip", "kici", "forward"), interfaceName);
+		if (handles.length === 0) {
+			logger$5.debug(`No rules found for interface ${interfaceName}`);
+			return;
+		}
+		for (const handle of handles.sort((a, b) => b - a)) try {
+			await nft(opts, "delete", "rule", "ip", "kici", "forward", "handle", String(handle));
+		} catch (err) {
+			logger$5.warn(`Failed to delete rule handle ${handle}: ${err}`);
+		}
+		logger$5.info(`Removed ${handles.length} rules for interface ${interfaceName}`);
+	} catch (err) {
+		logger$5.warn(`Failed to list/remove rules for ${interfaceName}: ${err}`);
 	}
-	/**
-	* Execute the join flow:
-	* 1. Send join.request with token to Platform relay or direct peer
-	* 2. Receive join.response with encrypted config bundle
-	* 3. Decrypt bundle using token-derived key
-	* 4. Write local config YAML
-	*/
-	async join() {
-		const request = {
-			type: "join.request",
-			token: this.options.token
-		};
-		logger.info("Sending join request...");
-		const response = this.options.platformUrl ? await this.joinViaPlatform(request) : await this.joinViaPeer(request);
-		if (!response.success) throw new Error(`Join rejected: ${response.error ?? "unknown error"}`);
-		if (!response.encryptedBundle) throw new Error("Join response missing encrypted bundle");
-		const parsed = parseToken(this.options.token);
-		const keys = deriveKeys(Buffer.from(parsed.secretHex, "hex"));
-		const bundle = decryptAndParseBundle(response.encryptedBundle, keys.encryptionKey);
-		logger.info("Join successful, writing config...", { clusterId: bundle.clusterId });
-		const localConfig = buildLocalConfig(bundle);
-		const configPath = this.options.configPath ?? "./kici-orchestrator.yaml";
-		await writeConfigFile(configPath, localConfig);
-		logger.info(`Config written to ${configPath}`);
-		logger.info("Start the orchestrator with: kici-admin orchestrator start");
+}
+/**
+* Parse nft rule listing output and extract handles for rules matching a given identifier.
+* Handles lines like: `  iifname "veth-abc" ip daddr 10.0.0.0/8 drop # handle 42`
+*
+* @param nftOutput - Raw output from `nft -a list chain ip kici <chain>`
+* @param identifier - String to search for in each rule line (interface name or UID)
+* @returns Array of numeric rule handles
+*/
+function parseRuleHandles(nftOutput, identifier) {
+	const handles = [];
+	const lines = nftOutput.split("\n");
+	const escaped = identifier.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+	const boundaryRe = new RegExp(`(^|[\\s"])${escaped}([\\s"]|$)`);
+	for (const line of lines) {
+		if (!line.includes("# handle")) continue;
+		if (!boundaryRe.test(line)) continue;
+		const match = line.match(/# handle (\d+)/);
+		if (match) handles.push(parseInt(match[1], 10));
 	}
-	/**
-	* Join via Platform relay: connect WS, authenticate, send join.request, receive join.response.
-	*/
-	async joinViaPlatform(request) {
-		const url = this.options.platformUrl;
-		const apiKey = this.options.apiKey;
-		if (!apiKey) throw new Error("--api-key is required for Platform relay mode");
-		const { default: WebSocket } = await import("ws");
-		return new Promise((resolve, reject) => {
-			const ws = new WebSocket(url, {
-				maxPayload: WS_MAX_PAYLOAD_BYTES,
-				perMessageDeflate: {
-					concurrencyLimit: 10,
-					threshold: 128
-				}
+	return handles;
+}
+//#endregion
+//#region src/firecracker/host-network.ts
+/**
+* Firecracker host-network provisioning.
+*
+* Creates the per-coordinator bridge (kici-brN), assigns its gateway IP,
+* marks kici-* interfaces unmanaged by NetworkManager, enables IP forwarding,
+* and builds a disjoint, source-scoped nftables table for NAT + egress
+* isolation. One pure command-builder drives live provisioning, the rendered
+* boot script, and (read-only) verification.
+*
+* This is HOST setup, distinct from the runtime per-VM isolation in
+* scaler/nftables.ts (added at spawn / removed at destroy). The two share the
+* nft table name but have separate lifecycles; this module never touches the
+* per-VM rules.
+*/
+const execFileP$1 = promisify(execFile);
+const logger$4 = createLogger({ prefix: "fc-host-network" });
+/** Privileged binaries that need `sudo -n` on a non-root orchestrator host. */
+const PRIVILEGED_BINS = new Set([
+	"ip",
+	"nft",
+	"sysctl"
+]);
+/** Timeout for a single host-network provisioning command. */
+const COMMAND_TIMEOUT_MS = 3e4;
+/**
+* Derive the network address (CIDR) from a gateway CIDR by masking host bits.
+* '10.0.0.1/24' -> '10.0.0.0/24'.
+*/
+function cidrToNetwork(cidr) {
+	const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})\/(\d{1,2})$/.exec(cidr);
+	if (!m) throw new Error(`Invalid CIDR "${cidr}" (expected a.b.c.d/prefix)`);
+	const octets = [
+		m[1],
+		m[2],
+		m[3],
+		m[4]
+	].map((o) => Number(o));
+	for (const o of octets) if (o > 255) throw new Error(`Invalid octet in CIDR "${cidr}" (each octet must be 0-255)`);
+	const prefix = Number(m[5]);
+	if (prefix > 32) throw new Error(`Invalid prefix /${prefix} in CIDR "${cidr}" (max /32)`);
+	const net = ((octets[0] << 24 | octets[1] << 16 | octets[2] << 8 | octets[3]) >>> 0 & (prefix === 0 ? 0 : 4294967295 << 32 - prefix >>> 0)) >>> 0;
+	return `${[
+		net >>> 24 & 255,
+		net >>> 16 & 255,
+		net >>> 8 & 255,
+		net & 255
+	].join(".")}/${prefix}`;
+}
+/** Bridge-name prefix used as the iifname match (matches the bridge + its TAP members). */
+function bridgePrefix(bridgeName) {
+	return `${bridgeName.split("-")[0]}-*`;
+}
+/**
+* Build the ordered command list that provisions one Firecracker host bridge.
+* Pure — performs no I/O. `provisionBridge` executes these; `renderBootScript`
+* serializes them.
+*
+* The nft `delete table`/`add table` here only ever touches `cfg.table`, so a
+* coord-B provision never wipes coord A's table (and vice versa). Every
+* forward/postrouting/MSS rule is source-scoped to the bridge subnet so two
+* tables on the shared hooks do not cross-drop each other's traffic.
+*/
+function buildBridgeCommands(cfg) {
+	const iface = cfg.hostIface;
+	if (!iface) throw new Error("buildBridgeCommands requires a resolved hostIface (call resolveHostIface first)");
+	const subnet = cidrToNetwork(cfg.bridgeCidr);
+	const gatewayIp = cfg.bridgeCidr.split("/")[0];
+	const prefix = bridgePrefix(cfg.bridgeName);
+	const t = cfg.table;
+	const nft = (...args) => ({
+		bin: "nft",
+		args
+	});
+	const saddr = [
+		"ip",
+		"saddr",
+		subnet
+	];
+	return [
+		{
+			bin: "ip",
+			args: [
+				"link",
+				"add",
+				"name",
+				cfg.bridgeName,
+				"type",
+				"bridge"
+			]
+		},
+		{
+			bin: "ip",
+			args: [
+				"addr",
+				"add",
+				cfg.bridgeCidr,
+				"dev",
+				cfg.bridgeName
+			]
+		},
+		{
+			bin: "ip",
+			args: [
+				"link",
+				"set",
+				cfg.bridgeName,
+				"up"
+			]
+		},
+		{
+			bin: "sysctl",
+			args: ["-w", "net.ipv4.ip_forward=1"]
+		},
+		nft("delete", "table", "ip", t),
+		nft("add", "table", "ip", t),
+		nft("add", "chain", t, "postrouting", "{ type nat hook postrouting priority srcnat; policy accept; }"),
+		nft("add", "rule", t, "postrouting", ...saddr, "oifname", iface, "masquerade"),
+		nft("add", "chain", t, "forward", "{ type filter hook forward priority filter; policy accept; }"),
+		nft("add", "rule", t, "forward", ...saddr, "iifname", prefix, "ip", "daddr", gatewayIp, "accept"),
+		...RFC1918_RANGES.map((r) => nft("add", "rule", t, "forward", ...saddr, "iifname", prefix, "ip", "daddr", r, "drop")),
+		nft("add", "rule", t, "forward", ...saddr, "iifname", prefix, "ip", "daddr", METADATA_RANGE, "drop"),
+		nft("add", "rule", t, "forward", ...saddr, "iifname", prefix, "oifname", iface, "accept"),
+		nft("add", "rule", t, "forward", "iifname", iface, "ip", "daddr", subnet, "oifname", prefix, "ct", "state", "related,established", "accept"),
+		nft("add", "rule", t, "forward", ...saddr, "tcp", "flags", "syn", "/", "syn,rst", "tcp", "option", "maxseg", "size", "set", "1460")
+	];
+}
+const NM_CONF_PATH = "/etc/NetworkManager/conf.d/90-kici-unmanaged.conf";
+const NM_CONF_CONTENT = [
+	"# Managed by kici-admin firecracker — do not hand-edit.",
+	"#",
+	"# KiCI's Firecracker scaler creates and destroys many kici-* interfaces",
+	"# (TAP devices + bridges). NetworkManager must not manage them: it auto-adopts",
+	"# them and can wedge the NM main thread at 100% CPU under churn.",
+	"[keyfile]",
+	"unmanaged-devices=interface-name:kici-*",
+	""
+].join("\n");
+const defaultFileWriter = (path, content) => writeFile(path, content, "utf8");
+function defaultRunner(requireSudo) {
+	return async ({ bin, args, stdin }) => {
+		const child = requireSudo && PRIVILEGED_BINS.has(bin) ? execFileP$1("sudo", [
+			"-n",
+			bin,
+			...args
+		], { timeout: COMMAND_TIMEOUT_MS }) : execFileP$1(bin, args, { timeout: COMMAND_TIMEOUT_MS });
+		if (stdin && child.child.stdin) child.child.stdin.end(stdin);
+		const { stdout } = await child;
+		return { stdout: stdout.toString() };
+	};
+}
+/** Resolve the default-route egress interface. */
+async function resolveHostIface(opts = {}) {
+	const { stdout } = await (opts.runner ?? defaultRunner(opts.requireSudo ?? false))({
+		bin: "ip",
+		args: [
+			"-j",
+			"route",
+			"show",
+			"default"
+		]
+	});
+	const dev = JSON.parse(stdout).find((r) => r.dev)?.dev;
+	if (!dev) throw new Error("could not detect the default-route interface for NAT egress");
+	return dev;
+}
+/** Provision (or heal) one Firecracker host bridge. Throws on any failure. */
+async function provisionBridge(cfg, opts = {}) {
+	const runner = opts.runner ?? defaultRunner(opts.requireSudo ?? false);
+	const iface = cfg.hostIface ?? await resolveHostIface(opts);
+	const resolved = {
+		...cfg,
+		hostIface: iface
+	};
+	const writeNmConf = opts.writeNmConf ?? defaultFileWriter;
+	try {
+		await writeNmConf(NM_CONF_PATH, NM_CONF_CONTENT);
+	} catch (err) {
+		if (!toErrorMessage(err).includes("ENOENT")) throw new Error(`failed to write ${NM_CONF_PATH}: ${toErrorMessage(err)}`);
+	}
+	for (const spec of buildBridgeCommands(resolved)) {
+		const line = [spec.bin, ...spec.args].join(" ");
+		try {
+			await runner(spec);
+		} catch (err) {
+			const msg = toErrorMessage(err);
+			const benignDelete = line.startsWith("nft delete table") && /No such file|does not exist/i.test(msg);
+			const benignExists = /File exists|already a member|already assigned|exists/i.test(msg) && (line.includes("link add") || line.includes("addr add"));
+			if (benignDelete || benignExists) {
+				logger$4.debug(`idempotent skip: ${line} (${msg})`);
+				continue;
+			}
+			throw new Error(`FC host-network command failed: ${line}: ${msg}`);
+		}
+	}
+	logger$4.info(`provisioned bridge ${cfg.bridgeName} (${cfg.bridgeCidr}, table ${cfg.table}, egress ${iface})`);
+}
+/** Read-only health probe for one bridge. Never throws on a missing resource. */
+async function verifyBridge(cfg, opts = {}) {
+	const runner = opts.runner ?? defaultRunner(opts.requireSudo ?? false);
+	const want = cfg.bridgeCidr.split("/")[0];
+	const wantPrefix = Number(cfg.bridgeCidr.split("/")[1]);
+	let bridgeExists = false;
+	let bridgeUp = false;
+	let addrPresent = false;
+	let tablePresent = false;
+	const misses = [];
+	try {
+		const { stdout } = await runner({
+			bin: "ip",
+			args: [
+				"-j",
+				"link",
+				"show",
+				cfg.bridgeName
+			]
+		});
+		const link = JSON.parse(stdout);
+		bridgeExists = link.length > 0;
+		const adminUp = (link[0]?.flags ?? []).includes("UP");
+		const operUp = link[0]?.operstate === "UP" || link[0]?.operstate === "UNKNOWN";
+		bridgeUp = adminUp || operUp;
+		if (!bridgeUp) misses.push(`${cfg.bridgeName} not up`);
+	} catch {
+		misses.push(`${cfg.bridgeName} does not exist`);
+	}
+	try {
+		const { stdout } = await runner({
+			bin: "ip",
+			args: [
+				"-j",
+				"addr",
+				"show",
+				cfg.bridgeName
+			]
+		});
+		addrPresent = (JSON.parse(stdout)[0]?.addr_info ?? []).some((a) => a.local === want && a.prefixlen === wantPrefix);
+		if (!addrPresent) misses.push(`${cfg.bridgeCidr} not assigned to ${cfg.bridgeName}`);
+	} catch {
+		misses.push(`could not read addrs on ${cfg.bridgeName}`);
+	}
+	try {
+		await runner({
+			bin: "nft",
+			args: [
+				"list",
+				"table",
+				"ip",
+				cfg.table
+			]
+		});
+		tablePresent = true;
+	} catch {
+		misses.push(`nft table ip ${cfg.table} missing`);
+	}
+	const healthy = bridgeExists && bridgeUp && addrPresent && tablePresent;
+	return {
+		bridgeName: cfg.bridgeName,
+		bridgeExists,
+		bridgeUp,
+		addrPresent,
+		tablePresent,
+		healthy,
+		detail: healthy ? "healthy" : misses.join("; ")
+	};
+}
+/** Remove the bridge + its nft table. Leaves the host-scoped NM conf in place. */
+async function teardownBridge(cfg, opts = {}) {
+	const runner = opts.runner ?? defaultRunner(opts.requireSudo ?? false);
+	for (const spec of [{
+		bin: "nft",
+		args: [
+			"delete",
+			"table",
+			"ip",
+			cfg.table
+		]
+	}, {
+		bin: "ip",
+		args: [
+			"link",
+			"del",
+			cfg.bridgeName
+		]
+	}]) try {
+		await runner(spec);
+	} catch (err) {
+		logger$4.debug(`teardown skip ${spec.bin}: ${toErrorMessage(err)}`);
+	}
+}
+const HOST_IFACE_SENTINEL = "__HOST_IFACE__";
+/** Serialize the provisioning command list into a dependency-free boot script. */
+function renderBootScript(cfg) {
+	const lines = buildBridgeCommands({
+		...cfg,
+		hostIface: HOST_IFACE_SENTINEL
+	}).map((s) => {
+		const benign = s.bin === "nft" && s.args[0] === "delete" && s.args[1] === "table";
+		const argv = [s.bin, ...s.args].map((tok) => tok === HOST_IFACE_SENTINEL ? "\"$HOST_IFACE\"" : shellQuote(tok)).join(" ");
+		return benign ? `${argv} 2>/dev/null || true` : argv;
+	});
+	return [
+		"#!/usr/bin/env bash",
+		`# Generated by kici-admin firecracker --persist for bridge ${cfg.bridgeName}. Do not hand-edit.`,
+		"set -euo pipefail",
+		`printf '%s\\n' "${NM_CONF_CONTENT.replace(/\n/g, "\\n").replace(/"/g, "\\\"")}" > ${NM_CONF_PATH} || true`,
+		"HOST_IFACE=$(ip -j route show default | sed -n 's/.*\"dev\":\"\\([^\"]*\\)\".*/\\1/p' | head -1)",
+		"if [ -z \"$HOST_IFACE\" ]; then echo \"no default-route iface\" >&2; exit 1; fi",
+		...lines,
+		""
+	].join("\n");
+}
+/**
+* Minimal POSIX-safe single-quote shell escaping for boot-script tokens.
+*
+* `*` is deliberately NOT in the bare-token allow-list: an `nft` arg like
+* `kici-*` (the iifname match) must reach nft literally, but an unquoted
+* `kici-*` would be glob-expanded by bash against the CWD. Tokens carrying any
+* shell metacharacter (incl. `*`, spaces, `{`/`;` from chain definitions) are
+* single-quoted so they pass through verbatim.
+*/
+function shellQuote(tok) {
+	if (/^[A-Za-z0-9_./:=,+-]+$/.test(tok)) return tok;
+	return `'${tok.replace(/'/g, `'\\''`)}'`;
+}
+//#endregion
+//#region src/firecracker/persist.ts
+/**
+* Boot-persistence for Firecracker host bridges: install a dependency-free
+* provisioning script + a per-bridge systemd oneshot unit so the bridge is
+* recreated on reboot (the kernel bridge/nft state is non-persistent).
+*/
+const execFileP = promisify(execFile);
+const logger$3 = createLogger({ prefix: "fc-persist" });
+const BOOT_SCRIPT_DIR = "/usr/local/lib/kici-firecracker";
+const SYSTEMD_DIR = "/etc/systemd/system";
+function persistUnitName(bridgeName) {
+	return `kici-fc-net-${bridgeName}.service`;
+}
+function renderPersistUnit(bridgeName) {
+	return [
+		"[Unit]",
+		`Description=KiCI Firecracker host bridge ${bridgeName}`,
+		"After=network-online.target",
+		"Wants=network-online.target",
+		"",
+		"[Service]",
+		"Type=oneshot",
+		"RemainAfterExit=yes",
+		`ExecStart=${BOOT_SCRIPT_DIR}/provision-${bridgeName}.sh`,
+		"",
+		"[Install]",
+		"WantedBy=multi-user.target",
+		""
+	].join("\n");
+}
+/**
+* Install the boot script + unit and `systemctl enable` it (enable only — the
+* deploy/CLI provisions the bridge live in the same run, so the unit fires on
+* the NEXT boot rather than re-churning nft now).
+*/
+async function installPersist(cfg, opts = {}) {
+	const sudo = opts.requireSudo ?? false;
+	const run = (bin, args) => sudo ? execFileP("sudo", [
+		"-n",
+		bin,
+		...args
+	], { timeout: 3e4 }) : execFileP(bin, args, { timeout: 3e4 });
+	const scriptPath = `${BOOT_SCRIPT_DIR}/provision-${cfg.bridgeName}.sh`;
+	const unitPath = `${SYSTEMD_DIR}/${persistUnitName(cfg.bridgeName)}`;
+	await mkdir(BOOT_SCRIPT_DIR, { recursive: true });
+	await writeFile(scriptPath, renderBootScript(cfg), "utf8");
+	await chmod(scriptPath, 493);
+	await writeFile(unitPath, renderPersistUnit(cfg.bridgeName), "utf8");
+	await run("systemctl", ["daemon-reload"]);
+	await run("systemctl", ["enable", persistUnitName(cfg.bridgeName)]);
+	logger$3.info(`installed + enabled ${persistUnitName(cfg.bridgeName)} (boot script ${scriptPath})`);
+}
+//#endregion
+//#region src/cli/commands/firecracker/provision.ts
+function optionsToConfig(opts) {
+	if (!opts.cidr) throw new Error("--cidr <gateway/prefix> is required");
+	return {
+		bridgeName: opts.bridge,
+		bridgeCidr: opts.cidr,
+		table: opts.table ?? "kici",
+		hostIface: opts.hostIface
+	};
+}
+function registerProvision(group) {
+	group.command("provision").description("Create/heal a Firecracker host bridge (NAT + egress isolation)").requiredOption("--bridge <name>", "bridge interface name (e.g. kici-br0)").requiredOption("--cidr <cidr>", "gateway IP + prefix (e.g. 10.0.0.1/24)").option("--table <name>", "nft table name", "kici").option("--host-iface <iface>", "NAT egress interface (auto-detected if omitted)").option("--persist", "install a systemd oneshot so the bridge survives reboot").option("--sudo", "wrap privileged commands with sudo -n (non-root host)").action(async (opts) => {
+		try {
+			const cfg = optionsToConfig(opts);
+			await provisionBridge(cfg, { requireSudo: opts.sudo });
+			if (opts.persist) await installPersist(cfg, { requireSudo: opts.sudo });
+			console.log(`Firecracker bridge ${cfg.bridgeName} provisioned${opts.persist ? " + persisted" : ""}.`);
+		} catch (err) {
+			console.error(`firecracker provision failed: ${toErrorMessage(err)}`);
+			process.exit(1);
+		}
+	});
+}
+//#endregion
+//#region src/cli/commands/firecracker/verify.ts
+function registerVerify(group) {
+	group.command("verify").description("Check a Firecracker host bridge is up with its addr + nft table").requiredOption("--bridge <name>", "bridge interface name").requiredOption("--cidr <cidr>", "gateway IP + prefix").option("--table <name>", "nft table name", "kici").option("--sudo", "wrap privileged commands with sudo -n").action(async (opts) => {
+		const cfg = optionsToConfig(opts);
+		const h = await verifyBridge(cfg, { requireSudo: opts.sudo });
+		if (h.healthy) {
+			console.log(`OK: ${cfg.bridgeName} healthy (${cfg.bridgeCidr}, table ${cfg.table})`);
+			return;
+		}
+		console.error(`UNHEALTHY: ${cfg.bridgeName}: ${h.detail}`);
+		process.exit(1);
+	});
+}
+//#endregion
+//#region src/cli/commands/firecracker/teardown.ts
+function registerTeardown(group) {
+	group.command("teardown").description("Remove a Firecracker host bridge + its nft table (leaves NM conf in place)").requiredOption("--bridge <name>", "bridge interface name").option("--cidr <cidr>", "gateway IP + prefix (unused but accepted for symmetry)", "0.0.0.0/0").option("--table <name>", "nft table name", "kici").option("--sudo", "wrap privileged commands with sudo -n").action(async (opts) => {
+		await teardownBridge(optionsToConfig(opts), { requireSudo: opts.sudo });
+		console.log(`Firecracker bridge ${opts.bridge} torn down.`);
+	});
+}
+//#endregion
+//#region src/cli/commands/firecracker/index.ts
+function registerFirecrackerCommands(program) {
+	const group = program.command("firecracker").description("Provision and verify Firecracker host networking");
+	registerProvision(group);
+	registerVerify(group);
+	registerTeardown(group);
+}
+//#endregion
+//#region src/config/loader.ts
+/**
+* YAML configuration file loader for the orchestrator.
+*
+* Reads the local YAML config file from a configurable path with fallback:
+* 1. Explicit configPath argument
+* 2. KICI_CONFIG environment variable
+* 3. /etc/kici/orchestrator.yaml default
+*
+* When no YAML file is found and no explicit path was given,
+* returns an empty config (YAML is optional -- env-only mode).
+*/
+init_schema();
+/** Default config file path when no explicit path or env var is set */
+const DEFAULT_CONFIG_PATH = "/etc/kici/orchestrator.yaml";
+/**
+* Load and validate the local orchestrator YAML configuration.
+*
+* @param configPath - Explicit path to the config file (highest precedence)
+* @returns Validated LocalConfig
+* @throws Error if explicit path doesn't exist, or if validation fails
+*/
+async function loadLocalConfig(configPath) {
+	const resolvedPath = configPath ?? process.env.KICI_CONFIG ?? DEFAULT_CONFIG_PATH;
+	const isExplicit = configPath !== void 0 || process.env.KICI_CONFIG !== void 0;
+	let rawYaml;
+	try {
+		rawYaml = await readFile(resolvedPath, "utf-8");
+	} catch (err) {
+		if (!isExplicit && isNodeError(err) && err.code === "ENOENT") return { database: { url: "" } };
+		throw new Error(`Failed to read config file at ${resolvedPath}: ${toErrorMessage(err)}`);
+	}
+	const parsed = parse(rawYaml);
+	if (!parsed || typeof parsed !== "object") {
+		if (isExplicit) throw new Error(`Config file at ${resolvedPath} is empty or not a valid YAML object`);
+		return { database: { url: "" } };
+	}
+	const result = localConfigSchema.safeParse(parsed);
+	if (!result.success) {
+		const errors = result.error.issues.map((e) => `  - ${e.path.join(".")}: ${e.message}`).join("\n");
+		throw new Error(`Config validation failed for ${resolvedPath}:\n${errors}`);
+	}
+	return result.data;
+}
+/**
+* Type guard for Node.js errors with a `code` property.
+*/
+function isNodeError(err) {
+	return err instanceof Error && "code" in err;
+}
+//#endregion
+//#region src/scaler/config.ts
+/**
+* YAML configuration loading and Zod validation for the scaler module.
+*
+* Handles:
+* - Main YAML config file parsing
+* - scalers.d/ directory merging (alphabetically sorted)
+* - Zod schema validation with type-specific refinements
+* - Memory string parsing (e.g., "2g" -> bytes)
+*/
+/**
+* Zod schema for a single resource spec (cpus + memory).
+*
+* The flat shape used to be the public scaler config form (`{ cpus, memory }`).
+* It's still accepted at the label-set / defaults level via `resourceRequestSchema`
+* below, where it's normalized to the nested `{ requests, limits }` form.
+*/
+const resourceSpecSchema = z.object({
+	memory: z.string().optional(),
+	cpus: z.number().positive().max(256).optional()
+}).strict();
+/**
+* Zod schema for nested-form `ResourceRequest` (`{ requests, limits }`).
+*/
+const nestedResourceRequestSchema = z.object({
+	requests: resourceSpecSchema.optional(),
+	limits: resourceSpecSchema.optional()
+}).strict();
+/**
+* Resource request schema accepted at the label-set / defaults level.
+*
+* Two input forms:
+* - Nested (preferred): `{ requests?: {cpus, memory}, limits?: {cpus, memory} }`.
+* - Flat shorthand: `{ cpus, memory }` -- treated as `limits`, `requests` mirrored from it.
+*
+* Always normalizes to the nested form so downstream code sees one shape.
+*/
+const resourceRequestSchema = z.union([nestedResourceRequestSchema, resourceSpecSchema]).transform((value) => {
+	if ("cpus" in value || "memory" in value) {
+		const flat = value;
+		if (flat.cpus === void 0 && flat.memory === void 0) return {};
+		return {
+			requests: { ...flat },
+			limits: { ...flat }
+		};
+	}
+	return value;
+});
+/**
+* Zod schema for an aggregate resource cap (per-scaler / per-orchestrator / per-machine).
+*
+* `maxMemory` is parsed at config-load to bytes, exposed downstream as
+* `maxMemoryBytes` so the scaler doesn't re-parse on every spawn check.
+*/
+const resourceCapSchema = z.object({
+	maxCpu: z.number().positive().optional(),
+	maxMemory: z.string().optional()
+}).strict().transform((value, ctx) => {
+	let maxMemoryBytes;
+	if (value.maxMemory !== void 0) try {
+		maxMemoryBytes = parseMemoryString(value.maxMemory);
+	} catch (err) {
+		ctx.addIssue({
+			code: z.ZodIssueCode.custom,
+			message: err instanceof Error ? err.message : String(err),
+			path: ["maxMemory"]
+		});
+		return z.NEVER;
+	}
+	return {
+		maxCpu: value.maxCpu,
+		maxMemoryBytes
+	};
+});
+/**
+* Zod schema for warm pool configuration.
+*/
+const warmPoolSchema = z.object({
+	enabled: z.boolean().default(false),
+	size: z.number().int().nonnegative().default(0),
+	idleTimeoutSeconds: z.number().default(300)
+}).optional();
+/**
+* Zod schema for network policy configuration on a label set.
+* Controls RFC1918 and internet access for spawned agents.
+*/
+const networkPolicySchema = z.object({
+	/** Allow traffic to these CIDR ranges (exceptions to default RFC1918 block) */
+	allowlist: z.array(z.string()).optional(),
+	/** Block all outbound traffic except allowlisted ranges */
+	denyAll: z.boolean().default(false)
+}).optional();
+/**
+* Zod schema for a label-set configuration entry.
+*/
+const labelSetConfigSchema = z.object({
+	labels: z.array(z.string()).min(1).refine((labels) => !labels.some((l) => l.toLowerCase().startsWith("kici:")), { message: "Labels with 'kici:' prefix are reserved and cannot be used in scaler labelSets" }),
+	image: z.string().optional(),
+	imagePullPolicy: z.enum([
+		"Always",
+		"IfNotPresent",
+		"Never"
+	]).default("Always"),
+	binaryPath: z.string().optional(),
+	/**
+	* Per-label-set resource request and limit. Accepts either the nested
+	* form `{ requests, limits }` or the legacy flat `{ cpus, memory }`
+	* (treated as `limits`, with `requests` mirrored). Always normalized to nested.
+	*/
+	resources: resourceRequestSchema.optional(),
+	volumes: z.array(z.string()).optional(),
+	containerSocket: z.boolean().default(false),
+	env: z.record(z.string(), z.string()).optional(),
+	backpressureMode: z.enum(["pause", "drop"]).optional(),
+	networkPolicy: networkPolicySchema,
+	rootfsPath: z.string().optional(),
+	kernelPath: z.string().optional(),
+	vcpuCount: z.number().int().positive().optional(),
+	memSizeMib: z.number().int().positive().optional(),
+	overlayDriveSizeMib: z.number().int().positive().optional()
+}).strict();
+/**
+* Zod schema for a single scaler entry.
+* Includes type-specific refinements:
+* - Docker scalers require 'image' on every label set
+* - Bare-metal scalers require 'binaryPath' on every label set
+*/
+const scalerEntrySchema = z.object({
+	name: z.string(),
+	type: ScalerBackendType.exclude(["kubernetes"]),
+	maxAgents: z.number().int().positive(),
+	labelSets: z.array(labelSetConfigSchema).min(1),
+	host: z.string().optional(),
+	socketPath: z.string().optional(),
+	runtime: z.enum([
+		"docker",
+		"podman",
+		"auto"
+	]).default("auto"),
+	orchestratorUrl: z.string().optional(),
+	extraHosts: z.array(z.string()).optional(),
+	networkIsolation: z.boolean().default(true),
+	warmPool: warmPoolSchema,
+	/**
+	* Labels a job MUST declare in `runsOn` to allocate on this scaler.
+	*
+	* Mirrors the Kubernetes "taints" concept: if a scaler has
+	* `mandatoryLabels: ['gpu']`, a job's `runsOn` must include `gpu` for
+	* the scaler to be considered. Generic jobs that don't list every
+	* mandatory label are blocked from this scaler entirely, even if
+	* their other labels are a subset of one of the scaler's labelSets.
+	*
+	* The `kici:` prefix is reserved for auto-injected system labels
+	* (kici:role:*, kici:os:*, kici:arch:*, kici:agent:*, kici:scaler:*)
+	* and cannot be used here — same as `labelSets[].labels`.
+	*
+	* Default: `[]` (no gating; behavior is unchanged from before this feature).
+	*/
+	mandatoryLabels: z.array(z.string()).default([]).refine((labels) => !labels.some((l) => l.toLowerCase().startsWith("kici:")), { message: "Labels with 'kici:' prefix are reserved and cannot be used in mandatoryLabels" }),
+	roles: z.array(z.enum([...KNOWN_ROLES, "all"])).optional().transform((roles) => {
+		if (!roles) return void 0;
+		if (roles.includes("all")) return void 0;
+		if (roles.length === 0) return [];
+		return roles.filter((r) => r !== "all");
+	}),
+	resourceCap: resourceCapSchema.optional(),
+	machinePool: z.string().optional(),
+	enforceCgroups: z.boolean().default(false),
+	firecrackerPath: z.string().optional(),
+	jailerPath: z.string().optional(),
+	kernelPath: z.string().optional(),
+	chrootBaseDir: z.string().default("/srv/jailer"),
+	uid: z.number().int().optional(),
+	gid: z.number().int().optional(),
+	vcpuCount: z.number().int().positive().default(2),
+	memSizeMib: z.number().int().positive().default(512),
+	/**
+	* When the orchestrator runs as a non-root user (e.g. user-mode systemd on
+	* an edge worker), set this to true so privileged commands (`ip`, `chown`)
+	* are wrapped with `sudo -n`. Operators must have a NOPASSWD sudoers entry
+	* for those binaries. On hosts where the orchestrator is already root,
+	* leave unset.
+	*/
+	requireSudo: z.boolean().default(false)
+}).strict().superRefine((data, ctx) => {
+	if (data.type === ScalerBackendType.enum.container) data.labelSets.forEach((ls, i) => {
+		if (!ls.image) ctx.addIssue({
+			code: z.ZodIssueCode.custom,
+			message: `Container scaler "${data.name}" label set [${i}] requires an 'image' field`,
+			path: [
+				"labelSets",
+				i,
+				"image"
+			]
+		});
+	});
+	if (data.type === ScalerBackendType.enum["bare-metal"]) data.labelSets.forEach((ls, i) => {
+		if (!ls.binaryPath) ctx.addIssue({
+			code: z.ZodIssueCode.custom,
+			message: `Bare-metal scaler "${data.name}" label set [${i}] requires a 'binaryPath' field`,
+			path: [
+				"labelSets",
+				i,
+				"binaryPath"
+			]
+		});
+	});
+	if (data.mandatoryLabels.length > 0) {
+		const mandatoryLower = data.mandatoryLabels.map((l) => l.toLowerCase());
+		data.labelSets.forEach((ls, i) => {
+			const labelsLower = new Set(ls.labels.map((l) => l.toLowerCase()));
+			for (const required of mandatoryLower) if (!labelsLower.has(required)) ctx.addIssue({
+				code: z.ZodIssueCode.custom,
+				message: `Scaler "${data.name}" mandatoryLabel "${required}" is missing from labelSets[${i}].labels — every mandatory label must appear in every labelSet, otherwise jobs can route through this labelSet and bypass the gate`,
+				path: [
+					"labelSets",
+					i,
+					"labels"
+				]
+			});
+		});
+	}
+	if (data.type === ScalerBackendType.enum.firecracker) {
+		if (!data.firecrackerPath) ctx.addIssue({
+			code: z.ZodIssueCode.custom,
+			message: `Firecracker scaler "${data.name}" requires a 'firecrackerPath' field`,
+			path: ["firecrackerPath"]
+		});
+		if (!data.jailerPath) ctx.addIssue({
+			code: z.ZodIssueCode.custom,
+			message: `Firecracker scaler "${data.name}" requires a 'jailerPath' field`,
+			path: ["jailerPath"]
+		});
+		if (!data.kernelPath) ctx.addIssue({
+			code: z.ZodIssueCode.custom,
+			message: `Firecracker scaler "${data.name}" requires a 'kernelPath' field`,
+			path: ["kernelPath"]
+		});
+		if (data.uid === void 0) ctx.addIssue({
+			code: z.ZodIssueCode.custom,
+			message: `Firecracker scaler "${data.name}" requires a 'uid' field`,
+			path: ["uid"]
+		});
+		if (data.gid === void 0) ctx.addIssue({
+			code: z.ZodIssueCode.custom,
+			message: `Firecracker scaler "${data.name}" requires a 'gid' field`,
+			path: ["gid"]
+		});
+		data.labelSets.forEach((ls, i) => {
+			if (!ls.rootfsPath) ctx.addIssue({
+				code: z.ZodIssueCode.custom,
+				message: `Firecracker scaler "${data.name}" label set [${i}] requires a 'rootfsPath' field`,
+				path: [
+					"labelSets",
+					i,
+					"rootfsPath"
+				]
+			});
+		});
+	}
+});
+/**
+* Zod schema for Firecracker network configuration.
+* Global across all Firecracker scalers on the orchestrator.
+*/
+const firecrackerNetworkSchema = z.object({
+	cidr: z.string().default("10.0.0.0/24"),
+	bridgeName: z.string().default("kici-br0"),
+	gateway: z.string().default("10.0.0.1"),
+	netmask: z.string().default("255.255.255.0"),
+	/** nft table name for this coordinator's host bridge (disjoint per bridge). */
+	table: z.string().default("kici")
+});
+/**
+* Zod schema for the complete scaler configuration file.
+* Validates version, global limits, defaults, and scaler entries.
+*/
+const scalerFileSchema = z.object({
+	version: z.literal(1),
+	globalMaxAgents: z.number().int().positive().default(50),
+	defaults: z.object({ resources: resourceRequestSchema.optional() }).optional(),
+	/** Cap on summed `requests` across every agent this orchestrator is running. */
+	globalResourceCap: resourceCapSchema.optional(),
+	/** Named pools for cross-orchestrator coordination on the same host. */
+	machinePools: z.array(z.object({
+		name: z.string().min(1),
+		cap: resourceCapSchema
+	}).strict()).optional(),
+	scalers: z.array(scalerEntrySchema),
+	firecracker: firecrackerNetworkSchema.optional()
+}).superRefine((data, ctx) => {
+	const poolNames = new Set((data.machinePools ?? []).map((p) => p.name));
+	data.scalers.forEach((entry, i) => {
+		if (entry.machinePool !== void 0 && !poolNames.has(entry.machinePool)) ctx.addIssue({
+			code: z.ZodIssueCode.custom,
+			message: `Scaler "${entry.name}" references unknown machinePool "${entry.machinePool}". Define it under top-level machinePools[].`,
+			path: [
+				"scalers",
+				i,
+				"machinePool"
+			]
+		});
+	});
+	const seen = /* @__PURE__ */ new Set();
+	(data.machinePools ?? []).forEach((p, i) => {
+		if (seen.has(p.name)) ctx.addIssue({
+			code: z.ZodIssueCode.custom,
+			message: `Duplicate machinePool name "${p.name}".`,
+			path: [
+				"machinePools",
+				i,
+				"name"
+			]
+		});
+		seen.add(p.name);
+	});
+});
+/**
+* Parse a memory string with unit suffix to bytes.
+*
+* Supported formats:
+* - "512m" or "512M" -> 536870912 (512 * 1024^2)
+* - "2g" or "2G" -> 2147483648 (2 * 1024^3)
+* - "1024k" or "1024K" -> 1048576 (1024 * 1024)
+*
+* @throws Error if the format is invalid
+*/
+function parseMemoryString(memory) {
+	const match = memory.match(/^(\d+(?:\.\d+)?)\s*([kmgKMG])$/);
+	if (!match) throw new Error(`Invalid memory format: "${memory}". Expected format like "512m", "2g", or "1024k".`);
+	const value = parseFloat(match[1]);
+	const unit = match[2].toLowerCase();
+	switch (unit) {
+		case "k": return Math.floor(value * 1024);
+		case "m": return Math.floor(value * 1024 * 1024);
+		case "g": return Math.floor(value * 1024 * 1024 * 1024);
+		default: throw new Error(`Unknown memory unit: "${unit}"`);
+	}
+}
+/**
+* Load and validate the scaler configuration from YAML files.
+*
+* 1. Reads the main config file
+* 2. If scalersDirPath provided, reads all *.yaml and *.yml files
+*    from the directory (sorted alphabetically) and merges their
+*    scalers arrays into the main config
+* 3. Validates the merged config through Zod schema
+*
+* @param configPath - Path to the main scaler YAML config file
+* @param scalersDirPath - Optional path to scalers.d/ directory for additional scaler definitions
+* @returns Validated ScalerConfig
+* @throws ZodError if validation fails
+*/
+async function loadScalerConfig(configPath, scalersDirPath) {
+	const mainConfig = parse(await readFile(configPath, "utf-8"));
+	if (scalersDirPath) {
+		const yamlFiles = (await readdir(scalersDirPath)).filter((f) => f.endsWith(".yaml") || f.endsWith(".yml")).sort();
+		for (const file of yamlFiles) {
+			const parsed = parse(await readFile(join(scalersDirPath, file), "utf-8"));
+			if (parsed?.scalers && Array.isArray(parsed.scalers)) mainConfig.scalers = [...mainConfig.scalers ?? [], ...parsed.scalers];
+		}
+	}
+	return scalerFileSchema.parse(mainConfig);
+}
+//#endregion
+//#region src/scaler/label-matcher.ts
+/**
+* Label-set matching and overlap detection for the scaler module.
+*
+* Label sets are normalized (sorted, deduplicated, lowercased) for
+* deterministic comparison.
+*
+* findBackendForLabels uses subset matching: a job requiring ['macos']
+* matches a scaler with ['macos', 'darwin', 'bare-metal']. This is
+* consistent with peer routing (findPeersWithCapacity) and allows
+* workflows to target broad labels like 'macos' without listing every
+* label the scaler defines.
+*/
+/**
+* Normalize a label set for comparison.
+* Sorts alphabetically, deduplicates, and lowercases all labels.
+* Produces a deterministic string key for comparison.
+*
+* @example
+* normalizeLabelSet(['Docker', 'linux', 'linux']) // => "docker,linux"
+* normalizeLabelSet([]) // => ""
+*/
+function normalizeLabelSet(labels) {
+	return [...new Set(labels.map((l) => l.toLowerCase()))].sort().join(",");
+}
+//#endregion
+//#region src/scaler/firecracker-api.ts
+/**
+* Firecracker REST API client over Unix domain sockets.
+*
+* Provides a thin wrapper around Node.js built-in `http` module for communicating
+* with Firecracker's REST API. Uses the `socketPath` option for HTTP-over-Unix-socket.
+*
+* Only used for post-boot operations:
+* - MMDS data injection (passing agent config to the guest VM)
+* - Graceful shutdown via SendCtrlAltDel (x86_64 only)
+* - Socket readiness polling after jailer invocation
+*
+* Pre-boot VM configuration uses `--config-file` JSON (atomic, simpler).
+*
+* @see https://github.com/firecracker-microvm/firecracker/blob/main/docs/getting-started.md
+* @see https://github.com/firecracker-microvm/firecracker/blob/main/docs/mmds/mmds-user-guide.md
+*/
+/**
+* Error thrown when the Firecracker API returns a non-2xx status code
+* or a network-level error occurs.
+*/
+var FirecrackerApiError = class extends Error {
+	/** HTTP status code from the Firecracker API (undefined for network errors) */
+	statusCode;
+	/** The API path that was requested */
+	path;
+	/** The response body from the Firecracker API */
+	responseBody;
+	constructor(message, path, statusCode, responseBody) {
+		super(message);
+		this.name = "FirecrackerApiError";
+		this.path = path;
+		this.statusCode = statusCode;
+		this.responseBody = responseBody ?? "";
+	}
+};
+/**
+* Thin REST client for the Firecracker API over Unix domain sockets.
+*
+* No external dependencies -- uses Node.js built-in `http` module with
+* the `socketPath` option for HTTP-over-Unix-socket communication.
+*/
+var FirecrackerApi = class {
+	constructor(socketPath) {
+		this.socketPath = socketPath;
+	}
+	/**
+	* Send an HTTP request to the Firecracker API.
+	*
+	* @param method - HTTP method (GET, PUT, PATCH)
+	* @param path - API path (e.g., '/mmds', '/actions', '/')
+	* @param body - Optional JSON body for PUT/PATCH requests
+	* @returns Response with statusCode and body
+	* @throws FirecrackerApiError on non-2xx status or network error
+	*/
+	request(method, path, body) {
+		return new Promise((resolve, reject) => {
+			const headers = {};
+			let data;
+			if (body !== void 0) {
+				data = JSON.stringify(body);
+				headers["Content-Type"] = "application/json";
+				headers["Content-Length"] = Buffer.byteLength(data);
+			}
+			const req = http.request({
+				socketPath: this.socketPath,
+				path,
+				method,
+				headers
+			}, (res) => {
+				let responseBody = "";
+				res.on("data", (chunk) => {
+					responseBody += chunk;
+				});
+				res.on("end", () => {
+					const statusCode = res.statusCode ?? 0;
+					if (statusCode >= 200 && statusCode < 300) resolve({
+						statusCode,
+						body: responseBody
+					});
+					else reject(new FirecrackerApiError(`Firecracker API ${method} ${path}: ${statusCode} ${responseBody}`, path, statusCode, responseBody));
+				});
+			});
+			req.on("error", (err) => {
+				reject(new FirecrackerApiError(`Firecracker API ${method} ${path}: ${err.message}`, path, void 0, ""));
+			});
+			if (data !== void 0) req.write(data);
+			req.end();
+		});
+	}
+	/**
+	* Inject MMDS (Micro VM Metadata Service) data into a running VM.
+	*
+	* Uses MMDS v2 data injection endpoint. The data should follow the structure:
+	* `{ latest: { 'meta-data': { ... } } }`
+	*
+	* The guest VM reads this data from http://169.254.169.254/latest/meta-data/
+	* using a token-based session (MMDS v2).
+	*
+	* @param data - Metadata object to inject
+	* @see https://github.com/firecracker-microvm/firecracker/blob/main/docs/mmds/mmds-user-guide.md
+	*/
+	async putMmds(data) {
+		await this.request("PUT", "/mmds", data);
+	}
+	/**
+	* Clear MMDS data after agent has received config via WS.
+	* Replaces the MMDS data with an empty meta-data object.
+	* Called after receiving config.ack from the agent.
+	*/
+	async clearMmds() {
+		await this.request("PUT", "/mmds", { latest: { "meta-data": {} } });
+	}
+	/**
+	* Send a SendCtrlAltDel action for graceful x86_64 shutdown.
+	*
+	* This simulates pressing Ctrl+Alt+Del on the virtual keyboard,
+	* which triggers a clean shutdown in most Linux distributions.
+	*
+	* Note: Only works on x86_64. On arm64, the i8042 keyboard controller
+	* is not available, so this action is not supported. Use process kill
+	* as fallback on arm64.
+	*
+	* @see https://github.com/firecracker-microvm/firecracker/blob/main/docs/getting-started.md
+	*/
+	async sendCtrlAltDel() {
+		await this.request("PUT", "/actions", { action_type: "SendCtrlAltDel" });
+	}
+	/**
+	* Get instance info from the Firecracker API root endpoint.
+	*
+	* Used to check if the API socket is reachable and the VM is running.
+	* Returns the parsed JSON response with instance information.
+	*/
+	async getInstanceInfo() {
+		const response = await this.request("GET", "/");
+		return JSON.parse(response.body);
+	}
+	/**
+	* Poll the Firecracker API socket until it becomes reachable or timeout expires.
+	*
+	* Used after jailer invocation to wait for Firecracker to create the API socket
+	* and become ready to accept requests.
+	*
+	* @param timeoutMs - Maximum time to wait in milliseconds (default: 5000)
+	* @param intervalMs - Polling interval in milliseconds (default: 100)
+	* @returns true if socket became reachable, false on timeout
+	*/
+	async waitForSocket(timeoutMs = 5e3, intervalMs = 100) {
+		const deadline = Date.now() + timeoutMs;
+		while (Date.now() < deadline) try {
+			await this.getInstanceInfo();
+			return true;
+		} catch {
+			await new Promise((resolve) => setTimeout(resolve, intervalMs));
+		}
+		return false;
+	}
+};
+//#endregion
+//#region src/scaler/file-tail.ts
+/**
+* File tailing utility for append-only log files.
+*
+* Provides an async generator that yields complete lines as they are appended
+* to a file, using `fs.watch()` for change notifications and partial line
+* buffering for split writes.
+*
+* Used by the Firecracker backend to tail serial console and VMM log files
+* from the jailer chroot directory.
+*/
+/**
+* Tail an append-only file, yielding complete lines as they are written.
+*
+* Pre-creates the file if it does not exist to avoid watch errors.
+* Tracks byte offset and partial (incomplete) trailing lines across reads.
+* Stops when the provided AbortSignal is triggered.
+*
+* @param filePath - Path to the file to tail
+* @param signal - AbortSignal to stop tailing
+* @yields Complete lines (non-empty) as they are appended to the file
+*/
+async function* tailFile(filePath, signal) {
+	await writeFile(filePath, "", { flag: "a" });
+	let offset = 0;
+	let partial = "";
+	/**
+	* Read new data from the file starting at the current offset.
+	* Returns complete lines and buffers any incomplete trailing line.
+	*/
+	function readNewData() {
+		return new Promise((resolve, reject) => {
+			let fileSize;
+			try {
+				fileSize = statSync(filePath).size;
+			} catch {
+				resolve([]);
+				return;
+			}
+			if (fileSize <= offset) {
+				resolve([]);
+				return;
+			}
+			const chunks = [];
+			const stream = createReadStream(filePath, {
+				start: offset,
+				encoding: "utf-8"
+			});
+			stream.on("data", (chunk) => {
+				chunks.push(typeof chunk === "string" ? chunk : chunk.toString("utf-8"));
+			});
+			stream.on("end", () => {
+				const parts = chunks.join("").split("\n");
+				const incompletePart = parts.pop();
+				if (parts.length > 0) {
+					parts[0] = partial + parts[0];
+					partial = incompletePart;
+				} else {
+					partial += incompletePart;
+					resolve([]);
+					try {
+						offset = statSync(filePath).size;
+					} catch {}
+					return;
+				}
+				const lines = parts.filter((l) => l.length > 0);
+				try {
+					offset = statSync(filePath).size;
+				} catch {}
+				resolve(lines);
+			});
+			stream.on("error", (err) => {
+				reject(err);
+			});
+		});
+	}
+	const lineQueue = [];
+	let resolveWaiter = null;
+	let stopped = false;
+	function onFileChange() {
+		if (stopped) return;
+		readNewData().then((lines) => {
+			if (lines.length > 0) {
+				lineQueue.push(...lines);
+				if (resolveWaiter) {
+					const r = resolveWaiter;
+					resolveWaiter = null;
+					r();
+				}
+			}
+		}, () => {});
+	}
+	watchFile(filePath, { interval: 100 }, onFileChange);
+	onFileChange();
+	const onAbort = () => {
+		stopped = true;
+		unwatchFile(filePath, onFileChange);
+		if (resolveWaiter) {
+			const r = resolveWaiter;
+			resolveWaiter = null;
+			r();
+		}
+	};
+	if (signal.aborted) {
+		stopped = true;
+		unwatchFile(filePath, onFileChange);
+	} else signal.addEventListener("abort", onAbort, { once: true });
+	try {
+		while (!stopped) if (lineQueue.length > 0) yield lineQueue.shift();
+		else await new Promise((resolve) => {
+			resolveWaiter = resolve;
+			if (stopped) {
+				resolveWaiter = null;
+				resolve();
+			}
+		});
+		if (partial.length > 0) {
+			yield partial;
+			partial = "";
+		}
+	} finally {
+		stopped = true;
+		unwatchFile(filePath, onFileChange);
+		signal.removeEventListener("abort", onAbort);
+	}
+}
+//#endregion
+//#region src/scaler/log-forwarder.ts
+/**
+* Enrich and forward a single log line to an output stream.
+*
+* Standalone function for use in the WS agent.log path (agent-handler).
+*
+* @param line - Raw log line from the agent
+* @param agentId - The agent that produced the line
+* @param output - Writable stream to write enriched JSON to
+* @param context - Optional trace context fields
+* @param logsSource - Optional log source identifier (e.g. 'docker', 'podman', 'bare-metal', 'firecracker-serial')
+*/
+function forwardLine(line, agentId, output, context, logsSource) {
+	let parsed;
+	try {
+		parsed = JSON.parse(line);
+		if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) parsed = {
+			level: "info",
+			message: line
+		};
+	} catch {
+		parsed = {
+			level: "info",
+			message: line
+		};
+	}
+	parsed.service = "agent";
+	parsed.agentId = agentId;
+	if (context?.runId) parsed.runId = context.runId;
+	if (context?.requestId) parsed.requestId = context.requestId;
+	if (context?.jobId) parsed.jobId = context.jobId;
+	if (logsSource) parsed.logsSource = logsSource;
+	output.write(JSON.stringify(parsed) + "\n");
+}
+//#endregion
+//#region src/scaler/firecracker-backend.ts
+/**
+* Firecracker scaler backend implementation.
+*
+* 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.
+*/
+/** Hardlink src to dest; fall back to copy if on different filesystems (EXDEV). */
+async function linkOrCopy(src, dest) {
+	try {
+		await link(src, dest);
+	} catch (err) {
+		if (err.code === "EXDEV") await copyFile(src, dest);
+		else throw err;
+	}
+}
+const execFileAsync = promisify(execFile);
+const logger$2 = createLogger({ prefix: "firecracker-backend" });
+/** Log file names within the jailer chroot directory */
+const SERIAL_LOG_FILE = "serial-console.log";
+const VMM_LOG_FILE = "vmm.log";
+/**
+* Maximum total bytes allowed for forwarded env vars in a single VM's MMDS payload.
+*
+* Firecracker's default MMDS data store cap is ~51 KiB shared across every metadata
+* field for that VM. The other static fields (URL, agent ID, labels, token, gateway,
+* backpressure) total well under 1 KiB, so 32 KiB is a generous-but-safe budget for
+* operator-defined env vars. Vars exceeding the remaining budget are skipped with a
+* warning rather than silently triggering an opaque MMDS PUT failure mid-spawn.
+*/
+const MMDS_FORWARDED_ENV_BUDGET_BYTES = 32 * 1024;
+/** POSIX shell-safe env var name pattern. Reject anything else to avoid MMDS path injection. */
+const POSIX_ENV_NAME_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+* Interface-name pattern for per-VM TAP devices.
+* Matches `kici-${vmId.slice(0, 8)}` — 8 lowercase hex chars.
+*/
+const VM_TAP_PATTERN = /^kici-[0-9a-f]{8}$/;
+/**
+* Infrastructure interfaces that share the `kici-` prefix but must NEVER be
+* deleted by the orphan sweep. Bridges (kici-br0/kici-br1) carry all VM
+* traffic; kici-m01 is the staging metadata interface. Losing any of these
+* kills all running VMs.
+*/
+const PROTECTED_INTERFACES = [
+	"kici-br0",
+	"kici-br1",
+	"kici-m01"
+];
+/** Convert a dotted IPv4 netmask ('255.255.255.0') to a CIDR prefix length (24). */
+function netmaskToPrefix(netmask) {
+	return netmask.split(".").map((o) => Number(o).toString(2).padStart(8, "0")).join("").split("1").length - 1;
+}
+var FirecrackerScalerBackend = class FirecrackerScalerBackend {
+	type = ScalerBackendType.enum.firecracker;
+	spawnsOnLocalHost = true;
+	maxAgents;
+	logsSource = "firecracker-serial";
+	/** AbortControllers for file tailing per managed VM (keyed by agent ID) */
+	tailAbortControllers = /* @__PURE__ */ new Map();
+	_labelSets;
+	name;
+	ipAllocator;
+	firecrackerPath;
+	jailerPath;
+	kernelPath;
+	chrootBaseDir;
+	uid;
+	gid;
+	vcpuCount;
+	memSizeMib;
+	bridgeName;
+	cidr;
+	gateway;
+	netmask;
+	table;
+	tokenStore;
+	tokenTtlMs;
+	roles;
+	requireSudo;
+	/** Tracks all managed VM agents by ManagedAgent.id */
+	agents = /* @__PURE__ */ new Map();
+	/** Periodic orphan sweep timer (null when stopped). */
+	orphanSweepTimer = null;
+	/** Guard against re-entrant sweeps if a single run takes longer than the interval. */
+	orphanSweepInFlight = false;
+	constructor(options) {
+		this.name = options.name;
+		this._labelSets = options.labelSets;
+		this.maxAgents = options.maxAgents;
+		this.ipAllocator = options.ipAllocator;
+		this.firecrackerPath = options.firecrackerPath;
+		this.jailerPath = options.jailerPath;
+		this.kernelPath = options.kernelPath;
+		this.chrootBaseDir = options.chrootBaseDir ?? "/srv/jailer";
+		this.uid = options.uid;
+		this.gid = options.gid;
+		this.vcpuCount = options.vcpuCount ?? 2;
+		this.memSizeMib = options.memSizeMib ?? 512;
+		this.bridgeName = options.bridgeName;
+		this.cidr = options.cidr;
+		this.gateway = options.gateway;
+		this.netmask = options.netmask;
+		this.table = options.table ?? "kici";
+		this.tokenStore = options.tokenStore;
+		this.tokenTtlMs = options.tokenTtlMs ?? 36e5;
+		this.roles = options.roles;
+		this.requireSudo = options.requireSudo ?? false;
+	}
+	/**
+	* Declare required tools for a firecracker scaler entry.
+	*/
+	static getRequiredTools(entry) {
+		const reqs = [];
+		const name = entry.name;
+		if (entry.firecrackerPath) reqs.push({
+			type: "file-access",
+			path: entry.firecrackerPath,
+			mode: "executable",
+			reason: `firecracker binary for scaler "${name}"`
+		});
+		if (entry.jailerPath) reqs.push({
+			type: "file-access",
+			path: entry.jailerPath,
+			mode: "executable",
+			reason: `jailer binary for scaler "${name}"`
+		});
+		if (entry.kernelPath) reqs.push({
+			type: "file-access",
+			path: entry.kernelPath,
+			mode: "readable",
+			reason: `kernel image for scaler "${name}"`
+		});
+		for (const ls of entry.labelSets) if (ls.rootfsPath) reqs.push({
+			type: "file-access",
+			path: ls.rootfsPath,
+			mode: "readable",
+			reason: `rootfs image for scaler "${name}" label set [${ls.labels.join(",")}]`
+		});
+		reqs.push({
+			type: "path-binary",
+			name: "ip",
+			reason: `required by firecracker scaler "${name}" for TAP device management`
+		});
+		reqs.push({
+			type: "path-binary",
+			name: "mkfs.ext4",
+			reason: `required by firecracker scaler "${name}" for overlay drive creation`
+		});
+		return reqs;
+	}
+	get labelSets() {
+		return this._labelSets;
+	}
+	getActiveCount() {
+		return this.agents.size;
+	}
+	async spawn(labelSet, agentId, orchestratorUrl, onEvent, effectiveLimits) {
+		const emit = (eventType, detail) => {
+			onEvent?.({
+				agentId,
+				eventType,
+				detail,
+				timestampMs: Date.now()
+			});
+		};
+		const normalizedTarget = normalizeLabelSet(labelSet);
+		const matchedLabelSet = this._labelSets.find((ls) => normalizeLabelSet(ls.labels) === normalizedTarget);
+		if (!matchedLabelSet) throw new Error(`Label set [${labelSet.join(", ")}] not supported by Firecracker backend "${this.name}"`);
+		if (this.getActiveCount() >= this.maxAgents) throw new Error(`Firecracker backend "${this.name}" at capacity (${this.maxAgents}/${this.maxAgents})`);
+		const managed = {
+			id: agentId,
+			labelSet,
+			backendRef: "",
+			spawnedAt: Date.now(),
+			state: "spawning",
+			ip: "",
+			tapDevice: ""
+		};
+		this.agents.set(managed.id, managed);
+		let alloc;
+		try {
+			emit(ScalerEventType.enum["scaler.provisioning"], "preparing rootfs and kernel");
+			alloc = await this.ipAllocator.allocate(agentId, this.name);
+			managed.ip = alloc.ip;
+			managed.tapDevice = alloc.tapDevice;
+			emit(ScalerEventType.enum["scaler.network"], `configuring TAP device ${alloc.tapDevice}`);
+			await this.execAsync("ip", [
+				"tuntap",
+				"add",
+				alloc.tapDevice,
+				"mode",
+				"tap"
+			]);
+			await this.execAsync("ip", [
+				"link",
+				"set",
+				alloc.tapDevice,
+				"master",
+				this.bridgeName
+			]);
+			await this.execAsync("ip", [
+				"link",
+				"set",
+				alloc.tapDevice,
+				"up"
+			]);
+			emit(ScalerEventType.enum["scaler.network"], `allocating IP ${alloc.ip}`);
+			const nftOpts = { requireSudo: this.requireSudo };
+			await ensureKiciTable(nftOpts);
+			await addIsolationRules(alloc.ip, this.gateway, matchedLabelSet.networkPolicy, "saddr", nftOpts);
+			const chrootDir = this.getChrootDir(agentId);
+			await mkdir(chrootDir, { recursive: true });
+			await linkOrCopy(matchedLabelSet.rootfsPath, join(chrootDir, "rootfs.ext4"));
+			await linkOrCopy(matchedLabelSet.kernelPath ?? this.kernelPath, join(chrootDir, "kernel"));
+			const overlayPath = join(chrootDir, "overlay.ext4");
+			const overlayMib = matchedLabelSet.overlayDriveSizeMib ?? 2048;
+			await this.createOverlayDrive(overlayPath, overlayMib);
+			const config = this.buildVmConfig(alloc, matchedLabelSet, effectiveLimits);
+			await writeFile(join(chrootDir, "config.json"), JSON.stringify(config, null, 2));
+			const serialLogPath = join(chrootDir, SERIAL_LOG_FILE);
+			const vmmLogPath = join(chrootDir, VMM_LOG_FILE);
+			writeFileSync(serialLogPath, "");
+			writeFileSync(vmmLogPath, "");
+			const stdoutFd = openSync(serialLogPath, "w");
+			const stderrFd = openSync(serialLogPath, "a");
+			const vmDir = join(this.chrootBaseDir, "firecracker", agentId);
+			await this.execAsync("chown", [
+				"-R",
+				`${this.uid}:${this.gid}`,
+				vmDir
+			]);
+			const orchUid = process.getuid?.();
+			const orchGid = process.getgid?.();
+			if (orchUid !== void 0 && orchUid !== 0) await this.execAsync("chown", [
+				`${orchUid}:${orchGid}`,
+				join(chrootDir, "rootfs.ext4"),
+				join(chrootDir, "kernel")
+			]);
+			emit(ScalerEventType.enum["scaler.provisioning"], "booting microVM");
+			const child = spawn(this.jailerPath, [
+				"--id",
+				agentId,
+				"--exec-file",
+				this.firecrackerPath,
+				"--uid",
+				String(this.uid),
+				"--gid",
+				String(this.gid),
+				"--chroot-base-dir",
+				this.chrootBaseDir,
+				"--new-pid-ns",
+				"--",
+				"--config-file",
+				"/config.json",
+				"--log-path",
+				"/vmm.log",
+				"--level",
+				"Warning"
+			], {
+				detached: true,
+				stdio: [
+					"ignore",
+					stdoutFd,
+					stderrFd
+				]
+			});
+			child.unref();
+			closeSync(stdoutFd);
+			closeSync(stderrFd);
+			this.startLogTailing(agentId, serialLogPath, vmmLogPath, child);
+			const api = new FirecrackerApi(this.getSocketPath(agentId));
+			let chmodLoosenInterval;
+			if (this.requireSudo) {
+				const chrootHostPath = join(join(this.chrootBaseDir, "firecracker", agentId), "root");
+				chmodLoosenInterval = setInterval(() => {
+					this.execAsync("chmod", [
+						"-R",
+						"go+rX",
+						chrootHostPath
+					]).catch(() => {});
+				}, 100);
+			}
+			let ready;
+			try {
+				ready = await api.waitForSocket(5e3);
+			} finally {
+				if (chmodLoosenInterval) clearInterval(chmodLoosenInterval);
+			}
+			if (!ready) throw new Error(`Firecracker API socket not ready within 5s for agent ${agentId}`);
+			const fullLabels = scalerAgentLabels(labelSet, this.type, this.name, this.roles);
+			let agentToken;
+			if (this.tokenStore) agentToken = await this.tokenStore.createEphemeral(agentId, fullLabels, this.tokenTtlMs);
+			const acceptedEnv = this.buildForwardedEnv(matchedLabelSet, agentId);
+			await api.putMmds({ latest: { "meta-data": {
+				"kici-orchestrator-url": orchestratorUrl,
+				"kici-agent-id": agentId,
+				"kici-labels": fullLabels.join(","),
+				"kici-scaler-managed": "1",
+				"kici-gateway-ip": this.gateway,
+				...agentToken ? { "kici-agent-token": agentToken } : {},
+				...matchedLabelSet.backpressureMode ? { "kici-backpressure-mode": matchedLabelSet.backpressureMode } : {},
+				...Object.keys(acceptedEnv).length > 0 ? { "kici-env": acceptedEnv } : {}
+			} } });
+			emit(ScalerEventType.enum["scaler.ready"], "microVM booted");
+			managed.state = "running";
+			managed.backendRef = agentId;
+			emit(ScalerEventType.enum["agent.connecting"], "waiting for agent WS registration from VM");
+			return managed;
+		} catch (err) {
+			emit(ScalerEventType.enum["scaler.failed"], err instanceof Error ? err.message : String(err));
+			await this.cleanupFailedSpawn(agentId, alloc);
+			this.agents.delete(managed.id);
+			throw err;
+		}
+	}
+	getScalerContext(agentId) {
+		const managed = this.agents.get(agentId);
+		if (!managed) return void 0;
+		const normalizedTarget = normalizeLabelSet(managed.labelSet);
+		const matchedLabelSet = this._labelSets.find((ls) => normalizeLabelSet(ls.labels) === normalizedTarget);
+		return {
+			backendType: "firecracker",
+			scalerName: this.name,
+			rootfsPath: matchedLabelSet?.rootfsPath,
+			kernelPath: matchedLabelSet?.kernelPath ?? this.kernelPath,
+			vcpuCount: matchedLabelSet?.vcpuCount ?? this.vcpuCount,
+			memSizeMib: matchedLabelSet?.memSizeMib ?? this.memSizeMib,
+			ip: managed.ip,
+			bridgeName: this.bridgeName,
+			gateway: this.gateway,
+			netmask: this.netmask
+		};
+	}
+	/**
+	* Bridge config for host-network diagnostics (read-only snapshot).
+	* `bridgeCidr` is the gateway IP with the network prefix (e.g. '10.0.0.1/24'),
+	* which is exactly what `provisionBridge`/`verifyBridge` consume. The prefix
+	* comes from the configured network `cidr`; if absent, it is derived from the
+	* dotted `netmask`.
+	*/
+	getBridgeConfig() {
+		const prefix = this.cidr ? this.cidr.split("/")[1] : netmaskToPrefix(this.netmask);
+		return {
+			bridgeName: this.bridgeName,
+			bridgeCidr: `${this.gateway}/${prefix}`,
+			table: this.table
+		};
+	}
+	async destroy(managedId) {
+		const managed = this.agents.get(managedId);
+		if (!managed) return;
+		managed.state = "destroying";
+		const abortController = this.tailAbortControllers.get(managedId);
+		if (abortController) {
+			abortController.abort();
+			this.tailAbortControllers.delete(managedId);
+		}
+		try {
+			await new FirecrackerApi(this.getSocketPath(managedId)).sendCtrlAltDel();
+			await this.waitForProcessExit(managedId, 5e3);
+		} catch {}
+		try {
+			const pidStr = await readFile(join(this.getChrootDir(managedId), "firecracker.pid"), "utf-8");
+			const pid = parseInt(pidStr.trim(), 10);
+			if (!isNaN(pid)) try {
+				process.kill(pid, "SIGKILL");
+			} catch {}
+		} catch {}
+		if (managed.ip) try {
+			await removeIsolationRules(managed.ip, { requireSudo: this.requireSudo });
+		} catch {}
+		if (managed.tapDevice) try {
+			await this.execAsync("ip", [
+				"link",
+				"del",
+				managed.tapDevice
+			]);
+		} catch {}
+		await this.ipAllocator.release(managedId);
+		try {
+			await this.removeChrootDir(managedId);
+		} catch {}
+		this.agents.delete(managedId);
+	}
+	async shutdownAll() {
+		this.stopPeriodicOrphanSweep();
+		const ids = [...this.agents.keys()];
+		await Promise.allSettled(ids.map((id) => this.destroy(id)));
+	}
+	/**
+	* 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.
+	*
+	* Note: Wiring from agent-handler is done in Plan 04.
+	*
+	* @param agentId - The agent ID whose VM MMDS should be cleared
+	*/
+	async clearAgentMmds(agentId) {
+		try {
+			await new FirecrackerApi(this.getSocketPath(agentId)).clearMmds();
+		} catch (err) {}
+	}
+	reload(labelSets) {
+		const errors = [];
+		labelSets.forEach((ls, i) => {
+			if (!ls.rootfsPath) errors.push(`Label set [${i}] requires a 'rootfsPath' field for Firecracker backend`);
+		});
+		if (errors.length > 0) return {
+			valid: false,
+			errors
+		};
+		this._labelSets = labelSets;
+		return { valid: true };
+	}
+	/**
+	* Clean up orphaned VMs.
+	*
+	* 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).
+	*
+	* Three 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.
+	*/
+	async cleanupOrphans() {
+		let cleaned = 0;
+		const trackedVmIds = new Set(this.agents.keys());
+		const chrootParent = join(this.chrootBaseDir, "firecracker");
+		let chrootEntries = [];
+		try {
+			chrootEntries = await readdir(chrootParent);
+		} catch {}
+		const liveVmIds = /* @__PURE__ */ new Set();
+		for (const entry of chrootEntries) if (trackedVmIds.has(entry) || await this.isVmProcessAlive(entry)) liveVmIds.add(entry);
+		const liveTapNames = new Set([...liveVmIds].map((id) => `kici-${id.slice(0, 8)}`));
+		try {
+			const allocations = await this.ipAllocator.getAllocations();
+			const scalerAllocations = allocations.filter((a) => a.scaler_name === this.name);
+			for (const alloc of scalerAllocations) {
+				if (trackedVmIds.has(alloc.vm_id)) continue;
+				if (!(liveVmIds.has(alloc.vm_id) || await this.isVmProcessAlive(alloc.vm_id))) {
+					try {
+						const chrootDir = this.getChrootDir(alloc.vm_id);
+						await this.forwardRemainingLogs(alloc.vm_id, chrootDir);
+					} catch {}
+					try {
+						await this.execAsync("ip", [
+							"link",
+							"del",
+							alloc.tap_device
+						]);
+					} catch {}
+					await this.ipAllocator.release(alloc.vm_id);
+					try {
+						await this.removeChrootDir(alloc.vm_id);
+					} catch {}
+					cleaned++;
+				}
+			}
+			const allocatedVmIds = new Set(allocations.map((a) => a.vm_id));
+			for (const entry of chrootEntries) {
+				if (allocatedVmIds.has(entry)) continue;
+				if (trackedVmIds.has(entry)) continue;
+				if (liveVmIds.has(entry)) continue;
+				try {
+					const orphanChrootDir = join(chrootParent, entry, "root");
+					await this.forwardRemainingLogs(entry, orphanChrootDir);
+				} catch {}
+				try {
+					await this.removeChrootDir(entry);
+					cleaned++;
+				} catch {}
+			}
+			const trackedTapDevices = new Set([...this.agents.values()].map((a) => a.tapDevice).filter((tap) => tap.length > 0));
+			const allocatedTapsBefore = new Set(allocations.map((a) => a.tap_device));
+			try {
+				const { stdout } = await this.execAsync("ip", ["-br", "link"]);
+				const ifaceNames = stdout.split("\n").map((line) => line.split(/\s+/)[0]).filter((name) => !!name);
+				let allocatedTapsAfter;
+				try {
+					const allocationsAfter = await this.ipAllocator.getAllocations();
+					allocatedTapsAfter = new Set(allocationsAfter.map((a) => a.tap_device));
+				} catch {
+					allocatedTapsAfter = allocatedTapsBefore;
+				}
+				for (const name of ifaceNames) {
+					if (!VM_TAP_PATTERN.test(name)) continue;
+					if (PROTECTED_INTERFACES.includes(name)) continue;
+					if (allocatedTapsBefore.has(name)) continue;
+					if (allocatedTapsAfter.has(name)) continue;
+					if (trackedTapDevices.has(name)) continue;
+					if (liveTapNames.has(name)) continue;
+					try {
+						await this.execAsync("ip", [
+							"link",
+							"del",
+							name
+						]);
+						cleaned++;
+					} catch {}
+				}
+			} catch {}
+		} catch {}
+		return cleaned;
+	}
+	/**
+	* Default interval for periodic orphan sweeps (15 minutes).
+	*
+	* Long-running orchestrators need in-process orphan sweeps because the
+	* external kici-leak-sweep timer skips TAP cleanup while a staging
+	* orchestrator is active (to avoid racing spawns). Without this, leaked
+	* TAPs accumulate until the orchestrator restarts — which can be weeks.
+	*/
+	static ORPHAN_SWEEP_INTERVAL_MS = 900 * 1e3;
+	/**
+	* Start a periodic orphan sweep. Idempotent — calling twice has no effect
+	* beyond the first call. Use stopPeriodicOrphanSweep() to stop.
+	*
+	* @param intervalMs override the default interval (primarily for tests)
+	*/
+	startPeriodicOrphanSweep(intervalMs = FirecrackerScalerBackend.ORPHAN_SWEEP_INTERVAL_MS) {
+		if (this.orphanSweepTimer !== null) return;
+		const runSweep = async () => {
+			if (this.orphanSweepInFlight) return;
+			this.orphanSweepInFlight = true;
+			try {
+				const cleaned = await this.cleanupOrphans();
+				if (cleaned > 0) logger$2.info(`Periodic orphan sweep cleaned ${cleaned} resources`, { backend: this.name });
+			} catch (err) {
+				logger$2.warn("Periodic orphan sweep failed", {
+					backend: this.name,
+					error: toErrorMessage(err)
+				});
+			} finally {
+				this.orphanSweepInFlight = false;
+			}
+		};
+		this.orphanSweepTimer = setInterval(() => {
+			runSweep().catch(() => {});
+		}, intervalMs);
+		this.orphanSweepTimer.unref?.();
+	}
+	/**
+	* Stop the periodic orphan sweep started by startPeriodicOrphanSweep().
+	* Safe to call when the sweep was never started.
+	*/
+	stopPeriodicOrphanSweep() {
+		if (this.orphanSweepTimer !== null) {
+			clearInterval(this.orphanSweepTimer);
+			this.orphanSweepTimer = null;
+		}
+	}
+	/**
+	* 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).
+	*
+	* 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.
+	*/
+	buildForwardedEnv(matchedLabelSet, agentId) {
+		const merged = {};
+		for (const [k, v] of Object.entries(process.env)) {
+			if (!k.startsWith(KICI_AGENT_ENV_PREFIX) || v === void 0) continue;
+			const stripped = k.slice(KICI_AGENT_ENV_PREFIX.length);
+			if (stripped.length === 0) continue;
+			merged[stripped] = v;
+		}
+		Object.assign(merged, matchedLabelSet.env ?? {});
+		const accepted = {};
+		let usedBytes = 0;
+		for (const [k, v] of Object.entries(merged)) {
+			if (!POSIX_ENV_NAME_PATTERN.test(k)) {
+				logger$2.warn(`Skipping forwarded env var "${k}" for agent ${agentId}: not a POSIX-safe identifier`);
+				continue;
+			}
+			const cost = Buffer.byteLength(k) + Buffer.byteLength(v) + 2;
+			if (usedBytes + cost > MMDS_FORWARDED_ENV_BUDGET_BYTES) {
+				logger$2.warn(`Skipping forwarded env var "${k}" for agent ${agentId}: would exceed ${MMDS_FORWARDED_ENV_BUDGET_BYTES}-byte MMDS budget`);
+				continue;
+			}
+			accepted[k] = v;
+			usedBytes += cost;
+		}
+		return accepted;
+	}
+	/**
+	* Build the Firecracker VM configuration JSON.
+	*
+	* Resolution order for vcpu_count and mem_size_mib:
+	*   1. effectiveLimits (resolved by ScalerManager from job/scaler/global caps) — wins if set.
+	*   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.
+	*/
+	buildVmConfig(alloc, labelSet, effectiveLimits) {
+		let vcpuCount = labelSet.vcpuCount ?? this.vcpuCount;
+		let memSizeMib = labelSet.memSizeMib ?? this.memSizeMib;
+		if (effectiveLimits) {
+			if (typeof effectiveLimits.cpus === "number" && effectiveLimits.cpus > 0) {
+				const rounded = Math.max(1, Math.ceil(effectiveLimits.cpus));
+				if (rounded !== effectiveLimits.cpus) logger$2.debug(`Rounding effective CPU limit ${effectiveLimits.cpus} up to ${rounded} vCPUs for Firecracker (integer vCPU required)`);
+				vcpuCount = rounded;
+			}
+			if (typeof effectiveLimits.memBytes === "number" && effectiveLimits.memBytes > 0) {
+				const mib = Math.floor(effectiveLimits.memBytes / (1024 * 1024));
+				if (mib > 0) {
+					if (mib * 1024 * 1024 !== effectiveLimits.memBytes) logger$2.debug(`Truncating effective memory limit ${effectiveLimits.memBytes}B to ${mib} MiB for Firecracker (integer MiB required)`);
+					memSizeMib = mib;
+				}
+			}
+		}
+		return {
+			"boot-source": {
+				kernel_image_path: "/kernel",
+				boot_args: `console=ttyS0 reboot=k panic=1 random.trust_cpu=on init=/init ip=${alloc.ip}::${this.gateway}:${this.netmask}::eth0:off`
+			},
+			drives: [{
+				drive_id: "rootfs",
+				path_on_host: "/rootfs.ext4",
+				is_root_device: true,
+				is_read_only: true
+			}, {
+				drive_id: "overlay",
+				path_on_host: "/overlay.ext4",
+				is_root_device: false,
+				is_read_only: false
+			}],
+			"machine-config": {
+				vcpu_count: vcpuCount,
+				mem_size_mib: memSizeMib,
+				smt: false
+			},
+			"network-interfaces": [{
+				iface_id: "eth0",
+				guest_mac: alloc.mac,
+				host_dev_name: alloc.tapDevice
+			}],
+			"mmds-config": {
+				network_interfaces: ["eth0"],
+				ipv4_address: "169.254.169.254"
+			}
+		};
+	}
+	/**
+	* Create a sparse ext4 overlay drive for per-VM writable layer.
+	* The file is sparse (allocates no disk blocks until written) and
+	* pre-formatted as ext4 so the guest can mount it immediately.
+	*/
+	async createOverlayDrive(path, sizeMib) {
+		const fd = await open(path, "w");
+		await fd.truncate(sizeMib * 1024 * 1024);
+		await fd.close();
+		await this.execAsync("mkfs.ext4", ["-qF", path]);
+	}
+	/**
+	* Promisified execFile wrapper with 30s timeout.
+	*/
+	async execAsync(cmd, args) {
+		if (this.requireSudo && (cmd === "ip" || cmd === "chown" || cmd === "chmod")) return execFileAsync("sudo", [
+			"-n",
+			cmd,
+			...args
+		], { timeout: 3e4 });
+		return execFileAsync(cmd, args, { timeout: 3e4 });
+	}
+	/**
+	* 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.
+	*/
+	async removeChrootDir(vmId) {
+		const dir = join(this.chrootBaseDir, "firecracker", vmId);
+		if (this.requireSudo) {
+			const owner = `${process.getuid?.() ?? 0}:${process.getgid?.() ?? 0}`;
+			try {
+				await this.execAsync("chown", [
+					"-R",
+					owner,
+					dir
+				]);
+			} catch {}
+		}
+		await rm(dir, {
+			recursive: true,
+			force: true
+		});
+	}
+	/**
+	* Get the API socket path for an agent's Firecracker VM.
+	*/
+	getSocketPath(agentId) {
+		return join(this.chrootBaseDir, "firecracker", agentId, "root", "run", "firecracker.socket");
+	}
+	/**
+	* Get the chroot directory path for an agent.
+	*/
+	getChrootDir(agentId) {
+		return join(this.chrootBaseDir, "firecracker", agentId, "root");
+	}
+	/**
+	* Check if a VM process is still alive by reading its PID file and sending signal 0.
+	*/
+	async isVmProcessAlive(vmId) {
+		try {
+			const pidStr = await readFile(join(this.getChrootDir(vmId), "firecracker.pid"), "utf-8");
+			const pid = parseInt(pidStr.trim(), 10);
+			if (isNaN(pid)) return false;
+			process.kill(pid, 0);
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	/**
+	* Wait for a VM's jailer process to exit within a timeout.
+	*/
+	async waitForProcessExit(vmId, timeoutMs) {
+		const deadline = Date.now() + timeoutMs;
+		const interval = 200;
+		while (Date.now() < deadline) {
+			if (!await this.isVmProcessAlive(vmId)) return true;
+			await new Promise((resolve) => setTimeout(resolve, interval));
+		}
+		return false;
+	}
+	/**
+	* Clean up resources after a failed spawn attempt.
+	*/
+	async cleanupFailedSpawn(agentId, alloc) {
+		if (alloc) {
+			try {
+				await removeIsolationRules(alloc.ip, { requireSudo: this.requireSudo });
+			} catch {}
+			try {
+				await this.ipAllocator.release(agentId);
+			} catch {}
+			try {
+				await this.execAsync("ip", [
+					"link",
+					"del",
+					alloc.tapDevice
+				]);
+			} catch {}
+		}
+		try {
+			await rm(join(this.chrootBaseDir, "firecracker", agentId), {
+				recursive: true,
+				force: true
+			});
+		} catch {}
+	}
+	/**
+	* 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.
+	*/
+	startLogTailing(agentId, serialLogPath, vmmLogPath, child) {
+		const abortController = new AbortController();
+		this.tailAbortControllers.set(agentId, abortController);
+		const signal = abortController.signal;
+		const output = process.stdout;
+		this.tailAndForward(serialLogPath, agentId, "firecracker-serial", signal, output);
+		this.tailAndForward(vmmLogPath, agentId, "firecracker-vmm", signal, output);
+		child.on("exit", (code, sig) => {
+			setTimeout(() => {
+				abortController.abort();
+				this.tailAbortControllers.delete(agentId);
+				if (code !== 0 && code !== null) {
+					const failureType = this.detectFailureType(serialLogPath);
+					forwardLine(JSON.stringify({
+						level: "error",
+						message: "VM boot failed",
+						exitCode: code,
+						signal: sig,
+						failureType
+					}), agentId, output, void 0, "firecracker-serial");
+				}
+			}, 500);
+		});
+	}
+	/**
+	* Tail a single log file and forward each line via forwardLine().
+	* For serial console lines: non-JSON lines (kernel boot output) are wrapped
+	* as debug-level JSON; failure patterns (kernel panic, init failure) are elevated to error.
+	*/
+	async tailAndForward(filePath, agentId, logsSource, signal, output) {
+		try {
+			for await (const line of tailFile(filePath, signal)) {
+				if (logsSource === "firecracker-serial") {
+					let isJson = false;
+					try {
+						JSON.parse(line);
+						isJson = true;
+					} catch {}
+					if (!isJson) {
+						const level = this.isFailurePattern(line) ? "error" : "debug";
+						forwardLine(JSON.stringify({
+							level,
+							message: line
+						}), agentId, output, void 0, logsSource);
+						continue;
+					}
+				}
+				forwardLine(line, agentId, output, void 0, logsSource);
+			}
+		} catch (err) {
+			if (err.name === "AbortError") return;
+			forwardLine(JSON.stringify({
+				level: "warn",
+				message: `Log tailing error for ${filePath}: ${err}`
+			}), agentId, output, void 0, logsSource);
+		}
+	}
+	/**
+	* Check if a serial console line matches known boot failure patterns.
+	*/
+	isFailurePattern(line) {
+		return [
+			/Kernel panic/i,
+			/Failed to execute \/init/i,
+			/failed to start/i,
+			/systemd\[1\]: Failed/i,
+			/VFS: Unable to mount root fs/i,
+			/not syncing/i
+		].some((p) => p.test(line));
+	}
+	/**
+	* Read the serial console log file and detect the type of boot failure.
+	*/
+	detectFailureType(serialLogPath) {
+		try {
+			const content = readFileSync(serialLogPath, "utf-8");
+			if (/Kernel panic/i.test(content)) return "kernel-panic";
+			if (/Failed to execute \/init/i.test(content) || /systemd\[1\]: Failed/i.test(content)) return "init-failure";
+			if (/VFS: Unable to mount root fs/i.test(content)) return "rootfs-mount-failure";
+			return "unknown";
+		} catch {
+			return "unknown";
+		}
+	}
+	/**
+	* Read and forward any remaining log file content for an orphaned/dead VM.
+	* Called during cleanupOrphans() before deleting the chroot directory.
+	*/
+	async forwardRemainingLogs(vmId, chrootDir) {
+		const output = process.stdout;
+		for (const [fileName, logsSource] of [[SERIAL_LOG_FILE, "firecracker-serial"], [VMM_LOG_FILE, "firecracker-vmm"]]) try {
+			const lines = (await readFile(join(chrootDir, fileName), "utf-8")).split("\n").filter((l) => l.length > 0);
+			for (const line of lines) forwardLine(line, vmId, output, void 0, logsSource);
+		} catch {}
+	}
+};
+//#endregion
+//#region src/scaler/container-backend.ts
+/**
+* Container scaler backend implementation.
+*
+* Manages ephemeral agent containers using Docker or Podman via dockerode.
+* Supports auto-detection of container runtime socket.
+* Handles full container lifecycle: pull, create, start, stop, remove.
+* Supports container socket sharing, resource limits, and orphan cleanup.
+*/
+const logger$1 = createLogger({ prefix: "container-backend" });
+/** Name of the isolated bridge network for agent containers. */
+const ISOLATED_NETWORK_NAME = "kici-agent-net";
+/** Subnet for the isolated agent network. */
+const ISOLATED_NETWORK_SUBNET = "172.30.0.0/16";
+/** Gateway IP for the isolated agent network (host-side). */
+const ISOLATED_NETWORK_GATEWAY = "172.30.0.1";
+const PROBE_ORDER = [{
+	path: "/var/run/docker.sock",
+	runtime: "docker"
+}, {
+	path: "/run/podman/podman.sock",
+	runtime: "podman"
+}];
+/**
+* Probe known socket paths to detect which container runtime is available.
+* Returns the first accessible socket found, or null if none found.
+*/
+async function detectRuntime(runtimeHint) {
+	const probes = [...PROBE_ORDER];
+	const xdgDir = process.env.XDG_RUNTIME_DIR;
+	if (xdgDir) probes.push({
+		path: `${xdgDir}/podman/podman.sock`,
+		runtime: "podman"
+	});
+	const filtered = runtimeHint && runtimeHint !== "auto" ? probes.filter((p) => p.runtime === runtimeHint) : probes;
+	for (const probe of filtered) try {
+		await access(probe.path, constants.R_OK | constants.W_OK);
+		return {
+			socketPath: probe.path,
+			runtime: probe.runtime
+		};
+	} catch {
+		continue;
+	}
+	return null;
+}
+/**
+* Create a LogCapture from a running container's stdout/stderr streams.
+* Uses dockerode's demuxStream to strip Docker's 8-byte multiplexed headers.
+*/
+async function createContainerLogCapture(docker, containerId) {
+	const stream = await docker.getContainer(containerId).logs({
+		follow: true,
+		stdout: true,
+		stderr: true,
+		timestamps: false
+	});
+	const passthrough = new PassThrough();
+	docker.modem.demuxStream(stream, passthrough, passthrough);
+	const TAIL_MAX_LINES = 50;
+	const tailBuf = [];
+	const pushTail = (line) => {
+		tailBuf.push(line);
+		if (tailBuf.length > TAIL_MAX_LINES) tailBuf.shift();
+	};
+	const rl = createInterface({
+		input: passthrough,
+		crlfDelay: Infinity
+	});
+	rl.on("line", pushTail);
+	return {
+		async *lines() {
+			for await (const line of rl) yield line;
+		},
+		tail() {
+			return tailBuf.join("\n");
+		},
+		close() {
+			stream.destroy?.();
+			rl.close();
+		}
+	};
+}
+var ContainerScalerBackend = class ContainerScalerBackend {
+	type = ScalerBackendType.enum.container;
+	spawnsOnLocalHost;
+	maxAgents;
+	_labelSets;
+	name;
+	docker;
+	defaultResources;
+	/** The resolved socket path (for socket sharing bind mounts) */
+	resolvedSocketPath;
+	/** The detected or configured runtime type */
+	detectedRuntime;
+	/** Extra host:IP mappings for spawned containers */
+	extraHosts;
+	/** Whether nftables-based network isolation is enabled */
+	networkIsolation;
+	/** Token store for creating ephemeral agent auth tokens */
+	tokenStore;
+	/** TTL for ephemeral agent tokens in ms */
+	tokenTtlMs;
+	/** Agent roles for this scaler. undefined = all, [] = execution only. */
+	roles;
+	/** ID of the isolated bridge network (set after creation/discovery) */
+	isolatedNetworkId = "";
+	/** Host bridge interface name for the isolated network (used by nftables) */
+	isolatedBridgeIface = "";
+	/** Tracks all managed agent containers by ManagedAgent.id */
+	agents = /* @__PURE__ */ new Map();
+	/** Maps container ID to ManagedAgent.id for reverse lookup */
+	containerToManaged = /* @__PURE__ */ new Map();
+	/** LogCapture instances for each managed agent (keyed by ManagedAgent.id) */
+	logCaptures = /* @__PURE__ */ new Map();
+	/** Maps managedId → container IP on the isolated network (for per-container nftables cleanup) */
+	containerIps = /* @__PURE__ */ new Map();
+	constructor(options, socketPath, runtime) {
+		this.name = options.name;
+		this._labelSets = options.labelSets;
+		this.maxAgents = options.maxAgents;
+		this.defaultResources = options.defaultResources;
+		this.extraHosts = options.extraHosts;
+		this.networkIsolation = options.networkIsolation !== false;
+		this.tokenStore = options.tokenStore;
+		this.tokenTtlMs = options.tokenTtlMs ?? 36e5;
+		this.roles = options.roles;
+		this.resolvedSocketPath = socketPath;
+		this.detectedRuntime = runtime;
+		this.spawnsOnLocalHost = !options.host;
+		if (options.host) {
+			this.docker = new Docker({ host: options.host });
+			this.resolvedSocketPath = "";
+			this.detectedRuntime = options.runtime === "podman" ? "podman" : "docker";
+		} else this.docker = new Docker({ socketPath });
+	}
+	/**
+	* Ensure the isolated bridge network exists and nftables rules are applied.
+	*
+	* Creates `kici-agent-net` if it doesn't exist, inspects the network to
+	* discover the host bridge interface name, then applies RFC1918 + metadata
+	* blocking rules via nftables with a gateway exception.
+	*
+	* Idempotent: safe to call across orchestrator restarts.
+	*/
+	async ensureIsolatedNetwork() {
+		const existing = (await this.docker.listNetworks({ filters: { name: [ISOLATED_NETWORK_NAME] } })).find((n) => n.Name === ISOLATED_NETWORK_NAME);
+		let networkId;
+		if (existing) {
+			networkId = existing.Id;
+			logger$1.info(`Isolated network ${ISOLATED_NETWORK_NAME} already exists (${networkId.slice(0, 12)})`);
+		} else try {
+			networkId = (await this.docker.createNetwork({
+				Name: ISOLATED_NETWORK_NAME,
+				Driver: "bridge",
+				IPAM: { Config: [{
+					Subnet: ISOLATED_NETWORK_SUBNET,
+					Gateway: ISOLATED_NETWORK_GATEWAY
+				}] },
+				Labels: { "kici-managed": "true" }
+			})).id;
+			logger$1.info(`Created isolated network ${ISOLATED_NETWORK_NAME} (${networkId.slice(0, 12)})`);
+		} catch (err) {
+			if (err.statusCode === 409) {
+				logger$1.info("Isolated network creation raced -- using existing network");
+				const found = (await this.docker.listNetworks({ filters: { name: [ISOLATED_NETWORK_NAME] } })).find((n) => n.Name === ISOLATED_NETWORK_NAME);
+				if (!found) throw new Error(`Failed to find isolated network ${ISOLATED_NETWORK_NAME} after 409 conflict`);
+				networkId = found.Id;
+			} else throw err;
+		}
+		this.isolatedNetworkId = networkId;
+		const bridgeName = (await this.docker.getNetwork(networkId).inspect()).Options?.["com.docker.network.bridge.name"] ?? `br-${networkId.slice(0, 12)}`;
+		this.isolatedBridgeIface = bridgeName;
+		logger$1.info(`Isolated network bridge interface: ${bridgeName}`);
+		if (this.networkIsolation) {
+			await ensureKiciTable();
+			logger$1.info("nftables kici table ready — per-container rules will be applied during spawn");
+		} else logger$1.warn("Network isolation DISABLED for container backend — nftables rules will NOT be applied. Agent containers will have unrestricted network access.");
+	}
+	/**
+	* Declare required tools for a container scaler entry.
+	*
+	* For the auto-detect case (no explicit socketPath / remote host) the
+	* orchestrator must have a local container runtime — docker OR podman — on
+	* PATH, otherwise the scaler cannot spawn agent containers. Declaring it
+	* here lets the startup tool-validation gate fail fast with a clear error
+	* instead of the first job hanging. When a socketPath or remote host is
+	* configured the binary need not be on PATH (the runtime may be remote), so
+	* reachability is validated later in create().
+	*/
+	static getRequiredTools(entry) {
+		if (entry.host || entry.socketPath) return [];
+		return [{
+			type: "any-path-binary",
+			names: ["docker", "podman"],
+			reason: `container scaler "${entry.name}" needs a local container runtime to spawn agents. Install Docker or Podman, or set socketPath / host in scalers.yaml for a remote runtime.`
+		}];
+	}
+	/**
+	* Create a ContainerScalerBackend with auto-detected or configured socket.
+	* Throws if no container runtime is found and no host is configured.
+	*/
+	static async create(options) {
+		if (options.networkIsolation !== false) await validateNftablesAvailability();
+		let backend;
+		if (options.host) backend = new ContainerScalerBackend(options, "", options.runtime === "podman" ? "podman" : "docker");
+		else if (options.socketPath) {
+			const runtime = options.socketPath.includes("podman") ? "podman" : "docker";
+			logger$1.info(`Using configured socket at ${options.socketPath}`, { runtime });
+			backend = new ContainerScalerBackend(options, options.socketPath, runtime);
+		} else {
+			const detected = await detectRuntime(options.runtime);
+			if (!detected) throw new Error("No container runtime found. Install Docker or Podman, or configure host.");
+			logger$1.info(`Detected ${detected.runtime} at ${detected.socketPath}`);
+			backend = new ContainerScalerBackend(options, detected.socketPath, detected.runtime);
+		}
+		if (options.networkIsolation !== false) await backend.ensureIsolatedNetwork();
+		else logger$1.info("Network isolation disabled — skipping isolated network and nftables setup");
+		return backend;
+	}
+	/** Log source identifier: 'docker' or 'podman' based on detected runtime. */
+	get logsSource() {
+		return this.detectedRuntime;
+	}
+	get labelSets() {
+		return this._labelSets;
+	}
+	getActiveCount() {
+		return this.agents.size;
+	}
+	async spawn(labelSet, agentId, orchestratorUrl, onEvent, effectiveLimits, spawnContext) {
+		const emit = (eventType, detail) => {
+			onEvent?.({
+				agentId,
+				eventType,
+				detail,
+				timestampMs: Date.now()
+			});
+		};
+		const normalizedTarget = normalizeLabelSet(labelSet);
+		const matchedLabelSet = this._labelSets.find((ls) => normalizeLabelSet(ls.labels) === normalizedTarget);
+		if (!matchedLabelSet) throw new Error(`Label set [${labelSet.join(", ")}] not supported by container backend "${this.name}"`);
+		if (this.getActiveCount() >= this.maxAgents) throw new Error(`Container backend "${this.name}" at capacity (${this.maxAgents}/${this.maxAgents})`);
+		const managed = {
+			id: agentId,
+			labelSet,
+			backendRef: "",
+			spawnedAt: Date.now(),
+			state: "spawning"
+		};
+		this.agents.set(managed.id, managed);
+		try {
+			const agentEnvForwarded = [];
+			for (const [key, value] of Object.entries(process.env)) if (key.startsWith(KICI_AGENT_ENV_PREFIX) && value !== void 0) {
+				const stripped = key.slice(KICI_AGENT_ENV_PREFIX.length);
+				if (stripped.length > 0) agentEnvForwarded.push(`${stripped}=${value}`);
+			}
+			const fullLabels = scalerAgentLabels(labelSet, this.type, this.name, this.roles);
+			let agentToken;
+			if (this.tokenStore) agentToken = await this.tokenStore.createEphemeral(agentId, fullLabels, this.tokenTtlMs);
+			const env = [
+				`KICI_ORCHESTRATOR_URL=${orchestratorUrl}`,
+				`KICI_AGENT_ID=${agentId}`,
+				`KICI_LABELS=${fullLabels.join(",")}`,
+				`KICI_SCALER_MANAGED=1`,
+				`KICI_EXECUTION_MODE=bare-metal`,
+				...agentToken ? [`KICI_AGENT_TOKEN=${agentToken}`] : [],
+				...matchedLabelSet.backpressureMode ? [`KICI_BACKPRESSURE_MODE=${matchedLabelSet.backpressureMode}`] : [],
+				...agentEnvForwarded,
+				...Object.entries(matchedLabelSet.env ?? {}).map(([k, v]) => `${k}=${v}`)
+			];
+			const binds = [...matchedLabelSet.volumes ?? []];
+			if (matchedLabelSet.containerSocket && this.resolvedSocketPath) binds.push(`${this.resolvedSocketPath}:${this.resolvedSocketPath}`);
+			let memoryBytes;
+			let nanoCpus;
+			if (effectiveLimits && (effectiveLimits.cpus || effectiveLimits.memBytes)) {
+				if (effectiveLimits.memBytes) memoryBytes = effectiveLimits.memBytes;
+				if (effectiveLimits.cpus) nanoCpus = effectiveLimits.cpus * 1e9;
+			} else {
+				const limits = (matchedLabelSet.resources ?? this.defaultResources)?.limits;
+				if (limits?.memory) memoryBytes = parseMemoryString(limits.memory);
+				if (limits?.cpus) nanoCpus = limits.cpus * 1e9;
+			}
+			const pullPolicy = matchedLabelSet.imagePullPolicy ?? "Always";
+			let shouldPull = pullPolicy === "Always";
+			if (pullPolicy === "IfNotPresent") try {
+				await this.docker.getImage(matchedLabelSet.image).inspect();
+				shouldPull = false;
+			} catch {
+				shouldPull = true;
+			}
+			if (shouldPull) {
+				emit(ScalerEventType.enum["scaler.provisioning"], `pulling image ${matchedLabelSet.image}`);
+				const stream = await this.docker.pull(matchedLabelSet.image);
+				await new Promise((resolve, reject) => {
+					this.docker.modem.followProgress(stream, (err) => {
+						if (err) reject(err);
+						else resolve();
+					});
+				});
+			}
+			emit(ScalerEventType.enum["scaler.provisioning"], "creating container");
+			const normalizedLabelSetStr = normalizeLabelSet(labelSet);
+			const container = await this.docker.createContainer({
+				Image: matchedLabelSet.image,
+				Env: env,
+				Labels: {
+					"kici-managed": "true",
+					"kici-scaler-name": this.name,
+					"kici-agent-id": agentId,
+					"kici-labels": normalizedLabelSetStr,
+					...spawnContext?.boundJobId && { "kici-bound-job-id": spawnContext.boundJobId },
+					...spawnContext?.runId && { "kici-run-id": spawnContext.runId }
+				},
+				HostConfig: {
+					Memory: memoryBytes,
+					NanoCpus: nanoCpus,
+					Binds: binds.length > 0 ? binds : void 0,
+					ExtraHosts: this.extraHosts?.length ? this.extraHosts : void 0,
+					AutoRemove: false
+				},
+				...this.networkIsolation && { NetworkingConfig: { EndpointsConfig: { [ISOLATED_NETWORK_NAME]: {} } } }
+			});
+			if (this.networkIsolation) emit(ScalerEventType.enum["scaler.network"], "configuring network isolation");
+			await container.start();
+			emit(ScalerEventType.enum["scaler.ready"], "container started");
+			if (this.networkIsolation) {
+				const containerIp = (await this.docker.getContainer(container.id).inspect()).NetworkSettings?.Networks?.[ISOLATED_NETWORK_NAME]?.IPAddress;
+				if (containerIp) {
+					this.containerIps.set(managed.id, containerIp);
+					await addIsolationRules(containerIp, ISOLATED_NETWORK_GATEWAY, matchedLabelSet.networkPolicy, "saddr");
+				} else logger$1.warn("Could not determine container IP for nftables rules", { agentId });
+			}
+			try {
+				const capture = await createContainerLogCapture(this.docker, container.id);
+				this.logCaptures.set(managed.id, capture);
+			} catch (err) {
+				logger$1.warn("Failed to create log capture for container", {
+					agentId,
+					error: toErrorMessage(err)
+				});
+			}
+			managed.state = "running";
+			managed.backendRef = container.id;
+			this.containerToManaged.set(container.id, managed.id);
+			emit(ScalerEventType.enum["agent.connecting"], "waiting for agent WS registration");
+			return managed;
+		} catch (err) {
+			const t = this.logCaptures.get(managed.id)?.tail() ?? "";
+			const base = toErrorMessage(err);
+			emit(ScalerEventType.enum["scaler.failed"], t ? `${base}\n--- captured output ---\n${t}` : base);
+			const failedIp = this.containerIps.get(managed.id);
+			if (failedIp) {
+				try {
+					await removeIsolationRules(failedIp);
+				} catch {}
+				this.containerIps.delete(managed.id);
+			}
+			this.agents.delete(managed.id);
+			throw err;
+		}
+	}
+	getScalerContext(agentId) {
+		const managed = this.agents.get(agentId);
+		if (!managed) return void 0;
+		const normalizedTarget = normalizeLabelSet(managed.labelSet);
+		const matchedLabelSet = this._labelSets.find((ls) => normalizeLabelSet(ls.labels) === normalizedTarget);
+		return {
+			backendType: "container",
+			scalerName: this.name,
+			image: matchedLabelSet?.image,
+			imagePullPolicy: matchedLabelSet?.imagePullPolicy ?? "Always",
+			runtime: this.detectedRuntime,
+			resources: matchedLabelSet?.resources ?? this.defaultResources,
+			networkIsolation: this.networkIsolation,
+			volumes: matchedLabelSet?.volumes,
+			extraHosts: this.extraHosts
+		};
+	}
+	async destroy(managedId) {
+		const managed = this.agents.get(managedId);
+		if (!managed) return;
+		managed.state = "destroying";
+		const containerIp = this.containerIps.get(managedId);
+		this.containerIps.delete(managedId);
+		this.containerToManaged.delete(managed.backendRef);
+		this.agents.delete(managedId);
+		if (containerIp && this.networkIsolation) try {
+			await removeIsolationRules(containerIp);
+		} catch {}
+		const capture = this.logCaptures.get(managedId);
+		if (capture) {
+			capture.close();
+			this.logCaptures.delete(managedId);
+		}
+		try {
+			const container = this.docker.getContainer(managed.backendRef);
+			try {
+				await container.stop({ t: 10 });
+			} catch {}
+			try {
+				await container.remove({ force: true });
+			} catch {}
+		} catch {}
+	}
+	/**
+	* Get the LogCapture for a managed agent (used by ScalerManager for log forwarding).
+	*/
+	getLogCapture(managedId) {
+		return this.logCaptures.get(managedId);
+	}
+	async shutdownAll() {
+		const ids = [...this.agents.keys()];
+		await Promise.allSettled(ids.map((id) => this.destroy(id)));
+	}
+	reload(labelSets) {
+		const errors = [];
+		labelSets.forEach((ls, i) => {
+			if (!ls.image) errors.push(`Label set [${i}] requires an 'image' field for container backend`);
+		});
+		if (errors.length > 0) return {
+			valid: false,
+			errors
+		};
+		this._labelSets = labelSets;
+		return { valid: true };
+	}
+	/**
+	* Clean up orphaned kici-managed containers on startup.
+	* Finds containers with the `kici-managed=true` label and removes them.
+	* Returns the count of cleaned containers.
+	*/
+	async cleanupOrphans() {
+		const containers = await this.docker.listContainers({
+			all: true,
+			filters: { label: ["kici-managed=true"] }
+		});
+		let cleaned = 0;
+		for (const info of containers) {
+			const container = this.docker.getContainer(info.Id);
+			try {
+				await container.stop({ t: 5 });
+			} catch {}
+			try {
+				await container.remove({ force: true });
+				cleaned++;
+			} catch {}
+		}
+		return cleaned;
+	}
+};
+//#endregion
+//#region src/scaler/ip-allocator.ts
+/**
+* Parse an IPv4 address string to a 32-bit unsigned integer.
+*/
+function ipToNumber(ip) {
+	const parts = ip.split(".");
+	if (parts.length !== 4) throw new Error(`Invalid IP address: "${ip}"`);
+	let result = 0;
+	for (const part of parts) {
+		const octet = parseInt(part, 10);
+		if (isNaN(octet) || octet < 0 || octet > 255) throw new Error(`Invalid IP address: "${ip}"`);
+		result = result << 8 | octet;
+	}
+	return result >>> 0;
+}
+/**
+* Convert a 32-bit unsigned integer back to an IPv4 address string.
+*/
+function numberToIp(n) {
+	const unsigned = n >>> 0;
+	return [
+		unsigned >>> 24 & 255,
+		unsigned >>> 16 & 255,
+		unsigned >>> 8 & 255,
+		unsigned & 255
+	].join(".");
+}
+/**
+* Parse a CIDR notation string into a CidrRange.
+*
+* @example parseCidr('10.0.0.0/24')
+* // => { networkAddress: 167772160, prefixLength: 24, startIp: 167772161, endIp: 167772414 }
+*/
+function parseCidr(cidr) {
+	const parts = cidr.split("/");
+	if (parts.length !== 2) throw new Error(`Invalid CIDR notation: "${cidr}"`);
+	const ip = parts[0];
+	const prefixLength = parseInt(parts[1], 10);
+	if (isNaN(prefixLength) || prefixLength < 0 || prefixLength > 32) throw new Error(`Invalid CIDR prefix length: ${parts[1]}`);
+	const networkAddress = ipToNumber(ip);
+	const broadcastAddress = (networkAddress | (1 << 32 - prefixLength) - 1) >>> 0;
+	return {
+		networkAddress,
+		prefixLength,
+		startIp: networkAddress + 1 >>> 0,
+		endIp: broadcastAddress - 1 >>> 0
+	};
+}
+/**
+* Generate a deterministic MAC address from an IP address.
+*
+* Uses the locally-administered unicast prefix 06:00:AC followed by
+* the last 3 octets of the IP address encoded as hex.
+*
+* @example generateMac('10.0.0.5')  // => '06:00:AC:00:00:05'
+* @example generateMac('10.0.1.42') // => '06:00:AC:00:01:2A'
+*/
+function generateMac(ip) {
+	const parts = ip.split(".");
+	if (parts.length !== 4) throw new Error(`Invalid IP address for MAC generation: "${ip}"`);
+	const hex = (n) => n.toString(16).toUpperCase().padStart(2, "0");
+	return `06:00:AC:${hex(parseInt(parts[1], 10))}:${hex(parseInt(parts[2], 10))}:${hex(parseInt(parts[3], 10))}`;
+}
+/**
+* Generate a TAP device name from a VM ID.
+* Linux interface names are limited to 15 characters (IFNAMSIZ).
+* Format: kici-XXXXXXXX (5 + 8 = 13 chars, well within limit).
+*
+* Uses the LAST 8 characters of the vmId to avoid collisions.
+* VM IDs have format "scaler-firecracker-XXXXXXXX" where the unique
+* random suffix is at the end. Using slice(0, 8) would always produce
+* "scaler-f" for all Firecracker VMs.
+*/
+function generateTapName(vmId) {
+	return `kici-${vmId.slice(-8)}`;
+}
+/**
+* Walk the CIDR range and call `pickIp` with each candidate IP (as a
+* dotted-quad string). The first IP for which `pickIp` returns a truthy
+* result is allocated and returned. Skips the gateway. Throws if the
+* range is exhausted. Shared by both `DbIpAllocator` and
+* `InMemoryIpAllocator` — keeps the "scan + skip gateway + skip
+* already-allocated" loop in one place.
+*/
+function findFirstFreeIp(range, gatewayNum, isAllocated) {
+	for (let n = range.startIp; n <= range.endIp; n++) {
+		const unsigned = n >>> 0;
+		if (unsigned === gatewayNum) continue;
+		const candidateIp = numberToIp(unsigned);
+		if (isAllocated(candidateIp)) continue;
+		return candidateIp;
+	}
+	throw new Error(`IP pool exhausted: no available addresses in ${numberToIp(range.startIp)}-${numberToIp(range.endIp)}`);
+}
+/**
+* In-memory CIDR IP allocator.
+*
+* Used by worker peers where the cluster Postgres is not reachable. State
+* lives in a `Map<vmId, IpAllocationRecord>` for the lifetime of the
+* orch process; on restart the allocator starts empty and the
+* firecracker-backend's existing `cleanupOrphans()` Pass-2/Pass-3 walks
+* the jailer chroot tree + host TAP devices (matching `VM_TAP_PATTERN`)
+* to reap any leftover state. No persistence and no chroot recovery
+* inside the allocator — the filesystem is the source of truth, and the
+* cleanup pass already consults it.
+*
+* Each orch has its own bridge with its own subnet, so per-process
+* state is by design. No locking needed: every method is synchronous on
+* the in-memory Map and only awaits to satisfy the async interface.
+*/
+var InMemoryIpAllocator = class {
+	range;
+	gateway;
+	gatewayNum;
+	netmask;
+	byVmId = /* @__PURE__ */ new Map();
+	allocatedIps = /* @__PURE__ */ new Set();
+	constructor(opts) {
+		this.range = parseCidr(opts.cidr);
+		this.gateway = opts.gateway;
+		this.gatewayNum = ipToNumber(opts.gateway);
+		this.netmask = opts.netmask;
+	}
+	async allocate(vmId, scalerName) {
+		const candidateIp = findFirstFreeIp(this.range, this.gatewayNum, (ip) => this.allocatedIps.has(ip));
+		const mac = generateMac(candidateIp);
+		const tapDevice = generateTapName(vmId);
+		this.byVmId.set(vmId, {
+			ip: candidateIp,
+			vm_id: vmId,
+			scaler_name: scalerName,
+			tap_device: tapDevice,
+			mac_address: mac
+		});
+		this.allocatedIps.add(candidateIp);
+		return {
+			ip: candidateIp,
+			gateway: this.gateway,
+			netmask: this.netmask,
+			mac,
+			tapDevice
+		};
+	}
+	async release(vmId) {
+		const existing = this.byVmId.get(vmId);
+		if (existing) {
+			this.allocatedIps.delete(existing.ip);
+			this.byVmId.delete(vmId);
+		}
+	}
+	async releaseByIp(ip) {
+		for (const [vmId, record] of this.byVmId) if (record.ip === ip) {
+			this.byVmId.delete(vmId);
+			this.allocatedIps.delete(ip);
+			return;
+		}
+	}
+	async getAllocations() {
+		return [...this.byVmId.values()];
+	}
+	async getAllocationForVm(vmId) {
+		return this.byVmId.get(vmId) ?? null;
+	}
+};
+//#endregion
+//#region src/scaler/reap-orphans.ts
+/**
+* Standalone orphan reaper.
+*
+* Reconstructs scaler backends from a loaded ScalerConfig and runs their
+* liveness-driven orphan cleanup WITHOUT a running orchestrator and (for
+* Firecracker) WITHOUT a database — an InMemoryIpAllocator stands in for the
+* coordinator's DbIpAllocator, exactly as worker mode does. Used by the
+* `kici-admin scaler reap-orphans` command and by the startup disk-space guard
+* to recover a node whose data disk is full and whose orchestrator therefore
+* cannot start.
+*
+* Writes nothing to disk: progress is the caller's concern (counts are
+* returned). removeChrootDir already chowns-before-rm on rootless (requireSudo)
+* nodes, so the reap frees disk owned by the jailer subuid.
+*/
+/**
+* Reap orphan Firecracker resources (dead-VM chroots + TAPs) for every
+* `firecracker` scaler in the config. Safe to run alongside a live
+* orchestrator: the reap is liveness-driven and only touches dead VMs.
+*/
+async function reapFirecrackerOrphans(scalerConfig) {
+	const counts = {};
+	const fcNet = scalerConfig.firecracker;
+	const cidr = fcNet?.cidr ?? "10.0.0.0/24";
+	const bridgeName = fcNet?.bridgeName ?? "kici-br0";
+	const gateway = fcNet?.gateway ?? "10.0.0.1";
+	const netmask = fcNet?.netmask ?? "255.255.255.0";
+	const table = fcNet?.table ?? "kici";
+	for (const s of scalerConfig.scalers) {
+		if (s.type !== "firecracker") continue;
+		const backend = new FirecrackerScalerBackend({
+			name: s.name,
+			labelSets: s.labelSets,
+			maxAgents: s.maxAgents,
+			ipAllocator: new InMemoryIpAllocator({
+				cidr,
+				gateway,
+				netmask
+			}),
+			firecrackerPath: s.firecrackerPath,
+			jailerPath: s.jailerPath,
+			kernelPath: s.kernelPath,
+			chrootBaseDir: s.chrootBaseDir,
+			uid: s.uid,
+			gid: s.gid,
+			vcpuCount: s.vcpuCount,
+			memSizeMib: s.memSizeMib,
+			bridgeName,
+			cidr,
+			gateway,
+			netmask,
+			table,
+			roles: s.roles,
+			requireSudo: s.requireSudo
+		});
+		counts[s.name] = await backend.cleanupOrphans();
+	}
+	return counts;
+}
+/**
+* Reap orphan container resources for every `container` scaler. Unlike the FC
+* reap, container cleanup is unconditional (it removes every kici-managed
+* container), so callers MUST ensure the orchestrator is NOT running before
+* invoking this — otherwise live agents are killed. The CLI command enforces
+* this via the /health gate.
+*/
+async function reapContainerOrphans(scalerConfig) {
+	const counts = {};
+	for (const s of scalerConfig.scalers) {
+		if (s.type !== "container") continue;
+		const backend = await ContainerScalerBackend.create({
+			name: s.name,
+			labelSets: s.labelSets,
+			maxAgents: s.maxAgents,
+			host: s.host,
+			socketPath: s.socketPath,
+			runtime: s.runtime
+		});
+		counts[s.name] = await backend.cleanupOrphans();
+	}
+	return counts;
+}
+/**
+* Reap orphans for all supported backends. Firecracker is always reaped
+* (liveness-driven, safe). Containers are reaped only when includeContainers
+* is set (caller has confirmed the orchestrator is down).
+*/
+async function reapAllOrphans(opts) {
+	const fc = await reapFirecrackerOrphans(opts.scalerConfig);
+	if (!opts.includeContainers) return fc;
+	const ct = await reapContainerOrphans(opts.scalerConfig);
+	return {
+		...fc,
+		...ct
+	};
+}
+//#endregion
+//#region src/cli/commands/scaler.ts
+/** Probe the local orchestrator /health endpoint. Healthy => it reaps itself. */
+async function isOrchestratorHealthy(port, basePath) {
+	const url = `http://127.0.0.1:${port}${basePath === "/" ? "" : basePath.replace(/\/$/, "")}/health`;
+	try {
+		return (await fetch(url, { signal: AbortSignal.timeout(2e3) })).status === 200;
+	} catch {
+		return false;
+	}
+}
+function registerScalerCommands(program) {
+	program.command("scaler").description("Scaler maintenance (local, no orchestrator)").command("reap-orphans").description("Free leaked Firecracker/container resources without a running orchestrator").option("--config <path>", "Path to the orchestrator config (default: KICI_CONFIG or /etc/kici/orchestrator.yaml)").option("--force", "Reap even if the local orchestrator reports healthy", false).option("--json", "Emit machine-readable JSON counts", false).action(async (opts) => {
+		try {
+			const local = await loadLocalConfig(opts.config);
+			const scalerConfigPath = local.scaler?.configPath ?? process.env.KICI_SCALER_CONFIG_PATH;
+			const scalerConfigDir = local.scaler?.configDir ?? process.env.KICI_SCALER_CONFIG_DIR;
+			if (!scalerConfigPath) {
+				console.error("Error: no scaler config path found (set scaler.configPath in the orchestrator config, KICI_SCALER_CONFIG_PATH in the environment, or pass --config)");
+				process.exit(1);
+			}
+			const scalerConfig = await loadScalerConfig(scalerConfigPath, scalerConfigDir);
+			const port = local.server?.port ?? Number(process.env.KICI_PORT ?? "4000");
+			const basePath = local.server?.basePath ?? process.env.KICI_BASE_PATH ?? "/";
+			if ((opts.force ? false : await isOrchestratorHealthy(port, basePath)) && !opts.force) {
+				const msg = "orchestrator is up and reaps orphans itself; pass --force to reap anyway";
+				if (opts.json) console.log(JSON.stringify({
+					skipped: true,
+					reason: "orchestrator-healthy",
+					counts: {}
+				}));
+				else console.log(msg);
+				process.exit(0);
+			}
+			const counts = await reapAllOrphans({
+				scalerConfig,
+				includeContainers: true
+			});
+			const total = Object.values(counts).reduce((a, b) => a + b, 0);
+			if (opts.json) console.log(JSON.stringify({
+				skipped: false,
+				counts,
+				total
+			}));
+			else if (total === 0) console.log("No orphan resources found.");
+			else {
+				console.log(`Reaped ${total} orphan resource(s):`);
+				for (const [name, n] of Object.entries(counts)) console.log(`  ${name}: ${n}`);
+			}
+		} catch (err) {
+			console.error(`Error: ${toErrorMessage(err)}`);
+			process.exit(1);
+		}
+	});
+}
+//#endregion
+//#region src/cluster/join-client.ts
+/**
+* Join client for zero-knowledge cluster bootstrap.
+*
+* Provides the joiner-side logic for `kici-admin join`:
+* 1. Connect to Platform relay (WS) or direct peer (HTTP POST)
+* 2. Send join.request with the join token
+* 3. Receive join.response with encrypted config bundle
+* 4. Decrypt bundle using token-derived AES-256-GCM key
+* 5. Write decrypted config as local YAML file
+*
+* The token carries routing info (cleartext for Platform relay) and a secret
+* (used for HKDF key derivation). Only the joiner and the token creator
+* can derive the encryption key -- the Platform relay sees only ciphertext.
+*/
+const logger = createLogger({ prefix: "join-client" });
+/**
+* Decrypt a base64-encoded encrypted config bundle using a derived encryption key.
+*/
+function decryptAndParseBundle(encryptedB64, encryptionKey) {
+	return decryptBundle(Buffer.from(encryptedB64, "base64"), encryptionKey);
+}
+/**
+* Build a JoinLocalConfig from a decrypted ConfigBundle.
+* Maps bundle fields to the structure expected by loadLocalConfig().
+*/
+function buildLocalConfig(bundle) {
+	const config = { database: { url: bundle.databaseUrl } };
+	if (bundle.storage) config.storage = bundle.storage;
+	if (bundle.secretKey) config.secrets = { key: bundle.secretKey };
+	return config;
+}
+/**
+* Write a local config object to a YAML file.
+*/
+async function writeConfigFile(path, config) {
+	await writeFile(path, stringify(config), "utf-8");
+}
+var JoinClient = class {
+	constructor(options) {
+		this.options = options;
+		if (!options.platformUrl && !options.peerUrl) throw new Error("Either --platform or --peer must be specified");
+		if (options.platformUrl && options.peerUrl) throw new Error("--platform and --peer are mutually exclusive");
+	}
+	/**
+	* Execute the join flow:
+	* 1. Send join.request with token to Platform relay or direct peer
+	* 2. Receive join.response with encrypted config bundle
+	* 3. Decrypt bundle using token-derived key
+	* 4. Write local config YAML
+	*/
+	async join() {
+		const request = {
+			type: "join.request",
+			token: this.options.token
+		};
+		logger.info("Sending join request...");
+		const response = this.options.platformUrl ? await this.joinViaPlatform(request) : await this.joinViaPeer(request);
+		if (!response.success) throw new Error(`Join rejected: ${response.error ?? "unknown error"}`);
+		if (!response.encryptedBundle) throw new Error("Join response missing encrypted bundle");
+		const parsed = parseToken(this.options.token);
+		const keys = deriveKeys(Buffer.from(parsed.secretHex, "hex"));
+		const bundle = decryptAndParseBundle(response.encryptedBundle, keys.encryptionKey);
+		logger.info("Join successful, writing config...", { clusterId: bundle.clusterId });
+		const localConfig = buildLocalConfig(bundle);
+		const configPath = this.options.configPath ?? "./kici-orchestrator.yaml";
+		await writeConfigFile(configPath, localConfig);
+		logger.info(`Config written to ${configPath}`);
+		logger.info("Start the orchestrator with: kici-admin orchestrator start");
+	}
+	/**
+	* Join via Platform relay: connect WS, authenticate, send join.request, receive join.response.
+	*/
+	async joinViaPlatform(request) {
+		const url = this.options.platformUrl;
+		const apiKey = this.options.apiKey;
+		if (!apiKey) throw new Error("--api-key is required for Platform relay mode");
+		const { default: WebSocket } = await import("ws");
+		return new Promise((resolve, reject) => {
+			const ws = new WebSocket(url, {
+				maxPayload: WS_MAX_PAYLOAD_BYTES,
+				perMessageDeflate: {
+					concurrencyLimit: 10,
+					threshold: 128
+				}
 			});
 			let authenticated = false;
 			let resolved = false;
@@ -13452,54 +16718,69 @@ function registerJoinCommand(program) {
 *   --url / -u    Orchestrator URL (env: KICI_ADMIN_URL, default: http://localhost:8080)
 *   --token / -t  Admin API token (env: KICI_ADMIN_TOKEN, required)
 */
-const program = new Command();
-program.name("kici-admin").description("KiCI orchestrator admin CLI for managing config, secrets, and tokens").version("0.0.1", "-V, --cli-version").option("-u, --url <url>", "Orchestrator URL", process.env.KICI_ADMIN_URL ?? "http://localhost:8080").option("-t, --token <token>", "Admin API token", process.env.KICI_ADMIN_TOKEN);
 /**
-* Create an AdminApiClient from global options.
-* Called lazily by each command to allow --help without requiring --token.
+* Build the kici-admin Commander program with every command group registered.
+* Exported so the surface registry can walk the real command tree without
+* parsing argv (no action runs during a tree walk, so `getClient` is
+* constructed but never invoked).
 */
-function getClient() {
-	const opts = program.opts();
-	if (!opts.token) {
-		console.error("Error: --token or KICI_ADMIN_TOKEN is required");
-		process.exit(1);
+function buildProgram() {
+	const program = new Command();
+	program.name("kici-admin").description("KiCI orchestrator admin CLI for managing config, secrets, and tokens").version("0.0.1", "-V, --cli-version").option("-u, --url <url>", "Orchestrator URL", process.env.KICI_ADMIN_URL ?? "http://localhost:8080").option("-t, --token <token>", "Admin API token", process.env.KICI_ADMIN_TOKEN);
+	/**
+	* Create an AdminApiClient from global options.
+	* Called lazily by each command to allow --help without requiring --token.
+	*/
+	function getClient() {
+		const opts = program.opts();
+		if (!opts.token) {
+			console.error("Error: --token or KICI_ADMIN_TOKEN is required");
+			process.exit(1);
+		}
+		return new AdminApiClient(opts.url, opts.token);
 	}
-	return new AdminApiClient(opts.url, opts.token);
-}
-registerSecretCommands(program, getClient);
-registerRotateCommand(program, getClient);
-registerAuditCommands(program, getClient);
-registerTokenCommands(program, getClient);
-registerAgentCommands(program, getClient);
-registerApiKeyCommands(program, getClient);
-registerConfigCommands(program, getClient);
-registerDbCommands(program, getClient);
-registerSourceCommands(program, getClient);
-registerWorkflowCommands(program, getClient);
-registerRunsCommands(program, getClient);
-registerEventLogCommands(program, getClient);
-registerAccessLogCommands(program, getClient);
-registerBackendCommands(program, getClient);
-registerDiagnoseCommand(program, getClient);
-registerDebugBundleCommand(program, getClient);
-registerInspectBundleCommand(program);
-registerOrchestratorServiceCommands(program);
-registerAgentServiceCommands(program);
-registerPeerCommands(program, getClient);
-registerOrgSettingsCommands(program, getClient);
-registerClusterNameCommands(program, getClient);
-registerMaintenanceCommands(program, getClient);
-registerEnvironmentCommands(program, getClient);
-registerVariableCommands(program, getClient);
-registerQueueCommands(program, getClient);
-registerExecutionCommands(program, getClient);
-registerRegistrationCommands(program, getClient);
-registerEventCommands(program, getClient);
-registerEventDlqCommands(program, getClient);
-registerColdStoreCommands(program, getClient);
-registerJoinCommand(program);
-program.parse();
-//#endregion
-export {};
+	registerSecretCommands(program, getClient);
+	registerRotateCommand(program, getClient);
+	registerAuditCommands(program, getClient);
+	registerTokenCommands(program, getClient);
+	registerAgentCommands(program, getClient);
+	registerApiKeyCommands(program, getClient);
+	registerConfigCommands(program, getClient);
+	registerDbCommands(program, getClient);
+	registerSourceCommands(program, getClient);
+	registerWorkflowCommands(program, getClient);
+	registerRunsCommands(program, getClient);
+	registerEventLogCommands(program, getClient);
+	registerAccessLogCommands(program, getClient);
+	registerBackendCommands(program, getClient);
+	registerDiagnoseCommand(program, getClient);
+	registerDebugBundleCommand(program, getClient);
+	registerInspectBundleCommand(program);
+	registerOrchestratorServiceCommands(program);
+	registerFirecrackerCommands(program);
+	registerScalerCommands(program);
+	registerAgentServiceCommands(program);
+	registerPeerCommands(program, getClient);
+	registerOrgSettingsCommands(program, getClient);
+	registerClusterNameCommands(program, getClient);
+	registerMaintenanceCommands(program, getClient);
+	registerEnvironmentCommands(program, getClient);
+	registerVariableCommands(program, getClient);
+	registerQueueCommands(program, getClient);
+	registerExecutionCommands(program, getClient);
+	registerRegistrationCommands(program, getClient);
+	registerEventCommands(program, getClient);
+	registerEventDlqCommands(program, getClient);
+	registerColdStoreCommands(program, getClient);
+	registerJoinCommand(program);
+	return program;
+}
+/** Build the program and parse argv — the bin-shim entry point. */
+function runCli(argv = process.argv) {
+	buildProgram().parse(argv);
+}
+if (resolve(process.argv[1] ?? "") === fileURLToPath(import.meta.url)) runCli();
+//#endregion
+export { buildProgram, runCli };
 
 //# sourceMappingURL=cli.js.map