@kici-dev/agent 0.4.0 → 0.6.0

package/dist/workflow-runner.js

@@ -8,7 +8,7 @@ import path, { dirname, isAbsolute, join, relative, resolve, sep } from "node:pa
 import { $ } from "zx";
 import { createLogger, deriveSharedSecret, initZx, normalizeLineEndings, sha256, sha256File, toErrorMessage } from "@kici-dev/shared";
 import { createTempScope, makeTempDir } from "@kici-dev/core/tmp";
-import { CacheOutcome, CacheStepType, CheckMode, CheckStepOutcome, ExecutionJobStatus, ExecutionStepStatus, LogStream, StepConcurrencyKind, TimeoutReason, artifactInvalidNameError, checkArtifactName } from "@kici-dev/engine";
+import { CacheOutcome, CacheStepType, CheckMode, CheckStepOutcome, ExecutionJobStatus, ExecutionStepStatus, LogStream, StepConcurrencyKind, TimeoutReason, artifactInvalidNameError, checkArtifactName, reservedEventNamePrefix } from "@kici-dev/engine";
 import { execFile, execFileSync } from "node:child_process";
 import { buildKiciApi, buildNeedsContext, createRuleContext, createStepSecrets, evaluateRules, isDynamicJobFn, isEventDefinition, isParallelGroup, normalizeApproval, normalizeCacheSpecs, provenanceSubjectIsPath, resolveJobOutputs, resolveStepOutputs, setJobOutputsMap, setStepOutputsMap, setStepRefMap } from "@kici-dev/sdk";
 import { OIDC_TOKEN_REQUEST_METHOD } from "@kici-dev/engine/protocol/messages/oidc-token-relay";
@@ -123,9 +123,11 @@ 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");
-	await writeFile(keyPath, opts.privateKey.endsWith("\n") ? opts.privateKey : `${opts.privateKey}\n`, { mode: 384 });
+	const pem = opts.privateKey.endsWith("\n") ? opts.privateKey : `${opts.privateKey}\n`;
+	await writeFile(keyPath, pem, { mode: 384 });
 	const knownHostsPath = join(tempDir, "known_hosts");
-	await writeFile(knownHostsPath, opts.hostKeyPolicy === "pinned" ? opts.knownHosts : "", { mode: 384 });
+	const knownHostsBody = opts.hostKeyPolicy === "pinned" ? opts.knownHosts : "";
+	await writeFile(knownHostsPath, knownHostsBody, { mode: 384 });
 	const parts = [
 		"ssh",
 		"-i",
@@ -462,13 +464,14 @@ async function signStatementDsse(payloadType, statementBytes) {
 	const kid = await calculateJwkThumbprint(publicJwk, "sha256");
 	publicJwk.kid = kid;
 	const pae = dssePae(payloadType, statementBytes);
+	const sig = new Uint8Array(await crypto.subtle.sign({
+		name: "ECDSA",
+		hash: "SHA-256"
+	}, privateKey, pae));
 	return {
 		envelope: buildDsseEnvelope(payloadType, statementBytes, [{
 			keyid: kid,
-			sig: new Uint8Array(await crypto.subtle.sign({
-				name: "ECDSA",
-				hash: "SHA-256"
-			}, privateKey, pae))
+			sig
 		}]),
 		publicJwk
 	};
@@ -495,7 +498,8 @@ async function attestProvenance(deps, input) {
 		startedOn: now,
 		finishedOn: now
 	});
-	const { envelope, publicJwk } = await signStatementDsse(IN_TOTO_PAYLOAD_TYPE, new TextEncoder().encode(JSON.stringify(statement)));
+	const statementBytes = new TextEncoder().encode(JSON.stringify(statement));
+	const { envelope, publicJwk } = await signStatementDsse(IN_TOTO_PAYLOAD_TYPE, statementBytes);
 	const bundle = {
 		mediaType: KICI_PROVENANCE_BUNDLE_MEDIA_TYPE,
 		dsseEnvelope: envelope,
@@ -681,7 +685,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 +746,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 +771,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);
@@ -780,8 +784,8 @@ async function restoreDeps(workDir, depsUrl, depsHash) {
 		await extractTarball(data, scratchDir);
 		await moveScratchIntoRepo(scratchDir, workDir);
 		await cleanupScratch(scratchDir);
-		const sizeMB = (data.length / (1024 * 1024)).toFixed(2);
-		logger$5.info("Dependencies restored from cache (file)", {
+		const sizeMB = (data.length / 1048576).toFixed(2);
+		logger$6.info("Dependencies restored from cache (file)", {
 			sizeMB,
 			targetDir: workDir
 		});
@@ -790,7 +794,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 +803,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,10 +815,10 @@ 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" });
-	DOWNLOAD_TIMEOUT_MS$2 = 300 * 1e3;
+	logger$6 = createLogger({ prefix: "dep-restore" });
+	DOWNLOAD_TIMEOUT_MS$2 = 3e5;
 	SCRATCH_DIR_BASENAME_PREFIX = ".dep-restore-scratch-";
 	SCRATCH_DIR_GIT_EXCLUDE_GLOB = `.kici/${SCRATCH_DIR_BASENAME_PREFIX}*`;
 }));
@@ -827,10 +831,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 +873,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 +885,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 +893,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();
-	DOWNLOAD_TIMEOUT_MS$1 = 300 * 1e3;
+	logger$5 = createLogger({ prefix: "agent:download" });
+	DOWNLOAD_TIMEOUT_MS$1 = 3e5;
+	UPLOAD_TIMEOUT_MS = 3e5;
+	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
@@ -916,11 +990,13 @@ init_download();
 * right destination (repo entries under `workDir`, home entries under the
 * homedir). Extraction lands in a scratch dir first, then moves each group
 * into place so a partial restore never leaves half-written paths in the live
-* tree (mirrors dep-restore).
+* tree (mirrors dep-restore). The scratch dir honors `KICI_TMPDIR`, which may
+* sit on a different filesystem from the workspace, so the move falls back to
+* copy-then-remove on `EXDEV` rather than assuming a same-filesystem rename.
 */
 const logger$4 = createLogger({ prefix: "cache-engine" });
 /** Download timeout for a presigned cache GET: 5 minutes. */
-const DOWNLOAD_TIMEOUT_MS = 300 * 1e3;
+const DOWNLOAD_TIMEOUT_MS = 3e5;
 /**
 * Resolve a cache path. `~`-prefixed -> home root; otherwise repo-root-relative.
 * Rejects absolute paths and `..` escapes so a workflow cannot read or clobber
@@ -995,6 +1071,32 @@ async function packCachePaths(workDir, paths, roots) {
 		await cleanup();
 	}
 }
+/**
+* Move a tree from `src` to `dest`. Attempts a rename (same-filesystem, cheap)
+* and falls back to copy-then-remove only on `EXDEV` — the errno `rename(2)`
+* reports when the scratch dir (which honors `KICI_TMPDIR`) is on a different
+* filesystem from the destination workspace. `verbatimSymlinks` keeps a cached
+* symlink graph intact (mirroring packCachePaths), and `preserveTimestamps`
+* keeps mtimes stable so the fallback is byte-for-byte equivalent to the
+* rename. Any non-`EXDEV` error propagates so a real permission or corruption
+* failure is never silently turned into a copy.
+*/
+async function moveOrCopy(src, dest) {
+	try {
+		await rename(src, dest);
+	} catch (err) {
+		if (err.code !== "EXDEV") throw err;
+		await cp(src, dest, {
+			recursive: true,
+			verbatimSymlinks: true,
+			preserveTimestamps: true
+		});
+		await rm(src, {
+			recursive: true,
+			force: true
+		});
+	}
+}
 /** Move the extracted `__repo__` / `__home__` groups from a scratch dir into place. */
 async function moveAnchoredGroups(scratchDir, workDir, home) {
 	for (const anchor of await readdir(scratchDir)) {
@@ -1008,7 +1110,7 @@ async function moveAnchoredGroups(scratchDir, workDir, home) {
 				recursive: true,
 				force: true
 			});
-			await rename(join(anchorDir, child), dest);
+			await moveOrCopy(join(anchorDir, child), dest);
 		}
 	}
 }
@@ -1487,7 +1589,7 @@ function buildMergedFlatSecrets(orchestratorSecrets, namespacedSecrets) {
 //#endregion
 //#region src/execution/hook-executor.ts
 /** Default hook timeout: 5 minutes */
-const DEFAULT_HOOK_TIMEOUT_MS = 300 * 1e3;
+const DEFAULT_HOOK_TIMEOUT_MS = 3e5;
 /**
 * Build outcome metadata from execution state.
 *
@@ -2011,7 +2113,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;
@@ -2363,6 +2467,7 @@ async function runJobCompletionHooks(opts, initial, outputsMap, startTime) {
 			opts
 		});
 	}
+	opts.sendIpc({ type: "completion-hooks-done" });
 	return state;
 }
 /**
@@ -2379,7 +2484,7 @@ async function runJobCompletionHooks(opts, initial, outputsMap, startTime) {
 async function executeStepLoop(opts) {
 	const startTime = opts.startTime ?? Date.now();
 	const stepResults = [];
-	const state = { failed: false };
+	const state = { failed: opts.forceInitialFailure === true };
 	const nodes = opts.stepNodes ?? opts.steps.map((step, i) => ({
 		kind: "sequential",
 		step,
@@ -2483,7 +2588,7 @@ var StepTaskRegistry = class {
 //#endregion
 //#region src/execution/env-init/init-phase.ts
 /** Default init timeout when a spec sets none: 10 minutes. */
-const DEFAULT_INIT_TIMEOUT_MS = 600 * 1e3;
+const DEFAULT_INIT_TIMEOUT_MS = 6e5;
 /**
 * Marker thrown when an init command exceeds its wall-clock budget. Carries the
 * distinct P3 timeout reason so the phase result + job.complete report a timeout
@@ -2849,6 +2954,37 @@ function armJobDeadline(timeoutMs, onTimeout) {
 //#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
@@ -2875,7 +3011,7 @@ function redactSensitive(input) {
 * @throws Error if clone fails or SHA does not match
 */
 async function gitClone(options) {
-	const { repoUrl, ref, sha, workDir, token, gitAuth, depth = 1 } = options;
+	const { repoUrl, ref, sha, workDir, token, gitAuth, depth = 1, credentialHelperPath, sshCleanupRegistry } = options;
 	const auth = gitAuth ? gitAuth : token ? {
 		kind: "basic",
 		user: "x-access-token",
@@ -2929,6 +3065,7 @@ async function gitClone(options) {
 		} catch (err) {
 			throw sanitizeGitError(err);
 		}
+		if (credentialHelperPath) configureCredentialHelper(workDir, credentialHelperPath);
 		if (!sha || sha === "HEAD") return;
 		const envOpts = env ? { env } : {};
 		if (!execFileSync("git", [
@@ -2984,11 +3121,90 @@ async function gitClone(options) {
 			if (!recheckedSha.startsWith(sha)) throw new Error(`SHA mismatch: expected ${sha}, got ${recheckedSha}`);
 		}
 	} finally {
-		if (sshSetup) await sshSetup.cleanup().catch(() => {});
+		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/clone-job-repos.ts
+/**
+* Clone a job's repositories — from the host or from inside the sandbox.
+*
+* This used to live only inside the workflow runner, which meant the clone
+* always happened wherever the runner ran: for a container job, inside the
+* customer's image, which therefore had to ship git. Extracting it lets the
+* AGENT clone on the host and copy the tree in, so the image needs no git —
+* and it puts clone-time credentials on the host, where the credential helper
+* already works, rather than needing a route into a container hardened with
+* `CapDrop: ALL`.
+*
+* Both callers run the SAME code: the runner keeps calling it for bare-metal
+* and for the legacy container path, and the agent calls it for a host-side
+* checkout. A second implementation would be two subtly different clones.
+*/
+/**
+* Clone whatever this job needs, or nothing.
+*
+* Three modes, unchanged from where this logic used to live: full-repo overlay
+* (no clone), global dual-clone (workflow repo + source repo), and the ordinary
+* single-repo clone.
+*/
+async function cloneJobRepos(request, dirs, deps) {
+	if (request.checkout === false) return;
+	const helper = request.credentialHelperPath ? { credentialHelperPath: request.credentialHelperPath } : {};
+	if (request.fullRepo) {
+		await mkdir(dirs.workDir, { recursive: true });
+		deps.log("Full-repo mode: skipping git clone (workspace from overlay tarball)");
+		return;
+	}
+	if (deps.isGlobal) {
+		await mkdir(dirs.workflowDir, { recursive: true });
+		await mkdir(dirs.sourceDir, { recursive: true });
+		const workflowAuth = request.workflowAuth ?? request.sourceAuth;
+		const sourceAuth = request.sourceAuth ?? request.workflowAuth;
+		deps.log(`Global workflow: cloning workflow repo ${request.workflowRepoUrl} ref=${request.workflowRef} into ${dirs.workflowDir}`);
+		await gitClone({
+			repoUrl: request.workflowRepoUrl,
+			ref: request.workflowRef ?? "",
+			sha: request.workflowSha ?? "",
+			workDir: dirs.workflowDir,
+			gitAuth: workflowAuth,
+			token: workflowAuth ? void 0 : request.token,
+			...helper
+		});
+		await deps.excludeScratchFromGit(dirs.workflowDir);
+		deps.log(`Global workflow: cloning source repo ${request.repoUrl} ref=${request.ref} into ${dirs.sourceDir}`);
+		await gitClone({
+			repoUrl: request.repoUrl,
+			ref: request.ref,
+			sha: request.sha,
+			workDir: dirs.sourceDir,
+			gitAuth: sourceAuth,
+			token: sourceAuth ? void 0 : request.token,
+			...helper
+		});
+		deps.log("Dual-clone complete");
+		return;
+	}
+	deps.log(`Cloning ${request.repoUrl} ref=${request.ref} into ${dirs.workDir}`);
+	await gitClone({
+		repoUrl: request.repoUrl,
+		ref: request.ref,
+		sha: request.sha,
+		workDir: dirs.workDir,
+		gitAuth: request.sourceAuth,
+		token: request.sourceAuth ? void 0 : request.token,
+		...helper
+	});
+	await deps.excludeScratchFromGit(dirs.workDir);
+	deps.log("Clone complete");
+}
+//#endregion
 //#region src/execution/npm-resolver.ts
 /**
 * Resolve the npm CLI path relative to the running Node.js binary.
@@ -3517,7 +3733,7 @@ const logger$2 = createLogger({ prefix: "dep-installer" });
 const execFileAsync = promisify(execFile);
 /** Install subprocess timeout (10 min) and stdout/stderr buffer (128 MiB). */
 const INSTALL_TIMEOUT_MS = 6e5;
-const INSTALL_MAX_BUFFER = 128 * 1024 * 1024;
+const INSTALL_MAX_BUFFER = 134217728;
 /**
 * Detect the package manager for the cloned repo from its committed manifests.
 * A pnpm workspace's `packageManager` field + `pnpm-lock.yaml` live at the repo
@@ -3874,6 +4090,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
@@ -3902,7 +4146,8 @@ function logSubprocessStreams(e, tokens) {
 */
 async function resolveWorkflowSdkSetters(workflowFilePath) {
 	try {
-		const sdk = await import(pathToFileURL(createRequire(workflowFilePath).resolve("@kici-dev/sdk")).href);
+		const sdkEntry = createRequire(workflowFilePath).resolve("@kici-dev/sdk");
+		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,
@@ -3915,8 +4160,8 @@ async function resolveWorkflowSdkSetters(workflowFilePath) {
 		setJobOutputsMap
 	};
 }
-const AGENT_SDK_VERSION = "0.4.0";
-const AGENT_SDK_BUNDLE_HASH = "fcd0a836aa1cb92debd93e0254450614d123b3748511aa4148d956fd72a7c29f";
+const AGENT_SDK_VERSION = "0.6.0";
+const AGENT_SDK_BUNDLE_HASH = "22faf0da45de7c243ce87f80fd33ee51b1df52809fde457b16bb821678f65eb3";
 /**
 * 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 +4301,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 +4309,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 +4340,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.
@@ -4206,7 +4507,8 @@ async function applyOverlay(config) {
 			throw new Error(`Overlay download failed from ${tarballUrl.replace(/\?.*$/, "?[redacted]")}: ${toErrorMessage(err)}`);
 		}
 		const cliPubKeyBuf = Buffer.from(cliPublicKey, "base64");
-		const aesKey = deriveSharedSecret(Buffer.from(orchestratorPrivateKey, "base64"), cliPubKeyBuf);
+		const orchPrivKeyBuf = Buffer.from(orchestratorPrivateKey, "base64");
+		const aesKey = deriveSharedSecret(orchPrivKeyBuf, cliPubKeyBuf);
 		const decryptedData = decryptBuffer(encryptedData, aesKey);
 		logger.info("Extracting overlay tarball", { size: decryptedData.length });
 		const extractDir = path.join(tmpDir, "extracted");
@@ -4292,7 +4594,7 @@ async function applyOverlay(config) {
 */
 init_download();
 init_dep_restore();
-const AGENT_VERSION = "0.4.0";
+const AGENT_VERSION = "0.6.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`);
@@ -4509,6 +4811,56 @@ const EMIT_RESPONSE_TIMEOUT_MS = 5e3;
 * (per research doc pitfall 5: event was already persisted by orchestrator,
 * so it will still be routed even if the ack is lost).
 */
+/** In-flight git write-grant requests, keyed by requestId. */
+const pendingGitGrants = /* @__PURE__ */ new Map();
+/** How long to wait for the agent to answer a grant request. */
+const GIT_GRANT_TIMEOUT_MS = 6e4;
+function waitForGitGrant(requestId) {
+	return new Promise((resolve) => {
+		const timer = setTimeout(() => {
+			pendingGitGrants.delete(requestId);
+			resolve({
+				type: "git.grant.response",
+				requestId,
+				error: "timed out waiting for the agent to answer a git write-grant request"
+			});
+		}, GIT_GRANT_TIMEOUT_MS);
+		pendingGitGrants.set(requestId, (r) => {
+			clearTimeout(timer);
+			pendingGitGrants.delete(requestId);
+			resolve(r);
+		});
+	});
+}
+/**
+* Open a write window for one repository, run `fn`, and close it.
+*
+* The revoke rides a `finally`, so a throwing callback still closes the
+* window — and the agent's TTL is the backstop if this process dies outright.
+*/
+async function withRepoWrite(repository, opts, fn, send, wait) {
+	const requestId = randomUUID();
+	send({
+		type: "git.grant.request",
+		requestId,
+		op: "elevate",
+		repository,
+		permissions: opts.permissions ?? { contents: "write" },
+		...opts.credential ? { credentialName: opts.credential } : {}
+	});
+	const granted = await wait(requestId);
+	if (granted.error) throw new Error(`Cannot open a git write window for '${repository}': ${granted.error}`);
+	try {
+		await fn();
+	} finally {
+		send({
+			type: "git.grant.request",
+			requestId: randomUUID(),
+			op: "revoke",
+			grantId: granted.grantId
+		});
+	}
+}
 function waitForEmitResponse(requestId) {
 	return new Promise((resolve) => {
 		const timer = setTimeout(() => {
@@ -4693,7 +5045,7 @@ const pendingApprovalResolutions = /* @__PURE__ */ new Map();
 * and sends `expired` when it lapses; this is a safety net well above any sane
 * approval window so the runner cannot hang forever if the resolution is lost.
 */
-const APPROVAL_RESOLUTION_TIMEOUT_MS = 10080 * 60 * 1e3;
+const APPROVAL_RESOLUTION_TIMEOUT_MS = 6048e5;
 /** Wait for an approval.resolved from the agent with the given requestId. */
 function waitForApprovalResolution(requestId) {
 	return new Promise((resolve) => {
@@ -5019,12 +5371,15 @@ function dispatchAgentMessage(msg) {
 	} else if (msg.type === "event.emit.response") {
 		const pending = pendingEmitResponses.get(msg.requestId);
 		if (pending) pending.resolve(msg);
-	} else if (msg.type === "concurrency.ack") {
+	} else if (msg.type === "git.grant.response") pendingGitGrants.get(msg.requestId)?.(msg);
+	else if (msg.type === "concurrency.ack") {
 		if (pendingConcurrencyAck) pendingConcurrencyAck.resolve(msg);
 	} else if (msg.type === "agent.api.response") {
 		const pending = pendingApiResponses.get(msg.requestId);
-		if (pending) if (msg.error) pending.reject(new Error(msg.error));
-		else pending.resolve(msg.result);
+		if (pending) {
+			if (msg.error) pending.reject(new Error(msg.error));
+			else pending.resolve(msg.result);
+		}
 	} else if (msg.type === "cache.response") {
 		const pending = pendingCacheResponses.get(msg.requestId);
 		if (pending) pending.resolve(msg);
@@ -5120,16 +5475,22 @@ function needBaseName(need) {
 * `{ result, status }` / ordered-array shape via the shared SDK builder. Returns
 * undefined when the job declares no needs.
 */
-function buildStepNeedsContext(declaredNeeds, upstreamJobOutputs, upstreamJobStatuses) {
+function buildStepNeedsContext(declaredNeeds, upstreamJobOutputs, upstreamJobStatuses, upstreamInvokeResults) {
 	if (!declaredNeeds || declaredNeeds.length === 0) return void 0;
 	const statuses = upstreamJobStatuses ?? {};
 	const jobs = {};
 	const groups = {};
 	const snapStatuses = {};
+	const invokeResults = {};
 	const resolvedNeeds = [];
 	for (const need of declaredNeeds) {
 		const base = needBaseName(need);
 		if (!base) continue;
+		if (base.kind === "job" && upstreamInvokeResults?.[base.key]) {
+			invokeResults[base.key] = upstreamInvokeResults[base.key];
+			resolvedNeeds.push(base.key);
+			continue;
+		}
 		const childNames = Object.keys(statuses).filter((n) => n.startsWith(`${base.key} (`));
 		if (base.kind === "group" || childNames.length > 0) {
 			groups[base.key] = [...childNames].sort();
@@ -5146,11 +5507,13 @@ function buildStepNeedsContext(declaredNeeds, upstreamJobOutputs, upstreamJobSta
 			resolvedNeeds.push(base.key);
 		}
 	}
-	return buildNeedsContext({
+	const snapshot = {
 		jobs,
 		groups,
 		statuses: snapStatuses
-	}, resolvedNeeds);
+	};
+	if (Object.keys(invokeResults).length > 0) snapshot.invokeResults = invokeResults;
+	return buildNeedsContext(snapshot, resolvedNeeds);
 }
 /**
 * Extract per-child output records from a fan-out outputs envelope, keyed by the
@@ -5191,7 +5554,8 @@ function buildStepSecrets(request, masker, onMaskerSecretsAdded) {
 			async writeMountedFile(args) {
 				const dir = await ensureTmpdir();
 				mountCounter += 1;
-				const filePath = join(dir, args.name ?? `secret-${mountCounter}`);
+				const filename = args.name ?? `secret-${mountCounter}`;
+				const filePath = join(dir, filename);
 				await fsPromises.writeFile(filePath, args.content);
 				await fsPromises.chmod(filePath, args.mode);
 				masker.registerSecrets({ [`__mount_${mountCounter}__`]: args.content });
@@ -5287,6 +5651,19 @@ function resolveEmitEventName(nameOrDefinition) {
 	return isEventDefinition(nameOrDefinition) ? nameOrDefinition.name : nameOrDefinition;
 }
 /**
+* Reject a user `ctx.emit` whose event name uses a reserved prefix: `kici.`
+* (KiCI-internal system events — the event scaler's scale-up / scale-down) or
+* `__` (the events the orchestrator mints for itself). A workflow step must
+* forge neither — a `__` name is dispatched as a TRUSTED ref and skips the
+* event-storm rate limiter, so emitting one would be a privilege escalation,
+* not merely a naming collision. Throws a clear error at the emit call; the
+* orchestrator enforces the same reservation authoritatively.
+*/
+function assertUserEmittableEventName(eventName) {
+	const reservedPrefix = reservedEventNamePrefix(eventName);
+	if (reservedPrefix) throw new Error(`event name prefix "${reservedPrefix}" is reserved for KiCI internal events and cannot be emitted from a workflow step (got "${eventName}")`);
+}
+/**
 * Sanitize a raw identifier into a valid temp label: lowercase, every
 * non-`[a-z0-9-]` char to `-`, falling back to `'step'` when the result is
 * empty. Applied to both the caller-supplied `ctx.mktemp(label)` and the
@@ -5389,6 +5766,7 @@ function createSandboxStepContext(workDir, stepIndex, stepName, request, maskedS
 		artifacts: createArtifactsApi(workDir, buildArtifactTransport()),
 		emit: async (nameOrDefinition, payload, options) => {
 			const eventName = resolveEmitEventName(nameOrDefinition);
+			assertUserEmittableEventName(eventName);
 			const reqId = randomUUID();
 			sendMessage({
 				type: "event.emit",
@@ -5413,6 +5791,13 @@ function createSandboxStepContext(workDir, stepIndex, stepName, request, maskedS
 		mktemp: (label) => jobTempScope.mktemp(sanitizeTempLabel(label ?? stepName)),
 		mktempFile: (label, opts) => jobTempScope.mktempFile(sanitizeTempLabel(label ?? stepName), opts),
 		kici,
+		repo: {
+			identifier: repoIdentifierFromUrl(request.repoUrl),
+			path: workDir,
+			ref: request.ref,
+			sha: request.sha,
+			withWrite: (opts, fn) => withRepoWrite(repoIdentifierFromUrl(request.repoUrl), opts, fn, sendMessage, waitForGitGrant)
+		},
 		attestProvenance: buildAttestProvenanceFn(request, workDir, (o) => kici.oidc.token(o)),
 		...rawPayload && { rawPayload },
 		...request.provider && { provider: request.provider },
@@ -5425,7 +5810,7 @@ function createSandboxStepContext(workDir, stepIndex, stepName, request, maskedS
 		})(),
 		dispatchInputs: request.dispatchInputs ?? {},
 		...(() => {
-			const needs = buildStepNeedsContext(request.jobNeeds, request.upstreamJobOutputs, request.upstreamJobStatuses);
+			const needs = buildStepNeedsContext(request.jobNeeds, request.upstreamJobOutputs, request.upstreamJobStatuses, request.upstreamInvokeResults);
 			return needs ? { needs } : {};
 		})()
 	};
@@ -5483,80 +5868,22 @@ function abortAndExit(reason) {
 * progress IPC log lines as before.
 */
 async function cloneRepoIfRequested(request, workDir, workflowDir, sourceDir, isGlobal) {
-	if (request.checkout === false) return;
-	if (request.fullRepo) {
-		trace("fullRepo mode -- skipping git clone, workspace from overlay");
-		await fsPromises.mkdir(workDir, { recursive: true });
-		sendMessage({
-			type: "log.line",
-			stepIndex: -1,
-			line: "[workflow-runner] Full-repo mode: skipping git clone (workspace from overlay tarball)"
-		});
-		return;
-	}
-	if (isGlobal) {
-		trace(`starting dual-clone (global workflow)`);
-		await fsPromises.mkdir(workflowDir, { recursive: true });
-		await fsPromises.mkdir(sourceDir, { recursive: true });
-		const workflowAuth = request.workflowAuth ?? request.sourceAuth;
-		const sourceAuth = request.sourceAuth ?? request.workflowAuth;
-		sendMessage({
-			type: "log.line",
-			stepIndex: -1,
-			line: `[workflow-runner] Global workflow: cloning workflow repo ${request.workflowRepoUrl} ref=${request.workflowRef} into ${workflowDir}`
-		});
-		await gitClone({
-			repoUrl: request.workflowRepoUrl,
-			ref: request.workflowRef ?? "",
-			sha: request.workflowSha ?? "",
-			workDir: workflowDir,
-			gitAuth: workflowAuth,
-			token: workflowAuth ? void 0 : request.token
-		});
-		trace("workflow repo clone complete");
-		await excludeScratchFromGit(workflowDir);
-		sendMessage({
-			type: "log.line",
-			stepIndex: -1,
-			line: `[workflow-runner] Global workflow: cloning source repo ${request.repoUrl} ref=${request.ref} into ${sourceDir}`
-		});
-		await gitClone({
-			repoUrl: request.repoUrl,
-			ref: request.ref,
-			sha: request.sha,
-			workDir: sourceDir,
-			gitAuth: sourceAuth,
-			token: sourceAuth ? void 0 : request.token
-		});
-		trace("source repo clone complete");
-		sendMessage({
-			type: "log.line",
-			stepIndex: -1,
-			line: "[workflow-runner] Dual-clone complete"
-		});
-		return;
-	}
-	trace("starting git clone");
-	sendMessage({
-		type: "log.line",
-		stepIndex: -1,
-		line: `[workflow-runner] Cloning ${request.repoUrl} ref=${request.ref} into ${workDir}`
-	});
-	await gitClone({
-		repoUrl: request.repoUrl,
-		ref: request.ref,
-		sha: request.sha,
+	await cloneJobRepos(request, {
 		workDir,
-		gitAuth: request.sourceAuth,
-		token: request.sourceAuth ? void 0 : request.token
-	});
-	await excludeScratchFromGit(workDir);
-	sendMessage({
-		type: "log.line",
-		stepIndex: -1,
-		line: "[workflow-runner] Clone complete"
+		workflowDir,
+		sourceDir
+	}, {
+		isGlobal,
+		log: (line) => {
+			trace(line);
+			sendMessage({
+				type: "log.line",
+				stepIndex: -1,
+				line: `[workflow-runner] ${line}`
+			});
+		},
+		excludeScratchFromGit
 	});
-	trace("git clone complete");
 }
 /**
 * Phase 1b — Apply the encrypted overlay tarball when present (test runs
@@ -5740,6 +6067,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 +6101,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 +6212,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 +6234,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
@@ -5978,6 +6326,7 @@ async function runCancelPathHooks(args) {
 		stepIndex: -1,
 		line: `[kici] Cancel complete, job status: ${cancelFailureReason ? "failed" : "cancelled"}`
 	});
+	maskedSend({ type: "completion-hooks-done" });
 	return {
 		finalStatus: ExecutionJobStatus.enum.failed,
 		cancelFailureReason
@@ -6030,11 +6379,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 +6529,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 +6538,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 +6552,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.
@@ -6360,6 +6737,30 @@ async function runInitPhaseOrFailJob(args) {
 * 7. Execute steps sequentially with IPC reporting
 * 8. Send job.complete and exit
 */
+/**
+* Extract + normalize the job's steps, or return an empty set for a cleanup-only
+* re-run (which runs no steps and skips the generator re-evaluation this would
+* otherwise trigger). Owns the `apiTransport` closure the generator uses.
+*/
+async function extractStepsForRun(workflow, request, globalRepoInfo) {
+	if (request.cleanupOnly) return {
+		normalizedSteps: [],
+		nodes: [],
+		refMap: /* @__PURE__ */ new WeakMap(),
+		driftDroppedJobs: []
+	};
+	const apiTransport = async (method, params) => {
+		const reqId = randomUUID();
+		sendMessage({
+			type: "agent.api.request",
+			requestId: reqId,
+			method,
+			params: params ?? {}
+		});
+		return waitForApiResponse(reqId);
+	};
+	return extractAndNormalizeSteps(workflow, request, apiTransport, globalRepoInfo);
+}
 async function main() {
 	trace(`main() started, isForkMode=${isForkMode}, pid=${process.pid}`);
 	sendMessage({ type: "ready" });
@@ -6367,7 +6768,7 @@ async function main() {
 	const request = (await receiveRequest()).request;
 	trace(`execute request received: workDir=${request.workDir}, workflow=${request.workflowName}, job=${request.jobName}`);
 	const workDir = request.workDir;
-	const defaultTimeoutMs = request.defaultStepTimeoutMs ?? 1800 * 1e3;
+	const defaultTimeoutMs = request.defaultStepTimeoutMs ?? 18e5;
 	const isGlobal = request.isGlobalWorkflow === true;
 	const workflowDir = isGlobal ? join(workDir, "workflow") : workDir;
 	const sourceDir = isGlobal ? join(workDir, "source") : workDir;
@@ -6391,48 +6792,47 @@ async function main() {
 		});
 		jobDeadlineAbort.abort();
 	});
-	await cloneRepoIfRequested(request, workDir, workflowDir, sourceDir, isGlobal);
-	await applyOverlayIfRequested(request, workflowDir);
-	await makeOverlayGitUsable(request, workflowDir);
-	if (aborted) abortAndExit("aborted after clone");
-	await installDependenciesIfNeeded(workflowDir, request);
-	if (aborted) abortAndExit("aborted after deps");
-	await restoreSourceTarballIfRequested(workflowDir, request);
+	if (!request.cleanupOnly) {
+		await cloneRepoIfRequested(request, workDir, workflowDir, sourceDir, isGlobal);
+		await applyOverlayIfRequested(request, workflowDir);
+		await makeOverlayGitUsable(request, workflowDir);
+		if (aborted) abortAndExit("aborted after clone");
+		await installDependenciesIfNeeded(workflowDir, request);
+		if (aborted) abortAndExit("aborted after deps");
+		await restoreSourceTarballIfRequested(workflowDir, request);
+	}
 	const loaded = await loadWorkflowModuleWithCapture(workflowDir, request, isGlobal, maskedSend);
 	const module = loaded.module;
 	const workflow = extractWorkflow(module, request.workflowName);
-	await evaluateConcurrencyGroupIfPresent(workflow, request);
-	const apiTransport = async (method, params) => {
-		const reqId = randomUUID();
-		sendMessage({
-			type: "agent.api.request",
-			requestId: reqId,
-			method,
-			params: params ?? {}
-		});
-		return waitForApiResponse(reqId);
-	};
-	const { normalizedSteps, nodes, refMap, driftDroppedJobs } = await extractAndNormalizeSteps(workflow, request, apiTransport);
+	if (!request.cleanupOnly) await evaluateConcurrencyGroupIfPresent(workflow, request);
+	const globalRepoInfo = setupGlobalWorkflowEnv(request, isGlobal, workflowDir, sourceDir);
+	const { normalizedSteps, nodes, refMap, driftDroppedJobs } = await extractStepsForRun(workflow, request, 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);
-	if (aborted) abortAndExit("aborted after rules");
+	if (!request.cleanupOnly) {
+		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, globalRepoInfo);
+		if (aborted) abortAndExit("aborted after rules");
+	}
 	const jobHooks = collectJobHooks(job);
-	const globalRepoInfo = setupGlobalWorkflowEnv(request, isGlobal, workflowDir, sourceDir);
+	maskedSend({
+		type: "hooks-declared",
+		declaresCleanup: Boolean(jobHooks.onFailure || jobHooks.cleanup)
+	});
 	flushOutputCapture();
 	capturePrepareActive = false;
 	const stepCwd = sourceDir;
-	await runInitPhaseOrFailJob({
+	const envFiles = await createEnvFiles(tmpdir());
+	if (!request.cleanupOnly) await runInitPhaseOrFailJob({
 		job,
 		stepCwd,
-		envFiles: await createEnvFiles(tmpdir()),
+		envFiles,
 		operatorSecretKeys,
 		maskedSend
 	});
-	const { cachePhaseDeps, jobCacheSpecs, jobCacheRestore } = await setupJobCache(stepCwd, normalizedSteps.length, job?.cache, maskedSend);
+	const { cachePhaseDeps, jobCacheSpecs, jobCacheRestore } = await setupJobCache(stepCwd, normalizedSteps.length, request.cleanupOnly ? void 0 : job?.cache, maskedSend);
 	const stepTasks = new StepTaskRegistry();
 	const stepAbortControllers = /* @__PURE__ */ new Map();
 	const jobTempScope = createTempScope();
@@ -6464,14 +6864,12 @@ async function main() {
 		abortStep: (stepIndex) => stepAbortControllers.get(stepIndex)?.abort(),
 		getStepAbortSignal: (stepIndex) => stepAbortControllers.get(stepIndex)?.signal,
 		checkMode: request.checkMode,
+		...request.cleanupOnly ? { forceInitialFailure: true } : {},
 		createStepContext: createStepCtxWithCapture,
 		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 +6973,6 @@ main().catch((error) => {
 	setTimeout(() => process.exit(1), 100);
 });
 //#endregion
-export { buildJobRuleCompletion, buildSandboxShell, buildStepEnvFileHooks, buildStepNeedsContext, coerceStep, createSandboxStepContext, deriveFanout, drainJobTempScope, rawPayloadFromEvent, resolveChangedFilesForRules, resolveEmitEventName, sanitizeTempLabel };
+export { assertUserEmittableEventName, buildConcurrencyGroupContext, buildJobRuleCompletion, buildSandboxShell, buildStepEnvFileHooks, buildStepLoopRuleInputs, buildStepNeedsContext, coerceStep, createSandboxStepContext, deriveFanout, drainJobTempScope, rawPayloadFromEvent, resolveChangedFilesForRules, resolveEmitEventName, sanitizeTempLabel, setupGlobalWorkflowEnv, withRepoWrite };
 
 //# sourceMappingURL=workflow-runner.js.map