@threadedstack/wmd-web 0.0.0-stage → 0.1.12

package/src/boot.js

@@ -0,0 +1,2037 @@
+// Page-side entry point of wmd-web: download vm.wasm and the boot files, compile,
+// build the shared memory and the Worker pool, run vm.wasm's _start in a Worker.
+//
+//   const vm = await bootWmd({ vmUrl, files: { Image: url, ... }, args: [...] })
+//   const { code, timings } = await vm.exited
+//
+// Requires a cross-origin isolated page (SharedArrayBuffer, shared wasm memory).
+
+import { absMs, markStart } from './host/clock.js'
+import {
+  CTL_EXIT,
+  CTL_EXIT_CODE,
+  CTL_TRAPS,
+  CTL_STALL_DONE,
+  CTL_STALL_MS,
+  CTL_STALL_TAKEN,
+  CTL_STALL_TID,
+  CTL_STALL_WAKE,
+  F64_STALL_AT,
+  F64_STALL_END,
+  CTL_LIVE_THREADS,
+  CTL_NEXT_TID,
+  CTL_POOL_N,
+  CTL_CK_ATTACHES,
+  CTL_CK_GO,
+  CTL_CK_RESTORED,
+  CTL_SPAWN_FAIL,
+  POOL_MAX,
+  SLOT_STATE,
+  ST_DEAD,
+  ST_IDLE,
+  ST_STARTING,
+  createControl,
+  hostCallCounts,
+  slotIndex,
+} from './host/layout.js'
+import { gcNudgeEvery } from './host/gcnudge.js'
+import { createRamMemory, haveMemory64 } from './host/ram-mem.js'
+import { bootFileName, cachedFromTiming, createBootEvents, createWorkerList, readBody, timingCount, vcpusOf } from './host/boot-events.js'
+import { createJitStore, readJitStats, tableMinOf } from './host/jit.js'
+import { createJitCacheHost } from './host/jit-cache.js'
+import { createPanicScanner, createThrottleMeter, createWatchdog, watchdogDefaultMs } from './host/monitor.js'
+import { BOOT_RING, createStdio, stdioReader, stdioText } from './host/stdio.js'
+import {
+  CONSOLE_IN_LIMIT, chanCounters, chanView, consoleInputGate, createChanBlock, markGuestGone, markServiceDead, ringBell, ringRead,
+} from './host/chan.js'
+import { ControlClient } from './host/ctl.js'
+import { PAGE as CKPT_PAGE, requestCheckpoint } from './host/ckpt-point.js'
+import {
+  CheckpointError, assembleCheckpoint, bootKeyOf, checkCheckpointFits, checkPacksFit, checkVmKeyFits, packDigestsOf, fdTableBytes, parseCheckpoint, restoreFdTable, resumePorts, sha256Hex, validateFdTable,
+} from './host/ckpt.js'
+import { captureJit, jitSnapStats, modulesOf, ownersNeedingHub, restoreStore } from './host/jit-snap.js'
+export { CheckpointError, memoryStore, opfsStore } from './host/ckpt.js'
+export { NetSwitch } from './net/switch.js'
+export { ImageFiles, openImage, parseGroup, parsePasswd, resolveUser } from './image-files.js'
+export { P9_CACHE_DEFAULT, p9InitCmdline, p9MountOptions } from './host/p9mount.js'
+
+const PAGE = 65536
+/** A trap with the memory this close to its maximum is reported as out of memory. */
+export const OOM_MARGIN = 64 << 20
+/** vm.wasm's stderr when it grew its memory to the maximum up front (W21, WMD_HEAP_RESERVE). */
+export const HEAP_RESERVE_RE = /vm\.wasm: heap reserve \d+ MiB at /
+/** vm.wasm's stderr when an allocation found the reserve used up (W21). */
+export const HEAP_USED_UP_RE = /vm\.wasm: heap reserve used up \(W21\): out of memory/
+/**
+ * vm.wasm's stderr when it stops on a failed allocation, reserve or not (W21 review A3), and the
+ * JIT encoder's own line (guest/vm/src/wasm_enc.c enc_alloc), which a vm.wasm built before
+ * vm_out_of_memory printed before it aborted (a trap): W29, a trap whose only word was this line.
+ */
+export const VM_OOM_RE = /vm\.wasm: out of memory: |wasm_enc: out of memory allocating \d+ bytes/
+
+/**
+ * Whether vm.wasm's environment asks for W21's heap reserve: WMD_HEAP_RESERVE=1 exactly
+ * (guest/vm/src/heap_reserve.c reads it so). bootWmd adds it unless heapReserve is false.
+ */
+export const heapReserveAsked = env => env.includes('WMD_HEAP_RESERVE=1')
+
+/**
+ * Whether a trap is vm.wasm out of memory, and the evidence: vm.wasm's own "heap reserve
+ * used up" line, or, when it runs without a reserve, the memory within OOM_MARGIN of its
+ * maximum. With a reserve (asked for in vm.wasm's environment, or reported by vm.wasm)
+ * the memory is at the maximum from the start, so the size says nothing.
+ * Returns null, 'heap reserve used up', 'vm.wasm out of memory' (its own line, no reserve)
+ * or 'memory at its maximum'.
+ */
+export function isOutOfMemory({ reserve = false, usedUp = false, said = false, memoryBytes, memoryMaxBytes }) {
+  if (usedUp) return 'heap reserve used up'
+  if (said) return 'vm.wasm out of memory'
+  if (!reserve && memoryBytes > memoryMaxBytes - OOM_MARGIN) return 'memory at its maximum'
+  return null
+}
+const VM_MIN_PAGES = 6144 // vm.wasm's memory import minimum (384 MiB)
+
+const haveJspi = () => typeof WebAssembly.Suspending === 'function' && typeof WebAssembly.promising === 'function'
+
+/**
+ * Whether JIT module sharing is on by default (jit.share 'auto'): wherever JSPI exists
+ * (Playwright's Chromium 153, Firefox 155 and WebKit 26.6 all have it). Firefox needs
+ * it: with a compiled copy per Worker it ran out of wasm code space at ~16,200 copies
+ * per process (P-B2 adversarial F1). In Chromium and WebKit it was as fast or faster
+ * and used no more memory in the measured boots (README "F1").
+ */
+export function jitShareDefault() {
+  return haveJspi()
+}
+
+/** WebKit (Safari, Playwright's WebKit) kills a content process whose memory footprint passes 8 GiB (W34). */
+export const WEBKIT_KILL_MIB = 8192
+/** Footprint the page itself needs besides the machine's memory and the JIT's modules (files, packs, rings), MiB (W34, measured: 0.75 GiB with a 220 MiB pack). */
+const PAGE_BASE_MIB = 768
+/** Footprint WebKit keeps per byte of a live JIT module (W34, measured with the heap reserve on: 2.2 GiB for 560 MiB of modules, about 4x; 2.2x with it off). */
+const MODULE_FOOTPRINT_X = 4
+
+export function isWebKit(nav = globalThis.navigator) {
+  const ua = nav?.userAgent || ''
+  return /AppleWebKit/.test(ua) && !/Chrome|Chromium|Firefox|Android/.test(ua) // desktop Edge says Chrome too; iOS Edge (EdgiOS), Chrome (CriOS) and Firefox (FxiOS) are WebKit
+}
+
+export function isFirefox(nav = globalThis.navigator) {
+  return /Firefox\//.test(nav?.userAgent || '') && !isWebKit(nav)
+}
+
+/**
+ * D-511: Firefox keeps all compiled code of a process, wasm and JavaScript, in one 2044 MiB pool
+ * (SpiderMonkey MaxCodeBytesPerProcess); our modules make about 2.7x their bytes of it, so new ones
+ * stop compiling at 768 MiB live. Every Worker instantiates every module and counts its code, and
+ * past 80% of the pool (~614 MiB of modules) each Worker runs back-to-back full GCs that discard its
+ * JavaScript code and free nothing (TOO_MUCH_JIT_CODE: 166 a second in a Go start-up at 700 MiB,
+ * vCPUs 93-97% in the collector, the channel service starved). A release's modules stay allocated
+ * until every Worker drops them, so live plus one released generation must fit: 2 x 320 < 768.
+ */
+export const FIREFOX_CODE_BUDGET_MIB = 320
+
+/**
+ * D-516 (wmn#67): mobile WebKit, the engine of every browser on iPhone and iPad. iOS kills its tab when the tab's memory
+ * passes a limit far below a Mac's (about 1.5 GiB, up to about 3 GiB on some phones), and mobile WebKit counts every
+ * byte a shared memory or growable SharedArrayBuffer grows by at once, written or not; desktop WebKit counts only the
+ * pages written. An iPad in desktop mode says Macintosh; it is told apart by its touch points.
+ */
+export function isMobileWebKit(nav = globalThis.navigator) {
+  if (!isWebKit(nav)) return false
+  const ua = nav?.userAgent || ''
+  return /\b(iPhone|iPad|iPod)\b/.test(ua) || (/Macintosh/.test(ua) && (nav?.maxTouchPoints || 0) > 1)
+}
+
+/**
+ * D-516: whether bootWmd asks for W21's heap reserve when the caller does not say. Not in mobile WebKit: there the
+ * reserve (the memory grown to its maximum before boot) costs the whole maximum at once, 2.4 GiB with a 1 GiB guest,
+ * and iOS kills the tab while the machine boots. The reserve is for V8's stale memory size (W21); WebKit checks the
+ * live size, so it does not need it.
+ */
+export function heapReserveDefault(nav = globalThis.navigator) {
+  return !isMobileWebKit(nav)
+}
+
+/**
+ * W34: the bytes of live JIT modules a WebKit page can hold, so that the machine's memory at its
+ * maximum + the page's own files + the engine's copies of the modules stay under 5.5 GiB (2.5 GiB
+ * below WebKit's kill limit). Firefox: FIREFOX_CODE_BUDGET_MIB (D-511). 0 (no budget) in Chromium,
+ * whose wasm code space held 1.7 GB of modules in a Go start-up.
+ * At least 128 MiB, so a big memory maximum slows the JIT's reach rather than switching it off.
+ */
+export function jitBudgetDefault(maxBytes, nav = globalThis.navigator) {
+  if (isFirefox(nav)) return FIREFOX_CODE_BUDGET_MIB * MiB
+  if (!isWebKit(nav)) return 0
+  const room = (WEBKIT_KILL_MIB - 2560 - PAGE_BASE_MIB) * MiB - maxBytes
+  return Math.min(WEBKIT_CODE_BUDGET_MIB * MiB, Math.max(128 * MiB, Math.floor(room / MODULE_FOOTPRINT_X)))
+}
+
+/**
+ * W32: JavaScriptCore's executable pool (512 MiB) stops taking new code at about 343 MB of
+ * "JS JIT generated code"; from then on new blocks run at interpreter speed (b8 in WebKit: 6000
+ * rounds took 55-63 s after a build instead of 0.55 s). It holds about 2.1x a module's bytes, so
+ * the budget releases every module before 144 MiB of them are live. A release is only a backstop:
+ * WebKit gives the code back 30-40 s later, so a workload that keeps reaching it builds slowly
+ * (b8 build at 144 MiB without a raised threshold: 80 s instead of 14 s, compute fast).
+ */
+export const WEBKIT_CODE_BUDGET_MIB = 144
+
+/**
+ * W32: runs a block makes in vm.wasm's interpreter before it is compiled, in WebKit (vm.wasm's
+ * default is 50, D-274). Code that runs a few hundred times stays interpreted, so a build's
+ * modules fit the executable pool: b8 in WebKit at 300: build 17.9-18.7 s (14 s at 50), compute
+ * after it 0.53-0.55 s (55-63 s at 50), 117 MiB of modules, 249 MB of code at most; at 200 the
+ * code reached 326 MB, at 500 the build took 24.7 s, at 2000 56 s.
+ * D-505: at 300 a long Claude Code session still filled the pool (about 345 MB) and ran
+ * interpreted after it. With vm.wasm batching blocks above jit_hot again, 1000 is the pick:
+ * b8 build 25.5-26.3 s (21.2-22.1 at 300, 40.6 at 3000), `claude -p` 32.9 s (57.3 at 300),
+ * 2000 terminal lines 4.2 s (31.7 at 300), 161 MB of code.
+ */
+export const WEBKIT_JIT_THRESHOLD = 1000
+
+const MiB = 1 << 20
+
+/**
+ * The default cap on a 9P service's upper (the guest's writes, held in the service
+ * Worker's memory): an eighth of the device's memory as navigator.deviceMemory reports it
+ * (Chromium: 0.25-8 GiB, rounded), from 256 MiB to 1 GiB; 512 MiB where the browser does
+ * not say (Firefox, Safari). Returns {bytes, source}.
+ */
+export function upperCapDefault(nav = globalThis.navigator) {
+  const gib = nav?.deviceMemory
+  if (typeof gib === 'number' && Number.isFinite(gib) && gib > 0) {
+    return { bytes: Math.min(1024 * MiB, Math.max(256 * MiB, Math.floor((gib * 1024 * MiB) / 8))), source: `navigator.deviceMemory ${gib} GiB / 8` }
+  }
+  return { bytes: 512 * MiB, source: 'default (navigator.deviceMemory unknown)' }
+}
+
+const fmtMiB = n => (Number.isFinite(n) ? `${Math.round((n / MiB) * 10) / 10} MiB` : 'no cap')
+
+// Host-side endings (vm.exited code < 0; guest exit codes are >= 0).
+export const EXIT_STOPPED = -1 // reason 'stopped' (vm.stop()) or 'aborted' (the AbortSignal)
+export const EXIT_NO_PROGRESS = -2 // the progress watchdog fired
+export const EXIT_PANIC = -3 // the console showed "Kernel panic - not syncing"
+export const EXIT_SERVICE_DIED = -4 // the channel service Worker ended while the guest ran (P-B3)
+
+/**
+ * The most --ram (MiB) a browser boot accepts unless the caller opts in (W28). The desktop engine
+ * now boots guests up to 3 GiB, but memory 0 is a shared wasm32 memory of at most 4 GiB that also
+ * holds vm.wasm's heap (translator IR, module buffers, ~384 MiB initial): --ram 3072 leaves about
+ * 0.6 GiB of heap, and a tab commits the whole 4 GiB (W21 reserve). 1536 leaves 2 GiB or more.
+ */
+export const MAX_BROWSER_RAM_MIB = 1536
+
+/**
+ * --ram's value in MiB; throws an error naming --ram when it is not a whole number, is 0, or when it is
+ * above MAX_BROWSER_RAM_MIB and allowLargeRam is not true.
+ */
+export function ramMiB(args, allowLargeRam = false) {
+  const i = args.indexOf('--ram')
+  if (i < 0) return args.includes('--machine') ? 256 : 0
+  const v = args[i + 1]
+  if (typeof v !== 'string' || !/^[0-9]+$/.test(v)) {
+    throw new Error(`--ram ${v === undefined ? '(missing)' : JSON.stringify(v)}: expected a whole number of MiB, e.g. --ram 256`)
+  }
+  const mib = Number(v)
+  if (mib < 1) throw new Error(`--ram ${v}: a guest needs at least 1 MiB, e.g. --ram 256`)
+  if (mib > MAX_BROWSER_RAM_MIB && allowLargeRam !== true) {
+    throw new Error(
+      `--ram ${v}: more than ${MAX_BROWSER_RAM_MIB} MiB is not supported in a browser by default: the shared memory is at most 4 GiB ` +
+        `and also holds the emulator's heap, so a bigger guest leaves it too little room. ` +
+        `Use ${MAX_BROWSER_RAM_MIB} or less, or pass allowLargeRam: true (bootWmd option; memoryMaxPages' third argument) to accept the risk.`,
+    )
+  }
+  return mib
+}
+
+/** Memory 0 of a flat guest besides vm.wasm's own minimum: the boot stand-in for the start of RAM (vm/ram.h VM_RAM_LOW_FLAT). */
+export const FLAT_STAGE_MIB = 512
+
+/**
+ * Whether a boot with these args keeps guest RAM in a memory64 of its own (host/ram-mem.js): o.flatRam when it
+ * is a boolean, else when --ram is above MAX_BROWSER_RAM_MIB, allowLargeRam is not set and the engine has memory64.
+ */
+export function wantsFlatRam(args, o = {}) {
+  if (o.flatRam === false) return false
+  let mib = 0
+  try {
+    mib = ramMiB(args, true)
+  } catch {
+    return false // ramMiB reports the bad value
+  }
+  if (!mib) return false
+  if (o.flatRam === true) {
+    if (!haveMemory64()) throw new Error('flatRam: this browser has no shared 64-bit memory (WebAssembly memory64)')
+    return true
+  }
+  return mib > MAX_BROWSER_RAM_MIB && o.allowLargeRam !== true && haveMemory64()
+}
+
+/** The memory 0 maximum, in pages, of a flat guest: vm.wasm's minimum, the boot stand-in and heap slack. */
+export function flatMaxPages(args, slackMiB = 1536) {
+  const stage = Math.min(ramMiB(args, true), FLAT_STAGE_MIB)
+  return Math.min(65536, VM_MIN_PAGES + Math.ceil(((stage + slackMiB) * 1024 * 1024) / PAGE))
+}
+
+/**
+ * vm.wasm's environment: the caller's entries plus WMD_HEAP_RESERVE=1 (W21) unless
+ * heapReserve is false or the caller sets WMD_HEAP_RESERVE itself.
+ */
+export function vmEnv(env = [], heapReserve = true) {
+  const out = [...env]
+  if (heapReserve !== false && !out.some(e => e.startsWith('WMD_HEAP_RESERVE='))) out.push('WMD_HEAP_RESERVE=1')
+  return out
+}
+
+/** The browser's wasm engine: 'webkit' (JavaScriptCore), 'gecko' (SpiderMonkey) or 'blink' (V8, the rest). */
+export function engineOf(nav = globalThis.navigator) {
+  if (isWebKit(nav)) return 'webkit'
+  return /Firefox\//.test(nav?.userAgent || '') ? 'gecko' : 'blink'
+}
+
+/**
+ * W30: the most members a trace (D-303) records in each engine (vm.wasm's WMD_TRACE_MAX; 1024
+ * natively). A trace is one looping wasm function; the browsers' compilers run a big one slower
+ * than the blocks it replaces (Chromium awk 29 s without traces, 37-52 s with traces of up to 1024
+ * members, 19-21 s with up to 32; Firefox 39 s against 67-99 s at 1024).
+ */
+export const BROWSER_TRACE_MAX = { blink: 32, gecko: 32, webkit: 32 }
+
+/**
+ * W33: a browser can stop one vCPU's Worker for seconds. When it stops in the vCPU's idle wait
+ * with an interrupt due (on the 6.1 guest kernel, RCU's grace-period timer), vm.wasm's rescue
+ * thread runs that vCPU after this many ms, so exec on the other vCPUs does not wait for it.
+ */
+export const BROWSER_RESCUE_MS = 20
+
+// D-539: a module with f64x2.relaxed_madd and f32x4.relaxed_madd, each on one lane: d(a, b, c) and s(a, b, c)
+const FMA_PROBE = new Uint8Array([
+  0x00, 0x61, 0x73, 0x6d, 0x01, 0x00, 0x00, 0x00,
+  0x01, 0x0f, 0x02, 0x60, 0x03, 0x7c, 0x7c, 0x7c, 0x01, 0x7c, 0x60, 0x03, 0x7d, 0x7d, 0x7d, 0x01, 0x7d,
+  0x03, 0x03, 0x02, 0x00, 0x01,
+  0x07, 0x09, 0x02, 0x01, 0x64, 0x00, 0x00, 0x01, 0x73, 0x00, 0x01,
+  0x0a, 0x2b, 0x02,
+  0x14, 0x00, 0x20, 0x00, 0xfd, 0x14, 0x20, 0x01, 0xfd, 0x14, 0x20, 0x02, 0xfd, 0x14, 0xfd, 0x87, 0x02, 0xfd, 0x21, 0x00, 0x0b,
+  0x14, 0x00, 0x20, 0x00, 0xfd, 0x13, 0x20, 0x01, 0xfd, 0x13, 0x20, 0x02, 0xfd, 0x13, 0xfd, 0x85, 0x02, 0xfd, 0x1f, 0x00, 0x0b,
+])
+let fmaFused = null
+
+/**
+ * D-539: whether this engine parses relaxed SIMD and its relaxed_madd is fused (one rounding), in f64 and f32:
+ * (1 + 2^-30)(1 - 2^-30) - 1 is -2^-60 fused and 0 unfused (2^-12 and -2^-24 for f32). Where it is, vm.wasm
+ * gets WMD_FMA_FUSED=1 (browserEnv) and its JIT blocks do a guest FMA with relaxed_madd (D-472); Safari
+ * rejects relaxed SIMD, so there it stays the exact plain-f64 FMA (D-535). Asked once per page.
+ */
+export function fmaFuses() {
+  if (fmaFused !== null) return fmaFused
+  fmaFused = false
+  try {
+    if (WebAssembly.validate(FMA_PROBE)) {
+      const { d, s } = new WebAssembly.Instance(new WebAssembly.Module(FMA_PROBE)).exports
+      fmaFused = d(1 + 2 ** -30, 1 - 2 ** -30, -1) === -(2 ** -60) &&
+        s(Math.fround(1 + 2 ** -12), Math.fround(1 - 2 ** -12), -1) === -(2 ** -24)
+    }
+  } catch {
+    fmaFused = false
+  }
+  return fmaFused
+}
+
+/**
+ * W32: the environment vm.wasm starts with in this browser: vmEnv's, plus
+ * WMD_JIT_THRESHOLD=WEBKIT_JIT_THRESHOLD in WebKit, W30's WMD_TRACE_MAX for the engine and
+ * W33's WMD_RESCUE_MS, D-539's WMD_FMA_FUSED=1 where the engine fuses relaxed_madd (fmaFuses) and, in
+ * Chromium, D-542's WMD_RGN_DUP=1 (regions copy sampled-hot compiled blocks of their page; Firefox's go ran
+ * slower with it, WebKit did not move), each unless the caller sets it. Kept out of the boot key (bootKeyOf hashes vmEnv's list), so a checkpoint or base
+ * snapshot made in one engine restores in another; a restored machine keeps the settings it started with, but
+ * its FMA follows the restoring page (machine_fma_env). A checkpoint taken with WMD_FMA_FUSED=1 records
+ * fmaFused, and an engine that does not fuse refuses it (checkCheckpointFits), as its blocks may hold
+ * relaxed_madd.
+ */
+export function browserEnv(env, nav = globalThis.navigator, fused = fmaFuses()) {
+  const has = k => env.some(e => e.startsWith(`${k}=`))
+  const add = []
+  if (isWebKit(nav) && !has('WMD_JIT_THRESHOLD')) add.push(`WMD_JIT_THRESHOLD=${WEBKIT_JIT_THRESHOLD}`)
+  if (!has('WMD_TRACE_MAX')) add.push(`WMD_TRACE_MAX=${BROWSER_TRACE_MAX[engineOf(nav)]}`)
+  if (!has('WMD_RESCUE_MS')) add.push(`WMD_RESCUE_MS=${BROWSER_RESCUE_MS}`)
+  if (!has('WMD_FMA_FUSED') && fused) add.push('WMD_FMA_FUSED=1')   // D-539
+  if (engineOf(nav) === 'blink' && !has('WMD_RGN_DUP')) add.push('WMD_RGN_DUP=1')   // D-542: proven in Chromium only
+  return add.length ? [...env, ...add] : env
+}
+
+/** Pages the shared memory must be able to grow to for a given --ram (MiB). */
+export function memoryMaxPages(args, slackMiB = 1024, allowLargeRam = false) {
+  const ramMiB_ = ramMiB(args, allowLargeRam)
+  // RAM + vCPU arena (a few MiB per vCPU) + heap growth slack.
+  const pages = VM_MIN_PAGES + Math.ceil((ramMiB_ * 1024 * 1024) / PAGE) + Math.ceil((slackMiB * 1024 * 1024) / PAGE)
+  return Math.min(65536, pages)
+}
+
+/**
+ * Time the throttle detector's calibration loop n times now (in its own Worker) and
+ * resolve with the fastest run, in ms. A page can call this while it is in the
+ * foreground and pass the result as bootWmd({throttle: {baselineMs}}), so a boot that
+ * starts in a background window is still recognised as throttled.
+ */
+export function calibrate(n = 3) {
+  return new Promise((resolve, reject) => {
+    const w = new Worker(new URL('./calib-worker.js', import.meta.url), { type: 'module', name: 'wmd-calib' })
+    let best = Infinity
+    let got = 0
+    w.onmessage = e => {
+      best = Math.min(best, e.data.workMs)
+      if (++got === n) {
+        w.terminate()
+        resolve(best)
+      }
+    }
+    w.onerror = err => {
+      w.terminate()
+      reject(new Error(`calibration Worker failed: ${err.message || err}`))
+    }
+    w.postMessage({ t: 'once', n })
+  })
+}
+
+async function fetchShared(url, signal, onBytes, shared = true, onResponse) {
+  const r = await fetch(url, { signal, cache: 'no-store' })
+  if (!r.ok) throw new Error(`GET ${url}: ${r.status} ${r.statusText}`)
+  onResponse?.(r)
+  return readBody(r, { shared, onBytes })
+}
+
+// W71: a pack the page made in shared memory (src/registry/pull.js) is used in place, not copied
+// (packs are read only; a file in o.files may not be, so files are always copied)
+function packShared(bytes) {
+  if (typeof SharedArrayBuffer !== 'undefined' && bytes.buffer instanceof SharedArrayBuffer && bytes.byteOffset === 0 && bytes.byteLength === bytes.buffer.byteLength) return bytes.buffer
+  return toShared(bytes)
+}
+
+function toShared(bytes) {
+  const sab = new SharedArrayBuffer(bytes.byteLength)
+  new Uint8Array(sab).set(bytes)
+  return sab
+}
+
+/**
+ * @param {object} o
+ * @param {string|Uint8Array|ArrayBuffer} o.vmUrl  URL of vm.wasm, or its bytes
+ * @param {Record<string,string|Uint8Array>} o.files  preopen contents: path → URL or bytes
+ * @param {string[]} o.args                     vm.wasm arguments (after argv[0])
+ * @param {string[]} [o.env]                    "K=V" (the runner passes only WMD_*)
+ * @param {boolean} [o.heapReserve]             W21 (default true, false in mobile WebKit: heapReserveDefault, D-516): vm.wasm grows its memory to the maximum
+ *        before any thread starts (WMD_HEAP_RESERVE=1), so memory never grows under running
+ *        vCPUs. Chromium checks memory.fill/copy against a per-Worker size that lags another
+ *        Worker's grow, and trapped (README "W21"). An env entry WMD_HEAP_RESERVE=... wins.
+ * @param {string} [o.preopen]                  guest name of the preopen (default "/g")
+ * @param {number} [o.pool]                     Workers started up front (default 4)
+ * @param {number} [o.spare]                    idle Workers kept in reserve (default 2)
+ * @param {boolean} [o.allowLargeRam]           accept --ram above MAX_BROWSER_RAM_MIB (1536; W28)
+ * @param {number} [o.maxPages]                 shared memory maximum, in 64 KiB pages
+ * @param {URL|string} [o.workerUrl]
+ * @param {(text:string)=>void} [o.onStdout]
+ * @param {(text:string)=>void} [o.onStderr]
+ * @param {(ev:object)=>void} [o.onEvent]        diagnostics: thread start/end, pool growth, ..., and W24's start-up events
+ *        ({t:'boot', stage, state, atMs, tookMs?}, {t:'heap'}, {t:'layer'}, {t:'exit'}: src/host/boot-events.js, README "W24")
+ * @param {{name:string, re:RegExp}[]} [o.marks] stdout regexes whose first match time is recorded
+ * @param {AbortSignal} [o.signal]            abort before the Workers start: bootWmd rejects with an
+ *                                              AbortError; after: vm.exited gives {code:-1, reason:'aborted'}
+ * @param {{compileOnCompile?:'compile'|'validate'|'none', brk?:string, share?:'auto'|boolean, shareWaitMs?:number, maxLiveBytes?:number, codePool?:boolean, cache?:{get:(key:string)=>Promise<Uint8Array|null>, put:(key:string, bytes:Uint8Array)=>Promise<void>}}|false} [o.jit]
+ *        false: no JIT door (the stubbed jit_* imports return -1 and are counted in hostCalls).
+ *        JIT door options. share: compile each JIT module once per process and hand the
+ *        Module to every vCPU Worker through a hub Worker (src/host/jit-hub.js), instead
+ *        of one compiled copy per Worker. Needs JSPI. 'auto' (default): on where
+ *        WebAssembly.Suspending exists (jitShareDefault). With sharing, jit_compile
+ *        always compiles (compileOnCompile applies only without it).
+ *        cache (W77): {get(key) -> Promise<Uint8Array|null>, put(key, bytes) -> Promise}, a byte store the
+ *        page keeps across visits (IndexedDB, say): the JIT's translated modules and an index of the
+ *        guest blocks they hold, so a later boot of the same vm.wasm skips translating them again
+ *        (host/jit-cache.js). Needs sharing. Counters in timings.jit (cacheHits, cacheMisses,
+ *        translated, ...) and timings.jitCache; the index is put before vm.exited resolves (up to 10 s).
+ * @param {number} [o.stdioRingBytes]           stdout/stderr ring per fd (power of two; default
+ *        BOOT_RING, 32 MiB). If the page falls a whole ring behind, the skipped bytes are
+ *        replaced in the delivered text by a "[wmd-web: N bytes of stdout were dropped]" line.
+ * @param {number} [o.watchdogMs]               end the boot (code -2) when the guest writes nothing and
+ *                                              spawns no thread for this long after it starts. 0 = off.
+ *                                              Default: watchdogDefaultMs(args) (60 s arm64, 300 s x86)
+ * @param {{intervalMs?:number, threshold?:number, baselineMs?:number}|false} [o.throttle]
+ *                                              the throttle detector (calib-worker.js); false = off
+ * @param {object} [o.channels]                 P-B3: wmd.chan_* over shared-memory rings, served by a
+ *        service Worker (src/host/chan-service.js). {services: [{port, kind: '9p'|'console'|'control'|'net',
+ *        layers?: (url|Uint8Array)[] (packs, top first), at?, files?: {path: string|Uint8Array},
+ *        maxUpperBytes?, yamux?}], ringBytes? (each direction, default 1 MiB), nslots? (8), spinUs? (5000: the
+ *        service's longest adaptive doorbell spin, W51)}.
+ *        A file is its bytes or text, or {data, mode?, uid?, gid?}; {dir: true, mode?, uid?, gid?} makes a
+ *        directory (W65: an image's WORKDIR). A control service with yamux: true is
+ *        wmd's control session (P-B11): vm.control drives it (src/host/ctl.js).
+ *        Pass the ports to vm.wasm yourself (--p9 PORT, --console PORT, ...). A port with no service
+ *        refuses (-111), as nothing listening does natively. collect?: [{port, path}]: files read
+ *        out of the 9P trees when the machine ends, into timings.chanFiles {"port:path": text|null}.
+ *        maxUpperBytes?: the cap on each 9P service's upper (bytes of file contents the guest's
+ *        writes hold in the service Worker) for services that do not set their own; default
+ *        upperCapDefault() (navigator.deviceMemory); Infinity for none. Reported in
+ *        timings.chanUppers; when a write hits it the guest gets ENOSPC and onStderr says so.
+ *        consoleInputBytes?: console input (vm.consoleWrite) queued for the guest at most
+ *        (default CONSOLE_IN_LIMIT, 4 MiB).
+ *        The guest should mount the 9P root with p9MountOptions() (cache=mmap): under
+ *        cache=loose a full upper cannot fail write(2) (src/host/p9mount.js).
+ *        P-B10: a net service with relay: {url, token?, tokenUrl?} ({port, kind: 'net', relay,
+ *        config?, maxConns?}) is the guest's network: a network Worker (src/net/net-worker.js) runs
+ *        a TCP/IP stack for the guest's virtio-net frames and carries its TCP connections and DNS
+ *        through the relay (web/relay). Pass --net PORT (and --mac) to vm.wasm. vm.net has its
+ *        stats; timings.net has them at the end.
+ *        W56: {port, kind: 'net', switch, name, ip?, relay?}: the guest is on an in-page network
+ *        (new NetSwitch(), src/net/switch.js) with the other guests of the page on the same switch:
+ *        they reach each other by address and by name (name, name.wmd.internal), with or without a
+ *        relay; the guest's address is `ip`, else the one its name had on the switch, else the next
+ *        free one (switch.address(name) tells it before the boot, for the bundle's /etc/hosts).
+ *        A restored guest must come back with the same address (same name, or the same ip). Without `ip` the
+ *        address follows the order names first reach the switch: to restore after a page reload, give `ip`.
+ * @param {(text:string)=>void} [o.onConsole]   text the guest wrote to the console channel (hvc0)
+ * @param {boolean} [o.checkpoint]               P-B9: the guest gets its checkpoint thread (wmd.ctl_attach) and point import
+ *        (wmd.point), the boot gets a key (the vm.wasm, kernel, command line, packs it ran), and the handle gets
+ *        checkpoint(): memory 0, the 9P service's files and fids, the JIT slot list and the fd table, taken while the
+ *        guest is stopped at its checkpoint point. Needs channels with a 9P service, and the same options to restore.
+ * @param {boolean} [o.checkpointHeapTop]       P-B9: bound the scan at vm.wasm's vm_heap_top() (default on, W58: false reads all of memory 0)
+ * @param {number} [o.checkpointScanLimit]      P-B9: bytes of memory 0 a checkpoint reads (default all). Above it pages are taken as zero:
+ *        only safe with the guest's real heap top (WebKit commits every page a scan reads, W34)
+ * @param {object} [o.restore]                  P-B9: a checkpoint ({header, sections}, from vm.checkpoint() or a store's load())
+ *        to continue from instead of booting: the same options as the boot that took it (a different vm.wasm, kernel,
+ *        command line, packs or bundle is refused with a CheckpointError, code 'stale'). The guest comes back as it was;
+ *        its console and control ports are reset (the init opens the control port again), network flows are gone.
+ * @param {boolean} [o.stallHook]               P-B8 test hook: vm.stallThread(tid, ms) stops one guest
+ *                                              thread's Worker at its next host call (default off; when
+ *                                              off the Workers do not look at the stall cells)
+ */
+export async function bootWmd(o) {
+  if (!globalThis.crossOriginIsolated) {
+    throw new Error('page is not cross-origin isolated (needs COOP same-origin + COEP require-corp)')
+  }
+  const t0 = absMs()
+  const timings = { t0 }
+  const ev = e => o.onEvent?.(e)
+  // W24: the start-up events (host/boot-events.js); be.close() at the end
+  const be = createBootEvents({ emit: ev, t0, now: absMs })
+  // the emulator's last stderr text, for the error a wait on a dead machine gives
+  let errTail = ''
+  const emitErr = text => {
+    errTail = (errTail + text).slice(-4096)
+    o.onStderr?.(text)
+  }
+  const preopen = o.preopen || '/g'
+  const argv = ['vm.wasm', ...o.args]
+  const env = vmEnv(o.env, o.heapReserve ?? heapReserveDefault())
+  // the default Worker is started from a literal new URL(..., import.meta.url) so bundlers (Vite, webpack)
+  // see it and bundle worker.js with its imports; a variable URL is copied as a plain asset (2.15)
+  const workerUrl = o.workerUrl
+  // The flat layout (host/ram-mem.js): a guest with more RAM than memory 0 can hold gets its RAM in a memory64 of its
+  // own. Chosen when --ram is above MAX_BROWSER_RAM_MIB and the engine has memory64 (o.flatRam forces it on or off);
+  // without it such a --ram is the error it was.
+  const flatRam = wantsFlatRam(o.args, o)
+  if (!flatRam) ramMiB(o.args, o.allowLargeRam) // a bad or too big --ram is a clear error before anything is downloaded
+  const maximum = o.maxPages || (flatRam ? flatMaxPages(o.args) : memoryMaxPages(o.args, 1024, o.allowLargeRam))
+  if (flatRam) {
+    if (o.restore || o.restoreLazy) throw new Error(`--ram ${ramMiB(o.args, true)}: a guest with more than ${MAX_BROWSER_RAM_MIB} MiB cannot start from a checkpoint yet`)
+    env.push('WMD_RAM_FLAT=1')
+  }
+  const ramMem = flatRam ? createRamMemory(ramMiB(o.args, true)) : null
+  // P-B9: checkpoints. restoreIn: the checkpoint's parts (parseCheckpoint refuses a malformed one).
+  // A flat guest takes none yet: a checkpoint holds memory 0 only.
+  const ckptOn = !flatRam && (!!o.checkpoint || !!o.restore || !!o.restoreLazy)
+  let restoreIn = o.restore ? parseCheckpoint(o.restore) : null
+  // P-B6: a base snapshot that is still downloading ({header: Promise, ckpt: Promise, abort()}, src/base.js openBase()). The
+  // boot downloads its own files meanwhile; the snapshot's header is checked against this boot's vm.wasm and boot key as soon
+  // as each is known. With o.restoreFallback a snapshot that is refused (other vm.wasm or boot key, cut, damaged, absent)
+  // does not fail the boot: it goes on cold, and timings.baseFallback says why.
+  let lazyIn = o.restoreLazy || null
+  let baseLazy = lazyIn // kept until the restore has succeeded (accept) or failed (reject)
+  // The handle must not keep the checkpoint it came from alive (about 500 MB): vm.restore() builds the next machine from
+  // `o`, so `o` carries no restore and no assets. (A caller that holds the checkpoint object holds it for its own reasons.)
+  const adoptIn = o._adopt || null // W57: the replaced machine's JIT hub, kept running by vm.restore() on the same handle
+  // W59: the network's identity across vm.restore(): the machine's instance id (one per bootWmd handle chain; the relay
+  // replaces this instance's old session) and its placeholder map (names the guest looked up -> 198.18.0.0/15 addresses).
+  // The checkpoint's own map comes first; the handle's names it does not conflict with are kept too (never recycled).
+  const netIn = o._net || null
+  const netInstance = netIn?.instance || Array.from(crypto.getRandomValues(new Uint8Array(16)), b => b.toString(16).padStart(2, '0')).join('')
+  const netNames = new Map()
+  const netIps = new Set()
+  for (const [n, ip] of [...(restoreIn?.names || []), ...(netIn?.names || [])]) {
+    if (netNames.has(n) || netIps.has(ip)) continue
+    netNames.set(n, ip)
+    netIps.add(ip)
+  }
+  let netStatus = null
+  const netStatusCbs = new Set()
+  const netNameWaiters = new Map()
+  o = { ...o, restore: undefined, restoreLazy: undefined, assets: o.assets && undefined, _assets: o.assets, _adopt: undefined, _net: undefined }
+  let heldAssets = null // what vm.restore() hands the next boot: bytes, Module, boot files, packs, keys
+  let restoring = false
+  let ck = null // the checkpoint being taken (declared early: finish() looks at it)
+  const ckptT = {}
+  let vmKey = null
+  let bootKey = null
+  let bootDesc = null
+  let packDigests = null
+  // W24: where the restored snapshot came from ('opfs' | 'network' for a base snapshot, 'memory' for vm.restore()), and its size
+  let baseSource = null
+  let baseTotal = null
+  let baseBytes = null
+
+  // Abort: listen from the start. Before the Workers exist an abort rejects every await
+  // below at once (raceAbort); afterwards it ends the machine (finish).
+  const signal = o.signal
+  let onAbortAfterStart = null
+  let rejectAbort
+  const abortP = new Promise((_, rej) => (rejectAbort = rej))
+  abortP.catch(() => {})
+  const abortError = () => new DOMException('boot aborted', 'AbortError')
+  const onAbort = () => (onAbortAfterStart ? onAbortAfterStart() : rejectAbort(abortError()))
+  if (signal?.aborted) throw abortError()
+  signal?.addEventListener('abort', onAbort)
+  const raceAbort = p => {
+    p.catch(() => {}) // once aborted nobody awaits p; its own failure must not go unhandled
+    return Promise.race([p, abortP])
+  }
+
+  // 1. Downloads (in parallel). vm.wasm is compiled from its bytes so the compile
+  //    time is measured on its own.
+  const names = Object.keys(o.files)
+  // P-B9: o.assets is what an earlier boot of this handle already had (vm.restore passes it): vm.wasm's bytes and compiled
+  // Module, the boot files and the packs, and the boot's keys. Nothing is downloaded, hashed or compiled again, and the
+  // old machine is not stopped until the new one's inputs are in hand.
+  const A = o._assets || null
+  o._assets = undefined // the handle keeps no reference of its own to the previous boot's assets
+  // W24: one download per file, with its bytes as they come. A file the caller passed as bytes, or one a restore reuses
+  // (o.assets), is reported once, done and cached.
+  const download = (file, url, shared, extra = {}) => {
+    const kind = `download:${file}`
+    const base = { t: 'boot', stage: 'download', file, ...extra }
+    let finalUrl = url
+    const before = timingCount(url)
+    const ts = absMs()
+    return fetchShared(url, o.signal, (bytes, total) => be.progress(kind, { ...base, state: 'progress', bytes, total, cached: null }), shared, r => (finalUrl = r.url || url)).then(async buf => {
+      const tookMs = Math.round(absMs() - ts)
+      // the browser adds a response's Resource Timing entry a little after its body is read (Chromium: a small file was
+      // read before its entry existed): wait for it, at most 200 ms
+      for (let i = 0; i < 20 && timingCount(url) <= before && !o.signal?.aborted; i++) await new Promise(r => setTimeout(r, 10))
+      const n = buf.byteLength
+      be.now(kind, { ...base, state: 'done', bytes: n, total: n, cached: cachedFromTiming(url, { bytes: n, finalUrl, before }), tookMs })
+      return buf
+    })
+  }
+  // reused: vm.restore() hands this boot the last one's bytes (nothing fetched: cached); bytes the caller passed came from
+  // wherever the caller got them, which wmd-web cannot see (cached null, given true)
+  const given = (file, buf, extra = {}) => {
+    be.now(`download:${file}`, { t: 'boot', stage: 'download', file, ...extra, state: 'done', bytes: buf.byteLength, total: buf.byteLength, cached: A ? true : null, ...(A ? {} : { given: true }), tookMs: 0 })
+    return buf
+  }
+  let lastDownloadAt = t0
+  const downloaded = x => ((lastDownloadAt = Math.max(lastDownloadAt, absMs())), x)
+  const vmP = A
+    ? Promise.resolve(given('vm.wasm', A.vmBytes))
+    : o.vmUrl instanceof Uint8Array || o.vmUrl instanceof ArrayBuffer
+      ? Promise.resolve(given('vm.wasm', o.vmUrl instanceof ArrayBuffer ? o.vmUrl : o.vmUrl.slice().buffer)) // 2.7: bytes the page already checked
+      : download('vm.wasm', o.vmUrl, false).then(b => {
+        timings.vmDownloadMs = absMs() - t0
+        return downloaded(b)
+      })
+  const fileName = n => bootFileName(n, o.args, preopen)
+  const filesP = A
+    ? Promise.resolve(A.files.map(f => given(fileName(f.path), f.buffer)))
+    : Promise.all(names.map(n => (typeof o.files[n] === 'string' ? download(fileName(n), o.files[n], true) : Promise.resolve(given(fileName(n), toShared(o.files[n])))))).then(bufs => {
+        timings.filesDownloadMs = absMs() - t0
+        return downloaded(bufs)
+      })
+  filesP.catch(() => {}) // awaited below; must not go unhandled if vm.wasm fails first
+  // P-B3: the channel services' packs (fetched in parallel with the rest); pack:<n> numbers them over all services
+  const chanSvcs = o.channels?.services || []
+  let packN = 0
+  const packIds = chanSvcs.map(svc => (svc.layers || []).map(() => packN++))
+  const layersP = A
+    ? Promise.resolve(A.chanLayers.map((ls, i) => ls.map((b, j) => given(`pack:${packIds[i][j]}`, b, { port: chanSvcs[i].port }))))
+    : Promise.all(
+        chanSvcs.map((svc, i) =>
+          Promise.all((svc.layers || []).map((l, j) => (typeof l === 'string' ? download(`pack:${packIds[i][j]}`, l, true, { port: svc.port }) : Promise.resolve(given(`pack:${packIds[i][j]}`, packShared(l), { port: svc.port }))))),
+        ),
+      ).then(downloaded)
+  layersP.catch(() => {})
+  let module, files, chanLayers, tableMin, vmBytes
+  function baseRefused(err) {
+    const lazy = lazyIn || baseLazy
+    lazyIn = null
+    baseLazy = null
+    try {
+      lazy?.abort?.(err)
+    } catch {}
+    if (!o.restoreFallback) throw err
+    timings.baseFallback = { code: err && err.code ? err.code : 'error', message: err && err.message ? err.message : String(err) }
+    // W24: the restore stage ends here, unused; the kernel stage follows
+    be.now('restore', { t: 'boot', stage: 'restore', state: 'done', used: false, fallback: timings.baseFallback.code, bytes: baseBytes, total: baseTotal, source: baseSource })
+    emitErr(`\n[wmd-web] base snapshot not used (${timings.baseFallback.code}): ${timings.baseFallback.message}\n[wmd-web] booting the kernel instead\n`)
+  }
+  try {
+    vmBytes = await raceAbort(vmP)
+    // the vm key first (1.4 MB of hashing): a snapshot of another vm.wasm is refused from its header before anything else is spent on it
+    if (ckptOn) vmKey = A ? A.keys.vmKey : await raceAbort(sha256Hex(new Uint8Array(vmBytes)))
+    if (lazyIn) {
+      try {
+        const h = await raceAbort(lazyIn.header)
+        checkVmKeyFits(h, vmKey)
+        lazyIn.proceed?.() // the reader decodes only from here: a refused header costs what was queued, not the file
+      } catch (err) {
+        if (signal?.aborted) throw err
+        baseRefused(err)
+      }
+    }
+    const tc = absMs()
+    be.now('compile', { t: 'boot', stage: 'compile', state: 'start', moduleBytes: vmBytes.byteLength, reused: !!A })
+    module = A ? A.module : await raceAbort(WebAssembly.compile(vmBytes))
+    timings.compileMs = absMs() - tc
+    be.now('compile', { t: 'boot', stage: 'compile', state: 'done', moduleBytes: vmBytes.byteLength, reused: !!A, tookMs: Math.round(timings.compileMs) })
+    tableMin = tableMinOf(vmBytes) ?? undefined
+    timings.tableMin = tableMin
+    const bufs = await raceAbort(filesP)
+    timings.downloadMs = Math.max(timings.vmDownloadMs || 0, timings.filesDownloadMs || 0)
+    timings.fileBytes = bufs.reduce((n, b) => n + b.byteLength, 0) + vmBytes.byteLength
+    files = names.map((n, i) => ({ path: n, buffer: bufs[i] }))
+    chanLayers = await raceAbort(layersP)
+    timings.layerBytes = chanLayers.flat().reduce((n, b) => n + b.byteLength, 0)
+    timings.allDownloadMs = lastDownloadAt - t0 // vm.wasm, the boot files and the packs all in
+    be.now('download', { t: 'boot', stage: 'download', state: 'done', fileBytes: timings.fileBytes, layerBytes: timings.layerBytes, tookMs: Math.round(timings.allDownloadMs) })
+    if (ckptOn) {
+      // the boot's identity: a checkpoint restores only into the same one (research/10 R11)
+      const tk = absMs()
+      let packs
+      if (A) {
+        bootKey = A.keys.bootKey
+        bootDesc = A.keys.bootDesc
+        packs = A.keys.packs
+      } else {
+        // the boot key samples each pack (head and tail); packs is the full digest of every layer (a SHA-256 tree over 8 MiB pieces), recorded in
+        // every checkpoint this boot takes and checked against a base snapshot's before it is used
+        const [k, pk] = await raceAbort(Promise.all([bootKeyOf({ vmKey, argv, env, preopen, files, services: chanSvcs.map((s, i) => ({ ...s, layers: chanLayers[i] })), maxPages: maximum }), packDigestsOf(chanLayers)]))
+        bootKey = k.key
+        bootDesc = k.desc
+        packs = pk
+      }
+      ckptT.keyMs = absMs() - tk
+      heldAssets = { vmBytes, module, tableMin, files, chanLayers, keys: { vmKey, bootKey, bootDesc, packs } }
+      packDigests = packs
+      if (lazyIn) {
+        const tw = absMs()
+        const info = lazyIn.info
+        const restoreProgress = () => {
+          if (!info) return
+          const att = info.attempts?.[info.attempts.length - 1]
+          if (!att) return
+          baseSource = att.source
+          baseTotal = att.size ?? info.entry?.bytes ?? null
+          be.progress('restore', { t: 'boot', stage: 'restore', state: 'progress', bytes: info.netBytes, total: baseTotal, source: baseSource })
+        }
+        restoreProgress()
+        const restoreTimer = setInterval(restoreProgress, 250)
+        try {
+          const box = await raceAbort(lazyIn.ckpt).finally(() => {
+            clearInterval(restoreTimer)
+            restoreProgress()
+            baseBytes = info?.netBytes ?? null
+          })
+          const got = typeof box.take === 'function' ? box.take() : box // a box hands the snapshot over once: the opener keeps no reference to its 0.5 GB
+          ckptT.baseWaitMs = absMs() - tw // the time the boot waited for the snapshot after everything else was in
+          const parsed = parseCheckpoint(got)
+          checkCheckpointFits(parsed.header, { vmKey, bootKey, bootDesc, maxPages: maximum, hasJit: o.jit !== false, fmaFused: fmaFuses() })
+          checkPacksFit(parsed.header.packs, packDigests)
+          restoreIn = parsed
+          lazyIn = null // baseLazy stays: accept() when the restore has succeeded, reject() if it fails
+        } catch (err) {
+          if (signal?.aborted) throw err
+          baseRefused(err)
+        }
+      }
+      if (restoreIn) checkCheckpointFits(restoreIn.header, { vmKey, bootKey, bootDesc, maxPages: maximum, hasJit: o.jit !== false, fmaFused: fmaFuses() })
+    }
+    if (signal?.aborted) throw abortError()
+  } catch (err) {
+    signal?.removeEventListener('abort', onAbort)
+    be.close()
+    // whatever ended the boot (the caller's signal, a failed download, a compile error): the snapshot download, the decoded
+    // snapshot and the pending cache copy are dropped here, not left for the garbage collector
+    const lazy = lazyIn || baseLazy
+    lazyIn = null
+    baseLazy = null
+    try {
+      lazy?.abort?.(err)
+    } catch {}
+    throw signal?.aborted ? abortError() : err
+  }
+
+  // 2. Shared memory and control block.
+  const tMem = absMs()
+  let memory = new WebAssembly.Memory({ initial: VM_MIN_PAGES, maximum, shared: true })
+  const memoryInitialBytes = memory.buffer.byteLength
+  const ctlSab = createControl()
+  const ctl = new Int32Array(ctlSab)
+  if (restoreIn) {
+    // The fd table now; the memory pages when the main thread has made its instance (restoreMemory, from the
+    // 'resume-instantiated' message): vm.wasm's start function must see an untouched memory (worker.js).
+    restoreFdTable(ctl, restoreIn.ctl, files.length)
+    ckptT.pagesRestored = restoreIn.index.length
+  }
+  function restoreMemory() {
+    try {
+      restoreMemoryNow()
+      // the snapshot restored: its cache copy may be committed now (not before: a snapshot that fails to restore must not stay cached)
+      const lazy = baseLazy
+      baseLazy = null
+      lazy?.accept?.()
+    } catch (err) {
+      const lazy = baseLazy
+      baseLazy = null
+      try {
+        lazy?.reject?.(err) // the cache entry this snapshot came from is removed: the next load downloads again
+      } catch {}
+      // the main thread waits for this (worker.js): tell it, instead of leaving it to its 120 s timeout
+      Atomics.store(ctl, CTL_CK_RESTORED, 2)
+      Atomics.notify(ctl, CTL_CK_RESTORED)
+      o.onStderr?.(`\n[wmd-web] restoring the checkpoint's memory failed: ${err && err.message ? err.message : err}\n`)
+      finish(4, `restore failed: ${err && err.message ? err.message : err}`)
+    }
+  }
+  function restoreMemoryNow() {
+    const tm = absMs()
+    const have = memory.buffer.byteLength / CKPT_PAGE
+    if (restoreIn.header.memPages > have) memory.grow(restoreIn.header.memPages - have)
+    const u8 = new Uint8Array(memory.buffer)
+    const kept = new Uint8Array(restoreIn.header.memPages)
+    let k = 0
+    for (const c of restoreIn.memChunks) {
+      for (let off = 0; off < c.length; off += CKPT_PAGE) {
+        const p = restoreIn.index[k++]
+        u8.set(c.subarray(off, off + CKPT_PAGE), p * CKPT_PAGE)
+        kept[p] = 1
+      }
+    }
+    // pages the instance's start function wrote that were zero at the checkpoint (the runner's zero_absent): the static region
+    let zeroed = 0
+    const w = new Int32Array(memory.buffer, 0, Math.min(restoreIn.header.memPages, VM_MIN_PAGES) * (CKPT_PAGE / 4))
+    for (let p = 0; p * (CKPT_PAGE / 4) < w.length; p++) {
+      if (kept[p]) continue
+      const lo = p * (CKPT_PAGE / 4)
+      let nz = false
+      for (let i = lo; i < lo + CKPT_PAGE / 4; i += 8) {
+        if ((w[i] | w[i + 1] | w[i + 2] | w[i + 3] | w[i + 4] | w[i + 5] | w[i + 6] | w[i + 7]) !== 0) {
+          nz = true
+          break
+        }
+      }
+      if (nz) {
+        w.fill(0, lo, lo + CKPT_PAGE / 4)
+        zeroed++
+      }
+    }
+    ckptT.instantiatedMs = tm - t0 // boot start to the main thread's instance made (key, download, replay, Worker start included)
+    ckptT.memoryMs = absMs() - tm
+    ckptT.zeroedAfterInstantiate = zeroed
+    ckptT.pagesWrittenAt = absMs() - t0
+    Atomics.store(ctl, CTL_CK_RESTORED, 1)
+    Atomics.notify(ctl, CTL_CK_RESTORED)
+    // everything of the checkpoint has been copied into this machine (memory, fd table, the 9P state and the JIT store went
+    // earlier): do not pin it for the machine's life
+    if (baseSource === null) {
+      baseSource = 'memory' // vm.restore() or bootWmd({restore}): the checkpoint was in the page's memory
+      baseBytes = baseTotal = restoreIn.memChunks.reduce((n, c) => n + c.length, 0)
+    }
+    be.now('restore', { t: 'boot', stage: 'restore', state: 'done', used: true, bytes: baseBytes, total: baseTotal, source: baseSource, tookMs: Math.round(ckptT.pagesWrittenAt) })
+    restoreIn.memChunks = null
+    restoreIn.index = null
+    restoreIn.jit = null
+    restoreIn.svc = null
+    restoreIn.ctl = null
+  }
+  // o.jit === false: no JIT door; vm.wasm gets the stubbed jit_* imports (-1, counted
+  // in the host-call counters), as before P-B2. Otherwise the door (src/host/jit.js).
+  // The log is reclaimed while sharing. A Worker that cannot receive a Module from the hub ('messageerror':
+  // Firefox past its per-process wasm code limit), or that starts after the log reused the bytes of early
+  // Modules, compiles its copy from bytes the hub keeps (W31b), so every browser reclaims. o.jitReclaim overrides.
+  const jitStore = o.jit === false ? null : restoreIn?.jit ? restoreStore(restoreIn.jit, { reclaim: o.jitReclaim ?? true }) : createJitStore({ reclaim: o.jitReclaim ?? true })
+  const stdio = createStdio(o.stdioRingBytes ?? BOOT_RING)
+  let memTook = absMs() - tMem // the memory, the control block, the JIT store and the stdio rings (the channel block is added below)
+  const out = stdioReader(stdio)
+  const outText = stdioText(out)
+  timings.stdioRingBytes = out.ringBytes
+  // W77: the cache is the page's object (functions): it stays here, the Workers get ports
+  const { cache: jitCacheStore, ...jitRest } = o.jit || {}
+  const jitOpts = { compileOnCompile: 'validate', ...jitRest }
+  // W34: WebKit keeps every live module until a flush and kills the page at 8 GiB. Past the budget the
+  // door answers JIT_OVER_BUDGET and the guest releases every module (one flush) and compiles again.
+  if (jitOpts.maxLiveBytes === undefined) jitOpts.maxLiveBytes = jitBudgetDefault(maximum * 65536)
+  timings.jitMaxLiveBytes = jitOpts.maxLiveBytes
+  const share = !jitStore ? false : jitOpts.share === undefined || jitOpts.share === 'auto' ? jitShareDefault() : !!jitOpts.share
+  if (share && !haveJspi()) {
+    signal?.removeEventListener('abort', onAbort)
+    be.close()
+    throw new Error('jit.share needs JSPI (WebAssembly.Suspending / promising)')
+  }
+  timings.jitShare = share
+  // W77: the JIT's module cache (host/jit-cache.js): the index is read before any Worker starts
+  let jitCache = null
+  let knownSab = null
+  if (jitStore && jitCacheStore) {
+    if (!share) {
+      timings.jitCache = { on: false, why: 'the JIT cache needs module sharing (JSPI)' }
+    } else {
+      const tag = vmKey ?? (await raceAbort(sha256Hex(new Uint8Array(vmBytes))))
+      jitCache = createJitCacheHost({ cache: jitCacheStore, tag, log: s => emitErr(`\n[${s}]\n`) })
+      knownSab = await raceAbort(jitCache.load())
+      timings.jitCache = { on: true, ...jitCache.stats }
+    }
+  }
+
+  // P-B3: the channel block and its service Worker.
+  let chanSab = null
+  let chanSvc = null
+  let chanDied = null
+  // P-B10: the network Worker, when a net service has a relay
+  let netWorker = null
+  let netStats = null
+  let netMember = null // W56: this guest on an in-page switch (switch.js attach())
+  const netWaiters = new Map()
+  let chanLock = null
+  let chanStats = null
+  let chanBytesSeen = 0
+  let controlUp = false
+  let collectDone = null
+  const upperWaiters = new Map() // W62: export-upper id -> {res, rej}
+  // P-B11: wmd's control session (a control service with yamux: true), driven from the page
+  const ctlService = chanSvcs.find(s => (s.kind === 'control' || s.kind === 3) && s.yamux)
+  const control = ctlService
+    ? new ControlClient({
+        post: m => {
+          if (!chanSvc || done || chanDied) {
+            if (m.op === 'open') queueMicrotask(() => control.onEvents([{ ev: 'closed', k: m.k, why: 'the machine has ended' }]))
+            return
+          }
+          if (m.bytes) {
+            const b = m.bytes instanceof Uint8Array ? m.bytes.slice() : new Uint8Array(m.bytes)
+            chanSvc.postMessage({ ...m, bytes: b }, [b.buffer])
+          } else chanSvc.postMessage(m)
+        },
+      })
+    : null
+  // W24: the Workers stage. Every Worker started before the vCPU (the channel service, the network Worker, the JIT hub,
+  // the first pool Workers and the main one) ready = the stage is done; later changes are progress events.
+  const wl = createWorkerList(be.at)
+  const vcpus = vcpusOf(o.args)
+  let workersDone = false
+  let workersStarted = false // set once the main Worker has been started: before that the list is not whole
+  let tWorkers = null
+  const workersEv = () => {
+    const e = { t: 'boot', stage: 'workers', workers: wl.list(), vcpus, jitShared: share }
+    if (!workersDone && workersStarted && wl.allReady()) {
+      workersDone = true
+      be.now('workers', { ...e, state: 'done', tookMs: Math.round(absMs() - tWorkers) })
+    } else be.progress('workers', { ...e, state: 'progress' })
+  }
+  const workerState = (id, role, state) => {
+    if (tWorkers === null) tWorkers = absMs()
+    wl.set(id, role, state)
+    workersEv()
+  }
+  const consoleDec = new TextDecoder()
+  const consoleBuf = new Uint8Array(1 << 20)
+  timings.consoleBytes = 0
+  let consoleGate = null
+  let consoleFull = false
+  if (o.channels) {
+    // the cap on each 9P upper (F2: none before, so a guest could grow the Worker without bound)
+    const capDefault = o.channels.maxUpperBytes !== undefined ? { bytes: o.channels.maxUpperBytes, source: 'channels.maxUpperBytes' } : upperCapDefault()
+    timings.chanUppers = chanSvcs
+      .filter(s => s.kind === '9p' || s.kind === 2)
+      .map(s => (s.maxUpperBytes !== undefined ? { port: s.port, maxUpperBytes: s.maxUpperBytes, source: 'service maxUpperBytes' } : { port: s.port, maxUpperBytes: capDefault.bytes, source: capDefault.source }))
+    try {
+      const tc = absMs()
+      chanSab = createChanBlock({
+        ports: chanSvcs.map(s => ({ port: s.port, kind: s.kind })),
+        nslots: o.channels.nslots ?? 8,
+        ringBytes: o.channels.ringBytes ?? 1 << 20,
+      })
+      memTook += absMs() - tc
+      // W56: on an in-page switch the guest gets its address there (the DHCP lease) and a port for its peers;
+      // taken here, before any Worker exists, so a refused name (taken, invalid) leaves nothing behind
+      const sw = chanSvcs.find(s => (s.kind === 'net' || s.kind === 1) && s.switch)
+      if (sw) netMember = sw.switch.attach({ name: sw.name, ip: sw.ip })
+    } catch (err) {
+      signal?.removeEventListener('abort', onAbort)
+      be.close()
+      throw err // (no Worker exists yet)
+    }
+    const lockName = `wmd-chan-${Math.random().toString(36).slice(2)}-${Date.now()}`
+    chanSvc = new Worker(new URL('./host/chan-service.js', import.meta.url), { type: 'module', name: 'wmd-chan' })
+    workerState('chan-service', 'chan-service', 'starting')
+    chanSvc.onmessage = e => {
+      const m = e.data
+      if (m.t === 'stats') {
+        chanStats = m.stats
+        layerEvents(m.stats)
+      }
+      else if (m.t === 'upper-full') {
+        emitErr(
+          `\n[wmd-web] the guest's files on 9P port ${m.port} are full: the upper holds ${fmtMiB(m.used)} of its ${fmtMiB(m.max)} cap ` +
+            `(channels.maxUpperBytes); the guest's writes get ENOSPC (No space left on device)\n`,
+        )
+        ev({ t: 'chan', ev: 'upper-full', port: m.port, used: m.used, max: m.max })
+      }
+      else if (m.t === 'snap') ckptSvc(m)
+      else if (m.t === 'collected') collectDone?.(m.files)
+      else if (m.t === 'upper') {
+        const w = upperWaiters.get(m.id)
+        upperWaiters.delete(m.id)
+        if (w && m.error) w.rej(new Error(`exportUpper: ${m.error}`))
+        else if (w) w.res({ bytes: new Uint8Array(m.bytes.buffer || m.bytes), entries: m.entries, files: m.files, whiteouts: m.whiteouts, opaque: m.opaque, dataBytes: m.dataBytes, ms: m.ms })
+      }
+      else if (m.t === 'ctl') {
+        if (m.evs.some(e => e.ev === 'data')) watchdog.progress()
+        if (!controlUp && vcpuAt !== null && m.evs.some(e => e.ev === 'session' && e.up)) {
+          controlUp = true // W24: the first time the guest's control session came up
+          be.now('control', { t: 'boot', stage: 'control', state: 'done', tookMs: Math.round(absMs() - vcpuAt) })
+        }
+        control?.onEvents(m.evs)
+      }
+      else if (m.t === 'error') serviceDied(`the channel service failed: ${m.message.split('\n')[0]}`)
+      else if (m.t === 'locked' && navigator.locks?.request) {
+        // Granted only when the service Worker has ended, however it ended.
+        chanLock = new AbortController()
+        navigator.locks
+          .request(lockName, { signal: chanLock.signal }, () => serviceDied('the channel service Worker ended'))
+          .catch(() => {})
+      } else if (m.t === 'ready') {
+        ev({ t: 'chan', ev: 'ready' })
+        workerState('chan-service', 'chan-service', 'ready')
+      }
+    }
+    chanSvc.onerror = err => {
+      if (!done) workerState('chan-service', 'chan-service', 'failed')
+      serviceDied(`the channel service Worker failed: ${err.message || err}`)
+    }
+    const netSvc = chanSvcs.find(s => (s.kind === 'net' || s.kind === 1) && (s.relay || s.switch))
+    let netPort = null
+    if (netSvc) {
+      const mc = new MessageChannel()
+      netPort = mc.port1
+      netWorker = new Worker(new URL('./net/net-worker.js', import.meta.url), { type: 'module', name: 'wmd-net' })
+      workerState('net', 'net', 'starting')
+      netWorker.onmessage = e => {
+        const m = e.data
+        if (m.t === 'ready') workerState('net', 'net', 'ready')
+        else if (m.t === 'stats') {
+          netStats = m.stats
+          const w = netWaiters.get(m.id)
+          if (w) {
+            netWaiters.delete(m.id)
+            w(m.stats)
+          }
+        } else if (m.t === 'log') emitErr(`[wmd-web] ${m.line}\n`)
+        else if (m.t === 'name') {
+          if (!netNames.has(m.name) && !netIps.has(m.ip)) {
+            netNames.set(m.name, m.ip)
+            netIps.add(m.ip)
+          }
+        } else if (m.t === 'status') {
+          netStatus = m.status
+          for (const cb of netStatusCbs) {
+            try {
+              cb(m.status)
+            } catch {}
+          }
+        } else if (m.t === 'names') {
+          const w = netNameWaiters.get(m.id)
+          if (w) {
+            netNameWaiters.delete(m.id)
+            w(m.names)
+          }
+        }
+      }
+      netWorker.onerror = err => {
+        if (!done) workerState('net', 'net', 'failed')
+        emitErr(`\n[wmd-web] the network Worker failed: ${err.message || err}\n`)
+      }
+      const r = netSvc.relay
+      const relay = r ? { url: r.url, protocol: r.protocol, token: r.token, key: r.key, tokenUrl: r.tokenUrl && new URL(r.tokenUrl, location.href).href } : null
+      const config = netMember ? { ...netSvc.config, ip: netMember.ip } : netSvc.config
+      const transfer = netMember ? [mc.port2, netMember.port] : [mc.port2]
+      netWorker.postMessage({ t: 'init', port: mc.port2, relay, instance: netInstance, names: [...netNames], switchPort: netMember?.port, config, maxConns: netSvc.maxConns }, transfer)
+    }
+    chanSvc.postMessage({
+      t: 'init',
+      sab: chanSab,
+      lockName,
+      spinUs: o.channels.spinUs,
+      consoleInputBytes: o.channels.consoleInputBytes ?? CONSOLE_IN_LIMIT,
+      services: chanSvcs.map((s, i) => ({
+        port: s.port,
+        kind: s.kind,
+        at: s.at,
+        files: s.files,
+        yamux: !!s.yamux,
+        maxUpperBytes: timings.chanUppers.find(u => u.port === s.port)?.maxUpperBytes,
+        layers: chanLayers[i],
+        restore: restoreIn?.svc[s.port], // P-B9: the 9P tree and fids of the checkpoint (copied: the checkpoint stays usable)
+      })),
+      netPort,
+    }, netPort ? [netPort] : [])
+    consoleGate = consoleInputGate(chanSab, o.channels.consoleInputBytes ?? CONSOLE_IN_LIMIT)
+  }
+  be.now('memory', { t: 'boot', stage: 'memory', state: 'done', initialBytes: memoryInitialBytes, maxBytes: maximum * PAGE, ringBytes: stdio.byteLength + (chanSab ? chanSab.byteLength : 0), tookMs: Math.round(memTook) })
+  // W24: each 9P service's writable layer (its upper), from the service's stats (every 250 ms while they change); an
+  // event when it is first seen and on each change of 1 MiB or more
+  const layerSeen = new Map()
+  function layerEvents(st) {
+    for (const [port, u] of Object.entries(st?.uppers || {})) {
+      const last = layerSeen.get(port)
+      if (last !== undefined && Math.abs(u.used - last) < 1 << 20) continue
+      layerSeen.set(port, u.used)
+      be.progress(`layer:${port}`, { t: 'layer', port: Number(port), usedBytes: u.used, capBytes: u.max, kind: 'memory' })
+    }
+  }
+  function serviceDied(why) {
+    if (done || chanDied) return
+    chanDied = why
+    markServiceDead(chanSab)
+    emitErr(`\n[wmd-web] ${why}: every channel is closed\n`)
+    control?.fail(`${why}: every channel is closed${errTail.trim() ? `; the emulator's last output:\n${errTail.trim().split('\n').slice(-12).join('\n')}` : ''}`)
+    ev({ t: 'chan', ev: 'service-died', why })
+    failUpperWaiters(why)
+  }
+  function failUpperWaiters(why) {
+    for (const w of upperWaiters.values()) w.rej(new Error(`exportUpper: ${why}`))
+    upperWaiters.clear()
+  }
+  const chanV = chanSab && chanView(chanSab)
+  function drainConsole() {
+    if (!chanV) return
+    const v = chanV
+    let text = ''
+    for (;;) {
+      const n = ringRead(v, v.pipe, consoleBuf)
+      if (!n) break
+      timings.consoleBytes += n
+      text += consoleDec.decode(consoleBuf.subarray(0, n), { stream: true })
+    }
+    if (text) {
+      ringBell(v) // the service may be waiting for room in the pipe
+      watchdog.progress()
+      o.onConsole?.(text)
+    }
+    // channel traffic is progress too (a guest busy on 9P may print nothing for a while)
+    const c = v.f64
+    let bytes = 0
+    for (let s = 0; s < v.nslots; s++) bytes += c[s * 4] + c[s * 4 + 1]
+    if (bytes !== chanBytesSeen) {
+      chanBytesSeen = bytes
+      watchdog.progress()
+    }
+  }
+  let hub = share ? new Worker(new URL('./host/jit-hub.js', import.meta.url), { type: 'module', name: 'wmd-jit-hub' }) : null
+  if (hub && jitStore) hub.postMessage({ t: 'store', recs: jitStore.recs, ctl: jitStore.ctl }) // the hub marks records delivered (W31)
+  // P-B9: a checkpoint needs the bytes of modules the log released; the hub keeps them (up to this much)
+  if (hub && ckptOn) hub.postMessage({ t: 'config', bytesMax: o.ckptHubBytes ?? 1 << 30 })
+  let hubUp = false
+  let replayDone = null // P-B9/W57: the hub's answer to a restore's replay
+  // W57: vm.restore() keeps this machine's hub past its end, for the next machine's hub to take its Modules from
+  let keepHub = false
+  let keptHub = null
+  if (hub) {
+    // W24: the hub's first answer (to a stats request) says its script runs
+    workerState('jit-hub', 'jit-hub', 'starting')
+    hub.onmessage = e => {
+      if (e.data.t === 'bytes-of') ckptOn && ckptHub(e.data)
+      else if (e.data.t === 'replayed') replayDone?.(e.data)
+      else if (e.data.t === 'stats' && !hubUp && !done) {
+        hubUp = true
+        workerState('jit-hub', 'jit-hub', 'ready')
+      }
+    }
+    hub.onerror = () => !done && workerState('jit-hub', 'jit-hub', 'failed')
+    hub.postMessage({ t: 'stats' })
+  }
+  /** A port to the hub for one Worker (null when not sharing). */
+  const hubPort = () => {
+    if (!hub) return null
+    const ch = new MessageChannel()
+    hub.postMessage({ t: 'port', port: ch.port1 }, [ch.port1])
+    return ch.port2
+  }
+
+  // 3. Workers.
+  const workers = []
+  const stdoutLines = { buf: '' }
+  const marks = (o.marks || []).map(m => ({ ...m, hit: false }))
+  let done = false
+  const jitCachePorts = [] // W77: the page's ends of the Workers' cache ports
+  let resolveExit
+  const exited = new Promise(r => (resolveExit = r))
+  let vcpuAt = null // W24: when vm.wasm's _start began (the main Worker's instance made)
+  let kernelDone = false
+  let lastHeap = -1
+  function heapEvent() {
+    const bytes = memory ? memory.buffer.byteLength : 0
+    if (bytes === lastHeap) return
+    lastHeap = bytes
+    be.progress('heap', { t: 'heap', bytes, maxBytes: maximum * PAGE })
+  }
+  const spare = o.spare ?? 2
+
+  // vm.wasm's own lines about its heap (W21's reserve, branch w21-trap): with the reserve
+  // the memory is at its maximum from the start, so only vm.wasm can say it ran out.
+  const heap = { reserve: false, usedUp: false, said: false, carry: '' }
+  const watchHeap = text => {
+    const t = heap.carry + text
+    if (HEAP_RESERVE_RE.test(t)) heap.reserve = true
+    if (HEAP_USED_UP_RE.test(t)) heap.usedUp = true
+    if (VM_OOM_RE.test(t)) heap.said = true
+    heap.carry = t.slice(-160)
+  }
+
+  function pump() {
+    const got = outText.drain() // text, with a marker line wherever bytes were skipped
+    if (got[1] || got[2]) watchdog.progress()
+    if (timings.firstByteMs === undefined && out.firstStdoutAt()) timings.firstByteMs = out.firstStdoutAt() - t0
+    if (!kernelDone && vcpuAt !== null && out.firstStdoutAt()) {
+      kernelDone = true // W24: the kernel stage ends at the first console byte (a restored machine has no kernel stage)
+      if (!restoreIn) be.now('kernel', { t: 'boot', stage: 'kernel', state: 'done', tookMs: Math.round(Math.max(0, out.firstStdoutAt() - vcpuAt)) })
+    }
+    if (got[1]) onStdoutText(got[1])
+    if (got[2]) {
+      watchHeap(got[2])
+      emitErr(got[2])
+    }
+    drainConsole()
+  }
+  const pumpTimer = setInterval(pump, 16)
+
+  let lateTrap = null
+  function finish(code, reason) {
+    if (done) return
+    done = true
+    if (baseLazy) {
+      // the machine ended before its restore succeeded (stopped, failed to start): the snapshot's cache copy is not committed
+      const lazy = baseLazy
+      baseLazy = null
+      try {
+        lazy.abort?.(new Error(`the machine ended (${reason}) before the base snapshot was restored`))
+      } catch {}
+    }
+    if (ck) ckptFail(new CheckpointError('ended', `the machine ended (${reason}) before the checkpoint was complete`)) // also stops its poll timer
+    timings.totalMs = absMs() - t0
+    timings.spawnFailures = Atomics.load(ctl, CTL_SPAWN_FAIL)
+    timings.threadsSpawned = Atomics.load(ctl, CTL_NEXT_TID) - 1
+    timings.jit = jitStore ? readJitStats(jitStore) : null
+    timings.memoryBytes = memory.buffer.byteLength
+    timings.memoryMaxBytes = maximum * PAGE
+    const trapped = String(reason).startsWith('trap')
+    if (trapped) {
+      // stop every guest thread now: after a trap the guest's memory may hold garbage
+      // (the others also stop at their next host call, worker.js guard)
+      for (const w of workers) w.terminate()
+    }
+    if (trapped || reason === 'exit') pump() // vm.wasm's last stderr lines (the heap reserve's "used up")
+    // W21 review A3: vm.wasm now stops itself on a failed allocation (exit 4 after its "out
+    // of memory" line) instead of trapping; that end is reported the same way.
+    // Only exit status 4, the one vm_out_of_memory uses: a user-mode guest can print the same
+    // lines on its own stderr (the joint W21/W23 review's oomspoof: exit 1 was taken for OOM).
+    if (trapped || (reason === 'exit' && code === 4 && (heap.usedUp || heap.said))) {
+      // A trap because vm.wasm ran out of room for its own heap: its malloc failed and it
+      // aborted (P-B11 problem 1, review finding 4). With W21's heap reserve vm.wasm says
+      // so on stderr, and the memory is at its maximum whatever happens, so the size
+      // only counts without a reserve.
+      const oom = isOutOfMemory({ ...heap, reserve: heap.reserve || heapReserveAsked(env), memoryBytes: timings.memoryBytes, memoryMaxBytes: timings.memoryMaxBytes })
+      if (oom) {
+        if (!trapped) for (const w of workers) w.terminate()
+        timings.oom = oom
+        timings.trap = reason
+        reason =
+          `out of memory: the emulator used ${fmtMiB(timings.memoryBytes)} of its ${fmtMiB(timings.memoryMaxBytes)} memory maximum and stopped ` +
+          `(${reason}); give it more room above the guest's RAM (bootWmd maxPages, memoryMaxPages(args, slackMiB))`
+        emitErr(`\n[wmd-web] ${reason}\n`)
+      }
+    }
+    let collected = Promise.resolve()
+    if (chanSab) {
+      markGuestGone(chanSab)
+      chanLock?.abort() // before the service ends, so its end is not taken for a death
+      chanSvc?.postMessage({ t: 'stats' })
+      netWorker?.postMessage({ t: 'stats', id: 'final' })
+      // files the caller wants out of the 9P trees (bundle/exitcode, a runc log, ...)
+      const want = o.channels.collect || []
+      if (want.length && chanSvc && !chanDied) {
+        collected = new Promise(res => {
+          collectDone = files => {
+            timings.chanFiles = files
+            res()
+          }
+          setTimeout(res, 2000)
+        })
+        chanSvc.postMessage({ t: 'collect', files: want })
+      }
+    }
+    // Give threads a moment to finish their last writes, drain, then stop every Worker.
+    const settle = new Promise(r => setTimeout(r, 50))
+    Promise.all([settle, collected]).then(async () => {
+      for (const w of workers) w.terminate()
+      // W77: the notes the Workers sent are in; put the index (bounded wait) before the end is reported
+      if (jitCache) {
+        await jitCache.save()
+        for (const p of jitCachePorts) p.close()
+        timings.jitCache = { on: true, ...jitCache.stats }
+      }
+      if (keepHub && hub) keptHub = hub
+      else hub?.terminate()
+      chanSvc?.terminate()
+      failUpperWaiters('the machine has ended (its files ended with it)')
+      netWorker?.terminate()
+      netMember?.detach() // W56: its peers' streams to it fail; the name keeps its address
+      if (netWorker) timings.net = netStats
+      if (chanSab) timings.chan = { ...chanCounters(chanSab), service: chanStats, died: chanDied }
+      if (control) {
+        control.fail(`the machine ended (${reason}, exit code ${code}) before the control channel was ready${errTail.trim() ? `; the emulator's last output:\n${errTail.trim().split('\n').slice(-12).join('\n')}` : ''}`)
+        // every stream still open ends (a process gets exit 125), as when the engine's
+        // control connection breaks
+        const evs = [...control.streams.keys()].map(k => ({ ev: 'closed', k, why: `the machine ended (${reason})` }))
+        evs.push({ ev: 'session', up: false, epoch: control.session.epoch, why: 'the machine ended' })
+        control.onEvents(evs)
+      }
+      clearInterval(pumpTimer)
+      pump()
+      timings.outputDropped = { stdout: out.dropped[1], stderr: out.dropped[2] }
+      timings.outputDropMarkers = { stdout: outText.skips[1], stderr: outText.skips[2] }
+      timings.hostCalls = hostCallCounts(ctl)
+      timings.throttle = throttle ? throttle.state() : null
+      // A kernel panic the guest turns into a clean exit (PSCI reset -> 0) is a failure.
+      if (panic.line && (reason === 'exit' || reason === 'kernel panic')) {
+        timings.guestExitCode = reason === 'exit' ? code : null
+        code = EXIT_PANIC
+        reason = `kernel panic: ${panic.line.replace(/^\[[^\]]*\]\s*/, '')}`
+      } else if (chanDied && reason === 'exit') {
+        // The guest powers off when its 9P or net channel closes (chan_pump.c host_gone),
+        // with exit 0: a host failure must not look like a clean run.
+        timings.guestExitCode = code
+        code = EXIT_SERVICE_DIED
+        reason = `channel service died: ${chanDied}`
+      }
+      // W21 review A2: a trap counted up to here (the 50 ms settle) turns an exit 0 into 4. A
+      // trap later than that is not seen; the joint W21/W23 review found none in 15 proof boots,
+      // and user mode now drains its threads before vm.wasm exits (main_wasm.c).
+      timings.traps = Atomics.load(ctl, CTL_TRAPS)
+      if (timings.traps && reason === 'exit' && code === 0) {
+        timings.guestExitCode = code
+        code = 4
+        reason = lateTrap || `trap: a thread trapped after the exit (${timings.traps})`
+      }
+      // W24: every Worker has ended; the end, by number
+      wl.endAll()
+      be.now('workers', { t: 'boot', stage: 'workers', state: 'progress', workers: wl.list(), vcpus, jitShared: share })
+      be.now('exit', { t: 'exit', code, reason, oom: !!timings.oom })
+      be.close()
+      release()
+      resolveExit({ code, reason, timings })
+    })
+  }
+
+  // Drop everything that holds the shared memory, the file buffers or a Worker, so a
+  // finished boot can be collected even while the page keeps its handle (vm.memory
+  // stays readable for post-mortem until vm.dispose()).
+  function release() {
+    clearInterval(tickTimer)
+    stopGcNudge()
+    clearTimeout(panicTimer)
+    signal?.removeEventListener('abort', onAbort)
+    for (const w of workers) w.onmessage = w.onerror = null
+    workers.length = 0
+    calib?.terminate()
+    if (calib) calib.onmessage = null
+    calib = null
+    hub = null // terminated in finish()
+    if (chanSvc) chanSvc.onmessage = chanSvc.onerror = null
+    chanSvc = null
+    if (netWorker) netWorker.onmessage = netWorker.onerror = null
+    netWorker = null
+    netMember?.detach()
+    module = files = null
+  }
+
+  function onStdoutText(text) {
+    o.onStdout?.(text)
+    if (panic.push(text)) onPanic()
+    if (!marks.length) return
+    stdoutLines.buf += text
+    let nl
+    while ((nl = stdoutLines.buf.indexOf('\n')) >= 0) {
+      const line = stdoutLines.buf.slice(0, nl).replace(/\r$/, '') // the x86 8250 console sends CRLF
+      stdoutLines.buf = stdoutLines.buf.slice(nl + 1)
+      for (const m of marks) {
+        if (!m.hit && m.re.test(line)) {
+          m.hit = true
+          timings[m.name] = absMs() - t0
+        }
+      }
+    }
+  }
+
+  function onMessage(e) {
+    const m = e.data
+    switch (m.t) {
+      case 'ready':
+        loaded.add(m.role === 'main' ? 'main' : m.slot)
+        if (!done) workerState(wid(m.role === 'main' ? 'main' : m.slot), m.role === 'main' ? 'vcpu' : 'pool', 'ready')
+        if (m.role === 'main') {
+          timings.instantiatedMs = m.at - t0
+          watchdog.start()
+          ev({ t: 'phase', phase: 'running' })
+          vcpuAt = m.at
+          if (!restoreIn) be.now('kernel', { t: 'boot', stage: 'kernel', state: 'start' })
+          heapEvent()
+        }
+        break
+      case 'need':
+        topUp(m.why)
+        break
+      case 'thread':
+        watchdog.progress()
+        ev(m)
+        if (!done && wl.tid(wid(m.slot), m.ev === 'start' ? m.tid : null)) workersEv()
+        break
+      case 'exit':
+        finish(m.code, 'exit')
+        break
+      case 'resume-instantiated':
+        restoreMemory()
+        break
+      case 'ckpt-point':
+      case 'ckpt-mem':
+      case 'ckpt-failed':
+      case 'ckpt-mem-error':
+        ckptEvent(m)
+        break
+      case 'trap':
+        emitErr(`\n[wmd-web] thread ${m.tid} trapped: ${m.message}\n${m.stack}\n`)
+        // W21 review A2: a thread that traps after another called proc_exit (the trap lost
+        // the race for CTL_EXIT) still fails the run; finish() turns an exit 0 into 4
+        if (done) lateTrap ??= `trap: ${m.message} (thread ${m.tid}, after the exit)`
+        finish(4, `trap: ${m.message}`)
+        break
+    }
+  }
+
+  // P-B7: a Worker whose script failed to load (an error before its 'ready') is made again,
+  // up to LOAD_TRIES times, after a delay that differs per Worker. WebKit, offline behind the
+  // pack host's service worker, failed the module imports of all but one of several Workers
+  // started at once from one script (README P-B7, problem 1); started 30 ms apart they load.
+  const LOAD_TRIES = 3
+  const loaded = new Set() // 'main' and pool slots that posted 'ready'
+  const retryDelay = (key, attempt) => 40 * attempt * (1 + (key === 'main' ? 0 : key + 1))
+  const wid = key => (key === 'main' ? 'vcpu-0' : `pool-${key}`)
+  function startWorker(key, name, role, slot, attempt, onFail) {
+    const w = workerUrl
+      ? new Worker(workerUrl, { type: 'module', name })
+      : new Worker(new URL('./worker.js', import.meta.url), { type: 'module', name })
+    workerState(wid(key), key === 'main' ? 'vcpu' : 'pool', 'starting')
+    w.onmessage = onMessage
+    w.onerror = err => {
+      if (!done && !loaded.has(key) && attempt < LOAD_TRIES) {
+        err.preventDefault?.()
+        w.terminate()
+        const i = workers.indexOf(w)
+        if (i >= 0) workers.splice(i, 1)
+        ev({ t: 'pool', ev: 'worker-retry', key, attempt })
+        timings.workerLoadRetries = (timings.workerLoadRetries || 0) + 1
+        setTimeout(() => !done && startWorker(key, name, role, slot, attempt + 1, onFail), retryDelay(key, attempt))
+        return
+      }
+      if (!done) workerState(wid(key), key === 'main' ? 'vcpu' : 'pool', 'failed')
+      onFail(err)
+    }
+    postInit(w, role, slot)
+    workers.push(w)
+    return w
+  }
+
+  function addPoolWorker() {
+    const slot = Atomics.load(ctl, CTL_POOL_N)
+    if (slot >= POOL_MAX) return false
+    Atomics.store(ctl, slotIndex(slot, SLOT_STATE), ST_STARTING)
+    Atomics.store(ctl, CTL_POOL_N, slot + 1)
+    startWorker(slot, `wmd-pool-${slot}`, 'pool', slot, 1, err => {
+      Atomics.store(ctl, slotIndex(slot, SLOT_STATE), ST_DEAD)
+      emitErr(`\n[wmd-web] pool worker ${slot} failed to load: ${err.message || err}\n`)
+      ev({ t: 'pool', ev: 'worker-error', slot })
+    })
+    return true
+  }
+
+  function topUp(why) {
+    if (done) return
+    const n = Atomics.load(ctl, CTL_POOL_N)
+    let idleOrStarting = 0
+    for (let i = 0; i < n; i++) {
+      const s = Atomics.load(ctl, slotIndex(i, SLOT_STATE))
+      if (s === ST_IDLE || s === ST_STARTING) idleOrStarting++
+    }
+    let added = 0
+    while (idleOrStarting + added < spare + (why === 'spawned' ? 0 : 1)) {
+      if (!addPoolWorker()) {
+        emitErr(`\n[wmd-web] thread pool exhausted: ${POOL_MAX} Workers in use (${why})\n`)
+        ev({ t: 'pool', ev: 'exhausted' })
+        return
+      }
+      added++
+    }
+    if (why === 'exhausted') {
+      emitErr(`\n[wmd-web] thread-spawn found no idle Worker in time; pthread_create failed (EAGAIN)\n`)
+      ev({ t: 'pool', ev: 'spawn-failed' })
+    }
+    if (added) ev({ t: 'pool', ev: 'grow', added, total: Atomics.load(ctl, CTL_POOL_N), why })
+  }
+
+  function postInit(w, role, slot) {
+    const msg = initMsg(role, slot)
+    msg.jitPort = hubPort()
+    const transfer = msg.jitPort ? [msg.jitPort] : []
+    if (jitCache) {
+      msg.jitCache = { sab: knownSab, port: jitCachePort() }
+      transfer.push(msg.jitCache.port)
+    }
+    w.postMessage(msg, transfer)
+  }
+
+  /** W77: a Worker's port to the JIT cache: module reads ({t:'get'}) and notes ({t:'note'}). */
+  function jitCachePort() {
+    const ch = new MessageChannel()
+    const p = ch.port1
+    p.onmessage = e => {
+      const m = e.data
+      if (m.t === 'get') {
+        jitCache.get(m.hl, m.hh, m.len).then(bytes => {
+          try {
+            p.postMessage({ id: m.id, bytes }, bytes ? [bytes.buffer] : [])
+          } catch {}
+        })
+      } else if (m.t === 'note') jitCache.note(m)
+    }
+    jitCachePorts.push(p)
+    return ch.port2
+  }
+
+  function initMsg(role, slot) {
+    return {
+      t: 'init',
+      role,
+      slot,
+      module,
+      tableMin,
+      memory,
+      ram: ramMem,
+      ctlSab,
+      files,
+      preopen,
+      args: argv,
+      env: browserEnv(env),
+      jit: jitStore,
+      jitOpts,
+      stdio,
+      chan: chanSab,
+      stallHook: !!o.stallHook,
+      ckpt: ckptOn,
+      ckptScanLimit: o.checkpointScanLimit,
+      ckptVerifyBound: !!o.checkpointVerifyBound,
+      ckptUseHeapTop: o.checkpointHeapTop !== false, // W58: reading untouched pages commits them in WebKit
+      resume: role === 'main' && restoreIn ? { ports: resumePorts(o.args), stats: o.args.includes('--stats') } : null,
+    }
+  }
+
+  // Monitors: kernel panic, progress watchdog, throttling, stub host-call counters.
+  const panic = createPanicScanner()
+  let panicTimer = 0
+  function onPanic() {
+    ev({ t: 'panic', line: panic.line })
+    emitErr(`\n[wmd-web] kernel panic on the console: ${panic.line}\n`)
+    // CONFIG_PANIC_TIMEOUT=-1 reboots at once (exit 0); a kernel that hangs instead is
+    // stopped after a few seconds, once the panic trace has been printed.
+    panicTimer = setTimeout(() => finish(EXIT_PANIC, 'kernel panic'), 5000)
+  }
+  const TICK_MS = 250
+  const watchdogMs = o.watchdogMs ?? watchdogDefaultMs(o.args)
+  const watchdog = createWatchdog({ limitMs: watchdogMs, tickMs: TICK_MS })
+  const throttleOpts = o.throttle === false ? null : o.throttle || {}
+  const throttle = throttleOpts && createThrottleMeter({ threshold: throttleOpts.threshold ?? 2, baselineMs: throttleOpts.baselineMs })
+  let calib = null
+  if (throttle) {
+    calib = new Worker(new URL('./calib-worker.js', import.meta.url), { type: 'module', name: 'wmd-calib' })
+    calib.onmessage = e => {
+      if (done || e.data.t !== 'calib') return
+      const s = throttle.sample(e.data.workMs)
+      if (s.changed) {
+        const { changed, ...st } = s
+        ev({ t: 'throttle', ...st, waitLateMs: e.data.waitLateMs })
+        if (st.throttled)
+          emitErr(`\n[wmd-web] the guest is running about ${st.ratio}x slower than this browser can run it (throttled: background window or tab?)\n`)
+      }
+    }
+    calib.postMessage({ t: 'start', intervalMs: throttleOpts.intervalMs ?? 2000 })
+  }
+  let lastCalls = ''
+  function onTick() {
+    if (done) return
+    if (vcpuAt !== null) heapEvent()
+    const calls = hostCallCounts(ctl)
+    const key = JSON.stringify(calls)
+    if (key !== lastCalls) {
+      lastCalls = key
+      ev({ t: 'host-calls', counts: calls }) // at most once per tick, however often the guest calls
+    }
+    if (watchdog.check(throttle && throttle.state().throttled ? throttle.state().ratio : 1)) {
+      const s = Math.round(watchdog.idleMs() / 1000)
+      emitErr(`\n[wmd-web] guest made no progress: no console output and no new thread for ${s} s after the vCPU started; stopping\n`)
+      finish(EXIT_NO_PROGRESS, `no progress: the guest wrote nothing for ${s} s`)
+    }
+  }
+  const tickTimer = setInterval(onTick, TICK_MS)
+  // D-419: the page holds the guest's memory too, so WebKit would collect its garbage late
+  const stopGcNudge = gcNudgeEvery()
+
+  if (restoreIn?.jit && hub) {
+    // the slot list's modules, compiled again by the hub before any vCPU starts. Not here: a Module the page compiles
+    // keeps its code until the page collects its garbage, and Firefox's per-process code limit then fills with the
+    // code of machines already gone (W57); the hub's code goes with its Worker when the machine ends.
+    const tr = absMs()
+    const mods = modulesOf(restoreIn.jit).map(m => ({ owner: m.owner, bytes: m.bytes.slice() }))
+    if (adoptIn) {
+      // the old machine's hub (still running) posts its Modules and their bytes to this one, Worker to Worker; the
+      // replay takes each whose bytes are the same instead of compiling them again
+      const ch = new MessageChannel()
+      adoptIn.postMessage({ t: 'handoff', port: ch.port1 }, [ch.port1])
+      hub.postMessage({ t: 'adopt', port: ch.port2 }, [ch.port2])
+    }
+    const r = await Promise.race([
+      new Promise(res => {
+        replayDone = res
+        hub.postMessage({ t: 'replay', id: 1, gen: restoreIn.jit.gen, mods }, mods.map(m => m.bytes.buffer))
+      }),
+      exited.then(() => ({ ended: true })), // the hub ends with the machine: the handle is returned, already ended
+    ])
+    replayDone = null
+    if (r.error && !done) throw new Error(`restore: the JIT hub could not compile the checkpoint's modules: ${r.error}`)
+    ckptT.replayModules = r.n ?? 0
+    ckptT.replayReused = r.reused ?? 0
+    ckptT.replayMs = absMs() - tr
+  }
+  if (restoreIn) timings.restore = ckptT
+
+  const poolSize = o.pool ?? 4
+  for (let i = 0; i < poolSize; i++) addPoolWorker()
+
+  markStart(ctlSab)
+  timings.startMs = absMs() - t0
+  startWorker('main', 'wmd-main', 'main', -1, 1, err => {
+    emitErr(`\n[wmd-web] main worker failed: ${err.message || err}\n`)
+    finish(4, 'main worker error')
+  })
+  workersStarted = true
+
+  onAbortAfterStart = () => finish(EXIT_STOPPED, 'aborted')
+  if (signal?.aborted) onAbortAfterStart()
+
+
+  // ---- P-B9: checkpoints -------------------------------------------------------------------
+  //
+  // vm.checkpoint(): the page stores REQ_CKPT in the guest's host_req word (the address the guest's ctl thread
+  // gave wmd.ctl_attach). The guest stops its vCPUs at a block boundary, drains the file share, stops its
+  // service threads and calls wmd.point on vCPU 0 (host/ckpt-point.js), which tells the page and copies memory
+  // 0's non-zero pages. At that same moment the page asks the channel service Worker for the 9P state and
+  // the JIT hub for the modules' bytes the log released, and reads the JIT slot list and the fd table (nothing
+  // else runs). When all four are in, the page lets vCPU 0 go (CTL_CK_GO) and the guest continues.
+  const gnow = () => performance.timeOrigin + performance.now()
+  const hdrNs = (hdr, off) => Number(new DataView(hdr.buffer, hdr.byteOffset, hdr.byteLength).getBigUint64(off, true)) / 1e6
+
+  function ckptFail(err) {
+    const c = ck
+    if (!c) return
+    ck = null
+    clearTimeout(c.timer)
+    clearInterval(c.poll)
+    if (c.atPoint && !c.went) {
+      Atomics.store(ctl, CTL_CK_GO, 2) // the guest's vCPU 0 is waiting for us: tell it the checkpoint failed
+      Atomics.notify(ctl, CTL_CK_GO)
+    }
+    c.reject(err)
+  }
+
+  function ckptEvent(m) {
+    const c = ck
+    if (!c) return // a point nobody asked for (or one that timed out): nothing to do
+    if (m.t === 'ckpt-failed') return ckptFail(new CheckpointError('point', `the guest could not take the checkpoint: ${m.why} (the machine goes on)`))
+    if (m.t === 'ckpt-mem-error') return ckptFail(new CheckpointError('memory', `copying the guest's memory failed: ${m.message}`))
+    if (m.t === 'ckpt-point') {
+      c.atPoint = true
+      c.hdr = m.hdr
+      c.pointAt = m.at
+      if (chanSvc) chanSvc.postMessage({ t: 'snap' })
+      else c.svc = {}
+      try {
+        c.ctlBytes = fdTableBytes(ctl)
+        if (!jitStore) c.jitDone = true
+        else {
+          const need = ownersNeedingHub(jitStore)
+          if (!need.length) {
+            const t = absMs()
+            c.jitSnap = captureJit(jitStore, new Map())
+            c.jitMs = absMs() - t
+            c.jitDone = true
+          } else if (!hub) {
+            throw new CheckpointError('jit', `${need.length} module records were released from the module log and there is no hub to ask`)
+          } else {
+            c.jitAskedAt = absMs()
+            hub.postMessage({ t: 'bytes-of', id: 1, owners: need })
+          }
+        }
+      } catch (err) {
+        return ckptFail(err)
+      }
+    } else if (m.t === 'ckpt-mem') {
+      c.mem = m
+    }
+    ckptMaybeGo()
+  }
+
+  function ckptSvc(m) {
+    const c = ck
+    if (!c || !c.atPoint) return
+    if (m.error) return ckptFail(new CheckpointError('service', `the file service could not save its state: ${m.error}`))
+    for (const d of Object.values(m.ports)) d.segments = d.segments.map(b => new Uint8Array(b))
+    c.svc = m.ports
+    c.svcMs = m.ms
+    ckptMaybeGo()
+  }
+
+  function ckptHub(m) {
+    const c = ck
+    if (!c || !c.atPoint) return
+    try {
+      if (m.missing.length) {
+        throw new CheckpointError('jit', `the JIT hub no longer holds the bytes of ${m.missing.length} released module records (first: ${m.missing[0]}); raise bootWmd({ckptHubBytes})`)
+      }
+      c.jitSnap = captureJit(jitStore, new Map(m.got))
+      c.jitMs = absMs() - c.jitAskedAt
+      c.jitDone = true
+    } catch (err) {
+      return ckptFail(err)
+    }
+    ckptMaybeGo()
+  }
+
+  function ckptMaybeGo() {
+    const c = ck
+    if (!c || c.went || !c.mem || !c.svc || !c.jitDone) return
+    c.went = true
+    c.goAt = gnow()
+    Atomics.store(ctl, CTL_CK_GO, 1)
+    Atomics.notify(ctl, CTL_CK_GO, 1)
+    // the guest runs again when its ctl thread attaches once more (the end of the pause)
+    c.poll = setInterval(() => {
+      if (Atomics.load(ctl, CTL_CK_ATTACHES) > c.attachesBefore || gnow() - c.goAt > 15000) {
+        clearInterval(c.poll)
+        c.resumeAt = gnow()
+        ckptFinish(c)
+      }
+    }, 2)
+  }
+
+  /** W59: the network Worker's whole placeholder map (a superset of what the guest has seen), else the page's copy. */
+  function netNameList() {
+    if (!netWorker || netSvcRelayProtocol() !== 'wisp') return Promise.resolve([...netNames])
+    return new Promise(res => {
+      const id = Math.random()
+      const t = setTimeout(() => netNameWaiters.delete(id) && res([...netNames]), 2000)
+      netNameWaiters.set(id, names => {
+        clearTimeout(t)
+        for (const [n, ip] of names) {
+          if (netNames.has(n) || netIps.has(ip)) continue
+          netNames.set(n, ip)
+          netIps.add(ip)
+        }
+        res([...netNames])
+      })
+      netWorker.postMessage({ t: 'names', id })
+    })
+  }
+  function netSvcRelayProtocol() {
+    return chanSvcs?.find(s => (s.kind === 'net' || s.kind === 1) && s.relay)?.relay?.protocol || ''
+  }
+
+  function ckptFinish(c) {
+    if (ck !== c) return
+    ck = null
+    clearTimeout(c.timer)
+    netNameList().then(names => ckptAssemble(c, names))
+  }
+
+  function ckptAssemble(c, names) {
+    try {
+      const t = absMs()
+      const stats = {
+        stopLatencyMs: c.pointAt - c.t0, // request to the vCPUs stopped and the point entered (includes the guest's world stop, share drain and service stop)
+        worldStopMs: hdrNs(c.hdr, 312 - 0),
+        p9DrainMs: hdrNs(c.hdr, 320),
+        svcStopMs: hdrNs(c.hdr, 328),
+        scanMs: c.mem.scanMs,
+        copyMs: c.mem.copyMs,
+        memWaitMs: c.goAt - c.pointAt, // point entered to released: scan, copy, the page's collection of the rest
+        svcMs: c.svcMs,
+        jitMs: c.jitMs ?? 0,
+        resumeMs: c.resumeAt - c.goAt, // released to the guest's ctl thread attached again
+        nonzeroPages: c.mem.nonzero,
+        memPages: c.mem.pages,
+        scannedPages: c.mem.scannedPages,
+        scanLimitBytes: c.mem.limitBytes,
+        heapTopPage: c.mem.heapTopRet ? Math.ceil(c.mem.heapTopRet / CKPT_PAGE) : null,
+        pagesAtOrAboveHeapTop: c.mem.heapTopRet ? Array.from(c.mem.index).filter(p => p >= Math.ceil(c.mem.heapTopRet / CKPT_PAGE)).length : null, // non-zero pages the checkpoint holds from the heap top up: 0 proves the heap-top bound
+        aboveNonzeroPages: c.mem.aboveNonzero,
+        brkLive: c.mem.brkLive,
+        endLive: c.mem.endLive,
+        heapTopRet: c.mem.heapTopRet,
+      }
+      // the guest's view of the pause: stopping the world, draining the share, stopping its threads, then everything from the point to its restart
+      stats.pauseMs = stats.worldStopMs + stats.p9DrainMs + stats.svcStopMs + (c.resumeAt - c.pointAt)
+      const meta = {
+        label: c.label || '',
+        vmKey,
+        bootKey,
+        bootDesc,
+        packs: packDigests,
+        ports: resumePorts(o.args),
+        args: o.args,
+        jitShare: share,
+        fmaFused: env.includes('WMD_FMA_FUSED=1') || (!env.some(e => e.startsWith('WMD_FMA_FUSED=')) && fmaFuses()), // D-539: as browserEnv; its blocks may hold relaxed_madd
+        stats,
+      }
+      const parts = { meta, hdr: c.hdr, mem: c.mem, jit: c.jitSnap ? { snap: c.jitSnap } : null, svc: c.svc, ctl: c.ctlBytes, names }
+      const ckpt = assembleCheckpoint(parts)
+      ckpt.header.stats.assembleMs = absMs() - t
+      ckpt.header.svcStats = Object.fromEntries(Object.entries(c.svc).map(([port, d]) => [port, { bytes: d.bytes, fids: d.fids }]))
+      if (c.jitSnap) ckpt.header.jitStats = jitSnapStats(c.jitSnap)
+      c.resolve(ckpt)
+    } catch (err) {
+      c.reject(err)
+    }
+  }
+
+  /**
+   * P-B9: take a checkpoint. Resolves with {header, sections}: the guest's memory pages, the JIT slot list, the 9P
+   * service's state and the fd table, as captured at one instant while the guest was stopped. header.stats has the
+   * times. It stays usable (restore it again as often as wanted) until the caller drops it; to survive a reload save
+   * it with a store (opfsStore().save(name, ckpt)).
+   */
+  function checkpoint({ label = '', timeoutMs = 60_000 } = {}) {
+    if (!ckptOn) return Promise.reject(new Error('this machine was booted without checkpoint support: bootWmd({checkpoint: true})'))
+    if (restoring) return Promise.reject(new CheckpointError('busy', 'a restore is running: this machine is about to end, and a checkpoint taken now would be lost'))
+    if (done || chanDied) return Promise.reject(new Error('the machine has ended'))
+    if (ck) return Promise.reject(new Error('a checkpoint is already being taken'))
+    return new Promise((resolve, reject) => {
+      const c = (ck = { label, t0: gnow(), resolve, reject, attachesBefore: Atomics.load(ctl, CTL_CK_ATTACHES), timer: null })
+      c.timer = setTimeout(() => ckptFail(new CheckpointError('timeout', `the guest did not reach its checkpoint point in ${timeoutMs} ms`)), timeoutMs)
+      if (!requestCheckpoint(memory, ctl)) ckptFail(new CheckpointError('not-ready', 'the guest has not started its checkpoint thread yet (it does that once the kernel has booted); try again after the control session is up'))
+    })
+  }
+
+  /**
+   * P-B9: end this machine and continue from a checkpoint in a new one (same page, same options). Resolves with the
+   * new machine's handle. The old machine's Workers are gone when this returns; anything that was running in it (a
+   * block, a process the guest started after the checkpoint) is gone with them.
+   */
+  async function restore(ckpt, over = {}) {
+    if (restoring) throw new CheckpointError('busy', 'a restore is already running on this machine: wait for it (it returns the new machine)')
+    restoring = true
+    try {
+      // everything that can fail without harming the running machine comes first: the checkpoint parses and is this boot's
+      const parsed = parseCheckpoint(ckpt)
+      checkCheckpointFits(parsed.header, { vmKey, bootKey, bootDesc, maxPages: maximum, hasJit: o.jit !== false, fmaFused: fmaFuses() })
+      if (!heldAssets) throw new CheckpointError('not-ready', 'this machine was booted without checkpoint support: it has no kept boot files to restore with')
+      validateFdTable(parsed.ctl, heldAssets.files.length) // the fd table is checked against this boot's files now, not after the old machine is gone
+      // the boot's own bytes (vm.wasm and its compiled Module, the kernel, the packs, the keys) are reused: nothing is
+      // downloaded or hashed again, so the running machine is stopped only when the next one's inputs are in hand. After a
+      // page reload (bootWmd({restore})) they are fetched, as for any boot.
+      const reuse = !['vmUrl', 'files', 'channels', 'args', 'env', 'maxPages'].some(k => k in over)
+      const assets = reuse ? heldAssets : null
+      if (ck) ckptFail(new CheckpointError('restore', 'a restore began: the checkpoint in progress was abandoned'))
+      // W57: this machine's hub outlives it until the next one's hub has taken the Modules it can reuse (the same
+      // code: Firefox would otherwise hold two copies of the guest's code, and two guests' restores filled its 2 GiB)
+      keepHub = !!(hub && parsed.jit)
+      let oldHub = null
+      try {
+        finish(EXIT_STOPPED, 'stopped')
+        await exited
+        memory = null
+        oldHub = keptHub
+        keptHub = null
+        const next = await bootWmd({ ...o, ...over, checkpoint: true, restore: ckpt, assets, _adopt: oldHub, _net: { instance: netInstance, names: [...netNames] } })
+        heldAssets = null // the new machine holds them
+        return next
+      } finally {
+        keepHub = false
+        ;(oldHub || keptHub)?.terminate() // the replay is over (or never came): the new hub holds what it took
+        keptHub = null
+      }
+    } finally {
+      restoring = false
+    }
+  }
+
+  return {
+    exited,
+    timings,
+    /** The shared memory, for post-mortem reads; null after dispose(). */
+    get memory() {
+      return memory
+    },
+    stop: () => finish(EXIT_STOPPED, 'stopped'),
+    checkpoint,
+    restore,
+    /** P-B9: this boot's identity keys ({vmKey, bootKey}; null without checkpoint support). */
+    keys: () => (ckptOn ? { vmKey, bootKey } : null),
+    /**
+     * P-B11: wmd's control session (src/host/ctl.js ControlClient), when a channel service
+     * {kind: 'control', yamux: true} was given: run / startExec / attach / kill / procs /
+     * simple over the guest init's yamux server. null otherwise.
+     */
+    control,
+    /**
+     * Bytes (or text) for the guest's console channel (hvc0); queued until it is open.
+     * Returns how many bytes were taken: at most consoleSpace(), so the queue for a guest
+     * that does not read stays under channels.consoleInputBytes (4 MiB). The rest is not
+     * sent; write it again once consoleSpace() > 0. 0 without channels or after the end.
+     */
+    consoleWrite: data => {
+      if (!chanSvc || !consoleGate || done || chanDied) return 0
+      const all = typeof data === 'string' ? new TextEncoder().encode(data) : new Uint8Array(data)
+      const n = consoleGate.take(all.length)
+      if (n < all.length) {
+        if (!consoleFull) {
+          consoleFull = true
+          emitErr(
+            `\n[wmd-web] console input is full: the guest has not read the ${fmtMiB(consoleGate.limit)} already queued ` +
+              `(channels.consoleInputBytes); vm.consoleWrite took ${n} of ${all.length} bytes\n`,
+          )
+          ev({ t: 'chan', ev: 'console-full', took: n, of: all.length })
+        }
+      } else consoleFull = false
+      if (!n) return 0
+      const bytes = all.slice(0, n) // our own copy: the caller's buffer is not transferred
+      chanSvc.postMessage({ t: 'console', bytes }, [bytes.buffer])
+      return n
+    },
+    /** Bytes vm.consoleWrite can take now (0 without channels or after the end). */
+    consoleSpace: () => (consoleGate && chanSvc && !done && !chanDied ? consoleGate.space() : 0),
+    /**
+     * P-B10: the guest network (null without a net service with a relay or a switch): stats() asks the
+     * network Worker for its stack and relay stats; dropRelay() drops the relay WebSocket
+     * as a network failure would (test hook).
+     */
+    net: netWorker
+      ? {
+          stats: () =>
+            new Promise(res => {
+              if (!netWorker) return res(netStats)
+              const id = Math.random()
+              netWaiters.set(id, res)
+              netWorker.postMessage({ t: 'stats', id })
+              setTimeout(() => netWaiters.delete(id) && res(netStats), 2000)
+            }),
+          dropRelay: () => netWorker?.postMessage({ t: 'drop-relay' }),
+          /** W59: the relay's state for the page ({state, relay, reason, words}); returns a function that stops the calls */
+          onStatus: cb => {
+            netStatusCbs.add(cb)
+            return () => netStatusCbs.delete(cb)
+          },
+          /** W59: the last status (null before the first) */
+          status: () => netStatus,
+          /** W56: the guest's name and address on its switch (null without one) */
+          member: netMember ? { name: netMember.name, ip: netMember.ip } : null,
+        }
+      : null,
+    /**
+     * W62: the guest's writable layer on 9P service `port` (the files it made, changed and removed
+     * under the service's `at`) as one pack: Promise<{bytes (Uint8Array, a pack), entries, files,
+     * whiteouts, opaque, dataBytes, ms}>. Booted again with `layers: [bytes, ...the image's layers]`
+     * the guest finds the tree it left (a build committed once, cached between visits). The tree
+     * is read as it is at that moment: have the guest finish its writes (`sync`) first. Rejects
+     * after the machine has ended, as the service's tree ends with it.
+     */
+    exportUpper: port =>
+      new Promise((res, rej) => {
+        if (!chanSvc || done || chanDied) return rej(new Error('exportUpper: the machine has ended (its files ended with it)'))
+        const svc = chanSvcs.find(s => s.port === port && (s.kind === '9p' || s.kind === 2))
+        if (!svc) return rej(new Error(`exportUpper: no 9P service on port ${port}`))
+        const id = Math.random()
+        upperWaiters.set(id, { res, rej })
+        chanSvc.postMessage({ t: 'export-upper', id, port })
+      }),
+    /** P-B3 channel counters, and the service's latest stats (refreshed every 250 ms). */
+    chanStats: () => (chanSab ? { ...chanCounters(chanSab), service: chanStats, died: chanDied } : null),
+    /**
+     * Test hooks for the channel service: 'terminate' (the page terminates it), 'die' (it
+     * calls self.close(): only its lock tells the page), 'crash' (an exception in its loop),
+     * ['stall', ms] (busy for ms).
+     */
+    chanTest: (what, arg) => {
+      if (!chanSvc) return false
+      if (what === 'terminate') {
+        chanSvc.terminate()
+        serviceDied('the channel service Worker was terminated')
+      } else chanSvc.postMessage({ t: what, ms: arg })
+      return true
+    },
+    /**
+     * P-B8 test hook (needs bootWmd({stallHook: true})): the Worker running guest thread `tid`
+     * (1 = _start, vCPU 0) blocks at its next host call for `ms`, as if the browser had stopped
+     * it. One stall at a time: false if the hook is off, the machine has ended, or a stall is
+     * still armed. vm.stallThread(0) ends a running stall early. vm.stats().stall reports it.
+     */
+    stallThread: (tid, ms = 0) => {
+      if (!o.stallHook || done) return false
+      if (!tid) {
+        Atomics.store(ctl, CTL_STALL_TID, 0)
+        Atomics.add(ctl, CTL_STALL_WAKE, 1)
+        Atomics.notify(ctl, CTL_STALL_WAKE)
+        return true
+      }
+      Atomics.store(ctl, CTL_STALL_MS, Math.max(0, Math.min(2 ** 31 - 1, Math.round(ms))))
+      return Atomics.compareExchange(ctl, CTL_STALL_TID, 0, tid) === 0
+    },
+    /** Stop if running and drop the last reference this handle holds (the memory). */
+    dispose: () => {
+      finish(EXIT_STOPPED, 'stopped')
+      memory = null
+    },
+    stats: () => ({
+      exited: Atomics.load(ctl, CTL_EXIT),
+      exitCode: Atomics.load(ctl, CTL_EXIT_CODE),
+      liveThreads: Atomics.load(ctl, CTL_LIVE_THREADS),
+      poolWorkers: Atomics.load(ctl, CTL_POOL_N),
+      spawnFailures: Atomics.load(ctl, CTL_SPAWN_FAIL),
+      memoryPages: memory ? memory.buffer.byteLength / PAGE : null,
+      jit: jitStore ? readJitStats(jitStore) : null,
+      hostCalls: hostCallCounts(ctl),
+      throttle: throttle ? throttle.state() : null,
+      noProgressMs: done ? null : Math.round(watchdog.idleMs()),
+      stall: o.stallHook
+        ? {
+            armed: Atomics.load(ctl, CTL_STALL_TID),
+            taken: Atomics.load(ctl, CTL_STALL_TAKEN),
+            done: Atomics.load(ctl, CTL_STALL_DONE),
+            at: new Float64Array(ctlSab)[F64_STALL_AT / 8],
+            end: new Float64Array(ctlSab)[F64_STALL_END / 8],
+          }
+        : null,
+    }),
+  }
+}