coding-agent-harness 1.0.7 → 1.1.0

package/dist/lib/preset-runner.mjs

@@ -0,0 +1,560 @@
+// Generic preset entrypoint runner. Domain logic belongs in preset packages.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import crypto from "node:crypto";
+import { spawnSync } from "node:child_process";
+import { absoluteHarnessPathContext, harnessPathContext, normalizeTarget, readFileSafe, readJsonSafe, renderHarnessTemplate, sanitizeDeep, toPosix, walkFiles, } from "./core-shared.mjs";
+import { beginGovernanceSync, commitGovernanceSync, releaseGovernanceSync } from "./governance-sync.mjs";
+import { parseTaskMetadata } from "./task-metadata.mjs";
+import { taskIdForDirectory } from "./task-scanner.mjs";
+import { resolveTaskDirectory } from "./task-lifecycle.mjs";
+import { evaluateTemplateValues, assertPresetWriteScope, resolvePresetScopes } from "./preset-engine.mjs";
+import { buildPresetAudit, buildPresetScriptPolicy, presetScriptTrustValid, readPresetPackage } from "./preset-registry.mjs";
+const materializationSchemaVersion = "preset-materialization/v1";
+const maxMaterializedFileBytes = 10 * 1024 * 1024;
+const maxMaterializedWrites = 500;
+export function runPresetEntrypoint(presetId, entrypointName, { taskRef = "", targetInput = ".", json = false, allowScripts = false, useCurrentPreset = false, reason = "" } = {}) {
+    void json;
+    const target = normalizeTarget(targetInput);
+    const preset = readPresetPackage(presetId, { targetInput });
+    const entrypoint = preset.entrypoints?.[entrypointName];
+    if (!entrypoint)
+        throw new Error(`Preset ${preset.id} does not declare entrypoint: ${entrypointName}`);
+    if (!["script", "check"].includes(entrypoint.type))
+        throw new Error(`Preset entrypoint ${entrypointName} is not runnable by preset run`);
+    const scriptPolicy = buildPresetScriptPolicy(preset);
+    if (scriptPolicy.requiresTrustedSource && !allowScripts && !presetScriptTrustValid(preset)) {
+        throw new Error(`Preset entrypoint ${preset.id}.${entrypointName} executes trusted local code. Re-run with --allow-scripts if you trust this preset source.`);
+    }
+    if (!taskRef)
+        throw new Error("preset run requires --task <task-id>");
+    const taskDir = resolveTaskDirectory(target, taskRef);
+    const taskPlan = readFileSafe(path.join(taskDir, "task_plan.md"));
+    const metadata = parseTaskMetadata(taskPlan);
+    if (metadata.preset !== preset.id)
+        throw new Error(`Task ${taskRef} was created by preset ${metadata.preset || "none"}, not ${preset.id}`);
+    const taskId = taskIdForDirectory(target, taskDir);
+    const audit = readPresetAudit(target, metadata);
+    const presetDrift = assessPresetDrift(audit, preset, { useCurrentPreset, reason });
+    const resolvedInputs = asRecord(audit.resolvedInputs);
+    const values = evaluateTemplateValues(preset, resolvedInputs, { taskId, taskTitle: taskId, moduleKey: "", target });
+    const resolvedScopes = resolvePresetScopes(preset, target);
+    const outputRoot = fs.mkdtempSync(path.join(os.tmpdir(), `harness-preset-${preset.id}-${entrypointName}-`));
+    const manifestPath = path.join(outputRoot, "materialization-manifest.json");
+    const contextPath = path.join(outputRoot, "preset-context.json");
+    const beforeSnapshot = targetSnapshot(target.projectRoot);
+    try {
+        const context = {
+            schemaVersion: "preset-run-context/v1",
+            preset: { id: preset.id, version: preset.version, source: preset.source },
+            entrypoint: entrypointName,
+            task: {
+                id: taskId,
+                ref: taskRef,
+                dir: toPosix(path.relative(target.projectRoot, taskDir)),
+                taskPlanPath: toPosix(path.relative(target.projectRoot, path.join(taskDir, "task_plan.md"))),
+            },
+            targetRoot: target.projectRoot,
+            targetRootPolicy: "read-only; direct target mutation before manifest materialization is a hard failure",
+            runtime: {
+                coreModule: new URL("./harness-core.mjs", import.meta.url).href,
+            },
+            outputRoot,
+            materializationManifestPath: manifestPath,
+            paths: harnessPathContext(target),
+            absolutePaths: absoluteHarnessPathContext(target),
+            inputs: sanitizeDeep(resolvedInputs),
+            values: sanitizeDeep(values),
+            audit: buildPresetAudit(preset, {
+                taskId,
+                targetRoot: target.projectRoot,
+                entrypoint: entrypointName,
+                writeScopes: resolvedScopes.entrypoints[entrypointName] || entrypoint.writes,
+                resolvedInputs,
+            }),
+        };
+        fs.writeFileSync(contextPath, `${JSON.stringify(context, null, 2)}\n`);
+        const commandPath = path.join(preset.directory, entrypoint.command || "");
+        const script = spawnSync(process.execPath, [commandPath], {
+            cwd: outputRoot,
+            encoding: "utf8",
+            env: presetScriptEnv(contextPath),
+            timeout: 120000,
+            maxBuffer: 10 * 1024 * 1024,
+        });
+        if (script.error)
+            throw script.error;
+        if (script.status !== 0) {
+            throw new Error(`Preset entrypoint ${preset.id}.${entrypointName} failed with ${script.status}\n${script.stderr || script.stdout || ""}`.trim());
+        }
+        const afterScriptSnapshot = targetSnapshot(target.projectRoot);
+        assertSnapshotsEqual(beforeSnapshot, afterScriptSnapshot, "Preset script mutated target before materialization");
+        const manifest = readMaterializationManifest(manifestPath);
+        const materialization = validateMaterializationManifest(preset, entrypoint, manifest, { outputRoot, target, entrypointName });
+        const governanceContext = beginGovernanceSync(target, {
+            operation: `preset-run ${preset.id}.${entrypointName}`,
+            allowDirtyWorktree: true,
+            allowedRelativePaths: materialization.map((item) => item.destination),
+        });
+        try {
+            materializeWrites(target.projectRoot, materialization);
+            const commit = commitGovernanceSync(governanceContext, materialization.map((item) => item.destination), {
+                message: `chore(harness): run preset ${preset.id} ${entrypointName}`,
+            });
+            return {
+                preset: preset.id,
+                entrypoint: entrypointName,
+                taskId,
+                status: manifest.status || (entrypoint.type === "check" ? "pass" : "ok"),
+                materialized: materialization.map((item) => ({
+                    source: item.source,
+                    destination: item.destination,
+                    type: item.type,
+                    sha256: item.sha256,
+                })),
+                governance: { commit },
+                presetDrift,
+            };
+        }
+        finally {
+            releaseGovernanceSync(governanceContext);
+        }
+    }
+    finally {
+        fs.rmSync(outputRoot, { recursive: true, force: true });
+    }
+}
+export function runPresetAction(presetId, actionName, { taskRef = "", targetInput = ".", json = false, actionArgs = [], allowScripts = false, useCurrentPreset = false, reason = "" } = {}) {
+    void json;
+    const target = normalizeTarget(targetInput);
+    const preset = readPresetPackage(presetId, { targetInput });
+    const action = preset.actions?.[actionName];
+    if (!action)
+        throw new Error(`Preset ${preset.id} does not declare action: ${actionName}`);
+    if (action.type !== "script")
+        throw new Error(`Preset action ${actionName} is not runnable by preset action`);
+    if (action.taskRequired !== true)
+        throw new Error(`Preset action ${preset.id}.${actionName} requires taskRequired: true`);
+    if (!taskRef)
+        throw new Error("preset action requires --task <task-id>");
+    const scriptPolicy = buildPresetScriptPolicy(preset);
+    if (scriptPolicy.requiresTrustedSource && !allowScripts && !presetScriptTrustValid(preset)) {
+        throw new Error(`Preset action ${preset.id}.${actionName} executes trusted local code. Re-run with --allow-scripts if you trust this preset source.`);
+    }
+    const taskDir = resolveTaskDirectory(target, taskRef);
+    const taskPlan = readFileSafe(path.join(taskDir, "task_plan.md"));
+    const metadata = parseTaskMetadata(taskPlan);
+    if (metadata.preset !== preset.id)
+        throw new Error(`Task ${taskRef} was created by preset ${metadata.preset || "none"}, not ${preset.id}`);
+    const taskId = taskIdForDirectory(target, taskDir);
+    const taskPaths = taskPathContext(target, taskDir);
+    const actionInputs = resolveActionInputs(action, actionArgs);
+    const audit = readPresetAudit(target, metadata);
+    const presetDrift = assessPresetDrift(audit, preset, { useCurrentPreset, reason });
+    const creationInputs = asRecord(audit.resolvedInputs);
+    const values = evaluateTemplateValues(preset, creationInputs, { taskId, taskTitle: taskId, moduleKey: "", target });
+    const actionWriteScopes = resolveActionScopes(action.writes, { target, taskPaths, label: `${actionName} action write scope` });
+    const outputRoot = fs.mkdtempSync(path.join(os.tmpdir(), `harness-preset-${preset.id}-${actionName}-`));
+    const manifestPath = path.join(outputRoot, "materialization-manifest.json");
+    const contextPath = path.join(outputRoot, "preset-action-context.json");
+    let governanceContext = null;
+    try {
+        governanceContext = beginGovernanceSync(target, {
+            operation: `preset-action ${preset.id}.${actionName}`,
+            allowDirtyWorktree: true,
+            allowedRelativePaths: concreteActionWriteScopes(actionWriteScopes),
+        });
+        const beforeSnapshot = targetSnapshot(target.projectRoot);
+        const context = {
+            schemaVersion: "preset-action-context/v1",
+            preset: { id: preset.id, version: preset.version, source: preset.source, manifestSha256: preset.manifestSha256 },
+            action: { id: actionName, type: action.type },
+            task: {
+                id: taskId,
+                ref: taskRef,
+                dir: taskPaths.dir,
+                taskPlanPath: taskPaths.taskPlan,
+                paths: taskPaths,
+            },
+            targetRoot: target.projectRoot,
+            targetRootPolicy: "read-only; direct target mutation before manifest materialization is a hard failure",
+            outputRoot,
+            materializationManifestPath: manifestPath,
+            paths: harnessPathContext(target),
+            inputs: sanitizeDeep(actionInputs),
+            creationInputs: sanitizeDeep(creationInputs),
+            values: sanitizeDeep(values),
+            audit: buildPresetAudit(preset, {
+                taskId,
+                targetRoot: target.projectRoot,
+                entrypoint: `action:${actionName}`,
+                writeScopes: actionWriteScopes,
+                resolvedInputs: actionInputs,
+            }),
+            presetDrift,
+        };
+        fs.writeFileSync(contextPath, `${JSON.stringify(context, null, 2)}\n`);
+        const commandPath = path.join(preset.directory, action.command || "");
+        const script = spawnSync(process.execPath, [commandPath], {
+            cwd: outputRoot,
+            encoding: "utf8",
+            env: presetScriptEnv(contextPath),
+            timeout: 120000,
+            maxBuffer: 128 * 1024,
+        });
+        if (script.error)
+            throw script.error;
+        if (script.status !== 0) {
+            throw new Error(`Preset action ${preset.id}.${actionName} failed with ${script.status}\n${boundedScriptOutput(script.stderr || script.stdout || "")}`.trim());
+        }
+        const afterScriptSnapshot = targetSnapshot(target.projectRoot);
+        assertSnapshotsEqual(beforeSnapshot, afterScriptSnapshot, "Preset script mutated target before materialization");
+        const manifest = readMaterializationManifest(manifestPath);
+        const materialization = validateMaterializationManifest(preset, {
+            type: action.type,
+            command: action.command,
+            templates: {},
+            writes: actionWriteScopes,
+            reads: action.reads,
+            audit: action.audit,
+        }, manifest, { outputRoot, target, entrypointName: actionName });
+        materializeWrites(target.projectRoot, materialization);
+        const commit = commitGovernanceSync(governanceContext, materialization.map((item) => item.destination), {
+            message: `chore(harness): run preset action ${preset.id} ${actionName}`,
+        });
+        return {
+            preset: preset.id,
+            action: actionName,
+            source: preset.source,
+            manifestSha256: preset.manifestSha256,
+            taskId,
+            status: manifest.status || "ok",
+            materialized: materialization.map((item) => ({
+                source: item.source,
+                destination: item.destination,
+                type: item.type,
+                sha256: item.sha256,
+            })),
+            governance: { commit },
+            presetDrift,
+        };
+    }
+    finally {
+        if (governanceContext)
+            releaseGovernanceSync(governanceContext);
+        fs.rmSync(outputRoot, { recursive: true, force: true });
+    }
+}
+function readPresetAudit(target, metadata) {
+    const evidenceBundle = normalizeTargetRelativePath(metadata.evidenceBundle || "", "Preset evidence bundle");
+    if (!evidenceBundle)
+        return {};
+    const auditPath = path.join(target.projectRoot, evidenceBundle, "preset-audit.json");
+    const audit = asRecord(readJsonSafe(auditPath, {}));
+    return audit;
+}
+function assessPresetDrift(audit, preset, { useCurrentPreset = false, reason = "" } = {}) {
+    const recorded = String(audit.manifestSha256 || "");
+    const current = String(preset.manifestSha256 || "");
+    if (!recorded || !current || recorded === current) {
+        return { detected: false, accepted: false, recordedManifestSha256: recorded, currentManifestSha256: current, reason: "" };
+    }
+    const normalizedReason = String(reason || "").trim();
+    if (!useCurrentPreset || !normalizedReason) {
+        throw new Error(`Preset manifest hash drift detected for ${preset.id}: recorded ${recorded}, current ${current}. Re-run with --use-current-preset --reason <why-current-semantics-are-intended>, or create a new task with the current preset.`);
+    }
+    return { detected: true, accepted: true, recordedManifestSha256: recorded, currentManifestSha256: current, reason: normalizedReason };
+}
+function resolveActionInputs(action, cliArgs) {
+    const remaining = [...cliArgs];
+    const inputs = {};
+    for (const [name, declaration] of Object.entries(action.inputs || {})) {
+        inputs[name] = resolveActionInputValue(name, declaration, remaining);
+    }
+    if (remaining.length > 0)
+        throw new Error(`Unknown action argument: ${remaining[0]}`);
+    return inputs;
+}
+function resolveActionInputValue(name, declaration, remaining) {
+    const flag = declaration.flag || name;
+    const index = remaining.indexOf(flag);
+    if (declaration.type === "flag") {
+        if (index >= 0) {
+            remaining.splice(index, 1);
+            return true;
+        }
+        return Boolean(declaration.default);
+    }
+    if (index < 0) {
+        if (declaration.required)
+            throw new Error(`Missing required action input ${flag}`);
+        return declaration.default ?? "";
+    }
+    const value = remaining[index + 1] || "";
+    if (!value || value.startsWith("--"))
+        throw new Error(`Missing value for action input ${flag}`);
+    remaining.splice(index, 2);
+    if (String(value).includes("\0"))
+        throw new Error(`Action input ${flag} contains NUL byte`);
+    if (declaration.type === "text") {
+        if (String(value).length > 4096)
+            throw new Error(`Action input ${flag} exceeds text length limit`);
+        return String(value);
+    }
+    if (declaration.type === "json-file") {
+        const filePath = path.resolve(String(value));
+        if (!fs.existsSync(filePath))
+            throw new Error(`Action input file not found for ${flag}: ${value}`);
+        const stat = fs.statSync(filePath);
+        if (!stat.isFile())
+            throw new Error(`Action input file must be a file for ${flag}: ${value}`);
+        if (stat.size > 1024 * 1024)
+            throw new Error(`Action input file exceeds size limit for ${flag}: ${value}`);
+        let readError = null;
+        const parsed = readJsonSafe(filePath, null, { onError: (error) => { readError = error; } });
+        if (!isRecord(parsed))
+            throw new Error(`Invalid action JSON input ${flag}: ${errorMessage(readError)}`);
+        return parsed;
+    }
+    throw new Error(`Unsupported action input type for ${flag}: ${declaration.type}`);
+}
+function taskPathContext(target, taskDir) {
+    const dir = toPosix(path.relative(target.projectRoot, taskDir));
+    return {
+        dir,
+        taskPlan: toPosix(path.join(dir, "task_plan.md")),
+        progress: toPosix(path.join(dir, "progress.md")),
+        artifacts: toPosix(path.join(dir, "artifacts")),
+        artifactsIndex: toPosix(path.join(dir, "artifacts/INDEX.md")),
+        visualMap: toPosix(path.join(dir, "visual_map.md")),
+    };
+}
+function resolveActionScopes(scopes, { target, taskPaths, label }) {
+    return (scopes || []).map((scope) => {
+        const rendered = renderHarnessTemplate(String(scope || ""), { paths: harnessPathContext(target), task: { paths: taskPaths } }, { strict: true });
+        const normalized = toPosix(path.normalize(rendered));
+        if (!rendered.trim() || path.isAbsolute(rendered) || normalized === "." || normalized === ".." || normalized.startsWith("../") || normalized.includes("/../")) {
+            throw new Error(`${label} escapes target root: ${scope}`);
+        }
+        return normalized;
+    });
+}
+function concreteActionWriteScopes(scopes) {
+    return scopes.filter((scope) => !scope.endsWith("/**"));
+}
+function presetScriptEnv(contextPath) {
+    const env = { HARNESS_PRESET_CONTEXT: contextPath };
+    for (const key of ["PATH", "TMPDIR", "TEMP", "TMP", "SystemRoot", "ComSpec"]) {
+        if (process.env[key])
+            env[key] = process.env[key];
+    }
+    return env;
+}
+function normalizeTargetRelativePath(value, label) {
+    const raw = String(value || "").replace(/^TARGET:/, "").replace(/^\/+/, "").trim();
+    if (!raw)
+        return "";
+    const normalized = toPosix(path.normalize(raw));
+    if (path.isAbsolute(raw) || normalized === "." || normalized === ".." || normalized.startsWith("../") || normalized.includes("/../")) {
+        throw new Error(`${label} escapes target root: ${raw}`);
+    }
+    return normalized;
+}
+function boundedScriptOutput(output) {
+    const redacted = String(output || "")
+        .replace(/(api[_-]?key|token|secret|password)=\S+/gi, "$1=[redacted]")
+        .replace(/\/Users\/[^/\s]+/g, "/Users/[redacted]");
+    return redacted.length > 4096 ? `${redacted.slice(0, 4096)}\n[output truncated]` : redacted;
+}
+function readMaterializationManifest(manifestPath) {
+    if (!fs.existsSync(manifestPath))
+        throw new Error("Preset entrypoint did not emit materialization manifest");
+    const manifest = readJsonSafe(manifestPath, null);
+    if (!isRecord(manifest))
+        throw new Error("Invalid preset materialization manifest");
+    if (manifest.schemaVersion !== materializationSchemaVersion)
+        throw new Error(`Invalid preset materialization schema: ${manifest.schemaVersion || "(missing)"}`);
+    if (!Array.isArray(manifest.writes))
+        throw new Error("Preset materialization manifest writes must be an array");
+    if (manifest.writes.length > maxMaterializedWrites)
+        throw new Error(`Preset materialization manifest has too many writes: ${manifest.writes.length}`);
+    return {
+        schemaVersion: String(manifest.schemaVersion),
+        writes: manifest.writes.map((write) => asRecord(write)),
+        status: manifest.status === undefined ? undefined : String(manifest.status),
+        publicRedactionReport: isRecord(manifest.publicRedactionReport) ? { source: String(manifest.publicRedactionReport.source || "") } : undefined,
+    };
+}
+function validateMaterializationManifest(preset, entrypoint, manifest, { outputRoot, target, entrypointName }) {
+    const targetRoot = target.projectRoot;
+    const seenDestinations = new Set();
+    const writes = manifest.writes.map((write, index) => {
+        const source = normalizeManifestRelativePath(write.source, "Manifest source");
+        const destination = normalizeManifestRelativePath(write.destination, "Manifest destination");
+        if (seenDestinations.has(destination))
+            throw new Error(`Duplicate materialization destination: ${destination}`);
+        seenDestinations.add(destination);
+        assertEntrypointWriteScope(preset, entrypoint, destination, target, entrypointName);
+        if (entrypointName && preset.actions?.[entrypointName] && isDefaultTaskGovernanceFile(destination)) {
+            throw new Error(`Preset action ${entrypointName} cannot write task governance file by default: ${destination}`);
+        }
+        const sourcePath = path.join(outputRoot, source);
+        assertOutputSource(outputRoot, sourcePath, source);
+        const stat = fs.lstatSync(sourcePath);
+        if (stat.size > maxMaterializedFileBytes)
+            throw new Error(`Manifest source exceeds size limit: ${source}`);
+        assertDestinationParent(targetRoot, destination);
+        return {
+            source,
+            sourcePath,
+            destination,
+            destinationPath: path.join(targetRoot, destination),
+            type: String(write.type || "text"),
+            visibility: String(write.visibility || ""),
+            sha256: sha256File(sourcePath),
+        };
+    });
+    enforcePublicRedaction(manifest, writes, { outputRoot });
+    return writes;
+}
+function normalizeManifestRelativePath(value, label) {
+    const raw = String(value || "").trim();
+    const normalized = toPosix(path.normalize(raw));
+    if (!raw || path.isAbsolute(raw) || normalized === "." || normalized === ".." || normalized.startsWith("../") || normalized.includes("/../")) {
+        throw new Error(`${label} escapes preset output root: ${raw || "(missing)"}`);
+    }
+    return normalized;
+}
+function assertOutputSource(outputRoot, sourcePath, source) {
+    if (!fs.existsSync(sourcePath))
+        throw new Error(`Manifest source missing: ${source}`);
+    const stat = fs.lstatSync(sourcePath);
+    if (stat.isSymbolicLink())
+        throw new Error(`Manifest source must not be a symlink: ${source}`);
+    if (!stat.isFile())
+        throw new Error(`Manifest source must be a file: ${source}`);
+    const realRoot = fs.realpathSync(outputRoot);
+    const realSource = fs.realpathSync(sourcePath);
+    if (!isInside(realRoot, realSource))
+        throw new Error(`Manifest source escapes preset output root: ${source}`);
+}
+function assertDestinationParent(targetRoot, destination) {
+    let parent = path.dirname(path.join(targetRoot, destination));
+    const realTarget = fs.realpathSync(targetRoot);
+    while (!fs.existsSync(parent) && parent !== targetRoot && parent !== path.dirname(parent))
+        parent = path.dirname(parent);
+    if (fs.existsSync(parent)) {
+        const stat = fs.lstatSync(parent);
+        if (stat.isSymbolicLink())
+            throw new Error(`Manifest destination parent must not be a symlink: ${destination}`);
+        const realParent = fs.realpathSync(parent);
+        if (!isInside(realTarget, realParent))
+            throw new Error(`Manifest destination parent escapes target root: ${destination}`);
+    }
+}
+function assertEntrypointWriteScope(preset, entrypoint, destination, target, entrypointName) {
+    assertPresetWriteScope(preset, destination, target);
+    const resolved = resolvePresetScopes(preset, target).entrypoints[entrypointName] || entrypoint.writes;
+    if (!resolved.some((scope) => matchesScope(scope, destination))) {
+        throw new Error(`Preset write scope violation for ${destination}`);
+    }
+}
+function matchesScope(scope, relativePath) {
+    const normalizedScope = toPosix(path.normalize(String(scope || "")));
+    if (normalizedScope.endsWith("/**")) {
+        const prefix = normalizedScope.slice(0, -3);
+        return relativePath === prefix || relativePath.startsWith(`${prefix}/`);
+    }
+    return relativePath === normalizedScope;
+}
+function isDefaultTaskGovernanceFile(destination) {
+    return /(^|\/)(review|brief|task_plan)\.md$/.test(destination);
+}
+function enforcePublicRedaction(manifest, writes, { outputRoot }) {
+    const publicWrites = writes.filter((write) => write.visibility === "public" || write.destination.startsWith("docs-release/"));
+    if (publicWrites.length === 0)
+        return;
+    const reportSource = normalizeManifestRelativePath(manifest.publicRedactionReport?.source || "", "Public redaction report source");
+    const reportPath = path.join(outputRoot, reportSource);
+    assertOutputSource(outputRoot, reportPath, reportSource);
+    const report = asRecord(readJsonSafe(reportPath, null));
+    if (report.status !== "pass")
+        throw new Error("Public materialization requires a passing public redaction report");
+}
+function materializeWrites(targetRoot, writes) {
+    const backups = [];
+    try {
+        for (const write of writes) {
+            const destinationPath = write.destinationPath;
+            fs.mkdirSync(path.dirname(destinationPath), { recursive: true });
+            const existed = fs.existsSync(destinationPath);
+            const backupPath = existed ? `${destinationPath}.backup-${process.pid}-${crypto.randomBytes(4).toString("hex")}` : "";
+            if (existed) {
+                fs.copyFileSync(destinationPath, backupPath);
+                backups.push({ destinationPath, backupPath, existed });
+            }
+            else {
+                backups.push({ destinationPath, backupPath: "", existed });
+            }
+            const tempPath = `${destinationPath}.tmp-${process.pid}-${crypto.randomBytes(4).toString("hex")}`;
+            fs.copyFileSync(write.sourcePath, tempPath);
+            fs.renameSync(tempPath, destinationPath);
+        }
+        for (const backup of backups) {
+            if (backup.backupPath)
+                fs.rmSync(backup.backupPath, { force: true });
+        }
+    }
+    catch (error) {
+        for (const backup of backups.reverse()) {
+            try {
+                if (backup.existed && backup.backupPath && fs.existsSync(backup.backupPath))
+                    fs.renameSync(backup.backupPath, backup.destinationPath);
+                else if (!backup.existed)
+                    fs.rmSync(backup.destinationPath, { force: true });
+            }
+            catch {
+                // Preserve the original materialization failure.
+            }
+        }
+        throw error;
+    }
+}
+function targetSnapshot(root) {
+    const entries = new Map();
+    for (const filePath of walkFiles(root)) {
+        const relative = toPosix(path.relative(root, filePath));
+        if (relative.startsWith(".harness/locks/"))
+            continue;
+        const stat = fs.lstatSync(filePath);
+        entries.set(relative, `${stat.size}:${sha256File(filePath)}`);
+    }
+    return entries;
+}
+function assertSnapshotsEqual(before, after, message) {
+    const changed = [];
+    const paths = new Set([...before.keys(), ...after.keys()]);
+    for (const item of paths) {
+        if (before.get(item) !== after.get(item))
+            changed.push(item);
+    }
+    if (changed.length)
+        throw new Error(`${message}: ${changed.slice(0, 12).join(", ")}`);
+}
+function sha256File(filePath) {
+    return crypto.createHash("sha256").update(fs.readFileSync(filePath)).digest("hex");
+}
+function isInside(root, candidate) {
+    const relative = path.relative(root, candidate);
+    return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function asRecord(value) {
+    return isRecord(value) ? value : {};
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}