@kici-dev/orchestrator 0.1.16 → 0.1.18

package/dist/lockfile-redos-guard.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Lock-load ReDoS revalidation.
+ *
+ * Re-validates every regex matcher in a fetched lock file before it is cached
+ * or dispatched. Defense-in-depth against a hand-edited or non-compiled lock
+ * that smuggled a ReDoS-prone pattern past the compile-time gate: the compiler
+ * runs the same `assertMatchersSafe` check when it emits the lock, but the
+ * orchestrator does not trust that the lock it fetched was produced by our
+ * compiler.
+ */
+import type { LockFile } from '@kici-dev/engine';
+/**
+ * Walk every static job's `runsOn` / `excludeLabels` / `runsOnAll` matchers and
+ * throw if any regex matcher is ReDoS-prone. Dynamic job generators carry no
+ * static routing matchers (they materialize jobs at eval time, which re-runs the
+ * compile-time gate), so only static jobs are checked.
+ */
+export declare function assertLockFileRegexesSafe(lockFile: LockFile): void;
+//# sourceMappingURL=lockfile-redos-guard.d.ts.map

package/dist/metrics/prometheus.d.ts

@@ -2,6 +2,8 @@
 export declare function setAgentsActive(value: number): void;
 /** Set the current config version number. */
 export declare function setConfigVersion(value: number): void;
+/** Set the current number of declared (static) roster hosts that are unreachable. */
+export declare function setDeclaredHostsUnreachable(value: number): void;
 /** Set the current number of stale runs detected. */
 export declare function setStaleRunsCurrent(value: number): void;
 interface ScalerUsageRow {
@@ -264,6 +266,8 @@ export declare const InstallSecretsDecisionReason: {
     readonly ProtectionRuleBlock: "protection_rule_block";
     readonly MissingToken: "missing_token";
     readonly MissingInstallEnv: "missing_install_env";
+    /** A protection gate held the workflow install (hold / wait / queue). */
+    readonly Held: "held";
 };
 export type InstallSecretsDecisionReason = (typeof InstallSecretsDecisionReason)[keyof typeof InstallSecretsDecisionReason];
 /**
@@ -280,8 +284,8 @@ export type InstallSecretsChannel = (typeof InstallSecretsChannel)[keyof typeof
  * Total install-secrets resolution decisions.
  *
  * Labels:
- * - decision: pass | reject
- * - reason: ok (only with `pass`), or one of the reject reasons enumerated in `InstallSecretsDecisionReason`
+ * - decision: pass | reject | hold
+ * - reason: ok (only with `pass`), held (only with `hold`), or one of the reject reasons enumerated in `InstallSecretsDecisionReason`
  *
  * Pass series are emitted exactly once per resolver call that does any work
  * (workflows declaring neither `registries:` nor `installEnv:` are NOT
@@ -320,5 +324,16 @@ export declare const installSecretsContributorStrippedTotal: import("@openteleme
  * - environment: the environment name referenced in the qualified `<environment>:<secret>` ref (per-org count is typically <10)
  */
 export declare const installSecretsTokenResolutionDurationSeconds: import("@opentelemetry/api").Histogram<import("@opentelemetry/api").Attributes>;
+/**
+ * Register every queued orchestrator observable gauge on the real meter.
+ *
+ * Must run AFTER `initTelemetry()` has wired the global MeterProvider —
+ * `createApp()` calls it once during bootstrap. Registering the gauges at
+ * module-eval time instead would bind them to the no-op provider (the
+ * bundler hoists some module init above the entry's `initTelemetry()` call),
+ * leaving every `kici_orch_*` gauge absent from the /metrics scrape and the
+ * Platform push. Idempotent: repeat calls are no-ops.
+ */
+export declare function registerOrchestratorMetrics(): void;
 export {};
 //# sourceMappingURL=prometheus.d.ts.map

package/dist/metrics/scheduled-jobs.d.ts

@@ -4,13 +4,13 @@
  * - job: scheduled-job name (one of `OrchestratorScheduledJobName`)
  * - result: success | failure
  */
-export declare const jobRunsTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+export declare const jobRunsTotal: Pick<import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>, "add">;
 /**
  * Histogram of per-tick duration, seconds.
  * Labels:
  * - job: scheduled-job name (one of `OrchestratorScheduledJobName`)
  */
-export declare const jobDurationSeconds: import("@opentelemetry/api").Histogram<import("@opentelemetry/api").Attributes>;
+export declare const jobDurationSeconds: Pick<import("@opentelemetry/api").Histogram<import("@opentelemetry/api").Attributes>, "record">;
 /**
  * Unix timestamp (seconds) of the most recent successful tick.
  * Labels:

package/dist/orchestrator-core.d.ts

@@ -13,6 +13,7 @@ import { type ColdStore } from '@kici-dev/shared';
 import type { AppConfig } from './config.js';
 import { ConfigReloader } from './config/reload.js';
 import { AgentRegistry } from './agent/registry.js';
+import { HostRosterStore } from './agent/host-roster.js';
 import { JobQueue } from './queue/job-queue.js';
 import { EventLogWriter } from './webhook/event-log.js';
 import { AccessLogWriter } from './audit/access-log.js';
@@ -22,7 +23,7 @@ import { DedupCache } from './webhook/dedup.js';
 import { ObserverRegistry } from './ws/observer-registry.js';
 import { AgentMetricsAggregator } from './metrics/agent-metrics-aggregator.js';
 import { SourceLocationStore } from './app.js';
-import { type PeerHeartbeat, type PeerLogsCollectRequest, type PeerToPeerMessage } from '@kici-dev/engine';
+import { type LabelMatcher, type PeerHeartbeat, type PeerLogsCollectRequest, type PeerToPeerMessage } from '@kici-dev/engine';
 import { ScalerManager } from './scaler/index.js';
 import type { ScalerConfig } from './scaler/index.js';
 import type { CacheStorage } from './storage/index.js';
@@ -63,6 +64,7 @@ export interface OrchestratorSubsystems {
     pool: pg.Pool;
     providerRegistry: ProviderRegistry;
     agentRegistry: AgentRegistry;
+    hostRosterStore: HostRosterStore;
     dispatcher: Dispatcher;
     queue: JobQueue;
     scalerManager: ScalerManager | null;
@@ -210,6 +212,97 @@ export interface OrchestratorHooks {
      */
     startupLogMessage: (port: number) => string;
 }
+/**
+ * Normalize a lock job's `needs` array (strings, NeedsEntry objects, or
+ * NeedsGroupEntry objects) to the set of upstream BASE job names. Group entries
+ * are skipped here — group fan-in is resolved separately by the scheduler.
+ */
+export declare function upstreamBaseNamesFromNeeds(needs: unknown): string[];
+/**
+ * Partition a lock job's `runsOn` / `excludeLabels` matchers into exact label
+ * strings and regex patterns for internal-event (cron / `ctx.emit`) dispatch.
+ * Lock jobs carry `runsOn` as `LabelMatcher[]`; the coordinator routing and the
+ * direct dispatcher both need exact labels for the indexed/SQL fast path and
+ * regex patterns as a separate JS post-filter — never the raw matcher objects.
+ */
+export declare function internalJobRunsOnSelectors(job: {
+    runsOn?: readonly LabelMatcher[];
+    excludeLabels?: readonly LabelMatcher[];
+}): {
+    runsOnLabels: string[];
+    runsOnPatterns: LabelMatcher[];
+    excludeLabels: string[];
+    excludePatterns: LabelMatcher[];
+};
+/**
+ * Parse an `execution_jobs.outputs` cell (string JSON or object) to a plain
+ * object, or null when empty / unparseable.
+ */
+export declare function parseOutputsCell(outputs: unknown): Record<string, unknown> | null;
+/**
+ * Build the downstream `upstreamJobOutputs` map keyed by BASE name. A base name
+ * that fanned into matrix children (rows with `matrix_values`) gets the
+ * `{ byMatrix, merged }` envelope; a single non-fanned row keeps the flat shape.
+ * Returns undefined when no upstream produced outputs.
+ */
+export declare function buildUpstreamOutputsByBase(baseNames: string[], rows: Array<{
+    job_name: string;
+    outputs: unknown;
+    matrix_values: unknown;
+    variant_kind?: string | null;
+    variant_label?: string | null;
+    status?: string | null;
+}>): Record<string, Record<string, unknown>> | undefined;
+/**
+ * Fold a `runsOnAll` upstream's host children into the `byHost` envelope
+ * `{ byHost: { '<host>': outputs }, summary: { succeededHosts, failedHosts, outputs } }`.
+ * Unlike the matrix envelope, `summary.outputs[key]` is an array view across hosts
+ * (host order), never a last-write-wins scalar; `succeededHosts`/`failedHosts`
+ * record each host's terminal outcome.
+ */
+export declare function buildHostOutputsEnvelope(children: Array<{
+    host: string;
+    status: string | null;
+    parsed: Record<string, unknown>;
+}>): {
+    byHost: Record<string, Record<string, unknown>>;
+    summary: {
+        succeededHosts: string[];
+        failedHosts: string[];
+        outputs: Record<string, unknown[]>;
+    };
+};
+/**
+ * Group an upstream's child rows into the matrix outputs envelope
+ * `{ byMatrix: { '<suffix>': outputs }, merged: <last-write-wins> }`. The suffix
+ * is the text inside the `(...)` of each expanded child name; children are
+ * merged in name order (deterministic, matching dispatch order).
+ */
+export declare function buildMatrixOutputsEnvelope(baseName: string, children: Array<{
+    job_name: string;
+    parsed: Record<string, unknown>;
+}>): {
+    byMatrix: Record<string, Record<string, unknown>>;
+    merged: Record<string, unknown>;
+};
+/**
+ * Merge plain `outputs` and decrypted `secret outputs` from upstream jobs
+ * into the dispatch envelope's `secrets` + `upstreamJobOutputs` fields.
+ *
+ * For a fanned (matrix) upstream, the downstream sees a keyed envelope
+ * `{ byMatrix: { '<suffix>': outputs }, merged: <last-write-wins> }` under the
+ * BASE name; a non-fanned upstream keeps the flat outputs shape.
+ *
+ * The needs-aware scheduler guarantees upstreams are
+ * terminal before the downstream is dispatched, so the lookups below
+ * always find final values. Errors are swallowed (warn-logged) so a flaky
+ * upstream-outputs read doesn't block dispatch — the agent will still get
+ * its declared secrets, just without the merged upstream additions.
+ */
+export declare function mergeUpstreamOutputs(db: Kysely<Database>, runId: string, jobName: string, needs: unknown, dispatchSecrets: Record<string, string> | undefined, secretKey: string): Promise<{
+    mergedSecrets: Record<string, string> | undefined;
+    upstreamJobOutputs: Record<string, Record<string, unknown>> | undefined;
+}>;
 export declare function bootstrapOrchestrator(config: AppConfig, hooks: OrchestratorHooks, options?: {
     otelSdk?: {
         shutdown(): Promise<void>;

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

@@ -14,7 +14,7 @@
  * results through the pipeline.
  */
 import { CacheRefScope } from '@kici-dev/engine';
-import type { LockWorkflow, SimulatedEvent, WorkflowDecision } from '@kici-dev/engine';
+import type { LabelMatcher, LockWorkflow, SimulatedEvent, WorkflowDecision, MaterializedJob } 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';
@@ -91,7 +91,64 @@ export interface WorkflowDispatchContext {
 export interface DispatchMatchedWorkflowResult {
     /** Number of jobs successfully dispatched (non-rejected). */
     dispatchedJobCount: number;
+    /** True when the workflow install gate paused the dispatch (held run). */
+    held?: boolean;
 }
+/** Options controlling a (re-)dispatch of a matched workflow. */
+export interface DispatchMatchedWorkflowOptions {
+    /**
+     * Resume path: skip the workflow install protection gate (already satisfied)
+     * so secrets resolve directly and the dispatch flows into job dispatch.
+     */
+    skipInstallProtectionGate?: boolean;
+    /** The released held-run id being resumed (for logging / correlation). */
+    reuseHeldRunId?: string;
+    /**
+     * The run id whose `held` execution_runs row should be reused (flipped to
+     * pending) instead of inserting a fresh row.
+     */
+    reuseRunId?: string;
+}
+/** Exact labels + regex patterns partitioned from a lock job's selectors. */
+interface JobRoutingSelectors {
+    runsOnLabels: string[];
+    runsOnPatterns: LabelMatcher[];
+    excludeLabels: string[];
+    excludePatterns: LabelMatcher[];
+}
+/**
+ * Partition a lock job's runsOn / excludeLabels matchers into exact labels (SQL
+ * `@>` prefilter + registry index) and regex patterns (JS post-filter). A
+ * `runsOnAll` host-fanout job has no `runsOn`; its pinned children carry no
+ * routing (the pin targets the resolved agent directly).
+ */
+export declare function runsOnSelectorsForLockJob(lockJob: {
+    runsOn?: readonly LabelMatcher[];
+    excludeLabels?: readonly LabelMatcher[];
+}): JobRoutingSelectors;
+/** Per-child rolling-wave plan: which children are held + the base's wave policy. */
+export interface WavePlan {
+    /** `expandedName`s held behind the wave gate (beyond the maxParallel window). */
+    held: Set<string>;
+    /** `expandedName` → the base's `{maxParallel, failFast}`, stamped on every child of a bounded wave. */
+    policy: Map<string, {
+        maxParallel: number;
+        failFast: boolean;
+    }>;
+}
+/**
+ * Compute the rolling-wave plan for a materialized job set.
+ *
+ * For each base job declaring `maxParallel` whose fan-out produced more than one
+ * child, children are ordered deterministically by `variant_label` (the matrix
+ * suffix / hostname, via `expandedName`) and every child at index `>=
+ * maxParallel` is held (`wave_gated=true`). The first `maxParallel` dispatch
+ * immediately; held children release one-per-terminal via the wave-scheduler.
+ * Every child of a bounded-wave base — held or not — gets a `policy` entry so
+ * the wave-scheduler can read the width/failFast at terminal time. A non-fan-out
+ * job (single child) or one without `maxParallel` contributes nothing.
+ */
+export declare function computeWavePlan(materializedJobs: readonly MaterializedJob[]): WavePlan;
 /**
  * Dispatch a single matched workflow.
  *
@@ -107,5 +164,6 @@ export interface DispatchMatchedWorkflowResult {
  *   I. deferred init dispatch (fire-and-forget per job)
  *   J. deferred dynamic dispatch (fire-and-forget per dynamic entry)
  */
-export declare function dispatchMatchedWorkflow(ctx: WorkflowDispatchContext): Promise<DispatchMatchedWorkflowResult>;
+export declare function dispatchMatchedWorkflow(ctx: WorkflowDispatchContext, opts?: DispatchMatchedWorkflowOptions): Promise<DispatchMatchedWorkflowResult>;
+export {};
 //# sourceMappingURL=dispatch-matched-workflow.d.ts.map

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

@@ -8,10 +8,13 @@
  *
  *   1. Parses every qualified ref and groups by environment name.
  *   2. Fires the per-environment protection-rule pipeline once per unique env
- *      (branch / trust / concurrency / reviewer / wait-timer). Any non-pass
- *      result rejects the whole workflow dispatch — v1 does not yet support
- *      workflow-scoped held-runs, so a `hold` from the reviewer-gate is
- *      surfaced as a reject with a clear reason.
+ *      (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
+ *      so the caller can pause the workflow dispatch as a workflow-scoped held
+ *      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`
  *      (which writes its own audit log lines).
  *   4. Validates each registry URL scheme: HTTPS always allowed; `http://`
@@ -26,7 +29,7 @@
  * Pure helper: no imports of the dispatch giant. Tested in isolation in
  * `install-secrets-resolver.test.ts`.
  */
-import type { LockRegistry } from '@kici-dev/engine';
+import type { ApproverClause, LockRegistry } from '@kici-dev/engine';
 import type { TrustResolution } from '../security/trust-resolver.js';
 import type { SecretResolver } from '../secrets/secret-resolver.js';
 import type { EnvironmentStore } from '../environments/environment-store.js';
@@ -47,6 +50,18 @@ export interface ResolveInstallSecretsArgs {
     environmentStore: EnvironmentStore | undefined;
     secretResolver: SecretResolver | undefined;
     protectionContext: JobDispatchContext;
+    /**
+     * Resume path: skip the protection-rule gate (already satisfied) and resolve
+     * secrets directly. The untrusted-contributor strip still runs first.
+     */
+    skipProtectionGate?: boolean;
+}
+/** Normalized requirement carried on a `hold` decision. */
+export interface InstallHoldRequirement {
+    clauses: ApproverClause[];
+    /** ISO timestamp after which the hold expires. */
+    expiresAt: string;
+    reason: string;
 }
 export type ResolveInstallSecretsResult = {
     decision: 'pass';
@@ -56,6 +71,18 @@ export type ResolveInstallSecretsResult = {
 } | {
     decision: 'reject';
     reason: string;
+} | {
+    decision: 'hold';
+    /** The gate action that paused the dispatch. */
+    action: 'hold' | 'wait' | 'queue';
+    /** The environment whose install gate held. */
+    envName: string;
+    /** Resolved environment id (for the held row). */
+    environmentId: string;
+    /** Discriminates the release trigger: 'reviewer' | 'wait_timer' | 'concurrency' | 'security'. */
+    holdType: string;
+    queueType: 'environment' | 'security';
+    requirement: InstallHoldRequirement;
 };
 /** Parse `<environment>:<secret-name>`. Returns null on malformed input. */
 export declare function parseQualifiedSecretRef(ref: string): {

package/dist/pipeline/needs-scheduler.d.ts

@@ -19,25 +19,28 @@
  */
 import type { Kysely } from 'kysely';
 import type { Database } from '../db/types.js';
-import type { NeedsEntry, NeedsGroupEntry } from '@kici-dev/engine';
+import type { MaterializedJob } from '@kici-dev/engine';
 /** Result of evaluating downstream jobs after an upstream completes. */
 export interface SchedulerResult {
     jobName: string;
     action: 'dispatch' | 'skip';
     reason?: string;
 }
-/** Minimal lock job shape needed by insertEdgesForRun. */
-interface LockJobLike {
-    readonly name: string;
-    readonly needs: readonly (string | NeedsEntry | NeedsGroupEntry)[];
-    readonly dependsOnGroups?: readonly string[];
-}
 /**
  * Insert dependency edges at run start for static-to-static needs.
+ *
+ * Operates on materialized jobs (matrix-expanded children) and an expansion map
+ * (base job name -> the expanded child names). An upstream reference to a base
+ * name `test` that fanned into `test (a)` / `test (b)` produces one edge per
+ * child, so a downstream `needs: ['test']` waits for ALL children to terminate.
+ * Each materialized child likewise inherits the full upstream edge set under its
+ * own expanded name.
+ *
  * NeedsGroupEntry items are skipped (resolved later via resolveGroupEdges).
- * Root jobs (no needs, no dependsOnGroups) are marked needs_satisfied=true.
+ * Root jobs (no needs, no dependsOnGroups) are marked needs_satisfied=true,
+ * keyed by expanded name.
  */
-export declare function insertEdgesForRun(db: Kysely<Database>, runId: string, lockJobs: readonly LockJobLike[]): Promise<void>;
+export declare function insertEdgesForRun(db: Kysely<Database>, runId: string, jobs: readonly MaterializedJob[], expansionMap: ReadonlyMap<string, readonly string[]>): Promise<void>;
 /**
  * Resolve dynamic group edges after eval completion.
  *
@@ -81,5 +84,4 @@ export declare function checkSchedulerInvariant(db: Kysely<Database>, runId: str
  * due to failure propagation. Only follows edges where if_failed='skip'.
  */
 export declare function getFailurePropagationTargets(db: Kysely<Database>, runId: string, failedJobName: string): Promise<string[]>;
-export {};
 //# sourceMappingURL=needs-scheduler.d.ts.map

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

@@ -0,0 +1,44 @@
+/**
+ * Pending workflow dispatch context store — the workflow-level analogue of the
+ * `pending_job_contexts` store. Persists the serializable inputs of a
+ * `WorkflowDispatchContext` so a workflow whose install gate held can be
+ * resumed (reviewer approve, wait-timer expiry, concurrency slot free) by
+ * rebuilding the dispatch context and re-running `dispatchMatchedWorkflow`.
+ *
+ * Only the serializable inputs are stored — the live `deps` (ProcessingDeps)
+ * and `bundle` (ProviderBundle) are NOT persisted; they are rebuilt from the
+ * live orchestrator on resume.
+ *
+ * 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 { Database } from '../db/types.js';
+import type { WorkflowDispatchContext } from './dispatch-matched-workflow.js';
+/**
+ * The serializable subset of a `WorkflowDispatchContext` — everything except
+ * the live `deps` and `bundle`, which are rebuilt on resume. Every field here
+ * is JSON-safe (the event, payload, and lock file already ride the WS protocol
+ * as JSON).
+ */
+export type SerializableWorkflowDispatchInputs = Omit<WorkflowDispatchContext, 'deps' | 'bundle'>;
+/** Extract the serializable inputs from a live dispatch context. */
+export declare function toSerializableInputs(ctx: WorkflowDispatchContext): SerializableWorkflowDispatchInputs;
+/** Persist the pending workflow context to the in-memory Map and the DB. */
+export declare function storePendingWorkflowContext(db: Kysely<Database> | undefined, inputs: SerializableWorkflowDispatchInputs): Promise<void>;
+/** Load the pending workflow context by run id (memory first, then DB). */
+export declare function loadPendingWorkflowContext(db: Kysely<Database> | undefined, runId: string): Promise<SerializableWorkflowDispatchInputs | null>;
+/** Delete the pending workflow context from the in-memory Map and the DB. */
+export declare function deletePendingWorkflowContext(db: Kysely<Database> | undefined, runId: string): Promise<void>;
+/**
+ * Restore the in-memory Map from the DB on startup, skipping rows whose run has
+ * already reached a terminal state. Mirrors `restorePendingJobContexts`.
+ * Returns the number of restored contexts.
+ */
+export declare function restorePendingWorkflowContexts(db: Kysely<Database>): Promise<number>;
+/**
+ * Clear all entries from the in-memory pending workflow contexts Map.
+ * @internal Exported for testing only.
+ */
+export declare function clearPendingWorkflowContextsMap(): void;
+//# sourceMappingURL=pending-workflow-context.d.ts.map

package/dist/pipeline/processor.d.ts

@@ -29,6 +29,7 @@ import type { PendingDynamicTracker } from '../cache/pending-dynamics.js';
 import type { CheckRunReporter } from '../reporting/check-run-reporter.js';
 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 { TeamMembershipLookup } from '../approvals/team-membership-lookup.js';
 import type { LogStorage } from '../reporting/log-storage.js';
@@ -62,6 +63,21 @@ interface PendingJobContext {
     jobInput: QueuedJobInput;
     runsOnLabels: string[];
 }
+/**
+ * Register an eval gate and return a promise that resolves when the scheduler
+ * opens it (the eval job's upstream needs are all satisfied).
+ */
+export declare function trackEvalGate(runId: string, evalJobName: string): Promise<void>;
+/**
+ * Open a registered eval gate, unblocking the deferred dispatch task. Returns
+ * true if a gate was registered for this eval job (so the scheduler knows it
+ * handled the ready signal itself and must not run the normal dispatch path).
+ */
+export declare function openEvalGate(runId: string, evalJobName: string): boolean;
+/** True when a job name is a result-aware dynamic eval job awaiting its gate. */
+export declare function isEvalGatePending(runId: string, evalJobName: string): boolean;
+/** Clear all eval gates for a run (called on run completion / cleanup). */
+export declare function clearEvalGatesForRun(runId: string): void;
 /**
  * Store a pending dispatch context for a job that will be dispatched later
  * by the needs scheduler. The key is `${runId}:${jobName}`.
@@ -112,7 +128,7 @@ export declare function isRootJob(lockJob: LockJob): boolean;
  * Why this exists
  * ----------------
  * The webhook pipeline binds `lockFileFetcher` to the inbound webhook's
- * provider bundle. When an internal-sourced webhook (e.g., the staging
+ * provider bundle. When a local-sourced webhook (e.g., the staging
  * stg-ha-smoke failover-dispatch test) arrives for a repo whose lock file
  * is only accessible via a different provider (e.g., github), the inbound
  * fetcher returns null and trigger matching silently drops the webhook.
@@ -143,7 +159,7 @@ export declare function isRootJob(lockJob: LockJob): boolean;
  * -----------
  * Each fallback fetcher is invoked with the REGISTRATION'S
  * `providerContext`, NOT the inbound normalizer's credentials. This is
- * load-bearing: the InternalWebhookNormalizer returns `{}` as
+ * load-bearing: the LocalWebhookNormalizer returns `{}` as
  * credentials, which would never satisfy a github fetcher that requires
  * `installationId`. The registration carries the correct credentials
  * because it was created via the owning provider's source.
@@ -178,8 +194,10 @@ export declare function resolveLockFileWithFallback(args: {
  * Resolve the customer/org ID for a routing key.
  *
  * Checks the `sources` table first (GitHub App sources), then
- * `generic_webhook_sources` (generic webhook sources). Falls back to
- * '__default__' if neither table has the routing key.
+ * `generic_webhook_sources` (generic webhook sources), then `remote_sources`
+ * (the auto-provisioned anchor for Platform-relayed `kici run remote`, routing
+ * key `remote:<orgId>`). Falls back to '__default__' if none of the three
+ * tables has the routing key.
  */
 export declare function resolveOrgId(db: Kysely<Database>, routingKey: string): Promise<string>;
 /**
@@ -318,6 +336,15 @@ export interface ProcessingDeps {
     /** Access-log writer for the orchestrator audit stream. Optional -- if not
      *  set, hold-creation audit rows (`held_run.request`) are skipped. */
     accessLogWriter?: AccessLogWriter;
+    /** Host roster store for runsOnAll fan-out resolution. Optional -- if not set,
+     *  runsOnAll jobs cannot be resolved and fail at materialize. */
+    hostRosterStore?: HostRosterStore;
+    /** This orchestrator instance id (for the cross-cluster host-fanout pin reroute). */
+    instanceId?: string;
+    /** Static-host grace before a disconnected static host reads unreachable (ms). */
+    rosterGraceMs?: number;
+    /** Cap on runsOnAll per-host children (default 1024). */
+    maxFanoutHosts?: number;
 }
 /**
  * Check if any trigger in the lock file workflows uses path filters.

package/dist/pipeline/remote-source-store.d.ts

@@ -0,0 +1,21 @@
+import type { Kysely } from 'kysely';
+import type { Database, RemoteSourceRow } from '../db/types.js';
+/**
+ * Deterministic routing key for an org's Platform-relayed remote runs. A
+ * Platform-relayed `test.trigger` carries this key; `resolveOrgId` maps it back
+ * to the canonical org id via the `remote_sources` row.
+ */
+export declare function remoteRoutingKeyFor(orgId: string): string;
+/**
+ * Idempotently upsert the `remote_sources` anchor for an org. Called on every
+ * Platform (re)connect once the orchestrator learns its canonical org id from
+ * `auth.success`. The unique `(customer_id)` constraint makes this a safe
+ * self-heal — re-running updates `cluster_id` if the cluster identity changed.
+ */
+export declare function provisionRemoteSource(db: Kysely<Database>, params: {
+    orgId: string;
+    clusterId: string | null;
+}): Promise<void>;
+/** Read the auto-provisioned remote-source row for an org, if it exists. */
+export declare function getRemoteSource(db: Kysely<Database>, orgId: string): Promise<RemoteSourceRow | undefined>;
+//# sourceMappingURL=remote-source-store.d.ts.map

package/dist/pipeline/resume-workflow.d.ts

@@ -0,0 +1,26 @@
+import type { Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+import type { ProcessingDeps } from './processor.js';
+import type { ReleaseSignal } from '../environments/held-runs.js';
+import { type WorkflowDispatchContext } from './dispatch-matched-workflow.js';
+import { type SerializableWorkflowDispatchInputs } from './pending-workflow-context.js';
+/**
+ * Rebuild a live `WorkflowDispatchContext` from the persisted serializable
+ * inputs by re-attaching the orchestrator's live `deps` and reconstructing the
+ * provider `bundle` from the live registry (keyed by the stored routing key).
+ * Returns null when the provider bundle can no longer be resolved.
+ */
+export declare function rebuildWorkflowDispatchContext(inputs: SerializableWorkflowDispatchInputs, deps: ProcessingDeps): WorkflowDispatchContext | null;
+/**
+ * Resume a released workflow install-gate hold. Loads the pending context,
+ * rebuilds the dispatch context, and re-dispatches with the gate skipped. On a
+ * lost pending context (or unresolvable provider bundle) the run is failed
+ * loudly rather than silently dropped.
+ */
+export declare function resumeWorkflow(signal: ReleaseSignal, deps: ProcessingDeps, db: Kysely<Database> | undefined): Promise<void>;
+/**
+ * Cancel a rejected workflow install-gate hold: mark the run cancelled and drop
+ * the pending context.
+ */
+export declare function rejectWorkflow(runId: string, deps: ProcessingDeps, db: Kysely<Database> | undefined, reason: string): Promise<void>;
+//# sourceMappingURL=resume-workflow.d.ts.map

package/dist/pipeline/wave-scheduler.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Rolling-wave scheduler for bounded fan-out (`maxParallel` / `failFast`).
+ *
+ * Sibling of the needs-scheduler (`needs-scheduler.ts`): both fire on a job
+ * reaching terminal state and decide what to do with held downstream/sibling
+ * jobs. The needs-scheduler releases jobs whose `needs` edges are now satisfied;
+ * the wave-scheduler releases the next `wave_gated` sibling of a fan-out base
+ * whenever an in-flight slot frees up (or, under `failFast`, skips the held
+ * remainder on the first child failure).
+ *
+ * Pure DB — no in-memory state. Every decision is a fresh query against
+ * `execution_jobs` keyed by `(run_id, base_job_name)`, so the scheduler needs
+ * zero recovery code on orchestrator restart. The caller performs the DB write
+ * (clear `wave_gated` / mark skipped) and the dispatch (`onJobReady`), keeping
+ * this module a pure decision function.
+ */
+import type { Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+/** Inputs identifying a completed fan-out child. The wave policy is read from the base group. */
+export interface WaveEvaluation {
+    runId: string;
+    /** The base (logical) job name shared by every fan-out child. */
+    baseJobName: string;
+    /** Terminal status of the child that just completed. */
+    completedStatus: string;
+}
+/** The wave-scheduler's decision for one completed child. */
+export type WaveResult = {
+    action: 'release';
+    jobName: string;
+    baseJobName: string;
+    maxParallel: number;
+    failFast: boolean;
+} | {
+    action: 'skip-remaining';
+    jobNames: string[];
+} | {
+    action: 'noop';
+};
+/**
+ * Decide what happens after a fan-out child of `baseJobName` reaches terminal.
+ *
+ * The wave policy (`maxParallel` / `failFast`) is read from the base group's
+ * own rows — every child of a bounded wave carries the same stamped
+ * `wave_max_parallel` / `wave_fail_fast`, so the just-completed child's slot
+ * being re-inserted without the policy on release does not break the chain
+ * (the still-held siblings carry it). If no sibling carries a policy, this is
+ * not a bounded wave → `noop`.
+ *
+ * - `failFast` + a child failure → `skip-remaining` every still-held sibling.
+ * - in-flight count `< maxParallel` AND a held sibling exists → `release` the
+ *   next held sibling (lowest `variant_label`).
+ * - otherwise → `noop`.
+ *
+ * "In-flight" = a non-terminal, non-`wave_gated` child (it has been dispatched
+ * and not yet completed). The just-completed child is terminal, so it does not
+ * count against the window — its slot is the one we are filling.
+ */
+export declare function evaluateWave(db: Kysely<Database>, evaluation: WaveEvaluation): Promise<WaveResult>;
+//# sourceMappingURL=wave-scheduler.d.ts.map