@openclaw/openshell-sandbox 2026.9.6 → 2026.9.7

package/node_modules/@openclaw/fs-safe/dist/root-move-noreplace.d.ts

@@ -1,13 +1,8 @@
 import { type BigIntStats, type Stats } from "node:fs";
-import { type DenyMutationPolicy } from "./deny-mutations.js";
+import type { RootMoveOptions } from "./root-options.js";
 import { type RootContext } from "./root-context.js";
-import { type MutationSymlinkPolicy } from "./root-symlink-policy.js";
 export declare function admitMoveSourceStat<T extends Stats | BigIntStats>(stat: T, overwrite?: boolean): T;
-export declare function movePathNoReplaceNative(root: RootContext, params: {
-    assertBeforeMutation?: () => void;
-    denyMutations?: DenyMutationPolicy;
-    mutationSymlinks?: MutationSymlinkPolicy;
-}, paths: {
+export declare function movePathNoReplaceNative(root: RootContext, params: Pick<RootMoveOptions, "assertBeforeMutation" | "denyMutations" | "mutationSymlinks">, paths: {
     sourcePath: string;
     sourceParentPath: string;
     targetPath: string;

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

@@ -4,7 +4,7 @@ import { assertAsyncDirectoryGuard, assertSyncDirectoryGuard } from "./directory
 import { FsSafeError } from "./errors.js";
 import { assertMutationNotDenied } from "./deny-mutations.js";
 import { openNativeParentAdmission, openNativeRootAdmission, } from "./native-parent-admission.js";
-import { getNativeBinding } from "./native.js";
+import { requireNativeBinding } from "./native.js";
 import { isNotFoundPathError } from "./path.js";
 import { assertRootIdentityCurrent, assertRootIdentityCurrentSync } from "./root-context.js";
 import { resolveRootPathSync } from "./root-path.js";
@@ -78,8 +78,8 @@ export async function movePathNoReplaceNative(root, params, paths) {
             throw error;
         // Advisory fast rejection only. renameNoReplace owns the collision decision.
     }
-    const binding = getNativeBinding();
-    if (!binding || typeof binding.renameNoReplace !== "function") {
+    const binding = requireNativeBinding();
+    if (typeof binding.renameNoReplace !== "function") {
         throw new FsSafeError("helper-unavailable", "native no-replace move is unavailable");
     }
     const rootAdmission = await openNativeRootAdmission(binding, {

package/node_modules/@openclaw/fs-safe/dist/root-observed-path.d.ts

@@ -1,7 +1,6 @@
 import { type RootPathObservationKind, type RootPathObservationReceipt } from "./root-path.js";
 import { type RootContext } from "./root-context.js";
 export type PinnedObservedPath = {
-    rootReal: string;
     resolved: string;
     receipt?: RootPathObservationReceipt;
 };

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

@@ -63,7 +63,6 @@ export async function resolvePinnedObservedPathInRoot(root, relativePath, kind)
         // A receipt is emitted only for the straight traversal whose lexical and
         // canonical cursors stayed identical and inside the checked boundary.
         return {
-            rootReal: resolved.rootCanonicalPath,
             resolved: resolved.canonicalPath,
             receipt: observed.receipt,
         };
@@ -71,7 +70,6 @@ export async function resolvePinnedObservedPathInRoot(root, relativePath, kind)
     const relativeResolved = path.relative(resolved.rootCanonicalPath, resolved.canonicalPath);
     if (relativeResolved === "" || relativeResolved === ".") {
         return {
-            rootReal: resolved.rootCanonicalPath,
             resolved: resolved.canonicalPath,
         };
     }
@@ -87,7 +85,6 @@ export async function resolvePinnedObservedPathInRoot(root, relativePath, kind)
     if (!admittedCanonicalPath)
         throw outsideWorkspaceError();
     return {
-        rootReal: resolved.rootCanonicalPath,
         resolved: admittedCanonicalPath.path,
     };
 }

package/node_modules/@openclaw/fs-safe/dist/root-path-observation.d.ts

@@ -7,14 +7,11 @@ export type RootPathObservationKind = "stat" | "directory";
 export type RootPathDirectoryObservationGuard = DirectoryObservationGuard | NativeDirectoryObservationGuard;
 export type RootPathTargetObservation = StatObservationReceipt | NativeDirectoryObservationGuard;
 /** An exact receipt owned by one stat/list operation. Never cache it. */
-export type RootPathObservationReceipt = {
-    kind: RootPathObservationKind;
-    rootGuard: DirectoryObservationGuard;
+export type RootPathObservationReceipt = Pick<RootPathObservationRequest & {
     directoryGuard: RootPathDirectoryObservationGuard;
-    directoryObserver?: NativeDirectoryObservationBackend;
     targetPath: string;
     target: RootPathTargetObservation;
-};
+}, "kind" | "rootGuard" | "directoryGuard" | "directoryObserver" | "targetPath" | "target">;
 /** A failed initial target lookup must not discard its already admitted parent. */
 export type RootPathParentObservationReceipt = Omit<RootPathObservationReceipt, "kind" | "target"> & {
     kind: "stat-parent";
@@ -24,16 +21,12 @@ export type RootPathObservationRequest = {
     rootGuard: DirectoryObservationGuard;
     directoryObserver?: NativeDirectoryObservationBackend;
 };
-export type RootPathTraversalObservation = {
+export type RootPathTraversalObservation = Omit<Partial<RootPathObservationReceipt> & {
     enabled: boolean;
     request: RootPathObservationRequest;
     targetIndex: number;
     directoryIndex: number;
-    directoryGuard?: RootPathDirectoryObservationGuard;
-    directoryObserver?: NativeDirectoryObservationBackend;
-    targetPath?: string;
-    target?: RootPathTargetObservation;
-};
+}, "kind" | "rootGuard">;
 export type RootPathObservedTraversalEntry = StatObservationReceipt | {
     stat: fs.Stats | BigIntStats;
     identity?: undefined;

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

@@ -214,8 +214,8 @@ function finalizeLexicalResolution(context, kind) {
         rootPath: context.rootPath,
         rootCanonicalPath: context.rootCanonicalPath,
         relativePath: relativeInsideRoot(context.rootCanonicalPath, context.state.canonicalCursor),
-        exists: kind.exists,
-        kind: kind.kind,
+        exists: kind !== "missing",
+        kind,
     };
 }
 function applyResolvedSymlinkHop(context, linkCanonical) {
@@ -374,12 +374,9 @@ function traverseRootPath(params, { mode = "native", observation: observationOut
     const completeObservation = observation?.enabled === true && observation.directoryGuard !== undefined &&
         observation.targetPath === state.canonicalCursor && observation.target !== undefined;
     const kind = completeObservation
-        ? {
-            exists: true,
-            kind: isNativeDirectoryObservationGuard(observation.target)
-                ? "directory"
-                : toResolvedKind(observation.target.stat),
-        }
+        ? isNativeDirectoryObservationGuard(observation.target)
+            ? "directory"
+            : toResolvedKind(observation.target.stat)
         : getPathKindSync(state.canonicalCursor, state.preserveFinalSymlink);
     if (completeObservation && observationOutput) {
         observationOutput.receipt = {
@@ -399,11 +396,11 @@ function getPathKindSync(absolutePath, preserveFinalSymlink) {
         const stat = preserveFinalSymlink
             ? fs.lstatSync(operationPath)
             : fs.statSync(operationPath);
-        return { exists: true, kind: toResolvedKind(stat) };
+        return toResolvedKind(stat);
     }
     catch (error) {
         if (isNotFoundPathError(error)) {
-            return { exists: false, kind: "missing" };
+            return "missing";
         }
         throw error;
     }

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

@@ -1,3 +1,4 @@
+import { type ResolvePathWithinRootParams } from "./path-scope-lexical.js";
 import { type DirectoryResult } from "./root-directory.js";
 export { resolvePathWithinRoot } from "./root-paths-lexical.js";
 export { ensureDirectoryWithinRoot } from "./root-directory.js";
@@ -44,12 +45,7 @@ export type PathScope = {
         mode?: number;
     }): Promise<DirectoryResult>;
 };
-export declare function resolveWritablePathWithinRoot(params: {
-    rootDir: string;
-    requestedPath: string;
-    scopeLabel: string;
-    defaultFileName?: string;
-}): Promise<{
+export declare function resolveWritablePathWithinRoot(params: ResolvePathWithinRootParams): Promise<{
     ok: true;
     path: string;
 } | {

package/node_modules/@openclaw/fs-safe/dist/root-remove-identity.d.ts

@@ -1,9 +1,7 @@
 import type { BigIntStats } from "node:fs";
 type ExactDirectoryIdentity = Readonly<Pick<BigIntStats, "dev" | "ino">>;
-export type RemovalDirectoryAssertion = Readonly<{
+export type RemovalDirectoryAssertion = ExactDirectoryIdentity & Readonly<{
     path: string;
-    dev: bigint;
-    ino: bigint;
     numericDev?: number;
     numericIno?: number;
     platform: NodeJS.Platform;

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

@@ -1,17 +1,21 @@
+import type { DirectoryObservationGuard } from "./directory-guard.js";
+import { type RootPathObservationReceipt } from "./root-path.js";
 import type { RootDirectoryListing, RootDirectoryListingOptions } from "./root-directory-list.js";
 import type { PathStat } from "./types.js";
-export type RootWalkSymlinkPolicy = "skip" | "follow-within-root";
+export type RootWalkSymlinkPolicy = "skip" | "follow-within-root" | "include";
+type LegacyRootWalkSymlinkPolicy = Exclude<RootWalkSymlinkPolicy, "include">;
 export type RootWalkLimitBehavior = "truncate" | "throw";
 export type RootWalkDirectoryErrorBehavior = "throw" | "skip-and-report";
 export type RootWalkEntryFilterResult = "include" | "skip" | "skip-subtree";
-export type RootWalkDataEntryKind = "file" | "directory" | "other";
-export type RootWalkEntryKind = RootWalkDataEntryKind | "directory-error" | "truncated";
-export type RootWalkDataEntry = {
+export type RootWalkDataEntryKind<Policy extends RootWalkSymlinkPolicy = LegacyRootWalkSymlinkPolicy> = "file" | "directory" | "other" | ("include" extends Policy ? "symlink" : never);
+export type RootWalkEntryKind<Policy extends RootWalkSymlinkPolicy = LegacyRootWalkSymlinkPolicy> = RootWalkDataEntryKind<Policy> | "directory-error" | "truncated";
+type WalkEntryOfKind<Kind extends RootWalkDataEntryKind<RootWalkSymlinkPolicy>> = {
     relativePath: string;
-    kind: RootWalkDataEntryKind;
+    kind: Kind;
     size: number;
 };
-export type RootWalkEntry = RootWalkDataEntry | {
+export type RootWalkDataEntry<Policy extends RootWalkSymlinkPolicy = LegacyRootWalkSymlinkPolicy> = WalkEntryOfKind<RootWalkDataEntryKind> | ("include" extends Policy ? WalkEntryOfKind<"symlink"> : never);
+export type RootWalkEntry<Policy extends RootWalkSymlinkPolicy = LegacyRootWalkSymlinkPolicy> = RootWalkDataEntry<Policy> | {
     relativePath: string;
     kind: "truncated";
     size: 0;
@@ -21,21 +25,24 @@ export type RootWalkEntry = RootWalkDataEntry | {
     size: 0;
     error: unknown;
 };
-export type RootWalkEntryFilter = (entry: RootWalkDataEntry) => RootWalkEntryFilterResult | Promise<RootWalkEntryFilterResult>;
-export type RootWalkOptions = {
+export type RootWalkEntryFilter<Policy extends RootWalkSymlinkPolicy = LegacyRootWalkSymlinkPolicy> = (entry: RootWalkDataEntry<Policy>) => RootWalkEntryFilterResult | Promise<RootWalkEntryFilterResult>;
+export type RootWalkOptions<Policy extends RootWalkSymlinkPolicy = LegacyRootWalkSymlinkPolicy> = {
     maxDepth?: number;
     maxEntries?: number;
     order?: "sorted" | "filesystem";
-    symlinkPolicy: RootWalkSymlinkPolicy;
+    symlinkPolicy: Policy;
     signal?: AbortSignal;
     limitBehavior?: RootWalkLimitBehavior;
-    entryFilter?: RootWalkEntryFilter;
+    entryFilter?: RootWalkEntryFilter<Policy>;
     onDirectoryError?: RootWalkDirectoryErrorBehavior;
 };
+type AnyRootWalkOptions = RootWalkOptions | RootWalkOptions<"include"> | RootWalkOptions<RootWalkSymlinkPolicy>;
+type AnyRootWalkEntry = RootWalkEntry<RootWalkSymlinkPolicy>;
 type RootWalkCapability = {
     rootReal: string;
+    observeRoot(): Promise<DirectoryObservationGuard | undefined>;
     stat(relativePath: string): Promise<PathStat>;
-    list(relativePath: string, options: RootDirectoryListingOptions): Promise<RootDirectoryListing>;
+    list(relativePath: string, options: RootDirectoryListingOptions, receipt?: RootPathObservationReceipt): Promise<RootDirectoryListing>;
 };
-export declare function walkRoot(root: RootWalkCapability, relativePath: string, options: RootWalkOptions): AsyncGenerator<RootWalkEntry>;
+export declare function walkRoot(root: RootWalkCapability, relativePath: string, options: AnyRootWalkOptions): AsyncGenerator<AnyRootWalkEntry>;
 export {};

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

@@ -1,7 +1,14 @@
 import path from "node:path";
 import { FsSafeError } from "./errors.js";
-import { resolveRootPath, ROOT_PATH_ALIAS_POLICIES } from "./root-path.js";
+import { expandRelativePathWithHome } from "./root-context.js";
+import { resolveRootPath, resolveRootPathWithObservation, ROOT_PATH_ALIAS_POLICIES, RootPathObservationError, } from "./root-path.js";
 import { createSuppressedError } from "./suppressed-error.js";
+function filterEntry(options, entry) {
+    if (entry.kind === "symlink") {
+        return options.symlinkPolicy === "include" ? options.entryFilter?.(entry) ?? "include" : "skip";
+    }
+    return options.entryFilter?.(entry) ?? "include";
+}
 function validateBudget(name, value) {
     if (value === undefined)
         return Number.POSITIVE_INFINITY;
@@ -23,7 +30,7 @@ function limitEntry(relativePath) {
     return { relativePath, kind: "truncated", size: 0 };
 }
 export async function* walkRoot(root, relativePath, options) {
-    if (!["skip", "follow-within-root"].includes(options.symlinkPolicy)) {
+    if (!["skip", "follow-within-root", "include"].includes(options.symlinkPolicy)) {
         throw new TypeError(`invalid root walk symlink policy: ${String(options.symlinkPolicy)}`);
     }
     if (options.order !== undefined && !["sorted", "filesystem"].includes(options.order)) {
@@ -61,23 +68,50 @@ export async function* walkRoot(root, relativePath, options) {
             throw error;
         return { relativePath: directory, kind: "directory-error", size: 0, error };
     };
-    async function* visit(directory, depth) {
+    async function* visit(directory, depth, admittedChildPath) {
         options.signal?.throwIfAborted();
         let listing;
+        let canonicalDirectory;
         try {
-            const skipChildSymlinks = depth > 0 && options.symlinkPolicy === "skip";
-            const resolvedDirectory = await resolveRootPath({
-                absolutePath: path.resolve(root.rootReal, directory),
+            const expandedDirectory = depth === 0 ? await expandRelativePathWithHome(directory) : directory;
+            const noFollowChildSymlinks = depth > 0 && options.symlinkPolicy !== "follow-within-root";
+            const includeChild = depth > 0 && options.symlinkPolicy === "include";
+            const resolution = {
+                absolutePath: admittedChildPath ?? path.resolve(root.rootReal, expandedDirectory),
                 rootPath: root.rootReal,
                 rootCanonicalPath: root.rootReal,
                 boundaryLabel: "root walk",
-                policy: skipChildSymlinks ? ROOT_PATH_ALIAS_POLICIES.unlinkTarget : undefined,
-            });
-            if (skipChildSymlinks && resolvedDirectory.kind === "symlink")
-                return;
+                policy: noFollowChildSymlinks ? ROOT_PATH_ALIAS_POLICIES.unlinkTarget : undefined,
+            };
+            let receipt;
+            let resolvedDirectory;
+            if (includeChild) {
+                const rootGuard = await root.observeRoot();
+                if (!rootGuard) {
+                    throw new FsSafeError("helper-unavailable", "root walk requires an exact directory observation");
+                }
+                const observed = await resolveRootPathWithObservation({
+                    ...resolution,
+                    rootIdentity: rootGuard.identity,
+                }, { kind: "directory", rootGuard });
+                resolvedDirectory = observed.resolved;
+                receipt = observed.receipt;
+            }
+            else {
+                resolvedDirectory = await resolveRootPath(resolution);
+            }
+            if (noFollowChildSymlinks && resolvedDirectory.kind === "symlink") {
+                if (options.symlinkPolicy === "skip")
+                    return;
+                throw new FsSafeError("path-mismatch", `root walk directory became a symlink: ${directory}`);
+            }
             if (!resolvedDirectory.exists || resolvedDirectory.kind !== "directory") {
                 throw new FsSafeError("not-file", `root walk path is not a directory: ${directory || "."}`);
             }
+            if (includeChild && (!receipt || receipt.directoryGuard.realPath !== resolvedDirectory.canonicalPath)) {
+                throw new FsSafeError("path-mismatch", "root walk directory observation was not retained");
+            }
+            canonicalDirectory = resolvedDirectory.canonicalPath;
             if (visitedDirectories.has(resolvedDirectory.canonicalPath)) {
                 return;
             }
@@ -87,15 +121,18 @@ export async function* walkRoot(root, relativePath, options) {
                 .relative(root.rootReal, resolvedDirectory.canonicalPath)
                 .split(path.sep)
                 .join(path.posix.sep);
-            listing = await root.list(listingDirectory, {
+            if (depth === 0 && expandedDirectory !== directory)
+                directory = listingDirectory;
+            // Resolved filesystem names are literal, not caller home-directory shorthand.
+            listing = await root.list(`./${listingDirectory}`, {
                 order: options.order ?? "sorted",
                 signal: options.signal,
                 snapshot: maxEntries === Number.POSITIVE_INFINITY,
                 admitEntry,
-            });
+            }, receipt);
         }
         catch (error) {
-            yield onDirectoryError(directory, error);
+            yield onDirectoryError(directory, error instanceof RootPathObservationError ? error.error : error);
             return;
         }
         // A thrown undefined still needs to be retained if closing also fails.
@@ -126,10 +163,9 @@ export async function* walkRoot(root, relativePath, options) {
                 const entry = next.entry;
                 let kind = entryKind(entry);
                 let size = entry.size;
-                if (kind === "symlink") {
-                    if (options.symlinkPolicy === "skip") {
-                        continue;
-                    }
+                if (kind === "symlink" && options.symlinkPolicy === "skip")
+                    continue;
+                if (kind === "symlink" && options.symlinkPolicy === "follow-within-root") {
                     const resolved = await resolveRootPath({
                         absolutePath: path.resolve(root.rootReal, child),
                         rootPath: root.rootReal,
@@ -139,12 +175,12 @@ export async function* walkRoot(root, relativePath, options) {
                     if (!resolved.exists) {
                         continue;
                     }
-                    const target = await root.stat(path.relative(root.rootReal, resolved.canonicalPath));
+                    const target = await root.stat(`./${path.relative(root.rootReal, resolved.canonicalPath)}`);
                     kind = target.isDirectory ? "directory" : target.isFile ? "file" : "other";
                     size = target.size;
                 }
                 const walkEntry = { relativePath: child, kind, size };
-                let filterResult = options.entryFilter?.(walkEntry) ?? "include";
+                let filterResult = filterEntry(options, walkEntry);
                 if (typeof filterResult !== "string") {
                     filterResult = (await filterResult) ?? "include";
                     options.signal?.throwIfAborted();
@@ -172,7 +208,7 @@ export async function* walkRoot(root, relativePath, options) {
                     yield onLimit(child);
                     return;
                 }
-                yield* visit(child, depth + 1);
+                yield* visit(child, depth + 1, options.symlinkPolicy === "include" ? path.join(canonicalDirectory, name) : undefined);
                 if (truncated)
                     return;
             }

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

@@ -14,7 +14,7 @@ import { mutationSymlinkResolution, } from "./root-symlink-policy.js";
 import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { realpathSync } from "./realpath.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
-import { assertPreparedRootWriteParentCurrent, } from "./root-write-complete-parent.js";
+import { assertPreparedRootWriteParentCurrent, writeSelectionChanged, } from "./root-write-complete-parent.js";
 export function createRootWriteSelectionForFd(selection, fd) {
     const stat = inspectFileIdentitySync(() => fsSync.fstatSync(fd, { bigint: true }));
     return Object.freeze({
@@ -22,9 +22,6 @@ export function createRootWriteSelectionForFd(selection, fd) {
         identity: Object.freeze({ dev: stat.dev, ino: stat.ino }),
     });
 }
-function writeSelectionChanged(cause) {
-    return new FsSafeError("path-mismatch", "write target changed during operation", errorCauseOptions(cause));
-}
 function inspectRegularSelectionPath(pathname, expected, follow) {
     let observed;
     try {
@@ -204,7 +201,6 @@ export async function resolveGuardedWriteTargetInRoot(root, params) {
     const relativeParent = path.relative(resolvedPath.rootReal, path.dirname(resolvedPath.resolved));
     const prepared = await preparePinnedWriteMutationAdmission({
         rootReal: resolvedPath.rootReal,
-        rootWithSep: resolvedPath.rootWithSep,
         rootIdentity: root.rootIdentity,
         resolvedTargetPath: resolvedPath.resolved,
         originalPath: params.relativePath,
@@ -291,7 +287,6 @@ export async function resolvePinnedWriteTargetInRoot(root, relativePath, request
     if (policy) {
         ({ relativeParentPath, mutationAdmission } = await preparePinnedWriteMutationAdmission({
             rootReal,
-            rootWithSep,
             rootIdentity: root.rootIdentity,
             resolvedTargetPath: resolved,
             originalPath: relativePath,

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

@@ -1,5 +1,6 @@
 import type { BigIntStats } from "node:fs";
 import { type AsyncDirectoryGuard } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
 import type { RootContext } from "./root-context.js";
 import type { GuardedRootWriteTarget } from "./root-write-admission.js";
 type PreparedWriteTargetObservation = Readonly<{
@@ -36,6 +37,7 @@ export type SharedRootWriteTarget = Readonly<{
     mutationAdmission: GuardedRootWriteTarget["mutationAdmission"];
     preparedParent?: PreparedRootWriteParent;
 }>;
+export declare function writeSelectionChanged(cause?: unknown): FsSafeError;
 export declare function assertPreparedRootWriteParentCurrent(prepared: PreparedRootWriteParent, verifyTarget?: boolean): void;
 export declare function prepareSharedRootWriteTarget(root: RootContext, params: SharedRootWriteTargetParams): Promise<SharedRootWriteTarget>;
 export {};

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

@@ -12,7 +12,7 @@ import { errorCauseOptions } from "./root-errors.js";
 import { canReuseParentWithMutationAssertion } from "./root-write-lock-binding.js";
 import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
-function writeSelectionChanged(cause) {
+export function writeSelectionChanged(cause) {
     return new FsSafeError("path-mismatch", "write target changed during operation", errorCauseOptions(cause));
 }
 function ordinarySharedWriteRoute(root, relativePath, operationTargetPath) {

package/node_modules/@openclaw/fs-safe/dist/safe-path-segment.d.ts

@@ -7,5 +7,6 @@ export declare function assertNoDriveRelativePathSegments(value: string, label:
 export declare function trimHyphenEdges(value: string): string;
 export declare function isSafePathSegment(segment: string, options?: SafePathSegmentOptions): boolean;
 export declare function assertSafePathSegment(segment: string, options?: SafePathSegmentOptions): string;
+export declare function normalizeSafePathSegment(value: string): string;
 export declare function sanitizeSafePathSegment(value: string): string | undefined;
 export declare function assertSafePathPrefix(prefix: string, options?: SafePathSegmentOptions): string;

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

@@ -1,3 +1,4 @@
+import { isWindowsReservedDeviceName } from "./device-path.js";
 import { FsSafeError } from "./errors.js";
 const SAFE_PATH_SEGMENT_PATTERN = /^[A-Za-z0-9_-][A-Za-z0-9._-]*$/;
 const SAFE_DOT_PREFIX_PATH_SEGMENT_PATTERN = /^[A-Za-z0-9._-]+$/;
@@ -34,6 +35,8 @@ export function isSafePathSegment(segment, options = {}) {
         !segment.includes("/") &&
         !segment.includes("\\") &&
         !segment.includes("\0") &&
+        // Segments are portable identifiers: CON.json and CON.<pid>.tmp name devices on Windows.
+        !isWindowsReservedDeviceName(segment) &&
         (options.allowDotPrefix === true || !segment.startsWith(".")) &&
         (options.allowDotPrefix === true
             ? SAFE_DOT_PREFIX_PATH_SEGMENT_PATTERN.test(segment)
@@ -47,13 +50,16 @@ export function assertSafePathSegment(segment, options = {}) {
     }
     return segment;
 }
-export function sanitizeSafePathSegment(value) {
+export function normalizeSafePathSegment(value) {
     const sanitized = value
         .trim()
         .replace(/[\\/]+/g, "-")
         .replace(/\0/g, "")
         .replace(/[^A-Za-z0-9._-]+/g, "-");
-    const trimmed = trimHyphenEdges(sanitized);
+    return trimHyphenEdges(sanitized);
+}
+export function sanitizeSafePathSegment(value) {
+    const trimmed = normalizeSafePathSegment(value);
     return isSafePathSegment(trimmed, { allowDotPrefix: true }) ? trimmed : undefined;
 }
 export function assertSafePathPrefix(prefix, options = {}) {

package/node_modules/@openclaw/fs-safe/dist/secret-file.d.ts

@@ -13,7 +13,11 @@ type SecretFileWriteParams = {
     dirMode?: number;
     durable?: boolean;
 };
-export declare function prepareSecretFileWrite(params: Omit<SecretFileWriteParams, "content">): Promise<{
+type SecretFileCreateParams = Omit<SecretFileWriteParams, "durable"> & {
+    /** "file" requires file synchronization; directory synchronization remains best effort. */
+    durable?: boolean | "file";
+};
+export declare function prepareSecretFileWrite(params: Pick<SecretFileWriteParams, "rootDir" | "filePath" | "mode" | "dirMode">): Promise<{
     mode: number;
     rootGuard: AsyncDirectoryGuard<BigIntStats>;
     parentGuard: AsyncDirectoryGuard<BigIntStats>;
@@ -21,5 +25,5 @@ export declare function prepareSecretFileWrite(params: Omit<SecretFileWriteParam
     finalFilePath: string;
 }>;
 export declare function writeSecretFileAtomic(params: SecretFileWriteParams): Promise<void>;
-export declare function createSecretFileAtomic(params: SecretFileWriteParams): Promise<void>;
+export declare function createSecretFileAtomic(params: SecretFileCreateParams): Promise<void>;
 export {};

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

@@ -5,8 +5,7 @@ import { recursiveMkdirPath } from "./recursive-mkdir-path.js";
 import { canonicalPathFromExistingAncestor } from "./absolute-path.js";
 import { readFileDescriptorBoundedSync } from "./bounded-read.js";
 import { assertAsyncDirectoryGuard, createAsyncDirectoryGuard, inspectDirectoryIdentity } from "./directory-guard.js";
-import { pinNodeDirectoryForMode } from "./directory-mode-node.js";
-import { assertOwnedDirectory } from "./directory-mode-owner.js";
+import { pinNodeDirectoryForMode, assertOwnedDirectory } from "./directory-mode-node.js";
 import { FsSafeError } from "./errors.js";
 import { openPinnedFileSync } from "./pinned-open.js";
 import { runPinnedWriteHelper } from "./pinned-write.js";
@@ -199,7 +198,11 @@ async function ensurePrivateDirectory(rootDir, targetDir, mode) {
     }
     return { rootGuard, parentGuard: targetGuard };
 }
-function snapshotSecretFileWriteParams(params, rootDir, filePath) {
+function snapshotSecretFileWriteParams(params) {
+    const rootDir = params.rootDir;
+    const filePath = params.filePath;
+    assertNoWindowsPathAlias(rootDir, "filesystem", "private secret root uses a Windows filesystem namespace alias");
+    assertNoWindowsPathAlias(filePath, "filesystem", "private secret path uses a Windows filesystem namespace alias");
     return {
         rootDir,
         filePath,
@@ -282,6 +285,7 @@ async function materializeSecretFileAtomic(params, createOnly) {
         mode,
         verifyPosixMode: true,
         sync: params.durable !== false,
+        strictFileSync: createOnly && params.durable === "file",
         overwrite: !createOnly,
         input: { kind: "buffer", data: typeof params.content === "string" ? params.content : Buffer.from(params.content) },
         rootIdentity: { dev: parentGuard.stat.dev, ino: parentGuard.stat.ino },
@@ -305,31 +309,23 @@ async function materializeSecretFileAtomic(params, createOnly) {
     });
 }
 export async function writeSecretFileAtomic(params) {
-    const rootDir = params.rootDir;
-    const filePath = params.filePath;
-    assertNoWindowsPathAlias(rootDir, "filesystem", "private secret root uses a Windows filesystem namespace alias");
-    assertNoWindowsPathAlias(filePath, "filesystem", "private secret path uses a Windows filesystem namespace alias");
-    const ownedParams = snapshotSecretFileWriteParams(params, rootDir, filePath);
-    const canonicalPath = await secretFileWriteQueueKey(filePath);
+    const ownedParams = snapshotSecretFileWriteParams(params);
+    const canonicalPath = await secretFileWriteQueueKey(ownedParams.filePath);
     await serializePathWrite(canonicalPath, async () => {
         await materializeSecretFileAtomic(ownedParams, false);
     });
 }
 export async function createSecretFileAtomic(params) {
     try {
-        const rootDir = params.rootDir;
-        const filePath = params.filePath;
-        assertNoWindowsPathAlias(rootDir, "filesystem", "private secret root uses a Windows filesystem namespace alias");
-        assertNoWindowsPathAlias(filePath, "filesystem", "private secret path uses a Windows filesystem namespace alias");
-        const ownedParams = snapshotSecretFileWriteParams(params, rootDir, filePath);
-        const canonicalPath = await secretFileWriteQueueKey(filePath);
+        const ownedParams = snapshotSecretFileWriteParams(params);
+        const canonicalPath = await secretFileWriteQueueKey(ownedParams.filePath);
         await serializePathWrite(canonicalPath, async () => {
             await materializeSecretFileAtomic(ownedParams, true);
         });
     }
     catch (error) {
         if ((error instanceof FsSafeError && error.code === "already-exists") ||
-            error.code === "EEXIST") {
+            error?.code === "EEXIST") {
             throw new FsSafeError("secret-exists", "Private secret file already exists.", { cause: error });
         }
         throw error;

package/node_modules/@openclaw/fs-safe/dist/secret-read-policy.js

@@ -7,7 +7,7 @@ import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
 export const DEFAULT_SECRET_FILE_MAX_BYTES = 16 * 1024;
 export function secretPathErrorCode(error) {
-    const code = error.code;
+    const code = error?.code;
     return code === "ENOENT" || code === "ENOTDIR" ? "not-found" : "invalid-path";
 }
 export function secretReadError(code, action, label, resolvedPath, error) {

package/node_modules/@openclaw/fs-safe/dist/secure-file-windows.js

@@ -1,29 +1,20 @@
-import { FsSafeError } from "./errors.js";
-import { recordFileObservationFailure } from "./file-observation.js";
+import { fileIdentityMismatchError } from "./strict-file-identity.js";
 import { getNativeBinding } from "./native.js";
 import { getFsSafeNativeConfig } from "./native-config.js";
 import { warnNativeFallback } from "./native-fallback-warning.js";
 import { inspectWindowsDescriptorCommand } from "./windows-security-command.js";
-import { validateSecureWindowsSecurityFacts } from "./windows-security-facts.js";
+import { unverified as permissionUnverified, validateSecureWindowsSecurityFacts } from "./windows-security-facts.js";
 const IDENTITY_RE = /^([0-9a-f]{8}):([0-9a-f]{16})$/;
 const TRUSTED_OWNER_CLASSES = new Set(["current-user", "system", "administrators"]);
-function permissionUnverified(message, cause) {
-    throw new FsSafeError("permission-unverified", message, cause === undefined ? {} : { cause });
-}
-function identityMismatch() {
-    const error = new FsSafeError("path-mismatch", "file identity changed or could not be verified");
-    recordFileObservationFailure(error, "identity");
-    throw error;
-}
 function isRecord(value) {
     return typeof value === "object" && value !== null;
 }
 function parseIdentity(value) {
     if (typeof value !== "string")
-        identityMismatch();
+        throw fileIdentityMismatchError();
     const match = IDENTITY_RE.exec(value);
     if (!match)
-        identityMismatch();
+        throw fileIdentityMismatchError();
     return {
         dev: BigInt(`0x${match[1]}`),
         ino: BigInt(`0x${match[2]}`),
@@ -34,7 +25,7 @@ function inspectDescriptorResult(params, result, mechanism) {
         permissionUnverified("Windows descriptor ACL facts were malformed");
     const observed = parseIdentity(result.identity);
     if (observed.dev !== params.identity.dev || observed.ino !== params.identity.ino) {
-        identityMismatch();
+        throw fileIdentityMismatchError();
     }
     const facts = validateSecureWindowsSecurityFacts(result.security);
     return {