Semantic versioning (1.0.0) and MSI-based agent upgrades #19

Merged
gsadmin merged 27 commits from dev into main 2026-10-24 02:57:05 +00:00
Owner

Semantic versioning, the first semantic release (1.0.0), and MSI-based agent upgrades.

Semantic versioning

  • Releases are X.Y.Z from vX.Y.Z tags. The next version is computed from conventional commits by semantic-release in dry-run mode (pinned in build/release). Our script creates the tag and the Gitea release with notes.
  • Seed tag: v0.1.0 is on the last calendar release (v2026.10.23.2331). This PR carries BREAKING CHANGE, so the first release is 1.0.0. I checked this with a simulated merge.
  • Builds between releases are X.Y.Z.N (commits since the tag), with no prerelease labels, so Windows, MSI and AssemblyVersion take them as they are. InformationalVersion is X.Y.Z+sha.
  • One comparison everywhere (server, agent, watchdog, installer custom action, console, group rules): calendar-era versions (major ≥ 2000) sort before every semantic version.
  • CI and release:
    • A push to main releases only when a release is due. release.yml builds X.Y.Z, tags it, publishes it, and pushes images :X.Y.Z and :latest.
    • Otherwise CI pushes :X.Y.Z.N and :latest.
    • Other branches push :dev and :X.Y.Z.N-dev. This is a change: they no longer push the bare version tag.
  • Installers (agent and server):
    • AllowDowngrades plus a FindNewerRelease custom action (DTF) that maps old 26.x MSI versions back to the calendar version. A 1.0.0 MSI therefore upgrades over 26.x, while a real accidental downgrade is refused unless ALLOWDOWNGRADE=1 is passed.
    • REINSTALLMODE=amus, so 1.x files replace 2026.x-stamped ones.
    • KeepInstallerPackage keeps the MSI an install ran from, with a package.json beside it, for rollbacks.

MSI-based agent upgrades

  • Which installs: an agent the MSI installed (found through its UpgradeCode and install folder) upgrades and rolls back through its MSI. Programs and Features and detection tools see the real version. Portable installs keep the file swap.
  • How it runs:
    • The watchdog starts a detached copy of itself that installs through msi.dll in-process (MsiSetInternalUI, MsiEnableLogW, MsiInstallProductW, REBOOT=ReallySuppress). No msiexec or PowerShell is involved, and the runner survives the MSI stopping both services.
    • 0, 3010 and 1641 count as success. When another install holds Windows Installer (1618), it retries every 30 s for up to 10 minutes. Each run is capped at 30 minutes and writes its own log.
  • Health and rollback: the new agent must report healthy and connected within the health deadline. If it doesn't, the previous MSI is reinstalled with ALLOWDOWNGRADE=1: the kept copy, or the server's copy for that version.
  • Server: the catalog holds the MSI, devices report how they were installed, MSI devices get the MSI together with the MSI of the version they run now, and the console shows Installed by MSI / Portable.

Testing

  • Automated: 173 shared, 137 agent, 73 watchdog and 184 backend tests pass, and the console typecheck and lint are clean.
  • Real local in-process MSI test: a detached runner installed throwaway MSIs after the watchdog was killed. It covered:
    • an upgrade
    • a rollback of an unhealthy version via ALLOWDOWNGRADE=1
    • Programs and Features showing the new version
    • Windows Installer's log naming the runner as the calling process
  • Release dry run on a simulated merge: 1.0.0.
  • Not tested:
    • Installing the new MSI over a real 26.x install, and the KeepInstallerPackage custom action running as SYSTEM.
    • A real fleet upgrade over NATS.
    • The watchdog on Linux/macOS.

🤖 Generated with Claude Code

Semantic versioning, the first semantic release (1.0.0), and MSI-based agent upgrades. ## Semantic versioning - **Releases** are `X.Y.Z` from `vX.Y.Z` tags. The next version is computed from conventional commits by semantic-release in dry-run mode (pinned in `build/release`). Our script creates the tag and the Gitea release with notes. - **Seed tag:** `v0.1.0` is on the last calendar release (`v2026.10.23.2331`). This PR carries `BREAKING CHANGE`, so the first release is **1.0.0**. I checked this with a simulated merge. - **Builds between releases** are `X.Y.Z.N` (commits since the tag), with no prerelease labels, so Windows, MSI and AssemblyVersion take them as they are. InformationalVersion is `X.Y.Z+sha`. - **One comparison everywhere** (server, agent, watchdog, installer custom action, console, group rules): calendar-era versions (major ≥ 2000) sort before every semantic version. - **CI and release:** - A push to `main` releases only when a release is due. `release.yml` builds `X.Y.Z`, tags it, publishes it, and pushes images `:X.Y.Z` and `:latest`. - Otherwise CI pushes `:X.Y.Z.N` and `:latest`. - Other branches push `:dev` and `:X.Y.Z.N-dev`. This is a change: they no longer push the bare version tag. - **Installers (agent and server):** - `AllowDowngrades` plus a **FindNewerRelease** custom action (DTF) that maps old 26.x MSI versions back to the calendar version. A 1.0.0 MSI therefore upgrades over 26.x, while a real accidental downgrade is refused unless `ALLOWDOWNGRADE=1` is passed. - `REINSTALLMODE=amus`, so 1.x files replace 2026.x-stamped ones. - **KeepInstallerPackage** keeps the MSI an install ran from, with a `package.json` beside it, for rollbacks. ## MSI-based agent upgrades - **Which installs:** an agent the MSI installed (found through its UpgradeCode and install folder) upgrades and rolls back through its MSI. Programs and Features and detection tools see the real version. Portable installs keep the file swap. - **How it runs:** - The watchdog starts a detached copy of itself that installs through `msi.dll` in-process (`MsiSetInternalUI`, `MsiEnableLogW`, `MsiInstallProductW`, `REBOOT=ReallySuppress`). No msiexec or PowerShell is involved, and the runner survives the MSI stopping both services. - 0, 3010 and 1641 count as success. When another install holds Windows Installer (1618), it retries every 30 s for up to 10 minutes. Each run is capped at 30 minutes and writes its own log. - **Health and rollback:** the new agent must report healthy and connected within the health deadline. If it doesn't, the previous MSI is reinstalled with `ALLOWDOWNGRADE=1`: the kept copy, or the server's copy for that version. - **Server:** the catalog holds the MSI, devices report how they were installed, MSI devices get the MSI together with the MSI of the version they run now, and the console shows Installed by MSI / Portable. ## Testing - **Automated:** 173 shared, 137 agent, 73 watchdog and 184 backend tests pass, and the console typecheck and lint are clean. - **Real local in-process MSI test:** a detached runner installed throwaway MSIs after the watchdog was killed. It covered: - an upgrade - a rollback of an unhealthy version via `ALLOWDOWNGRADE=1` - Programs and Features showing the new version - Windows Installer's log naming the runner as the calling process - **Release dry run** on a simulated merge: 1.0.0. - **Not tested:** - Installing the new MSI over a real 26.x install, and the KeepInstallerPackage custom action running as SYSTEM. - A real fleet upgrade over NATS. - The watchdog on Linux/macOS. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
gsadmin added 27 commits 2026-10-24 00:55:03 +00:00
AgentVersions compares semantic versions (a fourth field for builds between
releases, +metadata ignored) and sorts the calendar era (major 2000 or more)
before them. Presence reports how the agent was installed; MSI installs
upgrade from the MSI, with the current version's MSI for rollback; the
watchdog hand-over gains an msi kind and the runner's journal.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The MSI journal records a console rollback (ALLOWDOWNGRADE from the start) and
how many times a dead runner was resumed; the runner's lock, its binary folder
and the rollback MSI folder get names. An outcome can carry the sentence the
agent reports (exit code, log path, no MSI kept to go back to). Branding holds
the agent MSI's UpgradeCode and the file name an agent MSI is kept under.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The agent asks Windows Installer (msi.dll, MsiEnumRelatedProductsW on the
agent's UpgradeCode, the product's InstallLocation) whether it is an MSI
install and reports msi or portable on presence. An MSI install takes the msi
package only: downloaded and checked into upgrade/msi/, confirmed to be the
agent's MSI of that version (its Property table), with the MSI of the running
version set aside in upgrade/msi/rollback/ - a kept one from data/packages/,
else the command's rollback package, downloaded, checked and kept - or noted
as no automatic rollback. Every MSI an upgrade brings is kept under
data/packages/<sha256>/ (newest three). The hand-over has kind msi; a pending
msi.json makes the agent busy.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
An msi hand-over is never swapped. The watchdog checks the MSIs the agent
left in upgrade/msi/ (size, SHA-256), journals the run in msi.json, copies its
own binary to upgrade/msi/runner/ and starts it detached (CreateProcessW,
DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP | CREATE_BREAKAWAY_FROM_JOB, without
the breakaway when the job refuses it, | CREATE_NO_WINDOW) with the hidden verb
msi-run, since the MSI stops both services.

The runner holds msi.lock while it lives and calls msi.dll in process:
MsiSetInternalUI(NONE), MsiEnableLogW(0x1FDF, /l*v) into
<logs>/agent-msi-<version>-<id>.log, MsiInstallProductW with
REBOOT=ReallySuppress (ALLOWDOWNGRADE=1 for a console rollback). 0, 3010 and
1641 install; 1618 is retried every 30 s for 10 minutes, then installer-busy;
any other code, or 30 minutes without an answer, is failed/msi with the code,
the log path and its tail. It then waits for a connected beacon of the new
version written since the install began; one not healthy by the deadline is
taken back by the previous version's MSI with ALLOWDOWNGRADE=1 (its own log)
and ends rolled-back with the new agent's log tail, or, with no MSI kept, ends
failed/health-deadline saying so. Both services are left running, the outcome
written, msi.json removed.

A watchdog that finds msi.json leaves a live runner alone (its lock is held),
resumes a dead one from the journal (verifying when it died installing a
version that is already healthy), at most three times, and never supervises or
starts the agent while the run is pending.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A fake Windows Installer seam (the three msi.dll calls) and the fake clock and
agent drive the runner: silent UI and the verbose log per install, 0/3010/1641
as installed, 1618 retried every 30 s and given up as installer-busy after ten
minutes, other codes and a hung install as failed/msi, an unhealthy version
reinstalled from the previous MSI with ALLOWDOWNGRADE=1 into its own log, the
no-rollback failure, console rollbacks, the runner lock, and the watchdog
leaving a live runner alone, resuming a dead one and giving up after three.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
An MSI install hands the MSI over with the kept MSI of its version (or the
server's, downloaded, checked and kept; or none, said so), keeps what it
brought, refuses the zip, and is refused by a portable install; a kept MSI
whose bytes are not its folder's hash is not used; an MSI of another version
or not the agent's fails as package; msi.json makes it busy; kept packages
stay at the newest three plus those still needed. The outcome reporter passes
an MSI run's own detail on.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The catalog imports Agent.msi beside the zips (the same VERSION marker). A
device remembers from presence how its agent was installed (AgentInstall,
migration AgentInstallKind for SQLite, PostgreSQL and SQL Server; also on the
device DTO), and start, automatic upgrades and roll back pick its package with
AgentPackageTypes.ForDevice: an MSI install of win-x64 gets the MSI, or is
left out as no-package when the catalog holds no MSI of that version (never
the zip). An MSI command carries the catalog's MSI of the version the device
runs now (AreSame) as its rollback package, when held.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The catalog test now expects the MSI imported as Agent.msi. MSI devices get the
MSI and portable ones the zip, an MSI device without an MSI of the target is
left out as no-package, the MSI command carries the running version's MSI (or
none when the server has none), a rollback goes through the previous MSI, and
the device DTO says how the agent was installed.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The device page's Agent card has an Install row (Installed by MSI / Portable,
the upgrade path on hover), and the devices list's Agent version says it on
hover. The newest version a device is offered counts only MSIs for an MSI
install. Version chips name the MSI "Windows (MSI)"; the msi and
installer-busy reasons get labels; the installing and rolled-back hovers no
longer speak of swapping files only.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
How an agent the MSI installed upgrades: no msiexec, the Windows Installer API
from a detached runner, the verbose logs beside the agent's, 1618 retries,
ALLOWDOWNGRADE rollbacks, kept packages, and the server's copy for the first
upgrade of an install that has none kept; the catalog now holds the MSI.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The runner opens the MSI (and the rollback MSI) sharing read only and checks
its SHA-256 from that handle, holding it until Windows Installer answers, so
what installs is what was checked: nothing can write, replace or rename it in
between.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Two agent logs written in the same instant made the newest one a coin toss;
the test now leaves only the new agent's.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Releases are X.Y.Z from git tags vX.Y.Z; builds between releases are
X.Y.Z.N, N commits after the last release (git describe, 1-3 digit majors
only, so the calendar-era tags never count); with no release tag reachable
a build is 0.0.0.<commits>. Every version is 3-4 numeric fields, refused
when it does not fit an MSI ProductVersion or has a calendar-era major.

scripts/Get-Version.ps1 computes it (Get-UnifiedVersion.ps1 stays as the
old entry point). scripts/Get-NextRelease.ps1 runs semantic-release in
dry-run mode (pinned in build/release, conventionalcommits preset, main
only) for the version a release publishes, or for nothing when the commits
since the last release call for none. Directory.Build.props stamps
four-field assembly/file versions and InformationalVersion
X.Y.Z[.N]+<short commit>; a build not handed a version reads it from git
(build/Version.targets), otherwise 0.0.0.0.

BREAKING CHANGE: versions are no longer yyyy.MM.dd.HHmm. The first release
after the seed tag v0.1.0 is 1.0.0, which every comparison orders after
every calendar-era version.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Build, Test and the packaging scripts take the version from
Get-Version.ps1 and the short commit from the same place. Both MSIs get
the four-field version as ProductVersion (X.Y.Z.0 for a release, X.Y.Z.N
between releases) instead of the calendar transform. Checksums and release
assets take only their own version's files (1.4.0 no longer matches
1.4.0.7's).

Publish-Release.ps1 creates the tag vX.Y.Z on the released commit and the
release "ExecuteR X.Y.Z" with semantic-release's notes (-NotesFile,
-Prerelease), reuses both on a re-run of the same commit, refuses a version
already tagged on another commit and skips assets uploaded whole.

deploy.sh builds from source with the git version (0.0.0.0 without git)
and runs the images it built by that tag. Test.ps1 runs the watchdog
tests too.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The informational version is now X.Y.Z[.N]+<short commit>, so the reported
version (enrollment, presence, /health, CLI, the watchdog) is everything
before '+'; nothing is cut at '-' any more. No version is still 0.0.0.0.
ToMsiProductVersion (yyyy.MM.dd.HHmm to yy.MM.minutes) is gone: the MSIs
take the four-field version.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
IsCatalogVersion took only versions with a major above 0; semantic
versions start at 0.x (0.1.0 is the seed release). It now takes what
AgentVersions.IsValid takes (3 or 4 numeric fields, not 0.0.0.0), digits
and dots only.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
>, >=, < and <= on agentVersion compared text ordinally (1.10.0 before
1.9.0, every calendar version after 1.x). They now use AgentVersions, the
order upgrades use; a rule value of one or two numbers means its release
line (1.4 is 1.4.0).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
compareVersions and versionSortKey mirror AgentVersions: semantic versions
after the calendar era, a missing fourth field is 0, +metadata ignored,
0.0.0.0 and anything unparseable first, then ordinally.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Both MSIs take the four-field version as ProductVersion and remove every
installed version (MajorUpgrade AllowDowngrades), so 1.0.0.0 replaces the
calendar era's 26.x. Installer.CustomActions (DTF, WiX 5.0.2):

- FindNewerRelease (immediate, after FindRelatedProducts, NOT Installed)
  reads each WIX_UPGRADE_DETECTED product's version, maps the calendar
  encoding (yy.MM.minute-of-month) back to 20yy.MM.dd.HHmm and compares it
  with UNIFIEDVERSION by a copy of AgentVersions; a newer one sets
  NEWER_RELEASE_INSTALLED and the launch condition refuses the install
  unless ALLOWDOWNGRADE=1 (an MSI upgrade's rollback).
- KeepInstallerPackage (agent only; deferred, as SYSTEM, after InstallFiles
  on an install or upgrade) copies [OriginalDatabase] to
  %ProgramData%\ExecuteR\packages\<sha256>\<file name> in a folder only
  SYSTEM and Administrators may write, keeps the 3 most recently installed
  and never fails the install.

REINSTALLMODE=amus on upgrades and repairs, so 1.x files replace files
stamped 2026.x. PurgeCredentials and the server's service and data removal
stay gated on NOT UPGRADINGPRODUCTCODE, which a downgrade through the major
upgrade also sets.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
scripts/tests/Test-Versioning.ps1 (plain asserts, no Pester): the version
rules against canned git describe output and the limits, then a scratch
SHA-256 repository with a bare origin walked through the seed: calendar
tags ignored, no release tag refused, v0.1.0 plus a breaking change
releases 1.0.0, a re-run of the tagged commit is 1.0.0 again, builds after
it are 1.0.0.N, docs alone release nothing, a fix 1.0.1, a feat 1.1.0, a
branch other than main is refused.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Both workflows clone the branch's whole history with its tags (no
--depth): the version is the last release tag and the commits since it.

CI builds X.Y.Z.N. A push to main that releases builds as that release
(semantic-release dry run, the same numbering release.yml uses), so both
workflows agree on a release commit's version, and leaves its images to
release.yml. Other pushes publish images as before, except that only main
takes the bare <version> tag: a branch counts its own commits since the
same tag, so dev's 1.4.0.3 would overwrite main's. CI runs the versioning
checks.

release.yml numbers the release first and stops when none is due (only
docs, tests, chores...). Otherwise it builds every binary as X.Y.Z, tags
the commit vX.Y.Z and creates the Gitea release with semantic-release's
notes (Publish-Release.ps1), then publishes the images as X.Y.Z and
latest. Runs are serialized, so a second push numbers after the first.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
AgentVersions: the calendar era before 0.x and 1.x, 1.10 after 1.9, the
fourth field (missing = 0), +metadata, 0.0.0.0 and garbage first. The
installer's copy (compiled into Shared.Tests) answers exactly like it for
every pair, reads the calendar MSIs' yy.MM.minutes back and finds a newer
installed release by all four fields. KeepInstallerPackage keeps an MSI
under its hash with its name, once, the newest three and the one just
installed, and leaves other folders alone. agentVersion rules order by
version; the watchdog's version and the catalog's accepted versions.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The build stage copies build/Version.targets, so a handed-in
UNIFIED_VERSION is held to the same rules as every other build, and
passes GIT_COMMIT_SHORT on, so the image's binary reports X.Y.Z[.N]+<commit>
like the packaged one. Without a version it stays 0.0.0.0.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
README's Versioning section is rewritten: X.Y.Z releases from vX.Y.Z tags,
X.Y.Z.N builds, the limits, the one version order, how release.yml decides
and publishes a release, how to seed v0.1.0 so the first release is 1.0.0,
and how the MSIs upgrade over the calendar era and refuse a newer version
(ALLOWDOWNGRADE). The CI section names the new image tags. The design
specification's section 48 says semantic versions replace the calendar
ones; .env.example and the compose/swarm/k8s comments name the version
and tag shapes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
feat(installer): a kept MSI carries package.json, as the agent writes it
CI / build-test (push) Successful in 22m48s
CI / images (push) Successful in 2m46s
98f2a6f7a5
KeepInstallerPackage now gets the package's full version ([UNIFIEDVERSION])
and writes package.json ({"version","sha256"}, camelCase) beside the copy,
under a temporary name and renamed, so the agent finds a kept MSI's version
without opening it. The copy keeps the original file name
(ExecuteR-Agent-<version>.msi). UNIFIEDVERSION stays the version the agent
reports: the agent's MSI upgrades read it from the MSI.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Merge branch 'main' into dev
CI / build-test (pull_request) Successful in 5m44s
CI / images (pull_request) Has been skipped
e9d19a073f
gsadmin merged commit 7df75bdf77 into main 2026-10-24 02:57:05 +00:00
Sign in to join this conversation.