Repository navigation
Session export/import — portable bundles for store merge + sessions-to-go #291
Description
Important
Problem
Fleet clients hold a separate session store from the canonical hub, and there is no way to move session history between stores — the 2026-09-04 MacBook situation (560 MB local vs ~3 GB hub, zero cross-visibility) is the standing case. The thin-client PRD (amicode#792) unifies the view but not the stores; the offline story ("sessions to go") needs the same primitive.
Approach
Server-side export/import verbs, faithful at the storage layer: opencode export session <id> → a portable JSONL bundle (session metadata + every message part in order, IDs and timestamps preserved); opencode import session <bundle> [--remap-dir <from>=<to> ...] → writes into the target store idempotently (existing session ID = no-op), with an optional directory-remap table so sessions from another machine's paths appear under the target's project buckets.
Approaches Considered
- Storage-layer verbs (chosen) — faithful (parts, timestamps, model metadata), idempotent, reusable for one-time merge + offline export.
- API-level replay (POST session/messages) — lossy, risks re-triggering agent processing; rejected.
- Direct DB SQL across stores — schema-coupled surgery on a live store; rejected.
Scope
In: export verb, import verb, remap flag, idempotency, tests.
Out: UI/app packages (another stream owns fork UI right now); any automatic sync/mirror; retention or cleanup behavior.
Acceptance Criteria
export session <id>writes a bundle containing the session metadata and every message part, byte-faithful to what the storage layer returns, in order.import session <bundle>recreates the session in the target store; reading it back matches the export (round-trip identity).- Import is idempotent: importing a bundle whose session ID already exists is a no-op (exit 0, no duplication).
--remap-dir from=torewrites the session's project directory at import; sessions without a matching remap keep their original path.- The verbs work against a live store without corrupting it (concurrent-safe or documented single-writer requirement).
- Tests cover round-trip, idempotency, remap, and a multi-session bundle.
Source
- amicode#792 (thin-client PRD — offline story), amicissimo docs/fleet/ (fleet design record), armonissima spec-20260904 (fleet boundary + thin-client decision)
- Evidence: the 2026-09-04 MacBook store-split incident (fleet sessions invisible standalone, local sessions invisible in fleet)
Activity