@synap-core/cli 1.12.2 → 1.13.0

package/dist/lib/box/provisioner.js

@@ -0,0 +1,312 @@
+/**
+ * The provisioner's loop: one box per run, one run at a time (phase 0).
+ *
+ *   guards ok? ─no─▶ wait (the run keeps its turn: nothing is leased)
+ *   lease ─▶ clone + start a box ─▶ the box fetches its job, installs, runs
+ *        ─▶ done | a clock ran out | Stop | lease lost | provisioner stopping
+ *   destroy the box, ALWAYS ─▶ upload /out ─▶ finish with the evidence
+ *
+ * Three clocks, one after the other: BOOT (the box must ask for its job, else
+ * INFRA: it never started), SETUP (the declared packages must install, else
+ * timeout), and the script's own wall clock from the moment it starts.
+ *
+ * A lost lease (404/409) ends the work without a finish: the pod already gave
+ * the run up. A reaper destroys every tagged box no run holds, at start and
+ * after every run, so a crash never leaves a box behind for long.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { assembleFinish, LogCapture } from "./evidence.js";
+import { LeaseLostError, WorkspaceRequiredError, } from "./wire.js";
+/** Phase 0 on the founder's host: swap is full, so the margin is RAM only. */
+export const DEFAULT_GUARDS = { minMemAvailableMb: 6144, maxStorageUsedPct: 85, maxMetaUsedPct: 70 };
+/**
+ * BOX-CONTRACT "Phase 0 caps". The pod enforces them when a run is queued; the
+ * provisioner re-applies them because the host is the person's, not the pod's.
+ */
+export const PHASE0_CAPS = { wallSeconds: 3600, cpus: 2, memoryMb: 2048, diskMb: 8192, outMb: 200 };
+/** A box that has not asked for its job by then did not start: INFRA, not the script's verdict. */
+export const BOOT_SECONDS = 180;
+/** The declared packages must be installed by then; past it the run timed out in setup. */
+export const SETUP_SECONDS = 900;
+/** Limits cut to the phase 0 caps, and the names of the ones that were cut. */
+export function clampLimits(l) {
+    const clamped = [];
+    const out = { ...l };
+    for (const k of Object.keys(PHASE0_CAPS)) {
+        const v = Number.isFinite(l[k]) && l[k] > 0 ? l[k] : PHASE0_CAPS[k];
+        out[k] = Math.min(v, PHASE0_CAPS[k]);
+        if (out[k] !== l[k])
+            clamped.push(`${k} ${l[k]} → ${out[k]}`);
+    }
+    return { limits: out, clamped };
+}
+export function checkGuards(r, g) {
+    if (r.memAvailableMb < g.minMemAvailableMb) {
+        return { ok: false, reason: `host MemAvailable ${r.memAvailableMb} MB < ${g.minMemAvailableMb} MB` };
+    }
+    if (r.storageUsedPct > g.maxStorageUsedPct) {
+        return { ok: false, reason: `box storage ${r.storageUsedPct.toFixed(1)}% full > ${g.maxStorageUsedPct}%` };
+    }
+    if (r.metaUsedPct !== null && r.metaUsedPct > g.maxMetaUsedPct) {
+        return { ok: false, reason: `thin pool metadata ${r.metaUsedPct.toFixed(1)}% full > ${g.maxMetaUsedPct}%` };
+    }
+    return { ok: true };
+}
+const MIME = {
+    ".png": "image/png",
+    ".jpg": "image/jpeg",
+    ".jpeg": "image/jpeg",
+    ".gif": "image/gif",
+    ".svg": "image/svg+xml",
+    ".webp": "image/webp",
+    ".pdf": "application/pdf",
+    ".csv": "text/csv",
+    ".json": "application/json",
+    ".txt": "text/plain",
+    ".md": "text/markdown",
+    ".html": "text/html",
+    ".zip": "application/zip",
+    ".mp4": "video/mp4",
+    ".mp3": "audio/mpeg",
+    ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+};
+export function mimeOf(file) {
+    return MIME[path.extname(file).toLowerCase()] ?? "application/octet-stream";
+}
+/** Destroy every tagged box no run holds. Returns the VMIDs destroyed. */
+export async function reap(backend, held, log) {
+    const gone = [];
+    for (const b of await backend.list()) {
+        if (held.has(b.vmid))
+            continue;
+        try {
+            await backend.destroy(b.vmid);
+            gone.push(b.vmid);
+            log(`reaper: destroyed stray box ${b.vmid} (${b.name})`);
+        }
+        catch (err) {
+            log(`reaper: could not destroy box ${b.vmid}: ${err.message}`);
+        }
+    }
+    return gone;
+}
+/**
+ * Work one leased run to its end (BOX-CONTRACT v2). Returns the finish body sent, or null when
+ * the lease was lost (no finish is sent then).
+ */
+export async function runOne(leasedRun, deps) {
+    const now = deps.now ?? Date.now;
+    const startedAt = now();
+    const { limits, clamped } = clampLimits(leasedRun.script.limits);
+    const run = { ...leasedRun, script: { ...leasedRun.script, limits } };
+    const bootMs = deps.bootMs ?? BOOT_SECONDS * 1000;
+    const setupMs = deps.setupMs ?? SETUP_SECONDS * 1000;
+    let phase = "setup";
+    let stopped = false;
+    let lost = false;
+    let timedOut = false;
+    let infraReason;
+    /** Said in the run's log once a box exists (a clock that ran out, a cap that cut a limit). */
+    const notes = clamped.length ? [`limits cut to the phase 0 caps: ${clamped.join(", ")}`] : [];
+    let wake = () => { };
+    const interrupted = new Promise((r) => (wake = r));
+    const beat = async () => {
+        try {
+            const reply = await deps.hub.heartbeat(run, phase);
+            if (reply.stopRequested && !stopped) {
+                stopped = true;
+                deps.log(`run ${run.id}: Stop requested`);
+                wake();
+            }
+        }
+        catch (err) {
+            if (err instanceof LeaseLostError) {
+                lost = true;
+                deps.log(`run ${run.id}: ${err.message}`);
+                wake();
+                return;
+            }
+            // A transient failure: the next beat retries before the lease runs out.
+            deps.log(`run ${run.id}: heartbeat failed: ${err.message}`);
+        }
+    };
+    const onAbort = () => {
+        infraReason ??= "the provisioner was stopped mid-run";
+        wake();
+    };
+    deps.signal?.addEventListener("abort", onAbort);
+    let clock;
+    const arm = (ms, fire) => {
+        clearTimeout(clock);
+        clock = setTimeout(() => {
+            fire();
+            wake();
+        }, ms);
+    };
+    await beat();
+    if (lost) {
+        deps.signal?.removeEventListener("abort", onAbort);
+        return null;
+    }
+    const timer = setInterval(() => void beat(), Math.max(5, run.heartbeatIntervalSeconds) * 1000);
+    deps.registry.onEvent = (r, event) => {
+        if (r.id !== run.id)
+            return;
+        if (event === "job") {
+            arm(setupMs, () => {
+                timedOut = true;
+                notes.push(`packages were still installing after ${Math.round(setupMs / 1000)} s: the box was destroyed`);
+            });
+            return;
+        }
+        phase = "running";
+        void beat();
+        arm(limits.wallSeconds * 1000, () => {
+            timedOut = true;
+            notes.push(`the script ran past its ${limits.wallSeconds} s wall clock: the box was destroyed`);
+        });
+    };
+    let ip = null;
+    let vmid = null;
+    let report = { exitCode: null, installedPackages: [] };
+    try {
+        // A Stop, a lost lease or a stopping provisioner before the clone: no box at all.
+        if (!stopped && !lost && !deps.signal?.aborted) {
+            try {
+                const handle = await deps.backend.create(run.id, { cpus: limits.cpus, memoryMb: limits.memoryMb });
+                ip = handle.ip;
+                vmid = handle.vmid;
+            }
+            catch (err) {
+                infraReason = `clone failed: ${err.message}`;
+            }
+        }
+        if (ip) {
+            const box = deps.registry.register(ip, run);
+            deps.log(`run ${run.id}: box ${vmid} at ${ip}`);
+            arm(bootMs, () => {
+                infraReason ??= `the box did not ask for its job within ${Math.round(bootMs / 1000)} s (boot or template problem)`;
+            });
+            const first = await Promise.race([box.done.then((d) => ({ d })), interrupted]);
+            if (first && "d" in first)
+                report = first.d;
+        }
+    }
+    finally {
+        clearTimeout(clock);
+        deps.registry.onEvent = () => { };
+        deps.signal?.removeEventListener("abort", onAbort);
+        if (vmid !== null) {
+            const attempts = deps.destroyAttempts ?? 3;
+            for (let i = 1; i <= attempts; i++) {
+                try {
+                    await deps.backend.destroy(vmid);
+                    deps.log(`run ${run.id}: box ${vmid} destroyed`);
+                    break;
+                }
+                catch (err) {
+                    deps.log(`run ${run.id}: destroy ${vmid} attempt ${i} failed: ${err.message}`);
+                }
+            }
+        }
+    }
+    const box = ip ? deps.registry.get(ip) : undefined;
+    const log = box?.log ?? new LogCapture();
+    for (const n of notes)
+        log.append(`\n[synap box] ${n}\n`);
+    try {
+        if (lost)
+            return null;
+        const files = [];
+        let storable = true;
+        for (const f of box?.outFiles ?? []) {
+            try {
+                if (!storable)
+                    throw new WorkspaceRequiredError();
+                // The pod's upload door takes no empty file: listed in the evidence only.
+                if (f.size === 0)
+                    throw new Error("the file is empty");
+                const bytes = fs.readFileSync(path.join(box.outDir, f.path));
+                const uploadToken = await deps.hub.upload(run, { filename: path.basename(f.path), mimeType: mimeOf(f.path), bytes });
+                files.push({ ...f, uploadToken, title: f.path });
+            }
+            catch (err) {
+                if (err instanceof LeaseLostError)
+                    return null;
+                if (err instanceof WorkspaceRequiredError)
+                    storable = false;
+                // Recorded without a token (evidence only) and said in the log the
+                // person reads, so a missing file is never silent.
+                files.push({ ...f });
+                log.append(`\n[synap box] /out/${f.path} (${f.size} bytes) was not stored: ${err.message}\n`);
+            }
+        }
+        const outcome = { exitCode: report.exitCode, timedOut, stopped, infraReason };
+        const body = assembleFinish({
+            leaseId: run.leaseId,
+            outcome,
+            startedAt,
+            finishedAt: now(),
+            log,
+            blockedEgress: box?.blocked ?? [],
+            installedPackages: report.installedPackages,
+            files,
+        });
+        try {
+            await deps.hub.finish(run, body);
+            deps.log(`run ${run.id}: finished ${body.status}`);
+        }
+        catch (err) {
+            deps.log(`run ${run.id}: finish failed: ${err.message}`);
+            if (err instanceof LeaseLostError)
+                return null;
+            throw err;
+        }
+        return body;
+    }
+    finally {
+        clearInterval(timer);
+        if (ip)
+            deps.registry.unregister(ip);
+    }
+}
+const realSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Lease and work runs until the signal aborts (or one pass with `once`). */
+export async function serve(deps, opts) {
+    const sleep = opts.sleep ?? realSleep;
+    await reap(deps.backend, new Set(), deps.log);
+    let lastWait = "";
+    while (!opts.signal?.aborted) {
+        try {
+            const guard = checkGuards(await deps.backend.readHost(), opts.guards);
+            if (!guard.ok) {
+                if (guard.reason !== lastWait)
+                    deps.log(`waiting, turn kept: ${guard.reason}`);
+                lastWait = guard.reason;
+                if (opts.once)
+                    return;
+                await sleep(opts.guardWaitMs);
+                continue;
+            }
+            lastWait = "";
+            const run = await deps.hub.lease();
+            if (run) {
+                deps.log(`leased run ${run.id} (${run.script.name}, ${run.script.language})`);
+                await runOne(run, { ...deps, signal: opts.signal });
+                await reap(deps.backend, new Set(), deps.log);
+            }
+            if (opts.once)
+                return;
+            if (!run)
+                await sleep(opts.idleMs);
+        }
+        catch (err) {
+            deps.log(`error: ${err.message}`);
+            if (opts.once)
+                throw err;
+            await sleep(opts.guardWaitMs);
+        }
+    }
+}
+//# sourceMappingURL=provisioner.js.map

package/dist/lib/box/provisioner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provisioner.js","sourceRoot":"","sources":["../../../src/lib/box/provisioner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,cAAc,EAAE,UAAU,EAAmB,MAAM,eAAe,CAAC;AAG5E,OAAO,EACL,cAAc,EACd,sBAAsB,GAKvB,MAAM,WAAW,CAAC;AAWnB,8EAA8E;AAC9E,MAAM,CAAC,MAAM,cAAc,GAAe,EAAE,iBAAiB,EAAE,IAAI,EAAE,iBAAiB,EAAE,EAAE,EAAE,cAAc,EAAE,EAAE,EAAE,CAAC;AAEjH;;;GAGG;AACH,MAAM,CAAC,MAAM,WAAW,GAAc,EAAE,WAAW,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;AAE/G,mGAAmG;AACnG,MAAM,CAAC,MAAM,YAAY,GAAG,GAAG,CAAC;AAChC,2FAA2F;AAC3F,MAAM,CAAC,MAAM,aAAa,GAAG,GAAG,CAAC;AAEjC,+EAA+E;AAC/E,MAAM,UAAU,WAAW,CAAC,CAAY;IACtC,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,MAAM,GAAG,GAAG,EAAE,GAAG,CAAC,EAAE,CAAC;IACrB,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC,WAAW,CAA2B,EAAE,CAAC;QACnE,MAAM,CAAC,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;QACpE,GAAG,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC;QACrC,IAAI,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YAAE,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAChE,CAAC;IACD,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC;AAClC,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,CAAc,EAAE,CAAa;IACvD,IAAI,CAAC,CAAC,cAAc,GAAG,CAAC,CAAC,iBAAiB,EAAE,CAAC;QAC3C,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,qBAAqB,CAAC,CAAC,cAAc,SAAS,CAAC,CAAC,iBAAiB,KAAK,EAAE,CAAC;IACvG,CAAC;IACD,IAAI,CAAC,CAAC,cAAc,GAAG,CAAC,CAAC,iBAAiB,EAAE,CAAC;QAC3C,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,eAAe,CAAC,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,iBAAiB,GAAG,EAAE,CAAC;IAC7G,CAAC;IACD,IAAI,CAAC,CAAC,WAAW,KAAK,IAAI,IAAI,CAAC,CAAC,WAAW,GAAG,CAAC,CAAC,cAAc,EAAE,CAAC;QAC/D,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,sBAAsB,CAAC,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,cAAc,GAAG,EAAE,CAAC;IAC9G,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;AACtB,CAAC;AAiBD,MAAM,IAAI,GAA2B;IACnC,MAAM,EAAE,WAAW;IACnB,MAAM,EAAE,YAAY;IACpB,OAAO,EAAE,YAAY;IACrB,MAAM,EAAE,WAAW;IACnB,MAAM,EAAE,eAAe;IACvB,OAAO,EAAE,YAAY;IACrB,MAAM,EAAE,iBAAiB;IACzB,MAAM,EAAE,UAAU;IAClB,OAAO,EAAE,kBAAkB;IAC3B,MAAM,EAAE,YAAY;IACpB,KAAK,EAAE,eAAe;IACtB,OAAO,EAAE,WAAW;IACpB,MAAM,EAAE,iBAAiB;IACzB,MAAM,EAAE,WAAW;IACnB,MAAM,EAAE,YAAY;IACpB,OAAO,EAAE,mEAAmE;CAC7E,CAAC;AAEF,MAAM,UAAU,MAAM,CAAC,IAAY;IACjC,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC,IAAI,0BAA0B,CAAC;AAC9E,CAAC;AAED,0EAA0E;AAC1E,MAAM,CAAC,KAAK,UAAU,IAAI,CAAC,OAAmB,EAAE,IAAyB,EAAE,GAAwB;IACjG,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,KAAK,MAAM,CAAC,IAAI,MAAM,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC;QACrC,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;YAAE,SAAS;QAC/B,IAAI,CAAC;YACH,MAAM,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;YAC9B,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;YAClB,GAAG,CAAC,+BAA+B,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC;QAC3D,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,GAAG,CAAC,iCAAiC,CAAC,CAAC,IAAI,KAAM,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;QAC5E,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,SAAoB,EAAE,IAAqB;IACtE,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC;IACjC,MAAM,SAAS,GAAG,GAAG,EAAE,CAAC;IACxB,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,WAAW,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IACjE,MAAM,GAAG,GAAc,EAAE,GAAG,SAAS,EAAE,MAAM,EAAE,EAAE,GAAG,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,CAAC;IACjF,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,IAAI,YAAY,GAAG,IAAI,CAAC;IAClD,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,IAAI,aAAa,GAAG,IAAI,CAAC;IAErD,IAAI,KAAK,GAAwB,OAAO,CAAC;IACzC,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,IAAI,IAAI,GAAG,KAAK,CAAC;IACjB,IAAI,QAAQ,GAAG,KAAK,CAAC;IACrB,IAAI,WAA+B,CAAC;IACpC,8FAA8F;IAC9F,MAAM,KAAK,GAAa,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,mCAAmC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACxG,IAAI,IAAI,GAAe,GAAG,EAAE,GAAE,CAAC,CAAC;IAChC,MAAM,WAAW,GAAG,IAAI,OAAO,CAAO,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC;IAEzD,MAAM,IAAI,GAAG,KAAK,IAAmB,EAAE;QACrC,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YACnD,IAAI,KAAK,CAAC,aAAa,IAAI,CAAC,OAAO,EAAE,CAAC;gBACpC,OAAO,GAAG,IAAI,CAAC;gBACf,IAAI,CAAC,GAAG,CAAC,OAAO,GAAG,CAAC,EAAE,kBAAkB,CAAC,CAAC;gBAC1C,IAAI,EAAE,CAAC;YACT,CAAC;QACH,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,cAAc,EAAE,CAAC;gBAClC,IAAI,GAAG,IAAI,CAAC;gBACZ,IAAI,CAAC,GAAG,CAAC,OAAO,GAAG,CAAC,EAAE,KAAK,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;gBAC1C,IAAI,EAAE,CAAC;gBACP,OAAO;YACT,CAAC;YACD,wEAAwE;YACxE,IAAI,CAAC,GAAG,CAAC,OAAO,GAAG,CAAC,EAAE,uBAAwB,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;QACzE,CAAC;IACH,CAAC,CAAC;IAEF,MAAM,OAAO,GAAG,GAAG,EAAE;QACnB,WAAW,KAAK,qCAAqC,CAAC;QACtD,IAAI,EAAE,CAAC;IACT,CAAC,CAAC;IACF,IAAI,CAAC,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAEhD,IAAI,KAAiC,CAAC;IACtC,MAAM,GAAG,GAAG,CAAC,EAAU,EAAE,IAAgB,EAAE,EAAE;QAC3C,YAAY,CAAC,KAAK,CAAC,CAAC;QACpB,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YACtB,IAAI,EAAE,CAAC;YACP,IAAI,EAAE,CAAC;QACT,CAAC,EAAE,EAAE,CAAC,CAAC;IACT,CAAC,CAAC;IAEF,MAAM,IAAI,EAAE,CAAC;IACb,IAAI,IAAI,EAAE,CAAC;QACT,IAAI,CAAC,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACnD,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,KAAK,IAAI,EAAE,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,wBAAwB,CAAC,GAAG,IAAI,CAAC,CAAC;IAC/F,IAAI,CAAC,QAAQ,CAAC,OAAO,GAAG,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE;QACnC,IAAI,CAAC,CAAC,EAAE,KAAK,GAAG,CAAC,EAAE;YAAE,OAAO;QAC5B,IAAI,KAAK,KAAK,KAAK,EAAE,CAAC;YACpB,GAAG,CAAC,OAAO,EAAE,GAAG,EAAE;gBAChB,QAAQ,GAAG,IAAI,CAAC;gBAChB,KAAK,CAAC,IAAI,CAAC,wCAAwC,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC,2BAA2B,CAAC,CAAC;YAC5G,CAAC,CAAC,CAAC;YACH,OAAO;QACT,CAAC;QACD,KAAK,GAAG,SAAS,CAAC;QAClB,KAAK,IAAI,EAAE,CAAC;QACZ,GAAG,CAAC,MAAM,CAAC,WAAW,GAAG,IAAI,EAAE,GAAG,EAAE;YAClC,QAAQ,GAAG,IAAI,CAAC;YAChB,KAAK,CAAC,IAAI,CAAC,2BAA2B,MAAM,CAAC,WAAW,sCAAsC,CAAC,CAAC;QAClG,CAAC,CAAC,CAAC;IACL,CAAC,CAAC;IAEF,IAAI,EAAE,GAAkB,IAAI,CAAC;IAC7B,IAAI,IAAI,GAAkB,IAAI,CAAC;IAC/B,IAAI,MAAM,GAAc,EAAE,QAAQ,EAAE,IAAI,EAAE,iBAAiB,EAAE,EAAE,EAAE,CAAC;IAClE,IAAI,CAAC;QACH,kFAAkF;QAClF,IAAI,CAAC,OAAO,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC;YAC/C,IAAI,CAAC;gBACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC,CAAC;gBACnG,EAAE,GAAG,MAAM,CAAC,EAAE,CAAC;gBACf,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC;YACrB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,WAAW,GAAG,iBAAkB,GAAa,CAAC,OAAO,EAAE,CAAC;YAC1D,CAAC;QACH,CAAC;QACD,IAAI,EAAE,EAAE,CAAC;YACP,MAAM,GAAG,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,EAAE,GAAG,CAAC,CAAC;YAC5C,IAAI,CAAC,GAAG,CAAC,OAAO,GAAG,CAAC,EAAE,SAAS,IAAI,OAAO,EAAE,EAAE,CAAC,CAAC;YAChD,GAAG,CAAC,MAAM,EAAE,GAAG,EAAE;gBACf,WAAW,KAAK,0CAA0C,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,+BAA+B,CAAC;YACrH,CAAC,CAAC,CAAC;YACH,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC;YAC/E,IAAI,KAAK,IAAI,GAAG,IAAI,KAAK;gBAAE,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC;QAC9C,CAAC;IACH,CAAC;YAAS,CAAC;QACT,YAAY,CAAC,KAAK,CAAC,CAAC;QACpB,IAAI,CAAC,QAAQ,CAAC,OAAO,GAAG,GAAG,EAAE,GAAE,CAAC,CAAC;QACjC,IAAI,CAAC,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACnD,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;YAClB,MAAM,QAAQ,GAAG,IAAI,CAAC,eAAe,IAAI,CAAC,CAAC;YAC3C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,QAAQ,EAAE,CAAC,EAAE,EAAE,CAAC;gBACnC,IAAI,CAAC;oBACH,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;oBACjC,IAAI,CAAC,GAAG,CAAC,OAAO,GAAG,CAAC,EAAE,SAAS,IAAI,YAAY,CAAC,CAAC;oBACjD,MAAM;gBACR,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,IAAI,CAAC,GAAG,CAAC,OAAO,GAAG,CAAC,EAAE,aAAa,IAAI,YAAY,CAAC,YAAa,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;gBAC5F,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED,MAAM,GAAG,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACnD,MAAM,GAAG,GAAG,GAAG,EAAE,GAAG,IAAI,IAAI,UAAU,EAAE,CAAC;IACzC,KAAK,MAAM,CAAC,IAAI,KAAK;QAAE,GAAG,CAAC,MAAM,CAAC,iBAAiB,CAAC,IAAI,CAAC,CAAC;IAC1D,IAAI,CAAC;QACH,IAAI,IAAI;YAAE,OAAO,IAAI,CAAC;QAEtB,MAAM,KAAK,GAAwB,EAAE,CAAC;QACtC,IAAI,QAAQ,GAAG,IAAI,CAAC;QACpB,KAAK,MAAM,CAAC,IAAI,GAAG,EAAE,QAAQ,IAAI,EAAE,EAAE,CAAC;YACpC,IAAI,CAAC;gBACH,IAAI,CAAC,QAAQ;oBAAE,MAAM,IAAI,sBAAsB,EAAE,CAAC;gBAClD,0EAA0E;gBAC1E,IAAI,CAAC,CAAC,IAAI,KAAK,CAAC;oBAAE,MAAM,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAAC;gBACvD,MAAM,KAAK,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,GAAI,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;gBAC9D,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,EAAE,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;gBACrH,KAAK,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC,EAAE,WAAW,EAAE,KAAK,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;YACnD,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,GAAG,YAAY,cAAc;oBAAE,OAAO,IAAI,CAAC;gBAC/C,IAAI,GAAG,YAAY,sBAAsB;oBAAE,QAAQ,GAAG,KAAK,CAAC;gBAC5D,mEAAmE;gBACnE,mDAAmD;gBACnD,KAAK,CAAC,IAAI,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;gBACrB,GAAG,CAAC,MAAM,CAAC,sBAAsB,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,IAAI,2BAA4B,GAAa,CAAC,OAAO,IAAI,CAAC,CAAC;YAC3G,CAAC;QACH,CAAC;QAED,MAAM,OAAO,GAAe,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,EAAE,WAAW,EAAE,CAAC;QAC1F,MAAM,IAAI,GAAG,cAAc,CAAC;YAC1B,OAAO,EAAE,GAAG,CAAC,OAAO;YACpB,OAAO;YACP,SAAS;YACT,UAAU,EAAE,GAAG,EAAE;YACjB,GAAG;YACH,aAAa,EAAE,GAAG,EAAE,OAAO,IAAI,EAAE;YACjC,iBAAiB,EAAE,MAAM,CAAC,iBAAiB;YAC3C,KAAK;SACN,CAAC,CAAC;QACH,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;YACjC,IAAI,CAAC,GAAG,CAAC,OAAO,GAAG,CAAC,EAAE,cAAc,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;QACrD,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,GAAG,CAAC,OAAO,GAAG,CAAC,EAAE,oBAAqB,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;YACpE,IAAI,GAAG,YAAY,cAAc;gBAAE,OAAO,IAAI,CAAC;YAC/C,MAAM,GAAG,CAAC;QACZ,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;YAAS,CAAC;QACT,aAAa,CAAC,KAAK,CAAC,CAAC;QACrB,IAAI,EAAE;YAAE,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;IACvC,CAAC;AACH,CAAC;AAaD,MAAM,SAAS,GAAG,CAAC,EAAU,EAAE,EAAE,CAAC,IAAI,OAAO,CAAO,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC;AAE9E,6EAA6E;AAC7E,MAAM,CAAC,KAAK,UAAU,KAAK,CAAC,IAAqB,EAAE,IAAkB;IACnE,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,SAAS,CAAC;IACtC,MAAM,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,GAAG,EAAE,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;IAC9C,IAAI,QAAQ,GAAG,EAAE,CAAC;IAClB,OAAO,CAAC,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC;QAC7B,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,WAAW,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;YACtE,IAAI,CAAC,KAAK,CAAC,EAAE,EAAE,CAAC;gBACd,IAAI,KAAK,CAAC,MAAM,KAAK,QAAQ;oBAAE,IAAI,CAAC,GAAG,CAAC,uBAAuB,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;gBAC/E,QAAQ,GAAG,KAAK,CAAC,MAAM,CAAC;gBACxB,IAAI,IAAI,CAAC,IAAI;oBAAE,OAAO;gBACtB,MAAM,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;gBAC9B,SAAS;YACX,CAAC;YACD,QAAQ,GAAG,EAAE,CAAC;YACd,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,CAAC;YACnC,IAAI,GAAG,EAAE,CAAC;gBACR,IAAI,CAAC,GAAG,CAAC,cAAc,GAAG,CAAC,EAAE,KAAK,GAAG,CAAC,MAAM,CAAC,IAAI,KAAK,GAAG,CAAC,MAAM,CAAC,QAAQ,GAAG,CAAC,CAAC;gBAC9E,MAAM,MAAM,CAAC,GAAG,EAAE,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;gBACpD,MAAM,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,GAAG,EAAE,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC;YAChD,CAAC;YACD,IAAI,IAAI,CAAC,IAAI;gBAAE,OAAO;YACtB,IAAI,CAAC,GAAG;gBAAE,MAAM,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACrC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,GAAG,CAAC,UAAW,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;YAC7C,IAAI,IAAI,CAAC,IAAI;gBAAE,MAAM,GAAG,CAAC;YACzB,MAAM,KAAK,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC;QAChC,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/lib/box/proxmox.d.ts

@@ -0,0 +1,112 @@
+/**
+ * The Proxmox backend of the run box: one fresh unprivileged LXC per run,
+ * linked-cloned from a template CT, on the isolated box bridge, destroyed after.
+ *
+ * It talks to the Proxmox API with a POOL-SCOPED token (least privilege: it
+ * can clone, configure, start, stop and destroy guests of ONE pool, and read
+ * node memory, one storage's fill and the thin pools' fill — nothing else;
+ * host side in `my server` docs/RUNBOX.md, `scripts/box/setup-box-access.sh`). TLS is verified against the host's own CA, pinned by file,
+ * never `rejectUnauthorized: false`.
+ */
+export interface ProxmoxConfig {
+    /** e.g. https://10.10.0.1:8006 */
+    endpoint: string;
+    /** `user@realm!tokenid=secret` */
+    token: string;
+    /** PEM of the host CA (/etc/pve/pve-root-ca.pem). */
+    ca: string;
+    node: string;
+    /**
+     * The name the host certificate is checked against when the endpoint is an
+     * address it does not list. The founder's host cert names 192.168.1.201,
+     * `main` and `main.local.lan`, not 10.10.0.1 (read 2026-10-26), so the
+     * provisioner connects to 10.10.0.1 and verifies the cert as `main`.
+     */
+    serverName?: string;
+}
+export interface ProxmoxApi {
+    get<T>(path: string): Promise<T>;
+    post<T>(path: string, params?: Record<string, string | number>): Promise<T>;
+    put<T>(path: string, params?: Record<string, string | number>): Promise<T>;
+    del<T>(path: string, params?: Record<string, string | number>): Promise<T>;
+}
+export declare class ProxmoxError extends Error {
+    readonly status: number;
+    constructor(status: number, message: string);
+}
+export declare function createProxmoxApi(cfg: ProxmoxConfig): ProxmoxApi;
+export interface BoxHostConfig {
+    /** VMID of the template CT (a Proxmox template, linked clones only). */
+    templateVmid: number;
+    /** The pool every box is created in; the token can touch nothing else. */
+    pool: string;
+    /** Storage the template and its linked clones live on (the fill guard reads it). */
+    storage: string;
+    /**
+     * The LVM thin pool behind `storage`, `vg/lv` (e.g. `pve/data`), for the
+     * metadata guard. Unset = no metadata guard (said once at start).
+     */
+    thinpool?: string;
+    /** The isolated box bridge. */
+    bridge: string;
+    /** First three octets of the box subnet, e.g. "10.20.0". */
+    subnetPrefix: string;
+    /** VMIDs reserved for boxes, inclusive. */
+    vmidMin: number;
+    vmidMax: number;
+    cpuunits: number;
+}
+/** Every box carries this tag; the reaper touches nothing without it. */
+export declare const BOX_TAG = "synap-box";
+export interface BoxHandle {
+    vmid: number;
+    ip: string;
+}
+export interface HostReading {
+    memAvailableMb: number;
+    storageUsedPct: number;
+    /** Thin pool metadata fill; null only when no `thinpool` is configured (never for a failed read: that throws). */
+    metaUsedPct: number | null;
+}
+export interface ListedBox {
+    vmid: number;
+    name: string;
+}
+export interface BoxBackend {
+    readHost(): Promise<HostReading>;
+    /** Clone, size, attach to the bridge and start a box for one run. */
+    create(runId: string, limits: {
+        cpus: number;
+        memoryMb: number;
+    }): Promise<BoxHandle>;
+    /** Stop and destroy; idempotent (a box already gone is success). */
+    destroy(vmid: number): Promise<void>;
+    /** Every tagged box in the pool (the reaper destroys those no run holds). */
+    list(): Promise<ListedBox[]>;
+}
+/** The IP a box gets on the bridge, by its VMID slot (.10 upward). */
+export declare function boxIpFor(cfg: BoxHostConfig, vmid: number): string;
+type ClusterGuest = {
+    vmid?: number;
+    type?: string;
+    name?: string;
+    pool?: string;
+    tags?: string;
+    template?: number;
+};
+/**
+ * The boxes the reaper may destroy: guests of the box pool, in the box VMID
+ * range, tagged `synap-box`, never the template. Read from /cluster/resources
+ * (VM.Audit + Pool.Audit on the pool), not the deprecated GET /pools/{id}.
+ */
+export declare function boxesOf(cfg: BoxHostConfig, guests: readonly ClusterGuest[]): ListedBox[];
+type ThinPool = {
+    lv: string;
+    vg: string;
+    metadata_size: number;
+    metadata_used: number;
+};
+/** Metadata fill of `vg/lv`; throws when the pool is not listed (a missing reading is never "fine"). */
+export declare function thinMetaPct(spec: string, pools: readonly ThinPool[]): number;
+export declare function createProxmoxBackend(api: ProxmoxApi, node: string, cfg: BoxHostConfig): BoxBackend;
+export {};

package/dist/lib/box/proxmox.js

@@ -0,0 +1,211 @@
+/**
+ * The Proxmox backend of the run box: one fresh unprivileged LXC per run,
+ * linked-cloned from a template CT, on the isolated box bridge, destroyed after.
+ *
+ * It talks to the Proxmox API with a POOL-SCOPED token (least privilege: it
+ * can clone, configure, start, stop and destroy guests of ONE pool, and read
+ * node memory, one storage's fill and the thin pools' fill — nothing else;
+ * host side in `my server` docs/RUNBOX.md, `scripts/box/setup-box-access.sh`). TLS is verified against the host's own CA, pinned by file,
+ * never `rejectUnauthorized: false`.
+ */
+import https from "node:https";
+export class ProxmoxError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = "ProxmoxError";
+    }
+}
+export function createProxmoxApi(cfg) {
+    const base = new URL("/api2/json", cfg.endpoint);
+    const agent = new https.Agent({ ca: cfg.ca, keepAlive: true, ...(cfg.serverName ? { servername: cfg.serverName } : {}) });
+    function request(method, path, params) {
+        const url = new URL(base.pathname + path, base);
+        let body;
+        const form = params
+            ? new URLSearchParams(Object.entries(params).map(([k, v]) => [k, String(v)])).toString()
+            : "";
+        if (method === "GET" || method === "DELETE") {
+            if (form)
+                url.search = form;
+        }
+        else {
+            body = form;
+        }
+        return new Promise((resolve, reject) => {
+            const req = https.request(url, {
+                method,
+                agent,
+                headers: {
+                    Authorization: `PVEAPIToken=${cfg.token}`,
+                    ...(body !== undefined
+                        ? { "Content-Type": "application/x-www-form-urlencoded", "Content-Length": Buffer.byteLength(body) }
+                        : {}),
+                },
+                timeout: 30_000,
+            }, (res) => {
+                const chunks = [];
+                res.on("data", (c) => chunks.push(c));
+                res.on("end", () => {
+                    const text = Buffer.concat(chunks).toString("utf8");
+                    if ((res.statusCode ?? 500) >= 400) {
+                        reject(new ProxmoxError(res.statusCode ?? 500, `${method} ${path}: HTTP ${res.statusCode} ${res.statusMessage ?? ""} ${text.slice(0, 300)}`.trim()));
+                        return;
+                    }
+                    try {
+                        resolve(JSON.parse(text).data);
+                    }
+                    catch {
+                        reject(new ProxmoxError(res.statusCode ?? 500, `${method} ${path}: not JSON`));
+                    }
+                });
+            });
+            req.on("timeout", () => req.destroy(new Error(`${method} ${path}: timed out`)));
+            req.on("error", reject);
+            if (body !== undefined)
+                req.write(body);
+            req.end();
+        });
+    }
+    return {
+        get: (p) => request("GET", p),
+        post: (p, params) => request("POST", p, params),
+        put: (p, params) => request("PUT", p, params),
+        del: (p, params) => request("DELETE", p, params),
+    };
+}
+/** Every box carries this tag; the reaper touches nothing without it. */
+export const BOX_TAG = "synap-box";
+/** The IP a box gets on the bridge, by its VMID slot (.10 upward). */
+export function boxIpFor(cfg, vmid) {
+    return `${cfg.subnetPrefix}.${10 + (vmid - cfg.vmidMin)}`;
+}
+/**
+ * The boxes the reaper may destroy: guests of the box pool, in the box VMID
+ * range, tagged `synap-box`, never the template. Read from /cluster/resources
+ * (VM.Audit + Pool.Audit on the pool), not the deprecated GET /pools/{id}.
+ */
+export function boxesOf(cfg, guests) {
+    return guests
+        .filter((g) => g.type === "lxc" && typeof g.vmid === "number" && g.pool === cfg.pool)
+        .filter((g) => g.vmid !== cfg.templateVmid && !g.template)
+        .filter((g) => g.vmid >= cfg.vmidMin && g.vmid <= cfg.vmidMax)
+        .filter((g) => (g.tags ?? "").split(/[;, ]/).includes(BOX_TAG))
+        .map((g) => ({ vmid: g.vmid, name: g.name ?? "" }));
+}
+/** Metadata fill of `vg/lv`; throws when the pool is not listed (a missing reading is never "fine"). */
+export function thinMetaPct(spec, pools) {
+    const [vg, lv] = spec.split("/");
+    const p = pools.find((t) => t.vg === vg && t.lv === lv);
+    if (!p)
+        throw new Error(`thin pool ${spec} not found on the node`);
+    return p.metadata_size > 0 ? (p.metadata_used / p.metadata_size) * 100 : 100;
+}
+export function createProxmoxBackend(api, node, cfg) {
+    const n = encodeURIComponent(node);
+    async function waitTask(upid, timeoutMs = 120_000) {
+        const deadline = Date.now() + timeoutMs;
+        for (;;) {
+            const t = await api.get(`/nodes/${n}/tasks/${encodeURIComponent(upid)}/status`);
+            if (t.status === "stopped") {
+                if (t.exitstatus !== "OK")
+                    throw new ProxmoxError(500, `task ${upid} ended: ${t.exitstatus}`);
+                return;
+            }
+            if (Date.now() > deadline)
+                throw new ProxmoxError(504, `task ${upid} still running after ${timeoutMs} ms`);
+            await new Promise((r) => setTimeout(r, 1000));
+        }
+    }
+    /**
+     * The first VMID of the box range that is free cluster-wide. /cluster/resources
+     * shows only the guests this token may audit (the pool), so each candidate is
+     * confirmed by /cluster/nextid?vmid=N, which checks every guest.
+     */
+    async function freeVmid() {
+        const seen = new Set((await api.get(`/cluster/resources?type=vm`)).map((g) => g.vmid).filter((v) => typeof v === "number"));
+        for (let id = cfg.vmidMin; id <= cfg.vmidMax; id++) {
+            if (seen.has(id))
+                continue;
+            try {
+                await api.get(`/cluster/nextid?vmid=${id}`);
+                return id;
+            }
+            catch (err) {
+                if (err instanceof ProxmoxError && err.status === 400)
+                    continue; // "VM <id> already exists"
+                throw err;
+            }
+        }
+        return null;
+    }
+    async function destroy(vmid) {
+        try {
+            const st = await api.get(`/nodes/${n}/lxc/${vmid}/status/current`);
+            if (st.status === "running") {
+                await waitTask(await api.post(`/nodes/${n}/lxc/${vmid}/status/stop`));
+            }
+            await waitTask(await api.del(`/nodes/${n}/lxc/${vmid}`, { purge: 1, "destroy-unreferenced-disks": 1 }));
+        }
+        catch (err) {
+            // A box already gone is the outcome we want.
+            if (err instanceof ProxmoxError && (err.status === 404 || /does not exist/.test(err.message)))
+                return;
+            throw err;
+        }
+    }
+    return {
+        async readHost() {
+            // `memory.free` here is MemFree; total - used is MemAvailable (read on
+            // the host 2026-10-26: within 1% of /proc/meminfo MemAvailable).
+            const status = await api.get(`/nodes/${n}/status`);
+            const st = await api.get(`/nodes/${n}/storage/${encodeURIComponent(cfg.storage)}/status`);
+            const metaUsedPct = cfg.thinpool
+                ? thinMetaPct(cfg.thinpool, await api.get(`/nodes/${n}/disks/lvmthin`))
+                : null;
+            return {
+                memAvailableMb: Math.floor((status.memory.total - status.memory.used) / 1024 / 1024),
+                storageUsedPct: st.total > 0 ? (st.used / st.total) * 100 : 100,
+                metaUsedPct,
+            };
+        },
+        async create(runId, limits) {
+            const vmid = await freeVmid();
+            if (vmid === null)
+                throw new ProxmoxError(503, `no free VMID in ${cfg.vmidMin}-${cfg.vmidMax}`);
+            const ip = boxIpFor(cfg, vmid);
+            const upid = await api.post(`/nodes/${n}/lxc/${cfg.templateVmid}/clone`, {
+                newid: vmid,
+                hostname: `box-${runId.slice(0, 8)}`,
+                pool: cfg.pool,
+                full: 0,
+                description: `synap box run ${runId}`,
+            });
+            await waitTask(upid);
+            try {
+                await api.put(`/nodes/${n}/lxc/${vmid}/config`, {
+                    cores: limits.cpus,
+                    memory: limits.memoryMb,
+                    swap: 0,
+                    cpuunits: cfg.cpuunits,
+                    // No gateway: the box's only reachable neighbour is the provisioner.
+                    net0: `name=eth0,bridge=${cfg.bridge},ip=${ip}/24,firewall=0`,
+                    tags: `${BOX_TAG};run-${runId.slice(0, 8)}`,
+                    onboot: 0,
+                });
+                await waitTask(await api.post(`/nodes/${n}/lxc/${vmid}/status/start`));
+            }
+            catch (err) {
+                await destroy(vmid).catch(() => undefined);
+                throw err;
+            }
+            return { vmid, ip };
+        },
+        destroy,
+        async list() {
+            return boxesOf(cfg, await api.get(`/cluster/resources?type=vm`));
+        },
+    };
+}
+//# sourceMappingURL=proxmox.js.map