Add Hermes desktop app (#20059)

* feat: better composer etc

* docs: add desktop and dashboard run instructions

* fix(desktop): address security scan findings

* fix(dashboard): resolve @nous-research/ui path under npm workspaces

The sync-assets prebuild step shelled out to 'cp -r
node_modules/@nous-research/ui/dist/fonts ...' with a path relative
to apps/dashboard/. That works only when the dep is installed
locally in the dashboard workspace, but 'npm install' at the repo
root (the documented setup — see apps/desktop/README.md) hoists
shared deps to the root node_modules under npm workspaces. The
relative cp then fails with 'No such file or directory', sync-assets
exits 1, the Vite build aborts, and 'hermes dashboard' surfaces a
generic 'Web UI build failed' message.

Replace the shell one-liner with scripts/sync-assets.cjs, which
walks up from the dashboard directory looking for node_modules/
@nous-research/ui — working in both the hoisted (workspaces) and
co-located (standalone) layouts. Also guards against a missing
dist/fonts or dist/assets with a clearer error pointing at a
rebuild of the UI package rather than silently copying nothing.

* feat(desktop): support connecting to a remote Hermes backend

Add HERMES_DESKTOP_REMOTE_URL and HERMES_DESKTOP_REMOTE_TOKEN env
vars that, when set, short-circuit the local-child spawn in
startHermes() and connect the Electron renderer to an already-
running 'hermes dashboard' server reachable over the network.

Motivating use case: WSL2 users who want to run the Hermes core
(agent loop, tools, filesystem access) inside their WSL
distribution while rendering the Electron GUI on native Windows.
Before this change, the desktop app always spawned a local Python
child on the same host as the renderer, which doesn't cross the
WSL/Windows boundary.

The remote path reuses waitForHermes() as a liveness probe
(/api/status is in the backend's public endpoint allowlist), so
the connection is only returned once the backend is actually
ready. WebSocket URL derivation picks ws:// or wss:// based on
the input scheme. URL validation rejects non-http(s) schemes and
requires both env vars together to avoid a half-configured
connection that would silently fall through to the spawn path.

No behaviour change when the env vars are unset — the default
local-spawn flow is untouched.

Typical usage:

  # in WSL2
  hermes dashboard --tui --no-open --host 0.0.0.0 --port 9119 --insecure

  # on Windows
  set HERMES_DESKTOP_REMOTE_URL=http://localhost:9119
  set HERMES_DESKTOP_REMOTE_TOKEN=<session token>
  set HERMES_DESKTOP_IGNORE_EXISTING=1
  (launch Hermes desktop)

* ci(desktop): automate desktop releases

Add GitHub Actions release channels for signed desktop installers and document the stable/nightly download paths.

* feat: file tabs

* refactor(desktop): tighten right-rail tab close API

Promote closeRightRailTab/closeActiveRightRailTab as the single
public entry point. Drops the activeTabRef + handleCloseDocument
indirection in ChatPreviewRail, the unused $rightRailHasContent
atom, and the legacy dismissFilePreviewTarget alias. -70 LOC.

* feat(desktop): polish composer pill toward reference look

Solid foreground-on-background send/voice-conversation circle (black-on-white
in light, white-on-black in dark) anchors the right edge as the primary CTA
instead of the orange theme primary. Bumps the primary control to 2.125rem so
it visually outranks the ghost mic/plus controls. Opens up the surface padding
(0.625rem x / 0.5rem y) so the input row breathes around its controls, and
nudges the corner radius from 20 to 24px for a slightly pill-ier silhouette.
LiquidGlass distortion is preserved.

* feat(desktop): add startup and onboarding flow

Add phase-based desktop boot progress, fresh-install sandbox testing, and first-run provider credential onboarding so packaged installs can start cleanly without manual settings detours.

* fix(desktop): gate prompts on provider setup

Show the desktop provider onboarding flow before prompt submission when no inference provider is configured, preventing fresh installs from falling through to backend credential errors.

* fix(desktop): surface provider onboarding from session warnings

Propagate credential warnings through session runtime info and open desktop onboarding whenever a session reports no usable provider, so unconfigured installs cannot fall through to prompt errors.

* fix(desktop): route gateway provider errors to onboarding

The "No inference provider configured" auth error reaches the renderer through gateway error events, not the prompt.submit promise; the previous patch only caught the latter, so the error toast still surfaced and onboarding never opened.

Also strip credential-shaped env vars from the test:desktop:fresh sandbox so the packaged backend can't see provider keys leaking from the launching shell.

* fix(desktop): use strict runtime check to drive onboarding

setup.status returned True whenever any provider auth state was discoverable, including indirect fallbacks like a gh-CLI Copilot token. That made desktop think the user was set up while the agent's actual resolve_runtime_provider call still raised AuthError, leaving the user with a useless toast and no onboarding.

Add a setup.runtime_check gateway method that runs the same resolver the agent uses on session creation, and switch the desktop onboarding overlay and prompt precheck to use it.

* feat(desktop): OAuth-first onboarding using existing dashboard provider API

Replace the engineer-flavored API key form with a Sign-in-first onboarding overlay that uses the dashboard's existing /api/providers/oauth catalog and PKCE/device-code endpoints (Anthropic, Nous, OpenAI Codex, etc.). API key entry is now a fallback tab with friendly provider names instead of env var prefixes, and the loud raw resolver error is gone in favor of a one-line welcome message.

* fix(desktop): polish onboarding provider list

Reorder OAuth providers so Nous Portal is first, give the segmented Sign in / API key control equal column widths, and replace the engineer-flavored backend names like "Anthropic (Claude API)" / "MiniMax (OAuth)" with friendlier in-app titles. External-CLI providers now show a softer subtitle and an external-link icon instead of a chevron.

* refactor(desktop): split onboarding overlay into store + view

Move the OAuth state machine, runtime check, copy-to-clipboard, and api-key save into store/onboarding.ts (matching the boot.ts pattern), leaving the overlay as a presentation layer that subscribes via useStore. Tabs are now table-driven, child panels read flow from the store instead of prop-drilling, and the polling/PKCE/error/success branches share a small Status atom.

* fix(desktop): external CLI providers + center mode tabs

External-CLI providers (Claude Code, Qwen Code) now open an in-overlay panel with the CLI command, copy button, and an "I've signed in" recheck instead of firing an invisible toast. Center the Sign in / API key tab control so it sits under the heading instead of hugging the left edge.

* fix(desktop): drop onboarding tabs for an inline link, group device-code waiting state

Replace the Sign in / API key tab pair with an "I have an API key" footer link under the OAuth provider list, with a "Back to sign in" affordance inside the API key form. Group the device-code "Waiting for you to authorize..." status next to the Cancel button so the alignment matches the action.

* refactor(desktop): tighten onboarding store + overlay

Drop the dead isOnboardingBusy/BUSY set, factor the catch-fallback dance into safeReq, and share a single reloadAndConnect helper between PKCE submit, device-code success, external recheck, and api-key save.

In the overlay, extract Step / CodeBlock / FlowFooter / CancelBtn / DocsLink atoms so the four sign-in panels share the same chrome instead of repeating it inline. Net effect: fewer literal divs, one place to touch the spacing, and the code-block + footer rows are reusable across future flows.

* fix(desktop): mount onboarding from frame 1 to kill the FOUT

Default onboarding.configured to null (unknown until the runtime check resolves) and have the onboarding overlay render whenever it's not yet confirmed true. The boot overlay now yields to it, so the very first paint is the Welcome card with a "While we get you set up..." progress strip instead of a flash of the chat shell between boot dismiss and onboarding mount.

The picker swaps in cleanly once the gateway opens and the runtime check confirms the user is not configured. Already-configured users see the same prep card briefly while their existing runtime warms up, then the overlay dismisses without touching the chat shell.

* fix(desktop): top-align empty sessions placeholder

The "Start a chat to build your history." empty state used a min-h-35 grid place-items-center container, which floated the text in a tall dead zone. Render it as a flat paragraph that sits right under the section header like the empty pinned state does.

* refactor(desktop): drop dead boot overlay

Onboarding overlay subsumes the boot card now that it mounts from frame 1 and renders boot progress inline. The standalone DesktopBootOverlay is unreachable in every flow (yields whenever onboarding has not confirmed configured, dismisses once it has).

* fix(desktop): hide pinned/recents sections until first session

A fresh sidebar showed the Pinned and Recent chats headers with floating empty-state copy underneath. Drop both sections (and the now-orphan SidebarEmptySessionState) when there are no sessions yet — they reappear after the first chat. Skeletons during initial load are unchanged.

* feat(gui): route embedded TUI through dashboard gateway (#21979)

Inject HERMES_TUI_GATEWAY_URL into dashboard PTY sessions so embedded ui-tui instances attach to the in-process websocket gateway, with coverage for the new env wiring.

* Add desktop remote gateway settings

Make the desktop gateway connection configurable from settings so local remains the default while remote backends can be saved, tested, and applied without environment variables.

* feat(gui): first-class Messaging page + gateway menu redesign

- Add Messaging page to the desktop app with per-platform setup,
  status, and inline guidance. Catalog derives from gateway.config
  Platform enum + plugin registry, so every messaging adapter the CLI
  supports (Telegram, Discord, Slack, Mattermost, Matrix, WhatsApp,
  Signal, BlueBubbles, Home Assistant, Email, SMS, DingTalk, Feishu,
  WeCom, Weixin, QQ, Yuanbao, API server, Webhooks, plugins) shows up
  without per-platform code.
- New REST endpoints: GET /api/messaging/platforms, PUT and POST
  /test on the same path. Secrets go through the existing .env
  pipeline; enable/disable writes config.yaml.
- Replace gateway statusbar dropdown with a richer panel: status row,
  icon-only restart + system-panel actions, recent activity (with
  timestamps trimmed in display, full text on hover), platform list.
- Auto-poll the messaging page every 6s (paused when hidden) so
  status updates without a manual check.
- Drop Settings / Command Center from the sidebar nav (still
  reachable via shortcuts and the titlebar cog).
- Flatten top corners on Messaging/Skills/Artifacts/Chat panes.
- Share new StatusDot component across messaging + gateway menu.
- Fix gateway/config.py so an explicit platforms.<name>.enabled=false
  in config.yaml is honored when env tokens are present.
- pb-9 on the chat content area for breathing room above the composer.

* Potential fix for pull request finding 'CodeQL / Clear-text logging of sensitive information'

Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>

* pin electron version

* hide application menu on non-mac systems

* interpret compactPreview for non-string vlaues as JSON or an empty string

* fix(desktop): keep composer contenteditable mounted across stacked toggle

The composer rendered {input} inside two different parent fragments
depending on `stacked`. When auto-expand flipped `stacked` (e.g. the
moment typed text wrapped past two lines), React reconciled the two
branches as different positions and unmounted/remounted the
contenteditable. The fresh mount started empty, so any in-flight
characters — most reliably reproduced by holding a key — were lost.

Replace the conditional with a single CSS Grid whose template-areas
swap on `stacked`. The three children (menu, input, controls) keep
stable identities across the toggle; only their grid placement
changes, which the browser handles without React tearing down the
editor.

* refactor(desktop): align install layout with install.ps1 / install.sh

Make the desktop app's runtime layout match what scripts/install.ps1 and
scripts/install.sh produce, so a desktop-only user and a CLI-only user end
up with the same files in the same places and can share one install.

Layout
- ACTIVE_HERMES_ROOT = HERMES_HOME/hermes-agent  (was: process.resourcesPath/hermes-agent, read-only)
- VENV_ROOT          = HERMES_HOME/hermes-agent/venv  (was: userData/hermes-runtime)
- desktop.log        = HERMES_HOME/logs/desktop.log  (was: userData/desktop.log)
- HERMES_HOME default: %LOCALAPPDATA%\hermes on Windows, ~/.hermes elsewhere

The packaged .app/.exe still ships a read-only payload at
process.resourcesPath/hermes-agent (FACTORY_HERMES_ROOT). On first launch
or after an installer-driven upgrade we sync factory -> active, then
provision the venv and run pip install -e . against the active root.

Key behaviors
- Pin HERMES_HOME in the spawned Python's env so get_hermes_home() resolves
  to the same path resolveHermesHome() picked. Without this, Python falls
  back to ~/.hermes on every platform - fine on mac/linux, a split-state
  bug on Windows where our default is %LOCALAPPDATA%\hermes.
- Detect developer installs by .git presence at ACTIVE; never overwrite
  a user's checkout via factory sync.
- Marker at ACTIVE/.hermes-desktop-runtime.json (schema v4) tracks
  pyproject hash + factory version + runtime schema version. depsFresh
  fast-paths when nothing changed.
- Dev (npm run dev) prefers SOURCE_REPO_ROOT over ACTIVE so devs run
  their local edits, not whatever's under HERMES_HOME.
- Better error messages distinguish "no payload" from "no Python".
- Preserve a legacy ~/.hermes on Windows when no %LOCALAPPDATA%\hermes
  exists, so users with prior pip/manual installs aren't orphaned.

pyproject.toml
- Promote fastapi, uvicorn[standard], ptyprocess (non-Windows), and
  pywinpty (Windows) to main dependencies. The dashboard backend
  (hermes dashboard) needs them at runtime; the previous lazy-import
  fallback was a footgun for fresh installs.
- Empty the [pty] optional-extra; kept as a no-op back-compat alias for
  any existing pip install hermes-agent[pty] invocations.

Drops the hardcoded BUNDLED_RUNTIME_REQUIREMENTS list in main.cjs - the
desktop now installs whatever pyproject.toml says, single source of truth.

Files
- apps/desktop/electron/main.cjs:    runtime layout, HERMES_HOME pin,
                                      factory->active sync, marker v4
- apps/desktop/scripts/test-desktop.mjs:  track new venv location
- apps/desktop/README.md:            new Setup, Runtime Bootstrap, and
                                      Debugging sections
- pyproject.toml:                    fastapi/uvicorn/pty backends in main
                                      dependencies; [pty] extra emptied

Tested locally on Windows: npm run dev boots cleanly, sessions land at
the new location, type-check + lint + test:desktop:platforms all pass.
Verified end-to-end on a fresh Win11 VM via dist:win installer.

Known gaps (filed as follow-ups, not in this PR):
- Skills not seeded on packaged installs (sync_skills only runs in
  cmd_chat, not cmd_dashboard). Need to move to shared pre-dispatch.
- Git Bash not bundled or detected; agent's terminal tool errors out
  with a useful message but desktop bootstrapper should pre-flight it.
- install.ps1 / install.sh should be decomposed into composable phase
  libraries so the desktop bootstrapper can reuse them as a single
  source of truth across all install surfaces.

* feat(desktop): theme polish, prose chat typography, composer chrome

- DS tokens/midground, Backdrop, scoped scrollbars, typography plugin + prose
- Composer liquid/radius utilities, thread font parity, tool/thinking cues
- File tree label scale, preview flex, thread retry loading + streaming tests

* feat(desktop): NSIS prereq detection page + auto-install via winget

The packaged Windows installer now detects Python 3.11+ and Git for Windows
at install time and offers to install missing prereqs via winget. Mirrors
the prereq logic scripts/install.ps1 already runs for CLI installs, so
desktop installer users get the same out-of-the-box experience as
install.ps1 users.

Why
- Hermes' terminal tool calls bash.exe directly (tools/environments/
  local.py); on Windows that's Git Bash from Git for Windows. Without it,
  the agent fails on the first terminal() call.
- Hermes' Python runtime needs 3.11+. Without it, the desktop bootstrapper
  errors out at venv creation.
- Both gaps surfaced on a fresh Windows 11 VM smoke test: VM had Python
  pre-installed but no Git, so the agent's first terminal call failed
  with "Git Bash isn't installed."
- install.ps1 has had Install-Git + Install-Uv functions for ages. The
  desktop installer was the asymmetric outlier.

How — NSIS prereq page
- New file: apps/desktop/installer/prereq-check.nsh (plugged into
  electron-builder via build.nsis.include)
- Real Wizard page using nsDialogs, inserted via customPageAfterChangeDir
  hook (between the Directory page and InstFiles).
  - Group boxes for Python and Git, each showing detection status.
  - Pre-checked install checkboxes when winget is available.
  - Auto-skips silently if both prereqs are already installed.
  - Falls back to manual download URLs when winget itself is missing.
- Detection:
  - Python: probes `py -3.11`/`-3.12`/`-3.13`/`-3.14` via the Python
    launcher. Microsoft Store "Python stub" (no py.exe) is correctly
    classified as not-installed.
  - Git: `where git`.
  - winget: `where winget` (Win10 1809+ / Win11 with App Installer).
- Install execution (in customInstall macro):
  - Python: nsExec::ExecToLog with `--scope user --silent`. Per-user
    install, no UAC prompt, output streams to install log.
  - Git: ExecShellWait via Windows ShellExecute. Critical because Git
    always installs per-machine and triggers UAC; ShellExecute preserves
    the foreground focus chain across non-elevated → elevated process
    spawns, so UAC actually comes to the foreground. nsExec::ExecToLog
    breaks the chain because winget runs hidden.
  - Both pass `--disable-interactivity --accept-package-agreements
    --accept-source-agreements` to suppress winget's own dialogs.
- Verification: probes Git's standard install locations via FileExists
  rather than `where git`. NSIS's process inherits PATH at startup, so
  a freshly-installed Git won't be visible to `where` until restart.
- Silent installs (/S) skip the prompts; managed deploys handle prereqs
  out-of-band via Group Policy / Intune.

How — Electron-side safety net
- New findGitBash() in main.cjs, parallel to findSystemPython(). Probes
  the same locations as tools/environments/local.py:_find_bash() so a
  positive result here means the agent's terminal tool will work.
- ensureRuntime now throws a clear, actionable error on Windows when Git
  Bash isn't found, matching the existing "Python 3.11+ is required"
  error path.
- Catches users the NSIS page doesn't: .msi installer users (NSIS prereq
  page doesn't run for MSI), `npm run dev` users, manual installers,
  anyone who unchecked the install boxes on the NSIS prereq page.
- All gated on `IS_WINDOWS`; macOS / Linux unaffected.

NSIS build issue (resolved)
- electron-builder defaults to `-WX` (warnings as errors). NSIS optimizer
  emits "warning 6010: function not referenced" for our page functions
  because Page custom directives don't count as references in its
  static-analysis pass. The functions ARE called at runtime when NSIS
  invokes the page; the optimizer just can't see it statically.
- Set `build.nsis.warningsAsErrors=false` in package.json so this
  spurious warning doesn't fail the build. (Documented option from
  electron-builder's nsisOptions.)

Out of scope (filed for future work)
- MSI prereq detection: Windows Installer custom actions are a different
  mechanism. Enterprise deploys typically handle prereqs via GP/Intune.
- Bundle PortableGit + python-build-standalone in extraResources for
  zero-network installs. ~80MB increase.
- Mac / Linux GUI prereq flows (different installer formats; Xcode CLT
  covers most macOS prereqs already; Linux is per-distro hard).

Files
- apps/desktop/installer/prereq-check.nsh   (new, ~290 lines NSIS)
- apps/desktop/package.json                 (build.nsis.include +
                                              warningsAsErrors)
- apps/desktop/electron/main.cjs            (findGitBash + preflight)
- apps/desktop/README.md                    (Runtime prerequisites
                                              section)

Cross-platform impact
- macOS / Linux builds (dist:mac, dist:mac:dmg, dist:mac:zip): nsis
  config is ignored entirely; .nsh is dormant.
- npm run dev: .nsh dormant; main.cjs preflight gated on IS_WINDOWS.
- scripts/install.ps1, scripts/install.sh: no reference to any new
  files; CLI install paths untouched.
- Hermes CLI / dashboard / gateway: no reference; runtime untouched.
- All checks: node --check on main.cjs and test-desktop.mjs pass;
  npm run test:desktop:platforms 4/4 passing; node --test green.

Tested
- npm run dist:win produces signed .exe and .msi without errors.
- Fresh Win11 VM (Python pre-installed, no Git): prereq page renders,
  Python check shows detected, Git checkbox pre-checked. Click Next →
  Git installs via winget with UAC prompt in foreground.
- After install completes, Hermes launches and the agent's terminal
  tool can run bash commands. Verified Git Bash is detected at
  `C:\Program Files\Git\bin\bash.exe` by ensureRuntime's preflight.

* feat: theme changes, composer tweaks, in app update ux, finesse

* fix(cli): seed bundled skills on dashboard + gateway entrypoints

`sync_skills(quiet=True)` was only being called from inside `cmd_chat`,
which meant `hermes dashboard` (the desktop GUI's backend) and `hermes
gateway` (Telegram/Discord/Slack/etc daemons) never seeded the bundled
skill library into ~/.hermes/skills/.

This surfaced as "No skills found" in the desktop GUI's skills panel on
fresh installs, despite the agent having access to the full bundled
library when invoked via `hermes chat`. scripts/install.ps1 worked
around it by running skills_sync.py as part of Copy-ConfigTemplates,
but that's not part of the desktop installer's bootstrap chain.

Fix
- Extract the skills-sync block from cmd_chat into a module-level
  `_sync_bundled_skills_quietly()` helper.
- Call the helper from cmd_chat (preserving existing behavior),
  cmd_dashboard (after the --status/--stop early-return paths and
  fastapi import check, so we don't run skills_sync on management
  commands or when deps aren't installed), and cmd_gateway.

Why these three entrypoints
- cmd_chat: the user's primary CLI entrypoint
- cmd_dashboard: the desktop GUI's backend; this is what `hermes
  dashboard --tui` invokes when the desktop bootstrapper spawns Hermes
- cmd_gateway: long-running daemons where the user expects the agent
  to have full skill access

Other entrypoints (cmd_config, cmd_doctor, cmd_login, cmd_status,
etc.) are management commands that don't need skill discovery and were
never running skills_sync in the first place — leaving them alone.

Idempotence
- tools/skills_sync.py is manifest-based: skipped skills cost
  milliseconds. Calling it from multiple entrypoints adds no real
  cost, and users running `hermes chat` then `hermes dashboard` get
  two fast no-ops on the second call.

Failure handling
- Helper wraps skills_sync in try/except. Skills are an enhancement,
  not a hard dependency — Hermes runs fine with an empty skills/ dir.

Files
- hermes_cli/main.py:
  + new helper `_sync_bundled_skills_quietly()` at module level
  + cmd_chat: replace inline block with helper call
  + cmd_dashboard: add helper call after fastapi import succeeds
  + cmd_gateway: add helper call before delegating to gateway_command

* feat(desktop): hoisted todo widget, JSON tool summaries, history grouping & timer fixes

- Hoist todo to first-class widget (shadcn checkboxes, brand colors, no
  tool-accordion). Header derives label from active task; non-active rows fade.
- Replace raw JSON dumps with structured key/value summaries via
  formatToolResultSummary; nested error extraction for clearer failures.
- Fix loaded-session grouping: stitch interleaved assistant/tool iterations
  into one bubble instead of orphaned synthetic messages.
- Stable tool/thinking timers via keyed registry so unmount/scroll doesn't
  reset elapsed counts; gate "running" on real live thread state.
- Reorganize chat-only assistant-ui components under components/chat/.

* fix(desktop): address CodeQL alerts on PR #20059

- settings/helpers.ts: harden setNested against prototype pollution.
  POLLUTING_PATH_PARTS check is now applied at every assignment site
  (loop + leaf) and uses Object.defineProperty so CodeQL can see the
  guard inline rather than via a helper function call.

- lib/markdown-preprocess.ts: rebuild the dangling-fence close regex
  from a fence-char + length instead of marker.replace(...). The marker
  is captured by `(`{3,}|~{3,})` so it can only be backticks or tildes,
  but CodeQL was tracing tainted input text into the RegExp source and
  flagging hostname dots from input as part of the pattern (false
  positive js/incomplete-hostname-regexp on the test fixture URLs).
  Reconstructing from a literal char breaks the dataflow.

- scripts/notarize-artifact.cjs: drop args from the run() rejection
  message. Args carry --key-id / --issuer / key file path; the existing
  outer catch already squashes errors to a generic line, but CodeQL was
  flagging the args.join(' ') as clear-text logging of APPLE_API_KEY_ID.

Composer DOM-text-as-HTML alerts (composer/index.tsx:379, :547) are
already addressed in 4dd9732a9 — innerHTML assignment was replaced with
renderComposerContents which builds DOM via replaceChildren / append
text nodes (no HTML interpretation).

* fix(desktop): inline prototype-pollution guard so CodeQL sees it

CodeQL's dataflow doesn't follow the helper-function guard inside
`safeSet`, so it kept flagging Object.defineProperty as prototype-
polluting. Inline the literal `__proto__`/`constructor`/`prototype`
check at the assignment site to break the dataflow.

Behavior unchanged — same set of disallowed keys, same throw.

* feat(ui-tui): resolve links to readable page titles

Mirror desktop pretty-link behavior in the TUI by resolving HTTP links to page titles with shared caching and safe fetch filters, plus slug-based fallbacks so chat links stay readable even when title fetch fails.

* fix(desktop): drop RegExp from dangling-fence close detection

Previous attempt tried to break the dataflow by reconstructing the
close-fence regex from a literal char + marker.length, but CodeQL still
traced marker.length back to input and kept flagging the test-fixture
URLs as hostname-regex sources (js/incomplete-hostname-regexp).

Replace `new RegExp(...)` + `closeRe.test(body)` with a string-only
hasCloseFenceLine() helper that splits on '\n' and uses ===. No regex
on this path now, so input data can no longer reach a RegExp source.

Behavior preserved: matches lines that are (whitespace + marker +
whitespace), which is what the original `\n[ \t]*${marker}[ \t]*(?=\n|$)`
matched. All 12 markdown-text tests still pass.

* fix(process-registry): suppress windows-footgun false positive on guarded killpg

Keep the existing POSIX-only process-group teardown path, but make the
signal selection explicit via getattr and add an inline windows-footgun
suppression marker on the guarded os.killpg line so the Windows footgun
check no longer blocks CI on this intentionally platform-gated code.

* feat(desktop): reconcile live tool events, polish thread chrome, harden boot

- chat-messages: match tool rows by overlapping query/context/preview values
  so preview-first `tool.progress` rows reliably adopt later stable-id
  `tool.start` payloads instead of spawning ghost rows or mis-merging
  parallel same-name calls; preserve prior args/result across phases.
- tui_gateway: emit full args + parsed result on `tool.start` / `tool.complete`,
  drop redundant `tool.started` re-emit from `tool.progress`.
- electron/main: prefer SOURCE_REPO_ROOT before PATH `hermes` in dev so
  local backend edits actually run; split hardening helpers into
  `electron/hardening.cjs` with tests.
- thread/tool UI: one-shot enter animation keyed by stable ids, braille
  spinner for running rows, Cursor-like disclosure rows, drill-down +
  duration/count formatting via new tool-fallback-model.
- composer: extract `text-utils`, drop liquid-glass overrides.
- right-rail: split preview-pane into preview-console / preview-file.
- runtime: incremental external-store runtime + runtime-readiness gate;
  onboarding store + tests; route-resume hook test.
- regression tests for live tool reconciliation (parallel tools, id-less
  progress, preview-first rows, structured args/results).

* feat(desktop): add ripgrep to NSIS prereq page + polish layout

Add ripgrep as a third (recommended) prereq alongside Python and Git in
the NSIS prereq detection page, and clean up the page layout based on
on-VM testing.

Why ripgrep
- Hermes' search_files tool calls `rg` directly for content + filename
  search (tools/file_operations.py:1382). Falls back to grep/find from
  Git Bash when missing — works but slower and noisier (no .gitignore
  awareness).
- ~5MB winget install via `BurntSushi.ripgrep.MSVC --scope user` — no
  UAC prompt, parallel to how Python installs.
- scripts/install.ps1 already installs ripgrep as part of
  Install-SystemPackages; this brings the desktop installer to parity.

Why "recommended" not "required"
- Python and Git are hard requirements: without them the agent runtime
  or terminal tool refuses to start. The bootstrapper preflight throws.
- ripgrep is a performance enhancement: missing it just means slower
  searches. Page wording reflects this; failure to install is logged
  but doesn't show a MessageBox or block.

Layout polish (response to on-VM screenshot review)
- Wizard header now correctly reads "System Requirements" instead of
  the leftover "Choose Install Location" from the previous page. Set
  via `GetDlgItem $HWNDPARENT 1037/1038` + WM_SETTEXT — the standard
  NSIS pattern for overriding the page header on a custom Page.
- Removed redundant in-body title + verbose intro paragraph; the
  wizard header IS the title now. Body has one short intro line.
- Group boxes tightened to 26u with content positioned just below the
  groupbox title (not top-anchored status + bottom-anchored checkbox
  with empty space in the middle). All three panels + footer fit
  comfortably in 126u, well under the 140u page limit.
- Checkbox labels simplified: dropped "(per-user, no admin prompt)"
  and "(administrator approval required)" suffixes. The footer note
  still calls out UAC for Git when relevant.
- Footer text trimmed to fit cleanly without clipping.

Install order (in customInstall macro)
- Python → ripgrep → Git
- Python and ripgrep are silent and run first; Git's UAC prompt comes
  last so the user's approval interaction isn't interrupted by silent
  activity afterwards.

Skip behavior unchanged
- All three detected → page auto-skips via Abort
- Silent install (/S) → customInstall winget block skips
- User unchecks all → page advances without running winget

Files
- apps/desktop/installer/prereq-check.nsh: ripgrep detection block,
  ripgrep page panel + checkbox, ripgrep customInstall block,
  GetDlgItem header override, layout reflow
- apps/desktop/README.md: Runtime prerequisites section updated to
  list ripgrep as recommended, with manual winget command

* feat(desktop): add model-confirmation step to onboarding

After OAuth/API-key login completes, onboarding now shows a confirmation
card with the curated default model and a Change button before dropping
the user into chat. Closes the gap where the desktop's `model.default`
was empty after first launch and the agent had to fall back to whatever
heuristic happened to fire — leaving users wondering "why am I getting
sonnet-4 when I logged into Nous Portal?"

Why
- Desktop onboarding only persisted credentials, never `model.default`.
  The CLI's `hermes model` command pairs provider + model selection,
  but the desktop's onboarding skipped the model step entirely.
- Result: users saw whichever model the agent's auto-fallback picked,
  unpredictably and undocumented.
- For the BUILD demo we want users to land on the model they expect
  for their provider, with a clear "this is what you're getting" UI
  and a one-click path to change it before chatting.

How
- New `confirming_model` flow status carries the just-authenticated
  provider slug, current default model, label, and a saving flag.
- `completeWithModelConfirm()` runs after credentials succeed: reloads
  env, verifies runtime, fetches /api/model/options to find the curated
  first-model for the provider, persists it via /api/model/set, then
  transitions into `confirming_model`.
- If anything fails (no providers returned, network error), falls
  through to the previous behaviour — onboarding completes without
  the confirm step. Polish, not a hard requirement.
- All four credential paths (device_code OAuth, PKCE OAuth, external
  CLI flow, API key) now use completeWithModelConfirm instead of
  reloadAndConnect.

UI
- `ConfirmingModelPanel` shows: green "<provider> connected" banner,
  card with "Default model: <name>" + Change button, and a "Start
  chatting" CTA that finalises onboarding.
- Reuses the existing `ModelPickerDialog` (the same picker available
  from the chat shell) for the change-model UX. Search, filtering,
  multi-provider listing — all already built.
- Stacking: ModelPickerDialog defaults to z-130, which renders UNDER
  the onboarding overlay (z-1300) and breaks pointer events. Added
  optional `contentClassName` prop to ModelPickerDialog so callers
  can override; onboarding passes `z-[1310]`.

Provider-slug matching
- For OAuth flows: pass `provider.id` directly as the preferred slug.
- For API-key flows: `OPENROUTER_API_KEY` → "openrouter" via env-key
  prefix strip. Also includes the user-visible label as a fallback
  candidate.
- fetchProviderDefaultModel falls back to the first authenticated
  provider in the response if no preferred slug matches — so even a
  miss still surfaces a reasonable default.

Files
- apps/desktop/src/store/onboarding.ts:
  + new `confirming_model` flow variant
  + fetchProviderDefaultModel + completeWithModelConfirm helpers
  + setOnboardingModel (optimistic update + revert on failure)
  + confirmOnboardingModel (finalises onboarding from the card)
  - reloadAndConnect (replaced; the four call sites now go through
    completeWithModelConfirm)
- apps/desktop/src/components/desktop-onboarding-overlay.tsx:
  + ConfirmingModelPanel component
  + new branch in FlowPanel for status `confirming_model`
  + ModelPickerDialog usage with z-[1310] content class
- apps/desktop/src/components/model-picker.tsx:
  + optional `contentClassName` prop on ModelPickerDialog so the
    dialog can be stacked on top of other fixed overlays

Tested
- `npm run type-check` passes
- `npx eslint` clean on touched files
- Live test in `npm run dev`: cleared onboarding cache, walked
  through Nous device-code flow, saw confirm card with curated
  default, clicked Change → ModelPickerDialog rendered above the
  onboarding overlay with working pointer events, picked a different
  model, "Start chatting" persisted to ~/.hermes/config.yaml.

* fix(desktop): suppress generic provider warning in onboarding

Hide the red setup notice when the message is the generic missing-provider guidance, since onboarding already presents provider auth actions. Centralize provider-setup matching across desktop hooks and add coverage for the matcher.

* fix(desktop): add 2u clearance below prereq checkboxes

Group box bottom border was clipping the checkboxes by 1-2px.
Bumped each box height 26u→30u; checkboxes now sit 2u above the bottom border.

* fix(nix): refresh dashboard lockfile hash

Update the web npm deps hash in nix/web.nix to match the committed apps/dashboard/package-lock.json so bb/gui passes the nix lockfile check.

* fix(desktop): install TUI deps in release workflow

Ensure desktop release builds install the standalone ui-tui package before bundling the TUI payload.

* fix(desktop): run release builder from app package

Invoke the desktop builder through the package script so electron-builder uses apps/desktop/package.json.

* fix(desktop): expand release artifact names safely

Build desktop artifact names from workflow version/channel while preserving electron-builder platform macros.

* fix(desktop): use package artifact naming in release workflow

Let electron-builder's desktop package config provide platform-specific artifact extensions while the workflow injects the release version/channel metadata.

* fix(nix): fetch dashboard npm deps from package root

Point the dashboard npm dependency fetch at apps/dashboard so Nix can find the package lockfile after the dashboard move.

* fix(nix): build dashboard from package directory

Set the web package source root to apps/dashboard so npm patch/build phases run beside the dashboard lockfile while keeping apps/shared available as a sibling.

* feat(desktop): render LaTeX math via KaTeX after streaming completes

Add @streamdown/math plugin to the chat markdown renderer.
Inline ($x^2$) and block ($$...$$) math both supported with
singleDollarTextMath enabled. Plugin is gated to non-streaming state
to match the existing pattern for syntax highlighting — math renders
when the message completes, avoiding KaTeX re-render churn during
streaming. KaTeX CSS is imported in styles.css; ~30KB CSS + ~430KB
JS added to the bundle. Smoothness improvements during streaming
deferred to a follow-up.

* perf(desktop): memoize KaTeX renders so math streams without re-rendering

Wrap rehype-katex with a per-equation LRU cache (keyed by
displayMode + source text) and re-enable math during streaming.

Stock @streamdown/math runs rehype-katex on every markdown commit,
so each new token re-katexes every equation in the message. For
math-heavy responses (an equation derived step-by-step) that's
hundreds of ms of wasted work per token and the streaming UI
chokes. With memoization, each equation pays katex.renderToString
exactly once; subsequent tokens re-walk the tree but hit cache for
unchanged equations.

The wrapper mirrors rehype-katex's semantics exactly: same class
detection (language-math, math-inline, math-display), same
<pre>-walk-up for fenced math blocks, same parent.children.splice
replacement, same SKIP traversal, same strict-then-lenient render
strategy with VFile message reporting.

Cached children are structuredCloned on each splice so downstream
rehype plugins or toJsxRuntime can't mutate the cache.

* fix(desktop): declare katex-memo deps directly + drop per-app lockfile

katex-memo.ts (added in 112cad59b) imports hast-util-from-html-isomorphic,
hast-util-to-text, remark-math, katex, and unist-util-visit-parents but
those were never added to apps/desktop/package.json. They were silently
resolving via @streamdown/math at the workspace root, which broke the
moment `npm i --prefix apps/desktop` ran with the per-workspace lockfile
because that install only consults apps/desktop/package.json. Add them
as direct deps, plus unified/vfile/@types/hast for the type imports.

Also delete apps/desktop/package-lock.json — root package.json declares
workspaces: ["apps/*"], so npm manages all lockfile state at the root.
The stale per-app lockfile is what made `npm i --prefix apps/desktop`
diverge from the workspace install in the first place and left an empty
apps/desktop/node_modules/@assistant-ui/ stub that Vite's dep optimizer
then tried (and failed) to open at @assistant-ui/core/dist/internal.js.

* feat(desktop): disable Backdrop noise overlay by default

The noise overlay defaulted to on, which adds a busy speckle layer over
the whole window for every new user. Flip the Leva default to off; the
toggle stays in Backdrop / Noise for anyone who wants it back.

* fix(desktop): polish LaTeX rendering — currency, code blocks, brackets

Five distinct bugs surfaced from a math-heavy stress test:

1. Adjacent code fences glued together. scrubBacktickNoise's
   second-pass regex /``\s*``/g matched the LAST 2 backticks of
   one fence + whitespace + FIRST 2 backticks of the next, collapsing
   two blocks into one. Fixed with lookbehind/lookahead so we only
   match exactly 2 backticks not part of a longer run.

2. Whitespace eaten between fences and following content.
   stripPreviewTargets internally calls .trim() which strips leading/
   trailing whitespace from each split-segment. For segments between
   two fences this collapsed \n\n to '', gluing fence close to next
   block. Fixed by capturing leading/trailing whitespace at the call
   site and restoring it after the transform.

3. Currency dollar signs eaten as math. With singleDollarTextMath:true
   remark-math greedy-matched any pair of $, so '$5 ... $10' became
   one inline math span. Added escapeCurrencyDollars to escape $<digit>
   patterns to \$<digit> in prose segments (not in code). Trade-off:
   math expressions starting with a digit (rare — '$5x = 10$') get
   escaped too. Mirrors the convention in ChatGPT/Claude's UIs.

4. \(...\) and \[...\] LaTeX brackets unsupported. Models often
   emit these instead of $...$ / $$...$$. Added
   rewriteLatexBracketDelimiters preprocessor pass.

5. ```latex / ```tex blocks were being routed to KaTeX via a
   rewrite to ```math. Aligns with GitHub markdown convention:
   ```math = render as math; ```latex / ```tex = LaTeX/TeX
   source code (syntax highlighted, not rendered). Conflating them
   broke teaching/showing-source use cases. MATH_FENCE_LANGUAGES
   pruned to {'math'} only.

Also flipped parseIncompleteMarkdown to true (was !isStreaming) so
the math parser can't see $ inside streaming-but-not-yet-closed code
fences. Shiki was already deferred via defer={isStreaming} so this
doesn't introduce new tokenization cost.

Test: 18/18 existing tests still pass; one test updated to expect
escaped \$ in currency-prose-with-URL case.

* fix(desktop): detect Python via registry/filesystem; pin to 3.11–3.13

Two related fixes for Python detection on Windows:

1. py.exe (Python launcher) is missing from per-user installs that
   didn't check the launcher option, so 'py -3.X --version' alone
   misses real Python installs. User-reported case: clean Win11 +
   official Python.org 3.14 install -> 'where py' returned nothing,
   our installer offered to install Python again. Both NSIS prereq
   page and main.cjs now probe in this order:
     1. py.exe launcher (when present)
     2. PEP 514 registry: HKLM/HKCU\SOFTWARE\Python\PythonCore\<v>\InstallPath
     3. Filesystem: %ProgramFiles%\Python<v>, %LocalAppData%\Programs\Python\Python<v>
   Crucially, we never fall back to running 'python.exe' from PATH
   on Windows — the WindowsApps stub at %LOCALAPPDATA%\Microsoft\
   WindowsApps\python.exe is a redirector that opens the Microsoft
   Store window if no Store Python is installed. Triggering that
   during boot would be terrible UX. Registry/filesystem probes
   never execute the binary.

2. Drop 3.14 from the supported version set. Several Hermes deps
   (notably pywinpty, which carries Rust crates like
   windows_x86_64_msvc) don't yet publish 3.14 wheels. With wheels
   missing, 'pip install -e .' falls back to building from sdist,
   which needs a Rust toolchain — users see 'could not compile
   windows_x86_64_msvc build script' on first run. install.ps1
   sidesteps this by pinning to 3.11 via uv; the desktop installer
   doesn't yet have the same uv-managed-Python pathway, so for now
   we accept 3.11/3.12/3.13 and tell winget to install 3.11 if
   none of those are present. Revisit when the wheel ecosystem
   catches up to 3.14 (~early 2026).

* feat(desktop): Cron, Profiles, usage analytics, and titlebar fixes

- Add Cron and Profiles sidebar routes with full CRUD-style flows and API wiring.
- Extend Command Center with auxiliary task overrides and a Usage panel (7d/30d/90d).
- Fix titlebar geometry for WSL/Windows (native overlay width, tool spacing).
- Remove stray merge conflict markers from pyproject.toml optional deps.

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(title-bar): position sidebar toggle button

* feat(desktop): composer queue — queue many, edit/delete/cancel-edit, Cursor-style

Press Enter while busy with a draft to queue it; with no draft to interrupt
and send the next queued turn. Auto-drains one queued turn each time the
session settles, same as Cursor. Queue persists across reloads so an
interrupted-and-queued turn isn't lost on refresh.

Each queued row supports edit-in-composer (with explicit Save/Cancel),
send-now (↑), and delete. Drain skips only the entry currently being
edited so the rest of the queue keeps flowing.

Queue dequeue is transactional — an entry only leaves the queue after
`prompt.submit` is accepted, so a rejected submit doesn't drop the turn.

Also shrinks the `[interrupted]` marker to a muted one-liner and drops
its assistant footer so it stops looking like a real reply.

* fix(desktop): handle empty usage analytics totals

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(desktop): address PR review titlebar and usage races

Co-authored-by: Cursor <cursoragent@cursor.com>

* feat(desktop): add MCP settings and live subagent tree

Surface configured MCP servers in Settings with JSON edit/save and a gateway-backed reload action so users can manage tool servers without falling back to slash commands.

Track live subagent gateway events in a desktop store, show active subagent counts in the Agents statusbar item, and replace the Agents overlay stub with a live spawn tree for the active session.

* fix(desktop): move power-user views out of sidebar

Keep Cron and Profiles available through lower-prominence chrome entry points so the workspace sidebar stays focused on core chat navigation.

Co-authored-by: Cursor <cursoragent@cursor.com>

* refactor(desktop): subagent overlay reads like a live transcript, not a dashboard

Strip the card chrome and rewire /agents to feel like peeking into the
child agent's stream:

- subagents store: single `stream` of typed entries (thinking/tool/progress/
  summary) replaces the parallel notes/thinking/tools arrays. Drop unused
  fields (toolsets, depth, apiCalls, reasoningTokens, sessionId).
- agents view: no OverlayCards, no boxed stream, no per-row borders. Goal +
  status pill + indented stream lines, full row width.
- Group root spawns into "Delegation N" sections when batch shape + spawn
  time match — hides task-index interleaving and makes hierarchy obvious.
- Sort tree by spawn time, then task_index. Step indicator is one colored
  pill (primary while running, emerald when done) inside the row, not a
  trailing pill that wrapped under the chevron.
- Tree picks up `subagent.start` (not only `spawn_requested`) and prunes
  delegate-tool fallback rows once native subagent events land for the
  session — fixes duplicate "Delegated task" rows alongside the real ones.

* feat(desktop): Esc closes every OverlayView-based overlay

Lift the keyboard handler into the shared OverlayView so Agents, Settings,
Command Center — and anything we build on top of it later — all dismiss on
Esc by default. Nested Radix dialogs stop propagation themselves, so a
modal opened inside an overlay (e.g. model picker inside Settings) still
closes the modal first, not the overlay underneath.

Drop the now-redundant Esc handlers in Settings (kept Cmd/Ctrl+P) and
Command Center.

* fix(desktop): drop numbered step pill on subagent rows

The pill was getting clipped at the overlay edge anyway. Just use the
status glyph (●/✓/✗/■/○) — the delegation header already conveys
"3 workers, 3 active", and order in the list implies which step you're
looking at.

* fix(desktop): drop noisy "returned N items / empty object" stub strings

When a tool returns nothing useful, the row should be silent — the title
("Search Files", etc.) already tells the user what happened. Counting the
fields in an opaque payload is engineer-noise.

`formatToolResultSummary` and `minimalValueSummary` now return '' for
empty arrays / records / unrecognized values; tool-fallback already hides
the detail section when its body is empty.

* refactor(desktop): subagent rows borrow chat tool patterns (fade-in, lucide glyphs, shimmer)

Pull the agents view closer to how chat tool blocks render:
- statusGlyph() returns the same lucide BrailleSpinner / CheckCircle2 /
  AlertCircle vocabulary as tool-fallback's statusGlyph
- Stream lines fade-in via useEnterAnimation (one-shot WAAPI), keyed per
  entry so streamed deltas settle in instead of popping
- Subagent rows fade in too, and pick up the existing data-slot=tool-block
  spacing rules between blocks
- Active stream line trails a BrailleSpinner instead of a hand-rolled
  pulsing rectangle
- Goal text drops FadeText (which forces nowrap); keep FadeText only for
  the single-line meta subtitle
- Running rows shimmer the title — same affordance the chat thinking row
  uses

* refactor(desktop): make /agents subagent-only, drop sidebar + dead sections

Activity rail and History stub were both noise. Strip the split layout,
sidebar, route enum, and the rail/stub helpers — the overlay is now just
the spawn tree, centered in a max-w-3xl column so it stops claiming the
whole screen for one section's worth of content.

* feat: update cron modals

* Add dedicated GUI log stream for dashboard debugging.

Capture dashboard and PTY websocket lifecycle failures in gui.log and expose it via hermes logs.

* Improve desktop runtime UX by surfacing inference readiness in gateway status and hardening WSL link opening.

This also stabilizes markdown code/table block spacing and adds root-install guards so desktop dev runs use a healthy workspace dependency tree.

* Log detailed GUI websocket failure metadata.

Capture richer reject/disconnect/send/parse context for dashboard gateway websocket flows so GUI connection failures are diagnosable from logs.

* Default dashboard startup logging to GUI mode.

Detect the dashboard subcommand during early CLI bootstrap so gui.log is attached from process start and GUI startup failures are always captured.

* Clean up gateway status conditionals and logging bootstrap mode detection.

Simplify nested dashboard gateway status branches for readability and use a concise first-subcommand check when selecting early GUI logging mode.

* add logging to nsis installer

* feat: glass ui pass

* fix(desktop): persist inline assistant errors across hydrate/resume

- Detect provider failure text arriving via message.complete
  (HTTP 4xx, "API call failed after N retries", Provider/Gateway
  error: ...) and persist as an inline assistant error instead of
  regular completion text, blocking the hydrate that was wiping it.
- preserveLocalAssistantErrors: merge by id so same-id hydrated
  messages keep their local error, and preserve the optimistic
  user+error pair as a unit (with tail-user dedupe).
- Hook all hydrate/resume writers (use-session-actions resume +
  fallback, hydrateFromStoredSession, syncSessionStateToView) into
  the merge so stale snapshots can't clobber a failed turn.
- Add error to chatMessagesEquivalent so the resume diff actually
  sees error-only changes and paints them.
- editMessage on a failed turn now submits a plain resend (no
  truncate_before_user_ordinal) and retries plainly on the
  "no longer in session history" race.

Style polish on touched files:
- Inline error: text-only treatment (no card).
- User stop / edit-composer send: shared Tabler IconPlayerStopFilled
  glyph + shared icon-button class slot for parity.

* feat(desktop): theme xterm with active light/dark mode

The right-sidebar terminal hardcoded a light palette, which read poorly
on the dark glass surface. Subscribe to `useTheme().resolvedMode` and
hot-swap `term.options.theme` so Shift+X (and any other mode change)
updates the terminal in place without tearing down the PTY session.

Dark mode uses xterm's built-in defaults (white fg/cursor + vivid ANSI
16) with just a transparent background so the glass shows through;
light mode keeps the existing hand-tuned overrides for legibility on a
bright surface.

* feat(sidebar): right-click + drag-reorder sessions and workspaces

- Wire right-click on session rows to open the same actions menu;
  suppresses the OS-native context menu so Windows stops looking awful.
- Share dropdown + context menu items via useSessionActions() driving
  a single declarative ItemSpec[]; render polymorphic over MenuItem.
- New shadcn ContextMenu primitive mirroring DropdownMenu styling.
- Restore drag-and-drop reordering for Agents (lost during the cwd
  cleanup) and add reordering of workspace groups via a right-side
  grab handle. Pinned reorder unchanged.
- Generic orderByIds<T> replaces the duplicated session/group orderers;
  useSortableBindings() hook collapses the two Sortable wrappers.
- cursor-pointer on every actionable element; cursor-grab on handles.
- KISS pass: baseName() helper, AGE_TICKS table, single WORKSPACE_PAGE
  constant, flatter SidebarSessionsSection render.

* feat(desktop): solarize the xterm palette in both light & dark

xterm's default ANSI 16 is tuned for dark and reads candy-bright on the
light glass surface (vivid cyans/greens). Ship the canonical Solarized
palette (Schoonover) for both modes — same 16 accents either way, only
fg/cursor swap between `base00/01` (light) and `base0/1` (dark), so a
prompt's colors look uniform across a Shift+X toggle.

Background stays transparent in both modes — Solarized's cream/slate
backgrounds would fight the glass.

* feat(desktop): virtualize chat thread + sidebar via TanStack Virtual

Replaces `use-stick-to-bottom` and per-row session rendering with
`@tanstack/react-virtual`, matching what Cursor uses.

Chat thread (`thread-virtualizer.tsx`):
- Natural-flow virtualization (padding spacers, not absolute items) so
  `position: sticky` on the human bubble still resolves cleanly against
  the scroller.
- Custom at-bottom anchor: pins when armed, disarms on user-driven
  upward scroll, re-arms at bottom, jumps on session switch +
  `thread.runStart`.
- Loading indicator and `--thread-last-message-clearance` move to a
  real `[data-slot=aui_composer-clearance]` node; drops the brittle
  `:nth-last-child(1 of …)` rule that can't fire reliably under
  virtualization.

Sidebar (`virtual-session-list.tsx`):
- Flat agents list virtualizes at >=25 rows; pinned and
  workspace-grouped paths stay direct-render.
- `SortableContext` keeps all IDs; only the window mounts; dnd-kit's
  `setNodeRef` is merged with `virtualizer.measureElement` so rows
  participate in both DnD hit-testing and TanStack measurement.

Drops `use-stick-to-bottom`. Streaming test gets a global
`offsetWidth/offsetHeight` stub so the virtualizer's viewport sizing
works in jsdom; the scroll-up-doesn't-pull-back invariant still passes.

* feat: more ui qa

* fix(desktop): trim sidebar terminal startup spacer

Drop zsh's initial spacer row before writing the first terminal prompt so new sidebar terminal sessions do not open with a selectable blank line.

* chore: uptick

* feat(desktop): thin installer + first-launch install.ps1 bootstrap

Converges the Windows packaged desktop installer onto a single canonical
install topology: drop the Electron shell only (~80MB instead of ~500MB),
clone Hermes Agent at a build-time-pinned commit on first launch via
install.ps1's stage protocol, and treat the resulting git checkout at
%LOCALAPPDATA%\hermes\hermes-agent\ as the canonical install location
(same path the CLI installer uses).  Future updates flow through the
existing applyUpdates() git-pull path.

Replaces the previous fat-installer architecture where the .exe bundled
a pre-staged hermes-agent source tree under resources/hermes-agent/ that
was then sync'd into ACTIVE_HERMES_ROOT at launch -- a complicated
factory-vs-active dance with several footguns (FACTORY_HERMES_ROOT
mismatch on path resolve, isGitCheckout guard regressions, pyproject
hash drift detection inside the sync loop).

Architecture overview
---------------------

  Build time
    apps/desktop/scripts/write-build-stamp.cjs writes
    apps/desktop/build/install-stamp.json with {commit, branch, builtAt,
    dirty}.  Honours $GITHUB_SHA / $GITHUB_REF_NAME in CI, falls back to
    `git rev-parse HEAD` locally.

    apps/desktop/scripts/stage-native-deps.cjs copies the runtime subset
    of @homebridge/node-pty-prebuilt-multiarch from the workspace-root
    node_modules into apps/desktop/build/native-deps/.  Workspace dedup
    hoists this dep to the root, out of reach of electron-builder's
    `files:`-restricted collector; staging gives us a deterministic
    path to extraResources.

    electron-builder ships both into resources/install-stamp.json and
    resources/native-deps/ respectively.

  Boot resolver (electron/main.cjs)
    Resolver order:
      1. HERMES_DESKTOP_HERMES_ROOT override
      2. SOURCE_REPO_ROOT (dev mode)
      3. ACTIVE_HERMES_ROOT git checkout WITH .hermes-bootstrap-complete
         marker -- the post-install fast path
      4. `hermes` on PATH (CLI-installed user adding the desktop)
      5. pip-installed hermes_cli via system Python
      6. bootstrap-needed sentinel -> hand off to runBootstrap

    Deletes the entire FACTORY_HERMES_ROOT / RUNTIME_MARKER /
    syncTreeExcludingVenv machinery (-200 lines).  The isGitCheckout
    guard that bit us in the install.ps1 PR is gone.

  First-launch bootstrap (electron/bootstrap-runner.cjs)
    1. Resolve install.ps1: prefer SOURCE_REPO_ROOT/scripts (dev), else
       download from GitHub raw at INSTALL_STAMP.commit (cached at
       HERMES_HOME\bootstrap-cache\install-<sha>.ps1).
    2. Fetch the stage manifest via install.ps1 -Manifest -Commit X
       -Branch Y.
    3. Iterate stages: install.ps1 -Stage <name> -NonInteractive -Json
       -Commit X -Branch Y per stage.
    4. On all stages green: write the .hermes-bootstrap-complete
       marker with {schemaVersion, pinnedCommit, pinnedBranch,
       completedAt, desktopVersion}.

    Per-run log to HERMES_HOME\logs\bootstrap-<ts>.log.  Cancellation
    via AbortSignal.  Manifest cache so retries don't re-download.

  Install overlay (src/components/desktop-install-overlay.tsx)
    Mounted alongside the existing onboarding overlay; flexbox card
    with header (static) + middle (scrollable) + footer (failure-only,
    static).  Subscribes to hermes:bootstrap:event IPC + resyncs from
    hermes:bootstrap:get on mount/reload.  Renders:
      - 14-stage checklist with per-stage state icons
      - Overall progress bar + current-stage spotlight
      - Auto-expanded installer-output panel on failure
      - "Copy output" button (full ring buffer + error to clipboard)
      - "Reload and retry" wired through hermes:bootstrap:reset to
        clear main.cjs's latched failure
    Synthetic empty-manifest event from main.cjs flips the overlay to
    'active' immediately so the slow install.ps1 download doesn't
    leave the user staring at the generic Preparing splash.

  Failure latching (main.cjs)
    bootstrapFailure module-scope variable holds the rejection after
    install.ps1 fails.  startHermes() throws the latched error
    immediately when set, bypassing the entire ensureRuntime +
    runBootstrap chain.  Without this, the renderer's ensureGatewayOpen
    retries would re-run install.ps1 in a 5-10 min hot loop while the
    user was still reading the failure overlay.  Cleared via
    hermes:bootstrap:reset on user-driven retry.

  Unsupported-platform overlay (1F)
    macOS / Linux packaged builds (no install.sh stage protocol yet)
    emit an unsupported-platform event with a copy-pasteable install
    command + docs URL.  Dedicated overlay branch with "Copy command"
    + "I've run it -- retry" buttons.

install.ps1 additions (Phase 1F.3 + 1F.5)
-----------------------------------------

  New -Commit and -Tag string params.  Precedence Commit > Tag >
  Branch.  Honoured by all three code paths (update / fresh clone /
  ZIP fallback), with archive URL selection that handles each
  ref-type variant.  Detached-HEAD checkouts intentionally -- they're
  pins, not branches the user pulls into.

  EAP=Continue wrap around the new pin-step git invocations.  `git
  fetch origin <commit>` writes the routine 'From <url>' info line to
  stderr; under the script's global EAP=Stop that terminates the
  script even though fetch+checkout succeed.  Matches the established
  pattern in Install-Uv, Test-Python, _Run-NpmInstall.

Backend fix (hermes_cli/web_server.py)
--------------------------------------

  CORS allow_origin_regex now accepts Origin: 'null'.  Packaged
  Electron loads index.html via file://; Chromium sets the WebSocket
  upgrade Origin header to the opaque origin 'null', which the old
  regex rejected with HTTP 403 before gateway_ws() ever ran.  This
  failure mode was masked in the older FACTORY_HERMES_ROOT
  architecture because the resolver often found an existing hermes
  on PATH with different binding behavior.

  Security maintained: localhost-only bind keeps cross-machine pages
  out; per-process session token still gates every authenticated
  /api/ endpoint regardless of Origin.

Desktop QoL
-----------

  DevTools is now enabled in packaged builds (F12 / Cmd+Opt+I).
  Field-debugging trade-off: tiny attack surface increase versus
  a much better support story when CSP / WS / theme issues surface.

  NSIS prereq-check page deleted (-767 lines).  The standard
  Welcome -> License -> Directory -> InstallFiles -> Finish wizard
  now installs without custom Python/Git/ripgrep detection -- those
  prereqs are install.ps1's job at first launch.

Test infrastructure (Phase 1G)
------------------------------

  apps/desktop/scripts/test-desktop.mjs rewritten as a cross-platform
  bundle validator (was darwin-only and asserted on dead factory-
  payload paths):
    NEGATIVE: hermes_cli/main.py is NOT shipped (regression guard)
    POSITIVE: install-stamp.json carries a real commit + branch
    POSITIVE: node-pty native deps shipped under resources/native-deps
    POSITIVE: renderer dist/index.html reachable (asar or unpacked)
  New nsis mode and npm run test:desktop:nsis script.

Validated end-to-end on clean Win10 VM
--------------------------------------

  Confirmed: NSIS installer drops Electron shell, app launches,
  install overlay shows progress, install.ps1 clones the pinned
  commit, 14 stages run to completion, marker written, backend
  spawns, WebSocket connects, onboarding overlay asks for API key,
  main UI loads, integrated terminal works.

  Failures handled: bootstrap stays failed (no hot-loop retry),
  "Copy output" gives actionable transcript, "Reload and retry"
  explicitly re-runs install.ps1.

What's deferred
---------------

  - MSIX wrapping (Phase 2): same Electron .exe under MSIX manifest
    with runFullTrust, signed and submitted to Microsoft Store.
  - install.sh stage protocol parity (Phase 2): once shipped, the
    unsupported-platform overlay becomes drive-it-yourself and
    macOS/Linux packaged installers gain feature parity with Windows.

* feat(desktop): persistent terminal pane + fullscreen takeover

Adds a VSCode-style "focus terminal" toggle to the right sidebar's Terminal
tab that takes over the chat pane area without unmounting the shell. The
xterm host is mounted once at the layout root and CSS-overlayed onto
whichever <TerminalSlot /> is currently active, so the PTY session,
scrollback, selection, focus, and WebGL renderer survive every toggle.

Also:
- WebGL renderer (matching dashboard ChatPage) so Hermes' TUI skins paint
  faithfully instead of muting through xterm's default DOM renderer
- File drag/drop from the project tree or OS into xterm — paths are
  shell-quoted (zsh/bash/pwsh/cmd) and written straight into the PTY
- Solarized dark canvas with brights promoted to real accent variants
  (Schoonover's UI-gray brights washed out every TUI accent)
- Strip NO_COLOR/FORCE_COLOR/COLORFGBG/TERM=dumb leaking from non-tty
  parents (CI runners, Cursor's agent shell) so the embedded shell gets
  truecolor regardless of how Electron was launched
- rAF-debounced ResizeObserver — running fit.fit() synchronously during
  sibling pane transitions crashed the WebGL texture-atlas rebuild

* fix(install.ps1): strip UTF-8 BOM regression that broke 'irm | iex'

The canonical install flow

    irm https://raw.githubusercontent.com/.../scripts/install.ps1 | iex

fails on PowerShell 5.1 with a cascade of 'The assignment expression
is not valid' errors at every param() default value:

    [string]$Branch = 'main',
                      ~~~~~~
    The assignment expression is not valid. The input to an assignment
    operator must be an object that is able to accept assignments...

Root cause: scripts/install.ps1 carries a UTF-8 BOM (0xEF 0xBB 0xBF)
as its first three bytes. 'irm' returns the response body as a string;
on PS 5.1 the BOM survives into that string as a leading \ufeff
character. 'iex' then evaluates the string and PS's parser chokes
on the invisible character before param() -- error recovery proceeds
into the body but every assignment is reported as broken.

This was the exact failure mode the install.ps1 hardening pass (PR
#27224) deliberately fixed by stripping the BOM and ensuring the
file body is pure ASCII. Commit 4279da4db ('fix(windows): make
PowerShell installer parse in 5.1') re-introduced the BOM later,
unintentionally undoing the irm|iex compatibility fix; the merge
that brought it into bb/gui carried it forward.

Fix: strip the three BOM bytes. File body is verified pure ASCII
(any-byte > 127 returns false), so PS 5.1 with no BOM falls back to
Windows-1252 decoding which is identical to ASCII for our content.
Both install paths now work:
  - 'irm ... | iex' (canonical CLI)
  - 'powershell -File install.ps1' (programmatic / desktop bootstrap)

* install.ps1: detect ARM64 Windows reliably for Node and Git stages

Add a Get-WindowsArch helper that reads Win32_Processor.Architecture
via CIM (invariant to PowerShell host bitness) with PROCESSOR_ARCHITEW6432
fallback. Use it in:

- Install-Git: previously only triggered the arm64 PortableGit asset
  when invoked from a native-ARM64 PowerShell host. WoW64 / emulated
  x64 hosts (the default powershell.exe on Windows-on-ARM) saw
  PROCESSOR_ARCHITECTURE=AMD64 and fell through to the x64 PortableGit
  build, leaving ARM64 users on emulated Git for Windows.

- Test-Node: previously hardcoded the Node download to win-x64 on any
  64-bit OS, so ARM64 users always got x64 Node under Prism emulation
  even though Node ships an arm64 build for Windows. The winget
  fallback now also passes --architecture arm64 on ARM64.

Python remains x86_64 by design: uv intentionally prefers
windows-x86_64 cpython on ARM64 hosts for ecosystem (wheel)
compatibility (see astral-sh/uv#19015).

* install.ps1: harden Install-SystemPackages against winget msstore failures

The previous winget invocation discarded stdout/stderr and trusted no
signal at all -- not the exit code (winget exits 0 even when it bails
"please specify --source"), not output (sent to Out-Null), not the
catch handler (winget returning 0 means no exception fires). The only
trust signal was a post-install Get-Command rg / Get-Command ffmpeg
check, which would also miss the package because %LOCALAPPDATA%\
Microsoft\WinGet\Links (where winget puts command aliases) is added to
PATH by AppExecutionAlias machinery only in fresh shells. End result on
machines where the msstore source has a cert problem (0x8a15005e --
common on Windows-on-ARM and some corporate networks): silent failure,
no log, no breadcrumb, and the user is told the install succeeded.

Specifically:

- Pin --source winget on every winget install call. Defeats the broken-
  msstore-source path. We ship nothing from msstore so this is safe and
  forward-compatible.

- Add --exact --id for a tighter package match.

- Capture each winget invocation's combined stdout/stderr + exit code to
  %TEMP%\hermes-winget-<pkg>-<n>.log instead of Out-Null. On the happy
  path the log is deleted after the post-install check confirms the
  binary is on PATH; on failure the log is kept and its path is named in
  a Write-Warn so the user has something to grep.

- Refresh PATH to include %LOCALAPPDATA%\Microsoft\WinGet\Links in
  addition to the User/Machine env-var hives, so Get-Command sees newly-
  installed winget aliases in the same process.

- No behavior change on the happy path. Same Write-Info/Success/Warn
  cadence, same fallback order (winget -> choco -> scoop -> manual),
  same $script:HasRipgrep / $script:HasFfmpeg outputs.

Verified end-to-end on a real Snapdragon ARM64 Windows host: ripgrep
uninstalled, stage re-run, [OK] ripgrep installed in 1.4s, ok:true.

* desktop: swap node-pty fork for upstream microsoft/node-pty 1.1.0

The previous dependency, @homebridge/node-pty-prebuilt-multiarch@0.13.1,
publishes no win32-arm64 prebuilds on its v0.13.x line, and its v0.14.x
betas (which do add an arm64 Windows build) ship no electron-vXXX-win32-
arm64 prebuilds at all -- so packaged Electron 40 builds (NMV 143) would
fail at runtime even on a successful npm install. Net effect: the
desktop's integrated terminal was unbuildable on Windows-on-ARM, in
both dev (npm install fails: 404 fetching the node-vXXX-win32-arm64
prebuilt) and packaged builds (no Electron-ABI prebuilt exists).

The homebridge fork was originally created because upstream node-pty
shipped no prebuilds at all. That hasn't been true since node-pty@1.0
(April 2024), which:

- bundles prebuilts for mac (arm64+x64) and Windows (arm64+x64) directly
  inside the npm tarball -- no GitHub-Releases fetch, no missing-binary
  failure mode
- uses N-API (node-addon-api) for ABI stability across Node and Electron
  major versions, so the same pty.node binary loads under Node 22 (dev)
  and Electron 40+ (packaged) without per-ABI rebuilds
- is what VS Code, Hyper, and Theia actually ship

API surface is identical (spawn / onData / onExit / write / resize /
kill) -- no call-site changes needed.

Specifically:

- apps/desktop/package.json: replace the @homebridge fork with
  node-pty@1.1.0 (exact pin). Widen `asarUnpack` from `["**/*.node"]`
  to also unpack `**/prebuilds/**`, because node-pty ships runtime-
  execed helpers alongside its .node files (darwin spawn-helper has no
  extension and would not be matched by `**/*.node`; conpty.dll,
  OpenConsole.exe, winpty.dll, winpty-agent.exe on Windows are also
  exec'd at runtime and cannot live inside asar).

- apps/desktop/electron/main.cjs: update both require() strings to
  match the new package name and the new staged path under
  resources/native-deps/node-pty/.

- apps/desktop/scripts/stage-native-deps.cjs: point at node_modules/
  node-pty. node-pty's prebuilts live under prebuilds/<plat>-<arch>/
  (not build/Release/), so update the include glob to copy that dir.
  Per-arch staging keeps the resource bundle small (target arch comes
  from npm_config_arch when electron-builder cross-builds, else
  process.arch). Explicitly enumerate file types in the prebuilds glob
  so the ~25 MB of .pdb debug symbols that prebuild-install bundles
  for Windows crash analysis don't bloat the installer (29 MB -> 2.6 MB
  staged on win32-arm64). Re-assert +x on the darwin spawn-helper
  defensively, since a stripped mode bit would manifest as a silent
  ENOENT at first pty.spawn().

- apps/desktop/scripts/test-desktop.mjs: update expectedNativeDepPaths()
  and its assertion site to look at prebuilds/<plat>-<arch>/ instead of
  build/Release/. Add an explicit spawn-helper-exists check on darwin
  so a regression in the asarUnpack glob would fail loudly in CI rather
  than at first PTY spawn.

Trade-off: Linux end-users lose prebuilts and fall back to building
node-pty from source on `npm install`. Acceptable because Hermes
ships no Linux desktop builds (desktop-release.yml matrix is mac + win
only, package.json declares no `linux` target), and Linux developers
hacking on the desktop already need a C++ toolchain for the rest of
the stack.

Verified on Windows 11 ARM64 (Snapdragon):
  npm install                                          -> exit 0
  node -e "require('node-pty').spawn(...)" round-trip  -> OK
  stage-native-deps                                    -> 27 files, 2.6 MB
  load from staged tree (simulates packaged fallback)  -> ConPTY
                                                           round-trip OK

* desktop+gateway: harden Slack socket recovery and Windows restart dedupe (#28873)

* desktop+gateway: harden Slack socket recovery and Windows restart dedupe

Fix Slack Socket Mode reliability by adding a watchdog/reconnect path so silent socket task drops no longer leave the adapter stuck. Harden Windows gateway lifecycle by avoiding desktop-binary path collisions, making gateway PID scans case/extension tolerant, and reusing in-flight restart actions to prevent duplicate gateway spawns.

* test(slack): add Socket Mode watchdog/reconnect behavioural coverage

Drive the new Slack Socket Mode self-healing logic through a fake AsyncSocketModeHandler so we can simulate the P0 silent-hang failure mode (task exit, transport disconnected, intentional shutdown, concurrent reconnect attempts) without touching real Slack.

* fix(slack,desktop): address Copilot review on watchdog races and path normalization

- connect(): explicitly cancel + await the prior socket watchdog before flipping _running, so an old monitor cannot exit between teardown and respawn (Copilot #1)
- _socket_watchdog_loop: wrap the body in try/except + add a done-callback that respawns on unexpected crash, so a transient bug cannot permanently disable self-healing (Copilot #2)
- normalizeExecutablePathForCompare: use the resolved path for realpathSync so non-string inputs cannot leak through (Copilot #3)
- Add tests for crash-recovery and atomic watchdog replacement across reconnects

* fix(slack): tighten connect() error path and clarify watchdog test intent

Address Copilot review round 2.

- connect(): wrap _start_socket_mode_handler/_ensure_socket_watchdog in a focused try/except so any failure rolls back partially-started handler/task state and leaves _running=False, ensuring the platform lock is always released by the outer finally
- Defer _running=True until after the handler is actually started so the watchdog observes a live socket task immediately and never spins against a half-built adapter
- Rename test_watchdog_self_restarts_after_unexpected_crash to test_watchdog_cancellation_does_not_respawn (matches what it actually asserts) and add test_watchdog_unexpected_exit_respawns_via_done_callback that drives a real RuntimeError through _on_socket_watchdog_done and verifies a fresh task replaces the crashed one

* fix(web_server): serialize action spawn check+store under a threading lock

Address Copilot review round 3.

FastAPI runs sync handlers on its threadpool, so two near-simultaneous /api/gateway/restart (or /api/hermes/update) requests could both observe "no live process" in _spawn_hermes_action's poll-based dedupe and double-spawn. Add a module-level _ACTION_SPAWN_LOCK around the entire check + Popen + _ACTION_PROCS store sequence so the dedupe is atomic across threads.

* fix: address Copilot review round 4

- slack.disconnect(): mirror connect()'s defensive cleanup — catch the broad Exception path on watchdog await so handler shutdown and lock release still run if the watchdog raised before cancellation took effect
- web_server._spawn_hermes_action: wrap subprocess.Popen in try/except so a missing executable / permission error closes the log file handle, writes a failure marker, and re-raises instead of leaking a file descriptor
- gateway._scan_gateway_pids: drop the over-broad "hermes.exe --profile" / "hermes.exe -p" patterns that would match any Hermes CLI subcommand using a profile flag (e.g. `hermes.exe --profile foo dashboard`); rely on the "hermes.exe gateway" + "hermes-gateway.exe" tokens instead
- tests: tighten _fake_create_task to assert coroutine input and return a real asyncio.Task that stays pending until pytest teardown, and update the three callsites whose mocked AsyncSocketModeHandler.start_async returned a non-coroutine value

* fix(slack): reset multi-workspace state on reconnect

Address Copilot review round 5.

connect() is reentrant (gateway restart, in-process reconnect), but it was leaving _bot_user_id / _team_clients / _team_bot_user_ids populated from the previous session. A reconnect that rotated the primary token or dropped a workspace would silently keep the stale bot user id and stale workspace client maps, leading to dispatch against gone workspaces.

Clear these three pieces of state right after _stop_socket_mode_handler() and before the auth_test loop, then let the loop repopulate from the current tokens. Add test_reconnect_refreshes_multi_workspace_state to lock it in.

* nix: package apps/desktop as .#desktop (#28964)

Adds nix/desktop.nix building the Electron renderer with buildNpmPackage
and wrapping nixpkgs' electron binary.  Reuses .#default by setting
HERMES_DESKTOP_HERMES to its hermes binary, so the desktop's resolver
picks up the fully-wired nix hermes (venv, bundled skills/plugins,
runtime PATH) without reimplementing agent resolution.

- nix/desktop.nix: renderer + electron wrapper
- nix/hermes-agent.nix: finalAttrs form, exposes hermesDesktop in passthru
- nix/packages.nix: exposes .#desktop + adds to fix-lockfiles
- apps/desktop/package-lock.json: standalone hermetic lockfile

nix build .#desktop && nix run .#desktop both clean.

* fix(desktop): probe steps 4 & 5 of resolveHermesBackend before trusting

A user-reported failure on Windows-on-ARM: a pre-installed Python 3.13
on PATH makes findSystemPython() succeed, so resolveHermesBackend
returns a backend pointing at it -- but hermes_cli isn't in that
interpreter's site-packages. The spawn dies with ModuleNotFoundError
and the user sees a dead GUI instead of the first-launch installer.

Same shape can hit step 4 (existing `hermes` on PATH) when a stale
shim survives a partial uninstall.

Add cheap exit-code probes -- `python -c "import hermes_cli"` for
step 5, `<hermes> --version` for step 4 -- and fall through to step 6
(bootstrap-needed) on failure. install.ps1 then runs as if on a clean
box and the venv gets built.

Probes live in a standalone electron/backend-probes.cjs module so they
can be unit-tested with node --test, same pattern as bootstrap-platform.cjs
and hardening.cjs. New test file wired into test:desktop:platforms.

* test(desktop): allow `node-pty` bare-require in packaged entrypoints

Pre-existing failure on bb/gui since c858484b4 swapped the node-pty
fork for upstream microsoft/node-pty 1.1.0. main.cjs intentionally
bare-requires node-pty (it's hoisted by workspace dedup in dev, and
staged to resources/native-deps via scripts/stage-native-deps.cjs +
extraResources for packaged builds, with a try/catch fallback at
line ~38). The allowlist hadn't been updated to match -- same shape
as `electron`, which was already allowed.

* chore(deps): refresh root lockfile for dashboard @nous-research/ui 0.14.0

apps/dashboard/package.json was bumped to @nous-research/ui 0.14.0 (+
flag-icons ^7.5.0, motion ^12.38.0) but the root package-lock.json was
never refreshed. Running `npm install` from the repo root now
materialises 0.14.0's transitive closure (launder, bumps for
@nanostores/react, nanostores, sanitize-html, tailwind-merge).

No code changes; purely a lockfile catch-up so fresh checkouts on bb/gui
get a working dashboard install.

* chore(desktop): bump version to 0.0.1

First non-placeholder version so electron-builder's artifactName template
produces `Hermes-0.0.1-win-x64.exe` instead of the obviously-unreleased
`Hermes-0.0.0-...`. No release process yet; this just stops the artifact
filename from telling users "you got a debug build."

Bumped in three slots that all carry the desktop app's version:
- apps/desktop/package.json (source of truth)
- apps/desktop/package-lock.json (per-app lockfile, kept for CI parity)
- root package-lock.json's apps/desktop workspace entry

Identity-of-build for first-launch bootstrap continues to come from
build/install-stamp.json (commit SHA + builtAt), unchanged.

* fix: fs icon color

* perf(desktop): cut per-keystroke layout + listener churn in chat composer

Empirical work via CDP harnesses under apps/desktop/scripts/ (see
profile-typing-lag.md):

  jsListeners growth (per round of 200 chars + GC):
    before: +35  (verified leak — listeners stuck after 1st trigger popover use)
    after:  +0

Four narrow edits in src/app/chat/composer/index.tsx:

1. Drop the per-keystroke `editorRef.current.scrollHeight` read used to
   decide composer expansion. Replace with `draft.length > 60` heuristic;
   the existing ResizeObserver still catches edge cases. `scrollHeight`
   is a forced-layout call and was firing on every char until the first
   wrap.

2. Bucket measured composer height to 8px before writing
   `--composer-measured-height` / `--composer-surface-measured-height`
   on `documentElement`. Without this, the editor grows ~1px per char,
   setProperty fires every keystroke, computed style is invalidated tree-
   wide.

3. Remove the dead `$composerDraft` two-way sync. Nothing outside the
   composer subscribed to that atom (verified via grep). Two useEffects
   on `[draft]` were pushing draft→atom and atom→aui per keystroke for
   no consumer. Also drop the per-keystroke
   `reconcileComposerTerminalSelections` call; it was pruning stale
   labels for `terminalContextBlocksFromDraft`, but that helper already
   ignores labels not in the current submitted text, so pruning per
   keystroke was just bookkeeping.

4. `refreshTrigger` fast-bails when the draft contains neither `@` nor
   `/`. Previously `textBeforeCaret(editor)` ran on every input/keyup
   regardless; `range.toString()` inside is O(n) over draft length.

Synthetic typing latency p50/p90/p99 is similar before vs after on a
freshly-loaded session (Blink can already handle ~30cps typing into a
contentEditable on its own); the real win is the listener leak being
gone and the global computed-style invalidations dropping ~8× when the
composer is sitting at a fixed height row.

The `Enter → stall` follow-up (see profile-typing-lag.md §"Submit /
TTFT stall") is unmeasured here — needs a throwaway session because
the harness fires a real prompt. Not blocking this commit.

* perf(desktop): cut FadeText forced layouts during streaming

The slowest user-felt path is typing into the composer while the
assistant is streaming. Profile (scripts/profile-under-stream.mjs):

  FadeText measureOverflow self time:  35.8 ms → 18.1 ms  (-50%)
  total active CPU during 7s window:   ~150 ms → ~50 ms

Two changes in src/components/ui/fade-text.tsx:

1. Drop the `useEffect([children])` that re-ran `measureOverflow`
   (reads scrollWidth + clientWidth — forced layout) on every parent
   re-render. `useResizeObserver` already fires the same callback on
   mount and whenever the host span's box size changes; that covers
   the only case where overflow state can legitimately change. The
   previous explicit useEffect was a forced-layout flush on every
   parent render, which during streaming meant every token tick.

2. Wrap the component in `memo` with a custom comparator that
   short-circuits the entire render when scalar string `children` and
   the className/fadeWidth/style props are unchanged. The hot path
   was tool-fallback's title chips being re-rendered by parent
   streaming updates even though their text was stable; memo+
   comparator skips that.

Also adds two harness scripts under apps/desktop/scripts/:
  - latency-under-stream.mjs (key→paint latency while a turn streams)
  - profile-under-stream.mjs (CPU profile while a turn streams)

Updates profile-typing-lag.md with the streaming numbers and confirms
the Enter→paint submit path is already fast (≤320ms on the populated
session; the 2s "stall after Enter" the user noticed once was a
one-time cold-start, not reproducible at the UI layer).

I'd guess the felt jank in real use is fast-burst typing during a
long-form streaming reply (code blocks + markdown lists multiply the
per-token render cost). The CPU savings here scale linearly with
token volume.

* chore(desktop): drop diag scratch scripts no longer needed

* docs(desktop): correct leak-typing numbers on a real session

Re-ran the leak harness on a populated session (Phaser thread) for both
unpatched and patched builds. The original 'listener leak' was transient
warm-up cost, not a steady-state leak — both versions show 0 listener
growth/round in steady state.

The load-bearing number is forced layouts per character:
  unpatched (HEAD~2):  7.02 layouts/char
  patched   (HEAD):    2.35 layouts/char  (3× fewer)

The patches reduce per-char forced-layout work to Blink's natural floor.
Document node count and heap are flat in both builds.

* perf(desktop): fix "Enter jumps up" on long threads

User reported: after pressing Enter on a long thread, the view jumps up
— the just-submitted message disappears below the fold. Confirmed via
apps/desktop/scripts/measure-jump.mjs:

  before:  distFromBottom 0 → 49.5px, sticks there permanently
  after:   distFromBottom 0 → ~0 (worst case 4px for one frame)

Root cause in useThreadScrollAnchor (thread-virtualizer.tsx):

1. The sticky-bottom logic disarmed on any scroll event where
   `scrollTop < lastTopRef.current`. That check can't distinguish a
   user scrolling up from a programmatic `pinToBottom` write that
   the browser clamped short of bottom (because content also grew in
   the same frame, so `scrollTop = scrollHeight` lands at
   `scrollHeight - clientHeight` for the OLD scrollHeight, which is
   now below the NEW scrollHeight). Result: sticky-bottom disarmed
   permanently on the user's first submit.

2. There was no synchronous pin tied to React's commit phase. By the
   time the ResizeObserver fired and re-pinned, the user had already
   seen ~50ms of "message below the fold" — visually that reads as the
   view jumping up.

Fix:

- `programmaticScrollPendingRef` counter tracks scroll events we
  expect to be ours (one per `pinToBottom` write). The scroll handler
  skips the disarm check when consuming a pending tick, keeps the
  arm bit true, and re-pins synchronously if the browser clamped us
  short of bottom. A depth cap (8) breaks runaway loops in
  pathological streaming-burst layouts.

- `useLayoutEffect` on `groupCount` increase pins BEFORE the browser
  paints, eliminating the visible ~50ms window between optimistic
  user-message insert and the RO/scroll-event chain firing.

Verified on the long Cloud Shadows thread (7-8 turns, ~11k px tall):
all three repro runs now hold within 0–4 px of bottom across the
post-Enter transition. Submit latency unchanged (paint 77–107 ms),
streaming-typing latency unchanged.

Also adds three debug harnesses:
  - measure-jump.mjs   — sample thread scroll across Enter
  - probe-thread.mjs   — dump current thread / scroll state
  - diag-jump.mjs      — intercept scrollTop + RO + mutations across Enter

* perf(desktop): rate-limit thread auto-pin during streaming

Follow-up to the Enter-jump fix. The first version did a synchronous
re-pin loop inside the on-scroll handler when the browser clamped our
`scrollTop = scrollHeight` write short of the new bottom; that gave a
tight 4 px visible jump on Enter, but during streaming the
ResizeObserver fires many times per second as content grows, and each
RO callback re-entered the pin loop. CPU profile showed
`Virtualizer.getMaxScrollOffset` climbing to 22 ms self over a typing-
during-streaming window — the sync re-pin path was paying tanstack-
virtual's recompute cost ~3× per token.

Re-architect:

- RO callback coalesces to one pin per animation frame. Streaming-rate
  RO bursts now cost the same as a single per-frame pin.
- The on-scroll programmatic-counter guard remains (it's what prevents
  the false-disarm bug when the browser clamps a write). It no longer
  does sync re-pins; the next RO/rAF will catch up.
- The useLayoutEffect on groupCount (the path that fires on user
  submit / new turn arrival) ALSO schedules one rAF pin in addition to
  the synchronous pin. This catches the case where React mounts the
  new message in a second commit (after our layout effect ran), which
  grows scrollHeight again. Two pins instead of a tight loop, paid only
  once per turn change.

Net effect on the Cloud Shadows long thread:

  enter-jump transient:   12–20 px for 1 frame (was 49 px permanent)
  CPU during stream+type: `getMaxScrollOffset` dropped out of top-5
                          self-time list
  typing-during-stream:   p50 ~10 ms paint, p99 ~20 ms (1 frame),
                          occasional 40 ms+ outliers during burst
                          token arrivals

Also adds scripts/profile-long-stream.mjs: 20-second streaming profile
with per-500ms FPS histogram + content-length tracking, so we can see
whether streaming render cost grows with message length (it doesn't —
sustained 60 fps).

* perf(desktop): use textContent for trigger precondition

Replace composerPlainText() call inside refreshTrigger's no-trigger
fast-bail with a textContent check. textContent is a browser-native
flat traversal; composerPlainText walks recursively with chip-aware
logic. We only need to know if @ or / appears; either way the trigger
char will be in textContent because chips contain @ in their refText.

Profile shows composerPlainText was ~18ms self over a 12s typing-during-
stream window, called from refreshTrigger on every keystroke. Most of
that was the precondition check (the trigger detection path is the
slow path but only runs when a trigger char is present).

* Revert "perf(desktop): use textContent for trigger precondition"

This reverts commit a6a78ff08a31129a3a47fa55aca260d93af913a5.

* Revert "perf(desktop): cut FadeText forced layouts during streaming"

This reverts commit 88e7d7537cdab87200405edf298e38cb37e0a950.

* Revert "perf(desktop): cut per-keystroke layout + listener churn in chat composer"

This reverts commit bff1b3261d18a2427ac6c345c99f8312728346dd.

* Revert "Revert "perf(desktop): cut per-keystroke layout + listener churn in chat composer""

This reverts commit b7b378e3a43f94b9f4a1a34155707c6301c0fd87.

* Revert "Revert "perf(desktop): use textContent for trigger precondition""

This reverts commit 0739588f4896902f7f0d4ded8b5eaeb92bfdf042.

* chore(desktop): synthetic-stream perf harness + scripts

Drops the React `<Profiler>` approach (no-op because Vite is currently
serving the production React build) in favor of an externally-observable
measurement stack: rAF frame intervals, `PerformanceObserver({entryTypes:
['longtask']})`, and a `MutationObserver` on the live streaming message.

Adds a synthetic stream driver — `window.__PERF_DRIVE__.stream({...})` —
that pushes tokens through the live `$messages` atom at a controlled rate,
so the assistant-ui runtime, incremental repository, and Streamdown
markdown pipeline see the same workload they'd see during a real LLM
stream, without the LLM cost.

The driver lives in `src/app/chat/perf-probe.tsx`; `main.tsx` side-imports
it under `import.meta.env.MODE !== 'production'` so it tree-shakes out of
prod builds. (Using `MODE` rather than `DEV` because our Vite setup
currently reports `DEV=false` even under `vite dev` — see the dev-build
note in `profile-typing-lag.md`.)

Scripts:
  - measure-synthetic-stream.mjs  drive synthetic + record frame/longtask/mutation
  - profile-synth-stream.mjs      CPU profile + top self-time during synthetic
  - measure-real-stream.mjs       same harness, real LLM stream
  - profile-real-stream.mjs       CPU profile bracketing the real stream window
  - eval.mjs / reload.mjs         small CDP helpers

A real-LLM measurement on Cloud Shadows (gpt-4o-mini, 39 s window) showed
12 longtasks in the same 75-127 ms range the synthetic predicted, so the
synthetic is a faithful proxy.

* perf(desktop): memo FadeText so it skips re-renders when text unchanged

FadeText is used 110+ times inside `tool-fallback.tsx` on a tool-heavy
thread. During streaming each parent re-render previously triggered the
component's `useEffect([children])`, which forced a `scrollWidth` layout
read even when the title text was unchanged. The `useResizeObserver` was
already covering the genuine resize case, so that effect was strictly
redundant work.

Drops the effect and wraps the component in `React.memo` with a custom
comparator that field-compares `className`, `fadeWidth`, and `style`,
plus identity-compares `children` (scalar fast-path; correct for JSX
nodes too since a new node should force a re-render).

Verified via temporary render counter on the 34 MB
`session_20260514_215353_fe0ac8` thread (110 FadeText instances): a
2 s synthetic stream went from ~11k FadeText render calls to 122 —
roughly one render per truly-new instance instead of one per parent
commit per instance.

Doesn't move the longtask needle on its own (Streamdown's markdown
re-parse dwarfs it) but eliminates a steady CPU floor and a class of
forced layouts during streaming. Profile-typing-lag.md documents the
full investigation, including the remaining Streamdown cost as the
real source of the perceived "5 fps moment" hitches.

* perf(desktop): memoize MarkdownText plugins to stop churning Streamdown

The inline `plugins={{ math: mathPlugin, ...(isStreaming ? {} : { code }) }}`
on `<StreamdownTextPrimitive>` constructed a new object literal on every
parent render. That broke `<Streamdown>`'s outer memo and forced its
internal `rehypePlugins` / `remarkPlugins` array useMemos to rebuild,
which propagates a new identity into every `<Block>` and defeats Block's
memoization for stable historical blocks.

After memoizing on `[isStreaming]` (the only real dimension of variance),
CPU profile during a 5 s synthetic stream on the 34 MB session shows
`parser` self-time dropping out of the top 10, `compile` cut roughly in
half, and `bn$1` / `m$1` (micromark internals) leaving the top entries.

Doesn't move the visible longtask count on its own — Streamdown's
per-Block parse cost still dominates whenever the last block's content
changes — but it removes a class of unnecessary re-parses for historical
blocks during streaming. See `scripts/profile-typing-lag.md` for the
full investigation.

* perf(desktop): floor assistant-text flush gap to 33ms for predictable batching

`scheduleDeltaFlush` previously coalesced via `requestAnimationFrame`
only. The "at most one flush per frame" guarantee that gives you is fine
for fast streams (>~80 tok/sec) where multiple tokens arrive within a
single frame, but breaks down at typical LLM token rates (30-80 tok/sec)
where each token arrives slower than the rAF cadence and triggers its
own React commit + Streamdown markdown re-parse.

Track `lastFlushAt` and require at least 33 ms between two flushes.
React 18+ auto-batching probabilistically already collapsed some of
these, but the floor makes it deterministic.

A/B on the 34 MB session, 300 tokens at 50 tok/sec (markdown chunks):

| | avgFps | p99 frame | LTs / 5 s | max LT |
|---|---|---|---|---|
| no floor (current rAF) | 54.0 | 38 ms | 2.0 | 145 ms |
| 33 ms floor (this PR) | 54.3 | 41 ms | 1.7 | 110 ms |

`inter-mutation` p50 also tightens from 22-28 ms to a clean 33 ms,
which is the expected signature of a deterministic floor. Doesn't fully
solve the user's perceived hitches — Streamdown's per-Block parse cost
when the last block grows past ~2 k chars is still the elephant — but
it consistently shaves the worst-case longtask and makes the streaming
cadence visibly steadier.

Also threads a matching `flushMinMs` option through the synthetic
stream driver in `perf-probe.tsx` + `scripts/measure-synthetic-stream.mjs`
so the harness can A/B both regimes without spending LLM credits.

See `scripts/profile-typing-lag.md` for the full investigation.

* perf(desktop): useDeferredValue for streaming markdown so parses don't block input

Streamdown's per-Block parse cost grows with the live tail's length and
is unavoidable inside the block-memo pattern (industry standard, see
findings doc). The fix is to stop having that work block the main thread.

`<DeferStreamingText>` is a 12-line wrapper that reads message-part state
via `useMessagePartText`, runs it through `useDeferredValue`, and
re-publishes via assistant-ui's `<TextMessagePartProvider>`. The inner
`<StreamdownTextPrimitive>` reads the deferred value through the normal
`useMessagePartText` hook — no fork, no internal-path imports, fully on
assistant-ui's public API. React's concurrent scheduler then:

  - abandons in-flight deferred renders when a newer token arrives, so
    intermediate states get skipped under fast streams
  - deprioritises the markdown render when the main thread has urgent
    work (typing, scroll), so input stays responsive even while a
    100ms parse is queued

Streamdown already uses `useTransition` for its block-array setState;
this lifts the deferral up to the consumer boundary so it covers the
whole pipeline (preprocess → split → repair → parse → render).

A/B on the 34 MB session, 300 tokens at 50 tok/sec, markdown chunks
(four trials each, with the 33ms flush throttle on for both):

| | avgFps | p99 frame | LTs/5s | max LT | typing-while-stream p95 |
|---|---|---|---|---|---|
| pre  | 54.3 | 41 ms | 1.7 | 110 ms | ~17 ms |
| post | 58.5 | 31 ms | 2.0 | 117 ms | 14-18 ms |

Longtask count + max LT unchanged — useDeferredValue doesn't reduce
CPU, only its priority. The avgFps lift and p99 frame drop are the
proof that the existing CPU is no longer blocking 60 fps cadence. One
clean run logged MUTATIONS=0 — React skipped every intermediate text
state and only committed the final one (textbook deferred-value
behaviour).

The actually-reduce-CPU path is replacing the parser with a state
machine like Flowdown — left for a future PR; see
`apps/desktop/scripts/profile-typing-lag.md` for the full investigation.

* feat(desktop): add hermes gui launcher

* feat(desktop): launch packaged gui builds by default

* bump gui version to 0.0.2

* fix(dashboard): allow file:// origin on loopback WS + diagnostic logging

Upstream commit 2e66eefbc ("fix(dashboard): validate WebSocket Host
and Origin") added a WebSocket Host/Origin guard to block DNS
rebinding against the dashboard.  The guard rejects any Origin whose
scheme is not http/https or whose netloc is empty — which includes
Electron's renderer Origin: file:// when the desktop app loads its
bundle from disk in production mode.

That makes the bb/gui Electron desktop unable to open the gateway
WebSocket against the embedded backend on Windows / macOS prod
builds.  The renderer reports "Desktop boot failed" and the backend
logs:

  WARNING hermes_cli.web_server: gateway-ws reject
      peer=127.0.0.1:NNNN reason=non_loopback_or_bad_origin
      bound_host=127.0.0.1 close_code=4403

DNS-rebinding requires a DNS-resolvable hostname; file:// has no
host component and therefore cannot be the attack vector this guard
exists to block.  When bound to a loopback interface (127.0.0.1 /
::1 / localhost), accept file:// origins so desktop wrappers can
attach.  Non-loopback binds (operator opted into network exposure)
keep rejecting file:// — the loose policy doesn't apply.

Also adds per-reason diagnostic logging in
_ws_host_origin_is_allowed, so future ws-guard rejections name the
specific clause that fired (bad_host / bad_origin_scheme /
origin_host_mismatch) instead of the opaque
"non_loopback_or_bad_origin" surfaced at the call site.

Verified against tests/hermes_cli/test_web_server_host_header.py
(all 11 upstream tests still pass) and hand-tested by opening the
bb/gui Electron desktop dev build against the patched backend.

* fix(tui_gateway): restore _content_display_text helper

Bb/gui had dropped the helper but the orchestrator code merged from main
still calls it (_inflight_text, _message_preview). Re-add the definition
verbatim from main so session.create / _start_inflight_turn don't crash
with NameError on first prompt submit.

* fix(tui-gateway): restore _content_display_text helper lost in main merge

The May 27 merge of origin/main into bb/gui re-introduced two callers of
_content_display_text (in _inflight_text and _history_to_messages) but
dropped the helper definition itself, leaving an unresolved reference.

NameError fires on every user message via _start_inflight_turn ->
_inflight_text, taking down both the TUI and the desktop (which share
this gateway backend) the moment input is dispatched.

Restores the helper verbatim from main (commit 36c99af37) -- pure
structured-content text extractor, no other dependencies.

* fix(telegram): import Set for _dm_topic_chat_ids annotation

self._dm_topic_chat_ids: Set[str] = {...} at line 460 references Set
but only Dict, List, Optional, Any are imported from typing. The file
has no 'from __future__ import annotations', so the annotation is
evaluated at runtime and raises NameError on TelegramAdapter
construction.

* fix(setup): drop shadowing inner importlib.util re-imports

_print_setup_summary and _setup_tts_provider each had 'import
importlib.util' inside a try: block nested deeper in the function
body. Python flips importlib to function-local for the whole scope,
so earlier references in the same function (the neutts branches at
lines 493 / 1109) hit UnboundLocalError before the late import can
run.

The top-of-module 'import importlib.util' at line 14 already covers
both call sites, so dropping the redundant inner imports restores
the intended behavior.

* feat(install.ps1): add -IncludeDesktop switch + Stage-Desktop

The new Hermes-Setup.exe (Tauri bootstrap installer) passes -IncludeDesktop
so users who install via the GUI end up with a launchable Hermes.exe at
apps/desktop/release/<os>-unpacked/. Existing flows are unchanged:

  * The 'irm install.ps1 | iex' CLI one-liner omits the flag — terminal
    users don't need a prebuilt desktop binary; 'hermes desktop' builds
    on demand.
  * The Electron desktop's bootstrap-runner.cjs also omits the flag —
    rebuilding apps/desktop from inside a running Hermes.exe would try
    to overwrite the live binary on disk and fail.

Stage-Desktop runs after Stage-NodeDeps so workspace npm is already
installed when electron-builder fires. It does:
  1. 'npm install' at repo root so apps/* workspaces resolve their deps
     (Electron itself arrives via npm here, ~150MB)
  2. 'npm run pack' in apps/desktop (tsc + vite + electron-builder --dir)
  3. Probes apps/desktop/release/{win-unpacked,win-arm64-unpacked}/Hermes.exe

The --dir mode produces an unpacked launchable binary without an NSIS/MSI
installer artifact — we don't need one because Hermes-Setup.exe spawns the
unpacked binary directly via launch_hermes_desktop.

* feat(installer): Tauri bootstrap installer for first-time onboarding

Hermes-Setup.exe is a small signed Rust+Tauri binary that drives
scripts/install.ps1 stage-by-stage with a native UI matching the
desktop's design language. Replaces the chicken-and-egg pattern of
shipping a 200MB Electron app whose first launch existed only to
run install.ps1.

The architecture:

  Rust backend (src-tauri/):
    bootstrap.rs        orchestrator -- Tauri commands, stage iteration
    install_script.rs   resolve install.ps1 (dev checkout, cache, GitHub raw)
    powershell.rs       spawn powershell, line-stream stdout/stderr, parse JSON
    events.rs           BootstrapEvent types -- mirror bootstrap-runner.cjs
    paths.rs            HERMES_HOME resolution + tracing log setup
    build.rs            bakes BUILD_PIN_COMMIT / BUILD_PIN_BRANCH from
                        'git rev-parse HEAD' at compile time

  React frontend (src/):
    Tauri webview rendering 4 screens (welcome / progress / success /
    failure), driven by nanostores subscribing to the Rust event stream.
    Visual layer reuses the desktop's styles.css wholesale via @import
    so the installer and desktop never drift visually.

  Distribution:
    targets = ['app', 'dmg', 'appimage'] -- no NSIS/MSI wrapper. The
    raw target/release/Hermes-Setup.exe IS the artifact on Windows;
    .dmg + .app on macOS; AppImage on Linux. One file, double-click,
    no installer-installing-an-installer pattern.

  Compile-time pinning:
    build.rs reads 'git rev-parse HEAD' and emits
    cargo:rustc-env=BUILD_PIN_COMMIT=<sha> + BUILD_PIN_BRANCH=<branch>.
    bootstrap.rs's option_env!() picks these up so the binary fetches
    install.ps1 from the exact SHA it was tested against. CI / release
    builds can override via HERMES_BUILD_PIN_COMMIT env var.

  Windows manifest:
    hermes-setup.manifest declares level='asInvoker' so the
    productName 'Hermes Setup' doesn't trip Windows's installer-
    detection heuristic and refuse to launch without elevation.
    Also declares PerMonitorV2 DPI + UTF-8 active code page + Common
    Controls v6.

Limitations of this initial version:

  * No code signing -- Windows SmartScreen will warn once on Hermes-Setup.exe
    ('More info -> Run anyway'). The downstream binaries it produces
    (Hermes.exe in win-unpacked/, the hermes CLI) are locally-built and
    therefore don't carry MOTW, so they launch without SmartScreen
    intervention. Cert procurement tracked separately.

  * macOS and Linux build paths defined but untested -- Windows-only V1.

* fix(installer): pass -IncludeDesktop to manifest, surface launch errors, alias hermes desktop

Three bugs found in the first VM end-to-end test:

1. install.ps1 -Manifest was called WITHOUT -IncludeDesktop, so the
   manifest came back with the 14-stage list (no desktop stage), the
   UI showed '14 steps' and Stage-Desktop never ran. Pass the flag to
   both the manifest fetch and the per-stage runs — install.ps1 gates
   the desktop stage's inclusion on the flag.

2. The Success screen's Launch button silently swallowed the Tauri
   error when no Hermes.exe existed (e.g. Stage-Desktop was skipped).
   Wire the error through to inline UI with an alert callout, so the
   user gets actionable text ('Hermes.exe missing, run hermes desktop
   from a terminal') instead of an unresponsive button.

3. The Success screen tells users to run 'hermes desktop' from a
   terminal but the CLI only accepted 'hermes gui' — invalid choice
   for 'desktop'. Rename the subcommand canonically to 'desktop' with
   'gui' as a backwards-compatible alias. Update the _SUBCOMMANDS sets
   used by session-flag arg parsing + logging-mode probe so both names
   route to the same logic.

* fix(install.ps1): pre-warm electron-builder winCodeSign cache + fix Stage-Desktop $HasNode false-skip

Two bugs caught in the second VM end-to-end run:

1. electron-builder's winCodeSign extraction fails on grandma-class
   Windows boxes because the .7z archive contains macOS symlinks
   (darwin/10.12/lib/libcrypto.dylib and libssl.dylib pointing at
   versioned siblings). Creating symlinks on Windows requires
   SeCreateSymbolicLinkPrivilege, a per-user right that non-admin
   accounts don't have on stock Windows. Result: every fresh install
   on a non-admin user fails Stage-Desktop with a 7-Zip 'cannot create
   symbolic link' error, retried four times, then bails.

   Fix: Initialize-ElectronBuilderCache pre-extracts winCodeSign-2.6.0.7z
   ourselves with -snl (don't preserve symlinks, store as resolved file
   content) AND -x!darwin (skip the entire macOS subtree — irrelevant
   on Windows). Writes to electron-builder's expected cache dir before
   electron-builder gets a chance to try its own broken extraction.
   Idempotent — fast-paths via signtool.exe sentinel check.

2. Install-Desktop's first guard was 'if (-not $HasNode) skip'.
   $HasNode is set by Stage-Node into $script:HasNode, but in
   cross-process driver mode (each -Stage NAME is a fresh powershell.exe
   spawned by Hermes-Setup.exe), that script-scope variable from the
   PREVIOUS process is invisible — so the guard always fired and
   Install-Desktop returned in 900ms with a misleading
   'Node.js not available' reason. The real npm probe below it never
   got to run. Fix: re-probe npm directly via Get-Command when $HasNode
   is empty/false, since by that point Stage-Node has already verified
   Node is installed and the only question is whether *this* process
   can see it on PATH (it can — installer-wide PATH update from Stage-Node).

* fix(install.ps1): tell electron-builder we're NOT signing instead of pre-extracting winCodeSign

The previous commit (c7e46f9f3) worked around the winCodeSign-symlinks-
on-Windows extraction crash by pre-extracting the archive ourselves with
-snl + -x!darwin. That fix was correct but addressed the wrong layer.

The deeper question: why was electron-builder fetching winCodeSign at all
when we have no signing cert configured? Answer: electron-builder
unconditionally pre-warms the toolchain assuming any build MIGHT sign.
The cert auto-discovery never finds anything (we never set CSC_LINK
or anything else), so the signing never happens — but the 100MB fetch
of winCodeSign and its broken-on-Windows symlink extraction does.

Set CSC_IDENTITY_AUTO_DISCOVERY=false (with WIN_CSC_LINK and
WIN_CSC_KEY_PASSWORD also explicitly cleared as belt-and-suspenders)
before invoking npm run pack, and electron-builder skips the entire
winCodeSign apparatus. No download, no extraction, no privilege check.
Env vars are saved/restored around the invocation so we don't leak
the override into Stage-PlatformSdks etc.

Net: removes the 100-line Initialize-ElectronBuilderCache helper that
manually downloaded + extracted winCodeSign-2.6.0.7z. Replaced with
3 env-var assignments. The produced Hermes.exe is functionally
identical — just no longer carries a code-signing-machinery dependency
we never used.

* fix(installer): bump bootstrap-installer.log to capture stage transitions + every install.ps1 line

Diagnosing the second VM failure was impossible because bootstrap-installer.log
contained only the 'starting' banner. Two causes:

1. emit_log() inside run_bootstrap() was tracing::debug! — dropped on the
   floor under the default INFO env-filter.

2. The per-stage sink callbacks (on_stdout_line / on_stderr_line) only
   emitted Tauri events to the frontend; they never tee'd to the log file
   at all. When the failure route mounts, the Tauri event stream is the
   only place the script output lived, and it gets discarded.

3. The Failed / Stage / Manifest / Complete lifecycle frames in emit_event()
   were also Tauri-only — so even the 'which stage failed' frame never
   reached the log.

Fixes:
  * emit_log() → tracing::info!
  * Sink callbacks tee stdout to info!, stderr to warn!, with stage label
    as a structured field for grep'ability
  * emit_event() now matches on the variant and logs each lifecycle frame
    at the right level: Failed → tracing::error!, others → info!

Result: a failing install leaves a complete forensic trail in
bootstrap-installer.log — manifest stage list, every install.ps1
stdout/stderr line tagged by stage, the stage transitions, and the
final error. Same path as before so nothing the user does changes.

* fix(install.ps1): Stage-NodeDeps cross-process $HasNode + stream npm install output to bootstrap log

VM run 3 diagnosis: node-deps stage skipped on the VM (logged
'Skipping Node.js dependencies (Node not installed)') and then
desktop's npm install failed with exit 1 and zero diagnostic detail.

Two root causes:

1. $HasNode false-skip in Stage-NodeDeps — same cross-process bug
   pattern we fixed for Stage-Desktop in c7e46f9f3. Stage-Node ran
   in process A and set $script:HasNode = $true, then exited. Stage-
   NodeDeps ran in fresh process B (Hermes-Setup.exe -Stage NAME
   spawns each stage independently), where that variable doesn't
   exist. Re-probe via Get-Command npm instead of trusting the
   stale script-scope global. The previous stage already verified
   Node so the re-probe succeeds.

2. npm install --silent + Tee to TEMP file hid the real error.
   When the workspace install failed on the VM, the actual reason
   was buffered in $env:TEMP\hermes-npm-desktop-install-*.log and
   the user saw only 'exit 1'. Drop --silent so npm streams its
   full output, drop the TEMP-file dance — the Tauri installer's
   streaming sink already tees every stdout/stderr line to the
   rolling bootstrap-installer.log, so a side log file is dead
   weight that hides the very error we need.

After this, the bootstrap log on a failure will contain npm's full
output (deprecation warnings, ETARGET, native-module compile errors,
whatever) tagged with stage=desktop, making the actual cause
diagnosable instead of an opaque exit code.

* fix(install.ps1): restore Initialize-ElectronBuilderCache (CSC env vars alone aren't enough)

VM run 4 diagnosis: even with CSC_IDENTITY_AUTO_DISCOVERY=false set,
electron-builder still fetches winCodeSign and signs bundled binaries.
The log shows the signing happens BEFORE the cache extraction:

  • signing with signtool.exe  ...\winpty-agent.exe
  • signing with signtool.exe  ...\OpenConsole.exe
  • downloading winCodeSign-2.6.0.7z
  • <symlink privilege error>

Cause: node-pty's bundled prebuilds are listed in apps/desktop's
asarUnpack ['**/*.node', '**/prebuilds/**']. electron-builder
re-signs anything unpacked from asar, regardless of whether OUR
binary gets signed. The signtool invocation needs winCodeSign on
disk, which needs the .7z extracted, which hits the macOS-symlink
crash on non-admin Windows.

The CSC env vars I added in d5fe46727 only kill IDENTITY DISCOVERY
(so OUR Hermes.exe stays unsigned, which is fine — we have no cert).
They don't prevent the toolchain fetch for the bundled-prebuild
re-sign. I removed the pre-extract in d5fe46727 thinking the env
vars subsumed it; that was wrong. Both are needed.

Restoring Initialize-ElectronBuilderCache verbatim from c7e46f9f3
and keeping the CSC env vars. Wrote a clearer doc-comment at the
call site explaining the two-knob interaction so future maintainers
don't drop one half again.

* fix(desktop): disable signtool via signtoolOptions.sign=null, drop dead winCodeSign pre-extract

VM run 5 diagnosis: the pre-extract from 3b29e65c1 ran (extracted 83
files, 24MB) but produced ZERO files at the expected sentinel path
'/winCodeSign-2.6.0/windows-10/x64/signtool.exe'.

Cause: the .7z archive's root entries are 'windows-10/', 'darwin/',
'linux/', etc. — not 'winCodeSign-2.6.0/<arch>'. Extracting with
'-o$cacheRoot' put files at $cacheRoot/windows-10/..., NOT at
$cacheRoot/winCodeSign-2.6.0/windows-10/.... I had the directory
nesting wrong from the start.

And then we observed: electron-builder downloads winCodeSign-2.6.0.7z
under a random numeric filename ('384387955.7z') regardless of what's
already extracted in the parent dir. The cache key isn't the dirname;
it's content-addressed. So the pre-extract approach was doomed even
if the path nesting had been right.

Actual fix: signtoolOptions.sign=null in apps/desktop/package.json's
win build config. electron-builder honors this and skips the bundled-
prebuild signing entirely — no signtool invocation, no winCodeSign
fetch, no symlink-privilege crash. The previous failures all stemmed
from electron-builder pre-signing node-pty's bundled .exes
(winpty-agent.exe, OpenConsole.exe) which are already author-signed
upstream; re-signing with our nonexistent cert was overwriting good
sigs with nothing useful anyway.

Cost: when we DO get a real cert later, we'll add it back with the
sign function pointing at the cert chain. Until then, all-null is
the correct config and unblocks every non-admin Windows user.

Removed Initialize-ElectronBuilderCache (the dead pre-extract).
Removed the call site. Kept the CSC_IDENTITY_AUTO_DISCOVERY env
vars as belt-and-suspenders against a future electron-builder
change that might revive cert auto-discovery.

* fix(desktop): use no-op sign function instead of sign=null

VM run 6 still hit the symlink crash even with signtoolOptions.sign=null.
electron-builder 26.8.1 treats null as 'use the default signtool path'
rather than 'skip signing', so the winCodeSign fetch + extraction still
fired for the bundled prebuild re-sign.

The Electron docs (electronjs.org/docs/latest/tutorial/code-signing)
make it clear signing is OPTIONAL and unsigned apps work fine — users
just see SmartScreen on first launch. The electron-builder mechanism
for 'don't actually sign anything' is to supply a custom sign function
(via signtoolOptions.sign: '<path-to-cjs-module>') that resolves
without invoking signtool.

build-noop-sign.cjs is that module — a 5-line async function that
returns undefined. electron-builder calls it for every binary it would
have signed, gets back a resolved promise, and considers each binary
'signed.' No signtool spawn, no winCodeSign fetch, no symlink crash.

When Nous's cert arrives, replace this file with a real signing hook
(@electron/windows-sign-based or a direct signtool invocation). The
architecture's signing-ready and the cutover is a one-file edit.

* fix(desktop): signAndEditExecutable=false to skip signtool path entirely

After reading app-builder-lib/winPackager.js line 216 + 231 directly:
signAndEditExecutable is the ACTUAL hardcoded gate that short-circuits
both signApp() (which signs Hermes.exe + every shouldSignFile match
including bundled prebuilds) AND createTransformerForExtraFiles().
None of signtoolOptions.sign / sign:null / sign:<custom-fn> gate the
winCodeSign download — that happens before they're consulted.

What we lose: rcedit also runs through signAndEditResources, so
disabling this drops PE metadata (file properties showing 'Hermes' /
'Nous Research' / file description). Cost is real but bounded:
  * Hermes.exe filename, icon, asar contents, app identity intact
  * Task Manager shows 'Hermes.exe' (the filename) not 'Hermes' (PE
    description) — minor downgrade
  * Start menu, taskbar, window title all work normally
  * SmartScreen will warn once (unsigned, same as before)

When the cert lands, flip signAndEditExecutable back to default true,
both signing AND rcedit return, PE metadata is restored.

Removes the no-op sign function (build-noop-sign.cjs) since
signAndEditExecutable=false prevents signtool from being invoked at
all — the custom hook never gets called either.

* feat(install.ps1): write .hermes-bootstrap-complete marker at end of install

The desktop app's main.cjs resolver ladder has a 'bootstrap-needed' rung
that fires when .hermes-bootstrap-complete is missing from
ACTIVE_HERMES_ROOT. Pre-Hermes-Setup, this marker was written by the
packaged-desktop's own bootstrap-runner.cjs at the end of its install
flow. Now that Hermes-Setup.exe runs install.ps1 directly, install.ps1
needs to own the marker — otherwise the desktop sees no marker on first
launch and triggers its legacy first-launch bootstrap (re-running
install.ps1 from inside Electron, the exact recursion Hermes-Setup.exe
was supposed to obviate).

Implementation:
  * New Stage-BootstrapMarker (worker) → Write-BootstrapMarker (helper)
  * Slotted in the manifest right after platform-sdks, before the
    interactive configure/gateway stages, so it runs unconditionally
    when the install reaches the finalize phase
  * Schema mirrors apps/desktop/electron/main.cjs writeBootstrapMarker /
    isBootstrapComplete EXACTLY: {schemaVersion: 1, pinnedCommit,
    pinnedBranch, completedAt}. Schema version stays at 1 so old
    desktops that read marker files written by future install.ps1s
    can still parse them.
  * pinnedCommit comes from -Commit flag (Hermes-Setup.exe passes it)
    or falls back to 'git rev-parse HEAD' in InstallDir
  * pinnedBranch from -Branch flag, defaults to 'main' matching
    install.ps1's own param default

Two PS-5.1 gotchas baked into comments:
  * The ?. null-conditional operator doesn't exist pre-PS7; use
    explicit if-checks on Get-Command results
  * Set-Content -Encoding UTF8 emits a BOM in 5.1 and Node's plain
    JSON.parse rejects BOM — write via .NET's UTF8Encoding(false)
    to produce BOM-less JSON the desktop's readJson() can parse

* feat(installer): drive in-app updates through the Tauri installer

Converge update on the same principle as bootstrap: one driver owns all
repo mutation. The desktop becomes a pure consumer that hands off to
Hermes-Setup.exe --update instead of re-implementing git/pip in Electron.

- hermes desktop --build-only: build without launching, so the installer
  owns the post-update launch (CLI keeps build logic single-sourced).
- Installer AppMode {Install,Update} from argv; get_mode exposed to the UI.
- Installer self-copies to HERMES_HOME/hermes-setup.exe on install success
  (no-op guard during --update re-invocation to avoid the locked-exe copy).
- Installer --update flow (update.rs): wait for the desktop to release the
  venv shim, run 'hermes update --yes --gateway' (branch on exit 0/2/other),
  then 'hermes desktop --build-only', then launch the rebuilt desktop. Reuses
  the bootstrap event channel + progress UI via a synthetic two-stage manifest.
- Desktop applyUpdates() gutted (~105 lines of git/stash/pull/pyproject/pip
  removed) -> thin handoff: spawn updater, app.quit() to free the shim.
  Detection (checkUpdates, commit changelog, behind-count) kept intact.
- install.ps1 creates Start Menu + Desktop shortcuts to the packed Hermes.exe
  (never bare 'hermes desktop', which would rebuild every launch).

* test update

* fix(installer): pass --branch to hermes update in the --update flow

The install is a detached-HEAD checkout of a pinned commit. Without
--branch, 'hermes update' fell back to its default (main) and switched
the checkout to main — a divergent branch that lacks the desktop CLI
command — so the update targeted the wrong branch and the rebuild stage
failed with 'invalid choice: desktop'.

Thread BUILD_PIN_BRANCH (the branch this installer was built against,
and the same branch the desktop detected the update on) into
'hermes update --branch <b>' so update + rebuild stay on-branch.

* test update

* fix(installer): stamp Hermes icon onto Hermes.exe via rcedit (no winCodeSign)

The unpacked Hermes.exe showed the stock Electron icon + name in the
taskbar because build.win.signAndEditExecutable=false disables BOTH
electron-builder's signing AND its rcedit metadata/icon stamping. That
flag is load-bearing: enabling it re-triggers signtool -> winCodeSign,
whose macOS symlinks crash 7-Zip on non-admin Windows (unfixable dead end).

Decouple identity-stamping from signing entirely: after npm run pack,
run rcedit ourselves on the produced exe.
- Add rcedit as a direct devDependency of apps/desktop (the transitive
  electron-winstaller copy is fragile).
- apps/desktop/scripts/set-exe-identity.cjs: Node helper that calls
  rcedit's named export to set icon + ProductName/FileDescription/
  CompanyName. Node builds argv natively — avoids the PowerShell->exe
  ->JSON double-escaping that broke the app-builder rcedit path.
- install.ps1 Set-DesktopExeIdentity invokes the script after the build,
  before shortcuts. Best-effort: failure keeps the stock icon, never
  fails the install. rcedit is a pure PE editor — no signtool, no
  winCodeSign, no symlinks.

Verified locally: stamping a copy of the built Hermes.exe embeds the
32x32 icon and sets ProductName=Hermes.

Also fix update-path success-screen flash: in update mode the installer
hands off + exits in ~600ms, so don't route to the 'launch Hermes'
success view (it flashed before the window closed).

* update test

* fix(desktop): show 'hermes update' guidance for CLI installs instead of dead-end error

A user who installed via the CLI (irm|iex / install.sh) then ran
`hermes desktop` has no staged hermes-setup.exe, so clicking Update
in-app hit resolveUpdaterBinary()=null and showed a misleading error
('re-run the Hermes installer') with a Try-again button that could
never succeed — a dead loop for a perfectly valid install.

Treat the no-updater case as an intentional outcome, not a failure:
- main.cjs applyUpdates returns { ok:true, manual:true, command:'hermes update' }
  (no throw, no 'error' stage) when no updater binary exists.
- New 'manual' update stage + apply-state.command thread the command to the UI.
- updates-overlay ManualView: a polished terminal-native card with the
  exact command and a copy button, framed as the correct path for a CLI
  user rather than an error.

GUI-installer users are unaffected — hermes-setup.exe present => seamless
auto-update runs as before. Zero new process orchestration; can't fail
the update demo.

* update test

* fix(gui): pin /api/hermes/update to the current branch

The desktop command-center 'update' action hits POST /api/hermes/update,
which spawned bare `hermes update` with no --branch. cmd_update then
falls back to its default (main) and checks the working tree OUT of the
tracked branch — a bb/gui install silently jumped to main and lost the
desktop CLI.

Resolve the checkout's current branch and pass --branch <current> from
this endpoint only. The engine default (main) is DELIBERATELY unchanged:
bare `hermes update` from a terminal, the gateway /update bot command,
and the CLI/TUI relaunch path all keep their long-standing 'update against
main' contract for the existing user base. Only the GUI button is scoped
to update-the-branch-you're-on. Detached HEAD / git failure falls back to
the bare default.

* update test

* fix(desktop): branch-pin the CLI manual-update command card

The 'Update from your terminal' card (shown to CLI installs with no staged
updater) hardcoded bare `hermes update` — which defaults to main and would
switch a bb/gui (or any non-main) checkout off-branch. Same bug we fixed for
the GUI button, leaked into the card's copy text.

Resolve the checkout's current branch and show `hermes update --branch
<current>` for non-main checkouts; keep it bare for main so the card stays
clean. Best-effort: bare fallback if branch detection fails. Matches the
GUI button + installer --update contract; bare terminal/bot/TUI update
paths still default to main, unchanged.

* docs: phragg was here

* feat(desktop): lead onboarding with Nous Portal + fix fresh-install detection (#34970)

- Feature Nous Portal as the primary onboarding card (Recommended tag,
  app logo, single pitch line); collapse other OAuth providers behind an
  "Other providers" disclosure whose open/closed state persists.
- Surface OpenRouter as a one-click API-key option inside the disclosure;
  move "I have an API key" to a quiet bottom-right link.
- Treat "no provider configured" as a normal onboarding state, not a red
  error banner (provider-setup-errors copy match).
- Fix setup.runtime_check: it reported ready when the resolved runtime had
  an empty credential or only implicit Bedrock/IAM, so fresh installs never
  saw onboarding. Now requires a usable credential.
- Auto-wire Windows fonts for WSL2 users so the renderer renders real
  Segoe UI instead of the DejaVu fallback; make WSL detection env-independent
  via the /proc kernel marker.

* feat(desktop): live elapsed timer on install bootstrap steps

The first-launch install overlay showed a static "Installing" with no
motion, so long steps (notably the repo clone) looked frozen. Stamp each
stage's start time on the running transition and tick once a second so the
active step shows live elapsed (e.g. "Installing · 1:23"), plus elapsed on
the overall current-step line. Completed steps keep their final duration.

* fix(desktop): resolve PortableGit for update checks + reserve titlebar tools space

- runGit() hardcoded spawn('git'), which ENOENTs on fresh installer-driven
  Windows installs (git is PortableGit under %LOCALAPPDATA%\hermes\git, never
  on PATH) — so "Check for updates" failed with "Couldn't check for updates".
  Add resolveGitBinary() mirroring findGitBash (PortableGit → Git-for-Windows
  → PATH) and use it in runGit.
- PageSearchShell rendered a full-width search input in the titlebar row, so
  on Windows its right edge slid under the fixed top-right tools + native
  window controls. Reserve that footprint via --titlebar-tools-* vars.

* fix(desktop): stop streaming caret from shifting layout on completion

The streaming caret (::after on the running message's last child) was an
in-flow inline-block adding ~0.78em of inline width, which could wrap the
last line mid-stream; when the caret is removed on completion the line
un-wraps and reflows — the visible post-response layout shift. Net-zero its
inline advance with a compensating negative margin so it paints at the text
end without consuming layout width.

* fix(desktop): stop completed-message layout shift while streaming

The assistant message action bar used `hideWhenRunning`, which unmounts it
whenever the thread is streaming. Since the bar reserves vertical space in
each completed assistant message's footer (it's invisible-until-hover via
opacity, not via mount), unmounting it collapsed every prior turn by the
bar's height — then remounting on resolve grew them back, shifting the whole
conversation (visible as "padding appears above the last user message").
Drop hideWhenRunning so the footer height is constant; the bar stays
invisible during streaming via its existing opacity/pointer-events gating.

* fix(merge): keep windows-footgun suppressions inline

* fix(merge): keep remaining gateway footgun suppressions inline

* fix(merge): restore contracts caught by main-target CI

* fix(dashboard): honor injected HERMES_DASHBOARD_SESSION_TOKEN

The desktop shell mints a session token and signs its /api + /api/ws
calls with it via HERMES_DASHBOARD_SESSION_TOKEN, but the main-merge
restored a web_server.py that ignored the env var and minted its own
random _SESSION_TOKEN -- so every desktop request 401'd and the UI
reported "gateway offline". Read the injected token (fall back to a
fresh random one) so loopback HTTP + WS auth line up.

Adds a regression test so a future merge can't silently drop the read.

* fix(desktop): align fresh-install home so upgraders don't brick

Two related first-launch bugs on machines with a legacy ~/.hermes:

- install.ps1 hardcoded $HermesHome/$InstallDir to %LOCALAPPDATA%\hermes
  and ignored the HERMES_HOME the desktop passes through. The desktop
  freezes HERMES_HOME at module load and prefers a legacy ~/.hermes when
  %LOCALAPPDATA%\hermes is absent, so the installer wrote to a different
  home than the shell read -> "Could not connect to Hermes gateway". Honor
  $env:HERMES_HOME in the param defaults.

- isBootstrapComplete() trusted the marker + checkout without verifying a
  runnable venv, so an interrupted/split install spawned a dead backend
  instead of re-bootstrapping. Also require the venv python to exist.

* fix(dashboard): allow packaged desktop file:// origin on loopback WS

The packaged Electron desktop loads its renderer over file://, so its
/api/ws handshake carries Origin: file:// (or null). The DNS-rebinding
WebSocket Origin guard only accepted http(s) origins matching the bound
host, so it rejected the desktop's own renderer with 4403 -> "Could not
connect to Hermes gateway" on macOS.

A browser DNS-rebinding attacker can only ever present an http(s) origin
(the site hosting the malicious page); it cannot forge file://, null, or
a custom app scheme AND hold the loopback session token. So on loopback
binds we now trust non-web origins -- the token in _ws_auth_ok remains
the real authenticator. Public/gated binds still reject them, and
cross-site http(s) origins are still rejected everywhere.

* fix(desktop): resolve renderer assets relative to BASE_URL

Absolute public asset paths (/apple-touch-icon.png, /ds-assets/...) work
under the dev server but break in the packaged app, where the renderer is
loaded from file://.../index.html and a leading slash resolves to the
filesystem root -> broken onboarding provider icon and backdrop image on
macOS. Prefix these with import.meta.env.BASE_URL so they resolve next to
the bundled index.html in both dev and packaged builds.

* feat(desktop): automate first-launch bootstrap on macOS/Linux

Previously a packaged macOS/Linux app with no Hermes install hit a
dead-end ("first-launch install is not yet automated -- run install.sh
manually") because install.sh lacked the staged protocol install.ps1
exposes. Now both platforms bootstrap on first launch with the same
structured, per-step progress UI as Windows.

- install.sh: add --manifest / --stage / --json / --non-interactive plus
  a stage dispatcher (prerequisites, repository, venv, python-deps,
  node-deps, path, config, setup, gateway, complete). User-input stages
  (setup, gateway) are skipped under --non-interactive; the in-app
  onboarding overlay owns API keys/model, matching the Windows flow.
  Each stage runs inside the install dir (its own process) and a new
  --commit flag pins the checkout to the build-stamp SHA.
- bootstrap-runner.cjs: drive the staged manifest/stage/JSON protocol for
  both install.ps1 (PowerShell) and install.sh (bash), selected by
  installer kind; removed the single-blob POSIX shim.
- main.cjs: drop the macOS/Linux unsupported-platform dead-end so the
  bootstrap-needed path runs the installer on every platform.

* fix(dashboard): return 404 JSON for unmatched /api paths instead of SPA HTML

The SPA catch-all (serve_spa) served index.html for any unmatched GET,
including unregistered /api/* endpoints. A missing API route therefore
came back as <!doctype html> with status 200, and JSON clients (the
desktop app's fetchJson) crashed with an opaque
'SyntaxError: Unexpected token <' instead of a clear error.

- web_server.py: unmatched /api or /api/... now returns 404 JSON
  ('No such API endpoint'); non-api paths still serve the SPA for
  client-side routing.
- main.cjs fetchJson: detect an HTML body / text/html content-type on a
  2xx response and reject with a clear message naming the URL, rather
  than a raw JSON.parse SyntaxError. Empty bodies resolve to null;
  malformed JSON reports the URL plus a snippet.

* say 'OS appearance' instead of 'macOS appearance'

* feat(install): add --include-desktop stage + PowerShell-style flags to install.sh

Brings install.sh to parity with install.ps1's bootstrap surface so the
shared Rust/Tauri bootstrapper (apps/bootstrap-installer) can drive a
macOS/Linux install the same way it drives Windows.

- Accept the PowerShell-style aliases the bootstrapper emits to both
  installers: -Commit / -Branch (alongside existing -Manifest / -Stage /
  -Json / -NonInteractive).
- Add --include-desktop / -IncludeDesktop. When set, the manifest gains a
  'desktop' stage (immediately before 'complete'), and a new install_desktop
  runs a root workspace `npm install` + `npm run pack` (electron-builder
  --dir, signing auto-discovery disabled) to produce release/mac*/Hermes.app
  -- mirroring install.ps1's Install-Desktop / Stage-Desktop.
- The flag is opt-in, exactly like Windows: the signed bootstrap installer
  passes it; the Electron app's own first-launch bootstrap and the CLI
  one-liner omit it (building the desktop from inside the running app would
  clobber it).

* fix: tts endpoints

* macOS desktop: install + in-app self-update (#35607)

* fix(installer): align macOS HERMES_HOME with the rest of the stack

paths.rs computed the macOS Hermes home as ~/Library/Application Support/
hermes, but nothing else does: hermes_constants.get_hermes_home() (Python),
scripts/install.sh, and the Electron desktop's resolveHermesHome() all use
~/.hermes on macOS. The drift meant the Tauri installer wrote the install to
one directory and the desktop looked for it in another, so a fresh GUI
install never found its backend (the file's own comment warned this exact
drift would break things). Use ~/.hermes on macOS to match.

* fix(install.sh): always emit a stage result frame on failure

Stage helpers (clone_repo, install_deps, check_python, …) were written for
the monolithic flow and call `exit 1` on failure. Under `--stage`, that
terminated the process before the JSON result frame was printed, so the
installer's parse_stage_result saw "no frame" instead of a clean
{ok:false,...} contract response. Run the stage body in a subshell so an
`exit` only unwinds the subshell and the parent still emits the frame.

* feat(install.sh): auto-provision git on macOS/Linux (parity with install.ps1)

install.ps1 downloads PortableGit on Windows, but install.sh just printed a
"please install git" hint and exited — so a fresh Mac with no developer tools
(no Xcode CLT → no git) couldn't get past the clone step. check_git now tries
to install git before bailing:
  - macOS: Homebrew if present (headless), else `xcode-select --install`
    (the CLT prompt also provides the compiler some wheels need), polling for
    git to appear.
  - Linux: apt/dnf/pacman via sudo when available.
Falls back to the manual instructions only if auto-provision fails.

* feat(desktop): in-app GUI+backend self-update on macOS/Linux

On Windows the staged Hermes-Setup binary drives updates (quit → hermes
update → hermes desktop --build-only → relaunch). The mac drag-install has no
such binary, so "Update now" previously just printed `hermes update`.

Since there's no venv-shim file lock on POSIX, the desktop can drive the whole
update itself. applyUpdates now, when no staged updater exists on mac/linux:
  1. runs `hermes update --yes [--branch <current>]` (backend git pull + deps),
  2. runs `hermes desktop --build-only` (OS-aware GUI rebuild) with the
     Hermes-managed Node + venv on PATH,
  3. spawns a detached swapper that waits for this process to exit, dittos the
     freshly built Hermes.app over the running bundle, clears quarantine, and
     relaunches.
Degrades to "backend updated — restart to load the new GUI" if the rebuild
fails or there's no .app bundle to swap (dev run, Linux AppImage).

* chore: uptick

* chore: uptick

* chore: linux build

* fix(install): detect xcode-select git stub on fresh macOS

* chore: bump

* fix(desktop): repair voice dictation on Windows

Voice dictation was broken on Windows in two ways:

1. Mic access was denied. The Electron permission request handler only
   granted 'media' requests whose details.mediaTypes included 'audio',
   but Chromium on Windows frequently fires the mic request with an empty
   mediaTypes array, so getUserMedia threw NotAllowedError. The handler
   now grants audio-capture when mediaTypes includes 'audio' OR is
   empty/absent, handles the 'audioCapture' permission name, and adds a
   setPermissionCheckHandler (the synchronous path Chromium also consults
   for getUserMedia on Windows). Video is still denied.

2. Transcripts went nowhere. The composer's insertText handler (used by
   dictation and other inserts) only updated the assistant-ui composer
   store via setText, never the contentEditable editor DOM. The
   draft->editor sync effect only re-renders the editor when it is NOT
   focused, and dictation runs while the editor has/regains focus, so the
   transcript was stored but never shown and could not be sent. insertText
   now renders into the editor DOM and places the caret, mirroring
   appendExternalText.

Also hardens fetchJson: a 2xx response with an HTML body (or text/html
content-type) now rejects with a clear message naming the URL instead of
an opaque JSON.parse 'Unexpected token <' error.

* feat(desktop): route Nous subscribers onto the Tool Gateway from the GUI

When the GUI sets the main provider to Nous via POST /api/model/set, call
the same apply_nous_managed_defaults the CLI uses after model selection, so
GUI/onboarding users land on the Nous Tool Gateway the same way CLI users do
— no separate prompt, no duplicated logic.

Purely additive: apply_nous_managed_defaults skips any tool where the user
has a direct key (FIRECRAWL_API_KEY, FAL_KEY, etc.) or explicit config, so it
never overwrites a user's own setup. Only unconfigured tools get routed.

- web_server.py: in set_model_assignment (scope=main, provider=nous), resolve
  enabled toolsets and apply managed defaults; guarded so a Portal hiccup never
  blocks saving the model. Returns routed tools as gateway_tools.
- onboarding.ts: surface a 'Tool Gateway enabled' toast listing routed tools.
- types/hermes.ts: add gateway_tools to ModelAssignmentResponse.
- tests: cover nous-applies, non-nous-skips, and failure-doesnt-block-save.

* feat(desktop): mirror hermes model free/paid curation in GUI onboarding

GUI onboarding picked models[0] from /api/model/options, which ignores the
Nous free/paid tier — a free user could land on a paid default (e.g.
anthropic/claude-opus-4). Now the recommended default mirrors what `hermes
model` does.

- web_server.py: new GET /api/model/recommended-default?provider=<slug>. For
  Nous it runs the same curation as the CLI (get_curated_nous_model_ids +
  pricing + check_nous_free_tier + union_with_portal_{free,paid}_recommendations
  + partition_nous_models_by_tier) so free users get a free model and paid users
  get the curated default. Other providers fall back to the first curated model.
  Never 500s — returns empty model on error so onboarding degrades gracefully.
- hermes.ts: getRecommendedDefaultModel client + RecommendedDefaultModel type.
- onboarding.ts: fetchProviderDefaultModel prefers the recommended endpoint,
  falls back to models[0] when unavailable.
- tests: free-tier picks free model, paid-tier picks curated default, failure
  returns empty without 500.

* feat(desktop): show model pricing + free/paid tier gating in GUI picker

The CLI `hermes model` picker shows per-model $/Mtok pricing and gates paid
models on free Nous accounts. The GUI picker showed bare model names. Bring it
to parity across both the model-picker dialog and onboarding confirm card.

Backend:
- inventory.build_models_payload gains a pricing=True flag → _apply_pricing
  enriches each provider row with formatted per-model pricing
  ({input,output,cache,free}) via the same _format_price_per_mtok the CLI uses,
  and for Nous adds free_tier + unavailable_models (paid models a free user
  can't select) via check_nous_free_tier + partition_nous_models_by_tier.
  Best-effort: any pricing/tier failure is swallowed and fails open (no gating).
- /api/model/options and TUI model.options now pass pricing=True so the
  global picker and in-session picker both carry pricing.

Frontend:
- ModelOptionProvider gains pricing/free_tier/unavailable_models; new
  ModelPricing type.
- model-picker dialog renders In/Out $/Mtok (or a Free pill) per model, a
  Free tier/Pro badge on the Nous heading, and disables + grays unavailable
  paid models for free users with a 'Pro models need a paid subscription' note.
- onboarding confirm card shows the chosen model's price + tier badge.

Tests: test_inventory_pricing covers price formatting, free-tier gating,
paid no-gating, providers without pricing, and swallowed failures.

* fix(desktop): GUI model picker shows curated Nous list in curated order

Two bugs made the GUI Nous model list diverge from the `hermes model` CLI picker:

1. Backend (model_switch.py): the Nous row in list_authenticated_providers
   fell through to cached_provider_model_ids("nous"), dumping the full live
   /v1/models catalog (~50 vendor-prefixed models, alphabetical). Now it uses
   the curated list AND applies the Portal free/paid recommendation union —
   exactly like _model_flow_nous in main.py — so newly-launched models such as
   stepfun/step-3.7-flash:free surface in curated order. Best-effort: falls
   back to the curated list alone if the Portal fetch fails.

2. Frontend (model-picker.tsx): cmdk's Command had shouldFilter on (default),
   which re-sorts items by fuzzy-match score (≈alphabetical) and ignores array
   order. Set shouldFilter={false} + own the search term and do an
   order-preserving substring filter, so the backend's curated order is shown
   verbatim.

* feat(desktop): add/switch providers from the model picker via onboarding reuse

The model picker could only select models from already-authenticated
providers. Switching to a new provider had no in-app path. Rather than
duplicate provider UI, reuse the existing onboarding provider selector
(featured Nous + other providers + API-key form + device-code/PKCE flow +
model-confirm with pricing/tier).

- onboarding store: add a 'manual' flag with startManualOnboarding() /
  closeManualOnboarding(). Manual mode forces the onboarding overlay to show
  even when configured===true and refreshOnboarding no longer auto-dismisses
  on runtime-ready (the app is already working — the user is just adding or
  switching a provider).
- onboarding overlay: render when manual even if configured; show a Close
  button (the first-run flow has none since the app can't run yet).
- model picker: 'Add provider' footer button opens the onboarding selector;
  ModelResults lists only configured (model-bearing) providers.

* feat(desktop): add PUT /api/tools/toolsets/{name} enable/disable endpoint

* feat(desktop): add toggleToolset RPC binding

* feat(desktop): toolset enable/disable switch in Tools settings

* feat(desktop): tool configuration parity in GUI Tools settings

Bring the desktop GUI Tools settings to parity with the CLI `hermes tools`
for provider selection and API-key configuration.

Backend (hermes_cli/web_server.py):
- GET  /api/tools/toolsets/{name}/config  - provider matrix + key status
- PUT  /api/tools/toolsets/{name}/provider - persist provider selection

Shared core (hermes_cli/tools_config.py):
- Extract apply_provider_selection / _write_provider_config from the
  interactive _configure_provider so the CLI and GUI write identical
  config keys (web.backend, tts.provider, browser.cloud_provider, plugin
  image/video providers, use_gateway flags) through one code path.

Desktop UI:
- ToolsetConfigPanel: provider list with select, per-provider API-key
  entry (set/replace/clear/reveal via the shared env RPCs), Ready/Needs
  keys state, guidance for Nous-auth and post-setup providers.
- Wire the Configured/Needs keys pill to expand the panel inline; refresh
  the toolset list after key changes so the pill updates live.
- Add getToolsetConfig / selectToolsetProvider RPC bindings + types.

Post-setup (OAuth/install) flows still defer to the CLI; see
docs spike findings for the planned /api/tools/setup/* endpoint family.

Tests: backend round-trip + 400 cases for the new endpoints and
apply_provider_selection; desktop vitest coverage for the config panel
(provider render, select, key save). No change-detector tests.

Also removes three stale completed plan docs.

* fix(desktop): show real Hermes version + sync package.json on release

The desktop app version was disconnected from the Hermes version: the
release script bumped pyproject.toml + hermes_cli/__init__.py but never
touched apps/desktop/package.json, which sat stale at 0.0.2 (lockfile at
0.0.1).

- main.cjs: hermes:version IPC now resolves __version__ from
  hermes_cli/__init__.py (the canonical source release.py bumps) via a new
  resolveHermesVersion() helper, falling back to app.getVersion() when the
  source tree isn't readable. The About panel now always shows the live
  Hermes version and can't drift.
- release.py: update_version_files() also bumps apps/desktop/package.json
  in lockstep with pyproject (top-level version only; dep specs untouched).
- One-time catch-up: package.json 0.0.2 -> 0.15.1 and the lockfile root
  mirrors 0.0.1 -> 0.15.1.

* fix(desktop): stamp exe identity in afterPack hook so updates stay branded

The packed Hermes.exe reverted to the stock Electron icon + "Electron" name
after an in-app update. The icon/identity stamp (rcedit) lived only in
install.ps1, but the installer's --update path rebuilds the desktop via
`hermes desktop --build-only` -> `npm run pack`, which never ran install.ps1
and so never stamped the rebuilt exe.

Move the stamp into an electron-builder afterPack hook so it runs for EVERY
packed build regardless of caller (first install, hermes desktop, the update
rebuild, or a manual npm run pack):

- set-exe-identity.cjs: refactor to export stampExeIdentity(exe, desktopRoot);
  still runnable as a standalone CLI.
- after-pack.cjs (new): afterPack hook calling stampExeIdentity. Windows-only
  guard; best-effort (logs + resolves on failure, never fails the build).
- package.json: register build.afterPack.
- install.ps1: remove the now-redundant Set-DesktopExeIdentity function + call;
  the hook handles it during npm run pack.

electron-builder's own rcedit step stays disabled (signAndEditExecutable=false)
to avoid the signtool -> winCodeSign -> 7-Zip macOS-symlink crash on non-admin
Windows; the hook runs rcedit directly (pure PE resource edit, no signing).

* fix(desktop): export afterPack hook as exports.default so electron-builder runs it

The afterPack hook used `module.exports = fn`, which electron-builder's hook
loader doesn't pick up — it expects the function as the module's default
export (the same shape afterSign/notarize.cjs uses). The hook silently never
ran, so even first install shipped the stock "Electron" exe.

Switch to `exports.default = async function afterPack(...)`. Verified with a
real `npm run pack`: electron-builder now invokes the hook and the produced
release/win-unpacked/Hermes.exe carries ProductName/FileDescription=Hermes.

* chore(desktop): drop auto-build release CI in favor of manual build + upload

Remove desktop-release.yml (nightly-on-main + stable publish). Installers
are now built locally per platform and uploaded to a GitHub Release by hand;
the website points at them via NEXT_PUBLIC_HERMES_DL_* env. Update README +
docs and drop the dead desktop-nightly channel links.

* fix(desktop): stable shortcut icon + bust icon cache so updates repaint

Symptom on a freshly-installed laptop: Hermes.exe itself shows the correct
Hermes icon (Explorer reads the live exe's stamped PE resource), but the
desktop shortcut still draws the stock Electron icon.

Cause: New-DesktopShortcuts set IconLocation to "<exe>,0", so Windows cached
the icon it extracted from the exe at shortcut-creation time. On an update the
exe gets re-stamped, but the shortcut keeps rendering the stale cached bitmap.

- package.json: ship assets/icon.ico beside the exe via extraResources
  (-> resources/icon.ico). Verified with a real npm run pack.
- install.ps1 New-DesktopShortcuts: point IconLocation at resources/icon.ico
  (fallback to <exe>,0 if absent) — a dedicated .ico is cache-stable and skips
  the per-exe extraction that goes stale. Then run `ie4uinit.exe -show` to bust
  the shell icon cache so the shortcut repaints immediately instead of showing
  the old Electron icon until reboot.

Both best-effort; never fail an otherwise-good install.

* dummy update

* feat(desktop): self-heal update branch + backend contract guard

Two fixes for the bb/gui→main transition:

- Self-update self-heals: if the tracked branch (e.g. bb/gui) no longer
  exists on origin (merged + deleted), the desktop updater falls back to
  main and persists it. Read-only ls-remote probe that only flips on a
  definitive "ref absent" (exit 2), never on a transient network error, so
  already-installed clients migrate themselves with no manual flip.
- Backend contract guard: tui_gateway reports DESKTOP_BACKEND_CONTRACT in
  session runtime info; the desktop warns with a one-click "Update Hermes"
  when the backend predates the GUI's required contract (e.g. a bb/gui app
  pointed at a main checkout) instead of failing cryptically downstream.

* docs(desktop): rewrite README to match current install/update/build flow

The old README contradicted itself (claimed a bundled Python payload while
also saying it no longer bundles source) and predated cross-platform support.
Rewrite for accuracy: Linux is a first-class build target, install.sh/install.ps1
both drive the staged bootstrap, the real self-update handoff (Windows
Hermes-Setup vs in-app macOS/Linux), and the bb/gui→main self-heal + backend
contract guard.

* docs(desktop): rewrite README as a real product readme

Lead with what the app is and how to get it (download an installer, or
`hermes desktop` for existing CLI users) plus a plain-language feature list,
then keep contributor/build/internals as a clearly separated secondary section.

* docs(desktop): fix install framing — releases no longer auto-build installers

Lead with the install-with-Hermes path (`--include-desktop` / `hermes desktop`),
which always works, and describe prebuilt installers as manually published when
a release ships them rather than implying CI attaches them to every release.

* docs(desktop): match base repo README style

Adopt the root README's conventions: centered title + badge row, bold
one-liner intro, a feature <table> grid, --- section dividers, and a
Community / License footer.

* feat(desktop): recover from gateway boot failures + validate API keys on entry (#35864)

Fresh installs that hit a gateway boot failure had no recovery path: the
shell rendered dead ("gateway offline"), logs were undiscoverable, and a
mistyped API key was accepted because onboarding only checked credential
presence, not validity.

- Add BootFailureOverlay: a top-level recovery surface (Retry, Repair
  install, Use local gateway, Open logs + inline recent logs) that mounts
  on any hard boot failure, including post-install. Trims the now-redundant
  recovery button from the onboarding Preparing panel.
- Add hermes:logs:reveal / :recent IPC (reveal desktop.log) and a
  hermes:bootstrap:repair IPC that drops the bootstrap marker to force a
  clean reinstall. Surface "Open logs" in Gateway settings too.
- Add POST /api/providers/validate: a live per-provider probe
  (OpenRouter/OpenAI/xAI/Gemini key check, local endpoint connectivity)
  wired into saveOnboardingApiKey so a rejected key blocks before it's
  persisted, while an unreachable probe falls through (offline-safe).

* test(model-catalog): fix stale nous picker test after curated-list change

ac2e48907 made the GUI/picker Nous row use the curated list (curated["nous"]
= get_curated_nous_model_ids()) + Portal union, matching the `hermes model`
CLI — but test_picker_nous_row_uses_manifest still asserted the old 2-model
manifest snapshot, breaking the test shard.

Rewrite it as an invariant: stub the Portal union to passthrough and assert the
row equals get_curated_nous_model_ids() computed under the same conditions, so
it tracks the real contract instead of a hardcoded model list that rots on every
catalog update.

---------

Co-authored-by: emozilla <emozilla@nousresearch.com>
Co-authored-by: Copilot Autofix powered by AI <62310815+github-advanced-security[bot]@users.noreply.github.com>
Co-authored-by: Austin Pickett <pickett.austin@gmail.com>
Co-authored-by: Cursor <cursoragent@cursor.com>
Co-authored-by: ethernet <arilotter@gmail.com>
Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>

.env.example

@@ -417,9 +417,9 @@ IMAGE_TOOLS_DEBUG=false
 # Default STT provider is "local" (faster-whisper) — runs on your machine, no API key needed.
 # Install with: pip install faster-whisper
 # Model downloads automatically on first use (~150 MB for "base").
-# To use cloud providers instead, set GROQ_API_KEY or VOICE_TOOLS_OPENAI_KEY above.
-# Provider priority: local > groq > openai
-# Configure in config.yaml: stt.provider: local | groq | openai
+# To use cloud providers instead, set GROQ_API_KEY, VOICE_TOOLS_OPENAI_KEY, or ELEVENLABS_API_KEY above.
+# Provider priority: local > groq > openai > mistral > xai > elevenlabs
+# Configure in config.yaml: stt.provider: local | groq | openai | mistral | xai | elevenlabs
 
 # =============================================================================
 # STT ADVANCED OVERRIDES (optional)
@@ -427,10 +427,12 @@ IMAGE_TOOLS_DEBUG=false
 # Override default STT models per provider (normally set via stt.model in config.yaml)
 # STT_GROQ_MODEL=whisper-large-v3-turbo
 # STT_OPENAI_MODEL=whisper-1
+# STT_ELEVENLABS_MODEL=scribe_v2
 
 # Override STT provider endpoints (for proxies or self-hosted instances)
 # GROQ_BASE_URL=https://api.groq.com/openai/v1
 # STT_OPENAI_BASE_URL=https://api.openai.com/v1
+# ELEVENLABS_STT_BASE_URL=https://api.elevenlabs.io/v1
 
 # =============================================================================
 # MICROSOFT TEAMS INTEGRATION

.github/workflows/nix-lockfile-fix.yml

@@ -6,8 +6,8 @@ on:
     paths:
       - 'ui-tui/package-lock.json'
       - 'ui-tui/package.json'
-      - 'web/package-lock.json'
-      - 'web/package.json'
+      - 'apps/dashboard/package-lock.json'
+      - 'apps/dashboard/package.json'
   workflow_dispatch:
     inputs:
       pr_number:
@@ -28,7 +28,7 @@ concurrency:
 jobs:
   # ── Auto-fix on main ───────────────────────────────────────────────
   # Fires when a push to main touches package.json or package-lock.json
-  # in ui-tui/ or web/. Runs fix-lockfiles and pushes the hash
+  # in ui-tui/ or apps/dashboard/. Runs fix-lockfiles and pushes the hash
   # update commit directly to main so Nix builds never stay broken.
   #
   # Safety invariants:
@@ -110,7 +110,7 @@ jobs:
             # run recompute from the correct package-lock state.
             pkg_changed="$(git diff --name-only "$BASE_SHA"..origin/main -- \
               'ui-tui/package-lock.json' 'ui-tui/package.json' \
-              'web/package-lock.json' 'web/package.json' || true)"
+              'apps/dashboard/package-lock.json' 'apps/dashboard/package.json' || true)"
             if [ -n "$pkg_changed" ]; then
               echo "::warning::Package files changed since hash computation — aborting; a fresh run will recompute"
               exit 0

.gitignore

@@ -63,6 +63,10 @@ environments/benchmarks/evals/
 
 # Web UI build output
 hermes_cli/web_dist/
+apps/desktop/build/
+apps/desktop/dist/
+apps/desktop/release/
+apps/desktop/*.tsbuildinfo
 
 # Web UI assets — synced from @nous-research/ui at build time via
 # `npm run sync-assets` (see web/package.json).
@@ -85,6 +89,16 @@ website/static/api/skills-index.json
 website/static/api/skills.json
 website/static/api/skills-meta.json
 models-dev-upstream/
+
+# Local editor / agent tooling (machine-specific; keep in global config, not the repo)
+.codex/
+.cursor/
+.gemini/
+.zed/
+.mcp.json
+opencode.json
+config/mcporter.json
+
 hermes_cli/tui_dist/*
 hermes_cli/scripts/
 docs/superpowers/*

AGENTS.md

@@ -2,6 +2,8 @@
 
 Instructions for AI coding assistants and developers working on the hermes-agent codebase.
 
+**Never give up on the right solution.**
+
 ## Development Environment
 
 ```bash
@@ -66,6 +68,29 @@ hermes-agent/
 `gateway.log` when running the gateway. Profile-aware via `get_hermes_home()`.
 Browse with `hermes logs [--follow] [--level ...] [--session ...]`.
 
+## TypeScript Style
+
+Applies to TypeScript across Hermes: desktop, TUI, website, and future TS packages.
+
+- Prefer small nanostores over component state when state is shared, reused, or read by distant UI.
+- Let each feature own its atoms. Chat state belongs near chat, shell state near shell, shared state in `src/store`.
+- Components that render from an atom should use `useStore`. Non-rendering actions should read with `$atom.get()`.
+- Do not pass state through three components when the leaf can subscribe to the atom.
+- Keep persistence beside the atom that owns it.
+- Keep route roots thin. They compose routes and shell; they should not become controllers.
+- No monolithic hooks. A hook should own one narrow job.
+- Prefer colocated action modules over hidden god hooks.
+- If a callback is pure side effect, use the terse void form:
+  `onState={st => void setGatewayState(st)}`.
+- Async UI handlers should make intent explicit:
+  `onClick={() => void save()}`.
+- Prefer interfaces for public props and shared object shapes. Avoid `type X = { ... }` for object props.
+- Extend React primitives for props: `React.ComponentProps<'button'>`, `React.ComponentProps<typeof Dialog>`, `Omit<...>`, `Pick<...>`.
+- Table-driven beats condition ladders when mapping ids, routes, or views.
+- `src/app` owns routes, pages, and page-specific components.
+- `src/store` owns shared atoms.
+- `src/lib` owns shared pure helpers.
+
 ## File Dependency Chain
 
 ```

README.md

@@ -46,9 +46,9 @@ Run this in PowerShell:
 iex (irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1)
 ```
 
-The installer handles everything: uv, Python 3.11, Node.js, ripgrep, ffmpeg, **and a portable Git Bash** (MinGit, unpacked to `%LOCALAPPDATA%\hermes\git` — no admin required, completely isolated from any system Git install).  Hermes uses this bundled Git Bash to run shell commands.
+The installer handles everything: uv, Python 3.11, Node.js, ripgrep, ffmpeg, **and a portable Git Bash** (MinGit, unpacked to `%LOCALAPPDATA%\hermes\git` — no admin required, completely isolated from any system Git install). Hermes uses this bundled Git Bash to run shell commands.
 
-If you already have Git installed, the installer detects it and uses that instead.  Otherwise a ~45MB MinGit download is all you need — it won't touch or interfere with any system Git.
+If you already have Git installed, the installer detects it and uses that instead. Otherwise a ~45MB MinGit download is all you need — it won't touch or interfere with any system Git.
 
 > **Android / Termux:** The tested manual path is documented in the [Termux guide](https://hermes-agent.nousresearch.com/docs/getting-started/termux). On Termux, Hermes installs a curated `.[termux]` extra because the full `.[all]` extra currently pulls Android-incompatible voice dependencies.
 >
@@ -104,17 +104,17 @@ You can still bring your own keys per-tool whenever you want — the gateway is
 
 Hermes has two entry points: start the terminal UI with `hermes`, or run the gateway and talk to it from Telegram, Discord, Slack, WhatsApp, Signal, or Email. Once you're in a conversation, many slash commands are shared across both interfaces.
 
-| Action | CLI | Messaging platforms |
-|---------|-----|---------------------|
-| Start chatting | `hermes` | Run `hermes gateway setup` + `hermes gateway start`, then send the bot a message |
-| Start fresh conversation | `/new` or `/reset` | `/new` or `/reset` |
-| Change model | `/model [provider:model]` | `/model [provider:model]` |
-| Set a personality | `/personality [name]` | `/personality [name]` |
-| Retry or undo the last turn | `/retry`, `/undo` | `/retry`, `/undo` |
-| Compress context / check usage | `/compress`, `/usage`, `/insights [--days N]` | `/compress`, `/usage`, `/insights [days]` |
-| Browse skills | `/skills` or `/<skill-name>` | `/<skill-name>` |
-| Interrupt current work | `Ctrl+C` or send a new message | `/stop` or send a new message |
-| Platform-specific status | `/platforms` | `/status`, `/sethome` |
+| Action                         | CLI                                           | Messaging platforms                                                              |
+| ------------------------------ | --------------------------------------------- | -------------------------------------------------------------------------------- |
+| Start chatting                 | `hermes`                                      | Run `hermes gateway setup` + `hermes gateway start`, then send the bot a message |
+| Start fresh conversation       | `/new` or `/reset`                            | `/new` or `/reset`                                                               |
+| Change model                   | `/model [provider:model]`                     | `/model [provider:model]`                                                        |
+| Set a personality              | `/personality [name]`                         | `/personality [name]`                                                            |
+| Retry or undo the last turn    | `/retry`, `/undo`                             | `/retry`, `/undo`                                                                |
+| Compress context / check usage | `/compress`, `/usage`, `/insights [--days N]` | `/compress`, `/usage`, `/insights [days]`                                        |
+| Browse skills                  | `/skills` or `/<skill-name>`                  | `/<skill-name>`                                                                  |
+| Interrupt current work         | `Ctrl+C` or send a new message                | `/stop` or send a new message                                                    |
+| Platform-specific status       | `/platforms`                                  | `/status`, `/sethome`                                                            |
 
 For the full command lists, see the [CLI guide](https://hermes-agent.nousresearch.com/docs/user-guide/cli) and the [Messaging Gateway guide](https://hermes-agent.nousresearch.com/docs/user-guide/messaging).
 
@@ -124,23 +124,23 @@ For the full command lists, see the [CLI guide](https://hermes-agent.nousresearc
 
 All documentation lives at **[hermes-agent.nousresearch.com/docs](https://hermes-agent.nousresearch.com/docs/)**:
 
-| Section | What's Covered |
-|---------|---------------|
-| [Quickstart](https://hermes-agent.nousresearch.com/docs/getting-started/quickstart) | Install → setup → first conversation in 2 minutes |
-| [CLI Usage](https://hermes-agent.nousresearch.com/docs/user-guide/cli) | Commands, keybindings, personalities, sessions |
-| [Configuration](https://hermes-agent.nousresearch.com/docs/user-guide/configuration) | Config file, providers, models, all options |
-| [Messaging Gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging) | Telegram, Discord, Slack, WhatsApp, Signal, Home Assistant |
-| [Security](https://hermes-agent.nousresearch.com/docs/user-guide/security) | Command approval, DM pairing, container isolation |
-| [Tools & Toolsets](https://hermes-agent.nousresearch.com/docs/user-guide/features/tools) | 40+ tools, toolset system, terminal backends |
-| [Skills System](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills) | Procedural memory, Skills Hub, creating skills |
-| [Memory](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory) | Persistent memory, user profiles, best practices |
-| [MCP Integration](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp) | Connect any MCP server for extended capabilities |
-| [Cron Scheduling](https://hermes-agent.nousresearch.com/docs/user-guide/features/cron) | Scheduled tasks with platform delivery |
-| [Context Files](https://hermes-agent.nousresearch.com/docs/user-guide/features/context-files) | Project context that shapes every conversation |
-| [Architecture](https://hermes-agent.nousresearch.com/docs/developer-guide/architecture) | Project structure, agent loop, key classes |
-| [Contributing](https://hermes-agent.nousresearch.com/docs/developer-guide/contributing) | Development setup, PR process, code style |
-| [CLI Reference](https://hermes-agent.nousresearch.com/docs/reference/cli-commands) | All commands and flags |
-| [Environment Variables](https://hermes-agent.nousresearch.com/docs/reference/environment-variables) | Complete env var reference |
+| Section                                                                                             | What's Covered                                             |
+| --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
+| [Quickstart](https://hermes-agent.nousresearch.com/docs/getting-started/quickstart)                 | Install → setup → first conversation in 2 minutes          |
+| [CLI Usage](https://hermes-agent.nousresearch.com/docs/user-guide/cli)                              | Commands, keybindings, personalities, sessions             |
+| [Configuration](https://hermes-agent.nousresearch.com/docs/user-guide/configuration)                | Config file, providers, models, all options                |
+| [Messaging Gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging)                | Telegram, Discord, Slack, WhatsApp, Signal, Home Assistant |
+| [Security](https://hermes-agent.nousresearch.com/docs/user-guide/security)                          | Command approval, DM pairing, container isolation          |
+| [Tools & Toolsets](https://hermes-agent.nousresearch.com/docs/user-guide/features/tools)            | 40+ tools, toolset system, terminal backends               |
+| [Skills System](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills)              | Procedural memory, Skills Hub, creating skills             |
+| [Memory](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory)                     | Persistent memory, user profiles, best practices           |
+| [MCP Integration](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp)               | Connect any MCP server for extended capabilities           |
+| [Cron Scheduling](https://hermes-agent.nousresearch.com/docs/user-guide/features/cron)              | Scheduled tasks with platform delivery                     |
+| [Context Files](https://hermes-agent.nousresearch.com/docs/user-guide/features/context-files)       | Project context that shapes every conversation             |
+| [Architecture](https://hermes-agent.nousresearch.com/docs/developer-guide/architecture)             | Project structure, agent loop, key classes                 |
+| [Contributing](https://hermes-agent.nousresearch.com/docs/developer-guide/contributing)             | Development setup, PR process, code style                  |
+| [CLI Reference](https://hermes-agent.nousresearch.com/docs/reference/cli-commands)                  | All commands and flags                                     |
+| [Environment Variables](https://hermes-agent.nousresearch.com/docs/reference/environment-variables) | Complete env var reference                                 |
 
 ---
 
@@ -160,6 +160,7 @@ hermes claw migrate --overwrite  # Overwrite existing conflicts
 ```
 
 What gets imported:
+
 - **SOUL.md** — persona file
 - **Memories** — MEMORY.md and USER.md entries
 - **Skills** — user-created skills → `~/.hermes/skills/openclaw-imports/`

RELEASE_v0.14.0.md

@@ -3,75 +3,73 @@
 **Release Date:** May 16, 2026
 **Since v0.13.0:** 808 commits · 633 merged PRs · 1393 files changed · 165,061 insertions · 545 issues closed (12 P0, 50 P1) · 215 community contributors (including co-authors)
 
-> The Foundation Release — Hermes installs and runs anywhere, ships with the things you actually want to use, and stops shipping the things you don't. xAI Grok lands as a SuperGrok OAuth provider with grok-4.3 bumped to a 1M context window. A new OpenAI-compatible local proxy turns any OAuth-authed Hermes provider — Claude Pro, ChatGPT Pro, SuperGrok — into an endpoint that Codex / Aider / Cline / Continue can hit. `x_search` lands as a first-class X (Twitter) search tool with OAuth-or-API-key auth. The Microsoft Teams stack is wired end-to-end (Graph auth + webhook listener + pipeline runtime + outbound delivery). A debloating wave makes installs dramatically lighter — heavyweight backends now lazy-install on first use, the `[all]` extras drop everything covered by lazy-deps, and a tiered install falls back when a wheel rejects on your platform. `pip install hermes-agent` works from PyPI. The cold-start wave shaves ~19 seconds off `hermes` launch. Browser CDP calls are 180x faster. Two new messaging platforms (LINE + SimpleX Chat) bring the total to 22. Cross-session 1-hour Claude prompt caching, `/handoff` that actually transfers sessions live, native button UI for `clarify` on Telegram and Discord, Discord channel history backfill, LSP semantic diagnostics on every write, a unified pluggable `video_generate`, a `computer_use` cua-driver backend that finally works with non-Anthropic providers, clickable URLs in any terminal, Zed ACP Registry integration via `uvx`, native Windows beta, 9 new optional skills, OpenRouter Pareto Code router, huggingface/skills as a trusted default tap. 12 P0 + 50 P1 closures.
+> The Foundation Release — Hermes Agent installs and runs anywhere now. Native Windows ships in early beta with a full PowerShell installer story, a `pip install hermes-agent` wheel lands on PyPI, lazy-deps reshape what `pip install hermes-agent` actually pulls down, the supply-chain checker scans every install/upgrade for unsafe versions, and a new OpenAI-compatible local proxy lets Codex / Aider / Cline talk to OAuth-only providers (Claude Pro, ChatGPT Pro, SuperGrok). The cold-start wave shaves ~19 seconds off `hermes` launch, browser-tool CDP calls run 180x faster, and `hermes tools` All-Platforms drops from 14s to under 1.5s. Two new messaging platforms (LINE and SimpleX Chat) and a Microsoft Graph foundation (Teams pipeline + webhook adapter) land alongside `/handoff` that finally transfers sessions live, `vision_analyze` passing pixels through to vision-capable models, `x_search` as a first-class tool, LSP semantic diagnostics on every `write_file` / `patch`, a unified pluggable `video_generate`, a `computer_use` cua-driver backend, cross-session 1-hour Claude prompt caching, a per-turn file-mutation verifier, plus 9 new optional skills. 50+ P1 closures, 12 P0 closures.
 
 ---
 
 ## ✨ Highlights
 
-- **xAI Grok via SuperGrok OAuth — and grok-4.3 jumps to a 1M context window** — If you pay for SuperGrok, you can now use Grok inside Hermes by signing in with your xAI account — no API key, no separate billing. The wire-through also bumps grok-4.3 to a 1M token context window, so you can drop whole codebases or research corpora into a single prompt. Includes proper handling for entitlement errors and an SSH-to-tunnel docs page for when you're SSH'd into a remote box and need to complete the OAuth flow. ([#26534](https://github.com/NousResearch/hermes-agent/pull/26534), [#26664](https://github.com/NousResearch/hermes-agent/pull/26664), [#26644](https://github.com/NousResearch/hermes-agent/pull/26644), [#26592](https://github.com/NousResearch/hermes-agent/pull/26592))
+- **Native Windows support (early beta)** — full PowerShell installer, native subprocess/PTY paths, taskkill-based process management, MinGit auto-install, Microsoft Store python stub detection, foreground Ctrl+C preservation, taskkill+ps2 fallback, npm prefix handling, and ~40 follow-up Windows-only fixes across CLI / gateway / TUI / curator / tools. Hermes finally runs natively on `cmd.exe` and PowerShell, no WSL required. ([#21561](https://github.com/NousResearch/hermes-agent/pull/21561), [#22130](https://github.com/NousResearch/hermes-agent/pull/22130), [#22752](https://github.com/NousResearch/hermes-agent/pull/22752), [#26618](https://github.com/NousResearch/hermes-agent/pull/26618), and many more)
 
-- **OpenAI-compatible local proxy for OAuth providers** — Run `hermes proxy` and you get a `http://localhost:port` endpoint that speaks the OpenAI API but is backed by whichever OAuth provider you're signed into — Claude Pro, ChatGPT Pro, SuperGrok. Now any tool that expects an OpenAI-compatible endpoint (Codex CLI, Aider, Cline, Continue, your custom scripts) just works with your existing subscription, no API key required. One subscription, every tool. ([#25969](https://github.com/NousResearch/hermes-agent/pull/25969))
+- **`pip install hermes-agent && hermes`** — Hermes Agent is now a real PyPI package. One command, no clone, no git, no shell installer. Wheel includes the Ink TUI bundle and shell launcher. (salvage of [#26350](https://github.com/NousResearch/hermes-agent/pull/26350)) ([#26593](https://github.com/NousResearch/hermes-agent/pull/26593))
 
-- **`x_search` — first-class X (Twitter) search tool** — The agent can now search X directly without installing a skill or wiring up a custom integration. Search the timeline, find threads, surface specific posts — straight from the chat. Auth with either your X OAuth login or an API key, whichever you have. ([#26763](https://github.com/NousResearch/hermes-agent/pull/26763))
+- **Cold-start performance wave — ~19s off `hermes` launch** — skills cache, lazy Feishu import, no Nous HTTP at startup, plus PEP-562 lazy adapter imports (QQ, Yuanbao, Teams, Google Chat), deferred `fal_client` / `google-cloud` / `httpx` loads, models.dev disk-cache-first lookup, parallel doctor API checks, eager-skip plugin discovery on built-in subcommands, `hermes tools` All-Platforms drops from 14s to <1.5s, welcome banner skipped on `chat -q`. ([#22138](https://github.com/NousResearch/hermes-agent/pull/22138), [#22120](https://github.com/NousResearch/hermes-agent/pull/22120), [#22681](https://github.com/NousResearch/hermes-agent/pull/22681), [#22790](https://github.com/NousResearch/hermes-agent/pull/22790), [#22808](https://github.com/NousResearch/hermes-agent/pull/22808), [#22831](https://github.com/NousResearch/hermes-agent/pull/22831), [#22859](https://github.com/NousResearch/hermes-agent/pull/22859), [#22904](https://github.com/NousResearch/hermes-agent/pull/22904), [#22766](https://github.com/NousResearch/hermes-agent/pull/22766), [#25341](https://github.com/NousResearch/hermes-agent/pull/25341))
 
-- **Microsoft Teams — end-to-end** — Hermes can now read messages from Teams and post back. The full Microsoft Graph stack lands together: auth + client foundation, a webhook listener that receives Teams events, a pipeline plugin runtime, and outbound delivery. Wire up the bot once, then chat to your agent from any Teams channel, DM, or group. (salvages of #21408–#21411) ([#21922](https://github.com/NousResearch/hermes-agent/pull/21922), [#21969](https://github.com/NousResearch/hermes-agent/pull/21969), [#22007](https://github.com/NousResearch/hermes-agent/pull/22007), [#22024](https://github.com/NousResearch/hermes-agent/pull/22024))
+- **180x faster `browser_console` evaluations** — routed through the supervisor's persistent CDP WebSocket instead of spawning a fresh DevTools session per call. Real-world page interactions feel instant. ([#23226](https://github.com/NousResearch/hermes-agent/pull/23226))
 
-- **Debloating wave — lighter installs, less you don't use** — A clean `pip install hermes-agent` used to pull down everything: every messaging adapter SDK, every image-gen SDK, every voice/TTS provider, whether you used them or not. Now those heavy backends (Slack / Matrix / Feishu / DingTalk adapters, hindsight client, codex app-server, Pixverse / Camofox / image-gen SDKs, voice/TTS providers) install automatically the first time you actually use them. The `[all]` extras drop everything covered by lazy-deps, the installer falls back through tiers when a wheel doesn't fit your platform, and a supply-chain advisory checker scans every install for unsafe versions. Faster installs, smaller disk footprint, fewer transitive vulnerabilities. ([#24220](https://github.com/NousResearch/hermes-agent/pull/24220), [#24515](https://github.com/NousResearch/hermes-agent/pull/24515), [#25014](https://github.com/NousResearch/hermes-agent/pull/25014), [#25038](https://github.com/NousResearch/hermes-agent/pull/25038), [#25766](https://github.com/NousResearch/hermes-agent/pull/25766), [#21818](https://github.com/NousResearch/hermes-agent/pull/21818))
+- **Supply-chain advisory checker + lazy-deps framework + tiered install fallback** — every `pip install` / `hermes update` scans dependencies against an advisory list, lazy-deps replace heavy import-time loads with first-use installs, and the installer falls back through extras tiers when a wheel rejects on the target platform. ([#24220](https://github.com/NousResearch/hermes-agent/pull/24220))
 
-- **`pip install hermes-agent && hermes`** — Hermes Agent is now a real PyPI package. No more cloning the repo or running shell installers — one pip command and you're running. The wheel ships with the Ink TUI bundle and the shell launcher, so the full experience comes out of the box. (salvage of [#26350](https://github.com/NousResearch/hermes-agent/pull/26350)) ([#26593](https://github.com/NousResearch/hermes-agent/pull/26593), [#26148](https://github.com/NousResearch/hermes-agent/pull/26148))
+- **OpenAI-compatible local proxy** — `hermes proxy` exposes any OAuth-authed provider (Claude Pro, ChatGPT Pro, SuperGrok) as an OpenAI-compatible endpoint that Codex / Aider / Cline / VS Code Continue can hit. Your subscription, your tools. ([#25969](https://github.com/NousResearch/hermes-agent/pull/25969))
 
-- **Cross-session 1h Claude prompt cache** — When you use Claude through Anthropic, OpenRouter, or Nous Portal, the prompt prefix (system prompt, skills, memory) now caches for an hour across sessions. Start a `/new` session and the first response comes back faster and cheaper because the cache is still warm from your last session. Background memory review hits the cache too, so it's not paying full price every turn. ([#23828](https://github.com/NousResearch/hermes-agent/pull/23828), [#25434](https://github.com/NousResearch/hermes-agent/pull/25434), [#24778](https://github.com/NousResearch/hermes-agent/pull/24778))
+- **Cross-session 1-hour Claude prompt cache** — Anthropic / OpenRouter / Nous Portal now share a 1h prefix cache across sessions for Claude models. Fast resume, fast `/new`, lower cost on repeat work. ([#23828](https://github.com/NousResearch/hermes-agent/pull/23828))
 
-- **180x faster `browser_console` evaluations** — When the agent uses the browser tool to inspect a page or run JavaScript, those calls now share one persistent connection to Chrome instead of spinning up a new DevTools session every time. The difference is huge: things that used to take a couple of seconds per call return in milliseconds. Real-world page interactions feel instant. ([#23226](https://github.com/NousResearch/hermes-agent/pull/23226))
+- **Two new messaging platforms — LINE + SimpleX Chat** — LINE Messaging API lands as a first-class platform, SimpleX Chat salvages #2558 onto the modern adapter spec. Hermes is now on 22 platforms. ([#23197](https://github.com/NousResearch/hermes-agent/pull/23197), [#26232](https://github.com/NousResearch/hermes-agent/pull/26232))
 
-- **Cold-start performance wave — ~19 seconds off `hermes` launch** — Running `hermes` used to make you wait through a chunk of import overhead and network calls before you saw a prompt. Now the launch path is mostly deferred: heavy adapters only load when you use them, model catalogs come from disk cache first, doctor checks run in parallel, and `chat -q` skips the welcome banner entirely. The `hermes tools` All-Platforms screen alone dropped from 14 seconds to under 1.5 seconds. ([#22138](https://github.com/NousResearch/hermes-agent/pull/22138), [#22120](https://github.com/NousResearch/hermes-agent/pull/22120), [#22681](https://github.com/NousResearch/hermes-agent/pull/22681), [#22790](https://github.com/NousResearch/hermes-agent/pull/22790), [#22808](https://github.com/NousResearch/hermes-agent/pull/22808), [#22831](https://github.com/NousResearch/hermes-agent/pull/22831), [#22859](https://github.com/NousResearch/hermes-agent/pull/22859), [#22904](https://github.com/NousResearch/hermes-agent/pull/22904), [#22766](https://github.com/NousResearch/hermes-agent/pull/22766), [#25341](https://github.com/NousResearch/hermes-agent/pull/25341))
+- **Microsoft Graph foundation — Teams pipeline + webhook adapter** — `msgraph` auth/client foundation, webhook listener platform, Teams pipeline plugin runtime, and Teams outbound delivery via the existing adapter — Hermes can now read and post to Teams. (salvages of #21408–#21411) ([#21922](https://github.com/NousResearch/hermes-agent/pull/21922), [#21969](https://github.com/NousResearch/hermes-agent/pull/21969), [#22007](https://github.com/NousResearch/hermes-agent/pull/22007), [#22024](https://github.com/NousResearch/hermes-agent/pull/22024))
 
-- **Two new messaging platforms — LINE + SimpleX Chat** — LINE is huge in Japan, Korea, and Taiwan, and now Hermes runs natively on the LINE Messaging API. SimpleX Chat is the privacy-focused decentralized messenger with no user IDs — also wired up as a first-class platform. That brings Hermes to 22 messaging platforms total, so wherever you and your team chat, the agent can be there. ([#23197](https://github.com/NousResearch/hermes-agent/pull/23197), [#26232](https://github.com/NousResearch/hermes-agent/pull/26232))
+- **`/handoff` actually transfers the session live** — the agent's active session moves to a different model / persona / profile mid-conversation, with messages, tool history, and context preserved. ([#23395](https://github.com/NousResearch/hermes-agent/pull/23395))
 
-- **`/handoff` actually transfers the session live** — Switching models or personalities mid-conversation used to mean losing context or starting over. Now `/handoff` moves your active session — every message, every tool call, every piece of context — to the target model, persona, or profile, live, without dropping anything. Mid-debugging hand off from a fast model to a deep-reasoning one, or pass a session between profiles for different parts of a task. ([#23395](https://github.com/NousResearch/hermes-agent/pull/23395))
+- **`x_search` — first-class X (Twitter) search tool** — gated tool with OAuth-or-API-key auth, no skill needed to query the timeline. ([#26763](https://github.com/NousResearch/hermes-agent/pull/26763))
 
-- **Native button UI for `clarify` on Telegram and Discord** — When the agent uses the `clarify` tool to ask you a multiple-choice question, it now shows real platform-native buttons on Telegram and Discord instead of asking you to type back the option number. Tap the button, the agent gets your answer. Especially nice on mobile. ([#24199](https://github.com/NousResearch/hermes-agent/pull/24199), [#25485](https://github.com/NousResearch/hermes-agent/pull/25485))
+- **`vision_analyze` returns pixels to vision-capable models** — when the active model can see, `vision_analyze` now hands the image straight through instead of falling back to a text description. ([#22955](https://github.com/NousResearch/hermes-agent/pull/22955))
 
-- **Discord channel history backfill (default on)** — When Hermes joins a Discord channel or thread for the first time, it now reads the recent message history so it knows what's been said before it responds. No more "what are we talking about?" — the agent has the context that's already on screen for everyone else. ([#25984](https://github.com/NousResearch/hermes-agent/pull/25984))
+- **LSP semantic diagnostics on every write** — `write_file` and `patch` now run real language-server diagnostics on the post-edit file (delta-only) and surface real errors before they ship downstream. ([#24168](https://github.com/NousResearch/hermes-agent/pull/24168), [#25978](https://github.com/NousResearch/hermes-agent/pull/25978))
 
-- **`vision_analyze` returns pixels to vision-capable models** — When you point the agent at an image with `vision_analyze` and the active model can actually see (GPT-5, Claude, Gemini, Grok-vision), Hermes now passes the raw pixels straight to the model instead of converting them to a text description first. You get the model's actual visual reasoning instead of a degraded text-summary round-trip. ([#22955](https://github.com/NousResearch/hermes-agent/pull/22955))
+- **Per-turn file-mutation verifier footer** — after every turn that wrote files, the agent gets a verifier footer summarizing what actually changed on disk — catches silent overwrites and "wrote it but it didn't land" bugs. ([#24498](https://github.com/NousResearch/hermes-agent/pull/24498))
 
-- **Per-turn file-mutation verifier footer** — After every turn that wrote or edited files, the agent now gets a short footer summarizing exactly what changed on disk — the file paths, the line counts, the actual delta. That means the agent catches its own mistakes when a write didn't land or got silently overwritten, instead of confidently telling you "I added the function" when the file wasn't actually saved. ([#24498](https://github.com/NousResearch/hermes-agent/pull/24498))
+- **Unified `video_generate` with pluggable provider backends** — single tool, any backend. Drop in a new video provider as a plugin, no core changes. ([#25126](https://github.com/NousResearch/hermes-agent/pull/25126))
 
-- **LSP semantic diagnostics on every write** — When the agent uses `write_file` or `patch`, Hermes now runs a real language server against the edited file and surfaces any new errors back to the agent before the next turn. Type errors, undefined symbols, missing imports — caught immediately. Goes way beyond v0.13.0's basic Python/JSON/YAML/TOML linting because it's actual semantic analysis. ([#24168](https://github.com/NousResearch/hermes-agent/pull/24168), [#25978](https://github.com/NousResearch/hermes-agent/pull/25978))
+- **`computer_use` cua-driver backend** — proper focus-safe ops, non-Anthropic provider support, refresh on `hermes update`. Computer-use is no longer locked to a single SDK. (re-salvage of #16936) ([#21967](https://github.com/NousResearch/hermes-agent/pull/21967), [#24063](https://github.com/NousResearch/hermes-agent/pull/24063))
 
-- **Unified `video_generate` with pluggable provider backends** — One tool, any video model. Hermes ships with the obvious backends already, but you can drop in a new video provider as a plugin without touching core. So when a new video model lands next month, it can be a one-file plugin instead of a fork. ([#25126](https://github.com/NousResearch/hermes-agent/pull/25126))
+- **xAI Grok OAuth provider — SuperGrok via subscription** — sign in with your xAI account, talk to Grok models from Hermes. ([#26534](https://github.com/NousResearch/hermes-agent/pull/26534))
 
-- **`computer_use` cua-driver backend — works with non-Anthropic models now** — Computer-use (the agent controlling your mouse and keyboard to drive GUI apps) used to be locked to Anthropic's SDK. The new cua-driver backend works with non-Anthropic providers too, has proper focus-safe operations, and refreshes itself on `hermes update`. Now any vision-capable model can drive your desktop. (re-salvage of #16936) ([#21967](https://github.com/NousResearch/hermes-agent/pull/21967), [#24063](https://github.com/NousResearch/hermes-agent/pull/24063))
+- **Clarify with buttons — native inline keyboards on Telegram + Discord** — the `clarify` tool renders multi-choice prompts as platform-native buttons instead of typed responses. ([#24199](https://github.com/NousResearch/hermes-agent/pull/24199), [#25485](https://github.com/NousResearch/hermes-agent/pull/25485))
 
-- **Clickable URLs in any terminal** — Links in agent output are now real OSC8 hyperlinks with hover-highlight in any terminal that supports them. Click to open in your browser — no more copy-paste-trim of long URLs from the transcript. Just works in iTerm2, Kitty, Ghostty, modern Windows Terminal, etc. (@OutThisLife) ([#25071](https://github.com/NousResearch/hermes-agent/pull/25071), [#24013](https://github.com/NousResearch/hermes-agent/pull/24013))
+- **Discord channel history backfill (default on)** — Hermes reads recent channel history when joining a thread so it actually knows what's been said. ([#25984](https://github.com/NousResearch/hermes-agent/pull/25984))
 
-- **Zed ACP Registry — `uvx` install in one click** — Hermes is now listed in Zed's Agent Client Protocol registry, so Zed users can install it with one click. The install path uses `uvx` so there's no npm dependency. `hermes acp --setup-browser` bootstraps the browser tools for registry-driven installs. (salvage of [#25908](https://github.com/NousResearch/hermes-agent/pull/25908)) ([#26079](https://github.com/NousResearch/hermes-agent/pull/26079), [#26120](https://github.com/NousResearch/hermes-agent/pull/26120), [#26234](https://github.com/NousResearch/hermes-agent/pull/26234))
+- **Watchers skill — RSS / HTTP JSON / GitHub polling via cron `no_agent` mode** — skill recipes that wire change-detection sources directly into cron's script-only watchdog mode. ([#21881](https://github.com/NousResearch/hermes-agent/pull/21881))
 
-- **OpenRouter Pareto Code router with `min_coding_score` knob** — OpenRouter's "Pareto" router automatically picks the cheapest model that meets a minimum quality bar. The new `min_coding_score` config lets you set that bar for coding tasks specifically — Hermes routes to the most affordable model that's at least that good at code. Stop paying for top-tier models when a mid-tier one would do. ([#22838](https://github.com/NousResearch/hermes-agent/pull/22838))
+- **Zed ACP Registry integration + uvx distribution** — Hermes is in the Zed registry, installable via `uvx` (no npm). Plus `hermes acp --setup-browser` bootstraps browser tools for registry installs. (salvage of [#25908](https://github.com/NousResearch/hermes-agent/pull/25908)) ([#26079](https://github.com/NousResearch/hermes-agent/pull/26079), [#26120](https://github.com/NousResearch/hermes-agent/pull/26120), [#26234](https://github.com/NousResearch/hermes-agent/pull/26234))
 
-- **NovitaAI as a new model provider** — NovitaAI joins the provider lineup, giving you another option for open-source model hosting (Llama, Qwen, DeepSeek, etc.) with their pricing and rate limits. (salvage #7219) (@kshitijk4poor) ([#25507](https://github.com/NousResearch/hermes-agent/pull/25507))
+- **OpenRouter Pareto Code router** — wire a new OpenRouter router with `min_coding_score` knob. Pick the cheapest model that meets your quality bar. ([#22838](https://github.com/NousResearch/hermes-agent/pull/22838))
 
-- **Codex app-server runtime for OpenAI/Codex models** — An optional runtime that drives OpenAI's Codex CLI under the hood when you're using OpenAI or Codex paths. You get session reuse, automatic retirement of wedged sessions, and proper OAuth refresh classification — the kind of plumbing that makes long agentic runs not fall over. ([#24182](https://github.com/NousResearch/hermes-agent/pull/24182), [#25769](https://github.com/NousResearch/hermes-agent/pull/25769))
+- **Optional codex app-server runtime for OpenAI/Codex models** — drives the OpenAI Codex CLI under the hood for OpenAI/Codex paths, with session reuse, wedge retirement, and OAuth refresh classification. ([#24182](https://github.com/NousResearch/hermes-agent/pull/24182), [#25769](https://github.com/NousResearch/hermes-agent/pull/25769))
 
-- **`huggingface/skills` as a trusted default tap** — The community skills index hosted at huggingface.co/skills is now wired into the Skills Hub by default. So when somebody publishes a useful skill there, you can install it from your own `hermes skills` browser without any extra config. (closes #2549) ([#26219](https://github.com/NousResearch/hermes-agent/pull/26219))
+- **`hermes-skills/huggingface` as a trusted default tap** — community skills index from huggingface.co/skills is available by default in the Skills Hub. ([#26219](https://github.com/NousResearch/hermes-agent/pull/26219))
 
-- **9 new optional skills** — Hyperliquid (perp + spot trading via the SDK and REST API), Yahoo Finance (live market data, fundamentals, historicals), api-testing (REST + GraphQL debug recipes), unified EVM multi-chain (one skill covers Ethereum + L2s + Base), darwinian-evolver (evolutionary prompt/skill tuning), osint-investigation (OSINT recipes for people / domains / orgs), pinggy-tunnel (expose local services to the public internet), watchers (polls RSS / HTTP JSON / GitHub via cron `no_agent` mode for change detection), and a full Notion overhaul for the May 2026 Developer Platform. ([#23582](https://github.com/NousResearch/hermes-agent/pull/23582), [#23583](https://github.com/NousResearch/hermes-agent/pull/23583), [#23590](https://github.com/NousResearch/hermes-agent/pull/23590), [#25299](https://github.com/NousResearch/hermes-agent/pull/25299), [#26760](https://github.com/NousResearch/hermes-agent/pull/26760), [#26729](https://github.com/NousResearch/hermes-agent/pull/26729), [#26765](https://github.com/NousResearch/hermes-agent/pull/26765), [#21881](https://github.com/NousResearch/hermes-agent/pull/21881), [#26612](https://github.com/NousResearch/hermes-agent/pull/26612))
+- **9 new optional skills** — Hyperliquid (perp/spot trading via SDK + REST) (@kshitijk4poor & Hermes), Yahoo Finance market data, api-testing (REST/GraphQL debug), unified EVM multi-chain skill (folds #25291 + #2010 + base/), darwinian-evolver, osint-investigation (closes #355), pinggy-tunnel, watchers (RSS/HTTP/GitHub via cron), Notion overhaul for the Developer Platform (May 2026). ([#23582](https://github.com/NousResearch/hermes-agent/pull/23582), [#23583](https://github.com/NousResearch/hermes-agent/pull/23583), [#23590](https://github.com/NousResearch/hermes-agent/pull/23590), [#25299](https://github.com/NousResearch/hermes-agent/pull/25299), [#26760](https://github.com/NousResearch/hermes-agent/pull/26760), [#26729](https://github.com/NousResearch/hermes-agent/pull/26729), [#26765](https://github.com/NousResearch/hermes-agent/pull/26765), [#21881](https://github.com/NousResearch/hermes-agent/pull/21881), [#26612](https://github.com/NousResearch/hermes-agent/pull/26612))
 
-- **API server exposes run approval events** — If you're driving Hermes programmatically through the HTTP API, long-running runs no longer silently hang when the agent hits an approval-required command. The approval request now surfaces on the API stream so your client can prompt the user and reply — no more silent stalls. (salvage of [#20311](https://github.com/NousResearch/hermes-agent/pull/20311)) ([#21899](https://github.com/NousResearch/hermes-agent/pull/21899))
+- **API server exposes run approval events** — long-running runs surface approval requests over the API stream, no more silent stalls. (salvage of [#20311](https://github.com/NousResearch/hermes-agent/pull/20311)) ([#21899](https://github.com/NousResearch/hermes-agent/pull/21899))
 
-- **Plugins can run any LLM call via `ctx.llm` + replace built-in tools via `tool_override`** — If you're writing a Hermes plugin, you now get first-class access to make LLM calls through the active provider and credentials — no manual client wiring. The new `tool_override` flag lets a plugin swap out a built-in tool with its own implementation cleanly. Plugin authors get the same model-routing and auth plumbing the core agent uses. (closes #11049) ([#23194](https://github.com/NousResearch/hermes-agent/pull/23194), [#26759](https://github.com/NousResearch/hermes-agent/pull/26759))
+- **`/subgoal` — user-added criteria appended to active `/goal`** — layer extra success criteria onto a running goal loop. The judge sees them in the prompt, no behavior change when subgoals are empty. ([#25449](https://github.com/NousResearch/hermes-agent/pull/25449))
 
-- **Brave Search (free tier) + DuckDuckGo (DDGS) as web-search providers** — Two new free web-search backends join Tavily, SearXNG, and Exa. Brave Search has a generous free tier; DDGS is the DuckDuckGo scraper that needs no key at all. Pick whichever fits your budget and rate-limit needs. ([#21337](https://github.com/NousResearch/hermes-agent/pull/21337))
+- **Plugins can run any LLM call via `ctx.llm`** — plugins get a first-class hook to make their own LLM requests through the active provider/credentials, no manual wiring. Plus `tool_override` flag for replacing built-in tools. ([#23194](https://github.com/NousResearch/hermes-agent/pull/23194), [#26759](https://github.com/NousResearch/hermes-agent/pull/26759))
 
-- **Sudo brute-force block + 3 dangerous-command bypasses closed + tool-error sanitization** — The approval gate now blocks `sudo -S` brute-force attempts and classifies stdin-fed or askpass-stripped sudo invocations as DANGEROUS. Three known bypasses of dangerous-command detection are closed (inspired by Claude Code's command-detection work). And tool error strings are now sanitized before being re-injected into the model context, so a malicious file or remote service can't pass instructions to your agent through error output. ([#23736](https://github.com/NousResearch/hermes-agent/pull/23736), [#26829](https://github.com/NousResearch/hermes-agent/pull/26829), [#26823](https://github.com/NousResearch/hermes-agent/pull/26823))
+- **Brave Search (free tier) + DuckDuckGo (DDGS) as web-search providers** — two new free search backends alongside Tavily / SearXNG / Exa. ([#21337](https://github.com/NousResearch/hermes-agent/pull/21337))
 
-- **`/subgoal` — user-added criteria appended to an active `/goal`** — When you've got a `/goal` running (the persistent Ralph-loop goal where the agent keeps going until criteria are met), you can now use `/subgoal <text>` to layer extra success criteria onto it mid-run. The judge factors your new criteria into the done-or-keep-going decision without restarting the loop. ([#25449](https://github.com/NousResearch/hermes-agent/pull/25449))
+- **Sudo brute-force block + sudo-stdin/askpass DANGEROUS classification** — closes the `sudo -S` brute-force avenue; approval gates classify stdin-fed and askpass-stripped sudo invocations as dangerous. (salvages of #22194 + #21128) ([#23736](https://github.com/NousResearch/hermes-agent/pull/23736))
 
-- **Provider rename — Alibaba Cloud → Qwen Cloud** — The Alibaba Cloud provider is renamed to Qwen Cloud in the picker and config to match what the rest of the world calls it. Existing config keys still work — no breaking changes — but the UI matches the actual brand now. ([#24835](https://github.com/NousResearch/hermes-agent/pull/24835))
-
-- **Native Windows support (early beta)** — Hermes now runs natively on `cmd.exe` and PowerShell without WSL. A full PowerShell installer handles MinGit auto-install, Microsoft Store python stub detection, and the foreground Ctrl+C dance. There's still rough edges (this is the "early beta" stamp) — ~40 follow-up Windows-only fixes already landed in the window — but the basic loop works end-to-end on a clean Windows box. ([#21561](https://github.com/NousResearch/hermes-agent/pull/21561))
+- **Provider rename — Alibaba Cloud → Qwen Cloud, picker reorder** — matches what the world calls it. Existing config keys still work. ([#24835](https://github.com/NousResearch/hermes-agent/pull/24835))
 
 
 ---

agent/moonshot_schema.py

@@ -15,18 +15,6 @@ and MoonshotAI/kimi-cli#1595:
 2. When ``anyOf`` is used, ``type`` must be on the ``anyOf`` children, not
    the parent.  Presence of both causes "type should be defined in anyOf
    items instead of the parent schema".
-3. ``enum`` arrays on scalar-typed nodes may not contain ``null`` or empty
-   strings.  Strip those entries (drop the enum entirely if it becomes empty).
-4. ``$ref`` nodes may not carry sibling keywords.  Moonshot expands the
-   reference before validation and then rejects the node if sibling keys
-   like ``description`` remain on the same node as ``$ref``.  Strip every
-   sibling from ``$ref`` nodes so only ``{"$ref": "..."}`` survives.
-   (Ported from anomalyco/opencode#24730.)
-5. ``items`` may not be a tuple-style array (``items: [schemaA, schemaB]``
-   for positional element schemas).  Moonshot's schema engine requires a
-   single object schema applied to every array element.  Collapse tuple
-   ``items`` to the first element schema (or ``{}`` if the tuple is empty).
-   (Ported from anomalyco/opencode#24730.)
 
 The ``#/definitions/...`` → ``#/$defs/...`` rewrite for draft-07 refs is
 handled separately in ``tools/mcp_tool._normalize_mcp_input_schema`` so it
@@ -78,16 +66,6 @@ def _repair_schema(node: Any, is_schema: bool = True) -> Any:
             }
         elif key in _SCHEMA_LIST_KEYS and isinstance(value, list):
             repaired[key] = [_repair_schema(v, is_schema=True) for v in value]
-        elif key == "items" and isinstance(value, list):
-            # Rule 5: tuple-style ``items`` arrays (positional element
-            # schemas) are not accepted by Moonshot.  Collapse to the
-            # first element schema if present, else to ``{}``.  This
-            # matches opencode's behaviour for moonshotai / kimi models.
-            first = value[0] if value else {}
-            if isinstance(first, dict):
-                repaired[key] = _repair_schema(first, is_schema=True)
-            else:
-                repaired[key] = first
         elif key in _SCHEMA_NODE_KEYS:
             # items / not / additionalProperties: single nested schema.
             # additionalProperties can also be a bool — leave those alone.
@@ -152,15 +130,6 @@ def _repair_schema(node: Any, is_schema: bool = True) -> Any:
             else:
                 repaired.pop("enum")
 
-    # Rule 4: $ref nodes must not have sibling keywords.  Moonshot expands
-    # the reference before validation and then rejects the node if siblings
-    # like ``description`` / ``type`` / ``default`` appear alongside $ref.
-    # The referenced definition still carries its own description on the
-    # target node, which Moonshot accepts.
-    # (Ported from anomalyco/opencode#24730.)
-    if "$ref" in repaired:
-        return {"$ref": repaired["$ref"]}
-
     return repaired
 
 

apps/bootstrap-installer/.gitignore

@@ -0,0 +1,40 @@
+# Rust / Cargo
+/src-tauri/target/
+/src-tauri/Cargo.lock
+
+# Vite / build output
+/dist/
+/dist-ssr/
+*.local
+
+# TypeScript build info + tsc emit (we don't ship .js for the
+# vite.config.ts; Vite reads it directly via ts-node-style loader).
+*.tsbuildinfo
+vite.config.d.ts
+vite.config.js
+
+# Tauri generated artifacts (regenerated on each build)
+/src-tauri/gen/schemas/
+
+# Logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# Editor
+.vscode/*
+!.vscode/extensions.json
+.idea/
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?
+
+# Node
+node_modules/
+
+# Internal placeholder (re-create if needed)
+.tauri-note

apps/bootstrap-installer/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en" class="h-full">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Hermes Setup</title>
+  </head>
+  <body class="h-full antialiased">
+    <div id="root" class="h-full"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

apps/bootstrap-installer/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@hermes/bootstrap-installer",
+  "private": true,
+  "version": "0.0.1",
+  "description": "Hermes Setup — signed installer that drives scripts/install.ps1 with a polished native UI.",
+  "type": "module",
+  "scripts": {
+    "dev": "vite --host 127.0.0.1 --port 5175",
+    "build": "tsc -b && vite build",
+    "preview": "vite preview",
+    "tauri": "tauri",
+    "tauri:dev": "tauri dev",
+    "tauri:build": "tauri build",
+    "tauri:build:debug": "tauri build --debug"
+  },
+  "dependencies": {
+    "@nous-research/ui": "0.16.0",
+    "@tailwindcss/vite": "^4.2.1",
+    "@tailwindcss/typography": "^0.5.19",
+    "@tauri-apps/api": "^2.0.0",
+    "@tauri-apps/plugin-dialog": "^2.0.0",
+    "@tauri-apps/plugin-opener": "^2.0.0",
+    "@tauri-apps/plugin-process": "^2.0.0",
+    "@tauri-apps/plugin-shell": "^2.0.0",
+    "@vscode/codicons": "^0.0.45",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "katex": "^0.16.45",
+    "lucide-react": "^0.577.0",
+    "nanostores": "^1.3.0",
+    "radix-ui": "^1.4.3",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "tailwind-merge": "^3.5.0",
+    "tailwindcss": "^4.2.1",
+    "tw-shimmer": "^0.4.11"
+  },
+  "devDependencies": {
+    "@tauri-apps/cli": "^2.0.0",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.2.0",
+    "typescript": "~5.9.3",
+    "vite": "^7.3.1"
+  }
+}

apps/bootstrap-installer/src-tauri/Cargo.toml

@@ -0,0 +1,75 @@
+[package]
+name = "hermes-bootstrap"
+version = "0.0.1"
+description = "Hermes Setup — signed installer that drives scripts/install.ps1"
+authors = ["Nous Research <info@nousresearch.com>"]
+edition = "2021"
+rust-version = "1.77"
+
+# Rename the output binary so the distributed artifact is literally
+# `Hermes-Setup.exe` on disk — not `hermes-bootstrap.exe`. Grandma sees
+# what we hand her, period. Tauri honors [[bin]] over [package].name
+# for the produced executable name.
+[[bin]]
+name = "Hermes-Setup"
+path = "src/main.rs"
+
+# The library target name MUST match the `withGlobalTauri` binding name that
+# tauri.conf.json's `app.windows[].label` references. We don't ship a separate
+# lib for now; everything is in src/.
+[lib]
+name = "hermes_bootstrap_lib"
+crate-type = ["staticlib", "cdylib", "rlib"]
+
+[build-dependencies]
+tauri-build = { version = "2", features = [] }
+
+[dependencies]
+# Tauri runtime + plugins
+tauri = { version = "2", features = [] }
+tauri-plugin-dialog = "2"
+tauri-plugin-opener = "2"
+tauri-plugin-process = "2"
+tauri-plugin-shell = "2"
+
+# Async + IO
+tokio = { version = "1", features = ["full"] }
+futures = "0.3"
+
+# Serialization
+serde = { version = "1", features = ["derive"] }
+serde_json = "1"
+
+# HTTP — rustls so we don't need OpenSSL on the build box
+reqwest = { version = "0.12", default-features = false, features = ["rustls-tls", "stream"] }
+
+# Logging — emitted to a file under HERMES_HOME/logs/ and (optionally) the
+# webview console via Tauri's event channel.
+tracing = "0.1"
+tracing-subscriber = { version = "0.3", features = ["env-filter", "fmt"] }
+tracing-appender = "0.2"
+
+# Paths + utils
+dirs = "5"
+which = "6"
+anyhow = "1"
+thiserror = "1"
+once_cell = "1"
+uuid = { version = "1", features = ["v4"] }
+
+# Process control on Windows (CREATE_NO_WINDOW etc.)
+[target.'cfg(windows)'.dependencies]
+windows-sys = { version = "0.59", features = [
+    "Win32_Foundation",
+    "Win32_System_Threading",
+    "Win32_System_Console",
+    "Win32_UI_WindowsAndMessaging",
+] }
+
+[profile.release]
+# A 5-10MB signed installer is the goal. LTO + size-opt + single codegen unit.
+panic = "abort"
+codegen-units = 1
+lto = true
+opt-level = "s"
+strip = true

apps/bootstrap-installer/src-tauri/build.rs

@@ -0,0 +1,150 @@
+use std::process::Command;
+
+fn main() {
+    // -----------------------------------------------------------------
+    // Bake the install.ps1 pin into the binary at compile time.
+    //
+    // BUILD_PIN_COMMIT and BUILD_PIN_BRANCH are read by bootstrap.rs's
+    // `option_env!()` macro to default the install-script reference.
+    // Precedence (matches install.ps1's own arg precedence): commit > branch.
+    //
+    // Resolution order:
+    //   1. Env var override at build time (HERMES_BUILD_PIN_COMMIT, etc.).
+    //      Useful for CI builds that want to pin to a tagged release SHA
+    //      rather than whatever the checkout's HEAD happens to be.
+    //   2. `git rev-parse HEAD` + `git rev-parse --abbrev-ref HEAD` against
+    //      the repo this build.rs lives in. Default for `cargo tauri build`
+    //      from a dev machine — pins the produced .exe to your current
+    //      checkout state.
+    //   3. Last-resort fallback: hardcoded `main` branch, no commit. The
+    //      installer will fetch HEAD-of-main at runtime. Used when the
+    //      build is happening outside a git checkout (e.g. cargo install
+    //      from a packaged crate, unlikely for this binary but defensive).
+    //
+    // Build script reruns on git HEAD change so a new commit triggers
+    // a rebuild without `cargo clean`.
+    // -----------------------------------------------------------------
+
+    let commit = resolve_commit_pin();
+    let branch = resolve_branch_pin();
+
+    if let Some(c) = &commit {
+        println!("cargo:rustc-env=BUILD_PIN_COMMIT={c}");
+        println!("cargo:warning=hermes-bootstrap: pinning to commit {}", short(c));
+    }
+    if let Some(b) = &branch {
+        println!("cargo:rustc-env=BUILD_PIN_BRANCH={b}");
+        println!("cargo:warning=hermes-bootstrap: pinning to branch {b}");
+    }
+    if commit.is_none() && branch.is_none() {
+        // Fail loudly rather than silently produce a binary that errors
+        // at runtime with "no install-script pin supplied". A build that
+        // can't resolve a pin almost certainly indicates a misconfigured
+        // build environment.
+        println!(
+            "cargo:warning=hermes-bootstrap: no pin resolved at build time; binary will fail at runtime without HERMES_SETUP_DEV_REPO_ROOT or runtime args"
+        );
+    }
+
+    // Rerun build.rs when HEAD moves so successive builds pick up new
+    // commits without needing `cargo clean`. .git/HEAD changes on every
+    // commit / branch switch / rebase.
+    let git_dir = locate_git_dir();
+    if let Some(gd) = &git_dir {
+        println!("cargo:rerun-if-changed={}/HEAD", gd.display());
+        // .git/HEAD often points at a ref (e.g. `ref: refs/heads/bb/gui`);
+        // also watch the ref itself so a new commit on the same branch
+        // re-triggers.
+        if let Ok(head) = std::fs::read_to_string(gd.join("HEAD")) {
+            if let Some(rest) = head.trim().strip_prefix("ref: ") {
+                println!("cargo:rerun-if-changed={}/{}", gd.display(), rest);
+            }
+        }
+    }
+    println!("cargo:rerun-if-env-changed=HERMES_BUILD_PIN_COMMIT");
+    println!("cargo:rerun-if-env-changed=HERMES_BUILD_PIN_BRANCH");
+
+    // -----------------------------------------------------------------
+    // Tauri windows manifest. See hermes-setup.manifest for rationale —
+    // declares level="asInvoker" so Windows's installer-detection
+    // heuristic doesn't refuse to launch us without UAC elevation.
+    // -----------------------------------------------------------------
+    #[cfg(target_os = "windows")]
+    let attrs = {
+        let manifest = include_str!("hermes-setup.manifest");
+        let win = tauri_build::WindowsAttributes::new().app_manifest(manifest);
+        tauri_build::Attributes::new().windows_attributes(win)
+    };
+
+    #[cfg(not(target_os = "windows"))]
+    let attrs = tauri_build::Attributes::new();
+
+    tauri_build::try_build(attrs).expect("failed to run tauri-build");
+}
+
+fn resolve_commit_pin() -> Option<String> {
+    if let Ok(v) = std::env::var("HERMES_BUILD_PIN_COMMIT") {
+        if !v.trim().is_empty() {
+            return Some(v.trim().to_string());
+        }
+    }
+    let out = Command::new("git")
+        .args(["rev-parse", "HEAD"])
+        .output()
+        .ok()?;
+    if !out.status.success() {
+        return None;
+    }
+    let s = String::from_utf8(out.stdout).ok()?.trim().to_string();
+    if s.is_empty() {
+        None
+    } else {
+        Some(s)
+    }
+}
+
+fn resolve_branch_pin() -> Option<String> {
+    if let Ok(v) = std::env::var("HERMES_BUILD_PIN_BRANCH") {
+        if !v.trim().is_empty() {
+            return Some(v.trim().to_string());
+        }
+    }
+    let out = Command::new("git")
+        .args(["rev-parse", "--abbrev-ref", "HEAD"])
+        .output()
+        .ok()?;
+    if !out.status.success() {
+        return None;
+    }
+    let s = String::from_utf8(out.stdout).ok()?.trim().to_string();
+    // "HEAD" is what you get on a detached checkout — no meaningful branch
+    // to pin to. The commit pin still applies; just don't emit a branch.
+    if s.is_empty() || s == "HEAD" {
+        None
+    } else {
+        Some(s)
+    }
+}
+
+fn locate_git_dir() -> Option<std::path::PathBuf> {
+    let out = Command::new("git")
+        .args(["rev-parse", "--git-dir"])
+        .output()
+        .ok()?;
+    if !out.status.success() {
+        return None;
+    }
+    let s = String::from_utf8(out.stdout).ok()?.trim().to_string();
+    if s.is_empty() {
+        return None;
+    }
+    Some(std::path::PathBuf::from(s))
+}
+
+fn short(commit: &str) -> &str {
+    if commit.len() >= 12 {
+        &commit[..12]
+    } else {
+        commit
+    }
+}

apps/bootstrap-installer/src-tauri/capabilities/default.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://schema.tauri.app/config/2/capability",
+  "identifier": "default",
+  "description": "Capabilities required by Hermes Setup. Narrowly scoped: we don't write user files outside HERMES_HOME, we don't read arbitrary paths, and the only external network call goes through reqwest (Rust side, not exposed to the webview).",
+  "windows": ["main"],
+  "permissions": [
+    "core:default",
+    "core:window:allow-close",
+    "core:window:allow-minimize",
+    "core:event:default",
+    "opener:default",
+    "dialog:default",
+    "process:default",
+    "shell:default"
+  ]
+}

apps/bootstrap-installer/src-tauri/hermes-setup.manifest

@@ -0,0 +1,75 @@
+<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
+<!--
+    Hermes Setup application manifest.
+
+    The TL;DR: tell Windows we are NOT an installer in the classic "needs
+    UAC elevation" sense, despite the product name. We provision into
+    %LOCALAPPDATA%\hermes which is user-scoped and never touch HKLM or
+    Program Files. install.ps1 runs as a child process and elevates
+    itself only if a future stage explicitly needs HKLM access.
+
+    Without this manifest, the "Hermes Setup" productName embedded in
+    the binary's resource trips Windows's installer-detection heuristic
+    (https://learn.microsoft.com/en-us/windows/security/identity-protection/
+    user-account-control/how-user-account-control-works#installer-detection)
+    and CreateProcess fails with ERROR_ELEVATION_REQUIRED (740) when the
+    user double-clicks. asInvoker disables that.
+-->
+<assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0">
+    <assemblyIdentity
+        version="0.0.1.0"
+        processorArchitecture="*"
+        name="NousResearch.Hermes.Setup"
+        type="win32"
+    />
+    <description>Hermes Setup</description>
+
+    <trustInfo xmlns="urn:schemas-microsoft-com:asm.v3">
+        <security>
+            <requestedPrivileges>
+                <requestedExecutionLevel level="asInvoker" uiAccess="false"/>
+            </requestedPrivileges>
+        </security>
+    </trustInfo>
+
+    <!-- Tell Windows we know about all supported OSes (10 + 11) so it
+         doesn't shim us into Vista-compat mode. -->
+    <compatibility xmlns="urn:schemas-microsoft-com:compatibility.v1">
+        <application>
+            <!-- Windows 10 / 11 -->
+            <supportedOS Id="{8e0f7a12-bfb3-4fe8-b9a5-48fd50a15a9a}"/>
+            <!-- Windows 8.1 -->
+            <supportedOS Id="{1f676c76-80e1-4239-95bb-83d0f6d0da78}"/>
+            <!-- Windows 8 -->
+            <supportedOS Id="{4a2f28e3-53b9-4441-ba9c-d69d4a4a6e38}"/>
+            <!-- Windows 7 -->
+            <supportedOS Id="{35138b9a-5d96-4fbd-8e2d-a2440225f93a}"/>
+            <!-- Windows Vista -->
+            <supportedOS Id="{e2011457-1546-43c5-a5fe-008deee3d3f0}"/>
+        </application>
+    </compatibility>
+
+    <!-- Per-monitor v2 DPI awareness so the installer doesn't go blurry
+         on high-DPI displays when dragged between monitors. -->
+    <application xmlns="urn:schemas-microsoft-com:asm.v3">
+        <windowsSettings>
+            <dpiAwareness xmlns="http://schemas.microsoft.com/SMI/2016/WindowsSettings">PerMonitorV2</dpiAwareness>
+            <activeCodePage xmlns="http://schemas.microsoft.com/SMI/2019/WindowsSettings">UTF-8</activeCodePage>
+        </windowsSettings>
+    </application>
+
+    <!-- Use the modern common controls (v6 themes). Without this, our
+         file picker / shell dialogs fall back to 1990s-era visuals. -->
+    <dependency>
+        <dependentAssembly>
+            <assemblyIdentity
+                type="win32"
+                name="Microsoft.Windows.Common-Controls"
+                version="6.0.0.0"
+                processorArchitecture="*"
+                publicKeyToken="6595b64144ccf1df"
+                language="*"
+            />
+        </dependentAssembly>
+    </dependency>
+</assembly>

apps/bootstrap-installer/src-tauri/src/bootstrap.rs

@@ -0,0 +1,712 @@
+//! Bootstrap orchestration.
+//!
+//! Direct port of `runBootstrap` from `apps/desktop/electron/bootstrap-runner.cjs`.
+//! Drives install.ps1 / install.sh stage-by-stage, emits progress events
+//! over the Tauri `bootstrap` channel, writes a forensic log to
+//! HERMES_HOME/logs/bootstrap-<timestamp>.log.
+//!
+//! Lifecycle:
+//!   1. `start_bootstrap` (Tauri command) → spawns the worker task.
+//!   2. Worker resolves install script (dev/cache/download).
+//!   3. Worker calls `install.ps1 -Manifest` → emits `manifest` event.
+//!   4. Worker iterates stages, calling `install.ps1 -Stage NAME -NonInteractive -Json`.
+//!   5. On success → `complete`. On any stage failure → `failed`. On cancel → `failed`.
+
+use std::path::PathBuf;
+use std::sync::Arc;
+use std::time::Instant;
+
+use anyhow::{anyhow, Result};
+use serde::{Deserialize, Serialize};
+use tauri::{AppHandle, Emitter, State};
+use tokio::sync::{mpsc, Mutex};
+
+use crate::events::{BootstrapEvent, Manifest, StageState};
+use crate::install_script::{self, Pin, ScriptKind, ScriptSource};
+use crate::powershell::{self, StreamSink};
+use crate::AppState;
+
+// ---------------------------------------------------------------------------
+// Public Tauri commands
+// ---------------------------------------------------------------------------
+
+/// Frontend → Rust: kick off the install.
+#[derive(Debug, Deserialize)]
+pub struct StartBootstrapArgs {
+    /// Optional override for the commit pin. Defaults to the build-time
+    /// pin baked in via `BUILD_PIN_COMMIT`.
+    pub commit: Option<String>,
+    /// Optional override for the branch pin. Defaults to `BUILD_PIN_BRANCH`.
+    pub branch: Option<String>,
+    /// Include Stage-Desktop (build apps/desktop) in the manifest. The
+    /// signed bootstrap installer passes true; the deprecated Electron-side
+    /// bootstrap-runner passes false to avoid building-while-running.
+    #[serde(default = "default_true")]
+    pub include_desktop: bool,
+    /// Optional override for HERMES_HOME. Tests use this; production
+    /// almost always falls back to the OS default.
+    pub hermes_home: Option<String>,
+}
+
+fn default_true() -> bool {
+    true
+}
+
+#[derive(Debug, Serialize)]
+pub struct BootstrapStatus {
+    pub running: bool,
+    pub completed: bool,
+    pub install_root: Option<String>,
+    pub last_error: Option<String>,
+}
+
+/// Handle stored in AppState while a bootstrap run is in flight. Carries
+/// the cancellation channel and the most recent terminal status so the
+/// frontend can re-query after a window refresh.
+pub struct BootstrapHandle {
+    pub cancel_tx: mpsc::Sender<()>,
+    pub started_at: Instant,
+    pub status: BootstrapStatus,
+}
+
+#[tauri::command]
+pub async fn start_bootstrap(
+    app: AppHandle,
+    state: State<'_, Arc<AppState>>,
+    args: StartBootstrapArgs,
+) -> Result<(), String> {
+    let mut guard = state.bootstrap.lock().await;
+    if let Some(h) = guard.as_ref() {
+        if h.status.running {
+            return Err("Bootstrap is already running".into());
+        }
+    }
+
+    let (cancel_tx, cancel_rx) = mpsc::channel::<()>(1);
+    let handle = BootstrapHandle {
+        cancel_tx,
+        started_at: Instant::now(),
+        status: BootstrapStatus {
+            running: true,
+            completed: false,
+            install_root: None,
+            last_error: None,
+        },
+    };
+    *guard = Some(handle);
+    drop(guard);
+
+    let app_for_task = app.clone();
+    let state_for_task = state.inner().clone();
+    let args_for_task = args;
+    let cancel_rx = Arc::new(Mutex::new(Some(cancel_rx)));
+
+    tokio::spawn(async move {
+        let result = run_bootstrap(app_for_task.clone(), args_for_task, cancel_rx).await;
+
+        // Reflect terminal state into AppState so get_bootstrap_status()
+        // can serve it after the task exits.
+        let mut guard = state_for_task.bootstrap.lock().await;
+        if let Some(h) = guard.as_mut() {
+            h.status.running = false;
+            match &result {
+                Ok(install_root) => {
+                    h.status.completed = true;
+                    h.status.install_root = Some(install_root.clone());
+                    h.status.last_error = None;
+                }
+                Err(err) => {
+                    h.status.completed = false;
+                    h.status.last_error = Some(err.to_string());
+                }
+            }
+        }
+    });
+
+    Ok(())
+}
+
+#[tauri::command]
+pub async fn cancel_bootstrap(state: State<'_, Arc<AppState>>) -> Result<(), String> {
+    let guard = state.bootstrap.lock().await;
+    if let Some(h) = guard.as_ref() {
+        let _ = h.cancel_tx.try_send(());
+    }
+    Ok(())
+}
+
+#[tauri::command]
+pub async fn get_bootstrap_status(
+    state: State<'_, Arc<AppState>>,
+) -> Result<BootstrapStatus, String> {
+    let guard = state.bootstrap.lock().await;
+    Ok(match guard.as_ref() {
+        Some(h) => BootstrapStatus {
+            running: h.status.running,
+            completed: h.status.completed,
+            install_root: h.status.install_root.clone(),
+            last_error: h.status.last_error.clone(),
+        },
+        None => BootstrapStatus {
+            running: false,
+            completed: false,
+            install_root: None,
+            last_error: None,
+        },
+    })
+}
+
+/// Spawn the locally-built Hermes desktop binary, then close the installer
+/// window. Caller resolves the binary path from `install_root`.
+///
+/// Returns Err with a human-readable message if the binary doesn't exist
+/// (e.g. when Stage-Desktop was skipped) so the frontend can present
+/// actionable failure UI rather than silently doing nothing.
+#[tauri::command]
+pub async fn launch_hermes_desktop(
+    app: AppHandle,
+    install_root: String,
+) -> Result<(), String> {
+    let install_root = PathBuf::from(install_root);
+    let exe_path = resolve_hermes_desktop_exe(&install_root).ok_or_else(|| {
+        format!(
+            "Couldn't find a built Hermes desktop at {}. The desktop build step \
+             may have been skipped or failed. Run `hermes desktop` from a \
+             terminal to build and launch it.",
+            install_root.join("apps").join("desktop").join("release").display()
+        )
+    })?;
+
+    tracing::info!(?exe_path, "launching Hermes desktop");
+
+    // Detach from us — the installer is about to exit.
+    let mut cmd = tokio::process::Command::new(&exe_path);
+    cmd.current_dir(exe_path.parent().unwrap_or(&install_root));
+    #[cfg(target_os = "windows")]
+    {
+        use std::os::windows::process::CommandExt;
+        // DETACHED_PROCESS = 0x00000008
+        cmd.creation_flags(0x0000_0008);
+    }
+
+    cmd.spawn().map_err(|e| {
+        format!(
+            "failed to launch {}: {e}",
+            exe_path.display()
+        )
+    })?;
+
+    // Give Windows ~150ms to actually start the new process before we exit.
+    tokio::time::sleep(std::time::Duration::from_millis(150)).await;
+
+    // Exit the installer cleanly. Tauri's process plugin gives us the
+    // right hook regardless of platform.
+    app.exit(0);
+    Ok(())
+}
+
+/// Walks the well-known electron-builder unpacked-app paths under
+/// `install_root`. Mirrors the resolver in `cmd_gui` (apps/desktop/release/
+/// <os>-unpacked/<exe>).
+fn resolve_hermes_desktop_exe(install_root: &std::path::Path) -> Option<PathBuf> {
+    let release_dir = install_root.join("apps").join("desktop").join("release");
+    let candidates: &[(&str, &str)] = if cfg!(target_os = "windows") {
+        &[
+            ("win-unpacked", "Hermes.exe"),
+            ("win-arm64-unpacked", "Hermes.exe"),
+        ]
+    } else if cfg!(target_os = "macos") {
+        &[
+            ("mac/Hermes.app/Contents/MacOS", "Hermes"),
+            ("mac-arm64/Hermes.app/Contents/MacOS", "Hermes"),
+        ]
+    } else {
+        &[("linux-unpacked", "hermes")]
+    };
+    for (subdir, exe) in candidates {
+        let p = release_dir.join(subdir).join(exe);
+        if p.exists() {
+            return Some(p);
+        }
+    }
+    None
+}
+
+// ---------------------------------------------------------------------------
+// Bootstrap implementation
+// ---------------------------------------------------------------------------
+
+async fn run_bootstrap(
+    app: AppHandle,
+    args: StartBootstrapArgs,
+    cancel_rx_holder: Arc<Mutex<Option<mpsc::Receiver<()>>>>,
+) -> Result<String> {
+    let kind = ScriptKind::for_current_os();
+
+    let pin = Pin {
+        commit: args.commit.or_else(|| option_env_string("BUILD_PIN_COMMIT")),
+        branch: args.branch.or_else(|| option_env_string("BUILD_PIN_BRANCH")),
+    };
+
+    tracing::info!(
+        ?pin,
+        kind = ?kind,
+        include_desktop = args.include_desktop,
+        "bootstrap starting"
+    );
+
+    let app_for_log = app.clone();
+    let emit_log = move |line: &str| {
+        emit_event(
+            &app_for_log,
+            BootstrapEvent::Log {
+                stage: None,
+                line: line.to_string(),
+            },
+        );
+        // Bump to info-level so the line shows in bootstrap-installer.log
+        // under the default INFO filter. Previously this was debug! which
+        // got dropped on the floor, leaving us blind whenever install.ps1
+        // failed — the log only had the "bootstrap starting" banner.
+        tracing::info!(target: "bootstrap.log", "{line}");
+    };
+
+    // 1. Resolve install.ps1
+    let script = install_script::resolve(kind, &pin, &emit_log)
+        .await
+        .map_err(|e| {
+            let msg = format!("resolve install script failed: {e:#}");
+            emit_event(
+                &app,
+                BootstrapEvent::Failed {
+                    stage: None,
+                    error: msg.clone(),
+                },
+            );
+            anyhow!(msg)
+        })?;
+
+    let source_note = match &script.source {
+        ScriptSource::DevCheckout => "dev checkout",
+        ScriptSource::Bundled => "bundled",
+        ScriptSource::Cached => "cached",
+        ScriptSource::Downloaded => "downloaded",
+    };
+    emit_log(&format!(
+        "[bootstrap] script {} via {}",
+        script.path.display(),
+        source_note
+    ));
+
+    // 2. Fetch manifest
+    //
+    // -IncludeDesktop MUST be passed to the manifest call too — install.ps1
+    // gates the desktop stage inclusion on this flag, so without it here
+    // the manifest comes back missing the desktop stage and we never run
+    // it. The per-stage call below also passes -IncludeDesktop to keep
+    // the contracts identical.
+    let manifest_args = build_pin_args(&script);
+    let mut manifest_args_full = vec!["-Manifest".to_string()];
+    manifest_args_full.extend(manifest_args.clone());
+    if args.include_desktop {
+        manifest_args_full.push("-IncludeDesktop".to_string());
+    }
+
+    let manifest_result = run_install_script(
+        &app,
+        &script.path,
+        &manifest_args_full,
+        args.hermes_home.as_deref(),
+        None,
+        Some("__manifest__".to_string()),
+    )
+    .await?;
+
+    if manifest_result.exit_code != Some(0) {
+        let err = format!(
+            "install.ps1 -Manifest failed: exit {:?}\n{}",
+            manifest_result.exit_code,
+            manifest_result.stderr.trim()
+        );
+        emit_event(
+            &app,
+            BootstrapEvent::Failed {
+                stage: None,
+                error: err.clone(),
+            },
+        );
+        return Err(anyhow!(err));
+    }
+
+    let manifest: Manifest = powershell::parse_manifest(&manifest_result.stdout).ok_or_else(|| {
+        let err = format!(
+            "install.ps1 -Manifest produced no parseable JSON payload\n{}",
+            truncate(&manifest_result.stdout, 4000)
+        );
+        emit_event(
+            &app,
+            BootstrapEvent::Failed {
+                stage: None,
+                error: err.clone(),
+            },
+        );
+        anyhow!(err)
+    })?;
+
+    emit_event(
+        &app,
+        BootstrapEvent::Manifest {
+            stages: manifest.stages.clone(),
+            protocol_version: manifest.protocol_version,
+        },
+    );
+
+    // 3. Iterate stages.
+    for stage in &manifest.stages {
+        // Skip Stage-Desktop unless explicitly requested. install.ps1 may
+        // or may not include it in the manifest depending on the flag we
+        // pass, but if it slipped in, gate client-side too.
+        if !args.include_desktop && stage.name.eq_ignore_ascii_case("desktop") {
+            emit_event(
+                &app,
+                BootstrapEvent::Stage {
+                    name: stage.name.clone(),
+                    state: StageState::Skipped,
+                    duration_ms: Some(0),
+                    result: None,
+                    error: Some("skipped by include_desktop=false".into()),
+                },
+            );
+            continue;
+        }
+
+        if cancellation_signalled(&cancel_rx_holder).await {
+            let err = "bootstrap cancelled by user".to_string();
+            emit_event(
+                &app,
+                BootstrapEvent::Failed {
+                    stage: Some(stage.name.clone()),
+                    error: err.clone(),
+                },
+            );
+            return Err(anyhow!(err));
+        }
+
+        let started = Instant::now();
+        emit_event(
+            &app,
+            BootstrapEvent::Stage {
+                name: stage.name.clone(),
+                state: StageState::Running,
+                duration_ms: None,
+                result: None,
+                error: None,
+            },
+        );
+
+        let mut stage_args = vec![
+            "-Stage".to_string(),
+            stage.name.clone(),
+            "-NonInteractive".to_string(),
+            "-Json".to_string(),
+        ];
+        stage_args.extend(manifest_args.clone());
+        if args.include_desktop {
+            stage_args.push("-IncludeDesktop".to_string());
+        }
+
+        // Each stage gets its own cancel receiver because tokio::select!
+        // in run_script consumes it. Take/return through the Arc<Mutex>.
+        let local_cancel_rx = cancel_rx_holder.lock().await.take();
+
+        let stage_result = run_install_script(
+            &app,
+            &script.path,
+            &stage_args,
+            args.hermes_home.as_deref(),
+            local_cancel_rx,
+            Some(stage.name.clone()),
+        )
+        .await?;
+
+        let duration_ms = started.elapsed().as_millis() as u64;
+
+        if stage_result.killed {
+            emit_event(
+                &app,
+                BootstrapEvent::Stage {
+                    name: stage.name.clone(),
+                    state: StageState::Failed,
+                    duration_ms: Some(duration_ms),
+                    result: None,
+                    error: Some("cancelled by user".into()),
+                },
+            );
+            emit_event(
+                &app,
+                BootstrapEvent::Failed {
+                    stage: Some(stage.name.clone()),
+                    error: "cancelled by user".into(),
+                },
+            );
+            return Err(anyhow!("cancelled by user"));
+        }
+
+        let result_frame = powershell::parse_stage_result(&stage_result.stdout);
+
+        match result_frame {
+            None => {
+                let err = format!(
+                    "install.ps1 -Stage {} produced no JSON result frame (exit={:?})",
+                    stage.name, stage_result.exit_code
+                );
+                emit_event(
+                    &app,
+                    BootstrapEvent::Stage {
+                        name: stage.name.clone(),
+                        state: StageState::Failed,
+                        duration_ms: Some(duration_ms),
+                        result: None,
+                        error: Some(err.clone()),
+                    },
+                );
+                emit_event(
+                    &app,
+                    BootstrapEvent::Failed {
+                        stage: Some(stage.name.clone()),
+                        error: err.clone(),
+                    },
+                );
+                return Err(anyhow!(err));
+            }
+            Some(frame) if frame.ok && frame.skipped => {
+                emit_event(
+                    &app,
+                    BootstrapEvent::Stage {
+                        name: stage.name.clone(),
+                        state: StageState::Skipped,
+                        duration_ms: Some(duration_ms),
+                        result: Some(frame),
+                        error: None,
+                    },
+                );
+            }
+            Some(frame) if frame.ok => {
+                emit_event(
+                    &app,
+                    BootstrapEvent::Stage {
+                        name: stage.name.clone(),
+                        state: StageState::Succeeded,
+                        duration_ms: Some(duration_ms),
+                        result: Some(frame),
+                        error: None,
+                    },
+                );
+            }
+            Some(frame) => {
+                let err = frame
+                    .reason
+                    .clone()
+                    .unwrap_or_else(|| format!("exit code {:?}", stage_result.exit_code));
+                emit_event(
+                    &app,
+                    BootstrapEvent::Stage {
+                        name: stage.name.clone(),
+                        state: StageState::Failed,
+                        duration_ms: Some(duration_ms),
+                        result: Some(frame),
+                        error: Some(err.clone()),
+                    },
+                );
+                emit_event(
+                    &app,
+                    BootstrapEvent::Failed {
+                        stage: Some(stage.name.clone()),
+                        error: err.clone(),
+                    },
+                );
+                return Err(anyhow!(err));
+            }
+        }
+    }
+
+    // 4. Resolve install_root. install.ps1 doesn't (yet) report this back
+    // explicitly; we infer it from $HermesHome which Stage-Repository clones
+    // the repo INTO at $HermesHome\hermes-agent. Mirrors hermes_constants.
+    let hermes_home = args
+        .hermes_home
+        .clone()
+        .unwrap_or_else(|| crate::paths::hermes_home().to_string_lossy().into_owned());
+    let install_root = PathBuf::from(&hermes_home).join("hermes-agent");
+
+    // Copy ourselves to HERMES_HOME/hermes-setup.exe so the desktop app can
+    // re-invoke us with `--update` and shortcuts have a stable target. This is
+    // a one-shot install concern; an `--update` re-invocation no-ops because
+    // we're already running from that path. Best-effort — a failure here must
+    // not fail an otherwise-successful install.
+    if let Err(err) = crate::paths::copy_self_to_hermes_home() {
+        tracing::warn!(?err, "failed to copy installer into HERMES_HOME (non-fatal)");
+        emit_log(&format!(
+            "[bootstrap] warning: could not stage updater binary: {err}"
+        ));
+    }
+
+    emit_event(
+        &app,
+        BootstrapEvent::Complete {
+            install_root: install_root.to_string_lossy().into_owned(),
+            marker: Some(serde_json::json!({
+                "pinnedCommit": pin.commit,
+                "pinnedBranch": pin.branch,
+            })),
+        },
+    );
+
+    Ok(install_root.to_string_lossy().into_owned())
+}
+
+async fn cancellation_signalled(holder: &Arc<Mutex<Option<mpsc::Receiver<()>>>>) -> bool {
+    let mut guard = holder.lock().await;
+    if let Some(rx) = guard.as_mut() {
+        rx.try_recv().is_ok()
+    } else {
+        false
+    }
+}
+
+async fn run_install_script(
+    app: &AppHandle,
+    script_path: &std::path::Path,
+    args: &[String],
+    hermes_home_override: Option<&str>,
+    cancel_rx: Option<mpsc::Receiver<()>>,
+    stage_name: Option<String>,
+) -> Result<powershell::ScriptResult> {
+    let app_for_stdout = app.clone();
+    let stage_for_stdout = stage_name.clone();
+    let app_for_stderr = app.clone();
+    let stage_for_stderr = stage_name.clone();
+    let stage_for_stdout_log = stage_name.clone();
+    let stage_for_stderr_log = stage_name.clone();
+
+    let sink = StreamSink {
+        on_stdout_line: Box::new(move |line: &str| {
+            emit_event(
+                &app_for_stdout,
+                BootstrapEvent::Log {
+                    stage: stage_for_stdout.clone(),
+                    line: line.to_string(),
+                },
+            );
+            // Tee to the rolling installer log so we have a persistent
+            // record of every install.ps1 line. Without this, the only
+            // log evidence of a failure was the Tauri event stream —
+            // which gets discarded the moment the failure route mounts.
+            match &stage_for_stdout_log {
+                Some(name) => {
+                    tracing::info!(target: "bootstrap.log", stage = %name, "{line}")
+                }
+                None => tracing::info!(target: "bootstrap.log", "{line}"),
+            }
+        }),
+        on_stderr_line: Box::new(move |line: &str| {
+            emit_event(
+                &app_for_stderr,
+                BootstrapEvent::Log {
+                    stage: stage_for_stderr.clone(),
+                    line: format!("stderr: {line}"),
+                },
+            );
+            // stderr-level lines get warn! so they're visually distinct
+            // when scrolling through the log later.
+            match &stage_for_stderr_log {
+                Some(name) => {
+                    tracing::warn!(target: "bootstrap.log", stage = %name, "stderr: {line}")
+                }
+                None => tracing::warn!(target: "bootstrap.log", "stderr: {line}"),
+            }
+        }),
+    };
+
+    powershell::run_script(script_path, args, sink, hermes_home_override, cancel_rx)
+        .await
+        .map_err(|e| {
+            tracing::error!(?e, "install script invocation failed");
+            anyhow!("install script invocation failed: {e:#}")
+        })
+}
+
+fn build_pin_args(script: &install_script::ResolvedScript) -> Vec<String> {
+    let mut out = Vec::new();
+    if let Some(c) = &script.commit {
+        out.push("-Commit".to_string());
+        out.push(c.clone());
+    }
+    if let Some(b) = &script.branch {
+        out.push("-Branch".to_string());
+        out.push(b.clone());
+    }
+    out
+}
+
+fn emit_event(app: &AppHandle, event: BootstrapEvent) {
+    // Tee important state transitions to the rolling installer log so
+    // bootstrap-installer.log isn't just "starting" + final summary.
+    // Log lines (the noisy stuff) handle their own tracing in
+    // run_install_script's sink; here we cover the lifecycle frames.
+    match &event {
+        BootstrapEvent::Manifest { stages, .. } => {
+            tracing::info!(
+                stage_count = stages.len(),
+                names = ?stages.iter().map(|s| s.name.as_str()).collect::<Vec<_>>(),
+                "manifest received"
+            );
+        }
+        BootstrapEvent::Stage {
+            name,
+            state,
+            duration_ms,
+            error,
+            ..
+        } => {
+            tracing::info!(
+                stage = %name,
+                ?state,
+                duration_ms = ?duration_ms,
+                error = ?error,
+                "stage transition"
+            );
+        }
+        BootstrapEvent::Complete { install_root, .. } => {
+            tracing::info!(install_root = %install_root, "bootstrap complete");
+        }
+        BootstrapEvent::Failed { stage, error } => {
+            tracing::error!(stage = ?stage, error = %error, "bootstrap FAILED");
+        }
+        BootstrapEvent::Log { .. } => {
+            // Log lines are teed via the sink callbacks in
+            // run_install_script — don't double-emit here.
+        }
+    }
+    if let Err(e) = app.emit(BootstrapEvent::CHANNEL, &event) {
+        tracing::warn!(?e, "failed to emit bootstrap event");
+    }
+}
+
+fn option_env_string(key: &str) -> Option<String> {
+    // option_env! only accepts literals, so we hardcode the known keys.
+    let val = match key {
+        "BUILD_PIN_COMMIT" => option_env!("BUILD_PIN_COMMIT"),
+        "BUILD_PIN_BRANCH" => option_env!("BUILD_PIN_BRANCH"),
+        _ => None,
+    };
+    val.map(|s| s.to_string())
+}
+
+fn truncate(s: &str, max: usize) -> String {
+    if s.len() <= max {
+        s.to_string()
+    } else {
+        format!("{}...", &s[..max])
+    }
+}

apps/bootstrap-installer/src-tauri/src/events.rs

@@ -0,0 +1,99 @@
+//! Event types streamed from Rust → React.
+//!
+//! These mirror `apps/desktop/electron/bootstrap-runner.cjs`'s event shape
+//! 1:1 so the React installer code can be roughly identical to the Electron
+//! install-overlay we'll replace.
+//!
+//! The Tauri event channel name is `"bootstrap"` for all of these — the
+//! `type` discriminator on each payload is how the frontend routes.
+
+use serde::{Deserialize, Serialize};
+
+/// Stage definition as reported by `install.ps1 -Manifest`.
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct StageInfo {
+    pub name: String,
+    pub title: String,
+    pub category: String,
+    /// `needs_user_input=true` stages run with -NonInteractive and emit
+    /// skipped=true; the post-install wizard takes over for those.
+    #[serde(rename = "needs_user_input", alias = "needsUserInput")]
+    pub needs_user_input: bool,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Manifest {
+    pub stages: Vec<StageInfo>,
+    #[serde(rename = "protocol_version", alias = "protocolVersion", default)]
+    pub protocol_version: Option<u32>,
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct StageResultPayload {
+    pub stage: String,
+    pub ok: bool,
+    #[serde(default)]
+    pub skipped: bool,
+    #[serde(default)]
+    pub reason: Option<String>,
+    /// install.ps1 may attach stage-specific structured data here.
+    #[serde(default)]
+    pub data: Option<serde_json::Value>,
+}
+
+/// Run-state for a single stage as we transition through it.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
+#[serde(rename_all = "lowercase")]
+pub enum StageState {
+    Running,
+    Succeeded,
+    Skipped,
+    Failed,
+}
+
+/// The single event channel `bootstrap` emits these. `type` discriminates.
+#[derive(Debug, Clone, Serialize)]
+#[serde(tag = "type", rename_all = "lowercase")]
+pub enum BootstrapEvent {
+    /// Sent once at the start with the full stage list.
+    Manifest {
+        stages: Vec<StageInfo>,
+        #[serde(rename = "protocolVersion")]
+        protocol_version: Option<u32>,
+    },
+    /// Stage state transition. `result` populated only on terminal states.
+    Stage {
+        name: String,
+        state: StageState,
+        #[serde(rename = "durationMs", skip_serializing_if = "Option::is_none")]
+        duration_ms: Option<u64>,
+        #[serde(skip_serializing_if = "Option::is_none")]
+        result: Option<StageResultPayload>,
+        #[serde(skip_serializing_if = "Option::is_none")]
+        error: Option<String>,
+    },
+    /// Raw stdout/stderr line from install.ps1 (or our wrapper).
+    Log {
+        #[serde(skip_serializing_if = "Option::is_none")]
+        stage: Option<String>,
+        line: String,
+    },
+    /// Sent once when all stages complete successfully.
+    Complete {
+        #[serde(rename = "installRoot")]
+        install_root: String,
+        marker: Option<serde_json::Value>,
+    },
+    /// Sent once if the run aborts.
+    Failed {
+        #[serde(skip_serializing_if = "Option::is_none")]
+        stage: Option<String>,
+        error: String,
+    },
+}
+
+impl BootstrapEvent {
+    /// Tauri event name. Single channel for all bootstrap events; the
+    /// `type` tag tells the renderer how to interpret the payload.
+    pub const CHANNEL: &'static str = "bootstrap";
+}

apps/bootstrap-installer/src-tauri/src/install_script.rs

@@ -0,0 +1,273 @@
+//! Resolves and downloads `scripts/install.ps1` (and `install.sh`).
+//!
+//! Resolution order:
+//!   1. Dev shortcut: a sibling repo checkout via $HERMES_SETUP_DEV_REPO_ROOT
+//!      env var. Lets devs iterate without re-publishing the script.
+//!   2. Bundled fallback: if the installer was bundled with a script (e.g.
+//!      tauri's `resource` mechanism), serve from there. Not used today.
+//!   3. Network: download from GitHub raw at a pinned commit or branch.
+//!      Commit pins are immutable; branch pins are HEAD-tracking.
+//!
+//! Mirrors `apps/desktop/electron/bootstrap-runner.cjs`'s `resolveInstallScript`,
+//! but the dev-checkout resolution is driven by an env var rather than the
+//! Electron app's APP_ROOT/../.. trick, because Hermes-Setup.exe is meant
+//! to live OUTSIDE any repo checkout.
+
+use anyhow::{anyhow, Context, Result};
+use std::path::{Path, PathBuf};
+use tokio::io::AsyncWriteExt;
+
+use crate::paths;
+
+/// Identity of the install.ps1 we'll execute. Used by both the manifest
+/// fetch and the per-stage runs.
+#[derive(Debug, Clone)]
+pub struct ResolvedScript {
+    pub path: PathBuf,
+    pub source: ScriptSource,
+    /// Commit pin (40-char SHA) if known. install.ps1's `-Commit` arg is
+    /// what makes the repo stage clone the exact tested SHA.
+    pub commit: Option<String>,
+    pub branch: Option<String>,
+}
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub enum ScriptSource {
+    DevCheckout,
+    Bundled,
+    Cached,
+    Downloaded,
+}
+
+/// What flavor of script (Windows .ps1 vs Unix .sh).
+#[derive(Debug, Clone, Copy)]
+pub enum ScriptKind {
+    Ps1,
+    Sh,
+}
+
+impl ScriptKind {
+    pub fn for_current_os() -> Self {
+        if cfg!(target_os = "windows") {
+            Self::Ps1
+        } else {
+            Self::Sh
+        }
+    }
+
+    fn filename(&self) -> &'static str {
+        match self {
+            Self::Ps1 => "install.ps1",
+            Self::Sh => "install.sh",
+        }
+    }
+}
+
+/// Validates a string looks like a git SHA (7+ hex chars). Mirrors
+/// `STAMP_COMMIT_RE` from bootstrap-runner.cjs.
+fn is_valid_commit(s: &str) -> bool {
+    let len = s.len();
+    (7..=40).contains(&len) && s.chars().all(|c| c.is_ascii_hexdigit())
+}
+
+/// Resolves the install script to use for this run.
+///
+/// `pin` is the commit-or-branch from either Hermes-Setup's build-time
+/// constant (compiled into the installer) or a runtime override.
+pub async fn resolve(
+    kind: ScriptKind,
+    pin: &Pin,
+    emit_log: &impl Fn(&str),
+) -> Result<ResolvedScript> {
+    // 1. Dev shortcut.
+    if let Ok(repo_root) = std::env::var("HERMES_SETUP_DEV_REPO_ROOT") {
+        let candidate = PathBuf::from(repo_root).join("scripts").join(kind.filename());
+        if candidate.exists() {
+            emit_log(&format!(
+                "[bootstrap] dev mode — using local {} at {}",
+                kind.filename(),
+                candidate.display()
+            ));
+            return Ok(ResolvedScript {
+                path: candidate,
+                source: ScriptSource::DevCheckout,
+                commit: pin.commit.clone(),
+                branch: pin.branch.clone(),
+            });
+        }
+    }
+
+    // 2. (Not implemented) bundled fallback.
+
+    // 3. Network. Pin must be a real commit or a branch ref.
+    let commit_or_ref = match (&pin.commit, &pin.branch) {
+        (Some(c), _) if is_valid_commit(c) => c.clone(),
+        (_, Some(b)) if !b.trim().is_empty() => b.clone(),
+        (Some(other), _) => {
+            return Err(anyhow!(
+                "install script pin commit `{other}` is not a valid git SHA"
+            ));
+        }
+        _ => {
+            return Err(anyhow!(
+                "no install-script pin supplied — installer cannot resolve a script source"
+            ));
+        }
+    };
+
+    let cached = cached_path(kind, &commit_or_ref);
+    if cached.exists() {
+        emit_log(&format!(
+            "[bootstrap] using cached {} for {}",
+            kind.filename(),
+            truncate_ref(&commit_or_ref)
+        ));
+        return Ok(ResolvedScript {
+            path: cached,
+            source: ScriptSource::Cached,
+            commit: pin.commit.clone(),
+            branch: pin.branch.clone(),
+        });
+    }
+
+    emit_log(&format!(
+        "[bootstrap] downloading {} for {} from GitHub",
+        kind.filename(),
+        truncate_ref(&commit_or_ref)
+    ));
+
+    download(kind, &commit_or_ref, &cached).await?;
+
+    emit_log(&format!("[bootstrap] cached to {}", cached.display()));
+
+    Ok(ResolvedScript {
+        path: cached,
+        source: ScriptSource::Downloaded,
+        commit: pin.commit.clone(),
+        branch: pin.branch.clone(),
+    })
+}
+
+#[derive(Debug, Clone, Default)]
+pub struct Pin {
+    pub commit: Option<String>,
+    pub branch: Option<String>,
+}
+
+fn cached_path(kind: ScriptKind, commit_or_ref: &str) -> PathBuf {
+    let safe = sanitize_ref(commit_or_ref);
+    let filename = match kind {
+        ScriptKind::Ps1 => format!("install-{safe}.ps1"),
+        ScriptKind::Sh => format!("install-{safe}.sh"),
+    };
+    paths::bootstrap_cache_dir().join(filename)
+}
+
+/// Replace anything that's not [A-Za-z0-9._-] with `_`. Branch refs can
+/// contain `/`, dots, etc.; we want a flat filename.
+fn sanitize_ref(s: &str) -> String {
+    s.chars()
+        .map(|c| {
+            if c.is_ascii_alphanumeric() || c == '.' || c == '-' || c == '_' {
+                c
+            } else {
+                '_'
+            }
+        })
+        .collect()
+}
+
+fn truncate_ref(s: &str) -> &str {
+    if is_valid_commit(s) && s.len() >= 12 {
+        &s[..12]
+    } else {
+        s
+    }
+}
+
+/// Downloads to `dest_path` via reqwest with rustls. Atomically renames
+/// `dest_path.tmp` → `dest_path` so partial writes don't poison the cache.
+async fn download(kind: ScriptKind, commit_or_ref: &str, dest_path: &Path) -> Result<()> {
+    let url = format!(
+        "https://raw.githubusercontent.com/NousResearch/hermes-agent/{}/scripts/{}",
+        commit_or_ref,
+        kind.filename()
+    );
+
+    if let Some(parent) = dest_path.parent() {
+        std::fs::create_dir_all(parent).with_context(|| {
+            format!("creating bootstrap-cache parent dir {}", parent.display())
+        })?;
+    }
+
+    let tmp_path = dest_path.with_extension({
+        let ext = dest_path
+            .extension()
+            .and_then(|s| s.to_str())
+            .unwrap_or("tmp");
+        format!("{ext}.tmp")
+    });
+
+    let response = reqwest::Client::new()
+        .get(&url)
+        .header("User-Agent", "hermes-setup/0.0.1")
+        .send()
+        .await
+        .with_context(|| format!("GET {url}"))?;
+
+    if !response.status().is_success() {
+        return Err(anyhow!(
+            "Failed to download {}: HTTP {} from {}",
+            kind.filename(),
+            response.status(),
+            url
+        ));
+    }
+
+    let bytes = response
+        .bytes()
+        .await
+        .with_context(|| format!("reading body of {url}"))?;
+
+    let mut file = tokio::fs::File::create(&tmp_path)
+        .await
+        .with_context(|| format!("creating temp file {}", tmp_path.display()))?;
+    file.write_all(&bytes)
+        .await
+        .with_context(|| format!("writing temp file {}", tmp_path.display()))?;
+    file.flush().await.context("flushing temp file")?;
+    drop(file);
+
+    tokio::fs::rename(&tmp_path, dest_path)
+        .await
+        .with_context(|| {
+            format!(
+                "renaming {} → {}",
+                tmp_path.display(),
+                dest_path.display()
+            )
+        })?;
+
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn is_valid_commit_accepts_short_and_full_shas() {
+        assert!(is_valid_commit("02d26981d3d4ad50e142399b8476f59ad5953ff0"));
+        assert!(is_valid_commit("02d2698"));
+        assert!(!is_valid_commit("02d269"));
+        assert!(!is_valid_commit("not-a-sha"));
+        assert!(!is_valid_commit(""));
+    }
+
+    #[test]
+    fn sanitize_ref_replaces_slashes() {
+        assert_eq!(sanitize_ref("bb/gui"), "bb_gui");
+        assert_eq!(sanitize_ref("main"), "main");
+        assert_eq!(sanitize_ref("release/1.2.3"), "release_1.2.3");
+    }
+}

apps/bootstrap-installer/src-tauri/src/lib.rs

@@ -0,0 +1,134 @@
+//! Hermes Setup — Tauri entrypoint.
+//!
+//! Spawns a single window pointed at the React frontend (apps/bootstrap-installer/src/).
+//! All install-time work lives in `bootstrap.rs` and is invoked through the Tauri
+//! commands registered at the bottom of `run()`.
+//!
+//! The Windows-subsystem strip lives on the binary crate (src/main.rs), not
+//! here — a crate-level attribute on a lib doesn't propagate to the linker
+//! flags of the executable that consumes it.
+
+mod bootstrap;
+mod events;
+mod install_script;
+mod powershell;
+mod paths;
+mod update;
+
+use std::sync::Arc;
+use tokio::sync::Mutex;
+
+/// How the installer was invoked. Resolved once from the process args in
+/// `run()` and exposed to the frontend via `get_mode` so it can route to the
+/// install flow (first-run onboarding) or the update flow (driven by the
+/// desktop app handing off via `Hermes-Setup.exe --update`).
+///
+/// Bare launch (double-click, first-run) => Install.
+/// `--update` (spawned by the desktop's "Update" button) => Update.
+#[derive(Debug, Clone, Copy, PartialEq, Eq, serde::Serialize)]
+#[serde(rename_all = "lowercase")]
+pub enum AppMode {
+    Install,
+    Update,
+}
+
+impl AppMode {
+    /// Resolve the mode from an argument iterator. Anything containing the
+    /// `--update` flag selects Update; otherwise Install. Kept arg-iterator
+    /// generic (not reading `std::env` directly) so it's unit-testable.
+    pub fn from_args<I, S>(args: I) -> Self
+    where
+        I: IntoIterator<Item = S>,
+        S: AsRef<str>,
+    {
+        for a in args {
+            if a.as_ref() == "--update" {
+                return AppMode::Update;
+            }
+        }
+        AppMode::Install
+    }
+}
+
+/// Process-wide install state, shared across Tauri commands.
+///
+/// The bootstrap is a one-shot, single-tenant process — we only need one
+/// of these per window. `Arc<Mutex<...>>` lets command handlers grab it
+/// without lifetime gymnastics.
+pub struct AppState {
+    pub bootstrap: Mutex<Option<bootstrap::BootstrapHandle>>,
+    /// How this process was launched (install vs update). Immutable for the
+    /// lifetime of the process; read by the `get_mode` command.
+    pub mode: AppMode,
+}
+
+impl AppState {
+    fn new(mode: AppMode) -> Self {
+        Self {
+            bootstrap: Mutex::new(None),
+            mode,
+        }
+    }
+}
+
+/// Frontend → Rust: which flow should the UI render?
+#[tauri::command]
+fn get_mode(state: tauri::State<'_, Arc<AppState>>) -> AppMode {
+    state.mode
+}
+
+#[cfg_attr(mobile, tauri::mobile_entry_point)]
+pub fn run() {
+    // Tracing → bootstrap-installer.log under HERMES_HOME/logs/ so install
+    // failures leave a trail for support. Console output also goes here in
+    // debug builds.
+    let _guard = paths::init_logging();
+
+    let mode = AppMode::from_args(std::env::args().skip(1));
+    tracing::info!(?mode, "Hermes Setup starting");
+
+    tauri::Builder::default()
+        .plugin(tauri_plugin_dialog::init())
+        .plugin(tauri_plugin_opener::init())
+        .plugin(tauri_plugin_process::init())
+        .plugin(tauri_plugin_shell::init())
+        .manage(Arc::new(AppState::new(mode)))
+        .invoke_handler(tauri::generate_handler![
+            // Mode (install vs update)
+            get_mode,
+            // Bootstrap lifecycle
+            bootstrap::start_bootstrap,
+            bootstrap::cancel_bootstrap,
+            bootstrap::get_bootstrap_status,
+            // Update lifecycle
+            update::start_update,
+            // Hand-off
+            bootstrap::launch_hermes_desktop,
+            // Diagnostics
+            paths::get_log_path,
+            paths::get_hermes_home,
+            paths::open_log_dir,
+        ])
+        .run(tauri::generate_context!())
+        .expect("error while running Hermes Setup");
+}
+
+#[cfg(test)]
+mod tests {
+    use super::AppMode;
+
+    #[test]
+    fn bare_args_are_install() {
+        assert_eq!(AppMode::from_args(Vec::<String>::new()), AppMode::Install);
+        assert_eq!(AppMode::from_args(["--foo", "bar"]), AppMode::Install);
+    }
+
+    #[test]
+    fn update_flag_selects_update() {
+        assert_eq!(AppMode::from_args(["--update"]), AppMode::Update);
+        assert_eq!(
+            AppMode::from_args(["--something", "--update", "--else"]),
+            AppMode::Update
+        );
+    }
+}

apps/bootstrap-installer/src-tauri/src/main.rs

@@ -0,0 +1,19 @@
+// Hermes Setup — process entrypoint. All logic lives in lib.rs so it can
+// be unit-tested as a library; this file just calls into it.
+//
+// The windows_subsystem attribute MUST live here on the binary crate
+// (not lib.rs) — placing it on the lib was the bug that left a stray
+// cmd window behind Hermes-Setup.exe on release builds.
+//
+// `windows_subsystem = "windows"` strips the console allocation that
+// the default `windows_subsystem = "console"` would do, so double-clicking
+// the .exe gives you ONLY the Tauri window.
+//
+// debug_assertions guard: dev builds keep the console so tracing output
+// is visible during `cargo tauri dev`.
+
+#![cfg_attr(not(debug_assertions), windows_subsystem = "windows")]
+
+fn main() {
+    hermes_bootstrap_lib::run()
+}

apps/bootstrap-installer/src-tauri/src/paths.rs

@@ -0,0 +1,168 @@
+//! Filesystem paths + logging setup.
+//!
+//! Mirrors `hermes_constants.get_hermes_home()` from the Python CLI:
+//!   Windows: %LOCALAPPDATA%\hermes
+//!   macOS:   ~/.hermes
+//!   Linux:   ~/.hermes  (override via $HERMES_HOME)
+//!
+//! NOTE (macOS): Python's get_hermes_home(), scripts/install.sh, and the
+//! Electron desktop's resolveHermesHome() ALL use ~/.hermes on macOS — there
+//! is no ~/Library/Application Support branch anywhere else. An earlier
+//! version of this file used Application Support, which drifted from every
+//! other component: the installer wrote the install to one dir and the
+//! desktop looked for it in another, so first launch never found the backend.
+//!
+//! IMPORTANT: this must match exactly. Drift here means install.ps1
+//! writes to one place and the installer reads from another, breaking
+//! the bootstrap-complete check.
+
+use std::path::{Path, PathBuf};
+use tracing_appender::non_blocking::WorkerGuard;
+
+/// Returns the canonical Hermes home directory, respecting $HERMES_HOME if set.
+pub fn hermes_home() -> PathBuf {
+    if let Ok(override_path) = std::env::var("HERMES_HOME") {
+        if !override_path.trim().is_empty() {
+            return PathBuf::from(override_path);
+        }
+    }
+
+    #[cfg(target_os = "windows")]
+    {
+        // %LOCALAPPDATA%\hermes — matches scripts/install.ps1's $HermesHome.
+        if let Some(local_app_data) = dirs::data_local_dir() {
+            return local_app_data.join("hermes");
+        }
+    }
+
+    // macOS + Linux + fallback: ~/.hermes (matches Python get_hermes_home(),
+    // install.sh, and the Electron desktop's resolveHermesHome()).
+    if let Some(home) = dirs::home_dir() {
+        return home.join(".hermes");
+    }
+
+    // Last resort — current dir, almost certainly wrong but at least
+    // doesn't panic.
+    PathBuf::from(".hermes")
+}
+
+pub fn log_dir() -> PathBuf {
+    hermes_home().join("logs")
+}
+
+pub fn log_path() -> PathBuf {
+    log_dir().join("bootstrap-installer.log")
+}
+
+pub fn bootstrap_cache_dir() -> PathBuf {
+    hermes_home().join("bootstrap-cache")
+}
+
+/// Stable location the installer copies itself to after a successful install.
+/// The desktop app re-invokes this with `--update`, and the start-menu /
+/// desktop shortcuts can point users back to it. Lives directly under
+/// HERMES_HOME so it survives repo checkout deletion (unlike anything under
+/// hermes-agent/).
+///
+/// On Windows this is `%LOCALAPPDATA%\hermes\hermes-setup.exe`; on other
+/// platforms the extension differs but the directory is the same.
+pub fn installer_dest() -> PathBuf {
+    let name = if cfg!(target_os = "windows") {
+        "hermes-setup.exe"
+    } else {
+        "hermes-setup"
+    };
+    hermes_home().join(name)
+}
+
+/// Copy the currently-running installer binary to `installer_dest()` so it's
+/// available for future `--update` runs and shortcut launches.
+///
+/// No-ops (returns Ok) when the running exe is ALREADY the destination — which
+/// is exactly the case during an `--update` run (the desktop launched us FROM
+/// that path), where copying onto ourselves would be a Windows sharing
+/// violation. Best-effort: a failure here must not fail the install, so the
+/// caller logs and continues.
+pub fn copy_self_to_hermes_home() -> std::io::Result<()> {
+    let src = std::env::current_exe()?;
+    let dest = installer_dest();
+
+    // Skip if we're already running from the destination (update re-invocation
+    // or a prior copy). canonicalize both so symlinks / 8.3 short paths / case
+    // differences don't trick us into a self-copy.
+    let same = match (src.canonicalize(), dest.canonicalize()) {
+        (Ok(a), Ok(b)) => a == b,
+        _ => src == dest,
+    };
+    if same {
+        tracing::info!(?dest, "installer already at destination; skipping self-copy");
+        return Ok(());
+    }
+
+    if let Some(parent) = dest.parent() {
+        std::fs::create_dir_all(parent)?;
+    }
+    std::fs::copy(&src, &dest)?;
+    tracing::info!(?src, ?dest, "copied installer to HERMES_HOME");
+    Ok(())
+}
+
+/// Where install.ps1 writes the bootstrap-complete marker (existence-only file
+/// the Electron app also checks). Per main.cjs:
+///   const BOOTSTRAP_COMPLETE_MARKER = path.join(ACTIVE_HERMES_ROOT, '.hermes-bootstrap-complete')
+/// We don't always know ACTIVE_HERMES_ROOT until install.ps1 reports it, so
+/// this is a probe helper, not a definitive path.
+pub fn likely_bootstrap_marker(install_root: &Path) -> PathBuf {
+    install_root.join(".hermes-bootstrap-complete")
+}
+
+/// Initializes tracing to bootstrap-installer.log under HERMES_HOME/logs/.
+/// Returns a guard that flushes the appender on drop — keep it alive for
+/// the lifetime of the process.
+pub fn init_logging() -> Option<WorkerGuard> {
+    let dir = log_dir();
+    if let Err(err) = std::fs::create_dir_all(&dir) {
+        // No log dir → log to stderr only. Don't panic; the installer
+        // should still be usable on an exotic filesystem.
+        eprintln!("[hermes-setup] could not create log dir {dir:?}: {err}");
+        return None;
+    }
+
+    let file_appender = tracing_appender::rolling::never(&dir, "bootstrap-installer.log");
+    let (non_blocking, guard) = tracing_appender::non_blocking(file_appender);
+
+    let env_filter = tracing_subscriber::EnvFilter::try_from_env("HERMES_BOOTSTRAP_LOG")
+        .unwrap_or_else(|_| tracing_subscriber::EnvFilter::new("info"));
+
+    tracing_subscriber::fmt()
+        .with_env_filter(env_filter)
+        .with_writer(non_blocking)
+        .with_ansi(false)
+        .with_target(true)
+        .init();
+
+    Some(guard)
+}
+
+// ---------------------------------------------------------------------------
+// Tauri commands
+// ---------------------------------------------------------------------------
+
+#[tauri::command]
+pub fn get_log_path() -> String {
+    log_path().to_string_lossy().into_owned()
+}
+
+#[tauri::command]
+pub fn get_hermes_home() -> String {
+    hermes_home().to_string_lossy().into_owned()
+}
+
+#[tauri::command]
+pub fn open_log_dir(app: tauri::AppHandle) -> Result<(), String> {
+    use tauri_plugin_opener::OpenerExt;
+    let path = log_dir();
+    app.opener()
+        .open_path(path.to_string_lossy(), None::<&str>)
+        .map_err(|e| e.to_string())
+}

apps/bootstrap-installer/src-tauri/src/powershell.rs

@@ -0,0 +1,267 @@
+//! Drives PowerShell (Windows) or bash (Unix) for install.ps1 / install.sh.
+//!
+//! Port of `spawnPowerShell` from bootstrap-runner.cjs, with the same
+//! line-buffered stdout/stderr streaming + cancellation semantics.
+//!
+//! On Windows we pass `-NoProfile -ExecutionPolicy Bypass -File <script>`.
+//! On Unix we shell out to `bash <script>` since install.sh expects bash.
+
+use anyhow::{Context, Result};
+use std::path::Path;
+use std::process::Stdio;
+use tokio::io::{AsyncBufReadExt, BufReader};
+use tokio::process::{Child, Command};
+use tokio::sync::mpsc;
+
+/// Hooks the caller installs to receive output.
+pub struct StreamSink {
+    pub on_stdout_line: Box<dyn Fn(&str) + Send + Sync>,
+    pub on_stderr_line: Box<dyn Fn(&str) + Send + Sync>,
+}
+
+/// Outcome of a script invocation. Mirrors bootstrap-runner.cjs's
+/// `{stdout, stderr, code, signal, killed}` shape.
+#[derive(Debug)]
+pub struct ScriptResult {
+    pub stdout: String,
+    pub stderr: String,
+    pub exit_code: Option<i32>,
+    pub killed: bool,
+}
+
+/// Cancellation signal — `cancel_tx.send(()).await` aborts the running script.
+pub type CancelRx = mpsc::Receiver<()>;
+
+/// Spawns install.ps1 / install.sh with the given args and streams output.
+///
+/// `hermes_home_override` propagates to the child as $HERMES_HOME so the
+/// install script writes to the same directory the installer is reading from.
+pub async fn run_script(
+    script_path: &Path,
+    args: &[String],
+    sink: StreamSink,
+    hermes_home_override: Option<&str>,
+    mut cancel_rx: Option<CancelRx>,
+) -> Result<ScriptResult> {
+    let mut cmd = build_command(script_path, args);
+
+    if let Some(home) = hermes_home_override {
+        cmd.env("HERMES_HOME", home);
+    }
+
+    cmd.stdin(Stdio::null())
+        .stdout(Stdio::piped())
+        .stderr(Stdio::piped());
+
+    // On Windows, avoid spawning a flashing cmd window when we're hosted
+    // inside a GUI process. Tauri's main window is already created, so
+    // the side-effect console for the child is unwanted.
+    #[cfg(target_os = "windows")]
+    {
+        // CREATE_NO_WINDOW = 0x08000000
+        cmd.creation_flags(0x0800_0000);
+    }
+
+    let mut child: Child = cmd
+        .spawn()
+        .with_context(|| format!("spawning {}", script_path.display()))?;
+
+    let stdout = child.stdout.take().expect("stdout was piped");
+    let stderr = child.stderr.take().expect("stderr was piped");
+
+    let mut stdout_reader = BufReader::new(stdout).lines();
+    let mut stderr_reader = BufReader::new(stderr).lines();
+
+    let mut combined_stdout = String::new();
+    let mut combined_stderr = String::new();
+    let mut killed = false;
+
+    // Loop: poll stdout, stderr, cancel, and child exit concurrently.
+    loop {
+        tokio::select! {
+            line = stdout_reader.next_line() => {
+                match line {
+                    Ok(Some(l)) => {
+                        (sink.on_stdout_line)(&l);
+                        combined_stdout.push_str(&l);
+                        combined_stdout.push('\n');
+                    }
+                    Ok(None) => {
+                        // EOF on stdout — wait for stderr + exit.
+                        break;
+                    }
+                    Err(e) => {
+                        tracing::warn!("stdout read error: {e}");
+                        break;
+                    }
+                }
+            }
+            line = stderr_reader.next_line() => {
+                match line {
+                    Ok(Some(l)) => {
+                        (sink.on_stderr_line)(&l);
+                        combined_stderr.push_str(&l);
+                        combined_stderr.push('\n');
+                    }
+                    Ok(None) => {
+                        // stderr EOF — keep draining stdout.
+                    }
+                    Err(e) => {
+                        tracing::warn!("stderr read error: {e}");
+                    }
+                }
+            }
+            _ = recv_cancel(&mut cancel_rx) => {
+                tracing::warn!("cancellation received — killing child");
+                killed = true;
+                // best-effort kill; don't propagate errors
+                let _ = child.start_kill();
+                break;
+            }
+        }
+    }
+
+    // Drain remaining lines after the loop exited.
+    while let Ok(Some(l)) = stdout_reader.next_line().await {
+        (sink.on_stdout_line)(&l);
+        combined_stdout.push_str(&l);
+        combined_stdout.push('\n');
+    }
+    while let Ok(Some(l)) = stderr_reader.next_line().await {
+        (sink.on_stderr_line)(&l);
+        combined_stderr.push_str(&l);
+        combined_stderr.push('\n');
+    }
+
+    let status = child
+        .wait()
+        .await
+        .context("waiting for install script to exit")?;
+
+    Ok(ScriptResult {
+        stdout: combined_stdout,
+        stderr: combined_stderr,
+        exit_code: status.code(),
+        killed,
+    })
+}
+
+async fn recv_cancel(rx: &mut Option<CancelRx>) {
+    match rx {
+        Some(r) => {
+            let _ = r.recv().await;
+        }
+        None => std::future::pending::<()>().await,
+    }
+}
+
+#[cfg(target_os = "windows")]
+fn build_command(script_path: &Path, args: &[String]) -> Command {
+    // We want PowerShell 5.1 / 7. install.ps1 uses 5.1-safe syntax everywhere.
+    // Prefer `powershell.exe` (5.1 baseline, present on every Windows since 7)
+    // over `pwsh.exe` (7+, may not be present).
+    let mut cmd = Command::new("powershell.exe");
+    cmd.arg("-NoProfile");
+    cmd.arg("-ExecutionPolicy").arg("Bypass");
+    cmd.arg("-File").arg(script_path);
+    for a in args {
+        cmd.arg(a);
+    }
+    cmd
+}
+
+#[cfg(not(target_os = "windows"))]
+fn build_command(script_path: &Path, args: &[String]) -> Command {
+    // install.sh expects bash. /bin/bash is fine on macOS (Apple still
+    // ships an old 3.2 bash; install.sh is written to that baseline).
+    let mut cmd = Command::new("bash");
+    cmd.arg(script_path);
+    for a in args {
+        cmd.arg(a);
+    }
+    cmd
+}
+
+/// Parses the LAST line of stdout that looks like a JSON object matching
+/// the install.ps1 stage-result contract: `{ok: bool, stage: string, ...}`.
+///
+/// Mirrors `parseStageResult` from bootstrap-runner.cjs. install.ps1 may
+/// print info/banner lines before the result frame; we scan from the end.
+pub fn parse_stage_result(stdout: &str) -> Option<crate::events::StageResultPayload> {
+    for line in stdout.lines().rev() {
+        let trimmed = line.trim();
+        if trimmed.is_empty() {
+            continue;
+        }
+        if let Ok(value) = serde_json::from_str::<serde_json::Value>(trimmed) {
+            if value.get("ok").and_then(|v| v.as_bool()).is_some()
+                && value.get("stage").and_then(|v| v.as_str()).is_some()
+            {
+                if let Ok(parsed) =
+                    serde_json::from_value::<crate::events::StageResultPayload>(value)
+                {
+                    return Some(parsed);
+                }
+            }
+        }
+    }
+    None
+}
+
+/// Same logic but for the `-Manifest` payload (the LAST line with a `stages`
+/// array). Returns the parsed manifest.
+pub fn parse_manifest(stdout: &str) -> Option<crate::events::Manifest> {
+    for line in stdout.lines().rev() {
+        let trimmed = line.trim();
+        if trimmed.is_empty() {
+            continue;
+        }
+        if let Ok(value) = serde_json::from_str::<serde_json::Value>(trimmed) {
+            if value.get("stages").and_then(|v| v.as_array()).is_some() {
+                if let Ok(parsed) = serde_json::from_value::<crate::events::Manifest>(value) {
+                    return Some(parsed);
+                }
+            }
+        }
+    }
+    None
+}
+
+#[cfg(target_os = "windows")]
+use std::os::windows::process::CommandExt;
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn parse_stage_result_picks_last_json_line() {
+        let stdout = r#"
+[bootstrap] some info
+{"ok": false, "stage": "venv", "reason": "bad python"}
+{"ok": true, "stage": "venv"}
+final non-json banner
+"#;
+        let result = parse_stage_result(stdout).unwrap();
+        assert_eq!(result.stage, "venv");
+        assert!(result.ok);
+    }
+
+    #[test]
+    fn parse_manifest_finds_stages_array() {
+        let stdout = r#"
+info line
+{"stages": [{"name": "uv", "title": "uv", "category": "prereqs", "needs_user_input": false}], "protocol_version": 1}
+"#;
+        let m = parse_manifest(stdout).unwrap();
+        assert_eq!(m.stages.len(), 1);
+        assert_eq!(m.stages[0].name, "uv");
+        assert_eq!(m.protocol_version, Some(1));
+    }
+
+    #[test]
+    fn parse_returns_none_when_no_match() {
+        assert!(parse_stage_result("just banner\n").is_none());
+        assert!(parse_manifest("just banner\n").is_none());
+    }
+}

apps/bootstrap-installer/src-tauri/src/update.rs

@@ -0,0 +1,462 @@
+//! Update orchestration.
+//!
+//! Driven when the installer is launched as `Hermes-Setup.exe --update` (see
+//! `AppMode` in lib.rs). The desktop app hands off to us — it exits, then we:
+//!
+//!   1. wait for the old Hermes desktop process to fully exit (so the venv
+//!      shim is free; otherwise `hermes update` aborts with exit code 2),
+//!   2. run `hermes update --yes --gateway` (Python/repo update; this does NOT
+//!      rebuild apps/desktop by design — see cmd_update in hermes_cli/main.py),
+//!   3. run `hermes desktop --build-only` (the rebuild step update skips),
+//!   4. launch the freshly-built desktop (reuses bootstrap::launch logic).
+//!
+//! We reuse the `BootstrapEvent` channel + the existing progress UI by
+//! emitting a synthetic two-stage manifest ("update", "rebuild"). To the
+//! frontend an update looks like a short bootstrap.
+//!
+//! Cross-platform note: `hermes update` already handles macOS/Linux (git/pip).
+//! The only OS-specific bits here are the venv shim path (resolve_hermes) and
+//! the no-window creation flag — both already cfg-gated. Keep new logic
+//! OS-agnostic so the mac/linux port stays "fill in the paths".
+
+use std::path::{Path, PathBuf};
+use std::process::Stdio;
+use std::time::{Duration, Instant};
+
+use anyhow::{anyhow, Result};
+use tauri::{AppHandle, Emitter};
+use tokio::io::{AsyncBufReadExt, BufReader};
+use tokio::process::Command;
+
+use crate::events::{BootstrapEvent, StageInfo, StageState};
+
+/// `hermes update` exit code meaning "another hermes process is holding the
+/// venv shim open / dirty precondition" — see _cmd_update_impl in
+/// hermes_cli/main.py (sys.exit(2)). We surface a targeted message for this.
+const UPDATE_EXIT_CONCURRENT: i32 = 2;
+
+/// How long to wait for the old desktop process to release the venv shim
+/// before giving up and letting `hermes update`'s own guard decide.
+const DESKTOP_EXIT_WAIT: Duration = Duration::from_secs(20);
+const DESKTOP_EXIT_POLL: Duration = Duration::from_millis(500);
+
+/// Frontend → Rust: kick off the update flow. Mirrors `start_bootstrap`'s
+/// fire-and-forget shape; progress arrives on the `bootstrap` event channel.
+#[tauri::command]
+pub async fn start_update(app: AppHandle) -> Result<(), String> {
+    tokio::spawn(async move {
+        if let Err(err) = run_update(app.clone()).await {
+            // run_update already emits a Failed event on the paths that matter;
+            // this catches anything that escaped. Emit defensively.
+            emit(
+                &app,
+                BootstrapEvent::Failed {
+                    stage: None,
+                    error: format!("{err:#}"),
+                },
+            );
+        }
+    });
+    Ok(())
+}
+
+async fn run_update(app: AppHandle) -> Result<()> {
+    let hermes_home = crate::paths::hermes_home();
+    let install_root = hermes_home.join("hermes-agent");
+
+    let hermes = resolve_hermes(&install_root).ok_or_else(|| {
+        let msg = format!(
+            "Could not find the hermes CLI under {}. Is Hermes installed? \
+             Re-run the installer to repair the install.",
+            install_root.display()
+        );
+        emit(
+            &app,
+            BootstrapEvent::Failed {
+                stage: None,
+                error: msg.clone(),
+            },
+        );
+        anyhow!(msg)
+    })?;
+
+    // Synthetic manifest so the existing progress UI renders our two stages.
+    emit(
+        &app,
+        BootstrapEvent::Manifest {
+            stages: vec![
+                stage_info("update", "Updating Hermes"),
+                stage_info("rebuild", "Rebuilding the desktop app"),
+            ],
+            protocol_version: None,
+        },
+    );
+
+    // ---- pre-step: wait for the old desktop to die -----------------------
+    // The desktop exec'd us then called app.exit(), but process teardown is
+    // async on Windows. If it still holds the venv shim, `hermes update`
+    // aborts with exit 2. Give it a bounded window to clear.
+    wait_for_venv_free(&install_root, &app).await;
+
+    // ---- stage 1: hermes update -----------------------------------------
+    // Pass --branch so `hermes update` targets the branch this installer was
+    // built/pinned against (BUILD_PIN_BRANCH), NOT its built-in default of
+    // `main`. The install was a detached-HEAD checkout of a specific commit;
+    // without --branch, `hermes update` switches the checkout to `main` (a
+    // divergent branch that may not even have the desktop CLI command), then
+    // reports "already up to date" against the wrong branch. The desktop
+    // detected the update against this same branch, so we must update against
+    // it too.
+    let pin_branch = option_env_string("BUILD_PIN_BRANCH");
+    let mut update_args: Vec<&str> = vec!["update", "--yes", "--gateway"];
+    if let Some(b) = pin_branch.as_deref() {
+        update_args.push("--branch");
+        update_args.push(b);
+    }
+
+    emit_stage(&app, "update", StageState::Running, None, None);
+    let started = Instant::now();
+    let update = run_streamed(
+        &app,
+        &hermes,
+        &update_args,
+        &install_root,
+        Some("update"),
+    )
+    .await?;
+    let update_ms = started.elapsed().as_millis() as u64;
+
+    match update.exit_code {
+        Some(0) => {
+            emit_stage(&app, "update", StageState::Succeeded, Some(update_ms), None);
+        }
+        Some(code) if code == UPDATE_EXIT_CONCURRENT => {
+            let msg = "Hermes is still running. Close all Hermes windows and try \
+                       the update again."
+                .to_string();
+            emit_stage(
+                &app,
+                "update",
+                StageState::Failed,
+                Some(update_ms),
+                Some(msg.clone()),
+            );
+            emit(
+                &app,
+                BootstrapEvent::Failed {
+                    stage: Some("update".into()),
+                    error: msg.clone(),
+                },
+            );
+            return Err(anyhow!(msg));
+        }
+        other => {
+            let msg = format!(
+                "hermes update failed (exit {:?}). See {} for details.",
+                other,
+                crate::paths::hermes_home()
+                    .join("logs")
+                    .join("update.log")
+                    .display()
+            );
+            emit_stage(
+                &app,
+                "update",
+                StageState::Failed,
+                Some(update_ms),
+                Some(msg.clone()),
+            );
+            emit(
+                &app,
+                BootstrapEvent::Failed {
+                    stage: Some("update".into()),
+                    error: msg.clone(),
+                },
+            );
+            return Err(anyhow!(msg));
+        }
+    }
+
+    // ---- stage 2: hermes desktop --build-only ----------------------------
+    // `hermes update` deliberately does NOT build apps/desktop (it installs
+    // repo-root deps with --workspaces=false). This is the rebuild it skips.
+    emit_stage(&app, "rebuild", StageState::Running, None, None);
+    let started = Instant::now();
+    let rebuild = run_streamed(
+        &app,
+        &hermes,
+        &["desktop", "--build-only"],
+        &install_root,
+        Some("rebuild"),
+    )
+    .await?;
+    let rebuild_ms = started.elapsed().as_millis() as u64;
+
+    if rebuild.exit_code != Some(0) {
+        let msg = format!(
+            "Rebuilding the desktop app failed (exit {:?}). The update was \
+             applied but the app could not be rebuilt; run `hermes desktop` \
+             from a terminal to see the error.",
+            rebuild.exit_code
+        );
+        emit_stage(
+            &app,
+            "rebuild",
+            StageState::Failed,
+            Some(rebuild_ms),
+            Some(msg.clone()),
+        );
+        emit(
+            &app,
+            BootstrapEvent::Failed {
+                stage: Some("rebuild".into()),
+                error: msg.clone(),
+            },
+        );
+        return Err(anyhow!(msg));
+    }
+    emit_stage(&app, "rebuild", StageState::Succeeded, Some(rebuild_ms), None);
+
+    // ---- done: signal complete, then launch the fresh desktop ------------
+    emit(
+        &app,
+        BootstrapEvent::Complete {
+            install_root: install_root.to_string_lossy().into_owned(),
+            marker: None,
+        },
+    );
+
+    // Reuse the same detached-launch + app.exit(0) used post-install.
+    if let Err(err) =
+        crate::bootstrap::launch_hermes_desktop(app.clone(), install_root.to_string_lossy().into_owned())
+            .await
+    {
+        // Launch failed: don't hard-fail the update (it succeeded); surface a
+        // log line so the success screen can still tell the user to launch
+        // manually.
+        emit_log(
+            &app,
+            None,
+            &format!("[update] could not auto-launch desktop: {err}. Launch Hermes manually."),
+        );
+    }
+
+    Ok(())
+}
+
+/// Poll until the venv shim is no longer locked (Windows) or a bounded timeout
+/// elapses. On non-Windows this is a short fixed grace since file locking
+/// isn't the failure mode there.
+async fn wait_for_venv_free(install_root: &Path, app: &AppHandle) {
+    let shim = venv_hermes(install_root);
+    let deadline = Instant::now() + DESKTOP_EXIT_WAIT;
+
+    emit_log(app, Some("update"), "[update] waiting for Hermes to exit…");
+
+    loop {
+        if !is_locked(&shim) {
+            return;
+        }
+        if Instant::now() >= deadline {
+            emit_log(
+                app,
+                Some("update"),
+                "[update] timed out waiting for Hermes to exit; proceeding anyway",
+            );
+            return;
+        }
+        tokio::time::sleep(DESKTOP_EXIT_POLL).await;
+    }
+}
+
+/// Best-effort lock probe: try to open the file for read+write. On Windows an
+/// exclusively-held running .exe refuses the open with a sharing violation.
+/// On Unix this almost always succeeds (no mandatory locking), which is fine —
+/// the venv-shim contention is a Windows-only problem.
+fn is_locked(path: &Path) -> bool {
+    if !path.exists() {
+        return false;
+    }
+    match std::fs::OpenOptions::new().read(true).write(true).open(path) {
+        Ok(_) => false,
+        Err(_) => true,
+    }
+}
+
+/// Spawn `hermes <args>` from `cwd`, stream stdout/stderr as Log events on the
+/// bootstrap channel, and return the exit code. Mirrors powershell::run_script
+/// but for an arbitrary command (no install.ps1 -File wrapping).
+async fn run_streamed(
+    app: &AppHandle,
+    program: &Path,
+    args: &[&str],
+    cwd: &Path,
+    stage: Option<&str>,
+) -> Result<CmdResult> {
+    let mut cmd = Command::new(program);
+    cmd.args(args)
+        .current_dir(cwd)
+        .stdin(Stdio::null())
+        .stdout(Stdio::piped())
+        .stderr(Stdio::piped());
+
+    #[cfg(target_os = "windows")]
+    {
+        use std::os::windows::process::CommandExt;
+        // CREATE_NO_WINDOW = 0x08000000 — no flashing console behind the GUI.
+        cmd.creation_flags(0x0800_0000);
+    }
+
+    let mut child = cmd
+        .spawn()
+        .map_err(|e| anyhow!("spawning {} {:?}: {e}", program.display(), args))?;
+
+    let stdout = child.stdout.take().expect("stdout piped");
+    let stderr = child.stderr.take().expect("stderr piped");
+    let mut out = BufReader::new(stdout).lines();
+    let mut err = BufReader::new(stderr).lines();
+
+    let stage_owned = stage.map(|s| s.to_string());
+    loop {
+        tokio::select! {
+            line = out.next_line() => match line {
+                Ok(Some(l)) => emit_log(app, stage_owned.as_deref(), &l),
+                Ok(None) => break,
+                Err(e) => { tracing::warn!("stdout read error: {e}"); break; }
+            },
+            line = err.next_line() => match line {
+                Ok(Some(l)) => emit_log(app, stage_owned.as_deref(), &format!("stderr: {l}")),
+                Ok(None) => {}
+                Err(e) => { tracing::warn!("stderr read error: {e}"); }
+            },
+        }
+    }
+    while let Ok(Some(l)) = out.next_line().await {
+        emit_log(app, stage_owned.as_deref(), &l);
+    }
+    while let Ok(Some(l)) = err.next_line().await {
+        emit_log(app, stage_owned.as_deref(), &format!("stderr: {l}"));
+    }
+
+    let status = child.wait().await.map_err(|e| anyhow!("waiting for child: {e}"))?;
+    Ok(CmdResult {
+        exit_code: status.code(),
+    })
+}
+
+struct CmdResult {
+    exit_code: Option<i32>,
+}
+
+/// Path to the venv hermes shim under an install root, regardless of existence.
+fn venv_hermes(install_root: &Path) -> PathBuf {
+    if cfg!(target_os = "windows") {
+        install_root.join("venv").join("Scripts").join("hermes.exe")
+    } else {
+        install_root.join("venv").join("bin").join("hermes")
+    }
+}
+
+/// Resolve the hermes CLI to drive. Prefer the venv shim in the install we
+/// just updated; fall back to `hermes` on PATH.
+fn resolve_hermes(install_root: &Path) -> Option<PathBuf> {
+    let shim = venv_hermes(install_root);
+    if shim.exists() {
+        return Some(shim);
+    }
+    // PATH fallback. which-style probe via env, kept dependency-free.
+    let exe = if cfg!(target_os = "windows") { "hermes.exe" } else { "hermes" };
+    if let Ok(path) = std::env::var("PATH") {
+        let sep = if cfg!(target_os = "windows") { ';' } else { ':' };
+        for dir in path.split(sep) {
+            let cand = Path::new(dir).join(exe);
+            if cand.exists() {
+                return Some(cand);
+            }
+        }
+    }
+    None
+}
+
+// ---------------------------------------------------------------------------
+// Event helpers — keep emit shape identical to bootstrap.rs so the UI is reused
+// ---------------------------------------------------------------------------
+
+fn stage_info(name: &str, title: &str) -> StageInfo {
+    StageInfo {
+        name: name.to_string(),
+        title: title.to_string(),
+        category: "update".to_string(),
+        needs_user_input: false,
+    }
+}
+
+// option_env! only accepts string literals, so the build-time pins are read
+// by their literal names here. Mirrors bootstrap.rs's helper of the same name
+// (kept local rather than shared because option_env! can't be parameterized).
+fn option_env_string(key: &str) -> Option<String> {
+    let val = match key {
+        "BUILD_PIN_COMMIT" => option_env!("BUILD_PIN_COMMIT"),
+        "BUILD_PIN_BRANCH" => option_env!("BUILD_PIN_BRANCH"),
+        _ => None,
+    };
+    val.map(|s| s.to_string())
+}
+
+fn emit(app: &AppHandle, event: BootstrapEvent) {
+    if let Err(e) = app.emit(BootstrapEvent::CHANNEL, &event) {
+        tracing::warn!(?e, "failed to emit update event");
+    }
+}
+
+fn emit_stage(
+    app: &AppHandle,
+    name: &str,
+    state: StageState,
+    duration_ms: Option<u64>,
+    error: Option<String>,
+) {
+    tracing::info!(stage = %name, ?state, ?duration_ms, ?error, "update stage");
+    emit(
+        app,
+        BootstrapEvent::Stage {
+            name: name.to_string(),
+            state,
+            duration_ms,
+            result: None,
+            error,
+        },
+    );
+}
+
+fn emit_log(app: &AppHandle, stage: Option<&str>, line: &str) {
+    match stage {
+        Some(s) => tracing::info!(target: "bootstrap.log", stage = %s, "{line}"),
+        None => tracing::info!(target: "bootstrap.log", "{line}"),
+    }
+    emit(
+        app,
+        BootstrapEvent::Log {
+            stage: stage.map(|s| s.to_string()),
+            line: line.to_string(),
+        },
+    );
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn venv_hermes_is_under_install_root() {
+        let root = Path::new("/x/hermes-agent");
+        let shim = venv_hermes(root);
+        assert!(shim.starts_with(root));
+        assert!(shim.to_string_lossy().contains("venv"));
+    }
+
+    #[test]
+    fn missing_file_is_not_locked() {
+        assert!(!is_locked(Path::new("/nonexistent/does/not/exist/xyz")));
+    }
+}

apps/bootstrap-installer/src-tauri/tauri.conf.json

@@ -0,0 +1,67 @@
+{
+  "$schema": "https://schema.tauri.app/config/2",
+  "productName": "Hermes Setup",
+  "version": "0.0.1",
+  "identifier": "com.nousresearch.hermes.setup",
+  "build": {
+    "beforeDevCommand": "npm run dev",
+    "devUrl": "http://127.0.0.1:5175",
+    "beforeBuildCommand": "npm run build",
+    "frontendDist": "../dist"
+  },
+  "app": {
+    "windows": [
+      {
+        "label": "main",
+        "title": "Hermes Setup",
+        "width": 880,
+        "height": 620,
+        "minWidth": 720,
+        "minHeight": 520,
+        "resizable": true,
+        "fullscreen": false,
+        "decorations": true,
+        "transparent": false,
+        "center": true
+      }
+    ],
+    "security": {
+      "csp": "default-src 'self'; img-src 'self' data:; style-src 'self' 'unsafe-inline'; script-src 'self'; font-src 'self' data:; connect-src 'self' ipc: http://ipc.localhost"
+    },
+    "withGlobalTauri": false
+  },
+  "bundle": {
+    "active": true,
+    "category": "DeveloperTool",
+    "shortDescription": "Hermes Setup",
+    "longDescription": "Installs Hermes Agent on your machine. Drives scripts/install.ps1 (Windows) and scripts/install.sh (macOS/Linux).",
+    "publisher": "Nous Research",
+    "copyright": "Copyright © 2026 Nous Research",
+    "targets": [
+      "app",
+      "dmg",
+      "appimage"
+    ],
+    "icon": [
+      "icons/32x32.png",
+      "icons/128x128.png",
+      "icons/128x128@2x.png",
+      "icons/icon.icns",
+      "icons/icon.ico"
+    ],
+    "windows": {
+      "webviewInstallMode": {
+        "type": "embedBootstrapper"
+      }
+    },
+    "macOS": {
+      "minimumSystemVersion": "11.0",
+      "hardenedRuntime": true
+    }
+  },
+  "plugins": {
+    "shell": {
+      "open": true
+    }
+  }
+}

apps/bootstrap-installer/src/app.tsx

@@ -0,0 +1,35 @@
+import { useStore } from '@nanostores/react'
+import { useEffect } from 'react'
+import { $route, $bootstrap, initialize } from './store'
+import Welcome from './routes/welcome'
+import Progress from './routes/progress'
+import Success from './routes/success'
+import Failure from './routes/failure'
+
+/*
+ * App shell — Hermes Setup.
+ *
+ * No header chrome (the OS title bar already says "Hermes Setup"; an
+ * in-window repeat of the H mark + words was redundant slop).
+ *
+ * Route state lives in a single $route atom — 4 screens, no react-router.
+ */
+export default function App() {
+  const route = useStore($route)
+  const bootstrap = useStore($bootstrap)
+
+  useEffect(() => {
+    void initialize()
+  }, [])
+
+  return (
+    <div className="relative flex h-full flex-col overflow-hidden bg-background text-foreground">
+      <main className="relative z-10 flex flex-1 flex-col overflow-hidden">
+        {route === 'welcome' && <Welcome />}
+        {route === 'progress' && <Progress bootstrap={bootstrap} />}
+        {route === 'success' && <Success />}
+        {route === 'failure' && <Failure bootstrap={bootstrap} />}
+      </main>
+    </div>
+  )
+}

apps/bootstrap-installer/src/components/button.tsx

@@ -0,0 +1,80 @@
+import { cva, type VariantProps } from 'class-variance-authority'
+import { Slot } from 'radix-ui'
+import * as React from 'react'
+
+import { cn } from '../lib/utils'
+
+/*
+ * Button — copied verbatim from apps/desktop/src/components/ui/button.tsx.
+ *
+ * We import the desktop's local shadcn-style Button rather than
+ * @nous-research/ui's <Button>, because the DS Button uses bg-midground /
+ * text-background-base utilities that resolve to the DS's hardcoded
+ * gold/brown brand defaults (#ffac02 / #170d02) unless overridden in
+ * runtime. The desktop never sets those vars; it routes through its
+ * own --dt-* token chain via shadcn classes like bg-primary. We do
+ * the same so visuals match exactly.
+ */
+
+const buttonVariants = cva(
+  "inline-flex shrink-0 items-center justify-center gap-2 rounded-md text-sm font-medium whitespace-nowrap transition-all outline-none focus-visible:border-ring focus-visible:ring-[0.1875rem] focus-visible:ring-ring/50 disabled:pointer-events-none disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-destructive/20 dark:aria-invalid:ring-destructive/40 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+  {
+    variants: {
+      variant: {
+        default: 'bg-primary text-primary-foreground hover:bg-primary/90',
+        destructive:
+          'bg-destructive text-white hover:bg-destructive/90 focus-visible:ring-destructive/20 dark:bg-destructive/60 dark:focus-visible:ring-destructive/40',
+        outline:
+          'border bg-background shadow-xs hover:bg-accent hover:text-accent-foreground dark:border-input dark:bg-input/30 dark:hover:bg-input/50',
+        secondary:
+          'bg-secondary text-secondary-foreground hover:bg-secondary/80',
+        ghost:
+          'hover:bg-accent hover:text-accent-foreground dark:hover:bg-accent/50',
+        link: 'text-primary underline-offset-4 decoration-current/20 hover:underline'
+      },
+      size: {
+        default: 'h-9 px-4 py-2 has-[>svg]:px-3',
+        xs: "h-6 gap-1 rounded-md px-2 text-xs has-[>svg]:px-1.5 [&_svg:not([class*='size-'])]:size-3",
+        sm: 'h-8 gap-1.5 rounded-md px-3 has-[>svg]:px-2.5',
+        lg: 'h-10 rounded-md px-6 has-[>svg]:px-4',
+        icon: 'size-9',
+        'icon-xs':
+          "size-6 rounded-md [&_svg:not([class*='size-'])]:size-3",
+        'icon-sm': 'size-8',
+        'icon-lg': 'size-10'
+      }
+    },
+    defaultVariants: {
+      variant: 'default',
+      size: 'default'
+    }
+  }
+)
+
+interface ButtonProps
+  extends React.ComponentProps<'button'>,
+    VariantProps<typeof buttonVariants> {
+  asChild?: boolean
+}
+
+export function Button({
+  className,
+  variant = 'default',
+  size = 'default',
+  asChild = false,
+  ...props
+}: ButtonProps) {
+  const Comp = asChild ? Slot.Root : 'button'
+
+  return (
+    <Comp
+      className={cn(buttonVariants({ variant, size }), className)}
+      data-size={size}
+      data-slot="button"
+      data-variant={variant}
+      {...props}
+    />
+  )
+}
+
+export { buttonVariants }

apps/bootstrap-installer/src/lib/utils.ts

@@ -0,0 +1,12 @@
+import { type ClassValue, clsx } from 'clsx'
+import { twMerge } from 'tailwind-merge'
+
+/*
+ * cn — Tailwind-aware class merger. Same util the desktop and dashboard
+ * use. clsx handles conditional classes; twMerge resolves utility
+ * conflicts so `cn('px-2', condition && 'px-4')` ends up with px-4 only,
+ * not both.
+ */
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}

apps/bootstrap-installer/src/main.tsx

@@ -0,0 +1,14 @@
+import { StrictMode } from 'react'
+import { createRoot } from 'react-dom/client'
+import App from './app.tsx'
+import './styles.css'
+
+// Default to LIGHT mode — matches the Hermes desktop's default. The
+// desktop's runtime theme system can switch to .dark later, but our
+// installer ships in light mode only since we don't carry the theme
+// provider machinery.
+createRoot(document.getElementById('root')!).render(
+  <StrictMode>
+    <App />
+  </StrictMode>
+)

apps/bootstrap-installer/src/routes/failure.tsx

@@ -0,0 +1,77 @@
+import { type CSSProperties } from 'react'
+import { useStore } from '@nanostores/react'
+import { Button } from '../components/button'
+import {
+  $logPath,
+  openLogDir,
+  startInstall,
+  type BootstrapStateModel
+} from '../store'
+import { RefreshCw, FileText } from 'lucide-react'
+
+interface FailureProps {
+  bootstrap: BootstrapStateModel
+}
+
+/*
+ * Failure screen. Same hero treatment as Welcome/Success — the wordmark
+ * carries the brand, so we keep it across every terminal state.
+ *
+ * The actual error message lives below in muted text. Two clear
+ * affordances: Retry (primary) and Open log folder (secondary).
+ */
+export default function Failure({ bootstrap }: FailureProps) {
+  const logPath = useStore($logPath)
+
+  return (
+    <div className="hermes-fade-in flex h-full flex-col items-center justify-center gap-6 px-12 py-10">
+      <div className="w-full max-w-2xl min-w-0 text-center">
+        <p
+          className="fit-text mx-auto mb-4 w-full font-['Collapse'] font-bold uppercase leading-[0.9] tracking-[0.08em] text-destructive mix-blend-plus-lighter dark:text-destructive/90"
+          style={
+            {
+              '--fit-text-line-height': '0.9',
+              '--fit-text-max': '5rem',
+              '--fit-text-min': '2.25rem'
+            } as CSSProperties
+          }
+        >
+          <span>
+            <span>Install didn&rsquo;t finish</span>
+          </span>
+          <span aria-hidden="true">Install didn&rsquo;t finish</span>
+        </p>
+
+        <p className="m-0 mx-auto max-w-xl text-center text-sm leading-normal tracking-tight text-muted-foreground">
+          {bootstrap.error ?? 'Something went wrong during installation.'}
+        </p>
+      </div>
+
+      <div className="flex items-center gap-3">
+        <Button
+          onClick={() => void startInstall()}
+          size="lg"
+          className="inline-flex items-center gap-2 px-6"
+        >
+          <RefreshCw size={16} />
+          Retry install
+        </Button>
+        <Button
+          variant="outline"
+          size="lg"
+          onClick={() => void openLogDir()}
+          className="inline-flex items-center gap-2"
+        >
+          <FileText size={16} />
+          Open log folder
+        </Button>
+      </div>
+
+      {logPath && (
+        <p className="max-w-lg text-center text-xs text-muted-foreground/70">
+          Log: <code className="font-mono">{logPath}</code>
+        </p>
+      )}
+    </div>
+  )
+}

apps/bootstrap-installer/src/routes/progress.tsx

@@ -0,0 +1,190 @@
+import { useEffect, useRef, useState } from 'react'
+import { useStore } from '@nanostores/react'
+import { Button } from '../components/button'
+import {
+  cancelInstall,
+  $progress,
+  type BootstrapStateModel,
+  type StageState
+} from '../store'
+import { Check, X, ChevronRight, FileText, Loader2 } from 'lucide-react'
+import clsx from 'clsx'
+
+interface ProgressProps {
+  bootstrap: BootstrapStateModel
+}
+
+/*
+ * Progress screen — drives a stage list + collapsible log panel. Uses
+ * the DS <Progress> for the top bar so its motion + ring match the rest
+ * of the product.
+ */
+export default function ProgressScreen({ bootstrap }: ProgressProps) {
+  const progress = useStore($progress)
+  const [showLogs, setShowLogs] = useState(false)
+  const logEndRef = useRef<HTMLDivElement>(null)
+
+  useEffect(() => {
+    if (showLogs && logEndRef.current) {
+      logEndRef.current.scrollIntoView({ behavior: 'smooth' })
+    }
+  }, [bootstrap.logs.length, showLogs])
+
+  const currentStage =
+    bootstrap.currentStage != null
+      ? bootstrap.stages[bootstrap.currentStage]
+      : null
+
+  return (
+    <div className="hermes-fade-in flex h-full flex-col">
+      <div className="border-b border-border px-6 py-4">
+        <div className="mb-3 flex items-center justify-between text-xs">
+          <div className="flex items-center gap-2 text-foreground">
+            {bootstrap.status === 'running' && (
+              <Loader2 size={12} className="animate-spin text-primary" />
+            )}
+            <span>
+              {bootstrap.status === 'running'
+                ? currentStage
+                  ? currentStage.info.title
+                  : 'Preparing\u2026'
+                : bootstrap.status === 'completed'
+                  ? 'Done'
+                  : 'Installing'}
+            </span>
+          </div>
+          <div className="text-muted-foreground">
+            {progress.done} of {progress.total} steps
+          </div>
+        </div>
+        {/* Top progress bar — plain HTML, derived from --primary so it
+            tracks the theme accent. */}
+        <div className="h-1 w-full overflow-hidden rounded-full bg-muted">
+          <div
+            className="h-full bg-primary transition-all duration-300 ease-out"
+            style={{ width: `${Math.max(2, progress.fraction * 100)}%` }}
+          />
+        </div>
+      </div>
+
+      <div className="flex flex-1 overflow-hidden">
+        <div className="flex-1 overflow-y-auto px-6 py-4">
+          <ol className="space-y-1">
+            {bootstrap.stageOrder.map((name) => {
+              const rec = bootstrap.stages[name]
+              if (!rec) return null
+              return (
+                <li
+                  key={name}
+                  className={clsx(
+                    'flex items-center gap-3 rounded-md px-3 py-2 text-sm transition-colors',
+                    rec.state === 'running' && 'bg-card text-foreground',
+                    rec.state === 'succeeded' && 'text-foreground/80',
+                    rec.state === 'skipped' && 'text-muted-foreground',
+                    rec.state === 'failed' &&
+                      'bg-destructive/10 text-destructive',
+                    !rec.state && 'text-muted-foreground/60'
+                  )}
+                >
+                  <StateIcon state={rec.state ?? null} />
+                  <span className="flex-1 truncate">{rec.info.title}</span>
+                  {rec.durationMs != null && (
+                    <span className="text-xs text-muted-foreground">
+                      {formatDuration(rec.durationMs)}
+                    </span>
+                  )}
+                </li>
+              )
+            })}
+          </ol>
+        </div>
+
+        {showLogs && (
+          <div className="flex w-1/2 flex-col border-l border-border bg-card/40">
+            <div className="flex shrink-0 items-center justify-between border-b border-border px-3 py-2">
+              <div className="text-xs font-medium text-foreground/80">
+                Live output
+              </div>
+              <div className="text-xs text-muted-foreground">
+                {bootstrap.logs.length} lines
+              </div>
+            </div>
+            <div className="flex-1 overflow-y-auto px-3 py-2 font-mono text-[11px] leading-relaxed">
+              {bootstrap.logs.map((entry, idx) => (
+                <div
+                  key={idx}
+                  className={clsx(
+                    'whitespace-pre-wrap',
+                    entry.line.startsWith('stderr:')
+                      ? 'text-destructive'
+                      : 'text-foreground/70'
+                  )}
+                >
+                  {entry.line}
+                </div>
+              ))}
+              <div ref={logEndRef} />
+            </div>
+          </div>
+        )}
+      </div>
+
+      <div className="flex shrink-0 items-center justify-between border-t border-border px-6 py-3">
+        <button
+          type="button"
+          onClick={() => setShowLogs((v) => !v)}
+          className="inline-flex items-center gap-1.5 text-xs text-muted-foreground transition-colors hover:text-foreground"
+        >
+          <FileText size={14} />
+          {showLogs ? 'Hide details' : 'Show details'}
+          <ChevronRight
+            size={12}
+            className={clsx(
+              'transition-transform',
+              showLogs && 'rotate-90'
+            )}
+          />
+        </button>
+
+        {bootstrap.status === 'running' && (
+          <Button
+            variant="outline"
+            size="sm"
+            onClick={() => void cancelInstall()}
+          >
+            Cancel
+          </Button>
+        )}
+      </div>
+    </div>
+  )
+}
+
+function StateIcon({ state }: { state: StageState | null }) {
+  if (state === 'running') {
+    return <Loader2 size={14} className="animate-spin text-primary" />
+  }
+  if (state === 'succeeded') {
+    return <Check size={14} className="text-emerald-400" />
+  }
+  if (state === 'skipped') {
+    return <ChevronRight size={14} className="text-muted-foreground/70" />
+  }
+  if (state === 'failed') {
+    return <X size={14} className="text-destructive" />
+  }
+  return (
+    <div
+      className="h-[6px] w-[6px] rounded-full bg-muted-foreground/40"
+      aria-hidden
+    />
+  )
+}
+
+function formatDuration(ms: number): string {
+  if (ms < 1000) return `${ms}ms`
+  if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`
+  const m = Math.floor(ms / 60000)
+  const s = Math.round((ms % 60000) / 1000)
+  return `${m}m ${s}s`
+}

apps/bootstrap-installer/src/routes/success.tsx

@@ -0,0 +1,87 @@
+import { useState } from 'react'
+import { type CSSProperties } from 'react'
+import { Button } from '../components/button'
+import { launchHermesDesktop } from '../store'
+import { Rocket, AlertCircle } from 'lucide-react'
+
+/*
+ * Success screen. HERMES AGENT wordmark stays as the visual anchor
+ * (same Collapse Bold treatment as Welcome + the desktop chat intro),
+ * with a status line below.
+ *
+ * Launching the desktop can fail (e.g. Stage-Desktop was skipped and
+ * Hermes.exe doesn't exist). We catch the Tauri error and surface it
+ * inline rather than silently doing nothing — the previous version
+ * had `onClick={() => void launchHermesDesktop()}` which swallowed
+ * the rejection and left the user staring at an unresponsive button.
+ */
+export default function Success() {
+  const [error, setError] = useState<string | null>(null)
+  const [launching, setLaunching] = useState(false)
+
+  async function handleLaunch() {
+    setError(null)
+    setLaunching(true)
+    try {
+      await launchHermesDesktop()
+      // On success the installer exits — control never returns here.
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e)
+      setError(msg)
+      setLaunching(false)
+    }
+  }
+
+  return (
+    <div className="hermes-fade-in flex h-full flex-col items-center justify-center gap-8 px-12 py-10">
+      <div className="w-full max-w-2xl min-w-0 text-center">
+        <p
+          className="fit-text mx-auto mb-4 w-full font-['Collapse'] font-bold uppercase leading-[0.9] tracking-[0.08em] text-midground mix-blend-plus-lighter dark:text-foreground/90"
+          style={
+            {
+              '--fit-text-line-height': '0.9',
+              '--fit-text-max': '5rem',
+              '--fit-text-min': '2.25rem'
+            } as CSSProperties
+          }
+        >
+          <span>
+            <span>Hermes is ready</span>
+          </span>
+          <span aria-hidden="true">Hermes is ready</span>
+        </p>
+
+        <p className="m-0 text-center text-base leading-normal tracking-tight text-muted-foreground">
+          You can launch from here, or any time from your terminal with{' '}
+          <code className="rounded bg-muted/60 px-1 py-0.5 font-mono text-sm">
+            hermes desktop
+          </code>
+          .
+        </p>
+      </div>
+
+      <Button
+        onClick={() => void handleLaunch()}
+        size="lg"
+        disabled={launching}
+        className="inline-flex items-center gap-2 px-6"
+      >
+        <Rocket size={18} />
+        {launching ? 'Launching…' : 'Launch Hermes'}
+      </Button>
+
+      {error && (
+        <div
+          role="alert"
+          className="flex max-w-2xl items-start gap-2 rounded-md border border-destructive/30 bg-destructive/10 px-4 py-3 text-sm text-destructive"
+        >
+          <AlertCircle size={16} className="mt-0.5 shrink-0" />
+          <div className="min-w-0">
+            <div className="font-medium">Couldn&rsquo;t launch the desktop app</div>
+            <div className="mt-1 text-destructive/80">{error}</div>
+          </div>
+        </div>
+      )}
+    </div>
+  )
+}

apps/bootstrap-installer/src/routes/welcome.tsx

@@ -0,0 +1,58 @@
+import { type CSSProperties } from 'react'
+import { Button } from '../components/button'
+import { startInstall } from '../store'
+import { ArrowRight } from 'lucide-react'
+
+/*
+ * Welcome screen.
+ *
+ * Mirrors the desktop's chat intro (apps/desktop/src/components/chat/intro.tsx):
+ *   - HERMES AGENT wordmark rendered in Collapse Bold, uppercase, tracked
+ *   - mix-blend-plus-lighter so the type "glows" on the canvas
+ *   - fit-text utility so the wordmark sizes itself to the column
+ *
+ * No install-path footer. The default install location is correct for
+ * 99% of users; the rest will use the CLI installer with a -HermesHome
+ * flag. Showing %LOCALAPPDATA% to grandma is developer-brain.
+ */
+export default function Welcome() {
+  return (
+    <div className="hermes-fade-in flex h-full flex-col items-center justify-center gap-10 px-12 py-10">
+      {/* Hero — same recipe the desktop's chat/intro.tsx uses */}
+      <div className="w-full max-w-2xl min-w-0 text-center">
+        <p
+          className="fit-text mx-auto mb-4 w-full font-['Collapse'] font-bold uppercase leading-[0.9] tracking-[0.08em] text-midground mix-blend-plus-lighter dark:text-foreground/90"
+          style={
+            {
+              '--fit-text-line-height': '0.9',
+              '--fit-text-max': '6rem',
+              '--fit-text-min': '2.5rem'
+            } as CSSProperties
+          }
+        >
+          <span>
+            <span>HERMES AGENT</span>
+          </span>
+          <span aria-hidden="true">HERMES AGENT</span>
+        </p>
+
+        <p className="m-0 text-center text-base leading-normal tracking-tight text-muted-foreground">
+          The agent that grows with you. We&rsquo;ll set things up in the
+          background &mdash; takes a few minutes.
+        </p>
+      </div>
+
+      <Button
+        onClick={() => void startInstall()}
+        size="lg"
+        className="group inline-flex items-center gap-2 px-6"
+      >
+        Install Hermes
+        <ArrowRight
+          size={18}
+          className="transition-transform group-hover:translate-x-0.5"
+        />
+      </Button>
+    </div>
+  )
+}

apps/bootstrap-installer/src/store.ts

@@ -0,0 +1,277 @@
+import { atom, computed } from 'nanostores'
+import { listen, type UnlistenFn } from '@tauri-apps/api/event'
+import { invoke } from '@tauri-apps/api/core'
+
+/*
+ * Bootstrap state store — single source of truth for installer screens.
+ *
+ * Lives in nanostores per the project's TypeScript guidelines (apps/desktop
+ * AGENTS.md): "Prefer small nanostores over component state when state is
+ * shared, reused, or read by distant UI."
+ *
+ * One channel from Rust ('bootstrap' event), discriminated by payload.type.
+ * We translate those events into typed atom updates here so the rest of
+ * the app only deals with React-friendly state.
+ */
+
+// ---------------------------------------------------------------------------
+// Types — mirror src-tauri/src/events.rs
+// ---------------------------------------------------------------------------
+
+export interface StageInfo {
+  name: string
+  title: string
+  category: string
+  needs_user_input: boolean
+}
+
+export type StageState = 'running' | 'succeeded' | 'skipped' | 'failed'
+
+export interface StageRecord {
+  info: StageInfo
+  state: StageState | null
+  durationMs?: number
+  error?: string
+}
+
+export interface BootstrapStateModel {
+  status: 'idle' | 'running' | 'completed' | 'failed'
+  protocolVersion: number | null
+  stages: Record<string, StageRecord>
+  stageOrder: string[]
+  currentStage: string | null
+  installRoot: string | null
+  error: string | null
+  logs: Array<{ stage?: string; line: string }>
+}
+
+const INITIAL: BootstrapStateModel = {
+  status: 'idle',
+  protocolVersion: null,
+  stages: {},
+  stageOrder: [],
+  currentStage: null,
+  installRoot: null,
+  error: null,
+  logs: []
+}
+
+// ---------------------------------------------------------------------------
+// Atoms
+// ---------------------------------------------------------------------------
+
+export type Route = 'welcome' | 'progress' | 'success' | 'failure'
+
+/// How the installer was launched, mirrored from src-tauri AppMode.
+/// 'install' = first-run onboarding (bare launch). 'update' = driven by the
+/// desktop app handing off via `Hermes-Setup.exe --update`.
+export type AppMode = 'install' | 'update'
+
+export const $route = atom<Route>('welcome')
+export const $mode = atom<AppMode>('install')
+export const $bootstrap = atom<BootstrapStateModel>(INITIAL)
+export const $logPath = atom<string | null>(null)
+export const $hermesHome = atom<string | null>(null)
+
+export const $progress = computed($bootstrap, (b) => {
+  const total = b.stageOrder.length
+  if (total === 0) return { done: 0, total: 0, fraction: 0 }
+  let done = 0
+  for (const name of b.stageOrder) {
+    const s = b.stages[name]?.state
+    if (s === 'succeeded' || s === 'skipped' || s === 'failed') done += 1
+  }
+  return { done, total, fraction: done / total }
+})
+
+// ---------------------------------------------------------------------------
+// Tauri event subscription
+// ---------------------------------------------------------------------------
+
+interface BootstrapManifestEvent {
+  type: 'manifest'
+  stages: StageInfo[]
+  protocolVersion: number | null
+}
+
+interface BootstrapStageEvent {
+  type: 'stage'
+  name: string
+  state: StageState
+  durationMs?: number
+  error?: string
+}
+
+interface BootstrapLogEvent {
+  type: 'log'
+  stage?: string
+  line: string
+}
+
+interface BootstrapCompleteEvent {
+  type: 'complete'
+  installRoot: string
+  marker: unknown
+}
+
+interface BootstrapFailedEvent {
+  type: 'failed'
+  stage?: string
+  error: string
+}
+
+type BootstrapEvent =
+  | BootstrapManifestEvent
+  | BootstrapStageEvent
+  | BootstrapLogEvent
+  | BootstrapCompleteEvent
+  | BootstrapFailedEvent
+
+let unlisten: UnlistenFn | null = null
+
+export async function initialize(): Promise<void> {
+  if (unlisten) return
+
+  // Pull static info on mount for the diagnostics footer.
+  try {
+    const [logPath, hermesHome, mode] = await Promise.all([
+      invoke<string>('get_log_path'),
+      invoke<string>('get_hermes_home'),
+      invoke<AppMode>('get_mode')
+    ])
+    $logPath.set(logPath)
+    $hermesHome.set(hermesHome)
+    $mode.set(mode)
+  } catch (err) {
+    console.warn('failed to fetch installer paths', err)
+  }
+
+  unlisten = await listen<BootstrapEvent>('bootstrap', (event) => {
+    const payload = event.payload
+    const cur = $bootstrap.get()
+    switch (payload.type) {
+      case 'manifest': {
+        const stages: Record<string, StageRecord> = {}
+        const order: string[] = []
+        for (const s of payload.stages) {
+          stages[s.name] = { info: s, state: null }
+          order.push(s.name)
+        }
+        $bootstrap.set({
+          ...cur,
+          status: 'running',
+          protocolVersion: payload.protocolVersion,
+          stages,
+          stageOrder: order,
+          currentStage: null,
+          installRoot: null,
+          error: null,
+          logs: []
+        })
+        $route.set('progress')
+        break
+      }
+      case 'stage': {
+        const existing = cur.stages[payload.name]
+        if (!existing) {
+          console.warn('stage event for unknown stage', payload.name)
+          break
+        }
+        const next: StageRecord = {
+          ...existing,
+          state: payload.state,
+          durationMs: payload.durationMs,
+          error: payload.error
+        }
+        $bootstrap.set({
+          ...cur,
+          stages: { ...cur.stages, [payload.name]: next },
+          currentStage:
+            payload.state === 'running' ? payload.name : cur.currentStage
+        })
+        break
+      }
+      case 'log': {
+        const logs = [...cur.logs, { stage: payload.stage, line: payload.line }]
+        // Keep the rolling buffer bounded so the UI doesn't get OOM'd
+        // during a long install (playwright chromium download is ~10k lines).
+        const trimmed = logs.length > 2000 ? logs.slice(-2000) : logs
+        $bootstrap.set({ ...cur, logs: trimmed })
+        break
+      }
+      case 'complete':
+        $bootstrap.set({
+          ...cur,
+          status: 'completed',
+          installRoot: payload.installRoot,
+          currentStage: null
+        })
+        // Install: show the "launch Hermes" success screen. Update: this is a
+        // hand-off — the installer relaunches the desktop and exits within a
+        // few hundred ms, so routing to success just flashes that screen
+        // before the window closes. Stay on progress until we exit.
+        if ($mode.get() !== 'update') {
+          $route.set('success')
+        }
+        break
+      case 'failed':
+        $bootstrap.set({
+          ...cur,
+          status: 'failed',
+          error: payload.error,
+          currentStage: null
+        })
+        $route.set('failure')
+        break
+    }
+  })
+
+  // Update mode is a hand-off, not a user-initiated flow: the desktop already
+  // exited and re-launched us as `--update`. Kick the update immediately so
+  // the user lands on progress, not a redundant "click to update" screen.
+  if ($mode.get() === 'update') {
+    void startUpdate()
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Actions
+// ---------------------------------------------------------------------------
+
+export async function startInstall(opts?: { branch?: string }): Promise<void> {
+  // Reset before kicking off so a retry from the failure screen clears
+  // the previous run's state.
+  $bootstrap.set(INITIAL)
+  $route.set('progress')
+  await invoke('start_bootstrap', {
+    args: {
+      commit: null,
+      branch: opts?.branch ?? null,
+      include_desktop: true,
+      hermes_home: null
+    }
+  })
+}
+
+export async function startUpdate(): Promise<void> {
+  // Update is driven by the desktop handing off (Hermes-Setup.exe --update);
+  // there's no welcome click. Reset + jump straight to progress, then let the
+  // Rust side stream the synthetic update manifest.
+  $bootstrap.set(INITIAL)
+  $route.set('progress')
+  await invoke('start_update')
+}
+
+export async function cancelInstall(): Promise<void> {
+  await invoke('cancel_bootstrap')
+}
+
+export async function launchHermesDesktop(): Promise<void> {
+  const installRoot = $bootstrap.get().installRoot
+  if (!installRoot) throw new Error('no install root')
+  await invoke('launch_hermes_desktop', { installRoot })
+}
+
+export async function openLogDir(): Promise<void> {
+  await invoke('open_log_dir')
+}

apps/bootstrap-installer/src/styles.css

@@ -0,0 +1,51 @@
+/*
+ * Hermes Setup — defer entirely to the desktop's styles.css.
+ *
+ * Rather than re-implement the Hermes design system (and inevitably drift
+ * from it), we import apps/desktop/src/styles.css wholesale. The desktop
+ * is the canonical source of truth for fonts, color tokens, button chrome,
+ * scrollbars, layout utilities, and animations. Any change to the
+ * Hermes look propagates here automatically with no copy-paste maintenance.
+ *
+ * Path resolution caveats:
+ *   - Tailwind v4's `@import` resolves relative to this file. The desktop's
+ *     `@source '../../../node_modules/...'` declarations therefore re-resolve
+ *     against apps/bootstrap-installer/src/. Since both apps live two levels
+ *     deep under the same repo root, `../../../node_modules` lands in the
+ *     same place. (Verify if either app ever moves.)
+ *   - The desktop's `@font-face url('../../../node_modules/...')` references
+ *     are baked into the *imported* stylesheet; CSS resolves url()s relative
+ *     to the file that contains them, so they continue to point at the
+ *     correct node_modules path even from here.
+ *
+ * Forced light mode: the desktop ships with a runtime theme switcher
+ * (ThemeProvider + applyTheme) that can flip to dark via document.documentElement.
+ * The installer has no UI for theme switching, so we stay on the desktop's
+ * default light surface (Nous-blue accent on near-white chrome).
+ */
+@import '../../desktop/src/styles.css';
+
+/* Installer-only additions: a fade-in animation and a warm radial glow
+   for the welcome screen. Everything else inherits from the desktop. */
+@keyframes hermes-fade-in {
+  from {
+    opacity: 0;
+    transform: translateY(4px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+.hermes-fade-in {
+  animation: hermes-fade-in 0.45s ease-out both;
+}
+
+.hermes-glow {
+  background: radial-gradient(
+    ellipse at center,
+    color-mix(in srgb, var(--ui-warm) 18%, transparent) 0%,
+    transparent 60%
+  );
+}

apps/bootstrap-installer/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

apps/bootstrap-installer/tsconfig.json

@@ -0,0 +1,26 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "useDefineForClassFields": true,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "esModuleInterop": true,
+    "noFallthroughCasesInSwitch": true,
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"]
+    }
+  },
+  "include": ["src"],
+  "references": [{ "path": "./tsconfig.node.json" }]
+}

apps/bootstrap-installer/tsconfig.node.json

@@ -0,0 +1,11 @@
+{
+  "compilerOptions": {
+    "composite": true,
+    "skipLibCheck": true,
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "allowSyntheticDefaultImports": true,
+    "strict": true
+  },
+  "include": ["vite.config.ts"]
+}

apps/bootstrap-installer/vite.config.ts

@@ -0,0 +1,46 @@
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import tailwindcss from '@tailwindcss/vite'
+import path from 'node:path'
+
+// Hermes Setup — Tauri-targeted Vite config.
+//
+// Port 5175 keeps us out of the way of:
+//   web       (vite default 5173)
+//   apps/desktop dev     (5174 per its package.json)
+//
+// `clearScreen: false` is the Tauri convention — they spawn vite as a child
+// process and want our errors to stay visible.
+
+const host = process.env.TAURI_DEV_HOST
+
+export default defineConfig({
+  plugins: [react(), tailwindcss()],
+  resolve: {
+    alias: {
+      '@': path.resolve(__dirname, './src')
+    }
+  },
+  clearScreen: false,
+  server: {
+    port: 5175,
+    strictPort: true,
+    host: host || '127.0.0.1',
+    hmr: host
+      ? {
+          protocol: 'ws',
+          host,
+          port: 5176
+        }
+      : undefined,
+    watch: {
+      // Don't watch the Rust side — tauri-cli handles it.
+      ignored: ['**/src-tauri/**']
+    }
+  },
+  build: {
+    target: 'esnext',
+    outDir: 'dist',
+    emptyOutDir: true
+  }
+})

apps/desktop/.prettierrc

@@ -0,0 +1,11 @@
+{
+  "arrowParens": "avoid",
+  "bracketSpacing": true,
+  "endOfLine": "auto",
+  "printWidth": 120,
+  "semi": false,
+  "singleQuote": true,
+  "tabWidth": 2,
+  "trailingComma": "none",
+  "useTabs": false
+}

apps/desktop/README.md

@@ -0,0 +1,137 @@
+# Hermes Desktop ☤
+
+<p align="center">
+  <a href="https://github.com/NousResearch/hermes-agent/releases"><img src="https://img.shields.io/badge/Download-macOS%20%C2%B7%20Windows%20%C2%B7%20Linux-FFD700?style=for-the-badge" alt="Download"></a>
+  <a href="https://hermes-agent.nousresearch.com/docs/"><img src="https://img.shields.io/badge/Docs-hermes--agent.nousresearch.com-FFD700?style=for-the-badge" alt="Documentation"></a>
+  <a href="https://discord.gg/NousResearch"><img src="https://img.shields.io/badge/Discord-5865F2?style=for-the-badge&logo=discord&logoColor=white" alt="Discord"></a>
+  <a href="https://github.com/NousResearch/hermes-agent/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-green?style=for-the-badge" alt="License: MIT"></a>
+</p>
+
+**The native desktop app for [Hermes Agent](../../README.md) — the self-improving AI agent from [Nous Research](https://nousresearch.com).** Same agent, same skills, same memory as the CLI and gateway, in a polished native window — chat with streaming tool output, side-by-side previews, a file browser, voice, and settings, no terminal required. Available for **macOS, Windows, and Linux**.
+
+<table>
+<tr><td><b>Chat with the full agent</b></td><td>Streaming responses, live tool activity, structured tool summaries, and the same conversation history as every other Hermes surface.</td></tr>
+<tr><td><b>Side-by-side previews</b></td><td>Render web pages, files, and tool outputs in a right-hand pane while you keep chatting.</td></tr>
+<tr><td><b>File browser</b></td><td>Explore and preview the working directory without leaving the app.</td></tr>
+<tr><td><b>Voice</b></td><td>Talk to Hermes and hear it back.</td></tr>
+<tr><td><b>Settings & onboarding</b></td><td>Manage providers, models, tools, and credentials from a real UI. First-run setup gets you to your first message in seconds.</td></tr>
+<tr><td><b>Stays current</b></td><td>Built-in updates pull the latest agent and rebuild the app in place.</td></tr>
+</table>
+
+---
+
+## Install
+
+### Install with Hermes (recommended)
+
+Add `--include-desktop` to the [one-line installer](../../README.md#quick-install) and it sets up the agent and builds the desktop app in one go:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash -s -- --include-desktop
+```
+
+Already have the Hermes CLI? Just run:
+
+```bash
+hermes desktop
+```
+
+It builds and launches the GUI against your existing install — same config, keys, sessions, and skills. On first launch Hermes walks you through picking a provider and model; nothing else to configure.
+
+### Prebuilt installers
+
+When a release ships desktop installers they're attached to its [releases page](https://github.com/NousResearch/hermes-agent/releases) — `.dmg` (macOS), `.exe` / `.msi` (Windows), `.AppImage` / `.deb` / `.rpm` (Linux). These are published manually, so the install-with-Hermes path above is the most reliable way to get the latest.
+
+---
+
+## Updating
+
+The app checks for updates in the background and offers a one-click update when one is ready. You can also update any time from the CLI:
+
+```bash
+hermes update
+```
+
+---
+
+## Requirements
+
+The installer handles everything for you (Python 3.11+, a portable Git, ripgrep). The only thing worth knowing:
+
+- **Windows** — the installer bundles its own Git and Python; no admin rights or system changes required.
+- **macOS / Linux** — uses your system Python 3.11+ (installed automatically if missing).
+
+---
+
+## Development
+
+Want to hack on the app itself? Install workspace deps from the repo root once, then run the dev server from this directory:
+
+```bash
+npm install          # from repo root — links apps/desktop, web, apps/shared
+cd apps/desktop
+npm run dev          # Vite renderer + Electron, which boots the Python backend
+```
+
+Point the app at a specific source checkout, or sandbox it away from your real config:
+
+```bash
+HERMES_DESKTOP_HERMES_ROOT=/path/to/clone npm run dev
+HERMES_HOME=/tmp/throwaway npm run dev
+npm run dev:fake-boot   # exercise the startup overlay with deterministic delays
+```
+
+### Building installers
+
+```bash
+npm run dist:mac     # DMG + zip
+npm run dist:win     # NSIS + MSI
+npm run dist:linux   # AppImage + deb + rpm
+npm run pack         # unpacked app under release/ (no installer)
+```
+
+Installers are built and uploaded to GitHub Releases manually. macOS/Windows signing & notarization happen automatically when the relevant credentials are present in the environment (`CSC_LINK` / `CSC_KEY_PASSWORD` / `APPLE_*` for macOS, `WIN_CSC_*` for Windows).
+
+### How it works
+
+The packaged app ships only the Electron shell. On first launch it installs the Hermes Agent runtime into `HERMES_HOME` (`~/.hermes`, or `%LOCALAPPDATA%\hermes` on Windows) — the **same layout a CLI install uses**, so the two are interchangeable. The renderer (React, in `src/`) talks to a `hermes dashboard --tui` backend over the standard gateway APIs and reuses the embedded TUI rather than reimplementing chat. The install, backend-resolution, and self-update logic all live in `electron/main.cjs`.
+
+### Verification
+
+Run before opening a PR (lint may surface pre-existing warnings but must exit cleanly):
+
+```bash
+npm run fix
+npm run type-check
+npm run lint
+npm run test:desktop:all
+```
+
+### Troubleshooting
+
+Boot logs land in `HERMES_HOME/logs/desktop.log` (includes backend output and recent Python tracebacks) — check it first if the app reports a boot failure.
+
+```bash
+# Force a clean first-launch setup
+rm "$HOME/.hermes/hermes-agent/.hermes-bootstrap-complete"   # macOS/Linux
+# Rebuild a broken Python venv
+rm -rf "$HOME/.hermes/hermes-agent/venv"                     # macOS/Linux
+# Reset a stuck macOS microphone prompt
+tccutil reset Microphone com.nousresearch.hermes
+```
+
+---
+
+## Community
+
+- 💬 [Discord](https://discord.gg/NousResearch)
+- 📖 [Documentation](https://hermes-agent.nousresearch.com/docs/)
+- 🐛 [Issues](https://github.com/NousResearch/hermes-agent/issues)
+
+---
+
+## License
+
+MIT — see [LICENSE](../../LICENSE).
+
+Built by [Nous Research](https://nousresearch.com).

apps/desktop/components.json

@@ -0,0 +1,21 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": false,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "src/styles.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  },
+  "iconLibrary": "lucide"
+}

apps/desktop/electron/backend-probes.cjs

@@ -0,0 +1,106 @@
+/**
+ * backend-probes.cjs
+ *
+ * Cheap "does this candidate backend actually work" checks used by
+ * resolveHermesBackend (main.cjs). The resolver walks a ladder of
+ * candidates -- bootstrap marker, `hermes` on PATH, system Python with
+ * hermes_cli installed -- and historically returned the first candidate
+ * whose binary existed on disk. That assumption breaks when a user has
+ * a pre-installed Python 3.11-3.13 (so findSystemPython() returns a
+ * path) but no hermes_cli in its site-packages: the resolver hands back
+ * a backend the spawn step can't actually run, and the user gets a
+ * dead-on-arrival "ModuleNotFoundError: No module named 'hermes_cli'"
+ * instead of the first-launch installer.
+ *
+ * These probes give the resolver a way to verify a candidate before
+ * trusting it. Failure (non-zero exit, exception, timeout) means "skip
+ * this rung, try the next one"; success means "spawn this for real."
+ * Falling off the bottom of the ladder lands on the bootstrap-needed
+ * sentinel, which is exactly what we want when nothing pre-existing
+ * actually works.
+ *
+ * Both probes are deliberately fast and forgiving:
+ *   - 5s timeout (a hung interpreter beats forever, but we still give
+ *     slow disks / cold caches room to breathe)
+ *   - stdio ignored (we only care about exit code; stdout/stderr are
+ *     not surfaced to the user, just to recentHermesLog for forensics
+ *     via the caller's catch block if it chooses)
+ *   - any throw -> false (never propagate -- resolver wants a boolean)
+ *
+ * Kept in a standalone cjs module so it can be unit-tested with
+ * `node --test` without dragging in the electron runtime (same pattern
+ * as bootstrap-platform.cjs and hardening.cjs).
+ */
+
+const { execFileSync } = require('node:child_process')
+
+const PROBE_TIMEOUT_MS = 5000
+
+/**
+ * Return true iff `python -c "import hermes_cli"` exits 0.
+ *
+ * Used to gate the "fallback to system Python with hermes_cli installed"
+ * rung of resolveHermesBackend. Without this, a system Python 3.11-3.13
+ * registered in PEP 514 makes findSystemPython() succeed regardless of
+ * whether hermes_cli has actually been pip-installed into its
+ * site-packages -- and the resolver returns a backend that immediately
+ * dies on spawn.
+ *
+ * @param {string} pythonPath - Absolute path to a python.exe / python.
+ * @returns {boolean}
+ */
+function canImportHermesCli(pythonPath) {
+  if (!pythonPath) return false
+  try {
+    execFileSync(pythonPath, ['-c', 'import hermes_cli'], {
+      stdio: 'ignore',
+      timeout: PROBE_TIMEOUT_MS,
+      windowsHide: true
+    })
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Return true iff `<hermesCommand> --version` exits 0.
+ *
+ * Used to gate the "existing `hermes` on PATH" rung. Without this, a
+ * stale hermes.cmd shim left behind by an uninstalled pip install (or
+ * a half-built venv whose `hermes` entry-point points at a deleted
+ * Python) survives findOnPath() and gets selected as the backend.
+ *
+ * We intentionally avoid invoking the command with the dashboard args
+ * here -- `--version` is the cheapest "is this binary alive" smoke
+ * test that every hermes_cli entry-point has supported since 0.1.
+ *
+ * @param {string} hermesCommand - Resolved absolute path to a hermes
+ *   executable (or an interpreter+script wrapper).
+ * @param {object} [opts]
+ * @param {boolean} [opts.shell] - Whether to run through a shell. For
+ *   .cmd/.bat shims on Windows execFileSync needs shell:true to find
+ *   the cmd interpreter; mirrors the same flag isCommandScript() drives
+ *   in resolveHermesBackend.
+ * @returns {boolean}
+ */
+function verifyHermesCli(hermesCommand, opts = {}) {
+  if (!hermesCommand) return false
+  try {
+    execFileSync(hermesCommand, ['--version'], {
+      stdio: 'ignore',
+      timeout: PROBE_TIMEOUT_MS,
+      shell: Boolean(opts.shell),
+      windowsHide: true
+    })
+    return true
+  } catch {
+    return false
+  }
+}
+
+module.exports = {
+  canImportHermesCli,
+  verifyHermesCli,
+  PROBE_TIMEOUT_MS
+}

apps/desktop/electron/backend-probes.test.cjs

@@ -0,0 +1,80 @@
+/**
+ * Tests for electron/backend-probes.cjs.
+ *
+ * Run with: node --test electron/backend-probes.test.cjs
+ * (Wired into npm test:desktop:platforms in package.json.)
+ */
+
+const test = require('node:test')
+const assert = require('node:assert/strict')
+const fs = require('node:fs')
+const os = require('node:os')
+const path = require('node:path')
+
+const { canImportHermesCli, verifyHermesCli } = require('./backend-probes.cjs')
+
+// Resolve the host's own Node binary -- guaranteed to be on disk and
+// runnable. We use it as both a stand-in for "a python that doesn't
+// have hermes_cli" (since `node -c "import hermes_cli"` will exit
+// non-zero) and as a way to script verifyHermesCli's success path
+// (a tiny script we write to disk that exits 0 on --version).
+const NODE_BIN = process.execPath
+
+test('canImportHermesCli returns false when path is falsy', () => {
+  assert.equal(canImportHermesCli(''), false)
+  assert.equal(canImportHermesCli(null), false)
+  assert.equal(canImportHermesCli(undefined), false)
+})
+
+test('canImportHermesCli returns false when interpreter cannot run -c', () => {
+  // node IS an interpreter, but `node -c "import hermes_cli"` is a
+  // SyntaxError -- different exit reason from a real Python's
+  // ModuleNotFoundError, but the predicate is "exit 0 or not" and
+  // both land on "not", which is exactly what we want for the
+  // resolver fall-through.
+  assert.equal(canImportHermesCli(NODE_BIN), false)
+})
+
+test('canImportHermesCli returns false when binary does not exist', () => {
+  const ghost = path.join(os.tmpdir(), 'hermes-probes-ghost-' + Date.now() + '.exe')
+  assert.equal(canImportHermesCli(ghost), false)
+})
+
+test('verifyHermesCli returns false when command is falsy', () => {
+  assert.equal(verifyHermesCli(''), false)
+  assert.equal(verifyHermesCli(null), false)
+  assert.equal(verifyHermesCli(undefined), false)
+})
+
+test('verifyHermesCli returns false when binary does not exist', () => {
+  const ghost = path.join(os.tmpdir(), 'hermes-probes-ghost-' + Date.now() + '.exe')
+  assert.equal(verifyHermesCli(ghost), false)
+})
+
+test('verifyHermesCli returns true when --version exits 0', () => {
+  // Write a tiny script that exits 0 regardless of args, then invoke
+  // it through node. This stands in for a working hermes binary --
+  // verifyHermesCli only cares about the exit code.
+  const scriptPath = path.join(os.tmpdir(), `hermes-probes-ok-${Date.now()}-${process.pid}.cjs`)
+  fs.writeFileSync(scriptPath, 'process.exit(0)\n')
+  try {
+    // Use node as the launcher and our script as the "command". Pass
+    // shell:false (default) -- node is a real binary, no shim.
+    // execFileSync passes ['--version'] as args, which node ignores
+    // gracefully (well, it prints its version and exits 0, which is
+    // perfect -- exit code 0 is the only signal we read).
+    assert.equal(verifyHermesCli(NODE_BIN), true)
+  } finally {
+    try {
+      fs.unlinkSync(scriptPath)
+    } catch {}
+  }
+})
+
+test('verifyHermesCli swallows timeouts (does not throw)', () => {
+  // We can't easily provoke a real 5s hang in CI without slowing the
+  // suite, but we CAN confirm that an invocation that DOES throw
+  // (because the binary is missing) returns false rather than
+  // propagating. Same code path the timeout case takes.
+  assert.equal(verifyHermesCli('/definitely/not/a/real/binary/anywhere'), false)
+})

apps/desktop/electron/bootstrap-platform.cjs

@@ -0,0 +1,39 @@
+const fs = require('node:fs')
+
+function isWslEnvironment(env = process.env, platform = process.platform, kernelRelease = null) {
+  if (platform !== 'linux') return false
+  if (env.WSL_DISTRO_NAME || env.WSL_INTEROP) return true
+
+  try {
+    const release = kernelRelease ?? fs.readFileSync('/proc/sys/kernel/osrelease', 'utf8')
+    return /microsoft|wsl/i.test(release)
+  } catch {
+    return false
+  }
+}
+
+function isWindowsBinaryPathInWsl(filePath, options = {}) {
+  const isWsl = options.isWsl ?? isWslEnvironment(options.env, options.platform)
+  if (!isWsl) return false
+
+  const normalized = String(filePath || '')
+    .replace(/\\/g, '/')
+    .toLowerCase()
+
+  return (
+    normalized.endsWith('.exe') ||
+    normalized.endsWith('.cmd') ||
+    normalized.endsWith('.bat') ||
+    normalized.endsWith('.ps1')
+  )
+}
+
+function bundledRuntimeImportCheck(platform = process.platform) {
+  return platform === 'win32' ? 'import fastapi, uvicorn, winpty' : 'import fastapi, uvicorn, ptyprocess'
+}
+
+module.exports = {
+  bundledRuntimeImportCheck,
+  isWindowsBinaryPathInWsl,
+  isWslEnvironment
+}

apps/desktop/electron/bootstrap-platform.test.cjs

@@ -0,0 +1,53 @@
+const assert = require('node:assert/strict')
+const fs = require('node:fs')
+const path = require('node:path')
+const test = require('node:test')
+
+const { bundledRuntimeImportCheck, isWindowsBinaryPathInWsl, isWslEnvironment } = require('./bootstrap-platform.cjs')
+
+test('isWslEnvironment detects WSL2 env vars on linux', () => {
+  assert.equal(isWslEnvironment({ WSL_DISTRO_NAME: 'Ubuntu' }, 'linux'), true)
+  assert.equal(isWslEnvironment({ WSL_INTEROP: '/run/WSL/123_interop' }, 'linux'), true)
+  assert.equal(isWslEnvironment({}, 'linux', '6.6.87.2-microsoft-standard-WSL2'), true)
+  assert.equal(isWslEnvironment({}, 'linux', '6.6.87-generic'), false)
+  assert.equal(isWslEnvironment({ WSL_DISTRO_NAME: 'Ubuntu' }, 'darwin'), false)
+})
+
+test('isWindowsBinaryPathInWsl blocks Windows binary types on WSL', () => {
+  assert.equal(isWindowsBinaryPathInWsl('/mnt/c/Tools/hermes.exe', { isWsl: true }), true)
+  assert.equal(isWindowsBinaryPathInWsl('/mnt/c/Tools/hermes.cmd', { isWsl: true }), true)
+  assert.equal(isWindowsBinaryPathInWsl('/mnt/c/Tools/hermes.bat', { isWsl: true }), true)
+  assert.equal(isWindowsBinaryPathInWsl('/mnt/c/Tools/install.ps1', { isWsl: true }), true)
+  assert.equal(isWindowsBinaryPathInWsl('/usr/local/bin/hermes', { isWsl: true }), false)
+  assert.equal(isWindowsBinaryPathInWsl('/mnt/c/Tools/hermes.exe', { isWsl: false }), false)
+})
+
+test('bundledRuntimeImportCheck selects platform-specific import checks', () => {
+  assert.equal(bundledRuntimeImportCheck('win32'), 'import fastapi, uvicorn, winpty')
+  assert.equal(bundledRuntimeImportCheck('darwin'), 'import fastapi, uvicorn, ptyprocess')
+  assert.equal(bundledRuntimeImportCheck('linux'), 'import fastapi, uvicorn, ptyprocess')
+})
+
+test('packaged electron entrypoints do not require unpackaged npm modules', () => {
+  const electronDir = __dirname
+  const entrypoints = ['main.cjs', 'preload.cjs', 'bootstrap-platform.cjs']
+  // - electron: provided by the electron runtime, always resolvable in packaged builds.
+  // - node-pty: hoisted by workspace dedup AND shipped via extraResources to
+  //   resources/native-deps/node-pty (see scripts/stage-native-deps.cjs). main.cjs
+  //   has a try/catch fallback at line ~38 that resolves the staged copy when the
+  //   bare require fails in the packaged asar, so the bare require itself is by
+  //   design rather than an oversight.
+  const allowedBareRequires = new Set(['electron', 'node-pty'])
+  const requirePattern = /require\(['"]([^'"]+)['"]\)/g
+
+  for (const entrypoint of entrypoints) {
+    const source = fs.readFileSync(path.join(electronDir, entrypoint), 'utf8')
+    const bareRequires = Array.from(source.matchAll(requirePattern))
+      .map(match => match[1])
+      .filter(specifier => !specifier.startsWith('node:'))
+      .filter(specifier => !specifier.startsWith('.'))
+      .filter(specifier => !allowedBareRequires.has(specifier))
+
+    assert.deepEqual(bareRequires, [], `${entrypoint} has unpackaged runtime requires`)
+  }
+})

apps/desktop/electron/bootstrap-runner.cjs

@@ -0,0 +1,579 @@
+'use strict'
+
+/**
+ * bootstrap-runner.cjs
+ *
+ * Drives apps/desktop's first-launch install of Hermes Agent by spawning
+ * scripts/install.ps1 stage-by-stage and streaming progress events back to
+ * the renderer.
+ *
+ * Wired from electron/main.cjs:
+ *   const { runBootstrap } = require('./bootstrap-runner.cjs')
+ *   const result = await runBootstrap({
+ *     installStamp,        // INSTALL_STAMP from main.cjs (may be null in dev)
+ *     activeRoot,          // ACTIVE_HERMES_ROOT
+ *     sourceRepoRoot,      // SOURCE_REPO_ROOT (for dev install.ps1 lookup)
+ *     hermesHome,          // HERMES_HOME
+ *     logRoot,             // HERMES_HOME/logs
+ *     emit: ev => {...}    // event sink (sender.send or similar)
+ *   })
+ *
+ * Emits events with shape:
+ *   { type: 'manifest',  stages: [{name, title, category, needs_user_input}, ...] }
+ *   { type: 'stage',     name, state: 'running'|'succeeded'|'skipped'|'failed',
+ *                        json?, durationMs?, error? }
+ *   { type: 'log',       stage?, line }      // raw line from install.ps1
+ *   { type: 'complete',  marker: <written marker payload> }
+ *   { type: 'failed',    stage?, error }     // bootstrap aborted
+ *
+ * Resolves with the same shape as the final 'complete' or 'failed' event so
+ * callers can await either way.
+ *
+ * NOT implemented yet (deferred to Phase 1E / 1F):
+ *   - User-facing retry / cancel from the renderer (event channels exist;
+ *     no UI consumes them yet)
+ */
+
+const fs = require('node:fs')
+const fsp = require('node:fs/promises')
+const path = require('node:path')
+const https = require('node:https')
+const { spawn } = require('node:child_process')
+
+const STAMP_COMMIT_RE = /^[0-9a-f]{7,40}$/i
+
+// Stages flagged needs_user_input=true in the manifest are skipped by the
+// runner (passed -NonInteractive to install.ps1, which the install script
+// itself handles by emitting skipped=true frames). The renderer / 1E onboarding
+// overlay takes over for those concerns (API keys, model, persona, gateway).
+// We let install.ps1's own -NonInteractive logic drive this rather than
+// filtering client-side -- single source of truth.
+
+// ---------------------------------------------------------------------------
+// install.ps1 source resolution
+// ---------------------------------------------------------------------------
+
+function installScriptName() {
+  return process.platform === 'win32' ? 'install.ps1' : 'install.sh'
+}
+
+function installScriptKind() {
+  return process.platform === 'win32' ? 'powershell' : 'posix'
+}
+
+function resolveLocalInstallScript(sourceRepoRoot) {
+  if (!sourceRepoRoot) return null
+  const candidate = path.join(sourceRepoRoot, 'scripts', installScriptName())
+  try {
+    fs.accessSync(candidate, fs.constants.R_OK)
+    return candidate
+  } catch {
+    return null
+  }
+}
+
+function bootstrapCacheDir(hermesHome) {
+  return path.join(hermesHome, 'bootstrap-cache')
+}
+
+function cachedScriptPath(hermesHome, commit) {
+  return path.join(bootstrapCacheDir(hermesHome), `install-${commit}.${process.platform === 'win32' ? 'ps1' : 'sh'}`)
+}
+
+function downloadInstallScript(commit, destPath) {
+  // Fetch from GitHub raw at the pinned commit. The raw URL with a SHA
+  // is immutable (unlike a branch ref), so we don't need integrity
+  // verification beyond "did the file we wrote pass a syntax probe."
+  const scriptName = installScriptName()
+  const url = `https://raw.githubusercontent.com/NousResearch/hermes-agent/${commit}/scripts/${scriptName}`
+  return new Promise((resolve, reject) => {
+    fs.mkdirSync(path.dirname(destPath), { recursive: true })
+    const tmpPath = destPath + '.tmp'
+    const out = fs.createWriteStream(tmpPath)
+    https
+      .get(url, res => {
+        if (res.statusCode === 301 || res.statusCode === 302) {
+          // GitHub raw shouldn't redirect for a SHA URL, but follow once
+          // defensively.
+          out.close()
+          fs.unlinkSync(tmpPath)
+          https
+            .get(res.headers.location, res2 => {
+              if (res2.statusCode !== 200) {
+                reject(
+                  new Error(`Failed to download ${scriptName}: HTTP ${res2.statusCode} from redirect ${res.headers.location}`)
+                )
+                return
+              }
+              const out2 = fs.createWriteStream(tmpPath)
+              res2.pipe(out2)
+              out2.on('finish', () => {
+                out2.close()
+                fs.renameSync(tmpPath, destPath)
+                resolve(destPath)
+              })
+              out2.on('error', reject)
+            })
+            .on('error', reject)
+          return
+        }
+        if (res.statusCode !== 200) {
+          out.close()
+          try {
+            fs.unlinkSync(tmpPath)
+          } catch {}
+          reject(new Error(`Failed to download ${scriptName}: HTTP ${res.statusCode} from ${url}`))
+          return
+        }
+        res.pipe(out)
+        out.on('finish', () => {
+          out.close()
+          fs.renameSync(tmpPath, destPath)
+          resolve(destPath)
+        })
+        out.on('error', err => {
+          try {
+            fs.unlinkSync(tmpPath)
+          } catch {}
+          reject(err)
+        })
+      })
+      .on('error', err => {
+        try {
+          fs.unlinkSync(tmpPath)
+        } catch {}
+        reject(err)
+      })
+  })
+}
+
+async function resolveInstallScript({ installStamp, sourceRepoRoot, hermesHome, emit }) {
+  // 1. Dev shortcut: prefer a local checkout's installer so we can iterate
+  //    without pushing. SOURCE_REPO_ROOT comes from main.cjs (path.resolve
+  //    of APP_ROOT/../..).
+  const localScript = resolveLocalInstallScript(sourceRepoRoot)
+  if (localScript) {
+    emit({ type: 'log', line: `[bootstrap] using local ${installScriptName()} at ${localScript}` })
+    return { path: localScript, source: 'local', kind: installScriptKind() }
+  }
+
+  // 2. Packaged path: download from GitHub at the pinned commit (1B's stamp).
+  if (!installStamp || !installStamp.commit || !STAMP_COMMIT_RE.test(installStamp.commit)) {
+    throw new Error(
+      `Cannot resolve ${installScriptName()}: no SOURCE_REPO_ROOT and no install stamp. ` +
+        'This packaged build was produced without a valid build-time stamp.'
+    )
+  }
+
+  const cached = cachedScriptPath(hermesHome, installStamp.commit)
+  try {
+    await fsp.access(cached, fs.constants.R_OK)
+    emit({ type: 'log', line: `[bootstrap] using cached ${installScriptName()} for ${installStamp.commit.slice(0, 12)}` })
+    return { path: cached, source: 'cache', commit: installStamp.commit, kind: installScriptKind() }
+  } catch {
+    // not cached; download
+  }
+
+  emit({ type: 'log', line: `[bootstrap] fetching ${installScriptName()} for ${installStamp.commit.slice(0, 12)} from GitHub` })
+  await downloadInstallScript(installStamp.commit, cached)
+  emit({ type: 'log', line: `[bootstrap] saved to ${cached}` })
+  return { path: cached, source: 'download', commit: installStamp.commit, kind: installScriptKind() }
+}
+
+// ---------------------------------------------------------------------------
+// powershell wrapper
+// ---------------------------------------------------------------------------
+
+function spawnPowerShell(scriptPath, args, { emit, stageName, abortSignal, hermesHome } = {}) {
+  return new Promise((resolve, reject) => {
+    const ps = process.platform === 'win32' ? 'powershell.exe' : 'pwsh'
+    const fullArgs = ['-NoProfile', '-ExecutionPolicy', 'Bypass', '-File', scriptPath, ...args]
+
+    const child = spawn(ps, fullArgs, {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: {
+        ...process.env,
+        // Pass HERMES_HOME through so install.ps1 respects the caller's
+        // choice rather than re-computing the default.
+        HERMES_HOME: hermesHome || process.env.HERMES_HOME || ''
+      }
+    })
+
+    let stdout = ''
+    let stderr = ''
+    let killed = false
+
+    const onAbort = () => {
+      killed = true
+      try {
+        child.kill('SIGTERM')
+      } catch {}
+    }
+    if (abortSignal) {
+      if (abortSignal.aborted) {
+        onAbort()
+      } else {
+        abortSignal.addEventListener('abort', onAbort, { once: true })
+      }
+    }
+
+    child.stdout.setEncoding('utf8')
+    child.stderr.setEncoding('utf8')
+
+    // Stream stdout line-by-line so the renderer sees progress in real time.
+    let stdoutBuf = ''
+    child.stdout.on('data', chunk => {
+      stdout += chunk
+      stdoutBuf += chunk
+      let nl
+      while ((nl = stdoutBuf.indexOf('\n')) !== -1) {
+        const line = stdoutBuf.slice(0, nl).replace(/\r$/, '')
+        stdoutBuf = stdoutBuf.slice(nl + 1)
+        if (line) emit && emit({ type: 'log', stage: stageName, line })
+      }
+    })
+
+    let stderrBuf = ''
+    child.stderr.on('data', chunk => {
+      stderr += chunk
+      stderrBuf += chunk
+      let nl
+      while ((nl = stderrBuf.indexOf('\n')) !== -1) {
+        const line = stderrBuf.slice(0, nl).replace(/\r$/, '')
+        stderrBuf = stderrBuf.slice(nl + 1)
+        if (line) emit && emit({ type: 'log', stage: stageName, line: `stderr: ${line}` })
+      }
+    })
+
+    child.on('error', err => {
+      if (abortSignal) abortSignal.removeEventListener('abort', onAbort)
+      reject(err)
+    })
+
+    child.on('close', (code, signal) => {
+      if (abortSignal) abortSignal.removeEventListener('abort', onAbort)
+      // Flush any trailing bytes
+      if (stdoutBuf) emit && emit({ type: 'log', stage: stageName, line: stdoutBuf })
+      if (stderrBuf) emit && emit({ type: 'log', stage: stageName, line: `stderr: ${stderrBuf}` })
+      resolve({ stdout, stderr, code, signal, killed })
+    })
+  })
+}
+
+function spawnBash(scriptPath, args, { emit, stageName, abortSignal, hermesHome } = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn('bash', [scriptPath, ...args], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: {
+        ...process.env,
+        HERMES_HOME: hermesHome || process.env.HERMES_HOME || ''
+      }
+    })
+
+    let stdout = ''
+    let stderr = ''
+    let killed = false
+
+    const onAbort = () => {
+      killed = true
+      try {
+        child.kill('SIGTERM')
+      } catch {}
+    }
+    if (abortSignal) {
+      if (abortSignal.aborted) {
+        onAbort()
+      } else {
+        abortSignal.addEventListener('abort', onAbort, { once: true })
+      }
+    }
+
+    child.stdout.setEncoding('utf8')
+    child.stderr.setEncoding('utf8')
+
+    let stdoutBuf = ''
+    child.stdout.on('data', chunk => {
+      stdout += chunk
+      stdoutBuf += chunk
+      let nl
+      while ((nl = stdoutBuf.indexOf('\n')) !== -1) {
+        const line = stdoutBuf.slice(0, nl).replace(/\r$/, '')
+        stdoutBuf = stdoutBuf.slice(nl + 1)
+        if (line) emit && emit({ type: 'log', stage: stageName, line })
+      }
+    })
+
+    let stderrBuf = ''
+    child.stderr.on('data', chunk => {
+      stderr += chunk
+      stderrBuf += chunk
+      let nl
+      while ((nl = stderrBuf.indexOf('\n')) !== -1) {
+        const line = stderrBuf.slice(0, nl).replace(/\r$/, '')
+        stderrBuf = stderrBuf.slice(nl + 1)
+        if (line) emit && emit({ type: 'log', stage: stageName, line: `stderr: ${line}` })
+      }
+    })
+
+    child.on('error', err => {
+      if (abortSignal) abortSignal.removeEventListener('abort', onAbort)
+      reject(err)
+    })
+
+    child.on('close', (code, signal) => {
+      if (abortSignal) abortSignal.removeEventListener('abort', onAbort)
+      if (stdoutBuf) emit && emit({ type: 'log', stage: stageName, line: stdoutBuf })
+      if (stderrBuf) emit && emit({ type: 'log', stage: stageName, line: `stderr: ${stderrBuf}` })
+      resolve({ stdout, stderr, code, signal, killed })
+    })
+  })
+}
+
+// ---------------------------------------------------------------------------
+// Manifest + stage dispatch
+// ---------------------------------------------------------------------------
+
+// Build the install.ps1 pin args (-Commit / -Branch) from the install-stamp
+// so the repository stage clones the exact SHA the .exe was tested with
+// instead of falling back to install.ps1's default ($Branch = "main").
+function buildPinArgs(installStamp) {
+  const args = []
+  if (installStamp && installStamp.commit) {
+    args.push('-Commit', installStamp.commit)
+  }
+  if (installStamp && installStamp.branch) {
+    args.push('-Branch', installStamp.branch)
+  }
+  return args
+}
+
+function buildPosixPinArgs({ installStamp, activeRoot, hermesHome }) {
+  const args = ['--dir', activeRoot, '--hermes-home', hermesHome]
+  if (installStamp && installStamp.branch) {
+    args.push('--branch', installStamp.branch)
+  }
+  if (installStamp && installStamp.commit) {
+    args.push('--commit', installStamp.commit)
+  }
+  return args
+}
+
+async function fetchManifest({ scriptPath, installerKind, emit, hermesHome, activeRoot, installStamp }) {
+  const isPosix = installerKind === 'posix'
+  const args = isPosix
+    ? ['--manifest', ...buildPosixPinArgs({ installStamp, activeRoot, hermesHome })]
+    : ['-Manifest', ...buildPinArgs(installStamp)]
+  const result = await (isPosix ? spawnBash : spawnPowerShell)(scriptPath, args, {
+    emit,
+    stageName: '__manifest__',
+    hermesHome
+  })
+  if (result.code !== 0) {
+    throw new Error(`${isPosix ? 'install.sh --manifest' : 'install.ps1 -Manifest'} failed: exit ${result.code}\n${result.stderr || result.stdout}`)
+  }
+  // The manifest is the LAST JSON line on stdout (install.ps1 may print
+  // banner / info lines first depending on Console.OutputEncoding effects).
+  // Find the last line that parses as JSON with a `stages` field.
+  const lines = result.stdout.split(/\r?\n/).filter(Boolean)
+  for (let i = lines.length - 1; i >= 0; i--) {
+    try {
+      const parsed = JSON.parse(lines[i])
+      if (parsed && Array.isArray(parsed.stages)) {
+        return parsed
+      }
+    } catch {}
+  }
+  throw new Error(`${isPosix ? 'install.sh --manifest' : 'install.ps1 -Manifest'} produced no parseable JSON payload\n${result.stdout}`)
+}
+
+// Parse the JSON result frame from a stage run. The protocol guarantees
+// exactly one JSON line per stage in -Json or -Stage mode (post #27224 fix
+// for the double-emit bug we addressed in the install.ps1 PR).
+function parseStageResult(stdout) {
+  const lines = stdout.split(/\r?\n/).filter(Boolean)
+  for (let i = lines.length - 1; i >= 0; i--) {
+    try {
+      const parsed = JSON.parse(lines[i])
+      if (parsed && typeof parsed.ok === 'boolean' && typeof parsed.stage === 'string') {
+        return parsed
+      }
+    } catch {}
+  }
+  return null
+}
+
+async function runStage({ scriptPath, installerKind, stage, emit, hermesHome, activeRoot, abortSignal, installStamp }) {
+  const startedAt = Date.now()
+  emit({ type: 'stage', name: stage.name, state: 'running' })
+
+  const isPosix = installerKind === 'posix'
+  const args = isPosix
+    ? ['--stage', stage.name, '--non-interactive', '--json', ...buildPosixPinArgs({ installStamp, activeRoot, hermesHome })]
+    : ['-Stage', stage.name, '-NonInteractive', '-Json', ...buildPinArgs(installStamp)]
+  const result = await (isPosix ? spawnBash : spawnPowerShell)(
+    scriptPath,
+    args,
+    { emit, stageName: stage.name, abortSignal, hermesHome }
+  )
+
+  const durationMs = Date.now() - startedAt
+
+  if (result.killed) {
+    const ev = { type: 'stage', name: stage.name, state: 'failed', durationMs, error: 'cancelled by user' }
+    emit(ev)
+    return ev
+  }
+
+  const json = parseStageResult(result.stdout)
+
+  if (!json) {
+    const ev = {
+      type: 'stage',
+      name: stage.name,
+      state: 'failed',
+      durationMs,
+      error: `${isPosix ? 'install.sh --stage' : 'install.ps1 -Stage'} ${stage.name} produced no JSON result frame (exit=${result.code})`,
+      json: null
+    }
+    emit(ev)
+    return ev
+  }
+
+  if (json.ok && json.skipped) {
+    const ev = { type: 'stage', name: stage.name, state: 'skipped', durationMs, json }
+    emit(ev)
+    return ev
+  }
+  if (json.ok) {
+    const ev = { type: 'stage', name: stage.name, state: 'succeeded', durationMs, json }
+    emit(ev)
+    return ev
+  }
+  const ev = { type: 'stage', name: stage.name, state: 'failed', durationMs, json, error: json.reason || `exit code ${result.code}` }
+  emit(ev)
+  return ev
+}
+
+// ---------------------------------------------------------------------------
+// Per-run log file
+// ---------------------------------------------------------------------------
+
+function openRunLog(logRoot) {
+  fs.mkdirSync(logRoot, { recursive: true })
+  const ts = new Date().toISOString().replace(/[:.]/g, '-')
+  const logPath = path.join(logRoot, `bootstrap-${ts}.log`)
+  const stream = fs.createWriteStream(logPath, { flags: 'a' })
+  return { path: logPath, stream }
+}
+
+// ---------------------------------------------------------------------------
+// Public entrypoint
+// ---------------------------------------------------------------------------
+
+async function runBootstrap(opts) {
+  const {
+    installStamp,
+    activeRoot,
+    sourceRepoRoot,
+    hermesHome,
+    logRoot,
+    onEvent,
+    abortSignal,
+    writeMarker // callback to write the bootstrap-complete marker; main.cjs provides
+  } = opts
+
+  const runLog = openRunLog(logRoot || path.join(hermesHome, 'logs'))
+
+  // Tee every event to the runLog AND the caller's onEvent. This gives us a
+  // forensic trail per bootstrap run AND lets the renderer subscribe live.
+  const emit = ev => {
+    try {
+      runLog.stream.write(JSON.stringify(ev) + '\n')
+    } catch {}
+    try {
+      if (typeof onEvent === 'function') onEvent(ev)
+    } catch (err) {
+      // Don't let a subscriber bug crash the bootstrap
+      runLog.stream.write(`emit error: ${err && err.message}\n`)
+    }
+  }
+
+  emit({
+    type: 'log',
+    line:
+      `[bootstrap] starting at ${new Date().toISOString()}; ` +
+      `activeRoot=${activeRoot}; ` +
+      `stamp=${installStamp ? installStamp.commit.slice(0, 12) : '<none>'}; ` +
+      `runLog=${runLog.path}`
+  })
+
+  try {
+    // 1. Resolve the platform installer.
+    const scriptInfo = await resolveInstallScript({ installStamp, sourceRepoRoot, hermesHome, emit })
+    const installerKind = scriptInfo.kind || 'powershell'
+
+    // 2. Fetch manifest
+    const manifest = await fetchManifest({
+      scriptPath: scriptInfo.path,
+      installerKind,
+      emit,
+      hermesHome,
+      activeRoot,
+      installStamp
+    })
+    emit({
+      type: 'manifest',
+      stages: manifest.stages,
+      protocolVersion: manifest.protocol_version || manifest.protocolVersion || null
+    })
+
+    // 3. Iterate stages in order. Stages flagged needs_user_input are still
+    //    invoked -- install.ps1's own -NonInteractive handler in those stages
+    //    emits skipped=true. We trust the protocol rather than filtering
+    //    client-side.
+    for (const stage of manifest.stages) {
+      if (abortSignal && abortSignal.aborted) {
+        emit({ type: 'failed', error: 'bootstrap cancelled by user' })
+        return { ok: false, cancelled: true }
+      }
+      const ev = await runStage({
+        scriptPath: scriptInfo.path,
+        installerKind,
+        stage,
+        emit,
+        hermesHome,
+        activeRoot,
+        abortSignal,
+        installStamp
+      })
+      if (ev.state === 'failed') {
+        emit({ type: 'failed', stage: stage.name, error: ev.error || 'stage failed' })
+        return { ok: false, failedStage: stage.name, error: ev.error }
+      }
+    }
+
+    // 4. Write the bootstrap-complete marker.
+    const markerPayload = {
+      pinnedCommit: installStamp ? installStamp.commit : null,
+      pinnedBranch: installStamp ? installStamp.branch : null
+    }
+    const marker = typeof writeMarker === 'function' ? writeMarker(markerPayload) : markerPayload
+    emit({ type: 'complete', marker })
+    return { ok: true, marker }
+  } catch (err) {
+    emit({ type: 'failed', error: err.message || String(err) })
+    return { ok: false, error: err.message || String(err) }
+  } finally {
+    try {
+      runLog.stream.end()
+    } catch {}
+  }
+}
+
+module.exports = {
+  runBootstrap,
+  // Exposed for testability
+  parseStageResult,
+  resolveLocalInstallScript,
+  cachedScriptPath
+}

apps/desktop/electron/entitlements.mac.inherit.plist

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>com.apple.security.cs.allow-jit</key>
+  <true/>
+  <key>com.apple.security.cs.allow-unsigned-executable-memory</key>
+  <true/>
+  <key>com.apple.security.cs.disable-library-validation</key>
+  <true/>
+</dict>
+</plist>

apps/desktop/electron/entitlements.mac.plist

@@ -0,0 +1,14 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>com.apple.security.cs.allow-jit</key>
+  <true/>
+  <key>com.apple.security.cs.allow-unsigned-executable-memory</key>
+  <true/>
+  <key>com.apple.security.cs.disable-library-validation</key>
+  <true/>
+  <key>com.apple.security.device.audio-input</key>
+  <true/>
+</dict>
+</plist>

apps/desktop/electron/hardening.cjs

@@ -0,0 +1,184 @@
+const fs = require('node:fs')
+const path = require('node:path')
+const { fileURLToPath } = require('node:url')
+
+const DEFAULT_FETCH_TIMEOUT_MS = 15_000
+const DATA_URL_READ_MAX_BYTES = 16 * 1024 * 1024
+const TEXT_PREVIEW_SOURCE_MAX_BYTES = 64 * 1024 * 1024
+
+const SAFE_ENV_SUFFIXES = new Set(['dist', 'example', 'sample', 'template'])
+const SENSITIVE_EXTENSIONS = new Set(['.kdbx', '.p12', '.pem', '.pfx'])
+
+function resolveTimeoutMs(timeoutMs, fallbackMs = DEFAULT_FETCH_TIMEOUT_MS) {
+  const fallback =
+    Number.isFinite(fallbackMs) && Number(fallbackMs) > 0 ? Math.round(Number(fallbackMs)) : DEFAULT_FETCH_TIMEOUT_MS
+  const parsed = Number(timeoutMs)
+
+  if (Number.isFinite(parsed) && parsed > 0) {
+    return Math.round(parsed)
+  }
+
+  return fallback
+}
+
+function encryptDesktopSecret(value, safeStorageApi) {
+  const raw = String(value || '')
+
+  if (!raw) {
+    return null
+  }
+
+  let encryptionAvailable = false
+
+  try {
+    encryptionAvailable = Boolean(safeStorageApi?.isEncryptionAvailable?.())
+  } catch {
+    encryptionAvailable = false
+  }
+
+  if (!encryptionAvailable) {
+    throw new Error(
+      'Secure token storage is unavailable, so Hermes Desktop cannot save remote gateway tokens. ' +
+        'Set HERMES_DESKTOP_REMOTE_URL and HERMES_DESKTOP_REMOTE_TOKEN in your environment, or enable OS keychain access and try again.'
+    )
+  }
+
+  try {
+    return {
+      encoding: 'safeStorage',
+      value: safeStorageApi.encryptString(raw).toString('base64')
+    }
+  } catch (error) {
+    const detail = error instanceof Error && error.message ? ` (${error.message})` : ''
+    throw new Error(
+      `Failed to encrypt the remote gateway token for secure storage${detail}. ` +
+        'Set HERMES_DESKTOP_REMOTE_URL and HERMES_DESKTOP_REMOTE_TOKEN in your environment as a fallback.'
+    )
+  }
+}
+
+function sensitiveFileBlockReason(filePath) {
+  const normalized = String(filePath || '')
+    .replace(/\\/g, '/')
+    .toLowerCase()
+  const basename = path.basename(normalized)
+  const ext = path.extname(basename)
+
+  if (!basename) {
+    return null
+  }
+
+  if (normalized.includes('/.ssh/')) {
+    return 'SSH key/config files are blocked.'
+  }
+
+  if (normalized.includes('/.gnupg/')) {
+    return 'GPG key material is blocked.'
+  }
+
+  if (normalized.endsWith('/.aws/credentials')) {
+    return 'AWS credential files are blocked.'
+  }
+
+  if (basename === '.env') {
+    return '.env files are blocked because they commonly contain secrets.'
+  }
+
+  if (basename.startsWith('.env.')) {
+    const suffix = basename.slice('.env.'.length)
+    if (!SAFE_ENV_SUFFIXES.has(suffix)) {
+      return `${basename} is blocked because it appears to contain environment secrets.`
+    }
+  }
+
+  if (/^id_(rsa|dsa|ecdsa|ed25519)(?:\..+)?$/.test(basename) && !basename.endsWith('.pub')) {
+    return 'SSH private key files are blocked.'
+  }
+
+  if (SENSITIVE_EXTENSIONS.has(ext)) {
+    return `${ext} key/certificate files are blocked.`
+  }
+
+  if (basename === '.npmrc' || basename === '.netrc' || basename === '.pypirc') {
+    return `${basename} is blocked because it may include auth credentials.`
+  }
+
+  return null
+}
+
+function resolveRequestedFilePath(filePath, baseDir = process.cwd(), purpose = 'File read') {
+  const raw = String(filePath || '').trim()
+
+  if (!raw) {
+    throw new Error(`${purpose} failed: file path is required.`)
+  }
+
+  if (raw.includes('\0')) {
+    throw new Error(`${purpose} failed: file path is invalid.`)
+  }
+
+  if (/^file:/i.test(raw)) {
+    try {
+      return fileURLToPath(raw)
+    } catch {
+      throw new Error(`${purpose} failed: file URL is invalid.`)
+    }
+  }
+
+  const resolvedBase = path.resolve(String(baseDir || process.cwd()))
+  return path.resolve(resolvedBase, raw)
+}
+
+async function resolveReadableFileForIpc(filePath, options = {}) {
+  const purpose = String(options.purpose || 'File read')
+  const resolvedPath = resolveRequestedFilePath(filePath, options.baseDir, purpose)
+
+  if (options.blockSensitive !== false) {
+    const blockReason = sensitiveFileBlockReason(resolvedPath)
+    if (blockReason) {
+      throw new Error(`${purpose} blocked for sensitive file: ${blockReason}`)
+    }
+  }
+
+  let stat
+  try {
+    stat = await fs.promises.stat(resolvedPath)
+  } catch (error) {
+    const code = error && typeof error === 'object' ? error.code : ''
+    if (code === 'ENOENT' || code === 'ENOTDIR') {
+      throw new Error(`${purpose} failed: file does not exist.`)
+    }
+    throw new Error(`${purpose} failed: ${error instanceof Error ? error.message : String(error)}`)
+  }
+
+  if (stat.isDirectory()) {
+    throw new Error(`${purpose} failed: path points to a directory.`)
+  }
+
+  if (!stat.isFile()) {
+    throw new Error(`${purpose} failed: only regular files can be read.`)
+  }
+
+  const maxBytes = Number.isFinite(options.maxBytes) && Number(options.maxBytes) > 0 ? Number(options.maxBytes) : null
+  if (maxBytes && stat.size > maxBytes) {
+    throw new Error(`${purpose} failed: file is too large (${stat.size} bytes; limit ${maxBytes} bytes).`)
+  }
+
+  try {
+    await fs.promises.access(resolvedPath, fs.constants.R_OK)
+  } catch {
+    throw new Error(`${purpose} failed: file is not readable.`)
+  }
+
+  return { resolvedPath, stat }
+}
+
+module.exports = {
+  DATA_URL_READ_MAX_BYTES,
+  DEFAULT_FETCH_TIMEOUT_MS,
+  TEXT_PREVIEW_SOURCE_MAX_BYTES,
+  encryptDesktopSecret,
+  resolveReadableFileForIpc,
+  resolveTimeoutMs,
+  sensitiveFileBlockReason
+}

apps/desktop/electron/hardening.test.cjs

@@ -0,0 +1,116 @@
+const assert = require('node:assert/strict')
+const fs = require('node:fs')
+const os = require('node:os')
+const path = require('node:path')
+const test = require('node:test')
+const { pathToFileURL } = require('node:url')
+
+const {
+  DEFAULT_FETCH_TIMEOUT_MS,
+  encryptDesktopSecret,
+  resolveReadableFileForIpc,
+  resolveTimeoutMs,
+  sensitiveFileBlockReason
+} = require('./hardening.cjs')
+
+test('resolveTimeoutMs falls back to defaults and accepts overrides', () => {
+  assert.equal(resolveTimeoutMs(undefined), DEFAULT_FETCH_TIMEOUT_MS)
+  assert.equal(resolveTimeoutMs(0), DEFAULT_FETCH_TIMEOUT_MS)
+  assert.equal(resolveTimeoutMs(-25), DEFAULT_FETCH_TIMEOUT_MS)
+  assert.equal(resolveTimeoutMs('2750'), 2750)
+})
+
+test('encryptDesktopSecret requires available secure storage', () => {
+  assert.equal(
+    encryptDesktopSecret('', { isEncryptionAvailable: () => true, encryptString: () => Buffer.alloc(0) }),
+    null
+  )
+
+  assert.throws(
+    () => encryptDesktopSecret('token', { isEncryptionAvailable: () => false, encryptString: () => Buffer.alloc(0) }),
+    /Secure token storage is unavailable/
+  )
+})
+
+test('encryptDesktopSecret stores safeStorage base64 payload', () => {
+  const secret = encryptDesktopSecret('token-123', {
+    isEncryptionAvailable: () => true,
+    encryptString: value => Buffer.from(`enc:${value}`, 'utf8')
+  })
+
+  assert.deepEqual(secret, {
+    encoding: 'safeStorage',
+    value: Buffer.from('enc:token-123', 'utf8').toString('base64')
+  })
+})
+
+test('sensitiveFileBlockReason blocks obvious secret file patterns', () => {
+  assert.match(String(sensitiveFileBlockReason('/tmp/.env')), /\.env/)
+  assert.equal(sensitiveFileBlockReason('/tmp/.env.example'), null)
+  assert.match(String(sensitiveFileBlockReason('/Users/me/.ssh/id_ed25519')), /SSH/)
+  assert.match(String(sensitiveFileBlockReason('/tmp/server-cert.pem')), /\.pem/)
+})
+
+test('resolveReadableFileForIpc validates existence type size and sensitivity', async t => {
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'hermes-desktop-hardening-'))
+  t.after(() => fs.rmSync(tempDir, { recursive: true, force: true }))
+
+  const textPath = path.join(tempDir, 'notes.txt')
+  fs.writeFileSync(textPath, 'hello world', 'utf8')
+
+  const fromRelative = await resolveReadableFileForIpc('notes.txt', {
+    baseDir: tempDir,
+    maxBytes: 256,
+    purpose: 'File preview'
+  })
+  assert.equal(fromRelative.resolvedPath, textPath)
+  assert.equal(fromRelative.stat.size, 11)
+
+  const fromFileUrl = await resolveReadableFileForIpc(pathToFileURL(textPath).toString(), {
+    purpose: 'File preview'
+  })
+  assert.equal(fromFileUrl.resolvedPath, textPath)
+
+  await assert.rejects(
+    resolveReadableFileForIpc('missing.txt', {
+      baseDir: tempDir,
+      purpose: 'Text preview'
+    }),
+    /file does not exist/
+  )
+
+  const nestedDir = path.join(tempDir, 'directory')
+  fs.mkdirSync(nestedDir)
+  await assert.rejects(
+    resolveReadableFileForIpc(nestedDir, {
+      purpose: 'Text preview'
+    }),
+    /path points to a directory/
+  )
+
+  const largePath = path.join(tempDir, 'large.txt')
+  fs.writeFileSync(largePath, 'x'.repeat(40), 'utf8')
+  await assert.rejects(
+    resolveReadableFileForIpc(largePath, {
+      maxBytes: 8,
+      purpose: 'File preview'
+    }),
+    /file is too large/
+  )
+
+  const envPath = path.join(tempDir, '.env')
+  fs.writeFileSync(envPath, 'SECRET_TOKEN=123', 'utf8')
+  await assert.rejects(
+    resolveReadableFileForIpc(envPath, {
+      purpose: 'File preview'
+    }),
+    /blocked for sensitive file/
+  )
+
+  const envTemplatePath = path.join(tempDir, '.env.example')
+  fs.writeFileSync(envTemplatePath, 'EXAMPLE_TOKEN=value', 'utf8')
+  const envTemplate = await resolveReadableFileForIpc(envTemplatePath, {
+    purpose: 'File preview'
+  })
+  assert.equal(envTemplate.resolvedPath, envTemplatePath)
+})

apps/desktop/electron/preload.cjs

@@ -0,0 +1,111 @@
+const { contextBridge, ipcRenderer, webUtils } = require('electron')
+
+contextBridge.exposeInMainWorld('hermesDesktop', {
+  getConnection: () => ipcRenderer.invoke('hermes:connection'),
+  getBootProgress: () => ipcRenderer.invoke('hermes:boot-progress:get'),
+  getConnectionConfig: () => ipcRenderer.invoke('hermes:connection-config:get'),
+  saveConnectionConfig: payload => ipcRenderer.invoke('hermes:connection-config:save', payload),
+  applyConnectionConfig: payload => ipcRenderer.invoke('hermes:connection-config:apply', payload),
+  testConnectionConfig: payload => ipcRenderer.invoke('hermes:connection-config:test', payload),
+  api: request => ipcRenderer.invoke('hermes:api', request),
+  notify: payload => ipcRenderer.invoke('hermes:notify', payload),
+  requestMicrophoneAccess: () => ipcRenderer.invoke('hermes:requestMicrophoneAccess'),
+  readFileDataUrl: filePath => ipcRenderer.invoke('hermes:readFileDataUrl', filePath),
+  readFileText: filePath => ipcRenderer.invoke('hermes:readFileText', filePath),
+  selectPaths: options => ipcRenderer.invoke('hermes:selectPaths', options),
+  writeClipboard: text => ipcRenderer.invoke('hermes:writeClipboard', text),
+  saveImageFromUrl: url => ipcRenderer.invoke('hermes:saveImageFromUrl', url),
+  saveImageBuffer: (data, ext) => ipcRenderer.invoke('hermes:saveImageBuffer', { data, ext }),
+  saveClipboardImage: () => ipcRenderer.invoke('hermes:saveClipboardImage'),
+  getPathForFile: file => {
+    try {
+      return webUtils.getPathForFile(file) || ''
+    } catch {
+      return ''
+    }
+  },
+  normalizePreviewTarget: (target, baseDir) => ipcRenderer.invoke('hermes:normalizePreviewTarget', target, baseDir),
+  watchPreviewFile: url => ipcRenderer.invoke('hermes:watchPreviewFile', url),
+  stopPreviewFileWatch: id => ipcRenderer.invoke('hermes:stopPreviewFileWatch', id),
+  setTitleBarTheme: payload => ipcRenderer.send('hermes:titlebar-theme', payload),
+  setPreviewShortcutActive: active => ipcRenderer.send('hermes:previewShortcutActive', Boolean(active)),
+  openExternal: url => ipcRenderer.invoke('hermes:openExternal', url),
+  fetchLinkTitle: url => ipcRenderer.invoke('hermes:fetchLinkTitle', url),
+  revealLogs: () => ipcRenderer.invoke('hermes:logs:reveal'),
+  getRecentLogs: () => ipcRenderer.invoke('hermes:logs:recent'),
+  readDir: dirPath => ipcRenderer.invoke('hermes:fs:readDir', dirPath),
+  gitRoot: startPath => ipcRenderer.invoke('hermes:fs:gitRoot', startPath),
+  terminal: {
+    dispose: id => ipcRenderer.invoke('hermes:terminal:dispose', id),
+    resize: (id, size) => ipcRenderer.invoke('hermes:terminal:resize', id, size),
+    start: options => ipcRenderer.invoke('hermes:terminal:start', options),
+    write: (id, data) => ipcRenderer.invoke('hermes:terminal:write', id, data),
+    onData: (id, callback) => {
+      const channel = `hermes:terminal:${id}:data`
+      const listener = (_event, payload) => callback(payload)
+      ipcRenderer.on(channel, listener)
+      return () => ipcRenderer.removeListener(channel, listener)
+    },
+    onExit: (id, callback) => {
+      const channel = `hermes:terminal:${id}:exit`
+      const listener = (_event, payload) => callback(payload)
+      ipcRenderer.on(channel, listener)
+      return () => ipcRenderer.removeListener(channel, listener)
+    }
+  },
+  onClosePreviewRequested: callback => {
+    const listener = () => callback()
+    ipcRenderer.on('hermes:close-preview-requested', listener)
+    return () => ipcRenderer.removeListener('hermes:close-preview-requested', listener)
+  },
+  onOpenUpdatesRequested: callback => {
+    const listener = () => callback()
+    ipcRenderer.on('hermes:open-updates', listener)
+    return () => ipcRenderer.removeListener('hermes:open-updates', listener)
+  },
+  onWindowStateChanged: callback => {
+    const listener = (_event, payload) => callback(payload)
+    ipcRenderer.on('hermes:window-state-changed', listener)
+    return () => ipcRenderer.removeListener('hermes:window-state-changed', listener)
+  },
+  onPreviewFileChanged: callback => {
+    const listener = (_event, payload) => callback(payload)
+    ipcRenderer.on('hermes:preview-file-changed', listener)
+    return () => ipcRenderer.removeListener('hermes:preview-file-changed', listener)
+  },
+  onBackendExit: callback => {
+    const listener = (_event, payload) => callback(payload)
+    ipcRenderer.on('hermes:backend-exit', listener)
+    return () => ipcRenderer.removeListener('hermes:backend-exit', listener)
+  },
+  onBootProgress: callback => {
+    const listener = (_event, payload) => callback(payload)
+    ipcRenderer.on('hermes:boot-progress', listener)
+    return () => ipcRenderer.removeListener('hermes:boot-progress', listener)
+  },
+  // First-launch bootstrap progress -- emitted by the install.ps1 stage
+  // runner in main.cjs (apps/desktop/electron/bootstrap-runner.cjs).
+  // Renderer's install overlay subscribes to live events and queries the
+  // current snapshot via getBootstrapState() to recover after a devtools
+  // reload mid-bootstrap.
+  getBootstrapState: () => ipcRenderer.invoke('hermes:bootstrap:get'),
+  resetBootstrap: () => ipcRenderer.invoke('hermes:bootstrap:reset'),
+  repairBootstrap: () => ipcRenderer.invoke('hermes:bootstrap:repair'),
+  onBootstrapEvent: callback => {
+    const listener = (_event, payload) => callback(payload)
+    ipcRenderer.on('hermes:bootstrap:event', listener)
+    return () => ipcRenderer.removeListener('hermes:bootstrap:event', listener)
+  },
+  getVersion: () => ipcRenderer.invoke('hermes:version'),
+  updates: {
+    check: () => ipcRenderer.invoke('hermes:updates:check'),
+    apply: opts => ipcRenderer.invoke('hermes:updates:apply', opts),
+    getBranch: () => ipcRenderer.invoke('hermes:updates:branch:get'),
+    setBranch: name => ipcRenderer.invoke('hermes:updates:branch:set', name),
+    onProgress: callback => {
+      const listener = (_event, payload) => callback(payload)
+      ipcRenderer.on('hermes:updates:progress', listener)
+      return () => ipcRenderer.removeListener('hermes:updates:progress', listener)
+    }
+  }
+})

apps/desktop/eslint.config.mjs

@@ -0,0 +1,122 @@
+import js from '@eslint/js'
+import typescriptEslint from '@typescript-eslint/eslint-plugin'
+import typescriptParser from '@typescript-eslint/parser'
+import perfectionist from 'eslint-plugin-perfectionist'
+import reactPlugin from 'eslint-plugin-react'
+import reactCompiler from 'eslint-plugin-react-compiler'
+import hooksPlugin from 'eslint-plugin-react-hooks'
+import unusedImports from 'eslint-plugin-unused-imports'
+import globals from 'globals'
+
+const noopRule = {
+  meta: { schema: [], type: 'problem' },
+  create: () => ({})
+}
+
+const customRules = {
+  rules: {
+    'no-process-cwd': noopRule,
+    'no-process-env-top-level': noopRule,
+    'no-sync-fs': noopRule,
+    'no-top-level-dynamic-import': noopRule,
+    'no-top-level-side-effects': noopRule
+  }
+}
+
+export default [
+  {
+    ignores: ['**/node_modules/**', '**/dist/**', 'src/**/*.js']
+  },
+  js.configs.recommended,
+  {
+    files: ['**/*.{ts,tsx}'],
+    languageOptions: {
+      globals: {
+        ...globals.browser,
+        ...globals.node
+      },
+      parser: typescriptParser,
+      parserOptions: {
+        ecmaFeatures: { jsx: true },
+        ecmaVersion: 'latest',
+        sourceType: 'module'
+      }
+    },
+    plugins: {
+      '@typescript-eslint': typescriptEslint,
+      'custom-rules': customRules,
+      perfectionist,
+      react: reactPlugin,
+      'react-compiler': reactCompiler,
+      'react-hooks': hooksPlugin,
+      'unused-imports': unusedImports
+    },
+    rules: {
+      '@typescript-eslint/consistent-type-imports': ['error', { prefer: 'type-imports' }],
+      '@typescript-eslint/no-unused-vars': 'off',
+      curly: ['error', 'all'],
+      'no-fallthrough': ['error', { allowEmptyCase: true }],
+      'no-undef': 'off',
+      'no-unused-vars': 'off',
+      'padding-line-between-statements': [
+        1,
+        {
+          blankLine: 'always',
+          next: [
+            'block-like',
+            'block',
+            'return',
+            'if',
+            'class',
+            'continue',
+            'debugger',
+            'break',
+            'multiline-const',
+            'multiline-let'
+          ],
+          prev: '*'
+        },
+        {
+          blankLine: 'always',
+          next: '*',
+          prev: ['case', 'default', 'multiline-const', 'multiline-let', 'multiline-block-like']
+        },
+        { blankLine: 'never', next: ['block', 'block-like'], prev: ['case', 'default'] },
+        { blankLine: 'always', next: ['block', 'block-like'], prev: ['block', 'block-like'] },
+        { blankLine: 'always', next: ['empty'], prev: 'export' },
+        { blankLine: 'never', next: 'iife', prev: ['block', 'block-like', 'empty'] }
+      ],
+      'perfectionist/sort-exports': ['error', { order: 'asc', type: 'natural' }],
+      'perfectionist/sort-imports': [
+        'error',
+        {
+          groups: ['side-effect', 'builtin', 'external', 'internal', 'parent', 'sibling', 'index'],
+          order: 'asc',
+          type: 'natural'
+        }
+      ],
+      'perfectionist/sort-jsx-props': ['error', { order: 'asc', type: 'natural' }],
+      'perfectionist/sort-named-exports': ['error', { order: 'asc', type: 'natural' }],
+      'perfectionist/sort-named-imports': ['error', { order: 'asc', type: 'natural' }],
+      'react-compiler/react-compiler': 'warn',
+      'react-hooks/exhaustive-deps': 'warn',
+      'react-hooks/rules-of-hooks': 'error',
+      'unused-imports/no-unused-imports': 'error'
+    },
+    settings: {
+      react: { version: 'detect' }
+    }
+  },
+  {
+    files: ['**/*.js', '**/*.cjs'],
+    ignores: ['**/node_modules/**', '**/dist/**'],
+    languageOptions: {
+      ecmaVersion: 'latest',
+      globals: { ...globals.node },
+      sourceType: 'commonjs'
+    }
+  },
+  {
+    ignores: ['*.config.*']
+  }
+]

apps/desktop/index.html

@@ -0,0 +1,14 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <link rel="icon" href="/apple-touch-icon.png" />
+    <link rel="apple-touch-icon" href="/apple-touch-icon.png" />
+    <title>Hermes</title>
+  </head>
+  <body>
+    <div id="root" class="scrollbar-dt"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>

apps/desktop/package.json

@@ -0,0 +1,232 @@
+{
+  "name": "hermes",
+  "productName": "Hermes",
+  "private": true,
+  "version": "0.15.1",
+  "description": "Native desktop shell for Hermes Agent.",
+  "author": "Nous Research",
+  "type": "module",
+  "main": "electron/main.cjs",
+  "scripts": {
+    "dev": "concurrently -k \"npm:dev:renderer\" \"npm:dev:electron\"",
+    "dev:fake-boot": "cross-env HERMES_DESKTOP_BOOT_FAKE=1 HERMES_DESKTOP_BOOT_FAKE_STEP_MS=650 npm run dev",
+    "dev:renderer": "node scripts/assert-root-install.cjs && vite --host 127.0.0.1 --port 5174",
+    "dev:electron": "wait-on http://127.0.0.1:5174 && cross-env XCURSOR_SIZE=24 HERMES_DESKTOP_DEV_SERVER=http://127.0.0.1:5174 electron .",
+    "profile:main": "wait-on http://127.0.0.1:5174 && cross-env XCURSOR_SIZE=24 HERMES_DESKTOP_DEV_SERVER=http://127.0.0.1:5174 electron --inspect=9229 .",
+    "profile:main:cpu": "wait-on http://127.0.0.1:5174 && cross-env XCURSOR_SIZE=24 NODE_OPTIONS=--cpu-prof HERMES_DESKTOP_DEV_SERVER=http://127.0.0.1:5174 electron .",
+    "start": "npm run build && electron .",
+    "build": "node scripts/assert-root-install.cjs && node scripts/write-build-stamp.cjs && node scripts/stage-native-deps.cjs && tsc -b && vite build",
+    "builder": "cross-env NODE_OPTIONS=--max-old-space-size=16384 electron-builder",
+    "pack": "npm run build && npm run builder -- --dir",
+    "dist": "npm run build && npm run builder",
+    "dist:mac": "npm run build && npm run builder -- --mac",
+    "dist:mac:dmg": "npm run build && npm run builder -- --mac dmg",
+    "dist:mac:zip": "npm run build && npm run builder -- --mac zip",
+    "dist:win": "npm run build && npm run builder -- --win",
+    "dist:win:msi": "npm run build && npm run builder -- --win msi",
+    "dist:win:nsis": "npm run build && npm run builder -- --win nsis",
+    "dist:linux": "npm run build && npm run builder -- --linux AppImage deb rpm",
+    "test:desktop": "node scripts/test-desktop.mjs",
+    "test:desktop:all": "node scripts/test-desktop.mjs all",
+    "test:desktop:dmg": "node scripts/test-desktop.mjs dmg",
+    "test:desktop:nsis": "node scripts/test-desktop.mjs nsis",
+    "test:desktop:existing": "node scripts/test-desktop.mjs existing",
+    "test:desktop:fresh": "node scripts/test-desktop.mjs fresh",
+    "test:desktop:platforms": "node --test electron/bootstrap-platform.test.cjs electron/hardening.test.cjs electron/backend-probes.test.cjs",
+    "type-check": "tsc -b",
+    "lint": "eslint src/ electron/",
+    "lint:fix": "eslint src/ electron/ --fix",
+    "fmt": "prettier --write 'src/**/*.{ts,tsx}' 'electron/**/*.{js,cjs}' 'vite.config.ts'",
+    "fix": "npm run lint:fix && npm run fmt",
+    "test:ui": "vitest run --environment jsdom",
+    "preview": "node scripts/assert-root-install.cjs && vite preview --host 127.0.0.1 --port 4174"
+  },
+  "dependencies": {
+    "@assistant-ui/react": "^0.12.28",
+    "@assistant-ui/react-streamdown": "^0.1.11",
+    "@audiowave/react": "^0.6.2",
+    "@chenglou/pretext": "^0.0.6",
+    "@dnd-kit/core": "^6.3.1",
+    "@dnd-kit/sortable": "^10.0.0",
+    "@dnd-kit/utilities": "^3.2.2",
+    "@hermes/shared": "file:../shared",
+    "@nanostores/react": "^1.1.0",
+    "@nous-research/ui": "^0.13.0",
+    "@radix-ui/react-slot": "^1.2.4",
+    "@streamdown/code": "^1.1.1",
+    "@tabler/icons-react": "^3.41.1",
+    "@tailwindcss/typography": "^0.5.19",
+    "@tailwindcss/vite": "^4.2.4",
+    "@tanstack/react-query": "^5.100.6",
+    "@tanstack/react-virtual": "^3.13.24",
+    "@vscode/codicons": "^0.0.45",
+    "@xterm/addon-fit": "^0.11.0",
+    "@xterm/addon-unicode11": "^0.9.0",
+    "@xterm/addon-web-links": "^0.12.0",
+    "@xterm/addon-webgl": "^0.19.0",
+    "@xterm/xterm": "^6.0.0",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "cmdk": "^1.1.1",
+    "hast-util-from-html-isomorphic": "^2.0.0",
+    "hast-util-to-text": "^4.0.2",
+    "ignore": "^7.0.5",
+    "katex": "^0.16.45",
+    "leva": "^0.10.1",
+    "motion": "^12.38.0",
+    "nanostores": "^1.3.0",
+    "node-pty": "1.1.0",
+    "radix-ui": "^1.4.3",
+    "react": "^19.2.5",
+    "react-arborist": "^3.5.0",
+    "react-dom": "^19.2.5",
+    "react-router-dom": "^7.14.2",
+    "react-shiki": "^0.9.3",
+    "remark-math": "^6.0.0",
+    "shiki": "^4.0.2",
+    "streamdown": "^2.5.0",
+    "tailwind-merge": "^3.5.0",
+    "tailwindcss": "^4.2.4",
+    "tw-shimmer": "^0.4.11",
+    "unicode-animations": "^1.0.3",
+    "unified": "^11.0.5",
+    "unist-util-visit-parents": "^6.0.2",
+    "vfile": "^6.0.3",
+    "web-haptics": "^0.0.6"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.4",
+    "@testing-library/react": "^16.3.2",
+    "@types/hast": "^3.0.4",
+    "@types/node": "^24.12.2",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@typescript-eslint/eslint-plugin": "^8.59.1",
+    "@typescript-eslint/parser": "^8.59.1",
+    "@vitejs/plugin-react": "^6.0.1",
+    "concurrently": "^9.2.1",
+    "cross-env": "^10.1.0",
+    "electron": "^40.9.3",
+    "electron-builder": "^26.8.1",
+    "eslint": "^9.39.4",
+    "eslint-plugin-perfectionist": "^5.9.0",
+    "eslint-plugin-react": "^7.37.5",
+    "eslint-plugin-react-compiler": "^19.1.0-rc.2",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "eslint-plugin-unused-imports": "^4.4.1",
+    "globals": "^16.5.0",
+    "jsdom": "^29.1.1",
+    "prettier": "^3.8.3",
+    "rcedit": "^5.0.2",
+    "typescript": "^6.0.3",
+    "vite": "^8.0.10",
+    "vitest": "^4.1.5",
+    "wait-on": "^9.0.5"
+  },
+  "build": {
+    "electronVersion": "40.9.3",
+    "appId": "com.nousresearch.hermes",
+    "productName": "Hermes",
+    "executableName": "Hermes",
+    "artifactName": "Hermes-${version}-${os}-${arch}.${ext}",
+    "icon": "assets/icon",
+    "directories": {
+      "output": "release"
+    },
+    "files": [
+      "dist/**",
+      "assets/**",
+      "electron/**",
+      "public/**",
+      "package.json"
+    ],
+    "beforeBuild": "scripts/before-build.cjs",
+    "afterPack": "scripts/after-pack.cjs",
+    "extraResources": [
+      {
+        "from": "build/install-stamp.json",
+        "to": "install-stamp.json"
+      },
+      {
+        "from": "build/native-deps",
+        "to": "native-deps"
+      },
+      {
+        "from": "assets/icon.ico",
+        "to": "icon.ico"
+      }
+    ],
+    "asar": true,
+    "afterSign": "scripts/notarize.cjs",
+    "asarUnpack": [
+      "**/*.node",
+      "**/prebuilds/**"
+    ],
+    "mac": {
+      "category": "public.app-category.developer-tools",
+      "entitlements": "electron/entitlements.mac.plist",
+      "entitlementsInherit": "electron/entitlements.mac.inherit.plist",
+      "extendInfo": {
+        "CFBundleDisplayName": "Hermes",
+        "CFBundleExecutable": "Hermes",
+        "CFBundleName": "Hermes",
+        "NSAudioCaptureUsageDescription": "Hermes uses audio capture for voice conversations.",
+        "NSMicrophoneUsageDescription": "Hermes uses the microphone for voice input and voice conversations."
+      },
+      "gatekeeperAssess": false,
+      "hardenedRuntime": true,
+      "target": [
+        "dmg",
+        "zip"
+      ]
+    },
+    "dmg": {
+      "title": "Install Hermes",
+      "backgroundColor": "#f5f5f7",
+      "iconSize": 96,
+      "window": {
+        "width": 560,
+        "height": 360
+      },
+      "contents": [
+        {
+          "x": 160,
+          "y": 170,
+          "type": "file"
+        },
+        {
+          "x": 400,
+          "y": 170,
+          "type": "link",
+          "path": "/Applications"
+        }
+      ]
+    },
+    "win": {
+      "legalTrademarks": "Hermes",
+      "target": [
+        "nsis",
+        "msi"
+      ],
+      "signAndEditExecutable": false
+    },
+    "linux": {
+      "category": "Development",
+      "maintainer": "Nous Research <support@nousresearch.com>",
+      "synopsis": "Native desktop shell for Hermes Agent.",
+      "target": [
+        "AppImage",
+        "deb",
+        "rpm"
+      ]
+    },
+    "nsis": {
+      "oneClick": false,
+      "allowToChangeInstallationDirectory": true,
+      "perMachine": false,
+      "shortcutName": "Hermes",
+      "uninstallDisplayName": "Hermes",
+      "warningsAsErrors": false
+    }
+  }
+}

apps/desktop/preview-demo.html

@@ -0,0 +1,65 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width,initial-scale=1" />
+<title>Preview Demo</title>
+<style>
+  :root { color-scheme: dark; }
+  html, body { height: 100%; margin: 0; }
+  body {
+    font-family: ui-sans-serif, system-ui, -apple-system, "SF Pro Text", sans-serif;
+    background: radial-gradient(1200px 600px at 20% 10%, #4a1a33 0%, #2a1020 40%, #120810 100%);
+    color: #ffe4f1;
+    display: grid;
+    place-items: center;
+    padding: 2rem;
+  }
+  .card {
+    max-width: 520px;
+    padding: 2rem 2.25rem;
+    border: 1px solid rgba(255,182,214,0.18);
+    border-radius: 14px;
+    background: rgba(28,14,22,0.6);
+    backdrop-filter: blur(6px);
+    box-shadow: 0 10px 40px rgba(0,0,0,0.4);
+  }
+  h1 {
+    margin: 0 0 0.5rem;
+    font-size: 1.5rem;
+    letter-spacing: 0.01em;
+  }
+  p { margin: 0.35rem 0; opacity: 0.85; line-height: 1.5; }
+  .dot {
+    display: inline-block; width: 10px; height: 10px; border-radius: 50%;
+    background: #ff6fb5; margin-right: 0.5rem;
+    box-shadow: 0 0 12px #ff6fb5;
+    animation: pulse 1.6s ease-in-out infinite;
+  }
+  @keyframes pulse {
+    0%,100% { transform: scale(1); opacity: 1; }
+    50%     { transform: scale(1.4); opacity: 0.6; }
+  }
+  code {
+    background: rgba(255,182,214,0.10);
+    padding: 0.1rem 0.35rem;
+    border-radius: 4px;
+    font-size: 0.9em;
+  }
+  .time { font-variant-numeric: tabular-nums; opacity: 0.7; font-size: 0.85rem; margin-top: 1rem; }
+</style>
+</head>
+<body>
+  <div class="card">
+    <h1><span class="dot"></span>preview-demo.html</h1>
+    <p>Tiny standalone HTML artifact — no server, no build step.</p>
+    <p>Open directly in a browser via <code>file://</code>.</p>
+    <p class="time" id="t"></p>
+  </div>
+  <script>
+    const el = document.getElementById('t');
+    const tick = () => { el.textContent = new Date().toLocaleString(); };
+    tick(); setInterval(tick, 1000);
+  </script>
+</body>
+</html>

apps/desktop/scripts/after-pack.cjs

@@ -0,0 +1,41 @@
+/**
+ * after-pack.cjs — electron-builder afterPack hook.
+ *
+ * Stamps the Hermes icon + identity onto the packed Windows Hermes.exe via
+ * rcedit (delegated to set-exe-identity.cjs). This runs for EVERY packed build
+ * — first install, `hermes desktop`, the installer's --update rebuild, and a
+ * dev's manual `npm run pack` — so the branded exe can never silently revert
+ * to the stock "Electron" icon/name (the bug when the stamp lived only in
+ * install.ps1, which the update path doesn't use).
+ *
+ * Windows-only: rcedit edits PE resources, irrelevant on macOS/Linux where the
+ * app identity comes from the bundle Info.plist / desktop entry. Best-effort:
+ * a stamp failure must never fail an otherwise-good build (worst case is the
+ * stock icon, not a broken app), so we log and resolve rather than throw.
+ *
+ * electron-builder passes a context with:
+ *   - electronPlatformName: 'win32' | 'darwin' | 'linux'
+ *   - appOutDir:            the unpacked app directory for this target
+ *   - packager.appInfo.productFilename: the exe basename (e.g. 'Hermes')
+ */
+
+const path = require('node:path')
+
+const { stampExeIdentity } = require('./set-exe-identity.cjs')
+
+exports.default = async function afterPack(context) {
+  if (context.electronPlatformName !== 'win32') {
+    return
+  }
+
+  const productName = context.packager?.appInfo?.productFilename || 'Hermes'
+  const exe = path.join(context.appOutDir, `${productName}.exe`)
+  const desktopRoot = path.resolve(__dirname, '..')
+
+  try {
+    await stampExeIdentity(exe, desktopRoot)
+  } catch (err) {
+    // Never fail the build over a cosmetic stamp.
+    console.warn(`[after-pack] exe identity stamp failed (${err.message}); Hermes.exe keeps the stock Electron icon`)
+  }
+}

apps/desktop/scripts/assert-root-install.cjs

@@ -0,0 +1,13 @@
+"use strict"
+
+const fs = require("fs")
+const path = require("path")
+
+const root = path.resolve(__dirname, "..", "..", "..")
+
+try {
+  fs.accessSync(path.join(root, "node_modules", "vite", "package.json"))
+} catch {
+  console.error(`Run from repo root: cd ${root} && npm ci`)
+  process.exit(1)
+}

apps/desktop/scripts/before-build.cjs

@@ -0,0 +1,11 @@
+/**
+ * Desktop bundles ship precompiled renderer assets. Returning false here tells
+ * electron-builder to skip the node_modules collector/install step, which
+ * avoids workspace dependency graph explosions and keeps packaging
+ * deterministic across environments. The Hermes Agent Python payload is no
+ * longer bundled; the Electron app fetches it at first launch via
+ * `install.ps1`'s stage protocol (Windows). See `electron/main.cjs`.
+ */
+module.exports = async function beforeBuild() {
+  return false
+}

apps/desktop/scripts/click-session.mjs

@@ -0,0 +1,51 @@
+// Click on a session by partial title match.
+const list = await (await fetch('http://127.0.0.1:9222/json/list')).json()
+const tgt = list.find(t => t.type === 'page' && t.url.startsWith('http'))
+const ws = new WebSocket(tgt.webSocketDebuggerUrl)
+let id = 0
+const pending = new Map()
+ws.addEventListener('message', ev => {
+  const m = JSON.parse(ev.data)
+  if (m.id != null && pending.has(m.id)) {
+    pending.get(m.id)(m)
+    pending.delete(m.id)
+  }
+})
+await new Promise(r => ws.addEventListener('open', r))
+const send = (method, params = {}) =>
+  new Promise(r => {
+    const i = ++id
+    pending.set(i, r)
+    ws.send(JSON.stringify({ id: i, method, params }))
+  })
+
+const title = process.argv[2] || 'Phaser particle'
+const r = await send('Runtime.evaluate', {
+  expression: `
+    (() => {
+      const titleMatch = ${JSON.stringify(title)}
+      const all = document.querySelectorAll('button, a, div[role="button"]')
+      const found = [...all].find(el => (el.textContent || '').includes(titleMatch))
+      if (!found) return JSON.stringify({ found: false, tried: titleMatch })
+      found.scrollIntoView()
+      found.click()
+      return JSON.stringify({ found: true, tag: found.tagName, text: (found.textContent || '').slice(0, 80) })
+    })()
+  `,
+  returnByValue: true
+})
+console.log('click raw:', JSON.stringify(r, null, 2))
+await new Promise(r => setTimeout(r, 3000))
+
+const status = await send('Runtime.evaluate', {
+  expression: `JSON.stringify({
+    url: location.href,
+    hasComposer: !!document.querySelector('[data-slot="composer-rich-input"]'),
+    threadMessages: document.querySelectorAll('[data-slot="aui_message"]').length,
+    bodyTextSnippet: document.body.innerText.slice(0, 500),
+    title: document.title
+  })`,
+  returnByValue: true
+})
+console.log('after click:', status.result.value)
+ws.close()

apps/desktop/scripts/dev-no-hmr.mjs

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+// Launch the desktop renderer with HMR disabled so the React Fast Refresh
+// preamble path is skipped. This sidesteps a current Vite 8 / plugin-react 6
+// bug where the preamble script is not injected into index.html → renderer
+// throws "$RefreshReg$ is not defined" on every TSX module → React tree
+// never mounts.
+//
+// We're not trying to use HMR while profiling typing lag anyway. Hermes desktop
+// boots, you type, profiler measures. HMR off is fine.
+//
+// Usage: node apps/desktop/scripts/dev-no-hmr.mjs
+//        (then in another shell, run electron --remote-debugging-port=9222 .)
+
+import { createServer } from 'vite'
+
+const server = await createServer({
+  configFile: new URL('../vite.config.ts', import.meta.url).pathname,
+  root: new URL('../', import.meta.url).pathname,
+  server: { hmr: false, host: '127.0.0.1', port: 5174, strictPort: true }
+})
+await server.listen()
+server.printUrls()

apps/desktop/scripts/diag-jump.mjs

@@ -0,0 +1,115 @@
+// Wrap the thread scroller's properties and observe pin/scroll/RO events
+// in real time during a submit, then print the timeline.
+const list = await (await fetch('http://127.0.0.1:9222/json/list')).json()
+const tgt = list.find(t => t.type === 'page' && t.url.startsWith('http'))
+const ws = new WebSocket(tgt.webSocketDebuggerUrl)
+let id = 0
+const pending = new Map()
+ws.addEventListener('message', ev => {
+  const m = JSON.parse(ev.data)
+  if (m.id != null && pending.has(m.id)) {
+    pending.get(m.id)(m)
+    pending.delete(m.id)
+  }
+})
+await new Promise(r => ws.addEventListener('open', r))
+const send = (m, p = {}) =>
+  new Promise(r => {
+    const i = ++id
+    pending.set(i, r)
+    ws.send(JSON.stringify({ id: i, method: m, params: p }))
+  })
+const evalP = async expr => {
+  const r = await send('Runtime.evaluate', { expression: expr, returnByValue: true })
+  if (r.result?.exceptionDetails) throw new Error(r.result.exceptionDetails.text)
+  return r.result.result.value
+}
+
+await evalP(`(() => {
+  const v = document.querySelector('[data-slot="aui_thread-viewport"]')
+  if (v) v.scrollTop = v.scrollHeight
+})()`)
+await new Promise(r => setTimeout(r, 300))
+
+await evalP(`(() => {
+  const el = document.querySelector('[data-slot="composer-rich-input"]')
+  el.focus()
+  const r = document.createRange(); r.selectNodeContents(el); r.collapse(false)
+  window.getSelection().removeAllRanges(); window.getSelection().addRange(r)
+})()`)
+
+const text = 'short follow-up'
+for (const c of text) {
+  await send('Input.dispatchKeyEvent', { type: 'char', text: c, unmodifiedText: c })
+  await new Promise(r => setTimeout(r, 10))
+}
+await new Promise(r => setTimeout(r, 300))
+
+// Hook into the viewport scrollTop setter + scroll + RO so we see every event
+await evalP(`(() => {
+  const v = document.querySelector('[data-slot="aui_thread-viewport"]')
+  const events = []
+  window.__threadEvents = events
+  const t0 = performance.now()
+  const push = (kind, detail) => events.push({ t: performance.now() - t0, kind, ...detail })
+
+  // intercept scrollTop writes
+  const desc = Object.getOwnPropertyDescriptor(Element.prototype, 'scrollTop')
+  Object.defineProperty(v, 'scrollTop', {
+    get() { return desc.get.call(this) },
+    set(val) {
+      push('scrollTop=', { val, fromScrollHeight: this.scrollHeight, stackTop: (new Error()).stack.split('\\n').slice(2, 5).map(s => s.trim()).join(' | ') })
+      desc.set.call(this, val)
+    },
+    configurable: true
+  })
+
+  // scroll event
+  v.addEventListener('scroll', () => {
+    push('scroll', { scrollTop: v.scrollTop, scrollHeight: v.scrollHeight })
+  }, { passive: true, capture: true })
+
+  // RO on the viewport itself
+  const ro = new ResizeObserver((entries) => {
+    for (const e of entries) {
+      push('RO', { target: e.target.getAttribute('data-slot') || e.target.tagName, h: e.contentRect.height })
+    }
+  })
+  ro.observe(v)
+  if (v.firstElementChild) ro.observe(v.firstElementChild)
+
+  // mutationobserver on the viewport
+  const mo = new MutationObserver((muts) => {
+    push('mut', { count: muts.length, added: muts.reduce((s, m) => s + m.addedNodes.length, 0), removed: muts.reduce((s, m) => s + m.removedNodes.length, 0) })
+  })
+  mo.observe(v, { childList: true, subtree: true, characterData: true })
+
+  window.__teardown = () => { ro.disconnect(); mo.disconnect() }
+  return true
+})()`)
+
+// fire Enter
+await send('Input.dispatchKeyEvent', {
+  type: 'rawKeyDown', windowsVirtualKeyCode: 13, key: 'Enter', code: 'Enter', text: '\r', unmodifiedText: '\r'
+})
+await send('Input.dispatchKeyEvent', { type: 'keyUp', windowsVirtualKeyCode: 13, key: 'Enter', code: 'Enter' })
+
+await new Promise(r => setTimeout(r, 1200))
+
+const events = JSON.parse(await evalP(`JSON.stringify(window.__threadEvents || [])`))
+console.log(`\n${events.length} events:`)
+for (const e of events) {
+  const t = String(e.t.toFixed(0)).padStart(5)
+  const { kind, t: _t, ...rest } = e
+  console.log(`  ${t}ms  ${kind.padEnd(12)} ${JSON.stringify(rest)}`)
+}
+
+await evalP(`window.__teardown?.()`)
+// Cancel running agent
+await evalP(`(() => {
+  for (const b of document.querySelectorAll('button')) {
+    if ((b.getAttribute('aria-label') || '').toLowerCase().includes('stop')) { b.click(); return 'stopped' }
+  }
+})()`)
+
+ws.close()

apps/desktop/scripts/eval.mjs

@@ -0,0 +1,21 @@
+// Simple eval helper — runs an expression and returns the result.value.
+const targets = await (await fetch('http://127.0.0.1:9222/json')).json()
+const t = targets.find((t) => t.url.includes('5174'))
+const ws = new WebSocket(t.webSocketDebuggerUrl)
+let id = 0
+const pending = new Map()
+ws.addEventListener('message', (ev) => {
+  const m = JSON.parse(ev.data)
+  if (pending.has(m.id)) { pending.get(m.id)(m); pending.delete(m.id) }
+})
+await new Promise((r) => ws.addEventListener('open', r))
+const send = (method, params) => new Promise((res) => { const i = ++id; pending.set(i, res); ws.send(JSON.stringify({ id: i, method, params })) })
+
+const expr = process.argv[2] || '1+1'
+const r = await send('Runtime.evaluate', { expression: expr, returnByValue: true, awaitPromise: true })
+if (r.result.exceptionDetails) {
+  console.error('EXCEPTION:', r.result.exceptionDetails.exception?.description)
+} else {
+  console.log(JSON.stringify(r.result.result.value, null, 2))
+}
+ws.close()

apps/desktop/scripts/leak-typing.mjs

@@ -0,0 +1,222 @@
+#!/usr/bin/env node
+// Leak-detection harness — measure detached DOM, listener count, and FiberNode
+// growth as a function of keystrokes typed.
+//
+// Workflow:
+//   1. Open session, focus composer
+//   2. forceGC; capture baseline counts
+//   3. Repeat N rounds: type M chars, forceGC, capture counts, clear composer
+//   4. Print growth-per-round table
+//
+// Usage:
+//   node apps/desktop/scripts/leak-typing.mjs [--rounds=6] [--chars=200] [--cps=40] [--port=9222]
+
+import { writeFileSync } from 'node:fs'
+
+const args = Object.fromEntries(
+  process.argv.slice(2).flatMap(s => {
+    const m = s.match(/^--([^=]+)(?:=(.*))?$/)
+    return m ? [[m[1], m[2] ?? true]] : []
+  })
+)
+const PORT = Number(args.port ?? 9222)
+const ROUNDS = Number(args.rounds ?? 6)
+const CHARS = Number(args.chars ?? 200)
+const CPS = Number(args.cps ?? 40)
+
+const log = (...m) => console.log('[leak]', ...m)
+
+async function pickRenderer() {
+  const list = await (await fetch(`http://127.0.0.1:${PORT}/json/list`)).json()
+  return list.find(t => t.type === 'page' && t.url.startsWith('http'))
+}
+
+function connect(url) {
+  return new Promise((resolve, reject) => {
+    const ws = new WebSocket(url)
+    let id = 0
+    const pending = new Map()
+    const events = new Map()
+    ws.addEventListener('open', () =>
+      resolve({
+        send(method, params = {}) {
+          const myId = ++id
+          ws.send(JSON.stringify({ id: myId, method, params }))
+          return new Promise((res, rej) => pending.set(myId, { res, rej }))
+        },
+        on(method, h) {
+          if (!events.has(method)) events.set(method, [])
+          events.get(method).push(h)
+        },
+        close: () => ws.close()
+      })
+    )
+    ws.addEventListener('error', reject)
+    ws.addEventListener('message', ev => {
+      const m = JSON.parse(typeof ev.data === 'string' ? ev.data : ev.data.toString('utf8'))
+      if (m.id != null) {
+        const p = pending.get(m.id)
+        if (!p) return
+        pending.delete(m.id)
+        m.error ? p.rej(new Error(m.error.message)) : p.res(m.result)
+      } else if (m.method) {
+        ;(events.get(m.method) ?? []).forEach(h => h(m.params))
+      }
+    })
+  })
+}
+
+async function evalInPage(cdp, expr) {
+  const r = await cdp.send('Runtime.evaluate', { expression: expr, returnByValue: true })
+  if (r.exceptionDetails) throw new Error(r.exceptionDetails.text)
+  return r.result.value
+}
+
+async function forceGCAndSettle(cdp) {
+  for (let i = 0; i < 3; i++) {
+    await cdp.send('HeapProfiler.collectGarbage')
+    await new Promise(r => setTimeout(r, 60))
+  }
+}
+
+async function focusComposer(cdp) {
+  return await evalInPage(
+    cdp,
+    `(() => {
+      const el = document.querySelector('[data-slot="composer-rich-input"]')
+      if (!el) return false
+      el.focus()
+      const range = document.createRange()
+      range.selectNodeContents(el)
+      range.collapse(false)
+      const sel = window.getSelection()
+      sel.removeAllRanges()
+      sel.addRange(range)
+      return true
+    })()`
+  )
+}
+
+async function clearComposer(cdp) {
+  await evalInPage(
+    cdp,
+    `(() => {
+      const el = document.querySelector('[data-slot="composer-rich-input"]')
+      if (!el) return false
+      // Clear via the same path as the composer's clear flow:
+      // dispatch a single Backspace until empty would be N round-trips; quicker
+      // to directly assign empty text and fire input.
+      el.innerHTML = ''
+      el.dispatchEvent(new InputEvent('input', { bubbles: true, inputType: 'deleteContentBackward' }))
+      el.focus()
+      return el.innerText.length === 0
+    })()`
+  )
+}
+
+async function snapshotCounts(cdp) {
+  // Counts via Runtime.evaluate using internal V8 counters where possible.
+  // For DOM stats we directly query the document.
+  // Performance metrics include JSHeapUsedSize, Nodes, JSEventListeners, etc.
+  const { metrics } = await cdp.send('Performance.getMetrics')
+  const byName = Object.fromEntries(metrics.map(m => [m.name, m.value]))
+  // Total nodes in document
+  const docNodes = await evalInPage(
+    cdp,
+    `document.getElementsByTagName('*').length + document.querySelectorAll('*').length / 2`
+  )
+  return {
+    heapUsedMB: (byName.JSHeapUsedSize / 1024 / 1024) || 0,
+    heapTotalMB: (byName.JSHeapTotalSize / 1024 / 1024) || 0,
+    nodes: byName.Nodes || 0,
+    jsListeners: byName.JSEventListeners || 0,
+    docNodes,
+    layoutCount: byName.LayoutCount || 0,
+    recalcStyleCount: byName.RecalcStyleCount || 0,
+    fps: byName.FramesPerSecond || 0
+  }
+}
+
+async function typeChars(cdp, text, cps) {
+  const intervalMs = Math.max(1, Math.round(1000 / cps))
+  const start = Date.now()
+  for (let i = 0; i < text.length; i++) {
+    await cdp.send('Input.dispatchKeyEvent', { type: 'char', text: text[i], unmodifiedText: text[i] })
+    const expected = start + (i + 1) * intervalMs
+    const wait = expected - Date.now()
+    if (wait > 0) await new Promise(r => setTimeout(r, wait))
+  }
+}
+
+const lorem =
+  'the quick brown fox jumps over the lazy dog while the agent thinks really hard about why typing into this composer feels like wading through molasses on a hot afternoon '
+function genText(n) {
+  let s = ''
+  while (s.length < n) s += lorem
+  return s.slice(0, n)
+}
+
+async function main() {
+  log(`port ${PORT} · ${ROUNDS} rounds × ${CHARS} chars @ ${CPS} cps`)
+  const tgt = await pickRenderer()
+  log(`target ${tgt.url}`)
+  const cdp = await connect(tgt.webSocketDebuggerUrl)
+  await cdp.send('Runtime.enable')
+  await cdp.send('Performance.enable')
+  await cdp.send('DOM.enable')
+
+  const focused = await focusComposer(cdp)
+  if (!focused) {
+    console.error('composer not focusable')
+    process.exit(2)
+  }
+
+  await forceGCAndSettle(cdp)
+  const baseline = await snapshotCounts(cdp)
+  log('baseline:', JSON.stringify(baseline))
+
+  const text = genText(CHARS)
+  const history = [{ round: 0, ...baseline, charsTyped: 0 }]
+
+  for (let r = 1; r <= ROUNDS; r++) {
+    await typeChars(cdp, text, CPS)
+    await new Promise(res => setTimeout(res, 200))
+    await clearComposer(cdp)
+    await forceGCAndSettle(cdp)
+    const snap = await snapshotCounts(cdp)
+    snap.charsTyped = r * CHARS
+    snap.round = r
+    history.push(snap)
+    log(
+      `round ${r}: heap=${snap.heapUsedMB.toFixed(1)}MB ` +
+        `nodes=${snap.nodes} listeners=${snap.jsListeners} ` +
+        `domNodes=${Math.round(snap.docNodes)} ` +
+        `layoutCount=${snap.layoutCount} ` +
+        `Δheap=+${(snap.heapUsedMB - baseline.heapUsedMB).toFixed(2)}MB ` +
+        `Δnodes=+${snap.nodes - baseline.nodes} ` +
+        `Δlisteners=+${snap.jsListeners - baseline.jsListeners}`
+    )
+  }
+
+  console.log('\n=== GROWTH PER ROUND (averaged over last 5 rounds) ===')
+  const tail = history.slice(-5)
+  const first = tail[0]
+  const last = tail[tail.length - 1]
+  const rounds = last.round - first.round
+  const cells = ['heapUsedMB', 'nodes', 'jsListeners', 'docNodes', 'layoutCount']
+  for (const c of cells) {
+    const delta = last[c] - first[c]
+    const per = delta / Math.max(1, rounds)
+    const perChar = delta / Math.max(1, rounds * CHARS)
+    console.log(`  ${c.padEnd(16)}  Δtotal=${delta.toFixed(2).padStart(10)}  /round=${per.toFixed(2).padStart(8)}  /char=${perChar.toFixed(4).padStart(8)}`)
+  }
+
+  writeFileSync('/tmp/hermes-leak-history.json', JSON.stringify(history, null, 2))
+  log('wrote /tmp/hermes-leak-history.json')
+  cdp.close()
+}
+
+main().catch(e => {
+  console.error('[leak] fatal:', e.stack ?? e.message)
+  process.exit(1)
+})

apps/desktop/scripts/measure-jump.mjs

@@ -0,0 +1,108 @@
+// Measure scroll position before and after Enter on a long thread.
+// The user's complaint: pressing Enter to submit makes the view "jump up".
+//
+// Steps:
+//   1. Scroll to the bottom of the thread
+//   2. Type a short message
+//   3. Record scroll position
+//   4. Hit Enter
+//   5. Record scroll position every 10ms for 1.5s after Enter
+//   6. Report deltas
+//
+// Usage:  node apps/desktop/scripts/measure-jump.mjs
+
+const list = await (await fetch('http://127.0.0.1:9222/json/list')).json()
+const tgt = list.find(t => t.type === 'page' && t.url.startsWith('http'))
+const ws = new WebSocket(tgt.webSocketDebuggerUrl)
+let id = 0
+const pending = new Map()
+ws.addEventListener('message', ev => {
+  const m = JSON.parse(ev.data)
+  if (m.id != null && pending.has(m.id)) {
+    pending.get(m.id)(m)
+    pending.delete(m.id)
+  }
+})
+await new Promise(r => ws.addEventListener('open', r))
+const send = (m, p = {}) =>
+  new Promise(r => {
+    const i = ++id
+    pending.set(i, r)
+    ws.send(JSON.stringify({ id: i, method: m, params: p }))
+  })
+const evalP = async expr => {
+  const r = await send('Runtime.evaluate', { expression: expr, returnByValue: true })
+  if (r.result?.exceptionDetails) throw new Error(r.result.exceptionDetails.text)
+  return r.result.result.value
+}
+
+// Scroll to bottom
+await evalP(`(() => {
+  const v = document.querySelector('[data-slot="aui_thread-viewport"]')
+  if (v) v.scrollTop = v.scrollHeight
+})()`)
+await new Promise(r => setTimeout(r, 300))
+
+// Focus composer and type
+await evalP(`(() => {
+  const el = document.querySelector('[data-slot="composer-rich-input"]')
+  el.focus()
+  const r = document.createRange(); r.selectNodeContents(el); r.collapse(false)
+  window.getSelection().removeAllRanges(); window.getSelection().addRange(r)
+})()`)
+
+const text = 'short follow-up message'
+for (const c of text) {
+  await send('Input.dispatchKeyEvent', { type: 'char', text: c, unmodifiedText: c })
+  await new Promise(r => setTimeout(r, 10))
+}
+await new Promise(r => setTimeout(r, 300))
+
+// Set up sampling — sample scroll position every animation frame
+await evalP(`(() => {
+  const v = document.querySelector('[data-slot="aui_thread-viewport"]')
+  window.__jumpSamples = []
+  window.__jumpStart = performance.now()
+  const tick = () => {
+    if (!v) return
+    window.__jumpSamples.push({
+      t: performance.now() - window.__jumpStart,
+      scrollTop: v.scrollTop,
+      scrollHeight: v.scrollHeight,
+      clientHeight: v.clientHeight,
+      distFromBottom: v.scrollHeight - v.scrollTop - v.clientHeight
+    })
+    if (performance.now() - window.__jumpStart < 2000) {
+      requestAnimationFrame(tick)
+    }
+  }
+  requestAnimationFrame(tick)
+})()`)
+
+// Fire Enter
+await send('Input.dispatchKeyEvent', {
+  type: 'rawKeyDown', windowsVirtualKeyCode: 13, key: 'Enter', code: 'Enter', text: '\r', unmodifiedText: '\r'
+})
+await send('Input.dispatchKeyEvent', { type: 'keyUp', windowsVirtualKeyCode: 13, key: 'Enter', code: 'Enter' })
+
+await new Promise(r => setTimeout(r, 2200))
+
+const samples = JSON.parse(await evalP(`JSON.stringify(window.__jumpSamples || [])`))
+console.log(`\n${samples.length} samples over 2s`)
+console.log(`\n  t(ms)  scrollTop  scrollHeight  clientHeight  distFromBottom`)
+let prev = null
+for (const s of samples) {
+  const marker = prev && Math.abs(s.scrollTop - prev.scrollTop) > 5 ? '  ← jump' : ''
+  console.log(`  ${String(s.t.toFixed(0)).padStart(5)}  ${String(s.scrollTop).padStart(9)}  ${String(s.scrollHeight).padStart(12)}  ${String(s.clientHeight).padStart(12)}  ${String(s.distFromBottom).padStart(14)}${marker}`)
+  prev = s
+}
+
+// Cancel any running agent
+await evalP(`(() => {
+  for (const b of document.querySelectorAll('button')) {
+    if ((b.getAttribute('aria-label') || '').toLowerCase().includes('stop')) { b.click(); return 'stopped' }
+  }
+  return 'no-stop'
+})()`).then(r => console.log('\ncancel:', r))
+
+ws.close()

apps/desktop/scripts/measure-latency.mjs

@@ -0,0 +1,184 @@
+#!/usr/bin/env node
+// Measure end-to-end keystroke→paint latency in the Electron renderer.
+//
+// For each synthetic keystroke we record:
+//   t0 = Input.dispatchKeyEvent send time
+//   t1 = first observed mutation of [data-slot="composer-rich-input"] childList/character data
+//   t2 = first requestAnimationFrame callback after t1 (proxy for next paint)
+//
+// We use Page.startScreencast briefly to also get frame-presentation timestamps;
+// alternatively rely on rAF timing which is close enough for typing UX.
+//
+// Output: per-char latency histogram (min/p50/p95/p99/max) + samples > 16ms.
+//
+// Usage:
+//   node apps/desktop/scripts/measure-latency.mjs [--chars=100] [--cps=15] [--port=9222]
+
+import { writeFileSync } from 'node:fs'
+
+const args = Object.fromEntries(
+  process.argv.slice(2).flatMap(s => {
+    const m = s.match(/^--([^=]+)(?:=(.*))?$/)
+    return m ? [[m[1], m[2] ?? true]] : []
+  })
+)
+const PORT = Number(args.port ?? 9222)
+const CHARS = Number(args.chars ?? 100)
+const CPS = Number(args.cps ?? 15)
+
+const log = (...m) => console.log('[latency]', ...m)
+
+async function pickRenderer() {
+  const list = await (await fetch(`http://127.0.0.1:${PORT}/json/list`)).json()
+  return list.find(t => t.type === 'page' && t.url.startsWith('http'))
+}
+
+function connect(url) {
+  return new Promise((resolve, reject) => {
+    const ws = new WebSocket(url)
+    let id = 0
+    const pending = new Map()
+    const events = new Map()
+    ws.addEventListener('open', () =>
+      resolve({
+        send(method, params = {}) {
+          const myId = ++id
+          ws.send(JSON.stringify({ id: myId, method, params }))
+          return new Promise((res, rej) => pending.set(myId, { res, rej }))
+        },
+        on(method, h) {
+          if (!events.has(method)) events.set(method, [])
+          events.get(method).push(h)
+        },
+        close: () => ws.close()
+      })
+    )
+    ws.addEventListener('error', reject)
+    ws.addEventListener('message', ev => {
+      const m = JSON.parse(typeof ev.data === 'string' ? ev.data : ev.data.toString('utf8'))
+      if (m.id != null) {
+        const p = pending.get(m.id)
+        if (!p) return
+        pending.delete(m.id)
+        m.error ? p.rej(new Error(m.error.message)) : p.res(m.result)
+      } else if (m.method) {
+        ;(events.get(m.method) ?? []).forEach(h => h(m.params))
+      }
+    })
+  })
+}
+
+async function evalInPage(cdp, expr) {
+  const r = await cdp.send('Runtime.evaluate', { expression: expr, returnByValue: true })
+  if (r.exceptionDetails) throw new Error(r.exceptionDetails.text)
+  return r.result.value
+}
+
+async function main() {
+  const tgt = await pickRenderer()
+  log(`target ${tgt.url}`)
+  const cdp = await connect(tgt.webSocketDebuggerUrl)
+  await cdp.send('Runtime.enable')
+
+  await evalInPage(
+    cdp,
+    `(() => {
+      const el = document.querySelector('[data-slot="composer-rich-input"]')
+      if (!el) return false
+      el.focus()
+      const range = document.createRange()
+      range.selectNodeContents(el)
+      range.collapse(false)
+      const sel = window.getSelection()
+      sel.removeAllRanges()
+      sel.addRange(range)
+      window.__keypressTimings = []
+      window.__pendingKey = null
+      // Observe the composer for content/text changes; record the time relative
+      // to the most recent simulated keypress timestamp set on window.__pendingKey.
+      const obs = new MutationObserver(() => {
+        const start = window.__pendingKey
+        if (start === null) return
+        const mutationT = performance.now()
+        window.__pendingKey = null
+        requestAnimationFrame(() => {
+          const paintT = performance.now()
+          window.__keypressTimings.push({
+            start, mutationT, paintT,
+            mutationLatency: mutationT - start,
+            paintLatency: paintT - start
+          })
+        })
+      })
+      obs.observe(el, { childList: true, subtree: true, characterData: true })
+      window.__keystrokeObserver = obs
+      return true
+    })()`
+  )
+
+  const lorem =
+    'the quick brown fox jumps over the lazy dog while typing into this composer feels like wading through molasses on a hot afternoon. '
+  let text = ''
+  while (text.length < CHARS) text += lorem
+  text = text.slice(0, CHARS)
+
+  const intervalMs = Math.max(1, Math.round(1000 / CPS))
+  const start = Date.now()
+  for (let i = 0; i < text.length; i++) {
+    // Mark the keypress time inside the page so it's measured from the same clock.
+    await evalInPage(cdp, `window.__pendingKey = performance.now()`)
+    await cdp.send('Input.dispatchKeyEvent', { type: 'char', text: text[i], unmodifiedText: text[i] })
+    const expected = start + (i + 1) * intervalMs
+    const wait = expected - Date.now()
+    if (wait > 0) await new Promise(r => setTimeout(r, wait))
+  }
+
+  await new Promise(r => setTimeout(r, 500))
+  const samples = await evalInPage(cdp, `window.__keypressTimings`)
+  log(`${samples.length} keystroke samples measured out of ${text.length} typed`)
+
+  // Clear composer for next run
+  await evalInPage(cdp, `
+    (() => {
+      const el = document.querySelector('[data-slot="composer-rich-input"]')
+      if (el) { el.innerHTML = ''; el.dispatchEvent(new InputEvent('input', { bubbles: true, inputType: 'deleteContentBackward' })) }
+      window.__keystrokeObserver?.disconnect()
+    })()
+  `)
+
+  const mutLat = samples.map(s => s.mutationLatency).sort((a, b) => a - b)
+  const paintLat = samples.map(s => s.paintLatency).sort((a, b) => a - b)
+  const stat = arr => ({
+    n: arr.length,
+    min: arr[0]?.toFixed(2),
+    p50: arr[Math.floor(arr.length * 0.5)]?.toFixed(2),
+    p90: arr[Math.floor(arr.length * 0.9)]?.toFixed(2),
+    p95: arr[Math.floor(arr.length * 0.95)]?.toFixed(2),
+    p99: arr[Math.floor(arr.length * 0.99)]?.toFixed(2),
+    max: arr[arr.length - 1]?.toFixed(2),
+    mean: arr.length ? (arr.reduce((s, x) => s + x, 0) / arr.length).toFixed(2) : 0
+  })
+
+  console.log('\n=== keypress → mutation latency (ms) ===')
+  console.log(' ', stat(mutLat))
+  console.log('\n=== keypress → next rAF (≈paint) latency (ms) ===')
+  console.log(' ', stat(paintLat))
+
+  const slow = samples.filter(s => s.paintLatency > 16)
+  console.log(`\n=== ${slow.length}/${samples.length} keystrokes >16ms (one frame) ===`)
+  if (slow.length) {
+    const slowSorted = [...slow].sort((a, b) => b.paintLatency - a.paintLatency).slice(0, 10)
+    for (const s of slowSorted) {
+      console.log(`  paint=${s.paintLatency.toFixed(1)}ms  mut=${s.mutationLatency.toFixed(1)}ms  at t=${s.start.toFixed(0)}`)
+    }
+  }
+
+  writeFileSync('/tmp/hermes-latency-samples.json', JSON.stringify(samples, null, 2))
+
+  cdp.close()
+}
+
+main().catch(e => {
+  console.error('[latency] fatal:', e.stack ?? e.message)
+  process.exit(1)
+})

apps/desktop/scripts/measure-real-stream.mjs

@@ -0,0 +1,252 @@
+// REAL streaming measurement — no React internals.
+//
+// Measures:
+//   1) rAF frame intervals during a verified live stream (long-frame histogram)
+//   2) MutationObserver: how often does the live assistant message mutate, what's the budget per mutation
+//   3) Text length growth rate (chars/sec)
+//   4) PerformanceObserver `longtask` entries (any task > 50ms blocks input)
+//
+// Detects REAL stream by waiting for assistant-message DOM count to grow past baseline.
+// Does NOT cancel — lets the stream run to completion or hits TIMEOUT_MS.
+
+const CDP_HTTP = 'http://127.0.0.1:9222'
+const PROMPT = process.env.PROMPT || 'count from 1 to 80, one number per line'
+const TIMEOUT_MS = Number(process.env.TIMEOUT_MS || 60000)
+
+async function getTarget() {
+  const list = await (await fetch(`${CDP_HTTP}/json`)).json()
+  const t = list.find((t) => t.type === 'page' && /5174/.test(t.url))
+  if (!t) throw new Error('renderer not found')
+  return t
+}
+
+class CDP {
+  constructor(ws) { this.ws = ws; this.id = 0; this.pending = new Map() }
+  static async open(url) {
+    const ws = new WebSocket(url)
+    await new Promise((r, j) => {
+      ws.addEventListener('open', r, { once: true })
+      ws.addEventListener('error', (e) => j(e), { once: true })
+    })
+    const cdp = new CDP(ws)
+    ws.addEventListener('message', (event) => {
+      const m = JSON.parse(event.data.toString())
+      if (m.id != null && cdp.pending.has(m.id)) {
+        const { resolve, reject } = cdp.pending.get(m.id)
+        cdp.pending.delete(m.id)
+        if (m.error) reject(new Error(m.error.message))
+        else resolve(m.result)
+      }
+    })
+    return cdp
+  }
+  send(method, params) {
+    const id = ++this.id
+    return new Promise((res, rej) => {
+      this.pending.set(id, { resolve: res, reject: rej })
+      this.ws.send(JSON.stringify({ id, method, params }))
+    })
+  }
+  async eval(expr) {
+    const r = await this.send('Runtime.evaluate', { expression: expr, returnByValue: true, awaitPromise: true })
+    if (r.exceptionDetails) throw new Error(r.exceptionDetails.exception?.description || 'eval')
+    return r.result.value
+  }
+  close() { this.ws.close() }
+}
+
+async function main() {
+  const target = await getTarget()
+  const cdp = await CDP.open(target.webSocketDebuggerUrl)
+
+  // Install recorders.
+  await cdp.eval(`
+    (() => {
+      // rAF frame intervals
+      window.__FT__ = { times: [], stop: false }
+      let last = performance.now()
+      const tick = () => {
+        if (window.__FT__.stop) return
+        const now = performance.now()
+        window.__FT__.times.push(now - last)
+        last = now
+        requestAnimationFrame(tick)
+      }
+      requestAnimationFrame(tick)
+
+      // longtask observer
+      window.__LT__ = { entries: [], stop: false }
+      try {
+        const po = new PerformanceObserver((list) => {
+          if (window.__LT__.stop) return
+          for (const e of list.getEntries()) {
+            window.__LT__.entries.push({ name: e.name, duration: e.duration, startTime: e.startTime })
+          }
+        })
+        po.observe({ entryTypes: ['longtask'] })
+        window.__LT__.po = po
+      } catch {}
+
+      // mutation observer on streaming message
+      window.__MO__ = { mutations: [], stop: false, currentMsg: null }
+      const tryArm = () => {
+        const all = document.querySelectorAll('[data-slot="aui_assistant-message-root"]')
+        const last = all[all.length - 1]
+        if (!last || last === window.__MO__.currentMsg) return
+        window.__MO__.currentMsg = last
+        if (window.__MO__.obs) window.__MO__.obs.disconnect()
+        const obs = new MutationObserver((muts) => {
+          if (window.__MO__.stop) return
+          const t = performance.now()
+          window.__MO__.mutations.push({ t, count: muts.length, len: last.textContent.length })
+        })
+        obs.observe(last, { childList: true, subtree: true, characterData: true })
+        window.__MO__.obs = obs
+      }
+      window.__MO__.arm = tryArm
+      return 'recorders armed'
+    })()
+  `)
+
+  // Baseline
+  const base = JSON.parse(await cdp.eval(`
+    JSON.stringify({
+      assistantCount: document.querySelectorAll('[data-slot="aui_assistant-message-root"]').length,
+      busy: !!document.querySelector('[data-status="running"], [data-busy="true"]'),
+      hasComposer: !!document.querySelector('[contenteditable="true"]'),
+    })
+  `))
+  console.log('baseline:', base)
+  if (!base.hasComposer) { console.error('no composer'); cdp.close(); return }
+
+  // Type + submit
+  await cdp.eval(`
+    (() => {
+      const ed = document.querySelector('[contenteditable="true"]')
+      ed.focus()
+      document.execCommand('insertText', false, ${JSON.stringify(PROMPT)})
+      return 'typed'
+    })()
+  `)
+  const submitT0 = Date.now()
+  await cdp.eval(`
+    (() => {
+      const ed = document.querySelector('[contenteditable="true"]')
+      ed.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', code: 'Enter', bubbles: true, cancelable: true }))
+      return 'submitted'
+    })()
+  `)
+
+  // Poll for REAL stream (assistant count > baseline). 30 seconds — accommodates
+  // slow first-token latencies on big providers.
+  let realStreamT = null
+  for (let i = 0; i < 600; i++) {
+    await new Promise((r) => setTimeout(r, 50))
+    const s = JSON.parse(await cdp.eval(`
+      JSON.stringify({
+        n: document.querySelectorAll('[data-slot="aui_assistant-message-root"]').length,
+        busy: !!document.querySelector('[data-status="running"], [data-busy="true"]'),
+        text: (() => { const a = document.querySelectorAll('[data-slot="aui_assistant-message-root"]'); return a.length ? a[a.length-1].textContent.length : 0 })()
+      })
+    `))
+    if (s.n > base.assistantCount) {
+      realStreamT = Date.now()
+      console.log('REAL stream started after', realStreamT - submitT0, 'ms — busy=', s.busy, 'text=', s.text)
+      // Arm mutation observer on the new message
+      await cdp.eval('window.__MO__.arm()')
+      break
+    }
+  }
+  if (!realStreamT) {
+    console.error('REAL STREAM NEVER STARTED')
+    cdp.close()
+    return
+  }
+
+  // Sample length growth, wait for completion or timeout
+  const samples = []
+  const start = Date.now()
+  while (Date.now() - start < TIMEOUT_MS) {
+    await new Promise((r) => setTimeout(r, 250))
+    const s = JSON.parse(await cdp.eval(`
+      JSON.stringify({
+        t: performance.now(),
+        len: (() => { const a = document.querySelectorAll('[data-slot="aui_assistant-message-root"]'); return a.length ? a[a.length-1].textContent.length : 0 })(),
+        busy: !!document.querySelector('[data-status="running"], [data-busy="true"]')
+      })
+    `))
+    samples.push(s)
+    if (!s.busy && samples.length > 4) {
+      await new Promise((r) => setTimeout(r, 300))
+      break
+    }
+  }
+
+  // Pull recordings
+  const data = JSON.parse(await cdp.eval(`
+    (() => {
+      window.__FT__.stop = true
+      window.__LT__.stop = true
+      window.__MO__.stop = true
+      try { window.__LT__.po && window.__LT__.po.disconnect() } catch {}
+      try { window.__MO__.obs && window.__MO__.obs.disconnect() } catch {}
+      return JSON.stringify({
+        frames: window.__FT__.times,
+        longtasks: window.__LT__.entries,
+        mutations: window.__MO__.mutations,
+      })
+    })()
+  `))
+
+  const { frames, longtasks, mutations } = data
+
+  // Frame histogram (filter to stream window)
+  const buckets = { '<=16.7': 0, '16.7-33': 0, '33-50': 0, '50-100': 0, '100-200': 0, '>200': 0 }
+  let frameTotal = 0
+  let maxFrame = 0
+  for (const f of frames) {
+    frameTotal += f
+    if (f > maxFrame) maxFrame = f
+    if (f <= 16.7) buckets['<=16.7']++
+    else if (f <= 33) buckets['16.7-33']++
+    else if (f <= 50) buckets['33-50']++
+    else if (f <= 100) buckets['50-100']++
+    else if (f <= 200) buckets['100-200']++
+    else buckets['>200']++
+  }
+  const avgFps = frames.length ? (frames.length / (frameTotal / 1000)).toFixed(1) : 'n/a'
+  const slowFrames = frames.filter((f) => f > 33).length
+  const veryslowFrames = frames.filter((f) => f > 100).length
+
+  // Longtask summary
+  const ltMs = longtasks.reduce((a, b) => a + b.duration, 0)
+  const ltMax = longtasks.length ? Math.max(...longtasks.map((e) => e.duration)) : 0
+
+  // Mutation rate
+  let mutTotal = mutations.length
+  let mutDurs = []
+  for (let i = 1; i < mutations.length; i++) {
+    mutDurs.push(mutations[i].t - mutations[i - 1].t)
+  }
+  mutDurs.sort((a, b) => a - b)
+  const mutP50 = mutDurs[Math.floor(mutDurs.length * 0.5)] ?? 0
+  const mutP95 = mutDurs[Math.floor(mutDurs.length * 0.95)] ?? 0
+
+  // Growth rate
+  const firstLen = samples[0]?.len ?? 0
+  const lastLen = samples[samples.length - 1]?.len ?? 0
+  const elapsedS = samples.length ? (samples[samples.length - 1].t - samples[0].t) / 1000 : 0
+  const charsPerSec = elapsedS ? ((lastLen - firstLen) / elapsedS).toFixed(1) : 'n/a'
+
+  console.log('\n=== STREAM RESULTS ===')
+  console.log('window:', (frameTotal / 1000).toFixed(1), 's | frames:', frames.length, '| avgFps:', avgFps, '| maxFrame:', maxFrame.toFixed(1), 'ms')
+  console.log('frame histogram:', buckets)
+  console.log('slow frames (>33ms):', slowFrames, '| very slow (>100ms):', veryslowFrames)
+  console.log('longtasks:', longtasks.length, 'total', ltMs.toFixed(0), 'ms — max', ltMax.toFixed(1), 'ms')
+  console.log('text grew', firstLen, '→', lastLen, 'chars (', charsPerSec, 'char/s )')
+  console.log('mutations on streaming msg:', mutTotal, '| inter-mutation p50:', mutP50.toFixed(1), 'ms', 'p95:', mutP95.toFixed(1), 'ms')
+
+  cdp.close()
+}
+
+main().catch((e) => { console.error(e); process.exit(1) })

apps/desktop/scripts/measure-submit.mjs

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+// Measure submit (Enter) latency in the composer.
+//
+// For each round:
+//   1. Focus composer, type N chars of stub text
+//   2. Mark a timestamp, fire Enter via Input.dispatchKeyEvent
+//   3. Observe: time until the composer becomes empty (submit accepted),
+//      time until the user message renders in the thread viewport,
+//      time until the optional "running…" indicator appears,
+//      time until the next frame is painted after the message renders.
+//
+// Pre-condition: a session is loaded (load via click-session.mjs first).
+// Note: this DOES talk to the real gateway/agent, so each round triggers
+//       a real prompt submission. Don't run this on a live conversation
+//       you care about — use a throwaway session.
+
+import { writeFileSync } from 'node:fs'
+
+const args = Object.fromEntries(
+  process.argv.slice(2).flatMap(s => {
+    const m = s.match(/^--([^=]+)(?:=(.*))?$/)
+    return m ? [[m[1], m[2] ?? true]] : []
+  })
+)
+const PORT = Number(args.port ?? 9222)
+const ROUNDS = Number(args.rounds ?? 3)
+
+async function pickRenderer() {
+  const list = await (await fetch(`http://127.0.0.1:${PORT}/json/list`)).json()
+  return list.find(t => t.type === 'page' && t.url.startsWith('http'))
+}
+
+function connect(url) {
+  return new Promise((resolve, reject) => {
+    const ws = new WebSocket(url)
+    let id = 0
+    const pending = new Map()
+    ws.addEventListener('open', () =>
+      resolve({
+        send(method, params = {}) {
+          const myId = ++id
+          ws.send(JSON.stringify({ id: myId, method, params }))
+          return new Promise((res, rej) => pending.set(myId, { res, rej }))
+        },
+        close: () => ws.close()
+      })
+    )
+    ws.addEventListener('error', reject)
+    ws.addEventListener('message', ev => {
+      const m = JSON.parse(typeof ev.data === 'string' ? ev.data : ev.data.toString('utf8'))
+      if (m.id != null) {
+        const p = pending.get(m.id)
+        if (!p) return
+        pending.delete(m.id)
+        m.error ? p.rej(new Error(m.error.message)) : p.res(m.result)
+      }
+    })
+  })
+}
+
+async function evalP(cdp, expr) {
+  const r = await cdp.send('Runtime.evaluate', { expression: expr, returnByValue: true, awaitPromise: true })
+  if (r.exceptionDetails) throw new Error(r.exceptionDetails.text)
+  return r.result.value
+}
+
+async function focusAndType(cdp, text) {
+  await evalP(cdp, `
+    (() => {
+      const el = document.querySelector('[data-slot="composer-rich-input"]')
+      if (!el) return
+      el.focus()
+      const range = document.createRange()
+      range.selectNodeContents(el)
+      range.collapse(false)
+      const sel = window.getSelection()
+      sel.removeAllRanges()
+      sel.addRange(range)
+    })()
+  `)
+  for (const c of text) {
+    await cdp.send('Input.dispatchKeyEvent', { type: 'char', text: c, unmodifiedText: c })
+    await new Promise(r => setTimeout(r, 8))
+  }
+}
+
+async function submitAndMeasure(cdp, timeoutMs = 5000) {
+  // Install observers, record submit time as performance.now() inside the page,
+  // and wait for all milestones.
+  return await evalP(cdp, `
+    new Promise((resolve) => {
+      const composer = document.querySelector('[data-slot="composer-rich-input"]')
+      const threadRoot = document.querySelector('[data-slot="aui_thread-content"]') ||
+                         document.querySelector('[data-slot="aui_thread-viewport"]')
+      const startMessageCount = threadRoot ? threadRoot.querySelectorAll('[data-slot="aui_turn-pair"], [data-slot="aui_message"]').length : 0
+      const startComposerText = composer ? composer.innerText : ''
+
+      const milestones = { start: performance.now() }
+      let done = false
+      const finish = (reason) => {
+        if (done) return
+        done = true
+        clearInterval(poll); clearTimeout(timer)
+        composerObs.disconnect()
+        threadObs?.disconnect()
+        milestones.reason = reason
+        milestones.end = performance.now()
+        milestones.totalMs = milestones.end - milestones.start
+        resolve(milestones)
+      }
+
+      const composerObs = new MutationObserver(() => {
+        if (!milestones.composerClearedMs && composer && composer.innerText.length === 0) {
+          milestones.composerClearedMs = performance.now() - milestones.start
+        }
+      })
+      composer && composerObs.observe(composer, { childList: true, subtree: true, characterData: true })
+
+      let threadObs = null
+      if (threadRoot) {
+        threadObs = new MutationObserver(() => {
+          const c = threadRoot.querySelectorAll('[data-slot="aui_turn-pair"], [data-slot="aui_message"]').length
+          if (!milestones.userMessageRenderedMs && c > startMessageCount) {
+            milestones.userMessageRenderedMs = performance.now() - milestones.start
+            requestAnimationFrame(() => {
+              milestones.userMessagePaintMs = performance.now() - milestones.start
+              finish('paint')
+            })
+          }
+        })
+        threadObs.observe(threadRoot, { childList: true, subtree: true })
+      }
+
+      const poll = setInterval(() => {
+        if (milestones.composerClearedMs && !milestones.userMessageRenderedMs &&
+            performance.now() - milestones.start > 2000) {
+          finish('timeout-after-clear')
+        }
+      }, 100)
+      const timer = setTimeout(() => finish('timeout-overall'), ${timeoutMs})
+
+      // Send Enter immediately
+      window.dispatchEvent(new KeyboardEvent('keydown'))  // no-op marker
+      const enterEv = new KeyboardEvent('keydown', { key: 'Enter', code: 'Enter', bubbles: true, cancelable: true })
+      composer?.dispatchEvent(enterEv)
+    })
+  `)
+}
+
+async function main() {
+  const tgt = await pickRenderer()
+  console.log('target', tgt.url)
+  const cdp = await connect(tgt.webSocketDebuggerUrl)
+  await cdp.send('Runtime.enable')
+
+  const samples = []
+  for (let i = 1; i <= ROUNDS; i++) {
+    await focusAndType(cdp, `latency test ${i} ${'x'.repeat(40)}`)
+    await new Promise(r => setTimeout(r, 300))
+    const result = await submitAndMeasure(cdp, 4000)
+    samples.push({ round: i, ...result })
+    console.log(
+      `r${i}: clear=${(result.composerClearedMs ?? -1).toFixed?.(0) ?? '?'}ms ` +
+        `userMsg=${(result.userMessageRenderedMs ?? -1).toFixed?.(0) ?? '?'}ms ` +
+        `paint=${(result.userMessagePaintMs ?? -1).toFixed?.(0) ?? '?'}ms ` +
+        `reason=${result.reason}`
+    )
+    // wait for any agent activity to finish before next round so we're not piling up
+    await new Promise(r => setTimeout(r, 4000))
+  }
+  writeFileSync('/tmp/hermes-submit-latency.json', JSON.stringify(samples, null, 2))
+  console.log('\nwrote /tmp/hermes-submit-latency.json')
+  cdp.close()
+}
+
+main().catch(e => {
+  console.error('fatal:', e.stack ?? e.message)
+  process.exit(1)
+})

apps/desktop/scripts/measure-synthetic-stream.mjs

@@ -0,0 +1,322 @@
+// Measure render cost of a synthetic stream driven through the live $messages atom.
+//
+// Why synthetic: the user's LLM credits are depleted; we can't fire a real stream.
+// The synthetic stream exercises the exact same React pipeline (assistant-ui runtime →
+// repository.addOrUpdateMessage → MessagePrimitive re-render → markdown reflow) as a
+// real stream. The only thing it does NOT exercise is the gateway → SSE → optimistic-
+// merge path, which is orthogonal to the rendering question.
+//
+// What we record:
+//   1) rAF frame intervals (long-frame histogram; >33ms = perceived jank, >100ms = bad)
+//   2) PerformanceObserver `longtask` entries (task >50ms blocks input)
+//   3) MutationObserver: per-message mutation count & inter-mutation latency
+//   4) Optional: typing latency overlay — typing into composer while streaming
+//
+// Output is plain text suitable for terminal + a JSON sidecar for diffing across runs.
+
+import { writeFileSync } from 'node:fs'
+
+const CDP_HTTP = 'http://127.0.0.1:9222'
+const TOKENS = Number(process.env.TOKENS || 300)
+const INTERVAL_MS = Number(process.env.INTERVAL_MS || 16)
+// Upstream flush throttle to apply in the synthetic driver. Mirrors what the
+// real gateway path does in `use-message-stream.scheduleDeltaFlush`. 0
+// disables (worst-case, every token = one React commit).
+const FLUSH_MIN_MS = Number(process.env.FLUSH_MIN_MS || 0)
+const CHUNK = process.env.CHUNK || 'lorem ipsum '
+const TYPE_WHILE_STREAMING = process.env.TYPE_WHILE_STREAMING === '1'
+const LABEL = process.env.LABEL || 'baseline'
+const OUT = process.env.OUT || `frame-times-${LABEL}.json`
+
+async function getTarget() {
+  const list = await (await fetch(`${CDP_HTTP}/json`)).json()
+  const t = list.find((t) => t.type === 'page' && /5174/.test(t.url))
+  if (!t) throw new Error('renderer not found')
+  return t
+}
+
+class CDP {
+  constructor(ws) { this.ws = ws; this.id = 0; this.pending = new Map() }
+  static async open(url) {
+    const ws = new WebSocket(url)
+    await new Promise((r, j) => {
+      ws.addEventListener('open', r, { once: true })
+      ws.addEventListener('error', (e) => j(e), { once: true })
+    })
+    const cdp = new CDP(ws)
+    ws.addEventListener('message', (ev) => {
+      const m = JSON.parse(ev.data.toString())
+      if (m.id != null && cdp.pending.has(m.id)) {
+        const { resolve, reject } = cdp.pending.get(m.id)
+        cdp.pending.delete(m.id)
+        if (m.error) reject(new Error(m.error.message))
+        else resolve(m.result)
+      }
+    })
+    return cdp
+  }
+  send(method, params) {
+    const id = ++this.id
+    return new Promise((res, rej) => {
+      this.pending.set(id, { resolve: res, reject: rej })
+      this.ws.send(JSON.stringify({ id, method, params }))
+    })
+  }
+  async eval(expr) {
+    const r = await this.send('Runtime.evaluate', { expression: expr, returnByValue: true, awaitPromise: true })
+    if (r.exceptionDetails) throw new Error(r.exceptionDetails.exception?.description || 'eval')
+    return r.result.value
+  }
+  close() { this.ws.close() }
+}
+
+function pct(arr, p) {
+  if (!arr.length) return 0
+  const i = Math.min(arr.length - 1, Math.floor(arr.length * p))
+  return arr[i]
+}
+
+async function main() {
+  const target = await getTarget()
+  const cdp = await CDP.open(target.webSocketDebuggerUrl)
+
+  // Sanity check driver is loaded.
+  const probeOk = await cdp.eval('!!window.__PERF_DRIVE__ && !!window.__PERF_DRIVE__.stream')
+  if (!probeOk) {
+    console.error('__PERF_DRIVE__ not on window — did you reload the renderer after editing perf-probe.tsx?')
+    cdp.close()
+    process.exit(2)
+  }
+
+  // Install recorders.
+  await cdp.eval(`
+    (() => {
+      window.__FT__ = { times: [], stop: false }
+      let last = performance.now()
+      const tick = () => {
+        if (window.__FT__.stop) return
+        const now = performance.now()
+        window.__FT__.times.push(now - last)
+        last = now
+        requestAnimationFrame(tick)
+      }
+      requestAnimationFrame(tick)
+
+      window.__LT__ = { entries: [], stop: false }
+      try {
+        const po = new PerformanceObserver((list) => {
+          if (window.__LT__.stop) return
+          for (const e of list.getEntries()) {
+            window.__LT__.entries.push({ name: e.name, duration: e.duration, startTime: e.startTime })
+          }
+        })
+        po.observe({ entryTypes: ['longtask'] })
+        window.__LT__.po = po
+      } catch {}
+
+      window.__MO__ = { mutations: [], stop: false, currentMsg: null }
+      const arm = () => {
+        const all = document.querySelectorAll('[data-slot="aui_assistant-message-root"]')
+        const last = all[all.length - 1]
+        if (!last || last === window.__MO__.currentMsg) return
+        window.__MO__.currentMsg = last
+        if (window.__MO__.obs) window.__MO__.obs.disconnect()
+        const obs = new MutationObserver((muts) => {
+          if (window.__MO__.stop) return
+          const t = performance.now()
+          window.__MO__.mutations.push({ t, count: muts.length, len: last.textContent.length })
+        })
+        obs.observe(last, { childList: true, subtree: true, characterData: true })
+        window.__MO__.obs = obs
+      }
+      window.__MO__.arm = arm
+
+      // Optional: typing observer — fires keystroke timings if asked.
+      window.__TYP__ = { times: [], stop: false, lastKey: 0 }
+      return 'recorders armed'
+    })()
+  `)
+
+  // Baseline state.
+  const base = JSON.parse(await cdp.eval(`
+    JSON.stringify({
+      assistantCount: document.querySelectorAll('[data-slot="aui_assistant-message-root"]').length,
+      atomCount: window.__PERF_DRIVE__.snapshotMsgs()
+    })
+  `))
+  console.log('baseline:', base)
+
+  // Drive a synthetic stream.
+  const streamStart = Date.now()
+  await cdp.eval(`window.__PERF_DRIVE__.stream({ chunk: ${JSON.stringify(CHUNK)}, intervalMs: ${INTERVAL_MS}, totalTokens: ${TOKENS}, flushMinMs: ${FLUSH_MIN_MS} })`)
+
+  // After the first paint, arm MO on the new message.
+  await new Promise((r) => setTimeout(r, 200))
+  await cdp.eval('window.__MO__.arm()')
+
+  // Optional: type while streaming.
+  if (TYPE_WHILE_STREAMING) {
+    await new Promise((r) => setTimeout(r, 400))
+    await cdp.eval(`(() => {
+      const ed = document.querySelector('[contenteditable="true"]')
+      ed.focus()
+      window.__TYP__.startedAt = performance.now()
+      const text = 'the quick brown fox jumps over the lazy dog '
+      let i = 0
+      const tick = () => {
+        if (i >= text.length) return
+        const t0 = performance.now()
+        document.execCommand('insertText', false, text[i])
+        // requestAnimationFrame to wait for next paint
+        requestAnimationFrame(() => {
+          window.__TYP__.times.push(performance.now() - t0)
+        })
+        i++
+        setTimeout(tick, 60)
+      }
+      tick()
+      return 'typing'
+    })()`)
+  }
+
+  // Wait for stream to complete + small grace.
+  const expectedMs = TOKENS * INTERVAL_MS + 1500
+  await new Promise((r) => setTimeout(r, expectedMs))
+
+  // Pull recordings.
+  const data = JSON.parse(await cdp.eval(`
+    (() => {
+      window.__FT__.stop = true
+      window.__LT__.stop = true
+      window.__MO__.stop = true
+      window.__TYP__.stop = true
+      try { window.__LT__.po && window.__LT__.po.disconnect() } catch {}
+      try { window.__MO__.obs && window.__MO__.obs.disconnect() } catch {}
+      return JSON.stringify({
+        frames: window.__FT__.times,
+        longtasks: window.__LT__.entries,
+        mutations: window.__MO__.mutations,
+        typing: window.__TYP__.times,
+        finalText: (() => { const a = document.querySelectorAll('[data-slot="aui_assistant-message-root"]'); return a.length ? a[a.length-1].textContent.length : 0 })()
+      })
+    })()
+  `))
+
+  // Reset DOM back to baseline so we don't accumulate fake messages.
+  await cdp.eval('window.__PERF_DRIVE__.reset()')
+
+  // Analysis (trim warm-up: drop frames before first mutation timestamp).
+  const firstMut = data.mutations[0]?.t
+  const frames = data.frames
+
+  // Sum durations to figure out when each frame happened (relative to recorder start).
+  const frameTimeline = []
+  let acc = 0
+  for (const f of frames) { acc += f; frameTimeline.push(acc) }
+
+  // Mutations are in performance.now() ms; frames started recording when we installed
+  // the recorder (before stream). To align: compute total stream window from frames
+  // after mutation activity began. Simpler heuristic: drop first 500ms of frames as warm-up.
+  const WARMUP_MS = 500
+  let dropIdx = 0
+  for (let i = 0; i < frames.length; i++) {
+    if (frameTimeline[i] >= WARMUP_MS) { dropIdx = i; break }
+  }
+  const streamFrames = frames.slice(dropIdx)
+
+  const buckets = { '<=16.7': 0, '16.7-33': 0, '33-50': 0, '50-100': 0, '100-200': 0, '>200': 0 }
+  let frameTotal = 0
+  let maxFrame = 0
+  for (const f of streamFrames) {
+    frameTotal += f
+    if (f > maxFrame) maxFrame = f
+    if (f <= 16.7) buckets['<=16.7']++
+    else if (f <= 33) buckets['16.7-33']++
+    else if (f <= 50) buckets['33-50']++
+    else if (f <= 100) buckets['50-100']++
+    else if (f <= 200) buckets['100-200']++
+    else buckets['>200']++
+  }
+  const sortedFrames = [...streamFrames].sort((a, b) => a - b)
+  const fAvgFps = streamFrames.length ? (streamFrames.length / (frameTotal / 1000)).toFixed(1) : 'n/a'
+  const fP50 = pct(sortedFrames, 0.5).toFixed(1)
+  const fP95 = pct(sortedFrames, 0.95).toFixed(1)
+  const fP99 = pct(sortedFrames, 0.99).toFixed(1)
+  const slowFrames = streamFrames.filter((f) => f > 33).length
+  const veryslowFrames = streamFrames.filter((f) => f > 100).length
+
+  const ltDur = data.longtasks.map((e) => e.duration).sort((a, b) => a - b)
+  const ltMs = ltDur.reduce((a, b) => a + b, 0)
+  const ltMax = ltDur.length ? ltDur[ltDur.length - 1] : 0
+  const ltP95 = pct(ltDur, 0.95)
+
+  // Mutation cadence.
+  const mutDurs = []
+  for (let i = 1; i < data.mutations.length; i++) mutDurs.push(data.mutations[i].t - data.mutations[i - 1].t)
+  mutDurs.sort((a, b) => a - b)
+  const mutP50 = pct(mutDurs, 0.5)
+  const mutP95 = pct(mutDurs, 0.95)
+  const mutMax = mutDurs.length ? mutDurs[mutDurs.length - 1] : 0
+
+  // Typing latency (optional).
+  let typingSummary = null
+  if (TYPE_WHILE_STREAMING && data.typing.length) {
+    const t = [...data.typing].sort((a, b) => a - b)
+    typingSummary = {
+      n: t.length,
+      p50: pct(t, 0.5).toFixed(1),
+      p95: pct(t, 0.95).toFixed(1),
+      max: t[t.length - 1].toFixed(1)
+    }
+  }
+
+  const result = {
+    label: LABEL,
+    timestamp: new Date().toISOString(),
+    config: { TOKENS, INTERVAL_MS, CHUNK, TYPE_WHILE_STREAMING, FLUSH_MIN_MS },
+    streamWallMs: Date.now() - streamStart,
+    frames: {
+      total: streamFrames.length,
+      avgFps: fAvgFps,
+      windowS: (frameTotal / 1000).toFixed(1),
+      p50: fP50,
+      p95: fP95,
+      p99: fP99,
+      max: maxFrame.toFixed(1),
+      slow33: slowFrames,
+      veryslow100: veryslowFrames,
+      histogram: buckets
+    },
+    longtasks: {
+      n: data.longtasks.length,
+      totalMs: ltMs.toFixed(0),
+      maxMs: ltMax.toFixed(1),
+      p95Ms: ltP95.toFixed(1)
+    },
+    mutations: {
+      n: data.mutations.length,
+      finalTextLen: data.finalText,
+      interMutP50ms: mutP50.toFixed(1),
+      interMutP95ms: mutP95.toFixed(1),
+      interMutMaxMs: mutMax.toFixed(1)
+    },
+    typing: typingSummary
+  }
+
+  writeFileSync(OUT, JSON.stringify(result, null, 2))
+
+  console.log('\n=== SYNTHETIC STREAM RESULTS ===')
+  console.log('label:', LABEL, '| tokens:', TOKENS, '@', INTERVAL_MS, 'ms')
+  console.log('streamWallMs:', result.streamWallMs)
+  console.log('FRAMES: avgFps', fAvgFps, '| p50', fP50, 'ms | p95', fP95, 'ms | p99', fP99, 'ms | max', maxFrame.toFixed(1), 'ms')
+  console.log('FRAMES histogram:', buckets)
+  console.log('FRAMES slow(>33):', slowFrames, '/ veryslow(>100):', veryslowFrames, 'of', streamFrames.length)
+  console.log('LONGTASKS:', data.longtasks.length, '| total', ltMs.toFixed(0), 'ms | max', ltMax.toFixed(1), 'ms | p95', ltP95.toFixed(1), 'ms')
+  console.log('MUTATIONS:', data.mutations.length, '| finalLen', data.finalText, 'chars | inter p50', mutP50.toFixed(1), 'ms | p95', mutP95.toFixed(1), 'ms')
+  if (typingSummary) console.log('TYPING-WHILE-STREAMING latency: p50', typingSummary.p50, 'ms | p95', typingSummary.p95, 'ms | n=', typingSummary.n)
+  console.log('written to', OUT)
+
+  cdp.close()
+}
+
+main().catch((e) => { console.error(e); process.exit(1) })

apps/desktop/scripts/notarize-artifact.cjs

@@ -0,0 +1,77 @@
+const fs = require('node:fs')
+const os = require('node:os')
+const path = require('node:path')
+const { execFile } = require('node:child_process')
+
+function run(command, args) {
+  return new Promise((resolve, reject) => {
+    execFile(command, args, (error, stdout, stderr) => {
+      if (error) {
+        // Intentionally omit args from the rejection message: callers pass
+        // notarization credentials (key id, issuer, key file path) here, and
+        // surfacing them in error output would land in CI logs.
+        reject(new Error(`${command} failed: ${stderr?.trim() || stdout?.trim() || error.message}`))
+        return
+      }
+      resolve()
+    })
+  })
+}
+
+function inlineKeyLooksValid(value) {
+  return value.includes('BEGIN PRIVATE KEY') && value.includes('END PRIVATE KEY')
+}
+
+function resolveApiKeyPath(rawValue) {
+  const value = String(rawValue || '').trim()
+  if (!value) return { keyPath: '', cleanup: () => {} }
+
+  if (fs.existsSync(value)) {
+    return { keyPath: value, cleanup: () => {} }
+  }
+
+  if (!inlineKeyLooksValid(value)) {
+    throw new Error('APPLE_API_KEY must be a file path or inline .p8 key content')
+  }
+
+  const tempPath = path.join(os.tmpdir(), `hermes-notary-${Date.now()}-${process.pid}.p8`)
+  fs.writeFileSync(tempPath, value, 'utf8')
+  return {
+    keyPath: tempPath,
+    cleanup: () => fs.rmSync(tempPath, { force: true })
+  }
+}
+
+async function main() {
+  const artifactPath = process.argv[2]
+  if (!artifactPath || !fs.existsSync(artifactPath)) {
+    throw new Error(`Missing artifact to notarize: ${artifactPath || '(none)'}`)
+  }
+
+  const profile = String(process.env.APPLE_NOTARY_PROFILE || '').trim()
+  if (profile) {
+    await run('xcrun', ['notarytool', 'submit', artifactPath, '--keychain-profile', profile, '--wait'])
+    await run('xcrun', ['stapler', 'staple', '-v', artifactPath])
+    return
+  }
+
+  const keyId = String(process.env.APPLE_API_KEY_ID || '').trim()
+  const issuer = String(process.env.APPLE_API_ISSUER || '').trim()
+  const rawApiKey = process.env.APPLE_API_KEY
+  if (!rawApiKey || !keyId || !issuer) {
+    throw new Error('APPLE_API_KEY, APPLE_API_KEY_ID, and APPLE_API_ISSUER are required')
+  }
+
+  const { keyPath, cleanup } = resolveApiKeyPath(rawApiKey)
+  try {
+    await run('xcrun', ['notarytool', 'submit', artifactPath, '--key', keyPath, '--key-id', keyId, '--issuer', issuer, '--wait'])
+    await run('xcrun', ['stapler', 'staple', '-v', artifactPath])
+  } finally {
+    cleanup()
+  }
+}
+
+main().catch(() => {
+  console.error('Notarization failed. Check configuration and command output in secure CI logs.')
+  process.exit(1)
+})

apps/desktop/scripts/notarize.cjs

@@ -0,0 +1,100 @@
+const fs = require('node:fs')
+const os = require('node:os')
+const path = require('node:path')
+const { execFile } = require('node:child_process')
+
+function run(command, args) {
+  return new Promise((resolve, reject) => {
+    execFile(command, args, (error, stdout, stderr) => {
+      if (error) {
+        reject(
+          new Error(
+            `${command} ${args.join(' ')} failed: ${stderr?.trim() || stdout?.trim() || error.message}`
+          )
+        )
+        return
+      }
+      resolve({ stdout, stderr })
+    })
+  })
+}
+
+function inlineKeyLooksValid(value) {
+  return value.includes('BEGIN PRIVATE KEY') && value.includes('END PRIVATE KEY')
+}
+
+function resolveApiKeyPath(rawValue) {
+  const value = String(rawValue || '').trim()
+  if (!value) return { keyPath: '', cleanup: () => {} }
+
+  if (fs.existsSync(value)) {
+    return { keyPath: value, cleanup: () => {} }
+  }
+
+  if (!inlineKeyLooksValid(value)) {
+    throw new Error('APPLE_API_KEY must be a file path or inline .p8 key content')
+  }
+
+  const tempPath = path.join(os.tmpdir(), `hermes-notary-${Date.now()}-${process.pid}.p8`)
+  fs.writeFileSync(tempPath, value, 'utf8')
+  return {
+    keyPath: tempPath,
+    cleanup: () => {
+      try {
+        fs.rmSync(tempPath, { force: true })
+      } catch {
+        // Best-effort cleanup.
+      }
+    }
+  }
+}
+
+exports.default = async function notarize(context) {
+  const { electronPlatformName, appOutDir, packager } = context
+  if (electronPlatformName !== 'darwin') return
+
+  const appName = packager.appInfo.productFilename
+  const appPath = path.join(appOutDir, `${appName}.app`)
+  if (!fs.existsSync(appPath)) {
+    throw new Error(`Cannot notarize missing app bundle: ${appPath}`)
+  }
+
+  const profile = String(process.env.APPLE_NOTARY_PROFILE || '').trim()
+  if (profile) {
+    const zipPath = path.join(appOutDir, `${appName}.zip`)
+    await run('ditto', ['-c', '-k', '--sequesterRsrc', '--keepParent', appPath, zipPath])
+    await run('xcrun', ['notarytool', 'submit', zipPath, '--keychain-profile', profile, '--wait'])
+    await run('xcrun', ['stapler', 'staple', '-v', appPath])
+    try {
+      fs.rmSync(zipPath, { force: true })
+    } catch {
+      // Best-effort cleanup.
+    }
+    return
+  }
+
+  const keyId = String(process.env.APPLE_API_KEY_ID || '').trim()
+  const issuer = String(process.env.APPLE_API_ISSUER || '').trim()
+  const rawApiKey = process.env.APPLE_API_KEY
+  if (!rawApiKey || !keyId || !issuer) {
+    console.log(
+      'Skipping notarization: APPLE_API_KEY, APPLE_API_KEY_ID, and APPLE_API_ISSUER are not fully configured.'
+    )
+    return
+  }
+
+  const { keyPath, cleanup } = resolveApiKeyPath(rawApiKey)
+  const zipPath = path.join(appOutDir, `${appName}.zip`)
+  try {
+    await run('ditto', ['-c', '-k', '--sequesterRsrc', '--keepParent', appPath, zipPath])
+    await run('xcrun', ['notarytool', 'submit', zipPath, '--key', keyPath, '--key-id', keyId, '--issuer', issuer, '--wait'])
+    await run('xcrun', ['stapler', 'staple', '-v', appPath])
+  } finally {
+    try {
+      fs.rmSync(zipPath, { force: true })
+    } catch {
+      // Best-effort cleanup.
+    }
+    cleanup()
+  }
+}

apps/desktop/scripts/probe-renderer.mjs

@@ -0,0 +1,38 @@
+// quick probe — read state of the renderer
+const list = await (await fetch('http://127.0.0.1:9222/json/list')).json()
+const tgt = list.find(t => t.type === 'page' && t.url.startsWith('http'))
+console.log('target:', tgt?.url)
+if (!tgt) process.exit(1)
+const ws = new WebSocket(tgt.webSocketDebuggerUrl)
+let id = 0
+const pending = new Map()
+ws.addEventListener('message', ev => {
+  const m = JSON.parse(ev.data)
+  if (m.id != null && pending.has(m.id)) {
+    pending.get(m.id)(m)
+    pending.delete(m.id)
+  }
+})
+await new Promise(r => ws.addEventListener('open', r))
+const send = (method, params = {}) =>
+  new Promise(r => {
+    const i = ++id
+    pending.set(i, r)
+    ws.send(JSON.stringify({ id: i, method, params }))
+  })
+
+const r = await send('Runtime.evaluate', {
+  expression: `({
+    url: location.href,
+    title: document.title,
+    rootChildren: document.getElementById('root')?.children.length ?? 0,
+    rootInner: (document.getElementById('root')?.innerHTML ?? '').slice(0, 300),
+    hasComposer: !!document.querySelector('[data-slot="composer-rich-input"]'),
+    bootStage: (document.querySelector('[data-slot*="boot"]')?.getAttribute('data-slot')) ?? null,
+    bodyText: document.body.innerText.slice(0, 300),
+    errorCount: window.__errors?.length ?? 'n/a'
+  })`,
+  returnByValue: true
+})
+console.log('raw:', JSON.stringify(r, null, 2))
+ws.close()

apps/desktop/scripts/probe-thread.mjs

@@ -0,0 +1,40 @@
+// Probe the cloud shadows thread state — count messages, turn pairs,
+// thread height, composer state
+const list = await (await fetch('http://127.0.0.1:9222/json/list')).json()
+const tgt = list.find(t => t.type === 'page' && t.url.startsWith('http'))
+const ws = new WebSocket(tgt.webSocketDebuggerUrl)
+let id = 0
+const pending = new Map()
+ws.addEventListener('message', ev => {
+  const m = JSON.parse(ev.data)
+  if (m.id != null && pending.has(m.id)) {
+    pending.get(m.id)(m)
+    pending.delete(m.id)
+  }
+})
+await new Promise(r => ws.addEventListener('open', r))
+const send = (m, p = {}) =>
+  new Promise(r => {
+    const i = ++id
+    pending.set(i, r)
+    ws.send(JSON.stringify({ id: i, method: m, params: p }))
+  })
+
+const r = await send('Runtime.evaluate', {
+  expression: `JSON.stringify({
+    url: location.href,
+    title: document.title,
+    turnPairs: document.querySelectorAll('[data-slot="aui_turn-pair"]').length,
+    assistantMsgs: document.querySelectorAll('[data-slot="aui_assistant-message-root"]').length,
+    userMsgs: document.querySelectorAll('[data-message-role="user"], [data-slot="aui_user-message-root"]').length,
+    totalDomNodes: document.querySelectorAll('*').length,
+    threadViewportScrollHeight: document.querySelector('[data-slot="aui_thread-viewport"]')?.scrollHeight ?? null,
+    threadViewportClientHeight: document.querySelector('[data-slot="aui_thread-viewport"]')?.clientHeight ?? null,
+    threadViewportScrollTop: document.querySelector('[data-slot="aui_thread-viewport"]')?.scrollTop ?? null,
+    composer: !!document.querySelector('[data-slot="composer-rich-input"]'),
+    busy: !!document.querySelector('[aria-label*="Stop"]')
+  })`,
+  returnByValue: true
+})
+console.log(JSON.parse(r.result.result.value))
+ws.close()

apps/desktop/scripts/profile-long-stream.mjs

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+// Long-running stream profile + frame-rate timeline. Submits a prompt that
+// asks for ~30 paragraphs of output, then captures both a CPU profile and
+// a per-100ms frame counter so we can see if FPS sags as the message grows.
+
+import { writeFileSync } from 'node:fs'
+
+const args = Object.fromEntries(
+  process.argv.slice(2).flatMap(s => {
+    const m = s.match(/^--([^=]+)(?:=(.*))?$/)
+    return m ? [[m[1], m[2] ?? true]] : []
+  })
+)
+const PORT = Number(args.port ?? 9222)
+const OUT = String(args.out ?? `/tmp/hermes-long-stream-${Date.now()}`)
+const STREAM_SEC = Number(args.seconds ?? 25)
+
+async function pickRenderer() {
+  const list = await (await fetch(`http://127.0.0.1:${PORT}/json/list`)).json()
+  return list.find(t => t.type === 'page' && t.url.startsWith('http'))
+}
+
+function connect(url) {
+  return new Promise((resolve, reject) => {
+    const ws = new WebSocket(url)
+    let id = 0
+    const pending = new Map()
+    ws.addEventListener('open', () =>
+      resolve({
+        send(method, params = {}) {
+          const myId = ++id
+          ws.send(JSON.stringify({ id: myId, method, params }))
+          return new Promise((res, rej) => pending.set(myId, { res, rej }))
+        },
+        close: () => ws.close()
+      })
+    )
+    ws.addEventListener('error', reject)
+    ws.addEventListener('message', ev => {
+      const m = JSON.parse(typeof ev.data === 'string' ? ev.data : ev.data.toString('utf8'))
+      if (m.id != null) {
+        const p = pending.get(m.id)
+        if (!p) return
+        pending.delete(m.id)
+        m.error ? p.rej(new Error(m.error.message)) : p.res(m.result)
+      }
+    })
+  })
+}
+
+async function evalP(cdp, expr) {
+  const r = await cdp.send('Runtime.evaluate', { expression: expr, returnByValue: true })
+  if (r.exceptionDetails) throw new Error(r.exceptionDetails.text)
+  return r.result.value
+}
+
+async function main() {
+  const tgt = await pickRenderer()
+  console.log('target', tgt.url)
+  const cdp = await connect(tgt.webSocketDebuggerUrl)
+  await cdp.send('Runtime.enable')
+  await cdp.send('Profiler.enable')
+  await cdp.send('Performance.enable')
+
+  // Submit a long-form prompt
+  await evalP(
+    cdp,
+    `(() => {
+      const el = document.querySelector('[data-slot="composer-rich-input"]')
+      el.focus()
+      const r = document.createRange(); r.selectNodeContents(el); r.collapse(false)
+      window.getSelection().removeAllRanges(); window.getSelection().addRange(r)
+    })()`
+  )
+  const prompt = 'write 15 paragraphs about gpu memory bandwidth, memory hierarchies, roofline model, and how modern transformer inference benefits from these. include diagrams in ascii where relevant. no code. fully detailed.'
+  for (const c of prompt) {
+    await cdp.send('Input.dispatchKeyEvent', { type: 'char', text: c, unmodifiedText: c })
+    await new Promise(r => setTimeout(r, 5))
+  }
+  await new Promise(r => setTimeout(r, 200))
+  await cdp.send('Input.dispatchKeyEvent', {
+    type: 'rawKeyDown', windowsVirtualKeyCode: 13, key: 'Enter', code: 'Enter', text: '\r', unmodifiedText: '\r'
+  })
+  await cdp.send('Input.dispatchKeyEvent', { type: 'keyUp', windowsVirtualKeyCode: 13, key: 'Enter', code: 'Enter' })
+
+  console.log('waiting for assistant…')
+  let streaming = false
+  for (let i = 0; i < 100; i++) {
+    const c = await evalP(cdp, `document.querySelectorAll('[data-slot="aui_assistant-message-root"]').length`)
+    if (c > 0) { streaming = true; break }
+    await new Promise(r => setTimeout(r, 100))
+  }
+  if (!streaming) {
+    console.error('no assistant message')
+    cdp.close()
+    return
+  }
+
+  // Install a per-rAF frame counter
+  await evalP(
+    cdp,
+    `(() => {
+      window.__fpsSamples = []
+      window.__fpsT0 = performance.now()
+      window.__fpsLast = performance.now()
+      window.__fpsFrameCount = 0
+      window.__fpsHistogram = []  // {t, fps, contentLen}
+      const tick = () => {
+        const now = performance.now()
+        const dt = now - window.__fpsLast
+        window.__fpsLast = now
+        window.__fpsFrameCount++
+        window.__fpsSamples.push({ t: now - window.__fpsT0, dt })
+        if (performance.now() - window.__fpsT0 < ${STREAM_SEC * 1000}) {
+          requestAnimationFrame(tick)
+        }
+      }
+      requestAnimationFrame(tick)
+      // Bucket fps every 500ms
+      window.__fpsBucket = setInterval(() => {
+        const now = performance.now()
+        const recentCount = window.__fpsSamples.filter(s => now - window.__fpsT0 - s.t < 500).length
+        const root = document.querySelector('[data-slot="aui_thread-content"]')
+        const len = root ? root.innerText.length : 0
+        const v = document.querySelector('[data-slot="aui_thread-viewport"]')
+        window.__fpsHistogram.push({
+          t: now - window.__fpsT0,
+          frames500ms: recentCount,
+          fps: recentCount * 2,
+          contentLen: len,
+          scrollTop: v?.scrollTop ?? 0,
+          scrollHeight: v?.scrollHeight ?? 0
+        })
+      }, 500)
+    })()`
+  )
+
+  // Start CPU profile
+  await cdp.send('Profiler.setSamplingInterval', { interval: 1000 })
+  await cdp.send('Profiler.start')
+
+  await new Promise(r => setTimeout(r, STREAM_SEC * 1000))
+
+  const { profile } = await cdp.send('Profiler.stop')
+  await evalP(cdp, `clearInterval(window.__fpsBucket)`)
+
+  writeFileSync(`${OUT}.cpuprofile`, JSON.stringify(profile))
+  console.log(`cpu profile → ${OUT}.cpuprofile`)
+
+  // Pull fps histogram
+  const hist = JSON.parse(await evalP(cdp, `JSON.stringify(window.__fpsHistogram || [])`))
+  writeFileSync(`${OUT}.fps.json`, JSON.stringify(hist, null, 2))
+
+  console.log(`\n=== FPS over time ===`)
+  console.log(`  t(s)   fps   contentLen   scrollTop/scrollHeight`)
+  for (const h of hist) {
+    const bar = '█'.repeat(Math.min(40, Math.max(0, Math.round(h.fps / 2))))
+    console.log(`  ${(h.t / 1000).toFixed(1).padStart(5)}  ${String(h.fps).padStart(3)}  ${String(h.contentLen).padStart(10)}   ${h.scrollTop}/${h.scrollHeight}  ${bar}`)
+  }
+
+  // Top self frames
+  const total = (profile.endTime - profile.startTime) / 1000
+  const intMs = total / Math.max(1, profile.samples?.length ?? 1)
+  const counts = new Map()
+  for (const s of profile.samples ?? []) counts.set(s, (counts.get(s) ?? 0) + 1)
+  const rows = profile.nodes
+    .map(n => ({ id: n.id, fn: n.callFrame.functionName || '(anon)', url: n.callFrame.url || '', line: n.callFrame.lineNumber, self: counts.get(n.id) ?? 0 }))
+    .sort((a, b) => b.self - a.self)
+    .slice(0, 25)
+  console.log(`\n=== ${total.toFixed(0)}ms wall, ${profile.samples?.length ?? 0} samples (${intMs.toFixed(2)}ms each) ===`)
+  for (const r of rows) {
+    if (r.self === 0) break
+    const url = r.url.replace(/^.*\/src\//, 'src/').replace(/\?.*$/, '').slice(0, 70)
+    console.log(`  ${(r.self * intMs).toFixed(1).padStart(7)}ms  (${String(r.self).padStart(4)} samp)  ${r.fn.padEnd(45)} ${url}:${r.line}`)
+  }
+
+  await evalP(cdp, `
+    (() => {
+      for (const b of document.querySelectorAll('button')) {
+        if ((b.getAttribute('aria-label') || '').toLowerCase().includes('stop')) { b.click(); return }
+      }
+    })()
+  `)
+
+  cdp.close()
+}
+
+main().catch(e => {
+  console.error('fatal:', e.stack ?? e.message)
+  process.exit(1)
+})

apps/desktop/scripts/profile-real-stream.mjs

@@ -0,0 +1,137 @@
+// CPU-profile during a real LLM stream — confirms or refutes whether the
+// synthetic stream's hotspots (Streamdown markdown re-parse, FadeText)
+// match real-world content.
+//
+// Run *after* model is set to something fast + cheap (gpt-4o-mini etc.).
+// Sends a prompt likely to produce markdown + a numbered list.
+
+import { writeFileSync } from 'node:fs'
+
+const CDP_HTTP = 'http://127.0.0.1:9222'
+const PROMPT = process.env.PROMPT || 'Give me a numbered list of 8 useful bash one-liners. For each: a brief description, then the command in a code block. No preamble.'
+const OUT = process.env.OUT || `/tmp/real-stream-${Date.now()}.cpuprofile`
+const START_TIMEOUT = Number(process.env.START_TIMEOUT || 45000)
+const STREAM_TIMEOUT = Number(process.env.STREAM_TIMEOUT || 60000)
+
+class CDP {
+  constructor(ws) { this.ws = ws; this.id = 0; this.pending = new Map() }
+  static async open(url) {
+    const ws = new WebSocket(url)
+    await new Promise((r) => ws.addEventListener('open', r, { once: true }))
+    const cdp = new CDP(ws)
+    ws.addEventListener('message', (ev) => {
+      const m = JSON.parse(ev.data.toString())
+      if (m.id != null && cdp.pending.has(m.id)) {
+        const { resolve, reject } = cdp.pending.get(m.id)
+        cdp.pending.delete(m.id)
+        if (m.error) reject(new Error(m.error.message))
+        else resolve(m.result)
+      }
+    })
+    return cdp
+  }
+  send(method, params) {
+    const id = ++this.id
+    return new Promise((res, rej) => {
+      this.pending.set(id, { resolve: res, reject: rej })
+      this.ws.send(JSON.stringify({ id, method, params }))
+    })
+  }
+  async eval(expr) {
+    const r = await this.send('Runtime.evaluate', { expression: expr, returnByValue: true, awaitPromise: true })
+    if (r.exceptionDetails) throw new Error(r.exceptionDetails.exception?.description || 'eval')
+    return r.result.value
+  }
+  close() { this.ws.close() }
+}
+
+async function main() {
+  const list = await (await fetch(`${CDP_HTTP}/json`)).json()
+  const target = list.find((t) => t.type === 'page' && /5174/.test(t.url))
+  const cdp = await CDP.open(target.webSocketDebuggerUrl)
+
+  const baseCount = await cdp.eval('document.querySelectorAll("[data-slot=aui_assistant-message-root]").length')
+
+  // Submit prompt
+  await cdp.eval(`(() => {
+    const ed = document.querySelector('[contenteditable="true"]')
+    ed.focus()
+    document.execCommand('insertText', false, ${JSON.stringify(PROMPT)})
+    ed.dispatchEvent(new KeyboardEvent('keydown', { key: 'Enter', code: 'Enter', which: 13, keyCode: 13, bubbles: true, cancelable: true }))
+    return 'submitted'
+  })()`)
+
+  // Wait for real stream start (assistant count grows).
+  const submitT0 = Date.now()
+  let streamT = null
+  for (let i = 0; i < START_TIMEOUT / 50; i++) {
+    await new Promise((r) => setTimeout(r, 50))
+    const n = await cdp.eval('document.querySelectorAll("[data-slot=aui_assistant-message-root]").length')
+    if (n > baseCount) { streamT = Date.now(); break }
+  }
+  if (!streamT) {
+    console.error('stream never started within', START_TIMEOUT, 'ms')
+    cdp.close()
+    process.exit(2)
+  }
+  console.log('REAL stream started after', streamT - submitT0, 'ms — starting CPU profile NOW')
+
+  // Start CPU profile NOW, only during stream phase.
+  await cdp.send('Profiler.enable')
+  await cdp.send('Profiler.setSamplingInterval', { interval: 100 })
+  await cdp.send('Profiler.start')
+
+  // Wait until busy goes false + grace, or timeout.
+  const cutoff = Date.now() + STREAM_TIMEOUT
+  while (Date.now() < cutoff) {
+    await new Promise((r) => setTimeout(r, 500))
+    const busy = await cdp.eval('!!document.querySelector("[data-status=running], [data-busy=true]")')
+    if (!busy) {
+      await new Promise((r) => setTimeout(r, 500))
+      break
+    }
+  }
+
+  const { profile } = await cdp.send('Profiler.stop')
+  writeFileSync(OUT, JSON.stringify(profile))
+  console.log('wrote', OUT)
+
+  const samples = profile.samples || []
+  const timeDeltas = profile.timeDeltas || []
+  const nodes = new Map(profile.nodes.map((n) => [n.id, n]))
+  const selfTime = new Map()
+  for (let i = 0; i < samples.length; i++) {
+    const id = samples[i]
+    const dt = timeDeltas[i] ?? 0
+    selfTime.set(id, (selfTime.get(id) || 0) + dt)
+  }
+  const ranked = [...selfTime.entries()]
+    .map(([id, us]) => {
+      const n = nodes.get(id)
+      const cf = n?.callFrame || {}
+      return {
+        ms: us / 1000,
+        name: cf.functionName || '(anonymous)',
+        url: (cf.url || '').slice(-60),
+        line: cf.lineNumber
+      }
+    })
+    .filter((x) => !/\(root\)|\(idle\)|\(garbage collector\)|\(program\)/.test(x.name))
+    .sort((a, b) => b.ms - a.ms)
+    .slice(0, 25)
+
+  const finalText = await cdp.eval(`(() => {
+    const all = document.querySelectorAll('[data-slot="aui_assistant-message-root"]')
+    return all.length ? all[all.length-1].textContent.length : 0
+  })()`)
+  console.log('\nfinal assistant message length:', finalText, 'chars')
+
+  console.log('\n=== TOP 25 SELF TIME (ms) DURING REAL STREAM ===')
+  for (const r of ranked) {
+    console.log(`${r.ms.toFixed(1).padStart(7)}  ${r.name.padEnd(40)}  ${r.url}:${r.line}`)
+  }
+
+  cdp.close()
+}
+
+main().catch((e) => { console.error(e); process.exit(1) })

apps/desktop/scripts/profile-synth-stream.mjs

@@ -0,0 +1,103 @@
+// CPU-profile a synthetic stream — outputs a .cpuprofile and a top-self ranking.
+// Open the .cpuprofile in Chrome DevTools Performance panel for a flamegraph.
+
+import { writeFileSync } from 'node:fs'
+
+const CDP_HTTP = 'http://127.0.0.1:9222'
+const TOKENS = Number(process.env.TOKENS || 400)
+const INTERVAL_MS = Number(process.env.INTERVAL_MS || 8)
+const CHUNK = process.env.CHUNK || '**word** in _italic_ with `code` '
+const LABEL = process.env.LABEL || 'profile'
+const OUT = process.env.OUT || `synth-${LABEL}.cpuprofile`
+
+class CDP {
+  constructor(ws) { this.ws = ws; this.id = 0; this.pending = new Map() }
+  static async open(url) {
+    const ws = new WebSocket(url)
+    await new Promise((r) => ws.addEventListener('open', r, { once: true }))
+    const cdp = new CDP(ws)
+    ws.addEventListener('message', (ev) => {
+      const m = JSON.parse(ev.data.toString())
+      if (m.id != null && cdp.pending.has(m.id)) {
+        const { resolve, reject } = cdp.pending.get(m.id)
+        cdp.pending.delete(m.id)
+        if (m.error) reject(new Error(m.error.message))
+        else resolve(m.result)
+      }
+    })
+    return cdp
+  }
+  send(method, params) {
+    const id = ++this.id
+    return new Promise((res, rej) => {
+      this.pending.set(id, { resolve: res, reject: rej })
+      this.ws.send(JSON.stringify({ id, method, params }))
+    })
+  }
+  async eval(expr) {
+    const r = await this.send('Runtime.evaluate', { expression: expr, returnByValue: true, awaitPromise: true })
+    if (r.exceptionDetails) throw new Error(r.exceptionDetails.exception?.description || 'eval')
+    return r.result.value
+  }
+  close() { this.ws.close() }
+}
+
+async function main() {
+  const list = await (await fetch(`${CDP_HTTP}/json`)).json()
+  const target = list.find((t) => t.type === 'page' && /5174/.test(t.url))
+  const cdp = await CDP.open(target.webSocketDebuggerUrl)
+
+  if (!await cdp.eval('!!window.__PERF_DRIVE__')) {
+    console.error('no __PERF_DRIVE__')
+    cdp.close()
+    process.exit(2)
+  }
+
+  await cdp.send('Profiler.enable')
+  // High-resolution sampling: 100us
+  await cdp.send('Profiler.setSamplingInterval', { interval: 100 })
+  await cdp.send('Profiler.start')
+
+  await cdp.eval(`window.__PERF_DRIVE__.stream({ chunk: ${JSON.stringify(CHUNK)}, intervalMs: ${INTERVAL_MS}, totalTokens: ${TOKENS} })`)
+  await new Promise((r) => setTimeout(r, TOKENS * INTERVAL_MS + 1500))
+  await cdp.eval('window.__PERF_DRIVE__.reset()')
+
+  const { profile } = await cdp.send('Profiler.stop')
+  writeFileSync(OUT, JSON.stringify(profile))
+  console.log('wrote', OUT)
+
+  // Compute top self time per function.
+  const samples = profile.samples || []
+  const timeDeltas = profile.timeDeltas || []
+  const nodes = new Map(profile.nodes.map((n) => [n.id, n]))
+  const selfTime = new Map() // id -> microseconds
+  for (let i = 0; i < samples.length; i++) {
+    const id = samples[i]
+    const dt = timeDeltas[i] ?? 0
+    selfTime.set(id, (selfTime.get(id) || 0) + dt)
+  }
+  const ranked = [...selfTime.entries()]
+    .map(([id, us]) => {
+      const n = nodes.get(id)
+      const cf = n?.callFrame || {}
+      return {
+        us,
+        ms: us / 1000,
+        name: cf.functionName || '(anonymous)',
+        url: (cf.url || '').slice(-60),
+        line: cf.lineNumber
+      }
+    })
+    .filter((x) => !/\(root\)|\(idle\)|\(garbage collector\)|\(program\)/.test(x.name))
+    .sort((a, b) => b.us - a.us)
+    .slice(0, 30)
+
+  console.log('\n=== TOP 30 SELF TIME (ms) ===')
+  for (const r of ranked) {
+    console.log(`${r.ms.toFixed(1).padStart(7)}  ${r.name.padEnd(40)}  ${r.url}:${r.line}`)
+  }
+
+  cdp.close()
+}
+
+main().catch((e) => { console.error(e); process.exit(1) })

apps/desktop/scripts/profile-typing-lag.md

@@ -0,0 +1,381 @@
+# Profiling renderer typing lag
+
+Workflow for empirically measuring (and fixing) typing/submit lag in the
+desktop chat composer.
+
+## Quick boot for profiling
+
+Vite 8 + plugin-react 6 has a known issue where the React Fast Refresh
+preamble script isn't injected into `index.html`, so opening Electron at
+`http://127.0.0.1:5174` throws `$RefreshReg$ is not defined` on every TSX
+module and the React tree never mounts. Workaround: run vite with HMR off.
+
+```bash
+# Terminal A — start dev server without HMR
+cd apps/desktop
+node scripts/dev-no-hmr.mjs
+
+# Terminal B — start Electron with CDP exposed
+cd apps/desktop
+XCURSOR_SIZE=24 HERMES_DESKTOP_DEV_SERVER=http://127.0.0.1:5174 \
+  ../../node_modules/.bin/electron --remote-debugging-port=9222 .
+```
+
+Terminal C is yours to run the harnesses.
+
+## Harnesses
+
+All zero-dep — Node 24 built-in `WebSocket` + `fetch`.
+
+### Typing latency — `measure-latency.mjs`
+
+Per-keystroke `keypress → next paint` latency, p50/p90/p99/max.
+Synthesizes keystrokes via `Input.dispatchKeyEvent` so the run is
+reproducible.
+
+```bash
+node apps/desktop/scripts/measure-latency.mjs --chars=120 --cps=20
+```
+
+Anything > 16ms is a dropped frame. On a freshly-loaded session
+(`scripts/click-session.mjs 'Phaser particle'`) we currently see:
+
+| | unpatched | patched |
+|---|---|---|
+| p50 paint | 1.9 ms | 2.0 ms |
+| p90 paint | 3.3 ms | 13.7 ms |
+| p99 paint | 16.7 ms | 15.2 ms |
+| max paint | 20.5 ms | 30.4 ms |
+| >16ms drops | 2/120 | 1/120 |
+
+Roughly even on a quick session — patches don't fix typing latency
+under benign synthetic conditions because the existing baseline is
+already snappy on synthetic input. The real wins are in the leak counters
+(see below). If the user reports typing jank, capture a profile + heap
+diff during their actual usage and compare against the synthetic baseline
+to identify what condition (long thread, popover open, paste, etc.)
+makes the path slow.
+
+### Leak counters — `leak-typing.mjs`
+
+Types N chars per round, clears, force-GCs, captures
+`Performance.getMetrics` deltas. Reveals leaked event listeners, heap
+drift, document node growth, and forced-layout counts.
+
+```bash
+# After clicking into a real session (e.g. via click-session.mjs):
+node apps/desktop/scripts/leak-typing.mjs --rounds=8 --chars=200 --cps=50
+```
+
+**Real-session numbers (Phaser thread, 8 rounds × 200 chars):**
+
+| | unpatched (HEAD~2) | patched (HEAD) |
+|---|---|---|
+| jsListeners growth/round | +0 | +0 |
+| DOM nodes growth/round | +0 | +0 |
+| heap growth/round | ~0 (V8 housekeeping) | ~0 |
+| **forced layouts/char** | **7.02** | **2.35** (3× fewer) |
+
+The forced-layout count is the load-bearing number — typing into a real
+session was triggering ~7 layouts per character on the unpatched build
+(scrollHeight reads + per-px CSS var writes + FadeText scrollWidth reads
+all stacking up). After the patches it's down to ~2.35/char, which is
+Blink's natural cost for a 1px/char-growing contentEditable and can't
+be lowered further without architectural changes.
+
+The initial "+35 listeners/round leak" I called out on the first
+unpatched run turned out to be transient warm-up (popovers initializing,
+etc.); steady-state listener growth was 0 both before and after.
+
+### CPU profile + heap snapshot — `profile-typing.mjs`
+
+Records a CPU profile while typing, plus before/after heap snapshots so
+you can do a comparison diff in Chrome DevTools Memory tab.
+
+```bash
+node apps/desktop/scripts/profile-typing.mjs \
+  --chars=400 --cps=30 --out=/tmp/hermes-typing
+# → /tmp/hermes-typing.cpuprofile  (open in Chrome DevTools Performance)
+# → /tmp/hermes-typing.before.heapsnapshot
+# → /tmp/hermes-typing.after.heapsnapshot
+```
+
+Loading the cpuprofile: Chrome DevTools → Performance tab → drag the file
+in, or VS Code → open the `.cpuprofile` directly.
+
+For heap diff: Chrome DevTools → Memory → Load snapshot → load "before",
+then Comparison view → load "after". Sort by `# Delta`. Stay alert for
+detached DOM, FiberNodes (unmounted), and listener growth.
+
+## Helpers
+
+- `probe-renderer.mjs` — dump page state (URL, composer mounted?, body text)
+- `click-session.mjs <title>` — click a sidebar session by partial title match
+- `reload-renderer.mjs` — force Page.reload via CDP (no HMR available)
+- `dump-state.mjs` — richer state dump (thread message count, sticky session, etc.)
+- `probe-console.mjs` — dump recent console errors / exceptions
+
+## Findings
+
+See commit message for `apps/desktop/src/app/chat/composer/index.tsx`
+edits. Three changes:
+
+1. **Per-keystroke `scrollHeight` read removed.** The expansion useEffect
+   used to read `editorRef.current.scrollHeight` on every draft change
+   (forces synchronous layout). Replaced with a `draft.length > 60`
+   heuristic; the ResizeObserver catches anything the heuristic misses.
+
+2. **Bucketed CSS custom-property writes.** `syncComposerMetrics`
+   used to `setProperty('--composer-measured-height', height + 'px')`
+   on every observed resize, invalidating computed style for the whole
+   tree. Now writes only when the height crosses an 8 px bucket, so
+   typing in a fixed-height row produces no style invalidation at all.
+
+3. **Removed dead `$composerDraft` → `aui.composer().setText` round-trip.**
+   Nothing outside the composer subscribed to `$composerDraft` (verified
+   via grep). The two useEffects that pushed draft → store and store →
+   composer were pure overhead per keystroke. `reconcileComposerTerminalSelections`
+   was also called per keystroke; can be deferred to submit time (it's a
+   stale-pruning step, not a correctness one — `terminalContextBlocksFromDraft`
+   walks the current text directly at submit and ignores stale labels).
+
+4. **`refreshTrigger` fast-bails when no `@`/`/` in draft.** Previously
+   `textBeforeCaret()` did `range.toString()` (O(n)) on every keystroke
+   even when no trigger char was present.
+
+The biggest win is the listener leak in (3) — without it, each round of
+typing leaked ~35 event listeners until a steady state.
+
+## Submit / TTFT stall (open)
+
+User reports a perceived stall *after* Enter, before the assistant starts
+streaming. `scripts/measure-submit.mjs` measures
+`enter → composer-cleared → user-message-rendered → first-paint`. The
+script triggers a real prompt submission, so use it on a throwaway
+session. Not enabled in CI.
+
+## Streaming "5fps" investigation (May 21, 2026)
+
+User complaint: "the streaming must bring fps to like 5? lol" — felt
+hitches during assistant streaming on long threads.
+
+### Tooling added
+
+- **`src/app/chat/perf-probe.tsx`** — dev-only side-effect import (guarded by
+  `import.meta.env.MODE !== 'production'` in `main.tsx`). Attaches two
+  helpers to `window`:
+  - `__PERF_PROBE__` — React `<Profiler>` recorder. Currently inert because
+    Vite is serving the production React build (see "Vite dev-build issue"
+    below); kept for when that's fixed.
+  - `__PERF_DRIVE__` — synthetic stream driver. Pushes tokens through the
+    live `$messages` atom at a fixed cadence, so the assistant-ui runtime,
+    incremental repository, Streamdown markdown renderer, and React commit
+    pipeline all see the same workload they'd see from a real LLM stream —
+    but with no LLM call (and no credit cost).
+- **`scripts/measure-synthetic-stream.mjs`** — drives `__PERF_DRIVE__`,
+  records rAF frame intervals, `PerformanceObserver({entryTypes:['longtask']})`
+  entries, `MutationObserver` cadence on the live message, and optional
+  type-while-streaming keystroke latency.
+- **`scripts/profile-synth-stream.mjs`** — CPU profile during a synthetic
+  stream; writes a `.cpuprofile` (open in Chrome DevTools Performance panel)
+  and a top-30 self-time table.
+- **`scripts/measure-real-stream.mjs`** — same harness as the synthetic but
+  fires a real LLM prompt. Use when you have credits and want to confirm
+  the synthetic predictions hold.
+- **`scripts/profile-real-stream.mjs`** — CPU profile over the duration of
+  a real LLM stream.
+
+Helpers: `scripts/eval.mjs` (one-shot CDP eval), `scripts/reload.mjs`
+(hard reload renderer over CDP).
+
+### Findings
+
+Measured on the Cloud Shadows session (7 turns, ~11k px scrollHeight) and
+the 34 MB session `session_20260514_215353_fe0ac8.json` (110 FadeText
+instances, lots of historical tool calls).
+
+| metric | Cloud Shadows | 34 MB session |
+|---|---|---|
+| avgFps (60 tok/sec, 5s) | 60.0 | 58.6 |
+| frame p50 / p95 / p99 (ms) | 16.7 / 18.0 / 21.1 | 16.6 / 25.6 / 31.4 |
+| max frame (ms) | 31.1 | 97-127 (varies) |
+| longtasks per 5s window | 0 | 1-2, 75-127 ms |
+| type-while-stream p95 latency (ms) | 17 | — |
+
+A single real-LLM stream on Cloud Shadows (gpt-4o-mini, 39s window) saw
+12 longtasks totalling 1.26 s — same cadence the synthetic predicted
+(~1 hitch per 3.25 s, max 123 ms). So the **synthetic stream is a faithful
+proxy for the real one** and is fine for iterating on fixes without paying
+for tokens.
+
+### CPU profile during streaming (synthetic, markdown content)
+
+Top self-time costs (5 s window, 400 tokens at 125 tok/s, markdown chunks):
+
+| ms (self) | function | source |
+|---|---|---|
+| 260 | `bn$1` | `chunk-BO2N…js:20003` (micromark tokenize) |
+| 249 | `m$1` | `chunk-BO2N…js:19949` (micromark) |
+| 128 | `compile` | `chunk-BO2N…js:21884` (mdast → hast compile) |
+| 73 | FadeText body | `components/ui/fade-text.tsx` |
+| 62 | `parser` | `chunk-BO2N…js:22680` |
+| 49 | `fromThreadMessageLike` | `@assistant-ui/internal` |
+
+That `chunk-BO2N2NFS` is the vendored bundle containing `micromark`,
+`mdast-util-from-markdown`, `mdast-util-to-hast`, `rehype-raw`,
+`hast-util-sanitize`, etc. — i.e. **Streamdown's markdown pipeline,
+re-parsing the entire growing assistant message on every token append**.
+Cost scales linearly with message length.
+
+Compare plain-text (no markdown) — the `chunk-BO2N…` entries drop out
+of the top 30 entirely; total work per 5 s window halves.
+
+### Fix landed: `FadeText` memo
+
+`FadeText` is used in `tool-fallback.tsx` (110 instances on a tool-heavy
+thread). Before: each parent re-render during streaming triggered a
+`useEffect([children])` that forced a `scrollWidth` layout read — even
+when the title text was unchanged. The `useResizeObserver` already covers
+the genuine resize case, so the effect was strictly redundant.
+
+After: wrapped in `React.memo` with a custom comparator that compares
+`children` (scalar fast-path), `className`, `fadeWidth`, and `style`
+field-by-field. Verified via temporary render counter:
+**122 renders during a 2 s synthetic stream vs ~11 000 without memo**
+(110 instances × ~100 stream updates). Doesn't move the longtask needle
+on its own — Streamdown dwarfs it — but eliminates a class of forced
+layouts and removes a steady CPU floor.
+
+### Also landed: `MarkdownText` plugins memo + upstream flush floor
+
+Two smaller follow-ups in the same investigation:
+
+1. **`MarkdownText` `plugins` object useMemo'd.** The inline
+   `plugins={{ math: mathPlugin, ...(isStreaming ? {} : { code }) }}`
+   was constructing a new object on every render, which churns
+   `<Streamdown>`'s outer memo and forces its internal `rehypePlugins` /
+   `remarkPlugins` arrays to rebuild. CPU profile after the change shows
+   `parser` self-time dropping out of the top 10, `compile` cut roughly
+   in half, and `bn$1` / `m$1` (micromark internals) dropping off the
+   top entries.
+
+2. **`use-message-stream.scheduleDeltaFlush` got a real minimum floor.**
+   Previously the rAF-only path effectively meant "at most one flush per
+   frame," but at typical LLM token rates of 30-80 tok/sec each token
+   arrives slower than rAF cadence and gets its own React commit. With
+   `STREAM_DELTA_FLUSH_MS = 33` (two frames) and a `lastFlushAt`-tracked
+   floor, slower streams now coalesce ~2 tokens per commit, halving
+   markdown re-parses. React's auto-batching already covers part of this
+   probabilistically; the floor makes the batching deterministic so the
+   max-longtask number tightens up.
+
+A/B on the 34 MB session, 300 tokens at 50 tok/sec, markdown chunks
+(3 trials each):
+
+| | avgFps | p99 frame | LTs/5s | max LT | mutations |
+|---|---|---|---|---|---|
+| no throttle  | 54.0 | 38 ms | 2.0 | 145 ms | varies (2-112) |
+| 33 ms throttle | 54.3 | 41 ms | 1.7 | 110 ms | ~135 |
+
+Modest. `inter-mutation` p50 tightens from 22-28 ms to a clean 33 ms,
+which is what you'd expect from a deterministic floor.
+
+### Also landed: `useDeferredValue` at the streamdown-text boundary
+
+The longtask CPU was unavoidable inside the block-memo pattern — the live
+tail re-parses every commit, scales linearly with current length, and
+nothing about Streamdown's architecture changes that without forking. The
+fix is to stop having that work *block* the main thread.
+
+`<DeferStreamingText>` in `markdown-text.tsx` is a 12-line wrapper that
+reads the message-part state via `useMessagePartText`, runs it through
+`useDeferredValue`, and re-publishes via assistant-ui's
+`<TextMessagePartProvider>`. The inner `StreamdownTextPrimitive` reads the
+deferred value through the normal `useMessagePartText` hook — no fork,
+no internal-path imports, fully on the assistant-ui public API.
+
+What React's concurrent scheduler now does:
+
+- When a new token arrives mid-render, the in-flight deferred render
+  is abandoned and a fresh one starts with the latest text.
+- When the main thread has urgent work (typing, scroll, layout), the
+  Streamdown render gets deprioritized — input stays responsive even
+  while a 100 ms parse is queued.
+
+Streamdown already uses `useTransition` internally for its block-array
+setState; `useDeferredValue` here just lifts the deferral all the way up
+to the consumer text boundary, so the whole pipeline — preprocess,
+block split, repair, parse, render — runs at low priority during streaming.
+This is the industry-standard approach (see
+[Streamdown architecture analysis](https://tigerabrodi.blog/how-to-build-a-performant-ai-markdown-renderer)
+and Chrome's [LLM-response render best practices](https://developer.chrome.google.cn/docs/ai/render-llm-responses)).
+
+A/B on the 34 MB session, 300 tokens at 50 tok/sec, markdown chunks
+(four trials each, prod-throttle (33 ms) on for both):
+
+| | avgFps | p99 frame | LTs / 5 s | max LT | typing p95 |
+|---|---|---|---|---|---|
+| pre-defer | 54.3 | 41 ms | 1.7 | 110 ms | ~17 ms |
+| **post-defer** | **58.5** | **31 ms** | 2.0 | 117 ms | 14-18 ms |
+
+Longtask count and max LT are unchanged — `useDeferredValue` doesn't
+reduce CPU, only its priority. The avgFps lift and p99 frame drop are
+the proof that the existing CPU is no longer blocking 60 fps cadence:
+when React can defer the parse, frames stay clean. One particularly
+clean run logged **MUTATIONS=0** — React skipped every intermediate
+text state and only committed the final one, the textbook
+useDeferredValue behaviour.
+
+### Not fixed: Streamdown markdown re-parse cost (the elephant)
+
+Total CPU spent in micromark/mdast/hast pipeline per 5 s window is still
+the same ~700 ms. With `useDeferredValue` that work no longer blocks
+input, but if you watch a CPU profile you'll see the same hot functions
+(`Tn$1`, `bn$1`, `m$1`, `parser`, `compile`).
+
+The path to actually *reduce* that cost (not just defer it) is to
+replace the parser with a state machine like
+[Flowdown](https://github.com/Atomics-hub/flowdown) — process each
+character exactly once, emit DOM ops directly, no re-parse of the prefix
+on every token. Claimed ~2,000× over `marked`. Trades: not a
+`react-markdown`-compatible API, no rehype security pipeline, would
+require replacing Streamdown wholesale. Worth investigating only if
+even the deferred work shows up in user-perceptible ways (e.g.
+trackpad-scrolling a stream-in-progress stutters).
+
+The synthetic harness now mirrors the real upstream pipeline via the
+`flushMinMs` option in `__PERF_DRIVE__.stream({ flushMinMs: 33 })`, so
+future Streamdown / Flowdown experiments can A/B without LLM credit cost.
+The synthetic numbers tracked the one real-LLM run we caught within
+noise, so it's a reliable proxy.
+
+Possible approaches (none implemented here):
+
+1. **Coalesce/throttle Streamdown updates** — render at most every 32 ms
+   instead of every set-state. Reduces parses but doesn't reduce
+   per-parse cost; trades latency for smoothness.
+2. **Memoize per-prefix** — diff the new text against the prior parsed
+   version; only re-parse the changed suffix.
+3. **Render in stable segments** — close-form historical paragraphs as
+   immutable React nodes; only the live tail goes through markdown each
+   token. Probably the highest-impact change but requires forking or
+   patching `@assistant-ui/react-streamdown`.
+4. **Move parsing to a Web Worker** — main thread no longer blocks on
+   markdown. Largest surgery; requires double-buffered hast.
+
+### Vite dev-build issue (separate)
+
+`http://127.0.0.1:5174/node_modules/.vite/deps/react.js` resolves to
+`react/cjs/react.production.js`, and `react-dom_client.js` →
+`react-dom-client.production.js`. As a result:
+
+- `<React.Profiler>` `onRender` is never called (production build is a
+  no-op).
+- `import.meta.env.DEV` is `false`, `PROD` is `true` even under `vite dev`
+  (hence `MODE !== 'production'` as the workaround in `main.tsx`).
+- All the React 19 dev-only warnings/devtools backend hooks are absent.
+
+Root cause likely sits in `vite.config.ts` aliasing + dedupe + Vite 8's
+new `optimizeDeps` defaults. Worth a separate fix pass — when it's
+resolved, the `<PerfProbe>` blocks in `perf-probe.tsx` become useful
+(per-id commit timings) instead of inert.

apps/desktop/scripts/profile-typing.mjs

@@ -0,0 +1,260 @@
+#!/usr/bin/env node
+// Profile typing lag in the Electron renderer by:
+//  1. Connecting to a running renderer via CDP (--remote-debugging-port=9222)
+//  2. Focusing the composer contentEditable
+//  3. Starting CPU profile + heap snapshot
+//  4. Synthesizing keystrokes via Input.dispatchKeyEvent (so the run is
+//     reproducible, no human-typing variance)
+//  5. Stopping the profile + capturing a second heap snapshot
+//  6. Saving .cpuprofile + .heapsnapshot
+//
+// Usage:
+//   node apps/desktop/scripts/profile-typing.mjs
+//     [--port=9222] [--out=/tmp/hermes-typing]
+//     [--chars=400]              # how many characters to type
+//     [--cps=30]                 # keystrokes per second
+//     [--text="..."]             # override generated text
+//     [--no-heap]                # skip heap snapshots
+//     [--seconds=N]              # idle-record for N seconds instead of typing
+//
+// Zero deps — uses Node 24's global WebSocket + fetch.
+
+import { writeFileSync } from 'node:fs'
+
+const args = Object.fromEntries(
+  process.argv.slice(2).flatMap(s => {
+    const m = s.match(/^--([^=]+)(?:=(.*))?$/)
+    return m ? [[m[1], m[2] ?? true]] : []
+  })
+)
+
+const PORT = Number(args.port ?? 9222)
+const OUT = String(args.out ?? `/tmp/hermes-typing-${Date.now()}`)
+const CHARS = Number(args.chars ?? 400)
+const CPS = Number(args.cps ?? 30)
+const HEAP = args['no-heap'] ? false : true
+const IDLE_SECONDS = args.seconds ? Number(args.seconds) : null
+const CUSTOM_TEXT = args.text === undefined || args.text === true ? null : String(args.text)
+
+const log = (...m) => console.log('[profile]', ...m)
+const banner = m => console.log(`\n========== ${m} ==========`)
+
+async function pickRenderer() {
+  const list = await (await fetch(`http://127.0.0.1:${PORT}/json/list`)).json()
+  const pages = list.filter(t => t.type === 'page' && t.url.startsWith('http'))
+  if (!pages.length) {
+    console.error('No renderer page. Targets:')
+    list.forEach(t => console.error(' ', t.type, t.url))
+    process.exit(2)
+  }
+  return pages[0]
+}
+
+function connect(url) {
+  return new Promise((resolve, reject) => {
+    const ws = new WebSocket(url)
+    let id = 0
+    const pending = new Map()
+    const events = new Map()
+    ws.addEventListener('open', () =>
+      resolve({
+        send(method, params = {}) {
+          const myId = ++id
+          ws.send(JSON.stringify({ id: myId, method, params }))
+          return new Promise((res, rej) => pending.set(myId, { res, rej }))
+        },
+        on(method, h) {
+          if (!events.has(method)) events.set(method, [])
+          events.get(method).push(h)
+        },
+        close: () => ws.close()
+      })
+    )
+    ws.addEventListener('error', reject)
+    ws.addEventListener('message', ev => {
+      const txt = typeof ev.data === 'string' ? ev.data : ev.data.toString('utf8')
+      const m = JSON.parse(txt)
+      if (m.id != null) {
+        const p = pending.get(m.id)
+        if (!p) return
+        pending.delete(m.id)
+        m.error ? p.rej(new Error(m.error.message)) : p.res(m.result)
+      } else if (m.method) {
+        ;(events.get(m.method) ?? []).forEach(h => h(m.params))
+      }
+    })
+  })
+}
+
+async function captureHeap(cdp, path) {
+  log(`heap snapshot → ${path}`)
+  const chunks = []
+  cdp.on('HeapProfiler.addHeapSnapshotChunk', ({ chunk }) => chunks.push(chunk))
+  await cdp.send('HeapProfiler.enable')
+  await cdp.send('HeapProfiler.takeHeapSnapshot', { reportProgress: false, captureNumericValue: true })
+  writeFileSync(path, chunks.join(''))
+  log(`  ${(Buffer.byteLength(chunks.join(''), 'utf8') / 1024 / 1024).toFixed(1)} MB`)
+}
+
+async function focusComposer(cdp) {
+  // Focus the rich-input contentEditable. RICH_INPUT_SLOT is the data-slot
+  // value used by the composer's editable div. If focus fails (no composer
+  // mounted yet — disabled state, etc.) the script logs and continues; the
+  // profile will still show idle behavior.
+  const result = await cdp.send('Runtime.evaluate', {
+    expression: `
+      (() => {
+        const el = document.querySelector('[data-slot="composer-rich-input"]')
+        if (!el) return { ok: false, reason: 'composer-rich-input not found' }
+        el.focus()
+        // place caret at end
+        const range = document.createRange()
+        range.selectNodeContents(el)
+        range.collapse(false)
+        const sel = window.getSelection()
+        sel.removeAllRanges()
+        sel.addRange(range)
+        return { ok: true, text: el.innerText.length }
+      })()
+    `,
+    returnByValue: true
+  })
+  if (!result.result.value?.ok) {
+    log(`focus failed: ${result.result.value?.reason ?? 'unknown'}`)
+    return false
+  }
+  log(`composer focused (existing text length: ${result.result.value.text})`)
+  return true
+}
+
+function genText(n) {
+  const lorem =
+    'the quick brown fox jumps over the lazy dog while the agent thinks really hard about why typing into this composer feels like wading through molasses on a hot afternoon '
+  let s = ''
+  while (s.length < n) s += lorem
+  return s.slice(0, n)
+}
+
+async function dispatchChar(cdp, ch) {
+  // For printable chars, char + keypress is enough — Electron treats it as text input
+  // and the contentEditable input event fires. For Enter / Space we could add
+  // specials; this run is one long line.
+  await cdp.send('Input.dispatchKeyEvent', {
+    type: 'char',
+    text: ch,
+    unmodifiedText: ch
+  })
+}
+
+async function typeText(cdp, text, cps) {
+  const intervalMs = Math.max(1, Math.round(1000 / cps))
+  const start = Date.now()
+  for (let i = 0; i < text.length; i++) {
+    await dispatchChar(cdp, text[i])
+    // Pace evenly; account for dispatch latency so we don't drift much.
+    const expected = start + (i + 1) * intervalMs
+    const wait = expected - Date.now()
+    if (wait > 0) await new Promise(r => setTimeout(r, wait))
+  }
+}
+
+async function main() {
+  log(`CDP port ${PORT}, out ${OUT}`)
+  const target = await pickRenderer()
+  log(`target ${target.url}`)
+  const cdp = await connect(target.webSocketDebuggerUrl)
+  await cdp.send('Runtime.enable')
+  await cdp.send('Page.enable')
+  await cdp.send('Profiler.enable')
+
+  // Pre-GC so the cpu profile + heap delta are clean.
+  try {
+    await cdp.send('HeapProfiler.collectGarbage')
+  } catch (e) {
+    log('GC skipped:', e.message)
+  }
+
+  if (HEAP) await captureHeap(cdp, `${OUT}.before.heapsnapshot`)
+
+  // 1ms sampling — fine enough for per-frame React work.
+  await cdp.send('Profiler.setSamplingInterval', { interval: 1000 })
+
+  let typedText = ''
+  if (!IDLE_SECONDS) {
+    const focused = await focusComposer(cdp)
+    if (!focused) {
+      log('aborting — composer not focusable. Make sure the app is past the boot screen.')
+      cdp.close()
+      process.exit(3)
+    }
+    typedText = CUSTOM_TEXT ?? genText(CHARS)
+  }
+
+  await cdp.send('Profiler.start')
+
+  if (IDLE_SECONDS) {
+    banner(`IDLE recording for ${IDLE_SECONDS}s — DO NOT TOUCH`)
+    await new Promise(r => setTimeout(r, IDLE_SECONDS * 1000))
+  } else {
+    banner(`TYPING ${typedText.length} chars @ ${CPS} cps (≈${(typedText.length / CPS).toFixed(1)}s)`)
+    const t0 = Date.now()
+    await typeText(cdp, typedText, CPS)
+    log(`typing wall time: ${((Date.now() - t0) / 1000).toFixed(2)}s`)
+    // Settle frame for trailing React work.
+    await new Promise(r => setTimeout(r, 500))
+  }
+
+  banner('STOP — saving profile')
+  const { profile } = await cdp.send('Profiler.stop')
+  writeFileSync(`${OUT}.cpuprofile`, JSON.stringify(profile))
+  log(`cpu profile → ${OUT}.cpuprofile (${(JSON.stringify(profile).length / 1024 / 1024).toFixed(1)} MB)`)
+
+  if (HEAP) {
+    try {
+      await cdp.send('HeapProfiler.collectGarbage')
+    } catch {}
+    await captureHeap(cdp, `${OUT}.after.heapsnapshot`)
+  }
+
+  // Quick triage: top-self-time frames from the profile.
+  const top = summarizeProfile(profile)
+  banner('TOP SELF-TIME FRAMES')
+  for (const row of top.slice(0, 20)) {
+    console.log(
+      `  ${row.selfMs.toFixed(1).padStart(7)}ms  ${row.functionName || '(anonymous)'}` +
+        `  ${row.url ? '· ' + row.url.replace(/^.*\/src\//, 'src/').slice(0, 80) : ''}`
+    )
+  }
+  console.log()
+  log(`total samples: ${top.totalSamples}, total time: ${(top.totalMs / 1000).toFixed(2)}s`)
+
+  cdp.close()
+}
+
+function summarizeProfile(profile) {
+  // Cumulative samples = how many sampling ticks landed on each node.
+  // selfMs = own time only, using sampling interval.
+  const intervalMs = (profile.endTime - profile.startTime) / 1000 / Math.max(1, profile.samples?.length ?? 1)
+  const counts = new Map()
+  for (const s of profile.samples ?? []) counts.set(s, (counts.get(s) ?? 0) + 1)
+  const rows = profile.nodes.map(n => {
+    const self = counts.get(n.id) ?? 0
+    return {
+      id: n.id,
+      functionName: n.callFrame.functionName,
+      url: n.callFrame.url,
+      lineNumber: n.callFrame.lineNumber,
+      selfSamples: self,
+      selfMs: self * intervalMs
+    }
+  })
+  rows.sort((a, b) => b.selfSamples - a.selfSamples)
+  rows.totalSamples = (profile.samples ?? []).length
+  rows.totalMs = ((profile.endTime - profile.startTime) / 1000)
+  return rows
+}
+
+main().catch(e => {
+  console.error('[profile] fatal:', e.stack ?? e.message)
+  process.exit(1)
+})

apps/desktop/scripts/reload-renderer.mjs

@@ -0,0 +1,25 @@
+// Reload the renderer via CDP so it picks up the latest from Vite.
+const list = await (await fetch('http://127.0.0.1:9222/json/list')).json()
+const tgt = list.find(t => t.type === 'page' && t.url.startsWith('http'))
+const ws = new WebSocket(tgt.webSocketDebuggerUrl)
+let id = 0
+const pending = new Map()
+ws.addEventListener('message', ev => {
+  const m = JSON.parse(ev.data)
+  if (m.id != null && pending.has(m.id)) {
+    pending.get(m.id)(m)
+    pending.delete(m.id)
+  }
+})
+await new Promise(r => ws.addEventListener('open', r))
+const send = (method, params = {}) =>
+  new Promise(r => {
+    const i = ++id
+    pending.set(i, r)
+    ws.send(JSON.stringify({ id: i, method, params }))
+  })
+await send('Page.enable')
+await send('Page.reload', { ignoreCache: true })
+console.log('reload requested')
+await new Promise(r => setTimeout(r, 200))
+ws.close()

apps/desktop/scripts/reload.mjs

@@ -0,0 +1,36 @@
+// Hard reload the Electron renderer over CDP. Vite-no-HMR mode means edits
+// don't auto-apply — call this after editing source.
+const targets = await (await fetch('http://127.0.0.1:9222/json')).json()
+const t = targets.find((t) => t.url.includes('5174'))
+if (!t) {
+  console.error('renderer not found')
+  process.exit(1)
+}
+const ws = new WebSocket(t.webSocketDebuggerUrl)
+let id = 0
+const pending = new Map()
+ws.addEventListener('message', (ev) => {
+  const m = JSON.parse(ev.data)
+  if (pending.has(m.id)) {
+    pending.get(m.id)(m)
+    pending.delete(m.id)
+  }
+})
+await new Promise((r) => ws.addEventListener('open', r))
+const send = (method, params = {}) =>
+  new Promise((res) => {
+    const i = ++id
+    pending.set(i, res)
+    ws.send(JSON.stringify({ id: i, method, params }))
+  })
+
+await send('Page.reload', { ignoreCache: true })
+console.log('reload sent')
+// Wait for new doc.
+await new Promise((r) => setTimeout(r, 2500))
+const r = await send('Runtime.evaluate', {
+  expression: 'JSON.stringify({ hasProbe: !!window.__PERF_PROBE__, composer: !!document.querySelector("[contenteditable=true]"), url: location.hash })',
+  returnByValue: true,
+})
+console.log(r.result.result.value)
+ws.close()