@wenathlan/saddle 2.0.154 → 2.0.159

package/sandbox.ts

@@ -0,0 +1,3279 @@
+/**
+ * sandbox — consolidated sandbox engine logics of the saddle family.
+ * @module sandbox
+ * @family wave/logicfold2
+ * One keyed file per family: the former variant arms (sandboxenvprofile, sandboxprofile, sandboxqueue, sandboxquota)
+ * retired into this seat with every export preserved under the same name.
+ */
+
+/* ===== block: sandbox ===== */
+/**
+ * sandbox.ts — browser-pure port of the saddle virtual hardware engine.
+ *
+ * this module is a lightweight rewrite of the engine generators
+ * (virtualcpu.ts, virtualmemory.ts, virtualgpu.ts and render.ts) that runs
+ * unchanged in the browser and in node: it imports nothing, touches no
+ * node:* builtin and no dom api at module scope, and produces the exact
+ * same procfs payloads, the 89-character nvidia-smi summary table, the
+ * mesa software-stack summaries (rusticl opencl 3.1, lavapipe vulkan 1.4,
+ * llvmpipe opengl 4.6) and the boot dmesg sequence the native engine emits.
+ *
+ * contexts (22): cpudata, gpudata, migprofiles, vendortables, topology,
+ * cpuinfo, lscpu, pagealign, meminfo, freeh, smiformat, smitable, smilist,
+ * clinfo, vulkaninfo, glxinfo, mesaenv, bootsequence, sandboxstate,
+ * virtualfs, dispatcher, commands.
+ *
+ * rules: lowercase identifiers, english jsdoc in third person, no emoji,
+ * zero dependencies, and deterministic fallbacks when crypto randomness
+ * is unavailable.
+ */
+
+/* ------------------------------------------------------------------ */
+/* types: the exported surface                                         */
+/* ------------------------------------------------------------------ */
+
+/** reviewed processor catalog entry (mirrors the vendor pages). */
+export type CpuSpec = {
+  model: string;
+  displayname: string;
+  vendor: string;
+  arch: string;
+  cores: number;
+  threads: number;
+  baseclockmhz: number;
+  boostclockmhz: number;
+  allcoreclockmhz: number;
+  l3mb: number;
+  l2mb: number;
+  socket: string;
+  tdpwatts: number;
+  pcie: string;
+  maxmemorygb: number;
+  memorytype: string;
+  memorychannels: number;
+  microarch: string;
+  cpufamily: number;
+  cpumodel: number;
+  stepping: number;
+  physicalline: string;
+  virtualline: string;
+  launch: string;
+};
+
+/** reviewed virtual gpu catalog entry. */
+export type GpuSpec = {
+  id: string;
+  name: string;
+  vendor: string;
+  pcivendor: string;
+  pcidevice: string;
+  vrammib: number;
+  smireportedmib: number;
+  memtype: string;
+  busbits: number;
+  bandwidthgbs: number;
+  tdpwatts: number;
+  arch: string;
+  smarch: string;
+  smcount: number;
+  mig: boolean;
+  driver: string;
+  cuda: string | null;
+};
+
+/** one mig slicing profile of the 96 gb-class device. */
+export type MigProfile = {
+  id: string;
+  slicegb: number;
+  maxinstances: number;
+};
+
+/** sandbox specification accepted by createSandboxState. */
+export type SandboxSpec = {
+  model: string;
+  vcpus?: number;
+  ramgb?: number;
+  gpu: string;
+  mig?: string;
+  id?: string;
+};
+
+/** resolved smp topology for a virtual cpu spec. */
+export type CpuTopology = {
+  threadspercore: number;
+  coresonline: number;
+  vcpus: number;
+  siblings: number;
+  sockets: number;
+  fullypopulated: boolean;
+};
+
+/** one persistent workspace file entry. */
+export type SandboxFile = {
+  content: string;
+  size: number;
+  updatedat: string;
+};
+
+/** the filesystem contract shared by the api host and the memoryfs. */
+export type SandboxFs = {
+  write: (path: string, content: string) => { path: string; size: number; updatedat: string };
+  read: (path: string) => (SandboxFile & { path: string }) | null;
+  list: () => Array<{ path: string; size: number; updatedat: string }>;
+  del: (path: string) => boolean;
+};
+
+/** state object shared by the browser terminal and the api exec endpoint. */
+export type SandboxState = {
+  model: string;
+  cpuspec: CpuSpec;
+  gpuspec: GpuSpec;
+  vcpus: number;
+  ramgb: number;
+  gpu: string;
+  mig: string;
+  id: string;
+  hostname: string;
+  boottime: number;
+  kernel: string;
+  memsnapshot: string;
+  history: string[];
+  files: Map<string, SandboxFile>;
+};
+
+/** command result matching the api exec contract; clear is set by the
+ * clear command so the terminal can wipe the screen. */
+export type DispatchResult = {
+  output: string;
+  exitCode: number;
+  clear?: boolean;
+};
+
+/** optional exec context provided by the api host. */
+export type DispatchContext = {
+  fs?: SandboxFs;
+  quota?: number;
+};
+
+/* ------------------------------------------------------------------ */
+/* context: shared helpers                                             */
+/* ------------------------------------------------------------------ */
+
+/** inclusive pseudo-random integer between min and max; deterministic
+ * fallback when crypto randomness is unavailable. */
+function rnd(min: number, max: number): number {
+  try {
+    const span = max - min + 1;
+    if (typeof globalThis.crypto?.getRandomValues === 'function') {
+      const buf = new Uint32Array(1);
+      globalThis.crypto.getRandomValues(buf);
+      return min + (buf[0] % span);
+    }
+  } catch {
+    /* falls through to math.random */
+  }
+  return min + Math.floor(Math.random() * (max - min + 1));
+}
+
+/** right-pad helper that never exceeds the target width. */
+function pad(text: string, width: number): string {
+  return text.length >= width ? text.slice(0, width) : text + ' '.repeat(width - text.length);
+}
+
+/** left-pad helper for right-aligned columns. */
+function padstart(text: string, width: number): string {
+  return text.length >= width
+    ? text.slice(text.length - width)
+    : ' '.repeat(width - text.length) + text;
+}
+
+/**
+ * formats one byte count with binary units (512 B, 4 KiB, 16 MiB, 1.5 GiB);
+ * whole numbers drop the decimal so the default quota reads "16 MiB".
+ *
+ * @param {number} bytes the byte count.
+ * @returns {string} the human readable size.
+ */
+function humanbytes(bytes: number): string {
+  const value = Math.max(0, Math.round(bytes));
+  const unit = (size: number, suffix: string): string => {
+    const scaled = value / size;
+    const rounded = Math.round(scaled * 10) / 10;
+    return `${Number.isInteger(rounded) ? rounded : rounded.toFixed(1)} ${suffix}`;
+  };
+  if (value >= 1024 * 1024 * 1024) {
+    return unit(1024 * 1024 * 1024, 'GiB');
+  }
+  if (value >= 1024 * 1024) {
+    return unit(1024 * 1024, 'MiB');
+  }
+  if (value >= 1024) {
+    return unit(1024, 'KiB');
+  }
+  return `${value} B`;
+}
+
+/** lowercases a model string for case-insensitive lookups. */
+function normalizemodel(model: string): string {
+  return String(model ?? '').trim().toLowerCase();
+}
+
+/** generates a random uuid-shaped hex token with a prefix. */
+function token(prefix: string): string {
+  const raw =
+    typeof globalThis.crypto?.randomUUID === 'function'
+      ? globalThis.crypto.randomUUID().replace(/-/g, '')
+      : Array.from({ length: 32 }, () => '0123456789abcdef'[rnd(0, 15)]).join('');
+  return `${prefix}${raw.slice(0, 8)}-${raw.slice(8, 12)}-${raw.slice(12, 16)}-${raw.slice(16, 20)}-${raw.slice(20, 32)}`;
+}
+
+/* ------------------------------------------------------------------ */
+/* context: cpudata — the processor bank (specs verified 2026-08-22)   */
+/* ------------------------------------------------------------------ */
+
+/**
+ * cpudata carries the six engine-bank processors (amd epyc 9965, ryzen 9
+ * 9950x3d, threadripper pro 9995wx, threadripper 7980x, core ultra 9
+ * 285k, epyc 9955) plus the two web showcase additions intel xeon 6980p
+ * granite rapids and apple m3 ultra. every field mirrors the vendor pages
+ * and the techpowerup database as pinned by best_virtual_processors.
+ */
+export const cpudata: CpuSpec[] = [
+  {
+    model: 'AMD EPYC 9965',
+    displayname: 'AMD EPYC 9965 192-Core Processor',
+    vendor: 'amd',
+    arch: 'x86_64',
+    cores: 192,
+    threads: 384,
+    baseclockmhz: 2250,
+    boostclockmhz: 3700,
+    allcoreclockmhz: 3350,
+    l3mb: 384,
+    l2mb: 192,
+    socket: 'SP5 (LGA6096)',
+    tdpwatts: 500,
+    pcie: 'PCIe 5.0 x128',
+    maxmemorygb: 6144,
+    memorytype: 'DDR5-6400 ECC RDIMM',
+    memorychannels: 12,
+    microarch: 'Zen 5c (Turin)',
+    cpufamily: 25,
+    cpumodel: 17,
+    stepping: 2,
+    physicalline: '52 bits physical',
+    virtualline: '57 bits virtual',
+    launch: '2024-10-10',
+  },
+  {
+    model: 'AMD Ryzen 9 9950X3D',
+    displayname: 'AMD Ryzen 9 9950X3D 16-Core Processor',
+    vendor: 'amd',
+    arch: 'x86_64',
+    cores: 16,
+    threads: 32,
+    baseclockmhz: 4300,
+    boostclockmhz: 5700,
+    allcoreclockmhz: 5400,
+    l3mb: 128,
+    l2mb: 16,
+    socket: 'AM5',
+    tdpwatts: 170,
+    pcie: 'PCIe 5.0 x24',
+    maxmemorygb: 192,
+    memorytype: 'DDR5-5600',
+    memorychannels: 2,
+    microarch: 'Zen 5 X3D (3D V-Cache on one CCD)',
+    cpufamily: 25,
+    cpumodel: 17,
+    stepping: 2,
+    physicalline: '48 bits physical',
+    virtualline: '57 bits virtual',
+    launch: '2025-03-12',
+  },
+  {
+    model: 'AMD Threadripper PRO 9995WX',
+    displayname: 'AMD Ryzen Threadripper PRO 9995WX 96-Core Processor',
+    vendor: 'amd',
+    arch: 'x86_64',
+    cores: 96,
+    threads: 192,
+    baseclockmhz: 2500,
+    boostclockmhz: 5400,
+    allcoreclockmhz: 4100,
+    l3mb: 384,
+    l2mb: 96,
+    socket: 'sTR5 (LGA4844)',
+    tdpwatts: 350,
+    pcie: 'PCIe 5.0 x128',
+    maxmemorygb: 2048,
+    memorytype: 'DDR5-6400 ECC RDIMM',
+    memorychannels: 8,
+    microarch: 'Zen 5 (Shimada Peak, WRX90)',
+    cpufamily: 25,
+    cpumodel: 17,
+    stepping: 2,
+    physicalline: '52 bits physical',
+    virtualline: '57 bits virtual',
+    launch: '2025-07',
+  },
+  {
+    model: 'AMD Threadripper 7980X',
+    displayname: 'AMD Ryzen Threadripper 7980X 64-Core Processor',
+    vendor: 'amd',
+    arch: 'x86_64',
+    cores: 64,
+    threads: 128,
+    baseclockmhz: 3200,
+    boostclockmhz: 5100,
+    allcoreclockmhz: 4400,
+    l3mb: 256,
+    l2mb: 64,
+    socket: 'sTR5',
+    tdpwatts: 350,
+    pcie: 'PCIe 5.0 x48',
+    maxmemorygb: 1024,
+    memorytype: 'DDR5-6400',
+    memorychannels: 4,
+    microarch: 'Zen 5 (TRX50)',
+    cpufamily: 25,
+    cpumodel: 17,
+    stepping: 2,
+    physicalline: '52 bits physical',
+    virtualline: '57 bits virtual',
+    launch: '2023-10',
+  },
+  {
+    model: 'Intel Core Ultra 9 285K',
+    displayname: 'Intel(R) Core(TM) Ultra 9 285K',
+    vendor: 'intel',
+    arch: 'x86_64',
+    cores: 24,
+    threads: 24,
+    baseclockmhz: 3700,
+    boostclockmhz: 5700,
+    allcoreclockmhz: 5400,
+    l3mb: 36,
+    l2mb: 36,
+    socket: 'LGA1851',
+    tdpwatts: 125,
+    pcie: 'PCIe 5.0 x20 + PCIe 4.0 x4',
+    maxmemorygb: 192,
+    memorytype: 'DDR5-6400',
+    memorychannels: 2,
+    microarch: 'Arrow Lake (8P + 16E, no hyper-threading)',
+    cpufamily: 6,
+    cpumodel: 191,
+    stepping: 2,
+    physicalline: '46 bits physical',
+    virtualline: '57 bits virtual',
+    launch: '2024-10-24',
+  },
+  {
+    model: 'AMD EPYC 9955',
+    displayname: 'AMD EPYC 9955 128-Core Processor',
+    vendor: 'amd',
+    arch: 'x86_64',
+    cores: 128,
+    threads: 256,
+    baseclockmhz: 2600,
+    boostclockmhz: 3750,
+    allcoreclockmhz: 3450,
+    l3mb: 384,
+    l2mb: 128,
+    socket: 'SP5',
+    tdpwatts: 400,
+    pcie: 'PCIe 5.0 x128',
+    maxmemorygb: 6144,
+    memorytype: 'DDR5-6400 ECC RDIMM',
+    memorychannels: 12,
+    microarch: 'Zen 5c (Turin dense)',
+    cpufamily: 25,
+    cpumodel: 17,
+    stepping: 2,
+    physicalline: '52 bits physical',
+    virtualline: '57 bits virtual',
+    launch: '2024-10-10',
+  },
+  {
+    model: 'Intel Xeon 6980P',
+    displayname: 'Intel(R) Xeon(R) Platinum 6980P',
+    vendor: 'intel',
+    arch: 'x86_64',
+    cores: 128,
+    threads: 256,
+    baseclockmhz: 2200,
+    boostclockmhz: 3900,
+    allcoreclockmhz: 3300,
+    l3mb: 504,
+    l2mb: 128,
+    socket: 'LGA4710',
+    tdpwatts: 350,
+    pcie: 'PCIe 5.0 x128 + CXL 2.0 x16',
+    maxmemorygb: 6144,
+    memorytype: 'DDR5-6400 / MRDIMM-8800',
+    memorychannels: 12,
+    microarch: 'Granite Rapids (Intel 3)',
+    cpufamily: 6,
+    cpumodel: 173,
+    stepping: 2,
+    physicalline: '46 bits physical',
+    virtualline: '57 bits virtual',
+    launch: '2025-02',
+  },
+  {
+    model: 'Apple M3 Ultra',
+    displayname: 'Apple M3 Ultra (24P + 8E, 32-core CPU)',
+    vendor: 'apple',
+    arch: 'arm64',
+    cores: 32,
+    threads: 32,
+    baseclockmhz: 1000,
+    boostclockmhz: 4050,
+    allcoreclockmhz: 3400,
+    l3mb: 96,
+    l2mb: 96,
+    socket: 'soldered (UltraFusion interconnect)',
+    tdpwatts: 140,
+    pcie: 'PCIe 4.0 x8 + Thunderbolt 5 x2',
+    maxmemorygb: 512,
+    memorytype: 'LPDDR5 unified 819 GB/s',
+    memorychannels: 16,
+    microarch: 'Everest (3nm, two M3 Max dies fused)',
+    cpufamily: 0,
+    cpumodel: 0,
+    stepping: 0,
+    physicalline: '44 bits physical',
+    virtualline: '48 bits virtual',
+    launch: '2025-03',
+  },
+];
+
+/** resolves a processor spec by model name, case-insensitive; returns
+ * undefined for unknown models so callers can shape friendly errors. */
+export function getcpu(model: string): CpuSpec | undefined {
+  const needle = normalizemodel(model);
+  return cpudata.find((spec) => normalizemodel(spec.model) === needle);
+}
+
+/**
+ * resolves a catalog entry by its slug id (epyc-9965) as served by the
+ * /api/v1/specs/cpus endpoint; returns undefined for unknown ids.
+ * @param {string} id the catalog id.
+ * @returns {object | undefined} the matching cpu entry.
+ */
+export function getcpubyid(id: string): CpuSpec | undefined {
+  const key = String(id).toLowerCase().replace(/\s+/g, '-');
+  const strip = (name: string): string =>
+    name
+      .toLowerCase()
+      .replace(/\s+/g, '-')
+      .replace(/^(amd|intel|apple|nvidia)-/, '');
+  return cpudata.find((entry) => {
+    const slug = entry.model.toLowerCase().replace(/\s+/g, '-');
+    return slug === key || slug.endsWith(key) || strip(entry.model) === strip(key);
+  });
+}
+
+/* ------------------------------------------------------------------ */
+/* context: vendortables — flag sets and identity strings              */
+/* ------------------------------------------------------------------ */
+
+/** zen 5 flag set exactly as generatevirtualcpuinfo renders it (avx-512
+ * family, sha_ni, gfni and friends). */
+const zen5flags = [
+  'fpu', 'vme', 'de', 'pse', 'tsc', 'msr', 'pae', 'mce', 'cx8', 'apic',
+  'sep', 'mtrr', 'pge', 'mca', 'cmov', 'pat', 'pse36', 'clflush', 'mmx',
+  'fxsr', 'sse', 'sse2', 'ht', 'syscall', 'nx', 'mmxext', 'fxsr_opt',
+  'pdpe1gb', 'rdtscp', 'lm', 'constant_tsc', 'rep_good', 'amd_lbr_v2',
+  'nopl', 'nonstop_tsc', 'cpuid', 'extd_apicid', 'aperfmperf', 'rapl',
+  'pclmulqdq', 'monitor', 'ssse3', 'fma', 'cx16', 'sse4_1', 'sse4_2',
+  'x2apic', 'movbe', 'popcnt', 'aes', 'xsave', 'avx', 'f16c', 'rdrand',
+  'lahf_lm', 'cmp_legacy', 'svm', 'extapic', 'cr8_legacy', 'abm', 'sse4a',
+  'misalignsse', '3dnowprefetch', 'osvw', 'ibs', 'skinit', 'wdt', 'tce',
+  'topoext', 'perfctr_core', 'perfctr_nb', 'bpext', 'perfctr_llc',
+  'mwaitx', 'cpb', 'cat_l3', 'cdp_l3', 'hw_pstate', 'ssbd', 'mba',
+  'perfmon_v2', 'ibrs', 'ibpb', 'stibp', 'vmmcall', 'fsgsbase', 'bmi1',
+  'avx2', 'smep', 'bmi2', 'erms', 'invpcid', 'cqm', 'rdt_a', 'avx512f',
+  'avx512dq', 'rdseed', 'adx', 'smap', 'clflushopt', 'clwb', 'avx512vl',
+  'avx512bw', 'avx512cd', 'avx512_bf16', 'avx512vbmi', 'avx512vbmi2',
+  'avx512ifma', 'avx512vp2intersect', 'sha_ni', 'gfni', 'vaes',
+  'vpclmulqdq', 'avx512vpopcntdq', 'avx512vnni', 'avx512bitalg', 'rdpid',
+  'movdiri', 'movdir64b', 'fsrm', 'cldemote', 'serialize', 'flush_l1d',
+  'arch_capabilities',
+];
+
+/** arrow lake / granite rapids flag set: avx2 with avx_vnni and no avx-512
+ * execution units; the ht flag is appended per model because arrow lake
+ * ships without hyper-threading while xeon 6 keeps it. */
+const intelflags = [
+  'fpu', 'vme', 'de', 'pse', 'tsc', 'msr', 'pae', 'mce', 'cx8', 'apic',
+  'sep', 'mtrr', 'pge', 'mca', 'cmov', 'pat', 'pse36', 'clflush', 'mmx',
+  'fxsr', 'sse', 'sse2', 'syscall', 'nx', 'pdpe1gb', 'rdtscp', 'lm',
+  'constant_tsc', 'arch_perfmon', 'rep_good', 'nopl', 'xtopology',
+  'nonstop_tsc', 'cpuid', 'aperfmperf', 'tsc_known_freq', 'pclmulqdq',
+  'monitor', 'ssse3', 'fma', 'cx16', 'sse4_1', 'sse4_2', 'x2apic', 'movbe',
+  'popcnt', 'aes', 'xsave', 'avx', 'f16c', 'rdrand', 'lahf_lm', 'abm',
+  '3dnowprefetch', 'cpuid_fault', 'epb', 'invpcid_single', 'ssbd', 'ibrs',
+  'ibpb', 'stibp', 'ibrs_enhanced', 'tpr_shadow', 'vnmi', 'flexpriority',
+  'ept', 'vpid', 'ept_ad', 'fsgsbase', 'tsc_adjust', 'bmi1', 'avx2',
+  'smep', 'bmi2', 'erms', 'invpcid', 'rdseed', 'adx', 'smap',
+  'clflushopt', 'clwb', 'sha_ni', 'xsaveopt', 'xsavec', 'xgetbv1',
+  'xsaves', 'split_lock_detect', 'user_shstk', 'avx_vnni', 'waitpkg',
+  'gfni', 'vaes', 'vpclmulqdq', 'rdpid', 'movdiri', 'movdir64b', 'fsrm',
+  'md_clear', 'serialize', 'tsxldtrk', 'la57', 'cldemote',
+  'arch_capabilities',
+];
+
+/** arm64 feature line rendered for apple silicon cpuinfo blocks. */
+const armfeatures = [
+  'fp', 'asimd', 'aes', 'pmull', 'sha1', 'sha2', 'sha3', 'sha512', 'crc32',
+  'atomics', 'fphp', 'asimdhp', 'cpuid', 'asimdrdm', 'jscvt', 'fcma',
+  'lrcpc', 'dcpop', 'sm3', 'sm4', 'asimddp', 'uscat', 'ilrcpc', 'flagm',
+  'ssbs', 'sb', 'paca', 'pacg', 'dcpodp', 'flagm2', 'frint', 'ecs', 'wfxt',
+  'bti',
+];
+
+/** per-vendor identity block consumed by cpuinfo and lscpu. */
+type VendorTable = {
+  vendorid: string;
+  flags: string[];
+  bugs: string;
+  tlbsize: string | null;
+  cpuidlevel: number;
+  powermanagement: string;
+};
+
+/** vendor identity table consumed by cpuinfo and lscpu. */
+const vendortables: Record<string, VendorTable> = {
+  amd: {
+    vendorid: 'AuthenticAMD',
+    flags: zen5flags,
+    bugs: 'sysret_ss_attrs spectre_v1 spectre_v2 spec_store_bypass srso',
+    tlbsize: '3584 2M/4M pages',
+    cpuidlevel: 16,
+    powermanagement: 'ts ttp tm hwpstate cpb eff_freq_ro [13] [14]',
+  },
+  intel: {
+    vendorid: 'GenuineIntel',
+    flags: intelflags,
+    bugs: 'spectre_v1 spectre_v2 spec_store_bypass swapgs eibrs_pbrsb',
+    tlbsize: null,
+    cpuidlevel: 32,
+    powermanagement:
+      'ts ttp tm hwpstate cpb eff_freq_ro [8] [9] [10] [11] [12] [13] [14]',
+  },
+  apple: {
+    vendorid: 'Apple',
+    flags: armfeatures,
+    bugs: '',
+    tlbsize: null,
+    cpuidlevel: 0,
+    powermanagement: '',
+  },
+};
+
+/* ------------------------------------------------------------------ */
+/* context: topology                                                   */
+/* ------------------------------------------------------------------ */
+
+/**
+ * solves the package topology for a vcpu count against a spec; mirrors
+ * solvetopology from virtualcpu.ts (smt parts round core counts up,
+ * heterogeneous parts report one thread per core and the count is clamped
+ * to the model thread ceiling).
+ */
+export function solvetopology(spec: CpuSpec, vcpus: number): CpuTopology {
+  const threadspercore = Math.max(1, Math.round(spec.threads / spec.cores));
+  const count = Math.max(1, Math.min(Math.round(vcpus) || 1, spec.threads));
+  return {
+    vcpus: count,
+    threadspercore,
+    coresonline: Math.ceil(count / threadspercore),
+    siblings: count,
+    sockets: 1,
+    fullypopulated: count === spec.threads,
+  };
+}
+
+/* ------------------------------------------------------------------ */
+/* context: cpuinfo — /proc/cpuinfo generation                         */
+/* ------------------------------------------------------------------ */
+
+/** per-key tab alignment the kernel uses on x86 cpuinfo lines. */
+const keytabs: Record<string, string> = {
+  processor: '\t', vendor_id: '\t', 'cpu family': '\t', model: '\t\t',
+  'model name': '\t', stepping: '\t', microcode: '\t', 'cpu MHz': '\t\t',
+  'cache size': '\t', 'physical id': '\t', siblings: '\t', 'core id': '\t\t',
+  'cpu cores': '\t', apicid: '\t\t', 'initial apicid': '\t', fpu: '\t\t',
+  fpu_exception: '\t', 'cpuid level': '\t', wp: '\t\t', flags: '\t\t',
+  bugs: '\t\t', bogomips: '\t', 'TLB size': '\t', 'clflush size': '\t',
+  cache_alignment: '', 'address sizes': '\t', 'power management': '',
+};
+
+/** renders one cpuinfo line exactly as procfs does: key, tabs, colon, value. */
+function line(key: string, value: number | string): string {
+  const tabs = keytabs[key] ?? '\t';
+  return `${key}${tabs}: ${value}`;
+}
+
+/**
+ * generates a complete /proc/cpuinfo text for a bank model with an
+ * arbitrary vcpu count; x86_64 models render the full zen 5 / intel flag
+ * set per logical processor and the apple model renders the arm64 cpuinfo
+ * block shape instead.
+ *
+ * @param {string} model model name present in cpudata.
+ * @param {number} vcpus number of logical processors to render.
+ * @returns {string} the full procfs payload.
+ */
+
+
+export function cpuinfo(model: string, vcpus: number): string {
+  const spec = getcpu(model);
+  if (spec === undefined) {
+    throw new Error(
+      `unknown processor model "${model}"; known models: ${cpudata.map((entry) => entry.model).join(', ')}`,
+    );
+  }
+  const topology = solvetopology(spec, vcpus);
+  const table = vendortables[spec.vendor];
+  const blocks = [];
+  for (let processor = 0; processor < topology.vcpus; processor += 1) {
+    if (spec.vendor === 'apple') {
+      blocks.push(
+        [
+          `processor\t: ${processor}`,
+          'BogoMIPS\t: 48.00',
+          `Features\t: ${table.flags.join(' ')}`,
+          'CPU implementer\t: 0x41',
+          'CPU architecture: 8',
+          'CPU variant\t: 0x2',
+          'CPU part\t: 0x612',
+          `CPU revision\t: ${processor % 2 === 0 ? 0 : 3}`,
+          '',
+          `MIDR_EL1\t: 0x0000000041026${processor % 2 === 0 ? '00' : '03'}`,
+          'Revidr_EL1\t: 0x00000000',
+          `CPU affinity\t: ${processor}`,
+        ].join('\n'),
+      );
+      continue;
+    }
+    const currentmhz = rnd(
+      Math.round(spec.baseclockmhz),
+      Math.round(spec.boostclockmhz) + 1,
+    );
+    const bogomips = (spec.baseclockmhz * 2 + rnd(-40, 41) / 100).toFixed(2);
+    const coreid = Math.floor(processor / topology.threadspercore);
+    const flags =
+      spec.vendor === 'intel' && topology.threadspercore === 2
+        ? `${table.flags.join(' ')} ht`
+        : table.flags.join(' ');
+    const rows = [
+      line('processor', processor),
+      line('vendor_id', table.vendorid),
+      line('cpu family', spec.cpufamily),
+      line('model', spec.cpumodel),
+      line('model name', spec.displayname),
+      line('stepping', spec.stepping),
+      line('microcode', '0xffffffff'),
+      line('cpu MHz', currentmhz.toFixed(3)),
+      line('cache size', `${spec.l3mb} MB`),
+      line('physical id', 0),
+      line('siblings', topology.siblings),
+      line('core id', coreid),
+      line('cpu cores', topology.coresonline),
+      line('apicid', processor),
+      line('initial apicid', processor),
+      line('fpu', 'yes'),
+      line('fpu_exception', 'yes'),
+      line('cpuid level', table.cpuidlevel),
+      line('wp', 'yes'),
+      line('flags', flags),
+      line('bugs', table.bugs),
+      line('bogomips', bogomips),
+    ];
+    if (table.tlbsize !== null) {
+      rows.push(line('TLB size', table.tlbsize));
+    }
+    rows.push(
+      line('clflush size', 64),
+      line('cache_alignment', 64),
+      line('address sizes', `${spec.physicalline}, ${spec.virtualline}`),
+      line('power management', table.powermanagement),
+    );
+    blocks.push(rows.join('\n'));
+  }
+  return blocks.join('\n\n');
+}
+
+/**
+ * generates the util-linux lscpu summary for a bank model with numa node
+ * ranges and vulnerability lines, mirroring generatevirtuallscpu.
+ *
+ * @param {string} model model name present in cpudata.
+ * @param {number} vcpus logical processor count.
+ * @param {number} [numanodes=1] number of numa nodes to spread over.
+ * @returns {string} the lscpu text block.
+ */
+export function lscpu(model: string, vcpus: number, numanodes: number = 1): string {
+  const spec = getcpu(model);
+  if (spec === undefined) {
+    throw new Error(`unknown processor model "${model}"`);
+  }
+  const topology = solvetopology(spec, vcpus);
+  const corespersocket = Math.ceil(topology.coresonline / numanodes) * numanodes;
+  const rows = [
+    ['Architecture:', spec.arch === 'arm64' ? 'aarch64' : 'x86_64'],
+    ['CPU op-mode(s):', '32-bit, 64-bit'],
+    ['Byte Order:', 'Little Endian'],
+    ['Address sizes:', `${spec.physicalline}, ${spec.virtualline}`],
+    ['CPU(s):', String(topology.vcpus)],
+    ['On-line CPU(s) list:', topology.vcpus === 1 ? '0' : `0-${topology.vcpus - 1}`],
+  ];
+  if (spec.vendor === 'apple') {
+    rows.push(
+      ['Vendor ID:', 'Apple'],
+      ['Model name:', spec.displayname],
+      ['Thread(s) per core:', '1'],
+      ['Core(s) per socket:', String(topology.coresonline)],
+      ['Socket(s):', '1'],
+      ['Cluster(s)-wide:', '24 performance + 8 efficiency cores'],
+      ['Frequency boost:', 'enabled'],
+      ['CPU max MHz:', `${spec.boostclockmhz}.0000`],
+      ['CPU min MHz:', '600.0000'],
+    );
+  } else {
+    rows.push(
+      ['Vendor ID:', vendortables[spec.vendor].vendorid],
+      ['Model name:', spec.displayname],
+      ['CPU family:', String(spec.cpufamily)],
+      ['Model:', String(spec.cpumodel)],
+      ['Thread(s) per core:', String(topology.threadspercore)],
+      ['Core(s) per socket:', String(corespersocket)],
+      ['Socket(s):', '1'],
+      ['Stepping:', String(spec.stepping)],
+      ['Frequency boost:', 'enabled'],
+      ['CPU max MHz:', `${spec.boostclockmhz}.0000`],
+      ['CPU min MHz:', `${(spec.baseclockmhz * 0.62).toFixed(4)}`],
+      ['BogoMIPS:', `${(spec.baseclockmhz * 2).toFixed(2)}`],
+      [
+        'L1d cache:',
+        `${Math.round((spec.l2mb / spec.cores) * 1024)} KiB (${spec.cores} instances)`,
+      ],
+      ['L2 cache:', `${spec.l2mb} MiB (${spec.cores} instances)`],
+      ['L3 cache:', `${spec.l3mb} MiB (${Math.max(1, Math.round(spec.cores / 8))} instances)`],
+    );
+  }
+  rows.push(['NUMA node(s):', String(numanodes)]);
+  const pernode = Math.ceil(topology.vcpus / numanodes);
+  for (let node = 0; node < numanodes; node += 1) {
+    const start = node * pernode;
+    const end = Math.min(start + pernode, topology.vcpus) - 1;
+    rows.push([`NUMA node${node} CPU(s):`, start === end ? String(start) : `${start}-${end}`]);
+  }
+  if (spec.vendor !== 'apple') {
+    rows.push(
+      ['Vulnerability Itlb multihit:', 'Not affected'],
+      ['Vulnerability L1tf:', 'Not affected'],
+      ['Vulnerability Mds:', 'Not affected'],
+      ['Vulnerability Meltdown:', 'Not affected'],
+      [
+        'Vulnerability Spectre v1:',
+        'Mitigation; usercopy/swapgs barriers and __user pointer sanitization',
+      ],
+      [
+        'Vulnerability Spectre v2:',
+        spec.vendor === 'amd' ? 'Mitigation; Retpolines, IBPB' : 'Mitigation; Enhanced IBRS',
+      ],
+    );
+  }
+  return rows.map(([key, value]) => `${key.padEnd(28)}${value}`).join('\n');
+}
+
+/* ------------------------------------------------------------------ */
+/* context: gpudata and migprofiles                                    */
+/* ------------------------------------------------------------------ */
+
+/**
+ * gpudata mirrors the verified gpu_bank: seven real identities with
+ * vrammib (physical capacity) and smireportedmib (the value after the
+ * firmware carveout) cross-checked on 2026-08-22.
+ */
+export const gpudata: GpuSpec[] = [
+  {
+    id: 'rtx5090', name: 'NVIDIA GeForce RTX 5090', vendor: 'nvidia',
+    pcivendor: '10DE', pcidevice: '2B85', vrammib: 32768,
+    smireportedmib: 32607, memtype: 'GDDR7', busbits: 512,
+    bandwidthgbs: 1792, tdpwatts: 575, arch: 'GB202 Blackwell',
+    smarch: 'sm_120', smcount: 170, mig: false, driver: '575.57.08',
+    cuda: '12.9',
+  },
+  {
+    id: 'rtxpro6000', name: 'NVIDIA RTX PRO 6000 Blackwell', vendor: 'nvidia',
+    pcivendor: '10DE', pcidevice: '26B5', vrammib: 98304,
+    smireportedmib: 98304, memtype: 'GDDR7 ECC', busbits: 512,
+    bandwidthgbs: 1792, tdpwatts: 600, arch: 'GB202 Blackwell workstation',
+    smarch: 'sm_120', smcount: 188, mig: true, driver: '575.57.08',
+    cuda: '12.9',
+  },
+  {
+    id: 'b200', name: 'NVIDIA B200', vendor: 'nvidia',
+    pcivendor: '10DE', pcidevice: '2665', vrammib: 196608,
+    smireportedmib: 184320, memtype: 'HBM3e', busbits: 8192,
+    bandwidthgbs: 8000, tdpwatts: 1000, arch: 'GB100 Blackwell dual-die',
+    smarch: 'sm_100', smcount: 208, mig: true, driver: '575.57.08',
+    cuda: '12.9',
+  },
+  {
+    id: 'h100', name: 'NVIDIA H100 80GB HBM3', vendor: 'nvidia',
+    pcivendor: '10DE', pcidevice: '2330', vrammib: 81920,
+    smireportedmib: 81559, memtype: 'HBM3', busbits: 6144,
+    bandwidthgbs: 3350, tdpwatts: 700, arch: 'GH100 Hopper SXM5',
+    smarch: 'sm_90', smcount: 132, mig: true, driver: '575.57.08',
+    cuda: '12.9',
+  },
+  {
+    id: 'a100', name: 'NVIDIA A100-SXM4-40GB', vendor: 'nvidia',
+    pcivendor: '10DE', pcidevice: '20B0', vrammib: 40960,
+    smireportedmib: 40536, memtype: 'HBM2e', busbits: 5120,
+    bandwidthgbs: 1555, tdpwatts: 400, arch: 'GA100 Ampere SXM4',
+    smarch: 'sm_80', smcount: 108, mig: true, driver: '575.57.08',
+    cuda: '12.9',
+  },
+  {
+    id: 'rx9070xt', name: 'AMD Radeon RX 9070 XT', vendor: 'amd',
+    pcivendor: '1002', pcidevice: '748E', vrammib: 16384,
+    smireportedmib: 16384, memtype: 'GDDR6', busbits: 256,
+    bandwidthgbs: 640, tdpwatts: 304, arch: 'Navi 48 RDNA 4',
+    smarch: 'gfx1201', smcount: 64, mig: false,
+    driver: 'mesa 26.2.1 / rusticl', cuda: null,
+  },
+  {
+    id: 'mi350x', name: 'AMD Instinct MI350X', vendor: 'amd',
+    pcivendor: '1002', pcidevice: '75A0', vrammib: 294912,
+    smireportedmib: 294912, memtype: 'HBM3e', busbits: 8192,
+    bandwidthgbs: 8000, tdpwatts: 1000, arch: 'CDNA 4 Aqua Vanjaram',
+    smarch: 'gfx950', smcount: 304, mig: false, driver: 'rocm 7.x',
+    cuda: null,
+  },
+];
+
+/** resolves a gpu spec by id or name, case-insensitive. */
+export function getgpu(gpu: string): GpuSpec | undefined {
+  const needle = normalizemodel(gpu);
+  return gpudata.find(
+    (spec) =>
+      normalizemodel(spec.id) === needle || normalizemodel(spec.name) === needle,
+  );
+}
+
+/**
+ * migprofiles mirrors the mig catalog of the 96 gb-class virtual device:
+ * 1g.24gb exposes 24 gb slices (4 instances), 2g.48gb 48 gb slices (2
+ * instances) and 4g.96gb dedicates the full device to one instance.
+ */
+export const migprofiles: MigProfile[] = [
+  { id: '1g.24gb', slicegb: 24, maxinstances: 4 },
+  { id: '2g.48gb', slicegb: 48, maxinstances: 2 },
+  { id: '4g.96gb', slicegb: 96, maxinstances: 1 },
+];
+
+/** resolves a mig profile by id; null for 'off' and unknown names. */
+export function getmig(id: string | null | undefined): MigProfile | null {
+  if (id === 'off' || id === undefined || id === null || id === '') {
+    return null;
+  }
+  return migprofiles.find((profile) => profile.id === id) ?? null;
+}
+
+/* ------------------------------------------------------------------ */
+/* context: meminfo and free — /proc/meminfo generation                */
+/* ------------------------------------------------------------------ */
+
+/** rounds a kb value down to the nearest 4 kb page boundary. */
+export function pagealign(kb: number): number {
+  return Math.floor(kb / 4) * 4;
+}
+
+/**
+ * generates a complete /proc/meminfo text for the requested total ram in
+ * gb, mirroring generatevirtualmeminfo: memtotal, memfree, memavailable,
+ * buffers, cached, the anon/file split, swap, slab, commit accounting
+ * under vm.overcommit_memory=2 semantics and the direct map breakdown.
+ *
+ * @param {number} ramgb total guest ram in gb (positive number).
+ * @param {{swapgb?: number, vcpus?: number, freefraction?: number,
+ *   availablefraction?: number}} [options] optional overrides.
+ * @returns {string} the full meminfo payload.
+ */
+export function meminfo(
+  ramgb: number,
+  options: {
+    swapgb?: number;
+    vcpus?: number;
+    freefraction?: number;
+    availablefraction?: number;
+  } = {},
+): string {
+  if (!Number.isFinite(ramgb) || ramgb <= 0) {
+    throw new Error(`ramgb must be a positive number, received ${ramgb}`);
+  }
+  const vcpus = options.vcpus ?? 8;
+  const totalkb = pagealign(ramgb * 1024 * 1024 - 131072);
+  const freefraction = options.freefraction ?? rnd(38, 68) / 1000;
+  const availablefraction = options.availablefraction ?? rnd(860, 930) / 1000;
+  const memfree = pagealign(totalkb * freefraction);
+  const memavailable = pagealign(totalkb * availablefraction);
+  const buffers = pagealign(totalkb * (rnd(50, 80) / 10000));
+  const cached = pagealign(totalkb * (rnd(300, 420) / 1000));
+  const activeanon = pagealign(totalkb * (rnd(240, 320) / 1000));
+  const inactiveanon = pagealign(totalkb * (rnd(60, 120) / 1000));
+  const active = pagealign(activeanon + cached * 0.55);
+  const inactive = pagealign(inactiveanon + cached * 0.4);
+  const swapgb = options.swapgb ?? Math.min(Math.max(Math.round(ramgb / 8), 2), 128);
+  const swaptotal = swapgb * 1024 * 1024;
+  const swapfree = pagealign(swaptotal * (rnd(850, 980) / 1000));
+  const commitlimit = pagealign(swaptotal + (totalkb * 50) / 100);
+  const committedas = pagealign(totalkb * (rnd(95, 160) / 100));
+  const slab = pagealign(totalkb * (rnd(190, 240) / 10000));
+  const sreclaimable = pagealign(slab * 0.64);
+  const anonhuge = pagealign(activeanon * (rnd(20, 45) / 100));
+  const directmap1g = ramgb >= 64 ? pagealign(totalkb * 0.8) : 0;
+  const directmap2m =
+    directmap1g > 0 ? pagealign(totalkb * 0.15) : pagealign(totalkb * 0.9);
+  const rows: Array<[string, number]> = [
+    ['MemTotal', totalkb], ['MemFree', memfree],
+    ['MemAvailable', memavailable], ['Buffers', buffers], ['Cached', cached],
+    ['SwapCached', 0], ['Active', active], ['Inactive', inactive],
+    ['Active(anon)', activeanon], ['Inactive(anon)', inactiveanon],
+    ['Active(file)', pagealign(active - activeanon)],
+    ['Inactive(file)', pagealign(inactive - inactiveanon)],
+    ['Unevictable', pagealign(rnd(16384, 65536))],
+    ['Mlocked', pagealign(rnd(4096, 16384))],
+    ['SwapTotal', swaptotal], ['SwapFree', swapfree],
+    ['Dirty', pagealign(rnd(20480, 262144))], ['Writeback', 0],
+    ['AnonPages', pagealign(activeanon * 1.08)],
+    ['Mapped', pagealign(totalkb * (rnd(20, 42) / 1000))],
+    ['Shmem', pagealign(totalkb * (rnd(5, 12) / 1000))],
+    ['KReclaimable', sreclaimable], ['Slab', slab],
+    ['SReclaimable', sreclaimable],
+    ['SUnreclaim', pagealign(slab - sreclaimable)],
+    ['KernelStack', pagealign(vcpus * 320)],
+    ['PageTables', pagealign(totalkb * (rnd(30, 60) / 10000))],
+    ['SecPageTables', pagealign(totalkb * (rnd(8, 16) / 10000))],
+    ['NFS_Unstable', 0], ['Bounce', 0], ['WritebackTmp', 0],
+    ['CommitLimit', commitlimit], ['Committed_AS', committedas],
+    ['VmallocTotal', 34359738367],
+    ['VmallocUsed', pagealign(rnd(49152, 131072))], ['VmallocChunk', 0],
+    ['Percpu', pagealign(vcpus * rnd(20480, 40960))],
+    ['HardwareCorrupted', 0], ['AnonHugePages', anonhuge],
+    ['ShmemHugePages', 0], ['ShmemPmdMapped', 0], ['FileHugePages', 0],
+    ['FilePmdMapped', 0], ['Unaccepted', 0], ['HugePages_Total', 0],
+    ['HugePages_Free', 0], ['HugePages_Rsvd', 0], ['HugePages_Surp', 0],
+    ['Hugepagesize', 2048], ['Hugetlb', 0],
+    ['DirectMap4k', pagealign(rnd(131072, 262144))],
+    ['DirectMap2M', directmap2m], ['DirectMap1G', directmap1g],
+  ];
+  return rows
+    .map(([key, value]) => `${key}:${String(value).padStart(24 - key.length - 1)} kB`)
+    .join('\n');
+}
+
+/** converts a kb value to the largest human unit for free -h. */
+function human(kb: number): string {
+  if (kb >= 1024 * 1024) {
+    const gb = kb / (1024 * 1024);
+    return `${gb >= 100 ? Math.round(gb) : gb.toFixed(1)}Gi`;
+  }
+  if (kb >= 1024) {
+    return `${(kb / 1024).toFixed(1)}Mi`;
+  }
+  return `${Math.round(kb)}Ki`;
+}
+
+/**
+ * renders the free -h table derived from a memoized meminfo snapshot so
+ * cat /proc/meminfo and free -h always agree inside one sandbox.
+ *
+ * @param {string} meminfotext a payload previously returned by meminfo().
+ * @returns {string} the free -h table.
+ */
+export function freeh(meminfotext: string): string {
+  const map: Record<string, number> = {};
+  for (const row of meminfotext.split('\n')) {
+    const match = /^([A-Za-z_()]+):\s*(\d+)\skB$/.exec(row);
+    if (match !== null) {
+      map[match[1]] = Number(match[2]);
+    }
+  }
+  const total = map.MemTotal ?? 0;
+  const freekb = map.MemFree ?? 0;
+  const buffers = map.Buffers ?? 0;
+  const cached = (map.Cached ?? 0) + (map.SReclaimable ?? 0);
+  const available = map.MemAvailable ?? 0;
+  const used = Math.max(0, total - freekb - buffers - cached);
+  const swap = map.SwapTotal ?? 0;
+  const swapfreekb = map.SwapFree ?? 0;
+  const swapused = swap - swapfreekb;
+  const w = (text: string): string => padstart(String(text), 13);
+  return [
+    `${w('total')}${w('used')}${w('free')}${w('shared')}${w('buff/cache')}${w('available')}`,
+    ['Mem:', w(human(total)), w(human(used)), w(human(freekb)),
+      w(human(map.Shmem ?? 0)), w(human(buffers + cached)), w(human(available))].join(''),
+    ['Swap:', w(human(swap)), w(human(swapused)), w(human(swapfreekb))].join(''),
+  ].join('\n');
+}
+
+/* ------------------------------------------------------------------ */
+/* context: smiformat — the exact 89-char summary table                */
+/* ------------------------------------------------------------------ */
+
+const smiwidth = 89;
+const smicolumns = [40, 24, 21];
+const procwidth = 75;
+const smidriver = '575.57.08';
+const cudaversion = '12.9';
+const weekdays = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
+const months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+
+/** formats the nvidia-smi timestamp "weekday month day hh:mm:ss year". */
+function formatstamp(date: Date): string {
+  const two = (value: number): string => String(value).padStart(2, '0');
+  return `${weekdays[date.getDay()]} ${months[date.getMonth()]} ${two(date.getDate())} ${two(date.getHours())}:${two(date.getMinutes())}:${two(date.getSeconds())} ${date.getFullYear()}`;
+}
+
+/** full-width border line: "+" plus 87 fill characters plus "+". */
+function smiborder(fill: string): string {
+  return `+${fill.repeat(smiwidth - 2)}+`;
+}
+
+/** full-width content line padded to the 89-char table width. */
+function smifull(content: string): string {
+  return `|${pad(content, smiwidth - 2)}|`;
+}
+
+/** three-column separator: pipes at fixed offsets 1, 42 and 67. */
+function smisep(fill: string): string {
+  return `|${fill.repeat(smicolumns[0])}+${fill.repeat(smicolumns[1])}+${fill.repeat(smicolumns[2])}|`;
+}
+
+/** three-column data row within the 89-char width. */
+function smirow(left: string, mid: string, right: string): string {
+  return `|${pad(left, smicolumns[0])}|${pad(mid, smicolumns[1])}|${pad(right, smicolumns[2])}|`;
+}
+
+/** process table content line within the 75-char width. */
+function procline(content: string): string {
+  return `|${pad(content, procwidth - 2)}|`;
+}
+
+/**
+ * renders the complete virtual nvidia-smi adapter report; the summary
+ * table is exactly 89 characters wide and the header pins driver
+ * 575.57.08 and cuda 12.9 exactly as the native smiadapterbuilder does.
+ * when a mig profile is active the memory column reflects the slice size
+ * and a mig line joins the table.
+ *
+ * @param {string} gpu gpu id or name present in gpudata.
+ * @param {string} [migprofile='off'] one of 1g.24gb, 2g.48gb, 4g.96gb or off.
+ * @returns {string} the full report text.
+ */
+export function nvidiaSmiTable(gpu: string, migprofile: string = 'off'): string {
+  const spec = getgpu(gpu);
+  if (spec === undefined) {
+    throw new Error(
+      `unknown gpu "${gpu}"; known gpus: ${gpudata.map((entry) => entry.id).join(', ')}`,
+    );
+  }
+  const mig = getmig(migprofile);
+  const vrammib = mig !== null ? mig.slicegb * 1024 : spec.smireportedmib;
+  const memusedmib = rnd(0, 24);
+  const util = rnd(0, 3);
+  const temperature = rnd(38, 47);
+  const fanspeed = rnd(24, 38);
+  const powerw = Math.max(10, Math.round(spec.tdpwatts * 0.04));
+  const head = ` NVIDIA-SMI ${smidriver} ${' '.repeat(13)}Driver Version: ${smidriver}${' '.repeat(6)}CUDA Version: ${cudaversion}`;
+  const lines = [
+    formatstamp(new Date()),
+    smiborder('-'),
+    smifull(head),
+    smisep('-'),
+    smirow(
+      `${pad(' GPU  Name', 27)}${pad('Persistence-M', 13)}`,
+      pad(' Bus-Id          Disp.A', 24),
+      ` ${padstart('Volatile Uncorr. ECC', 20)}`,
+    ),
+    smirow(
+      pad(' Fan  Temp   Perf      Pwr:Usage/Cap', 40),
+      pad('         Memory-Usage', 24),
+      ` ${padstart('GPU-Util  Compute M.', 20)}`,
+    ),
+    smisep('='),
+    smirow(
+      `${pad(`   0  ${spec.name}`, 36)}${pad('Off', 4)}`,
+      pad('   00000000:01:00.0  Off', 24),
+      ` ${padstart('N/A', 20)}`,
+    ),
+    smirow(
+      pad(` ${fanspeed}%   ${temperature}C  P0    ${powerw}W / ${spec.tdpwatts}W`, 40),
+      padstart(`${memusedmib}MiB / ${vrammib}MiB`, 24),
+      `${padstart(`${util}%`, 10)}${pad('  Default', 11)}`,
+    ),
+  ];
+  if (mig !== null) {
+    lines.push(
+      smifull(
+        ` MIG: enabled, profile ${mig.id}, ${mig.maxinstances} instance(s) of ${mig.slicegb} GB`,
+      ),
+    );
+  }
+  lines.push(
+    smirow('', '', ''),
+    smiborder('-'),
+    '',
+    'Processes:',
+    procline(
+      `${pad(' GPU  GI  CI', 20)}${pad('PID', 7)}${pad('Type', 8)}${pad('Process name', 27)}${pad('GPU Memory', 11)}`,
+    ),
+    procline('='.repeat(procwidth - 2)),
+  );
+  if (mig !== null) {
+    for (let instance = 0; instance < mig.maxinstances; instance += 1) {
+      lines.push(
+        procline(
+          `${pad(` 0    ${instance}    0`, 20)}${pad(String(1200 + instance), 7)}${pad('MIG', 8)}${pad('mig-worker', 27)}${pad(`${rnd(0, 512)}MiB`, 11)}`,
+        ),
+      );
+    }
+  } else {
+    lines.push(procline('  No running processes found'));
+  }
+  lines.push(`+${'-'.repeat(procwidth - 2)}+`);
+  return lines.join('\n');
+}
+
+/**
+ * renders the nvidia-smi -l device listing; with an active mig profile
+ * the mig device lines follow the parent gpu line.
+ *
+ * @param {string} gpu gpu id or name present in gpudata.
+ * @param {string} [migprofile='off'] mig profile id or off.
+ * @returns {string} the -l listing.
+ */
+export function nvidiaSmiList(gpu: string, migprofile: string = 'off'): string {
+  const spec = getgpu(gpu);
+  if (spec === undefined) {
+    throw new Error(`unknown gpu "${gpu}"`);
+  }
+  const mig = getmig(migprofile);
+  const lines = [`GPU 0: ${spec.name} (UUID: ${token('GPU-')})`];
+  if (mig !== null) {
+    for (let instance = 0; instance < mig.maxinstances; instance += 1) {
+      lines.push(`  MIG ${mig.id}     Device  ${instance}: (UUID: ${token('MIG-')})`);
+    }
+  }
+  return lines.join('\n');
+}
+
+/* ------------------------------------------------------------------ */
+/* context: mesa stack summaries                                       */
+/* ------------------------------------------------------------------ */
+
+/** the software rendering stack pinned from primary sources. */
+const mesastack = {
+  mesa: '26.2.1', llvm: '22.1.8', gl: '4.6', gles: '3.2', vulkan: '1.4',
+  opencl: '3.1',
+};
+
+/**
+ * renders the clinfo summary for the rusticl platform on llvmpipe: opencl
+ * 3.1 (same-day spec support in mesa 26.2), fp16 default since 25.2 and
+ * fp64 through rusticl_features.
+ *
+ * @param {number} [vcpus=8] vcpu count reported as compute units.
+ * @returns {string} the clinfo summary block.
+ */
+export function clinfoSummary(vcpus: number = 8): string {
+  const units = Math.max(1, Math.min(vcpus, 32));
+  return [
+    'Number of platforms                               1',
+    '  Platform Name                                   rusticl',
+    '  Platform Vendor                                 Mesa/X.org',
+    '  Platform Version                                OpenCL 3.1',
+    '  Platform Profile                                FULL_PROFILE',
+    '  Platform Extensions                             cl_khr_fp64 cl_khr_fp16 cl_khr_icd cl_khr_command_buffer',
+    'Number of devices                                 1',
+    '  Device Name                                     llvmpipe (CPU)',
+    '  Device Vendor                                   Mesa/X.org',
+    '  Device Vendor ID                                0x10005 (Mesa)',
+    '  Device Version                                  OpenCL 3.1',
+    '  Device Type                                     GPU',
+    `  Max compute units                               ${units}`,
+    '  Max work item dimensions                        3',
+    '  Max work group size                             1024',
+    '  Preferred vector width char/int/float           16/16/16',
+    '  Max clock frequency                             3700MHz',
+    '  Address bits                                    64',
+    '  Half precision support                          cl_khr_fp16 (default since mesa 25.2)',
+    '  Double precision support                        cl_khr_fp64 (rusticl_features=fp64)',
+    '  Device available                                Yes',
+    '  Compiler available                              Yes',
+    '  SPIR versions                                   1.2',
+  ].join('\n');
+}
+
+/**
+ * renders the vulkaninfo --summary block for lavapipe: vulkan 1.4 surface
+ * since mesa 25.1, khronos-conformant on the vulkan 1.3 cts, selected
+ * through vk_driver_files (vk_icd_filenames is deprecated).
+ *
+ * @returns {string} the vulkan summary block.
+ */
+export function vulkanSummary(): string {
+  return [
+    '==========',
+    'VULKANINFO',
+    '==========',
+    '',
+    'Instance Extensions: count=10',
+    'VK_KHR_surface                            : extension revision 25',
+    'VK_KHR_get_physical_device_properties2    : extension revision 2',
+    'VK_EXT_headless_surface                   : extension revision 1',
+    '',
+    'API Version: 1.4.313',
+    '',
+    'GPU0:',
+    '    apiVersion        = 1.4.313',
+    '    driverVersion     = 26.2.1',
+    '    vendorID          = 0x10005',
+    '    deviceID          = 0x0000',
+    '    deviceType        = CPU',
+    '    deviceName        = llvmpipe (CPU (x86_64))',
+    '    driverName        = mesa_llvmpipe',
+    `    driverInfo        = Mesa ${mesastack.mesa} (LLVM ${mesastack.llvm})`,
+    '    conformantVersion = 1.3.0.0',
+    '',
+    'Device Extensions: count=204',
+    'VK_KHR_8bit_storage VK_KHR_16bit_storage VK_KHR_shader_float16_int8',
+    'VK_KHR_spirv_1_4 VK_KHR_storage_buffer_storage_class',
+  ].join('\n');
+}
+
+/**
+ * renders the glxinfo header block for llvmpipe: opengl 4.6 core profile
+ * 100% (161/161 extensions tracked by mesamatrix) and the llvmpipe
+ * renderer string with the llvm version.
+ *
+ * @returns {string} the glxinfo block.
+ */
+export function glxinfoSummary(): string {
+  return [
+    'name of display: :0',
+    'display: :0  screen: 0',
+    'direct rendering: Yes',
+    'server glx vendor string: SGI',
+    'client glx vendor string: Mesa Project and SGI',
+    'OpenGL vendor string: Mesa',
+    `OpenGL renderer string: llvmpipe (LLVM ${mesastack.llvm}, 256 bits)`,
+    `OpenGL core profile version string: ${mesastack.gl} (Core Profile) Mesa ${mesastack.mesa}`,
+    'OpenGL core profile shading language version string: 4.60',
+    '',
+    'OpenGL core profile context flags: (none)',
+    'OpenGL core profile profile mask: core profile',
+    '',
+    'OpenGL core profile extensions: 161',
+    `OpenGL version string: ${mesastack.gl} (Compatibility Profile) Mesa ${mesastack.mesa}`,
+    'OpenGL shading language version string: 4.60',
+    'OpenGL context flags: (none)',
+    '',
+    'Extended renderer info (GLX_MESA_query_renderer):',
+    '    Vendor: Mesa/X.org (0x1002)',
+    `    Device: llvmpipe (LLVM ${mesastack.llvm}, 256 bits) (0xffffffff)`,
+    `    Version: ${mesastack.mesa}`,
+    '    Accelerated: no',
+    '    Video memory: 32768MB',
+    '    Unified memory: yes',
+    '    Texture from pixmap: yes',
+  ].join('\n');
+}
+
+/**
+ * assembles the validated mesa environment exactly as mesaenvbuilder +
+ * renderenv('opengl') do: llvmpipe forced, gl 4.6, glsl 460, vector width
+ * 512 to exercise the avx-512 paths, lavapipe through vk_driver_files and
+ * rusticl opencl 3.1 with the fp64 feature.
+ *
+ * @param {number} [vcpus=8] vcpu count used for lp_num_threads (0 uses
+ *   every core up to the lp_max_threads=32 ceiling).
+ * @returns {Record<string, string>} the environment record.
+ */
+export function mesaenv(vcpus: number = 8): Record<string, string> {
+  const threads = vcpus <= 0 ? 0 : Math.min(vcpus, 32);
+  return {
+    LIBGL_ALWAYS_SOFTWARE: 'true',
+    GALLIUM_DRIVER: 'llvmpipe',
+    MESA_GL_VERSION_OVERRIDE: mesastack.gl,
+    MESA_GLSL_VERSION_OVERRIDE: '460',
+    MESA_GLES_VERSION_OVERRIDE: mesastack.gles,
+    MESA_VK_VERSION_OVERRIDE: mesastack.vulkan,
+    LP_NUM_THREADS: String(threads),
+    LP_NATIVE_VECTOR_WIDTH: '512',
+    MESA_NO_ERROR: '1',
+    VK_DRIVER_FILES: '/usr/share/vulkan/icd.d/lvp_icd.x86_64.json',
+    MESA_VK_WSI_HEADLESS_SWAPCHAIN: '1',
+    RUSTICL_ENABLE: 'llvmpipe',
+    RUSTICL_DEVICE_TYPE: 'gpu',
+    RUSTICL_CL_VERSION: mesastack.opencl,
+    RUSTICL_FEATURES: 'fp64',
+  };
+}
+
+/* ------------------------------------------------------------------ */
+/* context: bootsequence — dmesg-style boot lines                      */
+/* ------------------------------------------------------------------ */
+
+/**
+ * renders the firecracker-style boot log for a sandbox: kernel banner,
+ * 125 ms microvm bring-up, memory sizing, vcpu online lines, the mesa
+ * software stack bring-up and the virtual gpu identity binding. every
+ * line carries the kernel [    0.000000] timestamp style.
+ *
+ * @param {string} model cpu model name present in cpudata.
+ * @param {number} vcpus logical processor count.
+ * @param {number} [ramgb=32] guest ram in gb.
+ * @param {string} [gpu='rtx5090'] gpu id present in gpudata.
+ * @param {number} [quota=16777216] persistent workspace quota in bytes.
+ * @returns {string[]} ordered dmesg lines.
+ */
+export function bootSequence(
+  model: string,
+  vcpus: number,
+  ramgb: number = 32,
+  gpu: string = 'rtx5090',
+  quota: number = 16 * 1024 * 1024,
+): string[] {
+  const spec = getcpu(model) ?? cpudata[0];
+  const gpuspec = getgpu(gpu) ?? gpudata[0];
+  const topology = solvetopology(spec, vcpus);
+  const arch = spec.arch === 'arm64' ? 'aarch64' : 'x86_64';
+  const stamp = (seconds: number): string => `[${seconds.toFixed(6).padStart(12)}]`;
+  const onlinetime = 0.039 + 0.00042 * topology.vcpus;
+  return [
+    `${stamp(0)} Linux version 6.12.0-saddle (root@saddle) (gcc 15.1.0, ld 2.44) #1 SMP PREEMPT_DYNAMIC ${arch}`,
+    `${stamp(0.000049)} Command line: root=/dev/vda rw console=ttyS0 reboot=k panic=1 pci=off i8042.noaux i8042.nomux i8042.nopnp i8042.dumbkbd`,
+    `${stamp(0.004201)} BIOS-provided physical RAM map (virtio-mem + memfd hugetlb backend)`,
+    `${stamp(0.008913)} Memory: ${pagealign(ramgb * 1024 * 1024 - 131072)}K available (${ramgb} GB guest plan, 4 kB pages)`,
+    `${stamp(0.012451)} firecracker: microvm vm_state=Running boot_time=125ms vmm=fc v1.16.1`,
+    `${stamp(0.02133)} virtio_blk virtio1: [vda] 8589934592 512-byte logical blocks (8.6 GB)`,
+    `${stamp(0.038774)} smpboot: ${topology.coresonline} cores, ${topology.vcpus} threads online (${spec.model})`,
+    `${stamp(0.039001)} cpu cpu0: ${spec.microarch}, boost ${spec.boostclockmhz} MHz, l3 ${spec.l3mb} MB`,
+    `${stamp(onlinetime)} smp: brought up ${topology.vcpus} cpus, cpu mask 0-${topology.vcpus - 1}`,
+    `${stamp(onlinetime + 0.0148)} NUMA: ${Math.max(1, Math.round(topology.vcpus / 64))} node(s), interleave enabled`,
+    `${stamp(onlinetime + 0.0283)} hugepage: 2048 kB pages reserved, thp=always`,
+    `${stamp(onlinetime + 0.0422)} docker: engine 29.7.2 ready, containerd 2.3.1, memswap=-1 shm=2g`,
+    `${stamp(onlinetime + 0.0551)} qemu-system-${arch}: bridge 11.1.0 attached (qmp unix:/run/saddle/qemu-0.sock)`,
+    `${stamp(onlinetime + 0.0784)} mesa ${mesastack.mesa}: llvmpipe rasterizer, lp_num_threads=${Math.min(topology.vcpus, 32)}, lp_max_threads=32`,
+    `${stamp(onlinetime + 0.0789)} llvmpipe: avx-512 vector width 512 selected by gallivm (llvm ${mesastack.llvm})`,
+    `${stamp(onlinetime + 0.0812)} lavapipe: vulkan ${mesastack.vulkan}, icd lvp_icd.${arch}.json, wsi headless`,
+    `${stamp(onlinetime + 0.0837)} rusticl: opencl ${mesastack.opencl} on llvmpipe, features fp64 (fp16 default since 25.2)`,
+    `${stamp(onlinetime + 0.091)} virtualgpu: identity ${gpuspec.name} [${gpuspec.pcivendor}:${gpuspec.pcidevice}] ${gpuspec.memtype} ${gpuspec.vrammib / 1024} GB`,
+    `${stamp(onlinetime + 0.0922)} nvml shim: FAKE_MODEL="${gpuspec.name}" FAKE_VRAM=${gpuspec.smireportedmib} (fake-nvidia-smi adapter ready)`,
+    `${stamp(onlinetime + 0.1045)} saddle: virtual hardware engine v2.0.127, sandbox created -> running`,
+    `${stamp(onlinetime + 0.1047)} saddle: persistent workspace: ${humanbytes(quota)} quota, data stays with the sandbox id`,
+    `${stamp(onlinetime + 0.1046)} Freeing unused kernel image memory`,
+  ];
+}
+
+/* ------------------------------------------------------------------ */
+/* context: sandboxstate and dispatcher                                */
+/* ------------------------------------------------------------------ */
+
+/**
+ * creates the state object shared by the browser terminal and the api
+ * exec endpoint: resolved specs, a stable hostname, the boot timestamp and
+ * a memoized meminfo snapshot so memory reports stay consistent within
+ * one sandbox session.
+ *
+ * @param {{model: string, vcpus: number, ramgb: number, gpu: string,
+ *   mig?: string, id?: string}} spec the sandbox specification.
+ * @returns {object} the sandbox state consumed by dispatch.
+ */
+export function createSandboxState(spec: SandboxSpec): SandboxState {
+  // the reviewed catalog is the only source of processor identity; ram
+  // accepts any user chosen plan up to the 18 tb virtual ceiling.
+  const cpu = getcpu(spec.model) ?? cpudata[0];
+  const gpu = getgpu(spec.gpu) ?? gpudata[0];
+  const topology = solvetopology(cpu, spec.vcpus ?? 8);
+  const ramgb = Math.max(1, Math.min(Math.round(spec.ramgb ?? 32), 18432));
+  const id = spec.id ?? token('sb-');
+  return {
+    model: cpu.model,
+    cpuspec: cpu,
+    gpuspec: gpu,
+    vcpus: topology.vcpus,
+    ramgb,
+    gpu: gpu.id,
+    mig: getmig(spec.mig) === null ? 'off' : (spec.mig as string),
+    id,
+    hostname: `saddle-${id.replace(/^sb-/, '').slice(0, 8)}`,
+    boottime: Date.now(),
+    kernel: cpu.arch === 'arm64' ? '6.12.0-saddle-aarch64' : '6.12.0-saddle',
+    memsnapshot: meminfo(ramgb, { vcpus: topology.vcpus }),
+    history: [],
+    files: new Map(),
+  };
+}
+
+/** the supported command list, reused by help and the terminal. */
+export const commands: string[] = [
+  'help', 'lscpu', 'cat /proc/cpuinfo', 'cat /proc/meminfo', 'free -h',
+  'nvidia-smi', 'nvidia-smi -L', 'clinfo', 'vulkaninfo --summary',
+  'glxinfo', 'uname -a', 'ls /etc/virtual', 'env', 'docker --version',
+  'qemu-system-x86_64 --version', 'uptime', 'whoami', 'neofetch', 'clear',
+  'echo', 'echo <text> > <file>', 'echo <text> >> <file>', 'touch <file>',
+  'cat <file>', 'ls', 'rm <file>', 'df -h', 'stat <file>', 'pwd',
+  'history', 'streaming', 'man <command>',
+];
+
+/** renders the help text with every supported command. */
+function helpText(): string {
+  const rows = [
+    ['help', 'this command list'],
+    ['lscpu', 'virtual processor topology summary'],
+    ['cat /proc/cpuinfo', 'full procfs cpuinfo payload'],
+    ['cat /proc/meminfo', 'full procfs meminfo payload'],
+    ['free -h', 'human readable memory table'],
+    ['nvidia-smi', 'virtual gpu adapter report (89-char table)'],
+    ['nvidia-smi -L', 'virtual gpu device listing'],
+    ['clinfo', 'rusticl opencl 3.1 summary on llvmpipe'],
+    ['vulkaninfo --summary', 'lavapipe vulkan 1.4 summary'],
+    ['glxinfo', 'llvmpipe opengl 4.6 summary'],
+    ['uname -a', 'kernel and architecture line'],
+    ['ls /etc/virtual', 'virtual hardware definition files'],
+    ['env', 'mesa llvmpipe environment variables'],
+    ['docker --version', 'docker engine version'],
+    ['qemu-system-x86_64 --version', 'qemu bridge version'],
+    ['uptime', 'sandbox uptime and load average'],
+    ['whoami', 'current user'],
+    ['neofetch', 'saddle ascii logo and sandbox specs'],
+    ['clear', 'clear the terminal'],
+    ['echo <text>', 'print text'],
+    ['echo <text> > <file>', 'write text to a workspace file'],
+    ['echo <text> >> <file>', 'append text to a workspace file'],
+    ['touch <file>', 'create an empty workspace file'],
+    ['cat <file>', 'print a persistent workspace file'],
+    ['ls', 'list the workspace root with sizes and dates'],
+    ['rm <file>', 'delete one workspace file'],
+    ['df -h', 'workspace quota usage as a filesystem table'],
+    ['stat <file>', 'size and timestamps of one workspace file'],
+    ['pwd', 'print the working directory (always /)'],
+    ['history', 'streaming', 'the last 50 commands of this session'],
+    ['man <command>', 'short manual for one command'],
+  ];
+  return rows.map(([name, about]) => `  ${pad(name, 32)}${about}`).join('\n');
+}
+
+/** renders the neofetch block: the saddle ascii logo beside sandbox specs. */
+function neofetch(state: SandboxState): string {
+  const cpu = state.cpuspec;
+  const gpu = state.gpuspec;
+  const logo = [
+    '      ``-://////:-``          ',
+    '    ./+++++++++++++/-.        ',
+    '   -+++++++++++++++++++-`     ',
+    '  ./+++ saddle sandbox ++/.    ',
+    '  -+++++++++++++++++++++-`    ',
+    '   `-:/+++++++++++++/-.       ',
+    '      .-://////:-.            ',
+    '                              ',
+  ];
+  const uptime = Math.max(1, Math.round((Date.now() - state.boottime) / 1000));
+  const mins = Math.floor(uptime / 60);
+  const hours = Math.floor(mins / 60);
+  const uptimeText = hours > 0 ? `${hours} hour(s), ${mins % 60} min` : `${mins} min`;
+  const total = pagealign(state.ramgb * 1024 * 1024 - 131072);
+  const mig = getmig(state.mig);
+  const info = [
+    `root@${state.hostname}`,
+    '-----------------',
+    'OS: saddle linux (virtual hardware engine v2.0.127)',
+    'Host: firecracker microvm (125 ms boot)',
+    `Kernel: ${state.kernel}`,
+    `Uptime: ${uptimeText}`,
+    'Packages: 412 (dpkg), 8 (snap)',
+    'Shell: bash 5.2.37',
+    `CPU: ${cpu.displayname} (${state.vcpus}) @ ${cpu.boostclockmhz}.00MHz`,
+    `GPU: ${gpu.name} [${gpu.pcivendor}:${gpu.pcidevice}]`,
+    `Memory: ${human(Math.round(total * 0.31))} / ${human(total)}`,
+    `vRAM: ${gpu.memtype} ${gpu.vrammib / 1024} GB${mig !== null ? ` (MIG ${mig.id})` : ''}`,
+    'Renderer: llvmpipe (LLVM 22.1.8) / lavapipe 1.4 / rusticl 3.1',
+  ];
+  const rows = Math.max(logo.length, info.length);
+  const out = [];
+  for (let index = 0; index < rows; index += 1) {
+    out.push(`${(logo[index] ?? '').padEnd(30)}${info[index] ?? ''}`);
+  }
+  return out.join('\n');
+}
+
+/** renders the uptime line with a load average derived from the vcpus. */
+function uptimeLine(state: SandboxState): string {
+  const totalSeconds = Math.max(0, Math.floor((Date.now() - state.boottime) / 1000));
+  const now = new Date();
+  const mins = Math.max(1, Math.round(totalSeconds / 60));
+  const load = (decay: number): string =>
+    (Math.random() * state.vcpus * 0.18 * Math.exp(-decay / 30)).toFixed(2);
+  return ` ${now.toTimeString().slice(0, 8)} up ${mins} min,  1 user,  load average: ${load(1)}, ${load(5)}, ${load(15)}`;
+}
+
+/** renders the env listing: the mesa stack plus the sandbox variables. */
+function envText(state: SandboxState): string {
+  const mig = getmig(state.mig);
+  const entries: Record<string, string> = {
+    ...mesaenv(state.vcpus),
+    FAKE_MODEL: state.gpuspec.name,
+    FAKE_VRAM: String(mig !== null ? mig.slicegb * 1024 : state.gpuspec.smireportedmib),
+    SADDLE_VERSION: '2.0.127',
+    SADDLE_SANDBOX: state.id,
+    SADDLE_STATE: 'running',
+    SADDLE_CPU: state.model,
+    SADDLE_GPU: state.gpu,
+    SADDLE_MIG: state.mig,
+    HOSTNAME: state.hostname,
+    TERM: 'xterm-256color',
+    SHELL: '/bin/bash',
+    USER: 'root',
+    HOME: '/root',
+    PATH: '/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin',
+    LANG: 'C.UTF-8',
+  };
+  return Object.keys(entries)
+    .sort()
+    .map((key) => `${key}=${entries[key]}`)
+    .join('\n');
+}
+
+/* ------------------------------------------------------------------ */
+/* context: virtualfs — the persistent workspace filesystem            */
+/* ------------------------------------------------------------------ */
+
+/** the default workspace quota mirrored from the api contract. */
+const defaultquota = 16 * 1024 * 1024;
+
+/** the per-session history cap shown by the history command. */
+const historycap = 50;
+
+/**
+ * normalizes one workspace path: the working directory is always the
+ * sandbox root, so relative names gain the leading slash, duplicated
+ * slashes collapse, trailing slashes drop and any traversal attempt
+ * ("..") or oversized path is rejected.
+ *
+ * @param {string} input the raw path typed by the user.
+ * @returns {{ok: true, path: string} | {ok: false, error: string}} the verdict.
+ */
+function normalizepath(input: string): { ok: true; path: string } | { ok: false; error: string } {
+  const raw = String(input ?? '').trim();
+  if (raw.length === 0) {
+    return { ok: false, error: 'empty path' };
+  }
+  if (raw.includes('..')) {
+    return { ok: false, error: 'path traversal is not allowed' };
+  }
+  let path = raw.replace(/\/+/, '/');
+  if (!path.startsWith('/')) {
+    path = `/${path}`;
+  }
+  if (path.length > 1 && path.endsWith('/')) {
+    path = path.slice(0, -1);
+  }
+  if (path.length > 128) {
+    return { ok: false, error: 'path is too long (max 128 characters)' };
+  }
+  return { ok: true, path };
+}
+
+/**
+ * builds the fallback filesystem for contexts without callbacks (the
+ * browser terminal): a per-state map that lives exactly as long as the
+ * sandbox session and mirrors the {write, read, list, del} contract.
+ *
+ * @param {object} state a state built by createsandboxstate.
+ * @returns {{write: Function, read: Function, list: Function, del: Function}}
+ *   the in-memory filesystem adapter.
+ */
+function memoryfs(state: SandboxState): SandboxFs {
+  return {
+    write(path, content) {
+      const text = content === null || content === undefined ? '' : String(content);
+      const size = new TextEncoder().encode(text).length;
+      const updatedat = new Date().toISOString();
+      state.files.set(path, { content: text, size, updatedat });
+      return { path, size, updatedat };
+    },
+    read(path) {
+      const entry = state.files.get(path);
+      return entry === undefined ? null : { path, ...entry };
+    },
+    list() {
+      return [...state.files.entries()]
+        .map(([path, entry]) => ({ path, size: entry.size, updatedat: entry.updatedat }))
+        .sort((a, b) => (a.path < b.path ? -1 : 1));
+    },
+    del(path) {
+      return state.files.delete(path);
+    },
+  };
+}
+
+/**
+ * renders one ls row in the long listing style with size and date.
+ *
+ * @param {{path: string, size: number, updatedat: string}} file the file row.
+ * @returns {string} the formatted line.
+ */
+function lsrow(file: { path: string; size: number; updatedat: string }): string {
+  const when = String(file.updatedat ?? '').slice(0, 16).replace('T', ' ');
+  return `-rw-r--r-- 1 root root ${padstart(String(file.size), 9)} ${when} ${file.path}`;
+}
+
+/** the short manual pages served by the man command. */
+const manualpages: Record<string, string | undefined> = {
+  streaming: 'streaming: shows the streaming memory plan - any workload size runs inside a small hot window (mmap layers, evict after last consumer)',
+  quantum: 'quantum: quantum layer summary - simulator, bb84, grover, dna vault, optical planner',
+  tiers: 'tiers: shows the layered virtual memory - l1 ram to l4 buckets, the free pool and the npm-as-disk farm',
+  touch: 'touch <file> - create an empty file in the persistent workspace (or refresh its timestamp)',
+  echo: 'echo <text> - print text; echo <text> > <file> writes and echo <text> >> <file> appends (stored verbatim, no implicit newline)',
+  cat: 'cat <file> - print one persistent workspace file (also /proc/cpuinfo and /proc/meminfo)',
+  ls: 'ls [path] - list the persistent workspace root with sizes and dates; ls /etc/virtual keeps the hardware table',
+  rm: 'rm <file> - delete one persistent workspace file',
+  df: 'df [-h] - workspace quota usage as a filesystem table; the quota is fixed per sandbox id',
+  stat: 'stat <file> - size and timestamps of one persistent workspace file',
+  pwd: 'pwd - print the working directory; the sandbox is always rooted at /',
+  history: 'history - the last 50 commands typed in this session',
+  man: 'man <command> - this short manual',
+};
+
+/**
+ * dispatches one shell command against a sandbox state; the return shape
+ * matches the api exec contract {output, exitCode}. the optional context
+ * carries the persistent filesystem callbacks {write, read, list, del}
+ * bound to the sandbox id by the api host; without a context the same
+ * commands run on the per-session in-memory workspace so the browser
+ * terminal keeps working unchanged.
+ *
+ * @param {string} command the raw command line typed by the user.
+ * @param {object} state a state built by createsandboxstate.
+ * @param {{fs?: {write: Function, read: Function, list: Function,
+ *   del: Function}, quota?: number}} [context] the optional filesystem
+ *   context provided by the api host.
+ * @returns {{output: string, exitCode: number, clear?: boolean}} the result.
+ */
+export function dispatch(
+  command: string,
+  state: SandboxState,
+  context?: DispatchContext,
+): DispatchResult {
+  const raw = String(command ?? '').trim();
+  if (raw.length === 0) {
+    return { output: '', exitCode: 0 };
+  }
+  try {
+    if (!Array.isArray(state.history)) {
+      state.history = [];
+    }
+    state.history.push(raw);
+    if (state.history.length > historycap) {
+      state.history.splice(0, state.history.length - historycap);
+    }
+  } catch {
+    /* history is best effort; a frozen state must not break exec */
+  }
+  const fs = context?.fs ?? memoryfs(state);
+  const argv = raw.split(/\s+/);
+  const head = argv[0];
+  const rest = argv.slice(1).join(' ');
+  try {
+    /* echo is the one command with output redirection: the text is
+     * stored verbatim ("echo a > f" then "echo b >> f" yields "ab").
+     * The split is a linear scan off the last '>' — the lazy regex it
+     * replaces walked every boundary of a space run and the redos gate
+     * refused the polynomial detour: the operator is the last '>' doubled
+     * or single, the filename the single whitespace-free token after it
+     * and the command everything before the operator. */
+    const gt = raw.lastIndexOf('>');
+    let redirect: { command: string; operator: string; file: string } | null = null;
+    if (gt >= 0) {
+      const file = raw.slice(gt + 1).trim();
+      if (file.length > 0 && !/\s/.test(file)) {
+        const doubled = gt > 0 && raw[gt - 1] === '>';
+        redirect = {
+          command: raw.slice(0, doubled ? gt - 1 : gt).trim(),
+          operator: doubled ? '>>' : '>',
+          file,
+        };
+      }
+    }
+    if (redirect !== null) {
+      const commandpart = redirect.command;
+      const redirhead = commandpart.split(/\s+/)[0];
+      if (redirhead !== 'echo') {
+        return {
+          output: `bash: output redirection is only supported for echo (got ${redirhead})`,
+          exitCode: 1,
+        };
+      }
+      const text = commandpart.slice(redirhead.length).trim();
+      const norm = normalizepath(redirect.file);
+      if (!norm.ok) {
+        return { output: `bash: echo: ${redirect.file}: ${norm.error}`, exitCode: 1 };
+      }
+      try {
+        if (redirect.operator === '>>') {
+          const existing = fs.read(norm.path);
+          fs.write(norm.path, `${existing === null ? '' : existing.content}${text}`);
+        } else {
+          fs.write(norm.path, text);
+        }
+        return { output: '', exitCode: 0 };
+      } catch (writeerror) {
+        return {
+          output: `bash: echo: ${writeerror instanceof Error ? writeerror.message : String(writeerror)}`,
+          exitCode: 1,
+        };
+      }
+    }
+    switch (head) {
+      case 'help':
+        return { output: `saddle sandbox commands:\n${helpText()}`, exitCode: 0 };
+      case 'lscpu':
+        return { output: lscpu(state.model, state.vcpus, 1), exitCode: 0 };
+      case 'cat': {
+        if (argv[1] === '/proc/cpuinfo') {
+          return { output: cpuinfo(state.model, state.vcpus), exitCode: 0 };
+        }
+        if (argv[1] === '/proc/meminfo') {
+          return { output: state.memsnapshot, exitCode: 0 };
+        }
+        if (argv[1] === undefined) {
+          return { output: 'cat: missing file operand', exitCode: 1 };
+        }
+        const catnorm = normalizepath(argv[1]);
+        if (!catnorm.ok) {
+          return { output: `cat: ${argv[1]}: ${catnorm.error}`, exitCode: 1 };
+        }
+        const catfile = fs.read(catnorm.path);
+        if (catfile === null) {
+          return {
+            output: `cat: ${argv[1]}: No such file or directory`,
+            exitCode: 1,
+          };
+        }
+        return { output: catfile.content, exitCode: 0 };
+      }
+      case 'free':
+        return { output: freeh(state.memsnapshot), exitCode: 0 };
+      case 'nvidia-smi':
+        if (argv[1] === '-L') {
+          return { output: nvidiaSmiList(state.gpu, state.mig), exitCode: 0 };
+        }
+        return { output: nvidiaSmiTable(state.gpu, state.mig), exitCode: 0 };
+      case 'clinfo':
+        return { output: clinfoSummary(state.vcpus), exitCode: 0 };
+      case 'vulkaninfo':
+        return { output: vulkanSummary(), exitCode: 0 };
+      case 'glxinfo':
+        return { output: glxinfoSummary(), exitCode: 0 };
+      case 'uname':
+        return {
+          output: `Linux ${state.hostname} ${state.kernel} #1 SMP PREEMPT_DYNAMIC ${state.cpuspec.arch === 'arm64' ? 'aarch64' : 'x86_64'} GNU/Linux`,
+          exitCode: 0,
+        };
+      case 'ls': {
+        const target = argv[1] ?? '/';
+        if (target === '/etc/virtual') {
+          return {
+            output: [
+              'boards.json    cores.json    gpus.json',
+              'processors.json    virtualhardware.json    vm.config.json',
+              'cpuinfo    meminfo    lscpu    nvidia-smi',
+            ].join('\n'),
+            exitCode: 0,
+          };
+        }
+        const lsnorm = normalizepath(target);
+        if (!lsnorm.ok) {
+          return { output: `ls: ${target}: ${lsnorm.error}`, exitCode: 2 };
+        }
+        const rows = fs.list().filter(
+          (entry) => lsnorm.path === '/' || entry.path === lsnorm.path,
+        );
+        if (rows.length === 0) {
+          if (lsnorm.path !== '/') {
+            return {
+              output: `ls: cannot access '${target}': No such file or directory`,
+              exitCode: 2,
+            };
+          }
+          return { output: '', exitCode: 0 };
+        }
+        const blocks = Math.max(1, Math.ceil(rows.reduce((sum, row) => sum + row.size, 0) / 1024));
+        return {
+          output: [`total ${blocks}`, ...rows.map(lsrow)].join('\n'),
+          exitCode: 0,
+        };
+      }
+      case 'env':
+        return { output: envText(state), exitCode: 0 };
+      case 'docker':
+        return { output: 'Docker version 29.7.2, build 5ea4c1f', exitCode: 0 };
+      case 'qemu-system-x86_64':
+        return {
+          output: [
+            'QEMU emulator version 11.1.0 (saddle bridge)',
+            'Copyright (c) 2003-2026 Fabrice Bellard and the QEMU Project developers',
+          ].join('\n'),
+          exitCode: 0,
+        };
+      case 'uptime':
+        return { output: uptimeLine(state), exitCode: 0 };
+      case 'whoami':
+        return { output: 'root', exitCode: 0 };
+      case 'neofetch':
+        return { output: neofetch(state), exitCode: 0 };
+      case 'echo':
+        return { output: rest, exitCode: 0 };
+      case 'touch': {
+        if (argv[1] === undefined) {
+          return { output: 'touch: missing file operand', exitCode: 1 };
+        }
+        const touchnorm = normalizepath(argv[1]);
+        if (!touchnorm.ok) {
+          return { output: `touch: ${argv[1]}: ${touchnorm.error}`, exitCode: 1 };
+        }
+        try {
+          const existing = fs.read(touchnorm.path);
+          fs.write(touchnorm.path, existing === null ? '' : existing.content);
+          return { output: '', exitCode: 0 };
+        } catch (toucherror) {
+          return {
+            output: `touch: ${toucherror instanceof Error ? toucherror.message : String(toucherror)}`,
+            exitCode: 1,
+          };
+        }
+      }
+      case 'rm': {
+        if (argv[1] === undefined) {
+          return { output: 'rm: missing operand', exitCode: 1 };
+        }
+        const rmnorm = normalizepath(argv[1]);
+        if (!rmnorm.ok) {
+          return { output: `rm: ${argv[1]}: ${rmnorm.error}`, exitCode: 1 };
+        }
+        try {
+          const removed = fs.del(rmnorm.path);
+          if (!removed) {
+            return {
+              output: `rm: cannot remove '${argv[1]}': No such file or directory`,
+              exitCode: 1,
+            };
+          }
+          return { output: '', exitCode: 0 };
+        } catch (rmerror) {
+          return {
+            output: `rm: ${rmerror instanceof Error ? rmerror.message : String(rmerror)}`,
+            exitCode: 1,
+          };
+        }
+      }
+      case 'quantum':
+        return { output: quantumdemo(), exitCode: 0 };
+      case 'tiers':
+        return { output: tiersdemo(), exitCode: 0 };
+      case 'streaming':
+        return { output: streamingdemo(), exitCode: 0 };
+      case 'df': {
+        const rows = fs.list();
+        const used = rows.reduce((sum, row) => sum + row.size, 0);
+        const quota = Number(context?.quota ?? defaultquota);
+        const avail = Math.max(0, quota - used);
+        const percent = quota > 0 ? Math.min(100, Math.floor((used / quota) * 100)) : 0;
+        const col = (text: string, width: number): string => padstart(String(text), width);
+        return {
+          output: [
+            `Filesystem ${col('Size', 10)}${col('Used', 10)}${col('Avail', 10)}${col('Use%', 6)} Mounted on`,
+            `${pad(state.id, 11)}${col(humanbytes(quota), 10)}${col(humanbytes(used), 10)}${col(humanbytes(avail), 10)}${col(`${percent}%`, 6)} /`,
+          ].join('\n'),
+          exitCode: 0,
+        };
+      }
+      case 'stat': {
+        if (argv[1] === undefined) {
+          return { output: 'stat: missing operand', exitCode: 1 };
+        }
+        const statnorm = normalizepath(argv[1]);
+        if (!statnorm.ok) {
+          return { output: `stat: ${argv[1]}: ${statnorm.error}`, exitCode: 1 };
+        }
+        const file = fs.read(statnorm.path);
+        if (file === null) {
+          return {
+            output: `stat: cannot stat '${argv[1]}': No such file or directory`,
+            exitCode: 1,
+          };
+        }
+        return {
+          output: [
+            `  File: ${file.path ?? statnorm.path}`,
+            `  Size: ${padstart(String(file.size), 10)}\tBlocks: ${padstart(String(Math.ceil(file.size / 512)), 6)}          IO Block: 4096   regular file`,
+            `Device: saddle/virtual\tInode: ${padstart(String(state.files instanceof Map ? state.files.size + 1 : 1), 12)}   Links: 1`,
+            `Modify: ${file.updatedat}`,
+          ].join('\n'),
+          exitCode: 0,
+        };
+      }
+      case 'pwd':
+        return { output: '/', exitCode: 0 };
+      case 'history': {
+        const lines = (Array.isArray(state.history) ? state.history : [])
+          .map((entry, index) => `${padstart(String(index + 1), 5)}  ${entry}`);
+        return { output: lines.join('\n'), exitCode: 0 };
+      }
+      case 'man': {
+        const topic = argv[1];
+        if (topic === undefined) {
+          return { output: 'What manual page do you want?', exitCode: 1 };
+        }
+        const page = manualpages[topic];
+        if (page === undefined) {
+          return { output: `man: no manual for ${topic} (try: ${Object.keys(manualpages).join(', ')})`, exitCode: 1 };
+        }
+        return { output: `${topic.toUpperCase()}(1)\n\n  ${page}`, exitCode: 0 };
+      }
+      case 'clear':
+        return { output: '', exitCode: 0, clear: true };
+      default:
+        return {
+          output: `bash: ${head}: command not found (try "help")`,
+          exitCode: 127,
+        };
+    }
+  } catch (error) {
+    return {
+      output: `bash: ${head}: engine error: ${error instanceof Error ? error.message : String(error)}`,
+      exitCode: 1,
+    };
+  }
+}
+
+/**
+ * renders the streaming plan for a workload larger than any host: the
+ * demo the terminal shows for "how does a 1.5 tb model run here" - layers
+ * stream through a fixed window, the workload size is unbounded.
+ * @param {number} totalbytes workload size in bytes.
+ * @param {number} windowbytes hot-set budget in bytes.
+ * @returns {string} the plan summary lines.
+ */
+
+/**
+ * renders the layered virtual memory architecture: everything is vram and
+ * the only physical layer is the free pool (github, npm cdn and friends -
+ * the saddle storage doctrine applied to this engine).
+ * @returns {string} the tier summary lines.
+ */
+
+/**
+ * renders the quantum layer summary: a classical statevector simulator
+ * (1-20 qubits), the bb84/e91 key exchange, grover search, dna and 5d
+ * optical storage planners - every "quantum" capability is software.
+ * @returns {string} the quantum summary lines.
+ */
+export function quantumdemo(): string {
+  return [
+    'saddle quantum layer (100 percent classical simulation)',
+    '  simulator   statevector, float64 interleaved re/im, 1-20 qubits',
+    '  gates       h x y z s t rx ry rz cnot cz toffoli swap',
+    '  algorithms  bellstate, ghz, grover2 (provable), grover3, deutsch, teleport',
+    '  protocols   bb84 (1984) with intercept-resend detection, e91 (1991) + chsh',
+    '  randomness  quantum-inspired (csprng) with honest anu qrng fallback note',
+    '  storage     dna vault (goldman 2013, 215 pb/g, 4 strands, roundtrip proven)',
+    '              5d quartz planner (360 tb/disc, 13.8 billion years at room)',
+    '              qram bucket-brigade model (giovannetti prl 2008)',
+    '  engine: import { quantumsim, runbb84, dnavaultencode } from ./quantum',
+  ].join('\n');
+}
+
+export function tiersdemo(): string {
+  const ladder = ['ram ~100ns', 'zram ~500ns', 'tmpfs ~1us', 'mmap ~5us', 'sqlite ~10us', 'r2 ~50us'];
+  return [
+    'saddle tiered virtual memory (everything is vram)',
+    '  l1 ram      working set, ephemeral            ~100 ns',
+    '  l2 vram     compute-bound identity layer       spoofed',
+    '  l3 storage  repos as ram (sqlite kv, lru)     ~10 us',
+    '  l4 buckets  hf 10tb + kaggle 20tb + terabox   ~50 us',
+    '  physical    github artifacts + ghcr + npm cdn (the only disks)',
+    `  ladder      ${ladder.join(' | ')}`,
+    '  autoscale   <64mb memfs / <1gb mmap / larger sqlite+r2',
+    '  pool        >33 tb free across accounts (see tiers.ts FREEPOOL)',
+    '  npm-as-disk 200 mb chunks as .bin.js packages on the cdn farm',
+    '  vdr         64-bit bigint addressing up to 9.22 eb',
+    '  engine: import { creatiersengine } from the package (./tiers)',
+  ].join('\n');
+}
+
+export function streamingdemo(
+  totalbytes: number = 1649267441664,
+  windowbytes: number = 4 * 1024 * 1024 * 1024,
+): string {
+  const layerbytes = 512 * 1024 * 1024;
+  const count = Math.ceil(totalbytes / layerbytes);
+  const batches = Math.ceil(count / Math.max(1, Math.floor(windowbytes / layerbytes)));
+  const fmt = (b: number): string =>
+    (b >= 1024 ** 4 ? (b / 1024 ** 4).toFixed(2) + ' TB' : (b / 1024 ** 3).toFixed(1) + ' GB');
+  return [
+    'saddle streaming memory plan',
+    `  workload:  ${fmt(totalbytes)} decomposed into ${count} layers of ${layerbytes / 1024 ** 2} MiB`,
+    `  window:    ${fmt(windowbytes)} hot-set budget (peak resident)`,
+    `  batches:   ${batches} load/run/evict passes over the weights`,
+    '  technique: mmap + page cache streams each layer on demand; eviction',
+    '             after the last consumer keeps the resident set inside the',
+    '             window - the workload size is unbounded, only the window',
+    '             is fixed. this is how engines run models larger than ram.',
+  ].join('\n');
+}
+
+/* ------------------------------------------------------------------ */
+/* lifecycle: the cold/warm/hot sandbox state machine (wave 3)         */
+/* ------------------------------------------------------------------ */
+/**
+ * the sandbox lifecycle state machine of the family, distilled from the
+ * foundry herd (wave 3, the engine ownership law: the foundry page model
+ * re-implemented the machine as a local twin; the machine answers from
+ * the saddle owner from this day on and the apps import it through the
+ * published library specifier). the ladder mirrors the boot classes the
+ * modality registry answers (hot, warm, cold) and the warm pool the
+ * orchestrator keeps: cold is built and not booted, warm is booted and
+ * keeping its working set, hot is executing work. zero logic change to
+ * the engine lanes above - the section is additive and imports nothing,
+ * so the browser-pure contract of this module stands.
+ */
+
+/** the three states of the sandbox lifecycle machine. */
+export type SandboxLifecycleState = 'cold' | 'warm' | 'hot';
+
+/** the state ladder in machine order. */
+export const SANDBOX_LIFECYCLE_STATES: readonly SandboxLifecycleState[] = ['cold', 'warm', 'hot'];
+
+/** the allowed transitions of the machine: cold boots to warm, warm
+ * executes to hot, and both ride the cooling paths back. a cold sandbox
+ * never executes; a hot one is already executing. */
+const LIFECYCLE_TRANSITIONS: Readonly<Record<SandboxLifecycleState, readonly SandboxLifecycleState[]>> = {
+  cold: ['warm'],
+  warm: ['hot', 'cold'],
+  hot: ['warm', 'cold'],
+};
+
+/** answers whether the machine allows one transition. */
+export function canTransition(from: SandboxLifecycleState, to: SandboxLifecycleState): boolean {
+  return LIFECYCLE_TRANSITIONS[from].includes(to);
+}
+
+/** the refusal the machine answers when a transition is not allowed -
+ * honest strings, never a silent fallback. */
+export function refusalFor(from: SandboxLifecycleState, to: SandboxLifecycleState): string {
+  if (from === to) return `the sandbox is already ${from}`;
+  if (from === 'cold' && to === 'hot') return 'a cold sandbox cannot execute — warm it first';
+  if (from === 'hot' && to === 'hot') return 'the sandbox is already hot';
+  return `the machine never goes ${from} → ${to} directly`;
+}
+
+/** the action names of the machine, one per transition. */
+export type SandboxLifecycleAction = 'warm' | 'heat' | 'cool' | 'freeze';
+
+/** the guard target each action drives - the machine answers the
+ * transition against this target (the landing state stays the caller's
+ * projection: cool guards the cooling path yet may keep its working set
+ * warm). */
+export const SANDBOX_LIFECYCLE_ACTION_TARGETS: Readonly<Record<SandboxLifecycleAction, SandboxLifecycleState>> = {
+  warm: 'warm',
+  heat: 'hot',
+  cool: 'cold',
+  freeze: 'cold',
+};
+
+/* ===== block: sandboxenvprofile ===== */
+/**
+ * sandboxenvprofile.ts — the configuration adapter of the sandbox spec
+ * plane.
+ *
+ * the declarative spec (sandboxprofile.ts) never holds capacities: the
+ * limits table is a parameter. this module is the adapter that turns
+ * configuration into that parameter: it reads the SADDLE_SPEC_LIMITS
+ * json environment variable ({ "bases": { ... } }), merges it over a
+ * documented development bootstrap table (so a partial override stays
+ * safe) and returns the effective limits table. production deployments
+ * can equally hand the database sourced table straight to
+ * resolvesandboxspec and skip this adapter entirely.
+ *
+ * the module is browser-pure: zero dom, zero node builtins; it imports
+ * only the vocabulary and types of sandboxprofile.ts. the bootstrap table
+ * is a documented convenience, never a product rule — every field it
+ * carries is overridable.
+ */
+
+
+
+
+/** documented development bootstrap table; production overrides it with
+ * the SADDLE_SPEC_LIMITS json (or the database table). fields: maxvcpus/
+ * maxramgb/maxvgpus/maxdiskgb/maxtimeoutseconds/defaultvcpus/
+ * defaultramgb. */
+const bootstraplimits: sandboxspeclimits = {
+  bases: {
+    lite: {
+      maxvcpus: 4,
+      maxramgb: 8,
+      maxvgpus: 0,
+      maxdiskgb: 32,
+      maxtimeoutseconds: 900,
+      defaultvcpus: 2,
+      defaultramgb: 4,
+    },
+    balanced: {
+      maxvcpus: 16,
+      maxramgb: 32,
+      maxvgpus: 1,
+      maxdiskgb: 128,
+      maxtimeoutseconds: 3600,
+      defaultvcpus: 8,
+      defaultramgb: 16,
+    },
+    max: {
+      maxvcpus: 64,
+      maxramgb: 256,
+      maxvgpus: 2,
+      maxdiskgb: 512,
+      maxtimeoutseconds: 14400,
+      defaultvcpus: 32,
+      defaultramgb: 64,
+    },
+  },
+  defaulttimeoutseconds: 900,
+};
+
+/**
+ * reads the limits table from the SADDLE_SPEC_LIMITS environment json;
+ * the bootstrap table fills every base the json does not define, so a
+ * partial override stays safe. broken json falls back to the bootstrap
+ * table (the spec plane never becomes unavailable over config drift).
+ *
+ * @param env the environment record (process.env shaped).
+ * @returns the effective limits table.
+ */
+export function specenvlimits(env: Record<string, string | undefined>): sandboxspeclimits {
+  const raw = env.SADDLE_SPEC_LIMITS;
+  if (raw === undefined || raw.trim() === '') {
+    return bootstraplimits;
+  }
+  try {
+    const parsed = JSON.parse(raw) as { bases?: Record<string, Partial<sandboxbaselimit>> };
+    const bases = { ...bootstraplimits.bases };
+    if (typeof parsed?.bases === 'object' && parsed.bases !== null) {
+      for (const key of SANDBOXBASES) {
+        const override = parsed.bases[key as sandboxbaseid];
+        if (typeof override === 'object' && override !== null) {
+          bases[key as sandboxbaseid] = {
+            ...bootstraplimits.bases[key as sandboxbaseid],
+            ...override,
+          };
+        }
+      }
+    }
+    return { ...bootstraplimits, bases };
+  } catch {
+    return bootstraplimits;
+  }
+}
+
+/* ===== block: sandboxprofile ===== */
+/**
+ * sandboxprofile.ts — the declarative sandbox specification of saddle.
+ *
+ * a saddle sandbox is declared, never assembled: one request names the
+ * base (max, balanced or lite), the guest operating system (android,
+ * grapheneos, linux, omarchy, windows), the cpu architecture (arm64 or
+ * amd64), the runtime form (runtime-node, full-docker, published) and
+ * the optional resource wishes (vcpus, ramgb, vgpu, diskgb, timeout,
+ * networking). this module owns that vocabulary: it validates one
+ * declared spec against a caller supplied limits table and resolves it
+ * into concrete values the engine surface consumes.
+ *
+ * nothing about capacities lives in code: the limits table is a plain
+ * parameter (config, environment or database). the environment adapter
+ * lives in sandboxenvprofile.ts (SADDLE_SPEC_LIMITS json over a
+ * documented bootstrap table).
+ *
+ * the module is browser-pure like sandbox.ts: zero imports, zero dom,
+ * zero node builtins, deterministic verdicts. errors are typed and
+ * traceable — every sandboxspecerror carries a machine readable code,
+ * the offending field, the received value and the expectation missed.
+ *
+ * competitor sources shaping the contract: opensandbox-group/
+ * opensandbox (declared timeoutSeconds bounded by the server side
+ * max_sandbox_timeout_seconds; declared resources on the create
+ * request) and daytonaio/daytona (per-sandbox cpu/memory/disk quota
+ * fields with min=1 validation; gpu admission before create).
+ *
+ * wire points (kept honest): webserver.ts createsandbox validates the
+ * optional base/os/arch/form fields here before building the engine
+ * spec; sandbox.ts createSandboxState stays the hardware identity
+ * layer and receives the resolved vcpus/ramgb untouched.
+ */
+
+/* ------------------------------------------------------------------ */
+/* types: the declared vocabulary                                      */
+/* ------------------------------------------------------------------ */
+
+/** the three runtime bases of the saddle fleet. */
+export type sandboxbaseid = 'max' | 'balanced' | 'lite';
+
+/** the guest operating systems a sandbox can boot. */
+export type sandboxosid = 'android' | 'grapheneos' | 'linux' | 'omarchy' | 'windows';
+
+/** the guest cpu architectures (amd64 == the x86_64 of the engine bank). */
+export type sandboxarchid = 'arm64' | 'amd64';
+
+/** the runtime forms of a published sandbox. */
+export type sandboxformid = 'runtime-node' | 'full-docker' | 'published';
+
+/** the networking modes of a sandbox. */
+export type sandboxnetworkid = 'nat' | 'bridged' | 'isolated';
+
+/** the os family a guest belongs to (android builds on the linux kernel). */
+export type sandboxosfamily = 'android' | 'linux' | 'windows';
+
+/** fixed product vocabulary; only the capacities are configuration. */
+export const SANDBOXBASES: readonly sandboxbaseid[] = ['max', 'balanced', 'lite'];
+export const SANDBOXOSES: readonly sandboxosid[] = [
+  'android',
+  'grapheneos',
+  'linux',
+  'omarchy',
+  'windows',
+];
+export const SANDBOXARCHES: readonly sandboxarchid[] = ['arm64', 'amd64'];
+export const SANDBOXFORMS: readonly sandboxformid[] = ['runtime-node', 'full-docker', 'published'];
+export const SANDBOXNETWORKS: readonly sandboxnetworkid[] = ['nat', 'bridged', 'isolated'];
+
+/* ------------------------------------------------------------------ */
+/* types: the limits table (pure configuration, never hardcoded)       */
+/* ------------------------------------------------------------------ */
+
+/** one base row of the limits table: ceilings and defaults per base. */
+export type sandboxbaselimit = {
+  readonly maxvcpus: number;
+  readonly maxramgb: number;
+  readonly maxvgpus: number;
+  readonly maxdiskgb: number;
+  readonly maxtimeoutseconds: number;
+  readonly defaultvcpus: number;
+  readonly defaultramgb: number;
+};
+
+/** the full limits table handed to the resolver by the caller. */
+export type sandboxspeclimits = {
+  readonly bases: Readonly<Record<sandboxbaseid, sandboxbaselimit>>;
+  readonly defaulttimeoutseconds?: number;
+};
+
+/** the declared request shape (every field is optional or unknown). */
+export type sandboxspecinput = Record<string, unknown>;
+
+/** the resolved spec: concrete values validated against the limits. */
+export type resolvedsandboxspec = {
+  readonly base: sandboxbaseid;
+  readonly os: sandboxosid;
+  readonly arch: sandboxarchid;
+  readonly form: sandboxformid;
+  readonly networking: sandboxnetworkid;
+  readonly family: sandboxosfamily;
+  readonly vcpus: number;
+  readonly ramgb: number;
+  readonly vgpu: boolean;
+  readonly diskgb: number | null;
+  readonly timeoutseconds: number;
+};
+
+/* ------------------------------------------------------------------ */
+/* errors: typed and traceable                                         */
+/* ------------------------------------------------------------------ */
+
+/** every failure code the resolver can produce. */
+export type sandboxspecerrorcode =
+  | 'invalid-spec'
+  | 'missing-base'
+  | 'invalid-base'
+  | 'invalid-os'
+  | 'invalid-arch'
+  | 'invalid-form'
+  | 'invalid-networking'
+  | 'invalid-vcpus'
+  | 'invalid-ramgb'
+  | 'invalid-vgpu'
+  | 'invalid-diskgb'
+  | 'invalid-timeout'
+  | 'timeout-above-limit'
+  | 'vgpu-not-available'
+  | 'unknown-base-limits';
+
+/** the typed spec failure: code, field, received value and expectation. */
+export class sandboxspecerror extends Error {
+  /** machine readable failure code. */
+  readonly code: sandboxspecerrorcode;
+  /** the declared field that failed (or 'spec' for envelope failures). */
+  readonly field: string;
+  /** the received value, json-safe. */
+  readonly value: unknown;
+  /** the expectation the value missed. */
+  readonly expected: string;
+
+  constructor(
+    code: sandboxspecerrorcode,
+    field: string,
+    value: unknown,
+    expected: string,
+    message?: string,
+  ) {
+    super(message ?? `sandbox spec field "${field}" ${expected} (received ${show(value)})`);
+    this.name = 'sandboxspecerror';
+    this.code = code;
+    this.field = field;
+    this.value = value;
+    this.expected = expected;
+  }
+}
+
+/** renders a json-safe preview of any received value for error messages. */
+function show(value: unknown): string {
+  if (typeof value === 'string') {
+    return JSON.stringify(value);
+  }
+  if (typeof value === 'number' || typeof value === 'boolean' || value === null) {
+    return String(value);
+  }
+  if (value === undefined) {
+    return 'undefined';
+  }
+  return Array.isArray(value) ? 'an array' : typeof value;
+}
+
+/** picks the matching member of a fixed vocabulary; undefined otherwise. */
+function memberof<t extends string>(vocabulary: readonly t[], value: unknown): t | undefined {
+  return typeof value === 'string'
+    ? (vocabulary.find((item) => item === value) as t | undefined)
+    : undefined;
+}
+
+/** validates a positive integer wish; null when the shape is wrong. */
+function positiveinteger(value: unknown): number | null {
+  return typeof value === 'number' && Number.isInteger(value) && value >= 1 ? value : null;
+}
+
+/* ------------------------------------------------------------------ */
+/* the resolver                                                        */
+/* ------------------------------------------------------------------ */
+
+/**
+ * validates one declared spec against the limits table and resolves it
+ * into concrete values. the verdict is a discriminated result so
+ * callers surface the typed error without try/catch.
+ *
+ * @param input the declared spec (unknown json is tolerated).
+ * @param limits the limits table (config, env or database sourced).
+ * @returns the resolved spec or the typed, traceable error.
+ */
+export function resolvesandboxspec(
+  input: unknown,
+  limits: sandboxspeclimits,
+): { ok: true; value: resolvedsandboxspec } | { ok: false; error: sandboxspecerror } {
+  if (typeof input !== 'object' || input === null || Array.isArray(input)) {
+    return {
+      ok: false,
+      error: new sandboxspecerror('invalid-spec', 'spec', input, 'a plain object'),
+    };
+  }
+  const declared = input as sandboxspecinput;
+  const base = memberof(SANDBOXBASES, declared.base);
+  if (base === undefined) {
+    return {
+      ok: false,
+      error:
+        declared.base === undefined
+          ? new sandboxspecerror(
+              'missing-base',
+              'base',
+              undefined,
+              `one of ${SANDBOXBASES.join(', ')}`,
+            )
+          : new sandboxspecerror(
+              'invalid-base',
+              'base',
+              declared.base,
+              `one of ${SANDBOXBASES.join(', ')}`,
+            ),
+    };
+  }
+  const row: sandboxbaselimit | undefined = limits.bases[base];
+  if (row === undefined) {
+    return {
+      ok: false,
+      error: new sandboxspecerror(
+        'unknown-base-limits',
+        'base',
+        base,
+        'a base present in the limits table',
+      ),
+    };
+  }
+  // fixed vocabularies: a present but unknown member is a typed error.
+  const words: Array<readonly [string, readonly string[], sandboxspecerrorcode]> = [
+    ['os', SANDBOXOSES, 'invalid-os'],
+    ['arch', SANDBOXARCHES, 'invalid-arch'],
+    ['form', SANDBOXFORMS, 'invalid-form'],
+    ['networking', SANDBOXNETWORKS, 'invalid-networking'],
+  ];
+  for (const [field, vocabulary, code] of words) {
+    if (declared[field] !== undefined && !memberof(vocabulary, declared[field])) {
+      return {
+        ok: false,
+        error: new sandboxspecerror(
+          code,
+          field,
+          declared[field],
+          `one of ${vocabulary.join(', ')}`,
+        ),
+      };
+    }
+  }
+  // resource wishes: positive integers bounded by the base ceiling.
+  const ceilings: Array<readonly [string, sandboxspecerrorcode, number]> = [
+    ['vcpus', 'invalid-vcpus', row.maxvcpus],
+    ['ramgb', 'invalid-ramgb', row.maxramgb],
+    ['diskgb', 'invalid-diskgb', row.maxdiskgb],
+  ];
+  for (const [field, code, ceiling] of ceilings) {
+    if (declared[field] === undefined) {
+      continue;
+    }
+    const wish = positiveinteger(declared[field]);
+    if (wish === null) {
+      return {
+        ok: false,
+        error: new sandboxspecerror(code, field, declared[field], 'a positive integer'),
+      };
+    }
+    if (wish > ceiling) {
+      return {
+        ok: false,
+        error: new sandboxspecerror(
+          code,
+          field,
+          declared[field],
+          `an integer between 1 and ${ceiling} on the ${base} base`,
+        ),
+      };
+    }
+  }
+  let vgpu = false;
+  if (declared.vgpu !== undefined && typeof declared.vgpu !== 'boolean') {
+    return {
+      ok: false,
+      error: new sandboxspecerror('invalid-vgpu', 'vgpu', declared.vgpu, 'a boolean'),
+    };
+  }
+  vgpu = declared.vgpu === true;
+  if (vgpu && row.maxvgpus < 1) {
+    return {
+      ok: false,
+      error: new sandboxspecerror(
+        'vgpu-not-available',
+        'vgpu',
+        true,
+        `a base with vgpu slices (the ${base} base exposes none)`,
+      ),
+    };
+  }
+  const defaulttimeout = limits.defaulttimeoutseconds ?? 900;
+  let timeoutseconds = defaulttimeout;
+  if (declared.timeoutseconds !== undefined) {
+    const wish = positiveinteger(declared.timeoutseconds);
+    if (wish === null) {
+      return {
+        ok: false,
+        error: new sandboxspecerror(
+          'invalid-timeout',
+          'timeoutseconds',
+          declared.timeoutseconds,
+          'a positive integer of seconds',
+        ),
+      };
+    }
+    if (wish > row.maxtimeoutseconds) {
+      return {
+        ok: false,
+        error: new sandboxspecerror(
+          'timeout-above-limit',
+          'timeoutseconds',
+          declared.timeoutseconds,
+          `at most ${row.maxtimeoutseconds} seconds on the ${base} base`,
+        ),
+      };
+    }
+    timeoutseconds = wish;
+  }
+  const os = (memberof(SANDBOXOSES, declared.os) ?? 'linux') as sandboxosid;
+  return {
+    ok: true,
+    value: {
+      base,
+      os,
+      arch: (memberof(SANDBOXARCHES, declared.arch) ?? 'amd64') as sandboxarchid,
+      form: (memberof(SANDBOXFORMS, declared.form) ?? 'runtime-node') as sandboxformid,
+      networking: (memberof(SANDBOXNETWORKS, declared.networking) ?? 'nat') as sandboxnetworkid,
+      family: osfamily(os),
+      vcpus: (declared.vcpus as number | undefined) ?? row.defaultvcpus,
+      ramgb: (declared.ramgb as number | undefined) ?? row.defaultramgb,
+      vgpu,
+      diskgb: (declared.diskgb as number | undefined) ?? null,
+      timeoutseconds,
+    },
+  };
+}
+
+/* ------------------------------------------------------------------ */
+/* helpers and bridges                                                 */
+/* ------------------------------------------------------------------ */
+
+/** maps a guest os onto its kernel family (grapheneos builds on aosp). */
+export function osfamily(os: sandboxosid): sandboxosfamily {
+  if (os === 'android' || os === 'grapheneos') {
+    return 'android';
+  }
+  return os === 'windows' ? 'windows' : 'linux';
+}
+
+/** the structural shape consumed by sandbox.ts createSandboxState. */
+export type sandboxenginespec = {
+  readonly model: string;
+  readonly vcpus: number;
+  readonly ramgb: number;
+  readonly gpu: string;
+  readonly mig: string;
+};
+
+/**
+ * bridges a resolved spec onto the engine surface: vcpus and ramgb come
+ * from the resolved spec, the cpu model and gpu identity stay caller
+ * choices (the reviewed catalog of sandbox.ts remains the only source
+ * of processor and gpu identity).
+ *
+ * @param resolved the resolved spec produced by resolvesandboxspec.
+ * @param options the caller picked engine identities (model, gpu, mig).
+ * @returns the engine spec object.
+ */
+export function enginespecfor(
+  resolved: resolvedsandboxspec,
+  options?: { model?: string; gpu?: string; mig?: string },
+): sandboxenginespec {
+  return {
+    model: options?.model ?? '',
+    vcpus: resolved.vcpus,
+    ramgb: resolved.ramgb,
+    gpu: resolved.vgpu ? (options?.gpu ?? '') : '',
+    mig: options?.mig ?? 'off',
+  };
+}
+
+/* ===== block: sandboxqueue ===== */
+/**
+ * sandboxqueue.ts — the sandbox lifecycle queue of saddle.
+ *
+ * one sandbox walks a single linear machine: creating -> starting ->
+ * running -> stopping -> stopped, with the supervision states cancelled,
+ * failed and timedout closing the paths out. every intermediate state
+ * carries a per-state time budget; the health-check tick reaps entries
+ * whose budget expired (the ttl reaper pattern of webserver.ts and the
+ * pool reaper of opensandbox). transitions are validated by a pure
+ * transition table so both callers and tests exercise the same guard.
+ *
+ * the module is deliberately pure: no timers of its own, no dom, no node
+ * builtins, an injectable clock. hosts drive it — webserver.ts ramps
+ * the api lifecycle with a timeout, the ttl reaper sweeps every minute,
+ * and orchestrator.ts owns the fifteen state vm plane machine; this
+ * module is the queue-level complement those surfaces can delegate to
+ * (wire point documented in the webserver statemachine context: the
+ * api states map as created->creating, expired->timedout,
+ * destroyed->stopped).
+ *
+ * studied competitors shaping the contract: daytonaio/daytona (sandbox
+ * states creating/starting/started/stopping/stopped/error with the
+ * -ing intermediates) and opensandbox-group/opensandbox (Creating ->
+ * Running -> Deleting -> Deleted with 409 on state conflicting
+ * operations and a pool acquisition that fails fast with Retry-After).
+ */
+
+/* ------------------------------------------------------------------ */
+/* types: phases, transitions, entries                                 */
+/* ------------------------------------------------------------------ */
+
+/** every phase of the sandbox lifecycle queue. */
+export type sandboxphase =
+  | 'creating'
+  | 'starting'
+  | 'running'
+  | 'stopping'
+  | 'stopped'
+  | 'cancelled'
+  | 'failed'
+  | 'timedout';
+
+/** phases that end the queue entry (no further transition is legal). */
+export const SANDBOXTERMINALPHASES: readonly sandboxphase[] = [
+  'stopped',
+  'cancelled',
+  'failed',
+  'timedout',
+];
+
+/** the legal transitions of the single lifecycle machine. */
+const sandboxtransitions: Record<sandboxphase, readonly sandboxphase[]> = {
+  creating: ['starting', 'cancelled', 'failed', 'timedout'],
+  starting: ['running', 'cancelled', 'failed', 'timedout'],
+  running: ['stopping', 'cancelled', 'failed', 'timedout'],
+  stopping: ['stopped', 'failed', 'timedout'],
+  stopped: [],
+  cancelled: [],
+  failed: [],
+  timedout: [],
+};
+
+/** per-state time budgets in milliseconds; a state without a budget
+ * never times out (running typically relies on the host ttl instead). */
+export type sandboxphasebudgets = {
+  readonly creating?: number;
+  readonly starting?: number;
+  readonly running?: number;
+  readonly stopping?: number;
+};
+
+/** one queue entry: identity, phase, bookkeeping. */
+export type sandboxqueueentry = {
+  readonly id: string;
+  state: sandboxphase;
+  /** epoch ms of the last phase change. */
+  enteredat: number;
+  /** epoch ms the current phase budget expires; null when unbounded. */
+  deadline: number | null;
+};
+
+/** one recorded lifecycle event (bounded ring, newest last). */
+export type sandboxqueueevent = {
+  readonly id: string;
+  readonly from: sandboxphase;
+  readonly to: sandboxphase;
+  readonly at: number;
+  readonly reason: 'requested' | 'timeout' | 'cancel';
+};
+
+/** failure codes carried by sandboxqueueerror. */
+export type sandboxqueueerrorcode =
+  | 'unknown-sandbox'
+  | 'duplicate-sandbox'
+  | 'invalid-transition'
+  | 'terminal-phase';
+
+/** the typed queue failure, traceable to the entry and both phases. */
+export class sandboxqueueerror extends Error {
+  /** machine readable failure code. */
+  readonly code: sandboxqueueerrorcode;
+  /** the entry the failure belongs to. */
+  readonly id: string;
+  /** the phase the entry was in (or from), when known. */
+  readonly from: sandboxphase | null;
+  /** the requested target phase, when known. */
+  readonly to: sandboxphase | null;
+
+  constructor(
+    code: sandboxqueueerrorcode,
+    id: string,
+    from: sandboxphase | null,
+    to: sandboxphase | null,
+    message?: string,
+  ) {
+    super(
+      message ??
+        `sandbox queue ${code} for ${id}${from === null ? '' : ` (from ${from})`}${to === null ? '' : ` to ${to}`}`,
+    );
+    this.name = 'sandboxqueueerror';
+    this.code = code;
+    this.id = id;
+    this.from = from;
+    this.to = to;
+  }
+}
+
+/* ------------------------------------------------------------------ */
+/* pure guards                                                         */
+/* ------------------------------------------------------------------ */
+
+/** checks whether a phase change is legal on the single machine. */
+export function cansandboxstep(from: sandboxphase, to: sandboxphase): boolean {
+  return sandboxtransitions[from].includes(to);
+}
+
+/** reports whether a phase is terminal. */
+export function issandboxterminal(phase: sandboxphase): boolean {
+  return SANDBOXTERMINALPHASES.includes(phase);
+}
+
+/* ------------------------------------------------------------------ */
+/* the queue                                                           */
+/* ------------------------------------------------------------------ */
+
+/** options of createsandboxqueue (all optional, sane defaults). */
+export type sandboxqueueoptions = {
+  /** per-state budgets; the defaults mirror the 125 ms api ramp. */
+  readonly budgets?: sandboxphasebudgets;
+  /** event ring capacity (default 100). */
+  readonly eventcap?: number;
+};
+
+/** a read-only status view answered by status(). */
+export type sandboxqueuestatus = {
+  readonly id: string;
+  readonly state: sandboxphase;
+  readonly enteredat: number;
+  readonly deadline: number | null;
+  readonly age: number;
+  readonly terminal: boolean;
+};
+
+/**
+ * creates the lifecycle queue. the queue validates every transition,
+ * stamps deadlines from the budgets and reaps expired entries on the
+ * health-check tick; the host decides when to tick.
+ *
+ * @param options the budgets and event ring capacity.
+ * @returns the queue facade (add, step, cancel, healthcheck, status,
+ *   list, events, size).
+ */
+export function createsandboxqueue(options?: sandboxqueueoptions): {
+  add: (id: string, now?: number) => sandboxqueueentry;
+  step: (id: string, to: sandboxphase, now?: number) => sandboxqueueentry;
+  cancel: (id: string, now?: number) => sandboxqueueentry;
+  healthcheck: (now?: number) => string[];
+  status: (id: string, now?: number) => sandboxqueuestatus;
+  list: (now?: number) => sandboxqueuestatus[];
+  events: () => sandboxqueueevent[];
+  size: () => number;
+} {
+  const budgets: sandboxphasebudgets = options?.budgets ?? {
+    creating: 125,
+    starting: 125,
+    stopping: 30000,
+  };
+  const eventcap = options?.eventcap ?? 100;
+  const entries = new Map<string, sandboxqueueentry>();
+  const ring: sandboxqueueevent[] = [];
+
+  /** stamps one event into the bounded ring. */
+  function record(
+    id: string,
+    from: sandboxphase,
+    to: sandboxphase,
+    at: number,
+    reason: sandboxqueueevent['reason'],
+  ): void {
+    ring.push({ id, from, to, at, reason });
+    if (ring.length > eventcap) {
+      ring.splice(0, ring.length - eventcap);
+    }
+  }
+
+  /** resolves the deadline of a phase from the budget table. */
+  function deadlinefor(state: sandboxphase, now: number): number | null {
+    const budget = budgets[state as keyof sandboxphasebudgets];
+    return typeof budget === 'number' && budget > 0 ? now + budget : null;
+  }
+
+  function statusOf(entry: sandboxqueueentry, now: number): sandboxqueuestatus {
+    return {
+      id: entry.id,
+      state: entry.state,
+      enteredat: entry.enteredat,
+      deadline: entry.deadline,
+      age: Math.max(0, now - entry.enteredat),
+      terminal: issandboxterminal(entry.state),
+    };
+  }
+
+  return {
+    add(id, now = Date.now()) {
+      if (entries.has(id)) {
+        throw new sandboxqueueerror('duplicate-sandbox', id, null, null);
+      }
+      const entry: sandboxqueueentry = {
+        id,
+        state: 'creating',
+        enteredat: now,
+        deadline: deadlinefor('creating', now),
+      };
+      entries.set(id, entry);
+      record(id, 'creating', 'creating', now, 'requested');
+      return entry;
+    },
+
+    step(id, to, now = Date.now()) {
+      const entry = entries.get(id);
+      if (entry === undefined) {
+        throw new sandboxqueueerror('unknown-sandbox', id, null, to);
+      }
+      if (!cansandboxstep(entry.state, to)) {
+        if (issandboxterminal(entry.state)) {
+          throw new sandboxqueueerror(
+            'terminal-phase',
+            id,
+            entry.state,
+            to,
+            `sandbox ${id} is terminal (${entry.state}); ${to} is unreachable`,
+          );
+        }
+        throw new sandboxqueueerror(
+          'invalid-transition',
+          id,
+          entry.state,
+          to,
+          `sandbox ${id} cannot transition ${entry.state} -> ${to}`,
+        );
+      }
+      const from = entry.state;
+      entry.state = to;
+      entry.enteredat = now;
+      entry.deadline = deadlinefor(to, now);
+      record(id, from, to, now, 'requested');
+      return entry;
+    },
+
+    cancel(id, now = Date.now()) {
+      const entry = entries.get(id);
+      if (entry === undefined) {
+        throw new sandboxqueueerror('unknown-sandbox', id, null, 'cancelled');
+      }
+      const from = entry.state;
+      if (!cansandboxstep(from, 'cancelled')) {
+        if (issandboxterminal(from)) {
+          throw new sandboxqueueerror(
+            'terminal-phase',
+            id,
+            from,
+            'cancelled',
+            `sandbox ${id} is terminal (${from}); cancellation is unreachable`,
+          );
+        }
+        throw new sandboxqueueerror(
+          'invalid-transition',
+          id,
+          from,
+          'cancelled',
+          `sandbox ${id} cannot be cancelled from ${from}`,
+        );
+      }
+      entry.state = 'cancelled';
+      entry.enteredat = now;
+      entry.deadline = null;
+      record(id, from, 'cancelled', now, 'cancel');
+      return entry;
+    },
+
+    healthcheck(now = Date.now()) {
+      const reaped: string[] = [];
+      for (const entry of entries.values()) {
+        if (entry.deadline === null || entry.deadline > now || issandboxterminal(entry.state)) {
+          continue;
+        }
+        const from = entry.state;
+        entry.state = 'timedout';
+        entry.enteredat = now;
+        entry.deadline = null;
+        record(entry.id, from, 'timedout', now, 'timeout');
+        reaped.push(entry.id);
+      }
+      return reaped;
+    },
+
+    status(id, now = Date.now()) {
+      const entry = entries.get(id);
+      if (entry === undefined) {
+        throw new sandboxqueueerror('unknown-sandbox', id, null, null);
+      }
+      return statusOf(entry, now);
+    },
+
+    list(now = Date.now()) {
+      return [...entries.values()]
+        .map((entry) => statusOf(entry, now))
+        .sort((a, b) => (a.id < b.id ? -1 : 1));
+    },
+
+    events() {
+      return [...ring];
+    },
+
+    size() {
+      return entries.size;
+    },
+  };
+}
+
+/* ===== block: sandboxquota ===== */
+/**
+ * sandboxquota.ts — the per-account resource quota ledger of saddle.
+ *
+ * every account holds counters of the resources its live sandboxes
+ * allocate (sandbox count, vcpus, ramgb, vgpus, diskgb) against a
+ * limits table. the limits are a plain parameter — the operator's plan
+ * table comes from config or the database and never lives in code; an
+ * absent limit means unlimited, mirroring the SADDLE_MAX_SANDBOXES
+ * convention of webserver.ts (0 or unset means unlimited).
+ *
+ * the ledger keeps reservations and releases in balance with a simple
+ * reconciliation: the host projects the authoritative usage (for
+ * example from the sqlite sandboxes rows) and reconcile() overwrites
+ * the in-memory counters with it, so drift from admin deletes, restarts
+ * or crashes self-heals on the next create.
+ *
+ * the module is pure: zero imports, zero dom, zero node builtins, a
+ * Map per account, typed traceable errors (quotaexceedederror carries
+ * the resource, the request, the limit and the remaining headroom).
+ *
+ * competitor sources shaping the contract: daytonaio/daytona (tenant
+ * resource quota admission with per-sandbox cpu/memory/gpu quota
+ * fields and the gpu allocator acquire/release pair around create) and
+ * opensandbox-group/opensandbox (namespace ResourceQuota admission —
+ * the sandbox is not admitted when the quota is exhausted — and the
+ * pool acquisition that fails fast when capacity stays unavailable).
+ *
+ * wire point: webserver.ts createsandbox reconciles the owning
+ * account from store.listsandboxesbyuser rows and reserves the new
+ * sandbox; destroysandbox releases it. limits come from
+ * accountlimitsfromenv(process.env) and stay unlimited when unset.
+ */
+
+/* ------------------------------------------------------------------ */
+/* types: usage, limits, errors                                        */
+/* ------------------------------------------------------------------ */
+
+/** the resource counters one account allocates through live sandboxes. */
+export type accountusage = {
+  sandboxes: number;
+  vcpus: number;
+  ramgb: number;
+  vgpus: number;
+  diskgb: number;
+};
+
+/** the per-account limits; an absent or non-positive field is unlimited. */
+export type accountlimits = {
+  readonly sandboxes?: number;
+  readonly vcpus?: number;
+  readonly ramgb?: number;
+  readonly vgpus?: number;
+  readonly diskgb?: number;
+};
+
+/** one resource wish (a partial usage delta). */
+export type resourcewish = Partial<accountusage>;
+
+/** the resource names tracked by the ledger. */
+const RESOURCES: readonly (keyof accountusage)[] = [
+  'sandboxes',
+  'vcpus',
+  'ramgb',
+  'vgpus',
+  'diskgb',
+];
+
+/** failure codes carried by quotaerror. */
+export type quotaerrorcode = 'invalid-wish' | 'quota-exceeded';
+
+/** the typed quota failure, traceable to the account and the resource. */
+export class quotaerror extends Error {
+  /** machine readable failure code. */
+  readonly code: quotaerrorcode;
+  /** the account the failure belongs to. */
+  readonly accountid: string;
+  /** the resource that failed (or 'wish' for malformed deltas). */
+  readonly resource: string;
+  /** the requested amount (null when the wish itself was malformed). */
+  readonly requested: number | null;
+  /** the active limit (null when unlimited). */
+  readonly limit: number | null;
+  /** the headroom the account had before the request. */
+  readonly available: number | null;
+
+  constructor(
+    code: quotaerrorcode,
+    accountid: string,
+    resource: string,
+    requested: number | null,
+    limit: number | null,
+    available: number | null,
+    message?: string,
+  ) {
+    super(
+      message ??
+        `account ${accountid} ${code} on ${resource}: requested ${requested ?? '?'} of ${limit ?? 'unlimited'} (${available ?? '?'} available)`,
+    );
+    this.name = 'quotaerror';
+    this.code = code;
+    this.accountid = accountid;
+    this.resource = resource;
+    this.requested = requested;
+    this.limit = limit;
+    this.available = available;
+  }
+}
+
+/* ------------------------------------------------------------------ */
+/* helpers                                                             */
+/* ------------------------------------------------------------------ */
+
+/** validates one resource wish: every present field is a positive number. */
+function sanitize(wish: resourcewish): Partial<accountusage> {
+  const clean: Partial<accountusage> = {};
+  for (const resource of RESOURCES) {
+    const value = wish[resource];
+    if (value === undefined) {
+      continue;
+    }
+    if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
+      throw new quotaerror(
+        'invalid-wish',
+        '',
+        resource,
+        typeof value === 'number' ? value : null,
+        null,
+        null,
+        `resource ${resource} must be a positive finite number (received ${String(value)})`,
+      );
+    }
+    clean[resource] = value;
+  }
+  return clean;
+}
+
+/** headroom of one resource under its limit (null limit means Infinity). */
+function headroom(limit: number | undefined, used: number): number | null {
+  return typeof limit === 'number' && limit > 0 ? Math.max(0, limit - used) : null;
+}
+
+/* ------------------------------------------------------------------ */
+/* the ledger                                                          */
+/* ------------------------------------------------------------------ */
+
+/** a read-only snapshot answered by usage(). */
+export type accountquotasnapshot = {
+  readonly accountid: string;
+  readonly used: Readonly<accountusage>;
+  readonly remaining: Readonly<Record<keyof accountusage, number | null>>;
+};
+
+/**
+ * creates the per-account ledger with one limits table for every
+ * account (per-plan tables ride on the caller passing the plan row of
+ * the account).
+ *
+ * @param limits the limits table (absent fields are unlimited).
+ * @returns the ledger facade (admits, reserve, release, usage,
+ *   reconcile, reset).
+ */
+export function createaccountledger(limits: accountlimits): {
+  admits: (accountid: string, wish: resourcewish) => boolean;
+  reserve: (accountid: string, wish: resourcewish) => accountquotasnapshot;
+  release: (accountid: string, wish: resourcewish) => accountquotasnapshot;
+  usage: (accountid: string) => accountquotasnapshot;
+  reconcile: (
+    accountid: string,
+    observed: accountusage,
+  ) => { before: accountquotasnapshot; after: accountquotasnapshot };
+  reset: (accountid?: string) => void;
+} {
+  const books = new Map<string, accountusage>();
+
+  /** zeroes the counters of an unseen account. */
+  function blank(accountid: string): accountusage {
+    const existing = books.get(accountid);
+    if (existing !== undefined) {
+      return existing;
+    }
+    const fresh: accountusage = { sandboxes: 0, vcpus: 0, ramgb: 0, vgpus: 0, diskgb: 0 };
+    books.set(accountid, fresh);
+    return fresh;
+  }
+
+  function snapshotOf(accountid: string, used: accountusage): accountquotasnapshot {
+    const remaining = {} as Record<keyof accountusage, number | null>;
+    for (const resource of RESOURCES) {
+      remaining[resource] = headroom(limits[resource], used[resource]);
+    }
+    return { accountid, used: { ...used }, remaining };
+  }
+
+  /** the shared admit-or-throw walk used by admits and reserve. */
+  function check(accountid: string, wish: resourcewish): Partial<accountusage> {
+    const clean = sanitize(wish);
+    const used = blank(accountid);
+    for (const resource of RESOURCES) {
+      const request = clean[resource];
+      if (request === undefined) {
+        continue;
+      }
+      const room = headroom(limits[resource], used[resource]);
+      if (room !== null && request > room) {
+        throw new quotaerror(
+          'quota-exceeded',
+          accountid,
+          resource,
+          request,
+          limits[resource] ?? null,
+          room,
+        );
+      }
+    }
+    return clean;
+  }
+
+  return {
+    admits(accountid, wish) {
+      try {
+        check(accountid, wish);
+        return true;
+      } catch (error) {
+        if (error instanceof quotaerror) {
+          return false;
+        }
+        throw error;
+      }
+    },
+
+    reserve(accountid, wish) {
+      const clean = check(accountid, wish);
+      const used = blank(accountid);
+      for (const resource of RESOURCES) {
+        const request = clean[resource];
+        if (request !== undefined) {
+          used[resource] += request;
+        }
+      }
+      return snapshotOf(accountid, used);
+    },
+
+    release(accountid, wish) {
+      const clean = sanitize(wish);
+      const used = blank(accountid);
+      for (const resource of RESOURCES) {
+        const request = clean[resource];
+        if (request !== undefined) {
+          used[resource] = Math.max(0, used[resource] - request);
+        }
+      }
+      return snapshotOf(accountid, used);
+    },
+
+    usage(accountid) {
+      return snapshotOf(accountid, blank(accountid));
+    },
+
+    reconcile(accountid, observed) {
+      const used = blank(accountid);
+      const before = snapshotOf(accountid, used);
+      for (const resource of RESOURCES) {
+        const value = observed[resource];
+        used[resource] =
+          typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : 0;
+      }
+      const after = snapshotOf(accountid, used);
+      return { before, after };
+    },
+
+    reset(accountid) {
+      if (accountid === undefined) {
+        books.clear();
+        return;
+      }
+      books.delete(accountid);
+    },
+  };
+}
+
+/* ------------------------------------------------------------------ */
+/* projection: rows to usage                                           */
+/* ------------------------------------------------------------------ */
+
+/** the structural row shape the projection reads (SandboxRow of db.ts
+ * satisfies it; kept structural so the module stays import-free). */
+export type sandboxrowlike = {
+  readonly vcpus: number | null;
+  readonly ramgb: number | null;
+  readonly state: string | null;
+};
+
+/**
+ * projects sandbox rows onto one account usage: every row that is not
+ * destroyed counts as a live allocation (the same semantics the
+ * SADDLE_MAX_SANDBOXES cap check of webserver.ts uses).
+ *
+ * @param rows the authoritative rows of one account.
+ * @returns the usage counters the rows allocate.
+ */
+export function usagefromrows(rows: readonly sandboxrowlike[]): accountusage {
+  const usage: accountusage = { sandboxes: 0, vcpus: 0, ramgb: 0, vgpus: 0, diskgb: 0 };
+  for (const row of rows) {
+    if (row.state === 'destroyed') {
+      continue;
+    }
+    usage.sandboxes += 1;
+    usage.vcpus += typeof row.vcpus === 'number' ? row.vcpus : 0;
+    usage.ramgb += typeof row.ramgb === 'number' ? row.ramgb : 0;
+  }
+  return usage;
+}
+
+/* ------------------------------------------------------------------ */
+/* adapter: limits from the environment                                */
+/* ------------------------------------------------------------------ */
+
+/**
+ * reads the per-account limits from the environment: SADDLE_MAX_SANDBOXES
+ * (the existing count cap of webserver.ts), SADDLE_ACCOUNT_MAX_VCPUS,
+ * SADDLE_ACCOUNT_MAX_RAM_GB, SADDLE_ACCOUNT_MAX_VGPUS and
+ * SADDLE_ACCOUNT_MAX_DISK_GB. unset, zero and negative values mean
+ * unlimited, so the default deployment enforces nothing.
+ *
+ * @param env the environment record (process.env shaped).
+ * @returns the limits table.
+ */
+export function accountlimitsfromenv(env: Record<string, string | undefined>): accountlimits {
+  const positive = (name: string): number | undefined => {
+    const parsed = Number(env[name]);
+    return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : undefined;
+  };
+  return {
+    sandboxes: positive('SADDLE_MAX_SANDBOXES'),
+    vcpus: positive('SADDLE_ACCOUNT_MAX_VCPUS'),
+    ramgb: positive('SADDLE_ACCOUNT_MAX_RAM_GB'),
+    vgpus: positive('SADDLE_ACCOUNT_MAX_VGPUS'),
+    diskgb: positive('SADDLE_ACCOUNT_MAX_DISK_GB'),
+  };
+}