@openclaw/signal 2026.9.6 → 2026.9.8

package/dist/.setup/transport-detection-BVUDE42e.mjs

@@ -0,0 +1,25 @@
+import { o as __exportAll } from "./doctor-contract-api-Db9V9gsY.mjs";
+import { a as normalizeSignalTransportUrl } from "./transport-url-CAC0JcuI.mjs";
+//#region extensions/signal/src/transport-detection.ts
+var transport_detection_exports = /* @__PURE__ */ __exportAll({ detectSignalTransport: () => detectSignalTransport });
+const DEFAULT_PROBE_TIMEOUT_MS = 1e4;
+async function detectSignalTransport(params) {
+	const url = normalizeSignalTransportUrl(params.url);
+	const timeoutMs = params.timeoutMs ?? DEFAULT_PROBE_TIMEOUT_MS;
+	const probes = params.probeNative && params.probeContainer ? void 0 : await import("./transport-probes.runtime-DwXEHnXr.mjs");
+	const probeNative = params.probeNative ?? probes?.nativeCheck;
+	const probeContainer = params.probeContainer ?? probes?.containerCheck;
+	if (!probeNative || !probeContainer) throw new Error("Signal transport probes are unavailable");
+	const [native, container] = await Promise.all([probeNative(url, timeoutMs).catch(() => ({ ok: false })), probeContainer(url, timeoutMs, params.account).catch(() => ({ ok: false }))]);
+	if (native.ok) return {
+		kind: "external-native",
+		url
+	};
+	if (container.ok) return {
+		kind: "container",
+		url
+	};
+	throw new Error(`Signal transport not reachable at ${url}`);
+}
+//#endregion
+export { transport_detection_exports as n, detectSignalTransport as t };

package/dist/.setup/{transport-policy-5VSnj5ma.mjs → transport-policy-B6C_LogW.mjs}

@@ -17,6 +17,24 @@ function isSignalLocalEndpointHost(hostname) {
 function isValidSignalManagedNativePort(value) {
 	return Number.isInteger(value) && Number(value) >= 1 && Number(value) <= 65535;
 }
+function reserveSignalTransportPorts(transport, reservedPorts) {
+	if (transport?.kind === "managed-native") {
+		if (transport.socketPath !== void 0) return false;
+		const httpPort = transport.httpPort;
+		if (httpPort !== void 0) reservedPorts.add(httpPort);
+		if (transport.url && !isSignalManagedNativeConnectionUrlForBind(transport)) {
+			const localConnectionPort = resolveLocalSignalTransportPort(transport.url);
+			if (localConnectionPort !== void 0) reservedPorts.add(localConnectionPort);
+		}
+		return httpPort === void 0;
+	}
+	if (transport?.kind === "external-native" || transport?.kind === "container") {
+		const localPort = resolveLocalSignalTransportPort(transport.url);
+		if (localPort !== void 0) reservedPorts.add(localPort);
+		return false;
+	}
+	return true;
+}
 function allocateSignalManagedNativePort(params) {
 	if (params.preferredPort !== void 0) {
 		if (!isValidSignalManagedNativePort(params.preferredPort)) throw new Error("Signal managed native port must be an integer between 1 and 65535.");
@@ -65,4 +83,4 @@ function assignSignalManagedNativePort(transport, httpPort) {
 	};
 }
 //#endregion
-export { isSignalManagedNativeConnectionUrlForBind as a, assignSignalManagedNativePort as i, DEFAULT_SIGNAL_MANAGED_NATIVE_PORT as n, isValidSignalManagedNativePort as o, allocateSignalManagedNativePort as r, resolveLocalSignalTransportPort as s, DEFAULT_SIGNAL_MANAGED_NATIVE_HOST as t };
+export { isSignalManagedNativeConnectionUrlForBind as a, resolveLocalSignalTransportPort as c, assignSignalManagedNativePort as i, DEFAULT_SIGNAL_MANAGED_NATIVE_PORT as n, isValidSignalManagedNativePort as o, allocateSignalManagedNativePort as r, reserveSignalTransportPorts as s, DEFAULT_SIGNAL_MANAGED_NATIVE_HOST as t };

package/dist/.setup/transport-probes.runtime-DwXEHnXr.mjs

@@ -0,0 +1,2 @@
+import { n as signalCheck, s as containerCheck } from "./client-AXcDteBZ.mjs";
+export { containerCheck, signalCheck as nativeCheck };

package/dist/api.js

@@ -1,12 +1,12 @@
-import { i as resolveSignalAccount, n as listSignalAccountIds, r as resolveDefaultSignalAccountId, t as listEnabledSignalAccounts } from "./.setup/accounts-BV6tDOTc.mjs";
+import { i as resolveSignalAccount, n as listSignalAccountIds, r as resolveDefaultSignalAccountId, t as listEnabledSignalAccounts } from "./.setup/accounts-DMtj2E-4.mjs";
 import { n as normalizeSignalMessagingTarget, t as looksLikeSignalTargetId } from "./.setup/normalize-l_b99hap.mjs";
-import { a as normalizeSignalAllowRecipient, c as resolveSignalSender, i as isSignalSenderAllowed, l as looksLikeUuid, n as formatSignalSenderDisplay, o as resolveSignalPeerId, r as formatSignalSenderId, s as resolveSignalRecipient, t as formatSignalPairingIdLine } from "./.setup/identity-YXPmgFMu.mjs";
-import { c as signalMessageActions, d as markdownToSignalText, f as markdownToSignalTextChunks, l as resolveSignalReactionLevel, t as detectSignalTransport } from "./.setup/transport-detection-CoiRl7Gx.mjs";
-import { n as sendReactionSignal, t as removeReactionSignal } from "./.setup/reaction-runtime-api-BnQGHcrB.mjs";
-import { a as normalizeSignalAccountInput, d as probeSignalTransport, f as writeSignalAccountTransport, p as resolveSignalOutboundTarget, t as signalPlugin, u as prepareSignalManagedNativeTransport } from "./.setup/channel-DhzTcFsK.mjs";
-import { t as signalSetupPlugin } from "./.setup/api-B9-B1L7Q.mjs";
-import { r as installSignalCli } from "./.setup/install-signal-cli-BDbzFcU2.mjs";
-import { t as monitorSignalProvider } from "./.setup/monitor-Dnz6Ygz5.mjs";
-import { n as sendReadReceiptSignal, r as sendTypingSignal, t as sendMessageSignal } from "./.setup/send-B78M_eFp.mjs";
-import { t as probeSignal } from "./.setup/probe-DXT2eLnw.mjs";
+import { a as normalizeSignalAllowRecipient, c as resolveSignalSender, i as isSignalSenderAllowed, l as looksLikeUuid, n as formatSignalSenderDisplay, o as resolveSignalPeerId, r as formatSignalSenderId, s as resolveSignalRecipient, t as formatSignalPairingIdLine } from "./.setup/identity-B3JyPqGO.mjs";
+import { _ as resolveSignalReactionLevel, a as normalizeSignalAccountInput, b as markdownToSignalTextChunks, d as probeSignalTransport, f as writeSignalAccountTransport, g as signalMessageActions, h as resolveSignalOutboundTarget, t as signalPlugin, u as prepareSignalManagedNativeTransport, y as markdownToSignalText } from "./.setup/channel-DrUxv5cf.mjs";
+import { n as sendReactionSignal, t as removeReactionSignal } from "./.setup/reaction-runtime-api-DDi5x2wC.mjs";
+import { t as detectSignalTransport } from "./.setup/transport-detection-BVUDE42e.mjs";
+import { t as signalSetupPlugin } from "./.setup/api-DEB0Obj8.mjs";
+import { r as installSignalCli } from "./.setup/install-signal-cli-ChvjzM6X.mjs";
+import { t as monitorSignalProvider } from "./.setup/monitor-BfwQr78f.mjs";
+import { n as sendReadReceiptSignal, r as sendTypingSignal, t as sendMessageSignal } from "./.setup/send-DEjrbpIC.mjs";
+import { t as probeSignal } from "./.setup/probe-BYLzra6D.mjs";
 export { detectSignalTransport, formatSignalPairingIdLine, formatSignalSenderDisplay, formatSignalSenderId, installSignalCli, isSignalSenderAllowed, listEnabledSignalAccounts, listSignalAccountIds, looksLikeSignalTargetId, looksLikeUuid, markdownToSignalText, markdownToSignalTextChunks, monitorSignalProvider, normalizeSignalAccountInput, normalizeSignalAllowRecipient, normalizeSignalMessagingTarget, prepareSignalManagedNativeTransport, probeSignal, probeSignalTransport, removeReactionSignal, resolveDefaultSignalAccountId, resolveSignalAccount, resolveSignalOutboundTarget, resolveSignalPeerId, resolveSignalReactionLevel, resolveSignalRecipient, resolveSignalSender, sendMessageSignal, sendReactionSignal, sendReadReceiptSignal, sendTypingSignal, signalMessageActions, signalPlugin, signalSetupPlugin, writeSignalAccountTransport };

package/dist/channel-config-api.js

@@ -1,2 +1,2 @@
-import { t as SignalChannelConfigSchema } from "./.setup/config-schema-aQwwMGUj.mjs";
+import { t as SignalChannelConfigSchema } from "./.setup/config-schema-DvxZ18SD.mjs";
 export { SignalChannelConfigSchema };

package/dist/channel-plugin-api.js

@@ -1,2 +1,2 @@
-import { t as signalPlugin } from "./.setup/channel-DhzTcFsK.mjs";
+import { t as signalPlugin } from "./.setup/channel-DrUxv5cf.mjs";
 export { signalPlugin };

package/dist/contract-api.js

@@ -1,4 +1,4 @@
 import { n as normalizeSignalMessagingTarget, r as normalizeSignalReactionRecipient, t as looksLikeSignalTargetId } from "./.setup/normalize-l_b99hap.mjs";
-import { i as isSignalSenderAllowed } from "./.setup/identity-YXPmgFMu.mjs";
-import { a as looksLikeArchive, i as installSignalCliFromRelease, n as extractSignalCliArchive, o as pickAsset, r as installSignalCli, t as downloadToFile } from "./.setup/install-signal-cli-BDbzFcU2.mjs";
+import { i as isSignalSenderAllowed } from "./.setup/identity-B3JyPqGO.mjs";
+import { a as looksLikeArchive, i as installSignalCliFromRelease, n as extractSignalCliArchive, o as pickAsset, r as installSignalCli, t as downloadToFile } from "./.setup/install-signal-cli-ChvjzM6X.mjs";
 export { downloadToFile, extractSignalCliArchive, installSignalCli, installSignalCliFromRelease, isSignalSenderAllowed, looksLikeArchive, looksLikeSignalTargetId, normalizeSignalMessagingTarget, normalizeSignalReactionRecipient, pickAsset };

package/dist/doctor-contract-api.js

@@ -1,2 +1,2 @@
-import { n as normalizeCompatibilityConfig, t as legacyConfigRules } from "./.setup/doctor-contract-api-Rbq_sRTI.mjs";
+import { n as normalizeCompatibilityConfig, t as legacyConfigRules } from "./.setup/doctor-contract-api-Db9V9gsY.mjs";
 export { legacyConfigRules, normalizeCompatibilityConfig };

package/dist/reaction-runtime-api.js

@@ -1,2 +1,2 @@
-import { n as sendReactionSignal, t as removeReactionSignal } from "./.setup/reaction-runtime-api-BnQGHcrB.mjs";
+import { n as sendReactionSignal, t as removeReactionSignal } from "./.setup/reaction-runtime-api-DDi5x2wC.mjs";
 export { removeReactionSignal, sendReactionSignal };

package/dist/runtime-api.js

@@ -1,19 +1,2 @@
-import { i as resolveSignalAccount, n as listSignalAccountIds, r as resolveDefaultSignalAccountId, t as listEnabledSignalAccounts } from "./.setup/accounts-BV6tDOTc.mjs";
-import { n as normalizeSignalMessagingTarget, t as looksLikeSignalTargetId } from "./.setup/normalize-l_b99hap.mjs";
-import { c as signalMessageActions, l as resolveSignalReactionLevel, o as setSignalRuntime } from "./.setup/transport-detection-CoiRl7Gx.mjs";
-import { n as sendReactionSignal, t as removeReactionSignal } from "./.setup/reaction-runtime-api-BnQGHcrB.mjs";
-import { n as SignalConfigSchema } from "./.setup/config-schema-aQwwMGUj.mjs";
-import { r as installSignalCli } from "./.setup/install-signal-cli-BDbzFcU2.mjs";
-import { t as monitorSignalProvider } from "./.setup/monitor-Dnz6Ygz5.mjs";
-import { t as sendMessageSignal } from "./.setup/send-B78M_eFp.mjs";
-import { t as probeSignal } from "./.setup/probe-DXT2eLnw.mjs";
-import { resolveChannelMediaMaxBytes } from "openclaw/plugin-sdk/account-helpers";
-import { PAIRING_APPROVED_MESSAGE } from "openclaw/plugin-sdk/channel-status";
-import { buildBaseAccountStatusSnapshot, buildBaseChannelStatusSummary, collectStatusIssuesFromLastError, createDefaultChannelRuntimeState } from "openclaw/plugin-sdk/status-helpers";
-import { normalizeE164 } from "openclaw/plugin-sdk/text-utility-runtime";
-import { DEFAULT_ACCOUNT_ID, applyAccountNameToChannelSection, deleteAccountFromConfigSection, emptyPluginConfigSchema, formatPairingApproveHint, getChatChannelMeta, migrateBaseNameToDefaultAccount, normalizeAccountId, setAccountEnabledInConfigSection } from "openclaw/plugin-sdk/core";
-import { detectBinary, formatCliCommand, formatDocsLink } from "openclaw/plugin-sdk/setup-tools";
-import { buildChannelConfigSchema } from "openclaw/plugin-sdk/channel-config-schema";
-import { chunkText } from "openclaw/plugin-sdk/reply-runtime";
-import { resolveAllowlistProviderRuntimeGroupPolicy, resolveDefaultGroupPolicy } from "openclaw/plugin-sdk/runtime-group-policy";
-export { DEFAULT_ACCOUNT_ID, PAIRING_APPROVED_MESSAGE, SignalConfigSchema, applyAccountNameToChannelSection, buildBaseAccountStatusSnapshot, buildBaseChannelStatusSummary, buildChannelConfigSchema, chunkText, collectStatusIssuesFromLastError, createDefaultChannelRuntimeState, deleteAccountFromConfigSection, detectBinary, emptyPluginConfigSchema, formatCliCommand, formatDocsLink, formatPairingApproveHint, getChatChannelMeta, installSignalCli, listEnabledSignalAccounts, listSignalAccountIds, looksLikeSignalTargetId, migrateBaseNameToDefaultAccount, monitorSignalProvider, normalizeAccountId, normalizeE164, normalizeSignalMessagingTarget, probeSignal, removeReactionSignal, resolveAllowlistProviderRuntimeGroupPolicy, resolveChannelMediaMaxBytes, resolveDefaultGroupPolicy, resolveDefaultSignalAccountId, resolveSignalAccount, resolveSignalReactionLevel, sendMessageSignal, sendReactionSignal, setAccountEnabledInConfigSection, setSignalRuntime, signalMessageActions };
+import { r as setSignalRuntime } from "./.setup/runtime-8sxUF217.mjs";
+export { setSignalRuntime };

package/dist/setup-entry.js

@@ -4,7 +4,7 @@ import { fileURLToPath } from "node:url";
 var setup_entry_default = defineBundledChannelSetupEntry({
 	importMetaUrl: import.meta.url,
 	plugin: {
-		specifier: fileURLToPath(new URL(".setup/api-CGh4eWR8.mjs", import.meta.url).href),
+		specifier: fileURLToPath(new URL(".setup/api-DmCb6e7E.mjs", import.meta.url).href),
 		exportName: "signalSetupPlugin"
 	}
 });

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

@@ -2,6 +2,108 @@
 
 ## Unreleased
 
+## 0.21.1 - 2026-09-27
+
+### Fixes
+
+- **Linux without `openat2`:** native opens now follow in-root relative symlinks exactly as `RESOLVE_BENEATH` does, rejecting absolute links, `..` escapes, procfs and `nosymfollow` links, and chains longer than 40. Denial and symlink policies report the same errors as the `openat2` path. Links inside sticky world-writable directories are refused. ([#717](https://github.com/openclaw/fs-safe/pull/717))
+- **Deny policies on case-insensitive filesystems:** `denyMutations` now denies creating a not-yet-existing case or Unicode-normalization alias of a denied path (for example `case.txt` when `Case.txt` is denied on APFS, NTFS or casefold ext4). Where a filesystem's sensitivity cannot be proven, Unicode-equivalent names are denied conservatively. ([#720](https://github.com/openclaw/fs-safe/pull/720))
+- **Directory listings:** `list()`, `entries()` and `walk()` reject names that are not valid UTF-8 with `invalid-path` instead of decoding them lossily, which could collide with a real `U+FFFD` name and report another entry's metadata. ([#715](https://github.com/openclaw/fs-safe/pull/715))
+- **ZIP admission:** entries that differ only by case or Unicode normalization are rejected during preflight and member reads, matching extraction's collision policy. ([#716](https://github.com/openclaw/fs-safe/pull/716))
+- **Atomic restore:** when a metadata call fails with `EIO` after the destination was truncated, restore-original writes the original bytes back through the retained, identity-verified descriptor instead of leaving the file empty. ([#718](https://github.com/openclaw/fs-safe/pull/718))
+- **Lock and prune cleanup:** cleanup decisions compare exact bigint file identities. Legacy numeric receipts with IDs above 2^53 are refused instead of risking removal of the wrong file. ([#719](https://github.com/openclaw/fs-safe/pull/719))
+- **Watch overflow:** subscriptions no longer publish spurious whole-scope overflow invalidations for excluded or unselected paths or for slow reconcile passes. macOS streams use OS-level exclusion paths and anchor-scoped streams, and Windows uses a 1 MiB change buffer on local volumes. Genuine OS event drops still invalidate. ([#724](https://github.com/openclaw/fs-safe/pull/724))
+- **Mutation authority:** reject synchronous and asynchronous generator callback results before mutation, so lazy authority checks cannot be skipped. ([#711](https://github.com/openclaw/fs-safe/pull/711))
+- **Synchronous atomic writes:** reject deferred `beforeRename` hooks before publication and clean up the owned stage. ([#728](https://github.com/openclaw/fs-safe/pull/728))
+- **Copy publication callbacks:** reject deferred generator observers in `Root.copyIn()` while preserving the completed destination and source bytes. ([#726](https://github.com/openclaw/fs-safe/pull/726))
+- **Native move diagnostics:** no-clobber `Root.move()` keeps the original native loader error as its cause, including missing libraries or incompatible glibc versions. ([#709](https://github.com/openclaw/fs-safe/pull/709))
+
+### Features
+
+- **Watch polling interval:** `pollIntervalMs` sets the scan interval whenever polling is the selected transport, including `mode: "auto"` falling back to polling, without changing the events reconcile interval. ([#723](https://github.com/openclaw/fs-safe/pull/723))
+
+### Performance
+
+- **Linux directory cloning:** reuse the admitted filesystem type when creating clone sources and cloning trees, avoiding a duplicate filesystem probe and allocation per operation. ([#732](https://github.com/openclaw/fs-safe/pull/732))
+
+## 0.21.0 - 2026-09-26
+
+### Highlights
+
+- **Guarded filesystem observation:** `@openclaw/fs-safe/watch` observes literal entry and tree scopes beneath an admitted Root and delivers bounded advisory invalidations; guarded scans stay authoritative. One shared Rust event thread per process uses inotify, FSEvents and ReadDirectoryChangesW on Linux, macOS and Windows, sleeps while idle, and falls back to portable polling under `mode: "auto"`. Subscriptions become ready after one baseline scan, stay available under sustained writes, fence stale generations on `setScopes()`, join native work on `close()`, and support `persistent: false` so one-shot Node commands can exit. Thanks @vincentkoc. ([#690](https://github.com/openclaw/fs-safe/pull/690), [#695](https://github.com/openclaw/fs-safe/pull/695), [#697](https://github.com/openclaw/fs-safe/pull/697), [#703](https://github.com/openclaw/fs-safe/pull/703), [#707](https://github.com/openclaw/fs-safe/pull/707))
+- **Linux user namespaces:** private temp workspaces now work beneath unmapped ancestors, including systemd user services with `PrivateUsers=true`, while UID/GID mappings and ancestor permissions are still rechecked. ([#693](https://github.com/openclaw/fs-safe/pull/693))
+
+### Features
+
+- **Revocable atomic writes:** atomic replacement can recheck caller authority before new effects and report retained destination identities for partial writes and publication, without treating receipts as permission to roll back. ([#694](https://github.com/openclaw/fs-safe/pull/694))
+- **Root walking:** `symlinkPolicy: "include"` reports links without following their targets, preserving sorted traversal, entry budgets, and the existing skip/follow result types. Directory-to-symlink substitutions fail before descent. ([#692](https://github.com/openclaw/fs-safe/pull/692))
+- **Windows file retirement:** the advanced surface can retire existing NTFS files through a retained handle, with exact producer identity, current authority, and separate disposition and settlement facts. There is no persistence guarantee. ([#706](https://github.com/openclaw/fs-safe/pull/706))
+
+### Performance
+
+- **Temporary filename sanitization:** skip duplicate normalization after reserved-device suffixing while preserving filename admission and fallback rules. ([#689](https://github.com/openclaw/fs-safe/pull/689))
+
+### Compatibility
+
+- Supplied temp workspace roots must be owned by the effective user and must not be group- or world-writable; use a private per-user root instead of shared `/tmp`. A one-time warning reports host ownership that cannot be verified. ([#693](https://github.com/openclaw/fs-safe/pull/693))
+- On Windows, an events-mode watch holds one handle on each watched Root, so the Root's own ancestor directories cannot be renamed while it is open; renaming inside the Root is unaffected. Use `mode: "poll"` where that matters. ([#697](https://github.com/openclaw/fs-safe/pull/697))
+- `watch()` requires an explicit `mode` (`"auto"`, `"events"` or `"poll"`); `"events"` fails readiness with `helper-unavailable` when no native backend is available, and Bun currently selects polling under `"auto"`. ([#690](https://github.com/openclaw/fs-safe/pull/690))
+
+## 0.20.0 - 2026-09-25
+
+### Highlights
+
+- **Older Linux systems:** when `openat2` is absent (Linux before 5.6) or blocked by seccomp, native operations fall back to a guarded no-follow walk instead of failing with `ENOSYS`. Nested no-clobber moves keep working, and GNU x64/arm64 bindings now target glibc 2.28, so native operations load on RHEL 8-family systems. ([#686](https://github.com/openclaw/fs-safe/pull/686), [#685](https://github.com/openclaw/fs-safe/pull/685); fixes [#572](https://github.com/openclaw/fs-safe/issues/572), [#511](https://github.com/openclaw/fs-safe/issues/511), [#548](https://github.com/openclaw/fs-safe/issues/548))
+- **Path hardening:** trash moves stay inside allowed roots, symlink-parent checks inspect raw segments before dotdot normalization, relative-escape checks recognize either Windows separator and nested escapes, and safe path segments reject Windows reserved device names. Thanks @SebTardif. ([#611](https://github.com/openclaw/fs-safe/pull/611), [#615](https://github.com/openclaw/fs-safe/pull/615), [#614](https://github.com/openclaw/fs-safe/pull/614), [#612](https://github.com/openclaw/fs-safe/pull/612))
+- **ZIP admission per operation:** portable ZIP reads and extraction bind entry selection to the admitted archive, name, and decoder object, and verify payloads against the admitted CRC and size. Substituted, renamed, or replaced decoder entries are rejected. ([#660](https://github.com/openclaw/fs-safe/pull/660))
+
+### Features
+
+- **Retained symlink publication:** `retainSymlinkInDirectory()` on the advanced surface holds an explicitly identified POSIX symlink through exact-slot no-replace publication and explicit recovery, preserving observed foreign replacements and uncertain outcomes. ([#682](https://github.com/openclaw/fs-safe/pull/682))
+- **Batched Windows ACL facts:** `readOwnerAndDaclBatch()` inspects ordered paths in one isolated native worker or one PowerShell process, with a configurable whole-batch timeout and bounded output. Results are bounded during collection; oversized batches reject with `too-large` before later paths are queried. ([#669](https://github.com/openclaw/fs-safe/pull/669), [#680](https://github.com/openclaw/fs-safe/pull/680))
+- **Atomic text options:** `writeTextAtomic()` forwards the existing `beforeRename` hook and `tempPrefix` option to atomic replacement, keeping its validation and identity checks. ([#580](https://github.com/openclaw/fs-safe/pull/580))
+
+### Fixes
+
+- **Lock exit cleanup:** leave raw sidecars in place when Windows reports an unknown device or inode, while keeping token-owned cleanup working when the descriptor and path identities legitimately differ (for example on VirtioFS). Thanks @SebTardif. ([#617](https://github.com/openclaw/fs-safe/pull/617))
+- **Retained symlink errors:** preserve uncertain publication outcomes and cached cleanup/recovery failures when inspecting thrown error metadata fails, retaining the original cause without retrying mutations, callbacks, or descriptor closes. ([#684](https://github.com/openclaw/fs-safe/pull/684))
+- **Create collision cleanup:** atomic and streamed creates remove their private stage when the JavaScript fallback observes a competing destination before publication; failures after a link attempt retain their existing recovery evidence. ([#683](https://github.com/openclaw/fs-safe/pull/683))
+
+### Compatibility
+
+- Safe path segments now reject Windows reserved device names (`CON`, `NUL`, `COM1`, `CON.json`, …) on every platform, because segments are portable identifiers. Temporary filename sanitization still suffixes them (`CON.txt` becomes `CON_.txt`). ([#612](https://github.com/openclaw/fs-safe/pull/612))
+- `assertNoSymlinkParents()` and guarded appends with `rejectSymlinkParents` reject raw spellings whose dotdot segments would cancel a symlink or re-enter the root after leaving it. ([#615](https://github.com/openclaw/fs-safe/pull/615))
+- Without `openat2`, beneath opens report `best-effort` containment instead of `kernel-atomic`, anonymous `O_TMPFILE` opens report `ENOTSUP`, and bounded tree cleanup fails closed with `helper-unavailable` because it requires `RESOLVE_NO_XDEV`. ([#686](https://github.com/openclaw/fs-safe/pull/686))
+- The Linux GNU binding floor is glibc 2.28 for both x64 and arm64 (arm64 was previously built against 2.17), matching Node 22's own Linux baseline. ([#685](https://github.com/openclaw/fs-safe/pull/685))
+
+## 0.19.0 - 2026-09-24
+
+### Highlights
+
+- **Strict secret-file durability:** `createSecretFileAtomic()` accepts `durable: "file"` to require every file flush to succeed, including on `EPERM`; parent-directory synchronization remains best effort. ([#644](https://github.com/openclaw/fs-safe/pull/644))
+- **Literal `~` names:** keep FileStore keys, absolute Root reads, discovered walk entries, and ZIP/TAR entries literal instead of treating them as home-directory shorthand. Reads, writes, removal, pruning, extraction, and durable publication select the intended entry. ([#633](https://github.com/openclaw/fs-safe/pull/633))
+- **Native Unix descriptor safety:** reject negative descriptors in low-level root, query, hash, copy, clone, staging, and cleanup calls without Rust panics or working-directory operations. Modern macOS beneath opens report `EBADF` for negative roots instead of `EIO`. ([#640](https://github.com/openclaw/fs-safe/pull/640), [#643](https://github.com/openclaw/fs-safe/pull/643), [#646](https://github.com/openclaw/fs-safe/pull/646))
+
+### Fixes
+
+- **Guest directory permissions:** cross-device moves preserve mode `000`, including nested directories, without changing other modes' umask behavior. Restore top-level permissions through the retained directory descriptor and preserve published entries on failure. Thanks @SebTardif. ([#616](https://github.com/openclaw/fs-safe/pull/616))
+- **ReFS clone cleanup:** remove ordinary partial output when Windows rejects the ignore-readonly deletion flag. Keep readonly attributes intact and include cleanup failures in the original clone error; readonly files or other processes' open handles can still leave output behind. ([#648](https://github.com/openclaw/fs-safe/pull/648))
+
+### Compatibility and documentation
+
+- Secret creation's default and boolean durability options retain their behavior, and `writeSecretFileAtomic()` remains boolean-only. Strict file synchronization preserves existing publication and cleanup semantics: a failure after publication can leave a complete file present. ([#644](https://github.com/openclaw/fs-safe/pull/644))
+- `Root.walk("~")` and `Root.walk("~/dir")` expand home shorthand when iteration starts and return admitted canonical paths relative to the Root. Use `./~/dir` for a literal tilde directory, and prefix returned entry paths with `./` when passing them to another Root method. Relative Root `~/name` inputs still expand home; FileStore keys do not. ([#633](https://github.com/openclaw/fs-safe/pull/633))
+- Guest moves still require OS permission to read mode-000 source directories; they do not widen source permissions. If permission restoration fails after publication, the source and published copy remain for caller reconciliation. ([#616](https://github.com/openclaw/fs-safe/pull/616))
+- Clarify that `Root.append()` and `openWritable()` creation modes remain subject to the process umask and do not chmod existing files. This documents existing behavior. ([#636](https://github.com/openclaw/fs-safe/pull/636))
+
+## 0.18.2 - 2026-09-22
+
+### Fixes
+
+- **Lock errors:** preserve Root stale-removal rejections and `null` or `undefined` retry failures instead of masking them with timeouts or `TypeError`s. ([#624](https://github.com/openclaw/fs-safe/pull/624))
+- **Secret-file reads:** report caught `null` or `undefined` inspection and read failures as structured errors instead of internal `TypeError`s. ([#623](https://github.com/openclaw/fs-safe/pull/623))
+- **Secret-file creation:** preserve `null` or `undefined` thrown by parameter getters instead of masking them with an internal `TypeError`. ([#625](https://github.com/openclaw/fs-safe/pull/625))
+
 ## 0.18.1 - 2026-09-22
 
 ### Fixes

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

@@ -10,7 +10,7 @@
 
 Capability-style filesystem roots for Node.js apps that handle untrusted relative paths.
 
-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 native opens are kernel-atomic; macOS, Windows, and JavaScript paths are best-effort.
+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
 import { root } from "@openclaw/fs-safe";
@@ -45,7 +45,7 @@ The same idea has landed in other languages. Go [added `os.Root` and `OpenInRoot
 | `path.resolve().startsWith()` | string check only | – | – | – | – |
 | [`write-file-atomic`](https://www.npmjs.com/package/write-file-atomic) | – | ✓ | – | – | – |
 | Go [`os.Root`](https://go.dev/blog/osroot) / Rust [`cap-std`](https://github.com/bytecodealliance/cap-std) | ✓ | platform | ✓ | ✓ | – |
-| **`@openclaw/fs-safe`** | **✓** | **✓** | **✓** | **Linux atomic; others best-effort** | **✓ (ZIP/TAR/gzip/zstd/bzip2)** |
+| **`@openclaw/fs-safe`** | **✓** | **✓** | **✓** | **Linux openat2 atomic; others best-effort** | **✓ (ZIP/TAR/gzip/zstd/bzip2)** |
 
 ## Not a sandbox
 
@@ -84,7 +84,9 @@ reports the escape. Use `require` when hostile concurrent mutation is in scope.
 
 Equivalent env var: `FS_SAFE_NATIVE_MODE=auto|off|require`. The seven bindings
 ship as exact-version optional packages filtered by OS, CPU, and Linux libc, so
-a normal install receives only its matching binary. There are no postinstall
+a normal install receives only its matching binary. Linux GNU x64/arm64 bindings
+support [glibc 2.28 or newer](docs/install.md#supported-native-platforms), including
+RHEL 8-family systems. There are no postinstall
 steps, runtime downloads, or consumer Rust builds. On a platform without a
 published binding, or when optional dependencies are omitted, `auto` silently retains lexical and canonical root
 checks, no-follow opens, guarded temp+rename writes, and post-write identity
@@ -94,8 +96,11 @@ tradeoff, and [native architecture](docs/native.md) for the platform mechanisms
 and policy ownership model.
 
 Open results report the mechanism's containment class as `"kernel-atomic"` or
-`"best-effort"`. Linux native `openBeneath()` is kernel-atomic; macOS, Windows,
-and guarded JavaScript results are best-effort. See the [security model](docs/security-model.md#containment-guarantees-by-platform) before using that fact in higher-level policy.
+`"best-effort"`. Linux native `openBeneath()` is kernel-atomic when `openat2`
+is available. Older kernels and syscall-filtered containers use a guarded
+descriptor-relative walk reporting best-effort; nested no-clobber moves keep
+atomic `renameat2(RENAME_NOREPLACE)`. macOS, Windows, and guarded JavaScript
+results are best-effort. See [Linux compatibility](docs/native.md#linux-without-openat2). See the [security model](docs/security-model.md#containment-guarantees-by-platform) before using that fact in higher-level policy.
 
 ## Migrating from the Python helper
 
@@ -274,6 +279,7 @@ contract. Low-level helpers that OpenClaw needs to compose higher-level APIs are
 | `@openclaw/fs-safe/secure-file` | fd-pinned absolute file reads with owner, mode, ACL, trusted-dir, size, and timeout checks |
 | `@openclaw/fs-safe/file-lock` | async/sync sidecar locks, root-bounded sidecars, ownership verification, and stale policy |
 | `@openclaw/fs-safe/permissions` | POSIX mode and Windows ACL inspection, raw owner/ACE facts, private-directory creation, and remediation helpers |
+| [`@openclaw/fs-safe/watch`](docs/watch.md) | Guarded observation with native event hints, bounded scans, and joined close |
 | `@openclaw/fs-safe/walk` | budget-bounded directory walking with symlink policy, filters, and truncation accounting; not root-bounded |
 | `@openclaw/fs-safe/copy` | directory copying with `clone: "auto"`, `"always"`, or `"never"`; native APFS, Btrfs, ReFS, XFS, and ZFS cloning, portable byte copying, and clone metadata; see [directory copying](docs/copy.md) |
 | `@openclaw/fs-safe/archive` | policy-driven ZIP/TAR extraction, clamp/filter policy, metadata/path-depth limits, gzip/zstd/bzip2 support, and bounded entry reads |
@@ -342,6 +348,11 @@ original directory on Linux/macOS and requires native support for this operation
 It offers atomic replace/no-replace publication, not expected-inode replacement
 or a crash-durability promise; application checks and coordination remain yours.
 
+For an already staged POSIX symlink, [`retainSymlinkInDirectory()`](docs/staged-symlink.md)
+admits caller-captured identity and retains that exact inode through no-replace
+publication or explicit recovery. Same-target foreign replacements are not adopted.
+Staging, cooperative locking and crash recovery remain application responsibilities.
+
 `replaceFileAtomic()` writes a sibling temp file, applies its exact mode through the still-open descriptor, optionally fsyncs it, and renames it over the destination. It never follows the published destination path to set file permissions. Mode preservation inherits only rwx bits from an existing non-symlink regular file; special bits, ownership, ACLs, and extended attributes are not copied. Pinned-destination hardlink rejection, rename retry / copy fallback on `EPERM`, bounded original-content restoration after a torn fallback, parent-directory fsync, and a `beforeRename` hook for backup or observer flows are all opt-in. `movePathWithCopyFallback()` stages cross-device moves before commit and removes only the copied source entries, so concurrent source additions or replacements are preserved. Its optional synchronous `assertBeforeMutation` hook rechecks caller authority before renames and each source removal; `onDestinationPublished` reports an exact bigint destination identity before later checks or cleanup can fail. See [mutation authority and publication receipts](docs/atomic.md#mutation-authority-and-publication-receipts).
 
 ```ts
@@ -358,6 +369,12 @@ await replaceFileAtomic({
 
 `replaceFileAtomicSync()` covers the synchronous case with the same options shape. Both accept an injectable `fileSystem` for tests. Async adapters use `chmod()` on the `FileHandle` returned by their required `open()` operation; custom sync adapters using `mode` or `preserveExistingMode` provide the optional descriptor-bound `fchmodSync` operation.
 
+Both variants accept `assertBeforeMutation` for revocable caller authority and
+`onDestinationState` for observed removal, partial-write, and publication facts.
+The observer receives exact bigint identities from retained descriptors, including
+when later completion fails. These facts do not authorize rollback; the caller
+still owns current authority and content checks. See [atomic write authority](docs/atomic.md#atomic-write-authority-and-destination-state).
+
 ## External outputs
 
 Use `writeExternalFileWithinRoot()` when a browser download, renderer, media
@@ -549,7 +566,8 @@ Check `scan.truncated` before treating the result as complete, and `scan.failedD
 `walkDirectory()` accepts asynchronous `include` and `descend` callbacks through `AsyncWalkDirectoryOptions`, so a marker lookup can prune a directory before its children are read. Decisions remain serial and retain the options object as their `this` receiver; `walkDirectorySync()` and its options remain synchronous. See [Directory walking](docs/walk.md) for callback timing, JavaScript result compatibility, and error handling.
 
 For caller-controlled paths, `Root.walk()` is the root-bounded async iterator.
-It supports entry/depth budgets, in-root symlink following, cancellation, and a
+It supports entry/depth budgets, including links without following their targets,
+in-root symlink following, cancellation, and a
 truncation marker (or typed error) when a budget is reached. Its `entryFilter`
 accepts `"include"`, `"skip"`, or `"skip-subtree"`, directly or through a Promise.
 After an awaited decision resolves, the walk rechecks cancellation and the

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

@@ -8,6 +8,8 @@ export { resolvePathPrefixSync, type ResolvedPathPrefix } from "./path-prefix.js
 export { probePathSuffixAliasesSync, type ProbePathSuffixAliasesOptions } from "./path-suffix-aliases.js";
 export { readDirectoryIdentity, assertDirectoryIdentitySync, type DirectoryIdentity, } from "./directory-guard.js";
 export { stageFileInDirectory, } from "./native-staged-file.js";
+export { retainSymlinkInDirectory } from "./native-staged-symlink.js";
+export type { StagedSymlink, StagedSymlinkExpected, StagedSymlinkReceipt, PublishedSymlinkReceipt, StagedSymlinkPublication, StagedSymlinkRemoval, StagedSymlinkCleanupReceipt, StagedSymlinkFailureDetails, } from "./staged-symlink-types.js";
 export type { StagedFile, StagedFileReceipt, PublishedFileReceipt, StagedFilePublication, StagedFileCleanupReceipt, StagedFileFailureDetails, } from "./staged-file-types.js";
 export { readFileDescriptorBounded, readFileDescriptorBoundedSync, readFileHandleBounded, } from "./bounded-read.js";
 export { readFileWindowFully, readFileWindowFullySync, type ReadFileWindowOptions, } from "./positional-read.js";
@@ -33,4 +35,7 @@ export { resolveHomeRelativePath } from "./home-dir.js";
 export { appendRegularFile, appendRegularFileSync, readRegularFile, readRegularFileSync, resolveRegularFileAppendFlags, statRegularFile, statRegularFileSync, type AppendRegularFileOptions, type RegularFileStatResult, } from "./regular-file.js";
 export { buildRandomTempFilePath, sanitizeTempFileName, type TempFile, tempFile, withTempFile, } from "./temp-target.js";
 export { writeSiblingTempFile, writeViaSiblingTempPath, type WriteSiblingTempFileOptions, type WriteSiblingTempFileResult, } from "./sibling-temp.js";
-export { createIcaclsResetCommand, formatIcaclsResetCommand, formatWindowsAclSummary, inspectWindowsAcl, parseIcaclsOutput, resolveWindowsUserPrincipal, summarizeWindowsAcl, type IcaclsResetCommandOptions, type PermissionCommandFailure, type PermissionExec, type WindowsAclEntry, type WindowsAclSummary, } from "./permissions.js";
+export { createIcaclsResetCommand, formatIcaclsResetCommand, formatWindowsAclSummary, inspectWindowsAcl, parseIcaclsOutput, resolveWindowsUserPrincipal, summarizeWindowsAcl, type IcaclsResetCommandOptions, type PermissionExec, type WindowsAclEntry, type WindowsAclSummary, } from "./permissions-windows.js";
+export type { PermissionCommandFailure } from "./permission-exec.js";
+export { retainFileInDirectory } from "./retained-file.js";
+export type { RetainedFile, RetainedFileAdmission, RetainedFileExpected, RetainedFileIssue, RetainedFileReceipt, RetainedFileResult, RetainFileInDirectoryOptions, } from "./retained-file-types.js";

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

@@ -11,6 +11,7 @@ export { resolvePathPrefixSync } from "./path-prefix.js";
 export { probePathSuffixAliasesSync } from "./path-suffix-aliases.js";
 export { readDirectoryIdentity, assertDirectoryIdentitySync, } from "./directory-guard.js";
 export { stageFileInDirectory, } from "./native-staged-file.js";
+export { retainSymlinkInDirectory } from "./native-staged-symlink.js";
 export { readFileDescriptorBounded, readFileDescriptorBoundedSync, readFileHandleBounded, } from "./bounded-read.js";
 export { readFileWindowFully, readFileWindowFullySync, } from "./positional-read.js";
 export { writeFileWindowFully } from "./write-file-handle.js";
@@ -35,4 +36,5 @@ export { resolveHomeRelativePath } from "./home-dir.js";
 export { appendRegularFile, appendRegularFileSync, readRegularFile, readRegularFileSync, resolveRegularFileAppendFlags, statRegularFile, statRegularFileSync, } from "./regular-file.js";
 export { buildRandomTempFilePath, sanitizeTempFileName, tempFile, withTempFile, } from "./temp-target.js";
 export { writeSiblingTempFile, writeViaSiblingTempPath, } from "./sibling-temp.js";
-export { createIcaclsResetCommand, formatIcaclsResetCommand, formatWindowsAclSummary, inspectWindowsAcl, parseIcaclsOutput, resolveWindowsUserPrincipal, summarizeWindowsAcl, } from "./permissions.js";
+export { createIcaclsResetCommand, formatIcaclsResetCommand, formatWindowsAclSummary, inspectWindowsAcl, parseIcaclsOutput, resolveWindowsUserPrincipal, summarizeWindowsAcl, } from "./permissions-windows.js";
+export { retainFileInDirectory } from "./retained-file.js";

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

@@ -78,7 +78,7 @@ export async function finalizeArchivePublication(params) {
                     const env_1 = { stack: [], error: void 0, hasError: false };
                     try {
                         await assertGuards(file.guards);
-                        const opened = __addDisposableResource(env_1, await params.targetRoot.open(file.relativePath, { hardlinks: "reject", symlinks: "reject" })
+                        const opened = __addDisposableResource(env_1, await params.targetRoot.open(`./${file.relativePath}`, { hardlinks: "reject", symlinks: "reject" })
                             .catch((error) => {
                             if (error instanceof FsSafeError && (error.code === "hardlink" || error.code === "path-alias")) {
                                 throw createArchiveSymlinkTraversalError(file.relativePath);

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

@@ -3,7 +3,6 @@ import fs from "node:fs/promises";
 import path from "node:path";
 import { ownExtractionDestinationMutation } from "./archive-deadline.js";
 import { assertDirectoryIdentityGuard, assertResolvedInsideDestination, createDirectoryIdentityGuard, createArchiveSymlinkTraversalError, preparePrivateArchiveOutputPath, withStagedArchiveDestination, } from "./archive-staging.js";
-import {} from "./directory-mode-owner.js";
 import { pinNodeDirectoryForMode } from "./directory-mode-node.js";
 import { assertSyncDirectoryGuard, inspectDirectoryIdentitySync } from "./directory-guard.js";
 import { FsSafeError } from "./errors.js";
@@ -251,7 +250,7 @@ async function mergeTree(params, publication, durable = true, entryUmask = 0) {
                                 }
                             };
                         }
-                        await targetRoot.copyIn(relPath, sourcePath, options);
+                        await targetRoot.copyIn(`./${relPath}`, sourcePath, options);
                         check();
                         await assertGuards();
                         await assertResolvedInsideDestination({

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

@@ -54,14 +54,9 @@ export type TarEntryInfo = {
     mode?: number;
 };
 export declare function createTarEntryPlanner(params: ArchivePlanOptions): (entry: TarEntryInfo) => ArchivePlanEntry | null;
-export declare function createTarEntryPreflightChecker(params: {
+export declare function createTarEntryPreflightChecker(params: Omit<ArchivePlanOptions & {
     rootDir: string;
-    stripComponents?: number;
-    limits?: ArchiveExtractLimits;
-    escapeLabel?: string;
-    entryFilter?: ArchiveEntryFilter;
-    onFiltered?: ArchiveFilteredEntryPolicy;
-}): (entry: TarEntryInfo) => boolean;
+}, "entryModes">): (entry: TarEntryInfo) => boolean;
 export type ArchiveLogger = {
     info?: (message: string) => void;
     warn?: (message: string) => void;

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

@@ -11,9 +11,8 @@ import { resolveArchiveKind } from "./archive-kind.js";
 import { DEFAULT_MAX_ARCHIVE_BYTES_ZIP, ArchiveLimitError, ARCHIVE_LIMIT_ERROR_CODE, } from "./archive-limits.js";
 import { isGzipBuffer } from "./archive-gzip-tail.js";
 import { inspectTar, replayTar } from "./archive-tar-stream.js";
-import { loadAdmittedZipArchive } from "./archive-zip-loader.js";
+import { loadAdmittedZipArchive, assertZipEntryBinding } from "./archive-zip-loader.js";
 import { createZipIntegrityTransform, normalizeZipIntegrityError, } from "./archive-zip-integrity.js";
-import { isZipSymlinkEntry, zipEntryKind } from "./archive-zip-entry.js";
 import { FsSafeError } from "./errors.js";
 import { inspectFileIdentity } from "./strict-file-identity.js";
 import { resolveReadOpenFlags } from "./read-open-flags.js";
@@ -93,27 +92,19 @@ async function readArchiveInput(archivePath) {
     }
 }
 async function readZipEntry(buffer, entryPath, maxBytes, admitted) {
-    const archive = await loadAdmittedZipArchive(buffer, admitted);
-    let entry;
-    // JSZip keys retain some aliases and may use Unicode Path metadata. Scan the
-    // effective entries once, after raw ZIP admission has rejected collisions.
-    for (const candidate of Object.values(archive.files)) {
-        if (canonicalEntryPath(candidate.name) !== entryPath)
-            continue;
-        if (entry) {
-            throw new ArchiveSecurityError("entry-path", `archive contains duplicate entry path: ${formatErrorDetail(entryPath)}`);
-        }
-        entry = candidate;
-    }
-    if (!entry || entry.dir) {
+    const { archive, entries } = await loadAdmittedZipArchive(buffer, admitted);
+    const record = entries.get(entryPath);
+    if (!record || record.entry.dir) {
         throw new Error(`archive entry not found: ${formatErrorDetail(entryPath)}`);
     }
-    if (isZipSymlinkEntry(entry)) {
+    assertZipEntryBinding(archive, record, entryPath);
+    const { entry, kind } = record;
+    if (kind === "symlink") {
         throw new Error(`archive entry is a link: ${formatErrorDetail(entryPath)}`);
     }
-    if (zipEntryKind(entry) !== "file")
+    if (kind !== "file")
         throw new Error(`archive entry is not a file: ${formatErrorDetail(entryPath)}`);
-    const integrity = createZipIntegrityTransform(entry);
+    const integrity = createZipIntegrityTransform(record);
     const stream = typeof entry.nodeStream === "function"
         ? entry.nodeStream()
         : Readable.from(await entry.async("nodebuffer"));

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

@@ -3,7 +3,6 @@ import { type AsyncDirectoryGuard } from "./directory-guard.js";
 import { type ExtractionDeadline } from "./archive-deadline.js";
 import { ArchiveSecurityError } from "./archive-errors.js";
 export type ArchiveDirectoryGuard = AsyncDirectoryGuard<BigIntStats>;
-export { ArchiveSecurityError, type ArchiveSecurityErrorCode } from "./archive-errors.js";
 export declare function createDirectoryIdentityGuard(dir: string): Promise<ArchiveDirectoryGuard>;
 export declare function assertDirectoryIdentityGuard(guard: ArchiveDirectoryGuard): Promise<void>;
 export declare function prepareArchiveDestinationGuard(destDir: string): Promise<ArchiveDirectoryGuard>;
@@ -29,5 +28,5 @@ export declare function withStagedArchiveDestination<T>(params: {
     stagingDirPrefix?: string;
     run: (stagingDir: string) => Promise<T>;
 }): Promise<T>;
-export { mergeExtractedTreeIntoDestination } from "./archive-merge.js";
 export declare function createArchiveSymlinkTraversalError(originalPath: string): ArchiveSecurityError;
+export {};

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

@@ -21,7 +21,6 @@ const ARCHIVE_STAGING_MODE = 0o700;
 function checkExtractionDeadline(deadline) {
     deadline?.check();
 }
-export { ArchiveSecurityError } from "./archive-errors.js";
 function symlinkTraversalError(originalPath) {
     return new ArchiveSecurityError("destination-symlink-traversal", `${ERROR_ARCHIVE_ENTRY_TRAVERSES_SYMLINK}: ${formatErrorDetail(originalPath)}`);
 }
@@ -134,7 +133,9 @@ export async function assertResolvedInsideDestination(params) {
 }
 async function mkdirArchiveOutput(params) {
     try {
-        await params.targetRoot.mkdir(params.relativePath);
+        const relativePath = params.relativePath;
+        // Archive names are literal; retain Root.mkdir's admission without home expansion.
+        await params.targetRoot.mkdir(relativePath === "~" || relativePath.startsWith("~/") ? `./${relativePath}` : relativePath);
     }
     catch (error) {
         if (error instanceof FsSafeError) {
@@ -302,7 +303,6 @@ export async function withStagedArchiveDestination(params) {
         }
     }
 }
-export { mergeExtractedTreeIntoDestination } from "./archive-merge.js";
 export function createArchiveSymlinkTraversalError(originalPath) {
     return symlinkTraversalError(originalPath);
 }

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

@@ -1,5 +1,6 @@
 import { assertArchiveEntryCountWithinLimit, } from "./archive-limits.js";
 import { admitZipNames, zipExtraFields, zipFormat, zipUInt64 } from "./archive-zip-names.js";
+import { createArchiveOutputPathTracker } from "./archive-entry.js";
 function entryKind(attributes, directory) {
     const type = (attributes >>> 16) & 0o170000;
     // High-word symlinks remain links regardless of the creator or directory bits.
@@ -186,6 +187,7 @@ export function* scanZipDirectory(size, limits, onEntry) {
     const directory = yield* layout(size);
     assertArchiveEntryCountWithinLimit(directory.count, limits);
     const seen = new Set();
+    const trackKnownPath = createArchiveOutputPathTracker();
     const spans = [];
     let at = directory.start;
     let count = 0;
@@ -226,6 +228,8 @@ export function* scanZipDirectory(size, limits, onEntry) {
         const localNames = yield* read(localAt + 30, localNameLength + localExtraLength, directory.start);
         const localExtra = zipExtraFields(localNames.subarray(localNameLength));
         const admittedName = admitZipNames({ central: centralName, local: localNames.subarray(0, localNameLength), flags, centralExtra, localExtra, seen });
+        if (admittedName.path !== undefined)
+            trackKnownPath(admittedName.path, admittedName.path);
         const localValues = wideValues(local, localExtra, false);
         const crc = central.readUInt32LE(16);
         if (!(flags & 8) && (local.readUInt32LE(14) !== crc || localValues.compressed !== values.compressed || localValues.uncompressed !== values.uncompressed)) {

package/node_modules/@openclaw/fs-safe/dist/archive-zip-entry.d.ts

@@ -1,4 +1,4 @@
-import { type ArchiveEntryModePolicy, type ArchiveEntryKind } from "./archive-plan.js";
+import type { ArchiveEntryKind } from "./archive-plan.js";
 import type { ZipDirectoryEntry } from "./archive-zip-directory.js";
 export type ZipEntry = {
     name: string;
@@ -12,13 +12,13 @@ export type ZipEntry = {
     nodeStream?: () => NodeJS.ReadableStream;
     async: (type: "nodebuffer") => Promise<Buffer>;
 };
-/** Internal: register only after the complete decoder/admission association. */
-export declare function registerAdmittedZipEntry(entry: ZipEntry, physical: ZipDirectoryEntry): void;
-export declare function zipEntryIntegrityMetadata(entry: ZipEntry): {
-    crc32?: number;
-    uncompressedSize?: number;
-} | undefined;
-export declare function isZipSymlinkEntry(entry: ZipEntry): boolean;
-export declare function zipEntryKind(entry: ZipEntry): ArchiveEntryKind;
-export declare function zipEntryMode(entry: ZipEntry, policy: ArchiveEntryModePolicy | undefined): number;
-export declare function zipEntryDeclaredSize(entry: ZipEntry): number;
+export type AdmittedZipEntry = Readonly<{
+    entry: ZipEntry;
+    name: string;
+    kind: ArchiveEntryKind;
+    mode: number | undefined;
+    size: number;
+    crc32: number;
+}>;
+/** Internal: create only after the complete decoder/admission association. */
+export declare function createAdmittedZipEntry(entry: ZipEntry, name: string, physical: ZipDirectoryEntry): AdmittedZipEntry;