Como resolver quando o mise não fixa versões no Codex Cloud

mise install bun passou sem erros, mas bun voltou como command not found. Isso aconteceu usando mise no Codex Cloud.

Localmente, as versões estavam fixadas via .tool-versions e eu confiava nisso. No Cloud, essa configuração não é aplicada automaticamente.

Sintomas

As versões de bun e node fixadas divergem no Cloud. mise install bun é bem-sucedido, mas executar bun logo em seguida falha. Dependências também podem se desalinhar após a restauração do cache.

Se qualquer um desses casos ocorre, é provável que instalação e ativação no shell do mise estejam sendo confundidas.

Causa

O Codex Cloud não aplica .tool-versions nem .mise.toml automaticamente. Deixar como está, da mesma forma que no ambiente local, simplesmente não funciona.

A armadilha principal é o comportamento do mise install. mise install bun apenas baixa o binário, sem adicioná-lo ao PATH do shell. É preciso executar mise activate ou mise exec separadamente. Sem saber disso, command not found se repete indefinidamente.

Escrever no AGENTS.md para usar bun serve apenas como diretriz auxiliar. O setup do ambiente em si precisa ser controlado por outro mecanismo.

Resolvendo com setup.sh e maintenance.sh

Mudar a configuração do ambiente Codex Cloud para Manual setup e escrever os scripts por conta própria.

.tool-versions

bun 1.3.8
nodejs 25.6.0

.codex/cloud/setup.sh

#!/usr/bin/env bash

set -euo pipefail

mise use -g bun@1.3.8
mise use -g node@25.6.0

eval "$(mise activate bash --shims)"
bun install --frozen-lockfile

mise use -g registra as ferramentas globalmente, depois mise activate bash --shims as disponibiliza via shims no PATH. Separar em dois passos é o ponto-chave. Tentar resolver tudo com um único mise install falha.

.codex/cloud/maintenance.sh

#!/usr/bin/env bash

set -euo pipefail

bun install --frozen-lockfile

Este script roda após a restauração do cache. Ele assume que o PATH configurado pelo setup.sh ainda está ativo.

Procedimento operacional

Ativar Manual setup nas configurações de ambiente do Codex Cloud, indicar .codex/cloud/setup.sh como setup script e .codex/cloud/maintenance.sh como maintenance script. Resetar e recriar o cache do ambiente para que as mudanças entrem em vigor.

Como medida auxiliar, adicionar Use bun for install/run. Do not use npm unless explicitly requested. ao AGENTS.md.

Pontos de atenção

mise install sozinho não torna bun executável. mise activate ou mise exec é necessário. Sem montar a configuração com a premissa de que instalação e ativação no shell são etapas separadas, o mesmo problema se repete.

O setup script e os processos subsequentes rodam em sessões separadas. Configurações que dependem do PATH devem ser resolvidas dentro de cada script. Se bun não for encontrado no maintenance script, mise exec -- bun ... serve como contorno.

Conclusão

Para estabilizar o mise no Codex Cloud, preparar setup.sh e maintenance.sh próprios sob Manual setup e montar o PATH combinando mise use -g com mise activate. Não tentar resolver apenas com mise install.

Quando o Codex Cloud suportar imagens Docker customizadas, todo esse contorno pode se tornar desnecessário.