Compatibility and upgrades¶

v9.8.0 uses state format 8, as every v9 release before it did. Saved work from any earlier v9 release continues after the upgrade. v7.0.0 and v8.0.0 used state format 7, v6.0.0 through v6.3.0 used state format 6, v5.0.0 through v5.6.2 used state format 5, and v4.0.0 used state format 4. Saved work does not carry across from one format to the next.

Upgrade from v8.0.0 to v9.0.0¶

Before installing v9.0.0:

Decide whether you can start issue conversations and campaigns afresh. If you still need their saved context, postpone the upgrade.
Let every assignment finish its successful wrap-up and reach complete, or decide to finish its pull request yourself. v9.0.0 does not carry on an assignment that v8.0.0 started, and while its pull request stays open and linked to the issue, it claims the issue, so no new assignment starts there.
Stop the v8.0.0 dreamcatcher daemon and every standalone view, as Restart views across state formats describes.

The new release starts with empty local state in .dreamcatcher/v8/. It leaves .dreamcatcher/v7/ untouched but does not read it. Existing GitHub issues, comments and pull requests remain on GitHub.

A fresh conversation or campaign has read none of the issue's comments. If its issue still has a conversation or campaign label, the new conversation or campaign is given every comment you have posted on the issue, and dreamcatcher may answer them again.

There is no state migration. Once you have accepted the fresh start, run the new daemon normally from the same main checkout.

Upgrade from v7.0.0 to v8.0.0¶

v8.0.0 keeps state format 7, so saved work carries across. Stop the v7 daemon, install v8.0.0 and start the daemon again.

dreamcatcher view replaces dreamcatcher assignment, dreamcatcher conversation and dreamcatcher campaign, and stop and feed no longer take --assignment, --conversation or --campaign. Change any script or habit that uses them to name the work by GH<n> or by its agent work identifier, as the changelog describes.

Upgrade from v6 to v7.0.0¶

Before installing v7.0.0:

Decide whether you can start issue conversations afresh. If you still need their saved context, postpone the upgrade.
Let every assignment finish its successful wrap-up and reach complete, or decide to finish its pull request yourself. v7.0.0 does not carry on an assignment that v6 started, and while its pull request stays open and linked to the issue, it claims the issue, so no new assignment starts there.
Stop the v6 dreamcatcher daemon and every standalone view, as Restart views across state formats describes.

The new release starts with empty local state in .dreamcatcher/v7/. It leaves .dreamcatcher/v6/ untouched but does not read it. Existing GitHub issues, comments and pull requests remain on GitHub. To reclaim the disk it holds once you have finished with it, see Reclaim disk from an earlier state format.

A fresh conversation has read none of the issue's comments. If its issue still has a conversation label, the new conversation is given every comment you have posted on the issue, and dreamcatcher may answer them again.

There is no state migration. Once you have accepted the fresh start, run the new daemon normally from the same main checkout.

Upgrade from v5 to v6.0.0¶

Before installing v6.0.0:

Decide whether you can start issue conversations afresh. If you still need their saved context, postpone the upgrade.
Let every assignment finish its successful wrap-up and reach complete, or decide to finish its pull request yourself. v6.0.0 does not carry on an assignment that v5 started, and while its pull request stays open and linked to the issue, it claims the issue, so no new assignment starts there.
Stop the v5 dreamcatcher daemon and every standalone view, as Restart views across state formats describes.

The new release starts with empty local state in .dreamcatcher/v6/. It leaves .dreamcatcher/v5/ untouched but does not read it. Existing GitHub issues, comments and pull requests remain on GitHub. To reclaim the disk it holds once you have finished with it, see Reclaim disk from an earlier state format.

A fresh conversation has read none of the issue's comments. If its issue still has a conversation label, the new conversation is given every comment you have posted on the issue, and dreamcatcher may answer them again.

There is no state migration. Once you have accepted the fresh start, run the new daemon normally from the same main checkout.

Upgrade from v4.0.0 to v5.0.0¶

Before installing v5.0.0:

Decide whether you can start issue conversations afresh. If you still need their saved context, postpone the upgrade.
Let every assignment finish its successful wrap-up and reach complete. An assignment with no round running may still need feedback or wrap-up.
Stop the dreamcatcher daemon.

The new release starts with empty local state in .dreamcatcher/v5/. It leaves .dreamcatcher/v4/ untouched but does not read it. Existing GitHub issues, comments and pull requests remain on GitHub. To reclaim the disk it holds once you have finished with it, see Reclaim disk from an earlier state format.

A fresh conversation has read none of the issue's comments. If its issue still has a conversation label, dreamcatcher may treat existing eligible comments as new input and answer them again.

There is no state migration. Once you have accepted the fresh start, run the new daemon normally from the same main checkout.

Release compatibility¶

Beginning with v5.0.0, tagged releases follow Semantic Versioning:

A major release makes an incompatible change.
A minor release adds compatible functionality.
A patch release makes compatible fixes.

This promise covers documented commands, flags, configuration, saved agent work and agent obligations. Python internals, exact diagnostic wording and visual layout carry no stability promise.

An incompatible configuration or agent-contract change requires a major release. A state-format change also requires a major release because saved work does not continue automatically across formats. Every breaking change gets a changelog entry explaining its effect and what users must do before upgrading.

This policy does not assign compatibility promises to earlier releases. Untagged commits on main are development code and carry no release compatibility promise.

State format¶

The state format is an integer independent of the release version. A change that makes the structure or meaning of persisted records incompatible increments it; several releases may share one state format.

dreamcatcher reads and writes only the directory for its own format, and ignores other format directories without changing them. The daemon lock at .dreamcatcher/daemon.lock is shared across formats. v4.0.0 and earlier use .dreamcatcher/daemon.pid instead, so stop an older daemon before you start v5.0.0 or later.

A different format starts with empty local state. No migration is promised.

Restart views across state formats¶

A view reads only the records of its own state format. Running a view and a daemon that use different state formats is not supported, and the view may show stale status. dreamcatcher does not promise to detect the mismatch.

Before you install a release with a different state format:

Stop the old daemon. This also stops the web page that dreamcatcher run serves.
Stop every standalone view: dreamcatcher web, and any refreshing status, view or feed view, or before v8.0.0 any refreshing assignment, conversation or campaign view.

After you install it, start the daemon and any views you still want from the new installation. The restart depends on the state format, not the release version. Releases that share a state format read the same records.

Reclaim disk from an earlier state format¶

An earlier format's directory, .dreamcatcher/vN/, stays on disk with every worktree in it. dreamcatcher never deletes it, because a cancelled assignment's worktree in there is yours to work on. Once you have finished with that state, reclaim the space by hand from the main checkout, with N as the earlier format:

Look in .dreamcatcher/vN/worktrees/ for a cancelled assignment's worktree you still want. Commit any work in it that you want to keep. Its branch stays after the next steps, but uncommitted changes do not.
Delete the directory. On macOS and Linux run rm -rf .dreamcatcher/vN. In Windows PowerShell run Remove-Item -Recurse -Force .dreamcatcher\vN.
Run git worktree prune, so git forgets the worktrees you deleted and git worktree list no longer shows them.

Agent contract¶

The current agent contract is version 1. It covers assignment skills, conversation skills and campaign skills. Existing conforming skills remain compatible while the contract version stays the same.

The contract number is an integer independent of the release and state-format versions. A change that requires an existing conforming skill or prompt to change increments it; clarifications and editorial corrections do not. Version 1 documents the existing protocol rather than changing it. dreamcatcher does not negotiate the version at runtime.