feat(agents): add Chat Lite + Settings model/ctx/memory controls

[kovtcharov]

Summary

Ships Chat Lite — a 4B-model sibling of the built-in Chat Agent for Macs and other hardware that cannot host the 35B default — plus the three Settings controls needed to make swapping models practical: an Active Model override, a Context Size picker, and per-agent Memory Warnings. Chat Agent and its defaults are untouched; this is purely additive.

Threads

• New chat-lite agent (registry.py) — reuses ChatAgent but presets model_id to Qwen3-4B-Instruct-2507-GGUF (falls back to Qwen3-4B-GGUF). Appears alongside Chat in the picker. Why: 35B won't load on ~8-16GB machines, so users were stuck with no working out-of-the-box option.

• AgentInfo.min_memory_gb — new optional field on registrations/manifests/API. Chat Lite declares 5.0, Chat keeps None. Settings renders a Memory Warnings block only for agents whose requirement exceeds memory_available_gb. Why: warn before the user wastes time picking an agent that will OOM.

• Settings: Active Model — text field bound to the existing custom_model setting, with "Use agent default" placeholder. Empty → agent's registered models[0] wins (unchanged backend logic). Why: users needed a visible way to swap models per-agent without editing settings JSON.

• Settings: Context Size — preset chips (4K / 8K / 16K / 32K) plus numeric input, Apply reloads the active model via the existing /api/system/load-model. Why: matches what Lemonade's lemonade load --ctx-size already supports but the UI never exposed.

• expected_model_loaded respects registered agents (system.py) — used to hardcode the 35B default, so Chat Lite's 4B always tripped "Wrong model loaded". Now accepts any registered agent's preferred model as valid. Why: the old check is wrong the moment you have more than one agent with different model preferences.

• Pre-flight load handles wrong-model + small-ctx (_chat_helpers.py) — _maybe_load_expected_model used to short-circuit if any LLM was active, even the wrong one, and never checked ctx. It now requires the specific expected model with ctx ≥ 32K; otherwise it reloads. Why: Lemonade auto-loads requested models at its default 4096 ctx, silently truncating ChatAgent's >7K-token system prompt, producing an empty stream. This is what blocked Chat Lite from ever returning a response. _ensure_model_loaded also gains a 32K fallback for models not in the built-in MODELS registry (same rationale).

Test plan

• python -m pytest tests/unit/agents/ tests/unit/chat/ui/test_agents_router.py — 156 pass, incl. 10 new
• python util/lint.py --black --isort — green
• cd src/gaia/apps/webui && npm run build — clean, 0 new warnings
• End-to-end on Mac: create a chat-lite session, send "Reply with exactly: hello from chat-lite" — model auto-loads, streams back "hello from chat-lite" at ~60 tok/s
• Second message in same session — no reload (pre-flight correctly short-circuits when model + ctx already match)
• Open Settings modal on a running instance: verify Active Model, Context Size, and Memory Warnings sections render and persist round-trips

Out of scope

Two related improvements deferred to follow-ups:

• Lemonade's admin API lives on port 13305 in v10.x but GAIA still defaults to localhost:8000. Users currently need LEMONADE_BASE_URL=http://localhost:13305/api/v1 as an env var. A port probe would remove that step.
• _try_reload_with_ctx reloads whatever model is currently loaded, not the target model. Harmless after the pre-flight fix above, but worth cleaning up.

[github-actions]

Summary

Ships the Gaia Lite agent (ChatAgent + 4B model for low-memory hardware) and three Settings controls (Active Model override, Context Size picker, Memory Warnings) — purely additive and well-bounded. The real gem is the _maybe_load_expected_model fix in src/gaia/ui/_chat_helpers.py:407-467: the old short-circuit ("any LLM loaded → skip") silently truncated ChatAgent's >7K-token prompt when Lemonade had auto-loaded a model at 4096 ctx, producing empty streams. The new check (right model and ctx ≥ 32K) is the only reason Gaia Lite can ever return a response. Strong test coverage (10 new tests), clean consolidation of DEFAULT_CONTEXT_SIZE into a single source of truth, thoughtful comments at every non-obvious branch.

Issues Found

🟢 Minor

Silent except Exception in _canonical_agent_type (src/gaia/ui/_chat_helpers.py:93-106)

canonical_id is a pure dict lookup on a string — it physically cannot raise unless agent_type is unhashable, which the type hint already rules out. The blanket except Exception: return agent_type is silent degradation that CLAUDE.md's "fail loudly" rule tries to eliminate. Either drop the try/except entirely or narrow it:

def _canonical_agent_type(agent_type: str) -> str:
    """Resolve legacy agent-type aliases (e.g. ``chat-lite`` → ``gaia-lite``).

    Keeps the per-session agent cache from thrashing when a client mixes the
    old and new IDs within the same session — both resolve to the same
    canonical ID and therefore the same cache entry.
    """
    registry = _agent_registry
    if registry is None:
        return agent_type
    return registry.canonical_id(agent_type)

memory_available_gb defaults to 0.0 in src/gaia/ui/models.py:25

If psutil ever fails to populate memory_available_gb (e.g. an exception path in system_status), the default 0.0 makes a.min_memory_gb > 0 trip the Memory Warnings banner for every agent with a declared requirement — a confusing false-positive. Cheap guard: check a sentinel (status.memory_available_gb > 0) inside the filter in SettingsModal.tsx:549-551, or make the backend field Optional[float] = None and gate rendering on != null.

                        const warnings = status.memory_available_gb > 0
                            ? agents.filter(
                                (a) => a.min_memory_gb != null && a.min_memory_gb > status.memory_available_gb,
                            )
                            : [];

Source-shape regex test is fragile (tests/unit/chat/ui/test_chat_helpers.py:1493-1525)

The regex-over-source assertion for "streaming branch passes rag_file_paths=[]" will break if a future refactor adds a line break inside the call (e.g. a formatter change), even though the behavior is still correct. The comment acknowledges the tradeoff, but you could get the same ratcheting effect by monkeypatching registry.create_agent and asserting on the received kwargs — no mock for the full SSE/Lemonade stack required. Keep as-is if the cost/benefit feels right; flagging because a false CI red in 6 months will not be obvious.

Memory threshold comment vs. constant (src/gaia/agents/registry.py:102-109)

The 5 GB floor is justified as "Q4_K_M weights ~2.5 GB + context + runtime headroom". Nice rationale — consider lifting 5.0 to a module constant (_GAIA_LITE_MIN_MEMORY_GB = 5.0) so the number and the justification live together and don't drift if a bigger checkpoint is added to the models list later.

update_settings null-vs-empty-string docstring (src/gaia/ui/routers/system.py:430-435)

The new docstring is correct in its current wire format, but Pydantic absolutely can distinguish null from "unset" if the field uses Optional[str] = Field(default=None) + checks "custom_model" in request.model_fields_set. The comment bakes in a client-side workaround ("send \"\"") that future maintainers might puzzle over. Consider a one-line "see SettingsUpdateRequest for why" pointer, or clarify that this is a GAIA choice, not a Pydantic limitation.

Strengths

• Single source of truth for DEFAULT_CONTEXT_SIZE — consolidated in src/gaia/llm/lemonade_client.py:100-108 and re-exported from lemonade_manager and routers/system. Exactly the kind of consolidation that prevents the "ctx ceiling drifted between modules" bug class.
• _session_agent_kwargs helper in src/gaia/ui/_chat_helpers.py:342-365 dedupes four call sites that were already a foot-gun (the non-streaming-vs-streaming rag_file_paths=[] asymmetry is now documented at the call sites rather than being a silent timebomb).
• Legacy chat-lite alias (_LEGACY_ID_ALIASES in registry.py:107-113) avoids a DB migration for persisted sessions, is plumbed through get, create_agent, and resolve_model (the last one is easy to miss and has a specific regression test), and the alias map is trivial to extend on the next rename.
• Manifest factory kwarg filtering (registry.py:428-449) correctly identifies that the dynamic class's **kwargs forwards to BaseAgent.__init__ and introspects that signature rather than the class's — the comment explicitly explains why MRO-walking is a footgun.
• ctx_size: Optional[int] = Field(None, gt=0) in LoadModelRequest (system.py:468) — boundary-level validation that returns a clean 422 instead of a cryptic Lemonade error. Exactly what CLAUDE.md's "fail loudly at the boundary" rule asks for.
• MessageBubble "Gaia"-prefix strip (MessageBubble.tsx:242-251) — the word-boundary regex correctly handles both "Gaia Lite" and a hypothetical "Gaiadocs"; the inline comment earns its place.

Verdict

Approve with suggestions — no blocking issues. The except Exception and the memory_available_gb = 0.0 default are real but low-severity, and the other flags are nice-to-haves. Ship it after the author decides which suggestions to apply.

[kovtcharov]

@claude troubleshoot why our CI/CD pipeline is failing.

[github-actions]

CI/CD Failure Triage for PR #802

Two of the required checks are red on commit 6fd1e6f (run list):

🟡 1. Code Quality (Lint) — 2 issues

Job log

#	Check	File	Fix
1	Black formatting	src/gaia/mcp/mcp_bridge.py (the "error": {…} block around L332)	python util/lint.py --black --fix
2	Agent conventions	schemas/agent-manifest.schema.json is stale vs. the manifest model (this PR touches AgentInfo.min_memory_gb and resolve_model in registry.py)	python util/gen_manifest_schema.py

Note: the manifest-schema regeneration is the genuine tell here — the schema generator wasn't re-run after min_memory_gb landed, so it drifts from the runtime Pydantic model. That's the same drift the existing linter is designed to catch.

🟡 2. Unit Tests — 6 failures, all caused by this PR

Job log — 6 failed, 1484 passed, 16 skipped

All six are stale tests that still encode the old short-circuit behavior, not bugs in the new code. They directly contradict the "Pre-flight load handles wrong-model + small-ctx" thread in the PR description:

tests/unit/test_chat_preflight.py (4 tests) — pre-flight now requires the right model and ctx ≥ 32K, not just "any LLM is loaded":

• test_llm_active_skips_load — asserted LemonadeClient not called; actual call: load_model('Qwen3.5-35B-A3B-GGUF', ctx_size=32768, prompt=False)
• test_vlm_active_skips_load — same
• test_concurrent_second_thread_skips_load — same
• test_sse_not_called_on_fast_path — asserted _emit not called; actual calls: "Loading LLM model..." + "Could not auto-load LLM..."

tests/unit/test_lemonade_model_loading.py (2 tests) — _ensure_model_loaded now passes ctx_size=32768 for models not in the built-in MODELS registry (the 32K fallback described in the PR):

• test_calls_load_when_model_not_loaded — expected ctx_size=None, got ctx_size=32768
• test_model_loaded_when_not_present — same

Suggested fix plan

# 1. Reformat + regen schema
python util/lint.py --black --fix
python util/gen_manifest_schema.py

# 2. Update the 6 stale tests to assert the new behavior:
#    - test_chat_preflight.py: wrong-model or small-ctx case should now expect a reload + SSE emit
#    - test_lemonade_model_loading.py: expected `ctx_size=32768` on models outside MODELS registry
python -m pytest tests/unit/test_chat_preflight.py tests/unit/test_lemonade_model_loading.py -xvs

# 3. Full lint + unit suite before re-pushing
python util/lint.py --all
python -m pytest tests/unit/

All other checks (API Tests, CLI/Linux, CLI/Windows, Agent SDK, RAG, Security, CodeQL, Lemonade Embeddings) are green, so scope is narrow.

[kovtcharov]

@claude review this PR.

[github-actions]

PR Review — feat(agents): add Chat Lite + Settings model/ctx/memory controls

I reviewed the current state of this PR (HEAD 2c967a4, 31 commits, +6857/-2219 across 68 files). The Gaia Lite + Settings work itself looks solid — the previous review covered that scope well. But the PR has materially changed since then and I see three blockers plus a serious scope concern.

---

🔴 Blockers (must fix before merge)

1. eval/runner.py is Windows-incompatible — breaks 50+ tests.

src/gaia/eval/runner.py:20 unconditionally import fcntl for the new process-wide lock (commit 404ee397). fcntl is POSIX-only, so on Windows the module-load itself fails with ModuleNotFoundError: No module named 'fcntl' and every test that imports gaia.eval.runner errors out. The Test Eval Tool (Windows) job shows ~50 failures all with this exact stack.

The lock comment already acknowledges "better degraded than dead" for the OSError path on /tmp — apply the same logic to platform: if sys.platform == "win32": yield; return, or use msvcrt.locking() for cross-platform support. As written, this PR cannot ship to Windows users.

2. schemas/agent-manifest.schema.json is stale — lint job fails.

Code Quality is red on the same issue I flagged on Apr 20: the min_memory_gb field landed in the Pydantic model but the generated schema wasn't regenerated. One-shot fix:

python util/gen_manifest_schema.py
git add schemas/agent-manifest.schema.json && git commit -m "chore: regenerate manifest schema"

3. Merge conflicts against main.

gh pr view reports mergeable: CONFLICTING. Last merge from main was dbf0100a on commit-day-12 of this branch's life — a fresh rebase will surface what conflicts and let you resolve them deliberately rather than at merge time.

---

🟡 Important — scope creep is hiding the real review surface

The PR title and description still describe the original 6 threads (Gaia Lite agent, 3 Settings controls, expected_model_loaded, pre-flight load). The actual diff now contains at least 11 additional themes that aren't mentioned:

Theme	Evidence	LoC
Synthetic eval corpus generator	eval/corpus/gen_real_world.py + 19 docs + 4 .xlsx	+1303
--agent-type flag for eval	src/gaia/eval/runner.py	~200
Process-wide eval lock (the fcntl one)	src/gaia/eval/runner.py	~200
Tool-call envelope recovery + context-overflow retry	src/gaia/agents/base/agent.py	~540
Typed Lemonade errors + auto-retry	src/gaia/llm/providers/lemonade.py	~160
UI polish (cards, sidebar, greetings, ctx badge, drag-drop, varied greetings)	src/gaia/apps/webui/src/components/*	~700
Live model-download progress + auto-load + banner priority	src/gaia/apps/webui/src/components/ConnectionBanner.tsx	~140
Removed PyPI wheel-dist verification gate	.github/workflows/pypi.yml, util/verify_wheel_dist.py	−392 +33
Removed AGENTS.md (168 lines)	repo root	−168
Removed tests/unit/test_lemonade_manager_preload.py, test_init_ctx_size.py, test_export_import.py, test_code_index_sdk.py, test_ui_extras.py, test_verify_wheel_dist.py	tests	−981
Docs edits across agent-ui, code-index, custom-agent, patterns, plugin-registry, setup-wizard	docs/	~250

The reliability/UI polish work is mostly good in isolation — but I cannot do an honest review of "Chat Lite + Settings controls" when the diff also silently removes the PyPI wheel-dist gate (which was added specifically to prevent the webui-bundling regression that motivated docs/sdk/sdks/agent-ui.mdx) and 6 test modules totaling ~1000 LoC.

Two things would unblock review:

1. Update the PR description to enumerate every theme with a why, especially the deletions:
   • Why is verify_wheel_dist gone? Has the underlying regression class been ruled out?
   • Why is AGENTS.md deleted while CLAUDE.md still references AI-agent conventions?
   • Why were those 6 test modules removed — were the modules-under-test deleted, or just the tests?
2. Or split — at minimum, separate the eval corpus + reliability fixes into their own PRs. The original Chat Lite scope is small and reviewable; bundled this way it isn't.

---

🟢 What's still good

• The original 6 threads still hold up; suggestions from the Apr 20 review (the silent except Exception in _canonical_agent_type, the memory_available_gb = 0.0 default, the source-shape regex test) are worth checking but none are blockers.
• Test additions are thorough — tests/unit/agents/test_parse_error_recovery.py (+185), the registry tests (+566), and the chat-helpers expansion (+114) are all well-targeted.
• The _chat_helpers.py consolidation around _session_agent_kwargs and _maybe_load_expected_model (right model and ctx ≥ 32K) is the real load-bearing fix and it's well-commented.

---

Suggested path forward

# 1. Fix Windows fcntl
# In src/gaia/eval/runner.py, guard the import + helpers behind sys.platform.

# 2. Regenerate schema
python util/gen_manifest_schema.py

# 3. Rebase and re-run CI
git fetch origin && git rebase origin/main

# 4. Update PR description to match the actual diff (or split)

Once Windows + lint are green and the description matches the diff, this is reviewable for merge. Tagging @kovtcharov-amd for the scope/split decision since the deletions of AGENTS.md, the PyPI gate, and ~1000 LoC of tests are call-it-out-loud changes that need a maintainer eyes-on regardless of how the rest of the review goes.

[github-actions]

Summary

Substantively this is a strong, well-reasoned PR — the Chat Lite agent + Settings controls solve a real "35B won't load on this box" UX hole, and the pre-flight model + ctx≥32K fix is the right diagnosis for the silent-truncation bug. Inline comments are unusually good at explaining why (legacy-alias rationale, ctx-size floor reasoning, Gemma-vs-Qwen platform split). Most of my notes are about scope/description hygiene rather than the code itself.

Issues

🟡 Important

1. PR description is stale relative to the actual implementation.

The description claims the agent ID is chat-lite and the primary model is Qwen3-4B-Instruct-2507-GGUF. The code actually ships:

• Agent ID is gaia-lite (chat-lite is preserved as a legacy alias for stored sessions).
• Primary models are Qwen3.5-4B-GGUF (Darwin) and Gemma-4-E4B-it-GGUF (Linux/Windows), with platform-conditional ordering.

src/gaia/agents/registry.py:212-258 and the _LEGACY_ID_ALIASES plumbing are the right design, but the PR description is what reviewers and future archaeologists will read first — please bring it in line with reality before merge.

2. Scope is much wider than the description signals.

The description lists ~6 threads centered on Chat Lite + Settings. The diff also contains, none of which are mentioned:

• Typed Lemonade error hierarchy (LemonadeError/LemonadeModelNotLoadedError/LemonadeContextOverflowError/LemonadeNetworkError) with _classify_chat_exception walker and one-shot retry-after-reload in both streaming and non-streaming paths.
• Tool-call parse-error recovery loop in agents/base/agent.py (synthetic recovery prompt, 3-attempt cap, friendly fallback) + new tests/unit/agents/test_parse_error_recovery.py.
• Context-overflow _shrink_messages_for_overflow + retry-after-trim.
• eval/runner.py fcntl-based single-runner lock with stale-PID reclaim and GAIA_EVAL_NO_LOCK bypass.
• system.py SSE-consuming download-progress streaming + _auto_load_after_download + new DownloadProgress model.
• Auto-titling background task in _chat_helpers.py (Jaccard-overlap heuristic, 30 s throttle, fire-and-forget httpx call).
• WebUI red-color/cursor redesign (~10 CSS files, MessageBubble/Sidebar/ConnectionBanner restyle).
• New eval/corpus/gen_real_world.py (1,303 lines) + 19 generated documents + 4 xlsx files + 4 baseline/postfix eval/results/*.json snapshots.

Each of those has its own correctness surface. A reviewer reading the description will skip them; a future bisector tracking down (say) an eval-lock or auto-title regression will not realize this PR is the introduction. Either split or — more pragmatically given the size — expand the description to thread-list every distinct change with a one-line why. This is exactly the case CLAUDE.md's "PR Descriptions — Tight and Value-Focused" rule warns about: "If the PR really does bundle many threads, group them — don't list 16 commits."

3. tunnel-friendly-error.png (147 KB) committed at the repo root.

pr-files.txt:71 adds a binary screenshot with no references in code, docs, or .gitignore updates that would explain it. Looks like a debugging artifact that slipped in alongside pr-diff.txt / .claude-pr/. Please drop it before merge.

# (delete tunnel-friendly-error.png from the worktree before push)

🟢 Minor

4. uv.lock quietly drops the Python floor from 3.13 → 3.12 (uv.lock:3) without a corresponding pyproject.toml/setup.py change. Either it's intentional (in which case python_requires in the source-of-truth metadata should match, and the change deserves a one-liner in the description because it broadens supported Python versions) or it slipped in from a local-env bisect (in which case revert).

5. _classify_chat_exception walks __cause__ only, not __context__ (src/gaia/ui/_chat_helpers.py:117-121). Implicit chains from a bare raise ... inside an except block (no from e) won't be matched by the typed-isinstance pass. The substring fallback at :126 covers most of the gap, but if you ever rely on the typed-instance metadata (e.g. LemonadeContextOverflowError.retryable), an implicit chain will skip that branch.

    cur: Optional[BaseException] = exc
    while cur is not None:
        if isinstance(cur, LemonadeError):
            return cur
        cur = cur.__cause__ or cur.__context__

6. Auto-title task can race the next user turn for the Lemonade slot. _maybe_update_session_title fires _generate_session_title against /v1/chat/completions immediately after a stream finishes, without acquiring model_load_lock or any other coordinator. If the user's next message arrives while titling is in-flight and triggers a reload (e.g. they switched agents in the UI), both calls contend for Lemonade's single inference slot. Not a correctness bug — Lemonade serializes — but it can stretch the user-visible "thinking" delay by however long the title generation takes. Worth either gating titling behind the same lock or short-circuiting it when a load is pending.

7. eval/runner.py _acquire_eval_lock writes the PID after stale-lock reclaim, but if the os.write fails the lock fd stays open and the next failure message will print holder=-1. Cosmetic — the lock itself works — but worth a try/except around the PID stamping so the diagnostic stays useful.

8. gaia_lite_factory silently filters unknown kwargs via valid_fields (registry.py:229-235). This is the established pattern across the codebase, so I'm not asking you to change it here, but it does mask kwarg typos at call sites. Consider a follow-up that logs at debug when a kwarg is dropped — would catch a class of silent-config-bug.

Strengths

• Inline rationale is excellent. The legacy-alias docstring (registry.py:78-96), the platform-split block (:200-215), the _GAIA_LITE_MIN_MEMORY_GB = 5.0 derivation (:217-224), and the 32K-fallback comments in lemonade_client.py all explain why, not what. This is the kind of comment that ages well — preserve this discipline.
• Single-source-of-truth discipline. canonical_id() resolving aliases through one path; _GAIA_LITE_MODELS[0] driving both UI and factory preset; DEFAULT_CONTEXT_SIZE re-exported instead of re-declared. These are the right moves and they paid off in test cleanup.
• Test coverage is real, not nominal. test_parse_error_recovery.py, the alias-resolution suite in test_registry.py, the test_right_model_wrong_ctx_triggers_reload case, and the test_known_model_uses_registry_ctx_size regression guard all hit failure modes that would otherwise return as production bug reports. Mocks are at sensible boundaries.
• "Fail loudly" rule respected. _canonical_agent_type propagates AttributeError rather than swallowing it; typed Lemonade errors carry actionable user_message text; pre-flight reload emits a visible "Model reloaded — retrying…" SSE.

Verdict

Approve with suggestions.

The blockers are documentation, not code: please update the PR description (Issue 1) and drop tunnel-friendly-error.png (Issue 3) before merging. The uv.lock Python-version question (Issue 4) is worth a one-line clarification in the description either way. Everything else is non-blocking — minor robustness and ergonomic notes.

[itomek]

Cross-platform local validation

Every push to this branch was validated on both local Linux (Docker) and local Windows (SSH) before going out — so we don't burn an hour of CI to find platform-specific regressions.

Workflow

1. Commit the working tree, then bundle the rebased branch + commit: git bundle create /tmp/pr802.bundle origin/main..HEAD.
2. Transfer the bundle to the test box (docker cp for Linux, scp for Windows).
3. On the test box: git fetch /tmp/pr802.bundle "HEAD:refs/heads/test/pr802-…" && git checkout test/pr802-… (a throwaway branch — never touches the box's existing checkout).
4. Run the same gates CI runs:
   • python util/lint.py --black --isort --pylint --flake8
   • python -m pytest tests/unit/ tests/test_eval.py

Results for b2a952f0

Platform	Lint	tests/test_eval.py	tests/unit/
macOS host	✅ clean	✅ 100 / 100	✅ 1708 passed, 15 skipped, 0 failed
Linux container	✅ clean	✅ 100 / 100	✅ 1695 passed, 23 skipped, 0 failed
Windows (real win32)	n/a	✅ 100 / 100	1695 passed, 15 skipped, 13 failed*

*The 13 Windows-only failures are pre-existing Linux-specific tests (os.geteuid mock patches, sys.platform="linux" monkeypatches) in tests/unit/test_init_command.py::TestInstallViaPpa (7 tests, Ubuntu-PPA installer paths) and tests/unit/installer/test_uninstall_command.py (6 tests, POSIX path/permission paths). None have skipif win32 guards. CI's Run Unit Tests job is Linux-only, so it doesn't surface them. These tests would also fail against origin/main on Windows — not a regression from this PR.

What this catches

• Linux-specific import paths and lazy-import side effects. The new if sys.platform == "win32": fcntl = None; else: import fcntl guard in eval/runner.py was verified to import cleanly on Linux and on real Windows (platform=win32, fcntl=None) before pushing — the original blocker fix that made all of tests/test_eval.py go green on Windows.
• File-system case-sensitivity bugs that pass on macOS but fail on Linux.
• Lockfile resolution differences between hosts.
• Real-Windows behaviour the macOS-side monkeypatch.setattr(runner, "fcntl", None) test simulates — verified end-to-end here, not just by the GitHub Actions Windows runner.

One-time setup quirks

• Linux: project venv was missing pyfakefs (declared in setup.py's dev extras), making tests/unit/installer/test_uninstall_command.py ERROR on collection. uv pip install pyfakefs clears it.
• Windows: tests/unit/chat/ui/test_*.py needs the [ui] extra (FastAPI) on top of [dev]. uv pip install -e ".[dev,ui]" from a fresh venv is the one-shot recipe.