Bug: Complete embedded LLM lifecycle results and readiness checks #135

Summary

A mocked successful LlamaServerSupervisor.stop() returned None, despite its dictionary return annotation. main.py:152 automatically starts the first available local model at backend startup. The runtime uses a fixed port and starts without awaiting service readiness; local-provider configuration can appear ready before installation/health is established.

Environment and evidence

• Review finding: F35 (2026-10-05 product/technical review).
• Baseline: Windows, dev at c1c5dbe. The remote dev matched this commit when filing.
• Evidence: Reproduced + Code.
• Priority recommendation: P2 - material improvement or integration validation. This is review triage, not a production-incident severity declaration.
• No real credentials, paid inference, engine installation, or unrelated process termination were used for review probes. Mocked observations establish the stated code behavior, not live-provider/GPU acceptance.

Reproduction or validation

Mock LlamaServerSupervisor.get_pid, subprocess.run, and PID cleanup, then call stop: successful termination returns None despite its dictionary annotation. No real process was terminated. Source review also found automatic startup of the first local model, fixed-port use, and no awaited readiness before reporting start success.

User impact

Stop callers cannot rely on a result, startup can unexpectedly consume resources, and the Agent can appear available while its service is unavailable.

Proposed approach

Return explicit lifecycle results, honor a saved opt-in/start preference, select a known model, check port ownership, and report health separately from installation and PID state.

Acceptance criteria

• All start/stop paths return explicit structured results.
• Local startup follows a saved opt-in preference and selected model.
• Check port ownership and service readiness independently of PID existence.
• Provider configuration is not presented as readiness when runtime/model is missing.
• Tests cover absent/starting/healthy/failed services and successful stop.

Additional source references

• backend/app/runtime/llama_server/llama_supervisor.py:263

Related work

Related closed issue: #96. Embedded llama-server was implemented. This report concerns remaining lifecycle result and readiness contracts.

Verification scope

Real GPU inference, paid-provider compatibility, and a clean-machine packaged desktop journey remain unverified. Any follow-up implementation should target dev under the repository's contribution/branching rules.