Skip to content

Ensemble 0.1.0-rc.2 release notes ​

Status: published prerelease. 0.1.0-rc.2 is live on npm and as GitHub release v0.1.0-rc.2, marked prerelease. This note describes the published artifact, its public-registry install smoke on Linux, and the macOS checks. A launch announcement remains a separate decision.

Ensemble is a persistent agent team inside OpenCode. One plugin package carries the server that owns state, routing, Work, native sessions, and RPC, plus the TUI workspace and the /ensemble route. This is the first public package release, published as a prerelease.

Release identity ​

ItemValue
Package@heyimteee/ensemble
Version0.1.0-rc.2
LicenseMIT
Supported OpenCode2.2.6, 2.2.7, and 2.3.0 (Linux/tmux)
OpenCode peer range`2.2.6
Node floor22.23.4; live suites use 26.12.1
npm dist-tagslatest: 0.1.0-rc.2, next: 0.1.0-rc.2
Public release tagv0.1.0-rc.2 (GitHub prerelease)
Public releasehttps://github.com/heyimteee/ensemble/releases/tag/v0.1.0-rc.2
Verification tagrc-0.1.0-rc.2 (evidence base at d74fc3d; it predates the #281–#284 fixes)

The published version is 0.1.0-rc.2. The release workflow published with --tag next, but npm requires a latest tag and rejects deleting it (npm dist-tag rm ... latest returns E400). Because this is the first and only published version, latest necessarily points at the RC as well. Pin the exact version for deliberate installs; a later stable release will move latest.

What is in this release ​

  • MIT-licensed package identity with a runtime-only dist/ tarball.
  • A compiled server, TUI, and RPC package; the TUI uses the Solid OpenTUI transform and resolves its runtime dependencies from the plugin cache.
  • A clean-install proof against isolated OpenCode 2.2.7 hosts: six native Ensemble tools, the installed TUI route, and the /ensemble command.
  • Security and privacy work: threat model, permission-model review, accepted risks, supported-version security policy, Dependabot updates, scoped data export and delete, and the AGENTS v7 roster disclosure guidance.
  • Backup/restore, upgrade, and package/state rollback procedures, including a rehearsed failed-restore path.
  • A tag-driven release workflow with a token-free dry run, npm provenance, a CycloneDX SBOM, and changelog-based GitHub release notes.
  • macOS/Herdr verification of the installed package through SSH, including the deterministic fake E2E and the full manual checklist. 1.7 passes with a pane-bounded Shift+drag and explicit copy; automatic copy-on-release is a host preference and is not claimed. macOS/Herdr is verified on OpenCode 2.2.7 only.
  • OpenCode 2.3.0 support: Linux host probe 14/14, size matrix, deterministic fake E2E, and loopback install. The compatibility matrix and required context include 2.3.0. (#286)
  • Fixes in this release: interrupted init restores AGENTS.md (#281), NO_COLOR suppresses Work and transcript decoration (#282, #284), and the Work feed rebuilds after a service restart (#283).

Public install smoke ​

PASS on OpenCode 2.2.7 and 2.3.0 with Node 26.12.1:

  • opencode plugin add @heyimteee/ensemble@0.1.0-rc.2 installed from the public npm registry.
  • opencode plugin list reported ensemble.v2 0.1.0-rc.2 from the public package source.
  • The plugin record matched the package target and version, reported server/TUI/RPC true and active, and loaded its entrypoint from the public plugin cache, never the repository.
  • One host turn reported ensembleToolCount 6.
  • /ensemble rendered ENSEMBLE │ no workspace with no plugin failure.
  • Each version used isolated HOME/XDG/project/cache roots; services were stopped and directories removed afterwards.

Install from npm ​

Pin the exact published version. A bare npm install @heyimteee/ensemble or opencode plugin add @heyimteee/ensemble currently resolves the RC because latest and next both point at the only published version.

sh
opencode plugin add @heyimteee/ensemble@0.1.0-rc.2
opencode plugin list

opencode plugin list must show ensemble.v2 with version 0.1.0-rc.2 and the public package source @heyimteee/ensemble@0.1.0-rc.2. Restart OpenCode after the install, then open /ensemble or the Open Ensemble palette command.

Do not also load the same plugin from .opencode/plugins/; that creates a duplicate plugin ID. Do not use a Git spec with OpenCode 2.2.7: github:, git+https://, and owner/repo#tag installs fail upstream during Git dependency preparation, before Ensemble is loaded.

Upgrade ​

  1. Record the current install and back up durable state:
    sh
    opencode --version
    node --version
    opencode plugin list
    npm run backup -- export --out ./ensemble-backup.json "$PWD"
    The backup command runs from a checkout and contains conversation content; keep the file private.
  2. Stop the OpenCode host. The plugin and its RPC surface are replaced on the next start; there is no in-place hot swap.
  3. Install the exact version, restart, and verify:
    sh
    opencode plugin add @heyimteee/ensemble@0.1.0-rc.2
    opencode plugin list
  4. Open the workspace, confirm the AGENTS block is v7 with project content outside the markers intact, and send one group message. Confirm one turn, one Work card, and one final row.
  5. Keep the pre-upgrade backup until the workspace has run successfully for a full session.

An explicit nativeFirst: "off" or "shadow" is preserved. Durable state migrations are additive; see Upgrade from the pre-release for the full behavior table.

Rollback ​

If 0.1.0-rc.2 is wrong, reinstall the previous exact package and restart:

sh
opencode plugin add @heyimteee/ensemble@<previous-version>
opencode plugin list

There is no earlier public npm version for this first candidate, so a package-level downgrade is not available yet. For this release, rollback means restoring the pre-upgrade state backup and either removing the plugin entry or returning to the checkout install. Restore state only when the older code cannot read newer rows. Do not restore a backup produced by a newer formatVersion.

The full decision table, automatic rollback slot, and failure codes are in Package rollback and Backup and restore. Keep the pre-upgrade backup and rollback slot until the rolled-back workspace has run successfully.

Support ​

Support is best effort through GitHub Issues:

Include the Ensemble version, OpenCode and Node versions, operating system, terminal host, install method, exact commands, and redacted evidence. Never post credentials, conversation content, private project files, or unredacted logs. Maintainer response targets are best effort, not an SLA.

Known limitations ​

  • Windows is out of scope. Native Windows and WSL are untested.
  • Automatic copy-on-release is not claimed on macOS. Checklist item 1.7 passed with a pane-bounded Shift+drag and explicit copy; Ghostty copy-on-select is off, so a drag alone does not copy. This is a host preference, not Ensemble behavior. Cmd+C and Cmd+V also passed.
  • Herdr prefix control is inconclusive. The host-level test produced no tab or pane; no Ensemble key was observed to be intercepted, but the host claim is not proven.
  • Git-spec installs fail upstream in OpenCode 2.2.7. Use the npm package or a loopback registry; do not recommend Git installs for this host.
  • No telemetry. Ensemble does not upload logs or usage data. Diagnostics are local, and the support bundle is opt-in and redacted.
  • The 4-hour soak passed on both supported Linux hosts. The enforced gate passed on OpenCode 2.2.7 and 2.3.0 at b194b95; see the soak record.
  • macOS/Herdr is verified on OpenCode 2.2.7 only. The 2.3.0 support claim is Linux-verified; macOS 2.3.0 is not claimed.
  • macOS size-matrix load probe is Linux-only. Exact sizes pass with the load probe skipped. Braille glyphs depend on terminal font fallback on the tested Mac.
  • The prerelease owns npm latest. 0.1.0-rc.2 is the only published version, so both latest and next point at it. npm requires latest and rejects deleting it (E400). Pin 0.1.0-rc.2; a later stable release will move latest.

Proven and pending ​

The final-tip runtime checks at b194b95 established the 2.2.x evidence. The latest tip a7f1eb3 adds OpenCode 2.3.0 support (#286), hardens live TUI readiness (#287), and passes the full required CI matrix on the first attempt. The full macOS checklist including 1.7 also passes. The release is published: 0.1.0-rc.2 is live on npm and GitHub, and the public-registry install smoke passes on 2.2.7 and 2.3.0.

ItemStatusEvidence
Build, pack, and runtime-only contentsPASS#269, #279
Final-tip install at a0c39c0 (Linux, OpenCode 2.2.7)PASS507,907 bytes; six native tools, TUI route, /ensemble; parent #268 record
Earlier install at b194b95 (Linux, OpenCode 2.2.7)PASS124 runtime files, 507,824 bytes; six native tools, TUI route, /ensemble; parent #268 record
Deterministic fake E2E at a0c39c0 (2.2.7 and 2.3.0)PASSfake 416 s on each host; 2.3.0 host probe 14/14, size matrix PASS, loopback install PASS; parent #268 record
OpenCode 2.3.0 support (#286)PASSSupported range `2.2.6
Live TUI readiness (#287)PASSHarness false positive after Backspace (:setting → retype s → :settings restored); statusline-gated open and deterministic retype ordering. No product runtime change; 2,121 tests.
Required CI at a7f1eb3PASS (first attempt, no rerun)Verify (verify, live-fake, live-native, live-multilocation, latency-smoke), Compatibility (2.2.6, 2.2.7, and 2.3.0), Docs, and Node Matrix green. Parent record
Six native tools, installed TUI route, /ensemblePASS#279, #277
macOS/Herdr install, TUI, fake E2E, full checklistPASS#277
macOS/Herdr on OpenCode 2.3.0PENDING (not claimed)Only 2.2.7 is verified on macOS/Herdr.
macOS mouse drag (1.7)PASSPane-bounded Shift+drag over the composer marker, then explicit copy_to_clipboard; statusline and focus unchanged.
Automatic copy-on-release on macOSNOT CLAIMEDGhostty copy-on-select is off; explicit copy is required.
4-hour enforced soak at b194b95PASS on OpenCode 2.2.7 and 2.3.02.2.7: 240 samples, 14,439 s, 5,234 messages, 0 failures, 92.59 MiB/h and 18.71 MiB/1k. 2.3.0: 240 samples, 5,240 messages, 0 failures, 94.89 MiB/h and 19.14 MiB/1k. soak record
Public npm publish and tagPASS0.1.0-rc.2 on npm; GitHub prerelease v0.1.0-rc.2 at release. latest and next both point at the RC.
Provenance attestation and GitHub release assetsPASSnpm provenance; GitHub release assets are the tarball, CycloneDX SBOM, CHANGELOG, and release notes.
Public-registry install smokePASSOpenCode 2.2.7 and 2.3.0, Node 26.12.1; public package source, six tools, installed TUI route, /ensemble with no plugin failure.
Launch announcementPENDING / not claimedA separate decision; the release is already published.

The full release decision, sign-offs, and remaining gates are in Release sign-off and Parent #268 verification.

Released under the MIT License.