skills/codex-task-server-sync/references/recovery.md

Recovery Reference

Use this reference after bootstrap when the synced project needs inspection, conflict recovery, or server-side continuation.

Inspect Status

Run these from the migrated project root:

cat .codex-sync/manifest.json
cat .codex-sync/runtime/status.json
cat .codex-sync/runtime/last-error.log
git status -sb

If status.json says blocked, the last sync hit a rebase or merge conflict and automatic sync has paused itself.

Resolve A Conflict

1. Open the project and inspect git status.
2. Resolve the conflict or decide which side to keep.
3. Finish the git operation or abort it explicitly.
4. Remove .codex-sync/runtime/blocked.
5. Re-run .codex-sync/bin/sync-once.sh.

Re-run Sync Manually

./.codex-sync/bin/sync-once.sh --project-dir "$PWD"

Pass --host-label local-manual or --host-label remote-manual when you want the autosave commit to identify where it was triggered.

Continue The Task On The Server

cd /root/continue/<project>
./.codex-sync/bin/continue-task.sh

That command starts Codex with a prompt that tells it to read .codex-sync/handoff.md, inspect sync status, and continue work from the server checkout.

Service Control

The exact service names are written into .codex-sync/manifest.json and .codex-sync/README.md.

Local macOS:

launchctl print "gui/$(id -u)/<launchd-label>"
launchctl kickstart -k "gui/$(id -u)/<launchd-label>"

Remote Linux:

systemctl status <systemd-service> <systemd-timer>
systemctl restart <systemd-service>
systemctl restart <systemd-timer>