@kici-dev/orchestrator 0.5.0 → 0.6.0

package/dist/reporting/check-run-reporter.d.ts

@@ -30,7 +30,7 @@ import type { ProviderRegistry } from '../provider-registry.js';
 import type { StepLogBuffer } from './step-log-buffer.js';
 import { type SourceLocationData } from './check-run-summary.js';
 import type { CheckRunTrackingStore } from './check-run-tracking-store.js';
-import { type TerminalJobStatus } from '@kici-dev/engine';
+import { CheckRunConclusion, type TerminalJobStatus } from '@kici-dev/engine';
 /**
  * Dependencies for the CheckRunReporter.
  */
@@ -172,6 +172,15 @@ interface UpdateJobStatusOptions {
     runIdForLogs?: string;
     /** Job ID for StepLogBuffer lookup. */
     jobId?: string;
+    /**
+     * The run's resolved trust tier and lock-file branch. When the tier is
+     * anything other than `trusted`, the completion summary leads with the
+     * reduced-privilege note so a contributor reading a failed job on a fork pull
+     * request can see which parts of the build environment the run did not have.
+     * Both absent for a run whose trust never resolved.
+     */
+    trustTier?: string;
+    lockFileSource?: string;
 }
 /**
  * Options for updateWorkflowStatus.
@@ -193,6 +202,43 @@ interface UpdateWorkflowStatusOptions {
     requestId?: string;
     /** Explicit runId for trace context (falls back to AsyncLocalStorage context). */
     runId?: string;
+    /**
+     * The run's resolved trust tier and lock-file branch, same contract as
+     * {@link UpdateJobStatusOptions}. The roll-up check carries the note too: a
+     * contributor who reads only `kici/<workflow>` — the one branch protection
+     * usually requires — would otherwise see a run fail with no explanation.
+     */
+    trustTier?: string;
+    lockFileSource?: string;
+}
+/**
+ * Options for completeUndispatchedCheckRuns.
+ */
+export interface CompleteUndispatchedCheckRunsOptions {
+    provider: string;
+    owner: string;
+    repo: string;
+    sha: string;
+    workflowName: string;
+    /** See {@link SetPendingOptions.workflowRepoIdentifier}. */
+    workflowRepoIdentifier?: string;
+    /**
+     * The job names `setPending` / `setPendingAwait` created a check run for.
+     * Pass the same list that call used, or the names will not match the check
+     * runs on the commit.
+     */
+    jobNames: string[];
+    installationId?: number;
+    /** Routing key for per-app credential lookup (e.g., "github:12345"). */
+    routingKey?: string;
+    /** Explicit requestId for trace context (falls back to AsyncLocalStorage context). */
+    requestId?: string;
+    /** Explicit runId for trace context (falls back to AsyncLocalStorage context). */
+    runId?: string;
+    /** The conclusion to complete each check run with. */
+    conclusion: CheckRunConclusion;
+    /** The check-run output body. The title stays the standard `KiCI: <label>` form. */
+    summary: string;
 }
 /**
  * Options for updateStepProgress.
@@ -276,7 +322,26 @@ export declare class CheckRunReporter {
      * still find every key for a runId at cleanup time.
      */
     private readonly runIdToKeys;
+    /**
+     * Per-key serialization of GitHub check-run PATCHes. Two updates for one
+     * check run must never be in flight at GitHub simultaneously: the terminal
+     * `completed` write and an earlier `in_progress` write race last-write-wins,
+     * and if the `in_progress` PATCH lands second it reopens the check run to the
+     * permanently-unresolved `{ status: in_progress, conclusion: <terminal> }`
+     * state. The `terminalSent` re-check inside `updateCheckRun` cannot help once
+     * an `in_progress` PATCH has passed it and is awaiting the network — it is a
+     * check-then-await. Chaining every PATCH for a key through this map makes the
+     * re-check and the PATCH atomic relative to the completion write.
+     */
+    private readonly updateLocks;
     constructor(deps: CheckRunReporterDeps);
+    /**
+     * Run `fn` after every previously-queued check-run PATCH for `key` has
+     * settled, so all updates to one check run execute strictly in order. The
+     * chain swallows prior errors (each is surfaced to its own caller) so one
+     * failed PATCH does not wedge the key.
+     */
+    private runUpdateExclusive;
     /**
      * Update the provider registry used for per-routing-key credential lookup.
      * Called after config reload when the provider registry is rebuilt.
@@ -320,6 +385,33 @@ export declare class CheckRunReporter {
      * Fire-and-forget: errors are logged but don't block the pipeline.
      */
     updateWorkflowStatus(opts: UpdateWorkflowStatusOptions): void;
+    /**
+     * Complete the queued check runs of a workflow that never dispatched a job.
+     *
+     * `setPendingAwait` creates `kici/<workflow>` and one
+     * `kici/<workflow>/job/<name>` per static job before the pipeline knows
+     * whether the workflow will run. When the workflow then ends without
+     * dispatching one — a hold rejected or expired, or any pre-dispatch init
+     * failure — none of these names ever reaches a job or run record, so
+     * `updateJobStatus` and `updateWorkflowStatus` are never called for them, and
+     * `doCleanupStaleCheckRuns` skips them because that sweep only updates check
+     * runs whose status is `in_progress`. They stay `queued` on the commit, which
+     * on a pull request reads as a check that never finishes and blocks branch
+     * protection.
+     *
+     * Completes only the check runs this reporter can resolve an id for (L1 cache
+     * or the `check_run_tracking` row), and skips a key already latched terminal.
+     *
+     * The build check `kici/<workflow>/setup` is deliberately not in the set,
+     * because that latch does not reliably cover it. `setBuildComplete` stamps
+     * `terminal_sent_at` on the row but adds nothing to the in-process
+     * `terminalSent` set, and `resolveCheckRunId` returns on an L1 hit without
+     * reading the row — so a build check this process completed a moment ago
+     * resolves with no latch, and completing it again would overwrite a real
+     * build conclusion. An unreadable row is the harmless direction: it yields
+     * no id and the name is skipped.
+     */
+    completeUndispatchedCheckRuns(opts: CompleteUndispatchedCheckRunsOptions): Promise<void>;
     /**
      * Clean up stale check runs left by a dead orchestrator.
      *
@@ -519,6 +611,7 @@ export declare class CheckRunReporter {
      * Supports both 'completed' and 'in_progress' statuses.
      */
     private updateCheckRun;
+    private updateCheckRunLocked;
 }
 /**
  * Build a meaningful failure description from agent job status data.

package/dist/reporting/check-run-summary.d.ts

@@ -58,6 +58,17 @@ interface BuildCheckRunSummaryOptions {
     };
     /** Total job duration in milliseconds. */
     jobDurationMs?: number;
+    /**
+     * Bytes a caller will add around the returned summary — the reduced-privilege
+     * note it prepends, the annotation-count line it appends — subtracted from
+     * the byte budget below.
+     *
+     * Without it the budget is spent in full here and the caller's own bytes push
+     * the final string over the API's cap, which rejects the entire update and
+     * leaves the check run unresolved. Reserving instead drops one more tier of
+     * log lines, which costs context rather than the whole report.
+     */
+    reservedBytes?: number;
 }
 interface BuildAnnotationsOptions {
     stepResults: StepResultData[];
@@ -71,12 +82,25 @@ interface BuildProgressTextOptions {
         runId: string;
     };
 }
+/** GitHub Checks API output.summary byte limit. */
+export declare const SUMMARY_BYTE_LIMIT = 65535;
+/**
+ * Cut `summary` so it fits the API's cap, whatever a caller wrapped around it.
+ *
+ * The last line of defence, not the primary mechanism: `reservedBytes` is what
+ * keeps a summary readable by dropping log tiers, and this only runs when the
+ * final string is still over. Truncating at a UTF-8 boundary matters — a cut
+ * through a multi-byte sequence produces a replacement character and can leave
+ * the string one byte over the cap it was cut to fit.
+ */
+export declare function clampSummaryToLimit(summary: string, limit?: number): string;
 export { formatDuration } from '@kici-dev/shared';
 /**
  * Build a rich markdown summary for a GitHub Check run output.summary field.
  *
  * Includes: headline, step table, failure details with log context, trace footer.
- * Respects the 65535 byte limit with progressive log truncation.
+ * Respects the 65535 byte limit with progressive log truncation, minus whatever
+ * `reservedBytes` the caller will wrap around the result.
  */
 export declare function buildCheckRunSummary(opts: BuildCheckRunSummaryOptions): string;
 /**

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

@@ -13,6 +13,7 @@
  */
 import { type Kysely } from 'kysely';
 import type { Database } from '../db/types.js';
+import { JobKind } from '../db/types.js';
 import { ExecutionRunStatus, type InitFailure, RunFailureClass, ScalerEventType, OrchLogPhase } from '@kici-dev/engine';
 import type { ObserverRegistry } from '../ws/observer-registry.js';
 import type { LogStorage } from './log-storage.js';
@@ -36,6 +37,12 @@ export interface ExecutionContext {
      * `execution.status`.
      */
     workflowRepoIdentifier?: string;
+    /**
+     * True when this run records a global evaluation round rather than a
+     * workflow. Forwarded to the Platform so its own re-run refusal can admit the
+     * round's re-evaluation.
+     */
+    isGlobalEvalRound?: boolean;
     /** Git branch or tag (e.g. "main", "feature/foo"). */
     ref?: string;
     /** Trigger event type (e.g. "push", "pr:open"). */
@@ -64,6 +71,15 @@ export interface ExecutionContext {
      * subscriptions can match on it. Null/undefined for success or non-terminal.
      */
     failureClass?: RunFailureClass | null;
+    /**
+     * Resolved trust tier of the run's ref, and which branch's lock file it was
+     * evaluated against. Mirror the `execution_runs.trust_tier` /
+     * `lock_file_source` columns; both absent for a run whose trust never
+     * resolved. Read by the check-run reporter to name the reduced-privilege
+     * posture on a job's completion summary.
+     */
+    trustTier?: string;
+    lockFileSource?: string;
     /** Workflow-level concurrency config from the lock file. */
     concurrency?: {
         cancelInProgress?: boolean;
@@ -79,6 +95,7 @@ interface WorkflowCompleteCallbackData {
     jobResults: Array<{
         name: string;
         status: string;
+        outputs?: Record<string, unknown>;
     }>;
     routingKey?: string;
     repo: string;
@@ -106,6 +123,24 @@ export interface ExecutionTrackerDeps {
     observerRegistry?: ObserverRegistry;
     /** Optional callback when execution reaches terminal state. */
     onExecutionComplete?: (runId: string, status: Extract<ExecutionRunStatus, 'success' | 'failed' | 'cancelled'>, context: ExecutionContext, description?: string) => void;
+    /**
+     * Drop the in-process state a run leaves behind — its pending job contexts
+     * and its still-open eval gates.
+     *
+     * Separate from {@link ExecutionTrackerDeps.onExecutionComplete} because that
+     * callback is NOT the terminalization chokepoint it reads as. It fires on the
+     * three paths that finish a run whose jobs ran (`completeRun`, and both
+     * stale-detector arms) and on none of the paths that terminalize a run whose
+     * jobs never did — `failRun` (the expired-approval sweep and every
+     * pre-dispatch abort) and `cancelHeldRun` (an install gate rejected). Those
+     * are exactly the runs most likely to be holding a pending job context, since
+     * a context is only stored for a job that was gated rather than dispatched.
+     *
+     * Synchronous by contract: the in-memory half of the cleanup must not be
+     * deferred behind an await the caller does not hold, and the DB half is
+     * fire-and-forget inside the callback.
+     */
+    onRunTerminalCleanup?: (runId: string) => void;
     /** Optional callback to forward step status to Platform. */
     onStepStatusForward?: (runId: string, jobId: string, jobName: string, stepIndex: number, stepName: string, state: string, timestamp: number, data?: Record<string, unknown>, requestId?: string) => void;
     /** Optional callback when a completed run is pruned from memory. */
@@ -202,6 +237,7 @@ export declare class ExecutionTracker {
     private readonly db;
     private readonly observerRegistry?;
     private readonly onExecutionComplete?;
+    private readonly onRunTerminalCleanup?;
     private readonly onStepStatusForward?;
     private readonly onRunPruned?;
     private readonly onWorkflowComplete?;
@@ -350,6 +386,34 @@ export declare class ExecutionTracker {
      * after a peer ACKs a reroute.
      */
     markJobReroutedToPeer(runId: string, jobId: string, peerId: string): Promise<void>;
+    /**
+     * Whether a rerouted job has visibly started, read from the shared
+     * `execution_jobs` row rather than from a relayed progress frame.
+     *
+     * The coordinator's spawn-window backstop learns about progress from
+     * `job.progress`, which only a WORKER peer sends — a worker has no database,
+     * so relaying is its only channel. A peer COORDINATOR writes the job's status
+     * straight into this table instead, so silence on the wire says nothing about
+     * whether the job is running, and the backstop would cancel a healthy job.
+     *
+     * False when no row exists yet (the peer has not started the job) and when the
+     * row is still `pending`; the `started_at` half covers a status that has
+     * already moved on to a terminal value.
+     */
+    hasJobStarted(runId: string, jobId: string): Promise<boolean>;
+    /**
+     * Whether a job has reached a terminal state in the shared `execution_jobs`
+     * row.
+     *
+     * The companion read to {@link hasJobStarted}: a peer COORDINATOR runs a
+     * rerouted job against this same table and relays no terminal `job.progress`,
+     * so the row is the only signal the routing coordinator gets that the job is
+     * over and its reroute tracking can be released.
+     *
+     * False when no row exists yet — an absent row is a job that has not started,
+     * never a finished one.
+     */
+    isJobTerminal(runId: string, jobId: string): Promise<boolean>;
     /**
      * Run `fn` while holding a per-run lock, serializing the run-mutating methods
      * (`onJobStatus`, `addJobsToRun`) so a status reply cannot interleave with the
@@ -377,6 +441,9 @@ export declare class ExecutionTracker {
         contexts?: string[];
         skippedContexts?: string[];
         envWarning?: string;
+        jobKind?: JobKind;
+        summonedRunId?: string;
+        timeoutMs?: number;
     }>, dispatchedContexts?: string[], 
     /** Synthetic job ID to replace (e.g. needs-pending-deploy-{uuid}). */
     replaceSyntheticId?: string): Promise<void>;
@@ -470,6 +537,13 @@ export declare class ExecutionTracker {
      * - `noop`: nothing — a later terminal will free the next slot.
      */
     private runWaveSchedulerHook;
+    /**
+     * When a proxy job of an invoke gate reaches terminal, aggregate the gate once
+     * every sibling proxy is terminal: the gate is set `failed` if any proxy
+     * failed, else `success`. Setting the gate terminal drives its own downstream
+     * `needs` release via the scheduler hook. A no-op for any non-proxy job.
+     */
+    private runInvokeGateAggregationHook;
     /**
      * Phase 9: stuck-jobs invariant check ( Layer 3).
      * Before declaring a run complete, verify no stuck jobs exist. If any are
@@ -484,6 +558,51 @@ export declare class ExecutionTracker {
      * observer callbacks, and schedules in-memory pruning.
      */
     private finalizeRunCompletion;
+    /**
+     * Map a terminal run status to the terminal job status a proxy should carry.
+     * A failure class collapses to `failed`; a cancel to `cancelled`; everything
+     * else (success) to `success`.
+     */
+    private mapRunStatusToProxyStatus;
+    /**
+     * Read a summoned run's non-secret declared outputs — the merged `outputs`
+     * JSONB of its jobs. Secret-masked outputs live in `run_secret_outputs` and
+     * are deliberately NOT read here, so a repo's secret output never crosses into
+     * the summoning global run.
+     */
+    private readNonSecretRunOutputs;
+    /**
+     * Normalize an `outputs` JSONB cell to a plain object. The Postgres driver may
+     * return it already parsed (object) or as a JSON string; both are accepted. A
+     * null / empty / malformed cell yields `null`.
+     */
+    private parseOutputsCell;
+    /**
+     * When `spawnedRunId` was summoned by an invoke gate, set the gate's proxy job
+     * to the run's mapped terminal status and attach its non-secret outputs. The
+     * proxy's terminal transition drives the summoning run's scheduler (release the
+     * next held proxy, and aggregate the gate once every proxy is terminal).
+     */
+    private mirrorSummonedRunOntoProxy;
+    /**
+     * Set a proxy job's timeline span to the summoned run's own started_at /
+     * completed_at so its dashboard bar reflects the run it mirrors. A run rejected
+     * before executing any step has no start; fall back to its completion (and, for
+     * a run with no completion recorded, to the mirror timestamp) so the proxy
+     * still renders a point-width bar rather than a status-only placeholder.
+     */
+    private mirrorSummonedRunSpanOntoProxy;
+    /**
+     * Reconcile a just-tagged summoned run against its proxy: if the run is already
+     * terminal, drive the mirror now. Closes the tag race — a run that finalizes
+     * before `summoned_by_run_id` lands (a synchronous all-jobs-rejected completion,
+     * or an HA peer finalizing it first) reads a null tag in `mirrorSummonedRunOntoProxy`
+     * and skips, so nothing else terminalizes its proxy and the gate hangs until
+     * its timeout. The invoke gate calls this after tagging each spawned run; the
+     * `onJobStatus` idempotency guard makes a double-fire with the normal finalize
+     * a no-op.
+     */
+    reconcileSummonedRunIfTerminal(spawnedRunId: string): Promise<void>;
     /**
      * Mark a run as failed when its build fails (timeout or error).
      *
@@ -498,8 +617,25 @@ export declare class ExecutionTracker {
      *
      * Inserts a minimal execution_runs row with status='failed' directly so the E2E
      * test (and dashboard) can observe the failure instead of a missing run.
-     */
-    onBuildFailedBeforeTracking(runId: string, workflowName: string, provider: string, repoIdentifier: string, ref: string, sha: string, deliveryId: string | null, providerContext: Record<string, unknown>, routingKey: string, triggerEvent?: string, commitMessage?: string, failureReason?: string, initFailure?: InitFailure): Promise<void>;
+     *
+     * The fifth pre-dispatch recording site, and the third that writes the row and
+     * returns. Its row is terminal with no resume path, so no invoke gate ever
+     * reads its `chain_depth` — the stamp is here for the same reason as on
+     * {@link ExecutionTracker.recordInitFailureRun}: this row is the run's ONLY
+     * record, and one that says `0` claims to have started the chain it actually
+     * died inside.
+     */
+    onBuildFailedBeforeTracking(runId: string, workflowName: string, provider: string, repoIdentifier: string, ref: string, sha: string, deliveryId: string | null, providerContext: Record<string, unknown>, routingKey: string, triggerEvent?: string, commitMessage?: string, failureReason?: string, initFailure?: InitFailure, 
+    /**
+     * Internal-trigger provenance, as one object rather than two more
+     * positional args on an already 13-wide signature. Shape matches
+     * `preDispatchRunProvenance` in `dispatch-matched-workflow.ts`, which is
+     * the only caller.
+     */
+    provenance?: {
+        chainDepth?: number;
+        dispatchedByFailureLifecycle?: boolean;
+    }): Promise<void>;
     /**
      * Write a `failed` execution_runs row directly for an init failure, and drop
      * any in-memory run so the recorded failure is the run's final word. Also
@@ -543,6 +679,29 @@ export declare class ExecutionTracker {
          * and records nothing.
          */
         workflowRepoIdentifier: string;
+        /**
+         * Inherited invoke-chain depth for a run summoned by an invoke gate.
+         *
+         * An init failure is terminal, so unlike the hold on
+         * {@link ExecutionTracker.recordRunHeld} this run never fires a gate of its
+         * own and nothing reads the column back to bound recursion. It is recorded
+         * because this row is the run's ONLY record: one that says `0` claims to
+         * have started the chain it actually died inside.
+         */
+        chainDepth?: number;
+        /**
+         * True when a failure-lifecycle trigger dispatched this run, recorded as
+         * the run's `trigger_decision` marker
+         * (`EventRouter.isFailureLifecycleRun`).
+         *
+         * Consistency rather than a live reader: this path emits no
+         * `__workflow_complete`, so no accumulator reads the marker back today. It
+         * is recorded so the row does not disagree with the one
+         * {@link ExecutionTracker.recordRunHeld} writes for the same dispatch, and
+         * so adding an emit here later cannot silently re-open the self-retrigger
+         * loop.
+         */
+        dispatchedByFailureLifecycle?: boolean;
     }): Promise<void>;
     /**
      * Write one `failed` execution_runs row for a global eval round that never
@@ -573,6 +732,16 @@ export declare class ExecutionTracker {
         deliveryId: string | null;
         providerContext: Record<string, unknown>;
         routingKey: string;
+        /**
+         * The source `providerContext` was taken from, when a cross-provider
+         * lock-file fallback made it a different source from `routingKey`.
+         *
+         * Recorded because the two are a PAIR: a re-run of this round re-drives the
+         * organization-wide pass and must hand it the same bundle those credentials
+         * belong to. Pairing the stored context with the inbound routing key instead
+         * gives one source's credentials to another source's API client.
+         */
+        dispatchRoutingKey?: string;
         failureReason: string;
         triggerEvent?: string;
         /**
@@ -623,6 +792,20 @@ export declare class ExecutionTracker {
          * whole time it sits in the queue and for the run it resumes into.
          */
         workflowRepoIdentifier: string;
+        /**
+         * Inherited invoke-chain depth for a run summoned by an invoke gate.
+         * REQUIRED to be threaded by any caller that has one: a hold is resumable,
+         * so the resumed run can fire its own invoke gate, and the chain-depth
+         * circuit breaker reads this column back. Absent ⇒ the column's `0`
+         * default, which means "this run starts a chain".
+         */
+        chainDepth?: number;
+        /**
+         * True when a failure-lifecycle trigger dispatched this run, recorded as
+         * the run's `trigger_decision` marker so its eventual completion is
+         * excluded from batch accumulation (`EventRouter.isFailureLifecycleRun`).
+         */
+        dispatchedByFailureLifecycle?: boolean;
     }): Promise<void>;
     /**
      * Flip a `held` run back to `pending` so the resumed dispatch can proceed
@@ -769,6 +952,28 @@ export declare class ExecutionTracker {
      * Used by commit status reporting to access provider/repo/sha info.
      */
     getExecutionContext(runId: string): ExecutionContext | undefined;
+    /**
+     * Stamp the run's resolved trust tier and lock-file branch onto the in-memory
+     * state, after `onExecutionStarted` recorded the row.
+     *
+     * Separate from the start call because trust resolves on its own path and is
+     * written to `execution_runs` by its own update. The dispatch site that
+     * writes those two columns calls this with the same values, but the two
+     * writes are independent and either can be lost: the DB update is
+     * fire-and-forget with its own `.catch()`, and this call is wrapped in a
+     * `try`/`catch` there. Both are deliberate — the note is worth less than the
+     * run — so the in-memory copy and the row CAN disagree, and neither is
+     * authoritative for the other. `recoverRunFromDb` reconciles by reading the
+     * row, so the durable value is the one that survives.
+     *
+     * A run this tracker does not know is a no-op: a missing run means the status
+     * updates that would read the fields are not coming either.
+     *
+     * Keep this synchronous. Its one caller wraps it in `try`/`catch`, which
+     * catches a throw but not a rejected promise, so an async body would put the
+     * failure back outside the guard.
+     */
+    setRunTrustContext(runId: string, trustTier: string, lockFileSource?: string): void;
     /**
      * Update the heartbeat timestamp for a running job.
      *

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

@@ -1,17 +1,3 @@
-/**
- * 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 { ExecutionJobStatus, type InitFailure } from '@kici-dev/engine';
 import type { Database } from '../db/types.js';
@@ -58,6 +44,8 @@ export interface RunDetailJobRow {
     base_job_name: string | null;
     variant_kind: string | null;
     variant_label: string | null;
+    job_kind: string | null;
+    summoned_run_id: string | null;
     started_at: Date | null;
     completed_at: Date | null;
     duration_ms: number | null;
@@ -104,6 +92,8 @@ export declare function buildRunDetailJobs(jobs: RunDetailJobRow[], lookups: Run
     baseJobName: string | null;
     variantKind: string | null;
     variantLabel: string | null;
+    jobKind: string | null;
+    summonedRunId: string | null;
     startedAt: number | null;
     completedAt: number | null;
     durationMs: number | null;

package/dist/reporting/step-display-order.d.ts

@@ -0,0 +1,43 @@
+/**
+ * The order a run's steps are shown in.
+ *
+ * Every reader of `execution_steps` sorted by `step_index` alone, which puts a
+ * pseudo-step wherever its index landed rather than where it ran. That is fine
+ * for the cache pseudo-steps, whose indices sit above the real steps and which
+ * mostly bracket the work — but a job's image build runs strictly FIRST, and
+ * rendering it last reads as though it happened last.
+ *
+ * The index cannot express this: `step.status` rejects a negative index (an
+ * agent sending one to an older orchestrator is disconnected mid-job), and two
+ * consumers treat a negative index as absent — the check-run reporter writes
+ * `steps[stepIndex]`, and the dashboard gates log fetching on `stepIndex >= 0`.
+ * So the ordering is expressed by TYPE, here, once, rather than by each reader
+ * inventing its own rule.
+ */
+import { type Expression } from 'kysely';
+/**
+ * Sort key placing setup pseudo-steps (the ones that ran before the job's real
+ * steps) ahead of everything else. Apply BEFORE the `step_index` sort:
+ *
+ * ```ts
+ * qb.orderBy(setupStepsFirst()).orderBy('step_index', 'asc')
+ * ```
+ *
+ * Steps with no type, and every real step, share the same key — so within each
+ * group `step_index` remains the only thing that orders them, exactly as before.
+ */
+export declare function setupStepsFirst(): Expression<number>;
+/**
+ * In-memory equivalent, for a caller that already holds the rows.
+ *
+ * Kept beside the SQL so the two cannot drift into disagreeing about what
+ * "setup" means.
+ */
+export declare function compareStepsForDisplay(a: {
+    step_type?: string | null;
+    step_index: number;
+}, b: {
+    step_type?: string | null;
+    step_index: number;
+}): number;
+//# sourceMappingURL=step-display-order.d.ts.map