@loucompanion/forge-bridge 0.1.3-dev.fbe15023cdfe → 0.1.4-dev.1ff37038366e

package/dist/worktree/dependency-warmer.js

@@ -1,10 +1,14 @@
+import { createHash, randomUUID } from "node:crypto";
 import { existsSync, realpathSync } from "node:fs";
 import fs from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
+import { assertHostDatabaseCapabilityBoundary } from "../runtime/host-database-capability-boundary.js";
+import { RepositoryCoordinatorLock } from "../sandbox/repository-lock.js";
 import { NodeProcessRunner } from "../shared/process/process.js";
 import { buildWindowsCmdLaunch } from "../shared/process/windows-launch.js";
 import { isSubPath } from "../shared/path/path.js";
+import { defaultWorktreeCoordinatorStateRoot } from "./worktree-paths.js";
 const SKIP_DIR_NAMES = new Set([
     ".git",
     "node_modules",
@@ -24,6 +28,11 @@ const NATIVE_MODULE_HINTS = [
     "@swc/core"
 ];
 const MAX_COMMAND_FAILURE_OUTPUT_LENGTH = 8_000;
+const DEPENDENCY_RECEIPT_SCHEMA_VERSION = 1;
+const DEPENDENCY_PREPARATION_CONTRACT = "managed-worktree-isolated-v1";
+const WINDOWS_COMMAND_ENVIRONMENT_PATH_LIMIT = 8_191;
+const WINDOWS_PACKAGE_MANAGER_INTERNAL_PATH_RESERVE = 512;
+const dependencyPreparationCoordinator = new RepositoryCoordinatorLock(defaultWorktreeCoordinatorStateRoot());
 export async function detectWarmPaths(repoRoot, warmPathOverrides = []) {
     const entries = new Map();
     await collectDetectedPaths(repoRoot, repoRoot, entries, 0);
@@ -51,6 +60,7 @@ export async function warmWorktreeDependencies(request, executor = defaultComman
     const linked = [];
     const skipped = [];
     const fallbacks = [];
+    const receipts = [];
     const restoredDotNetRoots = new Set();
     const installedNodeRoots = new Set();
     for (const entry of warmPaths) {
@@ -67,8 +77,10 @@ export async function warmWorktreeDependencies(request, executor = defaultComman
                 continue;
             }
             installedNodeRoots.add(packageKey);
-            const install = await runInstallFallback({ ...entry, packageRoot: installPackageRoot }, worktreePath, "Managed worktrees require isolated Node dependencies.", executor);
-            fallbacks.push(install);
+            const preparation = await ensureInstallFallback({ ...entry, packageRoot: installPackageRoot }, worktreePath, "Managed worktrees require isolated Node dependencies.", executor, request.preparationPolicy);
+            receipts.push(preparation.receipt);
+            if (preparation.install)
+                fallbacks.push(preparation.install);
             continue;
         }
         if (entry.ecosystem === "dotnet") {
@@ -80,15 +92,19 @@ export async function warmWorktreeDependencies(request, executor = defaultComman
                 continue;
             }
             restoredDotNetRoots.add(packageKey);
-            const install = await runInstallFallback(entry, worktreePath, "Managed worktrees require isolated .NET build outputs.", executor);
-            fallbacks.push(install);
+            const preparation = await ensureInstallFallback(entry, worktreePath, "Managed worktrees require isolated .NET build outputs.", executor, request.preparationPolicy);
+            receipts.push(preparation.receipt);
+            if (preparation.install)
+                fallbacks.push(preparation.install);
             continue;
         }
         const sourceExists = await directoryExists(sourcePath);
         const fallbackReason = await resolveFallbackReason(entry, baseCheckoutPath, worktreePath, sourceExists);
         if (fallbackReason) {
-            const install = await runInstallFallback(entry, worktreePath, fallbackReason, executor);
-            fallbacks.push(install);
+            const preparation = await ensureInstallFallback(entry, worktreePath, fallbackReason, executor, request.preparationPolicy);
+            receipts.push(preparation.receipt);
+            if (preparation.install)
+                fallbacks.push(preparation.install);
             continue;
         }
         if (!sourceExists) {
@@ -98,7 +114,7 @@ export async function warmWorktreeDependencies(request, executor = defaultComman
         await createDirectoryLink(sourcePath, targetPath, allowedRoot);
         linked.push(entry.relativePath);
     }
-    return { linked, skipped, fallbacks };
+    return { linked, skipped, fallbacks, receipts };
 }
 async function removeLegacyDirectoryLink(targetPath, allowedRoot) {
     const resolvedTarget = path.resolve(targetPath);
@@ -225,28 +241,249 @@ export async function lockfilesDiffer(baseCheckoutPath, worktreePath, packageRoo
     }
     return false;
 }
+async function ensureInstallFallback(entry, worktreePath, reason, executor, policy) {
+    const startedAt = performance.now();
+    const cwd = path.resolve(worktreePath, entry.packageRoot === "." ? "" : entry.packageRoot);
+    assertWithinRoot(path.resolve(worktreePath), cwd, "Dependency package root");
+    const command = await installFallbackCommand(entry, cwd);
+    const outputMarker = dependencyOutputMarker(entry.ecosystem, cwd);
+    const receiptPath = path.join(outputMarker, ".forge-dependency-preparation.json");
+    const fingerprint = await dependencyPreparationFingerprint(entry, worktreePath, cwd, command, policy);
+    return await dependencyPreparationCoordinator.withLock(receiptPath, async () => {
+        const existing = await readDependencyPreparationReceipt(receiptPath);
+        if (existing?.fingerprint === fingerprint
+            && existing.ecosystem === entry.ecosystem
+            && existing.packageRoot === entry.packageRoot
+            && existing.command === command
+            && await directoryExists(outputMarker)) {
+            await markNpmCiRestored(outputMarker, command);
+            return {
+                install: null,
+                receipt: {
+                    ecosystem: entry.ecosystem,
+                    packageRoot: entry.packageRoot,
+                    command,
+                    cacheHit: true,
+                    fingerprint,
+                    receiptPath,
+                    durationMs: elapsedMilliseconds(startedAt),
+                },
+            };
+        }
+        const install = await runInstallFallback(entry, worktreePath, reason, executor);
+        // npm is allowed to omit node_modules when the package graph is empty. Keep
+        // an isolated, ignored output directory so the durable receipt still has a
+        // concrete marker whose removal invalidates reuse.
+        if (entry.ecosystem === "node") {
+            await fs.mkdir(outputMarker, { recursive: true });
+        }
+        if (!(await directoryExists(outputMarker))) {
+            throw new Error(`dependency_preparation_output_missing: ${install.command} succeeded without creating ${outputMarker}.`);
+        }
+        const receipt = {
+            schemaVersion: DEPENDENCY_RECEIPT_SCHEMA_VERSION,
+            fingerprint,
+            ecosystem: entry.ecosystem,
+            packageRoot: entry.packageRoot,
+            command,
+            outputMarker: path.relative(cwd, outputMarker).replaceAll("\\", "/"),
+            completedAt: new Date().toISOString(),
+        };
+        await persistDependencyPreparationReceipt(receiptPath, receipt);
+        await markNpmCiRestored(outputMarker, command);
+        return {
+            install,
+            receipt: {
+                ecosystem: entry.ecosystem,
+                packageRoot: entry.packageRoot,
+                command,
+                cacheHit: false,
+                fingerprint,
+                receiptPath,
+                durationMs: elapsedMilliseconds(startedAt),
+            },
+        };
+    });
+}
+async function markNpmCiRestored(outputMarker, command) {
+    if (command !== "npm ci")
+        return;
+    // Forge.Api's RestoreForgeBridge target uses this stamp as its incremental
+    // output. Worktree preparation has already installed and verified the same
+    // package graph, so an immediate dotnet build must not repeat npm ci.
+    await fs.writeFile(path.join(outputMarker, ".forge-restore.stamp"), "", { mode: 0o600 });
+}
+function elapsedMilliseconds(startedAt) {
+    return Math.max(0, Math.round((performance.now() - startedAt) * 1000) / 1000);
+}
+async function installFallbackCommand(entry, cwd) {
+    if (entry.ecosystem === "node") {
+        if (await pathExists(path.join(cwd, "pnpm-lock.yaml")))
+            return "pnpm install --frozen-lockfile";
+        return await pathExists(path.join(cwd, "package-lock.json")) ? "npm ci" : "npm install";
+    }
+    if (entry.ecosystem === "python") {
+        return await pathExists(path.join(cwd, "requirements.txt"))
+            ? "python -m venv .venv && pip install -r requirements.txt"
+            : "python -m venv .venv";
+    }
+    return "dotnet restore";
+}
+function dependencyOutputMarker(ecosystem, cwd) {
+    if (ecosystem === "node")
+        return path.join(cwd, "node_modules");
+    if (ecosystem === "python")
+        return path.join(cwd, ".venv");
+    return path.join(cwd, "obj");
+}
+async function dependencyPreparationFingerprint(entry, worktreePath, cwd, command, policy) {
+    const inputFiles = await dependencyInputFiles(entry.ecosystem, worktreePath, cwd);
+    const inputDigests = await Promise.all(inputFiles.map(async (file) => ({
+        path: path.relative(worktreePath, file).replaceAll("\\", "/"),
+        digest: await sha256File(file),
+    })));
+    const toolchainVersion = await dependencyToolchainVersion(entry.ecosystem, cwd, policy);
+    const trustDomain = policy?.trustDomain ?? process.env.FORGE_TRUST_DOMAIN_ID ?? "default";
+    const invalidationEpoch = policy?.invalidationEpoch ?? process.env.FORGE_DEPENDENCY_CACHE_EPOCH ?? "default";
+    const contract = {
+        schemaVersion: DEPENDENCY_RECEIPT_SCHEMA_VERSION,
+        preparationContract: DEPENDENCY_PREPARATION_CONTRACT,
+        ecosystem: entry.ecosystem,
+        packageRoot: entry.packageRoot.replaceAll("\\", "/"),
+        command,
+        inputDigests,
+        toolchainVersion,
+        nodeRuntime: process.version,
+        platform: process.platform,
+        architecture: process.arch,
+        osRelease: os.release(),
+        isolation: policy?.isolation ?? process.env.FORGE_RUNTIME_MODE ?? "managed_host_process",
+        trustDomainFingerprint: sha256Text(trustDomain),
+        invalidationEpochFingerprint: sha256Text(invalidationEpoch),
+    };
+    return `sha256:${sha256Text(JSON.stringify(contract))}`;
+}
+async function dependencyInputFiles(ecosystem, worktreePath, cwd) {
+    const result = new Set();
+    const directNames = ecosystem === "node"
+        ? ["package.json", "package-lock.json", "npm-shrinkwrap.json", "pnpm-lock.yaml", "pnpm-workspace.yaml", "yarn.lock", ".npmrc", ".yarnrc", ".yarnrc.yml", ".nvmrc", ".node-version"]
+        : ecosystem === "python"
+            ? ["pyproject.toml", "requirements.txt", "requirements-dev.txt", "poetry.lock", "Pipfile", "Pipfile.lock", "uv.lock", "pip.conf", "pyvenv.cfg"]
+            : ["global.json", "NuGet.Config", "nuget.config", "Directory.Build.props", "Directory.Build.targets", "Directory.Packages.props", "packages.lock.json"];
+    let current = cwd;
+    const root = path.resolve(worktreePath);
+    while (isSubPath(root, current)) {
+        for (const name of directNames) {
+            const candidate = path.join(current, name);
+            if (await pathExists(candidate))
+                result.add(candidate);
+        }
+        if (ecosystem === "dotnet" && current === cwd) {
+            const entries = await fs.readdir(current, { withFileTypes: true }).catch(() => []);
+            for (const item of entries) {
+                if (item.isFile() && (/\.(?:csproj|fsproj|vbproj|sln|slnx)$/iu.test(item.name))) {
+                    result.add(path.join(current, item.name));
+                }
+            }
+        }
+        if (current === root)
+            break;
+        current = path.dirname(current);
+    }
+    return [...result].sort((left, right) => left.localeCompare(right));
+}
+async function dependencyToolchainVersion(ecosystem, cwd, policy) {
+    if (ecosystem === "node") {
+        const manager = await pathExists(path.join(cwd, "pnpm-lock.yaml")) ? "pnpm" : "npm";
+        const override = policy?.toolchainVersions?.[manager];
+        if (override)
+            return `${manager}@${override};node@${process.version}`;
+        const launch = manager === "pnpm" ? resolvePnpmLaunch(["--version"]) : resolveNpmLaunch(["--version"]);
+        return `${manager}@${await readToolVersion(cwd, launch.command, launch.args)};node@${process.version}`;
+    }
+    const override = policy?.toolchainVersions?.[ecosystem];
+    if (override)
+        return `${ecosystem}@${override}`;
+    const launch = ecosystem === "dotnet"
+        ? { command: "dotnet", args: ["--version"] }
+        : { command: "python", args: ["--version"] };
+    return `${ecosystem}@${await readToolVersion(cwd, launch.command, launch.args)}`;
+}
+async function readToolVersion(cwd, command, args) {
+    return await defaultProcessRunner.run({ command, cwd, args })
+        .then(result => result.exitCode === 0
+        ? (result.stdout.trim() || result.stderr.trim() || "unknown").slice(0, 256)
+        : `unavailable:${result.exitCode}`)
+        .catch(() => "unavailable");
+}
+async function readDependencyPreparationReceipt(receiptPath) {
+    try {
+        const parsed = JSON.parse(await fs.readFile(receiptPath, "utf8"));
+        return parsed.schemaVersion === DEPENDENCY_RECEIPT_SCHEMA_VERSION
+            && typeof parsed.fingerprint === "string"
+            && typeof parsed.ecosystem === "string"
+            && typeof parsed.packageRoot === "string"
+            && typeof parsed.command === "string"
+            && typeof parsed.outputMarker === "string"
+            ? parsed
+            : null;
+    }
+    catch (error) {
+        if (error.code === "ENOENT" || error instanceof SyntaxError)
+            return null;
+        throw error;
+    }
+}
+async function persistDependencyPreparationReceipt(receiptPath, receipt) {
+    await fs.mkdir(path.dirname(receiptPath), { recursive: true });
+    const temporaryPath = `${receiptPath}.${randomUUID()}.tmp`;
+    await fs.writeFile(temporaryPath, `${JSON.stringify(receipt, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+    try {
+        await fs.rename(temporaryPath, receiptPath);
+    }
+    finally {
+        await fs.rm(temporaryPath, { force: true }).catch(() => undefined);
+    }
+}
+function sha256Text(value) {
+    return createHash("sha256").update(value).digest("hex");
+}
 async function runInstallFallback(entry, worktreePath, reason, executor) {
+    assertHostDatabaseCapabilityBoundary();
     const cwd = path.join(worktreePath, entry.packageRoot === "." ? "" : entry.packageRoot);
     if (entry.ecosystem === "node") {
         const pnpmLockPath = path.join(cwd, "pnpm-lock.yaml");
         if (await pathExists(pnpmLockPath)) {
             const args = ["install", "--frozen-lockfile"];
             const launch = resolvePnpmLaunch(args);
-            await executor.run(cwd, launch.command, launch.args, { env: unattendedPackageManagerEnvironment() });
+            await executor.run(cwd, launch.command, launch.args, {
+                env: unattendedPackageManagerEnvironment(process.env, {
+                    packageRoot: cwd,
+                    requiredPathDirectories: launch.requiredPathDirectories,
+                }),
+                windowsVerbatimArguments: launch.windowsVerbatimArguments,
+            });
             return { ecosystem: entry.ecosystem, packageRoot: entry.packageRoot, reason, command: `pnpm ${args.join(" ")}` };
         }
         const lockPath = path.join(cwd, "package-lock.json");
         const args = (await pathExists(lockPath)) ? ["ci"] : ["install"];
         const launch = resolveNpmLaunch(args);
-        await executor.run(cwd, launch.command, launch.args, { env: unattendedPackageManagerEnvironment() });
+        await executor.run(cwd, launch.command, launch.args, {
+            env: unattendedPackageManagerEnvironment(process.env, {
+                packageRoot: cwd,
+                requiredPathDirectories: launch.requiredPathDirectories,
+            }),
+            windowsVerbatimArguments: launch.windowsVerbatimArguments,
+        });
         return { ecosystem: entry.ecosystem, packageRoot: entry.packageRoot, reason, command: `npm ${args.join(" ")}` };
     }
     if (entry.ecosystem === "python") {
-        await executor.run(cwd, "python", ["-m", "venv", ".venv"]);
+        const environment = unattendedDependencyEnvironment();
+        await executor.run(cwd, "python", ["-m", "venv", ".venv"], { env: environment });
         const requirements = path.join(cwd, "requirements.txt");
         if (await pathExists(requirements)) {
             const pip = process.platform === "win32" ? path.join(".venv", "Scripts", "pip") : path.join(".venv", "bin", "pip");
-            await executor.run(cwd, pip, ["install", "-r", "requirements.txt"]);
+            await executor.run(cwd, pip, ["install", "-r", "requirements.txt"], { env: environment });
             return {
                 ecosystem: entry.ecosystem,
                 packageRoot: entry.packageRoot,
@@ -261,7 +498,7 @@ async function runInstallFallback(entry, worktreePath, reason, executor) {
             command: "python -m venv .venv"
         };
     }
-    await executor.run(cwd, "dotnet", ["restore"]);
+    await executor.run(cwd, "dotnet", ["restore"], { env: unattendedDependencyEnvironment() });
     return {
         ecosystem: entry.ecosystem,
         packageRoot: entry.packageRoot,
@@ -360,14 +597,37 @@ async function sha256File(filePath) {
 export function resolveNpmLaunch(args, options = {}) {
     const env = options.env ?? process.env;
     const execPath = options.execPath ?? process.execPath;
+    const platform = options.platform ?? process.platform;
+    const pathExists = options.pathExists ?? existsSync;
     const npmExecPath = env.npm_execpath;
-    if (npmExecPath) {
+    const npmExecPathIsAbsolute = platform === "win32"
+        ? path.win32.isAbsolute(npmExecPath ?? "")
+        : path.posix.isAbsolute(npmExecPath ?? "");
+    const npmExecPathBaseName = platform === "win32"
+        ? path.win32.basename(npmExecPath ?? "")
+        : path.posix.basename(npmExecPath ?? "");
+    if (npmExecPath
+        && npmExecPathIsAbsolute
+        && npmExecPathBaseName.toLowerCase() === "npm-cli.js"
+        && pathExists(npmExecPath)) {
         return { command: execPath, args: [npmExecPath, ...args] };
     }
-    const platform = options.platform ?? process.platform;
     if (platform === "win32") {
-        const comSpec = options.env ? env.ComSpec ?? "cmd.exe" : env.ComSpec;
-        return buildWindowsCmdLaunch("npm.cmd", args, comSpec);
+        const command = resolveWindowsPackageManagerCommand("npm.cmd", env, pathExists, [path.win32.dirname(execPath)]);
+        if (!command) {
+            throw new Error("Windows npm launcher could not be resolved before PATH compaction.");
+        }
+        const cli = resolveWindowsPackageManagerCli("npm", command, execPath, pathExists);
+        if (cli)
+            return { command: execPath, args: [cli, ...args] };
+        const comSpec = options.env
+            ? windowsEnvironmentValue(env, "ComSpec") ?? "cmd.exe"
+            : windowsEnvironmentValue(env, "ComSpec");
+        return {
+            ...buildWindowsCmdLaunch(command, args, comSpec),
+            requiredPathDirectories: [path.win32.dirname(command)],
+            windowsVerbatimArguments: true,
+        };
     }
     for (const candidate of options.candidates ?? defaultNpmCliCandidates(execPath, options.homeDir ?? os.homedir())) {
         const resolvedCandidate = tryResolveNpmCandidate(candidate);
@@ -377,9 +637,26 @@ export function resolveNpmLaunch(args, options = {}) {
     }
     return { command: "npm", args };
 }
-export function resolvePnpmLaunch(args) {
-    if (process.platform === "win32") {
-        return buildWindowsCmdLaunch("pnpm.cmd", args, process.env.ComSpec);
+export function resolvePnpmLaunch(args, options = {}) {
+    const platform = options.platform ?? process.platform;
+    if (platform === "win32") {
+        const env = options.env ?? process.env;
+        const execPath = options.execPath ?? process.execPath;
+        const command = resolveWindowsPackageManagerCommand("pnpm.cmd", env, options.pathExists ?? existsSync, [path.win32.dirname(execPath)]);
+        if (!command) {
+            throw new Error("Windows pnpm launcher could not be resolved before PATH compaction.");
+        }
+        const cli = resolveWindowsPackageManagerCli("pnpm", command, execPath, options.pathExists ?? existsSync);
+        if (cli)
+            return { command: execPath, args: [cli, ...args] };
+        const comSpec = options.env
+            ? windowsEnvironmentValue(env, "ComSpec") ?? "cmd.exe"
+            : windowsEnvironmentValue(env, "ComSpec");
+        return {
+            ...buildWindowsCmdLaunch(command, args, comSpec),
+            requiredPathDirectories: [path.win32.dirname(command)],
+            windowsVerbatimArguments: true,
+        };
     }
     return { command: "pnpm", args };
 }
@@ -394,8 +671,200 @@ export function formatCommandFailureOutput(stdout, stderr) {
     }
     return `[last ${MAX_COMMAND_FAILURE_OUTPUT_LENGTH} characters]\n${output.slice(-MAX_COMMAND_FAILURE_OUTPUT_LENGTH)}`;
 }
-export function unattendedPackageManagerEnvironment(env = process.env) {
-    return { ...env, CI: "true" };
+export function unattendedPackageManagerEnvironment(env = process.env, options = {}) {
+    const result = { ...unattendedDependencyEnvironment(env), CI: "true" };
+    if ((options.platform ?? process.platform) !== "win32")
+        return result;
+    const pathValue = windowsEnvironmentValues(env, "Path").join(";");
+    for (const key of Object.keys(result)) {
+        if (key.toLowerCase() === "path")
+            delete result[key];
+    }
+    result.PATH = compactWindowsPackageManagerPath(pathValue, env, options);
+    return result;
+}
+const dependencyEnvironmentAllowlist = new Set([
+    "appdata",
+    "comspec",
+    "corepack_home",
+    "dotnet_cli_home",
+    "dotnet_root",
+    "home",
+    "homedrive",
+    "homepath",
+    "http_proxy",
+    "https_proxy",
+    "localappdata",
+    "no_proxy",
+    "npm_config_cache",
+    "nuget_http_cache_path",
+    "nuget_packages",
+    "path",
+    "pathext",
+    "programdata",
+    "programfiles",
+    "programfiles(x86)",
+    "programw6432",
+    "ssl_cert_dir",
+    "ssl_cert_file",
+    "systemdrive",
+    "systemroot",
+    "temp",
+    "tmp",
+    "tmpdir",
+    "userdomain",
+    "username",
+    "userprofile",
+    "windir",
+]);
+export function unattendedDependencyEnvironment(env = process.env) {
+    return Object.fromEntries(Object.entries(env).filter(([name, value]) => typeof value === "string"
+        && (dependencyEnvironmentAllowlist.has(name.toLowerCase()) || name.toUpperCase().startsWith("LC_"))));
+}
+export function compactWindowsPackageManagerPath(pathValue, env = process.env, options = {}) {
+    const pathExists = options.pathExists ?? existsSync;
+    const maximumPathLength = options.maximumPathLength
+        ?? windowsPackageManagerPathBudget(options.packageRoot ?? process.cwd());
+    const execPath = options.execPath ?? process.execPath;
+    if (!Number.isSafeInteger(maximumPathLength) || maximumPathLength < 1) {
+        throw new Error(`Windows package-manager PATH budget is exhausted before launch (${maximumPathLength}).`);
+    }
+    const normalize = windowsPathNormalizer(env);
+    const inherited = [];
+    const seen = new Set();
+    for (const candidate of pathValue.split(";").map(normalize)) {
+        if (candidate.length === 0 || !path.win32.isAbsolute(candidate) || !pathExists(candidate))
+            continue;
+        const key = candidate.toLowerCase();
+        if (seen.has(key))
+            continue;
+        inherited.push(candidate);
+        seen.add(key);
+    }
+    const nodeDirectory = normalize(path.win32.dirname(execPath));
+    if (!nodeDirectory || !path.win32.isAbsolute(nodeDirectory) || !pathExists(nodeDirectory)) {
+        throw new Error(`Windows Node runtime directory is unavailable: ${nodeDirectory || "<empty>"}.`);
+    }
+    const systemRoot = normalize(windowsEnvironmentValue(env, "SystemRoot") ?? "");
+    const requiredCandidates = [
+        nodeDirectory,
+        normalize(path.win32.dirname(windowsEnvironmentValue(env, "ComSpec") ?? "")),
+        systemRoot ? path.win32.join(systemRoot, "System32") : "",
+        systemRoot,
+    ].filter(candidate => candidate.length > 0
+        && path.win32.isAbsolute(candidate)
+        && pathExists(candidate));
+    const explicitRequired = (options.requiredPathDirectories ?? []).map(normalize);
+    for (const candidate of explicitRequired) {
+        if (!candidate || !path.win32.isAbsolute(candidate) || !pathExists(candidate)) {
+            throw new Error(`Windows package-manager required PATH directory is unavailable: ${candidate || "<empty>"}.`);
+        }
+        requiredCandidates.push(candidate);
+    }
+    const required = new Map();
+    for (const candidate of requiredCandidates)
+        required.set(candidate.toLowerCase(), candidate);
+    const ordered = [...inherited];
+    for (const candidate of required.values()) {
+        if (!seen.has(candidate.toLowerCase()))
+            ordered.push(candidate);
+    }
+    const requiredLength = joinedWindowsPathLength([...required.values()]);
+    if (requiredLength > maximumPathLength) {
+        throw new Error(`Windows package-manager PATH cannot retain required runtime directories within ${maximumPathLength} characters.`);
+    }
+    const selected = new Set(required.keys());
+    let selectedLength = requiredLength;
+    for (const candidate of inherited) {
+        const key = candidate.toLowerCase();
+        if (selected.has(key))
+            continue;
+        const nextLength = selectedLength + (selected.size === 0 ? 0 : 1) + candidate.length;
+        if (nextLength > maximumPathLength)
+            continue;
+        selected.add(key);
+        selectedLength = nextLength;
+    }
+    return ordered.filter(candidate => selected.has(candidate.toLowerCase())).join(";");
+}
+export function windowsPackageManagerLifecyclePathPrefix(packageRoot) {
+    const entries = [];
+    let current = path.win32.resolve(packageRoot);
+    while (true) {
+        entries.push(path.win32.join(current, "node_modules", ".bin"));
+        const parent = path.win32.dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return entries.join(";");
+}
+export function windowsPackageManagerPathBudget(packageRoot) {
+    const lifecyclePrefix = windowsPackageManagerLifecyclePathPrefix(packageRoot);
+    return WINDOWS_COMMAND_ENVIRONMENT_PATH_LIMIT
+        - lifecyclePrefix.length
+        - 1
+        - WINDOWS_PACKAGE_MANAGER_INTERNAL_PATH_RESERVE;
+}
+function resolveWindowsPackageManagerCommand(commandName, env, pathExists, fallbackDirectories) {
+    const normalize = windowsPathNormalizer(env);
+    const directories = [
+        ...windowsEnvironmentValues(env, "Path").flatMap(value => value.split(";")),
+        ...fallbackDirectories,
+    ].map(normalize);
+    const seen = new Set();
+    for (const directory of directories) {
+        if (!directory || !path.win32.isAbsolute(directory))
+            continue;
+        const key = directory.toLowerCase();
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        const candidate = path.win32.join(directory, commandName);
+        if (pathExists(candidate))
+            return candidate;
+    }
+    return null;
+}
+function resolveWindowsPackageManagerCli(manager, commandPath, execPath, pathExists) {
+    const commandDirectory = path.win32.dirname(commandPath);
+    const execDirectory = path.win32.dirname(execPath);
+    const candidates = manager === "npm"
+        ? [
+            path.win32.join(commandDirectory, "node_modules", "npm", "bin", "npm-cli.js"),
+            path.win32.join(execDirectory, "node_modules", "npm", "bin", "npm-cli.js"),
+            path.win32.join(execDirectory, "node_modules", "corepack", "dist", "npm.js"),
+        ]
+        : [
+            path.win32.join(commandDirectory, "node_modules", "pnpm", "bin", "pnpm.mjs"),
+            path.win32.join(execDirectory, "node_modules", "pnpm", "bin", "pnpm.mjs"),
+            path.win32.join(execDirectory, "node_modules", "corepack", "dist", "pnpm.js"),
+        ];
+    return candidates.find(pathExists) ?? null;
+}
+function windowsPathNormalizer(env) {
+    const environment = new Map(Object.entries(env).map(([key, value]) => [key.toLowerCase(), value ?? ""]));
+    return (value) => {
+        const trimmed = value.trim();
+        const unquoted = trimmed.length >= 2 && trimmed.startsWith('"') && trimmed.endsWith('"')
+            ? trimmed.slice(1, -1).trim()
+            : trimmed;
+        return unquoted.replace(/%([^%]+)%/gu, (match, name) => environment.get(name.toLowerCase()) || match);
+    };
+}
+function windowsEnvironmentValues(env, name) {
+    const normalized = name.toLowerCase();
+    return Object.entries(env)
+        .filter(([key, value]) => key.toLowerCase() === normalized && Boolean(value))
+        .map(([, value]) => value);
+}
+function windowsEnvironmentValue(env, name) {
+    return windowsEnvironmentValues(env, name)[0];
+}
+function joinedWindowsPathLength(entries) {
+    return entries.length === 0
+        ? 0
+        : entries.reduce((total, entry) => total + entry.length, entries.length - 1);
 }
 function tryResolveNpmCandidate(candidate) {
     try {
@@ -419,7 +888,13 @@ function defaultNpmCliCandidates(execPath, homeDir) {
 }
 const defaultCommandExecutor = {
     async run(cwd, command, args, options) {
-        const result = await defaultProcessRunner.run({ command, cwd, args, env: options?.env });
+        const result = await defaultProcessRunner.run({
+            command,
+            cwd,
+            args,
+            env: options?.env,
+            windowsVerbatimArguments: options?.windowsVerbatimArguments,
+        });
         if (result.exitCode !== 0) {
             const output = formatCommandFailureOutput(result.stdout, result.stderr);
             const details = output.length > 0 ? `\n${output}` : " no output was captured";

package/dist/worktree/index.d.ts

@@ -1,5 +1,5 @@
 export { GitWorktreeService } from "./worktree.service.js";
 export { managedRepoRoot, resolveManagedWorktreeRoot, resolveManagedWorktreeRootForRepo, } from "./worktree-paths.js";
 export { detectWarmPaths, warmWorktreeDependencies, createDirectoryLink, lockfilesDiffer, requiresInstallFallback } from "./dependency-warmer.js";
-export type { WarmDependenciesResult, WarmPathEntry, InstallFallbackResult } from "./dependency-warmer.js";
+export type { WarmDependenciesResult, WarmPathEntry, InstallFallbackResult, DependencyPreparationPolicy, DependencyPreparationReceiptResult, } from "./dependency-warmer.js";
 export type { WorktreeService } from "./worktree.base.js";

package/dist/worktree/story-qa-reference-hydrator.d.ts

@@ -0,0 +1,4 @@
+import { GitClient } from "../shared/git/git.js";
+import type { WorktreePrepareRequest } from "./worktree.types.js";
+export declare function storyQaReferenceRoot(storyId: string, runId: string): string;
+export declare function materializeStoryQaReferences(worktreePath: string, request: WorktreePrepareRequest, git?: GitClient): Promise<void>;