@openclaw/matrix 2026.10.5-beta.4 → 2026.10.10-beta.2

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
@@ -81,6 +84,12 @@ kernel-atomic. Read the [native helper policy](docs/native-helper.md) and
 [operation/platform matrix](docs/security-model.md#native-root-mutation-capabilities)
 when concurrent mutation is in scope.
 
+For doctor/startup checks, use
+[`await getFsSafeNativeStatus({ probe: true })`](docs/config.md#getfssafenativestatus-options)
+from `@openclaw/fs-safe/config` to report whether the native addon is active,
+why it is unavailable, and what to do next. Calling it without options only reads
+the cache. Status is per module instance; Workers must be checked separately.
+
 ## Migrating from the Python helper
 
 Version 0.5 replaced the Python worker with prebuilt native bindings. Follow the
@@ -113,9 +122,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 +173,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 +252,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/advanced.d.ts

@@ -17,7 +17,7 @@ export { readFileWindowFully, readFileWindowFullySync, type ReadFileWindowOption
 export { writeFileWindowFully, type WriteFileWindowOptions } from "./write-file-handle.js";
 export { assertNoUnsafeDeviceReadPath, isUnsafeDeviceReadPath, matchUnsafeDeviceReadPath, type UnsafeDeviceReadPathMatch, type UnsafeDeviceReadPathOptions, type UnsafeDeviceReadPathReason, } from "./device-path.js";
 export { assertAbsolutePathInput, canonicalPathFromExistingAncestor, ensureAbsoluteDirectory, findExistingAncestor, resolveAbsolutePathForRead, resolveAbsolutePathForWrite, type AbsolutePathSymlinkPolicy, type EnsureAbsoluteDirectoryOptions, type EnsureAbsoluteDirectoryResult, type ResolvedAbsolutePath, type ResolvedWritableAbsolutePath, } from "./absolute-path.js";
-export { sameFileIdentity, type FileIdentityStat } from "./file-identity.js";
+export { sameFileIdentity, type FileIdentityStat, type FileIdentityInput, type ExactFileIdentity, type ExactIdentityReceipt } from "./file-identity.js";
 export { sanitizeUntrustedFileName } from "./filename.js";
 export { pathExists, pathExistsSync } from "./fs.js";
 export { resolveLocalPathFromRootsSync, readLocalFileFromRoots, type LocalRootsInputOptions, type LocalRootsPathResult, type LocalRootsReadResult, type ReadLocalFileFromRootsOptions, type ResolveLocalPathFromRootsSyncOptions, } from "./local-roots.js";
@@ -26,6 +26,7 @@ export { formatPosixMode } from "./permissions.js";
 export { configureFsSafeLocks, getFsSafeLockConfig, type FsSafeLockConfig, } from "./lock-config.js";
 export { assertNoHardlinkedFinalPath, assertNoPathAliasEscape, PATH_ALIAS_POLICIES, type PathAliasPolicy, } from "./path-policy.js";
 export { openRootFile, openRootFileSync, canUseRootFileOpen, matchRootFileOpenFailure, type OpenRootFileParams, type OpenRootFileSyncParams, type RootFileOpenFailure, type RootFileOpenFailureReason, type RootFileOpenResult, } from "./root-file.js";
+export { createRootFileOpenBatchSync, type RootFileOpenBatchSync } from "./root-file-open-batch-sync.js";
 export { ROOT_PATH_ALIAS_POLICIES, resolvePathViaExistingAncestorSync, resolveRootPath, resolveRootPathSync, type ResolvedRootPath, type RootPathAliasPolicy, } from "./root-path.js";
 export { ensureDirectoryWithinRoot, pathScope, resolveExistingPathsWithinRoot, resolvePathWithinRoot, resolvePathsWithinRoot, resolveStrictExistingPathsWithinRoot, resolveWritablePathWithinRoot, type PathScope, type PathScopeOptions, type PathScopeResolveOptions, } from "./root-paths.js";
 export { safeDirName, safePathSegmentHashed, safePathSegmentHashedV2, resolveSafeInstallDir, assertCanonicalPathWithinBase, } from "./install-path.js";

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

@@ -27,6 +27,7 @@ export { formatPosixMode } from "./permissions.js";
 export { configureFsSafeLocks, getFsSafeLockConfig, } from "./lock-config.js";
 export { assertNoHardlinkedFinalPath, assertNoPathAliasEscape, PATH_ALIAS_POLICIES, } from "./path-policy.js";
 export { openRootFile, openRootFileSync, canUseRootFileOpen, matchRootFileOpenFailure, } from "./root-file.js";
+export { createRootFileOpenBatchSync } from "./root-file-open-batch-sync.js";
 export { ROOT_PATH_ALIAS_POLICIES, resolvePathViaExistingAncestorSync, resolveRootPath, resolveRootPathSync, } from "./root-path.js";
 export { ensureDirectoryWithinRoot, pathScope, resolveExistingPathsWithinRoot, resolvePathWithinRoot, resolvePathsWithinRoot, resolveStrictExistingPathsWithinRoot, resolveWritablePathWithinRoot, } from "./root-paths.js";
 export { safeDirName, safePathSegmentHashed, safePathSegmentHashedV2, resolveSafeInstallDir, assertCanonicalPathWithinBase, } from "./install-path.js";

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/atomic-io.js

@@ -1,6 +1,6 @@
 import syncFs, {} from "node:fs";
 import fs, {} from "node:fs/promises";
-import { readBoundedSync } from "./bounded-read.js";
+import { readBoundedSync, readFileHandleBounded } from "./bounded-read.js";
 import { recursiveMkdirPath } from "./recursive-mkdir-path.js";
 import { inspectFileIdentity, inspectFileIdentitySync } from "./strict-file-identity.js";
 import { sleep, sleepSync } from "./timing.js";
@@ -207,7 +207,7 @@ export class AtomicFile {
     }
     *readFile(sizeHint) {
         if (typeof this.resource !== "number")
-            return yield* wait(this.resource.readFile());
+            return yield* wait(readFileHandleBounded(this.resource, Infinity));
         if (sizeHint === undefined)
             return this.io.syncFs.readFileSync(this.resource);
         const fd = this.resource;

package/node_modules/@openclaw/fs-safe/dist/bounded-read.d.ts

@@ -13,6 +13,7 @@ export declare function readBoundedAsync(maxBytes: number, readChunk: (scratch:
  * force an unbounded allocation.
  */
 export declare function readFileHandleBounded(handle: ReadableFileHandle, maxBytes: number): Promise<Buffer>;
+export declare function readFileHandleBoundedWithSize(handle: ReadableFileHandle, maxBytes: number, initialSize?: number): Promise<Buffer>;
 /** Async bounded read from a numeric descriptor. The caller owns the descriptor. */
 export declare function readFileDescriptorBounded(fd: number, maxBytes: number): Promise<Buffer>;
 export declare function readBoundedSync(maxBytes: number, readChunk: (scratch: Buffer, length: number) => number, options?: {

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

@@ -73,11 +73,18 @@ export async function readBoundedAsync(maxBytes, readChunk, options = {}) {
  * force an unbounded allocation.
  */
 export async function readFileHandleBounded(handle, maxBytes) {
+    return await readFileHandleBoundedWithSize(handle, maxBytes);
+}
+// Internal: the admitted size bounds the first allocation, never the read.
+export function readFileHandleBoundedWithSize(handle, maxBytes, initialSize) {
     normalizeMaxBytes(maxBytes);
     const fd = "fd" in handle && typeof handle.fd === "number" ? handle.fd : undefined;
-    return await readBoundedAsync(maxBytes, async (scratch, length) => {
+    return readBoundedAsync(maxBytes, async (scratch, length) => {
         return (await handle.read(scratch, 0, length, null)).bytesRead;
-    }, { observeRegularFileSize: fd === undefined ? undefined : () => regularFileSize(fd) });
+    }, {
+        initialSize,
+        observeRegularFileSize: fd === undefined ? undefined : () => regularFileSize(fd),
+    });
 }
 function regularFileSize(fd) {
     try {

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

@@ -1,4 +1,6 @@
+import type { ExactFileIdentity } from "./exact-identity.js";
 export type CloneFileMetadata = {
+    exactIdentity?: ExactFileIdentity;
     dev: number;
     type: number;
     mtimeSec: number;

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);
@@ -19,6 +19,7 @@ export async function readCloneFileMetadata(files) {
             result.readUInt32LE(20) !== 0x100)
             return undefined;
         return {
+            exactIdentity: Object.freeze({ dev: BigInt(result.readUInt32LE(24)), ino: result.readBigInt64LE(76) }),
             dev: result.readUInt32LE(24),
             type: result.readUInt32LE(28),
             mtimeSec: Number(result.readBigInt64LE(32)),

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

@@ -1,2 +1,8 @@
+import type { FsSafeNativeStatus } from "./native-status.js";
 export { configureFsSafeNative, getFsSafeNativeConfig, type FsSafeNativeConfig, type FsSafeNativeMode, } from "./native-config.js";
+export type { FsSafeNativeStatus, FsSafeNativeStatusReason, } from "./native-status.js";
 export { configureFsSafeLocks, getFsSafeLockConfig, type FsSafeLockConfig, } from "./lock-config.js";
+/** Read native status without loading the native module on config import. */
+export declare function getFsSafeNativeStatus(options?: {
+    probe?: boolean;
+}): Promise<FsSafeNativeStatus>;

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

@@ -1,2 +1,7 @@
 export { configureFsSafeNative, getFsSafeNativeConfig, } from "./native-config.js";
 export { configureFsSafeLocks, getFsSafeLockConfig, } from "./lock-config.js";
+/** Read native status without loading the native module on config import. */
+export async function getFsSafeNativeStatus(options) {
+    const { readFsSafeNativeStatus } = await import("./native-status.js");
+    return readFsSafeNativeStatus(options);
+}

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

@@ -3,19 +3,21 @@ 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;
 export declare function assertCopySourceCurrent(source: {
     handle: FileHandle;
     realPath: string;
-}, identity: BigIntStats): Promise<void>;
+}, identity: BigIntStats): void;
 export declare function writeCopyFileToFd(fd: number, input: CopyFileInput, maxBytes?: number, assertBeforeMutation?: () => void): Promise<void>;
 export declare function createNativeCopyFile(native: NativeBinding, input: CopyFileInput, parentFd: number, basename: string, maxBytes: number | undefined): Promise<NativeFileCopyResult | undefined>;
 export declare function assertNativeCopyCompleted(input: CopyFileInput, copied?: NativeFileCopyResult): void;

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

@@ -1,9 +1,9 @@
 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 { inspectFileIdentitySync } from "./strict-file-identity.js";
 import { transferFileHandle } from "./file-handle-transfer.js";
 export function resolveFileCopyCloneMode(mode) {
     const clone = resolveCopyCloneMode(mode, "never");
@@ -12,9 +12,9 @@ export function resolveFileCopyCloneMode(mode) {
     }
     return clone;
 }
-export async function assertCopySourceCurrent(source, identity) {
-    await inspectFileIdentity(() => fs.fstatSync(source.handle.fd, { bigint: true }), identity);
-    await inspectFileIdentity(() => {
+export function assertCopySourceCurrent(source, identity) {
+    inspectFileIdentitySync(() => fs.fstatSync(source.handle.fd, { bigint: true }), identity);
+    inspectFileIdentitySync(() => {
         const current = fs.lstatSync(source.realPath, { bigint: true });
         if (current.isSymbolicLink() || !current.isFile()) {
             throw new FsSafeError("path-mismatch", "copy source path changed");
@@ -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,170 @@
+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 { statIdentityFromNative } from "./native-stat-identity.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 = { dev: statIdentityFromNative(created.dev), ino: statIdentityFromNative(created.ino) };
+                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;

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

@@ -0,0 +1,39 @@
+import fs, {} from "node:fs";
+import { FsSafeError } from "./errors.js";
+import { getNativeBinding } from "./native.js";
+import { isFsSafeNativeRequired } from "./native-config.js";
+export function timestampSeconds(nanoseconds) {
+    // Numeric strings retain fractional and pre-epoch times in Node's utimes API.
+    return String(Number(nanoseconds / 1000000000n) + Number(nanoseconds % 1000000000n) / 1e9);
+}
+export function captureCopyMetadata(fd, stat) {
+    let restoreNative;
+    const native = getNativeBinding();
+    if (process.platform === "win32") {
+        if (native?.readCopyMetadata && native.restoreCopyMetadata) {
+            const snapshot = native.readCopyMetadata(fd);
+            const restore = native.restoreCopyMetadata.bind(native);
+            restoreNative = target => restore(target, snapshot);
+        }
+        else if (isFsSafeNativeRequired()) {
+            throw new FsSafeError("helper-unavailable", "native Windows copy metadata preservation is unavailable");
+        }
+    }
+    else if (native?.restoreCopyFileTimes) {
+        const restore = native.restoreCopyFileTimes.bind(native);
+        const { atimeNs, mtimeNs } = stat;
+        restoreNative = target => restore(target, atimeNs, mtimeNs);
+    }
+    else if (isFsSafeNativeRequired()) {
+        throw new FsSafeError("helper-unavailable", "native copy timestamp preservation is unavailable");
+    }
+    return Object.freeze({ atimeNs: stat.atimeNs, mtimeNs: stat.mtimeNs, restoreNative });
+}
+export function restoreCopyMetadata(fd, metadata) {
+    if (!metadata)
+        return;
+    if (metadata.restoreNative)
+        metadata.restoreNative(fd);
+    else
+        fs.futimesSync(fd, timestampSeconds(metadata.atimeNs), timestampSeconds(metadata.mtimeNs));
+}