PATH, reads its version, and selects a compiled compatibility profile before it writes managed files or launches the process. When an installed version is incompatible, an interactive CLI can offer to run the catalog-defined vendor installer after explicit confirmation.
Reconciliation flow
The selected profile owns the native representation of managed settings, MCP servers, gateway wiring, session hooks, skills, subagents, plugins, helpers, environment variables, and launch arguments. Governance and packages remain declarative inputs.Pin an allowed range
Setversion_requirement under the harness policy. Blue uses semantic-version requirement syntax.
=0.149.1. Omitting the field allows any installed version covered by a maintained client profile. The Control API records minimum_client_version for rollout visibility and requires the corresponding capabilities, which prevent an older Blue client from silently ignoring the constraint.
Every profile also has an exclusive certified release ceiling. A release tested through 0.151.0 uses 0.151.1-0 as its ceiling so prereleases of the next patch are blocked too. Blue blocks a newer release until that release is exercised and the ceiling advances. To deliberately accept a newer, untested release, constrain it explicitly and opt in:
version_requirement. Reconciliation and inventory continue with a warning because vendor changes beyond the certified ceiling may produce invalid configuration.
Run blue apply or launch through blue run to see the normalized version, selected profile, and compatibility error. Blue performs compatibility preflight only for the default or explicitly launched harness before changing its files.
Repair an incompatible installation
In a terminal,blue run and blue apply show the policy-compatible install command and ask whether to run it. The default answer is No. If approved, Blue resolves a published release inside the policy and certified range, updates the installation that owns the detected executable, and verifies that same path against the policy before reconciliation or launch continues. This prevents an npm repair from appearing successful while a standalone binary earlier on PATH remains unchanged.
For npm-owned binaries, Blue runs the package-manager selector directly.
OpenCode repairs through the detected executable’s version-aware upgrade command.
Standalone Kimi installations use Kimi’s checksum-verifying installer with an
exact version and the detected installation root. Installer failure or an
unchanged detected path stops the flow before any managed files are written.
Blue-launched sessions suppress each harness’s native update check or automatic
updater so a repaired version remains inside the certified range on subsequent
launches. This is scoped to the managed launch: running the native harness
directly retains the user’s normal update behavior, and an external package
manager can still replace the installed binary. The selected compatibility
version’s atomic operation set owns this suppression, so a later harness version
can adopt a changed vendor control without altering older intervals.
Daemon runs, redirected/non-interactive commands, and blue apply --yes never install native CLIs. They fail closed and print the command for an operator to run explicitly.
Breaking-version profiles
Each harness has an ordered registry of compiled profiles. Every profile has an inclusiveintroduced bound, an optional exclusive breaking-generation before bound, and a mandatory exclusive verified_before release ceiling. Dispatch may remain open-ended, but certified support never is: a parseable release at or beyond verified_before is blocked unless the organization uses the explicit unverified opt-in above.
For example, introducing a profile at 2.0.0 produces these paths:
Maintainers add the boundary and version specification together, retain the older specification and operation set, and add golden output tests at the versions immediately below and at the boundary. A profile may later be marked deprecated, which continues to work with a warning. Removing it is an explicit Blue release change.
Versioned package layouts
A package’s normal adapter fields are its fallback layout. Usevariants only when the archive exposes different paths for different native harness versions.
Use adapter-level introduced and before bounds when the package itself is
available only for part of the harness’s history. Blue rejects enabling the
package when the organization harness policy extends outside that availability
range, so administrators can either narrow the harness policy or disable the
package for that harness.
introduced and exclusive at before. Variants must stay inside adapter availability, be ordered, and not overlap. Gaps inside availability are allowed only when the adapter has a fallback layout.
Transaction and rollback guarantees
Blue resolves every harness generation and constructs exact file bodies, modes, removals, environment variables, and launch arguments in memory before active files change. It then validates the plan, snapshots affected paths, and commits under per-harness advisory locks. Package and compatibility state are committed in the same transaction. A failed renderer, package activation, or state commit restores the snapshot; if a later required harness fails, the outer revision transaction restores earlier harness commits too. If package selection, validation, download, helper collision, or installation fails, the whole previous package activation remains recorded. Blue activates that last-known-good content only when the stored adapter interval still contains the installed native harness version. Otherwise it retains the content inactive and blocks launch. Obsolete paths are removed only after a successful commit and only when the ownership manifest identifies them as Blue-owned. Package and compatibility state files include schema versions. Unknown future schemas fail closed.Maintainer checklist
To add a generation for an existing harness:- Add a complete
VersionSpecthat reuses the harness family’s operation set for unchanged behavior and explicitly marks optional capabilities supported or unsupported. - Register its contiguous
[introduced, before)interval and an exclusiveverified_beforeceiling in order. - Add vendor version-output fixtures and golden output immediately below and at the boundary.
- Advance the current certified ceiling when the E2E harness lock is updated; registry tests require a
next-patch-0ceiling immediately beyond that pinned stable release.
gh_common::harness_catalog! entry and its initial adapters/<harness>/ family implementation and version spec. The catalog generates harness identity, enumeration, discovery metadata, and the gh-config definition registration. Production API schemas accept catalog keys rather than repeating a closed enum; docs and E2E matrices remain explicit evidence. To support a breaking vendor version, add one specification and one contiguous interval registration. Registry tests enforce unique keys and aliases, valid ordered probes, ordered lifecycle metadata, certified ceilings, and exactly one implementation per interval. Deprecate an interval by changing its lifecycle to deprecated; remove it only in an announced client release after policies and package intervals no longer target it. The complete file-level workflow is in Harness adapter architecture.
Package variants select verified archive content only. They cannot send executable translation logic from the server: the selected compiled compatibility profile still decides how to load every component.