engineering-behavior-observatory 0.2.1

package/dist/src/workspaces.js

@@ -0,0 +1,1314 @@
+import { createHash, randomUUID } from "node:crypto";
+import { spawn as spawnProcess } from "node:child_process";
+import { closeSync, chmodSync, constants, fchmodSync, fsyncSync, fstatSync, futimesSync, lstatSync, mkdtempSync, mkdirSync, openSync, opendirSync, renameSync, rmdirSync, readSync, rmSync, realpathSync, unlinkSync, writeSync, } from "node:fs";
+import { lstat, realpath } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { basename, dirname, isAbsolute, join, parse, relative, resolve, sep } from "node:path";
+import { isSafeArtifactRelativePath, readTaskArchive, resolveTaskArchive, } from "./contracts.js";
+import { assertTaskPacketAdmitted, statusTaskPacket } from "./task-packets.js";
+const ATTEMPT_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const DIRECTORY_MODE = 0o700;
+const FILE_MODE = 0o600;
+const EPOCH_SECONDS = 0;
+/**
+ * Materialize one admitted, frozen task packet into an isolated attempt path.
+ * Only selected regular files and directories from the verified archive enter
+ * the workspace; restricted packet components never do.
+ */
+export async function materializeWorkspace(options) {
+    const attemptId = options.attemptId ?? randomUUID();
+    assertAttemptId(attemptId);
+    const freeze = statusTaskPacket(options.bundleRoot, options.packetLocator, options.freezeLocator);
+    if (freeze.status !== "frozen") {
+        throw new Error(`Task packet "${options.packetLocator}" is not frozen (${freeze.status}).`);
+    }
+    if (freeze.packetDigest === null)
+        throw new Error("Frozen task packet is missing its packet digest.");
+    const inspection = assertTaskPacketAdmitted(options.bundleRoot, options.packetLocator);
+    const packet = inspection.packet;
+    if (inspection.packetDigest === null || !sameDigest(inspection.packetDigest, freeze.packetDigest)) {
+        throw new Error(`Frozen task packet "${options.packetLocator}" changed before materialization.`);
+    }
+    const source = packet.agentInput.fixture.source;
+    const archive = resolveTaskArchive(options.bundleRoot, source, source.limits.maxCompressedBytes);
+    const entries = readTaskArchive(archive, source.limits, packet.agentInput.fixture.materializer.includePaths);
+    assertModelVisibleEntries(entries);
+    assertFrozenSnapshot(options, freeze.packetDigest, freeze.aggregateDigest);
+    const bundleRoot = await realpath(options.bundleRoot);
+    const parent = await prepareWorkspaceParent(options.workspaceParent ?? options.workspaceRoot ?? tmpdir(), bundleRoot);
+    const createdWorkspace = createWorkspace(parent, attemptId);
+    let workspacePath = createdWorkspace.path;
+    if (!isDisjoint(bundleRoot, workspacePath)) {
+        closeSync(createdWorkspace.descriptor);
+        removeWorkspaceIfOwned(workspacePath, createdWorkspace.identity);
+        throw new Error("Workspace and task-bundle roots must be separate.");
+    }
+    const retainOnFailure = options.retainOnFailure === true;
+    let workspaceIdentity = createdWorkspace.identity;
+    let result;
+    try {
+        materializeEntries(workspacePath, workspaceIdentity, entries, createdWorkspace.descriptor);
+        workspacePath = sealWorkspace(workspacePath, join(parent.path, `.ebo-${attemptId}-sealed-${randomUUID()}`), workspaceIdentity);
+        await runSetup(options.setup, options.setupSteps, workspacePath);
+        normalizeWorkspace(workspacePath, workspaceIdentity, createdWorkspace.descriptor);
+        assertWorkspaceRoot(workspacePath, workspaceIdentity);
+        const workspaceFingerprint = digestMaterializedWorkspace(workspacePath, workspaceIdentity);
+        assertWorkspaceRoot(workspacePath, workspaceIdentity);
+        const settledFingerprint = digestMaterializedWorkspace(workspacePath, workspaceIdentity);
+        if (workspaceFingerprint !== settledFingerprint) {
+            throw new Error("Workspace changed while its final fingerprint was settling.");
+        }
+        result = createResult({
+            attemptId,
+            packet,
+            packetDigest: freeze.packetDigest,
+            sourceDigest: source.digest,
+            workspacePath,
+            workspaceIdentity,
+            workspaceFingerprint,
+            retainOnFailure,
+            retained: true,
+            workspaceRemoved: false,
+        });
+        return result;
+    }
+    catch (error) {
+        const message = errorMessage(error);
+        let rootIsSafe = false;
+        if (workspaceIdentity !== undefined) {
+            try {
+                if (await isOwnedWorkspaceRoot(workspacePath, workspaceIdentity)) {
+                    normalizeWorkspace(workspacePath, workspaceIdentity, createdWorkspace.descriptor, true);
+                    rootIsSafe = await isSafeWorkspaceRoot(workspacePath, workspaceIdentity)
+                        && await isSafeWorkspaceTree(workspacePath);
+                }
+            }
+            catch {
+                rootIsSafe = false;
+            }
+        }
+        let workspaceRemoved = false;
+        if (!retainOnFailure || !rootIsSafe) {
+            workspaceRemoved = removeWorkspaceIfOwned(workspacePath, workspaceIdentity);
+        }
+        result = createResult({
+            attemptId,
+            packet,
+            packetDigest: freeze.packetDigest,
+            sourceDigest: source.digest,
+            workspacePath,
+            workspaceIdentity,
+            workspaceFingerprint: null,
+            retainOnFailure,
+            retained: retainOnFailure && rootIsSafe,
+            workspaceRemoved,
+            status: "failed",
+            error: message,
+        });
+        return result;
+    }
+    finally {
+        closeSync(createdWorkspace.descriptor);
+    }
+}
+export async function cleanupWorkspace(materialization, outcome = materialization.state === "failed" ? "failure" : "success") {
+    if (materialization.state === "cleaned")
+        return;
+    if (outcome === "failure" && materialization.retainOnFailure && materialization.retained)
+        return;
+    if (materialization.state === "failed" && !materialization.retained && materialization.workspaceRemoved) {
+        materialization.status = "cleaned";
+        materialization.state = "cleaned";
+        return;
+    }
+    if (!removeWorkspaceIfOwned(materialization.workspacePath, materialization.workspaceIdentity)) {
+        throw new Error("Workspace root changed before cleanup.");
+    }
+    materialization.status = "cleaned";
+    materialization.state = "cleaned";
+    materialization.retained = false;
+    materialization.workspaceRemoved = true;
+}
+function createResult(input) {
+    const result = {
+        attemptId: input.attemptId,
+        packetId: input.packet.id,
+        packetDigest: input.packetDigest,
+        fixtureDigest: input.sourceDigest,
+        startingDigest: input.sourceDigest,
+        workspacePath: input.workspacePath,
+        path: input.workspacePath,
+        ...(input.workspaceIdentity === undefined ? {} : { workspaceIdentity: input.workspaceIdentity }),
+        workspaceFingerprint: input.workspaceFingerprint,
+        workspaceDigest: input.workspaceFingerprint,
+        status: input.status ?? "ready",
+        state: input.status ?? "ready",
+        retainOnFailure: input.retainOnFailure,
+        retained: input.retained,
+        workspaceRemoved: input.workspaceRemoved,
+        ...(input.error === undefined ? {} : { error: input.error }),
+        cleanup: async (outcome) => cleanupWorkspace(result, outcome),
+    };
+    return result;
+}
+async function prepareWorkspaceParent(parent, bundleRoot) {
+    const absolute = await resolveFuturePath(resolve(parent));
+    const created = [];
+    const filesystemRoot = parse(absolute).root;
+    let current = filesystemRoot;
+    try {
+        for (const segment of absolute.slice(filesystemRoot.length).split(sep).filter(Boolean)) {
+            current = join(current, segment);
+            let metadata;
+            try {
+                metadata = await lstat(current);
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+                let createdByThisCall = false;
+                try {
+                    mkdirPrivate(current);
+                    createdByThisCall = true;
+                }
+                catch (mkdirError) {
+                    if (mkdirError.code !== "EEXIST")
+                        throw mkdirError;
+                }
+                metadata = await lstat(current);
+                if (createdByThisCall)
+                    created.push({ path: current, dev: metadata.dev, ino: metadata.ino });
+            }
+            if (!metadata.isDirectory() || metadata.isSymbolicLink()) {
+                throw new Error("Workspace parent cannot cross a symbolic link or non-directory.");
+            }
+            const resolved = await realpath(current);
+            if (resolved !== current || isContained(bundleRoot, resolved)) {
+                throw new Error("Workspace parent must be outside the task-bundle root.");
+            }
+        }
+        const metadata = await lstat(current);
+        return { path: current, dev: metadata.dev, ino: metadata.ino };
+    }
+    catch (error) {
+        for (const entry of created.reverse()) {
+            try {
+                const metadata = await lstat(entry.path);
+                if (metadata.isDirectory() && !metadata.isSymbolicLink()
+                    && metadata.dev === entry.dev && metadata.ino === entry.ino) {
+                    rmdirSync(entry.path);
+                }
+            }
+            catch (cleanupError) {
+                if (cleanupError.code !== "ENOENT")
+                    throw error;
+            }
+        }
+        throw error;
+    }
+}
+async function resolveFuturePath(path) {
+    try {
+        return await realpath(path);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+        const parent = dirname(path);
+        if (parent === path)
+            return path;
+        return resolve(await resolveFuturePath(parent), basename(path));
+    }
+}
+function createWorkspace(parent, attemptId) {
+    const parentFd = openSync(parent.path, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+    const originalCwd = process.cwd();
+    let createdPath;
+    let createdIdentity;
+    let descriptor;
+    try {
+        // This synchronous section has no await points, so concurrent callers cannot
+        // interleave cwd changes while mkdtemp is anchored to parentFd's directory.
+        process.chdir(parent.path);
+        if (!sameIdentity(fstatSync(parentFd), lstatSync("."))) {
+            throw new Error("Workspace parent changed before attempt creation.");
+        }
+        const originalUmask = process.umask(0);
+        try {
+            createdPath = mkdtempSync(`ebo-${attemptId}-`);
+        }
+        finally {
+            process.umask(originalUmask);
+        }
+        if (!sameIdentity(fstatSync(parentFd), lstatSync("."))) {
+            throw new Error("Workspace parent changed during attempt creation.");
+        }
+        descriptor = openSync(createdPath, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+        const metadata = fstatSync(descriptor);
+        const pathMetadata = lstatSync(createdPath);
+        if (!metadata.isDirectory() || metadata.isSymbolicLink()
+            || !sameIdentity(metadata, pathMetadata) || pathMetadata.isSymbolicLink()) {
+            closeSync(descriptor);
+            descriptor = undefined;
+            throw new Error("Workspace root changed during attempt creation.");
+        }
+        createdIdentity = { dev: metadata.dev, ino: metadata.ino };
+        const result = { path: realpathSync(createdPath), identity: createdIdentity, descriptor };
+        descriptor = undefined;
+        return result;
+    }
+    catch (error) {
+        if (descriptor !== undefined)
+            closeSync(descriptor);
+        // There is no descriptor-relative remove API in Node. If adoption failed,
+        // leave the returned pathname untouched rather than risk deleting a raced
+        // replacement; successful lifecycles clean through their retained handle.
+        throw error;
+    }
+    finally {
+        process.chdir(originalCwd);
+        closeSync(parentFd);
+    }
+}
+function mkdirPrivate(path) {
+    const originalUmask = process.umask(0);
+    try {
+        mkdirSync(path, { mode: DIRECTORY_MODE });
+    }
+    finally {
+        process.umask(originalUmask);
+    }
+}
+function materializeEntries(root, expectedIdentity, entries, verifiedFd) {
+    const originalCwd = process.cwd();
+    const rootFd = verifiedFd
+        ?? openSync(root, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+    try {
+        if (!sameIdentity(fstatSync(rootFd), expectedIdentity))
+            throw new Error("Workspace root changed before extraction.");
+        // Keep extraction synchronous. Relative opens stay anchored to the
+        // verified root directory descriptor, and concurrent materializers cannot
+        // interleave this short process-global cwd section.
+        process.chdir(root);
+        const cwdFd = openSync(".", constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+        try {
+            if (!sameIdentity(fstatSync(cwdFd), expectedIdentity)) {
+                throw new Error("Workspace root changed before extraction.");
+            }
+            for (const entry of entries)
+                materializeEntryFromCwd(root, entry);
+        }
+        finally {
+            closeSync(cwdFd);
+        }
+    }
+    finally {
+        process.chdir(originalCwd);
+        if (verifiedFd === undefined)
+            closeSync(rootFd);
+    }
+}
+function materializeEntryFromCwd(root, entry) {
+    const entryPath = entry.kind === "directory" ? entry.path.replace(/\/+$/, "") : entry.path;
+    assertSafeWorkspacePath(root, entryPath);
+    const parts = entryPath.split("/");
+    const directoryParts = entry.kind === "directory" ? parts : parts.slice(0, -1);
+    for (const segment of directoryParts)
+        enterMaterializationDirectory(root, segment);
+    try {
+        if (entry.kind === "directory")
+            return;
+        if (entry.kind !== "file")
+            throw new Error(`Archive entry "${entry.path}" is unsafe.`);
+        const name = parts.at(-1);
+        if (name === undefined || name.length === 0)
+            throw new Error(`Archive entry "${entry.path}" is unsafe.`);
+        const mode = normalizedFileMode(entry.mode);
+        const fileFd = openSync(name, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, mode);
+        try {
+            for (let offset = 0; offset < entry.bytes.length;) {
+                const written = writeSync(fileFd, entry.bytes, offset, entry.bytes.length - offset);
+                if (written <= 0)
+                    throw new Error(`Archive entry "${entry.path}" could not be written.`);
+                offset += written;
+            }
+            fsyncSync(fileFd);
+            fchmodSync(fileFd, mode);
+        }
+        finally {
+            closeSync(fileFd);
+        }
+    }
+    finally {
+        for (let index = directoryParts.length - 1; index >= 0; index -= 1)
+            process.chdir("..");
+    }
+}
+function enterMaterializationDirectory(root, segment) {
+    if (!isSafeArtifactRelativePath(segment))
+        throw new Error(`Workspace path "${segment}" is unsafe.`);
+    let metadata;
+    try {
+        metadata = lstatSync(segment);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+        mkdirPrivate(segment);
+        metadata = lstatSync(segment);
+    }
+    if (!metadata.isDirectory() || metadata.isSymbolicLink()) {
+        throw new Error(`Workspace destination "${segment}" crosses a symbolic link.`);
+    }
+    const childFd = openSync(segment, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+    try {
+        const childIdentity = fstatSync(childFd);
+        if (!sameIdentity(metadata, childIdentity))
+            throw new Error(`Workspace directory "${segment}" changed during extraction.`);
+        const alias = `.ebo-materialize-${randomUUID()}`;
+        try {
+            lstatSync(alias);
+            throw new Error(`Workspace extraction alias already exists: "${alias}".`);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+        renameSync(segment, alias);
+        let moved = true;
+        try {
+            if (!sameIdentity(childIdentity, lstatSync(alias))) {
+                throw new Error(`Workspace directory "${segment}" changed during extraction.`);
+            }
+            process.chdir(alias);
+            const enteredFd = openSync(".", constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+            try {
+                if (!sameIdentity(childIdentity, fstatSync(enteredFd)) || !isContained(root, realpathSync("."))) {
+                    throw new Error(`Workspace directory "${segment}" changed during extraction.`);
+                }
+            }
+            finally {
+                closeSync(enteredFd);
+            }
+            let destinationAbsent = false;
+            try {
+                lstatSync(join("..", segment));
+            }
+            catch (error) {
+                if (error.code === "ENOENT")
+                    destinationAbsent = true;
+                else
+                    throw error;
+            }
+            if (!destinationAbsent)
+                throw new Error(`Workspace destination "${segment}" changed during extraction.`);
+            renameSync(join("..", alias), join("..", segment));
+            moved = false;
+        }
+        finally {
+            if (moved) {
+                try {
+                    if (sameIdentity(childIdentity, lstatSync(join("..", alias)))) {
+                        let destinationAbsent = false;
+                        try {
+                            lstatSync(join("..", segment));
+                        }
+                        catch (error) {
+                            if (error.code === "ENOENT")
+                                destinationAbsent = true;
+                            else
+                                throw error;
+                        }
+                        if (destinationAbsent)
+                            renameSync(join("..", alias), join("..", segment));
+                    }
+                }
+                catch {
+                    // The caller will fail closed and remove only the original root.
+                }
+            }
+        }
+    }
+    finally {
+        closeSync(childFd);
+    }
+}
+function sealWorkspace(path, destination, expected) {
+    const current = lstatSync(path);
+    if (!current.isDirectory() || current.isSymbolicLink() || !sameIdentity(current, expected)) {
+        throw new Error("Workspace root changed before sealing.");
+    }
+    renameSync(path, destination);
+    try {
+        const sealed = lstatSync(destination);
+        if (!sealed.isDirectory() || sealed.isSymbolicLink() || !sameIdentity(sealed, expected)) {
+            if (sealed.isSymbolicLink())
+                rmSync(destination, { force: true });
+            throw new Error("Workspace root changed during sealing.");
+        }
+        return realpathSync(destination);
+    }
+    catch (error) {
+        if (error.code === "ENOENT") {
+            throw new Error("Workspace root disappeared during sealing.");
+        }
+        throw error;
+    }
+}
+function normalizeWorkspace(root, expectedIdentity, verifiedFd, preserveTimestamps = false) {
+    assertWorkspaceRoot(root, expectedIdentity);
+    try {
+        normalizeDirectory(root, root, "", verifiedFd, preserveTimestamps);
+    }
+    catch (error) {
+        if (error.code !== "EACCES")
+            throw error;
+        if (verifiedFd === undefined)
+            normalizeUnreadableDirectory(root, expectedIdentity);
+        else
+            fchmodSync(verifiedFd, DIRECTORY_MODE);
+        normalizeDirectory(root, root, "", verifiedFd, preserveTimestamps);
+    }
+    assertWorkspaceRoot(root, expectedIdentity);
+}
+function normalizeDirectory(root, directory, relativeDirectory, verifiedFd, preserveTimestamps = false) {
+    const directoryFd = verifiedFd
+        ?? openSync(directory, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+    const ownsFd = verifiedFd === undefined;
+    try {
+        assertContainedRealpathSync(root, directory);
+        if (!sameIdentity(fstatSync(directoryFd), lstatSync(directory))) {
+            throw new Error(`Workspace directory "${relativeDirectory}" changed during materialization.`);
+        }
+        fchmodSync(directoryFd, DIRECTORY_MODE);
+        const entries = readDirectoryEntries(directory, directoryFd, preserveTimestamps);
+        entries.sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0);
+        for (const entry of entries) {
+            const path = join(directory, entry.name);
+            const relativePath = relativeDirectory === "" ? entry.name : `${relativeDirectory}/${entry.name}`;
+            if (relativePath.split("/", 1)[0]?.toLowerCase() === "restricted") {
+                throw new Error(`Restricted packet content cannot enter the workspace: "${relativePath}".`);
+            }
+            const current = lstatSync(path);
+            const childFd = openChildSync(path, entry.isDirectory(), current.isDirectory() ? DIRECTORY_MODE : normalizedFileMode(current.mode));
+            try {
+                const metadata = fstatSync(childFd);
+                assertContainedRealpathSync(root, path);
+                if (current.isSymbolicLink() || !sameIdentity(metadata, current)) {
+                    throw new Error(`Workspace entry "${relativePath}" changed during materialization.`);
+                }
+                if (metadata.isDirectory()) {
+                    normalizeDirectory(root, path, relativePath, childFd, preserveTimestamps);
+                    fchmodSync(childFd, DIRECTORY_MODE);
+                    if (!preserveTimestamps)
+                        futimesSync(childFd, EPOCH_SECONDS, EPOCH_SECONDS);
+                }
+                else if (metadata.isFile()) {
+                    if (metadata.nlink > 1)
+                        throw new Error(`Workspace contains a hard-linked file at "${relativePath}".`);
+                    fchmodSync(childFd, normalizedFileMode(metadata.mode));
+                    if (!preserveTimestamps)
+                        futimesSync(childFd, EPOCH_SECONDS, EPOCH_SECONDS);
+                }
+                else {
+                    throw new Error(`Workspace contains an unsupported entry at "${relativePath}".`);
+                }
+                const completed = fstatSync(childFd);
+                const finalPath = lstatSync(path);
+                if (!sameIdentity(metadata, completed) || !sameIdentity(metadata, finalPath)
+                    || finalPath.isSymbolicLink()) {
+                    throw new Error(`Workspace entry "${relativePath}" changed during materialization.`);
+                }
+            }
+            finally {
+                closeSync(childFd);
+            }
+        }
+        fchmodSync(directoryFd, DIRECTORY_MODE);
+        if (!preserveTimestamps)
+            futimesSync(directoryFd, EPOCH_SECONDS, EPOCH_SECONDS);
+    }
+    finally {
+        if (ownsFd)
+            closeSync(directoryFd);
+    }
+}
+function openChildSync(path, directory, normalizeMode) {
+    const current = lstatSync(path);
+    if (current.isSymbolicLink())
+        throw new Error(`Workspace contains a symbolic link at "${path}".`);
+    if (!current.isDirectory() && !current.isFile()) {
+        throw new Error(`Workspace contains an unsupported entry at "${path}".`);
+    }
+    try {
+        return openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK | (directory ? constants.O_DIRECTORY : 0));
+    }
+    catch (error) {
+        if (error.code === "ELOOP") {
+            throw new Error(`Workspace contains a symbolic link at "${path}".`);
+        }
+        if (error.code === "EACCES" && normalizeMode !== undefined) {
+            return normalizeUnreadableChild(path, directory, current, normalizeMode);
+        }
+        throw error;
+    }
+}
+function normalizeUnreadableDirectory(path, expected) {
+    const parent = dirname(path);
+    const name = basename(path);
+    const alias = `.ebo-root-normalize-${randomUUID()}`;
+    const originalCwd = process.cwd();
+    const parentFd = openSync(parent, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+    let moved = false;
+    try {
+        if (!sameIdentity(fstatSync(parentFd), lstatSync(parent))) {
+            throw new Error(`Workspace parent "${parent}" changed during normalization.`);
+        }
+        process.chdir(parent);
+        if (!sameIdentity(fstatSync(parentFd), lstatSync("."))) {
+            throw new Error(`Workspace parent "${parent}" changed during normalization.`);
+        }
+        try {
+            lstatSync(alias);
+            throw new Error(`Workspace normalization alias already exists: "${alias}".`);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+        renameSync(name, alias);
+        moved = true;
+        const movedMetadata = lstatSync(alias);
+        if (!movedMetadata.isDirectory() || movedMetadata.isSymbolicLink() || !sameIdentity(movedMetadata, expected)) {
+            throw new Error(`Workspace root changed during normalization.`);
+        }
+        chmodSync(alias, DIRECTORY_MODE);
+        const opened = openSync(alias, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+        try {
+            if (!sameIdentity(fstatSync(opened), expected))
+                throw new Error(`Workspace root changed during normalization.`);
+        }
+        finally {
+            closeSync(opened);
+        }
+        renameSync(alias, name);
+        moved = false;
+        const restored = lstatSync(name);
+        if (!restored.isDirectory() || restored.isSymbolicLink() || !sameIdentity(restored, expected)) {
+            throw new Error(`Workspace root changed during normalization.`);
+        }
+    }
+    finally {
+        if (moved) {
+            try {
+                if (sameIdentity(lstatSync(alias), expected)) {
+                    let destinationAbsent = false;
+                    try {
+                        lstatSync(name);
+                    }
+                    catch (error) {
+                        if (error.code === "ENOENT")
+                            destinationAbsent = true;
+                        else
+                            throw error;
+                    }
+                    if (destinationAbsent)
+                        renameSync(alias, name);
+                }
+            }
+            catch {
+                // Preserve the original failure and let the root cleanup gate decide.
+            }
+        }
+        process.chdir(originalCwd);
+        closeSync(parentFd);
+    }
+}
+function normalizeUnreadableChild(path, directory, expected, mode) {
+    const parent = dirname(path);
+    const name = basename(path);
+    const alias = `.ebo-normalize-${randomUUID()}`;
+    const originalCwd = process.cwd();
+    const parentFd = openSync(parent, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+    let moved = false;
+    let childFd;
+    try {
+        if (!sameIdentity(fstatSync(parentFd), lstatSync(parent))) {
+            throw new Error(`Workspace parent "${parent}" changed during normalization.`);
+        }
+        // This synchronous section keeps relative rename/chmod/open operations
+        // on the verified parent descriptor without allowing concurrent JS calls
+        // to interleave the process-global cwd.
+        process.chdir(parent);
+        if (!sameIdentity(fstatSync(parentFd), lstatSync("."))) {
+            throw new Error(`Workspace parent "${parent}" changed during normalization.`);
+        }
+        try {
+            lstatSync(alias);
+            throw new Error(`Workspace normalization alias already exists: "${alias}".`);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+        renameSync(name, alias);
+        moved = true;
+        const movedMetadata = lstatSync(alias);
+        if (movedMetadata.isSymbolicLink() || !sameIdentity(movedMetadata, expected)) {
+            throw new Error(`Workspace entry "${path}" changed during normalization.`);
+        }
+        chmodSync(alias, mode);
+        childFd = openSync(alias, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK | (directory ? constants.O_DIRECTORY : 0));
+        const opened = fstatSync(childFd);
+        if (!sameIdentity(opened, expected))
+            throw new Error(`Workspace entry "${path}" changed during normalization.`);
+        renameSync(alias, name);
+        moved = false;
+        const restored = lstatSync(name);
+        if (restored.isSymbolicLink() || !sameIdentity(restored, expected)) {
+            throw new Error(`Workspace entry "${path}" changed during normalization.`);
+        }
+        const result = childFd;
+        childFd = undefined;
+        return result;
+    }
+    finally {
+        if (childFd !== undefined)
+            closeSync(childFd);
+        if (moved) {
+            try {
+                const current = lstatSync(alias);
+                if (sameIdentity(current, expected)) {
+                    let destinationAbsent = false;
+                    try {
+                        lstatSync(name);
+                    }
+                    catch (error) {
+                        if (error.code === "ENOENT")
+                            destinationAbsent = true;
+                        else
+                            throw error;
+                    }
+                    if (destinationAbsent)
+                        renameSync(alias, name);
+                }
+            }
+            catch {
+                // Preserve the original failure and let the root-level cleanup gate
+                // decide whether the partial tree is still safe to retain.
+            }
+        }
+        process.chdir(originalCwd);
+        closeSync(parentFd);
+    }
+}
+function readDirectoryEntries(directory, directoryFd, preserveTimestamps = false) {
+    const alias = join(dirname(directory), `.ebo-enumeration-${randomUUID()}`);
+    let moved = false;
+    let handle;
+    let expected;
+    let parentFd;
+    let parentExpected;
+    try {
+        expected = fstatSync(directoryFd);
+        if (!sameIdentity(expected, lstatSync(directory))) {
+            throw new Error(`Workspace directory "${directory}" changed during traversal.`);
+        }
+        parentFd = openSync(dirname(directory), constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+        parentExpected = fstatSync(parentFd);
+        if (!sameIdentity(parentExpected, lstatSync(dirname(directory)))) {
+            throw new Error(`Workspace parent "${dirname(directory)}" changed during traversal.`);
+        }
+        // Node's public Dir API does not expose its descriptor. Temporarily move
+        // the already-verified inode to a private, unique pathname so opendirSync
+        // opens that inode, then restore the public path while retaining the
+        // handle. A raced replacement makes restoration or identity validation
+        // fail closed instead of enumerating an unbound pathname.
+        try {
+            lstatSync(alias);
+            throw new Error(`Workspace enumeration alias already exists: "${alias}".`);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+        renameSync(directory, alias);
+        moved = true;
+        if (!sameIdentity(expected, lstatSync(alias))) {
+            throw new Error(`Workspace directory "${directory}" changed during traversal.`);
+        }
+        handle = opendirSync(alias);
+        if (!sameIdentity(expected, lstatSync(alias))) {
+            throw new Error(`Workspace directory "${directory}" changed during traversal.`);
+        }
+        renameSync(alias, directory);
+        moved = false;
+        // Renaming a child updates the parent directory's mtime. Restore the
+        // opened directory's timestamp so the operation stays digest-neutral.
+        const directoryAtime = preserveTimestamps ? expected.atimeMs / 1000 : expected.atime;
+        const directoryMtime = preserveTimestamps ? expected.mtimeMs / 1000 : expected.mtime;
+        futimesSync(directoryFd, directoryAtime, directoryMtime);
+        if (parentFd !== undefined && parentExpected !== undefined) {
+            const parentAtime = preserveTimestamps ? parentExpected.atimeMs / 1000 : parentExpected.atime;
+            const parentMtime = preserveTimestamps ? parentExpected.mtimeMs / 1000 : parentExpected.mtime;
+            futimesSync(parentFd, parentAtime, parentMtime);
+        }
+        if (!sameIdentity(expected, lstatSync(directory))) {
+            throw new Error(`Workspace directory "${directory}" changed during traversal.`);
+        }
+        const entries = [];
+        for (let entry = handle.readSync(); entry !== null; entry = handle.readSync()) {
+            if (!sameIdentity(expected, fstatSync(directoryFd)) || !sameIdentity(expected, lstatSync(directory))) {
+                throw new Error(`Workspace directory "${directory}" changed during traversal.`);
+            }
+            entries.push(entry);
+        }
+        if (!sameIdentity(expected, fstatSync(directoryFd)) || !sameIdentity(expected, lstatSync(directory))) {
+            throw new Error(`Workspace directory "${directory}" changed during traversal.`);
+        }
+        return entries;
+    }
+    finally {
+        handle?.closeSync();
+        if (moved) {
+            let aliasIsOwned = false;
+            try {
+                aliasIsOwned = expected !== undefined && sameIdentity(expected, lstatSync(alias));
+            }
+            catch {
+                aliasIsOwned = false;
+            }
+            if (aliasIsOwned) {
+                let destinationAbsent = false;
+                try {
+                    lstatSync(directory);
+                }
+                catch (error) {
+                    if (error.code === "ENOENT")
+                        destinationAbsent = true;
+                    else
+                        throw error;
+                }
+                if (destinationAbsent) {
+                    try {
+                        renameSync(alias, directory);
+                    }
+                    catch {
+                        if (expected !== undefined) {
+                            removeWorkspaceIfOwned(alias, { dev: Number(expected.dev), ino: Number(expected.ino) });
+                        }
+                    }
+                }
+                else if (expected !== undefined) {
+                    // Do not overwrite a raced replacement at the public path.
+                    removeWorkspaceIfOwned(alias, { dev: Number(expected.dev), ino: Number(expected.ino) });
+                }
+            }
+        }
+        if (parentFd !== undefined)
+            closeSync(parentFd);
+    }
+}
+function assertContainedRealpathSync(root, path) {
+    const resolved = realpathSync(path);
+    if (resolved !== path || !isContained(root, resolved)) {
+        throw new Error(`Workspace path "${path}" escapes its root.`);
+    }
+}
+function digestMaterializedWorkspace(root, expectedIdentity) {
+    const hash = createHash("sha256");
+    const rootFd = openSync(root, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+    try {
+        const metadata = fstatSync(rootFd, { bigint: true });
+        assertWorkspaceRoot(root, expectedIdentity);
+        assertContainedRealpathSync(root, root);
+        if (!metadata.isDirectory() || metadata.isSymbolicLink())
+            throw new Error("Workspace root is not a directory.");
+        hash.update("ebo.workspace/v1\0");
+        hash.update(`root\0${metadata.mode & 4095n}\0${workspaceTimestamp(metadata)}\0`);
+        hashWorkspaceDirectory(root, root, "", hash, rootFd);
+    }
+    finally {
+        closeSync(rootFd);
+    }
+    assertWorkspaceRoot(root, expectedIdentity);
+    return `sha256:${hash.digest("hex")}`;
+}
+function hashWorkspaceDirectory(root, directory, relativeDirectory, hash, verifiedFd) {
+    const directoryFd = verifiedFd
+        ?? openSync(directory, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+    const ownsFd = verifiedFd === undefined;
+    try {
+        assertContainedRealpathSync(root, directory);
+        const openedDirectory = fstatSync(directoryFd, { bigint: true });
+        if (!openedDirectory.isDirectory() || openedDirectory.isSymbolicLink()) {
+            throw new Error(`Workspace directory "${relativeDirectory}" is unsafe.`);
+        }
+        const entries = readDirectoryEntries(directory, directoryFd);
+        entries.sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0);
+        for (const entry of entries) {
+            const path = join(directory, entry.name);
+            const relativePath = relativeDirectory === "" ? entry.name : `${relativeDirectory}/${entry.name}`;
+            if (relativePath.split("/", 1)[0]?.toLowerCase() === "restricted") {
+                throw new Error(`Restricted packet content cannot enter the workspace: "${relativePath}".`);
+            }
+            const current = lstatSync(path, { bigint: true });
+            const childFd = openChildSync(path, entry.isDirectory());
+            try {
+                const metadata = fstatSync(childFd, { bigint: true });
+                assertContainedRealpathSync(root, path);
+                if (current.isSymbolicLink() || !sameIdentity(metadata, current)) {
+                    throw new Error(`Workspace entry "${relativePath}" changed during fingerprinting.`);
+                }
+                if (metadata.isDirectory()) {
+                    hash.update(`directory\0${relativePath}\0${metadata.mode & 4095n}\0${workspaceTimestamp(metadata)}\0`);
+                    hashWorkspaceDirectory(root, path, relativePath, hash, childFd);
+                }
+                else if (metadata.isFile()) {
+                    if (metadata.nlink > 1n)
+                        throw new Error(`Workspace contains a hard-linked file at "${relativePath}".`);
+                    const size = Number(metadata.size);
+                    if (!Number.isSafeInteger(size) || size < 0)
+                        throw new Error(`Workspace file "${relativePath}" is too large.`);
+                    hash.update(`file\0${relativePath}\0${metadata.mode & 4095n}\0${workspaceTimestamp(metadata)}\0${size}\0`);
+                    const bytes = Buffer.alloc(Math.min(size, 64 * 1024));
+                    for (let offset = 0; offset < size;) {
+                        const read = readSync(childFd, bytes, 0, Math.min(bytes.length, size - offset), offset);
+                        if (read === 0)
+                            throw new Error(`Workspace file "${relativePath}" changed during fingerprinting.`);
+                        hash.update(bytes.subarray(0, read));
+                        offset += read;
+                    }
+                }
+                else {
+                    throw new Error(`Workspace contains an unsupported entry at "${relativePath}".`);
+                }
+                const completed = fstatSync(childFd, { bigint: true });
+                const finalPath = lstatSync(path, { bigint: true });
+                if (!sameIdentity(metadata, completed) || !sameIdentity(metadata, finalPath)
+                    || finalPath.isSymbolicLink() || (metadata.isFile() && !sameFileSnapshot(metadata, completed))) {
+                    throw new Error(`Workspace entry "${relativePath}" changed during fingerprinting.`);
+                }
+            }
+            finally {
+                closeSync(childFd);
+            }
+        }
+    }
+    finally {
+        if (ownsFd)
+            closeSync(directoryFd);
+    }
+}
+async function runSetup(setup, setupSteps, workspacePath) {
+    const steps = setup === undefined ? [] : typeof setup === "function" ? [setup] : [...setup];
+    const allSteps = [...steps, ...(setupSteps ?? [])];
+    if (allSteps.length === 0)
+        return;
+    if (process.platform === "win32")
+        throw new Error("Workspace setup process tracking is unavailable on this platform.");
+    const children = new Map();
+    let spawnError;
+    let contextOpen = true;
+    const context = {
+        spawn(command, args, options) {
+            if (!contextOpen)
+                throw new Error("Workspace setup context is closed.");
+            const child = spawnOwnedProcess(command, args, options);
+            child.once("error", (error) => {
+                spawnError = error instanceof Error ? error : new Error("Workspace setup child failed.");
+            });
+            if (child.pid !== undefined)
+                children.set(child.pid, child);
+            return child;
+        },
+    };
+    let setupFailed = false;
+    let setupFailure;
+    try {
+        for (const step of allSteps) {
+            if (typeof step !== "function")
+                throw new Error("Workspace setup steps must be functions.");
+            await step(workspacePath, context);
+        }
+    }
+    catch (error) {
+        setupFailed = true;
+        setupFailure = error;
+        throw error;
+    }
+    finally {
+        contextOpen = false;
+        try {
+            await new Promise((resolve) => setImmediate(resolve));
+            await reapSetupChildren(children);
+            if (spawnError !== undefined)
+                throw new Error(`Workspace setup child failed: ${spawnError.message}`);
+        }
+        catch (cleanupError) {
+            if (setupFailed) {
+                throw new AggregateError([setupFailure, cleanupError], `Workspace setup failed: ${errorMessage(setupFailure)}; cleanup failed: ${errorMessage(cleanupError)}`);
+            }
+            throw cleanupError;
+        }
+    }
+}
+function spawnOwnedProcess(command, args, options) {
+    const ownedOptions = { ...options, detached: true };
+    return args === undefined
+        ? spawnProcess(command, ownedOptions)
+        : spawnProcess(command, args, ownedOptions);
+}
+async function reapSetupChildren(children) {
+    const waits = [];
+    for (const [pid, child] of children) {
+        try {
+            // A detached child is the leader of its own process group. Killing the
+            // group also covers descendants that outlive their direct parent.
+            process.kill(-pid, "SIGKILL");
+        }
+        catch {
+            // The setup child may have exited between the process snapshot and kill.
+        }
+        waits.push(waitForChildExit(child).then(() => waitForProcessGroupExit(pid)));
+    }
+    await Promise.all(waits);
+}
+function waitForChildExit(child) {
+    if (child.exitCode !== null || child.signalCode !== null)
+        return Promise.resolve();
+    return new Promise((resolve) => child.once("close", () => resolve()));
+}
+async function waitForProcessGroupExit(pid) {
+    for (let attempt = 0; attempt < 100; attempt += 1) {
+        try {
+            process.kill(-pid, 0);
+        }
+        catch (error) {
+            if (error.code === "ESRCH")
+                return;
+            throw error;
+        }
+        await new Promise((resolve) => setTimeout(resolve, 10));
+    }
+    throw new Error("Workspace setup process group did not terminate.");
+}
+function assertModelVisibleEntries(entries) {
+    for (const entry of entries) {
+        const first = entry.path.split("/", 1)[0]?.toLowerCase();
+        if (first === "restricted") {
+            throw new Error(`Restricted packet content cannot enter the workspace: "${entry.path}".`);
+        }
+    }
+}
+function assertSafeWorkspacePath(root, relativePath) {
+    if (relativePath === ".")
+        return;
+    if (!isSafeArtifactRelativePath(relativePath))
+        throw new Error(`Workspace path "${relativePath}" is unsafe.`);
+    const destination = resolve(root, relativePath);
+    if (!isContained(root, destination))
+        throw new Error(`Workspace path "${relativePath}" escapes its root.`);
+}
+async function isOwnedWorkspaceRoot(path, expected) {
+    try {
+        const metadata = await lstat(path);
+        return metadata.isDirectory() && !metadata.isSymbolicLink()
+            && metadata.dev === expected.dev && metadata.ino === expected.ino
+            && (await realpath(path)) === path;
+    }
+    catch {
+        return false;
+    }
+}
+async function isSafeWorkspaceRoot(path, expected) {
+    try {
+        const metadata = await lstat(path);
+        return metadata.isDirectory() && !metadata.isSymbolicLink()
+            && (metadata.mode & 0o7777) === DIRECTORY_MODE
+            && metadata.dev === expected.dev && metadata.ino === expected.ino
+            && (await realpath(path)) === path;
+    }
+    catch {
+        return false;
+    }
+}
+function isSafeWorkspaceTree(directory, relativeDirectory = "", root = directory, verifiedFd) {
+    let directoryFd;
+    try {
+        directoryFd = verifiedFd
+            ?? openSync(directory, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+    }
+    catch {
+        return false;
+    }
+    const ownsFd = verifiedFd === undefined;
+    try {
+        assertContainedRealpathSync(root, directory);
+        const directoryMetadata = fstatSync(directoryFd);
+        if (!directoryMetadata.isDirectory() || directoryMetadata.isSymbolicLink())
+            return false;
+        for (const entry of readDirectoryEntries(directory, directoryFd)) {
+            const path = join(directory, entry.name);
+            const relativePath = relativeDirectory === "" ? entry.name : `${relativeDirectory}/${entry.name}`;
+            if (relativePath.split("/", 1)[0]?.toLowerCase() === "restricted")
+                return false;
+            const current = lstatSync(path);
+            const childFd = openChildSync(path, entry.isDirectory());
+            try {
+                const metadata = fstatSync(childFd);
+                assertContainedRealpathSync(root, path);
+                if (current.isSymbolicLink() || !sameIdentity(metadata, current))
+                    return false;
+                if (metadata.isDirectory()) {
+                    if ((metadata.mode & 0o7777) !== DIRECTORY_MODE
+                        || !isSafeWorkspaceTree(path, relativePath, root, childFd))
+                        return false;
+                }
+                else if (!metadata.isFile() || metadata.nlink > 1
+                    || (metadata.mode & 0o7777) !== normalizedFileMode(metadata.mode)) {
+                    return false;
+                }
+            }
+            finally {
+                closeSync(childFd);
+            }
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        if (ownsFd)
+            closeSync(directoryFd);
+    }
+}
+function removeWorkspaceIfOwned(path, expected) {
+    try {
+        const metadata = lstatSync(path);
+        if (metadata.isSymbolicLink())
+            return false;
+        if (expected === undefined || !metadata.isDirectory()
+            || metadata.dev !== expected.dev || metadata.ino !== expected.ino)
+            return false;
+        const parent = dirname(path);
+        const quarantine = join(parent, `.${basename(path)}-cleanup-${randomUUID()}`);
+        const parentHandle = openSync(parent, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+        try {
+            if (!sameIdentity(fstatSync(parentHandle), lstatSync(parent)))
+                return false;
+            const current = lstatSync(path);
+            if (current.isSymbolicLink() || !current.isDirectory()
+                || current.dev !== expected.dev || current.ino !== expected.ino)
+                return false;
+            renameSync(path, quarantine);
+            const moved = lstatSync(quarantine);
+            if (moved.isDirectory() && !moved.isSymbolicLink()
+                && moved.dev === expected.dev && moved.ino === expected.ino) {
+                if (removeQuarantinedWorkspace(quarantine, expected))
+                    return true;
+            }
+            if (sameIdentity(moved, { dev: expected.dev, ino: expected.ino })) {
+                try {
+                    lstatSync(path);
+                }
+                catch (error) {
+                    if (error.code === "ENOENT")
+                        renameSync(quarantine, path);
+                }
+            }
+            return false;
+        }
+        finally {
+            closeSync(parentHandle);
+        }
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return expected === undefined;
+        throw error;
+    }
+}
+function removeQuarantinedWorkspace(path, expected) {
+    let rootFd;
+    try {
+        rootFd = openSync(path, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+    }
+    catch (error) {
+        if (error.code !== "EACCES")
+            return false;
+        try {
+            normalizeUnreadableDirectory(path, expected);
+            rootFd = openSync(path, constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+        }
+        catch {
+            return false;
+        }
+    }
+    const originalCwd = process.cwd();
+    try {
+        if (!sameIdentity(fstatSync(rootFd), expected))
+            return false;
+        fchmodSync(rootFd, DIRECTORY_MODE);
+        process.chdir(path);
+        const cwdFd = openSync(".", constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+        try {
+            if (!sameIdentity(fstatSync(cwdFd), expected))
+                return false;
+            removeDirectoryContentsFromCwd();
+        }
+        finally {
+            closeSync(cwdFd);
+        }
+        process.chdir(originalCwd);
+        const current = lstatSync(path);
+        if (!current.isDirectory() || current.isSymbolicLink() || !sameIdentity(current, expected))
+            return false;
+        rmdirSync(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        process.chdir(originalCwd);
+        closeSync(rootFd);
+    }
+}
+function removeDirectoryContentsFromCwd() {
+    const handle = opendirSync(".");
+    try {
+        for (let entry = handle.readSync(); entry !== null; entry = handle.readSync()) {
+            removeDirectoryEntryFromCwd(entry.name, entry.isDirectory());
+        }
+    }
+    finally {
+        handle.closeSync();
+    }
+}
+function removeDirectoryEntryFromCwd(name, directory) {
+    const current = lstatSync(name);
+    if (current.isSymbolicLink()) {
+        moveAndUnlinkFromCwd(name, current);
+        return;
+    }
+    if (!current.isDirectory() && !current.isFile()) {
+        moveAndUnlinkFromCwd(name, current);
+        return;
+    }
+    const childFd = openChildSync(name, directory, current.isDirectory() ? DIRECTORY_MODE : undefined);
+    try {
+        const opened = fstatSync(childFd);
+        if (!sameIdentity(current, opened))
+            throw new Error(`Workspace entry "${name}" changed during cleanup.`);
+        if (opened.isDirectory()) {
+            fchmodSync(childFd, DIRECTORY_MODE);
+            moveAndRemoveDirectoryFromCwd(name, opened);
+        }
+        else
+            moveAndUnlinkFromCwd(name, opened);
+    }
+    finally {
+        closeSync(childFd);
+    }
+}
+function moveAndUnlinkFromCwd(name, expected) {
+    const alias = `.ebo-clean-${randomUUID()}`;
+    try {
+        lstatSync(alias);
+        throw new Error(`Workspace cleanup alias already exists: "${alias}".`);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    renameSync(name, alias);
+    const moved = lstatSync(alias);
+    if (!sameIdentity(moved, expected))
+        throw new Error(`Workspace entry "${name}" changed during cleanup.`);
+    const final = lstatSync(alias);
+    if (!sameIdentity(final, expected))
+        throw new Error(`Workspace entry "${name}" changed during cleanup.`);
+    unlinkSync(alias);
+}
+function moveAndRemoveDirectoryFromCwd(name, expected) {
+    const alias = `.ebo-clean-${randomUUID()}`;
+    try {
+        lstatSync(alias);
+        throw new Error(`Workspace cleanup alias already exists: "${alias}".`);
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    renameSync(name, alias);
+    let entered = false;
+    try {
+        if (!sameIdentity(lstatSync(alias), expected))
+            throw new Error(`Workspace entry "${name}" changed during cleanup.`);
+        process.chdir(alias);
+        entered = true;
+        const cwdFd = openSync(".", constants.O_RDONLY | constants.O_DIRECTORY | constants.O_NOFOLLOW);
+        try {
+            if (!sameIdentity(fstatSync(cwdFd), expected))
+                throw new Error(`Workspace entry "${name}" changed during cleanup.`);
+            removeDirectoryContentsFromCwd();
+        }
+        finally {
+            closeSync(cwdFd);
+        }
+    }
+    finally {
+        if (entered)
+            process.chdir("..");
+    }
+    const final = lstatSync(join(".", alias));
+    if (!final.isDirectory() || final.isSymbolicLink() || !sameIdentity(final, expected)) {
+        throw new Error(`Workspace entry "${name}" changed during cleanup.`);
+    }
+    rmdirSync(alias);
+}
+function assertAttemptId(attemptId) {
+    if (!ATTEMPT_ID_PATTERN.test(attemptId))
+        throw new Error("Workspace attempt ID is unsafe.");
+}
+function normalizedFileMode(mode) {
+    return FILE_MODE | (mode & 0o100 ? 0o100 : 0);
+}
+function assertWorkspaceRoot(path, expected) {
+    const metadata = lstatSync(path);
+    if (!metadata.isDirectory() || metadata.isSymbolicLink()
+        || metadata.dev !== expected.dev || metadata.ino !== expected.ino) {
+        throw new Error("Workspace root changed during materialization.");
+    }
+}
+function sameIdentity(left, right) {
+    return left.dev === right.dev && left.ino === right.ino;
+}
+function sameFileSnapshot(left, right) {
+    return left.size === right.size && left.mtimeNs === right.mtimeNs && left.ctimeNs === right.ctimeNs;
+}
+function workspaceTimestamp(metadata) {
+    return process.platform === "win32" ? metadata.mtimeMs : metadata.mtimeNs;
+}
+function sameDigest(left, right) {
+    return left.algorithm === right.algorithm && left.value === right.value;
+}
+function assertFrozenSnapshot(options, packetDigest, aggregateDigest) {
+    const current = statusTaskPacket(options.bundleRoot, options.packetLocator, options.freezeLocator);
+    if (current.status !== "frozen" || current.packetDigest === null || !sameDigest(current.packetDigest, packetDigest)
+        || (aggregateDigest !== null && (current.aggregateDigest === null || !sameDigest(current.aggregateDigest, aggregateDigest)))) {
+        throw new Error(`Frozen task packet "${options.packetLocator}" changed before workspace creation.`);
+    }
+}
+function isDisjoint(left, right) {
+    return !isContained(left, right) && !isContained(right, left);
+}
+function isContained(root, path) {
+    const fromRoot = relative(root, path);
+    return fromRoot === "" || (!isAbsolute(fromRoot) && fromRoot !== ".." && !fromRoot.startsWith(`..${sep}`));
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : "Workspace materialization failed.";
+}