@synap-core/cli 1.12.2 → 1.13.1-next.20261102.ec3d166

package/dist/lib/box/job-server.js

@@ -0,0 +1,250 @@
+/**
+ * What the box talks to: a small HTTP server on the provisioner's bridge
+ * address. The box holds no token: its identity IS its address on the isolated
+ * bridge (the provisioner assigned it), so a request is answered only for the
+ * run that address was given to.
+ *
+ *   GET  /job          the script, its packages, parameters and wall clock
+ *   POST /phase        {"phase":"run"}: packages are in, egress narrows to the
+ *                      declared hosts (one way: never back to setup)
+ *   POST /log          a chunk of the run's stdout+stderr
+ *   PUT  /out/<path>   one /out file, streamed to staging under the caps
+ *   POST /done         {"exitCode", "installedPackages"}
+ */
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import http from "node:http";
+import path from "node:path";
+import { LogCapture } from "./evidence.js";
+/** BOX-CONTRACT v1: at most 20 files per run. */
+export const MAX_OUT_FILES = 20;
+const MAX_BODY_BYTES = 1024 * 1024;
+/**
+ * A safe relative path for an /out file, or null. Each segment is decoded
+ * once; no empty, `.`, `..`, NUL or separator inside a segment.
+ */
+export function safeOutPath(urlPath) {
+    const raw = urlPath.replace(/^\/out\//, "");
+    // 500 = the pod's finish `files[].path` limit.
+    if (!raw || raw.length > 500)
+        return null;
+    const segments = [];
+    for (const enc of raw.split("/")) {
+        let seg;
+        try {
+            seg = decodeURIComponent(enc);
+        }
+        catch {
+            return null;
+        }
+        if (!seg || seg === "." || seg === ".." || /[\0/\\]/.test(seg) || seg.length > 255)
+            return null;
+        segments.push(seg);
+    }
+    return segments.length <= 16 ? segments.join("/") : null;
+}
+/** The job document the box runner reads. */
+export function jobFor(run) {
+    const s = run.script;
+    return {
+        runId: run.id,
+        language: s.language,
+        entrypoint: s.entrypoint,
+        code: s.code,
+        packages: s.packages,
+        parameters: run.parameters ?? null,
+        wallSeconds: s.limits.wallSeconds,
+    };
+}
+export class BoxRegistry {
+    stagingRoot;
+    boxes = new Map();
+    /** Called once per box and event (the provisioner sets it per run: its clocks hang on it). */
+    onEvent = () => { };
+    constructor(stagingRoot) {
+        this.stagingRoot = stagingRoot;
+    }
+    register(ip, run) {
+        let finish;
+        const done = new Promise((r) => (finish = r));
+        const outDir = path.join(this.stagingRoot, run.id);
+        fs.rmSync(outDir, { recursive: true, force: true });
+        fs.mkdirSync(outDir, { recursive: true, mode: 0o700 });
+        const box = {
+            run,
+            phase: "setup",
+            log: new LogCapture(),
+            blocked: [],
+            outDir,
+            outBytes: 0,
+            outFiles: [],
+            jobFetched: false,
+            done,
+            finish,
+        };
+        this.boxes.set(ip, box);
+        return box;
+    }
+    /** Forget the box and drop its staged files. */
+    unregister(ip) {
+        const box = this.boxes.get(ip);
+        this.boxes.delete(ip);
+        if (box)
+            fs.rmSync(box.outDir, { recursive: true, force: true });
+    }
+    get(ip) {
+        return this.boxes.get(ip);
+    }
+    policyFor(ip) {
+        const b = this.boxes.get(ip);
+        return b ? { phase: b.phase, runHosts: b.run.script.hosts } : null;
+    }
+    recordBlock(ip, block) {
+        this.boxes.get(ip)?.blocked.push(block);
+    }
+    markJobFetched(ip) {
+        const b = this.boxes.get(ip);
+        if (!b || b.jobFetched)
+            return;
+        b.jobFetched = true;
+        this.onEvent(b.run, "job");
+    }
+    enterRunPhase(ip) {
+        const b = this.boxes.get(ip);
+        if (!b || b.phase === "run")
+            return;
+        b.phase = "run";
+        this.onEvent(b.run, "run");
+    }
+}
+function readBody(req, cap = MAX_BODY_BYTES) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let n = 0;
+        req.on("data", (c) => {
+            n += c.length;
+            if (n > cap) {
+                reject(new Error("body too large"));
+                req.destroy();
+                return;
+            }
+            chunks.push(c);
+        });
+        req.on("end", () => resolve(Buffer.concat(chunks)));
+        req.on("error", reject);
+    });
+}
+function json(res, status, body) {
+    if (status === 204) {
+        res.writeHead(204).end();
+        return;
+    }
+    res.writeHead(status, { "content-type": "application/json" }).end(JSON.stringify(body));
+}
+export function parseReport(raw) {
+    const body = (raw && typeof raw === "object" ? raw : {});
+    const exitCode = typeof body.exitCode === "number" && Number.isInteger(body.exitCode) ? body.exitCode : null;
+    const installedPackages = Array.isArray(body.installedPackages)
+        ? body.installedPackages
+            .filter((p) => p && typeof p.name === "string" && typeof p.version === "string" && p.name && p.version)
+            .slice(0, 2000)
+            .map((p) => ({
+            name: p.name,
+            version: p.version,
+            manager: p.manager === "npm" ? "npm" : "pip",
+        }))
+        : [];
+    return { exitCode, installedPackages };
+}
+export function createJobServer(registry) {
+    return http.createServer(async (req, res) => {
+        const ip = (req.socket.remoteAddress ?? "").replace(/^::ffff:/, "");
+        const box = registry.get(ip);
+        if (!box)
+            return json(res, 403, { error: "not a running box" });
+        const url = new URL(req.url ?? "/", "http://box");
+        try {
+            if (req.method === "GET" && url.pathname === "/job") {
+                registry.markJobFetched(ip);
+                return json(res, 200, jobFor(box.run));
+            }
+            if (req.method === "POST" && url.pathname === "/phase") {
+                const body = JSON.parse((await readBody(req)).toString("utf8") || "{}");
+                if (body.phase !== "run")
+                    return json(res, 400, { error: "the only move is to the run phase" });
+                registry.enterRunPhase(ip);
+                return json(res, 200, { phase: "run" });
+            }
+            if (req.method === "POST" && url.pathname === "/log") {
+                req.on("data", (c) => box.log.append(c));
+                req.on("end", () => json(res, 204));
+                return;
+            }
+            if (req.method === "PUT" && url.pathname.startsWith("/out/")) {
+                const rel = safeOutPath(url.pathname);
+                if (!rel)
+                    return json(res, 400, { error: "bad out path" });
+                if (box.outFiles.length >= MAX_OUT_FILES)
+                    return json(res, 413, { error: `more than ${MAX_OUT_FILES} files` });
+                const cap = box.run.script.limits.outMb * 1024 * 1024;
+                const dest = path.join(box.outDir, rel);
+                fs.mkdirSync(path.dirname(dest), { recursive: true });
+                const hash = createHash("sha256");
+                const file = fs.createWriteStream(dest, { mode: 0o600 });
+                let size = 0;
+                let over = false;
+                // Over the cap or cut off mid-upload: no partial file is kept, and the
+                // answer goes out only once it is gone.
+                const abort = (status, error) => {
+                    if (over)
+                        return;
+                    over = true;
+                    file.destroy();
+                    file.once("close", () => {
+                        fs.rmSync(dest, { force: true });
+                        if (!res.headersSent)
+                            json(res, status, { error });
+                        req.destroy();
+                    });
+                };
+                // A write that fails (disk full), or a pending write cut short by the
+                // destroy above: one answer either way, never an unhandled 'error'
+                // (which would crash the provisioner and leave the box unanswered).
+                file.on("error", () => abort(500, "could not stage the file"));
+                req.on("data", (c) => {
+                    if (over)
+                        return;
+                    size += c.length;
+                    if (box.outBytes + size > cap)
+                        return abort(413, `/out exceeds ${box.run.script.limits.outMb} MB`);
+                    hash.update(c);
+                    file.write(c);
+                });
+                req.on("end", () => {
+                    if (over)
+                        return;
+                    file.end(() => {
+                        box.outBytes += size;
+                        box.outFiles.push({ path: rel, size, sha256: hash.digest("hex") });
+                        json(res, 201, { path: rel, size });
+                    });
+                });
+                req.on("close", () => {
+                    if (!req.complete)
+                        abort(400, "upload cut off");
+                });
+                return;
+            }
+            if (req.method === "POST" && url.pathname === "/done") {
+                box.finish(parseReport(JSON.parse((await readBody(req)).toString("utf8"))));
+                return json(res, 200, { ok: true });
+            }
+            return json(res, 404, { error: "no such door" });
+        }
+        catch (err) {
+            if (!res.headersSent)
+                json(res, 400, { error: err.message });
+        }
+    });
+}
+//# sourceMappingURL=job-server.js.map

package/dist/lib/box/job-server.js.map

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

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

@@ -0,0 +1,83 @@
+/**
+ * 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 type { BoxRegistry } from "./job-server.js";
+import type { BoxBackend, HostReading } from "./proxmox.js";
+import { type BoxHub, type BoxLimits, type FinishBody, type LeasedRun } from "./wire.js";
+export interface HostGuards {
+    /** Wait unless the host has at least this much MemAvailable. */
+    minMemAvailableMb: number;
+    /** Wait while the box storage (thin pool data) is fuller than this. */
+    maxStorageUsedPct: number;
+    /** Wait while the thin pool's metadata is fuller than this. */
+    maxMetaUsedPct: number;
+}
+/** Phase 0 on the founder's host: swap is full, so the margin is RAM only. */
+export declare const DEFAULT_GUARDS: HostGuards;
+/**
+ * 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 declare const PHASE0_CAPS: BoxLimits;
+/** A box that has not asked for its job by then did not start: INFRA, not the script's verdict. */
+export declare const BOOT_SECONDS = 180;
+/** The declared packages must be installed by then; past it the run timed out in setup. */
+export declare const SETUP_SECONDS = 900;
+/** Limits cut to the phase 0 caps, and the names of the ones that were cut. */
+export declare function clampLimits(l: BoxLimits): {
+    limits: BoxLimits;
+    clamped: string[];
+};
+export declare function checkGuards(r: HostReading, g: HostGuards): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+export interface ProvisionerDeps {
+    hub: BoxHub;
+    backend: BoxBackend;
+    registry: BoxRegistry;
+    log: (line: string) => void;
+    now?: () => number;
+    /** Destroy attempts before leaving a box to the reaper. */
+    destroyAttempts?: number;
+    /** The provisioner is stopping: end the current run (box destroyed, finish INFRA). */
+    signal?: AbortSignal;
+    /** Clock overrides (tests). */
+    bootMs?: number;
+    setupMs?: number;
+}
+export declare function mimeOf(file: string): string;
+/** Destroy every tagged box no run holds. Returns the VMIDs destroyed. */
+export declare function reap(backend: BoxBackend, held: ReadonlySet<number>, log: (l: string) => void): Promise<number[]>;
+/**
+ * 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 declare function runOne(leasedRun: LeasedRun, deps: ProvisionerDeps): Promise<FinishBody | null>;
+export interface ServeOptions {
+    guards: HostGuards;
+    /** Wait between empty leases. */
+    idleMs: number;
+    /** Wait between guard readings while the host is short. */
+    guardWaitMs: number;
+    once?: boolean;
+    signal?: AbortSignal;
+    sleep?: (ms: number) => Promise<void>;
+}
+/** Lease and work runs until the signal aborts (or one pass with `once`). */
+export declare function serve(deps: ProvisionerDeps, opts: ServeOptions): Promise<void>;

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