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

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.

.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/desktop-release.yml

@@ -0,0 +1,342 @@
+name: Desktop Release
+
+on:
+  push:
+    branches: [main]
+  release:
+    types: [published]
+  workflow_dispatch:
+    inputs:
+      channel:
+        description: Release channel to build
+        required: true
+        default: nightly
+        type: choice
+        options:
+          - nightly
+          - stable
+      release_tag:
+        description: "Required when channel=stable (example: v2026.5.5)"
+        required: false
+        type: string
+
+permissions:
+  contents: write
+
+concurrency:
+  group: desktop-release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  prepare:
+    if: github.repository == 'NousResearch/hermes-agent'
+    runs-on: ubuntu-latest
+    outputs:
+      channel: ${{ steps.meta.outputs.channel }}
+      release_name: ${{ steps.meta.outputs.release_name }}
+      release_tag: ${{ steps.meta.outputs.release_tag }}
+      version: ${{ steps.meta.outputs.version }}
+      is_stable: ${{ steps.meta.outputs.is_stable }}
+    steps:
+      - id: meta
+        env:
+          EVENT_NAME: ${{ github.event_name }}
+          INPUT_CHANNEL: ${{ github.event.inputs.channel }}
+          INPUT_RELEASE_TAG: ${{ github.event.inputs.release_tag }}
+          RELEASE_TAG_FROM_EVENT: ${{ github.event.release.tag_name }}
+          GITHUB_SHA: ${{ github.sha }}
+        run: |
+          set -euo pipefail
+
+          channel="nightly"
+          release_tag="desktop-nightly"
+          is_stable="false"
+
+          if [[ "$EVENT_NAME" == "release" ]]; then
+            channel="stable"
+            release_tag="$RELEASE_TAG_FROM_EVENT"
+            is_stable="true"
+          elif [[ "$EVENT_NAME" == "workflow_dispatch" && "$INPUT_CHANNEL" == "stable" ]]; then
+            channel="stable"
+            release_tag="$INPUT_RELEASE_TAG"
+            is_stable="true"
+          fi
+
+          if [[ "$channel" == "stable" ]]; then
+            if [[ -z "$release_tag" ]]; then
+              echo "Stable desktop releases require a release tag." >&2
+              exit 1
+            fi
+
+            version="${release_tag#v}"
+            release_name="Hermes Desktop ${release_tag}"
+          else
+            stamp="$(date -u +%Y%m%d)"
+            short_sha="${GITHUB_SHA::7}"
+            version="0.0.0-nightly.${stamp}.${short_sha}"
+            release_name="Hermes Desktop Nightly ${stamp}-${short_sha}"
+          fi
+
+          {
+            echo "channel=$channel"
+            echo "release_name=$release_name"
+            echo "release_tag=$release_tag"
+            echo "version=$version"
+            echo "is_stable=$is_stable"
+          } >> "$GITHUB_OUTPUT"
+
+  build:
+    if: github.repository == 'NousResearch/hermes-agent'
+    needs: prepare
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - platform: mac
+            runner: macos-latest
+            build_args: --mac dmg zip
+          - platform: win
+            runner: windows-latest
+            build_args: --win nsis msi
+    runs-on: ${{ matrix.runner }}
+    env:
+      DESKTOP_CHANNEL: ${{ needs.prepare.outputs.channel }}
+      DESKTOP_VERSION: ${{ needs.prepare.outputs.version }}
+      MAC_CSC_LINK: ${{ secrets.CSC_LINK }}
+      MAC_CSC_KEY_PASSWORD: ${{ secrets.CSC_KEY_PASSWORD }}
+      APPLE_API_KEY: ${{ secrets.APPLE_API_KEY }}
+      APPLE_API_KEY_ID: ${{ secrets.APPLE_API_KEY_ID }}
+      APPLE_API_ISSUER: ${{ secrets.APPLE_API_ISSUER }}
+      WIN_CSC_LINK: ${{ secrets.WIN_CSC_LINK }}
+      WIN_CSC_KEY_PASSWORD: ${{ secrets.WIN_CSC_KEY_PASSWORD }}
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020  # v4
+        with:
+          node-version: 20
+          cache: npm
+          cache-dependency-path: package-lock.json
+
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065  # v5
+        with:
+          python-version: "3.11"
+
+      - name: Enforce signing gates for stable releases
+        if: needs.prepare.outputs.is_stable == 'true'
+        shell: bash
+        run: |
+          set -euo pipefail
+          missing=()
+
+          if [[ "${{ matrix.platform }}" == "mac" ]]; then
+            [[ -z "${MAC_CSC_LINK:-}" ]] && missing+=("CSC_LINK")
+            [[ -z "${MAC_CSC_KEY_PASSWORD:-}" ]] && missing+=("CSC_KEY_PASSWORD")
+            [[ -z "${APPLE_API_KEY:-}" ]] && missing+=("APPLE_API_KEY")
+            [[ -z "${APPLE_API_KEY_ID:-}" ]] && missing+=("APPLE_API_KEY_ID")
+            [[ -z "${APPLE_API_ISSUER:-}" ]] && missing+=("APPLE_API_ISSUER")
+          else
+            [[ -z "${WIN_CSC_LINK:-}" ]] && missing+=("WIN_CSC_LINK")
+            [[ -z "${WIN_CSC_KEY_PASSWORD:-}" ]] && missing+=("WIN_CSC_KEY_PASSWORD")
+          fi
+
+          if (( ${#missing[@]} > 0 )); then
+            echo "::error::Stable desktop release missing required secrets: ${missing[*]}"
+            exit 1
+          fi
+
+      - name: Install workspace dependencies
+        run: npm ci
+
+      - name: Install TUI dependencies
+        run: npm --prefix ui-tui ci
+
+      - name: Build bundled TUI payload
+        run: npm --prefix ui-tui run build
+
+      - name: Build desktop renderer
+        run: npm --prefix apps/desktop run build
+
+      - name: Map macOS signing credentials
+        if: matrix.platform == 'mac'
+        shell: bash
+        run: |
+          set -euo pipefail
+          has_link=0
+          has_pass=0
+          [[ -n "${MAC_CSC_LINK:-}" ]] && has_link=1
+          [[ -n "${MAC_CSC_KEY_PASSWORD:-}" ]] && has_pass=1
+
+          if [[ $has_link -eq 1 && $has_pass -eq 1 ]]; then
+            echo "CSC_LINK=${MAC_CSC_LINK}" >> "$GITHUB_ENV"
+            echo "CSC_KEY_PASSWORD=${MAC_CSC_KEY_PASSWORD}" >> "$GITHUB_ENV"
+          elif [[ $has_link -eq 1 || $has_pass -eq 1 ]]; then
+            echo "::error::macOS signing secrets are partially configured. Set both CSC_LINK and CSC_KEY_PASSWORD."
+            exit 1
+          fi
+
+      - name: Map Windows signing credentials
+        if: matrix.platform == 'win'
+        shell: bash
+        run: |
+          set -euo pipefail
+          has_link=0
+          has_pass=0
+          [[ -n "${WIN_CSC_LINK:-}" ]] && has_link=1
+          [[ -n "${WIN_CSC_KEY_PASSWORD:-}" ]] && has_pass=1
+
+          if [[ $has_link -eq 1 && $has_pass -eq 1 ]]; then
+            echo "CSC_LINK=${WIN_CSC_LINK}" >> "$GITHUB_ENV"
+            echo "CSC_KEY_PASSWORD=${WIN_CSC_KEY_PASSWORD}" >> "$GITHUB_ENV"
+            echo "CSC_FOR_PULL_REQUEST=true" >> "$GITHUB_ENV"
+          elif [[ $has_link -eq 1 || $has_pass -eq 1 ]]; then
+            echo "::error::Windows signing secrets are partially configured. Set both WIN_CSC_LINK and WIN_CSC_KEY_PASSWORD."
+            exit 1
+          fi
+
+      - name: Build desktop installers
+        shell: bash
+        env:
+          NODE_OPTIONS: --max-old-space-size=16384
+        run: |
+          set -euo pipefail
+          npm --prefix apps/desktop run builder -- \
+            ${{ matrix.build_args }} \
+            --publish never \
+            --config.extraMetadata.version="${DESKTOP_VERSION}" \
+            --config.extraMetadata.desktopChannel="${DESKTOP_CHANNEL}"
+
+      - name: Notarize and staple macOS DMG
+        if: matrix.platform == 'mac' && needs.prepare.outputs.is_stable == 'true'
+        shell: bash
+        run: |
+          set -euo pipefail
+          dmg_path="$(ls apps/desktop/release/*.dmg | head -n 1)"
+          node apps/desktop/scripts/notarize-artifact.cjs "$dmg_path"
+
+      - name: Validate macOS notarization and Gatekeeper trust
+        if: matrix.platform == 'mac' && needs.prepare.outputs.is_stable == 'true'
+        shell: bash
+        run: |
+          set -euo pipefail
+          app_path="$(ls -d apps/desktop/release/mac*/Hermes.app | head -n 1)"
+          dmg_path="$(ls apps/desktop/release/*.dmg | head -n 1)"
+          xcrun stapler validate "$app_path"
+          xcrun stapler validate "$dmg_path"
+          spctl --assess --type execute --verbose=4 "$app_path"
+
+      - name: Generate desktop checksums
+        shell: bash
+        run: |
+          set -euo pipefail
+          node <<'EOF'
+          const crypto = require('node:crypto')
+          const fs = require('node:fs')
+          const path = require('node:path')
+
+          const releaseDir = path.resolve('apps/desktop/release')
+          const platform = process.env.PLATFORM
+          const extensions = platform === 'mac' ? ['.dmg', '.zip'] : ['.exe', '.msi']
+          const files = fs
+            .readdirSync(releaseDir)
+            .filter(name => extensions.some(ext => name.endsWith(ext)))
+            .sort()
+
+          if (!files.length) {
+            throw new Error(`No release artifacts were produced for ${platform}`)
+          }
+
+          const lines = files.map(name => {
+            const full = path.join(releaseDir, name)
+            const hash = crypto.createHash('sha256').update(fs.readFileSync(full)).digest('hex')
+            return `${hash}  ${name}`
+          })
+          fs.writeFileSync(path.join(releaseDir, `SHA256SUMS-${platform}.txt`), `${lines.join('\n')}\n`)
+          EOF
+        env:
+          PLATFORM: ${{ matrix.platform }}
+
+      - name: Upload packaged desktop artifacts
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02  # v4
+        with:
+          name: desktop-${{ matrix.platform }}
+          path: |
+            apps/desktop/release/*.dmg
+            apps/desktop/release/*.zip
+            apps/desktop/release/*.exe
+            apps/desktop/release/*.msi
+            apps/desktop/release/SHA256SUMS-${{ matrix.platform }}.txt
+          if-no-files-found: error
+
+  publish:
+    if: github.repository == 'NousResearch/hermes-agent'
+    needs: [prepare, build]
+    runs-on: ubuntu-latest
+    env:
+      GH_TOKEN: ${{ github.token }}
+      CHANNEL: ${{ needs.prepare.outputs.channel }}
+      RELEASE_NAME: ${{ needs.prepare.outputs.release_name }}
+      RELEASE_TAG: ${{ needs.prepare.outputs.release_tag }}
+    steps:
+      - uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5  # v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093  # v4
+        with:
+          pattern: desktop-*
+          merge-multiple: true
+          path: dist/desktop
+
+      - name: Publish desktop assets to GitHub release
+        shell: bash
+        run: |
+          set -euo pipefail
+          shopt -s globstar nullglob
+
+          files=(
+            dist/desktop/**/*.dmg
+            dist/desktop/**/*.zip
+            dist/desktop/**/*.exe
+            dist/desktop/**/*.msi
+            dist/desktop/**/SHA256SUMS-*.txt
+          )
+
+          if (( ${#files[@]} == 0 )); then
+            echo "No desktop artifacts were downloaded for publishing." >&2
+            exit 1
+          fi
+
+          if [[ "$CHANNEL" == "nightly" ]]; then
+            git tag -f "$RELEASE_TAG" "$GITHUB_SHA"
+            git push origin "refs/tags/$RELEASE_TAG" --force
+
+            notes="Automated nightly desktop build from main. This prerelease is replaced on each new run."
+
+            if gh release view "$RELEASE_TAG" >/dev/null 2>&1; then
+              while IFS= read -r asset_name; do
+                gh release delete-asset "$RELEASE_TAG" "$asset_name" --yes
+              done < <(gh release view "$RELEASE_TAG" --json assets -q '.assets[].name')
+
+              gh release edit "$RELEASE_TAG" \
+                --title "$RELEASE_NAME" \
+                --prerelease \
+                --notes "$notes"
+            else
+              gh release create "$RELEASE_TAG" \
+                --target "$GITHUB_SHA" \
+                --title "$RELEASE_NAME" \
+                --notes "$notes" \
+                --prerelease
+            fi
+          else
+            if ! gh release view "$RELEASE_TAG" >/dev/null 2>&1; then
+              notes="Automated desktop artifacts attached by desktop-release workflow."
+              gh release create "$RELEASE_TAG" \
+                --target "$GITHUB_SHA" \
+                --title "$RELEASE_NAME" \
+                --notes "$notes"
+            fi
+          fi
+
+          gh release upload "$RELEASE_TAG" "${files[@]}" --clobber

.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

@@ -213,3 +213,5 @@ scripts/run_tests.sh
 MIT — see [LICENSE](LICENSE).
 
 Built by [Nous Research](https://nousresearch.com).
+
+phragg was here

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/context_compressor.py

@@ -518,6 +518,10 @@ class ContextCompressor(ContextEngine):
         self._last_compression_savings_pct = 100.0
         self._ineffective_compression_count = 0
         self._summary_failure_cooldown_until = 0.0  # transient errors must not block a fresh session
+        self.last_real_prompt_tokens = 0
+        self.last_compression_rough_tokens = 0
+        self.last_rough_tokens_when_real_prompt_fit = 0
+        self.awaiting_real_usage_after_compression = False
 
     def update_model(
         self,
@@ -615,6 +619,10 @@ class ContextCompressor(ContextEngine):
 
         self.last_prompt_tokens = 0
         self.last_completion_tokens = 0
+        self.last_real_prompt_tokens = 0
+        self.last_compression_rough_tokens = 0
+        self.last_rough_tokens_when_real_prompt_fit = 0
+        self.awaiting_real_usage_after_compression = False
 
         self.summary_model = summary_model_override or ""
 
@@ -648,6 +656,44 @@ class ContextCompressor(ContextEngine):
         self.last_prompt_tokens = usage.get("prompt_tokens", 0)
         self.last_completion_tokens = usage.get("completion_tokens", 0)
         self.last_total_tokens = usage.get("total_tokens", self.last_prompt_tokens + self.last_completion_tokens)
+        if self.last_prompt_tokens > 0:
+            self.last_real_prompt_tokens = self.last_prompt_tokens
+            if self.last_prompt_tokens < self.threshold_tokens:
+                if self.awaiting_real_usage_after_compression and self.last_compression_rough_tokens > 0:
+                    self.last_rough_tokens_when_real_prompt_fit = self.last_compression_rough_tokens
+            else:
+                self.last_rough_tokens_when_real_prompt_fit = 0
+        self.awaiting_real_usage_after_compression = False
+
+    def should_defer_preflight_to_real_usage(self, rough_tokens: int) -> bool:
+        """Return True when a high rough preflight estimate is known-noisy.
+
+        ``estimate_request_tokens_rough(..., tools=...)`` intentionally
+        overestimates schema-heavy requests so Hermes compresses before a
+        provider rejects the payload. After a successful compressed API call,
+        though, provider ``prompt_tokens`` are a better signal than repeating
+        compaction from the same rough schema overhead. Defer only while the
+        rough estimate has grown modestly since a request the provider proved
+        fit under the threshold.
+        """
+        if rough_tokens < self.threshold_tokens:
+            return False
+        if self.last_real_prompt_tokens <= 0:
+            return False
+        if self.last_real_prompt_tokens >= self.threshold_tokens:
+            return False
+
+        baseline = self.last_rough_tokens_when_real_prompt_fit or self.last_compression_rough_tokens
+        if baseline <= 0:
+            return False
+
+        growth = max(0, rough_tokens - baseline)
+        tolerated_growth = max(4096, int(self.threshold_tokens * 0.05))
+        if growth > tolerated_growth:
+            return False
+
+        self.last_rough_tokens_when_real_prompt_fit = max(baseline, rough_tokens)
+        return True
 
     def should_compress(self, prompt_tokens: int = None) -> bool:
         """Check if context exceeds the compression threshold.

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:   ~/Library/Application Support/hermes
+//!   Linux:   ~/.hermes  (XDG override via $HERMES_HOME)
+//!
+//! 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");
+        }
+    }
+
+    #[cfg(target_os = "macos")]
+    {
+        // ~/Library/Application Support/hermes
+        if let Some(home) = dirs::home_dir() {
+            return home.join("Library/Application Support/hermes");
+        }
+    }
+
+    // Linux + fallback: ~/.hermes
+    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,284 @@
+# Hermes Desktop
+
+Native Electron shell for Hermes. It packages the desktop renderer, a bundled Hermes source payload, and installer targets for macOS and Windows. Note: this doc needs updating.
+
+## Setup
+
+Install workspace dependencies from the repo root so `apps/desktop`, `web`, and `apps/shared` stay linked:
+
+```bash
+npm install
+```
+
+For Python, you have two options:
+
+**Option A — let the desktop provision it for you (recommended for first-time setup):** just run `npm run dev`. On first launch the desktop creates a venv at `HERMES_HOME/hermes-agent/venv` and runs `pip install -e .` against the resolved Hermes source automatically. Requires Python 3.11+ on `PATH`.
+
+**Option B — share an existing CLI install:** if you already ran `scripts/install.ps1` / `scripts/install.sh`, that's the same layout the desktop uses. The desktop reuses your existing venv and editable install — no extra steps. See [Runtime Bootstrap](#runtime-bootstrap) below for details.
+
+If you're hacking on Hermes from a clone outside `HERMES_HOME/hermes-agent`, point the desktop at it explicitly:
+
+```bash
+HERMES_DESKTOP_HERMES_ROOT=/path/to/your/clone npm run dev
+```
+
+### Runtime prerequisites
+
+Hermes Desktop needs:
+
+- **Python 3.11+** — for the agent runtime, dashboard backend, and tool execution. (required)
+- **Git for Windows** (Windows only) — provides Git Bash, which Hermes' terminal tool calls directly. Linux and macOS already ship a system bash. (required)
+- **ripgrep** — used by Hermes' `search_files` tool for fast `.gitignore`-aware file/content search. Recommended on all platforms; Hermes falls back to `grep`/`find` if missing (works but slower and noisier).
+
+The packaged Windows installer (`Hermes-*.exe`) detects all three at install time. Required items missing are auto-installed via `winget install -e --id Python.Python.3.11 --scope user` and `winget install -e --id Git.Git`. The recommended ripgrep is offered as `winget install -e --id BurntSushi.ripgrep.MSVC --scope user`. If `winget` isn't available the installer shows manual download URLs and lets you continue. The MSI installer (`Hermes-*.msi`) doesn't run the prereq page — enterprise deploys are expected to handle prereqs out-of-band.
+
+For dev (`npm run dev`) the Python and Git Bash checks happen at first launch via the Electron bootstrapper, which throws a clear error if either prereq is missing. Manual install commands you can run yourself:
+
+```powershell
+winget install -e --id Python.Python.3.11 --scope user
+winget install -e --id Git.Git
+winget install -e --id BurntSushi.ripgrep.MSVC --scope user
+```
+
+## Development
+
+```bash
+cd apps/desktop
+npm run dev
+```
+
+`npm run dev` starts Vite on `127.0.0.1:5174`, launches Electron, and lets Electron boot the Hermes backend (`hermes dashboard --no-open --tui`) on an open port in `9120-9199`. This path is for UI iteration and may still show Electron/dev identities in OS prompts.
+
+Useful overrides:
+
+```bash
+HERMES_DESKTOP_HERMES_ROOT=/path/to/hermes-agent npm run dev
+HERMES_DESKTOP_PYTHON=/path/to/python npm run dev
+HERMES_DESKTOP_CWD=/path/to/project npm run dev
+HERMES_DESKTOP_IGNORE_EXISTING=1 npm run dev
+HERMES_HOME=/tmp/throwaway-hermes-home npm run dev
+HERMES_DESKTOP_BOOT_FAKE=1 npm run dev
+HERMES_DESKTOP_BOOT_FAKE=1 HERMES_DESKTOP_BOOT_FAKE_STEP_MS=900 npm run dev
+```
+
+`HERMES_DESKTOP_IGNORE_EXISTING=1` skips any `hermes` CLI already on `PATH`, which is useful when testing the factory-image bootstrap path.
+
+`HERMES_HOME` overrides the install root (default: `%LOCALAPPDATA%\hermes` on Windows, `~/.hermes` elsewhere) — handy for sandboxed dev runs that shouldn't touch your real config.
+
+`HERMES_DESKTOP_BOOT_FAKE=1` adds deterministic per-phase delays to desktop startup so you can validate the startup overlay and progress bar. For convenience, `npm run dev:fake-boot` enables fake mode with defaults.
+
+On a fresh Hermes profile, Desktop shows a first-run setup overlay after boot. The overlay saves the minimum required provider credential (for example `OPENROUTER_API_KEY`, `ANTHROPIC_API_KEY`, or `OPENAI_API_KEY`) to the active Hermes `.env`, reloads the backend env, and then lets the user continue without opening Settings manually.
+
+## Dashboard Dev
+
+Run the Python dashboard backend with embedded chat enabled:
+
+```bash
+hermes dashboard --tui --no-open
+```
+
+For dashboard HMR, start Vite in another terminal:
+
+```bash
+cd web
+npm run dev
+```
+
+Open the Vite URL. The dev server proxies `/api`, `/api/pty`, and plugin assets to `http://127.0.0.1:9119` and fetches the live dashboard HTML so the ephemeral session token matches the running backend.
+
+## Build
+
+```bash
+npm run build
+npm run pack          # unpacked app at release/mac-<arch>/Hermes.app
+npm run dist:mac      # macOS DMG + zip
+npm run dist:mac:dmg  # DMG only
+npm run dist:mac:zip  # zip only
+npm run dist:win      # NSIS + MSI
+```
+
+Before packaging, the desktop app no longer bundles a copy of the Hermes Agent Python source. Instead, the packaged Electron app will fetch and install Hermes Agent at first launch via `scripts/install.ps1`'s stage protocol (Windows) — see the bootstrap flow documented in `electron/main.cjs`. macOS and Linux packaged builds are temporarily non-functional until `install.sh` gains the same stage protocol; dev workflows on all three platforms continue to work since they resolve a sibling source checkout.
+
+## Automated Releases
+
+Desktop installers are published by [`.github/workflows/desktop-release.yml`](../../.github/workflows/desktop-release.yml) with two channels:
+
+- **Stable:** runs on published GitHub releases and uploads signed artifacts to that release tag.
+- **Nightly:** runs on `main` pushes and updates the rolling `desktop-nightly` prerelease.
+
+The workflow injects a channel-aware desktop version at build time:
+
+- stable: derived from the release tag (for example `v2026.5.5` -> `2026.5.5`)
+- nightly: `0.0.0-nightly.YYYYMMDD.<sha>`
+
+Artifact names include channel, platform, and architecture:
+
+```text
+Hermes-<version>-<channel>-<platform>-<arch>.<ext>
+```
+
+Each run also publishes `SHA256SUMS-<platform>.txt` so installers can be verified.
+
+### Stable release gates
+
+Stable builds fail fast if signing credentials are missing:
+
+- macOS signing + notarization: `CSC_LINK`, `CSC_KEY_PASSWORD`, `APPLE_API_KEY`, `APPLE_API_KEY_ID`, `APPLE_API_ISSUER`
+- Windows signing: `WIN_CSC_LINK`, `WIN_CSC_KEY_PASSWORD`
+
+Stable macOS builds also validate stapling and Gatekeeper assessment in CI before upload.
+
+## Icons
+
+Desktop icons live in `assets/`:
+
+- `assets/icon.icns`
+- `assets/icon.ico`
+- `assets/icon.png`
+
+The builder config points at `assets/icon`. Replace these files directly if the app icon changes.
+
+## Testing Install Paths
+
+Use the package-local test scripts from this directory:
+
+```bash
+npm run test:desktop:all
+npm run test:desktop:existing
+npm run test:desktop:fresh
+npm run test:desktop:dmg
+npm run test:desktop:platforms
+```
+
+`test:desktop:existing` builds the packaged app and opens it normally. It should use an existing `hermes` CLI if one is on `PATH`, preserving the user’s real `~/.hermes` config.
+
+`test:desktop:fresh` builds the packaged app and launches it in a throwaway fresh-install sandbox. It sets `HERMES_DESKTOP_IGNORE_EXISTING=1`, points Electron `userData` at a temp dir, points `HERMES_HOME` at a temp dir, and launches through the factory-image bootstrap path without touching your real desktop runtime or `~/.hermes`.
+
+`test:desktop:dmg` builds and opens the DMG.
+
+`test:desktop:platforms` runs platform bootstrap-path assertions, including:
+- existing-CLI vs factory-image runtime path selection semantics
+- WSL2 protection against Windows `.exe/.cmd/.bat/.ps1` overrides
+- platform-specific runtime import checks (`winpty` vs `ptyprocess`)
+
+For fast reruns without rebuilding:
+
+```bash
+HERMES_DESKTOP_SKIP_BUILD=1 npm run test:desktop:fresh
+HERMES_DESKTOP_SKIP_BUILD=1 npm run test:desktop:existing
+HERMES_DESKTOP_SKIP_BUILD=1 npm run test:desktop:dmg
+```
+
+## Installing Locally
+
+```bash
+npm run dist:mac:dmg
+open release/Hermes-0.0.0-arm64.dmg
+```
+
+Drag `Hermes` to Applications. If testing repeated installs, replace the existing app.
+
+## Runtime Bootstrap
+
+Hermes Desktop shares its install layout with the CLI installers (`scripts/install.ps1`, `scripts/install.sh`) so a desktop-only user and a CLI-only user end up with the same files in the same places.
+
+### Where things live
+
+```text
+HERMES_HOME/                       # %LOCALAPPDATA%\hermes (Windows)
+                                   # ~/.hermes (macOS / Linux)
+├── hermes-agent/                  # ACTIVE_HERMES_ROOT — git checkout
+│   ├── .git/                      # canonical install is always a git checkout
+│   ├── hermes_cli/, agent/, ...   # Python source
+│   ├── pyproject.toml             # source of truth for deps
+│   ├── venv/                      # virtualenv (Scripts\python.exe on Windows,
+│   │                              #             bin/python elsewhere)
+│   └── .hermes-bootstrap-complete # marker: first-launch install.ps1 succeeded
+├── git/                           # PortableGit (Windows; installed by install.ps1)
+├── config.yaml                    # user config
+├── .env                           # API keys
+└── logs/
+    ├── desktop.log                # Electron-side boot log
+    ├── agent.log
+    ├── errors.log
+    └── gateway.log
+```
+
+The packaged installer ships only the Electron app — Hermes Agent itself is fetched and installed at first launch by running `scripts/install.ps1` (Windows) against the git ref baked into the .exe at build time (see `apps/desktop/scripts/write-build-stamp.cjs`).
+
+### Resolution order
+
+The desktop resolves a Hermes backend in this order:
+
+1. `HERMES_DESKTOP_HERMES_ROOT` — explicit dev override.
+2. Repo source root — only when running `npm run dev` from a checkout. Takes precedence over `HERMES_HOME/hermes-agent` so devs always run their local edits.
+3. `HERMES_HOME/hermes-agent` if the `.hermes-bootstrap-complete` marker is present. The marker attests that install.ps1 succeeded and the user finished initial configuration; we trust the install and skip the bootstrap flow on every launch after the first.
+4. Existing `hermes` CLI on PATH (skipped when `HERMES_DESKTOP_IGNORE_EXISTING=1`).
+5. Pip-installed `hermes_cli` module via system Python.
+6. None of the above → bootstrap-needed sentinel. The desktop's first-launch wizard runs `scripts/install.ps1` stages, then writes the marker on success.
+
+### First-launch flow on a packaged install
+
+1. `resolveHermesBackend()` returns `kind: 'bootstrap-needed'`.
+2. The renderer shows the install overlay; main fetches `scripts/install.ps1` from GitHub at the pinned commit (from `install-stamp.json`).
+3. Main drives `install.ps1 -Manifest` to get the stage list, then iterates `install.ps1 -Stage <name> -NonInteractive -Json` with live progress events to the renderer.
+4. On all stages succeeding, main writes `.hermes-bootstrap-complete` with `{ schemaVersion, pinnedCommit, pinnedBranch, completedAt, desktopVersion }`.
+5. Renderer hands off to the existing onboarding overlay (API key / model / persona).
+6. Subsequent launches see the marker and skip everything in steps 1-5.
+
+### Updates
+
+Once bootstrapped, the install is a real git checkout. Updates flow through the in-app update path (`applyUpdates()` → `git fetch && git pull --ff-only` against the configured branch) or `hermes update` from the CLI. Both check `pyproject.toml` drift and re-run `pip install -e .` only when needed.
+
+A user who installed via `scripts/install.ps1` directly (so `HERMES_HOME/hermes-agent/.git` exists but no `.hermes-bootstrap-complete` marker) is detected via resolver step 4 (their `hermes` CLI on PATH) and the desktop reuses their install without re-running the bootstrap.
+
+## Debugging
+
+Desktop boot logs are written to:
+
+```text
+HERMES_HOME/logs/desktop.log     # %LOCALAPPDATA%\hermes\logs\desktop.log on Windows
+                                  # ~/.hermes/logs/desktop.log on macOS / Linux
+```
+
+If the UI reports `Desktop boot failed`, check that log first. It includes the backend command output and recent Python traceback context.
+
+To force a fresh first-launch bootstrap (rare — useful for development / dogfooding the install flow):
+
+```bash
+# macOS / Linux
+rm "$HOME/.hermes/hermes-agent/.hermes-bootstrap-complete"
+
+# Windows (PowerShell)
+Remove-Item "$env:LOCALAPPDATA\hermes\hermes-agent\.hermes-bootstrap-complete"
+```
+
+For a full reset of just the Python venv (rare — usually only needed if the venv is broken):
+
+```bash
+# macOS / Linux
+rm -rf "$HOME/.hermes/hermes-agent/venv"
+
+# Windows (PowerShell)
+Remove-Item -Recurse -Force "$env:LOCALAPPDATA\hermes\hermes-agent\venv"
+```
+
+To reset stale macOS microphone permission prompts:
+
+```bash
+tccutil reset Microphone com.github.Electron
+tccutil reset Microphone com.nousresearch.hermes
+```
+
+## Verification
+
+Run before handing off installer changes:
+
+```bash
+npm run fix
+npm run type-check
+npm run lint
+npm run test:desktop:all
+```
+
+Current lint may report existing warnings, but it should exit with no errors.

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,466 @@
+'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)
+ *   - macOS / Linux install.sh equivalent
+ */
+
+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 resolveLocalInstallScript(sourceRepoRoot) {
+  if (!sourceRepoRoot) return null
+  const candidate = path.join(sourceRepoRoot, 'scripts', 'install.ps1')
+  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}.ps1`)
+}
+
+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 url = `https://raw.githubusercontent.com/NousResearch/hermes-agent/${commit}/scripts/install.ps1`
+  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 install.ps1: 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 install.ps1: 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 install.ps1 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 install.ps1 at ${localScript}` })
+    return { path: localScript, source: 'local' }
+  }
+
+  // 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 install.ps1: 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 install.ps1 for ${installStamp.commit.slice(0, 12)}` })
+    return { path: cached, source: 'cache', commit: installStamp.commit }
+  } catch {
+    // not cached; download
+  }
+
+  emit({ type: 'log', line: `[bootstrap] fetching install.ps1 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 }
+}
+
+// ---------------------------------------------------------------------------
+// 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 })
+    })
+  })
+}
+
+// ---------------------------------------------------------------------------
+// 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
+}
+
+async function fetchManifest({ scriptPath, emit, hermesHome, installStamp }) {
+  const pinArgs = buildPinArgs(installStamp)
+  const result = await spawnPowerShell(scriptPath, ['-Manifest', ...pinArgs], {
+    emit,
+    stageName: '__manifest__',
+    hermesHome
+  })
+  if (result.code !== 0) {
+    throw new Error(`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(`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, stage, emit, hermesHome, abortSignal, installStamp }) {
+  const startedAt = Date.now()
+  emit({ type: 'stage', name: stage.name, state: 'running' })
+
+  const pinArgs = buildPinArgs(installStamp)
+  const result = await spawnPowerShell(
+    scriptPath,
+    ['-Stage', stage.name, '-NonInteractive', '-Json', ...pinArgs],
+    { 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: `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 install.ps1
+    const scriptInfo = await resolveInstallScript({ installStamp, sourceRepoRoot, hermesHome, emit })
+
+    // 2. Fetch manifest
+    const manifest = await fetchManifest({ scriptPath: scriptInfo.path, emit, hermesHome, 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, stage, emit, hermesHome, 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,108 @@
+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),
+  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'),
+  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,216 @@
+{
+  "name": "hermes",
+  "productName": "Hermes",
+  "private": true,
+  "version": "0.0.2",
+  "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",
+    "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",
+    "extraResources": [
+      {
+        "from": "build/install-stamp.json",
+        "to": "install-stamp.json"
+      },
+      {
+        "from": "build/native-deps",
+        "to": "native-deps"
+      }
+    ],
+    "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
+    },
+    "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/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()