papersearch 0.4.2 → 0.4.3

package/carsi/paper_search_carsi/engine/batch_login.py

@@ -8,6 +8,7 @@ import json
 import re
 import time
 from typing import Any
+from types import SimpleNamespace
 from urllib.parse import unquote, urljoin, urlparse
 
 from . import access_rules
@@ -65,20 +66,23 @@ class LoginMixin:
         self._wait_past_redirect_page(page, result)
         self._raise_on_publisher_content_error(page)
         self._dismiss_cookie_banners(page, result)
-        if self._institution_pdf_entitlement_missing(page):
+        snapshot = self._access_snapshot(page) if not self._is_auth_page(str(page.url)) else None
+        if self._institution_pdf_entitlement_missing(page, snapshot=snapshot):
             return False
-        if self._pdf_first_unless_signed_out(page, result):
+        if self._pdf_first_unless_signed_out(page, result, snapshot=snapshot):
             return True
         return self._complete_login_from_current_page(page, result)
 
-    def _pdf_first_unless_signed_out(self, page: Any, result: DownloadResult) -> bool:
+    def _pdf_first_unless_signed_out(self, page: Any, result: DownloadResult,
+                                   snapshot: SimpleNamespace | None = None) -> bool:
         """True unless the page says the reader is signed out (access_rules OUT).
 
         With the institution's session, or an open-access article, the PDF is
         taken. With nothing either way, or with only the reader's access (also
         a personal account's or ClinicalKey's, J Hepatol 2026-10-31), the PDF is
         tried first and the school's login follows once if it fails (batch.py)."""
-        verdict, basis, evidence = self._access_decision(page)
+        result._open_access_current = False
+        verdict, basis, evidence = self._access_decision(page, snapshot) if snapshot is not None else self._access_decision(page)
         if verdict != access_rules.UNKNOWN:
             detail = f"{verdict} ({basis}): {evidence}"[:240]
             if next((e["detail"] for e in reversed(result.events) if e["state"] == "access_decision"), None) != detail:
@@ -86,6 +90,7 @@ class LoginMixin:
         if verdict == access_rules.OUT:
             return False
         open_to_all = basis == "reader" and access_rules.OPEN_TO_ALL.search(evidence.split("badge: ", 1)[-1])
+        result._open_access_current = bool(open_to_all)
         if (basis != "session" and not open_to_all and not getattr(result, "_pdf_first", False)
                 and not self._school_login_done()):
             result._pdf_first = True
@@ -122,32 +127,33 @@ class LoginMixin:
             return url[:200]
         return f"{url[:200]} | {verdict} ({basis or 'no rule'}): {evidence[:160]}"
 
-    # How long a page that shows no text yet is given to draw it.
-    PAGE_TEXT_WAIT_SEC = 20
     _PAGE_TEXT_JS = "() => document.contentType !== 'text/html' ? -1 : (document.body ? document.body.innerText.trim().length : 0)"
 
     def _wait_for_page_text(self, page: Any, result: DownloadResult) -> None:
-        """Let a page without any text yet draw it before it is judged: De Gruyter's
-        article page stayed blank for 9 s and was taken for one without an
-        institution entry (2026-11-02). Still blank after ``PAGE_TEXT_WAIT_SEC``:
-        the publisher's page did not load (``PublisherContentError``)."""
+        """Wait for the document before judging access, within the page budget.
+
+        A verification can disappear before the article draws. The old fixed
+        20 s cut this wait short even with automation time left (AIP,
+        2026-11-04). The enclosing page operation still bounds the whole step.
+        """
         def shown() -> bool:
             try:
                 return page.evaluate(self._PAGE_TEXT_JS) != 0
             except Exception as exc:
                 if not _is_browser_error(exc):
                     raise
-                return True  # a page navigating meanwhile is judged by the steps after
+                return False  # a document being replaced has not been read yet
         started = time.time()
         if shown():
             return
-        drawn = pump_until(page, shown, self.PAGE_TEXT_WAIT_SEC * 1000, step_ms=500)
+        timeout_sec = self.page_wait_sec
+        drawn = pump_until(page, shown, int(timeout_sec * 1000), step_ms=500)
         # Recorded however short: a blank page is worth knowing about.
         self._event(result, "wait", f"blank page: {time.time() - started:.0f} s, ended: "
-                                    f"{'text shown' if drawn else f'its {self.PAGE_TEXT_WAIT_SEC} s'}")
+                                    f"{'text shown' if drawn else f'its {timeout_sec:g} s'}")
         if not drawn:
             url = str(getattr(page, "url", "") or "")
-            raise PublisherContentError(f"publisher_page_blank: {url[:160]} showed no text for {self.PAGE_TEXT_WAIT_SEC} s")
+            raise PublisherContentError(f"publisher_page_blank: {url[:160]} showed no text for {timeout_sec:g} s")
 
     def _wait_past_redirect_page(self, page: Any, result: DownloadResult, timeout_sec: float = 20) -> None:
         """Let a publisher's script redirect page (linkinghub "Redirecting") move on
@@ -187,9 +193,12 @@ class LoginMixin:
         self._phase(result, "login")
         started, signed_in = time.time(), False
         try:
-            signed_in = self._complete_login_steps(page, result)
-            if signed_in:
-                self._return_to_article_after_login(page, result)
+            from ..browser import watchdog
+            # Human authentication has its own budget, not the automation's.
+            with watchdog.pause_operation():
+                signed_in = self._complete_login_steps(page, result)
+                if signed_in:
+                    self._return_to_article_after_login(page, result)
             return signed_in
         finally:
             last = next((e["state"] for e in reversed(result.events) if e["state"] != "wait"), "")
@@ -631,17 +640,23 @@ class LoginMixin:
         host = urlparse(self._entity_id()).hostname or getattr(result, "_idp_host", "")
         return access_rules.registrable_domain(host) if host else ""
 
-    def _school_or_federation_page(self, url: str, result: DownloadResult | None = None) -> bool:
+    def _school_or_federation_page(self, url: str, result: DownloadResult | None = None, *,
+                                   include_publisher_chooser: bool = True) -> bool:
         """The school's IdP or another page of its own site (its registrable domain),
-        or a federation's or the publisher's school chooser: the user's part of the
-        login, where the engine answers no banner and leaves the page where it is."""
+        or a federation's school chooser. Publisher-owned choosers are included
+        by default; their cookie prompts can be answered separately. The school's
+        own pages remain protected even if an adapter calls one a chooser."""
         host = (urlparse(url).hostname or "").lower()
         if not host:
             return False
-        if self._is_idp_host(host) or self._is_federation_chooser(url):
+        if self._is_idp_host(host):
             return True
         school = self._school_domain(result)
-        return bool(school) and access_rules.registrable_domain(host) == school
+        if school and access_rules.registrable_domain(host) == school:
+            return True
+        if not include_publisher_chooser and self.adapter.is_institution_chooser(url):
+            return False
+        return self._is_federation_chooser(url)
 
     def _stuck_on_school_site(self, page: Any, result: DownloadResult) -> str:
         """The page's URL when the login has stayed on a page of the school's own
@@ -798,7 +813,9 @@ class LoginMixin:
         for (const el of document.querySelectorAll('button, [role="button"], a')) {
             if (!shown(el) || el.closest('form')) continue;
             const label = (el.innerText || el.getAttribute('aria-label') || '').replace(/\s+/g, ' ').trim();
-            if (!MENU.test(label)) continue;
+            // A screen-reader hint can be part of innerText ("Sign In Open Menu").
+            const menuLabel = label.replace(/\s+open menu$/i, '');
+            if (!MENU.test(menuLabel)) continue;
             const href = (el.getAttribute('href') || '').trim();
             if (el.tagName === 'A' && href && !href.startsWith('#') && !/^javascript:/i.test(href)
                     && !TOGGLES.some(name => el.hasAttribute(name))) continue;
@@ -1374,8 +1391,9 @@ class LoginMixin:
     def _dismiss_cookie_banners(self, page: Any, result: DownloadResult | None = None, *,
                                 blocking: bool = False) -> bool:
         """Answer a cookie banner (``_COOKIE_BANNER_JS``) in the page or one of its
-        frames, at most ``BANNER_ANSWERS`` times per banner and page, never on the
-        school's or a federation's pages (``_school_or_federation_page``);
+        frames, at most ``BANNER_ANSWERS`` times per banner and page. The school's
+        and external federation pages stay protected; a publisher-owned chooser
+        may answer its own cookie prompt (``_school_or_federation_page``).
         ``blocking``: the banner covered a control the engine clicked. An
         advertisement over the page is closed first (``_close_advertisement_overlay``).
         True when either was done."""
@@ -1396,12 +1414,14 @@ class LoginMixin:
             pass
         for target in targets:
             where = str(getattr(target, "url", "") or "").split("#", 1)[0]
-            if self._school_or_federation_page(where, item):
+            if self._school_or_federation_page(where, item, include_publisher_chooser=False):
                 continue
             skip = [key for (url, key), count in answered.items() if url == where and count >= self.BANNER_ANSWERS]
             try:
                 clicked = target.evaluate(self._COOKIE_BANNER_JS, {"blocking": bool(blocking), "skip": skip})
-            except Exception:
+            except Exception as exc:
+                if not _is_browser_error(exc):
+                    raise
                 continue  # a frame gone meanwhile; the banner is a convenience, never the item's end
             if not isinstance(clicked, dict):
                 continue

package/carsi/paper_search_carsi/engine/batch_runs.py

@@ -610,13 +610,8 @@ class RunsMixin:
         if not any(kw in url_lower for kw in ("login", "cas", "sso", "signin", "sign-in")):
             return True
         # Check for SSO-specific indicators
-        try:
-            title = (page.title() or "").lower()
-            if any(kw in title for kw in ("登录成功", "welcome", "dashboard")):
-                return True
-        except Exception:
-            pass
-        return False
+        title = self._title(page).lower()
+        return any(kw in title for kw in ("登录成功", "welcome", "dashboard"))
 
     def _save_publisher_session(self, page: Any, result: DownloadResult) -> None:
         if not self.profile.base_domains:

package/carsi/paper_search_carsi/engine/batch_waits.py

@@ -7,12 +7,13 @@ from __future__ import annotations
 import inspect
 import re
 import time
+from contextlib import ExitStack
 from typing import Any
 from urllib.parse import urlparse
 
 from ..entitlements import UserMarkedNoEntitlement
-from .batch_common import (AWAY_WAIT_SEC, DownloadResult, _IP_BLOCK_STATUS_CODES, _observe_preview,
-                           looks_like_challenge)
+from ..browser import challenge_interaction, challenges, watchdog
+from .batch_common import (AWAY_WAIT_SEC, DownloadResult, _IP_BLOCK_STATUS_CODES, _observe_preview)
 
 
 class UserWaitMixin:
@@ -113,6 +114,10 @@ class UserWaitMixin:
     def _wait_out_suspect_block(self, page: Any, result: DownloadResult, captured: dict[str, Any], suspect: str,
                                 suspect_host: str, started: float) -> bool:
         deadline = started + self.page_wait_sec
+        automatic: dict[str, Any] = {}
+        interaction = ExitStack()
+        manual = False
+        state = ""
         reporter = None
         attention_key = f"pdf-step:{id(self)}:{result.doi}"
         try:
@@ -156,6 +161,8 @@ class UserWaitMixin:
                         if self._pdf_step_needs_login(candidate):
                             state, tab = "login", candidate
                             break
+                    except (watchdog.BrowserUnresponsive, UserMarkedNoEntitlement):
+                        raise
                     except Exception:
                         continue
                 if not state and time.time() - started < self.SUSPECT_UNKNOWN_GRACE_SEC:
@@ -167,8 +174,8 @@ class UserWaitMixin:
                         except Exception:
                             continue
                 if not state:
-                    if shown:
-                        self._event(result, "challenge_resolved", f"{shown} page gone")
+                    if shown or automatic:
+                        self._event(result, "challenge_resolved", f"{shown or 'verification'} page gone")
                     captured["suspect_block"] = None
                     return True  # the capture loop retries the PDF now
                 if state == "login" and tab == page:
@@ -179,6 +186,13 @@ class UserWaitMixin:
                     self._event(result, "pdf_step_login_required", str(getattr(page, "url", "") or ""))
                     captured["suspect_block"] = None
                     return False
+                if state == "verification":
+                    self._raise_on_publisher_access_blocked(tab)
+                    if not automatic:
+                        deadline = min(deadline, self._wait_deadline(result))
+                    if self._automatic_challenge_step(tab, result, automatic, deadline):
+                        page.wait_for_timeout(min(1000, max(0, (deadline - time.time()) * 1000)))
+                        continue
                 if state != shown:
                     if state in ("verification", "login"):
                         deadline = min(deadline, self._wait_deadline(result))
@@ -198,14 +212,19 @@ class UserWaitMixin:
                         except Exception:
                             pass
                     shown = state
+                if not manual:
+                    interaction.enter_context(watchdog.pause_operation())
+                    manual = True
                 try:
                     _observe_preview(page)  # what the user is asked to act on
-                    page.wait_for_timeout(1000)  # pump browser events while the user acts
+                    page.wait_for_timeout(min(1000, max(0, (deadline - time.time()) * 1000)))
+                except (watchdog.BrowserUnresponsive, UserMarkedNoEntitlement):
+                    raise
                 except Exception:
-                    time.sleep(1)
-            if shown in ("verification", "login"):
+                    time.sleep(min(1, max(0, deadline - time.time())))
+            if state in ("verification", "login"):
                 self._wait_ran_out(result)
-            if shown == "verification":
+            if state == "verification":
                 # The verification page stayed up: nobody completed it. That
                 # is a timeout, not evidence that the publisher blocked us.
                 captured["block_reason"] = "challenge_or_viewer_timeout"
@@ -215,6 +234,7 @@ class UserWaitMixin:
             self._event(result, "ip_blocked_response", f"{suspect} | no PDF after waiting ({shown or 'nothing shown'})")
             return False
         finally:
+            interaction.close()
             if shown and reporter is not None:
                 try:
                     reporter.clear_attention(attention_key)
@@ -327,8 +347,43 @@ class UserWaitMixin:
             result._user_wait_expired = True
             self._event(result, "user_wait_expired", "short wait" if self._user_away else "")
 
+    def _automatic_challenge_step(self, page: Any, result: DownloadResult,
+                                  attempt: dict[str, Any], deadline: float) -> bool:
+        """A short automatic phase inside the existing wait, shared by both entry points.
+
+        True means keep observing, never that verification passed. Each wait
+        allows at most three interactions, including failed clicks, without a
+        new budget. Observe for at least three seconds after each attempt.
+        """
+        now = time.time()
+        if not attempt:
+            attempt.update(started=now, attempts=0, retry_at=now + 2)
+            self._event(result, "challenge_wait", "automatic verification check")
+        # Live widgets may not ask for a click until ~14 s after navigation.
+        # Reserve up to 2 s for manual handling without extending short waits.
+        manual_reserve = min(2, max(0, deadline - attempt["started"]) * 0.2)
+        automatic_end = min(deadline - manual_reserve, attempt["started"] + 20)
+        if now >= automatic_end:
+            return False
+        if now >= attempt["retry_at"] and attempt["attempts"] < 3:
+            # Camoufox's native humanized move can take 1.5 s before mouse-down.
+            # Leave time for that action, still inside the original wait budget.
+            outcome = challenge_interaction.click_checkbox(
+                page, timeout_ms=min(2500, max(1, int((automatic_end - now) * 1000))),
+                checkpoint=lambda: self._check_user_decision(result, page),
+            )
+            if outcome != "absent":
+                attempt["attempts"] += 1
+                attempt["retry_at"] = time.time() + 3
+                self._event(result, "challenge_wait",
+                            f"checkbox {outcome}; attempt {attempt['attempts']}/3; awaiting verification")
+        return time.time() < automatic_end
+
     def _wait_for_challenge(self, page: Any, result: DownloadResult, *, deadline: float | None = None) -> bool:
         """Wait while a verification page is up, until ``_wait_deadline``."""
+        interaction = ExitStack()
+        automatic: dict[str, Any] = {}
+        manual = False
         wait_interval_sec = 1  # a cleared verification goes on within a second
         reporter = None
         attention_key = f"publisher-challenge:{id(self)}:{result.doi}"
@@ -352,6 +407,14 @@ class UserWaitMixin:
                     if not waited:
                         deadline = self._wait_deadline(result, deadline)
                         started, phase_before = time.time(), self._phase(result, "verification")
+                    waited = True
+                    result.state = "challenge_or_viewer_timeout"
+                    if time.time() >= deadline:
+                        break
+                    auto_pending = self._automatic_challenge_step(page, result, automatic, deadline)
+                    if not auto_pending and not manual:
+                        interaction.enter_context(watchdog.pause_operation())
+                        manual = True
                         self._event(result, "challenge_manual_wait", "complete verification in visible browser")
                         if not any(s["why"] == "waiting for the user: verification" for s in result.snapshots):
                             self._snapshot(page, result, "waiting for the user: verification")
@@ -363,10 +426,8 @@ class UserWaitMixin:
                                 phase="人工验证",
                             )
                             attention_open = True
-                    waited = True
-                    result.state = "challenge_or_viewer_timeout"
                     checks += 1
-                    self._event(result, "challenge_wait", str(checks))
+                    self._event(result, "challenge_wait", f"{'manual' if manual else 'automatic'} {checks}")
                     # Pump browser events while the user completes verification.
                     # Plain sleep can leave sync-API navigation state stale.
                     wait_ms = min(wait_interval_sec * 1000, max(0, (deadline - time.time()) * 1000))
@@ -389,6 +450,7 @@ class UserWaitMixin:
                 self._wait_ran_out(result)
             return passed
         finally:
+            interaction.close()
             if waited:
                 self._phase(result, phase_before or "open")
                 self._note_wait(result, "verification", started, "passed" if result.state != "challenge_or_viewer_timeout"
@@ -397,45 +459,23 @@ class UserWaitMixin:
                 reporter.clear_attention(attention_key)
 
     def _challenge_shell(self, page: Any) -> bool:
-        """A Cloudflare interstitial recognised from title and URL alone.
-
-        Scripts reading the challenge page (innerText, DOM queries) can make
-        Cloudflare fail and re-issue the check (``__cf_chl_rt_tk``) in a loop;
-        an untouched page passes. Callers waiting on a challenge use this and
-        nothing else.
-        """
+        """Read only URL/title while a verification interstitial is active."""
         try:
             url = str(getattr(page, "url", "") or "")
         except Exception:
             url = ""
-        return looks_like_challenge(url, self._title(page))
+        return challenges.looks_like_challenge(url, self._title(page))
 
     def _is_challenge_page(self, page: Any) -> bool:
+        """Apply engine block precedence before the independent recogniser.
+
+        Read lazily: an interstitial or crawl-prevention URL needs no body read;
+        an explicit publisher block must never turn into a verification wait.
+        """
         if self._challenge_shell(page):
             return True
         if self._publisher_access_blocked(page):
             return False
-        # Silverchair sites (OUP and others) send unusual traffic to their own
-        # reCAPTCHA page, /crawlprevention/governor?content=<the article> ("Validate
-        # User", 2026-11-01); it leads back to the article once the user passes it.
-        if "/crawlprevention/" in urlparse(str(getattr(page, "url", "") or "")).path.lower():
-            return True
-        haystack = f"{self._title(page)} {self._body_text(page, 1_200)}".lower()
-        direct_markers = (
-            "just a moment",
-            "attention required",
-            "verify you are human",
-            "checking your browser",
-            "are you a robot",
-            "please confirm you are a human",
-            "confirm that you are not a robot",
-        )
-        if any(marker in haystack for marker in direct_markers):
+        if challenges.is_challenge_path(str(getattr(page, "url", "") or "")):
             return True
-        return "cloudflare" in haystack and (
-            "ray id:" in haystack
-            or "security verification" in haystack
-            or "security service" in haystack
-            or "not a robot" in haystack
-            or "瀹夊叏楠岃瘉" in haystack
-        )
+        return challenges.has_challenge_text(self._title(page), self._body_text(page, 1_200))

package/carsi/paper_search_carsi/engine/bridge.py

@@ -36,6 +36,7 @@ _FAILURE_KINDS = {
     "publisher_content_error": ("publisher_content_error", "review_publisher_error"),
     "unsupported_platform": ("unsupported_platform", "review_publisher_error"),
     "browser_unresponsive": ("browser_unresponsive", "review_browser"),
+    "browser_operation_timeout": ("browser_operation_timeout", "review_browser"),
     "publisher_access_blocked": ("access_blocked", "review_access"),
     "publisher_unreachable": ("publisher_unreachable", "review_publisher_error"),
     "sso_required": ("paywall", "login_required"),
@@ -509,7 +510,8 @@ def _try_browser_batch_download(
         require_interactive_browser=True,
     )
 
-    run_dir = output_path.parent / ".browser_runs"
+    from uuid import uuid4
+    run_dir = Path(config.get("diagnostics_dir") or output_path.parent / "diagnostics") / uuid4().hex[:12]
     run_dir.mkdir(parents=True, exist_ok=True)
 
     log.info(f"   [Institutional] Browser batch download: {doi} via {profile.name}")
@@ -537,10 +539,10 @@ def _try_browser_batch_download(
             if watchdog.fired and not result.ok:
                 # The browser call never returned and the driver was stopped:
                 # whatever the engine reported after that is a consequence.
-                result.reason = result.state = "browser_unresponsive"
+                result.reason = result.state = watchdog.failure_code()
             if supplements_mode in ("with", "only"):
-                if result.state == "browser_unresponsive":
-                    result.supplements = [{"status": "skipped", "reason": "browser_unresponsive",
+                if result.state in ("browser_unresponsive", "browser_operation_timeout"):
+                    result.supplements = [{"status": "skipped", "reason": result.state,
                                            "url": "", "label": ""}]
                 elif result.state == "challenge_or_viewer_timeout":
                     # The verification page was never completed: the article
@@ -548,13 +550,16 @@ def _try_browser_batch_download(
                     result.supplements = [{"status": "skipped", "reason": "challenge_timeout",
                                            "url": "", "label": ""}]
                 elif result.state in ("unsupported_platform", "publisher_access_blocked", "publisher_unreachable",
-                                      "login_page_closed"):
+                                      "login_page_closed", "user_skipped", "batch_stopped",
+                                      "user_marked_no_entitlement"):
                     # Nothing more to fetch there now.
                     result.supplements = [{"status": "skipped", "reason": result.state,
                                            "url": "", "label": ""}]
                 else:
                     written = len(result.events)
-                    result.supplements = downloader.collect_supplements(context, doi, output_path.parent, result)
+                    result.supplements = downloader.collect_supplements(context, doi, output_path.parent, result, manifest_dir=run_dir)
+                    if supplements_mode == "only" and (run_dir / "manifest.json").is_file():
+                        result.record_path = str(run_dir / "manifest.json")
                     _note_supplements(result, written)
         finally:
             try:
@@ -577,6 +582,8 @@ def _try_browser_batch_download(
                 if output_path.exists():
                     output_path.unlink()
                 src.rename(output_path)
+            result.pdf_path = str(output_path)
+            _note_supplements(result, len(getattr(result, "events", [])))
             log.info(f"   [Institutional] Browser download succeeded: {result.size_bytes:,} bytes")
             return {
                 "success": True, "identifier": doi, "doi": doi,
@@ -618,8 +625,9 @@ def _note_supplements(result: Any, written: int) -> None:
         if not path.is_file():
             continue
         data = json.loads(path.read_text(encoding="utf-8"))
-        data["events"] = list(data.get("events") or []) + list(result.events[written:])
-        data["supplements"] = result.supplements
+        data["events"] = list(data.get("events") or []) + list(getattr(result, "events", [])[written:])
+        data["supplements"] = getattr(result, "supplements", [])
+        data["pdf_path"] = str(getattr(result, "pdf_path", "") or "")
         if getattr(result, "phases", None):
             data["phases"] = {k: round(float(v), 1) for k, v in result.phases.items()}
         path.write_text(json.dumps(data, ensure_ascii=False, indent=2), encoding="utf-8")

package/carsi/paper_search_carsi/engine/supplements.py

@@ -21,6 +21,8 @@ from typing import Any, Callable, Iterable
 from urllib.parse import unquote, urlparse
 
 from ..adapters.base import SupplementLink
+from ..browser.watchdog import BrowserUnresponsive, BrowserOperationTimeout
+from ..entitlements import UserMarkedNoEntitlement, UserSkippedArticle, UserStoppedBatch
 
 MAX_FILES = 50
 MAX_FILE_BYTES = 200 * 1024 * 1024
@@ -87,6 +89,8 @@ def _get(request: Any, url: str, entry: dict[str, Any], sleep) -> Any:
 
 def collect(request: Any, links: Iterable[SupplementLink], output_dir: Path, doi: str, *,
             clock=time.monotonic, sleep=time.sleep,
+            manifest_dir: Path | None = None,
+            target_dir: Path | None = None,
             download: Callable[[str], tuple[bytes, str]] | None = None,
             progress: Callable[[int], None] | None = None) -> list[dict[str, Any]]:
     """Fetch ``links`` with ``request`` (a Playwright APIRequestContext). A file
@@ -101,14 +105,19 @@ def collect(request: Any, links: Iterable[SupplementLink], output_dir: Path, doi
             unique.append(link)
     if not unique:
         return []
-    target = supplements_dir(output_dir, doi)
+    target = target_dir or supplements_dir(output_dir, doi)
     target.mkdir(parents=True, exist_ok=True)
     started = clock()
     taken: set[str] = set()
     files: list[dict[str, Any]] = []
+    stopped_reason = ""
     for index, link in enumerate(unique):
         entry: dict[str, Any] = {"url": link.url, "label": link.label}
-        if index >= MAX_FILES:
+        if stopped_reason:
+            entry.update(status="skipped", reason=stopped_reason)
+        elif link.error:
+            entry.update(status="failed", reason=link.error)
+        elif index >= MAX_FILES:
             entry.update(status="skipped", reason="file_limit")
         elif clock() - started > TIME_BUDGET_SEC:
             entry.update(status="skipped", reason="time_budget")
@@ -138,11 +147,21 @@ def collect(request: Any, links: Iterable[SupplementLink], output_dir: Path, doi
                         path.write_bytes(body)
                         entry.update(status="saved", file=str(path), size=len(body),
                                      content_type=content_type.split(";")[0].strip())
+            except (BrowserUnresponsive, UserMarkedNoEntitlement) as exc:
+                stopped_reason = ("batch_stopped" if isinstance(exc, UserStoppedBatch) else
+                                  "user_skipped" if isinstance(exc, UserSkippedArticle) else
+                                  "user_marked_no_entitlement" if isinstance(exc, UserMarkedNoEntitlement) else
+                                  "browser_operation_timeout" if isinstance(exc, BrowserOperationTimeout) else
+                                  "browser_unresponsive")
+                entry.update(status="skipped" if isinstance(exc, UserMarkedNoEntitlement) else "failed",
+                             reason=stopped_reason)
             except Exception as exc:
                 entry.update(status="failed", reason=f"{type(exc).__name__}: {str(exc)[:160]}")
         files.append(entry)
         if progress is not None:
             progress(sum(1 for f in files if f.get("status") == "saved"))
-    (target / "manifest.json").write_text(
+    manifest_target = manifest_dir or target
+    manifest_target.mkdir(parents=True, exist_ok=True)
+    (manifest_target / "manifest.json").write_text(
         json.dumps({"doi": doi, "files": files}, ensure_ascii=False, indent=2), encoding="utf-8")
     return files

package/carsi/paper_search_carsi/log.py

@@ -29,9 +29,8 @@ def _file_handler() -> logging.Handler | None:
 
 
 def enable_stack_dump() -> None:
-    """``kill -USR1 <pid>`` appends every thread's Python stack to
-    ``<data dir>/logs/stacks-<date>.txt``: a backend waiting forever on a browser
-    call (Camoufox, 2026-10-31) shows where it waits."""
+    """Prepare watchdog dumps on every OS; POSIX also supports ``kill -USR1``.
+    Stacks go to ``<data dir>/logs/stacks-<date>.txt``."""
     global _stack_file
     import faulthandler
     import os
@@ -39,15 +38,22 @@ def enable_stack_dump() -> None:
     from datetime import date
     from pathlib import Path
 
-    if _stack_file is not None or not hasattr(signal, "SIGUSR1") or os.environ.get("CARSI_FILE_LOG") == "0":
+    if _stack_file is not None or os.environ.get("CARSI_FILE_LOG") == "0":
         return
     try:
         log_dir = Path(os.environ.get("CARSI_DATA_DIR", str(Path.home() / ".local" / "share" / "paper-search-cli" / "carsi"))) / "logs"
         log_dir.mkdir(parents=True, exist_ok=True)
         _stack_file = open(log_dir / f"stacks-{date.today().isoformat()}.txt", "a", encoding="utf-8")
-        faulthandler.register(signal.SIGUSR1, file=_stack_file, all_threads=True)
-    except Exception:
-        _stack_file = None
+    except OSError:
+        get_logger().warning("Could not open the browser watchdog stack log")
+        return
+    # Windows has no SIGUSR1/register, but dump_traceback works there. A failed
+    # optional signal hook must not disable explicit watchdog dumps either.
+    if hasattr(signal, "SIGUSR1"):
+        try:
+            faulthandler.register(signal.SIGUSR1, file=_stack_file, all_threads=True)
+        except (OSError, RuntimeError, ValueError):
+            get_logger().warning("Stack log ready, but the SIGUSR1 hook is unavailable")
 
 
 def dump_stacks(reason: str) -> bool:

package/carsi/paper_search_carsi/orchestrator.py

@@ -32,6 +32,7 @@ def download_institutional(
     strategy: str | None = None,
     supplements: str | None = None,
     user_wait: str | None = None,
+    diagnostics_dir: str | None = None,
 ) -> dict[str, Any]:
     """Download one DOI through institutional access only.
 
@@ -66,6 +67,8 @@ def download_institutional(
         extra = {"supplements": supplements} if supplements in ("with", "only") else {}
         if user_wait == "short":
             extra["user_wait"] = user_wait
+        if diagnostics_dir:
+            extra["diagnostics_dir"] = diagnostics_dir
         return _download_impl(doi, output_dir, **extra)
     finally:
         with _INFLIGHT_LOCK:
@@ -73,7 +76,8 @@ def download_institutional(
 
 
 def _download_impl(doi: str, output_dir: str | Path | None, *,
-                   supplements: str | None = None, user_wait: str | None = None) -> dict[str, Any]:
+                   supplements: str | None = None, user_wait: str | None = None,
+                   diagnostics_dir: str | None = None) -> dict[str, Any]:
     config = load_config()
     if user_wait == "short":
         config["user_wait"] = "short"
@@ -82,6 +86,8 @@ def _download_impl(doi: str, output_dir: str | Path | None, *,
 
     target_dir = Path(output_dir) if output_dir else Path(config["output_dir"])
     target_dir.mkdir(parents=True, exist_ok=True)
+    if diagnostics_dir:
+        config["diagnostics_dir"] = str(Path(diagnostics_dir).resolve())
     output_path = target_dir / f"{safe_filename(doi)}.pdf"
 
     cached = cache_get(doi, config)