@kici-dev/orchestrator 0.1.26 → 0.2.0

package/dist/scaler/manager.d.ts

@@ -10,6 +10,27 @@ import type { ResourceRequest } from '@kici-dev/engine';
 import type { BackendFailureSummary } from './failure-tracker.js';
 import type { ScalerBackend, ScalerConfig, ScaleResult, ScalerEvent, ResourceCap, ValidationResult } from './types.js';
 import type { ScalerStateStore, ScalerStateRecovery } from './scaler-state-store.js';
+/**
+ * Counting semaphore that throttles the number of concurrent async operations.
+ *
+ * Used to bound how many `backend.spawn` provisioning operations (image pull +
+ * container create + start) run at once per backend, so a burst of in-cap jobs
+ * cannot storm the container socket / registry.
+ *
+ * Slots are handed directly to the next waiter on release (rather than bumping a
+ * counter the woken task re-decrements), so a task arriving in the microtask gap
+ * between a release and a woken waiter cannot jump the queue and transiently
+ * exceed the cap. The slot is always released in `run`'s `finally`, so a failed
+ * or throwing operation never leaks a slot and wedges the queue.
+ */
+export declare class SpawnSemaphore {
+    private available;
+    private readonly waiters;
+    constructor(max: number);
+    private acquire;
+    private release;
+    run<T>(fn: () => Promise<T>): Promise<T>;
+}
 /**
  * Resolved per-job resource amounts (cpus + bytes) for both `requests` and
  * `limits`. The scaler manager produces this from the job's declared resources
@@ -115,6 +136,10 @@ export declare class ScalerManager {
     private readonly globalUsage;
     /** Per-scaler machine-pool name (set when scalers reference a pool). */
     private readonly scalerMachinePools;
+    /** Per-scaler cap on concurrent `backend.spawn` operations (provisioning-rate throttle). */
+    private readonly maxConcurrentSpawns;
+    /** Per-scaler spawn throttles, created lazily from `maxConcurrentSpawns`. */
+    private readonly spawnSemaphores;
     /** Outstanding reservations keyed by agentId; used to release on disconnect. */
     private readonly reservations;
     /**
@@ -160,6 +185,23 @@ export declare class ScalerManager {
      * External callback for relaying correlated scaler events (e.g. to execution tracker).
      */
     private readonly onScalerEvent?;
+    /** Coordinator drain predicate; when true, requestScale() no-ops (no fresh
+     *  agents spawned for the held Pending backlog). Defaults to never-draining. */
+    private readonly isDraining;
+    /**
+     * Optional callback fired (debounced) whenever scaler capacity frees — an
+     * ephemeral agent released its reservation on disconnect, a spawn failed, or a
+     * managed agent completed its job. Wired by the composition roots to the
+     * dispatcher's capacity-freed re-drive so jobs that got an `at-capacity`
+     * verdict get re-offered to the scaler the moment a slot opens, instead of
+     * sitting pending until they time out. Assigned after construction because it
+     * references the dispatcher, which is built after the manager.
+     */
+    onCapacityFreed?: () => void;
+    /** Trailing-debounce timer coalescing a burst of releases into one re-drive. */
+    private capacityFreedTimer;
+    /** Trailing debounce window for {@link notifyCapacityFreed}. */
+    private static readonly CAPACITY_FREED_DEBOUNCE_MS;
     private readonly warmPool;
     /**
      * Optional DB-backed state store. When wired (production path), every
@@ -169,6 +211,10 @@ export declare class ScalerManager {
      * Unit tests can omit the store and operate from in-memory Maps only.
      */
     private readonly stateStore?;
+    /** Cluster-wide default deadline (ms) for a single `backend.spawn`. */
+    private readonly spawnTimeoutMs;
+    /** Optional per-org spawn-deadline resolver (production path; DB-backed). */
+    private readonly resolveSpawnTimeoutMs?;
     constructor(deps: {
         config: ScalerConfig;
         backends: Array<{
@@ -194,17 +240,64 @@ export declare class ScalerManager {
             /** Orchestrator instance id (used in ledger rows for ownership). */
             instanceId: string;
         };
+        /** Coordinator drain predicate. When true, requestScale() declines to spawn
+         *  fresh capacity for the held Pending backlog. Defaults to never-draining. */
+        isDraining?: () => boolean;
+        /**
+         * Cluster-wide default deadline (ms) for a single `backend.spawn`. Always
+         * supplied (from config.scalerSpawnTimeoutMs); the per-org resolver, when
+         * present, overrides it per tenant.
+         */
+        spawnTimeoutMs: number;
+        /**
+         * Optional per-org resolver for the spawn deadline: given the job's org
+         * (jobConfig.cacheOrgId, undefined for warm-pool spawns), returns the
+         * effective timeout, falling back to the cluster default internally. Wired
+         * in orchestrator-core (has DB); omitted by the worker + unit tests → the
+         * cluster default spawnTimeoutMs is used.
+         */
+        resolveSpawnTimeoutMs?: (orgId: string | undefined) => Promise<number>;
     });
     /** Per-scaler mandatoryLabels (taint-style opt-in gate). */
     private readonly scalerMandatoryLabels;
+    /** Declared structured platform per scaler (undefined = host-derive / linux default). */
+    private readonly scalerPlatform;
+    /**
+     * Warn when a pool declares a plain platform-ish label (matched by the legacy
+     * denylist) but omits the structured `platform` field. The denylist is a
+     * migration shim; declaring `platform` is the canonical way to taint a pool.
+     */
+    private warnOnUnstructuredPlatformLabels;
+    /**
+     * Resolve the pool's platform for label + taint derivation. Precedence:
+     *   1. A declared `platform` field always wins (even on a linux host).
+     *   2. Otherwise a bare-metal pool derives its platform from the host OS/arch.
+     *   3. Otherwise (container / firecracker, undeclared) returns null — those
+     *      pools run linux agents and are not auto-tainted; only an explicit
+     *      declared platform or a legacy denylist label taints them.
+     * Returns null when a bare-metal host's OS/arch is not a supported enum value
+     * (the caller falls back to the raw host-label derivation for labels).
+     */
+    private resolveScalerPlatform;
+    /**
+     * Effective taint gate for a scaler: its configured mandatoryLabels plus the
+     * platform-taint labels derived from the pool's resolved structured platform,
+     * unioned with the legacy plain-label denylist shim. A pool declaring a
+     * non-default platform (`windows`, `macos`, `arm64`, …) only accepts jobs that
+     * request that platform. Container / firecracker pools resolve to linux and
+     * carry no taint; calling it uniformly is safe.
+     */
+    private effectiveMandatoryLabels;
     /**
      * Build enriched scaler entries with auto-labels injected into each label set.
      * This ensures label matching accounts for auto-injected labels (kici:role:*,
      * kici:os:*, kici:arch:*, kici:agent:*, kici:scaler:*) that agents receive
      * at spawn time.
      *
-     * Mandatory labels are surfaced unchanged from the per-scaler config so the
-     * label matcher can apply the gate alongside subset matching.
+     * The os/arch labels derive from the pool's resolved structured platform
+     * (declared field wins, else host-derive for bare-metal, else linux), and the
+     * mandatory labels combine the per-scaler config gate with the platform taint,
+     * so the label matcher applies the gate alongside subset matching.
      */
     private getEnrichedScalerEntries;
     /**
@@ -214,12 +307,28 @@ export declare class ScalerManager {
      * back to scaler defaults). Used by per-scaler / per-orchestrator / per-machine
      * resource caps; the cap math is wired up by ScalerManager itself.
      */
-    requestScale(labels: string[], jobId: string, runId: string, excludeLabels?: string[], resources?: ResourceRequest): Promise<ScaleResult>;
+    /**
+     * Run a single backend spawn under the resolved spawn deadline. Returns the
+     * ManagedAgent on success. On deadline: aborts the signal (so the backend's
+     * threaded container-runtime/HTTP calls cancel and its own catch cleans up)
+     * AND rejects, so the caller's semaphore `run()` finally releases the slot
+     * even if the backend's unwind stalls in a non-abortable spot. The backing
+     * spawn promise gets a no-op catch attached so a late abort-rejection doesn't
+     * surface as an unhandled rejection.
+     */
+    private runSpawnWithTimeout;
+    requestScale(labels: string[], jobId: string, runId: string, excludeLabels?: string[], resources?: ResourceRequest, orgId?: string): Promise<ScaleResult>;
     /**
      * Run a critical section under the reservation lock. Serializes concurrent
      * `requestScale()` calls so the check+reserve sequence is atomic.
      */
     private runWithReservationLock;
+    /**
+     * Lazily resolve the per-backend spawn throttle, sized by the scaler's
+     * `maxConcurrentSpawns` (falling back to the cluster default). One semaphore
+     * per backend name, since each backend has its own container socket.
+     */
+    private spawnSemaphoreFor;
     /**
      * Resolve the effective `{ requests, limits }` for a job at this scaler.
      *
@@ -259,6 +368,15 @@ export declare class ScalerManager {
      * references a pool.
      */
     private releaseAll;
+    /**
+     * Signal that scaler capacity freed. Trailing-debounced by
+     * {@link CAPACITY_FREED_DEBOUNCE_MS} so a burst of simultaneous releases (and
+     * the onJobComplete → onAgentDisconnect pair for a single-use agent) coalesces
+     * into one re-drive pass that runs after the last release settles. No-op when
+     * no callback is wired. The timer is `unref`'d so it never keeps the process
+     * alive, and cleared on shutdown.
+     */
+    private notifyCapacityFreed;
     /**
      * Subtract the given `requests` from the per-scaler and global in-memory
      * counters. Used both by `releaseAll()` and by the rollback path when a
@@ -284,7 +402,9 @@ export declare class ScalerManager {
      *   Used by the caller to eagerly dispatch the bound job before the
      *   agent's idle timer fires, skipping the generic queue drain race.
      * - `mandatoryLabels` (always populated for scaler-managed agents): the
-     *   spawning scaler's `mandatoryLabels` gate. Threaded into the
+     *   spawning scaler's effective `mandatoryLabels` gate — its configured
+     *   labels plus the platform taint derived from the pool's declared OS/arch.
+     *   Threaded into the
      *   AgentRegistry so the queue-drain path (`onAgentAvailable` →
      *   `dequeueForLabels`) and the eager-dispatch path
      *   (`dispatchBoundJob` → `dequeueById`) both reject queued jobs whose
@@ -359,6 +479,29 @@ export declare class ScalerManager {
      * Firecracker backend's `getBridgeConfig()`).
      */
     getBackend(name: string): ScalerBackend | undefined;
+    /**
+     * Whether some configured backend could spawn capacity for this label set —
+     * the same `findBackendForLabels` match `requestScale` makes, asked without
+     * spawning anything.
+     *
+     * Read by the queue-expiry sweep to tell a fleet/label problem apart from a
+     * capacity one: a job whose labels no agent AND no backend can serve could
+     * never have run (`unroutable`), while a job whose backend matched but whose
+     * spawn kept failing is a provisioning/capacity problem (`timed_out_stale`),
+     * and mislabelling the latter would tell an operator to fix a `runsOn` that
+     * is perfectly correct.
+     *
+     * Exact labels only — the scaler's own routing (`requestScale`) matches on
+     * exact labels, so a regex `runsOn` matcher is not expressible here. On a
+     * scaler-configured orchestrator that makes the answer conservative for a
+     * pattern-only `runsOn`: a backend whose labelSets carry no mandatory labels
+     * matches the empty exact set, so such a job is reported routable and settles
+     * `timed_out_stale` rather than `unroutable`. That loses precision, never
+     * safety — the job is still terminal and the run still fails, which is the
+     * invariant that matters. Tightening it means teaching scaler routing about
+     * patterns, which would change where jobs actually spawn.
+     */
+    hasBackendForLabels(labels: string[], excludeLabels?: string[]): boolean;
     /**
      * Get scaler-specific configuration metadata for a managed agent.
      * Returns undefined for non-scaler-managed (static) agents.
@@ -370,10 +513,25 @@ export declare class ScalerManager {
      */
     start(): void;
     /**
-     * Remove spawning entries older than 5 minutes.
-     * These represent agents that were spawned but never registered via WS
-     * (e.g., process/container crashed on startup). Without cleanup, these
-     * entries would leak in spawningAgents forever.
+     * Provision/heal every backend's host prerequisites before spawning starts.
+     * Awaits each backend's optional ensureHostReady, catching per-backend so one
+     * scaler's host-prep failure degrades only that scaler (its spawns will fail
+     * with clear errors + the firecracker-network diagnostic reports it) rather
+     * than aborting orchestrator startup.
+     */
+    ensureHostsReady(): Promise<void>;
+    /**
+     * Remove spawning entries whose `backend.spawn` started more than 5 minutes
+     * ago but never registered via WS (e.g., process/container crashed on
+     * startup). Without cleanup, these entries would leak in spawningAgents
+     * forever.
+     *
+     * The window is measured from `spawnStartedAt` (when the throttled spawn
+     * actually began), NOT from `spawnedAt` (enqueue time): a spawn still waiting
+     * behind the per-backend spawn semaphore has not started and must not be
+     * reaped mid-queue during a large burst. Recovered orphan entries carry
+     * `spawnStartedAt` set to their persisted enqueue time, so they are subject to
+     * the normal window.
      */
     private pruneStaleSpawningEntries;
     private persistSpawningAgent;

package/dist/scaler/pending-scale-sweeper.d.ts

@@ -0,0 +1,35 @@
+export interface PendingScaleSweeperOptions {
+    /**
+     * Re-drive callback — the dispatcher's `retryPendingScaleRequests` bound to
+     * the `sweep` trigger. Returns the number of jobs re-driven (logged when > 0).
+     */
+    redrive: () => Promise<number>;
+    /** Sweep interval in milliseconds. */
+    intervalMs: number;
+}
+/**
+ * Leader-gated periodic backstop for the scaler capacity-freed re-drive.
+ *
+ * The capacity-freed hook (`ScalerManager.onCapacityFreed`) handles the common
+ * case with near-zero latency, but it can miss edge cases: a spawn that failed
+ * silently, a reservation freed on a non-leader coordinator, or a lost event.
+ * This sweeper re-runs the SAME `retryPendingScaleRequests` on a timer so a
+ * pending at-capacity job is never stranded past one interval.
+ *
+ * Modeled on `HostRosterReaper` / `EventRetryScanner`: started/stopped via the
+ * Raft leadership callbacks, a single timer cleared on `stop()`. Leader-only so
+ * multiple coordinators don't each drive the same queue.
+ */
+export declare class PendingScaleSweeper {
+    private readonly redrive;
+    private readonly intervalMs;
+    private timer;
+    private isLeader;
+    constructor(opts: PendingScaleSweeperOptions);
+    onBecomeLeader(): void;
+    onLoseLeadership(): void;
+    stop(): void;
+    /** One sweep pass. Public for tests. Never throws (logs and keeps ticking). */
+    tick(): Promise<void>;
+}
+//# sourceMappingURL=pending-scale-sweeper.d.ts.map

package/dist/scaler/types.d.ts

@@ -6,7 +6,7 @@
  */
 import { z } from 'zod';
 import { ScalerEventType } from '@kici-dev/engine';
-import type { ResourceRequest, ResourceSpec, ScalerBackendType } from '@kici-dev/engine';
+import type { ResourceRequest, ResourceSpec, ScalerBackendType, ScalerPlatform } from '@kici-dev/engine';
 export type { ResourceRequest, ResourceSpec } from '@kici-dev/engine';
 export { ScalerEventType } from '@kici-dev/engine';
 /**
@@ -73,6 +73,22 @@ export interface NetworkPolicy {
     /** Block all outbound traffic except allowlisted ranges */
     denyAll?: boolean;
 }
+/**
+ * Image pull policy for container-backend agent images.
+ *
+ * - `IfNotPresent` (default): pull only when the image is not already local.
+ *   KiCI agent images are pinned + immutable, so re-pulling on every spawn only
+ *   storms the registry/socket.
+ * - `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.
+ */
+export declare const ImagePullPolicy: z.ZodEnum<{
+    Always: "Always";
+    IfNotPresent: "IfNotPresent";
+    Never: "Never";
+}>;
+export type ImagePullPolicy = z.infer<typeof ImagePullPolicy>;
 /**
  * Configuration for a single label-set mapping within a scaler backend.
  * Maps an exact set of labels to the agent provisioning details.
@@ -82,8 +98,8 @@ export interface LabelSetConfig {
     labels: string[];
     /** Container image (Docker backend) */
     image?: string;
-    /** Image pull policy: Always (default), IfNotPresent, or Never */
-    imagePullPolicy?: 'Always' | 'IfNotPresent' | 'Never';
+    /** Image pull policy: IfNotPresent (default), Always, or Never */
+    imagePullPolicy?: ImagePullPolicy;
     /** Path to agent binary (bare-metal backend) */
     binaryPath?: string;
     /**
@@ -154,7 +170,23 @@ export type ScaleResult = {
 } | {
     action: 'failed';
     error: string;
+}
+/** Scale-up declined without attempting a spawn (e.g. coordinator draining). */
+ | {
+    action: 'skipped';
+    reason: string;
 };
+/**
+ * What triggered a pending-scale re-drive (`Dispatcher.retryPendingScaleRequests`):
+ * the near-zero-latency capacity-freed `hook` fired from `ScalerManager`, or the
+ * leader-gated periodic `sweep` backstop. Used as the `trigger` label on the
+ * `kici_orch_scaler_redispatch_total` counter.
+ */
+export declare const ScalerRedispatchTrigger: z.ZodEnum<{
+    hook: "hook";
+    sweep: "sweep";
+}>;
+export type ScalerRedispatchTrigger = z.infer<typeof ScalerRedispatchTrigger>;
 /**
  * Result of a configuration validation or reload operation.
  */
@@ -184,7 +216,8 @@ export interface ScalerBackend {
      * True for bare-metal and Firecracker (local processes / local VMs) and for
      * container backends using a local runtime socket; false when the backend
      * provisions elsewhere (remote container runtime, future cloud backends).
-     * Drives the static spawning-host display on the diagnostics page.
+     * Drives the static spawning-host display on the dashboard Infrastructure
+     * page.
      */
     readonly spawnsOnLocalHost: boolean;
     /** Current count of agents managed by this backend (including spawning) */
@@ -205,7 +238,14 @@ export interface ScalerBackend {
      * @returns The managed agent tracking object
      * @throws If the label set is not supported by this backend
      */
-    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, 
+    /**
+     * Optional abort signal from the ScalerManager spawn-timeout wrapper. When
+     * aborted, backends thread it into any long-running provisioning I/O
+     * (container-runtime requests, HTTP calls) so a hung provision cancels
+     * instead of pinning the per-backend spawn-semaphore slot.
+     */
+    signal?: AbortSignal): Promise<ManagedAgent>;
     /**
      * Destroy a specific managed agent.
      * Docker: docker rm -f; Bare-metal: SIGTERM -> SIGKILL
@@ -224,6 +264,14 @@ export interface ScalerBackend {
      * Used by the orchestrator to enrich job.context before forwarding to Platform.
      */
     getScalerContext?(agentId: string): Record<string, unknown> | undefined;
+    /**
+     * Provision or heal this backend's host prerequisites before it spawns.
+     * Called once by ScalerManager during startup. Optional — only backends with
+     * host-side setup (Firecracker's bridge) implement it; container/bare-metal
+     * omit it. May throw; the manager catches per-backend and degrades that
+     * scaler rather than aborting orchestrator startup.
+     */
+    ensureHostReady?(): Promise<void>;
     /**
      * Reload configuration (called on SIGHUP).
      * Returns validation errors if new config is invalid.
@@ -250,6 +298,12 @@ export interface FirecrackerNetworkConfig {
     netmask?: string;
     /** nft table name for this coordinator's host bridge @default 'kici' */
     table?: string;
+    /**
+     * When true (default), the orchestrator verifies and provisions this host
+     * bridge on startup (self-heal), so a fresh Firecracker host needs no manual
+     * `kici-admin firecracker provision`. @default true
+     */
+    autoProvisionHost?: boolean;
 }
 /**
  * Parsed and validated scaler configuration from YAML.
@@ -293,8 +347,15 @@ export interface ScalerEntry {
     name: string;
     /** Backend type */
     type: Exclude<ScalerBackendType, 'kubernetes'>;
-    /** Maximum concurrent agents for this scaler */
+    /** Maximum concurrent agents for this scaler (population cap) */
     maxAgents: number;
+    /**
+     * Maximum concurrent `backend.spawn` operations for this scaler
+     * (provisioning-rate throttle). Orthogonal to `maxAgents`: excess in-cap
+     * spawns queue and drain at this rate rather than storming the socket.
+     * Defaults to `DEFAULT_MAX_CONCURRENT_SPAWNS` at config-load.
+     */
+    maxConcurrentSpawns: number;
     /** Label-set to image/binary mappings */
     labelSets: LabelSetConfig[];
     /** Container runtime host (e.g. 'tcp://192.168.1.10:2376'). Works for both Docker and Podman remote. */
@@ -319,6 +380,14 @@ export interface ScalerEntry {
      * `labelSets`. Default: `[]` (no gating).
      */
     mandatoryLabels?: string[];
+    /**
+     * Structured platform of this pool's agents. When set, the auto-injected
+     * `kici:os:*` / `kici:arch:*` labels AND the mandatory platform taint both
+     * derive from this single field. Optional: when omitted, bare-metal pools
+     * derive the platform from the host OS/arch, and container / firecracker
+     * pools default to linux.
+     */
+    readonly platform?: ScalerPlatform;
     /**
      * Agent roles this scaler handles. scaler-entry level, not per-label-set.
      * - undefined (not set): handles all job types including build and init (backward compat,)

package/dist/secrets/backend-registry.d.ts

@@ -18,7 +18,26 @@ export declare class BackendRegistry {
     private readonly db;
     private readonly masterKey;
     private readonly logger?;
-    constructor(db: Kysely<any>, masterKey: Buffer, logger?: Logger | undefined);
+    private readonly oldMasterKey?;
+    constructor(db: Kysely<any>, masterKey: Buffer, logger?: Logger | undefined, oldMasterKey?: Buffer | undefined);
+    /**
+     * Decrypt a backend config with the current master key, falling back to the
+     * old key during a rotation grace window. Same dual-key pattern as
+     * PgSecretStore.decryptWithFallback / ephemeral-keys.decryptPrivateKey. The
+     * AAD stays `row.name` — ciphertext remains bound to its logical backend.
+     * Never called for sentinel rows (config_encrypted = '').
+     */
+    private decryptConfigWithFallback;
+    /** Loud, recovery-pointing error for a backend stranded by key rotation. */
+    private strandedError;
+    /**
+     * Re-seal a backend config that decrypted only under the old key back under
+     * the current master key. Runs at load time while KICI_SECRET_KEY_OLD is
+     * still configured, healing deployments that rotated before backend configs
+     * were part of the rotation sweep. The concurrent-rotation guard
+     * (`config_key_version` match) keeps a racing rotation from being clobbered.
+     */
+    private selfHealStrandedRow;
     /**
      * Register a new backend. Encrypts config and stores in DB.
      */
@@ -64,5 +83,17 @@ export declare class BackendRegistry {
      * Update sync status for a backend.
      */
     updateSyncStatus(name: string, scopeCount: number, error?: string): Promise<void>;
+    /**
+     * Re-encrypt every non-sentinel backend config under the current master key
+     * at max(config_key_version)+1. Same transactional skip-and-count shape as
+     * SharedConfigStore.rotateKey — an undecryptable row is counted and left in
+     * place (never aborts the sweep); recovery guidance lives in strandedError.
+     * Sentinel rows (config_encrypted = '') are excluded from the candidate set
+     * and never counted.
+     */
+    rotateKey(): Promise<{
+        reEncrypted: number;
+        skipped: number;
+    }>;
 }
 //# sourceMappingURL=backend-registry.d.ts.map

package/dist/secrets/context-secret-resolver.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Shared factory for the dispatch-time `SecretResolver` bound to the orchestrator's
+ * DB-backed context/binding/secret stores.
+ *
+ * Both boot paths use it: `server.ts` (platform/hybrid) always builds it, and
+ * `standalone.ts` (independent) builds it only when dispatch-time context-scoped
+ * secret resolution is explicitly opted in (the local dev plane). Keeping the
+ * ~one construction in one place stops the two call sites from drifting.
+ */
+import type { Kysely } from 'kysely';
+import type { SecretStore } from '@kici-dev/engine';
+import type { Logger } from '@kici-dev/shared';
+import type { Database } from '../db/types.js';
+import type { AuditLogger } from './audit-logger.js';
+import type { PgSecretStore } from './pg-secret-store.js';
+import { SecretResolver } from './secret-resolver.js';
+export interface ContextSecretResolverDeps {
+    pgSecretStore: PgSecretStore;
+    backendStores: Map<string, SecretStore>;
+    db: Kysely<Database>;
+    auditLogger: AuditLogger;
+    logger: Logger;
+}
+/**
+ * Build a `SecretResolver` over the org's contexts, bindings, and registered
+ * secret backends. The `pg` backend decrypts through the master key; external
+ * backends (Vault) return plaintext, so their decrypt is identity.
+ */
+export declare function buildContextSecretResolver(deps: ContextSecretResolverDeps): SecretResolver;
+//# sourceMappingURL=context-secret-resolver.d.ts.map

package/dist/secrets/dashboard-encryption-key.d.ts

@@ -0,0 +1,48 @@
+import { type JWK } from 'jose';
+import type { DashboardEncryptionKeyRepo } from '../db/repos/dashboard-encryption-keys-repo.js';
+export interface GeneratedDashboardEncryptionKey {
+    kid: string;
+    publicJwk: JWK;
+    /** AES-256-GCM-wrapped DER private key (master-key wrapped). */
+    encryptedPrivateKey: string;
+    /** DER-SPKI public key Buffer (for callers that need the raw bytes). */
+    publicKeyDer: Buffer;
+}
+/**
+ * Generate a fresh X25519 dashboard-encryption key: the OKP public JWK
+ * (`use:'enc'`, `kid` = RFC 7638 thumbprint) plus the master-key-wrapped
+ * private half.
+ */
+export declare function generateDashboardEncryptionKey(secretKey: string): Promise<GeneratedDashboardEncryptionKey>;
+export interface ReconcileDashboardEncryptionKeyDeps {
+    repo: Pick<DashboardEncryptionKeyRepo, 'getActiveRow' | 'upsertActive' | 'getByKid'>;
+    isLeader: () => boolean;
+    /** The orchestrator master key (`KICI_SECRET_KEY`), for db-custody wrapping. */
+    secretKey: string | undefined;
+    /** Called once when a NEW kid is first activated (audit log, system actor). */
+    audit: (info: {
+        kid: string;
+    }) => Promise<void> | void;
+}
+/** The resolved active dashboard-encryption key + a per-request decrypt closure. */
+export interface ResolvedDashboardEncryptionKey {
+    activeKid: string;
+    publicJwk: JWK;
+    /**
+     * Unwrap the DER private key for a given `kid` — the active key OR a
+     * rotated-out one whose row is still on record. The lookup is
+     * status-agnostic, so a revoked key that has left the published JWKS still
+     * decrypts; null means the kid is unknown (never minted, or its row was
+     * deleted). Reads the wrapped private half from the DB each call, so
+     * rotation is picked up without a restart.
+     */
+    decryptPrivateKeyDer: (kid: string) => Promise<Buffer | null>;
+}
+/**
+ * Ensure exactly one `active` dashboard-encryption key exists and return the
+ * resolved key + decrypt closure, or null when not yet ready (non-leader before
+ * the leader has generated it). Requires `KICI_SECRET_KEY` (throws otherwise —
+ * the private key is master-key wrapped, same posture as db-custody signing).
+ */
+export declare function reconcileDashboardEncryptionKey(deps: ReconcileDashboardEncryptionKeyDeps): Promise<ResolvedDashboardEncryptionKey | null>;
+//# sourceMappingURL=dashboard-encryption-key.d.ts.map

package/dist/secrets/ephemeral-keys.d.ts

@@ -46,4 +46,20 @@ export declare function decryptSecretOutput(envelope: {
     agentPublicKey: string;
     encrypted: string;
 }, runPrivateKeyDer: Buffer): string;
+/**
+ * Decrypt a browser-sealed dashboard write.
+ *
+ * Under the `encrypted` dashboard-write posture the browser seals the value to
+ * the orchestrator's published X25519 encryption key using the SAME
+ * ECDH → HKDF → AES-256-GCM envelope the agent uses for run secret outputs,
+ * but with the `kici-dashboard-sealed-write` HKDF info string.
+ *
+ * @param envelope - `{ ephemeralPublicKey: base64 DER-SPKI, encrypted: base64 IV||tag||ct }`
+ * @param encryptionPrivateKeyDer - DER-encoded orchestrator X25519 private key
+ * @returns Decrypted plaintext string
+ */
+export declare function decryptDashboardSealedWrite(envelope: {
+    ephemeralPublicKey: string;
+    encrypted: string;
+}, encryptionPrivateKeyDer: Buffer): string;
 //# sourceMappingURL=ephemeral-keys.d.ts.map

package/dist/secrets/index.d.ts

@@ -9,7 +9,7 @@ export { AuditLogger } from './audit-logger.js';
 export { loadMasterKey, loadOldMasterKey, loadSecretStoreConfig, type SecretStoreConfig, } from './config.js';
 export { encrypt, decrypt, deriveKey, generateMasterKey, type EncryptedValue, } from '@kici-dev/shared';
 export { VaultSecretStore, type VaultConfig } from './vault-secret-store.js';
-export { SecretResolver, type SecretResolverDeps, type ResolvedSecretMeta, type EnvironmentStoreLike, type BindingStoreLike, type SecretStoreLike, } from './secret-resolver.js';
+export { SecretResolver, type SecretResolverDeps, type ResolvedSecretMeta, type ContextStoreLike, type BindingStoreLike, type SecretStoreLike, } from './secret-resolver.js';
 export { BackendSyncManager } from './backend-sync.js';
 export { RbacEnforcer, PermissionDeniedError, type Role, type Permission } from './rbac.js';
 export { TokenManager } from './token-manager.js';

package/dist/secrets/pg-secret-store.d.ts

@@ -12,13 +12,23 @@ import type { SecretStore } from '@kici-dev/engine';
 import type { AuditLogger } from './audit-logger.js';
 /**
  * Thrown by `renameScope` when the named scope has no secret rows and no
- * environment binding — i.e. there is nothing to rename. Consumers map this to
+ * context binding — i.e. there is nothing to rename. Consumers map this to
  * a 404 (admin HTTP route) or a structured not-found response (dashboard path).
  */
 export declare class SecretScopeNotFoundError extends Error {
     readonly scope: string;
     constructor(scope: string);
 }
+/**
+ * Thrown by `renameScope` when the destination scope already holds secret rows
+ * or context bindings. Renaming onto it would merge two scopes rather than move
+ * one. The admin HTTP route maps it to a 409; the dashboard rename handler
+ * relays its message as the operation's error text.
+ */
+export declare class SecretScopeExistsError extends Error {
+    readonly scope: string;
+    constructor(scope: string);
+}
 /**
  * PostgreSQL secret store with AES-256-GCM encryption.
  * Uses scoped_secrets table keyed by (org_id, scope, key).
@@ -93,11 +103,11 @@ export declare class PgSecretStore implements SecretStore {
      */
     createScope(orgId: string, scope: string): Promise<void>;
     /**
-     * Rename a scope -- atomically update scoped_secrets and environment_bindings.
+     * Rename a scope -- atomically update scoped_secrets and context_bindings.
      */
     renameScope(orgId: string, oldScope: string, newScope: string): Promise<void>;
     /**
-     * Delete a scope and all its secrets, plus any environment bindings referencing it.
+     * Delete a scope and all its secrets, plus any context bindings referencing it.
      */
     deleteScope(orgId: string, scope: string): Promise<void>;
     /**

package/dist/secrets/rbac.d.ts

@@ -13,7 +13,11 @@ export type Role = 'owner' | 'admin' | 'auditor';
 /**
  * Permissions for the secrets management admin API.
  */
-export type Permission = 'context.create' | 'context.read' | 'context.update' | 'context.delete' | 'secret.read' | 'secret.write' | 'secret.delete' | 'secret.reveal' | 'audit.read' | 'token.manage' | 'key.rotate' | 'run.read' | 'run.cancel' | 'event_log.read' | 'event_log.read_payload' | 'access_log.read' | 'scheduled_job.trigger' | 'event_dlq.read' | 'event_dlq.manage';
+export type Permission = 'context.create' | 'context.read' | 'context.update' | 'context.delete' | 'secret.read' | 'secret.write' | 'secret.delete' | 'secret.reveal' | 'audit.read' | 'token.manage' | 'key.rotate' | 'run.read' | 'run.cancel' | 'event_log.read' | 'event_log.read_payload' | 'access_log.read' | 'scheduled_job.trigger' | 'attestation.retry' | 'event_dlq.read' | 'event_dlq.manage' | 'orchestrator.drain'
+/** Read the org-wide CI trust policy that gates fork / unknown / workflow-change PRs. */
+ | 'ci_trust.read'
+/** Modify org-wide trust policies (independent mode only — Platform-attached PATCH refuses). */
+ | 'ci_trust.admin';
 /**
  * Error thrown when a role lacks the required permission.
  */