Upgrade to stable 0.1.1
This guide moves an existing workspace to the stable 0.1.1 package. The runtime is identical to 0.1.0 (and to 0.1.0-rc.3); 0.1.1 is a documentation and npm presentation patch. The public prerelease history remains 0.1.0-rc.2 and 0.1.0-rc.3.
Node must be >=22.23.4; supported OpenCode hosts are 2.2.6, 2.2.7, and 2.3.0. Pin the exact package version rather than a floating tag.
Before you upgrade
- Record the current install:shKeep the local path or the exact prerelease version that is currently installed.
opencode --version node --version opencode plugin list - Back up durable state:shSee backup and restore. The file contains conversation content; keep it private.
npm run backup -- export --out ./ensemble-backup.json "$PWD" npm run backup -- status "$PWD" - Stop the OpenCode host. The plugin and its RPC surface are replaced on the next start; there is no in-place hot swap.
- If a workspace has uncommitted
.ensemble/config.jsonedits, decide whether they belong in the backup before restoring anything later.
Install stable 0.1.1
opencode plugin add @heyimteee/ensemble@0.1.1
opencode plugin listExpected entry:
ensemble.v2 0.1.1 @heyimteee/ensemble@0.1.1The package entry replaces a linked checkout or older plugin entry. A restart is required after the install. opencode plugin check reports updates and opencode plugin update applies them deliberately; do not use a floating tag in a shared instruction.
What happens on the first start
Durable state lives under the v2/ storage prefixes. There is no separate store schema number and no destructive rewrite: the first start reads the same rows, applies additive defaults, and writes only what a later mutation needs.
| Change | Behavior | Evidence |
|---|---|---|
| Native-first default | nativeFirst: "on" is persisted once when the meta row has no valid mode. An explicit off or shadow is preserved and is never flipped. | #240 |
| AGENTS v7 contract | The <!-- ensemble:start v7 --> block is reconciled in place. Content and version are compared; project content outside the block is preserved; a newer recorded version is never downgraded. | #238, #253 |
| Native state refactor | One NativeIngestionState value per session replaces the split trackers. Bindings are re-indexed, and a start reconciliation repairs missing turn rows without re-running work. | ADR 0010, #231, #218 |
| Durable dispatch ledger | Rows without a group synthesize one from the root ancestor; budgets are granted on first save. | #160 |
| Direct transcripts | Pre-channel v2/dm/ direct rows merge into conversation channels once; the merge is idempotent. | #226 |
| Legacy v1 agents | A pre-v2 ensemble.state row migrates agents that are not already present. | v2 migration |
| Init job phases | A stored single phase is read as the last phases entry and rewritten on the next advance. | #118 |
| Lease recovery | working rows are not rewritten on load. The lease-aware reaper and waiting-work repair decide what can run. | #148 |
The roster table in AGENTS v7 writes member names, titles, and roles into the workspace file. If a repository is public, review those fields before the first commit that includes the block. The disclosure policy and the guidance for disabling or limiting it are in Data classes, retention, export, and delete.
Verify the upgrade
- Start the host and open the workspace.
- Confirm the plugin entry and the diagnostic read:shZero mismatches means storage, bindings, and
npm run doctor -- "$PWD".ensemble/config.jsonagree. A package-only install has nonpmscripts; use/ensembleand the in-app:logsviewer instead. - Send one group message and confirm one turn, one work item, and one final row. Confirm
$Namerouting behaves as documented. - Confirm the AGENTS block is v7 and that project content outside the markers is intact.
- Keep the pre-upgrade backup until the workspace has run successfully for a full session.
If the upgrade is wrong
- Bad package or host incompatibility: package rollback.
- State damaged or the wrong team restored: run
backup.rollbackfor the automatic slot, orbackup.restorewith the pre-upgrade file. - A failed restore is expected to leave the previous state running; see the recovery codes in backup and restore.
Historical prerelease installs
These commands remain valid only when you deliberately need the prerelease history. 0.1.0-rc.2 was the first public prerelease; 0.1.0-rc.3 is the latest prerelease and stays on npm next.
opencode plugin add @heyimteee/ensemble@0.1.0-rc.2
opencode plugin add @heyimteee/ensemble@0.1.0-rc.3The 0.1.1 release notes record the stable promotion; the rc.2 release notes remain the historical prerelease record.