The core logic is correct and the fail-loudly approach is rigorously followed — NPU requests on CPU-only hosts now raise actionable errors with concrete remedies, and the long-standing B1 silent no-op is fixed end-to-end. Four items are worth addressing before merge, one of which is a real bug.

Issues

🟡 Bug: min_context_size falsy check rejects 0 (src/gaia/agents/chat/agent.py:366)

The guard if config.min_context_size else 32768 treats 0 as absent. Optional[int] fields should use is not None:

                config.min_context_size if config.min_context_size is not None else 32768

min_context_size=0 is never a valid real-world value, so this won't bite today, but the pattern is incorrect and will confuse the next reader who adds a device with an unusual ctx size.

🟡 DRY: multi-device resolution block is copy-pasted verbatim (src/gaia/ui/_chat_helpers.py:1108 and :1495)

The 14-line "Multi-device: the selected device dictates the model + ctx" block — including the nearly identical comment — is duplicated between _get_chat_response and _stream_chat_response. The only difference is the log message suffix "(streaming)". Extract to a helper:

def _apply_device_model(
    session: dict,
    agent_type: str,
    model_id: str | None,
    custom_model: str | None,
    registry=None,
    streaming: bool = False,
) -> tuple[str | None, int | None]:
    """Return (model_id, device_ctx) adjusted for the session's device."""
    device = session.get("device")
    if custom_model or not device:
        return model_id, None
    dev_model, dev_ctx = _resolve_device_model(agent_type, device, registry)
    if not dev_model:
        return model_id, None
    is_default_model = model_id in (None, _DB_DEFAULT_MODEL)
    device_is_explicit = device != "gpu"
    if dev_model == model_id or is_default_model or device_is_explicit:
        if dev_model != model_id:
            suffix = " (streaming)" if streaming else ""
            logger.info("chat: device=%s -> model %s (was %s)%s", device, dev_model, model_id, suffix)
        return dev_model, dev_ctx
    return model_id, None

Then both call sites collapse to one line each. The duplication isn't a bug now, but it's a divergence risk: the next change to the guard condition has to be made in two places.

🟡 Private function imported across module boundary (src/gaia/ui/routers/sessions.py:14)

_resolve_device_model is prefixed with _ (module-private by convention) but is imported in sessions.py. Either rename it resolve_device_model to signal it's part of the semi-public _chat_helpers interface, or move it to a shared _device_utils.py module. The current import is not wrong — Python doesn't enforce underscore privacy — but it breaks the "caller doesn't touch private helpers" convention and will confuse grep or auto-refactoring tools.

🟢 Fragile string heuristic for "server not reachable" (src/gaia/cli.py:657–660)

The _unreachable classification relies on two implementation-specific strings from lemonade_client.py:

_unreachable = (
    _probe_msg.startswith("Request failed:")
    and "with status" not in _probe_msg
)

This works today because lemonade_client.py:2498 uses "Request failed: {str(e)}" for RequestException and lemonade_client.py:3820 uses "Request failed with status {code}" for HTTP errors. But both strings can change independently of this guard, and any future LemonadeClientError subclass that formats its message differently could silently swallow an important error.

A more stable approach: check the exception type chain. requests.exceptions.ConnectionError and requests.exceptions.Timeout are what "server not reachable" looks like; they're wrapped by LemonadeClientError but the original exception is preserved in __cause__/__context__. Alternatively, add an is_connection_error: bool attribute to LemonadeClientError at the raise site and check that here. No suggestion block because this is an architectural decision — flagging for maintainer awareness.

🟢 Over-long comment block in ChatAgentConfig (src/gaia/agents/chat/agent.py:58–62)

CLAUDE.md calls for one short WHY comment per field, not a 5-line block covering both fields. The NPU 4K ctx constraint is the genuinely non-obvious part; the rest is derivable from the field name:

    # NPU FLM build requires 4K ctx; device is validated loudly at startup.
    device: Optional[str] = None
    min_context_size: Optional[int] = None

Strengths

• Fail-loudly throughout: every path that accepted except Exception: pass is now narrowed — H1 is properly scoped to genuine "server not running yet" cases, and B2 raises HardwareRequirementError with a named remedy and a gaia init call-to-action.
• _DEVICE_TO_MIN fix is clean: mapping "gpu" → "amd_dgpu" (the lowest GPU tier) correctly accepts either integrated or discrete Radeon without changing the existing _DEVICE_PRIORITY ordering. The added dgpu_only.json fixture pins the regression.
• Test suite is thorough and well-structured: TestDeviceModelOverride covers the four non-trivial guard conditions (NPU overrides default, NPU overrides pinned, GPU preserves pinned, custom_model beats device), and TestGpuSelectorAcceptsBothGpuTiers gives the dgpu fix its own dedicated class with the pre-fix behaviour described in context.
• Installer path fix is correct: both scripts had $SCRIPT_DIR/.. but the scripts live in installer/scripts/, so ../.. is the right root.

Verdict

Approve with suggestions. The is not None bug is the only issue that can cause wrong behaviour (though it requires min_context_size=0, which no current device config uses). The DRY violation and private-function import are the most likely sources of future maintenance pain. Everything else is correctly implemented and the test coverage is solid.

Reminder (from PR description): NPU quality eval must be run by a maintainer on Ryzen AI hardware before the tag. gaia eval agent --device npu --category context_retention,rag_quality.

Four real release-blocker bugs fixed cleanly, with 347 lines of new tests that pin the behaviour before and after. The core logic is correct throughout — no blocking issues, two things worth addressing before the next PR touches this code.

Summary

This delivers on all four v0.20.0 blockers: _DEVICE_TO_MIN["gpu"] now maps to amd_dgpu instead of amd_igpu so a dGPU-only host isn't rejected; device validation runs on every ensure_ready call (memoised per tier, so the cost is one probe per distinct device per process); ChatAgentConfig carries device and threads it base Agent → LemonadeManager; and the CLI's blanket except Exception: pass is narrowed to treat only genuine connection failures as soft. Actionable error messages name the device, the remedy, and the next step — exactly the fail-loudly pattern CLAUDE.md requires.

Issues

🟡 Duplicate multi-device resolution block (_chat_helpers.py:1108–1136, 1509–1521)

The same ~26-line block appears verbatim in _get_chat_response and _stream_chat_response, differing only in one log suffix "(streaming)". If either path needs a bug fix it must be applied twice, and they've already drifted on that log string. Extract to a helper:

def _apply_device_model(
    session: dict,
    agent_type: str,
    registry,
    custom_model: str | None,
    model_id: str | None,
) -> tuple[str | None, int | None]:
    """Return (model_id, ctx_size) after applying the session device override."""
    if custom_model:
        return model_id, None
    device = session.get("device")
    dev_model, dev_ctx = _resolve_device_model(agent_type, device, registry)
    if not dev_model:
        return model_id, None
    is_default_model = model_id in (None, _DB_DEFAULT_MODEL)
    device_is_explicit = bool(device) and device != "gpu"
    if dev_model == model_id or is_default_model or device_is_explicit:
        if dev_model != model_id:
            logger.info("chat: device=%s -> model %s (was %s)", device, dev_model, model_id)
        return dev_model, dev_ctx
    return model_id, None

Then both call sites become two lines. The per-site device read can be a local before the call so the streaming log suffix can be dropped (it adds no value).

🟢 except Exception in _maybe_validate_device silently swallows programming errors (lemonade_manager.py:313–318)

The intent is to pass through when the server is unreachable — but except Exception also catches AttributeError (if get_system_info() returns a non-dict), ValueError, and any future bug introduced inside _validate_device_requirement. These will be logged at DEBUG and silently skipped, making them invisible in normal operation. The old code at least surfaced them as HardwareRequirementError. A minimum fix is to log at WARNING for anything that doesn't look like a connection error:

        except HardwareRequirementError:
            raise
        except Exception as e:
            # Only connection-level failures (refused / timeout) are soft here.
            # Unexpected errors get a WARNING so they're visible in logs.
            msg = str(e)
            is_conn = "refused" in msg or "timeout" in msg or "Request failed:" in msg
            level = cls._log.debug if is_conn else cls._log.warning
            level("Skipping device validation (%s): %s", "unreachable" if is_conn else "unexpected error", e)
            return

🟢 Issue/blocker references in docstrings will become stale

_resolve_device_model (_chat_helpers.py:473), _build_create_kwargs docstring (_chat_helpers.py:453), and the ChatAgentConfig comment block (chat/agent.py:71–76) all mention issue #1220, B1, release blocker B1. Per CLAUDE.md these belong in the PR description and commit message, not the code — they rot as soon as the issue is closed. One-line WHY comments are fine; internal ticket IDs and blocker labels are not.

🟢 Sessions router model-rewrite logic is untested at the HTTP layer

sessions.py:100–109 has non-trivial logic (guards on is_default_model, device_is_explicit, same-model no-op). The database-layer test in test_database.py covers db.update_session(model=...), but no test drives the PUT /api/sessions/{id} endpoint with device=npu and verifies the session's model field is rewritten. The FastAPI TestClient fixture in the existing test suite makes this straightforward to add in a follow-up.

🟢 CLI error-string matching is fragile (cli.py:629–133)

The _unreachable check parses LemonadeClientError message text with startswith("Request failed:") and "with status" not in _probe_msg. This works today but breaks silently if LemonadeClient's error-format changes. A LemonadeConnectionError subclass on the client side would let callers except LemonadeConnectionError without any string inspection. Worth raising as a follow-on issue.

Strengths

• _DEVICE_TO_MIN bug fix is correct — mapping gpu → amd_dgpu (index 2) with detected_idx <= req_idx means iGPU (index 1) and dGPU (index 2) both satisfy the requirement; CPU (index 3) does not. The logic is sound and the new fixture dgpu_only.json pins the regression.
• Memoisation is thread-safe and properly reset — _validated_min_devices is checked and mutated inside with cls._lock:, and reset() reinitialises it to set(). Hardware is static per process so the "at most one probe per tier" invariant holds.
• Test suite is comprehensive — test_multi_device_wiring.py (347 lines) covers device→tier mapping, both GPU tier satisfaction, unavailable device raises actionable errors, post-init validation, memoisation probe count, and the unreachable-server-≠-hardware-error distinction. The test_chat_helpers_model_resolution.py additions cover all four model-selection cases cleanly.
• Error messages are actionable — every HardwareRequirementError names the requested device, the detected hardware, and a concrete gaia init remedy. Matches CLAUDE.md's three-part fail-loudly requirement exactly.
• Installer path depth fixes are correct — ../.. is the right root from installer/scripts/, confirmed by existing tests that pass.

Verdict

Approve with suggestions. No blocking issues — the logic is correct and the four regressions are genuinely fixed. The duplicate device-resolution block (🟡) should be extracted before this area grows again; the other items are low-priority follow-ups. NPU quality eval on Ryzen AI hardware remains a mandatory pre-tag step per the PR description.

Thanks for the thorough reviews — addressed the actionable items in b18f197:

• min_context_size falsy bug → now uses is not None.
• Duplicated device-resolution block → extracted to _apply_device_model; both chat paths are one line and can't drift.
• _resolve_device_model private-name import → renamed to resolve_device_model (the sessions router imports it; matches the module convention where cross-module helpers drop the underscore).
• _maybe_validate_device swallowing programming errors → genuine connection/timeout stays DEBUG; anything else now logs WARNING so it stays visible.
• Fragile CLI error-string match → now prefers the preserved requests ConnectionError/Timeout in the exception cause chain, with the string check kept only as a fallback.
• Stale issue/blocker IDs in code → stripped from comments/docstrings (kept in the PR/commit history).
• Sessions router untested at HTTP layer → added TestSessionsRouterDeviceRewrite driving PUT /api/sessions/{id} (switch-to-NPU rewrites the model, GPU keeps default, title-only update leaves model untouched).

Deferred as a follow-on: a dedicated LemonadeConnectionError subclass on the client (cleaner than any cause-chain/string inspection) — worth its own issue since it touches every LemonadeClient raise site. The cause-chain check removes the immediate fragility in the meantime.

Lint passes; chat/ui suite green (675 passed) apart from two pre-existing failures unrelated to this change (a Windows-only read_text()/cp1252 quirk and an unrelated memory-reconcile test, both failing identically on main).

Multi-device wiring is correctly end-to-end and the core logic is sound — the B1/B2/H1 blockers are genuinely fixed. One behavioral inconsistency in the soft-error path is worth tightening before merge; everything else is minor.

Summary

The PR correctly threads device from the UI/CLI through ChatAgentConfig → base Agent → LemonadeManager.ensure_ready, validates hardware on every call (not just first init), and rewrites the session model on a device switch so the rebuilt agent loads the right model. The _DEVICE_TO_MIN promotion to module level and the amd_dgpu fix for the GPU tier make the behavior consistent with what a discrete-Radeon user would expect. Test coverage is thorough and the fixture-driven hardware simulation is a pattern worth replicating elsewhere.

The one issue worth addressing before tag: _maybe_validate_device soft-passes HTTP auth/5xx errors with only a WARNING, while cli.py correctly re-raises them. On a 401-protected Lemonade server the user gets a confusing warning log and then fails later in init instead of immediately.

Issues Found

🟡 _maybe_validate_device soft-passes HTTP errors — inconsistent with cli.py (lemonade_manager.py:344–350)

In cli.py (lines ~132–146), a probe that returns an HTTP 4xx/5xx re-raises because _unreachable = False (the "with status" not in str(_probe_err) guard catches it). In _maybe_validate_device the equivalent block has no such guard:

is_conn = (
    "Request failed:" in msg          # matches connection errors only — good
    or "refused" in msg.lower()
    or "timeout" in msg.lower()
    or "timed out" in msg.lower()
)

LemonadeClient.get_system_info raises LemonadeClientError("Request failed with status 401: …") on auth failure. "Request failed:" in "Request failed with status 401: …" is False (no colon immediately after "failed"), so the 401 case correctly falls to is_conn=False and logs a WARNING — but then the function still returns (soft pass). The device validation is skipped with only a warning, and the user sees a confusing sequence instead of an immediate actionable error.

Suggested fix — re-raise on HTTP errors so the failure surfaces at device-validation time, matching cli.py:

            is_conn = (
                "Request failed:" in msg
                or "refused" in msg.lower()
                or "timeout" in msg.lower()
                or "timed out" in msg.lower()
            )
            if not is_conn and "with status" in msg:
                # Reachable server returned an HTTP error (auth, 5xx) —
                # surface it now rather than hiding it behind a WARNING.
                raise
            if is_conn:

🟢 Probe LemonadeClient created with keep_alive=True but immediately discarded (lemonade_manager.py:327,331)

The probe client is a throwaway — it exists only to call get_system_info and is never stored or reused. Using keep_alive=True opens a persistent connection that lingers for the life of the process, consuming a connection slot unnecessarily.

            if base_url:
                probe = LemonadeClient(
                    base_url=base_url, keep_alive=False, verbose=not quiet
                )
            else:
                probe = LemonadeClient(
                    host=host, port=port, keep_alive=False, verbose=not quiet
                )

🟢 Logic duplicated between _apply_device_model and the sessions router (routers/sessions.py:107–108)

Both files contain:

device_is_explicit = device != "gpu"
if resolved != current_model and (is_default_model or device_is_explicit):

The sessions router can't call _apply_device_model directly (it operates on a request dict, not a live session), but extracting the guard into a small _should_override_model(device, current_model) helper would keep the rule in one place and prevent the two from drifting. Not blocking — worth a follow-up issue.

🟢 Nit: _validated_min_devices missing ClassVar annotation (lemonade_manager.py:149)

    _validated_min_devices: ClassVar[set] = set()

Requires adding ClassVar to the from typing import at line 15.

Strengths

• Comparison direction is correct. detected_idx <= req_idx satisfies the requirement when the host's best device has equal or lower index (higher capability) — the iGPU/dGPU tier equivalence works exactly as described in the module-level comment.
• Memoisation is correctly scoped. _validated_min_devices is keyed by required_min_device tier, not raw device string, so gpu from two different call sites shares one probe. It's cleared by reset(), so test isolation is clean.
• Test suite is comprehensive. test_multi_device_wiring.py covers all four axes (tier mapping, GPU accepts igpu+dgpu, unavailable device raises actionably, device threaded through the agent, unreachable server ≠ hardware error, memoisation, sessions HTTP layer). The dgpu_only.json fixture fills the one gap the pre-existing fixtures left.
• _format_device_error follows the CLAUDE.md fail-loudly rule. The error names what's missing, what the user should do, and where to go next.

Verdict

Approve with suggestions. The 🟡 _maybe_validate_device HTTP-error path is the only item worth addressing before the v0.20.0 tag — everything else is a nit. The core hardware-validation logic, device→model resolution, and memoisation are all correct.

Multi-device wiring is now end-to-end and correct. All three release blockers (B1/B2/H1) and the dGPU tier mapping bug are addressed cleanly. Two nits below — neither blocks merge.

Summary

Before this PR, the device dropdown was purely cosmetic: session["device"] was written and the agent was evicted, but every rebuild site resolved the model from session["model"] (always the GPU default), so NPU selection silently ran on GPU. The runtime never validated whether the requested device existed, and the CLI swallowed every device-probe exception — including auth errors that should have surfaced. All four problems are fixed here with a coherent set of changes across the UI layer (_chat_helpers.py, sessions.py), the manager (lemonade_manager.py), the base agent, and the CLI.

The _validated_min_devices memoisation design is the clearest way to solve "validate on every call but only probe once per tier" without adding a per-request round-trip, and the implementation is correct. The _DEVICE_TO_MIN["gpu"] → "amd_dgpu" fix is the right direction: requiring the lowest GPU tier and using detected_idx ≤ req_idx correctly accepts iGPU, dGPU, or NPU-with-iGPU hosts when gpu is selected.

Issues Found

🟢 Minor — deferred import requests inside except handler (src/gaia/cli.py:660)

requests is a direct dependency (setup.py:126), so the import is safe — but placing it inside an except block is non-idiomatic and slightly obscures the dependency. Because the string-matching fallback already handles the case where __cause__ isn't preserved, the requests type-check is an extra safety net rather than the load-bearing path. Two clean options:

Option A — move the import to the module top (already has from gaia.llm.lemonade_client import LemonadeClientError there):

import requests

(with the other stdlib/third-party imports at the file top)

Option B — drop the isinstance check entirely and rely solely on the string fallback, which covers the same cases without a new import:

                    _unreachable = (
                        str(_probe_err).startswith("Request failed:")
                        and "with status" not in str(_probe_err)
                    )

Either is fine; the current code is not broken.

🟢 Minor — f-string in logger.debug call inside _validate_device_requirement (src/gaia/llm/lemonade_manager.py:301–303)

The string is always formatted even when the debug level is disabled. This is a pre-existing pattern that was moved here during the refactor, so the PR has a natural opportunity to fix it:

            cls._log.debug(
                "Hardware requirement satisfied: %s -> recipe=%s", highest, recipe
            )

Strengths

• _validated_min_devices memoisation elegantly solves the "validate on every ensure_ready call, but don't re-probe the same tier" requirement without any per-request overhead. The reset in LemonadeManager.reset() keeps the lifecycle clean.
• _format_device_error produces messages that satisfy the CLAUDE.md fail-loudly rule precisely: they name what failed, what the user should do, and where to look (gaia init --profile npu, --device gpu).
• Test coverage is comprehensive and purposeful. TestDeviceValidatedAfterWarmInit.test_device_switch_validated_when_already_initialized directly pins the regression scenario (UI switch after warm init); test_passing_device_is_memoized guards against per-request probes; test_unreachable_server_does_not_become_hardware_error ensures a down server doesn't mislabel as missing hardware. The class-level docstrings also communicate the pre-fix behaviour clearly.

Verdict

Approve with suggestions. Both issues are nits; neither affects correctness or the fix for B1/B2/H1. The NPU quality eval note is appropriate — this is a CI-unrunnable check that the maintainer owns before tag, not a reason to block the code change.