upstream-sync

name	upstream-sync
description	Sync your workspace after a Vesta upgrade, rebasing your own changes onto the new version's stock snapshot. Use during the upgrade boot turn, or when the user asks you to get up to date or get the latest changes.

Upstream Sync

Your workspace (~) is a git repository. Vesta's daemon keeps its stock contents in a per-host snapshot repo, bind-mounted read-only at /run/vesta-upstream: one commit per release, tagged agent-vX.Y.Z, fetched locally (no internet involved). When Vesta upgrades, the core you run changes with it (it is a read-only mount), but the rest of your workspace (skills, MEMORY.md, prompts, etc) stays as it was. Syncing closes that gap: rebase onto the tag matching the version you now run, so you take every stock change while everything you changed or added yourself stays on top. To contribute changes back to the Vesta project, see ~/agent/skills/upstream-pr/SKILL.md.

The version you are running: grep '^version = ' ~/agent/core/pyproject.toml

Sync (after an upgrade, when the boot turn asks)

bash ~/agent/core/skills/upstream-sync/scripts/sync.sh

The whole procedure, idempotent. Run it, never the porcelain by hand: it is what keeps git off the read-only engine mount. Exit 5 means it stopped on a conflict, which is yours:

• Conflicts: ALWAYS resolve by hand, and the default is to keep BOTH sides, your change AND the stock change, not pick a winner. Do NOT reflexively git checkout --ours/--theirs or blanket-take one side: that silently drops real work. Even a file you upstreamed comes back genericized, so take stock's form and re-apply your local specifics on top rather than discarding either. Edit each conflicted file so both sides survive, git add <file>, then git rebase --continue and re-run sync.sh to finish. git rebase --abort restores exactly the pre-sync state.
• Paused but git diff --diff-filter=U lists no files? Not a conflict: the rebase stopped on a commit that's now empty (its changes are already in the new stock) or mode-only. Run git add -A then git rebase --continue; if git says the commit is empty, run git rebase --skip. Don't hunt for conflict markers that aren't there.
• git add -A refusing paths "outside of your sparse-checkout definition" means you created a new directory: stage it deliberately with git add --sparse <dir> (never a blanket add -A --sparse, which would also stage engine files from the core mount); sync.sh's cone step covers it once committed.
• For agent/MEMORY.md, keep your accumulated knowledge and adopt the stock structure.
• Then call mark_upstream_synced. If the rebase brought changes, call restart_vesta (after marking) so the new skills load.

Status

~/agent/core/skills/upstream-sync/scripts/status.sh shows what you have changed since your current version's snapshot, and the newest snapshot Vesta's daemon has. Read-only.

Tidy-up (occasionally, e.g. during a dream)

Collapse your accumulated checkpoint commits into one readable commit:

git reset --soft agent-vX.Y.Z             # your current base tag; files untouched
git commit -m "my customizations"