The agent that grows with you
Python aiai-agentai-agentsanthropicchatgptclaudeclaude-codecodexhermeshermes-agentllmnous-researchopenai
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.tsindex 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: booleanmessage: stringbranch: 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.tsindex 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.tsindex 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: truediff --git a/apps/desktop/electron/update-stop-remedy.test.ts b/apps/desktop/electron/update-stop-remedy.test.tsnew file mode 100644index 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.tsnew file mode 100644index 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+}