[Bug]: Linux without openat2 cannot complete nested no-clobber moves; native-off also disables required operations

[ericpearson]

Summary

On Linux 4.4.302+, fs-safe 0.13.1's Linux native path requires unavailable openat2 for nested paths. Native-off avoids that call but intentionally disables no-clobber Root.move(), leaving an OpenClaw retained-state migration without a working path. Please expose/validate the actual operation capabilities and consider secure older-kernel support while retaining native no-replace operations that the host does implement.

Minimal reproduction

Tested in a disposable published OpenClaw 2026.9.5 container, without production mounts, Node v24.19.0, with its installed @openclaw/fs-safe@0.13.1:

import fs from 'node:fs/promises';
import os from 'node:os';
import path from 'node:path';
import { root, configureFsSafeNative } from '@openclaw/fs-safe';

for (const mode of ['auto', 'off']) {
  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'fs-safe-probe-'));
  try {
    await fs.mkdir(path.join(dir, 'nested'));
    await fs.writeFile(path.join(dir, 'nested/source'), 'probe-source', {mode: 0o600});
    configureFsSafeNative({mode});
    try {
      const scoped = await root(dir);
      await scoped.move('nested/source', 'nested/destination');
      console.log({mode, result: 'move succeeded'});
    } catch (error) {
      console.log({mode, code: error.code, message: error.message});
    }
  } finally {
    await fs.rm(dir, {recursive: true, force: true});
  }
}

Observed for both auto and off:

code: helper-unavailable
message: native no-replace move is unavailable

Positive control: with source and destination directly under the root (no nested/ prefix), native auto successfully moves the file on this host; off still refuses. Nested parent resolution matters.

Expected behavior

Keep collision and path-containment guarantees. Detect and report unavailable operations before a consumer starts migration; document the supported kernel/capability floor. If older-kernel support is intended, retain available native primitives and provide a reviewed resolver or explicitly labeled policy-controlled fallback. A userspace walk must not falsely report kernel-atomic containment. This is not a request to change no-clobber moves into overwriting rename or silently ignore safety failures.

Actual behavior and downstream impact

The Linux resolver calls openat2(BENEATH | NO_MAGICLINKS) directly. A real pinned-plugin installation failed with openat2 beneath root: Function not implemented (os error 38).

We then rehearsed the full downstream upgrade on Btrfs-cloned state with both OPENCLAW_FS_SAFE_NATIVE_MODE=off and FS_SAFE_NATIVE_MODE=off verified in the candidate. First Doctor exited 1:

Failed staging config audit log legacy recovery restore journal: FsSafeError: native no-replace move is unavailable

OpenClaw's stageAuditRecoveryRestore() writes and syncs a staging journal, then uses default no-overwrite Root.move() to publish it. Native-off returns no binding, so this fails as designed. The old installation was restored and independently verified healthy; candidate startup and subsequent gates were not reached.

A separate direct syscall probe on disposable files in the updater's Btrfs data mount returned ENOSYS for openat2, but renameat2(RENAME_NOREPLACE) correctly returned EEXIST for an occupied destination without changing either file, and succeeded for an absent destination. All probe resources were removed. This establishes capabilities in that tested container/filesystem, not every mount or security policy; syscall filtering was not independently excluded.

Package version or commit

@openclaw/fs-safe@0.13.1, source 7022a0a10c53e36f34a467df68ed5614a1db1741. Main 6953a1d85a92160f036b9ce9cfd5c8f096f92cbe still has direct openat2 resolution. Updating to current main has not been tested.

Affected surface

Atomic operations and file locking; rooted path resolution.

Environment

Synology DSM; Linux 4.4.302+; x86_64; Node v24.19.0; Docker. Minimal package reproducer uses disposable container temporary storage; real migration uses Btrfs bind mounts. No credentials, personal paths, hostnames, or private content included.

Cross-references and provenance

• Main downstream compatibility issue and full redacted report: [Feature]: [Feature]: Handle openat2 ENOSYS gracefully when acquiring the gateway state lock openclaw#152839 (comment)
• OpenClaw 9.3 pins fs-safe 0.8.5 and disables native mode by default; 9.5 pins 0.13.1 and preserves native auto. fix: preserve file operations with fs-safe 0.13.1 openclaw#150263 adopted the newer version and explicitly retained fail-closed behavior without the helper. This report acknowledges that policy; it asks for capability handling/compatibility, not removal of collision protection.
• fix: restore fs-safe native support after update fallback openclaw#152349 repairs missing optional native packages, a different failure from unavailable syscalls.
• OpenClaw 2026.9.5: Codex retained-state migration never settles; session-catalog stuck permanently cold (empty session lists, "thread not loaded" on archive) openclaw#152744 and PR #153097 in that repository address a separate retained-session migration failure. We initially posted there and corrected the attribution after examining full logs.

Searches for openat2, ENOSYS, Synology, and older-kernel reports found no matching existing fs-safe issue. Happy to consolidate if a canonical tracker exists.

[ericpearson]

Additional dependency-pin compatibility proof, isolated from production:

We installed exact @openclaw/fs-safe@0.12.0 into a separate prefix in a disposable OpenClaw 2026.9.5 image and redirected the candidate's resolved fs-safe package to it. We did not run npm against OpenClaw's pnpm-managed dependency tree or migrate production state.

The minimal nested Root.move() probe above succeeds with 0.12.0 in both native auto and off. However, the actual OpenClaw CLI fails before even reporting its version, with both native-off flags set:

node dist/index.js --version
SyntaxError: The requested module '@openclaw/fs-safe/advanced' does not provide an export named 'resolvePathPrefixSync'
ExitCode: 1

The actual 9.5 image imports resolvePathPrefixSync. Source history places its introduction in 6bbb13d, released in 0.13.0. That release also introduced the native-only no-clobber move path (5fe53dd). Therefore 0.13.0 is not an intermediate release that preserves both the older move behavior and the newer consumer API.

The 9.3 baseline's 0.8.5 is not a compatible replacement either: it lacks sha256FileSync, also imported by the actual 9.5 image. This is an export-contract comparison; we did not claim a successful 9.5 run with 0.8.5.

A straight older-version pin is not sufficient for this consumer. Supporting this combination requires a reviewed compatibility change/backport, or a different runtime environment; neither has been proven by these tests. No pin was deployed. The disposable container and installed test packages were removed; original production image/configuration/mounts remain unchanged and healthy.

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed September 19, 2026, 7:24 PM ET / 23:24 UTC.

Summary
Keep open: current main and v0.16.0 retain the reported limitation. This is a concrete compatibility gap requiring a support-policy decision; native-off rejection is intentional, and the reporter’s downgrade experiment identifies a consumer API incompatibility.

Reproducibility: yes. from source: nested parent admission necessarily reaches openat2, and ENOSYS becomes helper-unavailable; native-off independently removes the required binding. No current-main runtime reproduction was executed.

Maintainer decision needed

Question	Recommendation
Should Linux without usable openat2 remain unsupported for nested no-clobber moves, with earlier capability diagnostics, or receive a separately reviewed compatibility resolver?	Preflight and document the existing boundary: Expose operation-specific admission failures before consumer migrations while retaining current nested-move requirements.

Why: Current rejection implements a documented safety contract; choosing a weaker containment mechanism or expanding the supported platform contract requires explicit owner intent.

Next step
Security-sensitive compatibility work needs an owner-approved support boundary before implementation; it is not a safe automatic bug-fix candidate.

Security
None.

Review details

Best possible solution:

Provide root-scoped operation preflight and actionable capability diagnostics while preserving fail-closed defaults; consider older-kernel resolution separately under an explicit, tested containment contract.

Do we have a high-confidence way to reproduce the issue?

Yes, from source: nested parent admission necessarily reaches openat2, and ENOSYS becomes helper-unavailable; native-off independently removes the required binding. No current-main runtime reproduction was executed.

Is this the best way to solve the issue?

Unclear for older-kernel execution support: operation-specific preflight is a focused improvement, but replacing the resolver requires a defined safety contract. Restoring check-then-rename or selecting overwrite would violate the requested guarantees.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• A userspace resolver could weaken containment during directory swaps even if renameat2 still prevents destination overwrite.
• The reported syscall results cover one container and filesystem; kernel support, syscall filtering, and mount-specific availability must remain distinguishable.

Codex review notes: model internal, reasoning medium; reviewed against 00c4ebaedcce.

Label changes

Label changes:

• add P2: A concrete older-Linux compatibility limitation blocks the reported migration, but current behavior deliberately preserves the package’s safety contract.
• add impact:security: The requested compatibility path directly concerns root containment and collision-safe filesystem mutation.
• add issue-rating: 🦞 diamond lobster: Current issue advisory state selects this label.
• add clawsweeper:source-repro: Current issue advisory state selects this label.
• add clawsweeper:no-new-fix-pr: Current issue advisory state selects this label.
• add clawsweeper:needs-product-decision: Current issue advisory state selects this label.

Label justifications:

• P2: A concrete older-Linux compatibility limitation blocks the reported migration, but current behavior deliberately preserves the package’s safety contract.
• impact:security: The requested compatibility path directly concerns root containment and collision-safe filesystem mutation.

Evidence reviewed

What I checked:

• Current Linux resolver explains nested-path failure: Nonempty relative paths call openat2 with BENEATH and NO_MAGICLINKS and propagate failure. Empty parent paths duplicate the retained root descriptor, explaining the reporter’s successful direct-child control. (native/src/unix.rs:83, 00c4ebaedcce)
• Move admission requires the resolver before rename: The no-clobber move opens source and destination parents through openNativeParentAdmission, which calls openBeneath. ENOSYS is normalized to helper-unavailable before rename dispatch. (src/root-move-noreplace.ts:125, 00c4ebaedcce)
• Native-off rejection is deliberate: getNativeBinding returns undefined in off mode. The move implementation rejects a missing binding, and the focused test asserts helper-unavailable while preserving the source and leaving the destination absent. (test/root-move-noreplace.test.ts:190, 00c4ebaedcce)
• Published compatibility contract: The 0.13.0 compatibility notes explicitly require usable native parent admission and no-replace rename, reject native-off operation, and prohibit the old check-and-replace fallback. The same release adds resolvePathPrefixSync, corroborating the reporter’s explanation of why an older dependency pin is insufficient. (CHANGELOG.md:139, 00c4ebaedcce)
• Release remains affected: GitHub identifies v0.16.0 as the latest release, published September 19. Its Linux resolver still directly calls openat2 for nonempty relative paths. Current main retains that requirement; no implemented fix was established. (native/src/unix.rs:70, acbb91625172)
• Feature history and routing: GitHub’s commit patch shows the native no-clobber dispatch and helper-unavailable checks added in this commit, whose author login is steipete. Current-path history also records subsequent work by Peter Steinberger. Some local historical blob reads and blame failed; GitHub commit inspection supplied the relevant patch, without establishing a source-line ownership pointer. (src/root-move-noreplace.ts, 5fe53ddc6ee3)

Likely related people:

• steipete: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.