@oisincoveney/pipeline 1.17.0 → 1.18.1

package/dist/commands/pipeline-command.js

@@ -0,0 +1,28 @@
+//#region src/commands/pipeline-command.ts
+const BUILTIN_PIPE_COMMANDS = new Set([
+	"run",
+	"pipe",
+	"validate",
+	"explain-plan",
+	"doctor",
+	"init",
+	"install-commands",
+	"mcp",
+	"runner-job"
+]);
+function registerConfiguredEntrypointCommands(program, config, runEntrypoint) {
+	const registered = /* @__PURE__ */ new Set();
+	if (!config) return registered;
+	const reservedCommands = new Set(program.commands.map((command) => command.name()));
+	for (const [id, entrypoint] of Object.entries(config.entrypoints)) {
+		if (reservedCommands.has(id)) continue;
+		program.command(id).description(entrypoint.description ?? `Run the ${id} workflow`).argument("<description...>", "task description").action(async (descriptionParts) => {
+			await runEntrypoint(id, descriptionParts.join(" "));
+		});
+		registered.add(id);
+		reservedCommands.add(id);
+	}
+	return registered;
+}
+//#endregion
+export { BUILTIN_PIPE_COMMANDS, registerConfiguredEntrypointCommands };

package/dist/commands/runner-job-command.js

@@ -0,0 +1,10 @@
+import { runRunnerJob } from "../runner-job/run.js";
+//#region src/commands/runner-job-command.ts
+function registerRunnerJobCommand(program) {
+	program.command("runner-job").description("Run an in-pod pipeline runner job from the console payload").action(async () => {
+		const exitCode = await runRunnerJob();
+		process.exitCode = exitCode;
+	});
+}
+//#endregion
+export { registerRunnerJobCommand };

package/dist/config.d.ts

@@ -309,6 +309,20 @@ declare const configSchema: z.ZodObject<{
       task: "task";
     }>>>;
   }, z.core.$strict>>>;
+  runner_job: z.ZodDefault<z.ZodObject<{
+    environment: z.ZodDefault<z.ZodObject<{
+      setup: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        args: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        command: z.ZodString;
+        required: z.ZodDefault<z.ZodBoolean>;
+      }, z.core.$strict>>>;
+      smoke: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        args: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        command: z.ZodString;
+        required: z.ZodDefault<z.ZodBoolean>;
+      }, z.core.$strict>>>;
+    }, z.core.$strict>>;
+  }, z.core.$strict>>;
   rules: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
     path: z.ZodString;
   }, z.core.$strict>>>;

package/dist/config.js

@@ -361,6 +361,19 @@ const workflowSchema = z.object({
 	execution: workflowExecutionSchema.optional(),
 	nodes: z.array(workflowNodeSchema)
 }).strict();
+const runnerJobCommandSchema = z.object({
+	args: z.array(z.string()).default([]),
+	command: z.string().min(1),
+	required: z.boolean().default(true)
+}).strict();
+const runnerJobEnvironmentSchema = z.object({
+	setup: z.array(runnerJobCommandSchema).default([]),
+	smoke: z.array(runnerJobCommandSchema).default([])
+}).strict();
+const runnerJobConfigSchema = z.object({ environment: runnerJobEnvironmentSchema.default({
+	setup: [],
+	smoke: []
+}) }).strict();
 const runnersFileSchema = z.object({
 	runners: strictRecord(runnerSchema).default({}),
 	version: z.literal(1)
@@ -381,6 +394,10 @@ const pipelineFileSchema = z.object({
 		on: {}
 	}),
 	orchestrator: orchestratorSchema,
+	runner_job: runnerJobConfigSchema.default({ environment: {
+		setup: [],
+		smoke: []
+	} }),
 	schedules: strictRecord(schedulePolicySchema).default({}),
 	task_context: taskContextResolverSchema.optional(),
 	workflows: strictRecord(workflowSchema).default({}),
@@ -397,6 +414,10 @@ const configSchema = z.object({
 	mcp_servers: strictRecord(mcpServerSchema).default({}),
 	orchestrator: orchestratorSchema,
 	profiles: strictRecord(profileSchema).default({}),
+	runner_job: runnerJobConfigSchema.default({ environment: {
+		setup: [],
+		smoke: []
+	} }),
 	rules: strictRecord(pathRefSchema).default({}),
 	runners: strictRecord(runnerSchema).default({}),
 	schedules: strictRecord(schedulePolicySchema).default({}),
@@ -519,6 +540,7 @@ function parsePipelineConfigParts(sources, projectRoot, sourcePaths = {
 		mcp_servers: profiles.mcp_servers,
 		orchestrator: pipeline.orchestrator,
 		profiles: profiles.profiles,
+		runner_job: pipeline.runner_job,
 		rules: profiles.rules,
 		runners: runners.runners,
 		schedules: pipeline.schedules,

package/dist/hooks.d.ts

@@ -13,8 +13,8 @@ declare const hookResultSchema: z.ZodObject<{
     taskContext: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
   }, z.core.$strict>>;
   status: z.ZodEnum<{
-    pass: "pass";
     fail: "fail";
+    pass: "pass";
     skip: "skip";
   }>;
   summary: z.ZodOptional<z.ZodString>;

package/dist/index.js

@@ -1,13 +1,14 @@
 #!/usr/bin/env node
 import { PipelineConfigError, loadPipelineConfig, tryLoadPipelineConfig } from "./config.js";
+import { BUILTIN_PIPE_COMMANDS, registerConfiguredEntrypointCommands } from "./commands/pipeline-command.js";
 import { configureGatewayHosts, localGatewayStatus, renderGatewayConfig, runGatewayDoctor, startLocalGateway } from "./mcp/gateway.js";
-import { compileWorkflowPlan } from "./workflow-planner.js";
-import { formatInstallCommandsResult, installCommands, parseCommandHost } from "./install-commands.js";
 import { createOrchestratorLaunchPlan, createRunnerLaunchPlan } from "./runner.js";
+import { compileWorkflowPlan } from "./workflow-planner.js";
 import { formatConfigError, runPipelineFromConfig } from "./pipeline-runtime.js";
-import { runKubernetesRunnerJob } from "./kubernetes-runner.js";
-import { formatPipelineInitResult, initPipelineProject } from "./pipeline-init.js";
 import { compileScheduleArtifact, generateScheduleArtifact, parseScheduleArtifact } from "./schedule-planner.js";
+import { registerRunnerJobCommand } from "./commands/runner-job-command.js";
+import { formatInstallCommandsResult, installCommands, parseCommandHost } from "./install-commands.js";
+import { formatPipelineInitResult, initPipelineProject } from "./pipeline-init.js";
 import { existsSync, readFileSync, realpathSync } from "node:fs";
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -190,17 +191,6 @@ function truncateMiddle(text, maxLength) {
 	const keep = Math.floor((maxLength - 32) / 2);
 	return `${text.slice(0, keep)}\n... truncated ...\n${text.slice(-keep)}`;
 }
-const BUILTIN_PIPE_COMMANDS = new Set([
-	"run",
-	"pipe",
-	"validate",
-	"explain-plan",
-	"doctor",
-	"init",
-	"install-commands",
-	"mcp",
-	"runner-job"
-]);
 function createCliProgram() {
 	const configuredPipeline = tryLoadConfiguredEntrypoints(process.env.PIPELINE_TARGET_PATH ?? process.cwd());
 	const program = new Command();
@@ -284,11 +274,8 @@ function createCliProgram() {
 		});
 		console.log(formatInstallCommandsResult(result));
 	});
-	program.command("runner-job").description("Run an in-pod pipeline runner job from the console payload").action(async () => {
-		const exitCode = await runKubernetesRunnerJob();
-		process.exitCode = exitCode;
-	});
-	const configuredEntrypointCommands = registerConfiguredEntrypointCommands(program, configuredPipeline);
+	registerRunnerJobCommand(program);
+	const configuredEntrypointCommands = registerConfiguredEntrypointCommands(program, configuredPipeline, (entrypoint, task) => pipe(task, { entrypoint }));
 	if (configuredEntrypointCommands.size > 0) program.configureHelp({ subcommandTerm(command) {
 		if (configuredEntrypointCommands.has(command.name())) return command.name();
 		return Help.prototype.subcommandTerm.call(this, command);
@@ -303,20 +290,6 @@ function tryLoadConfiguredEntrypoints(cwd) {
 		throw err;
 	}
 }
-function registerConfiguredEntrypointCommands(program, config) {
-	const registered = /* @__PURE__ */ new Set();
-	if (!config) return registered;
-	const reservedCommands = new Set(program.commands.map((command) => command.name()));
-	for (const [id, entrypoint] of Object.entries(config.entrypoints)) {
-		if (reservedCommands.has(id)) continue;
-		program.command(id).description(entrypoint.description ?? `Run the ${id} workflow`).argument("<description...>", "task description").action(async (descriptionParts) => {
-			await pipe(descriptionParts.join(" "), { entrypoint: id });
-		});
-		registered.add(id);
-		reservedCommands.add(id);
-	}
-	return registered;
-}
 function parseGatewayHostScope(value) {
 	if (value === "project" || value === "global") return value;
 	throw new Error("scope must be project or global");

package/dist/mcp/gateway.js

@@ -72,6 +72,7 @@ function renderOpenCodeGatewayConfig(config) {
 		mcp: { [PIPELINE_GATEWAY_SERVER_ID]: {
 			enabled: true,
 			headers: gatewayOpenCodeHeaders(gateway),
+			oauth: false,
 			type: "remote",
 			url: gatewayUrl(gateway)
 		} }

package/dist/runner-event-sink.js

@@ -87,6 +87,20 @@ function createRunnerEventSink(options) {
 				workflowId
 			});
 		},
+		recordRunnerJobPhase(phase, message, output) {
+			queue.push({
+				...nextEnvelope(),
+				log: {
+					level: "info",
+					message,
+					output: {
+						phase,
+						...output
+					}
+				},
+				type: "runner.job.phase"
+			});
+		},
 		recordRuntimeEvent,
 		recordSchemaValidationFailure(message, issues, workflowId) {
 			queue.push({

package/dist/runner-job/delivery.js

@@ -0,0 +1,57 @@
+import { execa } from "execa";
+//#region src/runner-job/delivery.ts
+const GITHUB_HTTPS_REPOSITORY_RE = /^https:\/\/github\.com\/([^/]+\/[^/.]+)(?:\.git)?$/;
+const GITHUB_SSH_REPOSITORY_RE = /^git@github\.com:([^/]+\/[^/.]+)(?:\.git)?$/;
+const createPullRequest = async (options) => {
+	if (!options.payload.delivery.pullRequest) return null;
+	const repository = options.payload.repository;
+	const env = compactEnv(options.env);
+	const runCommand = options.runCommand ?? runDeliveryCommand;
+	const branch = (await runCommand("git", ["branch", "--show-current"], {
+		cwd: options.worktreePath,
+		env,
+		stdin: "ignore"
+	})).stdout.trim();
+	if (!branch) throw new Error("Pull request delivery requires a checked-out branch");
+	const headOwner = options.env.PIPELINE_PR_HEAD_OWNER?.trim() || "oisin-bot";
+	const repositoryName = githubRepositoryName(repository.url);
+	await runCommand("git", [
+		"push",
+		"--set-upstream",
+		"origin",
+		branch
+	], {
+		cwd: options.worktreePath,
+		env,
+		stdin: "ignore"
+	});
+	const url = (await runCommand("gh", [
+		"pr",
+		"create",
+		"--fill",
+		"--base",
+		repository.baseBranch,
+		"--head",
+		`${headOwner}:${branch}`,
+		"--repo",
+		repositoryName
+	], {
+		cwd: options.worktreePath,
+		env,
+		stdin: "ignore"
+	})).stdout.trim();
+	return url ? { url } : null;
+};
+const runDeliveryCommand = (command, args, options) => execa(command, args, options);
+function compactEnv(env) {
+	return Object.fromEntries(Object.entries(env).filter((entry) => Boolean(entry[1])));
+}
+function githubRepositoryName(repositoryUrl) {
+	const httpsMatch = repositoryUrl.match(GITHUB_HTTPS_REPOSITORY_RE);
+	if (httpsMatch?.[1]) return httpsMatch[1];
+	const sshMatch = repositoryUrl.match(GITHUB_SSH_REPOSITORY_RE);
+	if (sshMatch?.[1]) return sshMatch[1];
+	throw new Error("Pull request delivery requires a GitHub repository URL");
+}
+//#endregion
+export { createPullRequest };

package/dist/runner-job/devspace.js

@@ -0,0 +1,34 @@
+import { loadPipelineConfig } from "../config.js";
+import { execa } from "execa";
+//#region src/runner-job/devspace.ts
+function assertRunnerDevspaceReady(worktreePath) {
+	return { config: loadPipelineConfig(worktreePath, { allowMissingLintFileReferences: true }) };
+}
+async function runRunnerDevspaceSmoke(options) {
+	const smoke = options.config.runner_job.environment.smoke;
+	if (smoke.length === 0) return "skipped";
+	const runCommand = options.runCommand ?? runDevspaceCommand;
+	for (const command of smoke) await runCommand(command.command, command.args, {
+		cwd: options.worktreePath,
+		env: compactEnv(options.env),
+		stdin: "ignore"
+	});
+	return "ran";
+}
+async function runRunnerEnvironmentSetup(options) {
+	const setup = options.config.runner_job.environment.setup;
+	if (setup.length === 0) return "skipped";
+	const runCommand = options.runCommand ?? runDevspaceCommand;
+	for (const command of setup) await runCommand(command.command, command.args, {
+		cwd: options.worktreePath,
+		env: compactEnv(options.env),
+		stdin: "ignore"
+	});
+	return "ran";
+}
+const runDevspaceCommand = (command, args, options) => execa(command, args, options);
+function compactEnv(env) {
+	return Object.fromEntries(Object.entries(env).filter((entry) => Boolean(entry[1])));
+}
+//#endregion
+export { assertRunnerDevspaceReady, runRunnerDevspaceSmoke, runRunnerEnvironmentSetup };

package/dist/runner-job/run.js

@@ -0,0 +1,279 @@
+import { PipelineConfigError } from "../config.js";
+import { runPipelineFromConfig } from "../pipeline-runtime.js";
+import { RUNNER_PAYLOAD_ENV, parseRunnerJobPayloadWithIssues } from "../runner-job-contract.js";
+import { createRunnerEventSink } from "../runner-event-sink.js";
+import { compileScheduleArtifact, generateScheduleArtifact } from "../schedule-planner.js";
+import { createPullRequest } from "./delivery.js";
+import { assertRunnerDevspaceReady, runRunnerDevspaceSmoke, runRunnerEnvironmentSetup } from "./devspace.js";
+import { prepareRunnerWorkspace } from "./workspace.js";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+//#region src/runner-job/run.ts
+const EXIT_PASS = 0;
+const EXIT_FAIL = 1;
+const EXIT_CANCELLED = 130;
+const EXIT_VALIDATION = 64;
+const EXIT_STARTUP = 70;
+const RUNNER_SCHEDULE_ENTRYPOINT = "pipe";
+async function runRunnerJob(options = {}) {
+	const prepared = prepareRunnerJob(options);
+	if (prepared.exitCode !== void 0) return prepared.exitCode;
+	if ("validationFailure" in prepared) return reportPreparedValidationFailure(prepared.validationFailure, options);
+	const { env, payload, stderr } = prepared.job;
+	const controller = new AbortController();
+	const signalEmitter = options.signalEmitter ?? process;
+	const forceExit = options.onForceExit ?? ((exitCode) => process.exit(exitCode));
+	let signalExitCode;
+	let signalCount = 0;
+	let signalFinalResultRecorded = false;
+	const sink = createRunnerSink({
+		env,
+		events: payload.events,
+		fetch: options.fetch,
+		runId: payload.run.id
+	});
+	const handleSignal = (exitCode) => {
+		signalCount += 1;
+		if (signalCount === 1) {
+			signalExitCode = exitCode;
+			sink.recordCancellation(RUNNER_SCHEDULE_ENTRYPOINT);
+			signalFinalResultRecorded = true;
+			controller.abort();
+			return;
+		}
+		forceExit(signalExitCode ?? exitCode);
+	};
+	const handleSigterm = () => handleSignal(EXIT_CANCELLED);
+	const handleSigint = () => handleSignal(EXIT_CANCELLED);
+	signalEmitter.on("SIGTERM", handleSigterm);
+	signalEmitter.on("SIGINT", handleSigint);
+	const runner = options.pipelineRunner ?? runPipelineFromConfig;
+	let sawWorkflowFinish = false;
+	try {
+		const { config, readiness, task, workflowId, workspace } = await prepareReadyWorkspace(options, payload, env, sink);
+		const result = await runner({
+			config,
+			reporter: (event) => {
+				if (event.type === "workflow.finish") sawWorkflowFinish = true;
+				sink.recordRuntimeEvent(event);
+			},
+			runId: payload.run.id,
+			signal: controller.signal,
+			task,
+			hookPolicy: { allowCommandHooks: true },
+			workflowId,
+			worktreePath: workspace.worktreePath
+		});
+		if (result.outcome === "PASS") await deliverSuccessfulRun(options, payload, workspace, readiness, sink);
+		if (!(sawWorkflowFinish || signalFinalResultRecorded)) sink.recordFinalResult(result.outcome, result.plan.workflowId);
+		if (await flushAndReport(sink.flush, stderr) && !signalExitCode) return EXIT_STARTUP;
+		return signalExitCode ?? exitCodeForRuntimeResult(result);
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		stderr.write(`${message}\n`);
+		await flushAndReport(sink.flush, stderr);
+		if (err instanceof PipelineConfigError) return signalExitCode ?? EXIT_VALIDATION;
+		return signalExitCode ?? EXIT_STARTUP;
+	} finally {
+		removeSignalListener(signalEmitter, "SIGTERM", handleSigterm);
+		removeSignalListener(signalEmitter, "SIGINT", handleSigint);
+	}
+}
+async function prepareReadyWorkspace(options, payload, env, sink) {
+	const workspace = await prepareWorkspace(options, payload, env);
+	sink.recordRunnerJobPhase("workspace.prepared", "runner workspace prepared", { worktreePath: workspace.worktreePath });
+	const readiness = assertRunnerDevspaceReady(workspace.worktreePath);
+	const config = requireRunnerConfig(readiness);
+	sink.recordRunnerJobPhase("environment.ready", "runner environment ready");
+	const setupStatus = await runRunnerEnvironmentSetup({
+		config,
+		env: workspace.env,
+		runCommand: options.runDevspaceCommand,
+		worktreePath: workspace.worktreePath
+	});
+	sink.recordRunnerJobPhase(`environment.setup.${setupStatus}`, `runner environment setup ${setupStatus}`);
+	const task = resolveRunnerTask(payload.task, workspace.worktreePath);
+	const compiled = await (options.prepareSchedule ?? (options.pipelineRunner ? useConfiguredDefaultWorkflow : generateRunnerSchedule))(config, task, workspace, sink);
+	return {
+		config: compiled.config,
+		readiness,
+		task,
+		workflowId: compiled.workflowId,
+		workspace
+	};
+}
+function requireRunnerConfig(readiness) {
+	if (!readiness.config) throw new PipelineConfigError("PIPELINE_CONFIG_VALIDATION_ERROR", "Runner jobs require a repository pipeline config", [{
+		message: ".pipeline/pipeline.yaml is required for runner jobs",
+		path: ".pipeline/pipeline.yaml"
+	}]);
+	return readiness.config;
+}
+function resolveRunnerTask(task, worktreePath) {
+	if (task.kind === "prompt") return task.prompt;
+	if (task.path) return readFileSync(join(worktreePath, task.path), "utf8");
+	return task.id;
+}
+function useConfiguredDefaultWorkflow(config) {
+	return Promise.resolve({
+		config,
+		workflowId: config.default_workflow
+	});
+}
+async function generateRunnerSchedule(config, task, workspace, sink) {
+	const result = await generateScheduleArtifact({
+		config,
+		entrypointId: RUNNER_SCHEDULE_ENTRYPOINT,
+		task,
+		worktreePath: workspace.worktreePath
+	});
+	sink.recordRunnerJobPhase("schedule.generated", "runner schedule generated", { path: result.path });
+	const compiled = compileScheduleArtifact(config, result.artifact, workspace.worktreePath);
+	return {
+		config: compiled.config,
+		workflowId: compiled.workflowId
+	};
+}
+async function deliverSuccessfulRun(options, payload, workspace, readiness, sink) {
+	if (readiness.config) {
+		const config = readiness.config;
+		const smokeStatus = await runRunnerDevspaceSmokeWithPhase(options, config, workspace, sink);
+		sink.recordRunnerJobPhase(`environment.smoke.${smokeStatus}`, `runner environment smoke ${smokeStatus}`);
+	}
+	const pullRequest = await createRunnerPullRequestWithPhase(options, payload, workspace, sink);
+	if (pullRequest) sink.recordRunnerJobPhase("delivery.pull_request", "runner pull request created", { url: pullRequest.url });
+}
+async function runRunnerDevspaceSmokeWithPhase(options, config, workspace, sink) {
+	try {
+		return await runRunnerDevspaceSmoke({
+			config,
+			env: workspace.env,
+			runCommand: options.runDevspaceCommand,
+			worktreePath: workspace.worktreePath
+		});
+	} catch (err) {
+		sink.recordRunnerJobPhase("environment.smoke.failed", "runner environment smoke failed", { error: errorMessage(err) });
+		throw err;
+	}
+}
+async function createRunnerPullRequestWithPhase(options, payload, workspace, sink) {
+	try {
+		return await createRunnerPullRequest(options, payload, workspace.worktreePath, workspace.env);
+	} catch (err) {
+		sink.recordRunnerJobPhase("delivery.pull_request.failed", "runner pull request creation failed", { error: errorMessage(err) });
+		throw err;
+	}
+}
+function createRunnerPullRequest(options, payload, worktreePath, env) {
+	return (options.createPullRequest ?? createPullRequest)({
+		env,
+		payload,
+		worktreePath
+	});
+}
+function prepareWorkspace(options, payload, env) {
+	return (options.prepareWorkspace ?? prepareRunnerWorkspace)({
+		cwd: options.cwd,
+		env,
+		payload
+	});
+}
+function prepareRunnerJob(options) {
+	const env = options.env ?? process.env;
+	const stderr = options.stderr ?? process.stderr;
+	const payloadRaw = env[RUNNER_PAYLOAD_ENV];
+	if (!payloadRaw) {
+		stderr.write(`${RUNNER_PAYLOAD_ENV} is required\n`);
+		return { exitCode: EXIT_VALIDATION };
+	}
+	const payload = parsePayload(payloadRaw, stderr);
+	if (!payload.ok) return { validationFailure: {
+		env,
+		error: payload.error,
+		recoverable: payload.recoverable,
+		stderr
+	} };
+	return { job: {
+		env,
+		payload: payload.payload,
+		stderr
+	} };
+}
+function parsePayload(payloadRaw, stderr) {
+	const result = parseRunnerJobPayloadWithIssues(payloadRaw);
+	if (!result.ok) stderr.write(`${result.error.message}\n`);
+	return result;
+}
+async function reportPreparedValidationFailure(failure, options) {
+	if (failure.recoverable) {
+		const sink = createRunnerSink({
+			env: failure.env,
+			events: failure.recoverable.events,
+			fetch: options.fetch,
+			runId: failure.recoverable.run.id
+		});
+		sink.recordSchemaValidationFailure(failure.error.message, failure.error.issues, RUNNER_SCHEDULE_ENTRYPOINT);
+		await flushAndReport(sink.flush, failure.stderr);
+	}
+	return EXIT_VALIDATION;
+}
+function resolveAuthToken(authTokenEnv, env, stderr) {
+	const token = env[authTokenEnv]?.trim();
+	if (!token) {
+		stderr.write(`Runner event auth token is required. Set ${authTokenEnv}.\n`);
+		return null;
+	}
+	return token;
+}
+function createRunnerSink(options) {
+	const authToken = resolveAuthToken(options.events.authTokenEnv, options.env, { write: () => true });
+	if (!authToken) return createNoopRunnerEventSink();
+	return createRunnerEventSink({
+		authHeader: options.events.authHeader,
+		authToken,
+		fetch: options.fetch,
+		runId: options.runId,
+		url: options.events.url
+	});
+}
+function createNoopRunnerEventSink() {
+	return {
+		fail: () => Promise.resolve(),
+		flush: () => Promise.resolve(),
+		recordCancellation: () => void 0,
+		recordFinalResult: () => void 0,
+		recordRunnerJobPhase: () => void 0,
+		recordRuntimeEvent: () => void 0,
+		recordSchemaValidationFailure: () => void 0
+	};
+}
+function errorMessage(err) {
+	return err instanceof Error ? err.message : String(err);
+}
+function exitCodeForRuntimeResult(result) {
+	switch (result.outcome) {
+		case "PASS": return EXIT_PASS;
+		case "FAIL": return EXIT_FAIL;
+		case "CANCELLED": return EXIT_CANCELLED;
+		default: return EXIT_STARTUP;
+	}
+}
+async function flushAndReport(flush, stderr) {
+	try {
+		await flush();
+		return false;
+	} catch (err) {
+		const message = err instanceof Error ? err.message : String(err);
+		stderr.write(`Event sink flush failed: ${message}\n`);
+		return true;
+	}
+}
+function removeSignalListener(emitter, event, listener) {
+	if (emitter.off) {
+		emitter.off(event, listener);
+		return;
+	}
+	emitter.removeListener?.(event, listener);
+}
+//#endregion
+export { runRunnerJob };

package/dist/runner-job/workspace.js

@@ -0,0 +1,52 @@
+import { simpleGit } from "simple-git";
+//#region src/runner-job/workspace.ts
+const RUNNER_JOB_WORKSPACE_PATH = "/workspace";
+async function prepareRunnerWorkspace(options) {
+	const existingWorktreePath = options.env.PIPELINE_TARGET_PATH ?? options.cwd;
+	if (existingWorktreePath) return {
+		env: {
+			...options.env,
+			PIPELINE_TARGET_PATH: existingWorktreePath
+		},
+		worktreePath: existingWorktreePath
+	};
+	const repository = options.payload.repository;
+	if (!repository) throw new RunnerWorkspaceError("repository is required for runner jobs");
+	const git = options.createGitClient?.() ?? simpleGit();
+	const repositoryUrl = repository.url;
+	const branchName = runnerBranchName(options.payload);
+	try {
+		await git.clone(repositoryUrl, RUNNER_JOB_WORKSPACE_PATH, ["--no-tags"]);
+		await git.cwd(RUNNER_JOB_WORKSPACE_PATH).checkoutBranch(branchName, repository.sha ?? `origin/${repository.baseBranch}`);
+	} catch (err) {
+		throw new RunnerWorkspaceError(redactSecretText(errorMessage(err)));
+	}
+	return {
+		env: {
+			...options.env,
+			PIPELINE_TARGET_PATH: RUNNER_JOB_WORKSPACE_PATH
+		},
+		worktreePath: RUNNER_JOB_WORKSPACE_PATH
+	};
+}
+var RunnerWorkspaceError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "RunnerWorkspaceError";
+	}
+};
+function errorMessage(err) {
+	return err instanceof Error ? err.message : String(err);
+}
+const CREDENTIAL_IN_URL_RE = /(https?:\/\/)([^:@\s/]+):([^@\s/]+)@/g;
+function redactSecretText(value) {
+	return value.replace(CREDENTIAL_IN_URL_RE, "$1$2:<redacted>@");
+}
+function runnerBranchName(payload) {
+	const runId = payload.run?.id;
+	const source = payload.task?.kind === "ticket" ? payload.task.id : runId;
+	if (!(source && runId)) throw new RunnerWorkspaceError("run and task context are required for runner jobs");
+	return `pipeline/${source.trim().toLowerCase().replace(/[^a-z0-9._/-]+/g, "-").replace(/^[./-]+|[./-]+$/g, "").replace(/\.{2,}/g, ".") || runId}`;
+}
+//#endregion
+export { prepareRunnerWorkspace };