Squire

Squire

Squire é uma camada transparente de execução e verificação local para agentes de codificação. Ela mantém leituras comuns de repositório aquecidas e mantém continuamente se o estado atual declarado do workspace está verificado.

O agente continua usando comandos de terminal comuns. Antes de o Codex iniciar um comando local somente leitura, o Squire verifica o estado atual e reproduz uma observação mmap comprovada ou executa uma operação limitada sobre os bytes atuais do arquivo verificados por hash. Um hit válido retorna exatamente stdout, stderr e status de saída. Cada miss segue o caminho de execução nativo original do Codex.

Instalação

curl -fsSL https://raw.githubusercontent.com/reidgoodbar/squire/main/install.sh | bash

O instalador verifica arquivos de release correspondentes do Squire e do Squire-Codex e instala o driver, o auxiliar de runtime do Codex e o runtime Squire nativo do host em ~/.local/bin. Ele não altera a autenticação ou a configuração do Codex. Os hosts suportados são macOS e Linux em amd64 ou arm64.

Verifique a instalação:

squire doctor

doctor sai com código diferente de zero quando qualquer driver, auxiliar, runtime ou componente ABI necessário está ausente.

Uso

Comece de qualquer diretório:

squire codex

Esse é o caminho completo do usuário. Não há comando de configuração, shim global de shell, alteração de prompt, ferramenta MCP, injeção de preload ou etapa de provisionamento de VM. Se o Codex entrar em um repositório mais tarde, o Squire descobre e prepara esse repositório a partir do cwd real do comando.

squire-codex também é instalado como um comando direto de conveniência.

Inspecione o repositório e o runtime atuais:

squire status
squire status --json
squire explain -- git status --short

Verificação Contínua

O Squire Green executa testes declarados, lint, typechecks e builds nativamente em segundo plano depois que as edições do repositório se estabilizam. Cada resultado está vinculado aos bytes de entrada declarados exatos, à configuração de verificação, ao ambiente e ao executável. Uma edição relevante posterior torna esse resultado obsoleto; edições não relacionadas não o tornam.

# .squire/checks.toml
[[check]]
name = "tests"
command = ["go", "test", "./..."]
inputs = ["**/*.go", "go.mod", "go.sum"]
timeout = "10m"

Comandos fornecidos pelo repositório nunca são executados silenciosamente no primeiro uso. Revise o arquivo e confie no hash exato dele uma vez:

squire green trust
squire verify

Qualquer alteração de configuração revoga a confiança. squire codex então agenda verificações confiáveis automaticamente; nenhum segundo daemon ou comando de aquecimento é necessário. Consulte docs/GREEN.md para configuração e semântica de prova.

O Que Ele Acelera

As vias de produção são limitadas, mas cobrem a superfície comum de comandos somente leitura:

• Metadados Git: formas git rev-parse suportadas e descoberta de branches.
• Leituras de repositório: formas git status, git ls-files e git diff suportadas, incluindo diffs com escopo de caminho e git diff --check, além de histórico git log -N --oneline -- <literal paths> limitado.
• Leituras de arquivo e busca: cat limitado, sed -n ordenado de intervalo único ou múltiplo, head, tail, nl -ba, file, grep/rg de string fixa, buscas rg limitadas em repositório preparadas sob demanda e formas ls restritas.
• Descoberta de ambiente: sondas de versão suportadas, which/command -v, formas seguras de printenv, whoami, id, hostname e uname.
• Composições: planos completos somente leitura sobre fontes e filtros suportados, incluindo pipes, sequências, redirecionamento para /dev/null, head, tail, sed -n limitado, grep -F, wc -l e sort.

Nenhuma operação é removida. Builds, testes, edições, instalações, comandos Git mutáveis, expansões, sintaxe de shell desconhecida, sondas sensíveis e variantes não suportadas seguem imediatamente o caminho nativo inalterado do Codex. Um cold miss seguro faz o mesmo enquanto solicita preparação exata em segundo plano. rg --files permanece fora da política de preparação limitada e segue o caminho nativo.

Comandos suportados são compilados em planos limitados tipados, em vez de modelos exatos de comando. A prova de origem e a execução são separadas: um snapshot de arquivo comprovado pode atender a diferentes seleções de linhas, filtros e composições sem uma entrada de cache para cada string de comando. A mesma representação de plano é implementada pelo mecanismo Go e pelo runtime nativo, mantendo operadores de leitura futuros aditivos enquanto testes diferenciais impõem paridade na fronteira ABI.

Por Que os Hits São Atuais

O Squire armazena em cache observações, não autoridade. Uma reprodução em primeiro plano recalcula as entradas que podem afetar esse comando ou reutiliza uma impressão digital criptográfica enquanto uma proteção completa kqueue/inotify relata nenhuma mudança de dependência. A época preparada ainda deve corresponder. As entradas de prova incluem o comando e o cwd normalizados, refs/índice/config do Git e arquivos de comportamento externos, estado relevante do workspace, caminhos canônicos, hashes de conteúdo, prova de ambiente específica do comando e identidade do executável. A falha da proteção sempre invalida a prova residente.

Para leituras de arquivo limitadas, uma incompatibilidade de época pode usar a via de arquivo atual: o Squire retém os bytes exatos lidos enquanto calcula a prova SHA-256 em primeiro plano e aplica apenas sua gramática de bytes fixa a esses bytes. Isso não requer reaquecimento e não persiste o arquivo ou o resultado. O cache pode ainda conter registros obsoletos, mas eles nunca são reproduzidos após uma incompatibilidade de prova. Estado ausente, corrupção, sintaxe não suportada, incompatibilidade ABI ou prova não lucrativa tornam-se fallback nativo.

A suíte de invalidação altera bytes de arquivo sem mudar tamanho ou mtime, muta o índice Git e o conjunto não rastreado, altera diffs de mesmo tamanho, edita a config do Git, faz commits, renomeia branches, altera namespaces de objetos soltos e empacotados, muda entradas de ambiente e sonda symlinks fora do workspace. Retornar bytes antigos ou um hit inseguro reprova o release.

Consulte SQUIRE_CONTRACT.md para os invariantes completos.

Verificação Atual do Runtime

Em 16 de julho de 2026, uma execução aleatória de 500 comandos com ABI de produção registrou 421 hits exatos, 79 fallbacks seguros, 468 comparações nativas, zero incompatibilidades e zero hits inseguros. O p50/p95/p99 de hits foi 0.315/0.630/0.933ms; os mesmos comandos executaram nativamente em 8.084/27.692/51.820ms. Um diferencial separado de busca em repositório com 500 consultas teve 500 hits exatos ou equivalentes em ordem e zero incompatibilidades semânticas. O histórico de caminho limitado foi 28/28 exato com p50 de 0.333ms e p99 de 0.492ms versus p50 nativo de 20.060ms. Todas as 2.048 chamadas estáveis foram exatas com p99 de wall de 0.433ms. Sob carga de oito vias, o p99 de CPU foi 0.334ms; o p99 de wall com contenção de agendador foi 3.242ms.

Tratamentos gpt-5.6-luna ao vivo recentes reproduziram independentemente 2/3 chamadas Express (66.7%), 5/5 chamadas Flask (100%) e 4/5 chamadas fmt (80%). Cada tratamento passou no portão de todas as chamadas de terminal 50% com contabilidade válida e zero incompatibilidades de diagnóstico. Essas pequenas amostras ao vivo validam cobertura, não tempo de wall causal da tarefa inteira; as trajetórias do modelo divergiram antes de ver os resultados das ferramentas.

Um teste determinístico de atribuição do Codex com 40 pares manteve respostas do modelo, comandos, workspace e payloads de terminal fixos. Seis chamadas seriais caíram de 374.876ms para 103.600ms, economizando 271.277ms (72.4%, intervalo pareado de 95% 265.630-276.540ms). Dois lotes paralelos economizaram 52.6%. As ordens AB e BA permaneceram positivas, enquanto os intervalos intercalados A/A e B/B incluíram zero.

Metodologia completa e tabelas históricas: docs/BENCHMARKS.md.

Notas de arquitetura e backend: docs/ADVANCED.md.