@hotcell/daemon 0.1.0

package/dist/tracing.js

@@ -0,0 +1,144 @@
+import { randomBytes } from "node:crypto";
+import { log } from "./logger.js";
+let cfg = { serviceName: "sbd", otlpEndpoint: "", ringSize: 200 };
+const ring = [];
+let exportQueue = [];
+let flushTimer;
+export function configureTracing(opts) {
+    cfg = { ...cfg, ...opts };
+    if (cfg.otlpEndpoint && !flushTimer) {
+        flushTimer = setInterval(() => void flush(), 5000);
+        flushTimer.unref?.();
+    }
+}
+/** Stop the background OTLP flusher (call on daemon shutdown). */
+export function stopTracing() {
+    if (flushTimer) {
+        clearInterval(flushTimer);
+        flushTimer = undefined;
+    }
+}
+/** Recent finished spans, newest first. */
+export function recentSpans() {
+    return [...ring].reverse();
+}
+class ActiveSpan {
+    traceId;
+    spanId;
+    parentId;
+    name;
+    startWallMs;
+    startHr;
+    attributes;
+    status = "unset";
+    ended = false;
+    constructor(name, attributes, parent) {
+        this.name = name;
+        this.attributes = attributes;
+        this.traceId = parent?.traceId ?? randomBytes(16).toString("hex");
+        this.spanId = randomBytes(8).toString("hex");
+        this.parentId = parent?.spanId;
+        this.startWallMs = Date.now();
+        this.startHr = process.hrtime.bigint();
+    }
+    setAttribute(key, value) {
+        this.attributes[key] = value;
+        return this;
+    }
+    setStatus(status) {
+        this.status = status;
+        return this;
+    }
+    end() {
+        if (this.ended)
+            return;
+        this.ended = true;
+        const elapsedNs = process.hrtime.bigint() - this.startHr;
+        const startUnixNano = BigInt(this.startWallMs) * 1000000n;
+        const endUnixNano = startUnixNano + elapsedNs;
+        const data = {
+            traceId: this.traceId,
+            spanId: this.spanId,
+            parentId: this.parentId,
+            name: this.name,
+            startUnixNano: startUnixNano.toString(),
+            endUnixNano: endUnixNano.toString(),
+            durationMs: Number(elapsedNs) / 1e6,
+            attributes: this.attributes,
+            status: this.status === "unset" ? "ok" : this.status,
+        };
+        push(data);
+    }
+}
+/** Begin a span. Pass `parent` to nest it within an existing trace. */
+export function startSpan(name, attributes = {}, parent) {
+    return new ActiveSpan(name, attributes, parent);
+}
+function push(data) {
+    ring.push(data);
+    while (ring.length > cfg.ringSize)
+        ring.shift();
+    if (cfg.otlpEndpoint)
+        exportQueue.push(data);
+}
+async function flush() {
+    if (exportQueue.length === 0 || !cfg.otlpEndpoint)
+        return;
+    const batch = exportQueue;
+    exportQueue = [];
+    try {
+        const res = await fetch(`${cfg.otlpEndpoint}/v1/traces`, {
+            method: "POST",
+            headers: { "content-type": "application/json" },
+            body: JSON.stringify(toOtlp(batch, cfg.serviceName)),
+        });
+        if (!res.ok)
+            throw new Error(`status ${res.status}`);
+    }
+    catch (err) {
+        // Best-effort: drop this batch but keep the daemon healthy.
+        log.warn("otlp export failed", { error: String(err), spans: batch.length });
+    }
+}
+/** Build an OTLP/JSON ExportTraceServiceRequest from a batch of spans. */
+function toOtlp(spans, serviceName) {
+    return {
+        resourceSpans: [
+            {
+                resource: {
+                    attributes: [
+                        { key: "service.name", value: { stringValue: serviceName } },
+                    ],
+                },
+                scopeSpans: [
+                    {
+                        scope: { name: "hotcell", version: "0.1.0" },
+                        spans: spans.map((s) => ({
+                            traceId: s.traceId,
+                            spanId: s.spanId,
+                            parentSpanId: s.parentId,
+                            name: s.name,
+                            kind: 2, // SERVER
+                            startTimeUnixNano: s.startUnixNano,
+                            endTimeUnixNano: s.endUnixNano,
+                            attributes: Object.entries(s.attributes).map(([key, value]) => ({
+                                key,
+                                value: otlpValue(value),
+                            })),
+                            status: { code: s.status === "error" ? 2 : 1 },
+                        })),
+                    },
+                ],
+            },
+        ],
+    };
+}
+function otlpValue(value) {
+    if (typeof value === "boolean")
+        return { boolValue: value };
+    if (typeof value === "number") {
+        return Number.isInteger(value) ? { intValue: value } : { doubleValue: value };
+    }
+    return { stringValue: value };
+}
+//# sourceMappingURL=tracing.js.map

package/dist/tracing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tracing.js","sourceRoot":"","sources":["../src/tracing.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,274 @@
+/**
+ * Lifecycle states. `running` and `stopped` are explicit (user-driven via
+ * start/stop); `paused` is auto-entered by the idle reaper after `sleepAfterMs`
+ * of inactivity and auto-resumes on the next operation. A `stopped` sandbox is
+ * left alone by the reaper and does *not* auto-resume — the user must `start` it.
+ */
+export type SandboxStatus = "running" | "paused" | "stopped";
+/**
+ * Hard per-sandbox resource caps, enforced by the driver (cgroups via Docker).
+ * Each field `0`/undefined means "unlimited" (omitted from the container config).
+ * Units stay ergonomic for callers; the driver translates to its backend.
+ */
+export interface ResourceLimits {
+    /** Memory cap in MiB. */
+    memoryMb?: number;
+    /** CPU cap in fractional cores (e.g. 0.5 = half a core, 2 = two cores). */
+    cpus?: number;
+    /** Max number of processes/threads (fork-bomb guard). */
+    pidsLimit?: number;
+}
+export interface SandboxRecord {
+    id: string;
+    image: string;
+    status: SandboxStatus;
+    createdAt: string;
+    /**
+     * Runtime driver backing this sandbox (`container` | `applevz` | `firecracker`).
+     * Set at create time (per-sandbox isolation selection); the daemon routes every
+     * op to this driver. Empty/undefined falls back to the daemon default driver.
+     */
+    driver?: string;
+    labels: Record<string, string>;
+    /**
+     * Sandbox-level environment variables, merged into every `exec`/`startProcess`
+     * in this sandbox. Seeded from the create call's `env` and mutated by
+     * `setEnvVars`. Request- and session-level env take precedence over these.
+     */
+    env: Record<string, string>;
+    /**
+     * Whether `/workspace` is backed by a named volume that survives `stop`/`start`
+     * and container recreation. Set at create time; defaults to true.
+     */
+    persist: boolean;
+    /**
+     * ISO timestamp of the last operation that ran work in the sandbox (exec, file
+     * op, run-code, proxy traffic, …). Drives idle detection. Refreshed by the
+     * store's `touch`.
+     */
+    lastActivityAt: string;
+    /**
+     * Auto-pause the sandbox after this many milliseconds of inactivity (the idle
+     * reaper transitions `running → paused`, freeing compute while the workspace
+     * volume persists). `0` disables auto-pause. Set at create time.
+     */
+    sleepAfterMs: number;
+    /** Resolved hard resource caps (per-create override merged over daemon defaults). */
+    limits: ResourceLimits;
+    /**
+     * Hard ceiling (USD) on this sandbox's cumulative LLM-provider cost across ALL
+     * its egress tokens — the gateway returns 402 once `usage.providerCost` reaches
+     * it, regardless of per-token caps. `0`/undefined = unlimited. A blast-radius
+     * backstop: even an abused, not-yet-revoked token can't exceed it.
+     */
+    egressSpendCapUsd?: number;
+    /** Cumulative resource usage, integrated by the metrics sampler. */
+    usage: SandboxUsage;
+}
+/**
+ * Cumulative, time-integrated resource usage for a sandbox — the basis of the
+ * cost meter. Accumulated by the metrics sampler and persisted, so totals carry
+ * across daemon restarts. The two `last*` fields are sampler bookkeeping.
+ */
+export interface SandboxUsage {
+    /** Total vCPU-seconds consumed (Σ of cumulative-CPU-ns deltas / 1e9). */
+    cpuSeconds: number;
+    /** Total memory byte-seconds (Σ of memBytes × seconds-since-last-sample). */
+    memByteSeconds: number;
+    /** Total bytes the sandbox has sent out through the preview proxy. */
+    egressBytes: number;
+    /** Number of LLM-provider calls made through the egress credential proxy. */
+    providerCalls: number;
+    /** Total bytes exchanged with providers through the egress proxy (both ways). */
+    providerBytes: number;
+    /** Prompt/input tokens billed across provider calls (parsed from responses). */
+    providerTokensIn: number;
+    /** Completion/output tokens billed across provider calls. */
+    providerTokensOut: number;
+    /** Provider-reported LLM cost in USD (e.g. OpenRouter's `usage.cost`), summed across calls. */
+    providerCost: number;
+    /** Last observed cumulative CPU ns, to compute the next delta (reset-safe). */
+    lastCpuTotalNs: number;
+    /** ISO timestamp of the last sample, to integrate memory over wall-clock. */
+    lastSampledAt: string;
+}
+/**
+ * Per-token egress policy. Every field is optional; an empty policy (`{}`) means
+ * "unlimited" — the original, pre-policy behaviour. Enforced by the egress
+ * gateway on the LLM hot path (see `proxy/egress.ts`).
+ */
+export interface EgressPolicy {
+    /** ISO timestamp after which the token is rejected with 403. Omit = never expires. */
+    expiresAt?: string;
+    /** Cumulative USD this token may spend across provider calls; 402 once reached. */
+    spendCapUsd?: number;
+    /** Sliding-window rate limit (per token). Omit = unlimited. */
+    rateLimit?: {
+        /** Max provider calls per window. */
+        calls?: number;
+        /** Max billed tokens (in+out) per window. */
+        tokens?: number;
+        /** Window length in milliseconds. */
+        windowMs: number;
+    };
+    /** Allowed model ids/prefix-globs (matched against the request's `model`). Omit = all. */
+    models?: string[];
+    /** Allowed provider names (e.g. `openai`). Omit = every configured provider. */
+    providers?: string[];
+}
+/**
+ * A minted egress token bound to a sandbox, with its policy and running spend.
+ * The store keeps these in an O(1) `Map<token, EgressTokenRecord>` so the gateway
+ * resolves token → sandbox + policy in one lookup on every provider call.
+ */
+export interface EgressTokenRecord {
+    token: string;
+    sandboxId: string;
+    policy: EgressPolicy;
+    createdAt: string;
+    /** Cumulative USD spent through this token (drives the spend cap). */
+    spendUsd: number;
+}
+/** Per-resource cost breakdown in the configured currency. */
+export interface CostBreakdown {
+    cpu: number;
+    mem: number;
+    egress: number;
+    /** LLM cost (provider-reported, e.g. OpenRouter `usage.cost`). */
+    provider: number;
+    total: number;
+}
+/**
+ * A persistent execution context inside a sandbox. Holds a working directory
+ * (which follows `cd` across commands) and its own environment overlay, so a
+ * sequence of `exec`s behaves like one shell session. Built on top of the
+ * driver's stateless `exec`/`readFile` — no driver support required.
+ */
+export interface SessionInfo {
+    sessionId: string;
+    /** Working directory for the next command; updated after each exec. */
+    cwd: string;
+    /** Session-level env, layered over the sandbox env. */
+    env: Record<string, string>;
+    createdAt: string;
+}
+export interface ExecOptions {
+    cwd?: string;
+    env?: Record<string, string>;
+}
+/** A single event in a streaming command execution. */
+export type ExecEvent = {
+    type: "stdout";
+    data: string;
+} | {
+    type: "stderr";
+    data: string;
+} | {
+    type: "exit";
+    exitCode: number;
+};
+/** Metadata returned for a file or directory entry. */
+export interface FileInfo {
+    path: string;
+    name: string;
+    isDirectory: boolean;
+    size: number;
+    modifiedAt: string;
+}
+/** Options for writing a file inside a sandbox. */
+export interface WriteFileOptions {
+    path: string;
+    content: string;
+    mode?: string;
+}
+/** Options for reading a file from a sandbox. */
+export interface ReadFileOptions {
+    path: string;
+}
+/** Options for creating a directory inside a sandbox. */
+export interface MkdirOptions {
+    path: string;
+    parents?: boolean;
+}
+/** Options for listing files inside a sandbox. */
+export interface ListFilesOptions {
+    path: string;
+}
+/** Options for launching a long-running background process. */
+export interface StartProcessOptions {
+    cwd?: string;
+    env?: Record<string, string>;
+}
+/** A long-running background process tracked by the daemon. */
+export interface ProcessInfo {
+    /** Daemon-assigned handle (stable across PID reuse). */
+    procId: string;
+    /** In-container PID of the detached process. */
+    pid: number;
+    command: string;
+    status: "running" | "exited";
+    exitCode: number | null;
+    startedAt: string;
+    /** Path of the process logfile inside the sandbox. */
+    logPath: string;
+}
+/**
+ * A persistent code-interpreter context. Backed by a long-lived kernel process
+ * inside the sandbox that keeps a namespace across `runCode` calls (variables
+ * and imports persist, Jupyter-style).
+ */
+export interface CodeContextInfo {
+    contextId: string;
+    language: "python" | "javascript";
+    /** Context directory inside the sandbox (holds the kernel + its fifos). */
+    dir: string;
+    /** procId of the kernel background process (so it can be killed on cleanup). */
+    procId: string;
+    /** In-container PID of the kernel (target for the kill on cleanup). */
+    pid: number;
+    /** Monotonic cell counter, incremented per `runCode`. */
+    seq: number;
+    createdAt: string;
+}
+/** A single rich output from a code cell. */
+export interface CodeOutput {
+    type: "text";
+    text: string;
+}
+/** The result of running a code cell. */
+export interface CodeResult {
+    stdout: string;
+    stderr: string;
+    /** Rich outputs (e.g. the value of a trailing expression). */
+    results: CodeOutput[];
+    /** Formatted traceback/stack if the cell raised, else null. */
+    error: string | null;
+}
+/** A filesystem change observed by `watch`. */
+export interface FileChangeEvent {
+    type: "created" | "modified" | "deleted";
+    path: string;
+}
+/** Options for watching a path for changes. */
+export interface WatchOptions {
+    /** Poll interval in milliseconds (default 1000). */
+    intervalMs?: number;
+}
+/** Options for waiting until a TCP port is listening inside a sandbox. */
+export interface WaitForPortOptions {
+    timeoutMs?: number;
+    intervalMs?: number;
+    host?: string;
+}
+/** A port exposed through the daemon's preview-URL reverse proxy. */
+export interface ExposedPort {
+    /** In-container port the app listens on. */
+    port: number;
+    /** Routing label / subdomain (`<sandboxId>-<port>`). */
+    exposeId: string;
+    /** Optional per-port bearer token; null means open on loopback. */
+    token: string | null;
+    createdAt: string;
+    /** Computed preview URL. */
+    url: string;
+}

package/dist/types.js

@@ -0,0 +1,3 @@
+// Shared daemon types.
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,uBAAuB"}

package/dist/util.d.ts

@@ -0,0 +1,27 @@
+import type { ServerResponse } from "node:http";
+/** Normalize any thrown value to a message string. */
+export declare function errorMessage(err: unknown): string;
+/** Single-quote a value for safe interpolation into a shell command. */
+export declare function shellEscape(value: string): string;
+/** Thrown when a request body exceeds the configured cap (→ HTTP 413). */
+export declare class BodyTooLargeError extends Error {
+    constructor();
+}
+/**
+ * Read a request body fully into a Buffer, aborting with `BodyTooLargeError`
+ * once it would exceed `maxBytes`. Shared by the REST API and egress gateway so
+ * neither can be made to buffer unbounded memory from one request.
+ */
+export declare function readBodyCapped(req: {
+    [Symbol.asyncIterator](): AsyncIterator<unknown>;
+}, maxBytes: number): Promise<Buffer>;
+/**
+ * Constant-time string equality for secrets (API keys, preview tokens). Avoids
+ * the early-exit timing leak of `===`. The length comparison is intentional and
+ * standard — `timingSafeEqual` requires equal-length buffers.
+ */
+export declare function safeEqual(a: string, b: string): boolean;
+/** Send a JSON response with the correct Content-Length. */
+export declare function sendJson(res: ServerResponse, status: number, body: unknown): void;
+/** Send a `text/plain` response (one trailing newline) with Content-Length. */
+export declare function sendText(res: ServerResponse, status: number, message: string): void;

package/dist/util.js

@@ -0,0 +1,63 @@
+import { timingSafeEqual } from "node:crypto";
+/** Normalize any thrown value to a message string. */
+export function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/** Single-quote a value for safe interpolation into a shell command. */
+export function shellEscape(value) {
+    return `'${value.replace(/'/g, "'\"'\"'")}'`;
+}
+/** Thrown when a request body exceeds the configured cap (→ HTTP 413). */
+export class BodyTooLargeError extends Error {
+    constructor() {
+        super("request body too large");
+        this.name = "BodyTooLargeError";
+    }
+}
+/**
+ * Read a request body fully into a Buffer, aborting with `BodyTooLargeError`
+ * once it would exceed `maxBytes`. Shared by the REST API and egress gateway so
+ * neither can be made to buffer unbounded memory from one request.
+ */
+export async function readBodyCapped(req, maxBytes) {
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of req) {
+        total += chunk.length;
+        if (total > maxBytes)
+            throw new BodyTooLargeError();
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks);
+}
+/**
+ * Constant-time string equality for secrets (API keys, preview tokens). Avoids
+ * the early-exit timing leak of `===`. The length comparison is intentional and
+ * standard — `timingSafeEqual` requires equal-length buffers.
+ */
+export function safeEqual(a, b) {
+    const ab = Buffer.from(a, "utf8");
+    const bb = Buffer.from(b, "utf8");
+    if (ab.length !== bb.length)
+        return false;
+    return timingSafeEqual(ab, bb);
+}
+/** Send a JSON response with the correct Content-Length. */
+export function sendJson(res, status, body) {
+    const payload = JSON.stringify(body);
+    res.writeHead(status, {
+        "Content-Type": "application/json",
+        "Content-Length": Buffer.byteLength(payload),
+    });
+    res.end(payload);
+}
+/** Send a `text/plain` response (one trailing newline) with Content-Length. */
+export function sendText(res, status, message) {
+    const body = message + "\n";
+    res.writeHead(status, {
+        "Content-Type": "text/plain; charset=utf-8",
+        "Content-Length": Buffer.byteLength(body),
+    });
+    res.end(body);
+}
+//# sourceMappingURL=util.js.map

package/dist/util.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"util.js","sourceRoot":"","sources":["../src/util.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAG9C,sDAAsD;AACtD,MAAM,UAAU,YAAY,CAAC,GAAY;IACvC,OAAO,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;AAC1D,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,WAAW,CAAC,KAAa;IACvC,OAAO,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,SAAS,CAAC,GAAG,CAAC;AAC/C,CAAC;AAED,0EAA0E;AAC1E,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAC1C;QACE,KAAK,CAAC,wBAAwB,CAAC,CAAC;QAChC,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,GAAyD,EACzD,QAAgB;IAEhB,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,KAAK,EAAE,MAAM,KAAK,IAAI,GAA4B,EAAE,CAAC;QACvD,KAAK,IAAI,KAAK,CAAC,MAAM,CAAC;QACtB,IAAI,KAAK,GAAG,QAAQ;YAAE,MAAM,IAAI,iBAAiB,EAAE,CAAC;QACpD,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IACrB,CAAC;IACD,OAAO,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;AAC/B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,CAAS,EAAE,CAAS;IAC5C,MAAM,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IAClC,MAAM,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC;IAClC,IAAI,EAAE,CAAC,MAAM,KAAK,EAAE,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAC1C,OAAO,eAAe,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;AACjC,CAAC;AAED,4DAA4D;AAC5D,MAAM,UAAU,QAAQ,CAAC,GAAmB,EAAE,MAAc,EAAE,IAAa;IACzE,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IACrC,GAAG,CAAC,SAAS,CAAC,MAAM,EAAE;QACpB,cAAc,EAAE,kBAAkB;QAClC,gBAAgB,EAAE,MAAM,CAAC,UAAU,CAAC,OAAO,CAAC;KAC7C,CAAC,CAAC;IACH,GAAG,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;AACnB,CAAC;AAED,+EAA+E;AAC/E,MAAM,UAAU,QAAQ,CAAC,GAAmB,EAAE,MAAc,EAAE,OAAe;IAC3E,MAAM,IAAI,GAAG,OAAO,GAAG,IAAI,CAAC;IAC5B,GAAG,CAAC,SAAS,CAAC,MAAM,EAAE;QACpB,cAAc,EAAE,2BAA2B;QAC3C,gBAAgB,EAAE,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC;KAC1C,CAAC,CAAC;IACH,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC"}

package/dist/warmpool-check.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/warmpool-check.js

@@ -0,0 +1,83 @@
+/**
+ * Apple VZ warm-pool (M7b) check. Proves a pre-booted spare microVM is adopted
+ * on create — an instant acquire — versus a full cold boot, and that the adopted
+ * sandbox is fully functional with an isolated workspace that survives stop/start.
+ * Run on a Mac with the VZ artifacts built: `npm run check:warmpool`.
+ */
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+import { AppleVzDriver } from "./driver/applevz.js";
+async function main() {
+    const stateDir = mkdtempSync(join(tmpdir(), "hotcell-warmpool-"));
+    const driver = new AppleVzDriver({
+        helperPath: "helpers/hotcell-vz/dist/hotcell-vz",
+        kernel: "helpers/hotcell-vz/guest/vmlinux-vz",
+        rootfs: "helpers/hotcell-vz/guest/rootfs.img",
+        stateDir,
+        diskGb: 2,
+        imageCacheDir: join(homedir(), ".sbx", "vz", "images"),
+        warmPool: 1, // keep one spare base guest pre-booted
+    });
+    let passed = 0;
+    const ok = (l) => {
+        passed++;
+        console.log(`  ✓ ${l}`);
+    };
+    try {
+        // Wait for the background filler to pre-boot the spare.
+        const deadline = Date.now() + 40_000;
+        while (driver.poolSize() < 1 && Date.now() < deadline)
+            await sleep(200);
+        assert.ok(driver.poolSize() >= 1, "warm pool failed to pre-boot a spare");
+        ok(`warm pool pre-booted ${driver.poolSize()} spare guest`);
+        // Warm acquire: create a base sandbox — should adopt the spare (instant).
+        const warmId = "warm01";
+        const t0 = Date.now();
+        await driver.create({ id: warmId, image: "base", persist: true });
+        const warmMs = Date.now() - t0;
+        ok(`warm create adopted a spare in ${warmMs}ms`);
+        // The adopted sandbox is a real, working VM with its own workspace.
+        let out = "";
+        await driver.exec(warmId, "uname -s && echo WARM_OK", {}, (e) => {
+            if (e.type === "stdout")
+                out += e.data;
+        });
+        assert.match(out, /Linux/, "adopted guest runs Linux");
+        assert.match(out, /WARM_OK/, "adopted guest execs");
+        await driver.writeFile(warmId, { path: "/workspace/w.txt", content: "warm-data" });
+        assert.equal(await driver.readFile(warmId, { path: "/workspace/w.txt" }), "warm-data");
+        ok("adopted guest execs + has a writable workspace");
+        // Workspace survives stop/start (canonical path adopted from the slot).
+        await driver.stop(warmId);
+        await driver.start({ id: warmId, image: "base", persist: true });
+        assert.equal(await driver.readFile(warmId, { path: "/workspace/w.txt" }), "warm-data", "adopted workspace persists across stop/start");
+        ok("adopted workspace persists across stop/start");
+        // Cold baseline: drain the pool, then create — a full boot for comparison.
+        await driver.drainPool();
+        const coldId = "cold01";
+        const t1 = Date.now();
+        await driver.create({ id: coldId, image: "base", persist: true });
+        const coldMs = Date.now() - t1;
+        ok(`cold create (pool drained) booted in ${coldMs}ms`);
+        assert.ok(warmMs < coldMs, `warm acquire (${warmMs}ms) should beat cold boot (${coldMs}ms)`);
+        ok(`★ warm acquire ${warmMs}ms ≪ cold boot ${coldMs}ms (${Math.round(coldMs / Math.max(1, warmMs))}× faster)`);
+        await driver.destroy(warmId);
+        await driver.destroy(coldId);
+        ok("destroy both");
+        console.log(`\nwarmpool-check: ${passed} checks passed`);
+    }
+    finally {
+        await driver.drainPool().catch(() => { });
+        await driver.stop("warm01").catch(() => { });
+        await driver.stop("cold01").catch(() => { });
+        rmSync(stateDir, { recursive: true, force: true });
+    }
+}
+main().then(() => process.exit(0), (err) => {
+    console.error("warmpool-check FAILED:", err);
+    process.exit(1);
+});
+//# sourceMappingURL=warmpool-check.js.map

package/dist/warmpool-check.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"warmpool-check.js","sourceRoot":"","sources":["../src/warmpool-check.ts"],"names":[],"mappings":"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"}

package/dist/web/dashboard.d.ts

@@ -0,0 +1 @@
+export declare const DASHBOARD_HTML: string;