@kici-dev/orchestrator 0.5.0 → 0.6.1

package/dist/scaler/resolve-container-auth.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Resolve a job's container spec into something a runtime can pull with.
+ *
+ * The lock carries credential REFERENCES (`<context>:<secret-name>`), never
+ * material — so somebody has to turn those into an authconfig, and three call
+ * sites need the identical answer: the agent's container sandbox, the container
+ * scaler backend, and the bare-metal backend in container mode. One resolver
+ * keeps them from drifting into three subtly different readings of the same
+ * lock field.
+ */
+import type { LockJob } from '@kici-dev/engine';
+import type { ResolvedContainerSpawn } from './types.js';
+export type { ResolvedContainerSpawn };
+/** The `container` field as the lock carries it. */
+type LockContainer = LockJob['container'];
+export interface ResolveContainerSpawnDeps {
+    /**
+     * Resolve a qualified `<context>:<secret-name>` reference, or `undefined`
+     * when no such secret exists.
+     */
+    resolveSecret: (qualifiedRef: string) => Promise<string | undefined>;
+}
+/**
+ * Resolve just the registry credentials for a job's container.
+ *
+ * Split out of {@link resolveContainerSpawn} because the two consumers diverge
+ * for a dockerfile build: there is no image for the SCALER to spawn an agent
+ * from, but the AGENT still needs credentials to pull the Dockerfile's own
+ * `FROM` base.
+ *
+ * Returns `undefined` when the job declared no credentials at all.
+ */
+export declare function resolveContainerRegistryAuth(container: LockContainer, deps: ResolveContainerSpawnDeps): Promise<NonNullable<ResolvedContainerSpawn['authconfig']> | undefined>;
+/**
+ * Turn a lock `container` field into an image plus, when the job declared
+ * credentials, an authconfig for the registry that image lives in.
+ *
+ * Returns `undefined` for a job with no container at all — and for a job that
+ * BUILDS its image, because the scaler cannot spawn an agent from an image that
+ * does not exist yet. That job is run by an ordinary agent, which nests the
+ * container after it has cloned and built. So a caller can treat "no container",
+ * "container without auth" and "container built from a dockerfile" distinctly.
+ */
+export declare function resolveContainerSpawn(container: LockContainer, deps: ResolveContainerSpawnDeps): Promise<ResolvedContainerSpawn | undefined>;
+//# sourceMappingURL=resolve-container-auth.d.ts.map

package/dist/scaler/scaler-events.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Orchestrator-side entry point for the event scaler's event vocabulary.
+ *
+ * The schemas and constants themselves live in `@kici-dev/engine` so the SDK —
+ * the only KiCI package a workflow file may import — shares one source of truth
+ * with the emitting side. This module re-exports them (plus the reserved
+ * prefix) so orchestrator call sites keep a single local import for the whole
+ * vocabulary.
+ */
+export { KICI_EVENT_NAME_PREFIX, SCALER_EVENT_NAMES, ScaleDownReason, ScalerScaleUpPayload, ScalerScaleDownPayload, } from '@kici-dev/engine';
+//# sourceMappingURL=scaler-events.d.ts.map

package/dist/scaler/scaler-state-store.d.ts

@@ -1,9 +1,13 @@
-import type { Kysely } from 'kysely';
+import { type Kysely } from 'kysely';
 import type { Database } from '../db/types.js';
 import type { ScalerEvent } from './types.js';
 /**
  * Snapshot of a spawning-agent record. Mirrors the row shape in
  * `scaler_spawning_agents`.
+ *
+ * The ownership and self-describing fields are optional: a row written before a
+ * coordinator instance id was known carries none of them, and an absent
+ * `ownerInstanceId` means "unknown owner", never "owned by someone else".
  */
 export interface SpawningAgentSnapshot {
     agentId: string;
@@ -13,6 +17,82 @@ export interface SpawningAgentSnapshot {
     jobId?: string;
     boundJobId?: string;
     spawnedAt: Date;
+    /** The coordinator instance that spawned the agent. */
+    ownerInstanceId?: string;
+    /** The coordinator the agent actually reached when it registered. */
+    adoptedBy?: string;
+    /** When the adopting coordinator claimed the agent. */
+    adoptedAt?: Date;
+    /** The scaler's mandatory labels, copied onto the row at spawn time. */
+    mandatoryLabels?: string[];
+    /** The scaler's provisioning targets, copied onto the row at spawn time. */
+    provisioningTargets?: string[];
+    /** The scaler's roles, copied onto the row at spawn time. */
+    roles?: string[];
+    /** The scaler backend that spawned the agent. */
+    backendType?: string;
+}
+/** A pending provisioning claim, as written by the event scaler's claim store. */
+export interface PendingClaimRow {
+    claimHash: string;
+    claimPrefix: string;
+    agentId: string;
+    scalerName: string;
+    labels: string[];
+    agentTokenTtlMs: number;
+    orchestratorUrl: string;
+    expiresAt: Date;
+}
+/** What a successful `redeemClaim` returns. */
+export interface RedeemedClaim {
+    agentId: string;
+    labels: string[];
+    agentTokenTtlMs: number;
+    orchestratorUrl: string;
+}
+/**
+ * The critical section `withScalerCapLock` hands its caller: the scaler's
+ * cluster-wide spawn count, plus the one write that changes it.
+ */
+export interface ScalerCapSlot {
+    /**
+     * Live event-scaler spawn rows for this scaler across every coordinator.
+     * Read inside the advisory-locked transaction, so no other holder of the
+     * lock can change it while the caller decides.
+     */
+    clusterActiveCount: number;
+    /**
+     * Claim a slot by writing the spawn row in the same transaction the count
+     * was read in. Counting without claiming here bounds nothing: the spawn row
+     * is otherwise written well after the check, so every coordinator arriving
+     * in that window reads the same pre-spawn count and admits.
+     */
+    reserve(snapshot: SpawningAgentSnapshot): Promise<void>;
+}
+/** A row the event-provision reaper may need to tear down. */
+export interface ReapCandidate {
+    agentId: string;
+    scalerName: string;
+    provisioningTargets: string[];
+    ownerInstanceId?: string;
+    adoptedBy?: string;
+    /**
+     * When the provision was requested. The reaper ages every row on this and
+     * never on `adopted_at`: a coordinator that re-adopts its own agent refreshes
+     * `adopted_at`, so a restart loop on the adopter would keep resetting the
+     * clock on its own stranded provision and the row would never age out.
+     */
+    spawnedAt: Date;
+    /**
+     * The run this provision was spawned for, when it was job-bound. Carried so a
+     * teardown for a provision that never registered can be attributed back to the
+     * job that is still waiting on it — the reaper is leader-gated, so the
+     * coordinator that condemns the row is often not the one that spawned it and
+     * has no in-memory spawning entry to read the identity from.
+     */
+    runId?: string;
+    /** The queued job this provision was spawned for. Absent for a warm fill. */
+    boundJobId?: string;
 }
 /**
  * Snapshot of an agent-job correlation. Mirrors the row shape in
@@ -32,13 +112,18 @@ export interface ReservationSnapshot {
     scalerName: string;
     cpus: number;
     memBytes: number;
+    /**
+     * The coordinator instance holding the reservation. Absent means "unknown
+     * owner", never "held by someone else".
+     */
+    ownerInstanceId?: string;
 }
 /**
  * DB persistence for `ScalerManager` HA-critical state.
  *
- * Backed by three tables — `scaler_spawning_agents`, `scaler_agent_jobs`,
- * `scaler_reservations` — so a Raft leader switch / coord crash no
- * longer:
+ * Backed by four tables — `scaler_spawning_agents`, `scaler_agent_jobs`,
+ * `scaler_reservations`, `scaler_pending_claims` — so a Raft leader switch /
+ * coord crash no longer:
  *
  *  - orphans an agent that is mid-spawn (lost `boundJobId` → eager
  *    dispatch silently downgraded to a generic queue drain),
@@ -59,26 +144,225 @@ export interface ReservationSnapshot {
  * correlation are observability, not correctness. A coord crash before
  * `correlateAgentToJob()` runs accepts losing those events (see the
  * wishlist for the rationale).
+ *
+ * Ownership columns (`owner_instance_id`, `adopted_by`) let several
+ * coordinators behind one shared endpoint divide the same tables between them.
+ * A NULL owner means the owner is unknown — it never means "owned by another
+ * instance", so no query may read a NULL owner as somebody else's row.
+ */
+/**
+ * Postgres `lock_not_available`. Raised when the `lock_timeout` the cap
+ * transaction sets expires with the advisory lock still held elsewhere —
+ * a contended lock on a healthy database, which reads very differently from a
+ * database that could not be reached at all.
  */
+export declare const PG_LOCK_NOT_AVAILABLE = "55P03";
 export declare class ScalerStateStore {
     private readonly db;
-    constructor(db: Kysely<Database>);
+    private readonly lockWaitMs?;
+    /**
+     * `lockWaitMs` bounds how long `withScalerCapLock` waits to acquire the
+     * advisory lock. It is the orchestrator's existing `dbPoolAcquireTimeoutMs`
+     * — the same answer to "how long may a caller block waiting to get hold of a
+     * database resource before we fail" — not a timeout of its own. Omitted, the
+     * wait is unbounded except by `statement_timeout`, which is the behaviour a
+     * store built without it has always had.
+     */
+    constructor(db: Kysely<Database>, lockWaitMs?: number | undefined);
     upsertSpawningAgent(snapshot: SpawningAgentSnapshot): Promise<void>;
+    /**
+     * Run a cap check plus its slot claim for one scaler under a cluster-wide
+     * lock.
+     *
+     * `runWithReservationLock` in the manager is an in-process promise chain:
+     * correct within an instance, blind across them. For an event scaler that
+     * means N coordinators each provision up to `maxAgents` cloud instances, so
+     * the number an operator writes is not the number they are billed for. The
+     * advisory lock is transaction-scoped, so it releases on commit or rollback
+     * with no unlock path to leak.
+     *
+     * The count and the claim share the transaction on purpose — see
+     * `ScalerCapSlot.reserve`. `fn` therefore runs inside an open transaction:
+     * keep it short, and never await anything outside the database in it.
+     *
+     * READ COMMITTED is pinned rather than inherited. The lock is taken first
+     * and the count read second, so each statement needs its own snapshot for
+     * the second holder to see the first one's committed row. Under REPEATABLE
+     * READ the snapshot is taken at the FIRST statement — before the lock is
+     * granted — so both coordinators would read the same pre-claim count and
+     * both admit, reintroducing the exact defect this exists to close. Pinning
+     * it means a server-side `default_transaction_isolation` change cannot do
+     * that silently.
+     *
+     * A caller that cannot get the lock within `lockWaitMs` fails rather than
+     * queuing: the manager holds its process-wide reservation lock across this
+     * call, so an unbounded wait here stalls every other backend's scale
+     * request too.
+     */
+    withScalerCapLock<T>(scalerName: string, fn: (slot: ScalerCapSlot) => Promise<T> | T): Promise<T>;
     deleteSpawningAgent(agentId: string): Promise<void>;
+    /**
+     * Delete a spawning-agent row only while no instance has adopted it.
+     *
+     * The spawning instance is never told that a peer adopted its agent, so its
+     * in-memory entry survives adoption and its stale-entry prune fires five
+     * minutes later. An unconditional delete there would drop the row whose
+     * `adopted_by` is the only durable record of a live provision — and an
+     * adopted event agent legitimately runs for hours, so the reaper would find
+     * nothing to tear down if the adopting instance then died. The
+     * `adopted_by IS NULL` predicate keeps the prune to rows nobody claimed.
+     */
+    deleteUnadoptedSpawningAgent(agentId: string): Promise<void>;
+    /**
+     * The instance that adopted a provision, or null while nobody has.
+     *
+     * The counterpart read to `deleteUnadoptedSpawningAgent`'s predicate, for the
+     * caller that must not act rather than must not delete: the spawning instance
+     * is never told that a peer adopted its agent, so a stale in-memory entry is
+     * no evidence the provision failed.
+     *
+     * Reads the LIVE spawn row first and the durable outcome second, because the
+     * spawn row is deleted on teardown and its absence is ambiguous — it is both
+     * "never adopted" and "adopted, then torn down". The outcome row survives the
+     * delete and answers the second case positively.
+     *
+     * A provision with neither row still answers null, and the prune treats that
+     * as "no evidence" and reports — which is what a single coordinator wants and
+     * what keeps every coordinator backing off on a real provisioning outage. See
+     * `ScalerManager.reportPrunedProvisionFailure`.
+     */
+    provisionAdopter(agentId: string): Promise<string | null>;
+    /**
+     * Every spawning-agent row in the table, whoever owns it. Not for recovery —
+     * hydrating a peer's in-flight spawns as our own lets the spawn-timeout
+     * reaper destroy agents that peer is still waiting on. Recovery uses
+     * `listSpawningAgentsForOwner`.
+     */
     listSpawningAgents(): Promise<SpawningAgentSnapshot[]>;
     /**
-     * Delete every spawning-agent row whose `spawned_at` is older than the
-     * given cutoff. Used by the leader-gated GC sweep so a coord that
-     * crashed mid-spawn doesn't leave the row blocking the spawn-timeout
-     * detection forever. Returns the row count GC'd.
+     * Claim ownership of a spawning agent that registered on this instance.
+     * Conditional on the row being unclaimed **or already claimed by this same
+     * instance**, so exactly one instance adopts even if the agent flaps between
+     * instances behind a load balancer, while a re-registration on the adopter
+     * itself still resolves. Without the second arm a restart is a silent leak:
+     * recovery rehydrates the row, the stale-spawn prune drops the in-memory
+     * entry but spares the row, and the still-live agent's next registration
+     * finds neither — it reads as a static agent, so no `scale-down` is ever
+     * emitted and the reaper spares it because the agent is registered and its
+     * adopter is alive. Gated on `backend_type = 'event'`: a local-backend
+     * agent's compute is pinned to another host, so adopting its bookkeeping
+     * would be a lie.
+     *
+     * The adoption is also recorded in `scaler_provision_outcomes`, in the SAME
+     * transaction as the stamp. The spawn row is deleted on teardown, so its
+     * `adopted_by` is not a durable answer to "was this provision ever adopted?"
+     * — and the stale-spawn prune needs exactly that answer to tell a dead
+     * external provision from a healthy one it was not told about. Writing
+     * it here rather than at the two call sites is deliberate: this method is the
+     * single writer of `adopted_by`, so no adoption path can miss the record.
+     * Splitting the two writes would let a crash leave an adopted row whose
+     * adoption the prune cannot see, which is the very ambiguity being removed.
+     */
+    adoptSpawningAgent(agentId: string, instanceId: string): Promise<SpawningAgentSnapshot | null>;
+    /**
+     * Every spawning-agent row this instance owns. Scopes recovery so an instance
+     * rehydrates only its own bookkeeping. A row with a NULL `owner_instance_id`
+     * has an unknown owner and is deliberately not returned to anybody.
+     */
+    listSpawningAgentsForOwner(instanceId: string): Promise<SpawningAgentSnapshot[]>;
+    /**
+     * Every event row that is either past its spawn deadline without ever being
+     * adopted, or adopted by some instance. The reaper decides which to tear down;
+     * this only narrows the scan. Deliberately NOT a blanket `spawned_at < cutoff`
+     * delete: an adopted event agent legitimately runs for hours.
      */
-    sweepStaleSpawningAgents(olderThan: Date): Promise<number>;
+    listReapCandidates(spawnCutoff: Date): Promise<ReapCandidate[]>;
     upsertAgentJob(snapshot: AgentJobCorrelationSnapshot): Promise<void>;
     deleteAgentJob(agentId: string): Promise<void>;
     listAgentJobs(): Promise<AgentJobCorrelationSnapshot[]>;
     upsertReservation(snapshot: ReservationSnapshot): Promise<void>;
     deleteReservation(agentId: string): Promise<void>;
+    /**
+     * Every reservation row in the table, whoever holds it. Not for recovery —
+     * counting a peer's reservations against our own caps double-books the
+     * cluster. Recovery uses `listReservationsForOwner`.
+     */
     listReservations(): Promise<ReservationSnapshot[]>;
+    /**
+     * Every reservation this instance holds. Scopes recovery so an instance
+     * rehydrates only its own usage. A row with a NULL `owner_instance_id` has an
+     * unknown owner and is deliberately not returned to anybody.
+     */
+    listReservationsForOwner(instanceId: string): Promise<ReservationSnapshot[]>;
+    registerClaim(row: PendingClaimRow): Promise<void>;
+    /**
+     * Consume a claim and return its spec, or null when the code is unknown,
+     * already consumed, or expired. The UPDATE is the consumption: it commits
+     * before any mint is attempted, so two concurrent claims of one code — on the
+     * same instance or on different ones — can never both mint.
+     */
+    redeemClaim(claimHash: string): Promise<RedeemedClaim | null>;
+    /**
+     * Why a redeem failed. Called ONLY on the failure path, so the happy path
+     * stays one round trip.
+     */
+    describeClaim(claimHash: string): Promise<{
+        consumed: boolean;
+        expired: boolean;
+    } | null>;
+    invalidateClaimsForAgent(agentId: string): Promise<void>;
+    /**
+     * Delete every claim whose `expires_at` passed before `cutoff`. Returns how
+     * many rows went.
+     *
+     * Nothing else removes a claim on a timer: `redeemClaim` only marks
+     * `consumed_at`, and `invalidateClaimsForAgent` runs on a teardown path a
+     * stranded provision never reaches. So a claim outlives its agent whenever a
+     * registration unwinds after the claim was written, or whenever the
+     * coordinator that would have torn the agent down crashed first — and the row
+     * then sits in the table forever. Purging on `expires_at` covers both,
+     * consumed or not, because an expired claim can never be redeemed again.
+     *
+     * The caller subtracts a retention grace from now, so `describeClaim` can
+     * still tell a late redeemer "expired" rather than "unknown code" for a while
+     * after the deadline. Backed by `idx_scaler_pending_claims_expires_at`.
+     */
+    purgeExpiredClaims(cutoff: Date): Promise<number>;
+    /**
+     * Record the reaper's teardown verdict for one provision.
+     *
+     * Deliberately additive: it writes only the `condemned_*` columns. A
+     * `heartbeat-timeout` condemns a provision that WAS adopted, so clearing the
+     * adoption here would put the stale-spawn prune straight back to reporting a
+     * healthy provision as a failed one — the exact misattribution this table
+     * exists to remove.
+     *
+     * Called only once the teardown was actually delivered. An emit that reached
+     * nobody leaves the spawn row in place for the reaper to retry, so there is
+     * no verdict yet to record.
+     *
+     * The `condemned_*` half is the forensic side of the record and has no
+     * production reader: `provisionAdopter` answers from `adopted_by` alone, so
+     * the prune's verdict does not depend on it. It is written because the row
+     * is the only surviving account of what became of a provision once the spawn
+     * row is gone — which is what an operator investigating a torn-down
+     * provision, and the E2E that pins this behaviour, read it for.
+     */
+    recordProvisionCondemned(agentId: string, scalerName: string, reason: string): Promise<void>;
+    /**
+     * Delete outcome rows that can no longer be asked about; returns rows deleted.
+     *
+     * Two predicates, and the second is the load-bearing one. The cutoff alone is
+     * not safe: recovery rehydrates an in-memory spawning entry from
+     * `scaler_spawning_agents`, and a rehydrated entry is immediately stale, so
+     * it asks about its provision on the very next prune however old the
+     * provision is. While the spawn row exists the outcome must stay. Once the
+     * spawn row is gone, nothing can rehydrate an entry for it, and the caller's
+     * retention floor covers the one prune window still in flight.
+     *
+     * Backed by `idx_scaler_provision_outcomes_updated_at`.
+     */
+    purgeProvisionOutcomes(cutoff: Date): Promise<number>;
 }
 /**
  * Aggregate event surface for "the scaler manager fully replayed its

package/dist/scaler/types.d.ts

@@ -4,8 +4,10 @@
  * Provides the foundational types that all scaler backends, the ScalerManager,
  * and the configuration layer depend on.
  */
+import { ImagePullPolicy } from '@kici-dev/shared/container-runtime';
 import { z } from 'zod';
 import { ScalerEventType } from '@kici-dev/engine';
+import type { ScaleDownReason } from './scaler-events.js';
 import type { ResourceRequest, ResourceSpec, ScalerBackendType, ScalerPlatform } from '@kici-dev/engine';
 export type { ResourceRequest, ResourceSpec } from '@kici-dev/engine';
 export { ScalerEventType } from '@kici-dev/engine';
@@ -58,11 +60,43 @@ export interface EffectiveLimits {
  * select the exact container a trigger produced instead of guessing among
  * concurrent kici-managed containers. Absent for unbound spawns (warm pool).
  */
+/**
+ * A job's container spec with its registry credentials already resolved.
+ *
+ * The lock carries credential REFERENCES; this is what a runtime can actually
+ * pull with. Produced by `resolveContainerSpawn`, consumed by the container
+ * sandbox and by both spawning backends.
+ */
+export interface ResolvedContainerSpawn {
+    image: string;
+    authconfig?: {
+        username: string;
+        password: string;
+        serveraddress: string;
+    };
+    env?: Record<string, string>;
+}
 export interface SpawnContext {
     /** Execution job id the spawn is bound to. */
     boundJobId?: string;
     /** Execution run id the bound job belongs to. */
     runId?: string;
+    /**
+     * The job's own container image plus resolved registry credentials, when the
+     * job declared one. Present means "spawn THIS image with the KiCI runtime
+     * injected" rather than the pool's fixed agent image.
+     */
+    container?: ResolvedContainerSpawn;
+    /**
+     * Plain platform-taint tokens (`windows`, `macos`, `arm64`) for the pool this
+     * spawn belongs to, derived by `ScalerManager` from the same resolved
+     * platform its taint gate uses. A backend forwards them to
+     * `scalerAgentLabels()` so the agent registers carrying the very tokens the
+     * gate demands — without them a tainted pool spawns agents no job can be
+     * dispatched to. A backend must never derive them itself: the manager is the
+     * single source, and computing them twice is the defect this field closes.
+     */
+    platformTaints?: readonly string[];
 }
 /**
  * Network policy controlling RFC1918 and internet access for agents in this label set.
@@ -82,13 +116,12 @@ export interface NetworkPolicy {
  * - `Always`: re-pull on every spawn. Set this on a label set that tracks a
  *   moving tag (e.g. `:latest`) or otherwise needs a fresh image each spawn.
  * - `Never`: never pull; fail if the image is absent.
+ *
+ * Defined alongside `pullImageIfMissing` in `@kici-dev/shared` — the agent
+ * pulls job images through the same helper — and re-exported here so the scaler
+ * config schema and every operator-facing value stay exactly where they were.
  */
-export declare const ImagePullPolicy: z.ZodEnum<{
-    Always: "Always";
-    IfNotPresent: "IfNotPresent";
-    Never: "Never";
-}>;
-export type ImagePullPolicy = z.infer<typeof ImagePullPolicy>;
+export { ImagePullPolicy };
 /**
  * Configuration for a single label-set mapping within a scaler backend.
  * Maps an exact set of labels to the agent provisioning details.
@@ -196,6 +229,22 @@ export type ValidationResult = {
     valid: false;
     errors: string[];
 };
+/**
+ * Optional context passed to `ScalerBackend.destroy`. The event backend surfaces
+ * `reason` on its scale-down event; local backends ignore it.
+ */
+export interface ScalerDestroyContext {
+    /** Why the teardown was requested (idle, job-complete, drain, …). */
+    reason?: ScaleDownReason;
+    /**
+     * Where an event backend must deliver the teardown, overriding its live
+     * config. Set from the spawn record when the agent was adopted from another
+     * coordinator, so a teardown addresses the targets the provision was spawned
+     * with even if `provisioningTargets` has been edited since. Ignored by the
+     * local backends, which deliver nothing.
+     */
+    targets?: string[];
+}
 /**
  * Common interface for all scaler backends.
  * Each backend manages a specific pool of agents for specific label sets.
@@ -209,8 +258,11 @@ export interface ScalerBackend {
     readonly logsSource?: string;
     /** Label sets this backend can provision */
     readonly labelSets: LabelSetConfig[];
-    /** Per-backend maximum agents */
-    readonly maxAgents: number;
+    /**
+     * Per-backend maximum agents. Updated by `reload` so a config change to
+     * `maxAgents` applies without an orchestrator restart.
+     */
+    maxAgents: number;
     /**
      * Whether this backend spawns its agents on the orchestrator's own host.
      * True for bare-metal and Firecracker (local processes / local VMs) and for
@@ -248,9 +300,46 @@ export interface ScalerBackend {
     signal?: AbortSignal): Promise<ManagedAgent>;
     /**
      * Destroy a specific managed agent.
-     * Docker: docker rm -f; Bare-metal: SIGTERM -> SIGKILL
+     * Docker: docker rm -f; Bare-metal: SIGTERM -> SIGKILL.
+     *
+     * @param context - Optional teardown context. The event backend carries
+     *   `reason` onto its `kici.scaler.scale-down` event so a teardown workflow
+     *   (and the timeline) can distinguish an idle reap from a job-complete
+     *   teardown or a spawn timeout. Local backends accept and ignore it.
      */
-    destroy(managedId: string): Promise<void>;
+    destroy(managedId: string, context?: ScalerDestroyContext): Promise<void>;
+    /**
+     * Reclaim the HOST-LOCAL compute of a managed agent this backend no longer
+     * tracks in memory, from whatever durable host state survived the loss.
+     *
+     * `destroy` is keyed off the in-memory agent map, so an orchestrator restart
+     * makes it a silent no-op while the VM or host process keeps running. This
+     * hook is the restart-surviving half: it reads the backend's own on-host
+     * artifacts for `managedId` and reclaims them.
+     *
+     * Two properties every implementation MUST hold:
+     *
+     * - **Host-local evidence only.** Reclaim nothing unless an artifact for
+     *   exactly this `managedId` exists on THIS host — that artifact is the proof
+     *   this backend spawned it. A coordinator must never be able to reach across
+     *   and reap a peer's compute.
+     * - **Caller supplies the orphan verdict.** The hook force-reclaims a *live*
+     *   instance, which is precisely what the liveness-driven orphan sweeps
+     *   refuse to do on their own. Only call it where the agent is known to be
+     *   unowned.
+     *
+     * Optional: a backend whose compute is not host-local — the event backend's
+     * customer cloud instance — cannot implement it at all. An implementation may
+     * also cover only part of its own backend, when the rest keeps nothing durable
+     * to read. Bare metal is that case: a container-mode agent carries
+     * `kici-agent-id` / `kici-scaler-name` labels on the host and is reclaimed,
+     * while a plain-process agent records its PID in the in-memory entry alone, so
+     * a restart loses it and the hook reports nothing to reclaim.
+     *
+     * @returns `true` when host-local state for `managedId` was found and
+     *   reclaimed, `false` when there was nothing here to reclaim.
+     */
+    reapUnowned?(managedId: string): Promise<boolean>;
     /**
      * Get the LogCapture for a managed agent (optional -- container and bare-metal backends
      * support stdout capture. Firecracker handles log forwarding internally via file tailing
@@ -273,10 +362,23 @@ export interface ScalerBackend {
      */
     ensureHostReady?(): Promise<void>;
     /**
-     * Reload configuration (called on SIGHUP).
-     * Returns validation errors if new config is invalid.
+     * Reload configuration (called on config reload / SIGHUP).
+     *
+     * `opts.maxAgents`, when present, replaces the population cap. `opts.entry`
+     * is the whole new config entry, for a backend that reads more than its
+     * label sets off it. On an invalid result NOTHING is applied.
+     */
+    reload(labelSets: LabelSetConfig[], opts?: {
+        maxAgents?: number;
+        entry?: ScalerEntry;
+    }): ValidationResult;
+    /**
+     * The config entry this backend is currently serving, for backends that hold
+     * one. Read by the reload rollback so a rejected reload can restore it
+     * alongside `labelSets` and `maxAgents`. Undefined for backends that keep no
+     * entry (container, bare-metal, Firecracker all read only their label sets).
      */
-    reload(labelSets: LabelSetConfig[]): ValidationResult;
+    readonly currentEntry?: ScalerEntry;
 }
 /**
  * Parsed and validated scaler configuration from YAML.
@@ -438,6 +540,22 @@ export interface ScalerEntry {
      * binaries. Default false.
      */
     requireSudo?: boolean;
+    /**
+     * Workflow refs (e.g. `org/infra`) the reserved scale-up / scale-down events
+     * are delivered to. The customer's provisioning / teardown workflows
+     * subscribe with `kiciEvent()`. Required for a `type: event` scaler.
+     */
+    provisioningTargets?: string[];
+    /**
+     * Seconds a pending provisioning claim code stays valid before it expires.
+     * @default 300
+     */
+    claimTtlSeconds?: number;
+    /**
+     * Seconds the ephemeral agent token minted for a claimed provision stays
+     * valid. @default 600
+     */
+    agentTokenTtlSeconds?: number;
 }
 /**
  * Warm pool configuration for pre-provisioned idle agents.