@openclaw/openshell-sandbox 2026.9.5 → 2026.9.6

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

@@ -1,6 +1,8 @@
+import { type BigIntStats, type Stats } from "node:fs";
 import { type DenyMutationPolicy } from "./deny-mutations.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;
@@ -11,4 +13,3 @@ export declare function movePathNoReplaceNative(root: RootContext, params: {
     targetPath: string;
     targetParentPath: string;
 }): Promise<void>;
-//# sourceMappingURL=root-move-noreplace.d.ts.map

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

@@ -3,15 +3,16 @@ import path from "node:path";
 import { assertAsyncDirectoryGuard, assertSyncDirectoryGuard } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
 import { assertMutationNotDenied } from "./deny-mutations.js";
-import { closeNativeParentAdmission, openNativeParentAdmission, openNativeRootAdmission, } from "./native-parent-admission.js";
+import { openNativeParentAdmission, openNativeRootAdmission, } from "./native-parent-admission.js";
 import { getNativeBinding } from "./native.js";
 import { isNotFoundPathError } from "./path.js";
 import { assertRootIdentityCurrent, assertRootIdentityCurrentSync } from "./root-context.js";
 import { resolveRootPathSync } from "./root-path.js";
 import { admitPathInsideRoot } from "./root-boundary.js";
-import { fileNotFoundError, hardlinkedPathNotAllowedError, isAlreadyExistsError, normalizePinnedPathError, outsideWorkspaceError, } from "./root-errors.js";
+import { errorCauseOptions, fileNotFoundError, hardlinkedPathNotAllowedError, isAlreadyExistsError, normalizePinnedPathError, outsideWorkspaceError, } from "./root-errors.js";
 import { assertFinalSymlinkRejected } from "./root-symlink-policy.js";
 import { createSuppressedError } from "./suppressed-error.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
 function nativeParentRelativePath(rootReal, parentPath) {
     const relative = path.relative(rootReal, parentPath);
@@ -43,20 +44,28 @@ function normalizeMoveError(error) {
         return fileNotFoundError(error instanceof Error ? error : undefined);
     }
     if (nativePrimitiveUnavailable(error)) {
-        return new FsSafeError("helper-unavailable", "native no-replace move is unavailable", {
-            cause: error instanceof Error ? error : undefined,
-        });
+        return new FsSafeError("helper-unavailable", "native no-replace move is unavailable", errorCauseOptions(error));
     }
     return error;
 }
 function normalizeRenameNoReplaceError(error) {
     if (error?.code === "EINVAL") {
-        return new FsSafeError("helper-unavailable", "native no-replace move is unavailable on this filesystem", {
-            cause: error instanceof Error ? error : undefined,
-        });
+        return new FsSafeError("helper-unavailable", "native no-replace move is unavailable on this filesystem", errorCauseOptions(error));
     }
     return normalizeMoveError(error);
 }
+export function admitMoveSourceStat(stat, overwrite = false) {
+    if (stat.isSymbolicLink()) {
+        throw new FsSafeError("symlink", "symlink not allowed");
+    }
+    if (stat.isFile() && stat.nlink > 1) {
+        throw hardlinkedPathNotAllowedError();
+    }
+    if (!overwrite && stat.isDirectory()) {
+        throw new FsSafeError("invalid-path", "directory moves require overwrite: true");
+    }
+    return stat;
+}
 export async function movePathNoReplaceNative(root, params, paths) {
     try {
         fsSync.lstatSync(paths.targetPath);
@@ -104,21 +113,13 @@ export async function movePathNoReplaceNative(root, params, paths) {
         await assertRootIdentityCurrent(root);
         for (const admission of parentAdmissions)
             assertSyncDirectoryGuard(admission.guard);
+        // Capture an exact receipt only when admission must survive a callback.
         let sourceStat;
-        try {
-            sourceStat = fsSync.lstatSync(admittedSourcePath);
+        if (params.assertBeforeMutation) {
+            sourceStat = inspectFileIdentitySync(() => admitMoveSourceStat(fsSync.lstatSync(admittedSourcePath, { bigint: true })));
         }
-        catch (error) {
-            throw normalizeMoveError(error);
-        }
-        if (sourceStat.isSymbolicLink()) {
-            throw new FsSafeError("symlink", "symlink not allowed");
-        }
-        if (sourceStat.isFile() && sourceStat.nlink > 1) {
-            throw hardlinkedPathNotAllowedError();
-        }
-        if (sourceStat.isDirectory()) {
-            throw new FsSafeError("invalid-path", "directory moves require overwrite: true");
+        else {
+            admitMoveSourceStat(fsSync.lstatSync(admittedSourcePath));
         }
         assertFinalSymlinkRejected(admittedTargetPath, params.mutationSymlinks !== undefined);
         params.assertBeforeMutation?.();
@@ -143,14 +144,16 @@ export async function movePathNoReplaceNative(root, params, paths) {
             for (const admission of parentAdmissions)
                 assertSyncDirectoryGuard(admission.guard);
         }
+        // The callback can change a leaf without replacing its admitted parent.
+        if (sourceStat !== undefined) {
+            inspectFileIdentitySync(() => admitMoveSourceStat(fsSync.lstatSync(admittedSourcePath, { bigint: true })), sourceStat);
+        }
         try {
             binding.renameNoReplace(sourceParent.fd, path.basename(paths.sourcePath), targetParent.fd, path.basename(paths.targetPath));
         }
         catch (error) {
             if (isAlreadyExistsError(error) || error?.code === "ENOTEMPTY") {
-                throw new FsSafeError("already-exists", "destination exists", {
-                    cause: error instanceof Error ? error : undefined,
-                });
+                throw new FsSafeError("already-exists", "destination exists", errorCauseOptions(error));
             }
             throw normalizeRenameNoReplaceError(error);
         }
@@ -173,7 +176,7 @@ export async function movePathNoReplaceNative(root, params, paths) {
             continue;
         closedFds.add(admission.fd);
         try {
-            closeNativeParentAdmission(admission);
+            admission.close();
         }
         catch (error) {
             closeErrors.push(error);

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

@@ -5,4 +5,3 @@ export declare function assertMoveMutationAllowed(root: RootContext, params: {
     toRelative: string;
     denyMutations?: DenyMutationPolicy;
 }): Promise<void>;
-//# sourceMappingURL=root-move-preflight.d.ts.map

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

@@ -6,4 +6,3 @@ export type PinnedObservedPath = {
     receipt?: RootPathObservationReceipt;
 };
 export declare function resolvePinnedObservedPathInRoot(root: RootContext, relativePath: string, kind: RootPathObservationKind): Promise<PinnedObservedPath | undefined>;
-//# sourceMappingURL=root-observed-path.d.ts.map

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

@@ -7,7 +7,7 @@ import { admitPathInsideRoot } from "./root-boundary.js";
 import { assertRootPathObservationReceiptCurrent } from "./root-directory-list.js";
 import { RootPathObservationError, resolveRootPathWithObservation, } from "./root-path.js";
 import { createRootObservationGuard, ensureTrailingSep, expandRelativePathWithHome, } from "./root-context.js";
-import { fileNotFoundError, outsideWorkspaceError } from "./root-errors.js";
+import { errorCauseOptions, fileNotFoundError, outsideWorkspaceError } from "./root-errors.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
 export async function resolvePinnedObservedPathInRoot(root, relativePath, kind) {
     const rootGuard = await createRootObservationGuard(root);
@@ -50,9 +50,7 @@ export async function resolvePinnedObservedPathInRoot(root, relativePath, kind)
                 if (kind === "stat") {
                     throw fileNotFoundError(error.error instanceof Error ? error.error : undefined);
                 }
-                throw new FsSafeError("not-found", "directory not found", {
-                    cause: error.error instanceof Error ? error.error : undefined,
-                });
+                throw new FsSafeError("not-found", "directory not found", errorCauseOptions(error.error));
             }
             throw error.error;
         }

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

@@ -1,5 +1,5 @@
 import type { DenyMutationPolicy } from "./deny-mutations.js";
-import type { RenameIdentityPolicy } from "./pinned-write.js";
+import type { RenameIdentityPolicy } from "./pinned-write-types.js";
 import type { MutationSymlinkPolicy, SymlinkPolicy } from "./root-symlink-policy.js";
 import type { CopyCloneMode } from "./copy-policy.js";
 import type { RootCopyPublicationReceipt } from "./copy-publication.js";
@@ -50,12 +50,18 @@ export type RootWriteJsonOptions = RootWriteOptions & {
     space?: Parameters<typeof JSON.stringify>[2];
     trailingNewline?: boolean;
 };
-export type RootCreateOptions = Omit<RootWriteOptions, "overwrite">;
-export type RootCreateStreamOptions = Omit<RootCreateOptions, "encoding" | "renameIdentity"> & {
+export type RootCreateOptions = Omit<RootWriteOptions, "overwrite" | "durable"> & {
+    /** Publish complete content without replacing an existing entry, including without native support. */
+    atomic?: boolean;
+    private?: boolean;
+    /** "file" requires file synchronization; directory synchronization remains best effort. */
+    durable?: boolean | "file";
+};
+export type RootCreateStreamOptions = Omit<RootCreateOptions, "atomic" | "encoding" | "renameIdentity"> & {
     maxBytes?: number;
     signal?: AbortSignal;
 };
-export type RootCreateJsonOptions = Omit<RootWriteJsonOptions, "overwrite">;
+export type RootCreateJsonOptions = Omit<RootWriteJsonOptions, "overwrite" | "durable"> & Pick<RootCreateOptions, "atomic" | "durable" | "private">;
 export type RootAppendOptions = RootWriteOptions & {
     prependNewlineIfNeeded?: boolean;
 };
@@ -70,8 +76,9 @@ export type RootRemoveOptions = Pick<RootDefaults, "assertBeforeMutation" | "den
     maxDepth?: number;
     signal?: AbortSignal;
 };
-export type RootMkdirOptions = Pick<RootDefaults, "assertBeforeMutation" | "denyMutations" | "mutationSymlinks">;
+export type RootMkdirOptions = Pick<RootDefaults, "assertBeforeMutation" | "denyMutations" | "mutationSymlinks"> & {
+    private?: boolean;
+};
 export type RootReadParams = Omit<RootReadOptions, "nonBlockingRead">;
 export declare function readDefaults(defaults: RootDefaults): RootReadParams;
 export declare function mergeReadOptions(defaults: RootDefaults, options: RootReadOptions): RootReadParams;
-//# sourceMappingURL=root-options.d.ts.map

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

@@ -1,3 +1,4 @@
+export declare function isRootPathEscapeError(error: unknown): error is Error;
 export declare function sanitizeRootPathError(error: unknown): unknown;
 export declare function pathEscapeError(params: {
     boundaryLabel: string;
@@ -9,4 +10,3 @@ export declare function symlinkEscapeError(params: {
     rootCanonicalPath: string;
     symlinkPath: string;
 }): Error;
-//# sourceMappingURL=root-path-errors.d.ts.map

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

@@ -1,4 +1,13 @@
 import { formatErrorDetail, shortPath } from "./error-detail.js";
+const rootPathEscapeErrors = new WeakSet();
+function rootPathEscapeError(message) {
+    const error = new Error(message);
+    rootPathEscapeErrors.add(error);
+    return error;
+}
+export function isRootPathEscapeError(error) {
+    return error instanceof Error && rootPathEscapeErrors.has(error);
+}
 export function sanitizeRootPathError(error) {
     if (error instanceof Error) {
         error.message = formatErrorDetail(error.message);
@@ -6,8 +15,8 @@ export function sanitizeRootPathError(error) {
     return error;
 }
 export function pathEscapeError(params) {
-    return new Error(`Path escapes ${params.boundaryLabel} (${shortPath(params.rootPath)}): ${shortPath(params.absolutePath)}`);
+    return rootPathEscapeError(`Path escapes ${params.boundaryLabel} (${shortPath(params.rootPath)}): ${shortPath(params.absolutePath)}`);
 }
 export function symlinkEscapeError(params) {
-    return new Error(`Symlink escapes ${params.boundaryLabel} (${shortPath(params.rootCanonicalPath)}): ${shortPath(params.symlinkPath)}`);
+    return rootPathEscapeError(`Symlink escapes ${params.boundaryLabel} (${shortPath(params.rootCanonicalPath)}): ${shortPath(params.symlinkPath)}`);
 }

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

@@ -7,4 +7,6 @@ export declare function rawPathRelativeToCanonicalRoot(candidate: string, rootCa
 }): string | undefined;
 export declare function resolvePathViaExistingAncestor(targetPath: string): Promise<string>;
 export declare function resolvePathViaExistingAncestorSync(targetPath: string): string;
-//# sourceMappingURL=root-path-existing.d.ts.map
+export type RootPathMetadataMode = "native" | "ordinary";
+export declare function resolveExistingAncestor(targetPath: string, mode: RootPathMetadataMode): string;
+export declare function resolveSymlinkHopPath(symlinkPath: string, mode: RootPathMetadataMode, rejectUnresolved?: boolean): string;

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

@@ -2,10 +2,11 @@ import fs from "node:fs";
 import path from "node:path";
 import { FsSafeError } from "./errors.js";
 import { formatErrorDetail } from "./error-detail.js";
-import { isNotFoundPathError, isPathInside } from "./path.js";
+import { isNotFoundPathError, isPathInside, isSymlinkOpenError } from "./path.js";
 import { realpathSync } from "./realpath.js";
-import { assertNoWindowsPathAlias, pathForWindowsFilesystem, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
+import { assertNoWindowsPathAlias, pathForWindowsFilesystem, resolvePathFromBasePreservingWindowsRoot, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
 import { admitPathInsideRoot } from "./root-boundary.js";
+import { errorCauseOptions } from "./root-errors.js";
 export function absolutePathWithRawSegments(candidate) {
     if (path.sep !== "\\") {
         if (path.isAbsolute(candidate))
@@ -81,13 +82,9 @@ export function rawPathRelativeToCanonicalRoot(candidate, rootCanonicalPath, opt
     }
     return undefined;
 }
-function isFilesystemRoot(candidate) {
-    return path.parse(candidate).root === candidate;
-}
-async function pathExists(targetPath) {
+function pathExists(targetPath) {
     try {
-        fs.lstatSync(pathForWindowsFilesystem(targetPath));
-        return true;
+        return fs.lstatSync(pathForWindowsFilesystem(targetPath), { throwIfNoEntry: false }) !== undefined;
     }
     catch (error) {
         if (isNotFoundPathError(error)) {
@@ -97,25 +94,32 @@ async function pathExists(targetPath) {
     }
 }
 export async function resolvePathViaExistingAncestor(targetPath) {
+    return resolveExistingAncestor(targetPath, "native");
+}
+function pathExistsSync(targetPath) {
+    return fs.existsSync(pathForWindowsFilesystem(targetPath));
+}
+export function resolvePathViaExistingAncestorSync(targetPath) {
+    return resolveExistingAncestor(targetPath, "ordinary");
+}
+export function resolveExistingAncestor(targetPath, mode) {
+    const exists = mode === "native" ? pathExists : pathExistsSync;
+    const canonicalize = mode === "native" ? realpathSync.native : realpathSync;
     assertNoWindowsPathAlias(targetPath);
     const normalized = resolvePathPreservingWindowsRoot(targetPath);
     assertNoWindowsPathAlias(normalized);
     let cursor = normalized;
-    const missingSuffix = [];
-    while (!isFilesystemRoot(cursor) && !(await pathExists(cursor))) {
-        missingSuffix.unshift(path.basename(cursor));
-        const parent = path.dirname(cursor);
-        if (parent === cursor) {
-            break;
-        }
-        cursor = parent;
+    const filesystemRoot = path.parse(normalized).root;
+    while (cursor !== filesystemRoot &&
+        !exists(cursor)) {
+        cursor = path.dirname(cursor);
     }
-    if (!(await pathExists(cursor))) {
+    if (!exists(cursor)) {
         return normalized;
     }
     let rawResolvedAncestor;
     try {
-        rawResolvedAncestor = realpathSync.native(pathForWindowsFilesystem(cursor));
+        rawResolvedAncestor = canonicalize(pathForWindowsFilesystem(cursor));
     }
     catch {
         return normalized;
@@ -123,43 +127,34 @@ export async function resolvePathViaExistingAncestor(targetPath) {
     assertNoWindowsPathAlias(rawResolvedAncestor);
     const resolvedAncestor = resolvePathPreservingWindowsRoot(rawResolvedAncestor);
     assertNoWindowsPathAlias(resolvedAncestor);
-    const resolved = missingSuffix.length === 0
+    // Keep a leading suffix separator relative to the canonical ancestor.
+    const resolved = cursor === normalized
         ? resolvedAncestor
-        : path.resolve(resolvedAncestor, ...missingSuffix);
+        : path.resolve(resolvedAncestor, `.${path.sep}${normalized.slice(cursor.length)}`);
     assertNoWindowsPathAlias(resolved);
     return resolved;
 }
-export function resolvePathViaExistingAncestorSync(targetPath) {
-    assertNoWindowsPathAlias(targetPath);
-    const normalized = resolvePathPreservingWindowsRoot(targetPath);
-    assertNoWindowsPathAlias(normalized);
-    let cursor = normalized;
-    const missingSuffix = [];
-    while (!isFilesystemRoot(cursor) &&
-        !fs.existsSync(pathForWindowsFilesystem(cursor))) {
-        missingSuffix.unshift(path.basename(cursor));
-        const parent = path.dirname(cursor);
-        if (parent === cursor) {
-            break;
-        }
-        cursor = parent;
-    }
-    if (!fs.existsSync(pathForWindowsFilesystem(cursor))) {
-        return normalized;
-    }
-    let rawResolvedAncestor;
+export function resolveSymlinkHopPath(symlinkPath, mode, rejectUnresolved) {
     try {
-        rawResolvedAncestor = realpathSync(pathForWindowsFilesystem(cursor));
+        const canonicalize = mode === "native" ? realpathSync.native : realpathSync;
+        const rawRealPath = canonicalize(symlinkPath);
+        assertNoWindowsPathAlias(rawRealPath, "filesystem", "resolved symlink path uses a Windows filesystem namespace alias");
+        const realPath = resolvePathPreservingWindowsRoot(rawRealPath);
+        assertNoWindowsPathAlias(realPath, "filesystem", "resolved symlink path uses a Windows filesystem namespace alias");
+        return realPath;
     }
-    catch {
-        return normalized;
+    catch (error) {
+        if (isSymlinkOpenError(error) || (rejectUnresolved && isNotFoundPathError(error))) {
+            throw new FsSafeError("symlink", "symlink path could not be resolved", errorCauseOptions(error));
+        }
+        if (!isNotFoundPathError(error))
+            throw error;
+        const linkTarget = fs.readlinkSync(symlinkPath);
+        assertNoWindowsPathAlias(linkTarget, "filesystem", "symlink target uses a Windows filesystem namespace alias");
+        const linkDir = resolvePathPreservingWindowsRoot(path.dirname(symlinkPath));
+        const targetPath = resolvePathFromBasePreservingWindowsRoot(linkDir, linkTarget);
+        const resolved = resolveExistingAncestor(targetPath, mode);
+        assertNoWindowsPathAlias(resolved, "filesystem", "resolved symlink path uses a Windows filesystem namespace alias");
+        return resolved;
     }
-    assertNoWindowsPathAlias(rawResolvedAncestor);
-    const resolvedAncestor = resolvePathPreservingWindowsRoot(rawResolvedAncestor);
-    assertNoWindowsPathAlias(resolvedAncestor);
-    const resolved = missingSuffix.length === 0
-        ? resolvedAncestor
-        : path.resolve(resolvedAncestor, ...missingSuffix);
-    assertNoWindowsPathAlias(resolved);
-    return resolved;
 }

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

@@ -60,4 +60,3 @@ export type RootPathTraversalContext = {
 export declare function createRootPathTraversalObservation(context: RootPathTraversalContext, request?: RootPathObservationRequest): RootPathTraversalObservation | undefined;
 export declare function inspectRootPathTraversalEntry(pathname: string, directorySlot: boolean, observation: RootPathTraversalObservation): RootPathObservedTraversalEntry;
 export declare function captureRootPathObservedDirectory(observation: RootPathTraversalObservation, observed: RootPathObservedTraversalEntry, publicPath: string, canonicalPath: string, rootCanonicalPath: string, rootIdentity?: RootBoundaryIdentity): boolean;
-//# sourceMappingURL=root-path-observation.d.ts.map

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

@@ -2,4 +2,3 @@ import type { RootContext } from "./root-context.js";
 import type { RootPathObservationReceipt } from "./root-path.js";
 import type { PathStat } from "./types.js";
 export declare function statResolvedPathInRoot(root: RootContext, resolvedPath: string, receipt?: RootPathObservationReceipt): Promise<PathStat>;
-//# sourceMappingURL=root-path-stat.d.ts.map

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

@@ -1,23 +1,44 @@
 import fsSync from "node:fs";
 import path from "node:path";
 import { FsSafeError } from "./errors.js";
-import { recordFileObservationFailure } from "./file-observation.js";
+import { fileObservation, recordFileObservationFailure } from "./file-observation.js";
 import { hasNodeErrorCode, isNotFoundPathError } from "./path.js";
 import { assertRootDirectoryObservationGuard, assertRootPathObservationReceiptCurrent, createRootDirectoryObservationGuard, pathStatFromStats, } from "./root-directory-list.js";
-import { fileNotFoundError } from "./root-errors.js";
+import { errorCauseOptions, fileNotFoundError } from "./root-errors.js";
 import { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { assertStatObservationSync } from "./stat-observation.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
-async function missingObservedFileError(cause, pathname, before, assertParents) {
-    const failure = new FsSafeError("path-mismatch", "file changed during operation", {
-        cause: cause instanceof Error ? cause : undefined,
-    });
+function singleLinkFileIdentity(stat) {
+    if (!stat?.isFile() || stat.isSymbolicLink() || (stat.nlink !== 1 && stat.nlink !== 1n))
+        return;
+    const exact = (value) => typeof value === "bigint" ? value : Number.isSafeInteger(value) ? BigInt(value) : undefined;
+    const dev = exact(stat.dev), ino = exact(stat.ino);
+    if (dev === undefined || ino === undefined || dev < 0n || ino < 0n ||
+        (process.platform === "win32" && (dev === 0n || ino === 0n)))
+        return;
+    return { dev, ino };
+}
+async function captureChangedObservedFile(error, pathname, before, observed, assertParents, proof) {
+    try {
+        const previous = singleLinkFileIdentity(before), current = singleLinkFileIdentity(observed);
+        if (!previous || !current || (previous.dev === current.dev && previous.ino === current.ino))
+            return;
+        await assertParents();
+        // A changed metadata probe grants only a fresh acquisition attempt, never ownership.
+        proof.failure = { error, kind: `stat-leaf-changed:${pathname}` };
+    }
+    catch {
+        // Ambiguous file or ancestry observations retain the original public error.
+    }
+}
+async function missingObservedFileError(cause, pathname, before, assertParents, proof) {
+    const failure = new FsSafeError("path-mismatch", "file changed during operation", errorCauseOptions(cause));
     if (hasNodeErrorCode(cause, "ENOENT") && before?.isFile() && !before.isSymbolicLink() &&
         (before.nlink === 1 || before.nlink === 1n)) {
         try {
             await assertParents();
             // Metadata loss permits discarding a probe, never reading or owning a file.
-            recordFileObservationFailure(failure, `stat-leaf-missing:${pathname}`);
+            proof.failure = { error: failure, kind: `stat-leaf-missing:${pathname}` };
         }
         catch {
             // Keep the public mismatch and withhold provenance when ancestry changed.
@@ -26,6 +47,19 @@ async function missingObservedFileError(cause, pathname, before, assertParents)
     return failure;
 }
 export async function statResolvedPathInRoot(root, resolvedPath, receipt) {
+    const proof = {};
+    try {
+        // Nested observations in a hook cannot grant this invocation discard authority.
+        return await fileObservation().run(() => statObservedPathInRoot(root, resolvedPath, proof, receipt));
+    }
+    catch (error) {
+        const failure = proof.failure;
+        if (failure && failure.error === error)
+            recordFileObservationFailure(error, failure.kind);
+        throw error;
+    }
+}
+async function statObservedPathInRoot(root, resolvedPath, proof, receipt) {
     let admittedTarget = false;
     try {
         if (receipt) {
@@ -37,13 +71,21 @@ export async function statResolvedPathInRoot(root, resolvedPath, receipt) {
             if (beforeObservation)
                 await beforeObservation(resolvedPath);
             let observed;
+            let sample, samples = 0;
+            const comparison = fileObservation();
             try {
-                observed = assertStatObservationSync(bigint => bigint ? fsSync.lstatSync(resolvedPath, { bigint: true }) : fsSync.lstatSync(resolvedPath), receipt.target.identity);
+                observed = comparison.run(() => assertStatObservationSync(bigint => {
+                    sample = bigint ? fsSync.lstatSync(resolvedPath, { bigint: true }) : fsSync.lstatSync(resolvedPath);
+                    samples += 1;
+                    return sample;
+                }, receipt.target.identity));
             }
             catch (error) {
                 if (isNotFoundPathError(error)) {
-                    throw await missingObservedFileError(error, resolvedPath, "stat" in receipt.target ? receipt.target.stat : undefined, () => assertRootPathObservationReceiptCurrent(root, receipt));
+                    throw await missingObservedFileError(error, resolvedPath, "stat" in receipt.target ? receipt.target.stat : undefined, () => assertRootPathObservationReceiptCurrent(root, receipt), proof);
                 }
+                if (comparison.has(error, "identity"))
+                    await captureChangedObservedFile(error, resolvedPath, "stat" in receipt.target ? receipt.target.stat : undefined, samples === 1 ? sample : undefined, () => assertRootPathObservationReceiptCurrent(root, receipt), proof);
                 throw error;
             }
             if (observed.isSymbolicLink()) {
@@ -77,13 +119,21 @@ export async function statResolvedPathInRoot(root, resolvedPath, receipt) {
         if (beforeObservation)
             await beforeObservation(resolvedPath);
         let observed;
+        let sample, samples = 0;
+        const comparison = fileObservation();
         try {
-            observed = inspectFileIdentitySync(() => fsSync.lstatSync(resolvedPath, { bigint: true }), expected);
+            observed = comparison.run(() => inspectFileIdentitySync(() => {
+                sample = fsSync.lstatSync(resolvedPath, { bigint: true });
+                samples += 1;
+                return sample;
+            }, expected));
         }
         catch (error) {
             if (isNotFoundPathError(error)) {
-                throw await missingObservedFileError(error, resolvedPath, expected, () => assertRootDirectoryObservationGuard(root, parentGuard));
+                throw await missingObservedFileError(error, resolvedPath, expected, () => assertRootDirectoryObservationGuard(root, parentGuard), proof);
             }
+            if (comparison.has(error, "identity"))
+                await captureChangedObservedFile(error, resolvedPath, expected, samples === 1 ? sample : undefined, () => assertRootDirectoryObservationGuard(root, parentGuard), proof);
             throw error;
         }
         if (observed.isSymbolicLink()) {

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

@@ -51,4 +51,3 @@ export declare function resolveRootPathWithObservation(params: ResolveRootPathPa
 export declare function resolveRootPathForRemoval(params: ResolveRootPathParams, receipts: RemovalPathReceipts): Promise<ResolvedRootPath>;
 export declare function resolveRootPathSync(params: ResolveRootPathParams): ResolvedRootPath;
 export declare function resolveRootPathSyncWithCanonicalRootObservation(params: ResolveRootPathParams, observeRoot: (rootCanonicalPath: string) => void): ResolvedRootPath;
-//# sourceMappingURL=root-path.d.ts.map