Fix gaia init for remote Lemonade Server

[itomek-amd]

Summary

Fixes #311

When LEMONADE_BASE_URL points to a remote Lemonade server (e.g., Docker container without local Lemonade CLI), gaia init previously failed trying to install the local lemonade-server binary. This PR fixes that by:

• Auto-detecting remote mode from LEMONADE_BASE_URL when it points to a non-localhost host
• Delegating model downloads to LemonadeClient.ensure_model_downloaded() instead of shelling out to the local CLI or reimplementing streaming pull logic
• Removing ~165 lines of subprocess calls, CLI fallback routing, retry-on-corruption logic, and the separate _pull_models_via_api() method — all replaced by the existing client method that works for both local and remote servers

Bonus fix: _ctx_warning displayed "None" during verification

Why: During Step 4 model verification, the output showed ✓ Qwen3-0.6B-GGUF - OK None instead of ✓ Qwen3-0.6B-GGUF - OK (ctx: 4096).

Before: self._ctx_warning was initialized to None in __init__() (line 197). The display code used hasattr(self, "_ctx_warning") to check whether a warning existed — but since the attribute was always set (to None), hasattr always returned True. The f-string then rendered None as the literal string "None" inside the Rich markup.

# Before — hasattr is always True because __init__ sets it to None
if hasattr(self, "_ctx_warning"):
    ctx_msg = f" [yellow]{self._ctx_warning}[/yellow]"  # → " [yellow]None[/yellow]"
    delattr(self, "_ctx_warning")

After: Check the value's truthiness instead of attribute existence:

# After — only renders when _ctx_warning has an actual message
if self._ctx_warning:
    ctx_msg = f" [yellow]{self._ctx_warning}[/yellow]"
    self._ctx_warning = None

Justification: The hasattr check was the wrong guard here because _ctx_warning is always defined on the instance. The attribute is only populated with a real string when actual_ctx > min_ctx (context is larger than required). When context matches exactly (the common case), it stays None, and truthiness correctly skips the warning display.

Before

Step 3/4: Downloading models for 'minimal' profile...
   [runs subprocess: lemonade-server pull Qwen3-0.6B-GGUF]
   [retries on corruption, falls back to API if CLI missing]
Step 4/4: Verifying setup...
   ✓  Qwen3-0.6B-GGUF - OK None

After

Step 3/4: Downloading models for 'minimal' profile...
   Downloading: Qwen3-0.6B-GGUF
   ✓ Downloaded Qwen3-0.6B-GGUF
Step 4/4: Verifying setup...
   ✓  Qwen3-0.6B-GGUF - OK (ctx: 4096)

Test plan

• Unit tests pass (pytest tests/unit/test_init_command.py — 42/42 passed)
• Full unit test suite passes (pytest tests/unit/ — 417 passed, 13 skipped)
• Lint passes (python util/lint.py --all)
• E2E: LEMONADE_BASE_URL=https://itomek-gaia.ngrok.app/api/v1 gaia init --profile minimal --yes — all 4 steps complete, context displays correctly

[kovtcharov]

@claude review this PR for any issues.

[github-actions]

Claude finished @kovtcharov's task —— View job

---

Reviewing PR #345

• Read the PR diff and changed files
• Analyze code changes in src/gaia/installer/init_command.py
• Review test changes in tests/unit/test_init_command.py
• Review documentation changes in docs/reference/cli.mdx
• Provide comprehensive code review feedback

---

Code Review Summary

This PR is well-structured and addresses the issue appropriately. The changes significantly simplify the codebase by delegating model downloads to LemonadeClient.ensure_model_downloaded() instead of maintaining complex subprocess logic with retry-on-corruption handling.

🟢 Strengths

1. Significant code reduction (~165 lines removed) by delegating to LemonadeClient.ensure_model_downloaded() which already handles local and remote scenarios

2. Smart auto-detection of remote mode from LEMONADE_BASE_URL (init_command.py:160-171) - parses the URL and detects non-localhost hostnames

3. Bug fix for _ctx_warning (init_command.py:1327) - correctly uses truthiness check instead of hasattr() which was always true

4. Comprehensive test coverage - 5 new test classes covering:

   • Remote URL detection (TestRemoteAutoDetection)
   • Model download delegation (TestDownloadModels)
   • Edge cases (localhost, 127.0.0.1, ::1, explicit flag override)

5. Documentation improvements - Clear tabs for Local vs Remote mode in docs/reference/cli.mdx

🟡 Minor Observations

1. init_command.py:1321-1334 - The hasattr(self, "_ctx_verified") check on line 1321 has the same potential issue that was fixed for _ctx_warning. Both attributes are initialized to None in __init__() (lines 196-197), so hasattr() will always return True. However, the logic here is slightly different since it explicitly checks truthiness on line 1322 (if self._ctx_verified:), so this works correctly. Consider making the pattern consistent by removing the outer hasattr() check entirely:

   # Current (works but hasattr is redundant):
   if hasattr(self, "_ctx_verified"):
       if self._ctx_verified:
           ...
   
   # Could simplify to:
   if self._ctx_verified:
       ...

2. IPv6 localhost detection - The code correctly handles ::1 but doesn't handle other IPv6 loopback representations like [::1] with brackets. This is a very minor edge case unlikely to occur in practice.

3. _find_lemonade_server() is now unused in remote mode - The method at init_command.py:725-785 is still used for local mode server startup, but might be worth noting in a comment that it's only relevant for local mode.

🟢 Test Quality

The new tests are well-structured and properly mock dependencies:

• Uses @patch.dict("os.environ", ...) for environment variable testing
• Tests both positive and negative cases for URL parsing
• Validates that ensure_model_downloaded() is called for both local and remote modes
• Tests --force-models flow with delete + re-download

Verdict

LGTM - This is a clean refactor that improves maintainability while fixing the reported issue. The minor observations above are non-blocking and can be addressed in future iterations if desired.

---