openclaw-control-plane/sync/README.md

Sync Layer

This is the MVP communication layer for PC and VPS agents.

It uses polling-based Git synchronization. Git is the durable source of truth and audit log, while these scripts reduce manual pull and push work.

Each script also publishes non-secret health files under sync-state/ so CORRECTION can monitor communication:

• sync-state/heartbeat-pc.json
• sync-state/heartbeat-vps.json
• sync-state/error-pc.md
• sync-state/error-vps.md

PC

Run from D:\openclaw-control-plane:

.\sync\sync-agent.ps1

Run one cycle only:

.\sync\sync-agent.ps1 -Once

VPS

Run from /home/ubuntu/openclaw-control-plane:

bash sync/sync-agent.sh

Run one cycle only:

bash sync/sync-agent.sh --once

Rules

• Scripts only stage known control-plane paths.
• Scripts publish heartbeat at most once per HEARTBEAT_EVERY_SECONDS interval, default 60 seconds.
• Agents should avoid editing the same file concurrently.
• AGENT_BOARD.md is owned by ORCHESTRATOR.
• Each role owns its own handoff/*.md file.
• Evidence files should be append-only by unique filename.
• On conflict or sync failure, stop the script and resolve manually.
• CORRECTION treats heartbeat older than 2 minutes as warning and older than 5 minutes as blocked.
• CORRECTION blocks cross-device dependent and mutation-stage tasks when sync health is blocked.

Future Upgrade

This polling layer should be replaced or supplemented when conditions are mature:

• Gitea webhook triggers for pull notifications.
• Gitea Issues as the task queue.
• OpenClaw Gateway events for cross-device command triggers.
• Cursor SDK based coordinator for creating, resuming, and supervising agents.