Aislamiento con Git Worktrees

El principio de Soberanía de Git es una de las garantías fundamentales de gz-ia: ningún agente de inteligencia artificial puede alterar de manera silenciosa o descontrolada el repositorio principal ni la rama de desarrollo activa (main/develop).

Para lograrlo sin sobrecargar el disco con clones completos, gz-ia emplea Git Worktrees.

---

¿Qué es un Git Worktree?

Un Git Worktree es una característica nativa de Git que permite tener múltiples árboles de trabajo vinculados a un único repositorio local (.git).

A diferencia de un git clone:

• Cero Duplicación de Historial: Todos los worktrees comparten el mismo objeto de almacenamiento (.git/objects).
• Creación Ultrarrápida: Se inicializan en milisegundos.
• Ramas Dedicadas: Cada worktree está vinculado a una rama independiente, evitando colisiones de cabeceras (HEAD).

---

Ciclo de Vida del Worktree en gz-ia

---

Estructura en Disco

Cuando se lanza una sesión con el ID a8f1b2c3, la estructura resultante dentro del proyecto es:

mi-proyecto/
├── .git/
├── .harness/
│   ├── sessions/
│   │   ├── a8f1b2c3.json              # Registro de la sesión
│   │   └── a8f1b2c3.events.jsonl       # Observabilidad y logger
│   └── worktrees/
│       └── a8f1b2c3/                  # Árbol de trabajo aislado
│           ├── cmd/
│           ├── internal/
│           └── ...archivos del proyecto...
├── cmd/                               # Tu espacio de trabajo intacto
└── internal/

La rama de Git creada para la sesión es harness/a8f1b2c3.

---

Flujos de Trabajo: read y get

Para interactuar con el código generado por el agente sin tener que cambiar de rama ni ensuciar tu directorio de trabajo, gz-ia proporciona dos comandos clave:

1. Inspeccionar Cambios: session read

Inspecciona el estado exacto del código dentro del worktree de la sesión sin tocar tu espacio de trabajo:

# Ver el diff completo producido por el agente
gz-ia session read a8f1b2c3

# Ver resumen numérico de archivos modificados, agregados y borrados
gz-ia session read a8f1b2c3 --stat

Diferencia entre session diff y session read

• gz-ia session diff <id> consulta directamente las diferencias git de la sesión.
• gz-ia session read <id> está optimizado tanto para humanos como para subagentes y herramientas MCP (worktree_read), retornando un formato estandarizado.

2. Traer e Integrar Cambios: session get

Una vez verificados los cambios del agente, session get fusiona el trabajo de la rama harness/<id> hacia tu rama de trabajo actual:

# Integrar los cambios directamente
gz-ia session get a8f1b2c3

# Integrar aplicando squash para resumir los commits del agente en uno solo
gz-ia session get a8f1b2c3 --squash

# Integrar sin generar commit automático (permite revisión en staging)
gz-ia session get a8f1b2c3 --no-commit

---

Destrucción y Limpieza Segura: session delete

Cuando la sesión finaliza o deseas descartar el experimento del agente:

gz-ia session delete a8f1b2c3

Este comando realiza una limpieza atómica y segura:

1. Verifica si el proceso del agente sigue activo (y lo detiene si es necesario).
2. Ejecuta git worktree remove --force .harness/worktrees/a8f1b2c3.
3. Elimina la rama efímera harness/a8f1b2c3.
4. Elimina la metadata de .harness/sessions/a8f1b2c3.json.
5. Si .harness/worktrees queda vacío, limpia el directorio contenedor.

---

Modo Fallback Transparente

Si ejecutas gz-ia dentro de un directorio que no es un repositorio Git (o si el comando git no está disponible en el entorno):

• gz-ia detecta automáticamente la condición.
• Registra IsWorktree = false en el SessionRecord.
• Ejecuta la sesión directamente en el directorio actual, notificando al usuario.
• Garantía: El arnés nunca interrumpe el flujo de desarrollo debido a la ausencia de Git.