Supervise a bwrap sandbox programmatically using --info-fd, --json-status-fd, --sync-fd and --lock-file

Documented steps

1. Requirements / auth: No credentials. Requires bubblewrap and unprivileged user namespaces; the supervising process must be able to allocate and pass file descriptors.
2. Open a pipe for status in the supervising process and pass the write end as `--info-fd FD`; bwrap writes information in JSON format about the sandbox to that FD, which is how you learn namespace details at startup.
3. For lifecycle tracking, pass `--json-status-fd FD`. bwrap emits JSON-lines: a line carrying the child-pid when the sandbox starts, and a line carrying the exit-code when it terminates.
4. Parse the stream line by line rather than as a single JSON document — the two events arrive at different times and each line is its own object.
5. Keep an FD alive for the sandbox's lifetime with `--sync-fd FD`: bwrap keeps that file descriptor open while the sandbox is running, so the supervisor sees EOF exactly when the sandbox is gone.
6. Prevent concurrent runs from clobbering shared state with `--lock-file DEST`, which takes a lock on DEST while the sandbox is running and can be given multiple times for multiple resources.
7. To make the sandbox wait for the supervisor to finish external setup before it starts, use `--block-fd FD`: bwrap blocks reading from that FD until data is available.
8. Add `--die-with-parent` so a supervisor crash cannot leave orphaned sandboxes, and read the final result from bwrap's exit status (the exit status of pid 2 in the sandbox).
9. Official documentation: https://manpages.debian.org/unstable/bubblewrap/bwrap.1.en.html