@loucompanion/forge-bridge 0.1.3-dev.d1ca67076aa9 → 0.1.3-dev.e7b62d8fdd33

package/dist/shared/process/windows-launch.js

@@ -1,8 +1,11 @@
 import path from "node:path";
-export function buildWindowsCmdLaunch(command, args) {
+export function buildWindowsCmdLaunch(command, args, comSpec = process.env.ComSpec) {
+    const resolvedComSpec = comSpec?.trim();
+    const commandLine = windowsCommandLine(command, args);
+    const cmdPayload = commandLine.startsWith('"') ? `"${commandLine}"` : commandLine;
     return {
-        command: process.env.ComSpec ?? "cmd.exe",
-        args: ["/d", "/s", "/v:off", "/c", `"${windowsCommandLine(command, args)}"`]
+        command: resolvedComSpec || "cmd.exe",
+        args: ["/d", "/s", "/v:off", "/c", cmdPayload]
     };
 }
 export function buildWindowsLaunchCommand(commandPath, args) {

package/dist/shared/provider-capabilities.d.ts

@@ -0,0 +1 @@
+export declare function supportsDraftImageAttachmentsFor(cliProviders: readonly string[]): boolean;

package/dist/shared/provider-capabilities.js

@@ -0,0 +1,3 @@
+export function supportsDraftImageAttachmentsFor(cliProviders) {
+    return cliProviders.some((provider) => provider.trim().toLowerCase() === "codex");
+}

package/dist/shared/redaction/redaction.js

@@ -1,17 +1,29 @@
 const secretKeyPattern = /(api[_-]?key|authorization|bearer|client[_-]?secret|password|secret|token)/i;
+const attachmentContentKeyPattern = /^(textContent|contentBase64)$/i;
+const serializedAttachmentContentPattern = /("(?:textContent|contentBase64)"\s*:\s*")(?:(?:\\.)|[^"\\])*(")/gi;
+const authorizationCredentialPattern = /(\bauthorization\s*[:=]\s*(?:bearer|basic)?\s*)([^"',\s]+)/gi;
+const bearerCredentialPattern = /(\bbearer\s+)([^"',\s]+)/gi;
+const secretAssignmentPattern = /(api[_-]?key|client[_-]?secret|password|secret|token)(\s*["']?\s*[:=]\s*["']?\s*)([^"',\s]+)/gi;
+// Keep this boundary in parity with Forge.Api's SecretRedactor. Without it, the
+// `sk-` substring in a structural identifier such as `task-skill-contract`
+// is mistaken for a provider credential and corrupts the artifact after it has
+// already passed schema validation.
+const providerKeyPattern = /(?<![a-zA-Z0-9])sk-[a-zA-Z0-9_-]{12,}/g;
 export function redactSecrets(value, exactSecrets = []) {
     return redactValue(value, exactSecrets);
 }
 export function redactText(value, exactSecrets = []) {
-    let redacted = value;
+    let redacted = value.replace(serializedAttachmentContentPattern, "$1[REDACTED]$2");
     for (const secret of exactSecrets) {
         if (secret.length > 0) {
             redacted = redacted.split(secret).join("[REDACTED]");
         }
     }
     return redacted
-        .replace(/(api[_-]?key|authorization|bearer|client[_-]?secret|password|secret|token)(["':=\s]+)([^"',\s]+)/gi, "$1$2[REDACTED]")
-        .replace(/(sk-[a-zA-Z0-9_-]{12,})/g, "[REDACTED]");
+        .replace(authorizationCredentialPattern, "$1[REDACTED]")
+        .replace(bearerCredentialPattern, "$1[REDACTED]")
+        .replace(secretAssignmentPattern, "$1$2[REDACTED]")
+        .replace(providerKeyPattern, "[REDACTED]");
 }
 function redactValue(value, exactSecrets) {
     if (typeof value === "string") {
@@ -25,6 +37,6 @@ function redactValue(value, exactSecrets) {
     }
     return Object.fromEntries(Object.entries(value).map(([key, item]) => [
         key,
-        secretKeyPattern.test(key) ? "[REDACTED]" : redactValue(item, exactSecrets)
+        secretKeyPattern.test(key) || attachmentContentKeyPattern.test(key) ? "[REDACTED]" : redactValue(item, exactSecrets)
     ]));
 }

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const forgeBridgeVersion = "0.1.3-dev.d1ca67076aa9";
+export declare const forgeBridgeVersion = "0.1.3-dev.e7b62d8fdd33";

package/dist/version.js

@@ -1 +1 @@
-export const forgeBridgeVersion = "0.1.3-dev.d1ca67076aa9";
+export const forgeBridgeVersion = "0.1.3-dev.e7b62d8fdd33";

package/dist/worktree/artifact-injector.d.ts

@@ -1,9 +1,10 @@
 import type { DispatchResolvedArtifact } from "../session/session.types.js";
-export declare function injectWorktreeArtifacts(worktreePath: string, artifacts: readonly DispatchResolvedArtifact[]): Promise<void>;
+export declare function injectWorktreeArtifacts(worktreePath: string, artifacts: readonly DispatchResolvedArtifact[], protectedRelativePaths?: ReadonlySet<string>): Promise<void>;
 export declare function filterArtifactsForLane(artifacts: readonly DispatchResolvedArtifact[], lane: string, phase: string): readonly DispatchResolvedArtifact[];
-export declare function writeArtifact(worktreePath: string, artifact: DispatchResolvedArtifact): Promise<void>;
+export declare function writeArtifact(worktreePath: string, artifact: DispatchResolvedArtifact, protectedRelativePaths?: ReadonlySet<string>): Promise<void>;
 export declare function selectLaneCommand(artifacts: readonly DispatchResolvedArtifact[], lane: string, phase: string): DispatchResolvedArtifact | undefined;
 export declare function resolveCommandSlug(lane: string, phase: string): string;
+export declare function artifactExecutionBody(artifact: DispatchResolvedArtifact): string;
 export declare function buildSpecBody(laneCommand: DispatchResolvedArtifact, workItem: {
     readonly id: string;
     readonly title: string;

package/dist/worktree/artifact-injector.js

@@ -1,4 +1,5 @@
 import crypto from "node:crypto";
+import { spawn } from "node:child_process";
 import fs from "node:fs/promises";
 import path from "node:path";
 const DEBUG_OPERATIONAL_SKILLS = new Set(["debug-repro", "debug-root-cause", "debug-fix", "debug-regression"]);
@@ -59,9 +60,9 @@ const DRAFT_WORK_ITEM_OPERATIONAL_HOOKS = new Set([
 const DRAFT_WORK_ORDER_OPERATIONAL_HOOKS = new Set([
     "draft-work-order-plan"
 ]);
-export async function injectWorktreeArtifacts(worktreePath, artifacts) {
+export async function injectWorktreeArtifacts(worktreePath, artifacts, protectedRelativePaths = new Set()) {
     for (const artifact of artifacts) {
-        await writeArtifact(worktreePath, artifact);
+        await writeArtifact(worktreePath, artifact, protectedRelativePaths);
     }
 }
 export function filterArtifactsForLane(artifacts, lane, phase) {
@@ -78,7 +79,7 @@ export function filterArtifactsForLane(artifacts, lane, phase) {
     }
     return artifacts;
 }
-export async function writeArtifact(worktreePath, artifact) {
+export async function writeArtifact(worktreePath, artifact, protectedRelativePaths = new Set()) {
     const writtenHash = sha256(artifact.body);
     if (writtenHash !== artifact.contentHash.toLowerCase()) {
         throw new Error(`Injected artifact '${artifact.slug}' content_hash mismatch (expected ${artifact.contentHash}, got ${writtenHash}).`);
@@ -93,6 +94,11 @@ export async function writeArtifact(worktreePath, artifact) {
         ? path.resolve(scopeDir, slug, "SKILL.md")
         : path.resolve(scopeDir, `${slug}.md`);
     assertInside(forgeRoot, filePath, "Artifact file");
+    const relativePath = path.relative(worktreePath, filePath).replaceAll(path.sep, "/");
+    if (protectedRelativePaths.has(relativePath)) {
+        await restoreTrackedArtifactIfItMatchesManagedBody(worktreePath, filePath, relativePath, artifact);
+        return;
+    }
     await fs.mkdir(path.dirname(filePath), { recursive: true });
     await fs.writeFile(filePath, artifact.body, "utf8");
 }
@@ -120,6 +126,39 @@ export function resolveCommandSlug(lane, phase) {
             return "dev-prompt";
     }
 }
+async function restoreTrackedArtifactIfItMatchesManagedBody(worktreePath, filePath, relativePath, artifact) {
+    const current = await fs.readFile(filePath, "utf8").catch(() => null);
+    if (current === null
+        || (current !== artifact.body && current !== artifactExecutionBody(artifact)))
+        return;
+    const result = await new Promise((resolve) => {
+        const child = spawn("git", ["show", `HEAD:${relativePath}`], {
+            cwd: worktreePath,
+            windowsHide: true,
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        let stdout = "";
+        child.stdout?.setEncoding("utf8");
+        child.stdout?.on("data", chunk => { stdout += chunk; });
+        child.on("error", () => resolve({ exitCode: 1, stdout: "" }));
+        child.on("close", code => resolve({ exitCode: code ?? 1, stdout }));
+    });
+    if (result.exitCode === 0)
+        await fs.writeFile(filePath, result.stdout, "utf8");
+}
+export function artifactExecutionBody(artifact) {
+    const content = artifact.body;
+    if (!content.startsWith("---"))
+        return content;
+    const end = content.indexOf("\n---", 3);
+    if (end < 3)
+        return content;
+    let bodyStart = end + 4;
+    while (bodyStart < content.length && (content[bodyStart] === "\n" || content[bodyStart] === "\r")) {
+        bodyStart += 1;
+    }
+    return content.slice(bodyStart);
+}
 function shouldInjectDebugArtifact(artifact, commandSlug) {
     if (artifact.scope.trim().toLowerCase() !== "operational") {
         return false;
@@ -192,7 +231,7 @@ function normalizeDraftPhase(phase) {
     return phase.trim().toLowerCase().replaceAll("-", "_");
 }
 export function buildSpecBody(laneCommand, workItem, phase = "implementation") {
-    const prompt = laneCommand.body.replaceAll("{workItemId}", workItem.id);
+    const prompt = artifactExecutionBody(laneCommand).replaceAll("{workItemId}", workItem.id);
     return `---
 work_item_id: ${workItem.id}
 status: approved

package/dist/worktree/dependency-warmer.d.ts

@@ -9,6 +9,13 @@ export interface WarmDependenciesRequest {
     readonly worktreePath: string;
     readonly allowedRoot: string;
     readonly warmPathOverrides?: readonly string[];
+    readonly preparationPolicy?: DependencyPreparationPolicy;
+}
+export interface DependencyPreparationPolicy {
+    readonly isolation?: string;
+    readonly trustDomain?: string;
+    readonly invalidationEpoch?: string;
+    readonly toolchainVersions?: Readonly<Partial<Record<DependencyEcosystem | "npm" | "pnpm", string>>>;
 }
 export interface InstallFallbackResult {
     readonly ecosystem: DependencyEcosystem;
@@ -20,9 +27,23 @@ export interface WarmDependenciesResult {
     readonly linked: readonly string[];
     readonly skipped: readonly string[];
     readonly fallbacks: readonly InstallFallbackResult[];
+    readonly receipts: readonly DependencyPreparationReceiptResult[];
+}
+export interface DependencyPreparationReceiptResult {
+    readonly ecosystem: DependencyEcosystem;
+    readonly packageRoot: string;
+    readonly command: string;
+    readonly cacheHit: boolean;
+    readonly fingerprint: string;
+    readonly receiptPath: string;
+    /** End-to-end receipt lookup/preparation time, including coordinator wait. */
+    readonly durationMs: number;
 }
 export interface CommandExecutor {
-    run(cwd: string, command: string, args: readonly string[]): Promise<void>;
+    run(cwd: string, command: string, args: readonly string[], options?: CommandExecutionOptions): Promise<void>;
+}
+export interface CommandExecutionOptions {
+    readonly env?: NodeJS.ProcessEnv;
 }
 export declare function detectWarmPaths(repoRoot: string, warmPathOverrides?: readonly string[]): Promise<WarmPathEntry[]>;
 export declare function warmWorktreeDependencies(request: WarmDependenciesRequest, executor?: CommandExecutor): Promise<WarmDependenciesResult>;
@@ -30,3 +51,20 @@ export declare function createDirectoryLink(sourcePath: string, targetPath: stri
 export declare function lockfilesDiffer(baseCheckoutPath: string, worktreePath: string, packageRootRelative: string): Promise<boolean>;
 export declare function requiresInstallFallback(entry: WarmPathEntry, baseCheckoutPath: string, worktreePath: string, sourceExists: boolean): Promise<string | null>;
 export declare function declaresNativeModules(packageRootPath: string): Promise<boolean>;
+export interface NpmLaunchOptions {
+    readonly env?: NodeJS.ProcessEnv;
+    readonly execPath?: string;
+    readonly platform?: NodeJS.Platform;
+    readonly homeDir?: string;
+    readonly candidates?: readonly string[];
+}
+export declare function resolveNpmLaunch(args: readonly string[], options?: NpmLaunchOptions): {
+    command: string;
+    args: readonly string[];
+};
+export declare function resolvePnpmLaunch(args: readonly string[]): {
+    command: string;
+    args: readonly string[];
+};
+export declare function formatCommandFailureOutput(stdout: string, stderr: string): string;
+export declare function unattendedPackageManagerEnvironment(env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;

package/dist/worktree/dependency-warmer.js

@@ -1,7 +1,13 @@
+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 { 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",
@@ -20,6 +26,10 @@ const NATIVE_MODULE_HINTS = [
     "better-sqlite3",
     "@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 dependencyPreparationCoordinator = new RepositoryCoordinatorLock(defaultWorktreeCoordinatorStateRoot());
 export async function detectWarmPaths(repoRoot, warmPathOverrides = []) {
     const entries = new Map();
     await collectDetectedPaths(repoRoot, repoRoot, entries, 0);
@@ -47,15 +57,51 @@ 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) {
         const sourcePath = path.join(baseCheckoutPath, entry.relativePath);
         const targetPath = path.join(worktreePath, entry.relativePath);
         assertWithinRoot(allowedRoot, targetPath, "Warm target");
+        if (entry.ecosystem === "node" && path.basename(entry.relativePath) === "node_modules") {
+            await removeLegacyDirectoryLink(targetPath, allowedRoot);
+            const installPackageRoot = await resolveNodeInstallPackageRoot(worktreePath, entry.packageRoot);
+            const packageRoot = path.resolve(worktreePath, installPackageRoot === "." ? "" : installPackageRoot);
+            const packageKey = process.platform === "win32" ? packageRoot.toLowerCase() : packageRoot;
+            if (installedNodeRoots.has(packageKey)) {
+                skipped.push(entry.relativePath);
+                continue;
+            }
+            installedNodeRoots.add(packageKey);
+            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") {
+            await removeLegacyDirectoryLink(targetPath, allowedRoot);
+            const packageRoot = path.resolve(worktreePath, entry.packageRoot === "." ? "" : entry.packageRoot);
+            const packageKey = process.platform === "win32" ? packageRoot.toLowerCase() : packageRoot;
+            if (restoredDotNetRoots.has(packageKey)) {
+                skipped.push(entry.relativePath);
+                continue;
+            }
+            restoredDotNetRoots.add(packageKey);
+            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) {
@@ -65,7 +111,17 @@ 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);
+    const resolvedRoot = path.resolve(allowedRoot);
+    assertWithinRoot(resolvedRoot, resolvedTarget, "Legacy warm target");
+    const stat = await fs.lstat(resolvedTarget).catch(() => null);
+    if (!stat?.isSymbolicLink()) {
+        return;
+    }
+    await fs.rm(resolvedTarget, { force: true });
 }
 export async function createDirectoryLink(sourcePath, targetPath, allowedRoot) {
     const resolvedSource = path.resolve(sourcePath);
@@ -78,7 +134,10 @@ export async function createDirectoryLink(sourcePath, targetPath, allowedRoot) {
     if (!stat?.isDirectory()) {
         throw new Error(`Link source must be an existing directory: ${resolvedSource}`);
     }
-    await fs.rm(resolvedTarget, { recursive: true, force: true });
+    const existingTarget = await fs.lstat(resolvedTarget).catch(() => null);
+    await fs.rm(resolvedTarget, existingTarget?.isSymbolicLink()
+        ? { force: true }
+        : { recursive: true, force: true });
     await fs.mkdir(path.dirname(resolvedTarget), { recursive: true });
     if (process.platform === "win32") {
         await fs.symlink(resolvedSource, resolvedTarget, "junction");
@@ -179,12 +238,217 @@ 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)) {
+            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);
+        return {
+            install,
+            receipt: {
+                ecosystem: entry.ecosystem,
+                packageRoot: entry.packageRoot,
+                command,
+                cacheHit: false,
+                fingerprint,
+                receiptPath,
+                durationMs: elapsedMilliseconds(startedAt),
+            },
+        };
+    });
+}
+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) {
     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() });
+            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"];
-        await executor.run(cwd, "npm", args);
+        const launch = resolveNpmLaunch(args);
+        await executor.run(cwd, launch.command, launch.args, { env: unattendedPackageManagerEnvironment() });
         return { ecosystem: entry.ecosystem, packageRoot: entry.packageRoot, reason, command: `npm ${args.join(" ")}` };
     }
     if (entry.ecosystem === "python") {
@@ -215,6 +479,23 @@ async function runInstallFallback(entry, worktreePath, reason, executor) {
         command: "dotnet restore"
     };
 }
+async function resolveNodeInstallPackageRoot(worktreePath, packageRoot) {
+    const resolvedWorktree = path.resolve(worktreePath);
+    let current = path.resolve(resolvedWorktree, packageRoot === "." ? "" : packageRoot);
+    assertWithinRoot(resolvedWorktree, current, "Node package root");
+    while (isSubPath(resolvedWorktree, current)) {
+        if (await pathExists(path.join(current, "pnpm-lock.yaml"))
+            || await pathExists(path.join(current, "pnpm-workspace.yaml"))
+            || await pathExists(path.join(current, "package-lock.json"))) {
+            const relative = normalizeRelativePath(path.relative(resolvedWorktree, current));
+            return relative || ".";
+        }
+        if (current === resolvedWorktree)
+            break;
+        current = path.dirname(current);
+    }
+    return packageRoot;
+}
 export async function requiresInstallFallback(entry, baseCheckoutPath, worktreePath, sourceExists) {
     return resolveFallbackReason(entry, baseCheckoutPath, worktreePath, sourceExists);
 }
@@ -286,11 +567,73 @@ async function sha256File(filePath) {
     const content = await fs.readFile(filePath);
     return crypto.createHash("sha256").update(content).digest("hex");
 }
+export function resolveNpmLaunch(args, options = {}) {
+    const env = options.env ?? process.env;
+    const execPath = options.execPath ?? process.execPath;
+    const npmExecPath = env.npm_execpath;
+    if (npmExecPath && path.basename(npmExecPath).toLowerCase() === "npm-cli.js") {
+        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);
+    }
+    for (const candidate of options.candidates ?? defaultNpmCliCandidates(execPath, options.homeDir ?? os.homedir())) {
+        const resolvedCandidate = tryResolveNpmCandidate(candidate);
+        if (resolvedCandidate) {
+            return { command: execPath, args: [resolvedCandidate, ...args] };
+        }
+    }
+    return { command: "npm", args };
+}
+export function resolvePnpmLaunch(args) {
+    if (process.platform === "win32") {
+        return buildWindowsCmdLaunch("pnpm.cmd", args, process.env.ComSpec);
+    }
+    return { command: "pnpm", args };
+}
+export function formatCommandFailureOutput(stdout, stderr) {
+    const sections = [
+        stderr.trim().length > 0 ? `stderr:\n${stderr.trim()}` : null,
+        stdout.trim().length > 0 ? `stdout:\n${stdout.trim()}` : null,
+    ].filter((section) => section !== null);
+    const output = sections.join("\n");
+    if (output.length <= MAX_COMMAND_FAILURE_OUTPUT_LENGTH) {
+        return output;
+    }
+    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" };
+}
+function tryResolveNpmCandidate(candidate) {
+    try {
+        if (!existsSync(candidate)) {
+            return null;
+        }
+        return realpathSync(candidate);
+    }
+    catch {
+        return null;
+    }
+}
+function defaultNpmCliCandidates(execPath, homeDir) {
+    const candidates = [];
+    const execDir = path.dirname(execPath);
+    if (path.isAbsolute(execDir)) {
+        candidates.push(path.join(execDir, "npm"), path.join(execDir, "npm-cli.js"), path.join(execDir, "..", "lib", "node_modules", "npm", "bin", "npm-cli.js"));
+    }
+    candidates.push("/usr/bin/npm", "/usr/local/bin/npm", path.join(homeDir, ".npm-global", "bin", "npm"), path.join(homeDir, ".npm-global", "lib", "node_modules", "npm", "bin", "npm-cli.js"));
+    return candidates;
+}
 const defaultCommandExecutor = {
-    async run(cwd, command, args) {
-        const result = await defaultProcessRunner.run({ command, cwd, args });
+    async run(cwd, command, args, options) {
+        const result = await defaultProcessRunner.run({ command, cwd, args, env: options?.env });
         if (result.exitCode !== 0) {
-            throw new Error(`${command} ${args.join(" ")} failed (${result.exitCode}): ${result.stderr.trim()}`);
+            const output = formatCommandFailureOutput(result.stdout, result.stderr);
+            const details = output.length > 0 ? `\n${output}` : " no output was captured";
+            throw new Error(`${command} ${args.join(" ")} failed (${result.exitCode}) in ${cwd}:${details}`);
         }
     }
 };