@openclaw/fs-safe 0.18.0 → 0.18.2

package/dist/strict-file-identity.js

@@ -1,6 +1,6 @@
 import { FsSafeError } from "./errors.js";
 import { recordFileObservationFailure } from "./file-observation.js";
-function identityMismatch() {
+export function fileIdentityMismatchError() {
     const error = new FsSafeError("path-mismatch", "file identity changed or could not be verified");
     recordFileObservationFailure(error, "identity");
     return error;
@@ -13,20 +13,20 @@ function identityCheck(expected, platform) {
             const value = stat[field];
             // Numeric receipts cannot recover identity bits already lost to rounding.
             if (typeof value !== "bigint")
-                throw identityMismatch();
+                throw fileIdentityMismatchError();
             if (platform === "win32" && value === 0n) {
                 complete = false;
             }
             else {
                 if (known[field] !== undefined && known[field] !== value)
-                    throw identityMismatch();
+                    throw fileIdentityMismatchError();
                 known[field] = value;
             }
         }
         return complete;
     };
     if (expected && !check(expected))
-        throw identityMismatch();
+        throw fileIdentityMismatchError();
     return check;
 }
 // Retry only unknown Windows identities, retaining every known component so a
@@ -38,9 +38,9 @@ export async function inspectFileIdentity(inspect, expected, platform = process.
         if (check(stat))
             return stat;
     }
-    throw identityMismatch();
+    throw fileIdentityMismatchError();
 }
-export function inspectFileIdentitySync(inspect, expected, platform = process.platform, mismatch = identityMismatch) {
+export function inspectFileIdentitySync(inspect, expected, platform = process.platform, mismatch = fileIdentityMismatchError) {
     let knownDev;
     let knownIno;
     if (expected) {

package/dist/temp-target.js

@@ -6,6 +6,7 @@ import { suffixWindowsReservedDeviceName } from "./filename.js";
 import { sameFileIdentityForCleanup } from "./file-identity.js";
 import { assertSafePathSegment, sanitizeSafePathSegment, trimHyphenEdges } from "./safe-path-segment.js";
 import { resolveSecureTempRoot } from "./secure-temp-dir.js";
+import { hasNodeErrorCode } from "./path.js";
 import { registerTempPathForExit } from "./temp-cleanup.js";
 import { assertNoWindowsPathAlias, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
 const HYPHEN_CHAR_CODE = 0x2d;
@@ -76,12 +77,6 @@ export function buildRandomTempFilePath(params) {
     assertNoWindowsPathAlias(filePath, "filesystem", "temp file path uses a Windows filesystem namespace alias");
     return filePath;
 }
-function isNodeErrorWithCode(err, code) {
-    return (typeof err === "object" &&
-        err !== null &&
-        "code" in err &&
-        err.code === code);
-}
 async function cleanupTempDir(dir, identity, onCleanupError) {
     try {
         const current = fsSync.lstatSync(dir, { bigint: true });
@@ -91,7 +86,7 @@ async function cleanupTempDir(dir, identity, onCleanupError) {
         await fs.rm(dir, { recursive: true, force: true });
     }
     catch (err) {
-        if (!isNodeErrorWithCode(err, "ENOENT")) {
+        if (!hasNodeErrorCode(err, "ENOENT")) {
             onCleanupError?.(err);
         }
     }
@@ -174,7 +169,7 @@ export async function createOwnedTempFile(params) {
                     await owner.cleanup();
                 }
                 catch (err) {
-                    if (!isNodeErrorWithCode(err, "ENOENT")) {
+                    if (!hasNodeErrorCode(err, "ENOENT")) {
                         params.onCleanupError?.(err);
                     }
                 }

package/dist/temp-workspace-admission.js

@@ -2,14 +2,11 @@ import fsSync, {} from "node:fs";
 import fs from "node:fs/promises";
 import path from "node:path";
 import { inspectDirectoryIdentitySync, observeDirectoryIdentitySync, } from "./directory-guard.js";
-import { admitTempWorkspaceChild, admitTempWorkspaceChildSync, } from "./temp-workspace-child-admission.js";
+import { admitTempWorkspaceChild, admitTempWorkspaceChildSync, assertTrustedTempWorkspaceDirectory, inspectTempWorkspaceDescriptorIdentitySync, projectTempWorkspaceNumericIdentity, TEMP_WORKSPACE_NUMERIC_IDENTITY_REPLAY, } from "./temp-workspace-child-admission.js";
 import { FsSafeError } from "./errors.js";
-import { recordFileObservationFailure } from "./file-observation.js";
 import { realpathSync } from "./realpath.js";
 import { assertNoWindowsPathAlias, pathForWindowsFilesystem, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
-import { inspectFileIdentitySync } from "./strict-file-identity.js";
-import { inspectTempWorkspaceDescriptorIdentitySync, projectTempWorkspaceNumericIdentity, TEMP_WORKSPACE_NUMERIC_IDENTITY_REPLAY, } from "./temp-workspace-identity.js";
-import { assertTrustedTempWorkspaceDirectory } from "./temp-workspace-permissions.js";
+import { fileIdentityMismatchError, inspectFileIdentitySync } from "./strict-file-identity.js";
 const WINDOWS = process.platform === "win32";
 function effectiveOwner() {
     // Windows mode/uid fields do not describe ACL authority. The supplied root's
@@ -74,11 +71,6 @@ function assertCanonicalRoot(entry) {
         throw new FsSafeError("path-mismatch", "temp workspace root ancestry changed");
     }
 }
-function identityMismatch() {
-    const error = new FsSafeError("path-mismatch", "file identity changed or could not be verified");
-    recordFileObservationFailure(error, "identity");
-    throw error;
-}
 function inspectSnapshotIdentity(entry) {
     const expected = entry.numericIdentity;
     if (!expected) {
@@ -89,21 +81,21 @@ function inspectSnapshotIdentity(entry) {
     const devKnown = Number.isSafeInteger(stat.dev) && stat.dev >= 0 && (!WINDOWS || stat.dev !== 0);
     if (devKnown) {
         if (stat.dev !== expected.dev)
-            identityMismatch();
+            throw fileIdentityMismatchError();
     }
     else if (WINDOWS)
         requiresExactRetry = true;
     else
-        identityMismatch();
+        throw fileIdentityMismatchError();
     const inoKnown = Number.isSafeInteger(stat.ino) && stat.ino >= 0 && (!WINDOWS || stat.ino !== 0);
     if (inoKnown) {
         if (stat.ino !== expected.ino)
-            identityMismatch();
+            throw fileIdentityMismatchError();
     }
     else if (WINDOWS)
         requiresExactRetry = true;
     else
-        identityMismatch();
+        throw fileIdentityMismatchError();
     if (!requiresExactRetry)
         return stat;
     // Read exact identity only once. The strict helper may re-check this constant
@@ -159,7 +151,7 @@ function canonicalAncestry(root) {
 }
 function exactIdentityMatches(current, expected) {
     if (current.dev !== expected.dev || current.ino !== expected.ino)
-        identityMismatch();
+        throw fileIdentityMismatchError();
 }
 function associateTempWorkspaceRoot(entry, ownerUid, descriptorFd) {
     const stat = inspectTempWorkspaceDescriptorIdentitySync(descriptorFd, entry.identity, entry.numericIdentity);

package/dist/temp-workspace-child-admission.d.ts

@@ -1,6 +1,20 @@
-import type { BigIntStats, Stats } from "node:fs";
+import { type BigIntStats, type Stats } from "node:fs";
 import type { TempWorkspaceRootAdmission } from "./temp-workspace-admission.js";
-import { type TempWorkspaceIdentityStat } from "./temp-workspace-identity.js";
+export type TempWorkspaceIdentity = Readonly<{
+    dev: bigint;
+    ino: bigint;
+}>;
+export type TempWorkspaceNumericIdentity = Readonly<{
+    dev: number;
+    ino: number;
+}>;
+export type TempWorkspaceIdentityStat = BigIntStats | Stats;
+export declare const TEMP_WORKSPACE_NUMERIC_IDENTITY_REPLAY: boolean;
+export declare function projectTempWorkspaceNumericIdentity(identity: TempWorkspaceIdentity): TempWorkspaceNumericIdentity | undefined;
+export declare function inspectTempWorkspaceDescriptorIdentitySync(fd: number, expected: TempWorkspaceIdentity, numeric: TempWorkspaceNumericIdentity | undefined): TempWorkspaceIdentityStat;
+export declare function inspectTempWorkspaceDirectoryIdentitySync(dir: string, expected: TempWorkspaceIdentity, numeric: TempWorkspaceNumericIdentity | undefined): TempWorkspaceIdentityStat;
+export declare function validateTempWorkspaceDirMode(mode: number): void;
+export declare function assertTrustedTempWorkspaceDirectory(stat: Pick<BigIntStats, "uid" | "mode"> | Pick<Stats, "uid" | "mode">, uid: number | undefined, child?: boolean): void;
 export declare function assertTempWorkspaceChildState(stat: BigIntStats | Stats, ownerUid: number | undefined): void;
 export declare function validateInitialTempWorkspaceChild(stat: BigIntStats, ownerUid: number | undefined, mode: number): boolean;
 export declare function childHasRequestedMode(stat: BigIntStats | Stats, mode: number): boolean;

package/dist/temp-workspace-child-admission.js

@@ -1,8 +1,70 @@
-import { inspectDirectoryIdentitySync } from "./directory-guard.js";
+import fsSync, {} from "node:fs";
+import { inspectDirectoryIdentitySync, observeDirectoryIdentitySync } from "./directory-guard.js";
 import { pinNodeDirectoryForMode, pinNodeDirectoryForModeSync } from "./directory-mode-node.js";
 import { FsSafeError } from "./errors.js";
-import { TEMP_WORKSPACE_NUMERIC_IDENTITY_REPLAY, } from "./temp-workspace-identity.js";
-import { assertTrustedTempWorkspaceDirectory } from "./temp-workspace-permissions.js";
+import { fileIdentityMismatchError, inspectFileIdentitySync } from "./strict-file-identity.js";
+export const TEMP_WORKSPACE_NUMERIC_IDENTITY_REPLAY = process.platform === "linux" || process.platform === "darwin";
+export function projectTempWorkspaceNumericIdentity(identity) {
+    const dev = Number(identity.dev);
+    const ino = Number(identity.ino);
+    if (!Number.isSafeInteger(dev) || dev < 0 || BigInt(dev) !== identity.dev ||
+        !Number.isSafeInteger(ino) || ino < 0 || BigInt(ino) !== identity.ino) {
+        return undefined;
+    }
+    return Object.freeze({ dev, ino });
+}
+function inspectNumericIdentity(current, expected) {
+    if (!Number.isSafeInteger(current.dev) || current.dev < 0 || current.dev !== expected.dev ||
+        !Number.isSafeInteger(current.ino) || current.ino < 0 || current.ino !== expected.ino) {
+        throw fileIdentityMismatchError();
+    }
+    return current;
+}
+export function inspectTempWorkspaceDescriptorIdentitySync(fd, expected, numeric) {
+    // A malformed or mismatched numeric observation is definite and never
+    // retried. Unsafe receipts and other platforms retain exact replay.
+    if (TEMP_WORKSPACE_NUMERIC_IDENTITY_REPLAY && numeric) {
+        return inspectNumericIdentity(fsSync.fstatSync(fd), numeric);
+    }
+    return inspectFileIdentitySync(() => fsSync.fstatSync(fd, { bigint: true }), expected);
+}
+export function inspectTempWorkspaceDirectoryIdentitySync(dir, expected, numeric) {
+    if (TEMP_WORKSPACE_NUMERIC_IDENTITY_REPLAY && numeric) {
+        return inspectNumericIdentity(observeDirectoryIdentitySync(dir), numeric);
+    }
+    return inspectFileIdentitySync(() => observeDirectoryIdentitySync(dir, { bigint: true }), expected);
+}
+export function validateTempWorkspaceDirMode(mode) {
+    if (!Number.isInteger(mode) || mode < 0 || mode > 0o7777) {
+        throw new FsSafeError("insecure-permissions", "temp workspace dirMode must be permission bits");
+    }
+    if (process.platform !== "win32" && (mode & 0o022) !== 0) {
+        throw new FsSafeError("insecure-permissions", "temp workspace must not be group/world writable");
+    }
+}
+export function assertTrustedTempWorkspaceDirectory(stat, uid, child = false) {
+    if (uid === undefined)
+        return;
+    const ownedByUser = typeof stat.uid === "bigint" ? stat.uid === BigInt(uid) : stat.uid === uid;
+    const ownedByRoot = typeof stat.uid === "bigint" ? stat.uid === 0n : stat.uid === 0;
+    if (!ownedByUser && (child || !ownedByRoot)) {
+        throw new FsSafeError("not-owned", "temp workspace directory has an untrusted owner");
+    }
+    // A root/current-user-owned sticky directory protects children owned by us,
+    // including the usual shared system temp directory. Never chmod that parent.
+    const writable = typeof stat.mode === "bigint"
+        ? (stat.mode & 18n) !== 0n
+        : Number.isSafeInteger(stat.mode) && stat.mode >= 0 && (stat.mode & 0o022) !== 0;
+    const sticky = typeof stat.mode === "bigint"
+        ? (stat.mode & 512n) !== 0n
+        : Number.isSafeInteger(stat.mode) && stat.mode >= 0 && (stat.mode & 0o1000) !== 0;
+    if (typeof stat.mode !== "bigint" && (!Number.isSafeInteger(stat.mode) || stat.mode < 0)) {
+        throw new FsSafeError("insecure-permissions", "temp workspace directory permissions are invalid");
+    }
+    if (writable && (child || !sticky)) {
+        throw new FsSafeError("insecure-permissions", "temp workspace directory is group/world writable without sticky protection");
+    }
+}
 const WINDOWS = process.platform === "win32";
 export function assertTempWorkspaceChildState(stat, ownerUid) {
     const exactIdentity = typeof stat.dev === "bigint" && typeof stat.ino === "bigint" &&

package/dist/temp-workspace-descriptor.d.ts

@@ -1,7 +1,7 @@
 import fsSync from "node:fs";
 import type { FileIdentityStat } from "./file-identity.js";
 import type { TempWorkspaceRootAdmission } from "./temp-workspace-admission.js";
-import { type TempWorkspaceIdentityStat } from "./temp-workspace-identity.js";
+import { type TempWorkspaceIdentityStat } from "./temp-workspace-child-admission.js";
 type DirectoryDescriptorAccess = "read" | "search";
 export type RetainedDirectory = {
     fd: number;

package/dist/temp-workspace-descriptor.js

@@ -1,12 +1,10 @@
 import fsSync from "node:fs";
 import fs from "node:fs/promises";
-import { nodeDirectorySearchOnlyFlags } from "./directory-mode-node.js";
-import { assertOwnedDirectory } from "./directory-mode-owner.js";
+import { nodeDirectorySearchOnlyFlags, assertOwnedDirectory } from "./directory-mode-node.js";
 import { FsSafeError } from "./errors.js";
 import { assertNoWindowsPathAlias, pathForWindowsFilesystem, resolvePathPreservingWindowsRoot, } from "./windows-path-alias.js";
 import { inspectFileIdentitySync } from "./strict-file-identity.js";
-import { assertTempWorkspaceChildState, childHasRequestedMode, validateAdmittedTempWorkspaceChild, } from "./temp-workspace-child-admission.js";
-import { inspectTempWorkspaceDescriptorIdentitySync, inspectTempWorkspaceDirectoryIdentitySync, projectTempWorkspaceNumericIdentity, TEMP_WORKSPACE_NUMERIC_IDENTITY_REPLAY, } from "./temp-workspace-identity.js";
+import { assertTempWorkspaceChildState, childHasRequestedMode, validateAdmittedTempWorkspaceChild, inspectTempWorkspaceDescriptorIdentitySync, inspectTempWorkspaceDirectoryIdentitySync, projectTempWorkspaceNumericIdentity, TEMP_WORKSPACE_NUMERIC_IDENTITY_REPLAY, } from "./temp-workspace-child-admission.js";
 function assertRetainedChildDirectory(stat) {
     if (stat.isSymbolicLink() || !stat.isDirectory()) {
         throw new FsSafeError("not-file", "temp workspace child must be a real directory");

package/dist/text-atomic.js

@@ -1,5 +1,5 @@
 import { replaceFileAtomic } from "./replace-file.js";
-import { admitStandalonePublicationPath } from "./standalone-publication-path.js";
+import { admitStandalonePublicationPath } from "./windows-path-alias.js";
 export async function writeTextAtomic(filePath, content, options) {
     const admittedPath = admitStandalonePublicationPath(filePath);
     const payload = options?.trailingNewline && !content.endsWith("\n") ? `${content}\n` : content;

package/dist/windows-owner.d.ts

@@ -1,9 +1,9 @@
-import { type PermissionCommandFailure } from "./permission-exec.js";
+import { type PermissionFailureFields } from "./permission-exec.js";
 export type WindowsOwnerExec = (command: string, args: string[]) => Promise<{
     stdout: string;
     stderr: string;
 }>;
-export type WindowsOwnerSummary = {
+export type WindowsOwnerSummary = Omit<PermissionFailureFields & {
     sid?: string;
     currentUserSid?: string;
     daclPresent?: boolean;
@@ -11,10 +11,7 @@ export type WindowsOwnerSummary = {
     aclError?: string;
     remote?: boolean;
     trusted?: boolean;
-    error?: string;
-    errorDetail?: PermissionCommandFailure;
-    errorCause?: unknown;
-};
+}, never>;
 export type WindowsOwnerAce = {
     sid: string;
     mask: number;

package/dist/windows-owner.js

@@ -1,4 +1,4 @@
-import { formatCaughtPermissionFailure, formatPermissionErrorDetail, getPermissionCommandFailure, } from "./permission-exec.js";
+import { formatCaughtPermissionFailure, getPermissionCommandFailure, } from "./permission-exec.js";
 import { resolveWindowsSystemCommand } from "./windows-command.js";
 import { hasWindowsPathAlias } from "./windows-path-alias.js";
 const SID_RE = /^\*?s-\d+-\d+(-\d+)+$/i;

package/dist/windows-path-alias.d.ts

@@ -36,3 +36,4 @@ export declare function hasWindowsPathAlias(value: string, kind: WindowsPathAlia
 export declare function assertNoWindowsPathAliasForPlatform(value: string, kind: WindowsPathAliasKind, message: string, platform: NodeJS.Platform | string | undefined): void;
 export declare function assertNoWindowsPathAlias(value: string, kind?: WindowsPathAliasKind, message?: string, platform?: NodeJS.Platform | string): void;
 export declare function isWindowsPathAliasError(error: unknown): error is FsSafeError;
+export declare function admitStandalonePublicationPath(value: string, message?: string): string;

package/dist/windows-path-alias.js

@@ -115,3 +115,8 @@ export function assertNoWindowsPathAlias(value, kind = "filesystem", message = "
 export function isWindowsPathAliasError(error) {
     return error instanceof FsSafeError && error.details?.reason === "windows-path-alias";
 }
+export function admitStandalonePublicationPath(value, message) {
+    const admittedPath = anchorWindowsDriveRelativePath(value);
+    assertNoWindowsPathAlias(admittedPath, "filesystem", message);
+    return admittedPath;
+}

package/dist/windows-security-bridge.cs

@@ -2,8 +2,6 @@
 // descriptor never passes through CommonSecurityDescriptor's ACE normalization.
 using System;
 using System.Collections.Generic;
-using System.ComponentModel;
-using System.IO;
 using System.Runtime.InteropServices;
 using System.Security.AccessControl;
 using System.Security.Principal;

package/docs/advanced.md

@@ -106,7 +106,9 @@ before component traversal. Immediately before transferring descriptor ownership
 they check that root, freshly canonicalize the consumed pathname, admit the fresh
 spelling under the captured root, compare a no-follow canonical-leaf observation
 with the retained descriptor, and check the root again. Boundary or identity drift
-is a validation failure and the descriptor is closed. A custom `ioFs` supplies
+is a validation failure and triggers one descriptor-close attempt. If cleanup also
+fails, the selected admission failure result is preserved. Successful opens transfer
+descriptor ownership to the caller. A custom `ioFs` supplies
 these observations; the built-in adapter uses fs-safe's native realpath wrapper.
 On Windows, the built-in adapter binds native root spelling before traversal,
 including supplied `rootRealPath`, and returns that spelling in its root receipt.

package/docs/secret-file.md

@@ -113,6 +113,10 @@ If an already validated descriptor fails while reading, both readers throw an
 operational `FsSafeError` with `code: "read-failed"`; inspect `cause` for the
 underlying Node filesystem code such as `EIO`.
 
+Caught `null` or `undefined` inspection and read failures are reported as
+structured errors with an `Error` cause carrying `"null"` or `"undefined"`,
+instead of an internal `TypeError` while inspecting the thrown value.
+
 A synchronous reader closes its descriptor once. A close failure preserves an
 earlier read or identity-validation error; after a successful read, the close
 failure is reported before trimming or rejecting empty content.
@@ -137,6 +141,11 @@ startWebhookVerifier(signingKey);
 
 Async. Creates the parent directory at `dirMode` (default `0o700`) if missing, writes content to a sibling temp file, finalizes `mode` (default `0o600`) through an owned descriptor after content writes, and atomically renames over the destination. Publication verification checks the final file identity and mode.
 
+Both secret writers capture top-level parameter values when called, before
+asynchronous filesystem preparation; a supplied byte buffer is captured by
+reference. A parameter getter throwing `null` or `undefined` rejects with that
+same value before filesystem inspection.
+
 On POSIX, both native and JavaScript writers verify actual `0o600` permission
 bits through the retained descriptor before writing content. A filesystem that
 reports successful chmod without enforcing those bits fails with
@@ -205,6 +214,10 @@ Both mode options must resolve to integers between `0o0000` and `0o7777`; invali
 
 After this operation wins directory creation, initialization uses a pinned descriptor bound to the admitted identity and effective user, with ancestor checks before chmod. It does not chmod the caller's pathname. Creation and descriptor admission are separate operations, not an atomic create-and-pin guarantee. A raced directory that has not reached its requested mode yet is rejected rather than repaired; callers may retry after its creator finishes initialization.
 
+If initial directory-descriptor admission fails, its original identity, ownership,
+or inspection error is preserved even when closing the rejected descriptor fails.
+Close failures after successful admission remain reportable.
+
 Initialization fails closed if the platform cannot safely pin a created directory. In particular, a non-root macOS process cannot pin a new `000` directory produced by `umask(0o777)`; the write fails without repairing that directory or writing a secret. Restrictive masks retaining owner search permission remain usable. Linux x64/arm64 can use the guarded `O_PATH`/procfs descriptor route where available. There is no unguarded pathname-chmod fallback, and a failure may leave a created directory for caller-managed cleanup.
 
 ### `createSecretFileAtomic(params)`

package/docs/sidecar-lock.md

@@ -199,6 +199,10 @@ explicit `retry.retries` still applies with `timeoutMs: Infinity`, and zero allo
 only the initial attempt. After process defaults are applied, an omitted retry
 count means unlimited retries, and an omitted or infinite timeout means no
 deadline. With neither budget bounded, contention can wait indefinitely.
+Finite deadlines use monotonic elapsed time, so system clock corrections do not
+extend or shorten the retry budget. Payload timestamps, `heldEntries().acquiredAt`,
+and stale-policy `nowMs` remain wall-clock based. Deadlines are checked at retry
+boundaries; they do not interrupt callbacks or filesystem operations.
 `parsePayload` replaces JSON parsing for legacy or custom sidecars. Its `unknown`
 result is passed to `shouldReclaim` and `shouldRemoveStaleLock`, allowing PID,
 process-start, argv, or role schemas to remain application-owned.
@@ -263,6 +267,8 @@ Pass `lockRoot` to place sidecar create, read, verification, and removal behind
 an existing `Root` capability. `lockPath` must resolve inside that root.
 Identity-conditioned removal remains the only release and reclaim deletion
 path.
+Root mutation refusals during stale removal propagate unchanged, including
+`null`, `undefined`, and errors carrying `ENOENT`; they do not become missing-sidecar retries.
 
 Async Root-backed acquisition normalizes the target's parent without creating
 it, checking the retained Root before and after normalization. A deleted or

package/docs/store.md

@@ -93,6 +93,12 @@ existing single-load rejection and batch-skip behavior. A caller or migration
 error with code `ENOENT` is still a failure, not a missing queue entry; only a
 claim that is absent or disappears before reading returns `null` from a single load.
 
+If closing the read descriptor also fails, the original read, validation,
+callback, or migration failure keeps precedence, including non-Error rejection
+values. A close failure without an earlier failure is reported through the same
+loader policy: direct reads and single loads reject, while batch loads skip it
+unless migration has started.
+
 On Windows, migration releases its read pin once at this publication boundary
 because an open target can block replacement. It rechecks the exact pathname
 identity after the asynchronous close while still holding the transfer lock.

package/docs/temp.md

@@ -31,6 +31,8 @@ rejects with `permission-unverified`. Existing supplied directories keep their
 permissions. Missing root components are created at `0o700` and initialized
 from their first exact security snapshot; if a restrictive umask changes that
 mode, correction uses a verified directory descriptor.
+An initial mode-descriptor admission error is preserved if closing that rejected
+descriptor also fails; close failures after successful admission remain reportable.
 
 For an already existing canonical root, discovery retains only its immutable
 exact identity. Cleanup-parent retention is provisional: after any native
@@ -645,7 +647,12 @@ recursive-`mkdir` winner is inspected as an untrusted existing directory.
 Broad-mode repair also uses a pinned descriptor; there is no pathname chmod.
 
 Repair and finalization require a known nonnegative safe-integer UID and exact
-bigint device, inode, owner, mode, and directory-type facts. They open with
+bigint device, inode, owner, mode, and directory-type facts. Device and inode
+identities accept Node's signed 64-bit stat representation, including negative
+values down to `-(1n << 63n)`; inode zero remains invalid. Previously supported
+nonnegative device and positive inode adapter values remain supported without
+an upper cap. Values are compared exactly as received: signed and unsigned
+encodings of the same bits are not treated as equal. They open with
 `O_RDONLY | O_DIRECTORY | O_NOFOLLOW | O_NONBLOCK`, verify the descriptor and
 current directory entry against the initial receipt before `fchmod`, then
 verify identity, permissions, and write/search access again before closing.

package/docs/writing.md

@@ -198,6 +198,11 @@ existing `durable` file/directory synchronization policy; it does not turn
 best-effort synchronization into a strict crash-durability guarantee or strengthen
 JavaScript pathname containment.
 
+Wider option objects do not enable create-only `atomic` or `private` behavior on
+`write` or `writeJson`. Buffered Root writes and creates also ignore an extra
+`maxBytes` property; that byte limit belongs to streamed creation and `copyIn`.
+File synchronization follows each method's documented `durable` option.
+
 Atomic and streamed creates settle owned cleanup and close operations before
 returning. Failed or unverifiable cleanup is reported rather than silently
 discarded. Errors after publication and incomplete-settlement errors carry the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/fs-safe",
-  "version": "0.18.0",
+  "version": "0.18.2",
   "description": "Capability-style filesystem roots for Node.js apps that handle untrusted relative paths.",
   "keywords": [
     "filesystem",
@@ -169,13 +169,13 @@
     "archive:producer-smoke": "node scripts/archive-producer-smoke.mjs"
   },
   "optionalDependencies": {
-    "@openclaw/fs-safe-darwin-arm64": "0.18.0",
-    "@openclaw/fs-safe-darwin-x64": "0.18.0",
-    "@openclaw/fs-safe-linux-arm64-gnu": "0.18.0",
-    "@openclaw/fs-safe-linux-arm64-musl": "0.18.0",
-    "@openclaw/fs-safe-linux-x64-gnu": "0.18.0",
-    "@openclaw/fs-safe-linux-x64-musl": "0.18.0",
-    "@openclaw/fs-safe-win32-x64-msvc": "0.18.0",
+    "@openclaw/fs-safe-darwin-arm64": "0.18.2",
+    "@openclaw/fs-safe-darwin-x64": "0.18.2",
+    "@openclaw/fs-safe-linux-arm64-gnu": "0.18.2",
+    "@openclaw/fs-safe-linux-arm64-musl": "0.18.2",
+    "@openclaw/fs-safe-linux-x64-gnu": "0.18.2",
+    "@openclaw/fs-safe-linux-x64-musl": "0.18.2",
+    "@openclaw/fs-safe-win32-x64-msvc": "0.18.2",
     "jszip": "^3.10.2"
   },
   "devDependencies": {

package/dist/archive-native.d.ts

@@ -1,10 +0,0 @@
-import type { ArchiveKind } from "./archive-kind.js";
-import { type TarMeterLimits } from "./archive-limits.js";
-import type { StagedArchiveExtractOptions } from "./archive-options.js";
-import type { NativeBinding } from "./native.js";
-export declare function throwMappedNativeArchiveError(error: unknown): never;
-export declare function extractNativeArchive(params: StagedArchiveExtractOptions & {
-    binding: NativeBinding;
-    kind: ArchiveKind;
-    tarLimits: TarMeterLimits;
-}): Promise<void>;

package/dist/archive-native.js

@@ -1,73 +0,0 @@
-import { classifyArchiveParserError } from "./archive-parser-errors.js";
-import { constants as fsConstants } from "node:fs";
-import fs from "node:fs/promises";
-import { ArchiveFormatError, isArchiveFormatErrorMessage, } from "./archive-errors.js";
-import { validateArchiveEntryPath } from "./archive-entry.js";
-import { createArchiveEntryPlanner } from "./archive-plan.js";
-import { assertArchiveEntryCountWithinLimit, } from "./archive-limits.js";
-import { prepareArchiveDestinationGuard } from "./archive-staging.js";
-import { withStagedArchivePublication } from "./archive-merge.js";
-import { admitZipFile } from "./archive-zip-admission.js";
-import { validateNativeZipManifest } from "./archive-zip-manifest.js";
-export function throwMappedNativeArchiveError(error) {
-    if (error instanceof Error) {
-        const mapped = classifyArchiveParserError(error.message, { cause: error });
-        if (mapped)
-            throw mapped;
-        if (isArchiveFormatErrorMessage(error.message)) {
-            throw new ArchiveFormatError(error.message, { cause: error });
-        }
-        if (error.code === "InvalidArg") {
-            throw new ArchiveFormatError(`invalid archive: ${error.message}`, { cause: error });
-        }
-    }
-    throw error;
-}
-export async function extractNativeArchive(params) {
-    const { archivePath, limits, tarLimits, deadline } = params;
-    const zipEntries = [];
-    if (params.kind === "zip") {
-        await admitZipFile(archivePath, limits, deadline, (entry) => { zipEntries.push(entry); });
-    }
-    const destinationGuard = await prepareArchiveDestinationGuard(params.destDir);
-    await withStagedArchivePublication({ ...params, destinationGuard }, async (stagingDir) => {
-        deadline.check();
-        // N-API retains completed task state on its signal; each pass needs its own.
-        const manifest = await params.binding
-            .inspectArchiveNative(archivePath, params.kind, tarLimits, AbortSignal.any([deadline.signal]))
-            .catch(throwMappedNativeArchiveError);
-        deadline.check();
-        assertArchiveEntryCountWithinLimit(manifest.length, limits);
-        if (params.kind === "zip") {
-            validateNativeZipManifest(manifest, zipEntries);
-        }
-        // Recheck the native manifest before any caller callback observes an entry.
-        if (params.kind !== "zip") {
-            for (const entry of manifest)
-                validateArchiveEntryPath(entry.path);
-        }
-        const planEntry = createArchiveEntryPlanner({ ...params, rootDir: stagingDir }, params.kind);
-        const plan = [];
-        for (const entry of manifest) {
-            deadline.check();
-            const mode = params.kind === "zip"
-                ? zipEntries[entry.index].creatorSystem === 3
-                    ? zipEntries[entry.index].externalAttributes >>> 16
-                    : undefined
-                : entry.mode;
-            const accepted = planEntry({ ...entry, mode });
-            if (accepted)
-                plan.push({ ...accepted, index: entry.index });
-        }
-        const directory = await fs.open(stagingDir, fsConstants.O_RDONLY |
-            (typeof fsConstants.O_DIRECTORY === "number" ? fsConstants.O_DIRECTORY : 0));
-        try {
-            deadline.check();
-            await params.binding.extractArchiveNative(archivePath, params.kind, directory.fd, plan.map((entry) => ({ ...entry, mode: entry.kind === "directory" ? 0o700 : 0o600 })), tarLimits, AbortSignal.any([deadline.signal])).catch(throwMappedNativeArchiveError);
-        }
-        finally {
-            await directory.close().catch(() => undefined);
-        }
-        return plan;
-    });
-}

package/dist/archive-options.d.ts

@@ -1,30 +0,0 @@
-import type { ArchiveKind } from "./archive-kind.js";
-import type { ExtractionDeadline } from "./archive-deadline.js";
-import type { ArchiveExtractLimits, ResolvedArchiveExtractLimits } from "./archive-limits.js";
-import type { ArchiveEntryFilter, ArchiveEntryModePolicy, ArchiveFilteredEntryPolicy } from "./archive-policy.js";
-export type ArchiveLogger = {
-    info?: (message: string) => void;
-    warn?: (message: string) => void;
-};
-export type ExtractArchiveOptions = {
-    archivePath: string;
-    destDir: string;
-    timeoutMs: number;
-    /** Sync published files and directories before returning. Defaults to false. */
-    durable?: boolean;
-    kind?: ArchiveKind;
-    stripComponents?: number;
-    tarGzip?: boolean;
-    limits?: ArchiveExtractLimits;
-    logger?: ArchiveLogger;
-    entryModes?: ArchiveEntryModePolicy;
-    /** Remove these rwx bits from final entry modes. Defaults to zero. */
-    entryUmask?: number;
-    entryFilter?: ArchiveEntryFilter;
-    onFiltered?: ArchiveFilteredEntryPolicy;
-};
-/** Private executors receive owned options and an already-staged archive path. */
-export type StagedArchiveExtractOptions = Pick<ExtractArchiveOptions, "archivePath" | "destDir" | "durable" | "stripComponents" | "entryModes" | "entryUmask" | "entryFilter" | "onFiltered"> & {
-    limits: ResolvedArchiveExtractLimits;
-    deadline: ExtractionDeadline;
-};

package/dist/archive-policy.d.ts

@@ -1,21 +0,0 @@
-export type ArchiveEntryKind = "file" | "directory" | "symlink" | "other";
-export type ArchiveEntryModePolicy = "clamp" | "preserve";
-export type ArchiveFilteredEntryPolicy = "reject-archive" | "skip-entry";
-export type ArchiveEntryFilter = (entry: {
-    /** Validated canonical archive path before stripping: / separators, no empty or . components. */
-    path: string;
-    kind: ArchiveEntryKind;
-    size: number;
-}) => "extract" | "skip";
-export declare function archiveEntryKindFromTarType(type: string): ArchiveEntryKind;
-export declare function resolveArchiveEntryMode(params: {
-    kind: "file" | "directory";
-    archivedMode?: number | null;
-    policy?: ArchiveEntryModePolicy;
-}): number;
-export declare function resolveArchiveFilteredEntryPolicy(value: unknown): ArchiveFilteredEntryPolicy;
-export declare function shouldExtractArchiveEntry(params: {
-    filter?: ArchiveEntryFilter;
-    onFiltered?: ArchiveFilteredEntryPolicy;
-    entry: Parameters<ArchiveEntryFilter>[0];
-}): boolean;