@kici-dev/orchestrator 0.1.22 → 0.1.24

package/dist/orchestrator-core.d.ts

@@ -27,6 +27,7 @@ import { ExecutionJobStatus, type LabelMatcher, type PeerHeartbeat, type PeerLog
 import { ScalerManager } from './scaler/index.js';
 import type { ScalerConfig } from './scaler/index.js';
 import type { CacheStorage } from './storage/index.js';
+import { type ProvenanceTrustRoot } from './provenance/trust-root.js';
 import { SourceCache, BuildCoordinator, DepCache, UserCache, DispatchCacheRefTracker, PendingBuildTracker, PendingInitTracker, PendingDynamicTracker } from './cache/index.js';
 import { CheckRunReporter } from './reporting/check-run-reporter.js';
 import { StepLogBuffer } from './reporting/step-log-buffer.js';
@@ -70,6 +71,12 @@ export interface OrchestratorSubsystems {
     scalerManager: ScalerManager | null;
     scalerConfig: ScalerConfig | null;
     cacheStorage: CacheStorage | undefined;
+    /**
+     * Provenance trust root used to verify build-provenance bundles at ingest.
+     * The mode-specific hook (server.ts) wires the live issuer onto it from the
+     * Platform `auth.success` message via `onProvenanceIssuer`.
+     */
+    provenanceTrustRoot: ProvenanceTrustRoot;
     sourceCache: SourceCache | undefined;
     depCache: DepCache | undefined;
     userCache: UserCache | undefined;
@@ -315,6 +322,7 @@ export declare function mergeUpstreamOutputs(db: Kysely<Database>, runId: string
     upstreamJobOutputs: Record<string, Record<string, unknown>> | undefined;
     upstreamJobStatuses: Record<string, ExecutionJobStatus> | undefined;
 }>;
+export declare function buildInternalJobConfigForWorkflow(workflow: any, job: any): Record<string, unknown>;
 export declare function bootstrapOrchestrator(config: AppConfig, hooks: OrchestratorHooks, options?: {
     otelSdk?: {
         shutdown(): Promise<void>;

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

@@ -14,10 +14,12 @@
  * results through the pipeline.
  */
 import { ExecutionJobStatus, InitFailureCategory, CacheRefScope } from '@kici-dev/engine';
-import type { LabelMatcher, LockWorkflow, LockJob, HostTargetSelector, SimulatedEvent, WorkflowDecision, MaterializedJob, ResolvedHostAgent } from '@kici-dev/engine';
+import type { LabelMatcher, LockWorkflow, LockJob, HostTargetSelector, SimulatedEvent, WorkflowDecision, MaterializedJob, ResolvedHostAgent, HostFacts } 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 { Dispatcher } from '../agent/dispatcher.js';
+import type { QueuedJobInput } from '../queue/job-queue.js';
 import type { TrustResolution } from '../security/trust-resolver.js';
 import { type ProcessingDeps } from './processor.js';
 /**
@@ -69,6 +71,8 @@ export interface WorkflowDispatchContext {
     runId: string;
     trustResolution: TrustResolution | undefined;
     lockFileSource: string | undefined;
+    /** True when this run executes an uploaded local working tree (CLI remote run). */
+    localWorkingTree: boolean;
     /** True only when invoked from the cross-source dispatch shell. */
     crossSource: boolean;
     /** Composite dedup key `${info.deliveryId}:${reg.id}` (cross-source only). */
@@ -120,6 +124,12 @@ export interface WorkflowDispatchContext {
      * runsOnAll ∩ target. Narrow-only. Undefined for webhook runs (no narrowing).
      */
     target?: HostTargetSelector;
+    /**
+     * Resolved (coerced + defaulted + validated) workflow-dispatch inputs from
+     * `kici run --input`. Carried onto every dispatched job's request so the agent
+     * exposes them as `ctx.dispatchInputs`. Undefined for webhook runs.
+     */
+    dispatchInputs?: Record<string, unknown>;
 }
 export interface DispatchMatchedWorkflowResult {
     /** Number of jobs successfully dispatched (non-rejected). */
@@ -144,6 +154,30 @@ export interface DispatchMatchedWorkflowOptions {
      */
     reuseRunId?: string;
 }
+type DispatchFn = (input: QueuedJobInput) => ReturnType<Dispatcher['dispatch']>;
+interface DispatchSetup {
+    /** Wrapped dispatcher that injects ctx.extraJobConfig into every dispatch. */
+    dispatcher: {
+        dispatch: DispatchFn;
+    };
+    /** WebhookInfo overlaid with effective routing key + provider. */
+    info: WebhookInfo;
+    /** Composite delivery id on cross-source, otherwise info.deliveryId. */
+    effectiveDeliveryId: string;
+    workflowConcurrency: {
+        cancelInProgress?: boolean;
+        max?: number;
+    } | undefined;
+    workflowTimeoutMs: number | undefined;
+    /**
+     * Run mode for idempotent steps (`apply` | `check` | `check-fail-on-drift`),
+     * carried on `ctx.extraJobConfig` by the test-trigger / `kici run --check`
+     * path. Persisted onto the `execution_runs` row so `computeRunStatus` can
+     * fail a `check-fail-on-drift` run that detected drift. Undefined for the
+     * default apply-mode webhook path.
+     */
+    checkMode: string | undefined;
+}
 interface RejectedJob {
     jobId: string;
     jobName: string;
@@ -157,6 +191,20 @@ interface RejectedJob {
      */
     terminalStatus?: ExecutionJobStatus;
 }
+/**
+ * Build the QueuedJobInput for a synthetic `__bringup__` job: the orchestrator
+ * dispatches one per declared-but-un-agented `includeUninitialized` child to an
+ * agent holding `kici:capability:ssh-transport`, which runs the agent-side
+ * `ensureInitRunner(targetAgentId)` over SSH. The init-runner then connects
+ * under `targetAgentId`, and the child's pinned-hold (already queued with that
+ * pin) drains its bootstrap steps onto it. The bring-up job clones nothing and
+ * runs no sandbox (`bringupOnly`).
+ */
+export declare function buildBringupJobInput(args: {
+    ctx: WorkflowDispatchContext;
+    setup: DispatchSetup;
+    targetAgentId: string;
+}): QueuedJobInput;
 /**
  * Phase B orchestrator: probe caches, dispatch the build job (if needed),
  * and surface enough state for downstream phases to skip / continue
@@ -227,8 +275,9 @@ export interface WavePlan {
  * 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 `>=
+ * child, children are ordered deterministically by `fanoutIndex` (the
+ * agentId / variant-label rank assigned at materialization; falling back to
+ * `expandedName` for children with no index) 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
@@ -241,6 +290,14 @@ export declare function materializeStaticJobsSafe(staticJobs: readonly LockJob[]
     expansionMap: Map<string, readonly string[]>;
     matrixFailures: RejectedJob[];
 }>;
+/**
+ * Build the per-host secret-resolution context for a materialized child. A
+ * `runsOnAll` host child carries its identity on `mat.agent` (preferred) or
+ * `mat.pinnedAgentId`/`mat.host`; a non-host child (matrix/static) has none, so
+ * resolution stays fleet-wide (`'**'`-only). Returns `undefined` when there are
+ * no host facts to scope by.
+ */
+export declare function hostCtxFromMat(mat: MaterializedJob): HostFacts | undefined;
 export interface GeneratedJobConfig {
     /**
      * The generated lock job with its `name` and `needs` rewritten to expanded

package/dist/pipeline/flatten-lock-steps.d.ts

@@ -0,0 +1,11 @@
+import { type LockStep, type LockStepEntry } from '@kici-dev/engine';
+/**
+ * Flatten a lock job's `steps` into the flat sequential list the orchestrator
+ * iterates by `stepIndex`. A `parallel` group's children are inlined in array
+ * order and the group wrapper is dropped (it consumes no flat index). This keeps
+ * the orchestrator's enumeration aligned with the agent's `extractAndNormalizeSteps`
+ * — the flat-stepIndex invariant: `flattenLockSteps(job.steps)[i]` is the step at
+ * agent `stepIndex i`.
+ */
+export declare function flattenLockSteps(steps: readonly LockStepEntry[]): readonly LockStep[];
+//# sourceMappingURL=flatten-lock-steps.d.ts.map

package/dist/pipeline/inline-eval.d.ts

@@ -36,7 +36,8 @@ export declare function evaluateInlineRecord(expression: string, event: object):
  * failures are immediate dispatch failures (no init-job fallback).
  */
 export declare function evaluateInlineFields(lockJob: LockJob, event: object): {
-    inlineEnvironmentName: string | undefined;
+    /** Resolved name per `environments` element, aligned by index; undefined for static or impure-dynamic elements. */
+    inlineEnvironmentNames: Array<string | undefined>;
     inlineEnv: Record<string, string> | undefined;
     inlineConcurrencyGroup: string | undefined;
 };

package/dist/pipeline/job-environments.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Multi-environment resolution helpers for the dispatch path.
+ *
+ * A job binds an ordered list of environments (`LockJob.environments`). This
+ * module resolves that list into concrete environment names (static values
+ * verbatim, pure-inline dynamic elements evaluated against the event) and folds
+ * the per-environment secrets/variables last-wins. It keeps the heavy fold logic
+ * out of `dispatchMatchedWorkflow`, which must stay under the function-length cap.
+ */
+import { type Environment, type HostFacts, type LockJob } from '@kici-dev/engine';
+import type { SecretResolverApi } from '../secrets/secret-resolver.js';
+import type { VariableStore } from '../environments/variable-store.js';
+/**
+ * Placeholder written into the persisted bound-env list for an impure dynamic
+ * element the orchestrator cannot resolve at dispatch. The agent's init eval
+ * later overwrites the list with the resolved name.
+ */
+export declare const DYNAMIC_ENV_PLACEHOLDER = "(dynamic)";
+/** Ordered resolved environment names plus whether any element still needs agent init. */
+export interface ResolvedJobEnvironments {
+    /** Resolved static + pure-inline names, in order. */
+    names: string[];
+    /** True when an impure dynamic element must be resolved by an agent init job. */
+    needsInit: boolean;
+}
+/**
+ * Resolve the ordered bound-environment names from a lock job. Static elements
+ * use their value verbatim; pure-inline dynamic elements use the matching
+ * pre-evaluated inline name (aligned by index); an impure dynamic element cannot
+ * be resolved here and flags `needsInit`.
+ */
+export declare function resolveJobEnvironmentNames(lockJob: LockJob, inlineNames: ReadonlyArray<string | undefined>): ResolvedJobEnvironments;
+/**
+ * Build the ordered bound-environment display list for persistence at dispatch.
+ * Unlike {@link resolveJobEnvironmentNames}, this never drops an unresolved
+ * element: a static element uses its value, a pure-inline element uses its
+ * resolved name when known, and any element the orchestrator cannot resolve at
+ * dispatch (impure dynamic, or an unresolved pure-inline) becomes the
+ * `(dynamic)` placeholder — so the persisted column reflects every declared
+ * slot in order. Returns an empty array when the job binds no environment.
+ */
+export declare function buildJobEnvironmentDisplayNames(lockJob: LockJob, inlineNames: ReadonlyArray<string | undefined>): string[];
+/** Merged secrets/variables across an ordered list of resolved environments. */
+export interface MultiEnvMergedData {
+    environmentVars?: Record<string, string>;
+    jobSecrets?: Record<string, string>;
+    jobNamespacedSecrets?: Record<string, Record<string, string>>;
+}
+/**
+ * Resolve and fold variables + secrets across the ordered list of matched
+ * environments, last-wins. Each environment is resolved with the existing
+ * single-env logic (longest-scope-path-wins preserved within each environment),
+ * then folded in array order so a later environment overrides an earlier key.
+ * Secrets are also returned namespaced per environment so qualified
+ * `<env>:<secret>` references still resolve. `entries` carries the matched
+ * `Environment` for each name (in order); variables resolve by environment id.
+ */
+export declare function resolveMultiEnvMergedData(args: {
+    deps: {
+        variableStore?: VariableStore;
+        secretResolver?: SecretResolverApi;
+    };
+    orgId: string;
+    entries: ReadonlyArray<{
+        name: string;
+        env: Environment;
+    }>;
+    hostCtx?: HostFacts;
+    routingKey?: string;
+}): Promise<MultiEnvMergedData>;
+//# sourceMappingURL=job-environments.d.ts.map

package/dist/pipeline/manual-schedule.d.ts

@@ -9,6 +9,7 @@
  * eventRouter fire-and-forget. The manual path needs request/response
  * correlation to return the newRunId to the dashboard.
  */
+import type { LockWorkflow, MaterializedJob } from '@kici-dev/engine';
 import type { RerunDeps } from './rerun.js';
 import type { RegistrationIndex } from '../registration/registration-index.js';
 interface ManualScheduleDeps extends RerunDeps {
@@ -17,5 +18,26 @@ interface ManualScheduleDeps extends RerunDeps {
 export declare function handleManualSchedule(registrationId: string, triggeredBy: string | null, deps: ManualScheduleDeps): Promise<{
     newRunId: string;
 }>;
+export declare function buildManualJobConfig(workflow: LockWorkflow, mat: MaterializedJob): {
+    resolvedHashFiles?: string[] | undefined;
+    contentHash?: string | undefined;
+    dispatchInputs?: Record<string, unknown> | undefined;
+    steps: readonly import("@kici-dev/engine").LockStepEntry[];
+    needs: readonly (string | {
+        name: string;
+        runOn: ("success" | "pending" | "failed" | "recovering" | "running" | "queued" | "skipped" | "cancelled" | "cancelling" | "timed_out_stale" | "drift_dropped")[];
+    } | {
+        group: string;
+        runOn: ("success" | "pending" | "failed" | "recovering" | "running" | "queued" | "skipped" | "cancelled" | "cancelling" | "timed_out_stale" | "drift_dropped")[];
+    })[];
+    rules: readonly import("@kici-dev/engine").LockRule[] | undefined;
+    name: string;
+    baseJobName: string;
+    matrixValues?: import("@kici-dev/engine").MatrixValues;
+    fanoutIndex?: number;
+    fanoutTotal?: number;
+    source: import("@kici-dev/engine").LockSource | undefined;
+    workflowName: string;
+};
 export {};
 //# sourceMappingURL=manual-schedule.d.ts.map

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

@@ -73,6 +73,12 @@ export interface TestTriggerInput {
      * context, where it post-filters each runsOnAll job's matched roster.
      */
     target?: HostTargetSelector;
+    /**
+     * Raw operator-supplied `kici run --input KEY=VALUE` pairs (not coerced /
+     * defaulted). Validated + coerced + defaulted here against the matched
+     * workflow's lock dispatch descriptor before dispatch.
+     */
+    dispatchInputs?: Record<string, string>;
 }
 /**
  * Result of processing a test trigger.
@@ -87,6 +93,15 @@ interface TestTriggerResult {
     /** Dispatched job IDs. */
     jobIds: string[];
 }
+/**
+ * Repo identity for an inline-lock (local working tree) run. Derived from the
+ * event payload the CLI stamps -- NOT the relay routing key, which is the
+ * Platform-internal `remote:<orgId>` anchor and is meaningless as a repo.
+ */
+export declare function repoIdentityFromInlineInput(input: TestTriggerInput): {
+    repoIdentifier: string;
+    provider: string;
+};
 /**
  * Process a test trigger through the shared dispatch core.
  *

package/dist/provenance/trust-root.d.ts

@@ -0,0 +1,24 @@
+import type { JSONWebKeySet } from 'jose';
+/**
+ * Derive the JWKS URI for a provenance OIDC issuer. Identical to the Platform's
+ * own derivation (`packages/platform/src/dashboard/routes/runs.ts`) so a bundle
+ * verified client-side and at ingest resolve the same key set.
+ */
+export declare function deriveJwksUri(issuer: string): string;
+/**
+ * The orchestrator's view of the provenance trust root. The issuer arrives over
+ * the `auth.success` connect message for the live process, or from config/env
+ * (`KICI_PROVENANCE_ISSUER`) for the CLI backfill which has no live handshake.
+ * The JWKS is fetched lazily and cached with a single refetch-on-`kid`-miss.
+ */
+export interface ProvenanceTrustRoot {
+    getIssuer(): string | null;
+    getJwks(kid?: string): Promise<JSONWebKeySet | null>;
+    setIssuer(issuer: string | null): void;
+}
+export declare function createProvenanceTrustRoot(opts?: {
+    issuer?: string | null;
+    fetchImpl?: typeof fetch;
+    ttlMs?: number;
+}): ProvenanceTrustRoot;
+//# sourceMappingURL=trust-root.d.ts.map

package/dist/provenance/verify-at-ingest.d.ts

@@ -0,0 +1,24 @@
+import { type AttestationVerifyStatus } from '@kici-dev/engine';
+import type { CacheStorage } from '../storage/types.js';
+import type { ProvenanceTrustRoot } from './trust-root.js';
+export interface AttestationVerdict {
+    verifyStatus: AttestationVerifyStatus;
+    verifyReason: string | null;
+    verifiedAt: Date | null;
+}
+/**
+ * Compute the verification verdict for a stored provenance bundle at ingest.
+ *
+ * Fail-closed: a missing trust root, unfetchable JWKS, missing storage, or an
+ * unreadable bundle all yield `unverifiable` (never silently `verified`). A
+ * bundle that verifies false yields `failed` with the first failure code. Any
+ * thrown error is caught and recorded as `unverifiable` — verification never
+ * fails the upload.
+ */
+export declare function computeAttestationVerdict(opts: {
+    trustRoot: ProvenanceTrustRoot | undefined;
+    storage: CacheStorage | undefined;
+    storageKey: string;
+    logWarn?: (reason: string) => void;
+}): Promise<AttestationVerdict>;
+//# sourceMappingURL=verify-at-ingest.d.ts.map

package/dist/reporting/agent-failure-category.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Derive a coarse, trusted run-failure classification from existing signals.
+ *
+ * Pure derivation — no heuristics, no flaky/regression detection (that's a
+ * deferred phase). KiCI computes this from data it already records, so the
+ * resulting category is a trusted field on the agent run-result.
+ */
+import { AgentFailureCategory } from '@kici-dev/engine';
+export interface FailureSignals {
+    /** `execution_runs.status`. */
+    runStatus: string;
+    /** A run- or job-scoped init failure was recorded. */
+    hasInitFailure: boolean;
+    /** The init-failure category (`InitFailureCategory`), if any. */
+    initFailureCategory: string | null;
+    /** Any job ended in `timed_out_stale` (or a workflow/job timeout fired). */
+    timedOut: boolean;
+    /** Any step recorded a non-zero exit code. */
+    anyStepNonZeroExit: boolean;
+}
+/**
+ * Returns the failure category, or null for a non-failed run (success, or still
+ * in flight). Precedence: init failure → timeout → cancelled → step exit →
+ * unknown.
+ */
+export declare function deriveFailureCategory(s: FailureSignals): AgentFailureCategory | null;
+//# sourceMappingURL=agent-failure-category.d.ts.map

package/dist/reporting/agent-run-result-mapper.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Map the canonical run detail into the provenance-tagged `AgentRunResult`.
+ *
+ * Trusted (plain): ids, enum statuses, exit codes, durations, timestamps,
+ * hashes, the derived failure category. Untrusted (enveloped): every name, ref,
+ * error string, contributor, job output value — anything sourced from the user's
+ * repo / contributor / process output. Secret output *values* are never emitted;
+ * only their key names appear.
+ */
+import { type AgentRunResult } from '@kici-dev/engine';
+import type { CanonicalRunDetail } from './run-aggregator.js';
+export declare function mapToAgentRunResult(d: CanonicalRunDetail): AgentRunResult;
+//# sourceMappingURL=agent-run-result-mapper.d.ts.map

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

@@ -23,6 +23,8 @@ export interface ExecutionContext {
     provider: string;
     repoIdentifier: string;
     sha: string;
+    /** True when the run executed an uploaded local working tree (`kici run remote`). */
+    localWorkingTree?: boolean;
     installationId?: number;
     requestId?: string;
     routingKey?: string;
@@ -38,6 +40,14 @@ export interface ExecutionContext {
     originalRunId?: string | null;
     /** User identity that triggered this re-run (null/undefined for webhook-triggered). */
     triggeredBy?: string | null;
+    /**
+     * Provider login of the person who triggered the run (pusher / PR author).
+     * Captured for all event types; forwarded to the Platform run projection and
+     * used to resolve actor-scope notifications.
+     */
+    triggerActorUsername?: string | null;
+    /** Immutable provider user id of the triggering actor (preferred for resolution). */
+    triggerActorUserId?: string | null;
     /** Workflow-level concurrency config from the lock file. */
     concurrency?: {
         cancelInProgress?: boolean;
@@ -112,7 +122,9 @@ export interface ExecutionTrackerDeps {
      * Structured init-failure signal. Set for synthetic rejected-* / init-failed-*
      * jobs that never started. Persisted in execution_jobs.init_failure.
      */
-    initFailure?: InitFailure) => void;
+    initFailure?: InitFailure, 
+    /** Ordered bound deployment-environment names for this job (multi-env jobs). */
+    environments?: string[]) => void;
     /**
      * Optional callback to emit run.event messages to Platform.
      * Fires at orchestrator lifecycle points (dispatch, agent assignment, job start/complete).
@@ -208,6 +220,7 @@ export declare class ExecutionTracker {
         waveGated?: boolean;
         waveMaxParallel?: number;
         waveFailFast?: boolean;
+        environments?: string[];
     }>, routingKey?: string, 
     /** Secret context names dispatched with jobs (for context-disable job lookup). */
     dispatchedContexts?: string[], 
@@ -229,7 +242,13 @@ export declare class ExecutionTracker {
     /** Workflow-level wall-clock timeout in ms from the lock file. Sets the run deadline. */
     workflowTimeoutMs?: number, 
     /** Run mode for idempotent steps; non-apply labels the run a check-mode preview. */
-    checkMode?: string): Promise<void>;
+    checkMode?: string, 
+    /** True when the run executes an uploaded local working tree (`kici run remote`). */
+    localWorkingTree?: boolean, 
+    /** Provider login of the triggering actor (pusher / PR author). */
+    triggerActorUsername?: string | null, 
+    /** Immutable provider user id of the triggering actor. */
+    triggerActorUserId?: string | null): Promise<void>;
     /**
      * Add additional jobs to an already-started execution run.
      * Used when build jobs are tracked early and regular jobs are dispatched later.
@@ -283,6 +302,7 @@ export declare class ExecutionTracker {
         baseJobName?: string;
         variantKind?: string;
         variantLabel?: string;
+        environments?: string[];
     }>, dispatchedContexts?: string[], 
     /** Synthetic job ID to replace (e.g. needs-pending-deploy-{uuid}). */
     replaceSyntheticId?: string): Promise<void>;

package/dist/reporting/log-writer.d.ts

@@ -21,7 +21,26 @@ export declare class LogWriter {
     private readonly logStorage;
     private readonly observerRegistry?;
     private readonly isTestRun?;
+    /**
+     * In-flight `logStorage.append` promises, keyed by runId. `appendChunk` is
+     * called fire-and-forget from the agent WS handler (it does not await the
+     * storage write), so a run can flip to a terminal status while the final
+     * log chunk's append is still pending. `drain(runId)` lets a reader (the
+     * test-run logs cursor endpoint) wait for those pending writes before it
+     * reports the stream as fully drained — without this, the `done` flag can
+     * be returned `true` while the last user-visible log line is not yet on
+     * disk, dropping it from a blocking `kici run remote` follow.
+     */
+    private readonly pendingAppends;
     constructor(deps: LogWriterDeps);
+    /**
+     * Await every in-flight log append for `runId` that was registered before
+     * this call. Settles even if an append rejected (errors are already logged
+     * by `appendChunk`); the point is ordering, not error propagation. New
+     * appends started after this call are not waited on — a terminal run emits
+     * no further chunks, so the snapshot taken at call time is complete.
+     */
+    drain(runId: string): Promise<void>;
     /**
      * Append log lines from an agent to storage in JSONL format.
      *

package/dist/reporting/run-aggregator.d.ts

@@ -0,0 +1,161 @@
+/**
+ * Shared run-detail aggregator.
+ *
+ * One source of truth for "DB rows → canonical nested run detail (jobs with
+ * nested steps + needs + outputs)". The dashboard handler and the agent-facing
+ * structured run-result route both build on the same `buildRunDetailJobs` /
+ * `mapRunDetailStep` mapping, so the row→jobs shape never diverges between the
+ * two read surfaces.
+ *
+ * `aggregateRunDetail` is the warm-path convenience used by the agent route: it
+ * runs the run-header + per-run batch queries and returns the canonical detail.
+ * (Cold-store fallback stays a dashboard-handler concern — the agent read path
+ * is warm-only in v1.)
+ */
+import type { Kysely } from 'kysely';
+import type { ExecutionJobStatus, InitFailure } from '@kici-dev/engine';
+import type { Database } from '../db/types.js';
+/** A run-detail step row as queried from execution_steps (warm + cold paths). */
+export interface RunDetailStepRow {
+    step_index: number;
+    step_name: string;
+    status: string;
+    started_at: Date | null;
+    completed_at: Date | null;
+    duration_ms: number | null;
+    exit_code: number | null;
+    error_message: string | null;
+    step_type: string;
+    secrets_accessed: string | null;
+    check_outcome: string | null;
+    drift_summary: string | null;
+    concurrency_kind: string | null;
+    group_id: string | null;
+}
+/** Map a step row to the dashboard run-detail step shape (epoch-ms timestamps). */
+export declare function mapRunDetailStep(step: RunDetailStepRow): {
+    groupId?: string | undefined;
+    concurrencyKind?: string | undefined;
+    driftSummary?: string | undefined;
+    checkOutcome?: string | undefined;
+    secretsAccessed: string | null;
+    stepType?: string | undefined;
+    stepIndex: number;
+    stepName: string;
+    status: string;
+    startedAt: number | null;
+    completedAt: number | null;
+    durationMs: number | null;
+    exitCode: number | null;
+    errorMessage: string | null;
+};
+/** A run-detail job row as queried from execution_jobs (warm + cold paths). */
+export interface RunDetailJobRow {
+    job_id: string;
+    job_name: string;
+    status: string;
+    matrix_values: unknown;
+    base_job_name: string | null;
+    variant_kind: string | null;
+    variant_label: string | null;
+    started_at: Date | null;
+    completed_at: Date | null;
+    duration_ms: number | null;
+    agent_id: string | null;
+    error_message: string | null;
+    runs_on_labels: unknown;
+    environments: unknown;
+    outputs: unknown;
+    init_failure: unknown;
+}
+/** Lookups threaded into {@link buildRunDetailJobs} from the per-run batch queries. */
+export interface RunDetailJobLookups {
+    stepsByJob: Map<string, RunDetailStepRow[]>;
+    secretKeysByJob: Map<string, string[]>;
+    needsByJob: Map<string, Array<{
+        upstreamName: string;
+        runOn: ExecutionJobStatus[];
+    }>>;
+}
+/** Map queried job + step rows into the dashboard run-detail job DTO shape. */
+export declare function buildRunDetailJobs(jobs: RunDetailJobRow[], lookups: RunDetailJobLookups): {
+    needs: {
+        upstreamName: string;
+        runOn: ExecutionJobStatus[];
+    }[] | null;
+    steps: {
+        groupId?: string | undefined;
+        concurrencyKind?: string | undefined;
+        driftSummary?: string | undefined;
+        checkOutcome?: string | undefined;
+        secretsAccessed: string | null;
+        stepType?: string | undefined;
+        stepIndex: number;
+        stepName: string;
+        status: string;
+        startedAt: number | null;
+        completedAt: number | null;
+        durationMs: number | null;
+        exitCode: number | null;
+        errorMessage: string | null;
+    }[];
+    initFailure?: {
+        scope: "run" | "job";
+        category: "secret_resolution" | "install_secrets" | "lock_resolution" | "build_coordination" | "environment_rules" | "dynamic_eval" | "no_agent" | "matrix_expansion";
+        message: string;
+        jobName?: string | undefined;
+    } | undefined;
+    jobId: string;
+    jobName: string;
+    status: string;
+    matrixValues: Record<string, unknown> | null;
+    baseJobName: string | null;
+    variantKind: string | null;
+    variantLabel: string | null;
+    startedAt: number | null;
+    completedAt: number | null;
+    durationMs: number | null;
+    agentId: string | null;
+    orchestratorId: null;
+    errorMessage: string | null;
+    runsOnLabels: string[] | null;
+    environments: string[] | null;
+    outputs: any;
+    secretOutputKeys: string[] | null;
+}[];
+/** A dashboard-shaped run-detail job (epoch-ms timestamps). */
+export type CanonicalRunDetailJob = ReturnType<typeof buildRunDetailJobs>[number];
+/**
+ * Canonical run detail: the run header (raw `Date` timestamps) plus the
+ * dashboard-shaped nested jobs. The agent mapper formats timestamps to ISO and
+ * wraps untrusted fields; the dashboard handler consumes `buildRunDetailJobs`
+ * directly.
+ */
+export interface CanonicalRunDetail {
+    runId: string;
+    workflowName: string;
+    status: string;
+    provider: string;
+    repoIdentifier: string;
+    ref: string;
+    sha: string;
+    /** Best-effort base commit from provider context; null when unavailable. */
+    baseSha: string | null;
+    startedAt: Date | null;
+    completedAt: Date | null;
+    durationMs: number | null;
+    trustTier: string | null;
+    contributorUsername: string | null;
+    triggeredBy: string | null;
+    failureReason: string | null;
+    /** Run-scoped init failure (the run never executed a step). */
+    initFailure: InitFailure | null;
+    routingKey: string | null;
+    jobs: CanonicalRunDetailJob[];
+}
+/**
+ * Aggregate a run into the canonical nested detail (warm path). Returns null
+ * when the run row is absent in PostgreSQL.
+ */
+export declare function aggregateRunDetail(db: Kysely<Database>, runId: string): Promise<CanonicalRunDetail | null>;
+//# sourceMappingURL=run-aggregator.d.ts.map