Checkpoint Orchestrator v2.0.0

Checkpoint Orchestrator v2.0.0

Failure-resilient, session-isolated checkpointing for OpenCode. Task state is
persisted in SQLite so the next model, provider, or session can pick up exactly
where the last one left off.

This is a breaking release. The 1.0.1 line is unaffected and remains
installable for OpenCode V1 users.

Breaking changes

• Storage moved from project-level JSON to SQLite, and is now session-scoped.
  Checkpoints, snapshots, counters and dedup hashes are keyed by session id, so
  two sessions working in the same repository can no longer overwrite or inherit
  each other's state.
• OpenCode V2 is required. The plugin API moved from @opencode-ai/plugin
  (V1) to @opencode/plugin 2.0.21. V1 support is intentionally dropped: V1
  has no per-session tool context, so session isolation cannot be implemented
  correctly on it.
• The configuration key changed from plugin to plugins.
• Derived handoff exports and migration backups moved into the plugin's own
  namespace (.opencode/state/checkpoint-orchestrator/).
• engines.node is now >=22.13.0. node:sqlite is only available without
  --experimental-sqlite from Node 22.13.0 / 23.4.0.

Upgrade from 1.x

1. Install this version.
2. Change plugin to plugins in your OpenCode configuration.
3. Restart OpenCode. A .opencode/state/checkpoint.json that matches this
   plugin's schema is backed up and imported into a clearly named legacy
   namespace — not into any live session. Old data is never deleted, and the
   import never runs twice.
4. Run checkpoint_migrate to see what was found, then
   checkpoint_migrate { "adopt": true } in the session that should continue that
   work.

See docs/MIGRATION.md for the full path, including how to return to 1.x.

Install

{
  "$schema": "https://opencode.ai/config.json",
  "plugins": ["@gitdamnit/checkpoint-orchestrator"]
}

npm publication is pending explicit maintainer approval. The documented
npm install @gitdamnit/checkpoint-orchestrator currently resolves to 1.0.1,
not this release. Until 2.0.0 is published, install from this tag:

git clone --branch v2.0.0 https://github.com/gitdamnit/opencode-checkpoint-plugin
cd opencode-checkpoint-plugin && npm ci && npm run build
# then, in the project that should use it:
mkdir -p .opencode/plugins
ln -sf "$PWD/dist/checkpoint-orchestrator.js" <project>/.opencode/plugins/checkpoint-orchestrator.js

The publish workflow is manual-only, so creating this release did not publish
to npm. See docs/releases/v2.0.0.md for the publication status.

Tools

Eight tools: checkpoint_save, checkpoint_load, checkpoint_status,
checkpoint_clear, checkpoint_list, checkpoint_load_snapshot,
checkpoint_restore_snapshot, and checkpoint_migrate.

Every tool takes the calling session from the OpenCode tool context and every
query is scoped by session id.

Verified

• Docker Plugin Test Lab: 145 passed, 0 failed, 0 skipped at the tested
  release-candidate commit 65bf698, with Git That Shit 6069f91 and Stranger
  Danger 9cfd813, all three installed together in all six load orders plus a
  duplicate entry. Every plugin's tools registered in every configuration. The
  lab covered SQLite initialization and persistence, session isolation,
  concurrent writes, snapshot create/restore, legacy JSON migration, security and
  file permissions, failure isolation, automatic triggers, and real OpenCode V2
  execution through an offline model provider.
• 120 source-level tests drive the built dist/ output and the real V2 entry
  point.
• 22/22 real-runtime integration checks against opencode v2.0.21.
• Runtime: opencode v2.0.21, Node v22.23.3, Docker image
  sha256:76ebd805cd548a638b9b1508e5f16e680cd5b082cd3f3561d28f2f2301336ff1.

The release commit adds version metadata and documentation only; no functional
change was made after the tested commit. Full record:
docs/releases/v2.0.0.md.

Known limitations

1. node:sqlite may still produce an experimental API warning under plain Node.
   It is unflagged from Node 22.13.0 / 23.4.0, and Bun (the runtime OpenCode
   uses) does not warn.
2. OpenCode V2 is required; V1 is intentionally not supported.
3. SQLite checkpoints belong to their respective sessions and are never shared
   implicitly.
4. Legacy migration is deliberate and never automatically injects old data into
   an active session.
5. A compaction after clearing checkpoint state can create a non-injected
   synthesized placeholder.
6. The prompt hook is not an exactly-once event ledger.
7. Project identity and directory mapping have documented edge cases.

The complete list is in the README.