@kici-dev/orchestrator 0.1.26 → 0.2.0

package/dist/routes/admin-contexts.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Admin API routes for context management.
+ *
+ *   POST   /api/v1/admin/contexts                                    — create (upsert)
+ *   POST   /api/v1/admin/contexts/:name/bind                         — bind a scope pattern
+ *   PATCH  /api/v1/admin/contexts/:name/policy                       — update policy fields
+ *   GET    /api/v1/admin/contexts?orgId=<id>                         — list contexts
+ *   GET    /api/v1/admin/contexts/:name?orgId=<id>                   — show env + vars + bindings
+ *   DELETE /api/v1/admin/contexts/:name?orgId=<id>                   — delete env (cascades bindings/variables/overrides; pending held runs block with 409)
+ *   POST   /api/v1/admin/contexts/templates                          — create/update a template
+ *   GET    /api/v1/admin/contexts/:name/variables?orgId=<id>         — list org-level variables
+ *   PUT    /api/v1/admin/contexts/:name/variables/:key?orgId=<id>    — upsert variable
+ *   DELETE /api/v1/admin/contexts/:name/variables/:key?orgId=<id>    — delete variable
+ *
+ * Backs the `kici-admin context` dual-mode CLI. Offline (direct-DB) mode
+ * bypasses this router entirely — the CLI calls `*Direct` helpers from
+ * @kici-dev/shared. This HTTP surface exists so tooling with only an admin
+ * token (no DB reach) can do the same operations.
+ *
+ * All routes are protected by the admin auth middleware mounted in admin.ts
+ * (at `/api/v1/admin/*`). That middleware sets `role` + `userId` on the
+ * context, which we use for RBAC gating here.
+ */
+import { Hono } from 'hono';
+import { type Kysely } from 'kysely';
+import type { RbacEnforcer, Role } from '../secrets/rbac.js';
+export interface AdminContextRoutesDeps {
+    db: Kysely<any>;
+    rbac: RbacEnforcer;
+}
+/** Hono env type for admin-contexts routes with context variables. */
+type AdminEnvEnv = {
+    Variables: {
+        role: Role;
+        userId: string;
+        routingKey: string | null;
+    };
+};
+/**
+ * Create admin API routes for context management.
+ *
+ * @param deps - db (Kysely) + rbac enforcer
+ * @returns Hono app mounted at /api/v1/admin
+ */
+export declare function createAdminContextRoutes(deps: AdminContextRoutesDeps): Hono<AdminEnvEnv>;
+export {};
+//# sourceMappingURL=admin-contexts.d.ts.map

package/dist/routes/admin-events.d.ts

@@ -16,6 +16,7 @@ import type { RbacEnforcer, Role } from '../secrets/rbac.js';
 import type { AppConfig } from '../config.js';
 import type { ProviderRegistry } from '../provider-registry.js';
 import type { SecretResolver } from '../secrets/secret-resolver.js';
+import type { ClusterSettingsReader } from '../cluster/cluster-settings-reader.js';
 /**
  * Dependencies for admin event routes.
  */
@@ -38,6 +39,8 @@ interface AdminEventRouteDeps {
     /** Required for universal-git source registration — `null` is allowed;
      *  rows with `git_config` are skipped + metric-bumped in that case. */
     secretResolver: SecretResolver | null;
+    /** Fleet-wide settings reader; threads the live lock-file cap into newly-registered universal-git sources. */
+    clusterSettings?: ClusterSettingsReader;
     /**
      * Optional — when provided, the `POST /api/v1/admin/events/emit` route is
      * mounted so operators can INSERT into `kici_events` + `pg_notify` via HTTP.

package/dist/routes/admin-orchestrator-drain.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Orchestrator drain admin routes.
+ *
+ * Backs the `kici-admin orchestrator drain` / `resume` / `drain --status`
+ * verbs used to quiesce a coordinator before an upgrade. Mounted inside
+ * `createAdminRoutes` at `/api/v1/admin/orchestrator/drain`, so it inherits the
+ * Bearer-token auth middleware (which resolves the caller's role) and gates on
+ * the `orchestrator.drain` RBAC permission (owner + admin).
+ *
+ * - `GET  /api/v1/admin/orchestrator/drain` → current `{ draining, jobsRunning }`.
+ * - `POST /api/v1/admin/orchestrator/drain { action: 'drain' | 'resume' }` →
+ *   flips the drain flag and returns the new snapshot.
+ */
+import { Hono } from 'hono';
+import { z } from 'zod';
+import type { DrainController } from '../drain/drain-controller.js';
+import type { RbacEnforcer, Role } from '../secrets/rbac.js';
+export declare const DrainActionSchema: z.ZodEnum<{
+    drain: "drain";
+    resume: "resume";
+}>;
+export type DrainAction = z.infer<typeof DrainActionSchema>;
+type AdminEnv = {
+    Variables: {
+        role: Role;
+        userId: string;
+        routingKey: string | null;
+    };
+};
+export declare function createOrchestratorDrainRoutes(deps: {
+    drainController: DrainController;
+    rbac: RbacEnforcer;
+}): Hono<AdminEnv>;
+export {};
+//# sourceMappingURL=admin-orchestrator-drain.d.ts.map

package/dist/routes/admin-registrations.d.ts

@@ -10,7 +10,7 @@ import type { RegistrationStore } from '../registration/registration-store.js';
 import type { RegistrationIndex } from '../registration/registration-index.js';
 import type { TokenManager } from '../secrets/token-manager.js';
 import type { RbacEnforcer, Role } from '../secrets/rbac.js';
-import type { EnvironmentStore } from '../environments/environment-store.js';
+import type { ContextStore } from '../contexts/context-store.js';
 /**
  * Dependencies for admin registration routes.
  */
@@ -25,7 +25,7 @@ export interface AdminRegistrationRoutesDeps {
      * provably-unsatisfiable environment list (missing/disabled env, or
      * mutually-exclusive fixed branch/trigger/repo restrictions).
      */
-    environmentStore?: Pick<EnvironmentStore, 'matchEnvironment'>;
+    contextStore?: Pick<ContextStore, 'matchContext'>;
 }
 /** Hono env type for admin registration routes with context variables. */
 type AdminRegEnv = {

package/dist/routes/admin-runs.d.ts

@@ -25,6 +25,15 @@ import type { TokenManager } from '../secrets/token-manager.js';
 import type { RbacEnforcer, Role } from '../secrets/rbac.js';
 import type { AuditLogger } from '../secrets/audit-logger.js';
 import type { LogStorage } from '../reporting/log-storage.js';
+/**
+ * Statuses accepted by the `?status=` filter.
+ *
+ * The full canonical union rather than just `ExecutionRunStatus.options`: only
+ * run statuses can appear in `execution_runs.status`, but the job-only members
+ * were accepted before and simply match no row, so keeping them avoids turning
+ * an empty result into a rejected request.
+ */
+export declare const RUN_STATUSES: ReadonlySet<string>;
 /**
  * Dependencies for admin run routes.
  */

package/dist/routes/admin-sources.d.ts

@@ -9,6 +9,7 @@
  * the admin auth middleware in admin.ts.
  */
 import { Hono } from 'hono';
+import { OrchestratorMode } from '@kici-dev/engine';
 import type { SourceStore } from '../sources/source-store.js';
 import type { Role } from '../secrets/rbac.js';
 import { type FetchGithubAppIdentity } from '../github-app-name-refresher/github-app-name-refresher.js';
@@ -46,6 +47,12 @@ interface SourceRouteDeps {
      * `source refresh` route.
      */
     fetchAppIdentity?: FetchGithubAppIdentity;
+    /**
+     * Orchestrator operating mode. `observed` refuses GitHub-App source creation:
+     * those sources are ingested through the Platform relay, and an observed
+     * orchestrator never accepts a relay. Omitted (undefined) behaves as before.
+     */
+    mode?: OrchestratorMode;
 }
 type AdminSourcesEnv = {
     Variables: {

package/dist/routes/admin-trust-policy.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Admin API routes for the org trust policy.
+ *
+ * Exposes GET / PATCH `/api/v1/admin/trust-policy` so `kici-admin` can read the
+ * enforced policy and, on an independent orchestrator, set it.
+ *
+ * The policy is Platform-owned wherever a Platform is attached: the Platform
+ * pushes it on `trust_policy.update` and the next push would clobber a local
+ * write. PATCH therefore refuses on any Platform-attached orchestrator, and the
+ * refusal is server-side so it cannot be bypassed by calling the API directly.
+ */
+import { Hono } from 'hono';
+import type { OrchestratorMode } from '@kici-dev/engine';
+import type { TrustPolicyStore } from '../security/trust-policy-store.js';
+import type { RbacEnforcer, Role } from '../secrets/rbac.js';
+import type { AccessLogWriter } from '../audit/access-log.js';
+/**
+ * Wording for the Platform-managed refusal. Shared with the CLI through the
+ * response body — the CLI surfaces this verbatim rather than inventing its own.
+ */
+export declare const PLATFORM_MANAGED_MESSAGE: string;
+interface TrustPolicyRouteDeps {
+    store: TrustPolicyStore;
+    rbac: RbacEnforcer;
+    /** This orchestrator's mode; decides whether PATCH is permitted at all. */
+    mode: OrchestratorMode;
+    /**
+     * Audit sink for the PATCH, written inside the policy transaction.
+     *
+     * REQUIRED, not optional. The guarantee this route makes is that a loosened
+     * `forkPolicy` can never land unattributed; an optional sink would leave that
+     * resting on every construction site remembering to pass one, and a route
+     * built without one would accept the write and silently skip the audit. A
+     * required dependency moves the guarantee from convention to the compiler —
+     * and `admin.ts` skips mounting the route entirely rather than mounting an
+     * unauditable one.
+     */
+    accessLog: AccessLogWriter;
+}
+type AdminEnv = {
+    Variables: {
+        role: Role;
+        userId: string;
+        routingKey: string | null;
+    };
+};
+export declare function createTrustPolicyRoutes(deps: TrustPolicyRouteDeps): Hono<AdminEnv>;
+export {};
+//# sourceMappingURL=admin-trust-policy.d.ts.map

package/dist/routes/admin.d.ts

@@ -16,11 +16,12 @@ import type { AuditLogger } from '../secrets/audit-logger.js';
 import type { AgentTokenStore } from '../agent/token-store.js';
 import type { AgentRegistry } from '../agent/registry.js';
 import type { SharedConfigStore } from '../config/shared-store.js';
+import type { DrainController } from '../drain/drain-controller.js';
 import type { SourceStore } from '../sources/source-store.js';
 import type { JoinTokenManager } from '../cluster/join-token.js';
 import type { BackendRegistry } from '../secrets/backend-registry.js';
 import type { BackendHealthChecker } from '../secrets/backend-health.js';
-import type { BackendSyncManager } from '@kici-dev/engine';
+import type { BackendSyncManager, OrchestratorMode } from '@kici-dev/engine';
 import type { Kysely } from 'kysely';
 import type pg from 'pg';
 import type { AccessLogWriter } from '../audit/access-log.js';
@@ -29,9 +30,22 @@ import type { AccessLogWriter } from '../audit/access-log.js';
  */
 export interface AdminRouteDeps {
     tokenManager: TokenManager;
+    /**
+     * Orchestrator operating mode. Gates mode-specific admin behavior — today the
+     * `observed`-mode refusal of GitHub-App source creation (those sources are
+     * Platform-relayed by nature, and an observed orchestrator never accepts a
+     * relay). Optional so WS-only / test admins can omit it.
+     */
+    mode?: OrchestratorMode;
     rbac: RbacEnforcer;
     secretStore: PgSecretStore;
     auditLogger: AuditLogger;
+    /**
+     * Optional -- the coordinator drain controller. When provided, the
+     * `POST`/`GET /api/v1/admin/orchestrator/drain` routes are mounted (backing
+     * the `kici-admin orchestrator drain` verbs). Omitted on WS-only admins.
+     */
+    drainController?: DrainController;
     /** Optional -- for agent token CRUD endpoints. */
     tokenStore?: AgentTokenStore;
     /**

package/dist/routes/github-webhook.d.ts

@@ -1,6 +1,8 @@
 import { Hono } from 'hono';
+import type { OrchestratorMode } from '@kici-dev/engine';
 import type { WebhookInfo } from '../webhook/handler.js';
 import type { SourceStore } from '../sources/source-store.js';
+import type { ClusterSettingsReader } from '../cluster/cluster-settings-reader.js';
 import { type VerifyInboundDeps } from '../webhook/verify-inbound.js';
 import { WebhookIngestOutcome } from '../pipeline/process-webhook.js';
 /** Dependencies for the direct GitHub webhook ingress route. */
@@ -11,13 +13,17 @@ export interface GithubWebhookRoutesDeps {
     verifyDeps: VerifyInboundDeps;
     /** Pipeline entry — owns the atomic dedup claim + dispatch. */
     onWebhook: (info: WebhookInfo) => Promise<WebhookIngestOutcome>;
+    /** Fleet-wide settings reader; overrides the payload cap per request. */
+    clusterSettings?: ClusterSettingsReader;
+    /** Cluster default payload cap (bytes) when no cluster_settings override is set. */
+    maxGithubPayloadBytes?: number;
 }
 /**
  * Whether the orchestrator serves the direct GitHub ingress route for a given
- * operating mode. Hybrid + independent run local source config; platform mode
- * is relay-only (no local GitHub source to serve).
+ * operating mode. Hybrid, independent, and observed modes serve their own
+ * ingress; platform mode is relay-only (no local GitHub source to serve).
  */
-export declare function shouldServeGithubIngress(mode: 'platform' | 'hybrid' | 'independent'): boolean;
+export declare function shouldServeGithubIngress(mode: OrchestratorMode): boolean;
 /**
  * Direct GitHub-App webhook ingress: `POST /webhook/:orgId/github/:sourceId`.
  *

package/dist/routes/provenance-oidc.d.ts

@@ -0,0 +1,38 @@
+import { Hono } from 'hono';
+import type { OrchestratorSigningKeyRepo } from '../db/repos/signing-keys-repo.js';
+import type { DashboardEncryptionKeyRepo } from '../db/repos/dashboard-encryption-keys-repo.js';
+/** OIDC discovery document for the orchestrator provenance issuer. */
+export interface OpenidConfiguration {
+    issuer: string;
+    jwks_uri: string;
+    id_token_signing_alg_values_supported: string[];
+    response_types_supported: string[];
+    subject_types_supported: string[];
+    claims_supported: string[];
+}
+/** Build the `/.well-known/openid-configuration` document for the orchestrator issuer. */
+export declare function buildOpenidConfiguration(issuer: string): OpenidConfiguration;
+export interface ProvenanceOidcRoutesDeps {
+    /** The orchestrator's own provenance issuer (config.provenanceSigningIssuer). */
+    issuer: string | undefined;
+    repo: Pick<OrchestratorSigningKeyRepo, 'listTrusted'>;
+    /** Whether orchestrator-owned signing is configured. */
+    enabled: boolean;
+    /**
+     * Dashboard-encryption key repo. When present, the JWKS additionally serves
+     * the non-revoked X25519 `use:'enc'` key(s) for browser-sealed dashboard
+     * writes (the Verified tier's trust root). Independent of provenance signing.
+     */
+    dashboardEncryptionRepo?: Pick<DashboardEncryptionKeyRepo, 'listNonRevoked'>;
+}
+/**
+ * Public, unauthenticated OIDC discovery + JWKS endpoints for the orchestrator
+ * provenance issuer. Serves ONLY the public key halves (safe to expose).
+ *
+ * The discovery document returns 503 when orchestrator-owned signing is not
+ * configured. The JWKS does not: it also carries the X25519 dashboard-encryption
+ * key, which is unrelated to build attestations, and returns 503 only when there
+ * is no key of either kind to publish.
+ */
+export declare function createProvenanceOidcRoutes(deps: ProvenanceOidcRoutesDeps): Hono;
+//# sourceMappingURL=provenance-oidc.d.ts.map

package/dist/routes/verify-attestation.d.ts

@@ -0,0 +1,21 @@
+import { Hono } from 'hono';
+import type { OrchestratorSigningKeyRepo } from '../db/repos/signing-keys-repo.js';
+export interface VerifyAttestationRoutesDeps {
+    /** The orchestrator's own provenance issuer (config.provenanceSigningIssuer). */
+    issuer: string | undefined;
+    repo: Pick<OrchestratorSigningKeyRepo, 'listTrusted'>;
+    /** Whether orchestrator-owned signing is configured. */
+    enabled: boolean;
+}
+/**
+ * Native online verify endpoint: a third party POSTs a bundle and the
+ * orchestrator verifies it against its LIVE key set (fresh rotations /
+ * revocations included), returning a structured verdict. No Platform involved.
+ *
+ * The token `iss` is ALWAYS pinned out-of-band to the orchestrator's configured
+ * issuer — the bundle can never name its own trusted issuer. Never throws on a
+ * verification failure (returns `verified:false`); the shared engine core owns
+ * all crypto (ES256 pinned; no alg-confusion / alg:none).
+ */
+export declare function createVerifyAttestationRoutes(deps: VerifyAttestationRoutesDeps): Hono;
+//# sourceMappingURL=verify-attestation.d.ts.map

package/dist/scaler/bare-metal-backend.d.ts

@@ -7,7 +7,7 @@
  */
 import { type ToolRequirement } from '@kici-dev/shared';
 import type { AgentTokenStore } from '../agent/token-store.js';
-import type { ScalerBackend, ScalerEntry, ManagedAgent, LabelSetConfig, LogCapture, ResourceRequest, ScalerEventCallback, ValidationResult, EffectiveLimits } from './types.js';
+import type { ScalerBackend, ScalerEntry, ManagedAgent, LabelSetConfig, LogCapture, ResourceRequest, ScalerEventCallback, ValidationResult, EffectiveLimits, SpawnContext } from './types.js';
 export interface BareMetalScalerBackendOptions {
     /** Human-readable name for this scaler */
     name: string;
@@ -21,6 +21,12 @@ export interface BareMetalScalerBackendOptions {
     tokenStore?: AgentTokenStore;
     /** TTL for ephemeral agent tokens in ms. Default: 1 hour. */
     tokenTtlMs?: number;
+    /**
+     * Live resolver for the ephemeral agent-token TTL (ms). When set, called per
+     * spawn so the leader can serve the fleet-wide
+     * `cluster_settings.agent_token_ttl_ms` override; falls back to `tokenTtlMs`.
+     */
+    tokenTtlProvider?: () => Promise<number>;
     /** Agent roles for this scaler. undefined = all, [] = execution only. */
     roles?: string[];
     /**
@@ -47,6 +53,7 @@ export declare class BareMetalScalerBackend implements ScalerBackend {
     private readonly defaultResources?;
     private readonly tokenStore?;
     private readonly tokenTtlMs;
+    private readonly tokenTtlProvider?;
     private readonly roles;
     private readonly enforceCgroups;
     /** Tracks all managed agent processes */
@@ -72,7 +79,7 @@ export declare class BareMetalScalerBackend implements ScalerBackend {
     static getRequiredTools(entry: ScalerEntry): ToolRequirement[];
     get labelSets(): LabelSetConfig[];
     getActiveCount(): number;
-    spawn(labelSet: string[], agentId: string, orchestratorUrl: string, onEvent?: ScalerEventCallback, effectiveLimits?: EffectiveLimits): Promise<ManagedAgent>;
+    spawn(labelSet: string[], agentId: string, orchestratorUrl: string, onEvent?: ScalerEventCallback, effectiveLimits?: EffectiveLimits, _spawnContext?: SpawnContext, _signal?: AbortSignal): Promise<ManagedAgent>;
     getScalerContext(agentId: string): Record<string, unknown> | undefined;
     destroy(managedId: string): Promise<void>;
     /**

package/dist/scaler/config.d.ts

@@ -9,6 +9,13 @@
  */
 import { z } from 'zod';
 import type { ScalerConfig } from './types.js';
+/**
+ * Default cap on concurrent `backend.spawn` operations per backend when a
+ * scaler entry does not set `maxConcurrentSpawns`. Bounds the provisioning rate
+ * (image pull + create + start) so a burst of queued jobs cannot storm the
+ * container socket / registry.
+ */
+export declare const DEFAULT_MAX_CONCURRENT_SPAWNS = 8;
 /**
  * Zod schema for network policy configuration on a label set.
  * Controls RFC1918 and internet access for spawned agents.
@@ -67,8 +74,8 @@ export declare const labelSetConfigSchema: z.ZodObject<{
     containerSocket: z.ZodDefault<z.ZodBoolean>;
     env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
     backpressureMode: z.ZodOptional<z.ZodEnum<{
-        pause: "pause";
         drop: "drop";
+        pause: "pause";
     }>>;
     networkPolicy: z.ZodOptional<z.ZodObject<{
         allowlist: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -90,6 +97,7 @@ export declare const firecrackerNetworkSchema: z.ZodObject<{
     gateway: z.ZodDefault<z.ZodString>;
     netmask: z.ZodDefault<z.ZodString>;
     table: z.ZodDefault<z.ZodString>;
+    autoProvisionHost: z.ZodDefault<z.ZodBoolean>;
 }, z.core.$strip>;
 /**
  * Zod schema for the complete scaler configuration file.
@@ -160,11 +168,12 @@ export declare const scalerFileSchema: z.ZodObject<{
     scalers: z.ZodArray<z.ZodObject<{
         name: z.ZodString;
         type: z.ZodEnum<{
-            container: "container";
             "bare-metal": "bare-metal";
+            container: "container";
             firecracker: "firecracker";
         }>;
         maxAgents: z.ZodNumber;
+        maxConcurrentSpawns: z.ZodDefault<z.ZodNumber>;
         labelSets: z.ZodArray<z.ZodObject<{
             labels: z.ZodArray<z.ZodString>;
             image: z.ZodOptional<z.ZodString>;
@@ -212,8 +221,8 @@ export declare const scalerFileSchema: z.ZodObject<{
             containerSocket: z.ZodDefault<z.ZodBoolean>;
             env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
             backpressureMode: z.ZodOptional<z.ZodEnum<{
-                pause: "pause";
                 drop: "drop";
+                pause: "pause";
             }>>;
             networkPolicy: z.ZodOptional<z.ZodObject<{
                 allowlist: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -228,9 +237,9 @@ export declare const scalerFileSchema: z.ZodObject<{
         host: z.ZodOptional<z.ZodString>;
         socketPath: z.ZodOptional<z.ZodString>;
         runtime: z.ZodDefault<z.ZodEnum<{
+            auto: "auto";
             docker: "docker";
             podman: "podman";
-            auto: "auto";
         }>>;
         orchestratorUrl: z.ZodOptional<z.ZodString>;
         extraHosts: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -241,6 +250,17 @@ export declare const scalerFileSchema: z.ZodObject<{
             idleTimeoutSeconds: z.ZodDefault<z.ZodNumber>;
         }, z.core.$strip>>;
         mandatoryLabels: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        platform: z.ZodOptional<z.ZodObject<{
+            os: z.ZodEnum<{
+                linux: "linux";
+                macos: "macos";
+                windows: "windows";
+            }>;
+            arch: z.ZodEnum<{
+                arm64: "arm64";
+                x64: "x64";
+            }>;
+        }, z.core.$strict>>;
         roles: z.ZodPipe<z.ZodOptional<z.ZodArray<z.ZodEnum<{
             all: "all";
             builder: "builder";
@@ -274,6 +294,7 @@ export declare const scalerFileSchema: z.ZodObject<{
         gateway: z.ZodDefault<z.ZodString>;
         netmask: z.ZodDefault<z.ZodString>;
         table: z.ZodDefault<z.ZodString>;
+        autoProvisionHost: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strip>>;
 }, z.core.$strip>;
 /**

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

@@ -44,6 +44,12 @@ export interface ContainerScalerBackendOptions {
     tokenStore?: AgentTokenStore;
     /** TTL for ephemeral agent tokens in ms. Default: 1 hour. */
     tokenTtlMs?: number;
+    /**
+     * Live resolver for the ephemeral agent-token TTL (ms). When set, called per
+     * spawn so the leader can serve the fleet-wide
+     * `cluster_settings.agent_token_ttl_ms` override; falls back to `tokenTtlMs`.
+     */
+    tokenTtlProvider?: () => Promise<number>;
     /** Agent roles for this scaler. undefined = all, [] = execution only. */
     roles?: string[];
 }
@@ -67,6 +73,8 @@ export declare class ContainerScalerBackend implements ScalerBackend {
     private readonly tokenStore?;
     /** TTL for ephemeral agent tokens in ms */
     private readonly tokenTtlMs;
+    /** Live per-spawn resolver for the ephemeral agent-token TTL (ms). */
+    private readonly tokenTtlProvider?;
     /** Agent roles for this scaler. undefined = all, [] = execution only. */
     private readonly roles;
     /** ID of the isolated bridge network (set after creation/discovery) */
@@ -113,7 +121,7 @@ export declare class ContainerScalerBackend implements ScalerBackend {
     get logsSource(): string;
     get labelSets(): LabelSetConfig[];
     getActiveCount(): number;
-    spawn(labelSet: string[], agentId: string, orchestratorUrl: string, onEvent?: ScalerEventCallback, effectiveLimits?: EffectiveLimits, spawnContext?: SpawnContext): Promise<ManagedAgent>;
+    spawn(labelSet: string[], agentId: string, orchestratorUrl: string, onEvent?: ScalerEventCallback, effectiveLimits?: EffectiveLimits, spawnContext?: SpawnContext, signal?: AbortSignal): Promise<ManagedAgent>;
     getScalerContext(agentId: string): Record<string, unknown> | undefined;
     destroy(managedId: string): Promise<void>;
     /**

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

@@ -19,7 +19,8 @@
 import { type ToolRequirement } from '@kici-dev/shared';
 import type { IpAllocator, IpAllocationResult } from './ip-allocator.js';
 import type { AgentTokenStore } from '../agent/token-store.js';
-import type { ScalerBackend, ScalerEntry, ManagedAgent, LabelSetConfig, ScalerEventCallback, ValidationResult, EffectiveLimits } from './types.js';
+import { type FirecrackerBridgeConfig, type BridgeHealth, type ExecOptions } from '../firecracker/host-network.js';
+import type { ScalerBackend, ScalerEntry, ManagedAgent, LabelSetConfig, ScalerEventCallback, ValidationResult, EffectiveLimits, SpawnContext } from './types.js';
 /**
  * Infrastructure interfaces that share the `kici-` prefix but must NEVER be
  * deleted by the orphan sweep. Bridges (kici-br0/kici-br1) carry all VM
@@ -73,6 +74,12 @@ export interface FirecrackerScalerBackendOptions {
     tokenStore?: AgentTokenStore;
     /** TTL for ephemeral agent tokens in ms. Default: 1 hour. */
     tokenTtlMs?: number;
+    /**
+     * Live resolver for the ephemeral agent-token TTL (ms). When set, called per
+     * spawn so the leader can serve the fleet-wide
+     * `cluster_settings.agent_token_ttl_ms` override; falls back to `tokenTtlMs`.
+     */
+    tokenTtlProvider?: () => Promise<number>;
     /** Agent roles for this scaler. undefined = all, [] = execution only. */
     roles?: string[];
     /**
@@ -83,6 +90,16 @@ export interface FirecrackerScalerBackendOptions {
      * @default false
      */
     requireSudo?: boolean;
+    /**
+     * When true, `ensureHostReady()` verifies and provisions this host bridge on
+     * startup (self-heal). Threaded from `firecracker.autoProvisionHost`. When
+     * false the method is a no-op. @default false (cores pass the real value)
+     */
+    autoProvisionHost?: boolean;
+    /** Injectable bridge verifier (tests). @default host-network verifyBridge */
+    verifyBridgeFn?: (cfg: FirecrackerBridgeConfig, opts: ExecOptions) => Promise<BridgeHealth>;
+    /** Injectable bridge provisioner (tests). @default host-network provisionBridge */
+    provisionBridgeFn?: (cfg: FirecrackerBridgeConfig, opts: ExecOptions) => Promise<void>;
 }
 export declare class FirecrackerScalerBackend implements ScalerBackend {
     readonly type: "firecracker";
@@ -109,8 +126,12 @@ export declare class FirecrackerScalerBackend implements ScalerBackend {
     private readonly table;
     private readonly tokenStore?;
     private readonly tokenTtlMs;
+    private readonly tokenTtlProvider?;
     private readonly roles;
     private readonly requireSudo;
+    private readonly autoProvisionHost;
+    private readonly verifyBridgeFn;
+    private readonly provisionBridgeFn;
     /** Tracks all managed VM agents by ManagedAgent.id */
     private readonly agents;
     /** Periodic orphan sweep timer (null when stopped). */
@@ -124,7 +145,7 @@ export declare class FirecrackerScalerBackend implements ScalerBackend {
     static getRequiredTools(entry: ScalerEntry): ToolRequirement[];
     get labelSets(): LabelSetConfig[];
     getActiveCount(): number;
-    spawn(labelSet: string[], agentId: string, orchestratorUrl: string, onEvent?: ScalerEventCallback, effectiveLimits?: EffectiveLimits): Promise<ManagedAgent>;
+    spawn(labelSet: string[], agentId: string, orchestratorUrl: string, onEvent?: ScalerEventCallback, effectiveLimits?: EffectiveLimits, _spawnContext?: SpawnContext, _signal?: AbortSignal): Promise<ManagedAgent>;
     getScalerContext(agentId: string): Record<string, unknown> | undefined;
     /**
      * Bridge config for host-network diagnostics (read-only snapshot).
@@ -138,6 +159,12 @@ export declare class FirecrackerScalerBackend implements ScalerBackend {
         bridgeCidr: string;
         table: string;
     };
+    /**
+     * Verify and (if needed) provision this backend's host bridge on startup.
+     * No-op unless autoProvisionHost is set. Throws on a real provision failure;
+     * ScalerManager.ensureHostsReady catches per-backend and degrades this scaler.
+     */
+    ensureHostReady(): Promise<void>;
     destroy(managedId: string): Promise<void>;
     shutdownAll(): Promise<void>;
     /**

package/dist/scaler/index.d.ts

@@ -5,7 +5,7 @@
  * Supports Docker, bare-metal, and Firecracker backends with YAML configuration,
  * label-set matching, and warm pool management.
  */
-export type { ResourceLimits, LabelSetConfig, ManagedAgent, ScaleResult, ValidationResult, ScalerBackend, ScalerConfig, ScalerEntry, ScalerEvent, WarmPoolConfig, FirecrackerNetworkConfig, } from './types.js';
+export type { ResourceLimits, LabelSetConfig, ManagedAgent, ScaleResult, ValidationResult, ScalerBackend, ScalerConfig, ScalerEntry, ScalerEvent, ScalerRedispatchTrigger, WarmPoolConfig, FirecrackerNetworkConfig, } from './types.js';
 export { loadScalerConfig, scalerFileSchema, firecrackerNetworkSchema, parseMemoryString, } from './config.js';
 export { normalizeLabelSet, labelSetsMatch, detectLabelSetOverlaps, findBackendForLabels, } from './label-matcher.js';
 export { ContainerScalerBackend, detectRuntime } from './container-backend.js';