@gitdamnit/checkpoint-orchestrator

Failure-resilient checkpointing for OpenCode — persistent task state, atomic writes, automatic persistence, and resumable AI workflows.

Prevents context loss when switching models or providers during a session. The next model picks up exactly where the last one left off.

Install

npm install @gitdamnit/checkpoint-orchestrator

Then register in your OpenCode config:

{
  "plugin": ["@gitdamnit/checkpoint-orchestrator"]
}

Or via CLI:

opencode plugin @gitdamnit/checkpoint-orchestrator

Tools Provided

Tool	Description
checkpoint_save	Save task state — deep-merges fields so partial updates never clobber. Accepts title, objective, status, summary, currentPlan, completedSteps, nextSteps, blockers, filesTouched, notes, and optional snapshotName to tag this save.
checkpoint_load	Load full current checkpoint state.
checkpoint_status	Quick status summary — exists, updatedAt, title, status, step counts, blockers count.
checkpoint_clear	Delete the checkpoint file entirely.
checkpoint_list	List all snapshot history entries newest-first with name, savedAt, title, and status.
checkpoint_load_snapshot	Read-only inspection of a named snapshot's full data.
checkpoint_restore_snapshot	Promote a named snapshot to live state. Automatically creates a pre-restore-{timestamp} undo point.

Automatic Persistence

The plugin uses three independent triggers to ensure state is never lost — no agent initiative required:

Trigger	Fires when	Behavior
A — session.compacted	Context window fills, OpenCode compacts	Re-saves existing state, or synthesizes a minimal checkpoint if none exists
B — chat.message	Every 5th user message	Re-saves existing state only (no synthesis). Counter resets on manual save.
C — checkpoint_save	Agent explicitly calls the tool	Primary save path. Full state from agent, optional snapshotName.

Triggers A and B are safety nets. Trigger C is the primary save path.

Automatic Context Injection

On session compacting, the plugin automatically injects the checkpoint state into the LLM's context with instructions to continue from where it left off. Deduplication prevents re-injecting unchanged state.

Test Suite

All 979 tests pass on Node.js 18, 20, and 22 in CI.

tests/checkpoint_smoke.js — 85 tests, 0 failed

Core save/load lifecycle, deep merge, partial updates, status progression, atomic write integrity, handoff generation, ring buffer pruning, snapshot naming, and auto-save counter threshold/reset.

tests/checkpoint_hardening.js — 77 tests, 0 failed

Category	Tests	Coverage
Security	4	Prototype pollution via __proto__, constructor.prototype, nested __proto__, and array payloads
Markdown injection	5	Script tags, code fences, image/link syntax all escaped
Fuzz	8	String/number/boolean/array/null/undefined incoming types
Stress	9	100 rapid merges, ring buffer at limits, all-fields-max payload
Edge cases	11	Double merges, all 4 status transitions, empty state, special chars, multiline, TOCTOU, missing version, missing directory
Atomic integrity	4	Temp file uniqueness, valid output, partial crash recovery
Handoff	30	All field fallbacks, nullish input, version checks, emoji prefixes, long content

tests/checkpoint_comprehensive.js — 817 tests, 0 failed

Section	Tests	Coverage
Part 1 — Property Fuzz	~600 (100 iters × 6 asserts)	Random titles, statuses, summaries, plans — verifies deep merge stability under random input combinations
Part 2 — Filesystem Lifecycle	13	Full create → save → load → handoff → clear cycle across 5 sequential saves
Part 3 — Recovery & Resilience	11	Corrupted JSON, corrupted history, missing directory with auto-mkdir, empty state file, missing handoff regeneration, mid-write crash survival
Part 4 — Atomic Write Verification	5	50 rapid temp-file writes with unique naming, zero leftover temp files, large payload (10KB fields, 500-item arrays) data completeness
Part 5 — Ring Buffer History	19	Exact boundary (10 entries), overflow pruning, empty/single edge cases, named vs auto snapshots, newest-first ordering
Part 6 — Deep Merge Combinatorial	32	All 16 status transitions, all 10 field types, partial field preservation, empty strings, null values, 3-step chained merges
Part 7 — Sanitization	21	6 XSS vectors (script, img, anchor, angle brackets, quotes), undefined/null/number/non-angle inputs, array sanitization, unicode (7 languages/charsets), full handoff injection context
Part 8 — Clamp Boundaries	20	String input: undefined/null/number/empty/exact/+1/way-over/max/max+1. Array: undefined/null/not-array/empty/exact/+1/way-over/max/max+1
Part 9 — Schema Versioning	13	Current version detection, v1 migration, v0 handling, missing version field, forward compatibility
Part 10 — Timestamp & Format	6	ISO 8601 format, Z/offset suffix, valid Date parsing, recency (within 5s), not in future
Part 11 — Stress	10	1000 rapid deep merges with title/step/note accumulation, 200 file saves with ring buffer verification, zero temp file leaks
Part 12 — Security	8	4 prototype pollution variants (__proto__, constructor.prototype, nested, array), 100K-element DoS, deeply nested payloads, injection in all handoff contexts
Part 13 — Snapshot Operations	5	Find by name, unknown name, pre-restore undo point creation
Part 14 — Handoff Structure	30	All 10 markdown sections present, correct numbering/counts, 10 empty-field fallback strings
Part 15 — Checkpoint Clear	5	All 3 files deleted, graceful handling when no files exist

Architecture & Storage

• Storage Location: .opencode/state/
  • checkpoint.json — current live state (atomic write: temp + rename)
  • checkpoint-history.json — ring buffer of last 10 snapshots (atomic write)
  • handoff.md — human-readable markdown mirror of live state (plain write, derived)
• Atomic Writes: Primary state files write to a temp file first, then rename to final path — prevents corruption on crash or power loss.
• Deep Merge: Saving merges task fields individually rather than overwriting. You can save title in one call and status in another without losing data.
• Deduplication: The session compacting hook tracks state hashes to avoid injecting the same context multiple times.
• Ring Buffer History: Every save appends a copy to checkpoint-history.json. History is pruned to MAX_HISTORY (default: 10) automatically — oldest entries fall off.
• Schema Versioning: Checkpoint data files include a version field for forward compatibility. Old files load with a warning rather than breaking.
• Handoff File: handoff.md is generated on every write in markdown format readable by any tool — aider, Claude Code, Codex CLI, or a text editor.