Checkpoints e restauração

O que é um checkpoint, quando o AutoDev faz um, como listá-los e voltar a um, e o que uma restauração desfaz e não desfaz.

O que é um checkpoint #

Um checkpoint é um commit git que o AutoDev faz no seu repositório, na branch em que você está. O assunto dele é autodev: <label>. O autor é autodev <autodev@localhost>, então funciona num repositório sem user.name configurado, e ele pula os hooks de commit.

Um checkpoint guarda tudo, exceto .autodev/. Uma restauração existe para voltar o código, e voltar o memory.md junto apagaria o que a execução aprendeu no caminho.

Cada checkpoint também tem uma entrada em checkpoints.json, guardado na máquina junto com o resto do estado da execução. A entrada tem um id como c1 ou c2, o commit completo, um rótulo, um tipo e um horário. A lista abaixo lê desse arquivo.

Checkpoints precisam de um repositório git. Numa pasta que não seja um, o AutoDev escreve Not a git repository; checkpoints/rollback disabled (git init to enable recovery snapshots) e segue sem eles. A chave checkpoints os desliga, e vem ligada por padrão. Todas as chaves de configuração a descreve.

Quando um é feito #

Há três tipos:

• baseline: quando uma execução começa, se a árvore de trabalho tem mudanças não commitadas, o AutoDev as commita como autodev: baseline before run. Uma árvore limpa não recebe baseline.
• task: quando o work_done de um participante é creditado. Se as mudanças não estão commitadas, o AutoDev as commita como autodev: thread — <primeira linha do post>. Se o participante já commitou, esse commit é o checkpoint. Um turno que a aprovação de um gate iniciou é registrado do mesmo jeito.
• pre-restore: uma restauração registra o trabalho que substituiu, para que a própria restauração possa ser desfeita.

Mais um caso faz um commit e uma branch, e não é um checkpoint. Quando o trabalho falha depois de uma ação irreversível aprovada, o AutoDev estaciona a árvore numa branch chamada autodev/parked-<time> e não a volta, já que a árvore pode mostrar uma ação que não dá para desfazer. A execução para como error.

Listá-los #

autodev restore sem id lista os checkpoints, do mais novo ao mais antigo:

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

A marca no começo da linha é ─ para um baseline, ✔ para um task e ⤿ para um pre-restore. <task> é — para um checkpoint que não pertence a nenhuma tarefa, o que vale para todos os que uma thread faz hoje. A linha do checkpoint em que o repositório está termina com ← HEAD. Com os checkpoints desligados, a lista diz isso no lugar.

No painel, o botão Restore mostra a mesma lista. Clicar numa linha volta a ela, e o clique é a confirmação. O resultado aparece como Restored to "<label>", ou como Restore: <reason> quando falhou.

Voltar #

autodev restore <id> volta o código àquele checkpoint, nesta ordem:

1. Se a árvore tem mudanças não commitadas, o AutoDev as commita e as põe numa branch chamada autodev/pre-restore-<time>. Uma árvore limpa é resetada direto.
2. Ele roda git reset --hard até o commit do checkpoint.
3. Ele acrescenta uma entrada pre-restore para o trabalho que estacionou, para que a lista possa desfazer a restauração.
4. Ele põe o status em idle e limpa a tarefa atual.
5. Ele anexa uma linha RESTORE: ao memory.md, para que o próximo turno saiba que o código voltou.

Ele imprime Restored to "<label>" (<7 caracteres do commit>); saved on <branch>., e omite a branch quando a árvore estava limpa. Um id errado imprime Restore failed: unknown checkpoint: <id>. Se o git não consegue estacionar o trabalho nem resetar, nada é voltado, e o trabalho que você tinha fica onde estava.

O que ela não faz #

• Ela recusa enquanto um daemon está rodando: Stop the run before restoring — restore resets the project tree. O Restore do painel fica desabilitado com only while the run is stopped, e o New run também. Quando uma execução parada tem checkpoints, Needs you diz <n> restore point(s) — rewind now that the run is stopped.
• Ela volta o git e nada mais. Não volta o thread.jsonl, o events.jsonl, as sessões nem o memory.md. A thread guarda todos os posts, inclusive os sobre trabalho que já não existe, e o memory.md ganha uma linha. Um participante que lê os dois vê o código de antes da restauração e o relato do que aconteceu depois dela.
• Ela não desfaz o que aconteceu fora do repositório. Uma ação irreversível que um gate aprovou continua feita.
• Se o checkpoints.json se perde, a lista fica vazia, e os commits continuam no git sob os assuntos autodev:. Nada da execução se perde com ele.

Todos os comandos da CLI descreve autodev restore. O que sobrevive a um reinício trata dos outros arquivos, e Onde o estado fica os lista.