@oisincoveney/pipeline 1.11.3 → 1.12.0

package/README.md

@@ -128,6 +128,9 @@ flushing.
 The console starts the image with `OISIN_PIPELINE_RUNNER_PAYLOAD_JSON` and the
 runner-side event token. The payload contract is documented in
 [`docs/pipeline-console-runner-contract.md`](docs/pipeline-console-runner-contract.md).
+The executable contract is exported from
+`@oisincoveney/pipeline/runner-job-contract` for payload construction,
+validation, contract-version checks, and JSON Schema generation.
 Use `PIPELINE_TARGET_PATH=/path/to/worktree` when the checked-out target repo is
 mounted somewhere other than the process working directory.
 
@@ -374,6 +377,17 @@ import {
 } from "@oisincoveney/pipeline/runtime";
 ```
 
+Runner Job producers can import the shared payload contract:
+
+```ts
+import {
+  RUNNER_JOB_CONTRACT_VERSION,
+  buildRunnerJobPayload,
+  parseRunnerJobPayload,
+  runnerJobPayloadJsonSchema,
+} from "@oisincoveney/pipeline/runner-job-contract";
+```
+
 ## Verification
 
 Use these commands before committing changes in this repository:

package/dist/kubernetes-runner.js

@@ -1,6 +1,6 @@
 import { PipelineConfigError } from "./config.js";
 import { runPipelineFromConfig } from "./pipeline-runtime.js";
-import { RUNNER_PAYLOAD_ENV, parseRunnerJobPayload, resolveRunnerEventSinkAuthToken } from "./runner-job-contract.js";
+import { RUNNER_PAYLOAD_ENV, parseRunnerJobPayloadWithIssues, resolveRunnerEventSinkAuthToken } from "./runner-job-contract.js";
 import { createRunnerEventSink } from "./runner-event-sink.js";
 //#region src/kubernetes-runner.ts
 const EXIT_PASS = 0;
@@ -11,6 +11,7 @@ const EXIT_STARTUP = 70;
 async function runKubernetesRunnerJob(options = {}) {
 	const prepared = prepareRunnerJob(options);
 	if (prepared.exitCode !== void 0) return prepared.exitCode;
+	if ("validationFailure" in prepared) return reportPreparedValidationFailure(prepared.validationFailure, options);
 	const { authToken, env, payload, stderr } = prepared.job;
 	const controller = new AbortController();
 	const signalEmitter = options.signalEmitter ?? process;
@@ -51,6 +52,7 @@ async function runKubernetesRunnerJob(options = {}) {
 			runId: payload.run.runId,
 			signal: controller.signal,
 			task: payload.task.prompt,
+			hookPolicy: { allowCommandHooks: payload.selector.allowCommandHooks },
 			workflowId: payload.selector.workflowId,
 			worktreePath: env.PIPELINE_TARGET_PATH ?? options.cwd ?? process.cwd()
 		});
@@ -77,24 +79,40 @@ function prepareRunnerJob(options) {
 		return { exitCode: EXIT_VALIDATION };
 	}
 	const payload = parsePayload(payloadRaw, stderr);
-	if (!payload) return { exitCode: EXIT_VALIDATION };
+	if (!payload.ok) return { validationFailure: {
+		authToken: resolveAuthToken(env, stderr) ?? void 0,
+		env,
+		error: payload.error,
+		recoverable: payload.recoverable,
+		stderr
+	} };
 	const authToken = resolveAuthToken(env, stderr);
 	if (!authToken) return { exitCode: EXIT_VALIDATION };
 	return { job: {
 		authToken,
 		env,
-		payload,
+		payload: payload.payload,
 		stderr
 	} };
 }
 function parsePayload(payloadRaw, stderr) {
-	try {
-		return parseRunnerJobPayload(payloadRaw);
-	} catch (err) {
-		const message = err instanceof Error ? err.message : String(err);
-		stderr.write(`${message}\n`);
-		return null;
+	const result = parseRunnerJobPayloadWithIssues(payloadRaw);
+	if (!result.ok) stderr.write(`${result.error.message}\n`);
+	return result;
+}
+async function reportPreparedValidationFailure(failure, options) {
+	if (failure.recoverable && failure.authToken) {
+		const sink = createRunnerEventSink({
+			authHeader: failure.recoverable.eventSink.authHeader,
+			authToken: failure.authToken,
+			fetch: options.fetch,
+			runId: failure.recoverable.run.runId,
+			url: failure.recoverable.eventSink.url
+		});
+		sink.recordSchemaValidationFailure(failure.error.message, failure.error.issues, failure.recoverable.workflowId);
+		await flushAndReport(sink.flush, failure.stderr);
 	}
+	return EXIT_VALIDATION;
 }
 function resolveAuthToken(env, stderr) {
 	try {

package/dist/runner-event-sink.js

@@ -87,7 +87,27 @@ function createRunnerEventSink(options) {
 				workflowId
 			});
 		},
-		recordRuntimeEvent
+		recordRuntimeEvent,
+		recordSchemaValidationFailure(message, issues, workflowId) {
+			queue.push({
+				...nextEnvelope(),
+				log: {
+					level: "warn",
+					message: `Runner payload schema validation failed: ${message}`,
+					output: { issues },
+					workflowId
+				},
+				type: "runner.schema.validation"
+			});
+			queue.push({
+				...nextEnvelope(),
+				finalResult: {
+					outcome: "FAIL",
+					workflowId
+				},
+				type: "workflow.finish"
+			});
+		}
 	};
 }
 async function postBatch(options, fetchImpl, events) {

package/dist/runner-job-contract.d.ts

@@ -0,0 +1,281 @@
+import { PipelineRuntimeEvent } from "./pipeline-runtime.js";
+import { z } from "zod";
+
+//#region src/runner-job-contract.d.ts
+declare const RUNNER_PAYLOAD_ENV = "OISIN_PIPELINE_RUNNER_PAYLOAD_JSON";
+declare const RUNNER_JOB_CONTRACT_VERSION = "1";
+declare const runnerEventSinkConfigSchema: z.ZodObject<{
+  authHeader: z.ZodString;
+  url: z.ZodString;
+}, z.core.$strict>;
+declare const runnerRunIdentitySchema: z.ZodObject<{
+  projectId: z.ZodString;
+  requestedBy: z.ZodOptional<z.ZodString>;
+  runId: z.ZodString;
+}, z.core.$strict>;
+declare const runnerWorkflowSelectorSchema: z.ZodObject<{
+  allowCommandHooks: z.ZodDefault<z.ZodBoolean>;
+  workflowId: z.ZodString;
+}, z.core.$strict>;
+declare const runnerTaskPromptSchema: z.ZodObject<{
+  filePath: z.ZodOptional<z.ZodString>;
+  githubUrl: z.ZodOptional<z.ZodString>;
+  prompt: z.ZodString;
+  taskId: z.ZodString;
+  title: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+declare const runnerRepositoryContextSchema: z.ZodObject<{
+  branch: z.ZodString;
+  cloneUrl: z.ZodString;
+  fullName: z.ZodString;
+  owner: z.ZodString;
+  repo: z.ZodString;
+  sha: z.ZodString;
+}, z.core.$strict>;
+declare const runnerMomokayaContextSchema: z.ZodObject<{
+  automationNamespace: z.ZodOptional<z.ZodString>;
+  previewEnabled: z.ZodBoolean;
+  repoKey: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+declare const runnerJobPayloadSchema: z.ZodObject<{
+  contractVersion: z.ZodDefault<z.ZodLiteral<"1">>;
+  eventSink: z.ZodObject<{
+    authHeader: z.ZodString;
+    url: z.ZodString;
+  }, z.core.$strict>;
+  momokaya: z.ZodOptional<z.ZodObject<{
+    automationNamespace: z.ZodOptional<z.ZodString>;
+    previewEnabled: z.ZodBoolean;
+    repoKey: z.ZodOptional<z.ZodString>;
+  }, z.core.$strict>>;
+  repository: z.ZodOptional<z.ZodObject<{
+    branch: z.ZodString;
+    cloneUrl: z.ZodString;
+    fullName: z.ZodString;
+    owner: z.ZodString;
+    repo: z.ZodString;
+    sha: z.ZodString;
+  }, z.core.$strict>>;
+  run: z.ZodObject<{
+    projectId: z.ZodString;
+    requestedBy: z.ZodOptional<z.ZodString>;
+    runId: z.ZodString;
+  }, z.core.$strict>;
+  selector: z.ZodObject<{
+    allowCommandHooks: z.ZodDefault<z.ZodBoolean>;
+    workflowId: z.ZodString;
+  }, z.core.$strict>;
+  task: z.ZodObject<{
+    filePath: z.ZodOptional<z.ZodString>;
+    githubUrl: z.ZodOptional<z.ZodString>;
+    prompt: z.ZodString;
+    taskId: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+  }, z.core.$strict>;
+}, z.core.$strict>;
+type RunnerEventSinkConfig = z.infer<typeof runnerEventSinkConfigSchema>;
+type RunnerJobPayload = z.infer<typeof runnerJobPayloadSchema>;
+type RunnerMomokayaContext = z.infer<typeof runnerMomokayaContextSchema>;
+type RunnerRepositoryContext = z.infer<typeof runnerRepositoryContextSchema>;
+type RunnerRunIdentity = z.infer<typeof runnerRunIdentitySchema>;
+type RunnerTaskPrompt = z.infer<typeof runnerTaskPromptSchema>;
+type RunnerWorkflowSelector = z.infer<typeof runnerWorkflowSelectorSchema>;
+declare const runnerJobPayloadJsonSchema: z.core.ZodStandardJSONSchemaPayload<z.ZodObject<{
+  contractVersion: z.ZodDefault<z.ZodLiteral<"1">>;
+  eventSink: z.ZodObject<{
+    authHeader: z.ZodString;
+    url: z.ZodString;
+  }, z.core.$strict>;
+  momokaya: z.ZodOptional<z.ZodObject<{
+    automationNamespace: z.ZodOptional<z.ZodString>;
+    previewEnabled: z.ZodBoolean;
+    repoKey: z.ZodOptional<z.ZodString>;
+  }, z.core.$strict>>;
+  repository: z.ZodOptional<z.ZodObject<{
+    branch: z.ZodString;
+    cloneUrl: z.ZodString;
+    fullName: z.ZodString;
+    owner: z.ZodString;
+    repo: z.ZodString;
+    sha: z.ZodString;
+  }, z.core.$strict>>;
+  run: z.ZodObject<{
+    projectId: z.ZodString;
+    requestedBy: z.ZodOptional<z.ZodString>;
+    runId: z.ZodString;
+  }, z.core.$strict>;
+  selector: z.ZodObject<{
+    allowCommandHooks: z.ZodDefault<z.ZodBoolean>;
+    workflowId: z.ZodString;
+  }, z.core.$strict>;
+  task: z.ZodObject<{
+    filePath: z.ZodOptional<z.ZodString>;
+    githubUrl: z.ZodOptional<z.ZodString>;
+    prompt: z.ZodString;
+    taskId: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+  }, z.core.$strict>;
+}, z.core.$strict>>;
+interface RunnerJobPayloadValidationIssue {
+  code: string;
+  message: string;
+  path: string;
+}
+interface RecoverableRunnerJobPayloadEnvelope {
+  eventSink: RunnerEventSinkConfig;
+  run: RunnerRunIdentity;
+  workflowId: string;
+}
+declare class RunnerJobPayloadValidationError extends Error {
+  readonly issues: RunnerJobPayloadValidationIssue[];
+  constructor(message: string, issues: RunnerJobPayloadValidationIssue[]);
+}
+type RunnerJobPayloadParseResult = {
+  ok: true;
+  payload: RunnerJobPayload;
+} | {
+  error: RunnerJobPayloadValidationError;
+  ok: false;
+  recoverable?: RecoverableRunnerJobPayloadEnvelope;
+};
+interface BuildRunnerJobPayloadOptions {
+  allowCommandHooks?: boolean;
+  eventSink: RunnerEventSinkConfig;
+  momokaya?: RunnerMomokayaContext;
+  repository?: RunnerRepositoryContext;
+  run: RunnerRunIdentity;
+  task: RunnerTaskPrompt;
+  workflowId: string;
+}
+interface CreateRunnerJobPayloadEnvOptions {
+  allowCommandHooks?: boolean;
+  eventSinkUrl: string;
+  projectId: string;
+  requestedBy?: string;
+  runId: string;
+  taskId: string;
+  taskPrompt: string;
+  workflowId: string;
+}
+interface ResolveRunnerEventSinkAuthTokenOptions {
+  env?: Record<string, string | undefined>;
+  serviceAccountTokenPath?: string;
+}
+interface RunnerEventMappingContext {
+  runId: string;
+  sequence?: number;
+  timestamp: string;
+}
+interface RunnerWorkflowNodeDetails {
+  id: string;
+  kind: string;
+  needs: string[];
+  profile?: string;
+  runnerId?: string;
+}
+interface RunnerWorkflowEdgeDetails {
+  source: string;
+  target: string;
+}
+interface RunnerWorkflowPlanDetails {
+  edges?: RunnerWorkflowEdgeDetails[];
+  nodeIds?: string[];
+  nodes?: RunnerWorkflowNodeDetails[];
+  workflowId: string;
+}
+interface RunnerWorkflowEdgeRecordDetails {
+  id: string;
+  source: string;
+  target: string;
+}
+type RunnerNodeStatus = "agent-finished" | "agent-running" | "failed" | "passed" | "running";
+interface RunnerNodeDetails {
+  attempt: number;
+  exitCode?: number;
+  nodeId: string;
+  profile?: string;
+  runnerId?: string;
+  status: RunnerNodeStatus;
+}
+type RunnerGateStatus = "failed" | "passed" | "running";
+interface RunnerGateDetails {
+  event?: string;
+  evidence?: string[];
+  gateId?: string;
+  hookId?: string;
+  kind?: string;
+  label?: string;
+  nodeId?: string;
+  passed?: boolean;
+  reason?: string;
+  required?: boolean;
+  status: RunnerGateStatus;
+  workflowId?: string;
+}
+type RunnerArtifactStatus = "failed" | "passed" | "running";
+interface RunnerArtifactDetails {
+  kind: "artifact";
+  label: string;
+  nodeId: string;
+  passed?: boolean;
+  path: string;
+  reason?: string;
+  required: boolean;
+  status: RunnerArtifactStatus;
+  uri: string;
+}
+type RunnerLogLevel = "info" | "warn";
+interface RunnerLogDetails {
+  attempt?: number;
+  format?: string;
+  level: RunnerLogLevel;
+  message: string;
+  nodeId?: string;
+  output?: unknown;
+  passed?: boolean;
+  reason?: string;
+  workflowId?: string;
+}
+interface RunnerFinalResultDetails {
+  outcome: "CANCELLED" | "FAIL" | "PASS";
+  workflowId: string;
+}
+interface RunnerEventEnvelope {
+  at?: string;
+  sequence: number;
+  type: string;
+}
+type RunnerEventRecord = (RunnerEventEnvelope & {
+  type: "workflow.planned" | "workflow.start";
+  workflowPlan: RunnerWorkflowPlanDetails;
+}) | (RunnerEventEnvelope & {
+  edge: RunnerWorkflowEdgeRecordDetails;
+  type: "workflow.edge";
+}) | (RunnerEventEnvelope & {
+  node: RunnerNodeDetails;
+  type: "agent.finish" | "agent.start" | "node.finish" | "node.start";
+}) | (RunnerEventEnvelope & {
+  gate: RunnerGateDetails;
+  type: "gate.finish" | "gate.start" | "hook.finish" | "hook.start";
+}) | (RunnerEventEnvelope & {
+  artifact: RunnerArtifactDetails;
+  type: "artifact.check.finish" | "artifact.check.start";
+}) | (RunnerEventEnvelope & {
+  log: RunnerLogDetails;
+  type: "node.output.recorded" | "output.repair" | "run.cancelled" | "runner.schema.validation" | "runtime.observability";
+}) | (RunnerEventEnvelope & {
+  finalResult: RunnerFinalResultDetails;
+  type: "workflow.finish";
+});
+declare function resolveRunnerEventSinkAuthToken(options?: ResolveRunnerEventSinkAuthTokenOptions): string;
+declare function resolveRunnerEventSinkAuthHeader(options?: ResolveRunnerEventSinkAuthTokenOptions): string;
+declare function createRunnerJobPayloadEnv(options: CreateRunnerJobPayloadEnvOptions): {
+  name: typeof RUNNER_PAYLOAD_ENV;
+  value: string;
+};
+declare function buildRunnerJobPayload(options: BuildRunnerJobPayloadOptions): RunnerJobPayload;
+declare function parseRunnerJobPayload(rawPayload: string): RunnerJobPayload;
+declare function parseRunnerJobPayloadWithIssues(rawPayload: string): RunnerJobPayloadParseResult;
+declare function mapRuntimeEventToRunnerEventRecords(event: PipelineRuntimeEvent, context: RunnerEventMappingContext): RunnerEventRecord[];
+//#endregion
+export { BuildRunnerJobPayloadOptions, CreateRunnerJobPayloadEnvOptions, RUNNER_JOB_CONTRACT_VERSION, RUNNER_PAYLOAD_ENV, RecoverableRunnerJobPayloadEnvelope, ResolveRunnerEventSinkAuthTokenOptions, RunnerArtifactDetails, RunnerArtifactStatus, RunnerEventMappingContext, RunnerEventRecord, RunnerEventSinkConfig, RunnerFinalResultDetails, RunnerGateDetails, RunnerGateStatus, RunnerJobPayload, RunnerJobPayloadParseResult, RunnerJobPayloadValidationError, RunnerJobPayloadValidationIssue, RunnerLogDetails, RunnerLogLevel, RunnerMomokayaContext, RunnerNodeDetails, RunnerNodeStatus, RunnerRepositoryContext, RunnerRunIdentity, RunnerTaskPrompt, RunnerWorkflowEdgeDetails, RunnerWorkflowEdgeRecordDetails, RunnerWorkflowNodeDetails, RunnerWorkflowPlanDetails, RunnerWorkflowSelector, buildRunnerJobPayload, createRunnerJobPayloadEnv, mapRuntimeEventToRunnerEventRecords, parseRunnerJobPayload, parseRunnerJobPayloadWithIssues, resolveRunnerEventSinkAuthHeader, resolveRunnerEventSinkAuthToken, runnerEventSinkConfigSchema, runnerJobPayloadJsonSchema, runnerJobPayloadSchema, runnerMomokayaContextSchema, runnerRepositoryContextSchema, runnerRunIdentitySchema, runnerTaskPromptSchema, runnerWorkflowSelectorSchema };

package/dist/runner-job-contract.js

@@ -3,6 +3,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { z } from "zod";
 //#region src/runner-job-contract.ts
 const RUNNER_PAYLOAD_ENV = "OISIN_PIPELINE_RUNNER_PAYLOAD_JSON";
+const RUNNER_JOB_CONTRACT_VERSION = "1";
 const runnerEventSinkConfigSchema = z.object({
 	authHeader: z.string().min(1),
 	url: z.string().url()
@@ -12,17 +13,48 @@ const runnerRunIdentitySchema = z.object({
 	requestedBy: z.string().min(1).optional(),
 	runId: z.string().min(1)
 }).strict();
-const runnerWorkflowSelectorSchema = z.object({ workflowId: z.string().min(1) }).strict();
+const runnerWorkflowSelectorSchema = z.object({
+	allowCommandHooks: z.boolean().default(true),
+	workflowId: z.string().min(1)
+}).strict();
 const runnerTaskPromptSchema = z.object({
+	filePath: z.string().min(1).optional(),
+	githubUrl: z.string().url().optional(),
 	prompt: z.string().min(1),
-	taskId: z.string().min(1)
+	taskId: z.string().min(1),
+	title: z.string().min(1).optional()
+}).strict();
+const runnerRepositoryContextSchema = z.object({
+	branch: z.string().min(1),
+	cloneUrl: z.string().url(),
+	fullName: z.string().min(1),
+	owner: z.string().min(1),
+	repo: z.string().min(1),
+	sha: z.string().min(1)
+}).strict();
+const runnerMomokayaContextSchema = z.object({
+	automationNamespace: z.string().min(1).optional(),
+	previewEnabled: z.boolean(),
+	repoKey: z.string().min(1).optional()
 }).strict();
 const runnerJobPayloadSchema = z.object({
+	contractVersion: z.literal("1", { error: "runner job payload contract version must be 1" }).default("1"),
 	eventSink: runnerEventSinkConfigSchema,
+	momokaya: runnerMomokayaContextSchema.optional(),
+	repository: runnerRepositoryContextSchema.optional(),
 	run: runnerRunIdentitySchema,
 	selector: runnerWorkflowSelectorSchema,
 	task: runnerTaskPromptSchema
 }).strict();
+const runnerJobPayloadJsonSchema = z.toJSONSchema(runnerJobPayloadSchema);
+var RunnerJobPayloadValidationError = class extends Error {
+	issues;
+	constructor(message, issues) {
+		super(message);
+		this.name = "RunnerJobPayloadValidationError";
+		this.issues = issues;
+	}
+};
 const EVENT_AUTH_TOKEN_ENV_KEYS = ["OISIN_PIPELINE_EVENT_AUTH_TOKEN", "PIPELINE_EVENT_API_TOKEN"];
 const DEFAULT_SERVICE_ACCOUNT_TOKEN_PATH = "/var/run/secrets/kubernetes.io/serviceaccount/token";
 function resolveRunnerEventSinkAuthToken(options = {}) {
@@ -38,17 +70,79 @@ function resolveRunnerEventSinkAuthToken(options = {}) {
 	}
 	throw new Error(`Runner event auth token is required. Set ${EVENT_AUTH_TOKEN_ENV_KEYS.join(" or ")}, or mount a readable Kubernetes service account token at ${tokenPath}.`);
 }
+function resolveRunnerEventSinkAuthHeader(options = {}) {
+	return `Bearer ${resolveRunnerEventSinkAuthToken(options)}`;
+}
+function createRunnerJobPayloadEnv(options) {
+	const payload = buildRunnerJobPayload({
+		eventSink: {
+			authHeader: "Authorization",
+			url: options.eventSinkUrl
+		},
+		run: {
+			projectId: options.projectId,
+			requestedBy: options.requestedBy,
+			runId: options.runId
+		},
+		allowCommandHooks: options.allowCommandHooks,
+		task: {
+			prompt: options.taskPrompt,
+			taskId: options.taskId
+		},
+		workflowId: options.workflowId
+	});
+	return {
+		name: RUNNER_PAYLOAD_ENV,
+		value: JSON.stringify(payload)
+	};
+}
+function buildRunnerJobPayload(options) {
+	return runnerJobPayloadSchema.parse({
+		contractVersion: "1",
+		eventSink: options.eventSink,
+		momokaya: options.momokaya,
+		repository: options.repository,
+		run: options.run,
+		selector: {
+			allowCommandHooks: options.allowCommandHooks ?? true,
+			workflowId: options.workflowId
+		},
+		task: options.task
+	});
+}
 function parseRunnerJobPayload(rawPayload) {
+	const result = parseRunnerJobPayloadWithIssues(rawPayload);
+	if (!result.ok) throw result.error;
+	return result.payload;
+}
+function parseRunnerJobPayloadWithIssues(rawPayload) {
 	let parsed;
 	try {
 		parsed = parseJson(rawPayload, "runner payload JSON");
 	} catch (err) {
 		const message = err instanceof Error ? err.message : String(err);
-		throw new Error(`Malformed runner payload JSON: ${message}`);
+		return {
+			error: new RunnerJobPayloadValidationError(`Malformed runner payload JSON: ${message}`, [{
+				code: "invalid_json",
+				message,
+				path: "payload"
+			}]),
+			ok: false
+		};
 	}
 	const result = runnerJobPayloadSchema.safeParse(parsed);
-	if (!result.success) throw new Error(formatRunnerJobPayloadIssues(result.error, parsed));
-	return result.data;
+	if (!result.success) {
+		const issues = runnerJobPayloadIssues(result.error);
+		return {
+			error: new RunnerJobPayloadValidationError(formatRunnerJobPayloadIssues(issues, parsed), issues),
+			ok: false,
+			...recoverablePayloadEnvelope(parsed)
+		};
+	}
+	return {
+		ok: true,
+		payload: result.data
+	};
 }
 function mapRuntimeEventToRunnerEventRecords(event, context) {
 	const record = {
@@ -261,15 +355,53 @@ function formatLogMessage(output) {
 		return String(output);
 	}
 }
-function formatRunnerJobPayloadIssues(error, payload) {
+function formatRunnerJobPayloadIssues(issues, payload) {
 	const selector = readRecord(readRecord(payload)?.selector);
 	if (selector && !("workflowId" in selector) && Object.keys(selector).length > 0) return `Unsupported selector fields: ${Object.keys(selector).join(", ")}; selector.workflowId is required`;
-	return error.issues.map((issue) => {
+	return issues.map((issue) => `${issue.path || "payload"}: ${issue.message}`).join("; ");
+}
+function runnerJobPayloadIssues(error) {
+	return error.issues.flatMap((issue) => {
 		const path = issue.path.join(".");
-		if (issue.code === "invalid_type" && issue.input === void 0) return `${path || "payload"} is required`;
-		if (path === "eventSink.url") return "eventSink.url must be a valid URL";
-		return `${path || "payload"}: ${issue.message}`;
-	}).join("; ");
+		if (issue.code === "unrecognized_keys" && Array.isArray(issue.keys)) return issue.keys.map((key) => ({
+			code: issue.code,
+			message: "Unrecognized key",
+			path: [path, key].filter(Boolean).join(".")
+		}));
+		if (issue.code === "invalid_type" && issue.input === void 0) return [{
+			code: issue.code,
+			message: "is required",
+			path: path || "payload"
+		}];
+		if (path === "eventSink.url") return [{
+			code: issue.code,
+			message: "must be a valid URL",
+			path
+		}];
+		if (path === "contractVersion") return [{
+			code: issue.code,
+			message: `runner job payload contract version must be 1`,
+			path
+		}];
+		return [{
+			code: issue.code,
+			message: issue.message,
+			path: path || "payload"
+		}];
+	});
+}
+function recoverablePayloadEnvelope(payload) {
+	const envelope = readRecord(payload);
+	if (!envelope) return {};
+	const eventSink = runnerEventSinkConfigSchema.safeParse(envelope.eventSink);
+	const run = runnerRunIdentitySchema.safeParse(envelope.run);
+	const workflowId = readRecord(envelope.selector)?.workflowId;
+	if (!(eventSink.success && run.success && typeof workflowId === "string")) return {};
+	return { recoverable: {
+		eventSink: eventSink.data,
+		run: run.data,
+		workflowId
+	} };
 }
 function omitUndefined(value) {
 	return Object.fromEntries(Object.entries(value).filter(([, item]) => item !== void 0));
@@ -281,4 +413,4 @@ function assertNever(value) {
 	throw new Error(`Unhandled runtime event: ${String(value)}`);
 }
 //#endregion
-export { RUNNER_PAYLOAD_ENV, mapRuntimeEventToRunnerEventRecords, parseRunnerJobPayload, resolveRunnerEventSinkAuthToken };
+export { RUNNER_JOB_CONTRACT_VERSION, RUNNER_PAYLOAD_ENV, RunnerJobPayloadValidationError, buildRunnerJobPayload, createRunnerJobPayloadEnv, mapRuntimeEventToRunnerEventRecords, parseRunnerJobPayload, parseRunnerJobPayloadWithIssues, resolveRunnerEventSinkAuthHeader, resolveRunnerEventSinkAuthToken, runnerEventSinkConfigSchema, runnerJobPayloadJsonSchema, runnerJobPayloadSchema, runnerMomokayaContextSchema, runnerRepositoryContextSchema, runnerRunIdentitySchema, runnerTaskPromptSchema, runnerWorkflowSelectorSchema };

package/docs/operator-guide.md

@@ -133,7 +133,7 @@ Local dry run:
 ```shell
 export PIPELINE_TARGET_PATH=/path/to/target/repo
 export OISIN_PIPELINE_EVENT_AUTH_TOKEN=dev-token
-export OISIN_PIPELINE_RUNNER_PAYLOAD_JSON='{"eventSink":{"authHeader":"Authorization","url":"http://127.0.0.1:3000/api/pipeline/runs/run-uid-1/events"},"run":{"projectId":"alpha","requestedBy":"@agent","runId":"run-uid-1"},"selector":{"workflowId":"default"},"task":{"prompt":"PIPE-38","taskId":"PIPE-38"}}'
+export OISIN_PIPELINE_RUNNER_PAYLOAD_JSON='{"contractVersion":"1","eventSink":{"authHeader":"Authorization","url":"http://127.0.0.1:3000/api/pipeline/runs/run-uid-1/events"},"run":{"projectId":"alpha","requestedBy":"@agent","runId":"run-uid-1"},"selector":{"allowCommandHooks":true,"workflowId":"default"},"task":{"prompt":"PIPE-38","taskId":"PIPE-38"}}'
 pipe runner-job
 ```
 
@@ -161,7 +161,7 @@ spec:
           image: ghcr.io/oisin-ee/pipeline-runner:latest
           env:
             - name: OISIN_PIPELINE_RUNNER_PAYLOAD_JSON
-              value: '{"eventSink":{"authHeader":"Authorization","url":"https://console.example/api/pipeline/runs/run-uid-1/events"},"run":{"projectId":"alpha","runId":"run-uid-1"},"selector":{"workflowId":"default"},"task":{"prompt":"PIPE-38","taskId":"PIPE-38"}}'
+              value: '{"contractVersion":"1","eventSink":{"authHeader":"Authorization","url":"https://console.example/api/pipeline/runs/run-uid-1/events"},"run":{"projectId":"alpha","runId":"run-uid-1"},"selector":{"allowCommandHooks":true,"workflowId":"default"},"task":{"prompt":"PIPE-38","taskId":"PIPE-38"}}'
 ```
 
 The runner image is configured in `pipeline-console` as
@@ -171,9 +171,22 @@ event sink URL, and auth header. The runner-side
 `OISIN_PIPELINE_EVENT_AUTH_TOKEN` or `PIPELINE_EVENT_API_TOKEN` must match the
 console API `PIPELINE_EVENT_API_TOKEN`.
 
+The runner payload contract lives at
+`@oisincoveney/pipeline/runner-job-contract`. `pipeline-console` should create
+payloads with `buildRunnerJobPayload` and can use
+`runnerJobPayloadJsonSchema` for neutral validation or generated docs. The
+runner image labels `pipeline.oisin.dev.runner-contract-version` and
+`pipeline.oisin.dev.pipeline-package-version`, plus the console
+`runner.expectedContractVersion` setting and
+`pipeline.oisin.dev/runner-contract-version` Job label, give operators a fast
+way to detect image/dependency skew before starting Jobs.
+
 Troubleshooting:
 
 - Missing payload: set `OISIN_PIPELINE_RUNNER_PAYLOAD_JSON`; exit code is `64`.
+- Schema validation: unsupported selector fields or incompatible
+  `contractVersion` exit `64`; recoverable payloads also post
+  `runner.schema.validation` and a failing `workflow.finish` event.
 - Invalid auth: confirm the runner token matches the console API token; 401/403
   event sink responses are terminal.
 - Missing target config: set `PIPELINE_TARGET_PATH` to a repo containing

package/docs/pipeline-console-runner-contract.md

@@ -10,8 +10,15 @@ console database, event store, Job builder, Kueue watcher, or UI.
 `pipeline-console` starts the image with one environment variable:
 `OISIN_PIPELINE_RUNNER_PAYLOAD_JSON`.
 
+The executable payload contract lives in this package at
+`@oisincoveney/pipeline/runner-job-contract`. Console code must build runner
+payloads through `buildRunnerJobPayload` instead of hand-shaping JSON. The same
+subpath exports `parseRunnerJobPayload`, `RUNNER_JOB_CONTRACT_VERSION`, and
+`runnerJobPayloadJsonSchema` for validation, tests, and docs.
+
 ```json
 {
+  "contractVersion": "1",
   "eventSink": {
     "authHeader": "Authorization",
     "url": "https://console.example/api/pipeline/runs/run-uid-1/events"
@@ -22,6 +29,7 @@ console database, event store, Job builder, Kueue watcher, or UI.
     "runId": "run-uid-1"
   },
   "selector": {
+    "allowCommandHooks": true,
     "workflowId": "epic-drain"
   },
   "task": {
@@ -33,7 +41,19 @@ console database, event store, Job builder, Kueue watcher, or UI.
 
 `eventSink.url` is the exact append endpoint the runner posts to. The console
 resolves any requested entrypoint before creating the Job and sends
-`selector.workflowId`; the runner rejects unsupported selector modes.
+`selector.workflowId`; the runner rejects unsupported selector modes. The
+`selector.allowCommandHooks` boolean is the runner-side hook policy for command
+hooks in that job. It defaults to `true`, and console callers that disable hooks
+must send `false` through the shared builder.
+
+Payloads declare `contractVersion: "1"`. Runner images are labeled with
+`pipeline.oisin.dev.runner-contract-version` and
+`pipeline.oisin.dev.pipeline-package-version`; console deployment config records
+the expected payload contract as `runner.expectedContractVersion` and labels
+created Jobs with `pipeline.oisin.dev/runner-contract-version`. Operators should
+keep the console package dependency, console expected version, and runner image
+label version aligned. A future breaking payload change must increment the
+contract version and ship a compatibility plan.
 
 Console-created Jobs are labeled with `kueue.x-k8s.io/queue-name` and
 `pipeline.oisin.dev/project`, `pipeline.oisin.dev/run-id`,
@@ -63,6 +83,12 @@ Each event has a strictly increasing integer `sequence`, a string `type`, an
 `node`, `gate`, `artifact`, `log`, and `finalResult`. The console stores
 non-reserved top-level fields as event payload.
 
+If payload validation fails but the runner can recover the run identity and
+event sink identity, it posts a `runner.schema.validation` warning event with
+normalized issue details, then posts `workflow.finish` with outcome `FAIL`, and
+exits `64`. If identity is not recoverable, it writes the validation error to
+stderr and exits `64` without posting events.
+
 ## Authentication
 
 The payload carries the header name, not the token. The runner sets

package/package.json

@@ -62,6 +62,10 @@
       "types": "./dist/runner.d.ts",
       "import": "./dist/runner.js"
     },
+    "./runner-job-contract": {
+      "types": "./dist/runner-job-contract.d.ts",
+      "import": "./dist/runner-job-contract.js"
+    },
     "./runtime": {
       "types": "./dist/pipeline-runtime.d.ts",
       "import": "./dist/pipeline-runtime.js"
@@ -91,7 +95,7 @@
     "prepack": "bun run build:cli"
   },
   "type": "module",
-  "version": "1.11.3",
+  "version": "1.12.0",
   "description": "Config-driven multi-agent pipeline runner for repository work",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",