Squire

Squire

Squire es una capa transparente de ejecución local y verificación para agentes de codificación. Mantiene las lecturas comunes del repositorio en caché y verifica continuamente si el estado declarado del espacio de trabajo actual está confirmado.

El agente sigue usando comandos de terminal ordinarios. Antes de que Codex inicie un comando local de solo lectura, Squire comprueba el estado actual y o bien reproduce una observación mmap probada o ejecuta una operación acotada y pequeña sobre los bytes actuales del archivo verificados por hash. Un acierto válido devuelve exactamente stdout, stderr y el estado de salida. Cada fallo sigue la ruta de ejecución nativa original de Codex.

Instalación

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

El instalador verifica que los archivos de lanzamiento coincidentes de Squire y Squire-Codex sean correctos e instala el controlador, el asistente de runtime de Codex y el runtime nativo de Squire para el host en ~/.local/bin. No cambia la autenticación ni la configuración de Codex. Los hosts compatibles son macOS y Linux en amd64 o arm64.

Comprueba la instalación:

squire doctor

doctor sale con código distinto de cero cuando falta cualquier controlador, asistente, runtime o componente ABI requerido.

Uso

Inicia desde cualquier directorio:

squire codex

Ese es el camino completo del usuario. No hay comando de configuración, shim global de shell, cambio de prompt, herramienta MCP, inyección de precarga ni paso de aprovisionamiento de VM. Si Codex entra más tarde en un repositorio, Squire lo descubre y lo prepara desde el cwd real del comando.

squire-codex también se instala como comando directo de conveniencia.

Inspecciona el repositorio y el runtime actuales:

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

Verificación Continua

Squire Green ejecuta pruebas declaradas, lint, typechecks y compilaciones de forma nativa en segundo plano después de que los cambios del repositorio se asienten. Cada resultado está vinculado a los bytes de entrada declarados exactos, la configuración de comprobación, el entorno y el ejecutable. Una edición relevante posterior hace que ese resultado quede obsoleto; las ediciones no relacionadas no.

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

Los comandos proporcionados por el repositorio nunca se ejecutan en silencio en el primer uso. Revisa el archivo y confía en su hash exacto una vez:

squire green trust
squire verify

Cualquier cambio de configuración revoca la confianza. squire codex entonces programa comprobaciones de confianza automáticamente; no se requiere un segundo daemon ni un comando de calentamiento. Consulta docs/GREEN.md para la configuración y la semántica de prueba.

Qué Acelera

Los carriles de producción están acotados pero cubren la superficie común de comandos de solo lectura:

• Metadatos de Git: formas git rev-parse compatibles y descubrimiento de ramas.
• Lecturas de repositorio: formas git status, git ls-files y git diff compatibles, incluidos diffs con ámbito de ruta y git diff --check, además de historial git log -N --oneline -- <literal paths> acotado.
• Lecturas de archivos y búsquedas: cat acotado, sed -n ordenado de rango único o múltiple, head, tail, nl -ba, file, grep/rg de cadena fija, búsquedas rg de repositorio acotadas preparadas bajo demanda y formas ls estrictas.
• Descubrimiento de entorno: sondas de versión compatibles, which/command -v, printenv seguro, whoami, id, hostname y formas uname.
• Composiciones: planes completos de solo lectura sobre fuentes y filtros compatibles, incluidas tuberías, secuencias, redirección a /dev/null, head, tail, sed -n acotado, grep -F, wc -l y sort.

No se elimina ninguna operación. Compilaciones, pruebas, ediciones, instalaciones, comandos Git que mutan, expansiones, sintaxis de shell desconocida, sondas sensibles y variantes no compatibles siguen inmediatamente la ruta nativa sin cambios de Codex. Un fallo en frío seguro hace lo mismo mientras solicita una preparación exacta en segundo plano. rg --files permanece fuera de la política de preparación acotada y sigue la ruta nativa.

Los comandos compatibles se compilan en planes acotados tipados en lugar de plantillas de comando exactas. La prueba de fuente y la ejecución están separadas: una instantánea de archivo probada puede servir diferentes selecciones de líneas, filtros y composiciones sin una entrada de caché para cada cadena de comando. La misma representación de plan está implementada por el motor Go y el runtime nativo, manteniendo los operadores de lectura futuros aditivos mientras las pruebas diferenciales imponen paridad en el límite ABI.

Por Qué los Aciertos Son Actuales

Squire almacena en caché observaciones, no autoridad. Una reproducción en primer plano o bien recalcula las entradas que pueden afectar ese comando o reutiliza una huella criptográfica mientras un guardia completo kqueue/inotify informa que no hay cambios de dependencia. La época preparada debe seguir coincidiendo. Las entradas de prueba incluyen el comando y cwd normalizados, refs/índice/config de Git y archivos de comportamiento externos, estado relevante del espacio de trabajo, rutas canónicas, hashes de contenido, prueba de entorno específica del comando e identidad del ejecutable. El fallo del guardia siempre invalida la prueba residente.

Para lecturas de archivos acotadas, un desajuste de época puede usar en su lugar el carril de archivo actual: Squire conserva los bytes exactos leídos mientras calcula la prueba SHA-256 en primer plano y aplica solo su gramática de bytes fija a esos bytes. Esto no requiere recalentamiento y no persiste el archivo ni el resultado. La caché puede contener registros obsoletos, pero nunca se reproducen después de un desajuste de prueba. Estado faltante, corrupción, sintaxis no compatible, desajuste ABI o una prueba no rentable se convierten en respaldo nativo.

El conjunto de invalidación cambia los bytes del archivo sin cambiar el tamaño ni el mtime, muta el índice de Git y el conjunto no rastreado, cambia diffs del mismo tamaño, edita la configuración de Git, hace commits, renombra ramas, cambia los espacios de nombres de objetos sueltos y empaquetados, cambia las entradas de entorno y sondea enlaces simbólicos fuera del espacio de trabajo. Devolver bytes antiguos o un acierto inseguro falla el lanzamiento.

Consulta SQUIRE_CONTRACT.md para las invariantes completas.

Comprobación de Runtime Actual

El 16 de julio de 2026, una ejecución aleatorizada de 500 comandos con ABI de producción registró 421 aciertos exactos, 79 respaldos seguros, 468 comparaciones nativas, cero desajustes y cero aciertos inseguros. El p50/p95/p99 de aciertos fue 0.315/0.630/0.933ms; los mismos comandos se ejecutaron de forma nativa en 8.084/27.692/51.820ms. Un diferencial separado de 500 consultas de búsqueda en repositorio tuvo 500 aciertos exactos o equivalentes en orden y cero desajustes semánticos. El historial de ruta acotado fue 28/28 exacto con p50 de 0.333ms y p99 de 0.492ms frente a p50 nativo de 20.060ms. Las 2.048 llamadas estables fueron exactas con p99 de pared de 0.433ms. Bajo carga de ocho vías, el p99 de CPU fue 0.334ms; el p99 de pared con contención de programador fue 3.242ms.

Los tratamientos gpt-5.6-luna en vivo recientes reprodujeron de forma independiente 2/3 llamadas de Express (66.7%), 5/5 llamadas de Flask (100%) y 4/5 llamadas de fmt (80%). Cada tratamiento pasó la compuerta 50% de todas las llamadas de terminal con contabilidad válida y cero desajustes de diagnóstico. Estas pequeñas muestras en vivo validan la cobertura, no el tiempo de pared causal de la tarea completa; las trayectorias del modelo divergieron antes de ver los resultados de las herramientas.

Una prueba determinista de atribución de Codex con 40 pares mantuvo fijas las respuestas del modelo, los comandos, el espacio de trabajo y las cargas útiles del terminal. Seis llamadas seriales cayeron de 374.876ms a 103.600ms, ahorrando 271.277ms (72.4%, intervalo pareado del 95% 265.630-276.540ms). Dos lotes paralelos ahorraron 52.6%. Los órdenes AB y BA permanecieron positivos, mientras que los intervalos intercalados A/A y B/B incluyeron cero.

Metodología completa y tablas históricas: docs/BENCHMARKS.md.

Notas de arquitectura y backend: docs/ADVANCED.md.