feat: criado monitoramento contínuo de trilhas com varredura recur

- criado monitoramento contínuo de trilhas com varredura recursiva e baixa prioridade
- gerado e validado plano editorial revisável do depoimento da Erika sem aplicação na timeline
- adicionada leitura e comparação estrutural da timeline após aplicar planos de edição
- limitadas as classificações de trilhas às duas maiores probabilidades de cada categoria
- limpo o catálogo musical para reiniciar as análises sem remover dados de vídeo

Resumo:
- 34 arquivos alterados
- 6 novos
- 28 modificados
- 0 removidos

 28 files changed, 833 insertions(+), 75 deletions(-)

Arquivos:
  - .jhonny/analises.db
  - code/cep-plugin/index.html
  - code/cep-plugin/main.js
  - code/engine/analisar_trilhas.py
  - code/engine/aplicar_plano_de_edicao.py
  - code/engine/consultar_detalhes_de_trilha.py
  - code/engine/editor/__init__.py
  - code/engine/editor/aplicador_de_plano_de_edicao.py
  - code/engine/editor/backup_de_sequencia.py
  - code/engine/editor/escrita/escrita_no_editor.py
  - code/engine/editor/modelos.py
  - code/engine/editor/validacao_semantica.py
  - code/engine/integracoes/audio/classificador_de_musica_essentia.py
  - code/engine/integracoes/audio/modelos_de_analise_musical.py
  - code/engine/integracoes/audio/provider_de_analise_musical_essentia.py
  - code/engine/persistencia/esquema.py
  - code/engine/persistencia/repositorio_de_trilhas.py
  - code/engine/testes/duplos_de_premiere.py
  - code/engine/testes/test_aplicador_de_plano_de_edicao.py
  - code/engine/testes/test_aplicar_plano_de_edicao.py
  - code/engine/testes/test_escrita_no_editor.py
  - code/engine/testes/test_leitor_de_plano_de_edicao.py
  - code/engine/testes/test_validador_semantico_de_plano.py
  - code/plugins/premiere-pro/skills/editar-por-voz/SKILL.md
  - code/plugins/premiere-pro/skills/editar-por-voz/criterios/08-formato-de-saida.md
  - code/plugins/premiere-pro/skills/editar-por-voz/criterios/10-revisao-humana.md
  - code/src/tools/timeline.ts
  - code/tests/tools/tool-modules.test.ts
  - .jhonny/planos/
  - code/.jhonny/analises.db-shm
  - code/.jhonny/analises.db-wal
  - code/engine/editor/verificador_da_aplicacao.py
  - code/engine/testes/test_verificador_da_aplicacao.py
  - code/plugins/premiere-pro/skills/editar-por-voz/criterios/11-gancho.md

code/cep-plugin/index.html

@@ -306,7 +306,7 @@
         </div>
         <p class="field-help" id="trilhasPastaStatus">O caminho será salvo no banco para reutilizar esta pasta depois.</p>
         <p class="field-help">A análise usa os modelos Essentia instalados internamente pela aplicação. Você não precisa localizar nem selecionar essa pasta.</p>
-        <button class="button button-primary" id="btnTrilhasAnalisar" onclick="trilhasAnalisar()" type="button" disabled>Analisar trilhas</button>
+        <button class="button button-primary" id="btnTrilhasAnalisar" onclick="trilhasAnalisar()" type="button" disabled>Iniciar monitoramento</button>
       </section>
       <section class="card" id="trilhasProgressoCard" hidden>
         <div class="card-head"><h2>Progresso da análise</h2><span class="card-kicker" id="trilhasContagem">0 trilhas</span></div>

code/cep-plugin/main.js

@@ -1511,6 +1511,7 @@ var https = nodeRequire("https");
 var childProcess = nodeRequire("child_process");
 TRILHAS_BANCO_PATH = path.join(os.homedir(), ".premiere-mcp", "trilhas.db");
 TRILHAS_MODELOS_PATH = path.join(os.homedir(), ".premiere-mcp", "modelos-essentia");
+if (!fs.existsSync(TRILHAS_MODELOS_PATH) && fs.existsSync("/private/tmp/essentia-modelos")) TRILHAS_MODELOS_PATH = "/private/tmp/essentia-modelos";
 function defaultBridgeDirectory() {
   try {
     var nodeProcess = nodeRequire("process");
@@ -2889,15 +2890,15 @@ function trilhasAoAbrir() {
   var pasta = document.getElementById("trilhasPasta");
   if (pasta && configuracao.pasta) pasta.value = configuracao.pasta;
   trilhasAtualizarEstado();
-  if (pasta && pasta.value.trim() && fs.existsSync(pasta.value.trim())) trilhasAtualizarCatalogo(pasta.value.trim());
+  if (pasta && pasta.value.trim() && fs.existsSync(pasta.value.trim())) trilhasAtualizarCatalogo(pasta.value.trim(), function () { trilhasIniciarWorker(pasta.value.trim()); });
 }
 
-function trilhasAtualizarCatalogo(pasta) {
+function trilhasAtualizarCatalogo(pasta, aoFinalizar) {
   var argumentos = [TRILHAS_ENGINE_SCRIPT, pasta, "--banco", TRILHAS_BANCO_PATH, "--listar"];
   runStreamed(SCANNER_PYTHON_BIN, argumentos, function (linha) {
     if (linha.indexOf("@@PROGRESS ") !== 0) return;
     try { trilhasAtualizarEvento(JSON.parse(linha.slice(11))); } catch (_) {}
-  }, function () {}, { cwd: "/Volumes/Merongo/SISTEMAS/GENIAL SISTEMAS/Jhonny/code", stdio: ["ignore", "pipe", "pipe"] });
+  }, function () { if (typeof aoFinalizar === "function") aoFinalizar(); }, { cwd: "/Volumes/Merongo/SISTEMAS/GENIAL SISTEMAS/Jhonny/code", stdio: ["ignore", "pipe", "pipe"] });
 }
 
 function trilhasListarArquivos(pasta) {
@@ -2938,6 +2939,7 @@ function trilhasSelecionarPasta() {
     trilhasSalvarConfiguracao(escolhida);
     trilhasAtualizarEstado();
     trilhasPrepararLista(escolhida);
+    trilhasIniciarWorker(escolhida);
   } catch (erro) { showToast("err", erro.message); }
 }
 
@@ -2996,9 +2998,11 @@ function trilhasCarregarDetalhes(item, detalhes) {
     var etiquetas = dados.etiquetas || [];
     var generos = etiquetas.filter(function (etiqueta) { return etiqueta.tipo === "genero"; });
     var humores = etiquetas.filter(function (etiqueta) { return etiqueta.tipo === "humor"; });
+    var temas = etiquetas.filter(function (etiqueta) { return etiqueta.tipo === "tema"; });
     function formatar(valor, casas) { return valor === null || valor === undefined ? "—" : Number(valor).toFixed(casas || 2); }
     function listaEtiquetas(itens) { return itens.length ? itens.map(function (item) { return item.etiqueta + " (" + formatar(Number(item.confianca) * 100, 1) + "%)"; }).join(" · ") : "Não classificado"; }
-    detalhes.innerHTML = '<div class="trilha-detalhes-grid"><div><small>Duração</small><strong>' + formatar(dados.duracao_em_segundos, 1) + ' s</strong></div><div><small>BPM</small><strong>' + formatar(dados.batidas_por_minuto, 1) + '</strong></div><div><small>Tonalidade</small><strong>' + (dados.tonalidade || "—") + ' ' + (dados.modo || "") + '</strong></div><div><small>Intensidade</small><strong>' + formatar(dados.intensidade, 2) + '</strong></div><div><small>Dançabilidade</small><strong>' + formatar(dados.dancabilidade, 2) + '</strong></div></div><div class="trilha-etiquetas"><div><small>Estilos</small><p>' + listaEtiquetas(generos) + '</p></div><div><small>Humores</small><p>' + listaEtiquetas(humores) + '</p></div></div><small class="trilha-fonte">Análise salva por ' + (dados.provedor || "Essentia") + (dados.modelo ? " · " + dados.modelo : "") + '</small>';
+    function listaTextos(itens) { return itens && itens.length ? itens.join(" · ") : "Não identificado"; }
+    detalhes.innerHTML = '<div class="trilha-detalhes-grid"><div><small>Duração</small><strong>' + formatar(dados.duracao_em_segundos, 1) + ' s</strong></div><div><small>BPM</small><strong>' + formatar(dados.batidas_por_minuto, 1) + '</strong></div><div><small>Tonalidade</small><strong>' + (dados.tonalidade || "—") + ' ' + (dados.modo || "") + '</strong></div><div><small>Intensidade</small><strong>' + formatar(dados.intensidade, 2) + '</strong></div><div><small>Dançabilidade</small><strong>' + formatar(dados.dancabilidade, 2) + '</strong></div></div><div class="trilha-etiquetas"><div><small>Estilos / gêneros</small><p>' + listaEtiquetas(generos) + '</p></div><div><small>Humores</small><p>' + listaEtiquetas(humores) + '</p></div><div><small>Temas</small><p>' + listaEtiquetas(temas) + '</p></div><div><small>Instrumentos</small><p>' + listaTextos(dados.instrumentos) + '</p></div><div><small>Etiquetas do áudio</small><p>' + listaTextos(dados.etiquetas_audio) + '</p></div></div><small class="trilha-fonte">Análise salva por ' + (dados.provedor || "Essentia") + (dados.modelo ? " · " + dados.modelo : "") + '</small>';
     detalhes.setAttribute("data-carregado", "true");
   } catch (_) { detalhes.textContent = "A resposta da análise está inválida."; }
 }
@@ -3008,7 +3012,7 @@ function trilhasAtualizarEvento(evento) {
   if (evento.evento === "lote_iniciado") { trilhasRenderizarLista(evento.trilhas || evento.nomes || []); return; }
   if (!evento.nome) return;
   var itens = Array.prototype.slice.call(document.querySelectorAll(".trilha-item"));
-  var item = itens.filter(function (elemento) { return elemento.querySelector("strong").textContent === evento.nome; })[0];
+  var item = itens.filter(function (elemento) { return (evento.caminho && elemento.getAttribute("data-caminho") === evento.caminho) || elemento.querySelector("strong").textContent === evento.nome; })[0];
   if (!item) return;
   var estado = evento.evento === "trilha_concluida" ? "concluida" : evento.evento === "trilha_com_erro" ? "erro" : "analisando";
   item.setAttribute("data-state", estado);
@@ -3022,19 +3026,29 @@ function trilhasAtualizarEvento(evento) {
 function trilhasAnalisar() {
   var pasta = document.getElementById("trilhasPasta").value.trim();
   if (!pasta || !fs.existsSync(pasta) || !fs.statSync(pasta).isDirectory()) { showToast("err", "Selecione uma pasta existente."); return; }
+  trilhasIniciarWorker(pasta);
+}
+
+function trilhasIniciarWorker(pasta) {
+  if (trilhasProcesso || taskState.active) return;
   trilhasSalvarConfiguracao(pasta);
-  var argumentos = [TRILHAS_ENGINE_SCRIPT, pasta, "--banco", TRILHAS_BANCO_PATH];
-  argumentos.push("--modelos", TRILHAS_MODELOS_PATH);
+  var argumentos = [TRILHAS_ENGINE_SCRIPT, pasta, "--banco", TRILHAS_BANCO_PATH, "--modelos", TRILHAS_MODELOS_PATH, "--continuo", "--intervalo", "20"];
+  var ambiente = Object.assign({}, process.env, { OMP_NUM_THREADS: "1", OPENBLAS_NUM_THREADS: "1", MKL_NUM_THREADS: "1", TF_NUM_INTRAOP_THREADS: "1", TF_NUM_INTEROP_THREADS: "1" });
   setBusy("btnTrilhasAnalisar", true);
-  taskStart("Analisando trilhas musicais", "Descobrindo arquivos", function (evento) { trilhasAtualizarEvento(evento); }, function () { if (trilhasProcesso) trilhasProcesso.kill("SIGTERM"); });
+  taskStart("Catálogo de trilhas em segundo plano", "Monitorando a pasta", function (evento) { trilhasAtualizarEvento(evento); }, function () { if (trilhasProcesso) trilhasProcesso.kill("SIGTERM"); });
   trilhasProcesso = runStreamed(SCANNER_PYTHON_BIN, argumentos, function () {}, function (codigo, erro) {
     trilhasProcesso = null; setBusy("btnTrilhasAnalisar", false); trilhasAtualizarEstado();
-    if (codigo !== 0) { taskEnd(false, "Falha na análise das trilhas", erro || "O processamento não foi concluído."); return; }
-    taskEnd(true, "Análise das trilhas concluída");
-  }, { cwd: "/Volumes/Merongo/SISTEMAS/GENIAL SISTEMAS/Jhonny/code", stdio: ["ignore", "pipe", "pipe"] });
+    if (taskState.canceled) { taskEnd(false, "Monitoramento interrompido"); return; }
+    if (codigo !== 0) { taskEnd(false, "Falha no monitoramento das trilhas", erro || "O processamento não foi concluído."); return; }
+    taskEnd(true, "Monitoramento das trilhas concluído");
+  }, { cwd: "/Volumes/Merongo/SISTEMAS/GENIAL SISTEMAS/Jhonny/code", env: ambiente, stdio: ["ignore", "pipe", "pipe"] });
+  if (trilhasProcesso && trilhasProcesso.pid) childProcess.spawn("renice", ["-n", "15", "-p", String(trilhasProcesso.pid)], { stdio: "ignore" });
 }
 
 var trilhasProcesso = null;
+window.addEventListener("beforeunload", function () {
+  if (trilhasProcesso) trilhasProcesso.kill("SIGTERM");
+});
 
 // LEGADO comentado em 2026-09-09: transcrição/diarização feitas direto nesta aba,
 // duplicando o que a aba Scanner já faz e persiste no banco (.jhonny/analises.db).
@@ -3619,7 +3633,7 @@ function resolveEditorialActionsScript() {
   return resolveScript("apply-editorial-actions.mjs", EDITORIAL_ACTIONS_APPLY_SCRIPT_FALLBACK);
 }
 
-// ---- Aplicar o plano de edição devolvido pela IA (cut/zoom/text/marker) ----
+// ---- Aplicar o plano de edição devolvido pela IA (cut/hook/zoom/text/marker) ----
 function lerPlanoEditorialDaTela() {
   var campoJson = document.getElementById("editorialPlanJson");
   var campoCaminho = document.getElementById("editorialPlanPath");
@@ -3647,7 +3661,7 @@ function invalidarVinculoDoPlanoEditorial() {
   planoEditorialIdCarregado = null;
   var status = document.getElementById("editorialPlanJsonStatus");
   if (status) {
-    status.textContent = "Plano alterado fora do banco. Registre e carregue a nova versão antes de aplicar cortes.";
+    status.textContent = "Plano alterado fora do banco. Registre e carregue a nova versão antes de aplicar cortes ou ganchos.";
     status.className = "field-help err";
   }
 }
@@ -3669,13 +3683,13 @@ function applyEditorialActions() {
   var numActions = plan.actions.length;
 
   var summary =
-    numActions + " ação(ões) no plano (cortes, zooms, textos e/ou marcadores).\n\n" +
+    numActions + " ação(ões) no plano (cortes, ganchos, zooms, textos e/ou marcadores).\n\n" +
     "Um backup da sequência atual será criado antes de aplicar. Confirmar?";
   if (typeof window.confirm === "function" && !window.confirm(summary)) return;
 
   setBusy("btnApplyEditorialActions", true);
   setStep(3, "running", "Validando…");
-  taskStart("Aplicando o plano de edição", "Validando frases e bordas de corte");
+  taskStart("Aplicando o plano de edição", "Validando frases e bordas editoriais");
   var caminhoDoPlano = path.join(silenceState.outputDir || os.tmpdir(), "plano-editorial-" + Date.now() + ".json");
   try { fs.writeFileSync(caminhoDoPlano, JSON.stringify(plan, null, 2), "utf-8"); } catch (erroEscrita) {
     setBusy("btnApplyEditorialActions", false);
@@ -3703,6 +3717,10 @@ function applyEditorialActions() {
           var resultadoDaAplicacao = JSON.parse(lastOutput || "{}");
           var falhasDaAplicacao = (resultadoDaAplicacao.acoes || []).filter(function (acao) { return acao.sucesso === false; });
           if (falhasDaAplicacao.length) detalheDaAplicacao = falhasDaAplicacao.map(function (acao) { return acao.detalhe; }).join(" | ");
+          if (!detalheDaAplicacao && resultadoDaAplicacao.verificacao && resultadoDaAplicacao.verificacao.aprovada === false) {
+            detalheDaAplicacao = resultadoDaAplicacao.verificacao.mensagem ||
+              (resultadoDaAplicacao.verificacao.divergencias || []).join(" | ");
+          }
           if (!detalheDaAplicacao && resultadoDaAplicacao.erro) detalheDaAplicacao = resultadoDaAplicacao.erro;
         } catch (_) {}
         setStep(3, "error", "Bloqueado");
@@ -3712,8 +3730,16 @@ function applyEditorialActions() {
         return;
       }
       setStep(3, "done", "Aplicado");
-      taskEnd(true, numActions + " ação(ões) aplicadas na timeline!");
+      var verificacaoDaAplicacao = null;
+      try { verificacaoDaAplicacao = JSON.parse(lastOutput || "{}").verificacao || null; } catch (_) {}
+      var textoDaVerificacao = verificacaoDaAplicacao && verificacaoDaAplicacao.mensagem
+        ? " Verificação: " + verificacaoDaAplicacao.mensagem
+        : "";
+      taskEnd(true, numActions + " ação(ões) aplicadas na timeline!" + textoDaVerificacao);
       silenceLog("Plano de edição aplicado com sucesso!", "ok");
+      if (verificacaoDaAplicacao && verificacaoDaAplicacao.avisos && verificacaoDaAplicacao.avisos.length) {
+        silenceLog("Atenção na verificação pós-aplicação: " + verificacaoDaAplicacao.avisos.join(" | "), "err");
+      }
     }
   );
 }

code/engine/analisar_trilhas.py

@@ -6,6 +6,7 @@ import argparse
 import json
 from pathlib import Path
 import sys
+import time
 
 CAMINHO_DO_CODIGO = Path(__file__).resolve().parent.parent
 if str(CAMINHO_DO_CODIGO) not in sys.path:
@@ -33,18 +34,14 @@ def executar(pasta: Path, banco: Path, diretorio_dos_modelos: Path | None, apena
     try:
         repositorio = RepositorioDeTrilhasSQLite(conexao)
         trilhas = repositorio.registrar_pasta_e_arquivos(pasta, arquivos)
+        repositorio.reabrir_analises_sem_etiquetas()
+        trilhas = repositorio.registrar_pasta_e_arquivos(pasta, arquivos)
         if apenas_listar:
             emitir("catalogo_atualizado", trilhas=[
                 {"nome": trilha.nome_do_arquivo, "caminho": str(trilha.caminho), "status": trilha.status}
                 for trilha in trilhas
             ])
             return 0
-        classificador = (
-            ClassificadorDeMusicaEssentia(diretorio_dos_modelos)
-            if diretorio_dos_modelos and diretorio_dos_modelos.is_dir()
-            else None
-        )
-        analisador = AnalisadorDeMusicaInstrumentalEssentia(classificador=classificador)
         pendentes = tuple(trilha for trilha in trilhas if trilha.status != "concluida")
         emitir(
             "lote_iniciado",
@@ -53,22 +50,39 @@ def executar(pasta: Path, banco: Path, diretorio_dos_modelos: Path | None, apena
             nomes=[trilha.nome_do_arquivo for trilha in pendentes],
             trilhas=[{"nome": trilha.nome_do_arquivo, "caminho": str(trilha.caminho), "status": trilha.status} for trilha in trilhas],
         )
+        if not pendentes:
+            emitir("lote_concluido", total=0, percentual=100)
+            return 0
+        classificador = (
+            ClassificadorDeMusicaEssentia(diretorio_dos_modelos)
+            if diretorio_dos_modelos and diretorio_dos_modelos.is_dir()
+            else None
+        )
+        analisador = AnalisadorDeMusicaInstrumentalEssentia(classificador=classificador)
         for ordem, trilha in enumerate(pendentes, start=1):
             repositorio.iniciar_analise(trilha.identificador)
-            emitir("trilha_iniciada", nome=trilha.nome_do_arquivo, indice=ordem, total=len(trilhas), percentual=(ordem - 1) * 100 / max(1, len(trilhas)))
+            emitir("trilha_iniciada", nome=trilha.nome_do_arquivo, caminho=str(trilha.caminho), indice=ordem, total=len(trilhas), percentual=(ordem - 1) * 100 / max(1, len(trilhas)))
             try:
                 resultado = analisador.analisar(trilha.caminho)
                 repositorio.registrar_analise(trilha, resultado)
-                emitir("trilha_concluida", nome=trilha.nome_do_arquivo, indice=ordem, total=len(trilhas), percentual=ordem * 100 / max(1, len(trilhas)))
+                emitir("trilha_concluida", nome=trilha.nome_do_arquivo, caminho=str(trilha.caminho), indice=ordem, total=len(trilhas), percentual=ordem * 100 / max(1, len(trilhas)))
             except (OSError, RuntimeError, ValueError) as erro:
                 repositorio.registrar_erro(trilha.identificador, str(erro))
-                emitir("trilha_com_erro", nome=trilha.nome_do_arquivo, indice=ordem, total=len(trilhas), erro=str(erro), percentual=ordem * 100 / max(1, len(trilhas)))
+                emitir("trilha_com_erro", nome=trilha.nome_do_arquivo, caminho=str(trilha.caminho), indice=ordem, total=len(trilhas), erro=str(erro), percentual=ordem * 100 / max(1, len(trilhas)))
         emitir("lote_concluido", total=len(trilhas), percentual=100)
         return 0
     finally:
         conexao.close()
 
 
+def executar_continuamente(pasta: Path, banco: Path, diretorio_dos_modelos: Path | None, intervalo: float) -> int:
+    """Mantém a pasta monitorada e processa novas trilhas em baixa frequência."""
+    while True:
+        executar(pasta, banco, diretorio_dos_modelos)
+        emitir("worker_aguardando", intervalo=intervalo)
+        time.sleep(intervalo)
+
+
 def principal() -> None:
     """Lê argumentos e executa o lote de análise."""
     argumentos = argparse.ArgumentParser()
@@ -76,8 +90,12 @@ def principal() -> None:
     argumentos.add_argument("--banco", type=Path, default=Path(".jhonny/analises.db"))
     argumentos.add_argument("--modelos", type=Path, default=None)
     argumentos.add_argument("--listar", action="store_true")
+    argumentos.add_argument("--continuo", action="store_true")
+    argumentos.add_argument("--intervalo", type=float, default=20.0)
     opcoes = argumentos.parse_args()
     try:
+        if opcoes.continuo:
+            raise SystemExit(executar_continuamente(opcoes.pasta, opcoes.banco, opcoes.modelos, opcoes.intervalo))
         raise SystemExit(executar(opcoes.pasta, opcoes.banco, opcoes.modelos, opcoes.listar))
     except (OSError, RuntimeError, ValueError) as erro:
         emitir("lote_com_erro", erro=str(erro))

code/engine/aplicar_plano_de_edicao.py

@@ -37,8 +37,10 @@ from engine.editor import (
     LeitorDePlanoDeEdicao,
     MapeadorDeTempoDeOrigemParaTimeline,
     PlanoDeEdicao,
+    ResultadoDaVerificacao,
     TipoDeAcao,
     ValidadorSemanticoDePlano,
+    VerificadorDaAplicacao,
 )
 from engine.integracoes.premiere.cliente_mcp import ClienteMCPPorStdio
 from engine.integracoes.premiere.cliente_mcp_com_pausa import ClienteMCPComPausa
@@ -52,6 +54,14 @@ CAMINHO_DO_SERVIDOR_MCP = CAMINHO_DO_CODIGO / "dist" / "index.js"
 CAMINHO_DO_BANCO = CAMINHO_DO_CODIGO.parent / ".jhonny" / "analises.db"
 
 
+def _garantir_backup_para_ganchos(plano: PlanoDeEdicao, backup_criado: bool) -> None:
+    """Bloqueia ganchos quando não há uma cópia recuperável da sequência."""
+    if plano.acoes_do_tipo(TipoDeAcao.GANCHO) and not backup_criado:
+        raise ErroDePlanoInvalido(
+            "A ação hook não foi aplicada porque o Premiere não confirmou o backup da sequência."
+        )
+
+
 def _validar_integridade_semantica(
     plano: PlanoDeEdicao,
     plano_id: int | None,
@@ -59,7 +69,10 @@ def _validar_integridade_semantica(
     exigir_validacao: bool = False,
 ) -> None:
     """Valida palavras, frases e respiros antes de iniciar a sessão do Premiere."""
-    if not plano.acoes_do_tipo(TipoDeAcao.CORTE):
+    if not (
+        plano.acoes_do_tipo(TipoDeAcao.CORTE)
+        or plano.acoes_do_tipo(TipoDeAcao.GANCHO)
+    ):
         return
     if plano_id is None:
         if exigir_validacao:
@@ -119,6 +132,7 @@ def _registrar_no_banco(
     sequencia: str,
     plano_id: int | None = None,
     caminho_do_banco: Path = CAMINHO_DO_BANCO,
+    verificacao: ResultadoDaVerificacao | None = None,
 ) -> None:
     """Guarda no banco de análises o plano aplicado e o resultado da aplicação.
 
@@ -145,11 +159,14 @@ def _registrar_no_banco(
         if plano_id is None:
             plano_id = repositorio.registrar_plano(plano_de_dict(dados))
         aplicadas = sum(1 for item in resultado.resultados if item.sucesso)
+        verificacao_aprovada = verificacao is None or verificacao.aprovada
+        mensagem = verificacao.mensagem if verificacao is not None else None
         repositorio.registrar_aplicacao(
             plano_id,
-            sucesso=resultado.todas_bem_sucedidas,
+            sucesso=resultado.todas_bem_sucedidas and verificacao_aprovada,
             acoes_aplicadas=aplicadas,
             sequencia=sequencia,
+            mensagem=mensagem,
         )
     except (OSError, ValueError, sqlite3.Error) as erro:
         print(f"Plano aplicado, mas não foi possível registrá-lo no banco: {erro}",
@@ -186,9 +203,11 @@ def executar(
 
         # A engine é a única responsável pelo backup. A validação semântica já
         # aconteceu antes da conexão, portanto um plano bloqueado não duplica
-        # a sequência. Uma falha no backup fica registrada em stderr.
+        # a sequência. Gancho é recusado sem backup porque combina mais de
+        # uma mutação estrutural; as demais ações preservam o fluxo legado.
         sequencia_ativa = conversor_de_timeline.converter(acesso_ao_editor.obter_timeline_ativa())
         backup_ok = BackupDaSequencia(cliente).criar_backup(sequencia_ativa.identificador)
+        _garantir_backup_para_ganchos(plano, backup_ok)
         print(
             "Backup da sequência criado." if backup_ok else "Não foi possível criar o backup automático; aplicando mesmo assim.",
             file=sys.stderr,
@@ -201,15 +220,28 @@ def executar(
             mapeador=MapeadorDeTempoDeOrigemParaTimeline(),
         )
         resultado = aplicador.aplicar(plano)
+        timeline_depois = conversor_de_timeline.converter(
+            acesso_ao_editor.obter_timeline_ativa()
+        )
+        verificacao = VerificadorDaAplicacao().verificar(
+            sequencia_ativa, timeline_depois, plano
+        )
 
     _registrar_no_banco(
         caminho_do_plano, resultado, sequencia_ativa.nome,
         plano_id=plano_id, caminho_do_banco=caminho_do_banco,
+        verificacao=verificacao,
     )
 
     return {
         "arquivo_de_origem": plano.arquivo_de_origem,
-        "todas_bem_sucedidas": resultado.todas_bem_sucedidas,
+        "todas_bem_sucedidas": resultado.todas_bem_sucedidas and verificacao.aprovada,
+        "verificacao": {
+            "aprovada": verificacao.aprovada,
+            "mensagem": verificacao.mensagem,
+            "divergencias": list(verificacao.divergencias),
+            "avisos": list(verificacao.avisos),
+        },
         "acoes": [
             {
                 "tipo": item.acao.tipo.value,

code/engine/consultar_detalhes_de_trilha.py

@@ -21,7 +21,8 @@ def consultar(caminho: Path, banco: Path) -> dict[str, object]:
         analise = conexao.execute(
             """SELECT a.id, a.provedor, a.modelo, a.duracao_em_segundos,
                       a.batidas_por_minuto, a.tonalidade, a.modo,
-                      a.intensidade, a.dancabilidade
+                      a.intensidade, a.dancabilidade, a.temas_json,
+                      a.instrumentos_json, a.etiquetas_json
                FROM trilhas_musicais t
                JOIN analises_musicais a ON a.trilha_id = t.id
               WHERE t.caminho = ?
@@ -44,6 +45,9 @@ def consultar(caminho: Path, banco: Path) -> dict[str, object]:
             "modo": analise["modo"],
             "intensidade": analise["intensidade"],
             "dancabilidade": analise["dancabilidade"],
+            "temas": json.loads(analise["temas_json"] or "[]"),
+            "instrumentos": json.loads(analise["instrumentos_json"] or "[]"),
+            "etiquetas_audio": json.loads(analise["etiquetas_json"] or "[]"),
             "etiquetas": [dict(etiqueta) for etiqueta in etiquetas],
         }
     finally:

code/engine/editor/__init__.py

@@ -1,4 +1,4 @@
-"""Aplicação de planos de edição (cortes, zooms, marcadores) na timeline do Premiere.
+"""Aplicação de planos de edição (cortes, ganchos e destaques) no Premiere.
 
 Lê o JSON de ações produzido pelas skills de seleção de trechos
 (``kind``/``start``/``end``/``params``/``reason``), traduz os tempos de
@@ -19,6 +19,7 @@ from .leitura import LeitorDePlanoDeEdicao
 from .mapeamento import MapeadorDeTempoDeOrigemParaTimeline
 from .modelos import AcaoDeEdicao, PlanoDeEdicao, TipoDeAcao
 from .validacao_semantica import ProblemaSemanticoDoPlano, ValidadorSemanticoDePlano
+from .verificador_da_aplicacao import ResultadoDaVerificacao, VerificadorDaAplicacao
 
 __all__ = [
     "AcaoDeEdicao",
@@ -37,4 +38,6 @@ __all__ = [
     "ResultadoDaAplicacao",
     "TipoDeAcao",
     "ValidadorSemanticoDePlano",
+    "ResultadoDaVerificacao",
+    "VerificadorDaAplicacao",
 ]

code/engine/editor/aplicador_de_plano_de_edicao.py

@@ -60,7 +60,9 @@ class AplicadorDePlanoDeEdicao:
        tudo que vem depois dele. Processar do fim para o começo garante que
        a posição de um corte ainda não aplicado nunca é afetada pelos
        cortes já aplicados.
-    2. Marcadores e zooms por último, depois que a timeline já está no
+    2. O gancho para abertura vem depois dos cortes. Ele localiza o trecho por
+       tempo da mídia original e cria uma cópia no começo da sequência.
+    3. Marcadores e zooms por último, depois que a timeline já está no
        formato final. Zoom (``set_clip_properties``) muda uma propriedade do
        *clipe inteiro*, não de um trecho dele — se dois zooms caíssem em
        instantes diferentes do mesmo clipe ainda não dividido pelos cortes,
@@ -107,10 +109,15 @@ class AplicadorDePlanoDeEdicao:
 
     def aplicar(self, plano: PlanoDeEdicao) -> ResultadoDaAplicacao:
         """Aplica todas as ações de ``plano`` e devolve o resultado de cada uma."""
-        pontuais = [acao for acao in plano.acoes if acao.tipo is not TipoDeAcao.CORTE]
+        ganchos = plano.acoes_do_tipo(TipoDeAcao.GANCHO)
+        pontuais = [
+            acao for acao in plano.acoes
+            if acao.tipo not in {TipoDeAcao.CORTE, TipoDeAcao.GANCHO}
+        ]
         cortes = sorted(plano.acoes_do_tipo(TipoDeAcao.CORTE), key=lambda acao: acao.inicio, reverse=True)
 
         resultados = [self._aplicar_corte(acao, plano.arquivo_de_origem) for acao in cortes]
+        resultados += [self._aplicar_gancho(acao, plano.arquivo_de_origem) for acao in ganchos]
         resultados += [self._aplicar_acao_pontual(acao, plano.arquivo_de_origem) for acao in pontuais]
         return ResultadoDaAplicacao(tuple(resultados))
 
@@ -189,6 +196,78 @@ class AplicadorDePlanoDeEdicao:
         except ErroDeEdicao as erro:
             return ResultadoDaAcao(acao, False, str(erro))
 
+    def _aplicar_gancho(self, acao: AcaoDeEdicao, arquivo_de_origem: str) -> ResultadoDaAcao:
+        """Recorta uma cópia de um par simples e a insere na abertura."""
+        try:
+            faixas = self._timeline_atual().faixas
+            faixas_afetadas = [
+                faixa for faixa in faixas
+                if any(
+                    self._sobrepoe(clipe, acao.inicio, acao.fim)
+                    for clipe in self._clipes_do_arquivo(faixa, arquivo_de_origem)
+                )
+            ]
+            videos = [faixa for faixa in faixas_afetadas if faixa.tipo == "video"]
+            audios = [faixa for faixa in faixas_afetadas if faixa.tipo == "audio"]
+            if len(videos) != 1 or len(audios) != 1:
+                raise ErroDeMapeamentoDeTempo(
+                    "A ação hook exige exatamente uma faixa de vídeo e uma de áudio com o trecho de origem."
+                )
+            faixas_adicionais_ocupadas = [
+                faixa.identificador
+                for faixa in faixas
+                if faixa not in faixas_afetadas and faixa.clipes
+            ]
+            if faixas_adicionais_ocupadas:
+                raise ErroDeMapeamentoDeTempo(
+                    "A ação hook exige uma sequência simples; há conteúdo nas faixas adicionais: "
+                    + ", ".join(faixas_adicionais_ocupadas)
+                )
+            for faixa in faixas_afetadas:
+                afetados = [
+                    clipe for clipe in self._clipes_do_arquivo(faixa, arquivo_de_origem)
+                    if self._sobrepoe(clipe, acao.inicio, acao.fim)
+                ]
+                if len(afetados) != 1:
+                    raise ErroDeMapeamentoDeTempo(
+                        f"A ação hook precisa estar contida em um único clipe da faixa {faixa.identificador!r}."
+                    )
+                intervalo_na_origem = afetados[0].intervalo_na_origem
+                if (
+                    intervalo_na_origem is None
+                    or acao.inicio < intervalo_na_origem.inicio - _TOLERANCIA_DE_BORDA_EM_SEGUNDOS
+                    or acao.fim > intervalo_na_origem.fim + _TOLERANCIA_DE_BORDA_EM_SEGUNDOS
+                ):
+                    raise ErroDeMapeamentoDeTempo(
+                        f"A ação hook ultrapassa o clipe da faixa {faixa.identificador!r}."
+                    )
+                inicio_na_timeline = self._borda_de_entrada(afetados[0], acao.inicio)
+                if inicio_na_timeline <= _TOLERANCIA_DE_BORDA_EM_SEGUNDOS:
+                    raise ErroDeMapeamentoDeTempo("O trecho da ação hook já está no início da sequência.")
+                if min(clipe.intervalo_na_timeline.inicio for clipe in faixa.clipes) > _TOLERANCIA_DE_BORDA_EM_SEGUNDOS:
+                    raise ErroDeMapeamentoDeTempo(
+                        f"A faixa {faixa.identificador!r} não começa em 0s; o gancho foi recusado."
+                    )
+
+            alvos = [
+                clipe
+                for faixa in faixas_afetadas
+                for clipe in self._clipes_do_arquivo(faixa, arquivo_de_origem)
+                if self._sobrepoe(clipe, acao.inicio, acao.fim)
+            ]
+            if len(alvos) != 2:
+                raise ErroDeMapeamentoDeTempo(
+                    "O Premiere não localizou exatamente um clipe de vídeo e um de áudio para a ação hook."
+                )
+            self.escrita.duplicar_trecho_vinculado_para_o_inicio(
+                [clipe.identificador for clipe in alvos],
+                acao.inicio,
+                acao.fim,
+            )
+            return ResultadoDaAcao(acao, True, "gancho vinculado duplicado no início")
+        except ErroDeEdicao as erro:
+            return ResultadoDaAcao(acao, False, str(erro))
+
     def _preparar_alvos_da_faixa(
         self, faixa: Faixa, acao: AcaoDeEdicao, arquivo_de_origem: str
     ) -> list[Clipe]:

code/engine/editor/backup_de_sequencia.py

@@ -21,8 +21,8 @@ class BackupDaSequencia:
     def criar_backup(self, identificador_da_sequencia: str) -> bool:
         """Duplica a sequência. Devolve ``True`` se conseguiu, ``False`` se o Premiere recusou.
 
-        Não levanta exceção numa recusa: a engine registra a falha e continua
-        a aplicação solicitada, deixando a ausência de backup visível.
+        Não levanta exceção numa recusa: o chamador decide se a ação pode
+        continuar. Ganchos estruturais são bloqueados sem essa confirmação.
         """
         try:
             self.cliente_mcp.chamar("duplicate_sequence", {"sequence_id": identificador_da_sequencia})

code/engine/editor/escrita/escrita_no_editor.py

@@ -1,8 +1,9 @@
 """Escrita de mutações na sequência ativa do Premiere via MCP.
 
 Isola o nome das ferramentas MCP e o formato de argumentos externos
-(``split_clip``, ``remove_from_timeline``, ``remove_linked_from_timeline``, ``set_clip_properties``,
-``add_marker``) do resto do domínio. Quem chama esta classe fala só em
+(``split_clip``, ``remove_from_timeline``, ``remove_linked_from_timeline``,
+``duplicate_linked_range_to_start``, ``set_clip_properties``, ``add_marker``) do
+resto do domínio. Quem chama esta classe fala só em
 segundos de timeline, identificador de clipe e fator de escala — nunca em
 nomes de ferramenta ou ticks do Premiere.
 """
@@ -113,6 +114,34 @@ class EscritaNoEditor:
                 f"Não foi possível remover o par vinculado {identificadores_dos_clipes!r}: {erro}"
             ) from erro
 
+    def duplicar_trecho_vinculado_para_o_inicio(
+        self,
+        identificadores_dos_clipes: list[str],
+        inicio_na_origem: float,
+        fim_na_origem: float,
+    ) -> None:
+        """Copia parte de um par de vídeo e áudio para o início da sequência.
+
+        A ferramenta externa executa inserção com ripple, mantém a ocorrência
+        original intacta e confirma posição, duração e sincronismo. A operação
+        é recusada quando os identificadores não formam um par simples.
+        """
+        if len(identificadores_dos_clipes) != 2:
+            raise ErroDeEscritaNoEditor("O gancho exige exatamente um clipe de vídeo e um de áudio.")
+        try:
+            self.cliente_mcp.chamar(
+                "duplicate_linked_range_to_start",
+                {
+                    "node_ids": identificadores_dos_clipes,
+                    "source_in_seconds": inicio_na_origem,
+                    "source_out_seconds": fim_na_origem,
+                },
+            )
+        except ErroDeFerramentaMCP as erro:
+            raise ErroDeEscritaNoEditor(
+                f"Não foi possível duplicar o par vinculado {identificadores_dos_clipes!r} no início: {erro}"
+            ) from erro
+
     def aplicar_zoom(self, identificador_do_clipe: str, fator_de_escala: float) -> None:
         """Aplica um punch-in no clipe, escalando-o por ``fator_de_escala`` (1.0 = tamanho original).
 

code/engine/editor/modelos.py

@@ -14,12 +14,13 @@ from typing import Any
 
 
 class TipoDeAcao(str, Enum):
-    """Os quatro tipos de ação que o plano de edição pode descrever."""
+    """Os tipos de ação que o plano de edição pode descrever."""
 
     CORTE = "cut"
     ZOOM = "zoom"
     TEXTO = "text"
     MARCADOR = "marker"
+    GANCHO = "hook"
 
 
 @dataclass(frozen=True)
@@ -46,6 +47,13 @@ class AcaoDeEdicao:
             )
         if not self.motivo.strip():
             raise ValueError("Ação inválida: motivo não pode ser vazio.")
+        if self.tipo is TipoDeAcao.GANCHO:
+            destino = self.parametros.get("target", 0)
+            manter_original = self.parametros.get("keep_original", True)
+            if isinstance(destino, bool) or not isinstance(destino, (int, float)) or float(destino) != 0.0:
+                raise ValueError("Gancho inválido: params.target precisa ser 0 nesta versão.")
+            if manter_original is not True:
+                raise ValueError("Gancho inválido: params.keep_original precisa ser true.")
 
     @property
     def duracao(self) -> float:
@@ -63,6 +71,16 @@ class PlanoDeEdicao:
     def __post_init__(self) -> None:
         if not self.arquivo_de_origem.strip():
             raise ValueError("Plano de edição inválido: arquivo de origem não informado.")
+        ganchos = self.acoes_do_tipo(TipoDeAcao.GANCHO)
+        if len(ganchos) > 1:
+            raise ValueError("Plano de edição inválido: esta versão aceita somente uma ação hook.")
+        if ganchos:
+            gancho = ganchos[0]
+            for acao in self.acoes:
+                if acao is gancho:
+                    continue
+                if acao.inicio < gancho.fim and gancho.inicio < acao.fim:
+                    raise ValueError("Plano de edição inválido: outra ação não pode sobrepor o trecho do hook.")
 
     def acoes_do_tipo(self, tipo: TipoDeAcao) -> tuple[AcaoDeEdicao, ...]:
         """Devolve, na ordem original, só as ações do tipo informado."""

code/engine/editor/validacao_semantica.py

@@ -1,4 +1,4 @@
-"""Validação semântica das bordas de cortes antes de alterar a timeline."""
+"""Validação semântica de cortes e ganchos antes de alterar a timeline."""
 
 from __future__ import annotations
 
@@ -21,7 +21,7 @@ class ProblemaSemanticoDoPlano:
 
 
 class ValidadorSemanticoDePlano:
-    """Protege palavras, frases completas e respiros nas emendas de cortes."""
+    """Protege palavras, frases completas e respiros nas emendas editoriais."""
 
     _TOLERANCIA_EM_SEGUNDOS = 0.01
     _PONTUACAO_DE_FECHAMENTO = (".", "!", "?", "…")
@@ -37,12 +37,17 @@ class ValidadorSemanticoDePlano:
         plano: PlanoDeEdicao,
         falas: tuple[SegmentoDeTranscricao, ...],
     ) -> tuple[ProblemaSemanticoDoPlano, ...]:
-        """Devolve todos os problemas semânticos encontrados nas ações de corte."""
+        """Devolve os problemas semânticos encontrados em cortes e ganchos."""
         cortes = tuple(
             (indice, acao)
             for indice, acao in enumerate(plano.acoes)
             if acao.tipo is TipoDeAcao.CORTE
         )
+        ganchos = tuple(
+            (indice, acao)
+            for indice, acao in enumerate(plano.acoes)
+            if acao.tipo is TipoDeAcao.GANCHO
+        )
         palavras = tuple(
             sorted(
                 (palavra for fala in falas for palavra in fala.palavras),
@@ -54,6 +59,9 @@ class ValidadorSemanticoDePlano:
             problemas.extend(self._validar_palavras_interceptadas(indice, corte, palavras))
             problemas.extend(self._validar_borda_inicial(indice, corte, cortes, palavras))
             problemas.extend(self._validar_borda_final(indice, corte, cortes, falas, palavras))
+        for indice, gancho in ganchos:
+            problemas.extend(self._validar_palavras_interceptadas(indice, gancho, palavras))
+            problemas.extend(self._validar_frase_do_gancho(indice, gancho, falas, palavras))
         return tuple(problemas)
 
     def garantir_valido(
@@ -61,7 +69,7 @@ class ValidadorSemanticoDePlano:
         plano: PlanoDeEdicao,
         falas: tuple[SegmentoDeTranscricao, ...],
     ) -> None:
-        """Levanta erro explicativo quando qualquer corte ameaça a fala mantida."""
+        """Levanta erro explicativo quando uma emenda ameaça a integridade da fala."""
         problemas = self.validar(plano, falas)
         if not problemas:
             return
@@ -70,6 +78,71 @@ class ValidadorSemanticoDePlano:
             "Plano bloqueado pela validação de integridade da fala: " + detalhes
         )
 
+    def _validar_frase_do_gancho(
+        self,
+        indice: int,
+        gancho: AcaoDeEdicao,
+        falas: tuple[SegmentoDeTranscricao, ...],
+        palavras: tuple[PalavraDeTranscricao, ...],
+    ) -> list[ProblemaSemanticoDoPlano]:
+        """Confirma que o gancho duplicado começa e termina como uma fala completa."""
+        contidas = tuple(
+            palavra for palavra in palavras
+            if gancho.inicio - self._TOLERANCIA_EM_SEGUNDOS <= palavra.inicio
+            and palavra.fim <= gancho.fim + self._TOLERANCIA_EM_SEGUNDOS
+        )
+        if not contidas:
+            return [ProblemaSemanticoDoPlano(
+                codigo="gancho_sem_fala",
+                mensagem=f"ação {indice + 1}: o trecho do gancho não contém palavras temporizadas",
+                indice_da_acao=indice,
+                instante=gancho.inicio,
+            )]
+
+        primeira, ultima = contidas[0], contidas[-1]
+        problemas: list[ProblemaSemanticoDoPlano] = []
+        if primeira.inicio - gancho.inicio < self._margem_minima - self._TOLERANCIA_EM_SEGUNDOS:
+            problemas.append(ProblemaSemanticoDoPlano(
+                codigo="margem_inicial_do_gancho_insuficiente",
+                mensagem=(
+                    f"ação {indice + 1}: deixe ao menos {self._margem_minima:.2f}s antes "
+                    f'da primeira palavra do gancho "{primeira.texto}"'
+                ),
+                indice_da_acao=indice,
+                instante=gancho.inicio,
+            ))
+        if gancho.fim - ultima.fim < self._margem_minima - self._TOLERANCIA_EM_SEGUNDOS:
+            problemas.append(ProblemaSemanticoDoPlano(
+                codigo="margem_final_do_gancho_insuficiente",
+                mensagem=(
+                    f"ação {indice + 1}: deixe ao menos {self._margem_minima:.2f}s após "
+                    f'a última palavra do gancho "{ultima.texto}"'
+                ),
+                indice_da_acao=indice,
+                instante=gancho.fim,
+            ))
+        fala_inicial = self._fala_da_palavra(primeira, falas)
+        primeira_letra = next((letra for letra in primeira.texto if letra.isalpha()), "")
+        comeca_no_meio = (
+            fala_inicial is not None
+            and primeira.inicio > fala_inicial.inicio + self._TOLERANCIA_EM_SEGUNDOS
+        ) or bool(primeira_letra and primeira_letra.islower())
+        if comeca_no_meio:
+            problemas.append(ProblemaSemanticoDoPlano(
+                codigo="gancho_comeca_no_meio_da_frase",
+                mensagem=f'ação {indice + 1}: o gancho começa em "{primeira.texto}", no meio da frase',
+                indice_da_acao=indice,
+                instante=gancho.inicio,
+            ))
+        if not ultima.texto.rstrip().endswith(self._PONTUACAO_DE_FECHAMENTO):
+            problemas.append(ProblemaSemanticoDoPlano(
+                codigo="gancho_termina_no_meio_da_frase",
+                mensagem=f'ação {indice + 1}: o gancho termina em "{ultima.texto}" sem concluir a frase',
+                indice_da_acao=indice,
+                instante=gancho.fim,
+            ))
+        return problemas
+
     def _validar_palavras_interceptadas(
         self,
         indice: int,

code/engine/editor/verificador_da_aplicacao.py

@@ -0,0 +1,183 @@
+"""Verificação estrutural da timeline depois da aplicação de um plano.
+
+Compara a cobertura de origem que deveria sobreviver aos cortes com a
+cobertura realmente lida no Premiere depois da mutação. A verificação não
+avalia pixels, áudio ou qualidade editorial; ela detecta sobras, lacunas e
+desalinhamentos estruturais em cada tipo de faixa.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ..dominio import Clipe, Faixa, IntervaloDeTempo, Timeline
+from .modelos import PlanoDeEdicao, TipoDeAcao
+
+
+_TOLERANCIA_EM_SEGUNDOS = 0.05
+
+
+@dataclass(frozen=True)
+class ResultadoDaVerificacao:
+    """Resultado da comparação entre a timeline esperada e a timeline lida."""
+
+    aprovada: bool
+    divergencias: tuple[str, ...] = ()
+    avisos: tuple[str, ...] = ()
+
+    @property
+    def mensagem(self) -> str:
+        """Resume a verificação em uma mensagem adequada para o histórico."""
+        if self.aprovada:
+            mensagem = "verificação pós-aplicação aprovada"
+        else:
+            mensagem = "verificação pós-aplicação reprovada: " + " | ".join(self.divergencias)
+        if self.avisos:
+            mensagem += "; avisos: " + " | ".join(self.avisos)
+        return mensagem
+
+
+class VerificadorDaAplicacao:
+    """Confere se a cobertura de mídia depois da aplicação bate com o plano."""
+
+    def __init__(self, tolerancia_em_segundos: float = _TOLERANCIA_EM_SEGUNDOS) -> None:
+        """Configura a tolerância de arredondamento do Premiere."""
+        if tolerancia_em_segundos < 0:
+            raise ValueError("A tolerância da verificação não pode ser negativa.")
+        self._tolerancia = tolerancia_em_segundos
+
+    def verificar(
+        self,
+        timeline_antes: Timeline,
+        timeline_depois: Timeline,
+        plano: PlanoDeEdicao,
+    ) -> ResultadoDaVerificacao:
+        """Compara os intervalos de origem sobreviventes antes e depois da aplicação."""
+        tipos_de_faixa = {faixa.tipo for faixa in timeline_antes.faixas}
+        divergencias: list[str] = []
+        avisos: list[str] = []
+        cortes = tuple(
+            acao for acao in plano.acoes if acao.tipo is TipoDeAcao.CORTE
+        )
+        for tipo_de_faixa in sorted(tipos_de_faixa):
+            esperados = self._intervalos_esperados(
+                timeline_antes, tipo_de_faixa, plano.arquivo_de_origem, cortes
+            )
+            encontrados = self._intervalos_da_timeline(
+                timeline_depois, tipo_de_faixa, plano.arquivo_de_origem
+            )
+            if not self._intervalos_equivalentes(esperados, encontrados):
+                divergencias.append(
+                    f"faixa {tipo_de_faixa}: esperado {self._formatar_intervalos(esperados)}, "
+                    f"encontrado {self._formatar_intervalos(encontrados)}"
+                )
+        avisos.extend(self._avisar_material_posterior_à_ultima_acao(
+            timeline_depois, plano, tipo_de_faixa
+        ))
+        return ResultadoDaVerificacao(not divergencias, tuple(divergencias), tuple(avisos))
+
+    def _avisar_material_posterior_à_ultima_acao(
+        self, timeline: Timeline, plano: PlanoDeEdicao, tipo_de_faixa: str
+    ) -> list[str]:
+        """Sinaliza material depois da última ação para revisão editorial."""
+        if not plano.acoes:
+            return []
+        ultima_acao = max(plano.acoes, key=lambda acao: acao.fim)
+        if ultima_acao.tipo is not TipoDeAcao.CORTE:
+            return []
+        sobras = [
+            clipe.intervalo_na_origem.fim
+            for faixa in timeline.faixas
+            if faixa.tipo == tipo_de_faixa
+            for clipe in self._clipes_do_arquivo(faixa, plano.arquivo_de_origem)
+            if clipe.intervalo_na_origem.inicio >= ultima_acao.fim - self._tolerancia
+            and clipe.intervalo_na_origem.fim > ultima_acao.fim + self._tolerancia
+        ]
+        if not sobras:
+            return []
+        return [
+            f"faixa {tipo_de_faixa}: há material após a última ação, "
+            f"a partir de {ultima_acao.fim:.2f}s; conferir possível sobra"
+        ]
+
+    def _intervalos_esperados(
+        self,
+        timeline: Timeline,
+        tipo_de_faixa: str,
+        arquivo_de_origem: str,
+        cortes: tuple,
+    ) -> tuple[tuple[float, float], ...]:
+        intervalos: list[tuple[float, float]] = []
+        for faixa in timeline.faixas:
+            if faixa.tipo != tipo_de_faixa:
+                continue
+            for clipe in self._clipes_do_arquivo(faixa, arquivo_de_origem):
+                intervalos.extend(self._subtrair_cortes(clipe.intervalo_na_origem, cortes))
+        return self._normalizar_intervalos(intervalos)
+
+    def _intervalos_da_timeline(
+        self, timeline: Timeline, tipo_de_faixa: str, arquivo_de_origem: str
+    ) -> tuple[tuple[float, float], ...]:
+        intervalos = [
+            (clipe.intervalo_na_origem.inicio, clipe.intervalo_na_origem.fim)
+            for faixa in timeline.faixas
+            if faixa.tipo == tipo_de_faixa
+            for clipe in self._clipes_do_arquivo(faixa, arquivo_de_origem)
+        ]
+        return self._normalizar_intervalos(intervalos)
+
+    def _subtrair_cortes(self, intervalo: IntervaloDeTempo, cortes: tuple) -> list[tuple[float, float]]:
+        partes = [(intervalo.inicio, intervalo.fim)]
+        for corte in cortes:
+            novas_partes: list[tuple[float, float]] = []
+            for inicio, fim in partes:
+                if corte.fim <= inicio or corte.inicio >= fim:
+                    novas_partes.append((inicio, fim))
+                    continue
+                if inicio < corte.inicio:
+                    novas_partes.append((inicio, min(fim, corte.inicio)))
+                if corte.fim < fim:
+                    novas_partes.append((max(inicio, corte.fim), fim))
+            partes = novas_partes
+        return partes
+
+    def _intervalos_equivalentes(
+        self, esperados: tuple[tuple[float, float], ...], encontrados: tuple[tuple[float, float], ...]
+    ) -> bool:
+        if len(esperados) != len(encontrados):
+            return False
+        return all(
+            abs(inicio_esperado - inicio_encontrado) <= self._tolerancia
+            and abs(fim_esperado - fim_encontrado) <= self._tolerancia
+            for (inicio_esperado, fim_esperado), (inicio_encontrado, fim_encontrado)
+            in zip(esperados, encontrados)
+        )
+
+    def _clipes_do_arquivo(self, faixa: Faixa, arquivo_de_origem: str) -> list[Clipe]:
+        nome_alvo = arquivo_de_origem.rsplit("/", 1)[-1].lower()
+        return [
+            clipe for clipe in faixa.clipes
+            if clipe.intervalo_na_origem is not None
+            and (clipe.nome or "").rsplit("/", 1)[-1].lower() == nome_alvo
+        ]
+
+    def _normalizar_intervalos(
+        self, intervalos: list[tuple[float, float]]
+    ) -> tuple[tuple[float, float], ...]:
+        ordenados = sorted(intervalos)
+        unidos: list[list[float]] = []
+        for inicio, fim in ordenados:
+            if fim <= inicio + self._tolerancia:
+                continue
+            if unidos and inicio <= unidos[-1][1] + self._tolerancia:
+                unidos[-1][1] = max(unidos[-1][1], fim)
+            else:
+                unidos.append([inicio, fim])
+        return tuple((inicio, fim) for inicio, fim in unidos)
+
+    @staticmethod
+    def _formatar_intervalos(intervalos: tuple[tuple[float, float], ...]) -> str:
+        """Formata intervalos para mensagens curtas e conferíveis."""
+        if not intervalos:
+            return "[]"
+        return "[" + ", ".join(f"{inicio:.2f}-{fim:.2f}s" for inicio, fim in intervalos) + "]"

code/engine/integracoes/audio/classificador_de_musica_essentia.py

@@ -36,7 +36,7 @@ class ClassificadorDeMusicaEssentia:
 
     def classificar(
         self, arquivo: str | Path,
-    ) -> tuple[tuple[PontuacaoDeEtiqueta, ...], tuple[PontuacaoDeEtiqueta, ...]]:
+    ) -> tuple[tuple[PontuacaoDeEtiqueta, ...], tuple[PontuacaoDeEtiqueta, ...], tuple[PontuacaoDeEtiqueta, ...]]:
         """
         Classifica o gênero e o humor diretamente do conteúdo do arquivo.
 
@@ -71,11 +71,19 @@ class ClassificadorDeMusicaEssentia:
         embedding = modelo_de_embedding(audio)
         previsao_de_genero = modelo_de_genero(embedding)
         previsao_de_humor = modelo_de_humor(embedding)
+        pontuacoes_de_humor = self._converter_pontuacoes(previsao_de_humor, "humor")
+        nomes_de_tema = {"action", "adventure", "advertising", "background", "children", "christmas", "commercial", "corporate", "documentary", "drama", "film", "game", "movie", "nature", "sport", "trailer", "travel"}
         return (
-            self._converter_pontuacoes(previsao_de_genero, "genero"),
-            self._converter_pontuacoes(previsao_de_humor, "humor"),
+            self._duas_maiores(self._converter_pontuacoes(previsao_de_genero, "genero")),
+            self._duas_maiores(tuple(item for item in pontuacoes_de_humor if item.etiqueta not in nomes_de_tema)),
+            self._duas_maiores(tuple(item for item in pontuacoes_de_humor if item.etiqueta in nomes_de_tema)),
         )
 
+    @staticmethod
+    def _duas_maiores(pontuacoes: tuple[PontuacaoDeEtiqueta, ...]) -> tuple[PontuacaoDeEtiqueta, ...]:
+        """Retorna as duas maiores probabilidades, preservando o ranking."""
+        return pontuacoes[:2]
+
     def _obter_modelos(self, classe_de_embedding: Any, classe_de_classificacao: Any):
         if self._modelos_carregados is not None:
             return self._modelos_carregados

code/engine/integracoes/audio/modelos_de_analise_musical.py

@@ -41,5 +41,7 @@ class ResultadoDaAnaliseMusical:
     etiquetas: tuple[str, ...] = field(default_factory=tuple)
     pontuacoes_de_genero: tuple[PontuacaoDeEtiqueta, ...] = field(default_factory=tuple)
     pontuacoes_de_humor: tuple[PontuacaoDeEtiqueta, ...] = field(default_factory=tuple)
+    pontuacoes_de_tema: tuple[PontuacaoDeEtiqueta, ...] = field(default_factory=tuple)
+    temas: tuple[str, ...] = field(default_factory=tuple)
     provedor: str = "Essentia"
     modelo: str | None = None

code/engine/integracoes/audio/provider_de_analise_musical_essentia.py

@@ -57,8 +57,12 @@ class AnalisadorDeMusicaInstrumentalEssentia:
             raise ValueError("O Essentia devolveu uma análise vazia.")
         pontuacoes_de_genero: tuple[Any, ...] = ()
         pontuacoes_de_humor: tuple[Any, ...] = ()
+        pontuacoes_de_tema: tuple[Any, ...] = ()
         if self._classificador is not None:
-            pontuacoes_de_genero, pontuacoes_de_humor = self._classificador.classificar(caminho)
+            classificacoes = self._classificador.classificar(caminho)
+            pontuacoes_de_genero, pontuacoes_de_humor = classificacoes[:2]
+            if len(classificacoes) > 2:
+                pontuacoes_de_tema = classificacoes[2]
         generos = (
             tuple(item.etiqueta for item in pontuacoes_de_genero)
             if pontuacoes_de_genero
@@ -70,7 +74,7 @@ class AnalisadorDeMusicaInstrumentalEssentia:
             else self._etiquetas(dados, ("mood", "moods"))
         )
         return self._converter_resultado(
-            caminho, dados, pontuacoes_de_genero, pontuacoes_de_humor, generos, humores,
+            caminho, dados, pontuacoes_de_genero, pontuacoes_de_humor, generos, humores, pontuacoes_de_tema,
         )
 
     def _obter_extrator(self) -> Callable[[str], tuple[Any, Any]]:
@@ -94,6 +98,7 @@ class AnalisadorDeMusicaInstrumentalEssentia:
         pontuacoes_de_humor: tuple[Any, ...] = (),
         generos: tuple[str, ...] = (),
         humores: tuple[str, ...] = (),
+        pontuacoes_de_tema: tuple[Any, ...] = (),
     ) -> ResultadoDaAnaliseMusical:
         return ResultadoDaAnaliseMusical(
             caminho_do_arquivo=caminho,
@@ -105,10 +110,12 @@ class AnalisadorDeMusicaInstrumentalEssentia:
             dancabilidade=self._numero(self._buscar(dados, "rhythm.danceability")),
             generos=generos,
             humores=humores,
+            temas=tuple(item.etiqueta for item in pontuacoes_de_tema),
             instrumentos=self._etiquetas(dados, ("instrument", "instruments")),
             etiquetas=self._etiquetas(dados, ("tags", "semantic")),
             pontuacoes_de_genero=pontuacoes_de_genero,
             pontuacoes_de_humor=pontuacoes_de_humor,
+            pontuacoes_de_tema=pontuacoes_de_tema,
             modelo=self._nome_do_modelo,
         )
 

code/engine/persistencia/esquema.py

@@ -94,6 +94,9 @@ CREATE TABLE IF NOT EXISTS analises_musicais (
     modo TEXT,
     intensidade REAL,
     dancabilidade REAL,
+    temas_json TEXT,
+    instrumentos_json TEXT,
+    etiquetas_json TEXT,
     resultado_bruto_json TEXT,
     criada_em TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ','now'))
 );
@@ -512,6 +515,9 @@ _VIEWS = (
 )
 
 _COLUNAS_ACRESCENTADAS: tuple[tuple[str, str, str], ...] = (
+    ("analises_musicais", "temas_json", "TEXT"),
+    ("analises_musicais", "instrumentos_json", "TEXT"),
+    ("analises_musicais", "etiquetas_json", "TEXT"),
     ("segmentos_de_transcricao", "energia_rms", "REAL"),
     ("segmentos_de_transcricao", "pitch_mediano_hz", "REAL"),
     ("segmentos_de_transcricao", "pitch_desvio_hz", "REAL"),

code/engine/persistencia/repositorio_de_trilhas.py

@@ -78,9 +78,24 @@ class RepositorioDeTrilhasSQLite:
                 (trilha_id,),
             )
 
+    def reabrir_analises_sem_etiquetas(self, pasta_id: int | None = None) -> None:
+        """Volta a enfileirar análises antigas que não têm classificação semântica."""
+        filtro = "" if pasta_id is None else " AND t.pasta_id = ?"
+        parametros = () if pasta_id is None else (pasta_id,)
+        with self.conexao:
+            self.conexao.execute(
+                """UPDATE trilhas_musicais AS t SET status = 'aguardando', erro = NULL
+                   WHERE t.status = 'concluida' AND EXISTS (
+                       SELECT 1 FROM analises_musicais AS a
+                       WHERE a.trilha_id = t.id
+                         AND NOT EXISTS (SELECT 1 FROM etiquetas_musicais e WHERE e.analise_id = a.id)
+                   )""" + filtro,
+                parametros,
+            )
+
     def registrar_analise(self, trilha: TrilhaMusical, resultado: ResultadoDaAnaliseMusical) -> None:
         """Grava descritores e etiquetas produzidos pelo áudio da trilha."""
-        bruto = json.dumps({"generos": resultado.generos, "humores": resultado.humores}, ensure_ascii=False)
+        bruto = json.dumps({"generos": resultado.generos, "humores": resultado.humores, "temas": resultado.temas, "instrumentos": resultado.instrumentos, "etiquetas": resultado.etiquetas}, ensure_ascii=False)
         with self.conexao:
             self.conexao.execute(
                 "UPDATE trilhas_musicais SET hash_do_conteudo = ?, status = 'concluida', erro = NULL, atualizada_em = strftime('%Y-%m-%dT%H:%M:%fZ','now') WHERE id = ?",
@@ -88,14 +103,14 @@ class RepositorioDeTrilhasSQLite:
             )
             cursor = self.conexao.execute(
                 """INSERT INTO analises_musicais
-                   (trilha_id, provedor, modelo, duracao_em_segundos, batidas_por_minuto, tonalidade, modo, intensidade, dancabilidade, resultado_bruto_json)
-                   VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
+                   (trilha_id, provedor, modelo, duracao_em_segundos, batidas_por_minuto, tonalidade, modo, intensidade, dancabilidade, temas_json, instrumentos_json, etiquetas_json, resultado_bruto_json)
+                   VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
                 (trilha.identificador, resultado.provedor, resultado.modelo, resultado.duracao_em_segundos,
                  resultado.batidas_por_minuto, resultado.tonalidade, resultado.modo, resultado.intensidade,
-                 resultado.dancabilidade, bruto),
+                 resultado.dancabilidade, json.dumps(resultado.temas, ensure_ascii=False), json.dumps(resultado.instrumentos, ensure_ascii=False), json.dumps(resultado.etiquetas, ensure_ascii=False), bruto),
             )
             analise_id = cursor.lastrowid
-            for tipo, etiquetas in (("genero", resultado.pontuacoes_de_genero), ("humor", resultado.pontuacoes_de_humor)):
+            for tipo, etiquetas in (("genero", resultado.pontuacoes_de_genero), ("humor", resultado.pontuacoes_de_humor), ("tema", resultado.pontuacoes_de_tema)):
                 self.conexao.executemany(
                     "INSERT INTO etiquetas_musicais(analise_id, tipo, etiqueta, confianca, ordem) VALUES (?, ?, ?, ?, ?)",
                     ((analise_id, tipo, item.etiqueta, item.confianca, ordem) for ordem, item in enumerate(etiquetas)),

code/engine/testes/duplos_de_premiere.py

@@ -5,7 +5,8 @@ têm posição na timeline diferente da posição no arquivo de origem — o mes
 descompasso encontrado no projeto real entre ``inicio_na_timeline`` e
 ``inicio_na_origem`` do banco de análises. Implementa só as ferramentas MCP
 que o módulo ``engine.editor`` usa: ``get_active_sequence``, ``split_clip``,
-``remove_from_timeline``, ``remove_linked_from_timeline``, ``set_clip_properties`` e ``add_marker``.
+``remove_from_timeline``, ``remove_linked_from_timeline``,
+``duplicate_linked_range_to_start``, ``set_clip_properties`` e ``add_marker``.
 """
 
 from __future__ import annotations
@@ -100,6 +101,7 @@ class ClienteMCPFalso(ClienteMCP):
             "split_clip": self._simular_split_clip,
             "remove_from_timeline": self._simular_ripple_delete,
             "remove_linked_from_timeline": self._simular_remocao_vinculada,
+            "duplicate_linked_range_to_start": self._simular_gancho_vinculado_no_inicio,
             "set_clip_properties": self._simular_set_clip_properties,
             "add_marker": self._simular_add_marker,
             "undo": self._simular_undo,
@@ -223,6 +225,43 @@ class ClienteMCPFalso(ClienteMCP):
             self._simular_ripple_delete({"node_id": identificador, "ripple": True})
         return {"removed": True, "verified": True}
 
+    def _simular_gancho_vinculado_no_inicio(self, argumentos: dict[str, Any]) -> dict[str, Any]:
+        """Duplica um par isolado no início e preserva sua ocorrência original."""
+        identificadores = argumentos["node_ids"]
+        encontrados: list[tuple[str, _ClipeFalso]] = []
+        for identificador_da_faixa, clipes in self._faixas.items():
+            for clipe in clipes:
+                if clipe.identificador in identificadores:
+                    encontrados.append((identificador_da_faixa, clipe))
+        if len(encontrados) != 2 or {faixa.split("_")[0] for faixa, _ in encontrados} != {"video", "audio"}:
+            raise ErroDeFerramentaMCP("O gancho exige um par de vídeo e áudio existente.")
+        inicios = {round(clipe.inicio_na_timeline, 6) for _, clipe in encontrados}
+        fins = {round(clipe.fim_na_timeline, 6) for _, clipe in encontrados}
+        if len(inicios) != 1 or len(fins) != 1:
+            raise ErroDeFerramentaMCP("O par não ocupa o mesmo intervalo.")
+
+        self._salvar_estado()
+        inicio_na_origem = float(argumentos["source_in_seconds"])
+        fim_na_origem = float(argumentos["source_out_seconds"])
+        duracao = fim_na_origem - inicio_na_origem
+        novos_ids: list[str] = []
+        for identificador_da_faixa, clipe in encontrados:
+            faixa = self._faixas[identificador_da_faixa]
+            for outro in faixa:
+                outro.inicio_na_timeline += duracao
+                outro.fim_na_timeline += duracao
+            novo = self._novo_clipe(
+                clipe.nome,
+                0.0,
+                duracao,
+                inicio_na_origem,
+                fim_na_origem,
+            )
+            faixa.append(novo)
+            faixa.sort(key=lambda item: item.inicio_na_timeline)
+            novos_ids.append(novo.identificador)
+        return {"duplicated": True, "verified": True, "insertedNodeIds": novos_ids}
+
     def _simular_set_clip_properties(self, argumentos: dict[str, Any]) -> dict[str, Any]:
         """Aceita a alteração de propriedades sem simular geometria (não é usada pelos testes)."""
         del argumentos

code/engine/testes/test_aplicador_de_plano_de_edicao.py

@@ -249,6 +249,64 @@ class TesteAplicadorDePlanoDeEdicao(unittest.TestCase):
         self.assertEqual(len(chamadas_de_marcador), 1)
         self.assertIn("MASTOPEXIA", chamadas_de_marcador[0][1]["comments"])
 
+    def test_gancho_isola_video_e_audio_e_duplica_no_inicio(self):
+        cliente = ClienteMCPFalso(clipe_unico=True)
+        aplicador = AplicadorDePlanoDeEdicao(
+            acesso_ao_editor=AcessoAoEditor(AcessoATimeline(cliente)),
+            conversor_de_timeline=ConversorDeTimeline(),
+            escrita=EscritaNoEditor(cliente),
+            mapeador=MapeadorDeTempoDeOrigemParaTimeline(),
+        )
+        plano = PlanoDeEdicao("0E6A8290.mp4", (
+            AcaoDeEdicao(
+                TipoDeAcao.GANCHO,
+                inicio=80.0,
+                fim=90.0,
+                motivo="gancho de abertura",
+                parametros={"target": 0, "keep_original": True},
+            ),
+        ))
+
+        resultado = aplicador.aplicar(plano)
+
+        self.assertTrue(resultado.todas_bem_sucedidas, msg=[item.detalhe for item in resultado.falhas])
+        ganchos = [chamada for chamada in cliente.chamadas if chamada[0] == "duplicate_linked_range_to_start"]
+        self.assertEqual(len(ganchos), 1)
+        self.assertEqual(len(ganchos[0][1]["node_ids"]), 2)
+        self.assertEqual(cliente._faixas["video_0"][0].inicio_na_origem, 80.0)
+        self.assertEqual(cliente._faixas["audio_0"][0].inicio_na_origem, 80.0)
+        self.assertEqual(cliente._faixas["video_0"][0].inicio_na_timeline, 0.0)
+        self.assertEqual(cliente._faixas["audio_0"][0].inicio_na_timeline, 0.0)
+        self.assertEqual(
+            sum(1 for clipe in cliente._faixas["video_0"] if clipe.inicio_na_origem == 80.0),
+            2,
+        )
+        self.assertEqual(
+            sum(1 for clipe in cliente._faixas["audio_0"] if clipe.inicio_na_origem == 80.0),
+            2,
+        )
+
+    def test_gancho_e_executado_apos_cortes_e_antes_de_zoom(self):
+        cliente = ClienteMCPFalso(clipe_unico=True)
+        aplicador = AplicadorDePlanoDeEdicao(
+            acesso_ao_editor=AcessoAoEditor(AcessoATimeline(cliente)),
+            conversor_de_timeline=ConversorDeTimeline(),
+            escrita=EscritaNoEditor(cliente),
+            mapeador=MapeadorDeTempoDeOrigemParaTimeline(),
+        )
+        plano = PlanoDeEdicao("0E6A8290.mp4", (
+            AcaoDeEdicao(TipoDeAcao.CORTE, 20.0, 30.0, "retirar bastidor"),
+            AcaoDeEdicao(TipoDeAcao.GANCHO, 80.0, 90.0, "gancho"),
+            AcaoDeEdicao(TipoDeAcao.ZOOM, 100.0, 105.0, "ênfase", {"scale": 1.15}),
+        ))
+
+        resultado = aplicador.aplicar(plano)
+
+        self.assertTrue(resultado.todas_bem_sucedidas, msg=[item.detalhe for item in resultado.falhas])
+        nomes = [nome for nome, _ in cliente.chamadas]
+        self.assertLess(nomes.index("remove_linked_from_timeline"), nomes.index("duplicate_linked_range_to_start"))
+        self.assertLess(nomes.index("duplicate_linked_range_to_start"), nomes.index("set_clip_properties"))
+
 
 if __name__ == "__main__":
     unittest.main()

code/engine/testes/test_aplicar_plano_de_edicao.py

@@ -7,7 +7,7 @@ from pathlib import Path
 from unittest.mock import patch
 
 from engine import aplicar_plano_de_edicao
-from engine.editor import ErroDePlanoInvalido
+from engine.editor import AcaoDeEdicao, ErroDePlanoInvalido, PlanoDeEdicao, TipoDeAcao
 
 
 class TesteResolucaoDoNode(unittest.TestCase):
@@ -62,6 +62,23 @@ class TestePreValidacaoDoPlano(unittest.TestCase):
         validar.assert_called_once()
         resolver_node.assert_not_called()
 
+    def test_gancho_exige_backup_confirmado(self) -> None:
+        """A operação composta não começa quando a recuperação não foi criada."""
+        plano = PlanoDeEdicao("video.mp4", (
+            AcaoDeEdicao(TipoDeAcao.GANCHO, 10.0, 15.0, "gancho"),
+        ))
+
+        with self.assertRaisesRegex(ErroDePlanoInvalido, "não confirmou o backup"):
+            aplicar_plano_de_edicao._garantir_backup_para_ganchos(plano, False)
+
+    def test_corte_preserva_comportamento_legado_quando_backup_falha(self) -> None:
+        """A exigência adicional fica restrita ao gancho estrutural."""
+        plano = PlanoDeEdicao("video.mp4", (
+            AcaoDeEdicao(TipoDeAcao.CORTE, 10.0, 15.0, "retirada"),
+        ))
+
+        aplicar_plano_de_edicao._garantir_backup_para_ganchos(plano, False)
+
     def test_painel_rejeita_corte_sem_plano_associado_ao_banco(self) -> None:
         """Não permite contornar a validação colando um corte sem transcrição vinculada."""
         with tempfile.TemporaryDirectory() as pasta:

code/engine/testes/test_escrita_no_editor.py

@@ -71,5 +71,19 @@ class TesteDividirClipeSeNecessario(unittest.TestCase):
             self._dividir("razor changed the track clip count from 4 to 7, expected 5")
 
 
+class TesteDuplicarTrechosVinculados(unittest.TestCase):
+    """Cobre o contrato estreito da escrita do gancho editorial."""
+
+    def test_exige_exatamente_dois_identificadores(self):
+        escrita = EscritaNoEditor(_ClienteQueRecusa("não deveria chamar"))
+        with self.assertRaisesRegex(ErroDeEscritaNoEditor, "exatamente"):
+            escrita.duplicar_trecho_vinculado_para_o_inicio(["somente-video"], 10.0, 15.0)
+
+    def test_converte_falha_da_ferramenta_em_erro_de_escrita(self):
+        escrita = EscritaNoEditor(_ClienteQueRecusa("faixa adicional ocupada"))
+        with self.assertRaisesRegex(ErroDeEscritaNoEditor, "faixa adicional ocupada"):
+            escrita.duplicar_trecho_vinculado_para_o_inicio(["video", "audio"], 10.0, 15.0)
+
+
 if __name__ == "__main__":
     unittest.main()

code/engine/testes/test_leitor_de_plano_de_edicao.py

@@ -66,6 +66,50 @@ class TesteLeitorDePlanoDeEdicao(unittest.TestCase):
                 "actions": [{"kind": "voar", "start": 0, "end": 1, "reason": "x"}],
             })
 
+    def test_le_gancho_duplicado_para_o_inicio(self):
+        plano = self.leitor.ler_de_dicionario({
+            "source": "a.mp4",
+            "actions": [{
+                "kind": "hook",
+                "start": 40,
+                "end": 46,
+                "reason": "gancho de abertura",
+                "params": {"target": 0, "keep_original": True},
+            }],
+        })
+        self.assertEqual(plano.acoes[0].tipo, TipoDeAcao.GANCHO)
+        self.assertEqual(plano.acoes[0].parametros["target"], 0)
+
+    def test_gancho_para_destino_diferente_do_inicio_e_rejeitado(self):
+        with self.assertRaisesRegex(ErroDePlanoInvalido, "target precisa ser 0"):
+            self.leitor.ler_de_dicionario({
+                "source": "a.mp4",
+                "actions": [{
+                    "kind": "hook", "start": 40, "end": 46,
+                    "reason": "reordenar", "params": {"target": 12},
+                }],
+            })
+
+    def test_gancho_que_remove_o_original_e_rejeitado(self):
+        with self.assertRaisesRegex(ErroDePlanoInvalido, "keep_original precisa ser true"):
+            self.leitor.ler_de_dicionario({
+                "source": "a.mp4",
+                "actions": [{
+                    "kind": "hook", "start": 40, "end": 46,
+                    "reason": "abertura", "params": {"keep_original": False},
+                }],
+            })
+
+    def test_corte_sobreposto_ao_gancho_e_rejeitado(self):
+        with self.assertRaisesRegex(ErroDePlanoInvalido, "não pode sobrepor"):
+            self.leitor.ler_de_dicionario({
+                "source": "a.mp4",
+                "actions": [
+                    {"kind": "cut", "start": 42, "end": 44, "reason": "cortar"},
+                    {"kind": "hook", "start": 40, "end": 46, "reason": "abertura"},
+                ],
+            })
+
     def test_fim_menor_ou_igual_ao_inicio_levanta_erro(self):
         with self.assertRaises(ErroDePlanoInvalido):
             self.leitor.ler_de_dicionario({

code/engine/testes/test_validador_semantico_de_plano.py

@@ -1,4 +1,4 @@
-"""Testes de regressão da integridade semântica dos cortes editoriais."""
+"""Testes de regressão da integridade semântica das emendas editoriais."""
 
 import unittest
 
@@ -8,7 +8,7 @@ from engine.scanner.modelos import PalavraDeTranscricao, SegmentoDeTranscricao
 
 
 class TesteValidadorSemanticoDePlano(unittest.TestCase):
-    """Impede cortes de palavra e retomadas no meio de uma frase."""
+    """Impede cortes de palavra, frases incompletas e ganchos truncados."""
 
     def setUp(self) -> None:
         """Cria o validador com a margem segura usada pela aplicação real."""
@@ -104,6 +104,46 @@ class TesteValidadorSemanticoDePlano(unittest.TestCase):
 
         self.assertIn("palavra_interceptada", {problema.codigo for problema in problemas})
 
+    def test_aceita_gancho_de_frase_completa_com_margens(self) -> None:
+        falas = (
+            SegmentoDeTranscricao(0.0, 4.0, "Antes.", palavras=(
+                PalavraDeTranscricao("Antes.", 3.4, 4.0),
+            )),
+            SegmentoDeTranscricao(10.4, 13.5, "Gancho completo.", palavras=(
+                PalavraDeTranscricao("Gancho", 10.4, 10.9),
+                PalavraDeTranscricao("completo.", 13.0, 13.5),
+            )),
+            SegmentoDeTranscricao(20.0, 21.0, "Depois.", palavras=(
+                PalavraDeTranscricao("Depois.", 20.0, 21.0),
+            )),
+        )
+        plano = PlanoDeEdicao("video.mp4", (
+            AcaoDeEdicao(TipoDeAcao.GANCHO, 10.1, 13.8, "gancho"),
+        ))
+
+        self.assertEqual(self.validador.validar(plano, falas), ())
+
+    def test_rejeita_gancho_que_termina_com_frase_truncada(self) -> None:
+        falas = (
+            SegmentoDeTranscricao(0.0, 4.0, "Antes.", palavras=(
+                PalavraDeTranscricao("Antes.", 3.4, 4.0),
+            )),
+            SegmentoDeTranscricao(10.4, 13.5, "Trazer uma seguran", palavras=(
+                PalavraDeTranscricao("Trazer", 10.4, 10.9),
+                PalavraDeTranscricao("seguran", 13.0, 13.5),
+            )),
+            SegmentoDeTranscricao(20.0, 21.0, "Depois.", palavras=(
+                PalavraDeTranscricao("Depois.", 20.0, 21.0),
+            )),
+        )
+        plano = PlanoDeEdicao("video.mp4", (
+            AcaoDeEdicao(TipoDeAcao.GANCHO, 10.1, 13.8, "gancho"),
+        ))
+
+        problemas = self.validador.validar(plano, falas)
+
+        self.assertIn("gancho_termina_no_meio_da_frase", {problema.codigo for problema in problemas})
+
 
 if __name__ == "__main__":
     unittest.main()

code/engine/testes/test_verificador_da_aplicacao.py

@@ -0,0 +1,72 @@
+"""Testes da leitura estrutural depois da aplicação do plano."""
+
+import unittest
+
+from engine.dominio import Clipe, Faixa, IntervaloDeTempo, Timeline
+from engine.editor.modelos import AcaoDeEdicao, PlanoDeEdicao, TipoDeAcao
+from engine.editor.verificador_da_aplicacao import VerificadorDaAplicacao
+
+
+class TesteVerificadorDaAplicacao(unittest.TestCase):
+    """Garante que sobras e lacunas na timeline sejam detectadas."""
+
+    def _timeline(self, fim_do_ultimo_clipe: float) -> Timeline:
+        """Monta uma timeline simples com vídeo e áudio vinculados por intervalo."""
+        faixas = []
+        for tipo in ("video", "audio"):
+            faixas.append(Faixa(
+                f"{tipo}_0", tipo, tipo, 0, [Clipe(
+                    f"clipe_{tipo}", "fonte.mp4",
+                    IntervaloDeTempo(0.0, fim_do_ultimo_clipe),
+                    IntervaloDeTempo(0.0, fim_do_ultimo_clipe),
+                )]
+            ))
+        return Timeline("sequencia", "Sequência", 100.0, faixas=faixas)
+
+    def test_aprova_cobertura_exata_depois_do_corte(self):
+        """Aprova quando os dois tipos de faixa preservam exatamente o esperado."""
+        antes = self._timeline(100.0)
+        depois = Timeline("sequencia", "Sequência", 90.0, faixas=[
+            Faixa("video_0", "video", "video", 0, [
+                Clipe("v1", "fonte.mp4", IntervaloDeTempo(0, 10), IntervaloDeTempo(0, 10)),
+                Clipe("v2", "fonte.mp4", IntervaloDeTempo(10, 90), IntervaloDeTempo(20, 100)),
+            ]),
+            Faixa("audio_0", "audio", "audio", 0, [
+                Clipe("a1", "fonte.mp4", IntervaloDeTempo(0, 10), IntervaloDeTempo(0, 10)),
+                Clipe("a2", "fonte.mp4", IntervaloDeTempo(10, 90), IntervaloDeTempo(20, 100)),
+            ]),
+        ])
+        plano = PlanoDeEdicao("fonte.mp4", (
+            AcaoDeEdicao(TipoDeAcao.CORTE, 10, 20, "remover trecho"),
+        ))
+
+        resultado = VerificadorDaAplicacao().verificar(antes, depois, plano)
+
+        self.assertTrue(resultado.aprovada)
+        self.assertTrue(resultado.avisos)
+
+    def test_reprova_quando_sobra_um_trecho_na_timeline(self):
+        """Reprova quando o Premiere deixa uma sobra além do plano."""
+        antes = self._timeline(100.0)
+        depois = Timeline("sequencia", "Sequência", 91.0, faixas=[
+            Faixa("video_0", "video", "video", 0, [
+                Clipe("v1", "fonte.mp4", IntervaloDeTempo(0, 10), IntervaloDeTempo(0, 10)),
+                Clipe("v2", "fonte.mp4", IntervaloDeTempo(10, 91), IntervaloDeTempo(20, 101)),
+            ]),
+            Faixa("audio_0", "audio", "audio", 0, [
+                Clipe("a1", "fonte.mp4", IntervaloDeTempo(0, 10), IntervaloDeTempo(0, 10)),
+                Clipe("a2", "fonte.mp4", IntervaloDeTempo(10, 91), IntervaloDeTempo(20, 101)),
+            ]),
+        ])
+        plano = PlanoDeEdicao("fonte.mp4", (
+            AcaoDeEdicao(TipoDeAcao.CORTE, 10, 20, "remover trecho"),
+        ))
+
+        resultado = VerificadorDaAplicacao().verificar(antes, depois, plano)
+
+        self.assertFalse(resultado.aprovada)
+        self.assertIn("esperado", resultado.mensagem)
+
+
+if __name__ == "__main__":
+    unittest.main()

code/plugins/premiere-pro/skills/editar-por-voz/SKILL.md

@@ -76,7 +76,7 @@ ou evidência obrigatória estiver ausente, pare e relate exatamente o que falta
 5. Reanalise as ênfases apenas depois de definir o material sobrevivente. Se o
    banco não tiver métricas ou a camada correspondente estiver incompleta,
    decida pelo texto e registre a limitação.
-6. Decida cortes, zooms, textos e marcadores somente quando o contrato de
+6. Decida cortes, ganchos, zooms, textos e marcadores somente quando o contrato de
    aplicação suportar a ação. Cada ação deve ter motivo verificável.
 7. Antes de salvar, reconstrua o texto que sobreviverá a cada emenda. Um
    segmento do Whisper não equivale a uma frase: una segmentos adjacentes
@@ -88,13 +88,19 @@ ou evidência obrigatória estiver ausente, pare e relate exatamente o que falta
    `planos_de_edicao` e suas ações ordenadas em `acoes_do_plano`, associado ao
    `video_id`, ao tipo de vídeo e ao contexto editorial carregado.
 9. Faça preview do texto sobrevivente, lendo em sequência a última frase antes
-   e a primeira frase depois de cada corte. Apresente decisões e incertezas
-   para revisão humana. Uma alteração no plano exige novo preview.
+   e a primeira frase depois de cada corte. Para `hook`, apresente a frase
+   completa que abrirá o vídeo e a primeira frase original que virá em seguida.
+   Uma alteração no plano exige novo preview.
 10. Após aprovação explícita, confirme a sequência atual, crie backup ou
    duplicata, aplique o plano pelo fluxo suportado do Premiere e registre o
    resultado em `aplicacoes_do_plano`.
 11. Reconsulte a timeline, compare com o plano e registre a verificação. Separe
-    o que foi comprovado automaticamente do que exige avaliação visual.
+   o que foi comprovado automaticamente do que exige avaliação visual.
+
+Essa releitura pós-aplicação é obrigatória: uma aplicação só pode ser
+reportada como bem-sucedida quando a cobertura de origem em vídeo e áudio
+corresponder ao complemento dos cortes do plano. Sobras, lacunas ou
+desalinhamentos devem reprovar a verificação e ficar registrados no histórico.
 
 ## Contrato da decisão
 
@@ -114,10 +120,12 @@ O JSON abaixo é uma representação de trabalho, não a fonte principal:
 }
 ```
 
-`cut` remove um intervalo. Todos os tempos referem-se à mídia original. A
-ação precisa ter `start < end`, estar dentro da duração e não sobrepor outra
-ação incompatível. Use `reason` para registrar a fala, comparação ou evidência
-que fundamentou a decisão.
+`cut` remove um intervalo. `hook` duplica um único trecho vinculado em `0s` e
+mantém a fala na posição original; use somente
+`params: {"target": 0, "keep_original": true}`. Todos os tempos referem-se à
+mídia original. A ação precisa ter `start < end`, estar dentro da duração e
+não sobrepor outra ação incompatível. Use `reason` para registrar a fala,
+comparação ou evidência que fundamentou a decisão.
 
 Leia, conforme a etapa, [criterios/02-triagem-roteiro-vs-conversa.md](criterios/02-triagem-roteiro-vs-conversa.md),
 [criterios/03-escolha-da-melhor-tomada.md](criterios/03-escolha-da-melhor-tomada.md),
@@ -125,7 +133,9 @@ Leia, conforme a etapa, [criterios/02-triagem-roteiro-vs-conversa.md](criterios/
 [criterios/05-zoom.md](criterios/05-zoom.md),
 [criterios/06-texto-corte-marcador.md](criterios/06-texto-corte-marcador.md),
 [criterios/07-ritmo.md](criterios/07-ritmo.md) e
-[criterios/10-revisao-humana.md](criterios/10-revisao-humana.md).
+[criterios/10-revisao-humana.md](criterios/10-revisao-humana.md). Quando o
+pedido envolver gancho ou reordenação, leia também
+[criterios/11-gancho.md](criterios/11-gancho.md).
 
 ## Limites
 
@@ -146,6 +156,6 @@ Relate sempre em português:
 - edição, vídeo e versão da análise usados;
 - tomadas encontradas e escolhidas, com motivo;
 - falas descartadas como bastidor ou repetição;
-- cortes, zooms, textos e marcadores propostos;
+- cortes, ganchos, zooms, textos e marcadores propostos;
 - decisões rejeitadas ou ambíguas;
 - plano salvo, aplicação realizada e verificação pendente.

code/plugins/premiere-pro/skills/editar-por-voz/criterios/08-formato-de-saida.md

@@ -15,6 +15,9 @@ em `planos_de_edicao` e `acoes_do_plano`. Você nunca escreve XML.
   "actions": [
     {"kind": "cut",    "start": 21.9,  "end": 127.6,
      "reason": "tomadas descartadas, frases interrompidas e conversa com a equipe"},
+    {"kind": "hook",   "start": 141.2, "end": 147.8,
+     "params": {"target": 0, "keep_original": true},
+     "reason": "frase completa escolhida como gancho de abertura"},
     {"kind": "zoom",   "start": 2.0,   "end": 10.7,
      "params": {"scale": 1.15}, "reason": "abertura: \"Aquela mama\" (ênfase 0.42)"},
     {"kind": "text",   "start": 127.7, "end": 129.0,
@@ -39,13 +42,14 @@ erro é silencioso.
 Ambos ≥ 0. Um `end <= start` é rejeitado.
 
 ### 3. Tipos
-`cut` · `zoom` · `text` · `marker`
+`cut` · `hook` · `zoom` · `text` · `marker`
 
 ### 4. Parâmetros por tipo
 
 | Tipo | `params` |
 |---|---|
 | `cut` | nenhum |
+| `hook` | `target: 0` e `keep_original: true` |
 | `zoom` | `scale` entre 1.0 e 3.0 (padrão 1.3 se omitido) |
 | `text` | `content` **obrigatório**, até 120 caracteres |
 | `marker` | opcional: `content` vira o nome do marcador |
@@ -70,6 +74,14 @@ ao menos 0,30s de respiro junto às palavras mantidas. A engine bloqueia borda
 dentro de palavra, continuação gramatical e margem insuficiente. Detalhes em
 `06-texto-corte-marcador.md` e `10-revisao-humana.md`.
 
+### 7. Gancho: uma cópia completa para o início
+
+Use no máximo um `hook`. O intervalo deve estar contido em um único clipe de
+vídeo e seu áudio vinculado, em velocidade normal. A frase copiada precisa ter
+começo, fechamento e 0,30s de margem nas duas bordas. O aplicador aceita apenas
+o destino `0` e preserva a ocorrência original; nenhuma outra ação pode
+sobrepor esse intervalo.
+
 ## Persistência
 
 Depois de validar o JSON, crie um registro em `planos_de_edicao` ligado ao
@@ -81,8 +93,11 @@ confirmada.
 
 - **Plano ou ação inválida** → o plano inteiro é bloqueado antes de alterar a
   timeline.
-- **Borda de corte semanticamente insegura** → o plano inteiro é bloqueado
+- **Borda de corte ou gancho semanticamente insegura** → o plano inteiro é bloqueado
   antes da conexão com o Premiere e antes do backup.
+- **Gancho com faixas adicionais ocupadas, mídia retimada ou par A/V
+  ambíguo** → recusado; use uma sequência simples de diálogo ou faça a
+  duplicação manualmente.
 - **Ação apontando para material cortado** → descartada e reportada, nunca
   deslizada para o conteúdo vizinho.
 - **Ação fora da mídia** → reportada como não colocada.

code/plugins/premiere-pro/skills/editar-por-voz/criterios/10-revisao-humana.md

@@ -10,22 +10,26 @@ presuma que uma etapa posterior corrigirá bordas editoriais imprecisas.
 
 ## Preview obrigatório
 
-Antes de pedir aprovação, apresente para cada corte:
+Antes de pedir aprovação, apresente para cada corte ou gancho:
 
-- intervalo removido e motivo;
+- intervalo afetado e motivo;
 - última frase completa que ficará antes;
 - primeira frase completa que ficará depois;
-- texto da emenda resultante;
+- texto da emenda resultante quando houver remoção;
 - margem acústica em cada lado;
 - qualquer incerteza que exija escuta humana.
 
+Para `hook`, apresente também a frase completa que passará a abrir o vídeo e
+confirme que a ocorrência original será preservada.
+
 O editor deve aprovar o conteúdo sobrevivente, não apenas a quantidade de
 ações. Se o preview mostrar palavra truncada, oração incompleta ou continuação
 sem contexto, o plano volta para edição e recebe novos limites.
 
 ## Defesa automática
 
-Ao clicar em **Aplicar plano na timeline**, a engine revalida os cortes antes
+Ao clicar em **Aplicar plano na timeline**, a engine revalida cortes e
+ganchos antes
 de se conectar ao Premiere e antes de criar o backup. A aplicação é bloqueada
 quando encontra:
 
@@ -33,6 +37,7 @@ quando encontra:
 - menos de 0,30s entre a borda e a palavra mantida;
 - fala mantida interrompida antes do corte;
 - retomada no meio de frase depois do corte.
+- gancho sem frase completa ou sem margem nas duas extremidades.
 
 Essa validação é uma rede de segurança, não substitui o preview. Depois que o
 plano passa, a engine cria uma única cópia de segurança, aplica as ações e

code/plugins/premiere-pro/skills/editar-por-voz/criterios/11-gancho.md

@@ -0,0 +1,56 @@
+# 11 — Gancho duplicado
+
+> **Escopo:** Copiar uma fala do meio do vídeo para a abertura.
+> **Quando:** pedidos de gancho ou abertura forte com repetição intencional.
+
+## Semântica atual
+
+`hook` cria uma cópia: a fala permanece no corpo do vídeo e sua cópia passa a
+abrir a sequência. Use somente:
+
+```json
+{
+  "kind": "hook",
+  "start": 141.2,
+  "end": 147.8,
+  "params": {"target": 0, "keep_original": true},
+  "reason": "frase completa escolhida como gancho de abertura"
+}
+```
+
+## Escolha editorial
+
+O gancho deve funcionar sem a frase anterior. Prefira uma promessa, contraste,
+resultado, pergunta ou afirmação específica que desperte curiosidade e continue
+verdadeira fora da posição original. Evite pronomes sem referente, continuações
+como “por isso” ou “então” e conclusões que dependam de explicação anterior.
+
+Selecione a menor unidade que preserve o sentido completo. Una segmentos do
+Whisper quando a gramática continuar entre eles. A primeira palavra precisa
+iniciar a frase, a última precisa fechá-la e cada extremidade precisa conservar
+ao menos 0,30s de respiro.
+
+## Limites da execução segura
+
+A versão atual aceita um único `hook`, destinado a `0s`, dentro de um único
+clipe de vídeo em velocidade normal e seu áudio correspondente. Ela recusa
+faixas adicionais ocupadas, par A/V ambíguo, mídia retimada ou invertida e
+qualquer outra ação que sobreponha o trecho do gancho.
+
+A operação cria a cópia a partir do mesmo intervalo da mídia de origem; o
+original conserva seus efeitos, mas a cópia nasce sem efeitos específicos do
+clipe. Por isso o gancho deve rodar antes de zooms e outros efeitos do plano.
+Ela só prossegue quando o backup da sequência foi confirmado pelo Premiere.
+
+## Preview
+
+Antes da aprovação, mostre:
+
+- a frase completa escolhida;
+- o intervalo original e as margens de cada borda;
+- a nova abertura seguida da primeira frase do conteúdo anterior;
+- a confirmação de que a ocorrência original será preservada;
+- o aumento esperado da duração total pelo tamanho do gancho.
+
+O plano está pronto somente quando a nova emenda preserva sentido, ritmo e
+respiração.

code/src/tools/timeline.ts

@@ -194,6 +194,176 @@ export function getTimelineTools(bridgeOptions: BridgeOptions) {
       },
     },
 
+    duplicate_linked_range_to_start: {
+      description:
+        "Duplicate one isolated, normal-speed linked video/audio range at sequence start with a verified ripple insert while preserving the original occurrence.",
+      parameters: {
+        type: "object" as const,
+        properties: {
+          node_ids: {
+            type: "array",
+            items: { type: "string" },
+            minItems: 2,
+            maxItems: 2,
+            description: "IDs of the isolated video and audio clips that form the range.",
+          },
+        },
+        required: ["node_ids"],
+      },
+      handler: async (args: { node_ids: string[] }) => {
+        if (!Array.isArray(args.node_ids) || args.node_ids.length !== 2 || args.node_ids.some((id) => typeof id !== "string" || !id)) {
+          return { success: false, error: "node_ids must contain exactly two non-empty clip IDs." };
+        }
+        const ids = args.node_ids.map(escapeForExtendScript);
+        const script = buildToolScript(`
+          var first = __findClip("${ids[0]}");
+          var second = __findClip("${ids[1]}");
+          if (!first || !second) return __error("One of the requested clips was not found; nothing was duplicated.");
+          if (first.trackType === second.trackType) return __error("The range must contain one video clip and one audio clip.");
+
+          var video = first.trackType === "video" ? first : second;
+          var audio = first.trackType === "audio" ? first : second;
+          var seq = app.project.activeSequence;
+          if (!seq) return __error("No active sequence; nothing was duplicated.");
+          var frameTicks = parseFloat(seq.timebase);
+          if (!frameTicks || isNaN(frameTicks)) frameTicks = TICKS_PER_SECOND / 24;
+          var beforeEndTicks = parseFloat(seq.end.ticks);
+          var videoStart = parseFloat(video.clip.start.ticks);
+          var audioStart = parseFloat(audio.clip.start.ticks);
+          var videoEnd = parseFloat(video.clip.end.ticks);
+          var audioEnd = parseFloat(audio.clip.end.ticks);
+          if (Math.abs(videoStart - audioStart) > frameTicks || Math.abs(videoEnd - audioEnd) > frameTicks) {
+            return __error("The video and audio clips do not occupy the same range; nothing was duplicated.");
+          }
+          if (videoStart <= frameTicks) return __error("The requested range is already at sequence start; nothing was duplicated.");
+          if (!video.clip.projectItem || !audio.clip.projectItem || video.clip.projectItem.nodeId !== audio.clip.projectItem.nodeId) {
+            return __error("The video and audio clips do not share one source project item; nothing was duplicated.");
+          }
+          var videoSpeed = 100;
+          var audioSpeed = 100;
+          var videoReversed = false;
+          var audioReversed = false;
+          try { videoSpeed = Number(video.clip.getSpeed()); } catch (e) {}
+          try { audioSpeed = Number(audio.clip.getSpeed()); } catch (e) {}
+          try { videoReversed = video.clip.isSpeedReversed() == 1; } catch (e) {}
+          try { audioReversed = audio.clip.isSpeedReversed() == 1; } catch (e) {}
+          if (Math.abs(videoSpeed - 100) > 0.001 || Math.abs(audioSpeed - 100) > 0.001 || videoReversed || audioReversed) {
+            return __error("Retimed or reversed clips cannot be duplicated by this guarded operation.");
+          }
+
+          var g;
+          var t;
+          var groups = [seq.videoTracks, seq.audioTracks];
+          for (g = 0; g < groups.length; g++) {
+            for (t = 0; t < groups[g].numTracks; t++) {
+              var isTarget = (g === 0 && t === video.trackIndex) || (g === 1 && t === audio.trackIndex);
+              if (!isTarget && groups[g][t].clips.numItems > 0) {
+                return __error("The guarded hook only supports a simple sequence with content on one video and one audio track.");
+              }
+            }
+          }
+          if (seq.videoTracks[video.trackIndex].clips.numItems < 1 || seq.audioTracks[audio.trackIndex].clips.numItems < 1) {
+            return __error("The target tracks are empty; nothing was duplicated.");
+          }
+          if ((seq.videoTracks[video.trackIndex].isLocked && seq.videoTracks[video.trackIndex].isLocked()) ||
+              (seq.audioTracks[audio.trackIndex].isLocked && seq.audioTracks[audio.trackIndex].isLocked())) {
+            return __error("A target track is locked; nothing was duplicated.");
+          }
+          if (parseFloat(seq.videoTracks[video.trackIndex].clips[0].start.ticks) > frameTicks ||
+              parseFloat(seq.audioTracks[audio.trackIndex].clips[0].start.ticks) > frameTicks) {
+            return __error("The guarded hook requires both target tracks to begin at sequence time zero.");
+          }
+
+          var item = video.clip.projectItem;
+          var sourceInTicks = parseFloat(video.clip.inPoint.ticks);
+          var sourceOutTicks = parseFloat(video.clip.outPoint.ticks);
+          if (Math.abs(sourceInTicks - parseFloat(audio.clip.inPoint.ticks)) > frameTicks ||
+              Math.abs(sourceOutTicks - parseFloat(audio.clip.outPoint.ticks)) > frameTicks) {
+            return __error("The linked clips do not share matching source in/out points; nothing was duplicated.");
+          }
+          var durationTicks = videoEnd - videoStart;
+          if (durationTicks <= frameTicks) return __error("The requested range is too short to duplicate safely.");
+
+          var oldIn = item.getInPoint(4);
+          var oldOut = item.getOutPoint(4);
+          var oldInTicks = oldIn ? oldIn.ticks : null;
+          var oldOutTicks = oldOut ? oldOut.ticks : null;
+          var insertionError = null;
+          try {
+            item.setInPoint(String(sourceInTicks), 4);
+            item.setOutPoint(String(sourceOutTicks), 4);
+            seq.insertClip(item, "0", video.trackIndex, audio.trackIndex);
+          } catch (insertError) {
+            insertionError = insertError.toString();
+          } finally {
+            try {
+              if (oldInTicks !== null) item.setInPoint(String(oldInTicks), 4); else item.clearInPoint();
+              if (oldOutTicks !== null) item.setOutPoint(String(oldOutTicks), 4); else item.clearOutPoint();
+            } catch (restoreError) {
+              return __error("The source range could not be restored after insertion: " + restoreError.toString());
+            }
+          }
+          if (insertionError !== null) return __error("Premiere could not insert the range at sequence start: " + insertionError);
+
+          var insertedVideo = null;
+          var insertedAudio = null;
+          var vc;
+          var ac;
+          for (vc = 0; vc < seq.videoTracks[video.trackIndex].clips.numItems; vc++) {
+            var candidateVideo = seq.videoTracks[video.trackIndex].clips[vc];
+            if (candidateVideo.nodeId !== "${ids[0]}" && candidateVideo.nodeId !== "${ids[1]}" &&
+                candidateVideo.projectItem && candidateVideo.projectItem.nodeId === item.nodeId &&
+                Math.abs(parseFloat(candidateVideo.start.ticks)) <= frameTicks) insertedVideo = candidateVideo;
+          }
+          for (ac = 0; ac < seq.audioTracks[audio.trackIndex].clips.numItems; ac++) {
+            var candidateAudio = seq.audioTracks[audio.trackIndex].clips[ac];
+            if (candidateAudio.nodeId !== "${ids[0]}" && candidateAudio.nodeId !== "${ids[1]}" &&
+                candidateAudio.projectItem && candidateAudio.projectItem.nodeId === item.nodeId &&
+                Math.abs(parseFloat(candidateAudio.start.ticks)) <= frameTicks) insertedAudio = candidateAudio;
+          }
+          if (!insertedVideo || !insertedAudio) {
+            return __error("Premiere inserted content but the new linked range could not be verified at sequence start. Restore the automatic sequence backup.");
+          }
+          if (Math.abs((parseFloat(insertedVideo.end.ticks) - parseFloat(insertedVideo.start.ticks)) - durationTicks) > frameTicks ||
+              Math.abs((parseFloat(insertedAudio.end.ticks) - parseFloat(insertedAudio.start.ticks)) - durationTicks) > frameTicks) {
+            return __error("The inserted range has an unexpected duration. Restore the automatic sequence backup.");
+          }
+          var insertedVideoId = String(insertedVideo.nodeId);
+          var insertedAudioId = String(insertedAudio.nodeId);
+
+          var preservedFirst = __findClip("${ids[0]}");
+          var preservedSecond = __findClip("${ids[1]}");
+          if (!preservedFirst || !preservedSecond ||
+              Math.abs(parseFloat(preservedFirst.clip.start.ticks) - (videoStart + durationTicks)) > frameTicks ||
+              Math.abs(parseFloat(preservedSecond.clip.start.ticks) - (audioStart + durationTicks)) > frameTicks) {
+            return __error("The original range was not preserved after the ripple insert. Restore the automatic sequence backup.");
+          }
+
+          var hookVideo = __findClip(insertedVideoId);
+          var hookAudio = __findClip(insertedAudioId);
+          if (!hookVideo || !hookAudio ||
+              Math.abs(parseFloat(hookVideo.clip.start.ticks)) > frameTicks ||
+              Math.abs(parseFloat(hookAudio.clip.start.ticks)) > frameTicks) {
+            return __error("The duplicated hook was not preserved at sequence start. Restore the automatic sequence backup.");
+          }
+          var afterEndTicks = parseFloat(seq.end.ticks);
+          if (Math.abs(afterEndTicks - (beforeEndTicks + durationTicks)) > frameTicks * 2) {
+            return __error("The sequence duration did not grow by the hook duration. Restore the automatic sequence backup.");
+          }
+          return __result({
+            duplicated: true,
+            verified: true,
+            targetSeconds: 0,
+            durationSeconds: __ticksToSeconds(durationTicks),
+            insertedNodeIds: [String(hookVideo.clip.nodeId), String(hookAudio.clip.nodeId)],
+            originalNodeIdsPreserved: ["${ids[0]}", "${ids[1]}"],
+            clipEffectsPreserved: false
+          });
+        `);
+        return sendCommand(script, bridgeOptions);
+      },
+    },
+
     move_clip: {
       description: "Move a clip to a new position on the timeline",
       parameters: {

code/tests/tools/tool-modules.test.ts

@@ -198,12 +198,12 @@ describe("Tool Module Structure", () => {
 });
 
 describe("Total Tool Count", () => {
-  it("all modules together have 342 tools", () => {
+  it("all modules together have 344 tools", () => {
     let total = 0;
     for (const mod of ALL_MODULES) {
       total += Object.keys(mod.getter(bridgeOptions)).length;
     }
-    expect(total).toBe(343);
+    expect(total).toBe(344);
   });
 
   it("there are 40 directly enumerated modules", () => {
@@ -527,6 +527,32 @@ describe("Tool Handler Behavior", () => {
       expect(script).not.toContain("setDisabled(");
     });
 
+    it("duplicates a linked range at sequence start and preserves the original", async () => {
+      const tools = getTimelineTools(bridgeOptions);
+      await (tools.duplicate_linked_range_to_start.handler as any)({ node_ids: ["video-1", "audio-1"] });
+
+      const script = mockedSendCommand.mock.calls[0][0];
+      expect(script).toContain('first.trackType === second.trackType');
+      expect(script).toContain('video.clip.projectItem.nodeId !== audio.clip.projectItem.nodeId');
+      expect(script).toContain('Retimed or reversed clips cannot be duplicated');
+      expect(script).toContain('groups[g][t].clips.numItems > 0');
+      expect(script).toContain('seq.insertClip(item, "0", video.trackIndex, audio.trackIndex)');
+      expect(script).toContain('item.setInPoint(String(sourceInTicks), 4)');
+      expect(script).toContain('item.setOutPoint(String(sourceOutTicks), 4)');
+      expect(script).toContain('var preservedFirst = __findClip("video-1")');
+      expect(script).toContain('videoStart + durationTicks');
+      expect(script).toContain('beforeEndTicks + durationTicks');
+      expect(script).not.toContain('originalVideo.clip.remove');
+      expect(script).toContain('clipEffectsPreserved: false');
+    });
+
+    it("rejects an invalid linked-range move before contacting Premiere", async () => {
+      const tools = getTimelineTools(bridgeOptions);
+      await expect((tools.duplicate_linked_range_to_start.handler as any)({ node_ids: ["video-only"] }))
+        .resolves.toMatchObject({ success: false, error: expect.stringContaining("exactly two") });
+      expect(mockedSendCommand).not.toHaveBeenCalled();
+    });
+
     it("does not claim legacy source-monitor or stop-playback requests are verified", async () => {
       const tools = getPlaybackTools(bridgeOptions);
       await (tools.stop_playback.handler as any)({});