@volter/world-machine 2.0.0

package/src/gc.ts

@@ -0,0 +1,129 @@
+// Snapshot retention: a snapshot is kept while any existing branch's machine ledger (its whole view,
+// the parent's history included) names it; everything else in the store goes. Each snapshot directory
+// is self-contained (its memory and disk are reflink copies, never references to another directory), so
+// deleting one never breaks another.
+//
+// The store is shared by every World whose machine runs on this host, so each `serve` registers its
+// World in the store (`roots.json`: the World's branch directory, `<app>/.volter/worlds`, or the
+// service root itself when it is not laid out that way). A collection reads every registered World's
+// branches (a registration whose directory is gone is dropped), and deletes:
+//   - snapshot directories no ledger names, unless a checkpoint is still writing them (`.pending`) or a
+//     slot's machine was loaded from them;
+//   - warm bases no kept snapshot was built on (on the container backend, none a branch's head was not taken on: its
+//     snapshots never read their base), unless it is this configuration's base, a slot's machine was loaded from it,
+//     or it is still being built;
+//   - the container backend's filled trees (tree-<hash>) but this configuration's and those a kept base was made from;
+// then trims the store's filesystem so the space goes back to the host. A ledger that cannot be read
+// stops the collection: nothing is deleted on a partial view.
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { wholeLog } from '@volter/world-core';
+import type { MachineConfig } from './config.ts';
+import { type HostSession, q } from './host.ts';
+import { headSnapshot, LEDGER } from './ledger.ts';
+import { containerHashes } from './container.ts';
+import { baseHash } from './machine.ts';
+import { thinned } from './thin.ts';
+
+/** What `serve` registers for a service root: the World's branch directory when the root is a branch's
+ *  service data directory (`<app>/.volter/worlds/<branch>/data/<service>`), else the root itself. */
+export function registration(root: string): string {
+  const m = /^(.*\/\.volter\/worlds)\/[^/]+\/data\/[^/]+\/?$/.exec(root);
+  return m ? m[1]! : root;
+}
+
+/** Every machine service root a registration covers. */
+function machineRoots(registered: string): string[] {
+  if (basename(registered) === 'worlds') {
+    return readdirSync(registered)
+      .filter((b) => !b.startsWith('.'))
+      .map((b) => join(registered, b, 'data', LEDGER))
+      .filter((r) => existsSync(r) && statSync(r).isDirectory());
+  }
+  return [registered];
+}
+
+export async function register(session: HostSession, root: string): Promise<void> {
+  await session.call(`wm_register ${q(registration(root))}`);
+}
+
+export type GcReport = {
+  roots: string[]; dropped: string[]; branches: number; live: number;
+  deletedSnapshots: string[]; deletedBases: string[]; deletedTrees: string[]; expired: string[]; kept: { pending: string[]; loaded: string[] };
+  usedBefore: number; usedAfter: number; freedBytes: number; trimmed: string;
+};
+
+export async function collect(config: MachineConfig, session: HostSession, own?: string): Promise<GcReport> {
+  const store = await session.call<{ roots: string[]; snapshots: string[]; bases: string[]; trees: string[]; baseTrees: Record<string, string>; pending: string[]; loaded: string[] }>('wm_store_list');
+  const roots = store.roots.filter((r) => existsSync(r));
+  const dropped = store.roots.filter((r) => !roots.includes(r));
+  const liveDirs = new Set<string>();
+  const liveBases = new Set<string>();
+  const heads = new Set<string>();
+  const ownDirs = new Set<string>();
+  const othersDirs = new Set<string>();
+  const keepDirs = new Set<string>();
+  let branches = 0;
+  for (const registered of roots) {
+    const mine = own !== undefined && registered === registration(own);
+    for (const r of machineRoots(registered)) {
+      branches++;
+      let log;
+      try { log = wholeLog(LEDGER, r); } catch (error) {
+        throw new Error(`world-machine gc: cannot read the machine ledger at ${r} (${(error as Error).message}); nothing was deleted`);
+      }
+      for (const e of log) {
+        if (e.op !== 'set' || e.subject.type !== 'snapshot') continue;
+        const f = e.fields as { dir?: string; base?: string };
+        if (f.dir) { liveDirs.add(basename(f.dir)); (mine ? ownDirs : othersDirs).add(basename(f.dir)); }
+        if (f.dir && (e.fields as { keep?: boolean }).keep) keepDirs.add(basename(f.dir));
+        // a Firecracker snapshot is kept with the base it was built on; a container snapshot never reads its base (a
+        // restore reads the snapshot's own tree and dump, and a machine with no head the configured base), so there only
+        // the configured base, heads' bases (below) and a running machine's stay
+        if (f.base && config.backend !== 'container') liveBases.add(f.base);
+      }
+      const head = headSnapshot(r);
+      if (head) heads.add(basename(head.dir));
+      // on the container backend the base a branch's head was taken on stays (another World on this store, configured
+      // otherwise, starts a branch with no head from it); a base only older heads named goes once each moves on
+      if (head?.base && config.backend === 'container') liveBases.add(head.base);
+    }
+  }
+  // Retention (config `retain`): every branch's head stays (a World resumes at it), and the newest `retain` others (with
+  // `thin`, also the newest of each hour for a day and of each day for a month, and every snapshot taken with `keep`); the
+  // rest are let go though a ledger names them, and recorded so that a restore of one says it expired
+  // Only the calling World's own snapshots are counted: `retain` is its configuration, and another World on the store
+  // keeps its own, including a snapshot both name (a World's ledgers copied from another). They are ranked by when the host took them (the time in the snapshot's id), never by the World's
+  // clock, which a World can freeze (every mark would tie).
+  const expired: string[] = [];
+  if (config.retain && own) {
+    const present = new Set(store.snapshots);
+    const taken = (d: string): number => { const m = /^snap-([0-9a-z]+)-/.exec(d); return m ? parseInt(m[1]!, 36) : 0; };
+    const others = [...ownDirs].filter((d) => !heads.has(d) && !othersDirs.has(d) && present.has(d)).sort((a, b) => taken(b) - taken(a) || b.localeCompare(a));
+    // thinned with age (thin.ts), or the newest `retain` only
+    const stay = config.thin ? thinned(others.map((d) => ({ dir: d, takenMs: taken(d), keep: keepDirs.has(d) })), Date.now(), { retain: config.retain }) : new Set(others.slice(0, config.retain));
+    for (const d of others) if (!stay.has(d)) { liveDirs.delete(d); expired.push(d); }
+  }
+  const loaded = new Set(store.loaded.map((p) => basename(p.replace(/\/+$/, ''))));
+  const pending = new Set(store.pending);
+  const hashes = config.backend === 'container' ? await containerHashes(config, session) : { base: await baseHash(config, session), tree: '' };
+  const configured = `base-${hashes.base}`;
+  const deletedSnapshots = store.snapshots.filter((s) => !liveDirs.has(s) && !pending.has(s) && !loaded.has(s));
+  const deletedBases = store.bases.filter((b) => !liveBases.has(b) && b !== configured && !loaded.has(b) && !b.endsWith('.building'));
+  // the container backend's filled trees (tree-<hash>): only this configuration's is kept (a base's own root.img shares
+  // its blocks, so a tree whose image or fill moved on holds only what nothing else does)
+  // (bases being built included: each names its tree from its first step; a tree being saved is tree-<hash>.part-<slot>)
+  const keptTrees = new Set(store.bases.filter((b) => !deletedBases.includes(b)).map((b) => store.baseTrees[b]).filter(Boolean));
+  const treeOf = (t: string): string => t.replace(/\.part-[a-z0-9-]+$/, '');
+  const deletedTrees = store.trees.filter((t) => treeOf(t) !== `tree-${hashes.tree}` && !keptTrees.has(treeOf(t)));
+  const paths = [...deletedSnapshots.map((s) => `snapshots/${s}`), ...deletedBases, ...deletedTrees];
+  const expiring = expired.filter((d) => deletedSnapshots.includes(d));
+  const done = await session.call<{ usedBefore: number; usedAfter: number; trimmed: string }>(
+    `${expiring.length ? `printf '%s\\n' ${expiring.map(q).join(' ')} >> "$WM_STORE/expired.list"\n` : ''}wm_gc_delete ${q(JSON.stringify(dropped))} ${paths.map(q).join(' ')}`);
+  return {
+    roots, dropped, branches, live: liveDirs.size, deletedSnapshots, deletedBases, deletedTrees, expired: expiring,
+    kept: { pending: [...pending], loaded: [...loaded] },
+    usedBefore: done.usedBefore, usedAfter: done.usedAfter, freedBytes: Math.max(0, done.usedBefore - done.usedAfter), trimmed: done.trimmed,
+  };
+}
+

package/src/guest-inject.test.ts

@@ -0,0 +1,21 @@
+// The guest's copy of the injector is a hand list of files (GUEST_INJECT): every file the injector and the files it
+// loads `require` by relative path must be on it, or every Node process in a machine fails at its preload (the §9
+// review of the app-route move, 2026-09-27). Checked by loading the list, as the guest does, in an empty directory.
+import { expect, test } from 'bun:test';
+import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { GUEST_INJECT } from './host.ts';
+
+test('the guest injector loads from exactly the files written into the guest', async () => {
+  const dir = mkdtempSync(join(tmpdir(), 'guest-inject-'));
+  for (const [file, body] of Object.entries(GUEST_INJECT)) {
+    mkdirSync(dirname(join(dir, file)), { recursive: true });
+    writeFileSync(join(dir, file), body);
+  }
+  const child = Bun.spawn(['node', '--require', join(dir, 'inject.cjs'), '-e', 'console.log("loaded")'], { stdout: 'pipe', stderr: 'pipe', env: { PATH: process.env.PATH ?? '' } });
+  const [out, err] = await Promise.all([new Response(child.stdout).text(), new Response(child.stderr).text()]);
+  await child.exited;
+  expect(err).toBe('');
+  expect(out.trim()).toBe('loaded');
+}, 30_000);

package/src/host.sh

@@ -0,0 +1,302 @@
+# The machine host's half of @volter/world-machine: sourced once into the persistent shell the service
+# holds on the machine host (the Linux box itself, or the Lima VM on a Mac). Every function prints its
+# result as one `@{json}` line; diagnostics go to stderr, which the session folds into the output.
+# The caller sets WM_STORE, WM_SLOT, WM_FC, WM_SE, WM_KEY, WM_TAP, WM_HOSTIP, WM_GUESTIP before sourcing.
+WM_SLOTDIR="$WM_STORE/slots/$WM_SLOT"
+WM_SOCK="$WM_SLOTDIR/api.sock"
+WM_AGENT_PORT=7070
+
+wm_ns() { date +%s%N; }
+# wm_timed <name> <command...>: runs it and reports `<name>Ms`
+wm_timed() { local n="$1" s="$EPOCHREALTIME" rc e; shift; "$@"; rc=$?; e="$EPOCHREALTIME"; printf '@{"%sMs":%s}\n' "$n" "$(( (${e/./} - ${s/./}) / 1000 ))"; return $rc; }
+wm_ms_since() { echo $(( ($(date +%s%N) - $1) / 1000000 )); }
+wm_fail() { printf '@{"error":%s}\n' "$(printf '%s' "$*" | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))')"; return 1; }
+
+# A job backgrounded from a function of this session holds the copies bash keeps of the session's own descriptors while
+# the function runs with redirections (the service's pipes, the slot lock): `world-machine base` stayed until its tree's
+# fill ended (23 s measured). Such a job closes them first; one that execs a program does not need to (they close on exec).
+# (listed first, and closed with no redirection of its own: one would be saved to a high descriptor the loop then closes,
+# leaving stderr lost)
+wm_closefds() { local fds=(/proc/$BASHPID/fd/*) f n; for f in "${fds[@]}"; do n=${f##*/}; case "$n" in 0|1|2|*[!0-9]*) ;; *) eval "exec $n>&-" ;; esac; done; return 0; }
+
+wm_init() {
+  mkdir -p "$WM_STORE/snapshots" "$WM_SLOTDIR" || return 1
+  printf '@{"home":"%s","store":"%s"}\n' "$HOME" "$WM_STORE"
+}
+
+# A reflink-capable store is a precondition, never a preference: a whole-image copy dominated every
+# pause it was part of (1–13 s measured), so there is no fallback to one.
+wm_reflink_check() {
+  local probe="$WM_STORE/.reflink-probe"
+  head -c 4096 /dev/zero > "$probe" 2>/dev/null || { wm_fail "cannot write the store $WM_STORE"; return 1; }
+  if ! cp --reflink=always "$probe" "$probe.clone" 2>/dev/null; then
+    rm -f "$probe" "$probe.clone"
+    wm_fail "the store $WM_STORE is on $(stat -f -c %T "$WM_STORE") and cannot reflink; world-machine needs XFS (reflink=1) or btrfs there and never falls back to a full copy (run \`world-machine setup --make-store <size>\`)"
+    return 1
+  fi
+  rm -f "$probe" "$probe.clone"
+  wm_store_dio
+  printf '@{"reflink":true,"fs":"%s"}\n' "$(stat -f -c %T "$WM_STORE")"
+}
+
+# A store that is a loop image (setup --make-store) reads and writes its backing file with direct I/O: through the
+# page cache every page was cached twice, and a mark's 1.3 GB dump waited on writeback with the memory full
+# (measured: 7.5 s paused, 0.7-1.0 s with direct I/O). fstab cannot ask for it, so it is set here, on each use.
+wm_store_dio() {
+  local dev; dev=$(findmnt -no SOURCE --target "$WM_STORE" 2>/dev/null); dev=${dev%%[*}
+  case "$dev" in /dev/loop*) [ "$(cat "/sys/block/${dev#/dev/}/loop/dio" 2>/dev/null)" = 1 ] || sudo -n losetup --direct-io=on "$dev" 2>/dev/null || true ;; esac
+}
+
+# The guest's one link: a tap with the host end at WM_HOSTIP, forwarding from it dropped.
+wm_net() {
+  [ -n "$WM_NET_READY" ] && { printf '@{"tap":"%s"}\n' "$WM_TAP"; return 0; }
+  if ! ip link show "$WM_TAP" >/dev/null 2>&1; then
+    sudo -n ip tuntap add "$WM_TAP" mode tap user "$(id -un)" || { wm_fail "cannot create tap $WM_TAP (needs sudo; run world-machine setup)"; return 1; }
+    sudo -n ip addr add "$WM_HOSTIP/30" dev "$WM_TAP" && sudo -n ip link set "$WM_TAP" up || { wm_fail "cannot address tap $WM_TAP"; return 1; }
+  fi
+  if command -v iptables >/dev/null && ! sudo -n iptables -C FORWARD -i "$WM_TAP" -j DROP 2>/dev/null; then
+    sudo -n iptables -I FORWARD -i "$WM_TAP" -j DROP 2>/dev/null || true
+  fi
+  WM_NET_READY=1
+  printf '@{"tap":"%s"}\n' "$WM_TAP"
+}
+
+wm_api() {
+  local code
+  code=$(curl -s --unix-socket "$WM_SOCK" -X "$1" "http://localhost/$2" -H 'Content-Type: application/json' ${3:+-d "$3"} -o "$WM_SLOTDIR/api.out" -w '%{http_code}')
+  case "$code" in 2*) return 0 ;; esac
+  wm_fail "firecracker $1 /$2 answered $code: $(cat "$WM_SLOTDIR/api.out" 2>/dev/null)"
+}
+
+wm_fc_pid() {
+  local pid
+  pid=$(cat "$WM_SLOTDIR/fc.pid" 2>/dev/null) || return 1
+  [ -n "$pid" ] && [ -r "/proc/$pid/comm" ] && case "$(cat /proc/$pid/comm)" in firecracker*) echo "$pid"; return 0 ;; esac
+  return 1
+}
+
+wm_fc_stop() {
+  local pid i
+  if pid=$(wm_fc_pid); then
+    kill -KILL "$pid" 2>/dev/null
+    for i in $(seq 1 400); do [ -d "/proc/$pid" ] || break; sleep 0.005; done
+  fi
+  rm -f "$WM_SLOTDIR/fc.pid" "$WM_SOCK"
+}
+
+wm_fc_start() {
+  local i
+  rm -f "$WM_SOCK"
+  # the pid is written by the process that becomes firecracker (setsid may fork, so $! can be its parent).
+  # `exec`: the backgrounded `cd && …` list is a forked copy of this session's shell, holding the session's
+  # stdout; without it that copy waits on Firecracker for the machine's whole life, so the service's pipe to
+  # this shell never closes (on Linux `world-machine base` then never exits; over Lima's ssh it was hidden)
+  ( cd "$WM_SLOTDIR" && exec setsid bash -c 'echo $$ > "$1"; shift; exec "$@"' _ "$WM_SLOTDIR/fc.pid" "$WM_FC" --api-sock "$WM_SOCK" > "$WM_SLOTDIR/fc.log" 2>&1 < /dev/null & )
+  for i in $(seq 1 1000); do [ -S "$WM_SOCK" ] && return 0; sleep 0.002; done
+  wm_fail "firecracker did not open $WM_SOCK: $(tail -3 "$WM_SLOTDIR/fc.log")"
+}
+
+wm_running() {
+  local pid state='stopped'
+  if pid=$(wm_fc_pid); then
+    state=$(curl -s --unix-socket "$WM_SOCK" http://localhost/ 2>/dev/null | python3 -c 'import json,sys
+try: print(json.load(sys.stdin).get("state","unknown"))
+except Exception: print("unknown")')
+  fi
+  printf '@{"fc":"%s","owner":%s}\n' "$state" "$(cat "$WM_SLOTDIR/owner.json" 2>/dev/null || echo null)"
+}
+
+wm_own() { printf '%s\n' "$1" > "$WM_SLOTDIR/owner.json"; }
+wm_release() { rm -f "$WM_SLOTDIR/owner.json"; }
+
+# wm_boot <kernel> <disk-source> <vcpus> <mem-mib> <boot-args>: a cold boot on a reflink clone of the source disk.
+wm_boot() {
+  wm_fc_stop
+  cp --reflink=always "$2" "$WM_SLOTDIR/disk.ext4" || { wm_fail "cannot reflink $2 into the slot"; return 1; }
+  wm_fc_start || return 1
+  wm_api PUT machine-config "{\"vcpu_count\":$3,\"mem_size_mib\":$4,\"track_dirty_pages\":true}" || return 1
+  wm_api PUT boot-source "{\"kernel_image_path\":\"$1\",\"boot_args\":\"$5\"}" || return 1
+  wm_api PUT drives/rootfs "{\"drive_id\":\"rootfs\",\"path_on_host\":\"$WM_SLOTDIR/disk.ext4\",\"is_root_device\":true,\"is_read_only\":false}" || return 1
+  wm_api PUT network-interfaces/eth0 "{\"iface_id\":\"eth0\",\"host_dev_name\":\"$WM_TAP\",\"guest_mac\":\"06:00:AC:10:00:02\"}" || return 1
+  wm_api PUT actions '{"action_type":"InstanceStart"}' || return 1
+  printf '@{"booted":true}\n'
+}
+
+# wm_snapshot <dir> <Full|Diff>: the pause. Memory (all of it, or the pages dirtied since the last
+# snapshot or load) and the device state are written, the disk is reflink-cloned beside them, and the
+# guest runs again. A diff and the device state are written to memory (/dev/shm) and moved into the
+# store after the guest resumes: written into the store they made the pause (447 ms for 13 MB measured
+# on a loaded Mac). The disk's dirty pages are flushed before pausing, since a clone flushes them first.
+wm_snapshot() {
+  local d="$1" mem state t0 tw tp shm="/dev/shm/wm-$WM_SLOT-$$"
+  mkdir -p "$d" || return 1
+  if [ "$2" = Diff ]; then mem="$shm.diff"; state="$shm.vmstate"; else mem="$d/mem"; state="$d/vmstate"; fi
+  sync "$WM_SLOTDIR/disk.ext4"
+  t0=$(wm_ns)
+  wm_api PATCH vm '{"state":"Paused"}' || return 1
+  tp=$(wm_ns)
+  if ! wm_api PUT snapshot/create "{\"snapshot_type\":\"$2\",\"snapshot_path\":\"$state\",\"mem_file_path\":\"$mem\"}"; then wm_api PATCH vm '{"state":"Resumed"}'; return 1; fi
+  tw=$(wm_ns)
+  if ! cp --reflink=always "$WM_SLOTDIR/disk.ext4" "$d/disk.ext4"; then wm_api PATCH vm '{"state":"Resumed"}'; wm_fail "cannot reflink the disk into $d"; return 1; fi
+  wm_api PATCH vm '{"state":"Resumed"}' || return 1
+  printf '@{"pauseMs":%s,"memWriteMs":%s,"diskCloneMs":%s,"memBytes":%s}\n' \
+    "$(( ($(wm_ns) - t0) / 1000000 ))" "$(( (tw - tp) / 1000000 ))" "$(( ($(wm_ns) - tw) / 1000000 ))" "$(du -B1 "$mem" | cut -f1)"
+  WM_LAST_DIFF="$mem"
+  if [ "$2" = Diff ]; then mv "$state" "$d/vmstate" || { rm -f "$state" "$mem"; wm_fail "cannot move the device state into $d"; return 1; }; fi
+}
+
+# wm_materialize <parent-mem> <dir>: one full memory file per entry, so a restore loads one file:
+# a reflink copy of the parent's, with the diff wm_snapshot left in /dev/shm applied by Firecracker's
+# snapshot-editor.
+wm_materialize() {
+  local t0; t0=$(wm_ns)
+  cp --reflink=always "$1" "$2/mem.tmp" || { rm -f "$WM_LAST_DIFF"; wm_fail "cannot reflink $1"; return 1; }
+  if ! "$WM_SE" edit-memory rebase --memory-path "$2/mem.tmp" --diff-path "$WM_LAST_DIFF" >/dev/null; then rm -f "$WM_LAST_DIFF"; wm_fail "snapshot-editor rebase failed for $2"; return 1; fi
+  mv "$2/mem.tmp" "$2/mem" && rm -f "$WM_LAST_DIFF"
+  printf '@{"materializeMs":%s}\n' "$(wm_ms_since "$t0")"
+}
+
+# wm_restore <dir>: in place. The slot's process is replaced, the disk becomes a reflink clone of the
+# snapshot's, and the memory file is loaded as the backing of guest memory, resumed.
+wm_restore() {
+  local d="$1" t0 tl
+  [ -f "$d/vmstate" ] && [ -f "$d/mem" ] && [ -f "$d/disk.ext4" ] || { wm_fail "snapshot $d is incomplete"; return 1; }
+  t0=$(wm_ns)
+  wm_fc_stop
+  cp --reflink=always "$d/disk.ext4" "$WM_SLOTDIR/disk.ext4" || { wm_fail "cannot reflink the disk of $d"; return 1; }
+  wm_fc_start || return 1
+  tl=$(wm_ns)
+  wm_api PUT snapshot/load "{\"snapshot_path\":\"$d/vmstate\",\"mem_backend\":{\"backend_type\":\"File\",\"backend_path\":\"$d/mem\"},\"track_dirty_pages\":true,\"resume_vm\":true}" || return 1
+  printf '%s' "$d" > "$WM_SLOTDIR/loaded"   # what the collector must keep while this machine runs
+  printf '@{"loadMs":%s,"restoreMs":%s}\n' "$(wm_ms_since "$tl")" "$(wm_ms_since "$t0")"
+}
+
+# Retention (gc.ts). The store's registry of Worlds, kept under a lock since every serve writes it.
+wm_register() {
+  ( flock 9; python3 - "$WM_STORE/roots.json" "$1" <<'PY'
+import json, os, sys
+path, root = sys.argv[1:3]
+roots = json.load(open(path)) if os.path.exists(path) else []
+if root not in roots: roots.append(root)
+tmp = path + '.tmp'; json.dump(roots, open(tmp, 'w'), indent=1); os.replace(tmp, path)
+PY
+  ) 9> "$WM_STORE/.roots.lock" || { wm_fail "cannot register $1 in $WM_STORE/roots.json"; return 1; }
+  printf '@{"registered":%s}\n' "$(printf '%s' "$1" | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))')"
+}
+
+# The store as the collector sees it: registered Worlds, snapshot directories (those a checkpoint is still
+# writing marked pending), warm bases, and what each slot's machine was loaded from.
+wm_store_list() {
+  python3 - "$WM_STORE" <<'PY'
+import json, os, sys
+s = sys.argv[1]
+ls = lambda d: sorted(os.listdir(d)) if os.path.isdir(d) else []
+snaps = [n for n in ls(os.path.join(s, 'snapshots')) if os.path.isdir(os.path.join(s, 'snapshots', n))]
+loaded = []
+for slot in ls(os.path.join(s, 'slots')):
+    # only a slot whose Firecracker is running holds what it was loaded from
+    f, pid = os.path.join(s, 'slots', slot, 'loaded'), os.path.join(s, 'slots', slot, 'fc.pid')
+    try: running = open('/proc/%s/comm' % open(pid).read().strip()).read().startswith('firecracker')
+    except OSError: running = False
+    if running:
+        try: loaded.append(open(f).read().strip())
+        except OSError: pass
+    # a container slot being restored or prepared holds the snapshot it is reading (ct.sh wm_ct_restore, container.ts
+    # prepare), and a prepared slot the snapshot it hands over, until the branch adopting it names it in its ledger; a
+    # container slot holds what its machine was restored from (ct-loaded) until that machine's service stops
+    for name in ('restoring', 'preparing', 'ct-loaded', 'comparing'):  # comparing: ct.sh wm_ct_compare's mount
+        try: loaded.append(open(os.path.join(s, 'slots', slot, name)).read().strip())
+        except OSError: pass
+    try: handover = json.load(open(os.path.join(s, 'slots', slot, 'owner.json'))).get('handover')
+    except (OSError, ValueError, AttributeError): handover = None
+    if handover: loaded.append(handover)
+roots = json.load(open(os.path.join(s, 'roots.json'))) if os.path.exists(os.path.join(s, 'roots.json')) else []
+# each container base's (or base build's) filled tree; one deleted during the scan names none
+base_trees = {}
+for n in ls(s):
+    if not n.startswith('base-'): continue
+    try: base_trees[n] = open(os.path.join(s, n, 'tree')).read().strip()
+    except OSError: pass
+print('@' + json.dumps({'roots': roots, 'snapshots': snaps, 'pending': [n for n in snaps if os.path.exists(os.path.join(s, 'snapshots', n, '.pending'))],
+  'bases': [n for n in ls(s) if n.startswith('base-')], 'trees': [n for n in ls(s) if n.startswith('tree-')],
+  'baseTrees': base_trees, 'loaded': loaded}))
+PY
+}
+
+# wm_gc_delete <dropped-roots-json> <store-relative path...>: delete, drop the gone registrations, give the
+# space back to the host (fstrim on the store's filesystem), and report the store's use before and after.
+wm_gc_delete() {
+  local dropped="$1" before after p mnt trimmed=""; shift
+  sync -f "$WM_STORE"; before=$(df -B1 --output=used "$WM_STORE" | tail -1 | tr -d ' ')
+  for p in "$@"; do case "$p" in snapshots/snap-*|base-*|tree-*) rm -rf -- "${WM_STORE:?}/$p" ;; *) wm_fail "refusing to delete $p"; return 1 ;; esac; done
+  ( flock 9; python3 - "$WM_STORE/roots.json" "$dropped" <<'PY'
+import json, os, sys
+path, dropped = sys.argv[1], set(json.loads(sys.argv[2]))
+if os.path.exists(path):
+    roots = [r for r in json.load(open(path)) if r not in dropped]
+    tmp = path + '.tmp'; json.dump(roots, open(tmp, 'w'), indent=1); os.replace(tmp, path)
+PY
+  ) 9> "$WM_STORE/.roots.lock"
+  mnt=$(findmnt -n -o TARGET --target "$WM_STORE")
+  # the deletes committed first: btrfs frees their extents only then, and a trim before it gave nothing back (measured:
+  # 1.66 GB deleted, the store's image unchanged until a later trim returned 1.45 GB)
+  sync -f "$WM_STORE"
+  trimmed=$(sudo -n fstrim -v "$mnt" 2>&1 | tail -1)
+  sync -f "$WM_STORE"; after=$(df -B1 --output=used "$WM_STORE" | tail -1 | tr -d ' ')
+  printf '@{"usedBefore":%s,"usedAfter":%s,"trimmed":%s}\n' "$before" "$after" "$(printf '%s' "$trimmed" | python3 -c 'import json,sys; print(json.dumps(sys.stdin.read()))')"
+}
+
+# wm_room <bytes> [path...]: refused (wm_fail) unless every filesystem a store write lands on has <bytes> free: the
+# store, the file backing it when it is a loop image (a sparse XFS image promises room its backing filesystem may not
+# have), and each path named (on a Mac, the home the Lima VM mounts: its free space is the Mac's, beneath the VM's own
+# sparse disk). A write the lowest layer cannot hold fails as an I/O error in the layers above it, which is how a
+# store is corrupted; a mark refused first is only a mark not taken.
+wm_room() {
+  local need="$1" p dev back line av tg least="" at=""; shift
+  set -- "$WM_STORE" "$@"
+  dev=$(findmnt -no SOURCE --target "$WM_STORE" 2>/dev/null); dev=${dev%%[*}   # btrfs names a subvolume: /dev/loop0[/sub]
+  case "$dev" in /dev/loop*) back=$(losetup -nO BACK-FILE "$dev" 2>/dev/null | tr -d ' '); [ -n "$back" ] && set -- "$@" "$(dirname "$back")" ;; esac
+  for p in "$@"; do
+    [ -e "$p" ] || continue
+    line=$(df -B1 --output=avail,target "$p" 2>/dev/null | tail -1) || continue
+    read -r av tg <<<"$line"
+    if [ -z "$least" ] || [ "$av" -lt "$least" ]; then least=$av; at=$tg; fi
+  done
+  [ -n "$least" ] || { wm_fail "cannot read the free space under $WM_STORE"; return 1; }
+  [ "$least" -ge "$need" ] || { wm_fail "no room for a mark: $at has $((least / 1048576)) MB free and a mark needs about $((need / 1048576)) MB there (its estimate and the reserve); nothing was written. Free space there, or collect the snapshots no branch names (world-machine gc)"; return 1; }
+  printf '@{"room":%s,"at":"%s"}\n' "$least" "$at"
+}
+
+# the store's used bytes, after a syncfs: XFS frees an unlinked file's blocks in the background, and
+# a df read without it counted a just-deleted memory diff (+43 MB measured)
+wm_used() { sync -f "$WM_STORE"; printf '@{"used":%s}\n' "$(df -B1 --output=used "$WM_STORE" | tail -1 | tr -d ' ')"; }
+
+# wm_egress <host-port>=<target-host>:<target-port> ...: the guest's only way out. Each stable
+# guest-visible port on the tap's host address forwards to one twin of the World that owns the slot.
+wm_egress() {
+  local pid m
+  # unchanged and all alive: nothing to re-point
+  if [ "$*" = "$(cat "$WM_SLOTDIR/egress.spec" 2>/dev/null)" ] && [ -s "$WM_SLOTDIR/egress.pids" ]; then
+    m=0; for pid in $(cat "$WM_SLOTDIR/egress.pids"); do [ "$(cat /proc/$pid/comm 2>/dev/null)" = socat ] || m=1; done
+    [ "$m" = 0 ] && { printf '@{"forwarders":%s,"unchanged":true}\n' "$#"; return 0; }
+  fi
+  for pid in $(cat "$WM_SLOTDIR/egress.pids" 2>/dev/null); do
+    [ -r "/proc/$pid/comm" ] && [ "$(cat /proc/$pid/comm)" = socat ] && kill "$pid" 2>/dev/null
+  done
+  : > "$WM_SLOTDIR/egress.pids"
+  for m in "$@"; do
+    # to this host's loopback, from 127.0.0.2: the World's proxy knows a machine's connection by it and keeps the
+    # machine off this host's own network (world-runtime redirect-proxy.ts isGuestSource)
+    local src=""; case "${m#*=}" in 127.*|localhost:*) src=",bind=127.0.0.2" ;; esac
+    # 9>&-: the container backend's slot lock (host.ts) is never held by a forwarder that outlives the shell
+    setsid bash -c 'echo $$ >> "$1"; shift; exec "$@"' _ "$WM_SLOTDIR/egress.pids" socat "TCP-LISTEN:${m%%=*},bind=$WM_HOSTIP,fork,reuseaddr" "TCP:${m#*=}$src" > /dev/null 2>&1 < /dev/null 9>&- &
+  done
+  printf '%s' "$*" > "$WM_SLOTDIR/egress.spec"
+  printf '@{"forwarders":%s}\n' "$#"
+}
+
+# The guest agent (agent.py, inside the guest): the clock and the World's env file.
+wm_agent() { python3 "$WM_SLOTDIR/agentc.py" "$WM_GUESTIP" "$WM_AGENT_PORT" "$@"; }
+
+# bounded: under load a guest ssh login has taken 18 s
+wm_gssh() { timeout "${WM_GSSH_TIMEOUT:-20}" ssh -q -i "$WM_KEY" -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -o ConnectTimeout=2 -o BatchMode=yes "root@$WM_GUESTIP" "$@"; }

package/src/host.ts

@@ -0,0 +1,161 @@
+// The machine host: where Firecracker runs. On Linux it is this box; on a Mac it is a Lima (>= 2) VM
+// with nested virtualization, reached over Lima's own ssh config. Either way the service holds ONE
+// persistent bash session on it (a new ssh or bash per operation cost 75-125 ms on a loaded Mac) with
+// host.sh sourced, and every operation is one round trip over that session.
+import { spawn, type ChildProcessWithoutNullStreams } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { MachineConfig } from './config.ts';
+
+const HOST_LIB = readFileSync(new URL('./host.sh', import.meta.url), 'utf8');
+/** The container backend's functions, sourced after HOST_LIB when the config names that backend. */
+const CT_LIB = readFileSync(new URL('./ct.sh', import.meta.url), 'utf8');
+const AGENT_CLIENT = readFileSync(new URL('./agentc.py', import.meta.url), 'utf8');
+/** The container backend's page composer (compose.py), run detached on the host after each mark. */
+const COMPOSER = readFileSync(new URL('./compose.py', import.meta.url), 'utf8');
+/** The container backend's port publisher (publish.py), run detached on the host while the machine runs. */
+const PUBLISHER = readFileSync(new URL('./publish.py', import.meta.url), 'utf8');
+export const GUEST_AGENT = readFileSync(new URL('./agent.py', import.meta.url), 'utf8');
+
+/** world-core's zero-edit redirect (a real SDK's vendor host to its twin, by the *_TWIN_URL variables) and the files it
+ *  loads, written into the guest at GUEST_INJECT_DIR at every start and restore: an app in the machine reaches the twins
+ *  as `volter world run` does. */
+export const GUEST_INJECT_DIR = '/opt/volter-world';
+const core = (spec: string): string => readFileSync(fileURLToPath(import.meta.resolve(`@volter/world-core/${spec}`)), 'utf8');
+export const GUEST_INJECT: Record<string, string> = {
+  'inject.cjs': core('inject'), 'network-policy.cjs': core('network-policy'), 'app-route.cjs': core('app-route'),
+  'vendor-hosts.cjs': core('vendor-hosts'),
+  'generated/pack-facts.json': core('generated/pack-facts.json'),
+};
+/** Every login shell in the guest exports the World's env file (KEY=value lines, written at each start and restore). */
+export const GUEST_PROFILE = `[ -r /etc/world.env ] && while IFS= read -r l; do case "$l" in ''|'#'*) ;; *=*) export "$l" ;; esac; done < /etc/world.env`;
+
+/** A sub-millisecond wall clock on the World's host. */
+export const hostNowMs = (): number => performance.timeOrigin + performance.now();
+
+/** Single-quote a string for bash. */
+export const q = (s: string): string => `'${s.replace(/'/g, `'\\''`)}'`;
+
+export class HostSession {
+  private child: ChildProcessWithoutNullStreams | undefined;
+  private buffer = '';
+  private waiter: { marker: string; resolve: (v: { status: number; out: string }) => void; reject: (e: Error) => void } | undefined;
+  private queue: Promise<unknown> = Promise.resolve();
+  /** The machine host's clock minus this host's, in seconds; measured at open and before each clock step. */
+  offsetS = 0;
+
+  constructor(private readonly config: MachineConfig) {}
+
+  // Its own process group: the World stops a service by signalling its group, and the session must
+  // outlive that signal long enough to release the slot (it was cut mid-script, leaving the slot
+  // claimed). It still ends with this process: its stdin closes and the shell reads EOF.
+  private spawnShell(): ChildProcessWithoutNullStreams {
+    const h = this.config.host;
+    if (h.kind === 'linux') return spawn('bash', ['--noprofile', '--norc'], { stdio: 'pipe', detached: true });
+    const cfg = join(h.limaHome, h.instance, 'ssh.config');
+    return spawn('ssh', ['-F', cfg, '-T', '-o', 'ServerAliveInterval=10', `lima-${h.instance}`, 'bash --noprofile --norc'], { stdio: 'pipe', detached: true });
+  }
+
+  private async open(): Promise<void> {
+    const child = this.spawnShell();
+    this.child = child;
+    child.stdout.setEncoding('utf8');
+    child.stderr.setEncoding('utf8');
+    child.stdout.on('data', (chunk: string) => { this.buffer += chunk; this.drain(); });
+    child.stderr.on('data', (chunk: string) => { this.buffer += chunk; });
+    child.on('exit', (code) => {
+      if (this.child === child) this.child = undefined;
+      const w = this.waiter; this.waiter = undefined;
+      w?.reject(new Error(`the machine host session ended (exit ${code}): ${this.buffer.slice(-400)}`));
+    });
+    const c = this.config;
+    const vars: Record<string, string> = { WM_STORE: c.store, WM_SLOT: c.slot, WM_FC: c.firecracker, WM_SE: c.snapshotEditor, WM_KEY: c.sshKey, WM_TAP: c.tap, WM_HOSTIP: c.hostIp, WM_GUESTIP: c.guestIp };
+    if (c.backend === 'container') { vars.WM_BINDS = JSON.stringify(c.binds); if (c.export) vars.WM_EXPORT = JSON.stringify(c.export); }
+    // `~/` in a configured path is the machine host's home, expanded there.
+    const assign = Object.entries(vars).map(([k, v]) => `${k}=${v.startsWith('~/') ? `"$HOME"/${q(v.slice(2))}` : q(v)}`).join('\n');
+    await this.rawRun(`${assign}\n${HOST_LIB}\n${c.backend === 'container' ? `${CT_LIB}\n` : ''}wm_init && mkdir -p "$WM_SLOTDIR" && ${c.backend === 'container' ? 'exec 9>>"$WM_SLOTDIR/slot.lock" && WM_LOCKED=1 && ' : ''}cat > "$WM_SLOTDIR/agentc.py" <<'__WM_AGENTC__'\n${AGENT_CLIENT}\n__WM_AGENTC__\n${c.backend === 'container' ? `cat > "$WM_SLOTDIR/compose.py.$$" <<'__WM_COMPOSE__' && mv -f "$WM_SLOTDIR/compose.py.$$" "$WM_SLOTDIR/compose.py"\n${COMPOSER}\n__WM_COMPOSE__\ncat > "$WM_SLOTDIR/publish.py.$$" <<'__WM_PUBLISH__' && mv -f "$WM_SLOTDIR/publish.py.$$" "$WM_SLOTDIR/publish.py"\n${PUBLISHER}\n__WM_PUBLISH__\n` : ''}`);
+    await this.measureOffset();
+  }
+
+  private drain(): void {
+    const w = this.waiter;
+    if (!w) return;
+    const at = this.buffer.indexOf(w.marker);
+    if (at < 0) return;
+    const rest = this.buffer.slice(at + w.marker.length);
+    const nl = rest.indexOf('\n');
+    if (nl < 0) return;
+    const status = Number(rest.slice(0, nl).trim());
+    const out = this.buffer.slice(0, at);
+    this.buffer = rest.slice(nl + 1);
+    this.waiter = undefined;
+    w.resolve({ status, out });
+  }
+
+  /** Set while the store-wide collection runs (gc): it is no operation on the slot, and must not wait on one. */
+  unlocked = false;
+
+  private rawRun(script: string): Promise<{ status: number; out: string }> {
+    const child = this.child;
+    if (!child) return Promise.reject(new Error('no machine host session'));
+    const marker = `__WM_DONE_${randomBytes(6).toString('hex')}__`;
+    return new Promise((resolve, reject) => {
+      this.waiter = { marker, resolve, reject };
+      this.buffer = '';
+      // a function, so a script may `return` its status
+      // With the slot's lock open (the container backend, from init on), one operation at a time across every service on
+      // the slot: a World's branch runs the machine being left and the branch's own machine side by side (a retake's
+      // prepare, then adopt), and each must see the slot as the other left it. The lock is taken for the operation and
+      // released after it, however it ends; a background process that inherited it does not keep it.
+      child.stdin.write(`__wm_op() {\n${script}\n}\nif [ -n "\${WM_LOCKED:-}" ] && [ -z "${this.unlocked ? '1' : ''}" ]; then flock -w 120 9 || { echo '@{"error":"the machine slot stayed busy for 120 s (another World operating it)"}'; false; }; fi && __wm_op 2>&1 < /dev/null; __wm_rc=$?; [ -n "\${WM_LOCKED:-}" ] && flock -u 9; printf '\\n%s %d\\n' ${marker} $__wm_rc\n`);
+    });
+  }
+
+  /** Run a script on the machine host, one at a time; resolves with its status and output. */
+  run(script: string): Promise<{ status: number; out: string }> {
+    const next = this.queue.then(async () => {
+      if (!this.child) await this.open();
+      return this.rawRun(script);
+    });
+    this.queue = next.catch(() => undefined);
+    return next;
+  }
+
+  /** Run host.sh calls, each printing an `@{json}` result line; the results merge in order. An
+   *  `error` field, or a nonzero status, is thrown with the output. */
+  async call<T = Record<string, unknown>>(script: string): Promise<T> {
+    const { status, out } = await this.run(script);
+    const results = out.split('\n').filter((l) => l.startsWith('@{')).map((l) => JSON.parse(l.slice(1)) as Record<string, unknown>);
+    const failed = results.find((r) => typeof r.error === 'string');
+    if (failed) throw new Error(failed.error as string);
+    if (status !== 0 || !results.length) throw new Error(`machine host: \`${script.split('\n')[0]}\` exited ${status}: ${out.trim().slice(-600)}`);
+    return Object.assign({}, ...results) as T;
+  }
+
+  /** The machine host's clock against this host's: the exchange with the shortest round trip of
+   *  five bounds the error by half that round trip. */
+  async measureOffset(): Promise<{ offsetMs: number; rttMs: number }> {
+    let best: { offset: number; rtt: number } | undefined;
+    for (let i = 0; i < 5; i++) {
+      const t0 = hostNowMs();
+      const { out } = await this.rawRun('date +%s%N');
+      const t1 = hostNowMs();
+      const remote = Number(out.trim().split('\n').pop()) / 1e6;
+      const sample = { offset: remote - (t0 + t1) / 2, rtt: t1 - t0 };
+      if (!best || sample.rtt < best.rtt) best = sample;
+    }
+    this.offsetS = best!.offset / 1000;
+    return { offsetMs: Math.round(best!.offset * 100) / 100, rttMs: Math.round(best!.rtt * 100) / 100 };
+  }
+
+  /** measureOffset, serialized with every other operation. */
+  offset(): Promise<{ offsetMs: number; rttMs: number }> {
+    const next = this.queue.then(async () => { if (!this.child) await this.open(); return this.measureOffset(); });
+    this.queue = next.catch(() => undefined);
+    return next;
+  }
+
+  close(): void { this.child?.stdin.end(); this.child?.kill(); this.child = undefined; }
+}