Skip to content

The agent that grows with you

fix(update): a stable release the updater refuses is held, not offered (#139099)

ethernetb1cfca7d78bd
diff --git a/apps/desktop/src/components/update-status.test.tsx b/apps/desktop/src/components/update-status.test.tsx
index 5c576ea8e6b..014b41d0860 100644
--- a/apps/desktop/src/components/update-status.test.tsx
+++ b/apps/desktop/src/components/update-status.test.tsx
@@ -93,6 +93,33 @@ describe('deriveUpdateStatus', () => {
expect(derive({ supported: true, behind: 0, branch: 'main' }).line).toBe(en.updates.latestBody)
})
+ it('names a stable release the updater refuses as held, never an update', () => {
+ const view = deriveUpdateStatus({
+ apply: IDLE_APPLY,
+ checking: false,
+ held: en.settings.about.channel.heldBody,
+ latestRelease: en.settings.about.channel.latestRelease,
+ status: {
+ supported: true,
+ behind: 0,
+ updateAvailable: false,
+ held: 'downgrade',
+ channel: 'stable',
+ sourceVersion: '0.22.2',
+ targetSha: 'd'.repeat(40),
+ currentSha: 'e'.repeat(40),
+ aheadOfRelease: false,
+ rollback: false
+ },
+ target: 'client',
+ u: en.updates
+ })
+
+ expect(view.updateAvailable).toBe(false)
+ expect(view.tone).toBe('idle')
+ expect(view.line).toBe(en.settings.about.channel.heldBody('v0.22.2'))
+ })
+
it('names a stable release the checkout already contains as a rollback, never a new update', () => {
const status = {
supported: true,
diff --git a/apps/desktop/src/components/update-status.tsx b/apps/desktop/src/components/update-status.tsx
index 2a79ecb245a..385eec7d0a3 100644
--- a/apps/desktop/src/components/update-status.tsx
+++ b/apps/desktop/src/components/update-status.tsx
@@ -70,6 +70,8 @@ interface UpdateStatusInput {
latestRelease?: (version: string) => string
/** Names a move back to an older stable release the checkout already contains. */
rollback?: (version: string) => string
+ /** Names a stable release the updater refuses, so this install stays where it is. */
+ held?: (version: string) => string
}
export function deriveUpdateStatus(input: UpdateStatusInput): UpdateStatusView {
@@ -106,6 +108,7 @@ function availableLine(
function ordinaryUpdateStatus({
apply,
checking,
+ held,
latestRelease,
rollback,
status,
@@ -149,22 +152,9 @@ function ordinaryUpdateStatus({
}
if (status) {
- // Stable pins to a release; name it. A checkout ahead of it (forward-only) is newer
- // than the release, so it keeps the generic line instead of claiming to be on it.
- const pinned =
- target === 'client' &&
- latestRelease &&
- status.channel === 'stable' &&
- status.sourceVersion &&
- // Older checkers omit the field and may also pin an ahead checkout to HEAD.
- status.aheadOfRelease === false &&
- status.targetSha &&
- status.currentSha === status.targetSha
-
return {
applying,
- line:
- target === 'backend' ? u.latestBodyBackend : pinned ? latestRelease(`v${status.sourceVersion}`) : u.latestBody,
+ line: currentLine(status, target, u, latestRelease, held),
supported,
tone: 'idle',
updateAvailable
@@ -174,6 +164,36 @@ function ordinaryUpdateStatus({
return { applying, line: checking ? u.checking : u.tapCheck, supported, tone: 'idle', updateAvailable }
}
+/** The line for an install with nothing to apply: a held release, the pinned stable release, or "latest". */
+function currentLine(
+ status: DesktopUpdateStatus,
+ target: UpdateTarget,
+ u: Translations['updates'],
+ latestRelease?: (version: string) => string,
+ held?: (version: string) => string
+): string {
+ if (target === 'backend') {
+ return u.latestBodyBackend
+ }
+
+ if (held && status.held && status.sourceVersion) {
+ return held(`v${status.sourceVersion}`)
+ }
+
+ // Stable pins to a release; name it. A checkout ahead of it (forward-only) is newer
+ // than the release, so it keeps the generic line instead of claiming to be on it.
+ const pinned =
+ latestRelease &&
+ status.channel === 'stable' &&
+ status.sourceVersion &&
+ // Older checkers omit the field and may also pin an ahead checkout to HEAD.
+ status.aheadOfRelease === false &&
+ status.targetSha &&
+ status.currentSha === status.targetSha
+
+ return pinned ? latestRelease(`v${status.sourceVersion}`) : u.latestBody
+}
+
function relativeTime(ms: number | undefined, u: Translations['updates']): string {
if (!ms) {
return u.never
@@ -323,6 +343,7 @@ export function UpdateStatusCard({
const view = deriveUpdateStatus({
apply,
checking,
+ held: t.settings.about.channel.heldBody,
latestRelease: t.settings.about.channel.latestRelease,
rollback: t.settings.about.channel.rollbackBody,
status,
diff --git a/apps/desktop/src/global.d.ts b/apps/desktop/src/global.d.ts
index b2461278012..b266da09084 100644
--- a/apps/desktop/src/global.d.ts
+++ b/apps/desktop/src/global.d.ts
@@ -899,6 +899,9 @@ export interface DesktopUpdateStatus {
aheadOfRelease?: boolean
/** Source stable: the checkout already contains the release, so installing it moves back. */
rollback?: boolean
+ /** Source stable: `hermes update` would refuse the release (it predates the gateway runtime these
+ * session stores use), so it is held instead of offered. */
+ held?: 'downgrade'
targetSha?: string
commits?: DesktopUpdateCommit[]
dirty?: boolean
diff --git a/apps/desktop/src/i18n/ar_update_channel.ts b/apps/desktop/src/i18n/ar_update_channel.ts
index 9c3e5995de4..6beea371377 100644
--- a/apps/desktop/src/i18n/ar_update_channel.ts
+++ b/apps/desktop/src/i18n/ar_update_channel.ts
@@ -14,6 +14,8 @@ export const arUpdateChannel = {
latestRelease: (v: string) => `أنت على أحدث إصدار مستقر (${v}).`,
rollbackTitle: (v: string) => `العودة إلى الإصدار المستقر ${v}`,
rollbackBody: (v: string) => `هذا الإصدار أحدث من الإصدار المستقر ${v}. سيعيد التثبيت Hermes إلى ذلك الإصدار.`,
+ heldBody: (v: string) =>
+ `هذا الإصدار أحدث من الإصدار المستقر ${v}، وجلساتك تستخدم بالفعل بيئة البوابة الخاصة به التي لا يستطيع ${v} فتحها. سيبقى Hermes على هذا الإصدار حتى يصدر إصدار مستقر أحدث.`,
rollbackAction: (v: string) => `العودة إلى ${v}`,
allChanges: 'عرض كل التغييرات'
}
diff --git a/apps/desktop/src/i18n/de_update_channel.ts b/apps/desktop/src/i18n/de_update_channel.ts
index c3a7e3b3402..60876f8278a 100644
--- a/apps/desktop/src/i18n/de_update_channel.ts
+++ b/apps/desktop/src/i18n/de_update_channel.ts
@@ -16,6 +16,8 @@ export const deUpdateChannel = {
rollbackTitle: (v: string) => `Zurück zum stabilen Release ${v}`,
rollbackBody: (v: string) =>
`Dieser Build ist neuer als das stabile Release ${v}. Die Installation setzt Hermes auf dieses Release zurück.`,
+ heldBody: (v: string) =>
+ `Dieser Build ist neuer als das stabile Release ${v}, und deine Sitzungen nutzen bereits seine Gateway-Laufzeit, die ${v} nicht öffnen kann. Hermes bleibt bei diesem Build, bis ein neueres stabiles Release erscheint.`,
rollbackAction: (v: string) => `Zurück auf ${v}`,
allChanges: 'Alle Änderungen ansehen'
}
diff --git a/apps/desktop/src/i18n/en_update_channel.ts b/apps/desktop/src/i18n/en_update_channel.ts
index b0fddb9fe86..7286b5aba12 100644
--- a/apps/desktop/src/i18n/en_update_channel.ts
+++ b/apps/desktop/src/i18n/en_update_channel.ts
@@ -17,6 +17,8 @@ export const enUpdateChannel: UpdateChannelCopy = {
rollbackTitle: (v: string) => `Back to stable release ${v}`,
rollbackBody: (v: string) =>
`This build is newer than the stable release ${v}. Installing it moves Hermes back to that release.`,
+ heldBody: (v: string) =>
+ `This build is newer than stable release ${v}. Your sessions already use a gateway runtime that ${v} cannot open, so Hermes stays on this build until a newer stable release ships.`,
rollbackAction: (v: string) => `Roll back to ${v}`,
allChanges: 'See all changes'
}
diff --git a/apps/desktop/src/i18n/es_update_channel.ts b/apps/desktop/src/i18n/es_update_channel.ts
index 2b6a09a8321..dcf2c911cf7 100644
--- a/apps/desktop/src/i18n/es_update_channel.ts
+++ b/apps/desktop/src/i18n/es_update_channel.ts
@@ -15,6 +15,8 @@ export const esUpdateChannel = {
rollbackTitle: (v: string) => `Volver a la versión estable ${v}`,
rollbackBody: (v: string) =>
`Esta compilación es más reciente que la versión estable ${v}. Al instalarla, Hermes vuelve a esa versión.`,
+ heldBody: (v: string) =>
+ `Esta versión es más reciente que la versión estable ${v}, y tus sesiones ya usan su entorno de gateway, que ${v} no puede abrir. Hermes se queda en esta versión hasta que salga una versión estable más reciente.`,
rollbackAction: (v: string) => `Volver a ${v}`,
allChanges: 'Ver todos los cambios'
}
diff --git a/apps/desktop/src/i18n/fr_update_channel.ts b/apps/desktop/src/i18n/fr_update_channel.ts
index 91c29ea22a8..8c7b26df1cc 100644
--- a/apps/desktop/src/i18n/fr_update_channel.ts
+++ b/apps/desktop/src/i18n/fr_update_channel.ts
@@ -16,6 +16,8 @@ export const frUpdateChannel = {
rollbackTitle: (v: string) => `Revenir à la version stable ${v}`,
rollbackBody: (v: string) =>
`Cette build est plus récente que la version stable ${v}. L’installer ramène Hermes à cette version.`,
+ heldBody: (v: string) =>
+ `Cette version est plus récente que la version stable ${v}, et vos sessions utilisent déjà son environnement de passerelle, que ${v} ne peut pas ouvrir. Hermes reste sur cette version jusqu’à la prochaine version stable.`,
rollbackAction: (v: string) => `Revenir à ${v}`,
allChanges: 'Voir toutes les modifications'
}
diff --git a/apps/desktop/src/i18n/ja_update_channel.ts b/apps/desktop/src/i18n/ja_update_channel.ts
index 44078718d08..a68fc735de3 100644
--- a/apps/desktop/src/i18n/ja_update_channel.ts
+++ b/apps/desktop/src/i18n/ja_update_channel.ts
@@ -16,6 +16,8 @@ export const jaUpdateChannel = {
rollbackTitle: (v: string) => `安定版リリース ${v} に戻す`,
rollbackBody: (v: string) =>
`このビルドは安定版リリース ${v} より新しいです。インストールすると Hermes はそのリリースに戻ります。`,
+ heldBody: (v: string) =>
+ `このビルドは安定版 ${v} より新しく、セッションはすでに ${v} では開けないゲートウェイ ランタイムを使っています。新しい安定版が出るまで、Hermes はこのビルドのままです。`,
rollbackAction: (v: string) => `${v} に戻す`,
allChanges: 'すべての変更を見る'
}
diff --git a/apps/desktop/src/i18n/ru_update_channel.ts b/apps/desktop/src/i18n/ru_update_channel.ts
index 730a1f62b83..f4d1e854694 100644
--- a/apps/desktop/src/i18n/ru_update_channel.ts
+++ b/apps/desktop/src/i18n/ru_update_channel.ts
@@ -15,6 +15,8 @@ export const ruUpdateChannel = {
latestRelease: (v: string) => `У вас последний стабильный релиз (${v}).`,
rollbackTitle: (v: string) => `Вернуться к стабильному релизу ${v}`,
rollbackBody: (v: string) => `Эта сборка новее стабильного релиза ${v}. Установка вернёт Hermes к этому релизу.`,
+ heldBody: (v: string) =>
+ `Эта сборка новее стабильного релиза ${v}, и ваши сессии уже используют её среду шлюза, которую ${v} не может открыть. Hermes останется на этой сборке до выхода нового стабильного релиза.`,
rollbackAction: (v: string) => `Вернуться к ${v}`,
allChanges: 'Все изменения'
}
diff --git a/apps/desktop/src/i18n/types_update_channel.ts b/apps/desktop/src/i18n/types_update_channel.ts
index 856c98749cc..48bb8681452 100644
--- a/apps/desktop/src/i18n/types_update_channel.ts
+++ b/apps/desktop/src/i18n/types_update_channel.ts
@@ -20,6 +20,8 @@ export interface UpdateChannelCopy {
rollbackTitle: (version: string) => string
/** Installing the older stable release moves the checkout back; says so plainly. */
rollbackBody: (version: string) => string
+ /** A stable release `hermes update` refuses: this install keeps its build until a newer release. */
+ heldBody: (version: string) => string
/** Updates overlay install button for that rollback. */
rollbackAction: (version: string) => string
/** Update dialog link to every change in a commit-line update. */
diff --git a/apps/desktop/src/i18n/zh-hant_update_channel.ts b/apps/desktop/src/i18n/zh-hant_update_channel.ts
index d5703d08d5a..42dde355b7b 100644
--- a/apps/desktop/src/i18n/zh-hant_update_channel.ts
+++ b/apps/desktop/src/i18n/zh-hant_update_channel.ts
@@ -14,6 +14,8 @@ export const zhHantUpdateChannel = {
latestRelease: (v: string) => `你正在使用最新的穩定版發布(${v})。`,
rollbackTitle: (v: string) => `回退到穩定版 ${v}`,
rollbackBody: (v: string) => `目前的組建比穩定版 ${v} 更新。安裝後 Hermes 將回退到該版本。`,
+ heldBody: (v: string) =>
+ `此版本比穩定版 ${v} 更新,且你的工作階段已在使用 ${v} 無法開啟的閘道執行環境。在更新的穩定版發布前,Hermes 會維持目前版本。`,
rollbackAction: (v: string) => `回退到 ${v}`,
allChanges: '查看全部變更'
}
diff --git a/apps/desktop/src/i18n/zh_update_channel.ts b/apps/desktop/src/i18n/zh_update_channel.ts
index 49a27ddd1e5..381c2b7363d 100644
--- a/apps/desktop/src/i18n/zh_update_channel.ts
+++ b/apps/desktop/src/i18n/zh_update_channel.ts
@@ -14,6 +14,8 @@ export const zhUpdateChannel = {
latestRelease: (v: string) => `你正在使用最新的稳定版发布(${v})。`,
rollbackTitle: (v: string) => `回退到稳定版 ${v}`,
rollbackBody: (v: string) => `当前构建比稳定版 ${v} 更新。安装后 Hermes 将回退到该版本。`,
+ heldBody: (v: string) =>
+ `此版本比稳定版 ${v} 更新,且你的会话已在使用 ${v} 无法打开的网关运行时。在更新的稳定版发布前,Hermes 将保持当前版本。`,
rollbackAction: (v: string) => `回退到 ${v}`,
allChanges: '查看全部更改'
}
diff --git a/hermes_cli/source_check.py b/hermes_cli/source_check.py
index 3eae1ecefcc..e2d992a29a1 100644
--- a/hermes_cli/source_check.py
+++ b/hermes_cli/source_check.py
@@ -288,7 +288,19 @@ def _write_cache(cache_file: Path, identity: dict, now: float, result: dict) ->
logger.debug("Could not cache source check: %s", exc)
-def _resolve_channel(result: dict, channel: str, co: _Checkout, *, forward_only: bool = False):
+def _update_refuses(co: _Checkout, target: str, home: Path) -> bool:
+ """The updater's downgrade refusal, asked read-only. An embedded checkout has no git to ask."""
+ if co.embedded:
+ return False
+ from hermes_cli.update_downgrade_guard import would_refuse
+
+ def git(*args: str) -> int:
+ result = _git_run(list(args), cwd=co.root, git=co.git, text=False, timeout=20)
+ return -1 if result is None else result.returncode
+ return would_refuse(co.root, target, home, git=git)
+
+
+def _resolve_channel(result: dict, channel: str, co: _Checkout, home: Path, *, forward_only: bool = False):
"""Resolve a release channel's target into ``result``; the SourceTarget, or None on error.
A target with a pinned commit is final; one without names a branch to follow instead.
@@ -313,6 +325,11 @@ def _resolve_channel(result: dict, channel: str, co: _Checkout, *, forward_only:
# not a new update. Local ancestry only; an unknown relation stays an update.
result["rollback"] = bool(co.head and co.head != target and not co.embedded and _git_ok(
["merge-base", "--is-ancestor", target, co.head], cwd=co.root, git=co.git))
+ if result["updateAvailable"] and _update_refuses(co, target, home):
+ # `hermes update` refuses this release (it predates the gateway runtime these session
+ # stores use), so it is held, not offered. Covers releases off this checkout's history
+ # too, which the ancestry-only rollback test cannot see.
+ result.update(updateAvailable=False, behind=0, held="downgrade")
if source_target.retired:
result["retirement"] = {"destination": source_target.channel, "sourceOnly": True}
return source_target
@@ -437,7 +454,7 @@ def check_for_updates(*, install_root: Path | None = None, home: Path | None = N
else:
result["branch"] = selected_branch
identity = {"root": str(root), "home": str(home), "head": co.head, "origin": co.origin, "branch": selected_branch,
- "channel": channel, "embedded": embedded, "branchOverride": branch is not None, "channelProtocol": 1,
+ "channel": channel, "embedded": embedded, "branchOverride": branch is not None, "channelProtocol": 2,
"forwardOnly": forward_only}
cache_file = Path(cache_path) if cache_path is not None else home / "source-checks" / f"{install_id(root)}.json"
now = time.time()
@@ -449,7 +466,7 @@ def check_for_updates(*, install_root: Path | None = None, home: Path | None = N
if not _is_full_sha(co.head):
result.update(error="head-unavailable", message="Could not read the installed revision.")
elif branch is None:
- source_target = _resolve_channel(result, channel, co, forward_only=forward_only)
+ source_target = _resolve_channel(result, channel, co, home, forward_only=forward_only)
if source_target is not None and not source_target.commit:
# The record supplies a default, not permission to leave the user's branch.
selected_branch = configured_branch or _checked_out_branch(co.current_branch, source_target.branch)
diff --git a/hermes_cli/update_cmd_check.py b/hermes_cli/update_cmd_check.py
index 5143ffe0c28..f15ed5be733 100644
--- a/hermes_cli/update_cmd_check.py
+++ b/hermes_cli/update_cmd_check.py
@@ -62,6 +62,20 @@ def report_pack_tidy(root: Path) -> None:
print(f" (git cleanup stopped at its {TIDY_BUDGET_SECONDS}s limit; the next update continues it)")
+def _refuses(git_cmd: list[str], root: Path, target: str) -> bool:
+ """`hermes update` would refuse ``target`` (see update_downgrade_guard), so --check must not offer it."""
+ from hermes_cli.update_downgrade_guard import would_refuse
+ from hermes_cli._subprocess_compat import NO_LAZY_FETCH_ENV, noninteractive_git_env
+
+ def git(*args: str) -> int:
+ try:
+ return _git(git_cmd, root, list(args), env={**noninteractive_git_env(), **NO_LAZY_FETCH_ENV},
+ timeout=20).returncode
+ except (OSError, subprocess.SubprocessError):
+ return -1
+ return would_refuse(root, target, git=git)
+
+
def channel_compare_branch(selected_channel: str, git_cmd: list[str], root: Path) -> str | None:
"""Report a release-pinned channel's verdict, or return the branch to compare against.
@@ -92,6 +106,10 @@ def channel_compare_branch(selected_channel: str, git_cmd: list[str], root: Path
print(f"→ This checkout is newer than the selected release: {target.label}.")
print(" `hermes update` moves it back to that release"
" (`hermes update --set-channel main` follows every commit).")
+ elif _refuses(git_cmd, root, target.commit):
+ print(f"→ Holding at this build: {target.label} predates the gateway runtime your sessions use.")
+ print(" `hermes update` will not move back to it; the next stable release that includes the"
+ " runtime installs normally (`hermes update --set-channel main` follows every commit).")
else:
print(f"→ Selected release available: {target.label}")
print(" Run `hermes update` to install it.")
diff --git a/hermes_cli/update_downgrade_guard.py b/hermes_cli/update_downgrade_guard.py
index e9dcfd5fbc8..3812b99c0e3 100644
--- a/hermes_cli/update_downgrade_guard.py
+++ b/hermes_cli/update_downgrade_guard.py
@@ -11,8 +11,10 @@ reason to refuse, and a target that descends from the running commit is a forwar
from __future__ import annotations
import sqlite3
+from collections.abc import Callable
from contextlib import closing
from pathlib import Path
+from typing import Optional
# The runtime ledger DDL: a target whose state-store modules lack it predates the cutover.
_RUNTIME_SCHEMA_MARKER = "CREATE TABLE IF NOT EXISTS session_admissions"
@@ -21,10 +23,7 @@ _LEDGER_PROBE = ("SELECT EXISTS(SELECT 1 FROM session_admissions) "
_DOCS = "https://hermes-agent.nousresearch.com/docs/getting-started/updating#rolling-back-to-an-older-release"
-def target_predates_runtime(git_cmd, root: Path, target_ref: str) -> bool:
- """True when ``target_ref`` does not descend from HEAD and none of its ``hermes_state*.py`` files
- defines the runtime ledger. The pathspec keeps a blobless partial clone from fetching the whole
- tree. Any git failure proves nothing (False)."""
+def _updater_git(git_cmd, root: Path) -> Callable[..., int]:
import subprocess
from hermes_cli.update_custody import run_git
@@ -34,7 +33,16 @@ def target_predates_runtime(git_cmd, root: Path, target_ref: str) -> bool:
return run_git(git_cmd, list(args), cwd=str(root), capture_output=True, timeout=120).returncode
except (OSError, subprocess.SubprocessError):
return -1
+ return git
+
+def target_predates_runtime(git_cmd, root: Path, target_ref: str, *,
+ git: Optional[Callable[..., int]] = None) -> bool:
+ """True when ``target_ref`` does not descend from HEAD and none of its ``hermes_state*.py`` files
+ defines the runtime ledger. The pathspec keeps a blobless partial clone from fetching the whole
+ tree. Any git failure proves nothing (False). ``git`` runs one git command and returns its exit
+ code; the update check passes its own read-only probe."""
+ git = git or _updater_git(git_cmd, root)
if git("merge-base", "--is-ancestor", "HEAD", target_ref) == 0:
return False # forward update: whatever the target's schema, it was written knowing this one
if git("cat-file", "-e", f"{target_ref}^{{commit}}") != 0:
@@ -82,15 +90,25 @@ def _named_profile(home: Path) -> str:
return resolved.name if named else ""
-def downgrade_refusal(git_cmd, root: Path, target_ref: str, home: Path | None = None) -> str | None:
- """Why the update must not move to ``target_ref``, or ``None``: refuses only a pre-runtime target
- while this profile's or a sibling profile's state.db holds runtime ledger rows."""
+def _ledgered_profiles(home: Path | None) -> list[tuple[str, Path]]:
from hermes_cli.backup import _sibling_profile_homes
from hermes_constants import get_hermes_home
home = Path(home or get_hermes_home())
profiles = [(_named_profile(home), home), *_sibling_profile_homes(home)]
- ledgered = [(name, h) for name, h in profiles if _has_ledger_rows(h / "state.db")]
+ return [(name, h) for name, h in profiles if _has_ledger_rows(h / "state.db")]
+
+
+def would_refuse(root: Path, target_ref: str, home: Path | None = None, *, git: Callable[..., int]) -> bool:
+ """Whether ``hermes update`` would refuse ``target_ref`` here: the update check's read-only twin of
+ :func:`downgrade_refusal`, so a release the updater refuses is never offered as an update."""
+ return bool(_ledgered_profiles(home)) and target_predates_runtime(None, root, target_ref, git=git)
+
+
+def downgrade_refusal(git_cmd, root: Path, target_ref: str, home: Path | None = None) -> str | None:
+ """Why the update must not move to ``target_ref``, or ``None``: refuses only a pre-runtime target
+ while this profile's or a sibling profile's state.db holds runtime ledger rows."""
+ ledgered = _ledgered_profiles(home)
if not ledgered or not target_predates_runtime(git_cmd, root, target_ref):
return None
lines = [f"✗ Refusing to move this install to {target_ref[:12]}: that release predates the gateway runtime "
diff --git a/tests/hermes_cli/test_source_check.py b/tests/hermes_cli/test_source_check.py
index d1f3c6abcbd..aefea2f24dc 100644
--- a/tests/hermes_cli/test_source_check.py
+++ b/tests/hermes_cli/test_source_check.py
@@ -589,3 +589,39 @@ def test_stable_release_the_checkout_already_contains_is_a_rollback(installation
assert status.get("targetSha") == shas[release], status
assert status["updateAvailable"] is True
assert status["rollback"] is rollback
+
+
[email protected]("ledgered", [True, False])
+def test_stable_release_the_updater_refuses_is_held_not_offered(installation, tmp_path, monkeypatch, ledgered):
+ """A release off this checkout's history that predates the gateway runtime is held while a store
+ has runtime history (#139099): `hermes update` refuses it, so the check must not offer it."""
+ from hermes_cli.source_check import check_for_updates
+ from tests.hermes_cli.test_update_downgrade_guard import _ledgered_store
+
+ root, _linked, home, base, _head, responses, _requests, git = installation
+ monkeypatch.setattr("hermes_cli.backup._sibling_profile_homes", lambda h: [])
+ (root / "hermes_state_common.py").write_text("SCHEMA_SQL = 'CREATE TABLE IF NOT EXISTS session_admissions (seq)'\n")
+ git("add", "hermes_state_common.py")
+ git("commit", "-q", "-m", "gateway runtime")
+ git("checkout", "-q", "-b", "release-line", base)
+ (root / "hermes_state_common.py").write_text("SCHEMA_SQL = 'CREATE TABLE IF NOT EXISTS sessions (id)'\n")
+ git("add", "hermes_state_common.py")
+ git("commit", "-q", "-m", "release from the older line")
+ release = git("rev-parse", "HEAD")
+ bare = tmp_path / "origin.git"
+ git("clone", "-q", "--bare", str(root), str(bare), cwd=tmp_path)
+ git("tag", "v1.2.3", release, cwd=bare)
+ git("remote", "set-url", "origin", str(bare))
+ git("checkout", "-q", "main")
+ if ledgered:
+ _ledgered_store(home)
+ api = "/repos/NousResearch/hermes-agent"
+ responses[f"{api}/releases/latest"] = (200, {"draft": False, "prerelease": False, "tag_name": "v1.2.3"})
+ responses[f"{api}/commits/v1.2.3"] = (200, {"sha": release})
+
+ status = check_for_updates(install_root=root, home=home, channel="stable", force=True)
+
+ assert status.get("targetSha") == release, status
+ assert status["rollback"] is False # off-history: the ancestry test alone cannot see it
+ assert status["updateAvailable"] is not ledgered
+ assert status.get("held") == ("downgrade" if ledgered else None)
diff --git a/tests/hermes_cli/test_update_downgrade_guard.py b/tests/hermes_cli/test_update_downgrade_guard.py
index 43d82338b39..86a7a68efc4 100644
--- a/tests/hermes_cli/test_update_downgrade_guard.py
+++ b/tests/hermes_cli/test_update_downgrade_guard.py
@@ -95,3 +95,31 @@ def test_forward_updates_and_stores_without_ledger_rows_are_never_refused(repo,
assert guard.downgrade_refusal(["git"], repo, head, home=ledgered) is None
_git(repo, "checkout", "-q", "--detach", old) # running the old release: the newer target is forward
assert guard.downgrade_refusal(["git"], repo, head, home=ledgered) is None
+
+
+def test_check_holds_a_release_off_this_history_that_update_would_refuse(repo, tmp_path, monkeypatch, capsys):
+ """`hermes update --check` must not say "Selected release available" for a release the update then
+ refuses (#139099). A release cut beside this checkout's history is not a rollback by ancestry."""
+ from types import SimpleNamespace
+
+ from hermes_cli import source_releases, update_cmd_check
+
+ home = tmp_path / "home"
+ monkeypatch.setenv("HERMES_HOME", str(home))
+ monkeypatch.setattr("hermes_cli.backup._sibling_profile_homes", lambda h: [])
+ _git(repo, "checkout", "-q", "-b", "release-line", "old-release")
+ (repo / "notes.txt").write_text("release fix\n")
+ _git(repo, "add", "notes.txt")
+ _git(repo, "commit", "-qm", "release from the older line")
+ release = _git(repo, "rev-parse", "HEAD")
+ _git(repo, "checkout", "-q", "main")
+ target = SimpleNamespace(commit=release, retired=False, ahead=False, label="v1.2.3", branch=None)
+ monkeypatch.setattr(source_releases, "resolve_source_target", lambda *a, **k: target)
+
+ update_cmd_check.channel_compare_branch("stable", ["git"], repo)
+ assert "Selected release available" in capsys.readouterr().out # no runtime history yet: a real update
+
+ _ledgered_store(home)
+ update_cmd_check.channel_compare_branch("stable", ["git"], repo)
+ out = capsys.readouterr().out
+ assert "Holding at this build" in out and "Selected release available" not in out