Apply failure-status fix to --check-status; track new Facebook posts

Two more Codex findings, both real follow-ups to fixes made earlier
this round:

1. The FAILED-status fix (raising instead of silently reporting
   "uploaded") only applied to publish_tiktok()'s immediate post-upload
   check, not to check_publish_status() -- exactly the documented
   `--check-status` recovery path a user is told to use INSTEAD of
   retrying a real publish blind. Extracted the shared logic into
   _raise_on_terminal_failure() so both call sites behave identically.
   A caller using the safe, recommended tool to check an uncertain
   result must not be told a failed post "succeeded" either.

2. auth/publish_facebook.py's article-scoped verification (this
   round's earlier fix) narrowed false positives from the profile
   bio/nav text, but could still match an OLDER post with similar
   leading text -- a repeated caption, or a common generic opening.
   Fixed by snapshotting the profile timeline's existing posts before
   submitting anything (_find_profile_url extracted, plus a new
   _article_fingerprints helper), then only counting a match in a post
   that's genuinely new since that snapshot.

Added 2 tests for check_publish_status's FAILED/processing paths (no
direct unit test for the Facebook browser-flow change itself --
consistent with how every other browser-driven publisher here is
tested, via the shared dry-run safe-defaults suite, not by mocking
Playwright internals). No live TikTok/Facebook API calls, no account
access -- same as every other fix in this PR. 149 tests pass (was 147),
compileall clean, git diff --check clean.

Author: tradewithmeai

.claude/skills/publish-facebook/SKILL.md

@@ -33,9 +33,13 @@ to know its real character limits or rendering quirks. Keep posts short and simp
 run says otherwise.
 
 Verify after posting: reload the profile timeline and match on text unique to the post. The
-result dict's own `"verified"` field already tries this automatically (it revisits the profile and
-searches the rendered page text), but its `"verify_note"` says plainly when it couldn't confirm --
-treat that as "check by hand," not as a failure on its own.
+result dict's own `"verified"` field already tries this automatically -- it snapshots the profile
+timeline's existing posts *before* submitting anything, then afterward only counts a match in a
+post that's genuinely new since that snapshot, not just any post containing similar text (an older
+post with the same generic opening line would otherwise false-positive). Still not a unique post
+ID -- two genuinely new posts with identical leading text in the same run could still confuse it --
+so its `"verify_note"` says plainly when it couldn't confirm; treat that as "check by hand," not as
+a failure on its own.
 
 ## Guardrails
 

.claude/skills/publish-tiktok/SKILL.md

@@ -81,8 +81,10 @@ assume the post is stuck private forever.
   own `"status"` field distinguishes this now -- `"published"` means TikTok's status check
   reported `PUBLISH_COMPLETE`, `"processing"` means it hadn't finished yet as of that check (use
   `--check-status` to follow up), and a terminal `FAILED` status raises an error with TikTok's own
-  `fail_reason` instead of silently returning either of those. Don't trust a bare `publish_id`
-  alone as proof of success.
+  `fail_reason` instead of silently returning either of those. This applies identically to
+  `--check-status` itself, not just the initial publish call -- the documented "check instead of
+  retrying" recovery path won't tell you a failed post "succeeded" either. Don't trust a bare
+  `publish_id` alone as proof of success.
 - **Token expired and refresh fails**: `profiles/tiktok/client_secret.json` must still exist (not
   just `token.json`) for a refresh to succeed -- see `onboard-tiktok`'s known failures.
 - **The connected TikTok account gets reset/wiped after several real publish attempts in a short

CHANGELOG.md

@@ -35,7 +35,7 @@ that will firm up once it leaves beta. Dates are when a release was tagged, not
     safe-by-default test suite; added a dedicated TikTok OAuth check group to `doctor.py`
     (`python doctor.py --tiktok`). Still safe by default either way -- `--confirm-publish` is
     required for a real publish on both, exactly as for every other platform.
-  - **Seven further issues found by code review before any live retest, none of them guessed:**
+  - **Nine further issues found by code review before any live retest, none of them guessed:**
     (1) `auth/publish_facebook.py` never forced its browser context to English like every other
     publisher does -- fixed with the same `FORCE_ENGLISH_LOCALE` constant. (2) The documented
     `--client-secrets path/to/tiktok_client.json` setup form silently broke every token refresh
@@ -68,7 +68,16 @@ that will firm up once it leaves beta. Dates are when a release was tagged, not
     against the flags it sends before publishing -- confirmed against TikTok's public docs that
     the `creator_info/query` endpoint exposes this, but fixing it properly needs a live account to
     confirm what the init endpoint actually does when a flag doesn't match, so it's left as an
-    explicit, documented gap rather than guessed.
+    explicit, documented gap rather than guessed. (8) The FAILED-status fix above was applied to
+    `publish_tiktok()`'s immediate post-upload check but not to `check_publish_status()` --
+    exactly the documented `--check-status` recovery path a user is told to use *instead* of
+    retrying blind. Extracted the shared validation into `_raise_on_terminal_failure()` so both
+    call sites behave identically; that recovery path won't tell you a failed post "succeeded"
+    either now. (9) `auth/publish_facebook.py`'s article-scoped verification (added earlier this
+    round) narrowed false positives from the profile bio/nav text, but could still match an
+    *older* post with similar leading text (a repeated caption, or a common generic opening).
+    Fixed by snapshotting the profile timeline's existing posts before submitting anything, then
+    only counting a match in a post that's genuinely new since that snapshot.
 - **YouTube's upload category is no longer hardcoded.** `auth/publish_youtube.py` gained
   `--category-id` (default unchanged: `22`, People & Blogs) -- closes a previously-documented
   defect in the upload path.

auth/publish_facebook.py

@@ -81,6 +81,36 @@ def _dismiss_cookie_banner(page) -> None:
         pass
 
 
+def _find_profile_url(page) -> str | None:
+    """Find the user's own profile link dynamically, the same approach already used for
+    LinkedIn -- read `.href` (resolved absolute URL), not getAttribute('href'). Facebook's left
+    rail (and this nav link) persists across pages, so this works from the home feed too, not
+    just the profile page itself -- used both before posting (to snapshot existing articles) and
+    after (to verify)."""
+    return page.evaluate("""() => {
+        const link = document.querySelector('a[aria-label="Your profile"]')
+            || document.querySelector('a[href*="/profile.php?id="]')
+            || document.querySelector('div[data-pagelet="LeftRail"] a[role="link"]');
+        return link ? link.href : null;
+    }""")
+
+
+_ARTICLE_FINGERPRINT_PREFIX_LENGTH = 80
+
+
+def _article_fingerprints(page) -> list[str]:
+    """Snapshot every `[role="article"]` (Facebook's own ARIA role for a feed/timeline post)
+    currently on the page, as a short text prefix each -- used to tell a genuinely NEW post
+    (one that wasn't in an earlier snapshot) apart from an older post that happens to start with
+    similar text. Not a unique post ID (unverified against a live account like everything else in
+    this file), just a much narrower fingerprint than the article's full text."""
+    return page.evaluate(
+        """(prefixLen) => [...document.querySelectorAll('[role="article"]')]
+            .map(article => (article.innerText || '').slice(0, prefixLen))""",
+        _ARTICLE_FINGERPRINT_PREFIX_LENGTH,
+    )
+
+
 def _open_composer(page) -> bool:
     """Click the "What's on your mind?" opener on the home feed. The visible text includes the
     logged-in user's own first name (e.g. "What's on your mind, Alex?"), so this matches on the
@@ -193,6 +223,23 @@ def publish_facebook(
             page.wait_for_timeout(2000)
             _dismiss_cookie_banner(page)
 
+            # Snapshot the profile timeline's existing posts BEFORE submitting anything -- this
+            # is what makes the later verification step check for a genuinely NEW post rather
+            # than matching an older one with similar leading text (Codex-reported: scoping the
+            # match to `[role="article"]` alone narrows out bio/nav-text false positives, but an
+            # older post starting with the same ~40 characters -- a repeated caption, or a common
+            # generic opening -- would still false-positive "verified"). Best-effort: if the
+            # profile link isn't found yet (still unverified selector), verification below just
+            # falls back to no before-snapshot rather than failing the whole publish over it.
+            profile_url = _find_profile_url(page)
+            existing_article_fingerprints: set[str] = set()
+            if profile_url:
+                page.goto(profile_url, timeout=STEP_TIMEOUT_MS)
+                page.wait_for_timeout(3000)
+                existing_article_fingerprints = set(_article_fingerprints(page))
+                page.goto("https://www.facebook.com/", timeout=STEP_TIMEOUT_MS)
+                page.wait_for_timeout(2000)
+
             if not _open_composer(page):
                 screenshot_path = _save_debug_screenshot(page)
                 raise RuntimeError(
@@ -281,34 +328,34 @@ def publish_facebook(
                     + (f"Screenshot saved to {screenshot_path}." if screenshot_path else "")
                 )
 
-            # Find the user's own profile link dynamically, the same approach already used for
-            # LinkedIn -- read `.href` (resolved absolute URL), not getAttribute('href').
-            profile_url = page.evaluate("""() => {
-                const link = document.querySelector('a[aria-label="Your profile"]')
-                    || document.querySelector('a[href*="/profile.php?id="]')
-                    || document.querySelector('div[data-pagelet="LeftRail"] a[role="link"]');
-                return link ? link.href : null;
-            }""")
+            # Re-resolve profile_url here too, in case it wasn't found in the earlier
+            # before-snapshot step (best-effort there) but is findable now.
+            if not profile_url:
+                profile_url = _find_profile_url(page)
 
             verified = False
             if profile_url:
                 snippet = text[:40]
                 page.goto(profile_url, timeout=STEP_TIMEOUT_MS)
                 page.wait_for_timeout(4000)
                 for attempt in range(3):
-                    # Scoped to `[role="article"]` (Facebook's own ARIA role for a feed post),
-                    # not the whole page -- a bare document.body.innerText.includes() check would
-                    # also match the snippet in the profile bio, nav text, or an older post,
-                    # falsely reporting a post as verified when the new one never actually
-                    # appeared. Still unverified against a live account like everything else in
-                    # this file -- this narrows the false-positive surface, it doesn't eliminate
-                    # every way this selector could be wrong.
-                    match = page.evaluate(
-                        """(snippet) => [...document.querySelectorAll('[role="article"]')]
-                            .some(article => (article.innerText || '').includes(snippet))""",
-                        snippet,
-                    )
-                    if match:
+                    # Codex-reported, in two parts. First: a bare
+                    # document.body.innerText.includes() check would also match the snippet in
+                    # the profile bio or nav text -- fixed by scoping to `[role="article"]`
+                    # (Facebook's own ARIA role for a feed post). Second: scoping to articles
+                    # alone still doesn't prove the match is the post just made, not an older one
+                    # starting with similar text (a repeated caption, or a common generic
+                    # opening) -- fixed by comparing against the before-snapshot taken earlier
+                    # and only counting a match in an article that's NEW since then. Still
+                    # unverified against a live account like everything else in this file -- this
+                    # narrows the false-positive surface further, it doesn't eliminate every way
+                    # this could be wrong (e.g. two genuinely new posts with identical leading
+                    # text in the same run).
+                    current_fingerprints = _article_fingerprints(page)
+                    new_fingerprints = [
+                        fp for fp in current_fingerprints if fp not in existing_article_fingerprints
+                    ]
+                    if any(snippet in fp for fp in new_fingerprints):
                         verified = True
                         break
                     page.mouse.wheel(0, 4000)

auth/publish_tiktok.py

@@ -327,6 +327,36 @@ def _upload_video_chunks(
             offset += len(chunk)
 
 
+def _raise_on_terminal_failure(status_response: dict, publish_id: str) -> str | None:
+    """Interpret a status_response from STATUS_FETCH_URL and return TikTok's own status string
+    (e.g. "PUBLISH_COMPLETE", "PROCESSING_UPLOAD") unchanged -- or raise on a genuine API-level
+    error or a terminal FAILED status. TikTok's documented post-status values
+    (https://developers.tiktok.com/doc/content-posting-api-reference-get-video-status):
+    PUBLISH_COMPLETE (done), FAILED (terminal, with a fail_reason field), and several
+    PROCESSING_* values for "still working on it."
+
+    Shared by publish_tiktok()'s immediate post-upload check and check_publish_status()'s
+    --check-status follow-up -- Codex-reported: the first version of this fix only applied to the
+    former, leaving the documented "use --check-status instead of retrying" recovery path just as
+    blind to a real failure as the original bug it was meant to replace would have been."""
+    status_error = status_response.get("error", {})
+    if status_error.get("code") not in (None, "ok"):
+        raise RuntimeError(
+            f"TikTok status check failed for publish_id={publish_id}: {status_error}. "
+            "Do not retry blind -- use --check-status to re-check later."
+        )
+
+    tiktok_status = status_response.get("data", {}).get("status")
+    if tiktok_status == "FAILED":
+        fail_reason = status_response.get("data", {}).get("fail_reason", "unknown")
+        raise RuntimeError(
+            f"TikTok rejected this post (fail_reason={fail_reason}, publish_id={publish_id}). "
+            "Do not retry blind -- see the troubleshoot-publishing skill before attempting "
+            "another real publish."
+        )
+    return tiktok_status
+
+
 def publish_tiktok(
     video_path: str,
     title: str = "",
@@ -423,31 +453,7 @@ def publish_tiktok(
     _upload_video_chunks(upload_url, video_file, effective_chunk, total_size, total_chunk_count)
 
     status_response = _api_post_json(STATUS_FETCH_URL, access_token, {"publish_id": publish_id})
-
-    # Codex-reported regression, caught before any live test: this used to always return
-    # "status": "uploaded" regardless of what status_response actually said, even a terminal
-    # FAILED -- reporting a rejected post as if it succeeded unless the caller happened to
-    # manually inspect the nested status_response. TikTok's documented post-status values
-    # (https://developers.tiktok.com/doc/content-posting-api-reference-get-video-status):
-    # PUBLISH_COMPLETE (done), FAILED (terminal, with a fail_reason field), and several
-    # PROCESSING_* values for "still working on it" -- see check_publish_status above for
-    # re-checking one of those later. A FAILED status must raise, not silently succeed; anything
-    # short of PUBLISH_COMPLETE is honestly reported as still processing, not "uploaded" outright.
-    status_error = status_response.get("error", {})
-    if status_error.get("code") not in (None, "ok"):
-        raise RuntimeError(
-            f"TikTok status check failed for publish_id={publish_id}: {status_error}. "
-            "Do not retry blind -- use --check-status to re-check later."
-        )
-
-    tiktok_status = status_response.get("data", {}).get("status")
-    if tiktok_status == "FAILED":
-        fail_reason = status_response.get("data", {}).get("fail_reason", "unknown")
-        raise RuntimeError(
-            f"TikTok rejected this post after upload (fail_reason={fail_reason}, "
-            f"publish_id={publish_id}). Do not retry blind -- see the troubleshoot-publishing "
-            "skill before attempting another real publish."
-        )
+    tiktok_status = _raise_on_terminal_failure(status_response, publish_id)
 
     return {
         "dry_run": False,
@@ -472,11 +478,22 @@ def check_publish_status(publish_id: str) -> dict:
     was returned right after upload. Added 2026-08-18 after a real publish_id came back
     "PROCESSING_UPLOAD" (a transient state) and the video never actually appeared in the TikTok
     app -- the original code only ever checked status once, immediately after uploading, and
-    never found out whether processing later succeeded or failed."""
+    never found out whether processing later succeeded or failed.
+
+    This is the documented, safe way to check an uncertain publish instead of retrying it for
+    real -- see the troubleshoot-publishing/publish-tiktok guardrails. It must raise on a genuine
+    FAILED status exactly like publish_tiktok()'s own post-upload check does (via the same shared
+    _raise_on_terminal_failure), not just return the raw response unchanged: a caller using this
+    tool specifically to avoid a blind retry must not be told a failed post "succeeded" either."""
     token = _load_token()
     token = _refresh_token_if_needed(token)
     status_response = _api_post_json(STATUS_FETCH_URL, token["access_token"], {"publish_id": publish_id})
-    return {"publish_id": publish_id, "status_response": status_response}
+    tiktok_status = _raise_on_terminal_failure(status_response, publish_id)
+    return {
+        "publish_id": publish_id,
+        "status": "published" if tiktok_status == "PUBLISH_COMPLETE" else "processing",
+        "status_response": status_response,
+    }
 
 
 def main() -> None:

tests/test_publish_tiktok.py

@@ -350,12 +350,47 @@ def fake_api_post_json(url, access_token, body):
     result = check_publish_status("v_pub_file~v2-1.example")
 
     assert result["publish_id"] == "v_pub_file~v2-1.example"
+    assert result["status"] == "published"
     assert result["status_response"]["data"]["status"] == "PUBLISH_COMPLETE"
     assert captured["access_token"] == "tok123"
     assert captured["body"] == {"publish_id": "v_pub_file~v2-1.example"}
     assert "status/fetch" in captured["url"]
 
 
+def test_check_publish_status_raises_on_terminal_failed_status(monkeypatch):
+    """Codex-reported gap: the FAILED-status fix was applied to publish_tiktok()'s immediate
+    post-upload check but not to check_publish_status() -- the documented --check-status recovery
+    path a user is told to use INSTEAD of retrying blind. That path must not be just as capable of
+    silently reporting a failed post as a success as the original bug it was meant to fix."""
+    monkeypatch.setattr("auth.publish_tiktok._load_token", lambda: {"access_token": "tok123"})
+    monkeypatch.setattr("auth.publish_tiktok._refresh_token_if_needed", lambda t: t)
+    monkeypatch.setattr(
+        "auth.publish_tiktok._api_post_json",
+        lambda url, access_token, body: {
+            "data": {"status": "FAILED", "fail_reason": "video_format_check_failed"},
+            "error": {"code": "ok"},
+        },
+    )
+
+    with pytest.raises(RuntimeError, match="video_format_check_failed"):
+        check_publish_status("v_pub_file~v2-1.example")
+
+
+def test_check_publish_status_reports_still_processing_honestly(monkeypatch):
+    monkeypatch.setattr("auth.publish_tiktok._load_token", lambda: {"access_token": "tok123"})
+    monkeypatch.setattr("auth.publish_tiktok._refresh_token_if_needed", lambda t: t)
+    monkeypatch.setattr(
+        "auth.publish_tiktok._api_post_json",
+        lambda url, access_token, body: {
+            "data": {"status": "PROCESSING_UPLOAD"},
+            "error": {"code": "ok"},
+        },
+    )
+
+    result = check_publish_status("v_pub_file~v2-1.example")
+    assert result["status"] == "processing"
+
+
 def test_doctor_registers_tiktok_without_treating_it_as_a_browser_platform():
     """TikTok, like YouTube, uses OAuth + an API and never touches a browser profile -- it must
     not be listed alongside the Chrome-session platforms, but it must have its own check group."""