fix(rag): stop indexing on a broken vision model and name it - #7154

Summary

A vision model that is installed but crashing no longer turns a scanned PDF into blank pages. Indexing stops after the model has failed twice in a row without reading any image, and the error names the model and its last error. Before, every page waited out the failure in turn (minutes for a 10-page scan), and the run ended with a hint to download the model that was already there.

Why

The issue's Strix Halo box reset the Qwen3-VL backend on every image. Each page's failure became a page warning, so the document indexed as text-only, or failed as "no extractable text, enable VLM image extraction by downloading …", which sends the user after the wrong fix. The bot's suggested fix on the issue (stop once the model has failed with nothing read, and name it) is what this does.

Linked issue

Closes #4741

Changes

• PDFs and PowerPoints stop on a broken vision model. Two failures in a row with no image read raise an error that names the model and its last error, and says to check Lemonade's log and index again. A model that reads some images and fails on others still indexes, with those pages in degraded_pages, as before.
• The PowerPoint-to-PDF path doesn't fall back and ask the same broken model again.
• index_document returns error_type: "vision_model_failed", and the agent tool's hint says the model failed, not the file, instead of "suggest they check the file".
• The PDF page loop catches only vision errors. PDFium errors already have their own handler, so the broad catch was only hiding bugs.
• Docs: the RAG SDK guide and the RAG SDK and tools specs describe the new error.

Test plan

Run in a python:3.12 container:

• pytest tests/unit/rag/test_failing_vision_model.py: 7 passed. It indexes real reportlab PDFs and python-pptx decks with a vision model that fails, works, or fails after working.
• pytest tests/unit/test_rag_file_resolution.py::TestIndexDocumentVisionModelFailed: passes; the tool keeps the error and doesn't blame the file.
• pytest tests/unit/rag tests/unit/test_vlm_extraction_failures.py tests/unit/test_rag_file_resolution.py tests/unit/test_vision_uses_downloaded_model.py tests/test_rag.py: 909 passed, 35 skipped.
• Full pytest tests/unit: 38,761 passed, 590 skipped, 15 failed, of 39,270 collected, with no crashed workers. The 15 fail the same way on main in this container: 14 shell-guardrail and skill-grant tests refuse gh and npm because neither is installed there, and one expects a folder it can't create, but the container runs as root. 44 tests have :: inside their parameters, so they were rerun by file to account for them.
• python util/lint.py --all: passes.

The agent tool's reply for this failure gains a hint, so rag_quality is the eval category to watch on the next RC.

Evidence

The same 10-page scan, indexed with a vision model that fails every image with backend_watchdog_reset:

# main
vision model asked: 10 times
error: No extractable text in PDF: scan.pdf
  ...
  2. Or enable VLM image extraction by downloading Qwen3-VL-4B-Instruct-GGUF in Lemonade

# this PR
vision model asked: 2 times
error_type: vision_model_failed
error: Could not read the images in scan.pdf: the vision model Qwen3-VL-4B-Instruct-GGUF failed 2 times in a row without reading any of them.
Last error: Vision extraction failed for page 2, image 1: Backend error: backend_watchdog_reset
Check Lemonade's log for errors from that model, fix it or restart Lemonade, then index this file again.

• Agent exposed in the Agent UI: N/A
• MCP tools / servers: N/A
• CLI: N/A
• HTTP API / REST: N/A

Checklist

• I have linked a GitHub issue above (Closes #N / Fixes #N / Refs #N).
• I have described why this change is being made, not just what changed.
• I have run linting and tests locally (python util/lint.py --all, pytest tests/unit/).
• I have attached real-world evidence matched to the surface I changed (see Evidence above), or marked each surface N/A.
• I have updated documentation if user-visible behavior changed (see CONTRIBUTING.md).