Files
CenaForge/.claude/skills/cenaforge/references/gotchas.md
T
MateuusandClaude Opus 5.5 b11090ffa3 Skill cenaforge 1.54.0: Clipador (revisão × final, dublagem, falantes, expressões, Equipe de IA)
Dois arquivos novos em references/ (clipper-video.md, clipper-ai-team.md), banco em v17,
seção de expressões, gotchas 180–185 e ponteiros em panel/publishing/ai/tools.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-18 04:53:34 -03:00

877 lines
85 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Armadilhas conhecidas
Cada item: **sintoma → causa → correção → onde está tratado**. Observadas na implementação da
prova de conceito com Godot 4.7.2 / FFmpeg 7.1.1 / pnpm 11.22 (16/11/2026). Registro formal em
`doc/TEST_RESULT.md`: itens 1–5, 7, 13–15, 17 e 18; itens 30–33 estão em `voice/README.md`
("GPU e CPU"); itens 57–61 estão em `clipper/README.md` ("Armadilhas já resolvidas"); itens 74–76, 87–90 e 103–108 também estão lá e o 78 na seção "Limitações" do editor; itens 79, 81–84 e 92–95 estão em `doc/FACE_BAKEOFF.md` (o 93 também em "Variáveis" de `clipper/README.md`) (o 80, no comentário de `clipper/requirements.txt`); itens 168–172 (IA) seguem `doc/ia.md`; itens 118–128 (publicação) seguem `doc/publicacao/` e o código; itens 151–154 foram informados em 17/11/2026 (parte conferida no código); itens 129–132 foram informados em 17/11/2026 e conferidos no código (`doc_main.gd`, `doc/godot/cenas.md`) e no banco (`agent_runs` 5, 7 e 8); itens 62–67, 77, 85–86, 91, 99–102, 109–112 e as ampliações do 52, do 44, 77, 86 e 87 foram informados em 16–17/11/2026 (não estão em `doc/TEST_RESULT.md`); os demais vieram de erros de compilação ou instalação durante a implementação.
Ao descobrir uma nova, registre aqui via `cenaforge-skill-updater`. Os números são estáveis
(outros textos os citam): item novo entra na seção do assunto com o próximo número livre.
## Render (Godot Movie Maker)
1. **Primeiro quadro diferente** (azulado, sombra diagonal errada).
Causa: sombras e radiância do céu ainda não prontas no 1º quadro.
Correção: 3 quadros de aquecimento em t = 0, descartados com `-start_number 3`.
Onde: `--warmup-frames` em `main.gd`; `render.ts` passa `-start_number`.
2. **`delta` não é 1/fps** mesmo com `--fixed-fps` (0,025; 0,0333; 0,0417…).
Correção: tempo da cena = contador de quadros / fps. Nunca use `delta` em render.
Onde: `_process_render` em `main.gd`.
3. **Resolução do filme travada na inicialização.** `--resolution` e `content_scale_size` em
runtime não mudam o arquivo; janela de 1080×1920 não cabe numa tela de 1080 px.
Correção: `godot/override.cfg` temporário com o viewport do perfil e janela menor
(stretch `viewport`, aspect `keep`). A cena aborta (código 3) se o viewport ≠ config.
Onde: `render.ts` escreve/remove o arquivo; checagem em `main.gd`.
Consequência: render manual sem o lançador só sai em 540×960.
4. **`--write-movie` relativo grava em `godot/`, e falha em silêncio.** Com a pasta
inexistente, nenhum PNG é gravado e a Godot sai com código 0 dizendo "Done recording".
Correção: caminho absoluto; o lançador confere os PNGs; `main.gd` aborta se a pasta não existe.
Lição: log de sucesso não prova nada — confira arquivos.
5. **Quantidade de quadros.** Chamar `quit()` no `_process` do último quadro ainda grava esse
quadro: total de PNGs = aquecimento + fps × duração, índices contínuos a partir de 0,
padrão `frame%08d.png`, mais `frame.wav` (silencioso, descartado).
6. **Modo `--headless` não renderiza 3D válido.** Use só para validação, testes e preparação
de assets. O render abre uma janela e precisa de backend gráfico.
7. **Custo do render é a codificação PNG** (~105 ms/quadro em 540×960, ~404 ms em 1080×1920),
não a GPU. Não prometa tempo sem medir.
110. **Cena do documentário (`doc2d`/`doc3d`) reprovada como "quadro preto" ou "moto não termina no ponto".** Causa: as
checagens do lançador eram da rua — o fundo escuro do documentário (#0d0d10) tem luma ≈ 13, abaixo do piso 20
(`MIN_AVERAGE_LUMA`), e não há moto. Correção: com `kind` `doc2d` ou `doc3d`, `render.ts` pula a checagem da moto e usa
`MIN_AVERAGE_LUMA_DOC2D` = 4. Fundo novo mais escuro que isso → ajuste o piso, não desligue a checagem.
129. **Render de cena `doc3d` não termina e enche a pasta de PNGs** (17/11/2026: 39 mil quadros, "apply em Nil" em laço).
Causa: `template.gd` com erro de compilação; o protocolo seguia sem a cena. Correção: `doc_main.gd` carrega o script
na validação e, se `can_instantiate()` falha, sai com `SCENE_SCRIPT_INVALID` (código 2, `EXIT_INVALID_CONFIG`); os
`Parse Error` com a linha ficam no `render.log` do run. No render, cena sem `setup`/`apply` também sai com
`SCENE_SCRIPT_INVALID`. Se um render antigo travar assim: encerre a Godot **e** o lançador e apague
`output/.render.lock`. Erros de GDScript mais comuns: itens 9 e 130.
## GDScript (Godot 4.7) e TypeScript do lançador
8. **`class_name` depende do cache do editor.** O projeto roda sem importação prévia; use
`const X := preload(...)`.
9. **`var x := dicionario.campo + 1.0`** não compila (tipo não inferível a partir de Variant). Idem
`var x := dict.get("k")`, `var p := nodes[i]` e retorno de método de kit chamado por variável tipada como `Node3D`.
Declare o tipo (`var x: float = ...`) ou use `=`.
10. **Comparar valor não-objeto com `null`**: prefira `typeof(v) == TYPE_NIL`.
11. **`quit()` é adiado para o fim do quadro**: depois de chamar, marque um sinalizador
(`_halted`) para o `_process` seguinte não rodar com estado incompleto.
12. **Dentro de comentário de bloco TypeScript, `*/`** (ex.: `godot-*/`) encerra o comentário.
130. **"shadows a native class"**: constante com nome de classe do Godot (`const Sky := preload(...)`, `Camera3D`,
`Environment`) não compila. Use outro nome (`SkyRig` em `godot/library/castaways/template.gd`). Guia: "Testar" em
`doc/godot/cenas.md`.
## Composição visual
13. Título longo quebra linha: o rótulo cresce para cima (alinhado embaixo) para não invadir as
opções. Reserve ~18% inferior livre para a interface da plataforma.
14. No fim do plano, câmera baixa (~1,1 m) com leve inclinação para baixo põe o entregador na
metade superior e mantém o horizonte; câmera alta deixa o texto cobrindo o personagem.
15. Borda do plano do morro vira linha reta no céu: a cumeeira de volumes irregulares resolve.
16. Câmera lateral perto dos postes (x = meia pista + 0,5 m): mantenha ≥ 1 m de folga no offset.
17. Rodas: a ~4 m/s giram ~26°/quadro; acima de 30°/quadro a simetria de 60° dos raios pode
causar efeito estroboscópico.
111. **Espuma do mar desenhada por elipse não acompanha a costa** (anel regular em volta de uma ilha irregular).
Causa: a elipse no shader do mar ignora o contorno real do terreno. Correção: removida; a cor turquesa perto da
costa já marca a transição. Espuma futura precisa seguir a altura do terreno, não uma forma fixa. Onde:
`_build_ocean` em `godot/library/island/template.gd`.
## Ferramentas
18. **`pnpm doctor`** é comando nativo do pnpm 11 → use `pnpm run doctor`.
19. **pnpm 11 bloqueia scripts de instalação** não aprovados (erro `ERR_PNPM_IGNORED_BUILDS`).
O `esbuild` está recusado em `pnpm-workspace.yaml` (`allowBuilds: esbuild: false`) e funciona assim.
20. **pnpm repassa o `--`** para o script; o parser do lançador ignora um `--` solto.
21. Executável principal da Godot (não o `_console.exe`) escreve stdout em pipe normalmente;
use-o para poder encerrar a árvore com `taskkill /T`.
44. **Heredoc ou `node -e "..."` no Bash do agente quebra com barra invertida e aspas** (`\\` vira `\`; escapes como
`\b` de regex se perdem; às vezes o script inteiro falha). Em 17/11/2026 um `node -e` com regex quebrou o build do
painel duas vezes. Texto com barra invertida (caminhos Windows, `package.json`, regex) ou
script com aspas aninhadas: edite com Edit/Write, ou grave o script num arquivo (scratchpad) com
Write e execute o arquivo, nunca inline.
## Painel
22. **Portas:** o CenaForge usa a faixa **4500–4599** (painel = 4500). A 3100 já é de outro
aplicativo nesta máquina. `EADDRINUSE` = porta ocupada: escolha outra da faixa, nunca
encerre o processo alheio.
23. **Node não executa `.cmd`/`.bat` sem shell** (ex.: `pnpm.cmd`). O painel chama o lançador
como `node node_modules/tsx/dist/cli.mjs scripts/cli.ts render …` e procura só `.exe`.
24. **Next.js 16.4** vem com `cacheComponents` ligado; o painel desliga (dados sempre dinâmicos)
e chama `connection()` antes de ler o SQLite. `params` de página/rota é `Promise`.
25. **Script `.ts` dentro de `panel/`** roda como CommonJS (sem `"type": "module"`): para
`await` no topo, use `.mts`.
26. **`claude -p` reclama de stdin** se a entrada não for fechada: o painel usa `stdio: ["ignore", …]`.
27. **Codex fora de repositório Git** recusa rodar sem `--skip-git-repo-check`. `codex exec resume`
não aceita `--sandbox` nem `-C`: use `-c sandbox_mode="workspace-write"` e o cwd do processo.
28. **Shims do npm no Windows** (`codex`, `codex.cmd`, `codex.ps1`): o sem extensão é script de
shell e o `.cmd` exige shell. O painel (`agents.ts`) e o juiz do Clipador (`clipper/app/judge.py`)
executam `node <pacote>/bin/codex.js`.
29. **Ruído das CLIs no stderr.** Codex: configuração pessoal do usuário (`~/.codex/config.toml`,
servidor MCP fora do ar) e "Codex is ignoring N unrecognized configuration setting"; Claude Code:
`[claude-code:unrecognized_model]` para id fora da lista interna dele (ex.: `claude-fable-5-2`), mas
o modelo roda normalmente. O painel filtra esses padrões (`STDERR_NOISE` em `panel/src/lib/agents.ts`);
os avisos de configuração do Codex chegam como item `error`, exibidos como nota.
42. **Ícone some no menu recolhido:** SVG dentro de flex encolhe a 0 px ao lado de texto
`nowrap`. Correção: `shrink-0` nos ícones (`panel/src/components/icons.tsx`).
43. **Grade na barra lateral cresce até a largura do texto.** Correção: `flex-col` + `min-w-0`
(`panel/src/components/sidebar-nav.tsx`).
48. **Nó do `@xyflow/react` 13 não responde a clique** sem `onNodeClick` no canvas.
Correção: o clique sobe até o nó e é tratado no `onNodeClick` (`components/story-flow.tsx`).
49. **Foco dentro do canvas rola o contêiner** e desalinha a árvore. Correção: `onScrollCapture`
desfaz a rolagem e `setCenter` traz o nó focado para a vista (`story-flow.tsx`).
50. **Grade sem `grid-cols-1` estoura no celular** (colunas implícitas crescem até o conteúdo).
Correção: declarar `grid-cols-1` na base e as colunas extras só nos breakpoints.
51. **Mudança de esquema não aparece no painel em dev** (ex.: v4 → criar história documental falha no
CHECK de `stories.kind`). Causa: a conexão do SQLite fica em `globalThis.__cenaforgeDb`
(`panel/src/lib/db.ts`) e a migração só rodava ao abrir o banco. Hoje a marca `checkedThisModule` faz a 1ª
chamada de `db()` depois da recarga do código migrar o banco aberto (item 138); se o `db.ts` não foi recarregado,
faça uma requisição ao painel ou peça ao usuário que reinicie o `pnpm panel` (é dele: não reinicie você). Conferir:
`PRAGMA user_version` do `data/cenaforge.db` = `MIGRATIONS.length`.
52. **`tsx` com `await` no topo** exige arquivo `.mts`, e o import de módulo local precisa de URL
`file:///` (caminho Windows cru com `C:\` ou `f:/` não é URL e falha no loader ESM). Node puro não resolve
import `.ts` sem extensão: rode pelo tsx da raiz, `node node_modules/tsx/dist/cli.mjs <script>.mts`, com
imports `file:///<raiz-do-repo>/panel/src/lib/<módulo>.ts`. Complementa o item 25.
62. **Classe de largura não pega em `Select`/`Input`** do `panel/src/components/ui.tsx`.
Causa: a classe base tem `w-full` fixo e `cx()` só concatena (não faz merge de Tailwind como o
`tailwind-merge`); `w-48` passado junto perde para o `w-full`. Correção: controlar a largura com
um `<div>` em volta (ex.: barra de filtros de `voice-cards.tsx`).
63. **Patch por string falha nos `.tsx` do painel**: os arquivos são CRLF. Correção: normalizar o
fim de linha antes de procurar o trecho (ou usar a ferramenta Edit) e gravar de volta em CRLF.
96. **Codex aplica as restrições de ficção a um pedido documental.** Causa: o Codex lia
`.claude/agents/cenaforge-story-writer.md` como instrução, mas é um subagente do Claude. Correção: as
regras saíram do subagente para `doc/roteiro/` (`comum.md` + `ficcao.md`/`documental.md`); o prompt
(`writingRules(provider, kind)` em `panel/src/lib/prompts.ts`) manda o Codex ler só o guia do formato e
escrever sozinho, e o `AGENTS.md` da raiz tem a mesma regra. Regra nova de texto vai para os .md, não
para o subagente nem para o código.
97. **Codex retomado depois de interrompido esquece o pedido original.** Medido com o Codex 0.169 (`exec` +
`taskkill /T /F` + `exec resume <thread>`): matando logo no `thread.started`, a sessão retomada não tinha o
pedido (respondeu "Nenhuma"); matando depois de um `agent_message`, lembrou (respondeu "BANANA"). O 1º
`item.completed` pode ser um item `error` de MCP pessoal, que não conta como progresso. Correção:
"Corrigir agora" (`sendFollowUp` em `panel/src/lib/agents.ts`) exige `session_id` e `progressed` (algum
evento que não seja `system`, `stderr` nem `error`); antes disso, recusa e sugere "Enviar ao terminar".
98. **Acentos quebrados no Codex** ("história" no console). Causa: o Windows PowerShell 5.1 lê arquivo UTF-8
sem BOM como ANSI. Correção: o prompt do Codex (`panel/src/lib/prompts.ts`) manda ler texto com
`Get-Content -Raw -Encoding UTF8`. Mesma raiz do item 36 (script `.ps1` precisa de BOM).
99. **Script de teste marca como `interrupted` o que o painel está rodando.** Causa: importar `lib/db.ts` (direto
ou por outro módulo do painel) abre o banco, e a abertura roda `UPDATE renders/agent_runs SET status =
'interrupted' WHERE status = 'running'`. Correção: script fora do painel não importa nada que toque o banco;
por isso o FFmpeg da montagem documental fica em `panel/src/lib/montage-ffmpeg.ts`, sem banco.
100. **Parâmetro extra some da URL de arquivo.** Causa: `fileUrl()` (`panel/src/components/ui.tsx`) já devolve
`/api/files?path=...`. Correção: anexar com `&v=...` (ex.: quebra de cache do áudio em `montage-editor.tsx`).
101. **Asterisco no vídeo documental** (`*Bothrops insularis*`). Causa: o "texto na tela" do roteiro vem com
markdown. Correção: `loadMontage` (`panel/src/lib/montage.ts`) tira `**`, `__`, `*`, `_`, crase e aspas externas.
102. **Trecho do MP4 mais longo que a tabela do roteiro** (trecho 1: roteiro 0–2 s, fala 4,08 s). Não é erro: a
montagem segue a duração real de cada fala (+ pausa), não a coluna "t (s)". Para encurtar, corte o texto falado.
112. **Primeira montagem logo depois de editar `panel/src/lib/` sai com o comportamento antigo** (17/11/2026: a 1ª saiu
sem o fundo desfocado da foto; a 2ª, certa). Causa provável (não isolada): o Next dev ainda executa o módulo antigo
logo após a edição. Correção: confira os quadros da primeira saída depois de mexer no servidor; se vier com o
comportamento antigo, gere de novo antes de concluir.
109. **Ctrl+Z do editor de cortes não desfaz slider, arraste nem setas** (só em dev). Causa: o React em modo estrito roda
o updater do `setState` duas vezes; a chave/hora de agrupamento ficava num ref alterado dentro do updater, e a 2ª
execução "agrupava consigo mesma". Correção: o updater é **puro** — chave e hora moram no próprio estado. Regra
para todo `setState((s) => …)` do painel: nada de ref, relógio ou efeito lá dentro (leia `Date.now()` antes). Onde:
`useHistory` em `panel/src/components/clip-editor-model.ts`.
131. **Agente do painel morre ao reiniciar o `pnpm panel`** (execução #5, cena do estádio, ficou `interrupted`). Causa: o
agente é processo filho do painel, e a abertura do banco marca `running` como `interrupted` (item 99). Correção: não
reinicie o painel com agente rodando; se precisar (ex.: migração, item 51), espere terminar. O painel é do usuário.
132. **Agente para no meio por limite de uso** (17/11/2026: Claude na #7, "You've hit your 5-hour limit", e Codex na #8,
"You've hit your usage limit"; as duas ficaram `error`). A mensagem aparece no console (`data/logs/agents/<id>.jsonl`);
na #7 a coluna `agent_runs.error` ficou só "success". Correção: abra nova execução no **outro provedor** com o
contexto de onde parou (arquivos já feitos, o que falta); a #8 (Codex) continuou a cena `castaways` da #7 (Claude).
133. **Claude do painel falha com "Failed to authenticate: OAuth session expired".** Causa: o painel lança o `claude` sem
`CLAUDE_CONFIG_DIR`, ou seja com `~/.claude`, e o OAuth dessa config estava expirado (17/11/2026), mesmo com outra
conta ativa no terminal. Correção: rode `claude` e `/login` nessa config, ou suba o `pnpm panel` com
`CLAUDE_CONFIG_DIR` da conta ativa (o painel é do usuário, item 131). Onde: `panel/src/lib/agents.ts`.
134. **Execução do agente custa milhões de tokens / dura dezenas de minutos.** Causas medidas: (a) Codex abrindo ~100
imagens em resolução cheia (#8: 6,83 milhões de tokens de entrada, 29 min); (b) página web inteira na pesquisa
(#6: 1,06 milhão); (c) custo fixo de plugins/MCP/skills do usuário carregados pela CLI (#7: ~49 mil por chamada);
(d) retomar conversa longa. Correção: `frame_check.py` + uma imagem por render, pesquisa curta, flags enxutas
do painel, nova execução em vez de resume. Detalhes em [token-economy.md](token-economy.md).
135. **`-c mcp_servers={}` não desliga os MCPs do Codex, e `collaboration` (`spawn_agent` etc., ~5,4 mil caracteres) não
sai por `-c features.*`.** Causa: o Codex mescla tabelas do `-c` com o `config.toml`. Correção: um
`-c mcp_servers.<nome>.enabled=false` por servidor (lidos do `config.toml`) e `plugins."<id>".enabled=false` para
computer-use. A `collaboration` fica; é parte do fixo. Onde: `codexLeanOverrides` em `panel/src/lib/agents.ts`.
## Serviço de voz (`voice/`)
Medidas em 16/11/2026, RTX 2060 SUPER 8 GB, Windows 11.
30. **Whisper na GPU só falha na 1ª inferência** com `RuntimeError: Library cublas64_12.dll is
not found`: o `ctranslate2` enxerga a GPU mesmo sem cuBLAS/cuDNN.
Correção: aquecimento real na subida (`FasterWhisperEngine.warmup()`, 1 s de tom **sem VAD** —
com VAD o silêncio não chega ao modelo e a falha passa) e queda para CPU `int8` com aviso no log.
Onde: `voice/app/stt.py` (`warmup`), `voice/app/main.py`; DLLs em `voice/requirements-cuda.txt`.
31. **GPU disputada por jogo** (98% de uso, 7,4/8 GB): 6,5 s de fala levaram 41–124 s na GPU
contra 2,7 s na CPU; noutra medição (99%, 7,2 GB) a legenda de 6,5 s ficou > 8 min presa na GPU.
Correção: `VOICE_DEVICE=auto` consulta o `nvidia-smi` na subida e usa CPU com < 2048 MiB livres
ou ≥ 85% de uso (log: `GPU ocupada por outro programa (99% de uso, 1593 MiB livres)`); depois
do reinício a mesma legenda pelo painel levou 2,5 s (14 palavras + `.srt`). Só vale na subida:
jogo aberto depois → reinicie o serviço ou use `VOICE_DEVICE=cpu`. Onde: `voice/app/device.py`.
32. **Edge TTS 403** (`WSServerHandshakeError` de `speech.platform.bing.com`) desde out/2026 com
`edge-tts` 7.2.8. Correção: `edge-tts==7.3.1` em `voice/requirements.txt`, sem patch.
33. **sha256 do Piper divergente:** o lock apontava para `resolve/main` e o arquivo mudou no
Hugging Face. Correção: URL fixada no commit `e9ab671f2a0e50a701b34361136ba3e6a3a9eb0c` em
`voice/models.lock.json`. Regra: todo peso novo com URL imutável (commit no HF ou release
versionado no GitHub) e sha256.
34. **LRU do cache empatava no Windows** (`time.time_ns()` anda em passos de ~1 ms).
Correção: `Store._tick()` estritamente crescente em `voice/app/store.py`.
35. **Caminho Windows em script do `package.json`:** o `cmd` não aceita `voice/.venv/...` como
executável; use barra invertida, escrita `\\` no JSON (ver `test:voice`:
`cd voice && .venv\\Scripts\\python -m pytest`).
36. **`scripts/setup.ps1` precisa ser UTF-8 com BOM**: o PowerShell 5.1 lê sem BOM como ANSI e
estraga os acentos. Mantenha o BOM ao editar.
37. **GPU detectada como "sem GPU"** (RTX 2060 SUPER → torch `+cpu`).
Causa: `nvidia-smi ... | Select-Object -First 1` corta o pipeline, o PowerShell mata o
processo e `$LASTEXITCODE` ≠ 0.
Correção: capturar a saída inteira com `@(nvidia-smi ...)` e usar `[0]`. Onde: `scripts/setup.ps1`.
38. **`uv pip install torch==2.11.0` aceita a variante errada já instalada** (`2.11.0+cpu`
satisfaz). Correção: pedir `torch==2.11.0+cu128` (ou `+cpu`) explicitamente. Evidência: na
2ª rodada o uv trocou `- torch==2.11.0+cpu` por `+ torch==2.11.0+cu128`. Onde: `scripts/setup.ps1`.
39. **stderr do uv vira `NativeCommandError`** com `$ErrorActionPreference = "Stop"` no
PowerShell 5.1. Correção: `"Continue"` e conferir `$LASTEXITCODE` em `Run()`. Onde:
`scripts/setup.ps1`.
40. **Serviço órfão segurando a 4510** (`WinError 10048`) após reinício pelo `voice/.env`.
Causa: o `exit` do processo antigo chega depois de o novo subir; um sinalizador global
`restarting` fazia o lançador sair no `--voice-only` e largar o novo processo.
Correção: `WeakSet` dos processos substituídos + `process.on("exit", stopAll)`; checagem de
porta livre antes de subir. Onde: `scripts/dev.ts`.
41. **`.pth` que não é RVC** derruba o Applio com `KeyError: 'config'`.
Correção: vira `422 rvc_failed` com mensagem clara. Onde: `voice/app/rvc.py`, `voice/app/errors.py`.
45. **Edge TTS `NoAudioReceived` intermitente** (visto com `en-US-AndrewMultilingualNeural`, 1ª
tentativa). O serviço não repete: vira `502 engine_unavailable` (`EdgeEngine` em
`voice/app/engine.py`). Correção: repetir a requisição (a 2ª deu certo).
46. **Acentos estragados ao testar o Piper na linha de comando no Windows**
(`echo ... | python -m piper`: "até" vira lixo). Causa: stdin/stdout fora de UTF-8. Correção:
`PYTHONUTF8=1` ou `PYTHONIOENCODING=utf-8` no teste manual. O serviço não é afetado.
47. **`faster_whisper.decode_audio(caminho)` falha** com o PyAV do `voice/.venv`
(`open() got an unexpected keyword argument 'metadata_errors'`). Só em teste avulso: decodifique
com ffmpeg para PCM 16 kHz mono e passe o array numpy. O serviço não é afetado: decodifica os
bytes com o próprio `voice/app/decode.py` (`av.open` em memória).
53. **Mudança de código em `voice/app/` não entra no ar** com `pnpm dev`/`pnpm voice`.
Causa: `scripts/dev.ts` sobe o uvicorn sem `--reload`; só reinicia sozinho quando
`voice/.env` muda. Correção: reiniciar o serviço (o painel é do usuário: peça). Mudança de
catálogo (`catalog.json`, `models.lock.json`, `user-voices.json`) não precisa: é relida na
próxima consulta de vozes ou síntese.
Exceção: voz de **motor novo** (ex.: `kokoro`, `google`, `azure`, `clone` em 16/11/2026) com o serviço ainda no
código antigo → a recarga falha (`motor desconhecido`), as vozes atuais ficam e o log avisa;
só aparece depois de reiniciar (`start.bat` / `pnpm dev`). O worker de clonagem também só
reinicia sozinho quando `voice/.env` muda.
54. **`kokoro-v1.0.int8.onnx` não roda no onnxruntime 1.31.0** (`NOT_IMPLEMENTED` em
`ConvInteger(10)`). Correção: usar `kokoro/kokoro-v1.0.fp16.onnx` (é o que está no
`voice/models.lock.json`).
55. **Kokoro fp16 inunda o log com centenas de avisos "constant folding"** do onnxruntime ao criar
a sessão. Correção: `SessionOptions.log_severity_level = 3` (e threads limitadas) em
`KokoroEngine`, `voice/app/engine.py`. Não é erro; ignore se aparecer em teste avulso.
56. **Recarga do catálogo lenta com muitas vozes Kokoro** (todas apontam para o mesmo onnx de
~160 MB e o sha256 era recalculado por voz). Correção: cache de `sha256_file` por
(caminho, mtime, tamanho) em `voice/app/catalog.py` — 62 vozes: 0,3 s → 0,01 s (informado).
64. **Download dos pesos do Chatterbox trava** (~3,3 GB de `ResembleAI/chatterbox` para
`data/voice/models/clone-hf/`): o protocolo Xet do Hugging Face baixou 256 MB em 9 min.
Correção: `HF_HUB_DISABLE_XET=1` (com ele baixou tudo); o worker já define isso e
`HF_HUB_DISABLE_SYMLINKS_WARNING=1`. Onde: `voice/clone/worker.py`. Atenção: a revisão é `main`,
**não fixada em commit** nem conferida por sha256 (foge da regra do `models.lock.json`).
65. **Chatterbox não cabe no `voice/.venv`**: fixa `numpy<2`, torch 2.6 e transformers 5.2.0.
Correção: venv próprio `voice/.venv-clone` (Python 3.12, torch/torchaudio 2.6.0+cu124) e worker
HTTP separado na 4511, chamado pelo `CloneEngine`. Nunca instale `chatterbox-tts` no
`voice/.venv`. Onde: `scripts/setup.ps1` (`-Clone`), `voice/clone/requirements.txt`.
66. **Fala clonada longa estoura o tempo**: ~1,5 s de processamento por s de áudio na GPU (RTX 2060
SUPER) pode passar de `VOICE_SYNTH_TIMEOUT_S=90`. Correção: sintetizar textos longos em partes
(o worker já divide em trechos ≤ 280 caracteres, mas o tempo total da requisição conta). A 1ª
fala inclui o condicionamento da referência (6,0 s de áudio em 20,5 s; a 2ª, 7,1 s em 10,5 s).
67. **`speed` não muda a voz clonada** e todo áudio sai com marca d'água inaudível PerTh. Não é
defeito: o Chatterbox não tem controle de velocidade. Para outro ritmo, use outro motor.
## Clipador (`clipper/`)
Itens 57–61 observados em 16/11/2026 na live real (`twitch.tv/alanzoka`) e nos testes. Contexto em
[clipper.md](clipper.md).
57. **Legenda some ou sai deslocada no corte.** Causa: com `-ss` depois do `-i`, o filtro `ass` vê
o tempo do bloco, não o do corte. Correção: `-ss` **antes** do `-i`. Onde: `clipper/app/editor_render.py`
(render atual) e `clipper/app/media.py` (caminho antigo).
58. **Tag ASS inválida na legenda palavra a palavra.** Causa: `.upper()` na linha ASS inteira transformava a
tag `\c` em `\C`, que é inválida. Correção: maiúsculas só no texto da palavra. Onde:
`clipper/app/subtitles.py` (`build_ass`).
59. **Falsos positivos com o chat calmo.** Causa: o emote `clip5k1hmm` casava com `\bclip`, e 3
mensagens já davam razão 2,35. Além disso, o começo da gravação não tinha base de comparação.
Correção: "clip" só como palavra inteira, mínimo de mensagens nos 8 s do pico (hoje proporcional,
item 68) e 60 s de aquecimento. Onde: `clipper/app/scoring.py` (`Params`, `warmup_s`); há teste
de regressão em `clipper/tests/test_scoring.py`.
60. **Ao vivo, a explosão do chat era cortada cedo.** Causa: um pico menor do começo da explosão
fechava antes do pico maior, que ainda estava crescendo. Correção: o pico é escolhido olhando a
série inteira e só depois é filtrado pelo "assentado" (`limit_s`). Onde: `pick_peaks` em
`clipper/app/scoring.py`.
61. **Chat e vídeo desalinhados na Twitch.** Causa: o Streamlink pausa durante o anúncio filtrado.
Correção: o tempo da mensagem é convertido pela hora real em que cada bloco chegou (`wall_end`
da tabela `segments`), não pelo relógio desde o início. Onde: `clipper/app/worker.py`.
Observadas em 17/11/2026 (fase 2) numa cópia do banco da live do skipnho e nos testes:
68. **Live de chat pequeno nunca gerava corte.** Causa: com ~0,15 msg/s, o mínimo fixo de 12 mensagens
nos 8 s do pico era inalcançável. Correção: mínimo = 3× a mediana recente, entre 4 e 12, exigindo
≥ 2 reações (texto ou emote); com chat < 0,5 msg/s o áudio também propõe momentos; e a varredura da
IA cobre o resto. Onde: `_required_messages`, `_chat_moments`, `_audio_moments` em
`clipper/app/scoring.py`; varredura em `clipper/app/intel.py`.
69. **Título preso à frase solta da transcrição** ("Jogando três jogos ao mesmo tempo" num momento de
lag). Causa: um único juiz só com texto. Correção: ANALISTA com 6 frames (8 se o trecho passa de 80 s) + glossário de gírias do
chat (`CHAT_GLOSSARY`: "server chinês" = lag) e EDITOR que escreve a partir da análise. Onde:
`clipper/app/judge.py`; frames montados em `clipper/app/worker.py`.
70. **Crédito em cima do rosto no `cam_top`.** Causa: crédito no topo fica sobre a webcam. Correção:
no `cam_top` o crédito do topo desce para o pé do painel da câmera (`cam_panel_height`). Onde:
`clipper/app/subtitles.py`.
71. **Cor errada na legenda ASS.** Causa: formatos diferentes — a linha `Style` usa `&H00BBGGRR&` (com
alfa) e a tag `\c` inline usa `&HBBGGRR&` (sem alfa); ambos em BGR, não RGB. Correção: sempre
converter por `ass_color` (Style) ou `ass_inline_color` (tag). Onde: `clipper/app/layout.py`.
72. **Chat travando ao baixar emotes.** Causa: APIs de 7TV/BTTV/FFZ podem demorar (FFZ) ou dar 404
(7TV em canal sem 7TV). Correção: a thread do chat só lê `EmoteCatalog.cached()`; o download
(`names()`, cache de 1 h, fonte com falha ignorada) roda em thread à parte ao chegar o `room-id`.
Onde: `ingest_chat` em `clipper/app/intel.py`, `clipper/app/emotes.py`.
73. **Código novo do Clipador "não funciona" no painel.** Causa: o uvicorn sobe sem `--reload`; a UI
nova (o Next em dev recarrega sozinho) chama rotas ou manda campos que o serviço antigo não conhece — ex.: um
serviço anterior ao `cam_only` recusa o projeto do editor que usa esse modo (`validate_project` → 400).
Correção: reiniciar o Clipador (`start.bat` / `pnpm dev`, que é do usuário — peça a ele; ele pode estar
gravando). Mesmo padrão do item 53.
Observadas em 16/11/2026 no editor de cortes, numa cópia do banco (sessão 3 do skipnho) e nos testes:
74. **Projeto do editor recusado com 400.** Causa: o Whisper devolve palavra com duração zero (ex.: "queria"
1020,10–1020,10). Correção: palavra com fim ≤ início ganha 50 ms. Onde: `clipper/app/editor.py`
(leitura das palavras e `validate_project`).
75. **Capa sai vazia.** Causa: o mjpeg do FFmpeg 7.1 recusa yuv420p marcado como faixa "tv" (blocos do libx264).
Correção: o quadro intermediário da capa é PNG. Em teste, bloco sintético precisa de `-g` curto; senão o `-ss`
não acha quadro e o grab sai vazio. Onde: capa em `clipper/app/editor_render.py`; `clipper/tests/test_editor.py`.
76. **Gancho vira frase longa cortada ou mostra o tempo da gravação** ("Aos 5085s, ele solta que…", corte 25 do
skipnho). Causa: o `hook` do analista às vezes é uma frase descritiva. Correção: só vale com ≤ 8 palavras, ≤ 48
caracteres e sem tempo da gravação; senão usa o título do editor. A menção ao tempo é sempre removida e o texto
nunca para no meio de palavra (≤ 60 caracteres). Onde: `pick_hook` em `clipper/app/editor.py` (usado por
`auto_project` e `default_project`).
77. **Instância de teste do Clipador apaga a gravação real.** Causa: a cópia do banco aponta para os mesmos `.ts`;
o prune por `CLIPPER_KEEP_HOURS` e o monitor/varredura da cópia agiriam sobre os arquivos e canais reais.
Correção: na instância de teste, **sempre** `keep_hours = 0` (pula o prune), canais com `monitor = 0` na cópia e
sem monitor/varredura/contexto (subclasse de `Engine` que só sobe a fila de cortes); porta na faixa 4500–4599
(ex.: 4521). Derrube a instância e apague a cópia ao terminar. Onde: `prune` em `clipper/app/worker.py`.
A cópia também **herda as sessões**: um `Engine` completo retoma as `interrupted` na subida (`keep_live`), pode
gravar uma live de verdade e chamar a CLI de IA. Ao terminar, encerre a árvore de processos inteira (uvicorn,
streamlink, ffmpeg). Há várias sessões do Claude neste projeto ao mesmo tempo: uma instância na 4521 pode ser de
outra sessão — confira antes de derrubar ou usar.
78. **Emoji sai monocromático no vídeo.** Causa: o libass do FFmpeg não desenha emoji colorido. Sem correção por
enquanto (limitação registrada no README do Clipador); não prometa emoji colorido na legenda ou no gancho.
Observadas em 16–17/11/2026 no rastreio de reação (bancada e calibração numa cópia do banco, sessão 3 do skipnho;
registro em `doc/FACE_BAKEOFF.md`):
79. **`ImportError` ao carregar o MediaPipe.** Causa: `from mediapipe.tasks import python` não existe no
`mediapipe` 1.2.3. Correção: importar os submódulos (`from mediapipe.tasks.python import vision`,
`from mediapipe.tasks.python.core.base_options import BaseOptions`), e só dentro da função (o serviço e os
testes sobem sem cv2/mediapipe). Onde: backend `mediapipe` em `clipper/app/face.py`.
80. **`cv2` quebrado ou sem `FaceDetectorYN`.** Causa: `opencv-python-headless` instalado junto do
`opencv-contrib-python` (os dois brigam pelo mesmo módulo `cv2`). Correção: só `opencv-contrib-python`, o que
vem com o MediaPipe. Onde: comentário em `clipper/requirements.txt`.
81. **Risada não aparece no sinal.** Causa: em live, `jawOpen` quase nunca passa de 0,1 e `eyeWide*` fica em ~0,
mesmo com recorte apertado. Correção: risada sai do sorriso (`mouthSmile*`), com z relativo ao neutro do próprio
streamer; não exija boca aberta. Onde: `label` e `ReactionParams` em `clipper/app/reaction.py`.
82. **Streamer partido em dois na detecção da câmera.** Causa: agrupar os rostos comparando com o 1º membro do
grupo; quando ele se inclinou (0,8 largura de rosto) virou outro grupo. Correção: agrupar pelo **centro**
(média corrente) do grupo, tolerância `cluster_faces` 1,0. Onde: `locate_cam` em `clipper/app/reaction.py`.
83. **"Sustos" falsos.** Causa: o rastreio perde o rosto por instantes e o centro "pula", virando movimento grande.
Correção: movimento só rotula (não entra na intensidade) e só vale com rosto em ≥ 80 % do segundo
(`motion_min_present`). Onde: `clipper/app/reaction.py`.
84. **Streamer de neutro sorridente não gera pico** (corte 12 aprovado sem pico). Causa: o z é relativo ao normal
dele, que já é alto. Sem correção: limitação do sinal relativo (`smile_raw` só ajuda no rótulo). Por isso o rosto
só reforça o corte (bônus ≤ 0,6) e nunca decide sozinho; não o use como juiz.
Observadas em 17/11/2026 nos testes ao vivo do rastreio (instância isolada na 4521; seção "Testes de 17/11 — ao vivo"
de `doc/FACE_BAKEOFF.md`):
92. **Live sem câmera ganha "webcam"** (twitch.tv/lofigirl). Causa: o YuNet achou um rosto de 24×34 px colado na
borda (a tela de um notebook desenhado) em 8 de 12 quadros, score 0,61–0,66, e o `locate_cam` aceitou só pela
presença estável. Webcam real dá 0,92–0,94. Correção: confiança média do grupo ≥ `ReactionParams.min_cam_score`
(0,7). Onde: `locate_cam` em `clipper/app/reaction.py`; teste em `clipper/tests/test_reaction.py`.
93. **Instância de teste com banco novo pega a transcrição de outra sessão.** Causa: o serviço de voz (4510) é
compartilhado e guarda a transcrição pela chave `clipper-<sessão>-<bloco>`; num banco novo as sessões recomeçam
do 1 e colidem com as do banco real. Correção: antes da 1ª sessão, subir o `sqlite_sequence` de `sessions` do
banco de teste (ex.: 90000), além de `CLIPPER_DATA_DIR`/`CLIPPER_OUTPUT_DIR` dentro do repo. Onde: receita em
"Variáveis" de `clipper/README.md`; pastas em `clipper/app/config.py`.
94. **Analista lê "sem reação marcante no rosto" com o plano B.** Causa: o OpenSeeFace não tem blendshapes; os canais
saem 0 e o resumo dizia que não houve reação, o que é falso. Correção: com a série da sessão no backend
`openseeface`, `FaceService.summary` devolve "" (nenhuma linha de rosto vai ao analista). Onde: `clipper/app/face.py`.
95. **WARNING "pesquisa de jogo falhou: IA desligada" a cada 30 s** com o juiz `off`. Causa: `research_pending`
tentava pesquisar o jogo mesmo com a IA desligada. Correção: sai cedo se `judge.enabled` for falso (o jogo fica
`pending`). Onde: `Intel.research_pending` em `clipper/app/intel.py`.
Observadas em 16/11/2026 no teste de UI do editor de cortes redesenhado (Chrome sem janela por CDP):
85. **Teste automático não acha texto, legenda nem chat no monitor Programa.** Causa: a prévia é um `<canvas>`; as
camadas não são elementos do DOM. Correção: mover o ponteiro sobre o canvas e ler `style.cursor` — `"move"` =
há camada arrastável ali (`hitAt` em `panel/src/components/clip-editor-preview.tsx`). Trilhas e palavras da
timeline são DOM normal.
86. **Teste de UI grava no corte real do usuário.** Causa: o editor salva sozinho 1,2 s depois de cada mudança e o
painel (4500) fala com o Clipador real (4520). Correção: interceptar toda requisição não-GET de
`*/api/clipper/*` (domínio `Fetch` do CDP) e responder sem repassar; conferir depois que nada mudou. Para
simular dados (ex.: sessão em outro estado), altere só a **resposta** do GET (`requestStage: "Response"`). Para
testar gravação de verdade, use a instância sobre cópia do banco (item 77). Ligue o `Fetch` **antes** de navegar,
senão os GET da carga da página passam sem alteração. Atalho com Ctrl (Ctrl+Z) precisa ir como evento `keyDown`.
Observadas em 16–17/11/2026 no serviço do usuário (sessão 3 do skipnho) e no painel; 87–90 também em "Armadilhas já
resolvidas" de `clipper/README.md`:
87. **Cortes presos em `rendering` sem mensagem; a capa sai e o vídeo não** (10 cortes, ids 42–58). Causa: o serviço foi
reiniciado no meio de uma edição de código e subiu com uma versão intermediária da legenda (casava a ênfase por
`id()` da palavra → `KeyError` quando o saneamento mudava palavras); a exceção escapava do render e o corte ficava
em `rendering` para sempre. Correção: qualquer exceção no render vira `error` com a mensagem; `rendering` órfão há
> 5 min volta para `pending` (3ª vez = `error`). Regra: **só reinicie o serviço com a suíte verde**; agente que
edita `clipper/app/` trabalha numa cópia e aplica no fim **por edição pontual** (trecho a trecho), nunca
sobrescrevendo o arquivo inteiro: vários agentes e outras sessões mexem em `clipper/` ao mesmo tempo e a cópia
inteira apagaria o trabalho deles. Onde: `render_clip`, `recover_orphan_renders` em `clipper/app/worker.py`.
88. **Live no ar foi para `processing` depois de reiniciar o serviço.** Causa: a retomada da subida checava uma vez só,
e timeout/erro do `streamlink --json` pareciam "offline". Correção: `Engine.live_check` separa `live`/`offline`/
`unknown` e `keep_live` tenta de novo (`RESUME_DELAYS_S` 0…120 s); a sessão fica `interrupted` enquanto tenta; a
captura que cai no meio passa pelo mesmo caminho. Onde: `clipper/app/worker.py`; teste `clipper/tests/test_resume.py`.
89. **O mesmo momento vira vários cortes** (pico 1149 s → cortes 42, 47, 49, 51, 52 em cima do 9). Causa: o juiz recua o
trecho para antes do pico (ainda mais com `backtrackS` 120), e a checagem comparava o candidato só com o trecho
final dos cortes. Correção: comparar também o pico e a janela original (`reasons.candidateStartS/EndS`), em
qualquer estado, e conferir de novo depois do juiz (`judge.duplicateOf`). Onde: `clipper/app/worker.py`
(`SAME_PEAK_S`, `SAME_MOMENT_OVERLAP`, `discard_pending_duplicates`); teste `clipper/tests/test_render_and_duplicates.py`.
90. **Legenda uma em cima da outra com fala rápida.** Causa: o fim de cada bloco (fim da última palavra, no mínimo
+0,25 s) passava do início do seguinte e o libass empilha eventos ativos ao mesmo tempo; o Whisper também devolve
palavras de 0 s e palavras que começam juntas. Correção: `clean_words` (ordem, 60 ms mínimos, 40 ms entre inícios,
sem sobreposição) e `caption_blocks` (fim do bloco cortado no início do seguinte); ênfase casada nos tempos
originais. Onde: `clipper/app/subtitles.py`; teste `clipper/tests/test_format_and_captions.py`.
91. **Texto truncado longo alarga a página `/clipper`.** Causa: cartão dentro da grade das abas cresce com o conteúdo
intrínseco mesmo com `truncate`. Correção: `[contain:inline-size]` no cartão. Onde: cartão da sessão em
`panel/src/components/clipper-sessions.tsx`.
Observadas em 17/11/2026 (duração mínima, tarja do gancho, fontes, reenquadramento, camadas e qualidade de gravação;
103–108 também em "Armadilhas já resolvidas" de `clipper/README.md`):
103. **Cortes automáticos mais curtos que o mínimo** (mínimo 60: cortes 43 = 54,6 s, 55 = 46,8 s, 61 = 43,8 s). Causa:
`auto_project` adiantava o início para o `action_start_s` do analista sem reimpor o mínimo; juiz e varredura
limitavam o fim sem recuar o início. Correção: todo corte automático passa por `scoring.fit_window` com
`layout.min_target` (`minS` + 1 s + 0,1 s de folga, ≤ `maxS`); faltando material, cresce para trás. "Cortar agora"
e a edição à mão continuam livres. Teste: `clipper/tests/test_duration_banner_fonts.py`.
104. **Texto da tarja não desfoca na entrada `slide`.** Causa: com contorno (`\bord` > 0), o `\blur` do libass desfoca
só a borda e o preenchimento fica nítido. Correção: duas camadas ASS — preenchimento com `\bord0` e `\blur18`→0, e
o contorno por baixo. Assentado, sai idêntico ao de antes (0 px de diferença aos 1500 ms, informado). Onde:
gancho/texto `banner` em `clipper/app/editor_render.py`.
105. **Fonte empacotada ignorada pelo libass** (cai numa fonte padrão, sem erro). Causa: o `fontsdir` não lê subpastas,
e a família no ASS precisa ser o nome **dentro** do arquivo ("Poppins ExtraBold", não "Poppins"). Correção:
`assets/fonts/` plana; `family` em `assets/fonts/fonts.lock.json`; no Windows, caminho absoluto entre aspas com
`:` escapado (`layout.ass_filter`). O `fontsdir` só entra quando o ASS usa fonte empacotada, para o filtro de
projetos antigos (e o SHA de referência do vertical) não mudar.
106. **Zoom variável no tempo não sai com `crop`.** Causa: o `crop` do FFmpeg avalia `w`/`h` uma vez só (posição por
quadro, tamanho fixo); `scale` com `eval=frame` + `crop` fixo falhou no encoder e arredonda a posição a pixel
inteiro. Correção: `perspective` com `eval=frame` (4 cantos por quadro, subpixel) e depois `scale`. O contador
`in` do `perspective` começa em **1** (com `in/30` a janela ia 1 quadro adiantada). Grafo > 20 000 caracteres vai
por arquivo (`-/filter_complex`). Onde: `perspective_filter` em `clipper/app/reframe.py`; `editor_render.py`.
107. **Quadro errado ao buscar dentro de um bloco `.ts`.** Causa: o demuxer mpegts trata todo pacote como ponto de
busca; `-ss` antes do `-i` cai num quadro P → em H.264 sai o próximo quadro-chave (até 2 s depois), em **HEVC**
sai quadro **cinza** (frames do juiz, capa e YuNet; a câmera não era achada). Um 2º `-ss` depois do `-i` também
erra com áudio no bloco. Correção: `media.seek_args` busca 4 s antes, `-copyts -start_at_zero` e
`select='gte(t,alvo)'` (usado por `grab_frame` e `face.grab_bgr`). Render e proxy (concat demuxer) já buscavam certo.
108. **Vídeo para no meio do corte, sem erro** (corte de 35 s com 20 s de vídeo). Causa: o trecho atravessa a emenda de
uma retomada em outra resolução ou codec (H.264 → HEVC) e o concat + `filter_complex` corta o vídeo ali.
Correção: `uniform_segments` (`editor_render.py`) converte os blocos do trecho num intermediário uniforme só
nesse caso (render e proxy); o proxy faz `fps` antes do `scale`; `face.py` mede o tamanho do quadro por bloco.
Observadas em 17/11/2026 (diagnóstico da sessão 3, cartão da sessão, apagar cortes e prévia do editor; 114 também em
"Armadilhas já resolvidas" de `clipper/README.md`):
114. **"Não está gerando cortes".** Causa quase sempre: a **live esfriou**, não as regras. Sessão 3 (cópia do banco):
chat de 0,27–0,39 msg/s e 56–78 reações a cada 500 s caiu para 0,04–0,10 msg/s e 2–10 reações; nenhum pico da
heurística em 8872–10350 s, nem com as regras antigas; as antigas dariam 3 candidatos a mais (2 de rosto fraco com
nota 2,5 e 1 na cena do corte 61, rejeitado); zona proibida 34 % × 24 %. Correção: antes de mexer em regra, olhe
msg/s e reações (`GET /v1/sessions/{id}/timeline`) e `proposals`/`created` da varredura em `sessions.memory_json`
(e no log). Onde: `clipper/app/intel.py` (contagem), `worker.py` (`VETO_STATUSES`).
115. **"Agora na live" parece travado e o tempo gravado anda aos saltos.** Causa: o resumo só muda a cada janela da
varredura (`scanIntervalS`, 180 s) e `durationS` sobe por bloco (30 s). Correção: relógio local que corre entre as
consultas, com teto de 45 s ("aguardando o bloco"), e contagem "próximo em m:ss". Onde: `RecordingClock` e
`SummaryCadence` em `panel/src/components/clipper-sessions.tsx`.
116. **Barra de seleção presa no topo da fila reprovada pelo dono.** Causa: ação em massa ocupando espaço e cobrindo
o conteúdo. Correção: controles discretos no canto ("Selecionar", "⋯"), caixa do cartão só no hover/foco/modo de
seleção e pílula flutuante pequena; nada pode empurrar a lista. Vale para toda ação em massa nova. Onde:
`panel/src/components/clipper-queue.tsx`.
117. **Prévia do editor 1–3 px deslocada do render** (corte 61, câmera 18 % × 23 %) e blocos de legenda diferentes.
Causa: o FFmpeg recorta em pixel **par** no yuv420 e o `scale … increase` arredonda; a prévia dividia em subpixel;
a legenda do painel não saneava os tempos como `subtitles.py`. Correção: `ffmpegCropFill` com o tamanho de
`session.capture` e porte `cleanWords`/`groupWords`/`captionBlocks` (`CAPTION_TIMING`). Onde:
`panel/src/components/clip-editor-model.ts`; mudou `subtitles.py` ou `layout_chain`, mude o porte junto.
136. **Juiz do Clipador esgota a cota do ChatGPT / chamadas lentas e caras.** Causa: cada chamada do juiz é um processo
novo de CLI (2 por candidato) e o Codex carrega ~77 mil caracteres fixos (~19 mil tokens) antes do prompt; uma live de
3,7 h (75 candidatos, ~150 chamadas) gastou ~2,9 milhões de tokens só de fixo. Correção: `codex_lean_overrides`
(features/MCP/plugins off, `system` em `model_instructions_file`) e `--setting-sources project,local` no Claude.
**Só vale depois de reiniciar o Clipador (porta 4520)**: o código é lido na partida. Detalhes em
[token-economy.md](token-economy.md). Onde: `clipper/app/judge.py`.
Observadas em 18/11/2026 (revisão × final, falantes, dublagem, trabalho em worktree):
180. **Corte aprovado "não publica" e o job fica parado.** Causa: a publicação só usa o vídeo FINAL (`publishFile`); enquanto
`final_status` não é `ready` o job mostra "Esperando o vídeo final…" (final `pending`/`rendering`, ou `error`).
Correção: olhe `final` no corte (`GET /v1/clips`, campos `final` e `publishFile`); `error` → "Tentar de novo" = `POST /v1/clips/{id}/final`.
Nunca troque para `file` (é o de revisão, com camadas de teste). Corte antigo publicado com tradução e sem final: gere
com `POST /final` antes de mandar a outra rede. Onde: `clipPublishFile` (`panel/src/lib/publishing-rules.ts`),
`sendDue` (`publishing.ts`); doc `doc/clipador/REVISAO.md`.
181. **Botão "Traduzir a fala" (e a lista de vozes) dava 404.** Causa: a rota existia no Clipador, mas a regex `ALLOWED` do
proxy do painel não liberava `clips/{id}/translate` nem `sessions/{id}/speakers`. Correção: liberadas em `ALLOWED` +
`METHODS`. Rota nova do Clipador = regex, método e timeout em `panel/src/lib/clipper.ts` no mesmo commit.
182. **Fala do colega aparece como do streamer (ou tudo em uma linha só).** Causa esperada, não bug: sem atribuição nos
primeiros minutos (< 15 s de fala por voz); volume e boca **discordam** ou nenhum decide → ninguém vira "outro"; webcam
de perfil não separa pela boca; o código novo só roda depois de reiniciar o Clipador. Correção: confira
`GET /v1/sessions/{id}/speakers` (vozes e por quê); corrija à mão no editor (**Outra pessoa / É o streamer**).
Onde: `clipper/app/speakers.py`; `doc/clipador/FALANTES.md`.
183. **Dublagem soa corrida, emendada ou cortada no fim.** Causa: o português sai bem mais longo que o inglês; o encaixe
deixa a fala escorrer até 1,5 s sobre a próxima frase, acelera até 1,2× e por fim corta com fade (medido: 9 de 25 falas
cortadas no corte 259). Não é falha; **não** acelere além disso nem clone a voz do streamer. A 1ª renderização sintetiza
(~1,6 s por frase); depois o cache (`data/clipper/dub/`) deixa +0,3 s. Onde: `clipper/app/dub.py` (`fit`).
184. **Worktree de isolamento do harness falha no Windows.** Causa: diferença de caixa da letra do drive (`f:` × `F:`).
Correção: criar a worktree à mão em `F:/Projects/cf-wt/<nome>` (`git worktree add`). Para rodar testes nela: copiar
`clipper/tests/data/vertical_golden_sha256.json` (ignorado no git, o teste dourado do vertical precisa dele) e criar
um junction `panel/node_modules` apontando para o da pasta principal (sem isso `tsc` e os testes do painel não rodam).
185. **Serviço "não pegou" ou "caiu e não voltou".** Os serviços (painel, voz, Clipador, Publicador) são do usuário, subidos
por `pnpm dev`: agente **não** sobe nem encerra. O `scripts/dev.ts` pula um serviço se a porta já está ocupada e só
reinicia sozinho a voz (quando `voice/.env` muda); serviço que cai não volta. Peça ao usuário para reiniciar o `pnpm
dev` (com a suíte verde: item 87) e compare o início do processo com o arquivo (item 143).
## Publicação (Publicador + despachante do painel)
Regras de projeto informadas em 17/11/2026 (código em `panel/src/lib/publishing*.ts` e `publisher/app/`); nenhuma
observada num envio real ainda. Contexto em [publishing.md](publishing.md).
118. **Job em "Com problema" dizendo que o Publicador terminou sem confirmar o link.** Causa: o Publicador devolveu
`done` sem `remoteId`/`url` (comum no modo sessão quando a tela não mostra o link). Correção: por regra nunca vira
`published` sem ID/URL (ou rascunho) — `readPublisherJob` grava `failed`. **Confira na rede** antes de "Tentar de
novo", senão o vídeo sai duas vezes. Mesmo cuidado com `failed` "interrompido" (Publicador fechado no meio). Todo
`failed` que chegou ao Publicador tem `mayBeLive`: a UI pergunta "Confira na rede se o vídeo já saiu" e a API
responde 409 ao `retry` sem `{confirm: true}` (`retryJob` em `publishing.ts`).
119. **Job parado em "Esperando: …" sem falhar.** Causas, nesta ordem: painel fechado (o laço de 20 s roda dentro do
`pnpm panel`); publicação pausada em Configurações; Publicador fora (503 → "inicie com pnpm dev"); perfil não
`connected` no Publicador (409 → o job **fica na fila** e a rede é reconsultada); "Publicador indisponível ou mal
configurado" (401/403/404: `PUBLISHER_SERVICE_KEY` diferente ou Publicador antigo — reinicie o `pnpm dev`).
Timeout/conexão caída também deixa na fila: o reenvio usa o mesmo `clientRef` e não duplica. Onde: `sendDue`.
120. **Rede em `expired` ou `needs_login`.** Causa: autorização oficial vencida (ex.: YouTube em "Testing" vence em 7
dias) ou a rede pediu login/captcha no modo sessão. Correção: reconectar em Canais de publicação ("Entrar de
novo"/reabrir a janela); nunca automatizar login nem captcha.
121. **Jobs de um corte cancelados sozinhos.** Causa: exportar no editor (ou re-renderizar) volta o corte para
`pending`; jobs não enviados viram `canceled` com `cancel_reason = 'source_changed'`. Encerrar a fonte ou a
história no canal faz o mesmo com `unlinked` ("a fonte/história foi desligada deste canal"). Correção: nenhuma —
voltam sozinhos quando o corte fica pronto de novo ou a fonte é religada. Já enviado não é cancelado.
122. **Ligou a aprovação automática e os cortes antigos não saíram.** Não é erro: só cortes criados depois de ligar
(`accounts.auto_since`) e depois de ligar a fonte ao canal são aprovados sozinhos; religar uma fonte encerrada
zera `linked_at`, então os cortes do intervalo desligado também não. Antigos: aprovar à mão.
123. **"Na hora" virou agendado.** Causa: limite diário da rede (`daily_limit`) já atingido; vai para o próximo
horário bom livre. Correção: subir o limite ou esperar.
124. **TikTok oficial publica só como "Somente eu".** Causa: app sem auditoria só permite `SELF_ONLY` (conta privada)
e a auditoria para uso próprio provavelmente é negada (`doc/publicacao/PESQUISA.md`). Correção: modo Rascunho
(`tiktok_mode = 'draft'`, até 5 pendentes/24 h) ou sessão logada.
125. **API do painel responde 403 "Acesso recusado…" ou 415 a `curl`/script.** Causa: `panel/src/proxy.ts` só aceita
Host 127.0.0.1/localhost/[::1] e exige, em POST/PUT/PATCH/DELETE, `Origin` do mesmo host (ou `Sec-Fetch-Site:
same-origin`), senão "Acesso recusado: pedido sem origem do próprio painel"; `readJson` (`lib/http.ts`, usado em parte
das rotas; as outras leem `request.json()` direto) exige `Content-Type: application/json`. Correção:
`curl -X POST -H "Origin: http://127.0.0.1:4500" -H "Content-Type: application/json" -d '{}' http://127.0.0.1:4500/api/...`.
Não afrouxe a guarda (anti DNS rebinding e CSRF; teste em `panel/src/lib/proxy.test.ts`).
126. **Agendado saiu em outro horário depois de reabrir o painel.** Causa: horário automático (`schedule_source =
'auto'`) vencido há > 30 min (`STALE_AFTER_MS`) é reencaixado no próximo horário bom, sem rajada. Horário manual e
"Publicar agora"/"Tentar de novo" não são reencaixados. Onde: `needsReflow` (`publishing-rules.ts`), `promoteDue`.
127. **Conectar pela API oficial não conclui.** Causas: o Publicador reiniciou no meio (o `code_verifier` do PKCE fica
só em memória) ou o passo a passo parou de esperar (10 min, `WAIT_LIMIT_MS` em `connect-wizard.tsx`). Correção:
clicar **Conectar** de novo.
128. **Janela do navegador do modo sessão fecha sozinha.** Não é erro: fecha depois de cada envio e do "Já entrei"
(saída limpa; mata após 10 s) e quando ociosa (5 min; 15 min se aberta para login), para a porta CDP ficar aberta o
mínimo. Fica aberta se a rede pedir login/captcha. Onde: `publisher/app/platforms/session/browser.py`.
137. **Modo sessão: o Chrome abre, a conta está logada, a porta 4540 responde em `/json/version`, mas o painel diz "O
navegador abriu mas não respondeu".** Causa (17/11/2026): o **Chrome 157 (157.0.8103.79) não grava
`DevToolsActivePort` no perfil quando a porta é fixa** (`--remote-debugging-port=4540`), e `owns_port` dependia só
desse arquivo. Correção: `owns_port` usa o `DevToolsActivePort` quando existe; senão usa a marca
`CenaForgeWindow.json` (`{"pid","port"}`, gravada por `write_window_mark` logo depois do `Popen`) e exige que o PID
que escuta na porta (`listener_pid`, `GetExtendedTcpTable` via ctypes, sem psutil) seja exatamente o da marca e que o
executável (`process_exe_name`, `QueryFullProcessImageNameW`) seja `chrome.exe`/`msedge.exe`. `active_port` também lê
a marca; `open()` apaga marca e `DevToolsActivePort` velhos. Medido ao vivo: `listener_pid(4540)` = `chrome.exe`
lançado pelo Publicador (o PID do `Popen` é o próprio processo que escuta). **Só vale depois de reiniciar o
`pnpm dev`** (o Publicador roda sem `--reload`). Variante: se o processo sai logo, o Chrome entregou a URL a uma
janela já aberta com o mesmo perfil (sem a nossa porta); `_wait_cdp(port, user_dir, process)` detecta e mostra "Já
existe uma janela do navegador aberta com este perfil. Feche essa janela (a conta continua logada) e tente de
novo." — feche a janela, não mexa no código. Testes: `test_owns_port_without_devtools_file_uses_window_mark` e
`test_wait_cdp_explains_when_profile_window_is_already_open` em `publisher/tests/test_hardening.py`. Onde:
`publisher/app/platforms/session/browser.py`.
138. **"Publicar" no cartão do corte (ou desligar fonte) falha com "table publish_jobs has no column named origin".**
Causa (17/11/2026, `POST /api/publishing/clips/75`): a v7 do banco (`publish_jobs.origin`) não tinha sido aplicada
no banco já aberto; `INSERT ... origin` e `accounts.endChannel` (`AND origin = 'link'`) quebram. Hoje o `db()` migra
sozinho: a conexão fica em `globalThis.__cenaforgeDb`, e a marca de módulo `checkedThisModule` (some a cada recarga
do código pelo HMR) faz a 1ª chamada depois da recarga rodar `migrate()` no banco aberto, com backup em
`data/backups/` (`cenaforge-v<antiga>-<data>.db`). Medido: um `GET /api/publishing/summary` no painel em execução
levou o banco real a `user_version` 7, com a coluna `origin` e o backup `cenaforge-v6-2026-11-17T16-28-39-725Z.db`.
O sintoma ainda aparece se o próprio `db.ts` não foi recarregado (módulo antigo, sem a marca); na prática qualquer
edição em `db.ts` o recarrega. Correção: fazer qualquer requisição ao painel (ex.: `GET /api/publishing/summary`,
com `Origin` se não for GET, item 125) ou, se ainda falhar, pedir ao usuário que reinicie o `pnpm dev` (o painel é
dele; reiniciar mata agente em execução, item 131). Conferir: `PRAGMA user_version` de `data/cenaforge.db` =
`MIGRATIONS.length`. Onde: `db()` em `panel/src/lib/db.ts`, `publishClip` em `panel/src/lib/publishing.ts`.
139. **Modo sessão (TikTok): job falha com "Locator.set_input_files: Cannot transfer files larger than 50Mb to a browser
not co-located with the server", embora o login e a navegação tenham funcionado.** Sintoma (17/11/2026): a captura
`data/publisher/logs/20261117-133245-tiktok-*.png` mostra o TikTok Studio logado na tela "Selecione o vídeo a
enviar"; a falha foi só na entrega do arquivo. A mensagem ao usuário é a genérica "O navegador travou ou mudou de
página no meio do envio" (todo `PlaywrightError` cai nela, `_with_page`); o texto real vem depois de "Detalhe:". Causa:
com `connect_over_cdp` o Playwright trata o navegador como remoto e recusa `set_input_files` acima de 50 MB; os
cortes do Clipador têm 100–108 MB (`clip-52.mp4` com 107,9 MB). Correção: `is_local=True` no `connect_over_cdp`
(parâmetro existe no playwright 1.65.2 da `publisher/.venv`, conferido na assinatura), em `_with_page`
(`runner.py`, com comentário) e em `BrowserManager.close` (`browser.py`). Só `127.0.0.1` com porta conferida como
nossa (`owns_port`); não use para endereço remoto. **Só vale depois de reiniciar o `pnpm dev`** (o Publicador roda sem
`--reload`). Evidência: `pnpm test:publisher` → 73 passed (reexecutado na skill, 17/11/2026); **envio real ainda não
refeito**. Ao ver "travou ou mudou de página", leia o "Detalhe" antes de culpar o navegador. Onde:
`publisher/app/platforms/session/runner.py`, `publisher/app/platforms/session/browser.py`.
140. **TikTok em modo sessão publicou, mas o job falhou com "não confirmou o link".** Sintoma (17/11/2026, 1º envio real,
público às 13:35): o vídeo está no ar (`https://www.tiktok.com/@vortplay/video/7709179978520284437`) e o painel marcou
`failed`. Causa: depois de publicar, o Studio vai para `/tiktokstudio/content`, mas a linha nova só mostra o
`<a href="/@conta/video/<id>">` alguns segundos depois; o código antigo procurava `a[href*='/video/']` por só 5 s.
Correção (2ª versão, 17/11/2026): `find_video_url(page, caption, sleep, attempts=12, reads=5, progress)` espera 5 s e, a
cada tentativa, abre ou RECARREGA `CONTENT_URL` (a lista não se atualiza sozinha; o vídeo novo entra depois de
processar), lê 5 vezes a cada 3 s, até 12 cargas (~3 min), e só aceita o link da linha (até 10 ancestrais do `<a>`)
que contém `caption_key(caption)` (24 primeiros caracteres da legenda sem #hashtags/@menções): nunca pega o link de
outro vídeo. Sem link: step "…não apareceu na lista do Studio em ~3 min; link não encontrado"; o painel mostra "Saiu
na rede, mas o link do vídeo não apareceu a tempo… use 'Já saiu: informar o link'" (`readPublisherJob`). O seletor `video_link` saiu
de `SELECTORS`. Validado ao vivo, só leitura (informado): legenda certa → link; legenda de outro corte → `None`. Se
acontecer de novo: **confira na rede antes de "Tentar de novo"** (publicaria duas vezes) e use "Já saiu: informar o
link" (`mark-published`, `publishing.md`). Só vale depois de reiniciar o `pnpm dev` (item 137). Teste:
`test_tiktok_link_waits_for_the_list_and_matches_caption` (`publisher/tests/test_browser.py`). Onde:
`publisher/app/platforms/session/tiktok_studio.py`.
141. **Job manual novo cancelado como "unlinked" (regra antiga) ou despachante ignorando código novo.** Causa: o laço de
`panel/src/instrumentation.ts` (`startDispatcher`) guarda a função `tick` em `globalThis` e o HMR não a substitui;
o laço seguia com o `dispatcherTick` antigo (sem a regra de `origin = 'manual'`). Correção: no fim de
`panel/src/lib/publishing.ts`, ao carregar o módulo, `if (state.tick && state.tick !== dispatcherTick) state.tick =
dispatcherTick`. Regra: todo estado de laço guardado em `globalThis` precisa ser reapontado quando o módulo recarrega.
Se o sintoma voltar com outro módulo, aplique o mesmo padrão; reiniciar o `pnpm dev` é do usuário (item 131). Onde:
`panel/src/lib/publishing.ts` (bloco final), `panel/src/lib/dispatcher.ts`.
142. **Modo sessão (TikTok): falha com "Locator.click: Timeout 30000ms exceeded … waiting for locator("div[contenteditable='true'].public-DraftEditor-content")".**
Sintoma (17/11/2026): a captura `data/publisher/logs/20261117-134508-tiktok-*.png` mostra o vídeo já carregado e,
por cima da página escurecida, um aviso de novidade do Studio, "Veja a prévia do seu vídeo no seu celular", com o botão
**Entendi**. Causa: o aviso bloqueia o clique na legenda (o seletor está certo). O Studio também pré-preenche a legenda
com o nome do arquivo ("clip-75"), mas `fill_text` já faz Ctrl+A/Delete. Correção em `common.py`: `TIP_BUTTONS` aceita só
`^(Entendi|Entendido|Ok, entendi|Got it)$`; `dismiss_tips(page, sleep, rounds=3)` fecha esses avisos;
`click_through(locator, sleep, timeout_ms=8000)` clica e, no timeout, fecha os avisos e tenta de novo (sem aviso
para fechar, relança o erro original); `fill_text` usa `click_through`. Em `tiktok_studio.py`, `dismiss_tips` roda
antes da legenda e antes de "Publicar", e todos os cliques (privacidade, mostrar mais, IA, Publicar, Publicar agora)
passam por `click_through`. **Regra:** por esse caminho só se fecham avisos de "entendi"; nunca aceitar ou recusar
opções (verificação de conteúdo, música etc.). Outro aviso novo com outro texto de botão: acrescente-o a `TIP_BUTTONS`
só se fechá-lo não mudar o post. Mensagens: `browser_error_text(detail)` em `runner.py` troca o genérico "O navegador
travou…" por frases para clique com timeout ("aviso do site aberto por cima…"), timeout comum, arquivo > 50 MB e janela
fechada; o "Detalhe" técnico continua depois. Testes: `test_click_through_closes_tip_and_retries` e
`test_browser_error_text_explains_common_failures` (`publisher/tests/test_browser.py`); `pnpm test:publisher` → 76
passed (reexecutado na skill, 17/11/2026). **Só vale depois de reiniciar o `pnpm dev`** (item 137); o post desse envio
não chegou a ser feito e a correção **não foi testada num envio real**. O upload de 100+ MB funcionou nesse envio, o
que indica que o `is_local` (item 139) já valia. Onde: `publisher/app/platforms/session/common.py`,
`publisher/app/platforms/session/tiktok_studio.py`, `publisher/app/platforms/session/runner.py`.
143. **Corrigi o código, mas o envio/corte seguinte ainda se comportou como antes.** Sintoma (17/11/2026): o envio das
13:50 no TikTok durou 25 s, menos que a busca nova do link, e saiu sem link. Causa: o processo do Publicador (uvicorn
:4530) começou às 13:34:25; `tiktok_studio.py` (13:46), `common.py` e `runner.py` (13:46–13:47) foram gravados depois,
e o serviço roda sem `--reload`: rodou o código ANTIGO. Vale também para o Clipador (:4520) e a voz. Diagnóstico:
comparar o início do processo com a data dos arquivos, antes de culpar a correção:
`Get-CimInstance Win32_Process -Filter "Name='python.exe'" | Select ProcessId,CreationDate,CommandLine` (PowerShell) e
`Get-Item <arquivo> | Select LastWriteTime`. Arquivo mais novo que o processo = reiniciar o `pnpm dev` (do usuário,
item 131). Só dê "validado" a mudança em serviço depois de confirmar que o processo é posterior ao arquivo.
144. **Legenda do corte com `#RobRun` e `#ROBRUN` alternando ou tags genéricas (`#clã`, `#loot`).** Causa (antes de
17/11/2026): o juiz escrevia 3–5 hashtags livres na legenda. Hoje a legenda sai de `build_caption`
(`clipper/app/hashtags.py`): texto sem hashtags, tags de `compose` (canal, até 3 do jogo, até 4 do momento, sem
repetidas por `fold`, até 8) e crédito. Se o perfil do jogo **não tem `hashtags`** (caso do ROB RUN até a pesquisa ou
a edição), vale só o nome do jogo (`#ROBRUN`): use "Pesquisar de novo" ou edite a seção "Hashtags" na aba Jogos.
Legenda de corte antigo não muda; só corte novo ou "Mandar de novo para a IA". Só vale depois de reiniciar o
Clipador (item 143). Teste: `clipper/tests/test_hashtags.py`.
145. **Modo sessão (Instagram): "Já entrei" responde "não achei o botão Criar do Instagram" com a conta logada.**
Causa (17/11/2026, inspecionado ao vivo): no layout novo a barra lateral só tem ícones; o botão é `<a>` com
`<svg aria-label="Postar">` e abre direto o diálogo "Criar novo post" (sem submenu), com o `input[type=file]` dentro
do diálogo. O usuário também rodava código antigo (item 143). Correção: `SELECTORS["create"]` aceita "Postar"
(svg, link, botão); mensagem "botão Postar". Risco ligado: no feed cada post tem um botão de ícone "Compartilhar", e
`role=button ^Compartilhar$` podia clicá-lo; `next`, `share` e `reels_notice_ok` agora são CSS presos a `_DIALOG`
(`div[role='dialog']`). Teste: `test_buttons_of_the_flow_are_searched_inside_the_dialog`. Onde:
`publisher/app/platforms/session/instagram_web.py`. Fluxo e validação: [publishing.md](publishing.md).
146. **Instagram: rótulo de IA não liga, ou a legenda troca `#teste` por `#testemunho`.** Causa: com a legenda terminando
em `#tag`/`@menção`, o Instagram abre a lista de sugestões POR CIMA dos interruptores; um clique forçado
(`force=True`) no rótulo de IA caiu na lista (ensaio de 17/11/2026). O interruptor é `input role=switch` sem nome
acessível (achado pelo texto da linha, `find_ai_switch`). Correção: `close_suggestions` digita um espaço no fim
(Esc NÃO serve: fecha a caixa de criação); clique forçado removido; depois do clique `_is_on` confere e, se não ligou,
`PublishError` (não publica sem o rótulo). Teste: `test_instagram_links_and_hashtag_suggestions`. Regra geral: nunca
`force=True` em seletor de modo sessão (clica no que estiver por cima). Para validar seletor com conta real sem
publicar, rode só `prepare` e descarte o rascunho.
147. **Instagram: o reel saiu em 1:1 (quadrado), sem o topo do rosto do streamer; o TikTok saiu certo.** Sintoma
(17/11/2026, 1º reel real `/reel/Df2cezTNhY7/`, corte 68). Causa: a etapa "Cortar" do diálogo vem em 1:1 e o fluxo
clicava em "Avançar" direto. Correção: `keep_original_shape(page, sleep)` (`instagram_web.py`), chamada em `prepare`
antes dos "Avançar": clica em `svg[aria-label='Selecionar corte']` (ou 'Select crop') dentro do diálogo, escolhe
"Original" (opções: Original, 1:1, 9:16, 16:9) e fecha o menu. Sem o ícone ou sem a opção, `PublishError`: **não
publica cortado**. Sub-armadilha: o botão "Original" tem o texto mais o `<title>` do svg ("Ícone de contorno de
foto"), então `:text-is('Original')` não casa; usa-se `("role","button", r"^\s*Original\b")` e `:has-text` no
diálogo. Também `common.find` com `visible=True` agora olha até 6 ocorrências (`nth`) até achar uma visível (a
primeira pode ser cópia escondida); os falsos de teste ganharam `nth`. Validado (informado): ensaio sem publicar
mostrou a prévia "Novo reel" com o vídeo inteiro 9:16, rosto completo, legenda e rótulo de IA; rascunho descartado.
O usuário apagou o reel cortado à mão (a página mostra "Esta página não está disponível"). **Só vale depois de
reiniciar o `pnpm dev`** (item 143); nenhum envio real feito com o formato novo. Onde:
`publisher/app/platforms/session/instagram_web.py` (`SELECTORS["crop_toggle"]`, `["crop_original"]`), `common.py`.
148. **Corte publicado com rótulo de IA, ou "Perfil gerado por IA" sob o nome no Instagram.** Regra (pedido do dono,
17/11/2026): corte nunca leva rótulo de IA. Em `sendDue` (`publishing.ts`): `aiGenerated = job.source_kind === "clip"
? false : aiGeneratedFor(...)`, mesmo com o canal em "always". O texto "Perfil gerado por IA" visto no reel NÃO veio do
post: o job tinha `aiGenerated: False` e o canal estava em `ai_label=auto`. Provável rótulo do PERFIL (talvez foto de
perfil feita com IA e metadados); **não confirmado**. Episódio segue a regra de `aiGeneratedFor`.
149. **Vídeo publicado foi apagado na rede e o painel ainda o mostra como publicado (ou não deixa publicar de novo).**
Correção: ação "Apaguei na rede" (`removed`), só em job `published`. `markRemoved(id)` (`publishing.ts`) faz UPDATE
condicional para `canceled`/`user`, zera `url`, `remote_id`, `published_at`, grava o step "Apagado da rede por você…"
e apaga `publications WHERE job_id` (métricas saem em cascata). Depois, "Publicar" no corte reenvia com `attempts`+1
(novo `clientRef`). O painel NÃO apaga nada na rede: apague direto lá primeiro (a UI confirma). Rota
`POST /api/publishing/jobs/[id]/removed`; cliente `markJobRemoved`; botão em Publicadas (`publishing-board.tsx`).
Usada no job 3 (Instagram do corte 68). Teste em `publishing-db.test.ts`.
150. **Script Python de diagnóstico com `-I` imprime `?`/falha ao escrever acentos no Windows.** `python -I` ignora
`PYTHONIOENCODING` e `PYTHONUTF8`. Correção: no script, `sys.stdout.reconfigure(encoding="utf-8")`.
151. **YouTube Studio (modo sessão): "Cliquei em Publicar mas o YouTube Studio não confirmou", e o vídeo saiu.** Sintoma
(17/11/2026): a captura 60 s depois do clique mostrava a caixa de envio ainda aberta, com o botão Publicar. Causa
provável (não isolada): `#done-button` é um `ytcp-button`, não `<button>` nativo; o Playwright clica nele mesmo
desativado e o clique se perde. Correção: `is_enabled`/`wait_enabled` (lê `disabled`/`aria-disabled` do elemento e do
`<button>` interno; espera até 10 min), `dismiss_tips` + `click_through` antes de clicar e `confirm_published` (45
checagens de 2 s; aceita "publicado", "sendo processado" ou a caixa fechar; se o botão segue liberado depois de ~16 s,
clica de novo UMA vez). O erro final traz o link visto antes do clique: confira na rede e use "Já saiu: informar o
link" (nunca "Tentar de novo" sem conferir). Teste: `test_youtube_confirms_when_upload_box_closes_and_retries_once`.
Só vale depois de reiniciar o `pnpm dev` (item 143). Onde: `publisher/app/platforms/session/youtube_studio.py`.
152. **Números do Instagram vêm só com views (curtidas e comentários faltando).** Causa: a grade da aba Reels aparece ANTES
da resposta de `/api/graphql`; parar ao achar a grade perde `like_count`/`comment_count`. Correção: a API tem
prioridade e a grade só entra como reserva depois de 3 voltas (`instagram_stats`, `session/stats.py`). TikTok e
Instagram não têm leitura sem janela logada (página pública devolve só verificação ou nada). Ver [publishing.md](publishing.md).
153. **Corpo JSON com acento por `curl -d` no Git Bash chega com UTF-8 inválido** (`jsontext: invalid UTF-8`). Correção:
gravar o corpo num arquivo (scratchpad) e enviar com `--data-binary @arquivo`, com `Origin` e `Content-Type` (item 125).
Mesmo com `curl` o nome "Verificação" virou id `teste-verifica-o` na API de personagens (17/11/2026): teste acentos por
Python/UTF-8.
154. **Publicar o repositório (Gitea) expondo segredo ou e-mail pessoal.** O projeto é PÚBLICO em
`https://git.origininteractivestudios.com/Mateuus/CenaForge` (Gitea 1.27.3; 1º commit `84f30bb`, 484 arquivos,
~7,4 MB, 17/11/2026). Fora do git: `data/`, `.env`, venvs (inclui `publisher/.venv/`) e `output/`. Commits neste
repositório usam o e-mail noreply do Gitea (`git config` local). Antes de subir: procurar segredos (chave do serviço do
Publicador, tokens, e-mails) nos arquivos que vão. Commit e push só quando o dono pedir.
155. **Capa do vídeo publicado some do dashboard ("Views de cada vídeo") com imagem quebrada.** Causa: apagar uma sessão no
Clipador (`worker.delete_session`) faz `rmtree` de `output/clipper/<sessão>/`, levando vídeo e capa, e
`publish_jobs.cover` apontava para lá. Correção (17/11/2026): `clipCover()` copia a capa para
`output/publishing/covers/clip-<id>.<ext>` (pasta só do painel, `keepCover`); `keepClipCovers()` migra jobs antigos no
início de `syncClips` enquanto o arquivo existe (22 de 25 na hora); `metrics.ts` só devolve capa que existe no disco.
Capa já perdida: a miniatura do próprio Short serve, `https://i.ytimg.com/vi/<remote_id>/oar2.jpg` é a vertical
1080×1920 (`maxresdefault` é 1280×720 horizontal); foi o que se fez no corte 91. Junto: em `metrics.ts` a regex do
episódio era `/^ep(d+)/i` (faltava a barra) e o link ia só para a história; agora `/^ep(\d+)/i`. Onde:
`panel/src/lib/publishing.ts`, `panel/src/lib/metrics.ts`.
156. **Cartoon: a síntese de voz não devolve tempos por palavra.** `POST /v1/synthesize` só entrega o áudio; tempos vêm da
transcrição (`/v1/transcribe`, `X-Detail: words`). `wordTimings` transcreve o áudio do trecho; sem o serviço de voz,
reparte o texto pela duração (aproximado). A montagem antiga (FFmpeg) reparte a legenda por tamanho (`captionChunks`
em `montage-ffmpeg.ts`). Onde: `panel/src/lib/montage-cartoon.ts`.
157. **Cartoon: o plano sai genérico (rua de casas, noite) quando o texto não cita um lugar conhecido.** Observado
(17/11/2026, antes dos lugares por peças): história de ilha/cobras saiu em rua de casas. Hoje `LOCATIONS` cobre 10
lugares (parque, cemitério, bunker, casa…); fora deles cai nas cenas antigas (`scenes.tsx`, da história de energia).
Lugar novo = linha em `LOCATIONS` (+ peça em `places.tsx` se faltar), nunca cena pronta. Sem lugar, prefira `mixed`/`3d`.
Onde: `panel/src/lib/montage-cartoon.ts`.
158. **TikTok: `#hashtag` publicada vira texto, não hashtag.** Diagnóstico (`doc/publicacao/TIKTOK_DIAGNOSTICO.md`): a página
pública do vídeo mostrava `challenges: []` e `textExtra: []`, porque `insert_text` cola `#tag` como texto puro.
Correção: `caption_parts` separa texto e tags; `type_caption` cola o texto, digita cada `#tag` e confirma clicando na
sugestão exata (`hashtag_options`); sem sugestão a tag fica como texto; progresso "N de M hashtags confirmadas". Teste:
`publisher/tests/test_tiktok_caption.py` (3, não reexecutado na skill). **Não validado com vídeo real**; só vale
depois de reiniciar o `pnpm dev` (item 143). Onde: `publisher/app/platforms/session/tiktok_studio.py`.
159. **Ler várias páginas públicas do TikTok seguidas devolve o desafio anti-robô `SlardarWAF`** (1.462 bytes) para
`curl`/`yt-dlp`. Um Chrome real passa. Receita para baixar um vídeo de referência (informada, não reexecutada): Playwright
com `channel="chrome"` e perfil temporário, ler `__UNIVERSAL_DATA_FOR_REHYDRATION__`
(`itemStruct.video.bitrateInfo[].PlayAddr.UrlList`) e baixar por `ctx.request` com `Referer: https://www.tiktok.com/`.
Só para referência/estudo; nunca em stealth no fluxo de publicação (regra em publishing.md).
160. **Cartoon: HUD, gerador e onomatopeia do exemplo aparecem em todo trecho.** Causa: a Remotion completa props ausentes
com os `defaultProps` da composição; com o exemplo como padrão, tudo que o spec não trazia vinha do exemplo.
Correção: `Shot` tem padrão VAZIO; o exemplo fica na composição `Sample` (só Studio). Campo opcional novo no spec
precisa de valor vazio em `BLANK`. Onde: `cartoon/src/Root.tsx`.
161. **Cartoon: o plano errava o assunto do trecho.** "um barulho" solto virava "Vrrrum" (agora motor só com
gerador/motor/moto/carro perto; barulho genérico = "Crec"); "domingo de sol" virava noite (regra de dia ganhou
sol/manhã/domingo/claro); multidão era desenhada na frente do personagem (agora entra antes, pés em y 0,6);
onomatopeia cobria a etiqueta do personagem (vai para x 0,76 / y 0,24 quando há personagem). Ao mexer em palavra-chave,
rode `montage-cartoon.test.ts`. Onde: `panel/src/lib/montage-cartoon.ts`.
162. **Regex com `\b` escrita por heredoc/Python sem string raw vira um caractere de controle (backspace, 0x08)** (aconteceu 2x ao
editar `montage-cartoon.ts`): a regex deixa de casar, sem erro. Use `r"..."` ou o Edit (item 44) e confira com
`grep -nP "\x08" <arquivo>` que não sobrou nenhum.
163. **Cartoon: a boca (curva quadrática) só chega à METADE do ponto de controle.** Controles da boca ficam no dobro da
abertura desejada. Onde: `cartoon/src/CharacterFigure.tsx`.
164. **Script de teste em Python que grava JSON com `open(..., "w")` sem `encoding` estraga acento no Windows** (cp1252; o
render lê UTF-8). Sempre `open(..., "w", encoding="utf-8")` (e `ensure_ascii=False` se quiser acento legível). Mesma
família do item 153. Onde: ao gerar `character.json`/spec por script.
165. **Cartoon: sombra do corpo/barriga em elipse parece mancha.** Correção: elipse + curva de volume (contorno) e sombra
lateral recortada por `clipPath`. Onde: `cartoon/src/CharacterFigure.tsx`.
166. **Clipador: depois de parar a sessão à mão, a fonte não grava de novo (ou as rotas/campos novos "não pegam").**
Dois lados. (a) Parar à mão pausa o monitor da fonte de propósito (`monitor_paused_at`): live no ar e nada
reabrindo não é falha. Religar = "Religar" em `/clipper/sources`, `PATCH /v1/channels/{id}` `{"monitor": true}`,
gravar pelo link ou retomar a sessão; `{"pauseMonitor": false}` no stop evita a pausa. Queda de live sem ninguém
parar continua retomando na mesma sessão. (b) Serviço sem `--reload` (item 144): sem reiniciar, `stop` não pausa,
`language` não é aceito nem devolvido e a migração v11 não roda; o painel trata os campos como opcionais, então
nada quebra, só não pega. Reinicie (é do usuário) e confira `PRAGMA user_version` = 11. Onde:
`clipper/app/worker.py`, `main.py` (`StopIn`), `db.py` (v11); teste `clipper/tests/test_monitor_pause_and_language.py`.
167. **Clipador: perfil do jogo sem versão em inglês, GTA VI ausente ou "cadastrar jogo" que não funciona.** (a) Serviço
sem reiniciar (item 144): a migração v12 não roda, `POST /v1/games`, `translate`, `DELETE` e `?lang=` não existem e a
semente do GTA VI não é importada (só entra na subida, e só se o jogo não existe: nunca sobrescreve edição).
Reinicie (é do usuário) e confira `PRAGMA user_version` = 12. (b) Jogo antigo tem `profileAi: null`: a IA usa o
português até rodar `POST /v1/games/{id}/translate` ("Gerar versão em inglês" no modal). (c) Categoria ou tela com
outro nome ("Grand Theft Auto VI" × "GTA 6") só cai no mesmo perfil se o nome estiver em `aliases`; cadastro com nome
já existente (inclusive alias) dá 409. (d) Missões só entram quando a lista é pública; **a semente do GTA VI traz 4
missões do vídeo "An Extended Look" com nomes descritivos, não oficiais** (jogo lança 19/11/2026, sem lista oficial):
pesquisar de novo depois do lançamento, sem apagar o jogo. Edição à mão em um idioma é traduzida para o outro; tradução
que falha deixa a outra versão como estava e `error` explica. Onde: `clipper/app/intel.py` (`import_seeds`,
`add_game`, `translate`), `main.py`, `db.py` (v12), `seeds/games/`; teste `clipper/tests/test_game_profiles.py`.
173. **Clipador: fonte em inglês sem transcrição (422 `language_not_supported` em todo bloco).** Causa: a fonte/sessão
guarda `en-US` (idioma do público), mas o serviço de voz só aceita `pt-BR`, `en` e `es`; antes de 18/11/2026 o idioma
gringo nunca tinha sido testado ponta a ponta. Correção: `worker.voice_language()` (`VOICE_LANGUAGES`) traduz na
fronteira, antes de mandar `X-Language`; idioma novo = entrada ali **e** em `WHISPER_LANGUAGES` de `voice/app/stt.py`.
Sintoma parecido: corte em inglês sem o português no painel = serviço sem reiniciar (item 144; banco precisa estar em
v13) ou corte anterior à mudança (use "Traduzir a fala" / `POST /v1/clips/{id}/translate`). Onde:
`clipper/app/worker.py`; teste `clipper/tests/test_english_source.py`.
174. **Clipador: Fontes mostrava "ao vivo" por checagem velha e parecia que a gravação estava na fonte errada.** Causa: a
coluna usava a última checagem do monitor (de 2 h antes) como se fosse agora; o Skipnho aparecia "ao vivo" enquanto a
sessão gravando era a do Tfue. Correção: a coluna mostra "gravando #N" da sessão ativa e trata checagem com mais de
10 min como "ao vivo há X" apagado. Onde: `panel/src/components/clipper-channels.tsx`.
## IA: provedores, login e reserva
Itens 168–172 e 175–179 informados em 18/11/2026 e conferidos contra `doc/ia.md` e o código. Contexto em [ai.md](ai.md).
168. **Gemini CLI com login Google: `IneligibleTierError: UNSUPPORTED_CLIENT`** (gemini-cli 0.68.0). Causa: o OAuth gratuito
"Code Assist for individuals" foi encerrado; o Google manda migrar para o Antigravity. OAuth só com plano elegível
(Code Assist Standard/Enterprise, Workspace). Correção: conta pessoal usa **chave do AI Studio** (`authMode: "apiKey"`).
O erro conta como indisponibilidade (`IneligibleTier`) e aciona a reserva. Onde: `panel/src/lib/ai.ts`, `doc/ia.md`.
169. **`CODEX_API_KEY` só vale no `codex exec`** (confirmado no binário 0.169.0). Para chave sem mexer na conta do usuário,
ponha a variável só na chamada (`providerEnv`); **não** use `codex login --with-api-key`, que troca o login global.
Mesma regra para `ANTHROPIC_API_KEY` e `GEMINI_API_KEY`. Onde: `providerEnv` em `panel/src/lib/ai.ts`.
170. **Terminal de login no Windows: aspas do `cmd` e caminho com espaço ("Program Files").** Forma que funcionou:
`cmd /d /c start "<título>" cmd.exe /k "<linha>"` com `windowsVerbatimArguments: true` (testado com caminho em
"Program Files"); sem o modo verbatim o Node reescreve as aspas (causa não isolada). Onde: `openLoginTerminal` em
`panel/src/lib/ai.ts`.
171. **Status das IAs lento (~0,3 s por chamada ao cofre).** Causa: a DPAPI no Node passa por PowerShell. Correção: cofre
em cache por `mtime` de `data/ai/vault.bin`; o Clipador lê com `ctypes` (`clipper/app/ai_settings.py`). Não leia o
cofre por requisição sem o cache.
172. **CLI instalada "não aparece" no painel.** Causa: o PATH do painel é o de quando ele abriu (instalação nova não entra),
e o instalador nativo do Claude usa `~/.local/bin` e o npm `%APPDATA%\npm`. Correção: `resolveCommand` procura nesses
dois lugares além do PATH; mesmo assim, instalar e não ver = "Verificar" de novo na tela. Gemini no Windows: o
`gemini.cmd` exige shell, então roda `node …/@google/gemini-cli/bundle/gemini.js` (mesma família do item 28).
175. **Gemini CLI: nem conta pessoal AI Pro/Ultra entra.** OAuth de conta pessoal encerrado em 18/06/2026; Code Assist
Standard/Enterprise sem assinatura nova desde 09/10/2026. Correção: chave do AI Studio ou o provedor `antigravity`
(conta Google; atenção aos termos, ver [ai.md](ai.md)). Complementa o 168. Onde: `doc/ia.md`.
176. **`/usage` no Git Bash vira caminho e a CLI cobra uma resposta normal.** Causa: o MSYS converte `/usage` em
`C:/Program Files/Git/usage`. Correção no terminal: `MSYS_NO_PATHCONV=1 claude -p "/usage"`. O painel chama sem shell
e não é afetado. `claude -p "/usage"` bem formado custa US$ 0 (`<synthetic>`). Onde: `panel/src/lib/ai-usage.ts`.
177. **`agy`: shell recusado em silêncio.** Só vale correspondência exata `command(<linha>)` em `--settings`; prefixo,
`command(node)`, `command(node:*)` e `command(node -e *)` não liberam. O que não está liberado vira passo `ERROR`
+ mensagem `jetski:` no stderr com **código de saída 0**: não confie no código, leia os eventos. Não use
`--dangerously-skip-permissions`. Onde: `antigravityArgs`/`normalizeAntigravity` em `panel/src/lib/agents.ts`.
178. **`codex app-server`: leitura de limites falha sem o handshake.** Ordem: `initialize` → notificação `initialized` →
pedido. `account/read` sem `params` dá "missing field `params`". Onde: `panel/src/lib/ai-usage.ts`.
179. **IA aparecia "pronta" sem estar.** Causa: último teste falhado por login/cota não tirava a IA da cadeia, e o Gemini
em modo conta contava como pronto sem teste. Correção: teste falho por indisponibilidade tira de `readyChain`;
Gemini em conta só depois de um teste que passou; "Testar" segue habilitado. Onde: `panel/src/lib/ai.ts`;
teste `ai.test.ts`.
Relacionadas, já registradas acima:
- Patch por script em arquivos CRLF do painel (`lib/metrics.ts`, `components/metrics-view.tsx`, `dashboard-controls.tsx`,
`app/dashboard/page.tsx`): item 63 — uma substituição com "\n" não acha o trecho; normalize e grave de volta em CRLF.
- `codex.cmd` sem shell: item 28.
- Script de patch com regex (`\b`) passado por heredoc: item 44.
- Publicador roda sem `--reload`: mudança em `publisher/app/` só vale depois de reiniciar o `pnpm dev` (itens 137, 139, 140, 142, 143, 145 e 147; o Clipador também: 144).
- Migração do painel (v3 … v10) é aplicada na 1ª requisição depois da recarga do `db.ts`; reiniciar o `pnpm panel`/`pnpm dev` só se isso não bastar: itens 51 e 138 (reiniciar mata agente em execução: item 131).