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.

feat: add release script and Makefile target for automated CLI versioning and tagging

0xken150925271c1955
diff --git a/Makefile b/Makefile
index 9c05275cf..d73be70f2 100644
--- a/Makefile
+++ b/Makefile
@@ -4,12 +4,18 @@
# make install-cli ARGS="--no-restart"
# make upload-cli ARGS="0.1.0"
-.PHONY: cli-test install-cli upload-cli remote-machine
+.PHONY: cli-test install-cli upload-cli release remote-machine
## cli-test: typecheck + run the CLI test suite.
cli-test:
cd cli && npx tsc --noEmit && npx vitest run
+## release: tag this commit and push the tag — CI bundles the CLI, publishes it to GCS, and cuts the
+## GitHub Release. The version is bumped from max(last git tag, live metadata.json's `cli` key).
+## ARGS="--dry-run" to preview.
+release:
+ bash cli/scripts/release-cli.sh $(ARGS)
+
## install-cli: bundle the CLI from THIS working tree and install it into ~/.harness/cli — the local dev
## loop, nothing published. Restarts the daemon on the new bytes. Self-update stays ON: the build is
## labelled with the published version, which the release you are level with cannot outrank, so your bytes
diff --git a/cli/RELEASE.md b/cli/RELEASE.md
new file mode 100644
index 000000000..3a3f74bd8
--- /dev/null
+++ b/cli/RELEASE.md
@@ -0,0 +1,122 @@
+# Releasing the CLI
+
+Running daemons self-update from a public GCS bucket (`src/lib/selfUpdate.ts`). Releasing is pushing a
+tag: `.github/workflows/release.yml` bundles the CLI, publishes it to that bucket, and cuts the GitHub
+Release. **The tag IS the version — CI never bumps.**
+
+```bash
+make release # bump the patch, tag, push — CI does the rest
+make release ARGS="--dry-run" # print the version it would cut and the notes, do nothing
+make release ARGS="0.2.0" # release an explicit version
+make release ARGS="--notes-file notes.md" # hand-written release notes
+```
+
+Nothing is built locally and no GCS credentials are needed: the only things `cli/scripts/release-cli.sh`
+touches are git and a public HTTPS read of the manifest. See [`../docs/cicd.md`](../docs/cicd.md) for
+what the release workflow itself does, step by step.
+
+**Why the version comes from two places.** `cli/scripts/release-cli.sh` takes the highest of the last
+git tag and the version published under the `cli` key of `harness/cli/metadata.json`. Publishing by
+hand (`make upload-cli`, below) bumps from the manifest and tags nothing, so the two can drift — a
+maintainer who runs it, or a scratch publish that slipped, leaves the manifest ahead of the last tag.
+Bumping from tags alone there would produce a version LOWER than what's already served — every daemon
+refuses it (`shouldUpdate` / `semverGt` in `src/lib/selfUpdate.ts`) while the release still reports
+success.
+
+Unlike `autonomous-harness-desktop`'s `make release`, there is no `--minor` flag: `shouldUpdate` is a
+plain "strictly newer" check with no major/minor-triggers-a-forced-update concept, so every release
+just needs to outrank what's live.
+
+`package.json`'s `version` field is never touched by this script; the published version is baked into
+the bundle via `ADAPTER_VERSION` at build time (see `make upload-cli` below).
+
+## Publishing by hand
+
+`cli/scripts/upload-cli.sh` is the publishing step. CI invokes it with the version taken from the tag;
+it's also reachable directly when CI cannot be:
+
+```bash
+make upload-cli # auto-bump (0.1.2 -> 0.1.3; 0.1.99 -> 0.2.1)
+make upload-cli ARGS="0.2.0" # explicit version
+make upload-cli ARGS="--no-bump" # rebuild and re-upload the current version
+make upload-cli ARGS="--no-build" # upload the existing dist/ artifact as-is
+```
+
+**This creates no git tag.** It bumps from the remote manifest, so the repo stops reflecting what's
+published. Prefer `make release`; if you do publish by hand, cut a `make release` afterwards to bring
+the tag back in line.
+
+1. Reads the current version from the live manifest (falling back to `package.json` if the manifest is
+ unreadable), then bumps or takes the version it was given.
+2. Bundles with `ADAPTER_VERSION="$VERSION" npm run bundle` and asserts `node dist/cli.js version`
+ reads back that exact string before uploading anything.
+3. Uploads `cli.js` and `notify.mjs` to `harness/cli/<version>/`, then download-merge-reuploads
+ `metadata.json` in a single write, touching only the `cli` key.
+
+A failed build stops the release; nothing is uploaded and no version is consumed.
+
+## Local install (no upload)
+
+`bash cli/scripts/install-cli.sh` bundles **this working tree** into `~/.harness/cli` — the same
+layout the public installer produces — and restarts the daemon on it, so `harness` on this machine
+means your code without publishing anything:
+
+```bash
+make install-cli # bundle + install + restart the daemon
+make install-cli ARGS="--no-restart" # skip restarting the daemon
+make install-cli ARGS="--no-updates" # pin self-update off (see below)
+```
+
+Self-update stays **on** by default: the local build is labelled with the currently published version,
+which the release you're level with cannot outrank, so your bytes survive until a genuinely newer
+version ships — then the daemon quietly swaps back to it. `--no-updates` pins your build instead.
+
+## GCS layout and manifest shape
+
+```
+gs://s3-autonomous-upgrade-3/harness/cli/metadata.json
+gs://s3-autonomous-upgrade-3/harness/cli/<version>/cli.js
+gs://s3-autonomous-upgrade-3/harness/cli/<version>/notify.mjs
+```
+
+```json
+{
+ "cli": {
+ "version": "0.1.72",
+ "url": "https://storage.googleapis.com/s3-autonomous-upgrade-3/harness/cli/0.1.72/cli.js",
+ "sha256": "<64 hex>",
+ "size": 2103552
+ }
+}
+```
+
+The bucket must be public-read — that is bucket policy, not something the scripts set.
+
+## How a running daemon self-updates
+
+1. Polls `ADAPTER_UPDATE_URL` every `ADAPTER_UPDATE_CHECK_MS` (default 60 s) — see `src/config/env.ts`.
+2. Compares the manifest's `cli.version` against its own — strictly newer only (`semverGt`), so
+ republishing an old build can never downgrade a fleet.
+3. Downloads `cli.js` + `notify.mjs` and verifies each sha256/size against the manifest **before**
+ anything is swapped in. A mismatch is discarded.
+4. Swaps the bundle in when the daemon is idle and restarts, with rollback on a bad build.
+
+**There is no undo.** A bad release is rolled back by publishing a *higher* version containing the
+older code — never by deleting the new one, which just leaves every daemon pointed at a 404. Disable
+self-update on one machine with `ADAPTER_UPDATE_DISABLE=true`.
+
+## Rolling out safely
+
+Publish to a scratch manifest before touching the real one, then point a local build at it:
+
+```bash
+gh workflow run release.yml -f version=9.9.9 -f metadata_path=harness/cli/metadata-test.json
+```
+
+```bash
+ADAPTER_UPDATE_URL=https://storage.googleapis.com/s3-autonomous-upgrade-3/harness/cli/metadata-test.json harness start
+```
+
+No daemon polls `metadata-test.json`, so nothing self-updates from it. The *artifacts* still go to
+their real home (`harness/cli/<version>/` is hardcoded in `upload-cli.sh`), so use an unmistakable
+version and delete `gs://s3-autonomous-upgrade-3/harness/cli/9.9.9/` afterwards.
diff --git a/cli/scripts/release-cli.sh b/cli/scripts/release-cli.sh
new file mode 100755
index 000000000..f71651cf4
--- /dev/null
+++ b/cli/scripts/release-cli.sh
@@ -0,0 +1,224 @@
+#!/usr/bin/env bash
+# Cut a CLI release: work out the next version, tag it, push the tag. CI does everything else —
+# .github/workflows/release.yml bundles the CLI, publishes it to GCS, and creates the GitHub Release.
+# The tag IS the version; CI never bumps on its own.
+#
+# Usage:
+# bash cli/scripts/release-cli.sh # bump the patch and release
+# bash cli/scripts/release-cli.sh --dry-run # print everything, tag nothing, push nothing
+# bash cli/scripts/release-cli.sh 0.2.0 # release an explicit version
+# bash cli/scripts/release-cli.sh --notes-file f.md # hand-written release notes instead of the
+# # generated commit list
+#
+# THE NEXT VERSION COMES FROM TWO SOURCES, AND BOTH MATTER — same reasoning as
+# autonomous-harness-desktop/scripts/release-desktop.sh. Git tags alone are not enough:
+# `cli/scripts/upload-cli.sh` bumps from the live metadata.json and tags nothing, so a maintainer who
+# publishes by hand (or a scratch/dry-run publish that slipped) can leave the manifest ahead of the
+# last tag. Bumping from tags alone there would produce a version LOWER than what's already served,
+# which every daemon refuses (`semverGt` in cli/src/lib/selfUpdate.ts) while the release still looks
+# successful. So the current version is max(highest git tag, the manifest's `cli` key version).
+#
+# Unlike the desktop, there is no --minor flag here: `shouldUpdate` in selfUpdate.ts is a plain
+# semverGt with no major/minor-triggers-a-forced-update concept, so a "MANDATORY UPDATE" framing would
+# invent semantics this CLI doesn't have. Every release just needs to be strictly newer.
+#
+# Requires: git, curl, python3, and push access to origin. No GCS credentials — the manifest is read
+# over public HTTPS, exactly as cli/scripts/upload-cli.sh reads it.
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+cd "$ROOT"
+
+# --- config (all overridable via env) ---
+GCS_BUCKET="${GCS_BUCKET:-s3-autonomous-upgrade-3}"
+GCS_PUBLIC_BASE_URL="${GCS_PUBLIC_BASE_URL:-https://storage.googleapis.com/${GCS_BUCKET}}"
+METADATA_PATH="${METADATA_PATH:-harness/cli/metadata.json}"
+OTA_KEY="${OTA_KEY:-cli}" # must match ADAPTER_UPDATE_KEY in cli/src/config/env.ts
+META_URL="${META_URL:-${GCS_PUBLIC_BASE_URL%/}/${METADATA_PATH#/}}"
+BRANCH="${BRANCH:-main}"
+
+DRY_RUN=0
+ALLOW_NO_MANIFEST=0
+NEW_VER=""
+NOTES_FILE=""
+
+want_notes_file=0
+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 ;;
+ --allow-no-manifest) ALLOW_NO_MANIFEST=1 ;;
+ --notes-file) want_notes_file=1 ;;
+ --notes-file=*) NOTES_FILE="${arg#*=}" ;;
+ -h|--help) sed -n '2,23p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'; exit 0 ;;
+ -*) echo "ERROR unknown flag: $arg" >&2; exit 1 ;;
+ *) NEW_VER="$arg" ;;
+ esac
+done
+[ "$want_notes_file" -eq 0 ] || { echo "ERROR --notes-file needs a path" >&2; exit 1; }
+
+# Same rule as next_adapter_version() in cli/scripts/upload-cli.sh:28-42, which is where this
+# convention is defined. Note the rollover: .99 goes to the next MINOR at .1, not .0.
+next_patch_version() {
+ local current="$1" major minor patch
+ if [[ ! "$current" =~ ^([0-9]+)\.([0-9]+)\.([0-9]+)$ ]]; then
+ echo "ERROR version '$current' must look like X.Y.Z" >&2
+ return 1
+ fi
+ major=$((10#${BASH_REMATCH[1]}))
+ minor=$((10#${BASH_REMATCH[2]}))
+ patch=$((10#${BASH_REMATCH[3]}))
+ if (( patch >= 99 )); then
+ printf '%d.%d.1\n' "$major" "$((minor + 1))"
+ else
+ printf '%d.%d.%d\n' "$major" "$minor" "$((patch + 1))"
+ fi
+}
+
+# Strictly greater, comparing X.Y.Z numerically — the same test the daemon applies before it will
+# install anything (semverGt, cli/src/lib/selfUpdate.ts).
+version_gt() {
+ [ "$1" != "$2" ] && [ "$(printf '%s\n%s\n' "$1" "$2" | sort -V | tail -1)" = "$1" ]
+}
+
+# --- preflight: tooling ---
+for tool in git curl python3; do
+ command -v "$tool" >/dev/null 2>&1 || { echo "ERROR $tool not found — it is needed to cut a release" >&2; exit 1; }
+done
+
+# --- preflight: the tag must capture exactly what was tested, and CI must be able to fetch it ---
+git rev-parse --git-dir >/dev/null 2>&1 || { echo "ERROR not a git repository: $ROOT" >&2; exit 1; }
+git fetch --tags --quiet origin
+
+if [ -n "$(git status --porcelain)" ]; then
+ echo "ERROR working tree is dirty — a release tag must capture the tested source exactly:" >&2
+ git status --short | sed 's/^/ /' >&2
+ exit 1
+fi
+
+HEAD_SHA="$(git rev-parse HEAD)"
+if ! git merge-base --is-ancestor "$HEAD_SHA" "origin/$BRANCH" 2>/dev/null; then
+ echo "ERROR HEAD is not on origin/$BRANCH — push the commit first, or CI will build a commit nobody else has." >&2
+ exit 1
+fi
+
+# --- current version, source 1: the highest release tag in git ---
+# The brace group keeps `set -e` from killing the script when grep legitimately matches nothing.
+TAG_VER="$(git tag -l 'v*' \
+ | { grep -E '^v(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)$' || true; } \
+ | sed -E 's/^v//' \
+ | sort -V | tail -1)"
+LAST_TAG=""
+[ -z "$TAG_VER" ] || LAST_TAG="v${TAG_VER}"
+TAG_VER="${TAG_VER:-0.0.0}"
+
+# --- current version, source 2: the version actually being served ---
+GCS_VER="$(curl -fsSL "$META_URL" 2>/dev/null | python3 -c '
+import json, re, sys
+try:
+ data = json.load(sys.stdin)
+except Exception:
+ sys.exit(0)
+if not isinstance(data, dict):
+ sys.exit(0)
+entry = data.get(sys.argv[1])
+if not isinstance(entry, dict):
+ sys.exit(0)
+version = entry.get("version")
+if not isinstance(version, str) or not re.match(r"^\d+\.\d+\.\d+$", version.strip()):
+ sys.exit(0)
+print(version.strip())
+' "$OTA_KEY" 2>/dev/null || true)"
+
+if [ -z "$GCS_VER" ]; then
+ if [ "$ALLOW_NO_MANIFEST" -eq 1 ]; then
+ echo ">> WARNING could not read $META_URL — continuing on git tags alone (--allow-no-manifest)" >&2
+ GCS_VER="0.0.0"
+ else
+ echo "ERROR could not read the live manifest at $META_URL" >&2
+ echo " It is the only record of what daemons are actually running, and releasing without it" >&2
+ echo " risks publishing a version LOWER than the one already being served." >&2
+ echo " Re-run with --allow-no-manifest only if the bucket is genuinely down." >&2
+ exit 1
+ fi
+fi
+
+# --- the next version ---
+CUR="$TAG_VER"
+version_gt "$GCS_VER" "$CUR" && CUR="$GCS_VER"
+
+if [ -n "$NEW_VER" ]; then
+ VER="$NEW_VER"
+else
+ VER="$(next_patch_version "$CUR")"
+fi
+
+if [[ ! "$VER" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+ echo "ERROR version '$VER' must look like X.Y.Z — release.yml rejects anything else" >&2
+ exit 1
+fi
+
+TAG="v${VER}"
+
+# The last gate against a release no daemon can install.
+if ! version_gt "$VER" "$GCS_VER"; then
+ echo "ERROR $VER is not higher than $GCS_VER, which is already published." >&2
+ echo " Every running daemon would refuse it and the release would still look successful." >&2
+ exit 1
+fi
+
+if git rev-parse -q --verify "refs/tags/$TAG" >/dev/null; then
+ echo "ERROR tag $TAG already exists. Re-tagging a released version breaks the tag<->build mapping." >&2
+ exit 1
+fi
+
+# --- release notes: the tag message IS the GitHub Release body ---
+# release.yml's github-release job hard-fails on a lightweight tag or an empty message — and it runs
+# AFTER the manifest is already live, so a missing message means a half-done release: daemons are
+# already running a build that has no Release page. Refuse to tag without notes rather than find out
+# then.
+NOTES="$(mktemp)"
+trap 'rm -f "${NOTES:-}"' EXIT
+if [ -n "$NOTES_FILE" ]; then
+ [ -f "$NOTES_FILE" ] || { echo "ERROR notes file not found: $NOTES_FILE" >&2; exit 1; }
+ cat "$NOTES_FILE" > "$NOTES"
+else
+ {
+ printf 'Harness CLI %s\n\n' "$VER"
+ if [ -n "$LAST_TAG" ]; then
+ git log --no-merges --pretty='- %s' "${LAST_TAG}..HEAD"
+ else
+ git log --no-merges --pretty='- %s' -20
+ fi
+ } > "$NOTES"
+fi
+[ -s "$NOTES" ] || { echo "ERROR release notes are empty — CI would fail after publishing" >&2; exit 1; }
+
+# --- summary (shared by dry runs and real ones) ---
+echo ""
+echo " last git tag ${LAST_TAG:-(none)} ($TAG_VER)"
+echo " live on GCS $GCS_VER ($OTA_KEY key)"
+if version_gt "$GCS_VER" "$TAG_VER"; then
+ echo " NOTE the manifest is ahead of git — versions were published without a tag."
+ echo " Bumping from tags alone here would publish a downgrade."
+fi
+echo " releasing $VER (tag $TAG on ${HEAD_SHA:0:12})"
+echo ""
+echo " release notes:"
+sed 's/^/ /' "$NOTES"
+echo ""
+
+if [ "$DRY_RUN" -eq 1 ]; then
+ echo " dry run — nothing tagged, nothing pushed."
+ exit 0
+fi
+
+# --- tag and push ---
+git tag -a "$TAG" --cleanup=verbatim -F "$NOTES"
+git push origin "$TAG"
+
+echo ""
+echo " pushed $TAG → CI bundles the CLI, publishes to GCS, and cuts the GitHub Release."
+echo " running daemons self-update within ~1 min of the manifest moving."
+echo " watch : gh run watch \$(gh run list --workflow=release.yml --limit 1 --json databaseId --jq '.[0].databaseId')"
+echo ""
diff --git a/docs/cicd.md b/docs/cicd.md
index 8f54b06ad..0265f28c5 100644
--- a/docs/cicd.md
+++ b/docs/cicd.md
@@ -29,6 +29,19 @@ because the artifacts are two JavaScript files whose integrity is the sha256 in
## Cutting a release
+```bash
+make release # bump the patch, tag, push — CI does the rest
+make release ARGS="--dry-run" # print the version it would cut and the notes, do nothing
+make release ARGS="0.2.0" # release an explicit version
+```
+
+`cli/scripts/release-cli.sh` works out the next version as `max(last git tag, live metadata.json's cli
+key)`, refuses to publish anything that isn't strictly newer than what's live, and refuses an empty
+release message before tagging. See [`cli/RELEASE.md`](../cli/RELEASE.md) for the full rundown,
+including local installs and manual publishing.
+
+The manual fallback, for when `make release` itself can't be used:
+
```bash
# What is live right now — the next tag is one above this. Someone may have released by hand.
curl -fsS https://storage.googleapis.com/s3-autonomous-upgrade-3/harness/cli/metadata.json
@@ -114,10 +127,3 @@ whose `node_modules` came from pnpm. `ci.yml` now runs `pnpm install --frozen-lo
--lockfile-only` before anything else, which resolves in about five seconds, installs nothing and
fails naming the dependency that drifted. So: if you touch `package.json`, update **both**
lockfiles.
-
-## Known gap
-
-`cli/README.md` links to `cli/RELEASE.md` twice (publishing, and the local-install path). That file
-does not exist in this repository — it did not survive the split out of the monorepo. Both links are
-dead, and the material is currently spread across the headers of `cli/scripts/upload-cli.sh` and
-`cli/scripts/install-cli.sh`, plus this file.