Use write token for HF storage commits

api.py

@@ -88,8 +88,37 @@ runtime_state = {
 }
 
 
+def get_env_token(*names):
+    for name in names:
+        value = os.environ.get(name)
+        if value:
+            return value
+    return None
+
+
 def get_hf_token():
-    return os.environ.get("HF_TOKEN") or os.environ.get("HUGGING_FACE_HUB_TOKEN")
+    return get_env_token("HF_TOKEN", "HUGGING_FACE_HUB_TOKEN", "HUGGINGFACE_HUB_TOKEN", "HUGGINGFACEHUB_API_TOKEN")
+
+
+def get_hf_storage_write_token():
+    return get_env_token(
+        "SPORALIZE_STORAGE_WRITE_TOKEN",
+        "HF_WRITE_TOKEN",
+        "HUGGING_FACE_HUB_TOKEN",
+        "HF_TOKEN",
+        "HUGGINGFACE_HUB_TOKEN",
+        "HUGGINGFACEHUB_API_TOKEN",
+    )
+
+
+def add_hf_write_token_hint(error):
+    message = str(error)
+    if "403" in message or "Forbidden" in message or "correct permissions" in message:
+        return (
+            f"{message} Set SPORALIZE_STORAGE_WRITE_TOKEN, HF_WRITE_TOKEN, or HF_TOKEN "
+            "to a Hugging Face token with write access to the storage dataset."
+        )
+    return message
 
 
 def hf_storage_enabled():
@@ -184,13 +213,15 @@ def sync_storage_from_hf(force: bool = False):
 def push_session_to_hf(player_id: str, session_id: str, session_dir: str):
     if not hf_storage_enabled():
         return
-    api = HfApi(token=get_hf_token())
+    token = get_hf_storage_write_token()
+    api = HfApi(token=token)
     api.upload_folder(
         repo_id=STORAGE_DATASET_REPO_ID,
         repo_type=STORAGE_DATASET_REPO_TYPE,
         folder_path=session_dir,
         path_in_repo=hf_storage_path(safe_name(player_id), safe_name(session_id)),
         commit_message=f"Add session {safe_name(session_id)} for player {safe_name(player_id)}",
+        token=token,
     )
 
 
@@ -201,7 +232,6 @@ def _hf_files_under(api, path_in_repo: str):
         repo_id=STORAGE_DATASET_REPO_ID,
         repo_type=STORAGE_DATASET_REPO_TYPE,
         revision="main",
-        token=get_hf_token(),
     )
     return [f for f in files if f == path_in_repo or f.startswith(prefix)]
 
@@ -217,7 +247,8 @@ def _delete_folder_from_hf(path_in_repo: str, commit_message: str):
     if not hf_storage_enabled():
         return True, None
 
-    api = HfApi(token=get_hf_token())
+    token = get_hf_storage_write_token()
+    api = HfApi(token=token)
 
     try:
         targets = _hf_files_under(api, path_in_repo)
@@ -237,10 +268,10 @@ def _delete_folder_from_hf(path_in_repo: str, commit_message: str):
             repo_type=STORAGE_DATASET_REPO_TYPE,
             operations=operations,
             commit_message=commit_message,
-            token=get_hf_token(),
+            token=token,
         )
     except Exception as error:
-        delete_error = str(error)
+        delete_error = add_hf_write_token_hint(error)
         print(f"[SPORALIZE] HF delete commit failed for '{path_in_repo}' ({len(targets)} files): {delete_error}", flush=True)
         # Confirm by end state anyway — a benign race may still have removed it.
         try: