Report TikTok publish failures honestly; disclose creator-settings gap

Codex found two real issues in this review pass:

1. publish_tiktok() always returned "status": "uploaded" regardless of
   what the post-upload status check actually said. Confirmed against
   TikTok's real, documented status values (PUBLISH_COMPLETE, FAILED
   with a fail_reason field, and PROCESSING_* -- not guessed): a
   terminal FAILED status now raises, with TikTok's own fail_reason in
   the message, instead of being silently reported as a success.
   Anything short of PUBLISH_COMPLETE is now honestly reported as
   "processing," pointing at --check-status, rather than "published."
   This matters more than usual here given the documented account-reset
   risk from blind retries -- an agent or user trusting a false
   "uploaded" status is exactly the kind of mistake that guardrail
   exists to prevent.

2. This publisher never checks a creator's own account restrictions
   (e.g. comments globally disabled) against the flags it sends before
   publishing. Confirmed via TikTok's public docs that creator_info
   exposes this, but fixing it properly needs a live account to confirm
   what the init endpoint actually does when a flag doesn't match --
   reject outright, silently ignore, or something else. Left as an
   explicit, documented gap (module docstring + publish-tiktok skill)
   rather than guessed, to work through together during real testing
   rather than fixed blind now.

Added 4 tests exercising the full real-publish path end to end (token
load/refresh, init, upload, status fetch, all mocked) covering FAILED,
still-processing, and PUBLISH_COMPLETE outcomes. No live TikTok API
calls, no account access, nothing tested against a real account -- same
as every other fix in this PR. 147 tests pass (was 143), compileall
clean, git diff --check clean.

Author: tradewithmeai

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

@@ -49,8 +49,13 @@ assume the post is stuck private forever.
   `auth.publish_safety.should_publish`, as every other publisher here).
 - `--visibility` defaults to `private`. Only mention `--visibility public` once the user
   understands it is still forced private pre-audit -- see above.
-- `--title` is capped at 2200 UTF-16 code units by TikTok's API -- not independently verified
-  against a live account by this tool; treat as a soft limit to check for until confirmed.
+- `--title` is capped at 2,200 UTF-16 code units (TikTok's documented limit) and this tool now
+  actually enforces it before publishing -- an over-length title is rejected up front, not only
+  by the real API after the video has already uploaded.
+- **This tool does not check a creator's own account restrictions before publishing.** A creator
+  with e.g. comments disabled globally may reject the default `disable_comment=False` at the API
+  level -- see the module docstring's "Known, disclosed gap" section. Confirm this together on a
+  live account before assuming every combination of flags will be accepted.
 - **Never make multiple real (`--confirm-publish`) attempts back-to-back, even to debug the same
   failure.** Confirmed live 2026-08-18: a burst of real publish attempts against a brand-new
   unaudited developer app was followed by the connected TikTok account being reset entirely (new
@@ -67,10 +72,17 @@ assume the post is stuck private forever.
 - **Post "succeeds" (a `publish_id` comes back) but is invisible to anyone but the account
   owner**: expected pre-audit behavior, not a bug -- see the unaudited-app section above. Confirm
   with the user whether they want the manual per-post public-visibility fix.
-- **Upload fails partway through a chunk**: the chunk-size default (`DEFAULT_CHUNK_SIZE` in
-  `auth/publish_tiktok.py`) is a reasonable starting point, not independently confirmed against
-  TikTok's current minimum/maximum -- if this is the failure, that constant is the first thing to
-  adjust, informed by whatever error TikTok's API actually returns.
+- **Upload fails partway through a chunk**: `MIN_CHUNK_SIZE`/`MAX_CHUNK_SIZE` in
+  `auth/publish_tiktok.py` (5 MiB / 64 MiB) are confirmed against TikTok's real Media Transfer
+  Guide, not guessed -- but chunked upload of a video over 64 MiB has not itself been exercised
+  live yet (only the single-chunk, under-64-MiB path has). Treat the first large-video upload as
+  still-unverified for that specific path.
+- **A publish "succeeds" (a `publish_id` comes back) but the video never appears**: the result's
+  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.
 - **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.
-  - **Six further issues found by code review before any live retest, none of them guessed:**
+  - **Seven 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
@@ -58,7 +58,17 @@ that will firm up once it leaves beta. Dates are when a release was tagged, not
     code units rather than Python character count. (6) `auth/publish_facebook.py`'s
     timeline-verification check searched the whole page's text, which could false-positive on the
     profile bio, nav text, or an older post -- scoped to `[role="article"]` post containers
-    instead.
+    instead. (7) `publish_tiktok()` always returned `"status": "uploaded"` regardless of what the
+    post-upload status check actually said -- a terminal `FAILED` response (TikTok's own
+    documented status, with a `fail_reason` field) would have been reported as if it succeeded
+    unless the caller manually inspected the nested `status_response`. Now raises on a genuine
+    `FAILED` status, and honestly reports `"processing"` rather than `"published"` for anything
+    short of TikTok's own `PUBLISH_COMPLETE`. A related, disclosed-but-unfixed gap: this module
+    still doesn't check a creator's own account restrictions (e.g. comments disabled globally)
+    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.
 - **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_tiktok.py

@@ -39,6 +39,21 @@
 second chunking bug (total_chunk_count computed via ceil division with an undersized trailing
 chunk, instead of TikTok's documented floor-division-plus-oversized-final-chunk rule) was found
 and fixed by code review before ever reaching a live test. See _compute_chunking's docstring.
+
+## Known, disclosed gap: creator-level restrictions aren't checked before publishing
+
+A creator's own account settings can restrict what a post is allowed to request -- for example,
+an account with comments disabled globally may reject `disable_comment=False` (this module's
+default) at the API level, per TikTok's `creator_info/query` endpoint (the same one `doctor.py`'s
+TikTok check already queries, for a different purpose: confirming the token authenticates against
+a real account). This module does NOT currently query that endpoint before constructing
+`post_info` and validate/constrain `privacy_level`/`disable_duet`/`disable_stitch`/
+`disable_comment` against it -- so an otherwise-valid publish attempt could be rejected by an
+init-time API error for a creator with non-default restrictions. Fixing this properly needs a
+live account to confirm what TikTok's init endpoint actually does when a flag doesn't match a
+creator's restrictions (reject outright, silently ignore, or something else) -- deliberately not
+guessed here. Treat this as a real gap to work through together, live, before broader use -- not
+a hypothetical.
 """
 
 from __future__ import annotations
@@ -409,16 +424,46 @@ def publish_tiktok(
 
     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."
+        )
+
     return {
         "dry_run": False,
         "platform": "tiktok",
-        "status": "uploaded",
+        "status": "published" if tiktok_status == "PUBLISH_COMPLETE" else "processing",
         "visibility": visibility,
         "privacy_level": privacy_level,
         "publish_id": publish_id,
         "title": title,
         "status_response": status_response,
-        "note": UNAUDITED_APP_NOTICE,
+        "note": UNAUDITED_APP_NOTICE + (
+            "" if tiktok_status == "PUBLISH_COMPLETE" else
+            f" Status is still '{tiktok_status}' as of this check, not yet confirmed complete -- "
+            f"use `python -m auth.publish_tiktok --check-status {publish_id}` to re-check later "
+            "rather than assuming success or retrying."
+        ),
     }
 
 

tests/test_publish_tiktok.py

@@ -261,6 +261,72 @@ def fake_urlopen(req, timeout=30):
     assert "Settings and privacy" in message
 
 
+def _mock_full_publish_path(monkeypatch, tmp_path, status_data, status_error=None):
+    import auth.publish_tiktok as tiktok_module
+    """Mock every step of a real publish attempt (load/refresh token, init, upload, status
+    fetch) so publish_tiktok() can be exercised end to end with confirm_publish=True, entirely
+    offline -- no network, no credentials, no TikTok account involved."""
+    video = tmp_path / "clip.mp4"
+    video.write_bytes(b"not a real video, just needs to exist")
+
+    monkeypatch.setattr("auth.publish_tiktok._load_token", lambda: {"access_token": "tok"})
+    monkeypatch.setattr("auth.publish_tiktok._refresh_token_if_needed", lambda t: t)
+    monkeypatch.setattr("auth.publish_tiktok._upload_video_chunks", lambda *a, **k: None)
+
+    init_response = {
+        "error": {"code": "ok"},
+        "data": {"publish_id": "pub123", "upload_url": "https://upload.example/"},
+    }
+    status_response = {"error": status_error or {"code": "ok"}, "data": status_data}
+
+    def fake_api_post_json(url, access_token, body):
+        if url == tiktok_module.VIDEO_INIT_URL:
+            return init_response
+        assert url == tiktok_module.STATUS_FETCH_URL
+        return status_response
+
+    monkeypatch.setattr("auth.publish_tiktok._api_post_json", fake_api_post_json)
+    return video
+
+
+def test_real_publish_raises_on_terminal_failed_status(monkeypatch, tmp_path):
+    """Regression test for a Codex-reported bug found before any live test: publish_tiktok()
+    used to always return "status": "uploaded" regardless of what the post-upload status check
+    actually said -- reporting a rejected post as if it succeeded unless the caller happened to
+    manually inspect the nested status_response. A terminal FAILED status (TikTok's own
+    documented value, with a fail_reason field) must raise, not silently succeed."""
+    video = _mock_full_publish_path(
+        monkeypatch, tmp_path, status_data={"status": "FAILED", "fail_reason": "video_format_check_failed"}
+    )
+    with pytest.raises(RuntimeError, match="video_format_check_failed"):
+        publish_tiktok(str(video), title="t", confirm_publish=True)
+
+
+def test_real_publish_reports_still_processing_honestly(monkeypatch, tmp_path):
+    """A status short of PUBLISH_COMPLETE (e.g. still PROCESSING_UPLOAD moments after the upload
+    finished) must not be reported as unconditionally "uploaded"/done -- the caller needs to know
+    to check again later via --check-status, not assume success."""
+    video = _mock_full_publish_path(monkeypatch, tmp_path, status_data={"status": "PROCESSING_UPLOAD"})
+    result = publish_tiktok(str(video), title="t", confirm_publish=True)
+    assert result["status"] == "processing"
+    assert "PROCESSING_UPLOAD" in result["note"]
+    assert "--check-status" in result["note"]
+
+
+def test_real_publish_reports_success_on_publish_complete(monkeypatch, tmp_path):
+    video = _mock_full_publish_path(monkeypatch, tmp_path, status_data={"status": "PUBLISH_COMPLETE"})
+    result = publish_tiktok(str(video), title="t", confirm_publish=True)
+    assert result["status"] == "published"
+
+
+def test_real_publish_raises_on_status_check_api_error(monkeypatch, tmp_path):
+    video = _mock_full_publish_path(
+        monkeypatch, tmp_path, status_data={}, status_error={"code": "internal_error", "message": "..."}
+    )
+    with pytest.raises(RuntimeError, match="status check failed"):
+        publish_tiktok(str(video), title="t", confirm_publish=True)
+
+
 def test_check_publish_status_wires_token_and_publish_id_through(monkeypatch):
     """Regression test for a real publish_id that came back 'PROCESSING_UPLOAD' right after
     upload (a transient state) and never actually appeared in the TikTok app -- the original code