Skip to content

The agent that grows with you

fix(desktop): the version refresh never blocks the main thread on a historical install

Tekniumcef417201fbe
diff --git a/apps/desktop/electron/local-runtime-version.test.ts b/apps/desktop/electron/local-runtime-version.test.ts
index 190c1c77a3a..9bbd8b9ec8a 100644
--- a/apps/desktop/electron/local-runtime-version.test.ts
+++ b/apps/desktop/electron/local-runtime-version.test.ts
@@ -1,3 +1,7 @@
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
import { describe, expect, it, vi } from 'vitest'
import { PROBE_TIMEOUT_MS } from './backend-probes'
@@ -45,4 +49,43 @@ describe('local client version source', (): void => {
expect(run).not.toHaveBeenCalled()
})
+ // A historical source install (launcher published only to user-bin) proves the launcher's
+ // identity with its own `--version`. That probe ran synchronously before the cache check, so
+ // every About/focus/profile refresh froze the Electron main thread for the launcher's runtime.
+ it.skipIf(process.platform === 'win32')(
+ 'a historical user-bin launcher never blocks the event loop, first call or cached',
+ async (): Promise<void> => {
+ const base: string = fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), 'hist-launcher-')))
+
+ try {
+ const root: string = path.join(base, 'checkout')
+ const home: string = path.join(base, 'home')
+ fs.mkdirSync(path.join(root, 'hermes_cli'), { recursive: true })
+ fs.mkdirSync(path.join(root, 'pm'))
+ fs.writeFileSync(path.join(root, 'hermes_cli', '_launchers.py'), '')
+ fs.mkdirSync(path.join(home, 'bin'), { recursive: true })
+ fs.writeFileSync(
+ path.join(home, 'bin', 'hermes'),
+ `#!/bin/sh\nsleep 1\nprintf '%s\\n' 'Hermes Agent v1.2.3 (2026.10.1)' 'Install directory: ${root}'\n`,
+ { mode: 0o755 }
+ )
+
+ for (const _call of ['first', 'cached']) {
+ let timerFired = false
+ const timer = setTimeout(() => { timerFired = true }, 10)
+ const startedAt: number = Date.now()
+ const pending: Promise<string> = resolveLocalRuntimeVersion(root, home, { isWindows: false })
+
+ expect(Date.now() - startedAt).toBeLessThan(250)
+ await new Promise(resolve => setTimeout(resolve, 30))
+ expect(timerFired).toBe(true)
+ clearTimeout(timer)
+ await expect(pending).resolves.toBe('1.2.3')
+ }
+ } finally {
+ fs.rmSync(base, { recursive: true, force: true })
+ }
+ },
+ 20_000
+ )
})
diff --git a/apps/desktop/electron/local-runtime-version.ts b/apps/desktop/electron/local-runtime-version.ts
index 3568bf5fb5b..bfdf29c70b2 100644
--- a/apps/desktop/electron/local-runtime-version.ts
+++ b/apps/desktop/electron/local-runtime-version.ts
@@ -4,7 +4,7 @@ import { appVersionInfo } from './app-version'
import { buildDesktopBackendEnv } from './backend-env'
import { PROBE_TIMEOUT_MS } from './backend-probes'
import type { InstallStamp } from './install-stamp'
-import { resolveInstallationLauncher } from './updater-process'
+import { resolveInstallationLauncherAsync } from './updater-process'
import { windowsShellCommand } from './windows-child-options'
export type VersionProbeRunner = (
@@ -21,8 +21,10 @@ export type VersionProbeRunner = (
) => Promise<string>
const DEFAULT_CACHE_TTL_MS = 5_000
-let cached: { launcher: string; version: string; expiresAt: number } | null = null
-let inFlight: { launcher: string; promise: Promise<string> } | null = null
+// Keyed by installation (root + HERMES_HOME), not launcher: the cache must answer before any
+// launcher discovery, whose historical rung spawns the launcher to prove its identity.
+let cached: { key: string; version: string; expiresAt: number } | null = null
+let inFlight: { key: string; promise: Promise<string> } | null = null
/** Extract the client version printed by the exact local installation launcher. */
export function parseLocalRuntimeVersion(output: string): string {
@@ -63,13 +65,45 @@ export async function resolveLocalRuntimeVersion(
run?: VersionProbeRunner
cacheTtlMs?: number
} = {}
+): Promise<string> {
+ const useCache = options.run === undefined
+ const key = `${root}\0${hermesHome}`
+
+ if (useCache && cached?.key === key && cached.expiresAt > Date.now()) {
+ return cached.version
+ }
+
+ if (useCache && inFlight?.key === key) {
+ return inFlight.promise
+ }
+
+ const promise = probeLocalRuntimeVersion(root, hermesHome, options)
+
+ if (useCache) {
+ inFlight = { key, promise }
+ void promise.then(version => {
+ cached = { key, version, expiresAt: Date.now() + (options.cacheTtlMs ?? DEFAULT_CACHE_TTL_MS) }
+ }).finally(() => {
+ if (inFlight?.promise === promise) {
+ inFlight = null
+ }
+ })
+ }
+
+ return promise
+}
+
+async function probeLocalRuntimeVersion(
+ root: string,
+ hermesHome: string,
+ options: { isWindows?: boolean; launcher?: string | null; run?: VersionProbeRunner }
): Promise<string> {
const isWindows = options.isWindows ?? process.platform === 'win32'
let launcher: string | null
try {
launcher = options.launcher === undefined
- ? resolveInstallationLauncher(root, isWindows, hermesHome)
+ ? await resolveInstallationLauncherAsync(root, isWindows, hermesHome)
: options.launcher
} catch {
return ''
@@ -79,22 +113,10 @@ export async function resolveLocalRuntimeVersion(
return ''
}
- const run = options.run ?? runVersionProbe
- const useCache = options.run === undefined
- const now = Date.now()
-
- if (useCache && cached?.launcher === launcher && cached.expiresAt > now) {
- return cached.version
- }
-
- if (useCache && inFlight?.launcher === launcher) {
- return inFlight.promise
- }
-
const shell = isWindows && /\.(cmd|bat)$/i.test(launcher)
const command = windowsShellCommand(launcher, shell, isWindows)
- const promise = run(command, ['--version'], {
+ return (options.run ?? runVersionProbe)(command, ['--version'], {
cwd: root,
env: { ...process.env, ...buildDesktopBackendEnv({ currentEnv: process.env }), HERMES_HOME: hermesHome },
timeout: PROBE_TIMEOUT_MS,
@@ -104,19 +126,6 @@ export async function resolveLocalRuntimeVersion(
})
.then(parseLocalRuntimeVersion)
.catch(() => '')
-
- if (useCache) {
- inFlight = { launcher, promise }
- void promise.then(version => {
- cached = { launcher, version, expiresAt: Date.now() + (options.cacheTtlMs ?? DEFAULT_CACHE_TTL_MS) }
- }).finally(() => {
- if (inFlight?.promise === promise) {
- inFlight = null
- }
- })
- }
-
- return promise
}
/**
diff --git a/apps/desktop/electron/updater-process.ts b/apps/desktop/electron/updater-process.ts
index e744e89471a..f78052c2832 100644
--- a/apps/desktop/electron/updater-process.ts
+++ b/apps/desktop/electron/updater-process.ts
@@ -38,38 +38,82 @@ export function resolveInstallationLauncher(
isWindows: boolean = process.platform === 'win32',
hermesHome: string = process.env.HERMES_HOME ?? ''
): string | null {
- const names: string[] = isWindows ? ['hermes.exe', 'hermes.cmd'] : ['hermes']
+ const staged: string | null = stagedInstallationLauncher(updateRoot, isWindows)
- for (const name of names) {
- const candidate: string = path.join(updateRoot, '.hermes', 'bin', name)
+ if (staged) {
+ return staged
+ }
- if (stagedFileExists(candidate)) {
+ for (const candidate of historicalLauncherCandidates(updateRoot, isWindows, hermesHome)) {
+ if (launcherTargetsInstallation(candidate, updateRoot)) {
return candidate
}
}
- // Earlier PM installers published only to user-bin. Trust that historical
- // launcher only after its existing version surface proves exact source identity.
- if (stagedFileExists(path.join(updateRoot, 'hermes_cli', '_launchers.py'))) {
- const extraDirs: string[] = isWindows ? [path.join(path.dirname(updateRoot), 'bin')] : []
+ return legacyInstallationLauncher(updateRoot, isWindows)
+}
- for (const candidate of userBinLaunchers(isWindows, hermesHome, extraDirs)) {
- if (launcherTargetsInstallation(candidate, updateRoot)) {
- return candidate
- }
- }
+/**
+ * resolveInstallationLauncher for callers on Electron's main thread that run
+ * repeatedly (the About/version refresh): the historical user-bin rung proves
+ * identity with the launcher's own `--version`, which may take seconds, so it
+ * runs asynchronously here and never stalls the event loop.
+ */
+export async function resolveInstallationLauncherAsync(
+ updateRoot: string,
+ isWindows: boolean = process.platform === 'win32',
+ hermesHome: string = process.env.HERMES_HOME ?? ''
+): Promise<string | null> {
+ const staged: string | null = stagedInstallationLauncher(updateRoot, isWindows)
+
+ if (staged) {
+ return staged
}
- // An old shim is a migration rung, never a damaged PM install fallback.
- if (!existsSync(path.join(updateRoot, 'pm'))) {
- const legacy: string = path.join(updateRoot, 'venv', isWindows ? 'Scripts' : 'bin', names[0])
+ const realRoot: string | null = realpathOrNull(updateRoot)
- if (stagedFileExists(legacy)) {
- return legacy
+ for (const candidate of realRoot ? historicalLauncherCandidates(updateRoot, isWindows, hermesHome) : []) {
+ if ((await launcherInstallDirectoryAsync(candidate, updateRoot)) === realRoot) {
+ return candidate
}
}
- return null
+ return legacyInstallationLauncher(updateRoot, isWindows)
+}
+
+function stagedInstallationLauncher(updateRoot: string, isWindows: boolean): string | null {
+ const names: string[] = isWindows ? ['hermes.exe', 'hermes.cmd'] : ['hermes']
+
+ return names.map(name => path.join(updateRoot, '.hermes', 'bin', name)).find(stagedFileExists) ?? null
+}
+
+// Earlier PM installers published only to user-bin. Trust that historical
+// launcher only after its existing version surface proves exact source identity.
+function historicalLauncherCandidates(updateRoot: string, isWindows: boolean, hermesHome: string): string[] {
+ if (!stagedFileExists(path.join(updateRoot, 'hermes_cli', '_launchers.py'))) {
+ return []
+ }
+
+ return userBinLaunchers(isWindows, hermesHome, isWindows ? [path.join(path.dirname(updateRoot), 'bin')] : [])
+}
+
+// An old shim is a migration rung, never a damaged PM install fallback.
+function legacyInstallationLauncher(updateRoot: string, isWindows: boolean): string | null {
+ if (existsSync(path.join(updateRoot, 'pm'))) {
+ return null
+ }
+
+ const legacy: string = path.join(updateRoot, 'venv', isWindows ? 'Scripts' : 'bin', isWindows ? 'hermes.exe' : 'hermes')
+
+ return stagedFileExists(legacy) ? legacy : null
+}
+
+function realpathOrNull(target: string): string | null {
+ try {
+ return realpathSync(target)
+ } catch {
+ return null
+ }
}
// cmd.exe re-parses its command line, so a launcher path carrying any of
@@ -210,8 +254,8 @@ export function launcherInstallDirectory(launcher: string, root?: string): strin
}
/** launcherInstallDirectory without blocking the caller's event loop. */
-function launcherInstallDirectoryAsync(launcher: string): Promise<string | null> {
- const probe: LauncherVersionProbe | null = launcherVersionProbe(launcher)
+function launcherInstallDirectoryAsync(launcher: string, root?: string): Promise<string | null> {
+ const probe: LauncherVersionProbe | null = launcherVersionProbe(launcher, root)
if (!probe) {return Promise.resolve(null)}