From e4d60fcc986a805d5f445072fe9a440c98e0f0f1 Mon Sep 17 00:00:00 2001
From: laosb <git@lao.sb>
Date: Fri, 31 Jul 2026 14:26:00 +0800
Subject: [PATCH] feat: custom env support for apple container runtime.

---
 Sources/AgentIsolation/IsolationConfig.swift  |   3 +-
 .../AppleContainerEnvironment.swift           |  45 ++++
 .../AppleContainerRuntime.swift               |   9 +-
 .../DockerRuntime.swift                       |  53 ++--
 .../AppleContainerEnvironmentTests.swift      | 210 ++++++++++++++++
 .../DockerEnvironmentTests.swift              | 237 ++++++++++++++++++
 .../DockerRuntimeTests.swift                  |   3 +-
 7 files changed, 538 insertions(+), 22 deletions(-)
 create mode 100644 Sources/AgentIsolationAppleContainerRuntime/AppleContainerEnvironment.swift
 create mode 100644 Tests/AgentIsolationAppleContainerRuntimeTests/AppleContainerEnvironmentTests.swift
 create mode 100644 Tests/AgentIsolationDockerRuntimeTests/DockerEnvironmentTests.swift

diff --git a/Sources/AgentIsolation/IsolationConfig.swift b/Sources/AgentIsolation/IsolationConfig.swift
index 2fda813..76b83f5 100644
--- a/Sources/AgentIsolation/IsolationConfig.swift
+++ b/Sources/AgentIsolation/IsolationConfig.swift
@@ -45,7 +45,8 @@ public struct IsolationConfig: Sendable {
   public var arguments: [String]
 
   /// User-defined environment variables passed to the container.
-  /// Internal `AGENTC_*` variables take precedence when the session starts.
+  /// The `AGENTC_*` namespace is reserved for internal bootstrap controls; names in it
+  /// are dropped when the session starts.
   public var environment: [String: String]
 
   /// Whether to allocate a pseudo-TTY. Typically true when stdin is a terminal.
diff --git a/Sources/AgentIsolationAppleContainerRuntime/AppleContainerEnvironment.swift b/Sources/AgentIsolationAppleContainerRuntime/AppleContainerEnvironment.swift
new file mode 100644
index 0000000..78c45eb
--- /dev/null
+++ b/Sources/AgentIsolationAppleContainerRuntime/AppleContainerEnvironment.swift
@@ -0,0 +1,45 @@
+/// Environment variable handling for ``AppleContainerRuntime``.
+///
+/// Deliberately free of `Containerization` types so the merge rules build — and stay
+/// unit-testable — on every platform, not just where the runtime itself is available.
+enum AppleContainerEnvironment {
+  /// Merge agentc-supplied variables into an image's `KEY=VALUE` environment list.
+  ///
+  /// Entries are matched by name: an override replaces the image's value in place rather
+  /// than being appended, so an image default can never shadow a user value (a duplicate
+  /// name earlier in `environ` wins for `getenv`). This matches Docker's behavior, where
+  /// container `Env` overrides the image's `ENV` for the same name.
+  ///
+  /// Names not present in the image list are appended in sorted order, so the result is
+  /// deterministic even though `overrides` is an unordered dictionary. Image entries
+  /// without a `=` are passed through untouched.
+  static func merged(imageDefaults: [String], overrides: [String: String]) -> [String] {
+    var pending = overrides
+    var overridden = Set<String>()
+    var result: [String] = []
+    result.reserveCapacity(imageDefaults.count + overrides.count)
+
+    for entry in imageDefaults {
+      guard let separator = entry.firstIndex(of: "=") else {
+        // Not a `KEY=VALUE` entry — nothing to match on, keep it as-is.
+        result.append(entry)
+        continue
+      }
+      let name = String(entry[..<separator])
+
+      if let value = pending.removeValue(forKey: name) {
+        overridden.insert(name)
+        result.append("\(name)=\(value)")
+      } else if !overridden.contains(name) {
+        result.append(entry)
+      }
+      // else: a later duplicate of a name we already overrode — drop it.
+    }
+
+    for name in pending.keys.sorted() {
+      result.append("\(name)=\(pending[name]!)")
+    }
+
+    return result
+  }
+}
diff --git a/Sources/AgentIsolationAppleContainerRuntime/AppleContainerRuntime.swift b/Sources/AgentIsolationAppleContainerRuntime/AppleContainerRuntime.swift
index c61e91a..a0d8b9b 100644
--- a/Sources/AgentIsolationAppleContainerRuntime/AppleContainerRuntime.swift
+++ b/Sources/AgentIsolationAppleContainerRuntime/AppleContainerRuntime.swift
@@ -144,10 +144,11 @@
           containerConfig.process.workingDirectory = workDir
         }
 
-        // Environment
-        for (key, value) in configuration.environment {
-          containerConfig.process.environmentVariables.append("\(key)=\(value)")
-        }
+        // Environment: image defaults, with our values overriding matching names.
+        containerConfig.process.environmentVariables = AppleContainerEnvironment.merged(
+          imageDefaults: containerConfig.process.environmentVariables,
+          overrides: configuration.environment
+        )
 
         // Mounts
         for mount in configuration.mounts {
diff --git a/Sources/AgentIsolationDockerRuntime/DockerRuntime.swift b/Sources/AgentIsolationDockerRuntime/DockerRuntime.swift
index c9ccd4e..10aa6d1 100644
--- a/Sources/AgentIsolationDockerRuntime/DockerRuntime.swift
+++ b/Sources/AgentIsolationDockerRuntime/DockerRuntime.swift
@@ -130,17 +130,27 @@ public final class DockerRuntime: ContainerRuntime, Sendable {
     try await client.removeImage(nameOrDigest: digest)
   }
 
-  public func runContainer(
-    imageRef: String,
-    configuration: ContainerConfiguration
-  ) async throws -> DockerContainer {
-    let useTTY: Bool
-    switch configuration.io {
-    case .currentTerminal: useTTY = true
-    case .custom(_, _, _, let isTerminal): useTTY = isTerminal
-    default: useTTY = false
+  /// Whether the container should be created with a pseudo-TTY.
+  static func usesTTY(for io: ContainerConfiguration.IO) -> Bool {
+    switch io {
+    case .currentTerminal: return true
+    case .custom(_, _, _, let isTerminal): return isTerminal
+    default: return false
     }
+  }
 
+  /// Build the Docker Engine create-container payload for a configuration.
+  ///
+  /// Pure translation of ``ContainerConfiguration`` to Docker's wire format, kept separate
+  /// from ``runContainer(imageRef:configuration:)`` so it can be tested without a daemon.
+  ///
+  /// `Env` is left `nil` when no variables are set, so the image's own `ENV` is untouched.
+  /// Otherwise the daemon merges these entries over the image's by name, which is why we
+  /// pass them through as-is rather than reconciling anything here.
+  static func makeCreateRequest(
+    imageRef: String,
+    configuration: ContainerConfiguration
+  ) -> DockerCreateContainerRequest {
     // Build bind mounts
     var binds: [String] = []
     for mount in configuration.mounts {
@@ -148,23 +158,24 @@ public final class DockerRuntime: ContainerRuntime, Sendable {
       binds.append("\(mount.hostPath):\(mount.containerPath):\(opts)")
     }
 
-    // Build environment
+    // Build environment. Sorted so the same configuration always produces the same
+    // payload — `environment` is an unordered dictionary.
     let envVars: [String]? =
       configuration.environment.isEmpty
       ? nil
-      : configuration.environment.map { "\($0.key)=\($0.value)" }
+      : configuration.environment.keys.sorted().map { "\($0)=\(configuration.environment[$0]!)" }
 
-    // Create container – when a custom entrypoint override is requested, set Docker's
-    // Entrypoint field to replace the image's built-in ENTRYPOINT. Otherwise, use Cmd
-    // so the image's ENTRYPOINT receives these as arguments.
+    // When a custom entrypoint override is requested, set Docker's Entrypoint field to
+    // replace the image's built-in ENTRYPOINT. Otherwise, use Cmd so the image's
+    // ENTRYPOINT receives these as arguments.
     let entryArgs = configuration.entrypoint.isEmpty ? nil : configuration.entrypoint
-    let createConfig = DockerCreateContainerRequest(
+    return DockerCreateContainerRequest(
       Image: imageRef,
       Entrypoint: configuration.overridesImageEntrypoint ? entryArgs : nil,
       Cmd: configuration.overridesImageEntrypoint ? nil : entryArgs,
       Env: envVars,
       WorkingDir: configuration.workingDirectory,
-      Tty: useTTY,
+      Tty: Self.usesTTY(for: configuration.io),
       OpenStdin: true,
       AttachStdin: true,
       AttachStdout: true,
@@ -177,6 +188,16 @@ public final class DockerRuntime: ContainerRuntime, Sendable {
         Init: true
       )
     )
+  }
+
+  public func runContainer(
+    imageRef: String,
+    configuration: ContainerConfiguration
+  ) async throws -> DockerContainer {
+    let useTTY = Self.usesTTY(for: configuration.io)
+
+    let createConfig = Self.makeCreateRequest(
+      imageRef: imageRef, configuration: configuration)
 
     let containerId = try await client.createContainer(config: createConfig)
 
diff --git a/Tests/AgentIsolationAppleContainerRuntimeTests/AppleContainerEnvironmentTests.swift b/Tests/AgentIsolationAppleContainerRuntimeTests/AppleContainerEnvironmentTests.swift
new file mode 100644
index 0000000..94b6758
--- /dev/null
+++ b/Tests/AgentIsolationAppleContainerRuntimeTests/AppleContainerEnvironmentTests.swift
@@ -0,0 +1,210 @@
+#if ContainerRuntimeAppleContainer
+  @testable import AgentIsolationAppleContainerRuntime
+  import Testing
+
+  // MARK: - Environment Merge Unit Tests
+
+  @Suite("AppleContainerRuntime Environment Merge")
+  struct AppleContainerEnvironmentTests {
+
+    /// Parse a merged entry list back into names → values for order-independent checks.
+    private func parsed(_ entries: [String]) -> [String: String] {
+      var result: [String: String] = [:]
+      for entry in entries {
+        guard let separator = entry.firstIndex(of: "=") else { continue }
+        let name = String(entry[..<separator])
+        // First occurrence wins, mirroring `getenv` on a duplicated `environ`.
+        if result[name] == nil {
+          result[name] = String(entry[entry.index(after: separator)...])
+        }
+      }
+      return result
+    }
+
+    // MARK: - Pass-through
+
+    @Test("Image defaults are unchanged when there are no overrides")
+    func noOverridesKeepsImageDefaults() {
+      let defaults = ["PATH=/usr/bin", "LANG=C.UTF-8"]
+      let merged = AppleContainerEnvironment.merged(imageDefaults: defaults, overrides: [:])
+      #expect(merged == defaults)
+    }
+
+    @Test("Overrides alone become the whole environment")
+    func overridesWithoutImageDefaults() {
+      let merged = AppleContainerEnvironment.merged(
+        imageDefaults: [],
+        overrides: ["TZ": "America/Los_Angeles", "LC_ALL": "en_US.UTF-8"]
+      )
+      #expect(merged == ["LC_ALL=en_US.UTF-8", "TZ=America/Los_Angeles"])
+    }
+
+    @Test("Empty inputs produce an empty environment")
+    func emptyInputs() {
+      #expect(AppleContainerEnvironment.merged(imageDefaults: [], overrides: [:]).isEmpty)
+    }
+
+    // MARK: - Override semantics
+
+    @Test("Override replaces the image value in place instead of appending")
+    func overrideReplacesInPlace() {
+      let merged = AppleContainerEnvironment.merged(
+        imageDefaults: ["PATH=/usr/bin", "TZ=UTC", "LANG=C.UTF-8"],
+        overrides: ["TZ": "America/Los_Angeles"]
+      )
+      // Same slot, same count — an appended duplicate would leave "TZ=UTC" first
+      // and `getenv` inside the container would still report UTC.
+      #expect(merged == ["PATH=/usr/bin", "TZ=America/Los_Angeles", "LANG=C.UTF-8"])
+      #expect(!merged.contains("TZ=UTC"))
+    }
+
+    @Test("Overridden name appears exactly once")
+    func overriddenNameAppearsOnce() {
+      let merged = AppleContainerEnvironment.merged(
+        imageDefaults: ["TZ=UTC"],
+        overrides: ["TZ": "Europe/Berlin"]
+      )
+      #expect(merged.filter { $0.hasPrefix("TZ=") }.count == 1)
+      #expect(parsed(merged)["TZ"] == "Europe/Berlin")
+    }
+
+    @Test("Overriding one name leaves the other image defaults alone")
+    func overridePreservesUnrelatedDefaults() {
+      let merged = AppleContainerEnvironment.merged(
+        imageDefaults: ["PATH=/usr/bin", "HOME=/home/agent", "TZ=UTC"],
+        overrides: ["TZ": "Asia/Shanghai"]
+      )
+      let env = parsed(merged)
+      #expect(env["PATH"] == "/usr/bin")
+      #expect(env["HOME"] == "/home/agent")
+      #expect(env["TZ"] == "Asia/Shanghai")
+      #expect(merged.count == 3)
+    }
+
+    @Test("Duplicate image entries for an overridden name collapse to the override")
+    func duplicateImageEntriesCollapse() {
+      let merged = AppleContainerEnvironment.merged(
+        imageDefaults: ["TZ=UTC", "PATH=/usr/bin", "TZ=Etc/GMT"],
+        overrides: ["TZ": "Europe/Berlin"]
+      )
+      #expect(merged == ["TZ=Europe/Berlin", "PATH=/usr/bin"])
+    }
+
+    @Test("Duplicate image entries are kept when not overridden")
+    func duplicateImageEntriesKeptWithoutOverride() {
+      let defaults = ["TZ=UTC", "TZ=Etc/GMT"]
+      let merged = AppleContainerEnvironment.merged(imageDefaults: defaults, overrides: [:])
+      #expect(merged == defaults)
+    }
+
+    // MARK: - New names
+
+    @Test("New names are appended after the image defaults")
+    func newNamesAppended() {
+      let merged = AppleContainerEnvironment.merged(
+        imageDefaults: ["PATH=/usr/bin"],
+        overrides: ["TZ": "UTC"]
+      )
+      #expect(merged == ["PATH=/usr/bin", "TZ=UTC"])
+    }
+
+    @Test("Appended names are sorted, so the result is deterministic")
+    func appendedNamesAreSorted() {
+      let overrides = [
+        "TZ": "UTC", "LC_ALL": "en_US.UTF-8", "AGENTC_CONFIGURATIONS": "claude",
+        "EDITOR": "vim", "LANG": "en_US.UTF-8",
+      ]
+      let expected = [
+        "PATH=/usr/bin",
+        "AGENTC_CONFIGURATIONS=claude",
+        "EDITOR=vim",
+        "LANG=en_US.UTF-8",
+        "LC_ALL=en_US.UTF-8",
+        "TZ=UTC",
+      ]
+      // Repeat: dictionary iteration order varies per instance, so a single pass could
+      // pass by luck if the output depended on it.
+      for _ in 0..<10 {
+        let merged = AppleContainerEnvironment.merged(
+          imageDefaults: ["PATH=/usr/bin"], overrides: overrides)
+        #expect(merged == expected)
+      }
+    }
+
+    @Test("Every override reaches the container exactly once")
+    func allOverridesPresent() {
+      let overrides = ["TZ": "UTC", "LANG": "C.UTF-8", "FOO": "bar", "PATH": "/opt/bin"]
+      let merged = AppleContainerEnvironment.merged(
+        imageDefaults: ["PATH=/usr/bin", "HOME=/home/agent"],
+        overrides: overrides
+      )
+      #expect(merged.count == 5)  // 4 overrides + HOME
+      for (name, value) in overrides {
+        #expect(merged.filter { $0.hasPrefix("\(name)=") } == ["\(name)=\(value)"])
+      }
+    }
+
+    // MARK: - Value shapes
+
+    @Test("Empty override value is preserved as a set-but-empty variable")
+    func emptyValue() {
+      let merged = AppleContainerEnvironment.merged(
+        imageDefaults: ["EMPTY=not-empty"],
+        overrides: ["EMPTY": "", "ALSO_EMPTY": ""]
+      )
+      #expect(merged == ["EMPTY=", "ALSO_EMPTY="])
+      #expect(parsed(merged)["EMPTY"] == "")
+    }
+
+    @Test("Values containing '=' are preserved intact")
+    func valueWithEquals() {
+      let merged = AppleContainerEnvironment.merged(
+        imageDefaults: [],
+        overrides: ["JAVA_TOOL_OPTIONS": "-Dfoo=bar -Dbaz=qux"]
+      )
+      #expect(merged == ["JAVA_TOOL_OPTIONS=-Dfoo=bar -Dbaz=qux"])
+    }
+
+    @Test("An image entry whose value contains '=' is matched on its name only")
+    func imageValueWithEqualsIsOverridable() {
+      let merged = AppleContainerEnvironment.merged(
+        imageDefaults: ["OPTS=-Dfoo=bar"],
+        overrides: ["OPTS": "-Dfoo=baz"]
+      )
+      #expect(merged == ["OPTS=-Dfoo=baz"])
+    }
+
+    @Test("Values with spaces, newlines, and non-ASCII text survive unmodified")
+    func exoticValues() {
+      let overrides = [
+        "SPACED": "a b  c",
+        "MULTILINE": "line1\nline2",
+        "UNICODE": "日本語 🌏",
+      ]
+      let env = parsed(AppleContainerEnvironment.merged(imageDefaults: [], overrides: overrides))
+      #expect(env["SPACED"] == "a b  c")
+      #expect(env["MULTILINE"] == "line1\nline2")
+      #expect(env["UNICODE"] == "日本語 🌏")
+    }
+
+    // MARK: - Malformed image entries
+
+    @Test("Image entries without '=' are passed through untouched")
+    func imageEntryWithoutSeparator() {
+      let merged = AppleContainerEnvironment.merged(
+        imageDefaults: ["MALFORMED", "TZ=UTC"],
+        overrides: ["TZ": "Europe/Berlin"]
+      )
+      #expect(merged == ["MALFORMED", "TZ=Europe/Berlin"])
+    }
+
+    @Test("An image entry with an empty name is not confused with an override")
+    func imageEntryWithEmptyName() {
+      let merged = AppleContainerEnvironment.merged(
+        imageDefaults: ["=stray", "TZ=UTC"],
+        overrides: ["TZ": "Europe/Berlin"]
+      )
+      #expect(merged == ["=stray", "TZ=Europe/Berlin"])
+    }
+  }
+#endif
diff --git a/Tests/AgentIsolationDockerRuntimeTests/DockerEnvironmentTests.swift b/Tests/AgentIsolationDockerRuntimeTests/DockerEnvironmentTests.swift
new file mode 100644
index 0000000..fb89c02
--- /dev/null
+++ b/Tests/AgentIsolationDockerRuntimeTests/DockerEnvironmentTests.swift
@@ -0,0 +1,237 @@
+#if ContainerRuntimeDocker
+  import AgentIsolation
+  @testable import AgentIsolationDockerRuntime
+  import Foundation
+  import Testing
+
+  // MARK: - Create Request Environment Unit Tests
+
+  /// Unlike the Apple runtime, the Docker runtime does not reconcile our variables with the
+  /// image's `ENV` — the daemon merges them by name, with ours winning. So these tests pin
+  /// what we put on the wire; ``DockerRuntimeEnvironmentIntegrationTests`` pins the merge
+  /// the daemon performs.
+  @Suite("DockerRuntime Create Request Environment")
+  struct DockerCreateRequestEnvironmentTests {
+
+    private func request(
+      environment: [String: String],
+      entrypoint: [String] = ["echo", "hi"]
+    ) -> DockerCreateContainerRequest {
+      DockerRuntime.makeCreateRequest(
+        imageRef: "alpine:latest",
+        configuration: ContainerConfiguration(
+          entrypoint: entrypoint,
+          environment: environment,
+          io: .standardIO
+        )
+      )
+    }
+
+    /// Parse `Env` back into names → values for order-independent checks.
+    private func parsed(_ entries: [String]) -> [String: String] {
+      var result: [String: String] = [:]
+      for entry in entries {
+        guard let separator = entry.firstIndex(of: "=") else { continue }
+        if result[String(entry[..<separator])] == nil {
+          result[String(entry[..<separator])] = String(entry[entry.index(after: separator)...])
+        }
+      }
+      return result
+    }
+
+    // MARK: - Absent vs. present
+
+    @Test("Env is nil when no variables are set, leaving the image's ENV untouched")
+    func envOmittedWhenEmpty() {
+      #expect(request(environment: [:]).Env == nil)
+    }
+
+    @Test("Env is omitted from the JSON payload when no variables are set")
+    func envAbsentFromJSON() throws {
+      let data = try JSONEncoder().encode(request(environment: [:]))
+      let json = String(decoding: data, as: UTF8.self)
+      #expect(!json.contains("\"Env\""))
+      // And it is present once variables exist.
+      let withEnv = try JSONEncoder().encode(request(environment: ["TZ": "UTC"]))
+      #expect(String(decoding: withEnv, as: UTF8.self).contains("\"Env\":[\"TZ=UTC\"]"))
+    }
+
+    @Test("Env carries every variable as a single KEY=VALUE entry")
+    func envEntries() {
+      let env = request(environment: ["TZ": "America/Los_Angeles", "LC_ALL": "en_US.UTF-8"]).Env
+      #expect(env == ["LC_ALL=en_US.UTF-8", "TZ=America/Los_Angeles"])
+    }
+
+    @Test("Every variable reaches the payload exactly once")
+    func allVariablesPresentOnce() {
+      let environment = ["TZ": "UTC", "LANG": "C.UTF-8", "FOO": "bar", "PATH": "/opt/bin"]
+      let env = request(environment: environment).Env ?? []
+      #expect(env.count == environment.count)
+      for (name, value) in environment {
+        #expect(env.filter { $0.hasPrefix("\(name)=") } == ["\(name)=\(value)"])
+      }
+    }
+
+    // MARK: - Determinism
+
+    @Test("Entries are sorted, so the same configuration always yields the same payload")
+    func entriesAreSorted() {
+      let environment = [
+        "TZ": "UTC", "LC_ALL": "en_US.UTF-8", "AGENTC_CONFIGURATIONS": "claude",
+        "EDITOR": "vim", "LANG": "en_US.UTF-8",
+      ]
+      let expected = [
+        "AGENTC_CONFIGURATIONS=claude",
+        "EDITOR=vim",
+        "LANG=en_US.UTF-8",
+        "LC_ALL=en_US.UTF-8",
+        "TZ=UTC",
+      ]
+      // Repeat: dictionary iteration order varies per instance, so a single pass could
+      // pass by luck if the output depended on it.
+      for _ in 0..<10 {
+        #expect(request(environment: environment).Env == expected)
+      }
+    }
+
+    // MARK: - Value shapes
+
+    @Test("Empty value is sent as a set-but-empty variable")
+    func emptyValue() {
+      let env = request(environment: ["EMPTY": ""]).Env
+      #expect(env == ["EMPTY="])
+      #expect(parsed(env ?? [])["EMPTY"] == "")
+    }
+
+    @Test("Values containing '=' are preserved intact")
+    func valueWithEquals() {
+      let env = request(environment: ["JAVA_TOOL_OPTIONS": "-Dfoo=bar -Dbaz=qux"]).Env
+      #expect(env == ["JAVA_TOOL_OPTIONS=-Dfoo=bar -Dbaz=qux"])
+    }
+
+    @Test("Values with spaces, newlines, and non-ASCII text survive JSON encoding")
+    func exoticValuesRoundTrip() throws {
+      let environment = [
+        "SPACED": "a b  c",
+        "MULTILINE": "line1\nline2",
+        "UNICODE": "日本語 🌏",
+        "QUOTED": #"say "hi""#,
+      ]
+      let data = try JSONEncoder().encode(request(environment: environment))
+      let decoded = try JSONDecoder().decode(DockerCreateContainerRequest.self, from: data)
+      #expect(parsed(decoded.Env ?? []) == environment)
+    }
+
+    // MARK: - Independence from other fields
+
+    @Test("Setting variables does not disturb entrypoint dispatch")
+    func envDoesNotAffectEntrypoint() {
+      let withEnv = request(environment: ["TZ": "UTC"], entrypoint: ["echo", "hi"])
+      let without = request(environment: [:], entrypoint: ["echo", "hi"])
+      #expect(withEnv.Cmd == without.Cmd)
+      #expect(withEnv.Entrypoint == without.Entrypoint)
+      #expect(withEnv.Cmd == ["echo", "hi"])
+      #expect(withEnv.Entrypoint == nil)
+    }
+
+    @Test("Variables are sent the same way when the image entrypoint is overridden")
+    func envWithEntrypointOverride() {
+      let request = DockerRuntime.makeCreateRequest(
+        imageRef: "alpine:latest",
+        configuration: ContainerConfiguration(
+          entrypoint: ["/entrypoint-bootstrap/bootstrap"],
+          overridesImageEntrypoint: true,
+          environment: ["TZ": "UTC"],
+          io: .standardIO
+        )
+      )
+      #expect(request.Env == ["TZ=UTC"])
+      #expect(request.Entrypoint == ["/entrypoint-bootstrap/bootstrap"])
+      #expect(request.Cmd == nil)
+    }
+  }
+
+  // MARK: - Environment Integration Tests
+
+  @Suite("DockerRuntime Environment Integration", .enabled(if: isDockerAvailable()))
+  struct DockerRuntimeEnvironmentIntegrationTests {
+
+    private func makeRuntime() -> DockerRuntime {
+      let endpoint = ProcessInfo.processInfo.environment["CLAUDEC_DOCKER_ENDPOINT"]
+      let config = ContainerRuntimeConfiguration(
+        storagePath: "/tmp/claudec-test-docker", endpoint: endpoint)
+      return DockerRuntime(config: config)
+    }
+
+    /// Run `sh -c script` in alpine and return its stdout.
+    private func capture(script: String, environment: [String: String]) async throws -> (
+      exitCode: Int32, stdout: String
+    ) {
+      let runtime = makeRuntime()
+      defer { Task { try? await runtime.shutdown() } }
+      try await runtime.prepare()
+
+      _ = try await runtime.pullImage(ref: "alpine:latest")
+
+      let stdout = MockWriter()
+      let container = try await runtime.runContainer(
+        imageRef: "alpine:latest",
+        configuration: ContainerConfiguration(
+          entrypoint: ["/bin/sh", "-c", script],
+          environment: environment,
+          io: .custom(stdin: EmptyReaderStream(), stdout: stdout, stderr: MockWriter())
+        )
+      )
+
+      let exitCode = try await container.wait(timeoutInSeconds: 30)
+      try await runtime.removeContainer(container)
+      return (exitCode, stdout.string)
+    }
+
+    @Test("Our value overrides a variable the image already sets")
+    func overridesImageEnv() async throws {
+      // alpine's image config sets PATH; keep the real directories on it so the shell
+      // still works, and prepend a marker we can assert on.
+      let result = try await capture(
+        script: "printf '%s' \"$PATH\"",
+        environment: ["PATH": "/custom/bin:/usr/sbin:/usr/bin:/sbin:/bin"]
+      )
+      #expect(result.exitCode == 0)
+      #expect(result.stdout == "/custom/bin:/usr/sbin:/usr/bin:/sbin:/bin")
+    }
+
+    @Test("Variables the image sets are inherited when we do not override them")
+    func inheritsImageEnv() async throws {
+      let result = try await capture(
+        script: "printf '%s|%s' \"$PATH\" \"$TZ\"",
+        environment: ["TZ": "Europe/Berlin"]
+      )
+      #expect(result.exitCode == 0)
+      // The image's PATH survives alongside the variable we added.
+      #expect(result.stdout.hasSuffix("|Europe/Berlin"))
+      #expect(result.stdout.contains("/usr/bin"))
+      #expect(!result.stdout.hasPrefix("|"))
+    }
+
+    @Test("An empty value arrives as a set-but-empty variable, not as unset")
+    func emptyValueIsSet() async throws {
+      // `${VAR+set}` expands to "set" only when VAR is defined, empty or not.
+      let result = try await capture(
+        script: "printf '%s|%s' \"${EMPTY+set}\" \"${EMPTY}\"",
+        environment: ["EMPTY": ""]
+      )
+      #expect(result.exitCode == 0)
+      #expect(result.stdout == "set|")
+    }
+
+    @Test("A value containing '=' arrives intact")
+    func valueWithEqualsArrivesIntact() async throws {
+      let result = try await capture(
+        script: "printf '%s' \"$OPTS\"",
+        environment: ["OPTS": "-Dfoo=bar -Dbaz=qux"]
+      )
+      #expect(result.exitCode == 0)
+      #expect(result.stdout == "-Dfoo=bar -Dbaz=qux")
+    }
+  }
+#endif
diff --git a/Tests/AgentIsolationDockerRuntimeTests/DockerRuntimeTests.swift b/Tests/AgentIsolationDockerRuntimeTests/DockerRuntimeTests.swift
index 0565046..26522e8 100644
--- a/Tests/AgentIsolationDockerRuntimeTests/DockerRuntimeTests.swift
+++ b/Tests/AgentIsolationDockerRuntimeTests/DockerRuntimeTests.swift
@@ -343,7 +343,8 @@
 
   // MARK: - DockerRuntime Integration Tests
 
-  private func isDockerAvailable() -> Bool {
+  /// Shared by the integration suites across this target's test files.
+  func isDockerAvailable() -> Bool {
     FileManager.default.fileExists(atPath: "/var/run/docker.sock")
       || ProcessInfo.processInfo.environment["CLAUDEC_DOCKER_ENDPOINT"] != nil
   }