@kici-dev/agent 0.4.0 → 0.5.0

package/dist/server.js

@@ -27,7 +27,8 @@ import { gcStaleTmpDirs } from "@kici-dev/core/tmp-gc";
 import fsPromises, { access, lstat, mkdir, readFile, readdir, realpath, unlink, writeFile } from "node:fs/promises";
 import { makeTempDir } from "@kici-dev/core/tmp";
 import Docker from "dockerode";
-import { buildKiciApi, buildNeedsContext, isDynamicGroupRef, isDynamicJobFn, isParallelGroup, isStaticArray, isStaticObject, setJobOutputsMap, setStepOutputsMap, setStepRefMap } from "@kici-dev/sdk";
+import { buildKiciApi, buildNeedsContext, createFilterContext, isDynamicGroupRef, isDynamicJobFn, isParallelGroup, isStaticArray, isStaticObject, setJobOutputsMap, setStepOutputsMap, setStepRefMap } from "@kici-dev/sdk";
+import { $ } from "zx";
 import { c, x } from "tar";
 import https from "node:https";
 import http from "node:http";
@@ -324,7 +325,7 @@ var LogBuffer = class extends RingBuffer {
 };
 //#endregion
 //#region src/ws/orchestrator-client.ts
-const logger$12 = createLogger({ prefix: "orchestrator-client" });
+const logger$13 = createLogger({ prefix: "orchestrator-client" });
 /**
 * How long to wait for `artifacts.upload.complete.ack` before failing the step.
 *
@@ -484,7 +485,7 @@ var OrchestratorClient = class OrchestratorClient {
 	*/
 	connect() {
 		if (this._state !== "disconnected") {
-			logger$12.warn("connect() called while not disconnected", { state: this._state });
+			logger$13.warn("connect() called while not disconnected", { state: this._state });
 			return;
 		}
 		this.intentionalDisconnect = false;
@@ -1048,7 +1049,7 @@ var OrchestratorClient = class OrchestratorClient {
 				}
 			});
 		} catch (err) {
-			logger$12.error("Failed to create WebSocket", { error: toErrorMessage(err) });
+			logger$13.error("Failed to create WebSocket", { error: toErrorMessage(err) });
 			this._state = "disconnected";
 			this.scheduleReconnect();
 			return;
@@ -1056,7 +1057,7 @@ var OrchestratorClient = class OrchestratorClient {
 		this.ws.on("open", () => {
 			if (this.token) {
 				this._state = "authenticating";
-				logger$12.info("Connected to orchestrator, sending auth.request", {
+				logger$13.info("Connected to orchestrator, sending auth.request", {
 					url: this.url,
 					agentId: this.agentId
 				});
@@ -1067,7 +1068,7 @@ var OrchestratorClient = class OrchestratorClient {
 				}));
 			} else {
 				this._state = "registering";
-				logger$12.info("Connected to orchestrator, sending agent.register (no token)", {
+				logger$13.info("Connected to orchestrator, sending agent.register (no token)", {
 					url: this.url,
 					agentId: this.agentId
 				});
@@ -1078,12 +1079,12 @@ var OrchestratorClient = class OrchestratorClient {
 			this.handleMessage(data);
 		});
 		this.ws.on("close", (code, reason) => {
-			logger$12.info("Orchestrator connection closed", {
+			logger$13.info("Orchestrator connection closed", {
 				code,
 				reason: reason.toString()
 			});
 			if (code === WS_CLOSE_AGENT_AUTH_FAILED) {
-				logger$12.error("Orchestrator closed with auth-failed code -- token is invalid or revoked. NOT retrying.", {
+				logger$13.error("Orchestrator closed with auth-failed code -- token is invalid or revoked. NOT retrying.", {
 					code,
 					reason: reason.toString()
 				});
@@ -1120,7 +1121,7 @@ var OrchestratorClient = class OrchestratorClient {
 			if (!this.intentionalDisconnect) this.scheduleReconnect();
 		});
 		this.ws.on("error", (err) => {
-			logger$12.error(`Orchestrator WebSocket error: ${err.message}`);
+			logger$13.error(`Orchestrator WebSocket error: ${err.message}`);
 			if (this.ws && this.ws.readyState === WebSocket.OPEN) this.ws.close();
 		});
 	}
@@ -1228,7 +1229,7 @@ var OrchestratorClient = class OrchestratorClient {
 			this.pendingUserArtifactRequests.set(record.messageId, record.pending);
 			this.resendableCompletes.set(record.messageId, record);
 			this.sendDirect(record.frame);
-			logger$12.info("Re-sent artifact upload-complete after reconnect", {
+			logger$13.info("Re-sent artifact upload-complete after reconnect", {
 				messageId: record.messageId,
 				attempt: record.attempts
 			});
@@ -1255,7 +1256,7 @@ var OrchestratorClient = class OrchestratorClient {
 		try {
 			raw = JSON.parse(data.toString());
 		} catch {
-			logger$12.warn("Malformed JSON received from orchestrator");
+			logger$13.warn("Malformed JSON received from orchestrator");
 			return;
 		}
 		const rawMsg = raw;
@@ -1314,13 +1315,13 @@ var OrchestratorClient = class OrchestratorClient {
 			switch (msg.type) {
 				case "auth.success":
 					if (this._state === "authenticating") {
-						logger$12.info("Authentication successful, sending agent.register", { connectionId: msg.connectionId });
+						logger$13.info("Authentication successful, sending agent.register", { connectionId: msg.connectionId });
 						this._state = "registering";
 						this.sendAgentRegister();
 					}
 					break;
 				case "auth.failure":
-					logger$12.error("Authentication FAILED -- token is invalid or expired. NOT retrying.", { reason: msg.reason });
+					logger$13.error("Authentication FAILED -- token is invalid or expired. NOT retrying.", { reason: msg.reason });
 					this.authFailed = true;
 					this.intentionalDisconnect = true;
 					if (this.ws) {
@@ -1330,7 +1331,7 @@ var OrchestratorClient = class OrchestratorClient {
 					this._state = "disconnected";
 					break;
 				case "register.ack":
-					logger$12.info("Registration acknowledged by orchestrator", {
+					logger$13.info("Registration acknowledged by orchestrator", {
 						agentId: msg.agentId,
 						labels: msg.labels,
 						scalerManaged: msg.scalerManaged,
@@ -1347,14 +1348,14 @@ var OrchestratorClient = class OrchestratorClient {
 					this.sendConfigAck(msg.agentId);
 					break;
 				case "job.dispatch":
-					logger$12.info("Job dispatch received", {
+					logger$13.info("Job dispatch received", {
 						runId: msg.runId,
 						jobId: msg.jobId
 					});
 					this.onJobDispatch(msg);
 					break;
 				case "job.cancel":
-					logger$12.info("Job cancel received", {
+					logger$13.info("Job cancel received", {
 						runId: msg.runId,
 						jobId: msg.jobId,
 						reason: msg.reason
@@ -1362,7 +1363,7 @@ var OrchestratorClient = class OrchestratorClient {
 					this.onJobCancel(msg);
 					break;
 				case "job.concurrency.ack": {
-					logger$12.info("Concurrency ack received", {
+					logger$13.info("Concurrency ack received", {
 						requestId: msg.requestId,
 						action: msg.action
 					});
@@ -1377,7 +1378,7 @@ var OrchestratorClient = class OrchestratorClient {
 					break;
 				}
 				case "step.approval-resolved": {
-					logger$12.info("Step approval resolved", {
+					logger$13.info("Step approval resolved", {
 						requestId: msg.requestId,
 						runId: msg.runId,
 						jobId: msg.jobId,
@@ -1397,7 +1398,7 @@ var OrchestratorClient = class OrchestratorClient {
 					break;
 				}
 				case "fleet.logs.request":
-					logger$12.info("Fleet log collection requested", {
+					logger$13.info("Fleet log collection requested", {
 						requestId: msg.requestId,
 						logWindowHours: msg.logWindowHours
 					});
@@ -1407,7 +1408,7 @@ var OrchestratorClient = class OrchestratorClient {
 			return;
 		}
 		if (heartbeatSchema.safeParse(raw).success) return;
-		logger$12.warn("Invalid message from orchestrator", { errors: parsed.error.issues });
+		logger$13.warn("Invalid message from orchestrator", { errors: parsed.error.issues });
 	}
 	flushBuffer() {
 		const events = this.eventBuffer.flush();
@@ -1421,11 +1422,11 @@ var OrchestratorClient = class OrchestratorClient {
 		}
 		this.disconnectedAt = null;
 		if (events.length > 0) {
-			logger$12.info("Flushing event buffer", { count: events.length });
+			logger$13.info("Flushing event buffer", { count: events.length });
 			for (const msg of events) this.sendDirect(msg);
 		}
 		if (logLines.length > 0) {
-			logger$12.info("Flushing log buffer", { count: logLines.length });
+			logger$13.info("Flushing log buffer", { count: logLines.length });
 			for (let i = 0; i < logLines.length; i += OrchestratorClient.LOG_BATCH_SIZE) {
 				const batch = logLines.slice(i, i + OrchestratorClient.LOG_BATCH_SIZE);
 				this.sendAgentLogMessage(batch);
@@ -1478,14 +1479,14 @@ var OrchestratorClient = class OrchestratorClient {
 	*/
 	blockMmdsAccess() {
 		if (process.getuid?.() !== 0) {
-			logger$12.info("MMDS iptables block skipped (non-root) — network isolation handled by orchestrator");
+			logger$13.info("MMDS iptables block skipped (non-root) — network isolation handled by orchestrator");
 			return;
 		}
 		try {
 			execSync("iptables -A OUTPUT -d 169.254.169.254 -j DROP", { timeout: 5e3 });
-			logger$12.info("MMDS access blocked via iptables");
+			logger$13.info("MMDS access blocked via iptables");
 		} catch (err) {
-			logger$12.warn("Failed to block MMDS access via iptables", { error: toErrorMessage(err) });
+			logger$13.warn("Failed to block MMDS access via iptables", { error: toErrorMessage(err) });
 		}
 	}
 	/**
@@ -1499,7 +1500,7 @@ var OrchestratorClient = class OrchestratorClient {
 				messageId: `config-ack-${agentId}-${Date.now()}`,
 				agentId
 			}));
-			logger$12.info("Config ACK sent to orchestrator", { agentId });
+			logger$13.info("Config ACK sent to orchestrator", { agentId });
 		}
 	}
 	startHeartbeat() {
@@ -1565,12 +1566,12 @@ var OrchestratorClient = class OrchestratorClient {
 	scheduleReconnect() {
 		this.cancelReconnect();
 		if (this.authFailed) {
-			logger$12.error("Not reconnecting: authentication permanently failed");
+			logger$13.error("Not reconnecting: authentication permanently failed");
 			return;
 		}
 		const delay = this.getReconnectDelay();
 		this.reconnectAttempts++;
-		logger$12.info("Scheduling reconnect", {
+		logger$13.info("Scheduling reconnect", {
 			attempt: this.reconnectAttempts,
 			delayMs: Math.round(delay)
 		});
@@ -1655,14 +1656,14 @@ var init_console_capture = __esmMin((() => {
 init_console_capture();
 function safe(name, fallback = "unknown") {
 	switch (name) {
-		case "version": return "0.4.0";
-		case "buildCommit": return "ffd489464";
-		case "sdkVersion": return "0.4.0";
-		case "sdkBundleHash": return "fcd0a836aa1cb92debd93e0254450614d123b3748511aa4148d956fd72a7c29f";
-		case "sharedVersion": return "0.4.0";
-		case "sharedBundleHash": return "f16fa528a8a9ef1bed8df369f0e88efafca8a9954a749005299fdbcdb93fa188";
-		case "engineVersion": return "0.4.0";
-		case "engineBundleHash": return "31e2d5c327284e1cac908d7f85cf6d878bbf87ea0da93ed09c6205ada6935f89";
+		case "version": return "0.5.0";
+		case "buildCommit": return "cb51c7d1e";
+		case "sdkVersion": return "0.5.0";
+		case "sdkBundleHash": return "5b85e7cffa4a08e39329ff80448a2744af8e5b5f9840ec3801fad45ed11a3de9";
+		case "sharedVersion": return "0.5.0";
+		case "sharedBundleHash": return "b6b6d1818d1fe648150422daf073dafc18b037404cacf82e0ec03b4a2863e4c4";
+		case "engineVersion": return "0.5.0";
+		case "engineBundleHash": return "35d174ce6f4748abffcad194b335b508cade5d1c8af16d9cd3bdcb744f38717e";
 		default: return fallback;
 	}
 }
@@ -1947,7 +1948,7 @@ async function gcStaleAgentTmpDirs(base = kiciTmpBase()) {
 * spawn fails and the caller clears the orchestrator's reboot-pending flag and
 * surfaces the error — the deadline sweep is the backstop.
 */
-const logger$11 = createLogger({ prefix: "reboot" });
+const logger$12 = createLogger({ prefix: "reboot" });
 /** The OS reboot primitive for a Node platform string. */
 function rebootCommandFor(platform) {
 	switch (platform) {
@@ -1985,7 +1986,7 @@ function issueReboot(platform = process.platform) {
 				stdio: "ignore"
 			});
 			child.on("error", (err) => {
-				logger$11.error("Reboot command failed to spawn", {
+				logger$12.error("Reboot command failed to spawn", {
 					cmd,
 					args,
 					error: String(err)
@@ -1993,14 +1994,14 @@ function issueReboot(platform = process.platform) {
 				reject(err);
 			});
 			child.on("exit", (code) => {
-				if (code !== 0 && code !== null) logger$11.warn("Reboot command exited non-zero (privilege denied?)", {
+				if (code !== 0 && code !== null) logger$12.warn("Reboot command exited non-zero (privilege denied?)", {
 					cmd,
 					args,
 					code
 				});
 			});
 			child.unref();
-			logger$11.info("Issued host reboot", {
+			logger$12.info("Issued host reboot", {
 				cmd,
 				args
 			});
@@ -2259,6 +2260,229 @@ var init_git_clone = __esmMin((() => {
 	init_ssh_auth();
 }));
 //#endregion
+//#region src/checkout/changed-files.ts
+/** Build the auth context for the fetches, mirroring git-clone.ts's auth. */
+async function buildAuthCtx(auth) {
+	if (!auth) return { args: [] };
+	if (auth.kind === "basic") {
+		const user = auth.user ?? "x-access-token";
+		return { args: ["-c", `http.extraHeader=Authorization: Basic ${Buffer.from(`${user}:${auth.secret}`).toString("base64")}`] };
+	}
+	const sshSetup = await setupSshAuth({
+		privateKey: auth.secret,
+		hostKeyPolicy: auth.sshHostKeyPolicy,
+		knownHosts: auth.sshKnownHostsPem
+	});
+	return {
+		args: [],
+		env: { GIT_SSH_COMMAND: sshSetup.gitSshCommand },
+		cleanup: () => sshSetup.cleanup()
+	};
+}
+function git(workDir, args, ctx) {
+	return execFileSync("git", [
+		...ctx.args,
+		...BASE_GIT_ARGS,
+		"-C",
+		workDir,
+		...args
+	], {
+		encoding: "utf8",
+		stdio: [
+			"ignore",
+			"pipe",
+			"pipe"
+		],
+		...ctx.env && { env: {
+			...process.env,
+			...ctx.env
+		} }
+	});
+}
+function tryGit(workDir, args, ctx) {
+	try {
+		git(workDir, args, ctx);
+		return true;
+	} catch {
+		return false;
+	}
+}
+function parseNameOnly(out) {
+	return out.split("\n").map((s) => s.replace(/\r$/, "")).filter((s) => s.length > 0);
+}
+/** Ensure `commitish` exists locally; fetch / deepen (bounded) if not. */
+function ensureCommit(workDir, commitish, ctx) {
+	if (tryGit(workDir, [
+		"cat-file",
+		"-e",
+		`${commitish}^{commit}`
+	], ctx)) return true;
+	if (tryGit(workDir, [
+		"fetch",
+		"--depth",
+		"1",
+		"origin",
+		commitish
+	], ctx)) {
+		if (tryGit(workDir, [
+			"cat-file",
+			"-e",
+			`${commitish}^{commit}`
+		], ctx)) return true;
+	}
+	for (let i = 0; i < MAX_DEEPEN; i++) {
+		if (!tryGit(workDir, [
+			"fetch",
+			`--deepen=${DEEPEN_STEP}`,
+			"origin"
+		], ctx)) break;
+		if (tryGit(workDir, [
+			"cat-file",
+			"-e",
+			`${commitish}^{commit}`
+		], ctx)) return true;
+	}
+	return false;
+}
+function pushDiff(workDir, before, ctx) {
+	const isZero = !before || ZERO_SHA.test(before);
+	const baseRef = isZero ? EMPTY_TREE_SHA : before;
+	if (!isZero && !ensureCommit(workDir, before, ctx)) return {
+		files: [],
+		status: "unavailable"
+	};
+	return {
+		files: parseNameOnly(git(workDir, [
+			"diff",
+			"--name-only",
+			baseRef,
+			"HEAD"
+		], ctx)),
+		status: "fetched"
+	};
+}
+function prDiff(workDir, base, ctx) {
+	const candidates = [
+		base,
+		`origin/${base}`,
+		"FETCH_HEAD"
+	];
+	const resolveBase = () => candidates.find((c) => tryGit(workDir, [
+		"rev-parse",
+		"--verify",
+		`${c}^{commit}`
+	], ctx));
+	let baseRef = resolveBase();
+	if (!baseRef) {
+		if (!ensureCommit(workDir, base, ctx)) return {
+			files: [],
+			status: "unavailable"
+		};
+		baseRef = resolveBase();
+	}
+	if (!baseRef) return {
+		files: [],
+		status: "unavailable"
+	};
+	for (let i = 0; i <= MAX_DEEPEN; i++) {
+		if (tryGit(workDir, [
+			"merge-base",
+			baseRef,
+			"HEAD"
+		], ctx)) return {
+			files: parseNameOnly(git(workDir, [
+				"diff",
+				"--name-only",
+				`${baseRef}...HEAD`
+			], ctx)),
+			status: "fetched"
+		};
+		if (!tryGit(workDir, [
+			"fetch",
+			`--deepen=${DEEPEN_STEP}`,
+			"origin"
+		], ctx)) break;
+	}
+	return {
+		files: [],
+		status: "unavailable"
+	};
+}
+/**
+* Compute the changed-files list from the agent's local clone (HEAD is the
+* checked-out head commit). Ground truth for job/step rule evaluation. `auth`
+* (the same credentials used for the clone) authenticates the deepen / fetch
+* calls so a private remote resolves. Returns `unavailable` for diff-less
+* events (schedule/tag/manual) or any git failure — never throws.
+*/
+async function computeChangedFiles(workDir, event, auth) {
+	let ctx;
+	try {
+		if (event.type !== "push" && event.type !== "pull_request") return {
+			files: [],
+			status: "unavailable"
+		};
+		ctx = await buildAuthCtx(auth);
+		if (event.type === "push") return pushDiff(workDir, event.payload?.before ?? "", ctx);
+		const base = event.baseBranch ?? event.targetBranch;
+		if (!base) return {
+			files: [],
+			status: "unavailable"
+		};
+		return prDiff(workDir, base, ctx);
+	} catch {
+		return {
+			files: [],
+			status: "unavailable"
+		};
+	} finally {
+		if (ctx?.cleanup) await ctx.cleanup().catch(() => {});
+	}
+}
+var EMPTY_TREE_SHA, ZERO_SHA, MAX_DEEPEN, DEEPEN_STEP, BASE_GIT_ARGS;
+var init_changed_files = __esmMin((() => {
+	init_ssh_auth();
+	EMPTY_TREE_SHA = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
+	ZERO_SHA = /^0+$/;
+	MAX_DEEPEN = 4;
+	DEEPEN_STEP = 50;
+	BASE_GIT_ARGS = [
+		"-c",
+		"safe.directory=*",
+		"-c",
+		"core.quotePath=false"
+	];
+}));
+//#endregion
+//#region src/execution/generator-context.ts
+/**
+* Build the context handed to a `DynamicJobFn`.
+*
+* Optional members are spread conditionally rather than assigned `undefined`,
+* so an absent `needs` / repo pair leaves no key behind — a present-but-
+* undefined key reads as "declared" to a generator and serializes differently
+* between the two evaluations.
+*/
+function buildGeneratorContext(input) {
+	const { workflowName, event, env, repos, needs, $, log, kici } = input;
+	return {
+		$,
+		ctx: {
+			workflow: { name: workflowName },
+			event,
+			...needs && { needs }
+		},
+		log,
+		env,
+		kici,
+		...repos && {
+			sourceRepo: repos.sourceRepo,
+			workflowRepo: repos.workflowRepo
+		}
+	};
+}
+var init_generator_context = __esmMin((() => {}));
+//#endregion
 //#region src/execution/workflow-loader.ts
 /**
 * Workflow module loading: transforms `.ts` workflow files on import via the
@@ -2429,7 +2653,7 @@ function extractSteps(workflow, jobName) {
 * A sibling mismatch logs a warning; a missing target job throws a clear
 * determinism error.
 */
-async function extractStepsFromDynamicJob(workflow, dynamicIndex, jobName, event, env, apiTransport, expectedJobNames, upstreamSnapshot, declaredNeeds) {
+async function extractStepsFromDynamicJob(workflow, dynamicIndex, jobName, event, env, apiTransport, expectedJobNames, upstreamSnapshot, declaredNeeds, repos) {
 	const dynamicFn = extractDynamicJobFn(workflow, dynamicIndex);
 	const { $ } = await import("zx");
 	const { createLogger } = await import("@kici-dev/shared");
@@ -2437,17 +2661,16 @@ async function extractStepsFromDynamicJob(workflow, dynamicIndex, jobName, event
 	const log = createLogger({ prefix: `dynamic-job-fn:${workflow.name}` });
 	const kici = buildKiciApi(apiTransport ?? (() => Promise.reject(/* @__PURE__ */ new Error("Agent API not available during re-evaluation"))));
 	const needs = upstreamSnapshot ? buildNeedsContext(upstreamSnapshot, declaredNeeds ?? []) : void 0;
-	const generatedJobs = await dynamicFn({
+	const generatedJobs = await dynamicFn(buildGeneratorContext({
+		workflowName: workflow.name,
+		event,
+		env,
+		...repos && { repos },
+		...needs && { needs },
 		$,
-		ctx: {
-			workflow: { name: workflow.name },
-			event,
-			...needs && { needs }
-		},
 		log,
-		env,
 		kici
-	});
+	}));
 	const actualNames = generatedJobs.map((j) => j.name);
 	let droppedJobs = [];
 	if (expectedJobNames) {
@@ -2470,8 +2693,9 @@ async function extractStepsFromDynamicJob(workflow, dynamicIndex, jobName, event
 }
 var AGENT_SDK_VERSION, AGENT_SDK_BUNDLE_HASH, hookRegistered;
 var init_workflow_loader = __esmMin((() => {
-	AGENT_SDK_VERSION = "0.4.0";
-	AGENT_SDK_BUNDLE_HASH = "fcd0a836aa1cb92debd93e0254450614d123b3748511aa4148d956fd72a7c29f";
+	init_generator_context();
+	AGENT_SDK_VERSION = "0.5.0";
+	AGENT_SDK_BUNDLE_HASH = "5b85e7cffa4a08e39329ff80448a2744af8e5b5f9840ec3801fad45ed11a3de9";
 	hookRegistered = false;
 }));
 //#endregion
@@ -2492,7 +2716,7 @@ var init_workflow_loader = __esmMin((() => {
 async function packKiciSource(workDir) {
 	const kiciDir = join(workDir, ".kici");
 	if (!existsSync(kiciDir)) throw new Error(`.kici/ not found at ${kiciDir}`);
-	logger$10.info("Packing .kici/ source tarball", { dir: workDir });
+	logger$11.info("Packing .kici/ source tarball", { dir: workDir });
 	const startTime = Date.now();
 	const stream = c({
 		gzip: true,
@@ -2506,7 +2730,7 @@ async function packKiciSource(workDir) {
 	const hash = sha256(tarball);
 	const sizeKB = (tarball.length / 1024).toFixed(2);
 	const durationMs = Date.now() - startTime;
-	logger$10.info(".kici/ source packed", {
+	logger$11.info(".kici/ source packed", {
 		sizeKB,
 		hash: hash.slice(0, 12),
 		durationMs
@@ -2516,9 +2740,9 @@ async function packKiciSource(workDir) {
 		hash
 	};
 }
-var logger$10;
+var logger$11;
 var init_source_packer = __esmMin((() => {
-	logger$10 = createLogger({ prefix: "source-packer" });
+	logger$11 = createLogger({ prefix: "source-packer" });
 }));
 //#endregion
 //#region src/execution/dep-restore.ts
@@ -2605,6 +2829,52 @@ async function extractIntoScratch(url, kiciDir, attempt) {
 	};
 }
 /**
+* Append `SCRATCH_DIR_GIT_EXCLUDE_GLOB` to `${repoWorkDir}/.git/info/exclude`
+* so any in-flight or orphaned dep-restore scratch dirs are invisible to
+* `git status` / `git add` inside the customer's cloned working tree.
+*
+* Why `.git/info/exclude` and not `.gitignore`:
+* - `.gitignore` lives in the customer's repo and is committed; we MUST NOT
+*   modify it. Doing so would surface the rule in their PRs and create a
+*   diff customers never asked for.
+* - `.git/info/exclude` is per-clone, on-disk only, and exactly the git
+*   mechanism for "ignore these patterns in THIS working tree". Git creates
+*   an empty (template-commented) file on `git init` / `git clone`, so it
+*   already exists by the time we're called.
+*
+* Why this lives next to `extractIntoScratch`:
+* - The exclude glob is tied 1:1 to the scratch dir naming convention. If
+*   the prefix ever changes, the rule must change too. Defining both in the
+*   same file means a rename touches one place, not two.
+*
+* Best-effort: if the exclude file is missing (e.g. caller sandbox blocked
+* `git clone` and the dir layout differs) we log and continue — failing the
+* job over a missing git ignore wiring would be worse than the cosmetic
+* issue we're solving.
+*
+* Idempotent: callers may invoke this multiple times (dual-clone path, retry
+* after partial setup). We skip the append if the glob is already present.
+*
+* @param repoWorkDir - The git working tree root (the dir that contains
+*   `.git/`). For normal workflows this is the agent's job workDir; for
+*   global workflows it is the workflow repo dir (whose `.kici/` carries
+*   the scratch dirs).
+*/
+async function excludeScratchFromGit(repoWorkDir) {
+	const excludePath = join(repoWorkDir, ".git", "info", "exclude");
+	try {
+		const existing = await fsPromises.readFile(excludePath, "utf-8").catch(() => "");
+		if (existing.split("\n").some((line) => line.trim() === SCRATCH_DIR_GIT_EXCLUDE_GLOB)) return;
+		const suffix = existing.length === 0 || existing.endsWith("\n") ? "" : "\n";
+		await fsPromises.appendFile(excludePath, `${suffix}# kici: hide dep-restore scratch dirs from customer git status\n${SCRATCH_DIR_GIT_EXCLUDE_GLOB}\n`);
+	} catch (err) {
+		logger$10.warn("Failed to register scratch dir glob in .git/info/exclude", {
+			excludePath,
+			error: err instanceof Error ? err.message : String(err)
+		});
+	}
+}
+/**
 * Rewrite localhost URLs to use the orchestrator host.
 *
 * The orchestrator rewrites file:// cache URLs to http://localhost:PORT/...
@@ -2659,7 +2929,7 @@ async function cleanupScratch(scratchDir) {
 			force: true
 		});
 	} catch (cleanupErr) {
-		logger$9.warn("Scratch dir cleanup failed (orphan left behind)", {
+		logger$10.warn("Scratch dir cleanup failed (orphan left behind)", {
 			scratchDir,
 			error: cleanupErr instanceof Error ? cleanupErr.message : String(cleanupErr)
 		});
@@ -2684,7 +2954,7 @@ async function cleanupScratch(scratchDir) {
 */
 async function restoreDeps(workDir, depsUrl, depsHash) {
 	depsUrl = resolveOrchestratorUrl(depsUrl);
-	logger$9.info("Downloading dependency tarball", { url: depsUrl });
+	logger$10.info("Downloading dependency tarball", { url: depsUrl });
 	const kiciDir = join(workDir, ".kici");
 	if (depsUrl.startsWith("file://")) {
 		const localPath = fileURLToPath(depsUrl);
@@ -2698,7 +2968,7 @@ async function restoreDeps(workDir, depsUrl, depsHash) {
 		await moveScratchIntoRepo(scratchDir, workDir);
 		await cleanupScratch(scratchDir);
 		const sizeMB = (data.length / (1024 * 1024)).toFixed(2);
-		logger$9.info("Dependencies restored from cache (file)", {
+		logger$10.info("Dependencies restored from cache (file)", {
 			sizeMB,
 			targetDir: workDir
 		});
@@ -2707,7 +2977,7 @@ async function restoreDeps(workDir, depsUrl, depsHash) {
 	if (!depsUrl.startsWith("http://") && !depsUrl.startsWith("https://")) throw new Error(`Unsupported deps URL scheme: ${depsUrl}`);
 	let lastError;
 	for (let attempt = 0; attempt <= 2; attempt++) {
-		if (attempt > 0) logger$9.warn("Retrying dep tarball download", {
+		if (attempt > 0) logger$10.warn("Retrying dep tarball download", {
 			attempt,
 			url: depsUrl
 		});
@@ -2716,11 +2986,11 @@ async function restoreDeps(workDir, depsUrl, depsHash) {
 			if (depsHash && hash !== depsHash) throw new Error(`Dep tarball hash mismatch: expected ${depsHash}, got ${hash}`);
 			await moveScratchIntoRepo(scratchDir, workDir);
 			await cleanupScratch(scratchDir);
-			logger$9.info("Dependencies restored from cache (stream)", { targetDir: workDir });
+			logger$10.info("Dependencies restored from cache (stream)", { targetDir: workDir });
 			return;
 		} catch (err) {
 			lastError = err instanceof Error ? err : new Error(String(err));
-			logger$9.warn("Dep tarball download failed", {
+			logger$10.warn("Dep tarball download failed", {
 				attempt,
 				error: lastError.message
 			});
@@ -2728,12 +2998,12 @@ async function restoreDeps(workDir, depsUrl, depsHash) {
 	}
 	throw new Error(`Dep tarball download failed after 3 attempts: ${lastError?.message}`);
 }
-var logger$9, DOWNLOAD_TIMEOUT_MS$1, SCRATCH_DIR_BASENAME_PREFIX;
+var logger$10, DOWNLOAD_TIMEOUT_MS$1, SCRATCH_DIR_BASENAME_PREFIX, SCRATCH_DIR_GIT_EXCLUDE_GLOB;
 var init_dep_restore = __esmMin((() => {
-	logger$9 = createLogger({ prefix: "dep-restore" });
+	logger$10 = createLogger({ prefix: "dep-restore" });
 	DOWNLOAD_TIMEOUT_MS$1 = 300 * 1e3;
 	SCRATCH_DIR_BASENAME_PREFIX = ".dep-restore-scratch-";
-	`${SCRATCH_DIR_BASENAME_PREFIX}`;
+	SCRATCH_DIR_GIT_EXCLUDE_GLOB = `.kici/${SCRATCH_DIR_BASENAME_PREFIX}*`;
 }));
 //#endregion
 //#region src/execution/download.ts
@@ -2744,6 +3014,20 @@ var init_dep_restore = __esmMin((() => {
 * dep-restore.ts and workflow-loader.ts.
 */
 /**
+* Whether a failed upload attempt is worth repeating.
+*
+* A transport failure (connection refused, reset, DNS) never reached a
+* responder, and 5xx / 429 are the object-storage overload signals AWS
+* documents as retry-with-backoff (S3 answers `SlowDown` with 503). Every other
+* status is a decision the server will repeat: a 403 from an expired or
+* malformed signature, a 400 from a malformed request. Retrying those burns the
+* ceiling without a chance of success and delays the real error.
+*/
+function isRetryableUploadFailure(err) {
+	if (!(err instanceof PresignedUploadHttpError)) return true;
+	return err.statusCode >= 500 || err.statusCode === 429;
+}
+/**
 * Download content from an HTTP/HTTPS URL.
 *
 * Includes a 5-minute timeout to prevent the agent from hanging indefinitely
@@ -2767,21 +3051,10 @@ function downloadUrl(url) {
 		}).on("error", reject);
 	});
 }
-/**
-* Upload a buffer to a pre-signed S3 URL via HTTP PUT.
-*
-* Used for direct-to-S3 uploads of bundles and dep tarballs. Localhost /
-* 127.0.0.1 URLs are rewritten via `resolveOrchestratorUrl` so the
-* filesystem cache backend's signed URLs work from container agents that
-* can't reach the orchestrator's host loopback directly.
-*
-* @param url - The pre-signed URL to upload to
-* @param data - The buffer to upload
-*/
-function uploadToPresignedUrl(url, data) {
+/** One PUT of the whole buffer. Rejects with {@link PresignedUploadHttpError} on a non-2xx. */
+function putOnce(resolvedUrl, data, timeoutMs) {
 	return new Promise((resolve, reject) => {
-		const resolved = resolveOrchestratorUrl(url);
-		const parsed = new URL(resolved);
+		const parsed = new URL(resolvedUrl);
 		const req = (parsed.protocol === "https:" ? https : http).request({
 			hostname: parsed.hostname,
 			port: parsed.port,
@@ -2790,7 +3063,7 @@ function uploadToPresignedUrl(url, data) {
 			headers: { "Content-Length": data.length }
 		}, (res) => {
 			if (res.statusCode && (res.statusCode < 200 || res.statusCode >= 300)) {
-				reject(/* @__PURE__ */ new Error(`HTTP ${res.statusCode} uploading to pre-signed URL`));
+				reject(new PresignedUploadHttpError(res.statusCode));
 				res.resume();
 				return;
 			}
@@ -2798,14 +3071,80 @@ function uploadToPresignedUrl(url, data) {
 			res.on("end", () => resolve());
 			res.on("error", reject);
 		});
+		req.setTimeout(timeoutMs, () => {
+			req.destroy(/* @__PURE__ */ new Error(`Pre-signed upload timed out after ${timeoutMs}ms`));
+		});
 		req.on("error", reject);
 		req.end(data);
 	});
 }
-var DOWNLOAD_TIMEOUT_MS;
+/**
+* Upload a buffer to a pre-signed S3 URL via HTTP PUT, retrying a transient
+* failure.
+*
+* Used for direct-to-S3 uploads of bundles and dep tarballs. Localhost /
+* 127.0.0.1 URLs are rewritten via `resolveOrchestratorUrl` so the
+* filesystem cache backend's signed URLs work from container agents that
+* can't reach the orchestrator's host loopback directly.
+*
+* **Why retrying is safe here.** A pre-signed PUT writes one whole object at a
+* single key: there is no multipart session, no append, and no
+* server-generated identity, so a repeat attempt writes the same bytes to the
+* same key and the last write wins. S3 also only makes an object visible once
+* the body has been received in full, so an attempt that died mid-body left
+* nothing behind. A retry therefore cannot double-write or produce a torn
+* object — which is why every AWS SDK retries PUTs by default.
+*
+* Only a failure that can plausibly differ next time is repeated — see
+* {@link isRetryableUploadFailure}.
+*
+* @param url - The pre-signed URL to upload to
+* @param data - The buffer to upload
+* @param opts.baseDelayMs - Backoff before the first retry (doubles thereafter)
+* @param opts.timeoutMs - Per-attempt socket-inactivity timeout (see
+*   {@link UPLOAD_TIMEOUT_MS}); an override exists so a test can drive the
+*   stall path without waiting out the production budget.
+*/
+async function uploadToPresignedUrl(url, data, opts) {
+	const resolved = resolveOrchestratorUrl(url);
+	const baseDelayMs = opts?.baseDelayMs ?? UPLOAD_RETRY_BASE_DELAY_MS;
+	const timeoutMs = opts?.timeoutMs ?? UPLOAD_TIMEOUT_MS;
+	let lastError;
+	for (let attempt = 0; attempt <= 2; attempt++) {
+		if (attempt > 0) {
+			const delayMs = baseDelayMs * 2 ** (attempt - 1);
+			logger$9.warn("Retrying pre-signed upload", {
+				attempt,
+				delayMs,
+				error: lastError?.message
+			});
+			await new Promise((r) => setTimeout(r, delayMs));
+		}
+		try {
+			await putOnce(resolved, data, timeoutMs);
+			return;
+		} catch (err) {
+			lastError = err instanceof Error ? err : new Error(String(err));
+			if (!isRetryableUploadFailure(lastError)) throw lastError;
+		}
+	}
+	throw new Error(`Pre-signed upload failed after 3 attempts: ${lastError?.message}`);
+}
+var logger$9, DOWNLOAD_TIMEOUT_MS, UPLOAD_TIMEOUT_MS, UPLOAD_RETRY_BASE_DELAY_MS, PresignedUploadHttpError;
 var init_download = __esmMin((() => {
 	init_dep_restore();
+	logger$9 = createLogger({ prefix: "agent:download" });
 	DOWNLOAD_TIMEOUT_MS = 300 * 1e3;
+	UPLOAD_TIMEOUT_MS = 300 * 1e3;
+	UPLOAD_RETRY_BASE_DELAY_MS = 500;
+	PresignedUploadHttpError = class extends Error {
+		statusCode;
+		constructor(statusCode) {
+			super(`HTTP ${statusCode} uploading to pre-signed URL`);
+			this.statusCode = statusCode;
+			this.name = "PresignedUploadHttpError";
+		}
+	};
 }));
 //#endregion
 //#region src/execution/source-restore.ts
@@ -2889,6 +3228,44 @@ var init_timeout_util = __esmMin((() => {}));
 //#endregion
 //#region src/execution/init-runner.ts
 /**
+* Run a workflow's `filter` and report whether the workflow applies.
+*
+* Shared by both agent-side evaluation sites for a same-repo workflow: the init
+* job that gates each static job's dispatch, and the dynamic-eval job that gates
+* whether a generator runs at all. Both must reach the same verdict from the same
+* inputs, so neither builds the context itself.
+*
+* The context is built through `createFilterContext` rather than as an object
+* literal: the factory installs `changedFiles` as a throwing getter, so a filter
+* that reads the diff on an event that has none fails loudly instead of seeing an
+* empty list. A `false` verdict dispatches none of the workflow's own jobs, so a
+* silently-empty diff would suppress it on a mistake. On this same-repo path the
+* verdict is at least recoverable — the run row exists, carrying the `__init__*`
+* jobs, and this evaluation's own step log records the verdict; it is the
+* organization-wide path, which runs elsewhere, that leaves nothing behind.
+*
+* A throwing filter propagates: the evaluating job fails, which surfaces as a
+* failed run. "Could not decide" is never treated as "do not run" — that would
+* be a false green, the same reasoning `buildJobRuleCompletion` applies to a rule
+* whose `check()` threw.
+*/
+async function evaluateWorkflowFilter(workflow, event, input, timeoutMs) {
+	if (typeof workflow.filter !== "function") throw new Error(`Workflow '${workflow.name}' is recorded as declaring a filter, but its module exports none — the lock file is out of date. Run 'kici compile' and commit the result.`);
+	if (!input) throw new Error(`Workflow '${workflow.name}' declares a filter but the evaluating job supplied no filter context (source tree / changed files) to evaluate it against.`);
+	const filterFn = workflow.filter;
+	const ctx = createFilterContext({
+		sourceRepo: input.sourceRepo,
+		workflowRepo: input.workflowRepo,
+		event,
+		changedFiles: input.changedFiles,
+		changedFilesStatus: input.changedFilesStatus,
+		...input.env && { env: input.env },
+		...input.$ && { $: input.$ }
+	});
+	const verdict = await withTimeout(() => filterFn(ctx), timeoutMs, `filter for workflow '${workflow.name}'`);
+	return Boolean(verdict);
+}
+/**
 * Find a static job by name in a workflow's jobs array.
 * Skips dynamic job functions (factories).
 */
@@ -2907,15 +3284,25 @@ function findJobByName(workflow, jobName) {
 * -: If a dynamic function returns undefined/null, the field is left undefined.
 * -: Each dynamic function call is wrapped in a timeout (default 60s).
 *
+* A workflow-level `filter` is evaluated FIRST when `flags.hasFilter` is set. A
+* `false` verdict returns immediately: no job of that workflow will be
+* dispatched, so evaluating this one's dynamic fields would run customer code
+* whose result nothing can consume.
+*
 * @param workflow - The extracted Workflow object
 * @param jobName - Name of the job whose dynamic fields to evaluate
 * @param event - Normalized event envelope — same shape every dynamic-function call site receives.
 * @param flags - Which fields are dynamic and need evaluation
 * @param timeoutMs - Timeout per dynamic function call (default 60_000ms)
+* @param filterInput - Source tree + diff the workflow's `filter` reads. Required when `flags.hasFilter`.
 */
-async function evaluateDynamicFields(workflow, jobName, event, flags, timeoutMs = 6e4) {
-	const job = findJobByName(workflow, jobName);
+async function evaluateDynamicFields(workflow, jobName, event, flags, timeoutMs = 6e4, filterInput) {
 	const result = {};
+	if (flags.hasFilter) {
+		result.filterPassed = await evaluateWorkflowFilter(workflow, event, filterInput, timeoutMs);
+		if (!result.filterPassed) return result;
+	}
+	const job = findJobByName(workflow, jobName);
 	if (flags.dynamicMatrix && typeof job.matrix === "function") {
 		const matrixContext = {
 			$: (await import("zx")).$,
@@ -4012,6 +4399,231 @@ var init_dynamic_job_serializer = __esmMin((() => {
 		}
 	};
 	DYNAMIC_FIELD_TIMEOUT_MS = 6e4;
+}));
+//#endregion
+//#region src/execution/global-workflow-env.ts
+/**
+* Derive an `owner/repo` identifier from a clone URL, stripping the trailing
+* `.git` and any `http(s)://host/` prefix.
+*/
+function repoIdentifierFromUrl(repoUrl) {
+	return repoUrl.replace(/\.git$/, "").replace(/^https?:\/\/[^/]+\//, "");
+}
+/**
+* Inject the seven global-workflow env keys and return a restorer that puts
+* `process.env` back exactly as it was — each key reset to its prior value, or
+* deleted if it had none.
+*
+* **The restorer is mandatory for any caller in a long-lived process.** The
+* sandbox may ignore it: it runs one job per forked child, which exits. The
+* pre-dispatch global eval round may NOT: it runs in the agent process, which
+* serves many dispatches from one `JobRunner`. Leaving the keys set there is
+* this module's own hazard running backwards — a later NON-global
+* `DynamicJobFn` evaluation builds its generator context with
+* `env: process.env` still carrying `KICI_IS_GLOBAL_WORKFLOW=true` and a
+* `KICI_SOURCE_REPO_PATH` pointing at a deleted work directory, while that
+* job's own sandbox re-evaluation sees neither (`buildSanitizedEnv` scrubs the
+* whole `KICI_*` namespace on the trusted profile, and the default profile is
+* allowlist-only). That is the same two-worlds determinism failure, injected
+* into an unrelated job.
+*
+* `RepoInfo.ref` / `.sha` are optional, so an evaluation with no checkout
+* metadata writes an empty string rather than leaving the key unset — matching
+* how `KICI_WORKFLOW_REPO` already handles a missing identifier. Assigning
+* `undefined` to a `process.env` key would stringify to `"undefined"`, which is
+* worse than either.
+*/
+function applyGlobalWorkflowEnv(repos) {
+	const prior = GLOBAL_WORKFLOW_ENV_KEYS.map((key) => [key, process.env[key]]);
+	process.env.KICI_IS_GLOBAL_WORKFLOW = "true";
+	process.env.KICI_WORKFLOW_REPO_PATH = repos.workflowRepo.path;
+	process.env.KICI_SOURCE_REPO_PATH = repos.sourceRepo.path;
+	process.env.KICI_SOURCE_REPO = repos.sourceRepo.identifier;
+	process.env.KICI_SOURCE_BRANCH = repos.sourceRepo.ref ?? "";
+	process.env.KICI_SOURCE_SHA = repos.sourceRepo.sha ?? "";
+	process.env.KICI_WORKFLOW_REPO = repos.workflowRepo.identifier;
+	return () => {
+		for (const [key, value] of prior) if (value === void 0) delete process.env[key];
+		else process.env[key] = value;
+	};
+}
+var GLOBAL_WORKFLOW_ENV_KEYS;
+var init_global_workflow_env = __esmMin((() => {
+	GLOBAL_WORKFLOW_ENV_KEYS = [
+		"KICI_IS_GLOBAL_WORKFLOW",
+		"KICI_WORKFLOW_REPO_PATH",
+		"KICI_SOURCE_REPO_PATH",
+		"KICI_SOURCE_REPO",
+		"KICI_SOURCE_BRANCH",
+		"KICI_SOURCE_SHA",
+		"KICI_WORKFLOW_REPO"
+	];
+}));
+//#endregion
+//#region src/execution/global-eval-runner.ts
+function buildRoundState(args) {
+	const loadModule = args.loadModule ?? (async (sourceFile) => (await loadWorkflowSource(args.workflowDir, sourceFile)).module);
+	return {
+		args,
+		$: args.$ ?? $,
+		log: args.log ?? NOOP_LOG,
+		kici: args.kici ?? buildKiciApi(() => Promise.reject(/* @__PURE__ */ new Error("Agent API not available"))),
+		loadModule,
+		moduleCache: /* @__PURE__ */ new Map()
+	};
+}
+/** Load a workflow, caching per source file so a shared module is imported once. */
+async function loadWorkflowCached(shared, sourceFile, workflowName) {
+	let pending = shared.moduleCache.get(sourceFile);
+	if (!pending) {
+		pending = shared.loadModule(sourceFile);
+		shared.moduleCache.set(sourceFile, pending);
+	}
+	return extractWorkflow(await pending, workflowName);
+}
+/**
+* Run every `DynamicJobFn` the workflow declares and serialize the result.
+*
+* The generator context is built through `buildGeneratorContext` with the same
+* repo pair the sandbox re-evaluation gets, so the two calls a generator
+* receives cannot drift apart. Returns `undefined` when the workflow declares
+* no generators, which keeps the `jobs` key off the wire entirely.
+*/
+async function generateDynamicJobs(workflow, shared) {
+	const { args } = shared;
+	const generators = workflow.jobs.filter(isDynamicJobFn);
+	if (generators.length === 0) return void 0;
+	const serializerCtx = {
+		event: args.event,
+		$: shared.$,
+		log: shared.log,
+		env: process.env,
+		workflowName: workflow.name
+	};
+	const jobs = [];
+	for (const generator of generators) {
+		const generated = await generator(buildGeneratorContext({
+			workflowName: workflow.name,
+			event: args.event,
+			env: process.env,
+			repos: args.repos,
+			$: shared.$,
+			log: shared.log,
+			kici: shared.kici
+		}));
+		jobs.push(...await serializeJobsToLock(generated, serializerCtx));
+	}
+	return jobs;
+}
+/**
+* Evaluate one candidate to a verdict: run its `filter` if it declares one,
+* then its generators if it survives.
+*/
+async function evaluateCandidateInner(candidate, shared) {
+	const { args } = shared;
+	const workflow = await loadWorkflowCached(shared, candidate.sourceFile, candidate.workflowName);
+	if (candidate.hasFilter) {
+		if (typeof workflow.filter !== "function") throw new Error(`Workflow '${candidate.workflowName}' is recorded as declaring a filter, but its module exports none — the lock file is out of date. Run 'kici compile' and commit the result.`);
+		const filterCtx = createFilterContext({
+			sourceRepo: args.repos.sourceRepo,
+			workflowRepo: args.repos.workflowRepo,
+			event: args.event,
+			changedFiles: args.changedFiles,
+			changedFilesStatus: args.changedFilesStatus,
+			env: process.env,
+			$: shared.$
+		});
+		if (!await workflow.filter(filterCtx)) return {
+			workflowName: candidate.workflowName,
+			run: false
+		};
+	}
+	const jobs = await generateDynamicJobs(workflow, shared);
+	return {
+		workflowName: candidate.workflowName,
+		run: true,
+		...jobs && { jobs }
+	};
+}
+/**
+* Evaluate one candidate, never throwing. A failure — a throwing filter, a
+* broken generator, a blown per-candidate budget — becomes an indeterminate
+* verdict so the round's other candidates still get real answers.
+*/
+async function evaluateCandidate(candidate, shared) {
+	try {
+		return await withTimeout(() => evaluateCandidateInner(candidate, shared), shared.args.candidateTimeoutMs, `global workflow '${candidate.workflowName}'`);
+	} catch (error) {
+		return {
+			workflowName: candidate.workflowName,
+			run: false,
+			indeterminate: true,
+			reason: error instanceof Error ? error.message : String(error)
+		};
+	}
+}
+/**
+* Evaluate candidates one at a time — they share one checkout and one working
+* directory, so a parallel `$` would race on cwd.
+*
+* Stops before starting a candidate once the round deadline has passed or the
+* caller aborted. That check is what keeps the sequential guarantee meaningful
+* past a timeout: `withTimeout` races rather than cancels, so without it the
+* loop would keep launching every remaining candidate — each up to
+* `candidateTimeoutMs` — into a work directory the job has already reported on
+* and whose cleanup has already deleted. With it, at most one candidate is ever
+* in flight past the deadline.
+*
+* Results are appended to the caller's array as they land, so a round that
+* blows its own budget can still report the verdicts it did establish rather
+* than discarding the work.
+*/
+async function evaluateAllCandidates(shared, into, deadline) {
+	for (const candidate of shared.args.candidates) {
+		if (shared.args.signal?.aborted || Date.now() >= deadline) return;
+		into.push(await evaluateCandidate(candidate, shared));
+	}
+}
+/**
+* Run one global eval round and return every candidate's verdict, in candidate
+* order. Never throws: a round that exceeds `roundTimeoutMs` reports whatever
+* it established and marks the rest indeterminate.
+*/
+async function runGlobalEvalRound(args) {
+	const restoreEnv = applyGlobalWorkflowEnv(args.repos);
+	const shared = buildRoundState(args);
+	const settled = [];
+	let stopReason;
+	try {
+		await withTimeout(() => evaluateAllCandidates(shared, settled, Date.now() + args.roundTimeoutMs), args.roundTimeoutMs, `global eval round (${args.candidates.length} candidate(s))`);
+	} catch (error) {
+		stopReason = error instanceof Error ? error.message : String(error);
+	} finally {
+		restoreEnv();
+	}
+	const candidates = [...settled];
+	const reason = stopReason ?? (args.signal?.aborted ? "global eval round was cancelled before this candidate was evaluated" : "global eval round deadline reached before this candidate was evaluated");
+	for (const candidate of args.candidates.slice(candidates.length)) candidates.push({
+		workflowName: candidate.workflowName,
+		run: false,
+		indeterminate: true,
+		reason
+	});
+	return { candidates };
+}
+var NOOP_LOG;
+var init_global_eval_runner = __esmMin((() => {
+	init_timeout_util();
+	init_generator_context();
+	init_global_workflow_env();
+	init_workflow_loader();
+	init_dynamic_job_serializer();
+	NOOP_LOG = {
+		info: () => {},
+		warn: () => {},
+		error: () => {},
+		debug: () => {}
+	};
 })), DEFAULT_MAX_LOG_SIZE_BYTES, DEFAULT_FLUSH_INTERVAL_MS, DEFAULT_FLUSH_LINE_THRESHOLD, PAUSE_SAFETY_TIMEOUT_MS, LogStreamer;
 var init_log_streamer = __esmMin((() => {
 	init_prometheus();
@@ -6964,6 +7576,9 @@ var init_sandbox = __esmMin((() => {
 var job_runner_exports = /* @__PURE__ */ __exportAll({
 	JobRunner: () => JobRunner$1,
 	buildEvalNeedsContext: () => buildEvalNeedsContext,
+	buildEvalShell: () => buildEvalShell,
+	buildInitFilterInput: () => buildInitFilterInput,
+	ensureFilterSourceDir: () => ensureFilterSourceDir,
 	resolveJobWorkDir: () => resolveJobWorkDir,
 	resolveRunnerBundlePath: () => resolveRunnerBundlePath
 });
@@ -6979,6 +7594,192 @@ async function fileExists(p) {
 	}
 }
 /**
+* Build the source / workflow repo pair the round hands to every filter and
+* generator. Mirrors the sandbox's own `setupGlobalWorkflowEnv` construction so
+* a generator's two evaluations see the same identifiers, refs, and shas — only
+* the absolute paths differ, and those are never compared.
+*/
+function buildRoundRepos(dispatch, config, workflowDir, sourceDir) {
+	return {
+		workflowRepo: {
+			identifier: config.workflowRepoIdentifier ?? repoIdentifierFromUrl(config.workflowRepoUrl),
+			path: workflowDir,
+			ref: config.workflowRef,
+			sha: config.workflowSha
+		},
+		sourceRepo: {
+			identifier: repoIdentifierFromUrl(dispatch.repoUrl),
+			path: sourceDir,
+			ref: dispatch.ref,
+			sha: dispatch.sha
+		}
+	};
+}
+/**
+* Resolve the changed-files list a `filter` reads — for a global eval round and
+* for a filter-bearing init job alike.
+*
+* Ground truth is the agent's own source clone; an already-`fetched` list from
+* the orchestrator is a free fast-path. A diff-less event (schedule / tag /
+* manual) resolves to `unavailable`, which makes `ctx.changedFiles` throw
+* rather than read as an empty diff — a `filter` returning false produces no
+* run at all, so a silently-empty diff would suppress the workflow with no
+* artifact anywhere to inspect.
+*/
+async function resolveEvalChangedFiles(dispatch, event, sourceDir) {
+	const ev = event;
+	if (ev.changedFilesStatus === "fetched") return {
+		files: ev.changedFiles ?? [],
+		status: "fetched"
+	};
+	return computeChangedFiles(sourceDir, event, dispatch.sourceAuth ?? dispatch.workflowAuth ?? (dispatch.token ? {
+		kind: "basic",
+		user: "x-access-token",
+		secret: dispatch.token
+	} : void 0));
+}
+/**
+* Materialize the source tree a non-global workflow's `filter` reads through
+* `ctx.sourceRepo.path`.
+*
+* An init or dynamic-eval job normally restores only `.kici/` from the cached
+* source tarball — enough to import the workflow module, but a directory with no
+* repo in it. A filter that reads a file or shells out against that path would
+* get a confidently wrong answer, and `changedFiles` could not be computed at
+* all, so a filter-bearing job clones the source repo into a sibling directory.
+*
+* When no tarball was attached the job already cloned the whole repo into
+* `workDir`, and that clone is reused rather than duplicated — including the
+* local working-tree case, where there is no repo url and `workDir` IS the tree.
+*
+* A tarball with no repo url is the one combination that cannot be honoured:
+* `workDir` holds `.kici/` alone and there is nothing to clone from. Returning it
+* would hand the filter a directory in which every path test answers "absent" —
+* the exact silent lie this function exists to prevent — so it throws instead.
+*/
+async function ensureFilterSourceDir(dispatch, workDir) {
+	if (!dispatch.sourceTarUrl) return workDir;
+	if (!dispatch.repoUrl) throw new Error("Workflow declares a filter, but this job restored its source from the cache with no repo url to clone from — the filter would see an empty tree. Re-run with a source repository configured, or remove the filter.");
+	const sourceDir = join(workDir, FILTER_SOURCE_DIRNAME);
+	const sourceAuth = dispatch.sourceAuth;
+	await gitClone({
+		repoUrl: dispatch.repoUrl,
+		ref: dispatch.ref,
+		sha: dispatch.sha,
+		workDir: sourceDir,
+		gitAuth: sourceAuth,
+		token: sourceAuth ? void 0 : dispatch.token
+	});
+	return sourceDir;
+}
+/**
+* Restore deps, materialize the workflow source, and install `.kici/`
+* dependencies for a dynamic-eval job — everything that has to exist before its
+* workflow module can be imported.
+*
+* The init handler performs the same three steps against its own log wording and
+* keeps its own copy: sharing one helper would have to either move that
+* handler's `logger.info` call site (which Loki keys off) or parameterize it,
+* and neither is worth it for twenty lines.
+*/
+async function materializeEvalWorkspace(dispatch, workDir, log) {
+	if (dispatch.depsUrl) {
+		log("Restoring dependencies from cache");
+		await restoreDeps(workDir, dispatch.depsUrl, dispatch.depsHash);
+		log("Dependencies restored");
+	}
+	if (dispatch.sourceTarUrl) {
+		log("Restoring workflow source from cached tarball");
+		await restoreSource(workDir, dispatch.sourceTarUrl);
+	} else {
+		log(`Cloning ${dispatch.repoUrl} ref=${dispatch.ref}`);
+		const cloneStart = Date.now();
+		await gitClone({
+			repoUrl: dispatch.repoUrl,
+			ref: dispatch.ref,
+			sha: dispatch.sha,
+			workDir,
+			gitAuth: dispatch.sourceAuth,
+			token: dispatch.sourceAuth ? void 0 : dispatch.token
+		});
+		cloneDurationSeconds.record((Date.now() - cloneStart) / 1e3);
+	}
+	const kiciDir = join(workDir, ".kici");
+	if (!dispatch.depsUrl && await fileExists(join(kiciDir, "package.json"))) {
+		log("Installing dependencies locally");
+		await installDeps(kiciDir, {
+			npmRegistries: dispatch.npmRegistries,
+			installEnvSecrets: dispatch.installEnvSecrets,
+			jobIdShort: dispatch.jobId.slice(0, 8)
+		});
+	}
+}
+/**
+* Build the context a non-global workflow's `filter` is evaluated against.
+*
+* `sourceRepo` and `workflowRepo` are the same repo — that is what "non-global"
+* means — so both carry the same identifier, path, ref, and sha. The zx shell is
+* rooted at the source tree and streams into the evaluating step's log, matching
+* what the global eval round hands its own filters.
+*
+* They are two distinct objects all the same. Being the same repo is a fact
+* about their VALUES, not a licence to hand the author one object under two
+* names: a filter that mutated `ctx.sourceRepo` would silently see
+* `ctx.workflowRepo` change with it, which happens on no other path.
+*/
+async function buildInitFilterInput(dispatch, event, workDir, emit) {
+	const sourceDir = await ensureFilterSourceDir(dispatch, workDir);
+	const diff = await resolveEvalChangedFiles(dispatch, event, sourceDir);
+	const repo = {
+		identifier: repoIdentifierFromUrl(dispatch.repoUrl),
+		path: sourceDir,
+		ref: dispatch.ref,
+		sha: dispatch.sha
+	};
+	return {
+		sourceRepo: repo,
+		workflowRepo: { ...repo },
+		changedFiles: diff.files,
+		changedFilesStatus: diff.status,
+		env: process.env,
+		$: await buildEvalShell(sourceDir, emit)
+	};
+}
+/**
+* Build the per-invocation zx `$` a global eval round hands to filters and
+* generators, so a `await $\`…\`` inside one is visible in the eval step's log.
+*
+* **`env` is the LIVE `process.env` reference, never a spread.** A spread is a
+* snapshot taken when the shell is built, which is before the round applies the
+* seven `KICI_*` keys — so a filter that shells out (`$\`printenv
+* KICI_SOURCE_REPO_PATH\``, or any subprocess inheriting env) would see nothing
+* here while the sandbox re-evaluation's ambient `$` resolves `process.env`
+* after `setupGlobalWorkflowEnv` has run and does see them. That is the same
+* two-worlds determinism failure the cwd choice below exists to prevent, one
+* layer down. Passing the live reference reproduces the ambient `$`'s own
+* behaviour, which is what the sandbox uses.
+*
+* `verbose: true` + `makeStreamingZxLog` honors a per-call `quiet: true`, so a
+* decrypted secret never leaks into the log.
+*
+* `emit` is a callback rather than the `LogStreamer` itself so the caller can
+* route it through its own closed-guard: `LogStreamer.destroy()` sets no closed
+* flag and `addLine` buffers unconditionally, so a subprocess line arriving
+* after the step was reported would otherwise emit a `log.chunk` for a terminal
+* step. That is the likeliest path for it — an orphaned candidate is usually
+* orphaned *because* it is waiting on a subprocess.
+*/
+async function buildEvalShell(cwd, emit) {
+	const { $: zx$ } = await import("zx");
+	return zx$({
+		cwd,
+		env: process.env,
+		verbose: true,
+		quiet: false,
+		log: makeStreamingZxLog(emit)
+	});
+}
+/**
 * Resolve the absolute path to the compiled workflow-runner.js entry point.
 *
 * The runner is a separate rolldown entry point. Its location depends on the
@@ -7062,9 +7863,10 @@ async function resolveJobWorkDir(inPlace, repoUrl) {
 		inPlace: false
 	};
 }
-var logger$2, JobRunner$1;
+var logger$2, DEFAULT_GLOBAL_EVAL_ROUND_TIMEOUT_MS, DEFAULT_GLOBAL_EVAL_CANDIDATE_TIMEOUT_MS, FILTER_SOURCE_DIRNAME, JobRunner$1;
 var init_job_runner = __esmMin((() => {
 	init_git_clone();
+	init_changed_files();
 	init_workflow_loader();
 	init_source_packer();
 	init_source_restore();
@@ -7076,6 +7878,9 @@ var init_job_runner = __esmMin((() => {
 	init_timeout_util();
 	init_streaming_zx_log();
 	init_dynamic_job_serializer();
+	init_generator_context();
+	init_global_workflow_env();
+	init_global_eval_runner();
 	init_log_streamer();
 	init_overlay_applier();
 	init_dep_installer();
@@ -7085,6 +7890,9 @@ var init_job_runner = __esmMin((() => {
 	init_sandbox();
 	init_prometheus();
 	logger$2 = createLogger({ prefix: "job-runner" });
+	DEFAULT_GLOBAL_EVAL_ROUND_TIMEOUT_MS = 12e4;
+	DEFAULT_GLOBAL_EVAL_CANDIDATE_TIMEOUT_MS = 2e4;
+	FILTER_SOURCE_DIRNAME = "__kici_filter_source__";
 	JobRunner$1 = class {
 		send;
 		config;
@@ -7180,6 +7988,10 @@ var init_job_runner = __esmMin((() => {
 				await this.handleInitJob(dispatch, workDir, abortController);
 				return true;
 			}
+			if (jobConfig.globalEvalRound === true) {
+				await this.handleGlobalEvalRound(dispatch, workDir, abortController);
+				return true;
+			}
 			if (jobConfig.dynamicJobFn === true) {
 				await this.handleDynamicJobFn(dispatch, workDir, abortController);
 				return true;
@@ -7595,6 +8407,53 @@ var init_job_runner = __esmMin((() => {
 			}
 		}
 		/**
+		* Materialize the init job's workflow source into `workDir`. A test run ships
+		* its full working tree as an encrypted overlay tarball (`fullRepo`) rather
+		* than a git repo, so skip the clone and let the overlay populate the
+		* workspace — the same handling the normal execution-job path uses. Otherwise
+		* restore from the cached tarball if present, else clone. In every case, apply
+		* an attached overlay tarball afterward (test runs with uncommitted changes;
+		* for a fullRepo run this is what actually populates the workspace, so the
+		* init job resolves a dynamic context against the real source tree instead of
+		* an empty directory).
+		*/
+		async materializeInitJobSource(dispatch, workDir, initLog) {
+			const initJobConfig = dispatch.jobConfig;
+			if (initJobConfig.fullRepo) {
+				initLog("Test run: materializing workspace from overlay (no clone)");
+				await fsPromises.mkdir(workDir, { recursive: true });
+			} else if (dispatch.sourceTarUrl) {
+				initLog("Restoring workflow source from cached tarball");
+				await restoreSource(workDir, dispatch.sourceTarUrl);
+			} else {
+				initLog(`Cloning ${dispatch.repoUrl} (ref: ${dispatch.ref})`);
+				const cloneStart = Date.now();
+				await gitClone({
+					repoUrl: dispatch.repoUrl,
+					ref: dispatch.ref,
+					sha: dispatch.sha,
+					workDir,
+					gitAuth: dispatch.sourceAuth,
+					token: dispatch.sourceAuth ? void 0 : dispatch.token
+				});
+				cloneDurationSeconds.record((Date.now() - cloneStart) / 1e3);
+			}
+			if (initJobConfig.tarballUrl && initJobConfig.cliPublicKey && initJobConfig.orchestratorPrivateKey) {
+				initLog("Applying overlay tarball for test run");
+				const overlayResult = await applyOverlay({
+					tarballUrl: initJobConfig.tarballUrl,
+					cliPublicKey: initJobConfig.cliPublicKey,
+					orchestratorPrivateKey: initJobConfig.orchestratorPrivateKey,
+					repoDir: workDir
+				});
+				logger$2.info("Init job: overlay applied", {
+					jobId: dispatch.jobId,
+					filesApplied: overlayResult.filesApplied,
+					filesDeleted: overlayResult.filesDeleted
+				});
+			}
+		}
+		/**
 		* Phase 2 of build: install dependencies locally if needed for the build,
 		* and (when the orchestrator has flagged the dep cache as stale) pack
 		* `.kici/node_modules/` into a tarball and upload it to the deps cache.
@@ -7670,6 +8529,169 @@ var init_job_runner = __esmMin((() => {
 			});
 		}
 		/**
+		* Clone both repos for a global eval round and materialize the workflow
+		* repo's dependencies, mirroring the sandbox's own dual-clone: the workflow
+		* repo under `<workDir>/workflow`, the source repo under `<workDir>/source`.
+		*
+		* `.kici/` lives in the WORKFLOW repo for a global workflow, so deps and the
+		* scratch-dir git exclude both apply to that checkout, never the source one.
+		*/
+		async checkoutForGlobalEvalRound(dispatch, config, workflowDir, sourceDir, log) {
+			const workflowAuth = dispatch.workflowAuth ?? dispatch.sourceAuth;
+			const sourceAuth = dispatch.sourceAuth ?? dispatch.workflowAuth;
+			await fsPromises.mkdir(workflowDir, { recursive: true });
+			await fsPromises.mkdir(sourceDir, { recursive: true });
+			log(`Cloning workflow repo ${config.workflowRepoUrl} (ref: ${config.workflowRef ?? ""})`);
+			const cloneStart = Date.now();
+			await gitClone({
+				repoUrl: config.workflowRepoUrl,
+				ref: config.workflowRef ?? "",
+				sha: config.workflowSha ?? "",
+				workDir: workflowDir,
+				gitAuth: workflowAuth,
+				token: workflowAuth ? void 0 : dispatch.token
+			});
+			await excludeScratchFromGit(workflowDir);
+			log(`Cloning source repo ${dispatch.repoUrl} (ref: ${dispatch.ref})`);
+			await gitClone({
+				repoUrl: dispatch.repoUrl,
+				ref: dispatch.ref,
+				sha: dispatch.sha,
+				workDir: sourceDir,
+				gitAuth: sourceAuth,
+				token: sourceAuth ? void 0 : dispatch.token
+			});
+			cloneDurationSeconds.record((Date.now() - cloneStart) / 1e3);
+			if (dispatch.depsUrl) {
+				log("Restoring dependencies from cache");
+				await restoreDeps(workflowDir, dispatch.depsUrl, dispatch.depsHash);
+			}
+			if (dispatch.sourceTarUrl) {
+				log("Restoring workflow source from cached tarball");
+				await restoreSource(workflowDir, dispatch.sourceTarUrl);
+			}
+			const kiciDir = join(workflowDir, ".kici");
+			if (!dispatch.depsUrl && await fileExists(join(kiciDir, "package.json"))) {
+				log("Installing dependencies locally");
+				await installDeps(kiciDir, {
+					npmRegistries: dispatch.npmRegistries,
+					installEnvSecrets: dispatch.installEnvSecrets,
+					jobIdShort: dispatch.jobId.slice(0, 8)
+				});
+			}
+		}
+		/**
+		* Handle a pre-run global eval round.
+		*
+		* The round runs once per (event × workflow repo) BEFORE any run row exists:
+		* it checks out the workflow repo and the source repo, then runs each
+		* candidate global workflow's `filter` and — for a survivor — its
+		* `DynamicJobFn`s, so the orchestrator learns which workflows apply to this
+		* source repo and which jobs each one generates.
+		*
+		* A candidate that fails is reported indeterminate inside the result, not as
+		* a job failure: the round carries several unrelated org-wide workflows, and
+		* one broken filter must not suppress the rest. The job itself fails only
+		* when the checkout or the round machinery breaks.
+		*/
+		async handleGlobalEvalRound(dispatch, workDir, abortController) {
+			const { runId, jobId, jobConfig } = dispatch;
+			const config = jobConfig;
+			const workflowDir = join(workDir, "workflow");
+			const sourceDir = join(workDir, "source");
+			logger$2.info("Starting global eval round", {
+				jobId,
+				candidateCount: config.candidates.length,
+				workflowRepoIdentifier: config.workflowRepoIdentifier
+			});
+			this.sendJobStatus(dispatch, ExecutionJobStatus.enum.running);
+			const evalStreamer = this.createStepStreamer(dispatch, 0);
+			let streamerClosed = false;
+			const evalLog = (msg) => {
+				if (!streamerClosed) evalStreamer.addLine(msg);
+			};
+			const evalStreamLine = (line, stream) => {
+				if (!streamerClosed) evalStreamer.addLine(line, stream);
+			};
+			const closeStreamer = async () => {
+				await evalStreamer.flush();
+				evalStreamer.destroy();
+				streamerClosed = true;
+			};
+			const evalSink = { addLine: (line) => evalLog(line) };
+			this.sendStepStatus(dispatch, 0, "global-eval", ExecutionStepStatus.enum.running);
+			const heartbeatTimer = setInterval(() => {
+				this.send({
+					type: "job.heartbeat",
+					runId,
+					jobId,
+					timestamp: Date.now()
+				});
+			}, this.config.jobHeartbeatIntervalMs);
+			try {
+				if (abortController.signal.aborted) {
+					await closeStreamer();
+					this.sendStepStatus(dispatch, 0, "global-eval", ExecutionStepStatus.enum.skipped, void 0, evalStreamer.getTotalBytes());
+					this.sendJobStatus(dispatch, ExecutionJobStatus.enum.cancelled);
+					return;
+				}
+				await this.checkoutForGlobalEvalRound(dispatch, config, workflowDir, sourceDir, evalLog);
+				const diff = await resolveEvalChangedFiles(dispatch, config.event, sourceDir);
+				const evalShell = await buildEvalShell(workDir, evalStreamLine);
+				const roundResult = await runCaptured(evalSink, () => runGlobalEvalRound({
+					workflowDir,
+					sourceDir,
+					repos: buildRoundRepos(dispatch, config, workflowDir, sourceDir),
+					candidates: config.candidates,
+					event: config.event,
+					changedFiles: diff.files,
+					changedFilesStatus: diff.status,
+					roundTimeoutMs: config.roundTimeoutMs ?? DEFAULT_GLOBAL_EVAL_ROUND_TIMEOUT_MS,
+					candidateTimeoutMs: config.candidateTimeoutMs ?? DEFAULT_GLOBAL_EVAL_CANDIDATE_TIMEOUT_MS,
+					signal: abortController.signal,
+					$: evalShell,
+					log: {
+						info: (msg) => evalLog(msg),
+						warn: (msg) => evalLog(`WARN: ${msg}`),
+						error: (msg) => evalLog(`ERROR: ${msg}`),
+						debug: (msg) => evalLog(`DEBUG: ${msg}`)
+					},
+					kici: buildKiciApi(this._sendApiRequest ? withBootstrapInterception((method, params) => this._sendApiRequest(method, params ?? {})) : () => Promise.reject(/* @__PURE__ */ new Error("Agent API not available")))
+				}));
+				const running = roundResult.candidates.filter((c) => c.run).length;
+				const indeterminate = roundResult.candidates.filter((c) => c.indeterminate).length;
+				logger$2.info("Global eval round completed", {
+					jobId,
+					candidateCount: roundResult.candidates.length,
+					running,
+					indeterminate
+				});
+				evalLog(`Global eval round completed: ${running} of ${roundResult.candidates.length} workflow(s) apply` + (indeterminate > 0 ? ` (${indeterminate} indeterminate)` : ""));
+				for (const candidate of roundResult.candidates) if (candidate.indeterminate) evalLog(`  ${candidate.workflowName}: indeterminate — ${candidate.reason ?? "unknown"}`);
+				await closeStreamer();
+				this.sendStepStatus(dispatch, 0, "global-eval", ExecutionStepStatus.enum.success, void 0, evalStreamer.getTotalBytes());
+				this.sendJobStatus(dispatch, ExecutionJobStatus.enum.success, {
+					globalEvalResult: roundResult,
+					globalEvalComplete: true
+				});
+			} catch (err) {
+				const errorMsg = toErrorMessage(err);
+				logger$2.error("Global eval round failed", {
+					jobId,
+					error: errorMsg
+				});
+				evalLog(`Error: ${errorMsg}`);
+				await closeStreamer();
+				this.sendStepStatus(dispatch, 0, "global-eval", ExecutionStepStatus.enum.failed, { error: errorMsg }, evalStreamer.getTotalBytes());
+				this.sendJobStatus(dispatch, ExecutionJobStatus.enum.failed, {
+					error: errorMsg,
+					globalEvalFailed: true
+				});
+			} finally {
+				clearInterval(heartbeatTimer);
+			}
+		}
+		/**
 		* Handle an init-only job.
 		*
 		* Init jobs evaluate dynamic functions (environment, env, concurrencyGroup)
@@ -7691,8 +8713,20 @@ var init_job_runner = __esmMin((() => {
 			});
 			this.sendJobStatus(dispatch, ExecutionJobStatus.enum.running);
 			const initStreamer = this.createStepStreamer(dispatch, 0);
-			const initLog = (msg) => initStreamer.addLine(msg);
-			const initSink = { addLine: (line) => initStreamer.addLine(line) };
+			let streamerClosed = false;
+			const initLog = (msg) => {
+				if (!streamerClosed) initStreamer.addLine(msg);
+			};
+			const initStreamLine = (line, stream) => {
+				if (!streamerClosed) initStreamer.addLine(line, stream);
+			};
+			const closeStreamer = async () => {
+				if (streamerClosed) return;
+				streamerClosed = true;
+				await initStreamer.flush();
+				initStreamer.destroy();
+			};
+			const initSink = { addLine: (line) => initLog(line) };
 			this.sendStepStatus(dispatch, 0, "init", ExecutionStepStatus.enum.running);
 			const heartbeatTimer = setInterval(() => {
 				this.send({
@@ -7704,8 +8738,7 @@ var init_job_runner = __esmMin((() => {
 			}, this.config.jobHeartbeatIntervalMs);
 			try {
 				if (abortController.signal.aborted) {
-					await initStreamer.flush();
-					initStreamer.destroy();
+					await closeStreamer();
 					this.sendStepStatus(dispatch, 0, "init", ExecutionStepStatus.enum.skipped, void 0, initStreamer.getTotalBytes());
 					this.sendJobStatus(dispatch, ExecutionJobStatus.enum.cancelled);
 					return;
@@ -7714,22 +8747,7 @@ var init_job_runner = __esmMin((() => {
 					initLog("Restoring dependencies from cache");
 					await restoreDeps(workDir, dispatch.depsUrl, dispatch.depsHash);
 				}
-				if (dispatch.sourceTarUrl) {
-					initLog("Restoring workflow source from cached tarball");
-					await restoreSource(workDir, dispatch.sourceTarUrl);
-				} else {
-					initLog(`Cloning ${dispatch.repoUrl} (ref: ${dispatch.ref})`);
-					const cloneStart = Date.now();
-					await gitClone({
-						repoUrl: dispatch.repoUrl,
-						ref: dispatch.ref,
-						sha: dispatch.sha,
-						workDir,
-						gitAuth: dispatch.sourceAuth,
-						token: dispatch.sourceAuth ? void 0 : dispatch.token
-					});
-					cloneDurationSeconds.record((Date.now() - cloneStart) / 1e3);
-				}
+				await this.materializeInitJobSource(dispatch, workDir, initLog);
 				const kiciDir = join(workDir, ".kici");
 				const hasPackage = await fileExists(join(kiciDir, "package.json"));
 				logger$2.info("Init job: checking deps", {
@@ -7745,26 +8763,29 @@ var init_job_runner = __esmMin((() => {
 						jobIdShort: dispatch.jobId.slice(0, 8)
 					});
 				}
+				const filterInput = config.hasFilter ? await buildInitFilterInput(dispatch, config.event, workDir, initStreamLine) : void 0;
 				const initResult = await runCaptured(initSink, async () => {
 					const { module } = await loadWorkflowSource(workDir, config.source, config.contentHash, config.resolvedHashFiles);
 					const workflow = extractWorkflow(module, config.workflowName);
-					initLog(`Evaluating dynamic fields for job '${config.targetJobName}' (env=${config.dynamicEnv} context=${config.dynamicContext} concurrencyGroup=${config.dynamicConcurrencyGroup} matrix=${config.dynamicMatrix ?? false})`);
+					initLog(`Evaluating dynamic fields for job '${config.targetJobName}' (env=${config.dynamicEnv} context=${config.dynamicContext} concurrencyGroup=${config.dynamicConcurrencyGroup} matrix=${config.dynamicMatrix ?? false} filter=${config.hasFilter ?? false})`);
 					return evaluateDynamicFields(workflow, config.targetJobName, config.event, {
 						dynamicContext: config.dynamicContext,
 						dynamicEnv: config.dynamicEnv,
 						dynamicConcurrencyGroup: config.dynamicConcurrencyGroup,
-						dynamicMatrix: config.dynamicMatrix ?? false
-					}, config.timeoutMs);
+						dynamicMatrix: config.dynamicMatrix ?? false,
+						hasFilter: config.hasFilter ?? false
+					}, config.timeoutMs, filterInput);
 				});
 				logger$2.info("Init job completed successfully", {
 					jobId,
 					hasContext: initResult.contextNames !== void 0,
 					hasEnv: initResult.env !== void 0,
-					hasConcurrencyGroup: initResult.concurrencyGroup !== void 0
+					hasConcurrencyGroup: initResult.concurrencyGroup !== void 0,
+					filterPassed: initResult.filterPassed
 				});
+				if (initResult.filterPassed === false) initLog(`Workflow filter returned false — '${config.workflowName}' does not apply to this event, so no job is dispatched`);
 				initLog("Init completed successfully");
-				await initStreamer.flush();
-				initStreamer.destroy();
+				await closeStreamer();
 				this.sendStepStatus(dispatch, 0, "init", ExecutionStepStatus.enum.success, void 0, initStreamer.getTotalBytes());
 				this.sendJobStatus(dispatch, ExecutionJobStatus.enum.success, {
 					initResult,
@@ -7777,8 +8798,7 @@ var init_job_runner = __esmMin((() => {
 					error: errorMsg
 				});
 				initLog(`Error: ${errorMsg}`);
-				await initStreamer.flush();
-				initStreamer.destroy();
+				await closeStreamer();
 				this.sendStepStatus(dispatch, 0, "init", ExecutionStepStatus.enum.failed, { error: errorMsg }, initStreamer.getTotalBytes());
 				this.sendJobStatus(dispatch, ExecutionJobStatus.enum.failed, {
 					error: errorMsg,
@@ -7822,36 +8842,7 @@ var init_job_runner = __esmMin((() => {
 					this.sendJobStatus(dispatch, ExecutionJobStatus.enum.cancelled);
 					return;
 				}
-				if (dispatch.depsUrl) {
-					evalLog("Restoring dependencies from cache");
-					await restoreDeps(workDir, dispatch.depsUrl, dispatch.depsHash);
-					evalLog("Dependencies restored");
-				}
-				if (dispatch.sourceTarUrl) {
-					evalLog("Restoring workflow source from cached tarball");
-					await restoreSource(workDir, dispatch.sourceTarUrl);
-				} else {
-					evalLog(`Cloning ${dispatch.repoUrl} ref=${dispatch.ref}`);
-					const cloneStart = Date.now();
-					await gitClone({
-						repoUrl: dispatch.repoUrl,
-						ref: dispatch.ref,
-						sha: dispatch.sha,
-						workDir,
-						gitAuth: dispatch.sourceAuth,
-						token: dispatch.sourceAuth ? void 0 : dispatch.token
-					});
-					cloneDurationSeconds.record((Date.now() - cloneStart) / 1e3);
-				}
-				const kiciDir = join(workDir, ".kici");
-				if (!dispatch.depsUrl && await fileExists(join(kiciDir, "package.json"))) {
-					evalLog("Installing dependencies locally");
-					await installDeps(kiciDir, {
-						npmRegistries: dispatch.npmRegistries,
-						installEnvSecrets: dispatch.installEnvSecrets,
-						jobIdShort: dispatch.jobId.slice(0, 8)
-					});
-				}
+				await materializeEvalWorkspace(dispatch, workDir, evalLog);
 				const { $: zx$ } = await import("zx");
 				const scopedDollar = zx$({
 					cwd: workDir,
@@ -7861,6 +8852,7 @@ var init_job_runner = __esmMin((() => {
 					log: makeStreamingZxLog((line, stream) => evalStreamer.addLine(line, stream))
 				});
 				const evalSink = { addLine: (line) => evalStreamer.addLine(line) };
+				const filterInput = config.hasFilter ? await buildInitFilterInput(dispatch, config.event, workDir, (line, stream) => evalStreamer.addLine(line, stream)) : void 0;
 				const dynamicJobLogger = {
 					info: (msg, ..._args) => evalLog(msg),
 					warn: (msg, ..._args) => evalLog(`WARN: ${msg}`),
@@ -7872,20 +8864,25 @@ var init_job_runner = __esmMin((() => {
 					const { module } = await loadWorkflowSource(workDir, config.source.file, config.contentHash, config.resolvedHashFiles);
 					evalLog("Workflow loaded");
 					const { extractDynamicJobFn } = await Promise.resolve().then(() => (init_workflow_loader(), workflow_loader_exports));
-					const dynamicFn = extractDynamicJobFn(extractWorkflow(module, config.workflowName), config.source.index);
+					const workflow = extractWorkflow(module, config.workflowName);
+					if (config.hasFilter) {
+						if (!await evaluateWorkflowFilter(workflow, config.event, filterInput, timeoutMs)) {
+							evalLog(`Workflow filter returned false — '${config.workflowName}' does not apply to this event, so its generator is not run and no jobs are generated`);
+							return [];
+						}
+					}
+					const dynamicFn = extractDynamicJobFn(workflow, config.source.index);
 					evalLog(`Evaluating DynamicJobFn (index ${config.source.index}, timeout ${timeoutMs}ms)`);
 					const needs = buildEvalNeedsContext(config);
-					const context = {
+					const context = buildGeneratorContext({
+						workflowName: config.workflowName,
+						event: config.event,
+						env: process.env,
+						...needs && { needs },
 						$: scopedDollar,
-						ctx: {
-							workflow: { name: config.workflowName },
-							event: config.event,
-							...needs && { needs }
-						},
 						log: dynamicJobLogger,
-						env: process.env,
 						kici
-					};
+					});
 					return serializeJobsToLock(await withTimeout(() => dynamicFn(context), timeoutMs, `DynamicJobFn index ${config.source.index} in workflow '${config.workflowName}'`), {
 						event: config.event,
 						$: scopedDollar,
@@ -8111,14 +9108,14 @@ var init_job_runner = __esmMin((() => {
 */
 init_console_capture();
 init_npm_resolver();
-const AGENT_VERSION = "0.4.0";
-const BUILD_COMMIT = "ffd489464";
-const SDK_VERSION = "0.4.0";
-const SDK_BUNDLE_HASH = "fcd0a836aa1cb92debd93e0254450614d123b3748511aa4148d956fd72a7c29f";
-const SHARED_VERSION = "0.4.0";
-const SHARED_BUNDLE_HASH = "f16fa528a8a9ef1bed8df369f0e88efafca8a9954a749005299fdbcdb93fa188";
-const ENGINE_VERSION = "0.4.0";
-const ENGINE_BUNDLE_HASH = "31e2d5c327284e1cac908d7f85cf6d878bbf87ea0da93ed09c6205ada6935f89";
+const AGENT_VERSION = "0.5.0";
+const BUILD_COMMIT = "cb51c7d1e";
+const SDK_VERSION = "0.5.0";
+const SDK_BUNDLE_HASH = "5b85e7cffa4a08e39329ff80448a2744af8e5b5f9840ec3801fad45ed11a3de9";
+const SHARED_VERSION = "0.5.0";
+const SHARED_BUNDLE_HASH = "b6b6d1818d1fe648150422daf073dafc18b037404cacf82e0ec03b4a2863e4c4";
+const ENGINE_VERSION = "0.5.0";
+const ENGINE_BUNDLE_HASH = "35d174ce6f4748abffcad194b335b508cade5d1c8af16d9cd3bdcb744f38717e";
 initTelemetry({
 	serviceName: "kici-agent",
 	otlpEndpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT