@openclaw/matrix 2026.9.6 → 2026.9.7

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

@@ -0,0 +1,236 @@
+import crypto from "node:crypto";
+import fsSync from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { suffixWindowsReservedDeviceName } from "./filename.js";
+import { sameFileIdentityForCleanup } from "./file-identity.js";
+import { assertSafePathSegment, isSafePathSegment, normalizeSafePathSegment, trimHyphenEdges, } from "./safe-path-segment.js";
+import { resolveSecureTempRoot } from "./secure-temp-dir.js";
+import { hasNodeErrorCode } from "./path.js";
+import { registerTempPathForExit } from "./temp-cleanup.js";
+import { assertNoWindowsPathAlias, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
+const HYPHEN_CHAR_CODE = 0x2d;
+const DOT_CHAR_CODE = 0x2e;
+const NUMBER_ZERO_CHAR_CODE = 0x30;
+const NUMBER_NINE_CHAR_CODE = 0x39;
+const UPPERCASE_A_CHAR_CODE = 0x41;
+const UPPERCASE_Z_CHAR_CODE = 0x5a;
+const UNDERSCORE_CHAR_CODE = 0x5f;
+const LOWERCASE_A_CHAR_CODE = 0x61;
+const LOWERCASE_Z_CHAR_CODE = 0x7a;
+function isExtensionCharCode(charCode) {
+    return ((charCode >= NUMBER_ZERO_CHAR_CODE && charCode <= NUMBER_NINE_CHAR_CODE) ||
+        (charCode >= UPPERCASE_A_CHAR_CODE && charCode <= UPPERCASE_Z_CHAR_CODE) ||
+        (charCode >= LOWERCASE_A_CHAR_CODE && charCode <= LOWERCASE_Z_CHAR_CODE) ||
+        charCode === DOT_CHAR_CODE ||
+        charCode === UNDERSCORE_CHAR_CODE ||
+        charCode === HYPHEN_CHAR_CODE);
+}
+function trailingExtensionChars(value) {
+    let start = value.length;
+    while (start > 0 && isExtensionCharCode(value.charCodeAt(start - 1))) {
+        start -= 1;
+    }
+    return start === value.length ? "" : value.slice(start);
+}
+function trimLeadingExtensionPunctuation(value) {
+    let start = 0;
+    while (start < value.length) {
+        const charCode = value.charCodeAt(start);
+        if (charCode !== DOT_CHAR_CODE &&
+            charCode !== UNDERSCORE_CHAR_CODE &&
+            charCode !== HYPHEN_CHAR_CODE) {
+            break;
+        }
+        start += 1;
+    }
+    return start === 0 ? value : value.slice(start);
+}
+function sanitizePrefix(prefix) {
+    const normalized = trimHyphenEdges(prefix.replace(/[^a-zA-Z0-9_-]+/g, "-"));
+    return normalized || "tmp";
+}
+function sanitizeExtension(extension) {
+    if (!extension) {
+        return "";
+    }
+    const normalized = extension.startsWith(".") ? extension : `.${extension}`;
+    const suffix = trailingExtensionChars(normalized);
+    const token = trimLeadingExtensionPunctuation(suffix);
+    return token ? `.${token}` : "";
+}
+export function sanitizeTempFileName(fileName) {
+    // Suffix reserved stems before admission so CON.txt stays CON_.txt.
+    const suffixed = suffixWindowsReservedDeviceName(normalizeSafePathSegment(path.basename(fileName)));
+    // The suffix only inserts "_", so this value is already normalized.
+    return isSafePathSegment(suffixed, { allowDotPrefix: true }) ? suffixed : "download.bin";
+}
+export function buildRandomTempFilePath(params) {
+    const rootDir = resolveTempRoot(params.rootDir);
+    const prefix = sanitizePrefix(params.prefix);
+    const extension = sanitizeExtension(params.extension);
+    const nowCandidate = params.now;
+    const now = typeof nowCandidate === "number" && Number.isFinite(nowCandidate)
+        ? Math.trunc(nowCandidate)
+        : Date.now();
+    const uuid = params.uuid
+        ? assertSafePathSegment(params.uuid.trim(), { label: "temp uuid" })
+        : crypto.randomUUID();
+    const filePath = path.join(rootDir, `${prefix}-${now}-${uuid}${extension}`);
+    assertNoWindowsPathAlias(filePath, "filesystem", "temp file path uses a Windows filesystem namespace alias");
+    return filePath;
+}
+async function cleanupTempDir(dir, identity, onCleanupError) {
+    try {
+        const current = fsSync.lstatSync(dir, { bigint: true });
+        if (!current || !sameFileIdentityForCleanup(current, identity)) {
+            return;
+        }
+        await fs.rm(dir, { recursive: true, force: true });
+    }
+    catch (err) {
+        if (!hasNodeErrorCode(err, "ENOENT")) {
+            onCleanupError?.(err);
+        }
+    }
+}
+function resolveTempRoot(rootDir) {
+    if (rootDir !== undefined) {
+        assertNoWindowsPathAlias(rootDir, "filesystem", "temp root uses a Windows filesystem namespace alias");
+    }
+    const selectedRoot = rootDir ?? resolveSecureTempRoot({ fallbackPrefix: "fs-safe" });
+    assertNoWindowsPathAlias(selectedRoot, "filesystem", "temp root uses a Windows filesystem namespace alias");
+    const resolvedRoot = resolvePathPreservingWindowsRoot(selectedRoot);
+    assertNoWindowsPathAlias(resolvedRoot, "filesystem", "temp root uses a Windows filesystem namespace alias");
+    return resolvedRoot;
+}
+function resolveTempFileCleanupSafety(value) {
+    if (value === undefined || value === "compatible")
+        return "compatible";
+    if (value === "require-bounded")
+        return value;
+    throw new TypeError("cleanupSafety must be compatible or require-bounded");
+}
+export async function createOwnedTempFile(params) {
+    const cleanupSafety = resolveTempFileCleanupSafety(params.cleanupSafety);
+    const rootDir = resolveTempRoot(params.rootDir);
+    const prefix = `${sanitizePrefix(params.prefix)}-`;
+    if (cleanupSafety === "require-bounded") {
+        const initialFileName = sanitizeTempFileName(params.fileName ?? "download.bin");
+        const [{ TempWorkspaceCleanupCapability, TempWorkspaceCleanupOwner, throwTempWorkspaceCreationFailure }, { admitExistingTempWorkspaceRoot }, { TempWorkspaceRetainedChild }, { validateInitialTempWorkspaceChild }, { inspectDirectoryIdentitySync },] = await Promise.all([
+            import("./temp-workspace-owner.js"),
+            import("./temp-workspace-admission.js"),
+            import("./temp-workspace-descriptor.js"),
+            import("./temp-workspace-child-admission.js"),
+            import("./directory-guard.js"),
+        ]);
+        const admission = admitExistingTempWorkspaceRoot(rootDir);
+        const childPrefix = path.join(admission.dir, prefix);
+        assertNoWindowsPathAlias(childPrefix, "filesystem", "temp directory uses a Windows filesystem namespace alias");
+        const capability = new TempWorkspaceCleanupCapability(admission.dir, cleanupSafety, admission, 0o700);
+        let dir;
+        let initialPath;
+        let identity;
+        let retainedChild;
+        let cleanupOwner;
+        let unregisterTempDir;
+        try {
+            capability.prepareChildCreation();
+            dir = await fs.mkdtemp(childPrefix);
+            assertNoWindowsPathAlias(dir, "filesystem", "temp directory uses a Windows filesystem namespace alias");
+            initialPath = path.join(dir, initialFileName);
+            assertNoWindowsPathAlias(initialPath, "filesystem", "temp file path uses a Windows filesystem namespace alias");
+            capability.assertCurrent();
+            const initial = inspectDirectoryIdentitySync(dir);
+            identity = Object.freeze({ dev: initial.dev, ino: initial.ino });
+            const needsModeInitialization = validateInitialTempWorkspaceChild(initial, admission.ownerUid, 0o700);
+            retainedChild = TempWorkspaceRetainedChild.retain(dir, identity);
+            if (needsModeInitialization) {
+                await retainedChild.initializeMode(0o700, admission.ownerUid, admission.assertCurrent);
+            }
+            const retainDescriptor = capability.admitChildDescriptor(retainedChild.ensureReadable());
+            capability.assertAncestryCurrent();
+            retainedChild.finalizeAdmission(admission.ownerUid, 0o700);
+            cleanupOwner = new TempWorkspaceCleanupOwner(retainedChild, capability, retainDescriptor);
+            retainedChild = undefined;
+            unregisterTempDir = registerTempPathForExit(dir, {
+                cleanupSync: () => cleanupOwner.cleanupSync(),
+            });
+        }
+        catch (error) {
+            return throwTempWorkspaceCreationFailure(error, retainedChild, capability, cleanupOwner, "temp file");
+        }
+        const owner = cleanupOwner;
+        const file = (fileName) => {
+            const filePath = path.join(dir, sanitizeTempFileName(fileName ?? params.fileName ?? "download.bin"));
+            assertNoWindowsPathAlias(filePath, "filesystem", "temp file path uses a Windows filesystem namespace alias");
+            return filePath;
+        };
+        const cleanup = async () => {
+            try {
+                try {
+                    await owner.cleanup();
+                }
+                catch (err) {
+                    if (!hasNodeErrorCode(err, "ENOENT")) {
+                        params.onCleanupError?.(err);
+                    }
+                }
+            }
+            finally {
+                unregisterTempDir();
+            }
+        };
+        return {
+            target: {
+                dir,
+                path: initialPath,
+                file,
+                cleanup,
+                [Symbol.asyncDispose]: cleanup,
+            },
+            identity,
+        };
+    }
+    const dir = await fs.mkdtemp(path.join(rootDir, prefix));
+    assertNoWindowsPathAlias(dir, "filesystem", "temp directory uses a Windows filesystem namespace alias");
+    // Windows file indexes can exceed Number.MAX_SAFE_INTEGER. Cleanup receipts
+    // must retain the exact identity or adjacent directories can compare equal.
+    const identity = fsSync.lstatSync(dir, { bigint: true });
+    const unregisterTempDir = registerTempPathForExit(dir, { recursive: true, identity });
+    const file = (fileName) => {
+        const filePath = path.join(dir, sanitizeTempFileName(fileName ?? params.fileName ?? "download.bin"));
+        assertNoWindowsPathAlias(filePath, "filesystem", "temp file path uses a Windows filesystem namespace alias");
+        return filePath;
+    };
+    const cleanup = async () => {
+        try {
+            await cleanupTempDir(dir, identity, params.onCleanupError);
+        }
+        finally {
+            unregisterTempDir();
+        }
+    };
+    return {
+        target: {
+            dir,
+            path: file(),
+            file,
+            cleanup,
+            [Symbol.asyncDispose]: cleanup,
+        },
+        identity: Object.freeze({ dev: identity.dev, ino: identity.ino }),
+    };
+}
+export async function tempFile(params) {
+    return (await createOwnedTempFile(params)).target;
+}
+export async function withTempFile(params, fn) {
+    const target = await tempFile(params);
+    try {
+        return await fn(target.path);
+    }
+    finally {
+        await target.cleanup();
+    }
+}

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

@@ -0,0 +1,14 @@
+export type TempWorkspaceRootAdmission = {
+    dir: string;
+    ownerUid: number | undefined;
+    retainCleanupParent(descriptorFd: number): void;
+    prepareCleanupProbe(descriptorFd: number): void;
+    prepareChildCreation(descriptorFd?: number): void;
+    assertCurrent(): void;
+    assertAncestry(): void;
+    associateCurrent(descriptorFd: number): void;
+    associateAncestry(descriptorFd: number): void;
+};
+export declare function admitExistingTempWorkspaceRoot(rootDir: string): TempWorkspaceRootAdmission;
+export declare function admitTempWorkspaceRoot(rootDir: string): Promise<TempWorkspaceRootAdmission>;
+export declare function admitTempWorkspaceRootSync(rootDir: string): TempWorkspaceRootAdmission;

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

@@ -0,0 +1,387 @@
+import fsSync, {} from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { inspectDirectoryIdentitySync, observeDirectoryIdentitySync, } from "./directory-guard.js";
+import { admitTempWorkspaceChild, admitTempWorkspaceChildSync, assertTrustedTempWorkspaceDirectory, inspectTempWorkspaceDescriptorIdentitySync, projectTempWorkspaceNumericIdentity, TEMP_WORKSPACE_NUMERIC_IDENTITY_REPLAY, } from "./temp-workspace-child-admission.js";
+import { FsSafeError } from "./errors.js";
+import { realpathSync } from "./realpath.js";
+import { assertNoWindowsPathAlias, pathForWindowsFilesystem, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
+import { fileIdentityMismatchError, inspectFileIdentitySync } from "./strict-file-identity.js";
+const WINDOWS = process.platform === "win32";
+function effectiveOwner() {
+    // Windows mode/uid fields do not describe ACL authority. The supplied root's
+    // ACL remains a caller trust requirement, independently of cleanup safety.
+    if (WINDOWS)
+        return undefined;
+    let uid;
+    try {
+        uid = process.geteuid?.();
+    }
+    catch (cause) {
+        throw new FsSafeError("permission-unverified", "temp workspace requires effective owner identity", { cause });
+    }
+    if (!Number.isSafeInteger(uid) || uid === undefined || uid < 0) {
+        throw new FsSafeError("permission-unverified", "temp workspace requires effective owner identity");
+    }
+    return uid;
+}
+function safeNumericIdentity(stat) {
+    const numeric = projectTempWorkspaceNumericIdentity(stat);
+    return numeric && (!WINDOWS || (numeric.dev !== 0 && numeric.ino !== 0))
+        ? numeric
+        : undefined;
+}
+function copyExactDirectoryObservation(stat) {
+    return Object.freeze({
+        dev: stat.dev,
+        ino: stat.ino,
+        uid: stat.uid,
+        gid: stat.gid,
+        mode: stat.mode,
+        directory: stat.isDirectory(),
+        symbolicLink: stat.isSymbolicLink(),
+    });
+}
+function snapshotFromExactObservation(dir, uid, realPath, stat, privateDirectory = false) {
+    if (stat.symbolicLink || !stat.directory) {
+        throw new FsSafeError("not-file", "temp workspace root component must be a real directory");
+    }
+    assertTrustedTempWorkspaceDirectory(stat, uid, privateDirectory);
+    const identity = Object.freeze({ dev: stat.dev, ino: stat.ino });
+    // Retain copied immutable scalars, never a mutable Stats object supplied by
+    // an observation hook. Every later permission check uses a fresh snapshot.
+    return Object.freeze({ dir, identity, numericIdentity: safeNumericIdentity(stat), realPath, privateDirectory });
+}
+function canonicalTempWorkspacePath(dir) {
+    assertNoWindowsPathAlias(dir, "filesystem");
+    const canonical = realpathSync.native(pathForWindowsFilesystem(dir));
+    assertNoWindowsPathAlias(canonical, "filesystem");
+    return canonical;
+}
+function snapshot(dir, uid, realPath = canonicalTempWorkspacePath(dir), privateDirectory = false) {
+    const stat = inspectDirectoryIdentitySync(dir);
+    const observation = copyExactDirectoryObservation(stat);
+    return { entry: snapshotFromExactObservation(dir, uid, realPath, observation, privateDirectory), stat };
+}
+function hasCompleteExactIdentity(stat) {
+    return typeof stat.dev === "bigint" && typeof stat.ino === "bigint" &&
+        (!WINDOWS || (stat.dev !== 0n && stat.ino !== 0n));
+}
+function assertCanonicalRoot(entry) {
+    if (canonicalTempWorkspacePath(entry.dir) !== entry.realPath) {
+        throw new FsSafeError("path-mismatch", "temp workspace root ancestry changed");
+    }
+}
+function inspectSnapshotIdentity(entry) {
+    const expected = entry.numericIdentity;
+    if (!expected) {
+        return inspectDirectoryIdentitySync(entry.dir, entry.identity);
+    }
+    const stat = observeDirectoryIdentitySync(entry.dir);
+    let requiresExactRetry = false;
+    const devKnown = Number.isSafeInteger(stat.dev) && stat.dev >= 0 && (!WINDOWS || stat.dev !== 0);
+    if (devKnown) {
+        if (stat.dev !== expected.dev)
+            throw fileIdentityMismatchError();
+    }
+    else if (WINDOWS)
+        requiresExactRetry = true;
+    else
+        throw fileIdentityMismatchError();
+    const inoKnown = Number.isSafeInteger(stat.ino) && stat.ino >= 0 && (!WINDOWS || stat.ino !== 0);
+    if (inoKnown) {
+        if (stat.ino !== expected.ino)
+            throw fileIdentityMismatchError();
+    }
+    else if (WINDOWS)
+        requiresExactRetry = true;
+    else
+        throw fileIdentityMismatchError();
+    if (!requiresExactRetry)
+        return stat;
+    // Read exact identity only once. The strict helper may re-check this constant
+    // receipt in memory when Windows still reports an unknown component.
+    const exact = observeDirectoryIdentitySync(entry.dir, { bigint: true });
+    return inspectFileIdentitySync(() => exact, entry.identity);
+}
+function assertSnapshot(entry, uid) {
+    const stat = inspectSnapshotIdentity(entry);
+    assertTrustedTempWorkspaceDirectory(stat, uid, entry.privateDirectory);
+    assertCanonicalRoot(entry);
+}
+function snapshotMissingRootComponent(parent, dir, ownerUid, privateDirectory) {
+    if (parent.dir !== parent.realPath) {
+        assertSnapshot(parent, ownerUid);
+        return snapshot(dir, ownerUid, undefined, privateDirectory);
+    }
+    const current = inspectSnapshotIdentity(parent);
+    assertTrustedTempWorkspaceDirectory(current, ownerUid, parent.privateDirectory);
+    let realPath;
+    try {
+        realPath = canonicalTempWorkspacePath(dir);
+    }
+    catch (error) {
+        // Keep parent resolution failures ahead of a missing or unreadable child.
+        assertCanonicalRoot(parent);
+        throw error;
+    }
+    if (path.dirname(realPath) !== parent.realPath) {
+        assertCanonicalRoot(parent);
+        return snapshot(dir, ownerUid, undefined, privateDirectory);
+    }
+    // The child's canonical parent confirms the same parent name at this phase.
+    // Its exact non-symlink/owner observation still precedes mode initialization.
+    return snapshot(dir, ownerUid, realPath, privateDirectory);
+}
+function assertChain(chain, uid) {
+    for (const entry of chain) {
+        const current = inspectSnapshotIdentity(entry);
+        assertTrustedTempWorkspaceDirectory(current, uid, entry.privateDirectory);
+    }
+    const last = chain[chain.length - 1];
+    assertCanonicalRoot(last);
+}
+function canonicalAncestry(root) {
+    const ancestry = [];
+    for (let current = root;; current = path.dirname(current)) {
+        ancestry.push(current);
+        if (path.dirname(current) === current)
+            break;
+    }
+    return ancestry.reverse();
+}
+function exactIdentityMatches(current, expected) {
+    if (current.dev !== expected.dev || current.ino !== expected.ino)
+        throw fileIdentityMismatchError();
+}
+function associateTempWorkspaceRoot(entry, ownerUid, descriptorFd) {
+    const stat = inspectTempWorkspaceDescriptorIdentitySync(descriptorFd, entry.identity, entry.numericIdentity);
+    if (stat.isSymbolicLink() || !stat.isDirectory()) {
+        throw new FsSafeError("not-file", "temp workspace cleanup parent must be a real directory");
+    }
+    assertTrustedTempWorkspaceDirectory(stat, ownerUid, entry.privateDirectory);
+}
+function discoverMissingTempWorkspaceAncestor(ancestor, missing, missingError) {
+    // The caller already classified the first ENOENT. Keep this handoff out of
+    // the probe catch so neither it nor a later failure is classified twice.
+    const initialParent = path.dirname(ancestor);
+    if (initialParent === ancestor)
+        throw missingError;
+    missing.push(path.basename(ancestor));
+    ancestor = initialParent;
+    for (;;) {
+        try {
+            // Only subsequent non-volume-root probes may return a missing receipt.
+            const parent = path.dirname(ancestor);
+            const allowMissing = parent !== ancestor;
+            assertNoWindowsPathAlias(ancestor, "filesystem");
+            const operationPath = pathForWindowsFilesystem(ancestor);
+            const stat = allowMissing
+                ? fsSync.lstatSync(operationPath, { bigint: true, throwIfNoEntry: false })
+                : fsSync.lstatSync(operationPath, { bigint: true });
+            if (allowMissing && stat === undefined) {
+                missing.push(path.basename(ancestor));
+                ancestor = parent;
+                continue;
+            }
+            return { ancestor, initial: copyExactDirectoryObservation(stat) };
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+            const parent = path.dirname(ancestor);
+            if (parent === ancestor)
+                throw error;
+            missing.push(path.basename(ancestor));
+            ancestor = parent;
+        }
+    }
+}
+function rootPlan(rootDir) {
+    assertNoWindowsPathAlias(rootDir, "filesystem");
+    const ownerUid = effectiveOwner();
+    let ancestor = resolvePathPreservingWindowsRoot(rootDir);
+    assertNoWindowsPathAlias(ancestor, "filesystem");
+    const missing = [];
+    let initial;
+    try {
+        initial = copyExactDirectoryObservation(fsSync.lstatSync(pathForWindowsFilesystem(ancestor), { bigint: true }));
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+        ({ ancestor, initial } = discoverMissingTempWorkspaceAncestor(ancestor, missing, error));
+    }
+    missing.reverse();
+    // Keep the historical support for a caller-approved root alias and standard
+    // system aliases such as macOS /var. A dangling alias fails canonicalization.
+    const observedAncestor = ancestor;
+    ancestor = canonicalTempWorkspacePath(observedAncestor);
+    const existingCanonicalRoot = missing.length === 0 && observedAncestor === ancestor &&
+        !initial.symbolicLink && initial.directory && hasCompleteExactIdentity(initial);
+    if (existingCanonicalRoot) {
+        const discovery = snapshotFromExactObservation(ancestor, ownerUid, ancestor, initial, true);
+        return {
+            admission: canonicalRootAdmission(discovery, ownerUid),
+            missing,
+            ownerUid,
+        };
+    }
+    const chain = canonicalAncestry(ancestor).map((dir) => snapshot(dir, ownerUid, dir, missing.length === 0 && dir === ancestor).entry);
+    // Missing-component creation needs a replay before its first mutation. When
+    // the complete root already exists through an alias, retain the historical
+    // guarded route because discovery and mutation use different path spellings.
+    if (missing.length > 0)
+        assertChain(chain, ownerUid);
+    return { chain, missing, ownerUid };
+}
+function rootAdmission(chain, ownerUid) {
+    // Bind the immediate parent now: missing-component creation appends to chain.
+    const current = chain[chain.length - 1];
+    return {
+        dir: current.dir,
+        ownerUid,
+        retainCleanupParent: (descriptorFd) => {
+            assertSnapshot(current, ownerUid);
+            associateTempWorkspaceRoot(current, ownerUid, descriptorFd);
+        },
+        // The guarded route associated the cleanup parent while retaining it.
+        // A native capability probe therefore needs no additional observation.
+        prepareCleanupProbe: () => { },
+        prepareChildCreation: () => { assertChain(chain, ownerUid); },
+        assertCurrent: () => { assertSnapshot(current, ownerUid); },
+        assertAncestry: () => { assertChain(chain, ownerUid); },
+        associateCurrent: (descriptorFd) => {
+            assertSnapshot(current, ownerUid);
+            associateTempWorkspaceRoot(current, ownerUid, descriptorFd);
+        },
+        associateAncestry: (descriptorFd) => {
+            assertChain(chain, ownerUid);
+            associateTempWorkspaceRoot(current, ownerUid, descriptorFd);
+        },
+    };
+}
+function canonicalRootAdmission(discovery, ownerUid) {
+    let admittedChain;
+    const chain = () => {
+        if (!admittedChain) {
+            throw new FsSafeError("path-mismatch", "temp workspace root has not completed creation admission");
+        }
+        return admittedChain;
+    };
+    return {
+        dir: discovery.dir,
+        ownerUid,
+        // Merely opening the cleanup-parent descriptor grants no authority. The
+        // exact association is completed only at a bounded probe or the mutation
+        // boundary below.
+        retainCleanupParent: () => { },
+        prepareCleanupProbe: (descriptorFd) => {
+            // A native feature probe may inspect only a descriptor associated with
+            // the originally discovered root. This remains provisional: the named
+            // root and complete ancestry are freshly admitted before mutation.
+            assertCanonicalRoot(discovery);
+            associateTempWorkspaceRoot(discovery, ownerUid, descriptorFd);
+        },
+        prepareChildCreation: (descriptorFd) => {
+            const ancestry = canonicalAncestry(discovery.dir);
+            const candidate = ancestry.map((dir, index) => {
+                if (!TEMP_WORKSPACE_NUMERIC_IDENTITY_REPLAY || index !== ancestry.length - 1) {
+                    return snapshot(dir, ownerUid, dir, index === ancestry.length - 1 && discovery.privateDirectory).entry;
+                }
+                const current = inspectSnapshotIdentity(discovery);
+                assertTrustedTempWorkspaceDirectory(current, ownerUid, discovery.privateDirectory);
+                return discovery;
+            });
+            const current = candidate[candidate.length - 1];
+            exactIdentityMatches(current.identity, discovery.identity);
+            assertCanonicalRoot(current);
+            if (descriptorFd !== undefined) {
+                associateTempWorkspaceRoot(current, ownerUid, descriptorFd);
+            }
+            // Do not expose even the ancestry receipts until every named and
+            // descriptor association at this pre-mutation boundary has succeeded.
+            admittedChain = candidate;
+        },
+        assertCurrent: () => {
+            const currentChain = chain();
+            assertSnapshot(currentChain[currentChain.length - 1], ownerUid);
+        },
+        assertAncestry: () => { assertChain(chain(), ownerUid); },
+        associateCurrent: (descriptorFd) => {
+            const currentChain = chain();
+            const current = currentChain[currentChain.length - 1];
+            assertSnapshot(current, ownerUid);
+            associateTempWorkspaceRoot(current, ownerUid, descriptorFd);
+        },
+        associateAncestry: (descriptorFd) => {
+            const currentChain = chain();
+            assertChain(currentChain, ownerUid);
+            associateTempWorkspaceRoot(currentChain[currentChain.length - 1], ownerUid, descriptorFd);
+        },
+    };
+}
+export function admitExistingTempWorkspaceRoot(rootDir) {
+    const { admission, chain, missing, ownerUid } = rootPlan(rootDir);
+    if (missing.length > 0) {
+        throw new FsSafeError("helper-unavailable", "temp file cleanup parent is unavailable");
+    }
+    return admission ?? rootAdmission(chain, ownerUid);
+}
+export async function admitTempWorkspaceRoot(rootDir) {
+    const { admission, chain, missing, ownerUid } = rootPlan(rootDir);
+    if (admission)
+        return admission;
+    const guardedChain = chain;
+    for (const [index, segment] of missing.entries()) {
+        const parentEntry = guardedChain[guardedChain.length - 1];
+        const parent = rootAdmission(guardedChain, ownerUid);
+        const dir = path.join(parent.dir, segment);
+        assertNoWindowsPathAlias(dir, "filesystem");
+        parent.assertCurrent();
+        let created = false;
+        try {
+            await fs.mkdir(dir, { mode: 0o700 });
+            created = true;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+        const observed = snapshotMissingRootComponent(parentEntry, dir, ownerUid, index === missing.length - 1);
+        if (created) {
+            const modeInitialization = admitTempWorkspaceChild(dir, observed.stat, parent, 0o700);
+            if (modeInitialization)
+                await modeInitialization;
+        }
+        guardedChain.push(observed.entry);
+    }
+    return rootAdmission(guardedChain, ownerUid);
+}
+export function admitTempWorkspaceRootSync(rootDir) {
+    const { admission, chain, missing, ownerUid } = rootPlan(rootDir);
+    if (admission)
+        return admission;
+    const guardedChain = chain;
+    for (const [index, segment] of missing.entries()) {
+        const parentEntry = guardedChain[guardedChain.length - 1];
+        const parent = rootAdmission(guardedChain, ownerUid);
+        const dir = path.join(parent.dir, segment);
+        assertNoWindowsPathAlias(dir, "filesystem");
+        parent.assertCurrent();
+        let created = false;
+        try {
+            fsSync.mkdirSync(dir, { mode: 0o700 });
+            created = true;
+        }
+        catch (error) {
+            if (error.code !== "EEXIST")
+                throw error;
+        }
+        const observed = snapshotMissingRootComponent(parentEntry, dir, ownerUid, index === missing.length - 1);
+        if (created)
+            admitTempWorkspaceChildSync(dir, observed.stat, parent, 0o700);
+        guardedChain.push(observed.entry);
+    }
+    return rootAdmission(guardedChain, ownerUid);
+}

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

@@ -0,0 +1,23 @@
+import { type BigIntStats, type Stats } from "node:fs";
+import type { TempWorkspaceRootAdmission } from "./temp-workspace-admission.js";
+export type TempWorkspaceIdentity = Readonly<{
+    dev: bigint;
+    ino: bigint;
+}>;
+export type TempWorkspaceNumericIdentity = Readonly<{
+    dev: number;
+    ino: number;
+}>;
+export type TempWorkspaceIdentityStat = BigIntStats | Stats;
+export declare const TEMP_WORKSPACE_NUMERIC_IDENTITY_REPLAY: boolean;
+export declare function projectTempWorkspaceNumericIdentity(identity: TempWorkspaceIdentity): TempWorkspaceNumericIdentity | undefined;
+export declare function inspectTempWorkspaceDescriptorIdentitySync(fd: number, expected: TempWorkspaceIdentity, numeric: TempWorkspaceNumericIdentity | undefined): TempWorkspaceIdentityStat;
+export declare function inspectTempWorkspaceDirectoryIdentitySync(dir: string, expected: TempWorkspaceIdentity, numeric: TempWorkspaceNumericIdentity | undefined): TempWorkspaceIdentityStat;
+export declare function validateTempWorkspaceDirMode(mode: number): void;
+export declare function assertTrustedTempWorkspaceDirectory(stat: Pick<BigIntStats, "uid" | "gid" | "mode"> | Pick<Stats, "uid" | "gid" | "mode">, uid: number | undefined, privateDirectory?: boolean): void;
+export declare function assertTempWorkspaceChildState(stat: BigIntStats | Stats, ownerUid: number | undefined): void;
+export declare function validateInitialTempWorkspaceChild(stat: BigIntStats, ownerUid: number | undefined, mode: number): boolean;
+export declare function childHasRequestedMode(stat: BigIntStats | Stats, mode: number): boolean;
+export declare function admitTempWorkspaceChild(dir: string, expected: BigIntStats, parent: TempWorkspaceRootAdmission, mode: number): Promise<void> | undefined;
+export declare function admitTempWorkspaceChildSync(dir: string, expected: BigIntStats, parent: TempWorkspaceRootAdmission, mode: number): void;
+export declare function validateAdmittedTempWorkspaceChild(current: TempWorkspaceIdentityStat, ownerUid: number | undefined, mode: number): TempWorkspaceIdentityStat;