@danhachuel/thunderbolt 0.3.36 → 0.3.37

package/.streamlit/config.toml

@@ -1,5 +1,4 @@
 [theme]
-base = "dark"
 font = "sans serif"
 
 [theme.dark]

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.36
+> **Versão deste manual:** 0.3.37
 > **Pacote npm:** `@danhachuel/thunderbolt`
 > **Porta padrão da UI:** `localhost:3030`  
 > **Repositório:** [github.com/DanHachuel/thunderbolt](https://github.com/DanHachuel/thunderbolt)
@@ -100,13 +100,13 @@ Execute:
 Windows PowerShell ou MobaXterm:
 
 ```powershell
-npx.cmd --yes @danhachuel/thunderbolt@0.3.36 install
+npx.cmd --yes @danhachuel/thunderbolt@0.3.37 install
 ```
 
 Linux/macOS:
 
 ```bash
-npx --yes @danhachuel/thunderbolt@0.3.36 install
+npx --yes @danhachuel/thunderbolt@0.3.37 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.
@@ -200,7 +200,7 @@ Todas as subabas internas e o conteúdo das páginas também são traduzidos nos
 
 ### Temas Light e Dark
 
-A aplicação usa o mecanismo nativo de temas do Streamlit e é distribuída com `.streamlit/config.toml`, seguindo o padrão de configuração do [MoneyPrinterTurbo](https://github.com/harry0703/MoneyPrinterTurbo). O ficheiro define **Dark** como base inicial. A alternância para **Light** e o regresso a **Dark** ficam exclusivamente no menu nativo de três pontos do Streamlit, no local original do toolbar; não existe um selector Theme dentro da página. Os componentes próprios da UI herdam as cores do tema activo através de `currentColor` e `color-mix`. O toolbar nativo, o indicador de execução, **Deploy** e o menu principal continuam sem sobreposições CSS.
+A aplicação usa o mecanismo nativo de temas do Streamlit e é distribuída com `.streamlit/config.toml`, seguindo o padrão de configuração do [MoneyPrinterTurbo](https://github.com/harry0703/MoneyPrinterTurbo). O ficheiro disponibiliza as variantes nomeadas **Dark** e **Light**. A alternância entre elas fica exclusivamente no menu nativo de três pontos do Streamlit, no local original do toolbar; não existe um selector Theme dentro da página. Os componentes próprios da UI herdam as cores do tema activo através de `currentColor` e `color-mix`. O toolbar nativo, o indicador de execução, **Deploy** e o menu principal continuam sem sobreposições CSS.
 
 ## 4. Diagnóstico antes de iniciar
 
@@ -386,6 +386,16 @@ Na primeira execução, a barra lateral apresenta **Início**, **Niche Finder**,
 | Telegram Proxy | Proxy HTTP/HTTPS/SOCKS opcional para ambientes sem acesso directo |
 | Telegram timeout | Limite de espera de cada envio, entre 5 e 120 segundos |
 
+### Execução do pipeline de vídeos e acompanhamento
+
+Ao clicar em **Start** no **Backlog Vídeos**, a tarefa passa para `doing` e é processada pelo worker de pipeline iniciado pelo launcher normal. O worker grava o estado em `storage/state/pipeline_worker.json` e actualiza `updated_at`, a etapa e a percentagem em `storage/state/tasks.json`. O painel do Backlog consulta esse estado automaticamente a cada cinco segundos e mostra o worker, a etapa corrente, a percentagem, a idade da actualização e a mensagem de erro quando existe.
+
+A percentagem representa o avanço conhecido do pipeline: tema, roteiro, título/keywords, thumbnail, vídeo e upload. Durante a chamada longa ao MoneyPrinterTurbo, a UI mantém um heartbeat a cada cinco segundos e avança apenas dentro da faixa reservada à geração do vídeo; não apresenta 100% antes de existir um MP4 válido. O worker passa explicitamente a **Pasta do motor de vídeo** configurada na UI ao helper, por isso o clone usado, os logs e o manifesto pertencem à instalação seleccionada pelo utilizador.
+
+Uma execução da etapa Vídeo tem limite de 20 minutos. Se o processo externo terminar com erro, exceder o limite, devolver um resultado inválido ou ocorrer uma excepção inesperada, a tarefa é marcada como `failed`, com a etapa em `failed_stage`. As últimas linhas devolvidas pelo helper, sem as credenciais configuradas, são guardadas num artefacto `video-diagnostics` e as referências `video_log`/`video_result` ficam associadas à tarefa. Se o utilizador clicar em **Stop**, a tarefa passa para `blocked`, o subprocesso é terminado cooperativamente e o worker não substitui esse estado por `failed`.
+
+Se o launcher ou o worker for encerrado abruptamente, uma tarefa `doing` sem actualização durante 25 minutos é recuperada e marcada como `failed`, evitando estados indefinidos eternos. Para processar novas tarefas, deixe a aplicação iniciada com o comando normal; o painel avisa quando não existe heartbeat recente do worker.
+
 ### Upload Música — JewelMusic, Pushtunes e ytmusicapi
 
 A área **Pipeline Música > Upload Música** separa três métodos com contratos diferentes. Em **JewelMusic**, active a integração, introduza a API Key fornecida pelo dashboard da JewelMusic e confirme a Base URL oficial `https://api.jewelmusic.com` e, se necessário, configure proxy e timeout. Carregue ou seleccione um ficheiro de música, indique artista e título e clique em **Enviar música para JewelMusic**. O teste de ligação consulta `/v1/ping`; o upload envia `multipart/form-data` para `/v1/tracks/upload` com os metadados preenchidos.
@@ -471,7 +481,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 @danhachuel/thunderbolt@0.3.36 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 @danhachuel/thunderbolt@0.3.37 install`; o instalador detecta e reutiliza o que já estiver válido.
 
 ### Niche Finder Apify
 

package/README.md

@@ -12,6 +12,7 @@ A primeira versão implementa a camada UI independente com:
 |---|---|
 | Início | Resumo de canais, tarefas, backlog, execução e falhas, com as filas do Pipeline inline |
 | Pipeline Vídeos | Menu expansível com Criação de Vídeos, Backlog Vídeos, Roteiros, Thumbnails e Upload |
+| Worker de vídeo | Heartbeat persistido, barra de progresso por etapas, timeout de 20 minutos, recuperação de tarefas abandonadas e diagnóstico bounded do helper MoneyPrinterTurbo |
 | Pipeline Música | Menu expansível com Criação de Músicas e Upload Música |
 | Blueprints Youtube | Leitura da pasta `storage/blueprints/`, upload/validação de JSON e criação a partir de link YouTube |
 | Brandings | Subaba própria dentro de Blueprints, upload/listagem de Brandings e criação conjunta com Blueprint |
@@ -66,9 +67,9 @@ No topo da área principal da aplicação existe o menu nativo de idioma no padr
 
 ## Temas claro e escuro
 
-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` define **Dark** como base inicial 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.
+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.36
+## Navegação da UI 0.3.37
 
 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**, **Redes Sociais**, **Tutorial Meta** e **Tutorial Supabase**, nessa ordem. **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**, **Configuração API** e **Notificações**. O Início reúne o dashboard e as filas do Pipeline, sem botões de acções rápidas.
 

package/app/main.py

@@ -6,7 +6,7 @@ import json
 import mimetypes
 import re
 from contextlib import nullcontext
-from datetime import date, datetime
+from datetime import date, datetime, timezone
 import sys
 import uuid
 from pathlib import Path
@@ -26,6 +26,7 @@ except (OSError, json.JSONDecodeError):
 from hermes_ui.domain import STAGES, create_batch, create_channel, create_tasks_for_batch, delete_channel, pipeline_summary, set_channel_defaults, transition_task, update_channel, update_channel_video
 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 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
@@ -2449,6 +2450,7 @@ def render_new_video(page_title: str = "Criação de Vídeos", prefix: str = "ne
                         tasks = create_tasks_for_batch(batch)
                         st.success(f"Lote {batch['id']} criado com {len(tasks)} tarefa(s). Abra {ui_text('Backlog Vídeos', current_ui_language())} para acompanhar.")
 
+    _render_pipeline_progress_panel()
     if draft_tab is not None:
         with draft_tab:
             render_video_from_draft()
@@ -3315,10 +3317,106 @@ def render_python_editor():
                 st.error(str(exc))
 
 
+_PIPELINE_STAGE_LABELS = {
+    "niche": "Tema",
+    "blueprint": "Blueprint",
+    "brand": "Branding",
+    "topic": "Tema",
+    "script": "Roteiro",
+    "title": "Título",
+    "keywords": "Keywords",
+    "thumbnail_prompt": "Prompt da thumbnail",
+    "thumbnail": "Thumbnail",
+    "video": "Vídeo",
+    "edit": "Edição",
+    "upload": "Upload",
+    "idle": "A aguardar",
+}
+
+
+def _pipeline_progress_value(task: dict[str, Any]) -> int:
+    try:
+        return max(0, min(100, int(task.get("progress") or 0)))
+    except (TypeError, ValueError):
+        return 0
+
+
+def _pipeline_stage_label(task: dict[str, Any]) -> str:
+    stage = str(task.get("stage") or "pipeline")
+    return _PIPELINE_STAGE_LABELS.get(stage, stage.replace("_", " ").title())
+
+
+def _pipeline_time_age(value: Any) -> str:
+    text = str(value or "").strip()
+    if not text:
+        return "sem actualização registada"
+    try:
+        parsed = datetime.fromisoformat(text)
+        if parsed.tzinfo is None:
+            parsed = parsed.replace(tzinfo=timezone.utc)
+        seconds = max(0, int((datetime.now(timezone.utc) - parsed.astimezone(timezone.utc)).total_seconds()))
+    except ValueError:
+        return f"última actualização: {text}"
+    if seconds < 60:
+        return f"actualizado há {seconds}s"
+    if seconds < 3600:
+        return f"actualizado há {seconds // 60}min"
+    return f"actualizado há {seconds // 3600}h"
+
+
+def _render_pipeline_worker_banner(worker_status: dict[str, Any], active_count: int) -> None:
+    if worker_status.get("alive"):
+        stage = _PIPELINE_STAGE_LABELS.get(str(worker_status.get("stage") or "idle"), str(worker_status.get("stage") or "idle"))
+        progress = max(0, min(100, int(worker_status.get("progress") or 0)))
+        st.success(f"Worker de vídeo activo · {active_count} tarefa(s) em execução · {stage} · {progress}%")
+    else:
+        st.warning("Worker de vídeo sem heartbeat recente. O launcher deve estar aberto para processar as tarefas.")
+    heartbeat = worker_status.get("last_heartbeat_at") or worker_status.get("updated_at")
+    if heartbeat:
+        st.caption(f"{_pipeline_time_age(heartbeat)} · timeout de execução: {STALE_TASK_SECONDS // 60} minutos")
+    if worker_status.get("last_error"):
+        st.error(f"Último erro do worker: {worker_status['last_error']}")
+
+
+@st.fragment(run_every=5.0)
+def _render_pipeline_progress_live() -> None:
+    """Poll the persisted pipeline state only while video tasks are active."""
+    worker_status = load_pipeline_worker_status()
+    tasks = read_json("tasks.json", [])
+    active = [task for task in tasks if isinstance(task, dict) and str(task.get("state") or "") == "doing"]
+    if not worker_status.get("alive") and active:
+        recovered = recover_stale_tasks()
+        if recovered:
+            tasks = read_json("tasks.json", [])
+            active = [task for task in tasks if isinstance(task, dict) and str(task.get("state") or "") == "doing"]
+            worker_status = load_pipeline_worker_status()
+    if not active:
+        # A fragment that was already polling must stop itself after the worker
+        # reaches done/failed; otherwise Streamlit keeps refreshing an obsolete
+        # fragment even though the page no longer renders an active task.
+        st.rerun(scope="app")
+        return
+    _render_pipeline_worker_banner(worker_status, len(active))
+    for task in active:
+        progress = _pipeline_progress_value(task)
+        label = str(task.get("title") or task.get("topic") or task.get("id") or "Vídeo")
+        st.progress(progress, text=f"{label} · {_pipeline_stage_label(task)} · {progress}%")
+        st.caption(f"{task.get('channel_name') or 'Canal'} · {_pipeline_time_age(task.get('updated_at'))}")
+        if task.get("error"):
+            st.error(str(task.get("error")))
+
+
+def _render_pipeline_progress_panel() -> None:
+    tasks = read_json("tasks.json", [])
+    if any(isinstance(task, dict) and str(task.get("state") or "") == "doing" for task in tasks):
+        _render_pipeline_progress_live()
+
+
 def render_videos():
     st.subheader("Backlog Videos")
     st.caption("Acompanhamento dos vídeos criados, estados da pipeline e controlos de execução.")
     st.caption(f"Os vídeos são guardados em `{STORAGE / 'videos'}`.")
+    _render_pipeline_progress_panel()
     tasks = read_json("tasks.json", [])
     if not tasks:
         st.info("Nenhum vídeo criado.")
@@ -3341,8 +3439,16 @@ def render_videos():
                     prompt_note = ' · prompt pronto' if task.get('thumbnail_prompt') else ''
                     st.caption(f"Thumbnail: {status}{prompt_note}")
             with cols[1]: st.write(task.get("format", "wide"))
-            with cols[2]: st.write(task.get("stage", "—"))
-            with cols[3]: st.write(task.get("state", "—"))
+            with cols[2]:
+                st.write(_pipeline_stage_label(task))
+                if str(task.get("state") or "") in {"to_do", "doing", "blocked"}:
+                    progress = _pipeline_progress_value(task)
+                    st.progress(progress, text=f"{progress}%")
+            with cols[3]:
+                st.write(task.get("state", "—"))
+                if task.get("error"):
+                    st.caption(str(task.get("error"))[:240])
+
             with cols[4]:
                 state = str(task.get("state") or "")
                 start_col, stop_col = st.columns(2)

package/hermes_ui/pipeline_worker.py

@@ -2,8 +2,10 @@ from __future__ import annotations
 
 import json
 import os
+import queue
 import re
 import subprocess
+import threading
 import time
 from datetime import datetime, timezone
 from pathlib import Path
@@ -20,13 +22,18 @@ from hermes_ui.thumbnail_generation import generate_thumbnail_image
 PIPELINE_LOCK_FILENAME = "pipeline_worker.lock"
 PIPELINE_LOG_FILENAME = "pipeline_worker.json"
 VIDEO_TIMEOUT_SECONDS = 20 * 60
-STALE_TASK_SECONDS = 2 * 60 * 60
+STALE_TASK_SECONDS = VIDEO_TIMEOUT_SECONDS + 5 * 60
+WORKER_HEARTBEAT_TIMEOUT_SECONDS = 15
 
 
 class PipelineError(RuntimeError):
     """Raised when a pipeline stage cannot complete with an actionable error."""
 
 
+class PipelineStopped(PipelineError):
+    """Raised when the user stops a task while the worker is processing it."""
+
+
 def _now() -> str:
     return datetime.now(timezone.utc).isoformat()
 
@@ -41,16 +48,45 @@ def _lock_path() -> Path:
     return STORAGE / "state" / PIPELINE_LOCK_FILENAME
 
 
+def _pid_alive(pid: int) -> bool:
+    if pid <= 0:
+        return False
+    try:
+        os.kill(pid, 0)
+    except ProcessLookupError:
+        return False
+    except PermissionError:
+        return True
+    except OSError:
+        return False
+    return True
+
+
 def _acquire_lock() -> Path | None:
     path = _lock_path()
     path.parent.mkdir(parents=True, exist_ok=True)
     try:
         descriptor = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY)
+    except FileExistsError:
+        try:
+            old_pid = int(path.read_text(encoding="utf-8").strip())
+        except (OSError, ValueError):
+            old_pid = 0
+        if _pid_alive(old_pid):
+            return None
+        try:
+            path.unlink()
+        except OSError:
+            return None
+        try:
+            descriptor = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY)
+        except FileExistsError:
+            return None
+    try:
         os.write(descriptor, str(os.getpid()).encode("ascii"))
+    finally:
         os.close(descriptor)
-        return path
-    except FileExistsError:
-        return None
+    return path
 
 
 def _write_worker_state(**updates: Any) -> None:
@@ -62,6 +98,71 @@ def _write_worker_state(**updates: Any) -> None:
     write_json(PIPELINE_LOG_FILENAME, state)
 
 
+def _worker_heartbeat(**updates: Any) -> None:
+    _write_worker_state(
+        worker_pid=os.getpid(),
+        last_heartbeat_at=_now(),
+        **updates,
+    )
+
+
+def _parse_timestamp(value: Any) -> datetime | None:
+    text = str(value or "").strip()
+    if not text:
+        return None
+    try:
+        parsed = datetime.fromisoformat(text)
+    except ValueError:
+        return None
+    return parsed if parsed.tzinfo else parsed.replace(tzinfo=timezone.utc)
+
+
+def load_pipeline_worker_status() -> dict[str, Any]:
+    """Return the persisted worker heartbeat for the Backlog UI."""
+    status = read_json(PIPELINE_LOG_FILENAME, {})
+    if not isinstance(status, dict):
+        status = {}
+    heartbeat_at = _parse_timestamp(status.get("last_heartbeat_at"))
+    status["alive"] = bool(
+        heartbeat_at
+        and (datetime.now(timezone.utc) - heartbeat_at.astimezone(timezone.utc)).total_seconds()
+        <= WORKER_HEARTBEAT_TIMEOUT_SECONDS
+    )
+    return status
+
+
+def _recover_stale_tasks() -> list[str]:
+    """Convert abandoned doing tasks to failed after the worker timeout window."""
+    from hermes_ui.domain import update_task
+
+    recovered: list[str] = []
+    current_time = datetime.now(timezone.utc)
+    for task in read_json("tasks.json", []):
+        if not isinstance(task, dict) or str(task.get("state") or "") != "doing":
+            continue
+        updated_at = _parse_timestamp(task.get("updated_at"))
+        if not updated_at:
+            continue
+        age_seconds = (current_time - updated_at.astimezone(timezone.utc)).total_seconds()
+        if age_seconds <= STALE_TASK_SECONDS:
+            continue
+        task_id = str(task.get("id") or "")
+        if not task_id:
+            continue
+        message = (
+            f"A tarefa ficou sem heartbeat durante mais de {STALE_TASK_SECONDS // 60} minutos. "
+            "Foi marcada como falhada para evitar execução eterna; reveja o log do worker."
+        )
+        update_task(task_id, {"state": "failed", "error": message, "failed_stage": task.get("stage") or "pipeline"})
+        recovered.append(task_id)
+    return recovered
+
+
+def recover_stale_tasks() -> list[str]:
+    """Public wrapper used by the UI to recover tasks after an abrupt worker exit."""
+    return _recover_stale_tasks()
+
+
 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)
 
@@ -69,9 +170,20 @@ def _task_by_id(task_id: str) -> dict[str, Any] | None:
 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.")
     updated = update_task(task_id, updates)
     if not updated:
         raise PipelineError(f"Tarefa {task_id} deixou de existir durante a execução.")
+    _worker_heartbeat(
+        task_id=task_id,
+        status="running",
+        stage=str(updated.get("stage") or "pipeline"),
+        progress=int(updated.get("progress") or 0),
+    )
     return updated
 
 
@@ -111,6 +223,75 @@ def _save_json_artifact(task_id: str, name: str, payload: dict[str, Any]) -> str
     return str(path)
 
 
+def _configured_moneyprinter_root(settings: dict[str, Any]) -> Path | None:
+    """Resolve the installed MoneyPrinterTurbo project selected by the user."""
+    configured = str(settings.get("moneyprinter_path") or os.environ.get("MONEYPRINTER_PATH") or "").strip()
+    if not configured:
+        return None
+    root = Path(configured).expanduser().resolve()
+    if not (root / "cli.py").is_file():
+        raise PipelineError(f"A pasta configurada do MoneyPrinterTurbo não contém cli.py: {root}")
+    if not ((root / "config.toml").is_file() or (root / "config.example.toml").is_file()):
+        raise PipelineError(f"A pasta configurada do MoneyPrinterTurbo não contém config.toml: {root}")
+    return root
+
+
+def _helper_output_value(output: str, key: str) -> str:
+    match = re.search(rf"(?m)^{re.escape(key)}=(.+)$", output)
+    return match.group(1).strip() if match else ""
+
+
+def _redact_helper_output(text: str) -> str:
+    for key in ("MPT_LLM_API_KEY", "MPT_PEXELS_API_KEY"):
+        secret = os.environ.get(key, "").strip()
+        if secret:
+            text = text.replace(secret, "[redacted]")
+    return text
+
+
+def _persist_video_diagnostics(task: dict[str, Any], output: str) -> dict[str, str]:
+    """Persist only bounded helper diagnostics and return its declared file paths."""
+    task_id = str(task.get("id") or "").strip()
+    if not task_id:
+        return {}
+    log_file = _helper_output_value(output, "LOG_FILE")
+    result_file = _helper_output_value(output, "RESULT_FILE")
+    try:
+        payload: dict[str, Any] = {
+            "captured_at": _now(),
+            "log_file": log_file,
+            "result_file": result_file,
+            "output_tail": _redact_helper_output(output[-6000:]),
+        }
+        artifact_path = _save_json_artifact(task_id, "video-diagnostics", payload)
+        current = _task_by_id(task_id) or task
+        artifacts = dict(current.get("artifacts") or {})
+        artifacts["video_diagnostics"] = artifact_path
+        updates: dict[str, Any] = {"artifacts": artifacts}
+        if log_file:
+            updates["video_log"] = log_file
+            artifacts["video_log"] = log_file
+        if result_file:
+            updates["video_result"] = result_file
+            artifacts["video_result"] = result_file
+        from hermes_ui.domain import update_task
+        update_task(task_id, updates)
+        return {"log_file": log_file, "result_file": result_file, "artifact": artifact_path}
+    except Exception:
+        # Diagnostics must never hide the actual generation error.
+        return {"log_file": log_file, "result_file": result_file}
+
+
+def _stop_process(process: subprocess.Popen[str]) -> None:
+    if process.poll() is None:
+        process.kill()
+    try:
+        process.wait(timeout=5)
+    except subprocess.TimeoutExpired:
+        process.kill()
+        process.wait()
+
+
 def _run_video_helper(task: dict[str, Any]) -> Path:
     helper_dir = Path(__file__).resolve().parents[1] / "seed" / "skills"
     helper = helper_dir / "mpt_agent.py"
@@ -120,6 +301,10 @@ def _run_video_helper(task: dict[str, Any]) -> Path:
     if not subject:
         raise PipelineError("A etapa Vídeo não recebeu um tema válido.")
     settings = _settings()
+    configured_root = _configured_moneyprinter_root(settings)
+    task_id = str(task.get("id") or "").strip()
+    if not task_id:
+        raise PipelineError("A tarefa de vídeo não tem um identificador válido.")
     env = os.environ.copy()
     card = active_llm_card(settings)
     provider = str(card.get("provider") or "openai").strip()
@@ -134,23 +319,97 @@ def _run_video_helper(task: dict[str, Any]) -> Path:
     for key, value in env_values.items():
         if value:
             env[key] = value
-    command = ["uv", "run", "--no-project", "--python", "3.11", "python", "mpt_agent.py", "--subject", subject]
+    command = ["uv", "run", "--no-project", "--python", "3.11", "python", "mpt_agent.py"]
+    if configured_root:
+        command.extend(["--root", str(configured_root)])
+    command.extend(["--subject", subject])
+    output_lines: list[str] = []
+    line_queue: queue.Queue[str | None] = queue.Queue()
+    started_at = time.monotonic()
+    process: subprocess.Popen[str] | None = None
+
+    def _read_output() -> None:
+        if process is None or process.stdout is None:
+            line_queue.put(None)
+            return
+        for line in iter(process.stdout.readline, ""):
+            line_queue.put(line.rstrip())
+        process.stdout.close()
+        line_queue.put(None)
+
     try:
-        result = subprocess.run(command, cwd=helper_dir, env=env, capture_output=True, text=True, timeout=VIDEO_TIMEOUT_SECONDS, check=False)
+        process = subprocess.Popen(
+            command,
+            cwd=helper_dir,
+            env=env,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            text=True,
+            bufsize=1,
+        )
     except FileNotFoundError as exc:
         raise PipelineError("O comando uv não está instalado; não foi possível iniciar a geração de vídeo.") from exc
-    except subprocess.TimeoutExpired as exc:
-        raise PipelineError(f"A etapa Vídeo excedeu o limite de {VIDEO_TIMEOUT_SECONDS // 60} minutos e foi encerrada.") from exc
-    output = "\n".join(part for part in (result.stdout, result.stderr) if part)
-    if result.returncode == 10:
+
+    reader = threading.Thread(target=_read_output, name=f"mpt-output-{task.get('id', 'video')}", daemon=True)
+    reader.start()
+    output_finished = False
+    last_heartbeat = 0.0
+    try:
+        while True:
+            try:
+                line = line_queue.get(timeout=0.5)
+                if line is None:
+                    output_finished = True
+                elif line:
+                    output_lines.append(line)
+            except queue.Empty:
+                pass
+            elapsed = time.monotonic() - started_at
+            if elapsed - last_heartbeat >= 5:
+                # O helper expõe o resultado final, mas não uma percentagem estável.
+                # Mantemos uma faixa reservada para a etapa de vídeo e avançamos-a
+                # lentamente enquanto o processo responde, sem fingir conclusão.
+                video_progress = min(79, 68 + int(elapsed // 15))
+                current_task = _task_by_id(task_id)
+                if current_task and str(current_task.get("state") or "") in {"blocked", "cancelled"}:
+                    _stop_process(process)
+                    raise PipelineStopped("A tarefa foi parada pelo utilizador.")
+                _update(
+                    task_id,
+                    progress=video_progress,
+                    video_elapsed_seconds=int(elapsed),
+                )
+                _worker_heartbeat(
+                    task_id=str(task.get("id") or ""),
+                    status="running",
+                    stage="video",
+                    progress=video_progress,
+                    video_elapsed_seconds=int(elapsed),
+                )
+                last_heartbeat = elapsed
+            if process.poll() is not None and output_finished:
+                break
+            if elapsed >= VIDEO_TIMEOUT_SECONDS:
+                _stop_process(process)
+                raise PipelineError(f"A etapa Vídeo excedeu o limite de {VIDEO_TIMEOUT_SECONDS // 60} minutos e foi encerrada.")
+    finally:
+        reader.join(timeout=2)
+        _persist_video_diagnostics(task, "\n".join(output_lines))
+    if process.returncode is None:
+        process.wait(timeout=5)
+    result_code = process.returncode
+    output = "\n".join(output_lines)
+    _persist_video_diagnostics(task, output)
+    if result_code == 10:
         raise PipelineError("A geração de vídeo precisa de credenciais adicionais do MoneyPrinterTurbo.")
-    if result.returncode != 0:
-        detail = output[-1200:].strip() or "erro sem detalhes devolvidos pelo helper"
+    if result_code != 0:
+        detail = _redact_helper_output(output[-1200:]).strip() or "erro sem detalhes devolvidos pelo helper"
         raise PipelineError(f"MoneyPrinterTurbo falhou na etapa Vídeo: {detail}")
     match = re.search(r"(?m)^VIDEO_FILE=(.+)$", output)
     video_path = Path(match.group(1).strip()).expanduser() if match else None
     if not video_path or not video_path.is_file() or video_path.stat().st_size <= 0:
-        result_file = Path.home() / "MoneyPrinterTurbo" / ".agent-logs" / "moneyprinterturbo-video" / "latest-result.json"
+        result_root = configured_root or (Path.home() / "MoneyPrinterTurbo")
+        result_file = result_root / ".agent-logs" / "moneyprinterturbo-video" / "latest-result.json"
         if result_file.is_file():
             try:
                 payload = json.loads(result_file.read_text(encoding="utf-8"))
@@ -285,23 +544,33 @@ def run_once() -> dict[str, Any]:
     if lock is None:
         return {"ok": True, "busy": True}
     try:
+        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)
         if not candidate:
-            _write_worker_state(last_task_id=None, last_error="", status="idle")
-            return {"ok": True, "status": "idle"}
+            _worker_heartbeat(last_task_id=None, last_error="", status="idle", stage="idle", progress=0, recovered_task_ids=recovered)
+            return {"ok": True, "status": "idle", "recovered_task_ids": recovered}
         task_id = str(candidate.get("id") or "")
-        _write_worker_state(last_task_id=task_id, status="running", last_error="")
+        _worker_heartbeat(last_task_id=task_id, status="running", stage=str(candidate.get("stage") or "pipeline"), progress=int(candidate.get("progress") or 0), last_error="", recovered_task_ids=recovered)
         try:
             result = _run_task(candidate)
-            _write_worker_state(status="completed", last_error="")
-            return {"ok": True, "task_id": task_id, "task": result}
+            _worker_heartbeat(status="completed", last_error="", stage=str(result.get("stage") or "upload"), progress=100, task_id=task_id)
+            return {"ok": True, "task_id": task_id, "task": result, "recovered_task_ids": recovered}
+        except PipelineStopped as exc:
+            current_task = _task_by_id(task_id) or candidate
+            current_state = str(current_task.get("state") or "")
+            if current_state not in {"blocked", "cancelled"}:
+                from hermes_ui.domain import update_task
+                update_task(task_id, {"state": "blocked", "error": str(exc), "failed_stage": current_task.get("stage") or "pipeline"})
+            _worker_heartbeat(status="stopped", last_error=str(exc), stage=str(current_task.get("stage") or "pipeline"), progress=int(current_task.get("progress") or 0), task_id=task_id)
+            return {"ok": True, "task_id": task_id, "status": "stopped", "recovered_task_ids": recovered}
         except Exception as exc:
             message = str(exc)[:2000]
             from hermes_ui.domain import update_task
-            update_task(task_id, {"state": "failed", "error": message})
-            _write_worker_state(status="failed", last_error=message)
-            return {"ok": False, "task_id": task_id, "error": message}
+            current_task = _task_by_id(task_id) or candidate
+            update_task(task_id, {"state": "failed", "error": message, "failed_stage": current_task.get("stage") or "pipeline"})
+            _worker_heartbeat(status="failed", last_error=message, stage=str(current_task.get("stage") or "pipeline"), progress=int(current_task.get("progress") or 0), task_id=task_id)
+            return {"ok": False, "task_id": task_id, "error": message, "recovered_task_ids": recovered}
     finally:
         try:
             lock.unlink()
@@ -311,6 +580,7 @@ def run_once() -> dict[str, Any]:
 
 def run_worker(interval_seconds: int = 5) -> None:
     ensure_storage()
+    _worker_heartbeat(status="starting", stage="idle", progress=0, last_error="")
     while True:
         run_once()
         time.sleep(max(2, int(interval_seconds)))

package/package.json

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