@kici-dev/agent 0.1.16 → 0.1.18

package/dist/workflow-runner.js

@@ -1,24 +1,31 @@
 import { register } from "node:module";
 import { createInterface } from "node:readline";
-import crypto, { createHash, randomUUID } from "node:crypto";
+import crypto$1, { createHash, randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
-import fsPromises, { access, cp, mkdir, mkdtemp, readFile, readdir, rename, rm, unlink, writeFile } from "node:fs/promises";
+import fsPromises, { access, cp, lstat, mkdir, mkdtemp, readFile, readdir, realpath, rename, rm, unlink, writeFile } from "node:fs/promises";
 import os, { homedir, tmpdir } from "node:os";
 import path, { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { $ } from "zx";
 import { createLogger, deriveSharedSecret, initZx, normalizeLineEndings, sha256, sha256File, toErrorMessage } from "@kici-dev/shared";
 import { CacheOutcome, CacheStepType, ExecutionJobStatus, ExecutionStepStatus, TimeoutReason } from "@kici-dev/engine";
-import { buildKiciApi, createStepSecrets, evaluateRules, isDynamicJobFn, normalizeCacheSpecs, normalizeRequireApproval, resolveJobOutputs, resolveStepOutputs, setJobOutputsMap, setStepOutputsMap, setStepRefMap } from "@kici-dev/sdk";
+import { buildKiciApi, createStepSecrets, evaluateRules, isDynamicJobFn, normalizeCacheSpecs, normalizeRequireApproval, provenanceSubjectIsPath, resolveJobOutputs, resolveStepOutputs, setJobOutputsMap, setStepOutputsMap, setStepRefMap } from "@kici-dev/sdk";
+import { OIDC_TOKEN_REQUEST_METHOD } from "@kici-dev/engine/protocol/messages/oidc-token-relay";
+import { sha256File as sha256File$1 } from "@kici-dev/core";
+import { calculateJwkThumbprint, decodeJwt, exportJWK, generateKeyPair } from "jose";
+import { IN_TOTO_PAYLOAD_TYPE, KICI_PROVENANCE_AUDIENCE, KICI_PROVENANCE_BUNDLE_MEDIA_TYPE } from "@kici-dev/engine/provenance/bundle";
+import { IN_TOTO_STATEMENT_TYPE, KICI_WORKFLOW_BUILD_TYPE, SLSA_PROVENANCE_PREDICATE_TYPE } from "@kici-dev/engine/provenance/schema";
+import { buildDsseEnvelope, dssePae } from "@kici-dev/engine/provenance/dsse";
+import https from "node:https";
+import http from "node:http";
 import { Readable, Transform } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { createGunzip } from "node:zlib";
-import { c, x } from "tar";
-import https from "node:https";
-import http from "node:http";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import { c, x } from "tar";
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
-import { PNPM_IGNORE_BUILD_GATE_ARG, PackageManager, detectPackageManagerFromManifests } from "@kici-dev/shared/package-manager";
+import { PNPM_IGNORE_BUILD_GATE_ARG, PackageManager, YarnFlavor, detectPackageManagerFromManifests, detectYarnFlavor } from "@kici-dev/shared/package-manager";
+import { parse, stringify } from "yaml";
 var __defProp = Object.defineProperty;
 var __esmMin = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
 var __exportAll = (all, no_symbols) => {
@@ -32,6 +39,122 @@ var __exportAll = (all, no_symbols) => {
 };
 import.meta.url;
 //#endregion
+//#region src/provenance/statement-builder.ts
+/**
+* Build a SLSA v1.0 in-toto provenance statement from the server-truth identity
+* token claims plus the caller-supplied subject. The build context comes
+* entirely from the JWT claims (Platform-minted, unforgeable), so the
+* statement's identity equals the token's identity by construction.
+*/
+/** Build a KiCI SLSA v1.0 provenance statement (validates against the P1.1 schema). */
+function buildProvenanceStatement(input) {
+	const c = input.tokenClaims;
+	return {
+		_type: IN_TOTO_STATEMENT_TYPE,
+		subject: [{
+			name: input.subject.name,
+			digest: input.subject.digest
+		}],
+		predicateType: SLSA_PROVENANCE_PREDICATE_TYPE,
+		predicate: {
+			buildDefinition: {
+				buildType: KICI_WORKFLOW_BUILD_TYPE,
+				externalParameters: { workflow: {
+					repository: c.repository ?? "",
+					ref: c.ref ?? "",
+					path: c.workflow_ref ?? ""
+				} },
+				internalParameters: {
+					...c.sha ? { commit: c.sha } : {},
+					runId: c.kici_run_id,
+					jobId: c.kici_job_id
+				}
+			},
+			runDetails: {
+				builder: {
+					id: `${c.iss}/orchestrator/${c.orchestrator_id ?? "unknown"}`,
+					version: input.builderVersions
+				},
+				metadata: {
+					invocationId: c.kici_run_id,
+					startedOn: input.startedOn,
+					finishedOn: input.finishedOn
+				}
+			}
+		}
+	};
+}
+//#endregion
+//#region src/provenance/sign.ts
+/**
+* Ephemeral-key DSSE signer for KiCI provenance (Mode A).
+*
+* Generates a fresh in-process ES256 keypair (never persisted), DSSE-signs the
+* PAE of the statement bytes with the private half, and returns the envelope
+* plus the public JWK. The public key travels in the bundle so the verifier can
+* check the signature; the key needs no separate trust root because the bundle's
+* identity JWT (verified against the Platform JWKS) anchors the whole package.
+*/
+/** DSSE-sign `statementBytes` with a fresh in-process ephemeral ES256 key. */
+async function signStatementDsse(payloadType, statementBytes) {
+	const { privateKey, publicKey } = await generateKeyPair("ES256", { extractable: true });
+	const publicJwk = await exportJWK(publicKey);
+	publicJwk.alg = "ES256";
+	publicJwk.use = "sig";
+	const kid = await calculateJwkThumbprint(publicJwk, "sha256");
+	publicJwk.kid = kid;
+	const pae = dssePae(payloadType, statementBytes);
+	return {
+		envelope: buildDsseEnvelope(payloadType, statementBytes, [{
+			keyid: kid,
+			sig: new Uint8Array(await crypto.subtle.sign({
+				name: "ECDSA",
+				hash: "SHA-256"
+			}, privateKey, pae))
+		}]),
+		publicJwk
+	};
+}
+//#endregion
+//#region src/provenance/attest.ts
+/**
+* Provenance attestation orchestration (Mode A): request the identity token,
+* build the in-toto statement from its claims, DSSE-sign it with an ephemeral
+* key, assemble the KiCI bundle, and persist it.
+*/
+async function attestProvenance(deps, input) {
+	const audience = input.audience ?? KICI_PROVENANCE_AUDIENCE;
+	const { token } = await deps.getIdToken({ audience });
+	const claims = decodeJwt(token);
+	const now = (deps.now ?? (() => (/* @__PURE__ */ new Date()).toISOString()))();
+	const statement = buildProvenanceStatement({
+		tokenClaims: claims,
+		subject: input.subject,
+		builderVersions: deps.builderVersions,
+		startedOn: now,
+		finishedOn: now
+	});
+	const { envelope, publicJwk } = await signStatementDsse(IN_TOTO_PAYLOAD_TYPE, new TextEncoder().encode(JSON.stringify(statement)));
+	const bundle = {
+		mediaType: KICI_PROVENANCE_BUNDLE_MEDIA_TYPE,
+		dsseEnvelope: envelope,
+		verificationMaterial: {
+			publicKey: publicJwk,
+			identityToken: token
+		}
+	};
+	const subjectDigest = subjectDigestString(input.subject);
+	return {
+		storageKey: await deps.persist(bundle, subjectDigest),
+		bundle,
+		subjectDigest
+	};
+}
+/** Pick the primary digest (`sha256` preferred) as the storage-key discriminator. */
+function subjectDigestString(subject) {
+	return subject.digest.sha256 ?? Object.values(subject.digest)[0];
+}
+//#endregion
 //#region src/execution/dep-restore.ts
 /**
 * Dependency restoration from cached tarballs.
@@ -370,6 +493,7 @@ var init_download = __esmMin((() => {
 }));
 //#endregion
 //#region src/execution/cache/cache-engine.ts
+init_download();
 /**
 * User-facing cache engine (sandbox-side).
 *
@@ -769,7 +893,8 @@ function applyEnvDelta(delta, options) {
 	}
 	const appliedPaths = [];
 	if (delta.pathPrepends.length > 0) {
-		for (const dir of [...delta.pathPrepends].reverse()) target.PATH = target.PATH ? `${dir}:${target.PATH}` : dir;
+		const sep = options.pathSeparator ?? (process.platform === "win32" ? ";" : ":");
+		for (const dir of [...delta.pathPrepends].reverse()) target.PATH = target.PATH ? `${dir}${sep}${target.PATH}` : dir;
 		appliedPaths.push(...delta.pathPrepends);
 	}
 	return {
@@ -1514,6 +1639,256 @@ async function runOneInit(spec, index, stepIndex, stepType, opts) {
 	}
 }
 //#endregion
+//#region src/execution/env-init/presets/directives.ts
+function isPresetString(item) {
+	return item === "mise";
+}
+function isMiseObject(item) {
+	return typeof item === "object" && item !== null && "mise" in item;
+}
+function normalizeOne(item) {
+	if (isPresetString(item)) return {
+		kind: "preset",
+		name: "mise",
+		config: {}
+	};
+	if (isMiseObject(item)) return {
+		kind: "preset",
+		name: "mise",
+		config: item.mise
+	};
+	return {
+		kind: "generic",
+		config: item
+	};
+}
+/**
+* Normalize `Job.init` to an ordered list of directives, without touching the
+* filesystem. `false`/`undefined` -> []; `'auto'` -> one auto directive;
+* presets/generic configs -> their directive; arrays map element-wise.
+* `'auto'` is a scalar only — finding it inside an array throws.
+*/
+function normalizeInitItems(job) {
+	const init = job?.init;
+	if (init === void 0 || init === false) return [];
+	if (init === "auto") return [{ kind: "auto" }];
+	if (Array.isArray(init)) return init.map((item) => {
+		if (item === "auto") throw new Error("init: 'auto' cannot be combined in an array — use it as the sole value");
+		return normalizeOne(item);
+	});
+	return [normalizeOne(init)];
+}
+//#endregion
+//#region src/execution/env-init/presets/mise/cache-key.ts
+/** mise config files, in the fixed order they feed the content hash. */
+const MISE_CONFIG_FILES = [
+	"mise.toml",
+	".mise.toml",
+	".tool-versions"
+];
+/**
+* Derive the default mise cache key from the committed mise config under
+* `cloneRoot`. Concatenates whichever of {@link MISE_CONFIG_FILES} exist (in
+* fixed order) and hashes them. Returns `mise-noconfig` when none exist.
+*/
+async function miseCacheKey(cloneRoot) {
+	const hash = createHash("sha256");
+	let found = false;
+	for (const name of MISE_CONFIG_FILES) try {
+		const buf = await readFile(join(cloneRoot, name));
+		hash.update(name);
+		hash.update(buf);
+		found = true;
+	} catch {}
+	if (!found) return "mise-noconfig";
+	return `mise-${hash.digest("hex").slice(0, 16)}`;
+}
+//#endregion
+//#region src/execution/env-init/presets/mise/templates.ts
+const BASH_RUN = `set -euo pipefail
+command -v mise >/dev/null || curl -fsSL https://mise.run | sh
+export PATH="$HOME/.local/bin:$PATH"
+# Trust the committed config at the clone root (CWD): mise refuses to load an
+# untrusted config, and the author committing it to their repo is the trust signal.
+mise trust
+mise install
+mise env -s bash | sed -n 's/^export //p' | sed '/^PATH=/d' \\
+  | sed -E 's/^([A-Za-z_][A-Za-z0-9_]*)="(.*)"$/\\1=\\2/' >> "$KICI_ENV"
+echo "$HOME/.local/share/mise/shims" >> "$KICI_PATH"`;
+const PWSH_RUN = `$ErrorActionPreference = 'Stop'
+# mise writes informational output (\`mise trusted …\`, install progress) to
+# stderr even on success. Under \`$ErrorActionPreference = 'Stop'\` PowerShell
+# turns any native-command stderr line into a terminating error, so a
+# successful \`mise trust\` would abort the step. Run each mise invocation with
+# the preference relaxed and gate on the real exit code via \`$LASTEXITCODE\`.
+function Invoke-Mise {
+  param([Parameter(ValueFromRemainingArguments = $true)][string[]] $MiseArgs)
+  $prev = $ErrorActionPreference
+  $ErrorActionPreference = 'Continue'
+  try {
+    $output = & mise @MiseArgs 2>&1
+    $code = $LASTEXITCODE
+  } finally {
+    $ErrorActionPreference = $prev
+  }
+  if ($code -ne 0) {
+    throw "mise $($MiseArgs -join ' ') failed (exit $code): $($output -join ' | ')"
+  }
+  return $output
+}
+if (-not (Get-Command mise -ErrorAction SilentlyContinue)) {
+  # The standalone Windows zip extracts to mise/bin/mise.exe, so prepend the
+  # nested bin dir (not the extraction root) to PATH.
+  $dest = Join-Path $env:USERPROFILE '.local\\mise'
+  New-Item -ItemType Directory -Force -Path $dest | Out-Null
+  $zip = Join-Path $env:TEMP 'mise.zip'
+  Invoke-WebRequest -Uri '<ASSET_URL>' -OutFile $zip
+  Expand-Archive -Path $zip -DestinationPath $dest -Force
+  $env:PATH = "$dest\\mise\\bin;$env:PATH"
+}
+# Trust the committed config at the clone root (CWD) — mise refuses to load an
+# untrusted config; the author committing it to their repo is the trust signal.
+Invoke-Mise trust | Out-Null
+Invoke-Mise install | Out-Null
+Invoke-Mise env -s pwsh | ForEach-Object {
+  if ($_ -match '^\\$env:([^=]+) = ''(.*)''$' -and $Matches[1] -ne 'PATH') { "$($Matches[1])=$($Matches[2])" }
+} | Add-Content -Path $env:KICI_ENV
+# Add the real tool install dirs (not the shims dir): the standalone mise lives
+# in a temp dir that is gone by step time, so the shim wrappers (which re-invoke
+# mise) cannot resolve it. bin-paths points straight at the installed binaries.
+Invoke-Mise bin-paths | Add-Content -Path $env:KICI_PATH`;
+/**
+* Pick the mise template for a host platform (Node `process.platform` value).
+* The Windows `run` carries an `<ASSET_URL>` placeholder the expander replaces
+* with the resolved GitHub-release zip URL.
+*/
+function selectMiseTemplate(platform) {
+	if (platform === "win32") return {
+		run: PWSH_RUN,
+		shell: "pwsh",
+		cachePaths: ["~/AppData/Local/mise"]
+	};
+	if (platform === "linux" || platform === "darwin") return {
+		run: BASH_RUN,
+		shell: "bash",
+		cachePaths: ["~/.local/share/mise"]
+	};
+	throw new Error(`unsupported platform for mise preset: ${platform}`);
+}
+//#endregion
+//#region src/execution/env-init/presets/mise/windows-install.ts
+/** Map a Windows `PROCESSOR_ARCHITECTURE` value to mise's asset arch slug. */
+function miseWindowsArch(processorArch) {
+	return processorArch?.toUpperCase() === "ARM64" ? "arm64" : "x64";
+}
+const LATEST_RELEASE_URL = "https://api.github.com/repos/jdx/mise/releases/latest";
+/**
+* Resolve the download URL of the latest mise standalone Windows zip for `arch`.
+* `fetchJson` is injected (defaults to a real fetch) so the resolution is
+* unit-testable without network.
+*/
+async function resolveLatestMiseWindowsAsset(arch, fetchJson = defaultFetchJson) {
+	const release = await fetchJson(LATEST_RELEASE_URL);
+	const suffix = `-windows-${arch}.zip`;
+	const asset = release.assets.find((a) => a.name.endsWith(suffix));
+	if (!asset) throw new Error(`no mise windows ${arch} asset in latest release`);
+	return asset.browser_download_url;
+}
+async function defaultFetchJson(url) {
+	const res = await fetch(url, { headers: { "user-agent": "kici-agent" } });
+	if (!res.ok) throw new Error(`mise release lookup failed: ${res.status}`);
+	return await res.json();
+}
+//#endregion
+//#region src/execution/env-init/presets/mise/expander.ts
+async function buildRun(args, template) {
+	if ((args.platform ?? process.platform) !== "win32") return template.run;
+	const arch = miseWindowsArch(process.env.PROCESSOR_ARCHITECTURE);
+	const url = await (args.resolveWindowsAsset ?? ((a) => resolveLatestMiseWindowsAsset(a)))(arch);
+	return template.run.replace("<ASSET_URL>", url);
+}
+async function defaultCache(cloneRoot, paths) {
+	return {
+		key: await miseCacheKey(cloneRoot),
+		paths,
+		restoreKeys: ["mise-"]
+	};
+}
+//#endregion
+//#region src/execution/env-init/presets/registry.ts
+/**
+* The set of typed presets. Nix is added here (one row) once its provider lands.
+*/
+const PRESET_REGISTRY = { mise: { async expand(args) {
+	const template = selectMiseTemplate(args.platform ?? process.platform);
+	const run = await buildRun(args, template);
+	const cache = args.config.cache === false ? void 0 : args.config.cache ?? await defaultCache(args.cloneRoot, template.cachePaths);
+	const cfg = {
+		run,
+		shell: args.config.shell ?? template.shell,
+		timeout: args.config.timeout ?? 6e5
+	};
+	if (cache) cfg.cache = cache;
+	if (args.config.env) cfg.env = args.config.env;
+	return cfg;
+} } };
+/**
+* Ordered auto-detect table: `init: 'auto'` tries each row against the clone
+* root and accumulates matches in this order. (nix row added with its provider.)
+*/
+const AUTO_DETECT_TABLE = [{
+	markers: [
+		"mise.toml",
+		".mise.toml",
+		".tool-versions"
+	],
+	preset: "mise"
+}];
+//#endregion
+//#region src/execution/env-init/presets/expand.ts
+async function fileExists$2(p) {
+	try {
+		await access(p);
+		return true;
+	} catch {
+		return false;
+	}
+}
+/** Scan the clone root for marker files and return matched presets in table order. */
+async function autoDetect(cloneRoot) {
+	const matched = [];
+	for (const row of AUTO_DETECT_TABLE) for (const marker of row.markers) if (await fileExists$2(join(cloneRoot, marker))) {
+		matched.push(row.preset);
+		break;
+	}
+	return matched;
+}
+async function expandPreset(name, config, opts) {
+	return PRESET_REGISTRY[name].expand({
+		cloneRoot: opts.cloneRoot,
+		config,
+		...opts.platform ? { platform: opts.platform } : {}
+	});
+}
+/**
+* Expand normalized directives into concrete generic init configs, reading the
+* clone root for preset cache keys and `'auto'` marker detection.
+*/
+async function expandInitDirectives(directives, opts) {
+	const out = [];
+	for (const d of directives) if (d.kind === "generic") out.push(d.config);
+	else if (d.kind === "preset") out.push(await expandPreset(d.name, d.config, opts));
+	else {
+		const presets = await autoDetect(opts.cloneRoot);
+		if (presets.length === 0) {
+			opts.log?.("[kici] init: auto — no toolchain detected (no mise.toml / .tool-versions)");
+			continue;
+		}
+		for (const name of presets) out.push(await expandPreset(name, {}, opts));
+	}
+	return out;
+}
+//#endregion
 //#region src/execution/sandbox/job-deadline.ts
 /**
 * Arm a job-level wall-clock deadline. When `timeoutMs` is set and elapses
@@ -1801,7 +2176,7 @@ function noopResult() {
 	};
 }
 /** Build the synthesized env-var name for registry index `i`. */
-function tokenEnvName(jobIdShort, index) {
+function tokenEnvName$1(jobIdShort, index) {
 	return `KICI_NPM_TOKEN_${jobIdShort}_${index}`;
 }
 /** Render the agent-managed block of `.npmrc` lines. */
@@ -1810,7 +2185,7 @@ function renderAgentLines(registries, jobIdShort) {
 	const lines = [];
 	for (let i = 0; i < registries.length; i++) {
 		const reg = registries[i];
-		const envVar = tokenEnvName(jobIdShort, i);
+		const envVar = tokenEnvName$1(jobIdShort, i);
 		const authKey = reg.url.replace(/^https?:/, "");
 		if (reg.scope) lines.push(`${reg.scope}:registry=${reg.url}`);
 		else lines.push(`registry=${reg.url}`);
@@ -1842,7 +2217,7 @@ async function applyNpmRegistryConfig(args) {
 	const tokenEnv = {};
 	const tokensForRedaction = [];
 	for (let i = 0; i < registries.length; i++) {
-		tokenEnv[tokenEnvName(args.jobIdShort, i)] = registries[i].token;
+		tokenEnv[tokenEnvName$1(args.jobIdShort, i)] = registries[i].token;
 		tokensForRedaction.push(registries[i].token);
 	}
 	for (const value of Object.values(installEnvSecrets)) if (value) tokensForRedaction.push(value);
@@ -1878,6 +2253,112 @@ function redactNpmOutput(input, tokens) {
 	}
 	return out;
 }
+//#endregion
+//#region src/execution/yarnrc-berry-config.ts
+/**
+* Apply yarn-berry registry auth + a forced `nodeLinker: node-modules` to a
+* workflow's `.kici/.yarnrc.yml` for the lifetime of one `yarn install`, then
+* restore the file on cleanup. The berry analog of `npm-registry-config.ts`:
+* berry reads `.yarnrc.yml` (not `.npmrc`), so the auth block uses berry's
+* `npmRegistryServer` / `npmScopes` / `npmAuthToken` keys with `${VAR}`
+* env-var interpolation. Token bytes never reach disk — each registry token is
+* exposed as a job-scoped env var and the on-disk value is the `${VAR}`
+* reference.
+*
+* `nodeLinker: node-modules` makes berry lay down a real `node_modules` tree
+* (no PnP `.pnp.cjs`), so the agent's packer / restore / sibling-walk /
+* workflow-loader work unchanged. `enableScripts: false` (when a private
+* registry is configured) keeps dependency lifecycle scripts from seeing the
+* synthesized token env vars — the same security model as npm/pnpm/classic
+* `--ignore-scripts`.
+*
+* Reuses the same `ApplyNpmRegistryConfigArgs` / `ApplyNpmRegistryConfigResult`
+* shapes as the npm overlay so `dep-installer` can pick either by flavor.
+*/
+/** Build the synthesized env-var name for registry index `i`. */
+function tokenEnvName(jobIdShort, index) {
+	return `KICI_NPM_TOKEN_${jobIdShort}_${index}`;
+}
+/** Read + parse an existing `.yarnrc.yml`, or `{}` when absent/empty. */
+async function readOriginalYarnrc(path) {
+	try {
+		const raw = await readFile(path, "utf8");
+		return {
+			raw,
+			doc: parse(raw) ?? {}
+		};
+	} catch (err) {
+		if (err.code === "ENOENT") return {
+			raw: null,
+			doc: {}
+		};
+		throw err;
+	}
+}
+function buildRegistryBlock(envVar, url, alwaysAuth) {
+	return {
+		npmRegistryServer: url,
+		npmAuthToken: `\${${envVar}}`,
+		...alwaysAuth ? { npmAlwaysAuth: true } : {}
+	};
+}
+async function applyYarnrcBerryConfig(args) {
+	const registries = args.npmRegistries ?? [];
+	const installEnvSecrets = args.installEnvSecrets ?? {};
+	const hasPrivateRegistry = registries.length > 0 || Object.keys(installEnvSecrets).length > 0;
+	const yarnrcPath = join(args.kiciDir, ".yarnrc.yml");
+	const { raw: original, doc } = await readOriginalYarnrc(yarnrcPath);
+	const cacheFolder = await mkdtemp(join(tmpdir(), "kici-yarn-berry-cache-"));
+	const merged = {
+		...doc,
+		nodeLinker: "node-modules",
+		enableGlobalCache: false,
+		cacheFolder
+	};
+	const tokenEnv = {};
+	const tokensForRedaction = [];
+	if (hasPrivateRegistry) {
+		merged.enableScripts = false;
+		const npmScopes = { ...doc.npmScopes ?? {} };
+		for (let i = 0; i < registries.length; i++) {
+			const reg = registries[i];
+			const envVar = tokenEnvName(args.jobIdShort, i);
+			tokenEnv[envVar] = reg.token;
+			tokensForRedaction.push(reg.token);
+			const block = buildRegistryBlock(envVar, reg.url, reg.alwaysAuth);
+			if (reg.scope) npmScopes[reg.scope] = block;
+			else {
+				merged.npmRegistryServer = reg.url;
+				merged.npmAuthToken = block.npmAuthToken;
+				if (reg.alwaysAuth) merged.npmAlwaysAuth = true;
+			}
+		}
+		if (Object.keys(npmScopes).length > 0) merged.npmScopes = npmScopes;
+		for (const value of Object.values(installEnvSecrets)) if (value) tokensForRedaction.push(value);
+	}
+	await writeFile(yarnrcPath, stringify(merged), {
+		encoding: "utf8",
+		mode: 384
+	});
+	const cleanup = async () => {
+		try {
+			if (original === null) await unlink(yarnrcPath).catch(() => {});
+			else await writeFile(yarnrcPath, original, { encoding: "utf8" });
+		} catch {}
+		await rm(cacheFolder, {
+			recursive: true,
+			force: true
+		}).catch(() => {});
+	};
+	return {
+		extraEnv: {
+			...installEnvSecrets,
+			...tokenEnv
+		},
+		tokensForRedaction,
+		cleanup
+	};
+}
 const LOCAL_PROTOCOLS = [
 	"workspace:",
 	"file:",
@@ -1946,6 +2427,17 @@ async function fileExists$1(target) {
 		return false;
 	}
 }
+/** Whether the repo-root package.json declares a non-empty `workspaces` array. */
+async function rootHasWorkspaces(repoRoot) {
+	try {
+		const ws = JSON.parse(await readFile(join(repoRoot, "package.json"), "utf-8")).workspaces;
+		if (Array.isArray(ws)) return ws.length > 0;
+		if (ws && typeof ws === "object" && Array.isArray(ws.packages)) return ws.packages.length > 0;
+		return false;
+	} catch {
+		return false;
+	}
+}
 /** Resolve a `file:`/`link:`/`portal:` spec to an absolute path under kiciDir. */
 function resolveLocalPath(kiciDir, dep) {
 	const rawPath = dep.spec.slice(dep.protocol.length);
@@ -1960,8 +2452,31 @@ function isInsideRepo(repoRoot, target) {
 * Classify each local-protocol dependency for the detected package manager and
 * return the ones that are unresolvable in the agent's single-clone model.
 */
-async function findUnresolvableDeps(deps, packageManager, kiciDir, repoRoot) {
+async function findUnresolvableDeps(deps, packageManager, kiciDir, repoRoot, yarnFlavor) {
 	if (packageManager === PackageManager.Npm) return [...deps];
+	if (packageManager === PackageManager.Yarn && yarnFlavor === YarnFlavor.Berry) {
+		const hasWorkspaces = await rootHasWorkspaces(repoRoot);
+		const unresolvable = [];
+		for (const dep of deps) {
+			if (dep.protocol === "workspace:") {
+				if (!hasWorkspaces) unresolvable.push(dep);
+				continue;
+			}
+			if (!isInsideRepo(repoRoot, resolveLocalPath(kiciDir, dep))) unresolvable.push(dep);
+		}
+		return unresolvable;
+	}
+	if (packageManager === PackageManager.Yarn) {
+		const unresolvable = [];
+		for (const dep of deps) {
+			if (dep.protocol === "workspace:" || dep.protocol === "portal:") {
+				unresolvable.push(dep);
+				continue;
+			}
+			if (!isInsideRepo(repoRoot, resolveLocalPath(kiciDir, dep))) unresolvable.push(dep);
+		}
+		return unresolvable;
+	}
 	const hasWorkspaceFile = await fileExists$1(join(repoRoot, "pnpm-workspace.yaml"));
 	const unresolvable = [];
 	for (const dep of deps) {
@@ -1974,9 +2489,11 @@ async function findUnresolvableDeps(deps, packageManager, kiciDir, repoRoot) {
 	return unresolvable;
 }
 /** Build the actionable error for unresolvable local-protocol dependencies. */
-function formatUnresolvableDepError(offenders, packageManager) {
+function formatUnresolvableDepError(offenders, packageManager, yarnFlavor) {
 	const list = offenders.map((o) => `${o.name}: ${o.spec}`).join(", ");
 	if (packageManager === PackageManager.Npm) return `These .kici/ dependencies use local-protocol specifiers npm cannot resolve from a registry: ${list}. npm has no workspace protocol — pin a published version, publish the package to your registry, or use pnpm so an in-repo workspace sibling can be resolved.`;
+	if (packageManager === PackageManager.Yarn && yarnFlavor === YarnFlavor.Berry) return `These .kici/ dependencies cannot be resolved by yarn berry from the cloned repository: ${list}. A workspace: dependency requires a "workspaces" array in the repo-root package.json, and file:/link:/portal: paths must stay inside this repository.`;
+	if (packageManager === PackageManager.Yarn) return `These .kici/ dependencies use specifiers yarn classic cannot resolve: ${list}. yarn classic has no workspace: or portal: protocol — reference an in-repo sibling by a version range (yarn links matching workspace members), use pnpm, or keep file:/link: paths inside this repository. (yarn berry support requires a yarn@2+ packageManager field or a .yarnrc.yml.)`;
 	return `These .kici/ dependencies point outside the cloned repository, which the agent never has: ${list}. A workspace: dependency requires a pnpm-workspace.yaml at the repo root, and file:/link:/portal: paths must stay inside this repository.`;
 }
 /**
@@ -1990,9 +2507,105 @@ async function assertResolvableDeps(args) {
 	if (!pkg) return;
 	const localDeps = findLocalProtocolDeps(pkg);
 	if (localDeps.length === 0) return;
-	const offenders = await findUnresolvableDeps(localDeps, args.packageManager, args.kiciDir, args.repoRoot);
+	const flavor = args.yarnFlavor ?? YarnFlavor.Classic;
+	const offenders = await findUnresolvableDeps(localDeps, args.packageManager, args.kiciDir, args.repoRoot, flavor);
 	if (offenders.length === 0) return;
-	throw new Error(formatUnresolvableDepError(offenders, args.packageManager));
+	throw new Error(formatUnresolvableDepError(offenders, args.packageManager, flavor));
+}
+//#endregion
+//#region src/execution/workspace-siblings.ts
+/**
+* In-repo workspace-sibling discovery for the agent's dependency handling.
+*
+* A pnpm or yarn-classic workspace lays out a `.kici/` member's `workspace:`
+* (pnpm) or version-range (yarn) siblings as symlinks pointing at package
+* directories that live inside the clone but outside `.kici/` and outside the
+* `node_modules` store. The dep-cache packer must travel those sibling dirs with
+* the closure (their symlinks would dangle otherwise), and the yarn install path
+* must build them (the install links a sibling but does not build it).
+*
+* `collectInRepoSiblings` walks a starting `node_modules` (and transitively each
+* discovered sibling's `node_modules`), returning each in-repo sibling directory
+* once, repo-root-relative, in breadth-first discovery order. The starting
+* `node_modules` is a parameter so it serves pnpm + yarn-standalone (seeded at
+* `.kici/node_modules`) and yarn-workspace-member (seeded at the hoisted root
+* `node_modules`).
+*/
+/**
+* The directory yarn lays `.kici`'s dependencies into. A standalone `.kici`
+* (own lockfile, no parent workspace) gets `.kici/node_modules`; a workspace
+* member hoists everything to the repo-root `node_modules`, leaving no
+* `.kici/node_modules`.
+*/
+function resolveYarnNodeModulesRoot(repoRoot, kiciDir) {
+	const kiciNm = join(kiciDir, "node_modules");
+	return existsSync(kiciNm) ? kiciNm : join(repoRoot, "node_modules");
+}
+/**
+* Walk `seedNodeModules` (and transitively each in-repo sibling's
+* `node_modules`) collecting the repo-root-relative directories of workspace
+* siblings — package dirs that live inside the clone but outside `.kici/` and
+* outside the repo-root `node_modules/` store. Returns each dir once, in
+* discovery (BFS) order.
+*/
+async function collectInRepoSiblings(workDir, kiciDir, seedNodeModules = join(kiciDir, "node_modules")) {
+	const repoRoot = resolve(workDir);
+	const kiciResolved = resolve(kiciDir);
+	const rootNodeModules = resolve(join(workDir, "node_modules"));
+	const found = /* @__PURE__ */ new Set();
+	const visited = /* @__PURE__ */ new Set();
+	const queue = [seedNodeModules];
+	while (queue.length > 0) {
+		const nmDir = queue.shift();
+		const real = await realpath(nmDir).catch(() => null);
+		if (!real || visited.has(real)) continue;
+		visited.add(real);
+		for (const target of await resolveNodeModulesLinks(nmDir)) {
+			if (!isInside(repoRoot, target)) continue;
+			if (isInside(kiciResolved, target) || isInside(rootNodeModules, target)) continue;
+			const rel = relative(workDir, target);
+			if (!found.has(rel)) {
+				found.add(rel);
+				queue.push(join(target, "node_modules"));
+			}
+		}
+	}
+	return [...found];
+}
+/** Resolve every package symlink target under a `node_modules` dir (descending one level into `@scope` dirs). */
+async function resolveNodeModulesLinks(nmDir) {
+	const targets = [];
+	for (const entry of await readdir(nmDir).catch(() => [])) {
+		if (entry.startsWith(".")) continue;
+		const entryPath = join(nmDir, entry);
+		if (entry.startsWith("@")) {
+			for (const scoped of await readdir(entryPath).catch(() => [])) {
+				const target = await resolveIfSymlink(join(entryPath, scoped));
+				if (target) targets.push(target);
+			}
+			continue;
+		}
+		const target = await resolveIfSymlink(entryPath);
+		if (target) targets.push(target);
+	}
+	return targets;
+}
+/** Return the real path of `p` if it is a symlink, else null. */
+async function resolveIfSymlink(p) {
+	try {
+		if (!(await lstat(p)).isSymbolicLink()) return null;
+		return await realpath(p);
+	} catch {
+		return null;
+	}
+}
+/** Whether `target` is `root` itself or a path inside it. */
+function isInside(root, target) {
+	const rel = relative(root, target);
+	return rel === "" || !rel.startsWith("..") && !rel.startsWith(`..${sep}`) && !isAbsoluteRel(rel);
+}
+function isAbsoluteRel(rel) {
+	return rel.length > 1 && rel[1] === ":";
 }
 //#endregion
 //#region src/execution/dep-installer.ts
@@ -2002,12 +2615,17 @@ async function assertResolvableDeps(args) {
 * When the dep cache is unavailable or a download fails, the agent installs
 * `.kici/` dependencies directly with the repository's package manager.
 *
-* The package manager is detected from the cloned repo (npm / pnpm); the
+* The package manager is detected from the cloned repo (npm / pnpm / yarn); the
 * presence of `.kici/package.json` signals that deps should be installed. npm
 * is the default and ships with every Node.js install; pnpm is used when the
 * repo is a pnpm workspace so a `.kici/` member can resolve in-repo
-* `workspace:` siblings. yarn is detected but not yet supported and is
-* rejected with an actionable error.
+* `workspace:` siblings. yarn is supported in both flavors: classic (v1) reads
+* `.kici/.npmrc` for registry auth and links version-range workspace siblings;
+* berry (v2+) reads a synthesized `.kici/.yarnrc.yml` for auth, runs with a
+* forced `nodeLinker: node-modules` (so the resulting tree matches classic/npm
+* and the runner's plain node resolution holds), and resolves
+* `workspace:`/`portal:` siblings. Either flavor links the sibling but does not
+* build it, so the agent builds the in-repo closure after install.
 *
 * Security: the install runs with an isolated per-invocation cache/store
 * directory to prevent cache poisoning across build jobs — a malicious
@@ -2033,6 +2651,15 @@ async function detectKiciPackageManager(repoRoot, kiciDir) {
 	return await detectPackageManagerFromManifests(repoRoot) ?? await detectPackageManagerFromManifests(kiciDir) ?? PackageManager.Npm;
 }
 /**
+* Detect the yarn flavor (classic vs berry) for the cloned repo. Mirrors
+* `detectKiciPackageManager`: probe the repo root first, then `.kici/` for a
+* standalone project. Only called when the detected manager is `Yarn`.
+*/
+async function detectKiciYarnFlavor(repoRoot, kiciDir) {
+	if (await detectYarnFlavor(repoRoot) === YarnFlavor.Berry) return YarnFlavor.Berry;
+	return detectYarnFlavor(kiciDir);
+}
+/**
 * Install `.kici/` dependencies inline with the repo's package manager.
 *
 * Falls back to this when the dep cache is unavailable or a download fails.
@@ -2051,20 +2678,28 @@ async function detectKiciPackageManager(repoRoot, kiciDir) {
 async function installDeps(kiciDir, opts = {}) {
 	const repoRoot = opts.repoRoot ?? dirname(kiciDir);
 	const packageManager = await detectKiciPackageManager(repoRoot, kiciDir);
+	const yarnFlavor = packageManager === PackageManager.Yarn ? await detectKiciYarnFlavor(repoRoot, kiciDir) : YarnFlavor.Classic;
 	logger$2.info("Installing deps inline", {
 		packageManager,
+		yarnFlavor,
 		dir: kiciDir
 	});
-	process.stderr.write(`[dep-installer:trace] starting install: pm=${packageManager}, cwd=${kiciDir}\n`);
-	if (packageManager === PackageManager.Yarn) throw new Error("This repository uses yarn, which the KiCI agent does not yet support for .kici/ dependency installation. Use npm or pnpm for the .kici/ project, or open a feature request for yarn support.");
+	process.stderr.write(`[dep-installer:trace] starting install: pm=${packageManager}, flavor=${yarnFlavor}, cwd=${kiciDir}\n`);
 	await assertResolvableDeps({
 		kiciDir,
 		repoRoot,
-		packageManager
+		packageManager,
+		yarnFlavor
 	});
 	const startTime = Date.now();
 	const hasPrivateRegistry = (opts.npmRegistries?.length ?? 0) > 0 || (opts.installEnvSecrets ? Object.keys(opts.installEnvSecrets).length > 0 : false);
-	const registryConfig = await applyNpmRegistryConfig({
+	const isBerry = packageManager === PackageManager.Yarn && yarnFlavor === YarnFlavor.Berry;
+	const registryConfig = isBerry ? await applyYarnrcBerryConfig({
+		kiciDir,
+		npmRegistries: opts.npmRegistries,
+		installEnvSecrets: opts.installEnvSecrets,
+		jobIdShort: opts.jobIdShort ?? "00000000"
+	}) : await applyNpmRegistryConfig({
 		kiciDir,
 		npmRegistries: opts.npmRegistries,
 		installEnvSecrets: opts.installEnvSecrets,
@@ -2076,6 +2711,15 @@ async function installDeps(kiciDir, opts = {}) {
 			hasPrivateRegistry,
 			registryConfig
 		});
+		else if (isBerry) await runYarnBerryInstall({
+			kiciDir,
+			registryConfig
+		});
+		else if (packageManager === PackageManager.Yarn) await runYarnInstall({
+			kiciDir,
+			hasPrivateRegistry,
+			registryConfig
+		});
 		else await runNpmInstall({
 			kiciDir,
 			hasPrivateRegistry,
@@ -2090,6 +2734,7 @@ async function installDeps(kiciDir, opts = {}) {
 		await registryConfig.cleanup();
 	}
 	if (packageManager === PackageManager.Pnpm && await kiciHasLocalProtocolDeps(kiciDir)) await buildWorkspaceClosure(repoRoot);
+	if (packageManager === PackageManager.Yarn) await buildYarnWorkspaceClosure(repoRoot, kiciDir, yarnFlavor);
 	const durationMs = Date.now() - startTime;
 	process.stderr.write(`[dep-installer:trace] install complete: ${durationMs}ms\n`);
 	logger$2.info("Deps installed inline", {
@@ -2177,6 +2822,131 @@ async function runPnpmInstall(args) {
 		}).catch(() => {});
 	}
 }
+/** Pure: argv for `yarn install` with an isolated cache folder. */
+function buildYarnInstallArgs(cacheDir, hasPrivateRegistry) {
+	const a = [
+		"install",
+		"--cache-folder",
+		cacheDir,
+		"--non-interactive",
+		"--no-progress"
+	];
+	if (hasPrivateRegistry) a.push("--ignore-scripts");
+	return a;
+}
+/**
+* Run `yarn install` from `.kici/` with an isolated cache folder. yarn classic
+* reads the synthesized `.kici/.npmrc` (registry + `${VAR}` token expansion) for
+* private-registry auth. A workspace member hoists deps to the repo-root
+* node_modules; a standalone `.kici` gets `.kici/node_modules`. Not
+* `--frozen-lockfile` (resolved URLs in the lockfile may point at a different
+* registry than the synthesized `.npmrc`, e.g. localhost tunnel vs direct IP).
+*/
+async function runYarnInstall(args) {
+	await assertYarnAvailable();
+	const { nodeDir } = resolveNpm();
+	const cacheDir = await mkdtemp(join(tmpdir(), "kici-yarn-cache-"));
+	const env = envWithNodeOnPath(args.registryConfig.extraEnv, nodeDir);
+	const argv = buildYarnInstallArgs(cacheDir, args.hasPrivateRegistry);
+	try {
+		process.stderr.write(`[dep-installer:trace] running: yarn ${argv.join(" ")}\n`);
+		await execFileAsync("yarn", argv, {
+			cwd: args.kiciDir,
+			env,
+			timeout: INSTALL_TIMEOUT_MS,
+			maxBuffer: INSTALL_MAX_BUFFER
+		});
+	} finally {
+		await rm(cacheDir, {
+			recursive: true,
+			force: true
+		}).catch(() => {});
+	}
+}
+/** Pure: argv for a berry `yarn install`. Cache + linker live in .yarnrc.yml. */
+function buildYarnBerryInstallArgs() {
+	return ["install"];
+}
+/**
+* Run a berry `yarn install` from `.kici/`. The synthesized `.kici/.yarnrc.yml`
+* (applied by `applyYarnrcBerryConfig`) forces `nodeLinker: node-modules`, an
+* isolated `cacheFolder`, and — when a private registry is configured —
+* `enableScripts: false` + `npmScopes`/`npmRegistryServer` auth. corepack
+* provisions the repo-pinned berry version; `COREPACK_ENABLE_DOWNLOAD_PROMPT=0`
+* makes that non-interactive. Not `--immutable` (resolved URLs in the lockfile
+* may point at a different registry than the synthesized config).
+*/
+async function runYarnBerryInstall(args) {
+	await assertYarnAvailable();
+	const { nodeDir } = resolveNpm();
+	const env = {
+		...envWithNodeOnPath(args.registryConfig.extraEnv, nodeDir),
+		COREPACK_ENABLE_DOWNLOAD_PROMPT: "0"
+	};
+	const argv = buildYarnBerryInstallArgs();
+	process.stderr.write(`[dep-installer:trace] running: yarn ${argv.join(" ")} (berry)\n`);
+	await execFileAsync("yarn", argv, {
+		cwd: args.kiciDir,
+		env,
+		timeout: INSTALL_TIMEOUT_MS,
+		maxBuffer: INSTALL_MAX_BUFFER
+	});
+}
+/** Throw an actionable error when the repo needs yarn but it is not installed. */
+async function assertYarnAvailable() {
+	try {
+		await execFileAsync("yarn", ["--version"], {
+			timeout: 3e4,
+			cwd: tmpdir()
+		});
+	} catch (e) {
+		throw new Error(`This repository uses yarn, but yarn is not available on this agent. Install yarn (e.g. \`corepack enable\`) or run on a container/Firecracker agent that bundles it. (${toErrorMessage(e)})`);
+	}
+}
+/**
+* Build the in-repo workspace siblings `.kici` depends on (yarn links them on
+* install but does not build them). Walks siblings from the resolved
+* node_modules root and runs each sibling's `build` script in leaf-first
+* (reverse-discovery) order with a clean env (no synthesized registry tokens).
+* Deep cross-sibling build chains may build out of strict topological order —
+* real `.kici` closures are shallow.
+*/
+async function buildYarnWorkspaceClosure(repoRoot, kiciDir, yarnFlavor) {
+	const siblings = await collectInRepoSiblings(repoRoot, kiciDir, resolveYarnNodeModulesRoot(repoRoot, kiciDir));
+	if (siblings.length === 0) return;
+	const { nodeDir } = resolveNpm();
+	const env = envWithNodeOnPath({}, nodeDir);
+	for (const rel of [...siblings].reverse()) {
+		const sibDir = join(repoRoot, rel);
+		if (!await siblingHasBuildScript(sibDir)) continue;
+		const [argv, cwd] = yarnFlavor === YarnFlavor.Berry ? [["run", "build"], sibDir] : [[
+			"--cwd",
+			sibDir,
+			"run",
+			"build"
+		], repoRoot];
+		process.stderr.write(`[dep-installer:trace] building yarn sibling (${yarnFlavor}): yarn ${argv.join(" ")} @ ${cwd}\n`);
+		try {
+			await execFileAsync("yarn", argv, {
+				cwd,
+				env,
+				timeout: INSTALL_TIMEOUT_MS,
+				maxBuffer: INSTALL_MAX_BUFFER
+			});
+		} catch (e) {
+			logSubprocessStreams(e, []);
+			throw new Error(`Failed to build .kici yarn workspace sibling ${rel}: ${describeExecError(e)}`);
+		}
+	}
+}
+/** Whether a sibling package.json declares a `build` script. */
+async function siblingHasBuildScript(sibDir) {
+	try {
+		return typeof JSON.parse(await readFile(join(sibDir, "package.json"), "utf-8")).scripts?.build === "string";
+	} catch {
+		return false;
+	}
+}
 /**
 * Build the in-repo dependency closure of the `.kici/` package so a
 * `workspace:` sibling's build output exists before the workflow that imports
@@ -2220,7 +2990,10 @@ function describeExecError(e) {
 /** Throw an actionable error when the repo needs pnpm but it is not installed. */
 async function assertPnpmAvailable() {
 	try {
-		await execFileAsync("pnpm", ["--version"], { timeout: 3e4 });
+		await execFileAsync("pnpm", ["--version"], {
+			timeout: 3e4,
+			cwd: tmpdir()
+		});
 	} catch (e) {
 		throw new Error(`This repository is a pnpm workspace, but pnpm is not available on this agent. Install pnpm (e.g. \`corepack enable\`) or run on a container/ Firecracker agent that bundles it. (${toErrorMessage(e)})`);
 	}
@@ -2240,8 +3013,8 @@ function logSubprocessStreams(e, tokens) {
 * no Rolldown step at runtime. `@kici-dev/sdk` and host-repo deps resolve via
 * Node's normal ESM lookup against `.kici/node_modules/`.
 */
-const AGENT_SDK_VERSION = "0.1.16";
-const AGENT_SDK_BUNDLE_HASH = "cd4b8e0d91efe578c96e7c746f89b44a3df8fcaebaec2185399168ef8eb4ebca";
+const AGENT_SDK_VERSION = "0.1.18";
+const AGENT_SDK_BUNDLE_HASH = "8308089347c304e41b457d3867b17bbff11d6b5cd9706b6823e7abdbd849f33f";
 /**
 * Register the `@kici-dev/core/ts-loader-hook` oxc-transform ESM loader hook so
 * subsequent dynamic `import()` calls for `.ts` / `.tsx` files transform on the
@@ -2364,18 +3137,20 @@ 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) {
+async function extractStepsFromDynamicJob(workflow, dynamicIndex, jobName, event, env, apiTransport, expectedJobNames, upstreamSnapshot, declaredNeeds) {
 	const dynamicFn = extractDynamicJobFn(workflow, dynamicIndex);
 	const { $ } = await import("zx");
 	const { createLogger } = await import("@kici-dev/shared");
-	const { buildKiciApi } = await import("@kici-dev/sdk");
+	const { buildKiciApi, buildNeedsContext } = await import("@kici-dev/sdk");
 	const log = createLogger({ prefix: `dynamic-job-fn:${workflow.name}` });
 	const kici = buildKiciApi(apiTransport ?? (() => Promise.reject(/* @__PURE__ */ new Error("Agent API not available during re-evaluation"))));
+	const needs = upstreamSnapshot ? buildNeedsContext(upstreamSnapshot, declaredNeeds ?? []) : void 0;
 	const generatedJobs = await dynamicFn({
 		$,
 		ctx: {
 			workflow: { name: workflow.name },
-			event
+			event,
+			...needs && { needs }
 		},
 		log,
 		env,
@@ -2424,7 +3199,6 @@ async function extractStepsFromDynamicJob(workflow, dynamicIndex, jobName, event
 * runs without a preceding build (cache infrastructure unavailable, or a
 * build job that failed but left dynamic dispatch in flight).
 */
-init_download();
 init_dep_restore();
 const logger$1 = createLogger({ prefix: "source-restore" });
 async function extractSourceTarball(data, targetDir) {
@@ -2470,18 +3244,17 @@ async function restoreSource(workDir, sourceTarUrl) {
 init_download();
 const logger = createLogger({ prefix: "overlay-applier" });
 const IV_LENGTH = 12;
-const AUTH_TAG_LENGTH = 16;
 /**
 * Decrypt an encrypted buffer using AES-256-GCM.
 *
 * Wire format: [12-byte IV][16-byte auth tag][ciphertext]
 */
 function decryptBuffer(encrypted, aesKey) {
-	if (encrypted.length < IV_LENGTH + AUTH_TAG_LENGTH) throw new Error(`Tarball decryption failed: encrypted data too short (${encrypted.length} bytes, minimum ${IV_LENGTH + AUTH_TAG_LENGTH} bytes)`);
+	if (encrypted.length < 28) throw new Error(`Tarball decryption failed: encrypted data too short (${encrypted.length} bytes, minimum 28 bytes)`);
 	const iv = encrypted.subarray(0, IV_LENGTH);
-	const authTag = encrypted.subarray(IV_LENGTH, IV_LENGTH + AUTH_TAG_LENGTH);
-	const ciphertext = encrypted.subarray(IV_LENGTH + AUTH_TAG_LENGTH);
-	const decipher = crypto.createDecipheriv("aes-256-gcm", aesKey, iv);
+	const authTag = encrypted.subarray(IV_LENGTH, 28);
+	const ciphertext = encrypted.subarray(28);
+	const decipher = crypto$1.createDecipheriv("aes-256-gcm", aesKey, iv);
 	decipher.setAuthTag(authTag);
 	try {
 		return Buffer.concat([decipher.update(ciphertext), decipher.final()]);
@@ -2601,7 +3374,9 @@ async function applyOverlay(config) {
 * This file is compiled alongside the agent by rolldown (existing build), but
 * runs as a SEPARATE process spawned by the sandbox backend.
 */
+init_download();
 init_dep_restore();
+const AGENT_VERSION = "0.1.18";
 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`);
@@ -2911,6 +3686,33 @@ function waitForApiResponse(requestId) {
 const pendingCacheResponses = /* @__PURE__ */ new Map();
 /** Default timeout for a cache request relay (matches the upload-URL request budget). */
 const CACHE_RESPONSE_TIMEOUT_MS = 3e4;
+/**
+* Pending promises for provenance.response messages from the agent.
+* Key: requestId (correlates provenance.request -> provenance.response).
+*/
+const pendingProvenanceResponses = /* @__PURE__ */ new Map();
+/** Wait for a provenance.response from the agent with the given requestId. */
+function waitForProvenanceResponse(requestId) {
+	return new Promise((resolve, reject) => {
+		const timer = setTimeout(() => {
+			pendingProvenanceResponses.delete(requestId);
+			reject(/* @__PURE__ */ new Error(`Provenance request timed out after ${CACHE_RESPONSE_TIMEOUT_MS}ms`));
+		}, CACHE_RESPONSE_TIMEOUT_MS);
+		pendingProvenanceResponses.set(requestId, {
+			resolve: (response) => {
+				clearTimeout(timer);
+				pendingProvenanceResponses.delete(requestId);
+				resolve(response);
+			},
+			reject: (err) => {
+				clearTimeout(timer);
+				pendingProvenanceResponses.delete(requestId);
+				reject(err);
+			},
+			timer
+		});
+	});
+}
 /** Wait for a cache.response from the agent with the given requestId. */
 function waitForCacheResponse(requestId) {
 	return new Promise((resolve, reject) => {
@@ -3051,6 +3853,64 @@ function buildCacheTransport() {
 		}
 	};
 }
+/** Send a `provenance.request` IPC and await the matching `provenance.response`. */
+async function relayProvenanceIpc(request) {
+	const requestId = randomUUID();
+	sendMessage({
+		type: "provenance.request",
+		requestId,
+		...request
+	});
+	const response = await waitForProvenanceResponse(requestId);
+	if (response.error) throw new Error(`Provenance relay failed: ${response.error}`);
+	return response;
+}
+/**
+* Build the `ctx.attestProvenance` step helper. Resolves a `path` subject to a
+* SHA-256 digest, threads the identity token via the supplied OIDC getter, and
+* persists the bundle over the IPC -> WS provenance-upload relay.
+*/
+function buildAttestProvenanceFn(request, workDir, getIdToken) {
+	return async (opts) => {
+		const subject = provenanceSubjectIsPath(opts.subject) ? {
+			name: opts.subject.name,
+			digest: { sha256: await sha256File$1(join(workDir, opts.subject.path)) }
+		} : {
+			name: opts.subject.name,
+			digest: opts.subject.digest
+		};
+		const result = await attestProvenance({
+			getIdToken,
+			builderVersions: {
+				"kici-agent": AGENT_VERSION,
+				"kici-orchestrator": "unknown"
+			},
+			persist: async (bundle, subjectDigest) => {
+				const urlResponse = await relayProvenanceIpc({
+					op: "requestUploadUrl",
+					subjectDigest
+				});
+				if (!urlResponse.uploadUrl) throw new Error("Orchestrator returned no provenance upload URL");
+				await uploadToPresignedUrl(urlResponse.uploadUrl, Buffer.from(JSON.stringify(bundle)));
+				await relayProvenanceIpc({
+					op: "complete",
+					subjectDigest,
+					subjectName: subject.name,
+					mediaType: bundle.mediaType
+				});
+				return `provenance/${request.runId}/${request.jobId}/${subjectDigest}.kici.json`;
+			}
+		}, {
+			subject,
+			...opts.audience !== void 0 && { audience: opts.audience }
+		});
+		return {
+			storageKey: result.storageKey,
+			subjectDigest: result.subjectDigest,
+			bundleMediaType: result.bundle.mediaType
+		};
+	};
+}
 /**
 * Build the declarative-cache phase dependencies and run the job-level cache
 * restore (Phase 9b).
@@ -3108,6 +3968,9 @@ function dispatchAgentMessage(msg) {
 	} else if (msg.type === "cache.response") {
 		const pending = pendingCacheResponses.get(msg.requestId);
 		if (pending) pending.resolve(msg);
+	} else if (msg.type === "provenance.response") {
+		const pending = pendingProvenanceResponses.get(msg.requestId);
+		if (pending) pending.resolve(msg);
 	} else if (msg.type === "approval.resolved") {
 		const pending = pendingApprovalResolutions.get(msg.requestId);
 		if (pending) pending.resolve(msg);
@@ -3289,10 +4152,22 @@ function buildSandboxShell(cwd, stepIndex, maskedSendFn) {
 * NOT serialized across the process boundary. This means zx $ runs natively
 * inside this process with full shell access.
 */
-function createSandboxStepContext(workDir, stepIndex, stepName, request, maskedSendFn, outputsMap, refMap, operatorSecretKeys, secretOutputs, jobOutputsMap, secrets) {
+function createSandboxStepContext(workDir, stepIndex, stepName, request, maskedSendFn, outputsMap, refMap, operatorSecretKeys, secretOutputs, jobOutputsMap, secrets, masker) {
 	const step$ = buildSandboxShell(workDir, stepIndex, maskedSendFn);
 	const log = createIpcLogger(stepIndex, stepName, maskedSendFn);
 	const rawPayload = rawPayloadFromEvent(request.event);
+	const kici = buildKiciApi(async (method, params) => {
+		const reqId = randomUUID();
+		sendMessage({
+			type: "agent.api.request",
+			requestId: reqId,
+			method,
+			params: params ?? {}
+		});
+		const result = await waitForApiResponse(reqId);
+		if (method === OIDC_TOKEN_REQUEST_METHOD && result && typeof result.token === "string") masker.registerSecrets({ __oidc_token__: result.token });
+		return result;
+	}, { jobId: request.jobId });
 	return {
 		$: step$,
 		log,
@@ -3344,18 +4219,13 @@ function createSandboxStepContext(workDir, stepIndex, stepName, request, maskedS
 		setSecretOutput: (key, value) => {
 			secretOutputs.set(key, value);
 		},
-		kici: buildKiciApi(async (method, params) => {
-			const reqId = randomUUID();
-			sendMessage({
-				type: "agent.api.request",
-				requestId: reqId,
-				method,
-				params: params ?? {}
-			});
-			return waitForApiResponse(reqId);
-		}),
+		kici,
+		attestProvenance: buildAttestProvenanceFn(request, workDir, (o) => kici.oidc.token(o)),
 		...rawPayload && { rawPayload },
-		...request.provider && { provider: request.provider }
+		...request.provider && { provider: request.provider },
+		...request.matrixValues && { matrix: request.matrixValues },
+		...request.host && { host: request.host },
+		...request.agent && { agent: request.agent }
 	};
 }
 /** Raw provider webhook body for ctx.rawPayload — nested in the envelope. */
@@ -3498,6 +4368,31 @@ async function applyOverlayIfRequested(request, workflowDir) {
 	trace(`overlay applied: ${overlayResult.filesApplied} files, ${overlayResult.filesDeleted} deletions`);
 }
 /**
+* Phase 1c — Make git usable in a full-repo overlay workspace.
+*
+* `kici run remote` uploads the developer's working tree (including `.git`) as
+* a self-contained overlay; no clone happens, so the extracted `.git` directory
+* is owned by whatever UID wrote the tarball. Under rootless podman that UID may
+* not match the container UID, which trips git's "dubious ownership" /
+* `safe.directory` check and makes every step `git` command fail.
+*
+* Mirroring the `file://`-clone fix in checkout/git-clone.ts, we point
+* `GIT_CONFIG_GLOBAL` at a temp config carrying `safe.directory = *`. Setting it
+* on `process.env` here (before the step loop) means every step subprocess —
+* each zx `$` snapshots `process.env` at context creation — inherits it, so git
+* works in steps exactly as it does locally. We also register the dep-restore
+* scratch-dir exclude now that a real `.git` exists in the workspace.
+*/
+async function makeOverlayGitUsable(request, workspaceDir) {
+	if (!request.fullRepo) return;
+	if (!existsSync(join(workspaceDir, ".git"))) return;
+	const cfgPath = join(await fsPromises.mkdtemp(join(tmpdir(), "kici-gitcfg-")), "config");
+	await fsPromises.writeFile(cfgPath, "[safe]\n	directory = *\n", { mode: 384 });
+	process.env.GIT_CONFIG_GLOBAL = cfgPath;
+	trace(`fullRepo git safe.directory configured via GIT_CONFIG_GLOBAL=${cfgPath}`);
+	await excludeScratchFromGit(workspaceDir);
+}
+/**
 * Phase 2 — Restore deps from cache (with hash-mismatch hard-fail) OR fall
 * back to inline install. Skipped when `.kici/package.json` doesn't exist.
 * For global workflows deps come from the workflow repo (where `.kici/` lives).
@@ -3881,7 +4776,7 @@ async function extractAndNormalizeSteps(workflow, request, apiTransport) {
 	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);
+		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);
 		rawSteps = dynamicResult.steps;
 		driftDroppedJobs = dynamicResult.droppedJobs;
 		if (driftDroppedJobs.length > 0) trace(`Determinism drift: ${driftDroppedJobs.length} job(s) dropped: ${driftDroppedJobs.join(", ")}`);
@@ -3980,15 +4875,6 @@ function collectJobHooks(job) {
 	return jobHooks;
 }
 /**
-* Normalize `Job.init` (config | config[] | false | undefined) to an ordered
-* array of init specs. `false` is an explicit opt-out and `undefined` (no
-* config) both resolve to an empty list — the init phase is then a no-op.
-*/
-function resolveInitSpecs(job) {
-	if (!job || job.init === void 0 || job.init === false) return [];
-	return Array.isArray(job.init) ? [...job.init] : [job.init];
-}
-/**
 * Base stepIndex for the `init:<n>` pseudo-steps. The step loop reserves the
 * range starting at `steps.length` for hook pseudo-steps (`beforeStep` =
 * `steps.length + i*2`, `afterStep` = `steps.length + i*2 + 1`, and job-level
@@ -4064,7 +4950,16 @@ function buildStepEnvFileHooks(envFiles, operatorSecretKeys, maskedSend) {
 */
 async function runInitPhaseOrFailJob(args) {
 	const { job, stepCwd, envFiles, operatorSecretKeys, maskedSend } = args;
-	const initSpecs = resolveInitSpecs(job);
+	const directives = normalizeInitItems(job);
+	if (directives.length === 0) return;
+	const initSpecs = await expandInitDirectives(directives, {
+		cloneRoot: stepCwd,
+		log: (line) => maskedSend({
+			type: "log.line",
+			stepIndex: -1,
+			line
+		})
+	});
 	if (initSpecs.length === 0) return;
 	const initResult = await runInitPhase({
 		specs: initSpecs,
@@ -4139,6 +5034,7 @@ async function main() {
 	});
 	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");
@@ -4182,7 +5078,7 @@ async function main() {
 		const handle = buildStepSecrets(request, masker, () => {});
 		currentStepSecrets = handle.secrets;
 		currentStepDispose = handle.dispose;
-		const ctx = createSandboxStepContext(stepCwd, stepIndex, stepName, request, maskedSend, outputsMap, refMap, operatorSecretKeys, secretOutputs, jobOutputsMap, handle.secrets);
+		const ctx = createSandboxStepContext(stepCwd, stepIndex, stepName, request, maskedSend, outputsMap, refMap, operatorSecretKeys, secretOutputs, jobOutputsMap, handle.secrets, masker);
 		if (globalRepoInfo) {
 			ctx.workflowRepo = globalRepoInfo.workflowRepo;
 			ctx.sourceRepo = globalRepoInfo.sourceRepo;
@@ -4306,6 +5202,6 @@ main().catch((error) => {
 	setTimeout(() => process.exit(1), 100);
 });
 //#endregion
-export { rawPayloadFromEvent, resolveInitSpecs };
+export { createSandboxStepContext, rawPayloadFromEvent };
 
 //# sourceMappingURL=workflow-runner.js.map