@kici-dev/orchestrator 0.1.23 → 0.1.25

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

@@ -9,13 +9,35 @@
  * 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 {
     registrationIndex: RegistrationIndex;
 }
-export declare function handleManualSchedule(registrationId: string, triggeredBy: string | null, deps: ManualScheduleDeps): Promise<{
+export declare function handleManualSchedule(registrationId: string, triggeredBy: string | null, triggeredByAgentLabel: 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/process-webhook.d.ts

@@ -16,11 +16,24 @@
  * Internal helpers are pure phase functions returning typed results; the only
  * top-level export is `processWebhook`, callable from server.ts / app.ts.
  */
+import { z } from 'zod';
 import type { SimulatedEvent } from '@kici-dev/engine';
 import type { WebhookInfo } from '../webhook/handler.js';
 import type { ProviderBundle } from '../provider-registry.js';
 import type { TrustResolution } from '../security/trust-resolver.js';
 import { type ProcessingDeps } from './processor.js';
+/**
+ * Outcome of a single inbound-webhook ingestion. `duplicate` lets a direct-
+ * ingress route return `{ duplicate: true }` to GitHub's Recent Deliveries
+ * panel; `skipped` covers unknown provider / unknown event / no-repo paths;
+ * `processed` means the pipeline matched and dispatched (or recorded a run).
+ */
+export declare const WebhookIngestOutcome: z.ZodEnum<{
+    processed: "processed";
+    skipped: "skipped";
+    duplicate: "duplicate";
+}>;
+export type WebhookIngestOutcome = z.infer<typeof WebhookIngestOutcome>;
 interface TrustOutcome {
     trustResolution: TrustResolution | undefined;
     /** Default 'base' for PR events; trust resolution may override to 'head'. */
@@ -52,6 +65,6 @@ export declare function resolveTrustForPR(args: {
  *   9. Match + dispatch global workflows for OTHER repos
  *  10. Forward Platform trace + record event log
  */
-export declare function processWebhook(info: WebhookInfo, deps: ProcessingDeps): Promise<void>;
+export declare function processWebhook(info: WebhookInfo, deps: ProcessingDeps): Promise<WebhookIngestOutcome>;
 export {};
 //# sourceMappingURL=process-webhook.d.ts.map

package/dist/pipeline/rerun.d.ts

@@ -67,7 +67,7 @@ export interface RerunDeps {
      */
     coldStore: ColdStore | null;
 }
-export declare function handleRerun(originalRunId: string, triggeredBy: string | null, deps: RerunDeps, 
+export declare function handleRerun(originalRunId: string, triggeredBy: string | null, triggeredByAgentLabel: string | null, deps: RerunDeps, 
 /**
  * Phase F — routing key for the original run, forwarded by Platform
  * via the WS `run.rerun.request` payload. Required to address the

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

@@ -92,7 +92,22 @@ interface TestTriggerResult {
     reason?: string;
     /** Dispatched job IDs. */
     jobIds: string[];
+    /**
+     * User-visible warnings on an accepted run — today, one per job whose bound
+     * test-run environment(s) were unavailable (non-test or unconfigured) and
+     * skipped. Printed by the CLI on acceptance.
+     */
+    warnings?: 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/attestation-retrier.d.ts

@@ -0,0 +1,92 @@
+import type { PendingAttestationsRepo, PendingAttestationRow } from './pending-attestations-repo.js';
+/** A minted token, a still-transient deferral, or a terminal rejection. */
+export type RetrierMintResult = {
+    token: string;
+    expiresIn: number;
+    jti: string;
+} | {
+    deferred: true;
+    code: string;
+} | {
+    rejected: true;
+    reason: string;
+};
+export interface AttestationRetrierDeps {
+    repo: PendingAttestationsRepo;
+    /** Mint the deferred token (the OIDC relay with deferred params, Task 5). */
+    requestMint: (args: {
+        orchestratorId: string;
+        runId: string;
+        jobId: string;
+        audience: string;
+        deferred: {
+            statementHash: string;
+            origin: 'deferred' | 'offline-backfill';
+        };
+    }) => Promise<RetrierMintResult>;
+    /** Assemble + upload the bundle to object storage (initMeta included). */
+    uploadBundle: (args: {
+        runId: string;
+        jobId: string;
+        subjectDigest: string;
+        bundle: Record<string, unknown>;
+        storageKey: string;
+    }) => Promise<void>;
+    computeVerdict: (storageKey: string) => Promise<{
+        verifyStatus: string;
+        verifyReason: string | null;
+        verifiedAt: Date | null;
+    }>;
+    recordAttestation: (args: {
+        runId: string;
+        jobId: string;
+        subjectName: string;
+        subjectDigest: string;
+        storageKey: string;
+        mediaType: string;
+        verifyStatus: string;
+        verifyReason: string | null;
+        verifiedAt: Date | null;
+    }) => Promise<void>;
+    /** Replay the run/job rows the Platform missed (offline-backfill only). */
+    backfillRun: (runId: string) => Promise<void>;
+    setMetrics: (count: number, oldestCreatedAt: Date | null, rejected: number) => void;
+    isLeader: () => boolean;
+    orchestratorId: string;
+    intervalMs: number;
+    provenanceStorageKey: (runId: string, jobId: string, subjectDigest: string) => string;
+}
+export declare class AttestationRetrier {
+    private readonly deps;
+    private interval;
+    private running;
+    constructor(deps: AttestationRetrierDeps);
+    /**
+     * Start the periodic timer. Each tick self-gates on `isLeader()`, so it is
+     * safe to start on every instance — only the current Raft leader acts, and
+     * the `attestations` unique index makes fulfilment idempotent regardless.
+     */
+    start(): void;
+    onBecomeLeader(): void;
+    onLoseLeadership(): void;
+    stop(): void;
+    /** On-reconnect trigger (Platform WS re-authenticated). Leader-gated inside tick. */
+    triggerNow(): void;
+    tick(): Promise<void>;
+    /**
+     * Fulfil the targeted pending rows once and report counts. Used by the manual
+     * `kici-admin attestations retry` path (via the orchestrator admin API): the
+     * operator explicitly requested a drain, so this is NOT leader-gated — the
+     * `attestations` unique index keeps a concurrent leader tick idempotent.
+     */
+    runOnce(opts?: {
+        runId?: string;
+        includeRejected?: boolean;
+    }): Promise<{
+        minted: number;
+        stillPending: number;
+        rejected: number;
+    }>;
+    fulfilOne(row: PendingAttestationRow): Promise<'minted' | 'rejected' | 'deferred'>;
+}
+//# sourceMappingURL=attestation-retrier.d.ts.map

package/dist/provenance/backfill-run.d.ts

@@ -0,0 +1,41 @@
+import type { OrchestratorToPlatformMessage } from '@kici-dev/engine';
+/** The local `execution_runs` fields the backfill needs (production reads via Kysely). */
+export interface BackfillRunRow {
+    run_id: string;
+    workflow_name: string;
+    status: string;
+    repo_identifier: string | null;
+    provider: string | null;
+    local_working_tree: boolean | null;
+    sha: string | null;
+    ref: string | null;
+    job_count: number | null;
+    started_at: Date | null;
+    completed_at: Date | null;
+    duration_ms: number | null;
+}
+/** The local `execution_jobs` fields the backfill needs. */
+export interface BackfillJobRow {
+    run_id: string;
+    job_id: string;
+    job_name: string;
+    status: string;
+    started_at: Date | null;
+    completed_at: Date | null;
+    agent_id: string | null;
+    orchestrator_id: string | null;
+}
+export interface BackfillRunDeps {
+    send: (message: OrchestratorToPlatformMessage) => void;
+    loadRun: (runId: string) => Promise<BackfillRunRow | null>;
+    loadJobs: (runId: string) => Promise<BackfillJobRow[]>;
+}
+/**
+ * Send one `execution.status` (terminal) followed by one `job.status.forward`
+ * per job, populating exactly the fields the Platform's `handler.ts` upserts.
+ * Ordered execution.status FIRST so the run row exists before the job rows
+ * reference it. A no-op (throws) when the run is not found locally — the caller
+ * leaves the pending row `deferred` with a clear error.
+ */
+export declare function backfillRunToPlatform(deps: BackfillRunDeps, runId: string): Promise<void>;
+//# sourceMappingURL=backfill-run.d.ts.map

package/dist/provenance/pending-attestations-repo.d.ts

@@ -0,0 +1,64 @@
+import { type Kysely } from 'kysely';
+import type { AttestationOrigin } from '@kici-dev/engine';
+import type { Database, PendingAttestationRow } from '../db/types.js';
+/** The non-`live` AttestationOrigin values a pending row can carry. */
+export type PendingAttestationOrigin = Exclude<AttestationOrigin, 'live'>;
+export interface PendingAttestationInput {
+    id: string;
+    runId: string;
+    jobId: string;
+    subjectName: string;
+    subjectDigest: string;
+    audience: string;
+    dsseEnvelope: unknown;
+    publicKey: unknown;
+    mediaType: string;
+    statementHash: string;
+    originKind: PendingAttestationOrigin;
+}
+export type { PendingAttestationRow } from '../db/types.js';
+/** Typed CRUD over the deferred-attestation outbox (shared orchestrator DB). */
+export declare class PendingAttestationsRepo {
+    private readonly db;
+    constructor(db: Kysely<Database>);
+    /** Insert a pending row; re-deferring the same subject is a no-op. */
+    insert(row: PendingAttestationInput): Promise<void>;
+    /**
+     * List pending rows oldest-first, optionally scoped to a run. Terminally
+     * rejected rows (`rejected_at IS NOT NULL`) are excluded — the retrier never
+     * re-picks a row the Platform definitively cannot mint.
+     */
+    list(opts?: {
+        runId?: string;
+        limit?: number;
+    }): Promise<PendingAttestationRow[]>;
+    /** Bump the attempt counter + record the last error on a still-failing retry. */
+    recordAttempt(id: string, lastError: string | null): Promise<void>;
+    /** Remove a fulfilled pending row. */
+    delete(id: string): Promise<void>;
+    /**
+     * Outbox depth + oldest entry, feeding the metrics gauges. Terminally rejected
+     * rows are excluded so the pending gauge reflects only truly-pending rows.
+     */
+    countAndOldest(): Promise<{
+        count: number;
+        oldestCreatedAt: Date | null;
+    }>;
+    /**
+     * Terminally reject a pending row: the Platform definitively cannot mint it
+     * (run/job absent). Stamps rejected_at, records the reason, and bumps the
+     * attempt counter. The row stays for audit but is skipped by list()/counts.
+     */
+    markRejected(id: string, reason: string): Promise<void>;
+    /** Count terminally-rejected rows (feeds the rejected-attestations gauge). */
+    countRejected(): Promise<number>;
+    /**
+     * Re-arm terminally-rejected rows so the next drain re-attempts them (used
+     * after an operator fixes the Platform-side run/job). Scoped to a run when
+     * runId is given, else clears every rejected row. Returns the count re-armed.
+     */
+    clearRejected(opts?: {
+        runId?: string;
+    }): Promise<number>;
+}
+//# sourceMappingURL=pending-attestations-repo.d.ts.map

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,31 @@
+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.
+ *
+ * Reads the bundle, selects the signing-key set by the identity token's own
+ * `kid` (so a kid-miss triggers the trust root's single refetch — a token
+ * minted with a freshly-rotated key still verifies against a briefly-stale
+ * cached JWKS), then verifies offline.
+ *
+ * Fail-closed: a missing trust root, unfetchable JWKS, missing storage, or an
+ * unreadable bundle all yield `unverifiable` (never silently `verified`). A
+ * signing key that is absent from the published JWKS even after the refetch
+ * yields `unverifiable` (`signing_key_not_published`) — "couldn't verify", not
+ * "proved bad". 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,16 @@ export interface ExecutionContext {
     originalRunId?: string | null;
     /** User identity that triggered this re-run (null/undefined for webhook-triggered). */
     triggeredBy?: string | null;
+    /** Agent provenance label when triggered through an agent credential. */
+    triggeredByAgentLabel?: 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 +124,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 +222,9 @@ export declare class ExecutionTracker {
         waveGated?: boolean;
         waveMaxParallel?: number;
         waveFailFast?: boolean;
+        environments?: string[];
+        skippedEnvironments?: string[];
+        envWarning?: string;
     }>, routingKey?: string, 
     /** Secret context names dispatched with jobs (for context-disable job lookup). */
     dispatchedContexts?: string[], 
@@ -229,11 +246,22 @@ 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>;
-    /**
-     * Add additional jobs to an already-started execution run.
-     * Used when build jobs are tracked early and regular jobs are dispatched later.
-     */
+    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, 
+    /** Agent provenance label when triggered through an agent credential. */
+    triggeredByAgentLabel?: string | null): Promise<void>;
+    /**
+     * Upsert one execution_jobs row per dispatched job (idempotent on
+     * (run_id, job_id) to tolerate a race with an early `onJobStatus`). The
+     * `routing_key` is denormalized (see migration 006) so cold-store archival
+     * partitions by it without joining execution_runs.
+     */
+    private insertTrackedJobRows;
     /**
      * Find the synthetic needs-pending job ID for a given job name in a run.
      * Used by dispatchReadyJob to locate the placeholder entry before replacing it.
@@ -283,6 +311,9 @@ export declare class ExecutionTracker {
         baseJobName?: string;
         variantKind?: string;
         variantLabel?: string;
+        environments?: string[];
+        skippedEnvironments?: string[];
+        envWarning?: string;
     }>, dispatchedContexts?: string[], 
     /** Synthetic job ID to replace (e.g. needs-pending-deploy-{uuid}). */
     replaceSyntheticId?: string): Promise<void>;
@@ -551,6 +582,7 @@ export declare class ExecutionTracker {
         parentRunId?: string | null;
         originalRunId?: string | null;
         triggeredBy?: string | null;
+        triggeredByAgentLabel?: string | null;
         failureReason?: string;
         jobCount: number;
         startedAt: number;

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

@@ -0,0 +1,165 @@
+/**
+ * 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;
+    skipped_environments: unknown;
+    env_warning: string | null;
+    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: "job" | "run";
+        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;
+    skippedEnvironments: string[] | null;
+    envWarning: 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