@openclaw/openshell-sandbox 2026.9.4 → 2026.9.5

package/node_modules/@openclaw/fs-safe/dist/private-producer-handoff.js

@@ -0,0 +1,272 @@
+import fsSync, {} from "node:fs";
+import fs, {} from "node:fs/promises";
+import { FsSafeError } from "./errors.js";
+import { sameFileIdentityForCleanup } from "./file-identity.js";
+import { resolveReadOpenFlags } from "./read-open-flags.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
+import { registerTempPathForExit, } from "./temp-cleanup.js";
+function pathMismatch(message) {
+    return new FsSafeError("path-mismatch", message);
+}
+function assertInitialSource(stat) {
+    if (stat.isSymbolicLink()) {
+        throw new FsSafeError("path-alias", "isolated producer output must not be a symlink");
+    }
+    if (!stat.isFile()) {
+        throw new FsSafeError("not-file", "isolated producer output must be a regular file");
+    }
+    if (stat.nlink !== 1n) {
+        throw new FsSafeError("hardlink", "isolated producer output must have exactly one link");
+    }
+}
+function inspectLinkedFile(inspect, expected, links, label) {
+    return inspectFileIdentitySync(() => {
+        const stat = inspect();
+        if (stat.isSymbolicLink() || !stat.isFile() || stat.nlink !== links) {
+            throw pathMismatch(`${label} changed during isolated producer handoff`);
+        }
+        return stat;
+    }, expected);
+}
+function assertParents(params) {
+    params.assertTargetParent();
+    params.assertSourceParent();
+}
+function normalizeLinkError(error) {
+    const code = error?.code;
+    if (code === "EEXIST") {
+        return new FsSafeError("already-exists", "isolated producer sibling already exists", {
+            cause: error instanceof Error ? error : undefined,
+        });
+    }
+    if (code === "EXDEV" ||
+        code === "ENOSYS" ||
+        code === "ENOTSUP" ||
+        code === "EOPNOTSUPP" ||
+        code === "EPERM") {
+        return new FsSafeError("helper-unavailable", "atomic isolated producer handoff is unavailable", {
+            cause: error instanceof Error ? error : undefined,
+        });
+    }
+    return error;
+}
+function removeSiblingIfOwned(params) {
+    if (!params.state.siblingOwned)
+        return;
+    params.assertTargetParent();
+    let current;
+    try {
+        current = fsSync.lstatSync(params.targetPath, { bigint: true });
+    }
+    catch (error) {
+        if (error?.code === "ENOENT") {
+            params.state.siblingOwned = false;
+            return;
+        }
+        throw error;
+    }
+    if (current.isSymbolicLink() ||
+        !current.isFile() ||
+        (current.nlink !== 1n && current.nlink !== 2n) ||
+        !sameFileIdentityForCleanup(current, params.identity)) {
+        throw pathMismatch("isolated producer sibling changed before cleanup");
+    }
+    fsSync.unlinkSync(params.targetPath);
+    params.state.siblingOwned = false;
+    params.assertTargetParent();
+}
+function combinedFailure(primary, settlement) {
+    if (settlement.length === 0)
+        return primary;
+    return new AggregateError([primary, ...settlement], "isolated producer handoff and settlement failed");
+}
+function hasCode(error, codes) {
+    return !(error instanceof FsSafeError) &&
+        codes.includes(error?.code ?? "");
+}
+async function throwAfterClosing(primary, handles) {
+    const settlement = [];
+    const closed = new Set();
+    for (const handle of handles) {
+        if (!handle || closed.has(handle))
+            continue;
+        closed.add(handle);
+        try {
+            await handle.close();
+        }
+        catch (error) {
+            settlement.push(error);
+        }
+    }
+    throw combinedFailure(primary, settlement);
+}
+function inspectSourceDescriptor(handle, identity, links = 1n) {
+    inspectLinkedFile(() => fsSync.fstatSync(handle.fd, { bigint: true }), identity, links, "isolated producer descriptor");
+}
+function historicalOpenFlags(readWrite) {
+    const access = readWrite ? fsSync.constants.O_RDWR : fsSync.constants.O_RDONLY;
+    return access | resolveReadOpenFlags();
+}
+async function openHistoricalSource(sourcePath, identity, readWrite, links) {
+    let handle;
+    try {
+        handle = await fs.open(sourcePath, historicalOpenFlags(readWrite));
+        inspectSourceDescriptor(handle, identity, links);
+        return handle;
+    }
+    catch (error) {
+        if (handle)
+            return await throwAfterClosing(error, [handle]);
+        throw error;
+    }
+}
+// Windows data-read access can synchronously inspect a completed file through
+// filesystem filters. Prefer write-only admission, which still supports the
+// descriptor metadata, chmod and sync operations used below. Providers or
+// read-only files that reject that access retain the historical open contract.
+async function openProducerSource(params, identity, links = 1n) {
+    if (process.platform !== "win32") {
+        return await openHistoricalSource(params.sourcePath, identity, params.readWrite, links);
+    }
+    let provisional;
+    try {
+        provisional = await fs.open(params.sourcePath, fsSync.constants.O_WRONLY);
+    }
+    catch (error) {
+        if (!hasCode(error, ["EACCES", "EPERM", "EBUSY"]))
+            throw error;
+        return await openHistoricalSource(params.sourcePath, identity, params.readWrite, links);
+    }
+    try {
+        inspectSourceDescriptor(provisional, identity, links);
+        return provisional;
+    }
+    catch (error) {
+        if (!hasCode(error, ["EACCES", "EPERM"])) {
+            return await throwAfterClosing(error, [provisional]);
+        }
+    }
+    let fallback;
+    try {
+        fallback = await fs.open(params.sourcePath, historicalOpenFlags(params.readWrite));
+        inspectSourceDescriptor(fallback, identity, links);
+        inspectLinkedFile(() => fsSync.lstatSync(params.sourcePath, { bigint: true }), identity, links, "isolated producer path");
+        assertParents(params);
+    }
+    catch (error) {
+        return await throwAfterClosing(error, [fallback, provisional]);
+    }
+    try {
+        await provisional.close();
+    }
+    catch (error) {
+        return await throwAfterClosing(error, [fallback]);
+    }
+    return fallback;
+}
+function assertLinkedHandoff(params, handle, identity) {
+    assertParents(params);
+    inspectSourceDescriptor(handle, identity, 2n);
+    inspectLinkedFile(() => fsSync.lstatSync(params.sourcePath, { bigint: true }), identity, 2n, "isolated producer path");
+    inspectLinkedFile(() => fsSync.lstatSync(params.targetPath, { bigint: true }), identity, 2n, "isolated producer sibling");
+}
+export async function handoffPrivateProducerFile(params) {
+    assertParents(params);
+    const identity = inspectFileIdentitySync(() => {
+        const stat = fsSync.lstatSync(params.sourcePath, { bigint: true });
+        assertInitialSource(stat);
+        return stat;
+    });
+    let handle;
+    let siblingHandle;
+    let unregister;
+    const state = { siblingOwned: false };
+    try {
+        handle = await openProducerSource(params, identity);
+        inspectLinkedFile(() => fsSync.lstatSync(params.sourcePath, { bigint: true }), identity, 1n, "isolated producer path");
+        assertParents(params);
+        unregister = registerTempPathForExit(params.targetPath, {
+            cleanupSync: () => removeSiblingIfOwned({
+                assertTargetParent: params.assertTargetParent,
+                identity,
+                state,
+                targetPath: params.targetPath,
+            }),
+        });
+        assertParents(params);
+        try {
+            fsSync.linkSync(params.sourcePath, params.targetPath);
+        }
+        catch (error) {
+            throw normalizeLinkError(error);
+        }
+        state.siblingOwned = true;
+        assertLinkedHandoff(params, handle, identity);
+        if (process.platform === "win32") {
+            // Legacy Windows unlink retains a delete-pending name until handles
+            // opened through that name close. Transfer the pin before retiring it.
+            siblingHandle = await openProducerSource({ ...params, sourcePath: params.targetPath }, identity, 2n);
+            assertLinkedHandoff(params, siblingHandle, identity);
+            inspectSourceDescriptor(handle, identity, 2n);
+            await handle.close();
+            handle = siblingHandle;
+            siblingHandle = undefined;
+            // The old handle's close yielded; both names must still be ours.
+            assertLinkedHandoff(params, handle, identity);
+        }
+        assertParents(params);
+        fsSync.unlinkSync(params.sourcePath);
+        assertParents(params);
+        const opened = inspectLinkedFile(() => fsSync.fstatSync(handle.fd, { bigint: true }), identity, 1n, "isolated producer descriptor");
+        const sibling = inspectLinkedFile(() => fsSync.lstatSync(params.targetPath, { bigint: true }), identity, 1n, "isolated producer sibling");
+        const originalMode = identity.mode & 511n;
+        if (process.platform === "win32" && (originalMode & 128n) === 0n &&
+            ((opened.mode & 511n) !== originalMode || (sibling.mode & 511n) !== originalMode)) {
+            // Legacy unlink clears the shared read-only attribute. Repair only the
+            // admitted sibling inode, without reopening or chmodding its pathname.
+            assertParents(params);
+            fsSync.fchmodSync(handle.fd, Number(originalMode));
+            assertParents(params);
+            const restored = inspectLinkedFile(() => fsSync.fstatSync(handle.fd, { bigint: true }), identity, 1n, "isolated producer descriptor");
+            const restoredSibling = inspectLinkedFile(() => fsSync.lstatSync(params.targetPath, { bigint: true }), identity, 1n, "isolated producer sibling");
+            if ((restored.mode & 511n) !== originalMode || (restoredSibling.mode & 511n) !== originalMode) {
+                throw pathMismatch("isolated producer read-only mode could not be restored");
+            }
+        }
+        const registered = unregister;
+        const release = (() => {
+            state.siblingOwned = false;
+            registered();
+        });
+        release.setIdentity = registered.setIdentity;
+        return { handle, identity, unregister: release };
+    }
+    catch (error) {
+        const settlement = [];
+        if (unregister) {
+            try {
+                removeSiblingIfOwned({
+                    assertTargetParent: params.assertTargetParent,
+                    identity,
+                    state,
+                    targetPath: params.targetPath,
+                });
+                unregister();
+            }
+            catch (cleanupError) {
+                settlement.push(cleanupError);
+            }
+        }
+        for (const retained of new Set([siblingHandle, handle])) {
+            if (!retained)
+                continue;
+            try {
+                await retained.close();
+            }
+            catch (closeError) {
+                settlement.push(closeError);
+            }
+        }
+        throw combinedFailure(error, settlement);
+    }
+}

package/node_modules/@openclaw/fs-safe/dist/private-temp-workspace.d.ts

@@ -1,43 +1,6 @@
-import { type FileStore, type FileStoreSync } from "./file-store.js";
-import { type TempPathIdentityReceipt } from "./temp-cleanup.js";
-import { type TempWorkspaceCleanupResult, type TempWorkspaceCleanupSafety } from "./temp-workspace-owner.js";
+import type { TempWorkspaceOptions, TempWorkspace, TempWorkspaceSync } from "./temp-workspace-types.js";
 export type { TempWorkspaceCleanupResult, TempWorkspaceCleanupSafety, } from "./temp-workspace-owner.js";
-export type TempWorkspaceOptions = {
-    rootDir: string;
-    prefix: string;
-    dirMode?: number;
-    mode?: number;
-    cleanupSafety?: TempWorkspaceCleanupSafety;
-};
-export type TempWorkspace = {
-    dir: string;
-    identity: TempPathIdentityReceipt;
-    store: FileStore;
-    path(fileName: string): string;
-    write(fileName: string, data: string | Uint8Array): Promise<string>;
-    writeText(fileName: string, data: string): Promise<string>;
-    writeJson(fileName: string, data: unknown, options?: {
-        trailingNewline?: boolean;
-    }): Promise<string>;
-    copyIn(fileName: string, sourcePath: string): Promise<string>;
-    read(fileName: string): Promise<Buffer>;
-    cleanup(): Promise<TempWorkspaceCleanupResult>;
-    [Symbol.asyncDispose](): Promise<void>;
-};
-export type TempWorkspaceSync = {
-    dir: string;
-    identity: TempPathIdentityReceipt;
-    store: FileStoreSync;
-    path(fileName: string): string;
-    write(fileName: string, data: string | Uint8Array): string;
-    writeText(fileName: string, data: string): string;
-    writeJson(fileName: string, data: unknown, options?: {
-        trailingNewline?: boolean;
-    }): string;
-    read(fileName: string): Buffer;
-    cleanup(): TempWorkspaceCleanupResult;
-    [Symbol.dispose](): void;
-};
+export type { TempWorkspaceOptions, TempWorkspace, TempWorkspaceSync } from "./temp-workspace-types.js";
 export declare function tempWorkspace(options: TempWorkspaceOptions): Promise<TempWorkspace>;
 export declare function withTempWorkspace<T>(options: TempWorkspaceOptions, run: (workspace: TempWorkspace) => Promise<T>): Promise<T>;
 export declare function tempWorkspaceSync(options: TempWorkspaceOptions): TempWorkspaceSync;

package/node_modules/@openclaw/fs-safe/dist/private-temp-workspace.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"private-temp-workspace.d.ts","sourceRoot":"","sources":["../src/private-temp-workspace.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"private-temp-workspace.d.ts","sourceRoot":"","sources":["../src/private-temp-workspace.ts"],"names":[],"mappings":"AAwCA,OAAO,KAAK,EAAE,oBAAoB,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAExG,YAAY,EACV,0BAA0B,EAC1B,0BAA0B,GAC3B,MAAM,2BAA2B,CAAC;AAEnC,YAAY,EAAE,oBAAoB,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AA8OxG,wBAAsB,aAAa,CACjC,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,aAAa,CAAC,CAExB;AAED,wBAAsB,iBAAiB,CAAC,CAAC,EACvC,OAAO,EAAE,oBAAoB,EAC7B,GAAG,EAAE,CAAC,SAAS,EAAE,aAAa,KAAK,OAAO,CAAC,CAAC,CAAC,GAC5C,OAAO,CAAC,CAAC,CAAC,CAOZ;AA6JD,wBAAgB,iBAAiB,CAC/B,OAAO,EAAE,oBAAoB,GAC5B,iBAAiB,CAEnB;AAED,wBAAgB,qBAAqB,CAAC,CAAC,EACrC,OAAO,EAAE,oBAAoB,EAC7B,GAAG,EAAE,CAAC,SAAS,EAAE,iBAAiB,KAAK,CAAC,GACvC,CAAC,CAOH"}

package/node_modules/@openclaw/fs-safe/dist/private-temp-workspace.js

@@ -1,14 +1,20 @@
-import { randomUUID } from "node:crypto";
-import fsSync from "node:fs";
+import { randomInt, randomUUID } from "node:crypto";
+import fsSync, {} from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { fileStore, fileStoreSync, } from "./file-store.js";
 import { FsSafeError } from "./errors.js";
 import { isNotFoundPathError } from "./path.js";
+import { inspectDirectoryIdentitySync } from "./directory-guard.js";
 import { throwFsSafeReadError } from "./root-errors.js";
 import { matchRootFileOpenFailure, openRootFileSync, } from "./root-file.js";
 import { registerTempPathForExit, } from "./temp-cleanup.js";
 import { TempWorkspaceCleanupCapability, TempWorkspaceCleanupOwner, } from "./temp-workspace-owner.js";
+import { assertNoWindowsPathAlias, hasWindowsPathAlias, } from "./windows-path-alias.js";
+import { TempWorkspaceRetainedChild } from "./temp-workspace-descriptor.js";
+import { admitRetainedTempWorkspaceChild, admitRetainedTempWorkspaceChildSync, validateInitialTempWorkspaceChild, } from "./temp-workspace-child-admission.js";
+import { admitTempWorkspaceRoot, admitTempWorkspaceRootSync, } from "./temp-workspace-admission.js";
+import { validateTempWorkspaceDirMode } from "./temp-workspace-permissions.js";
 function resolveTempWorkspaceCleanupSafety(value) {
     if (value === undefined || value === "compatible")
         return "compatible";
@@ -23,8 +29,43 @@ function sanitizeTempPrefix(prefix) {
     }
     return sanitized.endsWith("-") ? sanitized : `${sanitized}-`;
 }
+const TEMP_WORKSPACE_SUFFIX_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
+const TEMP_WORKSPACE_SUFFIX_SPACE = TEMP_WORKSPACE_SUFFIX_ALPHABET.length ** 6;
+const TEMP_WORKSPACE_DIRECT_CREATE_ATTEMPTS = 64;
+function randomTempWorkspaceChildPath(childPrefix) {
+    let encoded = randomInt(TEMP_WORKSPACE_SUFFIX_SPACE);
+    let suffix = "";
+    for (let index = 0; index < 6; index += 1) {
+        suffix = TEMP_WORKSPACE_SUFFIX_ALPHABET[encoded % TEMP_WORKSPACE_SUFFIX_ALPHABET.length] + suffix;
+        encoded = Math.floor(encoded / TEMP_WORKSPACE_SUFFIX_ALPHABET.length);
+    }
+    return `${childPrefix}${suffix}`;
+}
+function canCreateTempWorkspaceWithRequestedMode(dirMode) {
+    return (process.platform === "linux" || process.platform === "darwin") && dirMode !== 0o700 &&
+        (dirMode & 0o700) === 0o700 && (dirMode & 0o7000) === 0 && (dirMode & 0o022) === 0;
+}
+function createTempWorkspaceWithRequestedModeSync(childPrefix, dirMode, prepareChildCreation) {
+    let collision;
+    for (let attempt = 0; attempt < TEMP_WORKSPACE_DIRECT_CREATE_ATTEMPTS; attempt += 1) {
+        const candidate = randomTempWorkspaceChildPath(childPrefix);
+        prepareChildCreation();
+        try {
+            fsSync.mkdirSync(candidate, { mode: dirMode, recursive: false });
+            return candidate;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+            collision = error;
+        }
+    }
+    throw collision;
+}
 function resolveWorkspaceLeaf(dir, fileName) {
-    return path.join(dir, assertWorkspaceFileName(fileName));
+    const resolved = path.join(dir, assertWorkspaceFileName(fileName));
+    assertNoWindowsPathAlias(resolved, "filesystem", "temp workspace path uses a Windows filesystem namespace alias");
+    return resolved;
 }
 function assertWorkspaceFileName(fileName) {
     const value = fileName.trim();
@@ -34,6 +75,7 @@ function assertWorkspaceFileName(fileName) {
         value.includes("\0") ||
         value.includes("/") ||
         value.includes("\\") ||
+        hasWindowsPathAlias(value, "relative") ||
         path.basename(value) !== value) {
         throw new Error(`Invalid temp workspace file name: ${JSON.stringify(fileName)}`);
     }
@@ -65,49 +107,60 @@ function throwTempWorkspaceOpenFailure(failure) {
         },
     });
 }
-async function ensurePrivateDirectory(dir, mode) {
-    await fs.mkdir(dir, { recursive: true, mode });
-    const stat = await fs.stat(dir);
-    if (!stat.isDirectory()) {
-        throw new Error(`Temp root must be a directory: ${dir}`);
-    }
-    await fs.chmod(dir, mode).catch(() => undefined);
-}
-function ensurePrivateDirectorySync(dir, mode) {
-    fsSync.mkdirSync(dir, { recursive: true, mode });
-    const stat = fsSync.statSync(dir);
-    if (!stat.isDirectory()) {
-        throw new Error(`Temp root must be a directory: ${dir}`);
-    }
-    try {
-        fsSync.chmodSync(dir, mode);
-    }
-    catch {
-        // Best-effort on platforms that do not enforce POSIX modes.
-    }
-}
-async function createTempWorkspace(options) {
+async function createTempWorkspace(options, scopedPrefix = false) {
+    const rootDir = options.rootDir;
+    assertNoWindowsPathAlias(rootDir, "filesystem", "temp workspace root uses a Windows filesystem namespace alias");
     const dirMode = options.dirMode ?? 0o700;
+    validateTempWorkspaceDirMode(dirMode);
     const mode = options.mode ?? 0o600;
     const cleanupSafety = resolveTempWorkspaceCleanupSafety(options.cleanupSafety);
-    const requestedRoot = path.resolve(options.rootDir);
-    const root = await fs.realpath(requestedRoot).catch(() => requestedRoot);
-    await ensurePrivateDirectory(root, dirMode);
-    const capability = new TempWorkspaceCleanupCapability(root, cleanupSafety);
+    const admission = await admitTempWorkspaceRoot(rootDir);
+    const root = admission.dir;
+    assertNoWindowsPathAlias(root, "filesystem", "temp workspace root uses a Windows filesystem namespace alias");
+    // Capture and sanitize caller-controlled prefix data before retaining descriptors.
+    const rawPrefix = options.prefix;
+    const workspacePrefix = scopedPrefix
+        ? `${sanitizeTempPrefix(rawPrefix)}${randomUUID()}-`
+        : rawPrefix;
+    const childPrefix = path.join(root, sanitizeTempPrefix(workspacePrefix));
+    assertNoWindowsPathAlias(childPrefix, "filesystem", "temp workspace path uses a Windows filesystem namespace alias");
+    const capability = new TempWorkspaceCleanupCapability(root, cleanupSafety, admission, dirMode);
     let dir;
     let stat;
+    let retainedChild;
+    let retainChildDescriptor = false;
     let cleanupOwner;
     let unregisterTempDir;
     try {
-        dir = await fs.mkdtemp(path.join(root, sanitizeTempPrefix(options.prefix)));
-        await fs.chmod(dir, dirMode).catch(() => undefined);
-        stat = await fs.lstat(dir, { bigint: true });
-        if (stat.isSymbolicLink() || !stat.isDirectory()) {
-            throw new Error(`Temp workspace must be a directory: ${dir}`);
-        }
+        // Native capability discovery is complete before this synchronous
+        // boundary. The existing canonical-root route now captures the complete
+        // ancestry and associates its provisional parent descriptor here, then
+        // dispatches mkdtemp without yielding or invoking another probe.
+        capability.prepareChildCreation();
+        dir = await fs.mkdtemp(childPrefix);
+        assertNoWindowsPathAlias(dir, "filesystem", "temp workspace path uses a Windows filesystem namespace alias");
         if (capability.parent)
             capability.assertCurrent();
-        cleanupOwner = new TempWorkspaceCleanupOwner(dir, stat, capability);
+        else
+            admission.assertCurrent();
+        stat = inspectDirectoryIdentitySync(dir);
+        const needsModeInitialization = validateInitialTempWorkspaceChild(stat, admission.ownerUid, dirMode);
+        // Retain while the child still has its private creation mode so an
+        // explicit dirMode such as 0 cannot make identity descriptor acquisition fail.
+        retainedChild = TempWorkspaceRetainedChild.retain(dir, stat);
+        const modeInitialization = admitRetainedTempWorkspaceChild(retainedChild, needsModeInitialization, admission, dirMode);
+        if (modeInitialization)
+            await modeInitialization;
+        retainChildDescriptor = capability.admitChildDescriptor(retainedChild.ensureReadable());
+        // Final adoption order is deliberate: complete ancestry, retained cleanup
+        // parent, then descriptor and named checks of the original child identity.
+        if (capability.parent)
+            capability.assertAncestryCurrent();
+        else
+            admission.assertAncestry();
+        stat = retainedChild.finalizeAdmission(admission.ownerUid, dirMode);
+        cleanupOwner = new TempWorkspaceCleanupOwner(retainedChild, capability, retainChildDescriptor);
+        retainedChild = undefined;
         unregisterTempDir = registerTempPathForExit(dir, {
             cleanupSync: () => cleanupOwner.cleanupSync(),
         });
@@ -116,8 +169,26 @@ async function createTempWorkspace(options) {
         try {
             if (cleanupOwner)
                 cleanupOwner.cleanupSync();
-            else
-                capability.close();
+            else {
+                const closeErrors = [];
+                try {
+                    retainedChild?.close();
+                }
+                catch (closeError) {
+                    closeErrors.push(closeError);
+                }
+                try {
+                    capability.close();
+                }
+                catch (closeError) {
+                    closeErrors.push(closeError);
+                }
+                if (closeErrors.length === 1)
+                    throw closeErrors[0];
+                if (closeErrors.length > 1) {
+                    throw new AggregateError(closeErrors, "temp workspace admission descriptor close failed");
+                }
+            }
         }
         catch (cleanupError) {
             throw new AggregateError([error, cleanupError], "temp workspace creation and cleanup both failed");
@@ -170,10 +241,7 @@ export async function tempWorkspace(options) {
     return await createTempWorkspace(options);
 }
 export async function withTempWorkspace(options, run) {
-    const workspace = await createTempWorkspace({
-        ...options,
-        prefix: `${sanitizeTempPrefix(options.prefix)}${randomUUID()}-`,
-    });
+    const workspace = await createTempWorkspace(options, true);
     try {
         return await run(workspace);
     }
@@ -181,39 +249,67 @@ export async function withTempWorkspace(options, run) {
         await workspace.cleanup();
     }
 }
-export function tempWorkspaceSync(options) {
+function createTempWorkspaceSync(options, scopedPrefix = false) {
+    const rootDir = options.rootDir;
+    assertNoWindowsPathAlias(rootDir, "filesystem", "temp workspace root uses a Windows filesystem namespace alias");
     const dirMode = options.dirMode ?? 0o700;
+    validateTempWorkspaceDirMode(dirMode);
     const mode = options.mode ?? 0o600;
     const cleanupSafety = resolveTempWorkspaceCleanupSafety(options.cleanupSafety);
-    const requestedRoot = path.resolve(options.rootDir);
-    let root = requestedRoot;
-    try {
-        root = fsSync.realpathSync.native(requestedRoot);
-    }
-    catch {
-        root = requestedRoot;
-    }
-    ensurePrivateDirectorySync(root, dirMode);
-    const capability = new TempWorkspaceCleanupCapability(root, cleanupSafety);
+    const admission = admitTempWorkspaceRootSync(rootDir);
+    const root = admission.dir;
+    assertNoWindowsPathAlias(root, "filesystem", "temp workspace root uses a Windows filesystem namespace alias");
+    // Capture and sanitize caller-controlled prefix data before retaining descriptors.
+    const rawPrefix = options.prefix;
+    const workspacePrefix = scopedPrefix
+        ? `${sanitizeTempPrefix(rawPrefix)}${randomUUID()}-`
+        : rawPrefix;
+    const childPrefix = path.join(root, sanitizeTempPrefix(workspacePrefix));
+    assertNoWindowsPathAlias(childPrefix, "filesystem", "temp workspace path uses a Windows filesystem namespace alias");
+    const capability = new TempWorkspaceCleanupCapability(root, cleanupSafety, admission, dirMode);
     let dir;
     let stat;
+    let retainedChild;
+    let retainChildDescriptor = false;
+    let needsModeInitialization;
     let cleanupOwner;
     let unregisterTempDir;
     try {
-        dir = fsSync.mkdtempSync(path.join(root, sanitizeTempPrefix(options.prefix)));
-        try {
-            fsSync.chmodSync(dir, dirMode);
-        }
-        catch {
-            // Best-effort on platforms that do not enforce POSIX modes.
+        const directRequestedMode = canCreateTempWorkspaceWithRequestedMode(dirMode);
+        if (directRequestedMode) {
+            dir = createTempWorkspaceWithRequestedModeSync(childPrefix, dirMode, () => capability.prepareChildCreation());
         }
-        stat = fsSync.lstatSync(dir, { bigint: true });
-        if (stat.isSymbolicLink() || !stat.isDirectory()) {
-            throw new Error(`Temp workspace must be a directory: ${dir}`);
+        else {
+            capability.prepareChildCreation();
+            dir = fsSync.mkdtempSync(childPrefix);
         }
+        assertNoWindowsPathAlias(dir, "filesystem", "temp workspace path uses a Windows filesystem namespace alias");
         if (capability.parent)
             capability.assertCurrent();
-        cleanupOwner = new TempWorkspaceCleanupOwner(dir, stat, capability);
+        else
+            admission.assertCurrent();
+        if (directRequestedMode) {
+            const created = TempWorkspaceRetainedChild.retainCreated(dir);
+            retainedChild = created.retained;
+            stat = created.stat;
+            needsModeInitialization = validateInitialTempWorkspaceChild(stat, admission.ownerUid, dirMode);
+        }
+        else {
+            stat = inspectDirectoryIdentitySync(dir);
+            needsModeInitialization = validateInitialTempWorkspaceChild(stat, admission.ownerUid, dirMode);
+            retainedChild = TempWorkspaceRetainedChild.retain(dir, stat);
+        }
+        admitRetainedTempWorkspaceChildSync(retainedChild, needsModeInitialization, admission, dirMode);
+        retainChildDescriptor = capability.admitChildDescriptor(retainedChild.ensureReadable());
+        // Match async adoption: complete ancestry and retained cleanup authority
+        // precede descriptor and named child security-state checks.
+        if (capability.parent)
+            capability.assertAncestryCurrent();
+        else
+            admission.assertAncestry();
+        stat = retainedChild.finalizeAdmission(admission.ownerUid, dirMode);
+        cleanupOwner = new TempWorkspaceCleanupOwner(retainedChild, capability, retainChildDescriptor);
+        retainedChild = undefined;
         unregisterTempDir = registerTempPathForExit(dir, {
             cleanupSync: () => cleanupOwner.cleanupSync(),
         });
@@ -222,8 +318,26 @@ export function tempWorkspaceSync(options) {
         try {
             if (cleanupOwner)
                 cleanupOwner.cleanupSync();
-            else
-                capability.close();
+            else {
+                const closeErrors = [];
+                try {
+                    retainedChild?.close();
+                }
+                catch (closeError) {
+                    closeErrors.push(closeError);
+                }
+                try {
+                    capability.close();
+                }
+                catch (closeError) {
+                    closeErrors.push(closeError);
+                }
+                if (closeErrors.length === 1)
+                    throw closeErrors[0];
+                if (closeErrors.length > 1) {
+                    throw new AggregateError(closeErrors, "temp workspace admission descriptor close failed");
+                }
+            }
         }
         catch (cleanupError) {
             throw new AggregateError([error, cleanupError], "temp workspace creation and cleanup both failed");
@@ -285,11 +399,11 @@ export function tempWorkspaceSync(options) {
         },
     };
 }
+export function tempWorkspaceSync(options) {
+    return createTempWorkspaceSync(options);
+}
 export function withTempWorkspaceSync(options, run) {
-    const workspace = tempWorkspaceSync({
-        ...options,
-        prefix: `${sanitizeTempPrefix(options.prefix)}${randomUUID()}-`,
-    });
+    const workspace = createTempWorkspaceSync(options, true);
     try {
         return run(workspace);
     }