@getforgeai/cli 0.1.0-beta.2 → 0.1.0-beta.3

package/dist/vm/secure-store.js

@@ -0,0 +1,110 @@
+/**
+ * Generic secure secret storage, parameterized by Keychain service / file path.
+ *
+ * Same scheme as claude-token-manager.ts:
+ *   - macOS: Keychain via the `security` CLI
+ *   - Linux/Windows: AES-256-GCM file encrypted with a machine-identity key
+ *
+ * Used by agent-auth-manager.ts for Codex / OpenCode credentials.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir, hostname, userInfo } from "node:os";
+import { join } from "node:path";
+import { createCipheriv, createDecipheriv, randomBytes, scryptSync, } from "node:crypto";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+const ALGORITHM = "aes-256-gcm";
+function filePath(location) {
+    return join(homedir(), ".forgeai", "auth", location.fileName);
+}
+function deriveKey(location) {
+    const machineId = `${hostname()}:${userInfo().username}`;
+    return scryptSync(machineId, location.fileSalt, 32);
+}
+async function saveToKeychain(location, value) {
+    try {
+        await execFileAsync("security", [
+            "delete-generic-password",
+            "-s",
+            location.keychainService,
+            "-a",
+            location.keychainAccount,
+        ], { timeout: 5_000 });
+    }
+    catch {
+        /* not found — OK */
+    }
+    await execFileAsync("security", [
+        "add-generic-password",
+        "-s",
+        location.keychainService,
+        "-a",
+        location.keychainAccount,
+        "-w",
+        value,
+        "-U",
+    ], { timeout: 5_000 });
+}
+async function loadFromKeychain(location) {
+    try {
+        const { stdout } = await execFileAsync("security", [
+            "find-generic-password",
+            "-s",
+            location.keychainService,
+            "-a",
+            location.keychainAccount,
+            "-w",
+        ], { timeout: 5_000 });
+        const value = stdout.trim();
+        return value || null;
+    }
+    catch {
+        return null;
+    }
+}
+function saveToFile(location, value) {
+    const key = deriveKey(location);
+    const iv = randomBytes(16);
+    const cipher = createCipheriv(ALGORITHM, key, iv);
+    let encrypted = cipher.update(value, "utf-8", "hex");
+    encrypted += cipher.final("hex");
+    const authTag = cipher.getAuthTag().toString("hex");
+    const dir = join(homedir(), ".forgeai", "auth");
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    writeFileSync(filePath(location), JSON.stringify({ iv: iv.toString("hex"), authTag, encrypted }), { mode: 0o600 });
+}
+function loadFromFile(location) {
+    const path = filePath(location);
+    if (!existsSync(path))
+        return null;
+    try {
+        const data = JSON.parse(readFileSync(path, "utf-8"));
+        const key = deriveKey(location);
+        const decipher = createDecipheriv(ALGORITHM, key, Buffer.from(data.iv, "hex"));
+        decipher.setAuthTag(Buffer.from(data.authTag, "hex"));
+        let decrypted = decipher.update(data.encrypted, "hex", "utf-8");
+        decrypted += decipher.final("utf-8");
+        return decrypted;
+    }
+    catch {
+        return null;
+    }
+}
+/** Store a secret. Keychain on macOS, encrypted file elsewhere. */
+export async function saveSecret(location, value) {
+    if (process.platform === "darwin") {
+        await saveToKeychain(location, value);
+    }
+    else {
+        saveToFile(location, value);
+    }
+}
+/** Load a secret. Returns null if not found or unreadable. */
+export async function loadSecret(location) {
+    if (process.platform === "darwin") {
+        return loadFromKeychain(location);
+    }
+    return loadFromFile(location);
+}
+//# sourceMappingURL=secure-store.js.map

package/dist/vm/session-manager.d.ts

@@ -32,6 +32,13 @@ export type SessionState = {
      * never logged. Passed to the in-container relay via FORGEAI_MCP_TOKEN.
      */
     mcpSecret: string;
+    /**
+     * Agent engine this session's container was provisioned for (config file,
+     * credentials, on-disk session state). Set at first spawn; same-container
+     * resumes must keep using it even if the CLI's configured engine changed
+     * in the meantime.
+     */
+    agentType?: string;
     /**
      * Git credential for this session's repo, resolved from the host credential
      * helper at clone time. Kept in memory only (never written to disk or
@@ -49,6 +56,8 @@ export declare class SessionManager {
     private dockerReady;
     private claudeOAuthToken;
     private tokenLoadedAt;
+    /** Cached Codex/OpenCode credentials, re-read hourly and on refreshToken(). */
+    private agentAuthCache;
     /**
      * Ensure Docker is available and image is ready.
      * Idempotent: if already checked, returns immediately.
@@ -89,7 +98,26 @@ export declare class SessionManager {
      * Spawn an agent inside the container.
      * Returns a DockerProcessProxy that satisfies the AgentProcess interface.
      */
-    spawnAgent(taskId: string, cmd: string, args: string[], env?: Record<string, string>): Promise<DockerProcessProxy>;
+    spawnAgent(taskId: string, cmd: string, args: string[], env?: Record<string, string>, agentType?: string): Promise<DockerProcessProxy>;
+    /**
+     * Secret env vars for an agent spawn, per engine:
+     *   - CLAUDE_CODE: long-lived OAuth token via CLAUDE_CODE_OAUTH_TOKEN
+     *   - OPENCODE (api_key): the provider's standard env var (ANTHROPIC_API_KEY, ...)
+     *   - CODEX / OPENCODE (auth_json): nothing — credentials were materialized
+     *     into the container home by materializeAgentAuth()
+     */
+    private getAgentSecretEnv;
+    /** Load (and cache) stored Codex/OpenCode credentials, or throw with a fix hint. */
+    private getAgentAuth;
+    /**
+     * Materialize agent credentials inside the container home when the engine
+     * reads them from disk rather than env vars:
+     *   - CODEX api_key: `codex login --with-api-key` (writes ~/.codex/auth.json)
+     *   - CODEX / OPENCODE auth_json: write the imported auth.json
+     * The secret travels via secretEnv (name-only -e), never via argv, and is
+     * written inside the container filesystem — not on the /session host volume.
+     */
+    materializeAgentAuth(taskId: string, agentType: string): Promise<void>;
     /**
      * Kill an agent process.
      */
@@ -106,11 +134,11 @@ export declare class SessionManager {
     getAllSessions(): SessionState[];
     isVmRunning(): boolean;
     /**
-     * Reload token from Keychain/file. Called after auth errors to pick up
-     * a refreshed token without restarting the CLI.
-     * Returns true if a new token was loaded.
+     * Reload credentials from Keychain/file. Called after auth errors to pick up
+     * refreshed credentials without restarting the CLI.
+     * Returns true if new credentials were loaded.
      */
-    refreshToken(): Promise<boolean>;
+    refreshToken(agentType?: string): Promise<boolean>;
     /**
      * Look up a session by taskId (primary key) or by sessionId (fallback).
      */

package/dist/vm/session-manager.js

@@ -24,6 +24,8 @@ import { gitCredentialConfigArgs, gitCredentialSecretEnv, } from "./git-credenti
 import { ensureImage, FORGEAI_IMAGE } from "./image-manager.js";
 import { vmLog } from "./log.js";
 import { ensureClaudeToken } from "./claude-token-manager.js";
+import { AGENT_AUTH_JSON_PATHS, loadAgentAuth, } from "./agent-auth-manager.js";
+import { getAgentProfile, resolveAgentType, } from "../orchestrator/agent-profiles.js";
 // ---------------------------------------------------------------------------
 // Paths
 // ---------------------------------------------------------------------------
@@ -59,6 +61,8 @@ export class SessionManager {
     dockerReady = false;
     claudeOAuthToken = "";
     tokenLoadedAt = 0;
+    /** Cached Codex/OpenCode credentials, re-read hourly and on refreshToken(). */
+    agentAuthCache = {};
     // -------------------------------------------------------------------------
     // VM lifecycle (now Docker)
     // -------------------------------------------------------------------------
@@ -67,11 +71,16 @@ export class SessionManager {
      * Idempotent: if already checked, returns immediately.
      */
     async ensureVmRunning() {
-        // Re-read token from Keychain every hour (catches external refresh via setup-claude)
+        // Re-read credentials from Keychain every hour (catches external refresh
+        // via forge auth setup-claude / setup-codex / setup-opencode)
         if (this.dockerReady) {
             const TOKEN_REFRESH_MS = 60 * 60 * 1000; // 1 hour
             if (Date.now() - this.tokenLoadedAt > TOKEN_REFRESH_MS) {
-                await this.refreshToken();
+                this.agentAuthCache = {};
+                if (this.claudeOAuthToken) {
+                    await this.refreshToken();
+                }
+                this.tokenLoadedAt = Date.now();
             }
             return;
         }
@@ -84,8 +93,8 @@ export class SessionManager {
         await ensureImage();
         // Create host directories
         mkdirSync(SESSIONS_DIR, { recursive: true, mode: 0o700 });
-        // Obtain Claude OAuth token for container authentication
-        this.claudeOAuthToken = await ensureClaudeToken();
+        // Agent credentials are loaded lazily per engine at spawn time
+        // (getAgentSecretEnv / materializeAgentAuth).
         this.tokenLoadedAt = Date.now();
         this.dockerReady = true;
         vmLog.cyan("session-manager", "Docker ready");
@@ -284,25 +293,29 @@ export class SessionManager {
      * Spawn an agent inside the container.
      * Returns a DockerProcessProxy that satisfies the AgentProcess interface.
      */
-    async spawnAgent(taskId, cmd, args, env = {}) {
+    async spawnAgent(taskId, cmd, args, env = {}, agentType = "CLAUDE_CODE") {
         const session = this.getSession(taskId);
         if (!session)
             throw new Error(`Session for task ${taskId} not found`);
+        const profile = getAgentProfile(agentType);
         session.status = "SPAWNING";
-        // Log the full command for debugging
+        session.agentType = profile.type;
+        // Log the full command for debugging. The prompt is either the value of
+        // -p (Claude Code) or the last positional argument (Codex / OpenCode).
         const promptArgIdx = args.indexOf("-p");
-        const promptPreview = promptArgIdx >= 0 && args[promptArgIdx + 1]
-            ? `"${args[promptArgIdx + 1].slice(0, 100)}${args[promptArgIdx + 1].length > 100 ? "..." : ""}"`
-            : "(no -p)";
+        const promptArg = promptArgIdx >= 0 ? args[promptArgIdx + 1] : args[args.length - 1];
+        const promptPreview = promptArg
+            ? `"${promptArg.slice(0, 100)}${promptArg.length > 100 ? "..." : ""}"`
+            : "(no prompt)";
         const flags = args.filter((a) => a.startsWith("--")).join(" ");
-        vmLog.magenta("session-manager", `${cmd} ${flags} -p ${promptPreview}`, session.id);
+        vmLog.magenta("session-manager", `${cmd} ${flags} ${promptPreview}`, session.id);
         // Spawn the process in the container
         const dockerExecProcess = spawnInContainer(session.containerId, [cmd, ...args], {
             cwd: "/session/workspace",
-            env,
-            // The long-lived Claude token goes through secretEnv (name-only -e) so
-            // it never lands in the host process table / `ps` output.
-            secretEnv: { CLAUDE_CODE_OAUTH_TOKEN: this.claudeOAuthToken },
+            env: { ...profile.spawnEnv, ...env },
+            // Credentials go through secretEnv (name-only -e) so they never land
+            // in the host process table / `ps` output.
+            secretEnv: await this.getAgentSecretEnv(resolveAgentType(agentType)),
             user: "agent",
         });
         // Create a kill function that removes the container when the process exits
@@ -315,7 +328,7 @@ export class SessionManager {
             }
         };
         // Create proxy wrapping the docker exec process
-        const proxy = new DockerProcessProxy(session.id, dockerExecProcess, killFn);
+        const proxy = new DockerProcessProxy(session.id, dockerExecProcess, killFn, profile.authErrorPatterns, profile.authSetupHint);
         session.agentPid = proxy.pid;
         session.agentProcess = dockerExecProcess;
         session.status = "RUNNING";
@@ -323,6 +336,87 @@ export class SessionManager {
         return proxy;
     }
     // -------------------------------------------------------------------------
+    // Agent credentials
+    // -------------------------------------------------------------------------
+    /**
+     * Secret env vars for an agent spawn, per engine:
+     *   - CLAUDE_CODE: long-lived OAuth token via CLAUDE_CODE_OAUTH_TOKEN
+     *   - OPENCODE (api_key): the provider's standard env var (ANTHROPIC_API_KEY, ...)
+     *   - CODEX / OPENCODE (auth_json): nothing — credentials were materialized
+     *     into the container home by materializeAgentAuth()
+     */
+    async getAgentSecretEnv(agentType) {
+        if (agentType === "CLAUDE_CODE") {
+            if (!this.claudeOAuthToken) {
+                this.claudeOAuthToken = await ensureClaudeToken();
+                this.tokenLoadedAt = Date.now();
+            }
+            return { CLAUDE_CODE_OAUTH_TOKEN: this.claudeOAuthToken };
+        }
+        if (agentType === "OPENCODE") {
+            const auth = await this.getAgentAuth("OPENCODE");
+            if (auth.kind === "api_key") {
+                return { [auth.envVar ?? "ANTHROPIC_API_KEY"]: auth.value };
+            }
+        }
+        return {};
+    }
+    /** Load (and cache) stored Codex/OpenCode credentials, or throw with a fix hint. */
+    async getAgentAuth(agent) {
+        const cached = this.agentAuthCache[agent];
+        if (cached)
+            return cached;
+        const loaded = await loadAgentAuth(agent);
+        if (!loaded) {
+            throw new Error(`No ${agent} credentials stored. Run: ${getAgentProfile(agent).authSetupHint}`);
+        }
+        this.agentAuthCache[agent] = loaded;
+        return loaded;
+    }
+    /**
+     * Materialize agent credentials inside the container home when the engine
+     * reads them from disk rather than env vars:
+     *   - CODEX api_key: `codex login --with-api-key` (writes ~/.codex/auth.json)
+     *   - CODEX / OPENCODE auth_json: write the imported auth.json
+     * The secret travels via secretEnv (name-only -e), never via argv, and is
+     * written inside the container filesystem — not on the /session host volume.
+     */
+    async materializeAgentAuth(taskId, agentType) {
+        const resolved = resolveAgentType(agentType);
+        if (resolved === "CLAUDE_CODE")
+            return;
+        const session = this.getSession(taskId);
+        if (!session)
+            throw new Error(`Session for task ${taskId} not found`);
+        const auth = await this.getAgentAuth(resolved);
+        if (resolved === "CODEX" && auth.kind === "api_key") {
+            const result = await execInContainer(session.containerId, [
+                "bash",
+                "-c",
+                "printenv FORGE_AGENT_SECRET | codex login --with-api-key",
+            ], { secretEnv: { FORGE_AGENT_SECRET: auth.value }, timeout: 30_000 });
+            if (result.exitCode !== 0) {
+                throw new Error(`codex login failed (exit ${result.exitCode}): ${result.stderr.slice(0, 200)}`);
+            }
+            vmLog.dim("session-manager", "Codex API key configured", session.id);
+            return;
+        }
+        if (auth.kind === "auth_json") {
+            const targetPath = AGENT_AUTH_JSON_PATHS[resolved];
+            const targetDir = targetPath.slice(0, targetPath.lastIndexOf("/"));
+            const result = await execInContainer(session.containerId, [
+                "bash",
+                "-c",
+                `mkdir -p ${targetDir} && printenv FORGE_AGENT_SECRET > ${targetPath} && chmod 600 ${targetPath}`,
+            ], { secretEnv: { FORGE_AGENT_SECRET: auth.value }, timeout: 15_000 });
+            if (result.exitCode !== 0) {
+                throw new Error(`Failed to install ${resolved} auth.json (exit ${result.exitCode}): ${result.stderr.slice(0, 200)}`);
+            }
+            vmLog.dim("session-manager", `${resolved} auth.json installed`, session.id);
+        }
+        // OPENCODE api_key: injected as env var at spawn — nothing to materialize.
+    }
+    // -------------------------------------------------------------------------
     // Agent lifecycle
     // -------------------------------------------------------------------------
     /**
@@ -394,11 +488,27 @@ export class SessionManager {
         return this.dockerReady;
     }
     /**
-     * Reload token from Keychain/file. Called after auth errors to pick up
-     * a refreshed token without restarting the CLI.
-     * Returns true if a new token was loaded.
+     * Reload credentials from Keychain/file. Called after auth errors to pick up
+     * refreshed credentials without restarting the CLI.
+     * Returns true if new credentials were loaded.
      */
-    async refreshToken() {
+    async refreshToken(agentType = "CLAUDE_CODE") {
+        const resolved = resolveAgentType(agentType);
+        if (resolved === "CODEX" || resolved === "OPENCODE") {
+            const previous = this.agentAuthCache[resolved];
+            delete this.agentAuthCache[resolved];
+            const fresh = await loadAgentAuth(resolved);
+            if (!fresh) {
+                vmLog.warn("session-manager", `No ${resolved} credentials found. Run: ${getAgentProfile(resolved).authSetupHint}`);
+                return false;
+            }
+            this.agentAuthCache[resolved] = fresh;
+            const changed = !previous || JSON.stringify(previous) !== JSON.stringify(fresh);
+            if (!changed) {
+                vmLog.warn("session-manager", `${resolved} credentials unchanged — same invalid credentials. Run: ${getAgentProfile(resolved).authSetupHint}`);
+            }
+            return changed;
+        }
         const { loadClaudeToken } = await import("./claude-token-manager.js");
         const fresh = await loadClaudeToken();
         const preview = (t) => `${t.slice(0, 15)}...${t.slice(-4)}`;

package/dist/vm/session-snapshot.d.ts

@@ -1,16 +1,19 @@
 /**
- * Session snapshot: save and restore Claude Code session files for workflow resume.
+ * Session snapshot: save and restore agent session state 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/)
+ *   2. Tar the agent's session state dir (profile.stateDir, e.g. ~/.claude,
+ *      ~/.codex, ~/.local/share/opencode) minus credentials/junk
  *   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)
+ *   2. Restore the state dir (only if the snapshot was produced by the same
+ *      agent engine — see the .forgeai-agent-type marker)
+ *   3. Launch the engine's continue command (full context restored)
  */
+import type { AgentProfile } from "../orchestrator/agent-profiles.js";
 import { type GitCredentials } from "./git-credentials.js";
 import type { SessionState } from "./session-manager.js";
 /**
@@ -19,13 +22,15 @@ import type { SessionState } from "./session-manager.js";
  */
 export declare function autoSaveCode(containerId: string, sessionId?: string, credentials?: GitCredentials): Promise<void>;
 /**
- * Save Claude Code session files from the container to a base64 tar.gz string.
+ * Save agent session state 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 declare function createSessionSnapshot(session: SessionState): Promise<string | null>;
+export declare function createSessionSnapshot(session: SessionState, profile: AgentProfile): Promise<string | null>;
 /**
- * Restore Claude Code session files into a container from a base64 tar.gz string.
+ * Restore agent session state into a container from a base64 tar.gz string.
+ * Returns false (without extracting into the live state dir) when the
+ * snapshot was produced by a different agent engine.
  */
-export declare function restoreSessionSnapshot(session: SessionState, snapshotBase64: string): Promise<boolean>;
+export declare function restoreSessionSnapshot(session: SessionState, snapshotBase64: string, profile: AgentProfile): Promise<boolean>;
 //# sourceMappingURL=session-snapshot.d.ts.map

package/dist/vm/session-snapshot.js

@@ -1,15 +1,17 @@
 /**
- * Session snapshot: save and restore Claude Code session files for workflow resume.
+ * Session snapshot: save and restore agent session state 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/)
+ *   2. Tar the agent's session state dir (profile.stateDir, e.g. ~/.claude,
+ *      ~/.codex, ~/.local/share/opencode) minus credentials/junk
  *   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)
+ *   2. Restore the state dir (only if the snapshot was produced by the same
+ *      agent engine — see the .forgeai-agent-type marker)
+ *   3. Launch the engine's continue command (full context restored)
  */
 import { readFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
@@ -18,6 +20,14 @@ import { gitCredentialConfigShellFragment, gitCredentialSecretEnv, } from "./git
 import { vmLog } from "./log.js";
 /** Max snapshot size: 5MB compressed */
 const MAX_SNAPSHOT_SIZE = 5 * 1024 * 1024;
+/** Tarball transport name on the /session volume. */
+const SNAPSHOT_TAR = "agent-session.tar.gz";
+/**
+ * Marker file inside the snapshot recording which engine produced it, so a
+ * snapshot taken under one agent type is never restored into another engine's
+ * state dir (the restore falls back to the prompt-based resume instead).
+ */
+const AGENT_TYPE_MARKER = ".forgeai-agent-type";
 /**
  * Auto-save code changes in the container (best-effort git commit + push).
  * Does not throw — failures are logged and ignored.
@@ -87,28 +97,29 @@ export async function autoSaveCode(containerId, sessionId, credentials) {
     }
 }
 /**
- * Save Claude Code session files from the container to a base64 tar.gz string.
+ * Save agent session state 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) {
+export async function createSessionSnapshot(session, profile) {
     const sessionId = session.id;
+    const stateDir = profile.stateDir;
     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.
+        // Tar the engine's session state dir (e.g. ~/.claude for Claude Code:
+        // --continue needs history.jsonl + projects/<encoded-path>/ session files).
+        // Exclude credentials and non-session files to keep size small and to
+        // never ship secrets to the Cloud. A marker file records the engine so a
+        // restore under a different agent type is rejected.
+        const excludes = profile.snapshotExcludes
+            .map((pattern) => `--exclude='${pattern}'`)
+            .join(" ");
         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'" +
-                    " .",
+                `test -d ${stateDir} || exit 0`,
+                `printf '%s' '${profile.type}' > ${stateDir}/${AGENT_TYPE_MARKER}`,
+                `tar czf /session/${SNAPSHOT_TAR} -C ${stateDir} ${excludes} .`,
             ].join(" && "),
         ], { timeout: 30_000 });
         if (tarResult.exitCode !== 0) {
@@ -116,9 +127,9 @@ export async function createSessionSnapshot(session) {
             return null;
         }
         // Read the tar from the host volume
-        const tarPath = join(session.sessionDir, "claude-session.tar.gz");
+        const tarPath = join(session.sessionDir, SNAPSHOT_TAR);
         if (!existsSync(tarPath)) {
-            vmLog.dim("session-snapshot", "No Claude session directory found in container, skipping snapshot", sessionId);
+            vmLog.dim("session-snapshot", `No ${profile.type} session directory found in container, skipping snapshot`, sessionId);
             return null;
         }
         const tarBuffer = readFileSync(tarPath);
@@ -136,28 +147,33 @@ export async function createSessionSnapshot(session) {
     }
 }
 /**
- * Restore Claude Code session files into a container from a base64 tar.gz string.
+ * Restore agent session state into a container from a base64 tar.gz string.
+ * Returns false (without extracting into the live state dir) when the
+ * snapshot was produced by a different agent engine.
  */
-export async function restoreSessionSnapshot(session, snapshotBase64) {
+export async function restoreSessionSnapshot(session, snapshotBase64, profile) {
     const sessionId = session.id;
+    const stateDir = profile.stateDir;
     try {
         // Write the tar to the host volume
-        const tarPath = join(session.sessionDir, "claude-session.tar.gz");
+        const tarPath = join(session.sessionDir, SNAPSHOT_TAR);
         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",
+        // Check the engine marker before touching the state dir. Snapshots from
+        // before the marker existed were always Claude Code.
+        const markerResult = await execInContainer(session.containerId, [
+            "bash",
+            "-c",
+            `tar -xzf /session/${SNAPSHOT_TAR} -O ./${AGENT_TYPE_MARKER} 2>/dev/null || printf 'CLAUDE_CODE'`,
         ], { timeout: 30_000 });
+        const snapshotAgentType = markerResult.stdout.trim() || "CLAUDE_CODE";
+        if (snapshotAgentType !== profile.type) {
+            vmLog.warn("session-snapshot", `Snapshot was taken with ${snapshotAgentType}, current engine is ${profile.type} — skipping restore`, sessionId);
+            return false;
+        }
+        // Create the target directory and extract
+        await execInContainer(session.containerId, ["mkdir", "-p", stateDir]);
+        const extractResult = await execInContainer(session.containerId, ["tar", "xzf", `/session/${SNAPSHOT_TAR}`, "-C", stateDir], { 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;
@@ -167,9 +183,9 @@ export async function restoreSessionSnapshot(session, snapshotBase64) {
             "chown",
             "-R",
             "agent:agent",
-            "/home/agent/.claude",
+            stateDir,
         ]);
-        vmLog.cyan("session-snapshot", "Restored Claude session snapshot", sessionId);
+        vmLog.cyan("session-snapshot", `Restored ${profile.type} session snapshot`, sessionId);
         return true;
     }
     catch (err) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getforgeai/cli",
-  "version": "0.1.0-beta.2",
+  "version": "0.1.0-beta.3",
   "description": "ForgeAI CLI — runs AI coding agents in local Docker containers with your own AI tokens, and connects them to the ForgeAI cockpit.",
   "license": "Apache-2.0",
   "type": "module",
@@ -47,7 +47,7 @@
     "ora": "^8.2.0",
     "socket.io-client": "^4.8.3",
     "zod": "^4.3.6",
-    "@getforgeai/protocol": "0.1.0-beta.1"
+    "@getforgeai/protocol": "0.1.0-beta.2"
   },
   "devDependencies": {
     "@types/node": "^25.0.2",

package/rootfs/Dockerfile

@@ -18,8 +18,11 @@ RUN curl -fsSL https://deb.nodesource.com/gpgkey/nodesource-repo.gpg.key | \
     apt-get install -y -qq nodejs && \
     rm -rf /var/lib/apt/lists/*
 
-# Claude Code CLI
-RUN npm install -g @anthropic-ai/claude-code 2>&1 | tail -3
+# Agent CLIs: Claude Code (primary), Codex and OpenCode (alternative engines).
+# No output pipe: `| tail` would mask npm failures (pipeline exit = tail's).
+# The `command -v` checks make a partial install fail the build loudly.
+RUN npm install -g --loglevel=error @anthropic-ai/claude-code @openai/codex opencode-ai && \
+    command -v claude && command -v codex && command -v opencode
 
 # ForgeAI MCP relay (baked-in copy for reference only — at runtime the CLI
 # stages its own copy into /session/forge-mcp-relay.mjs so the relay version