@volter/world-machine 2.0.0

package/dist/src/ct.sh

@@ -0,0 +1,675 @@
+# The container backend's half of the machine host (backend "container"), sourced after host.sh. The machine is a
+# container run by crun with CRIU, with no VM inside the host. On a Mac a VM inside the Lima VM faults every first
+# touch of memory through two hypervisors (a real project's install ran 20–80x slower), so the machine is the
+# host's own processes instead.
+#   the tree   one ext4 image per slot ($WM_SLOTDIR/root.img, mounted at $WM_SLOTDIR/root): the container's root and
+#              the emulated root both live in it, so a mark is one reflink of one file however many files it holds
+#              and a restore brings back the same blocks, keeping inode numbers (and an NFS client's handles) valid
+#   the net    a bridge $WM_TAP at $WM_HOSTIP and a network namespace holding $WM_GUESTIP: the Firecracker guest's
+#              addresses, so the egress forwarders and the doors into the machine are unchanged
+#   a mark     the container paused, the image reflinked, the processes dumped by CRIU, the container resumed
+#   a retake   the container gone, the mark's image reflinked back and mounted, the processes restored, and the
+#              connections the restore left stale (their far end was replaced) reset as the Firecracker guest agent
+#              resets them
+WM_CT="wm-$WM_SLOT"
+WM_NETNS="wm-$WM_SLOT"
+WM_ROOTIMG="$WM_SLOTDIR/root.img"
+WM_ROOT="$WM_SLOTDIR/root"
+WM_BUNDLE="$WM_SLOTDIR/bundle"
+
+# the bridge and the namespace, made once per boot of the host
+wm_ct_net() {
+  if ! ip link show "$WM_TAP" >/dev/null 2>&1; then
+    sudo -n ip link add "$WM_TAP" type bridge && sudo -n ip addr add "$WM_HOSTIP/30" dev "$WM_TAP" && sudo -n ip link set "$WM_TAP" up || { wm_fail "cannot make the bridge $WM_TAP"; return 1; }
+  fi
+  if [ ! -e "/var/run/netns/$WM_NETNS" ]; then
+    sudo -n ip netns add "$WM_NETNS" && sudo -n ip link add "${WM_TAP}p" type veth peer name eth0 netns "$WM_NETNS" \
+      && sudo -n ip link set "${WM_TAP}p" master "$WM_TAP" && sudo -n ip link set "${WM_TAP}p" up \
+      && sudo -n ip -n "$WM_NETNS" addr add "$WM_GUESTIP/30" dev eth0 && sudo -n ip -n "$WM_NETNS" link set eth0 up \
+      && sudo -n ip -n "$WM_NETNS" link set lo up && sudo -n ip -n "$WM_NETNS" route add default via "$WM_HOSTIP" \
+      || { wm_fail "cannot make the network namespace $WM_NETNS"; return 1; }
+  fi
+  printf '@{"net":"%s"}\n' "$WM_NETNS"
+}
+
+wm_ct_mount() {
+  # outside a restore's swap, a server a killed restore left stopped starts again (inside it, the restore does, once exported)
+  [ -n "${WM_SWAP:-}" ] || wm_ct_nfsd_resume
+  mkdir -p "$WM_ROOT"
+  # the tree's loop reads its image with direct I/O (4096-byte sectors, which direct I/O on the store needs): through
+  # the page cache the tree's files were cached once per layer (the tree, its image on the store, the store's image)
+  if ! mountpoint -q "$WM_ROOT"; then
+    local dev; dev=$(sudo -n losetup --find --show --direct-io=on --sector-size 4096 "$WM_ROOTIMG") && sudo -n mount "$dev" "$WM_ROOT" \
+      || { [ -n "${dev:-}" ] && sudo -n losetup -d "$dev"; wm_fail "cannot mount $WM_ROOTIMG"; return 1; }
+  fi
+  wm_ct_export
+}
+wm_ct_umount() {
+  wm_ct_unexport
+  mountpoint -q "$WM_ROOT" || return 0
+  local dev; dev=$(findmnt -no SOURCE "$WM_ROOT")
+  sudo -n umount "$WM_ROOT" || sudo -n umount -l "$WM_ROOT" || return 1
+  case "$dev" in /dev/loop*) sudo -n losetup -d "$dev" 2>/dev/null ;; esac; return 0
+}
+
+# WM_EXPORT ({"path","client","uid","gid"}, from the config's `export`): a path in the tree served by the host's NFS
+# server (the container shares the host kernel, so the server cannot run inside it) with a fixed fsid: a restore brings
+# back the same blocks, so inode numbers, and an NFS client's handles on unchanged files, stay valid across it
+wm_ct_export() {
+  [ -n "${WM_EXPORT:-}" ] || return 0
+  # the path is made by the base's provisioning: until then there is nothing to serve (exportfs refuses a missing path,
+  # and a stale entry for one blocks every later exportfs)
+  local path; path="$WM_ROOT/$(python3 -c 'import json,sys; print(json.loads(sys.argv[1])["path"].lstrip("/"))' "$WM_EXPORT")"
+  [ -d "$path" ] || { wm_ct_unexport; return 0; }
+  python3 - "$WM_EXPORT" "$WM_ROOT" "$WM_SLOT" <<'PY' | sudo -n tee "/etc/exports.d/world-machine-$WM_SLOT.exports" >/dev/null
+import json, sys
+e, root, slot = json.loads(sys.argv[1]), sys.argv[2], sys.argv[3]
+print(f'{root}/{e["path"].lstrip("/")} {e["client"]}(rw,sync,insecure,no_subtree_check,all_squash,anonuid={e["uid"]},anongid={e["gid"]},fsid={e.get("fsid", 7101)})')
+PY
+  sudo -n exportfs -ra
+}
+wm_ct_unexport() {
+  [ -f "/etc/exports.d/world-machine-$WM_SLOT.exports" ] || return 0
+  sudo -n rm -f "/etc/exports.d/world-machine-$WM_SLOT.exports"; sudo -n exportfs -ra
+}
+
+# wm_ct_bundle [argv...]: the OCI bundle: the image's tree as the root, the slot's namespace as the network, every
+# other namespace new, io_uring answered ENOSYS (CRIU cannot dump one); the process is the machine's init (world-machine-init, installed by the base) unless argv names
+# another (the base's provisioning run)
+wm_ct_bundle() {
+  mkdir -p "$WM_BUNDLE"
+  python3 - "$WM_BUNDLE/config.json" "$WM_ROOT" "/var/run/netns/$WM_NETNS" "${WM_BINDS:-[]}" "$@" <<'PY'
+import json, sys
+out, root, netns, binds = sys.argv[1:5]
+sys.argv = sys.argv[:4] + sys.argv[5:]
+argv = sys.argv[4:] or ["/usr/local/sbin/world-machine-init"]
+caps = ["CAP_CHOWN","CAP_DAC_OVERRIDE","CAP_FSETID","CAP_FOWNER","CAP_MKNOD","CAP_NET_RAW","CAP_SETGID","CAP_SETUID",
+        "CAP_SETFCAP","CAP_SETPCAP","CAP_NET_BIND_SERVICE","CAP_SYS_CHROOT","CAP_KILL","CAP_AUDIT_WRITE","CAP_SYS_PTRACE","CAP_NET_ADMIN"]
+config = {
+  "ociVersion": "1.0.2",
+  "process": {"terminal": False, "user": {"uid": 0, "gid": 0}, "args": argv,
+              "env": ["PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin", "HOME=/root"], "cwd": "/",
+              "capabilities": {k: caps for k in ("bounding", "effective", "permitted")}, "noNewPrivileges": False},
+  "root": {"path": root, "readonly": False},
+  "hostname": "machine",
+  "mounts": [
+    {"destination": "/proc", "type": "proc", "source": "proc"},
+    {"destination": "/dev", "type": "tmpfs", "source": "tmpfs", "options": ["nosuid", "strictatime", "mode=755", "size=65536k"]},
+    {"destination": "/dev/pts", "type": "devpts", "source": "devpts", "options": ["nosuid", "noexec", "newinstance", "ptmxmode=0666", "mode=0620"]},
+    {"destination": "/dev/shm", "type": "tmpfs", "source": "shm", "options": ["nosuid", "noexec", "nodev", "mode=1777", "size=268435456"]},
+    {"destination": "/sys", "type": "sysfs", "source": "sysfs", "options": ["nosuid", "noexec", "nodev", "ro"]},
+  ] + [{"destination": b["destination"], "type": "bind", "source": b["source"], "options": ["rbind", "ro"]} for b in json.loads(binds)],
+  "linux": {"namespaces": [{"type": "pid"}, {"type": "ipc"}, {"type": "uts"}, {"type": "mount"}, {"type": "cgroup"}, {"type": "network", "path": netns}],
+            # CRIU cannot dump an io_uring (measured: CRIU 4.2 refused next dev under Node 24, whose libuv uses one on
+            # kernel 7.0): the machine's processes are told it does not exist, and libuv and the rest fall back
+            "seccomp": {"defaultAction": "SCMP_ACT_ALLOW",
+                        "syscalls": [{"names": ["io_uring_setup", "io_uring_enter", "io_uring_register"], "action": "SCMP_ACT_ERRNO", "errnoRet": 38}]}},
+}
+json.dump(config, open(out, "w"), indent=1)
+PY
+}
+
+wm_ct_state() { sudo -n crun state "$WM_CT" 2>/dev/null | python3 -c 'import json,sys; print(json.load(sys.stdin).get("status",""))' 2>/dev/null; }
+wm_ct_running() { printf '@{"container":"%s","owner":%s}\n' "$(wm_ct_state)" "$(cat "$WM_SLOTDIR/owner.json" 2>/dev/null || echo null)"; }
+wm_ct_stop() { [ -n "$(wm_ct_state)" ] || return 0; sudo -n crun kill -a "$WM_CT" KILL 2>/dev/null; sudo -n crun delete -f "$WM_CT" >/dev/null 2>&1; }
+
+# wm_ct_mark <dir> [parent]: a mark into <dir> (root.img and criu/), the container running on afterwards; with <parent>
+# (the mark the machine was last marked or restored at), the dump is then composed against the parent's
+# (wm_ct_compose), detached. Every mark dumps: whether nothing in the machine ran since the parent cannot be told
+# exactly (a freeze and thaw run the processes' interrupted syscalls again, costing user time and a context switch per
+# thread, as a small real wake-up does), and a mark that reused a dump could claim a state the machine never held.
+# A mark of an unchanged machine costs a dump's pause and, composed, almost no store (measured: 0-2 MB).
+wm_ct_mark() {
+  local dir="$1" parent="${2:-}" t0 tp tr tc
+  mkdir -p "$dir/criu" || return 1
+  t0=$(wm_ns)
+  sudo -n crun pause "$WM_CT" || { wm_fail "cannot pause $WM_CT"; return 1; }
+  sync -f "$WM_ROOT"; sudo -n fsfreeze -f "$WM_ROOT"
+  tp=$(wm_ns)
+  cp --reflink=always "$WM_ROOTIMG" "$dir/root.img"; local rc=$?
+  sudo -n fsfreeze -u "$WM_ROOT"
+  tr=$(wm_ns)
+  [ $rc = 0 ] || { sudo -n crun resume "$WM_CT"; wm_fail "cannot reflink the tree into $dir"; return 1; }
+  # CRIU dumps the paused tree and leaves it as it found it; the resume below lets it run on
+  sudo -n crun checkpoint --leave-running --tcp-established --file-locks --image-path "$dir/criu" --work-path "$dir/criu" "$WM_CT" >"$dir/criu/dump.out" 2>&1 \
+    || { sudo -n crun resume "$WM_CT" 2>/dev/null; wm_fail "CRIU could not dump $WM_CT: $(tail -3 "$dir/criu/dump.out")"; return 1; }
+  [ "$(wm_ct_state)" = paused ] && sudo -n crun resume "$WM_CT"
+  tc=$(wm_ns)
+  [ -n "$parent" ] && wm_ct_compose "$parent" "$dir"
+  printf '@{"pauseMs":%s,"treeMs":%s,"dumpMs":%s,"memBytes":%s}\n' "$(( (tc - t0) / 1000000 ))" "$(( (tr - tp) / 1000000 ))" "$(( (tc - tr) / 1000000 ))" \
+    "$(du -sb "$dir/criu" | cut -f1)"
+}
+
+# wm_ct_publish <ports JSON>: the machine's allowed listening ports on this host's loopback (publish.py, as root, one per
+# slot). The running publisher is trusted only when its pid is a publish.py of the current version; otherwise it is
+# stopped and started again. wm_ct_unpublish stops it (its socat children die with it).
+wm_ct_publisher() { local pid; pid=$(cat "$WM_SLOTDIR/publish.pid" 2>/dev/null) || return 1
+  [ -n "$pid" ] && tr '\0' ' ' < "/proc/$pid/cmdline" 2>/dev/null | grep -q "$WM_SLOTDIR/publish.py" && echo "$pid"; }
+wm_ct_publish() {
+  # the version and ports the running publisher was started with, which it writes itself once it holds the slot's lock
+  local pid sum; sum=$(sha256sum "$WM_SLOTDIR/publish.py" | cut -c1-16)$(printf '%s' "$1" | sha256sum | cut -c1-16)
+  pid=$(wm_ct_publisher) && [ "$(cat "$WM_SLOTDIR/publish.sum" 2>/dev/null)" = "$sum" ] && return 0
+  wm_ct_unpublish
+  sudo -n setsid nohup python3 "$WM_SLOTDIR/publish.py" "$WM_SLOTDIR" "$WM_NETNS" "$WM_CT" "$1" "$sum" >> "$WM_SLOTDIR/publish.log" 2>&1 < /dev/null 9>&- &
+}
+wm_ct_unpublish() {
+  local pid; pid=$(wm_ct_publisher) || { rm -f "$WM_SLOTDIR/publish.pid"; return 0; }
+  sudo -n kill "$pid" 2>/dev/null
+  local i; for i in $(seq 1 30); do sudo -n kill -0 "$pid" 2>/dev/null || break; sleep 0.1; done
+  sudo -n kill -9 "$pid" 2>/dev/null; rm -f "$WM_SLOTDIR/publish.pid"; return 0
+}
+
+# wm_ct_compose <parent> <dir>: the mark's page files composed against its parent's (compose.py), detached
+wm_ct_compose() {
+  [ -f "$1/criu/inventory.img" ] || return 0
+  # idle I/O priority: the next mark's pause must not wait behind it
+  sudo -n setsid nohup nice -n 10 ionice -c 3 python3 "$WM_SLOTDIR/compose.py" "$1/criu" "$2/criu" > "$2/compose.log" 2>&1 < /dev/null 9>&- &
+}
+
+
+# the NFS server's threads, stopped for a restore's swap, started again from the count the slot kept
+wm_ct_nfsd_resume() {
+  [ -f "$WM_SLOTDIR/nfsd.threads" ] || return 0
+  sudo -n rpc.nfsd "$(cat "$WM_SLOTDIR/nfsd.threads")" && rm -f "$WM_SLOTDIR/nfsd.threads"
+}
+
+# wm_ct_restore <dir> [restore id]: the machine brought back to the mark in <dir>, the id in its tree (RESTORE_ID_FILE)
+# before its processes run
+wm_ct_restore() {
+  local dir="$1" rid="${2:-}" t0 tl tr threads="" WM_SWAP=1
+  t0=$(wm_ns)
+  # the snapshot being read is held against a collection until the processes are back (gc reads this marker)
+  printf '%s' "$dir" > "$WM_SLOTDIR/restoring"
+  # with an export, the NFS server's threads stop for the swap: a client (the Mac's hard mount) then waits and retries
+  # instead of being answered with an error for the moment the tree is not exported (measured: one of 60 reads failed).
+  # The count is kept in the slot first, so a restore killed mid-swap is undone by the next one (wm_ct_nfsd_resume).
+  # The server is the host's: every export on it waits out the swap.
+  wm_ct_nfsd_resume
+  if [ -n "${WM_EXPORT:-}" ]; then
+    threads=$(cat /proc/fs/nfsd/threads 2>/dev/null)
+    if [ "${threads:-0}" -gt 0 ]; then printf '%s' "$threads" > "$WM_SLOTDIR/nfsd.threads" && sudo -n rpc.nfsd 0; fi
+  fi
+  wm_ct_stop; wm_ct_umount || { rm -f "$WM_SLOTDIR/restoring"; wm_ct_nfsd_resume; wm_fail "cannot unmount $WM_ROOT"; return 1; }
+  cp --reflink=always "$dir/root.img" "$WM_ROOTIMG.next" && mv -f "$WM_ROOTIMG.next" "$WM_ROOTIMG" || { rm -f "$WM_SLOTDIR/restoring"; wm_ct_nfsd_resume; wm_fail "cannot reflink $dir/root.img"; return 1; }
+  wm_ct_mount; local mrc=$?
+  wm_ct_nfsd_resume
+  [ $mrc = 0 ] || { rm -f "$WM_SLOTDIR/restoring"; return 1; }
+  [ -n "$rid" ] && printf '{"/run/world-machine/restore-id": "%s\\n"}' "$rid" | wm_ct_write >/dev/null
+  wm_ct_bundle
+  tl=$(wm_ns)
+  sudo -n crun restore -d --tcp-established --file-locks --image-path "$dir/criu" --work-path "$WM_SLOTDIR" --bundle "$WM_BUNDLE" "$WM_CT" >"$WM_SLOTDIR/restore.out" 2>&1 \
+    || { rm -f "$WM_SLOTDIR/restoring"; wm_fail "CRIU could not restore $WM_CT from $dir: $(tail -3 "$WM_SLOTDIR/restore.out")"; return 1; }
+  rm -f "$WM_SLOTDIR/restoring"
+  tr=$(wm_ns)
+  printf '@{"loadMs":%s,"restoreMs":%s}\n' "$(( (tl - t0) / 1000000 ))" "$(( (tr - tl) / 1000000 ))"
+}
+
+# the connections the restore left open to the host (a twin, a door, the World), whose far end was replaced:
+# reset so the programs holding them reconnect at once, as the Firecracker guest agent's `reset` does
+# wm_ct_reset_egress <spec…>: only the machine's connections through the World's forwarders (each spec `port=target`, as
+# wm_egress takes them) reset, every other connection kept: a live handover's twins changed, the machine did not
+wm_ct_reset_egress() {
+  local t0 f="" m; t0=$(wm_ns)
+  for m in "$@"; do f="${f:+$f or }dport = :${m%%=*}"; done
+  [ -n "$f" ] && sudo -n ip netns exec "$WM_NETNS" ss -K dst "$WM_HOSTIP" "( $f )" >/dev/null 2>&1
+  printf '@{"resetMs":%s}\n' "$(( ($(wm_ns) - t0) / 1000000 ))"
+}
+wm_ct_reset() {
+  local t0; t0=$(wm_ns)
+  sudo -n ip netns exec "$WM_NETNS" ss -K dst "$WM_HOSTIP" >/dev/null 2>&1
+  printf '@{"resetMs":%s}\n' "$(( ($(wm_ns) - t0) / 1000000 ))"
+}
+
+# wm_ct_write: a JSON object of path -> content on stdin, written into the machine's tree (the World's env file, its
+# certificates, world-core's redirect), as the Firecracker guest agent's `write` does
+wm_ct_write() {
+  # written as host root into a tree the machine's own processes can change: every component is opened without
+  # following a symlink (O_NOFOLLOW, relative to the one before), so a link the machine left cannot point a write at
+  # the host's own files
+  sudo -n python3 -c '
+import json, os, sys
+root = os.open(sys.argv[1], os.O_DIRECTORY | os.O_NOFOLLOW)
+for path, content in json.load(sys.stdin).items():
+    parts = [p for p in path.split("/") if p and p not in (".", "..")]
+    d = os.dup(root)
+    for part in parts[:-1]:
+        try: os.mkdir(part, 0o755, dir_fd=d)
+        except FileExistsError: pass
+        n = os.open(part, os.O_DIRECTORY | os.O_NOFOLLOW, dir_fd=d); os.close(d); d = n
+    tmp = parts[-1] + ".wm-tmp"
+    try: os.unlink(tmp, dir_fd=d)
+    except FileNotFoundError: pass
+    f = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW, 0o644, dir_fd=d)
+    os.write(f, content.encode()); os.close(f)
+    os.replace(tmp, parts[-1], src_dir_fd=d, dst_dir_fd=d)
+    os.close(d)
+print("@" + json.dumps({"written": True}))
+' "$WM_ROOT"
+}
+
+# The machine's init (/usr/local/sbin/world-machine-init): runs each /etc/world-machine/services.d/*.sh in order to
+# completion (a service script starts its daemon detached and returns once it listens), marks itself ready only if
+# every one succeeded, and reaps. PID 1 of the container; the base's mark dumps it with its services.
+WM_CT_INIT='#!/usr/bin/python3
+import glob, os, signal, subprocess, time
+# crun hands the init its own stdio, host files outside the container that CRIU cannot dump: the container'"'"'s /dev/null instead
+null = os.open("/dev/null", os.O_RDWR)
+for fd in (0, 1, 2): os.dup2(null, fd)
+if null > 2: os.close(null)
+failed = []
+for s in sorted(glob.glob("/etc/world-machine/services.d/*.sh")):
+    with open("/var/log/" + os.path.basename(s) + ".log", "a") as log:
+        if subprocess.run(["/bin/bash", s], stdin=subprocess.DEVNULL, stdout=log, stderr=subprocess.STDOUT).returncode != 0: failed.append(os.path.basename(s))
+os.makedirs("/run", exist_ok=True)
+open("/run/world-machine-failed" if failed else "/run/world-machine-ready", "w").write(" ".join(failed) or str(time.time()))
+signal.signal(signal.SIGTERM, lambda *a: os._exit(0))
+while True:
+    try: os.waitpid(-1, 0)
+    except ChildProcessError: time.sleep(1)
+'
+
+# wm_ct_base_fill <image> <size> <dir>: <dir>/root.img made from the OCI image <image>, with the init installed
+wm_ct_base_fill() {
+  local image="$1" size="$2" dir="$3" mnt="$3/mnt" cid
+  mkdir -p "$mnt" || return 1
+  # 4 KiB blocks: the tree's loop has 4096-byte sectors (direct I/O), and a small image would otherwise get 1 KiB ones
+  truncate -s "$size" "$dir/root.img" && mkfs.ext4 -q -F -b 4096 "$dir/root.img" || { wm_fail "cannot make $dir/root.img"; return 1; }
+  sudo -n mount -o loop "$dir/root.img" "$mnt" || { wm_fail "cannot mount $dir/root.img"; return 1; }
+  # the image on this host, the one the base is named by (its id): `world-machine base` pulled one from a registry first
+  sudo -n podman image exists "$image" && cid=$(sudo -n podman create "$image" true) \
+    && sudo -n podman export "$cid" | sudo -n tar -x -C "$mnt"; local rc=$?
+  [ -n "$cid" ] && sudo -n podman rm -f "$cid" >/dev/null 2>&1
+  [ $rc = 0 ] || { sudo -n umount "$mnt"; wm_fail "cannot fill the tree from $image"; return 1; }
+  printf '%s' "$WM_CT_INIT" | sudo -n tee "$mnt/usr/local/sbin/world-machine-init" >/dev/null && sudo -n chmod 755 "$mnt/usr/local/sbin/world-machine-init"
+  sudo -n mkdir -p "$mnt/etc/world-machine/services.d" "$mnt/root"
+  sudo -n cp /etc/resolv.conf "$mnt/etc/resolv.conf" 2>/dev/null
+  # the names a container runtime would give it (podman writes these only into containers it runs itself, so an exported
+  # tree has none): without them `localhost` did not resolve in the machine (measured: getaddrinfo EAI_AGAIN)
+  printf '127.0.0.1\tlocalhost\n::1\tlocalhost ip6-localhost ip6-loopback\n%s\tmachine\n' "$WM_GUESTIP" | sudo -n tee "$mnt/etc/hosts" >/dev/null
+  printf 'machine\n' | sudo -n tee "$mnt/etc/hostname" >/dev/null
+  sudo -n umount "$mnt"; rmdir "$mnt"
+  printf '@{"filled":true}\n'
+}
+
+# wm_ct_provision <script>: the script run once in the slot's tree, as root, in the machine's namespaces; its exit code
+wm_ct_provision() {
+  local script="$1"
+  sudo -n install -m 755 "$script" "$WM_ROOT/root/.world-machine-provision.sh" || { wm_fail "cannot place the provisioning script"; return 1; }
+  wm_ct_bundle /bin/bash -c '/root/.world-machine-provision.sh > /root/.world-machine-provision.log 2>&1'
+  sudo -n crun run --bundle "$WM_BUNDLE" "$WM_CT-provision" </dev/null >/dev/null 2>&1; local rc=$?
+  sudo -n crun delete -f "$WM_CT-provision" >/dev/null 2>&1
+  printf '@{"code":%s,"log":%s}\n' "$rc" "$(sudo -n tail -c 600 "$WM_ROOT/root/.world-machine-provision.log" 2>/dev/null | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))')"
+}
+
+# wm_ct_start: the machine's init started in the slot's tree, detached; ready once it has started its services
+wm_ct_start() {
+  wm_ct_stop; wm_ct_bundle
+  # both markers cleared before the init starts: one that fails at once must still be read as failed
+  sudo -n rm -f "$WM_ROOT/run/world-machine-ready" "$WM_ROOT/run/world-machine-failed"
+  rm -f "$WM_SLOTDIR/start.err"   # a CRIU run over the init's inherited stderr once left it root's
+  sudo -n crun run -d --bundle "$WM_BUNDLE" "$WM_CT" >/dev/null 2>"$WM_SLOTDIR/start.err" || { wm_fail "crun could not start $WM_CT: $(tail -2 "$WM_SLOTDIR/start.err")"; return 1; }
+  local i; for i in $(seq 1 300); do [ -f "$WM_ROOT/run/world-machine-ready" ] || [ -f "$WM_ROOT/run/world-machine-failed" ] && break; sleep 0.1; done
+  [ -f "$WM_ROOT/run/world-machine-failed" ] && { wm_fail "$WM_CT: services failed: $(cat "$WM_ROOT/run/world-machine-failed") ($(sudo -n tail -n 3 "$WM_ROOT"/var/log/*.sh.log 2>/dev/null | tail -6))"; return 1; }
+  [ -f "$WM_ROOT/run/world-machine-ready" ] || { wm_fail "$WM_CT did not report ready in 30 s"; return 1; }
+  printf '@{"started":true}\n'
+}
+
+# wm_ct_run <user or ""> <seconds> <argv json>: a command run in the running machine (crun exec), as <user> (a name
+# the machine's own passwd resolves) or its root; the machine's own `timeout` ends it (and what it started in its
+# group) past <seconds>. Its exit code (124: it ran past the bound) and the last 16,000 bytes of each output, which go
+# to files on the host and are never held whole.
+wm_ct_run() {
+  local user=$1 secs=$2 argv=$3 ids=""
+  [ "$(wm_ct_state)" = running ] || { wm_fail "refused: the machine is $(wm_ct_state), not running"; return 1; }
+  if [ -n "$user" ]; then
+    ids=$(sudo -n crun exec "$WM_CT" /bin/sh -c 'echo "$(id -u "$1"):$(id -g "$1")"' sh "$user" 2>/dev/null) && [ "${ids#:}" = "$ids" ] \
+      || { wm_fail "refused: the machine has no user $user"; return 1; }
+  fi
+  sudo -n timeout -k 5 "$((secs + 15))" env PATH="$PATH" python3 - "$WM_CT" "$ids" "$argv" "$secs" <<'PY' || { wm_fail "the command could not be run in the machine"; return 1; }
+import json, os, subprocess, sys, tempfile
+ct, ids, argv, secs = sys.argv[1], sys.argv[2], json.loads(sys.argv[3]), sys.argv[4]
+with tempfile.TemporaryFile() as out, tempfile.TemporaryFile() as err:
+    # the bound inside the machine: its timeout kills the command's whole group there (crun exec's own child would
+    # otherwise outlive a kill of crun here)
+    r = subprocess.run(['crun', 'exec'] + (['--user', ids] if ids else []) + [ct, 'timeout', '-k', '5', secs] + argv,
+                       stdout=out, stderr=err, stdin=subprocess.DEVNULL)
+    def tail(f):
+        size = f.seek(0, os.SEEK_END); f.seek(max(0, size - 16000)); return f.read().decode(errors='replace')
+    print('@' + json.dumps({'code': r.returncode, 'stdout': tail(out), 'stderr': tail(err), **({'timedOut': True} if r.returncode == 124 else {})}))
+PY
+}
+
+# wm_ct_files <snap> <paths json>: part of the machine's disk back at the mark in <snap>, the machine running on: each
+# path (relative to the machine's root) made as the mark's image, mounted read-only, has it: a folder exactly (what
+# was made in it since removed), a file by its content (its time is not trusted: npm and tar keep old ones), owners,
+# modes and times as they were; a path the mark did not have is removed. The processes keep running and are not told.
+# Written as host root into a tree the machine's own processes can change while it runs, every component of the live
+# tree is opened relative to the one before without following a symlink (as wm_ct_write), so a link the machine left
+# or swaps in cannot lead a write or a removal out of the tree; a path whose folders are a symlink in either tree is
+# refused. Hard links, ACLs and extended attributes are not carried; a FIFO, socket or device is left as it is.
+wm_ct_files() {
+  local snap=$1 paths=$2 nolinks=${3:-} dry=${4:-} mnt
+  for m in "$WM_SLOTDIR"/compare.* "$WM_SLOTDIR"/files.*; do [ -d "$m" ] || continue; sudo -n umount "$m" 2>/dev/null; rmdir "$m" 2>/dev/null; done
+  mnt=$(mktemp -d "$WM_SLOTDIR/files.XXXXXX") || { wm_fail "cannot make a mount point"; return 1; }
+  # held against a collection while mounted, as a compare's (host.sh wm_store_list)
+  printf '%s' "$snap" > "$WM_SLOTDIR/comparing"
+  trap 'sudo -n umount "'"$mnt"'" 2>/dev/null; rmdir "'"$mnt"'" 2>/dev/null; rm -f "$WM_SLOTDIR/comparing"; trap - RETURN' RETURN
+  sudo -n mount -o ro,loop,noload,nodev,nosuid,noexec "$snap/root.img" "$mnt" || { wm_fail "cannot mount $snap/root.img"; return 1; }
+  sudo -n timeout -k 5 300 env PATH="$PATH" python3 - "$mnt" "$WM_ROOT" "$paths" "$nolinks" "$dry" <<'PY'
+import errno, json, os, shutil, stat, sys
+mnt, live, paths = sys.argv[1], sys.argv[2], json.loads(sys.argv[3])
+# nolinks: a tree that must be whole in itself (a database's data directory): a symlink anywhere under a path, in the
+# mark or now, is refused (a tablespace or a moved log would come back as a link to data that did not)
+NOLINKS = sys.argv[4] == 'nolinks'
+# dry: the checks only (every path, both trees), nothing touched: a caller that must stop something first asks this first
+DRY = sys.argv[5] == 'dry'
+LIMIT = 20
+NOFOLLOW_DIR = os.O_DIRECTORY | os.O_NOFOLLOW
+out = []
+
+def say(obj):
+    print('@' + json.dumps(obj)); sys.exit(0 if 'error' not in obj else 1)
+
+def open_parent(rel, create):
+    """The live folder holding rel's last component, opened component by component without following a symlink;
+    a missing folder made (with create) as the mark has it. None when a folder is missing and not made."""
+    parts = rel.split('/')
+    d = os.open(live, NOFOLLOW_DIR)
+    here = mnt
+    for part in parts[:-1]:
+        here = os.path.join(here, part)
+        try:
+            n = os.open(part, NOFOLLOW_DIR, dir_fd=d)
+        except FileNotFoundError:
+            if not create:
+                os.close(d); return None
+            st = os.lstat(here)
+            os.mkdir(part, 0o700, dir_fd=d)
+            n = os.open(part, NOFOLLOW_DIR, dir_fd=d)
+            fmeta(n, st)
+        except OSError as error:
+            os.close(d)
+            if error.errno in (errno.ELOOP, errno.ENOTDIR):
+                raise RuntimeError(f'/{rel}: /{os.path.relpath(here, mnt)} is not a folder in the machine now (a symlink or a file)')
+            raise
+        os.close(d); d = n
+    return d
+
+def lkind(name, d):
+    try:
+        st = os.stat(name, dir_fd=d, follow_symlinks=False)
+    except FileNotFoundError:
+        return None, None
+    return stat.S_IFMT(st.st_mode), st
+
+def remove(name, d):
+    """d/name removed, a folder with everything in it; the entries removed, counted. Never follows a symlink, and never
+    opens anything but a folder (O_DIRECTORY: the kernel refuses a device or FIFO swapped in before opening it)."""
+    kind, _ = lkind(name, d)
+    if kind is None: return 0
+    if kind != stat.S_IFDIR:
+        os.unlink(name, dir_fd=d); return 1
+    n = os.open(name, NOFOLLOW_DIR | os.O_NONBLOCK, dir_fd=d)
+    try:
+        count = sum(remove(e, n) for e in os.listdir(n))
+    finally:
+        os.close(n)
+    os.rmdir(name, dir_fd=d)
+    return count + 1
+
+def open_regular(name, d):
+    """A live regular file opened to read, or None: opened as a path first (O_PATH: nothing of a device or FIFO runs),
+    checked, then reopened through it."""
+    try:
+        p = os.open(name, os.O_PATH | os.O_NOFOLLOW, dir_fd=d)
+    except OSError:
+        return None
+    try:
+        if not stat.S_ISREG(os.fstat(p).st_mode): return None
+        return os.open(f'/proc/self/fd/{p}', os.O_RDONLY | os.O_NOCTTY | os.O_NONBLOCK)
+    finally:
+        os.close(p)
+
+def same_file(src, name, d, st):
+    f = open_regular(name, d)
+    if f is None: return False
+    try:
+        if os.fstat(f).st_size != st.st_size: return False
+        with open(src, 'rb') as a, os.fdopen(os.dup(f), 'rb') as b:
+            while True:
+                u, v = a.read(1 << 20), b.read(1 << 20)
+                if u != v: return False
+                if not u: return True
+    finally:
+        os.close(f)
+
+def fmeta(fd, st):
+    """Owner, mode and times from the mark's stat, on an open descriptor (never a path a swap could redirect)."""
+    os.fchown(fd, st.st_uid, st.st_gid); os.fchmod(fd, stat.S_IMODE(st.st_mode)); os.utime(fd, ns=(st.st_atime_ns, st.st_mtime_ns))
+
+def lmeta(name, d, st):
+    """A symlink's owner and times (the link itself: lchown, utimensat without following)."""
+    os.chown(name, st.st_uid, st.st_gid, dir_fd=d, follow_symlinks=False)
+    os.utime(name, ns=(st.st_atime_ns, st.st_mtime_ns), dir_fd=d, follow_symlinks=False)
+
+def put(src, name, d, rel, changes):
+    """Make d/name what the mark's src is; the changes it made appended to changes."""
+    st = os.lstat(src)
+    kind, cur = lkind(name, d)
+    if stat.S_ISLNK(st.st_mode):
+        target = os.readlink(src)
+        if kind == stat.S_IFLNK and os.readlink(name, dir_fd=d) == target: return
+        remove(name, d); os.symlink(target, name, dir_fd=d); lmeta(name, d, st); changes.append(rel); return
+    if stat.S_ISREG(st.st_mode):
+        if kind == stat.S_IFREG and same_file(src, name, d, st):
+            if (cur.st_uid, cur.st_gid, stat.S_IMODE(cur.st_mode)) != (st.st_uid, st.st_gid, stat.S_IMODE(st.st_mode)):
+                f = open_regular(name, d)
+                if f is None: raise RuntimeError(f'/{rel} changed while it was being restored')
+                try: fmeta(f, st)
+                finally: os.close(f)
+                changes.append(rel)
+            return
+        tmp = f'.{name}.wm-files'
+        try: os.unlink(tmp, dir_fd=d)
+        except FileNotFoundError: pass
+        f = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW, 0o600, dir_fd=d)
+        with open(src, 'rb') as a, os.fdopen(f, 'wb') as b:
+            shutil.copyfileobj(a, b, 1 << 20); b.flush(); fmeta(b.fileno(), st)
+        if kind == stat.S_IFDIR: remove(name, d)
+        os.replace(tmp, name, src_dir_fd=d, dst_dir_fd=d); changes.append(rel); return
+    if stat.S_ISDIR(st.st_mode):
+        if kind != stat.S_IFDIR:
+            remove(name, d); os.mkdir(name, 0o700, dir_fd=d); changes.append(rel + '/')
+        n = os.open(name, NOFOLLOW_DIR, dir_fd=d)
+        try:
+            want = set(os.listdir(src))
+            for e in sorted(set(os.listdir(n)) - want):
+                remove(e, n); changes.append(f'{rel}/{e} (removed)')
+            for e in sorted(want):
+                put(os.path.join(src, e), e, n, f'{rel}/{e}', changes)
+            if kind == stat.S_IFDIR and (cur.st_uid, cur.st_gid, stat.S_IMODE(cur.st_mode)) != (st.st_uid, st.st_gid, stat.S_IMODE(st.st_mode)):
+                changes.append(rel + '/ (owner or mode)')
+            fmeta(n, st)
+        finally:
+            os.close(n)
+        return
+    # a FIFO, socket or device in the mark: left as the machine has it
+    changes.append(f'{rel} (a special file: left as it is)')
+
+rels = [rel.strip('/') for rel in paths]
+# every path checked before any is touched: a request refused changes nothing
+for rel in rels:
+    parts = rel.split('/')
+    if not rel or parts[0] in ('proc', 'sys', 'dev', 'run') or any(p in ('', '.', '..') for p in parts):
+        say({'error': f'refused: files: /{rel} cannot be restored on its own'})
+    # the folders above it: real folders in the mark's image (a symlink there would have the copy follow it)
+    here = mnt
+    for part in parts[:-1]:
+        here = os.path.join(here, part)
+        if os.path.islink(here):
+            say({'error': f'refused: files: /{rel} is under a symlink in the mark (/{os.path.relpath(here, mnt)}); name the path it leads to'})
+    # and the live side as it is now (the copy checks each component again as it goes)
+    try:
+        d = open_parent(rel, create=False)
+        if d is not None: os.close(d)
+    except RuntimeError as error:
+        say({'error': f'refused: files: {error}'})
+    if NOLINKS:
+        for tree, name in ((os.path.join(mnt, rel), 'the mark'), (os.path.join(live, rel), 'the machine now')):
+            if os.path.islink(tree): say({'error': f'refused: files: /{rel} is a symlink in {name}: its data is not under it'})
+            for dpath, dnames, fnames in os.walk(tree):
+                link = next((n for n in dnames + fnames if os.path.islink(os.path.join(dpath, n))), None)
+                if link: say({'error': f'refused: files: /{rel} holds a symlink in {name} (/{os.path.relpath(os.path.join(dpath, link), tree if name == "the mark" else live)}): its data is not all under it'})
+
+if DRY: say({'checked': ['/' + rel for rel in rels]})
+for rel in rels:
+    src = os.path.join(mnt, rel)
+    name = rel.split('/')[-1]
+    try:
+        have = os.path.lexists(src)
+        d = open_parent(rel, create=have)
+        if d is None:
+            out.append({'path': '/' + rel, 'done': 'absent', 'changes': 0}); continue
+        try:
+            if not have:
+                n = remove(name, d)
+                out.append({'path': '/' + rel, 'done': 'removed' if n else 'absent', 'changes': n}); continue
+            changes = []
+            put(src, name, d, rel, changes)
+            # each change named below the path asked for (the path itself as `.`)
+            short = [c[len(rel) + 1:] if c.startswith(rel + '/') else ('.' if c.split(' ')[0].rstrip('/') == rel else c) for c in changes]
+            out.append({'path': '/' + rel, 'done': 'restored', 'changes': len(changes), 'sample': short[:LIMIT]})
+        finally:
+            os.close(d)
+    except Exception as error:  # noqa: BLE001 - every failure is said, with what was done before it
+        done = ', '.join(o['path'] for o in out) or 'none'
+        say({'error': f'files: /{rel} failed part way ({error}); paths already back: {done}', 'paths': out})
+say({'paths': out})
+PY
+}
+
+# wm_ct_compare <snapshot dir> <path in the tree> [exact]: what going back to the snapshot would change in the machine, read
+# only: the files under <path> (the snapshot's disk image mounted read-only beside the live tree; dependency, VCS and
+# cache directories left out) and the processes (the snapshot's process tree, from its CRIU images, beside the live
+# machine's). Bounded: 30,000 files a tree and 15 s of walking, past which the answer says it is partial; regular
+# files and symlinks only (a FIFO or device is never opened). With `exact` (a path named on its own) nothing is left
+# out and a file is compared by its content, never its time. One @{...} line.
+wm_ct_compare() {
+  local snap=$1 rel=${2#/} mnt
+  case "/$rel/" in */../*|*/./*) wm_fail "compare: the path must not climb (${2})"; return 1 ;; esac
+  # a compare killed part way leaves its mount: swept here
+  for m in "$WM_SLOTDIR"/compare.* "$WM_SLOTDIR"/files.*; do [ -d "$m" ] || continue; sudo -n umount "$m" 2>/dev/null; rmdir "$m" 2>/dev/null; done
+  mnt=$(mktemp -d "$WM_SLOTDIR/compare.XXXXXX") || { wm_fail "cannot make a mount point"; return 1; }
+  # the snapshot held against a collection while it is mounted (host.sh wm_store_list reads this marker)
+  printf '%s' "$snap" > "$WM_SLOTDIR/comparing"
+  trap 'sudo -n umount "'"$mnt"'" 2>/dev/null; rmdir "'"$mnt"'" 2>/dev/null; rm -f "$WM_SLOTDIR/comparing"; trap - RETURN' RETURN
+  # read only, no journal replay (the image is crash-consistent: its machine was frozen), and nothing on it opens as a
+  # device or runs
+  sudo -n mount -o ro,loop,noload,nodev,nosuid,noexec "$snap/root.img" "$mnt" || { wm_fail "cannot mount $snap/root.img"; return 1; }
+  local pid; pid=$(sudo -n crun state "$WM_CT" 2>/dev/null | python3 -c 'import json,sys; print(json.load(sys.stdin).get("pid",0))' 2>/dev/null || echo 0)
+  sudo -n timeout 20 env PATH="$PATH" python3 - "$mnt" "$WM_ROOT" "$rel" "$snap/criu" "$pid" "${3:-}" <<'PY'
+import collections, json, os, stat, subprocess, sys, time
+mnt, live, rel, criu, init = sys.argv[1], sys.argv[2], sys.argv[3], sys.argv[4], int(sys.argv[5] or 0)
+# exact (a path named on its own, as a partial restore's preview asks): every file under it, by content, never by time
+EXACT = sys.argv[6] == 'exact'
+then_root, now_root = os.path.join(mnt, rel), os.path.join(live, rel)
+for root, base in ((then_root, mnt), (now_root, live)):  # the path stays inside each tree, symlinks resolved
+    if os.path.commonpath([os.path.realpath(root), os.path.realpath(base)]) != os.path.realpath(base):
+        print('@' + json.dumps({'error': f'compare: {rel} leaves the machine\'s tree'})); sys.exit(1)
+DEEP = set() if EXACT else {'node_modules', '.git', '.next', '.cache', '__pycache__', '.pnpm-store', '.venv', '.yarn', '.gradle', 'Pods'}
+TOP = set() if EXACT else {'dist', 'build', 'target', '.turbo', 'coverage', 'vendor', 'tmp'}  # at the top level only (a src/build is source); tmp: the harness's own temp files (CLAUDE_CODE_TMPDIR)
+MAXF, BUDGET, LIMIT, BIG = 30000, 15.0, 40, 8 << 20
+start = time.time()
+partial = []
+
+def files(root):
+    out = {}
+    if not os.path.isdir(root) or os.path.islink(root):  # one file (or symlink) compared on its own
+        st = os.lstat(root)
+        if stat.S_ISREG(st.st_mode):
+            out[os.path.basename(root)] = ('f', st.st_size, st.st_mtime_ns, root)
+        elif stat.S_ISLNK(st.st_mode):
+            out[os.path.basename(root)] = ('l', os.readlink(root), 0, root)
+        return out
+    for d, dirs, names in os.walk(root):
+        top = os.path.normpath(d) == os.path.normpath(root)
+        dirs[:] = [x for x in dirs if x not in DEEP and not (top and x in TOP)]
+        for n in names:
+            p = os.path.join(d, n)
+            try:
+                st = os.lstat(p)
+            except OSError:
+                continue
+            if stat.S_ISREG(st.st_mode):
+                out[os.path.relpath(p, root)] = ('f', st.st_size, st.st_mtime_ns, p)
+            elif stat.S_ISLNK(st.st_mode):
+                out[os.path.relpath(p, root)] = ('l', os.readlink(p), 0, p)
+            if len(out) >= MAXF or time.time() - start > BUDGET:
+                partial.append(root); return out
+    return out
+
+def same(a, b):
+    if a[0] != b[0] or a[1] != b[1]:
+        return False
+    if a[0] == 'l' or (a[2] == b[2] and not EXACT):
+        return True
+    if a[1] > BIG or time.time() - start > BUDGET:
+        return False  # large, or out of time: by size and time only
+    def reg(path):  # a regular file opened to read: never a device or FIFO swapped in, never through a final symlink
+        p = os.open(path, os.O_PATH | os.O_NOFOLLOW)
+        try:
+            if not stat.S_ISREG(os.fstat(p).st_mode): raise OSError('not a regular file')
+            return open(os.open(f'/proc/self/fd/{p}', os.O_RDONLY | os.O_NOCTTY | os.O_NONBLOCK), 'rb')
+        finally:
+            os.close(p)
+    try:
+        with reg(a[3]) as x, reg(b[3]) as y:
+            while True:
+                u, v = x.read(1 << 20), y.read(1 << 20)
+                if u != v:
+                    return False
+                if not u:
+                    return True
+    except OSError:
+        return False
+
+then = files(then_root) if os.path.lexists(then_root) else {}
+now = files(now_root) if os.path.lexists(now_root) else {}
+back = sorted(set(then) - set(now))
+gone = sorted(set(now) - set(then))
+changed = sorted(p for p in set(then) & set(now) if not same(then[p], now[p]))
+
+def ps_then():
+    r = subprocess.run(['crit', 'x', criu, 'ps'], capture_output=True, text=True)
+    if r.returncode != 0:
+        raise RuntimeError((r.stderr or 'crit failed').strip().splitlines()[-1][:200])
+    return [row.split(None, 3)[3].strip() for row in r.stdout.splitlines()[1:] if len(row.split(None, 3)) == 4]
+
+def ps_now():
+    if not init:
+        return []
+    ns = os.readlink(f'/proc/{init}/ns/pid')
+    out = []
+    for p in os.listdir('/proc'):
+        if p.isdigit():
+            try:
+                if os.readlink(f'/proc/{p}/ns/pid') == ns:
+                    out.append(open(f'/proc/{p}/comm').read().strip())
+            except OSError:
+                pass
+    return out
+
+try:
+    pt, pn = collections.Counter(ps_then()), collections.Counter(ps_now())
+    procs = {'restarted': sorted((pt - pn).elements())[:LIMIT], 'stopped': sorted((pn - pt).elements())[:LIMIT],
+             'then': sum(pt.values()), 'now': sum(pn.values())}
+except Exception as error:
+    procs = {'unknown': str(error)}
+print('@' + json.dumps({
+    'files': {'back': back[:LIMIT], 'gone': gone[:LIMIT], 'changed': changed[:LIMIT],
+              'counts': {'back': len(back), 'gone': len(gone), 'changed': len(changed)},
+              'skipped': sorted(DEEP | TOP), 'partial': bool(partial)},
+    'processes': procs,
+}))
+PY
+}