Passo de raciocínio, e uma retomada que confere o que o humano respondeu

[davidbenal]

Metade do esqueleto da Etapa 1 do Crystal Ball (Linear PROD-2127). A outra metade é a PR do Workbench, que consome o --json que esta PR cria.

O problema

Um app declarado tem passos cujo resultado é estrutura, não arquivo: um dossiê de pesquisa, cinco caminhos criativos, um diagnóstico. O runner não sabia representar isso. ProviderOutput só aceita url ou data (lib/provider_base.py:25-32) e _run_step assume arquivo em todo passo. E passo de raciocínio não podia virar generation com asset falso só para caber: asset draft acende "precisa de você" no kanban do Workbench e infla a contagem de entrega.

O que entra

Kind reason: grava a estrutura em runs.state, uma linha em generations, zero assets. O cost_brl=0.0 vem com cost_source: nao-apurado, porque zero sem procedência já produziu prejuízo antes.

Três consertos na retomada, todos encontrados ao tentar provar o mecanismo, e nenhum deles aparecia em teste porque não existe uma única run em nenhum banco desta máquina:

1. resume usava o session_id do parâmetro, e o CLI passava None (lib/cli.py:939). Com session_id or 0, a FK de generations.session_id era violada e a run inteira virava failed na primeira geração depois da pausa.
2. A escolha do humano era gravada crua. Qualquer --selected passava, inclusive um que nunca esteve nas opções. Agora a pausa persiste as opções e a retomada resolve a resposta contra elas.
3. Falha de step apagava o ponteiro e o trabalho já pago. Agora step_outputs sobrevive e a run falhada é retomável.

Mais: a pausa acende sessions.awaiting_input; from string vira uma opção, não uma por caractere; passo de mídia que declara output de estrutura falha alto; workflow save respeita o slug do YAML; run, workflow list e workflow show ganham --json; e studiolocal runs [--paused] é novo, porque o run_id só vivia no stdout de quem disparou.

Verificação

pytest -q, na raiz do repo:

194 passed in 2.77s

Sendo 7 novos em tests/test_workflow_app_steps.py e 187 que já existiam, nenhum alterado. O gate do ruff:

$ ruff check . --select E9,F --output-format concise
All checks passed!

Os 23 achados de estilo herdados continuam 23 (medido antes e depois com git stash): esta PR não acrescenta nenhum. Ficam num passo não bloqueante e declarado, porque seis deles pedem renomear exceção pública, o que é mudança de API e não cabe aqui.

Ponta a ponta, com geração real, no data root de desenvolvimento do Workbench

Disparo:

$ studiolocal run eco --project acme-verao-2027 \
    --inputs '{"palavra":"jabuticaba","tom":"neon","quantos":1,"observacao":"sem pessoas"}' --json
{"run_id": 1, "status": "paused", "session_id": 2, "cost_brl": 0.0,
 "step_outputs": {"eco": {"palavra": "jabuticaba", "opcoes": [...3 opções...]}},
 "step_id": "escolha", "prompt_to_user": "Qual eco de 'jabuticaba' vira imagem?"}

A pausa, como o kanban a lê:

sessao  awaiting_input  awaiting_reason                        coluna_gravada  rodando  drafts
2       1               Qual eco de 'jabuticaba' vira imagem?  por_fazer       0        0

awaiting_input=1 com rodando=0 e drafts=0 é a combinação que faz deriveColumn acender precisa_voce pelo gatilho certo. column_status continua por_fazer de propósito: a coluna é derivada, e o app nunca escreve nela.

Processo frio, e a recusa:

$ pgrep -fl "studiolocal run" || echo "nenhum processo studiolocal vivo"
nenhum processo studiolocal vivo

$ studiolocal runs --paused
run  status  workflow  project          sessão  passo pendente  início
1    paused  eco       acme-verao-2027  2       escolha         2026-08-22 21:43:53

$ studiolocal run eco --project acme-verao-2027 --resume 1 --selected '{"id":"inventada"}' --json
{"error": "'inventada' não está entre as opções da pausa em 'escolha': ['amanhecer', 'chuva', 'letreiro']"}
exit=2

Retomada válida:

$ studiolocal run eco --project acme-verao-2027 --resume 1 --selected '{"id":"chuva"}' --json
{"run_id": 1, "status": "done", "session_id": 2, "cost_brl": 0.68}

E o que ficou gravado:

id  session_id  run_id  step_index  kind    model                   status  cost_brl
3   2           1       0           reason  template/eco            done    0.0
4   2           1       2           image   nano-banana-pro-google  done    0.68

prompt: uma foto de jabuticaba sob chuva, tom neon (eco de jabuticaba)

id  kind   status  width  height  bytes    provider  cost_brl
5   image  draft   1024   1024    1137898  gemini    0.68

O prompt é a prova que interessa. A retomada recebeu só {"id":"chuva"}: as duas metades do texto, a frase da opção e a palavra jabuticaba, vieram de runs.state, de um processo que já tinha morrido. session_id=2 em vez de 0 é o conserto 1 funcionando, e antes dele a linha nem existiria.

O passo de raciocínio no ledger:

{"motor": "template", "step": "eco", "cost_source": "nao-apurado",
 "cost_gaps": ["passo de raciocínio: tokens não medidos"]}
assets do passo reason: 0

E a sessão não fechou ao gerar (closed_at nulo), que é o comportamento do Workbench e não o do CMS.

O que fica de fora, e vira issue

• Não existe reaper de generation pendente: se o processo morrer durante um passo reason longo, o card fica preso em "em geração".
• Não há expiração de run pausada (docs/DESIGN.md:554 já registrava).
• workflow validate não existe: a validação continua sendo só o prefixo do schema.
• O motor crystalball não entra aqui; o v1 do reason só conhece template. A Etapa 2 resolve.

🤖 Generated with Claude Code