Checkpoints y restauración

Qué es un checkpoint, cuándo AutoDev hace uno, cómo listarlos y volver a uno, y qué deshace y qué no deshace una restauración.

Qué es un checkpoint #

Un checkpoint es un commit de git que AutoDev hace en tu repositorio, en la rama en la que estás. Su asunto es autodev: <label>. Su autor es autodev <autodev@localhost>, así que funciona en un repositorio sin user.name configurado, y se salta los hooks de commit.

Un checkpoint guarda todo menos .autodev/. Una restauración existe para devolver el código, y devolver memory.md con él borraría lo que la ejecución aprendió por el camino.

Cada checkpoint también tiene una entrada en checkpoints.json, guardado en la máquina junto con el resto del estado de la ejecución. La entrada lleva un id como c1 o c2, el commit completo, una etiqueta, un tipo y una hora. La lista de abajo lee de ese archivo.

Los checkpoints necesitan un repositorio git. En una carpeta que no lo sea, AutoDev escribe Not a git repository; checkpoints/rollback disabled (git init to enable recovery snapshots) y sigue sin ellos. La clave checkpoints los apaga, y viene activada por defecto. Todas las claves de configuración la describe.

Cuándo se hace uno #

Hay tres tipos:

• baseline: cuando una ejecución empieza, si el árbol de trabajo tiene cambios sin commit, AutoDev los confirma como autodev: baseline before run. Un árbol limpio no recibe baseline.
• task: cuando el work_done de un participante se acredita. Si los cambios no están confirmados, AutoDev los confirma como autodev: thread — <primera línea de la publicación>. Si el participante ya hizo commit, ese commit es el checkpoint. Un turno que inició la aprobación de un gate se registra igual.
• pre-restore: una restauración registra el trabajo que reemplazó, para que la propia restauración se pueda deshacer.

Un caso más hace un commit y una rama, y no es un checkpoint. Cuando el trabajo falla después de una acción irreversible aprobada, AutoDev aparca el árbol en una rama llamada autodev/parked-<time> y no lo devuelve, ya que el árbol puede mostrar una acción que no se puede deshacer. La ejecución se detiene como error.

Listarlos #

autodev restore sin id lista los checkpoints, del más nuevo al más antiguo:

✔ <label>   <task> · <sha> · <mode> · <age>

La marca al inicio de la línea es ─ para un baseline, ✔ para un task y ⤿ para un pre-restore. <task> es — para un checkpoint que no pertenece a ninguna tarea, que es el caso de todos los que hace un hilo hoy. La línea del checkpoint en el que está el repositorio termina con ← HEAD. Con los checkpoints apagados, la lista lo dice en su lugar.

En el panel, el botón Restore muestra la misma lista. Hacer clic en una línea vuelve a ella, y el clic es la confirmación. El resultado aparece como Restored to "<label>", o como Restore: <reason> cuando falló.

Volver #

autodev restore <id> devuelve el código a ese checkpoint, en este orden:

1. Si el árbol tiene cambios sin commit, AutoDev los confirma y los pone en una rama llamada autodev/pre-restore-<time>. Un árbol limpio se resetea directamente.
2. Ejecuta git reset --hard hasta el commit del checkpoint.
3. Añade una entrada pre-restore para el trabajo que aparcó, para que la lista pueda deshacer la restauración.
4. Pone el estado en idle y borra la tarea actual.
5. Añade una línea RESTORE: a memory.md, para que el siguiente turno sepa que el código volvió atrás.

Imprime Restored to "<label>" (<7 caracteres del commit>); saved on <branch>., y omite la rama cuando el árbol estaba limpio. Un id equivocado imprime Restore failed: unknown checkpoint: <id>. Si git no puede aparcar el trabajo ni resetear, no se devuelve nada, y el trabajo que tenías se queda donde estaba.

Lo que no hace #

• Se niega mientras un daemon está en marcha: Stop the run before restoring — restore resets the project tree. El Restore del panel queda deshabilitado con only while the run is stopped, y New run también. Cuando una ejecución detenida tiene checkpoints, Needs you dice <n> restore point(s) — rewind now that the run is stopped.
• Devuelve git y nada más. No devuelve thread.jsonl, events.jsonl, las sesiones ni memory.md. El hilo conserva todas las publicaciones, también las de un trabajo que ya no existe, y memory.md gana una línea. Un participante que lee ambos ve el código de antes de la restauración y el relato de lo que pasó después.
• No puede deshacer lo que ocurrió fuera del repositorio. Una acción irreversible que un gate aprobó sigue hecha.
• Si checkpoints.json se pierde, la lista queda vacía, y los commits siguen en git bajo sus asuntos autodev:. Nada de la ejecución se pierde con él.

Todos los comandos de la CLI describe autodev restore. Qué sobrevive a un reinicio trata de los otros archivos, y Dónde vive el estado los lista.