@provos/ironcurtain 0.11.0 → 0.12.0

package/dist/docker/docker-infrastructure.js

@@ -14,13 +14,14 @@ import { quote } from 'shell-quote';
 import { getBundleRuntimeRoot } from '../config/paths.js';
 import { getBundleShortId } from '../session/types.js';
 import { DEFAULT_CONTAINER_SCOPE } from '../workflow/types.js';
-import { CONTAINER_WORKSPACE_DIR, } from './agent-adapter.js';
+import { CONTAINER_SCRIPTS_DIR, CONTAINER_WORKSPACE_DIR, } from './agent-adapter.js';
 import { parseUpstreamBaseUrl } from './provider-config.js';
 import { getInternalNetworkName } from './platform.js';
 import { cleanupContainers } from './container-lifecycle.js';
 import { clampDockerResources } from './resource-limits.js';
 import { errorMessage } from '../utils/error-message.js';
 import { createCachedStager } from '../skills/staging.js';
+import { withProvisionLock } from './provision-lock.js';
 import * as logger from '../logger.js';
 /**
  * Create a bundle-owned directory and enforce 0o700 permissions even if
@@ -64,29 +65,19 @@ export function ensureSecureBundleDir(path) {
 }
 /** Hosts that use Anthropic OAuth credentials when available. */
 const ANTHROPIC_HOSTS = new Set(['api.anthropic.com', 'platform.claude.com']);
+/** Hosts that use Codex ChatGPT OAuth credentials when available. */
+const CODEX_CHATGPT_HOSTS = new Set(['chatgpt.com', 'auth.openai.com']);
 /** Prefix for container/sidecar names. Keep in sync with `docker ps` filters. */
 const CONTAINER_NAME_PREFIX = 'ironcurtain-';
 /** Host gateway alias used by Docker containers on macOS/Windows. */
 const DOCKER_HOST_GATEWAY = 'host.docker.internal';
 /** Bundle-relative subdir name for the skills staging dir. */
 const BUNDLE_SKILLS_SUBDIR = 'skills';
-/**
- * Prepares the shared (non-container) parts of Docker session infrastructure.
- *
- * Sets up proxies (Code Mode + MITM), CA, fake keys, orientation files, and
- * ensures the agent image. Does NOT create the agent container — that step is
- * specific to the session mode: standalone sessions go through
- * `createDockerInfrastructure()` (which wraps this with `sleep infinity`
- * container creation); PTY sessions call this directly and then create their
- * own TTY-enabled container.
- *
- * `workflowId` drives Docker labelling: when set, the main container (and
- * any sidecar created during `createSessionContainers`) carries
- * `ironcurtain.workflow=<workflowId>` + `ironcurtain.scope=<scope>`
- * alongside the always-present `ironcurtain.bundle=<bundleId>`. When
- * unset, only `ironcurtain.bundle` is emitted (standalone CLI / PTY).
- */
-export async function prepareDockerInfrastructure(config, mode, bundleDir, workspaceDir, escalationDir, bundleId, workflowId, scope, resolvedSkills) {
+/** Container path for runtime-provisioned workflow Python dependencies. */
+const WORKFLOW_PYTHON_VENV_DIR = '/opt/workflow-venv';
+/** Container path for runtime-provisioned workflow Node dependencies. */
+const WORKFLOW_NODE_MODULES_DIR = '/opt/workflow-node_modules';
+export async function prepareDockerInfrastructure(config, mode, bundleDir, workspaceDir, escalationDir, bundleId, workflowId, scope, resolvedSkills, captureInput, scriptsDir) {
     // The audit log path is read from config so the bundle is
     // self-describing: downstream consumers (AuditLogTailer, sandbox
     // coordinator) can take it from either `config.auditLogPath` or
@@ -98,16 +89,18 @@ export async function prepareDockerInfrastructure(config, mode, bundleDir, works
     const { createMitmProxy } = await import('./mitm-proxy.js');
     const { loadOrCreateCA } = await import('./ca.js');
     const { generateFakeKey } = await import('./fake-keys.js');
-    const { createDockerManager } = await import('./docker-manager.js');
-    const { useTcpTransport } = await import('./platform.js');
+    const { createContainerRuntime, resolveRuntimeKind } = await import('./container-runtime.js');
+    const { resolveNetworkTopology, createHostOnlyNetwork, makeSourceAddressGuard } = await import('./network-topology.js');
     const { getIronCurtainHome } = await import('../config/paths.js');
     const { prepareSession } = await import('./orientation.js');
-    const { detectAuthMethod, writeToKeychain } = await import('./oauth-credentials.js');
+    const { detectAuthMethod, writeToKeychain, getCodexAuthFilePath, loadCodexOAuthCredentials, refreshCodexOAuthToken, refreshResultToCreds, saveCodexOAuthCredentials, } = await import('./oauth-credentials.js');
     const { OAuthTokenManager } = await import('./oauth-token-manager.js');
     const { getBundleSocketsDir, getBundleHostOnlyDir, getBundleProxySocketPath, getBundleMitmProxySocketPath, getBundleMitmControlSocketPath, } = await import('../config/paths.js');
     await registerBuiltinAdapters(config.userConfig);
     const adapter = getAgent(mode.agent);
-    const useTcp = useTcpTransport();
+    const runtimeKind = await resolveRuntimeKind(config.userConfig.containerRuntime);
+    const topology = resolveNetworkTopology(runtimeKind);
+    const useTcp = topology !== 'uds';
     // Detect authentication method. Adapters with detectCredential() handle
     // their own credential detection (e.g., Goose checks provider-specific keys).
     // Adapters without it fall back to detectAuthMethod() (Anthropic OAuth + API key).
@@ -142,10 +135,26 @@ export async function prepareDockerInfrastructure(config, mode, bundleDir, works
     ensureSecureBundleDir(socketsDir);
     ensureSecureBundleDir(hostOnlyDir);
     const socketPath = getBundleProxySocketPath(bundleId);
+    const docker = createContainerRuntime(runtimeKind);
+    // tcp-hostonly: create the per-bundle host-only network BEFORE the
+    // proxies are constructed. The gateway address feeds the container env,
+    // the orientation proxy address, and the connection-source guard both
+    // proxies use while listening on 0.0.0.0 (the vmnet gateway interface
+    // only materializes once the first container attaches, so binding the
+    // gateway address directly is not possible at this point).
+    let hostOnlyNetwork;
+    let allowRemoteAddress;
+    if (topology === 'tcp-hostonly') {
+        hostOnlyNetwork = await createHostOnlyNetwork(docker, getInternalNetworkName(getBundleShortId(bundleId)));
+        allowRemoteAddress = makeSourceAddressGuard(hostOnlyNetwork.subnet);
+        logger.info(`Host-only network ${hostOnlyNetwork.name} (${hostOnlyNetwork.subnet}, gateway ${hostOnlyNetwork.gateway})`);
+    }
     const proxy = createCodeModeProxy({
         socketPath,
         config,
         listenMode: useTcp ? 'tcp' : 'uds',
+        bindHost: topology === 'tcp-hostonly' ? '0.0.0.0' : undefined,
+        allowRemoteAddress,
     });
     // Load or generate the IronCurtain CA for TLS termination
     const caDir = resolve(getIronCurtainHome(), 'ca');
@@ -158,8 +167,19 @@ export async function prepareDockerInfrastructure(config, mode, bundleDir, works
     const tokenManagerKeychainDeps = authMethod.kind === 'oauth' && authMethod.source === 'keychain'
         ? { writeToKeychain, keychainServiceName: authMethod.keychainServiceName }
         : undefined;
+    const tokenManagerCodexDeps = authMethod.kind === 'oauth' && adapter.id === 'codex'
+        ? {
+            loadCredentials: loadCodexOAuthCredentials,
+            refreshToken: async (rt) => refreshResultToCreds(await refreshCodexOAuthToken(rt)),
+            saveCredentials: saveCodexOAuthCredentials,
+            credentialsFilePath: getCodexAuthFilePath(),
+        }
+        : undefined;
     const tokenManager = authMethod.kind === 'oauth'
-        ? new OAuthTokenManager(authMethod.credentials, { canRefresh: true }, tokenManagerKeychainDeps)
+        ? new OAuthTokenManager(authMethod.credentials, { canRefresh: canRefreshOAuth(authMethod.credentials.refreshToken) }, {
+            ...tokenManagerKeychainDeps,
+            ...tokenManagerCodexDeps,
+        })
         : undefined;
     const providers = adapter.getProviders(authKind);
     const resolvedProviders = applyUpstreamOverrides(providers, parseUpstreamBaseUrl, {
@@ -178,8 +198,9 @@ export async function prepareDockerInfrastructure(config, mode, bundleDir, works
         }
         fakeKeys.set(providerConfig.host, fakeKey);
         const realKey = resolveRealKey(providerConfig.host, config, oauthAccessToken);
-        // Attach the token manager only to Anthropic hosts (the ones using OAuth)
-        const hostTokenManager = tokenManager && ANTHROPIC_HOSTS.has(providerConfig.host) ? tokenManager : undefined;
+        const isManagedOAuthHost = ANTHROPIC_HOSTS.has(providerConfig.host) ||
+            (adapter.id === 'codex' && CODEX_CHATGPT_HOSTS.has(providerConfig.host));
+        const hostTokenManager = tokenManager && isManagedOAuthHost ? tokenManager : undefined;
         providerMappings.push({ config: providerConfig, fakeKey, realKey, tokenManager: hostTokenManager });
     }
     // Build package installation proxy config if enabled
@@ -187,9 +208,9 @@ export async function prepareDockerInfrastructure(config, mode, bundleDir, works
     let registries;
     let packageValidation;
     if (pkgConfig.enabled) {
-        const { npmRegistry, pypiRegistry, debianRegistry } = await import('./registry-proxy.js');
+        const { npmRegistry, pypiRegistry, debianRegistry, cargoRegistry } = await import('./registry-proxy.js');
         const { createPackageValidator } = await import('./package-validator.js');
-        registries = [npmRegistry, pypiRegistry, debianRegistry];
+        registries = [npmRegistry, pypiRegistry, debianRegistry, cargoRegistry];
         const validator = createPackageValidator({
             allowedPackages: pkgConfig.allowedPackages,
             deniedPackages: pkgConfig.deniedPackages,
@@ -208,6 +229,28 @@ export async function prepareDockerInfrastructure(config, mode, bundleDir, works
     // A workflow bundle serves only workflow agents for its entire lifetime,
     // so agentKind is fixed at construction time.
     const agentKind = workflowId !== undefined ? 'workflow' : undefined;
+    // Single resolution point for trajectory-capture enablement. The raw
+    // CLI/RPC override wins; otherwise fall through to config; otherwise
+    // off. Consumers pass the raw override only — they never re-resolve
+    // against `userConfig.capture?.enabled`.
+    const captureEnabled = captureInput ? (captureInput.override ?? config.userConfig.capture?.enabled ?? false) : false;
+    // Construct the trajectory-capture writer when capture is enabled.
+    // When disabled, no writer is created, no taps are installed, and the
+    // forwarding path is byte-identical to today (per §10 "zero cost when
+    // disabled").
+    let captureWriter;
+    if (captureEnabled && captureInput) {
+        const { createTrajectoryCaptureWriter } = await import('./trajectory-capture.js');
+        captureWriter = createTrajectoryCaptureWriter({ capturesDir: captureInput.capturesDir });
+    }
+    const captureProxyOptions = captureWriter
+        ? {
+            capture: captureWriter,
+            recordedAgentName: captureInput?.recordedAgentName,
+            workflowRunId: captureInput?.workflowRunId,
+            bundleId: String(bundleId),
+        }
+        : {};
     const mitmProxy = useTcp
         ? createMitmProxy({
             listenPort: 0,
@@ -216,8 +259,10 @@ export async function prepareDockerInfrastructure(config, mode, bundleDir, works
             registries,
             packageValidation,
             controlPort: 0,
-            sessionId: routingId,
+            initialTokenSessionId: routingId,
             agentKind,
+            allowRemoteAddress,
+            ...captureProxyOptions,
         })
         : createMitmProxy({
             socketPath: getBundleMitmProxySocketPath(bundleId),
@@ -226,16 +271,18 @@ export async function prepareDockerInfrastructure(config, mode, bundleDir, works
             registries,
             packageValidation,
             controlSocketPath: getBundleMitmControlSocketPath(bundleId),
-            sessionId: routingId,
+            initialTokenSessionId: routingId,
             agentKind,
+            ...captureProxyOptions,
         });
-    const docker = createDockerManager();
     // Start MITM proxy FIRST so config.mitmControlAddr is set before proxy.start().
     // proxy.start() initializes the UTCP sandbox, which checks config.mitmControlAddr
     // to decide whether to register the proxy virtual MCP server for domain management.
     const mitmAddr = await mitmProxy.start();
     if (mitmAddr.port !== undefined) {
-        logger.info(`MITM proxy listening on 127.0.0.1:${mitmAddr.port}`);
+        logger.info(hostOnlyNetwork
+            ? `MITM proxy listening on ${hostOnlyNetwork.gateway}:${mitmAddr.port} (0.0.0.0, subnet-guarded)`
+            : `MITM proxy listening on 127.0.0.1:${mitmAddr.port}`);
     }
     else {
         logger.info(`MITM proxy listening on ${mitmAddr.socketPath}`);
@@ -254,7 +301,9 @@ export async function prepareDockerInfrastructure(config, mode, bundleDir, works
     // registers the proxy virtual server for network domain management.
     await proxy.start();
     if (useTcp && proxy.port !== undefined) {
-        logger.info(`Code Mode proxy listening on 127.0.0.1:${proxy.port}`);
+        logger.info(hostOnlyNetwork
+            ? `Code Mode proxy listening on ${hostOnlyNetwork.gateway}:${proxy.port} (0.0.0.0, subnet-guarded)`
+            : `Code Mode proxy listening on 127.0.0.1:${proxy.port}`);
     }
     else {
         logger.info(`Code Mode proxy listening on ${proxy.socketPath}`);
@@ -277,11 +326,18 @@ export async function prepareDockerInfrastructure(config, mode, bundleDir, works
             });
         }
         logger.info(`Available servers: ${serverListings.map((s) => s.name).join(', ')}`);
-        const proxyAddress = useTcp && proxy.port !== undefined ? `${DOCKER_HOST_GATEWAY}:${proxy.port}` : undefined;
+        // The address the agent uses to reach the Code Mode proxy: the vmnet
+        // gateway on host-only networks, the Docker host alias otherwise.
+        const proxyHost = hostOnlyNetwork ? hostOnlyNetwork.gateway : DOCKER_HOST_GATEWAY;
+        const proxyAddress = useTcp && proxy.port !== undefined ? `${proxyHost}:${proxy.port}` : undefined;
         const { systemPrompt } = prepareSession(adapter, serverListings, bundleDir, config, workspaceDir, proxyAddress);
-        // Ensure Docker image is built and up-to-date
-        const image = await adapter.getImage();
-        await ensureImage(image, docker, ca);
+        // Ensure the stock agent image is built and up-to-date. Workflow
+        // dependencies are provisioned at runtime into mounted caches below;
+        // they are no longer baked into per-workflow Docker images.
+        const agentImage = await adapter.getImage();
+        const agentBuildHash = await ensureImage(agentImage, docker, ca);
+        const image = agentImage;
+        const workflowDependencyMounts = prepareWorkflowDependencyMounts(agentBuildHash, scriptsDir, getIronCurtainHome());
         const orientationDir = resolve(bundleDir, 'orientation');
         // Set up conversation state directory if the adapter supports resume
         const conversationStateConfig = adapter.getConversationStateConfig?.();
@@ -312,6 +368,11 @@ export async function prepareDockerInfrastructure(config, mode, bundleDir, works
                 logger.info(`Re-staged ${skills.length} skill(s) to ${skillsMount.hostDir}`);
             }
         };
+        let scriptsMount;
+        if (scriptsDir !== undefined && existsSync(scriptsDir)) {
+            scriptsMount = { hostDir: scriptsDir, target: CONTAINER_SCRIPTS_DIR };
+            logger.info(`Staged workflow scripts available at ${scriptsDir}`);
+        }
         return {
             bundleId,
             workflowId,
@@ -329,23 +390,62 @@ export async function prepareDockerInfrastructure(config, mode, bundleDir, works
             orientationDir,
             systemPrompt,
             image,
+            runtimeKind,
+            topology,
             useTcp,
+            hostOnlyNetwork,
             socketsDir,
             mitmAddr,
             authKind,
             conversationStateDir,
             conversationStateConfig,
             skillsMount,
+            scriptsMount,
+            ...workflowDependencyMounts,
             restageSkills,
             setTokenSessionId: (id) => {
                 mitmProxy.setTokenSessionId(id);
             },
+            // Trajectory-capture lifecycle. When captureWriter is undefined
+            // (capture disabled, the common case), every method is a cheap
+            // no-op — zero cost on the forwarding path. When set, the bundle
+            // owns the three-step atomic begin (setCaptureSessionId →
+            // setCapturePersona → writer.beginSession) and the two-phase end
+            // (writer.endSession → null out proxy attribution).
+            beginCaptureSession: (opts) => {
+                if (!captureWriter)
+                    return;
+                mitmProxy.setCaptureSessionId(opts.sessionId);
+                mitmProxy.setCapturePersona(opts.persona);
+                captureWriter.beginSession(opts);
+            },
+            endCaptureSession: async (sessionId) => {
+                if (!captureWriter)
+                    return;
+                try {
+                    await captureWriter.endSession(sessionId);
+                }
+                finally {
+                    // Clear proxy attribution AFTER the drain settles so any
+                    // late-arriving response chunks already in flight are still
+                    // attributed to the correct session.
+                    mitmProxy.setCaptureSessionId(undefined);
+                    mitmProxy.setCapturePersona(undefined);
+                }
+            },
+            captureWriter,
         };
     }
     catch (error) {
         // Best-effort cleanup of proxies started above
         await mitmProxy.stop().catch(() => { });
         await proxy.stop().catch(() => { });
+        // Host-only network was created before the proxies; remove it too.
+        // (A leak through the narrow window before this catch is self-healing:
+        // createHostOnlyNetwork removes the stale same-named network first.)
+        if (hostOnlyNetwork) {
+            await docker.removeNetwork(hostOnlyNetwork.name).catch(() => { });
+        }
         throw error;
     }
 }
@@ -358,16 +458,27 @@ export async function prepareDockerInfrastructure(config, mode, bundleDir, works
  * failure after the proxies are started, all started resources are torn
  * down before the error propagates.
  */
-export async function createDockerInfrastructure(config, mode, bundleDir, workspaceDir, escalationDir, bundleId, workflowId, scope, resolvedSkills) {
-    const core = await prepareDockerInfrastructure(config, mode, bundleDir, workspaceDir, escalationDir, bundleId, workflowId, scope, resolvedSkills);
+export async function createDockerInfrastructure(config, mode, bundleDir, workspaceDir, escalationDir, bundleId, workflowId, scope, resolvedSkills, captureInput, scriptsDir, options) {
+    const core = await prepareDockerInfrastructure(config, mode, bundleDir, workspaceDir, escalationDir, bundleId, workflowId, scope, resolvedSkills, captureInput, scriptsDir);
+    let containerResources;
     try {
-        const containerResources = await createSessionContainers(core, config);
-        return { ...core, ...containerResources };
+        containerResources = await createSessionContainers(core, config, options);
+        const infra = { ...core, ...containerResources };
+        await provisionWorkflowDependencies(infra, config.userConfig.packageInstall.enabled);
+        return infra;
     }
     catch (error) {
         // Any partial container/sidecar/network cleanup happened inside
-        // createSessionContainers(). Here we just tear down the proxies that
-        // prepareDockerInfrastructure() started, to avoid leaking them.
+        // createSessionContainers(). If provisioning failed after a complete
+        // container bundle was created, clean that bundle here before tearing
+        // down the proxies.
+        if (containerResources) {
+            await cleanupContainers(core.docker, {
+                containerId: containerResources.containerId,
+                sidecarContainerId: containerResources.sidecarContainerId ?? null,
+                networkName: containerResources.internalNetwork ?? null,
+            });
+        }
         await core.mitmProxy.stop().catch(() => { });
         await core.proxy.stop().catch(() => { });
         throw error;
@@ -409,6 +520,17 @@ export async function destroyDockerInfrastructure(infra) {
             .stop()
             .catch((err) => logger.warn(`destroyDockerInfrastructure: proxy.stop() failed: ${errorMessage(err)}`)),
     ]);
+    // Trajectory-capture safety net (§9): close the writer AFTER the proxies
+    // have stopped, so no more records arrive mid-close. The writer emits
+    // synthetic `session-end` entries (with `closedReason:
+    // 'infrastructure-teardown'`) for any session whose explicit
+    // endCaptureSession was not called — covering Ctrl-C / abort / crash
+    // paths where the orchestrator's `finally` did not run.
+    if (infra.captureWriter) {
+        await infra.captureWriter
+            .close()
+            .catch((err) => logger.warn(`destroyDockerInfrastructure: captureWriter.close() failed: ${errorMessage(err)}`));
+    }
     // CA and fake keys are intentionally absent: neither owns any
     // process-level resources. CA material is persisted in ~/.ironcurtain/ca/
     // and reused across sessions; fake keys are just strings in a Map that
@@ -488,9 +610,9 @@ export function buildAgentUidRemap(useTcp) {
  *
  * Exported for testability: tests exercise the mount/env configuration and
  * the rollback-on-failure path by passing a mock `PreContainerInfrastructure`
- * with a scripted `DockerManager`.
+ * with a scripted `ContainerRuntime`.
  */
-export async function createSessionContainers(core, config) {
+export async function createSessionContainers(core, config, options) {
     const shortId = getBundleShortId(core.bundleId);
     const mainContainerName = `${CONTAINER_NAME_PREFIX}${shortId}`;
     // Labels applied to every IronCurtain-owned container (main + sidecar).
@@ -507,6 +629,9 @@ export async function createSessionContainers(core, config) {
     let sidecarContainerId;
     let internalNetwork;
     try {
+        const mainImage = options?.baseImageOverride && (await core.docker.imageExists(options.baseImageOverride))
+            ? options.baseImageOverride
+            : core.image;
         // Base mounts shared by TCP and UDS modes: the sandbox as the
         // workspace and the orientation dir. Mode-specific mounts (apt proxy
         // config, sockets dir, conversation state) are appended below.
@@ -519,7 +644,34 @@ export async function createSessionContainers(core, config) {
         };
         let network;
         let extraHosts;
-        if (core.useTcp && core.mitmAddr.port !== undefined && core.proxy.port !== undefined) {
+        // tcp-hostonly only: apt proxy config to write into the container via
+        // exec after start. Apple container's virtiofs shares directories
+        // only — the single-file bind mount the Docker topologies use for
+        // /etc/apt/apt.conf.d/90-ironcurtain-proxy is rejected with
+        // "path ... is not a directory".
+        let hostOnlyAptProxyUrl;
+        if (core.topology === 'tcp-hostonly') {
+            // Apple container host-only mode: the agent VM reaches the host
+            // proxies directly at the vmnet gateway address. No sidecar, no
+            // extra host mappings — egress is blocked at the network layer
+            // (`--internal`) and verified by the connectivity check below.
+            if (core.hostOnlyNetwork === undefined || core.mitmAddr.port === undefined || core.proxy.port === undefined) {
+                throw new Error('tcp-hostonly bundle is missing its host-only network or proxy ports');
+            }
+            const proxyUrl = `http://${core.hostOnlyNetwork.gateway}:${core.mitmAddr.port}`;
+            env = {
+                ...env,
+                HTTPS_PROXY: proxyUrl,
+                HTTP_PROXY: proxyUrl,
+            };
+            hostOnlyAptProxyUrl = proxyUrl;
+            network = core.hostOnlyNetwork.name;
+            // Report the host-only network as `internalNetwork` so the standard
+            // teardown paths (destroyDockerInfrastructure, rollback below)
+            // remove it with the containers.
+            internalNetwork = core.hostOnlyNetwork.name;
+        }
+        else if (core.topology === 'tcp-sidecar' && core.mitmAddr.port !== undefined && core.proxy.port !== undefined) {
             // macOS TCP mode: internal bridge network blocks egress.
             // A socat sidecar bridges the internal network to the host
             // because Docker Desktop VMs don't forward gateway traffic.
@@ -614,6 +766,23 @@ export async function createSessionContainers(core, config) {
         if (core.skillsMount) {
             mounts.push({ source: core.skillsMount.hostDir, target: core.skillsMount.target, readonly: true });
         }
+        if (core.scriptsMount) {
+            mounts.push({ source: core.scriptsMount.hostDir, target: core.scriptsMount.target, readonly: true });
+        }
+        if (core.workflowPythonVenvMount) {
+            mounts.push({
+                source: core.workflowPythonVenvMount.hostDir,
+                target: core.workflowPythonVenvMount.target,
+                readonly: false,
+            });
+        }
+        if (core.workflowNodeModulesMount) {
+            mounts.push({
+                source: core.workflowNodeModulesMount.hostDir,
+                target: core.workflowNodeModulesMount.target,
+                readonly: false,
+            });
+        }
         // Linux-only UID-remap wiring (issue #232). On Linux, run the
         // container as root and pass the host UID/GID via env so the
         // entrypoint can renumber codespace before dropping privileges.
@@ -627,11 +796,22 @@ export async function createSessionContainers(core, config) {
         // "no flag emitted" (see clampDockerResources docs).
         const { effective: containerResources } = clampDockerResources(config.userConfig.dockerResources);
         mainContainerId = await core.docker.create({
-            image: core.image,
+            image: mainImage,
             name: mainContainerName,
             network: network ?? 'none',
             mounts,
-            env: { ...env, ...uidRemap.env },
+            env: {
+                ...env,
+                // Do NOT override PATH here. Docker `-e PATH=...` REPLACES the image's
+                // PATH (it does not append), which would discard the base image's real
+                // PATH — including the NVM directory where `node`/`npm` live on the x86
+                // devcontainer base. Bare-`node` workflow helpers would then fail to
+                // resolve. The workflow venv bin is instead prepended to the live
+                // `$PATH` at exec time (see buildWorkflowExecCommand), which is
+                // base-image-agnostic and preserves the image's own PATH.
+                ...(core.workflowNodeModulesMount ? { NODE_PATH: core.workflowNodeModulesMount.target } : {}),
+                ...uidRemap.env,
+            },
             user: uidRemap.user,
             command: ['sleep', 'infinity'],
             ...bundleLabels,
@@ -648,9 +828,19 @@ export async function createSessionContainers(core, config) {
         });
         await core.docker.start(mainContainerId);
         logger.info(`Container started: ${mainContainerId.substring(0, 12)}`);
+        // tcp-hostonly: write the apt proxy config inside the container (the
+        // Docker topologies bind-mount it; see hostOnlyAptProxyUrl above).
+        if (hostOnlyAptProxyUrl !== undefined) {
+            await writeHostOnlyAptProxyConfig(core.docker, mainContainerId, hostOnlyAptProxyUrl);
+        }
         // Connectivity check: verify the container can reach host proxies
-        // through the internal network. Abort if unreachable.
-        if (core.useTcp && internalNetwork !== undefined && core.proxy.port !== undefined) {
+        // through the internal network. Abort if unreachable. Host-only
+        // bundles additionally assert the inverse — internet egress must be
+        // blocked — and never fall back to a weaker configuration.
+        if (core.topology === 'tcp-hostonly' && core.hostOnlyNetwork !== undefined && core.proxy.port !== undefined) {
+            await checkHostOnlyConnectivity(core.docker, mainContainerId, core.hostOnlyNetwork.gateway, core.proxy.port);
+        }
+        else if (core.useTcp && internalNetwork !== undefined && core.proxy.port !== undefined) {
             await checkInternalNetworkConnectivity(core.docker, mainContainerId, core.proxy.port);
         }
         return {
@@ -687,16 +877,76 @@ async function checkInternalNetworkConnectivity(docker, containerId, mcpPort) {
             `Check that the sidecar container is running and connected to the internal network.`);
     }
 }
+/**
+ * Writes /etc/apt/apt.conf.d/90-ironcurtain-proxy inside a running
+ * container via exec (as root). Used by the tcp-hostonly topology in
+ * both batch and PTY modes — Apple container's virtiofs shares
+ * directories only, so the single-file bind mount the Docker topologies
+ * use is rejected. The URL is built from our own gateway address and
+ * OS-assigned port — runtime-generated values, not untrusted input — so
+ * embedding it in the sh script is safe.
+ */
+export async function writeHostOnlyAptProxyConfig(docker, containerId, proxyUrl) {
+    const aptWrite = await docker.exec(containerId, [
+        'sh',
+        '-c',
+        `printf 'Acquire::http::Proxy "%s";\\nAcquire::https::Proxy "%s";\\n' '${proxyUrl}' '${proxyUrl}' > /etc/apt/apt.conf.d/90-ironcurtain-proxy`,
+    ], 10_000, 'root');
+    if (aptWrite.exitCode !== 0) {
+        throw new Error(`Failed to write apt proxy config in container (exit=${aptWrite.exitCode}): ${aptWrite.stderr}`);
+    }
+}
+/**
+ * External address used to probe that internet egress is blocked. Any
+ * globally-routable address works; the check asserts the connection
+ * FAILS, so the probe never carries data off the machine on a healthy
+ * setup.
+ */
+const EGRESS_PROBE_ADDRESS = '1.1.1.1:443';
+/**
+ * Fail-closed startup gate for the tcp-hostonly topology
+ * (docs/designs/apple-container-runtime.md, design decision 4). Asserts
+ * from inside the container that (a) the host-side proxies are reachable
+ * at the vmnet gateway and (b) internet egress is blocked by the
+ * host-only network. Either failure aborts session initialization —
+ * never a silent fallback to a weaker network configuration. Shared by
+ * batch (`createSessionContainers`) and PTY (`runPtySession`) modes.
+ */
+export async function checkHostOnlyConnectivity(docker, containerId, gateway, mcpPort) {
+    const reach = await docker.exec(containerId, ['socat', '-u', '/dev/null', `TCP:${gateway}:${mcpPort},connect-timeout=5`], 6_000);
+    if (reach.exitCode !== 0) {
+        throw new Error(`Host-only network connectivity check failed (exit=${reach.exitCode}). ` +
+            `The container cannot reach host-side proxies at gateway ${gateway}:${mcpPort}. ` +
+            `Check that the host-only network exists and the proxies are listening.`);
+    }
+    const egress = await docker.exec(containerId, ['socat', '-u', '/dev/null', `TCP:${EGRESS_PROBE_ADDRESS},connect-timeout=3`], 5_000);
+    if (egress.exitCode === 0) {
+        throw new Error(`Host-only network egress check failed: the container reached ${EGRESS_PROBE_ADDRESS}. ` +
+            `The network is not blocking internet egress as required; refusing to start the session.`);
+    }
+}
+/**
+ * Whether an OAuth credential set can be refreshed: true only when a
+ * non-empty refresh token is present. Externally-managed Codex tokens
+ * (`auth_mode: 'chatgptAuthTokens'`) carry an empty refresh token and must
+ * NOT be refreshed by IronCurtain. Pure helper, exported for testability.
+ */
+export function canRefreshOAuth(refreshToken) {
+    return refreshToken.length > 0;
+}
 /**
  * Resolves the real credential for a provider host.
  *
  * For Anthropic hosts in OAuth mode, uses the OAuth access token.
  * For all other cases, falls back to the API key from config.
  */
-function resolveRealKey(host, config, oauthAccessToken) {
+export function resolveRealKey(host, config, oauthAccessToken) {
     if (oauthAccessToken && ANTHROPIC_HOSTS.has(host)) {
         return oauthAccessToken;
     }
+    if (oauthAccessToken && CODEX_CHATGPT_HOSTS.has(host)) {
+        return oauthAccessToken;
+    }
     let key;
     switch (host) {
         case 'api.anthropic.com':
@@ -706,6 +956,10 @@ function resolveRealKey(host, config, oauthAccessToken) {
         case 'api.openai.com':
             key = config.userConfig.openaiApiKey;
             break;
+        case 'chatgpt.com':
+        case 'auth.openai.com':
+            key = '';
+            break;
         case 'generativelanguage.googleapis.com':
             key = config.userConfig.googleApiKey;
             break;
@@ -723,9 +977,13 @@ function resolveRealKey(host, config, oauthAccessToken) {
  * support session resume. Idempotent: skips seeding if the directory
  * already exists (resume case).
  *
- * As a defense-in-depth measure, always deletes `.credentials.json`
- * from the state directory — the MITM proxy handles auth independently,
- * so any credentials file left by the agent is stale.
+ * As a defense-in-depth measure, always deletes stale credential files
+ * (`.credentials.json` for Claude Code, `auth.json` for Codex) from the
+ * state directory — the MITM proxy handles auth independently, and each
+ * agent's entrypoint recreates its credential file from env on every
+ * start, so any credential file lingering across resumes is stale. The
+ * unlinks are no-ops for adapters whose state dir has neither file (e.g.
+ * Goose), since a missing file is swallowed.
  */
 export function prepareConversationStateDir(sessionDir, config) {
     const stateDir = resolve(sessionDir, config.hostDirName);
@@ -752,13 +1010,16 @@ export function prepareConversationStateDir(sessionDir, config) {
             }
         }
     }
-    // Defense-in-depth: remove stale credentials on every start
-    const credentialsPath = resolve(stateDir, '.credentials.json');
-    try {
-        unlinkSync(credentialsPath);
-    }
-    catch {
-        // File doesn't exist — expected on first run
+    // Defense-in-depth: remove stale credential files on every start. The
+    // entrypoint recreates them from env each start, so scrubbing host-side
+    // is safe. Both unlinks are no-ops when the file is absent.
+    for (const fileName of ['.credentials.json', 'auth.json']) {
+        try {
+            unlinkSync(resolve(stateDir, fileName));
+        }
+        catch {
+            // File doesn't exist — expected on first run / other adapters
+        }
     }
     return stateDir;
 }
@@ -777,12 +1038,12 @@ export function prepareConversationStateDir(sessionDir, config) {
 export async function ensureDockerImage(agentId, userConfig) {
     const { registerBuiltinAdapters, getAgent } = await import('./agent-registry.js');
     const { loadOrCreateCA } = await import('./ca.js');
-    const { createDockerManager } = await import('./docker-manager.js');
+    const { createContainerRuntime, resolveRuntimeKind } = await import('./container-runtime.js');
     const { getIronCurtainHome } = await import('../config/paths.js');
     await registerBuiltinAdapters(userConfig);
     const adapter = getAgent(agentId);
     const image = await adapter.getImage();
-    const docker = createDockerManager();
+    const docker = createContainerRuntime(await resolveRuntimeKind(userConfig.containerRuntime));
     const ca = loadOrCreateCA(resolve(getIronCurtainHome(), 'ca'));
     await ensureImage(image, docker, ca);
 }
@@ -792,7 +1053,33 @@ export async function ensureDockerImage(agentId, userConfig) {
  * agent-specific image. Content-hash labels on each image drive staleness
  * detection so repeated calls skip rebuilds when nothing has changed.
  */
-async function ensureImage(image, docker, ca) {
+/**
+ * Builds `image` from a fresh temp directory populated with the contents of
+ * `dockerDir` (plus any `extraFiles`, keyed dest→src). Building from a clean
+ * dir outside any git repo is REQUIRED for Apple `container build`, which
+ * resolves an EMPTY context when handed a git-tracked source directory (the
+ * repo's docker/ in a checkout/worktree) — making `COPY` fail with "not
+ * found"; harmless on Docker. The Dockerfiles only COPY files that live in
+ * `dockerDir` / `extraFiles`.
+ */
+async function buildImageFromCleanContext(docker, image, dockerDir, dockerfile, labels, extraFiles = {}) {
+    const tmpContext = mkdtempSync(resolve(tmpdir(), 'ironcurtain-build-'));
+    try {
+        for (const file of readdirSync(dockerDir)) {
+            copyFileSync(resolve(dockerDir, file), resolve(tmpContext, file));
+        }
+        for (const [dest, src] of Object.entries(extraFiles)) {
+            copyFileSync(src, resolve(tmpContext, dest));
+        }
+        await docker.buildImage(image, resolve(tmpContext, dockerfile), tmpContext, labels);
+    }
+    finally {
+        rmSync(tmpContext, { recursive: true, force: true });
+    }
+}
+// `docker` is typed `ContainerRuntime` (the apple-container generalization of
+// the former `DockerManager`); exported because callers/tests import it.
+export async function ensureImage(image, docker, ca) {
     const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
     const dockerDir = resolve(packageRoot, 'docker');
     // On arm64 hosts (Apple Silicon), use the lightweight arm64-native Dockerfile
@@ -814,29 +1101,186 @@ async function ensureImage(image, docker, ca) {
     const needsAgentBuild = baseRebuilt || (await isImageStale(image, docker, agentBuildHash));
     if (needsAgentBuild) {
         logger.info(`Building Docker image ${image}...`);
-        await docker.buildImage(image, agentDockerfilePath, dockerDir, {
+        await buildImageFromCleanContext(docker, image, dockerDir, dockerfile, {
             'ironcurtain.build-hash': agentBuildHash,
         });
         logger.info(`Docker image ${image} built successfully`);
     }
+    return agentBuildHash;
+}
+export function computeWorkflowDependencyHash(agentBuildHash, scriptsDir) {
+    const hash = createHash('sha256');
+    hash.update(`agent:${agentBuildHash}\n`);
+    for (const manifest of ['requirements.txt', 'package.json', 'package-lock.json']) {
+        const manifestPath = resolve(scriptsDir, manifest);
+        if (!existsSync(manifestPath))
+            continue;
+        hash.update(`file:${manifest}\n`);
+        hash.update(readFileSync(manifestPath));
+        hash.update('\n');
+    }
+    return hash.digest('hex');
+}
+/**
+ * Wraps an in-container command so the workflow dependency bins are prepended
+ * to the container's LIVE `$PATH` at exec time, rather than replacing the
+ * image's PATH at container-creation time.
+ *
+ * Why a runtime shell instead of an `-e PATH=...` env: Docker `-e` REPLACES the
+ * image PATH (it does not append), which would discard the base image's own
+ * PATH — including the NVM directory where `node`/`npm` live on the x86
+ * devcontainer base. Expanding `$PATH` inside the container at exec time is
+ * base-image-agnostic: it preserves whatever PATH the image ships and merely
+ * prepends the workflow venv bin (for bare `python`) and the installed Node
+ * package bins (`node_modules/.bin`).
+ *
+ * Returns the original command unchanged when neither dependency mount is
+ * present, so non-dependency workflows keep the plain exec path.
+ *
+ * Shell-safety: the only interpolated values are the hardcoded container
+ * constants `WORKFLOW_PYTHON_VENV_DIR` / `WORKFLOW_NODE_MODULES_DIR`. The
+ * caller's command and its arguments are passed verbatim as positional
+ * parameters consumed by `exec "$@"` — never string-interpolated — so no
+ * word-splitting or injection is possible.
+ */
+export function buildWorkflowExecCommand(bundle, command) {
+    const prefixDirs = [];
+    if (bundle.workflowPythonVenvMount)
+        prefixDirs.push(`${WORKFLOW_PYTHON_VENV_DIR}/bin`);
+    if (bundle.workflowNodeModulesMount)
+        prefixDirs.push(`${WORKFLOW_NODE_MODULES_DIR}/.bin`);
+    if (prefixDirs.length === 0 || command.length === 0)
+        return command;
+    const pathPrefix = prefixDirs.join(':');
+    // `exec "$@"` runs the original argv verbatim; the leading `sh` is $0.
+    return ['/bin/sh', '-lc', `export PATH=${pathPrefix}:"$PATH"; exec "$@"`, 'sh', ...command];
+}
+function prepareWorkflowDependencyMounts(agentBuildHash, scriptsDir, ironcurtainHome) {
+    if (scriptsDir === undefined || !existsSync(scriptsDir))
+        return {};
+    const requirementsPath = resolve(scriptsDir, 'requirements.txt');
+    const packageJsonPath = resolve(scriptsDir, 'package.json');
+    const packageLockPath = resolve(scriptsDir, 'package-lock.json');
+    const hasPythonManifest = existsSync(requirementsPath);
+    const hasNodeManifest = existsSync(packageJsonPath);
+    if (!hasPythonManifest && !hasNodeManifest)
+        return {};
+    const dependencyHash = computeWorkflowDependencyHash(agentBuildHash, scriptsDir);
+    const cacheRoot = resolve(ironcurtainHome, 'workflow-deps', dependencyHash.slice(0, 24));
+    mkdirSync(cacheRoot, { recursive: true, mode: 0o700 });
+    let workflowPythonVenvMount;
+    let workflowNodeModulesMount;
+    if (hasPythonManifest) {
+        const hostDir = resolve(cacheRoot, 'python-venv');
+        mkdirSync(hostDir, { recursive: true, mode: 0o700 });
+        workflowPythonVenvMount = {
+            hostDir,
+            target: WORKFLOW_PYTHON_VENV_DIR,
+            cacheKey: dependencyHash,
+        };
+    }
+    if (hasNodeManifest) {
+        const hostDir = resolve(cacheRoot, 'node_modules');
+        mkdirSync(hostDir, { recursive: true, mode: 0o700 });
+        workflowNodeModulesMount = {
+            hostDir,
+            target: WORKFLOW_NODE_MODULES_DIR,
+            cacheKey: dependencyHash,
+            hasPackageLock: existsSync(packageLockPath),
+        };
+    }
+    return {
+        ...(workflowPythonVenvMount ? { workflowPythonVenvMount } : {}),
+        ...(workflowNodeModulesMount ? { workflowNodeModulesMount } : {}),
+    };
+}
+async function provisionWorkflowDependencies(infra, packageInstallEnabled) {
+    if (!infra.workflowPythonVenvMount && !infra.workflowNodeModulesMount)
+        return;
+    // Runtime provisioning installs through the MITM registry proxy, which is
+    // only wired when packageInstall is enabled (see prepareDockerInfrastructure
+    // — `registries`/`packageValidation` are left undefined otherwise). The
+    // mounts above only exist when the workflow actually ships a
+    // requirements.txt / package.json, so reaching here with package install
+    // disabled means the run genuinely needs deps it can never fetch under
+    // `--network=none`. Fail fast with an actionable message rather than letting
+    // `uv pip install` / `npm install` die with an opaque network error.
+    if (!packageInstallEnabled) {
+        throw new Error('This workflow requires installing dependencies at runtime ' +
+            '(a requirements.txt and/or package.json is present in its scripts), ' +
+            'but packageInstall is disabled. Enable packageInstall in your IronCurtain ' +
+            'config to run workflows that declare runtime dependencies.');
+    }
+    if (infra.workflowPythonVenvMount) {
+        await provisionWorkflowPythonDependencies(infra);
+    }
+    if (infra.workflowNodeModulesMount) {
+        await provisionWorkflowNodeDependencies(infra);
+    }
+}
+async function provisionWorkflowPythonDependencies(infra) {
+    const mount = infra.workflowPythonVenvMount;
+    if (!mount)
+        return;
+    const sentinel = `${mount.target}/.ironcurtain-provisioned-${mount.cacheKey}`;
+    const command = [
+        'set -eu',
+        `if [ -f ${quote([sentinel])} ]; then exit 0; fi`,
+        `find ${quote([mount.target])} -mindepth 1 -maxdepth 1 -exec rm -rf {} +`,
+        `UV_NATIVE_TLS=1 uv venv ${quote([mount.target])}`,
+        `VIRTUAL_ENV=${quote([mount.target])} UV_NATIVE_TLS=1 uv pip install -r ${quote([`${CONTAINER_SCRIPTS_DIR}/requirements.txt`])}`,
+        `touch ${quote([sentinel])}`,
+    ].join('\n');
+    // Serialize concurrent provisioning of this content-keyed cache across runs.
+    // The lock is host-side because in-container flock does not propagate across
+    // containers on a Docker Desktop bind mount; the in-shell sentinel check
+    // provides the short-circuit, the host lock makes the second run wait for the
+    // first so it observes the populated cache instead of racing on the clean.
+    await withProvisionLock(mount.hostDir, async () => {
+        logger.info(`Provisioning workflow Python dependencies into ${mount.target}`);
+        const result = await infra.docker.exec(infra.containerId, ['/bin/sh', '-lc', command], 1_200_000, 'codespace', CONTAINER_WORKSPACE_DIR);
+        if (result.exitCode !== 0) {
+            throw new Error(`Workflow Python dependency provisioning failed: ${result.stderr || result.stdout}`);
+        }
+    });
+}
+async function provisionWorkflowNodeDependencies(infra) {
+    const mount = infra.workflowNodeModulesMount;
+    if (!mount)
+        return;
+    const sentinel = `${mount.target}/.ironcurtain-provisioned-${mount.cacheKey}`;
+    const installCommand = mount.hasPackageLock ? 'npm ci --omit=dev' : 'npm install --omit=dev';
+    const command = [
+        'set -eu',
+        `if [ -f ${quote([sentinel])} ]; then exit 0; fi`,
+        'tmp="$(mktemp -d)"',
+        'cleanup() { rm -rf "$tmp"; }',
+        'trap cleanup EXIT',
+        `cp ${quote([`${CONTAINER_SCRIPTS_DIR}/package.json`])} "$tmp/package.json"`,
+        mount.hasPackageLock ? `cp ${quote([`${CONTAINER_SCRIPTS_DIR}/package-lock.json`])} "$tmp/package-lock.json"` : '',
+        'cd "$tmp"',
+        installCommand,
+        `find ${quote([mount.target])} -mindepth 1 -maxdepth 1 -exec rm -rf {} +`,
+        `cp -a node_modules/. ${quote([mount.target])}/`,
+        `touch ${quote([sentinel])}`,
+    ]
+        .filter(Boolean)
+        .join('\n');
+    // Host-side serialization of this content-keyed cache (see the Python path
+    // for the bind-mount-flock rationale).
+    await withProvisionLock(mount.hostDir, async () => {
+        logger.info(`Provisioning workflow Node dependencies into ${mount.target}`);
+        const result = await infra.docker.exec(infra.containerId, ['/bin/sh', '-lc', command], 1_200_000, 'codespace', CONTAINER_WORKSPACE_DIR);
+        if (result.exitCode !== 0) {
+            throw new Error(`Workflow Node dependency provisioning failed: ${result.stderr || result.stdout}`);
+        }
+    });
 }
 async function ensureBaseImage(baseImage, docker, ca, dockerDir, dockerfile, buildHash) {
     if (!(await isImageStale(baseImage, docker, buildHash)))
         return false;
     logger.info('Building base Docker image (this may take a while on first run)...');
-    const tmpContext = mkdtempSync(resolve(tmpdir(), 'ironcurtain-build-'));
-    try {
-        for (const file of readdirSync(dockerDir)) {
-            copyFileSync(resolve(dockerDir, file), resolve(tmpContext, file));
-        }
-        copyFileSync(ca.certPath, resolve(tmpContext, 'ironcurtain-ca-cert.pem'));
-        await docker.buildImage(baseImage, resolve(tmpContext, dockerfile), tmpContext, {
-            'ironcurtain.build-hash': buildHash,
-        });
-    }
-    finally {
-        rmSync(tmpContext, { recursive: true, force: true });
-    }
+    await buildImageFromCleanContext(docker, baseImage, dockerDir, dockerfile, { 'ironcurtain.build-hash': buildHash }, { 'ironcurtain-ca-cert.pem': ca.certPath });
     logger.info('Base Docker image built successfully');
     return true;
 }