feat(cli): enforce tenant client version policy

apps/docs/next/cli/commands.mdx

@@ -48,7 +48,7 @@ blue codex      # launch Codex through Blue; or claude, kimi, opencode
 | `blue logout` | Revoke the refresh family when reachable and remove local tokens. |
 | `blue doctor` | Show detected harness paths, versions, and policy allow or deny state. |
 | `blue agent [NAME]` | Choose the preferred agent used by bare `blue`. In an interactive terminal this also offers installed agents whose version needs repairing, and installs a policy-supported release before saving the choice. Without a terminal only eligible agents are accepted. |
-| `blue status` | Compare desired/applied revisions and report managed-file and package health. |
+| `blue status` | Show the remote tenant version, compare desired/applied revisions, and report managed-file and package health. |
 | `blue verify` | Exit non-zero when policy or managed files are stale. |
 | `blue config` | Print the resolved, personalized configuration and its source. |
 | `blue apply [--yes]` | Reconcile the configured default agent. |

apps/docs/next/deployment/blue-yaml.mdx

@@ -305,7 +305,7 @@ The `governance` section is the deployment-authored baseline delivered to client
 | `contract_version` | Wire contract version. Current clients support version 3. |
 | `required_capabilities` | Features a client must support before accepting policy. |
 | `minimum_client_version` | Operator-visible rollout floor; required when using harness version ranges or versioned package adapters. |
-| `required_client_version` | Optional canonical exact SemVer recommendation for the Blue CLI. Defaults to the control API deployment version and requires `tenant_client_version_pin`. |
+| `required_client_version` | Optional canonical exact SemVer recommendation for the Blue CLI and major compatibility boundary. Same-major differences warn; different majors block. |
 | `ttl_seconds` | Client cache and polling interval; defaults to 300 seconds. |
 | `required` | When true, clients fail closed instead of launching from stale cached policy. |
 | `allowed_harnesses` | Supported agent keys users may launch through Blue. |
@@ -404,10 +404,10 @@ Every source must be immutable and SHA-256 pinned. Use `platform_sources` when h
   A complete rollout has healthy service probes, no unresolved environment references, the expected governance revision in the dashboard, and matching desired/applied revisions on a test client.
 </Check>
 
-## Recommended Blue CLI release
+## Tenant-compatible Blue CLI
 
 The reference control API advertises its deployment version as the exact
-recommended Blue CLI release. Set
+recommended Blue CLI release and the major-version compatibility boundary. Set
 `governance.required_client_version` to a published, compatible release to
 override that default, for example during a rolling upgrade. The default is
 applied when serving a document, so old revisions follow new deployments without
@@ -418,4 +418,34 @@ informational.
 The `tenant_client_version_pin` capability is required whenever a pin is served.
 The `X-Blue-Required-Client-Version` header exposes the same pin on successful
 config responses and capability/contract rejections (HTTP 426). Older clients
-without this capability cannot consume the document.
+without this capability are blocked and need a manual install.
+
+A CLI with the same major version prints a neutral recommendation when its minor,
+patch, prerelease, or build metadata differs. In an interactive foreground
+command, Blue offers to install the exact recommended release with consent
+defaulting to yes. Declining, cancelling, failing, or being unable to offer the
+compatible update leaves the installed release in place and lets the command
+continue. After a successful replacement, rerun the command so the old process
+does not continue. Noninteractive commands continue after printing the
+recommendation, and background watchers only log it. Exact matches are silent.
+
+A CLI with a different major version blocks governed commands before launching a
+harness or applying managed configuration. In an interactive foreground command,
+Blue offers to install the exact recommended release, with consent defaulting to
+yes. It stages and verifies the release before replacing the running executable.
+After success, rerun the original command; the old process never continues the
+operation and returns a nonzero exit code. Automatic installation supports stable
+releases only and requires a writable, safely resolved installation destination.
+
+Noninteractive commands, daemons and internal hooks never prompt or install.
+`blue apply --yes` does not approve replacing Blue. A difference displays the
+recommended installer command when available. A major mismatch also displays
+`blue reset` as a way to detach; declining or failing installation leaves that
+command blocked.
+
+A live cross-major mismatch invalidates the previous cached policy. Cached
+documents are also checked against the executing CLI version. Same-major drift
+does not invalidate the cache or managed state. A client that has never observed
+a remote version change cannot discover it offline; otherwise compatible cached
+policy retains the usual offline behavior. `blue reset` remains available without
+fetching governance policy.

apps/docs/next/reference/governance-config.mdx

@@ -79,7 +79,7 @@ harnesses:
 | `allowed_harnesses` | Harness names permitted by policy. |
 | `harnesses` | Per-harness policy keyed by supported harness name. |
 | `minimum_client_version` | Operator-visible rollout floor; it does not replace capability enforcement. |
-| `required_client_version` | Optional canonical exact SemVer recommendation for the Blue CLI. Defaults to the control API deployment version and requires `tenant_client_version_pin`. |
+| `required_client_version` | Optional canonical exact SemVer recommendation for the Blue CLI and major compatibility boundary. Same-major differences warn; different majors block. |
 | `packages` | Organization-selected, immutable extension packages and their harness adapters. |
 | `gateway` | Global inference routing policy applied to every allowed coding agent. |
 | `session_upload` | Global portable-session capture policy; compatible profiles upload integrity-checked bundles while older clients remain accepted as non-resumable raw artifacts. |
@@ -140,15 +140,32 @@ The dashboard can inspect `github:owner/repository@ref` for a public GitHub repo
 
 Removing a package disables it for subsequent governed launches. Unmodified owned content is deleted; locally changed content is moved to quarantine and reported as drift.
 
-## Recommended Blue CLI release
+## Tenant-compatible Blue CLI
 
 The reference control API advertises its deployment version as the exact
-recommended Blue CLI release. Set
+recommended Blue CLI release and the major-version compatibility boundary. Set
 `governance.required_client_version` to a published, compatible release to
 override that default. The value remains an exact canonical SemVer, not a range.
 `minimum_client_version` remains informational.
 
 The `tenant_client_version_pin` capability is required whenever a pin is served.
 The `X-Blue-Required-Client-Version` header exposes the same pin on successful
 config responses and capability/contract rejections (HTTP 426). Older clients
-without this capability cannot consume the document.
+without this capability are blocked and need a manual install.
+
+A different minor, patch, prerelease, or build value within the same major emits
+a neutral recommendation, then offers to install the exact recommended release
+in an interactive foreground command. The prompt defaults to yes; declining or
+an unavailable installation continues with the compatible installed version.
+Exact matches are silent. A different major blocks before launch or configuration
+changes and offers the same default-yes install prompt when supported, but the
+command remains blocked if installation does not complete.
+
+Noninteractive commands, daemons and internal hooks never prompt or install;
+background sessions only log same-major recommendations. `blue apply --yes` does
+not approve replacing Blue. Cross-major errors include `blue reset` as a way to
+detach.
+
+A live cross-major mismatch invalidates the previous cached policy. Same-major
+drift keeps cached policy and managed state usable. Cached documents are checked
+on load, and `blue reset` remains available without fetching governance policy.

apps/docs/openapi/next.yaml

@@ -190,7 +190,7 @@ paths:
           description: The governance config
           headers:
             X-Blue-Required-Client-Version:
-              description: Exact recommended Blue CLI release, identical to required_client_version in the document.
+              description: Exact recommended Blue CLI release, identical to required_client_version in the document. Same-major differences warn; different majors block.
               schema: { type: string }
           content:
             application/json:
@@ -201,7 +201,7 @@ paths:
           description: Client contract version or capabilities are insufficient
           headers:
             X-Blue-Required-Client-Version:
-              description: Exact recommended Blue CLI release, provided even when the document cannot be consumed.
+              description: Exact recommended Blue CLI release and major compatibility boundary, provided even when the document cannot be consumed.
               schema: { type: string }
 
   /harness-metadata:
@@ -1697,7 +1697,7 @@ components:
         minimum_client_version: { type: string, description: Operator-visible rollout floor; required capabilities enforce compatibility }
         required_client_version:
           type: string
-          description: Canonical exact SemVer of the recommended Blue CLI release. Defaults to the control API deployment version. Requires tenant_client_version_pin capability.
+          description: Canonical exact SemVer of the recommended Blue CLI release and major compatibility boundary. Unequal versions within the same major warn and continue; different majors block. Defaults to the control API deployment version. Requires tenant_client_version_pin capability.
           example: "0.1.0"
         ttl_seconds: { type: integer, description: Client cache TTL (default 300), example: 300 }
         required: { type: boolean, description: "If true, client fails closed without fresh config" }

crates/gh-agent/src/lib.rs

@@ -399,9 +399,10 @@ pub fn reconcile_loop(
 /// not be, because nothing the daemon does will fix it.
 fn failure_backoff(error: &GhError) -> (u64, bool) {
     match error {
-        GhError::Unauthorized(_) | GhError::Forbidden(_) | GhError::ActionRequired(_) => {
-            (GovernanceConfig::DEFAULT_TTL_SECONDS * 4, true)
-        }
+        GhError::ClientVersionMismatch { .. }
+        | GhError::Unauthorized(_)
+        | GhError::Forbidden(_)
+        | GhError::ActionRequired(_) => (GovernanceConfig::DEFAULT_TTL_SECONDS * 4, true),
         _ => (GovernanceConfig::DEFAULT_TTL_SECONDS, false),
     }
 }