Skip to content

Ticket #273: backup/restore and upgrade/rollback — verification ​

  • Date: 2026-11-16
  • Branch: ticket/273-backup
  • Base: integration/public-release at 3bd92b7 (ticket #269)
  • Final tree: merged integration/public-release (tickets #269, #271, #272, #274) before the ticket commit
  • Spec: parent #268; ticket #273
  • Docs: backup and restore, upgrade, package rollback
  • Unit gate: npm run verify — typecheck plus 2,066 tests on the merged tree, all passing
  • Docs gate: npm run docs:check — contract v7, OpenCode 2.2.6/2.2.7, Node >=22.23.4

What was built ​

One versioned ensemble.backup document covers the durable plugin state and the derived Workspace config:

  • payload.meta (settings, UI state, coordination version), the pre-v2 ensemble.state migration source, and every known durable prefix: agents, workspaces, messages, subtasks, dispatch groups, init jobs, native subagents, bindings, memories, approvals, the DM queue, and legacy direct rows;
  • payload.workspaceConfigs, joined by workspace ID, carrying the validated .ensemble/config.json and init.json values. Filesystem paths stay on the durable workspace row and are never duplicated in the document.

collectBackup reads only the public ctx.storage surface. validateBackup checks the format, version, digest, counts, key prefixes, and the fields the store indexes or doctor reads. applyBackup validates before writing, captures the current state and config text, writes one rollback slot at v2/backup/rollback, replaces the durable prefixes and meta row, restores configs, removes config files for workspaces the document no longer has, and returns a content-free report.

Four invoke actions expose the existing service seam: backup.export, backup.restore (confirmation: "RESTORE"), backup.rollback (confirmation: "ROLLBACK"), and backup.status. Restore and rollback refuse while a run, init job, or pump is active, and run the storage transaction on the store's serialized write queue. The store gained reload() (re-read after the external transaction and publish an explicit feed reset) and runExclusive() (serialize the transaction). NativeIngestionState reuses its existing clear() for restored state.

scripts/backup.mjs is the tested operator client. It resolves the same service descriptor as doctor, writes exports atomically with mode 0600, prints counts and versions only, and maps a service refusal to exit 1.

Upgrade and rollback coverage ​

upgrade.md covers the pre-release to 0.1.0: pinned install, backup before upgrade, restart requirement, and every additive first-start change — native-first on persistence, AGENTS v7 reconciliation, the native-state refactor and start reconciliation, dispatch-ledger synthesis, direct-transcript merge, v1 agent migration, init phase to phases, and lease-safe recovery. It also states the v7 roster title/role disclosure and defers the disclosure policy to #272.

rollback.md covers package-only rollback (pinned reinstall, restart, doctor and one group turn), state rollback first when the older release cannot read newer rows, refusal of a newer formatVersion, and the exact rehearsal commands and expected evidence.

Rehearsal evidence ​

The upgrade-failure rehearsal is deterministic and part of verify:

CaseTestResult
Export/restore round trip with config and version advancebackup.test.tspass
Restore replaces prior rows and removes stale configbackup.test.tspass
Store reload re-reads restored storage and publishes one explicit resetbackup.test.tspass
Foreign, newer, truncated, duplicate, or malformed document rejected before writesbackup.test.tspass
Injected write failure → restore_failed_rolled_back, previous rows and config text restoredbackup.test.tspass
Permanent write failure → restore_failed, complete slot remains and applies in a clean storebackup.test.tspass
Config write failure → durable state and prior config text recoveredbackup.test.tspass
Corrupt or absent slot reports no contentbackup.test.tspass
Service RPC export/restore/rollback round tripservice.test.ts (ticket273:)pass
Failed service restore keeps the running state and the slot usableservice.test.ts (ticket273:)pass
Restore and rollback refuse while work is active (busy)service.test.ts (ticket273:)pass
Restored state produces zero doctor mismatchesservice.test.ts (ticket273:)pass
CLI usage, confirmation, atomic 0600 export, restore, rollback, status, refusal, no content in outputbackup-cli.test.tspass

doctor compatibility is asserted at the shared seam: after a service restore, the diagnostic output is normalized with normalizeSnapshot (now exported from doctor-cli.ts) and passed to diagnoseLocations with the config file read from disk. The report has zero mismatches.

Log assertions cover the export, restore, and rollback events: the fields carry format/version and counts only; roster names and directories do not appear.

Privacy and scope ​

  • Fixtures and tests use temporary directories; no real path, conversation text, credential, or file bytes are committed.
  • The CLI writes an owner-only file and never prints the document, entity values, or the password.
  • Attachments, handoff files, AGENTS.md, host sessions, and logs are explicitly out of scope and documented as such.
  • No retention, delete, or user-export policy is implemented here. #272 owns that policy. The document envelope is the shared export format candidate; if #272 lands with a different shape, it can reuse collectBackup and the versioned header rather than adding a second serialization.

Coordination and conflicts ​

  • #272 (retention/export/delete): landed on integration/public-release during the final merge (with #271 and #274). Its ensemble.data-export is a deliberate user-facing projection and excludes bindings, host session ids, directories, settings, and logs, so it cannot restore a store. The recovery document stays ensemble.backup; data-control.ts and its retention/delete implementation were not duplicated. docs/privacy/data-and-retention.md now states the distinction, and the incident runbook links the recovery path. Conflicts were limited to the docs/README.md verification list, package.json scripts, and src/v2/service.ts dispatch cases; all were resolved by keeping both sides.
  • #275 (release workflow): this ticket adds no workflow, tag, or publish job. It adds one npm script (backup) and one repository script (scripts/backup.mjs); conflict risk is limited to package.json scripts and scripts/README.md.
  • #269 (package contents): src/v2/backup.ts is reachable from the server export and ships in the runtime closure; the CLI lives under scripts/, so the contents allowlist is unchanged.

Blocked checks ​

A real package downgrade rehearsal (install 0.1.0, reinstall 0.1.0-rc.1, restart, doctor, one turn) is blocked until a candidate is published and a previous installable version exists. The failure/recovery half is rehearsed above at the store and service seams; the package-install half is listed for the release sign-off (#278) rather than claimed as a pass.

Commands ​

sh
source /home/tristan/.nvm/nvm.sh && nvm use 26.12.1
npm run verify
npm run docs:check
node --test --experimental-strip-types src/v2/backup.test.ts
node --test --experimental-strip-types src/v2/backup-cli.test.ts
node --test --experimental-strip-types --test-name-pattern="ticket273" src/v2/service.test.ts

Released under the MIT License.