@kici-dev/orchestrator 0.1.21 → 0.1.22

package/dist/config.d.ts

@@ -68,6 +68,7 @@ declare const configSchema: z.ZodObject<{
     staleDetectorScanIntervalMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     staleDetectorThresholdMultiplier: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     jobHeartbeatIntervalMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    githubAppNameRefreshIntervalMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     secretKey: z.ZodOptional<z.ZodString>;
     secretKeyFile: z.ZodOptional<z.ZodString>;
     secretKeyOld: z.ZodOptional<z.ZodString>;
@@ -84,6 +85,8 @@ declare const configSchema: z.ZodObject<{
     agentTokenTtlMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     rosterGraceMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     rosterTtlMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    hostRebootDeadlineMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    orchestratorHostAgentId: z.ZodOptional<z.ZodString>;
     maxFanoutHosts: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     eventRouterMaxChainDepth: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     eventRouterRateLimitPerWorkflowPerMinute: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
@@ -197,11 +200,13 @@ export declare const envDef: import("@kici-dev/shared/env").DefineEnvResult<{
     staleDetectorScanIntervalMs: number;
     staleDetectorThresholdMultiplier: number;
     jobHeartbeatIntervalMs: number;
+    githubAppNameRefreshIntervalMs: number;
     pgCustomerSecrets: boolean;
     agentAuth: "token" | "none";
     agentTokenTtlMs: number;
     rosterGraceMs: number;
     rosterTtlMs: number;
+    hostRebootDeadlineMs: number;
     maxFanoutHosts: number;
     eventRouterMaxChainDepth: number;
     eventRouterRateLimitPerWorkflowPerMinute: number;
@@ -265,6 +270,7 @@ export declare const envDef: import("@kici-dev/shared/env").DefineEnvResult<{
     secretKeyOld?: string | undefined;
     secretKeyFileOld?: string | undefined;
     bootstrapAdminToken?: string | undefined;
+    orchestratorHostAgentId?: string | undefined;
     testEventFailFirstN?: string | undefined;
     otelExporterOtlpEndpoint?: string | undefined;
     clusterName?: string | undefined;

package/dist/dashboard/needs-edges.d.ts

@@ -1,13 +1,14 @@
-import { IfFailedPolicy } from '@kici-dev/engine';
+import type { ExecutionJobStatus } from '@kici-dev/engine';
 /** A single resolved upstream dependency edge for a job. */
 export interface JobNeedEdge {
     upstreamName: string;
-    ifFailed: IfFailedPolicy;
+    /** Upstream terminal statuses that satisfy this edge (the run-on set). */
+    runOn: ExecutionJobStatus[];
 }
 /** Group raw execution_job_needs rows by downstream job_name. */
 export declare function groupNeedsByJobName(rows: ReadonlyArray<{
     job_name: string;
     upstream_name: string;
-    if_failed: string;
+    run_on: string;
 }>): Map<string, JobNeedEdge[]>;
 //# sourceMappingURL=needs-edges.d.ts.map

package/dist/db/migrations/047_needs_run_on.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=047_needs_run_on.d.ts.map

package/dist/db/migrations/048_host_reboot_pending.d.ts

@@ -0,0 +1,19 @@
+import { type Kysely } from 'kysely';
+/**
+ * Add `host_roster.reboot_pending_until timestamptz NULL` — the persisted
+ * reboot-pending flag for workflow-level host restart.
+ *
+ * Set when an agent's `restartHost()` step calls `host.requestReboot` (so it
+ * survives an orchestrator restart during the host's reboot window). While the
+ * value is in the future it (1) makes the agent's imminent disconnect an
+ * expected reboot rather than a recovery-fail, (2) gates the pinned-drain off
+ * so the post-restart job is not dispatched into the about-to-reboot box, and
+ * (3) clears on the next reconnect (down-then-up), releasing the held job. NULL
+ * = no reboot pending.
+ *
+ * Idempotent (`ADD COLUMN IF NOT EXISTS`); additive, so staging data is
+ * preserved.
+ */
+export declare function up(db: Kysely<unknown>): Promise<void>;
+export declare function down(db: Kysely<unknown>): Promise<void>;
+//# sourceMappingURL=048_host_reboot_pending.d.ts.map

package/dist/db/migrations/049_held_runs_payload.d.ts

@@ -0,0 +1,14 @@
+import { type Kysely } from 'kysely';
+/**
+ * Add `held_runs.payload jsonb NULL` — the drift payload captured when a
+ * `when: 'drift'` step-approval gate fires. Holds `{ summaryMarkdown, drift }`:
+ * the author's `summarize(drift)` rendering plus the structured drift blob, so
+ * the dashboard approval queue and the CLI render the computed diff the
+ * operator approves. NULL for every non-drift hold.
+ *
+ * Idempotent (`ADD COLUMN IF NOT EXISTS`); additive, so staging data is
+ * preserved.
+ */
+export declare function up(db: Kysely<unknown>): Promise<void>;
+export declare function down(db: Kysely<unknown>): Promise<void>;
+//# sourceMappingURL=049_held_runs_payload.d.ts.map

package/dist/db/migrations/050_sources_slug.d.ts

@@ -0,0 +1,17 @@
+import { type Kysely } from 'kysely';
+/**
+ * Add `sources.slug TEXT NULL` — the GitHub App slug (the URL-safe identifier
+ * GitHub assigns, e.g. `my-kici-app`).
+ *
+ * For GitHub-App sources GitHub is the source of truth for both the display
+ * `name` and the `slug`: both are captured at creation and kept fresh by the
+ * daily refresher + `kici-admin source refresh`. NULL when the identity fetch
+ * hasn't populated it yet (manual `--app-id` flow whose initial fetch failed,
+ * or a row created before the rollout).
+ *
+ * Idempotent (`ADD COLUMN IF NOT EXISTS`); additive, so staging data is
+ * preserved.
+ */
+export declare function up(db: Kysely<unknown>): Promise<void>;
+export declare function down(db: Kysely<unknown>): Promise<void>;
+//# sourceMappingURL=050_sources_slug.d.ts.map

package/dist/db/types.d.ts

@@ -1,5 +1,5 @@
 import type { ColumnType, Generated, Insertable, Selectable, Updateable } from 'kysely';
-import type { ApprovalRequirement, ApproverClause, InitFailure } from '@kici-dev/engine';
+import type { ApprovalRequirement, ApproverClause, InitFailure, StepApprovalPayload } from '@kici-dev/engine';
 /**
  * PostgreSQL-only database types.
  * Column names use snake_case matching the actual database column names.
@@ -486,8 +486,13 @@ export interface ExecutionJobNeedsTable {
     job_name: string;
     /** Upstream job name (the job that must complete first) */
     upstream_name: string;
-    /** Per-edge failure policy: 'skip' (default) or 'run' */
-    if_failed: Generated<string>;
+    /**
+     * Per-edge run-on status-set: a JSON-encoded array of upstream terminal
+     * statuses (ExecutionJobStatus[]) that satisfy the edge. Default
+     * `'["success"]'`. The downstream dispatches when the upstream's terminal
+     * status is a member of this set.
+     */
+    run_on: Generated<string>;
 }
 export type ExecutionJobNeeds = Selectable<ExecutionJobNeedsTable>;
 export type NewExecutionJobNeeds = Insertable<ExecutionJobNeedsTable>;
@@ -695,7 +700,7 @@ export interface HeldRunsTable {
     step_index: number | null;
     /**
      * What created the hold: 'environment' (mandatory env policy) | 'explicit'
-     * (SDK `requireApproval`). Engine `TriggerSource`.
+     * (SDK `approval`). Engine `TriggerSource`.
      */
     trigger_source: Generated<string>;
     /**
@@ -703,6 +708,11 @@ export interface HeldRunsTable {
      * must satisfy. Null for legacy rows that predate the approval model.
      */
     approval_requirement: ColumnType<ApprovalRequirement | null, ApprovalRequirement | string | null | undefined, ApprovalRequirement | string | null>;
+    /**
+     * Drift payload `{ summaryMarkdown, drift }` captured when a `when: 'drift'`
+     * step-approval gate fires. Null for every non-drift hold.
+     */
+    payload: ColumnType<StepApprovalPayload | null, StepApprovalPayload | string | null | undefined, StepApprovalPayload | string | null>;
 }
 export type HeldRun = Selectable<HeldRunsTable>;
 export type NewHeldRun = Insertable<HeldRunsTable>;
@@ -1215,6 +1225,12 @@ export interface SourcesTable {
     routing_key: string;
     /** JSONB config (non-sensitive, e.g. { appId: '12345' }) */
     config: string;
+    /**
+     * GitHub App slug (the URL-safe identifier GitHub assigns, e.g.
+     * `my-kici-app`). NULL until the GitHub identity fetch populates it. GitHub
+     * is the source of truth for both `name` and `slug` on GitHub-App sources.
+     */
+    slug: string | null;
     /** Customer/org identifier for secret and environment scoping */
     customer_id: Generated<string>;
     /** When this source was created */
@@ -1616,6 +1632,13 @@ export interface HostRosterTable {
      */
     host_properties: ColumnType<Record<string, string | number | boolean>, Record<string, string | number | boolean> | string | undefined, Record<string, string | number | boolean> | string>;
     last_seen: ColumnType<Date, Date | string | undefined, Date | string>;
+    /**
+     * Reboot-pending flag for workflow-level host restart. When set to a future
+     * timestamp, the host's imminent disconnect is an expected reboot (not a
+     * recovery-fail) and its pinned post-restart job is held until the host
+     * reconnects (down-then-up). NULL = no reboot pending.
+     */
+    reboot_pending_until: ColumnType<Date | null, Date | string | null, Date | string | null>;
     created_at: Generated<Date>;
     updated_at: ColumnType<Date, Date | string | undefined, Date | string>;
 }

package/dist/deployment/deployment-identity.d.ts

@@ -0,0 +1,9 @@
+import { type DeploymentIdentity } from '@kici-dev/engine';
+/**
+ * Read the orchestrator's deployment shape from the env the installer injects
+ * (`KICI_DEPLOY_MODE` / `KICI_DEPLOY_CONTAINER` / `KICI_DEPLOY_CONTAINER_RUNTIME`).
+ * Hand-run / dev orchestrators carry no `KICI_DEPLOY_*` env and report `unknown`.
+ * Container fields are kept only for the `compose` mode.
+ */
+export declare function readDeploymentIdentity(env?: NodeJS.ProcessEnv): DeploymentIdentity;
+//# sourceMappingURL=deployment-identity.d.ts.map

package/dist/entry-helpers.d.ts

@@ -19,6 +19,13 @@ export interface ProviderSource {
     routingKey: string;
     name: string;
     subtype: SourceSubtype;
+    /**
+     * GitHub App slug (URL-safe identifier GitHub assigns). Only set for
+     * GitHub-App sources, where it propagates orchestrator → Platform → dashboard
+     * alongside the display `name`. Undefined for generic / universal-git / local
+     * sources, and for a GitHub source whose identity fetch hasn't run yet.
+     */
+    slug?: string;
 }
 /**
  * Map a generic_webhook_sources `provider_type` (plus optional `git_config`

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

@@ -4,7 +4,7 @@
  * Manages the lifecycle: pending -> approved/rejected/expired.
  */
 import { type Kysely } from 'kysely';
-import { type ApprovalRequirement, type ApproverClause, ApprovalDecision, HoldScope, TriggerSource } from '@kici-dev/engine';
+import { type ApprovalRequirement, type ApproverClause, type StepApprovalPayload, ApprovalDecision, HoldScope, TriggerSource } from '@kici-dev/engine';
 import type { Database, HeldRun, HeldRunApproval } from '../db/types.js';
 /** Status values for held runs (held_runs table). */
 export declare enum HeldRunStatus {
@@ -51,6 +51,12 @@ export interface CreateHoldData {
      * the automated release sweeps can find their rows.
      */
     holdType?: string;
+    /**
+     * Drift payload `{ summaryMarkdown, drift }` captured for a `when: 'drift'`
+     * step gate; persisted to `held_runs.payload` and surfaced in the dashboard
+     * approval queue + the CLI. Omit for non-drift holds.
+     */
+    payload?: StepApprovalPayload;
 }
 /** A single decision to record against a hold. */
 export interface RecordDecisionData {

package/dist/github-app-name-refresher/github-app-name-refresher.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Daily refresh of every GitHub source's display name + slug from GitHub.
+ *
+ * GitHub is the source of truth for a GitHub-App source's display name and
+ * slug. They are captured at creation, but an operator can rename the App in
+ * the GitHub UI afterwards — this periodic task re-fetches `GET /app` for each
+ * GitHub source and, when the name or slug drifted, writes the new values to
+ * the `sources` row. The `sources_change` DB trigger then fans the change out
+ * (SourceManager reload → `platformClient.updateSources()` → re-register), so
+ * the Platform `webhook_sources` row and the dashboard Sources tab pick up the
+ * new name/slug without any extra plumbing here.
+ *
+ * Lifecycle mirrors `StaleRunDetector`: `start()` runs an immediate refresh
+ * (so a rename made while the orchestrator was down propagates on next boot)
+ * then a `setInterval`; `stop()` clears it. Per-source errors are logged and
+ * never abort the loop.
+ */
+/** The slice of {@link SourceStore} this module needs. */
+export interface RefreshableSourceStore {
+    listSources(): Promise<Array<{
+        routing_key: string;
+        provider: string;
+        name: string;
+        slug: string | null;
+    }>>;
+    getSourceWithSecrets(routingKey: string): Promise<{
+        provider: string;
+        config: string;
+        privateKey: string;
+    } | null>;
+    updateSource(routingKey: string, updates: {
+        name?: string;
+        slug?: string | null;
+    }): Promise<unknown>;
+}
+/** Fetch a GitHub App's authoritative identity. Matches `fetchGithubAppIdentity`. */
+export type FetchGithubAppIdentity = (creds: {
+    appId: string;
+    privateKey: string;
+}) => Promise<{
+    name: string;
+    slug: string;
+}>;
+/** Outcome of a single source refresh. */
+export interface RefreshResult {
+    routingKey: string;
+    changed: boolean;
+    oldName: string;
+    newName: string;
+    oldSlug: string | null;
+    newSlug: string;
+}
+/**
+ * Re-fetch one GitHub source's identity from GitHub and persist it when the
+ * name or slug drifted. Shared by the daily task and `kici-admin source
+ * refresh`. Throws for a missing or non-GitHub routing key.
+ */
+export declare function refreshGithubSourceIdentity(sourceStore: RefreshableSourceStore, routingKey: string, fetchIdentity: FetchGithubAppIdentity): Promise<RefreshResult>;
+export interface GithubAppNameRefresherDeps {
+    sourceStore: RefreshableSourceStore;
+    fetchIdentity: FetchGithubAppIdentity;
+    /** Refresh cadence in ms. Default cluster value: 24h (`config.githubAppNameRefreshIntervalMs`). */
+    scanIntervalMs: number;
+}
+export declare class GithubAppNameRefresher {
+    private readonly sourceStore;
+    private readonly fetchIdentity;
+    private readonly scanIntervalMs;
+    private interval;
+    constructor(deps: GithubAppNameRefresherDeps);
+    /** Immediate refresh then periodic scans. */
+    start(): Promise<void>;
+    stop(): void;
+    /** Refresh every GitHub source once. Per-source failures are isolated. */
+    refresh(): Promise<void>;
+}
+//# sourceMappingURL=github-app-name-refresher.d.ts.map

package/dist/index.js

@@ -1892,6 +1892,23 @@ function createInstallationOctokit(config, installationId) {
 * registration and returns it on the conversion response, so both GitHub and
 * the Platform end up sharing the same secret with zero operator effort.
 */
+/**
+* Validate a self-hosted webhook URL supplied via `source add github
+* --webhook-url`. Must be a well-formed absolute `https://` URL. Returns the URL
+* verbatim on success; throws a clear error otherwise. The validated URL is
+* baked into `manifest.hook_attributes.url` as-is — KiCI adds no ingress and
+* does not receive events at it; the operator owns delivery.
+*/
+function validateWebhookUrl(value) {
+	let url;
+	try {
+		url = new URL(value);
+	} catch {
+		throw new Error(`--webhook-url must be a valid absolute URL: ${value}`);
+	}
+	if (url.protocol !== "https:") throw new Error(`--webhook-url must be an https:// URL (got ${url.protocol}//…)`);
+	return value;
+}
 function buildGithubAppManifest(input) {
 	return {
 		name: input.name,
@@ -1930,6 +1947,7 @@ async function convertManifestCode(code, deps = {}) {
 	return {
 		appId: String(d.id),
 		slug: d.slug,
+		name: d.name,
 		privateKey: d.pem,
 		webhookSecret: d.webhook_secret,
 		clientId: d.client_id,
@@ -2178,7 +2196,8 @@ async function storeAndRegister(opts, client, deps, creds) {
 	try {
 		return await client.post("/api/v1/admin/sources", {
 			provider: "github",
-			name: opts.name,
+			name: creds.name,
+			slug: creds.slug,
 			appId: creds.appId,
 			privateKey: creds.privateKey,
 			webhookSecret: creds.webhookSecret
@@ -2195,7 +2214,7 @@ async function storeAndRegister(opts, client, deps, creds) {
 	}
 }
 async function runGithubManifestSetup(opts, client, deps = realManifestSetupDeps) {
-	const webhookUrl = await resolveWebhookUrl(client);
+	const webhookUrl = opts.webhookUrl ? validateWebhookUrl(opts.webhookUrl) : await resolveWebhookUrl(client);
 	const state = randomBytes(16).toString("hex");
 	const createUrl = manifestCreateUrl(opts.githubOrg);
 	const loopback = await deps.startLoopback({

package/dist/orchestrator-core.d.ts

@@ -23,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 LabelMatcher, type PeerHeartbeat, type PeerLogsCollectRequest, type PeerToPeerMessage } from '@kici-dev/engine';
+import { ExecutionJobStatus, 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';
@@ -253,6 +253,17 @@ export declare function buildUpstreamOutputsByBase(baseNames: string[], rows: Ar
     variant_label?: string | null;
     status?: string | null;
 }>): Record<string, Record<string, unknown>> | undefined;
+/**
+ * Build the downstream `upstreamJobStatuses` map keyed by each upstream job
+ * row's name. A single non-fanned upstream is keyed by its base name; a
+ * fanned-out upstream contributes one entry per expanded child name (`base
+ * (child)`). The agent uses this to stamp `ctx.needs.<job>.status` (single) and
+ * the per-child status of group / matrix / host-fanout entries.
+ */
+export declare function buildUpstreamStatusesByBase(rows: Array<{
+    job_name: string;
+    status?: string | null;
+}>): Record<string, ExecutionJobStatus> | undefined;
 /**
  * Fold a `runsOnAll` upstream's host children into the `byHost` envelope
  * `{ byHost: { '<host>': outputs }, summary: { succeededHosts, failedHosts, outputs } }`.
@@ -302,6 +313,7 @@ export declare function buildMatrixOutputsEnvelope(baseName: string, children: A
 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;
+    upstreamJobStatuses: Record<string, ExecutionJobStatus> | undefined;
 }>;
 export declare function bootstrapOrchestrator(config: AppConfig, hooks: OrchestratorHooks, options?: {
     otelSdk?: {

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

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

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

@@ -13,8 +13,8 @@
  * exported function is a narrative orchestrator that threads the typed
  * results through the pipeline.
  */
-import { CacheRefScope } from '@kici-dev/engine';
-import type { LabelMatcher, LockWorkflow, LockJob, SimulatedEvent, WorkflowDecision, MaterializedJob } from '@kici-dev/engine';
+import { ExecutionJobStatus, InitFailureCategory, CacheRefScope } from '@kici-dev/engine';
+import type { LabelMatcher, LockWorkflow, LockJob, HostTargetSelector, SimulatedEvent, WorkflowDecision, MaterializedJob, ResolvedHostAgent } from '@kici-dev/engine';
 import { type HostRosterStore } from '../agent/host-roster.js';
 import type { WebhookInfo } from '../webhook/handler.js';
 import type { ProviderBundle } from '../provider-registry.js';
@@ -41,7 +41,15 @@ export declare function deriveCacheRefScope(trust: TrustResolution | undefined):
 export interface WorkflowDispatchContext {
     info: WebhookInfo;
     deps: ProcessingDeps;
-    bundle: ProviderBundle;
+    /**
+     * Provider bundle for the matched source. Undefined for local-repo test runs
+     * (`kici run` against an inline lock file with no remote provider): in that
+     * mode there is no clone-url builder / check-status poster / clone-token
+     * provider, and `repoUrl` falls back to `''` (the agent treats a missing url
+     * as a local/`fullRepo` clone). The webhook adapter always passes a defined
+     * bundle, so its dispatch behavior is unchanged.
+     */
+    bundle?: ProviderBundle;
     payload: unknown;
     repoIdentifier: string;
     credentials: Record<string, unknown>;
@@ -88,10 +96,36 @@ export interface WorkflowDispatchContext {
      * correct clone + logging.
      */
     extraJobConfig?: Record<string, unknown>;
+    /**
+     * Test-run provenance. Present only for `kici run` / test-trigger dispatches.
+     * When set, `recordRunStart` stamps `is_test_run = true` and
+     * `fixture_id = testRun.fixtureId` on the `execution_runs` row. Undefined for
+     * webhook runs (the stamp block is skipped).
+     */
+    testRun?: {
+        fixtureId: string;
+    };
+    /**
+     * Run-wide flat secrets layered onto EVERY dispatched job's `jobConfig.secrets`
+     * (env-declaring or not). Used by the test path to deliver `kici run --secret`
+     * / `--env` CLI flat secrets, which must reach a job regardless of whether it
+     * declares an `environment:`. Merged UNDER the per-job env-resolved secrets so
+     * the CLI value wins on a key collision (matching the prior B1-env -> A-CLI
+     * precedence). Undefined for webhook runs.
+     */
+    runWideFlatSecrets?: Record<string, string>;
+    /**
+     * Runtime host narrowing from `kici run --target` (Ansible `--limit`). Applied
+     * as a post-filter over each runsOnAll job's matched roster: effective hosts =
+     * runsOnAll ∩ target. Narrow-only. Undefined for webhook runs (no narrowing).
+     */
+    target?: HostTargetSelector;
 }
 export interface DispatchMatchedWorkflowResult {
     /** Number of jobs successfully dispatched (non-rejected). */
     dispatchedJobCount: number;
+    /** Execution job ids of every dispatched/tracked job (root, gated, synthetic). */
+    dispatchedJobIds: string[];
     /** True when the workflow install gate paused the dispatch (held run). */
     held?: boolean;
 }
@@ -110,6 +144,39 @@ export interface DispatchMatchedWorkflowOptions {
      */
     reuseRunId?: string;
 }
+interface RejectedJob {
+    jobId: string;
+    jobName: string;
+    reason: string;
+    /** Explicit init-failure category override; inferred from reason when absent. */
+    category?: InitFailureCategory;
+    /**
+     * Terminal status to record for this job. Defaults to `failed`. A zeroed
+     * `runsOnAll` that intentionally narrowed to no hosts is recorded as `skipped`
+     * (no init-failure) so its downstreams' `when` sets govern propagation.
+     */
+    terminalStatus?: ExecutionJobStatus;
+}
+/**
+ * Phase B orchestrator: probe caches, dispatch the build job (if needed),
+ * and surface enough state for downstream phases to skip / continue
+ * appropriately.
+ */
+/**
+ * Materialize each static job's matrix into dispatchable children. A job whose
+ * matrix is invalid (zero combinations / over the cap) is dropped from the
+ * dispatch list and recorded as a `matrix_expansion` matrix failure so the run's
+ * other jobs still proceed. Dynamic-matrix jobs pass through with a
+ * `pendingDynamicMatrix` marker for the eval flow.
+ */
+/**
+ * Resolve a `runsOnAll` lock job against the declared host roster and partition
+ * the matched hosts into the target set per the `onUnreachable` policy (R2):
+ * `ready` hosts always run; unreachable durable (`static`) hosts hold / fail /
+ * skip; stale ephemeral hosts are always skipped. Throws {@link FanoutError}
+ * when the run can't proceed (fail policy with an absent host, or zero targets).
+ */
+export declare function resolveHostFanoutTargets(lockJob: LockJob, deps: ProcessingDeps, target?: HostTargetSelector): Promise<ResolvedHostAgent[]>;
 /** Exact labels + regex patterns partitioned from a lock job's selectors. */
 interface JobRoutingSelectors {
     runsOnLabels: string[];
@@ -169,6 +236,11 @@ export interface WavePlan {
  * job (single child) or one without `maxParallel` contributes nothing.
  */
 export declare function computeWavePlan(materializedJobs: readonly MaterializedJob[]): WavePlan;
+export declare function materializeStaticJobsSafe(staticJobs: readonly LockJob[], deps: ProcessingDeps, target?: HostTargetSelector): Promise<{
+    materializedJobs: MaterializedJob[];
+    expansionMap: Map<string, readonly string[]>;
+    matrixFailures: RejectedJob[];
+}>;
 export interface GeneratedJobConfig {
     /**
      * The generated lock job with its `name` and `needs` rewritten to expanded

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

@@ -31,7 +31,7 @@
  */
 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 { SecretResolverApi } from '../secrets/secret-resolver.js';
 import type { EnvironmentStore } from '../environments/environment-store.js';
 import { type JobDispatchContext } from '../environments/protection/pipeline.js';
 /** Registry spec carried on the dispatch message (token already resolved). */
@@ -48,7 +48,7 @@ export interface ResolveInstallSecretsArgs {
     resolvedOrgId: string;
     trustResolution: TrustResolution | undefined;
     environmentStore: EnvironmentStore | undefined;
-    secretResolver: SecretResolver | undefined;
+    secretResolver: SecretResolverApi | undefined;
     protectionContext: JobDispatchContext;
     /**
      * Resume path: skip the protection-rule gate (already satisfied) and resolve

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

@@ -1,24 +1,29 @@
 /**
- * DB-backed needs-aware dispatch scheduler ( through).
+ * DB-backed needs-aware dispatch scheduler.
  *
- * This module is the core of 's behavioral change: it replaces the
- * "concurrent dispatch" model with event-driven scheduling that gates ALL
- * needs edges (static-to-static, static-to-dyn-group, dyn-to-static, dyn-to-dyn).
+ * Gates ALL needs edges (static-to-static, static-to-dyn-group, dyn-to-static,
+ * dyn-to-dyn) with event-driven scheduling instead of concurrent dispatch.
  *
  * The scheduler is pure DB — no in-memory state. Every scheduling decision is
  * a fresh DB query against execution_jobs + execution_job_needs. This means
  * zero recovery code on orchestrator restart.
  *
+ * Each edge carries a `run_on` status-set (the upstream terminal statuses that
+ * satisfy the edge). A downstream edge is dispatch-satisfied when the upstream's
+ * terminal status is a member of the edge's run_on set; otherwise the downstream
+ * is skipped. A downstream dispatches only when every edge is satisfied.
+ *
  * Entry points:
  * - insertEdgesForRun: called at run start for static-to-static edges
  * - resolveGroupEdges: called on dynamic-eval completion
  * - evaluateDownstreams: called from onJobStatus(terminal)
  * - recomputeNeedsSatisfied: batch recompute after group resolution
- * - checkSchedulerInvariant: Layer 3 defensive check
+ * - checkSchedulerInvariant: defensive stuck-job check
  * - getFailurePropagationTargets: cascade for transitive skip
  */
 import type { Kysely } from 'kysely';
 import type { Database } from '../db/types.js';
+import { ExecutionJobStatus } from '@kici-dev/engine';
 import type { MaterializedJob } from '@kici-dev/engine';
 /** Result of evaluating downstream jobs after an upstream completes. */
 export interface SchedulerResult {
@@ -48,21 +53,22 @@ export declare function insertEdgesForRun(db: Kysely<Database>, runId: string, j
  * edge row. Empty groups (0 members) trigger immediate needs_satisfied=true
  * for dependents.
  *
- * CRITICAL: dependentStaticJobs carries per-job ifFailed policy from the
+ * CRITICAL: dependentStaticJobs carries the per-job run_on status-set from the
  * NeedsGroupEntry in the lock file. Without this, all group edges would
- * silently default to 'skip'.
+ * silently default to success-only.
  */
 export declare function resolveGroupEdges(db: Kysely<Database>, runId: string, groupName: string, memberJobNames: string[], dependentStaticJobs: Array<{
     jobName: string;
-    ifFailed: 'skip' | 'run';
+    runOn: ExecutionJobStatus[];
 }>): Promise<void>;
 /**
  * Evaluate downstream jobs after an upstream reaches terminal state.
  *
  * This is the core scheduler hook. For each downstream of the completed job:
- * 1. If upstream failed and edge has if_failed='skip', mark downstream as 'skip'
- * 2. Otherwise, check if ALL upstreams are terminal
- * 3. If all satisfied, mark needs_satisfied=true and return for dispatch
+ * 1. If the completed status is not in this edge's run_on set, mark the
+ *    downstream as 'skip' immediately.
+ * 2. Otherwise, check if ALL upstreams are terminal and satisfied.
+ * 3. If all satisfied, mark needs_satisfied=true and return for dispatch.
  */
 export declare function evaluateDownstreams(db: Kysely<Database>, runId: string, completedJobName: string, completedStatus: string): Promise<SchedulerResult[]>;
 /**
@@ -80,8 +86,11 @@ export declare function recomputeNeedsSatisfied(db: Kysely<Database>, runId: str
  */
 export declare function checkSchedulerInvariant(db: Kysely<Database>, runId: string): Promise<string[]>;
 /**
- * cascade: find all transitive downstreams that should be skipped
- * due to failure propagation. Only follows edges where if_failed='skip'.
+ * Failure-propagation cascade: find all transitive downstreams that should be
+ * skipped because a terminal upstream's status is not in their edge's run_on
+ * set. At each hop, the propagating job's actual terminal status decides which
+ * downstream edges propagate (status not in run_on → the downstream skips and
+ * propagates further).
  */
 export declare function getFailurePropagationTargets(db: Kysely<Database>, runId: string, failedJobName: string): Promise<string[]>;
 //# sourceMappingURL=needs-scheduler.d.ts.map