@geminixiang/mikan 1.0.0-beta.2 → 1.0.0-beta.20

package/dist/sandbox/gondolin-worker-client.js

@@ -0,0 +1,325 @@
+import { spawn } from "node:child_process";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { SandboxError } from "./errors.js";
+import { gondolinInventory } from "./gondolin-inventory.js";
+/**
+ * The runtime is gone and the command never reached it (the session socket
+ * refused the connection) — safe to recreate the runtime and retry.
+ */
+export class GondolinRuntimeGoneError extends Error {
+}
+/** The runtime died with the command in flight — not safe to retry blindly. */
+export class GondolinRuntimeInterruptedError extends Error {
+}
+function defaultSpawnProcess(command, args) {
+    return spawn(command, args, { detached: true, stdio: ["ignore", "pipe", "pipe"] });
+}
+async function defaultConnect(socketPath, callbacks) {
+    const { connectToSession } = await import("@earendil-works/gondolin");
+    return connectToSession(socketPath, callbacks);
+}
+function abortError() {
+    return new Error("Error: command aborted");
+}
+/**
+ * A command may quietly work for a long time, but a session that produces no
+ * frame at all for this long is indistinguishable from one wedged on dead
+ * storage (a hung NFS mount under the workspace blocks guest I/O forever) —
+ * kill it and say so instead of hanging the run.
+ */
+const EXEC_IDLE_TIMEOUT_MS = 10 * 60 * 1000;
+/**
+ * Run one command through a fresh session connection — the shared state
+ * machine for both transports. Closing the connection (abort, timeout, or the
+ * far side dying) kills the in-flight guest process.
+ */
+export async function execOverSessionConnect(connect, command, options = {}) {
+    if (options.signal?.aborted)
+        throw abortError();
+    const idleTimeoutMs = options.idleTimeoutMs ?? EXEC_IDLE_TIMEOUT_MS;
+    return await new Promise((resolve, reject) => {
+        let stdout = "";
+        let stderr = "";
+        let received = false;
+        let settled = false;
+        let client;
+        let idleTimer;
+        const settle = (fn) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(idleTimer);
+            options.signal?.removeEventListener("abort", onAbort);
+            fn();
+        };
+        const onAbort = () => settle(() => {
+            client?.close();
+            reject(abortError());
+        });
+        const onIdle = () => settle(() => {
+            client?.close();
+            reject(new GondolinRuntimeInterruptedError(`no session activity for ${Math.round(idleTimeoutMs / 1000)}s — killed the command ` +
+                `(guest I/O hangs when the workspace sits on a dead mount; check the worker's workspace health)`));
+        });
+        const armIdleTimer = () => {
+            if (idleTimeoutMs <= 0 || settled)
+                return;
+            clearTimeout(idleTimer);
+            idleTimer = setTimeout(onIdle, idleTimeoutMs);
+            idleTimer.unref?.();
+        };
+        armIdleTimer();
+        const callbacks = {
+            onJson: (message) => {
+                received = true;
+                armIdleTimer();
+                if (message.type === "exec_response" && message.id === 1) {
+                    settle(() => {
+                        client?.close();
+                        resolve({
+                            stdout,
+                            stderr,
+                            code: typeof message.exit_code === "number" ? message.exit_code : 1,
+                        });
+                    });
+                }
+                else if (message.type === "error") {
+                    settle(() => {
+                        client?.close();
+                        reject(new Error(`Error: Gondolin exec failed (${message.code}): ${message.message}`));
+                    });
+                }
+            },
+            onBinary: (frame) => {
+                received = true;
+                armIdleTimer();
+                const tag = frame.readUInt8(0);
+                const data = frame.subarray(5).toString("utf8");
+                if (tag === 1)
+                    stdout += data;
+                else
+                    stderr += data;
+            },
+            onClose: (error) => {
+                settle(() => {
+                    const detail = error?.message ?? "connection closed before the command finished";
+                    const code = error?.code;
+                    if (!received && (code === "ENOENT" || code === "ECONNREFUSED")) {
+                        reject(new GondolinRuntimeGoneError(detail));
+                    }
+                    else {
+                        reject(new GondolinRuntimeInterruptedError(detail));
+                    }
+                });
+            },
+        };
+        options.signal?.addEventListener("abort", onAbort, { once: true });
+        Promise.resolve(connect(callbacks))
+            .then((created) => {
+            client = created;
+            if (settled) {
+                created.close();
+                return;
+            }
+            created.send({
+                type: "exec",
+                id: 1,
+                cmd: "/bin/sh",
+                argv: ["-c", command],
+                env: Object.entries(options.env ?? {}).map(([key, value]) => `${key}=${value}`),
+                cwd: "/workspace",
+            });
+        })
+            .catch((err) => settle(() => reject(new GondolinRuntimeGoneError(err instanceof Error ? err.message : String(err)))));
+    });
+}
+/** Workers self-stop once no mikan has refreshed the heartbeat for this long. */
+const WORKER_HEARTBEAT_STALE_MS = 45 * 60 * 1000;
+class GondolinWorkerClient {
+    constructor() {
+        this.spawnProcess = defaultSpawnProcess;
+        this.connectImpl = defaultConnect;
+        this.killImpl = (pid, signal) => process.kill(pid, signal);
+        this.handshakeTimeoutMs = 120_000;
+        this.stopWaitMs = 15_000;
+        this.stopPollIntervalMs = 100;
+    }
+    configure(overrides) {
+        this.spawnProcess = overrides?.spawnProcess ?? defaultSpawnProcess;
+        this.connectImpl = overrides?.connect ?? defaultConnect;
+        this.killImpl = overrides?.kill ?? ((pid, signal) => process.kill(pid, signal));
+        this.handshakeTimeoutMs = overrides?.handshakeTimeoutMs ?? 120_000;
+        this.stopWaitMs = overrides?.stopWaitMs ?? 15_000;
+        this.stopPollIntervalMs = overrides?.stopPollIntervalMs ?? 100;
+    }
+    /** Adopt a surviving local worker or spawn a fresh one for the spec. */
+    async ensure(instanceId, spec) {
+        const adopted = await this.adopt(instanceId, spec.fingerprint);
+        if (adopted)
+            return adopted;
+        return this.spawn({
+            instanceId,
+            image: spec.image,
+            mounts: spec.mounts,
+            cpus: spec.vmCpus,
+            memory: spec.memory,
+            fingerprint: spec.fingerprint,
+            inventoryDir: gondolinInventory.directory() ?? join(homedir(), ".mikan", "gondolin-runtimes"),
+            heartbeatStaleMs: WORKER_HEARTBEAT_STALE_MS,
+        });
+    }
+    /** Whether the runtime's worker process is still alive. */
+    async isRuntimeAlive(handle) {
+        return this.isPidAlive(handle.workerPid);
+    }
+    /** Spawn a detached worker for the config and wait for its ready handshake. */
+    async spawn(config) {
+        const entry = fileURLToPath(new URL("./gondolin-worker-main.js", import.meta.url));
+        const child = this.spawnProcess(process.execPath, [entry, JSON.stringify(config)]);
+        const handshake = await this.readHandshake(child);
+        if (!handshake.ready || !handshake.sessionId || !handshake.socketPath) {
+            throw new SandboxError(`Error: Gondolin worker failed to start: ${handshake.error ?? "no session in handshake"}`);
+        }
+        child.stdout?.destroy();
+        child.stderr?.destroy();
+        child.unref();
+        return {
+            sessionId: handshake.sessionId,
+            instanceId: config.instanceId,
+            socketPath: handshake.socketPath,
+            workerPid: handshake.workerPid ?? child.pid,
+            fingerprint: config.fingerprint,
+        };
+    }
+    /**
+     * Adopt a runtime a previous mikan left running: newest live record for the
+     * key whose fingerprint still matches and whose session answers a probe.
+     * Anything stale — drifted fingerprint, unresponsive session — is stopped so
+     * the caller can spawn fresh.
+     */
+    async adopt(instanceId, fingerprint) {
+        const record = await gondolinInventory.findAdoptable(instanceId);
+        if (!record?.socketPath)
+            return undefined;
+        const handle = {
+            sessionId: record.sessionId,
+            instanceId,
+            socketPath: record.socketPath,
+            workerPid: record.ownerPid,
+            fingerprint: record.fingerprint ?? "",
+        };
+        if (record.fingerprint !== fingerprint) {
+            await this.stop(handle);
+            return undefined;
+        }
+        try {
+            await this.exec(handle, "true", { signal: AbortSignal.timeout(5000) });
+        }
+        catch {
+            await this.stop(handle);
+            return undefined;
+        }
+        return handle;
+    }
+    /**
+     * Stop a worker and wait for it to clean up after itself; escalate to
+     * SIGKILL and reap its leftovers if it will not die.
+     */
+    async stop(handle) {
+        if (this.isPidAlive(handle.workerPid)) {
+            this.signal(handle.workerPid, "SIGTERM");
+            if (!(await this.waitForExit(handle.workerPid, this.stopWaitMs))) {
+                this.signal(handle.workerPid, "SIGKILL");
+                await this.waitForExit(handle.workerPid, 2000);
+            }
+        }
+        await gondolinInventory.reapSession(handle.sessionId);
+    }
+    /** Whether the worker process behind a handle is still alive. */
+    isWorkerAlive(handle) {
+        return this.isPidAlive(handle.workerPid);
+    }
+    /**
+     * Run one command over a dedicated session IPC connection. Aborting (or the
+     * caller's timeout signal firing) destroys the connection, which kills the
+     * in-flight guest process.
+     */
+    async exec(handle, command, options = {}) {
+        return execOverSessionConnect((callbacks) => this.connectImpl(handle.socketPath, callbacks), command, options);
+    }
+    signal(pid, signal) {
+        try {
+            this.killImpl(pid, signal);
+        }
+        catch {
+            // already gone
+        }
+    }
+    isPidAlive(pid) {
+        try {
+            this.killImpl(pid, 0);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async waitForExit(pid, waitMs) {
+        const deadline = Date.now() + waitMs;
+        while (this.isPidAlive(pid)) {
+            if (Date.now() >= deadline)
+                return false;
+            await new Promise((resolve) => setTimeout(resolve, this.stopPollIntervalMs));
+        }
+        return true;
+    }
+    readHandshake(child) {
+        return new Promise((resolve, reject) => {
+            let buffer = "";
+            let stderr = "";
+            let settled = false;
+            const settle = (fn) => {
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                fn();
+            };
+            const timer = setTimeout(() => {
+                settle(() => {
+                    child.kill("SIGKILL");
+                    reject(new SandboxError(`Error: Gondolin worker did not become ready within ${this.handshakeTimeoutMs}ms${stderr ? `: ${stderr.trim()}` : ""}`));
+                });
+            }, this.handshakeTimeoutMs);
+            child.stdout?.on("data", (chunk) => {
+                buffer += chunk.toString("utf8");
+                const newline = buffer.indexOf("\n");
+                if (newline < 0)
+                    return;
+                const line = buffer.slice(0, newline);
+                settle(() => {
+                    try {
+                        resolve(JSON.parse(line));
+                    }
+                    catch {
+                        child.kill("SIGKILL");
+                        reject(new SandboxError(`Error: invalid Gondolin worker handshake: ${line}`));
+                    }
+                });
+            });
+            child.stderr?.on("data", (chunk) => {
+                stderr += chunk.toString("utf8");
+            });
+            child.once("close", (code) => {
+                settle(() => reject(new SandboxError(`Error: Gondolin worker exited before becoming ready (code ${code})${stderr ? `: ${stderr.trim()}` : ""}`)));
+            });
+            child.once("error", (error) => {
+                settle(() => reject(new SandboxError(`Error: failed to spawn Gondolin worker: ${error.message}`)));
+            });
+        });
+    }
+}
+export const gondolinWorkers = new GondolinWorkerClient();
+//# sourceMappingURL=gondolin-worker-client.js.map

package/dist/sandbox/gondolin-worker-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gondolin-worker-client.js","sourceRoot":"","sources":["../../src/sandbox/gondolin-worker-client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAC3C,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,iBAAiB,EAA8B,MAAM,yBAAyB,CAAC;AA+CxF;;;GAGG;AACH,MAAM,OAAO,wBAAyB,SAAQ,KAAK;CAAG;AAEtD,+EAA+E;AAC/E,MAAM,OAAO,+BAAgC,SAAQ,KAAK;CAAG;AAsC7D,SAAS,mBAAmB,CAAC,OAAe,EAAE,IAAc;IAC1D,OAAO,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;AACrF,CAAC;AAED,KAAK,UAAU,cAAc,CAC3B,UAAkB,EAClB,SAAiC;IAEjC,MAAM,EAAE,gBAAgB,EAAE,GAAG,MAAM,MAAM,CAAC,0BAA0B,CAAC,CAAC;IACtE,OAAO,gBAAgB,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;AACjD,CAAC;AAED,SAAS,UAAU;IACjB,OAAO,IAAI,KAAK,CAAC,wBAAwB,CAAC,CAAC;AAC7C,CAAC;AAED;;;;;GAKG;AACH,MAAM,oBAAoB,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAE5C;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,OAAsF,EACtF,OAAe,EACf,OAAO,GAAmF,EAAE;IAE5F,IAAI,OAAO,CAAC,MAAM,EAAE,OAAO;QAAE,MAAM,UAAU,EAAE,CAAC;IAChD,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,oBAAoB,CAAC;IACpE,OAAO,MAAM,IAAI,OAAO,CAAa,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACvD,IAAI,MAAM,GAAG,EAAE,CAAC;QAChB,IAAI,MAAM,GAAG,EAAE,CAAC;QAChB,IAAI,QAAQ,GAAG,KAAK,CAAC;QACrB,IAAI,OAAO,GAAG,KAAK,CAAC;QACpB,IAAI,MAAiC,CAAC;QACtC,IAAI,SAAqC,CAAC;QAC1C,MAAM,MAAM,GAAG,CAAC,EAAc,EAAQ,EAAE;YACtC,IAAI,OAAO;gBAAE,OAAO;YACpB,OAAO,GAAG,IAAI,CAAC;YACf,YAAY,CAAC,SAAS,CAAC,CAAC;YACxB,OAAO,CAAC,MAAM,EAAE,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;YACtD,EAAE,EAAE,CAAC;QACP,CAAC,CAAC;QACF,MAAM,OAAO,GAAG,GAAS,EAAE,CACzB,MAAM,CAAC,GAAG,EAAE;YACV,MAAM,EAAE,KAAK,EAAE,CAAC;YAChB,MAAM,CAAC,UAAU,EAAE,CAAC,CAAC;QACvB,CAAC,CAAC,CAAC;QACL,MAAM,MAAM,GAAG,GAAS,EAAE,CACxB,MAAM,CAAC,GAAG,EAAE;YACV,MAAM,EAAE,KAAK,EAAE,CAAC;YAChB,MAAM,CACJ,IAAI,+BAA+B,CACjC,2BAA2B,IAAI,CAAC,KAAK,CAAC,aAAa,GAAG,IAAI,CAAC,yBAAyB;gBAClF,gGAAgG,CACnG,CACF,CAAC;QACJ,CAAC,CAAC,CAAC;QACL,MAAM,YAAY,GAAG,GAAS,EAAE;YAC9B,IAAI,aAAa,IAAI,CAAC,IAAI,OAAO;gBAAE,OAAO;YAC1C,YAAY,CAAC,SAAS,CAAC,CAAC;YACxB,SAAS,GAAG,UAAU,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;YAC9C,SAAS,CAAC,KAAK,EAAE,EAAE,CAAC;QACtB,CAAC,CAAC;QACF,YAAY,EAAE,CAAC;QACf,MAAM,SAAS,GAA2B;YACxC,MAAM,EAAE,CAAC,OAAO,EAAE,EAAE;gBAClB,QAAQ,GAAG,IAAI,CAAC;gBAChB,YAAY,EAAE,CAAC;gBACf,IAAI,OAAO,CAAC,IAAI,KAAK,eAAe,IAAI,OAAO,CAAC,EAAE,KAAK,CAAC,EAAE,CAAC;oBACzD,MAAM,CAAC,GAAG,EAAE;wBACV,MAAM,EAAE,KAAK,EAAE,CAAC;wBAChB,OAAO,CAAC;4BACN,MAAM;4BACN,MAAM;4BACN,IAAI,EAAE,OAAO,OAAO,CAAC,SAAS,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;yBACpE,CAAC,CAAC;oBACL,CAAC,CAAC,CAAC;gBACL,CAAC;qBAAM,IAAI,OAAO,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;oBACpC,MAAM,CAAC,GAAG,EAAE;wBACV,MAAM,EAAE,KAAK,EAAE,CAAC;wBAChB,MAAM,CAAC,IAAI,KAAK,CAAC,gCAAgC,OAAO,CAAC,IAAI,MAAM,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;oBACzF,CAAC,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;YACD,QAAQ,EAAE,CAAC,KAAK,EAAE,EAAE;gBAClB,QAAQ,GAAG,IAAI,CAAC;gBAChB,YAAY,EAAE,CAAC;gBACf,MAAM,GAAG,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC;gBAC/B,MAAM,IAAI,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;gBAChD,IAAI,GAAG,KAAK,CAAC;oBAAE,MAAM,IAAI,IAAI,CAAC;;oBACzB,MAAM,IAAI,IAAI,CAAC;YACtB,CAAC;YACD,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;gBACjB,MAAM,CAAC,GAAG,EAAE;oBACV,MAAM,MAAM,GAAG,KAAK,EAAE,OAAO,IAAI,+CAA+C,CAAC;oBACjF,MAAM,IAAI,GAAI,KAA2C,EAAE,IAAI,CAAC;oBAChE,IAAI,CAAC,QAAQ,IAAI,CAAC,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,cAAc,CAAC,EAAE,CAAC;wBAChE,MAAM,CAAC,IAAI,wBAAwB,CAAC,MAAM,CAAC,CAAC,CAAC;oBAC/C,CAAC;yBAAM,CAAC;wBACN,MAAM,CAAC,IAAI,+BAA+B,CAAC,MAAM,CAAC,CAAC,CAAC;oBACtD,CAAC;gBACH,CAAC,CAAC,CAAC;YACL,CAAC;SACF,CAAC;QACF,OAAO,CAAC,MAAM,EAAE,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;QACnE,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;aAChC,IAAI,CAAC,CAAC,OAAO,EAAE,EAAE;YAChB,MAAM,GAAG,OAAO,CAAC;YACjB,IAAI,OAAO,EAAE,CAAC;gBACZ,OAAO,CAAC,KAAK,EAAE,CAAC;gBAChB,OAAO;YACT,CAAC;YACD,OAAO,CAAC,IAAI,CAAC;gBACX,IAAI,EAAE,MAAM;gBACZ,EAAE,EAAE,CAAC;gBACL,GAAG,EAAE,SAAS;gBACd,IAAI,EAAE,CAAC,IAAI,EAAE,OAAO,CAAC;gBACrB,GAAG,EAAE,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,IAAI,KAAK,EAAE,CAAC;gBAC/E,GAAG,EAAE,YAAY;aAClB,CAAC,CAAC;QACL,CAAC,CAAC;aACD,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE,CACtB,MAAM,CAAC,GAAG,EAAE,CACV,MAAM,CAAC,IAAI,wBAAwB,CAAC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CACvF,CACF,CAAC;IACN,CAAC,CAAC,CAAC;AACL,CAAC;AAED,iFAAiF;AACjF,MAAM,yBAAyB,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC;AAEjD,MAAM,oBAAoB;IAA1B;QACU,iBAAY,GAAG,mBAAmB,CAAC;QACnC,gBAAW,GAG2B,cAAc,CAAC;QACrD,aAAQ,GAAsD,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,CACpF,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QACpB,uBAAkB,GAAG,OAAO,CAAC;QAC7B,eAAU,GAAG,MAAM,CAAC;QACpB,uBAAkB,GAAG,GAAG,CAAC;IA6MnC,CAAC;IA3MC,SAAS,CAAC,SAAyC;QACjD,IAAI,CAAC,YAAY,GAAG,SAAS,EAAE,YAAY,IAAI,mBAAmB,CAAC;QACnE,IAAI,CAAC,WAAW,GAAG,SAAS,EAAE,OAAO,IAAI,cAAc,CAAC;QACxD,IAAI,CAAC,QAAQ,GAAG,SAAS,EAAE,IAAI,IAAI,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC,CAAC;QAChF,IAAI,CAAC,kBAAkB,GAAG,SAAS,EAAE,kBAAkB,IAAI,OAAO,CAAC;QACnE,IAAI,CAAC,UAAU,GAAG,SAAS,EAAE,UAAU,IAAI,MAAM,CAAC;QAClD,IAAI,CAAC,kBAAkB,GAAG,SAAS,EAAE,kBAAkB,IAAI,GAAG,CAAC;IACjE,CAAC;IAED,wEAAwE;IACxE,KAAK,CAAC,MAAM,CAAC,UAAkB,EAAE,IAAyB;QACxD,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC;QAC/D,IAAI,OAAO;YAAE,OAAO,OAAO,CAAC;QAC5B,OAAO,IAAI,CAAC,KAAK,CAAC;YAChB,UAAU;YACV,KAAK,EAAE,IAAI,CAAC,KAAK;YACjB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,IAAI,EAAE,IAAI,CAAC,MAAM;YACjB,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,WAAW,EAAE,IAAI,CAAC,WAAW;YAC7B,YAAY,EAAE,iBAAiB,CAAC,SAAS,EAAE,IAAI,IAAI,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,mBAAmB,CAAC;YAC7F,gBAAgB,EAAE,yBAAyB;SAC5C,CAAC,CAAC;IACL,CAAC;IAED,2DAA2D;IAC3D,KAAK,CAAC,cAAc,CAAC,MAA6B;QAChD,OAAO,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IAC3C,CAAC;IAED,+EAA+E;IAC/E,KAAK,CAAC,KAAK,CAAC,MAA4B;QACtC,MAAM,KAAK,GAAG,aAAa,CAAC,IAAI,GAAG,CAAC,2BAA2B,EAAE,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;QACnF,MAAM,KAAK,GAAG,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;QACnF,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC;QAClD,IAAI,CAAC,SAAS,CAAC,KAAK,IAAI,CAAC,SAAS,CAAC,SAAS,IAAI,CAAC,SAAS,CAAC,UAAU,EAAE,CAAC;YACtE,MAAM,IAAI,YAAY,CACpB,2CAA2C,SAAS,CAAC,KAAK,IAAI,yBAAyB,EAAE,CAC1F,CAAC;QACJ,CAAC;QACD,KAAK,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC;QACxB,KAAK,CAAC,MAAM,EAAE,OAAO,EAAE,CAAC;QACxB,KAAK,CAAC,KAAK,EAAE,CAAC;QACd,OAAO;YACL,SAAS,EAAE,SAAS,CAAC,SAAS;YAC9B,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,UAAU,EAAE,SAAS,CAAC,UAAU;YAChC,SAAS,EAAE,SAAS,CAAC,SAAS,IAAK,KAAK,CAAC,GAAc;YACvD,WAAW,EAAE,MAAM,CAAC,WAAW;SAChC,CAAC;IACJ,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,KAAK,CAAC,UAAkB,EAAE,WAAmB;QACjD,MAAM,MAAM,GACV,MAAM,iBAAiB,CAAC,aAAa,CAAC,UAAU,CAAC,CAAC;QACpD,IAAI,CAAC,MAAM,EAAE,UAAU;YAAE,OAAO,SAAS,CAAC;QAC1C,MAAM,MAAM,GAA0B;YACpC,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,UAAU;YACV,UAAU,EAAE,MAAM,CAAC,UAAU;YAC7B,SAAS,EAAE,MAAM,CAAC,QAAQ;YAC1B,WAAW,EAAE,MAAM,CAAC,WAAW,IAAI,EAAE;SACtC,CAAC;QACF,IAAI,MAAM,CAAC,WAAW,KAAK,WAAW,EAAE,CAAC;YACvC,MAAM,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACxB,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,WAAW,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACzE,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YACxB,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,IAAI,CAAC,MAA8D;QACvE,IAAI,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC;YACtC,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;YACzC,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC,EAAE,CAAC;gBACjE,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;gBACzC,MAAM,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;YACjD,CAAC;QACH,CAAC;QACD,MAAM,iBAAiB,CAAC,WAAW,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACxD,CAAC;IAED,iEAAiE;IACjE,aAAa,CAAC,MAAgD;QAC5D,OAAO,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IAC3C,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,IAAI,CACR,MAA6B,EAC7B,OAAe,EACf,OAAO,GAA2D,EAAE;QAEpE,OAAO,sBAAsB,CAC3B,CAAC,SAAS,EAAE,EAAE,CAAC,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,UAAU,EAAE,SAAS,CAAC,EAC7D,OAAO,EACP,OAAO,CACR,CAAC;IACJ,CAAC;IAEO,MAAM,CAAC,GAAW,EAAE,MAAsB;QAChD,IAAI,CAAC;YACH,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;QAC7B,CAAC;QAAC,MAAM,CAAC;YACP,eAAe;QACjB,CAAC;IACH,CAAC;IAEO,UAAU,CAAC,GAAW;QAC5B,IAAI,CAAC;YACH,IAAI,CAAC,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;YACtB,OAAO,IAAI,CAAC;QACd,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IAEO,KAAK,CAAC,WAAW,CAAC,GAAW,EAAE,MAAc;QACnD,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,MAAM,CAAC;QACrC,OAAO,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC;YAC5B,IAAI,IAAI,CAAC,GAAG,EAAE,IAAI,QAAQ;gBAAE,OAAO,KAAK,CAAC;YACzC,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,IAAI,CAAC,kBAAkB,CAAC,CAAC,CAAC;QAC/E,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAEO,aAAa,CAAC,KAAwB;QAC5C,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YACrC,IAAI,MAAM,GAAG,EAAE,CAAC;YAChB,IAAI,MAAM,GAAG,EAAE,CAAC;YAChB,IAAI,OAAO,GAAG,KAAK,CAAC;YACpB,MAAM,MAAM,GAAG,CAAC,EAAc,EAAQ,EAAE;gBACtC,IAAI,OAAO;oBAAE,OAAO;gBACpB,OAAO,GAAG,IAAI,CAAC;gBACf,YAAY,CAAC,KAAK,CAAC,CAAC;gBACpB,EAAE,EAAE,CAAC;YACP,CAAC,CAAC;YACF,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;gBAC5B,MAAM,CAAC,GAAG,EAAE;oBACV,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;oBACtB,MAAM,CACJ,IAAI,YAAY,CACd,sDAAsD,IAAI,CAAC,kBAAkB,KAC3E,MAAM,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,EAClC,EAAE,CACH,CACF,CAAC;gBACJ,CAAC,CAAC,CAAC;YACL,CAAC,EAAE,IAAI,CAAC,kBAAkB,CAAC,CAAC;YAC5B,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE;gBACzC,MAAM,IAAI,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;gBACjC,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;gBACrC,IAAI,OAAO,GAAG,CAAC;oBAAE,OAAO;gBACxB,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC;gBACtC,MAAM,CAAC,GAAG,EAAE;oBACV,IAAI,CAAC;wBACH,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAA4B,CAAC,CAAC;oBACvD,CAAC;oBAAC,MAAM,CAAC;wBACP,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;wBACtB,MAAM,CAAC,IAAI,YAAY,CAAC,6CAA6C,IAAI,EAAE,CAAC,CAAC,CAAC;oBAChF,CAAC;gBACH,CAAC,CAAC,CAAC;YACL,CAAC,CAAC,CAAC;YACH,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE;gBACzC,MAAM,IAAI,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;YACnC,CAAC,CAAC,CAAC;YACH,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE;gBAC3B,MAAM,CAAC,GAAG,EAAE,CACV,MAAM,CACJ,IAAI,YAAY,CACd,6DAA6D,IAAI,IAC/D,MAAM,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,EAClC,EAAE,CACH,CACF,CACF,CAAC;YACJ,CAAC,CAAC,CAAC;YACH,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE;gBAC5B,MAAM,CAAC,GAAG,EAAE,CACV,MAAM,CAAC,IAAI,YAAY,CAAC,2CAA2C,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CACrF,CAAC;YACJ,CAAC,CAAC,CAAC;QACL,CAAC,CAAC,CAAC;IACL,CAAC;CACF;AAED,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,oBAAoB,EAAE,CAAC","sourcesContent":["import { spawn } from \"node:child_process\";\nimport { homedir } from \"node:os\";\nimport { join } from \"node:path\";\nimport type { Readable } from \"node:stream\";\nimport { fileURLToPath } from \"node:url\";\nimport { SandboxError } from \"./errors.js\";\nimport { gondolinInventory, type GondolinRuntimeRecord } from \"./gondolin-inventory.js\";\nimport type { GondolinWorkerConfig, GondolinWorkerHandshake } from \"./gondolin-worker.js\";\nimport type { ExecResult } from \"./types.js\";\n\n/** A live worker-hosted runtime as seen from mikan. */\nexport interface GondolinRuntimeHandle {\n  sessionId: string;\n  instanceId: string;\n  socketPath: string;\n  workerPid: number;\n  fingerprint: string;\n  /** Fleet identity of the worker hosting the runtime (remote transport). */\n  workerName?: string;\n}\n\n/**\n * What a runtime should look like, resolved by the executor layer. `image` is\n * a local asset directory for the local transport and an image selector for\n * the remote one (resolved on the worker host).\n */\nexport interface GondolinRuntimeSpec {\n  image: string;\n  mounts: Array<{ source: string; target: string }>;\n  /** Raw fractional CPU limit (cgroup enforcement on remote Linux workers). */\n  cpus?: string;\n  /** Whole vCPUs given to the VM. */\n  vmCpus?: number;\n  memory?: string;\n  fingerprint: string;\n  /** mikan-host workspace root, for remote mount prefix translation. */\n  workspacePath?: string;\n}\n\n/** One way of running Gondolin runtimes: in local workers or on a remote fleet. */\nexport interface GondolinRuntimeTransport {\n  ensure(instanceId: string, spec: GondolinRuntimeSpec): Promise<GondolinRuntimeHandle>;\n  stop(\n    handle: Pick<GondolinRuntimeHandle, \"workerPid\" | \"sessionId\" | \"instanceId\" | \"workerName\">,\n  ): Promise<void>;\n  exec(\n    handle: GondolinRuntimeHandle,\n    command: string,\n    options?: { env?: Record<string, string>; signal?: AbortSignal },\n  ): Promise<ExecResult>;\n  isRuntimeAlive(handle: GondolinRuntimeHandle): Promise<boolean>;\n}\n\n/**\n * The runtime is gone and the command never reached it (the session socket\n * refused the connection) — safe to recreate the runtime and retry.\n */\nexport class GondolinRuntimeGoneError extends Error {}\n\n/** The runtime died with the command in flight — not safe to retry blindly. */\nexport class GondolinRuntimeInterruptedError extends Error {}\n\ninterface WorkerProcessLike {\n  pid?: number;\n  stdout: Readable | null;\n  stderr: Readable | null;\n  once(event: \"close\", listener: (code: number | null) => void): unknown;\n  once(event: \"error\", listener: (error: Error) => void): unknown;\n  kill(signal?: NodeJS.Signals): boolean;\n  unref(): void;\n}\n\nexport interface SessionClientCallbacks {\n  onJson: (message: {\n    type: string;\n    id?: number;\n    exit_code?: number | null;\n    code?: string;\n    message?: string;\n  }) => void;\n  onBinary: (frame: Buffer) => void;\n  onClose: (error?: Error) => void;\n}\n\nexport interface SessionClient {\n  send(message: object): void;\n  close(): void;\n}\n\ninterface GondolinWorkerClientOverrides {\n  spawnProcess?: (command: string, args: string[]) => WorkerProcessLike;\n  connect?: (socketPath: string, callbacks: SessionClientCallbacks) => SessionClient;\n  kill?: (pid: number, signal: NodeJS.Signals | 0) => void;\n  handshakeTimeoutMs?: number;\n  stopWaitMs?: number;\n  stopPollIntervalMs?: number;\n}\n\nfunction defaultSpawnProcess(command: string, args: string[]): WorkerProcessLike {\n  return spawn(command, args, { detached: true, stdio: [\"ignore\", \"pipe\", \"pipe\"] });\n}\n\nasync function defaultConnect(\n  socketPath: string,\n  callbacks: SessionClientCallbacks,\n): Promise<SessionClient> {\n  const { connectToSession } = await import(\"@earendil-works/gondolin\");\n  return connectToSession(socketPath, callbacks);\n}\n\nfunction abortError(): Error {\n  return new Error(\"Error: command aborted\");\n}\n\n/**\n * A command may quietly work for a long time, but a session that produces no\n * frame at all for this long is indistinguishable from one wedged on dead\n * storage (a hung NFS mount under the workspace blocks guest I/O forever) —\n * kill it and say so instead of hanging the run.\n */\nconst EXEC_IDLE_TIMEOUT_MS = 10 * 60 * 1000;\n\n/**\n * Run one command through a fresh session connection — the shared state\n * machine for both transports. Closing the connection (abort, timeout, or the\n * far side dying) kills the in-flight guest process.\n */\nexport async function execOverSessionConnect(\n  connect: (callbacks: SessionClientCallbacks) => SessionClient | Promise<SessionClient>,\n  command: string,\n  options: { env?: Record<string, string>; signal?: AbortSignal; idleTimeoutMs?: number } = {},\n): Promise<ExecResult> {\n  if (options.signal?.aborted) throw abortError();\n  const idleTimeoutMs = options.idleTimeoutMs ?? EXEC_IDLE_TIMEOUT_MS;\n  return await new Promise<ExecResult>((resolve, reject) => {\n    let stdout = \"\";\n    let stderr = \"\";\n    let received = false;\n    let settled = false;\n    let client: SessionClient | undefined;\n    let idleTimer: NodeJS.Timeout | undefined;\n    const settle = (fn: () => void): void => {\n      if (settled) return;\n      settled = true;\n      clearTimeout(idleTimer);\n      options.signal?.removeEventListener(\"abort\", onAbort);\n      fn();\n    };\n    const onAbort = (): void =>\n      settle(() => {\n        client?.close();\n        reject(abortError());\n      });\n    const onIdle = (): void =>\n      settle(() => {\n        client?.close();\n        reject(\n          new GondolinRuntimeInterruptedError(\n            `no session activity for ${Math.round(idleTimeoutMs / 1000)}s — killed the command ` +\n              `(guest I/O hangs when the workspace sits on a dead mount; check the worker's workspace health)`,\n          ),\n        );\n      });\n    const armIdleTimer = (): void => {\n      if (idleTimeoutMs <= 0 || settled) return;\n      clearTimeout(idleTimer);\n      idleTimer = setTimeout(onIdle, idleTimeoutMs);\n      idleTimer.unref?.();\n    };\n    armIdleTimer();\n    const callbacks: SessionClientCallbacks = {\n      onJson: (message) => {\n        received = true;\n        armIdleTimer();\n        if (message.type === \"exec_response\" && message.id === 1) {\n          settle(() => {\n            client?.close();\n            resolve({\n              stdout,\n              stderr,\n              code: typeof message.exit_code === \"number\" ? message.exit_code : 1,\n            });\n          });\n        } else if (message.type === \"error\") {\n          settle(() => {\n            client?.close();\n            reject(new Error(`Error: Gondolin exec failed (${message.code}): ${message.message}`));\n          });\n        }\n      },\n      onBinary: (frame) => {\n        received = true;\n        armIdleTimer();\n        const tag = frame.readUInt8(0);\n        const data = frame.subarray(5).toString(\"utf8\");\n        if (tag === 1) stdout += data;\n        else stderr += data;\n      },\n      onClose: (error) => {\n        settle(() => {\n          const detail = error?.message ?? \"connection closed before the command finished\";\n          const code = (error as NodeJS.ErrnoException | undefined)?.code;\n          if (!received && (code === \"ENOENT\" || code === \"ECONNREFUSED\")) {\n            reject(new GondolinRuntimeGoneError(detail));\n          } else {\n            reject(new GondolinRuntimeInterruptedError(detail));\n          }\n        });\n      },\n    };\n    options.signal?.addEventListener(\"abort\", onAbort, { once: true });\n    Promise.resolve(connect(callbacks))\n      .then((created) => {\n        client = created;\n        if (settled) {\n          created.close();\n          return;\n        }\n        created.send({\n          type: \"exec\",\n          id: 1,\n          cmd: \"/bin/sh\",\n          argv: [\"-c\", command],\n          env: Object.entries(options.env ?? {}).map(([key, value]) => `${key}=${value}`),\n          cwd: \"/workspace\",\n        });\n      })\n      .catch((err: unknown) =>\n        settle(() =>\n          reject(new GondolinRuntimeGoneError(err instanceof Error ? err.message : String(err))),\n        ),\n      );\n  });\n}\n\n/** Workers self-stop once no mikan has refreshed the heartbeat for this long. */\nconst WORKER_HEARTBEAT_STALE_MS = 45 * 60 * 1000;\n\nclass GondolinWorkerClient implements GondolinRuntimeTransport {\n  private spawnProcess = defaultSpawnProcess;\n  private connectImpl: (\n    socketPath: string,\n    callbacks: SessionClientCallbacks,\n  ) => SessionClient | Promise<SessionClient> = defaultConnect;\n  private killImpl: (pid: number, signal: NodeJS.Signals | 0) => void = (pid, signal) =>\n    process.kill(pid, signal);\n  private handshakeTimeoutMs = 120_000;\n  private stopWaitMs = 15_000;\n  private stopPollIntervalMs = 100;\n\n  configure(overrides?: GondolinWorkerClientOverrides): void {\n    this.spawnProcess = overrides?.spawnProcess ?? defaultSpawnProcess;\n    this.connectImpl = overrides?.connect ?? defaultConnect;\n    this.killImpl = overrides?.kill ?? ((pid, signal) => process.kill(pid, signal));\n    this.handshakeTimeoutMs = overrides?.handshakeTimeoutMs ?? 120_000;\n    this.stopWaitMs = overrides?.stopWaitMs ?? 15_000;\n    this.stopPollIntervalMs = overrides?.stopPollIntervalMs ?? 100;\n  }\n\n  /** Adopt a surviving local worker or spawn a fresh one for the spec. */\n  async ensure(instanceId: string, spec: GondolinRuntimeSpec): Promise<GondolinRuntimeHandle> {\n    const adopted = await this.adopt(instanceId, spec.fingerprint);\n    if (adopted) return adopted;\n    return this.spawn({\n      instanceId,\n      image: spec.image,\n      mounts: spec.mounts,\n      cpus: spec.vmCpus,\n      memory: spec.memory,\n      fingerprint: spec.fingerprint,\n      inventoryDir: gondolinInventory.directory() ?? join(homedir(), \".mikan\", \"gondolin-runtimes\"),\n      heartbeatStaleMs: WORKER_HEARTBEAT_STALE_MS,\n    });\n  }\n\n  /** Whether the runtime's worker process is still alive. */\n  async isRuntimeAlive(handle: GondolinRuntimeHandle): Promise<boolean> {\n    return this.isPidAlive(handle.workerPid);\n  }\n\n  /** Spawn a detached worker for the config and wait for its ready handshake. */\n  async spawn(config: GondolinWorkerConfig): Promise<GondolinRuntimeHandle> {\n    const entry = fileURLToPath(new URL(\"./gondolin-worker-main.js\", import.meta.url));\n    const child = this.spawnProcess(process.execPath, [entry, JSON.stringify(config)]);\n    const handshake = await this.readHandshake(child);\n    if (!handshake.ready || !handshake.sessionId || !handshake.socketPath) {\n      throw new SandboxError(\n        `Error: Gondolin worker failed to start: ${handshake.error ?? \"no session in handshake\"}`,\n      );\n    }\n    child.stdout?.destroy();\n    child.stderr?.destroy();\n    child.unref();\n    return {\n      sessionId: handshake.sessionId,\n      instanceId: config.instanceId,\n      socketPath: handshake.socketPath,\n      workerPid: handshake.workerPid ?? (child.pid as number),\n      fingerprint: config.fingerprint,\n    };\n  }\n\n  /**\n   * Adopt a runtime a previous mikan left running: newest live record for the\n   * key whose fingerprint still matches and whose session answers a probe.\n   * Anything stale — drifted fingerprint, unresponsive session — is stopped so\n   * the caller can spawn fresh.\n   */\n  async adopt(instanceId: string, fingerprint: string): Promise<GondolinRuntimeHandle | undefined> {\n    const record: GondolinRuntimeRecord | undefined =\n      await gondolinInventory.findAdoptable(instanceId);\n    if (!record?.socketPath) return undefined;\n    const handle: GondolinRuntimeHandle = {\n      sessionId: record.sessionId,\n      instanceId,\n      socketPath: record.socketPath,\n      workerPid: record.ownerPid,\n      fingerprint: record.fingerprint ?? \"\",\n    };\n    if (record.fingerprint !== fingerprint) {\n      await this.stop(handle);\n      return undefined;\n    }\n    try {\n      await this.exec(handle, \"true\", { signal: AbortSignal.timeout(5000) });\n    } catch {\n      await this.stop(handle);\n      return undefined;\n    }\n    return handle;\n  }\n\n  /**\n   * Stop a worker and wait for it to clean up after itself; escalate to\n   * SIGKILL and reap its leftovers if it will not die.\n   */\n  async stop(handle: Pick<GondolinRuntimeHandle, \"workerPid\" | \"sessionId\">): Promise<void> {\n    if (this.isPidAlive(handle.workerPid)) {\n      this.signal(handle.workerPid, \"SIGTERM\");\n      if (!(await this.waitForExit(handle.workerPid, this.stopWaitMs))) {\n        this.signal(handle.workerPid, \"SIGKILL\");\n        await this.waitForExit(handle.workerPid, 2000);\n      }\n    }\n    await gondolinInventory.reapSession(handle.sessionId);\n  }\n\n  /** Whether the worker process behind a handle is still alive. */\n  isWorkerAlive(handle: Pick<GondolinRuntimeHandle, \"workerPid\">): boolean {\n    return this.isPidAlive(handle.workerPid);\n  }\n\n  /**\n   * Run one command over a dedicated session IPC connection. Aborting (or the\n   * caller's timeout signal firing) destroys the connection, which kills the\n   * in-flight guest process.\n   */\n  async exec(\n    handle: GondolinRuntimeHandle,\n    command: string,\n    options: { env?: Record<string, string>; signal?: AbortSignal } = {},\n  ): Promise<ExecResult> {\n    return execOverSessionConnect(\n      (callbacks) => this.connectImpl(handle.socketPath, callbacks),\n      command,\n      options,\n    );\n  }\n\n  private signal(pid: number, signal: NodeJS.Signals): void {\n    try {\n      this.killImpl(pid, signal);\n    } catch {\n      // already gone\n    }\n  }\n\n  private isPidAlive(pid: number): boolean {\n    try {\n      this.killImpl(pid, 0);\n      return true;\n    } catch {\n      return false;\n    }\n  }\n\n  private async waitForExit(pid: number, waitMs: number): Promise<boolean> {\n    const deadline = Date.now() + waitMs;\n    while (this.isPidAlive(pid)) {\n      if (Date.now() >= deadline) return false;\n      await new Promise((resolve) => setTimeout(resolve, this.stopPollIntervalMs));\n    }\n    return true;\n  }\n\n  private readHandshake(child: WorkerProcessLike): Promise<GondolinWorkerHandshake> {\n    return new Promise((resolve, reject) => {\n      let buffer = \"\";\n      let stderr = \"\";\n      let settled = false;\n      const settle = (fn: () => void): void => {\n        if (settled) return;\n        settled = true;\n        clearTimeout(timer);\n        fn();\n      };\n      const timer = setTimeout(() => {\n        settle(() => {\n          child.kill(\"SIGKILL\");\n          reject(\n            new SandboxError(\n              `Error: Gondolin worker did not become ready within ${this.handshakeTimeoutMs}ms${\n                stderr ? `: ${stderr.trim()}` : \"\"\n              }`,\n            ),\n          );\n        });\n      }, this.handshakeTimeoutMs);\n      child.stdout?.on(\"data\", (chunk: Buffer) => {\n        buffer += chunk.toString(\"utf8\");\n        const newline = buffer.indexOf(\"\\n\");\n        if (newline < 0) return;\n        const line = buffer.slice(0, newline);\n        settle(() => {\n          try {\n            resolve(JSON.parse(line) as GondolinWorkerHandshake);\n          } catch {\n            child.kill(\"SIGKILL\");\n            reject(new SandboxError(`Error: invalid Gondolin worker handshake: ${line}`));\n          }\n        });\n      });\n      child.stderr?.on(\"data\", (chunk: Buffer) => {\n        stderr += chunk.toString(\"utf8\");\n      });\n      child.once(\"close\", (code) => {\n        settle(() =>\n          reject(\n            new SandboxError(\n              `Error: Gondolin worker exited before becoming ready (code ${code})${\n                stderr ? `: ${stderr.trim()}` : \"\"\n              }`,\n            ),\n          ),\n        );\n      });\n      child.once(\"error\", (error) => {\n        settle(() =>\n          reject(new SandboxError(`Error: failed to spawn Gondolin worker: ${error.message}`)),\n        );\n      });\n    });\n  }\n}\n\nexport const gondolinWorkers = new GondolinWorkerClient();\n"]}

package/dist/sandbox/gondolin-worker-main.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=gondolin-worker-main.d.ts.map

package/dist/sandbox/gondolin-worker-main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gondolin-worker-main.d.ts","sourceRoot":"","sources":["../../src/sandbox/gondolin-worker-main.ts"],"names":[],"mappings":""}

package/dist/sandbox/gondolin-worker-main.js

@@ -0,0 +1,22 @@
+// Entry point for the detached Gondolin worker process. Spawned by mikan with
+// one JSON argv (the GondolinWorkerConfig); survives the spawning mikan so the
+// VM keeps running across mikan restarts and deploys.
+import { runGondolinWorker } from "./gondolin-worker.js";
+// The spawning mikan may be gone when we write; a broken pipe must not crash
+// a worker that is otherwise healthy.
+process.stdout.on("error", () => { });
+process.stderr.on("error", () => { });
+let config;
+try {
+    config = JSON.parse(process.argv[2] ?? "");
+}
+catch {
+    process.stdout.write(JSON.stringify({ ready: false, error: "invalid worker config" }) + "\n");
+    process.exit(2);
+}
+runGondolinWorker(config).catch((err) => {
+    const error = err instanceof Error ? err.message : String(err);
+    process.stdout.write(JSON.stringify({ ready: false, error }) + "\n");
+    process.exit(1);
+});
+//# sourceMappingURL=gondolin-worker-main.js.map

package/dist/sandbox/gondolin-worker-main.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gondolin-worker-main.js","sourceRoot":"","sources":["../../src/sandbox/gondolin-worker-main.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,+EAA+E;AAC/E,sDAAsD;AACtD,OAAO,EAAE,iBAAiB,EAA6B,MAAM,sBAAsB,CAAC;AAEpF,6EAA6E;AAC7E,sCAAsC;AACtC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;AACrC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;AAErC,IAAI,MAA4B,CAAC;AACjC,IAAI,CAAC;IACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,CAAyB,CAAC;AACrE,CAAC;AAAC,MAAM,CAAC;IACP,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,uBAAuB,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;IAC9F,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AAED,iBAAiB,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE;IAC/C,MAAM,KAAK,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAC/D,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC,CAAC;IACrE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC","sourcesContent":["// Entry point for the detached Gondolin worker process. Spawned by mikan with\n// one JSON argv (the GondolinWorkerConfig); survives the spawning mikan so the\n// VM keeps running across mikan restarts and deploys.\nimport { runGondolinWorker, type GondolinWorkerConfig } from \"./gondolin-worker.js\";\n\n// The spawning mikan may be gone when we write; a broken pipe must not crash\n// a worker that is otherwise healthy.\nprocess.stdout.on(\"error\", () => {});\nprocess.stderr.on(\"error\", () => {});\n\nlet config: GondolinWorkerConfig;\ntry {\n  config = JSON.parse(process.argv[2] ?? \"\") as GondolinWorkerConfig;\n} catch {\n  process.stdout.write(JSON.stringify({ ready: false, error: \"invalid worker config\" }) + \"\\n\");\n  process.exit(2);\n}\n\nrunGondolinWorker(config).catch((err: unknown) => {\n  const error = err instanceof Error ? err.message : String(err);\n  process.stdout.write(JSON.stringify({ ready: false, error }) + \"\\n\");\n  process.exit(1);\n});\n"]}

package/dist/sandbox/gondolin-worker.d.ts

@@ -0,0 +1,55 @@
+type GondolinModule = typeof import("@earendil-works/gondolin");
+/**
+ * Everything a worker process needs to host one Gondolin VM. Serialized as a
+ * single JSON argv entry — it must stay free of secrets (vault env travels
+ * per-exec over the session IPC socket, never through the worker command
+ * line).
+ */
+export interface GondolinWorkerConfig {
+    /** mikan session key the runtime belongs to. */
+    instanceId: string;
+    /** Resolved guest image asset directory. */
+    image?: string;
+    /** Image selector resolved inside the worker (remote workers, where the
+     * spawning host has no image store). Ignored when `image` is set. */
+    imageSelector?: string;
+    mounts: Array<{
+        source: string;
+        target: string;
+    }>;
+    cpus?: number;
+    memory?: string;
+    /** Desired-runtime fingerprint recorded for adoption checks. */
+    fingerprint: string;
+    /** Runtime inventory directory (shared with the spawning mikan). */
+    inventoryDir: string;
+    /**
+     * Self-stop when the mikan heartbeat file is older than this — no mikan is
+     * left to adopt the runtime. 0 disables the check.
+     */
+    heartbeatStaleMs: number;
+}
+/** First stdout line of a worker, consumed by the spawning mikan. */
+export interface GondolinWorkerHandshake {
+    ready: boolean;
+    error?: string;
+    sessionId?: string;
+    socketPath?: string;
+    workerPid?: number;
+    runnerPid?: number | null;
+}
+interface GondolinWorkerDeps {
+    loadGondolin?: () => Promise<GondolinModule>;
+    announce?: (line: string) => void;
+    exit?: (code: number) => void;
+    pollIntervalMs?: number;
+}
+/**
+ * Host one Gondolin VM for its whole life: boot it, persist the inventory
+ * record other processes adopt it through, announce readiness on stdout, then
+ * watch the VM runner and shut down when it dies, when a SIGTERM arrives, or
+ * when every mikan that could adopt the runtime is gone (stale heartbeat).
+ */
+export declare function runGondolinWorker(config: GondolinWorkerConfig, deps?: GondolinWorkerDeps): Promise<void>;
+export {};
+//# sourceMappingURL=gondolin-worker.d.ts.map

package/dist/sandbox/gondolin-worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gondolin-worker.d.ts","sourceRoot":"","sources":["../../src/sandbox/gondolin-worker.ts"],"names":[],"mappings":"AAMA,KAAK,cAAc,GAAG,cAAc,0BAA0B,CAAC,CAAC;AAEhE;;;;;GAKG;AACH,MAAM,WAAW,oBAAoB;IACnC,gDAAgD;IAChD,UAAU,EAAE,MAAM,CAAC;IACnB,4CAA4C;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;yEACqE;IACrE,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAClD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,WAAW,EAAE,MAAM,CAAC;IACpB,oEAAoE;IACpE,YAAY,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,qEAAqE;AACrE,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,UAAU,kBAAkB;IAC1B,YAAY,CAAC,EAAE,MAAM,OAAO,CAAC,cAAc,CAAC,CAAC;IAC7C,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAClC,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9B,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAwED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,oBAAoB,EAC5B,IAAI,GAAE,kBAAuB,GAC5B,OAAO,CAAC,IAAI,CAAC,CA8Hf"}