feat(sync): enhance sync configuration with activity-aware batching and migration support

Author: ErcinDedeoglu

README.md

@@ -8,7 +8,7 @@ Sync your OpenCode configuration, sessions, and data across multiple machines us
 - **Multi-Machine Support** - Safely sync across laptops, VMs, and servers simultaneously
 - **Conflict Resolution** - Vector clocks detect conflicts, three-way merge resolves them
 - **Encrypted Credentials** - AES-256-GCM encryption for sensitive data
-- **Auto-Sync** - Syncs on startup, on file changes (2s debounce), and every minute
+- **Auto-Sync** - Syncs on startup, on file changes (5s debounce, 30s max), and every 5 minutes
 - **Offline-Friendly** - Works offline, syncs when reconnected
 - **Atomic Updates** - Uses Git's compare-and-swap for safe concurrent access
 
@@ -52,12 +52,10 @@ npm install && npm run build
 | State | Model selections, prompt history, stashed prompts | ✅ Enabled |
 | Credentials | OAuth tokens, MCP auth (encrypted) | ✅ Enabled |
 | Sessions | Session metadata and history | ✅ Enabled |
-| Messages | Conversation messages and parts | ❌ Disabled* |
+| Messages | Conversation messages and parts | ✅ Enabled |
 | Projects | Project configurations | ✅ Enabled |
 | Todos | Task lists and session diffs | ✅ Enabled |
 
-*Messages sync is disabled by default because it can be very large (8MB+). Enable it in config if needed.
-
 ## How It Works
 
 ### Vector Clocks for Conflict Detection
@@ -154,33 +152,38 @@ On subsequent runs:
   "repoName": ".opencode-sync",
   "autoSyncOnStartup": true,
   "continuousSync": true,
-  "syncIntervalMinutes": 1,
+  "syncIntervalMinutes": 5,
+  "fileWatcherDebounceMs": 5000,
+  "maxDebounceMs": 30000,
   "sync": {
     "config": true,
     "state": true,
     "credentials": true,
     "sessions": true,
-    "messages": false,
+    "messages": true,
     "projects": true,
     "todos": true
   },
   "conflictStrategy": "auto-merge"
 }
 ```
 
-**Note:** `messages` is `false` by default because conversation history can be very large (8MB+). Set to `true` if you want to sync messages across machines.
+**Note:** All categories are enabled by default. Disable `messages` if you have very large conversation history (8MB+) and want to reduce sync size.
 
 ## Sync Timing
 
-The plugin syncs at these times:
+The plugin uses **activity-aware batching** to prevent excessive syncs during heavy IO:
+
+| Trigger | Default | Description |
+|---------|---------|-------------|
+| **Startup** | Enabled | Immediately when OpenCode starts |
+| **File Changes** | 5s debounce | Wait for inactivity before syncing |
+| **Max Delay** | 30s cap | Force sync even during heavy activity |
+| **Interval** | 5 minutes | Periodic sync regardless of changes |
 
-| Trigger | When |
-|---------|------|
-| **Startup** | Immediately when OpenCode starts |
-| **File Changes** | 2 seconds after local OpenCode files change |
-| **Interval** | Every 1 minute (configurable) |
+During heavy activity, syncs are batched and fire at most every 30 seconds.
 
-This is **not realtime** - there's typically a 1-60 second delay depending on when changes occur.
+See [docs/SYNC.md](docs/SYNC.md) for detailed architecture documentation.
 
 ## Security
 

docs/SYNC.md

@@ -0,0 +1,64 @@
+# Sync Architecture
+
+## Sync Triggers
+
+| Trigger | Default | Config Key |
+|---------|---------|------------|
+| Startup | Enabled | `autoSyncOnStartup` |
+| File Changes | 5s debounce | `fileWatcherDebounceMs` |
+| Max Delay | 30s cap | `maxDebounceMs` |
+| Interval | 5 min | `syncIntervalMinutes` |
+
+## Activity-Aware Batching
+
+Two timers prevent excessive syncs during heavy IO:
+
+- **Debounce** (5s): Resets on each file change
+- **Max Delay** (30s): Never resets, forces sync
+
+Sync fires on whichever timer completes first.
+
+```
+Heavy IO:  [changes...] ──────────────────────> 30s max delay fires
+Light IO:  [change] ─────> 5s inactivity ─────> debounce fires
+```
+
+## Configuration
+
+```json
+{
+  "syncIntervalMinutes": 5,
+  "fileWatcherDebounceMs": 5000,
+  "maxDebounceMs": 30000
+}
+```
+
+## Data Categories
+
+**Blob** (single compressed file): config, state, credentials, projects, todos
+
+**Item** (per-file sync): sessions, messages
+
+## Remote Storage Structure
+
+```
+.opencode-sync/
+├── manifest.json
+├── {category}.json.gz.b64          # Blob categories
+├── {category}-shard.json           # Item category index
+├── sessions/{projectHash}/{id}.json.gz
+└── messages/
+    ├── {sessionId}/{msgId}.json.gz
+    └── parts/{msgId}/{partId}.json.gz
+```
+
+## Key Files
+
+| File | Purpose |
+|------|---------|
+| `src/sync/watcher/file-watcher.ts` | Debounce + max delay |
+| `src/sync/engine/sync-engine.ts` | Sync orchestration |
+| `src/sync/operations/push.ts` | Local → Remote |
+| `src/sync/operations/pull.ts` | Remote → Local |
+| `src/sync/item-packer.ts` | Per-item compression |
+| `src/types/config.ts` | Config defaults |

src/data/state.ts

@@ -16,40 +16,43 @@ const ENV_TOKEN_KEY = 'GITHUB_TOKEN';
 
 /**
  * Load plugin configuration from disk with environment variable fallback.
+ * Automatically migrates config: adds missing keys, removes obsolete ones.
  *
  * Token resolution order:
  * 1. Config file token (if exists and non-empty)
  * 2. GITHUB_TOKEN environment variable
  * 3. null (no token available)
  */
 export async function loadConfig(pathConfig: PathConfig): Promise<SyncConfig | null> {
-  let config: SyncConfig | null = null;
+  let rawConfig: Record<string, unknown> | null = null;
 
   try {
     const content = await readFile(pathConfig.pluginConfigPath, 'utf-8');
-    config = JSON.parse(content) as SyncConfig;
+    rawConfig = JSON.parse(content) as Record<string, unknown>;
   } catch {
     // Config file doesn't exist or is invalid - will try env var
   }
 
   const envToken = process.env[ENV_TOKEN_KEY];
 
-  if (config) {
-    // Config exists - merge with defaults and use env var as fallback if no token
-    const mergedConfig = {
-      ...DEFAULT_CONFIG,
-      ...config,
-      sync: { ...DEFAULT_CONFIG.sync, ...config.sync },
-    };
+  if (rawConfig) {
+    // Migrate config: use defaults, keep user values, remove obsolete keys
+    const migratedConfig = migrateConfig(rawConfig);
 
-    if (!mergedConfig.token && envToken) {
-      mergedConfig.token = envToken;
+    if (!migratedConfig.token && envToken) {
+      migratedConfig.token = envToken;
     }
-    // Generate machineId if missing
-    if (!mergedConfig.machineId) {
-      mergedConfig.machineId = generateMachineId();
+    if (!migratedConfig.machineId) {
+      migratedConfig.machineId = generateMachineId();
+    }
+
+    // Save migrated config if it changed
+    const configChanged = !configsEqual(rawConfig, migratedConfig as unknown as RawConfig);
+    if (configChanged) {
+      await saveConfig(pathConfig, migratedConfig);
     }
-    return mergedConfig;
+
+    return migratedConfig;
   }
 
   // No config file - create minimal config from env var if available
@@ -64,6 +67,86 @@ export async function loadConfig(pathConfig: PathConfig): Promise<SyncConfig | n
   return null;
 }
 
+/** Raw config from disk (untyped) */
+type RawConfig = Record<string, unknown>;
+
+/** Keys that are user-specific and should always be preserved */
+const USER_KEYS = [
+  'token',
+  'machineId',
+  'repoOwner',
+  'repoName',
+  'branch',
+  'keySalt',
+  'passphraseHash',
+  'oldEncryptionKey',
+] as const;
+
+/**
+ * Migrate config to latest schema.
+ * - Adds missing keys from DEFAULT_CONFIG
+ * - Removes keys not in DEFAULT_CONFIG (except user-specific keys)
+ * - Preserves user values for existing keys
+ */
+function migrateConfig(raw: RawConfig): SyncConfig {
+  // Start with defaults
+  const migrated: RawConfig = { ...DEFAULT_CONFIG };
+
+  // Copy user-specific keys
+  for (const key of USER_KEYS) {
+    if (key in raw) {
+      migrated[key] = raw[key];
+    }
+  }
+
+  // For config keys in DEFAULT_CONFIG, use user value if present
+  for (const key of Object.keys(DEFAULT_CONFIG)) {
+    if (!(key in raw)) continue;
+    if (key === 'sync') {
+      migrated['sync'] = migrateSyncCategories(raw['sync'] as RawConfig | undefined);
+    } else {
+      migrated[key] = raw[key];
+    }
+  }
+
+  return migrated as unknown as SyncConfig;
+}
+
+/**
+ * Migrate sync categories: merge with defaults, remove obsolete keys.
+ */
+function migrateSyncCategories(rawSync: RawConfig | undefined): RawConfig {
+  const merged: RawConfig = { ...DEFAULT_CONFIG.sync, ...rawSync };
+  const validKeys = new Set(Object.keys(DEFAULT_CONFIG.sync));
+  const result: RawConfig = {};
+  for (const key of Object.keys(merged)) {
+    if (validKeys.has(key)) {
+      result[key] = merged[key];
+    }
+  }
+  return result;
+}
+
+/**
+ * Check if migration actually changed config values (ignoring key order).
+ * Only compares keys that exist in DEFAULT_CONFIG + USER_KEYS.
+ */
+function configsEqual(raw: RawConfig, migrated: RawConfig): boolean {
+  const allKeys = [...Object.keys(DEFAULT_CONFIG), ...USER_KEYS];
+  for (const key of allKeys) {
+    const rawVal = raw[key];
+    const migVal = migrated[key];
+    if (rawVal === undefined && migVal === undefined) continue;
+    if (rawVal === undefined || migVal === undefined) return false;
+    if (JSON.stringify(rawVal) !== JSON.stringify(migVal)) return false;
+  }
+  // Check if raw has extra keys that will be removed
+  for (const key of Object.keys(raw)) {
+    if (!(key in migrated)) return false;
+  }
+  return true;
+}
+
 /**
  * Get the source of the GitHub token.
  */

src/plugin/plugin.ts

@@ -243,6 +243,7 @@ function startFileWatcher(pathConfig: PathConfig): void {
     activeWatcher = new FileWatcher({
       pathConfig,
       debounceMs: state.config.fileWatcherDebounceMs,
+      maxDebounceMs: state.config.maxDebounceMs,
       enabledCategories,
       onEvent: async () => {
         try {
@@ -321,6 +322,9 @@ export const OpencodeSyncPlugin = async (_ctx: unknown): Promise<Record<string,
       log('Plugin ready');
     }
 
+    // Return cleanup function
+    // Note: OpenCode doesn't currently expose a shutdown hook for plugins,
+    // so this cleanup may not be called. See: https://github.com/anomalyco/opencode/issues/XXX
     return { cleanup: stopBackgroundSync };
   } catch (error) {
     const errMsg = error instanceof Error ? error.message : String(error);

src/sync/watcher/file-watcher.ts

@@ -14,6 +14,8 @@ export class FileWatcher {
   private readonly watchers = new Map<string, FSWatcher>();
   private readonly pendingEvents = new Map<string, WatcherEvent>();
   private debounceTimer: ReturnType<typeof setTimeout> | null = null;
+  private maxDelayTimer: ReturnType<typeof setTimeout> | null = null;
+  private firstEventTime: number | null = null;
   private isRunning = false;
 
   constructor(options: FileWatcherOptions) {
@@ -63,6 +65,12 @@ export class FileWatcher {
       this.debounceTimer = null;
     }
 
+    if (this.maxDelayTimer) {
+      clearTimeout(this.maxDelayTimer);
+      this.maxDelayTimer = null;
+    }
+
+    this.firstEventTime = null;
     this.pendingEvents.clear();
   }
 
@@ -81,6 +89,17 @@ export class FileWatcher {
     const event: WatcherEvent = { type, path, category };
     this.pendingEvents.set(path, event);
 
+    // Track first event time for max delay cap
+    if (this.firstEventTime === null) {
+      this.firstEventTime = Date.now();
+
+      // Set up max delay timer - will force flush even if activity continues
+      this.maxDelayTimer = setTimeout(() => {
+        void this.flushEvents();
+      }, this.options.maxDebounceMs);
+    }
+
+    // Reset debounce timer on each event
     if (this.debounceTimer) {
       clearTimeout(this.debounceTimer);
     }
@@ -95,7 +114,17 @@ export class FileWatcher {
 
     const events = Array.from(this.pendingEvents.values());
     this.pendingEvents.clear();
-    this.debounceTimer = null;
+
+    // Clear both timers
+    if (this.debounceTimer) {
+      clearTimeout(this.debounceTimer);
+      this.debounceTimer = null;
+    }
+    if (this.maxDelayTimer) {
+      clearTimeout(this.maxDelayTimer);
+      this.maxDelayTimer = null;
+    }
+    this.firstEventTime = null;
 
     try {
       await this.options.onEvent(events);

src/sync/watcher/index.ts

@@ -22,7 +22,8 @@ export function createFileWatcher(
   return new FileWatcher({
     pathConfig,
     onEvent,
-    debounceMs: options?.debounceMs ?? 2000,
+    debounceMs: options?.debounceMs ?? 5000,
+    maxDebounceMs: options?.maxDebounceMs ?? 30000,
     enabledCategories:
       options?.enabledCategories ??
       new Set(['config', 'state', 'credentials', 'sessions', 'messages', 'projects', 'todos']),

src/sync/watcher/types.ts

@@ -9,6 +9,8 @@ import type { SyncCategory, WatcherEvent, PathConfig } from '../../types/index.j
 export interface FileWatcherOptions {
   pathConfig: PathConfig;
   debounceMs: number;
+  /** Maximum time to wait before syncing even if activity continues (ms) */
+  maxDebounceMs: number;
   onEvent: (events: WatcherEvent[]) => void | Promise<void>;
   enabledCategories: Set<SyncCategory>;
 }

src/types/config.ts

@@ -25,6 +25,8 @@ export interface SyncConfig {
   continuousSync: boolean;
   syncIntervalMinutes: number;
   fileWatcherDebounceMs: number;
+  /** Maximum time to wait before syncing even if activity continues (ms) */
+  maxDebounceMs: number;
 
   // What to sync
   sync: {
@@ -53,8 +55,9 @@ export interface SyncConfig {
 export const DEFAULT_CONFIG: Omit<SyncConfig, 'token' | 'machineId'> = {
   autoSyncOnStartup: true,
   continuousSync: true,
-  syncIntervalMinutes: 1,
-  fileWatcherDebounceMs: 2000,
+  syncIntervalMinutes: 5,
+  fileWatcherDebounceMs: 5000,
+  maxDebounceMs: 30000,
   sync: {
     config: true,
     state: true,