@provos/ironcurtain 0.12.0 → 0.13.0

package/dist/docker/docker-infrastructure.js

@@ -15,14 +15,17 @@ import { getBundleRuntimeRoot } from '../config/paths.js';
 import { getBundleShortId } from '../session/types.js';
 import { DEFAULT_CONTAINER_SCOPE } from '../workflow/types.js';
 import { CONTAINER_SCRIPTS_DIR, CONTAINER_WORKSPACE_DIR, } from './agent-adapter.js';
+import { OPENROUTER_HOST, resolveActiveProfile } from '../config/user-config.js';
 import { parseUpstreamBaseUrl } from './provider-config.js';
 import { getInternalNetworkName } from './platform.js';
 import { cleanupContainers } from './container-lifecycle.js';
+import { createIronCurtainInternalNetwork, InternalNetworkConnectivityError, managedResourceLabels, reconcileIronCurtainDockerResourcesBestEffort, releaseManagedResourceLease, withInternalNetworkAllocationRetry, } from './docker-resource-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';
+export { InternalNetworkConnectivityError };
 /**
  * Create a bundle-owned directory and enforce 0o700 permissions even if
  * it already exists. `mkdirSync`'s `mode` only applies on creation, so a
@@ -77,7 +80,24 @@ const BUNDLE_SKILLS_SUBDIR = 'skills';
 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) {
+export async function prepareDockerInfrastructure(config, mode, bundleDir, workspaceDir, escalationDir, bundleId, workflowId, scope, resolvedSkills, captureInput, scriptsDir, providerProfileName) {
+    // Resolve and STAMP the active provider profile as the FIRST step (§9.7 F1),
+    // before any container-runtime probe, adapter registration, or auth
+    // detection. This ordering is load-bearing: Claude Code's
+    // detectCredential(config) reads config.activeProviderProfile to return an
+    // API-key AuthMethod for an OpenRouter-only user, so the stamp must already
+    // be present when auth detection runs below. An unknown providerProfileName
+    // throws a clear error listing the available profiles before any expensive
+    // work or container launch. Safe to mutate: callers always pass a
+    // session-specific config copy (the same invariant the config.dockerAuth
+    // stamp below relies on).
+    const activeProfile = resolveActiveProfile(config.userConfig.modelProviders, providerProfileName);
+    config.activeProviderProfile = activeProfile;
+    if (activeProfile.type === 'openrouter' && activeProfile.apiKey === '') {
+        const activeName = providerProfileName ?? config.userConfig.modelProviders.default;
+        throw new Error(`Provider profile "${activeName}" is OpenRouter but no API key is configured. ` +
+            "Set OPENROUTER_API_KEY or the profile's apiKey in ~/.ironcurtain/config.json.");
+    }
     // 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
@@ -102,9 +122,14 @@ export async function prepareDockerInfrastructure(config, mode, bundleDir, works
     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).
-    const authMethod = adapter.detectCredential ? adapter.detectCredential(config) : await detectAuthMethod(config);
+    // their own credential detection (e.g., Goose checks provider-specific keys;
+    // Claude Code returns an api-key AuthMethod for an OpenRouter-only profile).
+    // A `detectCredential` that returns `undefined` DEFERS to detectAuthMethod()
+    // (Anthropic OAuth + API key) — this is how Claude Code preserves today's
+    // detection for a native profile (B2a). Adapters without the method also
+    // fall back.
+    const detected = adapter.detectCredential?.(config);
+    const authMethod = detected ?? (await detectAuthMethod(config));
     if (authMethod.kind === 'none') {
         throw new Error(adapter.credentialHelpText ??
             'No credentials available for Docker session. ' +
@@ -181,7 +206,7 @@ export async function prepareDockerInfrastructure(config, mode, bundleDir, works
             ...tokenManagerCodexDeps,
         })
         : undefined;
-    const providers = adapter.getProviders(authKind);
+    const providers = adapter.getProviders(config, authKind);
     const resolvedProviders = applyUpstreamOverrides(providers, parseUpstreamBaseUrl, {
         'api.anthropic.com': config.userConfig.anthropicBaseUrl,
         'api.openai.com': config.userConfig.openaiBaseUrl,
@@ -287,6 +312,14 @@ export async function prepareDockerInfrastructure(config, mode, bundleDir, works
     else {
         logger.info(`MITM proxy listening on ${mitmAddr.socketPath}`);
     }
+    // apple-container's `-v <sock>` vsock relay propagates the host
+    // socket's mode bits to the guest side (owner is always root there),
+    // so the non-root `codespace` user can only connect() when "other"
+    // has write. The parent `sockets/` dir is 0o700, so widening the
+    // socket mode does not expose it to other host users.
+    if (!useTcp && runtimeKind === 'apple-container' && mitmAddr.socketPath !== undefined) {
+        chmodSync(mitmAddr.socketPath, 0o666);
+    }
     // Compute control address for the proxy tools MCP server instance
     const controlAddr = mitmAddr.controlPort !== undefined
         ? `http://127.0.0.1:${mitmAddr.controlPort}`
@@ -308,6 +341,9 @@ export async function prepareDockerInfrastructure(config, mode, bundleDir, works
     else {
         logger.info(`Code Mode proxy listening on ${proxy.socketPath}`);
     }
+    if (!useTcp && runtimeKind === 'apple-container') {
+        chmodSync(socketPath, 0o666);
+    }
     // Remaining setup steps can fail -- clean up started proxies on error.
     try {
         // Build orientation
@@ -337,6 +373,10 @@ export async function prepareDockerInfrastructure(config, mode, bundleDir, works
         const agentImage = await adapter.getImage();
         const agentBuildHash = await ensureImage(agentImage, docker, ca);
         const image = agentImage;
+        // Surface the (unpinned) agent CLI version baked into the image so silent
+        // version drift on rebuild is visible in logs (issue #367). Keyed by build
+        // hash so a same-process rebuild re-logs the possibly-changed version.
+        await logResolvedAgentVersion(docker, agentImage, agentBuildHash, adapter.versionProbe);
         const workflowDependencyMounts = prepareWorkflowDependencyMounts(agentBuildHash, scriptsDir, getIronCurtainHome());
         const orientationDir = resolve(bundleDir, 'orientation');
         // Set up conversation state directory if the adapter supports resume
@@ -458,8 +498,8 @@ 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, captureInput, scriptsDir, options) {
-    const core = await prepareDockerInfrastructure(config, mode, bundleDir, workspaceDir, escalationDir, bundleId, workflowId, scope, resolvedSkills, captureInput, scriptsDir);
+export async function createDockerInfrastructure(config, mode, bundleDir, workspaceDir, escalationDir, bundleId, workflowId, scope, resolvedSkills, captureInput, scriptsDir, options, providerProfileName) {
+    const core = await prepareDockerInfrastructure(config, mode, bundleDir, workspaceDir, escalationDir, bundleId, workflowId, scope, resolvedSkills, captureInput, scriptsDir, providerProfileName);
     let containerResources;
     try {
         containerResources = await createSessionContainers(core, config, options);
@@ -509,6 +549,8 @@ export async function destroyDockerInfrastructure(infra) {
         sidecarContainerId: infra.sidecarContainerId ?? null,
         networkName: infra.internalNetwork ?? null,
     });
+    if (infra.runtimeKind === 'docker')
+        releaseManagedResourceLease(infra.bundleId);
     // Proxies are independent producers -- stop them in parallel. Each
     // per-promise catch logs so one failure doesn't mask the other, and
     // allSettled ensures both complete even if one throws synchronously.
@@ -561,6 +603,10 @@ export async function destroyDockerInfrastructure(infra) {
  * See `docs/designs/workflow-session-identity.md` §7.
  */
 export function buildBundleLabels(core) {
+    const managedLabels = core.runtimeKind === 'docker' ? managedResourceLabels(core.bundleId) : undefined;
+    const labels = managedLabels
+        ? Object.fromEntries(Object.entries(managedLabels).filter(([key]) => key !== 'ironcurtain.bundle'))
+        : undefined;
     if (core.workflowId !== undefined) {
         return {
             bundleLabel: core.bundleId,
@@ -569,9 +615,10 @@ export function buildBundleLabels(core) {
             // bundle; default-fall back to DEFAULT_CONTAINER_SCOPE so that a
             // workflow bundle always carries a scope label.
             scopeLabel: core.scope ?? DEFAULT_CONTAINER_SCOPE,
+            labels,
         };
     }
-    return { bundleLabel: core.bundleId };
+    return { bundleLabel: core.bundleId, labels };
 }
 /**
  * Returns the `user` override and env vars needed for runtime UID
@@ -583,15 +630,20 @@ export function buildBundleLabels(core) {
  * so the entrypoint (running as root) can renumber the codespace
  * account before dropping privileges via `runuser`.
  *
- * On macOS (`useTcp === true`), Docker Desktop's VirtioFS handles UID
- * translation transparently and `--user 0:0` would defeat it; this
- * function returns an empty mapping there, leaving the container to
- * run as the baked `codespace` user from the Dockerfile.
+ * When `skipRemap` is true this returns an empty mapping so the
+ * container runs as the baked `codespace` user from the Dockerfile.
+ * Skipped on macOS Docker Desktop (VirtioFS handles UID translation
+ * transparently and `--user 0:0` would defeat it) AND on apple-container
+ * (virtiofs presents host files as root; the existing sessions work
+ * without the Linux renumber-and-drop dance) — i.e., remap is Linux
+ * Docker only. Callers pass `runtimeKind === 'apple-container' || useTcp`
+ * so apple-container's `uds` topology does not accidentally trip the
+ * Linux-only remap.
  *
  * Exported for testability.
  */
-export function buildAgentUidRemap(useTcp) {
-    if (useTcp)
+export function buildAgentUidRemap(skipRemap) {
+    if (skipRemap)
         return { user: undefined, env: {} };
     const uid = process.getuid?.() ?? 1000;
     const gid = process.getgid?.() ?? 1000;
@@ -603,6 +655,30 @@ export function buildAgentUidRemap(useTcp) {
         },
     };
 }
+/** In-container mount root for the UDS proxies (both runtimes). */
+export const CONTAINER_SOCKETS_DIR = '/run/ironcurtain';
+/**
+ * Returns the `uds`-topology socket mounts for a given runtime. Linux
+ * Docker bind-mounts the whole `sockets/` directory (the sockets are
+ * shared kernel objects). Apple `container` mounts each socket FILE via
+ * `-v` so the runtime creates a per-socket vsock relay — a virtiofs
+ * directory share does not carry sockets (verified: `connect()` on a
+ * socket inside a shared dir fails ENOTSUP on 1.1.0). Shared by batch
+ * (`createSessionContainers`) and PTY (`runPtySession`).
+ */
+export function buildUdsSocketMounts(runtimeKind, socketsDir) {
+    if (runtimeKind === 'apple-container') {
+        return [
+            { source: resolve(socketsDir, 'proxy.sock'), target: `${CONTAINER_SOCKETS_DIR}/proxy.sock`, readonly: false },
+            {
+                source: resolve(socketsDir, 'mitm-proxy.sock'),
+                target: `${CONTAINER_SOCKETS_DIR}/mitm-proxy.sock`,
+                readonly: false,
+            },
+        ];
+    }
+    return [{ source: socketsDir, target: CONTAINER_SOCKETS_DIR, readonly: false }];
+}
 /**
  * Creates and starts the main agent container (plus TCP-mode sidecar and
  * internal network on macOS). Cleans up any partially-created resources
@@ -613,6 +689,17 @@ export function buildAgentUidRemap(useTcp) {
  * with a scripted `ContainerRuntime`.
  */
 export async function createSessionContainers(core, config, options) {
+    if (core.runtimeKind === 'docker') {
+        await reconcileIronCurtainDockerResourcesBestEffort(core.docker, 'session startup');
+    }
+    const maxAttempts = core.topology === 'tcp-sidecar' ? 4 : 1;
+    return withInternalNetworkAllocationRetry({
+        maxAttempts,
+        description: 'Internal Docker network',
+        reconcile: () => reconcileIronCurtainDockerResourcesBestEffort(core.docker, 'internal network retry'),
+    }, (excludedSubnets, attempt) => createSessionContainersAttempt(core, config, options, excludedSubnets, attempt));
+}
+async function createSessionContainersAttempt(core, config, options, excludedSubnets, attempt) {
     const shortId = getBundleShortId(core.bundleId);
     const mainContainerName = `${CONTAINER_NAME_PREFIX}${shortId}`;
     // Labels applied to every IronCurtain-owned container (main + sidecar).
@@ -628,6 +715,7 @@ export async function createSessionContainers(core, config, options) {
     let mainContainerId;
     let sidecarContainerId;
     let internalNetwork;
+    let allocatedNetworkSubnet;
     try {
         const mainImage = options?.baseImageOverride && (await core.docker.imageExists(options.baseImageOverride))
             ? options.baseImageOverride
@@ -644,12 +732,11 @@ export async function createSessionContainers(core, config, options) {
         };
         let network;
         let extraHosts;
-        // 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;
+        // apple-container only (both `uds` and the retained `tcp-hostonly`):
+        // the apt proxy config is written into the container via exec after
+        // start instead of bind-mounted — see writeAptProxyConfigViaExec for
+        // the virtiofs constraints that make the bind mount unworkable.
+        let execAptProxyUrl;
         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
@@ -664,7 +751,7 @@ export async function createSessionContainers(core, config, options) {
                 HTTPS_PROXY: proxyUrl,
                 HTTP_PROXY: proxyUrl,
             };
-            hostOnlyAptProxyUrl = proxyUrl;
+            execAptProxyUrl = proxyUrl;
             network = core.hostOnlyNetwork.name;
             // Report the host-only network as `internalNetwork` so the standard
             // teardown paths (destroyDockerInfrastructure, rollback below)
@@ -688,10 +775,15 @@ export async function createSessionContainers(core, config, options) {
             writeFileSync(aptProxyPath, `Acquire::http::Proxy "${proxyUrl}";\nAcquire::https::Proxy "${proxyUrl}";\n`);
             mounts.push({ source: aptProxyPath, target: '/etc/apt/apt.conf.d/90-ironcurtain-proxy', readonly: true });
             // Create a per-session --internal Docker network that blocks internet egress.
-            const networkName = getInternalNetworkName(shortId);
-            await core.docker.createNetwork(networkName, { internal: true });
+            const baseNetworkName = getInternalNetworkName(shortId);
+            const networkName = attempt === 1 ? baseNetworkName : `${baseNetworkName}-a${attempt}`;
+            const allocatedNetwork = await createIronCurtainInternalNetwork(core.docker, networkName, core.bundleId, {
+                excludedSubnets,
+            });
+            allocatedNetworkSubnet = allocatedNetwork.subnet;
             internalNetwork = networkName;
             network = networkName;
+            logger.info(`Allocated internal Docker network ${networkName} at ${allocatedNetwork.subnet}`);
             // Ensure the socat image is available
             const socatImage = 'alpine/socat';
             if (!(await core.docker.imageExists(socatImage))) {
@@ -726,30 +818,43 @@ export async function createSessionContainers(core, config, options) {
             logger.info(`Sidecar ${sidecarName} bridging ports ${mcpPort},${mitmPort} at ${sidecarIp}`);
         }
         else {
-            // Linux UDS mode: --network=none, session dir with sockets mounted
-            const linuxProxyUrl = 'http://127.0.0.1:18080';
+            // UDS mode (Linux Docker AND apple-container >= 1.1.0):
+            // --network none, proxy sockets mounted at /run/ironcurtain.
+            const udsProxyUrl = 'http://127.0.0.1:18080';
             env = {
                 ...env,
-                HTTPS_PROXY: linuxProxyUrl,
-                HTTP_PROXY: linuxProxyUrl,
+                HTTPS_PROXY: udsProxyUrl,
+                HTTP_PROXY: udsProxyUrl,
             };
             network = null;
-            // Write apt proxy config so sudo apt-get routes through the MITM proxy
-            const aptProxyPathLinux = resolve(core.orientationDir, 'apt-proxy.conf');
-            writeFileSync(aptProxyPathLinux, `Acquire::http::Proxy "${linuxProxyUrl}";\nAcquire::https::Proxy "${linuxProxyUrl}";\n`);
-            mounts.push({
-                source: aptProxyPathLinux,
-                target: '/etc/apt/apt.conf.d/90-ironcurtain-proxy',
-                readonly: true,
-            });
-            // Mount ONLY the per-bundle `sockets/` directory into the
-            // container. The sockets dir lives under a short
-            // `~/.ironcurtain/run/<bid12>/` path (see `getBundleSocketsDir`)
-            // so the host path stays under `sockaddr_un.sun_path` on both
-            // macOS and Linux. The host-only MITM control socket lives in a
-            // sibling `host/` dir, NOT under this mount, so it is not
-            // visible to the container.
-            mounts.push({ source: core.socketsDir, target: '/run/ironcurtain', readonly: false });
+            // Write apt proxy config so sudo apt-get routes through the MITM
+            // proxy. On apple-container we CANNOT bind-mount this file: it
+            // lives inside `orientationDir`, and 1.1.0's virtiofs silently
+            // drops a directory share when a file inside that directory is
+            // ALSO `-v`-mounted (verified — /etc/ironcurtain vanishes). The
+            // exec-based writer runs after start instead. Linux Docker keeps
+            // the single-file bind mount.
+            if (core.runtimeKind === 'apple-container') {
+                execAptProxyUrl = udsProxyUrl;
+            }
+            else {
+                const aptProxyPathUds = resolve(core.orientationDir, 'apt-proxy.conf');
+                writeFileSync(aptProxyPathUds, `Acquire::http::Proxy "${udsProxyUrl}";\nAcquire::https::Proxy "${udsProxyUrl}";\n`);
+                mounts.push({
+                    source: aptProxyPathUds,
+                    target: '/etc/apt/apt.conf.d/90-ironcurtain-proxy',
+                    readonly: true,
+                });
+            }
+            // Mount ONLY the per-bundle proxy sockets into the container. The
+            // sockets dir lives under a short `~/.ironcurtain/run/<bid12>/`
+            // path (see `getBundleSocketsDir`) so host paths stay under
+            // `sockaddr_un.sun_path`. Linux mounts the directory; apple-
+            // container mounts each socket file so the runtime creates a
+            // vsock relay per socket (see buildUdsSocketMounts). The
+            // host-only MITM control socket lives in a sibling `host/` dir
+            // and is never mounted.
+            mounts.push(...buildUdsSocketMounts(core.runtimeKind, core.socketsDir));
         }
         // Mount conversation state directory for session resume (e.g., claude --continue)
         if (core.conversationStateDir && core.conversationStateConfig) {
@@ -790,7 +895,7 @@ export async function createSessionContainers(core, config, options) {
         // passing `--user 0:0` would actually break that translation,
         // so we leave the container running as the baked codespace user
         // and skip the env vars entirely.
-        const uidRemap = buildAgentUidRemap(core.useTcp);
+        const uidRemap = buildAgentUidRemap(core.runtimeKind === 'apple-container' || core.useTcp);
         // Resource ceilings come from userConfig (defaults: 8 GB / 4 cpus) and
         // are clamped to fit the host. `null` in either field is preserved as
         // "no flag emitted" (see clampDockerResources docs).
@@ -828,10 +933,13 @@ export async function createSessionContainers(core, config, options) {
         });
         await core.docker.start(mainContainerId);
         logger.info(`Container started: ${mainContainerId.substring(0, 12)}`);
+        if (core.runtimeKind === 'docker') {
+            await checkDockerContainerWritableStorage(core.docker, mainContainerId);
+        }
         // 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);
+        // Docker topologies bind-mount it; see execAptProxyUrl above).
+        if (execAptProxyUrl !== undefined) {
+            await writeAptProxyConfigViaExec(core.docker, mainContainerId, execAptProxyUrl);
         }
         // Connectivity check: verify the container can reach host proxies
         // through the internal network. Abort if unreachable. Host-only
@@ -841,7 +949,18 @@ export async function createSessionContainers(core, config, options) {
             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);
+            if (core.mitmAddr.port === undefined) {
+                throw new Error('tcp-sidecar bundle is missing its MITM proxy port');
+            }
+            try {
+                await checkInternalNetworkConnectivity(core.docker, mainContainerId, core.proxy.port, core.mitmAddr.port);
+            }
+            catch (error) {
+                if (error instanceof InternalNetworkConnectivityError) {
+                    throw new InternalNetworkConnectivityError(error.message, allocatedNetworkSubnet);
+                }
+                throw error;
+            }
         }
         return {
             containerId: mainContainerId,
@@ -860,6 +979,8 @@ export async function createSessionContainers(core, config, options) {
             sidecarContainerId: sidecarContainerId ?? null,
             networkName: internalNetwork ?? null,
         });
+        if (core.runtimeKind === 'docker')
+            releaseManagedResourceLease(core.bundleId);
         throw err;
     }
 }
@@ -867,26 +988,60 @@ export async function createSessionContainers(core, config, options) {
  * Probes whether the container can reach host-side proxies via the socat
  * sidecar on the internal Docker network. Throws a descriptive error if not.
  */
-async function checkInternalNetworkConnectivity(docker, containerId, mcpPort) {
-    const result = await docker.exec(containerId, ['socat', '-u', '/dev/null', `TCP:${DOCKER_HOST_GATEWAY}:${mcpPort},connect-timeout=5`], 
+export async function checkInternalNetworkConnectivity(docker, containerId, mcpPort, mitmPort) {
+    const mcpResult = await docker.exec(containerId, [
+        '/bin/sh',
+        '-c',
+        `printf 'IRONCURTAIN_HEALTH/1\\n' | socat -T5 - TCP:${DOCKER_HOST_GATEWAY}:${mcpPort},connect-timeout=5 | grep -q '^IRONCURTAIN_OK/1'`,
+    ], 
     // Allow a small buffer above socat's 5s connect-timeout for docker exec/process startup overhead.
     6_000);
-    if (result.exitCode !== 0) {
-        throw new Error(`Internal network connectivity check failed (exit=${result.exitCode}). ` +
-            `The container cannot reach host-side proxies via the socat sidecar on the --internal Docker network. ` +
-            `Check that the sidecar container is running and connected to the internal network.`);
+    if (mcpResult.exitCode !== 0) {
+        throw new InternalNetworkConnectivityError(`Internal network connectivity check failed: MCP round-trip exited ${mcpResult.exitCode}; ` +
+            `the sidecar could not reach the host proxy.`);
     }
+    const healthRequest = 'GET http://ironcurtain.invalid/__ironcurtain/health HTTP/1.1\\r\\n' +
+        'Host: ironcurtain.invalid\\r\\nConnection: close\\r\\n\\r\\n';
+    const mitmResult = await docker.exec(containerId, [
+        '/bin/sh',
+        '-c',
+        `printf '${healthRequest}' | socat -T5 - TCP:${DOCKER_HOST_GATEWAY}:${mitmPort},connect-timeout=5 | grep -q 'IRONCURTAIN_OK/1'`,
+    ], 6_000);
+    if (mitmResult.exitCode !== 0) {
+        throw new InternalNetworkConnectivityError(`Internal network connectivity check failed: MITM round-trip exited ${mitmResult.exitCode}; ` +
+            `the sidecar could not reach the host proxy.`);
+    }
+}
+/**
+ * Verifies that Docker's writable layer has space before an agent starts.
+ * Docker Desktop can keep creating/starting containers after its VM disk is
+ * full, while writes inside the container fail with ENOSPC. Claude Code then
+ * exits 0 with no output after its initialization timeout, which otherwise
+ * looks like a networking failure.
+ */
+export async function checkDockerContainerWritableStorage(docker, containerId) {
+    const result = await docker.exec(containerId, ['/bin/sh', '-c', 'probe="${HOME:-/home/codespace}/.ironcurtain-write-probe-$$"; mkdir "$probe" && rmdir "$probe"'], 5_000);
+    if (result.exitCode === 0)
+        return;
+    const detail = result.stderr.trim() || result.stdout.trim() || `exit ${result.exitCode}`;
+    const guidance = /ENOSPC|no space left on device/i.test(detail)
+        ? 'Docker storage may be full; inspect it with `docker system df` and reclaim unused data or increase the disk limit.'
+        : 'Inspect the container state, Docker daemon logs, and filesystem permissions.';
+    throw new Error(`Docker container writable storage check failed: ${detail}. ${guidance}`);
 }
 /**
  * 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.
+ * container via exec (as root). Used by apple-container in both batch
+ * and PTY modes — the single-file bind mount the Docker topologies use
+ * is unworkable there: on `tcp-hostonly` (pre-1.1.0) `--mount` rejected
+ * non-directory sources, and on `uds` (1.1.0+) a `-v <dir>/file` mount
+ * whose source nests under the already-shared orientation dir silently
+ * drops that dir share. The URL is built from IronCurtain's own
+ * gateway/loopback 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) {
+export async function writeAptProxyConfigViaExec(docker, containerId, proxyUrl) {
     const aptWrite = await docker.exec(containerId, [
         'sh',
         '-c',
@@ -963,6 +1118,15 @@ export function resolveRealKey(host, config, oauthAccessToken) {
         case 'generativelanguage.googleapis.com':
             key = config.userConfig.googleApiKey;
             break;
+        case OPENROUTER_HOST: {
+            // OpenRouter uses a static bearer key from the stamped active profile
+            // (§7.5). The same host serves all three agents, so this single case
+            // covers them. `isManagedOAuthHost` never matches openrouter.ai, so no
+            // OAuth token is involved here.
+            const profile = config.activeProviderProfile;
+            key = profile?.type === 'openrouter' ? profile.apiKey : '';
+            break;
+        }
         default:
             logger.warn(`No API key mapping for unknown provider host: ${host}`);
             return '';
@@ -1077,6 +1241,42 @@ async function buildImageFromCleanContext(docker, image, dockerDir, dockerfile,
         rmSync(tmpContext, { recursive: true, force: true });
     }
 }
+/**
+ * `${image}@${buildHash}` keys whose baked CLI version has already been logged
+ * this process, so the diagnostic probe (a throwaway `docker run --version`)
+ * runs at most once per built image rather than on every session/workflow-state.
+ * Keyed by build hash — not the tag alone — so a same-process rebuild (which
+ * keeps the `:latest` tag but changes `ironcurtain.build-hash`) re-probes and
+ * re-logs the possibly-changed version, which is the whole point of surfacing
+ * drift.
+ */
+const loggedAgentVersions = new Set();
+/**
+ * Best-effort: log the agent CLI version baked into `image`. The agent CLI is
+ * installed UNPINNED in the Docker image, so any change to a hashed build input
+ * (Dockerfile / *.sh) rebuilds the image and can silently pull a newer agent —
+ * see issue #367, where a Claude Code minor bump flipped subagents to run in the
+ * background, breaking the one-shot `claude -p` workflow model. Surfacing the
+ * resolved version makes that drift visible. Skipped when the adapter defines no
+ * probe or the runtime can't run an ephemeral container; never throws.
+ */
+async function logResolvedAgentVersion(runtime, image, buildHash, versionProbe) {
+    if (!versionProbe || versionProbe.length === 0 || !runtime.probeImageVersion)
+        return;
+    const cacheKey = `${image}@${buildHash}`;
+    if (loggedAgentVersions.has(cacheKey))
+        return;
+    loggedAgentVersions.add(cacheKey);
+    try {
+        const version = await runtime.probeImageVersion(image, versionProbe);
+        if (version) {
+            logger.info(`[docker] ${image} agent version (unpinned): ${version}`);
+        }
+    }
+    catch {
+        // Diagnostic only — never disturb infra prep.
+    }
+}
 // `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) {