fix(atom): align user-selected execution and kernel integration

.github/pre-release/prompts/pre-release/demo-12h-forge.md

@@ -16,10 +16,9 @@ unset, silently leaves GEAK owning the kernel phase. There is no CLI flag for it
 
 Two ways this silently degrades into a duplicate of the plain 12h leg — avoid both:
 
-- The demo skill's pre-launch install block sources `.env`, which sets
-  `KERNEL_OPT_BACKEND_ORDER` to whatever that file carries, and then replays the
-  caller's pre-existing exports on top via `eval "$_dotenv_prev"`. Export `forge`
-  **after** that whole block, not before.
+- The demo skill's shared environment loader fills missing values from `.env`
+  without overriding non-empty caller exports. Export `forge` in the execution
+  shell and verify it remains selected after environment preparation.
 - In docker mode the variable must be set **inside the same `docker exec`** that runs
   `optimize`. Exporting it on the host does not reach the optimizer.
 

docs/compatibility.rst

@@ -54,7 +54,7 @@ The following table lists the minimum requirements for running Hyperloom.
 | Python              | >= 3.10                                                |
 +---------------------+--------------------------------------------------------+
 | Inference Framework | SGLang (>= 0.5.12), vLLM (>= 0.21.0),                  |
-|                     | Atom (>= 0.1.7-rc0), plus ``custom`` for your own      |
+|                     | ATOM (preinstalled; see below), plus ``custom``        |
 |                     | benchmark script                                       |
 +---------------------+--------------------------------------------------------+
 | Kernel Languages    | HIP, Triton, FlyDSL                                    |
@@ -129,9 +129,9 @@ The following inference frameworks are supported:
        ``rocm723`` wheel, a ROCm 10 host (``torch.version.hip`` 7.15) builds vLLM
        from source, and any other combination is rejected (see below). Do not mix
        frameworks within one session
-   * - Atom
-     - 7.2.4
-     - AMD out-of-tree engine, launched as ``python3 -m atom.entrypoints.openai_server``. Container image only: ``install_baremetal.sh`` verifies ``atom`` but cannot install it, because ``--install-framework`` accepts only ``none``, ``sglang`` and ``vllm``. The kernel phase defaults to the KernelForge backend here (``KERNEL_OPT_BACKEND_ORDER`` is set to ``forge`` when you leave it unset). On a quantized non-vLLM backend GEAK must resolve a live rewrite seam rather than guess one, which forge does not require.
+   * - ATOM
+     - 7.2.4 (recorded image stack)
+     - AMD out-of-tree engine, launched as ``python3 -m atom.entrypoints.openai_server``. Supports Docker or direct execution in a preinstalled ATOM/ROCm torch environment. The recorded image-based stack used ``rocm/atom-dev:v0.1.7-rc0`` on MI355X, not a universal ATOM pip-version minimum. Other builds require local validation. The CLI defaults an unset/empty ``KERNEL_OPT_BACKEND_ORDER`` to ``forge`` on ATOM and preserves explicit values; GEAK's live rewrite-seam resolution is unproven here.
    * - ``custom``
      - Host-defined
      - Escape hatch for your own benchmark script; Hyperloom does not manage the server lifecycle. Requires ``HYPERLOOM_BENCHMARK_BACKEND=bypass`` plus ``--framework-path`` (or ``FRAMEWORK_REPO_PATH``) and ``--benchmark-scripts-dir`` (or ``HYPERLOOM_BYPASS_SCRIPTS_DIR``); the CLI exits with status 2 when any of the three is missing.
@@ -186,6 +186,23 @@ Bare-metal recommended environment
 For ``baremetal`` setup, align the host to this combination before running setup.
 Hyperloom does not install ROCm or torch itself.
 
+For ATOM, ``baremetal`` means running directly in the development machine's
+selected Python environment, including when the development platform itself is
+a container; it does not start an additional Docker container. ATOM must already
+be installed. Verify a real ``import atom`` and a non-empty ``torch.version.hip``
+with that Python, keep its executable first on ``PATH`` for Magpie's ``python3``
+launch, and use ``PYTHON`` with ``INFERENCE_OPTIMIZER_FORCE_PYTHON=1`` if pinning
+the interpreter. Keep any activated venv consistent; ``/opt/venv`` is not required.
+
+Run ``python -m hyperloom.inference_optimizer.setup --check-only --
+--install-framework none --frameworks atom --require-frameworks`` with the
+selected interpreter first. Only after approval, repeat without ``--check-only``:
+``none`` skips framework installation but can still write configuration and
+apply ROCm hotfixes. Preserve the selected ``USER_DATA_PATH``; an existing setup
+need not be repeated. Hyperloom does not install ATOM and does not assert a
+minimum ATOM package version derived from a Docker tag. Import checks establish
+local prerequisites, not end-to-end validation of every stack.
+
 .. list-table::
    :header-rows: 1
    :widths: 15 25 60

docs/how-to/optimize-custom-workload.md

@@ -210,23 +210,19 @@ auto-detects through `rocm-smi --showproductname`.
 **Pin GPUs with `ROCR_VISIBLE_DEVICES`, not `HIP_VISIBLE_DEVICES`.** On the known
 ROCm stack the latter can make `torch.cuda.is_available()` return false.
 
-**Export credentials from the launching shell.** Preflight refuses to load
-`*_CUSTOM_HEADERS` out of `.env`, so a gateway subscription key only reaches the
-SDK if the launching shell exports it. Without it every catalog probe and every
-orchestration turn returns HTTP 401 and the run idles in `PRELUDE` for the whole
-budget. See [Authentication and credentials](../reference/authentication.md).
+**Load workspace settings through the shared loader.** Existing caller values
+remain authoritative, including gateway keys and custom headers. The loader reads
+`.env` as data rather than executing it; never print credential values. See
+[Authentication and credentials](../reference/authentication.md).
 
 ```bash
-# Run from the workspace holding the hyperloom package; no installer exports REPO_ROOT.
 export REPO_ROOT="${REPO_ROOT:-$(pwd -P)}"
-# .env fills gaps only: re-exporting the non-empty pre-source snapshot keeps every
-# value the caller exported. Wider than install.sh, which guards a fixed list.
-_dotenv_prev="$(export -p | grep -v -e '=""$' -e "=''\$")"
-set -a
-. <(grep -E '^(ANTHROPIC|OPENAI)_(CUSTOM_HEADERS|API_KEY|BASE_URL)=' "$REPO_ROOT/.env")
-set +a
-eval "$_dotenv_prev"
-unset _dotenv_prev
+INSTALL_SH="${REPO_ROOT}/hyperloom/inference_optimizer/assets/install.sh"
+if [ ! -f "$INSTALL_SH" ]; then
+  INSTALL_SH="${REPO_ROOT}/src/hyperloom/inference_optimizer/assets/install.sh"
+fi
+. "${INSTALL_SH%/*}/runtime_env.sh"
+load_dotenv_no_clobber
 ```
 
 **Sessions.** `USER_DATA_PATH` sets the session root, and each `optimize`

docs/how-to/optimize.md

@@ -45,7 +45,7 @@ Before launch, run exactly:
 export REPO_ROOT="$(pwd -P)"
 export USER_DATA_PATH='/path/to/hyperloom-run'
 bash "$REPO_ROOT/hyperloom/inference_optimizer/assets/install.sh"
-source "$USER_DATA_PATH/runtime/kernel-agent.env.sh"
+# The optimizer preflight loads the generated runtime environment in process.
 
 Requirements:
 1. Report the session ID, log path, PID, and initial health check result.

docs/reference/environment-variables.md

@@ -195,7 +195,7 @@ The following variables control the kernel optimization backend ladder.
 
 | Variable                       | Default                       | Description                                                                                                                                                                                       |
 |--------------------------------|-------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| `KERNEL_OPT_BACKEND_ORDER`     | Unset (resolves to `geak`)    | Selects the kernel-opt backend. Unset resolves to `geak` (whole-pipeline GEAK owns the KERNEL phase); the bare-metal installer and the Slurm launchers export `${KERNEL_OPT_BACKEND_ORDER:-geak}` on top of that. **Only an exact, case-insensitive `forge` opts into the per-kernel forge backend** (`forge_explicitly_enabled` in `common/env.py`). Despite the historical name, a comma list is not parsed: `forge,geak` silently stays on `geak`, as does any other value, legacy alias, or payload override. |
+| `KERNEL_OPT_BACKEND_ORDER`     | Unset (`forge` for ATOM; otherwise `geak`) | Selects the kernel-opt backend. At launch, the CLI defaults an unset or blank value to `forge` for `--framework atom` when kernel optimization is enabled; SGLang/vLLM retain `geak`. Bare-metal setup preserves nonempty choices (process env > `.env`) without filling or persisting a backend default. Existing `.env` values, including `geak`, are not automatically migrated; remove that assignment and unset the shell variable to use the framework default. Slurm launchers still export `${KERNEL_OPT_BACKEND_ORDER:-geak}`. **Only an exact, case-insensitive `forge` enables the per-kernel Forge backend** (`forge_explicitly_enabled` in `common/env.py`). Despite the historical name, a comma list is not parsed: `forge,geak` stays on `geak`, as does any other nonblank value, legacy alias, or payload override. |
 | `KERNEL_OPT_MAX_PARALLEL`      | `8` (GPU-adaptive cap)        | Max parallel kernel-opt attempts per request (per-kernel race fan-out). The runtime caps this by visible GPUs and per-attempt GPU reservation when it can detect them.                                                                                                                            |
 | `HYPERLOOM_GEMM_SHAPE_CAPTURE` | `1`                           | Enables automatic runtime GEMM-shape capture for eligible single-node dense vLLM Forge tuning when no explicit shape input is available. Block-FP8 first reuses shapes from the TraceLens-selected steady-state trace of a successful Roofline with exactly matching model, workload, server arguments, environment, and backend controls. Missing or stale evidence triggers the same standard Roofline/ProfileExecutor/TraceLens steady-state pipeline as a fallback. Set to `0` to preserve the no-capture path. |
 | `HYPERLOOM_GEMM_SHAPE_CAPTURE_TIMEOUT_SEC` | `1800`          | Timeout in seconds for the dense vLLM TunableOp recording benchmark. Block-FP8 fallback uses the standard Roofline/ProfileExecutor timeout. Values below `60` are clamped to `60`. |

docs/reference/kernel-execution-path.md

@@ -72,7 +72,7 @@ fusion, the rewrite controller, GEAK and its revalidation) is covered by those
 lanes. Which calls it makes depends on the backend:
 
 ```python
-# 1. GEAK branch — the documented default. One whole-pipeline e2e run, then
+# 1. GEAK branch — the SGLang/vLLM default. One whole-pipeline e2e run, then
 #    the phase winds down to SWEEP. Nothing below this line executes.
 if geak_enabled:                      # geak_selected(): order is not exactly `forge`
     await self._run_geak_kernel_phase(from_phase=from_phase)
@@ -151,23 +151,33 @@ The seven rules from the retired `kernel_agent.md` live in executable Python:
 
 ## Backend selection
 
-GEAK owns the KERNEL phase by default and decides kernel strategy internally.
-The per-kernel Forge backend is an opt-in:
-
-- **Default**: `geak`. It is the code default whenever
-  `KERNEL_OPT_BACKEND_ORDER` is unset (`_DEFAULT_KERNEL_PHASE_BACKEND_ORDER` in
-  `orchestrator/kernel/request_handlers.py`), so no launcher has to set it. The
-  bare-metal installer additionally exports `${KERNEL_OPT_BACKEND_ORDER:-geak}`
-  and persists it into `.env`, and the Slurm launchers export the same
-  `:-geak` fallback into the job / container environment. `.env.template`
-  ships the line commented out.
-- **Forge (per-kernel)**: set `KERNEL_OPT_BACKEND_ORDER=forge` exactly. Any
-  other value (including `--backends` CLI flags, payload `backends` hints, or
-  `GEMM_TUNING_BACKEND`) doesn't enable Forge.
-
-Under the default `geak` backend the KERNEL-entry GEMM tuning never fires,
-because `_run_kernel_agent` hands the phase to `_run_geak_kernel_phase` and
-returns before reaching it.
+GEAK owns the KERNEL phase by default for SGLang/vLLM and decides kernel
+strategy internally. ATOM defaults to the per-kernel Forge backend at CLI launch:
+
+- **Framework default**: with `--framework atom` and kernel optimization
+  enabled, the CLI fills an unset or blank `KERNEL_OPT_BACKEND_ORDER` with
+  `forge`. Other frameworks retain the handler's `geak` default
+  (`_DEFAULT_KERNEL_PHASE_BACKEND_ORDER` in
+  `orchestrator/kernel/request_handlers.py`).
+- **Bare-metal setup**: preserves nonempty choices with process env > `.env`
+  precedence, but does not fill or persist a backend default. Existing `.env`
+  assignments, including `KERNEL_OPT_BACKEND_ORDER=geak`, are not automatically
+  migrated. To use the framework default, remove that assignment and unset the
+  shell variable. `.env.template` ships the line commented out.
+- **Slurm launchers**: still export `${KERNEL_OPT_BACKEND_ORDER:-geak}` into
+  the job / container environment; their behavior is unchanged.
+- **Explicit selection**: only an exact, case-insensitive `forge` enables
+  per-kernel Forge. Other nonblank values, including `forge,geak`, retain GEAK;
+  `--backends` CLI flags, payload `backends` hints, and `GEMM_TUNING_BACKEND`
+  do not override this choice.
+
+`run_gemm_tuning_handler` also defaults to GEAK unless the effective
+`KERNEL_OPT_BACKEND_ORDER` is `forge`, whether selected explicitly or by the
+ATOM CLI default. That default applies to an LLM-issued `run_gemm_tuning`
+REQUEST, which is dispatched inline whatever the backend. The KERNEL-**entry**
+GEMM tuning is a different matter: under `geak` it never fires at all, because
+`_run_kernel_agent` hands the phase to `_run_geak_kernel_phase` and returns
+before reaching it.
 
 FlyDSL kernels (`source_type=flydsl`) are handled by Forge when it is enabled.
 
@@ -201,11 +211,12 @@ export REPO_ROOT="$(pwd -P)"    # workspace holding the hyperloom package
 # CLI picks /workspace/hyperloom when writable and session/ under $PWD otherwise.
 export USER_DATA_PATH="${USER_DATA_PATH:-$REPO_ROOT/session}"
 bash "$REPO_ROOT/hyperloom/agents/kernel/scripts/install.sh"
-source "$USER_DATA_PATH/runtime/kernel-agent.env.sh"
 ```
 
 `install.sh` is idempotent. It sets up TraceLens, GEAK, Ray, and writes the
-env file. Re-run it after a venv rebuild or before each session.
+env file. Optimizer preflight loads that file in process; do not source it over
+the launching shell's selections. Re-run installation after a venv rebuild or
+when the prepared runtime is no longer valid.
 
 Required env vars:
 
@@ -214,7 +225,7 @@ Required env vars:
 | `ANTHROPIC_API_KEY` | operator | Anthropic-side key; GEAK and TraceLens both run Claude Code |
 | `ANTHROPIC_BASE_URL` | operator | Anthropic-side endpoint (point it at your gateway) |
 | `TRACELENS_ROOT` | `install.sh` (operator can override) | TraceLens checkout; installer clones to `.cache/TraceLens` by default |
-| `KERNEL_OPT_BACKEND_ORDER` | code default `geak` when unset; bare-metal installer and Slurm launchers export `${KERNEL_OPT_BACKEND_ORDER:-geak}` | Set to exactly `forge` to enable per-kernel Forge |
+| `KERNEL_OPT_BACKEND_ORDER` | CLI defaults unset/blank to `forge` for ATOM with kernel optimization enabled; otherwise code defaults to `geak`. Bare-metal setup only persists nonempty choices; Slurm launchers still export `${KERNEL_OPT_BACKEND_ORDER:-geak}` | Exact, case-insensitive `forge` enables per-kernel Forge; existing `.env` choices are retained |
 
 Forge needs **no path variable**. It ships inside the Hyperloom wheel, so the
 `FORGE_PATH` that used to be required here is removed and nothing reads it. The

docs/reference/troubleshooting.md

@@ -60,22 +60,22 @@ See [Hyperloom authentication and credentials](authentication.md) for credential
 credentials. `tr '\0' '\n' < /proc/<pid>/environ | grep ANTHROPIC_API_KEY` on the
 running optimizer shows the previous key.
 
-**Cause**: `install.sh` snapshots the resolved credentials into
-`$USER_DATA_PATH/runtime/kernel-agent.env.sh`, and every launch sources `.env`
-first and that file second. The snapshot is a fallback, so the rotated value
-wins — but only if it is in the environment when the file is sourced. Sourcing
-the file in a shell that never loaded the new `.env` still yields the old key.
+**Cause**: `install.sh` snapshots credentials into
+`$USER_DATA_PATH/runtime/kernel-agent.env.sh`. Optimizer preflight loads the
+workspace settings before this fallback, preserving caller exports. An old key
+still exported by the launching shell therefore wins over a rotated `.env` value.
 
 **Fix**:
 
-1. Source `.env` before `kernel-agent.env.sh`, which is the documented launch
-   order:
+1. Reconcile any stale credential export, then use the shared workspace loader:
    ```bash
-   set -a; . "$REPO_ROOT/.env"; set +a
-   . "$USER_DATA_PATH/runtime/kernel-agent.env.sh"
+   INSTALL_SH="$REPO_ROOT/hyperloom/inference_optimizer/assets/install.sh"
+   [ -f "$INSTALL_SH" ] || INSTALL_SH="$REPO_ROOT/src/hyperloom/inference_optimizer/assets/install.sh"
+   . "${INSTALL_SH%/*}/runtime_env.sh"
+   load_dotenv_no_clobber
    ```
-   The file prints `ANTHROPIC_API_KEY differs from the install-time snapshot` on
-   a mismatch; that line means the rotated value is the one in effect.
+   Do not print credential values. Let optimizer preflight load the runtime
+   snapshot; do not source it over the current launch environment.
 2. To refresh the snapshot itself, re-run the installer:
    ```bash
    bash "$REPO_ROOT/hyperloom/inference_optimizer/assets/install.sh"

examples/README.md

@@ -178,9 +178,15 @@ run:
 - [`12h`](hyperloom-qwen3-14b-fp8-12h/SKILL.md) — Qwen3-14B-FP8, medium-length FP8 run.
 - [`12h forge`](hyperloom-qwen3-14b-fp8-12h-forge/SKILL.md) — the same run on the
   KernelForge kernel backend.
-- [`12h atom`](hyperloom-qwen3-14b-fp8-12h-atom/SKILL.md) — the same run on the
-  ATOM serving framework; pins the KernelForge backend, because GEAK does not
-  drive kernel rewrites on ATOM.
+- [`12h atom`](hyperloom-qwen3-14b-fp8-12h-atom/SKILL.md) — the same run on ATOM,
+  using the user's selected `docker` or `baremetal` mode from setup; if no mode is
+  selected, ask before continuing. `baremetal` uses the development machine's
+  existing ATOM/ROCm Python environment, even if that platform is a container
+  (no additional Docker). Setup uses `--install-framework none
+  --frameworks atom --require-frameworks`, first with `--check-only` and then
+  with approval if setup is needed. The CLI defaults to KernelForge when no
+  backend is selected; explicit choices are preserved, with a warning and
+  confirmation for GEAK's unproven ATOM rewrite-seam path.
 - [`custom advanced`](hyperloom-custom-advanced/SKILL.md) — user-selected model,
   framework, TP/EP, concurrency, ISL/OSL, precision, budget, phase toggles, and
   advanced CLI flags.