Skip to content

The agent that grows with you

fix(desktop): name the update stop a failed hand-off recorded

686f6c61fe90ab635367
diff --git a/apps/desktop/electron/handoff-result.ts b/apps/desktop/electron/handoff-result.ts
index 5ff34a5386f..33b52fad216 100644
--- a/apps/desktop/electron/handoff-result.ts
+++ b/apps/desktop/electron/handoff-result.ts
@@ -40,6 +40,10 @@ export interface HandoffResult {
manual: boolean
message: string
branch: string
+ /** The run this result belongs to; the update receipt carries the same value
+ * as `correlation_id`, so a failed run can be explained by its own stop.
+ * Null for producers that predate the field. */
+ runId: string | null
/** C2: `ok:true` with follow-up work that failed after the commit point. */
warnings: string[]
/** #101789: programs outside Hermes whose working folder blocked the Desktop app swap. */
@@ -166,6 +170,8 @@ function toHandoffResult(parsed: any, manual: boolean): HandoffResult {
manual,
message: typeof parsed?.message === 'string' ? parsed.message : '',
branch: typeof parsed?.branch === 'string' ? parsed.branch : '',
+ // Already validated by handoffRunMismatch: a present but malformed id was discarded there.
+ runId: typeof parsed?.run_id === 'string' ? parsed.run_id : null,
warnings: Array.isArray(parsed?.warnings) ? parsed.warnings.map(String).filter(Boolean) : [],
releaseHolders: toReleaseHolders(parsed?.release_holders)
}
diff --git a/apps/desktop/electron/update-handoff-report.test.ts b/apps/desktop/electron/update-handoff-report.test.ts
index 6c3e5131582..4252cecd8f3 100644
--- a/apps/desktop/electron/update-handoff-report.test.ts
+++ b/apps/desktop/electron/update-handoff-report.test.ts
@@ -63,3 +63,88 @@ test('the boot wait reports the result of the run it last parked on, across line
)
assert.equal(fs.existsSync(handoffResultPath(home)), false, 'a foreign result is still consumed')
})
+
+function failedReport(home: string, runId: string, stopClass: string | null): { lines: string[]; dialogs: any[] } {
+ const lines: string[] = []
+ const dialogs: any[] = []
+ const finished_at = Math.floor(Date.now() / 1000)
+
+ fs.writeFileSync(
+ handoffResultPath(home),
+ JSON.stringify({
+ ok: false,
+ exit_code: 1,
+ message: 'Update failed (exit 1). Run hermes debug share in a terminal to send a report.',
+ branch: 'main',
+ run_id: runId,
+ started_at: finished_at - 60,
+ finished_at
+ })
+ )
+
+ if (stopClass !== null) {
+ const dir = path.join(home, 'logs', 'update_receipts')
+
+ fs.mkdirSync(dir, { recursive: true })
+ fs.writeFileSync(
+ path.join(dir, 'latest.json'),
+ JSON.stringify({
+ schema: 1,
+ update_id: 'u1',
+ correlation_id: runId,
+ started_at: '2026-10-19T10:00:00+00:00',
+ finished_at: '2026-10-19T10:00:04+00:00',
+ outcome: 'failed',
+ stop_class: stopClass,
+ exit_code: 1
+ })
+ )
+ }
+
+ const run = parkedRunReport()
+
+ run.park({ startedAt: finished_at - 60, runId })
+ run.report({
+ hermesHome: home,
+ log: line => lines.push(line),
+ dialog: {
+ showMessageBox: async (options: any) => {
+ dialogs.push(options)
+
+ return { response: 2, checkboxChecked: false }
+ }
+ },
+ shell: { showItemInFolder: () => undefined },
+ openUpdates: () => undefined
+ })
+
+ return { lines, dialogs }
+}
+
+test('a failed run the receipt explains names its stop instead of the bare exit code', () => {
+ const home = fs.mkdtempSync(path.join(os.tmpdir(), 'handoff-report-'))
+ const { lines, dialogs } = failedReport(home, 'run-refused', 'downgrade_refused')
+
+ assert.equal(dialogs.length, 1, 'a failed hand-off gets one dialog')
+ assert.match(dialogs[0].message, /kept your install/)
+ assert.match(dialogs[0].detail, /--set-channel main/)
+ assert.match(dialogs[0].detail, /Details: Update failed \(exit 1\)/, 'the raw message stays visible')
+ assert.deepEqual(dialogs[0].buttons, ['Update settings', 'Open log', 'Close'], 'a refusal is not retried')
+ assert.ok(
+ lines.some(line => line.includes('detached update FAILED (exit 1)') && line.includes('stop_class downgrade_refused')),
+ lines.join('\n')
+ )
+})
+
+test('a failed run with no receipt keeps the generic retry dialog', () => {
+ const home = fs.mkdtempSync(path.join(os.tmpdir(), 'handoff-report-'))
+ const { lines, dialogs } = failedReport(home, 'run-plain', null)
+
+ assert.equal(dialogs.length, 1)
+ assert.equal(dialogs[0].message, "Hermes couldn't finish updating")
+ assert.deepEqual(dialogs[0].buttons, ['Try again', 'Open log', 'Close'])
+ assert.ok(
+ lines.some(line => line.includes('detached update FAILED (exit 1)') && !line.includes('stop_class')),
+ lines.join('\n')
+ )
+})
diff --git a/apps/desktop/electron/update-handoff-report.ts b/apps/desktop/electron/update-handoff-report.ts
index fce19a1a2e3..b20b3c6f355 100644
--- a/apps/desktop/electron/update-handoff-report.ts
+++ b/apps/desktop/electron/update-handoff-report.ts
@@ -6,6 +6,7 @@ import type { Dialog, Shell } from 'electron'
import { readAndConsumeHandoffResult, type ReleaseHolder } from './handoff-result'
import { closableReleaseHolders } from './release-holder-consent'
+import { explainUpdateStop, readStoppedRun } from './update-stop-remedy'
export interface HandoffReportHost {
hermesHome: string
@@ -88,9 +89,18 @@ export function reportHandoffResult(host: HandoffReportHost): void {
} else if (result && result.ok) {
host.log(`[updates] detached update finished OK (branch ${result.branch})`)
} else if (result) {
- host.log(`[updates] detached update FAILED (exit ${result.exitCode}): ${result.message}`)
+ // The run's own receipt names the stop the updater took (it is written
+ // before this dialog renders). Matched by correlation id, so an older
+ // run's stop can never explain this one.
+ const stop: ReturnType<typeof readStoppedRun> = readStoppedRun(host.hermesHome, result.runId)
+ const explained: ReturnType<typeof explainUpdateStop> = explainUpdateStop(stop?.stopClass ?? null)
const handoffLogPath = path.join(host.hermesHome, 'logs', 'desktop-update-handoff.log')
+ host.log(
+ `[updates] detached update FAILED (exit ${result.exitCode}): ${result.message}` +
+ (stop === null ? '' : ` (stop_class ${stop.stopClass})`)
+ )
+
// Async so boot is not blocked behind the dialog; the response handlers
// reuse the menu's open-updates path (queued until the renderer is ready)
// and the same reveal primitive as 'hermes:logs:reveal'.
@@ -98,11 +108,14 @@ export function reportHandoffResult(host: HandoffReportHost): void {
.showMessageBox({
type: 'error',
title: 'Hermes update',
- message: "Hermes couldn't finish updating",
- detail:
- "You're still on the previous version and can keep using it. Try the update again, or open the update log to report the problem.\n\n" +
- `Details: ${result.message}`,
- buttons: ['Try again', 'Open log', 'Close'],
+ message: explained?.message ?? "Hermes couldn't finish updating",
+ detail: explained === null
+ ? "You're still on the previous version and can keep using it. Try the update again, or open the update log to report the problem.\n\n" +
+ `Details: ${result.message}`
+ : `${explained.detail}\n\nDetails: ${result.message}`,
+ // A refusal is not retried: the same offer fails the same way. Its way
+ // out is the channel the update settings own, so lead with that.
+ buttons: explained === null ? ['Try again', 'Open log', 'Close'] : ['Update settings', 'Open log', 'Close'],
defaultId: 0,
cancelId: 2,
noLink: true
diff --git a/apps/desktop/electron/update-stop-remedy.test.ts b/apps/desktop/electron/update-stop-remedy.test.ts
new file mode 100644
index 00000000000..56da59660f2
--- /dev/null
+++ b/apps/desktop/electron/update-stop-remedy.test.ts
@@ -0,0 +1,127 @@
+import assert from 'node:assert/strict'
+import fs from 'node:fs'
+import os from 'node:os'
+import path from 'node:path'
+
+import { afterEach, test } from 'vitest'
+
+import { explainUpdateStop, readStoppedRun, receiptDirectory } from './update-stop-remedy'
+
+const homes: string[] = []
+
+afterEach((): void => {
+ for (const home of homes.splice(0)) {
+ fs.rmSync(home, { recursive: true, force: true })
+ }
+})
+
+function home(): string {
+ const dir: string = fs.mkdtempSync(path.join(os.tmpdir(), 'update-stop-'))
+
+ homes.push(dir)
+
+ return dir
+}
+
+function writeReceipt(root: string, record: Record<string, unknown>): void {
+ const dir: string = path.join(root, 'logs', 'update_receipts')
+
+ fs.mkdirSync(dir, { recursive: true })
+ fs.writeFileSync(path.join(dir, 'latest.json'), JSON.stringify(record))
+}
+
+const REFUSED = {
+ schema: 1,
+ update_id: 'u1',
+ correlation_id: 'posix-1-2-3',
+ started_at: '2026-10-19T10:00:00+00:00',
+ finished_at: '2026-10-19T10:00:04+00:00',
+ outcome: 'failed',
+ stop_class: 'downgrade_refused',
+ exit_code: 1
+}
+
+test('a failed hand-off is explained by the stop its own receipt recorded', () => {
+ const root = home()
+
+ writeReceipt(root, REFUSED)
+
+ assert.deepEqual(readStoppedRun(root, 'posix-1-2-3'), { stopClass: 'downgrade_refused', outcome: 'failed' })
+})
+
+test('a receipt from another run never explains this one', () => {
+ const root = home()
+
+ writeReceipt(root, REFUSED)
+
+ assert.equal(readStoppedRun(root, 'posix-9-9-9'), null)
+})
+
+test('no run identity means no attribution', () => {
+ const root = home()
+
+ writeReceipt(root, REFUSED)
+
+ assert.equal(readStoppedRun(root, null), null)
+})
+
+test('a record still running has no stop to report', () => {
+ const root = home()
+
+ writeReceipt(root, { ...REFUSED, outcome: 'running', finished_at: null })
+
+ assert.equal(readStoppedRun(root, 'posix-1-2-3'), null)
+})
+
+test('a run that committed is not a stop, whatever class it carries', () => {
+ const root = home()
+
+ writeReceipt(root, { ...REFUSED, outcome: 'success', stop_class: null })
+
+ assert.equal(readStoppedRun(root, 'posix-1-2-3'), null)
+})
+
+test('a token outside the closed set is ignored', () => {
+ const root = home()
+
+ writeReceipt(root, { ...REFUSED, stop_class: 'Downgrade refused (exit 1)' })
+
+ assert.equal(readStoppedRun(root, 'posix-1-2-3'), null)
+})
+
+test('an unreadable receipt falls back to the generic dialog', () => {
+ const root = home()
+
+ fs.mkdirSync(path.join(root, 'logs', 'update_receipts'), { recursive: true })
+ fs.writeFileSync(path.join(root, 'logs', 'update_receipts', 'latest.json'), '{not json')
+
+ assert.equal(readStoppedRun(root, 'posix-1-2-3'), null)
+ assert.equal(readStoppedRun(path.join(root, 'missing'), 'posix-1-2-3'), null)
+})
+
+test('a profile home reads the root home receipts, where the update files them', () => {
+ const root = home()
+
+ writeReceipt(root, REFUSED)
+
+ assert.equal(receiptDirectory(path.join(root, 'profiles', 'acme')), path.join(root, 'logs', 'update_receipts'))
+ assert.deepEqual(readStoppedRun(path.join(root, 'profiles', 'acme'), 'posix-1-2-3'), {
+ stopClass: 'downgrade_refused',
+ outcome: 'failed'
+ })
+})
+
+test('the downgrade refusal names the channel that unblocks it', () => {
+ const explained = explainUpdateStop('downgrade_refused')
+
+ assert.ok(explained, 'the recorded refusal has an explanation')
+ assert.match(explained.message, /kept your install/)
+ assert.match(explained.detail, /--set-channel main/)
+ assert.match(explained.detail, /nothing was changed/)
+})
+
+test('a stop with no explanation keeps the generic failure dialog', () => {
+ assert.equal(explainUpdateStop(null), null)
+ assert.equal(explainUpdateStop('git_timeout'), null)
+ assert.equal(explainUpdateStop('toString'), null)
+})
diff --git a/apps/desktop/electron/update-stop-remedy.ts b/apps/desktop/electron/update-stop-remedy.ts
new file mode 100644
index 00000000000..3edba5f1d05
--- /dev/null
+++ b/apps/desktop/electron/update-stop-remedy.ts
@@ -0,0 +1,104 @@
+/** Name the stop the updater already recorded, instead of a bare "exit 1" dialog. */
+
+import fs from 'node:fs'
+import path from 'node:path'
+
+/** The closed token set `hermes_cli.update_receipt.record_stop_reason` records. */
+const STOP_CLASS_TOKEN = /^[a-z][a-z0-9_]{0,39}$/
+
+const UPDATES_GUIDE = 'https://hermes-agent.nousresearch.com/docs/getting-started/updating'
+
+export interface UpdateStop {
+ stopClass: string
+ outcome: string
+}
+
+export interface UpdateStopExplanation {
+ /** Dialog headline: says what happened to the install, not that it "failed". */
+ message: string
+ /** Dialog body: the stop, why it is the whole story, and where the way out is. */
+ detail: string
+}
+
+/**
+ * Receipts live under the ROOT home: `hermes -p <name> update` files its receipt
+ * in `<root>/logs/update_receipts/`, and the hand-off script resolves the same
+ * root before it reads the receipt back (scripts/desktop-update/posix.sh,
+ * `update_committed_after_exit`). A profile home passed here therefore still
+ * reads the root's store.
+ */
+export function receiptDirectory(hermesHome: string): string {
+ const home: string = path.resolve(hermesHome)
+ const root: string = path.basename(path.dirname(home)) === 'profiles' ? path.dirname(path.dirname(home)) : home
+
+ return path.join(root, 'logs', 'update_receipts')
+}
+
+/**
+ * This run's own stop, read from the receipt the update wrote.
+ *
+ * `correlation_id` is the hand-off `run_id` (the launcher exports it as
+ * `HERMES_UPDATE_CORRELATION_ID`), so a receipt left behind by an earlier run
+ * cannot explain this one. A record still `running` keeps `finished_at` null and
+ * never matches — the same rule the hand-off script applies before it trusts an
+ * outcome. Anything missing or unexpected returns null and the caller keeps its
+ * generic text: the dialog must never invent a stop it cannot prove.
+ */
+export function readStoppedRun(hermesHome: string, correlationId: string | null): UpdateStop | null {
+ if (!correlationId) {
+ return null // no run identity: a receipt on disk cannot be attributed to this result
+ }
+
+ let parsed: any
+
+ try {
+ parsed = JSON.parse(fs.readFileSync(path.join(receiptDirectory(hermesHome), 'latest.json'), 'utf8'))
+ } catch {
+ return null
+ }
+
+ if (!parsed || typeof parsed !== 'object' || parsed.correlation_id !== correlationId) {
+ return null
+ }
+
+ if (typeof parsed.finished_at !== 'string' || parsed.finished_at === '') {
+ return null // still running: its stop is not written yet
+ }
+
+ const outcome: string = typeof parsed.outcome === 'string' ? parsed.outcome : ''
+
+ if (outcome !== 'failed' && outcome !== 'refused') {
+ return null
+ }
+
+ const stopClass: string = typeof parsed.stop_class === 'string' ? parsed.stop_class : ''
+
+ return STOP_CLASS_TOKEN.test(stopClass) ? { stopClass, outcome } : null
+}
+
+/**
+ * What each recorded stop means for the user, where the receipt alone is enough
+ * to say it. Kept to the stops whose remedy the CLI already owns: a token with
+ * no entry keeps the generic failure dialog rather than a guessed explanation.
+ *
+ * `downgrade_refused` is the refusal `hermes_cli/update_downgrade_guard.py`
+ * prints before anything moves (the receipt records the exit, not that text), so
+ * the remedy here is the one the guide names: follow the checkout's channel.
+ */
+const STOP_EXPLANATIONS: Record<string, UpdateStopExplanation> = {
+ downgrade_refused: {
+ message: 'Hermes kept your install: the offered release is older than it',
+ detail:
+ 'The updater refused to move this install back to the release it offered, because that release predates the ' +
+ 'gateway runtime your session stores already use. Downgrading is unsupported, and nothing was changed: you are ' +
+ 'still on the version you had.\n\n' +
+ 'To follow this checkout instead of the release channel, run `hermes update --set-channel main`, or pick a ' +
+ `channel in About ▸ Updates.\n\n${UPDATES_GUIDE}`
+ }
+}
+
+export function explainUpdateStop(stopClass: string | null): UpdateStopExplanation | null {
+ return stopClass === null ? null : Object.prototype.hasOwnProperty.call(STOP_EXPLANATIONS, stopClass)
+ ? STOP_EXPLANATIONS[stopClass]
+ : null
+}