Worktrees

Revisa el estado de los worktrees de sesion, promuevelos o limpialos, y entiende que limpia el reaper automaticamente.

Objetivo#

Cada sesion despachada obtiene su propio worktree de git en la rama orch/<session> bajo paths.worktrees, aislado del checkout principal del proyecto. Aprende a inspeccionar, promover, y limpiar estos worktrees — y que es lo que orch ya hace por ti en segundo plano.

Pasos#

Lista cada worktree de sesion de orch para un proyecto:
```
orch worktree status [--project <path>] [--json]
```
Muestra la rama y ruta de cada worktree, marcado dirty (cambios sin commitear) u orphan (carpeta sin un registro de worktree de git que le corresponda). --project por defecto usa el proyecto de despacho registrado o la raiz del workspace; --base sobrescribe la rama base detectada.
Revisa la rama base resuelta a la que promote va a mezclar:
```
orch worktree base
```
Por defecto usa la variable de entorno ORCH_GIT_BASE, luego main/master auto-detectada.
Mezcla la rama de una sesion hacia la base:
```
orch worktree promote <session> [--strategy merge|rebase]
```
Falla en modo cerrado ante conflictos — nunca deja un arbol medio-mezclado, y nunca hace push a un remoto. --guard-ddl (activado por defecto) bloquea el promote si los archivos cambiados de la rama disparan el guard de DDL (una migracion sin un companero seeder/repository). --event (activado por defecto) emite un evento orch.git.promote sin contenido cuando el workspace esta vinculado.
Quita carpetas de worktree huerfanas y ramas orch/* huerfanas (limpieza segura, casi de solo lectura — nada con un registro de worktree de git vivo se toca):
```
orch worktree prune
```
Corre esto antes de promote si no estas seguro de que una carpeta siga rastreada.
Quita el worktree de una sesion especifica y su rama por completo:
```
orch worktree remove <session>
```

Lo que hace el reaper automaticamente#

El daemon limpia sesiones muertas en un reloj (daemon.reap_interval_sec en orch.yaml, por defecto 60s; 0 apaga el ciclo). Para cada sesion que encuentra abandonada:

libera cualquier fila de shared_locks que esa sesion tenia,
marca como fallida su fila de tarea en ejecucion,
y — solo para un checkout aislado (no in-place) — quita el worktree de la misma forma que lo haria un cierre normal.

No necesitas correr worktree remove o lock release tu mismo despues de una sesion que se cayo o fue matada; el siguiente ciclo del reaper (o el que corre de inmediato al arrancar el daemon) lo hace. orch worktree prune sigue existiendo para carpetas/ramas huerfanas que la contabilidad propia del reaper no cubre (ej. una carpeta que quedo de un rm manual equivocado).

Verificar#

orch worktree status

Vuelve a correrlo despues de un promote/prune/remove para confirmar que la entrada desaparecio (o que ya no esta marcada dirty/orphan).

Deshacer#

promote hace un merge/rebase de git real hacia la rama base sin auto-push — si mezclo lo que no era, deshazlo con git normal (git revert, o reinicia la rama base si aun no se ha subido). worktree remove/prune borran solo estado local; nada remoto se toca.

Relacionado#

troubleshooting.md — el reaper, sesiones abandonadas, y locks vencidos.
organise-a-workshop.md — donde vive paths.worktrees respecto a tus proyectos.