[P1][Release] Publicar e instalar versão com a correção de timeout do PR #232

[wesleysimplicio]

Contexto

O PR #232 corrigiu o comportamento de timeout no código-fonte do simplicio-mapper, mas a instalação global usada pelo operador ainda resolve simplicio-mapper 0.23.1. Assim, o fluxo operacional pode continuar executando o comportamento anterior até que uma nova versão seja empacotada, publicada e instalada no ambiente gerenciado.

Evidência reproduzível

Ambiente: Windows, 2026-07-17.

1. simplicio-mapper --version retorna 0.23.1.
2. origin/main contém o merge do PR fix(scan): bound synchronous workers and recover timeout #232 em 7db7105170c9af579719f9fc10df6c098e2061f6.
3. Executando o checkout que contém a correção, python -m simplicio_mapper.cli scan <repo> --json --sync --timeout 30 produz envelope simplicio.map-job/v1 com phase=complete, exit_code=0, sync=true, e o status --json retorna terminal=true, fresh=true, lock=false, warnings=[].
4. O executável instalado não possui uma forma verificável de declarar que já contém essa correção; a versão continua anterior ao merge e o Loop usa esse executável no PATH.

Impacto

• O operador pode iniciar o Loop com uma implementação anterior ao PR fix(scan): bound synchronous workers and recover timeout #232.
• A correção de WinError 6, recuperação de lock órfão e timeout bounded não é garantida no caminho real.
• O preflight Runtime/mapper fica inconsistente: o checkout validado está corrigido, mas o binário chamado por simplicio-loop pode não estar.
• Um run pode voltar a travar em mapping ou produzir evidência não comparável ao código mesclado.

Plano de implementação

1. Confirmar a política de versão e o mecanismo oficial de release do simplicio-mapper.
2. Incrementar a versão para uma release posterior a 0.23.1, preservando compatibilidade do CLI e do schema.
3. Gerar wheel/sdist em ambiente limpo.
4. Executar a matriz focada do PR fix(scan): bound synchronous workers and recover timeout #232:
   • scan síncrono completo;
   • timeout bounded com processo sobrevivente;
   • recuperação de lock com owner morto;
   • stdin=DEVNULL no worker Windows;
   • status --json terminal/fail-closed;
   • handoff --json somente quando os artefatos são frescos.
5. Publicar a release pelo workflow oficial, sem expor tokens em arquivos, argumentos ou logs.
6. Instalar a versão publicada no ambiente gerenciado usado pelo operador.
7. Verificar independentemente:
   • simplicio-mapper --version;
   • localização do executável;
   • import/metadata do pacote;
   • execução real do timeout no checkout simplicio-agent;
   • simplicio-loop preflight e handoff usando o binário instalado.
8. Registrar SHA, versão, artefatos, logs sanitizados e comando de rollback.

Critérios de aceite

• Existe uma versão publicada posterior a 0.23.1 contendo o merge fix(scan): bound synchronous workers and recover timeout #232.
• simplicio-mapper --version e python -m pip show simplicio-mapper apontam para a mesma versão publicada.
• O executável usado pelo PATH é o esperado pelo ambiente gerenciado.
• Timeout retorna em no máximo timeout + margem operacional, com phase=timeout, failure_reason=scan_timeout, exit_code=1, sem lock órfão.
• Scan que termina normalmente retorna phase=complete, exit_code=0, terminal=true, fresh=true, sem warnings.
• handoff --json retorna ready=true apenas para artefatos frescos.
• A matriz de regressão passa no ambiente suportado ou cada falha externa é isolada, reproduzida e registrada em issue própria.
• O próximo run real de simplicio-loop usa o binário publicado e deixa receipt verificável.
• A documentação de release/upgrade informa como detectar instalação defasada e como atualizar com segurança.

Fora de escopo

Não reabrir a implementação já mesclada do PR #232, salvo regressão demonstrada. Esta issue trata de empacotamento, publicação, instalação e prova do operador real.

[wesleysimplicio]

Preparação feita em #242 (branch `claude/simplicio-loop-skill-issues-d37464`):

• Versão incrementada para `0.23.2` em `pyproject.toml`, `package.json` e `simplicio_mapper/init.py` (`node scripts/check-version-sync.js` confirma alinhamento) — carrega o fix de fix(scan): bound synchronous workers and recover timeout #232 mais o hardening adicional de stdin/worktree-exclusion ([P1][Windows] Background/index worker falha com WinError 6 ao herdar stdin inválido #231, [P1][Performance] Excluir worktrees internos do escopo de mapeamento do projeto #234) deste mesmo branch.
• CHANGELOG atualizado, seção `0.23.2` datada.
• `python -m build` limpo gera `simplicio_mapper-0.23.2.tar.gz`/`.whl`; `test_cli_packaging.py` confirma que a árvore `contracts/` está incluída em ambos.
• Matriz focada do PR fix(scan): bound synchronous workers and recover timeout #232 (`test_lock_recovery.py` + `test_cli_coverage.py`, 18 testes) passa.

O publish real (twine upload, tag, GitHub Release, e instalação no ambiente gerenciado) ainda não foi executado — é uma ação irreversível em sistema compartilhado (registro público PyPI), e por instrução explícita do usuário só vai rodar mediante confirmação explícita dele no momento do merge/publish. Depois de #242 mergear, os passos restantes desta issue são: publicar pelo workflow oficial, instalar no ambiente gerenciado, e verificar independentemente (`simplicio-mapper --version`, `pip show`, execução real do timeout/lock no checkout `simplicio-agent`).

[wesleysimplicio]

Atualização: outra sessão preparou e mesclou o release 0.24.0 (#253, já em `main`), superando meu bump anterior para 0.23.2 — descartei minha versão em favor da deles ao reconciliar #242. #253 já cobre a preparação completa (build limpo, `twine check` passado, 90.48% coverage) e é mais abrangente que a minha (inclui #237/#238/#239/#240/#241/#243 no changelog).

Publish real (twine upload, tag, GitHub Release, instalação no ambiente gerenciado) continua não executado — mesma razão de antes: ação irreversível em sistema compartilhado, aguardando confirmação explícita do usuário/mantenedor.