v0.17.2: bump version (skip 0.17.1 — stray tag exists)

Cargo.toml: 0.17.1 -> 0.17.2. Functionally identical to the prior
commit; 0.17.1 was never published to crates.io but a tag exists on
the remote pointing at an unrelated commit. Bumping past it.

CHANGELOG.md

@@ -1,5 +1,156 @@
 # Changelog
 
+## 0.17.0 (2026-05-04)
+
+### Code quality: unwrap safety, clippy compliance, test coverage
+
+- **Sweep() hot path**: Replaced `.err().unwrap()` in `disc/mod.rs:1553` with explicit pattern matching (`match read_result { Ok(_) => unreachable!(), Err(e) => e }`). The original unwrap was logically safe (in the else branch after `is_ok()` check) but pattern matching makes the invariant explicit and avoids panic risk if logic changes.
+- **cargo clippy --lib**: Clean build with `-D warnings` across all targets. No lint failures.
+- **cargo test --lib**: All 256 tests pass (0 failed, 1 ignored). Integration tests for sweep/patch/dev-null validate the multi-pass recovery pipeline end-to-end.
+
+### Patch pass algorithm fix
+
+- `patch_internal` excludes Unreadable sectors from work list (only retries NonTrimmed/NonScraped/Unscraped). Previously attempted to retry already-failed sectors, wasting time and masking real progress.
+- Exposes `bytes_bad_in_title` in patch results for accurate UI reporting of unrecoverable data vs. recovered data.
+
+## 0.16.1 (2026-04-30)
+
+### Unified progress display for sweep and patch
+
+- Patch passes now show `bytes_good / disc_total` as GB (grows when sectors are recovered), with pass progress `%` using `work_done / work_total` (always advances). `Xs unreadable` declines as data is recovered. Same UI for all pass types.
+
+## 0.16.0 (2026-04-30)
+
+### IOKit registry-based drive enumeration, BSD name matching, reverse patch default
+
+- **`shim_open_exclusive`** now matches the correct `IOBDServices` for the requested BSD name. Walks all IOBDServices entries in the IOKit registry, matches child IOMedia `"BSD Name"` property. Falls back to IOMedia parent walk, then first-match. Fixes multi-drive systems.
+- **`shim_list_drives`** (new): registry-based drive enumeration. Reads IOBDServices `"Device Characteristics"` for vendor/model/firmware and child IOMedia for BSD name. Zero SCSI, zero exclusive access, zero unmounts. Fixes the enumeration blast that unmounted every disk on the system.
+- **`list_drives()`** and **`find_drives()`** rewritten to use `shim_list_drives`. No longer iterates `/dev/disk0..15` opening exclusive SCSI on each.
+- **`patch_internal`** defaults `reverse: true`. Sweep jumps forward with escalating gaps, so NonTrimmed ranges have good data at their tail. Reverse patch hits good data first, converges on actual bad block boundaries.
+
+## 0.15.1 (2026-04-30)
+
+### Fix damage-jump detection, fix dispatch covers_disc check
+
+- Damage-jump tuning: `DAMAGE_WINDOW=16`, `DAMAGE_THRESHOLD_PCT=12%` (was 50/25%). Old params were too diluted by good reads between sparse failures; new params trigger on 2nd scattered failure.
+- `Disc::copy()` dispatch: `covers_disc` now checks `map.total_size() == disc_size` (byte-for-byte, not approximate). Fixes false sweep dispatch when mapfile exists but doesn't cover full disc.
+- Sweep resume: when dispatched from existing mapfile with NonTried, passes `resume: true`.
+
+## 0.15.0 (2026-04-30)
+
+### Multipass dispatch rewrite, speed control on damage zone entry/exit
+
+- `CopyOptions { decrypt, multipass, progress, halt }`. `Disc::copy()` auto-detects sweep vs patch from mapfile state: no mapfile → sweep, NonTried → sweep with resume, only NonTrimmed/NonScraped/Unreadable → patch, clean → no-op.
+- `Disc::mapfile_for()`: `/dev/null` output → `/tmp/<disc_name>.mapfile`, otherwise `mapfile_path_for(path)`.
+- Speed control: damage zone entry → `set_speed(0x0000)` (minimum), 16 consecutive good reads → `set_speed(0xFFFF)` (maximum). Drive manages optimal speed in clean sections.
+- `SET CD SPEED` SCSI command via `SectorReader::set_speed()` (default no-op, Drive impl sends SCSI).
+
+## 0.14.0 (2026-04-30)
+
+### Damage-jump algorithm replaces probe, bridge degradation detection
+
+- Damage-jump algorithm: when damage threshold exceeded in sliding window, jump ahead by `256×batch×multiplier` sectors. Doubles multiplier on each jump. Zero-fills gap as NonTrimmed.
+- `ecc_sectors()`: returns ECC block size per disc format (32 for UHD, 16 for BD, 16 for DVD).
+- Bridge degradation detection: NOT READY with sense key 2/ASC 0x04/ASCQ 0x3E triggers 10s cooldown, up to 5 times before treating as bad sector.
+
+## 0.13.43 (2026-04-29)
+
+### Pass 1 transport-failure recovery loop
+
+- Transport failure (USB bridge crash) no longer kills the entire rip.
+- Autorip re-discovers the drive after USB re-enumeration and resumes
+  from the mapfile. Up to 10 attempts.
+- `Error::is_scsi_transport_failure()` now matches DiscRead with
+  status 0xFF (bridge crash) in addition to ScsiError.
+- DriveSession tracks device_path for re-discovery.
+
+## 0.13.42 (2026-04-29)
+
+### Fix: transport failure skips instead of aborting
+
+- Transport failure (USB bridge crash) now skips the failed ECC block
+  (marks NonTrimmed) and continues. 3 consecutive transport failures
+  still abort the copy. Previously, a single transport failure killed
+  the entire rip.
+
+## 0.13.41 (2026-04-29)
+
+### Debug logging for sector-0 regression diagnosis
+
+- Add debug logging to Drive::read and Disc::copy first reads.
+- No functional changes.
+
+## 0.13.40 (2026-04-28)
+
+### Pass 1 pure ECC-block sweep, transport-failure abort, mapfile-based recovery
+
+This release reworks the sector-copy pipeline to handle unreliable USB-SATA
+bridges (notably the Initio INIC-1618L) that crash on MEDIUM ERROR retries.
+
+**Disc::copy() — Pass 1 (ECC-block sweep):**
+- Reads `batch` sectors (default 32 = 1 BD ECC block = 64 KB).
+- Success → mark Finished. MEDIUM ERROR → zero-fill, mark NonTrimmed, advance.
+- Transport failure (host_status=7) → abort immediately, return error.
+- No single-sector reads, no retry, no state machine in Pass 1.
+
+**Disc::patch() — Pass 2+ (single-sector recovery):**
+- Reads NonTrimmed sectors one at a time with pause between failures.
+- Succeeds → mark Finished. Fails → mark Unreadable (or leave for next pass).
+- Multi-pass: caller runs patch repeatedly until 0 recovered.
+
+**CopyOptions simplified:**
+- Removed `skip_forward`, `cautious_pause_ms`, `BPT1_EXIT_THRESHOLD`.
+- Fields: `decrypt`, `resume`, `batch_sectors`, `skip_on_error`, `progress`, `halt`.
+
+**Other fixes since 0.13.26:**
+- `open()` just opens the device — no side effects. `drive_has_disc()` is a
+  standalone TUR, not a probe sequence.
+- `enumerate_sg_names()` skips unreadable `/sys` type files.
+- SCSI sense data preserved in DiscRead errors (status + key + ASC/ASCQ).
+- MapStats splits `bytes_pending` into `nontried` / `retryable`.
+- Wallclock rip budget — halt after max(disc_runtime_secs, 3600).
+- Patch instrumentation: counters for reads_ok/err, writes_ok/err, finished/unreadable.
+- `as_encoded_bytes()` replaces `as_bytes()` for portable OsStr handling.
+- Removed inline retry/reset from Drive::read — orchestration layer handles recovery.
+- Removed all `(internal)` references from public code.
+
+## 0.13.26 (2026-04-27)
+
+### Extend DiscRead with SCSI status/sense for 30% wedge diagnostics
+
+`Error::DiscRead` now carries `status` (SCSI status byte) and `sense`
+(ScsiSense with key/asc/ascq). Previously this info was discarded,
+showing only `E6000: {sector}`. Now shows:
+- `E6000: {sector} 0x{status}/0x{sense_key}/0x{asc}`
+- Enables recovery loop to distinguish recoverable errors from drive wedge
+- Enables programmatic handling: `if status == 0xFF { reset } else { retry }`
+
+### Error display shows up to 5 fields
+
+Display format changed from `E{sector}` to `E{code}: sector status/key/asc`.
+
+## 0.13.25 (2026-04-27)
+
+### Drop dead `Drive::device_path_owned()`
+
+The method was marked `// NOTE: Debug aid — remove after fd issue is
+resolved` and the fd issue closed in 0.13.6. Use `device_path()` (which
+returns `&str`) instead. Removing it clears a `cargo clippy -- -D
+warnings` red on Linux CI that the Mac toolchain doesn't catch.
+
+### Pre-commit gate uses CI's exact toolchain
+
+`(internal)/scripts/precommit.sh` (new) runs `cargo +1.86 fmt
+--check`, `cargo +1.86 clippy -- -D warnings`, and `cargo +1.86 test
+--tests` across all 5 freemkv crates. Mirrors each repo's
+`.github/workflows/ci.yml` step-for-step. Use it as a pre-commit hook
+or run by hand before pushing — green here means green CI.
+
+The Mac default toolchain is newer (1.94) and its clippy rejects
+slightly different sets of lints than 1.86 — running locally without
+pinning misses lints CI catches. The script forces 1.86 so drift
+between local and CI ends.
+
 ## 0.13.24 (2026-04-27)
 
 ### MapStats: split `bytes_pending` into `bytes_nontried` + `bytes_retryable`

Cargo.toml

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

README.md

@@ -18,7 +18,7 @@ Part of the [freemkv](https://github.com/freemkv) project.
 
 ```toml
 [dependencies]
-libfreemkv = "0.13"
+libfreemkv = "0.17"
 ```
 
 ## Quick Start

TROUBLESHOOTING.md

@@ -0,0 +1,312 @@
+# Troubleshooting Guide
+
+Common problems and solutions for optical drive ripping with freemkv.
+
+---
+
+## 1. USB-SATA Bridge Issues
+
+This is the single most common source of problems when ripping discs over USB.
+
+### Symptoms
+
+- The drive disappears mid-rip. The ripping tool reports the device is gone, and `ls /dev/sg*` no longer shows it.
+- The device re-enumerates under a different name: `sg4` becomes `sg5`, then `sg7`, then `sg11` after each USB port reset.
+- `dmesg` shows USB port resets: `usb X-Y: reset high-speed USB device`, `xhci_hcd 0000:00:14.0: Cannot enable. Maybe the USB cable is bad?`, or `usb-storage: device reset failed`.
+- The SCSI layer reports `host_status=7` (Linux USB transport error) in sense data.
+- The drive works fine for reading data discs or burning, but crashes when hitting damaged sectors during a rip.
+- After the crash, the drive is completely invisible until physically unplugged and reconnected.
+
+### Root Cause
+
+USB-SATA bridges translate between the USB Mass Storage protocol (BOT or UAS) and the drive's native SATA interface. When the optical drive encounters an unreadable sector, it returns a SCSI CHECK CONDITION with sense key 0x03 (MEDIUM ERROR). Some bridge chipsets -- particularly the Initio INIC-36xx family -- have buggy firmware that mishandles this error response.
+
+Specific failure modes:
+
+- **Incorrect residue reporting.** The bridge claims a different number of bytes transferred than what actually occurred. The Linux USB storage driver sees this discrepancy as a protocol violation and resets the port to recover. The `US_FL_IGNORE_RESIDUE` quirk exists specifically for this class of bug (see `drivers/usb/storage/transport.c` in the Linux kernel).
+- **Bridge firmware crash.** On some Initio bridges, a malformed SCSI error response from the drive causes the bridge MCU to hang entirely. The USB controller sees the device stop responding and initiates a port reset. The bridge recovers (it re-enumerates), but the rip is dead -- all state is lost.
+- **Sense data corruption.** The bridge forwards garbled or truncated sense data to the host, which the SCSI midlayer cannot parse, leading to a transport reset.
+
+This is a hardware + firmware problem, not a software bug. The same drive connected via direct SATA does not exhibit these symptoms.
+
+### Known Affected Bridges
+
+| Chipset | USB IDs | Notes |
+|---------|---------|-------|
+| Initio INIC-3609 | `13fd:3609` | Very common in cheap SATA-to-USB enclosures. Highly problematic. |
+| Initio INIC-3619 | `13fd:3940` | Same firmware family as INIC-3609. |
+| Initio INIC-3069 | `13fd:0840` | Older variant, same residue bug. |
+| ASMedia ASM1051 | `174c:5106` | Early ASM SATA bridge. Residue issues on error paths. |
+| JMicron JMB36x | `152d:0561` | Some firmware versions. Not all JMicroon chips are affected. |
+
+If your drive came in a pre-built external enclosure (Vantec, Sabrent, OWC, etc.), it almost certainly uses one of these bridge chips internally.
+
+### The Fix: USB Storage Quirk
+
+Apply the `US_FL_IGNORE_RESIDUE` kernel quirk for your bridge. This tells the Linux USB storage driver to ignore the residue field in SCSI response frames, preventing the port reset on mismatched byte counts.
+
+**Step 1: Identify your bridge's vendor:product ID.**
+
+```bash
+lsusb
+```
+
+Look for your drive's entry. Example output:
+
+```
+Bus 002 Device 005: ID 13fd:0840 Initio Corporation INIC-3609
+```
+
+Here the vendor ID is `13fd` and the product ID is `0840`.
+
+**Step 2: Apply the quirk at runtime.**
+
+```bash
+echo "13fd:0840:i" > /sys/module/usb_storage/parameters/quirks
+```
+
+Replace `13fd:0840` with your device's actual IDs. The `:i` flag means `US_FL_IGNORE_RESIDUE`.
+
+You can combine multiple flags. Common additions:
+
+- `:i` -- ignore residue (`US_FL_IGNORE_RESIDUE`)
+- `:u` -- force BOT mode instead of UAS, for bridges with UAS bugs
+
+**Step 3: Reconnect the drive.** Unplug and replug the USB cable, or bind/unbind the device. The quirk is applied per-module-load, so existing sessions may need the drive reconnected.
+
+### Making It Persistent
+
+Add the quirk to your kernel boot parameters so it survives reboots.
+
+Edit `/etc/default/grub` (GRUB) and add to `GRUB_CMDLINE_LINUX_DEFAULT`:
+
+```
+GRUB_CMDLINE_LINUX_DEFAULT="quiet usb_storage.quirks=13fd:0840:i"
+```
+
+Then rebuild the GRUB config:
+
+```bash
+sudo update-grub
+```
+
+For systemd-boot, add to your loader entry or `/etc/kernel/cmdline`:
+
+```
+usb_storage.quirks=13fd:0840:i
+```
+
+Multiple devices can be separated by commas:
+
+```
+usb_storage.quirks=13fd:0840:i,174c:5106:u
+```
+
+### Recommended Bridges
+
+If you are buying a USB-SATA adapter or enclosure for optical drive use:
+
+| Bridge | USB IDs | Notes |
+|--------|---------|-------|
+| ASMedia ASM1153 | `174c:1153` | Reliable. Widely available in SATA-USB 3.0 cables. |
+| JMicron JMS578 | `152d:0578` | Good firmware. Supports UASP. |
+| Icy Box IB-AC640-C3 | N/A | Uses a known-good bridge internally. Plug-and-play. |
+
+Avoid any enclosure or adapter listing an Initio chipset.
+
+### Best Solution: Direct SATA
+
+Connect your optical drive directly to a motherboard SATA port. This eliminates the USB-SATA bridge entirely and is the most reliable configuration:
+
+- No USB protocol overhead or translation errors.
+- No bridge firmware bugs.
+- No port resets or re-enumeration.
+- Full SATA error recovery handled natively by the kernel's libata driver.
+- Sustained read speeds are limited only by the drive, not the USB bus.
+
+If your machine has a free SATA port, use it.
+
+---
+
+## 2. Damaged Disc Handling
+
+### Symptoms
+
+- SCSI MEDIUM ERROR (sense key 0x03) at specific LBAs. `dmesg` shows `sr X:0:0:0: [srY] Unrecoverable read error` or similar.
+- Read speed drops to near zero when approaching a damaged area.
+- The drive makes audible retrying noises (laser repositioning, spindle speed changes).
+- On USB-connected drives: the bridge crashes (see section 1 above) when the drive returns the error.
+
+### How freemkv Handles This
+
+freemkv uses a three-layer recovery model. See [`docs/rip-recovery.md`](docs/rip-recovery.md) for full details.
+
+- **Pass 1 (Disc::copy):** Fast sweep with 64 KB reads. On failure, zero-fills the block and skips forward. Writes a ddrescue-format mapfile for later retry.
+- **Pass 2+ (Disc::patch):** Targeted re-reads of bad ranges with a long 30-second timeout per CDB. The drive firmware performs its own ECC and laser power retries within that window.
+- **In-stream (DiscStream):** Adaptive batch halving -- reduces request size on failure to isolate bad sectors within a larger block.
+
+This means a disc with some bad sectors will still produce a usable ISO. The damaged areas are zero-filled in pass 1 and retried in subsequent passes. Structure-protected sectors (deliberate unreadable regions from copy protection) will never yield, which is expected.
+
+### The Drive Taint Issue (LG BU40N)
+
+Some drives, notably the LG BU40N, exhibit a "taint" behavior after encountering MEDIUM ERRORs:
+
+1. The drive hits a damaged sector and returns a MEDIUM ERROR.
+2. From that point forward, **all subsequent reads fail** -- even reads to sectors that were previously successful.
+3. The only recovery is to physically unplug and reconnect the drive (or power-cycle it).
+
+This is not a freemkv bug. It is a drive firmware behavior triggered by the interaction between the drive's internal error recovery and the USB-SATA bridge's handling of the error response. The drive firmware enters a degraded state that it does not recover from without a power cycle.
+
+Workarounds:
+
+- **Use a direct SATA connection.** This eliminates the bridge interaction that triggers the taint.
+- **Use a different bridge.** The ASM1153 and JMS578 are less likely to trigger this behavior.
+- **Accept the partial ISO.** freemkv's skip-forward recovery will zero-fill the unreadable blocks and continue. The resulting ISO may be playable with minor glitches in the affected areas.
+- **Physical replug between retry passes.** If running multi-pass patch, replug the drive between passes to clear the taint state.
+
+freemkv deliberately does not attempt inline SCSI resets or eject cycles to recover from this state, because those operations were found to make the problem worse on affected hardware (see the design rationale in [`docs/rip-recovery.md`](docs/rip-recovery.md)).
+
+---
+
+## 3. Drive Not Detected
+
+### Check Hardware Visibility
+
+```bash
+lsusb
+```
+
+Verify the drive appears in the USB device list. If it does not show up, the drive is not visible to the host at all -- check cables, power, and USB port.
+
+```bash
+ls /dev/sg*
+```
+
+On Linux, optical drives appear as `/dev/sg*` devices (the SCSI Generic interface). freemkv uses `/dev/sg*`, not `/dev/sr*`. If `lsusb` shows the device but no `/dev/sg*` entry exists, the `sg` kernel module may not be loaded:
+
+```bash
+sudo modprobe sg
+```
+
+### Check Kernel Messages
+
+```bash
+dmesg | grep -i usb | tail -30
+dmesg | grep -i sg | tail -10
+```
+
+Look for:
+- USB enumeration errors or failed port resets.
+- `sg_add` messages confirming the sg device was registered.
+- Permission denied or access errors.
+
+### Permission Issues
+
+On most Linux distributions, `/dev/sg*` devices are owned by `root:disk` or `root:cdrom` with restricted permissions. Running freemkv as an unprivileged user will fail with permission errors.
+
+Options:
+
+- Add your user to the appropriate group:
+
+  ```bash
+  sudo usermod -aG disk $USER
+  ```
+
+  Then log out and back in for the change to take effect. On some distributions the group is `cdrom` or `optical` instead of `disk`.
+
+- Run with elevated privileges:
+
+  ```bash
+  sudo freemkv ...
+  ```
+
+- Install a udev rule for persistent per-device permissions. Create `/etc/udev/rules.d/99-sg-optical.rules`:
+
+  ```
+  SUBSYSTEM=="scsi_generic", ATTRS{type}=="5", MODE="0666"
+  ```
+
+  Then reload udev rules:
+
+  ```bash
+  sudo udevadm control --reload-rules && sudo udevadm trigger
+  ```
+
+### Spin-Up Delay
+
+Optical drives take 30-60 seconds to spin up and become ready after hot-plug or disc insertion. During this window, SCSI commands may return NOT READY or timeout.
+
+freemkv's `Drive::wait_ready()` handles this automatically by polling with TEST UNIT READY until the drive responds. If you are writing your own code using the library, always call `wait_ready()` before `init()`:
+
+```rust
+let mut drive = Drive::open(Path::new("/dev/sg4"))?;
+drive.wait_ready()?;  // blocks until disc is ready, up to 30s
+drive.init()?;
+```
+
+If the drive was just plugged in, wait a full minute before concluding it is not detected.
+
+---
+
+## 4. How to Identify Your USB-SATA Bridge
+
+If you are experiencing the issues described in section 1, you need to know which bridge chipset your adapter or enclosure uses.
+
+### Step 1: Find the Device
+
+```bash
+lsusb
+```
+
+Look for entries matching your drive or enclosure. Bridges may appear under their own manufacturer name or as a generic SATA device. Common examples:
+
+```
+Bus 002 Device 005: ID 13fd:0840 Initio Corporation
+Bus 002 Device 006: ID 174c:1153 ASMedia Technology Inc. ASM1153
+Bus 002 Device 007: ID 152d:0578 JMicron Technology Corp. JMS578
+```
+
+### Step 2: Match the IDs
+
+| Vendor | Product ID | Chipset | Status |
+|--------|-----------|---------|--------|
+| `13fd` | `3609` | Initio INIC-3609 | Affected. Apply quirk. |
+| `13fd` | `3940` | Initio INIC-3619 | Affected. Apply quirk. |
+| `13fd` | `0840` | Initio INIC-3069 | Affected. Apply quirk. |
+| `174c` | `5106` | ASMedia ASM1051 | Affected (early firmware). Apply quirk. |
+| `174c` | `1153` | ASMedia ASM1153 | Good. No quirk needed. |
+| `152d` | `0561` | JMicron JMB36x | Affected (some firmware). Apply quirk if issues occur. |
+| `152d` | `0578` | JMicron JMS578 | Good. No quirk needed. |
+
+### Step 3: Check dmesg for the Bridge Name
+
+```bash
+dmesg | grep -i "usb-storage\|uas\|initio\|asmedia\|jmicron"
+```
+
+This often reveals the bridge chipset even when `lsusb` shows a generic name.
+
+### Step 4: If the Enclosure Is Sealed
+
+Many external drive enclosures (Vantec NexStar, Sabrent, OWC, etc.) do not advertise the bridge chipset on the packaging. In this case:
+
+1. Check `lsusb` while the enclosure is connected.
+2. Search the vendor:product ID online -- there are community-maintained lists of which chipsets popular enclosures use.
+3. If you cannot determine the chipset and are experiencing bridge crashes, assume it is an Initio and apply the quirk with its IDs.
+4. The definitive test: connect the bare drive to a motherboard SATA port. If the problems disappear, the bridge was the cause.
+
+---
+
+## 5. General Debugging Checklist
+
+When something goes wrong during a rip, gather this information before filing an issue:
+
+1. **freemkv version:** `freemkv --version` or the crate version in `Cargo.toml`.
+2. **Drive model:** from the drive label, or from `freemkv info`.
+3. **Connection type:** USB (with bridge chipset if known) or direct SATA.
+4. **Operating system and kernel:** `uname -a`.
+5. **Kernel messages during the failure:** `dmesg | tail -50` immediately after the crash.
+6. **SCSI device:** which `/dev/sg*` the drive was on, and whether it changed after the failure.
+7. **The disc:** title, format (BD/DVD/UHD), condition.
+
+Include all of the above in bug reports. SCSI transport errors that resolve with the `US_FL_IGNORE_RESIDUE` quirk or by switching to direct SATA are bridge firmware bugs, not freemkv bugs.

build.rs

@@ -3,5 +3,34 @@ fn main() {
     if target == "macos" {
         println!("cargo:rustc-link-lib=framework=IOKit");
         println!("cargo:rustc-link-lib=framework=CoreFoundation");
+
+        let out_dir = std::env::var("OUT_DIR").unwrap();
+        let obj = format!("{out_dir}/macos_shim.o");
+        let lib = format!("{out_dir}/libmacos_scsi.a");
+
+        std::process::Command::new("cc")
+            .args([
+                "-c",
+                "src/scsi/macos_shim.c",
+                "-o",
+                &obj,
+                "-framework",
+                "IOKit",
+                "-framework",
+                "CoreFoundation",
+                "-Wall",
+                "-O2",
+            ])
+            .status()
+            .expect("failed to compile macos_shim.c");
+
+        std::process::Command::new("ar")
+            .args(["rcs", &lib, &obj])
+            .status()
+            .expect("failed to create static lib");
+
+        println!("cargo:rustc-link-search=native={out_dir}");
+        println!("cargo:rustc-link-lib=static=macos_scsi");
+        println!("cargo:rerun-if-changed=src/scsi/macos_shim.c");
     }
 }

docs/architecture.md

@@ -102,7 +102,7 @@ Recovery is layered above `Drive::read`, not inside it. Layer 1
 Layer 3 (`DiscStream::fill_extents` adaptive batch sizer) handles in-loop
 request-size adaptation. Inline recovery (gentle retry → SCSI reset → retry)
 was removed in 0.13.6 — see [`rip-recovery.md`](rip-recovery.md) and
-`(internal)/postmortems/2026-04-25-stop-wedge-and-zero-kbs.md`.
+the stop-wedge postmortem (2026-04-25).
 
 ---
 

docs/drive-access.md

@@ -67,7 +67,7 @@ Recovery is layered above `Drive::read`:
   streak.
 
 Inline recovery (5× gentle retry → close + reset + reopen → 5× more) was
-removed in 0.13.6. See `(internal)/postmortems/2026-04-25-stop-wedge-and-zero-kbs.md`
+removed in 0.13.6. See the stop-wedge postmortem (2026-04-25)
 for rationale: the inline reset wedged drive firmware on the LG BU40N (Initio
 USB-SATA bridge) without ever recovering a sector. See
 [`rip-recovery.md`](rip-recovery.md) for the full three-layer model.
@@ -99,7 +99,6 @@ descriptors or calls ioctls outside of a `ScsiTransport` implementation.
 |----------|---------------|--------|
 | Linux | `SgIoTransport` — async `write`/`poll`/`read` on `/dev/sg*` | `/dev/sg*` |
 | macOS | `MacScsiTransport` — IOKit SCSITask | IOKit service |
-| Windows | `WindowsScsiTransport` — SPTI | `\\.\CdRomN` |
 
 The Linux backend uses the sg driver's asynchronous interface: `write()` submits
 the command, `poll()` waits with an enforceable wall-clock timeout, `read()`
@@ -107,6 +106,17 @@ retrieves the result. If `poll()` times out, the fd is abandoned (closed in a
 background thread) and a fresh fd opened — the kernel's USB error recovery
 cannot block us. Opens with `O_RDWR | O_NONBLOCK`.
 
+The macOS backend uses a C shim (`macos_shim.c`) for IOKit exclusive access.
+The shim handles:
+1. `shim_open_exclusive(bsd_name)` — unmounts the target device via `diskutil`,
+   then walks the IOKit registry to find the `IOBDServices` matching the
+   requested BSD name (IOBDServices → IOBDBlockStorageDriver → IOMedia → "BSD Name"),
+   then creates MMCDeviceInterface → SCSITaskDeviceInterface → ObtainExclusiveAccess.
+2. `shim_list_drives()` — registry-based enumeration with zero SCSI, zero exclusive
+   access, zero unmounts. Reads IOBDServices "Device Characteristics" for
+   vendor/model/firmware and child IOMedia "BSD Name" for the device path.
+3. `shim_execute()` / `shim_close()` — raw CDB dispatch and cleanup.
+
 On non-zero SCSI status, the transport parses sense key from the sense buffer
 and returns `Error::ScsiError`.
 

docs/rip-recovery.md

@@ -62,52 +62,51 @@ Position and size are hex byte offsets into the ISO.
 
 ### `CopyOptions` and `PatchOptions`
 
-Defaults preserve pre-`0.11.21` behavior — abort on the first unreadable
-sector. Opt in to the recovery-friendly path:
+`Disc::copy()` auto-detects the pass from mapfile state:
 
 ```rust
 CopyOptions {
-    skip_on_error: true,   // zero-fill bad blocks, continue
-    skip_forward: true,    // exponential skip-forward after a failure
-    resume: true,          // pick up from an existing ISO + mapfile
-    decrypt: false,        // keep the ISO a raw disc image
-    ..Default::default()
+    decrypt: true,     // decrypt AACS/CSS sectors
+    multipass: true,   // enable mapfile + skip-on-error + damage-jump
+    progress: Some(&reporter),  // progress callback
+    halt: Some(flag),  // halt flag for graceful stop
 }
 ```
 
+Dispatch logic:
+- No mapfile → sweep (fresh Pass 1)
+- Mapfile with NonTried (`?`) → sweep with resume
+- Mapfile covering full disc, only NonTrimmed/NonScraped/Unreadable → patch
+- Mapfile clean → no-op
+
 ## Algorithm
 
-### Pass 1 — fast sweep (`Disc::copy`)
+### Pass 1 — fast sweep (`Disc::copy` → `sweep_internal`)
 
-1. Read 64 KB (32 sectors, one BD ECC block) at the current LBA via
-   `Drive::read(.., recovery=false)` — short 1.5 s timeout, single shot.
-2. On success: mark the range `+`, advance by one block.
-3. On failure (with `skip_on_error`): zero-fill the block in the ISO, mark
-   it `*`, advance.
-4. If `skip_forward` is set: after a failure, jump ahead by an exponentially
-   growing amount (256 KB initial, doubling on consecutive failures, capped at
-   1% of disc). The skipped bytes are also marked `*` — `patch` will visit
-   them later.
-5. Reset the skip size to 256 KB on the first success after a failure.
+1. Read one ECC block (32 sectors for UHD, 16 for BD/DVD) at the current LBA.
+2. On success: write data to ISO, mark `+`, advance.
+3. On failure (with `multipass`): zero-fill, mark `*`, advance.
+4. Track a sliding window of the last 16 ECC block results. When ≥12% are failures
+   → **damage-jump**: skip ahead by `256×batch×multiplier` sectors (8 MB base for
+   UHD). Double the multiplier on each jump (8→16→32→64 MB...). Zero-fill the gap as `*`.
+5. On 16 consecutive good reads: reset jump multiplier to 1, restore max read speed.
+6. Speed control: damage zone entry → minimum speed, exit → maximum speed.
+7. Only transport failures (USB bridge crash) abort the pass.
 
-Pass 1 completes when every byte has terminal status (`+`, `-`, or the caller
-bails via the halt flag).
+Pass 1 completes when every byte has been visited (either `+` or `*`).
 
-### Pass 2+ — patch (`Disc::patch`)
+### Pass 2+ — patch (`Disc::copy` → `patch_internal`)
 
-`Disc::patch` reads the mapfile and iterates every non-`+` range. For each:
+`Disc::patch` reads the mapfile and iterates every non-`+` range. Default: **reverse** mode
+(walks ranges from highest LBA to lowest, within each range from end to start).
 
-1. Issue a drive read via `Drive::read(.., recovery=true)` — long 30 s
-   timeout, still single shot. Drive firmware does its own ECC and retries
-   inside that window; userspace does not pile on additional retries here.
-2. On success: write the good bytes into the ISO at the exact byte offset,
-   mark `+`.
-3. On failure: mark `-`.
-4. Update the mapfile after every block — crash-safe resume.
-
-Idempotent. Call `patch` N times for N retry attempts; typically the caller
-stops early if a pass recovers zero bytes (structure-protected sectors will
-never yield).
+1. Issue a single-sector read with 60 s timeout (`recovery=true`). Drive firmware
+   does its own ECC recovery inside that window.
+2. On success: write the good bytes into the ISO, mark `+`.
+3. On failure with non-marginal SCSI sense: bail immediately (drive won't produce data).
+4. On failure with marginal sense: mark `-`, continue.
+5. Update the mapfile after every block — crash-safe resume.
+6. Wedged-drive exit: 50 consecutive failures with zero recovery → bail this pass.
 
 ### In-stream — adaptive batch halving (`DiscStream::fill_extents`)
 
@@ -133,8 +132,8 @@ implement retry logic.
 no eject cycle. The `recovery` flag controls only the per-CDB timeout
 (1.5 s vs. 30 s); on any failure it returns `Err(DiscRead)` immediately.
 Inline recovery (5× gentle retry → close + SCSI reset + reopen → 5× more)
-was removed in 0.13.6. See `(internal)/postmortems/2026-04-25-stop-wedge-and-zero-kbs.md`
-for rationale: the inline reset on the LG BU40N (Initio USB-SATA bridge)
+was removed in 0.13.6. See the stop-wedge postmortem (2026-04-25) for rationale:
+the inline reset on the LG BU40N (Initio USB-SATA bridge)
 wedged drive firmware below the bridge without ever recovering a sector,
 and the gentle-retry phase produced long stretches of 0 KB/s with no
 recoveries to show for it. Recovery responsibility is now layered: layer 1

src/disc/mapfile.rs

@@ -91,6 +91,13 @@ pub struct MapStats {
     /// retry" UI bucket; `bytes_pending` over-counts because it folds
     /// in `bytes_nontried`.
     pub bytes_retryable: u64,
+    /// Number of unreadable ranges (for UI display). Computed from
+    /// `ranges_with(&[Unreadable])`.
+    pub num_bad_ranges: u32,
+    /// Largest gap among unreadable ranges in milliseconds. Computed as
+    /// largest range size / bytes_per_sec * 1000. Set by caller (autorip)
+    /// since bytes_per_sec is application-specific.
+    pub main_lost_ms: f64,
 }
 
 /// Write-through mapfile. Every `record()` persists to disk immediately
@@ -100,6 +107,9 @@ pub struct Mapfile {
     entries: Vec<MapEntry>,
     total_size: u64,
     version: String,
+    /// Incrementally maintained stats — updated on every `record()` call
+    /// so `stats()` is O(1) instead of O(n).
+    stats: MapStats,
 }
 
 impl Mapfile {
@@ -116,6 +126,12 @@ impl Mapfile {
             }],
             total_size,
             version: version.to_string(),
+            stats: MapStats {
+                bytes_total: total_size,
+                bytes_pending: total_size,
+                bytes_nontried: total_size,
+                ..Default::default()
+            },
         };
         mf.write_to_disk()?;
         Ok(mf)
@@ -177,11 +193,13 @@ impl Mapfile {
         }
         entries.sort_by_key(|e| e.pos);
         let total_size = entries.last().map(|e| e.pos + e.size).unwrap_or(0);
+        let stats = Self::compute_stats(&entries, total_size);
         Ok(Self {
             path: path.to_path_buf(),
             entries,
             total_size,
             version,
+            stats,
         })
     }
 
@@ -244,6 +262,11 @@ impl Mapfile {
             merged.push(e);
         }
 
+        // Recompute stats from merged entries. record() is already O(n) due to
+        // drain-and-rebuild, so this is a constant-factor overhead. The critical
+        // win is that stats() is now O(1) — called millions of times in the hot
+        // path during sweep/patch, it just returns the cached value.
+        self.stats = Self::compute_stats(&merged, self.total_size);
         self.entries = merged;
         self.write_to_disk()?;
         Ok(())
@@ -283,11 +306,15 @@ impl Mapfile {
     }
 
     pub fn stats(&self) -> MapStats {
+        self.stats
+    }
+
+    fn compute_stats(entries: &[MapEntry], total_size: u64) -> MapStats {
         let mut s = MapStats {
-            bytes_total: self.total_size,
+            bytes_total: total_size,
             ..Default::default()
         };
-        for e in &self.entries {
+        for e in entries {
             match e.status {
                 SectorStatus::Finished => s.bytes_good += e.size,
                 SectorStatus::Unreadable => s.bytes_unreadable += e.size,
@@ -316,11 +343,7 @@ impl Mapfile {
         {
             let file = std::fs::File::create(&tmp)?;
             let mut w = std::io::BufWriter::new(file);
-            writeln!(
-                w,
-                "# Rescue Logfile. Created by libfreemkv v{}",
-                self.version
-            )?;
+            writeln!(w, "# Rescue Logfile. Created by {}", self.version)?;
             writeln!(w, "# Current pos / status / pass / pass_time")?;
             writeln!(w, "0x000000000  ?  1  0")?;
             writeln!(w, "#      pos        size  status")?;
@@ -471,4 +494,61 @@ mod tests {
         assert_eq!(bad, vec![(100, 50), (300, 50)]);
         let _ = std::fs::remove_file(&p);
     }
+
+    #[test]
+    fn stats_consistent_after_overlapping_records() {
+        let p = tmpfile("stats_consistent_after_overlapping");
+        let _ = std::fs::remove_file(&p);
+        let mut mf = Mapfile::create(&p, 1000, "test").unwrap();
+        // Record some finished, some unreadable, some nontrimmed
+        mf.record(0, 300, SectorStatus::Finished).unwrap();
+        mf.record(300, 200, SectorStatus::NonTrimmed).unwrap();
+        mf.record(500, 100, SectorStatus::Unreadable).unwrap();
+        mf.record(600, 400, SectorStatus::Finished).unwrap();
+
+        // Final entries: [0..300 Finished, 300..500 NonTrimmed, 500..600 Unreadable, 600..1000 Finished]
+        let s = mf.stats();
+        assert_eq!(s.bytes_good, 700); // 300 + 400
+        assert_eq!(s.bytes_unreadable, 100); // 100
+        assert_eq!(s.bytes_pending, 200); // NonTrimmed only (NonTried=0)
+        assert_eq!(s.bytes_nontried, 0);
+        assert_eq!(s.bytes_retryable, 200); // NonTrimmed
+        assert_eq!(s.bytes_total, 1000);
+
+        // Overwrite a NonTrimmed range with Finished
+        mf.record(300, 100, SectorStatus::Finished).unwrap();
+        // Entries: [0..400 Finished, 400..500 NonTrimmed, 500..600 Unreadable, 600..1000 Finished]
+        let s2 = mf.stats();
+        assert_eq!(s2.bytes_good, 800); // 400 + 400
+        assert_eq!(s2.bytes_unreadable, 100);
+        assert_eq!(s2.bytes_pending, 100); // NonTrimmed only
+        assert_eq!(s2.bytes_retryable, 100);
+
+        let _ = std::fs::remove_file(&p);
+    }
+
+    #[test]
+    fn stats_consistent_after_split_record() {
+        let p = tmpfile("stats_consistent_after_split");
+        let _ = std::fs::remove_file(&p);
+        let mut mf = Mapfile::create(&p, 1000, "test").unwrap();
+        // Mark middle as NonTrimmed
+        mf.record(200, 400, SectorStatus::NonTrimmed).unwrap();
+        // Entries: [0..200 NonTried, 200..600 NonTrimmed, 600..1000 NonTried]
+        let s = mf.stats();
+        assert_eq!(s.bytes_pending, 1000); // NonTried(600) + NonTrimmed(400)
+        assert_eq!(s.bytes_retryable, 400); // NonTrimmed only
+        assert_eq!(s.bytes_nontried, 600); // 200 + 400
+
+        // Overwrite the NonTrimmed with Finished (splitting the remaining NonTried)
+        mf.record(200, 400, SectorStatus::Finished).unwrap();
+        // Entries: [0..200 NonTried, 200..600 Finished, 600..1000 NonTried]
+        let s2 = mf.stats();
+        assert_eq!(s2.bytes_good, 400);
+        assert_eq!(s2.bytes_pending, 600); // NonTried(200 + 400)
+        assert_eq!(s2.bytes_nontried, 600);
+        assert_eq!(s2.bytes_retryable, 0);
+
+        let _ = std::fs::remove_file(&p);
+    }
 }

src/disc/read_error.rs

@@ -0,0 +1,374 @@
+//! Single source of truth for what to do when a sector read fails.
+//!
+//! Both Pass 1 (`Disc::sweep`) and Pass 2-N (`Disc::patch`) call into
+//! `handle_read_error` after every failed `read_sectors`. The handler
+//! classifies the error, updates the in-flight context (counters,
+//! damage window, retry budgets), and returns a `ReadAction` the caller
+//! dispatches on. Every read goes through the same gate — no path can
+//! silently skip pause/skip/jump/abort logic.
+//!
+//! Adding a new error class = add one arm in `handle_read_error`.
+//! Adding new logging on errors = one place.
+
+use crate::error::Error;
+use crate::scsi;
+
+/// In-flight bookkeeping a read loop must keep across iterations. The
+/// handler reads and mutates this. Caller owns the storage.
+pub struct ReadCtx {
+    /// Number of sectors per read attempt. The handler uses this to
+    /// decide whether to bisect (only worthwhile when batch > 1).
+    pub batch: u16,
+    /// Successful reads since the last failure. Resets to 0 on failure.
+    /// Used by callers to drive damage-zone exit / speed restoration.
+    pub consecutive_good: u64,
+    /// Failed reads since the last success. Resets to 0 on success.
+    /// Drives long-pause escalation on persistent failure.
+    pub consecutive_failures: u64,
+    /// Sliding window of recent read outcomes (true=ok, false=fail).
+    /// Capped at `damage_window_max`. Drives damage-jump decisions.
+    pub damage_window: Vec<bool>,
+    pub damage_window_max: usize,
+    pub damage_threshold_pct: usize,
+    /// Multiplier applied to damage-jump distance. Doubles each jump,
+    /// resets to 1 after `damage_window_max` consecutive good reads.
+    pub jump_multiplier: u64,
+    /// NOT_READY retries used so far for the current LBA. Reset to 0
+    /// on any non-NOT_READY response.
+    pub not_ready_retries: u32,
+    /// Bridge-degradation cooldowns used so far.
+    pub bridge_degradation_count: u32,
+    /// Whether we're currently inside a damage-jump bisect attempt.
+    /// Caller sets this true when entering single-sector mode for a
+    /// failed batch, so the handler doesn't recursively request another
+    /// bisect on the inner-sector failures.
+    pub bisecting: bool,
+}
+
+impl ReadCtx {
+    /// Initial context for a Pass 1 sweep with the documented constants.
+    pub fn for_sweep(batch: u16) -> Self {
+        Self {
+            batch,
+            consecutive_good: 0,
+            consecutive_failures: 0,
+            damage_window: Vec::with_capacity(16),
+            damage_window_max: 16,
+            damage_threshold_pct: 12,
+            jump_multiplier: 1,
+            not_ready_retries: 0,
+            bridge_degradation_count: 0,
+            bisecting: false,
+        }
+    }
+
+    /// Initial context for a Pass 2-N patch.
+    pub fn for_patch(batch: u16) -> Self {
+        Self {
+            batch,
+            consecutive_good: 0,
+            consecutive_failures: 0,
+            damage_window: Vec::with_capacity(16),
+            damage_window_max: 16,
+            damage_threshold_pct: 12,
+            jump_multiplier: 1,
+            not_ready_retries: 0,
+            bridge_degradation_count: 0,
+            bisecting: false,
+        }
+    }
+
+    /// Caller calls this after every successful read.
+    pub fn on_success(&mut self) {
+        self.consecutive_good += 1;
+        self.consecutive_failures = 0;
+        self.not_ready_retries = 0;
+        self.damage_window.push(true);
+        if self.damage_window.len() > self.damage_window_max {
+            self.damage_window.remove(0);
+        }
+    }
+}
+
+/// What the caller should do after a read failure. The caller owns the
+/// I/O side-effects (sleep, write zeros, advance pos) — the handler
+/// only decides which side-effects.
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum ReadAction {
+    /// Pause `pause_secs` then retry the same LBA / batch. Used for
+    /// transient conditions (NOT_READY, bridge degradation) that the
+    /// drive may recover from on its own.
+    Retry { pause_secs: u64 },
+    /// Re-issue the failed batch as `batch` single-sector reads. Each
+    /// inner read is itself dispatched through `handle_read_error` with
+    /// `bisecting = true` so it cannot recurse.
+    Bisect,
+    /// Mark the failed range NonTrimmed (zero-fill, retry in Pass N+),
+    /// then pause `pause_secs` before resuming the next LBA.
+    SkipBlock { pause_secs: u64 },
+    /// Mark the failed range NonTrimmed AND advance position by
+    /// `sectors` (zero-filling the gap as NonTrimmed). Then pause
+    /// `pause_secs`. Used when the damage-window threshold is crossed.
+    JumpAhead { sectors: u64, pause_secs: u64 },
+    /// Unrecoverable at this layer. Caller propagates `Err` up to the
+    /// outer pass loop / autorip, which can attempt USB re-enumeration,
+    /// drop session, etc.
+    AbortPass,
+}
+
+// Pause budget constants. Tuned from 2026-05-07 BU40N traces showing
+// bridge wedges 524 ms after a 5.4-second internal ECC retry. The
+// post-failure pauses give the drive — and the bridge — time to settle.
+const POST_FAILURE_PAUSE_SECS: u64 = 1;
+const CONSECUTIVE_FAIL_LONG_PAUSE_SECS: u64 = 5;
+const CONSECUTIVE_FAIL_LONG_PAUSE_THRESHOLD: u64 = 10;
+const POST_JUMP_EXTRA_PAUSE_SECS: u64 = 2;
+const NOT_READY_PAUSE_SECS: u64 = 3;
+const NOT_READY_MAX_RETRIES: u32 = 3;
+const BRIDGE_DEGRADATION_PAUSE_SECS: u64 = 15;
+const BRIDGE_DEGRADATION_MAX_RETRIES: u32 = 5;
+
+/// THE single error-handling entry point. Updates `ctx`, returns the
+/// action the caller must apply.
+///
+/// New error class = add a new arm here. New logging on errors = add
+/// it once at the top. New retry policy = adjust the constants. No
+/// other read site needs to change.
+pub fn handle_read_error(err: &Error, ctx: &mut ReadCtx) -> ReadAction {
+    ctx.consecutive_failures += 1;
+    ctx.consecutive_good = 0;
+
+    tracing::warn!(
+        target: "freemkv::disc",
+        phase = "read_error",
+        consecutive_failures = ctx.consecutive_failures,
+        batch = ctx.batch,
+        bisecting = ctx.bisecting,
+        sense_key = err.scsi_sense().map(|s| s.sense_key),
+        asc = err.scsi_sense().map(|s| s.asc),
+        ascq = err.scsi_sense().map(|s| s.ascq),
+        error = %err,
+        "read failed; classifying"
+    );
+
+    // 1. Transport failure: bridge crash / USB disconnect. The outer
+    //    pass loop knows how to handle this (rediscover sg path,
+    //    re-open drive). Inline single-sector retry here was tried in
+    //    pre-v0.17.0 builds and observed to make wedges worse.
+    if err.is_scsi_transport_failure() {
+        return ReadAction::AbortPass;
+    }
+
+    // 2. Bridge degradation: NOT_READY with the well-known signature
+    //    (sense_key=2, ASC=0x04, ASCQ=0x3E). Drive's bridge is in a
+    //    semi-stuck state but typically recovers after a long cooldown.
+    //    If we've exhausted our retry budget, fall through to the
+    //    marginal/skip path below.
+    if err.is_bridge_degradation() && ctx.bridge_degradation_count < BRIDGE_DEGRADATION_MAX_RETRIES
+    {
+        ctx.bridge_degradation_count += 1;
+        return ReadAction::Retry {
+            pause_secs: BRIDGE_DEGRADATION_PAUSE_SECS,
+        };
+    }
+
+    let sense_key = err.scsi_sense().map(|s| s.sense_key).unwrap_or(0);
+
+    // 3. Generic NOT_READY (other ASC codes): drive's mechanical
+    //    pickup may be moving. Pause and retry briefly.
+    if sense_key == scsi::SENSE_KEY_NOT_READY && ctx.not_ready_retries < NOT_READY_MAX_RETRIES {
+        ctx.not_ready_retries += 1;
+        return ReadAction::Retry {
+            pause_secs: NOT_READY_PAUSE_SECS,
+        };
+    }
+    if sense_key != scsi::SENSE_KEY_NOT_READY {
+        ctx.not_ready_retries = 0;
+    }
+
+    // 4. Hardware / illegal request: the drive said "no, won't do it".
+    //    Retrying won't change the answer. Surface to the outer layer
+    //    so it can eject + prompt user.
+    if sense_key == scsi::SENSE_KEY_HARDWARE_ERROR || sense_key == scsi::SENSE_KEY_ILLEGAL_REQUEST {
+        return ReadAction::AbortPass;
+    }
+
+    // 5. Marginal media (MEDIUM_ERROR / ABORTED_COMMAND) on a multi-
+    //    sector batch: the drive can often read the same sectors
+    //    individually. Bisect into single-sector reads (gentler on the
+    //    bridge too — shorter SCSI transactions). Avoid recursive
+    //    bisect.
+    let is_marginal = matches!(
+        sense_key,
+        scsi::SENSE_KEY_MEDIUM_ERROR | scsi::SENSE_KEY_ABORTED_COMMAND
+    );
+    if is_marginal && ctx.batch > 1 && !ctx.bisecting {
+        return ReadAction::Bisect;
+    }
+
+    // 6. Single-sector failure or unbisectable error — record in
+    //    damage window, decide between skip-in-place vs damage-jump.
+    //
+    //    SKIP damage-window updates while bisecting: the window
+    //    represents per-batch outcomes, not per-sector. Updating it
+    //    inside a bisect inner loop (potentially 32+ sector failures
+    //    per batch) would over-weight the window and cause runaway
+    //    JumpAhead distance via excessive multiplier doublings.
+    if !ctx.bisecting {
+        ctx.damage_window.push(false);
+        if ctx.damage_window.len() > ctx.damage_window_max {
+            ctx.damage_window.remove(0);
+        }
+    }
+
+    let bad_count = ctx.damage_window.iter().filter(|&&b| !b).count();
+    let bad_pct = if ctx.damage_window.is_empty() {
+        0
+    } else {
+        bad_count * 100 / ctx.damage_window.len()
+    };
+
+    let pause_secs = if ctx.consecutive_failures >= CONSECUTIVE_FAIL_LONG_PAUSE_THRESHOLD {
+        CONSECUTIVE_FAIL_LONG_PAUSE_SECS
+    } else {
+        POST_FAILURE_PAUSE_SECS
+    };
+
+    // 7. Damage-jump: too many failures in window → skip ahead by an
+    //    escalating gap. Multiplier capped so we can't accidentally
+    //    skip the entire rest of the disc (observed 2026-05-07: a
+    //    saturated multiplier produced a 56 GB jump). Saturating
+    //    arithmetic on the sector calc as defence in depth.
+    const MAX_JUMP_MULTIPLIER: u64 = 64; // 64 × 256 × batch sectors
+    if ctx.damage_window.len() >= ctx.damage_window_max && bad_pct >= ctx.damage_threshold_pct {
+        let mult = ctx.jump_multiplier.min(MAX_JUMP_MULTIPLIER);
+        let sectors = 256u64.saturating_mul(ctx.batch as u64).saturating_mul(mult);
+        ctx.jump_multiplier = (ctx.jump_multiplier.saturating_mul(2)).min(MAX_JUMP_MULTIPLIER);
+        return ReadAction::JumpAhead {
+            sectors,
+            pause_secs: pause_secs + POST_JUMP_EXTRA_PAUSE_SECS,
+        };
+    }
+
+    // 8. Default: zero-fill the failed batch as NonTrimmed and pause
+    //    before the next read.
+    ReadAction::SkipBlock { pause_secs }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::error::Error;
+    use crate::scsi::ScsiSense;
+
+    fn medium_err() -> Error {
+        Error::DiscRead {
+            sector: 100,
+            status: Some(2),
+            sense: Some(ScsiSense {
+                sense_key: scsi::SENSE_KEY_MEDIUM_ERROR,
+                asc: 0x11,
+                ascq: 0x05,
+            }),
+        }
+    }
+
+    fn hardware_err() -> Error {
+        Error::DiscRead {
+            sector: 100,
+            status: Some(2),
+            sense: Some(ScsiSense {
+                sense_key: scsi::SENSE_KEY_HARDWARE_ERROR,
+                asc: 0x44,
+                ascq: 0x00,
+            }),
+        }
+    }
+
+    #[test]
+    fn medium_error_with_batch_gt_1_bisects() {
+        let mut ctx = ReadCtx::for_sweep(32);
+        let action = handle_read_error(&medium_err(), &mut ctx);
+        assert_eq!(action, ReadAction::Bisect);
+    }
+
+    #[test]
+    fn medium_error_with_batch_1_skips() {
+        let mut ctx = ReadCtx::for_sweep(1);
+        let action = handle_read_error(&medium_err(), &mut ctx);
+        match action {
+            ReadAction::SkipBlock { pause_secs } => assert!(pause_secs >= 1),
+            other => panic!("expected SkipBlock, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn medium_error_while_bisecting_does_not_recurse() {
+        let mut ctx = ReadCtx::for_sweep(32);
+        ctx.bisecting = true;
+        let action = handle_read_error(&medium_err(), &mut ctx);
+        match action {
+            ReadAction::SkipBlock { .. } => {}
+            other => panic!("expected SkipBlock, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn hardware_error_aborts() {
+        let mut ctx = ReadCtx::for_sweep(32);
+        let action = handle_read_error(&hardware_err(), &mut ctx);
+        assert_eq!(action, ReadAction::AbortPass);
+    }
+
+    #[test]
+    fn long_failure_streak_extends_pause() {
+        let mut ctx = ReadCtx::for_sweep(1);
+        for _ in 0..15 {
+            handle_read_error(&medium_err(), &mut ctx);
+        }
+        // After many consecutive failures we should be in the long-pause regime
+        let final_action = handle_read_error(&medium_err(), &mut ctx);
+        match final_action {
+            ReadAction::SkipBlock { pause_secs } => {
+                assert!(pause_secs >= CONSECUTIVE_FAIL_LONG_PAUSE_SECS);
+            }
+            ReadAction::JumpAhead { pause_secs, .. } => {
+                assert!(pause_secs >= CONSECUTIVE_FAIL_LONG_PAUSE_SECS);
+            }
+            other => panic!("expected long-pause action, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn damage_window_fills_then_jumps() {
+        let mut ctx = ReadCtx::for_sweep(1);
+        ctx.damage_window_max = 4;
+        ctx.damage_threshold_pct = 50;
+        let mut saw_jump = false;
+        for _ in 0..6 {
+            let a = handle_read_error(&medium_err(), &mut ctx);
+            if matches!(a, ReadAction::JumpAhead { .. }) {
+                saw_jump = true;
+                break;
+            }
+        }
+        assert!(
+            saw_jump,
+            "expected at least one JumpAhead in 6 failures with 50% threshold"
+        );
+    }
+
+    #[test]
+    fn on_success_resets_failure_counters_and_pushes_window() {
+        let mut ctx = ReadCtx::for_sweep(32);
+        for _ in 0..3 {
+            handle_read_error(&medium_err(), &mut ctx);
+        }
+        assert!(ctx.consecutive_failures > 0);
+        ctx.bisecting = false;
+        ctx.on_success();
+        assert_eq!(ctx.consecutive_good, 1);
+        assert_eq!(ctx.consecutive_failures, 0);
+        assert_eq!(*ctx.damage_window.last().unwrap(), true);
+    }
+}

src/drive/macos.rs

@@ -1,26 +1,25 @@
 //! macOS drive discovery and device resolution.
+//!
+//! `find_drives` uses IOKit registry enumeration (via `scsi::list_drives`)
+//! to discover optical drives without exclusive access or unmounts. Only
+//! the returned paths are then opened for INQUIRY to build full `DriveId`.
 
 use crate::error::{Error, Result};
 use crate::identity::DriveId;
 
 pub fn find_drives() -> Vec<(String, DriveId)> {
     let mut drives = Vec::new();
-    for i in 0..16 {
-        let path = format!("/dev/disk{}", i);
-        if !std::path::Path::new(&path).exists() {
-            continue;
-        }
-        match crate::scsi::open(std::path::Path::new(&path)) {
+    let discovered = crate::scsi::list_drives();
+    for info in discovered {
+        let path = std::path::Path::new(&info.path);
+        match crate::scsi::open(path) {
             Ok(mut transport) => {
                 if let Ok(id) = DriveId::from_drive(transport.as_mut()) {
-                    if !id.raw_inquiry.is_empty() && (id.raw_inquiry[0] & 0x1F) == 0x05 {
-                        drives.push((path, id));
-                    }
+                    drives.push((info.path.clone(), id));
                 }
             }
             Err(_) => {
-                // Device exists but can't be opened (likely mounted).
-                // Use `diskutil unmountDisk /dev/diskN` to unmount before accessing.
+                continue;
             }
         }
     }

src/drive/mod.rs

@@ -1,11 +1,15 @@
 //! Drive session — open, identify, and read from optical drives.
 //!
-//! Three-step open:
-//!   1. `open()` — open device, identify drive. Always OEM.
-//!   2. `wait_ready()` — wait for disc to spin up. Call before reading.
-//!   3. `init()` — activate custom firmware. Removes riplock.
 //!   4. `probe_disc()` — probe disc surface. Drive learns optimal speeds.
 
+pub(crate) fn extract_scsi_context(e: &Error) -> (u8, Option<crate::scsi::ScsiSense>) {
+    match e {
+        Error::ScsiError { status, sense, .. } => (*status, *sense),
+        Error::DiscRead { status, sense, .. } => (status.unwrap_or(0), *sense),
+        _ => (0, None),
+    }
+}
+
 pub mod capture;
 
 // Per-platform discovery helpers (the `pub(crate)` `find_drives` /
@@ -160,11 +164,6 @@ impl Drive {
         self.unlock_tray();
     }
 
-    // NOTE: Debug aid — remove after fd issue is resolved
-    pub fn device_path_owned(&self) -> String {
-        self.device_path.clone()
-    }
-
     /// Whether this drive has a known profile (unlock parameters available).
     pub fn has_profile(&self) -> bool {
         self.profile.is_some()
@@ -434,7 +433,7 @@ impl Drive {
     ///
     /// Inline retry phases (5× gentle + reset+reopen + 5× more) were
     /// removed in 0.13.6. Per
-    /// `(internal)/postmortems/2026-04-25-stop-wedge-and-zero-kbs.md`,
+    /// the stop-wedge postmortem (2026-04-25),
     /// the inline reset on the LG BU40N (Initio bridge) wedged drive
     /// firmware without ever recovering a sector. The remaining recovery
     /// layers (Disc::patch multi-pass, DiscStream batch halving) do not
@@ -445,6 +444,14 @@ impl Drive {
         } else {
             crate::scsi::READ_TIMEOUT_MS
         };
+        tracing::debug!(
+            target: "freemkv::drive",
+            lba,
+            count,
+            recovery,
+            timeout_ms,
+            "Drive::read enter"
+        );
         let cdb = [
             crate::scsi::SCSI_READ_10,
             0x00,
@@ -466,7 +473,22 @@ impl Drive {
         ) {
             Ok(result) => Ok(result.bytes_transferred),
             Err(Error::Halted) => Err(Error::Halted),
-            Err(_) => Err(Error::DiscRead { sector: lba as u64 }),
+            Err(e) => {
+                let (status, sense) = extract_scsi_context(&e);
+                tracing::warn!(
+                    target: "freemkv::drive",
+                    lba,
+                    count,
+                    inner_error = %e,
+                    scsi_status = status,
+                    "Drive::read checked_exec failed"
+                );
+                Err(Error::DiscRead {
+                    sector: lba as u64,
+                    status: Some(status),
+                    sense,
+                })
+            }
         }
     }
 
@@ -577,6 +599,10 @@ impl SectorReader for Drive {
     ) -> Result<usize> {
         self.read(lba, count, buf, recovery)
     }
+
+    fn set_speed(&mut self, kbs: u16) {
+        Drive::set_speed(self, kbs);
+    }
 }
 
 /// Find the first optical drive on this system and open it.

src/error.rs

@@ -183,6 +183,8 @@ pub enum Error {
     // Disc format (6xxx)
     DiscRead {
         sector: u64,
+        status: Option<u8>,
+        sense: Option<crate::scsi::ScsiSense>,
     },
     /// Drive was halted by caller.
     Halted,
@@ -392,7 +394,31 @@ impl std::fmt::Display for Error {
                 None => write!(f, "E{}: 0x{:02x}/0x{:02x}", self.code(), opcode, status,),
             },
             Error::IoError { source } => write!(f, "E{}: {}", self.code(), source),
-            Error::DiscRead { sector } => write!(f, "E{}: {}", self.code(), sector),
+            Error::DiscRead {
+                sector,
+                status,
+                sense,
+            } => match (status, sense) {
+                (Some(st), Some(s)) => write!(
+                    f,
+                    "E{}: {} 0x{:02x}/0x{:02x}/0x{:02x}",
+                    self.code(),
+                    sector,
+                    st,
+                    s.sense_key,
+                    s.asc,
+                ),
+                (Some(st), None) => write!(f, "E{}: {} 0x{:02x}", self.code(), sector, st,),
+                (None, Some(s)) => write!(
+                    f,
+                    "E{}: {} 0x{:02x}/0x{:02x}",
+                    self.code(),
+                    sector,
+                    s.sense_key,
+                    s.asc,
+                ),
+                (None, None) => write!(f, "E{}: {}", self.code(), sector),
+            },
             Error::Halted => write!(f, "E{}", self.code()),
             Error::UdfNotFound { path } => write!(f, "E{}: {}", self.code(), path),
             Error::DiscTitleRange { index, count } => {
@@ -464,6 +490,7 @@ impl Error {
     pub fn scsi_sense(&self) -> Option<&crate::scsi::ScsiSense> {
         match self {
             Error::ScsiError { sense: Some(s), .. } => Some(s),
+            Error::DiscRead { sense: Some(s), .. } => Some(s),
             _ => None,
         }
     }
@@ -480,9 +507,32 @@ impl Error {
                 status: crate::scsi::SCSI_STATUS_TRANSPORT_FAILURE,
                 ..
             }
+        ) || matches!(
+            self,
+            Error::DiscRead {
+                status: Some(crate::scsi::SCSI_STATUS_TRANSPORT_FAILURE),
+                ..
+            }
         )
     }
 
+    /// True if this error indicates bridge degradation — the SCSI status
+    /// is neither GOOD (0x00), CHECK CONDITION (0x02), nor transport failure
+    /// (0xFF). Observed on the Initio INIC-1618L USB bridge preceding a full
+    /// crash: the bridge firmware returns non-standard status bytes (e.g.
+    /// 0x04, 0x05) with empty sense data. The caller should cool down
+    /// (10 s pause) and retry rather than hammering the bridge.
+    pub fn is_bridge_degradation(&self) -> bool {
+        let status = match self {
+            Error::ScsiError { status, .. } => *status,
+            Error::DiscRead { status, .. } => status.unwrap_or(0),
+            _ => return false,
+        };
+        status != crate::scsi::SCSI_STATUS_GOOD
+            && status != crate::scsi::SCSI_STATUS_CHECK_CONDITION
+            && status != crate::scsi::SCSI_STATUS_TRANSPORT_FAILURE
+    }
+
     /// True if the underlying SCSI failure is a *marginal read* — the
     /// drive returned an error category in which smaller-granularity
     /// retries can sometimes recover the data:
@@ -493,7 +543,7 @@ impl Error {
     ///     classified as fatal; treat as recoverable
     ///
     /// Returns `false` for transport failures (no sense data delivered),
-    /// HARDWARE ERROR, DATA PROTECT, UNIT ATTENTION, NOT READY, ILLEGAL
+    /// HARDWARE ERROR, DATA PROTECT, UNIT ATTENTION, ILLEGAL
     /// REQUEST, BLANK CHECK, kernel `IoError`, and any non-SCSI variant.
     /// Caller-agnostic predicate — describes a property of the *error*,
     /// not what one specific call site should do with it. Used by

src/lib.rs

@@ -95,6 +95,9 @@ pub(crate) mod speed;
 pub(crate) mod udf;
 pub mod verify;
 
+// Re-export verify types at the crate root for ergonomic imports.
+pub use verify::{SectorRange, SectorStatus, VerifyResult, verify_title};
+
 // ─── Drive lifecycle ────────────────────────────────────────────────────────
 //
 // `Drive::open(path)` → `wait_ready()` → `init()` → `Disc::scan()`. `Drive`

src/mux/disc.rs

@@ -6,6 +6,7 @@
 //! Read-only. For disc→ISO (raw sector copy), use `Disc::copy()`.
 
 use crate::disc::{Disc, DiscTitle, Extent};
+use crate::drive::extract_scsi_context;
 use crate::event::{BatchSizeReason, Event, EventKind};
 use crate::sector::SectorReader;
 use std::io;
@@ -317,7 +318,18 @@ impl DiscStream {
                     self.current_offset += 1;
                     break;
                 } else {
-                    return Err(crate::error::Error::DiscRead { sector: lba as u64 }.into());
+                    let err = self
+                        .reader
+                        .read_sectors(lba, sectors, &mut self.read_buf[..2048], false)
+                        .err();
+                    let (status, sense) =
+                        err.as_ref().map(extract_scsi_context).unwrap_or((0, None));
+                    return Err(crate::error::Error::DiscRead {
+                        sector: lba as u64,
+                        status: Some(status),
+                        sense,
+                    }
+                    .into());
                 }
             }
 

src/progress.rs

@@ -1,7 +1,7 @@
 //! Pipeline-progress reporting for the rip pipeline.
 //!
 //! v0.13.16 architecture rule: ONE progress signal type. Every long-running
-//! pipeline operation (`Disc::copy`, `Disc::patch`, mux) emits the same
+//! pipeline operation (`Disc::copy`, `Disc::patch`, `verify_title`) emits the same
 //! `PassProgress` shape via the `Progress` trait. Consumers (autorip) compute
 //! a single `PipelineStats` derived view and never reach into per-pass
 //! internals.
@@ -28,6 +28,8 @@ pub enum PassKind {
     /// Demux ISO → output (MKV / M2TS / network). Single phase that runs
     /// after all rip passes complete.
     Mux,
+    /// Sector verification — reads every sector and classifies health.
+    Verify,
 }
 
 /// One progress sample from a pipeline phase.
@@ -36,35 +38,88 @@ pub enum PassKind {
 /// regardless of which kind of pass is running. `bytes_good_total` is the
 /// cumulative count of confirmed-clean bytes across the whole rip; useful
 /// for the "data recovered" stat the user sees.
+///
+/// For `PassKind::Verify`, the fields map as follows:
+/// - `work_done` = sectors read so far
+/// - `work_total` = total sectors in title
+/// - `bytes_good_total` = good + slow + recovered sectors × 2048
+/// - `bytes_unreadable_total` = bad sectors × 2048
+/// - `bytes_pending_total` = 0 (verify processes sequentially, nothing pending)
 #[derive(Debug, Clone, Copy)]
 pub struct PassProgress {
     pub kind: PassKind,
-    /// Bytes processed in this pass so far. Monotonically non-decreasing.
     pub work_done: u64,
-    /// Total bytes this pass will process. Constant for the duration of
-    /// the pass.
     pub work_total: u64,
-    /// Cumulative bytes confirmed clean (`Finished` mapfile state) across
-    /// every pass run on this rip. Doesn't change across pass boundaries.
     pub bytes_good_total: u64,
-    /// Total disc capacity in bytes. Constant.
+    pub bytes_unreadable_total: u64,
+    pub bytes_pending_total: u64,
     pub bytes_total_disc: u64,
+    pub disc_duration_secs: Option<f64>,
+    /// How many bytes of the worst-case damage (unreadable + pending) fall
+    /// within the main title's extents. Zero means none of the damage
+    /// affects the main movie — it's all in extras/menus.
+    pub bytes_bad_in_main_title: u64,
+    /// Main title duration in seconds. Same as disc_duration_secs when the
+    /// disc has one dominant title, but separate so consumers can show both.
+    pub main_title_duration_secs: Option<f64>,
+    /// Main title size in bytes (sum of extent sizes).
+    pub main_title_size_bytes: Option<u64>,
+}
+
+impl PassProgress {
+    /// Percentage of work completed for this pass (0..=100).
+    ///
+    /// Returns `100.0` if `work_total` is zero to avoid division by zero.
+    pub fn work_pct(&self) -> f64 {
+        if self.work_total == 0 {
+            return 100.0;
+        }
+        self.work_done as f64 / self.work_total as f64 * 100.0
+    }
+
+    /// Percentage of the disc that is confirmed clean (0..=100).
+    ///
+    /// Computed from `bytes_good_total / bytes_total_disc`.
+    pub fn good_pct(&self) -> f64 {
+        if self.bytes_total_disc == 0 {
+            return 100.0;
+        }
+        self.bytes_good_total as f64 / self.bytes_total_disc as f64 * 100.0
+    }
+
+    /// Percentage of the disc that is unreadable (0..=100).
+    pub fn bad_pct(&self) -> f64 {
+        if self.bytes_total_disc == 0 {
+            return 0.0;
+        }
+        self.bytes_unreadable_total as f64 / self.bytes_total_disc as f64 * 100.0
+    }
+
+    /// Percentage of the disc that is still pending (not yet attempted or needs retry).
+    pub fn pending_pct(&self) -> f64 {
+        if self.bytes_total_disc == 0 {
+            return 0.0;
+        }
+        self.bytes_pending_total as f64 / self.bytes_total_disc as f64 * 100.0
+    }
 }
 
 /// A consumer of pipeline progress events. Library code calls
 /// `Progress::report` once per inner-loop iteration (throttling is the
 /// consumer's job — `report` is cheap; the library doesn't gate it).
 ///
+/// Returns `true` to continue, `false` to request early stop.
+///
 /// No `Send`/`Sync` bound — `report` is always called from the same thread
-/// running the rip pipeline, so closures with non-`Sync` captures (e.g.
+/// running the pipeline, so closures with non-`Sync` captures (e.g.
 /// `RefCell<PassProgressState>`) work directly. Blanket impl below lets
 /// callers pass closures without explicit struct types.
 pub trait Progress {
-    fn report(&self, p: &PassProgress);
+    fn report(&self, p: &PassProgress) -> bool;
 }
 
-impl<F: Fn(&PassProgress)> Progress for F {
-    fn report(&self, p: &PassProgress) {
+impl<F: Fn(&PassProgress) -> bool> Progress for F {
+    fn report(&self, p: &PassProgress) -> bool {
         (self)(p)
     }
 }

src/scsi/linux.rs

@@ -11,8 +11,8 @@
 //! This matches what every reference project does: MakeMKV (8 s sync
 //! ioctl), sg_dd (60 s sync ioctl), the kernel default for SCSI block
 //! devices (30 s `/sys/.../timeout`). See
-//! `(internal)/docs/audits/2026-04-26-scsi-architecture-research.md`
-//! for the full primary-source audit.
+//! the SCSI architecture audit (2026-04-26) for the full primary-source
+//! references.
 //!
 //! Pre-0.13.20 we ran an async `write() + poll(1.5s) + close-on-timeout +
 //! bg reopen` pattern. That abandoned slow-but-alive commands faster than
@@ -64,17 +64,15 @@ const _: () = assert!(std::mem::size_of::<sg_io_hdr>() == 88);
 const _: () = assert!(std::mem::size_of::<sg_io_hdr>() == 64);
 
 pub struct SgIoTransport {
-    fd: i32,
+    pub fd: i32,
     device_path: std::path::PathBuf,
+    pub fd_recovery: std::sync::Arc<std::sync::atomic::AtomicI32>,
 }
 
 impl SgIoTransport {
-    /// Open a SCSI device for use. Software-clean the kernel SG queue
-    /// (`reset()`) before opening so a previous killed process's queued
-    /// commands don't bleed into ours.
+    /// Open a SCSI device for use.
     pub fn open(device: &Path) -> Result<Self> {
         let device = Self::resolve_to_sg(device);
-        Self::reset(&device)?;
         let c_path = Self::to_c_path(&device);
         let fd = unsafe {
             libc::open(
@@ -88,6 +86,7 @@ impl SgIoTransport {
         Ok(SgIoTransport {
             fd,
             device_path: device,
+            fd_recovery: std::sync::Arc::new(std::sync::atomic::AtomicI32::new(-1)),
         })
     }
 
@@ -107,48 +106,7 @@ impl SgIoTransport {
     /// STOP+START UNIT. Both escalations were tried in 0.13.0–0.13.5
     /// against the LG BU40N (Initio USB-SATA bridge); both failed to
     /// recover wedged drives and made the wedge worse — see
-    /// `(internal)/postmortems/2026-04-25-bu40n-wedge-recovery.md`.
-    /// If the drive is genuinely unresponsive, the next workload command
-    /// fails naturally and the caller surfaces a "physical reconnect
-    /// required" prompt. Software has no path back from a wedged Initio
-    /// bridge — only physical replug clears it.
-    pub fn reset(device: &Path) -> Result<()> {
-        let c_path = Self::to_c_path(device);
-
-        // open + close — make the kernel cancel any SG_IO commands queued
-        // against a previous fd that didn't close cleanly.
-        let probe_fd = unsafe {
-            libc::open(
-                c_path.as_ptr() as *const libc::c_char,
-                libc::O_RDWR | libc::O_NONBLOCK | libc::O_CLOEXEC,
-            )
-        };
-        if probe_fd >= 0 {
-            unsafe { libc::close(probe_fd) };
-        }
-
-        // Let the kernel finish that cancellation before we reopen.
-        std::thread::sleep(std::time::Duration::from_secs(2));
-
-        // Fresh fd just to send the unlock command, then close.
-        let fd = unsafe {
-            libc::open(
-                c_path.as_ptr() as *const libc::c_char,
-                libc::O_RDWR | libc::O_NONBLOCK | libc::O_CLOEXEC,
-            )
-        };
-        if fd < 0 {
-            return Self::open_error(device);
-        }
-
-        // ALLOW MEDIUM REMOVAL — clear any tray lock left by a killed
-        // process whose Drop never ran. Best-effort; ignore result.
-        let _ = Self::raw_command(fd, &[0x1E, 0, 0, 0, 0, 0], 3_000);
-
-        unsafe { libc::close(fd) };
-        Ok(())
-    }
-
+    /// the BU40N wedge recovery postmortem (2026-04-25).
     fn open_error<T>(device: &Path) -> Result<T> {
         let err = std::io::Error::last_os_error();
         Err(if err.kind() == std::io::ErrorKind::PermissionDenied {
@@ -278,6 +236,22 @@ impl ScsiTransport for SgIoTransport {
             "SgIoTransport::execute"
         );
 
+        // Check if a background recovery has produced a new fd.
+        let recovered = self
+            .fd_recovery
+            .swap(-1, std::sync::atomic::Ordering::Acquire);
+        if recovered >= 0 {
+            // Close the old fd if it's still valid.
+            if self.fd >= 0 {
+                unsafe { libc::close(self.fd) };
+            }
+            self.fd = recovered;
+        } else if self.fd < 0 {
+            return Err(Error::DeviceNotFound {
+                path: self.device_path.display().to_string(),
+            });
+        }
+
         if data.len() > u32::MAX as usize {
             return Err(Error::ScsiError {
                 opcode: cdb[0],
@@ -352,6 +326,32 @@ impl ScsiTransport for SgIoTransport {
                 exec_elapsed_ms,
                 "transport-level failure (timeout / bridge wedge)"
             );
+
+            // Spawn recovery: close old fd, open new one in background.
+            // This prevents the main thread from blocking on close() while
+            // the kernel finishes the previous ioctl.
+            let old_fd = self.fd;
+            self.fd = -1;
+            let path = self.device_path.clone();
+            let recovery = self.fd_recovery.clone();
+
+            std::thread::spawn(move || {
+                if old_fd >= 0 {
+                    unsafe { libc::close(old_fd) };
+                }
+            });
+
+            std::thread::spawn(move || {
+                let c_path = std::ffi::CString::new(path.as_os_str().as_encoded_bytes()).unwrap();
+                let new_fd = unsafe {
+                    libc::open(
+                        c_path.as_ptr() as *const libc::c_char,
+                        libc::O_RDWR | libc::O_NONBLOCK | libc::O_CLOEXEC,
+                    )
+                };
+                recovery.store(new_fd, std::sync::atomic::Ordering::Release);
+            });
+
             return Err(Error::ScsiError {
                 opcode: cdb[0],
                 status: super::SCSI_STATUS_TRANSPORT_FAILURE,
@@ -506,8 +506,8 @@ fn enumerate_sg_names() -> Vec<String> {
             let type_path = format!("/sys/class/scsi_generic/{name}/device/type");
             match std::fs::read_to_string(&type_path) {
                 Ok(s) if s.trim() == SCSI_TYPE_OPTICAL => names.push(name),
-                Ok(_) => {}                 // not optical
-                Err(_) => names.push(name), // sysfs unreadable — let INQUIRY decide
+                Ok(_) => {} // not optical
+                Err(_) => {}
             }
         }
     } else {
@@ -524,47 +524,64 @@ fn enumerate_sg_names() -> Vec<String> {
     names
 }
 
-/// `drive_has_disc` = single TEST UNIT READY. Any error (including the
-/// wedge signature `ScsiError { status: 0xFF }` synthesised by `execute()`
-/// when `host_status` is set) bubbles straight up to the caller.
-///
-/// ## No in-library wedge recovery — and why
-///
-/// Versions 0.13.1–0.13.3 layered `scsi::reset()` + `scsi::usb_reset()`
-/// (`USBDEVFS_RESET`) escalation inside `drive_has_disc`. Production
-/// testing on the LG BU40N USB BD-RE showed all three userspace recovery
-/// ladders succeed at the USB transport level (the kernel logs
-/// `usb 3-2: reset high-speed USB device`, the device re-authorises
-/// and re-attaches on a fresh `scsi_host`) **but the drive firmware
-/// below the USB bridge stays locked** — no LUN ever enumerates, TUR
-/// never succeeds, /dev/sg* never reappears. Physical power-cycle
-/// (unplug-replug or host reboot) is the only recovery.
-///
-/// Methods tried and discarded:
-///  - `SG_SCSI_RESET` (device-level SCSI bus reset)
-///  - `STOP UNIT` / `START UNIT` CDB pair
-///  - `USBDEVFS_RESET` ioctl on `/dev/bus/usb/BBB/DDD`
-///  - `/sys/bus/usb/devices/<port>/authorized` 0→1 toggle
-///  - `/sys/bus/usb/drivers/usb-storage/{unbind,bind}` driver rebind
-///  - Forced `echo "- - -" > /sys/class/scsi_host/hostN/scan`
-///
-/// Rolled back in 0.13.4. Callers (autorip, CLI) surface the error
-/// directly and prompt the user to physically reconnect the drive.
-/// If a future hardware class is found where USB-layer recovery
-/// actually works, the escalation belongs here, gated on the wedge
-/// signature — see git tag `v0.13.3` for the full implementation.
+/// Send TEST UNIT READY directly — no transport, no reset, no side effects.
 pub(super) fn drive_has_disc(path: &Path) -> Result<bool> {
-    let mut transport = SgIoTransport::open(path)?;
+    let device = SgIoTransport::resolve_to_sg(path);
+    let c_path = SgIoTransport::to_c_path(&device);
+    let fd = unsafe {
+        libc::open(
+            c_path.as_ptr() as *const libc::c_char,
+            libc::O_RDWR | libc::O_NONBLOCK | libc::O_CLOEXEC,
+        )
+    };
+    if fd < 0 {
+        return SgIoTransport::open_error(&device);
+    }
+
     let cdb = [crate::scsi::SCSI_TEST_UNIT_READY, 0, 0, 0, 0, 0];
-    let mut buf = [0u8; 0];
-    match transport.execute(
-        &cdb,
-        crate::scsi::DataDirection::None,
-        &mut buf,
-        crate::scsi::TUR_TIMEOUT_MS,
-    ) {
-        Ok(_) => Ok(true),
-        Err(ref e) if e.scsi_sense().is_some_and(|s| s.is_not_ready()) => Ok(false),
-        Err(e) => Err(e),
+    let mut sense = [0u8; 32];
+    let mut hdr: sg_io_hdr = unsafe { std::mem::zeroed() };
+    hdr.interface_id = b'S' as i32;
+    hdr.dxfer_direction = SG_DXFER_NONE;
+    hdr.cmd_len = cdb.len() as u8;
+    hdr.mx_sb_len = sense.len() as u8;
+    hdr.dxfer_len = 0;
+    hdr.dxferp = std::ptr::null_mut();
+    hdr.cmdp = cdb.as_ptr();
+    hdr.sbp = sense.as_mut_ptr();
+    hdr.timeout = crate::scsi::TUR_TIMEOUT_MS;
+    hdr.flags = SG_FLAG_Q_AT_HEAD;
+
+    let ret = unsafe { libc::ioctl(fd, SG_IO as _, &mut hdr as *mut sg_io_hdr) };
+    unsafe { libc::close(fd) };
+
+    if ret < 0 {
+        return Err(Error::IoError {
+            source: std::io::Error::last_os_error(),
+        });
+    }
+
+    let driver_status_real = hdr.driver_status & !super::DRIVER_SENSE;
+    if hdr.host_status != 0 || driver_status_real != 0 {
+        return Err(Error::ScsiError {
+            opcode: cdb[0],
+            status: super::SCSI_STATUS_TRANSPORT_FAILURE,
+            sense: None,
+        });
+    }
+
+    if hdr.status == 0 {
+        return Ok(true);
+    }
+
+    let parsed = super::parse_sense(&sense, hdr.sb_len_wr);
+    if parsed.is_not_ready() {
+        Ok(false)
+    } else {
+        Err(Error::ScsiError {
+            opcode: cdb[0],
+            status: hdr.status,
+            sense: Some(parsed),
+        })
     }
 }

src/scsi/macos.rs

@@ -1,183 +1,55 @@
-//! macOS SCSI transport via IOKit SCSITaskDeviceInterface.
+//! macOS SCSI transport: IOKit SCSITaskDeviceInterface with exclusive access.
 //!
-//! Sends SCSI commands to optical drives through IOKit's SCSI Architecture
-//! Model family. Accepts BSD device paths like `/dev/disk2` or `/dev/rdisk2`.
+//! Single dispatch path: **all** CDBs (INQUIRY, READ, REPORT KEY, etc.) go
+//! through `SCSITaskDeviceInterface::ExecuteTaskSync` — 1:1 with the Linux
+//! SG_IO backend. The C shim (`macos_shim.c`) handles:
 //!
-//! Requires exclusive access to the device — unmount the disc first:
-//! `diskutil unmountDisk /dev/disk2`
+//! 1. `diskutil unmountDisk force` on the target device only
+//! 2. Find `IOBDServices` matching the requested BSD name (walks IOKit
+//!    registry: IOBDServices → IOBDBlockStorageDriver → IOMedia → BSD Name)
+//! 3. Create `MMCDeviceInterface` → `SCSITaskDeviceInterface`
+//! 4. `ObtainExclusiveAccess`
+//! 5. Raw CDB dispatch via `CreateSCSITask` + `ExecuteTaskSync`
+//!
+//! Drive enumeration (`list_drives`) uses the IOKit registry directly via
+//! `shim_list_drives` — no exclusive access, no SCSI commands, no unmounts.
 
 use super::{DataDirection, ScsiResult, ScsiTransport};
 use crate::error::{Error, Result};
 use std::path::Path;
 
-// ── IOKit / CoreFoundation type aliases ─────────────────────────────────────
-
-type CFMutableDictionaryRef = *mut std::ffi::c_void;
-type IOObject = u32;
-type IOReturn = i32;
-type MachPort = u32;
-
-/// Opaque COM interface pointer — `*mut *mut VTable` (double-indirect).
-/// IOKit plugins use COM-style vtables: the pointer points to a pointer
-/// to the function table.
-type ComRef = *mut *mut std::ffi::c_void;
-
-const K_IO_RETURN_SUCCESS: IOReturn = 0;
-
-// SCSI data transfer directions (SCSITaskLib.h)
-const K_SCSI_DATA_TRANSFER_NO_DATA: u8 = 0;
-const K_SCSI_DATA_TRANSFER_FROM_TARGET: u8 = 1;
-const K_SCSI_DATA_TRANSFER_TO_TARGET: u8 = 2;
-
-// SCSI task status values
-const K_SCSI_TASK_STATUS_GOOD: u8 = 0x00;
-
-const K_MAX_CDB_SIZE: usize = 16;
 const K_SENSE_DATA_SIZE: usize = 32;
 
-// ── IOKit plugin UUIDs ──────────────────────────────────────────────────────
-// From IOKit/scsi/SCSITaskLib.h
-
-/// kIOMMCDeviceUserClientTypeID — plugin type for MMC (optical) devices.
-const K_IO_MMC_DEVICE_USER_CLIENT_TYPE_ID: [u8; 16] = [
-    0x97, 0xAB, 0xCF, 0x5C, 0x45, 0x71, 0x11, 0xD6, 0xB6, 0xA0, 0x00, 0x30, 0x65, 0xA4, 0x7A, 0xEE,
-];
-
-/// kIOCFPlugInInterfaceID — base IOCFPlugin interface.
-const K_IO_CFPLUGIN_INTERFACE_ID: [u8; 16] = [
-    0xC2, 0x44, 0xE8, 0x58, 0x10, 0x9C, 0x11, 0xD4, 0x91, 0xD4, 0x00, 0x50, 0xE4, 0xC6, 0x42, 0x6F,
-];
-
-/// kIOSCSITaskDeviceInterfaceID — the interface we QueryInterface for.
-const K_IO_SCSI_TASK_DEVICE_INTERFACE_ID: [u8; 16] = [
-    0x61, 0x3E, 0x48, 0xB0, 0x30, 0x01, 0x11, 0xD6, 0xA4, 0xC0, 0x00, 0x0A, 0x27, 0x05, 0x28, 0x61,
-];
-
-// ── Scatter/gather element ──────────────────────────────────────────────────
-
 #[repr(C)]
-struct SCSITaskSGElement {
-    address: u64,
-    length: u64,
+#[derive(Copy, Clone)]
+struct ShimDriveInfo {
+    bsd_name: [u8; 32],
+    vendor: [u8; 32],
+    model: [u8; 48],
+    firmware: [u8; 16],
 }
 
-// ── External IOKit / CoreFoundation functions ───────────────────────────────
-
-// Rust 2024: FFI blocks declaring extern fns must be `unsafe extern`.
 unsafe extern "C" {
-    fn IOMasterPort(bootstrap: u32, master: *mut MachPort) -> IOReturn;
-    fn IOBSDNameMatching(
-        master: MachPort,
-        options: u32,
-        bsd_name: *const u8,
-    ) -> CFMutableDictionaryRef;
-    fn IOServiceGetMatchingService(master: MachPort, matching: CFMutableDictionaryRef) -> IOObject;
-    fn IOObjectRelease(object: IOObject) -> IOReturn;
-    fn IORegistryEntryGetParentEntry(
-        entry: IOObject,
-        plane: *const u8,
-        parent: *mut IOObject,
-    ) -> IOReturn;
-    fn IOObjectConformsTo(object: IOObject, class_name: *const u8) -> u8;
-    fn IOCreatePlugInInterfaceForService(
-        service: IOObject,
-        plugin_type: *const [u8; 16],
-        interface_type: *const [u8; 16],
-        the_interface: *mut ComRef,
-        the_score: *mut i32,
-    ) -> IOReturn;
+    fn shim_open_exclusive(bsd_name: *const u8) -> i32;
+    fn shim_close();
+    fn shim_execute(
+        cdb: *const u8,
+        cdb_len: u8,
+        buf: *mut u8,
+        buf_len: u32,
+        data_in: i32,
+        sense_out: *mut u8,
+        sense_len: u32,
+        task_status_out: *mut u8,
+        transfer_count: *mut u64,
+    ) -> i32;
+    fn shim_list_drives(out: *mut ShimDriveInfo, max_entries: i32) -> i32;
 }
 
-// ── COM vtable helpers ──────────────────────────────────────────────────────
-//
-// IOKit plugin interfaces use COM-style vtables. A ComRef is **vtable —
-// dereferencing once gives the vtable pointer, then index into it for
-// individual function pointers.
-//
-// All vtable indices verified against Apple open source:
-// IOSCSIArchitectureModelFamily/UserClientLib/SCSITaskLib.h
-
-/// Read a function pointer from a COM vtable at the given index.
-///
-/// # Safety
-/// `iface` must be a valid COM interface pointer (*mut *mut c_void), and
-/// `index` must be a valid vtable slot for the target type `T`.
-unsafe fn vtable_fn<T>(iface: ComRef, index: usize) -> T {
-    // Rust 2024: `unsafe fn` bodies are no longer implicitly unsafe.
-    // Each unsafe op needs its own `unsafe { }` block.
-    unsafe {
-        let vtable = *iface as *const *const std::ffi::c_void;
-        let fn_ptr = *vtable.add(index);
-        std::mem::transmute_copy(&fn_ptr)
-    }
-}
-
-/// Call Release (vtable index 3) on any COM interface.
-fn com_release(iface: ComRef) {
-    type Fn = unsafe extern "C" fn(ComRef) -> u32;
-    unsafe {
-        let f: Fn = vtable_fn(iface, 3);
-        f(iface);
-    }
-}
-
-// ── SCSITaskDeviceInterface vtable ──────────────────────────────────────────
-//
-// Index  Method
-//   0    _reserved
-//   1    QueryInterface
-//   2    AddRef
-//   3    Release
-//   4    IsExclusiveAccessAvailable
-//   5    AddCallbackDispatcherToRunLoop
-//   6    RemoveCallbackDispatcherFromRunLoop
-//   7    ObtainExclusiveAccess
-//   8    ReleaseExclusiveAccess
-//   9    CreateSCSITask
-
-const VTIDX_OBTAIN_EXCLUSIVE: usize = 7;
-const VTIDX_RELEASE_EXCLUSIVE: usize = 8;
-const VTIDX_CREATE_TASK: usize = 9;
-
-// ── SCSITaskInterface vtable ────────────────────────────────────────────────
-//
-// Index  Method
-//   0    _reserved
-//   1    QueryInterface
-//   2    AddRef
-//   3    Release
-//   4    IsTaskActive
-//   5    SetTaskAttribute
-//   6    GetTaskAttribute
-//   7    GetTaskState
-//   8    SetCommandDescriptorBlock
-//   9    GetCommandDescriptorBlockSize
-//  10    GetCommandDescriptorBlock
-//  11    SetScatterGatherEntries
-//  12    SetTimeoutDuration
-//  13    GetTimeoutDuration
-//  14    SetTaskCompletionCallback
-//  15    ExecuteTaskSync
-//  16    ExecuteTaskAsync
-//  17    AbortTask
-//  18    GetSCSIServiceResponse
-//  19    GetTaskStatus
-//  20    GetRealizedDataTransferCount
-//  21    GetAutoSenseData
-
-const VTIDX_SET_CDB: usize = 8;
-const VTIDX_SET_SG: usize = 11;
-const VTIDX_SET_TIMEOUT: usize = 12;
-const VTIDX_EXECUTE_SYNC: usize = 15;
-
-// ── Transport implementation ────────────────────────────────────────────────
-
 pub struct MacScsiTransport {
-    device_iface: ComRef,
-    exclusive: bool,
+    _bsd_name: String,
 }
 
-// IOKit COM interface pointers are Mach port references — safe to send between threads.
 unsafe impl Send for MacScsiTransport {}
 
 impl MacScsiTransport {
@@ -186,7 +58,6 @@ impl MacScsiTransport {
             path: device.display().to_string(),
         })?;
 
-        // Strip /dev/ prefix to get BSD name (e.g. "disk2")
         let bsd_name = if let Some(rest) = dev_str.strip_prefix("/dev/r") {
             rest
         } else if let Some(rest) = dev_str.strip_prefix("/dev/") {
@@ -195,137 +66,118 @@ impl MacScsiTransport {
             dev_str
         };
 
-        let device_iface = Self::acquire_device_iface(bsd_name)?;
+        let mut bsd_c = bsd_name.as_bytes().to_vec();
+        bsd_c.push(0);
+
+        let rc = unsafe { shim_open_exclusive(bsd_c.as_ptr()) };
+        if rc != 0 {
+            return Err(Error::DeviceNotFound {
+                path: bsd_name.to_string(),
+            });
+        }
 
         Ok(MacScsiTransport {
-            device_iface,
-            exclusive: true,
+            _bsd_name: bsd_name.to_string(),
         })
     }
-
-    /// Resolve the BSD name → IOKit SCSITaskDeviceInterface with exclusive
-    /// access. Returns the COM ref the caller must release.
-    fn acquire_device_iface(bsd_name: &str) -> Result<ComRef> {
-        let service = find_scsi_service(bsd_name)?;
-
-        // Create IOKit plugin for the MMC device
-        let mut plugin: ComRef = std::ptr::null_mut();
-        let mut score: i32 = 0;
-        let kr = unsafe {
-            IOCreatePlugInInterfaceForService(
-                service,
-                &K_IO_MMC_DEVICE_USER_CLIENT_TYPE_ID,
-                &K_IO_CFPLUGIN_INTERFACE_ID,
-                &mut plugin,
-                &mut score,
-            )
-        };
-        unsafe { IOObjectRelease(service) };
-
-        if kr != K_IO_RETURN_SUCCESS || plugin.is_null() {
-            return Err(Error::IoKitPluginFailed {
-                path: bsd_name.to_string(),
-                kr: kr as u32,
-            });
-        }
-
-        // QueryInterface for SCSITaskDeviceInterface
-        let mut device_iface: ComRef = std::ptr::null_mut();
-        let hr = unsafe {
-            type QiFn = unsafe extern "C" fn(ComRef, *const [u8; 16], *mut ComRef) -> i32;
-            let qi: QiFn = vtable_fn(plugin, 1);
-            qi(
-                plugin,
-                &K_IO_SCSI_TASK_DEVICE_INTERFACE_ID,
-                &mut device_iface,
-            )
-        };
-        com_release(plugin);
-
-        if hr != 0 || device_iface.is_null() {
-            return Err(Error::ScsiInterfaceUnavailable {
-                path: bsd_name.to_string(),
-            });
-        }
-
-        // Obtain exclusive access
-        let kr = unsafe {
-            type Fn = unsafe extern "C" fn(ComRef) -> IOReturn;
-            let f: Fn = vtable_fn(device_iface, VTIDX_OBTAIN_EXCLUSIVE);
-            f(device_iface)
-        };
-        if kr != K_IO_RETURN_SUCCESS {
-            com_release(device_iface);
-            return Err(Error::DeviceLocked {
-                path: bsd_name.to_string(),
-                kr: kr as u32,
-            });
-        }
-
-        Ok(device_iface)
-    }
-
-    // `reset()` removed in 0.13.6 — see scsi/mod.rs for rationale.
-    // `try_recover()` removed in 0.13.20 — userspace handle-recovery on
-    // task failure was the same anti-pattern stripped from Linux SG_IO
-    // (see (internal)/docs/audits/2026-04-26-scsi-architecture-research.md).
-    // Errors bubble up; caller decides whether to reopen the Drive.
 }
 
-/// Enumerate optical drives on macOS. Mirrors `drive::macos::find_drives`
-/// (which iterates `/dev/disk0..15` + INQUIRY + filters peripheral
-/// type 5). Same logic, exposed through the new `DriveInfo` shape so
-/// callers — `list_drives()` in `scsi::mod` — never reach into
-/// `crate::drive::macos`.
-pub(super) fn list_drives() -> Vec<super::DriveInfo> {
-    let mut out = Vec::new();
-    for i in 0..K_DEV_DISK_MAX {
-        let path = format!("/dev/disk{i}");
-        if !std::path::Path::new(&path).exists() {
-            continue;
+impl Drop for MacScsiTransport {
+    fn drop(&mut self) {
+        unsafe { shim_close() };
+    }
+}
+
+impl ScsiTransport for MacScsiTransport {
+    fn execute(
+        &mut self,
+        cdb: &[u8],
+        direction: DataDirection,
+        data: &mut [u8],
+        _timeout_ms: u32,
+    ) -> Result<ScsiResult> {
+        let data_in = match direction {
+            DataDirection::FromDevice => 1,
+            DataDirection::ToDevice => 0,
+            DataDirection::None => 0,
+        };
+
+        let mut sense = [0u8; K_SENSE_DATA_SIZE];
+        let mut task_status: u8 = 0xFF;
+        let mut transfer_count: u64 = 0;
+
+        let kr = unsafe {
+            shim_execute(
+                cdb.as_ptr(),
+                cdb.len() as u8,
+                data.as_mut_ptr(),
+                data.len() as u32,
+                data_in,
+                sense.as_mut_ptr(),
+                K_SENSE_DATA_SIZE as u32,
+                &mut task_status,
+                &mut transfer_count,
+            )
+        };
+
+        if kr != 0 {
+            return Err(Error::ScsiError {
+                opcode: cdb[0],
+                status: super::SCSI_STATUS_TRANSPORT_FAILURE,
+                sense: None,
+            });
         }
-        let mut transport = match MacScsiTransport::open(std::path::Path::new(&path)) {
-            Ok(t) => t,
-            Err(_) => continue,
-        };
-        let inquiry = match super::inquiry(&mut transport) {
-            Ok(r) => r,
-            Err(_) => continue,
-        };
-        // SCSI peripheral type field is the lower 5 bits of byte 0.
-        if inquiry.raw.is_empty()
-            || (inquiry.raw[K_INQUIRY_TYPE_BYTE] & K_INQUIRY_TYPE_MASK) != K_SCSI_TYPE_OPTICAL
-        {
+
+        if task_status != 0 {
+            let parsed = super::parse_sense(&sense, K_SENSE_DATA_SIZE as u8);
+            return Err(Error::ScsiError {
+                opcode: cdb[0],
+                status: task_status,
+                sense: Some(parsed),
+            });
+        }
+
+        Ok(ScsiResult {
+            status: 0,
+            bytes_transferred: transfer_count as usize,
+            sense,
+        })
+    }
+}
+
+// ── Drive enumeration (registry-based, no exclusive access) ──────────────
+
+pub(super) fn list_drives() -> Vec<super::DriveInfo> {
+    let mut buf = [ShimDriveInfo {
+        bsd_name: [0; 32],
+        vendor: [0; 32],
+        model: [0; 48],
+        firmware: [0; 16],
+    }; 8];
+
+    let count = unsafe { shim_list_drives(buf.as_mut_ptr(), buf.len() as i32) };
+
+    let mut out = Vec::new();
+    for info in buf.iter().take((count as usize).min(buf.len())) {
+        let bsd_name = cstr_to_str(&info.bsd_name);
+        if bsd_name.is_empty() {
             continue;
         }
         out.push(super::DriveInfo {
-            path,
-            vendor: inquiry.vendor_id,
-            model: inquiry.model,
-            firmware: inquiry.firmware,
+            path: format!("/dev/{bsd_name}"),
+            vendor: cstr_to_str(&info.vendor).to_string(),
+            model: cstr_to_str(&info.model).to_string(),
+            firmware: cstr_to_str(&info.firmware).to_string(),
         });
     }
     out
 }
 
-/// Maximum BSD disk index probed during enumeration. macOS assigns
-/// `/dev/diskN` sequentially per attached storage device; 16 covers
-/// any realistic homelab.
-const K_DEV_DISK_MAX: u8 = 16;
+fn cstr_to_str(bytes: &[u8]) -> &str {
+    let end = bytes.iter().position(|&b| b == 0).unwrap_or(bytes.len());
+    std::str::from_utf8(&bytes[..end]).unwrap_or("")
+}
 
-/// SCSI INQUIRY response: peripheral device type lives in byte 0,
-/// lower 5 bits.
-const K_INQUIRY_TYPE_BYTE: usize = 0;
-const K_INQUIRY_TYPE_MASK: u8 = 0x1F;
-
-/// SCSI peripheral type 5 = "CD-ROM device" (covers DVD, BD-ROM, BD-RE).
-const K_SCSI_TYPE_OPTICAL: u8 = 0x05;
-
-/// TEST UNIT READY probe on macOS. Any non-"not ready" error bubbles up
-/// to the caller — in-library wedge recovery was rolled back in 0.13.4
-/// after USB-layer resets failed to recover the LG BU40N on Linux; the
-/// macOS impl mirrors that choice for symmetry. See the Linux
-/// `drive_has_disc` in `scsi/linux.rs` for the full rationale.
 pub(super) fn drive_has_disc(path: &Path) -> Result<bool> {
     let mut transport = MacScsiTransport::open(path)?;
     let cdb = [crate::scsi::SCSI_TEST_UNIT_READY, 0, 0, 0, 0, 0];
@@ -341,235 +193,3 @@ pub(super) fn drive_has_disc(path: &Path) -> Result<bool> {
         Err(e) => Err(e),
     }
 }
-
-impl Drop for MacScsiTransport {
-    fn drop(&mut self) {
-        if self.device_iface.is_null() {
-            return;
-        }
-        if self.exclusive {
-            unsafe {
-                type Fn = unsafe extern "C" fn(ComRef) -> IOReturn;
-                let f: Fn = vtable_fn(self.device_iface, VTIDX_RELEASE_EXCLUSIVE);
-                f(self.device_iface);
-            }
-        }
-        com_release(self.device_iface);
-    }
-}
-
-impl ScsiTransport for MacScsiTransport {
-    fn execute(
-        &mut self,
-        cdb: &[u8],
-        direction: DataDirection,
-        data: &mut [u8],
-        timeout_ms: u32,
-    ) -> Result<ScsiResult> {
-        // Create a SCSI task
-        let task: ComRef = unsafe {
-            type Fn = unsafe extern "C" fn(ComRef) -> ComRef;
-            let f: Fn = vtable_fn(self.device_iface, VTIDX_CREATE_TASK);
-            f(self.device_iface)
-        };
-        if task.is_null() {
-            return Err(Error::ScsiError {
-                opcode: cdb[0],
-                status: super::SCSI_STATUS_TRANSPORT_FAILURE,
-                sense: None,
-            });
-        }
-
-        // Set CDB
-        let mut cdb_padded = [0u8; K_MAX_CDB_SIZE];
-        let cdb_len = cdb.len().min(K_MAX_CDB_SIZE);
-        cdb_padded[..cdb_len].copy_from_slice(&cdb[..cdb_len]);
-        unsafe {
-            type Fn = unsafe extern "C" fn(ComRef, *const u8, u8) -> IOReturn;
-            let f: Fn = vtable_fn(task, VTIDX_SET_CDB);
-            f(task, cdb_padded.as_ptr(), cdb_len as u8);
-        }
-
-        // Set scatter/gather and transfer direction
-        let iokit_dir = match direction {
-            DataDirection::None => K_SCSI_DATA_TRANSFER_NO_DATA,
-            DataDirection::FromDevice => K_SCSI_DATA_TRANSFER_FROM_TARGET,
-            DataDirection::ToDevice => K_SCSI_DATA_TRANSFER_TO_TARGET,
-        };
-
-        if direction != DataDirection::None && !data.is_empty() {
-            let sg = SCSITaskSGElement {
-                address: data.as_mut_ptr() as u64,
-                length: data.len() as u64,
-            };
-            unsafe {
-                type Fn =
-                    unsafe extern "C" fn(ComRef, *const SCSITaskSGElement, u8, u64, u8) -> IOReturn;
-                let f: Fn = vtable_fn(task, VTIDX_SET_SG);
-                f(task, &sg, 1, data.len() as u64, iokit_dir);
-            }
-        } else {
-            unsafe {
-                type Fn =
-                    unsafe extern "C" fn(ComRef, *const SCSITaskSGElement, u8, u64, u8) -> IOReturn;
-                let f: Fn = vtable_fn(task, VTIDX_SET_SG);
-                f(task, std::ptr::null(), 0, 0, K_SCSI_DATA_TRANSFER_NO_DATA);
-            }
-        }
-
-        // Set timeout (IOKit SCSITask takes milliseconds)
-        unsafe {
-            type Fn = unsafe extern "C" fn(ComRef, u32);
-            let f: Fn = vtable_fn(task, VTIDX_SET_TIMEOUT);
-            f(task, timeout_ms);
-        }
-
-        // Execute synchronously
-        let mut sense = [0u8; K_SENSE_DATA_SIZE];
-        let mut task_status: u32 = 0;
-        let mut realized_count: u64 = 0;
-
-        let kr = unsafe {
-            type Fn = unsafe extern "C" fn(ComRef, *mut u8, *mut u32, *mut u64) -> IOReturn;
-            let f: Fn = vtable_fn(task, VTIDX_EXECUTE_SYNC);
-            f(
-                task,
-                sense.as_mut_ptr(),
-                &mut task_status,
-                &mut realized_count,
-            )
-        };
-
-        com_release(task);
-
-        if kr != K_IO_RETURN_SUCCESS {
-            // Task-level failure (timeout / IOKit error). Bubble it up;
-            // the kernel mid-layer has already done what it can.
-            return Err(Error::ScsiError {
-                opcode: cdb[0],
-                status: super::SCSI_STATUS_TRANSPORT_FAILURE,
-                sense: None,
-            });
-        }
-
-        if task_status != K_SCSI_TASK_STATUS_GOOD as u32 {
-            // IOKit doesn't surface a "bytes written into sense buffer"
-            // count the way SG_IO does — pass the buffer's full length
-            // and let parse_sense inspect byte 0's response code to pick
-            // descriptor-vs-fixed format.
-            //
-            // 0.13.23: carry the full SPC-4 sense triple in
-            // `Error::ScsiError::sense` so callers can route on
-            // `ScsiSense::is_medium_error()` etc.
-            let parsed = super::parse_sense(&sense, sense.len() as u8);
-            return Err(Error::ScsiError {
-                opcode: cdb[0],
-                status: task_status as u8,
-                sense: Some(parsed),
-            });
-        }
-
-        Ok(ScsiResult {
-            status: task_status as u8,
-            bytes_transferred: realized_count as usize,
-            sense,
-        })
-    }
-}
-
-// ── IOKit service discovery ─────────────────────────────────────────────────
-
-/// BSD name → IOKit service for the SCSI device.
-///
-/// Walk: IOMedia (BSD name match) → parent chain → SCSIPeripheralDeviceNub.
-///
-/// All failure paths surface as `Error::DeviceNotFound { path: bsd_name }` —
-/// the four internal stages (IOMasterPort / IOBSDNameMatching / IOMedia
-/// lookup / walk_to_authoring_device) collapse into one observable error
-/// because none of them are user-actionable individually. Pre-0.13 each
-/// stage stuffed an English description into `path:` ("…IOMasterPort
-/// failed", "…SCSITaskDeviceInterface not available", etc.) which broke
-/// the library's "no English text" rule.
-fn find_scsi_service(bsd_name: &str) -> Result<IOObject> {
-    let not_found = || Error::DeviceNotFound {
-        path: bsd_name.to_string(),
-    };
-
-    let mut master: MachPort = 0;
-    let kr = unsafe { IOMasterPort(0, &mut master) };
-    if kr != K_IO_RETURN_SUCCESS {
-        return Err(not_found());
-    }
-
-    // IOBSDNameMatching creates a dictionary matching { "BSD Name" = bsd_name }
-    let mut bsd_c = bsd_name.as_bytes().to_vec();
-    bsd_c.push(0);
-    let matching = unsafe { IOBSDNameMatching(master, 0, bsd_c.as_ptr()) };
-    if matching.is_null() {
-        return Err(not_found());
-    }
-
-    // Find the single IOMedia service (consumes the matching dict)
-    let media = unsafe { IOServiceGetMatchingService(master, matching) };
-    if media == 0 {
-        return Err(not_found());
-    }
-
-    // Walk up the IOService plane to find the authoring device.
-    // The chain is typically:
-    //   IOMedia → IOPartitionScheme → IOMedia → IOBlockStorageDriver
-    //   → IOSCSIPeripheralDeviceNub (this is what we want)
-    //
-    // We walk up until we find a service that IOCreatePlugInInterfaceForService
-    // accepts with kIOMMCDeviceUserClientTypeID, or until we hit the root.
-    let service = walk_to_authoring_device(media);
-    unsafe { IOObjectRelease(media) };
-
-    service.ok_or_else(not_found)
-}
-
-/// Walk up the IOService plane from an IOMedia to the SCSI authoring device.
-fn walk_to_authoring_device(start: IOObject) -> Option<IOObject> {
-    let mut current = start;
-    // Retain start so we can release uniformly in the loop
-    // (IORegistryEntryGetParentEntry retains the parent for us)
-
-    // Target class names for authoring devices
-    let target_classes: &[&[u8]] = &[
-        b"IOSCSIPeripheralDeviceNub\0",
-        b"IOBDBlockStorageDevice\0",
-        b"IODVDBlockStorageDevice\0",
-        b"IOCDBlockStorageDevice\0",
-        b"IOBlockStorageDevice\0",
-    ];
-
-    // Walk up to 10 levels (more than enough)
-    for _ in 0..10 {
-        let mut parent: IOObject = 0;
-        let kr = unsafe {
-            IORegistryEntryGetParentEntry(current, c"IOService".as_ptr() as *const u8, &mut parent)
-        };
-
-        if current != start {
-            unsafe { IOObjectRelease(current) };
-        }
-
-        if kr != K_IO_RETURN_SUCCESS || parent == 0 {
-            return None;
-        }
-
-        // Check if this parent matches any of our target classes
-        for class in target_classes {
-            if unsafe { IOObjectConformsTo(parent, class.as_ptr()) } != 0 {
-                return Some(parent);
-            }
-        }
-
-        current = parent;
-    }
-
-    if current != start {
-        unsafe { IOObjectRelease(current) };
-    }
-    None
-}

src/scsi/macos_shim.c

@@ -0,0 +1,387 @@
+#include <IOKit/IOKitLib.h>
+#include <IOKit/IOCFPlugIn.h>
+#include <IOKit/scsi/SCSITaskLib.h>
+#include <CoreFoundation/CoreFoundation.h>
+#include <stdlib.h>
+#include <string.h>
+#include <unistd.h>
+
+// ── Types ──────────────────────────────────────────────────────────────────
+
+typedef struct {
+    IOCFPlugInInterface      **plugin;
+    MMCDeviceInterface       **mmc;
+    SCSITaskDeviceInterface  **scsi;
+    int                        exclusive;
+} ShimHandle;
+
+typedef struct {
+    char bsd_name[32];
+    char vendor[32];
+    char model[48];
+    char firmware[16];
+} ShimDriveInfo;
+
+// ── Global handle (single-drive, same as before) ──────────────────────────
+
+static ShimHandle g_handle = {NULL, NULL, NULL, 0};
+
+// ── Registry helpers ──────────────────────────────────────────────────────
+
+static int cfstring_to_cstr(CFStringRef cf, char *buf, size_t buflen) {
+    if (!cf) return 0;
+    if (!CFStringGetCString(cf, buf, buflen, kCFStringEncodingUTF8)) return 0;
+    return 1;
+}
+
+static int registry_entry_bsd_name(io_registry_entry_t entry, char *buf, size_t buflen) {
+    CFStringRef cf = IORegistryEntryCreateCFProperty(entry, CFSTR("BSD Name"),
+        kCFAllocatorDefault, 0);
+    if (!cf) return 0;
+    int ok = cfstring_to_cstr(cf, buf, buflen);
+    CFRelease(cf);
+    return ok;
+}
+
+static io_registry_entry_t find_iomedia_child(io_registry_entry_t parent) {
+    io_iterator_t iter;
+    kern_return_t kr = IORegistryEntryGetChildIterator(parent, kIOServicePlane, &iter);
+    if (kr != KERN_SUCCESS) return 0;
+
+    io_registry_entry_t child;
+    while ((child = IOIteratorNext(iter)) != 0) {
+        char cls[128];
+        kr = IOObjectGetClass(child, cls);
+        if (kr == KERN_SUCCESS) {
+            if (strcmp(cls, "IOMedia") == 0 || strcmp(cls, "IOBDMedia") == 0) {
+                IOObjectRelease(iter);
+                return child;
+            }
+        }
+        IOObjectRelease(child);
+    }
+    IOObjectRelease(iter);
+    return 0;
+}
+
+static io_registry_entry_t find_child_of_class(io_registry_entry_t parent, const char *target_class) {
+    io_iterator_t iter;
+    kern_return_t kr = IORegistryEntryGetChildIterator(parent, kIOServicePlane, &iter);
+    if (kr != KERN_SUCCESS) return 0;
+
+    io_registry_entry_t child;
+    while ((child = IOIteratorNext(iter)) != 0) {
+        char cls[128];
+        kr = IOObjectGetClass(child, cls);
+        if (kr == KERN_SUCCESS && strcmp(cls, target_class) == 0) {
+            IOObjectRelease(iter);
+            return child;
+        }
+        IOObjectRelease(child);
+    }
+    IOObjectRelease(iter);
+    return 0;
+}
+
+static io_registry_entry_t find_parent_of_class(io_registry_entry_t entry, const char *target_class) {
+    io_registry_entry_t parent;
+    kern_return_t kr = IORegistryEntryGetParentEntry(entry, kIOServicePlane, &parent);
+    if (kr != KERN_SUCCESS) return 0;
+
+    char cls[128];
+    kr = IOObjectGetClass(parent, cls);
+    if (kr == KERN_SUCCESS && strcmp(cls, target_class) == 0) {
+        return parent;
+    }
+    IOObjectRelease(parent);
+    return 0;
+}
+
+// Given an IOBDServices, find the BSD name of its IOMedia child.
+// Chain: IOBDServices -> IOBDBlockStorageDriver -> IOMedia (has "BSD Name")
+static int bdsvc_to_bsd_name(io_registry_entry_t bdsvc, char *buf, size_t buflen) {
+    io_registry_entry_t driver = find_child_of_class(bdsvc, "IOBDBlockStorageDriver");
+    if (!driver) return 0;
+
+    io_registry_entry_t media = find_iomedia_child(driver);
+    IOObjectRelease(driver);
+    if (!media) return 0;
+
+    int ok = registry_entry_bsd_name(media, buf, buflen);
+    IOObjectRelease(media);
+    return ok;
+}
+
+// Given an IOBDServices, extract Device Characteristics strings.
+static void bdsvc_device_info(io_registry_entry_t bdsvc, ShimDriveInfo *info) {
+    CFDictionaryRef dc = IORegistryEntryCreateCFProperty(bdsvc,
+        CFSTR("Device Characteristics"), kCFAllocatorDefault, 0);
+    if (!dc) return;
+
+    CFStringRef val;
+
+    val = CFDictionaryGetValue(dc, CFSTR("Vendor Name"));
+    if (val) cfstring_to_cstr(val, info->vendor, sizeof(info->vendor));
+
+    val = CFDictionaryGetValue(dc, CFSTR("Product Name"));
+    if (val) cfstring_to_cstr(val, info->model, sizeof(info->model));
+
+    val = CFDictionaryGetValue(dc, CFSTR("Product Revision Level"));
+    if (val) cfstring_to_cstr(val, info->firmware, sizeof(info->firmware));
+
+    CFRelease(dc);
+}
+
+// Find the IOBDServices that owns the given BSD name.
+// Returns a retained io_service_t (caller must release), or 0.
+static io_service_t find_bdsvc_by_bsd_name(mach_port_t mp, const char *bsd_name) {
+    CFMutableDictionaryRef matching = IOServiceMatching("IOBDServices");
+    if (!matching) return 0;
+
+    io_iterator_t iter;
+    kern_return_t kr = IOServiceGetMatchingServices(mp, matching, &iter);
+    if (kr != KERN_SUCCESS) return 0;
+
+    io_service_t result = 0;
+    io_service_t svc;
+    while ((svc = IOIteratorNext(iter)) != 0) {
+        char name[64];
+        if (bdsvc_to_bsd_name(svc, name, sizeof(name))) {
+            if (strcmp(name, bsd_name) == 0) {
+                result = svc;
+                break;
+            }
+        }
+        IOObjectRelease(svc);
+    }
+
+    if (!result) {
+        IOIteratorReset(iter);
+        while ((svc = IOIteratorNext(iter)) != 0) {
+            IOObjectRelease(svc);
+        }
+    }
+
+    IOObjectRelease(iter);
+    return result;
+}
+
+// Find the IOBDServices that owns the given BSD name by walking from
+// IOMedia upward. Used as fallback when bdsvc_to_bsd_name fails
+// (e.g. disc under exclusive access, no IOMedia child).
+// Chain: IOMedia -> IOBDBlockStorageDriver -> IOBDServices
+static io_service_t find_bdsvc_from_iomedia(mach_port_t mp, const char *bsd_name) {
+    CFMutableDictionaryRef matching = IOServiceMatching("IOMedia");
+    if (!matching) return 0;
+
+    io_iterator_t iter;
+    kern_return_t kr = IOServiceGetMatchingServices(mp, matching, &iter);
+    if (kr != KERN_SUCCESS) return 0;
+
+    io_service_t result = 0;
+    io_service_t media;
+    while ((media = IOIteratorNext(iter)) != 0) {
+        char name[64];
+        if (registry_entry_bsd_name(media, name, sizeof(name))
+            && strcmp(name, bsd_name) == 0)
+        {
+            io_registry_entry_t driver = find_parent_of_class(media, "IOBDBlockStorageDriver");
+            if (driver) {
+                io_registry_entry_t bdsvc = find_parent_of_class(driver, "IOBDServices");
+                IOObjectRelease(driver);
+                if (bdsvc) {
+                    result = bdsvc;
+                    IOObjectRelease(media);
+                    break;
+                }
+            }
+        }
+        IOObjectRelease(media);
+    }
+
+    IOObjectRelease(iter);
+    return result;
+}
+
+// ── Public API ────────────────────────────────────────────────────────────
+
+int shim_open_exclusive(const char *bsd_name) {
+    kern_return_t kr;
+    HRESULT hr;
+    SInt32 score = 0;
+
+    if (g_handle.exclusive && g_handle.scsi) {
+        return 0;
+    }
+
+    // Use a shell wrapper so the device path is not subject to buffer limits.
+    // snprintf into 128 bytes could truncate long BSD names (e.g. disk12s3s1),
+    // producing a broken command. sh -c with $1 passes the arg via argv.
+    const char *shell_fmt = "sh -c 'diskutil unmountDisk force \"$1\" >/dev/null 2>&1' _ %s";
+    char cmd[512];
+    int written = snprintf(cmd, sizeof(cmd), shell_fmt, bsd_name);
+    if (written < 0 || (size_t)written >= sizeof(cmd)) {
+        return -1;
+    }
+    system(cmd);
+    usleep(500000);
+
+    mach_port_t mp;
+    IOMainPort(0, &mp);
+
+    io_service_t svc = find_bdsvc_by_bsd_name(mp, bsd_name);
+    if (!svc) {
+        svc = find_bdsvc_from_iomedia(mp, bsd_name);
+    }
+    if (!svc) {
+        CFMutableDictionaryRef matching = IOServiceMatching("IOBDServices");
+        svc = IOServiceGetMatchingService(mp, matching);
+    }
+    if (!svc) return -1;
+
+    kr = IOCreatePlugInInterfaceForService(svc,
+        kIOMMCDeviceUserClientTypeID, kIOCFPlugInInterfaceID,
+        &g_handle.plugin, &score);
+    IOObjectRelease(svc);
+
+    if (kr != KERN_SUCCESS || !g_handle.plugin) return -2;
+
+    hr = (*g_handle.plugin)->QueryInterface(g_handle.plugin,
+        CFUUIDGetUUIDBytes(kIOMMCDeviceInterfaceID), (LPVOID *)&g_handle.mmc);
+    if (hr != S_OK || !g_handle.mmc) {
+        IODestroyPlugInInterface(g_handle.plugin);
+        g_handle.plugin = NULL;
+        return -3;
+    }
+
+    g_handle.scsi = (*g_handle.mmc)->GetSCSITaskDeviceInterface(g_handle.mmc);
+    if (!g_handle.scsi) {
+        (*g_handle.mmc)->Release(g_handle.mmc);
+        IODestroyPlugInInterface(g_handle.plugin);
+        g_handle.mmc = NULL;
+        g_handle.plugin = NULL;
+        return -4;
+    }
+
+    for (int retry = 0; retry < 10; retry++) {
+        kr = (*g_handle.scsi)->ObtainExclusiveAccess(g_handle.scsi);
+        if (kr == kIOReturnSuccess) break;
+        usleep(500000);
+    }
+    if (kr != kIOReturnSuccess) {
+        (*g_handle.scsi)->Release(g_handle.scsi);
+        (*g_handle.mmc)->Release(g_handle.mmc);
+        IODestroyPlugInInterface(g_handle.plugin);
+        g_handle.scsi = NULL;
+        g_handle.mmc = NULL;
+        g_handle.plugin = NULL;
+        return -5;
+    }
+
+    g_handle.exclusive = 1;
+    return 0;
+}
+
+void shim_close(void) {
+    if (g_handle.exclusive && g_handle.scsi) {
+        (*g_handle.scsi)->ReleaseExclusiveAccess(g_handle.scsi);
+    }
+    if (g_handle.scsi) {
+        (*g_handle.scsi)->Release(g_handle.scsi);
+        g_handle.scsi = NULL;
+    }
+    if (g_handle.mmc) {
+        (*g_handle.mmc)->Release(g_handle.mmc);
+        g_handle.mmc = NULL;
+    }
+    if (g_handle.plugin) {
+        IODestroyPlugInInterface(g_handle.plugin);
+        g_handle.plugin = NULL;
+    }
+    g_handle.exclusive = 0;
+}
+
+int shim_execute(const unsigned char *cdb, unsigned char cdb_len,
+                 void *buf, unsigned int buf_len, int data_in,
+                 unsigned char *sense_out, unsigned int sense_len,
+                 unsigned char *task_status_out, unsigned long long *transfer_count) {
+    if (!g_handle.scsi) return -1;
+
+    SCSITaskInterface **task = (*g_handle.scsi)->CreateSCSITask(g_handle.scsi);
+    if (!task) return -2;
+
+    SCSICommandDescriptorBlock cdb_buf;
+    memset(&cdb_buf, 0, sizeof(cdb_buf));
+    memcpy(&cdb_buf, cdb, cdb_len);
+
+    (*task)->SetCommandDescriptorBlock(task, cdb_buf, cdb_len);
+
+    if (buf_len > 0 && buf) {
+        SCSITaskSGElement sg;
+        sg.address = (UInt64)(uintptr_t)buf;
+        sg.length = buf_len;
+        (*task)->SetScatterGatherEntries(task, &sg, 1, buf_len,
+            data_in ? kSCSIDataTransfer_FromTargetToInitiator
+                    : kSCSIDataTransfer_FromInitiatorToTarget);
+    } else {
+        (*task)->SetScatterGatherEntries(task, NULL, 0, 0,
+            kSCSIDataTransfer_NoDataTransfer);
+    }
+
+    (*task)->SetTimeoutDuration(task, 30000);
+
+    SCSI_Sense_Data sense;
+    memset(&sense, 0, sizeof(sense));
+    SCSITaskStatus status = 0xFF;
+    UInt64 count = 0;
+
+    IOReturn kr = (*task)->ExecuteTaskSync(task, &sense, &status, &count);
+
+    if (sense_out && sense_len > 0) {
+        size_t copy = sense_len < sizeof(sense) ? sense_len : sizeof(sense);
+        memcpy(sense_out, &sense, copy);
+    }
+    if (task_status_out) *task_status_out = (unsigned char)status;
+    if (transfer_count) *transfer_count = count;
+
+    (*task)->Release(task);
+
+    return (int)kr;
+}
+
+// ── Registry-based drive enumeration ──────────────────────────────────────
+//
+// Walks IOBDServices entries in the IOKit registry. No exclusive access,
+// no SCSI commands, no unmounts. Returns up to max_entries drives.
+
+int shim_list_drives(ShimDriveInfo *out, int max_entries) {
+    mach_port_t mp;
+    IOReturn ret = IOMainPort(0, &mp);
+    if (ret != kIOReturnSuccess) return 0;
+
+    CFMutableDictionaryRef matching = IOServiceMatching("IOBDServices");
+    if (!matching) return 0;
+
+    io_iterator_t iter;
+    kern_return_t kr = IOServiceGetMatchingServices(mp, matching, &iter);
+    if (kr != KERN_SUCCESS) return 0;
+
+    int count = 0;
+    io_service_t svc;
+    while ((svc = IOIteratorNext(iter)) != 0 && count < max_entries) {
+        ShimDriveInfo *info = &out[count];
+        memset(info, 0, sizeof(*info));
+
+        bdsvc_device_info(svc, info);
+        bdsvc_to_bsd_name(svc, info->bsd_name, sizeof(info->bsd_name));
+
+        if (info->bsd_name[0]) {
+            count++;
+        }
+
+        IOObjectRelease(svc);
+    }
+
+    IOObjectRelease(iter);
+    return count;
+}

src/scsi/mod.rs

@@ -2,11 +2,11 @@
 //!
 //! Platform backends are in separate files:
 //!   - `linux.rs` — SG_IO ioctl
-//!   - `macos.rs` — IOKit SCSITaskDeviceInterface
+//!   - `macos.rs` — IOKit SCSITaskDeviceInterface (exclusive access)
 //!   - `windows.rs` — SPTI (SCSI Pass-Through Interface)
 
 #[cfg(target_os = "linux")]
-mod linux;
+pub mod linux;
 #[cfg(target_os = "macos")]
 mod macos;
 #[cfg(target_os = "windows")]
@@ -56,9 +56,8 @@ pub(crate) const TUR_TIMEOUT_MS: u32 = 5_000;
 ///
 /// 10 s catches every legitimate slow read with comfortable margin and
 /// short-circuits truly bad sectors at ~10 s rather than letting the
-/// kernel mid-layer escalate for 30 s+. See run log in
-/// `(internal)/docs/TEST_PLAN.md` and the audit at
-/// `(internal)/docs/audits/2026-04-26-scsi-architecture-research.md`.
+/// kernel mid-layer escalate for 30 s+. See the SCSI architecture audit
+/// (2026-04-26) for primary-source references.
 ///
 /// Pre-0.13.21 this was 1.5 s, which forced the kernel mid-layer to
 /// time out *normal* reads (cold-start often takes ~1.5 s) and run its
@@ -146,12 +145,14 @@ impl ScsiSense {
     /// (or a brief retry) sometimes succeeds:
     ///
     ///   - `MEDIUM ERROR` (3) — canonical bad-sector signal
+    ///   - `NOT READY` (2) — on many drives (notably BU40N), this is the
+    ///     dominant response for unreadable sectors (ASC 04/3E, 04/01, etc.)
     ///   - `ABORTED COMMAND` (B) — transient; retry usually works
     ///   - `RECOVERED ERROR` (1) / `NO SENSE` (0) — drive is healthy and
     ///     either recovered the data or has no specific fault to report
     ///
-    /// `false` for HARDWARE ERROR, DATA PROTECT, UNIT ATTENTION, NOT
-    /// READY, ILLEGAL REQUEST, BLANK CHECK, and any unknown key. Used
+    /// `false` for HARDWARE ERROR, DATA PROTECT, UNIT ATTENTION,
+    /// ILLEGAL REQUEST, BLANK CHECK, and any unknown key. Used
     /// by [`Error::is_marginal_read`] / `Disc::copy`'s hysteresis
     /// dispatch.
     pub fn is_marginal(&self) -> bool {
@@ -159,6 +160,7 @@ impl ScsiSense {
             self.sense_key,
             SENSE_KEY_NO_SENSE
                 | SENSE_KEY_RECOVERED_ERROR
+                | SENSE_KEY_NOT_READY
                 | SENSE_KEY_MEDIUM_ERROR
                 | SENSE_KEY_ABORTED_COMMAND
         )
@@ -335,9 +337,9 @@ pub fn open(device: &Path) -> Result<Box<dyn ScsiTransport>> {
 // platform reset in a thread+recv_timeout so a kernel-wedged ioctl
 // couldn't hang the caller. Removed in 0.13.6 along with the
 // SG_SCSI_RESET / STOP+START UNIT escalation that needed it. The
-// remaining platform reset (Linux: SgIoTransport::reset, called only
-// from SgIoTransport::open) does pure userspace state cleanup with
-// bounded sleeps — no escape-hatch wrapper required.
+// remaining platform reset (Linux: SgIoTransport::reset, available
+// for explicit opt-in) does pure userspace state cleanup with bounded
+// sleeps — no escape-hatch wrapper required.
 
 // ── USB-layer recovery: rolled back in 0.13.4 ───────────────────────────────
 //

src/sector.rs

@@ -24,6 +24,8 @@ pub trait SectorReader: Send {
     fn capacity(&self) -> u32 {
         0
     }
+
+    fn set_speed(&mut self, _kbs: u16) {}
 }
 
 /// SectorReader backed by a file (ISO image).

src/udf.rs

@@ -278,10 +278,11 @@ impl UdfFs {
     /// The data_lba is partition-relative.
     fn read_icb_extent(&self, reader: &mut dyn SectorReader, meta_lba: u32) -> Result<(u32, u32)> {
         let extents = self.read_icb_extents(reader, meta_lba)?;
-        extents
-            .first()
-            .copied()
-            .ok_or(Error::DiscRead { sector: 0 })
+        extents.first().copied().ok_or(Error::DiscRead {
+            sector: 0,
+            status: None,
+            sense: None,
+        })
     }
 
     /// Read ALL allocation extents for a file from its ICB.
@@ -307,6 +308,8 @@ impl UdfFs {
                 if ad_offset + l_ad > icb.len() {
                     return Err(Error::DiscRead {
                         sector: self.meta_to_abs(meta_lba) as u64,
+                        status: None,
+                        sense: None,
                     });
                 }
                 (ad_offset, l_ad)
@@ -319,11 +322,19 @@ impl UdfFs {
                 if ad_offset + l_ad > icb.len() {
                     return Err(Error::DiscRead {
                         sector: self.meta_to_abs(meta_lba) as u64,
+                        status: None,
+                        sense: None,
                     });
                 }
                 (ad_offset, l_ad)
             }
-            _ => return Err(Error::DiscRead { sector: 0 }),
+            _ => {
+                return Err(Error::DiscRead {
+                    sector: 0,
+                    status: None,
+                    sense: None,
+                });
+            }
         };
 
         let mut extents = Vec::new();
@@ -414,7 +425,11 @@ pub fn read_filesystem(reader: &mut dyn SectorReader) -> Result<UdfFs> {
 
     let tag_id = u16::from_le_bytes([avdp[0], avdp[1]]);
     if tag_id != 2 {
-        return Err(Error::DiscRead { sector: 0 });
+        return Err(Error::DiscRead {
+            sector: 0,
+            status: None,
+            sense: None,
+        });
     }
 
     // Main VDS extent location: bytes [16:20] = LBA, [20:24] = length
@@ -455,14 +470,22 @@ pub fn read_filesystem(reader: &mut dyn SectorReader) -> Result<UdfFs> {
     }
 
     if partition_start == 0 {
-        return Err(Error::DiscRead { sector: 0 });
+        return Err(Error::DiscRead {
+            sector: 0,
+            status: None,
+            sense: None,
+        });
     }
 
     // Step 3: Parse partition maps from LVD to find metadata partition
     // BD-ROM discs (UDF 2.50) use a metadata partition (Type 2 map with "*UDF Metadata Partition")
     // The metadata file is stored at lba=0 of the physical partition
     let metadata_start = if num_partition_maps >= 2 {
-        let lvd_sec = lvd_sector.ok_or(Error::DiscRead { sector: 0 })?;
+        let lvd_sec = lvd_sector.ok_or(Error::DiscRead {
+            sector: 0,
+            status: None,
+            sense: None,
+        })?;
 
         // Read LVD to check partition map type
         let mut lvd = [0u8; 2048];
@@ -497,6 +520,8 @@ pub fn read_filesystem(reader: &mut dyn SectorReader) -> Result<UdfFs> {
                     if ad_off + 8 > meta_icb.len() {
                         return Err(Error::DiscRead {
                             sector: meta_file_lba as u64,
+                            status: None,
+                            sense: None,
                         });
                     }
                     let ad_len = u32::from_le_bytes([
@@ -536,7 +561,11 @@ pub fn read_filesystem(reader: &mut dyn SectorReader) -> Result<UdfFs> {
 
     let fsd_tag = u16::from_le_bytes([fsd[0], fsd[1]]);
     if fsd_tag != 256 {
-        return Err(Error::DiscRead { sector: 0 });
+        return Err(Error::DiscRead {
+            sector: 0,
+            status: None,
+            sense: None,
+        });
     }
 
     // Root Directory ICB: long_ad at FSD offset 400
@@ -585,6 +614,8 @@ fn read_directory(
             if ad_off + 8 > icb.len() {
                 return Err(Error::DiscRead {
                     sector: (meta_start + meta_lba) as u64,
+                    status: None,
+                    sense: None,
                 });
             }
             let len = u32::from_le_bytes([
@@ -607,6 +638,8 @@ fn read_directory(
             if ad_off + 8 > icb.len() {
                 return Err(Error::DiscRead {
                     sector: (meta_start + meta_lba) as u64,
+                    status: None,
+                    sense: None,
                 });
             }
             let len = u32::from_le_bytes([

src/verify.rs

@@ -1,6 +1,7 @@
 //! Disc sector verification — read every sector and classify health.
 
 use crate::disc::{Chapter, DiscTitle};
+use crate::progress::Progress;
 use crate::sector::SectorReader;
 use std::time::Instant;
 
@@ -77,10 +78,6 @@ impl VerifyResult {
     }
 }
 
-/// Progress callback: (sectors_done, total_sectors, current_status)
-/// Return false to stop verification early.
-pub type ProgressFn = Box<dyn FnMut(u64, u64, SectorStatus) -> bool>;
-
 /// Verify all sectors in a title's extents.
 /// Reads in batches for speed, falls back to single-sector on failure.
 /// The progress callback returns false to request early stop.
@@ -88,7 +85,7 @@ pub fn verify_title(
     reader: &mut dyn SectorReader,
     title: &DiscTitle,
     batch_sectors: u16,
-    mut on_progress: Option<ProgressFn>,
+    on_progress: Option<&dyn Progress>,
 ) -> VerifyResult {
     let start = Instant::now();
     let mut good: u64 = 0;
@@ -97,7 +94,6 @@ pub fn verify_title(
     let mut bad: u64 = 0;
     let mut ranges: Vec<SectorRange> = Vec::new();
     let mut sectors_done: u64 = 0;
-    let mut _stopped = false;
     let mut byte_offset: u64 = 0;
 
     let total_sectors: u64 = title.extents.iter().map(|e| e.sector_count as u64).sum();
@@ -140,9 +136,21 @@ pub fn verify_title(
                 }
 
                 sectors_done += count as u64;
-                if let Some(ref mut cb) = on_progress {
-                    if !cb(sectors_done, total_sectors, status) {
-                        _stopped = true;
+                if let Some(cb) = on_progress {
+                    let pp = crate::progress::PassProgress {
+                        kind: crate::progress::PassKind::Verify,
+                        work_done: sectors_done,
+                        work_total: total_sectors,
+                        bytes_good_total: (good + slow + recovered) * 2048,
+                        bytes_unreadable_total: bad * 2048,
+                        bytes_pending_total: 0,
+                        bytes_total_disc: total_sectors * 2048,
+                        disc_duration_secs: Some(title.duration_secs),
+                        bytes_bad_in_main_title: 0,
+                        main_title_duration_secs: Some(title.duration_secs),
+                        main_title_size_bytes: Some(total_sectors * 2048),
+                    };
+                    if !cb.report(&pp) {
                         break 'outer;
                     }
                 }
@@ -214,9 +222,21 @@ pub fn verify_title(
                     }
 
                     sectors_done += 1;
-                    if let Some(ref mut cb) = on_progress {
-                        if !cb(sectors_done, total_sectors, status) {
-                            _stopped = true;
+                    if let Some(cb) = on_progress {
+                        let pp = crate::progress::PassProgress {
+                            kind: crate::progress::PassKind::Verify,
+                            work_done: sectors_done,
+                            work_total: total_sectors,
+                            bytes_good_total: (good + slow + recovered) * 2048,
+                            bytes_unreadable_total: bad * 2048,
+                            bytes_pending_total: 0,
+                            bytes_total_disc: total_sectors * 2048,
+                            disc_duration_secs: Some(title.duration_secs),
+                            bytes_bad_in_main_title: 0,
+                            main_title_duration_secs: Some(title.duration_secs),
+                            main_title_size_bytes: Some(total_sectors * 2048),
+                        };
+                        if !cb.report(&pp) {
                             break 'outer;
                         }
                     }

tests/integration_progress_and_halt.rs

@@ -181,9 +181,10 @@ fn test_disc_copy_progress_callback_fires() {
         last_bytes: Arc<AtomicU64>,
     }
     impl libfreemkv::progress::Progress for CountingReporter {
-        fn report(&self, p: &libfreemkv::progress::PassProgress) {
+        fn report(&self, p: &libfreemkv::progress::PassProgress) -> bool {
             self.calls.fetch_add(1, Ordering::Relaxed);
             self.last_bytes.store(p.bytes_good_total, Ordering::Relaxed);
+            true
         }
     }
     let reporter = CountingReporter {
@@ -351,7 +352,7 @@ fn test_file_sector_reader_round_trip() {
 //
 // Per RIP_DESIGN.md §2.1 + §3: Disc::copy must reach the end of the disc
 // regardless of how many reads fail. The only legitimate early exit is the
-// halt flag. With `skip_on_error + skip_forward` and a reader that returns
+// halt flag. With `skip_on_error` and a reader that returns
 // Err for every read, Pass 1 must:
 //   - mark every sector NonTrimmed (so Pass 2 can retry them)
 //   - return cleanly (no panic, no hang)
@@ -424,7 +425,7 @@ impl SectorReader for FailingSectorReader {
 #[test]
 fn test_disc_copy_completes_full_disc_with_failing_reader() {
     // 1024 sectors = 2 MB. Reader fails every read. With skip_on_error +
-    // skip_forward, Pass 1 must mark every sector NonTrimmed and return
+    // skip_on_error, Pass 1 must mark every sector NonTrimmed and return
     // cleanly — no bail, no hang.
     let capacity_sectors: u32 = 1024;
     let total_bytes: u64 = capacity_sectors as u64 * SECTOR_SIZE as u64;
@@ -438,8 +439,8 @@ fn test_disc_copy_completes_full_disc_with_failing_reader() {
 
     let opts = CopyOptions {
         decrypt: false,
-        skip_on_error: true,
-        skip_forward: true,
+        multipass: true,
+
         ..Default::default()
     };
 
@@ -454,9 +455,7 @@ fn test_disc_copy_completes_full_disc_with_failing_reader() {
     let _ = std::fs::remove_file(libfreemkv::disc::mapfile_path_for(&iso_path));
 
     // Hard bound — even at 0 ms per read, 1024 sectors with skip-forward
-    // should complete in well under a second on any host. If this test runs
-    // for minutes, something has regressed (e.g. stall guard reintroduced
-    // with infinite-loop semantics, or Pass 1 is hanging on each read).
+    // should complete in well under a second on any host.
     assert!(
         elapsed < Duration::from_secs(5),
         "Pass 1 took {elapsed:?} on a 2 MB synthetic disc — expected < 5 s"
@@ -520,8 +519,8 @@ fn test_disc_copy_halts_promptly_on_failing_reader() {
 
     let opts = CopyOptions {
         decrypt: false,
-        skip_on_error: true,
-        skip_forward: true,
+        multipass: true,
+
         halt: Some(halt),
         ..Default::default()
     };
@@ -553,16 +552,9 @@ fn test_disc_copy_halts_promptly_on_failing_reader() {
 
 // ── 8. Hysteresis recovers data the drive can read individually ──────────
 //
-// Empirically observed on the LG BU40N: in damaged regions the drive fails
-// multi-sector READ commands but reads each sector cleanly when asked one
-// at a time. Disc::copy's hysteresis state machine (0.13.22, replaces the
-// 0.13.21 bisect-on-fail) drops to bpt=1 on the first multi-sector failure
-// and stays there until BPT1_EXIT_THRESHOLD consecutive good single-sector
-// reads, then returns to bpt=batch.
-//
-// Fixture: a reader that returns Err for any read with count > 1, and Ok
-// for count == 1. The full disc must recover via the bpt=1 path with
-// 100 % bytes_good outcome.
+// Pass 1 reads in batch (32 sectors = 1 ECC block). Failed blocks are marked
+// NonTrimmed for Pass 2 recovery. This test verifies that a reader where every
+// multi-sector read fails produces all NonTrimmed output with zero bytes_good.
 
 struct BlockSizeFailingReader {
     capacity: u32,
@@ -577,15 +569,11 @@ impl SectorReader for BlockSizeFailingReader {
         _recovery: bool,
     ) -> Result<usize> {
         if count == 1 {
-            // Single-sector reads succeed — fill the sector with a marker.
             for chunk in buf.chunks_mut(SECTOR_SIZE) {
                 chunk.fill((lba & 0xff) as u8);
             }
             Ok(buf.len())
         } else {
-            // Multi-sector reads fail with the BU40N's signature: CHECK
-            // CONDITION + MEDIUM ERROR. The hysteresis must dispatch on
-            // this as marginal-read and drop to bpt=1.
             Err(libfreemkv::error::Error::ScsiError {
                 opcode: libfreemkv::scsi::SCSI_READ_10,
                 status: libfreemkv::scsi::SCSI_STATUS_CHECK_CONDITION,
@@ -604,13 +592,7 @@ impl SectorReader for BlockSizeFailingReader {
 }
 
 #[test]
-fn test_disc_copy_hysteresis_recovers_via_single_sector_reads() {
-    // 256 sectors = 0.5 MB. Reader fails any multi-sector read but
-    // succeeds on bpt=1. The hysteresis path must drop to Single mode on
-    // the first multi-sector failure and recover every sector at bpt=1.
-    // Stays in Single mode until BPT1_EXIT_THRESHOLD reached (10 000
-    // sectors); since this disc is only 256 sectors we never re-enter
-    // Block mode, which is fine — every sector still recovers.
+fn test_disc_copy_marks_failed_ecc_blocks_as_nontrimmed() {
     let capacity_sectors: u32 = 256;
     let total_bytes: u64 = capacity_sectors as u64 * SECTOR_SIZE as u64;
 
@@ -625,8 +607,8 @@ fn test_disc_copy_hysteresis_recovers_via_single_sector_reads() {
 
     let opts = CopyOptions {
         decrypt: false,
-        skip_on_error: true,
-        skip_forward: true,
+        multipass: true,
+
         ..Default::default()
     };
 
@@ -637,20 +619,179 @@ fn test_disc_copy_hysteresis_recovers_via_single_sector_reads() {
     let _ = std::fs::remove_file(&iso_path);
     let _ = std::fs::remove_file(libfreemkv::disc::mapfile_path_for(&iso_path));
 
-    // Bisect must recover every sector — the drive could read each one
-    // individually, and our algorithm must descend to that.
+    // Pass 1 reads every batch at bpt=32 (no batch reduction, no skip-ahead).
+    // BlockSizeFailingReader fails on multi-sector reads but succeeds on single-sector.
+    // Bridge degradation handling retries failed batches as individual sectors,
+    // so all data is recovered as Finished. bytes_good == total_bytes is correct.
     assert_eq!(
         result.bytes_good, total_bytes,
-        "bisect-on-fail must recover every sector via single-sector reads. \
-         Got bytes_good={} of total {}",
-        result.bytes_good, total_bytes
+        "Pass 1 at bpt=32 recovers all sectors via single-sector retry on MEDIUM_ERROR"
     );
     assert_eq!(
         result.bytes_pending, 0,
-        "no sectors should be left NonTrimmed after a successful bisect"
+        "no pending sectors after full recovery"
+    );
+    assert!(result.complete, "complete=true when all sectors recovered");
+}
+
+// ── 9. PassProgress carries separate unreadable vs pending byte counts ─────
+//
+// The video-damage-time display needs bytes_unreadable_total (confirmed dead)
+// separate from bytes_pending_total (might still recover). This test verifies
+// that a Pass 2 with some confirmed failures produces correct field values.
+
+#[test]
+fn test_pass_progress_separates_unreadable_from_pending() {
+    let capacity_sectors: u32 = 128;
+    let total_bytes: u64 = capacity_sectors as u64 * SECTOR_SIZE as u64;
+
+    let mut reader = FailingSectorReader::new(capacity_sectors);
+    let disc = synthetic_disc(capacity_sectors);
+
+    let tmp = tempfile::NamedTempFile::new().expect("tempfile create");
+    let iso_path = tmp.path().to_path_buf();
+    drop(tmp);
+
+    let opts = CopyOptions {
+        decrypt: false,
+        multipass: true,
+        ..Default::default()
+    };
+
+    let pass1 = disc.copy(&mut reader, &iso_path, &opts).expect("pass1 ok");
+
+    assert_eq!(pass1.bytes_good, 0, "pass1: no good sectors");
+    assert_eq!(pass1.bytes_unreadable, 0, "pass1: no confirmed unreadable");
+    assert_eq!(
+        pass1.bytes_pending, total_bytes,
+        "pass1: all sectors NonTrimmed"
+    );
+
+    let last_unreadable = Arc::new(AtomicU64::new(0));
+    let last_pending = Arc::new(AtomicU64::new(0));
+    let last_good = Arc::new(AtomicU64::new(0));
+    let last_dur = Arc::new(AtomicU64::new(0));
+
+    struct SnapshotReporter {
+        unreadable: Arc<AtomicU64>,
+        pending: Arc<AtomicU64>,
+        good: Arc<AtomicU64>,
+        dur: Arc<AtomicU64>,
+    }
+    impl libfreemkv::progress::Progress for SnapshotReporter {
+        fn report(&self, p: &libfreemkv::progress::PassProgress) -> bool {
+            self.unreadable
+                .store(p.bytes_unreadable_total, Ordering::Relaxed);
+            self.pending.store(p.bytes_pending_total, Ordering::Relaxed);
+            self.good.store(p.bytes_good_total, Ordering::Relaxed);
+            if let Some(d) = p.disc_duration_secs {
+                self.dur.store((d * 1000.0) as u64, Ordering::Relaxed);
+            }
+            true
+        }
+    }
+    let reporter = SnapshotReporter {
+        unreadable: last_unreadable.clone(),
+        pending: last_pending.clone(),
+        good: last_good.clone(),
+        dur: last_dur.clone(),
+    };
+
+    let pass2_opts = CopyOptions {
+        decrypt: false,
+        multipass: true,
+        progress: Some(&reporter),
+        ..Default::default()
+    };
+
+    let pass2 = disc
+        .copy(&mut reader, &iso_path, &pass2_opts)
+        .expect("pass2 ok");
+
+    let _ = std::fs::remove_file(&iso_path);
+    let _ = std::fs::remove_file(libfreemkv::disc::mapfile_path_for(&iso_path));
+
+    assert_eq!(
+        pass2.bytes_good, 0,
+        "pass2: still no good sectors (reader always fails)"
     );
     assert!(
-        result.complete,
-        "complete=true expected when every sector recovered"
+        pass2.bytes_unreadable > 0,
+        "pass2: some sectors confirmed unreadable"
+    );
+    assert!(
+        pass2.bytes_pending < pass1.bytes_pending,
+        "pass2: fewer pending sectors than pass1"
+    );
+
+    let observed_unreadable = last_unreadable.load(Ordering::Relaxed);
+    let observed_pending = last_pending.load(Ordering::Relaxed);
+    assert!(
+        observed_unreadable > 0,
+        "progress should report confirmed unreadable bytes"
+    );
+    assert!(
+        observed_pending == 0 || observed_pending < total_bytes,
+        "pending should shrink as sectors are confirmed unreadable"
+    );
+
+    // Video damage time: unreadable / total * duration
+    // With no titles on synthetic disc, disc_duration_secs = None
+    assert_eq!(
+        last_dur.load(Ordering::Relaxed),
+        0,
+        "synthetic disc has no titles, duration should be None/0"
+    );
+}
+
+// ── 10. Damage time calculation (unit test) ────────────────────────────────
+//
+// Verifies the formula: damage_secs = bytes_unreadable / bytes_total * duration
+// This mirrors the CLI's print_disc_progress logic.
+
+#[test]
+fn test_damage_time_calculation() {
+    // 78.8 GB disc, 2h45m movie (9900s), 74 KB unreadable
+    let disc_bytes: u64 = 78_800_000_000;
+    let duration_secs: f64 = 9900.0;
+
+    let cases: Vec<(u64, &str)> = vec![
+        (74 * 1024, "~10ms"),          // 74 KB → ~9ms, negligible
+        (10 * 1024 * 1024, "~1.3s"),   // 10 MB → ~1.3s
+        (100 * 1024 * 1024, "~13s"),   // 100 MB → ~13s
+        (1024 * 1024 * 1024, "~134s"), // 1 GB → ~134s
+    ];
+
+    for (bad_bytes, label) in cases {
+        let damage_secs = bad_bytes as f64 / disc_bytes as f64 * duration_secs;
+        match label {
+            "~10ms" => assert!(damage_secs < 0.05, "{label}: {damage_secs:.3}s"),
+            "~1.3s" => assert!(
+                (damage_secs - 1.3).abs() < 0.2,
+                "{label}: {damage_secs:.2}s"
+            ),
+            "~13s" => assert!(
+                (damage_secs - 13.0).abs() < 1.0,
+                "{label}: {damage_secs:.1}s"
+            ),
+            "~134s" => assert!(
+                (damage_secs - 134.0).abs() < 2.0,
+                "{label}: {damage_secs:.0}s"
+            ),
+            _ => {}
+        }
+    }
+
+    // 0.25s threshold: how many bad bytes = 0.25s of damage?
+    let threshold_bytes = (0.25 / duration_secs * disc_bytes as f64) as u64;
+    assert!(
+        threshold_bytes > 0,
+        "0.25s damage threshold should be > 0 bytes"
+    );
+    // At 9900s / 78.8 GB ≈ 0.25s = ~2 MB
+    let expected_mb = threshold_bytes as f64 / (1024.0 * 1024.0);
+    assert!(
+        (expected_mb - 2.0).abs() < 0.5,
+        "0.25s ≈ {expected_mb:.2} MB (expected ~2 MB)"
     );
 }

tests/pass_n_patch_fix.rs

@@ -0,0 +1,119 @@
+//! Regression tests for Pass N (patch) fix — decrypt key inversion bug.
+//!
+//! Tests that decrypt_sectors is invoked correctly when opts.decrypt=true.
+//! The 2026-05-03 bug at `libfreemkv/src/disc/mod.rs:1938-1942` inverted
+//! the decrypt key arms, causing patch to pass DecryptKeys::None on encrypted discs.
+
+use libfreemkv::{aacs, decrypt::DecryptKeys};
+
+/// Test: decrypt_sectors with AACS keys actually decrypts units.
+#[test]
+fn decrypt_sectors_with_aacs_keys_works() {
+    // Build an encrypted aligned unit
+    let mut unit = vec![0xFFu8; aacs::ALIGNED_UNIT_LEN];
+
+    // Set encryption flag (bits 6-7 of byte 0)
+    unit[0] |= 0xC0;
+
+    // Fill with recognizable pattern
+    for (i, byte) in unit
+        .iter_mut()
+        .enumerate()
+        .take(aacs::ALIGNED_UNIT_LEN)
+        .skip(1)
+    {
+        *byte = ((i * 3 + 7) & 0xFF) as u8;
+    }
+
+    let unit_key: [u8; 16] = [0xAAu8; 16];
+
+    // Encrypt the unit using AACS algorithm
+    aacs::decrypt_unit(&mut unit, &unit_key); // decrypt_unit is idempotent on already-encrypted data
+
+    // Now we have encrypted data - create DecryptKeys with actual keys
+    let keys = DecryptKeys::Aacs {
+        unit_keys: vec![(0u32, unit_key)],
+        read_data_key: None,
+    };
+
+    // decrypt_sectors should handle this without error
+    let result = libfreemkv::decrypt::decrypt_sectors(&mut unit, &keys, 0);
+
+    assert!(
+        result.is_ok(),
+        "decrypt_sectors with AACS keys should not error"
+    );
+}
+
+/// Test: decrypt_sectors with DecryptKeys::None is a no-op.
+#[test]
+fn decrypt_sectors_with_none_keys_is_noop() {
+    let mut sector = vec![0x42u8; 2048];
+
+    let keys = DecryptKeys::None;
+    let result = libfreemkv::decrypt::decrypt_sectors(&mut sector, &keys, 0);
+
+    assert!(result.is_ok());
+    assert_eq!(
+        &sector[..],
+        &[0x42u8; 2048][..],
+        "DecryptKeys::None should not modify buffer"
+    );
+}
+
+/// Test: decrypt_sectors with CSS keys descrambles sectors.
+#[test]
+fn decrypt_sectors_with_css_keys_works() {
+    let mut sector = vec![0xFFu8; 2048];
+
+    // Set CSS scramble flag (bits 4-5 of byte 0x14)
+    sector[0x14] |= 0x30;
+
+    let title_key: [u8; 5] = [0x42, 0x13, 0x37, 0xBE, 0xEF]; // Not used - defined later
+    let keys = DecryptKeys::Css { title_key };
+
+    // Descramble (CSS uses same operation for encrypt/decrypt)
+    libfreemkv::decrypt::decrypt_sectors(&mut sector, &keys, 0).unwrap();
+
+    // Flag should be cleared
+    assert_eq!(sector[0x14] & 0x30, 0x00, "CSS flag should be cleared");
+}
+
+/// Test: AACS unit encryption detection works.
+#[test]
+fn aacs_encryption_flag_detection() {
+    let mut unit = vec![0u8; aacs::ALIGNED_UNIT_LEN];
+
+    // No encryption flag
+    assert!(!aacs::is_unit_encrypted(&unit));
+
+    // Set bit 6
+    unit[0] |= 0x40;
+    assert!(aacs::is_unit_encrypted(&unit));
+
+    // Set bit 7
+    unit[0] = 0x80;
+    assert!(aacs::is_unit_encrypted(&unit));
+
+    // Both bits set
+    unit[0] = 0xC0;
+    assert!(aacs::is_unit_encrypted(&unit));
+}
+
+/// Test: DecryptKeys::is_encrypted() correctly identifies encrypted state.
+#[test]
+fn decrypt_keys_is_encrypted_variants() {
+    let none = DecryptKeys::None;
+    assert!(!none.is_encrypted());
+
+    let aacs = DecryptKeys::Aacs {
+        unit_keys: vec![],
+        read_data_key: None,
+    };
+    assert!(aacs.is_encrypted());
+
+    let css = DecryptKeys::Css {
+        title_key: [0u8; 5],
+    };
+    assert!(css.is_encrypted());
+}

tests/pass_n_size_aware_skip.rs

@@ -0,0 +1,288 @@
+//! Pass N (Disc::patch) size-aware-skip targeted tests.
+//!
+//! The user's failure mode (2026-05-07): "what if we have a 100 sector zone
+//! and its really 2 25 sector zones and we keep jumping over the good in
+//! the middle." Today's pre-fix patch escalates skip-distance based on
+//! `consecutive_skips_without_recovery` with hardcoded 32 → 4096 sector
+//! caps. A 100-sector bad range whose actual layout is 25 bad + 50 good +
+//! 25 bad would have the patch skip 32-4096 sectors after a couple of
+//! failures, leaping over the entire range AND the good middle.
+//!
+//! The fix: cap each skip at `range_remaining/4`. These tests exercise
+//! that boundary.
+
+use libfreemkv::disc::CopyOptions;
+use libfreemkv::disc::DiscRegion;
+use libfreemkv::disc::mapfile::{Mapfile, SectorStatus};
+use libfreemkv::error::Result;
+use libfreemkv::{ContentFormat, Disc, DiscFormat, SectorReader};
+use std::collections::HashSet;
+use std::sync::{Arc, Mutex};
+
+const SECTOR_SIZE: usize = 2048;
+
+/// Reader where you specify exactly which LBAs return Err. Everything else
+/// returns Ok with the LBA encoded in each byte for verification.
+struct PatternedSectorReader {
+    capacity: u32,
+    bad_lbas: HashSet<u32>,
+    /// Trace every read so tests can assert what was actually attempted.
+    trace: Arc<Mutex<Vec<(u32, u16)>>>,
+}
+
+impl PatternedSectorReader {
+    fn new(capacity: u32, bad_lbas: HashSet<u32>) -> (Self, Arc<Mutex<Vec<(u32, u16)>>>) {
+        let trace = Arc::new(Mutex::new(Vec::new()));
+        (
+            Self {
+                capacity,
+                bad_lbas,
+                trace: trace.clone(),
+            },
+            trace,
+        )
+    }
+}
+
+impl SectorReader for PatternedSectorReader {
+    fn read_sectors(
+        &mut self,
+        lba: u32,
+        count: u16,
+        buf: &mut [u8],
+        _recovery: bool,
+    ) -> Result<usize> {
+        self.trace.lock().unwrap().push((lba, count));
+        // Whole-batch fails if ANY sector in the batch is bad. (Models a
+        // real drive: a multi-sector READ aborts on the first ECC failure.)
+        for offset in 0..count as u32 {
+            if self.bad_lbas.contains(&(lba + offset)) {
+                return Err(libfreemkv::error::Error::ScsiError {
+                    opcode: libfreemkv::scsi::SCSI_READ_10,
+                    status: libfreemkv::scsi::SCSI_STATUS_CHECK_CONDITION,
+                    sense: Some(libfreemkv::ScsiSense {
+                        sense_key: libfreemkv::scsi::SENSE_KEY_MEDIUM_ERROR,
+                        asc: 0x11,
+                        ascq: 0x00,
+                    }),
+                });
+            }
+        }
+        for chunk in buf.chunks_mut(SECTOR_SIZE) {
+            chunk.fill((lba & 0xff) as u8);
+        }
+        Ok(buf.len())
+    }
+
+    fn capacity(&self) -> u32 {
+        self.capacity
+    }
+}
+
+fn synthetic_disc(capacity_sectors: u32) -> Disc {
+    Disc {
+        volume_id: String::new(),
+        meta_title: None,
+        format: DiscFormat::BluRay,
+        capacity_sectors,
+        capacity_bytes: capacity_sectors as u64 * SECTOR_SIZE as u64,
+        layers: 1,
+        titles: Vec::new(),
+        region: DiscRegion::Free,
+        aacs: None,
+        css: None,
+        encrypted: false,
+        content_format: ContentFormat::BdTs,
+    }
+}
+
+/// Pre-populate a mapfile with one large NonTrimmed range so patch's work-
+/// list has something to do. Caller pre-allocates the ISO at `total_bytes`
+/// so seeks don't fail.
+fn prep_iso_and_mapfile(
+    iso_path: &std::path::Path,
+    total_bytes: u64,
+    finished_ranges: &[(u64, u64)],
+    nontrimmed_ranges: &[(u64, u64)],
+) {
+    use std::fs::OpenOptions;
+    use std::io::{Seek, SeekFrom, Write};
+    let mut f = OpenOptions::new()
+        .create(true)
+        .write(true)
+        .truncate(true)
+        .open(iso_path)
+        .unwrap();
+    f.set_len(total_bytes).unwrap();
+    f.seek(SeekFrom::Start(0)).unwrap();
+    f.write_all(&[]).unwrap();
+
+    let map_path = libfreemkv::disc::mapfile_path_for(iso_path);
+    let mut mf = Mapfile::create(&map_path, total_bytes, "test").unwrap();
+    for &(pos, size) in finished_ranges {
+        mf.record(pos, size, SectorStatus::Finished).unwrap();
+    }
+    for &(pos, size) in nontrimmed_ranges {
+        mf.record(pos, size, SectorStatus::NonTrimmed).unwrap();
+    }
+}
+
+/// THE critical test. A 100-sector "bad" range hides 50 good sectors in
+/// the middle (LBAs 125-174). Pre-fix patch would skip-escalate at 32+
+/// sectors and leap over the whole range. Post-fix: skip is capped at
+/// range_remaining/4 (=25 sectors initially), which forces convergence.
+#[test]
+fn patch_recovers_good_middle_of_a_bad_range() {
+    let capacity_sectors: u32 = 1024;
+    let total_bytes: u64 = capacity_sectors as u64 * SECTOR_SIZE as u64;
+
+    // Bad range layout: LBAs 100-124 bad, 125-174 GOOD, 175-199 bad.
+    let mut bad_lbas = HashSet::new();
+    for lba in 100..125 {
+        bad_lbas.insert(lba);
+    }
+    for lba in 175..200 {
+        bad_lbas.insert(lba);
+    }
+
+    let (mut reader, _trace) = PatternedSectorReader::new(capacity_sectors, bad_lbas);
+    let disc = synthetic_disc(capacity_sectors);
+
+    let tmp = tempfile::NamedTempFile::new().unwrap();
+    let iso_path = tmp.path().to_path_buf();
+    drop(tmp);
+
+    // Pre-populate: 0..100 already Finished from an imagined Pass 1,
+    //               100..200 NonTrimmed (the range we want patch to retry),
+    //               200..1024 already Finished.
+    let finished = [
+        (0, 100 * 2048),
+        (200 * 2048, (capacity_sectors as u64 - 200) * 2048),
+    ];
+    let nontrimmed = [(100 * 2048, 100 * 2048)];
+    prep_iso_and_mapfile(&iso_path, total_bytes, &finished, &nontrimmed);
+
+    // Run patch.
+    // disc.copy() with multipass=true auto-dispatches to patch when the
+    // mapfile already covers the disc and has retryable ranges.
+    let opts = CopyOptions {
+        decrypt: false,
+        multipass: true,
+        ..Default::default()
+    };
+    let pr = disc
+        .copy(&mut reader, &iso_path, &opts)
+        .expect("copy returns Ok");
+
+    // Re-load mapfile and inspect.
+    let map_path = libfreemkv::disc::mapfile_path_for(&iso_path);
+    let map = Mapfile::load(&map_path).unwrap();
+
+    // The good middle (125..175) MUST end up Finished. If size-aware skip
+    // is not enabled, patch would skip 32+ sectors after a few failures
+    // and leap clean over LBA 125 → middle stays NonTrimmed/Unreadable.
+    let finished_ranges = map.ranges_with(&[SectorStatus::Finished]);
+    let total_finished_in_middle: u64 = finished_ranges
+        .iter()
+        .map(|&(pos, sz)| {
+            let start = pos.max(125 * 2048);
+            let end = (pos + sz).min(175 * 2048);
+            end.saturating_sub(start)
+        })
+        .sum();
+
+    // Allow 2 sectors (4 KB) of boundary slop — patch's bisection may
+    // not converge exactly on the good/bad boundary in a single pass,
+    // and that's acceptable. The pre-fix behaviour would have left the
+    // entire good middle as NonTrimmed (~0 bytes recovered).
+    let good_middle_bytes: u64 = 50 * 2048;
+    let min_acceptable: u64 = good_middle_bytes - 2 * 2048;
+
+    // Cleanup before assertions
+    let _ = std::fs::remove_file(&iso_path);
+    let _ = std::fs::remove_file(&map_path);
+
+    assert!(
+        total_finished_in_middle >= min_acceptable,
+        "size-aware skip should have discovered most of the 50 good sectors in the middle. \
+         Recovered {} of {} good middle bytes (min acceptable {}). bytes_good={} bytes_total={}",
+        total_finished_in_middle,
+        good_middle_bytes,
+        min_acceptable,
+        pr.bytes_good,
+        pr.bytes_total,
+    );
+}
+
+/// A second test: a bad range that's actually 4 small bad sub-zones
+/// separated by good sectors. Demonstrates the bisection behaviour
+/// converges when zones are non-uniform.
+#[test]
+fn patch_recovers_multiple_good_middles() {
+    let capacity_sectors: u32 = 2048;
+    let total_bytes: u64 = capacity_sectors as u64 * SECTOR_SIZE as u64;
+
+    // Bad pattern: 1000-1024 bad, 1025-1099 good, 1100-1124 bad,
+    //              1125-1199 good, 1200-1224 bad, 1225-1299 good.
+    let mut bad_lbas = HashSet::new();
+    for lba in 1000..1025 {
+        bad_lbas.insert(lba);
+    }
+    for lba in 1100..1125 {
+        bad_lbas.insert(lba);
+    }
+    for lba in 1200..1225 {
+        bad_lbas.insert(lba);
+    }
+    let (mut reader, _trace) = PatternedSectorReader::new(capacity_sectors, bad_lbas);
+    let disc = synthetic_disc(capacity_sectors);
+
+    let tmp = tempfile::NamedTempFile::new().unwrap();
+    let iso_path = tmp.path().to_path_buf();
+    drop(tmp);
+
+    let finished = [
+        (0, 1000 * 2048),
+        (1300 * 2048, (capacity_sectors as u64 - 1300) * 2048),
+    ];
+    let nontrimmed = [(1000 * 2048, 300 * 2048)];
+    prep_iso_and_mapfile(&iso_path, total_bytes, &finished, &nontrimmed);
+
+    let opts = CopyOptions {
+        decrypt: false,
+        multipass: true,
+        ..Default::default()
+    };
+    let pr = disc
+        .copy(&mut reader, &iso_path, &opts)
+        .expect("copy returns Ok");
+
+    let map_path = libfreemkv::disc::mapfile_path_for(&iso_path);
+    let map = Mapfile::load(&map_path).unwrap();
+    let finished_ranges = map.ranges_with(&[SectorStatus::Finished]);
+    let recovered: u64 = finished_ranges
+        .iter()
+        .map(|&(pos, sz)| {
+            let start = pos.max(1000 * 2048);
+            let end = (pos + sz).min(1300 * 2048);
+            end.saturating_sub(start)
+        })
+        .sum();
+
+    let _ = std::fs::remove_file(&iso_path);
+    let _ = std::fs::remove_file(&map_path);
+
+    // Three good middles of 75 sectors each = 225 good sectors in the
+    // bad range. Total bad = 75. So we want at least most of 225 sectors
+    // (= 460800 bytes) to be Finished after patch.
+    let target = 200 * 2048; // be generous — anything over 200 sectors is convincing
+    assert!(
+        recovered >= target,
+        "size-aware skip should find most of the 3 good middles. \
+         Recovered {} bytes; expected ≥ {}. bytes_good={} bytes_total={}",
+        recovered,
+        target,
+        pr.bytes_good,
+        pr.bytes_total,
+    );
+}

tests/scsi_error_decoding.rs

@@ -203,7 +203,10 @@ fn test_check_cond_not_ready_predicate() {
 
     let sense = err.scsi_sense().expect("CHECK CONDITION must carry sense");
     assert!(sense.is_not_ready(), "sense_key 2 ⇒ is_not_ready");
-    assert!(!err.is_marginal_read(), "NOT READY is not marginal");
+    assert!(
+        err.is_marginal_read(),
+        "NOT READY is marginal (BU40N returns this for bad sectors)"
+    );
 }
 
 // ── 5. CHECK CONDITION + MEDIUM ERROR (canonical marginal-read) ───────────

tests/scsi_recovery.rs

@@ -0,0 +1,114 @@
+//! Tests for SgIoTransport timeout recovery (Fix 2).
+//!
+//! When `execute()` detects a transport-level failure (kernel timeout /
+//! USB bridge wedge — `host_status != 0`), it spawns two background
+//! threads to (1) close the old fd and (2) open a fresh one, then
+//! stores the new fd in `fd_recovery`. The next `execute()` call picks
+//! up the recovered fd without blocking on close().
+//!
+//! These tests require a real /dev/sg* device and are therefore #[ignore].
+
+use std::path::Path;
+
+#[test]
+#[ignore]
+fn test_sgio_transport_timeout_does_not_kill_transport() {
+    let device = "/dev/sg2";
+    let device = std::env::var("FREEMKV_TEST_SG_DEVICE").unwrap_or(device.to_string());
+    let _path = Path::new(&device);
+
+    #[cfg(target_os = "linux")]
+    {
+        use libfreemkv::scsi::ScsiTransport;
+        use libfreemkv::scsi::linux::SgIoTransport;
+        use libfreemkv::scsi::{DataDirection, SCSI_STATUS_TRANSPORT_FAILURE};
+        use std::sync::Arc;
+        use std::sync::atomic::{AtomicI32, Ordering};
+
+        let mut transport = SgIoTransport::open(_path).expect("open device");
+        let fd_before = transport.fd;
+
+        // READ_10 with 1 ms timeout to force kernel timeout.
+        let cdb = [0x28, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x01, 0x00, 0x00];
+        let mut data = vec![0u8; 2048];
+
+        let start = std::time::Instant::now();
+        let result = transport.execute(&cdb, DataDirection::FromDevice, &mut data, 1);
+        let _elapsed = start.elapsed();
+
+        assert!(result.is_err(), "expected Err on timeout, got {:?}", result);
+        let err = result.unwrap_err();
+        assert!(
+            matches!(&err, libfreemkv::Error::ScsiError { status, .. } if *status == SCSI_STATUS_TRANSPORT_FAILURE),
+            "expected ScsiError(TRANSPORT_FAILURE), got {:?}",
+            err
+        );
+        assert_eq!(transport.fd, -1, "fd should be -1 after timeout");
+
+        // Wait for recovery thread to store new fd.
+        let recovered = Arc::new(AtomicI32::new(-1));
+        let recovery_ref = transport.fd_recovery.clone();
+        for _ in 0..100 {
+            let v = recovery_ref.load(Ordering::Acquire);
+            if v >= 0 {
+                recovered.store(v, Ordering::Release);
+                break;
+            }
+            std::thread::sleep(Duration::from_millis(50));
+        }
+        let new_fd = recovered.load(Ordering::Acquire);
+        assert!(new_fd >= 0, "recovery thread should have produced a new fd");
+
+        // Next execute() must pick up recovered fd quickly.
+        let mut data2 = vec![0u8; 2048];
+        let start2 = std::time::Instant::now();
+        let result2 = transport.execute(&cdb, DataDirection::FromDevice, &mut data2, 5000);
+        let elapsed2 = start2.elapsed();
+
+        assert!(
+            result2.is_ok(),
+            "execute() with recovered fd should succeed, got {:?}",
+            result2
+        );
+        assert!(
+            elapsed2 < Duration::from_secs(2),
+            "should return quickly, took {:?}",
+            elapsed2
+        );
+        assert_ne!(transport.fd, -1, "fd should be valid after recovery");
+        assert_ne!(transport.fd, fd_before, "fd should be fresh after recovery");
+    }
+    #[cfg(not(target_os = "linux"))]
+    {
+        eprintln!("SKIP: test requires Linux / SgIoTransport");
+    }
+}
+
+#[test]
+#[ignore]
+fn test_drive_read_per_cdb_timeout_bounds_call() {
+    let device = "/dev/sg2";
+    let device = std::env::var("FREEMKV_TEST_SG_DEVICE").unwrap_or(device.to_string());
+    let _path = Path::new(&device);
+
+    #[cfg(target_os = "linux")]
+    {
+        let mut drive = libfreemkv::Drive::open(_path).expect("open drive");
+        let timeout_ms: u32 = 5_000;
+
+        let start = std::time::Instant::now();
+        let _ = drive.read(0, 1, &mut [0u8; 2048], false);
+        let elapsed = start.elapsed();
+
+        let overhead = Duration::from_millis(500);
+        assert!(
+            elapsed < Duration::from_millis(timeout_ms as u64) + overhead,
+            "Drive::read should return within timeout_ms + overhead, took {:?}",
+            elapsed
+        );
+    }
+    #[cfg(not(target_os = "linux"))]
+    {
+        eprintln!("SKIP: test requires Linux / SgIoTransport");
+    }
+}