Long-Job Checkpoints: How to Resume After an Interrupt
Long agent jobs outlive a single chat: sessions drop, quotas hit, tabs close, or subagents finish while the goal remains. Re-reading the scrollback is weaker than opening a checkpoint file in the work tree (or an agreed path) and resuming from it. A checkpoint is not a “chat backup”; it is the minimum state so the next turn keeps the same Goal and the same Next.
This post covers only where to save · the resume prompt · what context is lost. What to summarize each turn and progress-field templates belong to agent-context-budget. opencode --continue / --session / /compact belong to opencode-session-resume. Here the focus is file-based interrupt and resume that does not depend on a product session ID. No pricing, plans, or token counts.
Where should you save it?
One-line answer: Not in chat—save one file on an agreed path inside the work tree (e.g. docs/progress/, .agent/, or a ticket-id file). Omit secrets and long log bodies; keep Goal · Done · Next · Blocked · Paths only.
Recommended locations (pick one as a team):
| Location | When | Watch-outs |
|---|---|---|
docs/progress/<ticket>.md | You want it visible with PRs/reviews | Need cleanup/delete rules before merge |
.agent/checkpoint-<slug>.md | Agent/IDE-only; keep out of human PRs | Agree on .gitignore |
| Issue/ticket attachment | Heavy collaboration outside the repo | If the agent cannot read it, put the path in the prompt |
Worktree-root CHECKPOINT.md | Isolated work via git-worktree-agent | Back up before deleting the worktree |
When to write (checkpoint triggers):
- Right after a meaningful file change (one coherent create/edit/delete batch)
- Right after a test/build pass or fail (command + one-line result)
- Right after a direction change (one Decision line)
- Just before interrupt (quota, EOD, tab close, subagent handoff)
Do not write on every tool call. Noise makes resume worse.
Minimum schema (copy-paste):
# Checkpoint — <ticket-or-slug>
Updated: <ISO date or local stamp>
## Goal
- …
## Done
- [x] …
- [ ] … → move to Next
## Next (exactly one)
- …
## Blocked
- none | one-line repro / waiting on person or issue
## Decisions
- …
## Paths / commands
- `path` — why
- `command` — last good / failing
## Do not re-do
- Verified dead-ends and discarded approachesBoundary vs agent-context-budget: that post is per-turn summary fields while the session is long; this section is where you pin that state for an interrupt. Field names may overlap; path, triggers, and resume contract are this post’s core.
What is the resume prompt?
One-line answer: In a new chat (or session), make the agent read the checkpoint path first, restate Goal and Next, then run only the Next step. “Just continue” is nearly forbidden.
Resume prompt template:
Read `PATH/TO/CHECKPOINT.md` first. Do not scan the whole chat history.
1) Restate Goal and Next in one sentence each.
2) Execute ONLY the Next step. Do not expand scope.
3) After the step (or on block), update the same checkpoint file:
Done / Next / Blocked / Paths.
4) Stop and report: what changed, how to verify, what is still open.Practice rules:
- Write absolute and relative paths — cwd differs across worktrees and subdirs; relative-only often fails.
- Do not say only “continue” — if the model assumes prior chat, it hallucinates. The file is the source of truth.
- If Next has two+ items, a human collapses to one before resume — bloated checkpoints degrade resume quality.
- Subagent handoff — parent passes checkpoint path + success criteria only, not full chat (subagent-brief axis).
Boundary vs product session resume: opencode-session-resume is reattaching to the same tool’s session ID. When there is no session—or you switch products—you need this post’s file checkpoint + resume prompt. You can use both (session continue + file sync).
What context is lost?
One-line answer: Easy to lose: tool logs, mid-exploration, unconfirmed hypotheses. Recoverable without the checkpoint: git state, test commands, issue links. If decisions, unfinished Next, or failure repro are missing from the file, treat them as lost.
Loss table:
| Easy to lose | Leave in checkpoint | Recovery hint |
|---|---|---|
| Long tool output / stacks | One-line error + repro command | Log file path only |
| “Which files did we open?” | Core files under Paths | git status / diff |
| Chat agreements (“later”) | Decisions / Do not re-do | PR / issue comments |
| Partially applied edits | Done: applied vs unverified | git diff |
| Secrets / tokens | Never (names/paths only) | Secret manager |
Post-resume context audit checklist:
[ ] Checkpoint opens and Updated is recent?
[ ] Goal matches ticket/PR?
[ ] Next is exactly one? If two+, did a human collapse?
[ ] If Blocked: waiting on human/issue, or can the agent clear it?
[ ] Do Paths commands still reproduce? (check cwd)
[ ] Does git status match Done claims? (claim vs dirty/clean mismatch → fix)
[ ] No secrets / .env bodies in the checkpoint?If loss already happened: do not restore chat. (1) git status / git diff / recent commits, (2) re-run the failing command to reproduce, (3) re-pin Goal from the ticket in one line, then rewrite a fresh checkpoint. “Continue from memory” causes a second incident.
FAQ
How is this different from agent-context-budget?
That post is minimum per-turn summary fields and progress placement for long sessions. This post is the interrupt/quota/handoff resume contract (path, prompt, loss audit). Templates may overlap; axes differ.
How is this different from opencode-session-resume?
That post is opencode CLI/TUI session IDs, --continue, /compact. This post is a product-agnostic checkpoint file. Session resume is convenient when available; the file is the fallback.
Should checkpoints be committed to git?
Follow team rules. Commit under docs/progress/ if reviews should see them; use a gitignored .agent/ if local-only. Before commit, confirm no secrets landed in the file.
What if the agent finishes without updating the checkpoint?
Put “update the same file at step end or on block” in the resume prompt. At the human gate, if the file is empty, fill Done from git diff, then re-delegate. Do not resume from an empty file.
Sources
- Team practice: work-tree checkpoint file, read path first on resume, single Next step — templates above
- Adjacent axes: agent-context-budget (per-turn fields), opencode-session-resume (product session ID), subagent-brief (handoff brief), git-worktree-agent (isolated trees)