hv-sync - Collective Synchronization

Purpose

Synchronize local hAIveMind installation with the collective, ensuring commands, configurations, and agent state are up-to-date across all nodes.

When to Use

• Regular Updates: Keep commands and configs current with collective
• After Network Issues: Resync after connectivity problems
• New Agent Setup: Initial sync for new agent registration
• Troubleshooting: Clean sync to resolve configuration issues
• Manual Updates: Force sync when automatic updates fail
• Status Checking: Verify current sync state and version info

Syntax

hv-sync [operation] [options]

Parameters

• operation (optional): Sync operation type
  • force: Force full resync regardless of current state
  • status: Show sync status without making changes
  • clean: Remove local state and perform fresh sync
  • (no operation): Smart sync based on current state
• options (optional):
  • --verbose: Show detailed progress during sync
  • --commands: Sync only command files
  • --config: Sync only configuration files
  • --memory: Sync only memory/agent state
  • --hooks: Enable automatic pre/post sync hooks for ticket-memory synchronization
  • --dry-run: Show what would be synced without making changes

Real-World Examples

Regular Update Check

hv-sync

Result: Smart sync that only updates changed components

Force Complete Resync

hv-sync force --verbose

Result: Downloads all commands and configs regardless of current versions

Check Sync Status Only

hv-sync status

Result: Shows version comparisons and sync timestamps without making changes

Clean Slate Resync

hv-sync clean

Result: Removes local state and performs complete fresh installation

Commands-Only Update

hv-sync --commands --verbose

Result: Updates only hv-* command files with detailed progress

Sync with Automated Hooks

hv-sync --hooks --verbose

Result: Performs sync with automatic pre/post hooks for ticket-memory synchronization

Expected Output

Smart Sync (Default)

🔄 hAIveMind Synchronization - 2025-01-24 15:45:00

🔍 Checking collective for updates...
✓ Connected to collective (lance-dev orchestrator)
✓ Local version: 2025-01-20, Collective version: 2025-01-24
✓ 3 updates available

📦 Syncing Commands:
✓ hv-broadcast.md - Updated (v1.2.3 → v1.2.4)
✓ hv-query.md - Updated (v1.0.5 → v1.0.6) 
⚪ hv-delegate.md - Current (v1.1.0)
⚪ hv-status.md - Current (v1.1.2)
✓ recall.md - Updated (v2.0.1 → v2.0.2)
⚪ remember.md - Current (v2.0.1)
⚪ hv-sync.md - Current (v1.0.8)

🔧 Agent Configuration:
✓ Agent registration refreshed
✓ Capabilities updated: +monitoring, +incident_response
✓ Network mesh updated (2 new nodes discovered)

📝 CLAUDE.md Integration:
⚪ No updates needed (current version)

🎉 Sync Complete!
   ↳ 3 commands updated
   ↳ Agent capabilities refreshed
   ↳ Network mesh updated
   ↳ Next automatic sync: 2025-01-24 21:45:00

Status Check Output

📊 hAIveMind Sync Status - 2025-01-24 15:45:00

🏷️  VERSIONS:
   ↳ Local Version: 2025-01-20 14:30:00
   ↳ Collective Version: 2025-01-24 12:15:00
   ↳ Status: 3 updates available
   ↳ Last Sync: 2025-01-23 09:20:00 (1 day ago)

📦 COMMAND STATUS:
┌─────────────────┬─────────────┬─────────────┬──────────────────┐
│ Command         │ Local       │ Collective  │ Status           │
├─────────────────┼─────────────┼─────────────┼──────────────────┤
│ hv-broadcast    │ v1.2.3      │ v1.2.4      │ ⬆️ Update Available │
│ hv-delegate     │ v1.1.0      │ v1.1.0      │ ✅ Current        │
│ hv-install      │ v1.0.3      │ v1.0.3      │ ✅ Current        │
│ hv-query        │ v1.0.5      │ v1.0.6      │ ⬆️ Update Available │
│ hv-status       │ v1.1.2      │ v1.1.2      │ ✅ Current        │
│ hv-sync         │ v1.0.8      │ v1.0.8      │ ✅ Current        │
│ recall          │ v2.0.1      │ v2.0.2      │ ⬆️ Update Available │
│ remember        │ v2.0.1      │ v2.0.1      │ ✅ Current        │
└─────────────────┴─────────────┴─────────────┴──────────────────┘

🤖 AGENT STATUS:
   ↳ Registration: Active (lance-dev-development-agent)
   ↳ Capabilities: development, infrastructure_management, coordination
   ↳ Network Nodes: 12 connected, 2 offline
   ↳ Last Heartbeat: 45 seconds ago

⚡ SYNC SCHEDULE:
   ↳ Auto-sync: Enabled (every 6 hours)
   ↳ Next Check: 2025-01-24 21:45:00
   ↳ Force Sync Available: Yes

Sync Operations Deep Dive

Smart Sync (Default)

• Compares local versions with collective versions
• Only downloads changed files
• Updates agent registration if needed
• Preserves local customizations where possible
• Fast and network-efficient

Force Sync

• Downloads all commands regardless of version
• Completely refreshes agent registration
• Overwrites local customizations
• Use when experiencing unexplained issues
• Longer operation but ensures consistency

Clean Sync

• Removes all local hAIveMind state
• Performs fresh installation from scratch
• Reregisters agent with new identity if needed
• Use as last resort for corrupted installations
• Equivalent to uninstall + install

Performance Considerations

• Smart Sync: ~5-15 seconds, minimal network usage
• Force Sync: ~30-60 seconds, full download
• Clean Sync: ~45-90 seconds, complete reinstall
• Status Check: ~2-5 seconds, minimal data transfer
• Network Impact: Syncs use efficient delta compression

Error Scenarios and Solutions

Network Connectivity Issues

❌ Error: Cannot connect to collective orchestrator
💡 Troubleshooting:
   1. Check Tailscale: tailscale status
   2. Verify orchestrator: ping lance-dev
   3. Check MCP server: curl http://lance-dev:8900/health
   4. Retry with: hv-sync force

Version Conflicts

⚠️  Warning: Local modifications detected in hv-broadcast.md
💡 Options:
   1. Backup and allow overwrite: hv-sync force
   2. Skip this file: choose 'skip' when prompted
   3. Manual merge: review differences before sync

Agent Registration Issues

❌ Error: Agent registration failed (duplicate ID)
💡 Resolution:
   1. Clean registration: hv-sync clean
   2. Check for duplicate agents: hv-status --agents
   3. Manual cleanup may be required

Best Practices

• Regular Sync: Run weekly or after system changes
• Before Important Work: Sync before major tasks
• After Network Issues: Sync after connectivity problems
• Status Monitoring: Check status before manual sync
• Backup Customizations: Save custom changes before force sync
• Scheduled Sync: Enable automatic sync for convenience

Related Commands

• Before syncing: Use hv-status to check collective health
• After syncing: Use hv-install status to verify installation
• For issues: Use hv-query to find sync-related solutions
• Share updates: Use hv-broadcast to inform others of sync results
• Hook management: Use hv-sync-hooks to manage automated synchronization hooks

---

Sync Operation: $ARGUMENTS

This will synchronize your local hAIveMind installation with the collective, ensuring you have the latest commands, configurations, and agent state for optimal collaborative intelligence.