@kici-dev/orchestrator 0.4.0 → 0.6.0

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';
@@ -28,6 +29,20 @@ export interface ExecutionContext {
     installationId?: number;
     requestId?: string;
     routingKey?: string;
+    /**
+     * The repository that DEFINES the workflow, when that is not
+     * `repoIdentifier` — a global workflow authored in one repository and
+     * dispatched against another. Set only when the two differ, so "present"
+     * marks a cross-repository global run; forwarded to the Platform on
+     * `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"). */
@@ -56,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;
@@ -71,6 +95,7 @@ interface WorkflowCompleteCallbackData {
     jobResults: Array<{
         name: string;
         status: string;
+        outputs?: Record<string, unknown>;
     }>;
     routingKey?: string;
     repo: string;
@@ -98,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. */
@@ -194,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?;
@@ -302,7 +346,14 @@ export declare class ExecutionTracker {
     /** Agent provenance label when triggered through an agent credential. */
     triggeredByAgentLabel?: string | null, 
     /** Pull-request number for PR-triggered runs; null/omitted for non-PR runs. */
-    prNumber?: number | null): Promise<void>;
+    prNumber?: number | null, 
+    /**
+     * The repository that DEFINES the workflow, when that is not
+     * `repoIdentifier` — an organization-wide workflow authored in one
+     * repository and dispatched against another. Omitted/null for every
+     * per-repository run, where the two are the same repository.
+     */
+    workflowRepoIdentifier?: 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
@@ -335,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
@@ -362,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>;
@@ -455,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
@@ -469,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).
      *
@@ -483,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
@@ -515,6 +666,91 @@ export declare class ExecutionTracker {
         initFailure: InitFailure;
         triggerEvent?: string;
         commitMessage?: string;
+        /**
+         * The repository that DEFINES the workflow this run was about to execute.
+         * REQUIRED: every run has one, and a caller that does not state it must not
+         * compile. Left optional, a global dispatch path added later would record a
+         * null marker — and a null marker does not mean "unknown", it means "the
+         * workflow lives in this run's own repository", which the whole
+         * defining-repository predicate then reads as fact.
+         *
+         * Narrowed to the differing case here, exactly as `onExecutionStarted`
+         * does, so passing `repoIdentifier` (the per-repository case) is correct
+         * 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
+     * produced verdicts.
+     *
+     * The round decides which organization-wide workflows apply to an event, so a
+     * round that fails suppresses every workflow it was deciding on. Without a row
+     * that outcome is invisible: no run was ever created for those workflows, so
+     * there is nothing on the dashboard to explain why they did not appear.
+     *
+     * **One row for the whole round, not one per workflow.** The round exists to
+     * collapse N candidate workflows into a single pre-run job; fanning its
+     * failure back out into N rows would undo exactly that. The reason names every
+     * affected workflow instead.
+     *
+     * Its `runId` is the round job's own — the last attempt's — so the row, the
+     * `dispatch_queue` row, and the attempt's logs all carry one id. No conflict
+     * guard is needed beyond `doNothing`: the id was minted for this round and
+     * belongs to no other run.
+     */
+    recordGlobalEvalRoundFailureRun(args: {
+        runId: string;
+        workflowName: string;
+        provider: string;
+        repoIdentifier: string;
+        ref: string;
+        sha: string;
+        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;
+        /**
+         * The repository whose global workflows the round was deciding. A round is
+         * definitionally the cross-repository case, so this is normally a different
+         * repository from `repoIdentifier` — recorded, like everywhere else, only
+         * when the two actually differ.
+         */
+        workflowRepoIdentifier: string;
     }): Promise<void>;
     /**
      * Record a run paused at the workflow install gate (a `registries:` /
@@ -549,6 +785,27 @@ export declare class ExecutionTracker {
          * security hold fail-closed unreachable by the comment path.
          */
         prNumber?: number | null;
+        /**
+         * The repository that DEFINES the held workflow. REQUIRED for the same
+         * reason as on {@link ExecutionTracker.recordInitFailureRun}: a hold is a
+         * live, resumable run, so a null marker here would misattribute it for the
+         * 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
@@ -593,11 +850,13 @@ export declare class ExecutionTracker {
      * registered. Returns true when a token was taken, false for an unknown or
      * already-completed run (nothing to hold).
      *
-     * Three registration windows need this. A run whose source-pack `__build__`
+     * Four registration windows need this. A run whose source-pack `__build__`
      * job is dispatched first is registered with that job ALONE, and its real
-     * jobs are only dispatched once the build finishes. A deferred init job and a
-     * deferred dynamic entry each register their jobs from a fire-and-forget task
-     * that outlives the dispatch call. In every case, without a token the already
+     * jobs are only dispatched once the build finishes; a run without a build is
+     * registered with NO jobs before its dispatch loop, so its jobs land once
+     * every dispatch has returned. A deferred init job and a deferred dynamic
+     * entry each register their jobs from a fire-and-forget task that outlives
+     * the dispatch call. In every case, without a token the already
      * -registered jobs reaching a terminal state satisfies {@link isRunComplete},
      * so the run is finalized early: a terminal run status is written, the
      * provider check is posted, and the status is forwarded to the Platform — all
@@ -612,9 +871,13 @@ export declare class ExecutionTracker {
      * and an off-by-one job count for the length of the window. A counter holds
      * the completion check open without being visible to any of them, and it
      * writes no `execution_jobs` row, so it never surfaces as a phantom job.
-     * A token whose holder never settles keeps the run `running` until the stale
+     * A token whose holder never settles keeps the run open until the stale
      * detector reaps it — the same backstop that covers a job that never
-     * reports.
+     * reports. That backstop only reaches a run that has at least one job: every
+     * sub-scan of the stale detector starts from `execution_jobs` or
+     * `dispatch_queue`. So a holder that registers NO jobs must terminalize the
+     * run itself rather than rely on the sweep — which is what
+     * `dispatchMatchedWorkflow` does when its dispatch loop throws.
      *
      * Each token must be paired with exactly one {@link releasePendingJobsHold}.
      */
@@ -645,6 +908,35 @@ export declare class ExecutionTracker {
      * Used by LogWriter to construct log paths.
      */
     getJobName(runId: string, jobId: string): string | undefined;
+    /**
+     * Resolve the job name that names a step-log storage path, with a durable
+     * fallback. The step-log path is `executions/{runId}/job-{jobName}/…` and it
+     * is written from two sites — the chunk writer (`log-chunk-sink`) and the
+     * `execution_steps.log_path` upsert in `onStepStatus`. A purely in-memory
+     * lookup (`getJobName`) returns `undefined` during the brief window between
+     * dispatch and `addJobsToRun` populating `run.jobs`, so an early chunk would
+     * land under `job-{jobId}` while the reader later keys on `job-{realName}` —
+     * silently losing those lines. Both write sites go through this resolver so
+     * they cannot disagree: in-memory first, then the authoritative
+     * `dispatch_queue.job_name` (the same source `recoverJobFromDispatchQueue`
+     * trusts), and only `jobId` when the job is genuinely unknown.
+     */
+    resolveJobName(runId: string, jobId: string): Promise<string>;
+    /**
+     * Seed the in-memory job name for a job the coordinator did not itself
+     * dispatch — a worker-rerouted job. Such a job is tracked in the cluster
+     * coordinator's own map, never enters this tracker's `run.jobs` via
+     * `addJobsToRun`, and has no coordinator-owned `dispatch_queue` row (the
+     * worker owns it under a fresh id), so `resolveJobName` would fall back to
+     * the bare `jobId` for its early log chunks while the reader keys on the real
+     * name — the same split-brain that loses lines. Seeding the name here, at
+     * reroute time, makes `resolveJobName`'s fast path correct from the first
+     * relayed chunk, independent of when the worker's `dispatch_queue` row becomes
+     * visible. In-memory only: the `execution_jobs` row is still created lazily by
+     * the worker's first status update. Guarded against clobbering an existing
+     * entry so a later terminal status is never overwritten.
+     */
+    registerJobName(runId: string, jobId: string, jobName: string): void;
     /**
      * Find the runId of the in-memory run that owns a given dispatched jobId.
      *
@@ -660,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.
      *
@@ -697,6 +1011,7 @@ export declare class ExecutionTracker {
         status: ExecutionRunStatus;
         routingKey?: string;
         repoIdentifier?: string;
+        workflowRepoIdentifier?: string;
         sha?: string;
         ref?: string;
         triggerEvent?: string;

package/dist/reporting/log-chunk-sink.d.ts

@@ -7,9 +7,12 @@
  * behave identically — a worker-dispatched job's logs are persisted, counted
  * and forwarded exactly like a locally-dispatched one's.
  *
- * The storage key is derived from `executionTracker.getJobName`, the same call
- * `ExecutionTracker.onStepStatus` uses to fill `execution_steps.log_path`, so
- * the reader and the writer cannot disagree about the naming rule.
+ * The storage key is derived from `executionTracker.resolveJobName`, the same
+ * call `ExecutionTracker.onStepStatus` uses to fill `execution_steps.log_path`,
+ * so the reader and the writer cannot disagree about the naming rule — the
+ * resolver falls back to `dispatch_queue.job_name` during the dispatch window
+ * before in-memory job state is populated, which is what stops an early chunk
+ * from being persisted under an unreadable `job-{jobId}` path.
  */
 import type { LogStream } from '@kici-dev/engine';
 import type { LogWriter } from './log-writer.js';
@@ -32,9 +35,9 @@ export interface LogChunkSinkDeps {
     stepLogBuffer?: StepLogBuffer;
     /** Durable step-log persistence. Absent when the orchestrator has no database. */
     logWriter?: LogWriter;
-    /** Resolves the job name that names the storage path. */
+    /** Resolves the job name that names the storage path (durable fallback). */
     executionTracker?: {
-        getJobName(runId: string, jobId: string): string | undefined;
+        resolveJobName(runId: string, jobId: string): Promise<string>;
     };
     /**
      * Forward to the Platform for browser fan-out. Absent in independent mode.

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