@kici-dev/orchestrator 0.5.0 → 0.6.0

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

@@ -0,0 +1,142 @@
+/**
+ * Admin API routes for reading and answering held runs.
+ *
+ * Exposes GET `/api/v1/admin/held-runs` and POST
+ * `/api/v1/admin/held-runs/decision` so `kici-admin held-run list|approve|reject`
+ * can release a hold locally, without a Platform.
+ *
+ * **Independent orchestrators only.** Wherever a Platform is attached it owns
+ * who may answer a hold: the Platform's held-run trust gate resolves the hold's
+ * type and requires `ci_trust:write` for a security hold and `contexts:write` /
+ * `contexts:admin` for the rest, against the acting member's org RBAC. This
+ * route authenticates with an orchestrator admin token, which carries
+ * orchestrator RBAC and no Platform membership at all — so answering a hold here
+ * on a Platform-attached deployment would land a release the Platform's own gate
+ * never authorized. Both write and read therefore refuse with 409 in
+ * `platform` / `hybrid` / `observed`, mirroring the trust-policy write verbs.
+ *
+ * On an independent orchestrator there is no upstream authority, and until this
+ * route existed an approval-queue hold there had no answer at all: `/kici
+ * approve` releases the `security` queue only, and the dashboard, `kici
+ * approve` and the MCP tools all reach the applier over the Platform relay.
+ *
+ * Answering goes through the shared `applyDecision` applier, not through a
+ * direct row flip, so an approve here obeys the hold's own
+ * `approval_requirement` clauses, records a `held_run_approvals` row, and — this
+ * is the part a row flip silently skips — resumes the held element through
+ * `routeRelease`, which re-dispatches the job or replays the workflow dispatch.
+ *
+ * The resume runs AFTER this route answers. The decision is durable at the
+ * applier's own transaction, and the resume it triggers is unbounded work whose
+ * latency has no business being the operator's — see
+ * `ApplyDecisionResult.consequence`. The access-log entry is written when that
+ * consequence settles, so a resume that failed is recorded as `error` with its
+ * message rather than being lost behind a successful-looking answer.
+ *
+ * Releasing a hold lets the held work RUN; it does not make its contributor
+ * trusted. The resumed dispatch replays the trust resolution the hold was
+ * created under, so an untrusted fork PR still runs with the base-branch lock
+ * file, no install/registry secrets, and an isolated cache write scope.
+ */
+import { Hono } from 'hono';
+import type { Kysely } from 'kysely';
+import type { OrchestratorMode } from '@kici-dev/engine';
+import { HeldRunStore, type ReleaseSignal } from '../contexts/held-runs.js';
+import { TrustDirectoryStore } from '../security/trust-directory-store.js';
+import { adminActorSub, triggererSubjectFor } from '../approvals/triggerer-subject.js';
+import { type ResolveCheckStatusPoster } from '../pipeline/security-hold-check.js';
+import type { RbacEnforcer, Role } from '../secrets/rbac.js';
+import type { AccessLogWriter } from '../audit/access-log.js';
+import type { Database, HeldRun } from '../db/types.js';
+/**
+ * Wording for the Platform-managed refusal, surfaced verbatim by the CLI.
+ *
+ * It names the surfaces that DO answer a hold on a Platform-attached
+ * orchestrator, because "not here" without "there instead" is the refusal an
+ * operator reads as a broken build.
+ */
+export declare const PLATFORM_MANAGED_HELD_RUN_MESSAGE: string;
+/**
+ * Wording for the step-scope refusal.
+ *
+ * A step-scoped hold is answered by notifying the waiting agent through the
+ * step-approval bridge, which an independent orchestrator does not wire — so
+ * this route has no way to tell the agent. Flipping the row anyway would be
+ * strictly worse than refusing: the agent would keep waiting while the row left
+ * `pending`, putting it beyond the stale detector's expiry sweep, so the step
+ * would block with nothing left to release OR expire it.
+ */
+export declare const STEP_SCOPE_UNSUPPORTED_MESSAGE: string;
+/** The release wiring the applier needs to actually resume a released element. */
+export interface HeldRunReleaseWiring {
+    /**
+     * Re-dispatch a job-scoped release.
+     *
+     * REQUIRED, and the mount is conditional on it. A release path that flips the
+     * row without dispatching looks like it works and does nothing — the hold
+     * reads `approved`, the job never starts, and no sweep will ever look at the
+     * row again.
+     */
+    onJobRelease: (signal: ReleaseSignal) => Promise<void>;
+    /** Replay the stored dispatch context of a released workflow-scoped hold. */
+    onWorkflowRelease?: (signal: ReleaseSignal) => Promise<void>;
+    /**
+     * Cancel the run and drop the pending dispatch context of a REJECTED
+     * workflow-scoped hold, resolving to whether it wrote the hold's terminal
+     * security check itself.
+     */
+    onWorkflowReject?: (hold: HeldRun, reason?: string) => Promise<boolean>;
+    /** Resolve the check poster of the provider bundle serving a routing key. */
+    resolveCheckStatusPoster?: ResolveCheckStatusPoster;
+}
+export interface HeldRunRouteDeps {
+    /** The held-run store the decision is applied through. */
+    store: HeldRunStore;
+    /**
+     * The org approval directory — the only place an independent orchestrator
+     * holds team membership, and therefore the only thing that can satisfy a
+     * `{team}` clause on a hold's requirement.
+     */
+    directory: TrustDirectoryStore;
+    /**
+     * Orchestrator database, for the two per-decision reads the applier needs
+     * that no store owns: `org_settings.allow_self_approval` and the run's
+     * triggerer.
+     */
+    db: Kysely<Database>;
+    rbac: RbacEnforcer;
+    /** This orchestrator's mode; decides whether either verb is permitted at all. */
+    mode: OrchestratorMode;
+    /**
+     * Audit sink, REQUIRED for the same reason the trust-policy route's is: the
+     * guarantee this route makes is that a locally-answered hold is always
+     * attributable, and an optional sink would leave that resting on every
+     * construction site remembering to pass one.
+     */
+    accessLog: AccessLogWriter;
+    release: HeldRunReleaseWiring;
+}
+type AdminEnv = {
+    Variables: {
+        role: Role;
+        userId: string;
+        routingKey: string | null;
+    };
+};
+/**
+ * The approval subject for a decision taken through an admin token.
+ *
+ * Namespaced `service:<token user id>`, matching how the dashboard applier
+ * derives a subject for a service-account actor. The namespace is what keeps it
+ * from ever colliding with a Keycloak sub named by an `approvers:` clause: an
+ * operator token answers as itself, never as a person it typed the name of.
+ * `held_run_approvals.approver_user_id` is the record of who approved, and a
+ * subject the operator merely asserted would make that record false.
+ *
+ * Re-exported from the shared subject module so this route and the dashboard
+ * handler cannot drift into two `service:` namespaces.
+ */
+export { adminActorSub };
+export { triggererSubjectFor };
+export declare function createHeldRunRoutes(deps: HeldRunRouteDeps): Hono<AdminEnv>;
+//# sourceMappingURL=admin-held-runs.d.ts.map

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

@@ -1,17 +1,28 @@
 /**
- * Admin API routes for the org trust policy.
+ * Admin API routes for the org trust policy and the approval directory it
+ * arrives with.
  *
  * Exposes GET / PATCH `/api/v1/admin/trust-policy` so `kici-admin` can read the
- * enforced policy and, on an independent orchestrator, set it.
+ * enforced policy and, on an independent orchestrator, set it, plus
+ * GET / PATCH / DELETE `/api/v1/admin/trust-policy/directory` for the approval
+ * directory that arrives with 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.
+ * Both are Platform-owned wherever a Platform is attached: the Platform pushes
+ * them together on `trust_policy.update` and the next push would clobber a
+ * local write. Every write verb therefore refuses on any Platform-attached
+ * orchestrator, and the refusal is server-side so it cannot be bypassed by
+ * calling the API directly. On an independent orchestrator there is no upstream
+ * authority at all, so the operator is the only possible one — which is what
+ * the directory's PATCH and DELETE are for. Without them nobody can ever be
+ * registered as an approver there, and `/kici approve` can release no hold.
+ *
+ * GET stays available in every mode: reading the cache is what lets an operator
+ * tell a stale directory from an absent one.
  */
 import { Hono } from 'hono';
 import type { OrchestratorMode } from '@kici-dev/engine';
 import type { TrustPolicyStore } from '../security/trust-policy-store.js';
+import type { TrustDirectoryStore } from '../security/trust-directory-store.js';
 import type { RbacEnforcer, Role } from '../secrets/rbac.js';
 import type { AccessLogWriter } from '../audit/access-log.js';
 /**
@@ -19,8 +30,25 @@ import type { AccessLogWriter } from '../audit/access-log.js';
  * response body — the CLI surfaces this verbatim rather than inventing its own.
  */
 export declare const PLATFORM_MANAGED_MESSAGE: string;
+/**
+ * Wording for the directory's own Platform-managed refusal. Separate from
+ * {@link PLATFORM_MANAGED_MESSAGE} because it names a different thing to change
+ * and a different place to change it: identity links and member CI trust levels
+ * are org membership, not a policy switch.
+ */
+export declare const PLATFORM_MANAGED_DIRECTORY_MESSAGE: string;
 interface TrustPolicyRouteDeps {
     store: TrustPolicyStore;
+    /**
+     * The org approval directory — the Platform's cache where one is attached,
+     * the operator's own registrations where none is.
+     *
+     * REQUIRED for the same reason `accessLog` is: an optional store would let an
+     * orchestrator mount a `directory` endpoint that reports "nothing cached" on
+     * every call, which reads identically to a genuinely empty cache and is
+     * exactly the wrong answer to give an operator debugging a refused approval.
+     */
+    directory: TrustDirectoryStore;
     rbac: RbacEnforcer;
     /** This orchestrator's mode; decides whether PATCH is permitted at all. */
     mode: OrchestratorMode;

package/dist/routes/admin.d.ts

@@ -16,6 +16,7 @@ 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 HeldRunReleaseWiring } from './admin-held-runs.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';
@@ -147,6 +148,14 @@ export interface AdminRouteDeps {
         stillPending: number;
         rejected: number;
     }>;
+    /**
+     * Optional -- the resume wiring behind `kici-admin held-run approve|reject`.
+     * When set (alongside `db` + `accessLog`), the local held-run read and
+     * decision routes are mounted; they refuse with 409 on a Platform-attached
+     * orchestrator. Unset leaves them unmounted, which is the honest state for an
+     * app that cannot dispatch a released hold.
+     */
+    heldRunRelease?: HeldRunReleaseWiring;
 }
 /** Hono env type for admin routes with context variables. */
 type AdminEnv = {

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

@@ -0,0 +1,55 @@
+/**
+ * The single construction path for scaler backends.
+ *
+ * Both startup hosts (`orchestrator-core`, `worker-core`) and
+ * `ScalerManager.reload` call this, so a backend built by a reload is built
+ * exactly the way startup builds one. Host differences (DB-backed vs in-memory
+ * IP allocation, event support) arrive as context fields rather than forked
+ * code.
+ */
+import type { createLogger, ToolRequirement } from '@kici-dev/shared';
+import type { AgentTokenStore } from '../agent/token-store.js';
+import type { ScalerEventEmitterLike } from './event-backend.js';
+import type { ScalerStateStore } from './scaler-state-store.js';
+import type { IpAllocator } from './ip-allocator.js';
+import type { ScalerBackend, ScalerConfig, ScalerEntry } from './types.js';
+/** Network parameters an IP allocator needs, resolved from `scalerConfig.firecracker`. */
+export interface IpAllocatorParams {
+    cidr: string;
+    gateway: string;
+    netmask: string;
+}
+export interface BackendFactoryContext {
+    /** The whole config — supplies `defaults.resources` and the firecracker network block. */
+    scalerConfig: ScalerConfig;
+    /**
+     * Always supplied when available; the event backend's claim store needs it
+     * regardless of the auth mode.
+     */
+    tokenStore?: AgentTokenStore;
+    /** True when `config.agentAuth === 'token'`; gates token injection for the three local backends. */
+    injectAgentToken: boolean;
+    tokenTtlMs?: number;
+    /** Live per-spawn resolver for the fleet-wide agent-token TTL. */
+    tokenTtlProvider: () => Promise<number>;
+    /** DB-backed on the leader, in-memory on the worker. */
+    ipAllocator: (params: IpAllocatorParams) => IpAllocator;
+    /**
+     * The already-constructed scaler state store. The event backend's claim
+     * store writes its pending-claim rows through it. Absent on the worker,
+     * which has no database — and so no event backend either.
+     */
+    stateStore?: ScalerStateStore;
+    /** Absent ⇒ the `event` type is unsupported on this host (worker mode). */
+    eventEmitterProvider?: () => ScalerEventEmitterLike;
+    logger: ReturnType<typeof createLogger>;
+}
+/** Tool requirements for a set of entries, for `validateRequiredTools` from `@kici-dev/shared`. */
+export declare function requiredToolsFor(entries: ScalerEntry[]): ToolRequirement[];
+/**
+ * Construct one backend. Returns null (with a warning) when the type is not
+ * supported on this host — the worker has no event emitter, and `kubernetes`
+ * is not implemented.
+ */
+export declare function createScalerBackend(s: ScalerEntry, ctx: BackendFactoryContext): Promise<ScalerBackend | null>;
+//# sourceMappingURL=backend-factory.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, SpawnContext } from './types.js';
+import type { ScalerBackend, ScalerDestroyContext, ScalerEntry, ManagedAgent, LabelSetConfig, LogCapture, ResourceRequest, ScalerEventCallback, ValidationResult, EffectiveLimits, SpawnContext } from './types.js';
 export interface BareMetalScalerBackendOptions {
     /** Human-readable name for this scaler */
     name: string;
@@ -47,7 +47,7 @@ export declare class BareMetalScalerBackend implements ScalerBackend {
     readonly type: "bare-metal";
     readonly spawnsOnLocalHost = true;
     readonly logsSource = "bare-metal";
-    readonly maxAgents: number;
+    maxAgents: number;
     private _labelSets;
     private readonly name;
     private readonly defaultResources?;
@@ -79,15 +79,53 @@ 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, _spawnContext?: SpawnContext, _signal?: AbortSignal): Promise<ManagedAgent>;
+    spawn(labelSet: string[], agentId: string, orchestratorUrl: string, onEvent?: ScalerEventCallback, effectiveLimits?: EffectiveLimits, spawnContext?: SpawnContext, signal?: AbortSignal): Promise<ManagedAgent>;
+    /**
+     * Launch the agent inside the job's own container image.
+     *
+     * The bare-metal backend historically only ran a local process, which meant a
+     * job naming its own image could not use this pool at all. With the KiCI
+     * runtime injected, the image needs neither Node nor git, so an arbitrary
+     * customer image can host the agent.
+     *
+     * Split out of `spawn()` because that function is already near the 200-line
+     * ceiling and the two launches share nothing past the env.
+     */
+    private spawnContainerAgent;
     getScalerContext(agentId: string): Record<string, unknown> | undefined;
-    destroy(managedId: string): Promise<void>;
+    destroy(managedId: string, _context?: ScalerDestroyContext): Promise<void>;
+    /**
+     * Force-reclaim a container-mode agent this backend no longer tracks.
+     *
+     * `destroy()` opens with an in-memory map lookup, so an orchestrator restart
+     * makes it a silent no-op while the container keeps running. The container
+     * backend's own startup sweep does not cover this one either: it removes every
+     * `kici-managed` container, but it only runs when a container scaler is
+     * configured, and a bare-metal-only deployment has none.
+     *
+     * The host-local evidence is the container itself: `spawnContainerAgent` stamps
+     * `kici-agent-id` and `kici-scaler-name` onto it, and a container listing only
+     * ever names containers on this host. So a coordinator cannot reach a peer's
+     * compute through this path — a wrongly-routed agent id simply matches nothing.
+     *
+     * A process-mode agent is NOT reclaimed here. Its PID lives in the in-memory
+     * entry alone, so a restart leaves no durable, host-local artifact to key off,
+     * and reclaiming it would need a persistence mechanism this backend does not
+     * have. Scanning the process table instead would risk signalling a recycled
+     * PID.
+     *
+     * @returns `true` when a container for `managedId` was found and removed.
+     */
+    reapUnowned(managedId: string): Promise<boolean>;
     /**
      * Get the LogCapture for a managed agent (used by ScalerManager for log forwarding).
      */
     getLogCapture(managedId: string): LogCapture | undefined;
     shutdownAll(): Promise<void>;
-    reload(labelSets: LabelSetConfig[]): ValidationResult;
+    reload(labelSets: LabelSetConfig[], opts?: {
+        maxAgents?: number;
+        entry?: ScalerEntry;
+    }): ValidationResult;
     /**
      * Build the (command, args) tuple used to spawn an agent process.
      *

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

@@ -0,0 +1,119 @@
+/**
+ * Pending-claim store for the event scaler backend.
+ *
+ * When the event backend spawns, it registers a pending claim and emits a
+ * scale-up event carrying a single-use `claimCode` (never the token itself).
+ * The provisioning workflow forwards that code to the instance it boots, and the
+ * agent exchanges it — over the `scaler.claim-credentials` RPC — for a freshly
+ * minted ephemeral agent token it then registers with. The claim code is the
+ * authorization for that RPC, so the agent can redeem it before it authenticates
+ * or registers; a workflow can also redeem the code itself and deliver the token.
+ * The token is therefore minted lazily (only when a real provision claims it) and
+ * is single-use: a leaked or replayed claim code mints nothing.
+ *
+ * The claim is persisted in `scaler_pending_claims` rather than held in a
+ * per-process map, so a code minted by one coordinator can be redeemed by any
+ * other coordinator behind the same shared endpoint. Only the sha256 of the
+ * code is stored, so a DB read can never hand back a redeemable secret.
+ */
+import type { ScalerStateStore } from './scaler-state-store.js';
+/**
+ * TTL (seconds) a pending claim code stays redeemable when the scaler entry
+ * does not set `claimTtlSeconds`. Long enough for a provisioning workflow to
+ * boot an instance, short enough that a leaked code ages out quickly.
+ */
+export declare const DEFAULT_CLAIM_TTL_SECONDS = 300;
+/**
+ * Function that mints an ephemeral agent token bound to an agent id + labels.
+ * Modelled on `AgentTokenStore.createEphemeral(agentId, labels, ttlMs)`.
+ */
+export type CreateEphemeralToken = (agentId: string, labels: string[], ttlMs: number) => Promise<string>;
+/** What the event backend registers when it emits a scale-up. */
+export interface ClaimSpec {
+    /** Agent id the provisioned instance must register with. */
+    agentId: string;
+    /** Exact label set the ephemeral token is authorized for. */
+    labels: string[];
+    /** Mandatory (taint) labels the pool gates on, carried for the workflow. */
+    mandatoryLabels: string[];
+    /** TTL of the ephemeral agent token minted on claim (seconds). */
+    agentTokenTtlSeconds: number;
+    /** Orchestrator WS URL the provisioned agent connects back to. */
+    orchestratorUrl: string;
+}
+/** What a successful claim returns to the provisioning workflow. */
+export interface ClaimedCredentials {
+    /** The freshly minted, single-use-per-claim ephemeral agent token. */
+    agentToken: string;
+    /** Agent id the instance must register with. */
+    agentId: string;
+    /** Orchestrator WS URL to connect back to. */
+    orchestratorUrl: string;
+    /** Labels the token authorizes. */
+    labels: string[];
+}
+export interface ClaimStoreOptions {
+    /** Mints the ephemeral agent token when a claim is honored. */
+    createEphemeral: CreateEphemeralToken;
+    /** Shared persistence, so any coordinator can redeem a code. */
+    stateStore: ScalerStateStore;
+    /**
+     * Scaler this store belongs to; recorded on each claim row. Required for
+     * `register`, and omitted on a redemption-only store (the manager's), which
+     * never writes a row.
+     */
+    scalerName?: string;
+    /** Injected clock (epoch ms) — no ambient `Date.now()` so TTLs are testable. */
+    now?: () => number;
+    /** Default TTL of a pending claim code (seconds) before it expires. */
+    ttlDefaultSec: number;
+}
+/**
+ * Shared store of pending provisioning claims, backed by `scaler_pending_claims`.
+ */
+export declare class ClaimStore {
+    private readonly createEphemeral;
+    private readonly stateStore;
+    private readonly scalerName;
+    private readonly now;
+    private ttlDefaultMs;
+    constructor(opts: ClaimStoreOptions);
+    /**
+     * Replace the default pending-claim TTL. Called when a config reload changes
+     * the owning scaler's `claimTtlSeconds`, so the new value applies without an
+     * orchestrator restart.
+     */
+    setDefaultTtlSeconds(seconds: number): void;
+    /**
+     * Register a pending claim and return its single-use code. The code is a
+     * 256-bit cryptographically-random token — unguessable, so it can travel in
+     * the (persisted) scale-up event without leaking the agent token. Only the
+     * sha256 of the code is persisted, so a DB read can never hand back a
+     * redeemable secret.
+     */
+    register(spec: ClaimSpec): Promise<string>;
+    /**
+     * Exchange a claim code for freshly minted credentials. Single-use and
+     * TTL-bounded, enforced by a conditional UPDATE that commits the consumption
+     * BEFORE the mint is attempted — so two concurrent claims of one code, on any
+     * two instances, can never both mint. Fail-closed: a failed mint does not
+     * reopen the code.
+     *
+     * The redeem is one round trip on the happy path; `describeClaim` runs only
+     * when the redeem found nothing, to say why (unknown / consumed / expired).
+     */
+    claim(code: string): Promise<ClaimedCredentials>;
+    /**
+     * Drop every claim for an agent id, so a torn-down provision's code can no
+     * longer be redeemed on any instance.
+     */
+    invalidate(agentId: string): Promise<void>;
+    /**
+     * A redemption-only store never writes a claim row, so it is constructed
+     * without a scaler name. Reaching `register` without one is a wiring bug, not
+     * a runtime condition — fail loudly rather than persisting a row nothing can
+     * attribute.
+     */
+    private requireScalerName;
+}
+//# sourceMappingURL=claim-store.d.ts.map

package/dist/scaler/config.d.ts

@@ -170,6 +170,7 @@ export declare const scalerFileSchema: z.ZodObject<{
         type: z.ZodEnum<{
             "bare-metal": "bare-metal";
             container: "container";
+            event: "event";
             firecracker: "firecracker";
         }>;
         maxAgents: z.ZodNumber;
@@ -287,6 +288,9 @@ export declare const scalerFileSchema: z.ZodObject<{
         vcpuCount: z.ZodDefault<z.ZodNumber>;
         memSizeMib: z.ZodDefault<z.ZodNumber>;
         requireSudo: z.ZodDefault<z.ZodBoolean>;
+        provisioningTargets: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        claimTtlSeconds: z.ZodDefault<z.ZodNumber>;
+        agentTokenTtlSeconds: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strict>>;
     firecracker: z.ZodOptional<z.ZodObject<{
         cidr: z.ZodDefault<z.ZodString>;

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

@@ -8,7 +8,7 @@
  */
 import { type ToolRequirement } from '@kici-dev/shared';
 import type { AgentTokenStore } from '../agent/token-store.js';
-import type { ScalerBackend, ManagedAgent, LabelSetConfig, LogCapture, ResourceRequest, EffectiveLimits, SpawnContext, ScalerEventCallback, ValidationResult, ScalerEntry } from './types.js';
+import type { ScalerBackend, ScalerDestroyContext, ManagedAgent, LabelSetConfig, LogCapture, ResourceRequest, EffectiveLimits, SpawnContext, ScalerEventCallback, ValidationResult, ScalerEntry } from './types.js';
 /**
  * Result of runtime detection.
  */
@@ -56,7 +56,7 @@ export interface ContainerScalerBackendOptions {
 export declare class ContainerScalerBackend implements ScalerBackend {
     readonly type: "container";
     readonly spawnsOnLocalHost: boolean;
-    readonly maxAgents: number;
+    maxAgents: number;
     private _labelSets;
     private readonly name;
     private readonly docker;
@@ -121,15 +121,29 @@ export declare class ContainerScalerBackend implements ScalerBackend {
     get logsSource(): string;
     get labelSets(): LabelSetConfig[];
     getActiveCount(): number;
+    /**
+     * The full label set the agent will present, and the ephemeral token bound to
+     * exactly that set.
+     *
+     * The binding is the point: the agent's register-time labels must not trip the
+     * scope gate, and the only labels it may add on top are the self-reported
+     * os/arch/host facts the gate exempts. The pool's platform taints are NOT such
+     * a fact — they are a routing grant, so the manager asserts them here via
+     * `spawnContext` rather than letting the agent claim them.
+     */
+    private mintAgentIdentity;
     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>;
+    destroy(managedId: string, _context?: ScalerDestroyContext): Promise<void>;
     /**
      * Get the LogCapture for a managed agent (used by ScalerManager for log forwarding).
      */
     getLogCapture(managedId: string): LogCapture | undefined;
     shutdownAll(): Promise<void>;
-    reload(labelSets: LabelSetConfig[]): ValidationResult;
+    reload(labelSets: LabelSetConfig[], opts?: {
+        maxAgents?: number;
+        entry?: ScalerEntry;
+    }): ValidationResult;
     /**
      * Clean up orphaned kici-managed containers on startup.
      * Finds containers with the `kici-managed=true` label and removes them.

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

@@ -0,0 +1,23 @@
+/**
+ * Capability label for hosts that can run containers.
+ *
+ * An operator may put this on a pool's label sets and on a container job's
+ * `runsOn` to steer container work at hosts with a runtime. KiCI does NOT add
+ * it automatically, and does not gate routing on it.
+ *
+ * **Why it is not automatic.** A container job needs a runtime on the host that
+ * ends up running it, and the orchestrator does not know that: an agent runs on
+ * its own machine, and whether that machine has docker or podman is the agent's
+ * fact, not the orchestrator's. Probing the orchestrator's own filesystem
+ * answers a different question — it was tried, and it stranded container jobs
+ * that had been running fine, because the probe and the job ran in different
+ * places.
+ *
+ * Doing this properly means the AGENT reporting the capability at registration,
+ * alongside the `kici:os:*` / `kici:arch:*` facts it already self-reports. Until
+ * then a mis-routed container job fails at the image preflight or a backend's
+ * fail-fast, both of which name what is missing — a clear late error, rather
+ * than a job that silently matches nothing and never runs.
+ */
+export declare const KICI_RUNTIME_DOCKER_LABEL = "kici:runtime:docker";
+//# sourceMappingURL=container-routing.d.ts.map

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

@@ -0,0 +1,28 @@
+/**
+ * Container-spawn primitives specific to the orchestrator's scaler backends.
+ *
+ * The runtime-injection half of this module (`pullImageIfMissing`,
+ * `ensureRuntimeVolume`, `runtimeInjectBind`, `injectedAgentCommand`,
+ * `runtimeVolumeName`, `RUNTIME_MOUNT`) now lives in
+ * `@kici-dev/shared/container-runtime`, because the AGENT needs exactly the
+ * same behaviour when it nests a job container. What stays here is the piece
+ * only a scaler backend does: streaming a host workspace into a container it
+ * just created.
+ */
+/**
+ * Stream a host directory into a container path.
+ *
+ * Used to populate a container-owned `/workspace` volume, which is a volume
+ * rather than a host bind precisely so the host-uid vs container-uid conflict
+ * disappears once `CapDrop: ALL` removes CAP_DAC_OVERRIDE — so the tree has to
+ * be copied in rather than mounted.
+ *
+ * A failure is fatal to the spawn: swallowing it starts the job against an
+ * empty workspace, which surfaces as a baffling "file not found" later.
+ */
+export declare function copyTreeIntoContainer(container: {
+    putArchive(stream: unknown, opts: {
+        path: string;
+    }): Promise<unknown>;
+}, hostDir: string, containerPath: string): Promise<void>;
+//# sourceMappingURL=container-spawn.d.ts.map