@kici-dev/agent 0.5.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,
@@ -780,7 +784,7 @@ 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);
+		const sizeMB = (data.length / 1048576).toFixed(2);
 		logger$6.info("Dependencies restored from cache (file)", {
 			sizeMB,
 			targetDir: workDir
@@ -814,7 +818,7 @@ async function restoreDeps(workDir, depsUrl, depsHash) {
 var logger$6, DOWNLOAD_TIMEOUT_MS$2, SCRATCH_DIR_BASENAME_PREFIX, SCRATCH_DIR_GIT_EXCLUDE_GLOB;
 var init_dep_restore = __esmMin((() => {
 	logger$6 = createLogger({ prefix: "dep-restore" });
-	DOWNLOAD_TIMEOUT_MS$2 = 300 * 1e3;
+	DOWNLOAD_TIMEOUT_MS$2 = 3e5;
 	SCRATCH_DIR_BASENAME_PREFIX = ".dep-restore-scratch-";
 	SCRATCH_DIR_GIT_EXCLUDE_GLOB = `.kici/${SCRATCH_DIR_BASENAME_PREFIX}*`;
 }));
@@ -952,8 +956,8 @@ var logger$5, DOWNLOAD_TIMEOUT_MS$1, UPLOAD_TIMEOUT_MS, UPLOAD_RETRY_BASE_DELAY_
 var init_download = __esmMin((() => {
 	init_dep_restore();
 	logger$5 = createLogger({ prefix: "agent:download" });
-	DOWNLOAD_TIMEOUT_MS$1 = 300 * 1e3;
-	UPLOAD_TIMEOUT_MS = 300 * 1e3;
+	DOWNLOAD_TIMEOUT_MS$1 = 3e5;
+	UPLOAD_TIMEOUT_MS = 3e5;
 	UPLOAD_RETRY_BASE_DELAY_MS = 500;
 	PresignedUploadHttpError = class extends Error {
 		statusCode;
@@ -986,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
@@ -1065,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)) {
@@ -1078,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);
 		}
 	}
 }
@@ -1557,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.
 *
@@ -2435,6 +2467,7 @@ async function runJobCompletionHooks(opts, initial, outputsMap, startTime) {
 			opts
 		});
 	}
+	opts.sendIpc({ type: "completion-hooks-done" });
 	return state;
 }
 /**
@@ -2451,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,
@@ -2555,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
@@ -2921,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
@@ -2947,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",
@@ -3001,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", [
@@ -3056,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.
@@ -3589,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
@@ -4002,7 +4146,8 @@ function buildGeneratorContext(input) {
 */
 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,
@@ -4015,8 +4160,8 @@ async function resolveWorkflowSdkSetters(workflowFilePath) {
 		setJobOutputsMap
 	};
 }
-const AGENT_SDK_VERSION = "0.5.0";
-const AGENT_SDK_BUNDLE_HASH = "5b85e7cffa4a08e39329ff80448a2744af8e5b5f9840ec3801fad45ed11a3de9";
+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
@@ -4362,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");
@@ -4448,7 +4594,7 @@ async function applyOverlay(config) {
 */
 init_download();
 init_dep_restore();
-const AGENT_VERSION = "0.5.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`);
@@ -4665,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(() => {
@@ -4849,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) => {
@@ -5175,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);
@@ -5276,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();
@@ -5302,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
@@ -5347,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 });
@@ -5443,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
@@ -5545,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",
@@ -5569,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 },
@@ -5581,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 } : {};
 		})()
 	};
@@ -5639,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
@@ -6155,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
@@ -6565,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" });
@@ -6572,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;
@@ -6596,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);
+	if (!request.cleanupOnly) await evaluateConcurrencyGroupIfPresent(workflow, request);
 	const globalRepoInfo = setupGlobalWorkflowEnv(request, isGlobal, workflowDir, sourceDir);
-	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, globalRepoInfo);
+	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, globalRepoInfo);
-	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);
+	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();
@@ -6669,6 +6864,7 @@ 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,
@@ -6777,6 +6973,6 @@ main().catch((error) => {
 	setTimeout(() => process.exit(1), 100);
 });
 //#endregion
-export { buildConcurrencyGroupContext, buildJobRuleCompletion, buildSandboxShell, buildStepEnvFileHooks, buildStepLoopRuleInputs, buildStepNeedsContext, coerceStep, createSandboxStepContext, deriveFanout, drainJobTempScope, rawPayloadFromEvent, resolveChangedFilesForRules, resolveEmitEventName, sanitizeTempLabel, setupGlobalWorkflowEnv };
+export { assertUserEmittableEventName, buildConcurrencyGroupContext, buildJobRuleCompletion, buildSandboxShell, buildStepEnvFileHooks, buildStepLoopRuleInputs, buildStepNeedsContext, coerceStep, createSandboxStepContext, deriveFanout, drainJobTempScope, rawPayloadFromEvent, resolveChangedFilesForRules, resolveEmitEventName, sanitizeTempLabel, setupGlobalWorkflowEnv, withRepoWrite };
 
 //# sourceMappingURL=workflow-runner.js.map