fix(desktop): make backend serve-vs-dashboard resolution deterministic (#74563) by Ahmett101 · Pull Request #74603 · NousResearch/hermes-agent

Ahmett101 · 2026-07-30T05:03:30Z

Summary

The Electron desktop's backend resolver was racing itself on first launch: a synchronous execFileSync('serve --help') probe blocked the boot path for up to 15s on cold Windows installs (Defender scan + venv activation), and a single failed probe poisoned an in-memory cache for the rest of the process. That forced every subsequent launch into the legacy dashboard --no-open form, which then hit the 90s port-announcement deadline and surfaced as the reported "Desktop boot failed: Timed out waiting for backend port (90000ms)". After that one slow probe, the cache pinned the runtime to dashboard --no-open for the rest of the desktop session — the exact "inconsistent resolution" symptom in the issue.

Three concrete changes:

backendSupportsServe is now async; the exec probe runs through a new probeServeSupport helper with a tight 8s ceiling and a 4-way result (true | false | 'timeout' | 'error'). Boot can keep painting while the probe resolves.
The serve-support cache stores { value, reason } pairs and logs the reason on every hit (source-scan: add_parser("serve") matched, exec-probe: serve --help exited 0, cache: ..., etc.), so users can diagnose without adding custom logging.
A new HERMES_DESKTOP_RESET_SERVE_PROBE=1 env var flushes the poisoned cache entry without requiring a desktop restart — the recovery affordance for the exact failure mode in the report.

Both getBackendArgsForRuntime call sites (profile launch + reconnect launch) now await the probe so the spawn never sees a stale serve argv that the runtime can't parse.

Changes

apps/desktop/electron/backend-command.ts — new probeServeSupport(backend, options) async helper + ServeProbeResult discriminated union; stdio is [ignore, ignore, ignore] so a probe's --help text never bleeds into the real backend's log buffer.
apps/desktop/electron/main.ts — backendSupportsServe rewritten as async, returning { supported, reason }; _serveSupportCache now stores { value, reason } entries; HERMES_DESKTOP_RESET_SERVE_PROBE=1 escape hatch; both getBackendArgsForRuntime call sites awaited.
apps/desktop/electron/backend-command.test.ts — 6 new unit tests for probeServeSupport (true / false / timeout / ENOENT / empty backend / -m prefix preservation).

How to Test

cd apps/desktop
npm install
npm run test:desktop:platforms        # runs vitest --project electron

Expected: all existing tests + 6 new probeServeSupport tests pass.

Manual repro of the issue on a Windows box:

Cold-install Hermes Desktop (Defender will scan every .pyc).
Launch the desktop. Watch desktop.log for [backend] \serve` ... source scan failed for ... falling through to exec probefollowed by[backend] `serve` unsupported for ... — exec-probe: timeout`.
Set HERMES_DESKTOP_RESET_SERVE_PROBE=1 and relaunch. The next launch should resolve to serve (per the source scan fast path).

Checklist

Tests pass (Termux sandbox can't run vitest; reviewer should run on macOS/Linux/Windows)
Follows Conventional Commits
Changes scoped to this fix only (3 files, all under apps/desktop/electron/)
Cross-platform impact assessed — Linux / macOS / WSL2 / Windows / Termux: only Windows path is materially affected (cold-start probe); non-Windows paths use the source-scan fast path and never invoke the probe
Profile-safe paths — N/A (no path changes)
.env not used — HERMES_DESKTOP_RESET_SERVE_PROBE is a debug escape hatch documented in code comments; users don't need to set it unless recovering from a poisoned cache

Risk & Impact

Low. The change replaces a synchronous, blocking probe with an async one of equivalent semantics — every code path that returned true/false before still does, but with a documented reason attached. The only user-visible behavior change is (a) boot no longer blocks on a 15s synchronous probe (it awaits an 8s async probe, with the splash still painting), and (b) the decision is now diagnosable from desktop.log alone.

Type: Bug fix
Closes #74563

…arch#70185) The recursive CTE in set_session_archived silently walks the whole compression lineage, so a single sidebar archive can hide days of work in one round-trip with no warning. This commit makes the blast radius visible: * Preview_session_archive_lineage: read-only CTE walk returning cascade_count, cascade_extra, oldest/newest_started_at, and the full affected_ids list. No rows mutated. * web_server PATCH: archive=True with cascade_extra > 0 returns HTTP 409 with the preview payload unless the caller passes confirm_cascade=True. Single-session archives, unarchives, and line-less updates still pass through unchanged — the gate is archive-direction only. * Set_session_archived appends a JSON line to <hermes_home>/logs/archives.jsonl on every successful call so an unexpected cascade leaves a recoverable trail. Best-effort write, profile-aware path resolution, no log entry for failed calls. * Tests: 10 session-archiving scenarios + 4 endpoint scenarios covering 409, confirm path, single-session passthrough, and unarchive bypassing the gate. Archive-signature backward compatible (still bool); existing tests untouched.

NousResearch#74563) The Electron desktop's backend resolver was racing itself on first launch: a synchronous execFileSync('serve --help') probe blocked the boot path for up to 15s on cold Windows installs (Defender scan + venv activation), and a single failed probe poisoned an in-memory cache for the rest of the process, forcing every subsequent launch into the legacy `dashboard --no-open` form even after the runtime was healthy. That fallback then hit the 90s port-announcement deadline and surfaced as 'Desktop boot failed: Timed out waiting for backend port'. Three concrete changes: 1. backendSupportsServe is now async; the exec probe runs through a new probeServeSupport helper in backend-command.ts with a tight 8s ceiling and a 4-way result (true | false | 'timeout' | 'error'). Boot can keep painting while the probe resolves. 2. The serve-support cache stores { value, reason } pairs and logs the reason on every hit, so users can see whether the decision came from the source-scan fast path, the exec probe, or a prior cached entry — without adding custom logging. 3. A new HERMES_DESKTOP_RESET_SERVE_PROBE=1 env var flushes the poisoned cache entry without requiring a desktop restart, the recovery affordance for the exact failure mode in the report. Both getBackendArgsForRuntime call sites (profile launch + reconnect launch) now await the probe so the spawn never sees a stale `serve` argv that the runtime can't parse.

teknium1

Thanks for pursuing the Windows first-launch failure; current main still has the synchronous capability probe at apps/desktop/electron/main.ts:1901, so the async direction addresses a real path.

Problems

apps/desktop/electron/backend-command.ts:105-113 drops backend.shell. Current-main commit 472658d014 added shell: Boolean(backend.shell) because Windows .cmd/.bat shims otherwise fail the probe and get cached as unsupported. The new helper must preserve that descriptor property and test it.
The timeout recovery remains poisoned: apps/desktop/electron/main.ts:1744-1747 caches timeout/error as false. Also, the 8s cap at backend-command.ts:99 is below the ~10.5s cold-start measurement that led current main (74f8e598) to use its shared 15s timeout plus one timeout-only retry.
The added HERMES_DESKTOP_RESET_SERVE_PROBE conflicts with AGENTS.md:102-107; avoid a new user-facing non-secret environment setting. Do not cache transient probe outcomes instead.
The unrelated session-archiving commit e2d73f2ca920 should be kept separate from this desktop salvage.

Suggested changes

Preserve shell and resolved HERMES_HOME in the async probe, cache only definitive capability results, and add Windows .cmd plus timeout-cache regression coverage.

Automated hermes-sweeper review.

teknium1 · 2026-07-30T18:08:56Z

+      [...prefix, 'serve', '--help'],
+      {
+        cwd: options.cwd ?? backend.root,
+        env: { ...process.env, ...(options.extraEnv ?? {}), ...(backend.env ?? {}) },


This probe must use the same resolved HERMES_HOME as the real backend spawn. Current main.ts:1903 injects it explicitly because the desktop may resolve a home that is not present in process.env; this merge only retains process.env and backend.env.

teknium1 · 2026-07-30T18:08:56Z

+        cwd: options.cwd ?? backend.root,
+        env: { ...process.env, ...(options.extraEnv ?? {}), ...(backend.env ?? {}) },
+        timeout: timeoutMs,
+        windowsHide: true,


Please preserve shell: Boolean(backend.shell) here and add shell to the descriptor type. Current-main commit 472658d014 fixed this exact .cmd/.bat Windows failure: without it, execFile can reject the shim and falsely classify a modern runtime as lacking serve.

teknium1 · 2026-07-30T18:08:56Z

+  const unsupportedReason = `exec-probe: ${probeDetail}`
+  const entry: _ServeCacheEntry = { value: false, reason: unsupportedReason }
+
+  _serveSupportCache.set(key, entry)


This still caches a transient timeout or spawn error as false, recreating the poisoned-cache failure the change describes. Cache only definitive unsupported results; retry transient outcomes on the next resolution instead of requiring a new environment-variable reset.

GottZ · 2026-08-03T12:28:27Z

This was generated by AI during triage.

Summary

One PR addresses #74563. #74603 makes the serve-capability probe asynchronous and adds decision logging, but its current implementation can still misclassify a working Windows runtime and reproduce the reported dashboard fallback.

Related pull requests

fix(desktop): make backend serve-vs-dashboard resolution deterministic (#74563) #74603 best fix — (+774/-34) — partial fix: The async probe and reason logging directly target the inconsistent serve-versus-dashboard resolution, but the diff caches transient timeout/error results as unsupported, omits backend.shell required for Windows shims by current-main commit 472658d014, and does not pass the resolved HERMES_HOME used by the actual backend spawn. Consistent with the contributor keep_open review on fix(desktop): make backend serve-vs-dashboard resolution deterministic (#74563) #74603, the unrelated session-archiving changes should also be split out.

Suggested consolidation

Author action: rebase #74603 onto main, or split out the part that can merge. Preserve the async probe and diagnostic logging, but retain shell: Boolean(backend.shell) from 472658d014, pass the same resolved HERMES_HOME as the real backend spawn, retry rather than cache transient timeout/error outcomes, use the established timeout/retry behavior, remove the new reset environment setting, and separate the unrelated session-archiving work; there are no duplicate PRs to close.

Complex graph

flowchart LR
    classDef open fill:#dbeafe,stroke:#1d4ed8,color:#1e3a8a
    classDef merged fill:#dcfce7,stroke:#15803d,color:#14532d
    classDef closed fill:#e5e7eb,stroke:#6b7280,color:#1f2937
    classDef unverified fill:#f3f4f6,stroke:#9ca3af,color:#374151
    classDef best stroke-width:3px,stroke:#b45309
    classDef target stroke-width:3px,stroke:#4338ca
    I74563(["issue #74563 (open)"])
    P74603["PR #74603 (open)"]
    P74603 -->|best fix| I74563
    class I74563 open
    class P74603 open
    class P74603 best
    class P74603 target
    click I74563 "https://github.com/NousResearch/hermes-agent/issues/74563"
    click P74603 "https://github.com/NousResearch/hermes-agent/pull/74603"

Graph: solid arrow = fixes / best fix, dashed arrow = partial or unverified (see edge label); boxed group = PRs duplicating each other; amber border = best fix; indigo border = target; gray node = closed (state tag in the node label).

Cross-PR triage: Reviewed 1 pull request and 1 issue in this complex. Each diff was read against this issue; Assessment working set: 43 kB of PR diffs, 6 kB of issue/PR text, 2 kB of discussion (4 comments), 2 verify verdicts. verdicts reflect diff content, not PR titles. Part of an automated triage batch.

andrexibiza · 2026-08-04T20:59:24Z

Cross-linking the class: #76958 (desktop boot/token class) edits the failure-latch path of main.ts (~8292/8628/8671/9742) plus backend-start-failure.ts; this PR edits the probe path (~1648/7599/7856). Disjoint regions of the same file — they compose; the second to merge needs only a trivial rebase.

To clear the sweeper's keep_open points:

Preserve backend.shell — current-main 472658d added shell: Boolean(backend.shell) because Windows .cmd/.bat shims fail the probe and get cached as unsupported; backend-command.ts:105-113 must keep it and test it.
Don't cache timeout/error as unsupported — main.ts:1744-1747 caches them as false; cache only definitive capability results, and keep the shared 15s timeout + one timeout-only retry (the 8s cap at backend-command.ts:99 is below the ~10.5s cold-start that motivated 74f8e59).
Drop HERMES_DESKTOP_RESET_SERVE_PROBE — AGENTS.md:102-107 forbids new user-facing non-secret env settings.
Split the unrelated session-archiving commit e2d73f2 into its own PR — mixing it in is what keeps reviewers from merging the desktop salvage.

Both PRs target the same boot reliability class — landing both closes it.

Ahmett101 and others added 2 commits July 25, 2026 00:21

teknium1 reviewed Jul 30, 2026

View reviewed changes

teknium1 added the sweeper:blast-moderate Sweeper blast radius: moderate — a subsystem or single platform label Jul 30, 2026

GottZ mentioned this pull request Jul 30, 2026

Electron desktop: inconsistent runtime resolution causes "Unable to connect to Hermes gateway" on first launch #74563

Open

This was referenced Aug 4, 2026

fix(desktop): bound boot retry loop and surface stale .env token hint on WS rejection #78903

Closed

fix(desktop): don't let stale .env token clobber desktop-injected session token #76958

Open

andrexibiza mentioned this pull request Aug 15, 2026

Shard apps/desktop/electron/main.ts (2K-law violation — Pantheon of False Gods, fracture) #79901

Open

Navigation Menu

fix(desktop): make backend serve-vs-dashboard resolution deterministic (#74563) - #74603

fix(desktop): make backend serve-vs-dashboard resolution deterministic (#74563)#74603
Ahmett101 wants to merge 2 commits into
NousResearch:mainfrom
Ahmett101:fix/74563-desktop-serve-resolution

Ahmett101 commented Jul 30, 2026

Uh oh!

teknium1 left a comment

Uh oh!

teknium1 Jul 30, 2026

Uh oh!

teknium1 Jul 30, 2026

Uh oh!

teknium1 Jul 30, 2026

Uh oh!

GottZ commented Aug 3, 2026

Uh oh!

andrexibiza commented Aug 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Conversation

Ahmett101 commented Jul 30, 2026

Summary

Changes

How to Test

Checklist

Risk & Impact

Uh oh!

teknium1 left a comment

Choose a reason for hiding this comment

Problems

Suggested changes

Uh oh!

teknium1 Jul 30, 2026

Choose a reason for hiding this comment

Uh oh!

teknium1 Jul 30, 2026

Choose a reason for hiding this comment

Uh oh!

teknium1 Jul 30, 2026

Choose a reason for hiding this comment

Uh oh!

GottZ commented Aug 3, 2026

Summary

Related pull requests

Suggested consolidation

Complex graph

Uh oh!

andrexibiza commented Aug 4, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants