Publishing a synced rig

Why rig hub publish and rig hub update can refuse on synced rigs, and how to override safely.

For a shared rig, rig hub publish and rig hub update add a precondition: sync must be clean. If the local workspace is ahead of the relay, behind it, or has unresolved conflicts, the command refuses.

Why

A .rig.tgz published from a dirty workspace would include changes the relay hasn't seen. Next time another collaborator pulls, their sync would collide with files now also out in the world. The cleanest invariant is: publish what the team has already seen.

Same logic for rig hub update: pulling a new version on top of unsynced local edits creates a conflict before the daemon has a chance to push them.

What "clean" means

rig status reports OK on all four:

Daemon running (tapd alive, pidfile valid).
No conflicts (no files in conflict state).
No apply errors (every relay event was applied successfully).
Not offline (the daemon has talked to the relay recently).

When you'll see the refusal

$ rig hub publish
✗ Cannot publish: sync is dirty.
  - 1 conflict in data/templates/email.md
  - 0 apply errors
  Run `rig status` for details, resolve, retry.

Or:

$ rig hub update
✗ Cannot update: daemon offline.
  Run `rig resume` and wait for sync to catch up.

How to clean up

Issue	Fix
Daemon stopped	`rig resume`
Daemon stuck	check `.rig/tap/daemon.log`; `rig pause && rig resume`
Conflicts	open the files; resolve; save
Apply errors	see the error in `rig status`; usually a file the daemon can't write (permissions); fix the perm
Offline	check your network; daemon will re-sync automatically

Then retry the publish or update.

Overriding

rig hub publish splits the guard by what's blocking, so the override matches the risk:

rig hub publish --no-wait    # don't wait for pending uploads to settle
rig hub publish --force      # publish despite pending uploads
rig hub publish --allow-conflicts   # publish despite unresolved conflicts

--no-wait / --force are for pending uploads — the snapshot is consistent locally, you just don't want to wait for the daemon to finish flushing. Lowest risk.
--allow-conflicts is for unresolved conflicts — you're knowingly shipping a workspace with conflict state. Use only when recovering a stuck state and you've eyeballed the files.

Don't use them routinely. Override every time and you'll publish dirty artifacts.

rig hub update has no override. Get sync clean first.

Solo rigs

These checks only apply when [sync] is enabled in rig.toml. Local-only rigs publish and update without any of this — there's no relay to be ahead of or behind.