Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

Cut Desktop release overhead with shared caches and automatic verification (#612)

Dee74c51107a155
diff --git a/.github/actions/desktop-flutter/action.yml b/.github/actions/desktop-flutter/action.yml
new file mode 100644
index 000000000..7339f8f6b
--- /dev/null
+++ b/.github/actions/desktop-flutter/action.yml
@@ -0,0 +1,63 @@
+name: Prepare desktop Flutter
+description: Restore shared toolchain/dependencies; only the cache preparation workflow saves them
+inputs:
+ version:
+ description: Exact Flutter version from release-desktop.yml
+ required: true
+ save-cache:
+ description: Save missing caches (for cache preparation, never the release critical path)
+ default: 'false'
+runs:
+ using: composite
+ steps:
+ # Keep upstream keys/paths so logging, internal and web builds can reuse main's caches too.
+ - id: paths
+ uses: subosito/flutter-action@v2
+ with:
+ flutter-version: ${{ inputs.version }}
+ channel: stable
+ dry-run: true
+ cache: false
+ pub-cache: false
+ - id: sdk
+ uses: actions/cache/restore@v4
+ with:
+ path: ${{ steps.paths.outputs.CACHE-PATH }}
+ key: ${{ steps.paths.outputs.CACHE-KEY }}
+ - id: pub
+ uses: actions/cache/restore@v4
+ with:
+ path: ${{ steps.paths.outputs.PUB-CACHE-PATH }}
+ key: ${{ steps.paths.outputs.PUB-CACHE-KEY }}-${{ hashFiles('**/pubspec.lock') }}
+ - uses: subosito/flutter-action@v2
+ with:
+ flutter-version: ${{ inputs.version }}
+ channel: stable
+ cache: false
+ pub-cache: false
+ - name: Prepare the pinned toolchain and dependencies
+ shell: bash
+ working-directory: desktop
+ env:
+ EXPECTED_FLUTTER: ${{ inputs.version }}
+ run: |
+ set -euo pipefail
+ actual="$(flutter --version --machine | jq -r .frameworkVersion)"
+ test "$actual" = "$EXPECTED_FLUTTER"
+ if [[ "$RUNNER_OS" == macOS ]]; then
+ flutter config --enable-swift-package-manager
+ flutter precache --macos
+ else
+ flutter precache --linux
+ fi
+ flutter pub get
+ - uses: actions/cache/save@v4
+ if: inputs.save-cache == 'true' && steps.sdk.outputs.cache-hit != 'true'
+ with:
+ path: ${{ steps.paths.outputs.CACHE-PATH }}
+ key: ${{ steps.paths.outputs.CACHE-KEY }}
+ - uses: actions/cache/save@v4
+ if: inputs.save-cache == 'true' && steps.pub.outputs.cache-hit != 'true'
+ with:
+ path: ${{ steps.paths.outputs.PUB-CACHE-PATH }}
+ key: ${{ steps.paths.outputs.PUB-CACHE-KEY }}-${{ hashFiles('**/pubspec.lock') }}
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index b22c379af..e1ed090ba 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -19,7 +19,7 @@ on:
scope:
description: 'Affected components (full for shared protocols or uncertain impact)'
type: choice
- options: [full, cli, tui, backend]
+ options: [full, cli, tui, backend, process]
default: full
# Callable as a reusable workflow. release.yml used to gate on this and take the Node pin from
# its output; it no longer does (see the note above `publish` there) and pins the same version
@@ -27,7 +27,7 @@ on:
workflow_call:
inputs:
scope:
- description: 'full, cli, tui, or backend'
+ description: 'full, cli, tui, backend, or process (repository tooling only)'
type: string
default: full
outputs:
@@ -46,7 +46,7 @@ concurrency:
jobs:
process-checks:
- if: ${{ contains(fromJSON('["full","cli","tui","backend"]'), inputs.scope || 'full') }}
+ if: ${{ contains(fromJSON('["full","cli","tui","backend","process"]'), inputs.scope || 'full') }}
runs-on: ubuntu-latest
timeout-minutes: 3
steps:
@@ -57,10 +57,10 @@ jobs:
# workflow_dispatch restricts the choice; reusable callers can pass any string.
# Fail invalid calls rather than reporting success after skipping every check.
invalid-scope:
- if: ${{ !contains(fromJSON('["full","cli","tui","backend"]'), inputs.scope || 'full') }}
+ if: ${{ !contains(fromJSON('["full","cli","tui","backend","process"]'), inputs.scope || 'full') }}
runs-on: ubuntu-latest
steps:
- - run: echo '::error::scope must be full, cli, tui, or backend'; exit 1
+ - run: echo '::error::scope must be full, cli, tui, backend, or process'; exit 1
# tty.ReadStream uses libuv's native TTY handle. Exercise descriptor ownership,
# binary backpressure and unplug behavior on both supported OSes and runtimes.
diff --git a/.github/workflows/desktop-cache.yml b/.github/workflows/desktop-cache.yml
new file mode 100644
index 000000000..a410995ff
--- /dev/null
+++ b/.github/workflows/desktop-cache.yml
@@ -0,0 +1,48 @@
+name: Prepare desktop caches
+
+# A tag can restore main's caches, but cannot restore a previous tag's caches.
+# Prepare these once when dependencies/toolchain change, outside any release.
+on:
+ push:
+ branches: [main]
+ paths:
+ - 'desktop/pubspec.yaml'
+ - '**/pubspec.lock'
+ - '.github/actions/desktop-flutter/**'
+ - '.github/workflows/desktop-cache.yml'
+ - '.github/workflows/release-desktop.yml'
+ pull_request:
+ paths:
+ - 'desktop/pubspec.yaml'
+ - '**/pubspec.lock'
+ - '.github/actions/desktop-flutter/**'
+ - '.github/workflows/desktop-cache.yml'
+ - '.github/workflows/release-desktop.yml'
+ workflow_dispatch:
+
+permissions:
+ contents: read
+
+concurrency:
+ group: desktop-cache-${{ github.ref }}
+ cancel-in-progress: false
+
+jobs:
+ prepare:
+ strategy:
+ fail-fast: false
+ matrix:
+ os: [macos-15, ubuntu-22.04]
+ runs-on: ${{ matrix.os }}
+ timeout-minutes: 15
+ steps:
+ - uses: actions/checkout@v7
+ - id: toolchain
+ run: |
+ version="$(sed -n "s/^ FLUTTER_VERSION: '\([^']*\)'.*/\1/p" .github/workflows/release-desktop.yml)"
+ test -n "$version"
+ echo "version=$version" >> "$GITHUB_OUTPUT"
+ - uses: ./.github/actions/desktop-flutter
+ with:
+ version: ${{ steps.toolchain.outputs.version }}
+ save-cache: 'true'
diff --git a/.github/workflows/release-desktop.yml b/.github/workflows/release-desktop.yml
index 0d863f7ee..be8a302d5 100644
--- a/.github/workflows/release-desktop.yml
+++ b/.github/workflows/release-desktop.yml
@@ -174,19 +174,11 @@ jobs:
steps:
- uses: actions/checkout@v7
- - uses: subosito/flutter-action@v2
+ # main prepares shared caches. A release only restores: per-tag uploads cannot
+ # help the next tag and added 81s after the 1.2.51 macOS build had finished.
+ - uses: ./.github/actions/desktop-flutter
with:
- flutter-version: ${{ env.FLUTTER_VERSION }}
- channel: stable
- cache: true
-
- # SPM must be on BEFORE pub get: the generated FlutterGeneratedPluginSwiftPackage only lists
- # the plugin dependencies when it is enabled at `pub get` time, and with it off the build
- # falls back to CocoaPods and rewrites tracked files under macos/. See CLAUDE.md.
- - name: Enable Swift Package Manager
- run: flutter config --enable-swift-package-manager
-
- - run: flutter pub get
+ version: ${{ env.FLUTTER_VERSION }}
# The throwaway keychain, the Developer ID certificate in it and the `harness-notarize` profile
# upload-desktop.sh submits with. It sets KEYCHAIN_PATH. internal-build.yml signs with the same
@@ -261,12 +253,10 @@ jobs:
# linux-arm64/artifacts.zip and dart-sdk-linux-arm64.zip are served for this engine), so the
# SAME toolchain is reached by the other route: clone the SDK at the same tag and let
# precache pull the artifacts. x64 keeps the action for its cache.
- - uses: subosito/flutter-action@v2
+ - uses: ./.github/actions/desktop-flutter
if: matrix.arch != 'arm64'
with:
- flutter-version: ${{ env.FLUTTER_VERSION }}
- channel: stable
- cache: true
+ version: ${{ env.FLUTTER_VERSION }}
- name: Install Flutter from git (arm64 has no published archive)
if: matrix.arch == 'arm64'
@@ -276,15 +266,15 @@ jobs:
https://github.com/flutter/flutter.git "$RUNNER_TEMP/flutter"
echo "$RUNNER_TEMP/flutter/bin" >> "$GITHUB_PATH"
- # Runs on both arches so the two install paths have one place to prove they landed on the
- # same toolchain, and so a missing arm64 artifact fails in a step that says so rather than
- # halfway through a build.
+ # x64 is prepared by the shared action. arm64 has no SDK archive/cache.
- name: Verify the toolchain and precache Linux artifacts
+ if: matrix.arch == 'arm64'
run: |
flutter --version
flutter precache --linux
- - run: flutter pub get
+ - if: matrix.arch == 'arm64'
+ run: flutter pub get
# appimagetool packages the Linux bundle into the single-file .AppImage the release publishes
# (see RELEASE.md). --appimage-extract-and-run in upload-desktop-linux.sh means the runner
@@ -382,6 +372,32 @@ jobs:
"$dst" "gs://${GCS_BUCKET}/${METADATA_PATH}"
echo "Published to \`${METADATA_PATH}\`" >> "$GITHUB_STEP_SUMMARY"
+ # Start as soon as the public manifest is live, beside release-page creation.
+ # A green workflow is the six-download verification receipt; do not download them
+ # all again locally just to finish the release task.
+ verify:
+ needs: [version, publish]
+ runs-on: ubuntu-latest
+ timeout-minutes: 5
+ permissions:
+ contents: read
+ steps:
+ - uses: actions/checkout@v7
+ - name: Verify all public artifacts as the updater
+ env:
+ VERSION: ${{ needs.version.outputs.version }}
+ METADATA_PATH: ${{ needs.version.outputs.metadata_path }}
+ run: |
+ python3 scripts/verify-desktop-release.py "$VERSION" \
+ --manifest-url "https://storage.googleapis.com/${GCS_BUCKET}/${METADATA_PATH}" \
+ --receipt desktop-release-verification.json
+ - uses: actions/upload-artifact@v4
+ if: always()
+ with:
+ name: desktop-release-verification
+ path: desktop-release-verification.json
+ if-no-files-found: error
+
# The GitHub Release. Notes are the tag's OWN message, verbatim — the same rule
# autonomous-grid's release.yml follows. CI generates nothing: what a human wrote and reviewed at
# tag time is exactly what publishes, and `generate_release_notes` would append a second,
diff --git a/AGENTS.md b/AGENTS.md
index 95f9ffdde..78a0f764e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -18,3 +18,5 @@ validation and shipping, use [docs/validation-and-release.md](docs/validation-an
suite as passing, and never silently skip a required check to meet a time target.
- Once required checks pass, carry out the authorized merge/release without another
validation cycle. Verify published versions and checksums, then report completion.
+ Desktop's `--wait` follows the exact tag/SHA through the workflow's six-artifact
+ verification; reuse that receipt instead of repeating the downloads manually.
diff --git a/desktop/scripts/release-desktop.sh b/desktop/scripts/release-desktop.sh
index 77e0b3012..a7d108367 100755
--- a/desktop/scripts/release-desktop.sh
+++ b/desktop/scripts/release-desktop.sh
@@ -14,6 +14,7 @@
# bash scripts/release-desktop.sh 1.1.0 # release an explicit version
# bash scripts/release-desktop.sh --notes-file f.md # hand-written release notes instead of the
# # generated commit list
+# bash scripts/release-desktop.sh --wait # finish when this tag is live and verified
#
# THE NEXT VERSION COMES FROM TWO SOURCES, AND BOTH MATTER. Git tags alone are not enough: this repo
# had one tag (v1.0.52) while the live manifest was already serving 1.0.61, because
@@ -23,7 +24,7 @@
# the current version is max(highest git tag, highest version in the manifest), across ALL of the
# manifest's desktop-* keys, not just the macOS one.
#
-# Requires: git, curl, python3, and push access to origin. No GCS credentials — the manifest is read
+# Requires: git, curl, python3, push access to origin; gh for --wait. No GCS credentials — the manifest is read
# over public HTTPS, exactly as scripts/upload-desktop.sh reads it.
set -euo pipefail
@@ -38,6 +39,7 @@ META_URL="${META_URL:-${GCS_PUBLIC_BASE_URL%/}/${METADATA_PATH#/}}"
BRANCH="${BRANCH:-main}"
DRY_RUN=0
+WAIT=0
DO_MINOR=0
ALLOW_NO_MANIFEST=0
NEW_VER=""
@@ -48,6 +50,7 @@ for arg in "$@"; do
if [ "$want_notes_file" -eq 1 ]; then NOTES_FILE="$arg"; want_notes_file=0; continue; fi
case "$arg" in
--dry-run) DRY_RUN=1 ;;
+ --wait) WAIT=1 ;;
--minor) DO_MINOR=1 ;;
--allow-no-manifest) ALLOW_NO_MANIFEST=1 ;;
--notes-file) want_notes_file=1 ;;
@@ -57,6 +60,9 @@ for arg in "$@"; do
*) NEW_VER="$arg" ;;
esac
done
+if [ "$WAIT" -eq 1 ]; then
+ command -v gh >/dev/null 2>&1 || { echo 'ERROR --wait requires gh' >&2; exit 1; }
+fi
[ "$want_notes_file" -eq 0 ] || { echo "ERROR --notes-file needs a path" >&2; exit 1; }
# Same rules as next_desktop_version()/bump_minor_version() in scripts/upload-desktop.sh:55-86, which
@@ -130,7 +136,7 @@ TAG_VER="${TAG_VER:-0.0.0}"
# --- current version, source 2: the highest version actually being served ---
# Every desktop-* key, because each publisher only ever wrote its own: a linux-only publish would be
# invisible if we read desktop-macos alone, and stepping over it is how a downgrade gets released.
-GCS_READ="$(curl -fsSL "$META_URL" 2>/dev/null | python3 -c '
+GCS_READ="$(curl -fsSL --connect-timeout 10 --max-time 30 "$META_URL" 2>/dev/null | python3 -c '
import json, re, sys
try:
data = json.load(sys.stdin)
@@ -251,5 +257,8 @@ git push origin "$TAG"
echo ""
echo " pushed $TAG → CI builds macOS + Linux, publishes to GCS, and cuts the GitHub Release."
-echo " watch : gh run watch \$(gh run list --workflow=release.yml --limit 1 --json databaseId --jq '.[0].databaseId')"
+echo " watch (from repo root): python3 scripts/watch-desktop-release.py $TAG --sha $HEAD_SHA"
echo ""
+if [ "$WAIT" -eq 1 ]; then
+ python3 "$ROOT/../scripts/watch-desktop-release.py" "$TAG" --sha "$HEAD_SHA"
+fi
diff --git a/docs/performance/2026-10-02-desktop-download-verification.json b/docs/performance/2026-10-02-desktop-download-verification.json
new file mode 100644
index 000000000..884dfc678
--- /dev/null
+++ b/docs/performance/2026-10-02-desktop-download-verification.json
@@ -0,0 +1,91 @@
+{
+ "version": "1.2.51",
+ "manifest_url": "https://storage.googleapis.com/s3-autonomous-upgrade-3/harness/desktop/metadata.json",
+ "started_at": "2026-10-02T13:34:26.289351+00:00",
+ "source_sha": null,
+ "run_id": null,
+ "status": "passed",
+ "artifacts": [
+ {
+ "version": "1.2.51",
+ "url": "https://cdn.autonomous.ai/harness/desktop/1.2.51/Harness-macos.zip",
+ "sha256": "c8b27b4d9c752a590c95449681581fe540a4563a6bfafbea7f627ae2cd0333d8",
+ "size": 115374651,
+ "key": "desktop-macos",
+ "started_at": "2026-10-02T13:34:26.652294+00:00",
+ "status": "passed",
+ "actual_size": 115374651,
+ "actual_sha256": "c8b27b4d9c752a590c95449681581fe540a4563a6bfafbea7f627ae2cd0333d8",
+ "finished_at": "2026-10-02T13:34:30.953515+00:00",
+ "duration_seconds": 4.301
+ },
+ {
+ "version": "1.2.51",
+ "url": "https://cdn.autonomous.ai/harness/desktop/1.2.51/Harness-macos.dmg",
+ "sha256": "806c3e5e80d1657e824bcc933d9c6019bd48d9ffa52f8eebad8dd486eb82728f",
+ "size": 119272496,
+ "key": "desktop-macos-dmg",
+ "started_at": "2026-10-02T13:34:26.652495+00:00",
+ "status": "passed",
+ "actual_size": 119272496,
+ "actual_sha256": "806c3e5e80d1657e824bcc933d9c6019bd48d9ffa52f8eebad8dd486eb82728f",
+ "finished_at": "2026-10-02T13:34:31.212793+00:00",
+ "duration_seconds": 4.56
+ },
+ {
+ "version": "1.2.51",
+ "url": "https://cdn.autonomous.ai/harness/desktop/1.2.51/Harness-macos-arm64.zip",
+ "sha256": "c92bd90f1e9639abeb85f8842e555211a6e8ca48d8ae37a07b9e514205769c6e",
+ "size": 115374684,
+ "key": "desktop-macos-arm64",
+ "started_at": "2026-10-02T13:34:26.652650+00:00",
+ "status": "passed",
+ "actual_size": 115374684,
+ "actual_sha256": "c92bd90f1e9639abeb85f8842e555211a6e8ca48d8ae37a07b9e514205769c6e",
+ "finished_at": "2026-10-02T13:34:32.560767+00:00",
+ "duration_seconds": 5.908
+ },
+ {
+ "version": "1.2.51",
+ "url": "https://cdn.autonomous.ai/harness/desktop/1.2.51/Harness-macos-arm64.dmg",
+ "sha256": "97c38cdcd37f530a017fafc564865ef5ec33095d292c5c02e25c3c429e14cbe0",
+ "size": 119275758,
+ "key": "desktop-macos-arm64-dmg",
+ "started_at": "2026-10-02T13:34:30.953717+00:00",
+ "status": "passed",
+ "actual_size": 119275758,
+ "actual_sha256": "97c38cdcd37f530a017fafc564865ef5ec33095d292c5c02e25c3c429e14cbe0",
+ "finished_at": "2026-10-02T13:34:36.102927+00:00",
+ "duration_seconds": 5.149
+ },
+ {
+ "version": "1.2.51",
+ "url": "https://cdn.autonomous.ai/harness/desktop/1.2.51/Harness-linux-x64.AppImage",
+ "sha256": "aca7f467d99676766301e5735ea0c4c9671b13dd6ac8a1f852b29cb69a05180d",
+ "size": 95910392,
+ "key": "desktop-linux-x64",
+ "started_at": "2026-10-02T13:34:31.212978+00:00",
+ "status": "passed",
+ "actual_size": 95910392,
+ "actual_sha256": "aca7f467d99676766301e5735ea0c4c9671b13dd6ac8a1f852b29cb69a05180d",
+ "finished_at": "2026-10-02T13:34:34.918303+00:00",
+ "duration_seconds": 3.705
+ },
+ {
+ "version": "1.2.51",
+ "url": "https://cdn.autonomous.ai/harness/desktop/1.2.51/Harness-linux-arm64.AppImage",
+ "sha256": "0a9cb996e7297f5ea24326b82296fcf0ce1c557b270aa5212ae55c281ff910d7",
+ "size": 95427080,
+ "key": "desktop-linux-arm64",
+ "started_at": "2026-10-02T13:34:32.560979+00:00",
+ "status": "passed",
+ "actual_size": 95427080,
+ "actual_sha256": "0a9cb996e7297f5ea24326b82296fcf0ce1c557b270aa5212ae55c281ff910d7",
+ "finished_at": "2026-10-02T13:34:35.782691+00:00",
+ "duration_seconds": 3.222
+ }
+ ],
+ "manifest_sha256": "ff0935300e107f944f3a04beb6e7c2dbb163dd8da99ebcf30789b49b6009f7f0",
+ "finished_at": "2026-10-02T13:34:36.103211+00:00",
+ "duration_seconds": 9.814
+}
diff --git a/docs/performance/2026-10-02-desktop-shipping-followup.md b/docs/performance/2026-10-02-desktop-shipping-followup.md
new file mode 100644
index 000000000..d107c7c1d
--- /dev/null
+++ b/docs/performance/2026-10-02-desktop-shipping-followup.md
@@ -0,0 +1,74 @@
+# Desktop testing and shipping follow-up
+
+Scope: code ready through required validation, merge, publication and verification.
+Design, implementation time and user review are not targets for shortening.
+
+## Evidence from Desktop 1.2.51
+
+[Release run 36995613336](https://github.com/autonomous-ai/openharness/actions/runs/36995613336)
+completed first attempt. The release workflow took 12m29s. On its critical macOS
+Apple Silicon job, the Flutter SDK and pub cache both missed. Setup took 73s;
+Flutter compilation took about 4m14s; app and DMG notarization took about 61s and
+52s respectively. After uploads finished, post-job cache saving took another 81s.
+The Intel job also missed and spent 33s saving caches.
+
+The caches were associated with release tags, with no corresponding Flutter cache
+on `main`. [GitHub's cache access rules](https://docs.github.com/en/actions/reference/workflows-and-actions/dependency-caching#restrictions-for-accessing-a-cache)
+allow a tag to restore the default branch's cache but not another tag's cache.
+Saving multi-gigabyte SDK copies after each release therefore delayed publication
+without helping the next release. [flutter-action's implementation](https://github.com/subosito/flutter-action/blob/v2/action.yaml)
+uses automatic post-job saves when its cache option is enabled.
+
+The user-visible shipping interval for 1.2.51 was 30m10s from "pr merge" to the
+completion message. That included user review. Merge to live publication was
+13m29s; live to final report was 4m18s. All six downloads were verified within
+that last interval, but orchestrating the checks and reporting added waiting.
+These are distinct from the Actions duration; they are not all build time.
+
+## Changes
+
+- Prepare SDK/pub caches on `main` when their inputs change. Reuse upstream keys
+ so existing logging, internal and web workflows can restore them too. Release
+ jobs restore only; misses still install the pinned toolchain. The preparation
+ workflow also tests changes to this setup on PRs, without release credentials.
+- Verify all six public downloads immediately after publication, parallel with
+ GitHub release-page creation. Check expected versions, full SHA-256 and sizes
+ with the updater's Dart user agent. Stream three downloads at a time and impose
+ total transfer deadlines. Preserve a JSON receipt on success or failure.
+- Add `--wait` to the Desktop release command. Follow the exact tag and SHA,
+ require the public verification job to pass, and finish promptly. The previous
+ printed command watched the latest run of the CLI workflow instead.
+- Add `scope=process` to manual CI for repository tooling changes. Application
+ changes still select their component checks; cache hits do not skip tests.
+
+No signing, notarization, application test gate or artifact integrity check was
+removed. The public manifest writer and uploaded bytes are unchanged.
+
+## Validation and expected effect
+
+Local process suite: 31 tests passed in 11.47s. HTTP fixtures exercise all six
+downloads, concurrency limits, Dart user agent, corrupt hashes/sizes, missing or
+mixed-version entries, HTTP failures and bounded timeouts. Watcher fixtures cover
+exact source selection, pending runs, failures and absent verification.
+`actionlint`, shell syntax and whitespace checks passed.
+
+The new read-only verifier checked the existing public 1.2.51 manifest and all
+six CDN artifacts in **9.814s**, with every hash and size matching. This is a
+measurement on this Mac/network, not a prediction of every CI run.
+The [JSON receipt](2026-10-02-desktop-download-verification.json) records the
+manifest digest, each artifact's expected/actual hash and byte count, and UTC times.
+
+On implementation commit `e3c38c4b8bca7a35b9a989fe03aaf368131770c2`,
+[process CI](https://github.com/autonomous-ai/openharness/actions/runs/37014248010)
+passed all 31 tests in a **25s workflow** (18s job), without component builds.
+[Cold preparation](https://github.com/autonomous-ai/openharness/actions/runs/37014247634)
+passed on both release runner types: macOS 2m46s, Linux 1m46s, including cache
+creation. This job runs separately from the release, so its cache saves do not
+delay publication.
+
+Removing release cache saves eliminates the observed 81s post-build cache phase.
+Warm restores should also reduce setup time, subject to restore throughput and
+cache eviction. Automated verification should replace most of the prior manual
+4m18s after-publication interval with runner startup, downloads and a concise
+report. Measure the next actual release before claiming an end-to-end speedup;
+Apple notarization and runner queues remain variable.
diff --git a/docs/validation-and-release.md b/docs/validation-and-release.md
index c1e659231..80a09b126 100644
--- a/docs/validation-and-release.md
+++ b/docs/validation-and-release.md
@@ -31,6 +31,19 @@ bundle checks, and the serial/login-shell OS/Node matrix. `tui` includes its nat
CLI integration tests. Select `full` for cross-component changes or uncertain impact.
The workflow remains on demand; this change does not introduce new required gates.
+For repository process tooling only, `scope=process` runs its Python regression
+tests without installing or building unrelated components. It does not validate
+application changes. Workflow edits also need `actionlint` and a run exercising
+the changed workflow behavior, such as the desktop cache preparation checks.
+
+Desktop SDK and pub caches are prepared on `main` when their inputs change by
+**Prepare desktop caches**. Run that workflow on `main` after cache eviction if
+needed; it does not publish anything. Release tags restore those caches without
+saving another tag-specific copy. Cache misses still install the pinned SDK and
+resolve dependencies normally. macOS enables Swift Package Manager before pub get.
+The shared keys include SDK version/commit, OS/architecture, and the dependency
+lockfiles for pub. Signing, notarization and artifact checks remain required.
+
Native TUI CI tests and builds the shipped musl target in the same Cargo output
directory. Dependency caches are keyed by target, Rust toolchain, and Cargo inputs;
cache hits still run every test. The ten native TUI fixtures run two at a time,
@@ -131,6 +144,32 @@ gate after shipping. Record these UTC timestamps in the PR or release task:
- Merge; each product's release trigger and live publication; completion reported.
- Pauses and waiting, with their known reason. Mark missing data unknown.
+For Desktop, use the existing release command with `--wait` to follow the exact
+tag and source through completion:
+
+```bash
+make release-desktop ARGS="--notes-file /path/to/reviewed-notes.md --wait"
+```
+
+The workflow's `verify` job downloads all six public artifacts three at a time,
+using the updater's Dart user agent, and checks every version, full SHA-256, and
+size. It starts immediately after publication, alongside release-page creation.
+Each transfer has a total deadline; any failure makes the workflow fail and keeps
+the JSON receipt in the `desktop-release-verification` artifact. A successful
+verification satisfies that release's download checks: report completion instead
+of downloading everything again locally. The watcher requires this job to pass
+and checks the tag's full SHA, so another release's success cannot satisfy it.
+
+For a release made before that job existed, or to investigate a download failure:
+
+```bash
+python3 scripts/verify-desktop-release.py 1.2.51
+```
+
+This is read-only. A failed verification after publication means the release may
+already be live; inspect the receipt and fix the cause rather than blindly
+retagging or retrying immutable artifact uploads.
+
Report both total elapsed time and its stages. For small changes, aim to return to
the team's previous 10–15 minute merge/release overhead; publishing duration alone
does not demonstrate that target. At ten minutes without progress, identify the
diff --git a/scripts/tests/test_desktop_verification.py b/scripts/tests/test_desktop_verification.py
new file mode 100644
index 000000000..85d665d94
--- /dev/null
+++ b/scripts/tests/test_desktop_verification.py
@@ -0,0 +1,131 @@
+"""Exercise the real HTTP/download/hash contract, including deadlines and concurrency."""
+import hashlib
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+import importlib.util
+import json
+from pathlib import Path
+import tempfile
+import threading
+import time
+import unittest
+
+SCRIPT = Path(__file__).resolve().parents[1] / "verify-desktop-release.py"
+spec = importlib.util.spec_from_file_location("verify_desktop", SCRIPT)
+verify = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(verify)
+
+
+class DesktopVerificationTests(unittest.TestCase):
+ def setUp(self):
+ self.payload = b"release artifact fixture\0" * 100
+ self.requests = []
+ self.active = 0
+ self.peak = 0
+ self.delay = 0.03
+ self.lock = threading.Lock()
+ test = self
+
+ class Handler(BaseHTTPRequestHandler):
+ def log_message(self, *_):
+ pass
+
+ def do_GET(self):
+ test.requests.append((self.path, self.headers.get("User-Agent")))
+ if self.path == "/metadata.json":
+ payload = json.dumps(test.manifest).encode()
+ elif self.path == "/missing":
+ self.send_error(404)
+ return
+ else:
+ with test.lock:
+ test.active += 1
+ test.peak = max(test.peak, test.active)
+ time.sleep(test.delay)
+ with test.lock:
+ test.active -= 1
+ payload = test.payload
+ self.send_response(200)
+ self.send_header("Content-Length", str(len(payload)))
+ self.end_headers()
+ try:
+ self.wfile.write(payload)
+ except (BrokenPipeError, ConnectionResetError):
+ pass
+
+ self.server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
+ self.thread = threading.Thread(target=self.server.serve_forever, daemon=True)
+ self.thread.start()
+ self.base = f"http://127.0.0.1:{self.server.server_port}"
+ self.manifest = {
+ key: dict(version="1.2.3", url=f"{self.base}/{key}",
+ size=len(self.payload), sha256=hashlib.sha256(self.payload).hexdigest())
+ for key in verify.KEYS
+ }
+
+ def tearDown(self):
+ self.server.shutdown()
+ self.server.server_close()
+ self.thread.join()
+
+ def run_verification(self, **kwargs):
+ return verify.verify("1.2.3", self.base + "/metadata.json", **kwargs)
+
+ def test_all_six_full_downloads_with_updater_agent_and_bounded_parallelism(self):
+ receipt = self.run_verification(jobs=2)
+ self.assertEqual(receipt["status"], "passed", receipt)
+ self.assertEqual(len(receipt["artifacts"]), 6)
+ self.assertEqual(self.peak, 2)
+ self.assertEqual(len(self.requests), 7)
+ self.assertTrue(all(agent == verify.USER_AGENT for _, agent in self.requests))
+ self.assertTrue(all(item["actual_size"] == len(self.payload) for item in receipt["artifacts"]))
+
+ def test_missing_or_mixed_version_fails_before_artifact_downloads(self):
+ for change in ("missing", "version"):
+ with self.subTest(change=change):
+ original = self.manifest.pop(verify.KEYS[0])
+ if change == "version":
+ self.manifest[verify.KEYS[0]] = dict(original, version="1.2.2")
+ self.requests.clear()
+ self.assertEqual(self.run_verification()["status"], "failed")
+ self.assertEqual(len(self.requests), 1)
+ self.manifest[verify.KEYS[0]] = original
+
+ def test_bad_schema_fails_before_artifact_downloads(self):
+ for patch in ({"size": True}, {"size": 0}, {"sha256": "bad"}, {"url": "file:///etc/passwd"}, {"url": "http://example.com/download"}):
+ with self.subTest(patch=patch):
+ original = self.manifest[verify.KEYS[0]]
+ self.manifest[verify.KEYS[0]] = dict(original, **patch)
+ self.requests.clear()
+ self.assertEqual(self.run_verification()["status"], "failed")
+ self.assertEqual(len(self.requests), 1)
+ self.manifest[verify.KEYS[0]] = original
+
+ def test_hash_size_and_http_failures_are_not_reported_as_passed(self):
+ for patch in ({"sha256": "0" * 64}, {"size": len(self.payload) + 1}, {"size": len(self.payload) - 1}, {"url": self.base + "/missing"}):
+ with self.subTest(patch=patch):
+ original = self.manifest[verify.KEYS[0]]
+ self.manifest[verify.KEYS[0]] = dict(original, **patch)
+ receipt = self.run_verification()
+ self.assertEqual(receipt["status"], "failed")
+ self.assertEqual(receipt["artifacts"][0]["status"], "failed")
+ self.assertEqual(sum(item["status"] == "passed" for item in receipt["artifacts"]), 5)
+ self.manifest[verify.KEYS[0]] = original
+
+ def test_transfer_deadline_fails_in_bounded_time(self):
+ self.delay = 1.5
+ start = time.monotonic()
+ receipt = self.run_verification(timeout=0.1, jobs=6)
+ self.assertEqual(receipt["status"], "failed")
+ self.assertLess(time.monotonic() - start, 1.3)
+
+ def test_cli_preserves_failed_receipt_and_exit_status(self):
+ self.manifest.pop(verify.KEYS[0])
+ with tempfile.TemporaryDirectory() as folder:
+ receipt = Path(folder) / "receipt.json"
+ code = verify.main(["1.2.3", "--manifest-url", self.base + "/metadata.json", "--receipt", str(receipt)])
+ self.assertEqual(code, 1)
+ self.assertEqual(json.loads(receipt.read_text())["status"], "failed")
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/scripts/tests/test_watch_desktop_release.py b/scripts/tests/test_watch_desktop_release.py
new file mode 100644
index 000000000..d2dd942b1
--- /dev/null
+++ b/scripts/tests/test_watch_desktop_release.py
@@ -0,0 +1,53 @@
+import importlib.util
+from pathlib import Path
+import unittest
+from unittest.mock import patch
+
+SCRIPT = Path(__file__).resolve().parents[1] / "watch-desktop-release.py"
+spec = importlib.util.spec_from_file_location("watch_desktop", SCRIPT)
+watch = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(watch)
+TAG = "v1.2.3_desktop"
+SHA = "a" * 40
+RUN = dict(databaseId=123, headSha=SHA, headBranch=TAG, url="https://github.com/owner/repo/actions/runs/123")
+DONE = dict(headSha=SHA, headBranch=TAG, status="completed", conclusion="success",
+ jobs=[dict(name="verify", status="completed", conclusion="success")])
+
+
+class ReleaseWatchTests(unittest.TestCase):
+ def test_exact_tag_sha_lookup_and_verified_success(self):
+ other = dict(RUN, headSha="b" * 40, databaseId=124)
+ with patch.object(watch, "gh_json", side_effect=[[other, RUN], DONE]) as gh:
+ self.assertEqual(watch.watch(TAG, SHA), RUN)
+ args = gh.call_args_list[0].args[0]
+ self.assertIn("release-desktop.yml", args)
+ self.assertEqual(args[args.index("--branch") + 1], TAG)
+ self.assertEqual(args[args.index("--commit") + 1], SHA)
+ self.assertEqual(gh.call_args_list[1].args[0][2], "123")
+
+ def test_failed_workflow_or_absent_verification_is_not_success(self):
+ for result in (dict(DONE, conclusion="failure"), dict(DONE, jobs=[]), dict(DONE, headSha="b" * 40),
+ dict(DONE, jobs=[dict(name="verify", status="completed", conclusion="skipped")])):
+ with self.subTest(result=result), patch.object(watch, "gh_json", side_effect=[[RUN], result]):
+ with self.assertRaises(RuntimeError):
+ watch.watch(TAG, SHA)
+
+ def test_appearance_wait_is_bounded(self):
+ with patch.object(watch, "gh_json", return_value=[]), patch.object(watch.time, "monotonic", side_effect=[0, 1, 1, 181]):
+ with self.assertRaisesRegex(TimeoutError, "no release-desktop.yml run appeared"):
+ watch.watch(TAG, SHA)
+
+ def test_in_progress_run_is_rechecked_without_another_validation(self):
+ pending = dict(DONE, status="in_progress", conclusion="", jobs=[])
+ with patch.object(watch, "gh_json", side_effect=[[RUN], pending, DONE]) as gh, patch.object(watch.time, "sleep"):
+ self.assertEqual(watch.watch(TAG, SHA), RUN)
+ self.assertEqual(len(gh.call_args_list), 3)
+
+ def test_overall_deadline_is_bounded(self):
+ with patch.object(watch.time, "monotonic", side_effect=[0, 2]):
+ with self.assertRaisesRegex(TimeoutError, "within 1s"):
+ watch.watch(TAG, SHA, timeout=1)
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/scripts/verify-desktop-release.py b/scripts/verify-desktop-release.py
new file mode 100644
index 000000000..def1ca95f
--- /dev/null
+++ b/scripts/verify-desktop-release.py
@@ -0,0 +1,158 @@
+#!/usr/bin/env python3
+"""Verify all six public Desktop downloads concurrently, without storing the binaries.
+
+Uses the updater's Dart user agent, full SHA-256/size checks and curl's total
+transfer deadline (a socket idle timeout alone does not bound a slow transfer).
+Only reads public endpoints; never publishes or changes a manifest.
+"""
+import argparse
+from concurrent.futures import ThreadPoolExecutor
+from datetime import datetime, timezone
+import hashlib
+import json
+import os
+from pathlib import Path
+import re
+import subprocess
+import sys
+import time
+from urllib.parse import urlsplit
+
+KEYS = (
+ "desktop-macos", "desktop-macos-dmg", "desktop-macos-arm64",
+ "desktop-macos-arm64-dmg", "desktop-linux-x64", "desktop-linux-arm64",
+)
+MANIFEST = "https://storage.googleapis.com/s3-autonomous-upgrade-3/harness/desktop/metadata.json"
+USER_AGENT = "Dart/3.13 (dart:io)"
+
+
+def utc_now():
+ return datetime.now(timezone.utc).isoformat()
+
+
+def curl_command(url, timeout):
+ parsed = urlsplit(url)
+ # Loopback HTTP permits real local-server regression tests. Public downloads
+ # and redirects must use HTTPS; never pass manifest text through a shell.
+ loopback = parsed.scheme == "http" and parsed.hostname in ("127.0.0.1", "::1")
+ if (parsed.scheme != "https" and not loopback) or not parsed.hostname or parsed.username or parsed.password or parsed.fragment:
+ raise ValueError(f"invalid public download URL: {url!r}")
+ return [
+ "curl", "--fail", "--location", "--silent", "--show-error",
+ "--connect-timeout", str(min(15, timeout)), "--max-time", str(timeout),
+ "--proto", "=http,https" if loopback else "=https", "--proto-redir", "=https",
+ "--user-agent", USER_AGENT, "--url", url,
+ ]
+
+
+def read_manifest(url, timeout):
+ result = subprocess.run(
+ curl_command(url, timeout) + ["--max-filesize", "1048576"],
+ capture_output=True, timeout=timeout + 2,
+ )
+ if result.returncode:
+ raise ValueError("manifest download failed: " + result.stderr.decode(errors="replace").strip())
+ return json.loads(result.stdout), hashlib.sha256(result.stdout).hexdigest()
+
+
+def entries_for_version(manifest, version):
+ if not re.fullmatch(r"(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)", version):
+ raise ValueError("expected version must be X.Y.Z")
+ if not isinstance(manifest, dict):
+ raise ValueError("manifest must be an object")
+ entries = []
+ for key in KEYS:
+ entry = manifest.get(key)
+ if not isinstance(entry, dict) or entry.get("version") != version:
+ raise ValueError(f"{key}: missing entry or version differs from {version}")
+ if type(entry.get("size")) is not int or entry["size"] <= 0:
+ raise ValueError(f"{key}: size must be a positive integer")
+ if not isinstance(entry.get("sha256"), str) or not re.fullmatch(r"[0-9a-f]{64}", entry["sha256"]):
+ raise ValueError(f"{key}: invalid SHA-256")
+ if not isinstance(entry.get("url"), str):
+ raise ValueError(f"{key}: missing URL")
+ curl_command(entry["url"], 1) # Validate every entry before starting downloads.
+ entries.append((key, entry))
+ return entries
+
+
+def verify_artifact(item, timeout):
+ key, entry = item
+ started = time.monotonic()
+ result = {field: entry[field] for field in ("version", "url", "sha256", "size")}
+ result.update(key=key, started_at=utc_now(), status="failed")
+ digest = hashlib.sha256()
+ size = 0
+ try:
+ with subprocess.Popen(
+ curl_command(entry["url"], timeout) + ["--max-filesize", str(entry["size"])],
+ stdout=subprocess.PIPE, stderr=subprocess.PIPE,
+ ) as process:
+ try:
+ for chunk in iter(lambda: process.stdout.read(1024 * 1024), b""):
+ size += len(chunk)
+ digest.update(chunk)
+ error = process.stderr.read().decode(errors="replace").strip()
+ if process.wait() != 0:
+ raise ValueError(f"download failed: {error}")
+ finally:
+ if process.poll() is None:
+ process.kill()
+ process.wait()
+ if size != entry["size"]:
+ raise ValueError(f"size mismatch: expected {entry['size']}, received {size}")
+ if digest.hexdigest() != entry["sha256"]:
+ raise ValueError("SHA-256 mismatch")
+ result["status"] = "passed"
+ except (OSError, ValueError) as error:
+ result["error"] = str(error)
+ result.update(actual_size=size, actual_sha256=digest.hexdigest(),
+ finished_at=utc_now(), duration_seconds=round(time.monotonic() - started, 3))
+ print(f"{key}: {result['status']} ({result['duration_seconds']}s)" +
+ (f" — {result['error']}" if "error" in result else ""), flush=True)
+ return result
+
+
+def verify(version, manifest_url=MANIFEST, jobs=3, timeout=90):
+ started = time.monotonic()
+ receipt = dict(version=version, manifest_url=manifest_url, started_at=utc_now(),
+ source_sha=os.environ.get("GITHUB_SHA"), run_id=os.environ.get("GITHUB_RUN_ID"),
+ status="failed", artifacts=[])
+ try:
+ manifest, receipt["manifest_sha256"] = read_manifest(manifest_url, min(20, timeout))
+ entries = entries_for_version(manifest, version)
+ with ThreadPoolExecutor(max_workers=jobs) as pool:
+ receipt["artifacts"] = list(pool.map(lambda item: verify_artifact(item, timeout), entries))
+ if all(item["status"] == "passed" for item in receipt["artifacts"]):
+ receipt["status"] = "passed"
+ except (OSError, ValueError, subprocess.TimeoutExpired) as error:
+ receipt["error"] = str(error)
+ receipt.update(finished_at=utc_now(), duration_seconds=round(time.monotonic() - started, 3))
+ return receipt
+
+
+def main(argv=None):
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("version")
+ parser.add_argument("--manifest-url", default=MANIFEST)
+ parser.add_argument("--receipt", type=Path, default=Path(".harness/desktop-release-verification.json"))
+ parser.add_argument("--jobs", type=int, choices=range(1, 7), default=3)
+ parser.add_argument("--timeout", type=int, choices=range(1, 301), default=90, metavar="SECONDS")
+ args = parser.parse_args(argv)
+ receipt = verify(args.version, args.manifest_url, args.jobs, args.timeout)
+ args.receipt.parent.mkdir(parents=True, exist_ok=True)
+ args.receipt.write_text(json.dumps(receipt, indent=2) + "\n")
+ message = f"Desktop {args.version}: {receipt['status']} in {receipt['duration_seconds']}s"
+ if receipt.get("error"):
+ message += f" — {receipt['error']}"
+ print(message)
+ if summary := os.environ.get("GITHUB_STEP_SUMMARY"):
+ with open(summary, "a") as stream:
+ stream.write(message + "\n\n| Download | Result | Seconds |\n|---|---|---|\n")
+ for item in receipt["artifacts"]:
+ stream.write(f"| {item['key']} | {item['status']} | {item['duration_seconds']} |\n")
+ return 0 if receipt["status"] == "passed" else 1
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/scripts/watch-desktop-release.py b/scripts/watch-desktop-release.py
new file mode 100644
index 000000000..8d4466161
--- /dev/null
+++ b/scripts/watch-desktop-release.py
@@ -0,0 +1,79 @@
+#!/usr/bin/env python3
+"""Wait for one Desktop tag/commit to publish and pass its automated verification."""
+import argparse
+import json
+import re
+import subprocess
+import sys
+import time
+
+
+def gh_json(args, timeout):
+ result = subprocess.run(["gh", *args], capture_output=True, text=True, timeout=timeout)
+ if result.returncode:
+ raise RuntimeError(result.stderr.strip() or "GitHub lookup failed")
+ return json.loads(result.stdout)
+
+
+def watch(tag, sha, timeout=1800, appear_timeout=180):
+ if not re.fullmatch(r"v[0-9]+\.[0-9]+\.[0-9]+_desktop", tag) or not re.fullmatch(r"[0-9a-f]{40}", sha):
+ raise ValueError("supply a Desktop release tag and its full commit SHA")
+ started = time.monotonic()
+ deadline = started + timeout
+ run = None
+ previous = None
+ while time.monotonic() < deadline:
+ remaining = max(1, min(30, deadline - time.monotonic()))
+ if run is None:
+ runs = gh_json([
+ "run", "list", "--workflow", "release-desktop.yml", "--event", "push",
+ "--branch", tag, "--commit", sha, "--limit", "5",
+ "--json", "databaseId,headSha,headBranch,url",
+ ], remaining)
+ matches = [item for item in runs if item["headSha"] == sha and item["headBranch"] == tag]
+ if matches:
+ run = matches[0] # gh returns newest first, including a rerun of the exact source.
+ print(f"Watching {tag} at {sha[:12]}: {run['url']}", flush=True)
+ elif time.monotonic() - started >= appear_timeout:
+ raise TimeoutError(f"no release-desktop.yml run appeared for {tag} at {sha}")
+ if run is not None:
+ detail = gh_json([
+ "run", "view", str(run["databaseId"]),
+ "--json", "headSha,headBranch,status,conclusion,jobs",
+ ], max(1, min(30, deadline - time.monotonic())))
+ if detail["headSha"] != sha or detail["headBranch"] != tag:
+ raise RuntimeError("release run does not match the requested tag/commit")
+ state = ", ".join(f"{job['name']}: {job['conclusion'] or job['status']}" for job in detail["jobs"])
+ if state != previous:
+ print(state or detail["status"], flush=True)
+ previous = state
+ if detail["status"] == "completed":
+ if detail["conclusion"] != "success":
+ raise RuntimeError(f"release {detail['conclusion']}: {run['url']}")
+ if not any(job["name"] == "verify" and job["conclusion"] == "success" for job in detail["jobs"]):
+ raise RuntimeError("run has no successful public-download verification; use verify-desktop-release.py for older releases")
+ release_url = run["url"].split("/actions/runs/", 1)[0] + "/releases/tag/" + tag
+ print(f"Published and verified: {release_url}", flush=True)
+ return run
+ time.sleep(max(0, min(10, deadline - time.monotonic())))
+ raise TimeoutError(f"release did not complete within {timeout}s; inspect " + (run["url"] if run else tag))
+
+
+def main(argv=None):
+ parser = argparse.ArgumentParser(description=__doc__)
+ parser.add_argument("tag")
+ parser.add_argument("--sha", required=True)
+ parser.add_argument("--timeout", type=int, default=1800)
+ args = parser.parse_args(argv)
+ if args.timeout <= 0:
+ parser.error("--timeout must be positive")
+ try:
+ watch(args.tag, args.sha, args.timeout)
+ except (OSError, ValueError, RuntimeError, subprocess.TimeoutExpired) as error:
+ print(f"error: {error}", file=sys.stderr)
+ return 1
+ return 0
+
+
+if __name__ == "__main__":
+ sys.exit(main())