@kici-dev/orchestrator 0.1.27 → 0.3.0

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

@@ -11,6 +11,7 @@
  * → 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, contextName: 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, contextName: 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

@@ -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;
     /**
@@ -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;
@@ -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/install-secrets-resolver.d.ts

@@ -79,7 +79,7 @@ export type ResolveInstallSecretsResult = {
     envName: string;
     /** Resolved context id (for the held row). */
     contextId: string;
-    /** Discriminates the release trigger: 'reviewer' | 'wait_timer' | 'concurrency' | 'security'. */
+    /** Discriminates the release trigger — an engine `HoldType` member. */
     holdType: string;
     queueType: 'context' | 'security';
     requirement: InstallHoldRequirement;
@@ -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/manual-schedule.d.ts

@@ -9,7 +9,7 @@
  * eventRouter fire-and-forget. The manual path needs request/response
  * correlation to return the newRunId to the dashboard.
  */
-import type { LockWorkflow, MaterializedJob } from '@kici-dev/engine';
+import type { LockScheduleTrigger, LockWorkflow, MaterializedJob } from '@kici-dev/engine';
 import type { RerunDeps } from './rerun.js';
 import type { RegistrationIndex } from '../registration/registration-index.js';
 interface ManualScheduleDeps extends RerunDeps {
@@ -25,19 +25,14 @@ export declare function handleManualSchedule(registrationId: string, triggeredBy
 requestId: string): Promise<{
     newRunId: string;
 }>;
+/**
+ * A manual "fire now" targets no specific schedule, so merge the declared
+ * default inputs across ALL of the workflow's schedule triggers (later triggers
+ * win on key collision) rather than arbitrarily taking the first. Returns
+ * undefined when no schedule declares resolvable inputs.
+ */
+export declare function mergeScheduleInputs(scheduleTriggers: LockScheduleTrigger[]): Record<string, unknown> | undefined;
 export declare function buildManualJobConfig(workflow: LockWorkflow, mat: MaterializedJob): {
-    resolvedHashFiles?: string[] | undefined;
-    contentHash?: string | undefined;
-    dispatchInputs?: Record<string, unknown> | undefined;
-    steps: readonly import("@kici-dev/engine").LockStepEntry[];
-    needs: readonly (string | {
-        name: string;
-        runOn: ("success" | "pending" | "failed" | "recovering" | "running" | "queued" | "skipped" | "cancelled" | "cancelling" | "timed_out_stale" | "drift_dropped")[];
-    } | {
-        group: string;
-        runOn: ("success" | "pending" | "failed" | "recovering" | "running" | "queued" | "skipped" | "cancelled" | "cancelling" | "timed_out_stale" | "drift_dropped")[];
-    })[];
-    rules: readonly import("@kici-dev/engine").LockRule[] | undefined;
     name: string;
     baseJobName: string;
     matrixValues?: import("@kici-dev/engine").MatrixValues;
@@ -45,6 +40,18 @@ export declare function buildManualJobConfig(workflow: LockWorkflow, mat: Materi
     fanoutTotal?: number;
     source: import("@kici-dev/engine").LockSource | undefined;
     workflowName: string;
+    steps: readonly import("@kici-dev/engine").LockStepEntry[];
+    needs: readonly (string | {
+        name: string;
+        runOn: ("cancelled" | "cancelling" | "drift_dropped" | "failed" | "pending" | "queued" | "recovering" | "running" | "skipped" | "success" | "timed_out_stale" | "unroutable")[];
+    } | {
+        group: string;
+        runOn: ("cancelled" | "cancelling" | "drift_dropped" | "failed" | "pending" | "queued" | "recovering" | "running" | "skipped" | "success" | "timed_out_stale" | "unroutable")[];
+    })[];
+    rules: readonly import("@kici-dev/engine").LockRule[] | undefined;
+    dispatchInputs?: Record<string, unknown> | undefined;
+    contentHash?: string | undefined;
+    resolvedHashFiles?: string[] | undefined;
 };
 export {};
 //# sourceMappingURL=manual-schedule.d.ts.map

package/dist/pipeline/pending-workflow-context.d.ts

@@ -12,7 +12,7 @@
  * Writes to both an in-memory Map (fast read on the same process) and the DB
  * (crash recovery + cross-orchestrator read), mirroring the pending-job store.
  */
-import type { Kysely } from 'kysely';
+import { type Kysely } from 'kysely';
 import type { Database } from '../db/types.js';
 import type { WorkflowDispatchContext } from './dispatch-matched-workflow.js';
 /**

package/dist/pipeline/process-webhook.d.ts

@@ -17,10 +17,13 @@
  * top-level export is `processWebhook`, callable from server.ts / app.ts.
  */
 import { z } from 'zod';
-import type { SimulatedEvent } from '@kici-dev/engine';
+import type { LockFile as FullLockFile, SimulatedEvent } from '@kici-dev/engine';
+import type { OrchestratorMode } from '@kici-dev/engine';
 import type { WebhookInfo } from '../webhook/handler.js';
 import type { ProviderBundle } from '../provider-registry.js';
 import type { TrustResolution } from '../security/trust-resolver.js';
+import { type TrustPolicyOutcome } from '../security/trust-policy-gate.js';
+import { type WorkflowModification } from '../security/workflow-diff.js';
 import { type ProcessingDeps } from './processor.js';
 /**
  * Outcome of a single inbound-webhook ingestion. `duplicate` lets a direct-
@@ -29,9 +32,10 @@ import { type ProcessingDeps } from './processor.js';
  * `processed` means the pipeline matched and dispatched (or recorded a run).
  */
 export declare const WebhookIngestOutcome: z.ZodEnum<{
+    duplicate: "duplicate";
     processed: "processed";
+    shed: "shed";
     skipped: "skipped";
-    duplicate: "duplicate";
 }>;
 export type WebhookIngestOutcome = z.infer<typeof WebhookIngestOutcome>;
 interface TrustOutcome {
@@ -49,6 +53,57 @@ export declare function resolveTrustForPR(args: {
     repoIdentifier: string;
     credentials: Record<string, unknown>;
 }): Promise<TrustOutcome>;
+interface SecurityState {
+    workflowModifications: WorkflowModification[];
+    /**
+     * True when this PR changes `.kici/` workflow definitions. A *signal*, not a
+     * decision — the trust-policy gate turns it into an outcome, which the
+     * dispatch gate then enforces as a held run or a rejected run.
+     */
+    hasWorkflowModifications: boolean;
+}
+/**
+ * Phase G — On PR events evaluated against the base lock file, detect workflow
+ * modifications by diffing base vs. head and post a neutral informational check
+ * (on its own dedicated check name).
+ *
+ * Detection only. Whether a modification gates the run is the org trust policy's
+ * call, evaluated in `evaluateSecurityPolicy` and enforced by the dispatch gate
+ * — which creates the real `held_runs` row and posts the pending
+ * "Held for approval" check, so `/kici approve` / reject / expiry can resolve it.
+ */
+export declare function applyWorkflowModificationsAndSecurityHold(args: {
+    info: WebhookInfo;
+    bundle: ProviderBundle;
+    event: SimulatedEvent;
+    fullLockFile: FullLockFile;
+    headLockFileForDiff: FullLockFile | undefined;
+    isPREvent: boolean;
+    lockFileSource: 'head' | 'base';
+    trustResolution: TrustResolution | undefined;
+    repoIdentifier: string;
+    ref: string;
+    credentials: Record<string, unknown>;
+}): SecurityState;
+/**
+ * Evaluate the org trust policy for a PR event.
+ *
+ * Scoped to providers with a contributor model — the same condition trust
+ * resolution uses. A source without a `ContributorResolver` (generic, local,
+ * universal-git) is trusted by construction, so it passes regardless of policy;
+ * in particular, universal-git computes an `isForkPR` signal that must NOT gate
+ * those sources.
+ */
+export declare function evaluateSecurityPolicy(args: {
+    deps: ProcessingDeps;
+    bundle: ProviderBundle;
+    isPREvent: boolean;
+    resolvedOrgId: string;
+    mode: OrchestratorMode;
+    trustResolution: TrustResolution | undefined;
+    isForkPR: boolean;
+    hasWorkflowModifications: boolean;
+}): Promise<TrustPolicyOutcome>;
 /**
  * Process a webhook through the complete pipeline.
  *

package/dist/pipeline/processor.d.ts

@@ -13,6 +13,7 @@
  */
 import { type Kysely } from 'kysely';
 import type { Database } from '../db/types.js';
+import type { SandboxAllowListReader } from './sandbox-allowlist-reader.js';
 import type { WebhookInfo } from '../webhook/handler.js';
 import type { DedupCache } from '../webhook/dedup.js';
 import type { ProviderRegistry, ProviderBundle } from '../provider-registry.js';
@@ -31,6 +32,7 @@ import type { ExecutionTracker } from '../reporting/execution-tracker.js';
 import type { AgentRegistry } from '../agent/registry.js';
 import type { HostRosterStore } from '../agent/host-roster.js';
 import type { RunCoordinator } from '../cluster/coordinator.js';
+import type { ClusterSettingsReader } from '../cluster/cluster-settings-reader.js';
 import type { TeamMembershipLookup } from '../approvals/team-membership-lookup.js';
 import type { LogStorage } from '../reporting/log-storage.js';
 import type { SecretResolverApi } from '../secrets/secret-resolver.js';
@@ -49,8 +51,9 @@ import type { LockJob } from '@kici-dev/engine';
 import type { ContextStore } from '../contexts/context-store.js';
 import type { VariableStore } from '../contexts/variable-store.js';
 import type { TrustResolver, IdentityLink, PermissionLevel } from '../security/trust-resolver.js';
-import type { HeldRunStore } from '../contexts/held-runs.js';
-import type { WorkflowDecision } from '@kici-dev/engine';
+import { type HeldRunStore } from '../contexts/held-runs.js';
+import type { OrchestratorMode, WorkflowDecision } from '@kici-dev/engine';
+import type { TrustPolicyStore } from '../security/trust-policy-store.js';
 /**
  * Pending dispatch context for jobs gated by the needs scheduler.
  * Keyed by `${runId}:${jobName}`. Populated at processWebhook time for all
@@ -210,13 +213,9 @@ export declare function eventTypeToTriggerType(eventType: string): string;
  * Combines event type with action (e.g. "push", "pull_request:opened").
  */
 export declare function buildTriggerEvent(event: string, action: string | null | undefined): string;
-/**
- * Extract the first line of the commit message from a webhook payload.
- * Handles push (head_commit.message) and PR (pull_request.title) events.
- */
 /**
  * Best-effort extraction of a repository identifier from a generic webhook
- * payload for cross-source dispatch (phase 28.5). Generic webhooks have no
+ * payload for cross-source dispatch. Generic webhooks have no
  * canonical repo shape, so we probe the conventions a sender is most likely
  * to use:
  *
@@ -228,11 +227,25 @@ export declare function buildTriggerEvent(event: string, action: string | null |
  * cross-source repo lookup is skipped (event-name fan-out still runs).
  */
 export declare function extractInboundRepoIdentifier(payload: unknown): string | null;
+/**
+ * Extract the first line of the commit message from a webhook payload.
+ * Handles push (head_commit.message) and PR (pull_request.title) events.
+ */
 export declare function extractCommitMessage(event: string, payload: unknown): string | undefined;
 /**
  * Build a human-readable summary for a security hold check.
  */
 export declare function buildSecurityHoldSummary(reason: string, tier: string, contributorUsername?: string): string;
+/**
+ * Build the failure check-run description for a run the org trust policy
+ * REJECTED.
+ *
+ * Deliberately not `buildSecurityHoldSummary`: a rejected run creates no
+ * `held_runs` row, so telling the contributor to seek "approval from a user
+ * with ci_trust:write or higher" points at a queue the run will never appear
+ * in. Only an org policy change can unblock it.
+ */
+export declare function buildSecurityRejectionSummary(reason: string, message: string, tier: string, contributorUsername?: string): string;
 /**
  * Build the pending check-run description for a job/workflow approval hold,
  * naming the clauses an approver must satisfy. `{team:X}` renders as
@@ -282,6 +295,12 @@ export interface ProcessingDeps {
     coordinator?: RunCoordinator;
     /** Secret resolver for dispatch-time secret resolution. Optional -- if not set, secrets are not resolved. */
     secretResolver?: SecretResolverApi;
+    /**
+     * Cached per-org container-sandbox escape-hatch allow-list reader. Optional --
+     * when absent, dispatch defaults to the safe deny-all allow-list, so no
+     * workflow can escalate capabilities / host networking.
+     */
+    sandboxAllowListReader?: SandboxAllowListReader;
     /** Optional callback when source locations are extracted from a lock file workflow. */
     onSourceLocationsExtracted?: (workflowName: string, jobName: string, sourceLocations: Array<{
         file: string;
@@ -310,6 +329,20 @@ export interface ProcessingDeps {
     heldRunStore?: HeldRunStore;
     /** Trust resolver for determining contributor trust tiers. Optional -- if not set, trust resolution is skipped. */
     trustResolver?: TrustResolver;
+    /**
+     * Cache of the Platform-owned org trust policy. Read per PR event by the
+     * trust-policy gate. Optional so existing tests and independent deployments
+     * that construct deps by hand keep working.
+     */
+    trustPolicyStore?: TrustPolicyStore;
+    /**
+     * This orchestrator's mode. The trust-policy gate needs it to decide what an
+     * absent policy means: Platform-attached modes fail closed (a push is
+     * imminent), independent mode has no upstream authority and keeps legacy
+     * behavior. Defaults to `'platform'` at the read site — the fail-closed side —
+     * so a hand-built deps object never accidentally opens the gate.
+     */
+    orchestratorMode?: OrchestratorMode;
     /** Identity links pushed from Platform for trust resolution. Optional -- defaults to empty. */
     identityLinks?: IdentityLink[];
     /** ci_trust permission levels per user ID from Platform push. Optional -- defaults to empty. */
@@ -343,8 +376,11 @@ export interface ProcessingDeps {
     instanceId?: string;
     /** Static-host grace before a disconnected static host reads unreachable (ms). */
     rosterGraceMs?: number;
-    /** Cap on runsOnAll per-host children (default 1024). */
+    /** Cap on runsOnAll per-host children (default 1024). Cluster default; the
+     * live per-cluster override is read from `cluster_settings.max_fanout_hosts`. */
     maxFanoutHosts?: number;
+    /** Reader for fleet-wide cluster tunables (max_fanout_hosts live override). */
+    clusterSettings?: ClusterSettingsReader;
 }
 /**
  * Check if any trigger in the lock file workflows uses path filters.

package/dist/pipeline/rerun.d.ts

@@ -28,18 +28,17 @@ import type { BuildCoordinator } from '../cache/index.js';
 import type { DepCache } from '../cache/index.js';
 import type { PendingBuildTracker } from '../cache/index.js';
 /**
- * Thrown when a rerun is attempted on an archived run AND the cold-store
- * replay path failed (chunk missing, contentHash mismatch, S3 outage, or
- * cold-store probe disabled). Phase F replaced the Phase-C "rerun is
- * blocked" semantics with a real replay path; this error now signals
- * a genuine "we tried to bring the row back and could not".
+ * Thrown when a rerun is attempted on a run whose row is absent from PG AND
+ * the cold-store replay path failed or is unavailable (chunk missing,
+ * contentHash mismatch, S3 outage, or cold-store probe disabled). Signals a
+ * genuine "we tried to bring the row back and could not".
  *
  * The WS dashboard handler maps this to a structured response that the
  * Platform proxy surfaces as HTTP 410 (`errorCode: 'runArchivedNotRerunnable'`).
  */
 export declare class RunArchivedNotRerunnableError extends Error {
     readonly runId: string;
-    readonly code: "runArchivedNotRerunnable";
+    readonly code: 'runArchivedNotRerunnable';
     constructor(runId: string);
 }
 export interface RerunDeps {
@@ -60,10 +59,10 @@ export interface RerunDeps {
     buildCoordinator: BuildCoordinator | null;
     pendingBuilds: PendingBuildTracker | null;
     /**
-     * Phase F — when set, a PG miss on `originalRunId` triggers a
-     * cold-store replay of the chunk containing the row, then a re-read.
-     * `null` keeps the legacy "throw RunArchivedNotRerunnableError on PG
-     * miss" path for deployments without cold-store wired up.
+     * When set, a PG miss on `originalRunId` triggers a cold-store replay of
+     * the chunk containing the row, then a re-read. `null` keeps the "throw
+     * RunArchivedNotRerunnableError on PG miss" path for deployments without
+     * cold-store wired up.
      */
     coldStore: ColdStore | null;
 }
@@ -77,9 +76,9 @@ export declare function handleRerun(originalRunId: string, triggeredBy: string |
  */
 requestId: string, 
 /**
- * Phase F — routing key for the original run, forwarded by Platform
- * via the WS `run.rerun.request` payload. Required to address the
- * cold-store chunk under the right tenant prefix.
+ * Routing key for the original run, forwarded by Platform via the WS
+ * `run.rerun.request` payload. Required to address the cold-store chunk
+ * under the right tenant prefix.
  */
 routingKeyHint?: string): Promise<{
     newRunId: string;