@openclaw/openshell-sandbox 2026.10.2 → 2026.10.5-beta.2

package/node_modules/@openclaw/fs-safe/dist/replace-file-copy-fallback.js

@@ -139,15 +139,12 @@ function* replacePinnedWithRestore(io, file, replacement, maxRestoreBytes, repla
             if (io.asynchronous)
                 yield chmod;
             yield* file.sync();
-            throw restoreFailure(writeError, "restored");
         }
         catch (restoreError) {
             mutation.rethrowRefusal();
-            if (restoreError instanceof FsSafeError && restoreError.details?.cleanup === "restored") {
-                throw restoreError;
-            }
             throw restoreFailure(writeError, "restore-failed", restoreError);
         }
+        throw restoreFailure(writeError, "restored");
     }
 }
 export function* copyFallbackReplace(io, params) {

package/node_modules/@openclaw/fs-safe/dist/replace-file-descriptor.js

@@ -139,6 +139,12 @@ export function* writeTempFile(io, params) {
         const writing = file.writeFile(params.content, true);
         if (io.asynchronous)
             yield writing;
+        if (io.asyncFs === fs && process.platform !== "win32" && !params.sync) {
+            // Matching non-durable writes have no I/O left after this identity fence.
+            const current = inspectAtomicIdentity(io, () => file.statExact(), identity, true);
+            if (Number(current.mode & 4095n) === (params.mode & 0o7777))
+                return { file, identity };
+        }
         const chmod = file.chmod(params.mode);
         if (io.asynchronous)
             yield chmod;

package/node_modules/@openclaw/fs-safe/dist/root-create-input.d.ts

@@ -1,14 +1,28 @@
-import type { PinnedWriteInput } from "./pinned-write-types.js";
+import type { NativeWriteParent, PinnedWriteInput, PublishedWriteIdentity } from "./pinned-write-types.js";
 import type { RootCreateOptions, RootCreateStreamOptions, RootWriteOptions } from "./root-options.js";
+import type { AnyAsyncDirectoryGuard } from "./directory-guard.js";
 declare const exclusiveSidecarCreate: unique symbol;
 export declare const sidecarExclusiveCreate: Readonly<{
     [exclusiveSidecarCreate]: true;
 }>;
+export declare const retainSidecarCreated: unique symbol;
+export type SidecarCreationRetention = Readonly<{
+    retain(fd: number, parent: AnyAsyncDirectoryGuard, nativeParent?: NativeWriteParent): void;
+    cleanup(fd: number, parent: NativeWriteParent, identity: PublishedWriteIdentity): void;
+}>;
 export type RootWriteParams = RootWriteOptions & RootCreateOptions & RootCreateStreamOptions & {
     relativePath: string;
     data: string | Buffer | AsyncIterable<Uint8Array>;
     strictFileSync?: boolean;
     [exclusiveSidecarCreate]?: true;
+    [retainSidecarCreated]?: SidecarCreationRetention;
+};
+export declare function sidecarRetainedCreate(retain: NonNullable<RootWriteParams[typeof retainSidecarCreated]>): {
+    [exclusiveSidecarCreate]: true;
+    [retainSidecarCreated]: Readonly<{
+        retain(fd: number, parent: AnyAsyncDirectoryGuard, nativeParent?: NativeWriteParent): void;
+        cleanup(fd: number, parent: NativeWriteParent, identity: PublishedWriteIdentity): void;
+    }>;
 };
 export declare function rethrowCreateInputError(error: unknown): never;
 export declare function createInputOptions(data: RootWriteParams["data"], options: RootCreateOptions & RootCreateStreamOptions, defaultMaxBytes?: number): RootCreateOptions & RootCreateStreamOptions;

package/node_modules/@openclaw/fs-safe/dist/root-create-input.js

@@ -5,6 +5,10 @@ import { MutationAuthorityError } from "./mutation-authority.js";
 // Keep this composition hook off the public Root options and package exports.
 const exclusiveSidecarCreate = Symbol("exclusiveSidecarCreate");
 export const sidecarExclusiveCreate = Object.freeze({ [exclusiveSidecarCreate]: true });
+export const retainSidecarCreated = Symbol("retainSidecarCreated");
+export function sidecarRetainedCreate(retain) {
+    return { ...sidecarExclusiveCreate, [retainSidecarCreated]: retain };
+}
 class CreateInputError extends FsSafeError {
     rejection;
     constructor(rejection) {

package/node_modules/@openclaw/fs-safe/dist/root-directory-entry.js

@@ -17,7 +17,7 @@ export async function lookupRootDirectoryEntry(root, guard, name) {
         const observed = inspectStatObservationSync(bigint => bigint
             ? fs.lstatSync(pathname, { bigint: true }) : fs.lstatSync(pathname));
         await assertRootDirectoryObservationGuard(root, guard);
-        return { entry: { name, ...pathStatFromStats(observed.stat) }, identity: observed.identity };
+        return { entry: pathStatFromStats(observed.stat, name), identity: observed.identity };
     }
     catch (error) {
         await assertRootDirectoryObservationGuard(root, guard);

package/node_modules/@openclaw/fs-safe/dist/root-directory-list.d.ts

@@ -16,6 +16,5 @@ export declare function assertRootDirectoryObservationGuard(root: RootContext, g
  * both its identity and canonical check here.
  */
 export declare function assertRootPathObservationReceiptCurrent(root: RootContext, receipt: RootPathObservationReceipt | RootPathParentObservationReceipt, finalTarget?: Stats | BigIntStats): void;
-export declare function listDirectoryPath(root: RootContext, directory: string, withFileTypes: true, receipt?: RootPathObservationReceipt): Promise<DirEntry[]>;
 export declare function listDirectoryPath(root: RootContext, directory: string, withFileTypes: boolean, receipt?: RootPathObservationReceipt): Promise<string[] | DirEntry[]>;
 export declare function openRootDirectoryListing(root: RootContext, directory: string, options: RootDirectoryListingOptions, receipt?: RootPathObservationReceipt): Promise<RootDirectoryListing>;

package/node_modules/@openclaw/fs-safe/dist/root-directory-list.js

@@ -105,10 +105,6 @@ export async function assertRootDirectoryObservationGuard(root, guard) {
         throw directoryChangedError(error);
     }
 }
-function sameObservationDirectory(left, right) {
-    return left.dir === right.dir && left.realPath === right.realPath &&
-        left.identity.dev === right.identity.dev && left.identity.ino === right.identity.ino;
-}
 function assertReceiptDirectoryGuardSync(root, guard, backend) {
     if (backend) {
         const observed = inspectNativeDirectoryObservation(backend, guard.dir, guard.identity);
@@ -139,7 +135,8 @@ export function assertRootPathObservationReceiptCurrent(root, receipt, finalTarg
         rootGuard.identity.dev !== root.rootIdentity.dev || rootGuard.identity.ino !== root.rootIdentity.ino) {
         throw rootPathChangedError();
     }
-    if (sameObservationDirectory(rootGuard, directoryGuard)) {
+    if (rootGuard.dir === directoryGuard.dir && rootGuard.realPath === directoryGuard.realPath &&
+        rootGuard.identity.dev === directoryGuard.identity.dev && rootGuard.identity.ino === directoryGuard.identity.ino) {
         try {
             if (receipt.kind === "stat" && receipt.target === rootGuard && finalTarget &&
                 !receipt.directoryObserver) {
@@ -176,12 +173,6 @@ function normalizeDirectoryError(error) {
     }
     return error;
 }
-function normalizeInitialDirectoryError(error) {
-    if (error instanceof FsSafeError && error.code === "not-file") {
-        return new FsSafeError("not-found", "directory not found", { cause: error });
-    }
-    return normalizeDirectoryError(error);
-}
 export async function listDirectoryPath(root, directory, withFileTypes, receipt) {
     let guard;
     if (receipt) {
@@ -192,7 +183,10 @@ export async function listDirectoryPath(root, directory, withFileTypes, receipt)
             guard = await createRootDirectoryObservationGuard(root, directory);
         }
         catch (error) {
-            throw normalizeInitialDirectoryError(error);
+            if (error instanceof FsSafeError && error.code === "not-file") {
+                throw new FsSafeError("not-found", "directory not found", { cause: error });
+            }
+            throw normalizeDirectoryError(error);
         }
     }
     return await listGuardedDirectoryPath(root, guard, withFileTypes, receipt);

package/node_modules/@openclaw/fs-safe/dist/root-impl.js

@@ -86,7 +86,6 @@ import { admitPathInsideRoot } from "./root-boundary.js";
 import { listDirectoryPath, openRootDirectoryListing } from "./root-directory-list.js";
 import { statResolvedPathInRoot } from "./root-path-stat.js";
 import { entriesInRoot } from "./root-entries.js";
-import { assertMoveMutationAllowed } from "./root-move-preflight.js";
 import { assertRootIdentityCurrent, assertRootIdentityCurrentSync, assertValidRootDestinationPath, assertValidRootRelativePath, createRootObservationGuard, ensureTrailingSep, expandRelativePathWithHome, resolvePathInRoot, resolveRootContext, rootRelativeReadPath, } from "./root-context.js";
 import { errorCauseOptions, fileNotFoundError, hardlinkedPathNotAllowedError, isAlreadyExistsError, normalizePinnedPathError, normalizePinnedWriteError, outsideWorkspaceError, } from "./root-errors.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
@@ -96,7 +95,7 @@ import { registerTempPathForExit } from "./temp-cleanup.js";
 import { removePathInRootFallback, validateRemoveOptions } from "./root-remove.js";
 import { removePathInRootNative } from "./root-remove-native.js";
 import { serializePathWrite } from "./write-queue.js";
-import { verifyAtomicWriteResult } from "./root-write-verification.js";
+import { verifyAtomicWriteResult, verifyRootWritePublication } from "./root-write-verification.js";
 import { assertRootWritePathSelectionSync, assertRootWriteSelectionSync, createRootWriteSelectionForFd, prepareGuardedRootWritePathSelection, resolveGuardedWritePathInRoot, resolveGuardedWriteTargetInRoot, resolvePinnedWriteTargetInRoot, refreshRetainedRootWriteAdmission, refreshRootWritePathSelection, } from "./root-write-admission.js";
 import { prepareSharedRootWriteTarget } from "./root-write-complete-parent.js";
 import { finishRootFallbackWrite } from "./root-write-publication.js";
@@ -107,7 +106,7 @@ import { admitMoveSourceStat, movePathNative } from "./root-move-noreplace.js";
 import { admitRootReadHandle, inspectOpenedPathIdentitySync } from "./root-read-admission.js";
 import { createCopyPublicationObserver, onCopyPublication, onCopySourceAdmission } from "./copy-publication.js";
 import { writeAllToFile } from "./write-file-handle.js";
-import { createInputOptions, rethrowCreateInputError, rootWriteInput } from "./root-create-input.js";
+import { createInputOptions, rethrowCreateInputError, rootWriteInput, retainSidecarCreated } from "./root-create-input.js";
 import { assertFinalSymlinkRejected, mutationSymlinkResolution, readSymlinkResolution } from "./root-symlink-policy.js";
 import { assertExclusiveCreateLeaf } from "./exclusive-create.js";
 import { assertNoWindowsPathAlias, resolvePathPreservingWindowsRoot } from "./windows-path-alias.js";
@@ -390,11 +389,14 @@ export class RootHandle {
         const { denyMutations, mutationSymlinks } = snapshotPinnedMutationPolicy(mutationOptions.denyMutations, mutationOptions.mutationSymlinks) ?? {};
         const overwrite = options.overwrite ?? false;
         const requireNative = isFsSafeNativeRequired();
-        await assertMoveMutationAllowed(this.context, {
-            fromRelative,
-            toRelative,
-            denyMutations,
-        });
+        // Deny both routes before source alias or identity admission.
+        for (const relativePath of [fromRelative, toRelative]) {
+            const { resolved } = await resolvePathInRoot(this.context, relativePath, {
+                aliasErrorCode: "path-alias",
+                allowFinalSymlink: true,
+            });
+            await assertMutationNotDenied(resolved, denyMutations, { protectAncestors: true });
+        }
         await movePathFallback(this.context, {
             requireNative,
             fromRelative,
@@ -934,15 +936,13 @@ async function commitPinnedWriteInRoot(root, pinned, params, input) {
             rootIdentity: root.rootIdentity,
             mutationAdmission: pinned.mutationAdmission,
             assertBeforeMutation: params.assertBeforeMutation,
-            verifyPublished: async (fd, expectedIdentity, parentGuard) => {
+            verifyPublished: async (fd, expectedIdentity, parentGuard, nativeParent) => {
                 verifyingPublication = true;
                 try {
-                    await verifyAtomicWriteResult({
-                        root,
-                        targetPath: pinned.targetPath,
-                        fd,
-                        expectedIdentity,
-                        parentGuard,
+                    await verifyRootWritePublication({
+                        fd, expectedIdentity, parentGuard,
+                        nativeParent, retention: params[retainSidecarCreated],
+                        verify: () => verifyAtomicWriteResult({ root, targetPath: pinned.targetPath, fd, expectedIdentity, parentGuard }),
                     });
                 }
                 catch (error) {

package/node_modules/@openclaw/fs-safe/dist/root-paths.js

@@ -244,7 +244,7 @@ async function resolveCheckedPathsWithinRoot(params, allowMissingFallback) {
             if (!root) {
                 throw new FsSafeError("not-found", "root dir not found");
             }
-            opened = await root.open(pathResult.relativePath);
+            opened = await root.open(`./${pathResult.relativePath}`);
             resolvedPaths.push(opened.realPath);
         }
         catch (err) {

package/node_modules/@openclaw/fs-safe/dist/root-walk.js

@@ -136,7 +136,9 @@ export async function* walkRoot(root, relativePath, options) {
         let failed = false;
         let operationError;
         try {
-            const relativeDirectory = directory.split(path.sep).join(path.posix.sep);
+            const relativeDirectory = path.posix.normalize(directory.split(path.sep).join(path.posix.sep));
+            const childPrefix = relativeDirectory === "." || relativeDirectory === "./" ? ""
+                : relativeDirectory.endsWith("/") ? relativeDirectory : `${relativeDirectory}/`;
             while (true) {
                 let next;
                 try {
@@ -150,9 +152,7 @@ export async function* walkRoot(root, relativePath, options) {
                 if (next === undefined)
                     return;
                 const name = next.kind === "entry" ? next.entry.name : next.name;
-                const child = directory
-                    ? path.posix.join(relativeDirectory, name)
-                    : name;
+                const child = childPrefix + name;
                 if (next.kind === "limit") {
                     yield onLimit(child);
                     return;

package/node_modules/@openclaw/fs-safe/dist/root-write-verification.d.ts

@@ -1,6 +1,15 @@
 import { type AnyAsyncDirectoryGuard } from "./directory-guard.js";
-import type { PublishedWriteIdentity } from "./pinned-write-types.js";
+import type { NativeWriteParent, PublishedWriteIdentity } from "./pinned-write-types.js";
+import type { SidecarCreationRetention } from "./root-create-input.js";
 import { type RootContext } from "./root-context.js";
+export declare function verifyRootWritePublication(params: {
+    fd: number;
+    expectedIdentity: PublishedWriteIdentity;
+    parentGuard: AnyAsyncDirectoryGuard;
+    nativeParent?: NativeWriteParent;
+    retention?: SidecarCreationRetention;
+    verify(): Promise<void>;
+}): Promise<void>;
 export declare function verifyAtomicWriteResult(params: {
     root: RootContext;
     targetPath: string;

package/node_modules/@openclaw/fs-safe/dist/root-write-verification.js

@@ -5,10 +5,30 @@ import { FsSafeError } from "./errors.js";
 import { sameFileIdentity } from "./file-identity.js";
 import { resolveOpenedFileRealPathForFd } from "./opened-realpath.js";
 import { assertNoUnsafeDeviceReadPath, hasNodeErrorCode, isNotFoundPathError, isSymlinkOpenError } from "./path.js";
+import { createSuppressedError } from "./suppressed-error.js";
 import { resolveReadOpenFlags } from "./read-open-flags.js";
 import { assertRootIdentityCurrent } from "./root-context.js";
 import { fileNotFoundError, hardlinkedPathNotAllowedError, outsideWorkspaceError } from "./root-errors.js";
 import { admitPathInsideRoot } from "./root-boundary.js";
+export async function verifyRootWritePublication(params) {
+    try {
+        await params.verify();
+        params.retention?.retain(params.fd, params.parentGuard, params.nativeParent);
+    }
+    catch (error) {
+        if (params.retention && params.nativeParent) {
+            // Publication already happened. The creator still owns these descriptors
+            // even if opening an additional retained handle failed.
+            try {
+                params.retention.cleanup(params.fd, params.nativeParent, params.expectedIdentity);
+            }
+            catch (cleanupError) {
+                throw createSuppressedError(cleanupError, error, "sidecar retention and creator cleanup both failed");
+            }
+        }
+        throw error;
+    }
+}
 export async function verifyAtomicWriteResult(params) {
     let needsPathOpen = false;
     const assertFile = (stat) => {

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

@@ -6,6 +6,7 @@ import { recursiveMkdirPath } from "./recursive-mkdir-path.js";
 import { hasNodeErrorCode } from "./path.js";
 import { assertSafePathSegment } from "./safe-path-segment.js";
 import { assertNoWindowsPathAlias, pathForWindowsFilesystem } from "./windows-path-alias.js";
+import { privateTempDirectoryFix, secureTempDirectoryFailure } from "./temp-directory-diagnostics.js";
 import { captureSecureTempRepairAdapter, repairSecureTempDirectory, secureTempDirectoryReceipt, } from "./secure-temp-repair.js";
 export function resolveSecureTempRoot(options) {
     const { fallbackPrefix: prefix, accessSync: suppliedAccess, lstatSync: suppliedLstat, mkdirSync: suppliedMkdir, descriptor: suppliedDescriptor, getuid: suppliedGetuid, tmpdir: suppliedTmpdir, platform: suppliedPlatform, preferredDir, skipPreferredOnWindows, warn: suppliedWarn, warningPrefix: suppliedWarningPrefix, unsafeFallbackLabel: suppliedFallbackLabel, } = options;
@@ -82,8 +83,17 @@ export function resolveSecureTempRoot(options) {
             candidate = lstatSync(candidatePath);
         }
         catch (error) {
-            return { kind: hasNodeErrorCode(error, "ENOENT") ? "missing" : "invalid", error };
+            return { kind: hasNodeErrorCode(error, "ENOENT") ? "missing" : "invalid", error,
+                detail: `directory metadata could not be read; check path traversal/access permissions; ${privateTempDirectoryFix(uid)}` };
         }
+        const failureDetail = () => {
+            try {
+                return secureTempDirectoryFailure(candidate, uid, windows);
+            }
+            catch {
+                return `directory security facts could not be read; ${privateTempDirectoryFix(uid)}`;
+            }
+        };
         let receipt;
         try {
             if (descriptor && uid !== undefined) {
@@ -91,26 +101,28 @@ export function resolveSecureTempRoot(options) {
             }
             if (receipt ? (receipt.mode & 18n) !== 0n :
                 candidate.isDirectory() !== true || candidate.isSymbolicLink() !== false || !isSecureDirForUser(candidate)) {
-                return { kind: "invalid", receipt };
+                return { kind: "invalid", receipt, detail: failureDetail() };
             }
             accessSync(candidatePath, TMP_DIR_ACCESS_MODE);
             return { kind: "available", receipt };
         }
         catch (error) {
-            return { kind: "invalid", receipt, error };
+            return { kind: "invalid", receipt, error, detail: failureDetail() };
         }
     };
     const tryRepair = (candidatePath, state, finalize = false) => {
         assertNoWindowsPathAlias(candidatePath, "filesystem", "temp directory uses a Windows filesystem namespace alias", admissionPlatform);
         if (!descriptor || uid === undefined || !state.receipt) {
-            return finalize ? { kind: "invalid", error: new Error("Secure temp descriptor finalization is unavailable.") } : state;
+            return finalize ? { ...state, kind: "invalid", error: new Error("Secure temp descriptor finalization is unavailable."),
+                detail: `descriptor finalization is unavailable; ${privateTempDirectoryFix(uid)}` } : state;
         }
         try {
             repairSecureTempDirectory(candidatePath, state.receipt, uid, descriptor, () => accessSync(candidatePath, TMP_DIR_ACCESS_MODE), () => warn(`${warningPrefix} tightened permissions on temp dir: ${candidatePath}`), finalize);
             return { kind: "available" };
         }
         catch (error) {
-            return { kind: "invalid", error };
+            return { kind: "invalid", error,
+                detail: state.detail ?? `descriptor identity, permissions, or access could not be verified during repair; ${privateTempDirectoryFix(uid)}` };
         }
     };
     const ensureTrustedFallbackDir = () => {
@@ -128,7 +140,7 @@ export function resolveSecureTempRoot(options) {
                 finalize = !windows && (suppliedMkdir !== undefined || created !== undefined);
             }
             catch (cause) {
-                throw new Error(`Unable to create fallback ${unsafeFallbackLabel}: ${fallbackPath}`, { cause });
+                throw new Error(`Unable to create fallback ${unsafeFallbackLabel}: ${JSON.stringify(fallbackPath)}; check parent directory write/search access; ${privateTempDirectoryFix(uid)}`, { cause });
             }
             // A concurrent mkdir winner has no implicit ownership or mode authority.
             state = resolveDirState(entryPath);
@@ -137,7 +149,7 @@ export function resolveSecureTempRoot(options) {
         }
         state = tryRepair(entryPath, state, finalize);
         if (state.kind !== "available") {
-            throw new Error(`Unsafe fallback ${unsafeFallbackLabel}: ${fallbackPath}`, { cause: state.error });
+            throw new Error(`Unsafe fallback ${unsafeFallbackLabel}: ${JSON.stringify(fallbackPath)}; ${state.detail}`, { cause: state.error });
         }
         return fallbackPath;
     };

package/node_modules/@openclaw/fs-safe/dist/sidecar-lock-acquire.js

@@ -2,6 +2,7 @@ import fsSync from "node:fs";
 import fs from "node:fs/promises";
 import { FsSafeError } from "./errors.js";
 import { fileObservation } from "./file-observation.js";
+import { sameFileIdentityForCleanup } from "./file-identity.js";
 import { readFileHandleBounded } from "./bounded-read.js";
 import { openSidecarRoot } from "./sidecar-lock-root.js";
 import { createNativeExclusiveFile } from "./native-operations.js";
@@ -14,7 +15,8 @@ import { ancestryHasSidecarAdmission, captureSidecarAdmissionAncestry, createSid
 import { resolveSidecarLockPaths } from "./sidecar-lock-target.js";
 import { createSuppressedError } from "./suppressed-error.js";
 import { sleep } from "./timing.js";
-import { sidecarExclusiveCreate } from "./root-create-input.js";
+import { sidecarRetainedCreate } from "./root-create-input.js";
+import { cleanupCreatedSidecar, retainCreatedSidecar } from "./sidecar-lock-retained.js";
 import { stopSidecarLockMonitoring } from "./sidecar-lock-handle.js";
 export async function acquireSidecarLock(options, context) {
     const admissionAncestry = captureSidecarAdmissionAncestry();
@@ -166,6 +168,7 @@ export async function acquireSidecarLock(options, context) {
                 continue;
             }
             let handle = null;
+            let retainedSidecar;
             let createdSnapshot = null, createdHeld;
             let admissionConflict = false;
             let exclusiveCreateConflict = false;
@@ -247,7 +250,13 @@ export async function acquireSidecarLock(options, context) {
                     const relativeLockPath = relativeSidecarLockPath(lockRoot, lockPath);
                     const observation = fileObservation();
                     try {
-                        await observation.run(() => lockRoot.create(relativeLockPath, raw, { ...sidecarExclusiveCreate, mkdir: true, mode: 0o600 }));
+                        await observation.run(() => lockRoot.create(relativeLockPath, raw, {
+                            mkdir: true, mode: 0o600,
+                            ...sidecarRetainedCreate({
+                                retain(fd, parent, nativeParent) { retainedSidecar = retainCreatedSidecar(lockPath, raw, fd, parent, nativeParent); },
+                                cleanup(fd, parent, identity) { cleanupCreatedSidecar(lockPath, raw, fd, parent, identity); },
+                            }),
+                        }));
                     }
                     catch (error) {
                         // Only this invocation's failed exclusive open grants denial retry authority.
@@ -262,6 +271,7 @@ export async function acquireSidecarLock(options, context) {
                     createdSnapshot = { raw, payload, ownershipToken };
                     const opened = await openSidecarRoot(lockRoot, relativeLockPath, "unlinked");
                     if (!opened) {
+                        retainedSidecar?.settle(true, false);
                         await waitForRetry();
                         continue;
                     }
@@ -299,7 +309,11 @@ export async function acquireSidecarLock(options, context) {
                 }
                 const snapshot = { raw, payload, stat: fsSync.fstatSync(handle.fd, { bigint: true }), ownershipToken };
                 createdSnapshot = snapshot;
+                if (retainedSidecar && !sameFileIdentityForCleanup(retainedSidecar.identity, snapshot.stat)) {
+                    throw new FsSafeError("path-mismatch", "created sidecar lock identity changed before admission");
+                }
                 if (snapshot.stat.nlink === 0n) {
+                    retainedSidecar?.settle(true, false);
                     await handle.close();
                     handle = null;
                     await waitForRetry();
@@ -310,10 +324,15 @@ export async function acquireSidecarLock(options, context) {
                     admissionConflict = true;
                     throw Object.assign(new Error("sidecar lock admission changed"), { code: "EEXIST" });
                 }
+                // An open descendant file prevents Windows directory relocation. The
+                // native receipt retains its parent and verifies the leaf at settlement.
+                if (retainedSidecar && process.platform === "win32")
+                    await handle.close();
                 createdHeld = {
                     refCount: 1,
                     reentrantOwner: requestedReentrantOwner,
                     handle,
+                    retainedSidecar,
                     lockPath,
                     snapshot,
                     acquiredAt: Date.now(),
@@ -380,7 +399,10 @@ export async function acquireSidecarLock(options, context) {
                         await handle.close().catch(() => undefined);
                     }
                     // Root records use the creator receipt; partial raw writes use fd identity.
-                    if (failedSnapshot) {
+                    if (retainedSidecar) {
+                        retainedSidecar.settle(true, false);
+                    }
+                    else if (failedSnapshot) {
                         await removeSidecarLockIfUnchanged(lockPath, failedSnapshot, {
                             lockRoot,
                             parsePayload: conditionalSidecarLockParser(parserState, admission, () => admission.hasToken() && !context.held.has(normalizedTargetPath)),

package/node_modules/@openclaw/fs-safe/dist/sidecar-lock-admission.d.ts

@@ -2,10 +2,12 @@ import type { NativeFileHandle } from "./native-operations.js";
 import type { Root } from "./root-impl.js";
 import type { SidecarLockSnapshot } from "./sidecar-lock-reclaim.js";
 import type { SidecarLockHandle } from "./sidecar-lock-types.js";
+import type { RetainedSidecar } from "./sidecar-lock-retained.js";
 export type HeldSidecarLock = {
     refCount: number;
     reentrantOwner?: string;
     handle: NativeFileHandle;
+    retainedSidecar?: RetainedSidecar;
     lockPath: string;
     snapshot: SidecarLockSnapshot;
     acquiredAt: number;

package/node_modules/@openclaw/fs-safe/dist/sidecar-lock-retained.d.ts

@@ -0,0 +1,14 @@
+import type { AnyAsyncDirectoryGuard } from "./directory-guard.js";
+import type { NativeWriteParent, PublishedWriteIdentity } from "./pinned-write-types.js";
+export interface RetainedSidecar {
+    readonly identity: Readonly<{
+        dev: bigint;
+        ino: bigint;
+    }>;
+    /** Synchronous settlement also works in the process exit handler. Always closes. */
+    settle(remove: boolean, reportMismatch?: boolean): void;
+}
+/** Borrowed creation authority: never reopens a path or closes the writer's fds. */
+export declare function cleanupCreatedSidecar(lockPath: string, raw: string, fd: number, parent: NativeWriteParent, identity: PublishedWriteIdentity): void;
+/** Called only by the exclusive creator while its verified descriptor is alive. */
+export declare function retainCreatedSidecar(lockPath: string, raw: string, createdFd: number, guard: AnyAsyncDirectoryGuard, nativeParent?: NativeWriteParent): RetainedSidecar | undefined;