@kici-dev/orchestrator 0.1.26 → 0.2.0

package/dist/oidc/orchestrator-mint.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Orchestrator-owned OIDC identity mint (production).
+ *
+ * Production sibling of `local-mint.ts`: the orchestrator mints the short-lived
+ * ES256 ID token for a build job LOCALLY from its own execution_runs/
+ * execution_jobs rows, signed with its own long-lived signing key (`Signer`),
+ * issued under its own real issuer. Zero hosted-Platform dependency.
+ *
+ * Anti-forgery is identical to the Platform-minted path and the local dev plane:
+ * every identity claim (run/job/repo/ref/sha/org) is read SERVER-SIDE from the
+ * orchestrator's own rows — never from the agent's wire input — and job ownership
+ * is resolved from dispatch state, never agent-asserted. The token is never
+ * logged.
+ */
+import type { Kysely } from 'kysely';
+import { type OidcTokenResult } from '@kici-dev/engine/protocol/messages/oidc-token-relay';
+import type { Database } from '../db/types.js';
+import { type IdTokenClaims } from './id-token-claims.js';
+import type { Signer } from './signer.js';
+/** The org anchor stamped when a run has no routing key (sourceless / local plane). */
+export declare const DEFAULT_ORG_ID = "__default__";
+/** ID-token lifetime (seconds). Matches the Platform's 10-minute cap. */
+export declare const ORCHESTRATOR_ID_TOKEN_TTL_SECONDS = 600;
+export declare class OrchestratorMintRunNotFoundError extends Error {
+}
+export declare class OrchestratorMintJobNotFoundError extends Error {
+}
+export declare class OrchestratorMintJobNotActiveError extends Error {
+}
+export interface OrchestratorMintDeps {
+    db: Kysely<Database>;
+    signer: Signer;
+    /** The orchestrator's own provenance issuer identity (real URL). */
+    issuer: string;
+    orchestratorId: string;
+    ttlSeconds?: number;
+    /** Injectable clock (seconds). Defaults to wall-clock. */
+    nowSeconds?: () => number;
+}
+export interface OrchestratorMintInput {
+    runId: string;
+    jobId: string;
+    audience: string;
+    /**
+     * Deferred-fulfilment mint: knowingly targets a completed (terminal) job and
+     * binds the frozen statement hash + origin so the terminal-job check is
+     * relaxed and the mint-timing marker is stamped. The live agent path never
+     * sets this.
+     */
+    deferred?: {
+        statementHash: string;
+        origin: 'deferred' | 'offline-backfill';
+    };
+}
+export interface OrchestratorMintResult {
+    token: string;
+    expiresIn: number;
+    jti: string;
+    claims: IdTokenClaims;
+}
+/**
+ * Mint a short-lived ES256 ID token for (run, job) from the orchestrator's own
+ * rows, signed with the orchestrator's signing key.
+ */
+export declare function mintOrchestratorIdToken(deps: OrchestratorMintDeps, input: OrchestratorMintInput): Promise<OrchestratorMintResult>;
+/** Job-ownership resolver surface (the dispatcher's `resolveOwnedJob`). */
+export interface OrchestratorMintOwnershipResolver {
+    resolveOwnedJob(agentId: string, jobId: string): {
+        runId: string;
+    } | undefined;
+}
+export declare class OrchestratorMintRejectedError extends Error {
+}
+/** unavailable: the signing key is not yet resolvable (leader election / cold start). */
+export declare class OrchestratorMintSignerUnavailableError extends Error {
+}
+export interface OrchestratorOidcTokenHandlerDeps {
+    dispatcher: OrchestratorMintOwnershipResolver;
+    /**
+     * Lazily resolve the orchestrator's signing key. Resolved on first token
+     * request (not at boot) so it is unaffected by the Raft leader-election race —
+     * by the time an agent requests a token the cluster has a leader and the key
+     * exists. May return null while the key is still being reconciled.
+     */
+    resolveSigner: () => Promise<Signer | null>;
+    /** Mint deps except the signer (supplied lazily via `resolveSigner`). */
+    mint: Omit<OrchestratorMintDeps, 'signer'>;
+}
+/**
+ * Build the agent.api handler for `OIDC_TOKEN_REQUEST_METHOD` when the
+ * orchestrator owns its signing key. Verifies the agent owns the named job
+ * (resolving its runId from the dispatcher — never an agent-asserted value),
+ * resolves the signing key lazily, then mints locally. A job the agent does not
+ * own is rejected without minting; an unresolved signer defers (never crashes).
+ */
+export declare function createOrchestratorOidcTokenHandler(deps: OrchestratorOidcTokenHandlerDeps): (agentId: string, params: Record<string, unknown>) => Promise<OidcTokenResult>;
+//# sourceMappingURL=orchestrator-mint.d.ts.map

package/dist/oidc/orchestrator-signer-factory.d.ts

@@ -0,0 +1,33 @@
+import { z } from 'zod';
+import type { Signer } from './signer.js';
+/** Custody backend for the orchestrator provenance signing key. */
+export declare const OrchestratorSignerKind: z.ZodEnum<{
+    "aws-kms": "aws-kms";
+    command: "command";
+    db: "db";
+}>;
+export type OrchestratorSignerKind = z.infer<typeof OrchestratorSignerKind>;
+/** The config slice the signer factory reads (subset of the orchestrator config). */
+export interface OrchestratorSignerConfig {
+    /** When set, provenance signing is ON (the issuer identity). */
+    provenanceSigningIssuer?: string;
+    /** Custody kind; defaults to `db` when signing is on. */
+    provenanceSignerKind?: string;
+    provenanceKmsKeyArn?: string;
+    provenanceKmsRegion?: string;
+    provenanceKmsAccessKeyId?: string;
+    provenanceKmsSecretAccessKey?: string;
+    provenanceSignerCommand?: string;
+}
+/** True iff orchestrator-owned provenance signing is configured (issuer set). */
+export declare function isProvenanceSigningEnabled(cfg: OrchestratorSignerConfig): boolean;
+/** Resolve the configured custody kind (defaulting to `db`). Throws on an invalid value. */
+export declare function resolveSignerKind(cfg: OrchestratorSignerConfig): OrchestratorSignerKind;
+/**
+ * Build a NON-`db` (external-custody) signer from config. Returns null for `db`
+ * custody (whose generate-or-load lives in the boot reconcile, since the private
+ * key is created + persisted in the DB) and null when signing is off. Throws
+ * when an external kind is selected but its required config is incomplete.
+ */
+export declare function buildExternalSigner(cfg: OrchestratorSignerConfig): Promise<Signer | null>;
+//# sourceMappingURL=orchestrator-signer-factory.d.ts.map

package/dist/oidc/reconcile-signing-key.d.ts

@@ -0,0 +1,21 @@
+import { type OrchestratorSignerConfig } from './orchestrator-signer-factory.js';
+import type { Signer } from './signer.js';
+import type { OrchestratorSigningKeyRepo } from '../db/repos/signing-keys-repo.js';
+export interface ReconcileSigningKeyDeps {
+    repo: Pick<OrchestratorSigningKeyRepo, 'getActiveRow' | 'upsertActive'>;
+    config: OrchestratorSignerConfig;
+    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;
+        signerKind: string;
+        keyRef: string | null;
+    }) => Promise<void> | void;
+}
+/** Reconcile + return the active signer, or null when signing is off / not yet ready. */
+export declare function reconcileOrchestratorSigningKey(deps: ReconcileSigningKeyDeps): Promise<{
+    signer: Signer;
+} | null>;
+//# sourceMappingURL=reconcile-signing-key.d.ts.map

package/dist/oidc/signer.d.ts

@@ -0,0 +1,25 @@
+import { type JWK } from 'jose';
+/**
+ * Provider-agnostic signing seam for orchestrator-owned provenance. Verifiers
+ * never see which implementation runs (`db` / `aws-kms` / `command`). Ported from
+ * the Platform's `oidc/signer.ts` so the two stacks stay byte-compatible.
+ */
+export interface Signer {
+    /** JOSE alg of the produced signatures. */
+    readonly alg: 'ES256';
+    /** Backend discriminator persisted on the key row (db | aws-kms | command). */
+    readonly signerKind: string;
+    /** Provider-neutral key locator persisted on the row (KMS ARN, signer command, or null for db). */
+    readonly keyRef: string | null;
+    /** Sign `data` and return the JOSE-raw (r||s) ES256 signature. */
+    sign(data: Uint8Array): Promise<Uint8Array>;
+    /** The public key as a JWK (kty EC, crv P-256, alg ES256, use sig, kid). */
+    getPublicJwk(): Promise<JWK>;
+    /** RFC 7638 thumbprint of the public JWK. */
+    getKid(): Promise<string>;
+}
+/** Convert a DER-encoded ECDSA signature (KMS output) to JOSE-raw r||s of `size`*2 bytes. */
+export declare function derToRawEcdsaSignature(der: Uint8Array, size?: number): Uint8Array;
+/** Build the public JWK (with kid + alg + use) from a DER SPKI public key (KMS GetPublicKey output). */
+export declare function derSpkiToPublicJwk(spkiDer: Uint8Array): Promise<JWK>;
+//# sourceMappingURL=signer.d.ts.map

package/dist/oidc/signing-key-status.d.ts

@@ -0,0 +1,23 @@
+import { z } from 'zod';
+/**
+ * Lifecycle of an orchestrator provenance signing key
+ * (orchestrator_signing_keys.status). Mirrors the Platform's status model so the
+ * rotation / retire / revoke semantics are identical.
+ *
+ *  - active   — the one current signing key.
+ *  - retiring — just rotated out; still in the JWKS during the overlap window
+ *               (in-flight short-lived JWTs minted just before rotation verify).
+ *  - retired  — no longer signs, but its public half STAYS in the trust root so
+ *               historical attestations it signed remain verifiable. retired != removed.
+ *  - revoked  — compromised; REMOVED from the trust root; everything it signed is distrusted.
+ */
+export declare const SigningKeyStatus: z.ZodEnum<{
+    active: "active";
+    retired: "retired";
+    retiring: "retiring";
+    revoked: "revoked";
+}>;
+export type SigningKeyStatus = z.infer<typeof SigningKeyStatus>;
+/** Statuses served in the JWKS / trusted for verification (everything except revoked). */
+export declare const TRUSTED_STATUSES: readonly SigningKeyStatus[];
+//# sourceMappingURL=signing-key-status.d.ts.map

package/dist/orchestrator-core.d.ts

@@ -21,19 +21,27 @@ import { Dispatcher } from './agent/dispatcher.js';
 import { LockFileCache } from './lockfile-cache.js';
 import { DedupCache } from './webhook/dedup.js';
 import { ObserverRegistry } from './ws/observer-registry.js';
+import { IngestAdmissionController } from './webhook/ingest-admission.js';
+import { type OrgIngestCapReader } from './webhook/org-ingest-cap-reader.js';
+import { type SandboxAllowListReader } from './pipeline/sandbox-allowlist-reader.js';
+import { IngestOverflowBuffer } from './webhook/ingest-overflow-buffer.js';
+import { IngestOverflowReplayer } from './webhook/ingest-overflow-replayer.js';
 import { AgentMetricsAggregator } from './metrics/agent-metrics-aggregator.js';
 import { SourceLocationStore } from './app.js';
-import { ExecutionJobStatus, type LabelMatcher, type PeerHeartbeat, type PeerLogsCollectRequest, type PeerToPeerMessage } from '@kici-dev/engine';
+import { ExecutionJobStatus, type LabelMatcher, type PeerHeartbeat, type PeerLogsCollectRequest, type PeerToPeerMessage, type ResolvedSandboxGrant } from '@kici-dev/engine';
 import { ScalerManager } from './scaler/index.js';
 import type { ScalerConfig } from './scaler/index.js';
 import type { CacheStorage } from './storage/index.js';
 import { type ProvenanceTrustRoot } from './provenance/trust-root.js';
+import { type ResolvedDashboardEncryptionKey } from './secrets/dashboard-encryption-key.js';
 import { SourceCache, BuildCoordinator, DepCache, UserCache, DispatchCacheRefTracker, PendingBuildTracker, PendingInitTracker, PendingDynamicTracker } from './cache/index.js';
+import { ArtifactStore } from './artifacts/artifact-store.js';
 import { CheckRunReporter } from './reporting/check-run-reporter.js';
 import { StepLogBuffer } from './reporting/step-log-buffer.js';
 import { type LogStorage } from './reporting/log-storage.js';
 import { ExecutionTracker, type ExecutionTrackerDeps } from './reporting/execution-tracker.js';
 import { LogWriter } from './reporting/log-writer.js';
+import { type NormalizedLogChunk } from './reporting/log-chunk-sink.js';
 import { PeerRegistry, PeerClient, createPeerHandler, RaftNode, OrphanRecovery, RunCoordinator } from './cluster/index.js';
 import { SourceStore, SourceManager } from './sources/index.js';
 import { PgSecretStore, AuditLogger, SecretResolver } from './secrets/index.js';
@@ -51,6 +59,7 @@ import { RegistrationStore } from './registration/registration-store.js';
 import { RegistrationIndex } from './registration/registration-index.js';
 import { CronScheduler } from './cron/cron-scheduler.js';
 import { ProviderRegistry } from './provider-registry.js';
+import { ClusterSettingsReader } from './cluster/cluster-settings-reader.js';
 import { JoinHandler } from './cluster/join-handler.js';
 import type { Kysely } from 'kysely';
 import type { Database } from './db/types.js';
@@ -63,6 +72,8 @@ export interface OrchestratorSubsystems {
     config: AppConfig;
     db: Kysely<Database>;
     pool: pg.Pool;
+    /** Cluster-global settings reader (fleet-wide tunables on cluster_settings). */
+    clusterSettings: ClusterSettingsReader;
     providerRegistry: ProviderRegistry;
     agentRegistry: AgentRegistry;
     hostRosterStore: HostRosterStore;
@@ -80,6 +91,7 @@ export interface OrchestratorSubsystems {
     sourceCache: SourceCache | undefined;
     depCache: DepCache | undefined;
     userCache: UserCache | undefined;
+    artifactStore: ArtifactStore | undefined;
     /** Server-side jobId -> user-cache-namespace store, written at dispatch, read by the agent-WS handler. */
     dispatchCacheRefs: DispatchCacheRefTracker;
     buildCoordinator: BuildCoordinator | undefined;
@@ -96,6 +108,14 @@ export interface OrchestratorSubsystems {
     secretResolver: SecretResolver | null;
     adminDeps: AdminRouteDeps | undefined;
     pgSecretStore: PgSecretStore | undefined;
+    /**
+     * Dashboard-encryption (X25519) key resolver for browser-sealed dashboard
+     * writes under the `encrypted` posture. Present whenever KICI_SECRET_KEY is
+     * configured; absent ⇒ `encrypted` writes fail closed at the WS handler.
+     */
+    dashboardEncryption: {
+        resolve: () => Promise<ResolvedDashboardEncryptionKey | null>;
+    } | undefined;
     tokenStore: AgentTokenStore;
     ownershipTracker: OwnershipTracker;
     lockFileCache: LockFileCache;
@@ -163,6 +183,16 @@ export interface OrchestratorSubsystems {
      * no-op.
      */
     fleetCollectResponder: (msg: PeerLogsCollectRequest, send: (out: PeerToPeerMessage) => boolean) => Promise<void>;
+    /** Shared webhook-ingest admission controller (HTTP + WS relay paths). */
+    ingestController: IngestAdmissionController;
+    /** Cached per-org ingest cap reader for admission fairness keying. */
+    ingestCapReader: OrgIngestCapReader;
+    /** Cached per-org container-sandbox escape-hatch allow-list reader (dispatch). */
+    sandboxAllowListReader: SandboxAllowListReader;
+    /** Durable overflow buffer capturing shed deliveries (HTTP + WS relay). */
+    ingestOverflowBuffer: IngestOverflowBuffer;
+    /** Background replayer draining the overflow buffer once capacity recovers. */
+    ingestOverflowReplayer: IngestOverflowReplayer;
 }
 /**
  * Mode-specific hooks injected by each entry point.
@@ -179,8 +209,15 @@ export interface OrchestratorHooks {
         onStepStatusForward?: ExecutionTrackerDeps['onStepStatusForward'];
         onJobStatusChange?: ExecutionTrackerDeps['onJobStatusChange'];
         onRunEventEmit?: ExecutionTrackerDeps['onRunEventEmit'];
+        onOrchLog?: ExecutionTrackerDeps['onOrchLog'];
         orgId?: string;
     };
+    /**
+     * Forward a step-log chunk to the Platform for browser fan-out. Implemented
+     * by modes that hold a Platform connection; left undefined in independent
+     * mode, where logs are persisted but not relayed.
+     */
+    forwardLogChunk?: (chunk: NormalizedLogChunk) => void;
     /**
      * Called after the secrets subsystem is initialized.
      * Server.ts uses this to create SecretResolver; standalone doesn't.
@@ -322,7 +359,10 @@ export declare function mergeUpstreamOutputs(db: Kysely<Database>, runId: string
     upstreamJobOutputs: Record<string, Record<string, unknown>> | undefined;
     upstreamJobStatuses: Record<string, ExecutionJobStatus> | undefined;
 }>;
-export declare function buildInternalJobConfigForWorkflow(workflow: any, job: any): Record<string, unknown>;
+export declare function buildInternalJobConfigForWorkflow(workflow: any, job: any, sandboxGrant?: ResolvedSandboxGrant, firedSchedule?: {
+    cronExpression?: string;
+    timezone?: string;
+}): Record<string, unknown>;
 export declare function bootstrapOrchestrator(config: AppConfig, hooks: OrchestratorHooks, options?: {
     otelSdk?: {
         shutdown(): Promise<void>;

package/dist/pipeline/decorating-secret-resolver.d.ts

@@ -1,16 +1,17 @@
 /**
  * CLI-secret overlay for `kici run` test dispatch.
  *
- * Wraps the orchestrator's environment `SecretResolver` and overlays the
+ * Wraps the orchestrator's context `SecretResolver` and overlays the
  * developer's CLI-uploaded local secrets on top of the env-resolved secrets,
  * with CLI winning on collision. Passed to the shared dispatch core via
  * `ProcessingDeps.secretResolver`, so the core's secret-resolution path is
  * unchanged and oblivious to "test secrets".
  *
- * Precedence: env-resolved secrets → CLI context for the requested environment
+ * Precedence: env-resolved secrets → CLI context for the requested context
  * → CLI flat. The CLI flat overlay is applied last so a CLI flat key always
  * wins.
  */
+import type { HostFacts } from '@kici-dev/engine';
 import type { SecretResolverApi, ResolvedSecretMeta } from '../secrets/secret-resolver.js';
 /** Decrypted CLI-uploaded local secrets: flat keys + per-context namespaces. */
 export interface CliSecrets {
@@ -21,12 +22,12 @@ export declare class DecoratingSecretResolver implements SecretResolverApi {
     private readonly base;
     private readonly cli;
     constructor(base: SecretResolverApi, cli: CliSecrets);
-    resolveForJob(orgId: string, environmentName: string): Promise<Record<string, string>>;
+    resolveForJob(orgId: string, contextName: string, hostCtx?: HostFacts): Promise<Record<string, string>>;
     resolveNamed(orgId: string, scope: string, key: string, opts?: {
         store?: string;
         runId?: string;
         jobId?: string;
     }): Promise<string | null>;
-    resolveForJobWithMeta(orgId: string, environmentName: string): Promise<Record<string, ResolvedSecretMeta>>;
+    resolveForJobWithMeta(orgId: string, contextName: string, hostCtx?: HostFacts): Promise<Record<string, ResolvedSecretMeta>>;
 }
 //# sourceMappingURL=decorating-secret-resolver.d.ts.map

package/dist/pipeline/dispatch-matched-workflow.d.ts

@@ -3,7 +3,7 @@
  *
  * Handles everything that happens AFTER a workflow has been matched against an
  * incoming webhook: payload storage, cache + build coordination, secret
- * resolution, per-job environment evaluation, static job dispatch (cluster +
+ * resolution, per-job context evaluation, static job dispatch (cluster +
  * single-orch paths), execution-tracker registration, deferred init dispatch
  * for jobs with dynamic fields, and deferred dynamic-job-fn dispatch for
  * `_type:'dynamic'` lock entries.
@@ -21,6 +21,7 @@ import type { ProviderBundle } from '../provider-registry.js';
 import type { Dispatcher } from '../agent/dispatcher.js';
 import type { QueuedJobInput } from '../queue/job-queue.js';
 import type { TrustResolution } from '../security/trust-resolver.js';
+import type { TrustPolicyOutcome } from '../security/trust-policy-gate.js';
 import { type ProcessingDeps } from './processor.js';
 /**
  * Trusted refs (write+ contributor, default-branch) get the org-shared cache
@@ -75,6 +76,28 @@ export interface WorkflowDispatchContext {
     localWorkingTree: boolean;
     /** True only when invoked from the cross-source dispatch shell. */
     crossSource: boolean;
+    /**
+     * Outcome of the org trust-policy gate for this PR event. `pass` dispatches
+     * normally; `hold` parks the run in the security queue; `reject` fails it
+     * before any job starts. Computed once per PR event in the webhook pipeline
+     * and threaded down; the dispatch gate acts on it directly, see
+     * `holdRunForSecurityPolicy` / `rejectRunForSecurityPolicy`.
+     *
+     * REQUIRED: a dispatch path that does not state a decision must not compile.
+     * This field was optional once and the gate read `if (!decision) return
+     * null`, so forgetting to thread it meant the run passed the security gate —
+     * fail-open by omission inside a fail-closed control. A `pass` is stated
+     * explicitly.
+     */
+    securityDecision: TrustPolicyOutcome;
+    /**
+     * Set when this dispatch call took a pending-jobs token for the source-pack
+     * build window. Tokens are fungible, so the `finally` must release only one
+     * it actually took — an unpaired release would consume a token held by a
+     * deferred init / dynamic task and un-hold the run while its jobs are still
+     * being registered.
+     */
+    buildWindowTokenHeld?: boolean;
     /** Composite dedup key `${info.deliveryId}:${reg.id}` (cross-source only). */
     crossSourceDeliveryId?: string;
     /**
@@ -113,7 +136,7 @@ export interface WorkflowDispatchContext {
      * Run-wide flat secrets layered onto EVERY dispatched job's `jobConfig.secrets`
      * (env-declaring or not). Used by the test path to deliver `kici run --secret`
      * / `--env` CLI flat secrets, which must reach a job regardless of whether it
-     * declares an `environment:`. Merged UNDER the per-job env-resolved secrets so
+     * declares an `context:`. Merged UNDER the per-job env-resolved secrets so
      * the CLI value wins on a key collision (matching the prior B1-env -> A-CLI
      * precedence). Undefined for webhook runs.
      */
@@ -131,6 +154,13 @@ export interface WorkflowDispatchContext {
      */
     dispatchInputs?: Record<string, unknown>;
 }
+/**
+ * Build the dispatch-envelope event, carrying the orchestrator's already-fetched
+ * changed-files list + status from `eventWithFiles` as a fast-path (the agent
+ * recomputes from the clone when status !== 'fetched', so this only forfeits the
+ * optimization when a path is missed — correctness comes from the agent).
+ */
+export declare function envelopeEvent(baseEvent: SimulatedEvent, eventWithFiles: SimulatedEvent): SimulatedEvent;
 export interface DispatchMatchedWorkflowResult {
     /** Number of jobs successfully dispatched (non-rejected). */
     dispatchedJobCount: number;
@@ -140,7 +170,7 @@ export interface DispatchMatchedWorkflowResult {
     held?: boolean;
     /**
      * User-visible warnings aggregated from dispatched jobs — today, one per job
-     * whose bound test-run environment(s) were unavailable and skipped. Surfaced
+     * whose bound test-run context(s) were unavailable and skipped. Surfaced
      * on the accepted trigger response so the CLI can print them.
      */
     envWarnings?: string[];
@@ -296,6 +326,17 @@ export declare function materializeStaticJobsSafe(staticJobs: readonly LockJob[]
     expansionMap: Map<string, readonly string[]>;
     matrixFailures: RejectedJob[];
 }>;
+/**
+ * Scan a lock workflow's always-mode approval timeouts (workflow-level +
+ * each static job) for a non-positive / non-finite `timeoutSeconds`. Returns the
+ * first offender or null. Step-scope approvals ride the validated
+ * `step.approval-request` wire schema and are not checked here.
+ */
+export declare function findInvalidApprovalTimeout(workflow: LockWorkflow): {
+    scope: 'workflow' | 'job';
+    jobName?: string;
+    value: number;
+} | null;
 /**
  * Build the per-host secret-resolution context for a materialized child. A
  * `runsOnAll` host child carries its identity on `mat.agent` (preferred) or

package/dist/pipeline/inline-eval.d.ts

@@ -36,8 +36,8 @@ export declare function evaluateInlineRecord(expression: string, event: object):
  * failures are immediate dispatch failures (no init-job fallback).
  */
 export declare function evaluateInlineFields(lockJob: LockJob, event: object): {
-    /** Resolved name per `environments` element, aligned by index; undefined for static or impure-dynamic elements. */
-    inlineEnvironmentNames: Array<string | undefined>;
+    /** Resolved name per `contexts` element, aligned by index; undefined for static or impure-dynamic elements. */
+    inlineContextNames: Array<string | undefined>;
     inlineEnv: Record<string, string> | undefined;
     inlineConcurrencyGroup: string | undefined;
 };

package/dist/pipeline/install-secrets-resolver.d.ts

@@ -4,10 +4,10 @@
  * private registries.
  *
  * Each `tokenSecret` / `installEnv[]` entry uses the qualified
- * `<environment>:<secret-name>` syntax. The resolver:
+ * `<context>:<secret-name>` syntax. The resolver:
  *
- *   1. Parses every qualified ref and groups by environment name.
- *   2. Fires the per-environment protection-rule pipeline once per unique env
+ *   1. Parses every qualified ref and groups by context name.
+ *   2. Fires the per-context protection-rule pipeline once per unique env
  *      (branch / trust / concurrency / reviewer / wait-timer). A `reject`
  *      result fails the whole workflow dispatch with a clear reason; a
  *      `hold` / `wait` / `queue` result returns a structured `hold` decision
@@ -15,13 +15,13 @@
  *      run and resume it when the gate clears. On the resume path the caller
  *      sets `skipProtectionGate` so the gate (already satisfied) is bypassed
  *      and secrets are resolved directly.
- *   3. Resolves secrets per environment via `secretResolver.resolveForJob`
+ *   3. Resolves secrets per context via `secretResolver.resolveForJob`
  *      (which writes its own audit log lines).
  *   4. Validates each registry URL scheme: HTTPS always allowed; `http://`
  *      allowed only for loopback / `*.local` hosts OR when the org operator
  *      has flipped `org_settings.allow_http_npm_registries=true`.
  *   5. Strips the resolved auth entirely when the contributor-trust tier is
- *      not `trusted` (defense in depth: even if a misconfigured environment
+ *      not `trusted` (defense in depth: even if a misconfigured context
  *      lets an unknown contributor through the protection-pipeline trust
  *      gate, this strip ensures fork PRs never see registry tokens — the
  *      install fails naturally because the deps are unreachable).
@@ -32,8 +32,8 @@
 import type { ApproverClause, LockRegistry } from '@kici-dev/engine';
 import type { TrustResolution } from '../security/trust-resolver.js';
 import type { SecretResolverApi } from '../secrets/secret-resolver.js';
-import type { EnvironmentStore } from '../environments/environment-store.js';
-import { type JobDispatchContext } from '../environments/protection/pipeline.js';
+import type { ContextStore } from '../contexts/context-store.js';
+import { type JobDispatchContext } from '../contexts/protection/pipeline.js';
 /** Registry spec carried on the dispatch message (token already resolved). */
 export interface NpmRegistrySpec {
     url: string;
@@ -47,7 +47,7 @@ export interface ResolveInstallSecretsArgs {
     allowHttpNpmRegistries: boolean;
     resolvedOrgId: string;
     trustResolution: TrustResolution | undefined;
-    environmentStore: EnvironmentStore | undefined;
+    contextStore: ContextStore | undefined;
     secretResolver: SecretResolverApi | undefined;
     protectionContext: JobDispatchContext;
     /**
@@ -75,16 +75,16 @@ export type ResolveInstallSecretsResult = {
     decision: 'hold';
     /** The gate action that paused the dispatch. */
     action: 'hold' | 'wait' | 'queue';
-    /** The environment whose install gate held. */
+    /** The context whose install gate held. */
     envName: string;
-    /** Resolved environment id (for the held row). */
-    environmentId: string;
-    /** Discriminates the release trigger: 'reviewer' | 'wait_timer' | 'concurrency' | 'security'. */
+    /** Resolved context id (for the held row). */
+    contextId: string;
+    /** Discriminates the release trigger — an engine `HoldType` member. */
     holdType: string;
-    queueType: 'environment' | 'security';
+    queueType: 'context' | 'security';
     requirement: InstallHoldRequirement;
 };
-/** Parse `<environment>:<secret-name>`. Returns null on malformed input. */
+/** Parse `<context>:<secret-name>`. Returns null on malformed input. */
 export declare function parseQualifiedSecretRef(ref: string): {
     envName: string;
     secretName: string;
@@ -96,5 +96,16 @@ export declare function validateRegistryUrlScheme(url: string, allowHttp: boolea
     ok: false;
     reason: string;
 };
+/**
+ * The held-run `hold_type` for a gate outcome — the gate's own `holdType` when
+ * it set one, otherwise the `HoldType` member its action implies. Column and
+ * gate share one vocabulary, so nothing is translated here.
+ *
+ * Distinct from the engine's `normalizePersistedHoldType`, which maps a value
+ * read back OUT of the column onto that same vocabulary.
+ *
+ * Exported for tests.
+ */
+export declare function resolveHoldType(action: 'hold' | 'wait' | 'queue', raw: string | undefined): string;
 export declare function resolveInstallSecrets(args: ResolveInstallSecretsArgs): Promise<ResolveInstallSecretsResult>;
 //# sourceMappingURL=install-secrets-resolver.d.ts.map

package/dist/pipeline/{job-environments.d.ts → job-contexts.d.ts}

@@ -1,59 +1,59 @@
 /**
- * Multi-environment resolution helpers for the dispatch path.
+ * Multi-context resolution helpers for the dispatch path.
  *
- * A job binds an ordered list of environments (`LockJob.environments`). This
- * module resolves that list into concrete environment names (static values
+ * A job binds an ordered list of contexts (`LockJob.contexts`). This
+ * module resolves that list into concrete context names (static values
  * verbatim, pure-inline dynamic elements evaluated against the event) and folds
- * the per-environment secrets/variables last-wins. It keeps the heavy fold logic
+ * the per-context secrets/variables last-wins. It keeps the heavy fold logic
  * out of `dispatchMatchedWorkflow`, which must stay under the function-length cap.
  */
-import { type Environment, type HostFacts, type LockJob } from '@kici-dev/engine';
+import { type Context, type HostFacts, type LockJob } from '@kici-dev/engine';
 import type { SecretResolverApi } from '../secrets/secret-resolver.js';
-import type { VariableStore } from '../environments/variable-store.js';
+import type { VariableStore } from '../contexts/variable-store.js';
 /**
  * Placeholder written into the persisted bound-env list for an impure dynamic
  * element the orchestrator cannot resolve at dispatch. The agent's init eval
  * later overwrites the list with the resolved name.
  */
 export declare const DYNAMIC_ENV_PLACEHOLDER = "(dynamic)";
-/** Ordered resolved environment names plus whether any element still needs agent init. */
-export interface ResolvedJobEnvironments {
+/** Ordered resolved context names plus whether any element still needs agent init. */
+export interface ResolvedJobContexts {
     /** Resolved static + pure-inline names, in order. */
     names: string[];
     /** True when an impure dynamic element must be resolved by an agent init job. */
     needsInit: boolean;
 }
 /**
- * Resolve the ordered bound-environment names from a lock job. Static elements
+ * Resolve the ordered bound-context names from a lock job. Static elements
  * use their value verbatim; pure-inline dynamic elements use the matching
  * pre-evaluated inline name (aligned by index); an impure dynamic element cannot
  * be resolved here and flags `needsInit`.
  */
-export declare function resolveJobEnvironmentNames(lockJob: LockJob, inlineNames: ReadonlyArray<string | undefined>): ResolvedJobEnvironments;
+export declare function resolveJobContextNames(lockJob: LockJob, inlineNames: ReadonlyArray<string | undefined>): ResolvedJobContexts;
 /**
- * Build the ordered bound-environment display list for persistence at dispatch.
- * Unlike {@link resolveJobEnvironmentNames}, this never drops an unresolved
+ * Build the ordered bound-context display list for persistence at dispatch.
+ * Unlike {@link resolveJobContextNames}, this never drops an unresolved
  * element: a static element uses its value, a pure-inline element uses its
  * resolved name when known, and any element the orchestrator cannot resolve at
  * dispatch (impure dynamic, or an unresolved pure-inline) becomes the
  * `(dynamic)` placeholder — so the persisted column reflects every declared
- * slot in order. Returns an empty array when the job binds no environment.
+ * slot in order. Returns an empty array when the job binds no context.
  */
-export declare function buildJobEnvironmentDisplayNames(lockJob: LockJob, inlineNames: ReadonlyArray<string | undefined>): string[];
-/** Merged secrets/variables across an ordered list of resolved environments. */
+export declare function buildJobContextDisplayNames(lockJob: LockJob, inlineNames: ReadonlyArray<string | undefined>): string[];
+/** Merged secrets/variables across an ordered list of resolved contexts. */
 export interface MultiEnvMergedData {
-    environmentVars?: Record<string, string>;
+    contextVars?: Record<string, string>;
     jobSecrets?: Record<string, string>;
     jobNamespacedSecrets?: Record<string, Record<string, string>>;
 }
 /**
  * Resolve and fold variables + secrets across the ordered list of matched
- * environments, last-wins. Each environment is resolved with the existing
- * single-env logic (longest-scope-path-wins preserved within each environment),
- * then folded in array order so a later environment overrides an earlier key.
- * Secrets are also returned namespaced per environment so qualified
+ * contexts, last-wins. Each context is resolved with the existing
+ * single-env logic (longest-scope-path-wins preserved within each context),
+ * then folded in array order so a later context overrides an earlier key.
+ * Secrets are also returned namespaced per context so qualified
  * `<env>:<secret>` references still resolve. `entries` carries the matched
- * `Environment` for each name (in order); variables resolve by environment id.
+ * `Context` for each name (in order); variables resolve by context id.
  */
 export declare function resolveMultiEnvMergedData(args: {
     deps: {
@@ -63,9 +63,9 @@ export declare function resolveMultiEnvMergedData(args: {
     orgId: string;
     entries: ReadonlyArray<{
         name: string;
-        env: Environment;
+        env: Context;
     }>;
     hostCtx?: HostFacts;
     routingKey?: string;
 }): Promise<MultiEnvMergedData>;
-//# sourceMappingURL=job-environments.d.ts.map
+//# sourceMappingURL=job-contexts.d.ts.map