@kici-dev/agent 0.4.0 → 0.5.0

package/dist/workflow-runner.js

@@ -681,7 +681,7 @@ async function excludeScratchFromGit(repoWorkDir) {
 		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$5.warn("Failed to register scratch dir glob in .git/info/exclude", {
+		logger$6.warn("Failed to register scratch dir glob in .git/info/exclude", {
 			excludePath,
 			error: err instanceof Error ? err.message : String(err)
 		});
@@ -742,7 +742,7 @@ async function cleanupScratch(scratchDir) {
 			force: true
 		});
 	} catch (cleanupErr) {
-		logger$5.warn("Scratch dir cleanup failed (orphan left behind)", {
+		logger$6.warn("Scratch dir cleanup failed (orphan left behind)", {
 			scratchDir,
 			error: cleanupErr instanceof Error ? cleanupErr.message : String(cleanupErr)
 		});
@@ -767,7 +767,7 @@ async function cleanupScratch(scratchDir) {
 */
 async function restoreDeps(workDir, depsUrl, depsHash) {
 	depsUrl = resolveOrchestratorUrl(depsUrl);
-	logger$5.info("Downloading dependency tarball", { url: depsUrl });
+	logger$6.info("Downloading dependency tarball", { url: depsUrl });
 	const kiciDir = join(workDir, ".kici");
 	if (depsUrl.startsWith("file://")) {
 		const localPath = fileURLToPath(depsUrl);
@@ -781,7 +781,7 @@ async function restoreDeps(workDir, depsUrl, depsHash) {
 		await moveScratchIntoRepo(scratchDir, workDir);
 		await cleanupScratch(scratchDir);
 		const sizeMB = (data.length / (1024 * 1024)).toFixed(2);
-		logger$5.info("Dependencies restored from cache (file)", {
+		logger$6.info("Dependencies restored from cache (file)", {
 			sizeMB,
 			targetDir: workDir
 		});
@@ -790,7 +790,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$5.warn("Retrying dep tarball download", {
+		if (attempt > 0) logger$6.warn("Retrying dep tarball download", {
 			attempt,
 			url: depsUrl
 		});
@@ -799,11 +799,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$5.info("Dependencies restored from cache (stream)", { targetDir: workDir });
+			logger$6.info("Dependencies restored from cache (stream)", { targetDir: workDir });
 			return;
 		} catch (err) {
 			lastError = err instanceof Error ? err : new Error(String(err));
-			logger$5.warn("Dep tarball download failed", {
+			logger$6.warn("Dep tarball download failed", {
 				attempt,
 				error: lastError.message
 			});
@@ -811,9 +811,9 @@ async function restoreDeps(workDir, depsUrl, depsHash) {
 	}
 	throw new Error(`Dep tarball download failed after 3 attempts: ${lastError?.message}`);
 }
-var logger$5, DOWNLOAD_TIMEOUT_MS$2, SCRATCH_DIR_BASENAME_PREFIX, SCRATCH_DIR_GIT_EXCLUDE_GLOB;
+var logger$6, DOWNLOAD_TIMEOUT_MS$2, SCRATCH_DIR_BASENAME_PREFIX, SCRATCH_DIR_GIT_EXCLUDE_GLOB;
 var init_dep_restore = __esmMin((() => {
-	logger$5 = createLogger({ prefix: "dep-restore" });
+	logger$6 = createLogger({ prefix: "dep-restore" });
 	DOWNLOAD_TIMEOUT_MS$2 = 300 * 1e3;
 	SCRATCH_DIR_BASENAME_PREFIX = ".dep-restore-scratch-";
 	SCRATCH_DIR_GIT_EXCLUDE_GLOB = `.kici/${SCRATCH_DIR_BASENAME_PREFIX}*`;
@@ -827,10 +827,25 @@ var init_dep_restore = __esmMin((() => {
 * dep-restore.ts and workflow-loader.ts.
 */
 var download_exports = /* @__PURE__ */ __exportAll({
+	UPLOAD_MAX_RETRIES: () => 2,
 	downloadUrl: () => downloadUrl,
 	uploadToPresignedUrl: () => uploadToPresignedUrl
 });
 /**
+* 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
@@ -854,21 +869,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,
@@ -877,7 +881,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;
 			}
@@ -885,14 +889,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$1;
+/**
+* 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$5.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$5, DOWNLOAD_TIMEOUT_MS$1, UPLOAD_TIMEOUT_MS, UPLOAD_RETRY_BASE_DELAY_MS, PresignedUploadHttpError;
 var init_download = __esmMin((() => {
 	init_dep_restore();
+	logger$5 = createLogger({ prefix: "agent:download" });
 	DOWNLOAD_TIMEOUT_MS$1 = 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/cache/cache-engine.ts
@@ -2011,7 +2081,9 @@ async function evaluateStepRulesAndMaybeSkip(step, stepIndex, opts) {
 		changedFilesStatus: ev.changedFilesStatus,
 		env: opts.env,
 		dispatchInputs: opts.dispatchInputs ?? {},
-		fanout: opts.fanout
+		fanout: opts.fanout,
+		...opts.sourceRepo && { sourceRepo: opts.sourceRepo },
+		...opts.workflowRepo && { workflowRepo: opts.workflowRepo }
 	});
 	const ruleResult = await evaluateRules(step.rules, ruleCtx, step.name);
 	if (ruleResult.allPassed) return null;
@@ -3874,6 +3946,34 @@ function logSubprocessStreams(e, tokens) {
 	if (e && typeof e === "object" && "stderr" in e) process.stderr.write(`[dep-installer:trace] stderr: ${redactNpmOutput(String(e.stderr), tokens).slice(0, 500)}\n`);
 }
 //#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
+		}
+	};
+}
+//#endregion
 //#region src/execution/workflow-loader.ts
 /**
 * Workflow module loading: transforms `.ts` workflow files on import via the
@@ -3915,8 +4015,8 @@ async function resolveWorkflowSdkSetters(workflowFilePath) {
 		setJobOutputsMap
 	};
 }
-const AGENT_SDK_VERSION = "0.4.0";
-const AGENT_SDK_BUNDLE_HASH = "fcd0a836aa1cb92debd93e0254450614d123b3748511aa4148d956fd72a7c29f";
+const AGENT_SDK_VERSION = "0.5.0";
+const AGENT_SDK_BUNDLE_HASH = "5b85e7cffa4a08e39329ff80448a2744af8e5b5f9840ec3801fad45ed11a3de9";
 /**
 * Register the ESM loader hook that transforms `.ts` / `.tsx` files on the fly
 * for subsequent dynamic `import()` calls. Idempotent at our level via the
@@ -4056,7 +4156,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");
@@ -4064,17 +4164,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) {
@@ -4096,6 +4195,63 @@ async function extractStepsFromDynamicJob(workflow, dynamicIndex, jobName, event
 	throw new Error(`Generated job '${jobName}' not found in DynamicJobFn output (workflow '${workflow.name}', index ${dynamicIndex}). Available: ${actualNames.join(", ")}`);
 }
 //#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/source-restore.ts
 /**
 * `.kici/` source tarball restoration for execution agents.
@@ -4292,7 +4448,7 @@ async function applyOverlay(config) {
 */
 init_download();
 init_dep_restore();
-const AGENT_VERSION = "0.4.0";
+const AGENT_VERSION = "0.5.0";
 process.on("uncaughtException", (err) => {
 	process.stderr.write(`[workflow-runner] UNCAUGHT EXCEPTION: ${err.message}\n`);
 	if (err.stack) process.stderr.write(`[workflow-runner] Stack: ${err.stack}\n`);
@@ -5740,6 +5896,27 @@ async function loadWorkflowModuleWithCapture(workflowRoot, request, isGlobal, ma
 	}
 }
 /**
+* Build the argument the user's `concurrency.group(...)` function receives.
+*
+* The only inputs an author can scope a group by. `branch` alone does not
+* separate one repository from another — an organization-wide workflow runs on
+* events from many repositories, and their default branches share a name — so
+* `event.sourceRepo` is what makes a per-source-repository group expressible.
+* That is why the orchestrator writes the whole normalized envelope into every
+* global job config: an empty `event` here silently collapses every repository
+* into one group, and with `cancelInProgress` (the default) one repository's
+* push then cancels another's in-flight run.
+*
+* Boundary cast: the wire `request.event` is untyped JSON that, per the unified
+* event protocol, always carries the normalized event envelope.
+*/
+function buildConcurrencyGroupContext(request) {
+	return {
+		branch: request.branch ?? request.ref,
+		event: request.event ?? {}
+	};
+}
+/**
 * Phase 4b — Evaluate the user-defined `concurrency.group(...)` function with
 * a timeout, report the resulting key to the orchestrator, and act on the
 * returned ack. `wait` and `cancel` paths exit the process directly (the run
@@ -5753,10 +5930,7 @@ async function evaluateConcurrencyGroupIfPresent(workflow, request) {
 	if (!workflow.concurrency?.group) return "proceed";
 	trace("evaluating concurrency group function");
 	const concurrencyTimeoutMs = request.concurrencyEvaluationTimeoutMs ?? 3e4;
-	const groupCtx = {
-		branch: request.branch ?? request.ref,
-		event: request.event ?? {}
-	};
+	const groupCtx = buildConcurrencyGroupContext(request);
 	try {
 		const ac = new AbortController();
 		const concurrencyTimer = setTimeout(() => ac.abort(), concurrencyTimeoutMs);
@@ -5867,21 +6041,21 @@ async function evaluateConcurrencyGroupIfPresent(workflow, request) {
 	}
 }
 /**
-* Phase 5 — Inject env vars and build the `RepoInfo` pair that step contexts
-* receive when the job is a global workflow. No-op for normal jobs.
+* Phase 5 — Inject env vars and build the `RepoInfo` pair that the generator,
+* the job rules, and step contexts receive when the job is a global workflow.
+* No-op for normal jobs.
+*
+* Runs at the head of phase 5, before anything that may read the source tree:
+* the generator's re-evaluation (phase 5) and the job rules (phase 7) both take
+* the returned pair, and both must see what the pre-dispatch evaluation saw.
+*
+* `sourceRepo.path` is this sandbox's own absolute path — the same repo lives at
+* a different path in the evaluation that produced the job list. Read through
+* it; never compare it or embed it in a job name.
 */
 function setupGlobalWorkflowEnv(request, isGlobal, workflowDir, sourceDir) {
 	if (!isGlobal) return void 0;
-	process.env.KICI_IS_GLOBAL_WORKFLOW = "true";
-	process.env.KICI_WORKFLOW_REPO_PATH = workflowDir;
-	process.env.KICI_SOURCE_REPO_PATH = sourceDir;
-	const sourceRepoIdentifier = request.repoUrl.replace(/\.git$/, "").replace(/^https?:\/\/[^/]+\//, "");
-	process.env.KICI_SOURCE_REPO = sourceRepoIdentifier;
-	process.env.KICI_SOURCE_BRANCH = request.ref;
-	process.env.KICI_SOURCE_SHA = request.sha;
-	process.env.KICI_WORKFLOW_REPO = request.workflowRepoIdentifier ?? "";
-	trace(`global workflow env vars injected: KICI_WORKFLOW_REPO_PATH=${workflowDir}, KICI_SOURCE_REPO_PATH=${sourceDir}`);
-	return {
+	const repos = {
 		workflowRepo: {
 			identifier: request.workflowRepoIdentifier ?? "",
 			path: workflowDir,
@@ -5889,12 +6063,15 @@ function setupGlobalWorkflowEnv(request, isGlobal, workflowDir, sourceDir) {
 			sha: request.workflowSha
 		},
 		sourceRepo: {
-			identifier: sourceRepoIdentifier,
+			identifier: repoIdentifierFromUrl(request.repoUrl),
 			path: sourceDir,
 			ref: request.ref,
 			sha: request.sha
 		}
 	};
+	applyGlobalWorkflowEnv(repos);
+	trace(`global workflow env vars injected: KICI_WORKFLOW_REPO_PATH=${workflowDir}, KICI_SOURCE_REPO_PATH=${sourceDir}`);
+	return repos;
 }
 /**
 * Phase 8 — Cancel-path hook execution. Runs the four cancel hooks
@@ -6030,11 +6207,11 @@ function coerceStep(stepOrFn, state) {
 * Bare-function steps get auto-generated `step-N` names so the IPC reporting
 * and the StepRefMap (used by `.result` proxies) line up.
 */
-async function extractAndNormalizeSteps(workflow, request, apiTransport) {
+async function extractAndNormalizeSteps(workflow, request, apiTransport, repos) {
 	let rawSteps;
 	let driftDroppedJobs = [];
 	if (request.dynamicSource) {
-		const dynamicResult = await extractStepsFromDynamicJob(workflow, request.dynamicSource.index, request.jobName, request.dynamicSource.event, process.env, apiTransport, request.dynamicSource.expectedJobNames, request.dynamicSource.upstreamSnapshot, request.dynamicSource.declaredNeeds);
+		const dynamicResult = await extractStepsFromDynamicJob(workflow, request.dynamicSource.index, request.jobName, request.dynamicSource.event, process.env, apiTransport, request.dynamicSource.expectedJobNames, request.dynamicSource.upstreamSnapshot, request.dynamicSource.declaredNeeds, repos);
 		rawSteps = dynamicResult.steps;
 		driftDroppedJobs = dynamicResult.droppedJobs;
 		if (driftDroppedJobs.length > 0) trace(`Determinism drift: ${driftDroppedJobs.length} job(s) dropped: ${driftDroppedJobs.join(", ")}`);
@@ -6180,7 +6357,7 @@ function buildJobRuleCompletion(ruleResult, normalizedSteps) {
 * success-skip). Returns false when the caller should continue to step
 * execution.
 */
-async function maybeSkipJobOnRules(job, request, normalizedSteps) {
+async function maybeSkipJobOnRules(job, request, normalizedSteps, repos) {
 	if (!job?.rules || job.rules.length === 0) return false;
 	const ev = request.event ?? {};
 	const ruleCtx = createRuleContext({
@@ -6189,7 +6366,11 @@ async function maybeSkipJobOnRules(job, request, normalizedSteps) {
 		changedFilesStatus: ev.changedFilesStatus,
 		env: process.env,
 		dispatchInputs: request.dispatchInputs ?? {},
-		fanout: deriveFanout(request)
+		fanout: deriveFanout(request),
+		...repos && {
+			sourceRepo: repos.sourceRepo,
+			workflowRepo: repos.workflowRepo
+		}
 	});
 	const completion = buildJobRuleCompletion(await evaluateRules(job.rules, ruleCtx, request.jobName), normalizedSteps);
 	if (!completion) return false;
@@ -6199,6 +6380,30 @@ async function maybeSkipJobOnRules(job, request, normalizedSteps) {
 	process.exit(0);
 }
 /**
+* Build the inputs the step loop turns into every step rule's `RuleContext`.
+*
+* Shares its source with `maybeSkipJobOnRules` so a step rule and a job rule
+* see the same world: the same event, env, dispatch inputs, fan-out position,
+* and — for a global workflow — the same source / workflow repo pair. A step
+* rule that received the pair as `undefined` while the job rule beside it
+* received the real thing would read the same `RuleContext` type two ways.
+*
+* The pair is spread conditionally: a present-but-undefined `sourceRepo` reads
+* as "declared" to a rule that guards on the key rather than the value.
+*/
+function buildStepLoopRuleInputs(request, repos) {
+	return {
+		event: request.event ?? {},
+		env: process.env,
+		dispatchInputs: request.dispatchInputs ?? {},
+		fanout: deriveFanout(request),
+		...repos && {
+			sourceRepo: repos.sourceRepo,
+			workflowRepo: repos.workflowRepo
+		}
+	};
+}
+/**
 * Collect the six job-level hooks (beforeStep / afterStep / onSuccess /
 * onFailure / onCancel / cleanup) into a single typed object the step loop
 * and cancel-path consume.
@@ -6402,6 +6607,7 @@ async function main() {
 	const module = loaded.module;
 	const workflow = extractWorkflow(module, request.workflowName);
 	await evaluateConcurrencyGroupIfPresent(workflow, request);
+	const globalRepoInfo = setupGlobalWorkflowEnv(request, isGlobal, workflowDir, sourceDir);
 	const apiTransport = async (method, params) => {
 		const reqId = randomUUID();
 		sendMessage({
@@ -6412,16 +6618,15 @@ async function main() {
 		});
 		return waitForApiResponse(reqId);
 	};
-	const { normalizedSteps, nodes, refMap, driftDroppedJobs } = await extractAndNormalizeSteps(workflow, request, apiTransport);
+	const { normalizedSteps, nodes, refMap, driftDroppedJobs } = await extractAndNormalizeSteps(workflow, request, apiTransport, globalRepoInfo);
 	const { operatorSecretKeys, outputsMap, secretOutputs, jobOutputsMap } = buildOutputInfrastructure(request, refMap, loaded.sdkSetters);
 	const job = findJob(workflow, request.jobName);
 	const jobHasRules = (job?.rules?.length ?? 0) > 0;
 	const anyStepHasRules = normalizedSteps.some((s) => (s.rules?.length ?? 0) > 0);
 	await resolveChangedFilesForRules(request, sourceDir, jobHasRules || anyStepHasRules);
-	await maybeSkipJobOnRules(job, request, normalizedSteps);
+	await maybeSkipJobOnRules(job, request, normalizedSteps, globalRepoInfo);
 	if (aborted) abortAndExit("aborted after rules");
 	const jobHooks = collectJobHooks(job);
-	const globalRepoInfo = setupGlobalWorkflowEnv(request, isGlobal, workflowDir, sourceDir);
 	flushOutputCapture();
 	capturePrepareActive = false;
 	const stepCwd = sourceDir;
@@ -6468,10 +6673,7 @@ async function main() {
 		sendIpc: maskedSend,
 		defaultTimeoutMs,
 		outputsMap,
-		event: request.event ?? {},
-		env: process.env,
-		dispatchInputs: request.dispatchInputs ?? {},
-		fanout: deriveFanout(request),
+		...buildStepLoopRuleInputs(request, globalRepoInfo),
 		jobHooks,
 		cachePhaseDeps,
 		isAborted: () => aborted,
@@ -6575,6 +6777,6 @@ main().catch((error) => {
 	setTimeout(() => process.exit(1), 100);
 });
 //#endregion
-export { buildJobRuleCompletion, buildSandboxShell, buildStepEnvFileHooks, buildStepNeedsContext, coerceStep, createSandboxStepContext, deriveFanout, drainJobTempScope, rawPayloadFromEvent, resolveChangedFilesForRules, resolveEmitEventName, sanitizeTempLabel };
+export { buildConcurrencyGroupContext, buildJobRuleCompletion, buildSandboxShell, buildStepEnvFileHooks, buildStepLoopRuleInputs, buildStepNeedsContext, coerceStep, createSandboxStepContext, deriveFanout, drainJobTempScope, rawPayloadFromEvent, resolveChangedFilesForRules, resolveEmitEventName, sanitizeTempLabel, setupGlobalWorkflowEnv };
 
 //# sourceMappingURL=workflow-runner.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kici-dev/agent",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Customer-deployable agent for the KiCI CI/CD stack. Connects to an orchestrator, clones the workflow repo, executes steps, and streams logs back.",
   "keywords": [
     "ci",
@@ -66,10 +66,10 @@
     "yaml": "^2.9.0",
     "zod": "^4.4.3",
     "zx": "^8.8.5",
-    "@kici-dev/core": "0.4.0",
-    "@kici-dev/engine": "0.4.0",
-    "@kici-dev/sdk": "0.4.0",
-    "@kici-dev/shared": "0.4.0"
+    "@kici-dev/core": "0.5.0",
+    "@kici-dev/engine": "0.5.0",
+    "@kici-dev/sdk": "0.5.0",
+    "@kici-dev/shared": "0.5.0"
   },
   "kici": {
     "metrics": {