@openclaw/openshell-sandbox 2026.9.4 → 2026.9.5

package/node_modules/@openclaw/fs-safe/dist/install-path.js

@@ -1,7 +1,9 @@
 import { createHash } from "node:crypto";
-import fs from "node:fs/promises";
+import fsSync from "node:fs";
 import path from "node:path";
 import { isPathInside } from "./path.js";
+import { realpathSync } from "./realpath.js";
+import { hasWindowsPathAlias, pathForWindowsFilesystem, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
 export function safeDirName(input) {
     const trimmed = input.trim();
     if (!trimmed) {
@@ -9,6 +11,7 @@ export function safeDirName(input) {
     }
     return trimmed.replaceAll("/", "__").replaceAll("\\", "__");
 }
+/** Legacy readable encoding; distinct IDs can share a result. Use V2 for untrusted IDs. */
 export function safePathSegmentHashed(input) {
     const trimmed = input.trim();
     const base = trimmed
@@ -19,21 +22,43 @@ export function safePathSegmentHashed(input) {
         .replaceAll(/-+$/g, "");
     const normalized = base.length > 0 ? base : "skill";
     const safe = normalized === "." || normalized === ".." ? "skill" : normalized;
-    const hash = createHash("sha256").update(trimmed).digest("hex").slice(0, 10);
-    if (safe !== trimmed) {
-        const prefix = safe.length > 50 ? safe.slice(0, 50) : safe;
-        return `${prefix}-${hash}`;
-    }
-    if (safe.length > 60) {
+    if (safe !== trimmed || safe.length > 60) {
+        const hash = createHash("sha256").update(trimmed).digest("hex").slice(0, 10);
         return `${safe.slice(0, 50)}-${hash}`;
     }
     return safe;
 }
+/**
+ * Versioned install-ID encoding: every trimmed ID receives a domain-separated
+ * SHA-256 digest. Only surrounding whitespace is intentionally equivalent.
+ */
+export function safePathSegmentHashedV2(input) {
+    const hash = createHash("sha256")
+        .update("@openclaw/fs-safe:install-path:v2\0", "utf8")
+        // UTF-16LE preserves every JavaScript code unit, including lone surrogates.
+        .update(input.trim(), "utf16le")
+        .digest("hex");
+    return `id-v2-${hash}`;
+}
 export function resolveSafeInstallDir(params) {
+    const baseDir = params.baseDir;
+    if (hasWindowsPathAlias(baseDir, "filesystem")) {
+        return { ok: false, error: params.invalidNameMessage };
+    }
     const encodedName = (params.nameEncoder ?? safeDirName)(params.id);
-    const targetDir = path.join(params.baseDir, encodedName);
-    const resolvedBase = path.resolve(params.baseDir);
+    if (hasWindowsPathAlias(encodedName, "relative")) {
+        return { ok: false, error: params.invalidNameMessage };
+    }
+    const targetDir = path.join(baseDir, encodedName);
+    if (hasWindowsPathAlias(targetDir, "filesystem")) {
+        return { ok: false, error: params.invalidNameMessage };
+    }
+    const resolvedBase = resolvePathPreservingWindowsRoot(baseDir);
     const resolvedTarget = path.resolve(targetDir);
+    if (hasWindowsPathAlias(resolvedBase, "filesystem") ||
+        hasWindowsPathAlias(resolvedTarget, "filesystem")) {
+        return { ok: false, error: params.invalidNameMessage };
+    }
     const relative = path.relative(resolvedBase, resolvedTarget);
     if (!relative ||
         relative === ".." ||
@@ -44,40 +69,58 @@ export function resolveSafeInstallDir(params) {
     return { ok: true, path: resolvedTarget };
 }
 export async function assertCanonicalPathWithinBase(params) {
-    const baseDir = path.resolve(params.baseDir);
-    const candidatePath = path.resolve(params.candidatePath);
+    const baseDirInput = params.baseDir;
+    const candidatePathInput = params.candidatePath;
+    const boundaryLabel = params.boundaryLabel;
+    const invalidPath = () => new Error(`Invalid path: must stay within ${boundaryLabel}`);
+    const assertAdmittedPath = (value) => {
+        if (hasWindowsPathAlias(value, "filesystem"))
+            throw invalidPath();
+    };
+    assertAdmittedPath(baseDirInput);
+    assertAdmittedPath(candidatePathInput);
+    const baseDir = resolvePathPreservingWindowsRoot(baseDirInput);
+    const candidatePath = resolvePathPreservingWindowsRoot(candidatePathInput);
+    assertAdmittedPath(baseDir);
+    assertAdmittedPath(candidatePath);
     if (!isPathInside(baseDir, candidatePath)) {
-        throw new Error(`Invalid path: must stay within ${params.boundaryLabel}`);
+        throw invalidPath();
     }
-    const baseLstat = await fs.lstat(baseDir);
+    const baseOperationPath = pathForWindowsFilesystem(baseDir);
+    const baseLstat = fsSync.lstatSync(baseOperationPath);
     if (baseLstat.isSymbolicLink()) {
-        const baseStat = await fs.stat(baseDir);
+        const baseStat = fsSync.statSync(baseOperationPath);
         if (!baseStat.isDirectory()) {
-            throw new Error(`Invalid ${params.boundaryLabel}: base directory must resolve to a directory`);
+            throw new Error(`Invalid ${boundaryLabel}: base directory must resolve to a directory`);
         }
     }
     else if (!baseLstat.isDirectory()) {
-        throw new Error(`Invalid ${params.boundaryLabel}: base directory must be a directory`);
+        throw new Error(`Invalid ${boundaryLabel}: base directory must be a directory`);
     }
-    const baseRealPath = await fs.realpath(baseDir);
+    const baseRealPath = realpathSync.native(baseOperationPath);
+    assertAdmittedPath(baseRealPath);
     const validateDirectory = async (dirPath) => {
-        const resolvedDirPath = path.resolve(dirPath);
-        const dirLstat = await fs.lstat(dirPath);
+        assertAdmittedPath(dirPath);
+        const resolvedDirPath = resolvePathPreservingWindowsRoot(dirPath);
+        assertAdmittedPath(resolvedDirPath);
+        const operationPath = pathForWindowsFilesystem(dirPath);
+        const dirLstat = fsSync.lstatSync(operationPath);
         if (dirLstat.isSymbolicLink()) {
             if (resolvedDirPath !== baseDir) {
-                throw new Error(`Invalid path: must stay within ${params.boundaryLabel}`);
+                throw new Error(`Invalid path: must stay within ${boundaryLabel}`);
             }
-            const dirStat = await fs.stat(dirPath);
+            const dirStat = fsSync.statSync(operationPath);
             if (!dirStat.isDirectory()) {
-                throw new Error(`Invalid path: must stay within ${params.boundaryLabel}`);
+                throw new Error(`Invalid path: must stay within ${boundaryLabel}`);
             }
         }
         else if (!dirLstat.isDirectory()) {
-            throw new Error(`Invalid path: must stay within ${params.boundaryLabel}`);
+            throw new Error(`Invalid path: must stay within ${boundaryLabel}`);
         }
-        const dirRealPath = await fs.realpath(dirPath);
+        const dirRealPath = realpathSync.native(operationPath);
+        assertAdmittedPath(dirRealPath);
         if (!isPathInside(baseRealPath, dirRealPath)) {
-            throw new Error(`Invalid path: must stay within ${params.boundaryLabel}`);
+            throw invalidPath();
         }
     };
     try {
@@ -90,5 +133,7 @@ export async function assertCanonicalPathWithinBase(params) {
             throw err;
         }
     }
-    await validateDirectory(path.dirname(candidatePath));
+    const candidateParent = path.dirname(candidatePath);
+    assertAdmittedPath(candidateParent);
+    await validateDirectory(candidateParent);
 }

package/node_modules/@openclaw/fs-safe/dist/json-document-store.d.ts

@@ -9,6 +9,8 @@ export type JsonStoreLockOptions = {
     managerKey?: string;
 };
 export type JsonFileStoreOptions = {
+    /** Overrides the parent store's durability for every JSON mutation. */
+    durable?: boolean;
     trailingNewline?: boolean;
     lock?: boolean | JsonStoreLockOptions;
 };
@@ -29,6 +31,7 @@ export type JsonStoreAdapter<T> = {
     readRequired(): Promise<T>;
     write(value: T, options?: {
         trailingNewline?: boolean;
+        durable?: boolean;
     }): Promise<void>;
 };
 export declare function createJsonStore<T>(adapter: JsonStoreAdapter<T>, options?: JsonFileStoreOptions): JsonStore<T>;

package/node_modules/@openclaw/fs-safe/dist/json-document-store.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"json-document-store.d.ts","sourceRoot":"","sources":["../src/json-document-store.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAE3D,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEtC,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AASlE,MAAM,MAAM,oBAAoB,GAAG;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,oBAAoB,CAAC;IAC7B,aAAa,CAAC,EAAE,wBAAwB,CAAC;IACzC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,IAAI,CAAC,EAAE,OAAO,GAAG,oBAAoB,CAAC;CACvC,CAAC;AAEF,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,IAAI,IAAI,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IAC/B,MAAM,CAAC,QAAQ,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAChC,YAAY,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC;IAC3B,KAAK,CAAC,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,MAAM,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,SAAS,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACpE,QAAQ,CAAC,QAAQ,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACxE,CAAC;AAEF,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC,YAAY,IAAI,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IACvC,YAAY,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC;IAC3B,KAAK,CAAC,KAAK,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE;QAAE,eAAe,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACzE,CAAC;AA2BF,wBAAgB,eAAe,CAAC,CAAC,EAC/B,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAC5B,OAAO,GAAE,oBAAyB,GACjC,SAAS,CAAC,CAAC,CAAC,CAmFd"}
+{"version":3,"file":"json-document-store.d.ts","sourceRoot":"","sources":["../src/json-document-store.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAE3D,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEtC,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AASlE,MAAM,MAAM,oBAAoB,GAAG;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,oBAAoB,CAAC;IAC7B,aAAa,CAAC,EAAE,wBAAwB,CAAC;IACzC,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,uEAAuE;IACvE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,IAAI,CAAC,EAAE,OAAO,GAAG,oBAAoB,CAAC;CACvC,CAAC;AAEF,MAAM,MAAM,SAAS,CAAC,CAAC,IAAI;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,IAAI,IAAI,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IAC/B,MAAM,CAAC,QAAQ,EAAE,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAChC,YAAY,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC;IAC3B,KAAK,CAAC,KAAK,EAAE,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/B,MAAM,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,SAAS,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IACpE,QAAQ,CAAC,QAAQ,EAAE,CAAC,EAAE,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACxE,CAAC;AAEF,MAAM,MAAM,gBAAgB,CAAC,CAAC,IAAI;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAClC,YAAY,IAAI,OAAO,CAAC,CAAC,GAAG,SAAS,CAAC,CAAC;IACvC,YAAY,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC;IAC3B,KAAK,CAAC,KAAK,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE;QAAE,eAAe,CAAC,EAAE,OAAO,CAAC;QAAC,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5F,CAAC;AA2BF,wBAAgB,eAAe,CAAC,CAAC,EAC/B,OAAO,EAAE,gBAAgB,CAAC,CAAC,CAAC,EAC5B,OAAO,GAAE,oBAAyB,GACjC,SAAS,CAAC,CAAC,CAAC,CAoFd"}

package/node_modules/@openclaw/fs-safe/dist/json-document-store.js

@@ -38,6 +38,7 @@ export function createJsonStore(adapter, options = {}) {
     async function write(value) {
         await adapter.write(value, {
             trailingNewline: options.trailingNewline ?? true,
+            durable: options.durable,
         });
     }
     async function withSerializedMutation(run) {

package/node_modules/@openclaw/fs-safe/dist/json-durable-queue-directory.js

@@ -1,10 +1,10 @@
-import fs from "node:fs/promises";
 import path from "node:path";
 import { syncDirectory } from "./directory-durability.js";
 import { isPathRelativeEscape } from "./path.js";
+import { realpathSync } from "./realpath.js";
 export async function syncQueueDirectoryCreation(dir, validationBase) {
-    const baseReal = await fs.realpath(validationBase);
-    const targetReal = await fs.realpath(dir);
+    const baseReal = realpathSync.native(validationBase);
+    const targetReal = realpathSync.native(dir);
     const relative = path.relative(baseReal, targetReal);
     if (isPathRelativeEscape(relative)) {
         throw new Error(`durable queue directory escapes validation base: ${dir}`);

package/node_modules/@openclaw/fs-safe/dist/json-durable-queue-ownership.d.ts

@@ -1,12 +1,20 @@
+import { type BigIntStats } from "node:fs";
 export type DurableQueueEntryPathsLike = {
     jsonPath: string;
     deliveredPath: string;
     processingPath?: string;
 };
+export type ValidatedDurableQueueEntryPaths = Readonly<{
+    jsonPath: string;
+    deliveredPath: string;
+    processingPath: string;
+}>;
+export declare function validateDurableQueueEntryPaths(paths: DurableQueueEntryPathsLike): ValidatedDurableQueueEntryPaths;
 export declare function durableQueueProcessingPath(paths: DurableQueueEntryPathsLike): string;
 export declare function claimDurableQueueEntry(paths: DurableQueueEntryPathsLike, options?: {
     skipUnowned?: boolean;
 }): Promise<string | null>;
+export declare function migrateDurableQueueEntry<T>(paths: DurableQueueEntryPathsLike, expected: BigIntStats, releaseReadPin: () => Promise<void>, run: (filePath: string, beforePublish: () => Promise<void>) => Promise<T>): Promise<T>;
 export declare function completeDeliveredQueueEntry(paths: DurableQueueEntryPathsLike): Promise<boolean>;
 export declare function acknowledgeDurableQueueEntry(paths: DurableQueueEntryPathsLike): Promise<void>;
 export declare function moveDurableQueueEntryToFailed(params: {

package/node_modules/@openclaw/fs-safe/dist/json-durable-queue-ownership.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"json-durable-queue-ownership.d.ts","sourceRoot":"","sources":["../src/json-durable-queue-ownership.ts"],"names":[],"mappings":"AAUA,MAAM,MAAM,0BAA0B,GAAG;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,0BAA0B,GAAG,MAAM,CAKpF;AA+DD,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,0BAA0B,EACjC,OAAO,GAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAA;CAAO,GACtC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAGxB;AAED,wBAAsB,2BAA2B,CAC/C,KAAK,EAAE,0BAA0B,GAChC,OAAO,CAAC,OAAO,CAAC,CAalB;AAED,wBAAsB,4BAA4B,CAChD,KAAK,EAAE,0BAA0B,GAChC,OAAO,CAAC,IAAI,CAAC,CAyBf;AAED,wBAAsB,6BAA6B,CAAC,MAAM,EAAE;IAC1D,KAAK,EAAE,0BAA0B,CAAC;IAClC,UAAU,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,IAAI,CAAC,CAiDhB;AAKD,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAI1D"}
+{"version":3,"file":"json-durable-queue-ownership.d.ts","sourceRoot":"","sources":["../src/json-durable-queue-ownership.ts"],"names":[],"mappings":"AAEA,OAAe,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAUnD,MAAM,MAAM,0BAA0B,GAAG;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC;AAEF,MAAM,MAAM,+BAA+B,GAAG,QAAQ,CAAC;IACrD,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;CACxB,CAAC,CAAC;AAUH,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,0BAA0B,GAChC,+BAA+B,CAkBjC;AAiBD,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,0BAA0B,GAAG,MAAM,CAIpF;AA0ED,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,0BAA0B,EACjC,OAAO,GAAE;IAAE,WAAW,CAAC,EAAE,OAAO,CAAA;CAAO,GACtC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAOxB;AAGD,wBAAsB,wBAAwB,CAAC,CAAC,EAC9C,KAAK,EAAE,0BAA0B,EACjC,QAAQ,EAAE,WAAW,EACrB,cAAc,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,EACnC,GAAG,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,GACxE,OAAO,CAAC,CAAC,CAAC,CAmCZ;AAED,wBAAsB,2BAA2B,CAC/C,KAAK,EAAE,0BAA0B,GAChC,OAAO,CAAC,OAAO,CAAC,CAclB;AAED,wBAAsB,4BAA4B,CAChD,KAAK,EAAE,0BAA0B,GAChC,OAAO,CAAC,IAAI,CAAC,CA0Bf;AAED,wBAAsB,6BAA6B,CAAC,MAAM,EAAE;IAC1D,KAAK,EAAE,0BAA0B,CAAC;IAClC,UAAU,EAAE,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,IAAI,CAAC,CAsDhB;AAKD,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAI1D"}

package/node_modules/@openclaw/fs-safe/dist/json-durable-queue-ownership.js

@@ -1,17 +1,55 @@
 import { randomUUID } from "node:crypto";
 import { withSidecarLock } from "./sidecar-lock.js";
+import fsSync, {} from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { syncDirectory } from "./directory-durability.js";
 import { FsSafeError } from "./errors.js";
 import { sameFileIdentityForCleanup, sha256Hex } from "./file-identity.js";
+import { inspectFileIdentity } from "./strict-file-identity.js";
 import { serializePathWrite } from "./write-queue.js";
+import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
+const validatedDurableQueueEntryPaths = new WeakSet();
+function assertQueuePathString(value, label) {
+    if (typeof value !== "string") {
+        throw new FsSafeError("invalid-path", `${label} must be a string`);
+    }
+}
+export function validateDurableQueueEntryPaths(paths) {
+    const jsonPath = paths.jsonPath;
+    const deliveredPath = paths.deliveredPath;
+    const requestedProcessingPath = paths.processingPath;
+    assertQueuePathString(jsonPath, "queue JSON path");
+    assertQueuePathString(deliveredPath, "queue delivered path");
+    if (requestedProcessingPath !== undefined) {
+        assertQueuePathString(requestedProcessingPath, "queue processing path");
+    }
+    assertNoWindowsPathAlias(jsonPath);
+    assertNoWindowsPathAlias(deliveredPath);
+    if (requestedProcessingPath !== undefined) {
+        assertNoWindowsPathAlias(requestedProcessingPath);
+    }
+    const processingPath = requestedProcessingPath || processingPathFromJsonPath(jsonPath);
+    const validated = Object.freeze({ deliveredPath, jsonPath, processingPath });
+    validatedDurableQueueEntryPaths.add(validated);
+    return validated;
+}
+function ownDurableQueueEntryPaths(paths) {
+    if (validatedDurableQueueEntryPaths.has(paths)) {
+        return paths;
+    }
+    return validateDurableQueueEntryPaths(paths);
+}
+function processingPathFromJsonPath(jsonPath) {
+    return jsonPath.endsWith(".json")
+        ? `${jsonPath.slice(0, -".json".length)}.processing`
+        : `${jsonPath}.processing`;
+}
 export function durableQueueProcessingPath(paths) {
-    if (paths.processingPath)
-        return paths.processingPath;
-    return paths.jsonPath.endsWith(".json")
-        ? `${paths.jsonPath.slice(0, -".json".length)}.processing`
-        : `${paths.jsonPath}.processing`;
+    const processingPath = paths.processingPath;
+    if (processingPath)
+        return processingPath;
+    return processingPathFromJsonPath(paths.jsonPath);
 }
 async function regularQueueFileIdentity(filePath) {
     const identity = await lstatOrNull(filePath);
@@ -23,18 +61,27 @@ async function regularQueueFileIdentity(filePath) {
     return identity;
 }
 async function withQueueEntryLock(paths, run) {
-    return await serializePathWrite(paths.jsonPath, async () => await withQueueTransferLock(path.resolve(paths.jsonPath), run));
+    const resolvedJsonPath = path.resolve(paths.jsonPath);
+    assertNoWindowsPathAlias(resolvedJsonPath);
+    return await serializePathWrite(paths.jsonPath, async () => await withQueueTransferLock(resolvedJsonPath, run));
 }
 async function claimDurableQueueEntryUnlocked(paths, options = {}) {
-    const processingPath = durableQueueProcessingPath(paths);
+    const processingPath = paths.processingPath;
     await recoverDurableQueueRetirement({ jsonPath: paths.jsonPath, processingPath });
     const existingProcessing = await regularQueueFileIdentity(processingPath);
     if (existingProcessing) {
         const pending = await lstatOrNull(paths.jsonPath);
-        if (pending &&
+        const retiresPending = pending !== null &&
             !pending.isSymbolicLink() &&
             pending.isFile() &&
-            sameFileIdentityForCleanup(pending, existingProcessing)) {
+            sameFileIdentityForCleanup(pending, existingProcessing);
+        if (!retiresPending ||
+            path.resolve(path.dirname(processingPath)) !== path.resolve(path.dirname(paths.jsonPath))) {
+            // An existing claim can contain a migration whose publication sync failed.
+            // Retirement already syncs this edge when both names share a parent.
+            await syncDirectory(path.dirname(processingPath));
+        }
+        if (retiresPending) {
             await retireDurableQueueSource({ jsonPath: paths.jsonPath, processingPath });
         }
         return processingPath;
@@ -53,7 +100,10 @@ async function claimDurableQueueEntryUnlocked(paths, options = {}) {
     }
     catch (error) {
         if (getErrorCode(error) === "EEXIST") {
-            return (await regularQueueFileIdentity(processingPath)) ? processingPath : null;
+            if (!(await regularQueueFileIdentity(processingPath)))
+                return null;
+            await syncDirectory(path.dirname(processingPath));
+            return processingPath;
         }
         if (getErrorCode(error) === "ENOENT")
             return null;
@@ -68,88 +118,130 @@ async function claimDurableQueueEntryUnlocked(paths, options = {}) {
     return processingPath;
 }
 export async function claimDurableQueueEntry(paths, options = {}) {
-    if (!(await lstatOrNull(path.dirname(paths.jsonPath))))
+    const validatedPaths = ownDurableQueueEntryPaths(paths);
+    if (!(await lstatOrNull(path.dirname(validatedPaths.jsonPath))))
         return null;
-    return await withQueueEntryLock(paths, async () => await claimDurableQueueEntryUnlocked(paths, options));
+    return await withQueueEntryLock(validatedPaths, async () => await claimDurableQueueEntryUnlocked(validatedPaths, options));
+}
+// The caller retains its read pin until this owner releases it or migration settles.
+export async function migrateDurableQueueEntry(paths, expected, releaseReadPin, run) {
+    const validatedPaths = ownDurableQueueEntryPaths(paths);
+    return await withQueueEntryLock(validatedPaths, async () => {
+        const processingPath = validatedPaths.processingPath;
+        const assertCurrent = async () => {
+            try {
+                await inspectFileIdentity(() => {
+                    const current = fsSync.lstatSync(processingPath, { bigint: true });
+                    if (current.isSymbolicLink() || !current.isFile() || current.nlink !== 1n) {
+                        throw new FsSafeError("path-mismatch", "queue migration requires its original processing claim");
+                    }
+                    return current;
+                }, expected);
+            }
+            catch (error) {
+                if (getErrorCode(error) === "ENOENT") {
+                    throw new FsSafeError("path-mismatch", "queue processing claim disappeared before migration", { cause: error });
+                }
+                throw error;
+            }
+        };
+        await assertCurrent();
+        return await run(processingPath, async () => {
+            await assertCurrent();
+            if (process.platform === "win32") {
+                // Windows cannot replace our still-open target. Keep the transfer lock
+                // across release and reject changes made while the async close settles.
+                await releaseReadPin();
+                await assertCurrent();
+            }
+        });
+    });
 }
 export async function completeDeliveredQueueEntry(paths) {
-    if (!(await lstatOrNull(path.dirname(paths.deliveredPath))))
+    const validatedPaths = ownDurableQueueEntryPaths(paths);
+    if (!(await lstatOrNull(path.dirname(validatedPaths.deliveredPath))))
         return false;
-    return await withQueueEntryLock(paths, async () => {
-        if (!(await regularQueueFileIdentity(paths.deliveredPath)))
+    return await withQueueEntryLock(validatedPaths, async () => {
+        if (!(await regularQueueFileIdentity(validatedPaths.deliveredPath)))
             return false;
-        if (await regularQueueFileIdentity(durableQueueProcessingPath(paths))) {
-            await fs.unlink(paths.deliveredPath);
-            await syncDirectory(path.dirname(paths.deliveredPath));
+        if (await regularQueueFileIdentity(validatedPaths.processingPath)) {
+            await fs.unlink(validatedPaths.deliveredPath);
+            await syncDirectory(path.dirname(validatedPaths.deliveredPath));
             return false;
         }
-        await fs.unlink(paths.deliveredPath);
-        await syncDirectory(path.dirname(paths.deliveredPath));
+        await fs.unlink(validatedPaths.deliveredPath);
+        await syncDirectory(path.dirname(validatedPaths.deliveredPath));
         return true;
     });
 }
 export async function acknowledgeDurableQueueEntry(paths) {
-    if (!(await lstatOrNull(path.dirname(paths.jsonPath))))
+    const validatedPaths = ownDurableQueueEntryPaths(paths);
+    if (!(await lstatOrNull(path.dirname(validatedPaths.jsonPath))))
         return;
-    await withQueueEntryLock(paths, async () => {
-        const processingPath = durableQueueProcessingPath(paths);
+    await withQueueEntryLock(validatedPaths, async () => {
+        const processingPath = validatedPaths.processingPath;
         const processing = await regularQueueFileIdentity(processingPath);
-        const delivered = await regularQueueFileIdentity(paths.deliveredPath);
+        const delivered = await regularQueueFileIdentity(validatedPaths.deliveredPath);
         if (!processing) {
             if (delivered) {
-                await fs.unlink(paths.deliveredPath);
+                await fs.unlink(validatedPaths.deliveredPath);
             }
-            await syncDirectory(path.dirname(paths.deliveredPath));
-            if (await regularQueueFileIdentity(paths.jsonPath)) {
+            await syncDirectory(path.dirname(validatedPaths.deliveredPath));
+            if (await regularQueueFileIdentity(validatedPaths.jsonPath)) {
                 throw new FsSafeError("path-mismatch", "queue acknowledgement requires a processing claim");
             }
             return;
         }
         if (delivered)
-            await fs.unlink(paths.deliveredPath);
-        await fs.rename(processingPath, paths.deliveredPath);
-        await syncDirectory(path.dirname(paths.deliveredPath));
-        await fs.unlink(paths.deliveredPath);
-        await syncDirectory(path.dirname(paths.deliveredPath));
+            await fs.unlink(validatedPaths.deliveredPath);
+        await fs.rename(processingPath, validatedPaths.deliveredPath);
+        await syncDirectory(path.dirname(validatedPaths.deliveredPath));
+        await fs.unlink(validatedPaths.deliveredPath);
+        await syncDirectory(path.dirname(validatedPaths.deliveredPath));
     });
 }
 export async function moveDurableQueueEntryToFailed(params) {
-    await withQueueEntryLock(params.paths, async () => {
-        const processingPath = durableQueueProcessingPath(params.paths);
+    const pathsInput = params.paths;
+    const paths = ownDurableQueueEntryPaths(pathsInput);
+    const failedPath = params.failedPath;
+    assertQueuePathString(failedPath, "failed queue path");
+    assertNoWindowsPathAlias(failedPath);
+    await withQueueEntryLock(paths, async () => {
+        const processingPath = paths.processingPath;
         const processing = await regularQueueFileIdentity(processingPath);
-        const existingFailed = await regularQueueFileIdentity(params.failedPath);
+        const existingFailed = await regularQueueFileIdentity(failedPath);
         if (!processing && existingFailed) {
-            await syncDirectory(path.dirname(params.failedPath));
+            await syncDirectory(path.dirname(failedPath));
             await syncDirectory(path.dirname(processingPath));
-            const recoveredFailed = await regularQueueFileIdentity(params.failedPath);
+            const recoveredFailed = await regularQueueFileIdentity(failedPath);
             if (!recoveredFailed ||
                 !sameFileIdentityForCleanup(existingFailed, recoveredFailed)) {
                 throw new FsSafeError("path-mismatch", "failed queue destination changed during recovery");
             }
-            if (await regularQueueFileIdentity(params.paths.jsonPath)) {
+            if (await regularQueueFileIdentity(paths.jsonPath)) {
                 throw new FsSafeError("already-exists", "failed queue destination already exists");
             }
             return;
         }
         const sourcePath = processing
             ? processingPath
-            : await claimDurableQueueEntryUnlocked(params.paths);
+            : await claimDurableQueueEntryUnlocked(paths);
         if (!sourcePath) {
             throw Object.assign(new Error("queue entry does not exist"), { code: "ENOENT" });
         }
         const source = await regularQueueFileIdentity(sourcePath);
-        const failed = await regularQueueFileIdentity(params.failedPath);
+        const failed = await regularQueueFileIdentity(failedPath);
         if (failed) {
             if (source && sameFileIdentityForCleanup(source, failed)) {
-                await syncDirectory(path.dirname(params.failedPath));
+                await syncDirectory(path.dirname(failedPath));
                 await fs.unlink(sourcePath);
                 await syncDirectory(path.dirname(sourcePath));
                 return;
             }
             throw new FsSafeError("already-exists", "failed queue destination already exists");
         }
-        await fs.link(sourcePath, params.failedPath);
-        await syncDirectory(path.dirname(params.failedPath));
+        await fs.link(sourcePath, failedPath);
+        await syncDirectory(path.dirname(failedPath));
         await fs.unlink(sourcePath);
         await syncDirectory(path.dirname(sourcePath));
     });
@@ -163,7 +255,7 @@ export function getErrorCode(error) {
 }
 async function lstatOrNull(filePath) {
     try {
-        return await fs.lstat(filePath, { bigint: true });
+        return fsSync.lstatSync(filePath, { bigint: true });
     }
     catch (error) {
         if (getErrorCode(error) === "ENOENT")
@@ -205,7 +297,7 @@ async function ensureRetirementRoot(jsonPath) {
         if (getErrorCode(error) !== "EEXIST")
             throw error;
     });
-    const root = await fs.lstat(rootPath, { bigint: true });
+    const root = fsSync.lstatSync(rootPath, { bigint: true });
     assertDirectory(root, "queue retirement root");
     await syncDirectory(parentPath);
     return rootPath;

package/node_modules/@openclaw/fs-safe/dist/json-durable-queue-paths.d.ts

@@ -0,0 +1,11 @@
+export type QueueValidationRoot = {
+    path: string;
+    allowSymlinkBase: boolean;
+};
+export declare function resolveQueueFilesystemPath(value: string): string;
+export declare function queueValidationRoots(queueDir: string, failedDir: string): Promise<{
+    queueRoot: QueueValidationRoot;
+    failedRoot: QueueValidationRoot;
+}>;
+export declare function queueValidationRoot(dir: string): QueueValidationRoot;
+//# sourceMappingURL=json-durable-queue-paths.d.ts.map

package/node_modules/@openclaw/fs-safe/dist/json-durable-queue-paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-durable-queue-paths.d.ts","sourceRoot":"","sources":["../src/json-durable-queue-paths.ts"],"names":[],"mappings":"AAMA,MAAM,MAAM,mBAAmB,GAAG;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,gBAAgB,EAAE,OAAO,CAAC;CAC3B,CAAC;AAEF,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAIhE;AAqBD,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC;IAAE,SAAS,EAAE,mBAAmB,CAAC;IAAC,UAAU,EAAE,mBAAmB,CAAA;CAAE,CAAC,CAU9E;AAED,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,mBAAmB,CAKpE"}

package/node_modules/@openclaw/fs-safe/dist/json-durable-queue-paths.js

@@ -0,0 +1,42 @@
+import path from "node:path";
+import { assertNoWindowsPathAlias, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
+export function resolveQueueFilesystemPath(value) {
+    const resolved = resolvePathPreservingWindowsRoot(value);
+    assertNoWindowsPathAlias(resolved);
+    return resolved;
+}
+function commonPathAncestor(paths) {
+    const resolved = paths.map(resolveQueueFilesystemPath);
+    const root = path.parse(resolved[0] ?? process.cwd()).root;
+    const parts = resolved.map((entry) => path.relative(root, entry).split(path.sep));
+    const common = [];
+    for (let index = 0; parts.every((part) => index < part.length); index++) {
+        const segment = parts[0]?.[index];
+        if (!segment || !parts.every((part) => part[index] === segment))
+            break;
+        common.push(segment);
+    }
+    return path.join(root, ...common);
+}
+function samePathRoot(paths) {
+    const roots = paths.map((entry) => path.parse(resolveQueueFilesystemPath(entry)).root);
+    const first = process.platform === "win32" ? roots[0]?.toLowerCase() : roots[0];
+    return roots.every((root) => (process.platform === "win32" ? root.toLowerCase() : root) === first);
+}
+export async function queueValidationRoots(queueDir, failedDir) {
+    if (samePathRoot([queueDir, failedDir])) {
+        const common = commonPathAncestor([queueDir, failedDir]);
+        const root = queueValidationRoot(common);
+        return { failedRoot: root, queueRoot: root };
+    }
+    return {
+        failedRoot: queueValidationRoot(failedDir),
+        queueRoot: queueValidationRoot(queueDir),
+    };
+}
+export function queueValidationRoot(dir) {
+    return {
+        path: path.parse(resolveQueueFilesystemPath(dir)).root,
+        allowSymlinkBase: process.platform === "darwin",
+    };
+}

package/node_modules/@openclaw/fs-safe/dist/json-durable-queue-read.d.ts

@@ -0,0 +1,6 @@
+import { type BigIntStats } from "node:fs";
+export declare const DEFAULT_JSON_DURABLE_QUEUE_ENTRY_MAX_BYTES: number;
+export declare function withJsonDurableQueueEntry<T, R>(filePath: string, options: {
+    maxBytes?: number;
+}, run: (entry: T, identity: BigIntStats, releaseReadPin: () => Promise<void>) => Promise<R>): Promise<R>;
+//# sourceMappingURL=json-durable-queue-read.d.ts.map

package/node_modules/@openclaw/fs-safe/dist/json-durable-queue-read.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-durable-queue-read.d.ts","sourceRoot":"","sources":["../src/json-durable-queue-read.ts"],"names":[],"mappings":"AAAA,OAAW,EAAE,KAAK,WAAW,EAAE,MAAM,SAAS,CAAC;AAO/C,eAAO,MAAM,0CAA0C,QAAmB,CAAC;AA8B3E,wBAAsB,yBAAyB,CAAC,CAAC,EAAE,CAAC,EAClD,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE;IAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,EAC9B,GAAG,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,QAAQ,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,GACxF,OAAO,CAAC,CAAC,CAAC,CA+BZ"}