feat(gateway): support process-level runtime image overrides

Start in crates/openshell-core/src/config.rs by reading default_sandbox_runtime_image() and default_supervisor_image(), then trace how Docker, Podman, and Kubernetes consume those defaults and how gateway.env is loaded by the Debian and RPM units. Done means the stated precedence, validation, diagnostics, package delivery, documentation, and end-to-end qualification behavior are covered without changing existing unset-variable behavior.

User Story

As an OpenShell operator or release qualification maintainer, I want to override the trusted sandbox and supervisor runtime image references when the gateway starts, so that I can run an unmodified package against exact candidate artifacts without generating driver-specific gateway configuration.

Problem Statement

OpenShell embeds default sandbox and supervisor image tags into the gateway binary at build time. At runtime, the only supported overrides live in driver-specific TOML tables such as [openshell.drivers.docker], [openshell.drivers.podman], and [openshell.drivers.kubernetes].

Package qualification therefore has to create a driver-specific gateway.toml even when the only desired change is selecting exact candidate runtime images. This makes qualification-only configuration look like required package configuration and requires the same artifact selection to be expressed separately for each driver.

This need surfaced while adding Debian-package qualification in #3461 as part of #3454.

Impact / Why This Matters

Today, release tooling must either:

• generate and select a driver-specific gateway configuration;
• rebuild the gateway with a test-specific embedded image tag; or
• retag candidate images to match the binary's compiled defaults.

Generating TOML conflates harness-owned artifact selection with operator-owned gateway configuration. Rebuilding means the test no longer exercises the exact release binary. Retagging is unreliable for mutable defaults such as dev and latest, which the local drivers intentionally refresh.

A process-level override would let package tests preserve the package-owned service and configuration lifecycle while pairing the unmodified gateway binary with exact, immutable sandbox and supervisor artifacts. It would also give operators a concise way to use registry mirrors or digest-pinned trusted runtime components without maintaining otherwise-empty driver tables.

Proposed Design

Allow the gateway process to accept complete runtime image references through environment variables:

OPENSHELL_SANDBOX_RUNTIME_IMAGE=registry.example.com/openshell/sandbox@sha256:...
OPENSHELL_SUPERVISOR_IMAGE=registry.example.com/openshell/supervisor@sha256:...

These values act as process-level defaults for built-in compute drivers that consume the trusted sandbox and supervisor OCI images. Explicit values in the selected driver's TOML table remain authoritative.

The observable precedence is:

driver-specific TOML > process environment > compiled release default

The variables accept complete tagged or digest-pinned OCI references. Package-managed services can receive them through their existing environment-file mechanism. Package preflight and actual startup must resolve and validate the same effective references. Sandbox requests cannot override these gateway-owned trusted runtime images.

Acceptance Criteria

• The gateway accepts process-level sandbox-runtime and supervisor image references at startup.
• Docker, Podman, and Kubernetes use the process-level references when their selected driver configuration does not set explicit image references.
• Explicit driver-specific TOML image references override the process environment.
• When the environment variables are unset, existing compiled defaults and behavior remain unchanged.
• Tagged and digest-pinned OCI references are supported.
• Package preflight validates the same effective references used by gateway startup.
• Debian and RPM user services can consume the overrides through their existing gateway.env mechanism.
• End-to-end coverage installs an unmodified package, supplies exact candidate runtime images through the environment, and runs without generating an operator gateway.toml.
• Documentation describes the variables, precedence, supported drivers, and trust implications.
• The effective runtime image references and their configuration source are visible in startup diagnostics without exposing credentials.

Alternatives Considered

Generate driver-specific TOML. This works today, but duplicates a cross-driver artifact-selection concern and makes qualification configuration appear operator-owned.

Compile a gateway specifically for qualification. This can embed the candidate tag, but the resulting binary is not the release artifact being qualified.

Retag local images to the compiled references. This can work for immutable release tags, but mutable dev and latest references are refreshed and may resolve to a different remote image.

Expose only a shared tag variable. A tag-only override cannot select another registry or an immutable digest, so complete image references are more generally useful.

Agent Investigation

The shared defaults are produced by default_sandbox_runtime_image() and default_supervisor_image() in crates/openshell-core/src/config.rs; their tag comes from the build-time OPENSHELL_IMAGE_TAG or IMAGE_TAG. Docker, Podman, and Kubernetes consume these shared defaults but expose runtime overrides only through their own driver configuration tables. The Debian and RPM package units already load ~/.config/openshell/gateway.env, providing a package-compatible delivery mechanism for process-level settings.