O que os primeiros usuários do coldstart realmente quebraram

Testar sua própria ferramenta diz que ela funciona. O uso real diz como ela falha — e essas falhas se mostraram quase inteiramente listas diferentes.

Eu tenho lançado o coldstart de forma aberta há alguns meses, e a diferença entre "funciona quando eu uso" e "funciona quando um estranho a instala às 23h em uma máquina que eu nunca vi" se revelou a coisa mais útil que aprendi. Nada do que segue é hipotético — é retirado diretamente do histórico de lançamentos. Mensagens de erro reais, causas raízes reais, correções reais.

O primeiro bug foi a instalação em si

Antes que alguém pudesse me dizer que a ferramenta era útil ou inútil, a maioria deles teve que passar pelo npx coldstart-mcp init realmente finalizando. Não finalizou, por um tempo.

O sintoma era uma paralisação com efetivamente 100% de CPU por minutos, às vezes indefinidamente. A causa era quase cômica uma vez que a encontrei: dois pacotes de gramática tree-sitter declararam intervalos de dependência de pares conflitantes (^0.21.x vs ^0.22.x), e o resolvedor do npm, dado que não havia um lockfile para ancorar em um cache frio, simplesmente... girou. Eu encontrei mais de 89.000 linhas repetidas de placeDep ROOT no log de depuração sem convergência.

A primeira correção foi uma flag — --legacy-peer-deps — e documentação mais clara. Isso funcionou por um tempo, depois quebrou novamente de uma maneira diferente: __filename não está definido, uma incompatibilidade direta entre ESM/CommonJS que travou init antes que pudesse fazer qualquer coisa, porque os testes exercitaram o módulo diretamente e nunca tocaram o código real do caminho de instalação que quebrou.

A correção que realmente funcionou foi mais drástica: mover todo o motor de análise para WASM na v2.1.0. Sem compilação nativa de node-gyp, sem intervalos de dependência de pares de gramática para reconciliar, sem scripts de instalação. npm install -g coldstart se tornou uma instalação completamente comum. Esse é o padrão que aparece em toda essa lista — a primeira correção aborda o sintoma, a correção real remove a categoria de falha.

Um timeout que ninguém conseguiu reproduzir

Por um tempo, as pessoas relataram O servidor MCP "coldstart" teve a conexão expirada após 30000ms e eu não consegui fazer isso acontecer localmente, não importa o que eu tentasse.

A causa era invisível a menos que você fosse procurá-la especificamente: .mcp.json lançou o servidor via npx -y coldstart-mcp, e a cada inicialização, npx re-hashava toda a árvore de instalação — quinze pacotes tree-sitter, vários com binários nativos de vários megabytes — como parte da verificação de integridade da cadeia de suprimentos do npm. Isso levou de 25 a 30 segundos. O timeout do cliente MCP era 30. Não era instável; era uma corrida que dependia exatamente da velocidade do disco e da CPU de alguém, razão pela qual nunca se reproduziu na minha máquina e sempre acontecia na deles.

A correção não foi uma flag, foi reconhecer que npx era a ferramenta errada para um padrão de "lançar em cada sessão de editor" — é construída para scaffolding de uma única vez, não para servidores de longa duração. init agora faz a instalação cara uma vez, e depois escreve uma invocação direta de node /path/to/index.js. Inicialização em sub-segundos, sem envolvimento do npm após a configuração. Usuários existentes receberam uma auto-migração que reescreveu sua configuração no primeiro lançamento com a v1.4.0, backup com timestamp incluído, sem ação necessária.

O caderno que esqueceu coisas no meio da sessão

Esse só apareceu nas minhas próprias longas sessões, que é uma categoria de bug que é genuinamente difícil de pegar de outra forma.

O pipeline de captura fatiou a transcrição de um agente por um deslocamento de linha armazenado para saber o que era novo desde a última captura. /compact no Claude Code reescreve a transcrição para algo muito mais curto — e o deslocamento armazenado continuava apontando além do novo, final mais curto. Cada turno após uma compactação era silenciosamente invisível para captura pelo resto da sessão. Não era um erro, não era um aviso — apenas silenciosamente nada, exatamente nas sessões longas e complicadas o suficiente para serem as mais dignas de serem lembradas.

A correção foi um guardião de encolhimento: detectar quando a transcrição ficou mais curta que o deslocamento armazenado, redefini-lo, reprocessar a partir da nova base. Pequena correção, mas só existe porque eu estava usando a ferramenta em tarefas reais, bagunçadas e de longa duração — não o tipo de coisa que um teste unitário jamais revelaria, já que os testes unitários não rodam tempo suficiente para atingir /compact em primeiro lugar.

O recall era principalmente ruído, e eu medi exatamente quanto

Esse é o que mais me alegra que eu não apenas corrigi por intuição.

A reclamação, ao observar minhas próprias sessões, era que o recall — o recurso que traz automaticamente uma nota passada quando pode ser relevante — parecia estar injetando a coisa errada na maioria das vezes. Sentir que não é um critério de correção, então eu rotulei manualmente 140 injeções reais contra se eram realmente relevantes. Precisão base: 31%.

Três causas separadas, cada uma mensurável por conta própria:

• Correspondências de palavras comuns eram principalmente homônimos, não correspondências de tópico. "Mesclar o PR" trouxe uma nota de mesclagem de caderno. "Status 403" trouxe uma nota não relacionada chamada apenas "status." Essas foram 61% de todas as injeções, com 5% de precisão. A correção não foi um limite de pontuação ou uma lista de palavras de parada — eu tentei ambos, ambos falharam na validação retida — foi exigir um segundo sinal corroborante a menos que o termo fosse em formato de código ou explicitamente nomeado.
• A mesma nota ressurgiu repetidamente em uma sessão — no pior caso, doze vezes — um imposto puro, já que o conteúdo já estava em contexto desde a primeira injeção.
• A telemetria do harness estava vazando na consulta de relevância. Texto de wrapper de boilerplate como "enquanto executava comandos locais" era suficiente por si só para promover uma nota não relacionada duas classificações. O removedor para isso existia no código, mas nunca havia sido realmente enviado.

Após todas as três correções: 47% de precisão, mantendo 86% das injeções que eram realmente boas. Eu publiquei a caverna honesta ao lado disso — os números vêm do caderno de um repositório e do estilo de prompt de uma pessoa, e enquanto a regra se manteve em uma divisão retida, não estou afirmando que se generaliza para todos os códigos. É um progresso real, medido, não um número de marketing.

Feedback que não era um relatório de bug

Nem tudo veio de algo quebrando. A renomeação de coldstart-mcp para coldstart na v2.0.0 veio de uma realização mais lenta: os metadados antigos do pacote — descrição, palavras-chave — nunca continham a palavra "memória" de forma alguma, então ninguém procurando o que a ferramenta realmente faz poderia encontrá-la pesquisando por isso. Esse é o mesmo problema de desajuste de terminologia que escrevi sobre em outro lugar com SEO, aparecendo primeiro dentro do registro de pacotes, antes de aparecer nos resultados de busca.

Essa correção cascata em sua própria pequena comédia de erros de validação: o registro MCP rejeitou o primeiro server.json por uma descrição de 215 caracteres contra um limite de 100 caracteres; o npm truncou uma descrição separada no meio da palavra; e uma versão depois, a publicação falhou completamente com um 403 porque o registro concede direitos de publicação usando a exata capitalização do nome de usuário do GitHub, e a configuração tinha isso em minúsculas. Nenhum desses eram bugs interessantes. Todos eles eram o custo não glamoroso e necessário de realmente ser encontrável.

O que isso realmente me ensinou

Nada disso foi encontrado escrevendo mais testes antecipadamente, e eu não acho que poderia ter sido. Parte disso — o bug de compactação, o ruído do recall — só existe na textura de uma longa, real sessão, fazendo uma tarefa real, com o tipo de contexto que um caso de teste sintético não tem razão para construir. O resto — o timeout do npx, a capitalização do registro — só existe uma vez que você está lidando com infraestrutura que você não controla totalmente: verificações de integridade do npm, regras de autorização de um registro, alguém...