These instructions describe the reliability candidate, awaiting release
acceptance. Every destination must be permitted to receive the entire selected
database: this transport does not enforce work/personal scope or per-peer content
permissions. Project search filters do not limit transfer. Local deletion is not
propagated forgetting; peers, backups and native transcripts can restore it.
The exporter and the database must agree on the schema; studyloop doctor
reports exporter_schema.
Install the repaired exporter on each machine. Run session-repair to inspect
native transcripts, then session-repair --apply to back up and repair that
machine's database, including pending schema migrations. Sync checks both schema
versions before transferring rows. If a machine is outdated, its error identifies
the machine and asks you to run session-repair --apply there; no columns or
populated source fields are silently discarded. A machine can only recover native conversations available
there; syncing distributes the recovered history afterwards.
Configure the machines in the shared ~/.config/studyloop/config.yaml:
hosts:
laptop:
hostname: My-Laptop
user: person
ip_address:
primary: 192.0.2.10
sessions_db: /Users/person/.config/studyloop/sessions.db
macmini:
hostname: My-Mac-mini
user: person
ip_address:
primary: 192.0.2.12
secondary: 192.0.2.13
sessions_db: /Users/person/.config/studyloop/sessions.dbUse each machine's actual hostname (without the .local suffix), SSH user,
reachable addresses, and absolute database path. The current hostname is
excluded automatically. Existing legacy endpoints configuration remains
supported when hosts is absent. SSH authentication must already work. Authenticate and accept verified host keys
once in a separate terminal before using session-sync all. Sync uses SSH batch
mode so offline or unauthenticated peers fail without password prompts; connection
timeouts and keepalive limits prevent an unreachable peer blocking the run.
session-sync allThis pushes to every configured peer before pulling from every peer. It reconciles shared sessions even when conversation timestamps have not changed, so newly repaired messages can transfer. Each failed peer operation is reported; other peers are attempted, and any failure produces a nonzero exit code. With more than two machines, a later run may be needed to distribute history first discovered during the pull phase to all other peers.
For one peer, use session-sync sync macmini --reconcile. For timestamp-only
routine transfers, use session-sync all --incremental. --db /absolute/path
overrides the local database; --tier full uses configured full_db paths.
Sync skips source-only empty message artifacts, preserving any empty rows already present at the destination. A reference requiring an omitted empty row aborts the transaction for explicit repair instead of leaving a dangling reference.
Sync adds missing messages and fills missing fields without replacing existing
nonempty conversation content or deleting local annotations. Different nonempty
versions of the same message are retained at their destination and counted in a
warning; they require explicit review with session-repair --from-db SNAPSHOT.
Thus reconciliation does not promise that conflicting databases become identical.
Per-destination writes are transactional and backups precede writes. Initial
seeding transfers a consistent SQLite backup, never a live database file.
Some older databases enforce one parked question per study session, while newer databases enforce one pending question across sessions. Their current views cannot both hold every duplicate event. Sync resolves those known natural-key collisions using the global metadata timestamp rule, preserving the destination row ID and sync key. This policy applies to learning metadata, never conversation message content.
Before merging, sync stores complete original parked rows from both machines in
sync_row_archive, including columns outside the current-view sync allowlist
(such as notes, board fields, and park counts). It also snapshots the resulting
current rows. Archiving and merging share one transaction. The composite key of
table name and JSON serialized with sorted column names makes identical snapshots
idempotent. Archive rows travel in subsequent syncs, so original variants remain
recoverable on other machines. The command reports newly preserved snapshots.
For read-only inspection:
SELECT row_json FROM sync_row_archive WHERE table_name = 'parked_topics';The parked-topic UI presents the merged current view; the archive retains its original variants for explicit review or restoration. Optional fields excluded from the current-view allowlist are preserved in the archive rather than forced into incompatible legacy table constraints.