bee/bible-local/decisions/2026-09-03-runtime-copy-to-ram-loop-change-fd.md

Runtime Copy to RAM must switch the active loop backing file

Date: 2026-09-03 Status: active

Evidence

On bee@172.16.41.97, the runtime Copy to RAM task showed two contradictory results:

• with the BMC virtual CD connected, the 2.7 GB squashfs copy reached 100%, loop reassociation logged invalid argument, and the worker failed;
• without the ISO connected, a later task found the stale file in /dev/shm/bee-live, logged the same reassociation error, but returned success.

After the reported success, /sys/block/loop0/loop/backing_file still named /run/live/medium/live/filesystem-*.squashfs, /run/live/medium was backed by /dev/sr0, and disconnecting virtual media produced repeated Medium not present and I/O errors. The system was not running independently from RAM.

The Linux ABI defines LOOP_CHANGE_FD as 0x4C06 and LOOP_SET_DIRECT_IO as 0x4C08. The application had named 0x4C08 as ioctlLoopChangeFD, so every fallback reassociation called the wrong ioctl and received EINVAL.

The follow-up live run exposed another independent failure: copying the remaining medium tree passes a nil progress callback to copyFileLarge, but the copier called that callback unconditionally after each progress interval. The worker therefore panicked immediately after logging "Copying remaining medium files...", and the parent task only reported exit status 1.

Decision

• Use the correct LOOP_CHANGE_FD request number, 0x4C06, and protect it with a Linux-specific regression test.
• Copy all source data before changing active loop devices.
• Treat a missing loop device, failed reassociation, or failed post-change backing-file lookup as a fatal task error. A copied file alone is never proof that the running system uses it.
• After all squashfs loops point at their files in /dev/shm/bee-live, unmount the original live-medium mount and bind the RAM directory at /run/live/medium.
• Success requires both at least one switched loop and a tmpfs-backed /run/live/medium.
• Eject the original device without unmounting the new RAM bind mount.
• Preserve a complete RAM copy after any failure that occurs after loop reassociation begins, so retry never deletes a file backing a live loop.
• Progress reporting is optional; bulk copies without a logger must never panic.

Consequences

The button can resume a complete copy left by an interrupted worker even if the virtual CD has since disappeared, but it reports success only if the kernel actually accepts that file as the live loop backing. Partial or stale copies can no longer produce a false done result. Boot-time toram remains a separate initramfs path and is not evidence that the runtime button worked.