v0.17.10: bounded-cache writeback pipeline for big sequential writes

Pass 1 sweep speed on a healthy disc previously dipped from ~15 MB/s
to ~1 MB/s every ~30 s on a host with default Linux dirty-page
settings. Empirical cause: the kernel's vm.dirty_ratio (~20% of RAM)
lets hundreds of MB of dirty pages accumulate, then bursts a flush at
99% disk utilisation that blocks app writes for ~1 s. Confirmed on
the BU40N test bed — dirty pages grew 112 → 563 MB between bursts;
lowering vm.dirty_bytes to 64 MB at the host sysctl level eliminated
the dips. Shipping the equivalent inside libfreemkv so users do not
need to tune the host kernel.

- New crate::io::Writer: drop-in File wrapper (impl Write + Seek).
  Wraps a per-platform WritebackPipeline that on Linux schedules
  sync_file_range(WRITE) + lagging sync_file_range(WAIT_AFTER) +
  posix_fadvise(DONTNEED) in 32 MB chunks, bounding dirty cache at
  ~64 MB. macOS and Windows ship a no-op stub.
- Disc::sweep wraps its output File in Writer. Loop body unchanged.
- Module is purpose-built so any large sequential output (patch,
  mux) can adopt the same wrapper as a one-line change later.

CHANGELOG.md

@@ -1,5 +1,108 @@
 # Changelog
 
+## 0.17.10 (2026-05-09)
+
+### Bounded-cache writeback for big sequential writes
+
+Pass 1 sweep speed on a healthy disc previously dipped from ~15 MB/s
+to ~1 MB/s every ~30 s on a host with default Linux dirty-page
+settings. Cause: the kernel's `vm.dirty_ratio` (~20 % of RAM) lets
+hundreds of MB of dirty pages accumulate, then bursts a flush at
+99 % disk utilisation that blocks app writes for ~1 s. Confirmed
+empirically on the BU40N test bed: dirty pages grew 112 → 563 MB
+between bursts; lowering `vm.dirty_bytes` to 64 MB at the host
+sysctl level eliminated the dips.
+
+This release ships the equivalent inside libfreemkv so users don't
+need to tune the host kernel:
+
+- New `crate::io::Writer` — drop-in `File` wrapper implementing
+  `Write` + `Seek`. Wraps a per-platform `WritebackPipeline` that on
+  Linux schedules `sync_file_range(WRITE)` + lagging
+  `sync_file_range(WAIT_AFTER)` + `posix_fadvise(DONTNEED)` calls in
+  32 MB chunks, keeping dirty cache bounded at ~64 MB. macOS and
+  Windows ship a no-op stub — their default cache policies don't
+  exhibit the same pathology for our access pattern.
+- Disc::sweep wraps its output `File` in `Writer`. No changes to the
+  loop body — `Writer` forwards `seek`/`write_all` to `File` and
+  drives the pipeline transparently.
+- Module is purpose-built for any large sequential output (sweep,
+  patch, future mux) — they can adopt `crate::io::Writer` with a
+  one-line wrapper and inherit the same behaviour.
+
+## 0.17.7 (2026-05-08)
+
+### Sync release — no functional libfreemkv changes
+
+Version bump to keep the four freemkv crates at unified versioning.
+autorip shipped UI smoothness + audit fixes today (v0.17.6, v0.17.7);
+libfreemkv carries no code changes, but is bumped + republished to
+crates.io so downstream `libfreemkv = "0.17"` consumers stay aligned
+on the latest patch version. See autorip CHANGELOG for the
+user-visible work in this release window.
+
+## 0.17.5 (2026-05-08)
+
+### Pass N recovery — kernel block-device fallback + per-range fixes
+
+Live testing on direct-SATA BU40N + AACS-encrypted UHD disc revealed that
+the v0.17.3 single-shot SCSI READ path matched 0/22 of the small bad-sector
+LBAs that `dd if=/dev/sr0` recovers on the same drive. This release closes
+that gap and fixes several adjacent bugs that were silently capping
+recovery.
+
+- **`/dev/sr0` pread fallback in `Drive::read` (Linux)**: when a SCSI READ
+  via `/dev/sg*` returns Err, fall back to `posix_fadvise(POSIX_FADV_DONTNEED)
+  + pread()` against the corresponding block device. The kernel `sr_mod`
+  driver runs ~5 internal retries per command without the per-attempt
+  error-escalation overhead that userspace SG_IO retries pay, which is the
+  source of dd's recovery advantage. End-to-end byte-verification confirms
+  the fallback path returns real disc data (md5-equivalent to fresh dd from
+  the same drive session). The block fd is opened in `Drive::open` by
+  resolving `/sys/class/scsi_generic/sgN/device/block`; best-effort, with no
+  fallback if open fails.
+
+- **`Disc::patch` per-range watchdog fix**: when a range hit `MAX_RANGE_SECS`,
+  the old code did `wedged_exit = true; break 'outer;` — a single slow range
+  killed the entire patch. Now `break;` (skip this range, advance the outer
+  for loop). Pre-fix, patch was dying after 4 sectors of the first slow
+  range and never reaching the other 46.
+
+- **Per-sector range budget**: replaced flat `MAX_RANGE_SECS = 180` with
+  `range_budget_secs = (range_sectors × SECONDS_PER_SECTOR).min(RANGE_BUDGET_CAP_SECS)`.
+  Tiny ranges exit fast (1-sector range = 25 s); medium ranges get
+  proportional time (51-sector range ≈ 1275 s); large ranges still bounded
+  by the 1800 s cap so they cannot monopolise pass 1.
+
+- **`consecutive_failures` resets per range**: the wedge-exit detector
+  (`>= 50 consecutive failures`) is for "stuck on the same range"; pre-fix
+  the counter persisted across ranges, so 50 small post-bisection ranges
+  with one failure each falsely tripped the wedge mid-pass. Reset at every
+  range boundary.
+
+- **Reverted inline 5× retry in patch**: a brief experiment that was
+  measurably harmful — each "2 s" SCSI timeout paid ~1.5 s kernel SCSI
+  mid-layer error-escalation overhead, so 5× retry took ~17 s per LBA and
+  triggered the per-range watchdog in 4 sectors. Restored
+  `READ_RECOVERY_TIMEOUT_MS = 60_000` (the v0.17.3 baseline; the kernel-
+  auto-retry pattern is now provided by the `/dev/sr0` fallback above).
+
+### Empirical results (Dune Part Two UHD, BU40N direct SATA)
+
+- Pass 1: **94.6 MB recovered** (28% of formerly-bad data, 33 sr0 fallback
+  saves), **11 s of main-title content** restored. Patch completed all 47
+  retryable ranges naturally (was wedging at range 1 of 47 in v0.17.3).
+- Pass 2 cumulative: 95.2 MB (+0.6 MB; diminishing returns curve).
+- Remaining ~233 MB on the test disc appears physically unrecoverable on
+  this hardware (kernel auto-retry can't decode it either).
+
+### Behavioural notes
+
+- The `/dev/sr0` fallback is Linux only; macOS and Windows fall back to
+  the existing single-shot SCSI behaviour. The fallback is gated to
+  `recovery=true` reads (only fires from the patch path, not the sweep
+  path) to avoid page-cache pressure during multi-GB sequential ripping.
+
 ## 0.17.0 (2026-05-04)
 
 ### Code quality: unwrap safety, clippy compliance, test coverage

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "libfreemkv"
-version = "0.17.2"
+version = "0.17.10"
 edition = "2024"
 rust-version = "1.86"
 license = "AGPL-3.0-only"

src/disc/mod.rs

@@ -1414,7 +1414,11 @@ impl Disc {
             f
         };
 
-        let mut file = file;
+        // Wrap the raw `File` in our bounded-cache writer so the
+        // kernel's writeback queue drains continuously instead of
+        // accumulating hundreds of MB of dirty pages and then bursting
+        // a flush that blocks app writes (see `crate::io`).
+        let mut file = crate::io::Writer::new(file).map_err(|e| Error::IoError { source: e })?;
         let batch: u16 = match opts.batch_sectors {
             Some(b) => b,
             None if opts.skip_on_error => ecc_sectors(self.format),
@@ -1995,14 +1999,33 @@ impl Disc {
         let mut blocks_attempted: u64 = 0;
         let mut blocks_read_ok: u64 = 0;
         let mut blocks_read_failed: u64 = 0;
-        let mut consecutive_failures: u64 = 0;
+        // Reset to 0 at the start of every range; declared without init
+        // because the per-range reset (below) always runs before any read.
+        let mut consecutive_failures: u64;
         let mut unreadable_count: u64 = 0;
         let mut bytes_good_last = bytes_good_before;
         let mut stall_start = std::time::Instant::now();
         let mut range_start;
         let mut range_bytes_good;
         const STALL_SECS: u64 = 3600;
-        const MAX_RANGE_SECS: u64 = 180;
+        // Per-range budget = sectors_in_range × SECONDS_PER_SECTOR, capped
+        // at RANGE_BUDGET_CAP. Replaces the old flat 180 s/range — that
+        // was unfair to medium ranges (a 51-sector range got the same
+        // 180 s as a 1-sector range, so multi-sector ranges couldn't
+        // even attempt every sector inside their budget) and pointlessly
+        // generous to single-sector ranges (180 s when ~5 s would do).
+        // The cap keeps catastrophic ranges (10s of MB) bounded so they
+        // can't consume the entire patch run; multi-pass orchestration
+        // raises the cap on later passes for the genuinely-stuck ones.
+        // Empirical per-failed-sector cost on direct-SATA BU40N (2026-05-08):
+        // ~3 s SCSI READ failure + ~15 s sr0 pread fallback (kernel sr_mod
+        // does ~5 internal retries) ≈ 18-25 s total. SECONDS_PER_SECTOR=25
+        // lets a small range fully sample within budget instead of bailing
+        // after one slow read. Previous value of 5 was too tight: a
+        // 3-sector range got 15 s budget but the first failed read alone
+        // took ~20 s, so the watchdog fired before sector 2 could be tried.
+        const SECONDS_PER_SECTOR: u64 = 25;
+        const RANGE_BUDGET_CAP_SECS: u64 = 1800;
         const MAX_SKIPS_PER_RANGE: u32 = 10;
         let mut skip_count: u32;
         let mut buf = vec![0u8; block_sectors as usize * 2048];
@@ -2132,6 +2155,24 @@ impl Disc {
             range_start = std::time::Instant::now();
             range_bytes_good = bytes_good_before;
             skip_count = 0;
+            // Reset consecutive_failures at each range boundary. The
+            // wedge-exit detector is for "stuck on the same range" — many
+            // tiny ranges that each fail their one sampled sector should
+            // NOT trigger it. Pre-fix: pass 2 hit 134 small post-pass-1
+            // ranges, each contributing a single failure, and tripped
+            // wedged_threshold=50 around range 27/134 — a false positive
+            // that aborted the rest of the pass.
+            consecutive_failures = 0;
+            let range_sectors = *range_size / 2048;
+            let range_budget_secs = (range_sectors * SECONDS_PER_SECTOR).min(RANGE_BUDGET_CAP_SECS);
+            tracing::debug!(
+                target: "freemkv::disc",
+                phase = "patch_range_budget",
+                range_lba = *range_pos / 2048,
+                range_sectors,
+                range_budget_secs,
+                "Per-range time budget computed"
+            );
             loop {
                 if let Some(ref h) = opts.halt {
                     if h.load(std::sync::atomic::Ordering::Relaxed) {
@@ -2140,39 +2181,47 @@ impl Disc {
                     }
                 }
 
-                // Test 1: Range timeout - max 3 minutes per range
-                if range_start.elapsed().as_secs() > MAX_RANGE_SECS {
+                // Per-range watchdog: budget = range_sectors × 5 s, capped
+                // at RANGE_BUDGET_CAP_SECS. Tiny ranges exit fast (1-sector
+                // range = 5 s budget); medium ranges get proportional time
+                // (51-sector range = 255 s); huge ranges still bounded by
+                // the cap so they can't monopolise pass 1.
+                //
+                // Both the absolute-elapsed and no-progress checks share
+                // the same per-range budget. The progress check resets
+                // range_start on every byte gained, so a steadily-recovering
+                // range can run as long as it makes progress.
+                if range_start.elapsed().as_secs() > range_budget_secs {
                     tracing::warn!(
                         target: "freemkv::disc",
                         phase = "patch_range_timeout",
                         range_lba = range_pos / 2048,
+                        range_sectors,
                         elapsed_secs = range_start.elapsed().as_secs(),
-                        bytes_recovered = bytes_good_before - range_bytes_good,
-                        "Range timeout - no progress in {}s, aborting",
-                        MAX_RANGE_SECS
+                        budget_secs = range_budget_secs,
+                        bytes_recovered = range_bytes_good.saturating_sub(bytes_good_before),
+                        "Range timeout - moving to next range"
                     );
-                    wedged_exit = true;
-                    break 'outer;
+                    break;
                 }
 
-                // Test 2: Range progress - must recover bytes in 60 seconds
                 let bytes_good_now = map.stats().bytes_good;
                 if bytes_good_now > range_bytes_good {
                     range_bytes_good = bytes_good_now;
                     range_start = std::time::Instant::now();
                 }
-                if range_start.elapsed().as_secs() > MAX_RANGE_SECS {
+                if range_start.elapsed().as_secs() > range_budget_secs {
                     tracing::warn!(
                         target: "freemkv::disc",
                         phase = "patch_range_stall",
                         range_lba = range_pos / 2048,
+                        range_sectors,
                         elapsed_secs = range_start.elapsed().as_secs(),
-                        bytes_recovered = bytes_good_before - range_bytes_good,
-                        "Range stalled - no recovery in {}s, aborting",
-                        MAX_RANGE_SECS
+                        budget_secs = range_budget_secs,
+                        bytes_recovered = range_bytes_good.saturating_sub(bytes_good_before),
+                        "Range stalled - moving to next range"
                     );
-                    wedged_exit = true;
-                    break 'outer;
+                    break;
                 }
 
                 // Test 3: Skip count - max 10 skips per range
@@ -2264,6 +2313,16 @@ impl Disc {
                     }
                 }
 
+                // Single-shot read. Inline retry was tried 2026-05-08 and
+                // actively hurt: each timeout pays kernel SCSI mid-layer
+                // error-escalation overhead (~1.5 s per attempt on top of
+                // the SCSI timeout), so 5× retry made each LBA take ~17 s
+                // and forced MAX_RANGE_SECS to fire after 4 sectors. The
+                // win that motivated the experiment (matching dd via
+                // /dev/sr0) is being pursued instead through a /dev/sr0
+                // pread-based fallback layer that lets the kernel
+                // sr_mod driver run its own auto-retries (which don't
+                // pay per-attempt escalation in the same way).
                 let read_start = std::time::Instant::now();
                 let read_result = reader.read_sectors(lba, count, &mut buf[..bytes], recovery);
                 let read_duration_ms = read_start.elapsed().as_millis();

src/drive/mod.rs

@@ -69,6 +69,16 @@ pub struct Drive {
     halt: Arc<AtomicBool>,
     /// Event handler — fires for read errors and library-level state changes.
     event_fn: Option<Box<dyn Fn(Event) + Send>>,
+    /// Linux only: raw fd for the corresponding block device (`/dev/sr*`)
+    /// used as a recovery fallback when SCSI READ via `/dev/sg*` returns
+    /// an error. The kernel `sr_mod` driver auto-retries failed reads
+    /// (~5× per command) — historically the reason `dd if=/dev/sr0`
+    /// recovers ~50% of bad sectors that single-shot `SG_IO` READ
+    /// misses on the same drive. `None` when the block device couldn't
+    /// be resolved or opened (no fallback in that case; SCSI read
+    /// errors propagate as before).
+    #[cfg(target_os = "linux")]
+    block_dev_fd: Option<std::os::unix::io::RawFd>,
 }
 
 impl Drive {
@@ -87,6 +97,9 @@ impl Drive {
             None => (None, None, None),
         };
 
+        #[cfg(target_os = "linux")]
+        let block_dev_fd = open_block_device_for_sg(device);
+
         Ok(Drive {
             scsi: transport,
             driver,
@@ -96,6 +109,8 @@ impl Drive {
             device_path: device.to_string_lossy().to_string(),
             halt: Arc::new(AtomicBool::new(false)),
             event_fn: None,
+            #[cfg(target_os = "linux")]
+            block_dev_fd,
         })
     }
 
@@ -483,6 +498,54 @@ impl Drive {
                     scsi_status = status,
                     "Drive::read checked_exec failed"
                 );
+
+                // /dev/sr0 pread fallback (Linux only). The kernel
+                // sr_mod driver auto-retries failed reads (~5× per
+                // command). Empirically (BU40N + Dune Part 2 UHD,
+                // 2026-05-08) dd via /dev/sr0 recovers ~50% of bad
+                // sectors that a single-shot SG_IO READ misses.
+                #[cfg(target_os = "linux")]
+                if recovery {
+                    if let Some(fd) = self.block_dev_fd {
+                        let len = count as usize * 2048;
+                        if buf.len() >= len {
+                            let offset = lba as i64 * 2048;
+                            // Drop kernel cache for this region so we get
+                            // a fresh device read, not stale page-cache
+                            // data from a prior successful neighbour read.
+                            let _ = unsafe {
+                                libc::posix_fadvise(
+                                    fd,
+                                    offset,
+                                    len as i64,
+                                    libc::POSIX_FADV_DONTNEED,
+                                )
+                            };
+                            let n = unsafe {
+                                libc::pread(fd, buf.as_mut_ptr() as *mut libc::c_void, len, offset)
+                            };
+                            if n == len as isize {
+                                tracing::info!(
+                                    target: "freemkv::drive",
+                                    lba,
+                                    count,
+                                    bytes = len,
+                                    "Drive::read recovered via /dev/sr0 pread fallback"
+                                );
+                                return Ok(len);
+                            }
+                            tracing::debug!(
+                                target: "freemkv::drive",
+                                lba,
+                                count,
+                                pread_ret = n as i64,
+                                errno = std::io::Error::last_os_error().raw_os_error().unwrap_or(0),
+                                "/dev/sr0 pread fallback also failed"
+                            );
+                        }
+                    }
+                }
+
                 Err(Error::DiscRead {
                     sector: lba as u64,
                     status: Some(status),
@@ -586,6 +649,61 @@ impl Drop for Drive {
     fn drop(&mut self) {
         self.cleanup();
         // SgIoTransport::drop() runs next, calling libc::close(fd)
+        #[cfg(target_os = "linux")]
+        if let Some(fd) = self.block_dev_fd.take() {
+            unsafe { libc::close(fd) };
+        }
+    }
+}
+
+/// Resolve a `/dev/sg*` path to the corresponding `/dev/sr*` block
+/// device by walking sysfs, then open it for read (no `O_DIRECT` —
+/// `posix_fadvise(POSIX_FADV_DONTNEED)` flushes the cache before each
+/// pread, which avoids buffer-alignment requirements while still
+/// forcing fresh device reads).
+///
+/// Returns `None` on any error (sysfs not present, no matching block
+/// device, open failed). Callers treat that as "no fallback available"
+/// and propagate the original SCSI READ error.
+#[cfg(target_os = "linux")]
+fn open_block_device_for_sg(sg_path: &Path) -> Option<std::os::unix::io::RawFd> {
+    let basename = sg_path.file_name()?.to_str()?;
+    if !basename.starts_with("sg") {
+        return None;
+    }
+    let sysfs_dir = format!("/sys/class/scsi_generic/{}/device/block", basename);
+    let entries = std::fs::read_dir(&sysfs_dir).ok()?;
+    let block_name = entries
+        .flatten()
+        .find_map(|e| e.file_name().into_string().ok())?;
+    let block_path = format!("/dev/{}", block_name);
+
+    let mut bytes = block_path.as_bytes().to_vec();
+    bytes.push(0);
+    let fd = unsafe {
+        libc::open(
+            bytes.as_ptr() as *const libc::c_char,
+            libc::O_RDONLY | libc::O_CLOEXEC,
+        )
+    };
+    if fd < 0 {
+        tracing::debug!(
+            target: "freemkv::drive",
+            sg = basename,
+            block_path,
+            errno = std::io::Error::last_os_error().raw_os_error().unwrap_or(0),
+            "Failed to open block device for fallback; sr0 fallback disabled"
+        );
+        None
+    } else {
+        tracing::info!(
+            target: "freemkv::drive",
+            sg = basename,
+            block_path,
+            fd,
+            "Opened /dev/sr* as recovery fallback for failed SCSI reads"
+        );
+        Some(fd)
     }
 }
 

src/io/mod.rs

@@ -0,0 +1,16 @@
+//! File I/O helpers that bound kernel cache pressure on big writes.
+//!
+//! `Writer` is a drop-in wrapper around `std::fs::File` for any call
+//! site that performs large sequential writes (sweep, mux, etc.). It
+//! implements `Write` and `Seek` so existing code paths can swap
+//! `File` for `Writer` with no body changes. Internally it drives a
+//! `WritebackPipeline` that, on Linux, drains dirty pages continuously
+//! at 32 MB granularity to avoid the kernel's accumulate-then-burst
+//! flush behaviour. macOS and Windows use a no-op pipeline — their
+//! default cache policies have not been shown to exhibit the same
+//! pathology for this access pattern.
+
+mod writeback;
+mod writer;
+
+pub(crate) use writer::Writer;

src/io/writeback.rs

@@ -0,0 +1,17 @@
+//! Per-platform writeback pipeline. On Linux, drains dirty pages
+//! continuously at chunk granularity to keep the kernel's writeback
+//! queue bounded. On macOS and Windows, a no-op stub.
+//!
+//! The platform decision lives entirely in this file (the cfg-gated
+//! `pub use` below). Callers — and `DiskWriter` itself — are
+//! platform-independent.
+
+#[cfg(target_os = "linux")]
+mod linux;
+#[cfg(not(target_os = "linux"))]
+mod noop;
+
+#[cfg(target_os = "linux")]
+pub(super) use linux::WritebackPipeline;
+#[cfg(not(target_os = "linux"))]
+pub(super) use noop::WritebackPipeline;

src/io/writeback/linux.rs

@@ -0,0 +1,95 @@
+//! Linux writeback pipeline using `sync_file_range` + `posix_fadvise`.
+//!
+//! Pathology this fixes: the kernel's default `vm.dirty_ratio` (~20 %
+//! of RAM) lets dirty pages accumulate to hundreds of MB during a
+//! big sequential write, then bursts a flush at 99 % disk utilisation.
+//! While the burst runs, app writes block on the writeback queue —
+//! observed empirically as instantaneous speed dropping from ~15 MB/s
+//! to ~1 MB/s every ~30 s during a Pass 1 sweep.
+//!
+//! Strategy: every `chunk_bytes` of new sequential output, kick async
+//! writeback (`SYNC_FILE_RANGE_WRITE`) on the just-completed chunk and
+//! finalise the *previous* chunk via `WAIT_AFTER` + `posix_fadvise
+//! (DONTNEED)`. By the time we finalise, that previous chunk has had
+//! a full chunk's worth of work to flush — the wait is near-instant.
+//! Dirty cache stays bounded at ~2 × `chunk_bytes` and writes drain
+//! continuously instead of in bursts.
+
+use std::fs::File;
+use std::os::unix::io::{AsRawFd, RawFd};
+
+pub(crate) struct WritebackPipeline {
+    fd: RawFd,
+    chunk_bytes: u64,
+    last_flush_pos: u64,
+    pending: Option<(u64, u64)>,
+}
+
+impl WritebackPipeline {
+    pub(crate) fn new(file: &File, start_pos: u64, chunk_bytes: u64) -> Self {
+        Self {
+            fd: file.as_raw_fd(),
+            chunk_bytes,
+            last_flush_pos: start_pos,
+            pending: None,
+        }
+    }
+
+    /// Caller advanced the file position to `pos`. If a chunk boundary
+    /// was crossed, kick async writeback for the just-completed chunk
+    /// and finalise the previous one.
+    pub(crate) fn note_progress(&mut self, pos: u64) {
+        if pos < self.last_flush_pos.saturating_add(self.chunk_bytes) {
+            return;
+        }
+        unsafe {
+            let chunk_off = self.last_flush_pos as i64;
+            let chunk_len = (pos - self.last_flush_pos) as i64;
+            libc::sync_file_range(self.fd, chunk_off, chunk_len, libc::SYNC_FILE_RANGE_WRITE);
+            if let Some((prev_off, prev_len)) = self.pending.take() {
+                libc::sync_file_range(
+                    self.fd,
+                    prev_off as i64,
+                    prev_len as i64,
+                    libc::SYNC_FILE_RANGE_WAIT_AFTER,
+                );
+                libc::posix_fadvise(
+                    self.fd,
+                    prev_off as i64,
+                    prev_len as i64,
+                    libc::POSIX_FADV_DONTNEED,
+                );
+            }
+            self.pending = Some((chunk_off as u64, chunk_len as u64));
+        }
+        self.last_flush_pos = pos;
+    }
+
+    /// Caller is about to seek away from the current write region.
+    /// Drain any in-flight chunk and reset tracking.
+    pub(crate) fn handle_seek(&mut self, new_pos: u64) {
+        self.finalize();
+        self.last_flush_pos = new_pos;
+    }
+
+    /// Drain any in-flight chunk. Idempotent. Call before `sync_all()`
+    /// or when discarding the pipeline.
+    pub(crate) fn finalize(&mut self) {
+        if let Some((prev_off, prev_len)) = self.pending.take() {
+            unsafe {
+                libc::sync_file_range(
+                    self.fd,
+                    prev_off as i64,
+                    prev_len as i64,
+                    libc::SYNC_FILE_RANGE_WAIT_AFTER,
+                );
+                libc::posix_fadvise(
+                    self.fd,
+                    prev_off as i64,
+                    prev_len as i64,
+                    libc::POSIX_FADV_DONTNEED,
+                );
+            }
+        }
+    }
+}

src/io/writeback/noop.rs

@@ -0,0 +1,18 @@
+//! No-op writeback pipeline for non-Linux targets. macOS and Windows
+//! page cache policies have not been shown to exhibit the Linux
+//! accumulate-then-burst flush pathology for our access pattern.
+//! If that changes, replace this stub with a real implementation
+//! (e.g. `F_NOCACHE` on macOS, `FILE_FLAG_WRITE_THROUGH` on Windows).
+
+use std::fs::File;
+
+pub(crate) struct WritebackPipeline;
+
+impl WritebackPipeline {
+    pub(crate) fn new(_file: &File, _start_pos: u64, _chunk_bytes: u64) -> Self {
+        Self
+    }
+    pub(crate) fn note_progress(&mut self, _pos: u64) {}
+    pub(crate) fn handle_seek(&mut self, _new_pos: u64) {}
+    pub(crate) fn finalize(&mut self) {}
+}

src/io/writer.rs

@@ -0,0 +1,88 @@
+//! `Writer` — a drop-in `File` wrapper that keeps the kernel page
+//! cache bounded during large sequential output.
+//!
+//! Implements `Write` and `Seek`, so any call site that uses `File`
+//! through those traits (sweep, mux, patch) can swap to `Writer`
+//! without touching the body of the loop. The wrapper tracks the
+//! current file position and forwards each write to a
+//! [`super::writeback::WritebackPipeline`], which on Linux schedules
+//! incremental `sync_file_range` + `posix_fadvise(DONTNEED)` calls
+//! to drain dirty pages continuously instead of letting the kernel
+//! burst-flush hundreds of MB at a time.
+//!
+//! See `super::writeback::linux` for the pathology and the strategy.
+
+use std::fs::{File, Metadata};
+use std::io::{self, Seek, SeekFrom, Write};
+
+use super::writeback::WritebackPipeline;
+
+const CHUNK_BYTES: u64 = 32 * 1024 * 1024;
+
+pub(crate) struct Writer {
+    file: File,
+    pipeline: WritebackPipeline,
+    pos: u64,
+}
+
+impl Writer {
+    /// Wrap an open `File`. The current OS file position is queried
+    /// once so the pipeline starts tracking from wherever the file
+    /// already is (typically 0 for fresh files; non-zero for resumed
+    /// or appended files).
+    pub(crate) fn new(mut file: File) -> io::Result<Self> {
+        let pos = file.stream_position()?;
+        let pipeline = WritebackPipeline::new(&file, pos, CHUNK_BYTES);
+        Ok(Self {
+            file,
+            pipeline,
+            pos,
+        })
+    }
+
+    pub(crate) fn metadata(&self) -> io::Result<Metadata> {
+        self.file.metadata()
+    }
+
+    /// Drain in-flight writeback then issue a full fsync. Use this in
+    /// place of `File::sync_all`.
+    pub(crate) fn sync_all(&mut self) -> io::Result<()> {
+        self.pipeline.finalize();
+        self.file.sync_all()
+    }
+}
+
+impl Write for Writer {
+    fn write(&mut self, buf: &[u8]) -> io::Result<usize> {
+        let n = self.file.write(buf)?;
+        self.pos += n as u64;
+        self.pipeline.note_progress(self.pos);
+        Ok(n)
+    }
+
+    fn write_all(&mut self, buf: &[u8]) -> io::Result<()> {
+        self.file.write_all(buf)?;
+        self.pos += buf.len() as u64;
+        self.pipeline.note_progress(self.pos);
+        Ok(())
+    }
+
+    fn flush(&mut self) -> io::Result<()> {
+        self.file.flush()
+    }
+}
+
+impl Seek for Writer {
+    fn seek(&mut self, from: SeekFrom) -> io::Result<u64> {
+        let p = self.file.seek(from)?;
+        // Only treat seeks that actually move the position as
+        // boundaries — sweep does a redundant `seek(Current(pos))`
+        // before every write, and we don't want that to drain the
+        // pipeline on every iteration.
+        if p != self.pos {
+            self.pipeline.handle_seek(p);
+            self.pos = p;
+        }
+        Ok(p)
+    }
+}

src/lib.rs

@@ -81,6 +81,7 @@ pub mod error;
 pub mod event;
 pub(crate) mod identity;
 pub(crate) mod ifo;
+pub(crate) mod io;
 pub mod keydb;
 pub(crate) mod labels;
 pub(crate) mod mpls;

src/scsi/mod.rs

@@ -68,10 +68,25 @@ pub(crate) const TUR_TIMEOUT_MS: u32 = 5_000;
 pub(crate) const READ_TIMEOUT_MS: u32 = 10_000;
 
 /// Timeout for content READ commands on the recovery path —
-/// [`disc::Disc::patch`]'s targeted retries on bad ranges. Doubles
-/// the fast-path budget so a sector that fails at 30 s gets one more
-/// honest attempt. Matches sg_dd's default per-command timeout
-/// (`DEF_TIMEOUT = 60000`).
+/// [`disc::Disc::patch`]'s targeted retries on bad ranges. Matches
+/// `sg_dd`'s 60 s ceiling: long enough that any sector the drive can
+/// recover at all gets the time to do so, short enough that an
+/// unresponsive bus is detected before the per-range watchdog fires.
+///
+/// In practice failed reads return in 1–4 s (the drive itself gives up
+/// on uncorrectable ECC before the timeout); the 60 s value is a
+/// safety ceiling, not a steady-state cost.
+///
+/// Historical note (2026-05-08): briefly lowered to 2 s with a 5×
+/// inline retry loop in `Disc::patch` to mimic the kernel `sr_mod`
+/// driver's auto-retry pattern. The synthetic logic worked but on the
+/// live drive each "2 s" read paid ~1.5 s of kernel SCSI mid-layer
+/// error escalation on top, so 5× retries took ~17 s per LBA and
+/// triggered MAX_RANGE_SECS after 4 sectors — pushing recovery to
+/// 0/22 ranges (worse than the 0/22 baseline of v0.17.3 single-shot
+/// at 60 s, since that at least visited every range). Reverted; the
+/// kernel-auto-retry approach is being pursued via a `/dev/sr0` pread
+/// fallback instead.
 pub(crate) const READ_RECOVERY_TIMEOUT_MS: u32 = 60_000;
 
 // ── SCSI status bytes (SPC-4 §4.5.5) ────────────────────────────────────────

tests/scsi_recovery.rs

@@ -24,6 +24,7 @@ fn test_sgio_transport_timeout_does_not_kill_transport() {
         use libfreemkv::scsi::{DataDirection, SCSI_STATUS_TRANSPORT_FAILURE};
         use std::sync::Arc;
         use std::sync::atomic::{AtomicI32, Ordering};
+        use std::time::Duration;
 
         let mut transport = SgIoTransport::open(_path).expect("open device");
         let fd_before = transport.fd;
@@ -93,6 +94,8 @@ fn test_drive_read_per_cdb_timeout_bounds_call() {
 
     #[cfg(target_os = "linux")]
     {
+        use std::time::Duration;
+
         let mut drive = libfreemkv::Drive::open(_path).expect("open drive");
         let timeout_ms: u32 = 5_000;