A pausa publica o contrato, o app se registra, e o refine ajusta fora do pipeline

[davidbenal]

Segunda frente da Etapa 2 (PROD-2128), sobre o motor vendorado da #23. Três coisas que faltavam para o Crystal Ball rodar como app de verdade, cada uma no seu commit, CI verde entre um e outro.

1. A pausa publica seu contrato

state["pending_aceita"]/pending_campo_livre" (workflow_runner.py:382-383) já eram persistidos pelo runner, mas nada os publicava: run --json só devolvia step_id/prompt_to_user/options, runs --json não dizia o que uma pausa aceita, e não existia como consultar UMA run pausada por fora do stdout de quem a disparou.

contrato_persistido(state), extraída de _resolver_escolha, é a fonte única lida nos três lugares: o ramo pausado de run --json (ganha aceita/campo_livre), as quatro chaves pending_* novas de runs --json (pending_aceita, pending_campo_livre, pending_prompt, pending_opcoes — contagem, não a lista inteira, porque é endpoint de listagem), e o subcomando novo runs show <run_id> --json (que virou runs grupo + show, sem quebrar runs --json/--paused como comando plano — Click com invoke_without_command=True). Preserva o fallback de pausa gravada antes de pending_aceita existir no state, para nunca publicar null onde uma run de verdade está esperando resposta.

2. O manifesto registrado

templates/apps/crystal-ball.yaml não era citado por nenhum instalador, e Tracker.create_workflow é um INSERT puro contra slug UNIQUE (migrations/001_initial.sql:38) — registrar duas vezes estourava IntegrityError cru, o bug que o David batia ao registrar na mão.

Tracker.upsert_workflow faz INSERT ... ON CONFLICT(slug) DO UPDATE, e workflow save passa a usá-lo. studiolocal workflow install [SLUG] [--force] instala manifestos de templates/apps/: valida schema (WorkflowSpec.from_yaml) e o contrato de cada pausa human_pick — reusando _contrato_da_pausa, a MESMA checagem que o runner aplica em execução, não uma reimplementação — antes de gravar qualquer coisa. YAML já presente no root que diverge do template é preservado, a menos que --force; manifesto quebrado não grava nem arquivo nem linha no banco, e não impede os outros do catálogo de instalarem. install chama o catálogo no fim, sem force e silencioso, só no bootstrap (nunca em _ctx(), para não sobrescrever em silêncio uma edição manual a cada invocação).

3. studiolocal refine

Verbo novo: refine <run_id> --alvo <prompt_video|cena:N> --queixa "<texto>" [--json]. Entra pela conversa, depois que o pacote já existe — por isso o par alvo→função é fechado em Python (FUNCOES_POR_CONVERSA, espelhando FUNCOES_POR_MOTOR) e não no manifesto: o interpolador do runner é cego para índice de lista ({{ steps.pacote.prompts_de_cena.0... }} devolve None em silêncio — medido, decisão já tomada, não é para arrumar aqui).

lib/refinamento.py concentra a lógica. Recusa ANTES de qualquer chamada de rede ou escrita: status fora de done/paused (running ainda grava, failed não tem resultado), cena inexistente (lista os números disponíveis), run sem sessão (generations.session_id é NOT NULL). Escreve sempre no lugar canônico que as ui.vistas do manifesto leem (step_outputs.pacote.resultado...); rechama validar_prompt_video depois de refinar o prompt de vídeo, porque a função não revalida sozinha; marca nota_desatualizada e nunca recalcula a nota (_criticar é privada e cara) nem toca status/finished_at. Histórico append-only em state["refinamentos"], com antes para permitir desfazer manualmente.

Tracker.update_run_state_if_status faz a escrita atômica (UPDATE ... WHERE status = ?): uma mudança de status entre a leitura e a escrita não é sobrescrita em silêncio — a generation já criada fica registrada, e o comando sai com exit 2. marcar_custo_nao_apurado, extraída de workflow_runner.py:567-578, é a fonte única do cost_source='nao-apurado', chamada tanto pelo runner quanto pelo refine.

4. Teste que toca o motor vendorado de verdade

Todo teste do Crystal Ball até aqui troca o ReasonRouter por um duplo — nenhum carregava lib/motores/crystalball_llm.py de fato. O motor só importa stdlib mais requests, então carregá-lo em teste é offline e barato.

tests/test_motor_vendorado.py confere: o blob do arquivo bate com o hash declarado em PROVENIENCIA.md (mesmo método do git hash-object); carga.motor() registra _crystalball_motor em sys.modules e não toca sys.path; a assinatura real de cada função em FUNCOES_POR_MOTOR e FUNCOES_POR_CONVERSA aceita os argumentos que reason_engines.py/refinamento.py de fato passam; PESOS tem 7 chaves, soma 1.0 e é idêntico ao PESOS_REAIS copiado à mão em test_reason_engines.py; chave_ligada() restaura o ambiente mesmo quando o bloco levanta. README ganha os três verbos novos na seção de comandos.

Prova

pytest -q                                   319 passed   (280 de base + 39 novos)
ruff check . --select E9,F --output-format concise    All checks passed!

Desvios do plano

• Nenhuma assinatura real diverge do que o plano descrevia (regenerate_scene(contexto, cena), refine_video_prompt(prompt, complaint, biblia=None), Tracker.update_run(...) incondicional existente): tudo bateu com o código real.
• runs virou um click.Group (invoke_without_command=True) em vez de continuar click.Command, para caber runs show como subcomando sem quebrar runs --project/--paused/--json como estava. Não havia outra forma de encaixar os dois no Click sem isso.
• workflow install some da leitura de _apps_dir() (nova função) em vez de inline, para o teste do manifesto quebrado poder apontar para um diretório temporário via monkeypatch sem depender do conteúdo real de templates/apps/.

🤖 Generated with Claude Code