Merge branch 'main' into bb/gui

.github/workflows/docker-publish.yml

@@ -10,48 +10,59 @@ on:
       - 'Dockerfile'
       - 'docker/**'
       - '.github/workflows/docker-publish.yml'
+      - '.github/actions/hermes-smoke-test/**'
+  pull_request:
+    branches: [main]
+    paths:
+      - '**/*.py'
+      - 'pyproject.toml'
+      - 'uv.lock'
+      - 'Dockerfile'
+      - 'docker/**'
+      - '.github/workflows/docker-publish.yml'
+      - '.github/actions/hermes-smoke-test/**'
   release:
     types: [published]
 
 permissions:
   contents: read
 
-# Top-level concurrency: do NOT cancel in-flight builds when a new push lands.
-# Every commit deserves its own SHA-tagged image in the registry, and we guard
-# the :latest tag in a separate job below (with its own concurrency group) so
-# a slow run can't clobber :latest with older bits.
+# Concurrency: push/release runs are NEVER cancelled so every merge gets its
+# own SHA-tagged image; :latest is guarded separately by the move-latest job.
+# PR runs reuse a PR-scoped group with cancel-in-progress: true so rapid
+# pushes to the same PR collapse to the latest commit.
 concurrency:
-  group: docker-${{ github.ref }}
-  cancel-in-progress: false
+  group: docker-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+env:
+  IMAGE_NAME: nousresearch/hermes-agent
 
 jobs:
-  build-and-push:
+  # ---------------------------------------------------------------------------
+  # Build amd64 natively.  This job also runs the smoke tests (basic --help
+  # and the dashboard subcommand regression guard from #9153), because amd64
+  # is the only arch we can `load` into the local daemon on an amd64 runner.
+  # ---------------------------------------------------------------------------
+  build-amd64:
     # Only run on the upstream repository, not on forks
     if: github.repository == 'NousResearch/hermes-agent'
     runs-on: ubuntu-latest
-    timeout-minutes: 60
+    timeout-minutes: 45
     outputs:
-      pushed_sha_tag: ${{ steps.mark_pushed.outputs.pushed }}
+      digest: ${{ steps.push.outputs.digest }}
     steps:
       - name: Checkout code
         uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
         with:
           submodules: recursive
-          # Fetch enough history to run `git merge-base --is-ancestor` in the
-          # move-latest job.  That job reuses this checkout via its own
-          # actions/checkout call, but commits reachable from main up to ~1000
-          # back are plenty for any realistic race window.
-          fetch-depth: 1000
-
-      - name: Set up QEMU
-        uses: docker/setup-qemu-action@c7c53464625b32c7a7e944ae62b3e17d2b600130  # v3
 
       - name: Set up Docker Buildx
         uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f  # v3
 
-      # Build amd64 only so we can `load` the image for smoke testing.
-      # `load: true` cannot export a multi-arch manifest to the local daemon.
-      # The multi-arch build follows on push to main / release.
+      # Build once, load into the local daemon for smoke testing.  Cached
+      # to gha with a per-arch scope; the push step below reuses every
+      # layer from this build.
       - name: Build image (amd64, smoke test)
         uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8  # v6
         with:
@@ -59,36 +70,14 @@ jobs:
           file: Dockerfile
           load: true
           platforms: linux/amd64
-          tags: nousresearch/hermes-agent:test
-          cache-from: type=gha
-          cache-to: type=gha,mode=max
+          tags: ${{ env.IMAGE_NAME }}:test
+          cache-from: type=gha,scope=docker-amd64
+          cache-to: type=gha,mode=max,scope=docker-amd64
 
-      - name: Test image starts
-        run: |
-          mkdir -p /tmp/hermes-test
-          sudo chown -R 10000:10000 /tmp/hermes-test
-          # The image runs as the hermes user (UID 10000).  GitHub Actions
-          # creates /tmp/hermes-test root-owned by default, which hermes
-          # can't write to — chown it to match the in-container UID before
-          # bind-mounting.  Real users doing `docker run -v ~/.hermes:...`
-          # with their own UID hit the same issue and have their own
-          # remediations (HERMES_UID env var, or chown locally).
-          docker run --rm \
-            -v /tmp/hermes-test:/opt/data \
-            --entrypoint /opt/hermes/docker/entrypoint.sh \
-            nousresearch/hermes-agent:test --help
-
-      - name: Test dashboard subcommand
-        run: |
-          mkdir -p /tmp/hermes-test
-          sudo chown -R 10000:10000 /tmp/hermes-test
-          # Verify the dashboard subcommand is included in the Docker image.
-          # This prevents regressions like #9153 where the dashboard command
-          # was present in source but missing from the published image.
-          docker run --rm \
-            -v /tmp/hermes-test:/opt/data \
-            --entrypoint /opt/hermes/docker/entrypoint.sh \
-            nousresearch/hermes-agent:test dashboard --help
+      - name: Smoke test image
+        uses: ./.github/actions/hermes-smoke-test
+        with:
+          image: ${{ env.IMAGE_NAME }}:test
 
       - name: Log in to Docker Hub
         if: github.event_name == 'push' && github.ref == 'refs/heads/main' || github.event_name == 'release'
@@ -97,61 +86,229 @@ jobs:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_TOKEN }}
 
-      # Always push a per-commit SHA tag on main.  This is race-free because
-      # every commit has a unique SHA — concurrent runs can't clobber each
-      # other here.  We also embed the git SHA as an OCI label so the
-      # move-latest job (below) can read it back off the registry's `:latest`.
-      - name: Push multi-arch image with SHA tag (main branch)
-        id: push_sha
-        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+      # Push amd64 by digest only (no tag).  The merge job assembles the
+      # tagged manifest list.  `push-by-digest=true` is docker's recommended
+      # pattern for multi-runner multi-platform builds.
+      #
+      # We apply the OCI revision label here (and again on arm64) because
+      # the move-latest job reads it off the linux/amd64 sub-manifest config
+      # of `:latest` to decide whether it's safe to advance.  The label must
+      # be on each per-arch image — manifest lists themselves don't carry
+      # image config labels.
+      - name: Push amd64 by digest
+        id: push
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main' || github.event_name == 'release'
         uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8  # v6
         with:
           context: .
           file: Dockerfile
-          push: true
-          platforms: linux/amd64,linux/arm64
-          tags: nousresearch/hermes-agent:sha-${{ github.sha }}
+          platforms: linux/amd64
           labels: |
             org.opencontainers.image.revision=${{ github.sha }}
-          cache-from: type=gha
-          cache-to: type=gha,mode=max
+          outputs: type=image,name=${{ env.IMAGE_NAME }},push-by-digest=true,name-canonical=true,push=true
+          cache-from: type=gha,scope=docker-amd64
+          cache-to: type=gha,mode=max,scope=docker-amd64
 
+      # Write the digest to a file and upload it as an artifact so the
+      # merge job can stitch both per-arch digests into a manifest list.
+      - name: Export digest
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main' || github.event_name == 'release'
+        run: |
+          mkdir -p /tmp/digests
+          digest="${{ steps.push.outputs.digest }}"
+          touch "/tmp/digests/${digest#sha256:}"
+
+      - name: Upload digest artifact
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main' || github.event_name == 'release'
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02  # v4
+        with:
+          name: digest-amd64
+          path: /tmp/digests/*
+          if-no-files-found: error
+          retention-days: 1
+
+  # ---------------------------------------------------------------------------
+  # Build arm64 natively on GitHub's free arm64 runner.  This replaces the
+  # previous QEMU-emulated arm64 build, which was ~5-10x slower and shared
+  # a cache scope with amd64.  Matches the amd64 job's shape: build+load,
+  # smoke test, then on push/release push by digest.
+  # ---------------------------------------------------------------------------
+  build-arm64:
+    if: github.repository == 'NousResearch/hermes-agent'
+    runs-on: ubuntu-24.04-arm
+    timeout-minutes: 45
+    outputs:
+      digest: ${{ steps.push.outputs.digest }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+        with:
+          submodules: recursive
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f  # v3
+
+      # Build once, load into the local daemon for smoke testing.  Cached
+      # to gha with a per-arch scope; the push step below reuses every
+      # layer from this build.
+      - name: Build image (arm64, smoke test)
+        uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8  # v6
+        with:
+          context: .
+          file: Dockerfile
+          load: true
+          platforms: linux/arm64
+          tags: ${{ env.IMAGE_NAME }}:test
+          cache-from: type=gha,scope=docker-arm64
+          cache-to: type=gha,mode=max,scope=docker-arm64
+
+      - name: Smoke test image
+        uses: ./.github/actions/hermes-smoke-test
+        with:
+          image: ${{ env.IMAGE_NAME }}:test
+
+      - name: Log in to Docker Hub
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main' || github.event_name == 'release'
+        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9  # v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Push arm64 by digest
+        id: push
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main' || github.event_name == 'release'
+        uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8  # v6
+        with:
+          context: .
+          file: Dockerfile
+          platforms: linux/arm64
+          labels: |
+            org.opencontainers.image.revision=${{ github.sha }}
+          outputs: type=image,name=${{ env.IMAGE_NAME }},push-by-digest=true,name-canonical=true,push=true
+          cache-from: type=gha,scope=docker-arm64
+          cache-to: type=gha,mode=max,scope=docker-arm64
+
+      - name: Export digest
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main' || github.event_name == 'release'
+        run: |
+          mkdir -p /tmp/digests
+          digest="${{ steps.push.outputs.digest }}"
+          touch "/tmp/digests/${digest#sha256:}"
+
+      - name: Upload digest artifact
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main' || github.event_name == 'release'
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02  # v4
+        with:
+          name: digest-arm64
+          path: /tmp/digests/*
+          if-no-files-found: error
+          retention-days: 1
+
+  # ---------------------------------------------------------------------------
+  # Stitch both per-arch digests into a single tagged multi-arch manifest.
+  # This is a registry-side operation — no building, no layer re-push —
+  # so it runs in ~30 seconds.  On main pushes it produces :sha-<sha>.
+  # On releases it produces :<release_tag_name>.
+  # ---------------------------------------------------------------------------
+  merge:
+    if: github.repository == 'NousResearch/hermes-agent' && (github.event_name == 'push' && github.ref == 'refs/heads/main' || github.event_name == 'release')
+    runs-on: ubuntu-latest
+    needs: [build-amd64, build-arm64]
+    timeout-minutes: 10
+    outputs:
+      pushed_sha_tag: ${{ steps.mark_pushed.outputs.pushed }}
+    steps:
+      - name: Download digests
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093  # v4
+        with:
+          path: /tmp/digests
+          pattern: digest-*
+          merge-multiple: true
+
+      - name: Set up Docker Buildx
+        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f  # v3
+
+      - name: Log in to Docker Hub
+        uses: docker/login-action@c94ce9fb468520275223c153574b00df6fe4bcc9  # v3
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      # Compute the tag for this run.  Main pushes use sha-<sha> (so every
+      # commit gets its own immutable tag); releases use the release tag name.
+      - name: Compute tag
+        id: tag
+        run: |
+          if [ "${{ github.event_name }}" = "release" ]; then
+            echo "tag=${{ github.event.release.tag_name }}" >> "$GITHUB_OUTPUT"
+          else
+            echo "tag=sha-${{ github.sha }}" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Create manifest list and push
+        working-directory: /tmp/digests
+        run: |
+          set -euo pipefail
+          # Build the arg array from each digest file (filename = the digest
+          # hex, with no sha256: prefix; empty file content, only the name
+          # matters).  Using an array avoids shellcheck SC2046 and keeps
+          # every digest a single argv token even under pathological names.
+          args=()
+          for digest_file in *; do
+            args+=("${IMAGE_NAME}@sha256:${digest_file}")
+          done
+          docker buildx imagetools create \
+            -t "${IMAGE_NAME}:${TAG}" \
+            "${args[@]}"
+        env:
+          IMAGE_NAME: ${{ env.IMAGE_NAME }}
+          TAG: ${{ steps.tag.outputs.tag }}
+
+      - name: Inspect image
+        run: |
+          docker buildx imagetools inspect "${IMAGE_NAME}:${TAG}"
+        env:
+          IMAGE_NAME: ${{ env.IMAGE_NAME }}
+          TAG: ${{ steps.tag.outputs.tag }}
+
+      # Signal to move-latest that the SHA tag is live.  Only on main pushes;
+      # releases don't trigger move-latest (they use their own release tag).
       - name: Mark SHA tag pushed
         id: mark_pushed
         if: github.event_name == 'push' && github.ref == 'refs/heads/main'
         run: echo "pushed=true" >> "$GITHUB_OUTPUT"
 
-      - name: Push multi-arch image (release)
-        if: github.event_name == 'release'
-        uses: docker/build-push-action@10e90e3645eae34f1e60eeb005ba3a3d33f178e8  # v6
-        with:
-          context: .
-          file: Dockerfile
-          push: true
-          platforms: linux/amd64,linux/arm64
-          tags: nousresearch/hermes-agent:${{ github.event.release.tag_name }}
-          cache-from: type=gha
-          cache-to: type=gha,mode=max
-
-  # Second job: moves `:latest` to point at the SHA tag the first job pushed.
+  # ---------------------------------------------------------------------------
+  # Move :latest to point at the SHA tag the merge job pushed.
   #
-  # Has its own concurrency group with `cancel-in-progress: true`, which
-  # gives us the serialization we need: if a newer push arrives while an
-  # older run is mid-way through this job, the older run is cancelled
-  # before it can clobber `:latest`.  Combined with the ancestor check
-  # below, this means `:latest` only ever moves forward in git history.
+  # The real serialization guarantee comes from the top-level concurrency
+  # group (`docker-${{ github.ref }}` with `cancel-in-progress: false`),
+  # which ensures at most one workflow run for this ref executes at a time.
+  # That means two move-latest steps for the same ref cannot overlap.
+  #
+  # This job has its own concurrency group as defense-in-depth: if the
+  # top-level group is ever loosened, queued move-latests will run serially
+  # in arrival order, each one running the ancestor check below and either
+  # advancing :latest or skipping.  `cancel-in-progress: false` matches the
+  # top-level setting — we don't want rapid pushes to cancel a queued
+  # move-latest, because the ancestor check is the real safety mechanism
+  # and queueing is cheap (move-latest is a ~30s registry op).
+  #
+  # Combined with the ancestor check, this means :latest only ever moves
+  # forward in git history.
+  # ---------------------------------------------------------------------------
   move-latest:
     if: |
       github.repository == 'NousResearch/hermes-agent'
       && github.event_name == 'push'
       && github.ref == 'refs/heads/main'
-      && needs.build-and-push.outputs.pushed_sha_tag == 'true'
-    needs: build-and-push
+      && needs.merge.outputs.pushed_sha_tag == 'true'
+    needs: merge
     runs-on: ubuntu-latest
     timeout-minutes: 10
     concurrency:
       group: docker-move-latest-${{ github.ref }}
-      cancel-in-progress: true
+      cancel-in-progress: false
     steps:
       - name: Checkout code
         uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
@@ -167,11 +324,11 @@ jobs:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_TOKEN }}
 
-      # Read the git revision label off the current `:latest` manifest, then
+      # Read the git revision label off the current :latest manifest, then
       # use `git merge-base --is-ancestor` to check whether our commit is a
-      # descendant of it.  If `:latest` doesn't exist yet, or its label is
+      # descendant of it.  If :latest doesn't exist yet, or its label is
       # missing, we treat that as "safe to publish".  If another run already
-      # advanced `:latest` past us (or diverged), we skip and leave it alone.
+      # advanced :latest past us (or diverged), we skip and leave it alone.
       - name: Decide whether to move :latest
         id: latest_check
         run: |

.github/workflows/lint.yml

@@ -1,9 +1,12 @@
 name: Lint (ruff + ty)
 
-# Surface ruff and ty diagnostics as a diff vs the target branch.
-# This check is advisory only ATM it always exits zero and never blocks merge.
-# It posts a Markdown summary to the workflow run and, for pull requests,
-# comments the same summary on the PR.
+# Two things here:
+#   1. Advisory diff — ruff + ty diagnostics as a diff vs the target branch.
+#      Posts a Markdown summary and a PR comment. Exit zero always.
+#   2. Blocking ``ruff check .`` — enforces the explicit rules in
+#      ``[tool.ruff.lint.select]`` (currently PLW1514). Failure blocks merge.
+#      Separate job so the advisory diff still runs and posts even when
+#      enforcement fails.
 
 on:
   push:
@@ -149,3 +152,50 @@ jobs:
                 body: fullBody,
               });
             }
+
+
+  ruff-blocking:
+    # Enforce the rules in pyproject.toml [tool.ruff.lint.select]. Currently
+    # PLW1514 (unspecified-encoding) — catches bare ``open()`` /
+    # ``read_text()`` / ``write_text()`` calls that default to locale
+    # encoding on Windows. Failure here blocks merge; the advisory
+    # ``lint-diff`` job above runs independently so reviewers still get
+    # the diff comment even when enforcement fails.
+    name: ruff enforcement (blocking)
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86 # v5
+
+      - name: Install ruff
+        run: uv tool install ruff
+
+      - name: ruff check .
+        # No --exit-zero, no || true. Exit code propagates to the job,
+        # which propagates to the required-check gate.
+        run: |
+          ruff check .
+
+  windows-footguns:
+    # Static guardrails on Windows-unsafe Python primitives — os.kill(pid, 0),
+    # os.killpg, os.setsid, signal.SIGKILL without getattr fallback,
+    # shebang scripts via subprocess, bare open() without encoding=, etc.
+    # See scripts/check-windows-footguns.py for the full rule list.
+    name: Windows footguns (blocking)
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+      - name: Set up Python
+        uses: actions/setup-python@0b93645e9fea7318ecaed2b359559ac225c90a2b # v5
+        with:
+          python-version: "3.11"
+
+      - name: Run footgun checker
+        run: python scripts/check-windows-footguns.py --all

.github/workflows/uv-lockfile-check.yml

@@ -0,0 +1,119 @@
+name: uv.lock check
+
+# Verify uv.lock is in sync with pyproject.toml.  Blocking check — PRs
+# that modify pyproject.toml without regenerating uv.lock (or vice versa)
+# must not merge, because the Docker build's `uv sync --frozen` step will
+# fail on a stale lockfile and we'd rather catch it here than in the
+# docker-publish workflow on main.
+#
+# ─────────────────────────────────────────────────────────────────────────
+# IMPORTANT: this check runs against the MERGED state, not just your branch
+# ─────────────────────────────────────────────────────────────────────────
+#
+# For `pull_request` events, GitHub checks out `refs/pull/<N>/merge` by
+# default — a synthetic commit that merges your PR branch into the CURRENT
+# state of `main`.  That means the pyproject.toml evaluated here is
+# `main's pyproject.toml + your PR's changes to pyproject.toml`, not just
+# what's on your branch.
+#
+# Failure mode this creates: if `main` has advanced since you branched
+# (e.g. someone merged a PR that added a dep to pyproject.toml + its
+# corresponding uv.lock entries), your branch's uv.lock is missing those
+# new entries.  `uv lock --check` resolves against the merged pyproject
+# and sees a lockfile that doesn't cover all the current deps → fails
+# with "The lockfile at uv.lock needs to be updated."
+#
+# This can be confusing: `uv lock --check` passes locally (your branch
+# is internally consistent) but fails in CI (merged state isn't).
+#
+# Fix is to sync your branch with main and regenerate the lockfile:
+#
+#     git fetch origin main
+#     git rebase origin/main      # or merge, whatever the repo prefers
+#     uv lock                     # regenerates uv.lock against new pyproject.toml
+#     git add uv.lock
+#     git commit -m "chore: refresh uv.lock after rebase onto main"
+#     git push --force-with-lease # if you rebased
+#
+# If you also changed pyproject.toml in your PR, `uv lock` handles that
+# at the same time — one regeneration covers both your changes and the
+# drift from main.
+#
+# This is the correct behavior!  The check is protecting main's Docker
+# build: a post-merge build would see the same merged state and fail
+# the same way.  Better to catch it here than after merge.
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'pyproject.toml'
+      - 'uv.lock'
+      - '.github/workflows/uv-lockfile-check.yml'
+  pull_request:
+    branches: [main]
+    paths:
+      - 'pyproject.toml'
+      - 'uv.lock'
+      - '.github/workflows/uv-lockfile-check.yml'
+
+permissions:
+  contents: read
+
+concurrency:
+  group: uv-lockfile-check-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  check:
+    name: uv lock --check
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@d4b2f3b6ecc6e67c4457f6d3e41ec42d3d0fcb86  # v5
+
+      # `uv lock --check` re-resolves the project from pyproject.toml and
+      # compares the result to uv.lock, exiting non-zero if they disagree.
+      # No network writes, no file modifications.
+      #
+      # On PRs this runs against the merge commit (see comment at the top
+      # of this file) — failures often mean "your branch is behind main,
+      # rebase and regenerate uv.lock."
+      - name: Verify uv.lock is up-to-date
+        run: |
+          if ! uv lock --check; then
+            cat <<'EOF' >> "$GITHUB_STEP_SUMMARY"
+          ## ❌ uv.lock is out of sync with pyproject.toml
+
+          **If this is a PR:** this check runs against the merged state
+          (your branch + current `main`), not just your branch.  If
+          `uv lock --check` passes locally, your branch is likely behind
+          `main` — recent changes to `pyproject.toml` on `main` aren't
+          reflected in your branch's `uv.lock` yet.
+
+          To fix, sync with main and regenerate the lockfile:
+
+          ```bash
+          git fetch origin main
+          git rebase origin/main   # or `git merge origin/main`
+          uv lock                  # regenerate against new pyproject.toml
+          git add uv.lock
+          git commit -m "chore: refresh uv.lock after syncing with main"
+          git push --force-with-lease  # drop --force-with-lease if you merged
+          ```
+
+          **If you only changed pyproject.toml:** run `uv lock` locally
+          and commit the result.
+
+          This check is blocking because the Docker image build uses
+          `uv sync --frozen --extra all`, which rejects stale lockfiles
+          — catching it here avoids a ~15 min failed docker-publish run
+          on `main` post-merge.
+          EOF
+            echo "::error title=uv.lock out of sync::Run \`uv lock\` locally and commit the result. If on a PR, sync with main first."
+            exit 1
+          fi