@kici-dev/agent 0.1.10 → 0.1.11

package/dist/workflow-runner.js

@@ -5,19 +5,21 @@ import { register } from "node:module";
 import { createInterface } from "node:readline";
 import crypto, { createHash, randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
-import fsPromises, { mkdir, mkdtemp, readFile, rm, unlink, writeFile } from "node:fs/promises";
+import fsPromises, { access, mkdir, mkdtemp, readFile, rm, unlink, writeFile } from "node:fs/promises";
 import os, { tmpdir } from "node:os";
-import path, { dirname, join } from "node:path";
+import path, { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { $ } from "zx";
 import { createLogger, deriveSharedSecret, initZx, normalizeLineEndings, sha256, sha256File, toErrorMessage } from "@kici-dev/shared";
 import { ExecutionJobStatus, ExecutionStepStatus } from "@kici-dev/engine";
 import { buildKiciApi, createStepSecrets, evaluateRules, isDynamicJobFn, resolveJobOutputs, resolveStepOutputs, setJobOutputsMap, setStepOutputsMap, setStepRefMap } from "@kici-dev/sdk";
-import "node:child_process";
+import { execFile } from "node:child_process";
 import { Readable, Transform } from "node:stream";
 import { pipeline } from "node:stream/promises";
 import { createGunzip } from "node:zlib";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { x } from "tar";
+import { promisify } from "node:util";
+import { PackageManager, detectPackageManagerFromManifests } from "@kici-dev/shared/package-manager";
 import https from "node:https";
 import http from "node:http";
 import.meta.url;
@@ -868,8 +870,8 @@ const SCRATCH_DIR_GIT_EXCLUDE_GLOB = `.kici/${SCRATCH_DIR_BASENAME_PREFIX}*`;
 * We sidestep the race entirely by extracting each attempt into a unique
 * scratch dir under `.kici/`. Failed attempts leave orphan scratch dirs whose
 * draining writes are harmless — the next attempt does not touch them. On
-* success we `fs.rename` `${scratchDir}/node_modules` into the final location
-* (atomic on the same filesystem), then best-effort clean the scratch dir.
+* success `moveScratchIntoRepo` renames the extracted entries into place
+* (atomic on the same filesystem), then best-effort cleans the scratch dir.
 *
 * Scratch dirs land inside the customer's cloned working tree, so the clone
 * phase registers `SCRATCH_DIR_GIT_EXCLUDE_GLOB` in `.git/info/exclude` to
@@ -951,13 +953,58 @@ function resolveOrchestratorUrl(url) {
 	}
 }
 /**
-* Restore dependencies from a cached tarball.
+* Move a fully-extracted scratch tree into the cloned repo. The dep tarball is
+* packed repo-root-relative, so the scratch holds repo-root entries:
+* `.kici/node_modules` for every manager, plus (for pnpm) the root
+* `node_modules/.pnpm` store and in-repo workspace sibling dirs. `.kici/` itself
+* already exists in the work tree (cloned or source-restored), so its children
+* are moved individually; every other top-level entry is moved wholesale.
+*
+* On a cache-hit execution agent the destinations do not pre-exist (source
+* restore excludes node_modules and never carries sibling dirs), so the renames
+* have nothing to race; the defensive `rm` covers re-runs.
+*/
+async function moveScratchIntoRepo(scratchDir, workDir) {
+	for (const child of await fsPromises.readdir(scratchDir)) if (child === ".kici") {
+		const kiciScratch = join(scratchDir, ".kici");
+		for (const sub of await fsPromises.readdir(kiciScratch)) await moveInto(join(kiciScratch, sub), join(workDir, ".kici", sub));
+	} else await moveInto(join(scratchDir, child), join(workDir, child));
+}
+/** Move `src` to `dest`, creating the parent and clearing any stale dest. */
+async function moveInto(src, dest) {
+	await mkdir(dirname(dest), { recursive: true });
+	await fsPromises.rm(dest, {
+		recursive: true,
+		force: true
+	});
+	await fsPromises.rename(src, dest);
+}
+/** Best-effort cleanup of a settled scratch dir; logs and continues on failure. */
+async function cleanupScratch(scratchDir) {
+	try {
+		await fsPromises.rm(scratchDir, {
+			recursive: true,
+			force: true
+		});
+	} catch (cleanupErr) {
+		logger$3.warn("Scratch dir cleanup failed (orphan left behind)", {
+			scratchDir,
+			error: cleanupErr instanceof Error ? cleanupErr.message : String(cleanupErr)
+		});
+	}
+}
+/**
+* Restore dependencies from a cached tarball into the cloned repo.
 *
-* For HTTP/HTTPS URLs: uses a streaming pipeline (response -> hash -> gunzip -> tar)
-* with a 5-minute timeout and up to 2 retries. This avoids buffering entire tarballs
-* in memory, eliminating memory spikes proportional to tarball size.
+* The tarball is packed repo-root-relative (see `dep-packer.ts`): every manager
+* carries `.kici/node_modules`; pnpm additionally carries the root
+* `node_modules/.pnpm` store and the in-repo workspace siblings `.kici` resolves.
+* Restore extracts into a scratch dir, then moves each entry into place — one
+* code path for all managers.
 *
-* For file:// URLs: uses a buffer-based approach (local, no streaming benefit).
+* For HTTP/HTTPS URLs: a streaming pipeline (response -> hash -> gunzip -> tar)
+* with a 5-minute timeout and up to 2 retries avoids buffering whole tarballs.
+* For file:// URLs: a buffer-based approach (local, no streaming benefit).
 *
 * @param workDir - Root directory of the cloned repository
 * @param depsUrl - URL to the dependency tarball (http://, https://, or file://)
@@ -974,11 +1021,14 @@ async function restoreDeps(workDir, depsUrl, depsHash) {
 			const actualHash = computeHash(data);
 			if (actualHash !== depsHash) throw new Error(`Dep tarball hash mismatch: expected ${depsHash}, got ${actualHash}`);
 		}
-		await extractTarball(data, kiciDir);
+		const scratchDir = join(kiciDir, `${SCRATCH_DIR_BASENAME_PREFIX}${process.pid}-file-${Date.now()}`);
+		await extractTarball(data, scratchDir);
+		await moveScratchIntoRepo(scratchDir, workDir);
+		await cleanupScratch(scratchDir);
 		const sizeMB = (data.length / (1024 * 1024)).toFixed(2);
 		logger$3.info("Dependencies restored from cache (file)", {
 			sizeMB,
-			targetDir: kiciDir
+			targetDir: workDir
 		});
 		return;
 	}
@@ -992,19 +1042,9 @@ async function restoreDeps(workDir, depsUrl, depsHash) {
 		try {
 			const { scratchDir, hash } = await extractIntoScratch(depsUrl, kiciDir, attempt);
 			if (depsHash && hash !== depsHash) throw new Error(`Dep tarball hash mismatch: expected ${depsHash}, got ${hash}`);
-			await fsPromises.rename(join(scratchDir, "node_modules"), join(kiciDir, "node_modules"));
-			try {
-				await fsPromises.rm(scratchDir, {
-					recursive: true,
-					force: true
-				});
-			} catch (cleanupErr) {
-				logger$3.warn("Scratch dir cleanup failed (orphan left behind)", {
-					scratchDir,
-					error: cleanupErr instanceof Error ? cleanupErr.message : String(cleanupErr)
-				});
-			}
-			logger$3.info("Dependencies restored from cache (stream)", { targetDir: kiciDir });
+			await moveScratchIntoRepo(scratchDir, workDir);
+			await cleanupScratch(scratchDir);
+			logger$3.info("Dependencies restored from cache (stream)", { targetDir: workDir });
 			return;
 		} catch (err) {
 			lastError = err instanceof Error ? err : new Error(String(err));
@@ -1163,48 +1203,190 @@ function redactNpmOutput(input, tokens) {
 	}
 	return out;
 }
+const LOCAL_PROTOCOLS = [
+	"workspace:",
+	"file:",
+	"link:",
+	"portal:"
+];
+/** The dependency maps a package manager resolves in `.kici/package.json`. */
+const DEP_FIELDS = [
+	"dependencies",
+	"devDependencies",
+	"optionalDependencies",
+	"peerDependencies"
+];
+/**
+* Scan a parsed `.kici/package.json` for dependency specifiers that use a
+* local protocol (`workspace:`/`file:`/`link:`/`portal:`). Returns one entry
+* per dependency, in field order. Returns an empty array when there are none.
+*/
+function findLocalProtocolDeps(pkg) {
+	const found = [];
+	for (const field of DEP_FIELDS) {
+		const deps = pkg[field];
+		if (!deps || typeof deps !== "object") continue;
+		for (const [name, spec] of Object.entries(deps)) {
+			if (typeof spec !== "string") continue;
+			const protocol = LOCAL_PROTOCOLS.find((proto) => spec.startsWith(proto));
+			if (protocol) found.push({
+				name,
+				spec,
+				protocol
+			});
+		}
+	}
+	return found;
+}
+/** Parse `.kici/package.json`, returning `null` when it is missing or invalid. */
+async function readKiciPackageJson(kiciDir) {
+	let raw;
+	try {
+		raw = await readFile(join(kiciDir, "package.json"), "utf-8");
+	} catch {
+		return null;
+	}
+	try {
+		return JSON.parse(raw);
+	} catch {
+		return null;
+	}
+}
+/**
+* Whether `.kici/package.json` declares any local-protocol dependency. Used to
+* decide whether the agent must build the in-repo workspace dependency closure
+* after a pnpm install (so a `workspace:` sibling's build output exists before
+* the workflow that imports it loads).
+*/
+async function kiciHasLocalProtocolDeps(kiciDir) {
+	const pkg = await readKiciPackageJson(kiciDir);
+	if (!pkg) return false;
+	return findLocalProtocolDeps(pkg).length > 0;
+}
+async function fileExists$1(target) {
+	try {
+		await access(target);
+		return true;
+	} 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);
+	return isAbsolute(rawPath) ? resolve(rawPath) : resolve(kiciDir, rawPath);
+}
+/** Whether `target` is `repoRoot` itself or a path inside it. */
+function isInsideRepo(repoRoot, target) {
+	const rel = relative(repoRoot, target);
+	return rel === "" || !rel.startsWith("..") && !isAbsolute(rel);
+}
+/**
+* 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) {
+	if (packageManager === PackageManager.Npm) return [...deps];
+	const hasWorkspaceFile = await fileExists$1(join(repoRoot, "pnpm-workspace.yaml"));
+	const unresolvable = [];
+	for (const dep of deps) {
+		if (dep.protocol === "workspace:") {
+			if (!hasWorkspaceFile) unresolvable.push(dep);
+			continue;
+		}
+		if (!isInsideRepo(repoRoot, resolveLocalPath(kiciDir, dep))) unresolvable.push(dep);
+	}
+	return unresolvable;
+}
+/** Build the actionable error for unresolvable local-protocol dependencies. */
+function formatUnresolvableDepError(offenders, packageManager) {
+	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.`;
+	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.`;
+}
+/**
+* Throw an actionable error when `.kici/package.json` declares a local-protocol
+* dependency the detected package manager cannot resolve from the single cloned
+* repository. A missing or unparseable package.json is left for the install to
+* report.
+*/
+async function assertResolvableDeps(args) {
+	const pkg = await readKiciPackageJson(args.kiciDir);
+	if (!pkg) return;
+	const localDeps = findLocalProtocolDeps(pkg);
+	if (localDeps.length === 0) return;
+	const offenders = await findUnresolvableDeps(localDeps, args.packageManager, args.kiciDir, args.repoRoot);
+	if (offenders.length === 0) return;
+	throw new Error(formatUnresolvableDepError(offenders, args.packageManager));
+}
 //#endregion
 //#region src/execution/dep-installer.ts
 /**
 * Inline dependency installation for graceful degradation.
 *
-* When dep cache is unavailable or download fails, the agent falls back
-* to running npm install directly.
+* When the dep cache is unavailable or a download fails, the agent installs
+* `.kici/` dependencies directly with the repository's package manager.
 *
-* Only npm is supported — it ships with every Node.js installation.
-* .kici/package.json is required — its presence signals deps should be installed.
+* The package manager is detected from the cloned repo (npm / pnpm); 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.
 *
-* Security: npm runs with an isolated per-invocation cache directory to prevent
-* cache poisoning across build jobs. A malicious package.json in one repo cannot
-* taint the cache used by subsequent builds. The same pressure rules out letting
-* lifecycle scripts see synthesized auth env vars — npm runs with
-* `--ignore-scripts` whenever a private registry is configured.
+* Security: the install runs with an isolated per-invocation cache/store
+* directory to prevent cache poisoning across build jobs — a malicious
+* package.json in one repo cannot taint the cache used by subsequent builds.
+* The same pressure rules out letting lifecycle scripts see synthesized auth
+* env vars — the install runs with `--ignore-scripts` whenever a private
+* registry is configured.
 */
 const logger$2 = createLogger({ prefix: "dep-installer" });
+const execFileAsync = promisify(execFile);
+/** Install subprocess timeout (10 min) and stdout/stderr buffer (128 MiB). */
+const INSTALL_TIMEOUT_MS = 6e5;
+const INSTALL_MAX_BUFFER = 128 * 1024 * 1024;
 /**
-* Install dependencies inline using npm.
-*
-* Falls back to this when the dep cache is unavailable or download fails.
+* Detect the package manager for the cloned repo from its committed manifests.
+* A pnpm workspace's `packageManager` field + `pnpm-lock.yaml` live at the repo
+* root, so check there first; fall back to `.kici/` for a standalone
+* (non-workspace) project that carries its own lockfile; default to npm when
+* neither carries a signal. Uses the manifests-only detector so the agent's own
+* launch env (`npm_config_user_agent`) never leaks into the decision.
+*/
+async function detectKiciPackageManager(repoRoot, kiciDir) {
+	return await detectPackageManagerFromManifests(repoRoot) ?? await detectPackageManagerFromManifests(kiciDir) ?? PackageManager.Npm;
+}
+/**
+* Install `.kici/` dependencies inline with the repo's package manager.
 *
-* npm runs with an isolated cache directory (created in os.tmpdir()) to prevent
-* cache poisoning between build jobs. The cache is removed after installation.
+* Falls back to this when the dep cache is unavailable or a download fails.
+* The install runs with an isolated cache/store directory (created in
+* `os.tmpdir()`) to prevent cache poisoning between build jobs; the directory
+* is removed after installation.
 *
-* If `opts.npmRegistries` / `opts.installEnvSecrets` is provided, the helper
-* synthesizes a job-scoped `.kici/.npmrc` overlay for the install, restores
-* the original file in `finally`, and runs npm with `--ignore-scripts` so
-* lifecycle scripts in committed `package.json` cannot exfiltrate the
-* synthesized token env vars.
+* If `opts.npmRegistries` / `opts.installEnvSecrets` is provided, a job-scoped
+* `.kici/.npmrc` overlay is synthesized for the install, restored in `finally`,
+* and the install runs with `--ignore-scripts` so lifecycle scripts in a
+* committed `package.json` cannot exfiltrate the synthesized token env vars.
 *
-* @param kiciDir - Path to the .kici/ directory containing package.json
-* @param opts    - Optional registry / installEnv configuration. When absent,
-*                  behavior is identical to the pre-private-registry version.
+* @param kiciDir - Path to the `.kici/` directory containing package.json.
+* @param opts    - Optional registry / installEnv / repoRoot configuration.
 */
 async function installDeps(kiciDir, opts = {}) {
+	const repoRoot = opts.repoRoot ?? dirname(kiciDir);
+	const packageManager = await detectKiciPackageManager(repoRoot, kiciDir);
 	logger$2.info("Installing deps inline", {
-		packageManager: "npm",
+		packageManager,
 		dir: kiciDir
 	});
-	process.stderr.write(`[dep-installer:trace] starting install: pm=npm, cwd=${kiciDir}\n`);
+	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.");
+	await assertResolvableDeps({
+		kiciDir,
+		repoRoot,
+		packageManager
+	});
 	const startTime = Date.now();
 	const hasPrivateRegistry = (opts.npmRegistries?.length ?? 0) > 0 || (opts.installEnvSecrets ? Object.keys(opts.installEnvSecrets).length > 0 : false);
 	const registryConfig = await applyNpmRegistryConfig({
@@ -1214,71 +1396,149 @@ async function installDeps(kiciDir, opts = {}) {
 		jobIdShort: opts.jobIdShort ?? "00000000"
 	});
 	try {
-		const { npmCliPath, nodeExe, nodeDir } = resolveNpm();
-		const npmCmd = "install";
-		const cacheDir = await mkdtemp(join(tmpdir(), "kici-npm-cache-"));
-		const { NODE_ENV: _, ...restEnv } = process.env;
-		const envWithNode = {
-			...restEnv,
-			...registryConfig.extraEnv,
-			PATH: `${nodeDir}${process.platform === "win32" ? ";" : ":"}${process.env.PATH ?? ""}`
-		};
-		const { execFile } = await import("node:child_process");
-		const { promisify } = await import("node:util");
-		const execFileAsync = promisify(execFile);
-		const buildArgs = (...prefix) => {
-			const args = [
-				...prefix,
-				npmCmd,
-				"--cache",
-				cacheDir,
-				"--no-audit",
-				"--no-fund"
-			];
-			if (hasPrivateRegistry) args.push("--ignore-scripts");
-			return args;
-		};
-		try {
-			if (npmCliPath) {
-				process.stderr.write(`[dep-installer:trace] running: ${nodeExe} ${npmCliPath} ${buildArgs().join(" ")}\n`);
-				await execFileAsync(nodeExe, buildArgs(npmCliPath), {
-					cwd: kiciDir,
-					env: envWithNode,
-					timeout: 6e5,
-					maxBuffer: 128 * 1024 * 1024
-				});
-			} else {
-				process.stderr.write(`[dep-installer:trace] running: npm ${buildArgs().join(" ")}\n`);
-				await execFileAsync("npm", buildArgs(), {
-					cwd: kiciDir,
-					env: envWithNode,
-					timeout: 6e5,
-					maxBuffer: 128 * 1024 * 1024
-				});
-			}
-		} finally {
-			await rm(cacheDir, {
-				recursive: true,
-				force: true
-			}).catch(() => {});
-		}
+		if (packageManager === PackageManager.Pnpm) await runPnpmInstall({
+			kiciDir,
+			hasPrivateRegistry,
+			registryConfig
+		});
+		else await runNpmInstall({
+			kiciDir,
+			hasPrivateRegistry,
+			registryConfig
+		});
 	} catch (e) {
-		const msg = toErrorMessage(e);
 		const tokens = registryConfig.tokensForRedaction;
-		process.stderr.write(`[dep-installer:trace] INSTALL FAILED: ${redactNpmOutput(msg, tokens)}\n`);
-		if (e && typeof e === "object" && "stdout" in e) process.stderr.write(`[dep-installer:trace] stdout: ${redactNpmOutput(String(e.stdout), tokens).slice(0, 500)}\n`);
-		if (e && typeof e === "object" && "stderr" in e) process.stderr.write(`[dep-installer:trace] stderr: ${redactNpmOutput(String(e.stderr), tokens).slice(0, 500)}\n`);
+		process.stderr.write(`[dep-installer:trace] INSTALL FAILED: ${redactNpmOutput(toErrorMessage(e), tokens)}\n`);
+		logSubprocessStreams(e, tokens);
 		throw e;
 	} finally {
 		await registryConfig.cleanup();
 	}
+	if (packageManager === PackageManager.Pnpm && await kiciHasLocalProtocolDeps(kiciDir)) await buildWorkspaceClosure(repoRoot);
 	const durationMs = Date.now() - startTime;
 	process.stderr.write(`[dep-installer:trace] install complete: ${durationMs}ms\n`);
 	logger$2.info("Deps installed inline", {
-		packageManager: "npm",
+		packageManager,
 		durationMs
 	});
 }
+/** Build the Node binary directory onto PATH so spawned tools find `node`. */
+function envWithNodeOnPath(extraEnv, nodeDir) {
+	const { NODE_ENV: _NODE_ENV, ...restEnv } = process.env;
+	return {
+		...restEnv,
+		...extraEnv,
+		PATH: `${nodeDir}${process.platform === "win32" ? ";" : ":"}${process.env.PATH ?? ""}`
+	};
+}
+/** Run `npm install` in `.kici/` with an isolated cache directory. */
+async function runNpmInstall(args) {
+	const { npmCliPath, nodeExe, nodeDir } = resolveNpm();
+	const cacheDir = await mkdtemp(join(tmpdir(), "kici-npm-cache-"));
+	const env = envWithNodeOnPath(args.registryConfig.extraEnv, nodeDir);
+	const buildArgs = (...prefix) => {
+		const a = [
+			...prefix,
+			"install",
+			"--cache",
+			cacheDir,
+			"--no-audit",
+			"--no-fund"
+		];
+		if (args.hasPrivateRegistry) a.push("--ignore-scripts");
+		return a;
+	};
+	try {
+		const bin = npmCliPath ? nodeExe : "npm";
+		const argv = npmCliPath ? buildArgs(npmCliPath) : buildArgs();
+		process.stderr.write(`[dep-installer:trace] running: ${bin} ${argv.join(" ")}\n`);
+		await execFileAsync(bin, argv, {
+			cwd: args.kiciDir,
+			env,
+			timeout: INSTALL_TIMEOUT_MS,
+			maxBuffer: INSTALL_MAX_BUFFER
+		});
+	} finally {
+		await rm(cacheDir, {
+			recursive: true,
+			force: true
+		}).catch(() => {});
+	}
+}
+/**
+* Run `pnpm install` from `.kici/`. pnpm walks up to the workspace root, so a
+* `workspace:` sibling in the same cloned repo resolves. Uses an isolated store
+* (`--config.store-dir`) for cross-job isolation, `package-import-method=copy`
+* so the on-disk store is a self-contained tree of real files (a later dep
+* cache tars it), and disables interactive purge prompts + the side-effects
+* cache for deterministic, non-interactive runs.
+*/
+async function runPnpmInstall(args) {
+	await assertPnpmAvailable();
+	const { nodeDir } = resolveNpm();
+	const storeDir = await mkdtemp(join(tmpdir(), "kici-pnpm-store-"));
+	const env = envWithNodeOnPath(args.registryConfig.extraEnv, nodeDir);
+	const argv = [
+		"install",
+		`--config.store-dir=${storeDir}`,
+		"--config.package-import-method=copy",
+		"--config.confirm-modules-purge=false",
+		"--config.side-effects-cache=false"
+	];
+	if (args.hasPrivateRegistry) argv.push("--ignore-scripts");
+	try {
+		process.stderr.write(`[dep-installer:trace] running: pnpm ${argv.join(" ")}\n`);
+		await execFileAsync("pnpm", argv, {
+			cwd: args.kiciDir,
+			env,
+			timeout: INSTALL_TIMEOUT_MS,
+			maxBuffer: INSTALL_MAX_BUFFER
+		});
+	} finally {
+		await rm(storeDir, {
+			recursive: true,
+			force: true
+		}).catch(() => {});
+	}
+}
+/**
+* Build the in-repo dependency closure of the `.kici/` package so a
+* `workspace:` sibling's build output exists before the workflow that imports
+* it loads. `--filter "{.kici}^..."` selects only `.kici`'s dependencies (not
+* `.kici` itself); `--if-present` skips siblings without a build script. Runs
+* with a clean env (no synthesized registry tokens).
+*/
+async function buildWorkspaceClosure(repoRoot) {
+	const { nodeDir } = resolveNpm();
+	const env = envWithNodeOnPath({}, nodeDir);
+	const argv = [
+		"--filter",
+		"{.kici}^...",
+		"run",
+		"build",
+		"--if-present"
+	];
+	process.stderr.write(`[dep-installer:trace] building workspace closure: pnpm ${argv.join(" ")}\n`);
+	await execFileAsync("pnpm", argv, {
+		cwd: repoRoot,
+		env,
+		timeout: INSTALL_TIMEOUT_MS,
+		maxBuffer: INSTALL_MAX_BUFFER
+	});
+}
+/** Throw an actionable error when the repo needs pnpm but it is not installed. */
+async function assertPnpmAvailable() {
+	try {
+		await execFileAsync("pnpm", ["--version"], { timeout: 3e4 });
+	} 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)})`);
+	}
+}
+/** Trace the redacted stdout/stderr of a failed install subprocess. */
+function logSubprocessStreams(e, tokens) {
+	if (e && typeof e === "object" && "stdout" in e) process.stderr.write(`[dep-installer:trace] stdout: ${redactNpmOutput(String(e.stdout), tokens).slice(0, 500)}\n`);
+	if (e && typeof e === "object" && "stderr" in e) process.stderr.write(`[dep-installer:trace] stderr: ${redactNpmOutput(String(e.stderr), tokens).slice(0, 500)}\n`);
+}
 //#endregion
 //#region src/execution/workflow-loader.ts
 /**
@@ -1288,7 +1548,7 @@ async function installDeps(kiciDir, opts = {}) {
 * 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.10";
+const AGENT_SDK_VERSION = "0.1.11";
 const AGENT_SDK_BUNDLE_HASH = "675aafe4de03e677785ef2794d8f34951b14e2bd1e6f0ea825953d6c2abfe128";
 /**
 * Register the shared oxc-transform ESM loader hook so subsequent dynamic

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kici-dev/agent",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "description": "Customer-deployable agent for the KiCI CI/CD stack. Connects to an orchestrator, clones the workflow repo, executes steps, and streams logs back.",
   "keywords": [
     "kici",
@@ -57,9 +57,9 @@
     "ws": "^8.20.0",
     "zod": "^4.3.6",
     "zx": "^8.8.5",
-    "@kici-dev/engine": "0.1.10",
-    "@kici-dev/sdk": "0.1.10",
-    "@kici-dev/shared": "0.1.10"
+    "@kici-dev/sdk": "0.1.11",
+    "@kici-dev/engine": "0.1.11",
+    "@kici-dev/shared": "0.1.11"
   },
   "kici": {
     "metrics": {