Worktrees y hooks de Git

Preparar un worktree para un agente de IA consiste en instalar las dependencias en su checkout, proporcionar su configuración ignorada y reservar puertos y una base de datos de pruebas propios del ticket. Una carpeta Git separada no separa los servicios de la máquina.

1. Activa los worktrees e inicia dos tickets independientes, A y B. Usa la ruta que devuelve Singularity para cada ticket; deja que la aplicación gestione las ramas y las carpetas.
2. Desde la raíz de cada checkout, ejecuta el comando del repositorio, por ejemplo pnpm install --frozen-lockfile en un proyecto pnpm. No compartas node_modules, las salidas de build ni las cachés modificables entre checkouts.
3. Vuelve a crear los archivos ignorados a partir de una plantilla sin secretos. Comprueba git check-ignore .env.local y git status --short. Proporciona los secretos con tu gestor habitual, sin copiarlos en un ticket, un log o un commit; no uses la base de datos de producción para las pruebas.
4. Asigna un puerto y una base de datos distintos: A usa 43101 y .local/ticket-a.sqlite, B usa 43102 y .local/ticket-b.sqlite. Para un servicio externo, usa dos bases de datos o esquemas de prueba y adapta las variables a tu aplicación.
5. Lanza las pruebas en los dos terminales al mismo tiempo. Un puerto ocupado debe hacer fallar la prueba; en ese caso, elige otro puerto libre y anótalo en el ticket. No mates un proceso desconocido.

Un ejemplo reproducible para dos tickets

Las instrucciones descargables instalan un pequeño proyecto Node 24+ con npm ci, sin dependencias de terceros. Descarga sus tres archivos en cada checkout: package.json, package-lock.json e isolation.test.mjs. Crea solo la configuración A en A, y la B en B.

# Checkout A: examples/worktree-setup/.env.local
TICKET_ID=ticket-a
PORT=43101
TEST_DB_PATH=.local/ticket-a.sqlite
# Checkout B: examples/worktree-setup/.env.local
TICKET_ID=ticket-b
PORT=43102
TEST_DB_PATH=.local/ticket-b.sqlite

npm test comprueba la respuesta HTTP del ticket y el propietario de su base de datos SQLite, con 1,5 segundos de solapamiento. La prueba cierra el servidor y la base de datos incluso si falla. Esta receta verifica el aislamiento de los recursos de este ejemplo, no todos los entornos de aplicación.

Detener, limpiar o secuenciar

Detén tus servidores de desarrollo antes de eliminar el worktree y borra únicamente las bases de datos de prueba de ese ticket. Conserva los cambios útiles antes de la limpieza de Git. Si dos tickets deben usar el mismo emulador, la misma base de datos o un puerto fijo, secuéncialos con una dependencia: A se detiene y libera el recurso antes de B. La cola de integración serializa los commits, no los servidores.

Estos comandos pertenecen al repositorio de ejemplo; no constituyen una API de preparación de Singularity. El worktrees.json de Cursor y los scripts de Superset o Conductor no se presentan aquí como configuraciones compatibles. Consulta los primeros pasos, la orquestación y el protocolo comparativo común.

Un worktree de Git es una segunda carpeta de trabajo vinculada al mismo repositorio. Tiene su propia rama y sus propios archivos extraídos, y comparte el historial de Git con la carpeta principal. Así puedes mantener abierta una modificación sin terminar en tu árbol habitual mientras otro trabajo avanza en otro lugar.

No es una copia completa del repositorio ni una rama abstracta sin archivos: las herramientas, las pruebas y los editores pueden abrirlo con normalidad.

Con el ajuste activo, cada ejecución de agente recibe su propio worktree en .singularity-worktrees/<uuid>/ y una rama dedicada. El flujo pide al agente que lea, modifique, pruebe y haga commit en esa carpeta, para separar sus cambios de tus archivos sin commit.

Esta separación reduce el solapamiento de archivos entre agentes. No constituye una restricción del acceso del proceso al resto del sistema.

No. Un worktree de Git es una carpeta de trabajo separada, no un sandbox del sistema. Por sí solo no bloquea ni la lectura ni la escritura en la carpeta principal, ni limita las conexiones de red. Un agente, un comando, una prueba o un hook puede acceder a otras rutas y servicios si los permisos del proceso lo autorizan.

Las restricciones efectivas dependen del CLI del proveedor, de su modo sandbox, de su política de aprobación y de los permisos del sistema. Comprueba las rutas autorizadas en lectura y escritura, el acceso a la red y las solicitudes de aprobación antes de lanzar el agente. En Settings → AI Providers, consulta las opciones del proveedor elegido: consulta los ajustes de los proveedores de IA, en particular el modo sandbox y las aprobaciones de Codex y las opciones de Gemini. Sus capacidades difieren; activar los worktrees no añade una protección universal del sistema.

1. Singularity crea el worktree a partir de la rama base del ticket.
2. El agente trabaja en la rama dedicada, verifica su trabajo y crea en ella sus commits.
3. Al final, Singularity vuelve a aplicar esos commits sobre la última versión de la rama base.
4. Según los ajustes del tablero, el resultado se integra automáticamente o se presenta en la pestaña Review.

La integración usa un rebase, no un merge. Los commits se reproducen sobre la base para conservar un historial lineal, sin commit de fusión. Si la base ha avanzado y aparece un conflicto, la ejecución sigue disponible para resolverlo.

Tickets paralelos y conflictos semánticos

La precualificación puede identificar dependencias entre tickets activos: si B depende de A, B espera a que A se integre. La cola de integración ordena los tickets de un mismo proyecto. Tras un rebase sobre una base que ha avanzado, el agente debe volver a ejecutar las pruebas afectadas y los controles del proyecto, y revisar las pruebas añadidas o modificadas por los otros tickets.

Que las pruebas pasen no garantiza la ausencia de conflictos semánticos. Dos solicitudes pueden imponer reglas incompatibles sin que haya un conflicto de Git. Precisa la regla compartida en los criterios de aceptación y prueba las interacciones. Una contradicción de negocio requiere una decisión; desactiva la fusión automática para conservar una revisión humana. Consulta el artículo sobre los tickets paralelos.

Abre Settings → Git → Worktrees para controlar el aislamiento. Mantén Use git worktrees activado para separar las carpetas y ramas de las ejecuciones. La fusión automática es independiente: desactívala si las ejecuciones terminadas deben esperar tu aprobación en la pestaña Review.

Cuando el aislamiento está desactivado, el agente escribe directamente en tu árbol de trabajo. No hay carpeta ni rama separadas, por lo que Singularity no tiene nada que presentar como trabajo aislado en Review.

En el navegador, abre la sección de worktrees del proyecto y después el menú correspondiente. Remove worktree borra su carpeta, pero conserva su rama y sus commits: su historial sigue siendo recuperable.

Clean up worktrees también elimina sus referencias de rama. Esta operación es irreversible. Comprueba que todo el trabajo útil se haya integrado o conservado en otro lugar antes de confirmar.

El detalle de un ticket muestra, en Work, el proyecto, la rama del worktree y su rama base. En la vista Git del navegador, la sección Worktrees del proyecto separa los worktrees sin fusionar y fusionados, con sus contadores. Despliega uno para ver su último commit y sus archivos modificados y, después, elige Merge into main…, Graph o Explore.

Explore abre el worktree en el explorador de archivos: recorres y abres los archivos que escribe el agente mientras trabaja, sin tocar tu propia copia. Cierra la exploración para volver a tu proyecto. Si la fusión entra en conflicto, consulta resolver un conflicto de Git.

Desde el cockpit Git de un proyecto, abre la pestaña Hooks para consultar los hooks detectados en el repositorio. Ejecutan los controles definidos por el proyecto en los momentos previstos por Git.

Si un hook pre-commit falla, el commit no se ha realizado. Corrige la causa indicada —formato, lint o una prueba, por ejemplo— y vuelve a lanzar el commit. Los archivos pueden seguir modificados o en el índice: comprueba su estado en el cockpit Git.

El panel Hooks lista todos los hooks de Git posibles; los que están instalados aparecen marcados, con su número de líneas. Singularity detecta Husky (core.hooksPath) y lee los hooks allí donde Git los ejecuta realmente. El menú de un hook ofrece Edit manually, Create a change ticket —un agente adapta el hook en su worktree—, chmod +x para un hook no ejecutable y Delete. Un hook que no existe puede crearse a partir de una plantilla.

En el compositor de commit, el indicador ⚡ seguido de un número anuncia los hooks que se ejecutarán. Su salida se muestra en un terminal; si un hook falla, el commit no se realiza: corrige la causa y vuelve a intentarlo.