sandcrawler 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: e23c0fbd03d38450155ff6452cda9ef0ea2df57a62510d14ff6b1dd0e7e0b7f5
+  data.tar.gz: 8ca4a9276f597ee1287680311337ba9cc8d7ce56ae003bee26835a8a1448de5c
+SHA512:
+  metadata.gz: 49b59f162a6edfc9dcc2aee9a08053d3f1fa51c065f85dffe196ef71e892c4a6dec0c7bf39c6bfb4305c421ec027d32508949ee50935306da53f941cc63ceea5
+  data.tar.gz: b9fcf2b93c4da162d72f889492c00f3b5518b91973713c3cc61e0611c489d4954be437e6a37d7f65adf2ef288c20caee392af52d5a716261356da0df005583c7

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0 (unreleased)
+
+- Initial release.

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,157 @@
+# Sandcrawler
+
+**Take a flash dump before using `flash_nuke.uf2`, reinstalling R2P2, or formatting a drive.** These operations can overwrite the files you want to recover. Keep the original dump and a second copy on another disk.
+
+Sandcrawler salvages files from Raspberry Pi Pico / Pico W (RP2040) and Pico 2 / Pico 2 W (RP2350) flash images. It reads FAT12, FAT16, FAT32, and long filenames (including Japanese), and recovers deleted files, orphaned cluster chains, and text fragments.
+
+Sandcrawler does not repair or write to the device. Its picotool adapter permits only `version`, `info`, and `save`. Hardware and VM compatibility still require the checks in [docs/findings.md](docs/findings.md).
+
+## Install
+
+Ruby 3.1 or newer is required. The core has no runtime gem dependencies. From this checkout:
+
+```sh
+gem build sandcrawler.gemspec
+gem install ./sandcrawler-0.1.0.gem
+sandcrawler --version
+```
+
+Install [picotool](https://github.com/raspberrypi/picotool) separately for flash acquisition; RP2350 requires picotool 2.x. Set `PICOTOOL=/path/to/picotool` or pass `--picotool /path/to/picotool` to choose an executable. The serial route additionally needs `gem install serialport`.
+
+## Recover a device
+
+Prefer BOOTSEL acquisition, which does not need R2P2 to start. Hold BOOTSEL while connecting the board, then:
+
+```sh
+sandcrawler doctor
+sandcrawler dump -o ./rescue
+sandcrawler scan ./rescue/dump.bin
+sandcrawler ls ./rescue/dump.bin --long --deleted
+sandcrawler extract ./rescue/dump.bin -o ./rescue/out --deleted --orphans
+```
+
+`dump` reads twice by default and compares SHA-256 hashes. If they differ, it reads once more and chooses the strict majority for each 4 KiB block. Every pass is retained. Blocks without a majority are listed in `dump.json` and cause exit code 5; producing an image does not imply its contents are reliable. `dump.bin` is made read-only and has a companion `dump.bin.sha256` file.
+
+Each picotool command has a 120-second timeout and a 1 MiB limit on each of stdout and stderr. If a failed save produced bytes, they are retained as `passN-all-failed.bin` or `passN-range-failed.bin` with an `acquisition_error` record and hash. Missing required hashes or acquisition metadata cause an integrity error.
+
+`scan` reports all plausible volumes with offsets and scores. `ls` and `extract` choose the highest-ranked candidate unless `--offset` selects another. `auto -o ./rescue` offers interactive route selection and runs acquisition and extraction together.
+
+If BOOTSEL is unavailable and the mounted R2P2 volume is readable:
+
+```sh
+sandcrawler copy /mnt/r2p2 -o ./copied
+```
+
+Use a read-only mount (`mount -o ro` on Linux). Although Sandcrawler only reads the source, the operating system may write hidden metadata to writable removable volumes. Symlinks are skipped. Keep the destination outside the source volume.
+
+Detected file changes during copying produce `SOURCE_CHANGED` warnings and a partial-success result. Copying a running filesystem does not provide a consistent snapshot.
+
+For a running R2P2 shell on CDC0:
+
+```sh
+sandcrawler serial --port /dev/ttyACM0 -o ./serial-copy
+```
+
+Without `--port`, the CLI lists candidates and asks for a selection. Choose the shell port, not debug or MIDI. Serial acquisition interrupts `app.rb`, enters IRB, probes APIs, and verifies hexadecimal chunks against a byte count and checksum. Session-specific marker tokens distinguish protocol responses from unrelated output. Failed transfers are retried up to three attempts. Device startup and unrelated running software can still alter flash; use BOOTSEL when possible.
+
+Serial requests have a 10-second idle timeout and a one-hour total deadline. Each request accepts at most 65,537 response records and 40 MiB of encoded responses, supporting files up to 16 MiB with the fixed 256-byte chunks. Incomplete listings, duplicate names, invalid frames, and oversized responses are rejected. These limits are built in; there are no CLI options to increase them.
+
+## Commands and options
+
+| Command | Purpose |
+|---|---|
+| `doctor` | Check Ruby, picotool, USB access, and optional serial support |
+| `dump -o DIR` | Read flash; `--passes N` sets the initial read count (default 2) |
+| `scan IMAGE` | Rank FAT candidates in raw or UF2 images |
+| `ls IMAGE` | List files; `--long` adds metadata, `--deleted` includes deleted entries |
+| `extract IMAGE -o DIR` | Extract files; `--deleted`, `--orphans`, and `--carve` enable recovery |
+| `copy MOUNTPOINT -o DIR` | Copy a mounted volume with hashes |
+| `serial -o DIR [--port PORT]` | Copy through the R2P2 shell |
+| `auto -o DIR` | Choose a route interactively |
+
+`--help` lists options. `--json` emits machine-readable results, `--verbose` adds diagnostics, and `--quiet` suppresses routine progress. `--force` permits a nonempty destination; use a new output directory to preserve earlier recovery results unchanged.
+
+| Image option | Meaning |
+|---|---|
+| `--offset N` | Volume byte offset, decimal or `0x` hexadecimal |
+| `--fat 1` / `--fat 2` | Force a FAT copy; otherwise erased sectors may fall back to the other copy |
+| `--codepage NAME` | Short filename encoding (default `IBM437`; for example `CP932`) |
+| `--reference-image FILE` | Borrow geometry from a healthy image with the same firmware and layout |
+| `--geometry KEY=VALUE,...` | Supply geometry when the boot sector is damaged |
+
+## Damaged volumes
+
+Try a healthy reference dump from a **separate test board** with the same firmware and flash layout:
+
+```sh
+sandcrawler extract broken.bin -o ./with-reference --reference-image healthy.bin
+```
+
+Manual geometry requires `bps` (bytes per sector), `spc` (sectors per cluster), `rsvd` (reserved sectors), `fats` (copy count), `fatsz` (sectors per FAT), and `root` (FAT12/16 root entry count, or zero for FAT32). Optional keys are `offset` (byte offset), `total` or `totsec` (total sectors, otherwise inferred from remaining image size), `root_cluster` (FAT32, default 2), and `media` (default 248). The following values are illustrative; substitute measured geometry:
+
+```sh
+sandcrawler extract broken.bin -o ./manual \
+  --geometry bps=4096,spc=1,rsvd=1,fats=2,fatsz=1,root=128,total=256,offset=0x100000
+sandcrawler extract broken.bin -o ./carved --carve
+```
+
+Missing fields, duplicate keys, conflicting `total`/`totsec`, and invalid geometry produce usage error 2. When a FAT32 backup boot sector has matching FAT copies and a plausible root entry, detection can recover the volume's original offset and records a `BACKUP_BOOT_SECTOR` warning.
+
+With no readable volume, `--carve` searches the whole image. Deleted-file recovery assumes consecutive free clusters and stops before allocated data. Original fragmentation and overwritten bytes cannot be reconstructed reliably. Orphan chains have no authoritative filename or length, so final clusters can include padding. Carving groups adjacent valid UTF-8 blocks with at least 95% printable characters; it cannot establish file boundaries or recover arbitrary binaries. Inspect every recovery result.
+
+## Results
+
+```text
+out/
+  files/           live files; .partial suffix when incomplete
+  deleted/         best-effort undeleted files
+  lost+found/      unreferenced chains
+  carved/          text fragments
+  manifest.json    provenance, paths, hashes, statuses, warnings
+  sandcrawler.log  diagnostics
+```
+
+The manifest records the source image's SHA-256 and size, geometry and FAT selection, original names, safe output paths, hashes, timestamps, attributes, and warnings. Its `directories` list also records directory metadata and creation failures. Invalid FAT timestamps are `null`. Unsafe path components, Windows reserved names, and case-insensitive collisions are renamed; original names remain in the manifest. Invalid UTF-8 path and name bytes are preserved in companion `_hex` fields. Console diagnostics escape control characters.
+
+`ok` means no read/structure error was detected, not that historical contents are proven intact. `truncated` and `chain_error` identify incomplete or broken chains; `suspect_erased` identifies all-`0xFF` clusters. `read_error` records an unreadable file or carving block; readable prefixes are preserved and other files or blocks are still attempted. Recovery warnings explain assumptions. Keep the source image after extraction.
+
+Extraction rechecks the image and any reference image against their original SHA-256 hashes before finishing. A changed or unreadable input produces `SOURCE_CHANGED` and exit code 5; recovered files and the failure manifest remain available for inspection.
+
+| Exit code | Meaning |
+|---|---|
+| 0 | Success |
+| 1 | General error |
+| 2 | Invalid usage |
+| 3 | Device unavailable |
+| 4 | Partial success; inspect statuses and warnings |
+| 5 | Integrity error, including unresolved dump disagreement or changed extraction input |
+
+## Troubleshooting
+
+| Symptom | Next step |
+|---|---|
+| No device | Check BOOTSEL, a data-capable cable, and USB permissions; Linux may need picotool's udev rules |
+| Different dump hashes | Connect directly without a hub, retain all passes, and inspect unstable blocks |
+| No FAT candidate | Check the offset, use matching reference geometry, then try carving |
+| Garbled short filename | Try the firmware's code page, such as `CP932` |
+| Partial files | Inspect `lost+found/` and `carved/`; keep the original image |
+| Serial timeout / unsupported API | Check CDC0 and firmware/VM details; use BOOTSEL if available |
+
+## Development
+
+```sh
+bundle install
+bundle exec rake test
+bundle exec rubocop
+bundle exec ruby exe/sandcrawler --version
+```
+
+Install dosfstools and mtools for independent integration fixtures (`brew install dosfstools mtools` or `sudo apt install dosfstools mtools`), with their executables on `PATH`. `rake test` builds missing fixtures when tools are available; otherwise it warns, runs synthetic unit tests, and skips external-fixture integration. Require full coverage with `REQUIRE_FIXTURES=1 bundle exec rake test`.
+
+`script/build_fixtures.sh` creates FAT12 with 512/4096-byte sectors, FAT16, FAT32, Japanese names, empty/multi-cluster files, deleted files, embedded volumes, and corruption cases. Expected trees come from `mcopy` and are checked against original content. Generated files are ignored by Git. CI generates on Ubuntu and shares fixtures with Ubuntu, macOS, and Windows jobs for Ruby 3.1 and maintained Ruby branches.
+
+See [software verification](docs/verification.md) for requirement coverage, adversarial cases, and the platforms actually exercised. Hardware acceptance is separate from image tests. Follow [the hardware checklist](docs/findings.md) before claiming a board/firmware/VM combination is validated. See [release instructions](docs/releasing.md) for publication checks.
+
+## License
+
+[MIT](LICENSE.txt).

data/docs/findings.md

@@ -0,0 +1,49 @@
+# Hardware findings and acceptance checklist
+
+Status: **not measured on physical hardware**. Synthetic images and mocked transports cannot answer the six questions below. No Pico has been flashed, erased, deliberately corrupted, or used for acquisition during implementation. Test offsets are not device measurements.
+
+## Open questions
+
+| Question | Current result | Evidence needed |
+|---|---|---|
+| FAT offset and size | Unverified; detected or supplied per image | Firmware, board, matching dumps, `scan --json` output |
+| Logical sector size | Unverified; parser accepts 512/1024/2048/4096 | Physical BPB and independently checked extraction hashes |
+| MBR presence | Unverified; scanner considers partition starts | MBR bytes, partition entries, selected offset |
+| Logical-to-physical mapping | Unverified; parser assumes linear mapping | Multi-cluster files match independent source hashes |
+| Startup flash writes | Unverified; do not assume boot preserves evidence | Before/after dumps around a controlled boot |
+| File/Dir APIs for each VM | Unverified; serial probes capabilities | Capability transcript and transfer hashes per firmware/VM |
+
+Nonlinear storage would require an additional mapping layer before raw recovery can be trusted. No mapping has been inferred from an untested firmware version.
+
+## Record each test
+
+Use a separate test board. Never experiment on the only recoverable copy of a device's data. Record:
+
+- Board, chip, flash capacity, firmware repository and exact release/commit, build settings, VM.
+- Host OS, Ruby/picotool versions, dump hashes, retained artifact location.
+- FAT offset/size/type, sector/cluster sizes, MBR result.
+- Original file hashes and hashes from each acquisition route.
+- Raw serial capability transcript, retries, missing APIs.
+- Flash blocks changed on startup, exact boot procedure, warnings, exit codes, observed losses.
+
+## Procedure
+
+1. On the test board only, install chosen firmware and create `home/app.rb`, nested directories, a Japanese filename, an empty file, and a 100 KB binary. Record their SHA-256 hashes on the host.
+2. Safely unmount, disconnect, reconnect in BOOTSEL, and run `sandcrawler dump -o before`. Require matching pass hashes.
+3. Run `scan before/dump.bin --json` and `extract before/dump.bin -o extracted`. Compare every output hash to the originals. This supplies evidence for geometry and linear mapping.
+4. On the test board only, boot normally and record what runs. Return to BOOTSEL, dump to `after`, and compare 4 KiB blocks. Record changed offsets and repeat only if needed for the experiment.
+5. Capture the serial capability output and copy via CDC0. Copy the read-only mounted volume separately. Compare both routes against originals and flash extraction.
+6. Delete a known file on the test board, dump again, and check `extract --deleted` against the original content.
+7. Only with expendable data and a disposable test board, interrupt a write and evaluate `--deleted --orphans --carve`. Record exact losses. Never run this experiment on a rescue target.
+
+## Acceptance matrix
+
+| Board | VM | BOOTSEL dump | Mounted copy | Serial copy |
+|---|---|---|---|---|
+| Pico | femtoruby | Pending (required) | Pending (required) | Pending (required) |
+| Pico 2 | femtoruby | Pending (required) | Pending (optional) | Pending (optional) |
+| Pico 2 | picoruby | Pending (required) | Pending (optional) | Pending (required) |
+| Pico W | firmware-specific | Pending (optional) | Pending (optional) | Pending (optional) |
+| Pico 2 W | firmware-specific | Pending (optional) | Pending (optional) | Pending (optional) |
+
+Completion requires measurements for all six questions and every required matrix cell. Software tests alone do not complete this checklist.

data/docs/releasing.md

@@ -0,0 +1,28 @@
+# Release procedure
+
+Publishing is a separate maintainer action. Implementation does not publish a gem or create release tags.
+
+1. Review `docs/findings.md`; state hardware limitations in release notes.
+2. Update `lib/sandcrawler/version.rb` and `CHANGELOG.md`.
+3. Run full tests with generated fixtures, lint, and build:
+
+   ```sh
+   REQUIRE_FIXTURES=1 bundle exec rake test
+   bundle exec rubocop
+   gem build sandcrawler.gemspec
+   ```
+
+4. Install the artifact in a temporary gem home and smoke-test the installed command (substitute the release version):
+
+   ```sh
+   gem install --install-dir ./tmp/release-gems ./sandcrawler-0.1.0.gem --no-document
+   GEM_HOME=./tmp/release-gems ./tmp/release-gems/bin/sandcrawler --version
+   GEM_HOME=./tmp/release-gems ./tmp/release-gems/bin/sandcrawler doctor
+   ```
+
+   A build machine may lack devices or optional tools. Record `doctor`'s result without claiming hardware validation.
+
+5. Verify CI and package contents: executable, every runtime Ruby file, README, license, changelog, and docs. Generated images and tests must be excluded.
+6. Verify ownership/availability of the `sandcrawler` name on RubyGems, enable MFA, and review the commit/version. After publication is explicitly approved, `bundle exec rake release` creates/pushes the tag and publishes the gem.
+
+The gemspec requires MFA and allows pushes only to `https://rubygems.org`.

data/docs/verification.md

@@ -0,0 +1,80 @@
+# Software verification
+
+This records the software acceptance scope for the implementation and adversarial review on 2026-10-28. Physical Pico testing and execution on Windows are outside this verification run. They are not implied by the passing software tests; physical acceptance remains documented in [findings.md](findings.md).
+
+## Independent acceptance oracle
+
+`script/build_fixtures.sh` uses dosfstools and mtools to construct FAT12 (512-byte and 4096-byte sectors), FAT16, and FAT32 images. It writes known original files and obtains the expected trees with `mcopy`. The generator verifies those trees against the originals before marking the corpus complete. Generated artifacts are excluded from the repository.
+
+`test/acceptance/offline_acceptance_test.rb` exercises the CLI rather than only the FAT reader. It checks:
+
+- All four filesystem types: exact directory and filename sets, every file's SHA-256, empty files, nested files, Japanese filenames, and multi-cluster binary content.
+- A complete flash image and an equivalent UF2 with blocks in reverse order: identical extracted trees and volume geometry, the correct embedded-volume offset, and source hashes.
+- An erased FAT copy and an erased boot sector with a healthy reference image: unchanged live file contents, explicit recovery warnings, and successful status.
+- A deleted file: exact recovered bytes and a status that identifies the recovery assumption.
+- An erased directory: unaffected siblings plus orphan contents matching the lost originals; unknown file lengths are not treated as authoritative.
+- A cyclic chain: the exact readable prefix has a `.partial` suffix, intact siblings remain correct, and the command reports partial success.
+
+Every acceptance extraction also checks that stdout JSON matches `manifest.json`, that recorded file hashes and sizes match the output bytes, that recorded timestamps match restored timestamps, and that the input image's hash is unchanged.
+
+## Requirement coverage
+
+| Requirement | Software evidence | Boundary |
+|---|---|---|
+| FR-01 / FR-02: acquisition and repeated reads | Fake picotool process tests verify allowed commands, pass counts, hashes, strict block majority, range fallback, and failures | Real USB devices and picotool-to-board compatibility require physical testing |
+| FR-03: raw/UF2 volume detection | Embedded-volume, MBR, UF2 validation, and full CLI raw/UF2 parity tests | A damaged boot sector can still require manual or reference geometry |
+| FR-04 / FR-05: FAT parsing and faithful extraction | Independent expected trees for FAT12/16/32; LFN/codepage/timestamp tests; output acceptance checks | Invalid timestamps remain unknown; FAT timestamps have no timezone metadata |
+| FR-06: mismatched and erased FAT copies | Copy selection, FAT32 active-copy, mixed-sector and erased-allocation tests | Disagreement without a uniquely healthy copy remains uncertain and is reported |
+| FR-07 / FR-08 / FR-09: recovery | Deleted, orphan, cycle, cross-link, and carving tests with exact content expectations | Deleted fragmentation and original orphan/carved file boundaries cannot be proven |
+| FR-10: serial transfer | Generated template execution plus pipe-based peers, checksums, listing completeness, retries, protocol validation and bounded failures | Actual firmware prompts and VM APIs require physical testing; individual file transfers are limited to 16 MiB |
+| FR-11: mounted copy | Tree/content/timestamp tests, hidden files, literal mount names, symlink rejection, changed files and failed reads | The host OS may independently write to a writable source mount; this is not an atomic snapshot |
+| FR-12 / NFR-04: provenance | Manifest/stdout agreement, source and output hashes, directory metadata, original byte names, failure reporting and post-extraction source verification | Source state changing outside Sandcrawler cannot establish historical provenance |
+| NFR-01: read-only acquisition | Command/argument allowlists and fixed read-only serial templates | Serial startup interrupts the application; other device software is outside the tool's control |
+| NFR-02: minimal dependencies | Gem metadata and installed executable checks; the core uses the Ruby standard library | Serial communication additionally needs the optional `serialport` gem |
+| NFR-03: platforms and Ruby | Local macOS and Linux container runs; Ruby 3.1 and 4.0 checks; CI configuration includes Windows | No Windows execution or remote CI run is claimed |
+| NFR-05: damaged-input robustness | Seeded metadata mutation, bounded chains/protocols, injected read/write failures, and preserved partial results | These are defined adversarial cases, not a proof over every possible byte sequence |
+| NFR-06: safe output | Traversal/reserved-name/collision tests, symlink rejection, and atomic output checks | Output directories must not be concurrently manipulated by another process |
+
+## Adversarial fixes verified
+
+The review used concrete malformed images, injected I/O failures, fake subprocesses, and scripted serial peers. Regression tests cover the corrected behavior:
+
+- FAT32 backup boot sectors no longer become a false volume at the backup sector's own offset when the primary is erased and the image has trailing bytes. The recovered original offset and `BACKUP_BOOT_SECTOR` evidence are recorded.
+- FAT structural `.` and `..` entries are identified before codepage decoding. Metadata corruption, cycles, cross-links, erased allocation entries, and directory terminators are checked without falsely treating damaged results as intact files.
+- A failed streamed read retains the readable prefix with a `.partial` suffix. Early EOF is compared with the expected size. Directory creation failures are recorded while independent entries remain recoverable.
+- Invalid UTF-8 source and entry names no longer abort JSON or diagnostic logging. Companion `_hex` fields retain original path and name bytes, distinct invalid-byte directory names remain distinct, and terminal control characters are escaped.
+- Missing, duplicate, contradictory, and invalid manual geometry produce usage error 2. Image and reference hashes are rechecked after extraction; changes produce `SOURCE_CHANGED`, exit 5, and a saved failure manifest.
+- Mounted paths containing glob characters no longer produce silently empty copies. Source symlinks and replaced source entries are rejected. Detected rewrites during copying are reported instead of marking the result `ok`.
+- Serial listings require a verified terminator, count, checksum, and unique names. Unexpected, incomplete, or malformed transfer frames fail. Requests stop after the idle timeout, one-hour deadline, 65,537 records, or 40 MiB of encoded responses.
+- picotool commands stop after 120 seconds by default or when either stdout or stderr exceeds 1 MiB. Failed saves preserve any acquired bytes and their hashes before fallback. Invalid UTF-8 device information remains serializable with original bytes in `info_hex`. Required acquisition sidecar failures and changed pass lengths are integrity errors.
+
+Final independent probes reconfirmed the invalid-name error path, directory collision separation, invalid geometry exit codes, and erased-primary FAT32 backup recovery. The independent CLI acceptance file still passed after these fixes: 6 tests, 264 assertions, no failures, errors, or skips.
+
+## Reproduce
+
+```sh
+bundle install
+bundle exec rake fixtures
+REQUIRE_FIXTURES=1 bundle exec rake test
+bundle exec rubocop
+actionlint
+gem build sandcrawler.gemspec
+```
+
+The strict `REQUIRE_FIXTURES=1` run must contain no fixture-related skips. Missing dosfstools/mtools or an absent generated corpus must not be interpreted as successful independent acceptance. The CI workflow generates fixtures once on Ubuntu and supplies the same corpus to each platform job.
+
+The acceptance file can also be run on its own:
+
+```sh
+REQUIRE_FIXTURES=1 bundle exec ruby -Itest test/acceptance/offline_acceptance_test.rb
+```
+
+After all adversarial fixes, the complete suite passed **127 tests and 1,686 assertions**, with **zero failures, errors, or skips**, in each environment below:
+
+| Environment | Ruby | Result |
+|---|---|---|
+| macOS | 4.0.9 | Full suite, including generated fixtures, passed |
+| macOS | 3.1.0 | Full suite passed; unrelated globally installed minitest plugins disabled |
+| Linux container | 4.0.9 | Full suite passed with networking disabled and the checkout mounted read-only |
+
+Mutation checks include 200 FAT metadata cases and 100 UF2 cases with fixed seeds. These supplement the independent mtools comparisons and exact damaged-file expectations. No Windows execution, physical-device acceptance, remote CI result, or RubyGems publication is claimed.

data/exe/sandcrawler

@@ -0,0 +1,5 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/sandcrawler"
+exit Sandcrawler::CLI.new.run(ARGV)

data/lib/sandcrawler/acquisition/mounted_volume.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module Sandcrawler
+  module Acquisition
+    class MountedVolume
+      WARNING = "Mounted volumes may be changed by the OS. On Linux use mount -o ro; " \
+                "on other systems prefer a BOOTSEL dump."
+
+      def initialize(path)
+        @path = File.realpath(path)
+        raise UsageError, "Mount point is not a directory: #{path}" unless File.directory?(@path)
+      end
+
+      def copy(out, force: false, log: nil)
+        reject_overlap!(out)
+        output = Extractor.new(out, source: { type: "mounted_volume", path: @path }, force: force, log: log)
+        output.warning("MOUNT_WRITE_RISK", WARNING)
+        Dir.open(@path, &:read)
+        Dir.glob("**/*", File::FNM_DOTMATCH, base: @path).sort.each do |relative|
+          next if %w[. ..].include?(File.basename(relative))
+
+          copy_entry(output, File.join(@path, relative))
+        end
+        output.finish
+      rescue SystemCallError, IOError => e
+        raise unless output
+
+        output.warning("COPY_FAILED", "#{@path}: #{e.message}")
+        output.finish
+      end
+
+      private
+
+      def reject_overlap!(out)
+        destination = File.expand_path(out)
+        ancestor = destination
+        ancestor = File.dirname(ancestor) until File.exist?(ancestor) || File.symlink?(ancestor)
+        resolved = File.join(File.realpath(ancestor), destination.delete_prefix(ancestor).sub(%r{\A/}, ""))
+        if resolved == @path || resolved.start_with?(@path + File::SEPARATOR) || @path.start_with?(resolved + File::SEPARATOR)
+          raise SafetyError, "Source and output directories must not overlap"
+        end
+      end
+
+      def copy_entry(output, path)
+        relative = path.delete_prefix(@path + File::SEPARATOR)
+        stat = File.lstat(path)
+        if stat.symlink? || File.realpath(path) != path
+          output.warning("SYMLINK_SKIPPED", relative)
+        elsif stat.directory?
+          Dir.open(path, &:read)
+          output.directory(path: relative, mtime: stat.mtime)
+        elsif stat.file?
+          flags = File::RDONLY
+          flags |= File::NOFOLLOW if File.const_defined?(:NOFOLLOW)
+          File.open(path, flags) do |file|
+            opened = file.stat
+            current = File.lstat(path)
+            if File.realpath(path) != path || !opened.file? ||
+               [current.dev, current.ino] != [stat.dev, stat.ino] || !File.identical?(file, path)
+              raise IOError, "Source changed while opening #{relative}"
+            end
+
+            file.binmode
+            record = output.write(path: relative, data: file, mtime: stat.mtime,
+                                  original_name: File.basename(path), expected_size: stat.size)
+            after = file.stat
+            if [stat.size, stat.mtime, stat.ctime] != [after.size, after.mtime, after.ctime]
+              record[:status] = "read_error" if record[:status] == "ok"
+              output.warning("SOURCE_CHANGED", "#{relative} changed during copying; verify recovered bytes")
+            end
+          end
+        else
+          output.warning("SPECIAL_FILE_SKIPPED", relative)
+        end
+      rescue SystemCallError, IOError => e
+        output.warning("COPY_FAILED", "#{relative}: #{e.message}")
+        output.write(path: relative, data: "".b, status: "read_error", error: e.message)
+      end
+    end
+  end
+end