# 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.