fix(tesseract): timeout sous-processus — un binaire figé gelait tout le run sans log

Symptôme production : benchmark Tesseract « charge un document puis
gèle », aucun log, aucune erreur, aucun timeout ne se déclenche.

Cause racine (pré-existante, indépendante du commit retry/image qui
ne touche pas le chemin OCR Tesseract) : les trois appels
pytesseract (image_to_string / image_to_data / image_to_alto_xml)
n'avaient PAS de paramètre `timeout`. pytesseract par défaut
(`timeout=0`) attend le sous-processus `tesseract` indéfiniment. Si
le binaire se fige sur une page, le thread worker reste bloqué dans
un appel C non-interruptible : le CorpusRunner ne peut pas le tuer
(documenté pipeline/runner.py), son timeout/doc est donc inopérant,
les workers du pool se bloquent → run gelé, SSE sans événement à
émettre (d'où « logs show nothing »).

Fix : `timeout_seconds` configurable (défaut 120.0 s, donc sûr sans
config ; `0` = opt-out explicite déconseillé), validé `>= 0`,
forwardé aux 3 appels pytesseract. factory.py:120 passe déjà
`**kwargs` → actif automatiquement dans le chemin web, tunable. Un
sous-processus figé devient un échec borné du document (mappé en
OCRAdapterError, le run continue) au lieu d'un gel infini.

Note (hors scope, non corrigé ici) : state.py:170 fait
`asyncio.Queue.put_nowait()` depuis le thread worker (cross-thread,
sans loop.call_soon_threadsafe). C'est un défaut réel mais masqué en
livraison SSE saccadée ~30 s par la boucle keepalive
`wait_for(timeout=30)` — latence, pas gel permanent. À traiter
séparément si besoin.

Régression : TestTesseractSubprocessTimeout (5 tests). Suite ciblée
OCR : 66 passed.

https://claude.ai/code/session_01KTzTK55Hxu8AR72xJUjcUW

picarones/adapters/ocr/tesseract.py

@@ -92,6 +92,16 @@ class TesseractAdapter(BaseOCRAdapter):
     tesseract_cmd:
         Chemin custom vers l'exécutable ``tesseract``.  Défaut
         ``None`` (laisse pytesseract trouver l'installation système).
+    timeout_seconds:
+        Délai max (s) du sous-processus ``tesseract`` par image.
+        Défaut ``120.0``.  **Garde-fou critique** : un appel
+        ``pytesseract`` sans timeout bloque indéfiniment le thread
+        worker si le binaire ``tesseract`` se fige sur une page
+        (le ``CorpusRunner`` ne peut pas interrompre un sous-processus
+        bloquant — cf. ``pipeline/runner.py``), ce qui gèle tout le
+        run sans log ni erreur.  Avec un timeout, pytesseract tue le
+        sous-processus et lève : le doc échoue proprement et le run
+        continue.  ``0`` désactive explicitement (déconseillé).
 
     Raises
     ------
@@ -131,6 +141,7 @@ class TesseractAdapter(BaseOCRAdapter):
         tesseract_cmd: str | None = None,
         expose_confidences: bool = True,
         expose_alto: bool = False,
+        timeout_seconds: float = 120.0,
     ) -> None:
         if not name or not name.strip():
             raise OCRAdapterError(
@@ -158,6 +169,11 @@ class TesseractAdapter(BaseOCRAdapter):
             raise OCRAdapterError(
                 f"TesseractAdapter : oem doit être ∈ [0, 3], reçu {oem}.",
             )
+        if timeout_seconds < 0:
+            raise OCRAdapterError(
+                "TesseractAdapter : timeout_seconds doit être >= 0 "
+                f"(0 = désactivé), reçu {timeout_seconds}.",
+            )
         self._name = name
         self._lang = lang
         self._psm = psm
@@ -165,6 +181,7 @@ class TesseractAdapter(BaseOCRAdapter):
         self._tesseract_cmd = tesseract_cmd
         self._expose_confidences = expose_confidences
         self._expose_alto = expose_alto
+        self._timeout = float(timeout_seconds)
 
     @property
     def name(self) -> str:
@@ -247,6 +264,7 @@ class TesseractAdapter(BaseOCRAdapter):
                     image,
                     lang=self._lang,
                     config=custom_config,
+                    timeout=self._timeout,
                 )
         except Exception as exc:
             raise OCRAdapterError(
@@ -348,6 +366,7 @@ class TesseractAdapter(BaseOCRAdapter):
                     lang=self._lang,
                     config=custom_config,
                     output_type=pytesseract_module.Output.DICT,
+                    timeout=self._timeout,
                 )
         except Exception as exc:  # noqa: BLE001 — best-effort
             logger.warning(
@@ -407,6 +426,7 @@ class TesseractAdapter(BaseOCRAdapter):
                     image,
                     lang=self._lang,
                     config=custom_config,
+                    timeout=self._timeout,
                 )
         except Exception as exc:  # noqa: BLE001 — best-effort
             logger.warning(

tests/adapters/ocr/test_sprint_a14_s30_tesseract_adapter.py

@@ -388,3 +388,69 @@ class TestTesseractAdapterExecute:
             encoding="utf-8",
         )
         assert out_text == "Hello world"
+
+
+class TestTesseractSubprocessTimeout:
+    """Garde-fou anti-freeze : un sous-processus ``tesseract`` figé
+    bloquait indéfiniment le thread worker (le CorpusRunner ne peut
+    pas tuer un sous-processus bloquant) → run gelé sans log ni
+    erreur.  ``pytesseract`` doit recevoir un ``timeout`` pour
+    convertir le blocage infini en échec borné du document."""
+
+    def _img(self, tmp_path: Path) -> Path:
+        p = tmp_path / "page.png"
+        p.write_bytes(b"\x89PNG\r\n\x1a\n")
+        return p
+
+    def test_rejects_negative_timeout(self) -> None:
+        with pytest.raises(OCRAdapterError, match="timeout_seconds"):
+            TesseractAdapter(timeout_seconds=-1)
+
+    def test_zero_timeout_allowed_explicit_optout(self) -> None:
+        TesseractAdapter(timeout_seconds=0)  # ne lève pas
+
+    @patch("PIL.Image.open")
+    @patch("pytesseract.image_to_string")
+    def test_timeout_forwarded_to_pytesseract(
+        self, mock_its: MagicMock, mock_open: MagicMock, tmp_path: Path,
+    ) -> None:
+        mock_its.return_value = "x"
+        mock_open.return_value.__enter__.return_value = MagicMock()
+        adapter = TesseractAdapter(
+            expose_confidences=False, timeout_seconds=37.5,
+        )
+        adapter.execute(
+            inputs={ArtifactType.IMAGE: _make_image_artifact(
+                str(self._img(tmp_path)))},
+            params={},
+            context=_make_context(),
+        )
+        assert mock_its.call_args.kwargs["timeout"] == 37.5
+
+    def test_default_timeout_is_bounded_not_infinite(self) -> None:
+        # Le défaut DOIT être > 0 : c'est précisément l'absence de
+        # timeout qui gelait le run en production.
+        adapter = TesseractAdapter()
+        assert adapter._timeout > 0
+
+    @patch("PIL.Image.open")
+    @patch("pytesseract.image_to_string")
+    def test_subprocess_timeout_becomes_bounded_error(
+        self, mock_its: MagicMock, mock_open: MagicMock, tmp_path: Path,
+    ) -> None:
+        # pytesseract lève ``RuntimeError('Tesseract process timeout')``
+        # quand le sous-processus dépasse ``timeout``.  L'adapter doit
+        # le mapper en OCRAdapterError (doc échoué, run continue) au
+        # lieu de bloquer indéfiniment.
+        mock_its.side_effect = RuntimeError("Tesseract process timeout")
+        mock_open.return_value.__enter__.return_value = MagicMock()
+        adapter = TesseractAdapter(
+            expose_confidences=False, timeout_seconds=5,
+        )
+        with pytest.raises(OCRAdapterError, match="Tesseract"):
+            adapter.execute(
+                inputs={ArtifactType.IMAGE: _make_image_artifact(
+                    str(self._img(tmp_path)))},
+                params={},
+                context=_make_context(),
+            )