Replay a dirty journal before writing to an instance image

[RobThePCGuy]

The bug

BlueStacks instances are almost never shut down cleanly. The player is terminated rather than asked to close (its own clean exit needs a human to click through a confirmation dialog), so the guest never unmounts and /data comes to rest with an unreplayed journal. Booting replays it, which is why this is invisible in normal use.

Offline it broke two things.

1. Operations were refused for no reason. e2fsck -fn cannot replay a journal, so it reports such an image as damaged:

Warning: skipping journal recovery because doing a read-only filesystem check.
Inode 3410023 was part of the orphaned inode list.  IGNORED.
Block bitmap differences:  -13640454 -(13696000--13697023) ...
Free blocks count wrong (32140416, counted=32135804).

Those are phantoms: the journal's own pending metadata, which evaporates once replayed. Every caller turned them into e2fsck reported errors. Restart an instance, then install Magisk, and it fails because of how the instance was last closed.

2. Writes could be silently clobbered. Writing with debugfs into a filesystem whose journal still holds pending metadata risks the replay at next boot overwriting what was just written. This is the likeliest explanation for module binaries previously turning up zero-length.

The fix

_Attached.__enter__ now replays the journal before handing out the device, so every offline writer inherits it (ext4_symlink, magisk_system, telemetry_block all funnel through it). A clean image is left completely untouched.

The repair has to run on the partition device, not the ?offset= one. After replaying, e2fsck reopens the filesystem to restart its check; the reopen drops the ?offset= qualifier, lands on the raw disk, and dies before committing:

e2fsck -fp /dev/sdc?offset=1048576  -> exit 12
   /dev/sdc: recovering journal
   e2fsck: Bad magic number in super-block while trying to re-open /dev/sdc

The replay never persists. Run it twice and it announces "recovering journal" both times, with the image byte-for-byte unchanged. Pointed at the partition there is nothing to lose on reopen:

e2fsck -fp /dev/sdc1  -> exit 1
   /dev/sdc1: recovering journal
   /dev/sdc1: Clearing orphaned inode 3410023 ... 3410598 ... 3410512
e2fsck -fn /dev/sdc1              -> exit 0  clean
e2fsck -fn /dev/sdc?offset=...    -> exit 0  clean

Two safeguards:

• The partition is identified, not guessed. Candidates are fingerprinted by e2fsck's capacity totals and only accepted when they match the offset device, so a repair can never land on a different filesystem. If none matches, it refuses rather than picking one.
• The verdict comes from re-checking, never from preen's exit code, which is 12 even on success here and 1 after a real repair.

Verification

Live, on an image left dirty by a real kill:

OLD: _fsck_ok (-fn) -> False
NEW: "Replayed the filesystem journal left by the last shutdown before writing."
     _fsck_ok (-fn) -> True
     second attach  -> None      (idempotent, clean images untouched)

259 tests green, ruff clean. The new tests cover routing to the partition device, the identity guard against repairing a different filesystem, exit-code independence across 0/1/2/4/8/12, and refusing to write when the image is still dirty afterwards.

[gemini-code-assist]

Caution

The consumer version of Gemini Code Assist on GitHub has been sunset. All code review activity has officially ceased.