@kici-dev/engine 0.1.14 → 0.1.16

package/dist/protocol/messages/dashboard.js

@@ -5,6 +5,8 @@ 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 { ApprovalDecision, HoldScope, approverClauseSchema } from "../../approval/types.js";
 import { globalWorkflowsGetRequestSchema, globalWorkflowsGetResponseSchema, globalWorkflowsUpdateRequestSchema, globalWorkflowsUpdateResponseSchema } from "./dashboard-global-workflows.js";
 import { z } from "zod";
 //#region src/protocol/messages/dashboard.ts
@@ -95,6 +97,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"),
@@ -428,6 +532,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(),
@@ -455,6 +560,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(),
@@ -506,6 +612,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"),
@@ -513,10 +632,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({
@@ -765,8 +896,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,
@@ -776,7 +907,20 @@ const heldRunsListResponseSchema = z.object({
 		reason: z.string().nullable(),
 		expiresAt: z.coerce.string().nullable(),
 		contributorUsername: z.string().nullable().optional(),
-		trustTier: z.string().nullable().optional()
+		trustTier: z.string().nullable().optional(),
+		jobId: z.string().optional(),
+		holdScope: HoldScope.optional(),
+		stepIndex: z.number().nullable().optional(),
+		requirement: z.object({
+			clauses: z.array(approverClauseSchema),
+			reason: z.string().nullable().optional()
+		}).nullable().optional(),
+		decisions: z.array(z.object({
+			approverUserId: z.string(),
+			decision: ApprovalDecision,
+			clausesSatisfied: z.array(approverClauseSchema).nullable().optional(),
+			createdAt: z.coerce.string()
+		})).optional()
 	})).optional(),
 	error: z.string().optional()
 });
@@ -840,11 +984,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({
@@ -853,7 +1005,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({
@@ -879,7 +1033,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(),
@@ -933,7 +1088,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(),
@@ -1155,6 +1316,9 @@ const backendTestResponseSchema = z.object({
 const dashboardPlatformToOrchSchema = z.discriminatedUnion("type", [
 	dashboardRunDetailRequestSchema,
 	dashboardStepLogsRequestSchema,
+	dashboardRunsListRequestSchema,
+	dashboardRunsFiltersRequestSchema,
+	dashboardSourcesListRequestSchema,
 	runRerunRequestSchema,
 	manualScheduleRequestSchema,
 	runCancelRequestSchema,
@@ -1164,6 +1328,7 @@ const dashboardPlatformToOrchSchema = z.discriminatedUnion("type", [
 	envGetRequestSchema,
 	envCreateRequestSchema,
 	envUpdateRequestSchema,
+	envTestAccessSetRequestSchema,
 	envDeleteRequestSchema,
 	envVarsListRequestSchema,
 	envVarSetRequestSchema,
@@ -1209,6 +1374,9 @@ const dashboardPlatformToOrchSchema = z.discriminatedUnion("type", [
 const dashboardOrchToPlatformSchema = z.discriminatedUnion("type", [
 	dashboardRunDetailResponseSchema,
 	dashboardStepLogsResponseSchema,
+	dashboardRunsListResponseSchema,
+	dashboardRunsFiltersResponseSchema,
+	dashboardSourcesListResponseSchema,
 	runRerunResponseSchema,
 	manualScheduleResponseSchema,
 	runCancelResponseSchema,
@@ -1218,6 +1386,7 @@ const dashboardOrchToPlatformSchema = z.discriminatedUnion("type", [
 	envGetResponseSchema,
 	envCreateResponseSchema,
 	envUpdateResponseSchema,
+	envTestAccessSetResponseSchema,
 	envDeleteResponseSchema,
 	envVarsListResponseSchema,
 	envVarSetResponseSchema,
@@ -1334,6 +1503,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,18 +32,36 @@ 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 by the orchestrator at the detection site and
+ * 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, matrix_expansion).
+ *    build_coordination).
  *  - `job`-scoped categories fail one job and leave siblings alone
- *    (environment_rules, dynamic_eval, no_agent).
+ *    (environment_rules, dynamic_eval, no_agent, matrix_expansion).
  */
 export declare const InitFailureCategory: z.ZodEnum<{
     secret_resolution: "secret_resolution";
@@ -56,6 +74,41 @@ export declare const InitFailureCategory: z.ZodEnum<{
     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<{

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

@@ -32,17 +32,31 @@ const ExecutionStepStatus = z.enum([
 	"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 by the orchestrator at the detection site and
+* 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, matrix_expansion).
+*    build_coordination).
 *  - `job`-scoped categories fail one job and leave siblings alone
-*    (environment_rules, dynamic_eval, no_agent).
+*    (environment_rules, dynamic_eval, no_agent, matrix_expansion).
 */
 const InitFailureCategory = z.enum([
 	"secret_resolution",
@@ -54,6 +68,32 @@ const InitFailureCategory = z.enum([
 	"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"]),
@@ -201,6 +241,6 @@ const stateReplaySchema = z.object({
 	timestamp: z.number()
 });
 //#endregion
-export { ExecutionJobStatus, ExecutionRunStatus, ExecutionStepStatus, InitFailureCategory, TERMINAL_JOB_STATES, TERMINAL_RUN_STATES, executionStatusSchema, initFailureSchema, 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