@getforgeai/cli 0.1.0-beta.1

package/dist/vm/session-snapshot.js

@@ -0,0 +1,180 @@
+/**
+ * Session snapshot: save and restore Claude Code session files for workflow resume.
+ *
+ * Before destroying a container after idle timeout:
+ *   1. Auto-save code: git add -A && git commit && git push
+ *   2. Tar Claude Code session files (~/.claude/projects/)
+ *   3. Upload encrypted snapshot to Cloud via socket event
+ *
+ * On resume in a new container:
+ *   1. Download snapshot from Cloud
+ *   2. Restore Claude Code session files
+ *   3. Launch `claude --continue` (full context restored)
+ */
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { execInContainer } from "./docker-executor.js";
+import { gitCredentialConfigShellFragment, gitCredentialSecretEnv, } from "./git-credentials.js";
+import { vmLog } from "./log.js";
+/** Max snapshot size: 5MB compressed */
+const MAX_SNAPSHOT_SIZE = 5 * 1024 * 1024;
+/**
+ * Auto-save code changes in the container (best-effort git commit + push).
+ * Does not throw — failures are logged and ignored.
+ */
+export async function autoSaveCode(containerId, sessionId, credentials) {
+    // Network pushes need the credential re-supplied out-of-band: the repo was
+    // cloned with a clean URL, so nothing is embedded in .git/config. The helper
+    // reads the value from FORGE_GIT_* env vars provided via secretEnv.
+    const gitPush = credentials
+        ? `git ${gitCredentialConfigShellFragment()} push`
+        : "git push";
+    const pushExecOpts = credentials
+        ? { timeout: 30_000, secretEnv: gitCredentialSecretEnv(credentials) }
+        : { timeout: 30_000 };
+    try {
+        // 0. Log current branch and remote
+        const branchInfo = await execInContainer(containerId, [
+            "bash",
+            "-c",
+            "cd /session/workspace && echo \"branch=$(git rev-parse --abbrev-ref HEAD) remote=$(git remote get-url origin 2>/dev/null | sed 's/\\/\\/.*@/\\/\\//') \"",
+        ], { timeout: 5_000 });
+        vmLog.dim("session-snapshot", branchInfo.stdout.trim(), sessionId);
+        // 1. Stage all changes
+        await execInContainer(containerId, ["bash", "-c", "cd /session/workspace && git add -A"], { timeout: 10_000 });
+        // 2. Check if there's anything to commit
+        const diffResult = await execInContainer(containerId, ["bash", "-c", "cd /session/workspace && git diff --cached --quiet"], { timeout: 10_000 });
+        if (diffResult.exitCode === 0) {
+            vmLog.dim("session-snapshot", "No changes to commit", sessionId);
+            // Still try to push (agent may have committed but not pushed)
+            const pushResult = await execInContainer(containerId, ["bash", "-c", `cd /session/workspace && ${gitPush} 2>&1`], pushExecOpts);
+            if (pushResult.exitCode === 0) {
+                const output = pushResult.stdout.trim();
+                if (output.includes("Everything up-to-date")) {
+                    vmLog.dim("session-snapshot", "Nothing to push (up-to-date)", sessionId);
+                }
+                else {
+                    vmLog.cyan("session-snapshot", `Pushed existing commits: ${output.slice(0, 100)}`, sessionId);
+                }
+            }
+            else {
+                vmLog.warn("session-snapshot", `Push failed: ${pushResult.stderr.slice(0, 200)}`, sessionId);
+            }
+            return;
+        }
+        // 3. Commit staged changes
+        const commitResult = await execInContainer(containerId, [
+            "bash",
+            "-c",
+            'cd /session/workspace && git commit -m "wip: auto-save step progress" 2>&1',
+        ], { timeout: 10_000 });
+        if (commitResult.exitCode !== 0) {
+            vmLog.warn("session-snapshot", `Commit failed: ${commitResult.stdout.slice(0, 200)}`, sessionId);
+            return;
+        }
+        vmLog.cyan("session-snapshot", "Committed changes", sessionId);
+        // 4. Push
+        const pushResult = await execInContainer(containerId, ["bash", "-c", `cd /session/workspace && ${gitPush} 2>&1`], pushExecOpts);
+        if (pushResult.exitCode !== 0) {
+            vmLog.error("session-snapshot", `Push FAILED: ${pushResult.stderr.slice(0, 200)} ${pushResult.stdout.slice(0, 200)}`, sessionId);
+        }
+        else {
+            vmLog.cyan("session-snapshot", "Auto-saved code (commit + push)", sessionId);
+        }
+    }
+    catch (err) {
+        vmLog.warn("session-snapshot", `Auto-save failed: ${err instanceof Error ? err.message : String(err)}`, sessionId);
+    }
+}
+/**
+ * Save Claude Code session files from the container to a base64 tar.gz string.
+ *
+ * Returns the base64-encoded tar.gz, or null if snapshot is unavailable or too large.
+ */
+export async function createSessionSnapshot(session) {
+    const sessionId = session.id;
+    try {
+        // Tar the entire Claude Code config directory (~/.claude/).
+        // --continue needs: history.jsonl (global session index) + projects/<encoded-path>/ (session JSONL files)
+        // Exclude settings.json and other non-session files to keep size small.
+        const tarResult = await execInContainer(session.containerId, [
+            "bash",
+            "-c",
+            [
+                "test -d /home/agent/.claude || exit 0",
+                "tar czf /session/claude-session.tar.gz -C /home/agent/.claude" +
+                    " --exclude='settings.json'" +
+                    " --exclude='credentials.json'" +
+                    " --exclude='statsig'" +
+                    " --exclude='commands'" +
+                    " --exclude='todos'" +
+                    " .",
+            ].join(" && "),
+        ], { timeout: 30_000 });
+        if (tarResult.exitCode !== 0) {
+            vmLog.warn("session-snapshot", `Tar failed (code ${tarResult.exitCode}): ${tarResult.stderr.slice(0, 200)}`, sessionId);
+            return null;
+        }
+        // Read the tar from the host volume
+        const tarPath = join(session.sessionDir, "claude-session.tar.gz");
+        if (!existsSync(tarPath)) {
+            vmLog.dim("session-snapshot", "No Claude session directory found in container, skipping snapshot", sessionId);
+            return null;
+        }
+        const tarBuffer = readFileSync(tarPath);
+        // Check size limit
+        if (tarBuffer.length > MAX_SNAPSHOT_SIZE) {
+            vmLog.warn("session-snapshot", `Snapshot too large (${(tarBuffer.length / 1024 / 1024).toFixed(1)}MB > 5MB), skipping`, sessionId);
+            return null;
+        }
+        vmLog.cyan("session-snapshot", `Created snapshot (${(tarBuffer.length / 1024).toFixed(0)}KB compressed)`, sessionId);
+        return tarBuffer.toString("base64");
+    }
+    catch (err) {
+        vmLog.warn("session-snapshot", `Snapshot creation failed: ${err instanceof Error ? err.message : String(err)}`, sessionId);
+        return null;
+    }
+}
+/**
+ * Restore Claude Code session files into a container from a base64 tar.gz string.
+ */
+export async function restoreSessionSnapshot(session, snapshotBase64) {
+    const sessionId = session.id;
+    try {
+        // Write the tar to the host volume
+        const tarPath = join(session.sessionDir, "claude-session.tar.gz");
+        const { writeFileSync } = await import("node:fs");
+        writeFileSync(tarPath, Buffer.from(snapshotBase64, "base64"));
+        // Create the target directory and extract (entire ~/.claude/)
+        await execInContainer(session.containerId, [
+            "mkdir",
+            "-p",
+            "/home/agent/.claude",
+        ]);
+        const extractResult = await execInContainer(session.containerId, [
+            "tar",
+            "xzf",
+            "/session/claude-session.tar.gz",
+            "-C",
+            "/home/agent/.claude",
+        ], { timeout: 30_000 });
+        if (extractResult.exitCode !== 0) {
+            vmLog.warn("session-snapshot", `Tar extract failed (code ${extractResult.exitCode}): ${extractResult.stderr.slice(0, 200)}`, sessionId);
+            return false;
+        }
+        // Fix ownership (tar may have preserved root ownership from the build)
+        await execInContainer(session.containerId, [
+            "chown",
+            "-R",
+            "agent:agent",
+            "/home/agent/.claude",
+        ]);
+        vmLog.cyan("session-snapshot", "Restored Claude session snapshot", sessionId);
+        return true;
+    }
+    catch (err) {
+        vmLog.warn("session-snapshot", `Snapshot restore failed: ${err instanceof Error ? err.message : String(err)}`, sessionId);
+        return false;
+    }
+}
+//# sourceMappingURL=session-snapshot.js.map

package/dist/vm/types.d.ts

@@ -0,0 +1,73 @@
+import type { ChildProcess } from "node:child_process";
+export type NetworkRule = {
+    cidr: string;
+    port: number;
+    protocol: "tcp" | "udp";
+};
+export type VmConfig = {
+    cpus: number;
+    memoryMB: number;
+    rootfsPath: string;
+    sessionDir: string;
+    networkAllowlist: NetworkRule[];
+    vsockPort: number;
+};
+export type VmInfo = {
+    id: string;
+    status: "RUNNING" | "STOPPED" | "ERROR";
+    pid?: number;
+    vsockCid?: number;
+};
+export type ExecResult = {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+};
+export type VmProvider = {
+    readonly name: string;
+    isAvailable(): Promise<boolean>;
+    start(id: string, config: VmConfig): Promise<VmInfo>;
+    exec(id: string, cmd: string, args?: string[]): Promise<ExecResult>;
+    /** Spawn a long-lived process with piped stdout/stderr (for agent execution via SSH) */
+    spawnStreaming(id: string, cmd: string, args: string[], cwd: string, options?: {
+        reverseTunnels?: Array<{
+            remotePort: number;
+            localPort: number;
+        }>;
+    }): {
+        pid: number;
+        process: ChildProcess;
+    };
+    stop(id: string): Promise<void>;
+    destroy(id: string): Promise<void>;
+    getInfo(id: string): Promise<VmInfo | null>;
+    /** Get the vsock socket path (Unix domain socket on macOS, TCP host:port on Linux/Windows) */
+    getVsockPath(id: string): string;
+};
+export type SessionConfig = {
+    repoUrl?: string;
+    branch?: string;
+    workflowBaseBranch?: string;
+    taskContext?: Record<string, unknown>;
+    workflowContext?: {
+        workflowId: string;
+        stepId: string;
+    };
+};
+export type SessionFiles = {
+    contextJson: string;
+    mcpConfigJson: string;
+    skillFiles: Array<{
+        relativePath: string;
+        content: string;
+    }>;
+};
+export type SessionInfo = {
+    id: string;
+    taskId: string;
+    vmInfo: VmInfo | null;
+    sessionDir: string;
+    config: SessionConfig;
+    status: "CREATED" | "BOOTING" | "RUNNING" | "STOPPED" | "DESTROYED";
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/vm/types.js

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

package/dist/vm/vm-helper-client.d.ts

@@ -0,0 +1,81 @@
+/**
+ * VmHelperClient — parent-side IPC client for the VM helper process.
+ *
+ * Provides the same API as SessionManager but delegates all native addon
+ * operations to a child process (node-vm) that has Apple Virtualization
+ * entitlements. Communication uses Node.js built-in IPC with structured
+ * clone for efficient Buffer transfer.
+ */
+import { EventEmitter } from "node:events";
+import { PassThrough } from "node:stream";
+import type { AgentProcess } from "../orchestrator/connectors/connector.js";
+import type { SessionState } from "./vm-ipc-protocol.js";
+/**
+ * Parent-side process proxy that receives streaming data via IPC events.
+ * Implements AgentProcess so the orchestrator can use it identically.
+ */
+export declare class RemoteVmProcessProxy extends EventEmitter implements AgentProcess {
+    private readonly taskId;
+    private readonly client;
+    readonly stdout: PassThrough;
+    readonly stderr: PassThrough;
+    pid: number;
+    exitCode: number | null;
+    killed: boolean;
+    constructor(taskId: string, client: VmHelperClient);
+    setPid(pid: number): void;
+    pushStdout(data: Buffer): void;
+    pushStderr(data: Buffer): void;
+    emitExit(code: number): void;
+    kill(signal?: string): boolean;
+}
+export declare class VmHelperClient {
+    private child;
+    private pending;
+    private proxies;
+    private exitListeners;
+    private _vmRunning;
+    /**
+     * Spawn the helper child process.
+     * Must be called before any other method.
+     */
+    spawn(): Promise<void>;
+    ensureVmRunning(): Promise<void>;
+    createSession(taskId: string): Promise<string>;
+    cloneRepo(sessionId: string, repoUrl: string | undefined, branch?: string, baseBranch?: string): Promise<void>;
+    /**
+     * Write session files to the VirtioFS-shared host directory.
+     * Stays in parent process — no IPC needed (pure filesystem I/O).
+     */
+    prepareWorkspace(sessionId: string, files: {
+        contextJson: string;
+        mcpConfigJson: string;
+        skillFiles: Array<{
+            relativePath: string;
+            content: string;
+        }>;
+    }): void;
+    spawnAgent(taskId: string, cmd: string, args: string[], env?: Record<string, string>): Promise<RemoteVmProcessProxy>;
+    killAgent(taskIdOrSessionId: string, signal?: string): Promise<void>;
+    destroySession(taskId: string): Promise<void>;
+    exec(cmd: string, args: string[], cwd?: string): Promise<{
+        stdout: string;
+        stderr: string;
+        exitCode: number;
+    }>;
+    shutdown(): Promise<void>;
+    /** Send a request on a specific child reference (used during shutdown) */
+    private requestOnChild;
+    isVmRunning(): boolean;
+    getAllSessions(): SessionState[];
+    getSessionByTaskId(_taskId: string): SessionState | undefined;
+    onSessionExit(sessionId: string, callback: (code: number) => void): void;
+    private request;
+    private handleMessage;
+    private handleResponse;
+    private handleEvent;
+    private handleChildDeath;
+}
+export declare function initVmHelper(): VmHelperClient;
+export declare function getVmHelper(): VmHelperClient;
+//# sourceMappingURL=vm-helper-client.d.ts.map

package/dist/vm/vm-helper-client.js

@@ -0,0 +1,335 @@
+/**
+ * VmHelperClient — parent-side IPC client for the VM helper process.
+ *
+ * Provides the same API as SessionManager but delegates all native addon
+ * operations to a child process (node-vm) that has Apple Virtualization
+ * entitlements. Communication uses Node.js built-in IPC with structured
+ * clone for efficient Buffer transfer.
+ */
+import { fork } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { EventEmitter } from "node:events";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { PassThrough } from "node:stream";
+import { vmLog } from "./log.js";
+// ---------------------------------------------------------------------------
+// Paths
+// ---------------------------------------------------------------------------
+const SESSIONS_DIR = join(homedir(), ".forgeai", "vm", "sessions");
+// ---------------------------------------------------------------------------
+// RemoteVmProcessProxy
+// ---------------------------------------------------------------------------
+/**
+ * Parent-side process proxy that receives streaming data via IPC events.
+ * Implements AgentProcess so the orchestrator can use it identically.
+ */
+export class RemoteVmProcessProxy extends EventEmitter {
+    taskId;
+    client;
+    stdout;
+    stderr;
+    pid = -1;
+    exitCode = null;
+    killed = false;
+    constructor(taskId, client) {
+        super();
+        this.taskId = taskId;
+        this.client = client;
+        this.stdout = new PassThrough();
+        this.stderr = new PassThrough();
+    }
+    setPid(pid) {
+        this.pid = pid;
+    }
+    pushStdout(data) {
+        this.stdout.push(data);
+    }
+    pushStderr(data) {
+        this.stderr.push(data);
+    }
+    emitExit(code) {
+        this.exitCode = code;
+        this.stdout.end();
+        this.stderr.end();
+        this.emit("exit", code, null);
+        this.emit("close", code, null);
+    }
+    kill(signal) {
+        if (this.exitCode !== null || this.killed)
+            return false;
+        this.killed = true;
+        this.client.killAgent(this.taskId, signal ?? "SIGTERM").catch(() => { });
+        return true;
+    }
+}
+// ---------------------------------------------------------------------------
+// VmHelperClient
+// ---------------------------------------------------------------------------
+export class VmHelperClient {
+    child = null;
+    pending = new Map();
+    proxies = new Map();
+    exitListeners = new Map();
+    _vmRunning = false;
+    /**
+     * Spawn the helper child process.
+     * Must be called before any other method.
+     */
+    async spawn() {
+        const cliRoot = join(import.meta.dirname, "..", "..");
+        const nodeVmPath = join(cliRoot, "native", "node-vm");
+        const helperScript = join(import.meta.dirname, "vm-helper.js");
+        if (!existsSync(nodeVmPath)) {
+            throw new Error(`node-vm not found at ${nodeVmPath}. Build it with:\n` +
+                "  cd packages/cli/native && cp $(which node) node-vm\n" +
+                '  codesign --entitlements entitlements-vm-only.plist --force -s "Developer ID Application: ..." node-vm');
+        }
+        this.child = fork(helperScript, [], {
+            execPath: nodeVmPath,
+            serialization: "advanced",
+            stdio: ["pipe", "pipe", "pipe", "ipc"],
+            env: process.env,
+        });
+        // Forward child stdout/stderr to logs
+        this.child.stdout?.on("data", (chunk) => {
+            const text = chunk.toString("utf-8").trimEnd();
+            if (text)
+                vmLog.info("vm-helper:stdout", text);
+        });
+        this.child.stderr?.on("data", (chunk) => {
+            const text = chunk.toString("utf-8").trimEnd();
+            if (text)
+                vmLog.info("vm-helper:stderr", text);
+        });
+        // Handle IPC messages from child
+        this.child.on("message", (msg) => {
+            this.handleMessage(msg);
+        });
+        // Handle child crash
+        this.child.on("exit", (code, signal) => {
+            vmLog.error("vm-helper-client", `Helper process exited (code=${code}, signal=${signal})`);
+            this.handleChildDeath();
+        });
+        vmLog.info("vm-helper-client", "Helper process spawned");
+    }
+    // -------------------------------------------------------------------------
+    // SessionManager-compatible API
+    // -------------------------------------------------------------------------
+    async ensureVmRunning() {
+        await this.request({ method: "ensureVmRunning" }, 120_000);
+        this._vmRunning = true;
+    }
+    async createSession(taskId) {
+        return (await this.request({ method: "createSession", taskId }, 30_000));
+    }
+    async cloneRepo(sessionId, repoUrl, branch, baseBranch) {
+        await this.request({ method: "cloneRepo", sessionId, repoUrl, branch, baseBranch }, 600_000);
+    }
+    /**
+     * Write session files to the VirtioFS-shared host directory.
+     * Stays in parent process — no IPC needed (pure filesystem I/O).
+     */
+    prepareWorkspace(sessionId, files) {
+        const sessionDir = join(SESSIONS_DIR, sessionId);
+        mkdirSync(sessionDir, { recursive: true, mode: 0o700 });
+        writeFileSync(join(sessionDir, "context.json"), files.contextJson, "utf-8");
+        writeFileSync(join(sessionDir, "mcp_config.json"), files.mcpConfigJson, "utf-8");
+        for (const file of files.skillFiles) {
+            const filePath = resolve(sessionDir, "skills", file.relativePath);
+            if (!filePath.startsWith(resolve(sessionDir))) {
+                throw new Error(`Path traversal detected: ${file.relativePath}`);
+            }
+            mkdirSync(join(filePath, ".."), { recursive: true });
+            writeFileSync(filePath, file.content, "utf-8");
+        }
+    }
+    async spawnAgent(taskId, cmd, args, env = {}) {
+        const proxy = new RemoteVmProcessProxy(taskId, this);
+        this.proxies.set(taskId, proxy);
+        const result = (await this.request({ method: "spawnAgent", taskId, cmd, args, env }, 30_000));
+        proxy.setPid(result.pid);
+        return proxy;
+    }
+    async killAgent(taskIdOrSessionId, signal = "SIGTERM") {
+        await this.request({ method: "killAgent", taskIdOrSessionId, signal }, 10_000);
+    }
+    async destroySession(taskId) {
+        await this.request({ method: "destroySession", taskId }, 30_000);
+        this.proxies.delete(taskId);
+    }
+    async exec(cmd, args, cwd) {
+        return (await this.request({ method: "exec", cmd, args, cwd }, 600_000));
+    }
+    async shutdown() {
+        if (!this.child)
+            return;
+        const child = this.child;
+        this.child = null;
+        this._vmRunning = false;
+        try {
+            if (child.connected) {
+                await this.requestOnChild(child, { method: "shutdown" }, 10_000);
+            }
+        }
+        catch {
+            /* child may already be gone */
+        }
+        try {
+            child.kill("SIGTERM");
+        }
+        catch {
+            /* already dead */
+        }
+    }
+    /** Send a request on a specific child reference (used during shutdown) */
+    requestOnChild(child, params, timeoutMs) {
+        if (!child.connected)
+            return Promise.resolve(null);
+        const reqId = randomUUID();
+        const msg = { type: "req", reqId, ...params };
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(reqId);
+                resolve(null); // Don't reject on shutdown timeout
+            }, timeoutMs);
+            this.pending.set(reqId, { resolve, reject, timer });
+            try {
+                child.send(msg);
+            }
+            catch {
+                clearTimeout(timer);
+                this.pending.delete(reqId);
+                resolve(null);
+            }
+        });
+    }
+    isVmRunning() {
+        return this._vmRunning && this.child !== null;
+    }
+    getAllSessions() {
+        // Synchronous — returns empty if not available (best effort)
+        // For accurate data, use the async version
+        return [];
+    }
+    getSessionByTaskId(_taskId) {
+        return undefined;
+    }
+    onSessionExit(sessionId, callback) {
+        this.exitListeners.set(sessionId, callback);
+    }
+    // -------------------------------------------------------------------------
+    // IPC internals
+    // -------------------------------------------------------------------------
+    request(params, timeoutMs) {
+        if (!this.child?.connected) {
+            return Promise.reject(new Error("VM helper process not connected"));
+        }
+        const reqId = randomUUID();
+        const msg = { type: "req", reqId, ...params };
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(reqId);
+                reject(new Error(`IPC timeout (${timeoutMs}ms): ${params.method}`));
+            }, timeoutMs);
+            this.pending.set(reqId, { resolve, reject, timer });
+            this.child.send(msg);
+        });
+    }
+    handleMessage(msg) {
+        switch (msg.type) {
+            case "res":
+                this.handleResponse(msg);
+                break;
+            case "stream":
+            case "exit":
+            case "log":
+                this.handleEvent(msg);
+                break;
+        }
+    }
+    handleResponse(res) {
+        const pending = this.pending.get(res.reqId);
+        if (!pending)
+            return;
+        this.pending.delete(res.reqId);
+        clearTimeout(pending.timer);
+        if (res.ok) {
+            pending.resolve(res.value);
+        }
+        else {
+            pending.reject(new Error(res.error));
+        }
+    }
+    handleEvent(event) {
+        switch (event.type) {
+            case "stream": {
+                const proxy = this.proxies.get(event.taskId);
+                if (!proxy)
+                    break;
+                if (event.channel === "stdout") {
+                    proxy.pushStdout(Buffer.from(event.data));
+                }
+                else {
+                    proxy.pushStderr(Buffer.from(event.data));
+                }
+                break;
+            }
+            case "exit": {
+                const proxy = this.proxies.get(event.taskId);
+                if (proxy) {
+                    proxy.emitExit(event.code);
+                    this.proxies.delete(event.taskId);
+                }
+                // Also fire exit listener (used by onSessionExit registrations)
+                const listener = this.exitListeners.get(event.taskId);
+                if (listener) {
+                    this.exitListeners.delete(event.taskId);
+                    listener(event.code);
+                }
+                break;
+            }
+            case "log": {
+                const logFn = event.level === "error"
+                    ? vmLog.error
+                    : event.level === "warn"
+                        ? vmLog.warn
+                        : vmLog.info;
+                logFn.call(vmLog, event.prefix, event.message);
+                break;
+            }
+        }
+    }
+    handleChildDeath() {
+        // Reject all pending requests
+        for (const [reqId, pending] of this.pending) {
+            clearTimeout(pending.timer);
+            pending.reject(new Error("VM helper process died"));
+            this.pending.delete(reqId);
+        }
+        // Emit exit on all active proxies
+        for (const [taskId, proxy] of this.proxies) {
+            proxy.emitExit(-1);
+            this.proxies.delete(taskId);
+        }
+        this.child = null;
+        this._vmRunning = false;
+    }
+}
+// ---------------------------------------------------------------------------
+// Singleton
+// ---------------------------------------------------------------------------
+let helperInstance = null;
+export function initVmHelper() {
+    if (helperInstance)
+        return helperInstance;
+    helperInstance = new VmHelperClient();
+    return helperInstance;
+}
+export function getVmHelper() {
+    if (!helperInstance)
+        throw new Error("VmHelperClient not initialized");
+    return helperInstance;
+}
+//# sourceMappingURL=vm-helper-client.js.map

package/dist/vm/vm-helper.d.ts

@@ -0,0 +1,11 @@
+/**
+ * VM Helper Process — child process entry point.
+ *
+ * Runs under node-vm (signed with com.apple.security.virtualization entitlement).
+ * Loads the native addon, creates a real SessionManager, and proxies commands
+ * from the parent CLI process over Node.js IPC.
+ *
+ * Usage: node-vm dist/vm/vm-helper.js
+ */
+export {};
+//# sourceMappingURL=vm-helper.d.ts.map