You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@opendal.apache.org by xu...@apache.org on 2026/10/26 16:10:03 UTC

(opendal-yinyang) 03/03: test: validate Linux FUSE saves and recovery on real mounts (#85)

This is an automated email from the ASF dual-hosted git repository.

Xuanwo pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/opendal-yinyang.git

commit 60daa7fefd87802ea55f9914c227dabb41dcba16
Author: Xuanwo <gi...@xuanwo.io>
AuthorDate: Tue Oct 27 00:09:51 2026 +0800

    test: validate Linux FUSE saves and recovery on real mounts (#85)
    
    * test: add Linux FUSE acceptance harness
    
    Exercise the yy mount subprocess and /dev/fuse boundary against isolated S3, with object and service publication coverage, read-only selection, failure recovery, and unmount cleanup.
    
    Co-authored-by: Chojan Shang <ps...@apache.org>
    
    * test: harden Linux FUSE acceptance semantics
    
    Keep external-change descriptors pinned, coordinate concurrent mounts, interrupt real in-flight fsync, preserve stale service addresses across restart, and require clean unmount and SIGTERM lease release.
    
    Co-authored-by: Chojan Shang <ps...@apache.org>
    
    * test: fix Linux FUSE acceptance compilation
    
    Pass owned commands to the timeout runner, use lossy path conversion at the CLI boundary, remove unneeded mutability, and prove pending fsync reaches frozen state before the daemon crash.
    
    Co-authored-by: Chojan Shang <ps...@apache.org>
    
    * test: cover Linux read-only directory traversal
    
    Seed a nested tree and a 520-entry directory through one Planner transaction, then exercise cached readdir after lookup, stable inodes, page cursors, and rename identity.
    
    Co-authored-by: Chojan Shang <ps...@apache.org>
    
    * test: fix cached readdir inner-entry assertion
    
    Avoid a map(function-pointer) type mismatch on the &&str iteration and assert the nested directory contents with set membership.
    
    Co-authored-by: Chojan Shang <ps...@apache.org>
    
    * test: add writable flush truncate and chmod boundaries
    
    Verify read-only close does not publish another descriptor's dirty or frozen state, real truncate(2) without fh reaches the authority, and chmod is limited to representable executable modes.
    
    Co-authored-by: Chojan Shang <ps...@apache.org>
    
    * test: cover chmod generation and directory mode boundaries
    
    Exercise dirty-write plus path chmod plus continued write plus fsync without self-conflict, and require fixed 0755 directories to reject chmod 0644.
    
    Co-authored-by: Chojan Shang <ps...@apache.org>
    
    * test: enable S3 service in Linux FUSE harness
    
    The integration test target constructs the same OpenDAL S3 operator as the binary, so its dev dependency needs the S3 and reqwest transport features.
    
    Co-authored-by: Chojan Shang <ps...@apache.org>
    
    * fix: register S3 schemes and harden xtask parse exits
    
    Register opendal default schemes in the acceptance harness and make xtask parse errors exit nonzero while keeping --help and --version at exit 0.
    
    Co-authored-by: Chojan Shang <ps...@apache.org>
    
    * test: keep staged sizes coherent across dirty and external changes
    
    Use same-length dirty payloads, assert fd fstat and path stat track staged grow/truncate after the attribute TTL, and pin the old descriptor's staged size against external growth and shrink.
    
    Co-authored-by: Chojan Shang <ps...@apache.org>
    
    * test: cover delayed completion after client SIGKILL
    
    Use a Python helper with stdin/stdout barriers to open and write, freeze fsync against a paused service, SIGKILL the client, recover the service, and verify delayed remote completion without real cancellation.
    
    Co-authored-by: Chojan Shang <ps...@apache.org>
    
    * test: cover busy SIGTERM grace and open-fd teardown
    
    Parameterize pending-fsync interruption by SIGKILL or SIGTERM, require forced non-zero exit within 10s with a held descriptor or frozen request, verify fd I/O errors and lease release, and check same-mount fresh reopens after external changes.
    
    Co-authored-by: Chojan Shang <ps...@apache.org>
    
    * test: avoid concurrent readiness deadlock and preserve overwrite tails
    
    Use bounded preparation and release channels for concurrent mounts so a failed create cannot strand the parent, and make the basic overwrite payload match the seeded length.
    
    Co-authored-by: Chojan Shang <ps...@apache.org>
    
    * test: remove unused mutability from concurrent writers
    
    File::sync_all uses shared access; keep the preparation binding mutable only for write and the post-barrier binding immutable.
    
    Co-authored-by: Chojan Shang <ps...@apache.org>
    
    * test: drop basic reader and retain service address across restarts
    
    Close the multi-fd reader before unmount and remember the last metadata service address so restart after an earlier stop remains usable.
    
    Co-authored-by: Chojan Shang <ps...@apache.org>
    
    * test: isolate authority checks and prepare SIGHUP refresh coverage
    
    Use in-process independent authority/runtime reads and writes plus nix signals so parent exec cannot FLUSH dirty FUSE descriptors; add the SIGHUP rename/add namespace and old-fd acceptance case.
    
    Co-authored-by: Chojan Shang <ps...@apache.org>
    
    * test: gate frozen commits and cover exec-close flush
    
    Add a transparent loopback TCP gate that blocks only the first mounted-volume connection after Runtime::inspect reports frozen, use it for pending fsync interruption flows, and prove CLOEXEC exec-close publishes a parent dirty descriptor.
    
    Co-authored-by: Chojan Shang <ps...@apache.org>
    
    * test: require completed SIGHUP notification counts
    
    Wait for the grounded refresh completion line and require positive inode/entry counts with zero notification errors before asserting namespace and pinned-fd behavior.
    
    Co-authored-by: Chojan Shang <ps...@apache.org>
    
    * test: fix frozen gate startup and release ordering
    
    Allow pre-staging service RPCs through the gate, remove the nonparallel frozen read, and assert the authority is unchanged before releasing a gated commit.
    
    Co-authored-by: Chojan Shang <ps...@apache.org>
    
    * test: cover fcntl O_APPEND toggling
    
    Clear and restore O_APPEND on one open descriptor, verify overwrite versus append behavior through fsync, and check both remote results.
    
    Co-authored-by: Chojan Shang <ps...@apache.org>
    
    * test: preserve pinned SIGHUP view until refs close
    
    Fix Linux trait-object coercion and borrow scoping, then assert renamed-path opens remain on the shared old view while an old descriptor lives and use a longer external payload to prove fstat pinning.
    
    Co-authored-by: Chojan Shang <ps...@apache.org>
    
    * test: fix root borrow scopes in Linux acceptance
    
    Keep the cached-readdir root borrowed and own the SIGHUP root before sending the mutable refresh signal.
    
    Co-authored-by: Chojan Shang <ps...@apache.org>
    
    * test: remove unused FUSE helpers and lint issues
    
    Drop obsolete command text, pause/resume, and kill helpers, remove redundant append write mode, and avoid needless path borrows in the pending-fsync helper.
    
    Co-authored-by: Chojan Shang <ps...@apache.org>
    
    * test: stream mount output for live refresh markers
    
    Append stdout/stderr chunks to shared capture buffers as they arrive so SIGHUP completion markers are visible while the mount process is alive.
    
    Co-authored-by: Chojan Shang <ps...@apache.org>
    
    ---------
    
    Co-authored-by: Chojan Shang <ps...@apache.org>
---
 .github/workflows/ci.yml           |   45 ++
 Cargo.toml                         |    6 +-
 docs/linux-fuse-acceptance.md      |  124 +++
 tests/linux_fuse/acceptance.rs     | 1526 ++++++++++++++++++++++++++++++++++++
 tests/linux_fuse/delayed_client.py |   31 +
 tests/linux_fuse/harness.rs        | 1144 +++++++++++++++++++++++++++
 tests/linux_fuse/main.rs           |   21 +
 xtask/src/main.rs                  |   84 +-
 8 files changed, 2978 insertions(+), 3 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 578882d..46a5222 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -142,6 +142,49 @@ jobs:
             docker logs yinyang-silo
           fi
 
+  linux-fuse:
+    name: Linux FUSE acceptance
+    runs-on: ubuntu-24.04
+    timeout-minutes: 45
+    env:
+      YINYANG_S3_BUCKET: yinyang-test
+      YINYANG_S3_ENDPOINT: http://127.0.0.1:9000
+      YINYANG_S3_REGION: us-east-1
+      YINYANG_S3_ACCESS_KEY_ID: yinyang-test
+      YINYANG_S3_SECRET_ACCESS_KEY: yinyang-test-only
+      YINYANG_STORAGE_PROFILE: minio
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Show FUSE device
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y fuse3
+          ls -l /dev/fuse
+
+      - name: Start isolated S3-compatible storage
+        run: |
+          docker run -d --name yinyang-linux-fuse-silo -p 127.0.0.1:9000:9000 \
+            -e MINIO_ROOT_USER=yinyang-test -e MINIO_ROOT_PASSWORD=yinyang-test-only \
+            docker.io/pgsty/silo:RELEASE.2026-09-16T00-00-00Z@sha256:635197cb9f36d01bee221d34d1c7d7960f6a95c48b0b6c01d99cd13bdae51a46 server /data
+          for _ in $(seq 1 30); do
+            if curl --fail --silent http://127.0.0.1:9000/minio/health/ready; then break; fi
+            sleep 1
+          done
+          curl --fail http://127.0.0.1:9000/minio/health/ready
+          docker exec yinyang-linux-fuse-silo mcli alias set local http://127.0.0.1:9000 yinyang-test yinyang-test-only
+          docker exec yinyang-linux-fuse-silo mcli mb local/yinyang-test
+
+      - name: Run real Linux FUSE acceptance
+        run: cargo x test-linux-fuse
+
+      - name: Show storage logs on failure
+        if: failure()
+        run: |
+          if docker container inspect yinyang-linux-fuse-silo > /dev/null 2>&1; then
+            docker logs yinyang-linux-fuse-silo
+          fi
+
   required:
     name: Required
     runs-on: ubuntu-24.04
@@ -152,6 +195,7 @@ jobs:
       - test
       - compliance
       - s3
+      - linux-fuse
     steps:
       - name: Guardian
         run: |
@@ -161,6 +205,7 @@ jobs:
               && "${{ needs.test.result }}" == "success" \
               && "${{ needs.compliance.result }}" == "success" \
               && "${{ needs.s3.result }}" == "success" \
+              && "${{ needs.linux-fuse.result }}" == "success" \
               ) ]]; then
             echo "Required jobs haven't been completed successfully."
             exit 1
diff --git a/Cargo.toml b/Cargo.toml
index 89537da..17e804d 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -57,7 +57,11 @@ yinyang-core = { path = "crates/core" }
 [target.'cfg(target_os = "linux")'.dependencies]
 fuser = "0.17.0"
 libc = "0.2"
-nix = { version = "0.30.0", features = ["user"] }
+nix = { version = "0.30.0", features = ["signal", "user"] }
+
+[dev-dependencies]
+opendal = { workspace = true, features = ["http-transport-reqwest", "services-s3"] }
+tempfile = "3"
 
 [workspace]
 members = [".", "crates/core", "crates/native", "xtask"]
diff --git a/docs/linux-fuse-acceptance.md b/docs/linux-fuse-acceptance.md
new file mode 100644
index 0000000..c5b7509
--- /dev/null
+++ b/docs/linux-fuse-acceptance.md
@@ -0,0 +1,124 @@
+# Linux FUSE acceptance
+
+This is the acceptance entry point for the Linux mount frontend. It validates
+the real product boundary: a `yy` subprocess installs a `/dev/fuse` mountpoint
+through `yy --volume CONFIG mount MOUNTPOINT`, and every scenario operates on
+that mountpoint with ordinary POSIX file descriptors. A mount that is not the
+YinYang kernel filesystem type (`fuse.yinyang`), a missing `/dev/fuse`, missing
+S3 settings, or a failed subprocess is a hard failure. There is no skip path in
+this acceptance run.
+
+The regular workspace checks (`cargo x test`) do not depend on `/dev/fuse`;
+`tests/linux_fuse` is compiled on Linux but its scenarios stay ignored there.
+Both object and service publication are exercised.
+
+## Run
+
+Use the same MinIO-compatible environment as the S3 CI job:
+
+```shell
+export YINYANG_S3_BUCKET=yinyang-test
+export YINYANG_S3_ENDPOINT=http://127.0.0.1:9000
+export YINYANG_S3_REGION=us-east-1
+export YINYANG_S3_ACCESS_KEY_ID=yinyang-test
+export YINYANG_S3_SECRET_ACCESS_KEY=yinyang-test-only
+export YINYANG_STORAGE_PROFILE=minio
+
+cargo x test-linux-fuse
+```
+
+Start an isolated Silo (the CI workflow uses the pinned `pgsty/silo` image)
+before running locally. Every test creates its own remote prefix and staging
+directory, mounts under its own temporary directory, and cleans up with
+`fusermount3`.
+
+Run only the read-only stage for a first-layer adapter PR:
+
+```shell
+cargo x test-linux-fuse --read-only
+```
+
+## Scenarios
+
+- Read-only basic: mounted reads, and explicit rejection (`EROFS`/`EACCES`) of
+  writable open, create, mkdir and rename.
+- Read-only directories: nested `read_dir` enumeration and stable inode numbers
+  across repeated stat calls, cached `readdir` after a file lookup/read, and a
+  520-entry bulk directory that crosses the adapter's 512-entry readdir page.
+- Basic writable I/O: create, write, remote `fsync` verified through an
+  independent authority, append, truncate, and multiple descriptors on one file.
+- Append flag toggling: one descriptor opened with `O_APPEND`, then cleared and
+  restored via `fcntl(F_SETFL)`, must overwrite at an explicit offset while
+  cleared and append only while restored; both remote results are verified.
+- Dirty descriptor isolation: a read-only descriptor closed while another
+  descriptor is dirty must not publish the dirty or frozen state; explicit
+  `fsync` on the dirty descriptor establishes the remote result.
+  Path stat and fd fstat both report the staged size after dirty grow/truncate
+  across the attribute TTL, and an external grow/shrink cannot overwrite the
+  same inode's staged size while an old descriptor is retained.
+- CLOEXEC/flush boundary: while a parent keeps a dirty descriptor open, an
+  in-process independent authority read still sees the old bytes; spawning
+  `/bin/true` explicitly exec-closes the inherited descriptor and the next
+  independent read observes the newly published bytes.
+- External rename and add refresh: after warming a dentry and opening an old
+  descriptor, an independent in-process authority renames `a` to `b`, changes
+  `b`, and adds `new.txt`; SIGHUP must emit a native invalidation notification,
+  the same mount must expose the new namespace, and the old descriptor (and a
+  new open of the renamed path while it lives) must retain the shared pinned
+  bytes and fstat until the old descriptor is closed; only the fresh open after
+  that sees the independently observed longer payload. The grounded
+  `yy: fuse refresh: done (inode=N entries=N errors=N)` line must report
+  positive inode/entry counts and zero errors before namespace assertions;
+  notification counts prove the native calls were accepted, while the
+  namespace and pinned-fd assertions prove their effect.
+- Path truncate: real `truncate(2)` without an open descriptor commits its
+  shrink/extend result to the independent authority at an explicit boundary.
+- Limited chmod: `0644 <-> 0755` is observable, while non-representable modes
+  such as `0600` and `0000` fail with an explicit error and leave attributes
+  unchanged. Directories remain fixed at `0755`; `chmod 0644` on a directory
+  must not report success. A path chmod to executable while one descriptor is
+  dirty must not self-conflict when that same descriptor continues writing and
+  later performs `fsync`.
+- Safe-save rename replacement: `rename` replaces an observed destination
+  atomically and the independent authority observes the result; plain rename
+  preserves the moved node's inode identity.
+- Retained unlink reads: bytes stay readable through an already-open descriptor
+  after `unlink`.
+- Unsupported operations: symlink and hard link return an explicit OS error
+  instead of advertising POSIX links.
+- External changes and dirty refresh: a descriptor opened before an external
+  grow/shrink keeps its pinned size, EOF and pread results, a fresh reopen
+  reflects the authoritative size, and a dirty descriptor keeps its staged
+  bytes while `fsync` reports failure instead of silently rebasing.
+- Concurrent mounts: two live `yy mount` processes on separate staging
+  directories publish distinct files concurrently under a barrier, then read
+  across each other's mounts.
+- Process kill recovery: `SIGKILL` of the mount process retains staged bytes
+  through persistent staging while the descriptor is still open; a reopened
+  mount can read and publish them.
+- Fsync/network failure retention: stopping the metadata service makes
+  `fsync` fail within a bound; staged bytes survive, the service restarts, and
+  a reopened mount publishes them through the unchanged service address.
+- Pending fsync interruption: a loopback TCP gate used only by the mount blocks
+  the first connection observed after `Runtime::inspect` reports
+  `frozen: true`. Killing the mount daemon then interrupts that pending
+  publication, the authority is untouched, and a reopened mount replays the
+  frozen request and publishes the staged bytes.
+- Delayed completion with client interruption: a separate Python client opens
+  and writes through `stdin`/`stdout` barriers, the gate blocks the frozen
+  commit connection, and the client is SIGKILLed. After gate release the
+  independent authority sees the delayed completion and the daemon remains
+  usable and unmounts normally. This verifies the adapter's ignored
+  interrupt/delayed completion behavior, not real cancellation.
+- Busy unmount: `fusermount3 -u` fails while a descriptor is open and succeeds
+  after the descriptor is released.
+- Unmount lifecycle: after a successful external `fusermount3 -u`, `yy` exits
+  on its own, removes the mount entry, and releases the staging lease. A
+  separate clean SIGTERM scenario verifies the same process and lease
+  lifecycle. Busy SIGTERM with an open descriptor or a pending fsync must exit
+  through the forced non-zero grace path within 10s, leave the held descriptor
+  with I/O errors, release the lease, and allow the same staging to remount.
+
+The assertions follow the core specs. They do not add POSIX guarantees that the
+transactional filesystem does not provide; for example symlinks are rejected,
+and dirty bases report conflict rather than merging.
diff --git a/tests/linux_fuse/acceptance.rs b/tests/linux_fuse/acceptance.rs
new file mode 100644
index 0000000..b15317b
--- /dev/null
+++ b/tests/linux_fuse/acceptance.rs
@@ -0,0 +1,1526 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Real /dev/fuse acceptance scenarios for the YinYang mount adapter.
+
+use crate::harness::{
+    Fixture, Frontend, Mounted, Publication, ServiceGate, assert_errno, run_external,
+    sync_all_with_deadline,
+};
+use nix::fcntl::{FcntlArg, OFlag, fcntl};
+use nix::unistd::truncate;
+use std::fs::{self, File, OpenOptions};
+use std::io::{BufRead, BufReader, Read, Seek, SeekFrom, Write};
+use std::os::unix::fs::{FileExt, MetadataExt, PermissionsExt};
+use std::path::Path;
+use std::process::{Child, Command, Stdio};
+use std::sync::mpsc;
+use std::thread;
+use std::time::{Duration, Instant};
+
+const EACCES: i32 = 13;
+const ENOSYS: i32 = 38;
+const EPERM: i32 = 1;
+const EOPNOTSUPP: i32 = 95;
+const EROFS: i32 = 30;
+const EINVAL: i32 = 22;
+const ENOTCONN: i32 = 107;
+const EIO: i32 = 5;
+const ENOENT: i32 = 2;
+const ATTR_TTL_WAIT: Duration = Duration::from_millis(1500);
+
+#[derive(Clone, Copy)]
+enum Interrupt {
+    Kill,
+    Terminate,
+}
+
+#[test]
+#[ignore = "requires /dev/fuse and isolated S3; run with cargo x test-linux-fuse"]
+fn fuse_read_only_both_publications() {
+    for publication in [Publication::Object, Publication::Service] {
+        read_only(&Fixture::new(publication));
+    }
+}
+
+fn names(path: &Path) -> std::collections::BTreeSet<String> {
+    fs::read_dir(path)
+        .unwrap_or_else(|error| panic!("read directory {}: {error}", path.display()))
+        .map(|entry| {
+            entry
+                .expect("read directory entry")
+                .file_name()
+                .into_string()
+                .expect("UTF-8 directory entry")
+        })
+        .collect()
+}
+
+fn inode(path: &Path) -> u64 {
+    fs::metadata(path)
+        .unwrap_or_else(|error| panic!("stat {}: {error}", path.display()))
+        .ino()
+}
+
+fn mode(path: &Path) -> u32 {
+    fs::metadata(path)
+        .unwrap_or_else(|error| panic!("stat mode {}: {error}", path.display()))
+        .permissions()
+        .mode()
+        & 0o7777
+}
+
+fn assert_staged_size(path: &Path, file: &File, expected: u64, phase: &str) {
+    let fd = file
+        .metadata()
+        .unwrap_or_else(|error| panic!("fstat {phase}: {error}"));
+    let by_path = fs::metadata(path).unwrap_or_else(|error| panic!("stat {phase}: {error}"));
+    assert_eq!(
+        by_path.ino(),
+        fd.ino(),
+        "{phase}: path lookup resolved a different inode"
+    );
+    assert_eq!(fd.len(), expected, "{phase}: fstat staged length");
+    assert_eq!(
+        by_path.len(),
+        expected,
+        "{phase}: path stat must use the same staged length"
+    );
+}
+
+fn wait_child(child: &mut Child, timeout: Duration) -> std::process::ExitStatus {
+    let deadline = Instant::now() + timeout;
+    loop {
+        if let Some(status) = child
+            .try_wait()
+            .unwrap_or_else(|error| panic!("wait for helper client: {error}"))
+        {
+            return status;
+        }
+        if Instant::now() >= deadline {
+            panic!(
+                "helper client did not exit within {timeout:?}; waiting while the service is paused is not allowed"
+            );
+        }
+        thread::sleep(Duration::from_millis(50));
+    }
+}
+
+fn wait_remote_bytes(
+    fixture: &Fixture,
+    library: &Path,
+    path: &str,
+    expected: &[u8],
+    timeout: Duration,
+) {
+    let deadline = Instant::now() + timeout;
+    loop {
+        if fixture.remote_read(library, path, 128) == expected {
+            return;
+        }
+        if Instant::now() >= deadline {
+            panic!("remote bytes did not reach the delayed completion within {timeout:?}");
+        }
+        thread::sleep(Duration::from_millis(200));
+    }
+}
+
+fn refresh_counts(line: &str) -> (u64, u64, u64) {
+    let fields = line
+        .split_once("done (")
+        .and_then(|(_, rest)| rest.trim().strip_suffix(')'))
+        .expect("refresh completion line has counts");
+    let mut inode = None;
+    let mut entries = None;
+    let mut errors = None;
+    for field in fields.split_whitespace() {
+        let (key, value) = field.split_once('=').expect("refresh count field");
+        let value = value.parse::<u64>().expect("numeric refresh count");
+        match key {
+            "inode" => inode = Some(value),
+            "entries" => entries = Some(value),
+            "errors" => errors = Some(value),
+            other => panic!("unexpected refresh count field {other}"),
+        }
+    }
+    (
+        inode.expect("inode count"),
+        entries.expect("entries count"),
+        errors.expect("errors count"),
+    )
+}
+
+#[test]
+#[ignore = "requires /dev/fuse and isolated S3; run with cargo x test-linux-fuse"]
+fn fuse_read_only_cached_readdir_and_nested_inodes_both_publications() {
+    for publication in [Publication::Object, Publication::Service] {
+        let fixture = Fixture::new(publication);
+        fixture.seed_read_only_tree();
+        let config = fixture.volume_config(
+            &format!("stage-readdir-{}", fixture.publication().as_str()),
+            Frontend::Fuse,
+            true,
+        );
+        let mountpoint = fixture
+            .temp
+            .path()
+            .join(format!("mnt-readdir-{}", fixture.publication().as_str()));
+        fs::create_dir(&mountpoint).expect("create mountpoint");
+        let mut mounted = fixture.mount(&config, &mountpoint);
+        let root = mounted.mountpoint();
+
+        let nested = root.join("nested");
+        let inner = nested.join("inner");
+        let file = inner.join("hello.txt");
+        assert_eq!(
+            fs::read(&file).expect("read nested file"),
+            b"hello from nested"
+        );
+        let nested_ino = inode(&nested);
+        let inner_ino = inode(&inner);
+        let file_ino = inode(&file);
+        assert_eq!(
+            inode(&nested),
+            nested_ino,
+            "nested inode changed across stat"
+        );
+        assert_eq!(
+            inode(&inner),
+            inner_ino,
+            "inner directory inode changed across stat"
+        );
+        assert_eq!(inode(&file), file_ino, "file inode changed across stat");
+
+        let root_first = names(root);
+        let root_second = names(root);
+        assert_eq!(root_first, root_second, "cached root readdir changed");
+        assert!(root_first.contains("nested"));
+        assert!(root_first.contains("bulk"));
+        assert!(root_first.contains("readonly.txt"));
+        let nested_first = names(&nested);
+        assert_eq!(
+            names(&nested),
+            nested_first,
+            "cached nested readdir changed"
+        );
+        let inner_first = names(&inner);
+        assert_eq!(inner_first.len(), 1);
+        assert!(inner_first.contains("hello.txt"));
+        assert_eq!(names(&inner), inner_first, "cached inner readdir changed");
+
+        let bulk = root.join("bulk");
+        assert_eq!(fs::read(bulk.join("entry-0000")).unwrap(), b"");
+        assert_eq!(
+            inode(&bulk.join("entry-0000")),
+            inode(&bulk.join("entry-0000"))
+        );
+        let bulk_first = names(&bulk);
+        let bulk_second = names(&bulk);
+        assert_eq!(bulk_first.len(), 520, "bulk directory entry count");
+        assert_eq!(bulk_first, bulk_second, "multi-page cached readdir changed");
+        for index in 0..520 {
+            assert!(
+                bulk_first.contains(&format!("entry-{index:04}")),
+                "missing bulk entry {index}"
+            );
+        }
+        mounted.unmount();
+    }
+}
+
+fn read_only(fixture: &Fixture) {
+    let library = fixture.volume_config(
+        &format!("lib-readonly-{}", fixture.publication().as_str()),
+        Frontend::Library,
+        false,
+    );
+    fixture.library_seed(&library, "readonly.txt", b"read-only bytes");
+    let config = fixture.volume_config(
+        &format!("stage-readonly-{}", fixture.publication().as_str()),
+        Frontend::Fuse,
+        true,
+    );
+    let mountpoint = fixture
+        .temp
+        .path()
+        .join(format!("mnt-readonly-{}", fixture.publication().as_str()));
+    fs::create_dir(&mountpoint).expect("create mountpoint");
+    let mut mounted = fixture.mount(&config, &mountpoint);
+
+    assert_eq!(
+        fs::read(mounted.mountpoint().join("readonly.txt")).expect("read mounted file"),
+        b"read-only bytes"
+    );
+    let write_existing = OpenOptions::new()
+        .write(true)
+        .open(mounted.mountpoint().join("readonly.txt"));
+    assert_errno(
+        write_existing.expect_err("read-only volume must reject a writable open"),
+        &[EROFS, EACCES, EPERM],
+        "read-only writable open",
+    );
+    let create_new = fs::write(mounted.mountpoint().join("new.txt"), b"x");
+    assert_errno(
+        create_new.expect_err("read-only volume must reject create"),
+        &[EROFS, EACCES, EPERM],
+        "read-only create",
+    );
+    let create_dir = fs::create_dir(mounted.mountpoint().join("new-dir"));
+    assert_errno(
+        create_dir.expect_err("read-only volume must reject mkdir"),
+        &[EROFS, EACCES, EPERM],
+        "read-only mkdir",
+    );
+    let rename = fs::rename(
+        mounted.mountpoint().join("readonly.txt"),
+        mounted.mountpoint().join("moved.txt"),
+    );
+    assert_errno(
+        rename.expect_err("read-only volume must reject rename"),
+        &[EROFS, EACCES, EPERM],
+        "read-only rename",
+    );
+    mounted.unmount();
+}
+
+#[test]
+#[ignore = "requires /dev/fuse and isolated S3; run with cargo x test-linux-fuse"]
+fn fuse_basic_io_both_publications() {
+    for publication in [Publication::Object, Publication::Service] {
+        basic_io(&Fixture::new(publication));
+    }
+}
+
+fn basic_io(fixture: &Fixture) {
+    let suffix = fixture.publication().as_str();
+    let library = fixture.volume_config(&format!("lib-basic-{suffix}"), Frontend::Library, false);
+    fixture.library_seed(&library, "basic.txt", b"initial");
+    let config = fixture.volume_config(&format!("stage-basic-{suffix}"), Frontend::Fuse, false);
+    let mountpoint = fixture.temp.path().join(format!("mnt-basic-{suffix}"));
+    fs::create_dir(&mountpoint).expect("create mountpoint");
+    let mut mounted = fixture.mount(&config, &mountpoint);
+    let root = mounted.mountpoint();
+
+    let mut file = OpenOptions::new()
+        .write(true)
+        .open(root.join("basic.txt"))
+        .expect("open mounted file for write");
+    file.write_all(b"hello!!").expect("write mounted file");
+    file.sync_all().expect("remote fsync through FUSE");
+    drop(file);
+    assert_eq!(
+        fixture.remote_read(&library, "basic.txt", 8),
+        b"hello!!",
+        "independent authority must observe a successful FUSE fsync"
+    );
+
+    let mut append = OpenOptions::new()
+        .append(true)
+        .open(root.join("basic.txt"))
+        .expect("open mounted file for append");
+    append.write_all(b"!").expect("append through FUSE");
+    append.sync_all().expect("remote fsync after append");
+    drop(append);
+    assert_eq!(fixture.remote_read(&library, "basic.txt", 8), b"hello!!!");
+
+    let truncate = OpenOptions::new()
+        .write(true)
+        .open(root.join("basic.txt"))
+        .expect("open mounted file for truncate");
+    truncate.set_len(3).expect("truncate through FUSE");
+    truncate.sync_all().expect("remote fsync after truncate");
+    drop(truncate);
+    assert_eq!(
+        fixture.remote_read(&library, "basic.txt", 8),
+        vec![b'h', b'e', b'l']
+    );
+
+    let mut created = File::create(root.join("created.txt")).expect("create through FUSE");
+    created.write_all(b"mount-created").expect("write new file");
+    created.sync_all().expect("remote fsync for new file");
+    drop(created);
+    assert_eq!(
+        fixture.remote_read(&library, "created.txt", 32),
+        b"mount-created"
+    );
+
+    let mut first = File::create(root.join("multi-fd.txt")).expect("create multi-fd file");
+    first.write_all(b"first").expect("write multi-fd file");
+    first.sync_all().expect("remote fsync multi-fd file");
+    drop(first);
+    let mut reader = File::open(root.join("multi-fd.txt")).expect("open multi-fd reader");
+    let mut writer = OpenOptions::new()
+        .write(true)
+        .open(root.join("multi-fd.txt"))
+        .expect("open multi-fd writer");
+    let mut initial = [0u8; 5];
+    reader.read_exact(&mut initial).expect("read initial");
+    assert_eq!(&initial, b"first");
+    writer
+        .seek(SeekFrom::Start(0))
+        .expect("seek multi-fd writer");
+    writer.write_all(b"X").expect("write through second fd");
+    drop(writer);
+    reader
+        .seek(SeekFrom::Start(0))
+        .expect("rewind multi-fd reader");
+    let mut updated = String::new();
+    reader
+        .read_to_string(&mut updated)
+        .expect("read updated bytes");
+    assert_eq!(
+        updated, "Xirst",
+        "an open reader must observe accepted writes"
+    );
+    drop(reader);
+    mounted.unmount();
+}
+
+#[test]
+#[ignore = "requires /dev/fuse and isolated S3; run with cargo x test-linux-fuse"]
+fn fuse_dirty_fd_readonly_close_keeps_remote_unchanged_both_publications() {
+    for publication in [Publication::Object, Publication::Service] {
+        let fixture = Fixture::new(publication);
+        let suffix = fixture.publication().as_str();
+        let library =
+            fixture.volume_config(&format!("lib-flush-{suffix}"), Frontend::Library, false);
+        fixture.library_seed(&library, "flush.txt", b"original");
+        let config = fixture.volume_config(&format!("stage-flush-{suffix}"), Frontend::Fuse, false);
+        let mountpoint = fixture.temp.path().join(format!("mnt-flush-{suffix}"));
+        fs::create_dir(&mountpoint).expect("create mountpoint");
+        let mut mounted = fixture.mount(&config, &mountpoint);
+
+        let mut dirty = OpenOptions::new()
+            .read(true)
+            .write(true)
+            .open(mounted.mountpoint().join("flush.txt"))
+            .expect("open write descriptor");
+        dirty.write_all(b"dirty!!!").expect("stage dirty bytes");
+        let mut reader =
+            File::open(mounted.mountpoint().join("flush.txt")).expect("open read-only descriptor");
+        let mut staged = Vec::new();
+        reader
+            .read_to_end(&mut staged)
+            .expect("read through the read-only descriptor");
+        assert_eq!(staged, b"dirty!!!");
+        drop(reader);
+        assert_eq!(
+            fixture.remote_read(&library, "flush.txt", 16),
+            b"original",
+            "closing a read-only descriptor must not publish another descriptor's dirty bytes"
+        );
+
+        let path = mounted.mountpoint().join("flush.txt");
+        assert_staged_size(&path, &dirty, 8, "same-length dirty write");
+        dirty.set_len(12).expect("grow the staged file");
+        thread::sleep(ATTR_TTL_WAIT);
+        assert_staged_size(&path, &dirty, 12, "dirty grow after attr TTL");
+        dirty.seek(SeekFrom::Start(0)).expect("rewind grown file");
+        let mut grown = Vec::new();
+        dirty
+            .read_to_end(&mut grown)
+            .expect("read grown staged bytes");
+        assert_eq!(grown, b"dirty!!!\0\0\0\0");
+        dirty.set_len(4).expect("shrink the staged file");
+        thread::sleep(ATTR_TTL_WAIT);
+        assert_staged_size(&path, &dirty, 4, "dirty shrink after attr TTL");
+        dirty.seek(SeekFrom::Start(0)).expect("rewind shrunk file");
+        let mut shrunk = Vec::new();
+        dirty
+            .read_to_end(&mut shrunk)
+            .expect("read shrunk staged bytes");
+        assert_eq!(shrunk, b"dirt");
+        dirty.sync_all().expect("explicit dirty fsync publishes");
+        drop(dirty);
+        assert_eq!(fixture.remote_read(&library, "flush.txt", 16), b"dirt");
+        mounted.unmount();
+    }
+}
+
+#[test]
+#[ignore = "requires /dev/fuse and isolated S3; run with cargo x test-linux-fuse"]
+fn fuse_cloexec_child_close_flushes_dirty_fd_both_publications() {
+    for publication in [Publication::Object, Publication::Service] {
+        let fixture = Fixture::new(publication);
+        let suffix = fixture.publication().as_str();
+        let library =
+            fixture.volume_config(&format!("lib-cloexec-{suffix}"), Frontend::Library, false);
+        fixture.library_seed(&library, "cloexec.txt", b"original");
+        let config =
+            fixture.volume_config(&format!("stage-cloexec-{suffix}"), Frontend::Fuse, false);
+        let mountpoint = fixture.temp.path().join(format!("mnt-cloexec-{suffix}"));
+        fs::create_dir(&mountpoint).expect("create mountpoint");
+        let mut mounted = fixture.mount(&config, &mountpoint);
+
+        let mut dirty = OpenOptions::new()
+            .read(true)
+            .write(true)
+            .open(mounted.mountpoint().join("cloexec.txt"))
+            .expect("open dirty descriptor");
+        dirty.write_all(b"dirty!!!").expect("stage dirty bytes");
+        assert_eq!(
+            fixture.remote_read(&library, "cloexec.txt", 16),
+            b"original",
+            "an in-process independent read must not close the dirty FUSE descriptor"
+        );
+        Command::new("/bin/true")
+            .status()
+            .expect("spawn a child that exec-closes the inherited dirty descriptor");
+        wait_remote_bytes(
+            &fixture,
+            &library,
+            "cloexec.txt",
+            b"dirty!!!",
+            Duration::from_secs(15),
+        );
+        drop(dirty);
+        mounted.unmount();
+    }
+}
+
+#[test]
+#[ignore = "requires /dev/fuse and isolated S3; run with cargo x test-linux-fuse"]
+fn fuse_append_flag_toggle_both_publications() {
+    for publication in [Publication::Object, Publication::Service] {
+        let fixture = Fixture::new(publication);
+        let suffix = fixture.publication().as_str();
+        let library =
+            fixture.volume_config(&format!("lib-append-{suffix}"), Frontend::Library, false);
+        fixture.library_seed(&library, "append-toggle.txt", b"0123456789");
+        let config =
+            fixture.volume_config(&format!("stage-append-{suffix}"), Frontend::Fuse, false);
+        let mountpoint = fixture.temp.path().join(format!("mnt-append-{suffix}"));
+        fs::create_dir(&mountpoint).expect("create mountpoint");
+        let mut mounted = fixture.mount(&config, &mountpoint);
+        let path = mounted.mountpoint().join("append-toggle.txt");
+
+        let mut file = OpenOptions::new()
+            .read(true)
+            .append(true)
+            .open(&path)
+            .expect("open with O_APPEND");
+        let flags = fcntl(&file, FcntlArg::F_GETFL).expect("read open flags");
+        let flags = OFlag::from_bits_truncate(flags);
+        assert!(flags.contains(OFlag::O_APPEND));
+        fcntl(&file, FcntlArg::F_SETFL(flags.difference(OFlag::O_APPEND)))
+            .expect("clear O_APPEND with fcntl");
+        file.seek(SeekFrom::Start(0))
+            .expect("seek after clearing O_APPEND");
+        file.write_all(b"AB")
+            .expect("write after clearing O_APPEND");
+        file.sync_all().expect("fsync overwrite without O_APPEND");
+        assert_eq!(
+            fixture.remote_read(&library, "append-toggle.txt", 16),
+            b"AB23456789",
+            "cleared O_APPEND must honor the explicit offset"
+        );
+
+        fcntl(&file, FcntlArg::F_SETFL(flags)).expect("restore O_APPEND with fcntl");
+        file.seek(SeekFrom::Start(0))
+            .expect("seek is ignored when O_APPEND is restored");
+        file.write_all(b"CD")
+            .expect("write after restoring O_APPEND");
+        file.sync_all().expect("fsync appended write");
+        assert_eq!(
+            fixture.remote_read(&library, "append-toggle.txt", 16),
+            b"AB23456789CD",
+            "restored O_APPEND must append at the current EOF"
+        );
+        drop(file);
+        mounted.unmount();
+    }
+}
+
+#[test]
+#[ignore = "requires /dev/fuse and isolated S3; run with cargo x test-linux-fuse"]
+fn fuse_path_truncate_commits_both_publications() {
+    for publication in [Publication::Object, Publication::Service] {
+        let fixture = Fixture::new(publication);
+        let suffix = fixture.publication().as_str();
+        let library =
+            fixture.volume_config(&format!("lib-truncate-{suffix}"), Frontend::Library, false);
+        fixture.library_seed(&library, "truncate.txt", b"0123456789");
+        let config =
+            fixture.volume_config(&format!("stage-truncate-{suffix}"), Frontend::Fuse, false);
+        let mountpoint = fixture.temp.path().join(format!("mnt-truncate-{suffix}"));
+        fs::create_dir(&mountpoint).expect("create mountpoint");
+        let mut mounted = fixture.mount(&config, &mountpoint);
+        let path = mounted.mountpoint().join("truncate.txt");
+
+        truncate(&path, 3).expect("truncate(2) shrink without an open descriptor");
+        assert_eq!(fs::metadata(&path).expect("stat truncated path").len(), 3);
+        assert_eq!(
+            fixture.remote_read(&library, "truncate.txt", 16),
+            b"012",
+            "a successful path truncate must have an explicit remote commit boundary"
+        );
+        truncate(&path, 6).expect("truncate(2) extend without an open descriptor");
+        assert_eq!(
+            fixture.remote_read(&library, "truncate.txt", 16),
+            vec![b'0', b'1', b'2', 0u8, 0u8, 0u8],
+            "path extension must also reach the independent authority"
+        );
+        mounted.unmount();
+    }
+}
+
+#[test]
+#[ignore = "requires /dev/fuse and isolated S3; run with cargo x test-linux-fuse"]
+fn fuse_chmod_limits_to_executable_bit_both_publications() {
+    for publication in [Publication::Object, Publication::Service] {
+        let fixture = Fixture::new(publication);
+        let suffix = fixture.publication().as_str();
+        let library =
+            fixture.volume_config(&format!("lib-chmod-{suffix}"), Frontend::Library, false);
+        fixture.library_seed(&library, "chmod.txt", b"mode");
+        let config = fixture.volume_config(&format!("stage-chmod-{suffix}"), Frontend::Fuse, false);
+        let mountpoint = fixture.temp.path().join(format!("mnt-chmod-{suffix}"));
+        fs::create_dir(&mountpoint).expect("create mountpoint");
+        let mut mounted = fixture.mount(&config, &mountpoint);
+        let path = mounted.mountpoint().join("chmod.txt");
+
+        fs::set_permissions(&path, fs::Permissions::from_mode(0o644)).expect("baseline chmod 0644");
+        assert_eq!(mode(&path), 0o644);
+        fs::set_permissions(&path, fs::Permissions::from_mode(0o755))
+            .expect("chmod 0755 must be representable");
+        assert_eq!(mode(&path), 0o755);
+        fs::set_permissions(&path, fs::Permissions::from_mode(0o644)).expect("chmod back to 0644");
+        assert_eq!(mode(&path), 0o644);
+
+        for unsupported_mode in [0o600, 0o000] {
+            let error = fs::set_permissions(&path, fs::Permissions::from_mode(unsupported_mode))
+                .expect_err("non-representable mode must fail explicitly");
+            assert_errno(
+                error,
+                &[ENOSYS, EOPNOTSUPP, EINVAL],
+                "chmod non-representable mode",
+            );
+            assert_eq!(
+                mode(&path),
+                0o644,
+                "failed chmod {unsupported_mode:o} must not change the previous attributes"
+            );
+        }
+
+        let directory = mounted.mountpoint().join("fixed-directory");
+        fs::create_dir(&directory).expect("create directory through the writable mount");
+        assert_eq!(mode(&directory), 0o755, "directories are fixed at 0755");
+        let error = fs::set_permissions(&directory, fs::Permissions::from_mode(0o644))
+            .expect_err("directory chmod 0644 must not report success");
+        assert_errno(error, &[ENOSYS, EOPNOTSUPP, EINVAL], "chmod directory 0644");
+        assert_eq!(
+            mode(&directory),
+            0o755,
+            "a rejected directory chmod must leave 0755 unchanged"
+        );
+        mounted.unmount();
+    }
+}
+
+#[test]
+#[ignore = "requires /dev/fuse and isolated S3; run with cargo x test-linux-fuse"]
+fn fuse_dirty_fd_and_executable_chmod_do_not_self_conflict_both_publications() {
+    for publication in [Publication::Object, Publication::Service] {
+        let fixture = Fixture::new(publication);
+        let suffix = fixture.publication().as_str();
+        let library = fixture.volume_config(
+            &format!("lib-chmod-dirty-{suffix}"),
+            Frontend::Library,
+            false,
+        );
+        fixture.library_seed(&library, "chmod-dirty.txt", b"base");
+        let config = fixture.volume_config(
+            &format!("stage-chmod-dirty-{suffix}"),
+            Frontend::Fuse,
+            false,
+        );
+        let mountpoint = fixture
+            .temp
+            .path()
+            .join(format!("mnt-chmod-dirty-{suffix}"));
+        fs::create_dir(&mountpoint).expect("create mountpoint");
+        let mut mounted = fixture.mount(&config, &mountpoint);
+        let path = mounted.mountpoint().join("chmod-dirty.txt");
+
+        let mut file = OpenOptions::new()
+            .read(true)
+            .write(true)
+            .open(&path)
+            .expect("open descriptor before chmod");
+        file.write_all(b"first").expect("stage first dirty write");
+        fs::set_permissions(&path, fs::Permissions::from_mode(0o755))
+            .expect("path chmod executable while the descriptor is dirty");
+        file.write_all(b"-tail")
+            .expect("continue writing through the same descriptor");
+        file.sync_all()
+            .expect("the mount's own metadata generation change must not self-conflict");
+        drop(file);
+        assert_eq!(mode(&path), 0o755);
+        assert_eq!(
+            fixture.remote_read(&library, "chmod-dirty.txt", 32),
+            b"first-tail",
+            "continued writes and executable metadata must publish together"
+        );
+        mounted.unmount();
+    }
+}
+
+#[test]
+#[ignore = "requires /dev/fuse and isolated S3; run with cargo x test-linux-fuse"]
+fn fuse_rename_replace_and_retained_unlink_both_publications() {
+    for publication in [Publication::Object, Publication::Service] {
+        rename_and_unlink(&Fixture::new(publication));
+    }
+}
+
+fn rename_and_unlink(fixture: &Fixture) {
+    let suffix = fixture.publication().as_str();
+    let library = fixture.volume_config(&format!("lib-rename-{suffix}"), Frontend::Library, false);
+    let config = fixture.volume_config(&format!("stage-rename-{suffix}"), Frontend::Fuse, false);
+    let mountpoint = fixture.temp.path().join(format!("mnt-rename-{suffix}"));
+    fs::create_dir(&mountpoint).expect("create mountpoint");
+    let mut mounted = fixture.mount(&config, &mountpoint);
+    let root = mounted.mountpoint();
+
+    let mut target = File::create(root.join("saved.txt")).expect("create rename target");
+    target.write_all(b"old").expect("write old target");
+    target.sync_all().expect("fsync rename target");
+    drop(target);
+    let mut temp = File::create(root.join("saved.txt.new")).expect("create rename source");
+    temp.write_all(b"new").expect("write rename source");
+    temp.sync_all().expect("fsync rename source");
+    drop(temp);
+    let source_inode = inode(&root.join("saved.txt.new"));
+    fs::rename(root.join("saved.txt.new"), root.join("renamed.txt"))
+        .expect("plain rename must preserve inode identity");
+    assert_eq!(
+        inode(&root.join("renamed.txt")),
+        source_inode,
+        "rename must not change the inode identity of the moved node"
+    );
+    fs::rename(root.join("renamed.txt"), root.join("saved.txt.new"))
+        .expect("rename back before safe-save");
+    let target_inode = inode(&root.join("saved.txt"));
+    fs::rename(root.join("saved.txt.new"), root.join("saved.txt"))
+        .expect("safe-save rename must atomically replace the target");
+    assert_eq!(
+        inode(&root.join("saved.txt")),
+        source_inode,
+        "safe-save replacement must keep the source identity"
+    );
+    assert_ne!(
+        target_inode, source_inode,
+        "safe-save replacement must replace the observed target node"
+    );
+    assert!(!root.join("saved.txt.new").exists());
+    assert_eq!(
+        fs::read(root.join("saved.txt")).expect("read replaced target"),
+        b"new"
+    );
+    assert_eq!(
+        fixture.remote_read(&library, "saved.txt", 8),
+        b"new",
+        "independent authority must observe the rename replacement"
+    );
+
+    let mut kept = File::create(root.join("retained.txt")).expect("create retained file");
+    kept.write_all(b"keep").expect("write retained file");
+    kept.sync_all().expect("fsync retained file");
+    drop(kept);
+    let mut open = File::open(root.join("retained.txt")).expect("open file before unlink");
+    fs::remove_file(root.join("retained.txt")).expect("unlink through FUSE");
+    let mut bytes = Vec::new();
+    open.read_to_end(&mut bytes)
+        .expect("read through an unlinked descriptor");
+    assert_eq!(bytes, b"keep", "retained unlink reads must keep bytes");
+    drop(open);
+    assert!(!root.join("retained.txt").exists());
+    mounted.unmount();
+}
+
+#[test]
+#[ignore = "requires /dev/fuse and isolated S3; run with cargo x test-linux-fuse"]
+fn fuse_unsupported_operations_both_publications() {
+    for publication in [Publication::Object, Publication::Service] {
+        unsupported_operations(&Fixture::new(publication));
+    }
+}
+
+fn unsupported_operations(fixture: &Fixture) {
+    let suffix = fixture.publication().as_str();
+    let config = fixture.volume_config(
+        &format!("stage-unsupported-{suffix}"),
+        Frontend::Fuse,
+        false,
+    );
+    let mountpoint = fixture
+        .temp
+        .path()
+        .join(format!("mnt-unsupported-{suffix}"));
+    fs::create_dir(&mountpoint).expect("create mountpoint");
+    let mut mounted = fixture.mount(&config, &mountpoint);
+    File::create(mounted.mountpoint().join("base.txt"))
+        .expect("create base file")
+        .sync_all()
+        .expect("fsync base file");
+
+    let symlink = std::os::unix::fs::symlink("base.txt", mounted.mountpoint().join("link"));
+    assert_errno(
+        symlink.expect_err("symlinks are not part of the YinYang contract and must be explicit"),
+        &[ENOSYS, EOPNOTSUPP, EPERM, EACCES],
+        "symlink",
+    );
+    let hardlink = fs::hard_link(
+        mounted.mountpoint().join("base.txt"),
+        mounted.mountpoint().join("hard"),
+    );
+    assert_errno(
+        hardlink.expect_err("hard links are not part of the YinYang contract and must be explicit"),
+        &[ENOSYS, EOPNOTSUPP, EPERM, EACCES],
+        "hard link",
+    );
+    mounted.unmount();
+}
+
+#[test]
+#[ignore = "requires /dev/fuse and isolated S3; run with cargo x test-linux-fuse"]
+fn fuse_external_changes_and_dirty_refresh_both_publications() {
+    for publication in [Publication::Object, Publication::Service] {
+        external_changes(&Fixture::new(publication));
+    }
+}
+
+fn external_changes(fixture: &Fixture) {
+    let suffix = fixture.publication().as_str();
+    let library =
+        fixture.volume_config(&format!("lib-external-{suffix}"), Frontend::Library, false);
+    fixture.library_seed(&library, "external.txt", b"AAAA");
+    fixture.library_seed(&library, "shrink.txt", b"0123456789");
+    fixture.library_seed(&library, "dirty.txt", b"BBBBBBBB");
+    let config = fixture.volume_config(&format!("stage-external-{suffix}"), Frontend::Fuse, false);
+    let mountpoint = fixture.temp.path().join(format!("mnt-external-{suffix}"));
+    fs::create_dir(&mountpoint).expect("create mountpoint");
+    let mut mounted = fixture.mount(&config, &mountpoint);
+
+    let mut old = File::open(mounted.mountpoint().join("external.txt"))
+        .expect("open descriptor before external growth");
+    let mut initial = Vec::new();
+    old.read_to_end(&mut initial).expect("read original bytes");
+    assert_eq!(initial, b"AAAA");
+    assert_eq!(old.metadata().expect("stat original").len(), 4);
+    fixture.remote_write(&library, "external.txt", b"BBBBBBBB");
+    assert_eq!(
+        fixture.remote_read(&library, "external.txt", 16),
+        b"BBBBBBBB",
+        "independent external growth must be authoritative"
+    );
+    thread::sleep(ATTR_TTL_WAIT);
+    assert_staged_size(
+        &mounted.mountpoint().join("external.txt"),
+        &old,
+        4,
+        "external growth with a retained descriptor",
+    );
+    assert_eq!(
+        old.metadata().expect("stat old descriptor").len(),
+        4,
+        "external growth must not resize a descriptor that was opened before the change"
+    );
+    let mut beyond_old_eof = [0u8; 4];
+    let count = old
+        .read_at(&mut beyond_old_eof, 4)
+        .expect("pread beyond the old EOF");
+    assert_eq!(
+        count, 0,
+        "pread past the old EOF must not leak bytes from the externally grown file"
+    );
+    drop(old);
+    let mut fresh = File::open(mounted.mountpoint().join("external.txt"))
+        .expect("reopen externally grown file on the live mount");
+    let mut fresh_bytes = Vec::new();
+    fresh
+        .read_to_end(&mut fresh_bytes)
+        .expect("read externally grown file on the live mount");
+    assert_eq!(fresh_bytes, b"BBBBBBBB");
+    assert_eq!(
+        fresh.metadata().expect("fstat fresh grow").len(),
+        8,
+        "fresh open must materialize the external grow length"
+    );
+    drop(fresh);
+
+    let dirty_path = mounted.mountpoint().join("dirty.txt");
+    let mut dirty = OpenOptions::new()
+        .read(true)
+        .write(true)
+        .open(&dirty_path)
+        .expect("open file for dirty write");
+    dirty.write_all(b"LOCAL").expect("stage dirty write");
+    fixture.remote_write(&library, "dirty.txt", b"ZZZZZZZZZZ");
+    dirty.seek(SeekFrom::Start(0)).expect("rewind dirty file");
+    let mut local = Vec::new();
+    dirty
+        .read_to_end(&mut local)
+        .expect("read dirty staged bytes");
+    assert_eq!(
+        local, b"LOCALBBB",
+        "an external change must not silently rebase a dirty descriptor"
+    );
+    let conflict = dirty.sync_all();
+    assert!(
+        conflict.is_err(),
+        "fsync of a stale dirty base must report failure instead of claiming remote durability"
+    );
+    drop(dirty);
+    mounted.unmount();
+
+    let config = fixture.volume_config(&format!("stage-external-{suffix}"), Frontend::Fuse, false);
+    let mountpoint = fixture
+        .temp
+        .path()
+        .join(format!("mnt-external-reopen-{suffix}"));
+    fs::create_dir(&mountpoint).expect("create reopen mountpoint");
+    let mut reopen = fixture.mount(&config, &mountpoint);
+    let mut old_shrink = File::open(reopen.mountpoint().join("shrink.txt"))
+        .expect("open descriptor before external shrink");
+    let mut before = Vec::new();
+    old_shrink
+        .read_to_end(&mut before)
+        .expect("read original shrink file");
+    assert_eq!(before, b"0123456789");
+    assert_eq!(old_shrink.metadata().expect("stat original").len(), 10);
+    fixture.remote_truncate(&library, "shrink.txt", 4);
+    thread::sleep(ATTR_TTL_WAIT);
+    assert_staged_size(
+        &reopen.mountpoint().join("shrink.txt"),
+        &old_shrink,
+        10,
+        "external shrink with a retained descriptor",
+    );
+    assert_eq!(
+        old_shrink.metadata().expect("stat old descriptor").len(),
+        10,
+        "external shrink must not resize a descriptor that was opened before the change"
+    );
+    let mut tail = [0u8; 2];
+    let count = old_shrink
+        .read_at(&mut tail, 8)
+        .expect("pread within the old EOF");
+    assert_eq!(
+        count,
+        tail.len(),
+        "pread at the old EOF must still return pinned bytes"
+    );
+    assert_eq!(&tail, b"89");
+    drop(old_shrink);
+    let mut fresh_shrink = File::open(reopen.mountpoint().join("shrink.txt"))
+        .expect("reopen externally shrunk file on the live mount");
+    let mut fresh_shrink_bytes = Vec::new();
+    fresh_shrink
+        .read_to_end(&mut fresh_shrink_bytes)
+        .expect("read externally shrunk file on the live mount");
+    assert_eq!(fresh_shrink_bytes, b"0123");
+    assert_eq!(
+        fresh_shrink.metadata().expect("fstat fresh shrink").len(),
+        4,
+        "fresh open must materialize the external shrink length"
+    );
+    drop(fresh_shrink);
+    reopen.unmount();
+
+    let mountpoint = fixture
+        .temp
+        .path()
+        .join(format!("mnt-external-final-{suffix}"));
+    fs::create_dir(&mountpoint).expect("create final mountpoint");
+    let mut final_mount = fixture.mount(&config, &mountpoint);
+    assert_eq!(
+        final_mount
+            .mountpoint()
+            .join("shrink.txt")
+            .metadata()
+            .expect("stat externally shrunk file")
+            .len(),
+        4
+    );
+    assert_eq!(
+        fs::read(final_mount.mountpoint().join("shrink.txt")).expect("read externally shrunk file"),
+        b"0123"
+    );
+    final_mount.unmount();
+}
+
+#[test]
+#[ignore = "requires /dev/fuse and isolated S3; run with cargo x test-linux-fuse"]
+fn fuse_sighup_refreshes_namespace_without_rebasing_old_fd_both_publications() {
+    for publication in [Publication::Object, Publication::Service] {
+        let fixture = Fixture::new(publication);
+        let suffix = fixture.publication().as_str();
+        let library =
+            fixture.volume_config(&format!("lib-sighup-{suffix}"), Frontend::Library, false);
+        fixture.library_seed(&library, "a.txt", b"old-content");
+        let config =
+            fixture.volume_config(&format!("stage-sighup-{suffix}"), Frontend::Fuse, false);
+        let mountpoint = fixture.temp.path().join(format!("mnt-sighup-{suffix}"));
+        fs::create_dir(&mountpoint).expect("create mountpoint");
+        let mut mounted = fixture.mount(&config, &mountpoint);
+        let root = mounted.mountpoint().to_path_buf();
+
+        let old_path = root.join("a.txt");
+        let mut old = File::open(&old_path).expect("open old descriptor before refresh");
+        let old_ino = inode(&old_path);
+        let old_len = fs::metadata(&old_path).expect("warm old dentry").len();
+        let mut old_bytes = Vec::new();
+        old.read_to_end(&mut old_bytes).expect("read old bytes");
+        assert_eq!(old_bytes, b"old-content");
+
+        let new_payload = b"new-content-longer";
+        fixture.remote_rename(&library, "a.txt", "b.txt");
+        fixture.remote_write(&library, "b.txt", new_payload);
+        fixture.remote_create(&library, "new.txt");
+        fixture.remote_write(&library, "new.txt", b"added");
+
+        mounted.refresh_sighup();
+        let refresh_log =
+            mounted.wait_for_output_line("yy: fuse refresh: done (", Duration::from_secs(30));
+        let completion = refresh_log
+            .lines()
+            .find(|line| line.contains("yy: fuse refresh: done ("))
+            .expect("refresh completion line");
+        let (inode_count, entry_count, error_count) = refresh_counts(completion);
+        assert!(
+            inode_count > 0 && entry_count > 0 && error_count == 0,
+            "refresh must acknowledge native notifications (inode={inode_count} \
+             entries={entry_count} errors={error_count}):\n{refresh_log}"
+        );
+
+        assert_errno(
+            fs::metadata(&old_path).expect_err("renamed source must disappear after SIGHUP"),
+            &[ENOENT],
+            "stat renamed source after SIGHUP",
+        );
+        let shared = fs::metadata(root.join("b.txt")).expect("stat renamed target after SIGHUP");
+        assert_eq!(shared.ino(), old_ino);
+        assert_eq!(shared.len(), old_len);
+        assert_eq!(
+            fs::read(root.join("b.txt")).expect("read renamed target after SIGHUP"),
+            b"old-content",
+            "the live mount keeps the shared pinned view while the old descriptor is active"
+        );
+        assert_eq!(
+            fixture.remote_read(&library, "b.txt", 32),
+            new_payload,
+            "the independent authority sees the externally updated target"
+        );
+        assert_eq!(
+            fs::read(root.join("new.txt")).expect("read externally added file after SIGHUP"),
+            b"added"
+        );
+        assert_eq!(old.metadata().expect("fstat old descriptor").ino(), old_ino);
+        assert_eq!(old.metadata().expect("fstat old descriptor").len(), old_len);
+        old.seek(SeekFrom::Start(0)).expect("rewind old descriptor");
+        let mut pinned = Vec::new();
+        old.read_to_end(&mut pinned)
+            .expect("read old descriptor after SIGHUP");
+        assert_eq!(pinned, b"old-content");
+        drop(old);
+
+        let mut fresh = File::open(root.join("b.txt")).expect("fresh open after old close");
+        let mut fresh_bytes = Vec::new();
+        fresh
+            .read_to_end(&mut fresh_bytes)
+            .expect("fresh read after old close");
+        assert_eq!(fresh_bytes, new_payload);
+        assert_eq!(
+            fresh.metadata().expect("fresh fstat after old close").len(),
+            new_payload.len() as u64
+        );
+        drop(fresh);
+        mounted.unmount();
+    }
+}
+
+#[test]
+#[ignore = "requires /dev/fuse and isolated S3; run with cargo x test-linux-fuse"]
+fn fuse_concurrent_mounts_object() {
+    let fixture = Fixture::new(Publication::Object);
+    let library = fixture.volume_config("lib-concurrent", Frontend::Library, false);
+    let config_a = fixture.volume_config("stage-concurrent-a", Frontend::Fuse, false);
+    let config_b = fixture.volume_config("stage-concurrent-b", Frontend::Fuse, false);
+    let mount_a = fixture.temp.path().join("mnt-concurrent-a");
+    let mount_b = fixture.temp.path().join("mnt-concurrent-b");
+    fs::create_dir(&mount_a).expect("create mount A");
+    fs::create_dir(&mount_b).expect("create mount B");
+    let mut a = fixture.mount(&config_a, &mount_a);
+    let mut b = fixture.mount(&config_b, &mount_b);
+
+    let path_a = a.mountpoint().join("from-a.txt");
+    let path_b = b.mountpoint().join("from-b.txt");
+    let (ready_tx, ready_rx) = mpsc::channel::<Result<(), String>>();
+    let (go_a_tx, go_a_rx) = mpsc::channel();
+    let (go_b_tx, go_b_rx) = mpsc::channel();
+    let ready_a = ready_tx.clone();
+    let writer_a = thread::spawn(move || {
+        let prepared = (|| -> std::io::Result<File> {
+            let mut file = File::create(&path_a)?;
+            file.write_all(b"a")?;
+            Ok(file)
+        })();
+        match prepared {
+            Ok(file) => {
+                ready_a
+                    .send(Ok(()))
+                    .expect("send mount A preparation barrier");
+                let _ = go_a_rx.recv();
+                file.sync_all()
+            }
+            Err(error) => {
+                let _ = ready_a.send(Err(format!("mount A prepare failed: {error}")));
+                Err(error)
+            }
+        }
+    });
+    let ready_b = ready_tx;
+    let writer_b = thread::spawn(move || {
+        let prepared = (|| -> std::io::Result<File> {
+            let mut file = File::create(&path_b)?;
+            file.write_all(b"b")?;
+            Ok(file)
+        })();
+        match prepared {
+            Ok(file) => {
+                ready_b
+                    .send(Ok(()))
+                    .expect("send mount B preparation barrier");
+                let _ = go_b_rx.recv();
+                file.sync_all()
+            }
+            Err(error) => {
+                let _ = ready_b.send(Err(format!("mount B prepare failed: {error}")));
+                Err(error)
+            }
+        }
+    });
+    let first = ready_rx
+        .recv_timeout(Duration::from_secs(60))
+        .expect("mount A did not reach its preparation barrier");
+    let second = ready_rx
+        .recv_timeout(Duration::from_secs(60))
+        .expect("mount B did not reach its preparation barrier");
+    let _ = go_a_tx.send(());
+    let _ = go_b_tx.send(());
+    let result_a = writer_a.join().expect("mount A writer panicked");
+    let result_b = writer_b.join().expect("mount B writer panicked");
+    assert!(first.is_ok(), "{first:?}");
+    assert!(second.is_ok(), "{second:?}");
+    result_a.expect("fsync via mount A");
+    result_b.expect("fsync via mount B");
+
+    assert_eq!(
+        fs::read(a.mountpoint().join("from-b.txt")).expect("cross read"),
+        b"b"
+    );
+    assert_eq!(
+        fs::read(b.mountpoint().join("from-a.txt")).expect("cross read"),
+        b"a"
+    );
+    assert_eq!(fixture.remote_read(&library, "from-a.txt", 8), b"a");
+    assert_eq!(fixture.remote_read(&library, "from-b.txt", 8), b"b");
+    a.unmount();
+    b.unmount();
+}
+
+#[test]
+#[ignore = "requires /dev/fuse and isolated S3; run with cargo x test-linux-fuse"]
+fn fuse_process_kill_recovery_object() {
+    let fixture = Fixture::new(Publication::Object);
+    let library = fixture.volume_config("lib-kill", Frontend::Library, false);
+    fixture.library_seed(&library, "recover.txt", b"seed");
+    let config = fixture.volume_config("stage-kill", Frontend::Fuse, false);
+    let mountpoint = fixture.temp.path().join("mnt-kill");
+    fs::create_dir(&mountpoint).expect("create mountpoint");
+    let mut mounted = fixture.mount(&config, &mountpoint);
+
+    let mut dirty = OpenOptions::new()
+        .write(true)
+        .open(mounted.mountpoint().join("recover.txt"))
+        .expect("open file for staged write");
+    dirty.write_all(b"dirty-local").expect("stage dirty write");
+    assert_eq!(
+        fixture.remote_read(&library, "recover.txt", 64),
+        b"seed",
+        "an un-fsynced mounted write must not publish before the daemon is interrupted"
+    );
+    mounted.kill_daemon_only();
+    drop(dirty);
+    mounted.cleanup_after_kill();
+
+    let mountpoint = fixture.temp.path().join("mnt-kill-reopen");
+    fs::create_dir(&mountpoint).expect("create reopen mountpoint");
+    let mut reopened = fixture.mount(&config, &mountpoint);
+    assert_eq!(
+        fs::read(reopened.mountpoint().join("recover.txt")).expect("read recovered staging"),
+        b"dirty-local",
+        "a killed mount process must recover staged bytes from persistent staging"
+    );
+    let publish = OpenOptions::new()
+        .write(true)
+        .open(reopened.mountpoint().join("recover.txt"))
+        .expect("reopen recovered file");
+    publish.sync_all().expect("recovered handle publishes");
+    drop(publish);
+    assert_eq!(
+        fixture.remote_read(&library, "recover.txt", 64),
+        b"dirty-local",
+        "independent authority must observe the recovered publication"
+    );
+    reopened.unmount();
+}
+
+#[test]
+#[ignore = "requires /dev/fuse and isolated S3; run with cargo x test-linux-fuse"]
+fn fuse_fsync_failure_retention_service() {
+    let mut fixture = Fixture::new(Publication::Service);
+    let library = fixture.volume_config("lib-network", Frontend::Library, false);
+    fixture.library_seed(&library, "network.txt", b"seed");
+    let config = fixture.volume_config("stage-network", Frontend::Fuse, false);
+    let mountpoint = fixture.temp.path().join("mnt-network");
+    fs::create_dir(&mountpoint).expect("create mountpoint");
+    let mut mounted = fixture.mount(&config, &mountpoint);
+
+    let mut dirty = OpenOptions::new()
+        .read(true)
+        .write(true)
+        .open(mounted.mountpoint().join("network.txt"))
+        .expect("open file for staged write");
+    dirty.write_all(b"survives").expect("stage dirty write");
+    fixture.stop_service();
+    let failure = sync_all_with_deadline(&dirty, Duration::from_secs(20));
+    assert!(
+        failure.is_err(),
+        "fsync must fail while the metadata service is unavailable"
+    );
+    dirty.seek(SeekFrom::Start(0)).expect("rewind dirty file");
+    let mut retained = Vec::new();
+    dirty
+        .read_to_end(&mut retained)
+        .expect("read retained dirty bytes");
+    assert_eq!(
+        retained, b"survives",
+        "a failed fsync must not discard staged bytes"
+    );
+    mounted.kill_daemon_only();
+    drop(dirty);
+    mounted.cleanup_after_kill();
+
+    fixture.restart_service();
+    let mountpoint = fixture.temp.path().join("mnt-network-reopen");
+    fs::create_dir(&mountpoint).expect("create reopen mountpoint");
+    let mut reopened = fixture.mount(&config, &mountpoint);
+    assert_eq!(
+        fs::read(reopened.mountpoint().join("network.txt")).expect("read staged recovery"),
+        b"survives"
+    );
+    let publish = OpenOptions::new()
+        .write(true)
+        .open(reopened.mountpoint().join("network.txt"))
+        .expect("reopen recovered file");
+    publish.sync_all().expect("recovered handle publishes");
+    drop(publish);
+    assert_eq!(
+        fixture.remote_read(&library, "network.txt", 64),
+        b"survives"
+    );
+    reopened.unmount();
+}
+
+#[test]
+#[ignore = "requires /dev/fuse and isolated S3; run with cargo x test-linux-fuse"]
+fn fuse_daemon_crash_interrupts_pending_fsync_service() {
+    let fixture = Fixture::new(Publication::Service);
+    let library = fixture.volume_config("lib-interrupted", Frontend::Library, false);
+    fixture.library_seed(&library, "interrupted.txt", b"seed");
+    let staging = fixture.temp.path().join("stage-interrupted");
+    let gate = ServiceGate::new(staging, fixture.service_address());
+    let config = fixture.volume_config_with_service(
+        "stage-interrupted",
+        Frontend::Fuse,
+        false,
+        Some(gate.address()),
+    );
+    let mountpoint = fixture.temp.path().join("mnt-interrupted");
+    fs::create_dir(&mountpoint).expect("create mountpoint");
+    let mounted = fixture.mount(&config, &mountpoint);
+    interrupt_pending_fsync(&fixture, &library, &config, mounted, &gate, Interrupt::Kill);
+}
+
+#[test]
+#[ignore = "requires /dev/fuse and isolated S3; run with cargo x test-linux-fuse"]
+fn fuse_sigterm_pending_fsync_service_exits_after_grace() {
+    let fixture = Fixture::new(Publication::Service);
+    let library = fixture.volume_config("lib-sigterm-fsync", Frontend::Library, false);
+    fixture.library_seed(&library, "interrupted.txt", b"seed");
+    let staging = fixture.temp.path().join("stage-sigterm-fsync");
+    let gate = ServiceGate::new(staging, fixture.service_address());
+    let config = fixture.volume_config_with_service(
+        "stage-sigterm-fsync",
+        Frontend::Fuse,
+        false,
+        Some(gate.address()),
+    );
+    let mountpoint = fixture.temp.path().join("mnt-sigterm-fsync");
+    fs::create_dir(&mountpoint).expect("create mountpoint");
+    let mounted = fixture.mount(&config, &mountpoint);
+    interrupt_pending_fsync(
+        &fixture,
+        &library,
+        &config,
+        mounted,
+        &gate,
+        Interrupt::Terminate,
+    );
+}
+
+fn interrupt_pending_fsync(
+    fixture: &Fixture,
+    library: &Path,
+    config: &Path,
+    mut mounted: Mounted,
+    gate: &ServiceGate,
+    interrupt: Interrupt,
+) {
+    let mut dirty = OpenOptions::new()
+        .read(true)
+        .write(true)
+        .open(mounted.mountpoint().join("interrupted.txt"))
+        .expect("open file for staged write");
+    dirty
+        .write_all(b"interrupted-local")
+        .expect("stage dirty write");
+    let in_flight = dirty.try_clone().expect("duplicate descriptor");
+    let (sender, receiver) = mpsc::channel();
+    let caller = thread::spawn(move || {
+        let _ = sender.send(in_flight.sync_all());
+    });
+    gate.wait_ready(Duration::from_secs(30));
+    let frozen = fixture.wait_for_frozen(config);
+    println!("fsync reached the frozen publication boundary:\n{frozen}");
+    match interrupt {
+        Interrupt::Kill => mounted.kill_daemon_only(),
+        Interrupt::Terminate => {
+            let status = mounted.terminate_busy();
+            assert!(
+                !status.success(),
+                "SIGTERM with a pending fsync must force a non-zero exit after grace"
+            );
+        }
+    }
+    assert_eq!(
+        fixture.remote_read(library, "interrupted.txt", 64),
+        b"seed",
+        "the authority must remain unchanged while the frozen commit connection is gated"
+    );
+    gate.release();
+    let outcome = receiver
+        .recv_timeout(Duration::from_secs(20))
+        .unwrap_or_else(|error| {
+            panic!("fsync did not return after the mount daemon stopped: {error}")
+        });
+    caller.join().expect("fsync caller panicked");
+    assert!(
+        outcome.is_err(),
+        "an fsync interrupted by stopping the mount daemon must fail, not report remote durability"
+    );
+    drop(dirty);
+    mounted.cleanup_after_kill();
+
+    let mountpoint = fixture.temp.path().join(format!(
+        "mnt-interrupted-reopen-{}",
+        fixture.publication().as_str()
+    ));
+    fs::create_dir(&mountpoint).expect("create reopen mountpoint");
+    let mut reopened = fixture.mount(config, &mountpoint);
+    assert_eq!(
+        fs::read(reopened.mountpoint().join("interrupted.txt")).expect("read staged recovery"),
+        b"interrupted-local"
+    );
+    let publish = OpenOptions::new()
+        .write(true)
+        .open(reopened.mountpoint().join("interrupted.txt"))
+        .expect("reopen recovered file");
+    publish.sync_all().expect("recovered handle publishes");
+    drop(publish);
+    assert_eq!(
+        fixture.remote_read(library, "interrupted.txt", 64),
+        b"interrupted-local"
+    );
+    reopened.unmount();
+}
+
+#[test]
+#[ignore = "requires /dev/fuse and isolated S3; run with cargo x test-linux-fuse"]
+fn fuse_delayed_completion_survives_client_interruption_service() {
+    let fixture = Fixture::new(Publication::Service);
+    let library = fixture.volume_config("lib-delayed", Frontend::Library, false);
+    fixture.library_seed(&library, "delayed.txt", b"seed");
+    let staging = fixture.temp.path().join("stage-delayed");
+    let gate = ServiceGate::new(staging, fixture.service_address());
+    let config = fixture.volume_config_with_service(
+        "stage-delayed",
+        Frontend::Fuse,
+        false,
+        Some(gate.address()),
+    );
+    let mountpoint = fixture.temp.path().join("mnt-delayed");
+    fs::create_dir(&mountpoint).expect("create mountpoint");
+    let mut mounted = fixture.mount(&config, &mountpoint);
+    let path = mounted.mountpoint().join("delayed.txt");
+
+    let script = Path::new(env!("CARGO_MANIFEST_DIR")).join("tests/linux_fuse/delayed_client.py");
+    let mut client = Command::new("python3")
+        .arg(script)
+        .arg(&path)
+        .stdin(Stdio::piped())
+        .stdout(Stdio::piped())
+        .stderr(Stdio::piped())
+        .spawn()
+        .expect("spawn delayed completion client");
+    let stdout = client.stdout.take().expect("client stdout is piped");
+    let (sender, receiver) = mpsc::channel();
+    let reader = thread::spawn(move || {
+        let mut line = String::new();
+        if BufReader::new(stdout).read_line(&mut line).is_ok() {
+            let _ = sender.send(line);
+        }
+    });
+    let line = receiver
+        .recv_timeout(Duration::from_secs(30))
+        .unwrap_or_else(|error| panic!("client did not reach its write barrier: {error}"));
+    assert_eq!(line.trim(), "READY", "unexpected client barrier: {line:?}");
+
+    client
+        .stdin
+        .as_mut()
+        .expect("client stdin is piped")
+        .write_all(b"FSYNC\n")
+        .expect("send fsync command");
+    gate.wait_ready(Duration::from_secs(30));
+    let frozen = fixture.wait_for_frozen(&config);
+    println!("delayed fsync reached the frozen publication boundary:\n{frozen}");
+    client.kill().expect("SIGKILL the blocked client");
+    gate.release();
+    let _ = wait_child(&mut client, Duration::from_secs(30));
+    let _ = reader.join();
+
+    wait_remote_bytes(
+        &fixture,
+        &library,
+        "delayed.txt",
+        b"delayed-payload",
+        Duration::from_secs(60),
+    );
+    assert!(
+        names(mounted.mountpoint()).contains("delayed.txt"),
+        "the daemon must remain available after delayed completion"
+    );
+    mounted.unmount();
+}
+
+#[test]
+#[ignore = "requires /dev/fuse and isolated S3; run with cargo x test-linux-fuse"]
+fn fuse_sigterm_with_open_fd_exits_and_releases_lease_both_publications() {
+    for publication in [Publication::Object, Publication::Service] {
+        let fixture = Fixture::new(publication);
+        let suffix = fixture.publication().as_str();
+        let library = fixture.volume_config(
+            &format!("lib-sigterm-open-{suffix}"),
+            Frontend::Library,
+            false,
+        );
+        fixture.library_seed(&library, "sigterm-open.txt", b"seed");
+        let config = fixture.volume_config(
+            &format!("stage-sigterm-open-{suffix}"),
+            Frontend::Fuse,
+            false,
+        );
+        let mountpoint = fixture
+            .temp
+            .path()
+            .join(format!("mnt-sigterm-open-{suffix}"));
+        fs::create_dir(&mountpoint).expect("create mountpoint");
+        let mut mounted = fixture.mount(&config, &mountpoint);
+        let path = mounted.mountpoint().join("sigterm-open.txt");
+        let mut held = File::open(&path).expect("hold a descriptor across SIGTERM");
+        let status = mounted.terminate_busy();
+        assert!(
+            !status.success(),
+            "SIGTERM with an open descriptor must exit through the forced non-zero path"
+        );
+        let mut after = Vec::new();
+        let error = held
+            .read_to_end(&mut after)
+            .expect_err("a held descriptor must report an I/O error after daemon exit");
+        assert_errno(error, &[ENOTCONN, EIO], "read after busy SIGTERM");
+        drop(held);
+        mounted.cleanup_after_kill();
+
+        let mountpoint = fixture
+            .temp
+            .path()
+            .join(format!("mnt-sigterm-open-reopen-{suffix}"));
+        fs::create_dir(&mountpoint).expect("create reopen mountpoint");
+        let mut reopened = fixture.mount(&config, &mountpoint);
+        assert_eq!(
+            fs::read(reopened.mountpoint().join("sigterm-open.txt"))
+                .expect("read after SIGTERM remount"),
+            b"seed"
+        );
+        reopened.unmount();
+    }
+}
+
+#[test]
+#[ignore = "requires /dev/fuse and isolated S3; run with cargo x test-linux-fuse"]
+fn fuse_busy_unmount_object() {
+    let fixture = Fixture::new(Publication::Object);
+    let config = fixture.volume_config("stage-busy", Frontend::Fuse, false);
+    let mountpoint = fixture.temp.path().join("mnt-busy");
+    fs::create_dir(&mountpoint).expect("create mountpoint");
+    let mut mounted = fixture.mount(&config, &mountpoint);
+
+    let file = File::create(mounted.mountpoint().join("held.txt")).expect("create held file");
+    let mountpoint = mounted.mountpoint().to_str().expect("UTF-8 mountpoint");
+    let output = run_external("fusermount3", &["-u", mountpoint], Duration::from_secs(30));
+    assert!(
+        !output.status.success(),
+        "busy unmount unexpectedly succeeded while a descriptor was open: {}",
+        String::from_utf8_lossy(&output.stderr)
+    );
+    drop(file);
+    mounted.unmount();
+}
+
+#[test]
+#[ignore = "requires /dev/fuse and isolated S3; run with cargo x test-linux-fuse"]
+fn fuse_sigterm_lifecycle_object() {
+    let fixture = Fixture::new(Publication::Object);
+    let config = fixture.volume_config("stage-sigterm", Frontend::Fuse, false);
+    let mountpoint = fixture.temp.path().join("mnt-sigterm");
+    fs::create_dir(&mountpoint).expect("create mountpoint");
+    let mut mounted = fixture.mount(&config, &mountpoint);
+    mounted.terminate();
+}
diff --git a/tests/linux_fuse/delayed_client.py b/tests/linux_fuse/delayed_client.py
new file mode 100644
index 0000000..9502deb
--- /dev/null
+++ b/tests/linux_fuse/delayed_client.py
@@ -0,0 +1,31 @@
+#!/usr/bin/env python3
+# Apache-2.0 licensed helper for delayed FUSE completion acceptance.
+#
+# The parent uses the READY line as a barrier after the client's write is
+# accepted, then tells this process to fsync. SIGKILL of this process must not
+# cancel the already-sent FUSE request because the adapter replies ENOSYS to
+# FUSE_INTERRUPT; the daemon is expected to complete it after service recovery.
+
+import os
+import sys
+
+
+def main() -> None:
+    path = sys.argv[1]
+    fd = os.open(path, os.O_RDWR)
+    payload = b"delayed-payload"
+    view = memoryview(payload)
+    written = 0
+    while written < len(view):
+        written += os.write(fd, view[written:])
+    print("READY", flush=True)
+    line = sys.stdin.readline()
+    if line.strip() != "FSYNC":
+        raise RuntimeError(f"unexpected parent command: {line!r}")
+    os.fsync(fd)
+    print("FSYNCED", flush=True)
+    os.close(fd)
+
+
+if __name__ == "__main__":
+    main()
diff --git a/tests/linux_fuse/harness.rs b/tests/linux_fuse/harness.rs
new file mode 100644
index 0000000..9a804d1
--- /dev/null
+++ b/tests/linux_fuse/harness.rs
@@ -0,0 +1,1144 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+//! Harness for real Linux FUSE acceptance against the yy CLI.
+
+use nix::sys::signal::{Signal, kill};
+use nix::unistd::Pid;
+use std::fs;
+use std::io::{BufRead, BufReader, Read};
+use std::net::{SocketAddr, TcpListener, TcpStream};
+use std::path::{Path, PathBuf};
+use std::process::{Child, Command, ExitStatus, Stdio};
+use std::sync::atomic::{AtomicBool, Ordering};
+use std::sync::mpsc::RecvTimeoutError;
+use std::sync::{Arc, Condvar, Mutex, mpsc};
+use std::thread::{self, JoinHandle};
+use std::time::{Duration, Instant};
+use yinyang::core::service::ServiceClient;
+use yinyang::core::{Authority, BackendProfile, CommitId, CommitOutcome, Fs, Planner};
+use yinyang::runtime::Runtime as YinYangRuntime;
+
+/// The kernel filesystem type advertised by the YinYang FUSE adapter.
+pub const MOUNT_TYPE: &str = "fuse.yinyang";
+
+pub fn require_fuse() {
+    if !Path::new("/dev/fuse").exists() {
+        panic!(
+            "/dev/fuse is not available; this is a hard Linux FUSE acceptance failure, not a skip"
+        );
+    }
+    for tool in ["fusermount3", "timeout", "python3"] {
+        if Command::new(tool).arg("--version").output().is_err() {
+            panic!("required tool {tool} is not available for Linux FUSE acceptance");
+        }
+    }
+}
+
+#[derive(Debug)]
+pub struct Captured {
+    pub status: ExitStatus,
+    pub stdout: Vec<u8>,
+    pub stderr: Vec<u8>,
+}
+
+impl Captured {
+    pub fn success_or(&self, context: &str) {
+        assert!(
+            self.status.success(),
+            "{context} failed with {}:\nstdout:\n{}\nstderr:\n{}",
+            self.status,
+            String::from_utf8_lossy(&self.stdout),
+            String::from_utf8_lossy(&self.stderr)
+        );
+    }
+}
+
+pub fn run_timeout(mut cmd: Command, timeout: Duration) -> Captured {
+    cmd.stdin(Stdio::null())
+        .stdout(Stdio::piped())
+        .stderr(Stdio::piped());
+    let mut child = cmd
+        .spawn()
+        .unwrap_or_else(|error| panic!("failed to spawn command (format: {cmd:?}): {error}"));
+    let stdout = child.stdout.take().expect("stdout is piped");
+    let stderr = child.stderr.take().expect("stderr is piped");
+    let stdout_thread = thread::spawn(move || read_all(stdout));
+    let stderr_thread = thread::spawn(move || read_all(stderr));
+    let deadline = Instant::now() + timeout;
+    let status = loop {
+        match child.try_wait() {
+            Ok(Some(status)) => break status,
+            Ok(None) => {
+                if Instant::now() >= deadline {
+                    let _ = child.kill();
+                    let status = child.wait().expect("wait after kill");
+                    let stdout = stdout_thread.join().unwrap_or_default();
+                    let stderr = stderr_thread.join().unwrap_or_default();
+                    panic!(
+                        "command timed out after {timeout:?} with {status} (format: {cmd:?}):\nstdout:\n{}\nstderr:\n{}",
+                        String::from_utf8_lossy(&stdout),
+                        String::from_utf8_lossy(&stderr)
+                    );
+                }
+                thread::sleep(Duration::from_millis(25));
+            }
+            Err(error) => {
+                let _ = child.kill();
+                let _ = child.wait();
+                panic!("failed to wait for command (format: {cmd:?}): {error}");
+            }
+        }
+    };
+    let stdout = stdout_thread.join().unwrap_or_default();
+    let stderr = stderr_thread.join().unwrap_or_default();
+    Captured {
+        status,
+        stdout,
+        stderr,
+    }
+}
+
+pub fn run_external(program: &str, args: &[&str], timeout: Duration) -> Captured {
+    let mut cmd = Command::new(program);
+    cmd.args(args);
+    run_timeout(cmd, timeout)
+}
+
+fn read_all(mut reader: impl Read) -> Vec<u8> {
+    let mut bytes = Vec::new();
+    let _ = reader.read_to_end(&mut bytes);
+    bytes
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum Publication {
+    Object,
+    Service,
+}
+
+impl Publication {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Object => "object",
+            Self::Service => "service",
+        }
+    }
+}
+
+#[derive(Clone, Copy, Debug, Eq, PartialEq)]
+pub enum Frontend {
+    Library,
+    Fuse,
+}
+
+impl Frontend {
+    pub fn as_str(self) -> &'static str {
+        match self {
+            Self::Library => "library",
+            Self::Fuse => "fuse",
+        }
+    }
+}
+
+pub struct Fixture {
+    pub temp: tempfile::TempDir,
+    root: String,
+    token: String,
+    service: Option<ServiceGuard>,
+    last_service_address: Option<SocketAddr>,
+}
+
+impl Fixture {
+    pub fn new(publication: Publication) -> Self {
+        require_fuse();
+        let temp = tempfile::tempdir().expect("create temporary test directory");
+        let root = format!(
+            "fuse-{}-{}",
+            std::process::id(),
+            std::time::SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .unwrap()
+                .as_nanos()
+        );
+        let token = "0123456789abcdef0123456789abcdef".to_owned();
+        let mut fixture = Fixture {
+            temp,
+            root,
+            token,
+            service: None,
+            last_service_address: None,
+        };
+        match publication {
+            Publication::Object => {
+                fixture.yy_ok(&["create"]);
+            }
+            Publication::Service => fixture.spawn_service(),
+        }
+        fixture
+    }
+
+    pub fn publication(&self) -> Publication {
+        if self.service.is_some() {
+            Publication::Service
+        } else {
+            Publication::Object
+        }
+    }
+
+    fn storage_env(&self) -> Vec<(&'static str, String)> {
+        let required = [
+            "YINYANG_S3_BUCKET",
+            "YINYANG_S3_ENDPOINT",
+            "YINYANG_S3_REGION",
+            "YINYANG_S3_ACCESS_KEY_ID",
+            "YINYANG_S3_SECRET_ACCESS_KEY",
+        ];
+        let mut env = Vec::new();
+        for name in required {
+            let value = std::env::var(name).unwrap_or_else(|_| {
+                panic!("set {name} before running Linux FUSE acceptance; missing configuration is a hard failure")
+            });
+            env.push((name, value));
+        }
+        env.push(("YINYANG_STORAGE_PROFILE", "minio".to_owned()));
+        env.push(("YINYANG_S3_ROOT", self.root.clone()));
+        env.push(("YINYANG_SERVICE_TOKEN", self.token.clone()));
+        env
+    }
+
+    pub fn yy_command(&self, args: &[&str]) -> Command {
+        let mut cmd = Command::new(env!("CARGO_BIN_EXE_yy"));
+        cmd.args(args);
+        for (name, value) in self.storage_env() {
+            cmd.env(name, value);
+        }
+        cmd
+    }
+
+    pub fn yy(&self, args: &[&str]) -> Captured {
+        run_timeout(self.yy_command(args), Duration::from_secs(120))
+    }
+
+    pub fn yy_ok(&self, args: &[&str]) -> Captured {
+        let output = self.yy(args);
+        output.success_or(&format!("yy {args:?}"));
+        output
+    }
+
+    fn spawn_service(&mut self) {
+        self.spawn_service_on("127.0.0.1:0".parse().expect("loopback wildcard"));
+    }
+
+    fn spawn_service_on(&mut self, listen: SocketAddr) {
+        let database = self.temp.path().join("metadata.db");
+        let database = database.to_str().expect("UTF-8 database path");
+        let listen = listen.to_string();
+        let mut cmd = self.yy_command(&["serve", "--database", database, "--listen", &listen]);
+        cmd.stdout(Stdio::piped()).stderr(Stdio::piped());
+        let mut child = cmd
+            .spawn()
+            .unwrap_or_else(|error| panic!("failed to spawn yy serve: {error}"));
+        let stdout = child.stdout.take().expect("stdout is piped");
+        let stderr = child.stderr.take().expect("stderr is piped");
+        let (sender, receiver) = mpsc::channel();
+        let reader = thread::spawn(move || {
+            let mut line = String::new();
+            if BufReader::new(stdout).read_line(&mut line).is_ok() {
+                let _ = sender.send(line);
+            }
+        });
+        let stderr_thread = thread::spawn(move || read_all(stderr));
+        let line = match receiver.recv_timeout(Duration::from_secs(60)) {
+            Ok(line) => line,
+            Err(error @ (RecvTimeoutError::Timeout | RecvTimeoutError::Disconnected)) => {
+                let _ = child.kill();
+                let _ = child.wait();
+                let _ = reader.join();
+                let stderr = stderr_thread.join().unwrap_or_default();
+                panic!(
+                    "yy serve did not report a listening address ({error:?}):\n{}",
+                    String::from_utf8_lossy(&stderr)
+                );
+            }
+        };
+        let address: SocketAddr = line
+            .trim()
+            .strip_prefix("metadata service listening on ")
+            .unwrap_or_else(|| {
+                let _ = child.kill();
+                let _ = child.wait();
+                panic!("unexpected yy serve startup line: {line:?}");
+            })
+            .parse()
+            .unwrap_or_else(|error| {
+                let _ = child.kill();
+                let _ = child.wait();
+                panic!("invalid yy serve listening address {line:?}: {error}");
+            });
+        let _ = reader.join();
+        self.last_service_address = Some(address);
+        self.service = Some(ServiceGuard {
+            child,
+            address,
+            stderr: Some(stderr_thread),
+        });
+    }
+
+    pub fn stop_service(&mut self) {
+        if let Some(mut service) = self.service.take() {
+            self.last_service_address = Some(service.address);
+            service.stop();
+        }
+    }
+
+    pub fn restart_service(&mut self) {
+        let address = self.service_address();
+        self.stop_service();
+        self.spawn_service_on(address);
+    }
+
+    pub fn service_address(&self) -> SocketAddr {
+        self.service
+            .as_ref()
+            .map(|service| service.address)
+            .or(self.last_service_address)
+            .expect("service publication requires a running metadata service")
+    }
+
+    /// Polls the existing no-lease status entry until a handle reports the
+    /// frozen publication boundary. A hang is a hard failure, not a skip.
+    pub fn wait_for_frozen(&self, config: &Path) -> String {
+        let deadline = Instant::now() + Duration::from_secs(30);
+        let staging = self
+            .temp
+            .path()
+            .join(config.file_stem().expect("volume config has a file stem"));
+        let runtime = tokio::runtime::Builder::new_current_thread()
+            .enable_all()
+            .build()
+            .expect("build status runtime");
+        loop {
+            let status = runtime
+                .block_on(YinYangRuntime::inspect(&staging))
+                .expect("inspect staging without the runtime lease");
+            let text = format!("{status:#?}");
+            if status.handles.iter().any(|handle| handle.frozen) {
+                return text;
+            }
+            if Instant::now() >= deadline {
+                panic!(
+                    "fsync never reached the frozen publication boundary within 30s; last yy status:\n{text}"
+                );
+            }
+            thread::sleep(Duration::from_millis(100));
+        }
+    }
+
+    /// Writes a strict volume config and returns its path. Rewriting the same
+    /// path is intentional: a restarted service keeps its original loopback
+    /// address, so an unchanged config keeps working.
+    pub fn volume_config(&self, name: &str, frontend: Frontend, read_only: bool) -> PathBuf {
+        self.volume_config_with_service(name, frontend, read_only, None)
+    }
+
+    pub fn volume_config_with_service(
+        &self,
+        name: &str,
+        frontend: Frontend,
+        read_only: bool,
+        service_address: Option<SocketAddr>,
+    ) -> PathBuf {
+        let staging = self.temp.path().join(name);
+        let mut json = format!(
+            "{{\n  \"name\": {},\n  \"model\": \"managed\",\n  \"access\": \"mount\",\n  \"frontend\": \"{}\",\n  \"publication\": \"{}\",\n  \"storage_profile\": \"minio\",\n  \"staging\": {},\n  \"read_only\": {},\n  \"require\": []",
+            json_string(name),
+            frontend.as_str(),
+            self.publication().as_str(),
+            json_string(staging.to_str().expect("UTF-8 staging path")),
+            read_only
+        );
+        if self.publication() == Publication::Service {
+            json.push_str(&format!(
+                ",\n  \"service_address\": \"{}\"",
+                service_address.unwrap_or_else(|| self.service_address())
+            ));
+        }
+        json.push_str("\n}");
+        let path = self.temp.path().join(format!("{name}.json"));
+        fs::write(&path, json).expect("write volume config");
+        path
+    }
+
+    /// Seed a directory tree in one core transaction. The 520 entries in
+    /// `bulk` cross the adapter's 512-entry readdir page without launching one
+    /// CLI process per entry.
+    pub fn seed_read_only_tree(&self) {
+        let operator = self.operator();
+        let publication = self.publication();
+        let address = self.service.as_ref().map(|service| service.address);
+        let token = self.token.clone();
+        let runtime = tokio::runtime::Builder::new_multi_thread()
+            .enable_all()
+            .build()
+            .expect("build seed runtime");
+        runtime.block_on(async move {
+            let authority: Arc<dyn Authority> = match publication {
+                Publication::Object => Arc::new(
+                    Fs::open(operator, BackendProfile::Minio)
+                        .await
+                        .expect("open object authority for batch seed"),
+                ),
+                Publication::Service => Arc::new(
+                    ServiceClient::connect(address.expect("service address"), token, operator)
+                        .await
+                        .expect("connect service authority for batch seed"),
+                ),
+            };
+            let snapshot = authority.observe_latest().await.expect("observe seed base");
+            let mut empty_source: &[u8] = b"";
+            let empty = authority
+                .prepare(&mut empty_source)
+                .await
+                .expect("prepare empty file content");
+            let mut hello_source: &[u8] = b"hello from nested";
+            let hello = authority
+                .prepare(&mut hello_source)
+                .await
+                .expect("prepare nested file content");
+            let mut root_source: &[u8] = b"read-only bytes";
+            let root_file = authority
+                .prepare(&mut root_source)
+                .await
+                .expect("prepare root file content");
+            let mut plan = Planner::new(&snapshot, CommitId::generate());
+            let nested = plan
+                .create_directory(authority.root(), "nested")
+                .await
+                .expect("plan nested directory");
+            let inner = plan
+                .create_directory(nested, "inner")
+                .await
+                .expect("plan inner directory");
+            plan.create_file(inner, "hello.txt", hello, false)
+                .await
+                .expect("plan nested file");
+            plan.create_file(authority.root(), "readonly.txt", root_file, false)
+                .await
+                .expect("plan root file");
+            let bulk = plan
+                .create_directory(authority.root(), "bulk")
+                .await
+                .expect("plan bulk directory");
+            for index in 0..520 {
+                plan.create_file(bulk, &format!("entry-{index:04}"), empty.clone(), false)
+                    .await
+                    .expect("plan bulk entry");
+            }
+            let request = plan.finish().expect("finish batch seed");
+            let outcome = authority.commit(&request).await.expect("commit batch seed");
+            assert!(
+                matches!(&outcome, CommitOutcome::Committed(_)),
+                "batch seed did not commit: {outcome:?}"
+            );
+        });
+    }
+
+    fn operator(&self) -> opendal::Operator {
+        opendal::install_default();
+        let config = self
+            .storage_env()
+            .into_iter()
+            .filter_map(|(key, value)| {
+                key.strip_prefix("YINYANG_S3_")
+                    .map(|key| (key.to_ascii_lowercase(), value))
+            })
+            .collect::<Vec<_>>();
+        opendal::Operator::via_iter("s3", config).expect("construct S3 operator")
+    }
+
+    pub fn library_seed(&self, config: &Path, path: &str, bytes: &[u8]) {
+        self.yy_ok(&[
+            "--volume",
+            config.to_str().expect("UTF-8 volume config"),
+            "file",
+            "create",
+            path,
+        ]);
+        self.remote_write(config, path, bytes);
+    }
+
+    pub fn remote_write(&self, _config: &Path, path: &str, bytes: &[u8]) {
+        let authority = self.in_process_authority();
+        let staging = self.in_process_staging("write");
+        let runtime = tokio::runtime::Builder::new_current_thread()
+            .enable_all()
+            .build()
+            .expect("build in-process write runtime");
+        runtime.block_on(async move {
+            let runtime = YinYangRuntime::open(authority, staging)
+                .await
+                .expect("open in-process write runtime");
+            let mut file = runtime
+                .open_file(path, true)
+                .await
+                .expect("open in-process write handle");
+            file.write(0, bytes)
+                .await
+                .expect("write through in-process authority");
+            file.fsync()
+                .await
+                .expect("fsync in-process authority write");
+            file.close().await.expect("close in-process write handle");
+        });
+    }
+
+    pub fn remote_truncate(&self, _config: &Path, path: &str, length: u64) {
+        let authority = self.in_process_authority();
+        let staging = self.in_process_staging("truncate");
+        let runtime = tokio::runtime::Builder::new_current_thread()
+            .enable_all()
+            .build()
+            .expect("build in-process truncate runtime");
+        runtime.block_on(async move {
+            let runtime = YinYangRuntime::open(authority, staging)
+                .await
+                .expect("open in-process truncate runtime");
+            let mut file = runtime
+                .open_file(path, true)
+                .await
+                .expect("open in-process truncate handle");
+            file.truncate(length)
+                .await
+                .expect("truncate through in-process authority");
+            file.fsync()
+                .await
+                .expect("fsync in-process authority truncate");
+            file.close()
+                .await
+                .expect("close in-process truncate handle");
+        });
+    }
+
+    pub fn remote_create(&self, _config: &Path, path: &str) {
+        let authority = self.in_process_authority();
+        let staging = self.in_process_staging("create");
+        let runtime = tokio::runtime::Builder::new_current_thread()
+            .enable_all()
+            .build()
+            .expect("build in-process create runtime");
+        runtime.block_on(async move {
+            let runtime = YinYangRuntime::open(authority, staging)
+                .await
+                .expect("open in-process create runtime");
+            let (parent, name) = path.rsplit_once('/').unwrap_or(("", path));
+            let snapshot = runtime
+                .authority()
+                .observe_latest()
+                .await
+                .expect("observe in-process create parent");
+            let parent = snapshot
+                .resolve(parent)
+                .await
+                .expect("resolve in-process create parent")
+                .expect("in-process create parent exists");
+            runtime
+                .create_file(parent.id(), name)
+                .await
+                .expect("create through in-process authority");
+        });
+    }
+
+    pub fn remote_rename(&self, _config: &Path, source: &str, destination: &str) {
+        let authority = self.in_process_authority();
+        let staging = self.in_process_staging("rename");
+        let runtime = tokio::runtime::Builder::new_current_thread()
+            .enable_all()
+            .build()
+            .expect("build in-process rename runtime");
+        runtime.block_on(async move {
+            let runtime = YinYangRuntime::open(authority, staging)
+                .await
+                .expect("open in-process rename runtime");
+            let snapshot = runtime
+                .authority()
+                .observe_latest()
+                .await
+                .expect("observe in-process rename source");
+            let source = snapshot
+                .resolve(source)
+                .await
+                .expect("resolve in-process rename source")
+                .expect("in-process rename source exists");
+            let (parent, name) = destination.rsplit_once('/').unwrap_or(("", destination));
+            let parent = snapshot
+                .resolve(parent)
+                .await
+                .expect("resolve in-process rename parent")
+                .expect("in-process rename parent exists");
+            runtime
+                .rename(source.id(), parent.id(), name)
+                .await
+                .expect("rename through in-process authority");
+        });
+    }
+
+    pub fn remote_read(&self, _config: &Path, path: &str, length: usize) -> Vec<u8> {
+        let authority = self.in_process_authority();
+        let runtime = tokio::runtime::Builder::new_current_thread()
+            .enable_all()
+            .build()
+            .expect("build in-process read runtime");
+        runtime.block_on(async move {
+            let snapshot = authority
+                .observe_latest()
+                .await
+                .expect("observe in-process read");
+            let node = snapshot
+                .resolve(path)
+                .await
+                .expect("resolve in-process read")
+                .expect("in-process read path exists");
+            snapshot
+                .open_file(node.id())
+                .await
+                .expect("open in-process read version")
+                .read(0, length)
+                .await
+                .expect("read through in-process authority")
+        })
+    }
+
+    fn in_process_authority(&self) -> Arc<dyn Authority> {
+        let operator = self.operator();
+        let publication = self.publication();
+        let address = self.last_service_address;
+        let token = self.token.clone();
+        let runtime = tokio::runtime::Builder::new_current_thread()
+            .enable_all()
+            .build()
+            .expect("build in-process authority runtime");
+        runtime.block_on(async move {
+            let authority: Arc<dyn Authority> = match publication {
+                Publication::Object => Arc::new(
+                    Fs::open(operator, BackendProfile::Minio)
+                        .await
+                        .expect("open in-process object authority"),
+                ),
+                Publication::Service => Arc::new(
+                    ServiceClient::connect(
+                        address.expect("in-process service address"),
+                        token,
+                        operator,
+                    )
+                    .await
+                    .expect("connect in-process service authority"),
+                ),
+            };
+            authority
+        })
+    }
+
+    fn in_process_staging(&self, operation: &str) -> PathBuf {
+        self.temp.path().join(format!(
+            "inproc-{operation}-{}",
+            std::time::SystemTime::now()
+                .duration_since(std::time::UNIX_EPOCH)
+                .expect("system time")
+                .as_nanos()
+        ))
+    }
+
+    pub fn mount(&self, config: &Path, mountpoint: &Path) -> Mounted {
+        let staging = self
+            .temp
+            .path()
+            .join(config.file_stem().expect("volume config has a file stem"));
+        let mountpoint = mountpoint.to_str().expect("UTF-8 mountpoint");
+        let config = config.to_str().expect("UTF-8 config path");
+        let mut cmd = self.yy_command(&["--volume", config, "mount", mountpoint]);
+        cmd.stdout(Stdio::piped()).stderr(Stdio::piped());
+        let mut child = cmd.spawn().unwrap_or_else(|error| {
+            panic!("failed to spawn `yy --volume {config} mount {mountpoint}`: {error}")
+        });
+        let stdout = child.stdout.take().expect("stdout is piped");
+        let stderr = child.stderr.take().expect("stderr is piped");
+        let stdout_log = Arc::new(Mutex::new(Vec::new()));
+        let stderr_log = Arc::new(Mutex::new(Vec::new()));
+        let log = stdout_log.clone();
+        let stdout_thread = thread::spawn(move || read_all_logged(stdout, log));
+        let log = stderr_log.clone();
+        let stderr_thread = thread::spawn(move || read_all_logged(stderr, log));
+        let mut mounted = Mounted {
+            child,
+            stdout: Some(stdout_thread),
+            stderr: Some(stderr_thread),
+            mountpoint: PathBuf::from(mountpoint),
+            staging,
+            stdout_log,
+            stderr_log,
+        };
+        mounted.wait_mounted();
+        mounted
+    }
+}
+
+pub struct ServiceGuard {
+    child: Child,
+    address: SocketAddr,
+    stderr: Option<JoinHandle<Vec<u8>>>,
+}
+
+impl ServiceGuard {
+    fn stop(&mut self) {
+        let _ = self.child.kill();
+        let _ = self.child.wait();
+        if let Some(thread) = self.stderr.take() {
+            let _ = thread.join();
+        }
+    }
+}
+
+impl Drop for ServiceGuard {
+    fn drop(&mut self) {
+        self.stop();
+    }
+}
+
+pub struct Mounted {
+    child: Child,
+    stdout: Option<JoinHandle<Vec<u8>>>,
+    stderr: Option<JoinHandle<Vec<u8>>>,
+    mountpoint: PathBuf,
+    staging: PathBuf,
+    stdout_log: Arc<Mutex<Vec<u8>>>,
+    stderr_log: Arc<Mutex<Vec<u8>>>,
+}
+
+impl Mounted {
+    pub fn mountpoint(&self) -> &Path {
+        &self.mountpoint
+    }
+
+    fn wait_mounted(&mut self) {
+        let deadline = Instant::now() + Duration::from_secs(60);
+        loop {
+            if let Some(kind) = mount_fs_type(&self.mountpoint) {
+                assert_eq!(
+                    kind,
+                    MOUNT_TYPE,
+                    "{} is mounted as {kind}, not the YinYang FUSE type {MOUNT_TYPE}; a foreign or sample mount is not acceptance",
+                    self.mountpoint.display()
+                );
+                return;
+            }
+            if let Some(status) = self
+                .child
+                .try_wait()
+                .unwrap_or_else(|error| panic!("failed to wait for yy mount: {error}"))
+            {
+                let stderr = self.join_stderr();
+                panic!(
+                    "yy mount exited before mounting {} with {status}:\n{}",
+                    self.mountpoint.display(),
+                    String::from_utf8_lossy(&stderr)
+                );
+            }
+            if Instant::now() >= deadline {
+                let _ = self.child.kill();
+                let _ = self.child.wait();
+                let stderr = self.join_stderr();
+                panic!(
+                    "yy mount did not install {} as {MOUNT_TYPE} within 60s:\n{}",
+                    self.mountpoint.display(),
+                    String::from_utf8_lossy(&stderr)
+                );
+            }
+            thread::sleep(Duration::from_millis(50));
+        }
+    }
+
+    /// Stop the daemon without spawning a cleanup helper while a dirty FUSE
+    /// descriptor is still owned by the test process.
+    pub fn kill_daemon_only(&mut self) {
+        let _ = self.child.kill();
+        let _ = self.wait_exit(Duration::from_secs(30));
+    }
+
+    pub fn cleanup_after_kill(&mut self) {
+        self.unmount_force();
+        self.assert_staging_lease_released();
+    }
+
+    pub fn terminate(&mut self) {
+        let pid = Pid::from_raw(self.child.id() as i32);
+        kill(pid, Signal::SIGTERM).expect("send SIGTERM without exec");
+        let status = self.wait_exit(Duration::from_secs(30));
+        assert!(
+            status.success(),
+            "yy mount did not exit cleanly after SIGTERM: {status}"
+        );
+        assert!(
+            mount_fs_type(&self.mountpoint).is_none(),
+            "yy did not remove {} after a graceful SIGTERM",
+            self.mountpoint.display()
+        );
+        self.assert_staging_lease_released();
+    }
+
+    /// SIGTERM with open descriptors or a pending fsync must exit under the
+    /// forced non-zero grace path and release the staging lease. No success
+    /// assertion is made here; the caller requires the busy exit contract.
+    pub fn terminate_busy(&mut self) -> ExitStatus {
+        let pid = Pid::from_raw(self.child.id() as i32);
+        kill(pid, Signal::SIGTERM).expect("send SIGTERM without exec");
+        self.wait_exit(Duration::from_secs(10))
+    }
+
+    /// Ask the live daemon for the explicit SIGHUP refresh path.
+    pub fn refresh_sighup(&mut self) {
+        let pid = Pid::from_raw(self.child.id() as i32);
+        kill(pid, Signal::SIGHUP).expect("send SIGHUP without exec");
+    }
+
+    pub fn wait_for_output_line(&self, needle: &str, timeout: Duration) -> String {
+        let deadline = Instant::now() + timeout;
+        loop {
+            let output = self.output_text();
+            if output
+                .lines()
+                .any(|line| line.contains(needle) && line.trim_end().ends_with(')'))
+            {
+                return output;
+            }
+            if Instant::now() >= deadline {
+                panic!(
+                    "yy mount did not emit expected output {needle:?} within {timeout:?}:\n{output}"
+                );
+            }
+            thread::sleep(Duration::from_millis(50));
+        }
+    }
+
+    pub fn output_text(&self) -> String {
+        let stdout = self
+            .stdout_log
+            .lock()
+            .unwrap_or_else(|poisoned| poisoned.into_inner());
+        let stderr = self
+            .stderr_log
+            .lock()
+            .unwrap_or_else(|poisoned| poisoned.into_inner());
+        format!(
+            "stdout:\n{}\nstderr:\n{}",
+            String::from_utf8_lossy(&stdout),
+            String::from_utf8_lossy(&stderr)
+        )
+    }
+
+    pub fn unmount(&mut self) {
+        let mountpoint = self.mountpoint.to_str().expect("UTF-8 mountpoint");
+        let output = run_external("fusermount3", &["-u", mountpoint], Duration::from_secs(30));
+        output.success_or(&format!("fusermount3 -u {mountpoint}"));
+        let status = self.wait_exit(Duration::from_secs(30));
+        assert!(
+            status.success(),
+            "yy mount did not exit cleanly after external unmount: {status}"
+        );
+        assert!(
+            mount_fs_type(&self.mountpoint).is_none(),
+            "external unmount left {} in /proc/mounts",
+            self.mountpoint.display()
+        );
+        self.assert_staging_lease_released();
+    }
+
+    fn unmount_force(&mut self) {
+        if mount_fs_type(&self.mountpoint).is_none() {
+            return;
+        }
+        let mountpoint = self.mountpoint.to_str().expect("UTF-8 mountpoint");
+        let _ = run_external(
+            "fusermount3",
+            &["-u", "-z", mountpoint],
+            Duration::from_secs(30),
+        );
+    }
+
+    fn wait_exit(&mut self, timeout: Duration) -> ExitStatus {
+        let deadline = Instant::now() + timeout;
+        loop {
+            if let Some(status) = self.child.try_wait().expect("wait for yy mount") {
+                let _ = self.stdout.take().map(JoinHandle::join);
+                let _ = self.stderr.take().map(JoinHandle::join);
+                return status;
+            }
+            if Instant::now() >= deadline {
+                let _ = self.child.kill();
+                let _ = self.child.wait();
+                let stderr = self.join_stderr();
+                panic!(
+                    "yy mount did not exit after unmount {}:\n{}",
+                    self.mountpoint.display(),
+                    String::from_utf8_lossy(&stderr)
+                );
+            }
+            thread::sleep(Duration::from_millis(25));
+        }
+    }
+
+    fn join_stderr(&mut self) -> Vec<u8> {
+        self.stderr
+            .take()
+            .and_then(|thread| thread.join().ok())
+            .unwrap_or_default()
+    }
+
+    fn assert_staging_lease_released(&self) {
+        let path = self.staging.join("runtime.lock");
+        let lock = fs::OpenOptions::new()
+            .create(true)
+            .truncate(false)
+            .read(true)
+            .write(true)
+            .open(&path)
+            .unwrap_or_else(|error| panic!("open staging lock {}: {error}", path.display()));
+        lock.try_lock().unwrap_or_else(|error| {
+            panic!(
+                "yy mount still holds the staging lease {} after process exit: {error}",
+                path.display()
+            )
+        });
+    }
+}
+
+fn read_all_logged(mut reader: impl Read, log: Arc<Mutex<Vec<u8>>>) -> Vec<u8> {
+    let mut bytes = Vec::new();
+    let mut chunk = [0u8; 8192];
+    loop {
+        match reader.read(&mut chunk) {
+            Ok(0) => break,
+            Ok(count) => {
+                bytes.extend_from_slice(&chunk[..count]);
+                if let Ok(mut output) = log.lock() {
+                    output.extend_from_slice(&chunk[..count]);
+                }
+            }
+            Err(error) if error.kind() == std::io::ErrorKind::Interrupted => continue,
+            Err(_) => break,
+        }
+    }
+    bytes
+}
+
+/// A loopback TCP gate used only by the mounting volume. It watches the
+/// no-lease staging status and blocks the first connection observed after a
+/// frozen publication is persisted. Service clients used by the test itself
+/// connect directly to the real service.
+pub struct ServiceGate {
+    address: SocketAddr,
+    release: Arc<(Mutex<bool>, Condvar)>,
+    ready: mpsc::Receiver<()>,
+    stop: Arc<AtomicBool>,
+    thread: Option<JoinHandle<()>>,
+}
+
+impl ServiceGate {
+    pub fn new(staging: PathBuf, upstream: SocketAddr) -> Self {
+        let listener = TcpListener::bind("127.0.0.1:0").expect("bind service gate");
+        let address = listener.local_addr().expect("service gate address");
+        let release = Arc::new((Mutex::new(false), Condvar::new()));
+        let stop = Arc::new(AtomicBool::new(false));
+        let ready_sent = Arc::new(AtomicBool::new(false));
+        let (sender, ready) = mpsc::channel();
+        let thread_release = release.clone();
+        let thread_stop = stop.clone();
+        let thread = thread::spawn(move || {
+            while !thread_stop.load(Ordering::SeqCst) {
+                let Ok((client, _)) = listener.accept() else {
+                    break;
+                };
+                if thread_stop.load(Ordering::SeqCst) {
+                    break;
+                }
+                let staging = staging.clone();
+                let release = thread_release.clone();
+                let ready_sent = ready_sent.clone();
+                let sender = sender.clone();
+                thread::spawn(move || {
+                    handle_gate_connection(client, upstream, staging, release, ready_sent, sender);
+                });
+            }
+        });
+        Self {
+            address,
+            release,
+            ready,
+            stop,
+            thread: Some(thread),
+        }
+    }
+
+    pub fn address(&self) -> SocketAddr {
+        self.address
+    }
+
+    pub fn wait_ready(&self, timeout: Duration) {
+        self.ready
+            .recv_timeout(timeout)
+            .expect("service gate did not observe a frozen commit connection");
+    }
+
+    pub fn release(&self) {
+        let (released, condvar) = &*self.release;
+        *released
+            .lock()
+            .unwrap_or_else(|poisoned| poisoned.into_inner()) = true;
+        condvar.notify_all();
+    }
+}
+
+impl Drop for ServiceGate {
+    fn drop(&mut self) {
+        self.stop.store(true, Ordering::SeqCst);
+        self.release();
+        let _ = TcpStream::connect(self.address);
+        if let Some(thread) = self.thread.take() {
+            let _ = thread.join();
+        }
+    }
+}
+
+fn handle_gate_connection(
+    client: TcpStream,
+    upstream: SocketAddr,
+    staging: PathBuf,
+    release: Arc<(Mutex<bool>, Condvar)>,
+    ready_sent: Arc<AtomicBool>,
+    sender: mpsc::Sender<()>,
+) {
+    let runtime = tokio::runtime::Builder::new_current_thread()
+        .enable_all()
+        .build()
+        .expect("build service gate runtime");
+    let frozen = staging.join("staging.db").exists()
+        && runtime
+            .block_on(YinYangRuntime::inspect(&staging))
+            .ok()
+            .is_some_and(|status| status.handles.iter().any(|handle| handle.frozen));
+    if frozen {
+        if !ready_sent.swap(true, Ordering::SeqCst) {
+            let _ = sender.send(());
+        }
+        let (released, condvar) = &*release;
+        let mut released = released
+            .lock()
+            .unwrap_or_else(|poisoned| poisoned.into_inner());
+        while !*released {
+            released = condvar
+                .wait(released)
+                .unwrap_or_else(|poisoned| poisoned.into_inner());
+        }
+    }
+    let Ok(server) = TcpStream::connect(upstream) else {
+        return;
+    };
+    let (Ok(mut client_read), Ok(mut client_write)) = (client.try_clone(), client.try_clone())
+    else {
+        return;
+    };
+    let (Ok(mut server_read), Ok(mut server_write)) = (server.try_clone(), server.try_clone())
+    else {
+        return;
+    };
+    let client_to_server = thread::spawn(move || {
+        let _ = std::io::copy(&mut client_read, &mut server_write);
+        let _ = server_write.shutdown(std::net::Shutdown::Write);
+    });
+    let server_to_client = thread::spawn(move || {
+        let _ = std::io::copy(&mut server_read, &mut client_write);
+        let _ = client_write.shutdown(std::net::Shutdown::Write);
+    });
+    let _ = client_to_server.join();
+    let _ = server_to_client.join();
+}
+
+impl Drop for Mounted {
+    fn drop(&mut self) {
+        let _ = self.child.kill();
+        let _ = self.child.wait();
+        if let Some(thread) = self.stdout.take() {
+            let _ = thread.join();
+        }
+        if let Some(thread) = self.stderr.take() {
+            let _ = thread.join();
+        }
+        self.unmount_force();
+    }
+}
+
+pub fn mount_fs_type(mountpoint: &Path) -> Option<String> {
+    let mounts = fs::read_to_string("/proc/mounts").expect("read /proc/mounts");
+    for line in mounts.lines() {
+        let mut fields = line.split_whitespace();
+        let _source = fields.next()?;
+        let point = fields.next()?;
+        let kind = fields.next()?;
+        if Path::new(point) == mountpoint {
+            return Some(kind.to_owned());
+        }
+    }
+    None
+}
+
+pub fn json_string(value: &str) -> String {
+    let mut escaped = String::with_capacity(value.len() + 2);
+    escaped.push('"');
+    for ch in value.chars() {
+        match ch {
+            '"' => escaped.push_str("\\\""),
+            '\\' => escaped.push_str("\\\\"),
+            '\n' => escaped.push_str("\\n"),
+            _ => escaped.push(ch),
+        }
+    }
+    escaped.push('"');
+    escaped
+}
+
+pub fn assert_errno(error: std::io::Error, allowed: &[i32], operation: &str) {
+    let code = error.raw_os_error().unwrap_or_else(|| {
+        panic!("{operation} failed without an explicit OS error: {error}");
+    });
+    assert!(
+        allowed.contains(&code),
+        "{operation} returned unexpected errno {code} ({error}); expected one of {allowed:?}"
+    );
+}
+
+pub fn sync_all_with_deadline(file: &fs::File, timeout: Duration) -> std::io::Result<()> {
+    let clone = file.try_clone()?;
+    let (sender, receiver) = mpsc::channel();
+    let worker = thread::spawn(move || {
+        let _ = sender.send(clone.sync_all());
+    });
+    let result = receiver.recv_timeout(timeout).unwrap_or_else(|error| {
+        panic!("fsync did not complete within {timeout:?}; a hang is not acceptance: {error}")
+    });
+    worker.join().expect("fsync worker panicked");
+    result
+}
diff --git a/tests/linux_fuse/main.rs b/tests/linux_fuse/main.rs
new file mode 100644
index 0000000..0dbd9c1
--- /dev/null
+++ b/tests/linux_fuse/main.rs
@@ -0,0 +1,21 @@
+// Licensed to the Apache Software Foundation (ASF) under one
+// or more contributor license agreements.  See the NOTICE file
+// distributed with this work for additional information
+// regarding copyright ownership.  The ASF licenses this file
+// to you under the Apache License, Version 2.0 (the
+// "License"); you may not use this file except in compliance
+// with the License.  You may obtain a copy of the License at
+//
+//   http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing,
+// software distributed under the License is distributed on an
+// "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+// KIND, either express or implied.  See the License for the
+// specific language governing permissions and limitations
+// under the License.
+
+#![cfg(target_os = "linux")]
+
+mod acceptance;
+mod harness;
diff --git a/xtask/src/main.rs b/xtask/src/main.rs
index 2f94115..8c0ce47 100644
--- a/xtask/src/main.rs
+++ b/xtask/src/main.rs
@@ -21,14 +21,28 @@ use std::process::Command as StdCommand;
 
 use clap::Parser;
 use clap::Subcommand;
+use clap::error::ErrorKind;
 
 fn main() {
-    let cmd = Command::parse();
+    let cmd = match Command::try_parse() {
+        Ok(cmd) => cmd,
+        Err(error) => {
+            let _ = error.print();
+            std::process::exit(parse_error_exit_code(error.kind()));
+        }
+    };
     cmd.run();
 }
 
+fn parse_error_exit_code(kind: ErrorKind) -> i32 {
+    match kind {
+        ErrorKind::DisplayHelp | ErrorKind::DisplayVersion => 0,
+        _ => 2,
+    }
+}
+
 #[derive(Parser)]
-#[clap(about = "Run repository tasks.")]
+#[clap(about = "Run repository tasks.", version, propagate_version = true)]
 struct Command {
     #[clap(subcommand)]
     sub: SubCommand,
@@ -42,6 +56,7 @@ impl Command {
             SubCommand::Lint(cmd) => cmd.run(),
             SubCommand::Test(cmd) => cmd.run(),
             SubCommand::Macos(cmd) => cmd.run(),
+            SubCommand::TestLinuxFuse(cmd) => cmd.run(),
         }
     }
 }
@@ -56,6 +71,10 @@ enum SubCommand {
     Lint(CommandLint),
     #[clap(about = "Run all workspace tests.")]
     Test(CommandTest),
+    #[clap(
+        about = "Run real Linux FUSE acceptance through yy and /dev/fuse (requires isolated S3 settings)."
+    )]
+    TestLinuxFuse(CommandTestLinuxFuse),
     #[clap(about = "Build the macOS native prototypes (requires Xcode 27 and XcodeGen).")]
     Macos(CommandMacos),
 }
@@ -240,6 +259,54 @@ impl CommandTest {
     }
 }
 
+#[derive(Parser)]
+#[clap(name = "test-linux-fuse")]
+struct CommandTestLinuxFuse {
+    #[arg(
+        long,
+        help = "Run only the read-only acceptance stage for independent first-layer validation."
+    )]
+    read_only: bool,
+}
+
+impl CommandTestLinuxFuse {
+    fn run(self) {
+        if !cfg!(target_os = "linux") {
+            panic!("Linux FUSE acceptance requires Linux");
+        }
+        if !std::path::Path::new("/dev/fuse").exists() {
+            panic!(
+                "/dev/fuse is unavailable; refusing to report a green acceptance run without a real mount"
+            );
+        }
+        if which::which("fusermount3").is_err() {
+            panic!(
+                "fusermount3 is unavailable; install fuse3 before running Linux FUSE acceptance"
+            );
+        }
+        for name in [
+            "YINYANG_S3_BUCKET",
+            "YINYANG_S3_ENDPOINT",
+            "YINYANG_S3_REGION",
+            "YINYANG_S3_ACCESS_KEY_ID",
+            "YINYANG_S3_SECRET_ACCESS_KEY",
+        ] {
+            if std::env::var_os(name).is_none() {
+                panic!("{name} is unset; Linux FUSE acceptance fails hard instead of skipping");
+            }
+        }
+        let mut cmd = find_command("cargo");
+        cmd.args(["test", "-p", "yinyang", "--test", "linux_fuse"]);
+        if self.read_only {
+            cmd.arg("fuse_read_only_");
+        } else {
+            cmd.arg("fuse_");
+        }
+        cmd.args(["--", "--ignored", "--nocapture", "--test-threads=1"]);
+        run_command(cmd);
+    }
+}
+
 fn find_command(cmd: &str) -> StdCommand {
     match which::which(cmd) {
         Ok(exe) => {
@@ -339,3 +406,16 @@ fn make_cargo_deny_cmd() -> StdCommand {
     cmd.args(["deny", "check", "licenses"]);
     cmd
 }
+
+#[cfg(test)]
+mod tests {
+    use super::parse_error_exit_code;
+    use clap::error::ErrorKind;
+
+    #[test]
+    fn parse_errors_are_nonzero_except_help_and_version() {
+        assert_eq!(parse_error_exit_code(ErrorKind::DisplayHelp), 0);
+        assert_eq!(parse_error_exit_code(ErrorKind::DisplayVersion), 0);
+        assert_eq!(parse_error_exit_code(ErrorKind::UnknownArgument), 2);
+    }
+}