@kici-dev/orchestrator 0.1.20 → 0.1.22

package/dist/lockfile-validate.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Lock-load shape + compatibility validation.
+ *
+ * A fetched lock must be a valid JSON document whose schemaVersion matches this
+ * orchestrator's engine SCHEMA_VERSION exactly, and whose routing matchers are
+ * well-formed LabelMatcher objects. A lock compiled by an older engine stored
+ * `runsOn` as a plain string array; without this gate those strings would parse
+ * past the dispatch path as an empty label set and mis-route jobs to an
+ * arbitrary scaler. These checks run at the cache choke point and surface as a
+ * `LockFileParseError` (the established corrupt-lock signal).
+ */
+import { type LockFile } from '@kici-dev/engine';
+/** Parse the raw lock JSON and assert the minimal document shape. */
+export declare function parseLockDocument(raw: string, repoIdentifier: string, ref: string): LockFile;
+/** Reject a lock whose schemaVersion does not exactly match this orchestrator. */
+export declare function assertLockFileSchemaCompatible(lockFile: LockFile): void;
+/**
+ * Walk every static job's runsOn / excludeLabels / runsOnAll matchers and throw
+ * if any element is not a valid LabelMatcher. Dynamic job generators carry no
+ * static routing matchers, so only static jobs are checked (mirrors
+ * assertLockFileRegexesSafe).
+ */
+export declare function assertLockFileMatchersValid(lockFile: LockFile): void;
+//# sourceMappingURL=lockfile-validate.d.ts.map

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,9 @@
  * exported function is a narrative orchestrator that threads the typed
  * results through the pipeline.
  */
-import { CacheRefScope } from '@kici-dev/engine';
-import type { LabelMatcher, LockWorkflow, 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';
 import type { TrustResolution } from '../security/trust-resolver.js';
@@ -40,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>;
@@ -87,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;
 }
@@ -109,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[];
@@ -126,6 +194,25 @@ export declare function runsOnSelectorsForLockJob(lockJob: {
     runsOn?: readonly LabelMatcher[];
     excludeLabels?: readonly LabelMatcher[];
 }): JobRoutingSelectors;
+/**
+ * Resolve a generated job's single bare-`agentId` `runsOn` into a host pin.
+ *
+ * The documented inventory fan-out pattern is `runsOn: [h.agentId]`. A bare
+ * agentId is not a label any agent advertises, so the normal label path leaves
+ * the job `queued-no-backend`. When the single exact label names a known roster
+ * host, resolve it to a `pinnedAgentId` dispatch (+ the host's coordinator for
+ * cross-cluster reroute) — exact parity with how `runsOnAll` children pin. Any
+ * other shape (multi-label, a regex pattern, a non-roster label, or no roster
+ * store) returns null and the caller keeps normal label routing.
+ */
+export declare function resolveRosterAgentPin(args: {
+    runsOnLabels: string[];
+    runsOnPatterns: LabelMatcher[];
+    hostRosterStore: HostRosterStore | undefined;
+}): Promise<{
+    pinnedAgentId: string;
+    connectedInstanceId: string | null;
+} | null>;
 /** 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). */
@@ -149,6 +236,43 @@ 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
+     * matrix-child names (identical to the base job for non-matrix generated
+     * jobs). Downstream dispatch / needs-edge / tracking code keys on this name.
+     */
+    genJob: LockJob;
+    genJobConfig: Record<string, unknown>;
+    runsOnLabels: string[];
+    /** Regex matchers the agent's labels must satisfy (JS post-filter). */
+    runsOnPatterns: LabelMatcher[];
+    /** Exact labels the dispatched agent must NOT have. */
+    excludeLabels: string[];
+    /** Regex matchers that disqualify an agent (JS post-filter). */
+    excludePatterns: LabelMatcher[];
+    /** Host-fanout pin: when runsOn resolved to a roster host, route only to it. */
+    pinnedAgentId?: string;
+    /** The host's current coordinator (cross-cluster reroute hint); null = not connected. */
+    connectedInstanceId?: string | null;
+    /** The matrix combination for this child; absent for non-matrix generated jobs. */
+    matrixValues?: Record<string, unknown>;
+}
+/**
+ * Split generated configs into pinned (host-pin dispatch) and unpinned (normal
+ * label routing). A pinned config always rides the dispatcher pin path because
+ * the coordinator's `JobToRoute` shape carries no pin field — routing it via the
+ * coordinator would silently drop the pin.
+ */
+export declare function partitionGeneratedConfigsByPin(configs: readonly GeneratedJobConfig[]): {
+    pinnedConfigs: GeneratedJobConfig[];
+    unpinnedConfigs: GeneratedJobConfig[];
+};
 /**
  * Dispatch a single matched workflow.
  *

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

package/dist/pipeline/processor.d.ts

@@ -33,7 +33,7 @@ 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';
-import type { SecretResolver } from '../secrets/secret-resolver.js';
+import type { SecretResolverApi } from '../secrets/secret-resolver.js';
 import type { ContributorCache } from '../security/contributor-cache.js';
 import type { AccessLogWriter } from '../audit/access-log.js';
 import type { LockFile as FullLockFile, LockWorkflow, SimulatedEvent, WebhookNormalizer } from '@kici-dev/engine';
@@ -281,7 +281,7 @@ export interface ProcessingDeps {
     /** Run coordinator for multi-orchestrator job routing. Optional -- if not set, all jobs dispatch locally (single-orchestrator mode). */
     coordinator?: RunCoordinator;
     /** Secret resolver for dispatch-time secret resolution. Optional -- if not set, secrets are not resolved. */
-    secretResolver?: SecretResolver;
+    secretResolver?: SecretResolverApi;
     /** Optional callback when source locations are extracted from a lock file workflow. */
     onSourceLocationsExtracted?: (workflowName: string, jobName: string, sourceLocations: Array<{
         file: string;

package/dist/pipeline/test-pipeline.d.ts

@@ -1,35 +1,28 @@
 /**
- * Test pipeline processor for CLI-initiated test runs.
+ * Test-trigger adapter for CLI-initiated runs (`kici run`).
  *
- * Reuses the existing webhook processing pipeline steps (lock file fetch,
- * trigger matching, job dispatch) but injects a synthetic event instead
- * of processing a real webhook. This avoids the anti-pattern of calling
- * processWebhook() directly (which expects WebhookInfo from a real webhook).
+ * Resolves the lock file, matched decisions, and fixture-specific concerns
+ * (inline-vs-provider lock, decision selection, fixture-payload storage, the
+ * `allow_local_execution` environment gate, CLI-secret overlay, in-memory
+ * test-run marking), then dispatches each matched workflow through the SAME
+ * shared core as webhooks (`dispatchMatchedWorkflow`). The test path is a thin
+ * adapter — needs-DAG scheduling, `expansionMap` fan-out edges, `runsOnAll`
+ * host fan-out, and deferred init/dynamic dispatch all come from the core.
  *
- * Key differences from processWebhook():
- * - Skips dedup check (test runs are always unique)
- * - Skips webhook normalization (event is already in SimulatedEvent shape)
- * - Skips repo extraction from payload (routing key is provided directly)
- * - deliveryId has `test:` prefix for identification
- * - Execution runs are marked with is_test_run=true and fixture_id
- * - Supports direct workflow execution (bypass trigger matching)
+ * Differences from a webhook run:
+ * - the synthetic event is injected directly (no provider normalization/dedup);
+ * - the lock file may be inline (local repos have no remote provider, so
+ *   `bundle` is undefined);
+ * - `deliveryId` carries a `test:` prefix;
+ * - the run is stamped `is_test_run = true` + `fixture_id` (via the core's
+ *   `testRun` meta) and marked in-memory for live-log broadcast to the CLI;
+ * - CLI-uploaded local secrets win over orchestrator env secrets (the
+ *   decorating secret resolver), and the fixture's `secrets` context mapping
+ *   resolves into namespaced secrets;
+ * - direct workflow execution (bypass trigger matching) is supported.
  */
-import type { LockFileCache } from '../lockfile-cache.js';
-import type { Dispatcher } from '../agent/dispatcher.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 { ProviderRegistry } from '../provider-registry.js';
-import type { SourceCache } from '../cache/index.js';
-import type { BuildCoordinator } from '../cache/index.js';
-import type { DepCache } from '../cache/index.js';
-import type { PendingBuildTracker } from '../cache/index.js';
-import type { SecretResolver } from '../secrets/secret-resolver.js';
-import type { EnvironmentStore } from '../environments/environment-store.js';
-import type { VariableStore } from '../environments/variable-store.js';
-import type { LogStorage } from '../reporting/log-storage.js';
-import type { Kysely } from 'kysely';
-import type { Database } from '../db/types.js';
+import { type ProcessingDeps } from './processor.js';
+import type { CheckMode, HostTargetSelector } from '@kici-dev/engine';
 /**
  * Input for a test trigger request.
  */
@@ -69,6 +62,17 @@ export interface TestTriggerInput {
     inlineLockFile?: string;
     /** When true, repo has no remote -- skip provider lookup, skip clone. */
     fullRepo?: boolean;
+    /**
+     * Run mode for idempotent steps (`apply` | `check` | `check-fail-on-drift`).
+     * Threaded onto each dispatched job's config and persisted on the run.
+     * Omitted means `apply`.
+     */
+    checkMode?: CheckMode;
+    /**
+     * Runtime host narrowing from `kici run --target`. Threaded onto the dispatch
+     * context, where it post-filters each runsOnAll job's matched roster.
+     */
+    target?: HostTargetSelector;
 }
 /**
  * Result of processing a test trigger.
@@ -84,37 +88,12 @@ interface TestTriggerResult {
     jobIds: string[];
 }
 /**
- * Dependencies for the test pipeline processor.
- * All injected for testability.
- */
-export interface TestPipelineDeps {
-    lockFileCache: LockFileCache;
-    dispatcher: Dispatcher;
-    executionTracker?: ExecutionTracker;
-    checkRunReporter?: CheckRunReporter;
-    sourceCache?: SourceCache;
-    buildCoordinator?: BuildCoordinator;
-    depCache?: DepCache;
-    pendingBuilds?: PendingBuildTracker;
-    secretResolver?: SecretResolver;
-    agentRegistry: AgentRegistry;
-    providerRegistry: ProviderRegistry;
-    /** Log storage for persisting test fixture payloads. Optional -- if not set, payload storage is skipped. */
-    logStorage?: LogStorage;
-    /** Database connection for environment protection checks. Optional. */
-    db?: Kysely<Database>;
-    /** Environment store for resolving environment ids in test dispatch parity. Optional. */
-    environmentStore?: EnvironmentStore;
-    /** Variable store for resolving environment variables in test dispatch parity. Optional. */
-    variableStore?: VariableStore;
-}
-/**
- * Process a test trigger through the existing pipeline.
+ * Process a test trigger through the shared dispatch core.
  *
- * Reuses pipeline steps starting from lock file fetch, skipping webhook
- * normalization and dedup. Supports both trigger-matched and direct
- * workflow execution modes.
+ * Resolves the lock file + matched decisions + fixture concerns, then builds a
+ * `WorkflowDispatchContext` per matched workflow and calls
+ * `dispatchMatchedWorkflow` — the same core the webhook path uses.
  */
-export declare function processTestTrigger(input: TestTriggerInput, deps: TestPipelineDeps): Promise<TestTriggerResult>;
+export declare function processTestTrigger(input: TestTriggerInput, deps: ProcessingDeps): Promise<TestTriggerResult>;
 export {};
 //# sourceMappingURL=test-pipeline.d.ts.map

package/dist/providers/github/manifest-form.d.ts

@@ -0,0 +1,15 @@
+/**
+ * GitHub's create-from-manifest flow is an HTML form POST (the `manifest`
+ * JSON cannot ride in a query string). These helpers render the auto-submitting
+ * form and the headless code-display page. Pure string builders — no IO — so
+ * both the CLI loopback server and the static marketing-site page can reuse the
+ * same shapes.
+ */
+export declare function manifestCreateUrl(githubOrg?: string): string;
+export declare function renderManifestFormHtml(opts: {
+    createUrl: string;
+    state: string;
+    manifestJson: string;
+}): string;
+export declare function renderCodeDisplayHtml(code: string): string;
+//# sourceMappingURL=manifest-form.d.ts.map

package/dist/providers/github/manifest.d.ts

@@ -0,0 +1,103 @@
+/**
+ * GitHub App Manifest flow helpers. The manifest encodes KiCI's exact
+ * permissions + events + webhook config so the operator never picks them by
+ * hand — GitHub creates a correctly-configured App from this object in one
+ * click. See docs.github.com "Registering a GitHub App from a manifest".
+ *
+ * The webhook secret is NOT part of the manifest: GitHub generates it during
+ * registration and returns it on the conversion response, so both GitHub and
+ * the Platform end up sharing the same secret with zero operator effort.
+ */
+import { Octokit } from '@octokit/rest';
+export interface GithubManifestInput {
+    /** App name shown on GitHub. */
+    name: string;
+    /** Full https webhook URL (org-scoped) GitHub will POST events to. */
+    webhookUrl: string;
+    /** Loopback or static-page callback GitHub redirects to with the setup code. */
+    redirectUrl: string;
+    /** Optional post-install redirect. */
+    setupUrl?: string;
+}
+/** The JSON object GitHub's create-from-manifest endpoint expects. */
+export interface GithubAppManifest {
+    name: string;
+    url: string;
+    hook_attributes: {
+        url: string;
+        active: boolean;
+    };
+    redirect_url: string;
+    setup_url?: string;
+    public: boolean;
+    default_permissions: Record<string, string>;
+    default_events: string[];
+}
+/**
+ * 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.
+ */
+export declare function validateWebhookUrl(value: string): string;
+export declare function buildGithubAppManifest(input: GithubManifestInput): GithubAppManifest;
+/** Credentials returned by GitHub's manifest-conversion endpoint. */
+export interface GithubAppCredentials {
+    appId: string;
+    slug: string;
+    /** GitHub's display name for the App (the authoritative stored name). */
+    name: string;
+    privateKey: string;
+    webhookSecret: string;
+    clientId?: string;
+    clientSecret?: string;
+    htmlUrl?: string;
+}
+/**
+ * Exchange the short-lived manifest `code` for the App's id, private key, and
+ * webhook secret. Runs server-to-server directly against GitHub — the private
+ * key never transits the Platform.
+ */
+export declare function convertManifestCode(code: string, deps?: {
+    octokit?: Pick<Octokit, 'request'>;
+}): Promise<GithubAppCredentials>;
+/**
+ * Ask GitHub who this App is (`GET /app`, authenticated as the App via its
+ * JWT) and return its authoritative display `name` + `slug`. This is the single
+ * "fetch the App's identity from GitHub" helper, reused at source creation, by
+ * the daily refresher, and by `kici-admin source refresh`.
+ *
+ * GitHub is the source of truth: a rename in the GitHub UI changes the value
+ * `GET /app` returns, which is what keeps the dashboard name fresh.
+ */
+export declare function fetchGithubAppIdentity(creds: Pick<GithubAppCredentials, 'appId' | 'privateKey'>, deps?: {
+    appOctokit?: Pick<Octokit, 'request'>;
+}): Promise<{
+    name: string;
+    slug: string;
+}>;
+/**
+ * Poll GitHub (as the App, via a JWT) until at least one installation exists,
+ * returning the first installation's id + account login. Throws on timeout.
+ */
+export declare function waitForInstallation(creds: Pick<GithubAppCredentials, 'appId' | 'privateKey'>, opts: {
+    timeoutMs: number;
+    pollMs: number;
+    now?: () => number;
+    appOctokit?: Pick<Octokit, 'request'>;
+}): Promise<{
+    installationId: number;
+    accountLogin: string;
+}>;
+/**
+ * Mint an installation token from the captured private key and confirm the App
+ * can reach repos — proves the key works end-to-end (the same path the agent's
+ * clone uses at runtime).
+ */
+export declare function verifyRepoAccess(creds: Pick<GithubAppCredentials, 'appId' | 'privateKey'>, installationId: number, deps?: {
+    octokit?: Pick<Octokit, 'request'>;
+}): Promise<{
+    repoCount: number;
+}>;
+//# sourceMappingURL=manifest.d.ts.map

package/dist/reporting/execution-tracker.d.ts

@@ -227,7 +227,9 @@ export declare class ExecutionTracker {
         max?: number;
     }, 
     /** Workflow-level wall-clock timeout in ms from the lock file. Sets the run deadline. */
-    workflowTimeoutMs?: number): Promise<void>;
+    workflowTimeoutMs?: number, 
+    /** Run mode for idempotent steps; non-apply labels the run a check-mode preview. */
+    checkMode?: string): Promise<void>;
     /**
      * Add additional jobs to an already-started execution run.
      * Used when build jobs are tracked early and regular jobs are dispatched later.
@@ -250,6 +252,13 @@ export declare class ExecutionTracker {
      * uses, so dispatchEvalJob can swap it for the real eval job id.
      */
     findDynamicEvalSyntheticId(runId: string, evalJobName: string): Promise<string | undefined>;
+    /**
+     * Durably mark the projected `execution_jobs` row so run-recovery sweepers
+     * know this job lives on a remote worker peer and must not be force-failed
+     * while that worker is connected. Called by the owning coordinator right
+     * after a peer ACKs a reroute.
+     */
+    markJobReroutedToPeer(runId: string, jobId: string, peerId: string): Promise<void>;
     /**
      * Run `fn` while holding a per-run lock, serializing the run-mutating methods
      * (`onJobStatus`, `addJobsToRun`) so a status reply cannot interleave with the