@kici-dev/engine 0.1.13 → 0.1.15

package/dist/protocol/messages/dashboard.js

@@ -1,9 +1,11 @@
 import "../../chunk-gOLHoazu.js";
 import { actorPrincipalSchema } from "./actor.js";
+import { initFailureSchema } from "./execution-status.js";
 import { SourceSubtype } from "./source-registration.js";
 import { dashboardAccessLogListRequestSchema, dashboardAccessLogListResponseSchema } from "./access-log.js";
 import { dashboardOrchLogsRequestSchema, dashboardOrchLogsResponseSchema } from "./run-events.js";
 import { EventLogSource, EventLogStatus, PayloadOmittedReason } from "./event-log.js";
+import { ScalerBackendType } from "../../scaler/scaler-backend-type.js";
 import { globalWorkflowsGetRequestSchema, globalWorkflowsGetResponseSchema, globalWorkflowsUpdateRequestSchema, globalWorkflowsUpdateResponseSchema } from "./dashboard-global-workflows.js";
 import { z } from "zod";
 //#region src/protocol/messages/dashboard.ts
@@ -56,6 +58,11 @@ const dashboardJobDetailSchema = z.object({
 	outputs: z.record(z.string(), z.record(z.string(), z.unknown())).nullable().optional(),
 	/** Secret output key names produced by this job (values are NOT included -- display masked). */
 	secretOutputKeys: z.array(z.string()).nullable().optional(),
+	/**
+	* Structured init-failure signal for jobs that never started. Presence means
+	* the job is a synthetic `rejected-*` or `init-failed-*` row; status will be 'failed'.
+	*/
+	initFailure: initFailureSchema.optional(),
 	steps: z.array(dashboardStepDetailSchema)
 });
 /** Trust context from orchestrator execution_runs (populated for PR-triggered runs). */
@@ -74,6 +81,11 @@ const dashboardRunDetailResponseSchema = z.object({
 	requestId: z.string(),
 	jobs: z.array(dashboardJobDetailSchema),
 	trustContext: trustContextSchema.optional(),
+	/**
+	* Structured init-failure signal for runs that never started. Set when the
+	* run row was created via recordInitFailureRun() on the orchestrator side.
+	*/
+	initFailure: initFailureSchema.optional(),
 	error: z.string().optional()
 });
 /** Response with step log lines (correlates to dashboard.step.logs). */
@@ -84,6 +96,108 @@ const dashboardStepLogsResponseSchema = z.object({
 	totalLines: z.number(),
 	error: z.string().optional()
 });
+/**
+* Run-summary projection from the orchestrator's execution_runs table.
+*
+* The required fields (`runId` / `routingKey` / `status`) are always present.
+* Every other field is optional: the orchestrator omits what it cannot
+* supply, and the customer runs page degrades a missing field to '—'.
+*/
+const dashboardRunSummarySchema = z.object({
+	runId: z.string(),
+	routingKey: z.string(),
+	status: z.string(),
+	repoIdentifier: z.string().nullable().optional(),
+	createdAt: z.string(),
+	updatedAt: z.string().optional(),
+	trigger: z.string().optional(),
+	workflowName: z.string().optional(),
+	sha: z.string().optional(),
+	ref: z.string().optional(),
+	triggerEvent: z.string().optional(),
+	commitMessage: z.string().optional(),
+	jobCount: z.number().optional(),
+	startedAt: z.string().optional(),
+	completedAt: z.string().optional(),
+	durationMs: z.number().optional(),
+	parentRunId: z.string().optional(),
+	originalRunId: z.string().optional(),
+	triggeredBy: z.string().optional(),
+	cancelledBy: z.string().optional(),
+	failureReason: z.string().optional(),
+	hadCompileJob: z.boolean().optional(),
+	compileJobId: z.string().optional(),
+	source: z.object({
+		routingKey: z.string(),
+		name: z.string().nullable(),
+		subtype: z.string(),
+		provider: z.string()
+	}).optional()
+});
+/** Request a page of run summaries from the orchestrator. */
+const dashboardRunsListRequestSchema = z.object({
+	type: z.literal("dashboard.runs.list"),
+	requestId: z.string(),
+	actor: actorPrincipalSchema,
+	/** Page size (1-200). Bounds protect the orchestrator from unbounded reads. */
+	limit: z.number().int().min(1).max(200).optional(),
+	cursor: z.string().optional()
+});
+/** Response with the page of run summaries + next-page cursor. */
+const dashboardRunsListResponseSchema = z.object({
+	type: z.literal("dashboard.runs.list.response"),
+	requestId: z.string(),
+	runs: z.array(dashboardRunSummarySchema),
+	nextCursor: z.string().optional(),
+	error: z.string().optional()
+});
+/** Request the distinct filter-option values from the orchestrator. */
+const dashboardRunsFiltersRequestSchema = z.object({
+	type: z.literal("dashboard.runs.filters"),
+	requestId: z.string(),
+	actor: actorPrincipalSchema
+});
+/** Response with the distinct filter-option values. */
+const dashboardRunsFiltersResponseSchema = z.object({
+	type: z.literal("dashboard.runs.filters.response"),
+	requestId: z.string(),
+	statuses: z.array(z.string()),
+	workflows: z.array(z.string()),
+	branches: z.array(z.string()),
+	repositories: z.array(z.string()),
+	triggerTypes: z.array(z.string()),
+	sources: z.array(z.object({
+		routingKey: z.string(),
+		name: z.string().nullable()
+	})),
+	error: z.string().optional()
+});
+/** Minimal source-summary projection from the orchestrator's sources tables. */
+const dashboardSourceSummarySchema = z.object({
+	routingKey: z.string(),
+	name: z.string().nullable(),
+	provider: z.string(),
+	subtype: SourceSubtype,
+	enabled: z.boolean(),
+	createdAt: z.string()
+});
+/** Request a page of source summaries from the orchestrator. */
+const dashboardSourcesListRequestSchema = z.object({
+	type: z.literal("dashboard.sources.list"),
+	requestId: z.string(),
+	actor: actorPrincipalSchema,
+	/** Page size (1-200). Bounds protect the orchestrator from unbounded reads. */
+	limit: z.number().int().min(1).max(200).optional(),
+	cursor: z.string().optional()
+});
+/** Response with the page of source summaries + next-page cursor. */
+const dashboardSourcesListResponseSchema = z.object({
+	type: z.literal("dashboard.sources.list.response"),
+	requestId: z.string(),
+	sources: z.array(dashboardSourceSummarySchema),
+	nextCursor: z.string().optional(),
+	error: z.string().optional()
+});
 /** Request to re-run a completed run. */
 const runRerunRequestSchema = z.object({
 	type: z.literal("run.rerun.request"),
@@ -417,6 +531,7 @@ const envListResponseSchema = z.object({
 		type: environmentTypeSchema,
 		globPattern: z.string().nullable(),
 		enabled: z.boolean(),
+		allowLocalExecution: z.boolean(),
 		createdAt: z.coerce.string(),
 		updatedAt: z.coerce.string()
 	})).optional(),
@@ -444,6 +559,7 @@ const envGetResponseSchema = z.object({
 		waitTimerSeconds: z.number().nullable(),
 		holdExpirySeconds: z.number().nullable(),
 		enabled: z.boolean(),
+		allowLocalExecution: z.boolean(),
 		createdAt: z.coerce.string(),
 		updatedAt: z.coerce.string()
 	}).optional(),
@@ -495,6 +611,19 @@ const envUpdateResponseSchema = z.object({
 	requestId: z.string(),
 	error: z.string().optional()
 });
+/** Set an environment's test-run access flag (allowLocalExecution). */
+const envTestAccessSetRequestSchema = z.object({
+	type: z.literal("dashboard.environments.test_access.set"),
+	requestId: z.string(),
+	actor: actorPrincipalSchema,
+	environmentId: z.string(),
+	allowLocalExecution: z.boolean()
+});
+const envTestAccessSetResponseSchema = z.object({
+	type: z.literal("dashboard.environments.test_access.set.response"),
+	requestId: z.string(),
+	error: z.string().optional()
+});
 /** Delete an environment. */
 const envDeleteRequestSchema = z.object({
 	type: z.literal("dashboard.environments.delete"),
@@ -502,10 +631,22 @@ const envDeleteRequestSchema = z.object({
 	actor: actorPrincipalSchema,
 	environmentId: z.string()
 });
+/**
+* Machine-readable codes for environment-delete rejections.
+*
+* Three-category response taxonomy on dashboard responses, each mapped to a
+* distinct HTTP status by the Platform proxy: a bare free-text `error` is the
+* human message and maps to 400; a missing result (e.g. environment not found)
+* maps to 404; an `errorCode` flags a specific business rejection mapped to a
+* non-400/404 status — here `pending_held_runs` → 409. The sibling precedent is
+* the rerun response's `errorCode` (`runArchivedNotRerunnable` → 410) above.
+*/
+const EnvDeleteErrorCode = z.enum(["pending_held_runs"]);
 const envDeleteResponseSchema = z.object({
 	type: z.literal("dashboard.environments.delete.response"),
 	requestId: z.string(),
-	error: z.string().optional()
+	error: z.string().optional(),
+	errorCode: EnvDeleteErrorCode.optional()
 });
 /** List variables for an environment. */
 const envVarsListRequestSchema = z.object({
@@ -754,8 +895,8 @@ const heldRunsListResponseSchema = z.object({
 	heldRuns: z.array(z.object({
 		id: z.string(),
 		runId: z.string(),
-		environmentId: z.string(),
-		environmentName: z.string(),
+		environmentId: z.string().nullable(),
+		environmentName: z.string().nullable(),
 		holdType: z.string(),
 		queueType: HeldRunQueueType,
 		status: HeldRunStatus,
@@ -829,11 +970,19 @@ const diagnosticsAgentSchema = z.object({
 /** Single scaler backend within the diagnostics response. */
 const diagnosticsScalerSchema = z.object({
 	name: z.string(),
-	type: z.string(),
+	type: ScalerBackendType,
 	maxAgents: z.number(),
 	activeAgents: z.number(),
 	labelSets: z.array(z.array(z.string())),
-	config: z.record(z.string(), z.unknown()).optional()
+	config: z.record(z.string(), z.unknown()).optional(),
+	/**
+	* The spawning host of this scaler, declared statically by its backend.
+	* Populated (with the owning orchestrator instance's hostname) for backends
+	* that spawn agents on the host itself — bare-metal, Firecracker, container
+	* on a local runtime socket. Omitted for backends that provision elsewhere
+	* (remote container runtime, future cloud backends).
+	*/
+	hosts: z.array(z.string()).optional()
 });
 /** Agent info within a peer diagnostics entry (subset of full agent schema). */
 const diagnosticsPeerAgentSchema = z.object({
@@ -842,7 +991,9 @@ const diagnosticsPeerAgentSchema = z.object({
 	platform: z.string(),
 	arch: z.string(),
 	activeJobs: z.number(),
-	maxConcurrency: z.number()
+	maxConcurrency: z.number(),
+	/** Scaler backend that spawned the agent, or null for static (stateful) agents. */
+	scalerName: z.string().nullable().optional()
 });
 /** Peer orchestrator reported by coordinator in diagnostics. */
 const diagnosticsPeerSchema = z.object({
@@ -868,7 +1019,8 @@ const diagnosticsPeerSchema = z.object({
 		type: z.string().optional(),
 		activeCount: z.number(),
 		maxAgents: z.number(),
-		labelSets: z.array(z.array(z.string()))
+		labelSets: z.array(z.array(z.string())),
+		spawnsOnLocalHost: z.boolean().optional()
 	})).optional(),
 	dependencyHealth: z.array(z.object({
 		name: z.string(),
@@ -922,7 +1074,13 @@ const dashboardDiagnosticsResponseSchema = z.object({
 		/** Total number of registered agents (always populated regardless of includeAgents). */
 		agentCount: z.number().nullable().optional(),
 		/** Number of agents not bound to any scaler. */
-		statefulAgentCount: z.number().nullable().optional()
+		statefulAgentCount: z.number().nullable().optional(),
+		/**
+		* Distinct host names of stateful (unbound) agents, derived from their
+		* self-reported kici:host: labels. Lets the dashboard surface the hosts of
+		* long-lived standalone agents on the collapsed "Stateful agents" header.
+		*/
+		statefulHosts: z.array(z.string()).optional()
 	}),
 	agents: z.array(diagnosticsAgentSchema),
 	scalers: z.array(diagnosticsScalerSchema).optional(),
@@ -1144,6 +1302,9 @@ const backendTestResponseSchema = z.object({
 const dashboardPlatformToOrchSchema = z.discriminatedUnion("type", [
 	dashboardRunDetailRequestSchema,
 	dashboardStepLogsRequestSchema,
+	dashboardRunsListRequestSchema,
+	dashboardRunsFiltersRequestSchema,
+	dashboardSourcesListRequestSchema,
 	runRerunRequestSchema,
 	manualScheduleRequestSchema,
 	runCancelRequestSchema,
@@ -1153,6 +1314,7 @@ const dashboardPlatformToOrchSchema = z.discriminatedUnion("type", [
 	envGetRequestSchema,
 	envCreateRequestSchema,
 	envUpdateRequestSchema,
+	envTestAccessSetRequestSchema,
 	envDeleteRequestSchema,
 	envVarsListRequestSchema,
 	envVarSetRequestSchema,
@@ -1198,6 +1360,9 @@ const dashboardPlatformToOrchSchema = z.discriminatedUnion("type", [
 const dashboardOrchToPlatformSchema = z.discriminatedUnion("type", [
 	dashboardRunDetailResponseSchema,
 	dashboardStepLogsResponseSchema,
+	dashboardRunsListResponseSchema,
+	dashboardRunsFiltersResponseSchema,
+	dashboardSourcesListResponseSchema,
 	runRerunResponseSchema,
 	manualScheduleResponseSchema,
 	runCancelResponseSchema,
@@ -1207,6 +1372,7 @@ const dashboardOrchToPlatformSchema = z.discriminatedUnion("type", [
 	envGetResponseSchema,
 	envCreateResponseSchema,
 	envUpdateResponseSchema,
+	envTestAccessSetResponseSchema,
 	envDeleteResponseSchema,
 	envVarsListResponseSchema,
 	envVarSetResponseSchema,
@@ -1251,7 +1417,14 @@ const dashboardOrchToPlatformSchema = z.discriminatedUnion("type", [
 /** REST API response for run detail (jobs with nested steps). */
 const dashboardRunDetailApiResponseSchema = z.object({
 	jobs: z.array(dashboardJobDetailSchema),
-	trustContext: trustContextSchema.optional()
+	trustContext: trustContextSchema.optional(),
+	/**
+	* Structured init-failure signal for runs that never started a step. Set
+	* when the run row was created via `recordInitFailureRun()` on the
+	* orchestrator and surfaced to the dashboard so the banner can render
+	* even while the orchestrator is offline (Platform-DB fallback path).
+	*/
+	initFailure: initFailureSchema.optional()
 });
 /** REST API response for step logs. */
 const dashboardStepLogsApiResponseSchema = z.object({
@@ -1316,6 +1489,6 @@ const orgMemberSchema = z.object({
 /** Response for org members list endpoint. */
 const memberListResponseSchema = z.object({ members: z.array(orgMemberSchema) });
 //#endregion
-export { EventLogPayloadStreamError, HeldRunQueueType, HeldRunStatus, backendGetRequestSchema, backendGetResponseSchema, backendItemSchema, backendSyncRequestSchema, backendSyncResponseSchema, backendTestRequestSchema, backendTestResponseSchema, backendsListRequestSchema, backendsListResponseSchema, backendsSyncAllRequestSchema, backendsSyncAllResponseSchema, browserEventLogPayloadChunkSchema, dashboardDiagnosticsRequestSchema, dashboardDiagnosticsResponseSchema, dashboardEventDlqCountRequestSchema, dashboardEventDlqDiscardRequestSchema, dashboardEventDlqListItemSchema, dashboardEventDlqListRequestSchema, dashboardEventDlqRetryRequestSchema, dashboardEventLogDetailRequestSchema, dashboardEventLogListRequestSchema, dashboardEventLogPayloadChunkSchema, dashboardEventLogPayloadStreamRequestSchema, dashboardJobDetailSchema, dashboardOrchToPlatformSchema, dashboardPayloadRequestSchema, dashboardPlatformToOrchSchema, dashboardRunDetailApiResponseSchema, dashboardRunDetailRequestSchema, dashboardRunDetailResponseSchema, dashboardScalerAgentsRequestSchema, dashboardScalerAgentsResponseSchema, dashboardScalerCapacityRequestSchema, dashboardScalerCapacityResponseSchema, dashboardStepLogsApiResponseSchema, dashboardStepLogsRequestSchema, dashboardStepLogsResponseSchema, envBindingsListRequestSchema, envBindingsSetRequestSchema, envCreateRequestSchema, envDeleteRequestSchema, envGetRequestSchema, envHistoryRequestSchema, envListRequestSchema, envSecretDeleteRequestSchema, envSecretScopeCreateRequestSchema, envSecretScopeDeleteRequestSchema, envSecretScopeRenameRequestSchema, envSecretSetRequestSchema, envSecretsListRequestSchema, envSourceOverrideDeleteRequestSchema, envSourceOverrideSetRequestSchema, envSourceOverridesListRequestSchema, envUpdateRequestSchema, envVarDeleteRequestSchema, envVarSetRequestSchema, envVarsListRequestSchema, eventLogListItemSchema, heldRunApproveRequestSchema, heldRunRejectRequestSchema, heldRunsListRequestSchema, identityLinkItemSchema, identityLinkListResponseSchema, manualScheduleRequestSchema, memberIdentityLinkSchema, memberListResponseSchema, memberRoleAssignmentSchema, orgMemberSchema, registrationDeleteRequestSchema, registrationDisableRequestSchema, registrationItemSchema, registrationsListRequestSchema, registrationsListResponseSchema, runCancelRequestSchema, runEventSchema, runLineageResponseSchema, runRerunRequestSchema, trustPolicyResponseSchema };
+export { EnvDeleteErrorCode, EventLogPayloadStreamError, HeldRunQueueType, HeldRunStatus, backendGetRequestSchema, backendGetResponseSchema, backendItemSchema, backendSyncRequestSchema, backendSyncResponseSchema, backendTestRequestSchema, backendTestResponseSchema, backendsListRequestSchema, backendsListResponseSchema, backendsSyncAllRequestSchema, backendsSyncAllResponseSchema, browserEventLogPayloadChunkSchema, dashboardDiagnosticsRequestSchema, dashboardDiagnosticsResponseSchema, dashboardEventDlqCountRequestSchema, dashboardEventDlqDiscardRequestSchema, dashboardEventDlqListItemSchema, dashboardEventDlqListRequestSchema, dashboardEventDlqRetryRequestSchema, dashboardEventLogDetailRequestSchema, dashboardEventLogListRequestSchema, dashboardEventLogPayloadChunkSchema, dashboardEventLogPayloadStreamRequestSchema, dashboardJobDetailSchema, dashboardOrchToPlatformSchema, dashboardPayloadRequestSchema, dashboardPlatformToOrchSchema, dashboardRunDetailApiResponseSchema, dashboardRunDetailRequestSchema, dashboardRunDetailResponseSchema, dashboardRunSummarySchema, dashboardRunsFiltersRequestSchema, dashboardRunsFiltersResponseSchema, dashboardRunsListRequestSchema, dashboardRunsListResponseSchema, dashboardScalerAgentsRequestSchema, dashboardScalerAgentsResponseSchema, dashboardScalerCapacityRequestSchema, dashboardScalerCapacityResponseSchema, dashboardSourceSummarySchema, dashboardSourcesListRequestSchema, dashboardSourcesListResponseSchema, dashboardStepLogsApiResponseSchema, dashboardStepLogsRequestSchema, dashboardStepLogsResponseSchema, envBindingsListRequestSchema, envBindingsSetRequestSchema, envCreateRequestSchema, envDeleteRequestSchema, envGetRequestSchema, envHistoryRequestSchema, envListRequestSchema, envSecretDeleteRequestSchema, envSecretScopeCreateRequestSchema, envSecretScopeDeleteRequestSchema, envSecretScopeRenameRequestSchema, envSecretSetRequestSchema, envSecretsListRequestSchema, envSourceOverrideDeleteRequestSchema, envSourceOverrideSetRequestSchema, envSourceOverridesListRequestSchema, envTestAccessSetRequestSchema, envUpdateRequestSchema, envVarDeleteRequestSchema, envVarSetRequestSchema, envVarsListRequestSchema, eventLogListItemSchema, heldRunApproveRequestSchema, heldRunRejectRequestSchema, heldRunsListRequestSchema, identityLinkItemSchema, identityLinkListResponseSchema, manualScheduleRequestSchema, memberIdentityLinkSchema, memberListResponseSchema, memberRoleAssignmentSchema, orgMemberSchema, registrationDeleteRequestSchema, registrationDisableRequestSchema, registrationItemSchema, registrationsListRequestSchema, registrationsListResponseSchema, runCancelRequestSchema, runEventSchema, runLineageResponseSchema, runRerunRequestSchema, trustPolicyResponseSchema };
 
 //# sourceMappingURL=dashboard.js.map

package/dist/protocol/messages/event-log.d.ts

@@ -9,6 +9,9 @@ import { z } from 'zod';
  * - `duplicate` — dedup cache rejected the delivery.
  * - `lockfile_missing` — repo lookup succeeded but no lock file was found
  *   (and no global workflows matched either).
+ * - `lockfile_corrupt` — a lock file was present at the repo ref but could not
+ *   be parsed or validated; the orchestrator records a `lock_resolution`
+ *   init-failure run for the delivery.
  * - `failed` — pipeline threw an unhandled error. `error_message` carries
  *   the message.
  */
@@ -18,6 +21,7 @@ export declare const EventLogStatus: z.ZodEnum<{
     processed: "processed";
     duplicate: "duplicate";
     lockfile_missing: "lockfile_missing";
+    lockfile_corrupt: "lockfile_corrupt";
 }>;
 export type EventLogStatus = z.infer<typeof EventLogStatus>;
 /**

package/dist/protocol/messages/event-log.js

@@ -11,6 +11,9 @@ import { z } from "zod";
 * - `duplicate` — dedup cache rejected the delivery.
 * - `lockfile_missing` — repo lookup succeeded but no lock file was found
 *   (and no global workflows matched either).
+* - `lockfile_corrupt` — a lock file was present at the repo ref but could not
+*   be parsed or validated; the orchestrator records a `lock_resolution`
+*   init-failure run for the delivery.
 * - `failed` — pipeline threw an unhandled error. `error_message` carries
 *   the message.
 */
@@ -19,6 +22,7 @@ const EventLogStatus = z.enum([
 	"processed",
 	"duplicate",
 	"lockfile_missing",
+	"lockfile_corrupt",
 	"failed"
 ]);
 /**

package/dist/protocol/messages/execution-status.d.ts

@@ -32,6 +32,103 @@ export declare const ExecutionStepStatus: z.ZodEnum<{
     skipped: "skipped";
 }>;
 export type ExecutionStepStatus = z.infer<typeof ExecutionStepStatus>;
+/**
+ * Distinct reasons a run/job ended because a configured wall-clock timeout
+ * was exceeded. Surfaced in the failure/cancel reason so the dashboard can
+ * label "timed out" instead of a generic failure.
+ *
+ *  - `job_timeout`      — a job exceeded its `timeout` (total job wall-clock,
+ *                         agent-enforced in the forked workflow-runner).
+ *  - `workflow_timeout` — a run exceeded the workflow `timeout` (whole-run
+ *                         wall-clock, orchestrator-enforced run deadline).
+ *
+ * Step-level timeouts are reported inline in the step error message and do
+ * NOT use this enum (they predate it and stay as-is).
+ */
+export declare const TimeoutReason: z.ZodEnum<{
+    job_timeout: "job_timeout";
+    workflow_timeout: "workflow_timeout";
+}>;
+export type TimeoutReason = z.infer<typeof TimeoutReason>;
+/**
+ * Categories of init failure — i.e. failures that prevent a run from ever
+ * executing a step. Set at the detection site (orchestrator or agent) and
+ * persisted alongside the run/job row so the dashboard can render an
+ * explanatory banner even when the orchestrator is offline.
+ *
+ * Scope is carried separately on `initFailureSchema.scope`:
+ *  - `run`-scoped categories fail the whole run before any job runs
+ *    (secret_resolution, install_secrets, lock_resolution,
+ *    build_coordination).
+ *  - `job`-scoped categories fail one job and leave siblings alone
+ *    (environment_rules, dynamic_eval, no_agent, matrix_expansion).
+ */
+export declare const InitFailureCategory: z.ZodEnum<{
+    secret_resolution: "secret_resolution";
+    install_secrets: "install_secrets";
+    lock_resolution: "lock_resolution";
+    build_coordination: "build_coordination";
+    environment_rules: "environment_rules";
+    dynamic_eval: "dynamic_eval";
+    no_agent: "no_agent";
+    matrix_expansion: "matrix_expansion";
+}>;
+export type InitFailureCategory = z.infer<typeof InitFailureCategory>;
+/**
+ * `step_type` values for the user-facing cache pseudo-steps that appear in the
+ * run timeline. Mirrors the `hook:*` pseudo-step `step_type` convention: each
+ * declarative job/step cache restore or save surfaces as one pseudo-step so the
+ * dashboard can render it inline alongside the real steps.
+ */
+export declare const CacheStepType: z.ZodEnum<{
+    "cache:restore": "cache:restore";
+    "cache:save": "cache:save";
+}>;
+export type CacheStepType = z.infer<typeof CacheStepType>;
+/** `run.event` types emitted for user-facing cache operations. */
+export declare const CacheRunEventType: z.ZodEnum<{
+    "cache.restore": "cache.restore";
+    "cache.save": "cache.save";
+}>;
+export type CacheRunEventType = z.infer<typeof CacheRunEventType>;
+/**
+ * Outcome recorded on a cache pseudo-step (drives the pseudo-step status + the
+ * `run.event` metadata).
+ *
+ *  - `hit`     — restore found an entry (exact key or restoreKeys prefix).
+ *  - `miss`    — restore found nothing.
+ *  - `saved`   — save uploaded a new entry under the immutable key.
+ *  - `skipped` — save was a no-op (the immutable exact key already existed).
+ *  - `error`   — the restore/save failed (pack/extract/transport error).
+ */
+export declare const CacheOutcome: z.ZodEnum<{
+    error: "error";
+    skipped: "skipped";
+    hit: "hit";
+    miss: "miss";
+    saved: "saved";
+}>;
+export type CacheOutcome = z.infer<typeof CacheOutcome>;
+/** Structured init-failure signal. Presence on a run/job means "never started". */
+export declare const initFailureSchema: z.ZodObject<{
+    scope: z.ZodEnum<{
+        run: "run";
+        job: "job";
+    }>;
+    category: z.ZodEnum<{
+        secret_resolution: "secret_resolution";
+        install_secrets: "install_secrets";
+        lock_resolution: "lock_resolution";
+        build_coordination: "build_coordination";
+        environment_rules: "environment_rules";
+        dynamic_eval: "dynamic_eval";
+        no_agent: "no_agent";
+        matrix_expansion: "matrix_expansion";
+    }>;
+    message: z.ZodString;
+    jobName: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export type InitFailure = z.infer<typeof initFailureSchema>;
 /** Terminal run states that indicate the run has completed. */
 export declare const TERMINAL_RUN_STATES: ReadonlySet<string>;
 /** Terminal job states that indicate the job is no longer running. */
@@ -65,6 +162,24 @@ export declare const executionStatusSchema: z.ZodObject<{
     triggeredBy: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     failureReason: z.ZodOptional<z.ZodString>;
     logBytes: z.ZodOptional<z.ZodNumber>;
+    initFailure: z.ZodOptional<z.ZodObject<{
+        scope: z.ZodEnum<{
+            run: "run";
+            job: "job";
+        }>;
+        category: z.ZodEnum<{
+            secret_resolution: "secret_resolution";
+            install_secrets: "install_secrets";
+            lock_resolution: "lock_resolution";
+            build_coordination: "build_coordination";
+            environment_rules: "environment_rules";
+            dynamic_eval: "dynamic_eval";
+            no_agent: "no_agent";
+            matrix_expansion: "matrix_expansion";
+        }>;
+        message: z.ZodString;
+        jobName: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 /** Per-step status forwarded from agent to Platform (real-time). */
 export declare const stepStatusForwardSchema: z.ZodObject<{
@@ -115,6 +230,24 @@ export declare const jobStatusForwardSchema: z.ZodObject<{
     runsOnLabels: z.ZodOptional<z.ZodArray<z.ZodString>>;
     logBytes: z.ZodOptional<z.ZodNumber>;
     timestamp: z.ZodNumber;
+    initFailure: z.ZodOptional<z.ZodObject<{
+        scope: z.ZodEnum<{
+            run: "run";
+            job: "job";
+        }>;
+        category: z.ZodEnum<{
+            secret_resolution: "secret_resolution";
+            install_secrets: "install_secrets";
+            lock_resolution: "lock_resolution";
+            build_coordination: "build_coordination";
+            environment_rules: "environment_rules";
+            dynamic_eval: "dynamic_eval";
+            no_agent: "no_agent";
+            matrix_expansion: "matrix_expansion";
+        }>;
+        message: z.ZodString;
+        jobName: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 /** State replay sent on orchestrator reconnection -- full snapshot of active runs and jobs. */
 export declare const stateReplaySchema: z.ZodObject<{

package/dist/protocol/messages/execution-status.js

@@ -31,6 +31,78 @@ const ExecutionStepStatus = z.enum([
 	"failed",
 	"skipped"
 ]);
+/**
+* Distinct reasons a run/job ended because a configured wall-clock timeout
+* was exceeded. Surfaced in the failure/cancel reason so the dashboard can
+* label "timed out" instead of a generic failure.
+*
+*  - `job_timeout`      — a job exceeded its `timeout` (total job wall-clock,
+*                         agent-enforced in the forked workflow-runner).
+*  - `workflow_timeout` — a run exceeded the workflow `timeout` (whole-run
+*                         wall-clock, orchestrator-enforced run deadline).
+*
+* Step-level timeouts are reported inline in the step error message and do
+* NOT use this enum (they predate it and stay as-is).
+*/
+const TimeoutReason = z.enum(["job_timeout", "workflow_timeout"]);
+/**
+* Categories of init failure — i.e. failures that prevent a run from ever
+* executing a step. Set at the detection site (orchestrator or agent) and
+* persisted alongside the run/job row so the dashboard can render an
+* explanatory banner even when the orchestrator is offline.
+*
+* Scope is carried separately on `initFailureSchema.scope`:
+*  - `run`-scoped categories fail the whole run before any job runs
+*    (secret_resolution, install_secrets, lock_resolution,
+*    build_coordination).
+*  - `job`-scoped categories fail one job and leave siblings alone
+*    (environment_rules, dynamic_eval, no_agent, matrix_expansion).
+*/
+const InitFailureCategory = z.enum([
+	"secret_resolution",
+	"install_secrets",
+	"lock_resolution",
+	"build_coordination",
+	"environment_rules",
+	"dynamic_eval",
+	"no_agent",
+	"matrix_expansion"
+]);
+/**
+* `step_type` values for the user-facing cache pseudo-steps that appear in the
+* run timeline. Mirrors the `hook:*` pseudo-step `step_type` convention: each
+* declarative job/step cache restore or save surfaces as one pseudo-step so the
+* dashboard can render it inline alongside the real steps.
+*/
+const CacheStepType = z.enum(["cache:restore", "cache:save"]);
+/** `run.event` types emitted for user-facing cache operations. */
+const CacheRunEventType = z.enum(["cache.restore", "cache.save"]);
+/**
+* Outcome recorded on a cache pseudo-step (drives the pseudo-step status + the
+* `run.event` metadata).
+*
+*  - `hit`     — restore found an entry (exact key or restoreKeys prefix).
+*  - `miss`    — restore found nothing.
+*  - `saved`   — save uploaded a new entry under the immutable key.
+*  - `skipped` — save was a no-op (the immutable exact key already existed).
+*  - `error`   — the restore/save failed (pack/extract/transport error).
+*/
+const CacheOutcome = z.enum([
+	"hit",
+	"miss",
+	"saved",
+	"skipped",
+	"error"
+]);
+/** Structured init-failure signal. Presence on a run/job means "never started". */
+const initFailureSchema = z.object({
+	scope: z.enum(["run", "job"]),
+	category: InitFailureCategory,
+	/** Human-readable failure message (same content surfaced by RunFailureSummary). */
+	message: z.string(),
+	/** Set when scope === 'job'. */
+	jobName: z.string().optional()
+});
 /** Terminal run states that indicate the run has completed. */
 const TERMINAL_RUN_STATES = new Set([
 	ExecutionRunStatus.enum.success,
@@ -80,7 +152,13 @@ const executionStatusSchema = z.object({
 	* Only set on terminal run states. Powers the operator-side
 	* `kici_org_log_bytes` capacity-planning gauge on the Platform.
 	*/
-	logBytes: z.number().int().nonnegative().optional()
+	logBytes: z.number().int().nonnegative().optional(),
+	/**
+	* Structured init-failure signal. Set by the orchestrator when the run
+	* never executed a single step. Persisted in execution_runs.init_failure
+	* on both orchestrator and Platform sides. Only present when status === 'failed'.
+	*/
+	initFailure: initFailureSchema.optional()
 });
 /** Per-step status forwarded from agent to Platform (real-time). */
 const stepStatusForwardSchema = z.object({
@@ -121,7 +199,9 @@ const jobStatusForwardSchema = z.object({
 	* `kici_org_log_bytes` capacity-planning gauge on the Platform.
 	*/
 	logBytes: z.number().int().nonnegative().optional(),
-	timestamp: z.number()
+	timestamp: z.number(),
+	/** Structured init-failure signal — set for synthetic rejected-* / init-failed-* jobs. */
+	initFailure: initFailureSchema.optional()
 });
 /** State replay sent on orchestrator reconnection -- full snapshot of active runs and jobs. */
 const stateReplaySchema = z.object({
@@ -161,6 +241,6 @@ const stateReplaySchema = z.object({
 	timestamp: z.number()
 });
 //#endregion
-export { ExecutionJobStatus, ExecutionRunStatus, ExecutionStepStatus, TERMINAL_JOB_STATES, TERMINAL_RUN_STATES, executionStatusSchema, jobStatusForwardSchema, stateReplaySchema, stepStatusForwardSchema };
+export { CacheOutcome, CacheRunEventType, CacheStepType, ExecutionJobStatus, ExecutionRunStatus, ExecutionStepStatus, InitFailureCategory, TERMINAL_JOB_STATES, TERMINAL_RUN_STATES, TimeoutReason, executionStatusSchema, initFailureSchema, jobStatusForwardSchema, stateReplaySchema, stepStatusForwardSchema };
 
 //# sourceMappingURL=execution-status.js.map