@openclaw/openshell-sandbox 2026.10.5 → 2026.10.7

package/dist/index.js

@@ -8,6 +8,7 @@ import { movePathWithCopyFallback } from "@openclaw/fs-safe/atomic";
 import { GUEST_FILESYSTEM_PYTHON } from "@openclaw/fs-safe/guest";
 import { createDeferred, formatPluginConfigIssue, mapPluginConfigIssues } from "openclaw/plugin-sdk/extension-shared";
 import { KeyedAsyncQueue } from "openclaw/plugin-sdk/keyed-async-queue";
+import { lstatIfExists } from "openclaw/plugin-sdk/path-existence-runtime";
 import { FsSafeError, canonicalPathFromExistingAncestor, extractErrorCode } from "openclaw/plugin-sdk/security-runtime";
 import { asOptionalRecord, normalizeLowercaseStringOrEmpty } from "openclaw/plugin-sdk/string-coerce-runtime";
 import { safeParseJson } from "openclaw/plugin-sdk/text-utility-runtime";
@@ -269,7 +270,7 @@ var OpenShellFsBridge = class {
 	async stat(params) {
 		const target = this.resolveTarget(params);
 		const hostPath = target.hostPath;
-		const stats = await fsPromises.lstat(hostPath).catch(() => null);
+		const stats = await lstatIfExists(hostPath, "ENOENT");
 		if (!stats) return null;
 		await assertLocalPathSafety({
 			target,
@@ -463,14 +464,14 @@ function createExcludeMatcher(excludeDirs) {
 	return (name) => excluded.has(normalizeLowercaseStringOrEmpty(name));
 }
 const runLimitedFs = pLimit(COPY_TREE_FS_CONCURRENCY);
-async function lstatIfExists(targetPath) {
+async function lstatIfExists$1(targetPath) {
 	return await runLimitedFs(fsPromises.lstat, targetPath).catch((error) => {
 		if (extractErrorCode(error) === "ENOENT") return null;
 		throw error;
 	});
 }
 async function reconcileMirrorPath(params) {
-	const targetStats = await lstatIfExists(params.targetPath);
+	const targetStats = await lstatIfExists$1(params.targetPath);
 	if (targetStats && !targetStats.isDirectory() && !targetStats.isFile()) return true;
 	const sourceStats = params.sourcePath ? await runLimitedFs(fsPromises.lstat, params.sourcePath) : null;
 	const sourceDir = sourceStats?.isDirectory() ? params.sourcePath : void 0;
@@ -807,11 +808,15 @@ var OpenShellSandboxBackendImpl = class {
 		await this.ensureSandboxExists();
 		const sshSession = await createOpenShellSshSession({ context: this.params.execContext });
 		try {
+			let root = this.params.remoteWorkspaceDir;
+			try {
+				root = this.resolveRemoteTarget(workdir).root;
+			} catch {}
 			const result = await runSshSandboxCommand({
 				session: sshSession,
 				remoteCommand: buildRemoteWorkdirValidationCommand({
 					workdir,
-					root: this.resolveWorkdirValidationRoot(workdir)
+					root
 				}),
 				allowFailure: true
 			});
@@ -820,13 +825,6 @@ var OpenShellSandboxBackendImpl = class {
 			await disposeSshSandboxSession(sshSession);
 		}
 	}
-	resolveWorkdirValidationRoot(workdir) {
-		try {
-			return this.resolveRemoteTarget(workdir).root;
-		} catch {
-			return this.params.remoteWorkspaceDir;
-		}
-	}
 	async validateMirrorWorkdir(workdir) {
 		const normalized = normalizeRemotePath(workdir);
 		const roots = this.workspaceUploadRoots();
@@ -851,7 +849,7 @@ var OpenShellSandboxBackendImpl = class {
 			let local = root.local;
 			for (const part of root.local === skillsWorkspaceDir ? ["", ...parts] : parts) {
 				local = path.join(local, part);
-				if (!(await fsPromises.lstat(local).catch(() => null))?.isDirectory()) return null;
+				if (!(await lstatIfExists(local, "ENOENT"))?.isDirectory()) return null;
 			}
 			return normalized;
 		}
@@ -941,7 +939,7 @@ var OpenShellSandboxBackendImpl = class {
 		await this.ensureSandboxExists();
 		await this.maybeSeedRemoteWorkspace();
 		const target = this.resolveRemoteTarget(remotePath);
-		const stats = await fsPromises.lstat(localPath).catch(() => null);
+		const stats = await lstatIfExists(localPath, "ENOENT");
 		if (!stats || stats.isSymbolicLink()) {
 			await this.removeRemotePath(remotePath, {
 				recursive: true,
@@ -1160,11 +1158,11 @@ var OpenShellSandboxBackendImpl = class {
 	async syncSkillsWorkspaceToRemote() {
 		if (this.params.createParams.cfg.workspaceAccess !== "rw" || !this.params.createParams.skillsWorkspaceDir) return;
 		const remoteSkillsWorkspaceDir = resolveRemoteMaterializedSkillsWorkspaceDir(this.params.remoteWorkspaceDir);
+		const stats = await lstatIfExists(this.params.createParams.skillsWorkspaceDir, "ENOENT");
 		await this.runRemoteShellScriptInternal({
 			script: `${ENSURE_OPEN_SHELL_REMOTE_REAL_DIRECTORY_SCRIPT}\nfind "$1" -mindepth 1 -maxdepth 1 -exec rm -rf -- {} +`,
 			args: [remoteSkillsWorkspaceDir, this.params.remoteWorkspaceDir]
 		});
-		const stats = await fsPromises.lstat(this.params.createParams.skillsWorkspaceDir).catch(() => null);
 		if (!stats?.isDirectory() || stats.isSymbolicLink()) return;
 		await this.uploadPathToRemote(this.params.createParams.skillsWorkspaceDir, remoteSkillsWorkspaceDir);
 	}
@@ -1332,7 +1330,7 @@ async function removeDownloadedWorkspacePath(tmpDir, parts) {
 	let cursor = tmpDir;
 	for (const [index, part] of parts.entries()) {
 		const next = path.join(cursor, part);
-		const stats = await fsPromises.lstat(next).catch(() => null);
+		const stats = await lstatIfExists(next, "ENOENT");
 		if (!stats) return;
 		if (index === parts.length - 1 || stats.isSymbolicLink() || !stats.isDirectory()) {
 			await fsPromises.rm(next, {
@@ -1346,9 +1344,9 @@ async function removeDownloadedWorkspacePath(tmpDir, parts) {
 }
 async function moveLocalShadowAside(params) {
 	const shadowPath = path.join(params.workspaceDir, ...params.relativeParts);
-	const parentStats = await fsPromises.lstat(path.dirname(shadowPath)).catch(() => null);
+	const parentStats = await lstatIfExists(path.dirname(shadowPath), "ENOENT");
 	if (!parentStats?.isDirectory() || parentStats.isSymbolicLink()) return;
-	const shadowStats = await fsPromises.lstat(shadowPath).catch(() => null);
+	const shadowStats = await lstatIfExists(shadowPath, "ENOENT");
 	if (!shadowStats || shadowStats.isSymbolicLink()) return;
 	const preserveRoot = await fsPromises.mkdtemp(path.join(path.dirname(params.tmpDir), "openclaw-openshell-preserve-"));
 	let preserved;
@@ -1374,7 +1372,7 @@ async function restoreLocalShadow(preserved) {
 	const { shadowPath, receipt } = preserved;
 	const assertBackup = () => assertPreservedShadowIdentity(receipt);
 	const parentPath = path.dirname(shadowPath);
-	const parentStats = await fsPromises.lstat(parentPath).catch(() => null);
+	const parentStats = await lstatIfExists(parentPath, "ENOENT");
 	if (parentStats?.isSymbolicLink()) throw new Error(`Refusing to restore workspace shadow through symlink parent: ${parentPath}`);
 	if (parentStats && !parentStats.isDirectory()) {
 		assertBackup();

package/node_modules/@openclaw/fs-safe/CHANGELOG.md

@@ -2,6 +2,54 @@
 
 ## Unreleased
 
+## 0.26.0 - 2026-10-10
+
+### Highlights
+
+- **New platforms:** native packages for FreeBSD x64/arm64 and Windows ARM64. ([#905](https://github.com/openclaw/fs-safe/pull/905), [#893](https://github.com/openclaw/fs-safe/pull/893))
+- **Native capabilities:** anonymous pipes, Linux write leases, Darwin ACL inspection, ReFS block cloning, and metadata- and link-preserving `Root.copyIn`. ([#892](https://github.com/openclaw/fs-safe/pull/892), [#896](https://github.com/openclaw/fs-safe/pull/896), [#920](https://github.com/openclaw/fs-safe/pull/920), [#921](https://github.com/openclaw/fs-safe/pull/921))
+- **Android/Termux publication:** staged no-replace copies and writes work when the OS refuses hard links. ([#888](https://github.com/openclaw/fs-safe/pull/888))
+- **Performance:** faster deep archive extraction, borrowed-handle copies and overwrites, sidecar locks, and Linux descriptor verification, with identity checks retained. ([#912](https://github.com/openclaw/fs-safe/pull/912), [#906](https://github.com/openclaw/fs-safe/pull/906), [#902](https://github.com/openclaw/fs-safe/pull/902), [#901](https://github.com/openclaw/fs-safe/pull/901), [#899](https://github.com/openclaw/fs-safe/pull/899))
+
+### Features
+
+- **ReFS file copies:** support guarded `Root.copyIn` block cloning on Windows ReFS and Dev Drive, with exclusive publication, cancellation cleanup, and automatic byte-copy fallback for unavailable clone capabilities. ([#920](https://github.com/openclaw/fs-safe/pull/920))
+- **Guarded file copying:** add `Root.copyIn` metadata preservation and exclusive literal-link copying, including dangling Windows file and directory links; keep permission selection separate from timestamps and attributes. ([#921](https://github.com/openclaw/fs-safe/pull/921))
+
+- **Native filesystem capabilities:** add Linux write leases on caller-owned descriptors, no-follow Darwin ACL inspection with separate file and directory inheritance facts, and Windows sharing-lock, attribute, and physical-extent test fixtures. ([#896](https://github.com/openclaw/fs-safe/pull/896))
+- **Anonymous pipes:** add `@openclaw/fs-safe/pipe` with native-owned, reopenable close-on-exec pipe ends for one-shot child input on POSIX, including safe stream closure in Workers. ([#892](https://github.com/openclaw/fs-safe/pull/892))
+
+### Fixes
+
+- **Windows creation diagnostics:** retain native Win32 error numbers through private directory and file creation failures, including the command fallback, without changing semantic error codes. ([#919](https://github.com/openclaw/fs-safe/pull/919))
+- **FreeBSD native packages:** add x64 and arm64 packages for FreeBSD 14.4+, with native anonymous pipes and canonicalization, and explicit capability absence for unported operations. ([#905](https://github.com/openclaw/fs-safe/pull/905))
+- **Partial native bindings:** select guarded fallbacks when an operation's native capabilities are absent, and report typed capability errors in required mode before mutation. ([#905](https://github.com/openclaw/fs-safe/pull/905))
+- **Android/Termux publication:** publish staged no-replace copies and writes when hardlinks are refused, using a verified empty placeholder before atomic replacement; include `EACCES` in the public hardlink-to-copy fallback classifier. Reported in [openclaw/openclaw#167791](https://github.com/openclaw/openclaw/issues/167791). ([#888](https://github.com/openclaw/fs-safe/pull/888))
+- **Native ZIP names:** preserve CP437 decoding for unflagged legacy filenames after the ZIP 9 upgrade, including collision rejection and bounded entry selection; continue rejecting invalid Unicode Path checksums and encodings before decoder normalization. ([#885](https://github.com/openclaw/fs-safe/pull/885))
+- **Native ZIP Unicode fields:** retain rejection of invalid Unicode Comment CRCs and UTF-8 before callbacks or bounded reads, and validate sequential Unicode fields in decoder order without repeated hashing of the original name. ([#887](https://github.com/openclaw/fs-safe/pull/887))
+- **Portable ZIP extraction:** accept safe relative root-directory markers such as `./` from libarchive and other producers without turning them into absolute paths; root markers remain skipped before callbacks and publication. ([#886](https://github.com/openclaw/fs-safe/pull/886))
+- **Durable JSON queues on Android/Termux:** claim, failed-entry quarantine, and retirement recovery report typed `helper-unavailable` errors when hardlinks are refused, preserving pending, claimed, and retirement evidence for retry. ([#889](https://github.com/openclaw/fs-safe/pull/889))
+- **Windows exclusive publication:** preserve dangling destination symlinks when a refused hard link falls back to placeholder publication. ([#894](https://github.com/openclaw/fs-safe/pull/894))
+- **Native mkdir collisions:** `Root.mkdir` consistently reports `not-file` for an existing regular-file destination in native require mode. ([#895](https://github.com/openclaw/fs-safe/pull/895))
+- **Guest directory publication:** report a changed source identity instead of a false destination collision when a Linux fallback rename refuses a substituted source. ([#898](https://github.com/openclaw/fs-safe/pull/898))
+- **Native recursive removal:** honor a zero entry budget before ignoring a missing target, including with `force`. ([#904](https://github.com/openclaw/fs-safe/pull/904))
+
+### Performance
+
+- **Linux opened-file verification:** read ordinary procfs descriptor paths directly instead of walking realpath, keeping identity checks and deleted-path canonicalization; `readLocalFileSafely` is 25–28% faster on deep paths. ([#899](https://github.com/openclaw/fs-safe/pull/899))
+- **Borrowed handles and locks:** keep descriptor metadata inspection off the asynchronous I/O queue for small overwrites (26–28% faster) and copies (31–34% faster), and skip a redundant parent `mkdir` when acquiring sidecar locks (15–18% faster). ([#901](https://github.com/openclaw/fs-safe/pull/901), [#902](https://github.com/openclaw/fs-safe/pull/902), [#906](https://github.com/openclaw/fs-safe/pull/906))
+- **Deep archive extraction:** native extraction verifies every retained ancestor through its open descriptor instead of repeated realpath walks: about 16% faster at depth 8 and 5–6% at depth 4, with every ancestor substitution check retained. ([#912](https://github.com/openclaw/fs-safe/pull/912))
+
+### Docs and Tooling
+
+- **Docs accuracy:** correct native-mode migration guidance for removed Python settings and bundled TAR fallbacks, clarify Root streaming ownership, create-only visibility, and Linux no-clobber move fallback limits, and fix the JSON-store and stale-lock examples so denied process probes keep live locks; README and docs examples are now type-checked in CI. ([#897](https://github.com/openclaw/fs-safe/pull/897), [#900](https://github.com/openclaw/fs-safe/pull/900), [#903](https://github.com/openclaw/fs-safe/pull/903))
+
+### Compatibility
+
+- **Windows ARM64:** add a native ARM64 package with real Windows 11 ARM64 and x64-emulation validation, including private ACL creation and Worker descriptor ownership. ([#893](https://github.com/openclaw/fs-safe/pull/893))
+
+- **Native ZIP metadata:** invalid UTF-8-flagged names now reject instead of decoding lossily or falling back to CP437. Public ZIP extraction, preflight, and reads already reject these names during physical admission. ([#885](https://github.com/openclaw/fs-safe/pull/885))
+
 ## 0.25.0 - 2026-10-08
 
 ### Highlights

package/node_modules/@openclaw/fs-safe/README.md

@@ -10,6 +10,9 @@
 
 Capability-style filesystem roots for Node.js apps that handle untrusted relative paths.
 
+Platform-specific additions include [Linux write leases, Darwin ACL inspection,
+and Windows test fixtures](docs/platform-capabilities.md).
+
 Think Go's `os.Root` / `OpenInRoot` or Rust's [`cap-std`](https://github.com/bytecodealliance/cap-std), but for Node. Hand `root()` a trusted directory and you get back a handle whose every method resolves relative paths against it and defends against `..`, symlink swaps, hardlink aliases, and TOCTOU rename races. The exact containment strength is reported per mechanism: Linux `openat2` opens are kernel-atomic; guarded Linux fallback, macOS, Windows, and JavaScript paths are best-effort.
 
 ```ts
@@ -113,9 +116,14 @@ operation; per-call options handle exceptions. See the [Root reference](docs/roo
 
 `write()` replaces contents by default. Use `create()` or `overwrite: false`
 when an existing destination should be an error. `move()` defaults to no clobber
-and requires native support for the atomic collision decision; it fails with
-`helper-unavailable` when unavailable. Pass `overwrite: true` when replacement
-is intended.
+and requires native support. On Linux, `auto` can replace a concurrently created
+empty directory if no-replace rename is unsupported; use native `require` for
+strict refusal. See the [move fallback contract](docs/writing.md#fs-move-from-to-options).
+Pass `overwrite: true` when replacement is intended.
+
+Staged JavaScript copies and creates also work when hardlinks are refused
+(including Android/Termux), using a verified empty placeholder before atomic
+replacement. See the [visibility and concurrency tradeoffs](docs/writing.md#publication-without-hardlinks).
 
 See [Writing](docs/writing.md) for copy sources, mutation authority, symlink
 policy, writable handles, and bounded removal, and [Creation](docs/creation.md)
@@ -159,6 +167,8 @@ and error exports. Prefer focused subpaths when a consumer needs a narrower
 contract. Low-level helpers that OpenClaw needs to compose higher-level APIs are grouped under
 `@openclaw/fs-safe/advanced` instead of being separate public leaf contracts.
 
+Use [`@openclaw/fs-safe/pipe`](docs/pipe.md) for native-owned, reopenable anonymous pipes and one-shot child input.
+
 See the [complete subpath catalogue](docs/install.md#subpath-exports) for every entry point and its contents.
 
 ## Failure semantics in the name
@@ -236,7 +246,7 @@ updates:
 import { fileStore } from "@openclaw/fs-safe/store";
 
 const files = fileStore({ rootDir: "/safe/workspace/state", private: true });
-const store = files.json("settings.json", { lock: true });
+const store = files.json<{ enabled: boolean }>("settings.json", { lock: true });
 
 await store.updateOr({ enabled: false }, (current) => ({ ...current, enabled: true }));
 ```

package/node_modules/@openclaw/fs-safe/dist/archive-merge.js

@@ -17,6 +17,7 @@ import { syncFileBestEffortSync } from "./file-sync.js";
 import { finalizeArchivePublication } from "./archive-durability.js";
 import { assertNoWindowsPathAlias } from "./windows-path-alias.js";
 import { inspectFileIdentitySync } from "./strict-file-identity.js";
+import { ArchiveSecurityError } from "./archive-errors.js";
 export async function withStagedArchivePublication(params, extract) {
     await withStagedArchiveDestination({
         destinationRealDir: params.destinationGuard.realPath,
@@ -101,6 +102,23 @@ async function mergeTree(params, publication, durable = true, entryUmask = 0) {
         assertDirectoryIdentityGuard(destinationGuard);
         check();
         for (const ancestor of ancestors) {
+            // Verify every retained ancestor, including its current name and physical path.
+            // Shallow chains cost less to verify directly than crossing the native bridge.
+            if (ancestors.length >= 4 && ancestor.owner.verifyCanonical) {
+                let verified;
+                try {
+                    verified = await ancestor.owner.verifyCanonical();
+                }
+                catch (error) {
+                    if (error instanceof FsSafeError || isNotFoundPathError(error)) {
+                        throw createArchiveSymlinkTraversalError(path.relative(destinationDir, ancestor.guard.dir));
+                    }
+                    throw error;
+                }
+                check();
+                if (verified)
+                    continue;
+            }
             assertDirectoryIdentityGuard(ancestor.guard);
             check();
             await ancestor.owner.verify(check);
@@ -156,15 +174,22 @@ async function mergeTree(params, publication, durable = true, entryUmask = 0) {
                     await ownExtractionDestinationMutation(params.deadline, async () => {
                         await assertGuards();
                         assertSourceFrontier();
-                        const owner = await pinNodeDirectoryForMode(destinationPath).catch((error) => {
+                        const guard = await createDirectoryIdentityGuard(destinationPath).catch((error) => {
+                            if (error instanceof ArchiveSecurityError && error.code === "destination-symlink") {
+                                throw createArchiveSymlinkTraversalError(originalPath);
+                            }
+                            throw error;
+                        });
+                        check();
+                        const owner = await pinNodeDirectoryForMode(destinationPath, {
+                            expectedIdentity: guard.stat, canonicalPath: guard.realPath,
+                        }).catch((error) => {
                             if (error instanceof FsSafeError && (error.code === "not-file" || error.code === "path-mismatch")) {
                                 throw createArchiveSymlinkTraversalError(originalPath);
                             }
                             throw error;
                         });
                         try {
-                            check();
-                            const guard = await createDirectoryIdentityGuard(destinationPath);
                             check();
                             await owner.verify(check);
                             ancestors.push({ guard, owner });

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

@@ -17,7 +17,7 @@ import { FsSafeError } from "./errors.js";
 import { inspectFileIdentity } from "./strict-file-identity.js";
 import { resolveReadOpenFlags } from "./read-open-flags.js";
 import { realpathSync } from "./realpath.js";
-import { getNativeBinding } from "./native.js";
+import { assertNativeCapabilities, getNativeBinding } from "./native.js";
 import { admitZipBuffer } from "./archive-zip-admission.js";
 import { validateNativeZipManifest } from "./archive-zip-manifest.js";
 import { resolveExtractLimits, resolveTarMeterLimits } from "./archive-limits.js";
@@ -199,9 +199,15 @@ async function readNativeBufferEntry(native, buffer, kind, requested, displayPat
     try {
         const signal = new AbortController().signal;
         const limits = resolveTarMeterLimits();
-        const reader = kind === "zip"
-            ? await native.openZipBufferNative(buffer, limits, AbortSignal.any([signal]))
-            : await native.openTarBufferNative(buffer, kind, limits, AbortSignal.any([signal]));
+        let reader;
+        if (kind === "zip") {
+            assertNativeCapabilities(native, "openZipBufferNative");
+            reader = await native.openZipBufferNative(buffer, limits, AbortSignal.any([signal]));
+        }
+        else {
+            assertNativeCapabilities(native, "openTarBufferNative");
+            reader = await native.openTarBufferNative(buffer, kind, limits, AbortSignal.any([signal]));
+        }
         const manifest = reader.entries;
         if (kind === "zip")
             validateNativeZipManifest(manifest, zipEntries);
@@ -227,7 +233,7 @@ export async function readArchiveEntry(archivePath, entryPath, options) {
     const zipEntries = [];
     if (kind === "zip")
         admitZipBuffer(buffer, resolveExtractLimits(), entry => { zipEntries.push(entry); });
-    const native = getNativeBinding();
+    const native = getNativeBinding(kind === "zip" ? "openZipBufferNative" : "openTarBufferNative");
     if (native)
         return await readNativeBufferEntry(native, buffer, kind, requestedEntry, entryPath, maxBytes, zipEntries);
     return kind === "zip" ? await readZipEntry(buffer, requestedEntry, maxBytes, zipEntries)

package/node_modules/@openclaw/fs-safe/dist/archive-zip-loader.js

@@ -118,11 +118,13 @@ export async function loadAdmittedZipArchive(buffer, admitted) {
     const entries = new Map();
     for (const [name, entry, physical] of normalized) {
         const appendSlash = physical.kind === "directory" && !name.endsWith("/");
-        const normalizedName = appendSlash ? `${name}/` : name;
+        // JSZip reduces a relative root marker such as "./" to an empty name.
+        // Keep its directory spelling relative when restoring the terminal slash.
+        const normalizedName = appendSlash ? `${name || "."}/` : name;
         if (Object.hasOwn(files, normalizedName))
             collision();
         if (appendSlash) {
-            entry.name = `${entry.name}/`;
+            entry.name = `${entry.name || "."}/`;
         }
         files[normalizedName] = entry;
         entries.set(physical.portableKey, createAdmittedZipEntry(entry, normalizedName, physical));

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

@@ -154,7 +154,7 @@ export async function extractArchive(params) {
     const label = kind === "zip" ? "extract zip" : "extract tar";
     const limits = resolveExtractLimits(params.limits);
     const tarLimits = resolveTarMeterLimits(limits);
-    const native = getNativeBinding();
+    const native = getNativeBinding("inspectArchiveNative", "extractArchiveNative");
     assertNoWindowsPathAlias(archivePath, "filesystem", "archive source uses a Windows filesystem namespace alias");
     assertNoWindowsPathAlias(destDir, "filesystem", "archive destination uses a Windows filesystem namespace alias");
     // Read the declared public fields before private adapters copy options: class
@@ -282,7 +282,7 @@ export async function inspectTarArchive(params) {
     const onFiltered = resolveArchiveFilteredEntryPolicy(params.onFiltered);
     const limits = resolveExtractLimits(params.limits);
     const tarLimits = resolveTarMeterLimits(limits);
-    const native = getNativeBinding();
+    const native = getNativeBinding("inspectArchiveNative");
     assertNoWindowsPathAlias(archivePath, "filesystem", "archive source uses a Windows filesystem namespace alias");
     return await withExtractionDeadline(params.timeoutMs, "inspect tar", async (deadline) => {
         const staged = await stageArchiveFileForExtraction({ archivePath, limits, deadline });

package/node_modules/@openclaw/fs-safe/dist/clone-metadata.js

@@ -6,7 +6,7 @@ import { getNativeBinding, requireNativeBinding } from "./native.js";
  */
 export async function readCloneFileMetadata(files) {
     const paths = files.map(assertAbsolutePathInput);
-    const native = process.platform === "darwin" ? requireNativeBinding() : getNativeBinding();
+    const native = process.platform === "darwin" ? requireNativeBinding("readCloneFileMetadata") : getNativeBinding("readCloneFileMetadata");
     if (!native)
         return paths.map(() => undefined);
     const results = await native.readCloneFileMetadata(paths);

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

@@ -3,12 +3,14 @@ import type { FileHandle } from "node:fs/promises";
 import { type CopyCloneMode } from "./copy-policy.js";
 import { type NativeBinding } from "./native.js";
 import { type NativeFileCopyResult } from "./native-binding.js";
+import type { CopyMetadata } from "./copy-metadata.js";
 export type CopyFileInput = {
     kind: "file";
     handle: FileHandle;
     size: number;
     clone: CopyCloneMode;
     signal?: AbortSignal;
+    metadata?: CopyMetadata;
     verifySource(): Promise<void>;
 };
 export declare function resolveFileCopyCloneMode(mode?: CopyCloneMode): CopyCloneMode;

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

@@ -1,7 +1,7 @@
 import fs, {} from "node:fs";
 import { resolveCopyCloneMode } from "./copy-policy.js";
 import { FsSafeError } from "./errors.js";
-import { getNativeBinding } from "./native.js";
+import { getNativeBinding, selectNativeBinding } from "./native.js";
 import { captureNativeFdClose } from "./native-binding.js";
 import { inspectFileIdentity } from "./strict-file-identity.js";
 import { transferFileHandle } from "./file-handle-transfer.js";
@@ -29,7 +29,8 @@ export async function writeCopyFileToFd(fd, input, maxBytes, assertBeforeMutatio
 }
 export async function createNativeCopyFile(native, input, parentFd, basename, maxBytes) {
     input.signal?.throwIfAborted();
-    if (!native.copyFileExclusive) {
+    const copier = selectNativeBinding(native, "copyFileExclusive");
+    if (!copier) {
         if (input.clone === "always") {
             throw new FsSafeError("helper-unavailable", "native file cloning is unavailable");
         }
@@ -39,7 +40,7 @@ export async function createNativeCopyFile(native, input, parentFd, basename, ma
     const nativeSignal = input.signal ? AbortSignal.any([input.signal]) : undefined;
     try {
         // The caller adopts this descriptor before observing a later cancellation.
-        return await native.copyFileExclusive(input.handle.fd, parentFd, basename, input.clone, maxBytes !== undefined && Number.isFinite(maxBytes) ? maxBytes : undefined, nativeSignal);
+        return await copier.copyFileExclusive(input.handle.fd, parentFd, basename, input.clone, maxBytes !== undefined && Number.isFinite(maxBytes) ? maxBytes : undefined, nativeSignal);
     }
     catch (error) {
         const code = error?.code;

package/node_modules/@openclaw/fs-safe/dist/copy-link.d.ts

@@ -0,0 +1,26 @@
+import { type BigIntStats } from "node:fs";
+import { type AnyAsyncDirectoryGuard } from "./directory-guard.js";
+import type { NativeBinding } from "./native-binding.js";
+import type { PinnedWriteParams } from "./pinned-write-types.js";
+export type CopyLinkInput = {
+    kind: "link";
+    stageBeforePublish: true;
+    sourcePath: string;
+    identity: BigIntStats;
+    target?: Buffer;
+    preserveMetadata: boolean;
+    signal?: AbortSignal;
+    verifySource(): Promise<void>;
+};
+/** Shared by tree byte copying and per-file copying; never resolves the target. */
+export declare function readCopyLinkTarget(source: string): Promise<Buffer>;
+export declare function assertCopyLinkAvailable(): void;
+export declare function admitCopyLink(sourcePath: string, preserveMetadata: boolean, signal?: AbortSignal): Promise<CopyLinkInput | undefined>;
+/** The caller has admitted the destination parent under Root's mutation policy. */
+export declare function copyLinkAtParent(params: PinnedWriteParams, input: CopyLinkInput, parent: AnyAsyncDirectoryGuard, native?: {
+    binding: NativeBinding;
+    fd: number;
+}): Promise<{
+    dev: bigint;
+    ino: bigint;
+}>;

package/node_modules/@openclaw/fs-safe/dist/copy-link.js

@@ -0,0 +1,169 @@
+import { randomUUID } from "node:crypto";
+import fs, {} from "node:fs";
+import fsp from "node:fs/promises";
+import path from "node:path";
+import { assertAsyncDirectoryGuard, assertSyncDirectoryGuard, createAsyncDirectoryGuard } from "./directory-guard.js";
+import { FsSafeError } from "./errors.js";
+import { getNativeBinding } from "./native.js";
+import { isFsSafeNativeRequired } from "./native-config.js";
+import { inspectFileIdentitySync } from "./strict-file-identity.js";
+import { timestampSeconds } from "./copy-metadata.js";
+import { syncDirectoryBestEffort } from "./directory-durability.js";
+import { noReplaceUnavailable } from "./native-noreplace.js";
+import { createSuppressedError } from "./suppressed-error.js";
+/** Shared by tree byte copying and per-file copying; never resolves the target. */
+export async function readCopyLinkTarget(source) {
+    return await fsp.readlink(source, { encoding: "buffer" });
+}
+export function assertCopyLinkAvailable() {
+    const native = getNativeBinding();
+    if (process.platform === "darwin" && !native?.createCopySymlink) {
+        throw new FsSafeError("helper-unavailable", "exclusive macOS link copying requires the native helper; link(2) follows its source");
+    }
+    if (process.platform === "win32" && (!native?.copyLinkExclusive || !native.publishCopyLink || !native.removeCopyLink)) {
+        throw new FsSafeError("helper-unavailable", "copying Windows links without following them requires the native helper");
+    }
+    if (native && process.platform !== "win32" && !native.createCopySymlink) {
+        throw new FsSafeError("helper-unavailable", "native link copying is unavailable");
+    }
+}
+export async function admitCopyLink(sourcePath, preserveMetadata, signal) {
+    const parent = await createAsyncDirectoryGuard(path.dirname(sourcePath), { bigint: true });
+    sourcePath = path.join(parent.realPath, path.basename(sourcePath));
+    const identity = fs.lstatSync(sourcePath, { bigint: true });
+    if (!identity.isSymbolicLink())
+        return undefined;
+    const target = process.platform === "win32" ? undefined : await readCopyLinkTarget(sourcePath);
+    const verifySource = async () => {
+        signal?.throwIfAborted();
+        await assertAsyncDirectoryGuard(parent);
+        const current = inspectFileIdentitySync(() => fs.lstatSync(sourcePath, { bigint: true }), identity);
+        if (!current.isSymbolicLink() || current.mtimeNs !== identity.mtimeNs || current.ctimeNs !== identity.ctimeNs) {
+            throw new FsSafeError("path-mismatch", "copy source link changed");
+        }
+    };
+    await verifySource();
+    return { kind: "link", stageBeforePublish: true, sourcePath, identity, target, preserveMetadata, signal, verifySource };
+}
+/** The caller has admitted the destination parent under Root's mutation policy. */
+export async function copyLinkAtParent(params, input, parent, native) {
+    const temporaryName = `.fs-safe-${randomUUID()}.tmp`;
+    const temporaryPath = path.join(parent.realPath, temporaryName);
+    const destination = path.join(parent.realPath, params.basename);
+    let identity;
+    let sourceParent;
+    let failure;
+    const assertStage = () => {
+        assertSyncDirectoryGuard(parent);
+        const stat = inspectFileIdentitySync(() => fs.lstatSync(temporaryPath, { bigint: true }), identity);
+        if (!stat.isSymbolicLink() || stat.nlink !== 1n)
+            throw new FsSafeError("path-mismatch", "copy link stage changed");
+    };
+    try {
+        await input.verifySource();
+        await assertAsyncDirectoryGuard(parent);
+        if (process.platform === "win32") {
+            if (!native?.binding.copyLinkExclusive)
+                throw new FsSafeError("helper-unavailable", "native Windows link copying is unavailable");
+            const sourceGuard = await createAsyncDirectoryGuard(path.dirname(input.sourcePath), { bigint: true });
+            sourceParent = await fsp.open(sourceGuard.realPath, fs.constants.O_RDONLY);
+            inspectFileIdentitySync(() => fs.fstatSync(sourceParent.fd, { bigint: true }), sourceGuard.stat);
+            await input.verifySource();
+            params.assertBeforeMutation?.();
+            assertSyncDirectoryGuard(parent);
+            identity = native.binding.copyLinkExclusive(sourceParent.fd, path.basename(input.sourcePath), native.fd, temporaryName, input.identity.dev, input.identity.ino, input.preserveMetadata, params.mode);
+        }
+        else {
+            if (native && !native.binding.createCopySymlink)
+                throw new FsSafeError("helper-unavailable", "native link copying is unavailable");
+            params.assertBeforeMutation?.();
+            assertSyncDirectoryGuard(parent);
+            if (native?.binding.createCopySymlink) {
+                const created = native.binding.createCopySymlink(native.fd, temporaryName, input.target, params.mode, input.preserveMetadata ? input.identity.atimeNs : undefined, input.preserveMetadata ? input.identity.mtimeNs : undefined);
+                identity = created;
+                if (created.errorCode)
+                    throw Object.assign(new Error(created.errorMessage), { code: created.errorCode });
+            }
+            else {
+                fs.symlinkSync(input.target, temporaryPath);
+                identity = fs.lstatSync(temporaryPath, { bigint: true });
+            }
+            if (!native && input.preserveMetadata) {
+                assertStage();
+                fs.lutimesSync(temporaryPath, timestampSeconds(input.identity.atimeNs), timestampSeconds(input.identity.mtimeNs));
+            }
+        }
+        assertStage();
+        await input.verifySource();
+        params.assertBeforeMutation?.();
+        input.signal?.throwIfAborted();
+        assertStage();
+        if (process.platform === "win32") {
+            native.binding.publishCopyLink(native.fd, temporaryName, params.basename, identity.dev, identity.ino);
+        }
+        else if (native) {
+            const renameNoReplace = native.binding.renameNoReplace;
+            if (!renameNoReplace)
+                throw new FsSafeError("helper-unavailable", "native link publication is unavailable");
+            try {
+                renameNoReplace(native.fd, temporaryName, native.fd, params.basename);
+            }
+            catch (error) {
+                const unavailable = noReplaceUnavailable(error, "link copy publication", true);
+                if (!unavailable || isFsSafeNativeRequired() || process.platform !== "linux")
+                    throw error;
+                // Linux link(2) links the symlink inode itself, never its target.
+                assertStage();
+                fs.linkSync(temporaryPath, destination);
+            }
+        }
+        else {
+            fs.linkSync(temporaryPath, destination);
+        }
+        params.onPublished?.(identity);
+        assertSyncDirectoryGuard(parent);
+        const final = inspectFileIdentitySync(() => fs.lstatSync(destination, { bigint: true }), identity);
+        if (!final.isSymbolicLink())
+            throw new FsSafeError("path-mismatch", "published copy link changed");
+        if (params.sync !== false)
+            await syncDirectoryBestEffort(parent.realPath);
+        await input.verifySource();
+        return identity;
+    }
+    catch (error) {
+        failure = { error };
+        throw error;
+    }
+    finally {
+        let cleanupFailure;
+        try {
+            if (identity) {
+                assertSyncDirectoryGuard(parent);
+                const remaining = fs.lstatSync(temporaryPath, { bigint: true, throwIfNoEntry: false });
+                if (remaining) {
+                    inspectFileIdentitySync(() => remaining, identity);
+                    if (!remaining.isSymbolicLink())
+                        throw new FsSafeError("path-mismatch", "copy link cleanup identity changed");
+                    if (process.platform === "win32")
+                        native.binding.removeCopyLink(native.fd, temporaryName, identity.dev, identity.ino);
+                    else
+                        fs.unlinkSync(temporaryPath);
+                }
+            }
+        }
+        catch (error) {
+            cleanupFailure = { error };
+        }
+        try {
+            await sourceParent?.close();
+        }
+        catch (error) {
+            cleanupFailure = { error: cleanupFailure
+                    ? createSuppressedError(error, cleanupFailure.error, "copy link cleanup and close failed") : error };
+        }
+        if (cleanupFailure)
+            throw failure
+                ? createSuppressedError(cleanupFailure.error, failure.error, "copy link operation and cleanup failed")
+                : cleanupFailure.error;
+    }
+}

package/node_modules/@openclaw/fs-safe/dist/copy-metadata.d.ts

@@ -0,0 +1,9 @@
+import { type BigIntStats } from "node:fs";
+export type CopyMetadata = Readonly<{
+    atimeNs: bigint;
+    mtimeNs: bigint;
+    restoreNative?: (fd: number) => void;
+}>;
+export declare function timestampSeconds(nanoseconds: bigint): string;
+export declare function captureCopyMetadata(fd: number, stat: BigIntStats): CopyMetadata;
+export declare function restoreCopyMetadata(fd: number, metadata: CopyMetadata | undefined): void;