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.

fix: never let self-update overwrite a local dev build

Dev jacobdf2f248e4ffa
diff --git a/cli/scripts/install-cli.sh b/cli/scripts/install-cli.sh
index dd1ca3a7c..556f9fee8 100755
--- a/cli/scripts/install-cli.sh
+++ b/cli/scripts/install-cli.sh
@@ -11,18 +11,22 @@
# bash scripts/install-cli.sh --no-updates # pin this build: turn self-update OFF (default: ON)
#
# SELF-UPDATE STAYS ON BY DEFAULT, and the version label is what makes that safe. The build is labelled
-# `<published-core>-dev.<sha>`, and semverGt() (lib/selfUpdate.ts) compares the X.Y.Z core ONLY and is
-# false on equality — so the release you are level with can never overwrite your build, while the NEXT
-# release does. That is the behaviour you want: develop on your own bytes, and still be carried forward
-# when a real version ships.
+# `<published-core>-dev.<sha>`, and shouldAutoUpdate() (lib/selfUpdate.ts) refuses to replace ANY
+# `-dev.` build automatically — so no release, however far ahead, overwrites your bytes on its own.
#
-# It used to default to OFF, which pinned the computer silently: a new release would land in the manifest
-# and simply never arrive, and the only clue was `harness update` working by hand while nothing happened
-# on its own. `--no-updates` still gives you that, deliberately — it exports ADAPTER_UPDATE_DISABLE=true
-# in the launcher, switching off both the 60s poll and `harness start`'s update-before-connect (cli.ts
-# `stageLatestBundle`). To rejoin the release train from a pinned install, re-run this without the flag,
-# or the public installer:
+# It did not always: the rule used to be ordering alone (semverGt on the X.Y.Z core), which let the
+# release you were level with sit still but let the NEXT one land. That reads like being carried
+# forward and behaves like losing your work — a machine developing against unreleased CLI code had its
+# bundle swapped mid-session, and the only symptom was the unreleased feature quietly not working.
+#
+# So: nothing here pins the computer, and nothing overwrites it either. To take a release deliberately,
+# `harness update --force`, or the public installer:
# curl -fsSL https://harness.autonomous.ai/cli/install.sh | bash
+#
+# `--no-updates` remains for a stronger promise — no manifest is even fetched. It exports
+# ADAPTER_UPDATE_DISABLE=true in the launcher, switching off both the 60s poll and `harness start`'s
+# update-before-connect (cli.ts `stageLatestBundle`), which also silences the update check for a
+# release-labelled build installed with --no-build.
set -euo pipefail
ADAPTER_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)" # this package
@@ -63,10 +67,8 @@ fi
# --- Step 1: bundle, labelled <published-core>-dev.<sha>[.dirty] ---
# The core matches the release so `harness version`/`status` read sensibly next to prod, and the
-# prerelease suffix makes it unmistakably a local build. semverGt() (lib/selfUpdate.ts) compares the
-# X.Y.Z core only, so this is never NEWER than the published release — a second layer under the
-# launcher's disable: even with updates on, the computer sits still until the next real release
-# instead of oscillating.
+# `-dev.` suffix is load-bearing, not decoration: it is what shouldAutoUpdate() (lib/selfUpdate.ts)
+# matches to leave this build alone, and what `harness update` refuses to replace without --force.
if [ "$DO_BUILD" -eq 1 ]; then
# Shared with the Docker remote-machine rig, so both boxes report the SAME version for the same
# tree — see scripts/lib/build-label.sh.
@@ -91,9 +93,10 @@ if [ "$DO_BUILD" -eq 1 ] && [ "$VER" != "$LABEL" ]; then
fi
echo ">> installing $VER"
case "$VER" in
- *-*) : ;; # has a prerelease suffix → a published release can never outrank it
- *) echo " note: '$VER' looks like a RELEASE version, not a -dev build. With self-update on, a newer" >&2
- echo " published release would replace it; rebuild without --no-build to get a -dev label." >&2 ;;
+ *-dev.*|*-dev) : ;; # the label shouldAutoUpdate() protects
+ *) echo " note: '$VER' is not a -dev build, so it is NOT protected from self-update. With updates" >&2
+ echo " on, a newer published release would replace it; rebuild without --no-build to get" >&2
+ echo " a -dev label, or install with --no-updates." >&2 ;;
esac
# --- Step 3: stop the running daemon (it holds the OLD bytes in memory) ---
diff --git a/cli/scripts/lib/build-label.sh b/cli/scripts/lib/build-label.sh
index 453751186..834aad130 100644
--- a/cli/scripts/lib/build-label.sh
+++ b/cli/scripts/lib/build-label.sh
@@ -4,10 +4,11 @@
# `<published-core>-dev.<sha>[.dirty]`. Two properties, both deliberate:
#
# * The core matches the current release, so `harness version` and `harness status` read sensibly
-# next to a production install, and semverGt() (lib/selfUpdate.ts) — which compares the X.Y.Z core
-# only and is false on equality — can never let the release you are level with overwrite your
-# build. The NEXT real release still lands, which is the behaviour you want.
-# * The `-dev.<sha>` suffix makes it unmistakably local, and `.dirty` says the tree had uncommitted
+# next to a production install.
+# * The `-dev.<sha>` suffix is what shouldAutoUpdate() (lib/selfUpdate.ts) matches to leave this
+# build alone: no release replaces it automatically, and `harness update` says so rather than
+# doing it. Change this shape and local builds start being overwritten again. It also makes the
+# build unmistakably local, and `.dirty` says the tree had uncommitted
# changes when it was bundled — the difference between "this is commit abc123" and "this is
# something only my disk has ever seen".
#
diff --git a/cli/src/cli.ts b/cli/src/cli.ts
index 8bb781d4d..8f596d51e 100644
--- a/cli/src/cli.ts
+++ b/cli/src/cli.ts
@@ -109,7 +109,7 @@ import { MachinePeerStore } from './lib/e2ee/machinePeers.js'
import { connectWithPassword } from './lib/e2ee/relayClient.js'
import {
startSelfUpdater, restore as restoreUpdate, confirm as confirmUpdate,
- fetchManifest, downloadVerified, canary, stage, semverGt,
+ fetchManifest, downloadVerified, canary, stage, semverGt, shouldAutoUpdate, isLocalDevBuild,
type Poller, type UpdateEntry,
} from './lib/selfUpdate.js'
import { stat } from 'fs/promises'
@@ -236,7 +236,8 @@ Machine:
harness machines list the machines on this account (this computer's is marked)
harness machines delete <id> remove ANOTHER machine (refuses this one; use \`harness logout\`)
harness version print the installed version (v${VERSION})
- harness update update to the latest build now (it also self-updates in the background)
+ harness update [--force] update to the latest build now (it also self-updates in the background;
+ neither touches a local install-cli.sh build without --force)
harness flash [flags] re-flash a plugged-in circle device over USB. Flags go straight to the
flasher: --detect-only, --port, --version, --yes, --erase-nvs
@@ -623,14 +624,15 @@ async function downloadCanaryStage(entry: UpdateEntry, dir: string, log: (m: str
}
/** Fetch the manifest and, if a strictly-newer build exists, stage it (see downloadCanaryStage). Returns
- * the staged version, or null when nothing was staged — already current, a dev/repo or update-disabled
- * build, or ANY fetch/verify/canary failure (all swallowed: an update hiccup must never block `start`). */
+ * the staged version, or null when nothing was staged — already current, a local, dev/repo or
+ * update-disabled build, or ANY fetch/verify/canary failure (all swallowed: an update hiccup must
+ * never block `start`). See {@link shouldAutoUpdate} for why a local build is left alone. */
async function stageLatestBundle(log: (m: string) => void): Promise<string | null> {
if (SCRIPT_PATH.endsWith('.ts') || env.ADAPTER_UPDATE_DISABLE) return null // dev/repo run never touches the installed bundle
const dir = resolve(env.ADAPTER_CLI_DIR)
try {
const entry = await fetchManifest(env.ADAPTER_UPDATE_URL, env.ADAPTER_UPDATE_KEY)
- if (!entry || !semverGt(entry.version, VERSION)) return null
+ if (!entry || !shouldAutoUpdate(entry.version, VERSION)) return null
log(`▸ newer build available — updating v${VERSION} → v${entry.version}…`)
return (await downloadCanaryStage(entry, dir, log)) ? entry.version : null
} catch (e) {
@@ -642,17 +644,33 @@ async function stageLatestBundle(log: (m: string) => void): Promise<string | nul
/** `harness update` — force the self-update NOW instead of waiting for the daemon's
* background poll. Checks the manifest; if a newer build exists it stops any running daemon first (so
* its poller can't race our staging), swaps in the new bytes, then relaunches on them. No-op on a
- * dev/repo build, and leaves the daemon running-on-the-old-build untouched when already up to date. */
-async function updateCommand(): Promise<void> {
+ * dev/repo build, and leaves the daemon running-on-the-old-build untouched when already up to date.
+ *
+ * On a LOCAL build (`install-cli.sh`) it stops and says so: the automatic paths leave those alone
+ * (see {@link shouldAutoUpdate}), and a command that silently did the opposite would be the same
+ * lost-work trap with a human's finger on it. [force] is that human saying it anyway. */
+async function updateCommand(force: boolean): Promise<void> {
if (SCRIPT_PATH.endsWith('.ts')) {
console.log('This is a dev/repo build (running from source) — `harness update` is a no-op. Rebuild the bundle instead.')
process.exit(0)
}
+ if (isLocalDevBuild(VERSION) && !force) {
+ console.log(`This is a local build (v${VERSION}), installed from a working tree by scripts/install-cli.sh.`)
+ console.log('Updating would replace it with a published release and lose whatever it was built to test.')
+ console.log(' keep it: rebuild with `make install-cli` after you pull')
+ console.log(' replace it: harness update --force')
+ process.exit(0)
+ }
console.log(`▸ Checking for updates… (current v${VERSION})`)
let entry: UpdateEntry | null = null
try { entry = await fetchManifest(env.ADAPTER_UPDATE_URL, env.ADAPTER_UPDATE_KEY) }
catch (e) { console.error(`✗ Could not reach the update manifest: ${e instanceof Error ? e.message : e}`); process.exit(1) }
- if (!entry || !semverGt(entry.version, VERSION)) {
+ // `--force` on a local build is the one case where "newer" is not the question. Its label carries
+ // the published core (`0.1.56-dev.<sha>`), so semverGt is false against the release it was built
+ // level with — the check that keeps a release from stomping the build is also the check that would
+ // make the deliberate swap a no-op.
+ const replacingLocalBuild = force && isLocalDevBuild(VERSION)
+ if (!entry || !(semverGt(entry.version, VERSION) || replacingLocalBuild)) {
console.log(`✓ Already on the latest version (v${VERSION}).`)
process.exit(0)
}
@@ -4585,7 +4603,7 @@ switch (cmd) {
status().catch(onError)
break
case 'update':
- updateCommand().catch(onError)
+ updateCommand(flags.includes('--force')).catch(onError)
break
case 'flash':
// Everything after `flash` belongs to the flasher, not to us — see lib/flash.ts on why the flags
diff --git a/cli/src/lib/selfUpdate.spec.ts b/cli/src/lib/selfUpdate.spec.ts
index 5424afde1..2619c1038 100644
--- a/cli/src/lib/selfUpdate.spec.ts
+++ b/cli/src/lib/selfUpdate.spec.ts
@@ -2,7 +2,7 @@ import { mkdtempSync, readFileSync, rmSync } from 'fs'
import { tmpdir } from 'os'
import { join } from 'path'
import { afterEach, describe, expect, it } from 'vitest'
-import { canary, stage } from './selfUpdate.js'
+import { canary, isLocalDevBuild, semverGt, shouldAutoUpdate, stage } from './selfUpdate.js'
let dirs: string[] = []
@@ -33,3 +33,28 @@ describe('selfUpdate packaging', () => {
expect(JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'))).toEqual({ type: 'module' })
})
})
+
+describe('shouldAutoUpdate', () => {
+ it('recognises the labels install-cli.sh and version.ts produce', () => {
+ expect(isLocalDevBuild('0.1.56-dev.a1b2c3d')).toBe(true)
+ expect(isLocalDevBuild('0.1.56-dev.a1b2c3d.dirty')).toBe(true)
+ expect(isLocalDevBuild('0.0.0-dev')).toBe(true)
+ expect(isLocalDevBuild('0.1.56')).toBe(false)
+ expect(isLocalDevBuild('0.1.56-rc.1')).toBe(false)
+ expect(isLocalDevBuild('')).toBe(false)
+ })
+
+ it('never overwrites a local build, however far ahead the release is', () => {
+ // The regression this exists for: a build labelled with the core it was made level with, then
+ // silently replaced mid-session by the very next release.
+ expect(semverGt('0.1.57', '0.1.56-dev.a1b2c3d')).toBe(true)
+ expect(shouldAutoUpdate('0.1.57', '0.1.56-dev.a1b2c3d')).toBe(false)
+ expect(shouldAutoUpdate('9.9.9', '0.1.56-dev.a1b2c3d.dirty')).toBe(false)
+ })
+
+ it('leaves a released install on the release train', () => {
+ expect(shouldAutoUpdate('0.1.57', '0.1.56')).toBe(true)
+ expect(shouldAutoUpdate('0.1.56', '0.1.56')).toBe(false)
+ expect(shouldAutoUpdate('0.1.55', '0.1.56')).toBe(false)
+ })
+})
diff --git a/cli/src/lib/selfUpdate.ts b/cli/src/lib/selfUpdate.ts
index 109db20d4..e875ce52d 100644
--- a/cli/src/lib/selfUpdate.ts
+++ b/cli/src/lib/selfUpdate.ts
@@ -35,7 +35,10 @@ const PACKAGE = 'package.json'
const RUNTIME_PACKAGE = `${JSON.stringify({ type: 'module' })}\n`
/** Strict semver-greater on the `X.Y.Z` core (ignores pre-release/build). Unparseable → false, so a
- * malformed manifest or the `0.0.0-dev` dev sentinel never triggers a downgrade/oscillation. */
+ * malformed manifest or the `0.0.0-dev` dev sentinel never triggers a downgrade/oscillation.
+ *
+ * Ordering only — it is NOT the permission to update. Automatic updates go through
+ * {@link shouldAutoUpdate}, which also refuses to overwrite a local build. */
export function semverGt(a: string, b: string): boolean {
const parse = (v: string): number[] | null => {
const m = /^(\d+)\.(\d+)\.(\d+)/.exec(v)
@@ -48,6 +51,29 @@ export function semverGt(a: string, b: string): boolean {
return false
}
+/** A build made from a working tree rather than downloaded from the release channel: the
+ * `<published-core>-dev.<sha>[.dirty]` label that scripts/lib/build-label.sh stamps on every local
+ * install, plus the `0.0.0-dev` sentinel version.ts falls back to. */
+export function isLocalDevBuild(version: string): boolean {
+ return /^\d+\.\d+\.\d+-dev(\.|$)/.test(version.trim())
+}
+
+/**
+ * The gate every AUTOMATIC update passes: the daemon's background poll and `harness start`'s
+ * update-before-connect. Newer, AND not on top of a local build.
+ *
+ * Install-if-missing, never upgrade-over-a-dev-build. The old rule was ordering alone, and because
+ * `install-cli.sh` labels a local build `<published-core>-dev.<sha>`, the very next release outranked
+ * it: a machine developing against unreleased CLI code had its bundle silently replaced mid-session,
+ * and the only symptom was the unreleased feature quietly not working. Being carried forward is not
+ * worth that — a developer who wants the release can ask for it (`harness update --force`) and a
+ * release install, which is every user's, still updates exactly as before.
+ */
+export function shouldAutoUpdate(candidate: string, current: string): boolean {
+ if (isLocalDevBuild(current)) return false
+ return semverGt(candidate, current)
+}
+
/** Fetch + parse the manifest; return this adapter's entry, or null (unreachable / malformed / absent). */
export async function fetchManifest(url: string, key: string): Promise<UpdateEntry | null> {
// No `cache` option needed: undici doesn't HTTP-cache by default and GCS serves the manifest no-cache.
@@ -125,8 +151,9 @@ export function confirm(dir: string): void {
export interface Poller { stop(): void }
/**
- * Poll on an interval; on the first strictly-newer, verified, canary-passed build, STAGE it and call
- * `onStaged(version)` exactly once, then stop polling (the caller restarts immediately). Every failure
+ * Poll on an interval; on the first build {@link shouldAutoUpdate} allows that also verifies and
+ * passes its canary, STAGE it and call `onStaged(version)` exactly once, then stop polling (the
+ * caller restarts immediately). Every failure
* (fetch/parse/sha/canary/disk) is swallowed and simply retried next tick — the daemon never crashes
* on a bad update.
*/
@@ -149,7 +176,7 @@ export function startSelfUpdater(opts: {
checking = true
try {
const entry = await fetchManifest(opts.url, opts.key)
- if (!entry || !semverGt(entry.version, opts.currentVersion)) return
+ if (!entry || !shouldAutoUpdate(entry.version, opts.currentVersion)) return
console.log(`[update] newer build available: ${opts.currentVersion} → ${entry.version}`)
const cliBuf = await downloadVerified(entry.cli)
const notifyBuf = await downloadVerified(entry.notify)