Session closeout — leaving work someone can pick up

The work is not the expensive part any more. The expensive part is that almost all of the context around the work evaporates when the window closes.

A session ends holding things no file records. Which of three approaches you tried and why two failed. That the test you skipped was skipped for a reason. That a command is blocked on this machine and the workaround is two lines further down. Close the window and every one of those has to be rediscovered, usually by rerunning the failure that taught it the first time.

I noticed this because I kept paying for it. A checkout sat abandoned for hours while scheduled tasks kept committing onto the detached head of a stalled rebase, so the work was both dead and live at once. Another session "recovered" a branch and silently reverted sixty-seven lines that belonged to somebody else, because nobody had written down what the branch held before the recovery started. Neither was a hard problem. Both were unwritten state.

End in one of two states, and say which

A closeout is not "I stopped working." It ends in exactly one named state, and the name is the whole point, because an unnamed ending is indistinguishable from an abandonment.

READY. Everything the session owned is verified, pushed, documented, and resumable.

BLOCKED. Something is genuinely unfinished, and the handoff says precisely what, why, and what the next person should do first.

There is no third state. "Mostly done" is BLOCKED wearing a nicer shirt, and the cost of pretending otherwise lands on whoever opens the repository next, which is often me on a different machine.

What the handoff has to carry

Four things, and they are all boring, which is why they get skipped.

The SHAs. Not a branch name, not "pushed." The exact revision, because branches move and a branch name six hours later is a guess.

The evidence. Which gate ran, what it printed, what was not run. A closeout that says "tests pass" without saying which command produced that is a claim, not a receipt.

The loose ends. Everything you decided not to do, with the reason. This is the part that disappears first and is worth the most.

The resume instruction. The literal next command. Not "continue the migration." The command, with the path, so the next session starts by doing rather than by archaeology.

Clean only what you own

The rule that took me longest to learn: a closeout removes only what the session created.

When several agents hold worktrees on the same repository at once, a tidy-up pass is a loaded weapon. I have watched a cleanup filter match on a name and stop another lane's server mid-run. I have watched a teardown empty the main checkout's dependencies because workspace links point both ways. And in the hour before I wrote this paragraph I hid one of my own real posts by matching a string in a file's body when I meant to match a field in its header.

That last one is the general shape. The cleanup is never the interesting work, so it gets the least attention, and it is the step with the widest blast radius. Check what you are about to remove actually belongs to you, and write down what you are undoing before you undo it, because a reflog you took after the mistake is not a safety net.

Why this matters if you build with AI agents

You are going to run more sessions than you can hold in your head, and they cannot see each other. The only thing connecting them is what got written down, which makes the handoff the actual artifact and the code almost a side effect.

There is a second reason, less obvious. A model asked to write an honest closeout has to answer which rung it proved, what it skipped, and what it broke. That question is much harder to answer fluently than "summarize what you did," and the difference shows immediately. A session that cannot produce a clean closeout usually did not do clean work, and you learn that at the end of the session instead of at the start of the next one.

Write the closeout as if the person opening it has no memory of today, because in every way that matters, they do not.