@danhachuel/thunderbolt 0.4.9 → 0.4.11

package/MANUAL-INSTALACAO.md

@@ -485,6 +485,8 @@ O **Backlog Vídeos** e a lista **Automação > Automação Youtube > Vídeos ca
 
 Nos dois cards, o bloco de estado apresenta o valor técnico, o rótulo legível, a barra de progresso e a mensagem de erro quando existir. O bloco **Formato** resolve nesta ordem `format`, `style_wide`, `style` e, por fim, `wide`, mantendo a apresentação de formatos como `wide`, `shorts`, `music` ou `full_ia` mesmo em tarefas antigas. Em **Automação Youtube > Vídeos cadastrados**, o botão **Start** retoma a partir dos artefactos persistidos: reutiliza roteiro, título/keywords, vídeo, prompt e thumbnail prontos e só executa novamente uma etapa cujo resultado não exista. O botão **Apagar** remove o card da fila depois de confirmação e preserva os ficheiros de artefactos; uma tarefa em execução deve ser parada antes da remoção.
 
+Não há expiração automática nem limpeza periódica de `tasks.json`. A interface e os workers usam locks de ficheiro nas actualizações read-modify-write, evitando que estados concorrentes substituam a fila por uma fotografia antiga. Em actualizações que detectem uma instalação legada, as tarefas e filas são unidas por ID mesmo que o storage novo já exista. Se o JSON protegido estiver corrompido, a cópia original é preservada e a leitura falha de forma explícita, em vez de criar uma lista vazia e apagar os dados no passo seguinte.
+
 ### Upload Música — JewelMusic, Pushtunes, ytmusicapi e DistroKid
 
 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.

package/README.md

@@ -44,7 +44,7 @@ A migração é baseada no workflow público [AI Agents A-Z — episódio 35](ht
 
 ## Pipeline de vídeo — fontes e ordem de execução
 
-Em **Pipeline Vídeos > Criação de Vídeos** e **Automação Youtube**, a opção **Pexels/Pixabay** usa a rota stock do [MoneyPrinterTurbo](https://github.com/harry0703/MoneyPrinterTurbo): as keywords do roteiro são encaminhadas para a pesquisa da fonte seleccionada, os clips são descarregados e reutilizados localmente, e o motor faz a composição com MoviePy/FFmpeg, respeitando proporção, duração máxima, concatenação, transições, correspondência visual ao roteiro, narração, legendas e música de fundo. As API keys de Pexels e Pixabay são exportadas para o `config.toml` do motor e a fonte efectiva é encaminhada por tarefa, sem depender apenas da fonte global guardada nas configurações.
+Em **Pipeline Vídeos > Criação de Vídeos** e **Automação Youtube**, a opção **Pexels/Pixabay** usa a rota stock do [MoneyPrinterTurbo](https://github.com/harry0703/MoneyPrinterTurbo): as keywords do roteiro são encaminhadas para a pesquisa da fonte seleccionada, os clips são descarregados e reutilizados localmente, e o motor faz a composição com MoviePy/FFmpeg, respeitando proporção, duração máxima, concatenação, transições, correspondência visual ao roteiro, narração, legendas e música de fundo. As API keys de Pexels e Pixabay são exportadas para o `config.toml` do motor e a fonte efectiva é encaminhada por tarefa, sem depender apenas da fonte global guardada nas configurações. Em **Configurações > Configuração API > API Keys > Imagem e Video Montagem/MoviePy**, cada cartão possui o campo **Prioridade**: o menor número aparece primeiro e a ordenação fica guardada no storage local.
 
 A ordem persistida da criação é **Tema → Script → Título → Keywords opcional → Vídeo → Prompt Thumbnail em JSON → Thumbnail → Upload**. O vídeo é materializado antes do prompt e da imagem da thumbnail; uma falha posterior de thumbnail não invalida um MP4 já pronto. **Full IA** é uma rota separada e usa o pool de vídeo configurável com **FAL AI, KIE AI, Agnes AI, Nano Banana, Replicate AI, Pollinations.ai, Hugging Face Inference API, InferencePort Proxy e HeyGen**, respeitando apenas cartões activos que declarem capacidade de vídeo. **Apenas Música** não chama a pipeline de vídeo nem tenta gerar thumbnail: reutiliza o áudio local/Suno já descarregado e deixa-o pronto para a integração de upload musical.
 
@@ -148,6 +148,8 @@ Os dois cards mostram de forma consistente o estado técnico, o rótulo legível
 
 Em **Automação Youtube > Vídeos cadastrados**, o botão **Start** retoma a tarefa a partir dos artefactos persistidos. O worker reutiliza o roteiro, título/keywords, MP4, prompt de thumbnail e imagem já existentes; só volta a gerar uma etapa quando o respectivo resultado não está disponível, e repete o upload apenas quando ele ainda não foi concluído. O botão **Apagar** remove o vídeo da fila e de `tasks.json` após confirmação, preservando os ficheiros de artefactos; tarefas em execução devem ser paradas antes de serem removidas.
 
+**Não existe expiração automática de vídeos ou limpeza periódica da fila.** As actualizações normais não usam `--purge-data`, preservam o storage local e, quando encontram uma instalação antiga juntamente com um storage novo, unem as tarefas e filas por ID em vez de substituir a lista. Se `tasks.json` ficar corrompido, a aplicação preserva a cópia danificada e interrompe a leitura protegida para evitar apresentar uma fila vazia e gravá-la por cima dos dados existentes. A remoção de uma tarefa só ocorre por confirmação explícita em **Apagar** ou pela opção destrutiva `--purge-data`.
+
 ## Canais Youtube — edição por cartão e vídeos recentes
 
 A página **Canais Youtube** mantém o cadastro e a importação existentes, mas cada cartão agora tem o botão **Editar**. O editor permite alterar nome, URL, handle, idioma, estilo wide, **Nicho**, **Blueprint Padrão**, **Narrador/Voz Padrão**, conta Google do Upload directo, descrição e Automação ON/horário. O nicho aparece imediatamente abaixo do nome do canal no cartão; quando não existe, a UI mostra **SEM NICHO CONFIGURADO**.

package/app/main.py

@@ -5617,7 +5617,7 @@ def _render_material_source_card(settings: dict[str, Any], cards: list[dict[str,
             _render_credential_status("" if is_local else card.get("api_key"), local=is_local, required=not is_local)
         card_form = nullcontext() if embedded else st.form(f"material_source_card_form_{card_id}")
         with card_form:
-            content_cols = st.columns(2)
+            content_cols = st.columns([1.4, 1.25, 0.85])
             with content_cols[0]:
                 if is_local:
                     st.caption("Esta fonte não usa API key.")
@@ -5631,6 +5631,16 @@ def _render_material_source_card(settings: dict[str, Any], cards: list[dict[str,
                     value=active_card_id == card_id,
                     key=f"material_card_{card_id}_selected",
                 )
+            with content_cols[2]:
+                priority = st.number_input(
+                    "Prioridade",
+                    min_value=1,
+                    max_value=999,
+                    value=max(1, int(card.get("priority", index + 1))),
+                    step=1,
+                    help="1 é o primeiro provider da fila. Em caso de falha elegível, os providers seguintes são considerados por ordem crescente.",
+                    key=f"material_card_{card_id}_priority",
+                )
             if not is_local:
                 _render_api_test_control(
                     settings,
@@ -5640,7 +5650,12 @@ def _render_material_source_card(settings: dict[str, Any], cards: list[dict[str,
                 )
             save_card = st.form_submit_button("Salvar", type="primary", use_container_width=True, key=f"material_card_{card_id}_save")
         if save_card:
-            cards[index] = {**card, "api_key": str(api_key or "").strip(), "enabled": bool(enabled)}
+            cards[index] = {
+                **card,
+                "api_key": str(api_key or "").strip(),
+                "enabled": bool(enabled),
+                "priority": max(1, int(priority)),
+            }
             selected_id = card_id if selected and enabled else active_card_id
             _persist_material_source_cards(settings, cards, selected_id)
             st.success(f"Fonte {definition['label']} guardada.")
@@ -5668,7 +5683,12 @@ def render_material_source_api_keys(settings: dict[str, Any], *, embedded: bool
         )
         add_source_clicked = st.form_submit_button("Configurar Nova Fonte de Materiais", type="primary", use_container_width=True, key="add_material_source_card") if embedded else st.button("Configurar Nova Fonte de Materiais", type="primary", use_container_width=True, key="add_material_source_card")
         if add_source_clicked:
-            cards.append(new_material_card(provider_to_add, card_id=f"material-{provider_to_add}-{uuid.uuid4().hex[:8]}"))
+            new_card = new_material_card(provider_to_add, card_id=f"material-{provider_to_add}-{uuid.uuid4().hex[:8]}")
+            new_card["priority"] = max(
+                (int(item.get("priority", index + 1)) for index, item in enumerate(cards)),
+                default=0,
+            ) + 1
+            cards.append(new_card)
             _persist_material_source_cards(settings, cards, str(settings.get("material_active_card_id") or ""))
             st.rerun()
 

package/hermes_ui/domain.py

@@ -5,7 +5,7 @@ import uuid
 from typing import Any
 
 from .notifications import record_notification
-from .storage import append_json, now, read_json, write_json
+from .storage import StorageIntegrityError, append_json, now, read_json, update_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
@@ -116,7 +116,6 @@ def create_batch(mode: str, channel_ids: list[str], topic: str, quantity: int, o
 
 def create_tasks_for_batch(batch: dict[str, Any]) -> list[dict[str, Any]]:
     """Expand a batch into tasks, allowing independent payloads for each channel."""
-    tasks = read_json("tasks.json", [])
     channels = {c["id"]: c for c in read_json("channels.json", [])}
     options = batch.get("options") or {}
     channel_payloads = options.get("channel_payloads") or {}
@@ -201,15 +200,26 @@ def create_tasks_for_batch(batch: dict[str, Any]) -> list[dict[str, Any]]:
                 "created_at": now(),
                 "updated_at": now(),
             }
-            tasks.append(task)
             created.append(task)
-    write_json("tasks.json", tasks)
-    queues = read_json("queues.json", {})
-    if not isinstance(queues, dict):
-        queues = {}
-    queues.setdefault("script", [])
-    queues["script"].extend(task["id"] for task in created)
-    write_json("queues.json", queues)
+
+    def persist_tasks(tasks: Any) -> list[dict[str, Any]]:
+        if not isinstance(tasks, list):
+            raise StorageIntegrityError("O ficheiro tasks.json não contém uma lista válida.")
+        tasks.extend(created)
+        return created
+
+    update_json("tasks.json", [], persist_tasks)
+
+    def persist_queues(queues: Any) -> dict[str, Any]:
+        if not isinstance(queues, dict):
+            raise StorageIntegrityError("O ficheiro queues.json não contém um objecto válido.")
+        queues.setdefault("script", [])
+        if not isinstance(queues["script"], list):
+            queues["script"] = []
+        queues["script"].extend(task["id"] for task in created)
+        return queues
+
+    update_json("queues.json", {}, persist_queues)
     return created
 
 
@@ -271,16 +281,24 @@ def _notify_task_completion(task: dict[str, Any], previous_state: str = "") -> N
 
 
 def update_task(task_id: str, updates: dict[str, Any]) -> dict[str, Any] | None:
-    tasks = read_json("tasks.json", [])
-    for task in tasks:
-        if task.get("id") == task_id:
-            previous_state = str(task.get("state") or "")
-            task.update(updates)
-            task["updated_at"] = now()
-            write_json("tasks.json", tasks)
-            _notify_task_completion(task, previous_state)
-            return task
-    return None
+    previous_state = ""
+
+    def mutate(tasks: Any) -> dict[str, Any] | None:
+        nonlocal previous_state
+        if not isinstance(tasks, list):
+            raise StorageIntegrityError("O ficheiro tasks.json não contém uma lista válida.")
+        for task in tasks:
+            if isinstance(task, dict) and task.get("id") == task_id:
+                previous_state = str(task.get("state") or "")
+                task.update(updates)
+                task["updated_at"] = now()
+                return task
+        return None
+
+    updated = update_json("tasks.json", [], mutate)
+    if updated is not None:
+        _notify_task_completion(updated, previous_state)
+    return updated
 
 
 def delete_task(task_id: str) -> dict[str, Any] | None:
@@ -288,30 +306,50 @@ def delete_task(task_id: str) -> dict[str, Any] | None:
     normalized_id = str(task_id or "").strip()
     if not normalized_id:
         return None
-    tasks = read_json("tasks.json", [])
-    if not isinstance(tasks, list):
-        return None
-    removed = next((task for task in tasks if isinstance(task, dict) and str(task.get("id") or "") == normalized_id), None)
+    removed: dict[str, Any] | None = None
+
+    def mutate(tasks: Any) -> list[dict[str, Any]]:
+        nonlocal removed
+        if not isinstance(tasks, list):
+            raise StorageIntegrityError("O ficheiro tasks.json não contém uma lista válida.")
+        for task in tasks:
+            if isinstance(task, dict) and str(task.get("id") or "") == normalized_id:
+                if str(task.get("state") or "") == "doing":
+                    raise ValueError("Pare a tarefa antes de a remover da fila.")
+                removed = task
+                break
+        if removed is not None:
+            tasks[:] = [task for task in tasks if not (isinstance(task, dict) and str(task.get("id") or "") == normalized_id)]
+        return tasks
+
+    update_json("tasks.json", [], mutate)
     if removed is None:
         return None
-    if str(removed.get("state") or "") == "doing":
-        raise ValueError("Pare a tarefa antes de a remover da fila.")
-    write_json("tasks.json", [task for task in tasks if not (isinstance(task, dict) and str(task.get("id") or "") == normalized_id)])
-    queues = read_json("queues.json", {})
-    if isinstance(queues, dict):
+
+    def clean_queues(queues: Any) -> dict[str, Any]:
+        if not isinstance(queues, dict):
+            raise StorageIntegrityError("O ficheiro queues.json não contém um objecto válido.")
         for queue_name, queue_items in list(queues.items()):
             if isinstance(queue_items, list):
                 queues[queue_name] = [item for item in queue_items if str(item) != normalized_id]
-        write_json("queues.json", queues)
+        return queues
+
+    update_json("queues.json", {}, clean_queues)
     return removed
 
 
 def transition_task(task_id: str, state: str | None = None, stage: str | None = None, error: str | None = None) -> dict[str, Any] | None:
     if state and state not in VALID_STATES:
         raise ValueError(f"Estado inválido: {state}")
-    tasks = read_json("tasks.json", [])
-    for task in tasks:
-        if task.get("id") == task_id:
+    previous_state = ""
+
+    def mutate(tasks: Any) -> dict[str, Any] | None:
+        nonlocal previous_state
+        if not isinstance(tasks, list):
+            raise StorageIntegrityError("O ficheiro tasks.json não contém uma lista válida.")
+        for task in tasks:
+            if not isinstance(task, dict) or task.get("id") != task_id:
+                continue
             previous_state = str(task.get("state") or "")
             if state:
                 task["state"] = state
@@ -322,10 +360,13 @@ def transition_task(task_id: str, state: str | None = None, stage: str | None =
             if error is not None:
                 task["error"] = error
             task["updated_at"] = now()
-            write_json("tasks.json", tasks)
-            _notify_task_completion(task, previous_state)
             return task
-    return None
+        return None
+
+    updated = update_json("tasks.json", [], mutate)
+    if updated is not None:
+        _notify_task_completion(updated, previous_state)
+    return updated
 
 
 def retry_task_with_current_settings(task_id: str) -> dict[str, Any] | None:
@@ -335,28 +376,31 @@ def retry_task_with_current_settings(task_id: str) -> dict[str, Any] | None:
     retry always uses the currently saved API keys, active provider priorities,
     and provider endpoints while retaining the task's completed artefacts.
     """
-    tasks = read_json("tasks.json", [])
-    for task in tasks:
-        if task.get("id") != task_id:
-            continue
-        previous_state = str(task.get("state") or "")
-        if previous_state not in {"failed", "blocked"}:
-            raise ValueError("Apenas tarefas falhadas ou bloqueadas podem ser retomadas.")
-        try:
-            retry_count = int(task.get("retry_count") or 0)
-        except (TypeError, ValueError):
-            retry_count = 0
-        task["state"] = "to_do"
-        task["error"] = None
-        task["retry_count"] = retry_count + 1
-        task["retry_requested_at"] = now()
-        task["retry_config_source"] = "settings.json_at_execution"
-        for field in ("failure_api", "failure_provider", "failure_service", "failure_config_fields"):
-            task.pop(field, None)
-        task["updated_at"] = now()
-        write_json("tasks.json", tasks)
-        return task
-    return None
+    def mutate(tasks: Any) -> dict[str, Any] | None:
+        if not isinstance(tasks, list):
+            raise StorageIntegrityError("O ficheiro tasks.json não contém uma lista válida.")
+        for task in tasks:
+            if not isinstance(task, dict) or task.get("id") != task_id:
+                continue
+            previous_state = str(task.get("state") or "")
+            if previous_state not in {"failed", "blocked"}:
+                raise ValueError("Apenas tarefas falhadas ou bloqueadas podem ser retomadas.")
+            try:
+                retry_count = int(task.get("retry_count") or 0)
+            except (TypeError, ValueError):
+                retry_count = 0
+            task["state"] = "to_do"
+            task["error"] = None
+            task["retry_count"] = retry_count + 1
+            task["retry_requested_at"] = now()
+            task["retry_config_source"] = "settings.json_at_execution"
+            for field in ("failure_api", "failure_provider", "failure_service", "failure_config_fields"):
+                task.pop(field, None)
+            task["updated_at"] = now()
+            return task
+        return None
+
+    return update_json("tasks.json", [], mutate)
 
 
 def pipeline_summary() -> dict[str, Any]:

package/hermes_ui/material_sources.py

@@ -6,6 +6,7 @@ from uuid import uuid4
 
 MATERIAL_CARDS_KEY = "material_source_cards"
 MATERIAL_ACTIVE_CARD_KEY = "material_active_card_id"
+DEFAULT_MATERIAL_PRIORITY = 1
 
 MATERIAL_SOURCE_CATALOG: tuple[dict[str, str], ...] = (
     {"code": "pexels", "label": "Pexels", "description": "Banco de vídeos e imagens para materiais da pipeline.", "legacy_key": "pexels_api_keys"},
@@ -43,15 +44,29 @@ def material_source_definition(source: Any) -> dict[str, str] | None:
     return _SOURCE_BY_CODE.get(str(source or "").strip().lower())
 
 
-def _new_card(provider: str, api_key: str = "", *, card_id: str | None = None) -> dict[str, Any]:
+def _new_card(
+    provider: str,
+    api_key: str = "",
+    *,
+    card_id: str | None = None,
+    priority: int = DEFAULT_MATERIAL_PRIORITY,
+) -> dict[str, Any]:
     return {
         "id": card_id or f"material-{provider}-{uuid4().hex[:8]}",
         "provider": provider,
         "api_key": str(api_key or "").strip(),
         "enabled": True,
+        "priority": max(1, int(priority)),
     }
 
 
+def _normalise_priority(value: Any, fallback: int = DEFAULT_MATERIAL_PRIORITY) -> int:
+    try:
+        return max(1, int(value))
+    except (TypeError, ValueError):
+        return max(1, int(fallback or DEFAULT_MATERIAL_PRIORITY))
+
+
 def normalize_material_card(card: Any, index: int = 0) -> dict[str, Any]:
     raw = card if isinstance(card, dict) else {}
     provider = str(raw.get("provider") or raw.get("source") or "pexels").strip().lower()
@@ -63,9 +78,25 @@ def normalize_material_card(card: Any, index: int = 0) -> dict[str, Any]:
         "provider": provider,
         "api_key": str(raw.get("api_key") or raw.get("key") or "").strip() if provider != "local" else "",
         "enabled": bool(raw.get("enabled", True)),
+        "priority": _normalise_priority(raw.get("priority", index + 1), index + 1),
     }
 
 
+def _ordered_cards(cards: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    indexed = [(index, normalize_material_card(card, index)) for index, card in enumerate(cards)]
+    indexed.sort(key=lambda pair: (pair[1].get("priority", pair[0] + 1), pair[0]))
+    return [card for _index, card in indexed]
+
+
+def material_source_cards(settings: dict[str, Any], *, enabled_only: bool = False) -> list[dict[str, Any]]:
+    """Return material providers in stable priority order for the MoviePy queue."""
+    migrated, _ = ensure_material_source_cards(settings)
+    cards = [dict(item) for item in migrated.get(MATERIAL_CARDS_KEY, [])]
+    if enabled_only:
+        cards = [card for card in cards if card.get("enabled", True)]
+    return cards
+
+
 def _cards_key_mapping(cards: list[dict[str, Any]]) -> dict[str, list[str]]:
     mapping = {item["code"]: [] for item in MATERIAL_SOURCE_CATALOG}
     for index, raw_card in enumerate(cards):
@@ -94,12 +125,23 @@ def ensure_material_source_cards(settings: dict[str, Any]) -> tuple[dict[str, An
         cards: list[dict[str, Any]] = []
         for item in MATERIAL_SOURCE_CATALOG:
             for key in material_api_keys(settings, item["code"], _ignore_cards=True):
-                cards.append(_new_card(item["code"], key, card_id=f"material-{item['code']}-{len(cards)}"))
+                cards.append(
+                    _new_card(
+                        item["code"],
+                        key,
+                        card_id=f"material-{item['code']}-{len(cards)}",
+                        priority=len(cards) + 1,
+                    )
+                )
         if not cards:
             selected = selected_material_source(settings)
             cards.append(_new_card(selected if selected in _SOURCE_BY_CODE else "pexels", card_id="material-default-0"))
         changed = True
 
+    ordered_cards = _ordered_cards(cards)
+    if ordered_cards != cards:
+        changed = True
+    cards = ordered_cards
     settings[MATERIAL_CARDS_KEY] = cards
     active_id = str(settings.get(MATERIAL_ACTIVE_CARD_KEY) or "").strip()
     valid_ids = {str(card["id"]) for card in cards}
@@ -137,6 +179,7 @@ def apply_material_source_cards_to_settings(
     normalized_cards = [normalize_material_card(item, index) for index, item in enumerate(cards)]
     if not normalized_cards:
         normalized_cards = [_new_card("pexels", card_id="material-default-0")]
+    normalized_cards = _ordered_cards(normalized_cards)
     settings[MATERIAL_CARDS_KEY] = normalized_cards
     selected_card = next((card for card in normalized_cards if str(card["id"]) == str(active_card_id)), None)
     if selected_card is None:

package/hermes_ui/storage.py

@@ -4,9 +4,12 @@ import json
 import os
 import shutil
 import tempfile
+import time
+from contextlib import contextmanager
+from copy import deepcopy
 from datetime import datetime, timezone
 from pathlib import Path
-from typing import Any
+from typing import Any, Callable, Iterator
 
 ROOT = Path(__file__).resolve().parents[1]
 STORAGE = Path(os.getenv("THUNDERBOLT_STORAGE_DIR") or ROOT / "storage")
@@ -407,13 +410,55 @@ def ensure_storage() -> None:
             atomic_write(target, default)
 
 
-def atomic_write(path: Path, data: Any) -> None:
-    """Write JSON through a same-directory temporary file and atomic replace.
+_LOCK_TIMEOUT_SECONDS = 30.0
+_LOCK_POLL_SECONDS = 0.05
+_LOCK_STALE_SECONDS = 15 * 60
+_PROTECTED_STATE_FILES = {"channels.json", "tasks.json", "batches.json", "queues.json", "uploads.json"}
 
-    The complete payload is flushed and fsynced before replacement, so a
-    process interruption cannot leave a partially written JSON document at the
-    destination.
+
+class StorageIntegrityError(RuntimeError):
+    """Raised when protected state cannot be recovered without risking data loss."""
+
+
+@contextmanager
+def _state_lock(path: Path) -> Iterator[None]:
+    """Serialise state mutations across the UI and both local workers.
+
+    A lock file is used instead of an in-memory mutex because the launcher
+    runs Streamlit and workers as separate Python processes. Stale locks from
+    a machine shutdown are reclaimed after a conservative timeout.
     """
+    lock_path = path.with_name(f".{path.name}.lock")
+    lock_path.parent.mkdir(parents=True, exist_ok=True)
+    deadline = time.monotonic() + _LOCK_TIMEOUT_SECONDS
+    descriptor: int | None = None
+    while descriptor is None:
+        try:
+            descriptor = os.open(lock_path, os.O_CREAT | os.O_EXCL | os.O_WRONLY)
+            os.write(descriptor, f"pid={os.getpid()}\n".encode("ascii"))
+        except FileExistsError:
+            try:
+                if time.time() - lock_path.stat().st_mtime > _LOCK_STALE_SECONDS:
+                    lock_path.unlink()
+                    continue
+            except OSError:
+                pass
+            if time.monotonic() >= deadline:
+                raise TimeoutError(f"Não foi possível obter o lock de storage: {path.name}")
+            time.sleep(_LOCK_POLL_SECONDS)
+    try:
+        yield
+    finally:
+        try:
+            os.close(descriptor)
+        finally:
+            try:
+                lock_path.unlink()
+            except FileNotFoundError:
+                pass
+
+
+def _atomic_write_unlocked(path: Path, data: Any) -> None:
     path.parent.mkdir(parents=True, exist_ok=True)
     fd, temp_name = tempfile.mkstemp(prefix=f".{path.name}.", dir=path.parent)
     try:
@@ -428,25 +473,79 @@ def atomic_write(path: Path, data: Any) -> None:
             os.unlink(temp_name)
 
 
+def atomic_write(path: Path, data: Any) -> None:
+    """Write JSON through a locked, same-directory temporary file and replace.
+
+    The complete payload is flushed and fsynced before replacement, so a
+    process interruption cannot leave a partially written JSON document at the
+    destination, while the lock prevents another process from racing with the
+    replacement.
+    """
+    with _state_lock(path):
+        _atomic_write_unlocked(path, data)
+
+
+def _corrupt_backup(path: Path) -> Path | None:
+    if not path.exists():
+        return None
+    backup = path.with_suffix(path.suffix + f".corrupt-{datetime.now(timezone.utc).strftime('%Y%m%d%H%M%S%f')}")
+    shutil.copy2(path, backup)
+    return backup
+
+
+def _load_json_unlocked(path: Path) -> Any:
+    with path.open("r", encoding="utf-8") as handle:
+        return json.load(handle)
+
+
+def _recover_json_unlocked(name: str, path: Path, default: Any | None) -> Any:
+    backup = _corrupt_backup(path)
+    if name in _PROTECTED_STATE_FILES:
+        candidates = sorted(path.parent.glob(f"{path.name}.corrupt-*"), key=lambda item: item.stat().st_mtime, reverse=True)
+        for candidate in candidates:
+            if backup is not None and candidate == backup:
+                continue
+            try:
+                recovered = _load_json_unlocked(candidate)
+            except (json.JSONDecodeError, OSError):
+                continue
+            _atomic_write_unlocked(path, recovered)
+            return recovered
+        location = str(backup or path)
+        raise StorageIntegrityError(f"O ficheiro protegido {name} está corrompido. A cópia foi preservada em {location}.")
+    fallback = deepcopy(DEFAULTS.get(name, [] if default is None else default))
+    _atomic_write_unlocked(path, fallback)
+    return fallback
+
+
 def read_json(name: str, default: Any | None = None) -> Any:
     ensure_storage()
     path = STATE / name
-    try:
-        with path.open("r", encoding="utf-8") as handle:
-            data = json.load(handle)
+    with _state_lock(path):
+        try:
+            data = _load_json_unlocked(path)
+        except (json.JSONDecodeError, OSError):
+            data = _recover_json_unlocked(name, path, default)
         if name != "settings.json":
             return data
         migrated, changed = _migrate_settings(data)
         if changed:
-            atomic_write(path, migrated)
+            _atomic_write_unlocked(path, migrated)
         return migrated
-    except (json.JSONDecodeError, OSError):
-        backup = path.with_suffix(path.suffix + f".corrupt-{datetime.now().strftime('%Y%m%d%H%M%S')}")
-        if path.exists():
-            shutil.copy2(path, backup)
-        fallback = DEFAULTS.get(name, [] if default is None else default)
-        atomic_write(path, fallback)
-        return fallback
+
+
+def update_json(name: str, default: Any, mutator: Callable[[Any], Any]) -> Any:
+    """Atomically mutate one JSON document under the cross-process state lock."""
+    ensure_storage()
+    path = STATE / name
+    with _state_lock(path):
+        try:
+            current = _load_json_unlocked(path)
+        except (json.JSONDecodeError, OSError):
+            current = _recover_json_unlocked(name, path, default)
+        result = mutator(current)
+        _atomic_write_unlocked(path, current)
+        return result
 
 
 def write_json(name: str, data: Any) -> None:
@@ -456,12 +555,13 @@ def write_json(name: str, data: Any) -> None:
 
 
 def append_json(name: str, item: dict[str, Any]) -> dict[str, Any]:
-    entries = read_json(name, [])
-    if not isinstance(entries, list):
-        entries = []
-    entries.append(item)
-    write_json(name, entries)
-    return item
+    def append(entries: Any) -> dict[str, Any]:
+        if not isinstance(entries, list):
+            raise StorageIntegrityError(f"O ficheiro {name} não contém uma lista válida.")
+        entries.append(item)
+        return item
+
+    return update_json(name, [], append)
 
 
 def _display_name_key(kind: str, path: Path) -> str:

package/hermes_ui/thumbnails.py

@@ -10,7 +10,7 @@ from typing import Any
 from .creative_generation import generate_thumbnail_prompt
 from .media_generation import generate_image_from_pool
 from .media_providers import media_cards_for_pool
-from .storage import STORAGE, now, read_json, write_json
+from .storage import STORAGE, now, read_json, update_json
 from .thumbnail_generation import ThumbnailGenerationError, generate_thumbnail_image
 
 
@@ -230,6 +230,18 @@ def _find_task(tasks: list[Any], task_id: str) -> tuple[dict[str, Any], dict[str
     raise ThumbnailGenerationError(f"A tarefa {task_id} não foi encontrada.")
 
 
+def _update_thumbnail_task(task_id: str, callback: Any) -> dict[str, Any]:
+    """Apply a thumbnail mutation to the latest task snapshot under the storage lock."""
+    def mutate(tasks: Any) -> dict[str, Any]:
+        if not isinstance(tasks, list):
+            raise ThumbnailGenerationError("O índice de tarefas não está disponível.")
+        task, record = _find_task(tasks, task_id)
+        callback(task, record)
+        return task
+
+    return update_json("tasks.json", [], mutate)
+
+
 def generate_thumbnail_for_task(task_id: str, settings: dict[str, Any]) -> tuple[dict[str, Any], Path]:
     """Generate an image from the task's current prompt and persist it on the task."""
     tasks = read_json("tasks.json", [])
@@ -247,9 +259,11 @@ def generate_thumbnail_for_task(task_id: str, settings: dict[str, Any]) -> tuple
         lettering_text=record.get("thumbnail_text") or "",
         lettering_prompt=record.get("lettering_prompt") or "",
     )
-    _persist_thumbnail_result(tasks, task, record, image_path)
-    write_json("tasks.json", tasks)
-    return task, image_path
+    updated = _update_thumbnail_task(
+        task_id,
+        lambda current_task, current_record: _persist_thumbnail_result([], current_task, current_record, image_path),
+    )
+    return updated, image_path
 
 
 def regenerate_thumbnail_prompt(
@@ -275,9 +289,11 @@ def regenerate_thumbnail_prompt(
         blueprint=blueprint,
         language=language,
     )
-    _persist_thumbnail_prompt_result(task, record, variant)
-    write_json("tasks.json", tasks)
-    return task, variant
+    updated = _update_thumbnail_task(
+        task_id,
+        lambda current_task, current_record: _persist_thumbnail_prompt_result(current_task, current_record, variant),
+    )
+    return updated, variant
 
 
 def regenerate_thumbnail_prompt_and_image(
@@ -302,9 +318,13 @@ def regenerate_thumbnail_prompt_and_image(
         lettering_text=str((variant or {}).get("overlay_text") or ""),
         lettering_prompt=str((variant or {}).get("lettering_prompt") or ""),
     )
-    _persist_thumbnail_result(tasks, task, record, image_path, variant=variant, source="prompt_regenerated")
-    write_json("tasks.json", tasks)
-    return task, image_path
+    updated = _update_thumbnail_task(
+        task_id,
+        lambda current_task, current_record: _persist_thumbnail_result(
+            [], current_task, current_record, image_path, variant=variant, source="prompt_regenerated"
+        ),
+    )
+    return updated, image_path
 
 
 def regenerate_thumbnail_lettering(
@@ -346,9 +366,13 @@ def regenerate_thumbnail_lettering(
     variant = _variant_for_record(record)
     variant["image_prompt"] = base_prompt
     variant["lettering_prompt"] = edit_prompt
-    _persist_thumbnail_result(tasks, task, record, image_path, variant=variant, source="lettering_regenerated", lettering_prompt=edit_prompt)
-    write_json("tasks.json", tasks)
-    return task, image_path
+    updated = _update_thumbnail_task(
+        task_id,
+        lambda current_task, current_record: _persist_thumbnail_result(
+            [], current_task, current_record, image_path, variant=variant, source="lettering_regenerated", lettering_prompt=edit_prompt
+        ),
+    )
+    return updated, image_path
 
 
 def upload_thumbnail_image(
@@ -387,9 +411,13 @@ def upload_thumbnail_image(
         if os.path.exists(temp_name):
             os.unlink(temp_name)
     variant = _variant_for_record(record)
-    _persist_thumbnail_result(tasks, task, record, destination, variant=variant, source="uploaded")
-    write_json("tasks.json", tasks)
-    return task, destination
+    updated = _update_thumbnail_task(
+        task_id,
+        lambda current_task, current_record: _persist_thumbnail_result(
+            [], current_task, current_record, destination, variant=variant, source="uploaded"
+        ),
+    )
+    return updated, destination
 
 
 def regenerate_thumbnail(task_id: str, settings: dict[str, Any]) -> tuple[dict[str, Any], Path]:

package/package.json

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

package/scripts/install.mjs

@@ -177,23 +177,27 @@ function legacyNpxPackageRoots() {
   for (const hashRoot of cacheHashes) {
     const candidate = resolve(hashRoot, "node_modules", "@danhachuel", "thunderbolt");
     if (candidate === root || roots.has(candidate)) continue;
-    if (existsSync(join(candidate, "storage", "state", "ai_influencers.db"))) roots.add(candidate);
+    const recoverableStateFiles = ["ai_influencers.db", "tasks.json", "channels.json", "batches.json", "queues.json"];
+    if (recoverableStateFiles.some((filename) => existsSync(join(candidate, "storage", "state", filename)))) roots.add(candidate);
   }
   return [...roots].sort((left, right) => {
-    try { return statSync(join(right, "storage", "state", "ai_influencers.db")).mtimeMs - statSync(join(left, "storage", "state", "ai_influencers.db")).mtimeMs; }
-    catch { return 0; }
+    const newestStateTime = (candidate) => Math.max(...["ai_influencers.db", "tasks.json", "channels.json", "batches.json", "queues.json"].map((filename) => {
+      try { return statSync(join(candidate, "storage", "state", filename)).mtimeMs; }
+      catch { return 0; }
+    }));
+    return newestStateTime(right) - newestStateTime(left);
   });
 }
 
 function migrateLegacyNpxStorage() {
   const targetStorage = join(thunderboltHome, "storage");
   const candidates = legacyNpxPackageRoots();
-  let copied = 0;
+  let mergedFiles = 0;
   for (const candidate of candidates) {
-    copied += copyMissingTree(join(candidate, "storage"), targetStorage);
-    if (existsSync(join(targetStorage, "state", "ai_influencers.db"))) break;
+    copyMissingTree(join(candidate, "storage"), targetStorage);
+    mergedFiles += mergeLegacyStorage(candidate);
   }
-  if (copied > 0) console.log(`Dados locais AI Influencers recuperados do cache npm para ${targetStorage}.`);
+  if (mergedFiles > 0) console.log(`Dados locais recuperados do cache npm para ${targetStorage} (${mergedFiles} ficheiro(s) unido(s)).`);
 }
 
 function copyOrMove(source, target, label) {
@@ -209,16 +213,86 @@ function copyOrMove(source, target, label) {
   return true;
 }
 
+function parseJsonFile(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function mergeUniqueArray(target, source) {
+  const merged = [...target];
+  const knownIds = new Set(merged.filter((item) => item && typeof item === "object" && item.id).map((item) => String(item.id)));
+  const knownValues = new Set(merged.map((item) => JSON.stringify(item)));
+  for (const item of source) {
+    const id = item && typeof item === "object" && item.id ? String(item.id) : "";
+    const value = JSON.stringify(item);
+    if ((id && knownIds.has(id)) || knownValues.has(value)) continue;
+    merged.push(item);
+    if (id) knownIds.add(id);
+    knownValues.add(value);
+  }
+  return merged;
+}
+
+function mergeJsonStateFile(source, target, filename) {
+  if (!existsSync(source) || !existsSync(target)) return false;
+  const sourceData = parseJsonFile(source);
+  const targetData = parseJsonFile(target);
+  if (sourceData === null) return false;
+  if (targetData === null) {
+    copyFileSync(target, `${target}.corrupt-${Date.now()}`);
+    writeFileSync(target, JSON.stringify(sourceData, null, 2) + "\n", "utf8");
+    return true;
+  }
+  let merged = targetData;
+  if (Array.isArray(sourceData) && Array.isArray(targetData)) {
+    merged = mergeUniqueArray(targetData, sourceData);
+  } else if (filename === "queues.json" && sourceData && targetData && typeof sourceData === "object" && typeof targetData === "object") {
+    merged = { ...targetData };
+    for (const [queueName, sourceItems] of Object.entries(sourceData)) {
+      if (!Array.isArray(sourceItems)) continue;
+      const targetItems = Array.isArray(merged[queueName]) ? merged[queueName] : [];
+      merged[queueName] = mergeUniqueArray(targetItems, sourceItems);
+    }
+  }
+  if (JSON.stringify(merged) === JSON.stringify(targetData)) return false;
+  writeFileSync(target, JSON.stringify(merged, null, 2) + "\n", "utf8");
+  return true;
+}
+
+function mergeLegacyStorage(legacyRoot) {
+  const sourceStorage = join(legacyRoot, "storage");
+  const targetStorage = join(thunderboltHome, "storage");
+  if (!existsSync(sourceStorage)) return 0;
+  mkdirSync(targetStorage, { recursive: true });
+  copyMissingTree(sourceStorage, targetStorage);
+  const sourceState = join(sourceStorage, "state");
+  const targetState = join(targetStorage, "state");
+  if (!existsSync(sourceState) || !existsSync(targetState)) return 0;
+  let mergedCount = 0;
+  for (const entry of readdirSync(sourceState, { withFileTypes: true })) {
+    if (!entry.isFile() || !entry.name.endsWith(".json")) continue;
+    if (mergeJsonStateFile(join(sourceState, entry.name), join(targetState, entry.name), entry.name)) mergedCount += 1;
+  }
+  return mergedCount;
+}
+
 function migrateLegacyInstallation() {
   if (explicitThunderboltHome) return;
   const candidates = legacyRoots();
-  const legacy = candidates.find((candidate) => existsSync(join(candidate, "storage")) || existsSync(join(candidate, ".venv")) || existsSync(join(candidate, "MoneyPrinterTurbo")));
-  if (!legacy) return;
-  console.warn(`Foi encontrada uma instalação antiga em ${legacy}. O Thunderbolt usará ${thunderboltHome}.`);
-  copyOrMove(join(legacy, "storage"), join(thunderboltHome, "storage"), "storage legado");
-  copyOrMove(join(legacy, ".venv"), join(thunderboltHome, ".venv"), "ambiente Python legado");
-  copyOrMove(join(legacy, "MoneyPrinterTurbo"), join(thunderboltHome, "MoneyPrinterTurbo"), "MoneyPrinterTurbo legado");
-  console.log("A pasta legada não será usada pelo Thunderbolt; foi preservada quando a cópia foi necessária.");
+  let found = false;
+  for (const legacy of candidates) {
+    if (!existsSync(join(legacy, "storage")) && !existsSync(join(legacy, ".venv")) && !existsSync(join(legacy, "MoneyPrinterTurbo"))) continue;
+    found = true;
+    console.warn(`Foi encontrada uma instalação antiga em ${legacy}. O Thunderbolt usará ${thunderboltHome}.`);
+    const mergedFiles = mergeLegacyStorage(legacy);
+    if (mergedFiles > 0) console.log(`Dados de estado recuperados da instalação antiga (${mergedFiles} ficheiro(s) unido(s)).`);
+    copyOrMove(join(legacy, ".venv"), join(thunderboltHome, ".venv"), "ambiente Python legado");
+    copyOrMove(join(legacy, "MoneyPrinterTurbo"), join(thunderboltHome, "MoneyPrinterTurbo"), "MoneyPrinterTurbo legado");
+  }
+  if (found) console.log("A instalação antiga foi preservada; o Thunderbolt não elimina tarefas, filas ou artefactos durante a actualização.");
 }
 
 function removePath(path) {