Context

Long tasks - migrations, multi-file refactors, anything that will outlive a single context window or a single sitting. The longer the task, the more certain it is that the session dies partway through: context limit, crashed process, closed laptop, a model that stops producing sensible output.

Problem

An agent session is state held in a window. When the window is gone, the work is gone - not the files it wrote, but the reasoning about what it was doing and what remains. Restarting means re-deriving, and re-deriving invites divergence: the second attempt makes different choices than the first, and now the repository is a blend of two plans.

Pattern

An explicit progress artefact, updated as the run proceeds rather than at the end:

## Done
- src/parser.ts - split into lexer + parser, tests updated

## In progress
- src/renderer.ts - half migrated; `renderBlock` still uses old signature

## Remaining
- src/api/*.ts call sites
- delete legacy adapter

## Decisions
- Kept the old error type; ADR-014 still applies

Three properties make it work: it is written before the risky step rather than after, it records decisions and not just tasks, and it is small enough that resuming means reading one file.

Tradeoffs

The log itself consumes context and turns - the very resource the pattern is meant to protect. On short tasks it is pure overhead, and a stale log is worse than none: a resumed agent will follow instructions that describe a repository state that no longer exists.

When not to use it

Tasks that fit in one session. The signal is simple: if you would not bother to write down where you got to before lunch, the task does not need a checkpoint.