fix(update-check): recover the real behind-count via the GitHub compare API

The honesty half (no fabricated counts) leaves shallow installs permanently
count-less. The compare API knows the full graph regardless of local clone
depth: GET /repos/<o>/<r>/compare/<current>...<target> returns ahead_by —
exactly the behind count the shallow boundary lost.

- hermes_cli/banner.py: _github_compare_behind() (bounded, unauthenticated,
  best-effort); wired into _check_via_rev and the shallow branch of
  _check_via_local_git. ahead_by==0 with differing tips = local-ahead => 0.
- hermes_cli/update_cmd.py: hermes update --check shallow path prints the
  exact count when recoverable, presence-only wording otherwise.
- apps/desktop/electron/update-count.ts: compareApiUrl() +
  parseCompareBehindCount() pure helpers; main.ts fetches the count when
  resolveBehindCount() returns null, and the SSH-official passive path stops
  fabricating behind:1 (uses compare API + updateAvailable flag).
- apps/desktop/src/lib/version-status.ts: updateAvailable now applies to the
  client target too, so a shallow desktop install shows '(update)' instead of
  nothing (or the old frozen '(+1)').

Fixes #84591; CLI siblings of #78253 / #53479 behavior.

E2E: live compare API returned 61/62 for real 61/62-commit gaps and 0 for the
reversed (local-ahead) pair; real shallow-clone fixture (depth-1 clone +
depth-1 fetch, merge-base broken) recovers the exact count with the API and
falls back to the honest sentinel offline.
This commit is contained in:
Teknium
2026-08-14 11:08:14 -07:00
parent 3dbdea8b8b
commit 9442a718da
9 changed files with 472 additions and 12 deletions
+75 -3
View File
@@ -206,7 +206,7 @@ import {
} from './ssh-connection'
import { createStreamThrottle } from './stream-throttle'
import { nativeOverlayWidth as computeNativeOverlayWidth, macTitleBarOverlayHeight } from './titlebar-overlay-width'
import { resolveBehindCount, resolveCommitLogSelection, shouldCountCommits } from './update-count'
import { compareApiUrl, parseCompareBehindCount, resolveBehindCount, resolveCommitLogSelection, shouldCountCommits } from './update-count'
import { waitForUpdateClearance } from './update-gate'
import { readLiveUpdateMarker, updateHandoffConflict, writeUpdateMarker } from './update-marker'
import { isOfficialSshRemote, OFFICIAL_REPO_HTTPS_URL } from './update-remote'
@@ -2574,11 +2574,21 @@ async function checkUpdates() {
}
}
// Passive SSH-official checks only know tip SHAs (ls-remote) — never
// fabricate a "1 commit behind". Recover the exact count via the GitHub
// compare API when possible; otherwise behind stays null ("update
// available, count unknown") and updateAvailable carries the signal.
const upToDate = Boolean(currentSha && currentSha === targetSha)
const sshBehind = upToDate
? 0
: await fetchCompareBehindCount({ currentSha, originUrl: OFFICIAL_REPO_HTTPS_URL, targetSha })
return {
supported: true,
branch,
currentBranch,
behind: currentSha && currentSha === targetSha ? 0 : 1,
behind: sshBehind,
updateAvailable: !upToDate,
currentSha,
targetSha,
commits: [],
@@ -2624,7 +2634,7 @@ async function checkUpdates() {
currentSha !== targetSha &&
(await runGit(['merge-base', '--is-ancestor', `origin/${branch}`, 'HEAD'], { cwd: updateRoot })).code === 0
const behind = resolveBehindCount({
let behind = resolveBehindCount({
countStr,
currentSha,
targetSha,
@@ -2632,6 +2642,14 @@ async function checkUpdates() {
targetIsAncestorOfHead
})
// Recover the exact count a shallow clone can't compute: the GitHub compare
// API knows the full graph regardless of local clone depth. Best-effort —
// offline, rate-limited, or non-GitHub origins keep the honest null
// ("update available", no fabricated number).
if (behind === null) {
behind = await fetchCompareBehindCount({ currentSha, originUrl, targetSha })
}
// behind === null means "update available, exact count unknown" (shallow
// clone): still list what origin offers — resolveCommitLogSelection keeps
// the shallow log to the fetched tip so the range walk can't enumerate the
@@ -2653,6 +2671,60 @@ async function checkUpdates() {
}
}
// Best-effort exact behind-count for graphs the local clone can't measure.
// Delegates URL building + response parsing to update-count.ts (pure, unit
// tested); this wrapper only does the bounded network call. Any failure —
// offline, 4xx/5xx, rate limit, shape surprise — returns null so callers keep
// the honest "update available, count unknown" state.
async function fetchCompareBehindCount({ currentSha, originUrl, targetSha }) {
const url = compareApiUrl({ currentSha, originUrl, targetSha })
if (!url) {
return null
}
try {
const payload = await new Promise((resolve, reject) => {
const req = https.get(
url,
{
headers: {
Accept: 'application/vnd.github+json',
// GitHub requires a UA on api.github.com; requests without one 403.
'User-Agent': 'hermes-desktop-update-check'
},
timeout: 10_000
},
res => {
const chunks = []
res.on('error', reject)
res.on('data', chunk => chunks.push(chunk))
res.on('end', () => {
if ((res.statusCode || 500) >= 400) {
reject(new Error(`compare API ${res.statusCode}`))
return
}
try {
resolve(JSON.parse(Buffer.concat(chunks).toString('utf8')))
} catch (error) {
reject(error)
}
})
}
)
req.on('timeout', () => req.destroy(new Error('compare API timeout')))
req.on('error', reject)
})
return parseCompareBehindCount(payload)
} catch {
return null
}
}
async function readCommitLog(cwd, branch, isShallow) {
const SEP = '\x1f'
const REC = '\x1e'
+50 -1
View File
@@ -6,7 +6,7 @@ import path from 'node:path'
import { test } from 'vitest'
import { resolveBehindCount, resolveCommitLogSelection, shouldCountCommits } from './update-count'
import { compareApiUrl, parseCompareBehindCount, resolveBehindCount, resolveCommitLogSelection, shouldCountCommits } from './update-count'
function createTempGitRepo() {
const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'hermes-update-count-'))
@@ -245,3 +245,52 @@ test('skipped-count path resolves via SHA compare, never via empty countStr', ()
0
)
})
// --- compare-API recovery: the accuracy half of the class fix (#84591) ---
const SHA_A = 'a'.repeat(40)
const SHA_B = 'b'.repeat(40)
test('compareApiUrl builds the GitHub compare URL for HTTPS origins', () => {
assert.equal(
compareApiUrl({
currentSha: SHA_A,
originUrl: 'https://github.com/NousResearch/hermes-agent.git',
targetSha: SHA_B
}),
`https://api.github.com/repos/NousResearch/hermes-agent/compare/${SHA_A}...${SHA_B}`
)
})
test('compareApiUrl handles SSH origin forms', () => {
for (const originUrl of [
'git@github.com:NousResearch/hermes-agent.git',
'ssh://git@github.com/NousResearch/hermes-agent.git',
'git@github.com:NousResearch/hermes-agent'
]) {
assert.equal(
compareApiUrl({ currentSha: SHA_A, originUrl, targetSha: SHA_B }),
`https://api.github.com/repos/NousResearch/hermes-agent/compare/${SHA_A}...${SHA_B}`
)
}
})
test('compareApiUrl refuses non-GitHub remotes and partial SHAs', () => {
assert.equal(compareApiUrl({ currentSha: SHA_A, originUrl: 'https://gitlab.com/x/y.git', targetSha: SHA_B }), null)
assert.equal(compareApiUrl({ currentSha: 'abc123', originUrl: 'https://github.com/x/y.git', targetSha: SHA_B }), null)
assert.equal(compareApiUrl({ currentSha: SHA_A, originUrl: '', targetSha: SHA_B }), null)
})
test('parseCompareBehindCount returns ahead_by (the behind count)', () => {
assert.equal(parseCompareBehindCount({ ahead_by: 61, status: 'ahead' }), 61)
assert.equal(parseCompareBehindCount({ ahead_by: 0, status: 'behind' }), 0)
})
test('parseCompareBehindCount rejects malformed payloads', () => {
assert.equal(parseCompareBehindCount(null), null)
assert.equal(parseCompareBehindCount({}), null)
assert.equal(parseCompareBehindCount({ ahead_by: -2 }), null)
assert.equal(parseCompareBehindCount({ ahead_by: '61' }), null)
assert.equal(parseCompareBehindCount({ ahead_by: 1.5 }), null)
assert.equal(parseCompareBehindCount([]), null)
})
+52 -1
View File
@@ -37,4 +37,55 @@ function resolveCommitLogSelection({ branch, isShallow }) {
return isShallow ? { limit: 1, revision: remote } : { limit: 40, revision: `HEAD..${remote}` }
}
export { resolveBehindCount, resolveCommitLogSelection, shouldCountCommits }
// When the local graph can't count (behind === null), the GitHub compare API
// still can: `GET /repos/<owner>/<repo>/compare/<current>...<target>` returns
// `ahead_by` — how many commits the remote tip is ahead of the local HEAD,
// i.e. exactly the behind count the shallow clone lost. Unauthenticated, no
// clone depth required. Pure URL builder + response parser here; the network
// call lives with the caller.
function compareApiUrl({ currentSha, originUrl, targetSha }) {
const sha = /^[0-9a-f]{40}$/i
if (!sha.test(currentSha || '') || !sha.test(targetSha || '')) {
return null
}
// Only GitHub remotes have a compare API. Reuse the canonical form the
// official-remote check produces: `github.com/<owner>/<repo>`.
const canonical = canonicalRemoteForCompare(originUrl)
if (!canonical) {
return null
}
return `https://api.github.com/repos/${canonical}/compare/${currentSha}...${targetSha}`
}
function canonicalRemoteForCompare(originUrl) {
const value = String(originUrl || '').trim()
const match =
/^git@github\.com:([^/]+\/[^/]+?)(?:\.git)?\/?$/i.exec(value) ||
/^(?:ssh:\/\/git@|https:\/\/|http:\/\/)github\.com\/([^/]+\/[^/]+?)(?:\.git)?\/?$/i.exec(value)
return match ? match[1] : null
}
// `ahead_by` counts target commits not reachable from current — the behind
// count. `status` is "ahead" / "behind" / "diverged" / "identical" relative to
// current...target; any shape surprise returns null so the caller keeps the
// honest "update available" fallback instead of trusting a partial answer.
function parseCompareBehindCount(payload) {
if (!payload || typeof payload !== 'object') {
return null
}
const ahead = payload.ahead_by
if (typeof ahead !== 'number' || !Number.isInteger(ahead) || ahead < 0) {
return null
}
return ahead
}
export { compareApiUrl, parseCompareBehindCount, resolveBehindCount, resolveCommitLogSelection, shouldCountCommits }
@@ -282,6 +282,7 @@ export function useStatusbarItems({
restarting: updateApply.stage === 'restart',
sha: updateStatus?.currentSha?.slice(0, 7) ?? null,
target: 'client',
updateAvailable: updateStatus?.updateAvailable,
version: desktopVersion?.appVersion
})
@@ -30,6 +30,18 @@ describe('resolveVersionStatus', () => {
expect(status.tooltip).toContain('12 commits behind main')
})
// FAIL-BEFORE (#84591 class): a shallow install reports behind:null +
// updateAvailable. The client target ignored updateAvailable entirely, so
// the statusbar showed no update at all — and further back, the fabricated
// behind:1 rendered a frozen "(+1)" while the real distance grew to 61.
it('shows a count-free update hint when the client count is unknown', () => {
const status = client({ behind: 0, updateAvailable: true, version: '0.4.2' })
expect(status.label).toBe(`v0.4.2 (${copy.update})`)
expect(status.label).not.toContain('+1')
expect(status.hasUpdate).toBe(true)
})
it('names the client as one of two versions in remote mode', () => {
expect(client({ remote: true, version: '0.4.2' }).label).toBe('client v0.4.2')
})
+7 -2
View File
@@ -39,7 +39,7 @@ export interface VersionStatusInput {
/** Client only: short commit sha of the running build. */
sha?: null | string
target: UpdateTarget
/** Backend only: an update the commit count can't express (pip installs). */
/** An update the commit count can't express (shallow clones, pip installs). */
updateAvailable?: boolean
version?: null | string
}
@@ -70,7 +70,12 @@ export function resolveVersionStatus({
}: VersionStatusInput): VersionStatusResult {
const client = target === 'client'
const busy = applying || restarting
const available = behind > 0 || (!client && !!updateAvailable)
// updateAvailable covers every "behind but uncountable" shape: shallow
// installer clones (behind === null upstream, coalesced to 0 by callers),
// SSH-official presence-only checks, and pip installs. It applies to BOTH
// targets — the client statusbar item is how a shallow desktop install
// learns it's stale at all.
const available = behind > 0 || !!updateAvailable
// A client with no version still identifies itself by sha; a backend can't.
const named = version ?? (client ? sha : null) ?? copy.unknown
+62 -2
View File
@@ -193,6 +193,52 @@ def _git_stdout(args: list[str], *, cwd: Path, timeout: int = 5) -> Optional[str
return (result.stdout or "").strip()
def _github_compare_behind(current_rev: str, target_rev: str) -> Optional[int]:
"""Exact behind-count via the GitHub compare API for uncountable graphs.
Shallow installer clones and ls-remote-only probes know the two tip SHAs
but have no local history to run ``rev-list --count`` across. GitHub's
``GET /repos/<owner>/<repo>/compare/<current>...<target>`` knows the full
graph regardless of local clone depth and returns ``ahead_by`` — exactly
the behind count the local graph lost. Unauthenticated, bounded, and
best-effort: any failure (offline, rate limit, diverged/unknown SHAs)
returns None so callers keep the honest UPDATE_AVAILABLE_NO_COUNT.
"""
if not (_is_full_sha(current_rev) and _is_full_sha(target_rev)):
return None
url = (
"https://api.github.com/repos/nousresearch/hermes-agent/"
f"compare/{current_rev}...{target_rev}"
)
try:
import urllib.request
req = urllib.request.Request(
url,
headers={
"Accept": "application/vnd.github+json",
# api.github.com 403s requests without a User-Agent.
"User-Agent": "hermes-cli-update-check",
},
)
with urllib.request.urlopen(req, timeout=10) as resp:
payload = json.loads(resp.read().decode("utf-8"))
except Exception:
return None
ahead = payload.get("ahead_by") if isinstance(payload, dict) else None
if isinstance(ahead, int) and not isinstance(ahead, bool) and ahead >= 0:
return ahead
return None
def _is_full_sha(value: Optional[str]) -> bool:
return (
isinstance(value, str)
and len(value) == 40
and all(c in "0123456789abcdefABCDEF" for c in value)
)
def _check_via_rev(local_rev: str) -> Optional[int]:
"""Compare an embedded git revision to upstream main via ls-remote.
@@ -212,7 +258,14 @@ def _check_via_rev(local_rev: str) -> Optional[int]:
upstream_rev = result.stdout.split()[0]
if not upstream_rev:
return None
return 0 if upstream_rev == local_rev else UPDATE_AVAILABLE_NO_COUNT
if upstream_rev == local_rev:
return 0
# Behind, but ls-remote only knows tip SHAs. Try to recover the exact
# count from the GitHub compare API before falling back to the sentinel.
# ahead_by == 0 with differing tips means the remote tip is reachable from
# our HEAD — a local-ahead checkout, i.e. NOT behind.
counted = _github_compare_behind(local_rev, upstream_rev)
return counted if counted is not None else UPDATE_AVAILABLE_NO_COUNT
def _check_via_local_git(repo_dir: Path) -> Optional[int]:
@@ -275,7 +328,14 @@ def _check_via_local_git(repo_dir: Path) -> Optional[int]:
)
if not head_rev or not target_rev:
return None
return 0 if head_rev == target_rev else UPDATE_AVAILABLE_NO_COUNT
if head_rev == target_rev:
return 0
# Tips differ but the shallow boundary hides the history between them.
# Recover the exact count from the GitHub compare API when possible
# (ahead_by == 0 means local-ahead ⇒ up to date); otherwise report the
# honest "update available, count unknown" sentinel.
counted = _github_compare_behind(head_rev, target_rev)
return counted if counted is not None else UPDATE_AVAILABLE_NO_COUNT
try:
result = subprocess.run(
+15 -3
View File
@@ -2419,8 +2419,10 @@ def _cmd_update_check(branch: str = "main", *, branch_explicit: bool = False):
sys.exit(1)
if is_shallow:
# No history to count across the shallow boundary. Compare tip SHAs and
# report presence-only (mirrors the banner's _check_via_local_git).
# No history to count across the shallow boundary. Compare tip SHAs
# (mirrors the banner's _check_via_local_git), then try to recover the
# exact count via the GitHub compare API — the remote graph is complete
# even when the local one is truncated.
head_sha = subprocess.run(
git_cmd + ["rev-parse", "HEAD"],
cwd=_m().PROJECT_ROOT, capture_output=True, text=True, encoding="utf-8", errors="replace",
@@ -2432,9 +2434,19 @@ def _cmd_update_check(branch: str = "main", *, branch_explicit: bool = False):
if head_sha and target_sha and head_sha == target_sha:
print("✓ Already up to date.")
else:
print(f"⚕ Update available (behind {compare_branch}).")
from hermes_cli.banner import _github_compare_behind
from hermes_cli.config import recommended_update_command
counted = _github_compare_behind(head_sha, target_sha)
if counted == 0:
# Local commits on top of the remote tip — not behind.
print("✓ Already up to date.")
return
if counted is not None:
commits_word = "commit" if counted == 1 else "commits"
print(f"⚕ Update available: {counted} {commits_word} behind {compare_branch}.")
else:
print(f"⚕ Update available (behind {compare_branch}).")
print(f" Run '{recommended_update_command()}' to install.")
return
@@ -0,0 +1,198 @@
"""Behind-count recovery via the GitHub compare API (banner.py).
The class of bug: any code path that knows two tip SHAs but has no local
history to count across (shallow installer clones, ls-remote-only probes)
used to fabricate a count of ``1`` — the UI then rendered "+1" / "1 commit
behind" forever while the real distance grew (#84591: 61 commits behind,
indicator said 1). The fix has two halves:
1. Honesty: never fabricate a number. Uncountable = UPDATE_AVAILABLE_NO_COUNT
sentinel (CLI) / null (desktop), rendered as a generic "update available".
2. Accuracy: recover the exact count via GitHub's compare API, which knows
the full graph regardless of local clone depth.
"""
import io
import json
from pathlib import Path
from unittest.mock import MagicMock, patch
import pytest
import hermes_cli.banner as banner
SHA_A = "a" * 40
SHA_B = "b" * 40
def _compare_payload(ahead):
return io.BytesIO(json.dumps({"ahead_by": ahead, "status": "ahead"}).encode())
class _FakeResponse:
def __init__(self, payload: bytes):
self._payload = payload
def read(self):
return self._payload
def __enter__(self):
return self
def __exit__(self, *exc):
return False
def _patch_urlopen(payload):
return patch(
"urllib.request.urlopen",
return_value=_FakeResponse(json.dumps(payload).encode()),
)
# ---------------------------------------------------------------------------
# _github_compare_behind
# ---------------------------------------------------------------------------
def test_compare_behind_returns_ahead_by():
with _patch_urlopen({"ahead_by": 61, "status": "ahead"}):
assert banner._github_compare_behind(SHA_A, SHA_B) == 61
def test_compare_behind_zero_means_local_ahead():
with _patch_urlopen({"ahead_by": 0, "status": "behind"}):
assert banner._github_compare_behind(SHA_A, SHA_B) == 0
def test_compare_behind_rejects_short_shas_without_network():
with patch("urllib.request.urlopen") as mock_open:
assert banner._github_compare_behind("abc123", SHA_B) is None
assert banner._github_compare_behind(SHA_A, "") is None
assert banner._github_compare_behind(None, SHA_B) is None
mock_open.assert_not_called()
def test_compare_behind_network_failure_returns_none():
with patch("urllib.request.urlopen", side_effect=OSError("offline")):
assert banner._github_compare_behind(SHA_A, SHA_B) is None
@pytest.mark.parametrize(
"payload",
[
{"status": "diverged"}, # no ahead_by
{"ahead_by": -3}, # negative
{"ahead_by": "12"}, # wrong type
{"ahead_by": True}, # bool masquerading as int
[], # wrong shape
],
)
def test_compare_behind_rejects_malformed_payloads(payload):
with _patch_urlopen(payload):
assert banner._github_compare_behind(SHA_A, SHA_B) is None
# ---------------------------------------------------------------------------
# _check_via_rev: sentinel replaced by exact count when compare API answers
# ---------------------------------------------------------------------------
def _ls_remote_result(sha):
return MagicMock(returncode=0, stdout=f"{sha}\trefs/heads/main\n")
def test_check_via_rev_recovers_exact_count():
with patch(
"hermes_cli.banner.subprocess.run", return_value=_ls_remote_result(SHA_B)
), patch.object(banner, "_github_compare_behind", return_value=61) as compare:
assert banner._check_via_rev(SHA_A) == 61
compare.assert_called_once_with(SHA_A, SHA_B)
def test_check_via_rev_falls_back_to_sentinel_offline():
"""FAIL-BEFORE (class): this path returned a fabricated 1 via callers."""
with patch(
"hermes_cli.banner.subprocess.run", return_value=_ls_remote_result(SHA_B)
), patch.object(banner, "_github_compare_behind", return_value=None):
assert banner._check_via_rev(SHA_A) == banner.UPDATE_AVAILABLE_NO_COUNT
def test_check_via_rev_up_to_date_short_circuits_compare():
with patch(
"hermes_cli.banner.subprocess.run", return_value=_ls_remote_result(SHA_A)
), patch.object(banner, "_github_compare_behind") as compare:
assert banner._check_via_rev(SHA_A) == 0
compare.assert_not_called()
def test_check_via_rev_local_ahead_reports_up_to_date():
"""ahead_by == 0 with differing tips = local commits on top, not behind."""
with patch(
"hermes_cli.banner.subprocess.run", return_value=_ls_remote_result(SHA_B)
), patch.object(banner, "_github_compare_behind", return_value=0):
assert banner._check_via_rev(SHA_A) == 0
# ---------------------------------------------------------------------------
# _check_via_local_git: shallow path recovers the exact count
# ---------------------------------------------------------------------------
def _shallow_git(head_sha, fetch_head_sha):
def fake_run(cmd, **kwargs):
if cmd[:4] == ["git", "remote", "get-url", "origin"]:
return MagicMock(
returncode=0,
stdout="https://github.com/NousResearch/hermes-agent.git\n",
)
if cmd[:3] == ["git", "rev-parse", "--is-shallow-repository"]:
return MagicMock(returncode=0, stdout="true\n")
if cmd[:2] == ["git", "fetch"]:
return MagicMock(returncode=0, stdout="")
if cmd[:3] == ["git", "rev-parse", "HEAD"]:
return MagicMock(returncode=0, stdout=f"{head_sha}\n")
if cmd[:3] == ["git", "rev-parse", "FETCH_HEAD"]:
return MagicMock(returncode=0, stdout=f"{fetch_head_sha}\n")
raise AssertionError(f"unexpected git command: {cmd!r}")
return fake_run
def test_shallow_checkout_recovers_exact_count(tmp_path):
"""The #84591 shape: shallow boundary kills merge-base, tips differ.
FAIL-BEFORE (class): reported UPDATE_AVAILABLE_NO_COUNT (or, further back,
a fabricated 1) even though the compare API could count exactly.
"""
repo_dir = tmp_path / "hermes-agent"
repo_dir.mkdir()
with patch(
"hermes_cli.banner.subprocess.run", side_effect=_shallow_git(SHA_A, SHA_B)
), patch.object(banner, "_github_compare_behind", return_value=61):
assert banner._check_via_local_git(repo_dir) == 61
def test_shallow_checkout_offline_keeps_honest_sentinel(tmp_path):
repo_dir = tmp_path / "hermes-agent"
repo_dir.mkdir()
with patch(
"hermes_cli.banner.subprocess.run", side_effect=_shallow_git(SHA_A, SHA_B)
), patch.object(banner, "_github_compare_behind", return_value=None):
assert (
banner._check_via_local_git(repo_dir)
== banner.UPDATE_AVAILABLE_NO_COUNT
)
def test_shallow_checkout_equal_tips_up_to_date_without_compare(tmp_path):
repo_dir = tmp_path / "hermes-agent"
repo_dir.mkdir()
with patch(
"hermes_cli.banner.subprocess.run", side_effect=_shallow_git(SHA_A, SHA_A)
), patch.object(banner, "_github_compare_behind") as compare:
assert banner._check_via_local_git(repo_dir) == 0
compare.assert_not_called()