@kici-dev/engine 0.1.21 → 0.1.22

package/dist/protocol/messages/dashboard.js

@@ -2,6 +2,7 @@ import "../../chunk-BTugEXQM.js";
 import { CheckMode, CheckStepOutcome } from "../../check-mode.js";
 import { actorPrincipalSchema } from "./actor.js";
 import { initFailureSchema } from "./execution-status.js";
+import { DeploymentContainerRuntimeSchema, DeploymentModeSchema } from "./deployment-identity.js";
 import { SourceSubtype } from "./source-registration.js";
 import { kiciBundleSchema } from "../../provenance/bundle.js";
 import { dashboardAccessLogListRequestSchema, dashboardAccessLogListResponseSchema } from "./access-log.js";
@@ -9,7 +10,9 @@ import { dashboardOrchLogsRequestSchema, dashboardOrchLogsResponseSchema } from
 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 { IfFailedPolicy } from "../../trigger/types.js";
+import { NeedsRunOn, OnUnreachableMode } from "../../trigger/types.js";
+import { HostTargetSelector } from "../../labels-match.js";
+import { HostInventoryEntry } from "../../inventory.js";
 import { globalWorkflowsGetRequestSchema, globalWorkflowsGetResponseSchema, globalWorkflowsUpdateRequestSchema, globalWorkflowsUpdateResponseSchema } from "./dashboard-global-workflows.js";
 import { z } from "zod";
 //#region src/protocol/messages/dashboard.ts
@@ -80,12 +83,13 @@ const dashboardJobDetailSchema = z.object({
 	/**
 	* Upstream dependency edges for this job (one entry per `needs` declaration),
 	* resolved by the orchestrator from execution_job_needs. `upstreamName` is the
-	* upstream job name; `ifFailed` is the per-edge failure policy. null/absent when
-	* the job has no upstreams.
+	* upstream job name; `runOn` is the per-edge run-on status-set (the upstream
+	* terminal statuses that satisfy the edge). null/absent when the job has no
+	* upstreams.
 	*/
 	needs: z.array(z.object({
 		upstreamName: z.string(),
-		ifFailed: IfFailedPolicy
+		runOn: NeedsRunOn
 	})).nullable().optional(),
 	steps: z.array(dashboardStepDetailSchema)
 });
@@ -990,6 +994,10 @@ const heldRunsListResponseSchema = z.object({
 			clauses: z.array(approverClauseSchema),
 			reason: z.string().nullable().optional()
 		}).nullable().optional(),
+		payload: z.object({
+			summaryMarkdown: z.string(),
+			drift: z.unknown()
+		}).nullable().optional(),
 		decisions: z.array(z.object({
 			approverUserId: z.string(),
 			decision: ApprovalDecision,
@@ -1004,7 +1012,14 @@ const heldRunApproveRequestSchema = z.object({
 	type: z.literal("dashboard.held-runs.approve"),
 	requestId: z.string(),
 	actor: actorPrincipalSchema,
-	heldRunId: z.string()
+	heldRunId: z.string(),
+	/**
+	* Set by the `kici run --approve-all` breakglass: the approval was issued by
+	* the run's own dispatcher auto-approving every gate of that run. Eligibility
+	* is still enforced (this only changes the audit action to
+	* `held_run.auto_approve`); it is never a bypass.
+	*/
+	autoApprove: z.boolean().optional()
 });
 const heldRunApproveResponseSchema = z.object({
 	type: z.literal("dashboard.held-runs.approve.response"),
@@ -1032,6 +1047,90 @@ const dashboardDiagnosticsRequestSchema = z.object({
 	/** When false or omitted, agents[] is empty and aggregate fields are populated instead. */
 	includeAgents: z.boolean().optional()
 });
+/** A run pinned to a host, for the host-detail "recent runs" list. */
+const fleetPinnedRunSchema = z.object({
+	runId: z.string(),
+	workflowName: z.string().nullable(),
+	status: z.string(),
+	createdAt: z.string()
+});
+/** A host matched by a runsOnAll preview, plus how the fan-out would treat it. */
+const fleetPreviewHostSchema = z.object({
+	entry: HostInventoryEntry,
+	disposition: z.enum([
+		"target",
+		"unreachable-durable",
+		"skipped-ephemeral"
+	])
+});
+const dashboardFleetHostsRequestSchema = z.object({
+	type: z.literal("dashboard.fleet.hosts"),
+	requestId: z.string(),
+	actor: actorPrincipalSchema
+});
+const dashboardFleetHostRequestSchema = z.object({
+	type: z.literal("dashboard.fleet.host"),
+	requestId: z.string(),
+	actor: actorPrincipalSchema,
+	agentId: z.string()
+});
+const dashboardFleetPreviewRequestSchema = z.object({
+	type: z.literal("dashboard.fleet.preview"),
+	requestId: z.string(),
+	actor: actorPrincipalSchema,
+	workflowName: z.string()
+});
+const dashboardFleetHostsResponseSchema = z.object({
+	type: z.literal("dashboard.fleet.hosts.response"),
+	requestId: z.string(),
+	hosts: z.array(HostInventoryEntry)
+});
+const dashboardFleetHostResponseSchema = z.object({
+	type: z.literal("dashboard.fleet.host.response"),
+	requestId: z.string(),
+	host: HostInventoryEntry.nullable(),
+	runs: z.array(fleetPinnedRunSchema)
+});
+const dashboardFleetPreviewResponseSchema = z.object({
+	type: z.literal("dashboard.fleet.preview.response"),
+	requestId: z.string(),
+	matched: z.array(fleetPreviewHostSchema),
+	onUnreachable: OnUnreachableMode,
+	estimatedChildCount: z.number()
+});
+/** Declare a static host into the roster (wraps HostRosterStore.declareStatic). */
+const fleetHostDeclareRequestSchema = z.object({
+	type: z.literal("dashboard.fleet.host.declare"),
+	requestId: z.string(),
+	actor: actorPrincipalSchema,
+	agentId: z.string(),
+	labels: z.array(z.string()),
+	hostname: z.string().optional(),
+	properties: z.record(z.string(), z.union([
+		z.string(),
+		z.number(),
+		z.boolean()
+	])).optional()
+});
+const fleetHostDeclareResponseSchema = z.object({
+	type: z.literal("dashboard.fleet.host.declare.response"),
+	requestId: z.string(),
+	declared: z.boolean().optional(),
+	error: z.string().optional()
+});
+/** Remove a host from the roster by agent id (HostRosterStore.removeStatic). */
+const fleetHostRemoveRequestSchema = z.object({
+	type: z.literal("dashboard.fleet.host.remove"),
+	requestId: z.string(),
+	actor: actorPrincipalSchema,
+	agentId: z.string()
+});
+const fleetHostRemoveResponseSchema = z.object({
+	type: z.literal("dashboard.fleet.host.remove.response"),
+	requestId: z.string(),
+	removed: z.boolean().optional(),
+	error: z.string().optional()
+});
 /** Agent info within the diagnostics response. */
 const diagnosticsAgentSchema = z.object({
 	agentId: z.string(),
@@ -1431,6 +1530,11 @@ const testRelayTriggerRequestSchema = z.object({
 	fullRepo: z.boolean().optional(),
 	/** Run mode for idempotent steps; relayed onto the dispatch event. Omitted = apply. */
 	checkMode: CheckMode.optional(),
+	/**
+	* Runtime host narrowing from `kici run --target`. Intersects each runsOnAll
+	* job's matched roster with this selector. Omitted for webhook runs.
+	*/
+	target: HostTargetSelector.optional(),
 	secrets: z.record(z.string(), z.string()).optional(),
 	encryptedSecrets: z.string().optional(),
 	encryptedSecretsKey: z.string().optional()
@@ -1541,6 +1645,11 @@ const dashboardPlatformToOrchSchema = z.discriminatedUnion("type", [
 	registrationDisableRequestSchema,
 	registrationDeleteRequestSchema,
 	dashboardDiagnosticsRequestSchema,
+	dashboardFleetHostsRequestSchema,
+	dashboardFleetHostRequestSchema,
+	dashboardFleetPreviewRequestSchema,
+	fleetHostDeclareRequestSchema,
+	fleetHostRemoveRequestSchema,
 	dashboardScalerCapacityRequestSchema,
 	dashboardScalerAgentsRequestSchema,
 	backendsListRequestSchema,
@@ -1605,6 +1714,11 @@ const dashboardOrchToPlatformSchema = z.discriminatedUnion("type", [
 	registrationDisableResponseSchema,
 	registrationDeleteResponseSchema,
 	dashboardDiagnosticsResponseSchema,
+	dashboardFleetHostsResponseSchema,
+	dashboardFleetHostResponseSchema,
+	dashboardFleetPreviewResponseSchema,
+	fleetHostDeclareResponseSchema,
+	fleetHostRemoveResponseSchema,
 	dashboardScalerCapacityResponseSchema,
 	dashboardScalerAgentsResponseSchema,
 	backendsListResponseSchema,
@@ -1755,6 +1869,16 @@ const diagnosticsInfraOrchestratorSchema = z.object({
 	raftTerm: z.number().nullable().optional(),
 	raftLeaderId: z.string().nullable().optional(),
 	scalerBackends: z.array(z.string()),
+	/**
+	* Self-reported deployment shape, used by the dashboard to build the correct
+	* per-orchestrator kici-admin invocation. Orchestrators that never reported
+	* it serialize as `mode: 'unknown'` with null container fields.
+	*/
+	deployment: z.object({
+		mode: DeploymentModeSchema,
+		containerName: z.string().nullable(),
+		containerRuntime: DeploymentContainerRuntimeSchema.nullable()
+	}),
 	s3LogAccess: z.boolean().nullable().optional(),
 	agentCount: z.number(),
 	runningJobs: z.number(),
@@ -1867,6 +1991,6 @@ const orgMemberSchema = z.object({
 /** Response for org members list endpoint. */
 const memberListResponseSchema = z.object({ members: z.array(orgMemberSchema) });
 //#endregion
-export { EnvDeleteErrorCode, EventLogPayloadStreamError, HeldRunQueueType, HeldRunStatus, TestRelayType, attestationListItemSchema, backendGetRequestSchema, backendGetResponseSchema, backendItemSchema, backendSyncRequestSchema, backendSyncResponseSchema, backendTestRequestSchema, backendTestResponseSchema, backendsListRequestSchema, backendsListResponseSchema, backendsSyncAllRequestSchema, backendsSyncAllResponseSchema, browserEventLogPayloadChunkSchema, dashboardAttestationsApiResponseSchema, dashboardAttestationsListRequestSchema, dashboardAttestationsListResponseSchema, 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, diagnosticsInfrastructureResponseSchema, diagnosticsSummaryResponseSchema, 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, runListItemSchema, runListResponseSchema, runRerunRequestSchema, testRelayCancelRequestSchema, testRelayCancelResponseSchema, testRelayRunLogsRequestSchema, testRelayRunLogsResponseSchema, testRelayRunStatusRequestSchema, testRelayRunStatusResponseSchema, testRelayTriggerRequestSchema, testRelayTriggerResponseSchema, testRelayUploadsInitRequestSchema, testRelayUploadsInitResponseSchema, trustPolicyResponseSchema };
+export { EnvDeleteErrorCode, EventLogPayloadStreamError, HeldRunQueueType, HeldRunStatus, TestRelayType, attestationListItemSchema, backendGetRequestSchema, backendGetResponseSchema, backendItemSchema, backendSyncRequestSchema, backendSyncResponseSchema, backendTestRequestSchema, backendTestResponseSchema, backendsListRequestSchema, backendsListResponseSchema, backendsSyncAllRequestSchema, backendsSyncAllResponseSchema, browserEventLogPayloadChunkSchema, dashboardAttestationsApiResponseSchema, dashboardAttestationsListRequestSchema, dashboardAttestationsListResponseSchema, dashboardDiagnosticsRequestSchema, dashboardDiagnosticsResponseSchema, dashboardEventDlqCountRequestSchema, dashboardEventDlqDiscardRequestSchema, dashboardEventDlqListItemSchema, dashboardEventDlqListRequestSchema, dashboardEventDlqRetryRequestSchema, dashboardEventLogDetailRequestSchema, dashboardEventLogListRequestSchema, dashboardEventLogPayloadChunkSchema, dashboardEventLogPayloadStreamRequestSchema, dashboardFleetHostRequestSchema, dashboardFleetHostResponseSchema, dashboardFleetHostsRequestSchema, dashboardFleetHostsResponseSchema, dashboardFleetPreviewRequestSchema, dashboardFleetPreviewResponseSchema, dashboardJobDetailSchema, dashboardOrchToPlatformSchema, dashboardPayloadRequestSchema, dashboardPlatformToOrchSchema, dashboardRunDetailApiResponseSchema, dashboardRunDetailRequestSchema, dashboardRunDetailResponseSchema, dashboardRunSummarySchema, dashboardRunsFiltersRequestSchema, dashboardRunsFiltersResponseSchema, dashboardRunsListRequestSchema, dashboardRunsListResponseSchema, dashboardScalerAgentsRequestSchema, dashboardScalerAgentsResponseSchema, dashboardScalerCapacityRequestSchema, dashboardScalerCapacityResponseSchema, dashboardSourceSummarySchema, dashboardSourcesListRequestSchema, dashboardSourcesListResponseSchema, dashboardStepLogsApiResponseSchema, dashboardStepLogsRequestSchema, dashboardStepLogsResponseSchema, diagnosticsInfrastructureResponseSchema, diagnosticsSummaryResponseSchema, envBindingsListRequestSchema, envBindingsSetRequestSchema, envCreateRequestSchema, envDeleteRequestSchema, envGetRequestSchema, envHistoryRequestSchema, envListRequestSchema, envSecretDeleteRequestSchema, envSecretScopeCreateRequestSchema, envSecretScopeDeleteRequestSchema, envSecretScopeRenameRequestSchema, envSecretSetRequestSchema, envSecretsListRequestSchema, envSourceOverrideDeleteRequestSchema, envSourceOverrideSetRequestSchema, envSourceOverridesListRequestSchema, envTestAccessSetRequestSchema, envUpdateRequestSchema, envVarDeleteRequestSchema, envVarSetRequestSchema, envVarsListRequestSchema, eventLogListItemSchema, fleetHostDeclareRequestSchema, fleetHostDeclareResponseSchema, fleetHostRemoveRequestSchema, fleetHostRemoveResponseSchema, fleetPinnedRunSchema, fleetPreviewHostSchema, heldRunApproveRequestSchema, heldRunRejectRequestSchema, heldRunsListRequestSchema, identityLinkItemSchema, identityLinkListResponseSchema, manualScheduleRequestSchema, memberIdentityLinkSchema, memberListResponseSchema, memberRoleAssignmentSchema, orgMemberSchema, registrationDeleteRequestSchema, registrationDisableRequestSchema, registrationItemSchema, registrationsListRequestSchema, registrationsListResponseSchema, runCancelRequestSchema, runEventSchema, runLineageResponseSchema, runListItemSchema, runListResponseSchema, runRerunRequestSchema, testRelayCancelRequestSchema, testRelayCancelResponseSchema, testRelayRunLogsRequestSchema, testRelayRunLogsResponseSchema, testRelayRunStatusRequestSchema, testRelayRunStatusResponseSchema, testRelayTriggerRequestSchema, testRelayTriggerResponseSchema, testRelayUploadsInitRequestSchema, testRelayUploadsInitResponseSchema, trustPolicyResponseSchema };
 
 //# sourceMappingURL=dashboard.js.map

package/dist/protocol/messages/deployment-identity.d.ts

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+/** How the orchestrator process itself was deployed (not how it runs agents). */
+export declare const DeploymentModeSchema: z.ZodEnum<{
+    unknown: "unknown";
+    systemd: "systemd";
+    launchd: "launchd";
+    windows: "windows";
+    compose: "compose";
+}>;
+export type DeploymentMode = z.infer<typeof DeploymentModeSchema>;
+/** Container runtime that launched a `compose`-mode orchestrator. */
+export declare const DeploymentContainerRuntimeSchema: z.ZodEnum<{
+    podman: "podman";
+    docker: "docker";
+}>;
+export type DeploymentContainerRuntime = z.infer<typeof DeploymentContainerRuntimeSchema>;
+/**
+ * The orchestrator's self-reported deployment shape, used to build the correct
+ * kici-admin invocation in the dashboard diagnostics page. Container fields are
+ * populated only for the `compose` mode; a hand-run orchestrator reports
+ * `mode: 'unknown'` with no container fields.
+ */
+export declare const DeploymentIdentitySchema: z.ZodObject<{
+    mode: z.ZodEnum<{
+        unknown: "unknown";
+        systemd: "systemd";
+        launchd: "launchd";
+        windows: "windows";
+        compose: "compose";
+    }>;
+    containerName: z.ZodOptional<z.ZodString>;
+    containerRuntime: z.ZodOptional<z.ZodEnum<{
+        podman: "podman";
+        docker: "docker";
+    }>>;
+}, z.core.$strip>;
+export type DeploymentIdentity = z.infer<typeof DeploymentIdentitySchema>;
+//# sourceMappingURL=deployment-identity.d.ts.map

package/dist/protocol/messages/deployment-identity.js

@@ -0,0 +1,28 @@
+import "../../chunk-BTugEXQM.js";
+import { z } from "zod";
+//#region src/protocol/messages/deployment-identity.ts
+/** How the orchestrator process itself was deployed (not how it runs agents). */
+const DeploymentModeSchema = z.enum([
+	"systemd",
+	"launchd",
+	"windows",
+	"compose",
+	"unknown"
+]);
+/** Container runtime that launched a `compose`-mode orchestrator. */
+const DeploymentContainerRuntimeSchema = z.enum(["podman", "docker"]);
+/**
+* The orchestrator's self-reported deployment shape, used to build the correct
+* kici-admin invocation in the dashboard diagnostics page. Container fields are
+* populated only for the `compose` mode; a hand-run orchestrator reports
+* `mode: 'unknown'` with no container fields.
+*/
+const DeploymentIdentitySchema = z.object({
+	mode: DeploymentModeSchema,
+	containerName: z.string().min(1).optional(),
+	containerRuntime: DeploymentContainerRuntimeSchema.optional()
+});
+//#endregion
+export { DeploymentContainerRuntimeSchema, DeploymentIdentitySchema, DeploymentModeSchema };
+
+//# sourceMappingURL=deployment-identity.js.map

package/dist/protocol/messages/orchestrator-agent.d.ts

@@ -22,10 +22,25 @@ export type CacheRefScope = z.infer<typeof CacheRefScope>;
  *
  * - `jobs` maps an upstream job name to its outputs record.
  * - `groups` maps a dynamic group name to its ordered member job names.
+ * - `statuses` maps an upstream job name to its terminal status, so the
+ *   generator's `ctx.needs.<job>.status` reflects the frozen upstream outcome.
  */
 export declare const upstreamSnapshotSchema: z.ZodObject<{
     jobs: z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     groups: z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>;
+    statuses: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEnum<{
+        skipped: "skipped";
+        success: "success";
+        pending: "pending";
+        running: "running";
+        failed: "failed";
+        cancelled: "cancelled";
+        cancelling: "cancelling";
+        queued: "queued";
+        recovering: "recovering";
+        timed_out_stale: "timed_out_stale";
+        drift_dropped: "drift_dropped";
+    }>>>;
 }, z.core.$strip>;
 export type UpstreamSnapshot = z.infer<typeof upstreamSnapshotSchema>;
 /**
@@ -79,6 +94,19 @@ export declare const jobDispatchSchema: z.ZodObject<{
     requestId: z.ZodOptional<z.ZodString>;
     runPublicKey: z.ZodOptional<z.ZodString>;
     upstreamJobOutputs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    upstreamJobStatuses: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEnum<{
+        skipped: "skipped";
+        success: "success";
+        pending: "pending";
+        running: "running";
+        failed: "failed";
+        cancelled: "cancelled";
+        cancelling: "cancelling";
+        queued: "queued";
+        recovering: "recovering";
+        timed_out_stale: "timed_out_stale";
+        drift_dropped: "drift_dropped";
+    }>>>;
     sourceAuth: z.ZodOptional<z.ZodObject<{
         kind: z.ZodEnum<{
             basic: "basic";
@@ -491,12 +519,25 @@ export declare const StepApprovalOutcome: z.ZodEnum<{
 }>;
 export type StepApprovalOutcome = z.infer<typeof StepApprovalOutcome>;
 /**
- * Agent -> Orchestrator: a step carrying `requireApproval` is about to run and
+ * Drift payload carried on a `when: 'drift'` step-approval hold. Captured from
+ * the step's check/summarize: `summaryMarkdown` is the author's `summarize(drift)`
+ * rendering, `drift` is the structured drift blob. Rendered in the dashboard
+ * approval queue + the CLI so the operator sees the computed diff before
+ * approving the apply.
+ */
+export declare const stepApprovalPayloadSchema: z.ZodObject<{
+    summaryMarkdown: z.ZodString;
+    drift: z.ZodUnknown;
+}, z.core.$strip>;
+export type StepApprovalPayload = z.infer<typeof stepApprovalPayloadSchema>;
+/**
+ * Agent -> Orchestrator: a step carrying an `approval` gate is about to run and
  * the agent is blocking its step loop until the orchestrator resolves the
  * approval. The orchestrator creates a step-scoped `held_runs` row from the
  * normalized requirement and replies with `step.approval-resolved` once the
  * hold is approved, rejected, or expired. The agent keeps heartbeats flowing
- * during the wait so it is not reaped as stale.
+ * during the wait so it is not reaped as stale. For a `when: 'drift'` gate the
+ * request carries the computed drift `payload`.
  *
  * NOT fast-pathed — the `log.chunk` / `heartbeat` manual-validator invariant is
  * untouched by this message.
@@ -515,6 +556,10 @@ export declare const stepApprovalRequestSchema: z.ZodObject<{
     }, z.core.$strict>]>>;
     reason: z.ZodString;
     timeoutSeconds: z.ZodOptional<z.ZodNumber>;
+    payload: z.ZodOptional<z.ZodObject<{
+        summaryMarkdown: z.ZodString;
+        drift: z.ZodUnknown;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type StepApprovalRequest = z.infer<typeof stepApprovalRequestSchema>;
 /**
@@ -560,6 +605,19 @@ export declare const orchestratorToAgentMessageSchema: z.ZodDiscriminatedUnion<[
     requestId: z.ZodOptional<z.ZodString>;
     runPublicKey: z.ZodOptional<z.ZodString>;
     upstreamJobOutputs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    upstreamJobStatuses: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodEnum<{
+        skipped: "skipped";
+        success: "success";
+        pending: "pending";
+        running: "running";
+        failed: "failed";
+        cancelled: "cancelled";
+        cancelling: "cancelling";
+        queued: "queued";
+        recovering: "recovering";
+        timed_out_stale: "timed_out_stale";
+        drift_dropped: "drift_dropped";
+    }>>>;
     sourceAuth: z.ZodOptional<z.ZodObject<{
         kind: z.ZodEnum<{
             basic: "basic";
@@ -923,6 +981,10 @@ export declare const agentToOrchestratorMessageSchema: z.ZodDiscriminatedUnion<[
     }, z.core.$strict>]>>;
     reason: z.ZodString;
     timeoutSeconds: z.ZodOptional<z.ZodNumber>;
+    payload: z.ZodOptional<z.ZodObject<{
+        summaryMarkdown: z.ZodString;
+        drift: z.ZodUnknown;
+    }, z.core.$strip>>;
 }, z.core.$strip>], "type">;
 export type JobDispatch = z.infer<typeof jobDispatchSchema>;
 export type JobCancel = z.infer<typeof jobCancelSchema>;

package/dist/protocol/messages/orchestrator-agent.js

@@ -22,10 +22,13 @@ const CacheRefScope = z.enum(["shared", "isolated"]);
 *
 * - `jobs` maps an upstream job name to its outputs record.
 * - `groups` maps a dynamic group name to its ordered member job names.
+* - `statuses` maps an upstream job name to its terminal status, so the
+*   generator's `ctx.needs.<job>.status` reflects the frozen upstream outcome.
 */
 const upstreamSnapshotSchema = z.object({
 	jobs: z.record(z.string(), z.record(z.string(), z.unknown())),
-	groups: z.record(z.string(), z.array(z.string()))
+	groups: z.record(z.string(), z.array(z.string())),
+	statuses: z.record(z.string(), ExecutionJobStatus).optional()
 });
 /**
 * Structured git-clone auth material. Carries everything the agent needs to
@@ -93,6 +96,8 @@ const jobDispatchSchema = z.object({
 	runPublicKey: z.string().optional(),
 	/** Plain outputs from upstream jobs (keyed by job name, then by step name). Populated for downstream jobs with `needs` dependencies. */
 	upstreamJobOutputs: z.record(z.string(), z.record(z.string(), z.unknown())).optional(),
+	/** Terminal status of each upstream job (keyed by job name; per-child for fan-out). Powers `ctx.needs.<job>.status`. */
+	upstreamJobStatuses: z.record(z.string(), ExecutionJobStatus).optional(),
 	/**
 	* Structured clone auth for the source repo. Preferred over `token` (which
 	* remains as a backward-compat field for same-provider GitHub App flows
@@ -638,12 +643,24 @@ const StepApprovalOutcome = z.enum([
 	"expired"
 ]);
 /**
-* Agent -> Orchestrator: a step carrying `requireApproval` is about to run and
+* Drift payload carried on a `when: 'drift'` step-approval hold. Captured from
+* the step's check/summarize: `summaryMarkdown` is the author's `summarize(drift)`
+* rendering, `drift` is the structured drift blob. Rendered in the dashboard
+* approval queue + the CLI so the operator sees the computed diff before
+* approving the apply.
+*/
+const stepApprovalPayloadSchema = z.object({
+	summaryMarkdown: z.string(),
+	drift: z.unknown()
+});
+/**
+* Agent -> Orchestrator: a step carrying an `approval` gate is about to run and
 * the agent is blocking its step loop until the orchestrator resolves the
 * approval. The orchestrator creates a step-scoped `held_runs` row from the
 * normalized requirement and replies with `step.approval-resolved` once the
 * hold is approved, rejected, or expired. The agent keeps heartbeats flowing
-* during the wait so it is not reaped as stale.
+* during the wait so it is not reaped as stale. For a `when: 'drift'` gate the
+* request carries the computed drift `payload`.
 *
 * NOT fast-pathed — the `log.chunk` / `heartbeat` manual-validator invariant is
 * untouched by this message.
@@ -657,14 +674,16 @@ const stepApprovalRequestSchema = z.object({
 	stepName: z.string(),
 	/** AND-list of approver clauses (empty = any approval-capable member). */
 	clauses: z.array(approverClauseSchema),
-	/** Human label for the gate (from the SDK `requireApproval` reason). */
+	/** Human label for the gate (from the SDK `approval` reason). */
 	reason: z.string(),
 	/**
-	* Per-gate timeout override (seconds) from the SDK `requireApproval.timeout`.
+	* Per-gate timeout override (seconds) from the SDK `approval.timeout`.
 	* Absent ⇒ the orchestrator uses the org-default `approval_expiry_seconds`.
 	* The orchestrator owns the authoritative `expiresAt` computation.
 	*/
-	timeoutSeconds: z.number().int().positive().optional()
+	timeoutSeconds: z.number().int().positive().optional(),
+	/** Computed drift payload, present only for `when: 'drift'` gates. */
+	payload: stepApprovalPayloadSchema.optional()
 });
 /**
 * Orchestrator -> Agent: resolution of a step-level approval hold. `requestId`
@@ -729,6 +748,6 @@ const agentToOrchestratorMessageSchema = z.discriminatedUnion("type", [
 	stepApprovalRequestSchema
 ]);
 //#endregion
-export { CacheRefScope, JobRejectReason, StepApprovalOutcome, agentApiRequestSchema, agentApiResponseSchema, agentAuthFailureSchema, agentAuthRequestSchema, agentAuthSuccessSchema, agentLogChunkSchema, agentMetricsSchema, agentRegisterSchema, agentStatusSchema, agentStepStatusSchema, agentToOrchestratorMessageSchema, cacheUserRestoreRequestSchema, cacheUserRestoreResponseSchema, cacheUserSaveCompleteSchema, cacheUserSaveRequestSchema, cacheUserSaveResponseSchema, configAckSchema, eventEmitResponseSchema, eventEmitSchema, fleetBundleChunkSchema, fleetBundleErrorSchema, fleetLogsRequestSchema, gitAuthSchema, jobAckSchema, jobCancelSchema, jobConcurrencyAckSchema, jobConcurrencyReportSchema, jobDispatchSchema, jobRejectSchema, jobStatusSchema, orchestratorToAgentMessageSchema, provenanceUploadCompleteSchema, provenanceUploadRequestSchema, provenanceUploadResponseSchema, registerAckSchema, stepApprovalRequestSchema, stepApprovalResolvedSchema, upstreamSnapshotSchema };
+export { CacheRefScope, JobRejectReason, StepApprovalOutcome, agentApiRequestSchema, agentApiResponseSchema, agentAuthFailureSchema, agentAuthRequestSchema, agentAuthSuccessSchema, agentLogChunkSchema, agentMetricsSchema, agentRegisterSchema, agentStatusSchema, agentStepStatusSchema, agentToOrchestratorMessageSchema, cacheUserRestoreRequestSchema, cacheUserRestoreResponseSchema, cacheUserSaveCompleteSchema, cacheUserSaveRequestSchema, cacheUserSaveResponseSchema, configAckSchema, eventEmitResponseSchema, eventEmitSchema, fleetBundleChunkSchema, fleetBundleErrorSchema, fleetLogsRequestSchema, gitAuthSchema, jobAckSchema, jobCancelSchema, jobConcurrencyAckSchema, jobConcurrencyReportSchema, jobDispatchSchema, jobRejectSchema, jobStatusSchema, orchestratorToAgentMessageSchema, provenanceUploadCompleteSchema, provenanceUploadRequestSchema, provenanceUploadResponseSchema, registerAckSchema, stepApprovalPayloadSchema, stepApprovalRequestSchema, stepApprovalResolvedSchema, upstreamSnapshotSchema };
 
 //# sourceMappingURL=orchestrator-agent.js.map

package/dist/protocol/messages/peer.js

@@ -1,7 +1,7 @@
 import "../../chunk-BTugEXQM.js";
 import { ExecutionJobStatus } from "./execution-status.js";
-import { ScalerEventType } from "./scaler-event.js";
 import { LabelMatcher } from "../../labels-match.js";
+import { ScalerEventType } from "./scaler-event.js";
 import { z } from "zod";
 //#region src/protocol/messages/peer.ts
 /** Agent summary included in peer heartbeat and auth response messages. */