@kici-dev/orchestrator 0.1.17 → 0.1.18

package/dist/cluster/coordinator.d.ts

@@ -10,7 +10,7 @@
  * - "Peers report step-by-step progress back to coordinator"
  * - "Cancel mode: graceful -- finish current step, cancel remaining"
  */
-import type { JobReroute, JobProgress, PeerScalerEvent, PeerToPeerMessage, ResourceRequest } from '@kici-dev/engine';
+import type { JobReroute, JobProgress, PeerScalerEvent, PeerToPeerMessage, ResourceRequest, LabelMatcher } from '@kici-dev/engine';
 import type { PeerRegistry } from './peer-registry.js';
 import type { PeerClient } from './peer-client.js';
 import type { Dispatcher } from '../agent/dispatcher.js';
@@ -37,6 +37,10 @@ export interface RunContext {
 export interface JobToRoute {
     jobName: string;
     runsOnLabels: string[][];
+    /** Regex matchers the agent's labels must satisfy (JS post-filter). */
+    runsOnPatterns?: LabelMatcher[];
+    /** Regex matchers that disqualify an agent (JS post-filter). */
+    excludePatterns?: LabelMatcher[];
     jobConfig: Record<string, unknown>;
     repoUrl: string;
     ref: string;

package/dist/config/schema.d.ts

@@ -69,6 +69,8 @@ export declare const sharedConfigSchema: z.ZodObject<{
         none: "none";
     }>>;
     agentTokenTtlMs: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    rosterGraceMs: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+    rosterTtlMs: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
     queue: z.ZodOptional<z.ZodObject<{
         maxDepth: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
         timeoutMs: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
@@ -156,6 +158,8 @@ export declare const appConfigSchema: z.ZodObject<{
         none: "none";
     }>>;
     agentTokenTtlMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    rosterGraceMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    rosterTtlMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     queueMaxDepth: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     queueTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     queueBackpressureThreshold: z.ZodDefault<z.ZodCoercedNumber<unknown>>;

package/dist/config/types.d.ts

@@ -50,6 +50,9 @@ export interface SharedConfig {
     };
     agentAuth?: 'token' | 'none';
     agentTokenTtlMs?: number;
+    rosterGraceMs?: number;
+    rosterTtlMs?: number;
+    maxFanoutHosts?: number;
     queue?: {
         maxDepth?: number;
         timeoutMs?: number;
@@ -135,6 +138,12 @@ export interface AppConfig {
     agentAuth: 'token' | 'none';
     /** Agent token TTL in milliseconds */
     agentTokenTtlMs: number;
+    /** Host roster: static grace before a disconnected static host reads unreachable (ms) */
+    rosterGraceMs: number;
+    /** Host roster: ephemeral GC ttl — past this a disconnected ephemeral host is reaped (ms) */
+    rosterTtlMs: number;
+    /** Cap on per-host children produced by a runsOnAll fan-out */
+    maxFanoutHosts: number;
     /** Queue settings */
     queueMaxDepth: number;
     queueTimeoutMs: number;

package/dist/config.d.ts

@@ -82,6 +82,9 @@ declare const configSchema: z.ZodObject<{
         none: "none";
     }>>;
     agentTokenTtlMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    rosterGraceMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    rosterTtlMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    maxFanoutHosts: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     eventRouterMaxChainDepth: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     eventRouterRateLimitPerWorkflowPerMinute: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     eventRouterEventTtlSeconds: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
@@ -197,6 +200,9 @@ export declare const envDef: import("@kici-dev/shared/env").DefineEnvResult<{
     pgCustomerSecrets: boolean;
     agentAuth: "token" | "none";
     agentTokenTtlMs: number;
+    rosterGraceMs: number;
+    rosterTtlMs: number;
+    maxFanoutHosts: number;
     eventRouterMaxChainDepth: number;
     eventRouterRateLimitPerWorkflowPerMinute: number;
     eventRouterEventTtlSeconds: number;

package/dist/db/migrations/039_host_roster.d.ts

@@ -0,0 +1,19 @@
+import { type Kysely } from 'kysely';
+/**
+ * `host_roster` is KiCI's declared inventory: one durable row per agent the
+ * cluster has ever enrolled, reconciled from the in-memory AgentRegistry on
+ * every register/unregister. `lifecycle_class` (snapshot of the auth token's
+ * agent_type) drives reaping — `ephemeral` rows are GC'd past their TTL,
+ * `static` rows persist and read as `unreachable` when their heartbeat goes
+ * stale. `connected_instance_id` records which orchestrator holds the live WS
+ * (cluster liveness + the host-fanout reroute target); NULL = disconnected.
+ *
+ * The roster lives in the shared cluster DB (one table, all instances). Status
+ * is derived at read from the shared `last_seen` + `connected_instance_id`, so
+ * every instance agrees regardless of which one holds the agent's live WS.
+ *
+ * Idempotent: a re-run on a DB that already has the table is a no-op.
+ */
+export declare function up(db: Kysely<unknown>): Promise<void>;
+export declare function down(db: Kysely<unknown>): Promise<void>;
+//# sourceMappingURL=039_host_roster.d.ts.map

package/dist/db/migrations/040_runsonall_pin.d.ts

@@ -0,0 +1,4 @@
+import { type Kysely } from 'kysely';
+export declare function up(db: Kysely<unknown>): Promise<void>;
+export declare function down(db: Kysely<unknown>): Promise<void>;
+//# sourceMappingURL=040_runsonall_pin.d.ts.map

package/dist/db/migrations/041_wave_gated.d.ts

@@ -0,0 +1,4 @@
+import { type Kysely } from 'kysely';
+export declare function up(db: Kysely<unknown>): Promise<void>;
+export declare function down(db: Kysely<unknown>): Promise<void>;
+//# sourceMappingURL=041_wave_gated.d.ts.map

package/dist/db/migrations/042_dispatch_queue_patterns.d.ts

@@ -0,0 +1,4 @@
+import { type Kysely } from 'kysely';
+export declare function up(db: Kysely<unknown>): Promise<void>;
+export declare function down(db: Kysely<unknown>): Promise<void>;
+//# sourceMappingURL=042_dispatch_queue_patterns.d.ts.map

package/dist/db/types.d.ts

@@ -50,6 +50,7 @@ export interface Database {
     scaler_reservations: ScalerReservationsTable;
     attestations: AttestationsTable;
     remote_sources: RemoteSourcesTable;
+    host_roster: HostRosterTable;
 }
 /**
  * Cluster metadata table
@@ -138,6 +139,10 @@ export interface DispatchQueueTable {
     request_id: string | null;
     /** JSONB array of exclusion labels. Default '[]'. */
     exclude_labels: Generated<string>;
+    /** Regex matchers (LabelMatcher[]) the job requires; JS post-filter on top of runs_on_labels. Default '[]'. */
+    runs_on_patterns: Generated<string>;
+    /** Regex matchers (LabelMatcher[]) that disqualify an agent; JS post-filter. Default '[]'. */
+    exclude_patterns: Generated<string>;
     /** Routing key (e.g. "github:12345") so dispatch can pick the right
      *  per-app provider bundle in multi-app setups. Required (NOT NULL). */
     routing_key: string;
@@ -173,6 +178,12 @@ export interface DispatchQueueTable {
     ack_deadline: ColumnType<Date | null, Date | null | undefined, Date | null>;
     /** Agent the dispatch was sent to (for ack-timeout disconnect + logging). */
     ack_agent_id: ColumnType<string | null, string | null | undefined, string | null>;
+    /**
+     * For a runsOnAll host-fanout child: the agent this job is pinned to. The
+     * dispatcher routes it only to that agent and the queue drain never hands it
+     * to another. NULL for normal label-routed jobs.
+     */
+    pinned_agent_id: ColumnType<string | null, string | null | undefined, string | null>;
 }
 /**
  * Deduplication cache table
@@ -354,6 +365,23 @@ export interface ExecutionJobTable {
     ready_at: Date | null;
     /** Dynamic group membership tag (NULL for static jobs). */
     group_name: string | null;
+    /** Base (logical) job name for a fan-out child. NULL for non-fanned jobs. */
+    base_job_name: string | null;
+    /** Fan-out kind for a child: 'matrix' | 'host'. NULL for non-fanned jobs. */
+    variant_kind: string | null;
+    /** Fan-out label for a child: matrix suffix or hostname. NULL for non-fanned jobs. */
+    variant_label: string | null;
+    /**
+     * Wave gate: a fan-out child beyond the job's `maxParallel` window is held
+     * (`true`) instead of dispatched. Cleared by the wave-scheduler when a sibling
+     * reaches terminal and an in-flight slot frees up. NULL/false for any job not
+     * held by a rolling wave.
+     */
+    wave_gated: Generated<boolean>;
+    /** The fan-out base's `maxParallel` wave width, stamped on every child. NULL = no bounded wave. */
+    wave_max_parallel: number | null;
+    /** The fan-out base's `failFast` policy, stamped on every child. NULL = no bounded wave. */
+    wave_fail_fast: boolean | null;
     /** When this record was created */
     created_at: Generated<Date>;
     /**
@@ -1529,6 +1557,39 @@ export interface RemoteSourcesTable {
 }
 export type RemoteSourceRow = Selectable<RemoteSourcesTable>;
 export type NewRemoteSourceRow = Insertable<RemoteSourcesTable>;
+/**
+ * Host roster table (host_roster).
+ *
+ * KiCI's declared inventory: one durable row per agent the cluster has ever
+ * enrolled, reconciled from the in-memory AgentRegistry on register/unregister.
+ * `lifecycle_class` (snapshot of the auth token's `agent_type`) drives reaping;
+ * `connected_instance_id` records which orchestrator holds the live WS (cluster
+ * liveness + the host-fanout reroute target), null when disconnected. Status is
+ * derived at read from the shared `last_seen` + `connected_instance_id`.
+ */
+export interface HostRosterTable {
+    /** UUID primary key */
+    id: Generated<string>;
+    /** The agent identity the pin targets; unique. */
+    agent_id: string;
+    /** FK to agent_tokens.id (provenance), or null when auth mode is none. */
+    token_id: string | null;
+    /** Snapshot of the token's agent_type: 'static' | 'ephemeral'. */
+    lifecycle_class: string;
+    /** JSON-encoded string[] of the post-Gate-1 validated labels. */
+    labels: string;
+    hostname: string | null;
+    platform: string | null;
+    arch: string | null;
+    /** Which orchestrator instance holds the live WS; null = disconnected. */
+    connected_instance_id: string | null;
+    last_seen: ColumnType<Date, Date | string | undefined, Date | string>;
+    created_at: Generated<Date>;
+    updated_at: ColumnType<Date, Date | string | undefined, Date | string>;
+}
+export type HostRosterRow = Selectable<HostRosterTable>;
+export type NewHostRosterRow = Insertable<HostRosterTable>;
+export type HostRosterUpdate = Updateable<HostRosterTable>;
 /**
  * Scaler spawning-agents table (scaler_spawning_agents).
  *

package/dist/diagnostics/fleet-collector.d.ts

@@ -12,8 +12,8 @@ import { z } from 'zod';
 /** Per-node collection outcome recorded in the fleet manifest. */
 export declare const FleetNodeStatus: z.ZodEnum<{
     error: "error";
-    ok: "ok";
     unreachable: "unreachable";
+    ok: "ok";
     timeout: "timeout";
 }>;
 export type FleetNodeStatus = z.infer<typeof FleetNodeStatus>;

package/dist/environments/held-runs.d.ts

@@ -71,6 +71,15 @@ export interface ReleaseSignal {
     scope: HoldScope;
     /** Set only for step-scoped holds. */
     stepIndex: number | null;
+    /**
+     * What kind of gate created the hold. `explicit` (SDK `requireApproval`) holds
+     * a real root job and resumes by re-dispatching it; `environment` covers the
+     * workflow install-gate (wait-timer / concurrency / env approval) which resumes
+     * by rebuilding the workflow dispatch context. The resume router keys off this
+     * so a workflow-scoped explicit hold goes through the job re-dispatch path
+     * rather than the install-gate path (which has no pending workflow context).
+     */
+    triggerSource: TriggerSource;
 }
 /** Options for listing held runs. */
 export interface ListHeldRunsOptions {

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 {
@@ -322,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;
@@ -216,6 +218,27 @@ export interface OrchestratorHooks {
  * 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
@@ -226,7 +249,29 @@ export declare function buildUpstreamOutputsByBase(baseNames: string[], rows: Ar
     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

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';
@@ -109,6 +109,46 @@ export interface DispatchMatchedWorkflowOptions {
      */
     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.
  *
@@ -125,4 +165,5 @@ export interface DispatchMatchedWorkflowOptions {
  *   J. deferred dynamic dispatch (fire-and-forget per dynamic entry)
  */
 export declare function dispatchMatchedWorkflow(ctx: WorkflowDispatchContext, opts?: DispatchMatchedWorkflowOptions): Promise<DispatchMatchedWorkflowResult>;
+export {};
 //# sourceMappingURL=dispatch-matched-workflow.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}`.
@@ -320,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/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