@openclaw/openshell-sandbox 2026.10.5-beta.4 → 2026.10.10-beta.2

package/node_modules/@openclaw/fs-safe/dist/native.js

@@ -3,7 +3,7 @@ import { closeSync, openSync, readSync, readdirSync, } from "node:fs";
 import { createRequire } from "node:module";
 import { FsSafeError } from "./errors.js";
 import { captureNativeFdClose } from "./native-binding.js";
-import { getFsSafeNativeConfig } from "./native-config.js";
+import { getFsSafeNativeConfig, getNativeModeSetting } from "./native-config.js";
 const require = createRequire(import.meta.url);
 // Native registration creates process-lifetime housekeeping. Use the import
 // context rather than retaining the first operation's AsyncLocalStorage stores.
@@ -12,6 +12,62 @@ let binding;
 let loadError;
 let attempted = false;
 let loadBinding = loadBundledBinding;
+let resolvePackage = (name) => require.resolve(name);
+let loadOutcome = { reason: "not-probed" };
+let selectedTarget;
+let targetDescription;
+function loadFailure(error, packageName) {
+    try {
+        return classifyLoadFailure(error, packageName);
+    }
+    catch {
+        // Diagnostic inspection must not replace an arbitrary thrown load value.
+        return { reason: "load-failed", code: "UNKNOWN" };
+    }
+}
+function classifyLoadFailure(error, packageName) {
+    const code = typeof error === "object" && error !== null && "code" in error ? error.code : undefined;
+    // Resolution must fail for the selected package itself. An exception inside
+    // an installed package (even one naming this package) is not package omission.
+    if (code === "MODULE_NOT_FOUND" && error instanceof Error &&
+        error.message.split("\n", 1)[0] === `Cannot find module '${packageName}'`) {
+        try {
+            resolvePackage(packageName);
+        }
+        catch (resolutionError) {
+            if (resolutionError instanceof Error && "code" in resolutionError &&
+                resolutionError.code === "MODULE_NOT_FOUND" &&
+                resolutionError.message.split("\n", 1)[0] === `Cannot find module '${packageName}'`) {
+                return { reason: "package-missing" };
+            }
+        }
+    }
+    // An allowlist excludes paths, secrets and arbitrary text in exception codes.
+    const knownCodes = ["ERR_DLOPEN_FAILED", "MODULE_NOT_FOUND", "ERR_MODULE_NOT_FOUND",
+        "ERR_PACKAGE_PATH_NOT_EXPORTED", "ERR_INVALID_PACKAGE_CONFIG", "EACCES", "EPERM", "ENOENT"];
+    return { reason: "load-failed", code: typeof code === "string" && knownCodes.includes(code) ? code : "UNKNOWN" };
+}
+/** Internal view of the cached load; never attempts to load an addon. */
+export function getNativeFallbackDiagnostic(...capabilities) {
+    const setting = getNativeModeSetting();
+    const target = targetDescription === undefined ? bundledTarget() : selectedTarget;
+    const packageName = target === undefined ? undefined : nativePackageForTarget(target);
+    const manifest = require("../package.json");
+    const expected = {
+        target: targetDescription,
+        packageName,
+        packageVersion: packageName === undefined ? undefined : manifest.optionalDependencies[packageName],
+    };
+    if (setting.mode === "off")
+        return { ...expected, reason: "disabled", source: setting.source };
+    const loaded = binding;
+    if (loaded) {
+        const missing = capabilities.filter(name => typeof loaded[name] !== "function");
+        if (missing.length)
+            return { ...expected, reason: "capability-missing", capabilities: missing };
+    }
+    return { ...expected, ...loadOutcome };
+}
 function isMuslFilename(file) {
     return file.includes("libc.musl-") || file.includes("ld-musl-");
 }
@@ -127,19 +183,24 @@ function isMusl() {
     return false;
 }
 function targetFor(platform, arch, musl) {
-    if (platform === "win32" && arch === "x64")
-        return "win32-x64-msvc";
+    if (platform === "win32" && (arch === "x64" || arch === "arm64"))
+        return `win32-${arch}-msvc`;
     if (platform === "darwin" && arch === "x64")
         return "darwin-x64";
     if (platform === "darwin" && arch === "arm64")
         return "darwin-arm64";
+    if (platform === "freebsd" && (arch === "x64" || arch === "arm64"))
+        return `freebsd-${arch}`;
     if (platform === "linux" && (arch === "x64" || arch === "arm64")) {
         return `linux-${arch}-${musl ? "musl" : "gnu"}`;
     }
     return undefined;
 }
 function bundledTarget() {
-    return targetFor(process.platform, process.arch, isMusl());
+    const musl = isMusl();
+    selectedTarget = targetFor(process.platform, process.arch, musl);
+    targetDescription = selectedTarget ?? `${process.platform}-${process.arch}${process.platform === "linux" ? `-${musl ? "musl" : "gnu"}` : ""}`;
+    return selectedTarget;
 }
 function nativePackageForTarget(target) {
     return `@openclaw/fs-safe-${target}`;
@@ -147,9 +208,13 @@ function nativePackageForTarget(target) {
 function loadBundledBinding() {
     const target = bundledTarget();
     if (!target) {
+        loadOutcome = { reason: "unsupported-target" };
         throw new Error(`Unsupported OS or architecture: ${process.platform}-${process.arch}`);
     }
     const loaded = runNativeInitialization(() => require(nativePackageForTarget(target)));
+    if (typeof loaded.closeOwnedFd !== "function") {
+        loadOutcome = { reason: "capability-missing", capabilities: ["closeOwnedFd"] };
+    }
     captureNativeFdClose(loaded);
     return loaded;
 }
@@ -166,7 +231,24 @@ export function __nativeLoaderDetectorsForTest() {
 export function __nativeTargetForTest(platform, arch, musl = false) {
     return targetFor(platform, arch, musl);
 }
-export function getNativeBinding() {
+export function selectNativeBinding(native, ...capabilities) {
+    if (!native)
+        return undefined;
+    const missing = capabilities.filter((name) => typeof native[name] !== "function");
+    if (missing.length === 0)
+        return native;
+    if (getFsSafeNativeConfig().mode === "require") {
+        throw new FsSafeError("helper-unavailable", `native fs-safe capabilities unavailable: ${missing.join(", ")}`);
+    }
+    return undefined;
+}
+export function assertNativeCapabilities(native, ...capabilities) {
+    const missing = capabilities.filter((name) => typeof native[name] !== "function");
+    if (missing.length) {
+        throw new FsSafeError("helper-unavailable", `native fs-safe capabilities unavailable: ${missing.join(", ")}`);
+    }
+}
+export function getNativeBinding(...capabilities) {
     const { mode } = getFsSafeNativeConfig();
     if (mode === "off")
         return undefined;
@@ -174,15 +256,23 @@ export function getNativeBinding() {
         attempted = true;
         try {
             const loaded = loadBinding();
+            if (typeof loaded.closeOwnedFd !== "function") {
+                loadOutcome = { reason: "capability-missing", capabilities: ["closeOwnedFd"] };
+            }
             captureNativeFdClose(loaded);
             binding = loaded;
+            loadOutcome = { reason: "loaded" };
         }
         catch (error) {
             loadError = error;
+            if (loadOutcome.reason === "not-probed") {
+                selectedTarget ??= bundledTarget();
+                loadOutcome = loadFailure(error, nativePackageForTarget(selectedTarget ?? `${process.platform}-${process.arch}`));
+            }
         }
     }
     if (binding)
-        return binding;
+        return selectNativeBinding(binding, ...capabilities);
     if (mode === "require") {
         throw new FsSafeError("helper-unavailable", "native fs-safe helper is unavailable", {
             cause: loadError,
@@ -190,8 +280,8 @@ export function getNativeBinding() {
     }
     return undefined;
 }
-export function requireNativeBinding() {
-    const native = getNativeBinding();
+export function requireNativeBinding(...capabilities) {
+    const native = getNativeBinding(...capabilities);
     if (!native) {
         throw new FsSafeError("helper-unavailable", "native fs-safe helper is unavailable", {
             cause: loadError,
@@ -199,15 +289,23 @@ export function requireNativeBinding() {
     }
     return native;
 }
-export function __setNativeLoaderForTest(loader) {
+export function __setNativeLoaderForTest(loader, resolver) {
     binding = undefined;
     loadError = undefined;
     attempted = false;
     loadBinding = loader;
+    loadOutcome = { reason: "not-probed" };
+    selectedTarget = undefined;
+    targetDescription = undefined;
+    resolvePackage = resolver ?? ((name) => require.resolve(name));
 }
 export function __resetNativeLoaderForTest() {
     binding = undefined;
     loadError = undefined;
     attempted = false;
     loadBinding = loadBundledBinding;
+    loadOutcome = { reason: "not-probed" };
+    selectedTarget = undefined;
+    targetDescription = undefined;
+    resolvePackage = (name) => require.resolve(name);
 }

package/node_modules/@openclaw/fs-safe/dist/opened-realpath.js

@@ -26,7 +26,15 @@ export async function resolveOpenedFileRealPathForFd(fd, handleStat, ioPath) {
         : [];
     for (const fdPath of fdCandidates) {
         try {
-            const fdRealPath = realpathSync.native(fdPath);
+            // Linux procfs already reports the descriptor's physical pathname. Keep
+            // the fresh identity check without walking that canonical path again.
+            const fdLink = fdPath.startsWith("/proc/") ? fsSync.readlinkSync(fdPath) : undefined;
+            // The deletion suffix can also name a live entry or a symlink. Preserve
+            // canonicalization for that ambiguous spelling, including literal names.
+            const fdRealPath = fdLink !== undefined && !fdLink.endsWith(" (deleted)")
+                ? fdLink : realpathSync.native(fdPath);
+            if (!path.isAbsolute(fdRealPath))
+                continue;
             const fdRealStat = statOptions ? fsSync.statSync(fdRealPath, statOptions) : fsSync.statSync(fdRealPath);
             if (sameFileIdentity(handleStat, fdRealStat)) {
                 return { realPath: fdRealPath, stat: fdRealStat };

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

@@ -1,3 +1,4 @@
+import fs from "node:fs";
 import { FsSafeError } from "./errors.js";
 import { assertSynchronousCallbackResult } from "./mutation-authority.js";
 import { readFileWindowFully } from "./positional-read.js";
@@ -10,7 +11,9 @@ export async function overwriteFileHandle(handle, data, options = {}) {
     const beforeWrite = options.beforeWrite;
     const payload = data.subarray(0, data.byteLength);
     const payloadBytes = payload.byteLength;
-    const stat = await handle.stat();
+    const fd = handle.fd;
+    // Keep FileHandle's closed-handle error while avoiding a metadata I/O hop.
+    const stat = fd < 0 ? await handle.stat() : fs.fstatSync(fd);
     if (!stat.isFile()) {
         throw new FsSafeError("not-file", "overwrite handle must be a regular file");
     }

package/node_modules/@openclaw/fs-safe/dist/owner-dacl-batch.js

@@ -57,7 +57,7 @@ export async function readOwnerAndDaclBatch(paths, options = {}) {
         if (config.mode === "require") {
             throw new FsSafeError("helper-unavailable", "Windows owner and DACL facts require an up-to-date native helper");
         }
-        warnNativeFallback("windows-owner-dacl", "Windows owner and DACL inspection uses a slower built-in system command.");
+        warnNativeFallback("windows-owner-dacl", "Windows owner and DACL inspection launches the packaged .NET helper for each check.", "readOwnerAndDacl");
     }
     const facts = await readWindowsSecurityFactsBatch(selected, { timeoutMs, native: useNative, mode: config.mode });
     return facts.map(projectOwnerAndDacl);

package/node_modules/@openclaw/fs-safe/dist/owner-dacl.js

@@ -15,7 +15,7 @@ export function readOwnerAndDacl(targetPath) {
         if (getFsSafeNativeConfig().mode === "require") {
             throw new FsSafeError("helper-unavailable", "Windows owner and DACL facts require an up-to-date native helper");
         }
-        warnNativeFallback("windows-owner-dacl", "Windows owner and DACL inspection uses a slower built-in system command.");
+        warnNativeFallback("windows-owner-dacl", "Windows owner and DACL inspection launches the packaged .NET helper for each check.", "readOwnerAndDacl");
     }
     const facts = typeof inspect === "function" ? inspect.call(native, targetPath) : readWindowsSecurityFactsCommand(targetPath);
     return projectOwnerAndDacl(facts);

package/node_modules/@openclaw/fs-safe/dist/permission-exec.js

@@ -1,7 +1,9 @@
+import { assertWindowsHelperAllowed } from "./windows-appcontainer.js";
 import { execFile } from "node:child_process";
 import path from "node:path";
 import { promisify, types as utilTypes } from "node:util";
 import { formatErrorDetail } from "./error-detail.js";
+import { windowsSecurityHelperPath, explainWindowsSecurityHelperFailure } from "./windows-security-helper.js";
 const execFileAsync = promisify(execFile);
 export const DEFAULT_PERMISSION_EXEC_TIMEOUT_MS = 30_000;
 export function formatPermissionErrorDetail(value) {
@@ -179,6 +181,7 @@ export function getPermissionCommandFailure(error, command, durationMs) {
     return { command, durationMs: Math.round(durationMs), ...detail };
 }
 export async function executePermissionCommand(command, args, timeoutMs = DEFAULT_PERMISSION_EXEC_TIMEOUT_MS) {
+    assertWindowsHelperAllowed();
     const startedAt = performance.now();
     try {
         return (await execFileAsync(command, args, {
@@ -190,6 +193,11 @@ export async function executePermissionCommand(command, args, timeoutMs = DEFAUL
         }));
     }
     catch (err) {
-        throw new PermissionCommandError(command, performance.now() - startedAt, err, timeoutMs);
+        const error = new PermissionCommandError(command, performance.now() - startedAt, err, timeoutMs);
+        if (command === windowsSecurityHelperPath() &&
+            ["ENOENT", "EACCES", "ENOEXEC"].includes(dataProperty(err, "code")?.value)) {
+            explainWindowsSecurityHelperFailure(error);
+        }
+        throw error;
     }
 }

package/node_modules/@openclaw/fs-safe/dist/permissions-public.d.ts

@@ -3,3 +3,4 @@ export type { PermissionCommandFailure } from "./permission-exec.js";
 export { createPrivateDirectory, type CreatePrivateDirectoryOptions, } from "./private-directory.js";
 export { readOwnerAndDacl, type OwnerAndDaclResult, type WindowsAccessControlEntry, type WindowsAceFlags, } from "./owner-dacl.js";
 export { readOwnerAndDaclBatch } from "./owner-dacl-batch.js";
+export { inspectDarwinAcl, type DarwinAclInspection } from "./darwin-acl.js";

package/node_modules/@openclaw/fs-safe/dist/permissions-public.js

@@ -2,3 +2,4 @@ export { formatOctal, formatPermissionDetail, formatPermissionRemediation, inspe
 export { createPrivateDirectory, } from "./private-directory.js";
 export { readOwnerAndDacl, } from "./owner-dacl.js";
 export { readOwnerAndDaclBatch } from "./owner-dacl-batch.js";
+export { inspectDarwinAcl } from "./darwin-acl.js";

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

@@ -1,10 +1,12 @@
 import os from "node:os";
+import { FsSafeError } from "./errors.js";
 import { getNativeBinding } from "./native.js";
 import { executePermissionCommand } from "./permission-exec.js";
 import { safeStat } from "./permissions.js";
 import { normalizeLowercaseStringOrEmpty } from "./string-coerce.js";
 import { resolveWindowsSystemCommand } from "./windows-command.js";
 import { inspectWindowsOwner } from "./windows-owner.js";
+import { assertWindowsAclRemediationAllowed } from "./windows-appcontainer.js";
 import { hasWindowsPathAlias } from "./windows-path-alias.js";
 const INHERIT_FLAGS = new Set(["I", "OI", "CI", "IO", "NP"]);
 const WORLD_PRINCIPALS = new Set(["everyone", "users", "builtin\\users", "authenticated users", "nt authority\\authenticated users", "anonymous logon", "nt authority\\anonymous logon", "guests", "builtin\\guests", "interactive", "nt authority\\interactive", "network", "nt authority\\network", "local"]);
@@ -40,30 +42,29 @@ const normalize = (value) => normalizeLowercaseStringOrEmpty(value);
 const defaultWindowsUserInfo = () => os.userInfo();
 const defaultPermissionExec = executePermissionCommand;
 function inspectWindowsPermissionsNative(targetPath, unverified) {
-    const native = getNativeBinding();
+    const native = getNativeBinding("readOwnerAndDacl");
     if (!native)
         return undefined;
-    try {
-        const facts = native.readOwnerAndDacl(targetPath);
-        if (facts.fallbackRequired)
-            return undefined;
-        return {
-            ...unverified,
-            source: "windows-acl",
-            worldWritable: facts.worldWritable,
-            groupWritable: facts.groupWritable,
-            worldReadable: facts.worldReadable,
-            groupReadable: facts.groupReadable,
-            ownerSid: facts.ownerSid,
-            ownerTrusted: facts.ownerClass !== "foreign",
-            aclSummary: `native owner=${facts.ownerClass} world=` +
-                `${facts.worldReadable ? "r" : "-"}${facts.worldWritable ? "w" : "-"} ` +
-                `group=${facts.groupReadable ? "r" : "-"}${facts.groupWritable ? "w" : "-"}`,
-        };
-    }
-    catch {
+    const facts = native.readOwnerAndDacl(targetPath);
+    if (facts.fallbackRequired) {
+        if (facts.currentAppContainerSid) {
+            throw new FsSafeError("helper-unavailable", "AppContainer ACL facts require an unavailable external helper");
+        }
         return undefined;
     }
+    return {
+        ...unverified,
+        source: "windows-acl",
+        worldWritable: facts.worldWritable,
+        groupWritable: facts.groupWritable,
+        worldReadable: facts.worldReadable,
+        groupReadable: facts.groupReadable,
+        ownerSid: facts.ownerSid,
+        ownerTrusted: facts.ownerClass !== "foreign",
+        aclSummary: `native owner=${facts.ownerClass} world=` +
+            `${facts.worldReadable ? "r" : "-"}${facts.worldWritable ? "w" : "-"} ` +
+            `group=${facts.groupReadable ? "r" : "-"}${facts.groupWritable ? "w" : "-"}`,
+    };
 }
 export async function inspectWindowsPermissions(targetPath, unverified, opts) {
     if (hasWindowsPathAlias(targetPath, "filesystem", "win32")) {
@@ -250,7 +251,38 @@ function summarizeWindowsOwnerAcl(owner) {
             canWrite: (ace.mask & 0x500d_0156) !== 0,
         };
     });
-    return { ok: true, entries, ...summarizeWindowsAcl(entries, { USERSID: owner.currentUserSid }) };
+    const summary = summarizeWindowsAcl(entries, { USERSID: owner.currentUserSid });
+    if (owner.currentAppContainerSid) {
+        const own = summary.untrustedGroup.filter(entry => entry.sid === owner.currentAppContainerSid);
+        summary.trusted.push(...own);
+        summary.untrustedGroup = summary.untrustedGroup.filter(entry => entry.sid !== owner.currentAppContainerSid);
+    }
+    return { ok: true, entries, ...summary };
+}
+function hasUnmergedAppContainerAces(facts) {
+    // These unique full-control allow entries cannot be merged or have their masks
+    // rewritten by .NET's ACL normalization. SID trust stays with the summary owner.
+    const inheritance = facts.aces[0]?.flags.raw;
+    return !!facts.currentAppContainerSid && (inheritance === 0 || inheritance === 3) &&
+        new Set(facts.aces.map(ace => ace.sid)).size === facts.aces.length &&
+        facts.aces.every(ace => ace.aceType === "allow" && ace.mask === 0x001f01ff &&
+            ace.flags.raw === inheritance);
+}
+function compareWindowsSids(left, right) {
+    const a = left.split("-").slice(2).map(Number);
+    const b = right.split("-").slice(2).map(Number);
+    // Match .NET Framework SecurityIdentifier.CompareTo: authority, subauthority
+    // count, then signed 32-bit subtraction for each subauthority.
+    if (a[0] !== b[0])
+        return a[0] < b[0] ? -1 : 1;
+    if (a.length !== b.length)
+        return a.length - b.length;
+    for (let index = 1; index < a.length; index++) {
+        const difference = ((a[index] | 0) - (b[index] | 0)) | 0;
+        if (difference !== 0)
+            return difference;
+    }
+    return 0;
 }
 export async function inspectWindowsAcl(targetPath, opts) {
     if (opts?.principalTranslationFailed) {
@@ -262,33 +294,35 @@ export async function inspectWindowsAcl(targetPath, opts) {
         return summarizeWindowsOwnerAcl({ error: String(error), errorCause: error });
     }
     let owner;
-    if (process.platform === "win32" && opts?.env === undefined && opts?.exec === undefined) {
-        try {
-            const native = getNativeBinding();
-            const stat = native && await safeStat(targetPath);
-            // Keep the named-query behavior for leaf links; the native reader follows them.
-            const facts = stat?.ok && !stat.isSymlink ? native?.readOwnerAndDacl(targetPath) : undefined;
-            if (facts && !facts.fallbackRequired && facts.isLocal && facts.aceListComplete && facts.unsupportedAceTypes.length === 0 &&
-                facts.aces.every(ace => ace.flags.inherited && ace.mask !== 0)) {
-                // .NET normalizes explicit ACEs, but retains nonzero inherited ACEs in
-                // their original order without merging them. Other forms keep its query.
-                // Adapt descriptor facts only: the public summary owns its SID and rights
-                // classification, which differs from the native secure-read policy.
-                owner = {
-                    daclPresent: facts.daclPresent,
-                    currentUserSid: facts.currentUserSid,
-                    aces: facts.aces.map(ace => ({
-                        sid: ace.sid,
-                        mask: ace.mask,
-                        deny: ace.aceType === "deny",
-                        inheritOnly: ace.flags.inheritOnly,
-                    })),
-                };
-            }
+    if (process.platform === "win32" && opts?.exec === undefined) {
+        const native = getNativeBinding("readOwnerAndDacl");
+        const stat = native && await safeStat(targetPath);
+        // Keep the named-query behavior for leaf links; the native reader follows them.
+        const facts = stat?.ok && !stat.isSymlink ? native?.readOwnerAndDacl(targetPath) : undefined;
+        const explicitAppContainer = facts && hasUnmergedAppContainerAces(facts);
+        if (facts && !facts.fallbackRequired && facts.isLocal && facts.aceListComplete && facts.unsupportedAceTypes.length === 0 &&
+            (facts.aces.every(ace => ace.flags.inherited && ace.mask !== 0) || explicitAppContainer)) {
+            // .NET normalizes explicit ACEs, but retains nonzero inherited ACEs in
+            // their original order without merging them. Other forms keep its query.
+            // Adapt descriptor facts only: the public summary owns its SID and rights
+            // classification, which differs from the native secure-read policy.
+            const aces = explicitAppContainer
+                ? [...facts.aces].sort((a, b) => compareWindowsSids(a.sid, b.sid)) : facts.aces;
+            owner = {
+                daclPresent: facts.daclPresent,
+                currentUserSid: facts.currentUserSid,
+                currentAppContainerSid: facts.currentAppContainerSid ?? undefined,
+                sid: facts.ownerSid,
+                aces: aces.map(ace => ({
+                    sid: ace.sid,
+                    mask: ace.mask,
+                    deny: ace.aceType === "deny",
+                    inheritOnly: ace.flags.inheritOnly,
+                })),
+            };
         }
-        catch {
-            // Preserve this inspector's structured fallback and command diagnostics
-            // when the optional helper or native descriptor query is unavailable.
+        else if (facts?.currentAppContainerSid) {
+            throw new FsSafeError("helper-unavailable", "AppContainer ACL normalization requires an unavailable external helper");
         }
     }
     owner ??= await inspectWindowsOwner({ targetPath, env: opts?.env, exec: opts?.exec ?? defaultPermissionExec });
@@ -304,6 +338,8 @@ export function formatWindowsAclSummary(summary) {
     return untrusted.length === 0 ? "trusted-only" : untrusted.map((entry) => `${entry.principal}:${entry.rawRights}`).join(", ");
 }
 export function formatIcaclsResetCommand(targetPath, opts) {
+    // Removing inherited ACEs can revoke the container's own access.
+    assertWindowsAclRemediationAllowed();
     const command = resolveWindowsSystemCommand("icacls.exe", opts.env);
     const user = resolveWindowsUserPrincipal(opts.env, opts.userInfo) ?? "%USERNAME%";
     const grant = opts.isDir ? "(OI)(CI)F" : "F";

package/node_modules/@openclaw/fs-safe/dist/pinned-open.d.ts

@@ -22,9 +22,11 @@ export declare function openPinnedFileSync(params: {
     filePath: string;
     resolvedPath?: string;
     rejectPathSymlink?: boolean;
+    rejectLeafSymlinks?: boolean;
     rejectHardlinks?: boolean;
     maxBytes?: number;
     allowedType?: PinnedOpenSyncAllowedType;
     ioFs?: PinnedOpenSyncFs;
+    admittedFd?: number;
     finalAdmission?: PinnedOpenSyncFinalAdmission;
 }): PinnedOpenSyncResult;

package/node_modules/@openclaw/fs-safe/dist/pinned-open.js

@@ -1,3 +1,4 @@
+import { numberStats } from "./exact-identity.js";
 import fs from "node:fs";
 import { isUnsafeDeviceReadPath } from "./device-path.js";
 import { FsSafeError } from "./errors.js";
@@ -17,10 +18,11 @@ export function openPinnedFileSync(params) {
     const rejectPathSymlink = params.rejectPathSymlink === true;
     const statPolicy = {
         rejectHardlinks: params.rejectHardlinks,
+        rejectLeafSymlinks: params.rejectLeafSymlinks,
         maxBytes: params.maxBytes,
     };
     const openReadFlags = resolveReadOpenFlags({ constants: ioFs.constants });
-    let fd = null;
+    let fd = params.admittedFd ?? null;
     try {
         assertNoWindowsPathAlias(filePath, "filesystem", "file path uses a Windows filesystem namespace alias");
         if (resolvedPath !== undefined) {
@@ -46,8 +48,7 @@ export function openPinnedFileSync(params) {
             assertAllowedStat(stat, allowedType, statPolicy);
             return stat;
         });
-        fd = ioFs.openSync(realPath, openReadFlags);
-        const openedStat = ioFs.fstatSync(fd);
+        fd ??= ioFs.openSync(realPath, openReadFlags);
         const identity = inspectFileIdentitySync(() => {
             const stat = ioFs.fstatSync(fd, { bigint: true });
             assertAllowedStat(stat, allowedType, statPolicy);
@@ -62,6 +63,7 @@ export function openPinnedFileSync(params) {
             path: realPath,
             descriptorIdentity: identity,
         }) ?? realPath;
+        const openedStat = numberStats(identity);
         const opened = { ok: true, path: admittedPath, fd, stat: openedStat, identity };
         fd = null;
         return opened;
@@ -86,6 +88,9 @@ export function openPinnedFileSync(params) {
     }
 }
 function assertAllowedStat(stat, allowedType, params) {
+    if (stat.isSymbolicLink() && params.rejectLeafSymlinks) {
+        throw new FsSafeError("symlink", "symlink not allowed");
+    }
     if (stat.isSymbolicLink() || !(allowedType === "directory" ? stat.isDirectory() : stat.isFile())) {
         throw new FsSafeError("not-file", "path does not have the required file type");
     }

package/node_modules/@openclaw/fs-safe/dist/pinned-write-input.js

@@ -21,6 +21,7 @@ export function replayPinnedInput(fd, input) {
         })() };
 }
 const isUint8Array = types.isUint8Array;
+const SMALL_BUFFER_BYTES = 64 * 1024;
 function streamChunkBytes(chunk) {
     if (Buffer.isBuffer(chunk))
         return chunk;
@@ -29,10 +30,22 @@ function streamChunkBytes(chunk) {
     return snapshotByteView(chunk);
 }
 export async function writePinnedInput(target, input, maxBytes, assertBeforeMutation) {
+    if (input.kind === "link")
+        throw new FsSafeError("helper-failed", "link copying requires the link publication path");
     if (input.kind === "file") {
         await writeCopyFileToFd(typeof target === "number" ? target : target.fd, input, maxBytes, assertBeforeMutation);
         return;
     }
+    if (typeof target === "number" && input.kind === "buffer" &&
+        input.stageBeforePublish !== false && !assertBeforeMutation) {
+        const data = typeof input.data === "string" ? Buffer.from(input.data, input.encoding ?? "utf8") : input.data;
+        if (data.byteLength <= SMALL_BUFFER_BYTES) {
+            if (maxBytes !== undefined && data.byteLength > maxBytes) {
+                throw new FsSafeError("too-large", `file exceeds limit of ${maxBytes} bytes (got at least ${data.byteLength})`);
+            }
+            return writeAllToFile(target, data, { synchronous: true });
+        }
+    }
     let bytes = 0;
     const write = async (data) => {
         bytes += data.byteLength;

package/node_modules/@openclaw/fs-safe/dist/pinned-write-staged.js

@@ -3,6 +3,7 @@ import { assertExclusiveCreateLeaf } from "./exclusive-create.js";
 import fsSync, {} from "node:fs";
 import fs, {} from "node:fs/promises";
 import path from "node:path";
+import { readFileHandleBounded } from "./bounded-read.js";
 import { createFileHandle } from "./create.js";
 import { hasPreservedCreationArtifacts, creationAdmissionFromParent } from "./creation-boundary.js";
 import { syncDirectoryBestEffort } from "./directory-durability.js";
@@ -18,6 +19,7 @@ import { cleanupPinnedFilePath } from "./file-cleanup.js";
 import { assertFinalSymlinkRejected } from "./root-symlink-policy.js";
 import { createStagedFileReceipt, settleStagedFile } from "./staged-file-settlement.js";
 import { getFsSafeTestHooks } from "./test-hooks.js";
+import { restoreCopyMetadata } from "./copy-metadata.js";
 export async function runPinnedStagedWrite(params, parentPath, parentGuard) {
     const verifyPosixMode = process.platform !== "win32" &&
         (params.verifyPosixMode === true || params.private === true);
@@ -31,7 +33,6 @@ export async function runPinnedStagedWrite(params, parentPath, parentGuard) {
             ? fsSync.constants.O_NOFOLLOW
             : 0);
     let handle;
-    let tempStat;
     let tempIdentity;
     let readHandle;
     let renamed = false;
@@ -59,13 +60,15 @@ export async function runPinnedStagedWrite(params, parentPath, parentGuard) {
         await writePinnedInput(handle, params.input, params.maxBytes, assertBeforeWrite);
         if (verifyPosixMode)
             assertPinnedWriteMode(handle.fd, 0o600, params.private);
-        tempStat = fsSync.fstatSync(handle.fd);
-        const tempPathStat = fsSync.lstatSync(tempPath);
+        const tempStat = fsSync.fstatSync(handle.fd, { bigint: true });
+        const tempPathStat = fsSync.lstatSync(tempPath, { bigint: true });
         if (tempPathStat.isSymbolicLink() || !sameFileIdentity(tempPathStat, tempStat)) {
             throw new FsSafeError("path-mismatch", "fallback temp path changed during write");
         }
         const expectedTempStat = tempStat;
-        await handle.chmod(params.mode);
+        fsSync.fchmodSync(handle.fd, params.mode);
+        if (params.input.kind === "file")
+            restoreCopyMetadata(handle.fd, params.input.metadata);
         if (verifyPosixMode) {
             assertPinnedWriteMode(handle.fd, params.mode, params.private);
             assertBeforeMutation = pinnedWriteModeAssertion(handle.fd, params.mode, params.assertBeforeMutation, params.private);
@@ -115,7 +118,7 @@ export async function runPinnedStagedWrite(params, parentPath, parentGuard) {
             await getFsSafeTestHooks()?.afterPinnedWriteFallbackRename?.(targetPath);
             if (params.sync !== false)
                 await syncDirectoryBestEffort(parentPath);
-            const targetStat = fsSync.lstatSync(targetPath);
+            const targetStat = fsSync.lstatSync(targetPath, { bigint: true });
             if (targetStat.isSymbolicLink()) {
                 throw new FsSafeError("path-mismatch", "fallback target changed during write");
             }
@@ -133,14 +136,13 @@ export async function runPinnedStagedWrite(params, parentPath, parentGuard) {
                 const expectedHash = sha256Hex(params.input.data, params.input.encoding);
                 readHandle = await fs.open(targetPath, resolveReadOpenFlags());
                 const readHandleStat = fsSync.fstatSync(readHandle.fd, { bigint: true });
-                const actualHash = sha256Hex(await readHandle.readFile());
+                const actualHash = sha256Hex(await readFileHandleBounded(readHandle, Infinity));
                 if (actualHash !== expectedHash) {
                     throw new FsSafeError("path-mismatch", "fallback target changed during write");
                 }
                 // The content-verified destination, not the old temp inode, is now pinned.
                 verificationIdentity = readHandleStat;
-                // Preserve the helper's legacy numeric return facts, not the private proof.
-                verifiedIdentity = { dev: Number(readHandleStat.dev), ino: Number(readHandleStat.ino) };
+                verifiedIdentity = readHandleStat;
             }
         });
         await params.verifyPublished?.((readHandle ?? handle).fd, verificationIdentity, parentGuard);

package/node_modules/@openclaw/fs-safe/dist/pinned-write-types.d.ts

@@ -1,4 +1,5 @@
 import type { CopyFileInput } from "./copy-file-input.js";
+import type { CopyLinkInput } from "./copy-link.js";
 import type { AnyAsyncDirectoryGuard } from "./directory-guard.js";
 import type { FileIdentityStat } from "./file-identity.js";
 import type { MutationDirectoryObservation } from "./pinned-mutation-observation.js";
@@ -16,7 +17,7 @@ export type PinnedWriteInput = {
     kind: "stream";
     stream: AsyncIterable<Uint8Array | string>;
     stageBeforePublish?: boolean;
-} | CopyFileInput;
+} | CopyFileInput | CopyLinkInput;
 export type RenameIdentityPolicy = "strict" | "verify-content-with-lock";
 export type PublishedWriteIdentity = Readonly<{
     dev: bigint;