@openclaw/openshell-sandbox 2026.9.7 → 2026.10.1-beta.1

package/dist/index.js

@@ -9,7 +9,8 @@ import { GUEST_FILESYSTEM_PYTHON } from "@openclaw/fs-safe/guest";
 import { createDeferred, formatPluginConfigIssue, mapPluginConfigIssues } from "openclaw/plugin-sdk/extension-shared";
 import { KeyedAsyncQueue } from "openclaw/plugin-sdk/keyed-async-queue";
 import { FsSafeError, canonicalPathFromExistingAncestor, extractErrorCode } from "openclaw/plugin-sdk/security-runtime";
-import { normalizeLowercaseStringOrEmpty } from "openclaw/plugin-sdk/string-coerce-runtime";
+import { asOptionalRecord, normalizeLowercaseStringOrEmpty } from "openclaw/plugin-sdk/string-coerce-runtime";
+import { safeParseJson } from "openclaw/plugin-sdk/text-utility-runtime";
 import { buildPluginConfigSchema } from "openclaw/plugin-sdk/core";
 import { MAX_TIMER_TIMEOUT_SECONDS } from "openclaw/plugin-sdk/number-runtime";
 import { z } from "zod";
@@ -63,9 +64,9 @@ const DEFAULT_SOURCE = "openclaw";
 const DEFAULT_REMOTE_WORKSPACE_DIR = "/sandbox";
 const DEFAULT_REMOTE_AGENT_WORKSPACE_DIR = "/agent";
 const DEFAULT_TIMEOUT_MS = 12e4;
-const OPEN_SHELL_MANAGED_REMOTE_ROOTS = [DEFAULT_REMOTE_WORKSPACE_DIR, DEFAULT_REMOTE_AGENT_WORKSPACE_DIR];
+const OPEN_SHELL_MANAGED_REMOTE_PATH = /^\/(?:sandbox|agent)(?:\/|$)/;
 const nonEmptyTrimmedString = (message) => z.string({ error: message }).trim().min(1, { error: message });
-const openShellManagedRemotePath = (fieldName) => nonEmptyTrimmedString(`${fieldName} must be a non-empty string`).regex(/^\/(?:sandbox|agent)(?:\/|$)/, { error: (issue) => String(issue.input).startsWith("/") ? `OpenShell ${fieldName} must stay under /sandbox or /agent` : `OpenShell ${fieldName} must be absolute` }).refine((value) => isManagedOpenShellRemotePath(path.posix.normalize(value)), { error: `OpenShell ${fieldName} must stay under /sandbox or /agent` });
+const openShellManagedRemotePath = (fieldName) => nonEmptyTrimmedString(`${fieldName} must be a non-empty string`).regex(OPEN_SHELL_MANAGED_REMOTE_PATH, { error: (issue) => String(issue.input).startsWith("/") ? `OpenShell ${fieldName} must stay under /sandbox or /agent` : `OpenShell ${fieldName} must be absolute` }).refine((value) => OPEN_SHELL_MANAGED_REMOTE_PATH.test(path.posix.normalize(value)), { error: `OpenShell ${fieldName} must stay under /sandbox or /agent` });
 const openShellWorkspaceName = z.string({ error: "workspace must be a valid OpenShell workspace name" }).trim().min(1, { error: "workspace must be a valid OpenShell workspace name" }).max(19, { error: "workspace must be at most 19 characters" }).regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, { error: "workspace must contain lowercase alphanumeric characters or single hyphens and must not start or end with a hyphen" });
 const OpenShellPluginConfigSchema = z.strictObject({
 	mode: z.enum(["mirror", "remote"], { error: "mode must be one of mirror, remote" }).optional(),
@@ -82,14 +83,9 @@ const OpenShellPluginConfigSchema = z.strictObject({
 	remoteAgentWorkspaceDir: openShellManagedRemotePath("remoteAgentWorkspaceDir").optional(),
 	timeoutSeconds: z.number({ error: `timeoutSeconds must be a number between 1 and ${MAX_TIMER_TIMEOUT_SECONDS}` }).min(1, { error: "timeoutSeconds must be a number >= 1" }).max(MAX_TIMER_TIMEOUT_SECONDS, { error: `timeoutSeconds must be a number <= ${MAX_TIMER_TIMEOUT_SECONDS}` }).optional()
 });
-function isManagedOpenShellRemotePath(value) {
-	return OPEN_SHELL_MANAGED_REMOTE_ROOTS.some((root) => value === root || value.startsWith(`${root}/`));
-}
-function normalizeOpenShellRemotePath(value, fallback, fieldName = "remote path") {
-	const candidate = value ?? fallback;
-	const normalized = path.posix.normalize(candidate.trim() || fallback);
-	if (!normalized.startsWith("/")) throw new Error(`OpenShell ${fieldName} must be absolute: ${candidate}`);
-	if (!isManagedOpenShellRemotePath(normalized)) throw new Error(`OpenShell ${fieldName} must stay under ${OPEN_SHELL_MANAGED_REMOTE_ROOTS.join(" or ")}: ${candidate}`);
+function normalizeOpenShellRemotePath(value) {
+	const normalized = path.posix.normalize(value);
+	if (!OPEN_SHELL_MANAGED_REMOTE_PATH.test(normalized)) throw new Error(`OpenShell remote path must stay under /sandbox or /agent: ${value}`);
 	return normalized;
 }
 function createOpenShellPluginConfigSchema() {
@@ -127,8 +123,8 @@ function resolveOpenShellPluginConfig(value) {
 		providers: [...new Set(cfg.providers ?? [])],
 		gpu: cfg.gpu ?? false,
 		autoProviders: cfg.autoProviders ?? true,
-		remoteWorkspaceDir: normalizeOpenShellRemotePath(cfg.remoteWorkspaceDir, DEFAULT_REMOTE_WORKSPACE_DIR, "remoteWorkspaceDir"),
-		remoteAgentWorkspaceDir: normalizeOpenShellRemotePath(cfg.remoteAgentWorkspaceDir, DEFAULT_REMOTE_AGENT_WORKSPACE_DIR, "remoteAgentWorkspaceDir"),
+		remoteWorkspaceDir: normalizeOpenShellRemotePath(cfg.remoteWorkspaceDir ?? DEFAULT_REMOTE_WORKSPACE_DIR),
+		remoteAgentWorkspaceDir: normalizeOpenShellRemotePath(cfg.remoteAgentWorkspaceDir ?? DEFAULT_REMOTE_AGENT_WORKSPACE_DIR),
 		timeoutMs: typeof cfg.timeoutSeconds === "number" ? Math.floor(cfg.timeoutSeconds * 1e3) : DEFAULT_TIMEOUT_MS
 	};
 }
@@ -223,21 +219,17 @@ var OpenShellFsBridge = class {
 	}
 	async mkdirp(params) {
 		const target = this.resolveTarget(params);
-		const hostPath = target.hostPath;
 		this.ensureWritable(target, "create directories");
 		await assertLocalPathSafety({
 			target,
 			allowFinalSymlinkForUnlink: false
 		});
 		await this.backend.mkdirpRemotePath(target.containerPath, params.signal);
-		await mkdirLocalRootPath({
-			hostPath,
-			target
-		});
+		const relativePath = relativeToRoot(target, target.hostPath);
+		if (relativePath) await (await root(target.mountHostRoot)).mkdir(relativePath);
 	}
 	async remove(params) {
 		const target = this.resolveTarget(params);
-		const hostPath = target.hostPath;
 		this.ensureWritable(target, "remove files", params.recursive);
 		await assertLocalPathSafety({
 			target,
@@ -250,15 +242,12 @@ var OpenShellFsBridge = class {
 		});
 		await removeLocalRootPath({
 			force: params.force,
-			hostPath,
 			recursive: params.recursive,
 			target
 		});
 	}
 	async rename(params) {
 		const { from, to } = this.resolveRenameTargets(params);
-		const fromHostPath = from.hostPath;
-		const toHostPath = to.hostPath;
 		await assertLocalPathSafety({
 			target: from,
 			allowFinalSymlinkForUnlink: true
@@ -267,20 +256,20 @@ var OpenShellFsBridge = class {
 			target: to,
 			allowFinalSymlinkForUnlink: false
 		});
-		await assertRenameSourceSupported(fromHostPath);
+		await assertRenameSourceSupported(from.hostPath);
 		if (from.mountHostRoot !== to.mountHostRoot) throw new Error("OpenShell cross-root mirror renames require pinned fs-safe support");
 		await assertSameDeviceRenameSupported({
-			fromHostPath,
+			fromHostPath: from.hostPath,
 			root: from.mountHostRoot,
-			toHostPath
+			toHostPath: to.hostPath
 		});
 		await this.backend.renameRemotePath(from.containerPath, to.containerPath, params.signal);
-		await moveLocalRootPath({
-			from,
-			fromHostPath,
-			to,
-			toHostPath
-		});
+		const root$3 = await root(from.mountHostRoot);
+		const fromRelativePath = relativeToRoot(from, from.hostPath);
+		const toRelativePath = relativeToRoot(to, to.hostPath);
+		const parentPath = path.dirname(toRelativePath);
+		if (parentPath !== "." && parentPath !== "") await root$3.mkdir(parentPath);
+		await root$3.move(fromRelativePath, toRelativePath, { overwrite: true });
 	}
 	async stat(params) {
 		const target = this.resolveTarget(params);
@@ -396,18 +385,13 @@ function expectResolvedContainerTarget(target, input) {
 	if (!target) throw new Error(`Sandbox path escapes allowed mounts; cannot access: ${input}`);
 	return target;
 }
-async function mkdirLocalRootPath(params) {
-	const relativePath = relativeToRoot(params.target, params.hostPath);
-	if (!relativePath) return;
-	await (await root(params.target.mountHostRoot)).mkdir(relativePath);
-}
 async function removeLocalRootPath(params) {
-	const root$3 = await root(params.target.mountHostRoot);
-	const relativePath = relativeToRoot(params.target, params.hostPath);
+	const root$4 = await root(params.target.mountHostRoot);
+	const relativePath = relativeToRoot(params.target, params.target.hostPath);
 	try {
-		if (params.force === false) await fsPromises.lstat(params.hostPath);
-		const targets = params.recursive && !relativePath ? (await root$3.list("")).map((name) => relativeToRoot(params.target, path.join(params.hostPath, name))) : [relativePath];
-		for (const target of targets) await root$3.remove(target, {
+		if (params.force === false) await fsPromises.lstat(params.target.hostPath);
+		const targets = params.recursive && !relativePath ? (await root$4.list("")).map((name) => relativeToRoot(params.target, path.join(params.target.hostPath, name))) : [relativePath];
+		for (const target of targets) await root$4.remove(target, {
 			force: params.force !== false,
 			...params.recursive ? {
 				recursive: true,
@@ -421,18 +405,6 @@ async function removeLocalRootPath(params) {
 		throw err;
 	}
 }
-async function moveLocalRootPath(params) {
-	const root$4 = await root(params.from.mountHostRoot);
-	const fromRelativePath = relativeToRoot(params.from, params.fromHostPath);
-	const toRelativePath = relativeToRoot(params.to, params.toHostPath);
-	await mkdirParentPath(root$4, toRelativePath);
-	await root$4.move(fromRelativePath, toRelativePath, { overwrite: true });
-}
-async function mkdirParentPath(root, relativePath) {
-	const parentPath = path.dirname(relativePath);
-	if (parentPath === "." || parentPath === "") return;
-	await root.mkdir(parentPath);
-}
 function relativeToRoot(target, hostPath) {
 	const relativePath = path.relative(target.mountHostRoot, hostPath);
 	return relativePath ? `.${path.sep}${relativePath}` : "";
@@ -638,10 +610,23 @@ const ENSURE_OPEN_SHELL_REMOTE_REAL_DIRECTORY_SCRIPT = [
 	"done"
 ].join("\n");
 function createOpenShellSandboxBackendFactory(params) {
-	return async (createParams) => await createOpenShellSandboxBackend({
-		...params,
-		createParams
-	});
+	return async (createParams) => {
+		if ((createParams.cfg.docker.binds?.length ?? 0) > 0) throw new Error("OpenShell sandbox backend does not support sandbox.docker.binds.");
+		const { sandboxName, legacyRuntimeAdopted } = resolveOpenShellSandboxName({
+			scopeKey: createParams.scopeKey,
+			registeredRuntimeIds: createParams.registeredRuntimeIds
+		});
+		return new OpenShellSandboxBackendImpl({
+			createParams,
+			execContext: {
+				config: params.pluginConfig,
+				sandboxName
+			},
+			legacyRuntimeAdopted,
+			remoteWorkspaceDir: params.pluginConfig.remoteWorkspaceDir,
+			remoteAgentWorkspaceDir: params.pluginConfig.remoteAgentWorkspaceDir
+		}).asHandle();
+	};
 }
 function createOpenShellSandboxBackendManager(params) {
 	return {
@@ -683,25 +668,6 @@ function createOpenShellSandboxBackendManager(params) {
 		}
 	};
 }
-async function createOpenShellSandboxBackend(params) {
-	if ((params.createParams.cfg.docker.binds?.length ?? 0) > 0) throw new Error("OpenShell sandbox backend does not support sandbox.docker.binds.");
-	const resolvedSandboxName = resolveOpenShellSandboxName({
-		scopeKey: params.createParams.scopeKey,
-		registeredRuntimeIds: params.createParams.registeredRuntimeIds
-	});
-	const sandboxName = resolvedSandboxName.sandboxName;
-	const execContext = {
-		config: params.pluginConfig,
-		sandboxName
-	};
-	return new OpenShellSandboxBackendImpl({
-		createParams: params.createParams,
-		execContext,
-		legacyRuntimeAdopted: resolvedSandboxName.legacyRuntimeAdopted,
-		remoteWorkspaceDir: params.pluginConfig.remoteWorkspaceDir,
-		remoteAgentWorkspaceDir: params.pluginConfig.remoteAgentWorkspaceDir
-	}).asHandle();
-}
 var OpenShellSandboxBackendImpl = class {
 	constructor(params) {
 		this.params = params;
@@ -1378,30 +1344,20 @@ function resolveOpenShellSandboxName(params) {
 	};
 }
 function parseOpenShellSandboxPhasePage(stdout, sandboxName) {
-	try {
-		const parsed = JSON.parse(stdout);
-		if (!Array.isArray(parsed)) return;
-		for (const entry of parsed) {
-			if (!entry || typeof entry !== "object") continue;
-			const record = entry;
-			if (record.name === sandboxName && typeof record.phase === "string") return {
-				count: parsed.length,
-				phase: record.phase
-			};
-		}
-		return { count: parsed.length };
-	} catch {
-		return;
+	const parsed = safeParseJson(stdout);
+	if (!Array.isArray(parsed)) return;
+	for (const entry of parsed) {
+		const record = asOptionalRecord(entry);
+		if (record?.name === sandboxName && typeof record.phase === "string") return {
+			count: parsed.length,
+			phase: record.phase
+		};
 	}
+	return { count: parsed.length };
 }
 function parseOpenShellSandboxPhase(stdout) {
-	try {
-		const parsed = JSON.parse(stdout);
-		if (typeof parsed !== "object" || parsed === null || !("phase" in parsed)) return;
-		return typeof parsed.phase === "string" ? parsed.phase : void 0;
-	} catch {
-		return;
-	}
+	const parsed = asOptionalRecord(safeParseJson(stdout));
+	return typeof parsed?.phase === "string" ? parsed.phase : void 0;
 }
 function resolveRemoteMaterializedSkillsWorkspaceDir(remoteWorkspaceDir) {
 	const root = remoteWorkspaceDir.replace(/\\/g, "/").replace(/\/+$/, "") || "/";

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

@@ -2,6 +2,101 @@
 
 ## Unreleased
 
+## 0.23.0 - 2026-10-02
+
+### Highlights
+
+- **BREAKING: Python bridge removed:** remove the Python bridge and its compatibility options; migrate to `configureFsSafeNative` / `FS_SAFE_NATIVE_MODE`. ([#815](https://github.com/openclaw/fs-safe/pull/815))
+- **Watch overflow:** fold busy hints so unselected sibling churn beside a missing tree no longer overflows the watch. ([#813](https://github.com/openclaw/fs-safe/pull/813))
+- **Windows exclusive creation:** no longer follows unchanged dangling file symlinks, including standalone creators, unrooted locks and cross-volume copy publication. ([#823](https://github.com/openclaw/fs-safe/pull/823), [#824](https://github.com/openclaw/fs-safe/pull/824))
+- **Faster metadata listings:** reduce path normalization and per-entry allocation when listing Root directory metadata. ([#818](https://github.com/openclaw/fs-safe/pull/818), [#819](https://github.com/openclaw/fs-safe/pull/819))
+
+### Fixes
+
+- **Windows directory preparation:** retain exact file identities in `ensureAbsoluteDirectory()` so a replaced directory cannot compare equal after large Windows file IDs are rounded to JavaScript numbers. ([#825](https://github.com/openclaw/fs-safe/pull/825))
+- **Windows writable creation:** in native `auto`/`off` mode, `openWritable()`, `append()`, and create-only writes could create a dangling file symlink's missing in-Root target before rejecting the link. Check final leaves before fallback creation; outside-Root targets were already rejected. ([#823](https://github.com/openclaw/fs-safe/pull/823))
+- **Windows symlink creation escape:** unchanged dangling file symlinks could redirect standalone exclusive creation outside the caller-selected directory, including source contents during cross-volume copy publication and records from unrooted fallback locks. Check final leaves before creation, including internal staging files; concurrent replacement remains best-effort. ([#824](https://github.com/openclaw/fs-safe/pull/824))
+- **Atomic writes:** preserve both parent-directory preparation and descriptor-close failures, in operation-first order, for synchronous and asynchronous replacements. ([#820](https://github.com/openclaw/fs-safe/pull/820))
+- **Watch overflow:** fold busy pending hints into guarded subtree reconciliation so unselected sibling churn beside a missing tree no longer exhausts the hint budget. ([#813](https://github.com/openclaw/fs-safe/pull/813))
+- **Native initialization:** lazily load the addon in fs-safe's import context so its housekeeping does not retain the first operation's `AsyncLocalStorage` stores when fs-safe is imported outside caller scopes. ([#797](https://github.com/openclaw/fs-safe/pull/797))
+
+### Performance
+
+- **Root metadata path assembly:** avoid renormalizing each literal child beneath its canonical directory, cutting 1,000-entry listing time by a further 19–23% and sampled allocations by 33–34% on Linux x64. ([#819](https://github.com/openclaw/fs-safe/pull/819))
+- **Root metadata listings:** construct named metadata once per entry, reducing 1,000-entry listing time by 16% and sampled allocations by 27–28% on Linux x64, with all filesystem and identity checks retained. ([#818](https://github.com/openclaw/fs-safe/pull/818))
+
+### Compatibility
+
+- **Removed compatibility options:** remove `configureFsSafePython`, `FsSafePythonConfig`, `pythonPath`, and the six Python environment variables; use `configureFsSafeNative`, `FsSafeNativeConfig`, and `FS_SAFE_NATIVE_MODE` (or `OPENCLAW_FS_SAFE_NATIVE_MODE`). The Python variables are now ignored, so a deployment that still sets `FS_SAFE_PYTHON_MODE=require` or `off` runs in `auto` until it sets `FS_SAFE_NATIVE_MODE`. Remove secure-temp `chmodSync`, atomic adapter `chmod`/`chmodSync`, Root `nonBlockingRead`, and ACL `principalSids`; use descriptor-bound permission adapters (`descriptor` for secure-temp, `FileHandle.chmod` / `fchmodSync` for atomic writes), automatic nonblocking read admission, and direct SID classification. Callers passing removed options get TypeScript errors. ([#815](https://github.com/openclaw/fs-safe/pull/815))
+
+## 0.22.0 - 2026-10-01
+
+### Highlights
+
+- **One-way publication:** `retainEntryForPublication` on `advanced` provides no-replace export for POSIX directories, regular files and direct symlinks, plus Windows NTFS files, directories, symbolic links and junctions. ([#776](https://github.com/openclaw/fs-safe/pull/776), [#778](https://github.com/openclaw/fs-safe/pull/778), [#779](https://github.com/openclaw/fs-safe/pull/779))
+- **Windows path hardening:** reject foreign UNC shares and device namespaces before filesystem probes, blocking attacker-chosen SMB lookups, NTLM exposure and stalls. ([#781](https://github.com/openclaw/fs-safe/pull/781), [#784](https://github.com/openclaw/fs-safe/pull/784))
+- **Watch overflow fixes:** Linux watch-retirement echoes no longer overflow unrelated subscriptions; Linux and macOS classify undecodable names, Linux preserves nameless lifecycle events, and macOS cleans up failed startup correctly. ([#782](https://github.com/openclaw/fs-safe/pull/782), [#783](https://github.com/openclaw/fs-safe/pull/783), [#769](https://github.com/openclaw/fs-safe/pull/769))
+
+### Features
+
+- **One-way publication:** `retainEntryForPublication` retains source and parent identities for native no-replace export on supported local POSIX filesystems and Windows NTFS. It supports directories, regular files and direct symbolic links, plus NTFS junctions; link targets stay opaque, and POSIX relative and dangling targets retain their exact bytes. Commit, indeterminate and close failures remain distinct. Requires caller-exclusive source namespaces, with no source-CAS or automatic rollback guarantee; disposal only closes retained resources and never deletes either location. ([#776](https://github.com/openclaw/fs-safe/pull/776), [#778](https://github.com/openclaw/fs-safe/pull/778), [#779](https://github.com/openclaw/fs-safe/pull/779))
+
+### Fixes
+
+- **Watch name handling:** ignore undecodable unselected siblings, fail closed for selected tree names on Linux and macOS, and preserve Linux directory lifecycle detail without spurious overflow. ([#783](https://github.com/openclaw/fs-safe/pull/783))
+- **Windows UNC admission:** Root, root-file readers, `pathScope`, `isPathInside`, secret-file writers, sibling-temp output, trash admission, and archive output preparation reject foreign UNC shares and device namespaces before probing them, comparing hosts without Unicode case folding, preventing attacker-chosen SMB lookups, NTLM exposure, and stalls. Existing containment errors are preserved; absolute paths on another share no longer resolve through aliases back into the boundary. ([#781](https://github.com/openclaw/fs-safe/pull/781), [#784](https://github.com/openclaw/fs-safe/pull/784))
+- **Linux watch isolation:** closing or replacing a watch, including after a scan failure, no longer overflows unrelated subscriptions. ([#782](https://github.com/openclaw/fs-safe/pull/782))
+- **macOS watch startup:** clean up rejected FSEvents configuration and failed stream startup with the correct lifecycle calls, keeping the registration available for retry. ([#769](https://github.com/openclaw/fs-safe/pull/769))
+
+### Performance
+
+- **Bounded temporary-directory cleanup:** avoid a redundant descriptor metadata read for each descendant directory on Linux and macOS, while retaining fresh name identity checks before removal. ([#760](https://github.com/openclaw/fs-safe/pull/760))
+- **Atomic temp cleanup:** use the file identity captured after creation, avoiding an unnecessary metadata lookup and preserving preexisting temporary paths. ([#772](https://github.com/openclaw/fs-safe/pull/772))
+
+### Compatibility
+
+- Windows now rejects foreign UNC shares and device namespaces before probing them. Absolute paths on another share no longer resolve through aliases back into the boundary; callers that relied on that behavior must pass in-boundary paths. ([#781](https://github.com/openclaw/fs-safe/pull/781), [#784](https://github.com/openclaw/fs-safe/pull/784))
+
+## 0.21.3 - 2026-09-30
+
+### Highlights
+
+- **Watch transient files:** excluded files and atomic-save temp files no longer cause spurious overflow when they disappear between guarded passes. ([#773](https://github.com/openclaw/fs-safe/pull/773))
+- **Faster watch rescans:** unrelated native hints skip rescans, and relevant hints reconcile affected directories, reducing scan work and allocation. ([#774](https://github.com/openclaw/fs-safe/pull/774))
+
+### Fixes
+
+- **Watch:** no longer reports overflow when an excluded or atomic-save temp file appears and disappears between guarded passes under the same observed parent directory. ([#773](https://github.com/openclaw/fs-safe/pull/773))
+- **Windows removal:** nonrecursive `Root.remove()` reports `not-empty` for a nonempty directory in required native mode, including with `force: true`, instead of `not-removable`. ([#771](https://github.com/openclaw/fs-safe/pull/771))
+- **Copy and staging failures:** preserve publication callback errors with unreadable metadata, retain uncertain native rename outcomes, and prevent repeated or reentrant cleanup from reusing consumed descriptors. ([#763](https://github.com/openclaw/fs-safe/pull/763))
+
+### Performance
+
+- **Watch:** skip guarded unrelated native hints and reconcile affected directories, reducing a 502-file memory-watch fixture from 513 to 55 visits and 8.16 MB to 1.33 MB sampled allocation per relevant event pass; unrelated detailed hints at two edits/second no longer trigger 120 full scans/minute, while periodic and uncertain-event reconciliation remain full. ([#774](https://github.com/openclaw/fs-safe/pull/774))
+- **Linux fallback resolution:** reuse the file type from each component's checked descriptor observation, avoiding a duplicate metadata read while retaining fresh identity, symlink-target, and mount-policy checks. ([#757](https://github.com/openclaw/fs-safe/pull/757))
+- **Native parent validation:** reuse the retained descriptor's captured identity during ordinary POSIX policy checks, avoiding a duplicate metadata read while keeping the final pathname inspection fresh. ([#735](https://github.com/openclaw/fs-safe/pull/735))
+
+## 0.21.2 - 2026-09-28
+
+### Highlights
+
+- **`require` mode confines mutations under hostile concurrency:** with `FS_SAFE_NATIVE_MODE=require` (or `configureFsSafeNative({ mode: "require" })`), remove, recursive remove, `mkdir`, writable-open creation and overwrite `move` now run through retained, identity-checked native parents: descriptor-relative `unlinkat`, `mkdirat` and `renameat2` on POSIX, and handle-relative operations on Windows. An adversarial race fuzzer observed no outside or denied-path effects across about 2.8 million racing calls on Linux (with and without `openat2`), macOS and Windows. `auto` keeps its documented best-effort paths and performance. See the [operation/platform matrix](docs/security-model.md#native-root-mutation-capabilities). ([#744](https://github.com/openclaw/fs-safe/pull/744), [#751](https://github.com/openclaw/fs-safe/pull/751), [#750](https://github.com/openclaw/fs-safe/pull/750), [#752](https://github.com/openclaw/fs-safe/pull/752))
+- **Watch on macOS:** entry scopes use identity-checked kqueue descriptors instead of recursive FSEvents streams, ending overflow storms for shallow ancestor scopes above busy trees. ([#753](https://github.com/openclaw/fs-safe/pull/753))
+- **Faster watch scans:** watch readiness and reconciliation are 27–34% faster on large trees. ([#747](https://github.com/openclaw/fs-safe/pull/747))
+
+### Fixes
+
+- **Watch cancellation:** a subscription's `signal` closes it even when another abort listener stops event propagation. ([#738](https://github.com/openclaw/fs-safe/pull/738))
+- **Walk cancellation:** walks stop without yielding the current entry when a synchronous filter aborts the signal. ([#739](https://github.com/openclaw/fs-safe/pull/739))
+- **Writes with `mkdir: false`:** the JavaScript fallback writes through existing in-root parent aliases using the same guarded walk, instead of rejecting them. ([#740](https://github.com/openclaw/fs-safe/pull/740))
+- **Descriptor exhaustion:** native writes that fail with `EMFILE`/`ENFILE` report `helper-failed` with the exhaustion code, the indeterminate publication outcome and the preserved stage, instead of a misleading path error. ([#742](https://github.com/openclaw/fs-safe/pull/742))
+- **Walk memory:** `walkDirectory()` and `walkDirectorySync()` stop reading a directory once `maxEntries` is reached instead of enumerating it completely first. `Root.walk()` sorted mode stays deterministic. ([#743](https://github.com/openclaw/fs-safe/pull/743))
+
+### Compatibility
+
+- In `require` mode, the operations above now reject with `helper-unavailable` where no confining native primitive exists, instead of silently falling back to JavaScript. Examples are recursive removal on Linux without `openat2` and recursive directory removal on Windows. Use `auto` for the best-effort fallback. These `require`-mode mutations also do more identity-checked work and are slower than before, while `auto` is unchanged. ([#744](https://github.com/openclaw/fs-safe/pull/744), [#751](https://github.com/openclaw/fs-safe/pull/751), [#750](https://github.com/openclaw/fs-safe/pull/750))
+- Create-only writes to an existing directory report `already-exists` in every implementation (previously `not-file` on some Windows paths). With `mutationSymlinks` omitted, Windows native and legacy JavaScript writes still differ for final links and parent junctions; set `mutationSymlinks: "reject"` for uniform behavior. ([#745](https://github.com/openclaw/fs-safe/pull/745))
+
 ## 0.21.1 - 2026-09-27
 
 ### Fixes