pyXcom 1.2.0__tar.gz → 1.2.1__tar.gz

{pyxcom-1.2.0 → pyxcom-1.2.1}/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 1.2.1 — 2026-10-13
+
+### Fixed
+
+- Retain comment cursors paused by the empty-page guard and support explicit
+  `retry_stalled=True` through the saver, CLI and pool resume.
+- Recover older discarded cursors only from hash-verified archives bound to the
+  last committed focal/cursor request, including after an ordinary resume.
+- Keep historical pagination warnings while reporting still-stalled and
+  unrecoverable branches separately; bounded retries may remain partial.
+
 ## 1.2.0 — 2026-10-12
 
 ### Added

{pyxcom-1.2.0 → pyxcom-1.2.1}/CITATION.cff

@@ -6,8 +6,8 @@ authors:
   - family-names: Wang
     given-names: Haocheng
     affiliation: Communication University of China
-version: 1.2.0
-date-released: 2026-10-12
+version: 1.2.1
+date-released: 2026-10-13
 license: Apache-2.0
 repository-code: "https://github.com/haochengw372-hash/pyXcom"
 url: "https://github.com/haochengw372-hash/pyXcom"

{pyxcom-1.2.0 → pyxcom-1.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pyXcom
-Version: 1.2.0
+Version: 1.2.1
 Summary: Collect public X posts, search results, conversations, reposts, and observed follow networks with your browser session
 Project-URL: Homepage, https://github.com/haochengw372-hash/pyXcom
 Project-URL: Repository, https://github.com/haochengw372-hash/pyXcom
@@ -411,7 +411,7 @@ These are offline development checks. They do not collect new X data.
 
 Created by **Haocheng Wang, Communication University of China**.
 
-[PykTok](https://github.com/dfreelon/pyktok) inspired the approachable get/save naming and task-by-task examples. pyXcom is an independent implementation and does not depend on PykTok or twikit.
+[PykTok](https://github.com/dfreelon/pyktok) inspired the approachable get/save naming and task-by-task examples. 
 
 ## Citation
 

{pyxcom-1.2.0 → pyxcom-1.2.1}/README.md

@@ -392,7 +392,7 @@ These are offline development checks. They do not collect new X data.
 
 Created by **Haocheng Wang, Communication University of China**.
 
-[PykTok](https://github.com/dfreelon/pyktok) inspired the approachable get/save naming and task-by-task examples. pyXcom is an independent implementation and does not depend on PykTok or twikit.
+[PykTok](https://github.com/dfreelon/pyktok) inspired the approachable get/save naming and task-by-task examples. 
 
 ## Citation
 

{pyxcom-1.2.0 → pyxcom-1.2.1}/docs/api.md

@@ -1,4 +1,4 @@
-# Public API — pyXcom 1.2.0
+# Public API — pyXcom 1.2.1
 
 The native discovery and network methods have passed offline tests and bounded authenticated live endpoint tests. These tests verify the exercised acquisition paths, not complete historical or network coverage.
 
@@ -81,6 +81,28 @@ Traversal depth is relative to the seed (direct replies=1), recorded as `seed_po
 
 For offline validation of `post_comments`, UTC date scope applies to analysis descendants, while the seed and explicitly marked context can lie outside it. These retained records still participate in identifier, relationship and artifact-integrity checks. The exemption does not apply to other collection types; a descendant missing `observation_role` is treated as analysis for this date check.
 
+### Retry a paused comment branch
+
+`save_post_comments(..., retry_stalled=True)` explicitly requeues cursors saved
+by the empty-page guard. Ordinary resume keeps these branches paused. Repeated
+cursor warnings and unresolved ancestors are still reported as partial.
+
+For older collections, an empty-page cursor is recovered only from a hash-checked
+raw response whose focal ID and request cursor match the last committed request.
+Missing or mismatched evidence remains unresolved; no cursor or tree depth is guessed.
+
+```python
+result = client.save_post_comments(
+    post_id, output_dir, max_depth=3, max_comments=100,
+    max_pages=2, retry_stalled=True,
+)
+```
+
+The manifest distinguishes queued requests, stalled requests, active warnings,
+and historical warnings. A retry can still return a partial result when the
+platform keeps returning empty pages. CLI: `pyxcom post-comments ID --output-dir
+DIR --retry-stalled`. Pool: `resume_job(job_id, retry_stalled=True)`.
+
 ## Keyword search
 
 ```python

{pyxcom-1.2.0 → pyxcom-1.2.1}/docs/pool.md

@@ -83,7 +83,7 @@ X's quota implementation. Requests already in flight cannot be recalled.
 
 Reopen the same `state_dir` with the same login IDs and call `run` again. Re-adding
 an identical job is harmless; changing its query, scope, or observer is rejected.
-Use `resume_job(job_id)` for a paused job. Explicit discovery-stall retries use
+Use `resume_job(job_id)` for a paused job. Explicit discovery or comment empty-page retries use
 `resume_job(job_id, retry_stalled=True)` where the underlying saver supports it.
 
 Adopting existing output requires both a pinned `login_id` and

{pyxcom-1.2.0 → pyxcom-1.2.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pyXcom"
-version = "1.2.0"
+version = "1.2.1"
 description = "Collect public X posts, search results, conversations, reposts, and observed follow networks with your browser session"
 readme = "README.md"
 license = "Apache-2.0"

{pyxcom-1.2.0 → pyxcom-1.2.1}/src/pyxcom/__init__.py

@@ -50,4 +50,4 @@ __all__ = [
     "validate_collection",
     "validate_network_collection",
 ]
-__version__ = "1.2.0"
+__version__ = "1.2.1"

{pyxcom-1.2.0 → pyxcom-1.2.1}/src/pyxcom/cli.py

@@ -251,6 +251,7 @@ def build_parser() -> argparse.ArgumentParser:
         help="Collect replies below a post or reply, including nested replies",
     )
     comments.add_argument("post_id_or_url")
+    comments.add_argument("--retry-stalled", action="store_true", help="Explicitly retry saved comment cursors paused by empty-page guard")
     comments.add_argument("--max-depth", type=_depth, default=2)
     comments.add_argument("--max-comments", type=_budget, default=100)
     comments.add_argument("--max-pages", type=_budget, default=20)
@@ -576,6 +577,7 @@ def main(argv: list[str] | None = None) -> int:
                     max_pages=args.max_pages,
                     since=args.since,
                     until=args.until,
+                    **({"retry_stalled": True} if args.retry_stalled else {}),
                 )
                 print(json.dumps(result.to_dict(), ensure_ascii=False))
             elif args.command in ("search-query", "post-quotes", "user-reposts"):

{pyxcom-1.2.0 → pyxcom-1.2.1}/src/pyxcom/client.py

@@ -968,9 +968,10 @@ class XClient(DiscoveryMixin, NetworkMixin):
         max_pages: int | None = 20,
         since: str | None = None,
         until: str | None = None,
+        retry_stalled: bool = False,
     ) -> CollectionResult:
         """Save a root post, its reply tree and observed author profiles; resume safely."""
-        from .comments import CommentTraversal
+        from .comments import CommentTraversal, restore_archived_stalls
 
         root_id = _post_id(post_id_or_url)
         # Validate bounds before creating or migrating output.
@@ -982,6 +983,7 @@ class XClient(DiscoveryMixin, NetworkMixin):
             max_pages=max_pages,
             since=since,
             until=until,
+            retry_stalled=retry_stalled,
         )
         store = PostStore(
             output_dir,
@@ -994,6 +996,8 @@ class XClient(DiscoveryMixin, NetworkMixin):
         )
         if store.complete:
             return store.finish(complete=True, reason=store.state["reason"])
+        if retry_stalled:
+            restore_archived_stalls(store)
         traversal = CommentTraversal(
             self,
             root_id,
@@ -1004,6 +1008,7 @@ class XClient(DiscoveryMixin, NetworkMixin):
             until=until,
             records=store._posts,
             state=store.state.setdefault("conversation", {}),
+            retry_stalled=retry_stalled,
         )
 
         def save_profiles():

{pyxcom-1.2.0 → pyxcom-1.2.1}/src/pyxcom/comments.py

@@ -1,11 +1,14 @@
 """Bounded, resumable traversal of public replies to an X post or reply seed."""
 
 import time
+import json
+import hashlib
 from dataclasses import replace
 from datetime import date
 from typing import TYPE_CHECKING, Iterator
 
-from .errors import ParseError, RateLimitError
+from .errors import IntegrityError, ParseError, RateLimitError
+from ._persistence import read_jsonl
 from .models import Post
 from .parse import _walk, parse_post, parse_profile
 from .transport import now_utc
@@ -80,6 +83,71 @@ def parse_conversation(data: dict) -> tuple[list[Post], list[str], dict]:
     return list(posts.values()), list(dict.fromkeys(cursors)), profiles
 
 
+def restore_archived_stalls(store) -> None:
+    """Recover legacy dropped frontiers from exact, verified response artifacts.
+
+    Called only for explicit retry. Missing evidence remains an unresolved stop;
+    no cursor is guessed and no existing post or raw artifact is rewritten.
+    """
+    state = store.state.get("conversation", {})
+    if (
+        state.get("stalled_queue")
+        or state.get("legacy_stall_recovery") is not None
+        or "empty_page_limit" not in state.get("pagination_warnings", [])
+    ):
+        return
+    affected = {
+        focal for focal, count in state.get("empty_pages", {}).items() if count >= 2
+    }
+    latest = {}
+    last_visited = {task[0]: task for task in state.get("visited", [])}
+    log_path = store.output_dir / ".pyxcom" / "collection_log.jsonl"
+    for record in read_jsonl(log_path) if log_path.exists() else ():
+        if record.get("operation") == "TweetDetail":
+            focal = record.get("variables", {}).get("focalTweetId")
+            request_cursor = record.get("variables", {}).get("cursor")
+            if focal in affected and last_visited.get(focal) == [focal, request_cursor]:
+                latest[focal] = record
+    recovered: list[dict] = []
+    unresolved: list[str] = []
+    for focal in sorted(affected):
+        archived = latest.get(focal)
+        if (
+            not archived
+            or not archived.get("raw_path")
+            or not archived.get("raw_sha256")
+        ):
+            unresolved.append(focal)
+            continue
+        path = (store.output_dir / archived["raw_path"]).resolve()
+        if not path.is_relative_to((store.output_dir / ".pyxcom" / "raw").resolve()):
+            raise IntegrityError(
+                "Comment retry archive must remain inside the raw directory"
+            )
+        raw = path.read_bytes()
+        if hashlib.sha256(raw).hexdigest() != archived["raw_sha256"]:
+            raise IntegrityError("Comment retry archive changed")
+        _, cursors, _ = parse_conversation(json.loads(raw))
+        tasks = [
+            [focal, cursor]
+            for cursor in cursors
+            if [focal, cursor] not in state.get("visited", [])
+            and [focal, cursor] not in state.get("queue", [])
+        ]
+        if not tasks:
+            unresolved.append(focal)
+        recovered.extend(
+            {"focal_id": task[0], "cursor": task[1], "reason": "empty_page_limit"}
+            for task in tasks
+        )
+    state["stalled_queue"] = recovered
+    state["unrecoverable_stalled_focals"] = unresolved
+    state["legacy_stall_recovery"] = {
+        "restored": len(recovered),
+        "unresolved": len(unresolved),
+    }
+
+
 class CommentTraversal:
     def __init__(
         self,
@@ -93,7 +161,10 @@ class CommentTraversal:
         state: dict | None = None,
         since: str | None = None,
         until: str | None = None,
+        retry_stalled: bool = False,
     ):
+        if not isinstance(retry_stalled, bool):
+            raise ValueError("retry_stalled must be boolean")
         if max_depth is None:
             raise ValueError("max_depth must be a positive integer")
         for name, value in (
@@ -138,6 +209,28 @@ class CommentTraversal:
             ],
         )
         self.state.setdefault("excluded_ids", [])
+        self.state.setdefault("stalled_queue", [])
+        self.state.setdefault("pagination_warning_history", [])
+        if retry_stalled and self.state["stalled_queue"]:
+            for task in self.state["stalled_queue"]:
+                if task["reason"] != "empty_page_limit":
+                    continue
+                follow = [task["focal_id"], task["cursor"]]
+                if follow not in self.state["queue"]:
+                    self.state["queue"].append(follow)
+                self.state["empty_pages"][task["focal_id"]] = 0
+                self.state["pagination_warning_history"].append(task["reason"])
+            self.state["stalled_queue"] = [
+                task
+                for task in self.state["stalled_queue"]
+                if task["reason"] != "empty_page_limit"
+            ]
+            if not self.state.get("unrecoverable_stalled_focals"):
+                self.state["pagination_warnings"] = [
+                    reason
+                    for reason in self.state["pagination_warnings"]
+                    if reason != "empty_page_limit"
+                ]
         self.latest_payload: dict | None = None
         self.latest_request: dict | None = None
         self.latest_response_number = 0
@@ -252,7 +345,11 @@ class CommentTraversal:
             if not self.state["queue"]:
                 unresolved = len(self.state["pending"])
                 self.state["unresolved_count"] = unresolved
-                self.complete = not unresolved and not self.state["pagination_warnings"]
+                self.complete = (
+                    not unresolved
+                    and not self.state["pagination_warnings"]
+                    and not self.state["stalled_queue"]
+                )
                 self.reason = (
                     "visible_source_end" if self.complete else "partial_conversation"
                 )
@@ -300,6 +397,13 @@ class CommentTraversal:
                     self.state["pagination_warnings"].append("repeated_cursor")
                 elif self.state["empty_pages"][focal] >= 2:
                     self.state["pagination_warnings"].append("empty_page_limit")
+                    paused = {
+                        "focal_id": focal,
+                        "cursor": next_cursor,
+                        "reason": "empty_page_limit",
+                    }
+                    if paused not in self.state["stalled_queue"]:
+                        self.state["stalled_queue"].append(paused)
                 elif follow not in self.state["queue"]:
                     self.state["queue"].append(follow)
             self.pages_fetched += 1

{pyxcom-1.2.0 → pyxcom-1.2.1}/src/pyxcom/pool.py

@@ -424,6 +424,7 @@ class XClientPool:
             "search_query",
             "post_quotes",
             "user_reposts",
+            "post_comments",
         }:
             raise ValueError("This collector does not support retry_stalled")
         job.update(status="pending", retry_stalled=retry_stalled)

{pyxcom-1.2.0 → pyxcom-1.2.1}/src/pyxcom/tables.py

@@ -184,6 +184,7 @@ def _depths(records: dict[str, Post]) -> dict[str, tuple[int | None, str]]:
 def export_tables(output_dir: str | Path) -> dict:
     """Rebuild verified public tables under an exclusive collection scope lock."""
     from .provenance import collection_write_guard
+
     with collection_write_guard(output_dir):
         return _export_tables_verified(output_dir)
 
@@ -452,6 +453,11 @@ def _export_tables_unchecked(output_dir: str | Path) -> dict:
         manifest["comment_collection"] = {
             "max_depth": manifest["query"]["max_depth"],
             "pending_requests": len(state.get("queue", [])),
+            "stalled_requests": len(state.get("stalled_queue", [])),
+            "unrecoverable_stalled_focals": len(
+                state.get("unrecoverable_stalled_focals", [])
+            ),
+            "pagination_warning_history": state.get("pagination_warning_history", []),
             "unresolved_or_deferred_records": len(state.get("pending", {})),
             "pagination_warnings": sorted(set(state.get("pagination_warnings", []))),
             "depth_counts": {

pyxcom-1.2.1/tests/test_comment_stalls.py

@@ -0,0 +1,258 @@
+import json
+import tempfile
+import unittest
+from pathlib import Path
+
+from test_comments import ROOT, A, B, C, client, page, tweet, traversal
+from pyxcom.storage import PostStore
+
+
+class CommentStallTests(unittest.TestCase):
+    def stalled(self):
+        c = client(
+            page(tweet(A, ROOT), cursor="c1"), page(cursor="c2"), page(cursor="c3")
+        )
+        t = traversal(c, max_depth=3)
+        list(t.pages())
+        return c, t
+
+    def test_stalled_cursor_is_retained_and_default_resume_does_not_retry(self):
+        c, t = self.stalled()
+        self.assertEqual(
+            t.state["stalled_queue"],
+            [{"focal_id": ROOT, "cursor": "c3", "reason": "empty_page_limit"}],
+        )
+        c._x.conversation_page.reset_mock()
+        resumed = traversal(c, records=t.records, state=t.state, max_depth=3)
+        list(resumed.pages())
+        c._x.conversation_page.assert_not_called()
+        self.assertFalse(resumed.complete)
+
+    def test_explicit_retry_resumes_same_cursor_and_resolves_nested_records(self):
+        c, t = self.stalled()
+        c._x.conversation_page.reset_mock()
+        c._x.conversation_page.side_effect = [page(tweet(B, A), tweet(C, B))]
+        resumed = traversal(
+            c, records=t.records, state=t.state, max_depth=3, retry_stalled=True
+        )
+        list(resumed.pages())
+        c._x.conversation_page.assert_called_once_with(ROOT, cursor="c3")
+        self.assertEqual(set(resumed.records), {ROOT, A, B, C})
+        self.assertEqual(resumed.state["depths"][C], 3)
+        self.assertTrue(resumed.complete)
+        self.assertEqual(resumed.state["stalled_queue"], [])
+        self.assertIn("empty_page_limit", resumed.state["pagination_warning_history"])
+
+    def test_retry_that_stalls_again_retains_new_cursor_and_does_not_loop(self):
+        c, t = self.stalled()
+        c._x.conversation_page.reset_mock()
+        c._x.conversation_page.side_effect = [page(cursor="c4"), page(cursor="c5")]
+        resumed = traversal(
+            c, records=t.records, state=t.state, max_depth=3, retry_stalled=True
+        )
+        list(resumed.pages())
+        self.assertEqual(c._x.conversation_page.call_count, 2)
+        self.assertFalse(resumed.complete)
+        self.assertEqual(resumed.state["stalled_queue"][0]["cursor"], "c5")
+
+    def test_old_saved_empty_page_stop_can_resume_from_archived_exact_cursor(self):
+        with tempfile.TemporaryDirectory() as folder:
+            c = client(
+                page(tweet(A, ROOT), cursor="c1"), page(cursor="c2"), page(cursor="c3")
+            )
+            c.save_post_comments(
+                ROOT, folder, max_depth=3, max_comments=100, max_pages=5
+            )
+            store = PostStore(
+                folder,
+                query={"kind": "post_comments", "root_post_id": ROOT, "max_depth": 3},
+            )
+            store.state["conversation"].pop("stalled_queue", None)
+            store.finish(complete=False, reason="partial_conversation")
+            original_bytes = (Path(folder) / ".pyxcom/posts.jsonl").read_bytes()
+            c._x.conversation_page.reset_mock()
+            c._x.conversation_page.side_effect = [page(tweet(B, A))]
+            result = c.save_post_comments(
+                ROOT, folder, max_depth=3, max_pages=1, retry_stalled=True
+            )
+            c._x.conversation_page.assert_called_once_with(ROOT, cursor="c3")
+            self.assertEqual(result.post_count, 3)
+            self.assertTrue(
+                (Path(folder) / ".pyxcom/posts.jsonl")
+                .read_bytes()
+                .startswith(original_bytes)
+            )
+            manifest = json.loads((Path(folder) / "manifest.json").read_text())
+            self.assertEqual(manifest["comment_collection"]["stalled_requests"], 0)
+
+    def test_old_default_resume_does_not_prevent_later_explicit_retry(self):
+        with tempfile.TemporaryDirectory() as folder:
+            c = client(
+                page(tweet(A, ROOT), cursor="c1"), page(cursor="c2"), page(cursor="c3")
+            )
+            c.save_post_comments(ROOT, folder, max_depth=3, max_pages=5)
+            store = PostStore(
+                folder,
+                query={"kind": "post_comments", "root_post_id": ROOT, "max_depth": 3},
+            )
+            store.state["conversation"].pop("stalled_queue")
+            store.finish(complete=False, reason="partial_conversation")
+            c._x.conversation_page.reset_mock()
+            c.save_post_comments(ROOT, folder, max_depth=3, max_pages=1)
+            c._x.conversation_page.assert_not_called()
+            c._x.conversation_page.side_effect = [page(tweet(B, A))]
+            c.save_post_comments(
+                ROOT, folder, max_depth=3, max_pages=1, retry_stalled=True
+            )
+            c._x.conversation_page.assert_called_once_with(ROOT, cursor="c3")
+
+
+class CommentStallIntegrationTests(unittest.TestCase):
+    def test_legacy_missing_archive_keeps_stop_unresolved(self):
+        from types import SimpleNamespace
+        from pyxcom.comments import restore_archived_stalls
+
+        with tempfile.TemporaryDirectory() as folder:
+            state = {
+                "queue": [],
+                "visited": [],
+                "empty_pages": {ROOT: 2},
+                "pagination_warnings": ["empty_page_limit"],
+            }
+            store = SimpleNamespace(
+                output_dir=Path(folder), state={"conversation": state}
+            )
+            restore_archived_stalls(store)
+            self.assertEqual(state["stalled_queue"], [])
+            self.assertEqual(state["unrecoverable_stalled_focals"], [ROOT])
+            c = client()
+            t = traversal(
+                c, records={ROOT: c.get_post(ROOT)}, state=state, retry_stalled=True
+            )
+            list(t.pages())
+            self.assertFalse(t.complete)
+            c._x.conversation_page.assert_not_called()
+
+    def test_rate_limit_preserves_explicit_retry_task(self):
+        from pyxcom import RateLimitError
+
+        c, t = CommentStallTests().stalled()
+        c._x.conversation_page.side_effect = [RateLimitError("limited")]
+        resumed = traversal(c, records=t.records, state=t.state, retry_stalled=True)
+        list(resumed.pages())
+        self.assertEqual(resumed.reason, "rate_limited")
+        self.assertEqual(resumed.state["queue"], [[ROOT, "c3"]])
+        self.assertFalse(resumed.complete)
+
+    def test_cli_forwards_explicit_comment_retry(self):
+        import contextlib
+        import io
+        from unittest.mock import patch, MagicMock
+        from pyxcom.cli import main
+
+        with tempfile.TemporaryDirectory() as directory:
+            factory = MagicMock()
+            saved = factory.return_value.__enter__.return_value.save_post_comments
+            saved.return_value.to_dict.return_value = {"complete": False}
+            with (
+                patch("pyxcom.cli.XClient", factory),
+                contextlib.redirect_stdout(io.StringIO()),
+            ):
+                code = main(
+                    [
+                        "post-comments",
+                        ROOT,
+                        "--output-dir",
+                        directory,
+                        "--retry-stalled",
+                    ]
+                )
+            self.assertEqual(code, 0)
+            self.assertTrue(saved.call_args.kwargs["retry_stalled"])
+
+
+class CommentRetryBindingTests(unittest.TestCase):
+    def test_wrong_or_older_request_cursor_is_not_recovered(self):
+        from types import SimpleNamespace
+        import hashlib
+        from pyxcom.comments import restore_archived_stalls
+
+        for logged_cursor, focal in [
+            ("never-requested", ROOT),
+            ("earlier", ROOT),
+            ("last", A),
+        ]:
+            with (
+                self.subTest(cursor=logged_cursor, focal=focal),
+                tempfile.TemporaryDirectory() as folder,
+            ):
+                path = Path(folder)
+                raw = path / ".pyxcom/raw"
+                raw.mkdir(parents=True)
+                payload = json.dumps(page(cursor="unbound-next")).encode()
+                (raw / "page.json").write_bytes(payload)
+                record = {
+                    "operation": "TweetDetail",
+                    "variables": {"focalTweetId": focal, "cursor": logged_cursor},
+                    "raw_path": ".pyxcom/raw/page.json",
+                    "raw_sha256": hashlib.sha256(payload).hexdigest(),
+                }
+                (path / ".pyxcom/collection_log.jsonl").write_text(
+                    json.dumps(record) + "\n"
+                )
+                state = {
+                    "pagination_warnings": ["empty_page_limit"],
+                    "empty_pages": {ROOT: 2},
+                    "visited": [[ROOT, "earlier"], [ROOT, "last"]],
+                    "queue": [],
+                }
+                restore_archived_stalls(
+                    SimpleNamespace(output_dir=path, state={"conversation": state})
+                )
+                self.assertEqual(state["stalled_queue"], [])
+                self.assertEqual(state["unrecoverable_stalled_focals"], [ROOT])
+
+    def test_pool_resume_forwards_comment_retry_and_keeps_observer(self):
+        from unittest.mock import patch
+        from test_pool import FakeClient
+        from pyxcom import XClientPool, LoginConfig, CollectionJob
+        from pyxcom.models import CollectionResult
+
+        calls = []
+        c = FakeClient("100")
+
+        def comments(
+            target,
+            output,
+            *,
+            max_pages=None,
+            max_depth=2,
+            max_comments=100,
+            retry_stalled=False,
+        ):
+            calls.append(retry_stalled)
+            return CollectionResult(
+                Path(output),
+                3 if retry_stalled else 2,
+                len(calls),
+                retry_stalled,
+                "visible_source_end" if retry_stalled else "partial_conversation",
+            )
+
+        c.save_post_comments = comments
+        with (
+            tempfile.TemporaryDirectory() as tmp,
+            patch("pyxcom.pool.XClient.from_login", return_value=c),
+        ):
+            with XClientPool(
+                [LoginConfig("a", profile="A")], state_dir=Path(tmp) / "queue"
+            ) as pool:
+                pool.add_job(
+                    CollectionJob("root", "post_comments", ROOT, Path(tmp) / "tree")
+                )
+                pool.run(max_steps=1)
+                pool.resume_job("root", retry_stalled=True)
+                final = pool.run(max_steps=1)
+                self.assertEqual(final["jobs"]["root"]["observer_id"], "100")
+                self.assertEqual(final["jobs"]["root"]["status"], "complete")
+        self.assertEqual(calls, [False, True])