upstream-sync

name	upstream-sync
description	Sync your workspace after a Vesta upgrade by merging the new stock snapshot into your own history. 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: a plain full checkout of Vesta's stock content (your skills and MEMORY.md). Vesta's daemon keeps that stock 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), and syncing brings the rest of your workspace up to the same version: merge the tag matching the version you now run, so you take every stock change without rewriting any of your commits. To contribute changes back to the Vesta project, see ~/agent/skills/upstream-pr/SKILL.md.

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

Work in ~ and use Git directly. There is no sync wrapper hiding the operation.

First run git status. If Git reports an operation already in progress, finish or abandon that operation before starting another one:

• Merge in progress: resolve every conflicted file, git add <file>, then git commit --no-edit; or restore the pre-update state with git merge --abort.
• Rebase in progress: this is one update interrupted before Vesta switched to merges. Resolve every conflicted file, git add <file>, then git rebase --continue; or restore the pre-update state with git rebase --abort. Once it is gone, all later updates merge.

If birth was interrupted before it finished creating the initial Git history, bootstrap it first. Checking HEAD also repairs an empty .git directory left by an interrupted attach:

git -C ~ rev-parse -q --verify HEAD >/dev/null 2>&1 || \
  bash ~/agent/core/skills/upstream-sync/scripts/attach.sh

Then fetch the stock snapshots from Vesta's read-only local repository. A normal current container has the mount and uses plain git fetch; the fallback exists only for a fleet box whose container rebuild was deferred before this mount shipped:

cd ~
if test -d /run/vesta-upstream/upstream.git; then
  git fetch --no-tags /run/vesta-upstream/upstream.git \
    '+refs/tags/agent-v*:refs/tags/agent-v*'
else
  bash ~/agent/core/skills/upstream-sync/scripts/fetch-upstream.sh
fi
VERSION="$(grep '^version = ' agent/core/pyproject.toml | cut -d'"' -f2)"
TAG="agent-v$VERSION"
git rev-parse -q --verify "refs/tags/$TAG"

If the tag is already in your history, you are done:

git merge-base --is-ancestor "$TAG" HEAD

Otherwise checkpoint anything not committed, then merge the update. git add -A is safe: the read-only agent/core/ mount is ignored by the repository.

git add -A
git diff --cached --quiet || git commit -m checkpoint
git merge --no-ff --no-edit "$TAG"

If the merge stops on a conflict, the resolution 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 commit --no-edit. git merge --abort restores exactly the pre-sync state.
• For agent/MEMORY.md, keep your accumulated knowledge and adopt the stock structure.
• If the merge brought changes, call restart_vesta so the new skills load. Completion is read directly from Git history; there is no separate state marker to maintain.

Status

After fetching and setting TAG as above, standard Git shows the complete answer:

git status --short
git merge-base --is-ancestor "$TAG" HEAD && echo synced || echo needs-sync
git log --oneline "$TAG..HEAD"