Skip to content

armgit / cua

Public Imported from GitHub
0

Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.

ci(images): rebuild and pin Space images on every cua-spacesd release (#4574)

ddupont8fdcd83ede8d
diff --git a/.github/workflows/cd-bench-images.yml b/.github/workflows/cd-bench-images.yml
index c9d514666f..4f69a047f5 100644
--- a/.github/workflows/cd-bench-images.yml
+++ b/.github/workflows/cd-bench-images.yml
@@ -54,6 +54,22 @@ on:
description: "Verify and promote this already-staged stamp (lock.json) instead of building (needs push=true)"
type: string
default: ""
+ # cd-images-spacesd-release.yml (bench=osworld push=true) on every
+ # cua-spacesd release.
+ workflow_call:
+ inputs:
+ bench:
+ type: string
+ default: web
+ push:
+ type: boolean
+ default: false
+ amd64_runner:
+ type: string
+ default: ubuntu-24.04
+ promote_stamp:
+ type: string
+ default: ""
concurrency:
group: cd-bench-images-${{ github.ref }}-${{ inputs.bench || 'pr' }}
@@ -80,7 +96,8 @@ jobs:
for f in scripts/bench-images/*.sh libs/images/bench/*/vm/*.sh; do bash -n "$f"; done
meta:
- if: github.event_name == 'workflow_dispatch'
+ # A dispatch, or a call (which sees its caller's event).
+ if: github.event_name != 'pull_request'
needs: checks
runs-on: ubuntu-latest
outputs:
diff --git a/.github/workflows/cd-image-linux.yml b/.github/workflows/cd-image-linux.yml
index e201001862..47049e9ddd 100644
--- a/.github/workflows/cd-image-linux.yml
+++ b/.github/workflows/cd-image-linux.yml
@@ -103,6 +103,20 @@ on:
description: "Only doctor and attest published disk children, ARCH@sha256:... comma separated (the strict VM doctor, report referrer and ledger entry); pushes no image"
type: string
default: ""
+ # cd-images-spacesd-release.yml on every cua-spacesd release. A called
+ # workflow sees the caller's event (workflow_run), so meta treats it like
+ # a dispatch.
+ workflow_call:
+ inputs:
+ publish:
+ type: boolean
+ default: false
+ spacesd_source:
+ type: string
+ default: local
+ spacesd_version:
+ type: string
+ default: latest
concurrency:
group: cd-image-linux-${{ github.ref }}
@@ -145,7 +159,8 @@ jobs:
publish=false
case "$EVENT" in
push) [[ "$REF" == refs/tags/linux-image-v* ]] && publish=true ;;
- workflow_dispatch) [ "$INPUT_PUBLISH" = true ] && publish=true ;;
+ # workflow_run: called by cd-images-spacesd-release.yml.
+ workflow_dispatch|workflow_run) [ "$INPUT_PUBLISH" = true ] && publish=true ;;
# Publishes only the tiers whose content changed (the changes job).
schedule) publish=true ;;
esac
diff --git a/.github/workflows/cd-image-omarchy.yml b/.github/workflows/cd-image-omarchy.yml
index d85a23d50d..0dde4d257b 100644
--- a/.github/workflows/cd-image-omarchy.yml
+++ b/.github/workflows/cd-image-omarchy.yml
@@ -65,6 +65,17 @@ on:
type: choice
options: [edge]
default: edge
+ # cd-images-spacesd-release.yml on every cua-spacesd release. A called
+ # workflow sees the caller's event (workflow_run), so meta treats it like
+ # a dispatch.
+ workflow_call:
+ inputs:
+ publish:
+ type: boolean
+ default: false
+ series:
+ type: string
+ default: edge
concurrency:
group: cd-image-omarchy-${{ github.ref }}
@@ -103,7 +114,8 @@ jobs:
publish=false
case "$EVENT" in
push) [[ "$REF" == refs/tags/omarchy-image-v* ]] && publish=true ;;
- workflow_dispatch) [ "$INPUT_PUBLISH" = true ] && publish=true ;;
+ # workflow_run: called by cd-images-spacesd-release.yml.
+ workflow_dispatch|workflow_run) [ "$INPUT_PUBLISH" = true ] && publish=true ;;
# Publishes only when the content changed (the build job decides).
schedule) publish=true ;;
esac
diff --git a/.github/workflows/cd-image-windows.yml b/.github/workflows/cd-image-windows.yml
index ec216c06b0..f107efa6b0 100644
--- a/.github/workflows/cd-image-windows.yml
+++ b/.github/workflows/cd-image-windows.yml
@@ -31,6 +31,18 @@ on:
mem:
type: string
default: "4G"
+ # cd-images-spacesd-release.yml (stage=publish) on every cua-spacesd release.
+ workflow_call:
+ inputs:
+ stage:
+ type: string
+ default: build
+ base:
+ type: string
+ default: "ghcr.io/trycua/windows@sha256:a2966dac6c68a60f67addcc2c23db40ca1048a37616b1d6d39abc25dab9ce1f4"
+ mem:
+ type: string
+ default: "4G"
permissions:
contents: read
diff --git a/.github/workflows/cd-images-spacesd-release.yml b/.github/workflows/cd-images-spacesd-release.yml
new file mode 100644
index 0000000000..7d1498c11d
--- /dev/null
+++ b/.github/workflows/cd-images-spacesd-release.yml
@@ -0,0 +1,204 @@
+name: "CD: Images on cua-spacesd release"
+
+# Every cua-spacesd release rebuilds the Space images on it and opens ONE pins
+# PR, with no hand dispatches:
+#
+# CD: cua-spacesd (tag cua-spacesd-vX.Y.Z) completes
+# -> linux, omarchy, windows, bench: the image workflows, called as
+# reusable workflows with their publish inputs, in parallel (each one
+# builds, gates on `cua-spacesd doctor --strict` and promotes, exactly
+# as a manual workflow_dispatch with publish=true does)
+# -> pins: scripts/images/pins-pr.sh opens or updates the PR on branch
+# images/pins. An OS is pinned only when its floating tags resolve to
+# NEW digests whose attached doctor reports say cua-spacesd X.Y.Z
+# (scripts/images/image_pins.py), so a green run that pushed nothing
+# cannot move a pin; the job fails loudly if that happens. The PR body
+# is a per-OS checklist, and the PR is regenerated from main and the
+# registry each run.
+#
+# macOS cannot build here (Lume needs an Apple silicon host; there is no
+# hosted macOS-VM runner): the PR lists it as pending with the command,
+# `scripts/images/release-macos.sh X.Y.Z`, which builds, gates, pushes and
+# promotes on a Mac and then dispatches this workflow with build=false to add
+# macOS to the same PR. Benchmark images open their own catalog PR from
+# cd-bench-images.yml (bench lock files are not registry state).
+#
+# Why workflow_run: cd-cua-spacesd.yml publishes the release with
+# GITHUB_TOKEN, and events made with GITHUB_TOKEN (release: published) start
+# no workflows. workflow_run of the tag-pushed run fires once its assets are
+# attached, which is what cd-image-linux (spacesd_source=release) downloads.
+#
+# Why the pins job uses the release GitHub App (RELEASE_APP_ID /
+# RELEASE_APP_PRIVATE_KEY, as release-please.yml): a PR opened with
+# GITHUB_TOKEN runs no checks, so it could never be merged as is.
+#
+# Manual: workflow_dispatch with a version (default libs/cua-spacesd/VERSION)
+# reruns everything; build=false only refreshes the pins PR. The image
+# workflows keep their own workflow_dispatch paths.
+
+on:
+ workflow_run:
+ workflows: ["CD: cua-spacesd"]
+ types: [completed]
+ workflow_dispatch:
+ inputs:
+ version:
+ description: "cua-spacesd version X.Y.Z the images must report (default libs/cua-spacesd/VERSION)"
+ type: string
+ default: ""
+ build:
+ description: "Rebuild and publish the CI images first (false: only refresh the pins PR, e.g. after release-macos.sh)"
+ type: boolean
+ default: true
+
+permissions:
+ contents: read
+
+# One release at a time; a newer release queued behind it replaces any older
+# pending one, so the newest version wins.
+concurrency:
+ group: cd-images-spacesd-release
+ cancel-in-progress: false
+
+jobs:
+ resolve:
+ # Registry names belong to trycua/cua (staging builds no images); only a
+ # successful tag-pushed cua-spacesd run counts.
+ if: >-
+ github.repository == 'trycua/cua' && (
+ github.event_name == 'workflow_dispatch' || (
+ github.event.workflow_run.conclusion == 'success' &&
+ github.event.workflow_run.event == 'push' &&
+ startsWith(github.event.workflow_run.head_branch, 'cua-spacesd-v')))
+ runs-on: ubuntu-latest
+ timeout-minutes: 5
+ outputs:
+ version: ${{ steps.v.outputs.version }}
+ build: ${{ steps.v.outputs.build }}
+ steps:
+ - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+ with:
+ persist-credentials: false
+ - id: v
+ env:
+ GH_TOKEN: ${{ github.token }}
+ TAG: ${{ github.event.workflow_run.head_branch }}
+ INPUT_VERSION: ${{ inputs.version }}
+ INPUT_BUILD: ${{ inputs.build }}
+ run: |
+ set -euo pipefail
+ if [ "$GITHUB_EVENT_NAME" = workflow_run ]; then
+ version="${TAG#cua-spacesd-v}" build=true
+ else
+ version="${INPUT_VERSION:-$(cat libs/cua-spacesd/VERSION)}" build="$INPUT_BUILD"
+ fi
+ version="${version#cua-spacesd-v}"; version="${version#v}"
+ [[ "$version" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]] || { echo "::error::not a version: $version"; exit 1; }
+ # Images pin a published release only (never a draft or prerelease).
+ state="$(gh release view "cua-spacesd-v$version" -R "$GITHUB_REPOSITORY" --json isDraft,isPrerelease -q '.isDraft or .isPrerelease')"
+ [ "$state" = false ] || { echo "::error::cua-spacesd-v$version is not a published release"; exit 1; }
+ { echo "version=$version"; echo "build=$build"; } | tee -a "$GITHUB_OUTPUT"
+ echo "### cua-spacesd $version (build images: $build)" >>"$GITHUB_STEP_SUMMARY"
+
+ # The image workflows, unchanged except for their workflow_call trigger.
+ # A called workflow's jobs can hold no more than the permissions granted
+ # here, so each grant is the union of its jobs' own blocks.
+ linux:
+ needs: resolve
+ if: needs.resolve.outputs.build == 'true'
+ uses: ./.github/workflows/cd-image-linux.yml
+ permissions:
+ contents: write
+ packages: write
+ actions: read
+ issues: write
+ with:
+ publish: true
+ spacesd_source: release
+ spacesd_version: ${{ needs.resolve.outputs.version }}
+
+ omarchy:
+ needs: resolve
+ if: needs.resolve.outputs.build == 'true'
+ uses: ./.github/workflows/cd-image-omarchy.yml
+ permissions:
+ contents: write
+ packages: write
+ issues: write
+ with:
+ publish: true
+ series: edge
+
+ windows:
+ needs: resolve
+ if: needs.resolve.outputs.build == 'true'
+ uses: ./.github/workflows/cd-image-windows.yml
+ permissions:
+ contents: write
+ packages: write
+ with:
+ stage: publish
+
+ # Builds cua-spacesd from this checkout (main at the release); its promote
+ # job opens the bench catalog PR itself.
+ bench:
+ needs: resolve
+ if: needs.resolve.outputs.build == 'true'
+ uses: ./.github/workflows/cd-bench-images.yml
+ permissions:
+ contents: write
+ packages: write
+ pull-requests: write
+ with:
+ bench: osworld
+ push: true
+
+ pins:
+ needs: [resolve, linux, omarchy, windows, bench]
+ # Also after a failed or skipped build: whatever did reach the version is
+ # pinned, and the PR lists the rest as pending.
+ if: ${{ !cancelled() && needs.resolve.result == 'success' }}
+ runs-on: ubuntu-24.04
+ timeout-minutes: 60
+ steps:
+ - name: Release GitHub App token (the PR's checks run)
+ id: app-token
+ uses: actions/create-github-app-token@d72941d797fd3113feb6b93fd0dec494b13a2547 # v1
+ with:
+ app-id: ${{ secrets.RELEASE_APP_ID }}
+ private-key: ${{ secrets.RELEASE_APP_PRIVATE_KEY }}
+ owner: ${{ github.repository_owner }}
+ repositories: ${{ github.event.repository.name }}
+ - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+ with:
+ ref: main
+ token: ${{ steps.app-token.outputs.token }}
+ - name: Install protoc
+ uses: arduino/setup-protoc@c65c819552d16ad3c9b72d9dfd5ba5237b9c906b # v3.0.0
+ with:
+ version: "29.x"
+ repo-token: ${{ secrets.GITHUB_TOKEN }}
+ - name: Tools (crane, oras, jq, zstd) and Rust
+ run: |
+ scripts/images/install-release-tools.sh --push-only
+ cd libs/cua && (rustup show active-toolchain || rustup toolchain install)
+ - uses: Swatinem/rust-cache@9d47c6ad4b02e050fd481d890b2ea34778fd09d6 # v2
+ with:
+ workspaces: libs/cua
+ key: images-pins
+ - name: Commit as the App's bot user (contributor-attribution resolves it)
+ env:
+ GH_TOKEN: ${{ steps.app-token.outputs.token }}
+ SLUG: ${{ steps.app-token.outputs.app-slug }}
+ run: |
+ set -euo pipefail
+ id="$(gh api "/users/${SLUG}%5Bbot%5D" --jq .id)"
+ git config user.name "${SLUG}[bot]"
+ git config user.email "${id}+${SLUG}[bot]@users.noreply.github.com"
+ - name: Open or update the pins PR (images/pins)
+ env:
+ GH_TOKEN: ${{ steps.app-token.outputs.token }}
+ VERSION: ${{ needs.resolve.outputs.version }}
+ RESULTS: linux=${{ needs.linux.result }},omarchy=${{ needs.omarchy.result }},windows=${{ needs.windows.result }}
+ RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+ run: scripts/images/pins-pr.sh "$VERSION" --results "$RESULTS" --run-url "$RUN_URL"
diff --git a/.github/workflows/ci-images-spacesd-lag.yml b/.github/workflows/ci-images-spacesd-lag.yml
new file mode 100644
index 0000000000..432cb36e20
--- /dev/null
+++ b/.github/workflows/ci-images-spacesd-lag.yml
@@ -0,0 +1,67 @@
+name: "CI: Images on the current cua-spacesd"
+
+# Reports catalog images (libs/images/sandbox-images.json) whose pinned
+# digests do not run the cua-spacesd in libs/cua-spacesd/VERSION, per their
+# attached doctor reports (scripts/images/image_pins.py lag). Runs on PRs that
+# touch the catalog or VERSION, and on Release Please PRs (the manifest), so a
+# Cua Spaces release shows when it would ship pins on an older daemon.
+#
+# It only warns and never fails, on purpose:
+# - Images legitimately lag a cua-spacesd release by a few hours: the CI
+# images rebuild automatically (cd-images-spacesd-release.yml) and macOS
+# needs a Mac (scripts/images/release-macos.sh). A blocking check would make
+# every PR in that window red for nothing.
+# - Blocking an app release (or hotfix) on images would be worse than shipping
+# one on the previous daemon's images, which keep working.
+# The images/pins PR is the place that closes the gap; this check makes the gap
+# visible (warning annotations and a step summary table) where the decision
+# is made. A registry hiccup cannot fail it either (continue-on-error).
+
+on:
+ pull_request:
+ paths:
+ - "libs/images/sandbox-images.json"
+ - "libs/cua-spacesd/VERSION"
+ - ".release-please-manifest.json"
+ - "scripts/images/image_pins.py"
+ - ".github/workflows/ci-images-spacesd-lag.yml"
+
+permissions:
+ contents: read
+
+concurrency:
+ group: ci-images-spacesd-lag-${{ github.ref }}
+ cancel-in-progress: true
+
+jobs:
+ lag:
+ name: Catalog images on the current cua-spacesd (warning only)
+ runs-on: ubuntu-latest
+ timeout-minutes: 10
+ steps:
+ - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+ with:
+ persist-credentials: false
+ - name: Does this PR release cua-spacesd itself?
+ id: scope
+ env:
+ BASE_SHA: ${{ github.event.pull_request.base.sha }}
+ run: |
+ set -euo pipefail
+ git fetch -q --depth=1 origin "$BASE_SHA"
+ before="$(git show "$BASE_SHA:libs/cua-spacesd/VERSION")"
+ after="$(cat libs/cua-spacesd/VERSION)"
+ if [ "$before" != "$after" ]; then
+ echo "::notice title=Images follow this release::This PR moves cua-spacesd $before -> $after. Once it is released, cd-images-spacesd-release.yml rebuilds the images and opens the images/pins PR."
+ echo "skip=true" >>"$GITHUB_OUTPUT"
+ fi
+ - name: Install crane and oras
+ if: steps.scope.outputs.skip != 'true'
+ run: |
+ go install github.com/google/go-containerregistry/cmd/[email protected]
+ go install oras.land/oras/cmd/[email protected]
+ echo "$(go env GOPATH)/bin" >>"$GITHUB_PATH"
+ - name: Catalog digests vs libs/cua-spacesd/VERSION
+ if: steps.scope.outputs.skip != 'true'
+ continue-on-error: true
+ run: python3 scripts/images/image_pins.py lag
diff --git a/libs/images/README.md b/libs/images/README.md
index b3ec8e69e9..a0ff7fb1bd 100644
--- a/libs/images/README.md
+++ b/libs/images/README.md
@@ -243,6 +243,16 @@ A publish run whose gates and pushes passed but that stopped before its floating
Pull requests run step 1 only. The plain images are built and smoke tested in the same workflow and not published.
+#### On every cua-spacesd release (`cd-images-spacesd-release.yml`)
+
+Nobody dispatches the image builds after a cua-spacesd release:
+
+1. **Builds:** once `CD: cua-spacesd` finishes a `cua-spacesd-vX.Y.Z` tag, the workflow calls `cd-image-linux.yml` (`spacesd_source=release`), `cd-image-omarchy.yml`, `cd-image-windows.yml` (`stage=publish`) and `cd-bench-images.yml` (`bench=osworld push=true`), all in parallel and with the same gates as a manual publish.
+2. **Pins PR:** then `scripts/images/pins-pr.sh` opens or updates one PR from the branch `images/pins`. It changes `sandbox-images.json` (digests and sizes), the README pin rows and the app-core parity goldens. An OS moves only when its floating tags resolve to new digests whose attached doctor reports say cua-spacesd X.Y.Z (`scripts/images/image_pins.py`). A green build that pushed nothing therefore fails the job instead of moving a pin. The PR body lists each OS as done or pending. The PR is rebuilt from `main` and the registry on every run, so never edit it by hand: merge it once its checks pass. Benchmark pins come in `cd-bench-images.yml`'s own catalog PR.
+3. **macOS (by hand, on an Apple silicon Mac with Lume):** run `scripts/images/release-macos.sh X.Y.Z`. It downloads the release's notarized `Cua Spacesd.app`, runs `cua images release libs/images/macos` for `slim` and then `full` (build, gates, publish), promotes both tiers and then dispatches the workflow with `build=false`, which adds macOS to the same PR. Its state lives under `~/.cache/cua-images/macos-release/X.Y.Z`, and a rerun resumes.
+
+`python3 scripts/images/image_pins.py status` shows where each OS stands at any time. `CI: Images on the current cua-spacesd` (`ci-images-spacesd-lag.yml`) warns on PRs that touch the catalog, `libs/cua-spacesd/VERSION` or a release manifest when the pinned images report an older cua-spacesd. It never fails, because images normally trail a release by a few hours and an app release must not wait for them.
+
### cua-spacesd
`CUA_SPACESD_SOURCE` selects where the image gets the driver:
diff --git a/scripts/images/image_pins.py b/scripts/images/image_pins.py
new file mode 100755
index 0000000000..d7a929ae11
--- /dev/null
+++ b/scripts/images/image_pins.py
@@ -0,0 +1,422 @@
+#!/usr/bin/env python3
+"""Which catalog images run a given cua-spacesd, and moving their pins.
+
+ image_pins.py status [--version X.Y.Z] [--json]
+ image_pins.py apply [--version X.Y.Z] [--body FILE] [--run-url URL]
+ [--results linux=success,windows=failure,...]
+ image_pins.py lag [--version X.Y.Z]
+
+The version defaults to libs/cua-spacesd/VERSION. An OS is the catalog
+entries (libs/images/sandbox-images.json, canonical and distro groups) of one
+repository that run cua-spacesd and carry a ``digest``: ghcr.io/trycua/linux
+(4 tags), windows, macos, omarchy. Benchmark images pin through
+cd-bench-images.yml's own catalog PR and are not handled here.
+
+A tag "reports" a version when every platform child of what it resolves to
+that has a passing doctor report attached (an OCI referrer of artifact type
+application/vnd.cua.doctor.report.v1+json, found with ``oras discover``) has
+its newest passing report annotated ``ai.cua.doctor.spacesd=<version>``, and
+at least one child has one. Children without a report (a hosted arm64 disk
+that only boot-smoked) do not count either way.
+
+Per OS, against the version:
+
+* pinned every floating tag reports it, and the catalog already holds the
+ floating digests
+* ready every floating tag reports it, and some catalog digest differs: a
+ new digest was really pushed
+* pending some floating tag does not report it yet
+
+status prints that table (or JSON).
+apply moves every ready OS: ``record-image-sizes.py --refresh-digest`` for
+ its tags (new digest and sizes), checks the catalog now holds exactly
+ the digests that were verified, and moves the dated pin named in the
+ libs/images/README.md table row of each tag that has one. Writes the
+ pins PR body (a per-OS checklist) to --body and prints a JSON summary.
+ Exits 1 when an OS whose CI build (--results) succeeded still does
+ not report the version: a green run that pushed nothing.
+lag the CI check: every catalog digest that does not report the version
+ becomes a ``::warning::`` (and a step summary table). Never fails.
+
+Needs ``crane`` and ``oras`` on PATH (anonymous pulls of the public repos).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+from concurrent.futures import ThreadPoolExecutor
+from dataclasses import dataclass, field
+from typing import Callable
+
+ROOT = os.path.abspath(os.path.join(os.path.dirname(__file__), "..", ".."))
+CATALOG = os.path.join(ROOT, "libs", "images", "sandbox-images.json")
+README = os.path.join(ROOT, "libs", "images", "README.md")
+VERSION_FILE = os.path.join(ROOT, "libs", "cua-spacesd", "VERSION")
+REPORT_TYPE = "application/vnd.cua.doctor.report.v1+json"
+INDEX_TYPES = {
+ "application/vnd.oci.image.index.v1+json",
+ "application/vnd.docker.distribution.manifest.list.v2+json",
+}
+PIN_RE = re.compile(r"pin `([^`]+)`")
+
+# How each OS gets onto a new cua-spacesd: (label, what builds it).
+OSES = {
+ "linux": ("Linux", "cd-image-linux.yml"),
+ "windows": ("Windows", "cd-image-windows.yml"),
+ "omarchy": ("Omarchy", "cd-image-omarchy.yml"),
+ "macos": ("macOS", None), # Lume needs Apple silicon: scripts/images/release-macos.sh
+}
+
+
+def macos_command(version: str) -> str:
+ return f"scripts/images/release-macos.sh {version}"
+
+
+class Registry:
+ """crane and oras, anonymous."""
+
+ def _run(self, *cmd: str) -> str:
+ return subprocess.run(cmd, check=True, capture_output=True, text=True).stdout
+
+ def digest(self, ref: str) -> str:
+ return self._run("crane", "digest", ref).strip()
+
+ def manifest(self, ref: str) -> dict:
+ return json.loads(self._run("crane", "manifest", ref))
+
+ def tags(self, repo: str) -> list[str]:
+ return self._run("crane", "ls", repo).split()
+
+ def reports(self, ref: str) -> list[dict]:
+ """Annotations of every doctor report attached to ref."""
+ out = json.loads(self._run("oras", "discover", "--format", "json", "--artifact-type", REPORT_TYPE, ref))
+ found: list[dict] = []
+
+ def walk(node: object) -> None:
+ if isinstance(node, dict):
+ ann = node.get("annotations")
+ if node.get("artifactType") == REPORT_TYPE and isinstance(ann, dict):
+ found.append(ann)
+ for v in node.values():
+ walk(v)
+ elif isinstance(node, list):
+ for v in node:
+ walk(v)
+
+ walk(out)
+ return found
+
+
+def repo_of(ref: str) -> str:
+ return ref.rsplit(":", 1)[0]
+
+
+def os_key(ref: str) -> str:
+ return repo_of(ref).rsplit("/", 1)[-1]
+
+
+def spacesd_of(registry: Registry, repo: str, digest: str) -> str | None:
+ """The cua-spacesd version repo@digest reports; None when no child has a
+ passing report, ``mixed:a,b`` when its children disagree."""
+ manifest = registry.manifest(f"{repo}@{digest}")
+ if manifest.get("mediaType") in INDEX_TYPES or "manifests" in manifest:
+ children = [
+ m["digest"]
+ for m in manifest.get("manifests", [])
+ if (m.get("platform") or {}).get("architecture") not in (None, "unknown")
+ ]
+ else:
+ children = [digest]
+ versions = set()
+ for child in children:
+ passing = [
+ a for a in registry.reports(f"{repo}@{child}")
+ if a.get("ai.cua.doctor.status") == "pass" and a.get("ai.cua.doctor.spacesd")
+ ]
+ if passing:
+ newest = max(passing, key=lambda a: a.get("org.opencontainers.image.created", ""))
+ versions.add(newest["ai.cua.doctor.spacesd"])
+ if not versions:
+ return None
+ if len(versions) == 1:
+ return versions.pop()
+ return "mixed:" + ",".join(sorted(versions))
+
+
+@dataclass
+class Tag:
+ ref: str
+ catalog: str # digest main pins
+ floating: str = "" # digest the tag resolves to now
+ floating_version: str | None = None
+ catalog_version: str | None = None
+
+
+@dataclass
+class OS:
+ key: str
+ tags: list[Tag] = field(default_factory=list)
+ status: str = "" # pinned | ready | pending
+
+ @property
+ def label(self) -> str:
+ return OSES.get(self.key, (self.key, None))[0]
+
+
+def load_catalog(path: str = CATALOG) -> dict:
+ with open(path) as fh:
+ return json.load(fh)
+
+
+def catalog_oses(catalog: dict) -> list[OS]:
+ oses: dict[str, OS] = {}
+ for img in catalog["images"]:
+ if img.get("group") not in ("canonical", "distro") or not img.get("spacesd") or not img.get("digest"):
+ continue
+ key = os_key(img["ref"])
+ oses.setdefault(key, OS(key)).tags.append(Tag(img["ref"], img["digest"]))
+ order = list(OSES)
+ return sorted(oses.values(), key=lambda o: (order.index(o.key) if o.key in order else len(order), o.key))
+
+
+def resolve(registry: Registry, oses: list[OS], version: str, *, floating: bool = True, catalog: bool = False) -> None:
+ """Fill in digests and versions (in parallel) and each OS's status."""
+ tags = [t for o in oses for t in o.tags]
+
+ def one(t: Tag) -> None:
+ if floating:
+ t.floating = registry.digest(t.ref)
+ t.floating_version = spacesd_of(registry, repo_of(t.ref), t.floating)
+ if catalog:
+ t.catalog_version = spacesd_of(registry, repo_of(t.ref), t.catalog)
+
+ with ThreadPoolExecutor(max_workers=8) as pool:
+ list(pool.map(one, tags))
+ if not floating:
+ return
+ for o in oses:
+ if any(t.floating_version != version for t in o.tags):
+ o.status = "pending"
+ elif all(t.floating == t.catalog for t in o.tags):
+ o.status = "pinned"
+ else:
+ o.status = "ready"
+
+
+def short(ref: str) -> str:
+ return ref.removeprefix("ghcr.io/trycua/")
+
+
+def parse_results(text: str) -> dict[str, str]:
+ out = {}
+ for item in filter(None, (s.strip() for s in (text or "").split(","))):
+ key, _, value = item.partition("=")
+ out[key.strip()] = value.strip()
+ return out
+
+
+def silent_pushes(oses: list[OS], results: dict[str, str]) -> list[OS]:
+ """OSes whose CI build succeeded but whose tags do not report the version."""
+ return [o for o in oses if o.status == "pending" and results.get(o.key) == "success"]
+
+
+def body(oses: list[OS], version: str, *, run_url: str = "", results: dict[str, str] | None = None) -> str:
+ results = results or {}
+ done = sum(o.status in ("pinned", "ready") for o in oses)
+ lines = [
+ f"Moves the catalog pins of every Space image that runs **cua-spacesd {version}**. "
+ f"**{done} of {len(oses)}** OS images are on {version}.",
+ "",
+ ]
+ for o in oses:
+ tags = ", ".join(f"`{short(t.ref)}`" for t in o.tags)
+ if o.status == "ready":
+ lines.append(f"- [x] **{o.label}** ({tags}): pinned by this PR")
+ elif o.status == "pinned":
+ lines.append(f"- [x] **{o.label}** ({tags}): already pinned on main")
+ else:
+ seen = sorted({t.floating_version or "no doctor report" for t in o.tags})
+ if o.key == "macos":
+ todo = f"on an Apple silicon Mac, run `{macos_command(version)}`"
+ else:
+ wf = OSES.get(o.key, (o.key, None))[1]
+ result = results.get(o.key)
+ if result == "success":
+ todo = f"**its CI build passed but pushed nothing that reports {version}**; check {wf}"
+ elif result in ("failure", "cancelled"):
+ todo = f"its CI build ended `{result}`: re-run the failed jobs of the run below"
+ elif wf:
+ todo = f"waiting for `{wf}`"
+ else:
+ todo = "no automated build"
+ lines.append(f"- [ ] **{o.label}** ({tags}): pending, the floating tags report {', '.join(seen)}; {todo}")
+ moving = [t for o in oses if o.status == "ready" for t in o.tags]
+ if moving:
+ lines += ["", "| Tag | Digest | cua-spacesd |", "|---|---|---|"]
+ lines += [f"| `{short(t.ref)}` | `{t.floating}` | {t.floating_version} |" for t in moving]
+ lines += [
+ "",
+ "A tag counts as on the version when the newest passing doctor report attached to each of its "
+ "platform children (an OCI referrer) says so: a green run that pushed nothing cannot move a pin. "
+ "Sizes are from `record-image-sizes.py --refresh-digest`, the app-core parity goldens from "
+ "`UPDATE_PARITY=1`, and README pin rows follow their tags.",
+ "",
+ "This PR is regenerated from `main` and the registry on every run of "
+ "`.github/workflows/cd-images-spacesd-release.yml` (each cua-spacesd release, and after "
+ f"`{macos_command(version)}`): do not push to `images/pins` by hand. Merge it whenever the "
+ "checks pass; OSes still pending land in the next PR.",
+ ]
+ if run_url:
+ lines += ["", f"Run: {run_url}"]
+ return "\n".join(lines) + "\n"
+
+
+def pin_tag(registry: Registry, ref: str, digest: str, *, look: int = 12) -> str | None:
+ """The newest dated pin <tag>-<yyyymmdd>-<sha7> of ref's repo at digest."""
+ repo, tag = ref.rsplit(":", 1)
+ pat = re.compile(rf"^{re.escape(tag)}-(\d{{8}})-[0-9a-f]{{7}}$")
+ pins = sorted((t for t in registry.tags(repo) if pat.match(t)), key=lambda t: pat.match(t).group(1), reverse=True)
+ for t in pins[:look]:
+ if registry.digest(f"{repo}:{t}") == digest:
+ return t
+ return None
+
+
+def update_readme(text: str, ref: str, pin: str) -> str:
+ """Move the `pin` of the README table row whose first cell is exactly ref."""
+ row = re.compile(rf"^(\| `{re.escape(ref)}` \|.*)$", re.M)
+ return row.sub(lambda m: PIN_RE.sub(f"pin `{pin}`", m.group(1)), text)
+
+
+def refresh_sizes(refs: list[str]) -> None:
+ cmd = [sys.executable, os.path.join(ROOT, "scripts", "images", "record-image-sizes.py"), "--refresh-digest"]
+ for r in refs:
+ cmd += ["--ref", r]
+ subprocess.run(cmd, check=True)
+
+
+def apply(
+ registry: Registry,
+ oses: list[OS],
+ *,
+ refresh: Callable[[list[str]], None] = refresh_sizes,
+ catalog_path: str = CATALOG,
+ readme_path: str = README,
+) -> list[str]:
+ """Move every ready OS's pins; returns the refs moved."""
+ ready = [t for o in oses if o.status == "ready" for t in o.tags]
+ if not ready:
+ return []
+ refresh([t.ref for t in ready])
+ now = {i["ref"]: i.get("digest") for i in load_catalog(catalog_path)["images"]}
+ moved = [t for t in ready if now.get(t.ref) != t.floating]
+ if moved:
+ # The tag moved again between the check and the refresh: never pin
+ # bytes that were not verified.
+ raise SystemExit(
+ "image_pins: the catalog now holds digests other than the verified ones: "
+ + ", ".join(f"{t.ref} {now.get(t.ref)} (verified {t.floating})" for t in moved)
+ )
+ with open(readme_path) as fh:
+ text = fh.read()
+ new = text
+ for t in ready:
+ if re.search(rf"^\| `{re.escape(t.ref)}` \|.*pin `", new, re.M):
+ pin = pin_tag(registry, t.ref, t.floating)
+ if pin is None:
+ raise SystemExit(f"image_pins: no dated pin of {t.ref} at {t.floating} for the README")
+ new = update_readme(new, t.ref, pin)
+ if new != text:
+ with open(readme_path, "w") as fh:
+ fh.write(new)
+ return [t.ref for t in ready]
+
+
+def lag(registry: Registry, oses: list[OS], version: str) -> list[Tag]:
+ resolve(registry, oses, version, floating=False, catalog=True)
+ behind = [t for o in oses for t in o.tags if t.catalog_version != version]
+ summary = os.environ.get("GITHUB_STEP_SUMMARY")
+ lines = [f"### Catalog images on cua-spacesd {version}", "", "| Tag | Catalog digest reports |", "|---|---|"]
+ for o in oses:
+ for t in o.tags:
+ mark = "" if t.catalog_version == version else " (behind)"
+ lines.append(f"| `{short(t.ref)}` | {t.catalog_version or 'no doctor report'}{mark} |")
+ if behind:
+ lines += [
+ "",
+ f"{len(behind)} catalog tags are not on cua-spacesd {version} yet. This is a warning, not a failure: "
+ "images follow a cua-spacesd release by a few hours (`cd-images-spacesd-release.yml` rebuilds them "
+ "and opens the `images/pins` PR; macOS needs `scripts/images/release-macos.sh`).",
+ ]
+ for o in oses:
+ late = [t for t in o.tags if t in behind]
+ if late:
+ seen = ", ".join(sorted({t.catalog_version or "no doctor report" for t in late}))
+ print(
+ f"::warning title={o.label} images behind cua-spacesd {version}::"
+ f"{', '.join(short(t.ref) for t in late)} are pinned at builds that report {seen}"
+ )
+ else:
+ print(f"every catalog image reports cua-spacesd {version}")
+ if summary:
+ with open(summary, "a") as fh:
+ fh.write("\n".join(lines) + "\n")
+ else:
+ print("\n".join(lines))
+ return behind
+
+
+def main(argv: list[str] | None = None, registry: Registry | None = None) -> int:
+ ap = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+ ap.add_argument("command", choices=["status", "apply", "lag"])
+ ap.add_argument("--version", help="cua-spacesd X.Y.Z (default libs/cua-spacesd/VERSION)")
+ ap.add_argument("--json", action="store_true")
+ ap.add_argument("--body", help="apply: write the pins PR body here")
+ ap.add_argument("--run-url", default="")
+ ap.add_argument("--results", default="", help="apply: CI build results, os=success|failure|cancelled|skipped,...")
+ a = ap.parse_args(argv)
+ version = (a.version or open(VERSION_FILE).read()).strip().removeprefix("cua-spacesd-v").removeprefix("v")
+ if not re.fullmatch(r"\d+\.\d+\.\d+", version):
+ ap.error(f"--version must be X.Y.Z, got {version!r}")
+ registry = registry or Registry()
+ oses = catalog_oses(load_catalog())
+
+ if a.command == "lag":
+ lag(registry, oses, version)
+ return 0
+
+ resolve(registry, oses, version)
+ summary = {s: [o.key for o in oses if o.status == s] for s in ("ready", "pinned", "pending")}
+ if a.command == "status":
+ if a.json:
+ print(json.dumps({"version": version, **summary}))
+ else:
+ for o in oses:
+ for t in o.tags:
+ print(f"{o.status:8} {short(t.ref):28} {t.floating_version or '-':10} {t.floating}")
+ return 0
+
+ results = parse_results(a.results)
+ summary["moved"] = apply(registry, oses)
+ if a.body:
+ with open(a.body, "w") as fh:
+ fh.write(body(oses, version, run_url=a.run_url, results=results))
+ silent = silent_pushes(oses, results)
+ summary["silent"] = [o.key for o in silent]
+ print(json.dumps({"version": version, **summary}))
+ for o in silent:
+ print(
+ f"::error::{OSES[o.key][1]} succeeded but {', '.join(t.ref for t in o.tags)} "
+ f"does not report cua-spacesd {version}: the run pushed nothing new",
+ file=sys.stderr,
+ )
+ return 1 if silent else 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/scripts/images/pins-pr.sh b/scripts/images/pins-pr.sh
new file mode 100755
index 0000000000..c1aa613167
--- /dev/null
+++ b/scripts/images/pins-pr.sh
@@ -0,0 +1,82 @@
+#!/usr/bin/env bash
+# Open or update THE pins PR (branch images/pins) for one cua-spacesd version:
+#
+# scripts/images/pins-pr.sh VERSION [--results os=result,...] [--run-url URL] [--dry-run]
+#
+# 1. image_pins.py apply: every OS whose floating tags report cua-spacesd
+# VERSION (doctor reports attached to the pushed digests) and differ from
+# the catalog gets its new digests and sizes in libs/images/sandbox-images.json
+# and its README pin rows moved.
+# 2. The app-core parity goldens follow the catalog (UPDATE_PARITY=1).
+# 3. The branch is rebuilt from the checked-out main and force-pushed, and the
+# PR's title and body (a per-OS checklist) are set. The PR is a pure function
+# of main and the registry, so every run (CI, or after a local macOS
+# release) recomputes it from scratch; nothing pushed to the branch by hand
+# survives. With nothing to move, an open pins PR is closed.
+#
+# Run by .github/workflows/cd-images-spacesd-release.yml (pins job), which sets
+# the git identity and GH_TOKEN (the release GitHub App, so the PR's checks run).
+# --dry-run leaves the changes in the working tree and prints the body.
+# Needs crane, oras, jq, cargo (with protoc) and gh.
+set -euo pipefail
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+BRANCH=images/pins
+VERSION="" RESULTS="" RUN_URL="" DRY=0
+while [ $# -gt 0 ]; do
+ case "$1" in
+ --results) RESULTS="$2"; shift 2 ;;
+ --run-url) RUN_URL="$2"; shift 2 ;;
+ --dry-run) DRY=1; shift ;;
+ -h|--help) sed -n '2,22p' "$0"; exit 0 ;;
+ -*) echo "unknown option $1" >&2; exit 2 ;;
+ *) VERSION="$1"; shift ;;
+ esac
+done
+[[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]] || { echo "usage: pins-pr.sh X.Y.Z [--results ...] [--run-url URL] [--dry-run]" >&2; exit 2; }
+cd "$ROOT"
+TITLE="chore(images): pin Space images on cua-spacesd $VERSION"
+FILES=(libs/images/sandbox-images.json libs/images/README.md libs/cua/crates/cua-spaces-app-core/parity/golden)
+work="$(mktemp -d)"
+trap 'rm -rf "$work"' EXIT
+
+# A green build that pushed nothing fails this script, but only after the PR
+# is up to date with everything else.
+rc=0
+python3 scripts/images/image_pins.py apply --version "$VERSION" --body "$work/body.md" \
+ --results "$RESULTS" --run-url "$RUN_URL" >"$work/summary.json" || rc=$?
+[ -s "$work/summary.json" ] || exit "${rc:-1}"
+cat "$work/summary.json"
+if [ "$(jq '.moved | length' "$work/summary.json")" -gt 0 ]; then
+ (cd libs/cua && UPDATE_PARITY=1 cargo test --locked -p cua-spaces-app-core --test parity)
+fi
+
+open_pr="$(gh pr list --head "$BRANCH" --base main --state open --json number -q '.[0].number // empty' 2>/dev/null || true)"
+if git diff --quiet -- "${FILES[@]}"; then
+ echo "nothing to pin for cua-spacesd $VERSION"
+ if [ -n "$open_pr" ] && [ "$DRY" = 0 ]; then
+ gh pr close "$open_pr" --delete-branch \
+ --comment "Nothing on cua-spacesd $VERSION is left to pin (${RUN_URL:-a later run}); closing."
+ fi
+ exit "$rc"
+fi
+if [ "$DRY" = 1 ]; then
+ git diff --stat -- "${FILES[@]}"
+ echo "--- $TITLE"; cat "$work/body.md"
+ exit "$rc"
+fi
+git checkout -B "$BRANCH"
+git add -- "${FILES[@]}"
+git commit -q -m "$TITLE" -m "Generated by scripts/images/pins-pr.sh${RUN_URL:+ in $RUN_URL}."
+git push --force origin "$BRANCH"
+if [ -n "$open_pr" ]; then
+ gh pr edit "$open_pr" --title "$TITLE" --body-file "$work/body.md"
+ url="$(gh pr view "$open_pr" --json url -q .url)"
+else
+ url="$(gh pr create --base main --head "$BRANCH" --title "$TITLE" --body-file "$work/body.md")"
+fi
+echo "pins PR: $url"
+[ -z "${GITHUB_STEP_SUMMARY:-}" ] || {
+ echo "### Pins PR: $url"
+ cat "$work/body.md"
+} >>"$GITHUB_STEP_SUMMARY"
+exit "$rc"
diff --git a/scripts/images/release-macos.sh b/scripts/images/release-macos.sh
new file mode 100755
index 0000000000..e1dbc668e2
--- /dev/null
+++ b/scripts/images/release-macos.sh
@@ -0,0 +1,140 @@
+#!/usr/bin/env bash
+# The macOS half of a cua-spacesd image release, on an Apple silicon Mac with
+# Lume (GitHub has no macOS-VM runner for it). One command:
+#
+# scripts/images/release-macos.sh X.Y.Z [--dry-run]
+#
+# 1. download the published cua-spacesd-vX.Y.Z "Cua Spacesd.app" (Developer
+# ID signed and notarized) and check it against the release's SHA256SUMS
+# 2. per tier, slim then full (full builds on the gated slim VM):
+# `cua images release libs/images/macos` build and gates (doctor --strict,
+# ax probe, live input), then the keychain check (below), then --publish
+# (push the dated pin, attach the doctor report, verify)
+# 3. promote: 26-slim and 26 move to the new pins
+# 4. ask CI to refresh the pins PR (cd-images-spacesd-release.yml with
+# build=false): it sees macOS on X.Y.Z, adds it and ticks its box
+#
+# Keychain check (required, before publishing a tier): a throwaway clone of
+# the built VM boots, and its login keychain must unlock with the account
+# password `lume`, with no login_renamed_* keychain next to it. It guards the
+# Chrome Safe Storage / keychain-password regression (#4445, #4470); the built
+# VM itself never boots. The clone, $PREFIX-kc-<tier>, is always deleted.
+#
+# Rerunning resumes: steps that passed with the same inputs are skipped (the
+# stamp is today's date and this checkout's HEAD, so rerun from the same
+# commit on the same day, or pass STAMP=...).
+#
+# Everything lives under $WORK (default ~/.cache/cua-images/macos-release/X.Y.Z):
+# the app, the release work and evidence, an isolated CUA_HOME and sandbox
+# state, so your own ~/.cua and Spaces are never touched. The only VMs it
+# creates or deletes are $PREFIX-slim, $PREFIX-full and their keychain clones
+# $PREFIX-kc-{slim,full} (cua-e2e-macos-rel-*).
+#
+# Needs: lume (`lume serve`), the cua CLI ($CUA, default `cua` on PATH, or
+# build it: cargo build --release -p cua-cli in libs/cua), crane, oras, jq,
+# uv, gh (logged in with write:packages, for ghcr.io and the dispatch).
+# Knobs: STAMP, PREFIX, WORK, RECORD_LEDGER (default false: trycua/cua has
+# no image-doctor-ledger branch yet), CUA.
+set -euo pipefail
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+VERSION="" DRY=0
+for a in "$@"; do
+ case "$a" in
+ --dry-run) DRY=1 ;;
+ -h|--help) sed -n '2,37p' "$0"; exit 0 ;;
+ -*) echo "unknown option $a" >&2; exit 2 ;;
+ *) VERSION="${a#cua-spacesd-v}"; VERSION="${VERSION#v}" ;;
+ esac
+done
+[[ "$VERSION" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]] || { echo "usage: release-macos.sh X.Y.Z [--dry-run]" >&2; exit 2; }
+[ "$(uname -s)-$(uname -m)" = Darwin-arm64 ] || [ "$DRY" = 1 ] || { echo "needs an Apple silicon Mac" >&2; exit 2; }
+REPO_SLUG=trycua/cua
+TAG="cua-spacesd-v$VERSION"
+ASSET=cua-spacesd-macos-universal.app.zip
+CUA="${CUA:-cua}"
+STAMP="${STAMP:-$(date -u +%Y%m%d)-$(git -C "$ROOT" rev-parse --short=7 HEAD)}"
+PREFIX="${PREFIX:-cua-e2e-macos-rel-${STAMP%%-*}}"
+WORK="${WORK:-${CUA_IMAGES_OUT:-$HOME/.cache/cua-images}/macos-release/$VERSION}"
+RECORD_LEDGER="${RECORD_LEDGER:-false}"
+log() { echo "[release-macos $(date +%T)] $*" >&2; }
+run() { log "+ $*"; [ "$DRY" = 1 ] || "$@"; }
+
+# The images must carry exactly the released daemon.
+[ "$(gh release view "$TAG" -R "$REPO_SLUG" --json isDraft,isPrerelease -q '.isDraft or .isPrerelease')" = false ] ||
+ { echo "$TAG is not a published release" >&2; exit 1; }
+for tool in lume "$CUA" crane oras jq uv gh; do
+ command -v "$tool" >/dev/null || [ "$DRY" = 1 ] || { echo "missing $tool" >&2; exit 2; }
+done
+
+mkdir -p "$WORK/app" "$WORK/state" "$WORK/cuahome"
+if [ "$DRY" = 1 ]; then
+ log "would download $TAG $ASSET into $WORK/app"
+elif [ ! -d "$WORK/app/Cua Spacesd.app" ]; then
+ log "downloading $TAG $ASSET"
+ rm -f "$WORK/$ASSET" "$WORK/SHA256SUMS"
+ gh release download "$TAG" -R "$REPO_SLUG" -D "$WORK" -p "$ASSET" -p SHA256SUMS
+ (cd "$WORK" && grep " $ASSET\$" SHA256SUMS | shasum -a 256 -c -)
+ ditto -x -k "$WORK/$ASSET" "$WORK/app"
+fi
+[ "$DRY" = 1 ] || [ -d "$WORK/app/Cua Spacesd.app" ] || { echo "$ASSET has no Cua Spacesd.app" >&2; exit 1; }
+
+export CUA_HOME="$WORK/cuahome" CUA_TELEMETRY=0 DO_NOT_TRACK=1
+export CUA_MACOS_APP="$WORK/app/Cua Spacesd.app" CUA_MACOS_SPACESD_SOURCE=release
+if [ "$DRY" = 0 ]; then
+ export GITHUB_USERNAME="${GITHUB_USERNAME:-$(gh api user -q .login)}"
+ export GITHUB_TOKEN="${GITHUB_TOKEN:-$(gh auth token)}"
+fi
+common=(--stamp "$STAMP" --var "prefix=$PREFIX" --var "record_ledger=$RECORD_LEDGER" --embedded --state-dir "$WORK/state")
+log "cua-spacesd $VERSION, stamp $STAMP, VMs $PREFIX-{slim,full}, work $WORK"
+
+# The login keychain of a throwaway clone of VM unlocks with `lume`, and no
+# login_renamed_* keychain exists (see the header). Fails the run otherwise.
+keychain_check() (
+ vm="$1" out="$2"
+ clone="${vm%-*}-kc-${vm##*-}" # <prefix>-kc-<tier>
+ if [ "$DRY" = 1 ]; then log "+ keychain check of $vm on a clone $clone"; exit 0; fi
+ kc_cleanup() {
+ lume stop "$clone" >/dev/null 2>&1 || true
+ lume delete "$clone" --force >/dev/null 2>&1 || true
+ }
+ trap kc_cleanup EXIT # this subshell's exit: the clone never outlives the check
+ kc_cleanup
+ lume clone "$vm" "$clone" >/dev/null
+ lume set "$clone" --memory 4096MB >/dev/null
+ lume run "$clone" --display none --detach >/dev/null
+ g() { lume ssh "$clone" -t "${2:-60}" "$1" </dev/null; }
+ for _ in $(seq 1 60); do g 'echo up' 2>/dev/null | grep -q up && break; sleep 5; done
+ for _ in $(seq 1 60); do g 'pgrep -qx Dock && pgrep -qx Finder' 2>/dev/null && break; sleep 5; done
+ # shellcheck disable=SC2016 # expanded in the guest
+ g 'kc="$HOME/Library/Keychains/login.keychain-db"
+ ls "$HOME/Library/Keychains" | tr "\n" " "; echo
+ security lock-keychain "$kc"
+ security unlock-keychain -p lume "$kc" && echo UNLOCK_OK || echo UNLOCK_FAIL
+ echo "RENAMED=$(ls "$HOME/Library/Keychains" | grep -c login_renamed)"' 120 >"$out" 2>&1 || true
+ cat "$out" >&2
+ grep -q '^UNLOCK_OK' "$out" || { echo "keychain check: $vm's login keychain does not unlock with lume ($out)" >&2; exit 1; }
+ grep -q '^RENAMED=0$' "$out" || { echo "keychain check: $vm has login_renamed keychains ($out)" >&2; exit 1; }
+ log "keychain check: $vm unlocks with lume, no login_renamed keychains"
+)
+
+cd "$ROOT"
+for tier in slim full; do
+ log "$tier: build and gates (evidence: $WORK/$tier/evidence)"
+ run "$CUA" images release libs/images/macos --tier "$tier" "${common[@]}" --work "$WORK/$tier" --resume
+ log "$tier: keychain check on a throwaway clone"
+ mkdir -p "$WORK/$tier"
+ keychain_check "$PREFIX-$tier" "$WORK/$tier/keychain.txt"
+ log "$tier: push, attach the doctor report, verify"
+ run "$CUA" images release libs/images/macos --tier "$tier" "${common[@]}" --work "$WORK/$tier" --resume --publish
+ # The full tier is built; the slim VM it cloned is no longer needed.
+ [ "$tier" = slim ] || run lume delete "$PREFIX-slim" --force
+done
+for tier in slim full; do
+ log "$tier: promote"
+ run "$CUA" images release libs/images/macos --tier "$tier" "${common[@]}" --work "$WORK/$tier" --resume --publish --promote --steps promote
+done
+run lume delete "$PREFIX-full" --force
+
+log "macOS is on cua-spacesd $VERSION; refreshing the pins PR in CI"
+run gh workflow run cd-images-spacesd-release.yml -R "$REPO_SLUG" -f "version=$VERSION" -f build=false
+log "follow it: gh run list -R $REPO_SLUG -w cd-images-spacesd-release.yml -L 1"
diff --git a/scripts/images/tests/test_image_pins.py b/scripts/images/tests/test_image_pins.py
new file mode 100644
index 0000000000..ad1fb129c1
--- /dev/null
+++ b/scripts/images/tests/test_image_pins.py
@@ -0,0 +1,348 @@
+"""Tests for image_pins.py (against a fake registry) and the wiring of
+cd-images-spacesd-release.yml to the image workflows it calls."""
+
+from __future__ import annotations
+
+import contextlib
+import io
+import json
+import os
+import re
+import shutil
+import sys
+import tempfile
+import unittest
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+sys.path.insert(0, os.path.dirname(HERE))
+import image_pins # noqa: E402
+
+ROOT = os.path.abspath(os.path.join(HERE, "..", "..", ".."))
+WORKFLOWS = os.path.join(ROOT, ".github", "workflows")
+INDEX = "application/vnd.oci.image.index.v1+json"
+# Built, not spelled out: dated pins are not catalog refs (check-image-refs.py).
+MACOS = "ghcr.io/trycua/" + "macos"
+
+
+def d(n: int) -> str:
+ return "sha256:" + f"{n:064x}"
+
+
+class FakeRegistry(image_pins.Registry):
+ """tags: ref -> digest; manifests: repo@digest -> manifest;
+ reports: repo@digest -> [annotations]."""
+
+ def __init__(self) -> None:
+ self.tag_digests: dict[str, str] = {}
+ self.manifests: dict[str, dict] = {}
+ self.report_map: dict[str, list[dict]] = {}
+
+ def digest(self, ref: str) -> str:
+ return self.tag_digests[ref]
+
+ def manifest(self, ref: str) -> dict:
+ return self.manifests.get(ref, {"mediaType": "application/vnd.oci.image.manifest.v1+json"})
+
+ def tags(self, repo: str) -> list[str]:
+ return [r.rsplit(":", 1)[1] for r in self.tag_digests if r.rsplit(":", 1)[0] == repo]
+
+ def reports(self, ref: str) -> list[dict]:
+ return self.report_map.get(ref, [])
+
+ # helpers
+ def index(self, repo: str, digest: str, children: dict[str, str]) -> None:
+ self.manifests[f"{repo}@{digest}"] = {
+ "mediaType": INDEX,
+ "manifests": [{"digest": c, "platform": {"architecture": a, "os": "linux"}} for a, c in children.items()]
+ + [{"digest": d(999), "platform": {"architecture": "unknown", "os": "unknown"}}],
+ }
+
+ def report(self, repo: str, digest: str, version: str, created: str = "2026-10-03T00:00:00Z", status: str = "pass") -> None:
+ self.report_map.setdefault(f"{repo}@{digest}", []).append(
+ {
+ "ai.cua.doctor.spacesd": version,
+ "ai.cua.doctor.status": status,
+ "org.opencontainers.image.created": created,
+ }
+ )
+
+
+class SpacesdOfTests(unittest.TestCase):
+ def setUp(self) -> None:
+ self.r = FakeRegistry()
+ self.repo = "ghcr.io/trycua/linux"
+
+ def test_index_children_agree(self) -> None:
+ self.r.index(self.repo, d(1), {"amd64": d(2), "arm64": d(3)})
+ self.r.report(self.repo, d(2), "0.5.2")
+ self.r.report(self.repo, d(3), "0.5.2")
+ self.assertEqual(image_pins.spacesd_of(self.r, self.repo, d(1)), "0.5.2")
+
+ def test_child_without_report_does_not_count(self) -> None:
+ # A hosted arm64 disk that only boot-smoked has no report.
+ self.r.index(self.repo, d(1), {"amd64": d(2), "arm64": d(3)})
+ self.r.report(self.repo, d(2), "0.5.2")
+ self.assertEqual(image_pins.spacesd_of(self.r, self.repo, d(1)), "0.5.2")
+
+ def test_newest_passing_report_wins(self) -> None:
+ self.r.report(self.repo, d(1), "0.5.1", created="2026-10-02T00:00:00Z")
+ self.r.report(self.repo, d(1), "0.5.2", created="2026-10-03T00:00:00Z")
+ self.r.report(self.repo, d(1), "0.5.3", created="2026-10-04T00:00:00Z", status="fail")
+ self.assertEqual(image_pins.spacesd_of(self.r, self.repo, d(1)), "0.5.2")
+
+ def test_no_report_and_mixed(self) -> None:
+ self.assertIsNone(image_pins.spacesd_of(self.r, self.repo, d(1)))
+ self.r.index(self.repo, d(5), {"amd64": d(6), "arm64": d(7)})
+ self.r.report(self.repo, d(6), "0.5.2")
+ self.r.report(self.repo, d(7), "0.5.1")
+ self.assertEqual(image_pins.spacesd_of(self.r, self.repo, d(5)), "mixed:0.5.1,0.5.2")
+
+
+class PinsTests(unittest.TestCase):
+ """A two-OS catalog: linux (two tags) and macos (one tag, a README row)."""
+
+ def setUp(self) -> None:
+ self.tmp = tempfile.mkdtemp()
+ self.catalog = os.path.join(self.tmp, "catalog.json")
+ self.readme = os.path.join(self.tmp, "README.md")
+ self.data = {
+ "images": [
+ {"ref": "ghcr.io/trycua/linux:24.04", "group": "canonical", "spacesd": True, "digest": d(10)},
+ {"ref": "ghcr.io/trycua/linux:24.04-disk", "group": "canonical", "spacesd": True, "digest": d(11)},
+ {"ref": "ghcr.io/trycua/macos:26", "group": "canonical", "spacesd": True, "digest": d(20)},
+ {"ref": "ghcr.io/trycua/macos:15", "group": "canonical", "spacesd": False, "digest": d(30)},
+ {"ref": "ghcr.io/trycua/macos:26-xcode", "group": "canonical", "spacesd": True},
+ {"ref": "ghcr.io/trycua/bench-web:1.0", "group": "benchmark", "spacesd": True, "digest": d(40)},
+ ]
+ }
+ self._write_catalog()
+ with open(self.readme, "w") as fh:
+ fh.write(
+ "| `ghcr.io/trycua/macos:26` | full tier; pin `26-20261001-aaaaaaa` |\n"
+ "| `ghcr.io/trycua/macos:26-slim` | slim tier; pin `26-slim-20261001-aaaaaaa` |\n"
+ )
+ self.r = FakeRegistry()
+ for ref, digest in (
+ ("ghcr.io/trycua/linux:24.04", d(10)),
+ ("ghcr.io/trycua/linux:24.04-disk", d(11)),
+ ("ghcr.io/trycua/macos:26", d(20)),
+ (MACOS + ":26-20261001-aaaaaaa", d(20)),
+ ):
+ self.r.tag_digests[ref] = digest
+ for repo, digest in (("ghcr.io/trycua/linux", d(10)), ("ghcr.io/trycua/linux", d(11)), ("ghcr.io/trycua/macos", d(20))):
+ self.r.report(repo, digest, "0.5.1")
+
+ def tearDown(self) -> None:
+ shutil.rmtree(self.tmp)
+
+ def _write_catalog(self) -> None:
+ with open(self.catalog, "w") as fh:
+ json.dump(self.data, fh)
+
+ def oses(self, version: str = "0.5.2") -> list[image_pins.OS]:
+ oses = image_pins.catalog_oses(image_pins.load_catalog(self.catalog))
+ image_pins.resolve(self.r, oses, version)
+ return oses
+
+ def publish(self, ref: str, digest: str, version: str, pin: str | None = None) -> None:
+ self.r.tag_digests[ref] = digest
+ self.r.report(image_pins.repo_of(ref), digest, version)
+ if pin:
+ self.r.tag_digests[f"{image_pins.repo_of(ref)}:{pin}"] = digest
+
+ def fake_refresh(self, refs: list[str]) -> None:
+ for img in self.data["images"]:
+ if img["ref"] in refs:
+ img["digest"] = self.r.tag_digests[img["ref"]]
+ self._write_catalog()
+
+ def test_only_spacesd_oses_with_digests(self) -> None:
+ oses = image_pins.catalog_oses(image_pins.load_catalog(self.catalog))
+ self.assertEqual([(o.key, [t.ref for t in o.tags]) for o in oses], [
+ ("linux", ["ghcr.io/trycua/linux:24.04", "ghcr.io/trycua/linux:24.04-disk"]),
+ ("macos", ["ghcr.io/trycua/macos:26"]),
+ ])
+
+ def test_green_run_that_pushed_nothing_is_pending_and_flagged(self) -> None:
+ oses = self.oses()
+ self.assertEqual([o.status for o in oses], ["pending", "pending"])
+ silent = image_pins.silent_pushes(oses, {"linux": "success"})
+ self.assertEqual([o.key for o in silent], ["linux"])
+ self.assertIn("pushed nothing that reports 0.5.2", image_pins.body(oses, "0.5.2", results={"linux": "success"}))
+
+ def test_an_os_moves_only_when_every_tag_reports_the_version(self) -> None:
+ self.publish("ghcr.io/trycua/linux:24.04", d(12), "0.5.2")
+ self.assertEqual(self.oses()[0].status, "pending")
+ self.publish("ghcr.io/trycua/linux:24.04-disk", d(13), "0.5.2")
+ oses = self.oses()
+ self.assertEqual([o.status for o in oses], ["ready", "pending"])
+ moved = image_pins.apply(self.r, oses, refresh=self.fake_refresh, catalog_path=self.catalog, readme_path=self.readme)
+ self.assertEqual(moved, ["ghcr.io/trycua/linux:24.04", "ghcr.io/trycua/linux:24.04-disk"])
+ self.assertEqual([o.status for o in self.oses()], ["pinned", "pending"])
+ body = image_pins.body(oses, "0.5.2")
+ self.assertIn("- [x] **Linux**", body)
+ self.assertIn("- [ ] **macOS**", body)
+ self.assertIn("scripts/images/release-macos.sh 0.5.2", body)
+ self.assertIn(f"| `linux:24.04-disk` | `{d(13)}` | 0.5.2 |", body)
+
+ def test_readme_pin_follows_the_tag(self) -> None:
+ self.publish("ghcr.io/trycua/macos:26", d(21), "0.5.2", pin="26-20261003-bbbbbbb")
+ self.r.tag_digests[MACOS + ":26-20261003-bbbbbbb-raw"] = d(77)
+ oses = self.oses()
+ image_pins.apply(self.r, oses, refresh=self.fake_refresh, catalog_path=self.catalog, readme_path=self.readme)
+ with open(self.readme) as fh:
+ text = fh.read()
+ self.assertIn("full tier; pin `26-20261003-bbbbbbb` |", text)
+ self.assertIn("pin `26-slim-20261001-aaaaaaa`", text) # another tag's row is untouched
+
+ def test_refuses_a_digest_that_moved_after_the_check(self) -> None:
+ self.publish("ghcr.io/trycua/macos:26", d(21), "0.5.2", pin="26-20261003-bbbbbbb")
+ oses = self.oses()
+
+ def racing_refresh(refs: list[str]) -> None:
+ self.r.tag_digests["ghcr.io/trycua/macos:26"] = d(22)
+ self.fake_refresh(refs)
+
+ with self.assertRaises(SystemExit):
+ image_pins.apply(self.r, oses, refresh=racing_refresh, catalog_path=self.catalog, readme_path=self.readme)
+
+ def test_lag_warns_per_os_and_never_fails(self) -> None:
+ out = io.StringIO()
+ with contextlib.redirect_stdout(out):
+ oses = image_pins.catalog_oses(image_pins.load_catalog(self.catalog))
+ behind = image_pins.lag(self.r, oses, "0.5.2")
+ oses = image_pins.catalog_oses(image_pins.load_catalog(self.catalog))
+ current = image_pins.lag(self.r, oses, "0.5.1")
+ self.assertEqual(len(behind), 3)
+ self.assertEqual(current, [])
+ warnings = [line for line in out.getvalue().splitlines() if line.startswith("::warning")]
+ self.assertEqual(len(warnings), 2) # one per OS
+
+ def test_parse_results(self) -> None:
+ self.assertEqual(
+ image_pins.parse_results("linux=success, omarchy=failure,windows=skipped"),
+ {"linux": "success", "omarchy": "failure", "windows": "skipped"},
+ )
+
+
+def read(name: str) -> str:
+ with open(os.path.join(WORKFLOWS, name)) as fh:
+ return fh.read()
+
+
+def top_block(text: str, key: str, indent: int) -> str:
+ """The lines under `key:` at this indent, up to the next key at the same or lower indent."""
+ lines = text.splitlines()
+ pad = " " * indent
+ for i, line in enumerate(lines):
+ if line == f"{pad}{key}:" or line.startswith(f"{pad}{key}: "):
+ out = []
+ for nxt in lines[i + 1:]:
+ stripped = nxt.lstrip(" ")
+ if stripped and not stripped.startswith("#") and len(nxt) - len(stripped) <= indent:
+ break
+ out.append(nxt)
+ return "\n".join(out)
+ raise AssertionError(f"no {key!r} at indent {indent}")
+
+
+def job_permissions(text: str) -> dict[str, str]:
+ """Union of every job-level permissions block: scope -> strongest grant."""
+ rank = {"none": 0, "read": 1, "write": 2}
+ out: dict[str, str] = {}
+ for block in re.findall(r"^ permissions:\n((?: [a-z-]+: \w+.*\n| #.*\n)+)", text, re.M):
+ for scope, grant in re.findall(r"^ ([a-z-]+): (\w+)", block, re.M):
+ if rank[grant] > rank.get(out.get(scope, "none"), 0):
+ out[scope] = grant
+ return out
+
+
+class ReleaseWiringTests(unittest.TestCase):
+ FANOUT = "cd-images-spacesd-release.yml"
+ CALLS = {
+ "linux": ("cd-image-linux.yml", {"publish", "spacesd_source", "spacesd_version"}),
+ "omarchy": ("cd-image-omarchy.yml", {"publish", "series"}),
+ "windows": ("cd-image-windows.yml", {"stage"}),
+ "bench": ("cd-bench-images.yml", {"bench", "push"}),
+ }
+
+ def setUp(self) -> None:
+ self.fanout = read(self.FANOUT)
+ self.jobs = top_block(self.fanout, "jobs", 0)
+
+ def test_triggered_by_the_cua_spacesd_cd_by_its_exact_name(self) -> None:
+ name = re.search(r'^name: "([^"]+)"', read("cd-cua-spacesd.yml"), re.M).group(1)
+ self.assertIn(f'workflows: ["{name}"]', self.fanout)
+ self.assertIn("startsWith(github.event.workflow_run.head_branch, 'cua-spacesd-v')", self.fanout)
+ self.assertIn("github.event.workflow_run.conclusion == 'success'", self.fanout)
+ self.assertIn("workflow_dispatch:", top_block(self.fanout, "on", 0))
+
+ def test_calls_each_image_workflow_with_inputs_it_declares(self) -> None:
+ for job, (callee, inputs) in self.CALLS.items():
+ block = top_block(self.jobs, job, 2)
+ self.assertIn(f"uses: ./.github/workflows/{callee}", block)
+ passed = set(re.findall(r"^ ([a-z_]+):", top_block(block, "with", 4), re.M))
+ self.assertEqual(passed, inputs, job)
+ call = top_block(top_block(read(callee), "on", 0), "workflow_call", 2)
+ declared = set(re.findall(r"^ ([a-z_]+):$", top_block(call, "inputs", 4), re.M))
+ self.assertLessEqual(passed, declared, callee)
+ # Manual runs keep working.
+ self.assertIn("workflow_dispatch:", top_block(read(callee), "on", 0), callee)
+
+ def test_publishes(self) -> None:
+ self.assertIn("publish: true", top_block(self.jobs, "linux", 2))
+ self.assertIn("spacesd_source: release", top_block(self.jobs, "linux", 2))
+ self.assertIn("publish: true", top_block(self.jobs, "omarchy", 2))
+ self.assertIn("stage: publish", top_block(self.jobs, "windows", 2))
+ self.assertIn("push: true", top_block(self.jobs, "bench", 2))
+
+ def test_grants_cover_every_called_job(self) -> None:
+ rank = {"none": 0, "read": 1, "write": 2}
+ for job, (callee, _) in self.CALLS.items():
+ granted = dict(re.findall(r"^ ([a-z-]+): (\w+)", top_block(top_block(self.jobs, job, 2), "permissions", 4), re.M))
+ for scope, grant in job_permissions(read(callee)).items():
+ self.assertGreaterEqual(rank[granted.get(scope, "none")], rank[grant], f"{job}: {scope}: {grant}")
+
+ def test_called_publish_paths_accept_the_callers_event(self) -> None:
+ # A called workflow sees its caller's event (workflow_run).
+ for callee in ("cd-image-linux.yml", "cd-image-omarchy.yml"):
+ self.assertIn('workflow_dispatch|workflow_run) [ "$INPUT_PUBLISH" = true ] && publish=true', read(callee))
+ meta = top_block(top_block(read("cd-bench-images.yml"), "jobs", 0), "meta", 2)
+ self.assertIn("if: github.event_name != 'pull_request'", meta)
+
+ def test_pins_job(self) -> None:
+ pins = top_block(self.jobs, "pins", 2)
+ self.assertIn("needs: [resolve, linux, omarchy, windows, bench]", pins)
+ self.assertIn("!cancelled()", pins)
+ self.assertIn("secrets.RELEASE_APP_ID", pins)
+ self.assertIn("secrets.RELEASE_APP_PRIVATE_KEY", pins)
+ self.assertIn('scripts/images/pins-pr.sh "$VERSION"', pins)
+ self.assertTrue(os.access(os.path.join(ROOT, "scripts/images/pins-pr.sh"), os.X_OK))
+ self.assertTrue(os.access(os.path.join(ROOT, "scripts/images/release-macos.sh"), os.X_OK))
+
+ def test_macos_command_refreshes_this_workflow(self) -> None:
+ with open(os.path.join(ROOT, "scripts/images/release-macos.sh")) as fh:
+ script = fh.read()
+ self.assertIn(f"gh workflow run {self.FANOUT}", script)
+ self.assertIn("-f build=false", script)
+ self.assertIn("build:", top_block(top_block(self.fanout, "on", 0), "workflow_dispatch", 2))
+
+ def test_macos_keychain_check_gates_each_publish(self) -> None:
+ with open(os.path.join(ROOT, "scripts/images/release-macos.sh")) as fh:
+ script = fh.read()
+ loop = script[script.index('for tier in slim full; do'):]
+ check = loop.index('keychain_check "$PREFIX-$tier"')
+ self.assertLess(check, loop.index("--resume --publish"))
+ self.assertIn("security unlock-keychain -p lume", script)
+ self.assertIn("grep -q '^RENAMED=0$'", script)
+
+ def test_lag_check_never_blocks(self) -> None:
+ lag = read("ci-images-spacesd-lag.yml")
+ self.assertIn("continue-on-error: true", lag)
+ self.assertIn("python3 scripts/images/image_pins.py lag", lag)
+ for path in ("libs/images/sandbox-images.json", "libs/cua-spacesd/VERSION", ".release-please-manifest.json"):
+ self.assertIn(f'- "{path}"', lag)
+
+
+if __name__ == "__main__":
+ unittest.main()