bug: `gateway select` silently succeeds when OPENSHELL_GATEWAY env var overrides selection

[johntmyers]

Agent Diagnostic

During a cluster debugging session, all gateway metadata was removed and a fresh gateway was registered as docker-dev. Running openshell gateway select docker-dev printed a green checkmark, but every subsequent command (openshell status, openshell sandbox create) reported "No gateway configured" or "No gateway metadata found for 'openshell'".

Root cause: OPENSHELL_GATEWAY=openshell was set in the shell environment. The env var takes precedence over the persisted selection, so select wrote to disk but the value was never read back. The CLI arg is defined as:

-g, --gateway <GATEWAY>  [env: OPENSHELL_GATEWAY=openshell]

Discovered by inspecting echo $OPENSHELL_GATEWAY after select appeared to succeed.

Description

Actual behavior: openshell gateway select <name> succeeds with a green checkmark even when OPENSHELL_GATEWAY is set to a different value. All subsequent commands ignore the selection and resolve the gateway from the env var instead.

Expected behavior: gateway select should detect when OPENSHELL_GATEWAY is set and either:

• Warn that the env var will override the selection, e.g.:

  ⚠ OPENSHELL_GATEWAY=openshell is set and will override this selection.
    Unset it or run: export OPENSHELL_GATEWAY=<name>
  

• Or refuse to proceed and explain why.

Reproduction Steps

1. export OPENSHELL_GATEWAY=openshell
2. openshell gateway add http://127.0.0.1:18080 --name docker-dev
3. openshell gateway select docker-dev — prints success
4. openshell status — reports "No gateway configured" (resolves openshell, not docker-dev)

Environment

• OS: macOS (darwin)
• OpenShell: 0.0.37-dev

[sjenning]

I hit this as well! I thought I was going crazy.

[johntmyers]

🏗️ build-plan

Implementation Plan

Issue type: fix
Complexity: Low
Confidence: High — clear path

Summary

Add an explicit warning when openshell gateway select <name> persists a gateway while OPENSHELL_GATEWAY is set to a different name. The command should still succeed: selecting a persisted default is valid even when the current shell has an override, and a warning avoids breaking scripts or workflows that intentionally update the stored default for later use.

Scope

• crates/openshell-cli/src/run.rs: after gateway_use() saves the selected gateway, detect a non-empty OPENSHELL_GATEWAY value that differs from the selected name and print a warning explaining that the env var overrides the persisted selection.
• crates/openshell-cli/src/run.rs: add focused unit coverage around the override-warning decision, including different-name warning and same-name no-op behavior.
• docs/sandboxes/manage-gateways.mdx: document that OPENSHELL_GATEWAY overrides the active gateway and that gateway select warns when the current env var masks the newly selected default.

Implementation Steps

1. Add a small helper in the CLI gateway-selection path that returns override warning text only when OPENSHELL_GATEWAY is set, non-empty, and different from the selected gateway.
2. Call the helper from gateway_use() after save_active_gateway(name)?, keeping the existing success exit status and success message.
3. Add unit tests in the existing crates/openshell-cli/src/run.rs test module using the existing EnvVarGuard and temp XDG helpers.
4. Update gateway management docs with the precedence note and the warning behavior.

Test Plan

• Unit tests: add tests in crates/openshell-cli/src/run.rs for warning generation when OPENSHELL_GATEWAY=openshell and selected gateway is docker-dev, plus no warning when the env value matches the selected gateway.
• Integration tests: N/A — this is isolated CLI output/selection behavior and the unit path exercises the decision logic without requiring a real gateway.
• E2E tests: N/A — no gateway, sandbox runtime, or deployment behavior changes.
• Verification: run mise run pre-commit after implementation.

Risks & Open Questions

• Warning-only is recommended over a hard stop because the selection was persisted successfully; the problem is current-session precedence. Hard-stopping would make it harder to update the stored default while an env override is intentionally set.
• The warning should not trigger when OPENSHELL_GATEWAY already matches the selected gateway, because subsequent commands resolve to the same target.
• If maintainers want stricter behavior later, a separate explicit --force/--ignore-env design would be better than changing this bug fix into a breaking stop.

Documentation Impact

• Update docs/sandboxes/manage-gateways.mdx to make the precedence and warning visible in the user-facing gateway workflow.
• No architecture document change is expected because the resolution order is already documented in architecture/README.md.

---

Revision 1 — initial plan; recommends warning-only behavior instead of a hard stop

[johntmyers]

🏗️ build-from-issue-agent

Implementation Complete

PR: #1219

What was built

openshell gateway select <name> now warns when OPENSHELL_GATEWAY is set to a different gateway and will override the persisted active selection. The command remains warning-only and still saves the selected gateway.

Tests

• Unit: 2 tests added
• Integration: N/A
• E2E: N/A — no e2e/ changes

Docs updated

• docs/sandboxes/manage-gateways.mdx: documents active gateway precedence and the env override warning.

The issue will auto-close when the PR is merged.