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.

ci: add CI and release workflows for the harness CLI

Dev jacob421e3ddd7d88
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 000000000..d191d13b6
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,116 @@
+name: CI
+
+# Modelled on autonomous-harness-desktop's ci.yml, with ONE deliberate difference: that one has no
+# `pull_request` trigger and this one does.
+#
+# The desktop repo is private, and everything that reaches its main branch was pushed by a
+# maintainer who could run the suite locally; a per-commit run there is the same verdict paid for
+# twice. THIS repo is public, takes fork PRs (CONTRIBUTING.md walks through it), and until this file
+# existed said so out loud: "there is no CI on pull requests yet. Nothing runs automatically when
+# you push, so what you report is what a reviewer starts from." A contributor's own report is not a
+# verdict — it is a claim about a machine nobody else can see — and a maintainer pulling every
+# branch to find out is the manual step CI exists to delete.
+#
+# `pull_request`, never `pull_request_target`: a fork's PR runs with a read-only token and no access
+# to secrets, and this job wants neither. It checks out and runs the contributor's code, which is
+# exactly why it must not be handed a writable token.
+#
+# There is still no `push` trigger. Nobody pushes to main directly (CONTRIBUTING.md step 2) and
+# merges are squashed, so a push run would re-test the commit the PR run just cleared.
+on:
+ pull_request:
+ branches: [main]
+ # Deliberately unfiltered by `paths`. A docs-only PR running the CLI suite is 90 seconds of noise;
+ # a `paths` filter that makes the check never REPORT is a PR nobody can merge the day somebody
+ # turns on branch protection. The cheap failure is the better one, and public repos do not pay for
+ # standard runners.
+ #
+ # It is also the escape hatch for a verdict on any branch without opening a PR:
+ # Actions -> CI -> Run workflow.
+ workflow_dispatch:
+ # release.yml calls this. It also hands the release the Node this suite actually ran on (see
+ # below), so a published bundle can never be built on a runtime the tests did not use.
+ workflow_call:
+ outputs:
+ node-version:
+ description: The Node the suite ran on. release.yml bundles the release with it.
+ value: ${{ jobs.typecheck-test.outputs.node-version }}
+
+permissions:
+ contents: read
+
+concurrency:
+ group: cli-ci-${{ github.workflow }}-${{ github.ref }}
+ # A second push to an open PR makes the first run's verdict worthless, so that one is cancelled.
+ # Everything else — a release's gate, a run somebody started by hand — is the record of whether a
+ # commit was green, and is never killed to make room.
+ cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+ # `make cli-test`, exactly: typecheck then the vitest suite. Nothing else — the repo has no lint
+ # or format gate, and inventing one here would fail on code no reviewer ever agreed to.
+ typecheck-test:
+ runs-on: ubuntu-latest
+ timeout-minutes: 20
+ outputs:
+ node-version: ${{ steps.pin.outputs.node-version }}
+ defaults:
+ run:
+ working-directory: cli
+ steps:
+ - uses: actions/checkout@v7
+
+ # THE runtime pin for the whole repo — CI and the release bundle read this one line.
+ #
+ # It is not a taste in Node versions: it is the version of the MANAGED runtime the shipped CLI
+ # actually executes on. `harness/runtime/metadata.json` in the release bucket serves
+ # node v22.23.2 for darwin-arm64, darwin-x64, linux-x64 and linux-arm64, `install.sh` unpacks
+ # it under ~/.harness/runtime, and the launcher names that binary absolutely — so the user's
+ # own node, if any, never runs this bundle. Testing on anything else measures a runtime no
+ # machine in the field has. Bump this together with `make upload-node-runtime` in
+ # autonomous-harness-desktop, never on its own.
+ #
+ # (package.json's `engines` says >=20, which is the floor a THIRD PARTY may run it on. A floor
+ # is not a pin: a floating 22.x turns an unrelated upstream release into a red build on an
+ # untouched commit.)
+ - id: pin
+ run: echo "node-version=22.23.2" >> "$GITHUB_OUTPUT"
+
+ - uses: actions/setup-node@v7
+ with:
+ node-version: ${{ steps.pin.outputs.node-version }}
+ cache: npm
+ # Relative to the repo root, not to `defaults.working-directory` — this is an action
+ # input, not a `run:`.
+ cache-dependency-path: cli/package-lock.json
+
+ # TWO lockfiles are tracked here, and only one of them has ever been guarded.
+ #
+ # `package-lock.json` is the one the released bytes are built from — every build path in this
+ # repo shells out to `npm run bundle` (install-cli.sh, upload-cli.sh, remote-machine.sh) — and
+ # `npm ci` below refuses to run when it disagrees with package.json, so npm's half checks
+ # itself.
+ #
+ # `pnpm-lock.yaml` is checked by nothing, and on 2026-09-09 that cost a maintainer an
+ # afternoon: `bonjour-service` was added to package.json with only package-lock.json updated,
+ # main went green, and `make install-cli` then died at `Could not resolve "bonjour-service"`
+ # on every machine whose node_modules came from pnpm. Deleting the file would also fix that;
+ # keeping it and checking it is the choice made here, because contributors do use it.
+ #
+ # `--lockfile-only` resolves without installing (~5s) and writes nothing under --frozen-lockfile.
+ # Verified against this repo: it exits 1 on the stale lockfile that shipped in c4de318, naming
+ # the added dependency, and 0 once it is regenerated.
+ - name: Check pnpm-lock.yaml still matches package.json
+ run: |
+ npm i -g pnpm@11 >/dev/null
+ pnpm install --frozen-lockfile --lockfile-only
+
+ # `npm ci`, not `npm install`: the lockfile is the input, not a suggestion.
+ - run: npm ci
+
+ - run: npx tsc --noEmit
+
+ # 1,871 tests over 144 files, ~30s. The four `*.real.spec.ts` / `localE2e.spec.ts` suites that
+ # need a live tmux, Herdr or Cursor are gated behind RUN_* env vars and stay skipped here —
+ # `npm run test:tmux-real` and friends are how those are run, on a machine that has them.
+ - run: npx vitest run
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
new file mode 100644
index 000000000..2fcfe5d67
--- /dev/null
+++ b/.github/workflows/release.yml
@@ -0,0 +1,285 @@
+name: Release
+
+# Cut a release by pushing a tag: git tag -a v0.1.72 -F notes.md && git push origin v0.1.72
+#
+# Publishes the `cli` key of harness/cli/metadata.json — the manifest EVERY RUNNING DAEMON POLLS
+# EVERY 60 SECONDS (src/config/env.ts: ADAPTER_UPDATE_URL / ADAPTER_UPDATE_CHECK_MS). That is the
+# one way this workflow is not the desktop's: there is no download page and no user clicking
+# "install". A minute after the manifest moves, every machine on the fleet is running these bytes.
+# Everything below that looks like belt-and-braces is sized against that blast radius.
+#
+# Shape borrowed from autonomous-harness-desktop's release.yml, minus the parts that do not apply:
+#
+# * SAME bucket, SAME `GCP_SA_KEY` service account, SAME preflight, SAME "the tag is the version"
+# rule, SAME annotated-tag release notes, SAME `metadata_path` dry run.
+# * NO scratch-manifest merge. The desktop fans out to three build jobs that each own a manifest
+# key, so it points each at its own scratch file and merges once at the end. The CLI is ONE
+# platform-independent bundle under ONE key, published by ONE job — the race the desktop
+# designs around cannot occur here, so inventing a merge step would be ceremony.
+# * NO signing or notarization. The artifacts are two JavaScript files; integrity is the sha256
+# in the manifest, which selfUpdate.ts verifies in memory before it writes anything to disk.
+#
+# cli/scripts/upload-cli.sh is used EXACTLY as it is, with no flag this file invented: GCS_BUCKET,
+# METADATA_PATH and OTA_KEY are env overrides it already supports. The script is the production
+# release path — `make upload-cli` runs the same bytes from a laptop — and CI adapts to it.
+#
+# The TAG is the version. CI never auto-bumps: left to itself the script reads the current version
+# out of the remote manifest and adds one, so what publishes would depend on when the job ran.
+#
+# Dry run first: Actions -> Release -> Run workflow, with metadata_path = harness/cli/
+# metadata-test.json. No daemon polls that file, so nothing self-updates. Note that the ARTIFACTS
+# still go to their real home, harness/cli/<version>/ — the script hardcodes that path and this
+# file does not edit scripts. Use an unmistakable version (9.9.9) and delete
+# gs://<bucket>/harness/cli/9.9.9/ afterwards.
+#
+# There is no undo. selfUpdate.ts only ever moves forward, so 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.
+
+on:
+ push:
+ tags: ['v*']
+ workflow_dispatch:
+ inputs:
+ version:
+ description: 'Version to publish (X.Y.Z)'
+ required: true
+ metadata_path:
+ description: 'Manifest to write. Leave as-is for a real release; metadata-test.json for a dry run.'
+ required: false
+ default: harness/cli/metadata.json
+
+permissions:
+ contents: read
+ id-token: write # only used by the Workload Identity Federation variant of the auth steps below
+
+concurrency:
+ # Two releases overlapping would interleave their manifest writes, and the loser's version would
+ # be the one the fleet installs. Never cancelled in progress: a run killed between "artifacts
+ # uploaded" and "manifest written" leaves bytes nobody references, which is harmless — one killed
+ # a second later leaves the manifest pointing at a build whose job never finished.
+ group: cli-release
+ cancel-in-progress: false
+
+env:
+ GCS_BUCKET: s3-autonomous-upgrade-3 # upload-cli.sh reads this too — one place, not three
+
+jobs:
+ # Resolve and validate before anything else starts. A malformed tag fails here in seconds.
+ version:
+ runs-on: ubuntu-latest
+ outputs:
+ version: ${{ steps.resolve.outputs.version }}
+ metadata_path: ${{ steps.resolve.outputs.metadata_path }}
+ steps:
+ - id: resolve
+ # Through env, never `${{ }}` inline in run:. Git permits quotes, backticks and $() in a ref
+ # name, so interpolating one into the shell would let a tag name execute as code.
+ env:
+ REF_NAME: ${{ github.ref_name }}
+ INPUT_VERSION: ${{ inputs.version }}
+ INPUT_METADATA_PATH: ${{ inputs.metadata_path }}
+ run: |
+ set -euo pipefail
+ ver="${INPUT_VERSION:-${REF_NAME#v}}"
+ if [[ ! "$ver" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]; then
+ echo "::error::version '$ver' must look like X.Y.Z — tag as vX.Y.Z"
+ exit 1
+ fi
+ meta="${INPUT_METADATA_PATH:-harness/cli/metadata.json}"
+ echo "version=$ver" >> "$GITHUB_OUTPUT"
+ echo "metadata_path=$meta" >> "$GITHUB_OUTPUT"
+ echo "Publishing **$ver** to \`$meta\`" >> "$GITHUB_STEP_SUMMARY"
+
+ # Proving the credential now means a broken one costs seconds instead of a whole test run. Runs
+ # beside `version` and `tests`, so it is free in wall clock.
+ preflight:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: google-github-actions/auth@v2
+ with:
+ credentials_json: ${{ secrets.GCP_SA_KEY }}
+ - uses: google-github-actions/setup-gcloud@v2
+ - name: Verify GCS write access
+ run: |
+ set -euo pipefail
+ probe="gs://${GCS_BUCKET}/harness/cli/.ci-preflight/${GITHUB_RUN_ID}"
+ echo "$GITHUB_RUN_ID" | gsutil cp - "$probe"
+ gsutil rm "$probe"
+
+ tests:
+ uses: ./.github/workflows/ci.yml
+ permissions:
+ contents: read
+
+ publish:
+ needs: [version, tests, preflight]
+ runs-on: ubuntu-latest
+ timeout-minutes: 20
+ env:
+ # The script's own env override. For a real release this IS harness/cli/metadata.json; for a
+ # dry run it is the scratch manifest nothing polls.
+ METADATA_PATH: ${{ needs.version.outputs.metadata_path }}
+ VERSION: ${{ needs.version.outputs.version }}
+ steps:
+ - uses: actions/checkout@v7
+
+ - uses: actions/setup-node@v7
+ with:
+ # The Node the suite just ran on, not a second opinion about which Node is current.
+ node-version: ${{ needs.tests.outputs.node-version }}
+ cache: npm
+ cache-dependency-path: cli/package-lock.json
+
+ - run: npm ci
+ working-directory: cli
+
+ - uses: google-github-actions/auth@v2
+ with:
+ credentials_json: ${{ secrets.GCP_SA_KEY }}
+ - uses: google-github-actions/setup-gcloud@v2
+
+ # From the repo root, the way `make upload-cli` calls it. The script bundles with
+ # ADAPTER_VERSION="$VERSION" baked in, refuses to upload if `node dist/cli.js version` does
+ # not read back that exact string, uploads cli.js + notify.mjs to harness/cli/$VERSION/, then
+ # merges the `cli` key into $METADATA_PATH.
+ #
+ # Expect `>> could not read remote metadata` on a dry run: METADATA_PATH points at a file that
+ # does not exist yet, and that line is only the auto-bump's input. The version that publishes
+ # is the one passed here.
+ - name: Bundle and publish the CLI
+ run: bash cli/scripts/upload-cli.sh "$VERSION"
+
+ # Do exactly what a daemon does one minute from now, and fail the release if it does not work.
+ #
+ # upload-cli.sh already checks the bundle before uploading; this checks the PUBLISHED result —
+ # manifest actually served, URLs actually reachable, sha256 actually matching the bytes GCS
+ # hands out, and the downloaded cli.js actually able to print its own version. Those are
+ # different failures (a half-written manifest, a botched Cache-Control, an object that landed
+ # in the wrong bucket) and none of them are visible from the upload side.
+ #
+ # selfUpdate.ts refuses a digest mismatch, so the fleet is safe either way. What it does NOT
+ # do is tell anyone: every daemon simply keeps the version it has and the release looks green.
+ - name: Verify the published release the way a daemon would
+ run: |
+ set -euo pipefail
+ # Built here from $GCS_BUCKET and $METADATA_PATH, both already in this job's environment,
+ # rather than interpolated into the script by Actions — same rule as the tag name above.
+ # (A workflow expression is substituted into `run:` BEFORE any shell sees it, so writing
+ # one is not made safe by putting it in a comment: an empty pair of braces here is a
+ # workflow syntax error, not a comment. actionlint catches that; nothing else does.)
+ curl -fsSL "https://storage.googleapis.com/${GCS_BUCKET}/${METADATA_PATH}" -o manifest.json
+ echo "::group::manifest"; cat manifest.json; echo "::endgroup::"
+
+ # The layout install.sh writes next to the downloaded bundle, and it is load-bearing: the
+ # bundle is ESM, and node decides that from the nearest package.json. Without this file it
+ # would parse a 2MB ES module as CommonJS. (Node 22 would probably rescue it by sniffing
+ # the syntax; a verification step must not depend on probably.)
+ mkdir -p verify && printf '{"type":"module"}\n' > verify/package.json
+
+ # The single quotes are the point: this is JavaScript, and its `${...}` template literals
+ # must reach node unexpanded by the shell.
+ # shellcheck disable=SC2016
+ node -e '
+ const fs = require("node:fs"), crypto = require("node:crypto")
+ const { execFileSync } = require("node:child_process")
+
+ const main = async () => {
+ const want = process.env.VERSION
+ const entry = JSON.parse(fs.readFileSync("manifest.json", "utf8")).cli
+ if (!entry) throw new Error("manifest has no `cli` key")
+ if (entry.version !== want) throw new Error(`manifest says ${entry.version}, expected ${want}`)
+
+ for (const [key, file] of [["cli", "cli.js"], ["notify", "notify.mjs"]]) {
+ const ref = entry[key]
+ if (!ref || !ref.url || !ref.sha256) throw new Error(`${key}: manifest entry has no url/sha256`)
+ const res = await fetch(ref.url, { cache: "no-store" })
+ if (!res.ok) throw new Error(`${key}: GET ${ref.url} -> ${res.status}`)
+ const buf = Buffer.from(await res.arrayBuffer())
+ const got = crypto.createHash("sha256").update(buf).digest("hex")
+ if (got !== String(ref.sha256).toLowerCase()) throw new Error(`${key}: sha256 ${got} != manifest ${ref.sha256}`)
+ if (buf.length !== ref.size) throw new Error(`${key}: ${buf.length} bytes != manifest ${ref.size}`)
+ fs.writeFileSync(`verify/${file}`, buf)
+ console.log(` ${file}: ${buf.length} bytes, sha256 ok`)
+ }
+
+ // The bytes a daemon would install, asked their own version. This is the one check
+ // that proves the manifest and the object describe the SAME build — every check above
+ // would still pass if a correct manifest pointed at a correctly-hashed wrong file.
+ const said = execFileSync(process.execPath, ["verify/cli.js", "version"], { encoding: "utf8" }).trim()
+ if (said !== want) throw new Error(`downloaded cli.js reports ${said}, expected ${want}`)
+ console.log(` verify/cli.js reports ${said}`)
+ }
+
+ main().catch(err => { console.error(`::error::${err.message}`); process.exit(1) })
+ '
+ {
+ echo "Verified \`$VERSION\` at \`$METADATA_PATH\`"
+ echo ""
+ echo "Running daemons self-update within ~1 min."
+ } >> "$GITHUB_STEP_SUMMARY"
+
+ # The GitHub Release. Notes are the tag's OWN message, verbatim — the same rule the desktop repo
+ # 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, differently-built list under it
+ # that silently omits anything which reached main without a PR.
+ #
+ # No binaries attached. GCS is the distribution channel — install.sh and the self-updater both
+ # read the manifest — so a copy here would be a second set of bytes that can disagree with the
+ # one machines actually install. The notes link to the real ones instead.
+ github-release:
+ needs: [version, publish]
+ if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/')
+ runs-on: ubuntu-latest
+ permissions:
+ contents: write # narrower than the workflow default only here, where a release is created
+ steps:
+ - uses: actions/checkout@v7
+ with:
+ fetch-depth: 0
+
+ - name: Take the release notes from the tag
+ env:
+ REF_NAME: ${{ github.ref_name }}
+ VERSION: ${{ needs.version.outputs.version }}
+ run: |
+ set -euo pipefail
+ # actions/checkout replaces the pushed annotated tag with a LIGHTWEIGHT local ref, even at
+ # fetch-depth: 0, so `git cat-file -t` below would see "commit" and reject a properly
+ # annotated tag. Re-fetch the tag object to restore the annotation before reading it.
+ git fetch --force origin tag "$REF_NAME"
+ # A lightweight tag has no message of its own, and %(contents) would quietly fall through
+ # to the commit's — publishing "chore(release): vX.Y.Z" as the notes.
+ if [ "$(git cat-file -t "$REF_NAME")" != tag ]; then
+ echo "::error::$REF_NAME is a lightweight tag, so it carries no release notes."
+ echo "::error::Re-tag with: git tag -a $REF_NAME --cleanup=verbatim -F notes.md"
+ exit 1
+ fi
+ git tag -l --format='%(contents)' "$REF_NAME" > RELEASE_NOTES.md
+ if [ ! -s RELEASE_NOTES.md ]; then
+ echo "::error::$REF_NAME has an empty tag message — no notes to publish."
+ exit 1
+ fi
+ base="https://storage.googleapis.com/${GCS_BUCKET}/harness/cli/${VERSION}"
+ cat >> RELEASE_NOTES.md <<EOF
+
+ ---
+
+ ## Install
+
+ \`\`\`bash
+ curl -fsSL https://harness.autonomous.ai/cli/install.sh | bash
+ \`\`\`
+
+ Already running \`harness\`? The daemon self-updates within a minute — nothing to do.
+
+ | Artifact | |
+ |---|---|
+ | \`cli.js\` | [download](${base}/cli.js) |
+ | \`notify.mjs\` | [download](${base}/notify.mjs) |
+ EOF
+ echo "::group::RELEASE_NOTES.md"; cat RELEASE_NOTES.md; echo "::endgroup::"
+
+ - uses: softprops/action-gh-release@v2
+ with:
+ body_path: RELEASE_NOTES.md
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index bb9c05918..2bf945862 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -44,8 +44,13 @@ not code at all.
you ran them against** — "`npm test` plus `test:tmux-real` on tmux 3.5a, macOS" is worth more than
a green checkbox.
- That last part is not politeness: **there is no CI on pull requests yet.** Nothing runs
- automatically when you push, so what you report is what a reviewer starts from.
+ That last part is not politeness. CI now runs `npm run typecheck` and `npm test` on every pull
+ request (Ubuntu, on the same pinned Node the released bundle is built with), so a green check
+ means those two passed — and **nothing more**. The suites that need real software are gated
+ behind `RUN_*` env vars precisely because a hosted runner has no tmux server, no Herdr and no
+ Cursor, so `test:tmux-real`, `test:herdr-real` and `test:cursor-e2e` are still only ever run by
+ you and by the maintainer reviewing you. For an engine or a multiplexer, that is the half of the
+ verdict that matters, and it starts from what you report.
5. **Review is manual, and hands-on.** A maintainer pulls the branch and runs the suites locally. For
an engine or a multiplexer that also means installing the real software, so tell us exactly what to
install and how you exercised it — a change nobody can reproduce cannot be merged, however good it
diff --git a/docs/cicd.md b/docs/cicd.md
new file mode 100644
index 000000000..8f54b06ad
--- /dev/null
+++ b/docs/cicd.md
@@ -0,0 +1,123 @@
+# CI/CD
+
+Two workflows, both under [`.github/workflows/`](../.github/workflows/).
+
+| File | Runs when | Does |
+|---|---|---|
+| `ci.yml` | every pull request against `main`; on demand | `npm ci` → `npx tsc --noEmit` → `npx vitest run`, i.e. `make cli-test` |
+| `release.yml` | a pushed `v*` tag; on demand | bundles and publishes the CLI, then verifies the published bytes |
+
+They are modelled on the ones in `autonomous-harness-desktop` and share that repo's release
+infrastructure: the same GCS bucket (`s3-autonomous-upgrade-3`), the same `GCP_SA_KEY` service
+account, the same "the tag is the version" rule, the same annotated-tag release notes, and the same
+`metadata_path` dry run. What follows is only what is specific to the CLI.
+
+## Setup
+
+One secret, in **Settings → Secrets and variables → Actions**:
+
+| Secret | Value |
+|---|---|
+| `GCP_SA_KEY` | the JSON key of the service account with object read/write on `s3-autonomous-upgrade-3` |
+
+GitHub does not share secrets between repositories. This is the *same credential* the desktop repo
+uses, but it has to exist here as well — either added to this repo or promoted to an organization
+secret scoped to both. Nothing else is needed: there is no signing identity and no notarization,
+because the artifacts are two JavaScript files whose integrity is the sha256 in the manifest.
+
+`ci.yml` needs no secret at all, which is what makes it safe to run on a fork's pull request.
+
+## Cutting a release
+
+```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
+
+git tag -a vX.Y.Z --cleanup=verbatim -F notes.md
+git push origin vX.Y.Z
+```
+
+**Check the manifest first, and never re-use a version.** Uploading over `harness/cli/<version>/`
+replaces bytes whose sha256 some machine may already have recorded, and a daemon that sees the
+manifest and the object disagree refuses the update and stays where it is — silently.
+
+The tag **is** the version, and the tag *message* is the release notes — a lightweight tag is
+rejected rather than published with the commit subject as its notes. Left to itself
+`cli/scripts/upload-cli.sh` reads the current version out of the remote manifest and adds one, so
+what published would depend on when the job ran; CI passes the version explicitly instead.
+
+Then, in order: `version` validates `X.Y.Z` · `preflight` proves the GCS credential · `tests` runs
+the full suite · `publish` bundles, uploads and verifies · `github-release` creates the release from
+the tag message.
+
+## What "publish" actually means here
+
+`harness/cli/metadata.json` is polled by **every running daemon every 60 seconds**
+(`ADAPTER_UPDATE_URL` / `ADAPTER_UPDATE_CHECK_MS` in `cli/src/config/env.ts`). There is no download
+page and no user clicking install: a minute after the manifest moves, the fleet is running the new
+bytes. That is the difference from the desktop release, and it is what the extra care is sized
+against.
+
+Two consequences worth knowing before you push a tag:
+
+- **There is no undo.** `selfUpdate.ts` only moves forward. A bad release is rolled back by
+ publishing a *higher* version containing the older code — never by deleting the new one, which
+ leaves every daemon pointed at a 404.
+- **A green job is not a green release.** `upload-cli.sh` checks the bundle before uploading;
+ `publish` then does what a daemon does — fetches the manifest, downloads both URLs, checks each
+ sha256 and size against the manifest, and runs `node cli.js version` on the downloaded bytes. Those
+ catch a different class of failure (a half-written manifest, a bad `Cache-Control`, an object in
+ the wrong place), and `selfUpdate.ts` would refuse them silently: every daemon simply keeps the
+ version it has, and the release looks fine.
+
+## Dry run
+
+**Actions → Release → Run workflow**, with `metadata_path` = `harness/cli/metadata-test.json`. No
+daemon polls that file, so nothing self-updates.
+
+The *artifacts* still go to their real home, `harness/cli/<version>/` — that path is hardcoded in
+`upload-cli.sh`, and these workflows do not edit the release scripts. So use an unmistakable version
+(`9.9.9`) and delete `gs://s3-autonomous-upgrade-3/harness/cli/9.9.9/` afterwards.
+
+Expect `>> could not read remote metadata` in the log: `METADATA_PATH` points at a file that does
+not exist yet, and that line is only the auto-bump's input. The version that publishes is the one
+you typed.
+
+## The Node pin
+
+`ci.yml` has a single step whose whole job is to print `node-version=22.23.2`, and `release.yml`
+reads it back through `needs.tests.outputs.node-version`. A release therefore cannot be bundled on a
+runtime the suite did not run on.
+
+The number is not a taste in Node versions. It is the **managed runtime** the shipped CLI actually
+executes on: `harness/runtime/metadata.json` serves node v22.23.2 for `darwin-arm64`, `darwin-x64`,
+`linux-x64` and `linux-arm64`, `install.sh` unpacks it under `~/.harness/runtime`, and the launcher
+names that binary absolutely — the user's own node, if any, never runs the bundle. Bump it together
+with `make upload-node-runtime` in `autonomous-harness-desktop`, never on its own.
+
+`package.json`'s `engines: node >=20` is a different statement: the floor a third party may run the
+package on. A floor is not a pin.
+
+## npm, not pnpm
+
+CI installs with `npm ci` against `cli/package-lock.json`, because every build path in this repo
+shells out to `npm run bundle` — `install-cli.sh`, `upload-cli.sh`, `remote-machine.sh`. npm's
+lockfile is the one the released bytes are built from.
+
+That also makes `npm ci` a gate rather than a chore: it fails when `package-lock.json` and
+`package.json` disagree.
+
+`cli/pnpm-lock.yaml` is tracked too, and until now nothing kept it in step. On 2026-09-09
+`bonjour-service` was added to `package.json` with only `package-lock.json` updated; `main` went
+green, and `make install-cli` then died at `Could not resolve "bonjour-service"` on every machine
+whose `node_modules` came from pnpm. `ci.yml` now runs `pnpm install --frozen-lockfile
+--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.