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.

46.0 KB
Raw Blame

Releasing the desktop app

Running apps self-update from a public GCS bucket (lib/update/desktop_updater.dart). Releasing is pushing a tag: ../.github/workflows/release-desktop.yml builds both macOS builds (Intel on Skia, Apple Silicon on Impeller — see "Two macOS builds" below) and both Linux architectures, publishes them to that bucket, and cuts the GitHub Release. The tag IS the version — CI never bumps.

Tags are vX.Y.Z_desktop, not plain vX.Y.Z: the CLI (cli/, tags vX.Y.Z_cli) and the backend (backend/, tags vX.Y.Z_backend) release from this same repo, so the suffix is what tells each tag-push trigger which workflow to run. It is stripped before anything treats it as a version — the manifest, --build-name, the release title and the updater's comparison all see a bare X.Y.Z.

# from the repo root (or `cd desktop && make release ...`, which is the same script)
make release-desktop                       # bump the patch, tag, push — CI does the rest
make release-desktop ARGS="--dry-run"      # print the version it would cut and the notes, do nothing
make release-desktop ARGS="--minor"        # bump the MINOR version, per the usual semver convention
make release-desktop ARGS="1.3.0"          # release an explicit version
make release-desktop ARGS="--notes-file notes.md"   # hand-written release notes
make release-desktop ARGS="--prepare"      # package the final pushed PR head during tests/review; publish nothing
make release-desktop ARGS="--wait"         # release, then follow this exact tag through public verification

Nothing is built locally and no GCS credentials are needed. The script uses Git and a public HTTPS read of the manifest; --prepare and --wait also need the authenticated gh CLI.

For an authorized release, run --prepare once the final implementation is pushed to its PR branch, while the required tests and review run. It selects the next version by the same rules as a release, builds/signs/notarizes all platforms in CI, and verifies all nine downloads at an isolated candidate path. It creates neither a release tag nor a product manifest/Release page. After checks pass, merge and release that same version normally. CI reuses the candidate only when the Desktop build inputs and version match; unrelated component merges and a clean squash are supported. Changed build inputs or version require a new build. Candidate packaging does not replace application tests or authorize publication. See the validation guide for identity checks, bounded waiting, expiration and disposable promotion validation.

Why the version comes from two places. scripts/release-desktop.sh takes the highest of the last git tag and the highest version in the live metadata.json, across every desktop-* key. Publishing used to be a local command that bumped from the manifest and tagged nothing, so the two drifted: this repo once had a single tag v1.0.52 while the manifest was already serving 1.0.61. Bumping from tags alone there produces a version LOWER than what users run — every app refuses it (semverGt) while the release still reports success. That local path is gone; the tag is now the only way in.

A release contains the one before it. The script refuses a checkout that lacks the last release's commit (the highest v*_desktop tag, and the tag of the version the manifest serves): it is still on origin/main, so nothing else stopped it, and it would ship older code under a newer version to every app. v1.2.36_desktop was cut that way on October 1, 2026, twenty commits behind v1.2.35_desktop. Update the checkout (git fetch origin && git checkout --detach origin/main). A rollback, which means to do exactly this, is make release-desktop ARGS="--allow-older". --prepare is not checked: it publishes nothing. make release-web checks the same against the last v*_web tag.

pubspec.yaml's version: field is never touched; it's a dev-only placeholder.

Managed Node runtime

Node lives under ~/.harness/runtime and does not alter the user's system Node, Homebrew, nvm, or shell PATH. That is the point of it — the CLI launcher is written against that exact binary, so a Finder launch (where PATH is launchd's bare /usr/bin:/bin:/usr/sbin:/sbin) and a Terminal launch behave identically.

The desktop app no longer installs it; the harness installer does — for the app's first run and for a terminal install alike. This repo still owns the publishing, so the command below is unchanged and still has to be run before a release needs a newer Node. Publish macOS and Linux archives for both ARM64 and x64 (including machines where uname -m reports amd64) before releasing a desktop build that requires a new Node version:

make upload-node-runtime ARGS="22.23.2"

The publisher downloads the official Node archives and SHASUMS256.txt, verifies each archive before uploading, then atomically merges harness/runtime/metadata.json. The app verifies the manifest's size and SHA-256 again before extracting an archive. A runtime manifest applies to fresh installs; roll out a changed runtime to existing users with a newer desktop build. Never replace an existing versioned archive in place.

Until that managed manifest covers a platform, the desktop build falls back to its checksum-pinned official Node 22 archive for it. The fallback keeps first-run setup functional but is intentionally not a replacement for publishing the managed runtime channel before release.

tmux is a separate step and unrelated to Node: on macOS it comes from Homebrew when Homebrew is already there, else from the managed runtime below; on Linux from apt — and only when tmux is missing; a computer that already runs it is never asked about any of them.

Managed tmux runtime (macOS)

The same idea as Node, for the one host dependency that still came from a package manager: a checksum-verified tmux archive under harness/runtime/tmux/, built once per tmux version so a Mac with no tmux and no Homebrew can obtain it with no compiler, no package manager and no password. cli/scripts/build-managed-tmux.sh builds tmux against static libevent and ncurses (terminfo is read from macOS's own /usr/share/terminfo); the result links only libSystem and is ad-hoc signed. Its three macOS traps — the toolchain clang needing SDKROOT, tmux's configure silently linking the system ncurses 5.4 unless LIBTINFO_LIBS is explicit, and libevent's autoconf detecting a pipe2 macOS does not have — are handled in the script and gated by otool -L and a real new-session smoke test (under Rosetta for the x64 build). pkg-config is pointed at our own .pc files only (PKG_CONFIG_LIBDIR) and jemalloc is disabled: with Homebrew on the build host — every CI runner — tmux 3.7's configure otherwise picks up a Homebrew jemalloc. Keep the pinned tmux level with what Homebrew ships (3.7c today): a tmux client and server must agree on their protocol, and a managed client older than a Homebrew server on the same socket only says "server exited unexpectedly".

Publish from CI, never by hand unless rebuilding the same version:

gh workflow run release-tmux-runtime.yml -f tmux_version=3.7c                  # build both, publish
gh workflow run release-tmux-runtime.yml -f tmux_version=3.7c -f publish=false # build only, inspect
make upload-tmux-runtime ARGS="3.7c /path/to/archives"                          # the publisher CI calls

The manifest is harness/runtime/tmux/metadata.json — its own file, because install.sh slices a manifest by the first "<platform>" key and Node's already has one — with the same {version,url,sha256,size,archiveRoot} entries. install.sh reads it on a Mac that has no tmux and no Homebrew (Homebrew's tmux is used when Homebrew is already there): download into ~/.harness/runtime/tmux-<ver>-<platform>, verify, record the binary in ~/.harness/runtime/current-tmux (which the daemon's ensureTmuxOnPath falls back to when neither its PATH nor the user's login shell resolves a tmux — the terminal's tmux always wins, so daemon and terminal share one server) and link it as ~/.local/bin/tmux. The desktop runs that same install.sh --host in-app, so on macOS first-run setup never opens a Terminal window. Publish a new runtime before the install.sh that pins a newer tmux level, and keep it level with what Homebrew ships.

Managed grid runtime

The grid CLI, as a runtime beside Node and tmux: the daemon shells out to grid for every Local model (gridExec.ts), and the Local model manager has an agent run it by name in its pane, so a machine that installs the harness must have one without a second installer. Same shape as the other two — harness/runtime/grid/metadata.json, its own manifest for the reason tmux has one, entries {version,url,sha256,size,archiveRoot}, archives grid-<ver>-<platform>/bin/grid — with one difference: the manifest's version is a pin. install.sh lays that grid down (step 3b, optional: a failed download does not fail the install), and the daemon moves every installed machine to it on its next start (ensureManagedGrid), keeping one version back for the panes still running the old one. Laid down read-only, bin/ included, so grid update — an os.replace into that directory — fails loudly instead of overwriting the pin; the daemon also sets GRID_NO_UPDATE_CHECK=1 on every spawn and pane. Never linked into ~/.local/bin: that path is grid's own installer's (uv's, on a Mac), and the daemon puts the managed grid on an agent pane's PATH itself.

Linux archives wrap autonomous-grid's own release binaries (grid-linux-{x86_64,arm64}, verified against the release's SHA256SUMS at build time, then re-hosted under our manifest so nothing is fetched from GitHub at install time). macOS archives are built by cli/scripts/build-managed-grid.sh from a checkout of the release tag with grid's own packaging/build_binary.sh — Nuitka onefile, ad-hoc signed, not notarized: the SIGKILL grid's README attributes to ad-hoc signing is Gatekeeper on a quarantined download, which a curl-fetched runtime never is (the managed tmux runs the same way). Nuitka does not cross-compile, so darwin-x64 builds on an Intel runner; drop it from platforms when none is available.

gh workflow run release-grid-runtime.yml -f grid_version=0.3.47                                   # build all four, publish
gh workflow run release-grid-runtime.yml -f grid_version=0.3.47 -f publish=false                  # build only, inspect
gh workflow run release-grid-runtime.yml -f grid_version=0.3.47 -f platforms=darwin-arm64,linux-x64,linux-arm64
make upload-grid-runtime ARGS="0.3.47 /path/to/archives"                                          # the publisher CI calls

The pin may only move to a version at or above GRID_VERSION_FLOOR (cli/src/lib/gridExec.ts); the publisher refuses anything lower, because the daemon would too. Move the floor and the pin in the same change when a harness release starts to need a newer grid.

Two macOS builds — Intel on Skia, Apple Silicon on Impeller

Every release ships the macOS app twice: the same universal (arm64 + x86_64) build of the same commit, differing in one Info.plist key, FLTEnableImpeller — which renderer Flutter draws with.

Build Renderer Manifest keys Files Installed by
Intel Skia (FLTEnableImpeller = false) desktop-macos, desktop-macos-dmg Harness-macos.{zip,dmg} Intel Macs, every install from before the split on either CPU, and the website download
Apple Silicon Impeller (the engine default) desktop-macos-arm64, desktop-macos-arm64-dmg Harness-macos-arm64.{zip,dmg} Apple Silicon Macs whose updater knows the key

CI calls scripts/build-macos-variants.py <version> --metadata-prefix <run-prefix>. It compiles one universal app, copies it into separate directories, pins and verifies each renderer, then packages, notarizes and uploads both variants in parallel. Version/build-number, arm64/x86_64 slices, signatures and hardened runtime are checked before publication. Each variant still receives both app and DMG notarization, with the stapled app inside the DMG. Separate scratch manifests are combined only after all macOS, Linux and Windows builds succeed, followed by verification of all nine public downloads. macos-build-timings records the bounded build and per-variant phases. App copies and DMG staging use independent APFS clones when available. The temporary notarization ZIP uses faster compression; the downloadable ZIP retains normal compression and is rebuilt from the stapled app while DMG notarization runs. Compression failures stop publication; uploads wait for both artifacts and their checks. Packaging phase timings are printed in the build log. Signing and both notarization checks remain the same.

scripts/publish-macos-variant.sh intel|apple-silicon <version> remains the single-variant entry point. With --no-build, APP_BUNDLE selects an existing bundle; the uploader's OUTPUT_DIR keeps parallel archives separate. These overrides do not permit rebuilding an arbitrary path. Without --metadata-prefix, the coordinator only builds and verifies local bundles.

To validate workflow changes with real signing and notarization, dispatch desktop-internal-build.yml on the candidate branch with test_build=true. It builds both renderers, verifies all four internal downloads, records timings, and deletes only that run's random artifact prefix. It does not update release tags or the live updater manifest.

Why. Intel users report the app stuttering; Apple Silicon users do not. Flutter renders macOS with Impeller by default, and the one thing that differs between those two users running the same universal build is the GPU Impeller drives — so the Intel build opts out. A release build can only opt out through Info.plist: the engine compiles its command-line switches out of release (GetSwitchesFromEnvironment), and an Info.plist belongs to a bundle, so choosing by CPU means shipping two bundles. The x86_64 code an Intel Mac runs is identical in both — the split is about the renderer, not the CPU slices; a universal build was already native on Intel.

Why both stay universal. The Intel build carries the key every older install polls, Apple Silicon ones included, so it has to launch on both. The Apple Silicon build stays universal so a Mac running it under Rosetta, or a DMG handed to the wrong person, still launches.

Why the Intel build kept the old key and file name. desktop-macos is what every install before the split polls, and desktop-macos-dmg is what harness.autonomous.ai/desktop/download-macos serves. The Skia build there fixes every Intel Mac on its next update, with no new updater needed first, and hands a new visitor a build that works on whatever Mac they have — so the website needed no change. The cost is one release on Skia for an Apple Silicon Mac arriving from an old build or from the website: the build it lands on already asks for desktop-macos-arm64, and moves onto Impeller at the next release (not the same one — the updater only ever moves to a strictly newer version).

How the updater picks (DesktopUpdater._otaKeys). An Intel Mac reads desktop-macos only — the arm64 build renders on exactly what it must not, however new. Apple Silicon reads both and takes the newer, desktop-macos-arm64 winning a tie: a release that published both installs the Impeller build, and one that only moved desktop-macos (a hand publish that stopped halfway, say) still reaches it rather than hiding behind an older arm64 entry.

TODO(BE): this is a workaround, not a diagnosis, and it has a real cost. Every machine this app is developed on is Apple Silicon, on Impeller, so Intel users now run a renderer nobody here looks at, and a Skia-only rendering bug reaches them unseen. Nothing here has measured that Skia cures the stutter either — confirm it with an Intel user on the first release that carries it, and if they still stutter on Skia, the renderer was not the cause and this split should go. The Grid app is the precedent both ways: it added this exact opt-out for Intel (autonomous-grid-app 87def3c6) and removed it the same day (58687e7f), because its real cause turned out to be CI shipping a newer Flutter than the team ran, fixed by pinning. Harness's release already builds with the Flutter it is developed on (FLUTTER_VERSION in release-desktop.yml), so that cause does not apply here. Re-check on every Flutter bump: the engine reads FLTEnableImpeller in FlutterDartProject.mm, and the day that read goes away the Intel build silently goes back to Impeller.

Publishing by hand

scripts/publish-macos-variant.sh (one macOS build per run) and scripts/upload-desktop-linux.sh are the publishing steps. The macOS one builds and pins the renderer, then hands the bundle to scripts/upload-desktop.sh --no-build, which does everything after the build exactly as it always has. CI runs them with the version taken from the tag, and they are also reachable directly when CI cannot be:

make upload-desktop VERSION=1.3.0                          # both macOS builds, Intel first
make upload-desktop VERSION=1.3.0 ARGS="--no-notarize"     # the same, Developer ID signed only
bash scripts/publish-macos-variant.sh intel 1.3.0          # one macOS build
bash scripts/publish-macos-variant.sh apple-silicon 1.3.0
bash scripts/publish-macos-variant.sh intel 1.3.0 --build-only   # build + pin the renderer, publish nothing
make upload-desktop-linux ARCH=arm64                       # per Linux architecture

macOS takes an explicit version. Two runs have to publish one version, and upload-desktop.sh's own auto-bump reads the manifest — the second run would see the first one's upload and bump again. make release-desktop ARGS="--dry-run" prints the next one. ⚠️ upload-desktop.sh run on its own still works, and is now wrong: it builds without the renderer pin and writes desktop-macos, which puts Impeller back on every Intel Mac. Go through publish-macos-variant.sh.

These create no git tag, so the repo stops reflecting what is published — one tag, v1.0.52, once sat nine releases behind a manifest already serving 1.0.61. Prefer make release-desktop; if you do publish by hand, cut a make release-desktop afterwards to bring the tag back in line, and remember it only publishes the platform you ran it on.

For one macOS build, publish-macos-variant.sh:

  1. Takes the build (intel / apple-silicon) and the version it was given (CI passes the tag's X.Y.Z).
  2. Runs flutter build macos --release --build-name=<version> --build-number=<n> — the version is stamped into the bundle's Info.plist at build time, not read from any file.
  3. Pins the renderer. Intel: writes FLTEnableImpeller = false, reads it back, and re-signs the outer bundle — the edit broke Xcode's seal — keeping the identity, hardened runtime and entitlements Xcode signed it with, and failing if the entitlements come out different. Apple Silicon: writes nothing, and fails if the key is there, so an opt-out committed to macos/Runner/Info.plist cannot quietly put it on Skia. Both then verify the signature and the hardened runtime.
  4. Hands the bundle to upload-desktop.sh --no-build with that build's keys and file names (OTA_KEY, DMG_KEY, GCS_PATH, DMG_GCS_PATH — set per build, so two runs cannot write each other's), which:
  5. Asserts the built bundle's CFBundleShortVersionString really carries that version before publishing anything.
  6. Packages the .app with ditto -c -k --sequesterRsrc --keepParent (keeps the bundle structure and extended attributes intact — a plain zip does not).
  7. Notarizes the zip, staples the ticket into the .app, and asserts Gatekeeper accepts it (spctl).
  8. Packages a .dmg from that same stapled bundle — a staging folder holding Harness.app plus an /Applications symlink, imaged with hdiutil — then signs, notarizes and staples the image too. The final ZIP is rebuilt during DMG notarization; both artifacts must finish and pass their checks.
  9. Uploads both artifacts with a year-long immutable Cache-Control (see "GCS layout").
  10. Download-merge-reuploads metadata.json in a single write, touching only that build's two keys.

A failed build stops the release; nothing is uploaded and no version is consumed.

One build, two artifacts — per macOS build — and why the dmg is separate

Each macOS build is one flutter build and one signature. Its dmg is cut from the bundle its zip was cut from, after stapling — an app stapled afterwards would leave the image carrying an unstapled copy that Gatekeeper can only clear by calling Apple on first launch.

The two artifacts serve different jobs and must not be merged:

  • zip / desktop-macos, desktop-macos-arm64 — what DesktopUpdater consumes. It unpacks with ditto -x -k and then mvs the running bundle in place. It has no code path for a disk image, and a mounted dmg volume is read-only, so it could not host the app it is asked to replace.
  • dmg / desktop-macos-dmg, desktop-macos-arm64-dmg — what a person downloads and drags into Applications. Nothing in the app ever reads these keys.

Expect two notarization submissions per build — four per release, the two builds in parallel on CI. They cannot be collapsed: stapling only attaches a ticket to the exact artifact submitted, so the zip's ticket does not cover the image. The second pass is usually quick because Apple has already seen that app's cdhash.

Publishing also refreshes the public download link with no web deploy: harness.autonomous.ai/desktop/download-macos (in autonomous-code, apps/web/src/app/desktop/download-macos/) resolves desktop-macos-dmg — the Intel build, which runs on any Mac — from this same manifest on every request, so the new version is live the moment step 10 lands. Offering the Apple Silicon dmg there is a change in that repo, not this one.

GCS layout

gs://s3-autonomous-upgrade-3/harness/desktop/metadata.json
gs://s3-autonomous-upgrade-3/harness/desktop/<version>/Harness-macos.zip         (Intel build, Skia)
gs://s3-autonomous-upgrade-3/harness/desktop/<version>/Harness-macos.dmg
gs://s3-autonomous-upgrade-3/harness/desktop/<version>/Harness-macos-arm64.zip   (Apple Silicon build, Impeller)
gs://s3-autonomous-upgrade-3/harness/desktop/<version>/Harness-macos-arm64.dmg

The manifest is always read straight off the GCS origin (CDN_ASSET_BASE_URL in upload-desktop.sh/ upload-desktop-linux.sh does not apply to it) — it's polled every ~60s by every running app, and this product's CDN caps any cacheable response at ~31 days regardless of origin headers, so it must never be CDN-fronted. The zip/dmg/AppImage it points at are the opposite: immutable once published, so their url fields point at cdn.autonomous.ai instead, and are uploaded with a long Cache-Control on purpose.

{
  "desktop-macos": {
    "version": "1.2.4",
    "url": "https://cdn.autonomous.ai/harness/desktop/1.2.4/Harness-macos.zip",
    "sha256": "<64 hex>",
    "size": 45231920
  },
  "desktop-macos-dmg": {
    "version": "1.2.4",
    "url": "https://cdn.autonomous.ai/harness/desktop/1.2.4/Harness-macos.dmg",
    "sha256": "<64 hex>",
    "size": 47118336
  },
  "desktop-macos-arm64": {
    "version": "1.2.4",
    "url": "https://cdn.autonomous.ai/harness/desktop/1.2.4/Harness-macos-arm64.zip",
    "sha256": "<64 hex>",
    "size": 45231920
  },
  "desktop-macos-arm64-dmg": {
    "version": "1.2.4",
    "url": "https://cdn.autonomous.ai/harness/desktop/1.2.4/Harness-macos-arm64.dmg",
    "sha256": "<64 hex>",
    "size": 47118336
  }
}

The bucket must be public-read — that is bucket policy, not something the script sets.

Signing — Developer ID, notarized

The Release build is signed with a real Developer ID Application certificate (team 54DJVWMJCC, "Autonomous Inc.") and notarized — a freshly downloaded copy (browser, Slack, AirDrop — anything that sets the com.apple.quarantine extended attribute) passes Gatekeeper with no "unidentified developer" prompt and no manual Open Anyway/xattr -d workaround needed.

What that takes, end to end:

  • The signing certificate (Developer ID Application: Autonomous Inc. (54DJVWMJCC)) must be in the machine's login keychain — not the System keychain, which prompts for an admin password on every codesign invocation and breaks a non-interactive build. security find-identity -v -p codesigning should list it with no password needed to check.
  • macos/Runner.xcodeproj's Runner target Release config carries CODE_SIGN_STYLE = Manual, CODE_SIGN_IDENTITY = "Developer ID Application", DEVELOPMENT_TEAM = 54DJVWMJCC, ENABLE_HARDENED_RUNTIME = YES, and OTHER_CODE_SIGN_FLAGS = "--timestamp" — notarization hard- rejects a signature with no secure timestamp ("Archive contains critical validation errors"), and Manual signing style doesn't request one on its own the way Automatic does.
  • macos/Runner/Release.entitlements pins com.apple.security.get-task-allow to false — Flutter's build backend stamps this true regardless of build mode, and notarization rejects a debugger-attachable binary outright.
  • A notarytool keychain profile must exist for the script's notarize step (see the comment block at the top of scripts/upload-desktop.sh for the one-time store-credentials setup — needs an app-specific password from appleid.apple.com, never the Apple ID's own password).

scripts/upload-desktop.sh submits the packaged zip to Apple's notary service (notarytool submit --wait), staples the returned ticket onto the .app (stapler staple — this changes the bundle's contents, so the zip is rebuilt from the stapled bundle before upload), and asserts spctl -a accepts the result before publishing anything. Skip notarizing with --no-notarize (the build stays Developer ID signed, just without Apple's ticket — more likely to prompt Gatekeeper on a copy downloaded fresh by someone else, though probably still fine for the OTA self-update path below, which doesn't reliably pick up the quarantine flag in the first place).

How a running app self-updates

  1. DesktopUpdater checks the manifest once on launch, then every minute (lib/update/desktop_updater.dart) — desktop-macos on an Intel Mac, the newer of desktop-macos-arm64 and desktop-macos on Apple Silicon (see "Two macOS builds").
  2. Compares against the running app's own version (package_info_plus) — strictly newer only, so republishing an old build cannot downgrade anyone.
  3. After the user chooses Update now, downloads the zip and verifies its sha256 before anything is unpacked. A mismatch is discarded.
  4. Unpacks into a staging directory and re-reads CFBundleShortVersionString from the staged bundle as a sanity check that the download really is the version it claims to be. It installs it only if whoever signed the running app signed it too (lib/update/update_signature.dart): on macOS codesign --verify --deep --strict against a Developer ID requirement with the running app's team and identifier, notarized; on Windows every .exe/.dll and the launcher Authenticode-valid, the app, the launcher and app/<version>/harness-desktop.cat signed like the running harness-desktop.exe (subject and Artifact Signing identity), and that catalog matching every file in the folder, data/app.so included. Otherwise the banner says it is not signed by the running app's publisher and the current version stays. The manifest can only pick among builds we signed. A running app that is itself unsigned (a local or staging build) keeps the sha256 check alone; Linux AppImages are unsigned, so Linux does too. Rotating keys: a new Developer ID certificate or a renewed Artifact Signing certificate changes neither the team nor the identity, so nothing is needed. A new team or a new identity validation needs one bridge release, signed the old way, whose rule also accepts the new signer.
  5. Checks on launch (including the sign-in screen) and every minute. When a newer build exists, it shows a non-blocking notification. The user chooses Update now to download and install it, or Skip version to silence that exact version. A later version is shown normally; the account menu also has Check for updates to revisit a skipped version.
  6. On restart: a detached helper process waits for this app to exit, backs the current bundle up as Harness.app.prev, swaps the staged build into place, relaunches it, and — if the relaunched app doesn't stay alive a few seconds later — restores Harness.app.prev and relaunches the old build instead.

Rolling out safely

Publish to a scratch manifest before touching the real one, and point a test build at it via --dart-define. release-desktop.yml has a workflow_dispatch trigger that takes both the version and the manifest to write, so a rehearsal never touches the real one:

gh workflow run release-desktop.yml -f version=1.3.0 -f metadata_path=harness/desktop/metadata-test.json
flutter run -d macos --dart-define=DESKTOP_UPDATE_METADATA_URL=https://storage.googleapis.com/s3-autonomous-upgrade-3/harness/desktop/metadata-test.json

A debug build does not check at all (canCheck wants release mode), so the line above only does something in a release build. To exercise the band, its percentage and the install itself while developing, add --dart-define=DESKTOP_UPDATE_FORCE=true — and always with a scratch manifest, or the debug build will offer to replace itself with the current public release:

flutter run -d macos \
  --dart-define=DESKTOP_UPDATE_FORCE=true \
  --dart-define=DESKTOP_UPDATE_METADATA_URL=http://127.0.0.1:8899/metadata.json

A local origin is enough for that manifest: serve a zip of any Harness.app (its CFBundleShortVersionString must match the version the manifest advertises, which the staging step verifies) with its real size and sha256 — a local build is ad hoc signed, so it skips the signature check (step 4 above), while a released build only takes a zip signed by its own team — and write the body slowly if you want to read the percentage rather than watch it jump to 100. applyStaged replaces the bundle it is running from, so run a COPY of the build rather than the one flutter run owns.

Internal builds — an unlisted link, not a release

../.github/workflows/desktop-internal-build.yml builds any branch the way a release would — both macOS builds, Developer ID signed, notarized, stapled and checked by Gatekeeper — and uploads them where no running app and no public page will ever look:

git push origin HEAD:internal/<name>     # builds that commit: Debug off
gh workflow run desktop-internal-build.yml --ref <branch> -f debug_surface=false

(workflow_dispatch only exists once the file is on main; the internal/** push works from any branch that carries it.) The run prints one .dmg link per build — as a notice at the top of the run page, and in its summary — named Harness-macos[-arm64]-<next version>-<commit>.dmg.

  • Unlisted, not private — and this repository is public. The files sit under harness/desktop-internal/<128 random bits>/ and the bucket refuses anonymous listing, so a build cannot be found by guessing. The run page that prints its link is public, though, so anyone who opens it can download the build. The team chose that on 2026-09-10 over a key-derived link that only key holders could work out; if it stops being acceptable, that is the design to go back to.
  • Take a build back with gcloud storage rm -r gs://s3-autonomous-upgrade-3/harness/desktop-internal/<token> (the summary prints it); the workflow strips the release's year-long cache headers from these files so a deletion sticks.
  • It never updates itself. DESKTOP_UPDATE_METADATA_URL points at a manifest nothing writes, so a tester stays on the build they were asked to test rather than being moved onto the next public release. The next internal build is installed by its own link.
  • Same code path as a release, flags aside. publish-macos-variant.sh --build-only builds and pins the renderer (its --dart-define= arguments go to flutter build and nowhere else), then upload-desktop.sh --no-build packages, notarizes and uploads, moved onto the internal prefix by its existing env overrides (GCS_PATH, DMG_GCS_PATH, METADATA_PATH). Its signing steps are the release's own .github/actions/macos-signing, so an internal build also proves those before a release depends on them.
  • Why not by hand. An Info.plist edited and re-signed on a laptop reached a tester as "The application "Harness" can't be opened", and a laptop without the notarytool profile cannot notarize at all — which is what makes a copy downloaded fresh on another Mac open cleanly.

Rollback

The relaunch-health check (step 6 above) only guards against a build that fails to start. To roll back a build that starts but is otherwise broken, publish a higher version containing the older code — the updater refuses to move backwards, so editing the manifest to an older version will not roll a running app back.

Linux

scripts/upload-desktop-linux.sh publishes architecture-specific Linux ARM64 and x64 releases to the same metadata.json as macOS. release-desktop.yml runs it on both a ubuntu-22.04 and a ubuntu-22.04-arm runner — the oldest Ubuntu supported, because the bundle links the build host's GLib and glibc and a 24.04 build will not start on 22.04 — so one make release-desktop covers every build — which is also why the nine desktop-* keys only stay on one version when the release goes through CI. Run by hand (make upload-desktop-linux ARCH=arm64) it moves one key and leaves the others behind. amd64 and x86_64 are accepted aliases for x64; aarch64 is accepted as an alias for arm64.

With no ARCH, the command detects the host architecture. A build must run on a matching Ubuntu/Linux host because Flutter Linux desktop builds use the host architecture. --no-build can package and upload an already-built bundle for the selected architecture. APPIMAGETOOL must point at an executable appimagetool-<x86_64|aarch64>.AppImage — release-desktop.yml downloads a pinned one per matrix job; running by hand, fetch one yourself from the AppImage/appimagetool releases.

No signing/notarization step — there is no Linux equivalent of Apple's Developer ID/notarization, and none is needed: the trust boundary is the same sha256-verified manifest entry DesktopUpdater already checks on every platform.

The Linux viewer uses the host's WebKitGTK 4.1 runtime (libwebkit2gtk-4.1-0). The AppImage contains Harness and its Flutter bundle, but does not bundle WebKitGTK. The Linux plugin is loaded optionally: if the host runtime or plugin is unavailable, Harness still launches and viewer panes show the URL placeholder (recordings offer browser playback). Install the runtime package and restart Harness to enable embedded viewing. Linux release builds also need libwebkit2gtk-4.1-dev on the build host.

webview_all_linux is deliberately pinned to 1.2.1: its published manifest uses webview_flutter_platform_interface, while 1.3.0 switched to the separate webview_platform_interface package. A caret constraint would allow that incompatible interface change. The lockfile records the source archive hash; upgrading the plugin requires reviewing its native code and rerunning Linux integration tests. The pin neither freezes the distribution's WebKitGTK security updates nor establishes that the plugin has been security-audited or endorsed by Flutter. It is MIT-licensed; retain its attribution in Flutter's bundled notices.

webview_win_floating is deliberately pinned to 2.3.2, its last release that registers on Windows alone: 3.x registers on Linux too, where it would replace webview_all_linux. Its fullscreen_window dependency still adds that small native plugin to the Linux build. It and video_player_win, pinned to 3.3.1, are BSD-3-Clause and one author's work, not endorsed by Flutter. Upgrading either requires reviewing its native code and retesting on Windows. Their DLLs ship in the Windows package, which the release signs. Retain their attribution in Flutter's bundled notices.

The official webview_flutter currently lists Android, iOS and macOS implementations, with no endorsed Linux implementation. webview_flutter_linux is an experimental, non-endorsed WPE WebKit implementation requiring WPE WebKit 2.52+, so it is not a drop-in endorsed replacement for this GTK integration.

GTK views are detached while registered Flutter transient overlays are open, including pane menus, the agent picker and resize help. All native viewers are hidden for that interval because a popup may cross pane boundaries; their controllers retain the loaded pages. Dismissal restores them without navigation or reload.

Packaged as a single-file AppImage, not a tarball. The script stages an AppDir (usr/bin/ = the Flutter bundle/ verbatim, plus a hand-written harness.desktop and the harness.png icon CMake already installs at the bundle root) and hands it to appimagetool with --appimage-extract-and-run, so packaging needs no FUSE on the build host. AppRun is a plain symlink to usr/bin/harness — the Flutter runner locates its own lib//data/ next to /proc/self/exe, which resolves to the real binary after exec regardless of the symlink used to launch it.

No Info.plist-style version stamp. flutter build linux has nowhere to stamp a version the way Xcode does into Info.plist, so the release script writes a plain version.txt into the built bundle (build/linux/<arm64|x64>/release/bundle/version.txt, which ends up at usr/bin/version.txt inside the AppDir) and asserts it before packaging. lib/core/app_version.dart (what Settings ▸ About shows) reads this file back on Linux, falling through to PackageInfo.fromPlatform() (which would otherwise just return pubspec.yaml's never-bumped placeholder) everywhere else — this still works unchanged for a running AppImage, since the AppImage runtime mounts the whole AppDir at a temporary path and the app resolves version.txt relative to its own (mounted) executable exactly as it did inside the old tarball. lib/update/desktop_updater.dart's downloadAndStage() does not re-verify this against the manifest for Linux — sha256 already authenticates the entire single-file download, so there's nothing left inside it to disagree with the hash.

GCS layout

gs://s3-autonomous-upgrade-3/harness/desktop/metadata.json          (shared with macOS, different key)
gs://s3-autonomous-upgrade-3/harness/desktop/<version>/Harness-linux-x64.AppImage
gs://s3-autonomous-upgrade-3/harness/desktop/<version>/Harness-linux-arm64.AppImage
{
  "desktop-linux-x64": {
    "version": "1.2.4",
    "url": "https://cdn.autonomous.ai/harness/desktop/1.2.4/Harness-linux-x64.AppImage",
    "sha256": "<64 hex>",
    "size": 41230011
  }
}

How a running Linux app self-updates

Same shape as macOS (see above), with the platform-specific pieces:

  1. DesktopUpdater reads the desktop-linux-arm64 or desktop-linux-x64 manifest entry for its runtime architecture instead of desktop-macos.
  2. The download IS the artifact — a single .AppImage file, made executable after its sha256 verifies, with nothing to unpack.
  3. On restart, the detached helper resolves the running AppImage's own path from the APPIMAGE environment variable (set by the AppImage runtime on launch — the process itself runs from a temporary FUSE mount, not from that path), mvs it to a .prev backup, mvs the staged file into its place, then execs that same path directly (there's no open -n/LaunchServices equivalent for a plain packaged Linux binary) and checks it's still alive with pgrep -f, same as macOS.

Rolling out safely / rollback

Same conventions as macOS — publish to a scratch METADATA_PATH first, and roll back only by publishing a newer version containing the older code (see above).

Windows

Every release ships Windows with macOS and Linux: release-desktop.yml's build-windows builds each architecture on its own runner and upload-windows publishes from ubuntu. Three files go to harness/desktop/<version>/:

  • Harness-windows-x64.zip and Harness-windows-arm64.zip (desktop-windows-x64, desktop-windows-arm64), the install-shaped zips below, which the Windows updater and install.ps1 -App take;
  • harness-install.exe (desktop-windows-installer), what the website's Download for Windows serves. It carries no app: it reads the manifest when it runs, picks this PC's zip as install.ps1 -App does, checks it and runs its Harness.exe --install (installer/, docs/superpowers/specs/2026-10-19-windows-installer-design.md).

sign-windows Authenticode-signs every .exe and .dll in both zips and harness-install.exe through Azure Artifact Signing, then writes and signs app/<version>/harness-desktop.cat, a catalog of every file in the version folder that the updater checks ("How a running app self-updates", step 4), as AUTONOMOUS INC., once the repository variable WINDOWS_SIGNING is required (docs/windows-code-signing.md). Until then it is skipped and the files ship unsigned: Windows shows SmartScreen once, on the installer a browser downloaded, and Smart App Control blocks the build where it is on. Once signing is required, a failed signature stops the release and a candidate prepared unsigned is not reused. A failed Windows build stops the release, as a failed macOS or Linux build does.

If Microsoft Defender flags harness-install.exe or the app, submit the file as a software developer at https://www.microsoft.com/wdsi/filesubmission with the release version. Do not change the build to dodge a detection.

Staging

scripts/package-windows.ps1 packages the complete Flutter Release bundle in the per-user install shape: Harness.exe (the harness-desktop-launcher binary), Harness.ico, current, and app\<version>\ with harness-desktop.exe, harness_pipe_io.dll, the other runtime DLLs and data\. The app's first-frame .started marker is excluded. Harness.exe --install installs from this zip, and the Windows updater consumes the same layout. The version comes from the app EXE's ProductVersion resource, stamped by flutter build windows --build-name <version>; Windows does not use a version.txt file.

The Windows desktop workflow has a release mode that builds both x64 and arm64 staging zips, and a staging harness-install.exe (desktop-windows-installer) in the x64 job, on their own runners. It passes --dart-define=HARNESS_STAGING=true, so the installed app reads the staging desktop manifest and installs the staging CLI. dry_run defaults to true. Its artifact contains proposed Windows manifest entries, computed without reading or writing the bucket; it does not describe the live manifest's unrelated keys. A live staging publication requires the owner's explicit approval, then merges the two keys into the observed staging manifest generation:

# Only after approval for this staging publish:
gh workflow run windows-desktop.yml -f release=true -f version=<version> -f dry_run=false
gs://s3-autonomous-upgrade-3/harness/staging/desktop/metadata.json
gs://s3-autonomous-upgrade-3/harness/staging/desktop/<version>/harness-desktop-<version>-windows-x64.zip
gs://s3-autonomous-upgrade-3/harness/staging/desktop/<version>/harness-desktop-<version>-windows-arm64.zip
gs://s3-autonomous-upgrade-3/harness/staging/desktop/<version>/harness-install.exe

The publisher validates both complete zips (check-windows-zip.py) and the installer before upload, creates each versioned object only when absent, reads the uploaded bytes back, and conditionally writes the manifest so another publisher's change cannot be lost. If a publish stops after uploading an object, that version is spent: inspect staging and use a new version. Signing is separate.

Install by one command. After an approved staging publish, bash cli/scripts/upload-install-ps1.sh --app publishes harness/staging/desktop/install.ps1, a copy of B's installer with its app-default line on. A person runs irm https://cdn.autonomous.ai/harness/staging/desktop/install.ps1 | iex. It chooses this PC's zip from the staging desktop manifest, verifies its size and SHA-256, and runs the zip's Harness.exe --install. PowerShell's download does not add the browser's mark of the web, so SmartScreen does not show its first-run prompt. Smart App Control can still block an unsigned build. --app --production is the owner's later publication step, after production has the Windows manifest keys.

First production release

The first release with Windows follows the merge of the Windows PR, and each step needs the owner's go. The CLI side comes first: the app installs the CLI through the production install.ps1, which 404s until step 5. Until then, do not cut a desktop release, because every desktop release now publishes the Windows zips and harness-install.exe.

  1. the CLI release. macOS and Linux go to production; its Windows terminal host and CLI go to staging only;
  2. the staging E2E on Windows (docs/testing/windows-cli-e2e.md) with that release;
  3. the Windows Node runtime manifest, through the Node workflow with the production metadata_path;
  4. cli/scripts/promote-pty-payload.sh <that release>, which uploads nothing and checks each payload file's SHA-256 and size;
  5. bash cli/scripts/upload-install-ps1.sh --production. It refuses until production has this CLI's Windows terminal host and a Windows Node runtime;
  6. make release-desktop, the first with the Windows keys;
  7. bash cli/scripts/upload-install-ps1.sh --app --production, which refuses until production has both Windows zips;
  8. the website release. Its Windows download answers 503 until the production manifest has desktop-windows-installer, so it goes last.