v0.13.41: debug logging for sector-0 regression

v0.13.40
fix CI: Rust 2024 match ergonomics - remove ref binding modifier
2026-10-07 18:13:10 +00:00 · 2026-04-29 07:09:46 -07:00 · 2026-04-28 21:50:32 -07:00 · 2026-04-28 21:47:19 -07:00 · 2026-04-28 21:45:34 -07:00 · 2026-04-28 21:43:14 -07:00
26 changed files with 3362 additions and 569 deletions
@@ -1,5 +1,674 @@
 # Changelog

+## 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`
+
+`MapStats.bytes_pending` aggregates `NonTried` (sectors Pass 1 hasn't
+reached) + `NonTrimmed` + `NonScraped` (sectors flagged for Pass 2-N
+retry). UIs that wanted a "MAYBE / will retry" bucket were stuck
+showing the entire unread disc as "Maybe" at pct=0.
+
+v0.13.24 keeps `bytes_pending` for back-compat and adds two granular
+fields:
+
+  - `bytes_nontried` — Pass 1 hasn't read these yet
+  - `bytes_retryable` — `NonTrimmed + NonScraped`, Pass 2-N will retry
+
+`bytes_pending == bytes_nontried + bytes_retryable` (invariant).
+
+### cargo fmt cleanup
+
+Picks up the `cargo fmt --check` lint failure that's been red on
+`main` since v0.13.18 (long format-string layouts the local rustfmt
+folded differently from CI's runner).
+
+## 0.13.23 (2026-04-27)
+
+### Stop discarding the drive's SCSI sense data
+
+Through the entire 0.13.x line, every CHECK CONDITION reply from the
+drive (the standard way SCSI reports a sector failure) was being
+collapsed into a synthetic `status=0xFF, sense_key=0` "transport
+wedge" sentinel and the real sense data was thrown away. Live tracing
+on the BU40N reading Dune 2 on 2026-04-27 confirmed it: the drive was
+returning `host_status=0, driver_status=8, status=2, exec_elapsed_ms=1416`
+on every bad sector — a clean CHECK CONDITION carrying full sense
+data — and the library was misclassifying it as a wedge and bailing.
+
+Root cause: `scsi/linux.rs`'s wedge check was `host_status != 0 ||
+driver_status != 0`. SG's `DRIVER_SENSE` bit (0x08) is set on every
+CHECK CONDITION reply just to flag "sense buffer is populated" — it's
+not a transport failure on its own. Pre-0.13.23 we conflated the two
+and silently lost every drive-reported error reason. macOS and Windows
+backends had the same shape: they extracted `sense_key` only, dropping
+ASC/ASCQ.
+
+### What 0.13.23 changes (API)
+
+- **Linux**: mask `DRIVER_SENSE` before treating `driver_status` as a
+  transport-layer failure. Real transport failures (`host_status != 0`
+  or any non-SENSE bit set) still synthesise the `0xFF` sentinel.
+- **`Error::ScsiError`** carries `sense: Option<ScsiSense>` instead of
+  flat `sense_key`/`asc`/`ascq`. `sense=None` ⇔ transport failure (no
+  SCSI status delivered). `Some(ScsiSense {…})` ⇔ drive replied with
+  sense data. Removes the `0xFF`/`sense_key=0` magic-number coupling.
+- **`ScsiSense`** is a public type with predicate methods on it —
+  `is_marginal`, `is_medium_error`, `is_hardware_error`,
+  `is_unit_attention`, `is_data_protect`, `is_not_ready`,
+  `is_illegal_request`, `is_aborted_command`. Callers route on the
+  structured fields rather than raw key comparisons.
+- **`Error::scsi_sense()`** / **`Error::is_scsi_transport_failure()`** /
+  **`Error::is_marginal_read()`** convenience predicates on `Error`.
+  `is_marginal_read` is the high-level "should `Disc::copy` engage
+  hysteresis on this error?" check.
+- **SCSI protocol constants** (`SCSI_STATUS_GOOD`,
+  `SCSI_STATUS_CHECK_CONDITION`, `SCSI_STATUS_TRANSPORT_FAILURE`,
+  `SENSE_KEY_*`) moved from `error.rs` to `scsi/mod.rs` where they
+  belong alongside `SCSI_INQUIRY`, `SCSI_READ_10`, etc.
+- **macOS** + **Windows** backends parse the full sense triple too.
+  Same code path on every platform — a regression in `parse_sense`
+  would surface on all three OSes simultaneously.
+- **`parse_sense`** replaces `parse_sense_key` (returns the full
+  triple). Inline sense-format tests (descriptor 0x72/0x73 vs fixed
+  0x70/0x71, short-buffer, VALID-bit masking, unknown response codes)
+  now also exercise ASC/ASCQ extraction at the right offsets.
+
+### Disc::copy + Disc::patch sense-aware dispatch
+
+Both passes now bail immediately when a read fails with a sense class
+that retry can't help (HARDWARE ERROR, DATA PROTECT, UNIT ATTENTION,
+NOT READY, ILLEGAL REQUEST, real transport failure, kernel `IoError`)
+rather than burning hysteresis cycles on a doomed loop. Marginal-read
+sense (MEDIUM ERROR, ABORTED COMMAND, RECOVERED ERROR, NO SENSE)
+engages hysteresis as before. New `phase=bail` trace event records
+the bail reason.
+
+`Disc::patch`'s `wedged_threshold` (50 consecutive failures) remains
+as defense-in-depth for chains of marginal failures, but a single
+non-marginal sense now short-circuits it.
+
+### Behavioural impact
+
+For damaged-disc rips on the BU40N this unblocks v0.13.22's
+hysteresis: pre-fix, the misclassified "wedge" caused `Disc::copy` to
+exit before hysteresis could engage, so `bytes_good` froze at the bad
+zone. Post-fix the drive's CHECK CONDITION replies flow through the
+normal path → hysteresis drops to bpt=1 → marginal sectors are
+recovered or marked Unreadable. Calibration data
+(`docs/audits/2026-04-26-bisect-on-fail-empirical-findings.md`) shows
+~86 % of marginal-region sectors recover at bpt=1 on this drive.
+
+## 0.13.22 (2026-04-26)
+
+### Replace bisect-on-fail with hysteresis state machine (Block ↔ Single)
+
+Live test on Dune 2 v0.13.21 showed bisect-on-fail recovered every
+recoverable sector, but spent ~30 sec per damaged 60-block (paying a
+~5 sec kernel timeout at every bisection level). Each level descended
+log₂(60) ≈ 6 times on the failing branch.
+
+Replaced with a two-state hysteresis machine in `Disc::copy`:
+
+```
+Block(batch):
+  read(batch) ok    → write, advance, stay Block
+  read(batch) fail  → switch to Single, retry SAME range at bpt=1
+
+Single:
+  read(1) ok    → write, consecutive_good++
+                  if consecutive_good >= BPT1_EXIT_THRESHOLD:
+                     switch to Block, reset counter
+  read(1) fail  → mark NonTrimmed, consecutive_good = 0
+```
+
+`BPT1_EXIT_THRESHOLD = 10_000` sectors (= 20 MB of clean data).
+Calibrated from the 2026-04-26 BU40N empirical run; tunable.
+
+Per-block cost on a 60-sector damaged block with 1 bad sector:
+- Bisect (v0.13.21): ~30 sec (5 s × 6 levels)
+- Hysteresis (v0.13.22): ~10 sec (5 s bpt=batch fail + 59 × 1 ms good
+  + 1 × 5 s bad)
+
+Plus inside a damaged cluster spanning many 60-blocks, hysteresis
+pays the bpt=batch fail cost ONCE on entry; bisection paid it every
+60 sectors. For Dune 2's ~1248-sector boundary cluster that's ~21
+fewer 5-sec waits = ~100 sec saved.
+
+Telemetry: new `phase=mode_change` trace event with `from`, `to`,
+`lba`, `consecutive_good`. Replaces v0.13.21's `phase=bisect`. The
+v0.13.21 worklist DFS is gone — single iterative `for s in 0..count`
+on the failure path.
+
+Test rename:
+`test_disc_copy_bisect_recovers_via_single_sector_reads` →
+`test_disc_copy_hysteresis_recovers_via_single_sector_reads`. Same
+synthetic BU40N-pattern reader; same 100% recovery expectation.
+
+## 0.13.21 (2026-04-26)
+
+### Fix: Disc::copy bisect-on-fail (replaces skip-forward)
+
+Empirical live-hardware testing on the LG BU40N (see
+`(internal)/docs/audits/2026-04-26-test-plan-audit.md` and the
+TEST_PLAN.md run log) revealed that the drive often **fails
+multi-sector READ commands** in damaged regions but **succeeds when
+asked one sector at a time**. The old skip-forward strategy responded
+to multi-sector failures by jumping up to 1 % of the disc forward,
+marking everything in between as bad — losing **clean territory**
+sandwiched between bad sectors.
+
+`Disc::copy` now bisects on read failure: split the failed block in
+half, retry each half, recurse down to single-sector reads. Sectors
+the drive can read individually are recovered in Pass 1; only sectors
+that fail at bpt=1 are marked NonTrimmed for the patch passes.
+
+Empirical results on Dune 2 UHD on the BU40N:
+- Old algorithm: 25 GB read in Pass 1, then ~6 GB skip-forwarded;
+  retry passes failed to recover most of the skipped zone.
+- New algorithm: ~99 % of disc recovered in Pass 1; only the truly
+  unreadable cluster (~14 % of a 2 MB hot zone) marked NonTrimmed.
+
+Implementation: stack-based DFS in the inner read loop. log₂(batch)
+levels max — for the default 60-sector batch, 6 levels. Multi-pass
+machinery is untouched: Pass 2 .. N walk the mapfile and become fast
+no-ops when bisect already recovered everything. New integration test
+`test_disc_copy_bisect_recovers_via_single_sector_reads` validates
+the behavior against a synthetic BU40N-pattern reader.
+
+### Fix: READ_TIMEOUT_MS bumped 1.5 s → 10 s (caller-side)
+
+The 0.13.20 SCSI rewrite gave the kernel mid-layer the ability to run
+its own ABORT/RESET escalation. But callers (`Drive::read` for the
+fast path) still passed `timeout_ms=1500`. Cold-start seek on the
+BU40N can take ~1.5 s, which means **normal reads were being
+cancelled at the boundary**, triggering the kernel mid-layer's
+escalation, which the Initio bridge couldn't drain — resulting in the
+firmware-level wedge that only physical replug recovers.
+
+Live-hardware probe data:
+- Sustained sequential read: 3–7 ms
+- Cold-start seek + read: up to ~1500 ms
+- Successful ECC recovery: 1.6–2.6 s
+- Confirmed unreadable: 3.6–8.8 s (kernel timeout)
+
+10 s is calibrated to cover every legitimate read with margin while
+still short-circuiting truly bad sectors before the kernel runs full
+LUN/BUS/HOST reset. `READ_RECOVERY_TIMEOUT_MS` (60 s) unchanged.
+
+## 0.13.20 (2026-04-26)
+
+### Architecture: SCSI transport — sync blocking SG_IO
+
+`scsi/linux.rs` rewritten from async `write/poll/read + 1.5 s timeout
+ close-on-timeout in bg thread` to a single synchronous blocking
+`ioctl(fd, SG_IO, &hdr)`. The old pattern abandoned slow-but-alive
+commands faster than the drive could drain its internal queue,
+deepening the BU40N wedge. Per the audit at
+`(internal)/docs/audits/2026-04-26-scsi-architecture-research.md`,
+no reference project (MakeMKV / sg_dd / ddrescue) does what we did —
+all use sync blocking SG_IO with 8-60 s timeouts and let the kernel's
+mid-layer (`scsi_eh.rst`) run ABORT TASK / LUN RESET / BUS RESET /
+HOST RESET escalation internally.
+
+What changed:
+- `SgIoTransport::execute()` is one syscall now. Caller-supplied
+  `timeout_ms` is honored by the kernel, which does its own
+  ABORT/RESET escalation if the device times out.
+- Errors check `host_status` and `driver_status` (both 0xFF-synthesised
+  for the caller) in addition to `status` — transport-level failures
+  no longer slip through as Ok.
+- Sense-key parser handles both descriptor format (0x72/0x73, key at
+  byte 1) and fixed format (0x70/0x71, key at byte 2).
+- Deleted the `fd_recovery: Arc<AtomicI32>` field, the bg close+open
+  thread, and the stale-fd swap dance. `scsi/linux.rs` shrank from
+  ~720 to ~520 lines.
+- Module doc rewritten to reflect the new architecture.
+
+### Architecture: parity strip on macOS + Windows
+
+`scsi/macos.rs` and `scsi/windows.rs` had `try_recover()` —
+userspace handle-recovery on task failure. Same anti-pattern as the
+Linux fd-recovery dance, removed for the same reason: the kernel
+mid-layer already runs its own escalation. Errors bubble up directly.
+
+Cleanups:
+- `MacScsiTransport`: `try_recover()` deleted, `bsd_name` field
+  deleted (was only used by try_recover), fail-fast device_iface guard
+  deleted (no longer null'd mid-session).
+- `SptiTransport`: `try_recover()` deleted, `wide_path` field deleted,
+  INVALID_HANDLE guard deleted.
+
+### API cleanup: drop `Drive::reset` and `find_drives`
+
+Two duplicates removed from the public surface:
+
+- `Drive::reset()` — escalating recovery (STOP/START unit + eject +
+  reinit). Per the audit, userspace shouldn't escalate; the kernel
+  already does. Only one internal caller (`wait_ready` line 195),
+  which now just keeps polling TUR for 60 iterations. No external
+  consumer used it.
+- `pub fn find_drives() -> Vec<Drive>` — opened N drives just to throw
+  most away. Only caller was `find_drive()` itself, which now uses
+  `discover_drives()` directly. No external consumer used it. For
+  lightweight enumeration (UI sidebar etc.) use `scsi::list_drives()`.
+
+`lib.rs` re-export of `find_drives` removed.
+
+## 0.13.19 (2026-04-26 — held, never released)
+
+Held in development; folded into 0.13.20.
+
+## 0.13.18 (2026-04-26)
+
+### Sync release — no functional changes
+
+Bumped to satisfy the unified-versioning rule. Actual fix is in autorip
+(`web.rs` two-bar UI — separates per-pass and total progress bars +
+their own text rows so the rip dashboard is readable again).
+
+## 0.13.17 (2026-04-26)
+
+### Sync release — no functional changes
+
+Bumped to satisfy the unified-versioning rule. Actual fix is in autorip
+(hot-plug rescan in the drive poll loop — autorip now picks up
+unplug/replug events without a container restart).
+
+## 0.13.16 (2026-04-26)
+
+### Architecture: single `Progress` trait + `PassProgress` struct
+
+Pre-0.13.16 the rip API leaked internal mapfile concepts (`pos`,
+`bytes_good`, `work_done`, `bytes_pending`, `Finished`/`NonTrimmed`)
+into per-pass positional callbacks. Consumers reinvented the math each
+time, and the v0.13.15 UI bug surfaced exactly because of this — autorip's
+web JS computed `progress_pct` from `bytes_good` while the backend
+computed from `pos`, silent drift, frozen UI bar.
+
+This release replaces both `Disc::copy::on_progress` and
+`Disc::patch::on_progress` `Fn(u64, u64, u64)` callbacks with a single
+`Progress` trait and `PassProgress` struct (new `progress` module).
+
+```rust
+pub struct PassProgress {
+    pub kind: PassKind,            // Sweep | Trim {reverse} | Scrape {reverse} | Mux
+    pub work_done: u64,
+    pub work_total: u64,
+    pub bytes_good_total: u64,
+    pub bytes_total_disc: u64,
+}
+
+pub trait Progress {
+    fn report(&self, p: &PassProgress);
+}
+
+impl<F: Fn(&PassProgress)> Progress for F { ... }
+```
+
+Both `CopyOptions::on_progress` and `PatchOptions::on_progress` are
+renamed to `progress: Option<&dyn Progress>`. Closure callers update
+trivially; struct callers gain a clean named-field shape with no
+positional-arg confusion.
+
+`PassKind` carries the semantic (sweep vs trim vs scrape vs mux) so
+consumers can label phases without reinventing detection logic. The
+`Mux` variant is reserved for v0.13.17 when the mux pipeline emits
+progress; not yet emitted by libfreemkv code.
+
+`Disc::patch` reports `Trim {reverse}` for retry passes with
+`block_sectors >= 2` and `Scrape {reverse}` when `block_sectors == 1`
+(the per-sector final pass). Direction comes through `reverse: bool`.
+
+## 0.13.15 (2026-04-26)
+
+### Breaking: `on_progress` callback gains `pos` parameter
+
+Both `CopyOptions::on_progress` and `PatchOptions::on_progress` now take
+`Fn(bytes_good: u64, pos: u64, total_bytes: u64)`. The new `pos` parameter
+is the current sweep / retry position. Pass 1 callers should display
+`pos / total_bytes` for the "% swept" UI bar — `bytes_good` only counts
+clean reads (Finished sectors) and freezes during skip-forward bad zones,
+which made every previous version's UI look hung at the bad-zone boundary.
+This was the v0.13.9 stall-guard origin bug.
+
+Live trace from v0.13.14: Pass 1 hit a Dune 2 bad zone at 24 GB and
+appeared "stuck" for 14 minutes per autorip's UI (`bytes_good = 23.97 GB`
+unchanged). Disc trace events showed `pos` actually advanced from 25.8 GB
+to 70 GB during that window — Pass 1 was 83 % through the disc, marking
+the post-bad-zone NonTrimmed via skip-forward exactly as designed. The
+display lied. Now consumers can show the truth.
+
+### Feature: `PatchOptions::reverse` for reverse-direction retry passes
+
+When set, `Disc::patch` walks bad ranges from highest LBA to lowest, and
+within each range reads sectors back-to-front. Hypothesis (per the live
+v0.13.14 test): drives that wedge after a forward read of a bad sector
+read fine when approached from end-of-disc backward — most of the
+post-bad-zone NonTrimmed range is actually clean data the drive could
+have read on Pass 1 had it not been wedged. autorip alternates F/R
+across retry passes (Pass 2 = reverse half-batch, Pass 3 = forward
+quarter-batch, ...).
+
+### Feature: `PatchOptions::wedged_threshold` early-exit
+
+When > 0, `Disc::patch` exits early if it sees this many consecutive
+read failures with zero successful reads in the same pass. Saves the
+wallclock budget for productive grinding when the drive has clearly
+wedged on the bad zone for this pass — a future pass with a different
+direction or block size may still recover. Reported via new
+`PatchResult::wedged_exit: bool`.
+
+### Trace: `patch_start` and `patch_done` events
+
+`freemkv::disc` target now emits `patch_start` (block_sectors, recovery,
+reverse, wedged_threshold, num_ranges) and `patch_done`
+(blocks_attempted, blocks_read_ok, blocks_read_failed, wedged_exit,
+halted, bytes_recovered) at Disc::patch boundaries.
+
+## 0.13.14 (2026-04-25)
+
+### Sync release — no functional changes in libfreemkv
+
+Bumped solely to satisfy the unified-versioning rule. The actual fix in
+this release is in autorip: the tracing subscriber now enables
+`freemkv::scsi=trace,freemkv::disc=trace` so the v0.13.13 instrumentation
+events actually surface in `/api/debug`. Without that filter override the
+trace events were silently dropped by the default `libfreemkv=warn` rule.
+
+## 0.13.13 (2026-04-25)
+
+### Telemetry: instrument the rip pipeline for in-flight diagnosis
+
+v0.13.12 shipped Fix 1+2+4 + cross-platform parity but a live test on Dune 2
+showed Pass 1 sat for 14 minutes with `bytes_good=0` while the inner loop
+appeared to iterate (the throttled `on_progress` log fired every 78s). The
+async fd_recovery design at §7 said each `execute()` call should bound at
+~1.5 s on poll timeout, with subsequent calls returning `DeviceNotFound` in
+microseconds until recovery completes. Observed reality contradicts that:
+each iteration takes ~60 s, not microseconds. Without trace-level telemetry
+at the SCSI + Disc::copy boundaries we can't diagnose where the time goes.
+
+This release adds the telemetry. No behavior change; instrumentation only.
+
+- New dep: `tracing = "0.1"`. Per project docs, debug/trace logging is permitted
+  in libfreemkv (the no-English rule applies to errors, not telemetry).
+  Consumers (autorip) wire a tracing subscriber and pipe events into the
+  JSONL debug log automatically.
+- `SgIoTransport::execute` (Linux): trace events at every state transition
+  (entry, recovery_swap_ok, recovery_pending, write_ok / write_err, poll_done,
+  timeout_spawn_recovery, scsi_err, read_err, ok). Each event includes the
+  opcode and elapsed timing. The bg recovery thread also traces close_ms +
+  open_ms so we can see if the kernel is hanging close+open.
+- `Disc::copy`: trace events at copy_start, outer_loop, region_enter, every
+  100 inner-loop iterations (iter_progress with pos / region_end / skip_size /
+  bytes_good / read_ok_count / read_err_count / last_read_ms /
+  copy_elapsed_ms), and copy_done.
+- All trace events use `target` strings `freemkv::scsi` and `freemkv::disc`
+  so consumers can filter by subsystem.
+
+### What this enables
+
+- A live rip will now produce a SCSI event stream visible at
+  `/api/debug?n=N&q=freemkv::scsi`. We can finally answer: "is the inner
+  loop iterating slowly because each call is slow, or fast with the bg
+  thread blocked?"
+- `bg_recovery_done` events with `close_ms` / `open_ms` reveal whether the
+  kernel really takes 60 s for close+open on a wedged Initio bridge.
+
+## 0.13.12 (2026-04-25)
+
+### Fix: delete stall guard from `Disc::copy` (RIP_DESIGN.md §6 Fix 1)
+
+The v0.13.9 stall guard at `disc/mod.rs` exited Pass 1 early when
+`bytes_good` was flat for `stall_secs` (default 120s). This violated the
+ddrescue model: Pass 1 must sweep end-to-end, marking failed reads
+NonTrimmed for Pass 2 retry. The guard caused Pass 1 to bail at 30% on
+Dune 2 with 56 GB still NonTried, leaving Pass 2 nothing useful to do.
+
+- Deleted the stall-guard state vars and the `if cur_good != ...
+  break 'outer;` block.
+- Deleted `CopyOptions::stall_secs` field — no longer wired.
+- Replaced the broken regression test
+  `test_disc_copy_stall_detection_triggers_skip_forward` with
+  `test_disc_copy_completes_full_disc_with_failing_reader` (asserts Pass 1
+  walks to end-of-disc with everything NonTrimmed when reads keep failing)
+  and added `test_disc_copy_halts_promptly_on_failing_reader` (halt flag
+  honored within 2s mid-skip-forward).
+
+### Fix: async SCSI transport recovery (RIP_DESIGN.md §6 Fix 2 / §7)
+
+`SgIoTransport::execute` (Linux) previously did close-in-background +
+synchronous open-on-main-thread on poll timeout. The kernel serialized
+the main-thread `open()` against the in-flight `close()` of the same
+`/dev/sg*`, blocking the rip thread up to ~60s per timeout.
+
+- Added `fd_recovery: Arc<AtomicI32>` field. On poll timeout, both
+  `close(old_fd)` AND `open(new_fd)` run in a background thread; the new
+  fd is published to `fd_recovery`. Returns Err immediately. Main thread
+  is never blocked beyond the `poll()` budget (~1.5 s).
+- Top of `execute()`: if `self.fd < 0`, swap from `fd_recovery`. If
+  recovery is also pending, return `DeviceNotFound` and let the caller's
+  retry loop come back later.
+- Drop drains any pending `fd_recovery` so the fd doesn't leak.
+- Stripped the v0.13.9 stall-guard narrative comment that justified
+  the deleted behavior.
+
+### Fix: cross-platform SCSI parity — Windows + macOS recovery (RIP_DESIGN.md §15.1)
+
+Per the platform parity rule (no stubs), Windows and macOS now have the
+same observable recovery contract as Linux:
+
+- `SptiTransport` (Windows): added `try_recover()` that calls
+  `CloseHandle` + `CreateFileW` synchronously after a failed
+  `DeviceIoControl`. Stripped English error string ("run as
+  administrator") from `open()`. Fixed the ms→s timeout truncation
+  (1500ms now rounds up to 2s, was 1s).
+- `MacScsiTransport` (macOS): added `try_recover()` that releases the
+  IOKit interface (`RELEASE_EXCLUSIVE` + `com_release`) and re-acquires
+  via the new `acquire_device_iface()` helper. Stores `bsd_name` so
+  recovery can re-call `find_scsi_service`.
+- All three platforms: top of `execute()` returns `DeviceNotFound`
+  immediately if a prior `try_recover()` left the transport in an
+  invalid state. Drop guards null'd-out interfaces.
+- Send is auto-derived on all three (i32 fd / isize HANDLE / IOKit
+  interface ref are Send-safe); explicit comments document the
+  intentional implicit Send and the absence of Sync.
+
+### Fix: instrument `Disc::patch` — diagnostic counters (RIP_DESIGN.md §6 Fix 4)
+
+`PatchResult` now reports `blocks_attempted`, `blocks_read_ok`,
+`blocks_read_failed`. Pass 2's "100 minutes recovered 0 bytes" mystery
+(Dune 2) becomes diagnosable from these counters: distinguish "drive
+returned Ok but write/record dropped data" from "every read was Err for
+the entire range" without instrumenting from outside the lib.
+
+### Fix: honor `PatchOptions::full_recovery`
+
+The field was previously read into `let _ = opts.full_recovery;` and
+ignored — `read_sectors(..., true)` was hardcoded. Now routed to
+`read_sectors(..., opts.full_recovery)`. Behavior unchanged for
+default callers (which pass `true`).
+
+### Doc: `CopyOptions::batch_sectors` accuracy
+
+Doc comment said "Defaults to 32 sectors (64 KB)". Updated to describe
+the actual production path: callers should resolve via
+`detect_max_batch_sectors(device_path)` (kernel-reported sysfs value,
+typically 60 sectors / ~120 KB on the BU40N). The 32-sector internal
+fallback is only reached when `batch_sectors=None AND skip_forward=true`.
+
+## 0.13.11 (2026-04-25)
+
+### Fix: revert SgIoTransport timeout path to keep transport alive
+
+v0.13.10 changed `SgIoTransport::execute` to set `fd = -1` on a poll
+timeout (no reopen on the main thread, since that would serialize
+against the spawned close()). The intent was to escape the 60-s
+blocking reopen.
+
+The cost was too high: a single transient poll timeout permanently
+killed the transport. Live test on Dune 2 (post-replug):
+- Pass 1 ran for **45 ms** then returned with 0 GB good and 80 GB
+  pending.
+- The first SCSI READ timed out, fd went to -1, every subsequent
+  read returned `DeviceNotFound` instantly, Disc::copy raced through
+  the entire disc skip-forwarding in milliseconds.
+- Pass 2 inherited the dead Drive and was equally useless.
+
+Revert: spawn close + reopen on main thread (the v0.13.5/8
+behavior). Yes the main-thread open() may block up to ~60 s while
+the kernel completes the abandoned command — but the v0.13.9
+`Disc::copy` stall guard already caps catastrophic stalls at 120 s
+of `bytes_good` non-advance. Net: per-timeout cost is ~60 s, but
+Pass 1 cleanly bails out within 120 s of any wedge, and Pass 2 has
+a working Drive to retry NonTrimmed ranges with `recovery=true` +
+30 s timeouts.
+
+The integration test for the stall guard
+(`test_disc_copy_stall_detection_triggers_skip_forward`) continues
+to pass — the guard fires regardless of which transport-recovery
+strategy is in play.
+
+## 0.13.10 (2026-04-25)
+
+### Version sync — no functional changes
+
+Sync bump for the autorip-side fix in 0.13.10 (Pass 1 batch reporting).
+
+## 0.13.9 (2026-04-25)
+
+### Fix: Disc::copy silent stall + SgIoTransport reopen-after-timeout serialization
+
+Two correlated fixes for a hang observed live on the LG BU40N during a
+v0.13.8 rip of Dune: Part Two. At ~30 % progress through Pass 1
+(disc → ISO), `bytes_good` froze for 10+ minutes with `errs=0`,
+no error surfaced, drive not wedged.
+
+Root cause: `SgIoTransport::execute` (linux.rs) attempted to recover from
+a `poll()` timeout by spawning a background `close()` of the old fd and
+opening a fresh `/dev/sg*` fd on the main thread. On Linux, opening the
+SAME device while a prior fd is mid-close serializes via the kernel's
+per-device state lock — so the fresh `open()` blocks for as long as the
+close does (until the kernel completes the in-flight CDB). This undid
+the userspace 1.5 s timeout: each timed-out read added 60+ s to the
+next iteration. From `Disc::copy`'s perspective, reads kept returning
+Err slowly, the skip-forward path advanced `pos` but never `bytes_good`.
+
+Fixes:
+- `SgIoTransport::execute` no longer reopens on timeout. Spawns the
+  close, sets `self.fd = -1`, returns Err immediately. Subsequent
+  calls fail with `DeviceNotFound` (already gated at line 248).
+  Caller (Drive) is invalidated until reopened. Pass 2's
+  `Disc::patch` would need a fresh Drive; that's a v0.14 follow-up.
+- `Disc::copy` adds a stall guard. New `CopyOptions::stall_secs:
+  Option<u64>` (default 120 s). If `bytes_good` doesn't advance for
+  the threshold, breaks the outer loop with `complete: false,
+  bytes_pending > 0` so the caller's retry path picks up.
+
+Tests: new `test_disc_copy_stall_detection_triggers_skip_forward` in
+`tests/integration_progress_and_halt.rs` proves the guard fires within
+the configured threshold.
+
+Other:
+- Cosmetic: warning text "rip thread did not drain within 35s" updated
+  to 60s (matches the v0.13.8 timeout bump).
+
+## 0.13.8 (2026-04-25)
+
+### Version sync — no functional changes
+
+Sync bump for the ecosystem. 0.13.8 carries autorip-side fixes:
+post-stop "error" leak (halt-aware Err handling in Pass 1/2+),
+60 s drain timeout, and a structural spawn_rip_thread helper.
+
+## 0.13.7 (2026-04-25)
+
+### Version sync — no functional changes
+
+Sync bump for the ecosystem. All four freemkv crates (libfreemkv,
+freemkv CLI, bdemu, autorip) always share a version number; 0.13.7
+carries an autorip-side fix (HTTP-spawned rip/scan threads now
+register for stop-drain).
+
 ## 0.13.6 (2026-04-25)

 ### Inline retry/reset stripped from `Drive::read`; `BytesRead` now emitted
@@ -1,6 +1,6 @@
 [package]
 name = "libfreemkv"
-version = "0.13.6"
+version = "0.13.41"
 edition = "2024"
 rust-version = "1.86"
 license = "AGPL-3.0-only"
@@ -24,6 +24,10 @@ rand = "0.8"
 cmac = "0.7"
 zip = { version = "2", default-features = false, features = ["deflate"] }
 base64 = "0.22.1"
+# Trace-level instrumentation for Disc::copy + SgIoTransport::execute. Permitted
+# under project docs ("Acceptable strings: debug/trace logging"). Consumers (autorip)
+# wire a tracing subscriber and pipe events into the JSONL debug log.
+tracing = "0.1"

 [target.'cfg(target_os = "linux")'.dependencies]
 libc = "0.2"
@@ -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.
@@ -8,13 +8,12 @@ fn main() {
    let device = std::env::args()
        .skip(1)
        .find(|a| !a.starts_with('-'))
-        .unwrap_or_else(|| {
-            let drives = libfreemkv::find_drives();
-            if drives.is_empty() {
+        .unwrap_or_else(|| match libfreemkv::find_drive() {
+            Some(d) => d.device_path().to_string(),
+            None => {
                eprintln!("No drives found");
                std::process::exit(1);
            }
-            drives[0].device_path().to_string()
        });

    let mut drive = Drive::open(Path::new(&device)).unwrap_or_else(|e| {
@@ -12,6 +12,7 @@ Technical documentation for [libfreemkv](https://github.com/freemkv/libfreemkv),
 |----------|---------------|
 | [Architecture](architecture.md) | Module map, design principles, error codes, platform support |
 | [Drive Access](drive-access.md) | Drive, SCSI transport, profiles, unlock, why raw mode is needed |
+| [Rip Recovery](rip-recovery.md) | Three-layer recovery model: Disc::patch, single-shot Drive::read, DiscStream batch halving |
 | [AACS Encryption](aacs.md) | Key resolution (4 paths), content decryption, bus encryption, SCSI handshake |
 | [UDF Filesystem](udf.md) | UDF 2.50 with metadata partitions, pointer chain, how files are read from disc |
 | [MPLS Playlists](mpls.md) | Playlist format, play items, STN stream table, coding types |
@@ -126,15 +126,45 @@ pub struct Event {
 }

 pub enum EventKind {
+    // Init / scan
+    DriveOpened { device: String },
+    DriveReady,
+    InitComplete { success: bool },
+    ProbeComplete { success: bool },
+    ScanComplete { titles: usize },
+
+    // Read pipeline
    BytesRead { bytes: u64, total: u64 },
    ReadError { sector: u64, error: Error },
-    Retry { attempt: u32 },
    SpeedChange { speed_kbs: u16 },
    ExtentStart { index: usize, start_sector: u64, sector_count: u64 },
+    SectorSkipped { sector: u64 },
+    BatchSizeChanged { new_size: u16, reason: BatchSizeReason },
    Complete { bytes: u64, errors: u32 },
+
+    // Kept for forward-compat; not emitted in 0.13.6+
+    Retry { attempt: u32 },
+    SectorRecovered { sector: u64 },
 }
 ```

+Emission notes:
+
+- `BytesRead { bytes, total }` is emitted from `DiscStream::fill_extents`
+  after each successful sector read. `bytes` is the cumulative running
+  total; `total` is the precomputed extent sum (0 if unknown).
+- `SpeedChange` is emitted from the public `Drive::set_speed` API path.
+  It is no longer emitted from a recovery hot loop (recovery loop removed
+  in 0.13.6).
+- `BatchSizeChanged` fires from the `DiscStream` adaptive sizer on shrink
+  (read failed at a larger size) and on probe-up (clean-read streak hit
+  the threshold). Consumers use it to display a "recovering" state
+  distinct from "ripping normally".
+- `Retry` and `SectorRecovered` are NOT emitted in 0.13.6+. They were
+  tied to the inline `Drive::read` recovery phases that were removed; the
+  variants are kept for forward compatibility so consumers' match arms
+  don't need conditional compilation.
+
 Events report what happened. App decides what to do. GUI shows a dialog. CLI
 prints a line. Server logs to file.

@@ -145,8 +175,8 @@ libfreemkv/src/
 ├── lib.rs              Public exports
 ├── error.rs            Error codes (no English)
 ├── event.rs            Event types for callbacks
-├── drive/              Drive (open, init, read with recovery)
-│   ├── mod.rs          Drive struct, init, read, reset, eject
+├── drive/              Drive (open, init, single-shot read)
+│   ├── mod.rs          Drive struct, init, read (single-shot), reset, eject
 │   ├── capture.rs      Drive profile capture for contribution
 │   ├── linux.rs        Linux drive discovery
 │   ├── macos.rs        macOS drive discovery
@@ -41,7 +41,7 @@ AACS keys are derived internally, and all SCSI communication is handled in-proce
 libfreemkv (lib.rs)
 │
 ├── Drive Access
-│   ├── drive         Drive — open, identify, init, unlock, read (with recovery)
+│   ├── drive         Drive — open, identify, init, unlock, single-shot read
 │   ├── scsi          ScsiTransport trait + platform backends (sg async, IOKit, SPTI)
 │   ├── platform/     Platform trait — per-chipset command handlers
 │   │   └── mt1959    MediaTek MT1959 driver (LG, ASUS, HP)
@@ -93,10 +93,17 @@ Drive::open(Path::new("/dev/sg4"))
 After open:
 - `init()` -- unlock + firmware upload + speed calibration
 - `probe_disc()` -- probe disc surface for optimal speeds
- `read(lba, count, buf)` -- single read method with built-in error recovery
+- `read(lba, count, buf, recovery)` -- single-shot read; `recovery` only selects the per-CDB timeout (1.5 s vs. 30 s)
 - `wait_ready()` -- wait for disc insertion
 - `eject()` -- eject tray

+Recovery is layered above `Drive::read`, not inside it. Layer 1
+(`Disc::patch`) handles bad-range retry by replaying the ddrescue mapfile.
+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
+the stop-wedge postmortem (2026-04-25).
+
 ---

 ## Disc Scanning Flow
@@ -77,7 +77,9 @@ Insert disc
 10. Stream content (mux/disc.rs → DiscStream)
     │  Read sectors → decrypt → TS demux → PES frames
     │  Or: read sectors → decrypt → raw bytes (for ISO output)
-     │  Drive::read() handles error recovery (min speed → reset → retry)
+     │  Drive::read() is single-shot. DiscStream::fill_extents adapts the
+     │  batch size on failure (halve / probe-up). Bad-range retry is layer
+     │  1 above this — Disc::patch re-runs against the mapfile.
     │
     ▼
  PES frames → output stream (MKV, M2TS, network, etc.)
@@ -110,7 +112,7 @@ output.finish()?;

 | Module | Doc | Purpose |
 |--------|-----|---------|
-| drive/ | [drive-access.md](drive-access.md) | Open, identify, init, unlock, read (with recovery) |
+| drive/ | [drive-access.md](drive-access.md) | Open, identify, init, unlock, single-shot read |
 | scsi/ | [drive-access.md](drive-access.md) | Platform SCSI transport (Linux, macOS, Windows) |
 | udf.rs | [udf.md](udf.md) | UDF 2.50 filesystem |
 | mpls.rs | [mpls.md](mpls.md) | MPLS playlists + STN streams |
@@ -26,8 +26,8 @@ platform driver. The drive is ready for `wait_ready()` and `init()`.
 | `wait_ready()` | Wait for disc insertion (30s timeout, TUR polling) |
 | `init()` | Firmware upload + unlock + speed calibration |
 | `probe_disc()` | Probe disc surface for optimal speeds |
-| `read(lba, count, buf)` | Read sectors with built-in error recovery |
-| `reset()` | Close/reopen device, TUR, escalate if needed |
+| `read(lba, count, buf, recovery)` | Read sectors. Single-shot — no inline retries or reset. |
+| `reset()` | Eject-cycle escape hatch. Caller-invoked only; not on the read path. |
 | `lock_tray()` | Prevent tray ejection during rip |
 | `unlock_tray()` | Allow tray ejection (also runs on Drop) |
 | `eject()` | Eject disc tray |
@@ -44,22 +44,33 @@ platform driver. The drive is ready for `wait_ready()` and `init()`.
 3. Speed calibration after unlock
 4. Max 3 attempts before giving up

-### read() with Recovery
+### read() — single-shot

-`Drive::read(lba, count, buf, recovery)` is the single read method. The
-`recovery` parameter controls whether to attempt multi-phase recovery on
-failure or return immediately (used by DiscStream's binary search for
-single-sector probes).
+`Drive::read(lba, count, buf, recovery)` is the single read method. It issues
+exactly one READ(10) CDB and returns the result. The `recovery` parameter only
+selects the per-CDB timeout:

-On error with `recovery = true`:
+| `recovery` | Timeout  | Used by                                  |
+|------------|----------|------------------------------------------|
+| `false`    | 1.5 s    | `Disc::copy` fast skip-forward sweep, `DiscStream::fill_extents` |
+| `true`     | 30 s     | `Disc::patch` multi-pass over the mapfile |

-1. **Phase 1 — gentle retry (5 attempts):** set min speed, sleep 30s, retry.
-   Each retry has a hard wall-clock timeout via async SG_IO.
-2. **Phase 2 — fresh start:** close transport, reset device, reopen, reinit.
-3. **Phase 3 — gentle retry on fresh connection (5 attempts).**
-4. If all fail: return `Err(DiscRead)`. DiscStream handles it (binary search,
-   skip, zero-fill).
-5. Stay at min speed for 500 MB after any recovery (recovery window).
+On any SCSI failure or timeout, `read` returns `Err(DiscRead)` immediately.
+There are no inline retries, no SCSI reset, no Phase 1/2/3 escalation.
+
+Recovery is layered above `Drive::read`:
+
+- **Layer 1 — `Disc::patch`** loops over the ddrescue mapfile and re-issues
+  `read(.., recovery=true)` against each non-`+` range.
+- **Layer 3 — `DiscStream::fill_extents`** halves the request size on
+  failure, retries at the same LBA, and probes back up on a clean-read
+  streak.
+
+Inline recovery (5× gentle retry → close + reset + reopen → 5× more) was
+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,6 +110,17 @@ cannot block us. Opens with `O_RDWR | O_NONBLOCK`.
 On non-zero SCSI status, the transport parses sense key from the sense buffer
 and returns `Error::ScsiError`.

+`SgIoTransport::reset` (Linux) does pure userspace state cleanup: an open +
+close pair to make the kernel cancel any SG_IO commands queued against a
+previous fd, a 2 s sleep to let the kernel finish that cancellation, then a
+fresh fd to send ALLOW MEDIUM REMOVAL to clear any stale tray lock. It does
+NOT issue `SG_SCSI_RESET` or escalate via STOP+START UNIT. Both 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. The macOS reset (which
+had been a no-op) was removed entirely in 0.13.6, and the top-level
+`scsi::reset()` / `reset_with_timeout()` / `reset_blocking()` wrappers were
+removed at the same time (no callers).
+
 ### CDB Builders

 The `scsi` module provides platform-agnostic CDB constructors:
@@ -1,12 +1,27 @@
-# Rip recovery — multi-pass architecture
+# Rip recovery — three-layer architecture

-`libfreemkv` supports a two-stage rip model for damaged or protection-bearing
-discs: a fast forward sweep that tolerates read failures, followed by targeted
+`libfreemkv` supports a multi-stage rip model for damaged or protection-bearing
+discs: a fast forward sweep that tolerates read failures, in-loop request-size
+adaptation that survives transient drive trouble without bailing, and targeted
 retry passes against a persistent bad-range map. The stream pipeline
 (`DiscStream` + `input`/`output`) operates against the resulting ISO image, so
 the mux stage never touches the drive.

-Three primitives compose the flow:
+Recovery is layered cleanly. Each layer has one responsibility and does not
+reach into the others.
+
+| Layer | Where it lives | What it does |
+|-------|---------------|--------------|
+| 1 — Bad-range retry | `Disc::patch` (multi-pass over the mapfile) | Re-reads non-`+` ranges with the long timeout. Idempotent; call N times. |
+| 2 — Single-shot primitive | `Drive::read` in `src/drive/mod.rs` | One CDB, one timeout, one result. No inline retries, no SCSI reset. |
+| 3 — In-loop request adaptation | `DiscStream::fill_extents` adaptive batch sizer | Halves the batch on failure, retries at the same LBA, walks back up on a clean-read streak. |
+
+The caller orchestrates layer 1. Autorip's `rip_disc` loops `copy` then
+N × `patch` per the `MAX_RETRIES` config, then hands the ISO off to the
+existing mux pipeline. Layer 3 runs inside any consumer of `DiscStream`
+(direct PES pipeline, ISO playback, etc.) without caller involvement.
+
+Three primitives compose the disc-side flow:

 | Primitive                 | What it does                                                          |
 |---------------------------|-----------------------------------------------------------------------|
@@ -14,9 +29,6 @@ Three primitives compose the flow:
 | `Disc::patch`             | Re-reads bad ranges from the drive. Idempotent; call N times.         |
 | `DiscStream` (ISO source) | Reads sectors from the ISO, feeds decrypt → demux → codec → mux.      |

-The caller orchestrates. Autorip's `rip_disc` loops `copy` then N × `patch` per
-the `MAX_RETRIES` config, then hands the ISO off to the existing mux pipeline.
-
 ## Data model

 ### Mapfile
@@ -26,7 +38,7 @@ plain text, greppable, tool-interoperable. Flushed to disk on every `record()`
 so a crashed rip loses at most one block.

 ```
-# Rescue Logfile. Created by libfreemkv v0.11.22
+# Rescue Logfile. Created by libfreemkv v0.13.6
 # Current pos / status / pass / pass_time
 0x000000000  ?  1  0
 #      pos        size  status
@@ -50,8 +62,8 @@ Position and size are hex byte offsets into the ISO.

 ### `CopyOptions` and `PatchOptions`

-Defaults preserve pre-`0.11.21` behavior — full drive recovery on every read,
-abort on the first unreadable sector. Opt in to the recovery-friendly path:
+Defaults preserve pre-`0.11.21` behavior — abort on the first unreadable
+sector. Opt in to the recovery-friendly path:

 ```rust
 CopyOptions {
@@ -65,9 +77,10 @@ CopyOptions {

 ## Algorithm

-### Pass 1 — fast sweep
+### Pass 1 — fast sweep (`Disc::copy`)

-1. Read 64 KB (32 sectors, one BD ECC block) at the current LBA.
+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.
@@ -80,12 +93,13 @@ CopyOptions {
 Pass 1 completes when every byte has terminal status (`+`, `-`, or the caller
 bails via the halt flag).

-### Pass 2+ — patch
+### Pass 2+ — patch (`Disc::patch`)

 `Disc::patch` reads the mapfile and iterates every non-`+` range. For each:

-1. Issue a drive read with full recovery enabled (SCSI-level retries,
-   ECC recovery, the lot).
+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 `-`.
@@ -95,21 +109,61 @@ 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).

+### In-stream — adaptive batch halving (`DiscStream::fill_extents`)
+
+When a consumer reads a `DiscStream` directly (no ISO intermediate),
+`fill_extents` runs an adaptive sizer in front of `Drive::read`:
+
+1. Try the current preferred batch size (e.g. 32 sectors, one BD ECC block).
+2. On failure: halve the batch and retry at the same LBA. Emit
+   `EventKind::BatchSizeChanged { reason: Shrunk }`.
+3. On a clean-read streak: probe back up toward the preferred size. Emit
+   `EventKind::BatchSizeChanged { reason: Probed }`.
+4. If a single-sector read fails: skip (zero-fill, emit
+   `EventKind::SectorSkipped`) when `skip_errors` is set, otherwise return
+   `Err(DiscRead)`.
+
+This is layer 3. It exists so a transient single-sector glitch in a 32-sector
+batch can be isolated and read individually without the caller needing to
+implement retry logic.
+
 ## Design choices

+**`Drive::read` is single-shot.** No inline retry phases, no SCSI reset,
+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 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
+handles ranges, layer 3 handles request size, neither touches the
+wedge-prone reset path.
+
 **No `MODE SELECT` to disable drive retries.** Research showed neither ddrescue
 nor MakeMKV does this. Drive firmware has access to raw analog signal, laser
 power control, and drive-specific ECC tuning that userspace can't replicate —
 disabling it throws away recovery headroom on marginal sectors. We fail fast
-via short SG_IO timeouts instead, and we avoid per-sector probing on first
-contact by using large blocks + skip-forward.
+via short SG_IO timeouts in pass 1 and let the firmware work the long timeout
+in pass 2 / patch.
+
+**No SCSI reset from any retry path.** `SgIoTransport::reset` (Linux) is
+trimmed to a kernel SG_IO state flush plus ALLOW MEDIUM REMOVAL — the
+`SG_SCSI_RESET` ioctl and STOP/START UNIT escalation were removed in 0.13.6.
+The macOS reset (which had been a no-op) was removed entirely. The top-level
+`scsi::reset()` / `reset_with_timeout()` / `reset_blocking()` wrappers were
+also removed (no callers). The remaining `Drive::reset()` is only invoked
+explicitly by callers that need an eject-cycle escape hatch — it is never
+reached from a read path.

 **ISO intermediate, even for single-pass.** Pass 1 always writes an ISO. The
 mux stage reads the ISO via `IsoSectorReader`. For single-pass (no retries),
 this adds ~2-3 min (local disk mux) but gains resumability across crashes,
 re-muxability without re-ripping, and a persistent forensic artifact. Callers
 who need pure speed can bypass and use `DiscStream::new(Box::new(drive), …)`
-directly — the lib doesn't forbid it.
+directly — the lib doesn't forbid it, and layer 3 (adaptive batch halving)
+still applies there.

 **Mapfile in ddrescue format.** Plain text so users can `less` it, `diff` it,
 or feed it to ddrescue's own tooling. Crash-safe (flush-per-record). Entries
@@ -117,11 +171,11 @@ coalesce on adjacent same-status ranges so files stay small.

 **Patches target `-`, `*`, `/`, and `?` alike.** The status state machine is
 ddrescue's but `patch` collapses the distinction — it just tries every
-non-finished range with full recovery. Future work can specialize (trim vs.
+non-finished range with the long timeout. Future work can specialize (trim vs.
 scrape vs. retry with direction reversal) if there's measured benefit.

 ## References

 - [ddrescue manual, Algorithm chapter](https://www.gnu.org/software/ddrescue/manual/ddrescue_manual.html)
 - [ddrescue optical media notes](https://www.electric-spoon.com/doc/gddrescue/html/Optical-media.html)
- Source: [`src/disc/mapfile.rs`](../src/disc/mapfile.rs), [`src/disc/mod.rs`](../src/disc/mod.rs) (`Disc::copy`, `Disc::patch`)
+- Source: [`src/disc/mapfile.rs`](../src/disc/mapfile.rs), [`src/disc/mod.rs`](../src/disc/mod.rs) (`Disc::copy`, `Disc::patch`), [`src/drive/mod.rs`](../src/drive/mod.rs) (`Drive::read`), [`src/mux/disc.rs`](../src/mux/disc.rs) (`DiscStream::fill_extents`).
@@ -69,12 +69,28 @@ pub struct MapEntry {
 }

 /// Summary statistics over all entries.
+///
+/// `bytes_pending` aggregates `NonTried + NonTrimmed + NonScraped` for
+/// back-compat. `bytes_nontried` and `bytes_retryable` (= NonTrimmed +
+/// NonScraped) split that aggregate so UIs can distinguish *unread*
+/// territory (still ahead of Pass 1's read head) from *needs-retry*
+/// territory (Pass 1 already encountered, queued for Pass 2-N).
 #[derive(Debug, Clone, Copy, Default)]
 pub struct MapStats {
    pub bytes_total: u64,
    pub bytes_good: u64,
    pub bytes_unreadable: u64,
    pub bytes_pending: u64,
+    /// Sectors Pass 1 hasn't reached yet (`NonTried`). Subset of
+    /// `bytes_pending`.
+    pub bytes_nontried: u64,
+    /// Sectors flagged for Pass 2-N retry — `NonTrimmed` (multi-sector
+    /// read failed; needs split) + `NonScraped` (small-block read
+    /// partially recovered; remainder still pending). Subset of
+    /// `bytes_pending`. This is the right signal for a "MAYBE / will
+    /// retry" UI bucket; `bytes_pending` over-counts because it folds
+    /// in `bytes_nontried`.
+    pub bytes_retryable: u64,
 }

 /// Write-through mapfile. Every `record()` persists to disk immediately
@@ -275,8 +291,13 @@ impl Mapfile {
            match e.status {
                SectorStatus::Finished => s.bytes_good += e.size,
                SectorStatus::Unreadable => s.bytes_unreadable += e.size,
-                SectorStatus::NonTried | SectorStatus::NonTrimmed | SectorStatus::NonScraped => {
-                    s.bytes_pending += e.size
+                SectorStatus::NonTried => {
+                    s.bytes_pending += e.size;
+                    s.bytes_nontried += e.size;
+                }
+                SectorStatus::NonTrimmed | SectorStatus::NonScraped => {
+                    s.bytes_pending += e.size;
+                    s.bytes_retryable += e.size;
                }
            }
        }
@@ -13,7 +13,7 @@ mod dvd;
 mod encrypt;
 pub mod mapfile;

-use crate::drive::Drive;
+use crate::drive::{Drive, extract_scsi_context};
 use crate::error::{Error, Result};
 use crate::sector::SectorReader;
 use crate::udf;
@@ -1217,14 +1217,14 @@ impl Disc {
    /// `path + ".mapfile"` — flushed every block for crash-safe resume.
    ///
    /// # Options
-    /// - **default** (all false): behavior matches pre-v0.11.21 — uses full
-    ///   drive recovery (may take minutes per bad sector), aborts on error.
-    ///   Mapfile is produced as a side-effect.
-    /// - **skip_on_error**: zero-fill bad blocks in the ISO, mark them in the
-    ///   mapfile, and continue. Uses fast reads (no drive-level recovery loop).
-    /// - **skip_forward** (implies skip_on_error): on block failure, also skip
-    ///   forward by an exponentially-growing amount, marking the jumped region
-    ///   as `non-trimmed` for later trimming/scraping by `Disc::patch`.
+    /// - **default** (skip_on_error=false): uses full drive recovery (may take
+    ///   minutes per bad sector), aborts on error. Mapfile is produced as a
+    ///   side-effect.
+    /// - **skip_on_error**: zero-fill bad blocks in the ISO, mark them NonTrimmed
+    ///   in the mapfile, and continue. Reads in `batch`-sector chunks (32 sectors
+    ///   = 1 BD ECC block by default). Failed blocks are marked NonTrimmed for
+    ///   recovery by `Disc::patch`. No single-sector reads in this pass —
+    ///   Pass 1 is pure ECC-block sweep.
    /// - **resume**: if the mapfile exists, resume from its state — only
    ///   `non-tried` ranges are read. Without `resume`, a fresh mapfile is
    ///   written and the ISO recreated from scratch.
@@ -1274,39 +1274,56 @@ impl Disc {
        let mut file = file;
        let batch: u16 = match opts.batch_sectors {
            Some(b) => b,
-            None if opts.skip_forward => 32, // 64 KB = BD ECC block size
+            None if opts.skip_on_error => 32,
            None => DEFAULT_BATCH_SECTORS,
        };

-        // Skip-forward state.
-        let skip_init = 256 * 1024u64; // 256 KB
-        let skip_max = (total_bytes / 100).max(skip_init); // cap at 1% of disc
-        let mut skip_size = skip_init;
-
        let mut buf = vec![0u8; batch as usize * 2048];
        let mut bytes_done = 0u64;
        let mut halt_requested = false;
+        let copy_t0 = std::time::Instant::now();
+        let mut iter_count: u64 = 0;
+        let mut read_ok_count: u64 = 0;
+        let mut read_err_count: u64 = 0;
+        let mut last_log_iter: u64 = 0;
+        tracing::trace!(
+            target: "freemkv::disc",
+            phase = "copy_start",
+            total_bytes,
+            batch,
+            skip_on_error = opts.skip_on_error,
+            "Disc::copy entered"
+        );

-        // Iterate over not-yet-finished regions from the mapfile. We re-read the
-        // mapfile after each block because record() mutates the region list.
        'outer: loop {
            let regions_to_do = map.ranges_with(&[
                mapfile::SectorStatus::NonTried,
                mapfile::SectorStatus::NonTrimmed,
                mapfile::SectorStatus::NonScraped,
            ]);
+            tracing::trace!(
+                target: "freemkv::disc",
+                phase = "outer_loop",
+                regions_remaining = regions_to_do.len(),
+                "Disc::copy outer iter"
+            );
            if regions_to_do.is_empty() {
                break;
            }
-            // Only process the first NonTried range per outer pass; skip_forward
-            // may turn others into NonTrimmed which we DO NOT re-enter here —
-            // Disc::patch handles those.
            let Some((region_pos, region_size)) = map.next_with(0, mapfile::SectorStatus::NonTried)
            else {
                break;
            };
            let region_end = region_pos + region_size;
            let mut pos = region_pos;
+            tracing::trace!(
+                target: "freemkv::disc",
+                phase = "region_enter",
+                region_pos,
+                region_size,
+                region_end,
+                "entering NonTried region"
+            );

            while pos < region_end {
                if let Some(ref h) = opts.halt {
@@ -1315,64 +1332,148 @@ impl Disc {
                        break 'outer;
                    }
                }
+
                let block_bytes = (region_end - pos).min(batch as u64 * 2048);
-                let lba = (pos / 2048) as u32;
-                let count = (block_bytes / 2048) as u16;
-                let bytes = count as usize * 2048;
+                let block_lba = (pos / 2048) as u32;
+                let block_count = (block_bytes / 2048) as u16;
+                let recovery = !opts.skip_on_error;

-                let recovery = !opts.skip_on_error; // fast reads when skipping
-                let read_ok = reader
-                    .read_sectors(lba, count, &mut buf[..bytes], recovery)
-                    .is_ok();
+                if read_ok_count + read_err_count < 3 {
+                    tracing::info!(
+                        target: "freemkv::disc",
+                        block_lba,
+                        block_count,
+                        block_bytes,
+                        recovery,
+                        skip_on_error = opts.skip_on_error,
+                        batch,
+                        total_bytes,
+                        "Disc::copy first reads"
+                    );
+                }

-                if read_ok {
+                let read_result = reader.read_sectors(
+                    block_lba,
+                    block_count,
+                    &mut buf[..block_bytes as usize],
+                    recovery,
+                );
+
+                if read_result.is_ok() {
+                    read_ok_count += 1;
                    if opts.decrypt {
-                        crate::decrypt::decrypt_sectors(&mut buf[..bytes], &keys, 0)?;
+                        crate::decrypt::decrypt_sectors(
+                            &mut buf[..block_bytes as usize],
+                            &keys,
+                            0,
+                        )?;
                    }
                    file.seek(SeekFrom::Start(pos))
                        .map_err(|e| Error::IoError { source: e })?;
-                    file.write_all(&buf[..bytes])
+                    file.write_all(&buf[..block_bytes as usize])
                        .map_err(|e| Error::IoError { source: e })?;
                    map.record(pos, block_bytes, mapfile::SectorStatus::Finished)
                        .map_err(|e| Error::IoError { source: e })?;
                    bytes_done = bytes_done.saturating_add(block_bytes);
-                    skip_size = skip_init; // reset after success
-                    pos += block_bytes;
-                } else if opts.skip_on_error {
-                    // Zero-fill this block, mark non-trimmed for later patch trim.
-                    buf[..bytes].fill(0);
+                } else if !opts.skip_on_error {
+                    let (status, sense) = read_result
+                        .as_ref()
+                        .err()
+                        .map(extract_scsi_context)
+                        .unwrap_or((0, None));
+                    return Err(Error::DiscRead {
+                        sector: block_lba as u64,
+                        status: Some(status),
+                        sense,
+                    });
+                } else {
+                    let err = read_result.err().unwrap();
+                    read_err_count += 1;
+
+                    if err.is_scsi_transport_failure() {
+                        tracing::warn!(
+                            target: "freemkv::disc",
+                            phase = "transport_failure",
+                            lba = block_lba,
+                            error = %err,
+                            "transport failure (bridge crash); aborting copy"
+                        );
+                        return Err(err);
+                    }
+
+                    if !err.is_marginal_read()
+                        && err.scsi_sense().is_none_or(|s| !s.is_medium_error())
+                    {
+                        return Err(err);
+                    }
+
+                    // ECC block failed — zero-fill, mark NonTrimmed, advance.
+                    tracing::warn!(
+                        target: "freemkv::disc",
+                        phase = "skip_ecc_block",
+                        lba = block_lba,
+                        sectors = block_count,
+                        error = %err,
+                        "ECC block failed; marking NonTrimmed"
+                    );
+                    let zero = vec![0u8; block_bytes as usize];
                    file.seek(SeekFrom::Start(pos))
                        .map_err(|e| Error::IoError { source: e })?;
-                    file.write_all(&buf[..bytes])
+                    file.write_all(&zero)
                        .map_err(|e| Error::IoError { source: e })?;
                    map.record(pos, block_bytes, mapfile::SectorStatus::NonTrimmed)
                        .map_err(|e| Error::IoError { source: e })?;
-                    pos += block_bytes;
-
-                    if opts.skip_forward && pos < region_end {
-                        // Skip ahead; mark skipped bytes as non-trimmed too.
-                        let jump = skip_size.min(region_end - pos);
-                        if jump > 0 {
-                            map.record(pos, jump, mapfile::SectorStatus::NonTrimmed)
-                                .map_err(|e| Error::IoError { source: e })?;
-                            pos += jump;
-                        }
-                        skip_size = (skip_size * 2).min(skip_max);
-                    }
-                } else {
-                    // Current behavior (pre-0.11.21): abort on first bad sector.
-                    return Err(Error::DiscRead { sector: lba as u64 });
+                    bytes_done = bytes_done.saturating_add(block_bytes);
                }

-                if let Some(cb) = opts.on_progress {
+                pos += block_bytes;
+                iter_count += 1;
+
+                if iter_count - last_log_iter >= 100 {
+                    last_log_iter = iter_count;
                    let stats = map.stats();
-                    cb(stats.bytes_good, total_bytes);
+                    tracing::trace!(
+                        target: "freemkv::disc",
+                        phase = "iter_progress",
+                        iter_count,
+                        read_ok_count,
+                        read_err_count,
+                        pos,
+                        region_end,
+                        bytes_good = stats.bytes_good,
+                        bytes_pending = stats.bytes_pending,
+                        copy_elapsed_ms = copy_t0.elapsed().as_millis() as u64,
+                        "Disc::copy inner iter"
+                    );
+                }
+
+                if let Some(reporter) = opts.progress {
+                    let stats = map.stats();
+                    reporter.report(&crate::progress::PassProgress {
+                        kind: crate::progress::PassKind::Sweep,
+                        work_done: pos,
+                        work_total: total_bytes,
+                        bytes_good_total: stats.bytes_good,
+                        bytes_total_disc: total_bytes,
+                    });
                }
            }
        }

        file.sync_all().map_err(|e| Error::IoError { source: e })?;
        let stats = map.stats();
+        tracing::trace!(
+            target: "freemkv::disc",
+            phase = "copy_done",
+            iter_count,
+            read_ok_count,
+            read_err_count,
+            bytes_good = stats.bytes_good,
+            bytes_pending = stats.bytes_pending,
+            halted = halt_requested,
+            copy_elapsed_ms = copy_t0.elapsed().as_millis() as u64,
+            "Disc::copy returning"
+        );
        Ok(CopyResult {
            bytes_total: total_bytes,
            bytes_good: stats.bytes_good,
@@ -1392,17 +1493,19 @@ pub struct CopyOptions<'a> {
    /// Resume from existing mapfile + ISO if present. Without this, any
    /// existing mapfile is wiped and the ISO recreated.
    pub resume: bool,
-    /// Override the default block size. Defaults to 32 sectors (64 KB) in
-    /// `skip_forward` mode, `DEFAULT_BATCH_SECTORS` otherwise.
+    /// Override the default block size in sectors. Callers should resolve
+    /// this with `detect_max_batch_sectors(device_path)` for live drives.
+    /// When `None`, falls back to 32 sectors (64 KB BD ECC block) in
+    /// `skip_on_error` mode or `DEFAULT_BATCH_SECTORS=60` otherwise.
    pub batch_sectors: Option<u16>,
-    /// Zero-fill bad blocks in the ISO, mark them in the mapfile, continue.
-    /// Uses fast reads (no drive-level recovery loop).
+    /// Zero-fill bad blocks in the ISO, mark them NonTrimmed in the mapfile,
+    /// and continue. Failed ECC blocks are left for `Disc::patch` to recover.
    pub skip_on_error: bool,
-    /// ddrescue-style exponential skip-forward on block failure. Implies
-    /// `skip_on_error`. The skipped region is marked `non-trimmed` for later
-    /// trimming/scraping by `Disc::patch`.
-    pub skip_forward: bool,
-    pub on_progress: Option<&'a dyn Fn(u64, u64)>,
+    /// Per-iteration progress reporter. v0.13.16 architecture: the library
+    /// emits a single `PassProgress` shape via the `Progress` trait;
+    /// consumers compute their own derived percentages / ETAs from it. No
+    /// more positional `(bytes_good, pos, total)` callbacks.
+    pub progress: Option<&'a dyn crate::progress::Progress>,
    pub halt: Option<std::sync::Arc<std::sync::atomic::AtomicBool>>,
 }

@@ -1436,11 +1539,23 @@ pub struct PatchOptions<'a> {
    /// Use full drive-level recovery on each read (slow but thorough). Defaults
    /// to true — patch is the pass where we *want* the drive to try hard.
    pub full_recovery: bool,
-    pub on_progress: Option<&'a dyn Fn(u64, u64)>,
+    /// Walk bad ranges in reverse order, and within each range walk sectors
+    /// from high to low LBA. Useful for drives that wedge after a forward
+    /// read of a bad sector — approaching the post-bad-zone from end-of-disc
+    /// reads good sectors before the drive sees a bad one.
+    pub reverse: bool,
+    /// Bail out early if this many consecutive read failures occur with zero
+    /// successful reads in the same pass — i.e. the drive is wedged on the
+    /// bad zone and won't recover during this attempt. `0` disables the
+    /// guard (run to completion or halt).
+    pub wedged_threshold: u64,
+    /// Per-iteration progress reporter. See `CopyOptions::progress`.
+    pub progress: Option<&'a dyn crate::progress::Progress>,
    pub halt: Option<std::sync::Arc<std::sync::atomic::AtomicBool>>,
 }

-/// Result of `Disc::patch` — how many bad bytes were recovered.
+/// Result of `Disc::patch` — how many bad bytes were recovered, plus
+/// per-block counters for diagnosing why a pass made or didn't make progress.
 #[derive(Debug, Clone, Copy)]
 pub struct PatchResult {
    pub bytes_total: u64,
@@ -1449,6 +1564,16 @@ pub struct PatchResult {
    pub bytes_pending: u64,
    pub bytes_recovered_this_pass: u64,
    pub halted: bool,
+    /// Total inner-loop iterations this pass (one per block attempted).
+    pub blocks_attempted: u64,
+    /// Reads that returned Ok and were promoted to `Finished`.
+    pub blocks_read_ok: u64,
+    /// Reads that returned Err and were marked `Unreadable`.
+    pub blocks_read_failed: u64,
+    /// Pass exited early because `wedged_threshold` consecutive failures
+    /// occurred with zero successful reads — drive appears wedged on the
+    /// bad zone for this pass.
+    pub wedged_exit: bool,
 }

 impl Disc {
@@ -1482,43 +1607,107 @@ impl Disc {
            .map_err(|e| Error::IoError { source: e })?;

        let block_sectors = opts.block_sectors.unwrap_or(1);
-        // Patch always reads with full drive recovery — this is the pass where
-        // we want the drive's ECC retry machinery. Consumers who want fast-fail
-        // use Disc::copy with skip_on_error instead.
-        let _ = opts.full_recovery;
+        let recovery = opts.full_recovery;

        let bytes_good_before = map.stats().bytes_good;
        let mut halted = false;
+        let mut wedged_exit = false;
+        let mut blocks_attempted: u64 = 0;
+        let mut blocks_read_ok: u64 = 0;
+        let mut blocks_read_failed: u64 = 0;
+        let mut consecutive_failures: u64 = 0;
+        let mut unreadable_count: u64 = 0;
        let mut buf = vec![0u8; block_sectors as usize * 2048];

        // Collect bad ranges up front. Iterating while mutating is fragile;
        // each recorded change is persisted, so resume works even if we crash
        // mid-loop.
-        let bad_ranges = map.ranges_with(&[
+        let mut bad_ranges = map.ranges_with(&[
            mapfile::SectorStatus::NonTried,
            mapfile::SectorStatus::NonTrimmed,
            mapfile::SectorStatus::NonScraped,
            mapfile::SectorStatus::Unreadable,
        ]);
+        // Reverse mode: walk ranges from highest LBA to lowest.
+        if opts.reverse {
+            bad_ranges.reverse();
+        }
+        // work_total = sum of all bad-range bytes. on_progress's third arg
+        // is this value; the second arg (work_done) is incremented per block
+        // attempted. UI consumers (autorip) compute pass_progress_pct =
+        // work_done / work_total — true 0..100% per pass per RIP_DESIGN.md §16.
+        let work_total: u64 = bad_ranges.iter().map(|(_, sz)| *sz).sum();
+        let mut work_done: u64 = 0;
+        tracing::trace!(
+            target: "freemkv::disc",
+            phase = "patch_start",
+            block_sectors,
+            recovery,
+            reverse = opts.reverse,
+            wedged_threshold = opts.wedged_threshold,
+            num_ranges = bad_ranges.len(),
+            work_total,
+            "Disc::patch entered"
+        );

        'outer: for (range_pos, range_size) in bad_ranges {
-            let mut pos = range_pos;
            let end = range_pos + range_size;
-            while pos < end {
+            // In reverse mode, walk this range from end - block_bytes back to range_pos.
+            // Each iteration emits the block ending at `block_end` (so reads land on
+            // increasing LBAs internally; we just choose blocks back-to-front).
+            let mut block_end = if opts.reverse { end } else { range_pos };
+            loop {
                if let Some(ref h) = opts.halt {
                    if h.load(std::sync::atomic::Ordering::Relaxed) {
                        halted = true;
                        break 'outer;
                    }
                }
-                let block_bytes = (end - pos).min(block_sectors as u64 * 2048);
+                // Compute block boundaries based on direction.
+                let (pos, block_bytes) = if opts.reverse {
+                    if block_end <= range_pos {
+                        break;
+                    }
+                    let span = (block_end - range_pos).min(block_sectors as u64 * 2048);
+                    (block_end - span, span)
+                } else {
+                    if block_end >= end {
+                        break;
+                    }
+                    let span = (end - block_end).min(block_sectors as u64 * 2048);
+                    (block_end, span)
+                };
                let lba = (pos / 2048) as u32;
                let count = (block_bytes / 2048) as u16;
                let bytes = count as usize * 2048;
-                let read_ok = reader
-                    .read_sectors(lba, count, &mut buf[..bytes], true)
-                    .is_ok();
+                blocks_attempted += 1;
+                let read_result = reader.read_sectors(lba, count, &mut buf[..bytes], recovery);
+                // 0.13.23: parity with Disc::copy — bail immediately on a
+                // non-marginal SCSI sense (transport failure, HARDWARE
+                // ERROR, DATA PROTECT, UNIT ATTENTION, NOT READY,
+                // ILLEGAL REQUEST, kernel IoError). The wedged_threshold
+                // counter is a defense-in-depth backstop for ~50
+                // consecutive marginal failures, but a single
+                // non-marginal error already proves the drive can't
+                // produce data this pass — don't waste 50× the timeout
+                // budget proving it again.
+                if let Err(ref e) = read_result {
+                    if !e.is_marginal_read() {
+                        let err = read_result.err().unwrap();
+                        tracing::trace!(
+                            target: "freemkv::disc",
+                            phase = "patch_bail",
+                            lba,
+                            error = %err,
+                            "patch read failed with non-marginal sense; bailing"
+                        );
+                        return Err(err);
+                    }
+                }
+                let read_ok = read_result.is_ok();
                if read_ok {
+                    blocks_read_ok += 1;
+                    consecutive_failures = 0;
                    if opts.decrypt {
                        crate::decrypt::decrypt_sectors(&mut buf[..bytes], &keys, 0)?;
                    }
@@ -1529,20 +1718,81 @@ impl Disc {
                    map.record(pos, block_bytes, mapfile::SectorStatus::Finished)
                        .map_err(|e| Error::IoError { source: e })?;
                } else {
+                    blocks_read_failed += 1;
+                    consecutive_failures += 1;
+                    unreadable_count += 1;
                    map.record(pos, block_bytes, mapfile::SectorStatus::Unreadable)
                        .map_err(|e| Error::IoError { source: e })?;
                }
-                pos += block_bytes;
+                // Advance block_end in chosen direction.
+                if opts.reverse {
+                    block_end = block_end.saturating_sub(block_bytes);
+                } else {
+                    block_end += block_bytes;
+                }

-                if let Some(cb) = opts.on_progress {
+                // Wedged-drive early-exit: many consecutive failures with zero
+                // recovered bytes this pass means the drive is stuck and won't
+                // produce data this pass. Save the wallclock budget for productive
+                // grinding; future passes (with smaller block size, reverse, or
+                // after settle) may still recover.
+                if opts.wedged_threshold > 0
+                    && consecutive_failures >= opts.wedged_threshold
+                    && blocks_read_ok == 0
+                {
+                    tracing::trace!(
+                        target: "freemkv::disc",
+                        phase = "patch_wedged_exit",
+                        consecutive_failures,
+                        blocks_read_failed,
+                        "Disc::patch giving up — drive appears wedged"
+                    );
+                    wedged_exit = true;
+                    break 'outer;
+                }
+
+                // Track work done in this pass for the per-pass progress bar.
+                // Each block iterated counts as work, regardless of read
+                // outcome — a failed retry is still progress through the
+                // bad-range walk.
+                work_done = work_done.saturating_add(block_bytes);
+
+                if let Some(reporter) = opts.progress {
                    let s = map.stats();
-                    cb(s.bytes_good, total_bytes);
+                    let kind = if block_sectors == 1 {
+                        crate::progress::PassKind::Scrape {
+                            reverse: opts.reverse,
+                        }
+                    } else {
+                        crate::progress::PassKind::Trim {
+                            reverse: opts.reverse,
+                        }
+                    };
+                    reporter.report(&crate::progress::PassProgress {
+                        kind,
+                        work_done,
+                        work_total,
+                        bytes_good_total: s.bytes_good,
+                        bytes_total_disc: total_bytes,
+                    });
                }
            }
        }

        file.sync_all().map_err(|e| Error::IoError { source: e })?;
        let stats = map.stats();
+        tracing::info!(
+            target: "freemkv::disc",
+            phase = "patch_done",
+            blocks_attempted,
+            blocks_read_ok,
+            blocks_read_failed,
+            unreadable_count,
+            wedged_exit,
+            halted,
+            bytes_recovered = stats.bytes_good.saturating_sub(bytes_good_before),
+            "Disc::patch returning"
+        );
        Ok(PatchResult {
            bytes_total: total_bytes,
            bytes_good: stats.bytes_good,
@@ -1550,6 +1800,10 @@ impl Disc {
            bytes_pending: stats.bytes_pending,
            bytes_recovered_this_pass: stats.bytes_good.saturating_sub(bytes_good_before),
            halted,
+            blocks_attempted,
+            blocks_read_ok,
+            blocks_read_failed,
+            wedged_exit,
        })
    }
 }
@@ -1558,6 +1812,71 @@ const MAX_BATCH_SECTORS: u16 = 510;
 const DEFAULT_BATCH_SECTORS: u16 = 60;
 const MIN_BATCH_SECTORS: u16 = 3;

+/// Coarse damage tier for a finished or in-progress rip. Maps the
+/// observable signals (bad sector count + lost wallclock playback time)
+/// onto a small discrete classification so UIs can render a colored badge
+/// and operators can decide whether to rescan / replug / accept.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize, serde::Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum DamageSeverity {
+    /// No bad sectors at all.
+    Clean,
+    /// 1–50 bad sectors AND <1 sec lost. Likely unnoticeable.
+    Cosmetic,
+    /// 51–500 sectors OR 1–30 sec lost. Visible artifacts possible.
+    Moderate,
+    /// 500+ sectors OR 30+ sec lost. Significant damage; consider rescan
+    /// or different drive.
+    Serious,
+}
+
+/// Classify damage severity from raw counters. `bad_sectors` is the
+/// number of sectors marked unreadable (or NonTrimmed pending Pass 2);
+/// `lost_ms` is the cumulative wallclock playback time those sectors
+/// represent (computed from the title's bytes-per-sec).
+pub fn classify_damage(bad_sectors: u64, lost_ms: f64) -> DamageSeverity {
+    if bad_sectors == 0 {
+        return DamageSeverity::Clean;
+    }
+    if bad_sectors >= 500 || lost_ms >= 30_000.0 {
+        return DamageSeverity::Serious;
+    }
+    if bad_sectors >= 51 || lost_ms >= 1_000.0 {
+        return DamageSeverity::Moderate;
+    }
+    DamageSeverity::Cosmetic
+}
+
+#[cfg(test)]
+mod severity_tests {
+    use super::*;
+    #[test]
+    fn clean_when_no_damage() {
+        assert_eq!(classify_damage(0, 0.0), DamageSeverity::Clean);
+    }
+    #[test]
+    fn cosmetic_for_a_handful() {
+        assert_eq!(classify_damage(1, 5.0), DamageSeverity::Cosmetic);
+        assert_eq!(classify_damage(50, 999.0), DamageSeverity::Cosmetic);
+    }
+    #[test]
+    fn moderate_threshold_by_sectors() {
+        assert_eq!(classify_damage(51, 0.0), DamageSeverity::Moderate);
+    }
+    #[test]
+    fn moderate_threshold_by_time() {
+        assert_eq!(classify_damage(10, 1_000.0), DamageSeverity::Moderate);
+    }
+    #[test]
+    fn serious_threshold_by_sectors() {
+        assert_eq!(classify_damage(500, 0.0), DamageSeverity::Serious);
+    }
+    #[test]
+    fn serious_threshold_by_time() {
+        assert_eq!(classify_damage(10, 30_000.0), DamageSeverity::Serious);
+    }
+}
+
 /// Detect the maximum transfer size in sectors for a device.
 /// Reads /sys/block/<dev>/queue/max_hw_sectors_kb on Linux.
 /// For sg devices, resolves the corresponding block device via sysfs.
@@ -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` /
@@ -115,6 +119,9 @@ impl Drive {
        self.event_fn = Some(Box::new(f));
    }

+    #[allow(dead_code)] // public on_event registration kept; Drive currently
+    // has no internal emission sites after the 0.13.6 recovery strip.
+    // DiscStream is the BytesRead source. Plan to drop on_event in 0.14.
    fn emit(&self, kind: EventKind) {
        if let Some(ref f) = self.event_fn {
            f(Event { kind });
@@ -157,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()
@@ -174,31 +176,16 @@ impl Drive {

    pub fn wait_ready(&mut self) -> Result<()> {
        let tur = [SCSI_TEST_UNIT_READY, 0x00, 0x00, 0x00, 0x00, 0x00];
-        let mut tried_reset = false;

        for _ in 0..60 {
            let mut buf = [0u8; 0];
-            match self.scsi.as_mut().execute(
-                &tur,
-                crate::scsi::DataDirection::None,
-                &mut buf,
-                5_000,
-            ) {
-                Ok(_) => return Ok(()),
-                Err(Error::ScsiError { sense_key: 5, .. }) if !tried_reset => {
-                    // Illegal Request on TUR — drive may be stuck from a previous session.
-                    // Try reset() which attempts multiple recovery approaches.
-                    tried_reset = true;
-                    if self.reset().is_ok() {
-                        return Ok(());
-                    }
-                    // If reset failed but disc is present, proceed anyway —
-                    // the scan path will handle errors individually.
-                    if self.drive_status() == DriveStatus::DiscPresent {
-                        return Ok(());
-                    }
-                }
-                Err(_) => {}
+            if self
+                .scsi
+                .as_mut()
+                .execute(&tur, crate::scsi::DataDirection::None, &mut buf, 5_000)
+                .is_ok()
+            {
+                return Ok(());
            }
            std::thread::sleep(std::time::Duration::from_millis(500));
        }
@@ -253,94 +240,18 @@ impl Drive {
                    5_000,
                ) {
                    Ok(_) => DriveStatus::DiscPresent,
-                    Err(Error::ScsiError { sense_key: 2, .. }) => DriveStatus::NotReady,
-                    Err(Error::ScsiError { sense_key: 6, .. }) => DriveStatus::NotReady, // UNIT ATTENTION
+                    Err(ref e)
+                        if e.scsi_sense()
+                            .is_some_and(|s| s.is_not_ready() || s.is_unit_attention()) =>
+                    {
+                        DriveStatus::NotReady
+                    }
                    _ => DriveStatus::Unknown,
                }
            }
        }
    }

-    /// Attempt to reset the drive to a clean state.
-    ///
-    /// Escalates through increasingly aggressive recovery:
-    /// 1. Unlock tray + stop/start — handles normal stuck states
-    /// 2. Eject cycle — clears LibreDrive firmware stuck state (proven on BU40N)
-    /// 3. Re-init — firmware re-upload if profile available
-    ///
-    /// Note: step 2 physically ejects the tray. On slimline drives the user
-    /// must push it back in manually. Returns Ok(()) if TUR succeeds after
-    /// any step, even if the drive reports "tray open" (that's a valid state).
-    pub fn reset(&mut self) -> Result<()> {
-        let mut buf = [0u8; 0];
-        let tur = [SCSI_TEST_UNIT_READY, 0x00, 0x00, 0x00, 0x00, 0x00];
-
-        // 1. Unlock + stop/start
-        self.unlock_tray();
-        let stop = [SCSI_START_STOP_UNIT, 0x00, 0x00, 0x00, 0x00, 0x00];
-        let _ =
-            self.scsi
-                .as_mut()
-                .execute(&stop, crate::scsi::DataDirection::None, &mut buf, 5_000);
-        std::thread::sleep(std::time::Duration::from_millis(500));
-        let start = [SCSI_START_STOP_UNIT, 0x00, 0x00, 0x00, 0x01, 0x00];
-        let _ =
-            self.scsi
-                .as_mut()
-                .execute(&start, crate::scsi::DataDirection::None, &mut buf, 5_000);
-        std::thread::sleep(std::time::Duration::from_millis(2000));
-
-        if self
-            .scsi
-            .as_mut()
-            .execute(&tur, crate::scsi::DataDirection::None, &mut buf, 5_000)
-            .is_ok()
-        {
-            return Ok(());
-        }
-
-        // 2. Eject cycle — clears MT1959 LibreDrive stuck state.
-        // After eject, TUR returning "Not Ready — tray open" (sense key 2)
-        // counts as success: the drive is functional, just needs disc reinserted.
-        self.unlock_tray();
-        let eject = [SCSI_START_STOP_UNIT, 0x00, 0x00, 0x00, 0x02, 0x00];
-        let _ =
-            self.scsi
-                .as_mut()
-                .execute(&eject, crate::scsi::DataDirection::None, &mut buf, 30_000);
-        std::thread::sleep(std::time::Duration::from_millis(2000));
-
-        match self
-            .scsi
-            .as_mut()
-            .execute(&tur, crate::scsi::DataDirection::None, &mut buf, 5_000)
-        {
-            Ok(_) => return Ok(()),
-            Err(Error::ScsiError { sense_key: 2, .. }) => return Ok(()), // tray open = valid
-            _ => {}
-        }
-
-        // 3. If still stuck and we have a profile, try re-init
-        if self.driver.is_some() {
-            self.init()?;
-            std::thread::sleep(std::time::Duration::from_millis(1000));
-            match self.scsi.as_mut().execute(
-                &tur,
-                crate::scsi::DataDirection::None,
-                &mut buf,
-                5_000,
-            ) {
-                Ok(_) => return Ok(()),
-                Err(Error::ScsiError { sense_key: 2, .. }) => return Ok(()),
-                _ => {}
-            }
-        }
-
-        Err(Error::DeviceResetFailed {
-            path: self.device_path.clone(),
-        })
-    }
-
    pub fn platform_name(&self) -> &str {
        match self.platform {
            Some(ref p) => p.name(),
@@ -509,22 +420,38 @@ impl Drive {
    /// Read sectors from the disc. Single-shot — no inline retries, no
    /// SCSI reset.
    ///
-    /// `recovery=true` bumps the per-CDB timeout to 30 s for the
-    /// `Disc::patch` pass; `recovery=false` uses 1.5 s for `Disc::copy`'s
-    /// fast skip-forward sweep. On any failure returns `Err(DiscRead)`
-    /// immediately. The orchestration layer (`Disc::patch`'s outer loop
-    /// for the patch pass, `DiscStream`'s adaptive batch halving for the
-    /// stream path) handles retries.
+    /// `recovery=true` uses [`crate::scsi::READ_RECOVERY_TIMEOUT_MS`] (60 s,
+    /// matches sg_dd) for the `Disc::patch` pass; `recovery=false` uses
+    /// [`crate::scsi::READ_TIMEOUT_MS`] (30 s, matches the kernel's
+    /// `/sys/block/sr*/device/timeout` default) for `Disc::copy`'s fast
+    /// skip-forward sweep. Both budgets are generous enough that the drive
+    /// can finish ECC recovery on a marginal sector — pre-0.13.21 this was
+    /// 1.5 s on the fast path which forced the kernel mid-layer to time
+    /// out and escalate while we waited anyway. On any failure returns
+    /// `Err(DiscRead)` immediately; orchestration (`Disc::patch` multi-pass,
+    /// `DiscStream` adaptive batch halving) handles retry policy.
    ///
    /// 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
    /// touch the wedge-prone reset path.
    pub fn read(&mut self, lba: u32, count: u16, buf: &mut [u8], recovery: bool) -> Result<usize> {
-        let timeout_ms = if recovery { 30_000 } else { 1_500 };
+        let timeout_ms = if recovery {
+            crate::scsi::READ_RECOVERY_TIMEOUT_MS
+        } 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,
@@ -546,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,
+                })
+            }
        }
    }

@@ -659,19 +601,15 @@ impl SectorReader for Drive {
    }
 }

-/// Find all optical drives connected to this system.
-/// Returns opened Drive objects ready for use.
-pub fn find_drives() -> Vec<Drive> {
+/// Find the first optical drive on this system and open it.
+///
+/// For just listing drives without opening (e.g. UI sidebar), use
+/// `scsi::list_drives()` — that returns `DriveInfo` (path + identity)
+/// without the cost of running every drive's profile + identity probe.
+pub fn find_drive() -> Option<Drive> {
    discover_drives()
        .into_iter()
-        .filter_map(|(path, _)| Drive::open(std::path::Path::new(&path)).ok())
-        .collect()
-}
-
-/// Find the first optical drive.
-/// Returns an opened Drive ready for use.
-pub fn find_drive() -> Option<Drive> {
-    find_drives().into_iter().next()
+        .find_map(|(path, _)| Drive::open(std::path::Path::new(&path)).ok())
 }

 /// Halt-aware sleep primitive — wakes within ~100 ms of `halt` flipping
@@ -155,10 +155,24 @@ pub enum Error {
    },

    // SCSI (4xxx)
+    /// SCSI command failed.
+    ///
+    /// `opcode` is the failing CDB byte 0. `status` is the raw SCSI
+    /// status byte: `0x02` = CHECK CONDITION (drive replied with sense
+    /// data), `0xFF` = libfreemkv-synthesised sentinel meaning "no SCSI
+    /// status delivered" (kernel timeout, USB bridge wedge, IOKit
+    /// service failure). `sense` carries the drive's SPC-4 sense triple
+    /// when the drive replied; `None` for transport-layer failures.
+    ///
+    /// Recommended dispatch (callers shouldn't pattern-match raw
+    /// fields):
+    ///   - [`Error::is_scsi_transport_failure`] — bail; bridge/transport wedge
+    ///   - [`Error::is_marginal_read`] — drive said this read was marginal; smaller block may recover
+    ///   - [`Error::scsi_sense`] — borrow the sense triple for finer routing ([`ScsiSense::is_medium_error`] etc.)
    ScsiError {
        opcode: u8,
        status: u8,
-        sense_key: u8,
+        sense: Option<crate::scsi::ScsiSense>,
    },

    // I/O (5xxx)
@@ -169,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,
@@ -363,19 +379,46 @@ impl std::fmt::Display for Error {
            Error::ScsiError {
                opcode,
                status,
-                sense_key,
-            } => {
-                write!(
+                sense,
+            } => match sense {
+                Some(s) => write!(
                    f,
-                    "E{}: 0x{:02x}/0x{:02x}/0x{:02x}",
+                    "E{}: 0x{:02x}/0x{:02x}/0x{:02x}/0x{:02x}/0x{:02x}",
                    self.code(),
                    opcode,
                    status,
-                    sense_key
-                )
-            }
+                    s.sense_key,
+                    s.asc,
+                    s.ascq,
+                ),
+                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 } => {
@@ -438,6 +481,57 @@ impl From<Error> for std::io::Error {
 /// Convenience alias for `Result<T, Error>`.
 pub type Result<T> = std::result::Result<T, Error>;

+impl Error {
+    /// Borrow the drive-returned SPC-4 sense triple if this error is a
+    /// [`Error::ScsiError`] carrying sense data. `None` for any other
+    /// variant **and** for `ScsiError`s that represent a transport-layer
+    /// failure (where the device never delivered a SCSI status reply, so
+    /// no sense data exists).
+    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,
+        }
+    }
+
+    /// True if this is a [`Error::ScsiError`] representing a transport-layer
+    /// failure — kernel timeout, USB bridge wedge, IOKit service error.
+    /// The device never delivered a SCSI status reply, so there is no
+    /// sense data to inspect; retrying typically requires physical
+    /// intervention (replug).
+    pub fn is_scsi_transport_failure(&self) -> bool {
+        matches!(
+            self,
+            Error::ScsiError {
+                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:
+    ///
+    ///   - MEDIUM ERROR (sense key 3) — canonical bad-sector signal
+    ///   - ABORTED COMMAND (sense key B) — transient; retry usually works
+    ///   - RECOVERED ERROR (sense key 1) / NO SENSE (sense key 0) — not
+    ///     classified as fatal; treat as recoverable
+    ///
+    /// Returns `false` for transport failures (no sense data delivered),
+    /// HARDWARE ERROR, DATA PROTECT, UNIT ATTENTION, NOT READY, 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
+    /// `Disc::copy`'s hysteresis dispatch.
+    pub fn is_marginal_read(&self) -> bool {
+        self.scsi_sense()
+            .map(crate::scsi::ScsiSense::is_marginal)
+            .unwrap_or(false)
+    }
+}
+
 #[cfg(test)]
 mod tests {
    //! Smoke tests for the error code → variant mapping. Each new variant
@@ -88,6 +88,7 @@ pub mod mux;
 pub mod pes;
 pub(crate) mod platform;
 pub mod profile;
+pub mod progress;
 pub mod scsi;
 pub mod sector;
 pub(crate) mod speed;
@@ -102,7 +103,7 @@ pub mod verify;
 pub use drive::capture::{
    CapturedFeature, DriveCapture, capture_drive_data, mask_bytes, mask_string,
 };
-pub use drive::{Drive, DriveStatus, find_drive, find_drives};
+pub use drive::{Drive, DriveStatus, find_drive};

 // ─── Errors ─────────────────────────────────────────────────────────────────
 //
@@ -133,9 +134,10 @@ pub use decrypt::{DecryptKeys, decrypt_sectors};
 // background. The codec / channel / resolution enums are the canonical
 // structured representation; never compare against display strings.
 pub use disc::{
-    AacsState, AudioChannels, AudioStream, Clip, Codec, ColorSpace, ContentFormat, Disc,
-    DiscFormat, DiscId, DiscTitle, Extent, FrameRate, HdrFormat, KeySource, LabelPurpose,
+    AacsState, AudioChannels, AudioStream, Clip, Codec, ColorSpace, ContentFormat, DamageSeverity,
+    Disc, DiscFormat, DiscId, DiscTitle, Extent, FrameRate, HdrFormat, KeySource, LabelPurpose,
    LabelQualifier, Resolution, SampleRate, ScanOptions, Stream, SubtitleStream, VideoStream,
+    classify_damage,
 };

 // ─── Streams ────────────────────────────────────────────────────────────────
@@ -167,7 +169,7 @@ pub use mux::{InputOptions, StreamUrl, input, output, parse_url};
 // out-of-tree platform backends. `SectorReader` lets callers feed any byte
 // source (test harness, network image, SMB share) into the disc scan
 // pipeline; `FileSectorReader` is the standard ISO-on-disk implementation.
-pub use scsi::{DriveInfo, ScsiTransport, drive_has_disc, list_drives};
+pub use scsi::{DriveInfo, ScsiSense, ScsiTransport, drive_has_disc, list_drives};
 pub use sector::{FileSectorReader, SectorReader};
 pub use speed::DriveSpeed;
 pub use udf::{UdfFs, read_filesystem};
@@ -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;
@@ -157,8 +158,7 @@ impl DiscStream {
        content_format: crate::disc::ContentFormat,
    ) -> Self {
        let extents = title.extents.clone();
-        let bytes_total_extents: u64 =
-            extents.iter().map(|e| e.sector_count as u64 * 2048).sum();
+        let bytes_total_extents: u64 = extents.iter().map(|e| e.sector_count as u64 * 2048).sum();

        let mut pids = Vec::new();
        let mut parsers = Vec::new();
@@ -318,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());
                }
            }

@@ -96,8 +96,8 @@ impl Mt1959 {
        if result.bytes_transferred != expected {
            return Err(Error::ScsiError {
                opcode: SCSI_READ_BUFFER,
-                status: 0xFF,
-                sense_key: 0,
+                status: crate::scsi::SCSI_STATUS_TRANSPORT_FAILURE,
+                sense: None,
            });
        }
        Ok(result.bytes_transferred)
@@ -169,8 +169,8 @@ impl Mt1959 {
        }
        Err(Error::ScsiError {
            opcode: SCSI_READ_BUFFER,
-            status: 0xFF,
-            sense_key: 0,
+            status: crate::scsi::SCSI_STATUS_TRANSPORT_FAILURE,
+            sense: None,
        })
    }

@@ -275,8 +275,8 @@ impl Mt1959 {
            {
                return Err(Error::ScsiError {
                    opcode: SCSI_READ_BUFFER,
-                    status: 0xFF,
-                    sense_key: 0,
+                    status: crate::scsi::SCSI_STATUS_TRANSPORT_FAILURE,
+                    sense: None,
                });
            }
            addr = addr.wrapping_add(PROBE_STEP);
@@ -0,0 +1,70 @@
+//! 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
+//! `PassProgress` shape via the `Progress` trait. Consumers (autorip) compute
+//! a single `PipelineStats` derived view and never reach into per-pass
+//! internals.
+//!
+//! Why this matters: pre-0.13.16 the API leaked `pos`, `bytes_good`,
+//! `work_done`, `bytes_pending`, `Finished/NonTrimmed` mapfile semantics —
+//! and consumers reinvented the math each time they wanted a percentage.
+//! UIs ended up reading one source while server-side computed from another,
+//! producing wrong percentages without anyone noticing.
+
+/// Identifies which pipeline phase the progress event belongs to.
+///
+/// Consumers can render a phase-specific label (e.g. "Sweep", "Trim
+/// (reverse)", "Scrape", "Mux") or just use a generic "Pass N" label.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum PassKind {
+    /// `Disc::copy` — initial sweep across the entire disc.
+    Sweep,
+    /// `Disc::patch` retry pass with `block_sectors >= 2`. `reverse=true`
+    /// means walking bad ranges from highest to lowest LBA.
+    Trim { reverse: bool },
+    /// `Disc::patch` final pass at 1 sector per block.
+    Scrape { reverse: bool },
+    /// Demux ISO → output (MKV / M2TS / network). Single phase that runs
+    /// after all rip passes complete.
+    Mux,
+}
+
+/// One progress sample from a pipeline phase.
+///
+/// `work_done / work_total` is the per-pass percentage — always 0..=100%
+/// 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.
+#[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_total_disc: u64,
+}
+
+/// 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).
+///
+/// No `Send`/`Sync` bound — `report` is always called from the same thread
+/// running the rip 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);
+}
+
+impl<F: Fn(&PassProgress)> Progress for F {
+    fn report(&self, p: &PassProgress) {
+        (self)(p)
+    }
+}
@@ -1,11 +1,23 @@
-//! Linux SCSI transport via async sg write/poll/read.
+//! Linux SCSI transport via synchronous blocking SG_IO ioctl.
 //!
-//! Uses the sg driver's asynchronous interface instead of the blocking
-//! SG_IO ioctl. Commands are submitted via write(), waited on via
-//! poll() with a hard timeout, and completed via read(). If poll()
-//! times out, the fd is abandoned (closed in a background thread) and
-//! a fresh fd is opened. This gives us true user-controlled timeouts
-//! that the kernel's USB error recovery cannot override.
+//! `execute()` is one syscall: `ioctl(fd, SG_IO, &hdr)` blocks until the
+//! kernel completes the command (success, error, or its own timeout).
+//! No userspace abort, no fd close+reopen, no SG_SCSI_RESET escalation —
+//! the kernel SCSI mid-layer's `scsi_eh.rst` ladder
+//! (ABORT TASK → LUN RESET → BUS RESET → HOST RESET) runs internally
+//! when `hdr.timeout` expires, and by the time the ioctl returns the
+//! kernel has already done what it can.
+//!
+//! 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
+//! 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
+//! the drive could drain its internal queue, deepening the wedge
+//! pattern on the LG BU40N. Reverted in 0.13.20.

 use super::{DataDirection, ScsiResult, ScsiTransport};
 use crate::error::{Error, Result};
@@ -45,23 +57,22 @@ struct sg_io_hdr {
 }

 // Compile-time validation: sg_io_hdr must match the kernel's layout.
-// 64 bytes on 64-bit, 44 bytes on 32-bit (pointer-size dependent).
+// 88 bytes on 64-bit, 64 bytes on 32-bit (pointer-size dependent).
 #[cfg(target_pointer_width = "64")]
 const _: () = assert!(std::mem::size_of::<sg_io_hdr>() == 88);
 #[cfg(target_pointer_width = "32")]
 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. Resets the drive first to ensure
-    /// a known good state, then opens a fresh fd for commands.
+    /// 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(
@@ -75,6 +86,7 @@ impl SgIoTransport {
        Ok(SgIoTransport {
            fd,
            device_path: device,
+            fd_recovery: std::sync::Arc::new(std::sync::atomic::AtomicI32::new(-1)),
        })
    }

@@ -94,56 +106,12 @@ 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 {
            Error::DevicePermission {
-                path: format!(
-                    "{}: permission denied (try running as root)",
-                    device.display()
-                ),
+                path: device.display().to_string(),
            }
        } else {
            Error::DeviceNotFound {
@@ -153,8 +121,7 @@ impl SgIoTransport {
    }

    /// Send a raw SCSI command on an fd. Used by reset() before the
-    /// transport is constructed. Uses synchronous SG_IO — fine for
-    /// short commands (TUR, PREVENT MEDIUM REMOVAL, START/STOP).
+    /// transport is constructed.
    fn raw_command(fd: i32, cdb: &[u8], timeout_ms: u32) -> std::result::Result<(), ()> {
        let mut sense = [0u8; 32];
        let mut hdr: sg_io_hdr = unsafe { std::mem::zeroed() };
@@ -170,7 +137,7 @@ impl SgIoTransport {
        hdr.flags = SG_FLAG_Q_AT_HEAD;

        let ret = unsafe { libc::ioctl(fd, SG_IO as _, &mut hdr as *mut sg_io_hdr) };
-        if ret < 0 || hdr.status != 0 {
+        if ret < 0 || hdr.status != 0 || hdr.host_status != 0 || hdr.driver_status != 0 {
            Err(())
        } else {
            Ok(())
@@ -215,7 +182,7 @@ impl SgIoTransport {
 impl Drop for SgIoTransport {
    fn drop(&mut self) {
        if self.fd >= 0 {
-            // Unlock tray before closing — don't leave it locked
+            // Unlock tray before closing — don't leave it locked.
            let _ = Self::raw_command(self.fd, &[0x1E, 0, 0, 0, 0, 0], 3_000);
            unsafe { libc::close(self.fd) };
        }
@@ -223,21 +190,33 @@ impl Drop for SgIoTransport {
 }

 impl ScsiTransport for SgIoTransport {
-    /// Execute a SCSI command with an enforceable timeout.
+    /// Execute a SCSI command via synchronous blocking SG_IO.
    ///
-    /// Uses the sg driver's async write/poll/read interface:
-    /// 1. write() submits the command — returns immediately
-    /// 2. poll() waits for completion — respects our timeout exactly
-    /// 3. read() retrieves the result — copies data to caller's buffer
+    /// One syscall: `ioctl(fd, SG_IO, &hdr)`. The kernel honors
+    /// `hdr.timeout` and runs its own ABORT TASK → LUN RESET → BUS
+    /// RESET → HOST RESET escalation if the device times out (per
+    /// `Documentation/scsi/scsi_eh.rst`). By the time this returns,
+    /// the kernel has done its recovery work.
    ///
-    /// If poll() times out, the pending command is abandoned: the old fd
-    /// is closed in a background thread (may block while kernel finishes
-    /// the USB transfer) and a fresh fd is opened. The caller sees a
-    /// normal SCSI error and can retry.
+    /// Errors we surface to caller (any of these = command failed):
    ///
-    /// Without SG_FLAG_DIRECT_IO, the kernel uses internal buffers for
-    /// DMA and copies to userspace during read(). On timeout (no read),
-    /// the caller's buffer is untouched — safe to return immediately.
+    ///   - ioctl returned -1 → `Error::IoError` (kernel-level failure)
+    ///   - `hdr.host_status` != 0 OR `(hdr.driver_status & ~DRIVER_SENSE)` != 0
+    ///     → `Error::ScsiError { status: 0xFF, sense_key: 0, asc: 0, ascq: 0 }`
+    ///     (real transport-layer failure: kernel timeout, bridge wedge, bus error)
+    ///   - `hdr.status` != 0 (typically `0x02` CHECK CONDITION) →
+    ///     `Error::ScsiError { status, sense_key, asc, ascq }` carrying the
+    ///     drive's full SPC-4 sense triple. Callers route on
+    ///     `is_medium_error()`, `is_unit_attention()`, etc.
+    ///
+    /// Note: SG's `DRIVER_SENSE` (0x08) bit indicates *sense data is
+    /// attached* — it's set on every CHECK CONDITION reply. It is **not**
+    /// a transport failure; pre-0.13.23 we conflated it with one and
+    /// silently lost every drive-reported error reason. The mask in the
+    /// transport-error check below is the fix.
+    ///
+    /// Caller's `data` buffer is mutated only on success; partial
+    /// transfers are reported via `bytes_transferred = data.len() - resid`.
    fn execute(
        &mut self,
        cdb: &[u8],
@@ -245,30 +224,50 @@ impl ScsiTransport for SgIoTransport {
        data: &mut [u8],
        timeout_ms: u32,
    ) -> Result<ScsiResult> {
-        if self.fd < 0 {
+        let exec_t0 = std::time::Instant::now();
+        let opcode = cdb[0];
+        tracing::trace!(
+            target: "freemkv::scsi",
+            phase = "enter",
+            opcode = opcode,
+            timeout_ms,
+            data_len = data.len(),
+            fd = self.fd,
+            "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(),
            });
        }

-        let mut sense = [0u8; 32];
+        if data.len() > u32::MAX as usize {
+            return Err(Error::ScsiError {
+                opcode: cdb[0],
+                status: super::SCSI_STATUS_TRANSPORT_FAILURE,
+                sense: None,
+            });
+        }

        let dxfer_direction = match direction {
            DataDirection::None => SG_DXFER_NONE,
            DataDirection::FromDevice => SG_DXFER_FROM_DEV,
            DataDirection::ToDevice => SG_DXFER_TO_DEV,
        };
-
-        if data.len() > u32::MAX as usize {
-            return Err(Error::ScsiError {
-                opcode: cdb[0],
-                status: 0xFF,
-                sense_key: 0,
-            });
-        }
-
        let cmd_len = cdb.len().min(16) as u8;

+        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 = dxfer_direction;
@@ -281,109 +280,118 @@ impl ScsiTransport for SgIoTransport {
        hdr.timeout = timeout_ms;
        hdr.flags = SG_FLAG_Q_AT_HEAD;

-        // Submit command asynchronously via write()
-        let hdr_size = std::mem::size_of::<sg_io_hdr>();
-        let wr = unsafe {
-            libc::write(
-                self.fd,
-                &hdr as *const sg_io_hdr as *const libc::c_void,
-                hdr_size,
-            )
-        };
-        if wr < 0 {
-            return Err(Error::IoError {
-                source: std::io::Error::last_os_error(),
-            });
+        // The single blocking syscall. Returns when the device responds,
+        // when the kernel's timeout fires, or when the kernel's error
+        // recovery completes its escalation. On a healthy read this is
+        // <100 ms; on a slow-recovery bad sector it can be tens of
+        // seconds; on a hung drive it returns at `timeout_ms` with
+        // `host_status` flagged.
+        let ret = unsafe { libc::ioctl(self.fd, SG_IO as _, &mut hdr as *mut sg_io_hdr) };
+        let exec_elapsed_ms = exec_t0.elapsed().as_millis() as u64;
+
+        if ret < 0 {
+            let errno = std::io::Error::last_os_error();
+            tracing::trace!(
+                target: "freemkv::scsi",
+                phase = "ioctl_err",
+                opcode = opcode,
+                errno = errno.raw_os_error().unwrap_or(0),
+                exec_elapsed_ms,
+                "ioctl(SG_IO) returned <0"
+            );
+            return Err(Error::IoError { source: errno });
        }

-        // Wait for completion with enforceable timeout.
-        // Retry on EINTR (signal interrupted poll) with remaining time.
-        let deadline =
-            std::time::Instant::now() + std::time::Duration::from_millis(timeout_ms as u64);
-        let pr = loop {
-            let remaining = deadline
-                .saturating_duration_since(std::time::Instant::now())
-                .as_millis() as i32;
-            if remaining <= 0 {
-                break 0; // expired
-            }
-            let mut pfd = libc::pollfd {
-                fd: self.fd,
-                events: libc::POLLIN,
-                revents: 0,
-            };
-            let ret = unsafe { libc::poll(&mut pfd, 1, remaining) };
-            if ret >= 0 || std::io::Error::last_os_error().kind() != std::io::ErrorKind::Interrupted
-            {
-                break ret;
-            }
-        };
+        // Transport-level failure (kernel timeout, USB bridge wedge,
+        // bus error). `hdr.status` may still be zero — the SCSI device
+        // never got to send a status byte. Surface as 0xFF so callers
+        // (e.g. `drive_has_disc`) can detect the wedge signature.
+        //
+        // 0.13.23: mask out `DRIVER_SENSE` (0x08) before treating
+        // `driver_status` as a transport failure. That bit is set on
+        // *every* CHECK CONDITION reply just to flag "sense data is
+        // attached in `sbp`" — it's not an error of its own. Pre-fix
+        // we collapsed every drive-reported error into a synthetic
+        // 0xFF wedge signature and discarded the sense data, which
+        // killed the rip's classification logic on damaged discs.
+        let driver_status_real = hdr.driver_status & !super::DRIVER_SENSE;
+        if hdr.host_status != 0 || driver_status_real != 0 {
+            tracing::trace!(
+                target: "freemkv::scsi",
+                phase = "transport_err",
+                opcode = opcode,
+                host_status = hdr.host_status,
+                driver_status = hdr.driver_status,
+                status = hdr.status,
+                exec_elapsed_ms,
+                "transport-level failure (timeout / bridge wedge)"
+            );

-        if pr <= 0 {
-            // Timeout (0) or fatal poll error (-1).
-            // Command is still pending in the kernel. Abandon this fd and
-            // open a fresh one. The old fd is closed in a background thread
-            // because close() blocks until the kernel completes/aborts the
-            // pending command.
+            // 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 || {
-                unsafe { libc::close(old_fd) };
+                if old_fd >= 0 {
+                    unsafe { libc::close(old_fd) };
+                }
            });

-            let c_path = Self::to_c_path(&self.device_path);
-            let new_fd = unsafe {
-                libc::open(
-                    c_path.as_ptr() as *const libc::c_char,
-                    libc::O_RDWR | libc::O_NONBLOCK | libc::O_CLOEXEC,
-                )
-            };
-            self.fd = if new_fd >= 0 { new_fd } else { -1 };
+            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: 0xFF,
-                sense_key: 0,
+                status: super::SCSI_STATUS_TRANSPORT_FAILURE,
+                sense: None,
            });
        }

-        // Read response — copies data from kernel buffer to caller's buffer
-        let rd = unsafe {
-            libc::read(
-                self.fd,
-                &mut hdr as *mut sg_io_hdr as *mut libc::c_void,
-                hdr_size,
-            )
-        };
-        if rd < 0 {
-            return Err(Error::IoError {
-                source: std::io::Error::last_os_error(),
+        // SCSI-level failure: device responded, returned non-zero status
+        // (typically 0x02 CHECK CONDITION). Parse the full SPC-4 sense
+        // triple so callers can route on `ScsiSense::is_medium_error()`
+        // etc.
+        if hdr.status != 0 {
+            let parsed = super::parse_sense(&sense, hdr.sb_len_wr);
+            tracing::trace!(
+                target: "freemkv::scsi",
+                phase = "scsi_err",
+                opcode = opcode,
+                status = hdr.status,
+                sense_key = parsed.sense_key,
+                asc = parsed.asc,
+                ascq = parsed.ascq,
+                exec_elapsed_ms,
+                "SCSI status non-zero"
+            );
+            return Err(Error::ScsiError {
+                opcode: cdb[0],
+                status: hdr.status,
+                sense: Some(parsed),
            });
        }

        let bytes_transferred = (data.len() as i32).saturating_sub(hdr.resid).max(0) as usize;
-
-        if hdr.status != 0 {
-            let sense_key = if hdr.sb_len_wr >= 3 {
-                let response_code = sense[0] & 0x7F;
-                if response_code == 0x72 || response_code == 0x73 {
-                    // Descriptor format sense: sense key at byte 1
-                    sense[1] & 0x0F
-                } else {
-                    // Fixed format sense (0x70/0x71): sense key at byte 2
-                    sense[2] & 0x0F
-                }
-            } else {
-                0
-            };
-            return Err(Error::ScsiError {
-                opcode: cdb[0],
-                status: hdr.status,
-                sense_key,
-            });
-        }
-
+        tracing::trace!(
+            target: "freemkv::scsi",
+            phase = "ok",
+            opcode = opcode,
+            bytes_transferred,
+            exec_elapsed_ms,
+            "execute() success"
+        );
        Ok(ScsiResult {
            status: hdr.status,
            bytes_transferred,
@@ -399,35 +407,20 @@ impl ScsiTransport for SgIoTransport {
 // `/dev/sg0..15` probe when sysfs is unreadable (minimal containers).
 //
 // `drive_has_disc` issues a single TEST UNIT READY. On the wedge signature
-// (kernel returns status `0xff` with no sense) it escalates: SCSI bus reset
-// → if still wedged → USB device reset (`USBDEVFS_RESET`) → retry TUR.
-// Callers never see the escalation; if it fails too, surface
-// `DeviceResetFailed` so the caller can back off.
+// (kernel returns status `0xff` with no sense — synthesised by `execute()`
+// from a non-zero `host_status`) the error bubbles directly to the caller;
+// no in-library reset escalation. See the rationale block on
+// `drive_has_disc` below.

 /// SCSI peripheral type 5 = "CD-ROM device" (covers DVD, BD-ROM, BD-RE, etc.).
 /// Stored in `/sys/class/scsi_generic/sgN/device/type` as ASCII decimal.
 const SCSI_TYPE_OPTICAL: &str = "5";

-/// SCSI sense key 2 = "NOT READY". Sub-codes distinguish "medium not present"
-/// (no disc) from other not-ready states (loading, etc.); for poll-loop
-/// purposes any sense-key 2 means "no disc to act on".
-const SENSE_KEY_NOT_READY: u8 = 2;
-
 /// Maximum sg index probed in the fallback path when sysfs is unavailable.
 /// Linux assigns `/dev/sgN` sequentially per host adapter; 16 covers any
 /// realistic homelab (typical PERC + USB optical = ≤8 nodes).
 const SG_FALLBACK_MAX: u8 = 16;

-/// SCSI INQUIRY response field offsets (SPC-4, 6-byte standard CDB
-/// returning 96 bytes). Used to populate `DriveInfo` fields without
-/// magic-number arithmetic at the call site.
-const INQUIRY_VENDOR_OFFSET: usize = 8;
-const INQUIRY_VENDOR_LEN: usize = 8;
-const INQUIRY_MODEL_OFFSET: usize = 16;
-const INQUIRY_MODEL_LEN: usize = 16;
-const INQUIRY_FIRMWARE_OFFSET: usize = 32;
-const INQUIRY_FIRMWARE_LEN: usize = 4;
-
 pub(super) fn list_drives() -> Vec<super::DriveInfo> {
    let mut out = Vec::new();
    let names = enumerate_sg_names();
@@ -447,8 +440,7 @@ pub(super) fn list_drives() -> Vec<super::DriveInfo> {

        // INQUIRY-only probe — open transport, run INQUIRY, drop. No
        // identify, no init, no firmware reset preamble's secondary
-        // commands beyond what `SgIoTransport::open` already does (one
-        // SCSI bus reset on the kernel SG fd, ~2 s).
+        // commands beyond what `SgIoTransport::open` already does.
        let info = match SgIoTransport::open(std::path::Path::new(&path)) {
            Ok(mut transport) => match super::inquiry(&mut transport) {
                Ok(r) => super::DriveInfo {
@@ -514,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 {
@@ -532,50 +524,64 @@ fn enumerate_sg_names() -> Vec<String> {
    names
 }

-/// `drive_has_disc` = single TEST UNIT READY. Any error (including our
-/// synthesised wedge signature, `ScsiError { status: 0xFF }`, when
-/// `execute()` times out) 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),
+    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 {
-            sense_key: SENSE_KEY_NOT_READY,
-            ..
-        }) => Ok(false),
-        Err(e) => Err(e),
+            opcode: cdb[0],
+            status: hdr.status,
+            sense: Some(parsed),
+        })
    }
 }
@@ -195,6 +195,17 @@ impl MacScsiTransport {
            dev_str
        };

+        let device_iface = Self::acquire_device_iface(bsd_name)?;
+
+        Ok(MacScsiTransport {
+            device_iface,
+            exclusive: true,
+        })
+    }
+
+    /// 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
@@ -213,7 +224,7 @@ impl MacScsiTransport {

        if kr != K_IO_RETURN_SUCCESS || plugin.is_null() {
            return Err(Error::IoKitPluginFailed {
-                path: dev_str.to_string(),
+                path: bsd_name.to_string(),
                kr: kr as u32,
            });
        }
@@ -233,7 +244,7 @@ impl MacScsiTransport {

        if hr != 0 || device_iface.is_null() {
            return Err(Error::ScsiInterfaceUnavailable {
-                path: dev_str.to_string(),
+                path: bsd_name.to_string(),
            });
        }

@@ -245,22 +256,20 @@ impl MacScsiTransport {
        };
        if kr != K_IO_RETURN_SUCCESS {
            com_release(device_iface);
-            // No "Try: diskutil unmountDisk" hint — that's the CLI's job.
-            // The typed variant carries device path + IOReturn so the
-            // caller can render the right message in the right language.
            return Err(Error::DeviceLocked {
-                path: dev_str.to_string(),
+                path: bsd_name.to_string(),
                kr: kr as u32,
            });
        }

-        Ok(MacScsiTransport {
-            device_iface,
-            exclusive: true,
-        })
+        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 architecture audit, 2026-04-26).
+    // Errors bubble up; caller decides whether to reopen the Drive.
 }

 /// Enumerate optical drives on macOS. Mirrors `drive::macos::find_drives`
@@ -328,15 +337,16 @@ pub(super) fn drive_has_disc(path: &Path) -> Result<bool> {
        crate::scsi::TUR_TIMEOUT_MS,
    ) {
        Ok(_) => Ok(true),
-        Err(Error::ScsiError { sense_key, .. }) if sense_key == K_SENSE_KEY_NOT_READY => Ok(false),
+        Err(ref e) if e.scsi_sense().is_some_and(|s| s.is_not_ready()) => Ok(false),
        Err(e) => Err(e),
    }
 }

-const K_SENSE_KEY_NOT_READY: u8 = 2;
-
 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;
@@ -365,8 +375,8 @@ impl ScsiTransport for MacScsiTransport {
        if task.is_null() {
            return Err(Error::ScsiError {
                opcode: cdb[0],
-                status: 0xFF,
-                sense_key: 0,
+                status: super::SCSI_STATUS_TRANSPORT_FAILURE,
+                sense: None,
            });
        }

@@ -433,19 +443,29 @@ impl ScsiTransport for MacScsiTransport {
        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: 0xFF,
-                sense_key: 0,
+                status: super::SCSI_STATUS_TRANSPORT_FAILURE,
+                sense: None,
            });
        }

        if task_status != K_SCSI_TASK_STATUS_GOOD as u32 {
-            let sense_key = if sense[2] != 0 { sense[2] & 0x0F } else { 0 };
+            // 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_key,
+                sense: Some(parsed),
            });
        }

@@ -6,7 +6,7 @@
 //!   - `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")]
@@ -43,6 +43,238 @@ pub const AACS_KEY_CLASS: u8 = 0x02;
 /// a poll-loop tick.
 pub(crate) const TUR_TIMEOUT_MS: u32 = 5_000;

+/// Timeout for content READ commands (READ_10 / READ_12) on the fast
+/// path — the [`disc::Disc::copy`] sweep that bisects-on-failure.
+///
+/// 10 s is calibrated from live empirical data on an LG BU40N + Initio
+/// 1618L bridge ripping a UHD with marginal sectors:
+///
+///   - Sustained sequential reads:    3 – 7 ms
+///   - Cold-start seek + read:        up to ~1500 ms
+///   - Successful ECC recovery:       1.6 – 2.6 sec
+///   - Confirmed unreadable sector:   3.6 – 8.8 sec (kernel timeout)
+///
+/// 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 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
+/// full ABORT TASK / LUN RESET / BUS RESET escalation while userspace
+/// kept submitting fresh reads. The Initio bridge couldn't drain the
+/// resulting command queue and entered a wedge state that only physical
+/// replug recovered — proven by the v0.13.18 + v0.13.20 live tests.
+pub(crate) const READ_TIMEOUT_MS: u32 = 10_000;
+
+/// Timeout for content READ commands on the recovery path —
+/// [`disc::Disc::patch`]'s targeted retries on bad ranges. Doubles
+/// the fast-path budget so a sector that fails at 30 s gets one more
+/// honest attempt. Matches sg_dd's default per-command timeout
+/// (`DEF_TIMEOUT = 60000`).
+pub(crate) const READ_RECOVERY_TIMEOUT_MS: u32 = 60_000;
+
+// ── SCSI status bytes (SPC-4 §4.5.5) ────────────────────────────────────────
+
+/// Status byte 0x00 — `GOOD`. Command completed successfully.
+pub const SCSI_STATUS_GOOD: u8 = 0x00;
+/// Status byte 0x02 — `CHECK CONDITION`. Drive completed the command
+/// reply and attached sense data describing the failure.
+pub const SCSI_STATUS_CHECK_CONDITION: u8 = 0x02;
+/// libfreemkv-synthesised sentinel: the transport never delivered a
+/// SCSI status byte (kernel timeout, USB bridge wedge, IOKit service
+/// failure). Distinct from any drive-returned value. Carriers
+/// [`Error::ScsiError`] with `sense = None`.
+pub const SCSI_STATUS_TRANSPORT_FAILURE: u8 = 0xFF;
+
+// ── SPC-4 sense keys (§4.5.6 Table 28) ─────────────────────────────────────
+//
+// Broad failure category returned in a CHECK CONDITION reply's sense data.
+// Names match the SCSI spec; predicate methods on [`ScsiSense`] (e.g.
+// `is_medium_error`, `is_unit_attention`) read more fluently than raw
+// constant comparisons at call sites.
+
+pub const SENSE_KEY_NO_SENSE: u8 = 0x00;
+pub const SENSE_KEY_RECOVERED_ERROR: u8 = 0x01;
+pub const SENSE_KEY_NOT_READY: u8 = 0x02;
+pub const SENSE_KEY_MEDIUM_ERROR: u8 = 0x03;
+pub const SENSE_KEY_HARDWARE_ERROR: u8 = 0x04;
+pub const SENSE_KEY_ILLEGAL_REQUEST: u8 = 0x05;
+pub const SENSE_KEY_UNIT_ATTENTION: u8 = 0x06;
+pub const SENSE_KEY_DATA_PROTECT: u8 = 0x07;
+pub const SENSE_KEY_BLANK_CHECK: u8 = 0x08;
+pub const SENSE_KEY_ABORTED_COMMAND: u8 = 0x0B;
+
+// ── Sense parsing ───────────────────────────────────────────────────────────
+
+/// Decoded SPC-4 sense triple — the precise reason a SCSI command failed.
+///
+/// Returned by [`parse_sense`] and embedded inside [`Error::ScsiError`]
+/// (`sense: Option<ScsiSense>`). Predicate methods (`is_medium_error`,
+/// `is_unit_attention`, `is_marginal`, …) read more fluently at call
+/// sites than raw `sense_key` comparisons.
+///
+/// `Default::default()` and the [`ScsiSense::NONE`] constant both
+/// produce the all-zero "no sense info" triple. Per SPC-4 §4.5.3, an
+/// empty sense buffer is reported as NO SENSE (key 0); use the constant
+/// for explicit intent at construction sites.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
+pub struct ScsiSense {
+    /// Sense key — broad failure category (SPC-4 §4.5.6 Table 28).
+    /// See the `SENSE_KEY_*` constants for named values.
+    pub sense_key: u8,
+    /// Additional Sense Code — narrows the cause within a sense key
+    /// (SPC-4 §4.5.6 Table 29). E.g. `0x11` = UNRECOVERED READ ERROR.
+    pub asc: u8,
+    /// Additional Sense Code Qualifier — finest-grain disambiguation.
+    /// E.g. `0x05` (with `asc=0x11`) = L-EC UNCORRECTABLE.
+    pub ascq: u8,
+}
+
+impl ScsiSense {
+    /// Sense reply with all-zero fields — explicit "no sense info"
+    /// constructor for sites where `Default::default()` would be opaque.
+    pub const NONE: ScsiSense = ScsiSense {
+        sense_key: 0,
+        asc: 0,
+        ascq: 0,
+    };
+
+    /// `true` when the sense key indicates a *marginal-read* failure —
+    /// the kind of error where the same read at smaller granularity
+    /// (or a brief retry) sometimes succeeds:
+    ///
+    ///   - `MEDIUM ERROR` (3) — canonical bad-sector signal
+    ///   - `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
+    /// by [`Error::is_marginal_read`] / `Disc::copy`'s hysteresis
+    /// dispatch.
+    pub fn is_marginal(&self) -> bool {
+        matches!(
+            self.sense_key,
+            SENSE_KEY_NO_SENSE
+                | SENSE_KEY_RECOVERED_ERROR
+                | SENSE_KEY_MEDIUM_ERROR
+                | SENSE_KEY_ABORTED_COMMAND
+        )
+    }
+
+    /// `true` if `sense_key == MEDIUM ERROR (3)` — canonical "bad sector"
+    /// signal from the drive.
+    pub fn is_medium_error(&self) -> bool {
+        self.sense_key == SENSE_KEY_MEDIUM_ERROR
+    }
+
+    /// `true` if `sense_key == HARDWARE ERROR (4)` — drive itself is
+    /// failing. Not recoverable by retry.
+    pub fn is_hardware_error(&self) -> bool {
+        self.sense_key == SENSE_KEY_HARDWARE_ERROR
+    }
+
+    /// `true` if `sense_key == NOT READY (2)` — medium not present /
+    /// drive becoming ready / etc.
+    pub fn is_not_ready(&self) -> bool {
+        self.sense_key == SENSE_KEY_NOT_READY
+    }
+
+    /// `true` if `sense_key == UNIT ATTENTION (6)` — disc/drive state
+    /// changed since the prior command (media inserted/removed,
+    /// power-on reset, parameters changed). Caller should rescan rather
+    /// than retry the read.
+    pub fn is_unit_attention(&self) -> bool {
+        self.sense_key == SENSE_KEY_UNIT_ATTENTION
+    }
+
+    /// `true` if `sense_key == DATA PROTECT (7)` — read blocked by
+    /// AACS / region / write-protect. Retry won't help.
+    pub fn is_data_protect(&self) -> bool {
+        self.sense_key == SENSE_KEY_DATA_PROTECT
+    }
+
+    /// `true` if `sense_key == ILLEGAL REQUEST (5)` — typically a bug
+    /// in the CDB we sent (LBA out of range, reserved bit, etc.). Don't
+    /// retry.
+    pub fn is_illegal_request(&self) -> bool {
+        self.sense_key == SENSE_KEY_ILLEGAL_REQUEST
+    }
+
+    /// `true` if `sense_key == ABORTED COMMAND (B)` — transient; one
+    /// retry is usually safe.
+    pub fn is_aborted_command(&self) -> bool {
+        self.sense_key == SENSE_KEY_ABORTED_COMMAND
+    }
+}
+
+/// Decode an SPC-4 sense buffer into the structured triple
+/// `(sense_key, asc, ascq)`.
+///
+/// Handles both response-code formats SPC-4 mandates:
+///
+///   - **Descriptor format** (response code `0x72` / `0x73`):
+///     - sense key = `sense[1] & 0x0F`
+///     - asc = `sense[2]`
+///     - ascq = `sense[3]`
+///   - **Fixed format** (response code `0x70` / `0x71` and any unknown
+///     code per SPC-4 §4.5.3):
+///     - sense key = `sense[2] & 0x0F`
+///     - asc = `sense[12]`
+///     - ascq = `sense[13]`
+///
+/// `sb_len_wr` is the number of bytes the transport actually wrote into
+/// `sense`. When the buffer is too short for the relevant fields we
+/// return [`ScsiSense::NONE`] for the missing pieces rather than reading
+/// uninitialised memory. The minimum useful sense reply per SPC-4 is 8
+/// bytes (descriptor) or 14 bytes (fixed, to reach ASC/ASCQ at offsets
+/// 12/13).
+///
+/// Pure function — same parse on every platform backend (Linux SG_IO,
+/// macOS IOKit, Windows SPTI) so a regression here would silently
+/// mis-route SCSI errors on all three OSes simultaneously.
+pub(crate) fn parse_sense(sense: &[u8], sb_len_wr: u8) -> ScsiSense {
+    let n = (sb_len_wr as usize).min(sense.len());
+    if n < 3 {
+        return ScsiSense::NONE;
+    }
+    let response_code = sense[0] & 0x7F;
+    let descriptor = response_code == 0x72 || response_code == 0x73;
+    if descriptor {
+        // Descriptor format: key/asc/ascq are at fixed offsets 1/2/3.
+        let asc = if n >= 3 { sense[2] } else { 0 };
+        let ascq = if n >= 4 { sense[3] } else { 0 };
+        ScsiSense {
+            sense_key: sense[1] & 0x0F,
+            asc,
+            ascq,
+        }
+    } else {
+        // Fixed format: key at byte 2, ASC/ASCQ at bytes 12/13.
+        let asc = if n >= 13 { sense[12] } else { 0 };
+        let ascq = if n >= 14 { sense[13] } else { 0 };
+        ScsiSense {
+            sense_key: sense[2] & 0x0F,
+            asc,
+            ascq,
+        }
+    }
+}
+
+// ── SG_IO driver_status bits ────────────────────────────────────────────────
+
+/// `DRIVER_SENSE` (0x08) — bit set in `driver_status` to indicate that
+/// sense data was attached to a CHECK CONDITION reply. **Not** a transport
+/// failure on its own. Mask this off before deciding whether `driver_status`
+/// represents a real bus/host problem.
+///
+/// Used by Linux SG_IO (`sg_io_hdr.driver_status`); macOS IOKit and
+/// Windows SPTI carry the equivalent signal in different fields and
+/// don't need the same masking — the misclassification was Linux-only.
+#[cfg(target_os = "linux")]
+pub(crate) const DRIVER_SENSE: u16 = 0x08;
+
 // ── Types ───────────────────────────────────────────────────────────────────

 #[derive(Debug, Clone, Copy, PartialEq)]
@@ -102,9 +334,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 ───────────────────────────────
 //
@@ -326,3 +558,116 @@ pub fn build_read10_raw(lba: u32, count: u16) -> [u8; 10] {
        0x00,
    ]
 }
+
+#[cfg(test)]
+mod parse_sense_tests {
+    //! Unit tests for `parse_sense_key`. Covers both SPC-4 sense data
+    //! formats (descriptor / fixed) and the short-buffer fallback. The
+    //! same helper runs on every platform backend so a regression here
+    //! would silently miscategorize SCSI errors on Linux, macOS, and
+    //! Windows simultaneously.
+    use super::parse_sense;
+    fn parse_sense_key(sense: &[u8], sb_len_wr: u8) -> u8 {
+        parse_sense(sense, sb_len_wr).sense_key
+    }
+
+    /// Helper: build a 32-byte sense buffer whose first three bytes are
+    /// the given prefix; the rest are zeroes (sense data area).
+    fn buf(b0: u8, b1: u8, b2: u8) -> [u8; 32] {
+        let mut s = [0u8; 32];
+        s[0] = b0;
+        s[1] = b1;
+        s[2] = b2;
+        s
+    }
+
+    #[test]
+    fn descriptor_format_72_picks_byte_1() {
+        // Response code 0x72 (current, descriptor): sense key is the
+        // low nibble of byte 1. Byte 2 here is 0x77 to prove it is NOT
+        // the byte the parser reads.
+        let s = buf(0x72, 0x05, 0x77); // ILLEGAL REQUEST
+        assert_eq!(parse_sense_key(&s, 8), 5);
+    }
+
+    #[test]
+    fn descriptor_format_73_picks_byte_1() {
+        // Response code 0x73 (deferred, descriptor): same parse rule
+        // as 0x72.
+        let s = buf(0x73, 0x06, 0xFF); // UNIT ATTENTION
+        assert_eq!(parse_sense_key(&s, 8), 6);
+    }
+
+    #[test]
+    fn fixed_format_70_picks_byte_2() {
+        // Response code 0x70 (current, fixed): sense key is the low
+        // nibble of byte 2. Byte 1 is 0x77 to prove it is NOT read.
+        let s = buf(0x70, 0x77, 0x05); // ILLEGAL REQUEST
+        assert_eq!(parse_sense_key(&s, 18), 5);
+    }
+
+    #[test]
+    fn fixed_format_71_picks_byte_2() {
+        // Response code 0x71 (deferred, fixed): same parse as 0x70.
+        let s = buf(0x71, 0x77, 0x02); // NOT READY
+        assert_eq!(parse_sense_key(&s, 18), 2);
+    }
+
+    #[test]
+    fn high_bit_in_byte_0_is_masked() {
+        // SPC-4 sets the top bit of byte 0 ("INFORMATION VALID" / "VALID")
+        // independently of the response code. parse_sense_key must mask
+        // it off before classifying the format.
+        let s = buf(0xF2, 0x05, 0x77);
+        assert_eq!(
+            parse_sense_key(&s, 8),
+            5,
+            "VALID-bit must not leak into format detection"
+        );
+        let s = buf(0xF0, 0x77, 0x02);
+        assert_eq!(parse_sense_key(&s, 18), 2);
+    }
+
+    #[test]
+    fn high_nibble_in_key_byte_is_masked() {
+        // Sense key is byte_n & 0x0F (low nibble). Top nibble holds
+        // FILEMARK / EOM / ILI / SDAT_OVFL flags, which must not bleed
+        // into the key value.
+        let s = buf(0x70, 0x00, 0xE5); // 0xE0 flags + key 5
+        assert_eq!(parse_sense_key(&s, 18), 5);
+    }
+
+    #[test]
+    fn sb_len_wr_zero_returns_no_sense() {
+        // Transport set status non-zero but wrote zero sense bytes —
+        // SPC-4 §4.5.3 says treat as NO SENSE (key 0).
+        let s = buf(0x72, 0x05, 0x05);
+        assert_eq!(parse_sense_key(&s, 0), 0);
+    }
+
+    #[test]
+    fn sb_len_wr_below_three_returns_no_sense() {
+        // Less than three bytes in the buffer means we can't safely
+        // read either format byte 0 or key byte 2 — return 0.
+        let s = buf(0x72, 0x05, 0x05);
+        assert_eq!(parse_sense_key(&s, 1), 0);
+        assert_eq!(parse_sense_key(&s, 2), 0);
+    }
+
+    #[test]
+    fn slice_below_three_returns_no_sense() {
+        // Defense-in-depth: even if a caller passes a too-short slice
+        // with a falsely-large sb_len_wr, we don't panic and we return 0.
+        let s = [0x72u8, 0x05];
+        assert_eq!(parse_sense_key(&s, 8), 0);
+    }
+
+    #[test]
+    fn unknown_response_code_falls_through_to_fixed() {
+        // SPC-4 mandates implementations tolerate unknown response
+        // codes and treat them as fixed format. Vendor-specific codes
+        // in the 0x74..0x7E range surface here.
+        let s = buf(0x7A, 0x77, 0x03); // MEDIUM ERROR via "fixed"
+        assert_eq!(parse_sense_key(&s, 18), 3);
+    }
+}
@@ -87,6 +87,10 @@ pub struct SptiTransport {
    handle: isize,
 }

+// SptiTransport's only field is the isize HANDLE — Send is auto-derived
+// and intentional. Sync is NOT: handle mutation in execute() requires
+// &mut, enforced by the trait object dispatch.
+
 /// Normalize a device path to Windows \\.\X: format.
 ///
 /// NOTE: A near-identical `normalize_path` exists in `drive::windows`.
@@ -129,8 +133,17 @@ impl SptiTransport {
        };

        if handle == INVALID_HANDLE_VALUE {
-            return Err(Error::DeviceNotFound {
-                path: format!("{}: cannot open device (run as administrator)", dev_str),
+            // Map last-os-error → Error variant; don't embed English hints
+            // in the path field (the CLI handles localization).
+            let err = std::io::Error::last_os_error();
+            return Err(if err.kind() == std::io::ErrorKind::PermissionDenied {
+                Error::DevicePermission {
+                    path: dev_str.to_string(),
+                }
+            } else {
+                Error::DeviceNotFound {
+                    path: dev_str.to_string(),
+                }
            });
        }

@@ -215,15 +228,17 @@ pub(super) fn drive_has_disc(path: &Path) -> Result<bool> {
        crate::scsi::TUR_TIMEOUT_MS,
    ) {
        Ok(_) => Ok(true),
-        Err(Error::ScsiError { sense_key: 2, .. }) => Ok(false),
+        Err(ref e) if e.scsi_sense().is_some_and(|s| s.is_not_ready()) => Ok(false),
        Err(e) => Err(e),
    }
 }

 impl Drop for SptiTransport {
    fn drop(&mut self) {
-        unsafe {
-            CloseHandle(self.handle);
+        if self.handle != INVALID_HANDLE_VALUE {
+            unsafe {
+                CloseHandle(self.handle);
+            }
        }
    }
 }
@@ -254,7 +269,11 @@ impl ScsiTransport for SptiTransport {
            DataDirection::ToDevice => SCSI_IOCTL_DATA_OUT,
        };
        sptwb.spt.DataTransferLength = data.len() as u32;
-        sptwb.spt.TimeOutValue = (timeout_ms / 1000).max(1) as u32;
+        // Round up to the next whole second so a 1500ms request gets at
+        // least 2s, not 1s. SPTI's TimeOutValue is u32 seconds with no
+        // sub-second resolution; biasing toward "more time" is safer than
+        // truncating (truncation broke 1500ms fast-reads on Drive::read).
+        sptwb.spt.TimeOutValue = ((timeout_ms + 999) / 1000).max(1);
        sptwb.spt.DataBuffer = if data.is_empty() {
            std::ptr::null_mut()
        } else {
@@ -280,23 +299,34 @@ impl ScsiTransport for SptiTransport {
        };

        if ok == 0 {
+            // Driver-level failure (timeout, handle gone, etc.). Bubble
+            // up; in-library handle recovery was removed in 0.13.20 along
+            // with Linux's async fd-recovery and macOS's `try_recover` —
+            // the kernel mid-layer already did its escalation by the time
+            // DeviceIoControl returned, and re-issuing reset/reopen here
+            // is at best redundant and at worst deepens the wedge. Caller
+            // surfaces the failure to UX.
            return Err(Error::ScsiError {
                opcode: cdb[0],
-                status: 0xFF,
-                sense_key: 0,
+                status: super::SCSI_STATUS_TRANSPORT_FAILURE,
+                sense: None,
            });
        }

        if sptwb.spt.ScsiStatus != 0 {
-            let sense_key = if sptwb.sense[2] != 0 {
-                sptwb.sense[2] & 0x0F
-            } else {
-                0
-            };
+            // SPTI doesn't surface a "bytes written into sense buffer"
+            // count separate from SenseInfoLength (input). Pass the full
+            // K_SENSE_SIZE; parse_sense keys off byte 0's response code
+            // to handle descriptor (0x72/0x73) vs fixed (0x70/0x71).
+            //
+            // 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(&sptwb.sense, K_SENSE_SIZE as u8);
            return Err(Error::ScsiError {
                opcode: cdb[0],
                status: sptwb.spt.ScsiStatus,
-                sense_key,
+                sense: Some(parsed),
            });
        }

@@ -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([
@@ -175,17 +175,25 @@ fn test_disc_copy_progress_callback_fires() {

    let calls = Arc::new(AtomicU64::new(0));
    let last_bytes = Arc::new(AtomicU64::new(0));
-    let calls_cb = calls.clone();
-    let last_bytes_cb = last_bytes.clone();

-    let progress = move |bytes: u64, _total: u64| {
-        calls_cb.fetch_add(1, Ordering::Relaxed);
-        last_bytes_cb.store(bytes, Ordering::Relaxed);
+    struct CountingReporter {
+        calls: Arc<AtomicU64>,
+        last_bytes: Arc<AtomicU64>,
+    }
+    impl libfreemkv::progress::Progress for CountingReporter {
+        fn report(&self, p: &libfreemkv::progress::PassProgress) {
+            self.calls.fetch_add(1, Ordering::Relaxed);
+            self.last_bytes.store(p.bytes_good_total, Ordering::Relaxed);
+        }
+    }
+    let reporter = CountingReporter {
+        calls: calls.clone(),
+        last_bytes: last_bytes.clone(),
    };

    let opts = CopyOptions {
        decrypt: false,
-        on_progress: Some(&progress),
+        progress: Some(&reporter),
        ..Default::default()
    };

@@ -199,7 +207,10 @@ fn test_disc_copy_progress_callback_fires() {
    let n = calls.load(Ordering::Relaxed);
    let last = last_bytes.load(Ordering::Relaxed);
    assert!(n > 0, "on_progress should fire at least once, got {n}");
-    assert!(last > 0, "final progress bytes should be non-zero, got {last}");
+    assert!(
+        last > 0,
+        "final progress bytes should be non-zero, got {last}"
+    );
 }

 // ── 3. Halt aborts disc copy promptly ─────────────────────────────────────
@@ -335,3 +346,290 @@ fn test_file_sector_reader_round_trip() {
    assert_eq!(n, N_SECTORS * SECTOR_SIZE);
    assert_eq!(all, data, "bulk read mismatch");
 }
+
+// ── 6. Pass 1 sweeps the entire disc even when every read fails ───────────
+//
+// 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` 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)
+//   - bytes_good = 0
+//   - bytes_pending = total_bytes (NonTrimmed counts as pending in mapfile
+//     accounting; see disc/mapfile.rs::stats)
+//   - bytes_unreadable = 0 (only Pass 2 marks Unreadable)
+//   - complete = false (work remains for Pass 2)
+//   - halted = false (no user stop)
+//   - ISO file is `total_bytes` size on disk (sparse zeros)
+
+/// Reader that returns Err for every read. Optionally signals a halt
+/// flag on the first read so tests can exercise the halt-during-skip-forward
+/// path deterministically (no wallclock dependency).
+struct FailingSectorReader {
+    capacity: u32,
+    /// If set, signals halt on the first `read_sectors` call. Cleared after
+    /// the first signal so subsequent reads are plain Err.
+    halt_on_first_read: Option<Arc<AtomicBool>>,
+}
+
+impl FailingSectorReader {
+    fn new(capacity: u32) -> Self {
+        Self {
+            capacity,
+            halt_on_first_read: None,
+        }
+    }
+
+    fn with_halt_on_first_read(capacity: u32, halt: Arc<AtomicBool>) -> Self {
+        Self {
+            capacity,
+            halt_on_first_read: Some(halt),
+        }
+    }
+}
+
+impl SectorReader for FailingSectorReader {
+    fn read_sectors(
+        &mut self,
+        _lba: u32,
+        _count: u16,
+        _buf: &mut [u8],
+        _recovery: bool,
+    ) -> Result<usize> {
+        if let Some(h) = self.halt_on_first_read.take() {
+            h.store(true, Ordering::Relaxed);
+        }
+        // Model what a real damaged-disc read returns: CHECK CONDITION +
+        // MEDIUM ERROR (sense_key 3, ASC 0x11 UNRECOVERED READ ERROR,
+        // ASCQ 0x05 L-EC UNCORRECTABLE). Disc::copy's hysteresis must
+        // engage on this — `Error::DiscRead` is libfreemkv's own
+        // post-classification signal, not what a real reader emits.
+        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: 0x05,
+            }),
+        })
+    }
+
+    fn capacity(&self) -> u32 {
+        self.capacity
+    }
+}
+
+#[test]
+fn test_disc_copy_completes_full_disc_with_failing_reader() {
+    // 1024 sectors = 2 MB. Reader fails every read. With skip_on_error +
+    // 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;
+
+    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,
+        skip_on_error: true,
+
+        ..Default::default()
+    };
+
+    let t0 = Instant::now();
+    let result = disc
+        .copy(&mut reader, &iso_path, &opts)
+        .expect("copy returns Ok");
+    let elapsed = t0.elapsed();
+
+    // Cleanup
+    let _ = std::fs::remove_file(&iso_path);
+    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).
+    assert!(
+        elapsed < Duration::from_secs(5),
+        "Pass 1 took {elapsed:?} on a 2 MB synthetic disc — expected < 5 s"
+    );
+
+    // Per RIP_DESIGN.md §2.1: Pass 1 must reach end of disc regardless of
+    // read outcomes.
+    assert_eq!(
+        result.bytes_total, total_bytes,
+        "bytes_total must match disc capacity"
+    );
+    assert_eq!(
+        result.bytes_good, 0,
+        "no reads succeeded, bytes_good must be 0"
+    );
+    assert_eq!(
+        result.bytes_unreadable, 0,
+        "Pass 1 does not mark Unreadable; only Pass 2 (Disc::patch) does"
+    );
+    assert_eq!(
+        result.bytes_pending, total_bytes,
+        "every sector must be NonTrimmed → counted as pending. \
+         Got bytes_pending={} of total {}",
+        result.bytes_pending, total_bytes
+    );
+    assert!(
+        !result.complete,
+        "complete=false because NonTrimmed regions remain (work for Pass 2)"
+    );
+    assert!(!result.halted, "no halt was set; halted must be false");
+
+    // ISO file should be the full disc size on disk (sparse zeros where
+    // reads failed).
+    // Note: tempfile was dropped above; the file may or may not still exist
+    // depending on cleanup ordering. We only assert what we can observe in
+    // the CopyResult.
+}
+
+// ── 7. Halt during Pass 1 skip-forward path returns promptly (deterministic) ─
+//
+// Per RIP_DESIGN.md §3: halt is the only legitimate early exit from Pass 1.
+// Even when every read is failing (skip-forward path), a halt must be
+// honored within a small bounded time.
+//
+// Deterministic fixture: the reader signals halt on its FIRST read. The
+// inner copy loop's halt check fires on the next iteration, breaking out
+// of 'outer. This avoids any wallclock race on fast CI runners (where a
+// 2 GB synthetic disc can sweep skip-forward in <100 ms).
+
+#[test]
+fn test_disc_copy_halts_promptly_on_failing_reader() {
+    let capacity_sectors: u32 = 1024 * 1024; // 2 GB synthetic disc
+
+    let halt = Arc::new(AtomicBool::new(false));
+    let mut reader = FailingSectorReader::with_halt_on_first_read(capacity_sectors, halt.clone());
+    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,
+        skip_on_error: true,
+
+        halt: Some(halt),
+        ..Default::default()
+    };
+
+    let t0 = Instant::now();
+    let result = disc
+        .copy(&mut reader, &iso_path, &opts)
+        .expect("copy returns Ok on halt");
+    let elapsed = t0.elapsed();
+
+    // Cleanup
+    let _ = std::fs::remove_file(&iso_path);
+    let _ = std::fs::remove_file(libfreemkv::disc::mapfile_path_for(&iso_path));
+
+    assert!(
+        elapsed < Duration::from_secs(2),
+        "halt must return within 2 s; took {elapsed:?}"
+    );
+    assert!(result.halted, "result.halted must be true");
+    assert!(
+        !result.complete,
+        "halted run cannot be complete (bytes_pending > 0 expected)"
+    );
+    assert!(
+        result.bytes_pending > 0,
+        "halt fired before sweep completed; bytes_pending must be > 0"
+    );
+}
+
+// ── 8. Hysteresis recovers data the drive can read individually ──────────
+//
+// 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,
+}
+
+impl SectorReader for BlockSizeFailingReader {
+    fn read_sectors(
+        &mut self,
+        lba: u32,
+        count: u16,
+        buf: &mut [u8],
+        _recovery: bool,
+    ) -> Result<usize> {
+        if count == 1 {
+            for chunk in buf.chunks_mut(SECTOR_SIZE) {
+                chunk.fill((lba & 0xff) as u8);
+            }
+            Ok(buf.len())
+        } else {
+            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,
+                }),
+            })
+        }
+    }
+
+    fn capacity(&self) -> u32 {
+        self.capacity
+    }
+}
+
+#[test]
+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;
+
+    let mut reader = BlockSizeFailingReader {
+        capacity: 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,
+        skip_on_error: true,
+        ..Default::default()
+    };
+
+    let result = disc
+        .copy(&mut reader, &iso_path, &opts)
+        .expect("copy returns Ok");
+
+    let _ = std::fs::remove_file(&iso_path);
+    let _ = std::fs::remove_file(libfreemkv::disc::mapfile_path_for(&iso_path));
+
+    assert_eq!(
+        result.bytes_good, 0,
+        "Pass 1 should have 0 bytes_good when all batch reads fail. Got {} of {}",
+        result.bytes_good, total_bytes
+    );
+    assert!(
+        result.bytes_pending > 0,
+        "all sectors should be NonTrimmed pending Pass 2"
+    );
+    assert!(
+        !result.complete,
+        "complete=false when sectors remain NonTrimmed"
+    );
+}
@@ -0,0 +1,391 @@
+//! Integration tests for the SCSI error-decoding contract.
+//!
+//! v0.13.20 rewrote `scsi/linux.rs` to a synchronous blocking SG_IO and
+//! consolidated sense parsing into the `parse_sense` helper that every
+//! platform backend now shares. v0.13.23 replaced the `Error::ScsiError`
+//! flat-fields shape with `{ opcode, status, sense: Option<ScsiSense> }`
+//! so callers can route on structured sense data (key + ASC + ASCQ) via
+//! [`Error::scsi_sense`] / [`Error::is_marginal_read`] /
+//! [`ScsiSense::is_*`].
+//!
+//! The actual `ioctl(SG_IO, ...)` call is impossible to mock without a
+//! kernel — see
+//! `(internal)/docs/audits/2026-04-26-scsi-architecture-research.md`
+//! for why the audit recommends against libc shims here. These tests
+//! therefore pin the *contract* every backend must satisfy via a mock
+//! `ScsiTransport`:
+//!
+//!   1. Healthy result → `Ok(ScsiResult { bytes_transferred = data.len() - resid })`.
+//!   2. Transport-level failure (no SCSI status delivered: kernel
+//!      timeout, USB bridge wedge, IOKit service error) →
+//!      `Error::ScsiError { status: SCSI_STATUS_TRANSPORT_FAILURE, sense: None }`.
+//!      `Error::is_scsi_transport_failure()` returns `true`. Used by
+//!      `drive_has_disc` to detect the wedge signature.
+//!   3. SCSI-level failure (drive replied CHECK CONDITION with sense) →
+//!      `Error::ScsiError { status: 0x02, sense: Some(ScsiSense {…}) }`
+//!      with the parsed key/ASC/ASCQ.
+//!   4. `Error::is_marginal_read()` is `true` for MEDIUM ERROR /
+//!      ABORTED COMMAND / RECOVERED ERROR / NO SENSE; `false` for
+//!      HARDWARE / DATA PROTECT / UNIT ATTENTION / NOT READY / ILLEGAL
+//!      REQUEST and for transport failures.
+//!
+//! Inline `parse_sense_tests` in `src/scsi/mod.rs` cover the pure parse
+//! logic (descriptor 0x72/0x73 vs fixed 0x70/0x71, short-buffer, VALID
+//! bit masking, unknown response codes, ASC/ASCQ offsets); this file
+//! covers the consumer side — a real transport feeding a real Error
+//! variant to a real call site (`scsi::inquiry`).
+
+use libfreemkv::error::Error;
+use libfreemkv::scsi::{
+    DataDirection, SCSI_STATUS_CHECK_CONDITION, SCSI_STATUS_TRANSPORT_FAILURE,
+    SENSE_KEY_ABORTED_COMMAND, SENSE_KEY_DATA_PROTECT, SENSE_KEY_HARDWARE_ERROR,
+    SENSE_KEY_ILLEGAL_REQUEST, SENSE_KEY_MEDIUM_ERROR, SENSE_KEY_NOT_READY,
+    SENSE_KEY_RECOVERED_ERROR, SENSE_KEY_UNIT_ATTENTION, ScsiResult, ScsiSense, ScsiTransport,
+};
+
+/// A scripted ScsiTransport. Each `execute()` consumes the next entry
+/// from `script` and returns the corresponding outcome.
+///
+/// Outcomes mirror what each backend's `execute()` should produce after
+/// the v0.13.23 sense plumbing: `Option<ScsiSense>` carrying the full
+/// SPC-4 triple for drive-reported failures, `None` for transport-level
+/// failures.
+struct MockTransport {
+    script: Vec<MockOutcome>,
+    next: usize,
+}
+
+#[derive(Clone)]
+enum MockOutcome {
+    /// Healthy completion. `data` is what the transport wrote into the
+    /// caller's data buffer (truncated to the buffer length); `resid`
+    /// is reported back as `data.len() - bytes_transferred`.
+    Ok { data: Vec<u8>, resid: i32 },
+    /// Transport-level failure: `hdr.host_status = DID_TIME_OUT` on
+    /// Linux, `kIOReturnError` on macOS, `DeviceIoControl` returning 0
+    /// on Windows. Backends synthesise `SCSI_STATUS_TRANSPORT_FAILURE`
+    /// with `sense = None`.
+    TransportFailure,
+    /// Drive replied with sense data (typically `SCSI_STATUS_CHECK_CONDITION`
+    /// + a populated sense buffer).
+    ScsiFailure { status: u8, sense: ScsiSense },
+}
+
+impl MockTransport {
+    fn new(script: Vec<MockOutcome>) -> Self {
+        Self { script, next: 0 }
+    }
+}
+
+impl ScsiTransport for MockTransport {
+    fn execute(
+        &mut self,
+        cdb: &[u8],
+        _direction: DataDirection,
+        data: &mut [u8],
+        _timeout_ms: u32,
+    ) -> libfreemkv::error::Result<ScsiResult> {
+        let i = self.next;
+        self.next += 1;
+        let outcome = self
+            .script
+            .get(i)
+            .cloned()
+            .expect("MockTransport script ran out — test wrote fewer outcomes than calls");
+        match outcome {
+            MockOutcome::Ok { data: d, resid } => {
+                let n = d.len().min(data.len());
+                data[..n].copy_from_slice(&d[..n]);
+                let bytes = (data.len() as i32).saturating_sub(resid).max(0) as usize;
+                Ok(ScsiResult {
+                    status: 0,
+                    bytes_transferred: bytes,
+                    sense: [0u8; 32],
+                })
+            }
+            MockOutcome::TransportFailure => Err(Error::ScsiError {
+                opcode: cdb[0],
+                status: SCSI_STATUS_TRANSPORT_FAILURE,
+                sense: None,
+            }),
+            MockOutcome::ScsiFailure { status, sense } => Err(Error::ScsiError {
+                opcode: cdb[0],
+                status,
+                sense: Some(sense),
+            }),
+        }
+    }
+}
+
+/// Helper — build a CHECK CONDITION outcome with a given sense key
+/// and zero ASC/ASCQ. Most consumer-side tests only care about the key.
+fn check_cond(sense_key: u8) -> MockOutcome {
+    MockOutcome::ScsiFailure {
+        status: SCSI_STATUS_CHECK_CONDITION,
+        sense: ScsiSense {
+            sense_key,
+            asc: 0,
+            ascq: 0,
+        },
+    }
+}
+
+// ── 1. Healthy read ───────────────────────────────────────────────────────
+
+#[test]
+fn test_healthy_inquiry_returns_ok_with_full_transfer() {
+    // Build a fake INQUIRY response (96 bytes per scsi::inquiry).
+    // Vendor "TEST-VND", model "TEST-MODEL ", firmware "1.00".
+    let mut payload = vec![0u8; 96];
+    payload[8..16].copy_from_slice(b"TEST-VND");
+    payload[16..32].copy_from_slice(b"TEST-MODEL      ");
+    payload[32..36].copy_from_slice(b"1.00");
+
+    let mut transport = MockTransport::new(vec![MockOutcome::Ok {
+        data: payload,
+        resid: 0,
+    }]);
+
+    let r = libfreemkv::scsi::inquiry(&mut transport).expect("inquiry should succeed");
+    assert_eq!(r.vendor_id, "TEST-VND");
+    assert_eq!(r.model, "TEST-MODEL");
+    assert_eq!(r.firmware, "1.00");
+}
+
+// ── 2. Transport-level failure: no SCSI status, no sense data ─────────────
+
+#[test]
+fn test_transport_failure_surfaces_with_sense_none() {
+    let mut transport = MockTransport::new(vec![MockOutcome::TransportFailure]);
+
+    let err = libfreemkv::scsi::inquiry(&mut transport).unwrap_err();
+    assert!(
+        err.is_scsi_transport_failure(),
+        "TransportFailure must satisfy is_scsi_transport_failure()"
+    );
+    assert!(
+        err.scsi_sense().is_none(),
+        "transport failure has no sense data"
+    );
+    assert!(
+        !err.is_marginal_read(),
+        "transport failure must not be classified as marginal-read"
+    );
+    match err {
+        Error::ScsiError { status, sense, .. } => {
+            assert_eq!(status, SCSI_STATUS_TRANSPORT_FAILURE);
+            assert!(sense.is_none());
+        }
+        other => panic!("expected ScsiError, got {other:?}"),
+    }
+}
+
+// ── 3. CHECK CONDITION + ILLEGAL REQUEST ──────────────────────────────────
+
+#[test]
+fn test_check_cond_illegal_request_carries_sense() {
+    let mut transport = MockTransport::new(vec![check_cond(SENSE_KEY_ILLEGAL_REQUEST)]);
+    let err = libfreemkv::scsi::inquiry(&mut transport).unwrap_err();
+
+    let sense = err.scsi_sense().expect("CHECK CONDITION must carry sense");
+    assert_eq!(sense.sense_key, SENSE_KEY_ILLEGAL_REQUEST);
+    assert!(sense.is_illegal_request());
+    assert!(!err.is_marginal_read(), "ILLEGAL REQUEST is not marginal");
+    assert!(!err.is_scsi_transport_failure());
+}
+
+// ── 4. CHECK CONDITION + NOT READY (drive_has_disc relies on this) ────────
+
+#[test]
+fn test_check_cond_not_ready_predicate() {
+    let mut transport = MockTransport::new(vec![check_cond(SENSE_KEY_NOT_READY)]);
+    let err = libfreemkv::scsi::inquiry(&mut transport).unwrap_err();
+
+    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");
+}
+
+// ── 5. CHECK CONDITION + MEDIUM ERROR (canonical marginal-read) ───────────
+
+#[test]
+fn test_check_cond_medium_error_is_marginal() {
+    let mut transport = MockTransport::new(vec![check_cond(SENSE_KEY_MEDIUM_ERROR)]);
+    let err = libfreemkv::scsi::inquiry(&mut transport).unwrap_err();
+
+    let sense = err.scsi_sense().expect("CHECK CONDITION must carry sense");
+    assert!(sense.is_medium_error());
+    assert!(sense.is_marginal());
+    assert!(
+        err.is_marginal_read(),
+        "MEDIUM ERROR is the canonical marginal-read signal"
+    );
+}
+
+// ── 6. CHECK CONDITION + ABORTED COMMAND (also marginal) ──────────────────
+
+#[test]
+fn test_check_cond_aborted_command_is_marginal() {
+    let mut transport = MockTransport::new(vec![check_cond(SENSE_KEY_ABORTED_COMMAND)]);
+    let err = libfreemkv::scsi::inquiry(&mut transport).unwrap_err();
+
+    let sense = err.scsi_sense().expect("CHECK CONDITION must carry sense");
+    assert!(sense.is_aborted_command());
+    assert!(err.is_marginal_read(), "ABORTED COMMAND is marginal");
+}
+
+// ── 7. CHECK CONDITION + RECOVERED ERROR (drive recovered; marginal) ──────
+
+#[test]
+fn test_check_cond_recovered_error_is_marginal() {
+    let mut transport = MockTransport::new(vec![check_cond(SENSE_KEY_RECOVERED_ERROR)]);
+    let err = libfreemkv::scsi::inquiry(&mut transport).unwrap_err();
+    assert!(
+        err.is_marginal_read(),
+        "RECOVERED ERROR is treated as marginal (drive recovered, retry-friendly class)"
+    );
+}
+
+// ── 8. CHECK CONDITION + HARDWARE ERROR (NOT marginal — bail) ─────────────
+
+#[test]
+fn test_check_cond_hardware_error_not_marginal() {
+    let mut transport = MockTransport::new(vec![check_cond(SENSE_KEY_HARDWARE_ERROR)]);
+    let err = libfreemkv::scsi::inquiry(&mut transport).unwrap_err();
+
+    let sense = err.scsi_sense().expect("CHECK CONDITION must carry sense");
+    assert!(sense.is_hardware_error());
+    assert!(
+        !err.is_marginal_read(),
+        "HARDWARE ERROR must not be marginal — drive failing, retry can't help"
+    );
+}
+
+// ── 9. CHECK CONDITION + DATA PROTECT (NOT marginal — bail) ───────────────
+
+#[test]
+fn test_check_cond_data_protect_not_marginal() {
+    let mut transport = MockTransport::new(vec![check_cond(SENSE_KEY_DATA_PROTECT)]);
+    let err = libfreemkv::scsi::inquiry(&mut transport).unwrap_err();
+
+    let sense = err.scsi_sense().expect("CHECK CONDITION must carry sense");
+    assert!(sense.is_data_protect());
+    assert!(
+        !err.is_marginal_read(),
+        "DATA PROTECT (AACS / region) must not be marginal — retry can't help"
+    );
+}
+
+// ── 10. CHECK CONDITION + UNIT ATTENTION (NOT marginal — caller rescans) ──
+
+#[test]
+fn test_check_cond_unit_attention_not_marginal() {
+    let mut transport = MockTransport::new(vec![check_cond(SENSE_KEY_UNIT_ATTENTION)]);
+    let err = libfreemkv::scsi::inquiry(&mut transport).unwrap_err();
+
+    let sense = err.scsi_sense().expect("CHECK CONDITION must carry sense");
+    assert!(sense.is_unit_attention());
+    assert!(
+        !err.is_marginal_read(),
+        "UNIT ATTENTION must not be marginal — caller should rescan, not retry"
+    );
+}
+
+// ── 11. ASC/ASCQ propagate from sense buffer to ScsiError.sense ───────────
+
+#[test]
+fn test_asc_ascq_round_trip_through_error() {
+    let outcome = MockOutcome::ScsiFailure {
+        status: SCSI_STATUS_CHECK_CONDITION,
+        sense: ScsiSense {
+            sense_key: SENSE_KEY_MEDIUM_ERROR,
+            asc: 0x11,
+            ascq: 0x05, // L-EC UNCORRECTABLE
+        },
+    };
+    let mut transport = MockTransport::new(vec![outcome]);
+    let err = libfreemkv::scsi::inquiry(&mut transport).unwrap_err();
+
+    let sense = err.scsi_sense().expect("must carry sense");
+    assert_eq!(sense.sense_key, SENSE_KEY_MEDIUM_ERROR);
+    assert_eq!(sense.asc, 0x11);
+    assert_eq!(sense.ascq, 0x05);
+}
+
+// ── 12. Healthy short transfer (resid > 0) ────────────────────────────────
+
+#[test]
+fn test_healthy_short_transfer_reports_partial_bytes() {
+    // Transport reported back fewer bytes than requested (resid = 16).
+    // For a 96-byte buffer that means bytes_transferred = 80.
+    let payload = vec![0u8; 96];
+    let mut transport = MockTransport::new(vec![MockOutcome::Ok {
+        data: payload,
+        resid: 16,
+    }]);
+
+    let cdb = [libfreemkv::scsi::SCSI_INQUIRY, 0, 0, 0, 0x60, 0];
+    let mut buf = [0u8; 96];
+    let r = transport
+        .execute(&cdb, DataDirection::FromDevice, &mut buf, 1_000)
+        .expect("ok");
+    assert_eq!(r.status, 0);
+    assert_eq!(
+        r.bytes_transferred, 80,
+        "bytes_transferred must equal data.len() - resid"
+    );
+}
+
+// ── 13. Error::Display does not leak English in the SCSI variant ──────────
+//
+// Library rule (project docs): no English in error display, only "E{code}"
+// + structured data. Regression guard for the SCSI variant specifically
+// because it's the most-emitted error in the rip path.
+
+#[test]
+fn test_scsi_error_display_format_is_codes_only() {
+    let err = Error::ScsiError {
+        opcode: 0x12,
+        status: SCSI_STATUS_CHECK_CONDITION,
+        sense: Some(ScsiSense {
+            sense_key: SENSE_KEY_ILLEGAL_REQUEST,
+            asc: 0x24,
+            ascq: 0x00,
+        }),
+    };
+    let s = err.to_string();
+    assert!(
+        s.starts_with("E4000:"),
+        "ScsiError must lead with E4000: {s}"
+    );
+    assert!(
+        s.contains("0x12") && s.contains("0x02") && s.contains("0x05") && s.contains("0x24"),
+        "ScsiError must show opcode/status/key/asc in hex: {s}"
+    );
+    // Crude English filter — same as the inline error.rs::display test.
+    for word in s.split(|c: char| !c.is_ascii_alphabetic()) {
+        assert!(
+            word.len() <= 4,
+            "ScsiError display contains suspicious word `{word}`: {s}"
+        );
+    }
+}
+
+// ── 14. Transport-failure Display omits sense fields ──────────────────────
+
+#[test]
+fn test_scsi_transport_failure_display_short_form() {
+    let err = Error::ScsiError {
+        opcode: 0x28,
+        status: SCSI_STATUS_TRANSPORT_FAILURE,
+        sense: None,
+    };
+    let s = err.to_string();
+    assert!(s.starts_with("E4000:"));
+    assert!(s.contains("0x28") && s.contains("0xff"));
+    // No sense triple should appear in the no-sense form.
+    assert!(
+        !s.contains("0x00/0x00/0x00"),
+        "transport failure must not carry phantom sense: {s}"
+    );
+}
@@ -0,0 +1,115 @@
+//! 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 libfreemkv::scsi::{DataDirection, SCSI_STATUS_TRANSPORT_FAILURE};
+use std::path::Path;
+use std::time::Duration;
+
+#[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 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");
+    }
+}