@kici-dev/agent 0.1.16 → 0.1.18

package/dist/index.js

@@ -5,12 +5,13 @@ import { z } from "zod";
 import { LOGGER_ENV_VARS, defineEnv, validateUnknownKiciVars } from "@kici-dev/shared/env";
 import { KNOWN_ROLES, validateNoReservedLabels } from "@kici-dev/engine";
 import { execFile } from "node:child_process";
-import { access, cp, mkdir, mkdtemp, readFile, readdir, rename, rm, unlink, writeFile } from "node:fs/promises";
+import { access, cp, lstat, mkdir, mkdtemp, readFile, readdir, realpath, rename, rm, unlink, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { promisify } from "node:util";
 import { createLogger, sha256, toErrorMessage } from "@kici-dev/shared";
-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 { existsSync } from "node:fs";
+import { parse, stringify } from "yaml";
 import { Readable, Transform } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { createGunzip } from "node:zlib";
@@ -214,7 +215,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. */
@@ -223,7 +224,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}`);
@@ -255,7 +256,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);
@@ -292,6 +293,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
+	};
+}
+//#endregion
 //#region src/execution/validate-kici-deps.ts
 /**
 * Pre-install validation for `.kici/` dependency specifiers.
@@ -309,6 +416,13 @@ function redactNpmOutput(input, tokens) {
 *   clones the whole repo, so an in-repo sibling is present), and resolves
 *   `file:`/`link:`/`portal:` against a path — allowed when that path stays
 *   inside the cloned repo, rejected when it escapes the clone.
+* - yarn classic (v1) has no `workspace:` protocol and no `portal:` — it links
+*   in-repo siblings by version range, not by a local specifier — so both are
+*   rejected with guidance; `file:`/`link:` are allowed when the path stays
+*   inside the clone, rejected when it escapes.
+* - yarn berry (v2+) resolves `workspace:` against the repo-root package.json
+*   `workspaces` field and `portal:`/`file:`/`link:` against inside-repo paths,
+*   so those are allowed when present/inside the clone and rejected otherwise.
 *
 * This module performs that classification so unresolvable specifiers fail
 * fast with guidance rather than a cryptic install error.
@@ -389,6 +503,17 @@ async function fileExists(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);
@@ -403,8 +528,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(join(repoRoot, "pnpm-workspace.yaml"));
 	const unresolvable = [];
 	for (const dep of deps) {
@@ -417,9 +565,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.`;
 }
 /**
@@ -433,9 +583,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
@@ -445,12 +691,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
@@ -476,6 +727,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.
@@ -494,20 +754,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,
@@ -519,6 +787,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,
@@ -533,6 +810,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", {
@@ -620,6 +898,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
@@ -663,7 +1066,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)})`);
 	}

package/dist/provenance/attest.d.ts

@@ -0,0 +1,30 @@
+import { type KiciBundle } from '@kici-dev/engine/provenance/bundle';
+import type { OidcTokenResult } from '@kici-dev/engine/protocol/messages/oidc-token-relay';
+import { type ProvenanceSubject } from './statement-builder.js';
+export interface AttestDeps {
+    /** P1.4 relay: returns a KiCI ID token bound to the current job. */
+    getIdToken: (opts: {
+        audience: string;
+    }) => Promise<OidcTokenResult>;
+    /** Upload the serialized bundle; returns the storage key it was written to. */
+    persist: (bundle: KiciBundle, subjectDigest: string) => Promise<string>;
+    builderVersions: {
+        'kici-agent': string;
+        'kici-orchestrator': string;
+    };
+    /** Injectable clock for deterministic tests; defaults to wall time. */
+    now?: () => string;
+}
+export interface AttestInput {
+    subject: ProvenanceSubject;
+    audience?: string;
+}
+export interface AttestResult {
+    storageKey: string;
+    bundle: KiciBundle;
+    subjectDigest: string;
+}
+export declare function attestProvenance(deps: AttestDeps, input: AttestInput): Promise<AttestResult>;
+/** Pick the primary digest (`sha256` preferred) as the storage-key discriminator. */
+export declare function subjectDigestString(subject: ProvenanceSubject): string;
+//# sourceMappingURL=attest.d.ts.map

package/dist/provenance/sign.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 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.
+ */
+import { type JWK } from 'jose';
+import { type DsseEnvelope } from '@kici-dev/engine/provenance/dsse';
+export interface SignedStatement {
+    envelope: DsseEnvelope;
+    /** Ephemeral public key as a JWK, with `kid` = its RFC 7638 thumbprint. */
+    publicJwk: JWK & {
+        kid: string;
+    };
+}
+/** DSSE-sign `statementBytes` with a fresh in-process ephemeral ES256 key. */
+export declare function signStatementDsse(payloadType: string, statementBytes: Uint8Array): Promise<SignedStatement>;
+//# sourceMappingURL=sign.d.ts.map

package/dist/provenance/statement-builder.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 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.
+ */
+import { type KiciProvenanceStatement } from '@kici-dev/engine/provenance/schema';
+/** The KiCI identity-token claims the builder reads (Platform server-truth). */
+export interface ProvenanceTokenClaims {
+    iss: string;
+    repository?: string | null;
+    ref?: string | null;
+    sha?: string | null;
+    workflow_ref?: string | null;
+    kici_run_id: string;
+    kici_job_id: string;
+    orchestrator_id?: string | null;
+}
+/** Caller-supplied artifact subject: a name plus a lowercase-hex digest map. */
+export interface ProvenanceSubject {
+    name: string;
+    digest: Record<string, string>;
+}
+export interface BuildStatementInput {
+    tokenClaims: ProvenanceTokenClaims;
+    subject: ProvenanceSubject;
+    builderVersions: {
+        'kici-agent': string;
+        'kici-orchestrator': string;
+    };
+    /** ISO-8601 timestamp with offset. */
+    startedOn: string;
+    /** ISO-8601 timestamp with offset. */
+    finishedOn: string;
+}
+/** Build a KiCI SLSA v1.0 provenance statement (validates against the P1.1 schema). */
+export declare function buildProvenanceStatement(input: BuildStatementInput): KiciProvenanceStatement;
+//# sourceMappingURL=statement-builder.d.ts.map