fix(auth): honor NOUS_INFERENCE_BASE_URL env override for Nous OAuth sessions

[benbarclay]

Summary

The NOUS_INFERENCE_BASE_URL dev/staging escape hatch is unreachable for OAuth (Nous Portal login) sessions, even though three separate code comments assert it still works. A user pointing Hermes at staging via the env var silently gets production (or 401s against a dead endpoint). This restores the documented behavior.

Root cause

The host-allowlist hardening (#30611) plus the refresh heal (#49735) interact with the resolution precedence in resolve_nous_runtime_credentials:

inference_base_url = (
    _optional_base_url(state.get("inference_base_url"))   # stored — wins
    or os.getenv("NOUS_INFERENCE_BASE_URL")               # env — never reached
    or DEFAULT_NOUS_INFERENCE_URL
)

A staging OAuth login persists its inference_base_url, but:

1. the allowlist (#30611) rejects the staging host, and
2. the refresh heal (#49735) rewrites the stored value to the production default.

The stored (now prod) value is read before the env var, so the override never takes effect. The comments in #30611/#49735 claim the env path is the trusted escape hatch — but precedence makes it dead for any already-authenticated OAuth session.

Fix

The user-set env override is the most-trusted source, so consult it first for the URL used to build the client / returned to callers — while keeping the persisted value the validated, network-provenance one. The override is a runtime overlay: it is never written to auth.json, so unsetting it cleanly reverts to the stored/default production URL (threat model intact).

Applied at both chokepoints (this is the whole bug class, not just the one site):

• resolve_nous_runtime_credentials — both the no-refresh read path and the refresh path. Persistence keeps the validated network value; the returned/client URL is env-first.
• hermes_cli/proxy/adapters/nous_portal.py — the proxy adapter re-validates the resolver's returned base_url against the prod allowlist as defense-in-depth, and would otherwise reject a legitimate staging override at the forward boundary. Same env-first overlay applied; the validator stays in place.

New _nous_inference_env_override() helper centralizes the (deliberately ungated) env read. Portal-returned URLs are still allowlist-validated at every network site.

Relationship to open PRs

• Supersedes fix(auth): heal poisoned stored Nous inference URL on the no-refresh read path #50265 (no-refresh read-path heal) — this PR folds in that heal and fixes the env-override precedence fix(auth): heal poisoned stored Nous inference URL on the no-refresh read path #50265 leaves unaddressed (it heals to the prod default, not the env var).
• Unrelated to fix(auth): validate portal_base_url and migrate stale api.nousresearch.com (#44710) #50274 (portal_base_url allowlist). ⚠️ Heads-up: if fix(auth): validate portal_base_url and migrate stale api.nousresearch.com (#44710) #50274 lands as-is, portal_base_url will inherit the same heal-to-prod + env-shadowing behavior this PR fixes for inference. Worth applying the same overlay there.

Audit of sibling env vars (requested)

Env var	Verdict
NOUS_INFERENCE_BASE_URL	Was broken — fixed here.
HERMES_PORTAL_BASE_URL	Honored at login (env-first). Stored-first at runtime-refresh, but that's intentional — a runtime portal override must match the token issuer (see _resolve_portal_base_url docstring), so overriding mid-session would break auth. Not a bug.
TOOL_GATEWAY_DOMAIN	Read directly via os.getenv, no stored value, always honored. No shadowing bug. (Separate UX gap: not derived from the portal URL — out of scope.)
HERMES_DASHBOARD_PORTAL_URL	Override-first (_resolve_portal_base_url). Correct — the model this fix follows.

Tests

• TestEnvOverrideWins — env wins over a prod-pinned stored value on both the no-refresh and refresh paths; override never persisted to state; poisoned stored host still heals when no env is set.
• TestProxyAdapterEnvOverride — forward-boundary consults the override before the validator.
• Verified the 4 behavioral tests fail against pre-fix code and pass with the fix.
• Full test_nous_inference_url_validation.py + test_auth_nous_provider.py: 85 passed. (One existing idempotency fixture used a non-allowlisted host incidentally; updated it to a realistic allowlisted host so the new read-path heal doesn't trip its "no write on unchanged" assertion.)
• E2E against a real temp HERMES_HOME exercising the real resolver + real proxy adapter: resolver→staging, persisted→prod, proxy→staging, unset→reverts to prod.

How to test

pytest tests/hermes_cli/test_nous_inference_url_validation.py -v
# Manual: log into Nous (prod), then
NOUS_INFERENCE_BASE_URL=https://stg-inference-api.nousresearch.com/v1 hermes status
# inference URL should now reflect staging; auth.json keeps the prod host.

Type of Change

• 🐛 Bug fix (non-breaking)
• ✅ Tests

[github-actions]

🔎 Lint report: fix/nous-inference-env-override vs origin/main

ruff

Total: 0 on HEAD, 0 on base (➖ 0)

🆕 New issues: none

✅ Fixed issues: none

Unchanged: 0 pre-existing issues carried over.

ty (type checker)

Total: 11258 on HEAD, 11260 on base (✅ -2)

🆕 New issues (1):

Rule	Count
invalid-assignment	1

First entries

tests/run_agent/test_credits_notices_toggle.py:76: [invalid-assignment] invalid-assignment: Object of type `None` is not assignable to attribute `_credits_session_start_micros` of type `int`

✅ Fixed issues (2):

Rule	Count
unresolved-attribute	2

First entries

tests/run_agent/test_credits_notices_toggle.py:76: [unresolved-attribute] unresolved-attribute: Unresolved attribute `_credits_session_start_micros` on type `AIAgent`
run_agent.py:2984: [unresolved-attribute] unresolved-attribute: Object of type `Self@get_credits_spent_micros` has no attribute `_credits_session_start_micros`

Unchanged: 5939 pre-existing issues carried over.

Diagnostics are surfaced as warnings — this check never fails the build.