@the-open-engine/zeroshot 6.23.0 → 6.25.0

package/src/isolation-manager.js

@@ -15,7 +15,7 @@ const path = require('path');
 const os = require('os');
 const fs = require('fs');
 const { loadSettings } = require('../lib/settings');
-const { CLAUDE_AUTH_ENV_VARS, resolveClaudeAuth } = require('../lib/settings/claude-auth');
+const { resolveClaudeAuth } = require('../lib/settings/claude-auth');
 const {
   normalizeProviderName,
   getProviderMetadata,
@@ -23,9 +23,12 @@ const {
 } = require('../lib/provider-names');
 const {
   MOUNT_PRESETS,
+  ENV_PRESETS,
   resolveMounts,
   resolveEnvs,
   expandEnvPatterns,
+  isUsableEnvValue,
+  validateProviderEnvAuth,
 } = require('../lib/docker-config');
 const { getProvider } = require('./providers');
 const { readRepoSettings } = require('../lib/repo-settings');
@@ -181,6 +184,40 @@ function providerDockerInstall(providerName) {
   }
 }
 
+/**
+ * Registry-owned Docker platform (e.g. 'linux/amd64') for a provider, or null when unset.
+ * Providers other than the ones that declare `docker.platform` keep today's host-native
+ * (unset `--platform`) behavior.
+ * @param {string} providerName
+ * @returns {string|null}
+ */
+function providerDockerPlatform(providerName) {
+  if (!providerName) return null;
+  try {
+    const metadata = getProviderMetadata(providerName);
+    const platform = metadata && metadata.docker && metadata.docker.platform;
+    return typeof platform === 'string' && platform.trim() ? platform.trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Registry-owned $HOME-placeholder config/overlay roots for a provider, unexpanded.
+ * @param {string} providerName
+ * @returns {readonly string[]}
+ */
+function providerDockerConfigRootsRaw(providerName) {
+  if (!providerName) return [];
+  try {
+    const metadata = getProviderMetadata(providerName);
+    const roots = metadata && metadata.docker && metadata.docker.configRoots;
+    return Array.isArray(roots) ? roots : [];
+  } catch {
+    return [];
+  }
+}
+
 class IsolationManager {
   constructor(options = {}) {
     this.image = options.image || DEFAULT_IMAGE;
@@ -234,35 +271,48 @@ class IsolationManager {
       return runningContainerId;
     }
 
-    this._removeContainerByName(containerName);
-
-    workDir = await this._prepareIsolatedWorkspace(clusterId, workDir, reuseExisting);
-
     const settings = loadSettings();
     const providerName = normalizeProviderName(
       config.provider || settings.defaultProvider || getDefaultProviderId()
     );
     const containerHome = config.containerHome || settings.dockerContainerHome || '/root';
 
-    const clusterConfigDir = this._createClusterConfigDir(clusterId, containerHome);
-    console.log(`[IsolationManager] Created cluster config dir at ${clusterConfigDir}`);
+    // Pre-effect auth gate. The effective env/mount plan is computed (read-only) and validated
+    // BEFORE the stale-container removal and the isolated-workspace copy, so a missing or
+    // malformed credential plan leaves no container or workspace side effect behind — matching
+    // the platform probe's ordering in orchestrator/agent-lifecycle/preflight.
+    const credentialPlan = this._buildCredentialPlan(config, settings, containerHome, providerName);
+    this._assertProviderCredentialPlan(providerName, {
+      ...credentialPlan,
+      config,
+      containerHome,
+    });
+
+    this._removeContainerByName(containerName);
+
+    workDir = await this._prepareIsolatedWorkspace(clusterId, workDir, reuseExisting);
+
+    // The cluster config dir carries Claude credentials (via provisionClaudeCredentials) and the
+    // Claude-specific AskUserQuestion-blocking hook (~/.claude/settings.json PreToolUse), which
+    // only the `claude` CLI reads. Creating and mounting it for every provider — regardless of
+    // whether Claude is even running in the container — was an unconditional Claude-auth side
+    // channel into other providers' containers (e.g. omp, whose Docker isolation must be
+    // env/broker-only with zero automatic mounts). Scope it to the claude provider only.
+    const clusterConfigDir =
+      providerName === 'claude' ? this._createClusterConfigDir(clusterId, containerHome) : null;
+    if (clusterConfigDir) {
+      console.log(`[IsolationManager] Created cluster config dir at ${clusterConfigDir}`);
+    }
 
     const args = this._buildBaseDockerArgs({
       containerName,
       workDir,
       containerHome,
       clusterConfigDir,
+      platform: config.platform,
     });
 
-    const mountedHosts = this._applyCredentialMounts(
-      args,
-      config,
-      settings,
-      containerHome,
-      providerName
-    );
-    this._warnMissingProviderCredentials(providerName, mountedHosts, config, containerHome);
-
+    args.push(...credentialPlan.args);
     args.push('-w', '/workspace', image, 'tail', '-f', '/dev/null');
 
     const containerId = await this._spawnContainer(clusterId, args, workDir);
@@ -340,21 +390,26 @@ class IsolationManager {
     return isolatedDir;
   }
 
-  _buildBaseDockerArgs({ containerName, workDir, containerHome, clusterConfigDir }) {
-    return [
-      'run',
-      '-d',
-      '--name',
-      containerName,
+  _buildBaseDockerArgs({ containerName, workDir, containerHome, clusterConfigDir, platform }) {
+    const args = ['run', '-d', '--name', containerName];
+    if (platform) {
+      args.push('--platform', platform);
+    }
+    args.push(
       '-v',
       `${workDir}:/workspace`,
       '-v',
       '/var/run/docker.sock:/var/run/docker.sock',
       '--group-add',
-      this._getDockerGid(),
-      '-v',
-      `${clusterConfigDir}:${containerHome}/.claude`,
-    ];
+      this._getDockerGid()
+    );
+    // Only mounted when the active provider is claude (see createContainer) — carries Claude
+    // credentials and the Claude-specific AskUserQuestion-blocking hook, neither of which any
+    // other provider's CLI reads.
+    if (clusterConfigDir) {
+      args.push('-v', `${clusterConfigDir}:${containerHome}/.claude`);
+    }
+    return args;
   }
 
   _resolveMountConfig(config, settings) {
@@ -374,26 +429,56 @@ class IsolationManager {
     return settings.dockerMounts;
   }
 
-  // Auto-activate the running provider's own credential preset (mount + env) so `--docker` works
-  // without listing it in dockerMounts. Claude is mounted separately, so skip it.
+  // Auto-activate the running provider's own credential preset (mount and/or env) so `--docker`
+  // works without listing it in dockerMounts. Env-only providers (e.g. omp) have no MOUNT_PRESETS
+  // entry, so both preset maps are checked.
   _withActiveProviderPreset(mountConfig, providerName) {
-    if (!providerName || providerName === 'claude') return mountConfig;
-    if (!MOUNT_PRESETS[providerName]) return mountConfig;
+    if (!providerName) return mountConfig;
+    if (!MOUNT_PRESETS[providerName] && !ENV_PRESETS[providerName]) return mountConfig;
     if (mountConfig.some((item) => item === providerName)) return mountConfig;
     return [...mountConfig, providerName];
   }
 
-  _applyCredentialMounts(args, config, settings, containerHome, providerName) {
-    const mountedHosts = [];
+  /**
+   * Compute the *effective* credential plan for a container — the exact `-v`/`-e` argv the
+   * container would receive, plus which of it the user explicitly opted into — WITHOUT applying
+   * any side effect. Callers validate the plan (see `_assertProviderCredentialPlan`) before
+   * touching containers or workspaces, then splice `plan.args` into the final argv.
+   *
+   * `forwardedEnv` holds the ACTUAL values the container would receive, so a forced-empty entry
+   * (`dockerEnvPassthrough: ["OPENAI_API_KEY="]`) is distinguishable from a real key. Values stay
+   * internal — they are never logged or included in any error message.
+   *
+   * @param {object} config
+   * @param {object} settings
+   * @param {string} containerHome
+   * @param {string} providerName
+   * @returns {{args: string[], mountedHosts: string[], explicitMountContainerPaths: string[],
+   *   forwardedEnv: Record<string, string>, explicitEnvNames: Set<string>}}
+   */
+  _buildCredentialPlan(config, settings, containerHome, providerName) {
+    const plan = {
+      args: [],
+      mountedHosts: [],
+      explicitMountContainerPaths: [],
+      forwardedEnv: {},
+      explicitEnvNames: new Set(),
+    };
+
     if (config.noMounts) {
-      return mountedHosts;
+      return plan;
     }
 
-    const mountConfig = this._withActiveProviderPreset(
-      this._resolveMountConfig(config, settings),
-      providerName
-    );
+    // The user's own config, before the running provider's preset is auto-activated. Anything
+    // sourced from here is an *explicit* opt-in; anything added by `_withActiveProviderPreset` is
+    // automatic. Credential accounting depends on that distinction.
+    const userMountConfig = this._resolveMountConfig(config, settings);
+    const mountConfig = this._withActiveProviderPreset(userMountConfig, providerName);
+
     const mounts = resolveMounts(mountConfig, { containerHome });
+    const explicitContainerPaths = new Set(
+      resolveMounts(userMountConfig, { containerHome }).map((mount) => mount.container)
+    );
     const claudeContainerPath = path.posix.join(containerHome, '.claude');
 
     for (const mount of mounts) {
@@ -419,21 +504,52 @@ class IsolationManager {
       const mountSpec = mount.readonly
         ? `${hostPath}:${mount.container}:ro`
         : `${hostPath}:${mount.container}`;
-      args.push('-v', mountSpec);
-      mountedHosts.push(hostPath);
+      plan.args.push('-v', mountSpec);
+      plan.mountedHosts.push(hostPath);
+      if (explicitContainerPaths.has(mount.container)) {
+        plan.explicitMountContainerPaths.push(mount.container);
+      }
     }
 
-    const envToPass = this._collectDockerEnvVars(mountConfig, settings);
+    const { envToPass, explicitNames } = this._collectDockerEnvVars(
+      mountConfig,
+      userMountConfig,
+      settings
+    );
     for (const [key, value] of Object.entries(envToPass)) {
-      args.push('-e', `${key}=${value}`);
+      plan.args.push('-e', `${key}=${value}`);
+      plan.forwardedEnv[key] = value;
     }
+    plan.explicitEnvNames = explicitNames;
 
-    return mountedHosts;
+    return plan;
   }
 
-  _collectDockerEnvVars(mountConfig, settings) {
+  /**
+   * Apply the credential plan to an argv array. Thin wrapper around `_buildCredentialPlan` kept
+   * for callers that build argv incrementally.
+   */
+  _applyCredentialMounts(args, config, settings, containerHome, providerName) {
+    const plan = this._buildCredentialPlan(config, settings, containerHome, providerName);
+    args.push(...plan.args);
+    return plan;
+  }
+
+  /**
+   * @param {Array<string|object>} mountConfig - effective config (user's + auto provider preset)
+   * @param {Array<string|object>} userMountConfig - the user's config only
+   * @param {object} settings
+   * @returns {{envToPass: Record<string, string>, explicitNames: Set<string>}}
+   */
+  _collectDockerEnvVars(mountConfig, userMountConfig, settings) {
     const envToPass = {};
     const envSpecs = expandEnvPatterns(resolveEnvs(mountConfig, settings.dockerEnvPassthrough));
+    // Names the user opted into by name (dockerEnvPassthrough) or by explicitly listing a preset,
+    // as opposed to the running provider's automatically-activated preset.
+    const explicitSpecs = expandEnvPatterns(
+      resolveEnvs(userMountConfig, settings.dockerEnvPassthrough)
+    );
+    const explicitNames = new Set(explicitSpecs.map((spec) => spec.name));
 
     for (const spec of envSpecs) {
       if (spec.forced) {
@@ -443,69 +559,215 @@ class IsolationManager {
       }
     }
 
-    for (const envVar of CLAUDE_AUTH_ENV_VARS) {
-      if (process.env[envVar]) {
-        envToPass[envVar] = process.env[envVar];
-      }
-    }
-
-    const authEnv = resolveClaudeAuth(settings);
-    for (const [key, value] of Object.entries(authEnv)) {
-      if (!(key in envToPass)) {
-        envToPass[key] = value;
+    // Claude's own auth resolution only applies when Claude's preset is actually active (either
+    // as the running provider or explicitly configured) — never as an unconditional side channel
+    // into another provider's container (e.g. omp).
+    if (mountConfig.includes('claude')) {
+      const authEnv = resolveClaudeAuth(settings);
+      for (const [key, value] of Object.entries(authEnv)) {
+        if (!(key in envToPass)) {
+          envToPass[key] = value;
+        }
       }
     }
 
-    return envToPass;
+    return { envToPass, explicitNames };
   }
 
-  _warnMissingProviderCredentials(providerName, mountedHosts, config, containerHome) {
+  /**
+   * Decide whether the running provider has usable credentials in the *effective* container plan
+   * (what would actually be mounted/forwarded, with actual values), not host presence. Providers
+   * with no `docker.mount` (env-only, e.g. omp) fail closed — throw with remediation and never
+   * fall back to another provider. All other providers keep today's non-fatal warning.
+   *
+   * A credential counts when ALL of the following hold:
+   *  - it is a registry-known credential env key for this provider, AND
+   *  - it is in the provider's automatic allowlist (`docker.envAuth.requireOneOf`) OR the user
+   *    explicitly opted it in (dockerEnvPassthrough / an explicitly listed preset), AND
+   *  - its forwarded value is non-empty/non-whitespace, AND
+   *  - if that value is an absolute container path (a *path* credential), an explicitly
+   *    configured mount actually provides that path inside the container.
+   *
+   * Hard plan defects (a partial required pair, a non-http(s) broker URL) are never compensated
+   * for by another credential.
+   *
+   * Error/warning text names variables and paths from the *configuration*, never a forwarded
+   * value.
+   *
+   * @param {string} providerName
+   * @param {{mountedHosts: string[], explicitMountContainerPaths: string[],
+   *   forwardedEnv: Record<string, string>, explicitEnvNames: Set<string>,
+   *   config: object, containerHome: string}} plan
+   */
+  _assertProviderCredentialPlan(
+    providerName,
+    {
+      mountedHosts,
+      explicitMountContainerPaths = [],
+      forwardedEnv,
+      explicitEnvNames = new Set(),
+      config,
+      containerHome,
+    }
+  ) {
     if (providerName === 'claude') {
       return;
     }
 
     const metadata = getProviderMetadata(providerName);
     const provider = getProvider(providerName);
-
-    // An env token (e.g. COPILOT_GITHUB_TOKEN) is a complete credential on its own.
-    const credentialEnvKeys = metadata.credentialEnvKeys || [];
-    if (credentialEnvKeys.some((key) => process.env[key])) {
-      return;
-    }
+    const docker = metadata.docker || {};
+
+    // Structural env/broker validation: required-pair completeness and URL shape.
+    const envAuthResult = validateProviderEnvAuth(providerName, forwardedEnv);
+    const { satisfying, notOptedIn, unmountedPath } = this._classifyForwardedCredentials(metadata, {
+      forwardedEnv,
+      explicitEnvNames,
+      explicitMountContainerPaths,
+    });
 
     // A mount only counts if it carries the secret (credentialInMount !== false).
-    const credentialInMount = metadata.docker && metadata.docker.credentialInMount === false;
     const credentialPaths = provider.getCredentialPaths ? provider.getCredentialPaths() : [];
     const expandedCreds = credentialPaths.map((cred) => expandHomePath(cred));
     const hasCredentialMount =
-      !credentialInMount &&
+      docker.credentialInMount !== false &&
       mountedHosts.some((hostPath) =>
         expandedCreds.some(
           (credPath) => pathContains(hostPath, credPath) || pathContains(credPath, hostPath)
         )
       );
-    if (hasCredentialMount) {
+
+    if (envAuthResult.malformed.length === 0 && (satisfying.length > 0 || hasCredentialMount)) {
       return;
     }
 
-    if (credentialInMount && credentialEnvKeys.length > 0) {
-      console.warn(
-        `[IsolationManager] ⚠️  ${provider.displayName} could not find credentials for Docker. ` +
-          `Its login token is not stored in a mountable file — export one of ` +
-          `${credentialEnvKeys.join(', ')} before running with --docker.`
+    const reasons = [...envAuthResult.malformed];
+    if (unmountedPath.length > 0) {
+      reasons.push(
+        `${unmountedPath.join(', ')} points at a container path that no explicit --mount provides`
       );
-      return;
     }
+    if (notOptedIn.length > 0) {
+      reasons.push(
+        `${notOptedIn.join(', ')} (known ${provider.displayName} credentials outside the ` +
+          'automatic allowlist) were not explicitly opted in'
+      );
+    }
+    if (reasons.length === 0) {
+      reasons.push('no credential env var or mount found in the effective container plan');
+    }
+
+    const mountNote = config.noMounts ? 'Credential mounts are disabled. ' : '';
+    const allowlist = docker.envPassthrough || [];
+    const message =
+      `${mountNote}No usable credentials found for ${provider.displayName} in the effective ` +
+      `Docker env/mount plan (${reasons.join('; ')}). Automatic env allowlist: ` +
+      `${allowlist.join(', ') || '(none)'}. ` +
+      this._credentialRemediation(provider, docker, credentialPaths, containerHome);
+
+    // Env-only providers (no automatic mount) have no fallback credential surface, so an
+    // unsatisfied/malformed plan must fail closed before the container ever starts.
+    if (!docker.mount) {
+      throw new Error(`[IsolationManager] ${message}`);
+    }
+
+    console.warn(`[IsolationManager] ⚠️  ${message}`);
+  }
+
+  /**
+   * Split this provider's registry-known credential env vars into the ones that actually
+   * authenticate the container and the two ways they can fail to.
+   *
+   * @param {object} metadata - registry provider metadata
+   * @param {{forwardedEnv: Record<string, string>, explicitEnvNames: Set<string>,
+   *   explicitMountContainerPaths: string[]}} plan
+   * @returns {{satisfying: string[], notOptedIn: string[], unmountedPath: string[]}}
+   *   `notOptedIn`: a known credential carrying a real value that is neither on the automatic
+   *   allowlist nor explicitly passed through. `unmountedPath`: a path credential whose container
+   *   path no explicit mount provides — the file simply is not there.
+   */
+  _classifyForwardedCredentials(
+    metadata,
+    { forwardedEnv, explicitEnvNames, explicitMountContainerPaths }
+  ) {
+    const docker = metadata.docker || {};
+    const envAuth = docker.envAuth;
+    const automatic = new Set(envAuth ? envAuth.requireOneOf : []);
+    const usable = (metadata.credentialEnvKeys || []).filter((key) =>
+      isUsableEnvValue(forwardedEnv[key])
+    );
+
+    const satisfying = [];
+    const notOptedIn = [];
+    const unmountedPath = [];
 
-    if (expandedCreds.length > 0) {
-      const exampleHost = credentialPaths[0];
-      const exampleContainer = exampleHost.replace(/^~(?=\/|$)/, containerHome);
-      const mountNote = config.noMounts ? 'Credential mounts are disabled. ' : '';
-      console.warn(
-        `[IsolationManager] ⚠️  ${mountNote}No credential mounts found for ${provider.displayName}. ` +
-          `Add one with --mount ${exampleHost}:${exampleContainer}:ro`
+    for (const name of usable) {
+      // A registry-known credential outside the automatic allowlist is usable only when explicitly
+      // opted in — that is the "custom env credential requires explicit passthrough" rule, not a
+      // reason for it to stay permanently unusable.
+      if (envAuth && !automatic.has(name) && !explicitEnvNames.has(name)) {
+        notOptedIn.push(name);
+        continue;
+      }
+      // A path credential (value is an absolute container path) is only real when an explicitly
+      // configured mount actually provides that path. Host-side existence proves nothing about
+      // what the container can read.
+      const value = forwardedEnv[name];
+      const isContainerPath = value.startsWith('/');
+      if (
+        isContainerPath &&
+        !explicitMountContainerPaths.some((containerPath) => pathContains(containerPath, value))
+      ) {
+        unmountedPath.push(name);
+        continue;
+      }
+      satisfying.push(name);
+    }
+
+    return { satisfying, notOptedIn, unmountedPath };
+  }
+
+  /**
+   * Remediation sentence for a provider with no usable credential plan.
+   *
+   * Env-only providers (no `docker.mount`) must NEVER be told to mount their host auth store —
+   * not mounting/copying it is the whole point of their Docker contract. They get the broker
+   * pair (when the registry declares one) plus a generic custom-path example instead. Mount-based
+   * providers keep the concrete "mount your credential dir" hint.
+   *
+   * @param {{displayName: string}} provider
+   * @param {object} docker - registry docker metadata
+   * @param {readonly string[]} credentialPaths
+   * @param {string} containerHome
+   * @returns {string}
+   */
+  _credentialRemediation(provider, docker, credentialPaths, containerHome) {
+    const customEnvHint =
+      `Any other credential needs explicit opt-in: ` +
+      `zeroshot settings set dockerEnvPassthrough '["MY_KEY"]'`;
+    const genericPathHint =
+      `for a file credential also mount it and point the var at the container path: ` +
+      `--mount /host/path/to/credential:${path.posix.join(containerHome, 'credential')}:ro ` +
+      `with dockerEnvPassthrough '["MY_PATH_CREDENTIAL=${path.posix.join(containerHome, 'credential')}"]'`;
+
+    if (!docker.mount) {
+      const brokerPair =
+        (docker.envAuth && docker.envAuth.requireTogether && docker.envAuth.requireTogether[0]) ||
+        null;
+      const brokerHint = brokerPair
+        ? `Prefer the auth broker (${brokerPair.join(' + ')}) so host refresh tokens never cross. `
+        : '';
+      return (
+        `Export one of the listed vars. ${brokerHint}${customEnvHint}, or ${genericPathHint}. ` +
+        `${provider.displayName}'s host auth store is never mounted or copied into the container.`
       );
     }
+
+    const exampleHost = credentialPaths[0];
+    const mountHint = exampleHost
+      ? ` or --mount ${exampleHost}:${exampleHost.replace(/^~(?=\/|$)/, containerHome)}:ro for a custom path credential`
+      : '';
+    return `Export one of the listed vars, or add a custom credential with ${customEnvHint}${mountHint}.`;
   }
 
   _spawnContainer(clusterId, args, workDir) {
@@ -1374,40 +1636,207 @@ class IsolationManager {
     }
   }
 
+  /**
+   * Registry-owned Docker platform for a provider (e.g. 'linux/amd64'), or null when the
+   * provider declares no `docker.platform` (host-native, unset `--platform`).
+   * @param {string} providerName
+   * @returns {string|null}
+   */
+  static providerDockerPlatform(providerName) {
+    return providerDockerPlatform(providerName);
+  }
+
+  /**
+   * Registry-owned config/overlay roots for a provider, with $HOME expanded to containerHome.
+   * @param {string} providerName
+   * @param {string} [containerHome]
+   * @returns {string[]}
+   */
+  static providerConfigRoots(providerName, containerHome = '/root') {
+    return providerDockerConfigRootsRaw(providerName).map((root) =>
+      root.replace(/\$HOME/g, containerHome)
+    );
+  }
+
+  /**
+   * Parse the exact platform tokens advertised by `docker buildx inspect`.
+   *
+   * The `Platforms:` line is comma-delimited, and buildx marks preferred entries with a trailing
+   * `*`. Tokens are returned verbatim (minus that marker) so callers can compare exactly:
+   * `linux/amd64/v2` is a *variant*, not `linux/amd64`, and a substring test would wrongly accept
+   * a builder that only advertises the variant. Multiple builder nodes each emit their own
+   * `Platforms:` line; all are collected.
+   *
+   * @param {string} buildxOutput
+   * @returns {string[]}
+   */
+  static parseBuildxPlatforms(buildxOutput) {
+    const platforms = [];
+    for (const line of (buildxOutput || '').split('\n')) {
+      const trimmed = line.trim();
+      if (!trimmed.startsWith('Platforms:')) {
+        continue;
+      }
+      for (const token of trimmed.slice('Platforms:'.length).split(',')) {
+        const platform = token.trim().replace(/\*$/, '');
+        if (platform) {
+          platforms.push(platform);
+        }
+      }
+    }
+    return platforms;
+  }
+
+  /**
+   * Pre-effect probe: throws before any workspace/container side effect when the Docker engine
+   * cannot run `platform`. No-op when `platform` is null (provider declares no platform
+   * requirement). Native arch match satisfies the platform directly; otherwise a Buildx builder
+   * advertising exactly that platform (emulation) is required.
+   * @param {string|null} platform
+   * @param {{info?: () => string, buildxInspect?: () => string}} [probe] - command runners,
+   *   injectable for tests; defaults to the real `docker info` / `docker buildx inspect`
+   */
+  static assertPlatformSupported(platform, probe = {}) {
+    if (!platform) {
+      return;
+    }
+
+    const runInfo =
+      probe.info ||
+      (() =>
+        runSync('docker', ['info', '--format', '{{.OSType}}|{{.Architecture}}'], {
+          encoding: 'utf8',
+          stdio: 'pipe',
+        }));
+    const runBuildxInspect =
+      probe.buildxInspect ||
+      (() => runSync('docker', ['buildx', 'inspect'], { encoding: 'utf8', stdio: 'pipe' }));
+
+    let info;
+    try {
+      info = String(runInfo()).trim();
+    } catch (err) {
+      throw new Error(`Cannot determine Docker engine platform: ${err.message}`);
+    }
+
+    const [osType, arch] = info.split('|').map((part) => (part || '').trim());
+    const requiredArch = platform.split('/')[1] || '';
+    const nativeMatch = arch === requiredArch || (requiredArch === 'amd64' && arch === 'x86_64');
+
+    if (osType === 'linux' && nativeMatch) {
+      return;
+    }
+
+    let buildxOutput = '';
+    if (osType === 'linux') {
+      try {
+        buildxOutput = String(runBuildxInspect());
+      } catch {
+        buildxOutput = '';
+      }
+    }
+
+    if (
+      osType === 'linux' &&
+      IsolationManager.parseBuildxPlatforms(buildxOutput).includes(platform)
+    ) {
+      return;
+    }
+
+    throw new Error(
+      `Docker engine cannot run ${platform} (server ${osType || 'unknown'}/${arch || 'unknown'}, ` +
+        `no buildx builder advertising ${platform}). Install Buildx and run: ` +
+        `docker run --privileged --rm tonistiigi/binfmt --install ${requiredArch || platform}`
+    );
+  }
+
+  /**
+   * Split a Docker image reference into `{name, tag, digest}` per the reference grammar
+   * `[registry[:port]/]name[:tag][@digest]`.
+   *
+   * The only ambiguity is `:` — it is a registry port when it appears before the last `/`, and a
+   * tag separator only when it appears after it. `registry.example:5000/base` therefore has no
+   * tag, while `base:v2` does.
+   *
+   * @param {string} reference
+   * @returns {{name: string, tag: string|null, digest: string|null}}
+   */
+  static parseImageReference(reference) {
+    const atIndex = reference.indexOf('@');
+    const digest = atIndex === -1 ? null : reference.slice(atIndex + 1);
+    const withoutDigest = atIndex === -1 ? reference : reference.slice(0, atIndex);
+
+    const lastSlash = withoutDigest.lastIndexOf('/');
+    const colonIndex = withoutDigest.indexOf(':', lastSlash + 1);
+    const name = colonIndex === -1 ? withoutDigest : withoutDigest.slice(0, colonIndex);
+    const tag = colonIndex === -1 ? null : withoutDigest.slice(colonIndex + 1);
+
+    return { name, tag, digest };
+  }
+
   /**
    * Resolve the cluster image tag for a provider. Providers baked into the base image (e.g.
    * Claude) run on the base image directly; providers with a `docker.install` command get a
-   * per-provider image variant `<baseImage>-<providerId>` whose install step is a Docker-cached
-   * layer (built once, reused thereafter).
+   * per-provider image variant `<baseName>-<providerId>-<hash>`.
+   *
+   * `<baseName>` is the base reference's NAME only. A tag or digest may not be carried over: the
+   * derived value is a new locally-built tag, and `registry/base@sha256:…-omp-<hash>` /
+   * `base:v2-omp-<hash>` are not valid references (the first is a malformed digest, the second
+   * silently reinterprets the tag). A registry port is preserved because it belongs to the name
+   * (`registry.example:5000/base` → `registry.example:5000/base-omp-<hash>`).
+   *
+   * `<hash>` covers the FULL base reference (tag and digest included) alongside the install
+   * command and platform, so two different pins of the same base name — or a pinned-version or
+   * platform change — never collide on one cached tag.
+   *
    * @param {string} providerName
    * @param {string} [baseImage]
    * @returns {string}
    */
   static imageForProvider(providerName, baseImage = DEFAULT_IMAGE) {
-    if (!providerDockerInstall(providerName)) {
+    const install = providerDockerInstall(providerName);
+    if (!install) {
       return baseImage;
     }
-    return `${baseImage}-${normalizeProviderName(providerName)}`;
+    const platform = providerDockerPlatform(providerName) || '';
+    const { name } = IsolationManager.parseImageReference(baseImage);
+    const hash = crypto
+      .createHash('sha256')
+      .update(`${baseImage}\n${platform}\n${install}`)
+      .digest('hex')
+      .slice(0, 12);
+    return `${name}-${normalizeProviderName(providerName)}-${hash}`;
   }
 
   /**
-   * Docker `--build-arg` values that install a provider's CLI into its image variant, or [] when
-   * the provider is baked into the base image or has no installer.
+   * Docker `--build-arg` values that install a provider's CLI (and create its config roots) in
+   * its image variant, or [] when the provider is baked into the base image or has no installer.
    * @param {string} providerName
+   * @param {string} [containerHome]
    * @returns {string[]}
    */
-  static providerBuildArgs(providerName) {
+  static providerBuildArgs(providerName, containerHome = '/home/node') {
     const install = providerDockerInstall(providerName);
-    return install ? [`PROVIDER_INSTALL=${install}`] : [];
+    if (!install) {
+      return [];
+    }
+    const args = [`PROVIDER_INSTALL=${install}`];
+    const configRoots = IsolationManager.providerConfigRoots(providerName, containerHome);
+    if (configRoots.length > 0) {
+      args.push(`PROVIDER_CONFIG_ROOTS=${configRoots.join(' ')}`);
+    }
+    return args;
   }
 
   /**
    * Build the Docker image with retry logic
    * @param {string} [image] - Image name to build
    * @param {number} [maxRetries=3] - Maximum retry attempts
+   * @param {string[]} [buildArgs] - `--build-arg KEY=VALUE` pairs
+   * @param {string|null} [platform] - Registry-owned `--platform` value, or null for host-native
    * @returns {Promise<void>}
    */
-  static async buildImage(image = DEFAULT_IMAGE, maxRetries = 3, buildArgs = []) {
+  static async buildImage(image = DEFAULT_IMAGE, maxRetries = 3, buildArgs = [], platform = null) {
     // Repository root is one level up from src/
     const repoRoot = path.join(__dirname, '..');
     const dockerfilePath = path.join(repoRoot, 'docker', 'zeroshot-cluster', 'Dockerfile');
@@ -1421,6 +1850,7 @@ class IsolationManager {
     for (const arg of buildArgs) {
       buildArgFlags.push('--build-arg', arg);
     }
+    const platformFlags = platform ? ['--platform', platform] : [];
 
     console.log(`[IsolationManager] Building Docker image '${image}'...`);
 
@@ -1432,7 +1862,16 @@ class IsolationManager {
         // Use -f flag to specify Dockerfile location
         runSync(
           'docker',
-          ['build', '-f', 'docker/zeroshot-cluster/Dockerfile', ...buildArgFlags, '-t', image, '.'],
+          [
+            'build',
+            '-f',
+            'docker/zeroshot-cluster/Dockerfile',
+            ...platformFlags,
+            ...buildArgFlags,
+            '-t',
+            image,
+            '.',
+          ],
           {
             cwd: repoRoot,
             encoding: 'utf8',
@@ -1466,9 +1905,16 @@ class IsolationManager {
    * Ensure Docker image exists, building it if necessary
    * @param {string} [image] - Image name to ensure
    * @param {boolean} [autoBuild=true] - Auto-build if missing
+   * @param {string[]} [buildArgs] - `--build-arg KEY=VALUE` pairs
+   * @param {string|null} [platform] - Registry-owned `--platform` value, or null for host-native
    * @returns {Promise<void>}
    */
-  static async ensureImage(image = DEFAULT_IMAGE, autoBuild = true, buildArgs = []) {
+  static async ensureImage(
+    image = DEFAULT_IMAGE,
+    autoBuild = true,
+    buildArgs = [],
+    platform = null
+  ) {
     if (this.imageExists(image)) {
       return;
     }
@@ -1481,7 +1927,7 @@ class IsolationManager {
     }
 
     console.log(`[IsolationManager] Image '${image}' not found, building automatically...`);
-    await this.buildImage(image, 3, buildArgs);
+    await this.buildImage(image, 3, buildArgs, platform);
   }
 
   /**