@openclaw/feishu 2026.9.8 → 2026.10.1-beta.1

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

@@ -1,3 +1,4 @@
+import path from "node:path";
 export function isWindowsSeparator(value, offset) {
     const code = value.charCodeAt(offset);
     return code === 0x2f || code === 0x5c;
@@ -19,3 +20,53 @@ export function rootedWindowsDriveColonIndex(value) {
         : windowsNamespaceMarker(value) !== undefined && hasWindowsDrivePrefix(value, 4) ? 5 : -1;
     return colon >= 0 && isWindowsSeparator(value, colon + 1) ? colon : -1;
 }
+function asciiLowercase(value) {
+    return value.replace(/[A-Z]/g, letter => String.fromCharCode(letter.charCodeAt(0) + 0x20));
+}
+/**
+ * True when dot-like components climb above the start of `segments`. Win32
+ * trims trailing dots and spaces, so any all-dot or all-space component other
+ * than `.` is counted as a parent step.
+ */
+export function windowsSegmentsClimbAbove(segments) {
+    let depth = 0;
+    for (const segment of segments) {
+        if (segment === "" || segment === ".")
+            continue;
+        depth += /^[. ]+$/.test(segment) ? -1 : 1;
+        if (depth < 0)
+            return true;
+    }
+    return false;
+}
+/**
+ * Comparable share or device root of a path spelled with two leading
+ * separators, excluding namespaced drive roots such as `\\?\C:\`.
+ * Returns undefined for drive, rooted, and relative spellings, and null when
+ * the spelling alone cannot establish which share or device it reaches.
+ */
+export function windowsShareOrDeviceRoot(value) {
+    if (!isWindowsSeparator(value, 0) || !isWindowsSeparator(value, 1))
+        return undefined;
+    const spelled = value.replaceAll("/", "\\");
+    if (windowsNamespaceMarker(spelled) === undefined) {
+        return asciiLowercase(path.win32.parse(spelled).root.replace(/\\+$/, ""));
+    }
+    // Node passes namespace spellings to Win32 unchanged, where `..` climbs out
+    // of a drive or share (`\\.\C:\..\UNC\host`) and trailing dots, spaces and
+    // empty components are rewritten. GLOBALROOT and Global expose whole object
+    // namespaces, so none of these identify a single share or device.
+    const segments = spelled.slice(4).split("\\");
+    const head = asciiLowercase(segments[0] ?? "");
+    const authority = head === "unc" ? segments.slice(0, 3) : segments.slice(0, 1);
+    if (head === "globalroot" || head === "global" || authority.length < (head === "unc" ? 3 : 1) ||
+        authority.some(segment => segment === "" || /[. ]$/.test(segment)) ||
+        windowsSegmentsClimbAbove(segments.slice(authority.length))) {
+        return null;
+    }
+    if (rootedWindowsDriveColonIndex(value) === 5)
+        return undefined;
+    return asciiLowercase(head === "unc"
+        ? `\\\\${authority[1]}\\${authority[2]}`
+        : `${spelled.slice(0, 4)}${authority[0]}`);
+}

package/node_modules/@openclaw/fs-safe/docs/advanced.md

@@ -63,6 +63,9 @@ supplies a path that must stay under a root.
 The helper returns `{ ok: false, code, error }` for path-policy failures such as
 relative paths, symlinks, non-directories, or directory swaps during creation.
 Operational filesystem failures such as permissions or I/O errors are rethrown.
+Directory guards retain exact bigint identities, including Windows file IDs
+above JavaScript's integer precision. These checks remain best-effort against
+concurrent namespace changes.
 
 ### Files and identity
 
@@ -77,6 +80,7 @@ Operational filesystem failures such as permissions or I/O errors are rethrown.
 | `overwriteFileHandle`, `OverwriteFileHandleOptions` | [in-place-write.md](in-place-write.md) | Overwrite a borrowed read/write handle with prefix-only preparation and best-effort rollback; preserves its inode, cursor, and caller-owned lifetime. |
 | `openRootFile`, `openRootFileSync`, `canUseRootFileOpen`, `matchRootFileOpenFailure`, related types | – | Low-level root-bounded open; rejects every symlink component by default, with `symlinks: "follow-parents-within-root"` for contained parent aliases or `"follow-within-root"` for final links too. |
 | `appendRegularFile`, `appendRegularFileSync`, `readRegularFile`, `readRegularFileSync`, `statRegularFile`, `statRegularFileSync`, `resolveRegularFileAppendFlags`, `AppendRegularFileOptions`, `RegularFileStatResult` | [regular-file.md](regular-file.md) | Type-checked regular-file I/O. |
+| `retainEntryForPublication`, `RetainedEntryPublication`, `RetainEntryForPublicationOptions`, `EntryPublicationReceipt`, `EntryPublicationResult`, `EntryPublicationIssue`, `PublicationIdentity`, `PublicationParent` | [One-way entry publication](entry-publication.md) | Native no-replace directory/regular-file/symlink export, including Windows NTFS junctions, under caller-exclusive namespace; explicit transition receipts, close-only disposal, no source CAS. |
 | `retainFileInDirectory`, `RetainedFile`, related receipt/result types | [Retained Windows files](retained-file.md) | Existing-file native handle custody and explicit removal; local NTFS, producer authority required, no persistence guarantee. |
 | `sameFileIdentity`, `FileIdentityStat` | – | Compare two stats for same-inode equality. |
 | `readDirectoryIdentity`, `assertDirectoryIdentitySync`, `DirectoryIdentity` | [directory-identity.md](directory-identity.md) | Observe exact bigint directory identity and synchronously check a caller-selected path, optionally retaining its canonical path. |

package/node_modules/@openclaw/fs-safe/docs/atomic.md

@@ -233,6 +233,9 @@ synchronous throws and rejected promises from custom asynchronous adapters.
 
 The best-effort parent-directory synchronization helper also ignores either form
 of close failure. Parent-directory mode admission and its close remain fail-closed.
+If parent preparation and its descriptor close both fail, sync and async replacement
+report an `AggregateError` retaining the preparation failure first and the close
+failure second. A close failure alone is propagated unchanged.
 A compatibility-publication handle that was not adopted also receives one
 best-effort close, preserving the selected verification or previous-handle close
 failure. The retained owner's close failures remain reportable.
@@ -601,7 +604,7 @@ type ReplaceFileAtomicSyncFileSystem = {
 };
 ```
 
-The async interface already requires `open()`, whose `FileHandle` supplies `chmod()`, so injecting `node:fs` or another conforming adapter needs no new async member. The async temp owner consumes its retained handle before awaiting `close()` during publication handoff and terminal settlement: if a custom adapter releases the resource and then rejects, that rejection is reported without calling `close()` on the same retained handle again. If publication verification opened a replacement handle before the previous retained handle failed to close, the replacement receives one best-effort close attempt. On POSIX, `open()` must support no-follow directory descriptors as Node does. A custom synchronous filesystem that passes `mode`, `dirMode`, or `preserveExistingMode` must supply `fchmodSync`; omission fails before any file or directory is created and never falls back to a pathname `chmod`. Existing synchronous adapters that request none of those options may omit it; their parent is still opened and identity-checked through a no-follow directory descriptor. Injecting plain `node:fs` supports explicit file and directory modes. Older adapter literals may continue to include `chmod` or `chmodSync` for source compatibility, but those operations are ignored. Copy fallback applies the file mode through its pinned destination descriptor as well, preserving exact modes despite the process umask.
+The async interface already requires `open()`, whose `FileHandle` supplies `chmod()`, so injecting `node:fs` or another conforming adapter needs no new async member. The async temp owner consumes its retained handle before awaiting `close()` during publication handoff and terminal settlement: if a custom adapter releases the resource and then rejects, that rejection is reported without calling `close()` on the same retained handle again. If publication verification opened a replacement handle before the previous retained handle failed to close, the replacement receives one best-effort close attempt. On POSIX, `open()` must support no-follow directory descriptors as Node does. A custom synchronous filesystem that passes `mode`, `dirMode`, or `preserveExistingMode` must supply `fchmodSync`; omission fails before any file or directory is created and never falls back to a pathname `chmod`. Existing synchronous adapters that request none of those options may omit it; their parent is still opened and identity-checked through a no-follow directory descriptor. Injecting plain `node:fs` supports explicit file and directory modes. Copy fallback applies the file mode through its pinned destination descriptor as well, preserving exact modes despite the process umask.
 
 ## See also
 

package/node_modules/@openclaw/fs-safe/docs/config.md

@@ -112,20 +112,12 @@ FS_SAFE_NATIVE_MODE=auto      # auto | off | require | true | false | on | 1 | 0
 
 `OPENCLAW_FS_SAFE_NATIVE_MODE` is accepted as an alias. Programmatic overrides via `configureFsSafeNative` always win.
 
-### Python-helper migration bridge
-
-Version 0.5 detects the former `FS_SAFE_PYTHON_MODE`, `FS_SAFE_PYTHON`,
-`OPENCLAW_FS_SAFE_PYTHON_MODE`, `OPENCLAW_FS_SAFE_PYTHON`,
-`OPENCLAW_PINNED_PYTHON`, and `OPENCLAW_PINNED_WRITE_PYTHON` names. It emits one
-`FS_SAFE_PYTHON_DEPRECATED` warning and maps `auto`, `off`, or `require` to the
-same native mode; interpreter paths are ignored. The deprecated
-`configureFsSafePython()` export behaves the same way.
-
-Replace these inputs with `configureFsSafeNative()` or
-`FS_SAFE_NATIVE_MODE` during the 0.5 upgrade. The bridge exists only so shipped
-0.4 configuration fails loudly and maps predictably; it is not a supported
-Python execution path. Follow the [0.5 migration checklist](migrating-to-0.5.md)
-for the full upgrade.
+### Removed Python-helper configuration
+
+The deprecated Python configuration bridge and its environment variables have
+been removed. Use `configureFsSafeNative()` or `FS_SAFE_NATIVE_MODE`. See the
+[0.5 migration checklist](migrating-to-0.5.md#2-replace-python-helper-configuration)
+for the migration path.
 
 ## Related pages
 

package/node_modules/@openclaw/fs-safe/docs/contributing.md

@@ -336,20 +336,10 @@ Small, focused PRs land faster. The general shape:
 
 ## Releases
 
-Maintainers publish from a protected `vX.Y.Z` tag on `main` through
-`.github/workflows/release.yml`. The workflow requires the package version and a
-dated `CHANGELOG.md` section to match the tag. It builds and publishes all seven
-platform packages before publishing `@openclaw/fs-safe`, verifies every registry
-artifact and provenance statement, and then creates the GitHub release.
-
-Each package needs its own npm trusted-publisher configuration for
-`openclaw/fs-safe` and `release.yml`. A new platform package must be created and
-configured on npm before the first tag that references it; npm trust is
-package-specific and cannot be bootstrapped by the tag workflow itself.
-
-External contributors do not need to do anything beyond getting the pull
-request merged. Maintainers must not publish locally or add npm automation
-tokens.
+Releases use protected `vX.Y.Z` tags on `main` and npm trusted publishing.
+Contributors finish at PR merge; maintainers follow the
+[release checklist](https://github.com/openclaw/fs-safe/blob/main/RELEASE-PREREQS.md).
+Do not publish locally or add npm automation tokens.
 
 ## Reporting security issues
 

package/node_modules/@openclaw/fs-safe/docs/durability.md

@@ -217,35 +217,12 @@ clone or `copy_file_range` transparently continues down the fallback chain.
 
 ## Recoverable atomic-replace fallback
 
-`replaceFileAtomic()` normally publishes a synchronized sibling temp with an
-atomic rename. Some Windows filesystems and file owners reject that rename with
-`EPERM` or `EEXIST`; `copyFallbackOnPermissionError: true` permits a non-atomic
-copy fallback.
-
-Callers that cannot tolerate a torn in-place fallback can add:
-
-```ts
-await replaceFileAtomic({
-  filePath: statePath,
-  content: nextState,
-  syncTempFile: true,
-  syncParentDir: true,
-  copyFallbackOnPermissionError: true,
-  copyFallbackRestore: "restore-original",
-  maxRestoreBytes: 4 * 1024 * 1024,
-  destinationHardlinks: "reject",
-});
-```
-
-The existing regular-file destination is pinned before its link count is
-accepted. Its original bytes are read within `maxRestoreBytes`, then the new
-bytes are written and synchronized through the same descriptor. If a write or
-sync tears, fs-safe rewrites the snapshot and fsyncs it before throwing. Inspect
-`details.cleanup`: `"restored"` means the original bytes were put back and
-synchronized; `"restore-failed"` means the replacement and recovery both
-failed, so the destination must be treated as indeterminate. This is recovery
-from a live-process I/O failure, not a transaction or a substitute for an
-application backup protocol.
+`replaceFileAtomic()` normally publishes a sibling temp with an atomic rename;
+file and directory synchronization are opt-in. Its permission-error copy fallback
+remains non-atomic even with opt-in `copyFallbackRestore: "restore-original"`.
+Recovery requires an explicit `maxRestoreBytes` budget and inspection of the
+`details.cleanup` receipt. See [Atomic writes](atomic.md#eperm-and-copy-fallback)
+for restoration limits, identity/authority refusals, and retained-inode semantics.
 
 ## Streaming SHA-256
 

package/node_modules/@openclaw/fs-safe/docs/entry-publication.md

@@ -0,0 +1,146 @@
+---
+title: One-way entry publication
+description: Retained directory, regular-file and symlink publication with atomic destination absence, under caller-owned namespace stability.
+---
+
+# One-way retained entry publication
+
+`retainEntryForPublication` from `@openclaw/fs-safe/advanced` admits an existing
+directory, single-link regular file or single-link symlink for a **one-way, native no-replace rename**.
+It retains both parent directories and the source object. It never reverses a
+move, unlinks a name, removes a tree, or copies across filesystems.
+
+This is an advanced cooperative primitive, **not a sandbox or source-identity
+compare-and-swap**. The caller must exclude source namespace writers from its
+original observation through publication, and keep the admitted physical parent
+and ancestor topology stable through all later pathname consumers. Descriptors
+prevent identity reuse and bind the native rename to retained parents; they do
+not pin the source name or confine the operation to the parents' current paths.
+Observed substitutions refuse; substitutions after the last check remain outside
+this contract. A callback, lockfile, random directory or mode `0700` does not
+exclude arbitrary same-user nonparticipants.
+
+## Inputs and admission
+
+```ts
+import {
+  retainEntryForPublication,
+  type RetainEntryForPublicationOptions,
+  type EntryPublicationResult,
+} from "@openclaw/fs-safe/advanced";
+
+function publishManagedEntry(options: RetainEntryForPublicationOptions): EntryPublicationResult {
+  const publication = retainEntryForPublication(options);
+  return publication.publish();
+}
+```
+
+`options` contains:
+
+- `source.parent` and `destination.parent`: `{ path, identity: { dev, ino } }`.
+  Paths must already be absolute canonical physical spellings, with no symlink,
+  case or lexical aliases. Preserve caller-captured original identities; never
+  substitute a new observation merely to make a stale admission succeed.
+- `source.basename` and `destination.basename`: nonempty direct-child names.
+  Dot entries, separators, colons, NUL and control characters are refused.
+- `source.expected`: `{ dev, ino, kind: "directory" | "file" | "symlink" }`. Identities must
+  be exact unsigned bigint observations with a known nonzero inode. File contents
+  are not hashed, frozen or made read-only. Regular files and symlinks must have one link;
+  directories are not recursively inspected. Source and destination must not
+  overlap. Special entries are not supported.
+- `assertBeforeMutation`: required synchronous authority callback. Throw to refuse.
+  Promises and generators refuse. The callback runs once in `publish()`, followed
+  by fresh source and parent checks. It cannot dispose or reenter the resource.
+  It supplies authorization, not namespace isolation.
+
+Admission can throw `FsSafeError`. `cause` retains the original admission error;
+`details.result` reports `not-published`, descriptor settlement and ordered issues.
+Admission never changes either namespace. Caller cleanup responsibilities do not
+transfer to this resource.
+
+Symlink publication moves the link inode, never its payload. Link target bytes are
+not decoded, resolved or rewritten; relative, dangling and non-UTF-8 targets are
+preserved. Relative targets resolve from the final parent after publication, so
+the caller must prepare the correct final layout. External payloads remain owned
+by their existing owner, and the caller must hold any target/ancestor stability
+needed by subsequent consumers. Source symlink basenames must match the physical
+directory entry spelling; parent aliases remain refused. No recursive symlink
+policy is imposed on the contents of a published directory.
+
+## Results and lifetime
+
+`publish()` is synchronous, one-shot, and closes every retained descriptor/handle
+before returning an immutable `EntryPublicationResult`. Inspect **all** fields:
+
+| Field | Meaning |
+| --- | --- |
+| `transition: "committed"` | Native rename returned success. Recorded before verification or close. |
+| `transition: "not-published"` | Refused before dispatch, or a determinate native rejection. Both entries are preserved by this operation. |
+| `transition: "indeterminate"` | Native reply was lost/malformed or the error did not prove rejection. Retain both locations; do not infer a result from later path observations. |
+| `verification` | `verified`, `failed`, or `not-performed`. A failed postcheck never changes committed to not-published. |
+| `resources` | `closed` or `close-failed`. Every owned close is attempted once, even if an earlier close failed; ambiguous closes are never retried. |
+| `issues` | Ordered `{ phase, cause }` failures. The first is primary, including falsy thrown values; later close failures do not mask it. |
+
+A committed result with issues is not an error-free publication. The immutable
+`receipt` records original source/destination observations and capability facts:
+`destinationAbsence: "atomic"`,
+`sourceIdentity: "observed-under-caller-exclusive-namespace"`, and
+`parentBinding: "retained-object"`, plus admitted filesystem names.
+
+`dispose()` only closes. It does not delete unpublished staging or published
+names. Subsequent `publish()`/`dispose()` return the same terminal result without
+another effect. `Symbol.dispose` closes too, throwing with `details.result` if
+closure reported a failure. Retain an unused resource only while its namespace
+contract is held, then explicitly dispose it; there is no GC cleanup guarantee.
+
+Results are in-memory syscall dispositions, **not a durable transaction journal**.
+For crash recovery record intent before dispatch in the caller's own durable
+owner, then persist the result. A crash before receipt persistence is unresolved.
+Several publications are not one atomic transaction: if a later child collides,
+keep prior exposed children, newer destination writes and remaining staging. This
+API deliberately provides no automatic compensation or retry.
+
+## Platform and filesystem contract
+
+Native support is mandatory even in `auto` mode. There is no Node pathname
+rename or copy fallback. This API supports local APFS/HFS on macOS and
+ext-family/XFS/Btrfs/tmpfs on Linux, subject to the kernel/filesystem's native
+no-replace operation (`renameatx_np(RENAME_EXCL)` or `renameat2(RENAME_NOREPLACE)`).
+Network, FUSE, overlay and unknown filesystem types refuse before dispatch;
+On Windows, fixed local NTFS volumes support handle-relative
+`FileRenameInformationEx` without replacement. Other Windows filesystems, remote
+paths and namespace aliases refuse; cross-device moves refuse without copying.
+Other platforms are unsupported.
+Unsupported syscall/flag errors do not trigger another rename implementation.
+
+A preexisting **or raced** empty directory, file or symlink at the destination is
+never overwritten by a successful no-replace call. Admission also rejects a
+destination alias of the source, including Darwin case-only rename exceptions.
+For distinct destination entries this is the syscall guarantee;
+POSIX source selection still occurs by basename. Moving admitted A away and installing
+B after the native source check can cause POSIX to move B. Postchecks may detect
+that only after commitment. Applications needing protection from that schedule
+must use a stronger namespace owner, not treat this API as source CAS.
+
+### Windows entries and resources
+
+`kind: "symlink"` includes Windows file/directory symbolic links
+(`IO_REPARSE_TAG_SYMLINK`) and directory junctions (`IO_REPARSE_TAG_MOUNT_POINT`).
+The original entry handle is renamed relative to the retained destination parent;
+the source is not reopened to select the object for mutation. The complete opaque
+reparse buffer is checked before and after publication, never decoded or rebuilt.
+Other reparse tags fail closed. Relative symbolic-link targets and absolute
+junction targets keep their original bytes. Reparse ancestors are not admitted.
+The caller's existing-empty destination directory and distinct sibling runtime
+stores need not be replaced or removed.
+
+All ancestors and both parents are opened component-by-component without following
+reparse points, checked against physical spellings, and retained until close.
+Original exact same-volume source/parent identities are required. Named source
+observations are checked against the retained handle, including native file ID.
+Windows handle selection does not upgrade the cross-platform receipt into a
+namespace lock, current-path confinement or a durable transaction. Keep the same
+caller-exclusive namespace and stable-topology contract through later consumers.
+Every handle, including partial admission and temporary observation handles, is
+consumed once by explicit close; a lost native reply leaves the transition or
+resource settlement unknown rather than inferring success from pathnames.

package/node_modules/@openclaw/fs-safe/docs/errors.md

@@ -46,6 +46,16 @@ code and `policy` category for compatibility, along with the original `cause`;
 they do not expose native message text or paths. Already-classified `FsSafeError`
 instances and missing-path errors keep their existing classification.
 
+Descriptor exhaustion during writes uses `helper-failed` / `operational` and
+names `EMFILE` (process descriptor limit) or `ENFILE` (system descriptor limit)
+in its message. The original error remains in `cause`, including any
+`SuppressedError` linking publication and disposal failures. When native rename
+has an uncertain outcome, the message explicitly reports indeterminate
+publication and a preserved stage; `details.publication` and `details.cleanup`
+retain that receipt. Descriptors are still closed. An errno alone does not prove
+that publication never happened, so this diagnostic does not authorize removing
+the stage or retrying the write. Existing boundary/policy errors keep their codes.
+
 `details` is an operation-specific receipt, not an alternate error code. For
 example, `publishFileExclusive()` uses it to report the failing phase, created
 target identity, cleanup decision, and failed directory-sync outcome. Narrow
@@ -115,6 +125,12 @@ type FsSafeErrorCode =
 
 ## Code reference
 
+Create-only Root writes to an existing regular file or directory report
+`already-exists` in every native mode, including atomic and streamed creation.
+Policy failures such as an explicit symlink rejection or a denied path retain
+their precedence. A non-directory ancestor still reports its path/type failure;
+it is not an existing destination.
+
 | Code | When it fires | Common causes |
 |---|---|---|
 | `already-exists` | `create()`, `createJson()`, `move({ overwrite: false })`. | Target file or directory already at the destination. |

package/node_modules/@openclaw/fs-safe/docs/file-store.md

@@ -42,11 +42,6 @@ const cache = fileStore({
 
 Store and per-call `maxBytes` values must be non-negative safe integers or positive `Infinity`. Zero is an active zero-byte cap; `Infinity` disables the cap. An omitted or explicitly `undefined` per-call value preserves the store-level limit. The same rule applies to buffer writes, streams, copies, async reads, and synchronous reads/writes.
 
-Use `private: true` for credentials, auth profiles, tokens, and other private
-state. Private mode keeps the same `FileStore` shape but routes writes through
-the secret-file atomic path, refusing symlink parent components and re-asserting
-mode after rename.
-
 Returns a `FileStore`:
 
 ```ts
@@ -116,6 +111,34 @@ therefore does not imply that no filesystem access or serialization occurred.
 
 `root()` returns a [`Root`](root.md) handle for the same directory when you need the full surface (move, list, mkdir). It's a fresh handle per call and is safe to call frequently.
 
+## Private mode
+
+Use `fileStore({ private: true })` for credentials, auth profiles, tokens, and
+other private state. It keeps the same `FileStore` shape and mode defaults above.
+Async writes use the secret-file atomic path, refusing symlink parent components
+and re-asserting file mode after rename. Existing directories must already have
+the requested mode; async writes reject unsuitable permissions rather than
+repairing them. New-directory initialization requires guarded descriptor
+authority and can fail closed under restrictive platform/umask combinations;
+see the [secret-directory policy](secret-file.md#parameters).
+
+Private locked JSON mutations prepare directories before sidecar acquisition
+and bind the lock to the admitted parent identity. Lock normalization is
+read-only: a deleted or replaced parent is rejected, not recreated. The writer
+revalidates directory admission afterward. Reads never create directories and
+retain the shared [read semantics](#reads).
+
+For boot paths or sync-only integrations:
+
+```ts
+import { fileStoreSync } from "@openclaw/fs-safe/store";
+
+fileStoreSync({ rootDir: "/var/lib/app", private: true }).writeJson("config.json", config);
+```
+
+Sync directory modes remain repair-compatible on POSIX through verified
+descriptors, with the platform limitations described under [Writes](#writes).
+
 ## Writes
 
 Writes use guarded sibling-temp publication: apply file and directory modes,

package/node_modules/@openclaw/fs-safe/docs/index.md

@@ -48,37 +48,8 @@ await fs.remove("notes/archive/today.txt");
 
 ## What you get
 
-| Surface | Use it for |
-|---|---|
-| [`root()`](root.md) | One boundary for read/write/move/remove and bounded recursive walking inside a trusted directory. |
-| [`@openclaw/fs-safe/config`](config.md) | Process-global native helper and lock-option defaults. |
-| [`@openclaw/fs-safe/guest`](guest.md) | Python filesystem source for caller-owned guest transports, with admitted roots and descriptor-relative operations. |
-| [Native helper policy](native-helper.md) | Choose `auto`, `off`, or `require` for platform-native primitives. |
-| [Native architecture](native.md) | Understand the thin syscall layer, beneath model, platform mechanisms, and fallback boundary. |
-| [`replaceFileAtomic`](atomic.md) | Sibling-temp + rename, fsync hooks, mode preservation, copy fallback. |
-| [`@openclaw/fs-safe/durability`](durability.md) | Pinned directory identities, durable creation, exclusive publication, streaming SHA-256, provenance receipts, and sync-failure policy. |
-| [`writeExternalFileWithinRoot`](output.md) | Stage external-library file output in private temp storage, then finalize under a root. |
-| [`writeJson` / `readJson*`](json.md) | JSON state files with strict and lenient read variants. |
-| [`@openclaw/fs-safe/store`](store.md) | Overview of `fileStore`, `fileStoreSync`, and `jsonStore`. |
-| [`jsonStore`](json-store.md) | Single JSON state file with explicit fallback, atomic writes, and optional locking. |
-| [`fileStore`](file-store.md) | Managed multi-file/blob store with modes, stream writes, copy-in, pruning, and private mode. |
-| [Private file-store mode](private-file-store.md) | `fileStore({ private: true })` for private JSON/text state at 0600 under 0700 dirs. |
-| [`tempWorkspace`](temp.md) | 0700 scratch dir with auto-cleanup. |
-| [`readSecureFile`](secure-file.md) | Absolute file reads with fd pinning, permissions, owner, size, and timeout checks. |
-| [`watch`](watch.md) | Guarded filesystem observation with advisory native hints and polling. |
-| [`walkDirectory` / `Root.walk`](walk.md) | Standalone inventories plus root-bounded pruning, budgets, and partial-error reporting. |
-| [`Root.entries`](entries.md) | Guarded nonrecursive entries, bounded name collection, and caller-owned symlink validation. |
-| [`extractArchive`](archive.md) | Policy-driven ZIP/TAR extraction with clamp/filter, metadata/path-depth, link, count, and byte limits. |
-| [Secret files](secret-file.md) | Mode-0600 credentials with size and TOCTOU defense. |
-| [Permissions](permissions.md) | POSIX mode helpers plus Windows ACL inspection, raw owner/ACE facts, remediation, and private-directory creation. |
-| [`acquireFileLock`](sidecar-lock.md) | Cross-process file lock with retry and fail-closed stale-lock handling. |
-| [`FsSafeError`](errors.md) | Closed code union (with `policy` / `operational` category) you can branch on. |
-| [Public API inventory](public-api.md) | Complete runtime/type export cross-check against the generated declarations. |
-| [`pathScope()`](path-scope.md) | Lower-level absolute-path boundary helper; lives behind `@openclaw/fs-safe/advanced`. |
-| [`@openclaw/fs-safe/advanced`](advanced.md) | Directory of lower-level composition helpers (path scopes, regular-file I/O, install paths, sibling-temp writes, …). |
-| [`@openclaw/fs-safe/test-hooks`](test-hooks.md) | Test-only injection hooks for reproducing open/lstat races. |
-| [Migrating to 0.5](migrating-to-0.5.md) | End-to-end checklist for Python removal and 0.4 API behavior changes. |
-| [Migrating to 0.6](migrating-to-0.6.md) | Installer-policy checklist for the platform-native package split. |
+Browse the [subpath catalogue](install.md#subpath-exports) for entry points and
+the [public API inventory](public-api.md) for individual runtime and type exports.
 
 ## Status
 

package/node_modules/@openclaw/fs-safe/docs/install.md

@@ -98,6 +98,8 @@ Use the main entry for the common surface, or the focused subpaths when you want
 |---|---|
 | `@openclaw/fs-safe` | Common root, config, output, lock, native-mode, and error exports. |
 | `@openclaw/fs-safe/root` | `root()`, `Root`, `RootDefaults`, and root-walk types. |
+| `@openclaw/fs-safe/copy` | [Directory copying and cloning](copy.md), clone-source creation, filesystem probes, and clone metadata. |
+| `@openclaw/fs-safe/guest` | [Guest filesystem protocol](guest.md): Python source and exit constants for caller-owned transports. |
 | `@openclaw/fs-safe/config` | Process-global native helper and lock defaults. |
 | `@openclaw/fs-safe/path` | `isPathInside`, `safeRealpathSync`, `isWithinDir`, error helpers. |
 | `@openclaw/fs-safe/output` | Guarded staging/finalization for libraries that require an absolute output path. |
@@ -107,15 +109,17 @@ Use the main entry for the common surface, or the focused subpaths when you want
 | `@openclaw/fs-safe/atomic` | `replaceFileAtomic`, `writeTextAtomic`, `replaceDirectoryAtomic`, `movePathWithCopyFallback`. |
 | `@openclaw/fs-safe/durability` | Pinned directories, strict sync, durable directory creation, exclusive publication, and streaming SHA-256. |
 | `@openclaw/fs-safe/temp` | `tempWorkspace`, `withTempWorkspace`, sync variants, `resolveSecureTempRoot`. |
+| `@openclaw/fs-safe/secure-temp-root` | [Secure temp root](temp.md#secure-temp-root) resolution without workspace/store imports. |
 | `@openclaw/fs-safe/secure-file` | `readSecureFile` for pinned absolute file reads with permissions checks. |
 | `@openclaw/fs-safe/file-lock` | `acquireFileLock`, `withFileLock`, `createFileLockManager`, and related lock types. |
+| `@openclaw/fs-safe/watch` | [Guarded filesystem observation](watch.md) with advisory native hints and polling. |
 | `@openclaw/fs-safe/permissions` | POSIX mode helpers, Windows ACL inspection/remediation, raw owner/ACE facts, and private-directory creation. |
 | `@openclaw/fs-safe/walk` | `walkDirectory`, `walkDirectorySync`, related types. Budget-bounded, not root-bounded. |
 | `@openclaw/fs-safe/archive` | `extractArchive`, `readArchiveEntry`, kind resolution, policy types, limits, and preflight helpers. |
 | `@openclaw/fs-safe/advanced` | Lower-level composition helpers: path scopes, root-file open, install paths, local-root readers, temp-file targets, sibling-temp writes, regular-file helpers, `pathExists`, `withTimeout`, and related advanced types. This surface is less stable than the focused public subpaths. |
 | `@openclaw/fs-safe/errors` | `FsSafeError`, `FsSafeErrorCode`. |
 | `@openclaw/fs-safe/types` | Shared types: `DirEntry`, `PathStat`, `BasePathOptions`, … |
-| `@openclaw/fs-safe/test-hooks` | Test-only hooks for injecting races. Active under `NODE_ENV=test`. |
+| `@openclaw/fs-safe/test-hooks` | [Test-only hooks](testing.md#hooks-api) for injecting races; registration requires `NODE_ENV=test` or `VITEST=true`. |
 
 ## Runtime dependencies
 
@@ -191,36 +195,11 @@ the cause.
 
 ### Loading modes
 
-The platform native binaries provide fd-relative open/link/mkdir primitives,
-atomic no-replace rename, and file identity checks. The default is `auto`: use
-the matching binary when it loads, otherwise use the guarded JavaScript path
-where a safe fallback exists. Native-only operations fail with
-`helper-unavailable`.
-
-```ts
-import { configureFsSafeNative } from "@openclaw/fs-safe/config";
-
-configureFsSafeNative({ mode: "auto" });    // default
-configureFsSafeNative({ mode: "off" });     // disable the addon; reject native-only operations
-configureFsSafeNative({ mode: "require" }); // fail closed if unavailable
-```
-
-Environment variables are read at runtime:
-
-```bash
-FS_SAFE_NATIVE_MODE=off      # auto | off | require
-```
-
-`OPENCLAW_FS_SAFE_NATIVE_MODE` is also accepted.
-
-Disabling native loading keeps fallback-capable operations working through Node path
-operations guarded by lexical and canonical checks plus identity verification.
-Use `require` when native-backed operations must fail instead of falling back.
-Temp workspaces retain compatible JavaScript quarantine cleanup in `auto` and
-`off`. Set `cleanupSafety: "require-bounded"` to reject before child creation
-unless native no-replace quarantine and descriptor-bounded tree removal are
-available. See the [temp workspace contract](temp.md#private-temp-workspaces). The exact boundary
-for other operations is documented in [native helper policy](native-helper.md).
+Configure `auto` (default), `off`, or `require` before first use with
+`configureFsSafeNative()` or `FS_SAFE_NATIVE_MODE`. See
+[Native helper policy](native-helper.md#modes) for mode selection, loader lifetime,
+and strict failure behavior. Temp workspace `cleanupSafety` is a separate policy;
+see the [temp workspace contract](temp.md#private-temp-workspaces).
 
 ## Verify the install
 

package/node_modules/@openclaw/fs-safe/docs/json.md

@@ -221,5 +221,5 @@ const state = await readJsonIfExists<State>("./state.json");
 - [JSON store](json-store.md) — a single-file state wrapper with explicit per-call fallback (`readOr` / `updateOr`) and optional sidecar locking.
 - [Atomic writes](atomic.md) — lower-level sibling-temp replacement helpers.
 - [Secret files](secret-file.md) — JSON-or-text writes with mode 0600 in mode 0700 dirs.
-- [Private file-store mode](private-file-store.md) — root-bounded JSON+text state stores.
+- [Private file-store mode](file-store.md#private-mode) — root-bounded JSON+text state stores.
 - [File lock](sidecar-lock.md) — cross-process coordination.

package/node_modules/@openclaw/fs-safe/docs/local-roots.md

@@ -90,7 +90,6 @@ candidate, so replacing options while a read is pending cannot weaken admission.
 type ReadLocalFileFromRootsOptions = LocalRootsInputOptions & {
   hardlinks?: "reject" | "allow";
   maxBytes?: number;
-  nonBlockingRead?: boolean;
   symlinks?: "reject" | "follow-within-root" | "follow-parents-within-root";
 };
 

package/node_modules/@openclaw/fs-safe/docs/migrating-to-0.5.md

@@ -29,7 +29,9 @@ resolved outside the root. `root()` handles were not affected. See the
 
 ## 2. Replace Python helper configuration
 
-Change startup configuration before the first filesystem operation:
+The deprecated `configureFsSafePython()` / `FsSafePythonConfig` bridge and its
+six Python environment variables have been removed in current releases.
+Configure native mode before the first filesystem operation:
 
 ```ts
 import { configureFsSafeNative } from "@openclaw/fs-safe/config";
@@ -37,17 +39,15 @@ import { configureFsSafeNative } from "@openclaw/fs-safe/config";
 configureFsSafeNative({ mode: "auto" });
 ```
 
-| Remove from 0.4 | Use in 0.5 |
-|---|---|
-| `configureFsSafePython({ mode })` | `configureFsSafeNative({ mode })` |
-| `FS_SAFE_PYTHON_MODE` | `FS_SAFE_NATIVE_MODE` |
-| `OPENCLAW_FS_SAFE_PYTHON_MODE` | `OPENCLAW_FS_SAFE_NATIVE_MODE` |
-| `pythonPath`, `FS_SAFE_PYTHON`, pinned-Python aliases | Nothing; prebuilt native binaries do not use an interpreter |
-
-The old names warn once and map `auto`, `off`, or `require` so a shipped 0.4
-deployment does not silently change policy. Interpreter paths are ignored and
-Python is never spawned. Treat that warning as an upgrade diagnostic, not as a
-second supported helper path.
+Replace `FS_SAFE_PYTHON_MODE` with `FS_SAFE_NATIVE_MODE`, or
+`OPENCLAW_FS_SAFE_PYTHON_MODE` with `OPENCLAW_FS_SAFE_NATIVE_MODE`. Remove
+`pythonPath`, `FS_SAFE_PYTHON`, `OPENCLAW_FS_SAFE_PYTHON`,
+`OPENCLAW_PINNED_PYTHON`, and `OPENCLAW_PINNED_WRITE_PYTHON`; prebuilt native
+binaries need no interpreter. Python environment settings are now ignored
+silently: a deployment that set `FS_SAFE_PYTHON_MODE=require` or `off` runs in
+`auto` after upgrading unless it sets `FS_SAFE_NATIVE_MODE` (or calls
+`configureFsSafeNative`) first. Programmatic native configuration wins, followed by
+`FS_SAFE_NATIVE_MODE`, `OPENCLAW_FS_SAFE_NATIVE_MODE`, and the default `auto`.
 
 Choose the production mode deliberately: