@oisincoveney/pipeline 1.11.3 → 1.13.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/config.d.ts

@@ -231,10 +231,10 @@ declare const configSchema: z.ZodObject<{
     }, z.core.$strict>>;
     output: z.ZodOptional<z.ZodObject<{
       format: z.ZodEnum<{
-        json_schema: "json_schema";
         text: "text";
         json: "json";
         jsonl: "jsonl";
+        json_schema: "json_schema";
       }>;
       repair: z.ZodOptional<z.ZodObject<{
         enabled: z.ZodOptional<z.ZodBoolean>;
@@ -274,10 +274,10 @@ declare const configSchema: z.ZodObject<{
         disabled: "disabled";
       }>>>;
       output_formats: z.ZodOptional<z.ZodArray<z.ZodEnum<{
-        json_schema: "json_schema";
         text: "text";
         json: "json";
         jsonl: "jsonl";
+        json_schema: "json_schema";
       }>>>;
       rules: z.ZodOptional<z.ZodBoolean>;
       skills: z.ZodOptional<z.ZodBoolean>;

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/pipeline-init.js

@@ -734,6 +734,7 @@ const SCAFFOLD_FILES = {
 		"",
 		"Use the provided backlog work units as the source of truth when present. Assign each work unit to explicit generated agent nodes with only its `task_context.id`, use only allowed configured profiles, and ensure implementation work has downstream acceptance, verification, or review coverage. Do not invent profiles or node-level skill overrides.",
 		"Do not copy backlog descriptions or acceptance criteria into output; the scheduler hydrates them from the assigned `task_context.id` after parsing.",
+		"Preserve Backlog dependency ids as schedule needs edges. A node assigned a dependent work unit must depend on the nodes assigned its prerequisite work units, directly or through an explicit path.",
 		"",
 		"Shape the graph by intent, not by ticket count. Do not create a full RED/GREEN/ACCEPTANCE/VERIFY chain for each backlog ticket unless each step needs ticket-specific evidence. Use one RED node for a group of tickets when they share a test strategy, fan out to parallel GREEN implementation nodes where the work can be implemented independently, and fan back in to shared acceptance or verifier nodes when the same acceptance checklist or real repository commands prove the group. Only serialize ticket nodes when the backlog, a shared migration/schema/API dependency, or implementation risk requires it.",
 		"",

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/dist/schedule-planner.js

@@ -372,6 +372,7 @@ function plannerPrompt(entrypointId, task, baseline, config, planningContext) {
 		"Assign each backlog work unit to explicit generated agent nodes with task_context.id. The scheduler hydrates title, description, and acceptance_criteria after parsing.",
 		"Do not copy backlog descriptions or acceptance criteria into task_context output.",
 		"Implementation work must have downstream acceptance, verification, or review coverage in the generated DAG.",
+		"Preserve Backlog dependency ids as schedule needs edges. A node assigned a dependent work unit must depend on the nodes assigned its prerequisite work units, directly or through an explicit path.",
 		"Shape the graph by intent, not by ticket count. Do not create a full RED/GREEN/ACCEPTANCE/VERIFY chain for each backlog ticket unless each step needs ticket-specific evidence.",
 		"Use one RED node for a group of tickets when they share a test strategy, then fan out to parallel GREEN implementation nodes where the work can be implemented independently.",
 		"Use one acceptance or verifier node for multiple GREEN nodes when the same acceptance checklist or real repository commands prove the group.",
@@ -402,6 +403,7 @@ function validateScheduleArtifact(config, artifact, planningContext) {
 		...workflowReferenceNodeIssues(artifact),
 		...workflowAssignedWorkUnitIssues(artifact, planningContext.workUnits),
 		...missingAssignedWorkUnitIssues(artifact, planningContext.workUnits),
+		...workUnitDependencyIssues(artifact, planningContext.workUnits),
 		...invalidWorkflowPrimitiveIssues(config, artifact),
 		...implementationCoverageIssues(artifact)
 	];
@@ -464,6 +466,47 @@ function missingAssignedWorkUnitIssues(artifact, workUnits) {
 	const missing = workUnits.map((unit) => unit.id).filter((id) => !assigned.has(id));
 	return missing.length > 0 ? [`missing assigned backlog work units: ${missing.join(", ")}`] : [];
 }
+function workUnitDependencyIssues(artifact, workUnits) {
+	if (workUnits.length === 0) return [];
+	const workUnitIds = new Set(workUnits.map((unit) => unit.id));
+	const dependenciesByUnit = new Map(workUnits.map((unit) => [unit.id, (unit.dependencies ?? []).filter((id) => workUnitIds.has(id))]));
+	return Object.entries(artifact.workflows).flatMap(([workflowId, workflow]) => {
+		const nodes = workflow.nodes.flatMap(flattenWorkflowNode);
+		const dependentsByNeed = workflowDependentsByNeed(nodes);
+		const nodesByWorkUnit = nodesByAssignedWorkUnit(nodes);
+		return nodes.filter(isImplementationNode).flatMap((node) => {
+			const dependentId = node.task_context?.id;
+			if (!dependentId) return [];
+			return (dependenciesByUnit.get(dependentId) ?? []).flatMap((prerequisiteId) => {
+				const prerequisiteNodes = nodesByWorkUnit.get(prerequisiteId) ?? [];
+				return prerequisiteNodes.some((source) => hasPathToNode(source.id, node.id, dependentsByNeed)) ? [] : [`work unit dependency edge missing in '${workflowId}': '${dependentId}' node '${node.id}' must depend on prerequisite '${prerequisiteId}' nodes ${prerequisiteNodes.map((prerequisite) => `'${prerequisite.id}'`).join(", ")}`];
+			});
+		});
+	});
+}
+function nodesByAssignedWorkUnit(nodes) {
+	const grouped = /* @__PURE__ */ new Map();
+	for (const node of nodes) {
+		const id = node.task_context?.id;
+		if (!id) continue;
+		const current = grouped.get(id) ?? [];
+		current.push(node);
+		grouped.set(id, current);
+	}
+	return grouped;
+}
+function hasPathToNode(sourceId, targetId, dependentsByNeed) {
+	const queue = [...dependentsByNeed.get(sourceId) ?? []];
+	const seen = /* @__PURE__ */ new Set();
+	while (queue.length > 0) {
+		const node = queue.shift();
+		if (!node || seen.has(node.id)) continue;
+		if (node.id === targetId) return true;
+		seen.add(node.id);
+		queue.push(...dependentsByNeed.get(node.id) ?? []);
+	}
+	return false;
+}
 function invalidWorkflowPrimitiveIssues(config, artifact) {
 	const allowed = new Set(Object.keys(config.workflows));
 	return allWorkflowNodes(artifact.workflows).flatMap((node) => {
@@ -543,6 +586,7 @@ function readBacklogTaskFile(path) {
 		parentTaskId: stringFrontmatter(parsed.data.parent_task_id),
 		workUnit: {
 			acceptance_criteria: acceptanceCriteriaFromMarkdown(parsed.content),
+			...optionalStringArrayField("dependencies", stringArrayFrontmatter(parsed.data.dependencies)),
 			...optionalStringField("description", descriptionFromMarkdown(parsed.content)),
 			id,
 			...optionalStringField("title", stringFrontmatter(parsed.data.title))
@@ -552,9 +596,16 @@ function readBacklogTaskFile(path) {
 function stringFrontmatter(value) {
 	return typeof value === "string" && value.trim() ? value.trim() : void 0;
 }
+function stringArrayFrontmatter(value) {
+	if (!Array.isArray(value)) return [];
+	return value.filter((item) => typeof item === "string").map((item) => item.trim()).filter(Boolean);
+}
 function optionalStringField(key, value) {
 	return value ? { [key]: value } : {};
 }
+function optionalStringArrayField(key, value) {
+	return value.length > 0 ? { [key]: value } : {};
+}
 function descriptionFromMarkdown(content) {
 	const marked = betweenMarkers(content, "<!-- SECTION:DESCRIPTION:BEGIN -->", "<!-- SECTION:DESCRIPTION:END -->");
 	if (marked) return marked;

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.13.0",
   "description": "Config-driven multi-agent pipeline runner for repository work",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",