Session export/import — portable bundles for store merge + sessions-to-go

[aarontrowbridge]

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

1. export session <id> writes a bundle containing the session metadata and every message part, byte-faithful to what the storage layer returns, in order.
2. import session <bundle> recreates the session in the target store; reading it back matches the export (round-trip identity).
3. Import is idempotent: importing a bundle whose session ID already exists is a no-op (exit 0, no duplication).
4. --remap-dir from=to rewrites the session's project directory at import; sessions without a matching remap keep their original path.
5. The verbs work against a live store without corrupting it (concurrent-safe or documented single-writer requirement).
6. 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)