@kici-dev/agent 0.1.17 → 0.1.19

package/dist/execution/dep-installer.d.ts

@@ -8,10 +8,13 @@
  * 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 classic (v1) is supported for registry
- * dependencies and version-range workspace siblings (which it links but does
- * not build, so the agent builds the in-repo closure after install). yarn
- * berry (v2+) is not yet supported.
+ * `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
@@ -53,4 +56,6 @@ export interface InstallDepsOptions {
 export declare function installDeps(kiciDir: string, opts?: InstallDepsOptions): Promise<void>;
 /** Pure: argv for `yarn install` with an isolated cache folder. */
 export declare function buildYarnInstallArgs(cacheDir: string, hasPrivateRegistry: boolean): string[];
+/** Pure: argv for a berry `yarn install`. Cache + linker live in .yarnrc.yml. */
+export declare function buildYarnBerryInstallArgs(): string[];
 //# sourceMappingURL=dep-installer.d.ts.map

package/dist/execution/dep-packer.d.ts

@@ -13,11 +13,14 @@
  *   symlinks into the root store and into sibling dirs that live outside
  *   `.kici/`, so packing `.kici/node_modules` alone would capture dangling
  *   links — the store and siblings must travel together.
- * - yarn classic: the resolved node_modules root (standalone `.kici` →
- *   `.kici/node_modules`; hoisted workspace member → the repo-root
- *   `node_modules`) plus the in-repo version-range sibling package directories
- *   `.kici` depends on (with their built output), whose symlinks would dangle
- *   otherwise.
+ * - yarn (classic + berry): the resolved node_modules root (standalone `.kici`
+ *   → `.kici/node_modules`; hoisted workspace member → the repo-root
+ *   `node_modules`) plus the in-repo sibling package directories `.kici` depends
+ *   on (with their built output), whose symlinks would dangle otherwise. Berry
+ *   runs with a forced `nodeLinker: node-modules`, so its tree has the same
+ *   node_modules shape as classic and is packed identically (the flavor only
+ *   changes how siblings are referenced — version range vs `workspace:`/`portal:`
+ *   — not the packed layout).
  *
  * Uses tar.gz (Node.js built-in zlib, no external binary) in portable mode to
  * strip user/group info for cross-machine consistency; symlinks are preserved

package/dist/execution/sandbox/ipc-protocol.d.ts

@@ -379,6 +379,21 @@ export interface JobExecutionRequest {
      * to steps as `ctx.matrix`. Absent for non-matrix jobs.
      */
     matrixValues?: Record<string, unknown>;
+    /**
+     * For a `runsOnAll` host-fanout child: the hostname this child runs on,
+     * exposed to steps as `ctx.host`. Absent for non-host jobs.
+     */
+    host?: string;
+    /**
+     * For a `runsOnAll` host-fanout child: the resolved agent facts, exposed to
+     * steps as `ctx.agent`. Absent for non-host jobs.
+     */
+    agent?: {
+        host: string;
+        labels: string[];
+        platform?: string;
+        arch?: string;
+    };
     /** Secrets to merge into step environment (highest precedence). */
     secrets?: Record<string, string>;
     /** Namespaced secrets by context name for ctx.secrets['context-name'].KEY access. */
@@ -468,6 +483,14 @@ export interface JobExecutionRequest {
         event: Record<string, unknown>;
         /** Expected job names from the original eval (for determinism validation). */
         expectedJobNames?: string[];
+        /**
+         * Frozen upstream-output snapshot for a result-aware generator. When present
+         * the re-eval rebuilds `ctx.needs` from this snapshot (never a live read),
+         * so the generator sees the same upstream data as the original eval.
+         */
+        upstreamSnapshot?: import('@kici-dev/engine').UpstreamSnapshot;
+        /** Declared upstream needs (normalized lock edges) used to shape ctx.needs. */
+        declaredNeeds?: readonly unknown[];
     };
 }
 export {};

package/dist/execution/validate-kici-deps.d.ts

@@ -17,13 +17,15 @@
  * - 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 is not yet
- *   supported.)
+ *   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.
  */
-import { PackageManager } from '@kici-dev/shared/package-manager';
+import { PackageManager, YarnFlavor } from '@kici-dev/shared/package-manager';
 /** Local-protocol specifier prefixes that resolve against the filesystem. */
 export declare enum LocalDepProtocol {
     Workspace = "workspace:",
@@ -54,7 +56,7 @@ export declare function findLocalProtocolDeps(pkg: PackageJsonShape): LocalProto
  */
 export declare function kiciHasLocalProtocolDeps(kiciDir: string): Promise<boolean>;
 /** Build the actionable error for unresolvable local-protocol dependencies. */
-export declare function formatUnresolvableDepError(offenders: readonly LocalProtocolDep[], packageManager: PackageManager): string;
+export declare function formatUnresolvableDepError(offenders: readonly LocalProtocolDep[], packageManager: PackageManager, yarnFlavor: YarnFlavor): string;
 /**
  * Throw an actionable error when `.kici/package.json` declares a local-protocol
  * dependency the detected package manager cannot resolve from the single cloned
@@ -65,6 +67,7 @@ export declare function assertResolvableDeps(args: {
     kiciDir: string;
     repoRoot: string;
     packageManager: PackageManager;
+    yarnFlavor?: YarnFlavor;
 }): Promise<void>;
 export {};
 //# sourceMappingURL=validate-kici-deps.d.ts.map

package/dist/execution/workflow-loader.d.ts

@@ -64,7 +64,11 @@ export declare function extractSteps(workflow: Workflow, jobName: string): reado
  * A sibling mismatch logs a warning; a missing target job throws a clear
  * determinism error.
  */
-export declare function extractStepsFromDynamicJob(workflow: Workflow, dynamicIndex: number, jobName: string, event: Record<string, unknown>, env: Record<string, string | undefined>, apiTransport?: (method: string, params?: Record<string, unknown>) => Promise<unknown>, expectedJobNames?: string[]): Promise<{
+export declare function extractStepsFromDynamicJob(workflow: Workflow, dynamicIndex: number, jobName: string, event: Record<string, unknown>, env: Record<string, string | undefined>, apiTransport?: (method: string, params?: Record<string, unknown>) => Promise<unknown>, expectedJobNames?: string[], 
+/** Frozen upstream snapshot for a result-aware generator (rebuilds ctx.needs). */
+upstreamSnapshot?: import('@kici-dev/engine').UpstreamSnapshot, 
+/** Declared upstream needs that shape ctx.needs. */
+declaredNeeds?: readonly unknown[]): Promise<{
     steps: readonly StepInput[];
     droppedJobs: string[];
 }>;

package/dist/execution/yarnrc-berry-config.d.ts

@@ -0,0 +1,23 @@
+/**
+ * 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.
+ */
+import type { ApplyNpmRegistryConfigArgs, ApplyNpmRegistryConfigResult } from './npm-registry-config.js';
+export declare function applyYarnrcBerryConfig(args: ApplyNpmRegistryConfigArgs): Promise<ApplyNpmRegistryConfigResult>;
+//# sourceMappingURL=yarnrc-berry-config.d.ts.map

package/dist/index.js

@@ -9,8 +9,9 @@ import { access, cp, lstat, mkdir, mkdtemp, readFile, readdir, realpath, rename,
 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.
@@ -312,8 +419,10 @@ function redactNpmOutput(input, tokens) {
 * - 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 is not yet
-*   supported.)
+*   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.
@@ -394,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);
@@ -408,8 +528,20 @@ 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) {
@@ -433,10 +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) 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 is planned.)`;
+	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.`;
 }
 /**
@@ -450,9 +583,10 @@ 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
@@ -561,10 +695,13 @@ function isAbsoluteRel(rel) {
 * 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 classic (v1) is supported for registry
-* dependencies and version-range workspace siblings (which it links but does
-* not build, so the agent builds the in-repo closure after install). yarn
-* berry (v2+) is not yet supported.
+* `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
@@ -590,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.
@@ -608,19 +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`);
+	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,
@@ -632,6 +787,10 @@ async function installDeps(kiciDir, opts = {}) {
 			hasPrivateRegistry,
 			registryConfig
 		});
+		else if (isBerry) await runYarnBerryInstall({
+			kiciDir,
+			registryConfig
+		});
 		else if (packageManager === PackageManager.Yarn) await runYarnInstall({
 			kiciDir,
 			hasPrivateRegistry,
@@ -651,7 +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);
+	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", {
@@ -780,6 +939,35 @@ async function runYarnInstall(args) {
 		}).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 {
@@ -799,7 +987,7 @@ async function assertYarnAvailable() {
 * Deep cross-sibling build chains may build out of strict topological order —
 * real `.kici` closures are shallow.
 */
-async function buildYarnWorkspaceClosure(repoRoot, kiciDir) {
+async function buildYarnWorkspaceClosure(repoRoot, kiciDir, yarnFlavor) {
 	const siblings = await collectInRepoSiblings(repoRoot, kiciDir, resolveYarnNodeModulesRoot(repoRoot, kiciDir));
 	if (siblings.length === 0) return;
 	const { nodeDir } = resolveNpm();
@@ -807,15 +995,16 @@ async function buildYarnWorkspaceClosure(repoRoot, kiciDir) {
 	for (const rel of [...siblings].reverse()) {
 		const sibDir = join(repoRoot, rel);
 		if (!await siblingHasBuildScript(sibDir)) continue;
-		process.stderr.write(`[dep-installer:trace] building yarn sibling: yarn --cwd ${sibDir} run build\n`);
+		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", [
-				"--cwd",
-				sibDir,
-				"run",
-				"build"
-			], {
-				cwd: repoRoot,
+			await execFileAsync("yarn", argv, {
+				cwd,
 				env,
 				timeout: INSTALL_TIMEOUT_MS,
 				maxBuffer: INSTALL_MAX_BUFFER

package/dist/provenance/attest.d.ts

@@ -25,6 +25,14 @@ export interface AttestResult {
     subjectDigest: string;
 }
 export declare function attestProvenance(deps: AttestDeps, input: AttestInput): Promise<AttestResult>;
-/** Pick the primary digest (`sha256` preferred) as the storage-key discriminator. */
+/**
+ * Pick the primary digest (`sha256` preferred) as the storage-key discriminator.
+ * Throws when the subject carries no digest: an empty digest set would otherwise
+ * yield an `undefined` storage-key segment (`provenance/<run>/<job>/undefined.kici.json`)
+ * and an unverifiable statement, since in-toto requires every subject to carry
+ * at least one digest. The SDK `ProvenanceSubjectInput` type allows an empty
+ * digest map (both `sha256` and `sha512` are optional), so this is the runtime
+ * boundary that upholds the engine `digestSetSchema` invariant.
+ */
 export declare function subjectDigestString(subject: ProvenanceSubject): string;
 //# sourceMappingURL=attest.d.ts.map