@danhachuel/thunderbolt 0.3.73 → 0.3.74

package/MANUAL-INSTALACAO.md

@@ -2,7 +2,7 @@
 
 Este manual descreve a instalação local da UI Thunderbolt, baseada no MoneyPrinterTurbo, utilizando o pacote npm `@danhachuel/thunderbolt`. O fluxo recomendado instala automaticamente o ambiente Python, as dependências da aplicação, as dependências do MoneyPrinterTurbo, o Streamlit e o suporte FFmpeg através de `imageio-ffmpeg`.
 
-> **Versão deste manual:** 0.3.73
+> **Versão deste manual:** 0.3.74
 > **Pacote npm:** `@danhachuel/thunderbolt`
 > **Porta padrão da UI:** `localhost:3030`  
 > **Repositório:** [github.com/DanHachuel/thunderbolt](https://github.com/DanHachuel/thunderbolt)
@@ -132,13 +132,13 @@ Execute:
 Windows PowerShell ou MobaXterm:
 
 ```powershell
-npx.cmd --yes --prefer-online @danhachuel/thunderbolt@0.3.73 install
+npx.cmd --yes --prefer-online @danhachuel/thunderbolt@0.3.74 install
 ```
 
 Linux/macOS:
 
 ```bash
-npx --yes --prefer-online @danhachuel/thunderbolt@0.3.73 install
+npx --yes --prefer-online @danhachuel/thunderbolt@0.3.74 install
 ```
 
 A instalação normal é **segura para actualizações**: preserva `storage`, Blueprints, Brandings, configurações e artefactos do utilizador. Remove apenas `.venv`, o clone técnico do MoneyPrinterTurbo e dependências que serão recriadas. Uma pasta antiga sem dados do utilizador, como `C:\Users\<utilizador>\AppData\Local\hermes` da tentativa incompleta, pode ser removida; uma pasta antiga que contenha Blueprints, Brandings ou storage é preservada e apenas avisada no terminal. Feche processos Python, Node, Streamlit e MobaXterm que estejam a usar as pastas antes de executar.
@@ -146,7 +146,7 @@ A instalação normal é **segura para actualizações**: preserva `storage`, Bl
 Se quiser apagar absolutamente tudo de forma intencional, use o comando destrutivo separado:
 
 ```powershell
-npx.cmd --yes --prefer-online @danhachuel/thunderbolt@0.3.73 install --purge-data
+npx.cmd --yes --prefer-online @danhachuel/thunderbolt@0.3.74 install --purge-data
 ```
 
 O parâmetro `--purge-data` apaga Blueprints, Brandings, configurações, storage e artefactos locais. Não o use numa actualização normal.
@@ -574,7 +574,7 @@ Ao abrir a página, o Thunderbolt não prepara dados públicos, não descarrega
 
 Os parâmetros da UI são número de clusters entre 2 e 10, suporte mínimo entre 0,01 e 0,50, país, engagement, intervalo de datas e tags, todos dentro da área principal da aba. O núcleo normaliza os dados, calcula engagement, aplica filtros, faz transformação logarítmica e standardização, executa K-Means e calcula itemsets/regras com FP-Growth. Não são apresentados resultados até ao primeiro clique em **Analisar Nichos**; o mesmo botão aplica alterações posteriores aos filtros. Os resultados são DataFrames de clusters, itemsets frequentes, regras de associação e dados analisados; o gráfico de dispersão é criado nativamente com Plotly.
 
-As dependências adicionais — `scikit-learn`, `mlxtend`, `plotly`, `seaborn`, `matplotlib` e `kagglehub` — são instaladas pelo procedimento normal de `npx`. Em instalações existentes, execute novamente `npx.cmd --yes --prefer-online @danhachuel/thunderbolt@0.3.73 install`; o instalador detecta e reutiliza o que já estiver válido.
+As dependências adicionais — `scikit-learn`, `mlxtend`, `plotly`, `seaborn`, `matplotlib` e `kagglehub` — são instaladas pelo procedimento normal de `npx`. Em instalações existentes, execute novamente `npx.cmd --yes --prefer-online @danhachuel/thunderbolt@0.3.74 install`; o instalador detecta e reutiliza o que já estiver válido.
 
 ### Niche Finder Apify
 
@@ -803,3 +803,8 @@ A publicação YouTube segue primeiro a lógica adaptada do `PublishingSchedulin
 
 ### Growth — novas áreas reservadas
 O grupo **Growth** inclui agora as abas **Analista Facebook Pages** e **Analista Bilibili**. Ambas são páginas vazias nesta versão e não executam operações nem pedem credenciais.
+
+## 15. Documentação técnica e execução retomável
+Consulte [`docs/api-internal.md`](docs/api-internal.md) no repositório GitHub para os contratos internos, diagramas de sequência, escritas atómicas de JSON, health check de `sessionInfo` e orquestrador em cascata.
+
+O worker local guarda a etapa actual e os artefactos de cada tarefa. Ao reiniciar, retoma a primeira etapa pendente; não deve regenerar ficheiros válidos já persistidos. O `sessionInfo` do Upload directo é monitorizado com uma janela preventiva de 24–48 horas, por defeito 36 horas. A renovação é manual em **Contas Google**.

package/README.md

@@ -107,7 +107,7 @@ No topo da área principal da aplicação existe o menu nativo de idioma no padr
 
 A UI suporta os temas **Dark** e **Light** através do menu nativo de três pontos do Streamlit, no local original do toolbar. Não existe um selector Theme adicional dentro da página. A configuração distribuída em `.streamlit/config.toml` disponibiliza as variantes nomeadas **Dark** e **Light**, e o menu nativo continua responsável por alternar entre os modos, seguindo o padrão do [MoneyPrinterTurbo](https://github.com/harry0703/MoneyPrinterTurbo). O CSS próprio do Thunderbolt usa cores semânticas, `currentColor` e `color-mix` para acompanhar o tema activo, sem alterar a posição nem a funcionalidade do toolbar, do botão Deploy e do menu principal.
 
-## Navegação da UI 0.3.73
+## Navegação da UI 0.3.74
 
 A barra lateral mantém os níveis principais, nesta ordem: **Início**, **Niche Finder**, **Pipeline**, **Pipeline TikTok**, **Automação**, **Edição**, **AI Influencers** e **Configurações**. **Pipeline Vídeos** é expansível e contém **Criação de Vídeos**, **Backlog Vídeos**, **Roteiros**, **Thumbnails** e **Upload**. **Pipeline Música** é expansível e contém **Criação de Músicas** e **Upload Música**. **Automação** também é expansível e contém **Automação Youtube**. **Edição** é expansível e contém **Limpador de Metadados**, **Cortes**, **Editor Python** e **Download Mídia**, nessa ordem. **AI Influencers** é expansível e contém **Personagens**, **Geração de Conteúdo IA**, **Motion Control**, **UGC Products**, **Redes Sociais**, **Tutorial Meta** e **Tutorial Supabase**, nessa ordem. A criação de Motion Control e UGC Products ocorre nas páginas standalone e guarda os artefactos localmente; não existem tabs duplicadas dentro de Geração de Conteúdo IA.
  **Niche Finder** é expansível e contém **Niche Finder Kaggle** e **Niche Finder Apify**. **Configurações** é expansível e contém **Canais Youtube**, **Blueprints Youtube**, **MCP**, **Contas Google**, **Notificações**, **Logs** e **Configuração API**, nessa ordem. O Início reúne o dashboard e as filas do Pipeline, sem botões de acções rápidas.
@@ -418,3 +418,8 @@ Não coloque chaves, cookies, tokens YouTube ou segredos TikTok no Git. Use a co
 
 ## Growth
 As páginas **Analista Facebook Pages** e **Analista Bilibili** foram adicionadas ao grupo **Growth** como áreas reservadas e permanecem vazias nesta versão, prontas para futuras implementações específicas.
+
+## Documentação técnica interna
+A documentação de API interna, os contratos de persistência, o health check de `sessionInfo` e os diagramas de sequência estão em [`docs/api-internal.md`](docs/api-internal.md). Os ficheiros Mermaid editáveis ficam em [`docs/diagrams/`](docs/diagrams/).
+
+A pipeline do worker usa agora um orquestrador local em cascata, com artefactos retomáveis e transições persistidas. As escritas de estado JSON e de Blueprints usam substituição atómica para evitar documentos truncados após interrupções.

package/app/main.py

@@ -26,7 +26,7 @@ from hermes_ui.domain import STAGES, create_batch, create_channel, create_tasks_
 from hermes_ui.drafts import list_drafts, save_draft
 from hermes_ui.automation_worker import load_worker_status
 from hermes_ui.pipeline_worker import load_pipeline_worker_status, recover_stale_tasks, STALE_TASK_SECONDS, WORKER_HEARTBEAT_TIMEOUT_SECONDS
-from hermes_ui.storage import BLUEPRINTS, DEFAULT_LLM_PROVIDER, MEDIA_DOWNLOADS, STORAGE, TIKTOK_PROMPT_MASTERS, ensure_storage, get_display_name, list_blueprint_files, list_prompt_master_files, load_blueprint_file, load_prompt_master_file, now, read_json, set_display_name, write_json
+from hermes_ui.storage import BLUEPRINTS, DEFAULT_LLM_PROVIDER, MEDIA_DOWNLOADS, STORAGE, TIKTOK_PROMPT_MASTERS, atomic_write, ensure_storage, get_display_name, list_blueprint_files, list_prompt_master_files, load_blueprint_file, load_prompt_master_file, now, read_json, set_display_name, write_json
 from app.modules.niche_finder.apify import ApifyError, DEFAULT_ACTOR_ID, abort_actor_run, build_actor_input, get_dataset_items, normalize_video_items, start_actor_run, wait_for_actor_run
 from app.modules.niche_finder.core import NicheAnalysisError, run_niche_analysis
 from app.modules.niche_finder.data_loader import DatasetError, download_kaggle_dataset
@@ -76,6 +76,7 @@ from integrations.music_uploads import JewelMusicAdapter, PushtunesAdapter, YTMu
 from integrations.upload_routing import OFFICIAL_DAILY_LIMIT, official_upload_count, upload_with_default_route
 from integrations.youtube_direct_upload import YouTubeDirectUploader
 from integrations.youtube_direct_credentials import delete_credentials_document, direct_account_status, document_status, ensure_credentials_document, load_credentials_document, merge_credentials_document, parse_credentials_document, save_credentials_document, update_credentials_document_session_info
+from integrations.session_info_health import check_account_session_info_health
 from integrations.youtube_batch import account_key as youtube_batch_account_key, account_status as youtube_batch_account_status, authorize_account as authorize_youtube_batch_account, delete_account_token as delete_youtube_batch_token, list_my_channels as list_youtube_batch_channels, loopback_redirect_uri
 from integrations.local_runtime import MoneyPrinterRuntime
 from integrations.moneyprinter_config import sync_moneyprinter_config
@@ -1353,7 +1354,7 @@ def render_blueprints():
                 if destination.exists() and not st.checkbox("Confirmar substituição", key="confirm_blueprint_replace"):
                     st.warning("O ficheiro já existe. Confirme a substituição.")
                 else:
-                    destination.write_text(json.dumps(data, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+                    atomic_write(destination, data)
                     record_notification("blueprint_completed", f"Blueprint guardado: {destination.stem}", "O Blueprint importado foi guardado no storage local.", metadata={"name": destination.stem}, dedupe_key=f"blueprint:{destination}:{destination.stat().st_mtime_ns}")
                     st.success(f"Blueprint guardado em {destination}")
                     st.rerun()
@@ -1393,7 +1394,7 @@ def render_blueprints():
                     raise ValueError("O JSON raiz deve ser um objecto.")
                 target = BLUEPRINTS / "brandings" / (Path(branding_upload.name).stem.replace(" ", "-") + ".json")
                 target.parent.mkdir(parents=True, exist_ok=True)
-                target.write_text(json.dumps(data, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+                atomic_write(target, data)
                 record_notification("branding_completed", f"Branding guardado: {target.stem}", "O Branding importado foi guardado no storage local.", metadata={"name": target.stem}, dedupe_key=f"branding:{target}:{target.stat().st_mtime_ns}")
                 st.success(f"Branding guardado em {target}")
                 st.rerun()
@@ -4966,6 +4967,7 @@ def render_google_accounts():
         account_label_snapshot = str(batch_account.get("label") or "Canais YouTube")
         ensure_credentials_document(STORAGE, batch_account, settings, channel_state)
         direct_status = direct_account_status(STORAGE, batch_account, settings)
+        session_health = check_account_session_info_health(STORAGE, batch_account, settings)
         missing_document_parts = list(direct_status.get("missing_cookies", []))
         if not direct_status.get("has_session_info"):
             missing_document_parts.append("sessionInfo")
@@ -4985,6 +4987,15 @@ def render_google_accounts():
                 st.subheader(f"{account_label_snapshot} — {account_email_snapshot}")
             with account_header_cols[1]:
                 _api_status_badge("Configured" if account_ready else "Missing configuration", "ready" if account_ready else "missing")
+            health_message = f"SessionInfo: {session_health.message}"
+            if session_health.status == "healthy":
+                st.caption(health_message)
+            elif session_health.status == "expiring":
+                st.warning(health_message, icon="⚠️")
+            elif session_health.status == "expired":
+                st.error(health_message, icon="⚠️")
+            elif session_health.status == "unknown":
+                st.warning(health_message, icon="⚠️")
             with st.expander("Detalhes da conta Google", expanded=False):
                 with st.form(f"batch_account_form_{account_id}"):
                     account_cols = st.columns(2)

package/hermes_ui/automation_worker.py

@@ -12,6 +12,7 @@ from .creative_generation import generate_title_and_keywords, generate_topic_for
 from .domain import create_batch, create_tasks_for_batch
 from .material_sources import selected_material_source
 from .notifications import record_notification
+from integrations.session_info_health import check_all_accounts_session_info_health, emit_session_info_health_alerts
 
 WORKER_STATE_FILE = "automation_worker.json"
 LOCK_FILENAME = "automation_worker.lock"
@@ -233,6 +234,14 @@ def run_once(when: datetime | None = None) -> dict[str, Any]:
     status["last_tick_local"] = _local_iso(current)
     status["last_heartbeat_local"] = _local_iso(current)
     status["last_error"] = ""
+    try:
+        session_health = check_all_accounts_session_info_health(storage.STORAGE, storage.read_json("settings.json", {}))
+        session_alerts = emit_session_info_health_alerts(session_health, now=current.astimezone())
+        status["session_info_health"] = [item.as_dict() for item in session_health]
+        status["session_info_alerts"] = len(session_alerts)
+    except Exception as exc:
+        # Session monitoring must never stop creation of a scheduled batch.
+        status["session_info_health_error"] = type(exc).__name__
     created: list[dict[str, Any]] = []
     skipped: list[str] = []
     channels = storage.read_json("channels.json", [])

package/hermes_ui/blueprints.py

@@ -6,7 +6,7 @@ from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any
 
-from .storage import BLUEPRINTS, now
+from .storage import BLUEPRINTS, atomic_write, now
 
 
 def _slug(value: str) -> str:
@@ -140,15 +140,16 @@ def create_branding_for_blueprint(blueprint: dict[str, Any]) -> dict[str, Any]:
 
 
 def save_generated_blueprint(blueprint: dict[str, Any], branding: dict[str, Any] | None = None) -> tuple[Path, Path | None]:
+    """Persist generated Blueprint/Branding JSON using atomic replacement."""
     BLUEPRINTS.mkdir(parents=True, exist_ok=True)
     target = BLUEPRINTS / "canais" / f"{_slug(blueprint.get('name', 'blueprint'))}-{blueprint['id']}.json"
     target.parent.mkdir(parents=True, exist_ok=True)
-    target.write_text(__import__("json").dumps(blueprint, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    atomic_write(target, blueprint)
     branding_path = None
     if branding:
         branding_path = BLUEPRINTS / "brandings" / f"{_slug(branding.get('name', 'branding'))}-{branding['id']}.json"
         branding_path.parent.mkdir(parents=True, exist_ok=True)
-        branding_path.write_text(__import__("json").dumps(branding, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+        atomic_write(branding_path, branding)
     return target, branding_path
 
 

package/hermes_ui/cuts.py

@@ -304,8 +304,9 @@ def _run_ffmpeg(command: list[str], output: Path, *, source: Path, segment: dict
 
 
 def _write_manifest(record: dict[str, Any], run_dir: Path) -> Path:
+    """Write a complete clip manifest atomically."""
     path = run_dir / "manifest.json"
-    path.write_text(json.dumps(record, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+    storage.atomic_write(path, record)
     return path
 
 

package/hermes_ui/domain.py

@@ -8,6 +8,9 @@ from .notifications import record_notification
 from .storage import append_json, now, read_json, write_json
 
 STAGES = ["niche", "blueprint", "brand", "topic", "script", "title", "keywords", "video", "thumbnail_prompt", "thumbnail", "upload"]
+# Ordem executada pelo worker. Cada etapa só é executada quando o seu artefacto
+# ainda não existe; os artefactos persistidos tornam a cascata retomável.
+CASCADE_STAGE_ORDER = ("topic", "script", "title", "keywords", "video", "thumbnail_prompt", "thumbnail", "upload")
 LEGACY_STAGES = {"edit"}
 VALID_STATES = {"to_do", "doing", "blocked", "done", "failed", "cancelled"}
 
@@ -148,6 +151,7 @@ def create_tasks_for_batch(batch: dict[str, Any]) -> list[dict[str, Any]]:
             thumbnail_status = str(payload.get("thumbnail_status") or ("generated" if thumbnail_path else "not_generated"))
             if thumbnail_path:
                 artifacts.setdefault("thumbnail", thumbnail_path)
+            initial_stage = "topic" if not topic and str(payload.get("topic_source") or options.get("topic_source") or "manual") in {"auto", "llm_pending"} else "script"
             task = {
                 "id": make_id("video"),
                 "batch_id": batch["id"],
@@ -180,7 +184,15 @@ def create_tasks_for_batch(batch: dict[str, Any]) -> list[dict[str, Any]]:
                 "title_candidates": payload.get("title_candidates", []),
                 "keywords": payload.get("keywords", options.get("keywords", [])),
                 "ai_generation": payload.get("ai_generation", {}),
-                "stage": "script",
+                "stage": initial_stage,
+                "orchestration": {
+                    "name": "local-cascade",
+                    "stage_order": list(CASCADE_STAGE_ORDER),
+                    "current_stage": initial_stage,
+                    "completed_stages": [],
+                    "resumable": True,
+                    "last_transition_at": now(),
+                },
                 "state": "to_do",
                 "progress": 0,
                 "video_ready": bool(artifacts.get("video")),

package/hermes_ui/notifications.py

@@ -34,6 +34,8 @@ EVENT_CATALOG: tuple[dict[str, str], ...] = (
     {"code": "automation_completed", "category": "Automação", "label": "Automação concluída", "description": "Quando o worker concluir o lote agendado de um canal."},
     {"code": "automation_failed", "category": "Automação", "label": "Automação falhou", "description": "Quando uma execução automática terminar com erro."},
     {"code": "activity_failed", "category": "Sistema", "label": "Actividade falhou", "description": "Quando uma tarefa ou operação persistida terminar em erro."},
+    {"code": "session_info_expiring", "category": "Autenticação", "label": "SessionInfo a expirar", "description": "Quando o token sessionInfo de uma conta Google/YouTube se aproximar da expiração estimada."},
+    {"code": "session_info_expired", "category": "Autenticação", "label": "SessionInfo expirado", "description": "Quando o token sessionInfo de uma conta Google/YouTube ultrapassar a expiração estimada."},
     {"code": "upload_youtube_success", "category": "Upload", "label": "Upload YouTube concluído", "description": "Quando um vídeo for publicado num canal YouTube."},
     {"code": "upload_tiktok_success", "category": "Upload", "label": "Upload TikTok concluído", "description": "Quando um vídeo for publicado numa conta TikTok."},
     {"code": "upload_instagram_success", "category": "Upload", "label": "Upload Instagram concluído", "description": "Quando um vídeo for publicado num perfil Instagram."},

package/hermes_ui/pipeline_worker.py

@@ -12,11 +12,12 @@ from pathlib import Path
 from typing import Any
 
 from integrations.moneyprinter_config import sync_moneyprinter_config
+from integrations.session_info_health import check_all_accounts_session_info_health, emit_session_info_health_alerts
 from integrations.upload_routing import upload_with_default_route
 from hermes_ui.creative_generation import CreativeGenerationError, generate_creative_package, generate_title_and_keywords, generate_thumbnail_prompt, generate_topic_for_channel
 from hermes_ui.script_documents import save_script_document
 from hermes_ui.script_generation import generate_script_document
-from hermes_ui.storage import STORAGE, ensure_storage, read_json, write_json
+from hermes_ui.storage import STORAGE, atomic_write, ensure_storage, read_json, write_json
 from hermes_ui.llm_providers import active_llm_card, provider_definition
 from hermes_ui.media_generation import MediaGenerationError, _append_generation_constraints, generate_image_from_pool, generate_video_from_pool
 from hermes_ui.media_providers import FULL_IA_VIDEO_PROVIDER_CODES, media_cards_for_pool, media_provider_definition
@@ -28,6 +29,7 @@ PIPELINE_LOG_FILENAME = "pipeline_worker.json"
 VIDEO_TIMEOUT_SECONDS = 20 * 60
 STALE_TASK_SECONDS = VIDEO_TIMEOUT_SECONDS + 5 * 60
 WORKER_HEARTBEAT_TIMEOUT_SECONDS = 15
+CASCADE_STAGE_ORDER = ("topic", "script", "title", "keywords", "video", "thumbnail_prompt", "thumbnail", "upload")
 
 
 class PipelineError(RuntimeError):
@@ -207,14 +209,42 @@ def _task_by_id(task_id: str) -> dict[str, Any] | None:
     return next((task for task in read_json("tasks.json", []) if isinstance(task, dict) and task.get("id") == task_id), None)
 
 
+def _cascade_metadata(current: dict[str, Any], updates: dict[str, Any]) -> dict[str, Any]:
+    """Build resumable orchestration metadata for one stage transition."""
+    previous = str(current.get("stage") or "")
+    next_stage = str(updates.get("stage") or previous)
+    raw = current.get("orchestration") if isinstance(current.get("orchestration"), dict) else {}
+    completed = [str(item) for item in raw.get("completed_stages", []) if str(item) in CASCADE_STAGE_ORDER]
+    if previous in CASCADE_STAGE_ORDER and next_stage != previous and previous not in completed:
+        completed.append(previous)
+    if str(updates.get("state") or "") == "done" and next_stage in CASCADE_STAGE_ORDER and next_stage not in completed:
+        completed.append(next_stage)
+    transition_at = raw.get("last_transition_at") or _now()
+    if next_stage != previous:
+        transition_at = _now()
+    try:
+        transition_count = int(raw.get("transition_count") or 0)
+    except (TypeError, ValueError):
+        transition_count = 0
+    return {
+        "name": "local-cascade",
+        "stage_order": list(CASCADE_STAGE_ORDER),
+        "current_stage": next_stage,
+        "completed_stages": completed,
+        "resumable": True,
+        "last_transition_at": transition_at,
+        "transition_count": transition_count + (1 if next_stage != previous else 0),
+    }
+
 def _update(task_id: str, **updates: Any) -> dict[str, Any]:
     from hermes_ui.domain import update_task
-
     current = _task_by_id(task_id)
     if not current:
         raise PipelineError(f"Tarefa {task_id} deixou de existir durante a execução.")
     if str(current.get("state") or "") in {"blocked", "cancelled"}:
         raise PipelineStopped("A tarefa foi parada pelo utilizador.")
+    updates = dict(updates)
+    updates["orchestration"] = _cascade_metadata(current, updates)
     updated = update_task(task_id, updates)
     if not updated:
         raise PipelineError(f"Tarefa {task_id} deixou de existir durante a execução.")
@@ -223,10 +253,9 @@ def _update(task_id: str, **updates: Any) -> dict[str, Any]:
         status="running",
         stage=str(updated.get("stage") or "pipeline"),
         progress=int(updated.get("progress") or 0),
+        orchestration=updated.get("orchestration") or {},
     )
     return updated
-
-
 def _channel_for_task(task: dict[str, Any]) -> dict[str, Any]:
     channel_id = str(task.get("channel_id") or "")
     return next((channel for channel in read_json("channels.json", []) if str(channel.get("id")) == channel_id), {})
@@ -254,12 +283,11 @@ def _keywords(topic: str, title: str, niche: str = "") -> list[str]:
 
 
 def _save_json_artifact(task_id: str, name: str, payload: dict[str, Any]) -> str:
+    """Persist a resumable pipeline artifact atomically."""
     directory = STORAGE / "artifacts"
     directory.mkdir(parents=True, exist_ok=True)
     path = directory / f"{task_id}-{name}.json"
-    temporary = path.with_suffix(".tmp")
-    temporary.write_text(json.dumps(payload, ensure_ascii=False, indent=2), encoding="utf-8")
-    temporary.replace(path)
+    atomic_write(path, payload)
     return str(path)
 
 
@@ -947,6 +975,7 @@ def _read_json_artifact(value: Any) -> dict[str, Any] | None:
 
 
 def _run_task(task: dict[str, Any]) -> dict[str, Any]:
+    """Run one resumable local-cascade task, reusing valid persisted artefacts."""
     task_id = str(task.get("id") or "")
     channel = _channel_for_task(task)
     settings = _settings()
@@ -1213,11 +1242,23 @@ def _run_task(task: dict[str, Any]) -> dict[str, Any]:
 
 
 def run_once() -> dict[str, Any]:
+    """Execute one worker tick and resume the first pending cascade task."""
     ensure_storage()
     lock = _acquire_lock()
     if lock is None:
         return {"ok": True, "busy": True}
     try:
+        try:
+            session_health = check_all_accounts_session_info_health(STORAGE, _settings())
+            session_alerts = emit_session_info_health_alerts(session_health)
+            _worker_heartbeat(
+                session_info_health=[item.as_dict() for item in session_health],
+                session_info_alerts=len(session_alerts),
+                session_info_health_error="",
+            )
+        except Exception as exc:
+            # Monitoring is advisory and must not prevent a resumable task from running.
+            _worker_heartbeat(session_info_health_error=type(exc).__name__)
         recovered = _recover_stale_tasks()
         tasks = read_json("tasks.json", [])
         candidate = next((task for task in tasks if isinstance(task, dict) and task.get("state") in {"to_do", "doing"}), None)

package/hermes_ui/provider_routing.py

@@ -25,7 +25,7 @@ from .llm_providers import (
     normalize_llm_card,
     provider_definition,
 )
-from .storage import STORAGE, ensure_storage
+from .storage import STORAGE, atomic_write, ensure_storage
 
 
 POOL_LLM = "llm_text"
@@ -159,10 +159,8 @@ def _load_state(path: Path, default: Any) -> Any:
 
 
 def _save_state(path: Path, value: Any) -> None:
-    path.parent.mkdir(parents=True, exist_ok=True)
-    temporary = path.with_name(f".{path.name}.{os.getpid()}.tmp")
-    temporary.write_text(json.dumps(value, ensure_ascii=False, indent=2), encoding="utf-8")
-    os.replace(temporary, path)
+    """Persist provider routing state without exposing a partial JSON file."""
+    atomic_write(path, value)
 
 
 def nvidia_rpm_enabled(settings: Mapping[str, Any]) -> bool:

package/hermes_ui/storage.py

@@ -105,6 +105,8 @@ DEFAULTS: dict[str, Any] = {
         "telegram_chat_id": "",
         "telegram_proxy_url": "",
         "telegram_timeout_seconds": 15,
+        "session_info_ttl_hours": 36,
+        "session_info_alert_hours": 6,
         "notification_preferences": {
             "video_completed": True,
             "music_completed": True,
@@ -122,6 +124,8 @@ DEFAULTS: dict[str, Any] = {
             "automation_completed": True,
             "automation_failed": True,
             "activity_failed": True,
+            "session_info_expiring": True,
+            "session_info_expired": True,
             "upload_youtube_success": True,
             "upload_tiktok_success": True,
             "upload_instagram_success": True,
@@ -401,6 +405,12 @@ def ensure_storage() -> None:
 
 
 def atomic_write(path: Path, data: Any) -> None:
+    """Write JSON through a same-directory temporary file and atomic replace.
+
+    The complete payload is flushed and fsynced before replacement, so a
+    process interruption cannot leave a partially written JSON document at the
+    destination.
+    """
     path.parent.mkdir(parents=True, exist_ok=True)
     fd, temp_name = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent)
     try:
@@ -437,6 +447,7 @@ def read_json(name: str, default: Any | None = None) -> Any:
 
 
 def write_json(name: str, data: Any) -> None:
+    """Persist a state JSON file using :func:`atomic_write`."""
     ensure_storage()
     atomic_write(STATE / name, data)
 

package/integrations/session_info_health.py

@@ -0,0 +1,238 @@
+"""Health check read-only para sessões do Upload directo YouTube.
+
+O token ``sessionInfo`` não é interpretado nem devolvido. O módulo controla a
+idade de captura persistida no documento de credenciais, aplica uma janela
+conservadora de expiração e permite que a UI/worker alerte antes de iniciar um
+upload. A renovação continua manual: o utilizador deve substituir o token na
+conta Google/YouTube.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timedelta, timezone
+from pathlib import Path
+from typing import Any
+
+from integrations.youtube_direct_credentials import credentials_document_path, load_credentials_document
+
+DEFAULT_SESSION_INFO_TTL_HOURS = 36
+DEFAULT_SESSION_INFO_ALERT_HOURS = 6
+MIN_SESSION_INFO_TTL_HOURS = 24
+MAX_SESSION_INFO_TTL_HOURS = 48
+
+
+def utc_now() -> datetime:
+    """Return the current timezone-aware UTC timestamp."""
+    return datetime.now(timezone.utc)
+
+
+def parse_timestamp(value: Any) -> datetime | None:
+    """Parse ISO-8601 timestamps used in local credential documents."""
+    text = str(value or "").strip()
+    if not text:
+        return None
+    try:
+        parsed = datetime.fromisoformat(text.replace("Z", "+00:00"))
+    except ValueError:
+        return None
+    return parsed if parsed.tzinfo else parsed.replace(tzinfo=timezone.utc)
+
+
+def _clamp_hours(value: Any, default: int) -> int:
+    try:
+        hours = int(value)
+    except (TypeError, ValueError):
+        hours = default
+    return max(MIN_SESSION_INFO_TTL_HOURS, min(MAX_SESSION_INFO_TTL_HOURS, hours))
+
+
+@dataclass(frozen=True)
+class SessionInfoHealth:
+    """Safe, serialisable status of one account's sessionInfo token."""
+
+    status: str
+    message: str
+    age_hours: float | None
+    remaining_hours: float | None
+    expires_at: str | None
+    captured_at: str | None
+    account_id: str
+    account_label: str
+    credential_file: str
+    has_session_info: bool
+    needs_manual_renewal: bool
+
+    @property
+    def ok(self) -> bool:
+        """Whether the token is usable without a preventive warning."""
+        return self.status == "healthy"
+
+    @property
+    def warning(self) -> bool:
+        """Whether the account is usable but close to the configured TTL."""
+        return self.status == "expiring"
+
+    def as_dict(self) -> dict[str, Any]:
+        """Return public health fields without secrets or token material."""
+        return {
+            "status": self.status,
+            "message": self.message,
+            "age_hours": round(self.age_hours, 2) if self.age_hours is not None else None,
+            "remaining_hours": round(self.remaining_hours, 2) if self.remaining_hours is not None else None,
+            "expires_at": self.expires_at,
+            "captured_at": self.captured_at,
+            "account_id": self.account_id,
+            "account_label": self.account_label,
+            "credential_file": self.credential_file,
+            "has_session_info": self.has_session_info,
+            "needs_manual_renewal": self.needs_manual_renewal,
+        }
+
+
+def health_check_session_info(
+    account: dict[str, Any],
+    document: dict[str, Any] | None,
+    *,
+    now: datetime | None = None,
+    ttl_hours: Any = DEFAULT_SESSION_INFO_TTL_HOURS,
+    alert_hours: Any = DEFAULT_SESSION_INFO_ALERT_HOURS,
+    credential_file: str | Path = "",
+) -> SessionInfoHealth:
+    """Check a sessionInfo document without making a network request.
+
+    A new or legacy document without ``sessionInfoCapturedAt`` is reported as
+    ``unknown`` rather than silently trusted. The next manual save records the
+    capture time; this avoids claiming that an old token is fresh.
+    """
+    current = now or utc_now()
+    if current.tzinfo is None:
+        current = current.replace(tzinfo=timezone.utc)
+    ttl = _clamp_hours(ttl_hours, DEFAULT_SESSION_INFO_TTL_HOURS)
+    alert = max(1, min(ttl - 1, _clamp_hours(alert_hours, DEFAULT_SESSION_INFO_ALERT_HOURS)))
+    document = document if isinstance(document, dict) else {}
+    session_info = str(document.get("sessionInfo") or document.get("session_info") or "").strip()
+    captured_value = document.get("sessionInfoCapturedAt") or document.get("session_info_captured_at")
+    captured = parse_timestamp(captured_value)
+    account_id = str(account.get("id") or document.get("account_id") or "").strip()
+    account_label = str(account.get("label") or account.get("name") or account.get("email") or account_id or "Conta Google").strip()
+    file_text = str(credential_file or "")
+    if not session_info:
+        return SessionInfoHealth("missing", "Falta sessionInfo nesta conta Google/YouTube.", None, None, None, None, account_id, account_label, file_text, False, True)
+    if captured is None:
+        return SessionInfoHealth("unknown", "sessionInfo existe, mas a data de captura não é conhecida; guarde novamente o token para activar o alerta de expiração.", None, None, None, None, account_id, account_label, file_text, True, True)
+    age = max(0.0, (current - captured.astimezone(timezone.utc)).total_seconds() / 3600)
+    remaining = float(ttl) - age
+    expires = captured.astimezone(timezone.utc) + timedelta(hours=ttl)
+    if remaining <= 0:
+        return SessionInfoHealth("expired", f"sessionInfo expirou há {abs(remaining):.1f} horas; renove-o manualmente antes de criar ou enviar conteúdos.", age, remaining, expires.isoformat(), captured.isoformat(), account_id, account_label, file_text, True, True)
+    if remaining <= alert:
+        return SessionInfoHealth("expiring", f"sessionInfo expira em aproximadamente {remaining:.1f} horas; renove-o manualmente preventivamente.", age, remaining, expires.isoformat(), captured.isoformat(), account_id, account_label, file_text, True, True)
+    return SessionInfoHealth("healthy", f"sessionInfo válido por aproximadamente mais {remaining:.1f} horas.", age, remaining, expires.isoformat(), captured.isoformat(), account_id, account_label, file_text, True, False)
+
+
+def session_info_health_from_settings(
+    account: dict[str, Any],
+    document: dict[str, Any] | None,
+    settings: dict[str, Any] | None = None,
+    *,
+    now: datetime | None = None,
+    credential_file: str | Path = "",
+) -> SessionInfoHealth:
+    """Apply local settings while keeping the 24–48 hour TTL bounded."""
+    settings = settings or {}
+    return health_check_session_info(
+        account,
+        document,
+        now=now,
+        ttl_hours=settings.get("session_info_ttl_hours", DEFAULT_SESSION_INFO_TTL_HOURS),
+        alert_hours=settings.get("session_info_alert_hours", DEFAULT_SESSION_INFO_ALERT_HOURS),
+        credential_file=credential_file,
+    )
+
+
+def check_account_session_info_health(
+    storage_root: Path,
+    account: dict[str, Any],
+    settings: dict[str, Any] | None = None,
+    *,
+    now: datetime | None = None,
+) -> SessionInfoHealth:
+    """Load one account document and return its safe SessionInfo health state."""
+    settings = settings or {}
+    document = load_credentials_document(storage_root, account, settings, create=False)
+    return session_info_health_from_settings(
+        account,
+        document,
+        settings,
+        now=now,
+        credential_file=credentials_document_path(storage_root, account),
+    )
+
+
+def check_all_accounts_session_info_health(
+    storage_root: Path,
+    settings: dict[str, Any] | None = None,
+    *,
+    now: datetime | None = None,
+) -> list[SessionInfoHealth]:
+    """Return health states for all configured Google/YouTube accounts."""
+    settings = settings or {}
+    accounts = settings.get("youtube_batch_accounts", [])
+    if not isinstance(accounts, list):
+        return []
+    result: list[SessionInfoHealth] = []
+    for account in accounts:
+        if not isinstance(account, dict) or not str(account.get("id") or "").strip():
+            continue
+        result.append(check_account_session_info_health(storage_root, account, settings, now=now))
+    return result
+
+
+def emit_session_info_health_alerts(
+    health_items: list[SessionInfoHealth],
+    *,
+    now: datetime | None = None,
+) -> list[dict[str, Any]]:
+    """Persist one deduplicated local notification per account and state."""
+    from hermes_ui.notifications import record_notification
+
+    current = now or utc_now()
+    day = current.astimezone(timezone.utc).date().isoformat()
+    created: list[dict[str, Any]] = []
+    for health in health_items:
+        if health.status not in {"unknown", "expiring", "expired"}:
+            continue
+        event_type = "session_info_expired" if health.status == "expired" else "session_info_expiring"
+        state_label = "expirado" if health.status == "expired" else "a expirar"
+        title = f"SessionInfo {state_label}: {health.account_label}"
+        entry = record_notification(
+            event_type,
+            title,
+            health.message,
+            metadata={
+                "account_id": health.account_id,
+                "account_label": health.account_label,
+                "status": health.status,
+                "captured_at": health.captured_at or "",
+                "expires_at": health.expires_at or "",
+            },
+            dedupe_key=f"session-info:{health.account_id}:{health.status}:{day}",
+        )
+        if entry:
+            created.append(entry)
+    return created
+
+
+__all__ = [
+    "DEFAULT_SESSION_INFO_ALERT_HOURS",
+    "DEFAULT_SESSION_INFO_TTL_HOURS",
+    "MAX_SESSION_INFO_TTL_HOURS",
+    "MIN_SESSION_INFO_TTL_HOURS",
+    "SessionInfoHealth",
+    "check_account_session_info_health",
+    "check_all_accounts_session_info_health",
+    "emit_session_info_health_alerts",
+    "health_check_session_info",
+    "parse_timestamp",
+    "session_info_health_from_settings",
+]

package/integrations/upload_routing.py

@@ -14,6 +14,7 @@ from typing import Any, Callable
 
 from integrations.platforms import IntegrationResult, YouTubeAdapter
 from integrations.postiz import PostizAdapter
+from integrations.session_info_health import check_account_session_info_health, emit_session_info_health_alerts
 from integrations.youtube_direct_credentials import document_status
 from integrations.youtube_direct_upload import YouTubeDirectUploader
 from hermes_ui.storage import read_json, write_json
@@ -126,8 +127,16 @@ def upload_with_default_route(
     if account:
         try:
             status = document_status(storage_root, account, channel, settings, [channel])
-            direct_ready = bool(status.get("ready"))
-            if not direct_ready:
+            health = check_account_session_info_health(storage_root, account, settings)
+            emit_session_info_health_alerts([health])
+            direct_ready = bool(status.get("ready")) and health.status != "expired"
+            if health.status == "expired":
+                direct_result = IntegrationResult(
+                    False,
+                    f"Upload directo indisponível: {health.message}",
+                    {"missing": ["sessionInfo"], "session_info_health": health.as_dict()},
+                )
+            elif not direct_ready:
                 missing = list(status.get("missing_cookies", []))
                 if not status.get("has_session_info"):
                     missing.append("sessionInfo")

package/integrations/youtube_direct_credentials.py

@@ -5,9 +5,12 @@ import os
 import re
 import secrets
 import shutil
+from datetime import datetime, timezone
 from pathlib import Path
 from typing import Any
 
+from hermes_ui.storage import atomic_write
+
 COOKIE_KEYS = ("SID", "SSID", "HSID", "APISID", "SAPISID")
 DIRECT_DOCUMENT_NAME = "credentials.json"
 DEFAULT_CHUNK_SIZE = 262144
@@ -32,6 +35,10 @@ def cookie_file_path(storage_root: Path, account: dict[str, Any]) -> Path:
     return account_directory(storage_root, account) / "cookies.json"
 
 
+def _session_info_now() -> str:
+    """Return the UTC timestamp recorded when a sessionInfo token is saved."""
+    return datetime.now(timezone.utc).isoformat()
+
 def _placeholder_to_empty(value: Any) -> str:
     text = str(value or "").strip()
     if text in {"...", "…", "<preencher>", "<valor>"}:
@@ -177,6 +184,7 @@ def _normalise_document(raw: Any, account: dict[str, Any]) -> dict[str, Any]:
         "account_id": str(raw.get("account_id") or account.get("id") or "").strip(),
         "email": str(raw.get("email") or account.get("email") or "").strip(),
         "sessionInfo": _placeholder_to_empty(raw.get("sessionInfo") or raw.get("session_info") or raw.get("direct_session_info") or _account_session_info(account)),
+        "sessionInfoCapturedAt": str(raw.get("sessionInfoCapturedAt") or raw.get("session_info_captured_at") or account.get("sessionInfoCapturedAt") or account.get("session_info_captured_at") or "").strip(),
         "cookies": {key: cookies.get(key, "") for key in COOKIE_KEYS},
         "INNERTUBE_API_KEY": _placeholder_to_empty(raw.get("INNERTUBE_API_KEY") or raw.get("innertube_api_key") or raw.get("direct_innertube_api_key") or ""),
         "chunk_size": _safe_chunk_size(raw.get("chunk_size", raw.get("direct_chunk_size", DEFAULT_CHUNK_SIZE))),
@@ -204,6 +212,7 @@ def _legacy_document(storage_root: Path, account: dict[str, Any], settings: dict
         "account_id": account.get("id"),
         "email": account.get("email"),
         "sessionInfo": _account_session_info(account) or settings.get("direct_session_info"),
+        "sessionInfoCapturedAt": account.get("sessionInfoCapturedAt") or settings.get("direct_session_info_captured_at") or "",
         "cookies": legacy_cookies,
         "INNERTUBE_API_KEY": settings.get("direct_innertube_api_key"),
         "chunk_size": settings.get("direct_chunk_size", DEFAULT_CHUNK_SIZE),
@@ -219,18 +228,13 @@ def save_credentials_document(storage_root: Path, account: dict[str, Any], docum
         "account_id": normalised["account_id"],
         "email": normalised["email"],
         "sessionInfo": normalised["sessionInfo"],
+        "sessionInfoCapturedAt": normalised.get("sessionInfoCapturedAt", ""),
         "cookies": normalised["cookies"],
         # INNERTUBE_API_KEY não pertence ao documento de cookies/credenciais.
         "chunk_size": normalised["chunk_size"],
         "delegated_session_ids": normalised["delegated_session_ids"],
     }
-    temporary = destination.with_name(f".{destination.name}.{secrets.token_hex(6)}.tmp")
-    temporary.write_text(json.dumps(payload, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
-    try:
-        os.chmod(temporary, 0o600)
-    except OSError:
-        pass
-    temporary.replace(destination)
+    atomic_write(destination, payload)
     try:
         os.chmod(destination, 0o600)
     except OSError:
@@ -239,13 +243,15 @@ def save_credentials_document(storage_root: Path, account: dict[str, Any], docum
 
 
 def update_credentials_document_session_info(storage_root: Path, account: dict[str, Any], session_info: str) -> Path | None:
-    """Update only sessionInfo in an existing credentials document."""
+    """Save sessionInfo and its UTC capture time without exposing the token."""
     path = credentials_document_path(storage_root, account)
-    if not path.exists():
-        return None
-    raw = _read_json_document(path) or {}
+    if path.exists():
+        raw = _read_json_document(path) or {}
+    else:
+        raw = load_credentials_document(storage_root, {**account, "sessionInfo": session_info}, create=True)
     document = _normalise_document(raw, {**account, "sessionInfo": session_info})
     document["sessionInfo"] = str(session_info or "").strip()
+    document["sessionInfoCapturedAt"] = _session_info_now() if document["sessionInfo"] else ""
     return save_credentials_document(storage_root, account, document)
 
 
@@ -326,8 +332,13 @@ def merge_credentials_document(
         if incoming["cookies"].get(key):
             merged["cookies"][key] = incoming["cookies"][key]
     incoming_session = _placeholder_to_empty(session_info_override) or incoming.get("sessionInfo", "")
+    previous_session = str(merged.get("sessionInfo") or "").strip()
     if incoming_session:
         merged["sessionInfo"] = incoming_session
+        if incoming_session != previous_session or not merged.get("sessionInfoCapturedAt"):
+            merged["sessionInfoCapturedAt"] = _session_info_now()
+    elif not merged.get("sessionInfo"):
+        merged["sessionInfoCapturedAt"] = ""
     # INNERTUBE_API_KEY recebida num JSON é deliberadamente ignorada: a fonte oficial
     # é a configuração separada da secção Contas Google/YouTube.
     if "chunk_size" in raw:

package/integrations/youtube_direct_upload.py

@@ -10,6 +10,7 @@ from pathlib import Path
 from typing import Any
 
 from integrations.youtube_direct_credentials import COOKIE_KEYS, account_innertube_api_key, delegated_session_id, load_credentials_document
+from integrations.session_info_health import session_info_health_from_settings
 from urllib.parse import quote
 
 import requests
@@ -201,11 +202,23 @@ class YouTubeDirectUploader:
         validation_error = validate_direct_upload(path, self.channel, self.settings, self.account, self.storage_root)
         if validation_error:
             return DirectUploadResult(False, validation_error, {"mechanism": "youtube-frontend-direct"})
+        session_health = session_info_health_from_settings(
+            self.account or {},
+            self.document,
+            self.settings,
+            credential_file=(str(self.storage_root) if self.storage_root else ""),
+        )
+        if session_health.status == "expired":
+            return DirectUploadResult(
+                False,
+                f"Upload directo bloqueado: {session_health.message}",
+                {"mechanism": "youtube-frontend-direct", "session_info_health": session_health.as_dict()},
+            )
         try:
             self.describe_file(path)
             self.create_video(title, description, visibility)
             configured_chunk_size = int(chunk_size or self.document.get("chunk_size") or CHUNK_GRANULARITY)
             self.upload_chunks(path, configured_chunk_size)
-            return DirectUploadResult(True, f"Upload directo concluído: {self.video_id}", {"mechanism": "youtube-frontend-direct", "video_id": self.video_id, "page_id": self.channel.get("delegated_session_id", ""), "google_account_id": (self.account or {}).get("id", "")})
+            return DirectUploadResult(True, f"Upload directo concluído: {self.video_id}", {"mechanism": "youtube-frontend-direct", "video_id": self.video_id, "page_id": self.channel.get("delegated_session_id", ""), "google_account_id": (self.account or {}).get("id", ""), "session_info_health": session_health.as_dict()})
         except (requests.RequestException, OSError, ValueError, RuntimeError) as exc:
             return DirectUploadResult(False, f"Upload directo falhou: {exc}", {"mechanism": "youtube-frontend-direct", "video_id": self.video_id})

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danhachuel/thunderbolt",
-  "version": "0.3.73",
+  "version": "0.3.74",
   "description": "Thunderbolt — interface local para operação de canais faceless e motor MoneyPrinterTurbo",
   "license": "MIT",
   "main": "scripts/cli.mjs",