Import AITURK IDE 1.0.0-beta.1 from Hermes 63279301; preserve MIT license

.coderabbit.yaml

@@ -0,0 +1,18 @@
+# CodeRabbit configuration.
+#
+# Auto-review is DISABLED repo-wide: the app was enabled at the org level on
+# 2026-08-14 and immediately began reviewing every opened PR. This repo's
+# merge gate is CI ("All required checks pass") plus maintainer review —
+# CodeRabbit reviews carry no merge weight (protect-main ruleset requires
+# 0 approving reviews), so auto-firing on the full PR firehose adds comment
+# noise without gating value.
+#
+# The bot stays installed and summonable on demand: comment
+# `@coderabbitai review` on any PR to request a one-off review, or
+# `@coderabbitai ignore` to mute it on a PR it has already joined.
+#
+# To re-enable auto-review, flip `enabled: true` below (or delete this file —
+# the app default is on).
+reviews:
+  auto_review:
+    enabled: false

.dockerignore

@@ -0,0 +1,115 @@
+# Git
+.git
+.gitignore
+.gitmodules
+
+# Python
+__pycache__
+*.py[cod]
+*$py.class
+*.so
+.Python
+*.egg-info/
+dist/
+build/
+
+# Virtual environments
+venv/
+env/
+ENV/
+
+# Dependencies
+node_modules
+**/node_modules
+.venv
+**/.venv
+.notebooklm-cli-venv/
+.notebooklm-playwright/
+.pip-cache/
+.uv-cache/
+
+# Built artifacts that are regenerated inside the image.  Excluded so local
+# rebuilds on the developer's machine don't invalidate the npm-install layer
+# that now depends on the full ui-tui/packages/hermes-ink/ tree being present.
+ui-tui/dist/
+ui-tui/packages/hermes-ink/dist/
+
+# CI/CD
+.github
+
+# Environment files
+.env
+.env.*
+# ...but keep the template: docker/stage2-hook.sh seeds $HERMES_HOME/.env from
+# /opt/hermes/.env.example on first boot (OOF-285 — excluding it silently broke
+# first-boot .env seeding and the API_SERVER_KEY generation that depends on it).
+!.env.example
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Documentation
+*.md
+
+# Runtime data (bind-mounted at /opt/data; must not leak into build context)
+data/
+.hermes-docker/
+.notebooklm-home/
+
+# Compose/profile runtime state (bind-mounted; avoid ownership/secret issues)
+hermes-config/
+runtime/
+
+# ---------- Not needed inside the Docker image ----------
+
+# Desktop app source (Tauri/Electron); never installed in the container.
+# apps/shared is the dashboard↔desktop websocket helper and is linked from
+# web/package.json as a file: workspace dep — keep it in the build context.
+apps/
+!apps/shared/
+!apps/shared/**
+
+# Test suite — not shipped in production images
+tests/
+
+# Documentation site (Docusaurus) and supplementary docs
+website/
+docs/
+
+# Assets only used by the GitHub README
+assets/
+infographic/
+
+# Plugin-level docs (hermes-achievements ships docs/ but the runtime doesn't read them)
+plugins/hermes-achievements/docs/
+
+# Nix / Homebrew / AUR packaging metadata — irrelevant to Docker
+nix/
+flake.nix
+flake.lock
+packaging/
+
+# Design and planning documents
+plans/
+.plans/
+
+# Repo-level dotfiles that are git-only or dev-tooling config
+.envrc
+.gitattributes
+.hadolint.yaml
+.mailmap
+
+# Debug/export artifacts — must never reach image layers (COPY . .)
+/log.txt
+/sqlite_leak_fix.png
+/*.png.bak
+*.tar.gz
+*.tgz

.env.example

@@ -0,0 +1,535 @@
+# Hermes Agent Environment Configuration
+# Copy this file to .env and fill in your API keys
+
+# =============================================================================
+# LLM PROVIDER (Fireworks AI)
+# =============================================================================
+# Get your key at: https://app.fireworks.ai/settings/users/api-keys
+# Address models directly by catalog ID, e.g.
+#   accounts/fireworks/models/kimi-k2p6, accounts/fireworks/models/glm-5p2
+# FIREWORKS_API_KEY=
+# =============================================================================
+# LLM PROVIDER (OpenRouter)
+# =============================================================================
+# OpenRouter provides access to many models through one API
+# All LLM calls go through OpenRouter - no direct provider keys needed
+# Get your key at: https://openrouter.ai/keys
+# OPENROUTER_API_KEY=
+
+# Default model is configured in ~/.hermes/config.yaml (model.default).
+# Use 'hermes model' or 'hermes setup' to change it.
+# LLM_MODEL is no longer read from .env — this line is kept for reference only.
+# LLM_MODEL=anthropic/claude-opus-4.6
+
+# =============================================================================
+# LLM PROVIDER (NovitaAI)
+# =============================================================================
+# NovitaAI — 90+ models, pay-per-use
+# Get your key at: https://novita.ai/settings/key-management
+# NOVITA_API_KEY=
+# NOVITA_BASE_URL=https://api.novita.ai/openai/v1  # Override default base URL
+
+# =============================================================================
+# LLM PROVIDER (Google AI Studio / Gemini)
+# =============================================================================
+# Native Gemini API via Google's OpenAI-compatible endpoint.
+# Get your key at: https://aistudio.google.com/app/apikey
+# GOOGLE_API_KEY=your_google_ai_studio_key_here
+# GEMINI_API_KEY=your_gemini_key_here  # alias for GOOGLE_API_KEY
+# Optional base URL override (default: Google's OpenAI-compatible endpoint)
+# GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai
+
+# =============================================================================
+# LLM PROVIDER (Ollama Cloud)
+# =============================================================================
+# Cloud-hosted open models via Ollama's OpenAI-compatible endpoint.
+# Get your key at: https://ollama.com/settings
+# OLLAMA_API_KEY=your_ollama_key_here
+# Optional base URL override (default: https://ollama.com/v1)
+# OLLAMA_BASE_URL=https://ollama.com/v1
+
+# =============================================================================
+# LLM PROVIDER (z.ai / GLM)
+# =============================================================================
+# z.ai provides access to ZhipuAI GLM models (GLM-4-Plus, etc.)
+# Get your key at: https://z.ai or https://open.bigmodel.cn
+# GLM_API_KEY=
+# GLM_BASE_URL=https://api.z.ai/api/paas/v4  # Override default base URL
+
+# =============================================================================
+# LLM PROVIDER (Kimi / Moonshot)
+# =============================================================================
+# Kimi Code provides access to Moonshot AI coding models (kimi-k2.5, etc.)
+# Get your key at: https://platform.kimi.ai (Kimi Code console)
+# Keys prefixed sk-kimi- use the Kimi Code API (api.kimi.com) by default.
+# Legacy keys from platform.moonshot.ai need KIMI_BASE_URL override below.
+# KIMI_API_KEY=
+# KIMI_BASE_URL=https://api.kimi.com/coding/v1  # Default for sk-kimi- keys
+# KIMI_BASE_URL=https://api.moonshot.ai/v1      # For legacy Moonshot keys
+# KIMI_BASE_URL=https://api.moonshot.cn/v1       # For Moonshot China keys
+# KIMI_CN_API_KEY=                               # Dedicated Moonshot China key
+
+# =============================================================================
+# LLM PROVIDER (Arcee AI)
+# =============================================================================
+# Arcee AI provides access to Trinity models (trinity-mini, trinity-large-*)
+# Get an Arcee key at: https://chat.arcee.ai/
+# ARCEEAI_API_KEY=
+# ARCEE_BASE_URL=                                 # Override default base URL
+
+# =============================================================================
+# LLM PROVIDER (MiniMax)
+# =============================================================================
+# MiniMax provides access to MiniMax models (global endpoint)
+# Get your key at: https://www.minimax.io
+# MINIMAX_API_KEY=
+# MINIMAX_BASE_URL=https://api.minimax.io/v1  # Override default base URL
+
+# MiniMax China endpoint (for users in mainland China)
+# MINIMAX_CN_API_KEY=
+# MINIMAX_CN_BASE_URL=https://api.minimaxi.com/v1  # Override default base URL
+
+# =============================================================================
+# LLM PROVIDER (OpenCode Zen)
+# =============================================================================
+# OpenCode Zen provides curated, tested models (GPT, Claude, Gemini, MiniMax, GLM, Kimi)
+# Pay-as-you-go pricing. Get your key at: https://opencode.ai/auth
+# OPENCODE_ZEN_API_KEY=
+# OPENCODE_ZEN_BASE_URL=https://opencode.ai/zen/v1  # Override default base URL
+
+# =============================================================================
+# LLM PROVIDER (OpenCode Go)
+# =============================================================================
+# OpenCode Go provides access to open models (GLM-5, Kimi K2.5, MiniMax M2.5)
+# $10/month subscription. Get your key at: https://opencode.ai/auth
+# OPENCODE_GO_API_KEY=
+
+# =============================================================================
+# LLM PROVIDER (OpenCode Free)
+# =============================================================================
+# OpenCode Free provides keyless free models (Ox Alpha / x-preview-f-free,
+# big-pickle, etc.). NO env var and NO account needed — requests are sent
+# anonymously (the free tier rejects any unrecognized Authorization header).
+# Select it with `hermes model` or `/model free`.
+
+# =============================================================================
+# LLM PROVIDER (Hugging Face Inference Providers)
+# =============================================================================
+# Hugging Face routes to 20+ open models via unified OpenAI-compatible endpoint.
+# Free tier included ($0.10/month), no markup on provider rates.
+# Get your token at: https://huggingface.co/settings/tokens
+# Required permission: "Make calls to Inference Providers"
+# HF_TOKEN=
+# HF_BASE_URL=https://router.huggingface.co/v1  # Override default base URL
+# OPENCODE_GO_BASE_URL=https://opencode.ai/zen/go/v1  # Override default base URL
+
+# DeepInfra — 100+ top open models, pay-per-use.
+# Get your key at: https://deepinfra.com/dash/api_keys
+# DEEPINFRA_API_KEY=
+
+# =============================================================================
+# LLM PROVIDER (Qwen OAuth)
+# =============================================================================
+# Qwen OAuth reuses your local Qwen CLI login (qwen auth qwen-oauth).
+# No API key needed — credentials come from ~/.qwen/oauth_creds.json.
+# Optional base URL override:
+# HERMES_QWEN_BASE_URL=https://portal.qwen.ai/v1
+
+# =============================================================================
+# LLM PROVIDER (Xiaomi MiMo)
+# =============================================================================
+# Xiaomi MiMo models (mimo-v2-pro, mimo-v2-omni, mimo-v2-flash).
+# Get your key at: https://platform.xiaomimimo.com
+# XIAOMI_API_KEY=your_key_here
+# Optional base URL override:
+# XIAOMI_BASE_URL=https://api.xiaomimimo.com/v1
+
+# =============================================================================
+# LLM PROVIDER (Upstage Solar)
+# =============================================================================
+# Upstage provides access to Upstage Solar models.
+# Get your key at: https://console.upstage.ai/api-keys
+# UPSTAGE_API_KEY=your_key_here
+# Optional base URL override:
+# UPSTAGE_BASE_URL=https://api.upstage.ai/v1
+
+# =============================================================================
+# LLM PROVIDER (Ramp Router)
+# =============================================================================
+# Ramp Router (router.com) — Responses-native LLM gateway; model IDs come
+# from your account's live catalog (GET /v1/models).
+# Get your key at: https://app.router.com/keys
+# RAMP_ROUTER_API_KEY=your_key_here
+# Optional base URL override:
+# RAMP_ROUTER_BASE_URL=https://api.router.com/v1
+
+# =============================================================================
+# LLM PROVIDER (Nebius Token Factory)
+# =============================================================================
+# Nebius Token Factory — OpenAI-compatible inference for open models.
+# Get your key at: https://tokenfactory.nebius.com/
+# NEBIUS_API_KEY=your_key_here
+# Optional base URL override:
+# NEBIUS_BASE_URL=https://api.tokenfactory.nebius.com/v1
+
+# =============================================================================
+# LLM PROVIDER (Tencent Hy — TokenHub & TokenPlan)
+# =============================================================================
+# Tencent TokenHub (OpenAI-compatible): https://tokenhub.tencentmaas.com
+# TOKENHUB_API_KEY=your_key_here
+# TOKENHUB_BASE_URL=https://tokenhub.tencentmaas.com/v1
+# Tencent TokenPlan (Anthropic Messages endpoint via LKEAP):
+# TOKENPLAN_API_KEY=your_key_here
+# TOKENPLAN_BASE_URL=https://api.lkeap.cloud.tencent.com/plan/anthropic
+
+# =============================================================================
+# TOOL API KEYS
+# =============================================================================
+
+# Exa API Key - AI-native web search and contents
+# Get at: https://exa.ai
+# EXA_API_KEY=
+
+# Parallel API Key - AI-native web search and extract
+# Get at: https://parallel.ai
+# PARALLEL_API_KEY=
+
+# Firecrawl API Key - Web search, extract, and crawl
+# Get at: https://firecrawl.dev/
+# FIRECRAWL_API_KEY=
+
+
+# FAL.ai API Key - Image generation
+# Get at: https://fal.ai/
+# FAL_KEY=
+
+# Honcho - Cross-session AI-native user modeling (optional)
+# Builds a persistent understanding of the user across sessions and tools.
+# Get at: https://app.honcho.dev
+# Also requires ~/.honcho/config.json with enabled=true (see README).
+# HONCHO_API_KEY=
+
+# =============================================================================
+# HYPERLIQUID OPTIONAL SKILL
+# =============================================================================
+# Optional defaults for the Hyperliquid skill in optional-skills/blockchain/hyperliquid
+#
+# Hyperliquid API base URL override
+# Default: https://api.hyperliquid.xyz
+# HYPERLIQUID_API_URL=https://api.hyperliquid-testnet.xyz
+#
+# Default address for account-level commands like state, fills, orders, and review
+# HYPERLIQUID_USER_ADDRESS=0x0000000000000000000000000000000000000000
+
+# =============================================================================
+# TERMINAL TOOL CONFIGURATION
+# =============================================================================
+# Backend type: "local", "singularity", "docker", "modal", or "ssh"
+# Terminal backend is configured in ~/.hermes/config.yaml (terminal.backend).
+# Use 'hermes setup' or 'hermes config set terminal.backend docker' to change.
+# Supported: local, docker, singularity, modal, ssh
+#
+# Only override here if you need to force a backend without touching config.yaml:
+# TERMINAL_ENV=local
+
+# Override the container runtime binary (e.g. to use Podman instead of Docker).
+# Useful on systems where Docker's storage driver is broken or unavailable.
+# HERMES_DOCKER_BINARY=/usr/local/bin/podman
+
+# Container images (for singularity/docker/modal backends)
+# TERMINAL_DOCKER_IMAGE=nikolaik/python-nodejs:python3.11-nodejs20
+# TERMINAL_SINGULARITY_IMAGE=docker://nikolaik/python-nodejs:python3.11-nodejs20
+TERMINAL_MODAL_IMAGE=nikolaik/python-nodejs:python3.11-nodejs20
+
+
+# Working directory for terminal commands
+# For local backend: "." means current directory (resolved automatically)
+# For remote backends (ssh/docker/modal/singularity): use an absolute path
+#   INSIDE the target environment, or leave unset for the backend's default
+#   (/root for modal, / for docker, ~ for ssh). Do NOT use a host-local path.
+# Usually managed by config.yaml (terminal.cwd) — uncomment to override
+# TERMINAL_CWD=.
+
+# Default command timeout in seconds
+TERMINAL_TIMEOUT=60
+
+# Cleanup inactive environments after this many seconds
+TERMINAL_LIFETIME_SECONDS=300
+
+# =============================================================================
+# SSH REMOTE EXECUTION (for TERMINAL_ENV=ssh)
+# =============================================================================
+# Run terminal commands on a remote server via SSH.
+# Agent code stays on your machine, commands execute remotely.
+#
+# SECURITY BENEFITS:
+# - Agent cannot read your .env file (API keys protected)
+# - Agent cannot modify its own code
+# - Remote server acts as isolated sandbox
+# - Can safely configure passwordless sudo on remote
+#
+# TERMINAL_SSH_HOST=192.168.1.100
+# TERMINAL_SSH_USER=agent
+# TERMINAL_SSH_PORT=22
+# TERMINAL_SSH_KEY=~/.ssh/id_rsa
+
+# =============================================================================
+# SUDO SUPPORT (works with ALL terminal backends)
+# =============================================================================
+# If set, enables sudo commands by piping password via `sudo -S`.
+# Works with: local, docker, singularity, modal, and ssh backends.
+# 
+# SECURITY WARNING: Password stored in plaintext. Only use on trusted machines.
+# 
+# ALTERNATIVES:
+# - For SSH backend: Configure passwordless sudo on the remote server
+# - For containers: Run as root inside the container (no sudo needed)
+# - For local: Configure /etc/sudoers for specific commands
+# - For CLI: Leave unset - you'll be prompted interactively with 45s timeout
+#
+# SUDO_PASSWORD=your_password_here
+
+# =============================================================================
+# MODAL CLOUD BACKEND (Optional - for TERMINAL_ENV=modal)
+# =============================================================================
+# Modal uses CLI authentication, not environment variables.
+# Run: pip install modal && modal setup
+# This will authenticate via browser and store credentials locally.
+# No API key needed in .env - Modal handles auth automatically.
+
+# =============================================================================
+# BROWSER TOOL CONFIGURATION (agent-browser + Browserbase)
+# =============================================================================
+# Browser automation requires Browserbase cloud service for remote browser execution.
+# This allows the agent to navigate websites, fill forms, and extract information.
+#
+# STEALTH MODES:
+# - Basic Stealth: ALWAYS active (random fingerprints, auto CAPTCHA solving)
+# - Advanced Stealth: Requires BROWSERBASE_ADVANCED_STEALTH=true (Scale Plan only)
+
+# Browserbase API Key - Cloud browser execution
+# Get at: https://browserbase.com/
+# BROWSERBASE_API_KEY=
+
+# Browserbase Project ID - From your Browserbase dashboard
+# BROWSERBASE_PROJECT_ID=
+
+# Enable residential proxies for better CAPTCHA solving (default: true)
+# Routes traffic through residential IPs, significantly improves success rate
+BROWSERBASE_PROXIES=true
+
+# Enable advanced stealth mode (default: false, requires Scale Plan)
+# Uses custom Chromium build to avoid bot detection altogether
+BROWSERBASE_ADVANCED_STEALTH=false
+
+# Local browser engine (default: auto = Chrome)
+# "auto"       — use Chrome
+# "lightpanda" — use Lightpanda (faster navigation, no screenshots)
+# "chrome"     — explicitly request Chrome
+# Browser Use mode (default) spawns `lightpanda serve` itself; the built-in
+# browser tools pass --engine to agent-browser v0.25.3+ and retry failed or
+# empty Lightpanda results with Chrome. Ignored while a cloud provider,
+# Camofox or browser.cdp_url is active (`hermes doctor` reports that).
+# Also configurable via browser.engine in config.yaml.
+# AGENT_BROWSER_ENGINE=auto
+
+# Browser session timeout in seconds (default: 300)
+# Sessions are cleaned up after this duration of inactivity
+BROWSER_SESSION_TIMEOUT=300
+
+# Browser inactivity timeout - auto-cleanup inactive sessions (default: 120 = 2 min)
+# Browser sessions are automatically closed after this period of no activity
+BROWSER_INACTIVITY_TIMEOUT=120
+
+# Extra Chromium launch flags passed to agent-browser, comma- or newline-separated.
+# Hermes auto-injects "--no-sandbox,--disable-dev-shm-usage" when it detects root
+# or AppArmor-restricted unprivileged user namespaces (Ubuntu 23.10+, DGX Spark,
+# many container images), so leave this unset unless you need extra flags.
+# Setting this disables the auto-injection.
+# AGENT_BROWSER_ARGS=--no-sandbox
+
+# Camofox local anti-detection browser (Camoufox-based Firefox).
+# Set CAMOFOX_URL to route the browser tools through a local Camofox server
+# instead of agent-browser/Browserbase. See docs/user-guide/features/browser.md.
+# CAMOFOX_URL=http://localhost:9377
+
+# Externally managed Camofox sessions — when another app owns the visible
+# Camofox browser, set these so Hermes shares the same userId/profile instead
+# of creating its own isolated session.
+# CAMOFOX_USER_ID=
+# CAMOFOX_SESSION_KEY=
+# Set to true to reuse an already-open Camofox tab for this identity before
+# creating a new one (useful for gateway restarts).
+# CAMOFOX_ADOPT_EXISTING_TAB=false
+
+# =============================================================================
+# SESSION LOGGING
+# =============================================================================
+# Session trajectories are automatically saved to logs/ directory
+# Format: logs/session_YYYYMMDD_HHMMSS_UUID.json
+# Contains full conversation history in trajectory format for debugging/replay
+
+# =============================================================================
+# VOICE TRANSCRIPTION & OPENAI TTS
+# =============================================================================
+# Required for voice message transcription (Whisper) and OpenAI TTS voices.
+# Uses OpenAI's API directly (not via OpenRouter).
+# Named VOICE_TOOLS_OPENAI_KEY to avoid interference with OpenRouter.
+# Get at: https://platform.openai.com/api-keys
+# VOICE_TOOLS_OPENAI_KEY=
+
+# =============================================================================
+# SLACK INTEGRATION
+# =============================================================================
+# Slack Bot Token - From Slack App settings (OAuth & Permissions)
+# Get at: https://api.slack.com/apps
+# SLACK_BOT_TOKEN=xoxb-...
+
+# Slack App Token - For Socket Mode (App-Level Tokens in Slack App settings)
+# SLACK_APP_TOKEN=xapp-...
+
+# Slack allowed users (comma-separated Slack user IDs)
+# SLACK_ALLOWED_USERS=
+
+# =============================================================================
+# TELEGRAM INTEGRATION
+# =============================================================================
+# Telegram Bot Token - From @BotFather (https://t.me/BotFather)
+# TELEGRAM_BOT_TOKEN=
+# TELEGRAM_ALLOWED_USERS=                  # Comma-separated user IDs
+# TELEGRAM_HOME_CHANNEL=                   # Default chat for cron delivery
+# TELEGRAM_HOME_CHANNEL_NAME=              # Display name for home channel
+# TELEGRAM_CRON_THREAD_ID=                 # Forum topic ID for cron deliveries; overrides TELEGRAM_HOME_CHANNEL_THREAD_ID for cron so replies work in topic mode
+
+# Webhook mode (optional — for cloud deployments like Fly.io/Railway)
+# Default is long polling. Setting TELEGRAM_WEBHOOK_URL switches to webhook mode.
+# TELEGRAM_WEBHOOK_URL=https://my-app.fly.dev/telegram
+# TELEGRAM_WEBHOOK_PORT=8443
+# TELEGRAM_WEBHOOK_SECRET=                 # Recommended for production
+
+# WhatsApp (built-in Baileys bridge — run `hermes whatsapp` to pair)
+# WHATSAPP_ENABLED=false
+# WHATSAPP_ALLOWED_USERS=15551234567
+
+# Email (IMAP/SMTP — send and receive emails as Hermes)
+# For Gmail: enable 2FA → create App Password at https://myaccount.google.com/apppasswords
+# EMAIL_ADDRESS=hermes@gmail.com
+# EMAIL_PASSWORD=xxxx xxxx xxxx xxxx
+# EMAIL_IMAP_HOST=imap.gmail.com
+# EMAIL_IMAP_PORT=993
+# EMAIL_SMTP_HOST=smtp.gmail.com
+# EMAIL_SMTP_PORT=587
+# EMAIL_POLL_INTERVAL=15
+# EMAIL_ALLOWED_USERS=your@email.com
+# EMAIL_HOME_ADDRESS=your@email.com
+
+# Gateway-wide: allow ALL users without an allowlist (default: false = deny)
+# Only set to true if you intentionally want open access.
+# GATEWAY_ALLOW_ALL_USERS=false
+
+# =============================================================================
+# RESPONSE PACING
+# =============================================================================
+# Human-like delays between message chunks on messaging platforms.
+# Makes the bot feel less robotic.
+# HERMES_HUMAN_DELAY_MODE=off     # off | natural | custom
+# HERMES_HUMAN_DELAY_MIN_MS=800   # Min delay in ms (custom mode)
+# HERMES_HUMAN_DELAY_MAX_MS=2500  # Max delay in ms (custom mode)
+
+# =============================================================================
+# DEBUG OPTIONS
+# =============================================================================
+WEB_TOOLS_DEBUG=false
+VISION_TOOLS_DEBUG=false
+MOA_TOOLS_DEBUG=false
+IMAGE_TOOLS_DEBUG=false
+
+# =============================================================================
+# CONTEXT COMPRESSION (Auto-shrinks long conversations)
+# =============================================================================
+# When conversation approaches model's context limit, middle turns are
+# automatically summarized to free up space.
+#
+# Context compression is configured in ~/.hermes/config.yaml under compression:
+# CONTEXT_COMPRESSION_ENABLED=true        # Enable auto-compression (default: true)
+# CONTEXT_COMPRESSION_THRESHOLD=0.85      # Compress at 85% of context limit
+# Model is set via compression.summary_model in config.yaml (default: google/gemini-3-flash-preview)
+
+# =============================================================================
+# SKILLS HUB (GitHub integration for skill search/install/publish)
+# =============================================================================
+
+# GitHub Personal Access Token — for higher API rate limits on skill search/install
+# Get at: https://github.com/settings/tokens (Fine-grained recommended)
+# GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
+
+# GitHub App credentials (optional — for bot identity on PRs)
+# GITHUB_APP_ID=
+# GITHUB_APP_PRIVATE_KEY_PATH=
+# GITHUB_APP_INSTALLATION_ID=
+
+# Groq API key (free tier — used for Whisper STT in voice mode)
+# GROQ_API_KEY=
+
+# ElevenLabs API key (cloud STT/TTS — Scribe transcription)
+# ELEVENLABS_API_KEY=
+
+# =============================================================================
+# STT PROVIDER SELECTION
+# =============================================================================
+# 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, 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)
+# =============================================================================
+# 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
+# =============================================================================
+# Register a Bot in Azure: https://dev.botframework.com/ → "Register a bot"
+# Or use Azure Portal: Azure Active Directory → App registrations → New registration
+# Then add the bot to Teams via the Bot Framework or App Studio.
+#
+# TEAMS_CLIENT_ID=                     # Azure AD App (client) ID
+# TEAMS_CLIENT_SECRET=                 # Azure AD client secret value
+# TEAMS_TENANT_ID=                     # Azure AD tenant ID (or "common" for multi-tenant)
+# TEAMS_ALLOWED_USERS=                 # Comma-separated AAD object IDs or UPNs
+# TEAMS_ALLOW_ALL_USERS=false          # Set true to skip the allowlist
+# TEAMS_HOME_CHANNEL=                  # Default channel/chat ID for cron delivery
+# TEAMS_HOME_CHANNEL_NAME=             # Display name for the home channel
+# TEAMS_PORT=3978                      # Webhook listen port (Bot Framework default)
+
+# =============================================================================
+# GOOGLE CHAT INTEGRATION
+# =============================================================================
+# Connects via Cloud Pub/Sub pull subscription (no public URL required).
+# Setup walkthrough: website/docs/user-guide/messaging/google_chat.md.
+# 1. Create a GCP project, enable the Google Chat API and Cloud Pub/Sub.
+# 2. Create a Service Account with roles/pubsub.subscriber on the
+#    subscription (NOT project-wide); download the JSON key.
+# 3. Configure your Chat app at console.cloud.google.com/apis/credentials
+#    → Google Chat API → Configuration → Cloud Pub/Sub topic.
+# 4. (Optional, for native attachment delivery) Each user runs
+#    `/setup-files` once in their own DM after Pub/Sub is wired up.
+#
+# GOOGLE_CHAT_PROJECT_ID=                       # GCP project hosting the topic (or set GOOGLE_CLOUD_PROJECT)
+# GOOGLE_CHAT_SUBSCRIPTION_NAME=                # Full path: projects/<id>/subscriptions/<name>
+# GOOGLE_CHAT_SERVICE_ACCOUNT_JSON=             # Path to SA JSON (or set GOOGLE_APPLICATION_CREDENTIALS)
+# GOOGLE_CHAT_ALLOWED_USERS=                    # Comma-separated emails allowed to talk to the bot
+# GOOGLE_CHAT_ALLOW_ALL_USERS=false             # Set true to skip the allowlist
+# GOOGLE_CHAT_HOME_CHANNEL=                     # Default space (spaces/XXXX) for cron delivery
+# GOOGLE_CHAT_HOME_CHANNEL_NAME=                # Display name for the home channel

.envrc

@@ -0,0 +1,5 @@
+watch_file pyproject.toml uv.lock hermes
+watch_file package-lock.json package.json web/package.json ui-tui/package.json website/package.json apps/shared/package.json apps/desktop/package.json ui-tui/packages/hermes-ink/package.json
+watch_file flake.nix flake.lock nix/devShell.nix nix/tui.nix nix/package.nix nix/python.nix nix/hermes-agent.nix nix/desktop.nix
+
+use flake

.gitattributes

@@ -0,0 +1,34 @@
+# Auto-generated files — collapse diffs and exclude from language stats
+web/package-lock.json linguist-generated=true
+
+# Enforce LF for scripts that run inside Linux containers.
+# Without this, Windows checkout converts to CRLF and breaks `exec` in the
+# container entrypoint with "no such file or directory".
+*.sh        text eol=lf
+Dockerfile  text eol=lf
+*.dockerfile text eol=lf
+docker/entrypoint.sh text eol=lf
+
+# Enforce LF for all source/text files. Windows editors and tools default to
+# CRLF; without normalization a Windows contributor's edit turns into a
+# whole-file phantom diff (every line "changed" by its ending), breaks
+# string-match patch tooling, and pollutes review. `text` normalizes to LF
+# at check-in; `eol=lf` also checks out as LF so the working tree matches
+# the index on every platform. PowerShell files are the deliberate
+# exception (PS 5.1 tooling expects CRLF).
+*.py    text eol=lf
+*.ts    text eol=lf
+*.tsx   text eol=lf
+*.js    text eol=lf
+*.mjs   text eol=lf
+*.cjs   text eol=lf
+*.jsx   text eol=lf
+*.json  text eol=lf
+*.yaml  text eol=lf
+*.yml   text eol=lf
+*.toml  text eol=lf
+*.md    text eol=lf
+*.css   text eol=lf
+*.html  text eol=lf
+*.svg   text eol=lf
+*.ps1   text eol=crlf

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,162 @@
+name: "🐛 Bug Report"
+description: Report a bug — something that's broken, crashes, or behaves incorrectly.
+title: "[Bug]: "
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting a bug! Please fill out the sections below so we can reproduce and fix it quickly.
+
+        **Before submitting**, please:
+        - [ ] Search [existing issues](https://github.com/NousResearch/hermes-agent/issues) to avoid duplicates
+        - [ ] Update to the latest version (`hermes update`) and confirm the bug still exists
+        - [ ] Run `hermes debug share` and paste the links below (see Debug Report section)
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Bug Description
+      description: A clear description of what's broken. Include error messages, tracebacks, or screenshots if relevant.
+      placeholder: |
+        What happened? What did you expect to happen instead?
+    validations:
+      required: true
+
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to Reproduce
+      description: Minimal steps to trigger the bug. The more specific, the faster we can fix it.
+      placeholder: |
+        1. Run `hermes chat`
+        2. Send the message "..."
+        3. Agent calls tool X
+        4. Error appears: ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: expected
+    attributes:
+      label: Expected Behavior
+      description: What should have happened instead?
+    validations:
+      required: true
+
+  - type: textarea
+    id: actual
+    attributes:
+      label: Actual Behavior
+      description: What actually happened? Include full error output if available.
+    validations:
+      required: true
+
+  - type: dropdown
+    id: component
+    attributes:
+      label: Affected Component
+      description: Which part of Hermes is affected?
+      multiple: true
+      options:
+        - CLI (interactive chat)
+        - Gateway (Telegram/Discord/Slack/WhatsApp)
+        - Setup / Installation
+        - Tools (terminal, file ops, web, code execution, etc.)
+        - Skills (skill loading, skill hub, skill guard)
+        - Agent Core (conversation loop, context compression, memory)
+        - Configuration (config.yaml, .env, hermes setup)
+        - Other
+    validations:
+      required: true
+
+  - type: dropdown
+    id: platform
+    attributes:
+      label: Messaging Platform (if gateway-related)
+      description: Which platform adapter is affected?
+      multiple: true
+      options:
+        - N/A (CLI only)
+        - Telegram
+        - Discord
+        - Slack
+        - WhatsApp
+
+  - type: textarea
+    id: debug-report
+    attributes:
+      label: Debug Report
+      description: |
+        Run `hermes debug share` from your terminal and paste the links it prints here.
+        This uploads your system info, config, and recent logs to a paste service automatically.
+
+        If you're in an interactive chat session, you can also use the `/debug` slash command — it does the same thing.
+
+        If the upload fails, run `hermes debug share --local` and paste the output directly.
+      placeholder: |
+        Report   https://paste.rs/abc123
+        agent.log   https://paste.rs/def456
+        gateway.log   https://paste.rs/ghi789
+      render: shell
+    validations:
+      required: true
+
+  - type: input
+    id: os
+    attributes:
+      label: Operating System
+      description: e.g. Ubuntu 24.04, macOS 15.2, Windows 11
+      placeholder: Ubuntu 24.04
+    validations:
+      required: true
+
+  - type: input
+    id: python-version
+    attributes:
+      label: Python Version
+      description: Output of `python --version`
+      placeholder: "3.11.9"
+
+  - type: input
+    id: hermes-version
+    attributes:
+      label: Hermes Version
+      description: Output of `hermes version`
+      placeholder: "2.1.0"
+
+  - type: textarea
+    id: logs
+    attributes:
+      label: Additional Logs / Traceback (optional)
+      description: |
+        The debug report above covers most logs. Use this field for any extra error output, 
+        tracebacks, or screenshots not captured by `hermes debug share`.
+      render: shell
+
+  - type: textarea
+    id: root-cause
+    attributes:
+      label: Root Cause Analysis (optional)
+      description: |
+        If you've dug into the code and identified the root cause, share it here.
+        Include file paths, line numbers, and code snippets if possible. This massively speeds up fixes.
+      placeholder: |
+        The bug is in `gateway/run.py` line 949. `len(history)` counts session_meta entries
+        but `agent_messages` was built from filtered history...
+
+  - type: textarea
+    id: proposed-fix
+    attributes:
+      label: Proposed Fix (optional)
+      description: If you have a fix in mind (or a PR ready), describe it here.
+      placeholder: |
+        Replace `.get()` with `.pop()` on line 289 of `gateway/platforms/base.py`
+        to actually clear the pending message after retrieval.
+
+  - type: checkboxes
+    id: pr-ready
+    attributes:
+      label: Are you willing to submit a PR for this?
+      options:
+        - label: I'd like to fix this myself and submit a PR

.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,11 @@
+blank_issues_enabled: true
+contact_links:
+  - name: 💬 Nous Research Discord
+    url: https://discord.gg/NousResearch
+    about: For quick questions, showcasing projects, sharing skills, and community chat.
+  - name: 📖 Documentation
+    url: https://github.com/NousResearch/hermes-agent/blob/main/README.md
+    about: Check the README and docs before opening an issue.
+  - name: 🤝 Contributing Guide
+    url: https://github.com/NousResearch/hermes-agent/blob/main/CONTRIBUTING.md
+    about: Read this before submitting a PR.

.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,85 @@
+name: "✨ Feature Request"
+description: Suggest a new feature or improvement.
+title: "[Feature]: "
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for the suggestion! Before submitting, please consider:
+
+        - **Is this a new skill?** Most capabilities should be [skills, not tools](https://github.com/NousResearch/hermes-agent/blob/main/CONTRIBUTING.md#should-it-be-a-skill-or-a-tool). If it's a specialized integration (crypto, NFT, niche SaaS), it belongs on the Skills Hub, not bundled.
+        - **Search [existing issues](https://github.com/NousResearch/hermes-agent/issues)** — someone may have already proposed this.
+
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem or Use Case
+      description: What problem does this solve? What are you trying to do that you can't today?
+      placeholder: |
+        I'm trying to use Hermes with [provider/platform/workflow] but currently
+        there's no way to...
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed Solution
+      description: How do you think this should work? Be as specific as you can — CLI flags, config options, UI behavior.
+      placeholder: |
+        Add a `--foo` flag to `hermes chat` that enables...
+        Or: Add a config key `bar.baz` that controls...
+    validations:
+      required: true
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives Considered
+      description: What other approaches did you consider? Why is the proposed solution better?
+
+  - type: dropdown
+    id: type
+    attributes:
+      label: Feature Type
+      options:
+        - New tool
+        - New bundled skill
+        - CLI improvement
+        - Gateway / messaging improvement
+        - Configuration option
+        - Performance / reliability
+        - Developer experience (tests, docs, CI)
+        - Other
+    validations:
+      required: true
+
+  - type: dropdown
+    id: scope
+    attributes:
+      label: Scope
+      description: How big is this change?
+      options:
+        - Small (single file, < 50 lines)
+        - Medium (few files, < 300 lines)
+        - Large (new module or significant refactor)
+
+  - type: checkboxes
+    id: pr-ready
+    attributes:
+      label: Contribution
+      options:
+        - label: I'd like to implement this myself and submit a PR
+
+  - type: textarea
+    id: debug-report
+    attributes:
+      label: Debug Report (optional)
+      description: |
+        If this feature request is related to a problem you're experiencing, run `hermes debug share` and paste the links here.
+        In an interactive chat session, you can use `/debug` instead.
+        This helps us understand your environment and any related logs.
+      placeholder: |
+        Report   https://paste.rs/abc123
+      render: shell

.github/ISSUE_TEMPLATE/setup_help.yml

@@ -0,0 +1,112 @@
+name: "🔧 Setup / Installation Help"
+description: Having trouble installing or configuring Hermes? Ask here.
+title: "[Setup]: "
+labels: ["setup"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Sorry you're having trouble! Please fill out the details below so we can help.
+
+        **Quick checks first:**
+        - Run `hermes debug share` and paste the links in the Debug Report section below
+        - If you're in a chat session, you can use `/debug` instead — it does the same thing
+        - Try `hermes update` to get the latest version
+        - Check the [README troubleshooting section](https://github.com/NousResearch/hermes-agent#troubleshooting)
+        - For general questions, consider the [Nous Research Discord](https://discord.gg/NousResearch) for faster help
+
+  - type: textarea
+    id: description
+    attributes:
+      label: What's Going Wrong?
+      description: Describe what you're trying to do and where it fails.
+      placeholder: |
+        I ran `hermes setup` and selected Nous Portal, but when I try to
+        start the gateway I get...
+    validations:
+      required: true
+
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps Taken
+      description: What did you do? Include the exact commands you ran.
+      placeholder: |
+        1. Ran the install script: `curl -fsSL ... | bash`
+        2. Ran `hermes setup` and chose "Quick setup"
+        3. Selected OpenRouter, entered API key
+        4. Ran `hermes chat` and got error...
+    validations:
+      required: true
+
+  - type: dropdown
+    id: install-method
+    attributes:
+      label: Installation Method
+      options:
+        - Install script (curl | bash)
+        - Manual clone + pip/uv install
+        - PowerShell installer (Windows)
+        - Docker
+        - Other
+    validations:
+      required: true
+
+  - type: input
+    id: os
+    attributes:
+      label: Operating System
+      placeholder: Ubuntu 24.04 / macOS 15.2 / Windows 11
+    validations:
+      required: true
+
+  - type: input
+    id: python-version
+    attributes:
+      label: Python Version
+      description: Output of `python --version` (or `python3 --version`)
+      placeholder: "3.11.9"
+
+  - type: input
+    id: hermes-version
+    attributes:
+      label: Hermes Version
+      description: Output of `hermes version` (if install got that far)
+      placeholder: "2.1.0"
+
+  - type: textarea
+    id: debug-report
+    attributes:
+      label: Debug Report
+      description: |
+        Run `hermes debug share` from your terminal and paste the links it prints here.
+        This uploads your system info, config, and recent logs to a paste service automatically.
+
+        If you're in an interactive chat session, you can also use the `/debug` slash command — it does the same thing.
+
+        If the upload fails or install didn't get that far, run `hermes debug share --local` and paste the output directly.
+        If even that doesn't work, run `hermes doctor` and paste that output instead.
+      placeholder: |
+        Report   https://paste.rs/abc123
+        agent.log   https://paste.rs/def456
+        gateway.log   https://paste.rs/ghi789
+      render: shell
+
+  - type: textarea
+    id: error-output
+    attributes:
+      label: Full Error Output
+      description: Paste the complete error message or traceback. This will be auto-formatted.
+      render: shell
+    validations:
+      required: true
+
+  - type: textarea
+    id: tried
+    attributes:
+      label: What I've Already Tried
+      description: List any fixes or workarounds you've already attempted.
+      placeholder: |
+        - Ran `hermes update`
+        - Tried reinstalling with `pip install -e ".[all]"`
+        - Checked that OPENROUTER_API_KEY is set in ~/.hermes/.env

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,75 @@
+## What does this PR do?
+
+<!-- Describe the change clearly. What problem does it solve? Why is this approach the right one? -->
+
+
+
+## Related Issue
+
+<!-- Link the issue this PR addresses. If no issue exists, consider creating one first. -->
+
+Fixes #
+
+## Type of Change
+
+<!-- Check the one that applies. -->
+
+- [ ] 🐛 Bug fix (non-breaking change that fixes an issue)
+- [ ] ✨ New feature (non-breaking change that adds functionality)
+- [ ] 🔒 Security fix
+- [ ] 📝 Documentation update
+- [ ] ✅ Tests (adding or improving test coverage)
+- [ ] ♻️ Refactor (no behavior change)
+- [ ] 🎯 New skill (bundled or hub)
+
+## Changes Made
+
+<!-- List the specific changes. Include file paths for code changes. -->
+
+- 
+
+## How to Test
+
+<!-- Steps to verify this change works. For bugs: reproduction steps + proof that the fix works. -->
+
+1. 
+2. 
+3. 
+
+## Checklist
+
+<!-- Complete these before requesting review. -->
+
+### Code
+
+- [ ] I've read the [Contributing Guide](https://github.com/NousResearch/hermes-agent/blob/main/CONTRIBUTING.md)
+- [ ] My commit messages follow [Conventional Commits](https://www.conventionalcommits.org/) (`fix(scope):`, `feat(scope):`, etc.)
+- [ ] I searched for [existing PRs](https://github.com/NousResearch/hermes-agent/pulls) to make sure this isn't a duplicate
+- [ ] My PR contains **only** changes related to this fix/feature (no unrelated commits)
+- [ ] I've run `pytest tests/ -q` and all tests pass
+- [ ] I've added tests for my changes (required for bug fixes, strongly encouraged for features)
+- [ ] I've tested on my platform: <!-- e.g. Ubuntu 24.04, macOS 15.2, Windows 11 -->
+
+### Documentation & Housekeeping
+
+<!-- Check all that apply. It's OK to check "N/A" if a category doesn't apply to your change. -->
+
+- [ ] I've updated relevant documentation (README, `docs/`, docstrings) — or N/A
+- [ ] I've updated `cli-config.yaml.example` if I added/changed config keys — or N/A
+- [ ] I've updated `CONTRIBUTING.md` or `AGENTS.md` if I changed architecture or workflows — or N/A
+- [ ] I've considered cross-platform impact (Windows, macOS) per the [compatibility guide](https://github.com/NousResearch/hermes-agent/blob/main/CONTRIBUTING.md#cross-platform-compatibility) — or N/A
+- [ ] I've updated tool descriptions/schemas if I changed tool behavior — or N/A
+
+## For New Skills
+
+<!-- Only fill this out if you're adding a skill. Delete this section otherwise. -->
+
+- [ ] This skill is **broadly useful** to most users (if bundled) — see [Contributing Guide](https://github.com/NousResearch/hermes-agent/blob/main/CONTRIBUTING.md#should-the-skill-be-bundled)
+- [ ] SKILL.md follows the [standard format](https://github.com/NousResearch/hermes-agent/blob/main/CONTRIBUTING.md#skillmd-format) (frontmatter, trigger conditions, steps, pitfalls)
+- [ ] No external dependencies that aren't already available (prefer stdlib, curl, existing Hermes tools)
+- [ ] I've tested the skill end-to-end: `hermes --toolsets skills -q "Use the X skill to do Y"`
+
+## Screenshots / Logs
+
+<!-- If applicable, add screenshots or log output showing the fix/feature in action. -->
+

.github/actionlint.yaml

@@ -0,0 +1,9 @@
+# actionlint knows only GitHub-hosted runner labels. An org admin names the
+# larger runners. Each one therefore reads as "unknown runner label" and hides
+# the real findings, unless this file declares it.
+self-hosted-runner:
+  labels:
+    - ubuntu-latest-96-core
+    - ubuntu-latest-32-core
+    - ubuntu-latest-32-arm-core
+    - windows-latest-32-core

.github/actions/detect-changes/action.yml

@@ -0,0 +1,126 @@
+name: Detect affected areas
+description: >-
+  Classify a PR's changed files into CI work lanes (python, frontend, site,
+  scan, deps, mcp_catalog) so the orchestrator can conditionally call only
+  the sub-workflows a PR can affect. Outputs are always "true" on push/dispatch
+  events and fail open (everything "true") when the diff cannot be computed.
+
+inputs:
+  github-token:
+    description: Token for the GitHub API (gh CLI). Pass steps.app-token.outputs.token from the calling workflow.
+    required: false
+    default: ${{ github.token }}
+
+outputs:
+  python:
+    description: Run Python tests / ruff / ty / windows-footguns.
+    value: ${{ steps.classify.outputs.python }}
+  python_prod:
+    description: Python changes outside tests/ — gates product jobs (Desktop E2E, Docker).
+    value: ${{ steps.classify.outputs.python_prod }}
+  frontend:
+    description: Run the TypeScript testing matrix + desktop build.
+    value: ${{ steps.classify.outputs.frontend }}
+  docker_meta:
+    description: Docker setup and meta files have changed.
+    value: ${{ steps.classify.outputs.docker_meta }}
+  docker:
+    description: Files included in the docker image have changed.
+    value: ${{ steps.classify.outputs.docker }}
+  nix:
+    description: Run `nix flake check` (flake inputs, or any product Python change).
+    value: ${{ steps.classify.outputs.nix }}
+  site:
+    description: Build the Docusaurus docs site.
+    value: ${{ steps.classify.outputs.site }}
+  scan:
+    description: Run the supply-chain critical-pattern scanner.
+    value: ${{ steps.classify.outputs.scan }}
+  deps:
+    description: Check pyproject.toml dependency upper bounds.
+    value: ${{ steps.classify.outputs.deps }}
+  uv_lock:
+    description: Run `uv lock --check` (pyproject.toml / uv.lock changes only).
+    value: ${{ steps.classify.outputs.uv_lock }}
+  npm_lock:
+    description: Post/update the semantic package-lock.json diff PR comment.
+    value: ${{ steps.classify.outputs.npm_lock }}
+  installer:
+    description: Run the PowerShell installer tests on a Windows runner.
+    value: ${{ steps.classify.outputs.installer }}
+  desktop_updater:
+    description: Run the Windows desktop-update hand-off (windows.ps1) integration tests.
+    value: ${{ steps.classify.outputs.desktop_updater }}
+  rust:
+    description: Run `cargo test` for the Tauri bootstrap installer.
+    value: ${{ steps.classify.outputs.rust }}
+  mcp_catalog:
+    description: Require MCP catalog security review label.
+    value: ${{ steps.classify.outputs.mcp_catalog }}
+  ci_review:
+    description: Require CI-sensitive file review label.
+    value: ${{ steps.classify.outputs.ci_review }}
+  ci_review_files:
+    description: JSON list of CI-sensitive files changed by the pull request.
+    value: ${{ steps.classify.outputs.ci_review_files }}
+
+runs:
+  using: composite
+  steps:
+    - name: Classify changed files
+      id: classify
+      shell: bash
+      env:
+        # Fall back to the built-in read-only token when the caller passes an
+        # empty value. Fork PRs get no repo secrets, so AUTOFIX_BOT_PAT is ""
+        # there, and an input `default:` only applies when the input is omitted,
+        # not when it's passed empty. Without this fallback the compare API
+        # fails on forks and the classifier fails open (every lane forced on).
+        GH_TOKEN: ${{ inputs.github-token || github.token }}
+        REPO: ${{ github.repository }}
+        EVENT_NAME: ${{ github.event_name }}
+        BASE_SHA: ${{ github.event.pull_request.base.sha }}
+        HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+      run: |
+        set -euo pipefail
+
+        # Only pull_request events are gated. Other events (push, release,
+        # dispatch) leave CHANGED empty, so the classifier fails open and every
+        # lane runs. Post-merge / on-demand validation is never weakened.
+        if [ "$EVENT_NAME" = "pull_request" ]; then
+          # Use the compare endpoint with the pinned base/head SHAs from the
+          # event payload instead of the "current PR files" endpoint. The SHAs
+          # are frozen at trigger time, so the file list is deterministic even
+          # if the PR receives a new push between trigger and detect.
+          #
+          # Retried: a rate-limit blip or eventual-consistency 404 on a
+          # freshly-pushed HEAD would otherwise silently fall open (all lanes
+          # run — safe, but wasteful and it masks the API failure).
+          #
+          # `.files[]?` (null-safe): with --paginate, a PR more than 100
+          # commits ahead of its merge-base paginates the compare, and pages
+          # after the first carry `files: null` — bare `.files[]` makes jq
+          # die with "cannot iterate over: null", which fails every retry
+          # and forces the fail-open path (seen on stacked PRs). The full
+          # file list (up to the API's 300-file cap) is on page one.
+          CHANGED=""
+          for i in 1 2 3; do
+            if CHANGED="$(gh api \
+              --paginate \
+              "repos/${REPO}/compare/${BASE_SHA}...${HEAD_SHA}" \
+              --jq '.files[]?.filename')"; then
+              break
+            fi
+            if [ "$i" = 3 ]; then
+              echo "::warning::compare API failed after 3 attempts — failing open (all lanes run)"
+              CHANGED=""
+              break
+            fi
+            echo "::warning::compare API failed (attempt $i); retrying in 10s"
+            sleep 10
+          done
+        fi
+
+        echo "Changed files:"
+        printf '%s\n' "${CHANGED:-(none)}"
+        printf '%s\n' "${CHANGED:-}" | python3 scripts/ci/classify_changes.py

.github/actions/get-app-token/action.yml

@@ -0,0 +1,69 @@
+name: Get GitHub App Token
+description: >-
+  Mint a short-lived (1-hour) installation access token from the repo's
+  GitHub App, replacing the long-lived AUTOFIX_BOT_PAT. App tokens get
+  5,000 req/hr per installation (vs 1,000 for the default GITHUB_TOKEN)
+  and are scoped to the App's installation permissions, not a user account.
+
+  Callers must source App credentials from a protected, main-only environment.
+  Never pass an App private key to a pull_request job, a local action, or a
+  reusable workflow resolved from an untrusted PR ref. The fallback keeps a
+  trusted caller functional when its protected environment is misconfigured.
+
+  Composite actions cannot access contexts directly, so callers pass the
+  public vars.APP_CLIENT_ID and protected secrets.APP_PRIVATE_KEY as inputs.
+  When the private key is empty, the fallback fires.
+
+inputs:
+  client-id:
+    description: GitHub App Client ID. Pass vars.APP_CLIENT_ID from the calling workflow.
+    required: false
+    default: ''
+  private-key:
+    description: GitHub App private key PEM. Pass secrets.APP_PRIVATE_KEY from the calling workflow.
+    required: false
+    default: ''
+  owner:
+    description: GitHub App installation owner. Empty scopes the token to the current repository.
+    required: false
+    default: ''
+  repositories:
+    description: Comma- or newline-separated repositories to scope within the installation owner.
+    required: false
+    default: ''
+
+outputs:
+  token:
+    description: A GitHub App installation access token (1-hour TTL), or GITHUB_TOKEN on forks.
+    value: ${{ steps.app-token.outputs.token || steps.fallback.outputs.token }}
+
+runs:
+  using: composite
+  steps:
+    - name: Check if App credentials exist
+      id: check
+      shell: bash
+      env:
+        CLIENT_ID: ${{ inputs.client-id }}
+      run: |
+        if [ -n "$CLIENT_ID" ]; then
+          echo "has_app=true" >> "$GITHUB_OUTPUT"
+        else
+          echo "has_app=false" >> "$GITHUB_OUTPUT"
+        fi
+
+    - name: Create GitHub App token
+      id: app-token
+      if: steps.check.outputs.has_app == 'true'
+      uses: actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1 # v3.2.0
+      with:
+        client-id: ${{ inputs.client-id }}
+        private-key: ${{ inputs.private-key }}
+        owner: ${{ inputs.owner }}
+        repositories: ${{ inputs.repositories }}
+
+    - name: Fall back to GITHUB_TOKEN
+      id: fallback
+      if: steps.check.outputs.has_app != 'true'
+      shell: bash
+      run: echo "token=${{ github.token }}" >> "$GITHUB_OUTPUT"

.github/actions/nix-setup/action.yml

@@ -0,0 +1,18 @@
+name: 'Setup Nix'
+description: 'Install Nix and configure Cachix binary cache'
+
+inputs:
+  cachix-auth-token:
+    description: 'Cachix auth token (enables push). Omit for read-only.'
+    required: false
+    default: ''
+
+runs:
+  using: composite
+  steps:
+    - uses: DeterminateSystems/nix-installer-action@ef8a148080ab6020fd15196c2084a2eea5ff2d25 # v22
+    - uses: cachix/cachix-action@1eb2ef646ac0255473d23a5907ad7b04ce94065c # v17
+      with:
+        name: hermes-agent
+        authToken: ${{ inputs.cachix-auth-token }}
+      continue-on-error: true

.github/actions/retry/action.yml

@@ -0,0 +1,70 @@
+name: Retry a flaky command
+description: >-
+  Run a shell command, retrying on non-zero exit. For dependency installs
+  (npm ci, uv sync) whose only failures are transient network/toolchain
+  flakes — a node-gyp header fetch, a registry blip — so CI self-heals
+  instead of needing a manual re-run. Can also capture stdout as a step
+  output for commands whose result must be consumed by later steps.
+
+inputs:
+  command:
+    description: Shell command to run (and retry).
+    required: true
+  attempts:
+    description: Max attempts before giving up.
+    default: "3"
+  delay:
+    description: Seconds to wait between attempts.
+    default: "10"
+  working-directory:
+    description: Directory to run in.
+    default: "."
+
+outputs:
+  stdout:
+    description: Captured stdout from the successful attempt (empty if not needed).
+    value: ${{ steps.retry.outputs.stdout }}
+
+runs:
+  using: composite
+  steps:
+    - id: retry
+      shell: bash
+      working-directory: ${{ inputs.working-directory }}
+      # command goes through env, never interpolated into the script body, so
+      # a command with quotes/specials can't break or inject into the runner.
+      env:
+        _CMD: ${{ inputs.command }}
+        _ATTEMPTS: ${{ inputs.attempts }}
+        _DELAY: ${{ inputs.delay }}
+      run: |
+        set -uo pipefail
+        _OUTFILE="$(mktemp)"
+        trap 'rm -f "$_OUTFILE"' EXIT
+        n=0
+        while :; do
+          n=$((n + 1))
+          echo "::group::attempt $n/$_ATTEMPTS: $_CMD"
+          # Run the command, capturing stdout to a temp file while still
+          # streaming to the log. We redirect first, then tee the file to
+          # stdout — this avoids pipefail + tee exit-code interactions that
+          # can cause the if-branch to be skipped under set -e.
+          if bash -c "$_CMD" > "$_OUTFILE"; then
+            cat "$_OUTFILE"
+            echo "::endgroup::"
+            # Preserve newlines in the output via heredoc delimiter.
+            {
+              echo 'stdout<<__RETRY_STDOUT_EOF__'
+              cat "$_OUTFILE"
+              echo '__RETRY_STDOUT_EOF__'
+            } >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          echo "::endgroup::"
+          if [ "$n" -ge "$_ATTEMPTS" ]; then
+            echo "::error::failed after $n attempts: $_CMD"
+            exit 1
+          fi
+          echo "::warning::attempt $n failed; retrying in ${_DELAY}s: $_CMD"
+          sleep "$_DELAY"
+        done

.github/dependabot.yml

@@ -0,0 +1,44 @@
+# Dependabot configuration for hermes-agent.
+#
+# Deliberately scoped to github-actions only.
+#
+# We do NOT enable Dependabot for pip / npm / any source-dependency ecosystem
+# because we pin source dependencies exactly (uv.lock, package-lock.json) as
+# part of our supply-chain posture. Automatic version-bump PRs against those
+# pins would undermine the strategy — pins are moved deliberately, after
+# review, not on a schedule.
+#
+# github-actions is the exception: action pins (we use full commit SHAs per
+# supply-chain policy) must be updated when upstream actions publish
+# patches — usually themselves security fixes. Dependabot opens a PR with
+# the new SHA and release notes; we review and merge like any other PR.
+#
+# Security-update PRs for source dependencies (opened ONLY when a CVE is
+# published affecting a currently-pinned version) are enabled separately
+# via the repo's Dependabot security updates setting
+# (Settings → Code security → Dependabot → Dependabot security updates).
+# Those are CVE-only, not schedule-driven, and do not conflict with our
+# pinning strategy — they fire when a pinned version becomes known-bad,
+# which is exactly when we want to move the pin.
+
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+      day: "monday"
+    open-pull-requests-limit: 5
+    labels:
+      - "dependencies"
+      - "github-actions"
+    commit-message:
+      prefix: "chore(actions)"
+      include: "scope"
+    groups:
+      # Batch routine action bumps into one PR per week to reduce noise.
+      # Security updates still open individually and bypass grouping.
+      actions-minor-patch:
+        update-types:
+          - "minor"
+          - "patch"

.github/scripts/run-workspace-checks.mjs

@@ -0,0 +1,141 @@
+// Run every workspace check at the same time and report all failures.
+//
+// The unit of work is a CHECK, and not a workspace. A package that declares
+// `check:*` sub-scripts gives one unit for each sub-script. A package with a
+// plain `check` gives that. This is the same selection rule the old CI matrix
+// used, so the set of commands is unchanged. Only the schedule is different.
+//
+// This is not `npm run --ws check`, because that command is serial and stops
+// at the first workspace that fails. This runs every unit and fails at the
+// end with the full list.
+//
+// The output of each unit goes to a buffer and prints on completion inside a
+// group that collapses. Children that write to one stdout together interleave
+// their lines, and a failure is then hard to read.
+//
+// This also runs on a laptop: `node .github/scripts/run-workspace-checks.mjs`.
+// `--concurrency N` sets the limit. `--list` prints the units and exits.
+
+import { execFileSync, spawn } from 'node:child_process'
+import { availableParallelism } from 'node:os'
+
+const IS_CI = Boolean(process.env.GITHUB_ACTIONS)
+const NPM = process.platform === 'win32' ? 'npm.cmd' : 'npm'
+
+/** @returns {{pkg: string, script: string}[]} */
+function discoverUnits() {
+  const raw = execFileSync(NPM, ['query', '.workspace'], {
+    encoding: 'utf-8',
+    shell: process.platform === 'win32',
+  })
+  /** @type {{location: string, scripts?: Record<string,string>}[]} */
+  const pkgs = JSON.parse(raw)
+
+  /** @type {{pkg: string, script: string}[]} */
+  const units = []
+  for (const pkg of pkgs) {
+    const scripts = pkg.scripts || {}
+    const subs = Object.keys(scripts).filter((s) => /^check:.+$/.test(s))
+    if (subs.length > 0) {
+      for (const script of subs) units.push({ pkg: pkg.location, script })
+    } else if (scripts.check) {
+      units.push({ pkg: pkg.location, script: 'check' })
+    }
+  }
+  return units
+}
+
+/** @param {{pkg: string, script: string}} unit */
+function runUnit(unit) {
+  return new Promise((resolve) => {
+    const started = Date.now()
+    const child = spawn(NPM, ['run', '--prefix', unit.pkg, unit.script], {
+      // Buffer, and do not inherit. Children that share one stdout
+      // interleave their lines, and a failure is then hard to read.
+      stdio: ['ignore', 'pipe', 'pipe'],
+      shell: process.platform === 'win32',
+    })
+    /** @type {Buffer[]} */
+    const chunks = []
+    child.stdout.on('data', (c) => chunks.push(c))
+    child.stderr.on('data', (c) => chunks.push(c))
+    child.on('error', (err) => {
+      chunks.push(Buffer.from(`failed to spawn: ${err.message}\n`))
+      resolve({ unit, code: 1, output: Buffer.concat(chunks).toString('utf-8'), ms: Date.now() - started })
+    })
+    child.on('close', (code) => {
+      resolve({
+        unit,
+        code: code ?? 1,
+        output: Buffer.concat(chunks).toString('utf-8'),
+        ms: Date.now() - started,
+      })
+    })
+  })
+}
+
+async function main() {
+  const argv = process.argv.slice(2)
+  const units = discoverUnits()
+
+  if (units.length === 0) {
+    console.error(
+      '::error::No workspace package declares a check script — refusing to report green having run nothing.',
+    )
+    process.exit(1)
+  }
+
+  if (argv.includes('--list')) {
+    for (const u of units) console.log(`${u.pkg} :: ${u.script}`)
+    return
+  }
+
+  const flagIdx = argv.indexOf('--concurrency')
+  const concurrency = Math.max(
+    1,
+    flagIdx !== -1 ? Number(argv[flagIdx + 1]) : Math.min(units.length, availableParallelism()),
+  )
+
+  console.log(`running ${units.length} checks, up to ${concurrency} at a time:`)
+  for (const u of units) console.log(`  ${u.pkg} :: ${u.script}`)
+  console.log('')
+
+  const queue = [...units]
+  /** @type {{unit: {pkg: string, script: string}, code: number, output: string, ms: number}[]} */
+  const results = []
+
+  async function worker() {
+    for (;;) {
+      const unit = queue.shift()
+      if (!unit) return
+      const res = await runUnit(unit)
+      results.push(res)
+      const label = `${res.unit.pkg} :: ${res.unit.script}`
+      const secs = (res.ms / 1000).toFixed(1)
+      const status = res.code === 0 ? 'PASS' : 'FAIL'
+      if (IS_CI) console.log(`::group::${status} ${label} (${secs}s)`)
+      else console.log(`----- ${status} ${label} (${secs}s) -----`)
+      process.stdout.write(res.output.endsWith('\n') ? res.output : res.output + '\n')
+      if (IS_CI) console.log('::endgroup::')
+    }
+  }
+
+  await Promise.all(Array.from({ length: Math.min(concurrency, units.length) }, worker))
+
+  const failed = results.filter((r) => r.code !== 0)
+  console.log('\n=== summary ===')
+  for (const r of [...results].sort((a, b) => b.ms - a.ms)) {
+    console.log(
+      `  ${r.code === 0 ? 'pass' : 'FAIL'}  ${(r.ms / 1000).toFixed(1).padStart(6)}s  ${r.unit.pkg} :: ${r.unit.script}`,
+    )
+  }
+
+  if (failed.length > 0) {
+    for (const r of failed) console.error(`::error::${r.unit.pkg} :: ${r.unit.script} failed`)
+    console.error(`::error::${failed.length} of ${results.length} checks failed`)
+    process.exit(1)
+  }
+  console.log(`\nall ${results.length} checks passed`)
+}
+
+await main()

.github/workflows/case-collision-check.yml

@@ -0,0 +1,33 @@
+name: Case Collision Check
+
+# Rejects PRs that track two files whose paths differ only by case
+# (README.md vs readme.md, src/Foo.py vs SRC/foo.py).
+#
+# Linux is case-sensitive; Windows and macOS (default) are not. A
+# case-colliding pair lives fine in a Linux checkout and silently breaks
+# every clone on a case-insensitive host — the filesystem can hold only
+# one of them, so checkout fails or whichever wins overwrites the other.
+# Git won't prevent the pair from landing (it only warns at checkout time,
+# on a case-insensitive FS, for the client doing the checkout), so the only
+# enforcement point is CI, on Linux, against the index.
+#
+# Runs unconditionally (no change-classifier gate): a collision can ship in
+# any kind of PR — docs, JS, config, not just Python — so gating on a
+# language lane would be the same "passive rule that cannot enforce a
+# policy" trap the infographic check exists to close.
+
+on:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  check-case-collisions:
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Run case-collision checker
+        run: python3 scripts/check-case-collisions.py

.github/workflows/ci-review-comment.yml

@@ -0,0 +1,80 @@
+name: CI review comment
+
+# Live-updating PR review comment.
+#
+# The poller runs for up to 40 minutes.
+# This run lives in its own workflow.
+# A run stays in progress until its last job ends, and GitHub refuses
+# ``gh run rerun`` on a run that is in progress.
+#
+# ``workflow_run`` starts this when CI starts. It always reads the workflow
+# and the scripts from the default branch, never from the PR head.
+# It makes a write token safe here.
+#
+# The poller reads job results through the API. Thus it watches the CI run
+# and the separate docker run, and it depends on neither.
+
+on:
+  workflow_run:
+    workflows: [CI]
+    # ``in_progress``, not ``requested``: a first-time contributor's run
+    # sits in ``action_required`` until a maintainer approves it, and
+    # ``requested`` fires at creation — the poller would wait out its
+    # whole timeout on a run that never starts. ``in_progress`` fires
+    # when the run actually starts, and it also fires on re-runs, which
+    # ``requested`` does not.
+    types: [in_progress]
+
+permissions:
+  contents: read
+  actions: read
+  pull-requests: write
+
+# One poller per CI run. A new push starts a new CI run, and its poller
+# cancels the poller of the run that GitHub superseded. The group keys
+# on the head repository too: fork PRs often share a branch name
+# (``main``, ``patch-1``), and two PRs must not cancel each other.
+concurrency:
+  group: ci-review-comment-${{ github.event.workflow_run.head_repository.full_name }}-${{ github.event.workflow_run.head_branch }}
+  cancel-in-progress: true
+
+jobs:
+  comment:
+    name: CI review comment (live)
+    # Fork PRs get no comment: the poller needs a write token, and the
+    # ``pull_requests`` payload is empty for a fork run.
+    if: >-
+      github.event.workflow_run.event == 'pull_request' &&
+      github.event.workflow_run.head_repository.full_name == github.repository
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    steps:
+      - name: Checkout trusted default branch
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          ref: ${{ github.event.repository.default_branch }}
+          persist-credentials: false
+
+      - name: Run live comment poller
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          # The CI run to report on — not this run. The name must not be
+          # GITHUB_RUN_ID: the runner sets the GITHUB_* defaults itself and
+          # ignores an env: override, so that name silently resolves to THIS
+          # run. The poller then watches itself, which stays in_progress for
+          # as long as the poller runs, and it waits out its whole timeout.
+          CI_RUN_ID: ${{ github.event.workflow_run.id }}
+          # Sibling runs for the same commit that the comment also covers,
+          # one workflow name per line (a name can contain a comma).
+          # The poller resolves each name to its runs through the API.
+          WATCH_WORKFLOWS: |
+            Docker Build, Test, and Publish
+          PR_NUMBER: ${{ github.event.workflow_run.pull_requests[0].number }}
+          RUN_URL: ${{ github.event.workflow_run.html_url }}
+          # Commit info for the review comment header.
+          COMMIT_SHA: ${{ github.event.workflow_run.head_sha }}
+          COMMIT_MESSAGE: ${{ github.event.workflow_run.head_commit.message }}
+        run: |
+          python3 -u scripts/ci/live_comment.py \
+            --interval 15 \
+            --timeout 3000

.github/workflows/ci.yaml

@@ -0,0 +1,385 @@
+name: CI
+
+# Orchestrator workflow. Runs ``detect-changes`` once, then conditionally
+# calls the sub-workflows that a PR can actually affect. A final
+# ``all-checks-pass`` gate job aggregates results so branch protection only
+# needs to require a single check.
+#
+# Sub-workflows are triggered via ``workflow_call`` and keep their own job
+# definitions, matrices, and concurrency settings. They no longer have
+# ``push:`` / ``pull_request:`` triggers of their own — everything flows
+# through this file.
+#
+# SECURITY: this workflow runs PR-controlled actions, workflows, and code.
+# Do not add ``secrets: inherit`` or GitHub App credentials here. Trusted
+# main-only automation uses protected environments in its own workflows.
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+  pull-requests: write # needed by lint (PR comment) + supply-chain review_status
+  actions: read # needed by osv-scanner (SARIF upload)
+  security-events: write # needed by osv-scanner (SARIF upload)
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  # ─────────────────────────────────────────────────────────────────────
+  # detect: run the classifier once. Every downstream job reads its outputs
+  # to decide whether to run. On push/dispatch the classifier fails open
+  # (all lanes true) so post-merge validation is never weakened.
+  # ─────────────────────────────────────────────────────────────────────
+  detect:
+    name: Detect affected areas
+    runs-on: ubuntu-latest
+    timeout-minutes: 1
+    outputs:
+      python: ${{ steps.classify.outputs.python }}
+      python_prod: ${{ steps.classify.outputs.python_prod }}
+      frontend: ${{ steps.classify.outputs.frontend }}
+      site: ${{ steps.classify.outputs.site }}
+      scan: ${{ steps.classify.outputs.scan }}
+      deps: ${{ steps.classify.outputs.deps }}
+      uv_lock: ${{ steps.classify.outputs.uv_lock }}
+      npm_lock: ${{ steps.classify.outputs.npm_lock }}
+      installer: ${{ steps.classify.outputs.installer }}
+      desktop_updater: ${{ steps.classify.outputs.desktop_updater }}
+      rust: ${{ steps.classify.outputs.rust }}
+      docker_meta: ${{ steps.classify.outputs.docker_meta }}
+      mcp_catalog: ${{ steps.classify.outputs.mcp_catalog }}
+      ci_review: ${{ steps.classify.outputs.ci_review }}
+      ci_review_files: ${{ steps.classify.outputs.ci_review_files }}
+      event_name: ${{ github.event_name }}
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - name: Detect affected areas
+        id: classify
+        uses: ./.github/actions/detect-changes
+        with:
+          sparse-checkout: scripts/ci/classify_changes.py
+          sparse-checkout-cone-mode: false
+          github-token: ${{ github.token }}
+
+  # ─────────────────────────────────────────────────────────────────────
+  # Lane-gated sub-workflows. Each runs in parallel after detect finishes.
+  # Skipped workflows (if condition is false) don't spin up runners.
+  # ─────────────────────────────────────────────────────────────────────
+  tests:
+    name: Python tests
+    needs: detect
+    if: needs.detect.outputs.python == 'true'
+    uses: ./.github/workflows/tests.yml
+
+  # macOS + Windows lanes. The main `tests` lane above is Linux-only, and
+  # the OS-marked tests it collects are skipped there by design (see the
+  # `_OS_MARKS` comment in tests/conftest.py) — this is where they run.
+  # Same `python` lane gate: if no Python changed, neither runs.
+  tests-os:
+    name: OS-specific tests
+    needs: detect
+    if: needs.detect.outputs.python == 'true'
+    uses: ./.github/workflows/tests-os.yml
+    with:
+      # The Windows lane spawns the real desktop-update hand-off script
+      # (tests/test_desktop_update_windows_*.py) only when that surface
+      # changed; unit-level windows_only tests always run.
+      desktop_updater: ${{ needs.detect.outputs.desktop_updater == 'true' }}
+
+  lint:
+    name: Python lints
+    needs: detect
+    if: needs.detect.outputs.python == 'true'
+    uses: ./.github/workflows/lint.yml
+    with:
+      event_name: ${{ needs.detect.outputs.event_name }}
+
+  js-tests:
+    name: JS & TS checks
+    needs: detect
+    if: needs.detect.outputs.frontend == 'true'
+    uses: ./.github/workflows/js-tests.yml
+
+  installer-tests:
+    name: Installer tests
+    needs: detect
+    # Windows-only, and only for PRs that touch install.ps1 or its tests.
+    if: needs.detect.outputs.installer == 'true'
+    uses: ./.github/workflows/installer-tests.yml
+
+  rust-tests:
+    name: Rust tests
+    needs: detect
+    # Only for PRs that touch a Rust crate. `.rs` is under apps/, so these
+    # changes used to run the TypeScript matrix and nothing that compiles them.
+    if: needs.detect.outputs.rust == 'true'
+    uses: ./.github/workflows/rust-tests.yml
+
+  e2e-desktop:
+    name: Desktop E2E
+    needs: detect
+    # python_prod (not python): the Playwright suite exercises the built app
+    # + `hermes serve` backend, which never import anything under tests/.
+    # Tests-only PRs (~17% of commits) skip this 5-minute job — the longest
+    # single job in the workflow — while still running the full pytest lanes.
+    #
+    # Re-disabled (Sep 2026): the Sep 1 re-enable is still incredibly flaky.
+    # Keep this a bare `if: false`. The earlier
+    # `${{ false && (... || ...) }}` form on this reusable-workflow job made
+    # GitHub's workflow parser fail at startup ("An unexpected error has
+    # occurred") — every ci.yaml run repo-wide dispatched 0 jobs from
+    # 24f5a60ed1 until this line changed. To re-enable, restore:
+    #   if: ${{ needs.detect.outputs.python_prod == 'true' || needs.detect.outputs.frontend == 'true' }}
+    if: false
+    uses: ./.github/workflows/e2e-desktop.yml
+
+  docs-site:
+    name: Docs Site
+    needs: detect
+    if: needs.detect.outputs.site == 'true'
+    uses: ./.github/workflows/docs-site-checks.yml
+
+  history-check:
+    name: Deny unrelated histories
+    needs: detect
+    if: needs.detect.outputs.event_name == 'pull_request'
+    uses: ./.github/workflows/history-check.yml
+
+  contributor-check:
+    name: Check contributors
+    needs: detect
+    if: needs.detect.outputs.python == 'true'
+    uses: ./.github/workflows/contributor-check.yml
+
+  uv-lockfile:
+    name: Check uv.lock
+    needs: detect
+    # Gated: `uv lock --check` re-resolves the whole dependency graph against
+    # PyPI, so on every PR it spent a network round-trip — and, on a registry
+    # blip, a blocking red X — for diffs that cannot desync the lockfile
+    # (docs, frontend, prose). Only pyproject.toml / uv.lock can. A
+    # `.github/` change still forces it on via the classifier's fail-open.
+    if: needs.detect.outputs.uv_lock == 'true'
+    uses: ./.github/workflows/uv-lockfile-check.yml
+
+  infographic-check:
+    name: Check no committed infographics
+    needs: detect
+    uses: ./.github/workflows/infographic-check.yml
+
+  profile-artifact-check:
+    name: Profile artifact check
+    needs: detect
+    uses: ./.github/workflows/profile-artifact-check.yml
+
+  case-collision-check:
+    name: Check no case-colliding filenames
+    needs: detect
+    uses: ./.github/workflows/case-collision-check.yml
+
+  lockfile-diff:
+    name: package-lock.json diff
+    needs: detect
+    if: needs.detect.outputs.event_name == 'pull_request' && needs.detect.outputs.npm_lock == 'true'
+    uses: ./.github/workflows/lockfile-diff.yml
+
+  docker-lint:
+    name: Lint Docker scripts
+    needs: detect
+    if: needs.detect.outputs.docker_meta == 'true'
+    uses: ./.github/workflows/docker-lint.yml
+
+  supply-chain:
+    name: Supply-chain scan
+    needs: detect
+    if: needs.detect.outputs.event_name == 'pull_request' && (needs.detect.outputs.scan == 'true' || needs.detect.outputs.deps == 'true')
+    uses: ./.github/workflows/supply-chain-audit.yml
+    with:
+      event_name: ${{ needs.detect.outputs.event_name }}
+      scan: ${{ needs.detect.outputs.scan == 'true' }}
+      deps: ${{ needs.detect.outputs.deps == 'true' }}
+
+  review-labels:
+    name: Review label gate
+    needs: [detect, supply-chain]
+    if: always() && needs.detect.outputs.event_name == 'pull_request' && (needs.detect.outputs.ci_review == 'true' || needs.detect.outputs.mcp_catalog == 'true' || needs.supply-chain.outputs.critical_findings == 'true')
+    uses: ./.github/workflows/review-labels.yml
+    with:
+      ci_review: ${{ needs.detect.outputs.ci_review == 'true' }}
+      ci_review_files: ${{ needs.detect.outputs.ci_review_files }}
+      mcp_catalog: ${{ needs.detect.outputs.mcp_catalog == 'true' }}
+      supply_chain: ${{ needs.supply-chain.outputs.critical_findings == 'true' }}
+
+  osv-scanner:
+    name: OSV scan
+    uses: ./.github/workflows/osv-scanner.yml
+
+  # ─────────────────────────────────────────────────────────────────────
+  # Gate: runs after everything. ``if: always()`` ensures it reports a
+  # status even when some deps were skipped. Only actual ``failure``
+  # results cause it to fail; ``skipped`` is treated as success.
+  #
+  # Branch protection should require ONLY this check.
+  #
+  # Outputs ``needs-json`` — a compact ``{job_name: result}`` dict — so
+  # the live comment poller can list failed jobs in the PR comment.
+  # ─────────────────────────────────────────────────────────────────────
+  all-checks-pass:
+    name: All required checks pass
+    needs:
+      - detect
+      - tests
+      - tests-os
+      - lint
+      - js-tests
+      - installer-tests
+      - rust-tests
+      - e2e-desktop
+      - docs-site
+      - history-check
+      - contributor-check
+      - uv-lockfile
+      - case-collision-check
+      - lockfile-diff
+      - docker-lint
+      - profile-artifact-check
+      - supply-chain
+      - review-labels
+      - osv-scanner
+      # The image build runs in its own workflow (docker.yml) and reports
+      # its own check. It was never required here, because it is too slow
+      # to block a merge. A separate run also stops it from holding this
+      # run open. That is what blocked ``gh run rerun``.
+    if: always()
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    outputs:
+      needs-json: ${{ steps.evaluate.outputs.needs-json }}
+    steps:
+      - name: Evaluate job results
+        id: evaluate
+        env:
+          NEEDS: ${{ toJSON(needs) }}
+        run: |
+          echo "$NEEDS" | python3 -c "
+          import json, sys
+          needs = json.load(sys.stdin)
+          # Emit compact {job_name: result} for the comment assembler.
+          compact = {name: info['result'] for name, info in needs.items()}
+          print(f'needs-json={json.dumps(compact)}')
+          with open('$GITHUB_OUTPUT', 'a') as f:
+              f.write(f'needs-json={json.dumps(compact)}\n')
+          failed = [name for name, info in needs.items() if info['result'] == 'failure']
+          for name, info in sorted(needs.items()):
+              result = info['result']
+              icon = '✅' if result in ('success', 'skipped') else '❌'
+              print(f'{icon} {name}: {result}')
+          if failed:
+              print(f'::error::{len(failed)} job(s) failed: {\", \".join(failed)}')
+              sys.exit(1)
+          print('All checks passed (or were skipped)')
+          "
+
+  # ─────────────────────────────────────────────────────────────────────
+  # CI timing report: collect per-job/step durations from the GitHub API,
+  # cache them on main (as a baseline), and on PRs generate an HTML diff
+  # report with a gantt chart + per-step breakdown. The report is uploaded
+  # as an artifact and a markdown summary is written to $GITHUB_STEP_SUMMARY.
+  #
+  # The live comment poller dynamically fetches all review-status-* artifacts
+  # across the orchestrator and sub-workflow runs every cycle, so its link
+  # points straight at that report.
+  # ─────────────────────────────────────────────────────────────────────
+  ci-timings:
+    name: CI timing report
+    needs: [all-checks-pass]
+    if: always()
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Restore baseline cache (PR only)
+        if: github.event_name == 'pull_request'
+        uses: actions/cache/restore@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+        with:
+          path: ci-timings-baseline.json
+          # Prefix-match: exact key will never hit (run_id differs), so
+          # restore-keys finds the most recent baseline from main.
+          key: ci-timings-baseline-never-exact
+          restore-keys: |
+            ci-timings-baseline-
+
+      - name: Collect timings and generate report
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: |
+          python3 scripts/ci/timings_report.py \
+            --baseline ci-timings-baseline.json \
+            --output ci-timings-report.html \
+            --json-out ci-timings.json \
+            --summary-out ci-timings-summary.md
+
+      - name: Upload HTML report
+        # Advisory report — artifact-service blips must not fail the job.
+        continue-on-error: true
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        id: ci-timings-html
+        with:
+          name: ci-timings-report
+          path: ci-timings-report.html
+          retention-days: 14
+
+      - name: Build linked review status
+        if: hashFiles('ci-timings.json') != ''
+        env:
+          CI_TIMINGS_REPORT_URL: ${{ steps.ci-timings-html.outputs.artifact-url }}
+        run: |
+          python3 scripts/ci/timings_report.py \
+            --from-json ci-timings.json \
+            --baseline ci-timings-baseline.json \
+            --review-status-out review-status.json \
+            --review-status-only
+
+      - name: Upload review status
+        if: hashFiles('review-status.json') != ''
+        continue-on-error: true
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: review-status-ci-timings
+          path: review-status.json
+          retention-days: 14
+
+      - name: Output summary
+        env:
+          REPORT_URL: ${{ steps.ci-timings-html.outputs.artifact-url}}
+        run: |
+          {
+            echo "# CI Timing report"
+            echo "[View the full interactive report]($REPORT_URL)"
+          } >> "$GITHUB_STEP_SUMMARY"
+          cat ci-timings-summary.md >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Save baseline cache (main only)
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+        run: |
+          # Degraded runs (API rate-limited) produce no ci-timings.json —
+          # skip rather than fail, and never cache an empty baseline.
+          if [ -f ci-timings.json ]; then
+            cp ci-timings.json ci-timings-baseline.json
+          else
+            echo "No timings JSON this run — skipping baseline update"
+          fi
+
+      - name: Upload baseline to cache (main only)
+        if: github.event_name == 'push' && github.ref == 'refs/heads/main' && hashFiles('ci-timings-baseline.json') != ''
+        uses: actions/cache/save@27d5ce7f107fe9357f9df03efb73ab90386fccae # v5.0.5
+        with:
+          path: ci-timings-baseline.json
+          key: ci-timings-baseline-${{ github.run_id }}

.github/workflows/contributor-check.yml

@@ -0,0 +1,108 @@
+name: Contributor Attribution Check
+
+on:
+  workflow_call:
+    outputs:
+      review_status:
+        description: "JSON array of review status objects"
+        value: ${{ jobs.check-attribution.outputs.review_status }}
+
+permissions:
+  contents: read
+
+jobs:
+  check-attribution:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    outputs:
+      review_status: ${{ steps.check-emails.outputs.review_status }}
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+        with:
+          fetch-depth: 0  # Full history needed for git log
+
+      - name: Check for unmapped contributor emails
+        id: check-emails
+        run: |
+          # Get the merge base between this PR and main
+          MERGE_BASE=$(git merge-base origin/main HEAD)
+
+          # Find any new author emails in this PR's commits
+          NEW_EMAILS=$(git log ${MERGE_BASE}..HEAD --format='%ae' --no-merges | sort -u)
+
+          if [ -z "$NEW_EMAILS" ]; then
+            echo "No new commits to check."
+            echo "review_status=[]" >> "$GITHUB_OUTPUT"
+            echo "review_status=[]" > review-status.json
+            exit 0
+          fi
+
+          # An email is mapped if it has a file in contributors/emails/
+          # (one file per email — conflict-free) or an entry in the frozen
+          # legacy AUTHOR_MAP in scripts/release.py.
+          MISSING=""
+          while IFS= read -r email; do
+            # Skip teknium and bot emails
+            case "$email" in
+              *teknium*|*noreply@github.com*|*dependabot*|*github-actions*|*anthropic.com*|*cursor.com*)
+                continue ;;
+            esac
+
+            if echo "$email" | grep -qP '\+.*@users\.noreply\.github\.com'; then
+              continue  # GitHub id+login noreply emails auto-resolve
+            fi
+
+            if [ -f "contributors/emails/${email}" ]; then
+              continue  # mapped via the contributors directory
+            fi
+
+            if ! grep -qF "\"${email}\"" scripts/release.py 2>/dev/null; then
+              AUTHOR=$(git log --author="$email" --format='%an' -1)
+              MISSING="${MISSING}\n  ${email} (${AUTHOR})"
+            fi
+          done <<< "$NEW_EMAILS"
+
+          if [ -n "$MISSING" ]; then
+            echo ""
+            echo "⚠️  New contributor email(s) without a mapping:"
+            echo -e "$MISSING"
+            echo ""
+            echo "Add a mapping file (do NOT edit AUTHOR_MAP in release.py):"
+            echo "  python3 scripts/audit_pr_attribution.py --fix   # auto-resolve + create files"
+            echo "or manually:"
+            echo -e "$MISSING" | while read -r line; do
+              email=$(echo "$line" | sed 's/^ *//' | cut -d' ' -f1)
+              [ -z "$email" ] && continue
+              echo "    python3 scripts/add_contributor.py ${email} <github-username>"
+            done
+            echo ""
+            echo "To find the GitHub username for an email:"
+            echo "  gh api 'search/users?q=EMAIL+in:email' --jq '.items[0].login'"
+
+            # Emit review_status for unmapped emails
+            DETAIL=$(echo -e "$MISSING" | sed '/^$/d; s/^  //')
+            HOW_TO_FIX=$'Run from the PR branch:\n```\npython3 scripts/audit_pr_attribution.py --fix\ngit add contributors && git commit -m "chore: map contributor emails" && git push\n```\nOr map one email manually (do NOT edit AUTHOR_MAP in release.py):\n```\npython3 scripts/add_contributor.py <email> <github-username>\n```\nTo find the GitHub username for an email:\n```\ngh api \'search/users?q=EMAIL+in:email\' --jq \'.items[0].login\'\n```\n'
+            REVIEW_STATUS=$(jq -nc \
+              --arg detail "$DETAIL" \
+              --arg how_to_fix "$HOW_TO_FIX" \
+              '[{"source":"contributor attribution","results":[{"kind":"action_required","title":"Unmapped contributor email(s)","summary":"New contributor email(s) are not in AUTHOR_MAP.","detail":$detail,"how_to_fix":$how_to_fix}]}]')
+            echo "review_status=$REVIEW_STATUS" >> "$GITHUB_OUTPUT"
+            echo "review_status=$REVIEW_STATUS" > review-status.json
+
+            exit 1
+          else
+            echo "✅ All contributor emails are mapped."
+            echo "review_status=[]" >> "$GITHUB_OUTPUT"
+            echo "review_status=[]" > review-status.json
+          fi
+
+      - name: Upload review status artifact
+        if: always() && steps.check-emails.outcome != 'skipped'
+        continue-on-error: true
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: review-status-contributor-check
+          path: review-status.json
+          retention-days: 1
+          overwrite: true
+          if-no-files-found: ignore

.github/workflows/deploy-site.yml

@@ -0,0 +1,254 @@
+name: Deploy Site
+
+on:
+  release:
+    types: [published]
+  push:
+    branches: [main]
+    paths:
+      - 'website/**'
+      - 'skills/**'
+      - 'optional-skills/**'
+      - '.github/workflows/deploy-site.yml'
+  workflow_dispatch:
+    inputs:
+      skills_index_run_id:
+        description: 'Optional Build Skills Index run ID whose skills-index artifact should be deployed'
+        required: false
+        type: string
+      rebuild_skills_index:
+        description: 'Force a fresh multi-source crawl instead of reusing the latest healthy index'
+        required: false
+        default: false
+        type: boolean
+
+permissions:
+  contents: read
+  actions: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  deploy-vercel:
+    # Triggered automatically on release publish (production cuts) and
+    # manually via `gh workflow run deploy-site.yml` when an out-of-band
+    # main commit needs to ship live before the next release tag — e.g.
+    # a skills-index PR that doesn't touch website/** paths and so
+    # doesn't auto-deploy via the deploy-docs path.
+    if: github.event_name == 'release' || github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - name: Trigger Vercel Deploy
+        run: curl -fsS --retry 3 --retry-delay 10 -X POST "${{ secrets.VERCEL_DEPLOY_HOOK }}"
+
+  deploy-docs:
+    if: github.repository == 'NousResearch/hermes-agent'
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    environment:
+      name: github-pages
+      url: ${{ steps.deploy.outputs.page_url }}
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+
+      - name: Get GitHub App token
+        id: app-token
+        uses: ./.github/actions/get-app-token
+        with:
+          client-id: ${{ vars.APP_CLIENT_ID }}
+          private-key: ${{ secrets.APP_PRIVATE_KEY }}
+
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020  # v4
+        with:
+          node-version: 26
+          cache: npm
+          cache-dependency-path: website/package-lock.json
+
+      - name: grab npm 12
+        run: |
+          npm i -g npm@12
+
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
+        with:
+          python-version: '3.11'
+
+      - name: Install PyYAML for skill extraction
+        uses: ./.github/actions/retry
+        with:
+          command: pip install pyyaml==6.0.2 httpx==0.28.1
+
+      - name: Prepare skills index (unified multi-source catalog)
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+          GITHUB_TOKEN: ${{ steps.app-token.outputs.token }}
+          SKILLS_INDEX_RUN_ID: ${{ github.event.inputs.skills_index_run_id || '' }}
+          REBUILD_SKILLS_INDEX: ${{ github.event.inputs.rebuild_skills_index || 'false' }}
+        run: |
+          # The unified external catalog is expensive to crawl and can burn
+          # through the repository installation's GitHub API quota when several
+          # docs deploys land close together.  Normal docs deploys therefore
+          # reuse the latest healthy catalog: first the artifact from a
+          # scheduled skills-index run, then the currently live index.  Only a
+          # manual force rebuild does a fresh crawl here.
+          #
+          # If we do crawl, the build remains fatal. build_skills_index.py runs
+          # the health check BEFORE writing and exits non-zero on source
+          # collapse, keeping the last good Pages deployment live instead of
+          # publishing a degenerate catalog.
+          set -euo pipefail
+          INDEX_PATH="website/static/api/skills-index.json"
+          mkdir -p "$(dirname "$INDEX_PATH")"
+
+          validate_index() {
+            python3 - "$INDEX_PATH" <<'PY'
+          import json
+          import sys
+          from pathlib import Path
+
+          path = Path(sys.argv[1])
+          try:
+              data = json.loads(path.read_text(encoding="utf-8"))
+          except Exception as exc:
+              print(f"invalid skills index JSON: {exc}", file=sys.stderr)
+              sys.exit(1)
+          skills = data.get("skills")
+          if not isinstance(skills, list) or len(skills) < 1500:
+              count = len(skills) if isinstance(skills, list) else "missing"
+              print(f"skills index too small: {count}", file=sys.stderr)
+              sys.exit(1)
+          print(f"skills index ready: {len(skills)} skills")
+          PY
+          }
+
+          if [ "$REBUILD_SKILLS_INDEX" = "true" ]; then
+            python3 scripts/build_skills_index.py
+            validate_index
+            exit 0
+          fi
+
+          if [ -n "$SKILLS_INDEX_RUN_ID" ]; then
+            tmpdir="$(mktemp -d)"
+            echo "Downloading skills-index artifact from run $SKILLS_INDEX_RUN_ID"
+            if gh run download "$SKILLS_INDEX_RUN_ID" --name skills-index --dir "$tmpdir"; then
+              candidate="$(find "$tmpdir" -name skills-index.json -type f | head -n 1 || true)"
+              if [ -n "$candidate" ]; then
+                cp "$candidate" "$INDEX_PATH"
+                if validate_index; then
+                  exit 0
+                fi
+              fi
+            fi
+            echo "::warning::Could not use skills-index artifact from run $SKILLS_INDEX_RUN_ID; trying live index"
+          fi
+
+          echo "Downloading currently live skills index"
+          if curl -fsSL --retry 3 --retry-delay 5 \
+            "https://hermes-agent.nousresearch.com/docs/api/skills-index.json" \
+            -o "$INDEX_PATH" && validate_index; then
+            exit 0
+          fi
+
+          echo "::warning::Live skills index unavailable or unhealthy; falling back to a fresh crawl"
+          rm -f "$INDEX_PATH"
+          python3 scripts/build_skills_index.py
+          validate_index
+
+      - name: Extract skill metadata for dashboard
+        run: python3 website/scripts/extract-skills.py
+
+      - name: Regenerate per-skill docs pages + catalogs
+        run: python3 website/scripts/generate-skill-docs.py
+
+      - name: Install dependencies
+        uses: ./.github/actions/retry
+        with:
+          command: npm ci
+          working-directory: website
+
+      - name: Build Docusaurus
+        run: npm run build
+        working-directory: website
+
+      - name: Stage deployment
+        run: |
+          mkdir -p _site/docs
+          cp -r website/build/* _site/docs/
+          # llms.txt / llms-full.txt are also published at the site root
+          # (https://hermes-agent.nousresearch.com/llms.txt) because some
+          # agents and IDE plugins probe the classic root-level path rather
+          # than /docs/llms.txt. Same file, two URLs, one source of truth.
+          if [ -f website/build/llms.txt ]; then
+            cp website/build/llms.txt _site/llms.txt
+          fi
+          if [ -f website/build/llms-full.txt ]; then
+            cp website/build/llms-full.txt _site/llms-full.txt
+          fi
+
+      # Pages serves exactly the newest artifact, so each deploy used to delete
+      # the previous build's content-hashed JS/CSS while edge caches (Vercel →
+      # Fastly, max-age=300 + stale-while-revalidate=3600) kept serving HTML
+      # that referenced it — every asset request 404'd for up to ~65 minutes
+      # after each deploy. With push-triggered deploys landing every ~15-30
+      # minutes, the docs were in that broken window most of the day (search,
+      # being pure client JS, died first). Fix: keep a rolling pool of prior
+      # builds' hashed assets and union-merge it into every artifact so stale
+      # HTML keeps resolving. Hashed filenames are content-addressed, so a
+      # collision is by definition the identical file — the merge never
+      # overwrites current-build output (cp --update=none).
+      - name: Restore asset retention pool
+        uses: actions/cache/restore@27d5ce7f107fe9357f9df03efb73ab90386fccae  # v5.0.5
+        with:
+          path: _asset_retention
+          key: docs-asset-retention-${{ github.run_id }}
+          restore-keys: |
+            docs-asset-retention-
+
+      - name: Merge retained assets from previous deploys
+        run: |
+          set -euo pipefail
+          ASSET_DIRS="assets zh-Hans/assets"
+          mkdir -p _asset_retention
+          # 1) Add this build's hashed assets to the pool (fresh mtimes, so
+          #    assets still shipped by current builds never age out).
+          for d in $ASSET_DIRS; do
+            if [ -d "_site/docs/$d" ]; then
+              mkdir -p "_asset_retention/$d"
+              cp -a "_site/docs/$d/." "_asset_retention/$d/"
+            fi
+          done
+          # 2) Drop pool entries no build has produced for 14 days — far
+          #    beyond any edge-cache or open-tab horizon.
+          find _asset_retention -type f -mtime +14 -delete
+          find _asset_retention -type d -empty -delete
+          # 3) Union-merge the pool into the artifact; --update=none keeps the
+          #    current build authoritative for any path it produced.
+          for d in $ASSET_DIRS; do
+            if [ -d "_asset_retention/$d" ]; then
+              mkdir -p "_site/docs/$d"
+              cp -R --update=none "_asset_retention/$d/." "_site/docs/$d/"
+            fi
+          done
+          echo "retention pool:" && du -sh _asset_retention
+          echo "deployed assets:" && du -sh _site/docs/assets
+
+      - name: Save asset retention pool
+        # Always save under a fresh key (caches are immutable); restore-keys
+        # prefix matching picks the newest on the next run.
+        uses: actions/cache/save@27d5ce7f107fe9357f9df03efb73ab90386fccae  # v5.0.5
+        with:
+          path: _asset_retention
+          key: docs-asset-retention-${{ github.run_id }}
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@56afc609e74202658d3ffba0e8f6dda462b719fa  # v3
+        with:
+          path: _site
+
+      - name: Deploy to GitHub Pages
+        id: deploy
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e  # v4

.github/workflows/docker-lint.yml

@@ -0,0 +1,55 @@
+name: Docker / shell lint
+
+# Lints the container build inputs: Dockerfile (via hadolint) and any shell
+# scripts under docker/ (via shellcheck). These catch the class of regression
+# the behavioral docker smoke test can't — unquoted variable
+# expansions, silently-failing RUN commands, etc.
+#
+# Rules and ignores are documented in .hadolint.yaml at the repo root.
+# shellcheck severity is pinned to `error` so SC1091-style "can't follow
+# sourced script" info-level warnings don't fail the job — the .venv
+# activate script doesn't exist at lint time.
+
+on:
+  workflow_call:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: docker-lint-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  hadolint:
+    name: Lint Dockerfile (hadolint)
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: hadolint
+        uses: hadolint/hadolint-action@54c9adbab1582c2ef04b2016b760714a4bfde3cf # v3.1.0
+        with:
+          dockerfile: Dockerfile
+          config: .hadolint.yaml
+          failure-threshold: warning
+
+  shellcheck:
+    name: Lint docker/ shell scripts (shellcheck)
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: shellcheck
+        uses: ludeeus/action-shellcheck@00cae500b08a931fb5698e11e79bfbd38e612a38 # v2.0.0
+        env:
+          # Severity = error: SC1091 (can't follow sourced script) is info-
+          # level and would otherwise fail when the venv activate script
+          # doesn't exist at lint time.
+          SHELLCHECK_OPTS: --severity=error
+        with:
+          scandir: ./docker

.github/workflows/docker.yml

@@ -0,0 +1,341 @@
+name: Docker Build, Test, and Publish
+
+on:
+  # This workflow owns its own triggers. ci.yml does not call it.
+  # A reusable-workflow call eeps the caller run in progress for that full time.
+  # GitHub refuses  ``gh run rerun`` on a run that is still in progress.
+  # Thus one slow advisory job blocked every rerun of the fast required jobs. A separate
+  # run reruns and cancels independently.
+  #
+  # Trusted main pushes resolve the environment-scoped Docker Hub secrets in
+  # this same workflow, never across a workflow boundary.
+  pull_request:
+  push:
+    branches: [main]
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+# Concurrency: push/release runs are NEVER cancelled so every merge gets
+# its own image.  PR runs reuse a PR-scoped group with
+# cancel-in-progress: true so rapid pushes to the same PR collapse to
+# the latest commit.
+concurrency:
+  group: docker-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+env:
+  IMAGE_NAME: nousresearch/hermes-agent
+
+jobs:
+  # Classify the PR's changed files. ci.yml used to gate the docker call on
+  # its own ``detect`` outputs; now that this workflow triggers itself, it
+  # runs the same composite action. On push and release the classifier fails
+  # open (every lane true), so post-merge validation is never weakened.
+  detect:
+    name: Detect affected areas
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    outputs:
+      build: ${{ steps.gate.outputs.build }}
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Detect affected areas
+        id: classify
+        uses: ./.github/actions/detect-changes
+        with:
+          github-token: ${{ github.token }}
+
+      - name: Decide whether to build
+        id: gate
+        env:
+          # The docker lane derives from python_prod (not python: the image
+          # copies installed code, never tests/, so tests-only PRs skip the
+          # build), frontend and docker_meta. classify_changes.py owns the
+          # formula so this gate and the nix lane cannot drift apart.
+          DOCKER: ${{ steps.classify.outputs.docker }}
+        run: |
+          set -euo pipefail
+          if [ "$DOCKER" = "true" ]; then
+            echo "build=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "build=false" >> "$GITHUB_OUTPUT"
+          fi
+
+  # Build and test the image for each architecture. This job runs PR code,
+  # so it must remain secret-free. Publishing happens in the separate,
+  # protected publish job after these tests pass.
+  build:
+    needs: [detect]
+    if: github.repository == 'NousResearch/hermes-agent' && needs.detect.outputs.build == 'true'
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - arch: amd64
+            runner: ubuntu-latest-32-core
+            platform: linux/amd64
+            cache-from: type=gha,scope=docker-amd64
+            cache-to: type=gha,mode=max,scope=docker-amd64
+          # arm64 builds on the native arm64 larger runner. A build of
+          # linux/arm64 on an x64 host uses emulation.
+          - arch: arm64
+            runner: ubuntu-latest-32-arm-core
+            platform: linux/arm64
+            cache-from: type=gha,scope=docker-arm64
+            cache-to: type=gha,mode=max,scope=docker-arm64
+
+    runs-on: ${{ matrix.runner }}
+    timeout-minutes: 45
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Reject profile exports in the build context
+        run: python3 scripts/ci/check_profile_archive_boundary.py
+
+      # Retry once on transient Docker Hub / buildkit pull failures
+      # (connection reset, auth token timeout, rate limiting). The action
+      # generates a unique builder name per invocation so the retry doesn't
+      # collide with the failed first attempt. A genuine persistent failure
+      # still fails the job — only the first attempt has continue-on-error.
+      # Refs: docker/setup-buildx-action#510
+      - name: Set up Docker Buildx
+        id: buildx
+        continue-on-error: true
+        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3
+
+      - name: Set up Docker Buildx (retry)
+        if: steps.buildx.outcome == 'failure'
+        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3
+
+      # Build once, load into the local daemon for testing.  Cached
+      # per-arch; the push step below reuses every layer from this build.
+      - name: Build image (${{ matrix.arch }})
+        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
+        with:
+          context: .
+          file: Dockerfile
+          load: true
+          platforms: ${{ matrix.platform }}
+          tags: ${{ env.IMAGE_NAME }}:test
+          build-args: |
+            HERMES_GIT_SHA=${{ github.sha }}
+          cache-from: ${{ matrix.cache-from }}
+          cache-to: ${{ (github.event_name != 'pull_request') && matrix.cache-to || '' }}
+
+
+      # Run the docker-integration test suite against the freshly-built
+      # image already loaded into the local daemon (`:test`).
+      #
+      # Piggybacking here avoids a second image build: the build step
+      # already loaded the image into the daemon under
+      # `${IMAGE_NAME}:test`, so we just point ``HERMES_TEST_IMAGE`` at
+      # that.  The fixture's ``HERMES_TEST_IMAGE`` branch (see
+      # tests/docker/conftest.py:62-63) short-circuits the rebuild.
+      #
+      # Why this job and not a standalone one: the image is 5GB+; passing
+      # it between jobs via ``docker save``/``upload-artifact`` is slower
+      # than the build itself.  Reusing the existing daemon state is the
+      # cheapest path to coverage on every PR that touches docker code.
+      # ---------------------------------------------------------------------
+      - name: Install uv (for docker tests)
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # 8.2.0
+        with:
+          # Pinned: unpinned setup-uv fetches a 'latest' manifest from
+          # raw.githubusercontent.com every job; transient fetch failures
+          # fail the job (2026-07-28 incident). Keep in sync with tests.yml.
+          version: "0.9.28"
+
+      - name: Set up Python 3.11 (for docker tests)
+        uses: ./.github/actions/retry
+        with:
+          command: uv python install 3.11
+
+      - name: Install Python dependencies (for docker tests)
+        # ``dev`` extra pulls in pytest, pytest-asyncio —
+        # everything tests/docker/ needs.  We deliberately avoid ``all``
+        # here because the docker tests only drive the container via
+        # subprocess and don't import hermes_agent's optional deps.
+        uses: ./.github/actions/retry
+        with:
+          command: uv sync --locked --python 3.11 --extra dev
+
+      - name: Run docker integration tests
+        env:
+          # Skip rebuild; use the image already loaded by the build step.
+          HERMES_TEST_IMAGE: ${{ env.IMAGE_NAME }}:test
+          # Match the policy in tests.yml :: test job — no accidental
+          # real-API calls from inside the harness.
+          OPENROUTER_API_KEY: ""
+          OPENAI_API_KEY: ""
+          NOUS_API_KEY: ""
+        run: |
+          # Each of these tests drives a container, so the docker daemon sets
+          # the limit and not the processor. This caps the workers. The
+          # default from run_tests.sh is cpu_count*2, which starts 64
+          # containers together on the 32-core amd64 runner.
+          HERMES_TEST_WORKERS=$(nproc) scripts/run_tests.sh tests/docker/ --file-timeout 600
+
+  # ---------------------------------------------------------------------------
+  # Rebuild and push each architecture only after the unprivileged build/test
+  # matrix passes. This job is the sole Docker Hub credential boundary.
+  # ---------------------------------------------------------------------------
+  publish:
+    if: github.repository == 'NousResearch/hermes-agent' && (github.event_name == 'push' && github.ref == 'refs/heads/main' || github.event_name == 'release')
+    needs: [build]
+    environment: container-publish
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - arch: amd64
+            runner: ubuntu-latest-32-core
+            platform: linux/amd64
+            cache-from: type=gha,scope=docker-amd64
+            cache-to: type=gha,mode=max,scope=docker-amd64
+          # Native arm64 for the same reason as the build matrix above.
+          - arch: arm64
+            runner: ubuntu-latest-32-arm-core
+            platform: linux/arm64
+            cache-from: type=gha,scope=docker-arm64
+            cache-to: type=gha,mode=max,scope=docker-arm64
+    runs-on: ${{ matrix.runner }}
+    timeout-minutes: 30
+    steps:
+      - name: Checkout trusted source
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Reject profile exports in the build context
+        run: python3 scripts/ci/check_profile_archive_boundary.py
+
+      # Retry once on transient Docker Hub / buildkit pull failures.
+      # See build job for rationale; same pattern.
+      - name: Set up Docker Buildx
+        id: buildx
+        continue-on-error: true
+        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3
+
+      - name: Set up Docker Buildx (retry)
+        if: steps.buildx.outcome == 'failure'
+        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3
+
+      - name: Log in to Docker Hub
+        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.0
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      # Push by digest only (no tag). The merge job assembles the tagged
+      # manifest list after both architecture publishers complete.
+      - name: Push ${{ matrix.arch }} by digest
+        id: push
+        uses: docker/build-push-action@bcafcacb16a39f128d818304e6c9c0c18556b85f # v7.1.0
+        with:
+          context: .
+          file: Dockerfile
+          platforms: ${{ matrix.platform }}
+          labels: |
+            org.opencontainers.image.revision=${{ github.sha }}
+          build-args: |
+            HERMES_GIT_SHA=${{ github.sha }}
+          outputs: type=image,name=${{ env.IMAGE_NAME }},push-by-digest=true,name-canonical=true,push=true
+          cache-from: ${{ matrix.cache-from }}
+          cache-to: ${{ matrix.cache-to }}
+
+      - name: Export digest
+        run: |
+          mkdir -p /tmp/digests
+          digest="${{ steps.push.outputs.digest }}"
+          touch "/tmp/digests/${digest#sha256:}"
+
+      - name: Upload digest artifact
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: digest-${{ matrix.arch }}
+          path: /tmp/digests/*
+          if-no-files-found: error
+          retention-days: 1
+
+  # ---------------------------------------------------------------------------
+  # Stitch both per-arch digests into a single tagged multi-arch manifest.
+  # This is a registry-side operation — no building, no layer re-push —
+  # so it runs in ~30 seconds.
+  #
+  # On main pushes: tags both :main and :latest.
+  # On releases: tags :<release_tag_name>.
+  # ---------------------------------------------------------------------------
+  merge:
+    if: github.repository == 'NousResearch/hermes-agent' && (github.event_name == 'push' && github.ref == 'refs/heads/main' || github.event_name == 'release')
+    runs-on: ubuntu-latest
+    needs: [publish]
+    timeout-minutes: 10
+    environment: container-publish
+    steps:
+      - name: Download digests
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          path: /tmp/digests
+          pattern: digest-*
+          merge-multiple: true
+
+      # Retry once on transient Docker Hub / buildkit pull failures.
+      # See build job for rationale; same pattern.
+      - name: Set up Docker Buildx
+        id: buildx
+        continue-on-error: true
+        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3
+
+      - name: Set up Docker Buildx (retry)
+        if: steps.buildx.outcome == 'failure'
+        uses: docker/setup-buildx-action@8d2750c68a42422c14e847fe6c8ac0403b4cbd6f # v3
+
+      - name: Log in to Docker Hub
+        uses: docker/login-action@4907a6ddec9925e35a0a9e82d7399ccc52663121 # v4.1.0
+        with:
+          username: ${{ secrets.DOCKERHUB_USERNAME }}
+          password: ${{ secrets.DOCKERHUB_TOKEN }}
+
+      - name: Create manifest list and push
+        working-directory: /tmp/digests
+        env:
+          IMAGE_NAME: ${{ env.IMAGE_NAME }}
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: |
+          set -euo pipefail
+          args=()
+          for digest_file in *; do
+            args+=("${IMAGE_NAME}@sha256:${digest_file}")
+          done
+          if [ "${{ github.event_name }}" = "release" ]; then
+            tags=(-t "${IMAGE_NAME}:${RELEASE_TAG}")
+          else
+            tags=(-t "${IMAGE_NAME}:main" -t "${IMAGE_NAME}:latest")
+          fi
+          # Retry: Docker Hub API + just-pushed digest eventual consistency
+          # can transiently fail the create; the operation is idempotent.
+          for i in 1 2 3; do
+            if docker buildx imagetools create "${tags[@]}" "${args[@]}"; then
+              break
+            fi
+            if [ "$i" = 3 ]; then
+              echo "::error::imagetools create failed after 3 attempts"
+              exit 1
+            fi
+            echo "::warning::imagetools create failed (attempt $i); retrying in 20s"
+            sleep 20
+          done
+
+      - name: Inspect image
+        env:
+          IMAGE_NAME: ${{ env.IMAGE_NAME }}
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: |
+          if [ "${{ github.event_name }}" = "release" ]; then
+            docker buildx imagetools inspect "${IMAGE_NAME}:${RELEASE_TAG}"
+          else
+            docker buildx imagetools inspect "${IMAGE_NAME}:main"
+          fi

.github/workflows/docs-site-checks.yml

@@ -0,0 +1,56 @@
+name: Docs Site Checks
+
+on:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  docs-site-checks:
+    runs-on: ubuntu-latest
+    timeout-minutes: 20
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: 26
+          cache: npm
+          cache-dependency-path: website/package-lock.json
+
+      - name: grab npm 12
+        run: |
+          npm i -g npm@12
+
+      - name: Install website dependencies
+        uses: ./.github/actions/retry
+        with:
+          command: npm ci
+          working-directory: website
+
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: "3.11"
+
+      - name: Install ascii-guard
+        uses: ./.github/actions/retry
+        with:
+          command: python -m pip install ascii-guard==2.3.0 pyyaml==6.0.3
+
+      - name: Extract skill metadata for dashboard
+        run: python3 website/scripts/extract-skills.py
+
+      - name: Regenerate per-skill docs pages + catalogs
+        run: python3 website/scripts/generate-skill-docs.py
+
+      - name: Lint docs diagrams
+        run: npm run lint:diagrams
+        working-directory: website
+
+      - name: Build Docusaurus
+        # Build only the default (en) locale in CI — the full bilingual
+        # build runs in deploy-site.yml on push-to-main / release.
+        # Same pattern Docusaurus uses internally (build:fast --locale en).
+        run: npm run build:fast
+        working-directory: website

.github/workflows/e2e-desktop.yml

@@ -0,0 +1,284 @@
+name: E2E Desktop
+
+on:
+  workflow_call:
+    outputs:
+      review_status:
+        description: Screenshot and visual-diff status for the CI review comment.
+        value: ${{ jobs.e2e.outputs.review_status }}
+
+permissions:
+  contents: read
+
+concurrency:
+  group: e2e-desktop-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  e2e:
+    name: Playwright E2E (Linux)
+    # This job builds the renderer and the electron bundle, then drives a real
+    # Electron app under xvfb. vite, tsc and the Playwright workers all scale
+    # with the core count.
+    runs-on: ubuntu-latest-32-core
+    timeout-minutes: 20
+    outputs:
+      review_status: ${{ steps.review-status.outputs.review_status }}
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      # ── System deps for Electron on headless Ubuntu ───────────────────
+      # Electron needs GTK, NSS,atk, etc. even under xvfb. Playwright's
+      # install-deps covers browsers; for Electron we install the apt
+      # packages directly.
+      - name: Install system dependencies for Electron
+        run: |
+          sudo apt-get update -qq
+          sudo apt-get install -y -qq \
+            xvfb \
+            libgtk-3-0 libnotify4 libnss3 libxss1 libxtst6 \
+            xdg-utils libatspi2.0-0 libdrm2 libgbm1 libasound2t64
+
+      # ── Node ───────────────────────────────────────────────────────────
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: 26
+          cache: npm
+
+      - name: grab npm 12
+        run: |
+          npm i -g npm@12
+
+      # Full npm ci (not --ignore-scripts): electron's postinstall
+      # downloads the binary we launch, and node-pty's native build is
+      # needed for the terminal pane.
+      - uses: ./.github/actions/retry
+        with:
+          command: npm ci
+
+      # ── Python (for the hermes serve backend) ──────────────────────────
+      - name: Install uv
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # 8.2.0
+        with:
+          # Pin the uv version: unpinned, setup-uv resolves "latest" by
+          # fetching a manifest from raw.githubusercontent.com on EVERY job —
+          # a transient fetch failure fails the whole job (2026-07-28 slice-5
+          # incident). Pinned, the binary downloads directly; no manifest hop.
+          version: '0.9.28'
+          enable-cache: true
+          cache-dependency-glob: |
+            pyproject.toml
+            uv.lock
+
+      - name: Set up Python 3.11
+        uses: ./.github/actions/retry
+        with:
+          command: uv python install 3.11
+
+      - name: Install Python dependencies
+        uses: ./.github/actions/retry
+        with:
+          command: uv sync --locked --python 3.11 --extra all --extra dev
+
+      # ── Build desktop app ─────────────────────────────────────────────
+      # The Playwright step below runs `npm run build` before testing so
+      # dist/ is always fresh — no separate build step needed here.
+
+      # ── Restore visual baseline screenshots from main ──────────────────
+      # Baselines are generated on main (via --update-snapshots) and cached.
+      # On PRs, we restore them so toHaveScreenshot has something to compare
+      # against.  The cache key is keyed on the desktop source files so a
+      # UI change naturally invalidates it — but we fall back to the main
+      # cache to avoid cold starts on unrelated PRs.
+      - name: Restore visual baseline screenshots
+        id: restore-baselines
+        uses: actions/cache@0400d5f644dc74513175e3cd8d07132dd4860809 # v4.2.4
+        with:
+          path: apps/desktop/e2e/*-snapshots
+          key: visual-baselines-${{ github.ref_name }}
+          restore-keys: |
+            visual-baselines-main
+
+      # ── Run Playwright E2E under xvfb ─────────────────────────────────
+      # xvfb runs at a fixed 1280x1024 screen so the 1220x800 Electron
+      # window always has a consistent viewport for screenshot comparison.
+      # On main, we run with --update-snapshots to generate baselines.
+      # `npm run test:e2e` builds dist/ as a pretest hook so the renderer
+      # is always fresh — no separate build step needed.
+      - name: Run Playwright E2E tests
+        working-directory: apps/desktop
+        run: |
+          if [ "${{ github.ref_name }}" = "main" ]; then
+            echo "On main — generating/updating baseline screenshots"
+            npm run build && xvfb-run -a --server-args="-screen 0 1280x1024x24" \
+              npx playwright test --reporter=list --update-snapshots
+          else
+            echo "On PR — comparing against cached baselines"
+            npm run build && xvfb-run -a --server-args="-screen 0 1280x1024x24" \
+              npx playwright test --reporter=list
+          fi
+        env:
+          CI: 'true'
+          # Ensure no real API keys leak into the test env.
+          OPENROUTER_API_KEY: ''
+          OPENAI_API_KEY: ''
+          NOUS_API_KEY: ''
+
+      # ── Save updated baselines to cache (main only) ───────────────────
+      - name: Save updated baselines to cache
+        if: github.ref_name == 'main' && always()
+        uses: actions/cache/save@0400d5f644dc74513175e3cd8d07132dd4860809 # v4.2.4
+        with:
+          path: apps/desktop/e2e/*-snapshots
+          key: visual-baselines-main
+
+      # ── Upload Playwright report (HTML + traces) ──────────────────────
+      - name: Upload Playwright report
+        id: upload-report
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: playwright-report-${{ github.sha }}
+          path: apps/desktop/playwright-report
+          retention-days: 14
+          overwrite: true
+
+      # ── Upload test results (screenshots, traces, diffs) ───────────────
+      - name: Upload test results
+        id: upload-results
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: playwright-test-results-${{ github.sha }}
+          path: apps/desktop/test-results
+          retention-days: 14
+          overwrite: true
+
+      # ── Upload just the visual diffs (small, fast to review) ──────────
+      - name: Upload visual diffs
+        id: upload-diffs
+        if: always() && github.ref_name != 'main'
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: visual-diffs-${{ github.sha }}
+          path: |
+            apps/desktop/test-results/**/*-diff.png
+            apps/desktop/test-results/**/*-actual.png
+            apps/desktop/test-results/**/*-expected.png
+          retention-days: 14
+          overwrite: true
+          if-no-files-found: ignore
+
+      - name: Build screenshot review status
+        id: review-status
+        if: always()
+        working-directory: apps/desktop
+        env:
+          RESULTS_URL: ${{ steps.upload-results.outputs.artifact-url }}
+        run: |
+          python3 ../../scripts/ci/e2e_screenshot_status.py \
+            --results-dir test-results \
+            --manifest-output /tmp/e2e-screenshot-manifest.json \
+            --evidence-dir /tmp/e2e-evidence \
+            --artifact-url "$RESULTS_URL" \
+            --output /tmp/e2e-review-status.json
+          {
+            echo 'review_status<<__E2E_REVIEW_STATUS__'
+            cat /tmp/e2e-review-status.json
+            echo '__E2E_REVIEW_STATUS__'
+          } >> "$GITHUB_OUTPUT"
+          cp /tmp/e2e-review-status.json review-status.json
+
+      - name: Upload review status artifact
+        if: always() && steps.review-status.outcome != 'skipped'
+        continue-on-error: true
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: review-status-e2e-desktop
+          path: apps/desktop/review-status.json
+          retention-days: 1
+          overwrite: true
+          if-no-files-found: ignore
+
+      # The trusted workflow_run publisher consumes only this flat, bounded
+      # artifact. It turns selected images into GitHub attachment URLs; it
+      # never checks out or runs this PR's code.
+      - name: Upload inline E2E evidence
+        if: always() && github.ref_name != 'main'
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: e2e-evidence-${{ github.sha }}
+          path: /tmp/e2e-evidence
+          retention-days: 14
+          overwrite: true
+          if-no-files-found: error
+
+      # ── Generate step summary with visual diff info ───────────────────
+      # Parse the JSON report + scan for diff images, then post a summary
+      # to the GitHub Actions step output so reviewers can see what changed
+      # without downloading artifacts.  Runs AFTER uploads so it can link
+      # the artifact download URLs from their step outputs.
+      - name: Generate visual diff summary
+        if: always()
+        working-directory: apps/desktop
+        env:
+          REPORT_URL: ${{ steps.upload-report.outputs.artifact-url }}
+          RESULTS_URL: ${{ steps.upload-results.outputs.artifact-url }}
+          DIFFS_URL: ${{ steps.upload-diffs.outputs.artifact-url }}
+        run: |
+          {
+          echo "## Desktop E2E — Visual Diff Report"
+          echo ""
+
+          # Count diff images (playwright writes *-diff.png on mismatch)
+          DIFF_COUNT=$(find test-results -name '*-diff.png' 2>/dev/null | wc -l)
+          ACTUAL_COUNT=$(find test-results -name '*-actual.png' 2>/dev/null | wc -l)
+
+          if [ "$DIFF_COUNT" -eq 0 ]; then
+            echo "✅ All $ACTUAL_COUNT screenshot(s) matched their baselines (or no baselines existed yet)."
+          else
+            echo "📸 **$DIFF_COUNT of $ACTUAL_COUNT screenshot(s) differ from baseline:**"
+            echo ""
+            echo "| Test | Diff | Actual | Expected |"
+            echo "|------|------|--------|----------|"
+
+            # List each diff image with a link to the artifact
+            for diff in $(find test-results -name '*-diff.png' 2>/dev/null | sort); do
+              base=${diff%-diff.png}
+              test_name=$(basename "$base")
+              echo "| $test_name | [diff]($diff) | [actual](${base}-actual.png) | [expected](${base}-expected.png) |"
+            done
+          fi
+
+          echo ""
+          echo "📥 **Artifacts:**"
+          echo ""
+          if [ -n "$RESULTS_URL" ]; then
+            echo "- [playwright-test-results]($RESULTS_URL) — all screenshots (actual + expected + diff) + traces"
+          fi
+          if [ -n "$REPORT_URL" ]; then
+            echo "- [playwright-report]($REPORT_URL) — interactive HTML report"
+          fi
+          if [ -n "$DIFFS_URL" ]; then
+            echo "- [visual-diffs]($DIFFS_URL) — just the diffed screenshots (small, fast to review)"
+          fi
+          echo ""
+          echo "**To update baselines:** merge to main (baselines auto-update on main runs) or run \`npx playwright test --update-snapshots\` locally."
+
+          # Also parse the JSON report for pass/fail counts
+          if [ -f playwright-report/results.json ]; then
+            echo ""
+            echo "### Test Results"
+            echo ""
+            node -e "
+              const r = require('./playwright-report/results.json');
+              const stats = r.stats || {};
+              console.log('| Status | Count |');
+              console.log('|--------|-------|');
+              console.log('| ✅ Passed | ' + (stats.expected || 0) + ' |');
+              console.log('| ❌ Failed | ' + (stats.unexpected || 0) + ' |');
+              console.log('| ⏭️ Skipped | ' + (stats.skipped || 0) + ' |');
+              console.log('| 🔄 Flaky | ' + (stats.flaky || 0) + ' |');
+            " 2>/dev/null || true
+          fi
+          } >> "$GITHUB_STEP_SUMMARY"

.github/workflows/history-check.yml

@@ -0,0 +1,81 @@
+name: History Check
+
+# Rejects PRs whose branch has no common ancestor with main.
+#
+# In May 2026 PR #25045 was merged from a branch that had been disconnected
+# from main's history (likely an accidental `git checkout --orphan` or
+# `.git/` re-init).  GitHub's merge UI does not refuse merges of unrelated
+# histories, so the PR landed cleanly with the intended one-file change —
+# but its parent-less root commit (413990c94) got grafted into main as a
+# second root, and ~1500 files' worth of `git blame` history collapsed
+# onto that single commit.
+#
+# This check catches the failure mode by requiring `git merge-base` between
+# the PR head and main to be non-empty.
+
+on:
+  workflow_call:
+    outputs:
+      review_status:
+        description: "JSON array of review_status objects for the synthesizer."
+        value: ${{ jobs.check-common-ancestor.outputs.review_status }}
+
+permissions:
+  contents: read
+
+jobs:
+  check-common-ancestor:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    outputs:
+      review_status: ${{ steps.merge-base-check.outputs.review_status }}
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 0 # full history both sides for merge-base
+
+      - id: merge-base-check
+        name: Reject PRs with no common ancestor on main
+        run: |
+          # `git merge-base` exits non-zero AND prints nothing when the two
+          # commits share no ancestor.  We check both conditions explicitly
+          # so the failure message is clear regardless of which signal fires
+          # first.
+          if ! BASE=$(git merge-base origin/main HEAD 2>/dev/null) || [ -z "$BASE" ]; then
+            STATUS='[{"source":"unrelated histories","results":[{"kind":"action_required","title":"Unrelated histories","summary":"This PR has no common ancestor with main.","detail":"","how_to_fix":"Rebase your changes onto current main:\n```\ngit fetch origin main\ngit checkout -b fix-branch origin/main\n# re-apply your changes (cherry-pick, copy files, etc.)\ngit push -f origin fix-branch\n```\n"}]}]'
+            echo "review_status=${STATUS}" >> "$GITHUB_OUTPUT"
+            echo "review_status=${STATUS}" > review-status.json
+            echo ""
+            echo "::error::This PR has no common ancestor with main."
+            echo ""
+            echo "Your branch's history is disconnected from main.  Common causes:"
+            echo "  - the branch was created with 'git checkout --orphan'"
+            echo "  - '.git/' was re-initialized at some point during the work"
+            echo "  - the branch was force-pushed from an unrelated repository"
+            echo ""
+            echo "Merging an unrelated-history PR grafts a parent-less root commit"
+            echo "into main and collapses git blame for every file in that snapshot."
+            echo "Reference: PR #25045 caused this and re-rooted blame on ~1500"
+            echo "files to a single orphan commit."
+            echo ""
+            echo "To fix, rebase your changes onto current main:"
+            echo "  git fetch origin main"
+            echo "  git checkout -b fix-branch origin/main"
+            echo "  # re-apply your changes (cherry-pick, copy files, etc.)"
+            echo "  git push -f origin fix-branch"
+            exit 1
+          fi
+          echo "::notice::Common ancestor with main: $BASE"
+          echo "review_status=[]" >> "$GITHUB_OUTPUT"
+          echo "review_status=[]" > review-status.json
+
+      - name: Upload review status artifact
+        if: always() && steps.merge-base-check.outcome != 'skipped'
+        continue-on-error: true
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: review-status-history-check
+          path: review-status.json
+          retention-days: 1
+          overwrite: true
+          if-no-files-found: ignore

.github/workflows/infographic-check.yml

@@ -0,0 +1,78 @@
+name: Infographic Check
+
+# Rejects PRs that commit PR-infographic images into the repo.
+#
+# PR infographics are rendered to an image-provider URL (fal.media) and
+# embedded in the PR *description*.  The PR body is the archive; the binary
+# never belongs in git history.
+#
+# This has now leaked twice.  PR #48261 removed the first batch, PR #54564
+# removed a second batch and added `infographic/` to `.gitignore` — but
+# `.gitignore` only stops *accidental* `git add`.  It does nothing against
+# `git add -f`, and it does nothing for a path that does not literally match
+# the ignore pattern.  Nine more PNGs (~14MB) were committed in the four
+# weeks AFTER that rule landed, plus PR #70552 caught an `infograficos/`
+# spelling that sidestepped the pattern entirely.
+#
+# A passive ignore rule cannot enforce a policy.  This check can.
+
+on:
+  workflow_call:
+    outputs:
+      review_status:
+        description: "JSON array of review_status objects for the synthesizer."
+        value: ${{ jobs.check-no-committed-infographics.outputs.review_status }}
+
+permissions:
+  contents: read
+
+jobs:
+  check-no-committed-infographics:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    outputs:
+      review_status: ${{ steps.infographic-check.outputs.review_status }}
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - id: infographic-check
+        name: Reject committed PR-infographic images
+        run: |
+          # Match on the IMAGE, not on a directory name.  Keying this to
+          # `infographic/` is what let `infograficos/` through in #70552 —
+          # any localized or typo'd directory would sidestep it again.
+          # Instead: find tracked raster images whose path contains an
+          # infographic-ish segment, in any spelling, at any depth.
+          #
+          # `docs/assets` and `website/` legitimately hold product imagery
+          # and are excluded; those are referenced from shipped docs pages.
+          OFFENDERS=$(git ls-files -z \
+            | tr '\0' '\n' \
+            | grep -iE '(^|/)(infograph|infograf)[^/]*/' \
+            | grep -iE '\.(png|jpe?g|webp|gif)$' \
+            || true)
+
+          if [ -n "$OFFENDERS" ]; then
+            COUNT=$(printf '%s\n' "$OFFENDERS" | wc -l | tr -d ' ')
+            STATUS='[{"source":"committed infographics","results":[{"kind":"action_required","title":"PR infographic committed to the repo","summary":"Infographic images belong in the PR description, never in git.","detail":"","how_to_fix":"Untrack the image and reference the provider URL from the PR body instead:\n```\ngit rm --cached <path-to-image>\n```\nThen put it in the PR description:\n```\n## Infographic\n\n![slug](https://<provider-url>)\n```\n"}]}]'
+            echo "review_status=${STATUS}" >> "$GITHUB_OUTPUT"
+            echo ""
+            echo "::error::${COUNT} PR-infographic image(s) are tracked in git."
+            echo ""
+            printf '%s\n' "$OFFENDERS" | sed 's/^/  /'
+            echo ""
+            echo "PR infographics are rendered to an image-provider URL and"
+            echo "embedded in the PR DESCRIPTION.  The PR body is the archive —"
+            echo "the binary never enters git history."
+            echo ""
+            echo "This rule has been re-established twice already (#48261,"
+            echo "#54564) and leaked both times, because .gitignore cannot stop"
+            echo "'git add -f' or a differently-spelled directory (#70552)."
+            echo ""
+            echo "To fix:"
+            echo "  git rm --cached <path>   # keeps your local copy"
+            echo "  # then embed the provider URL in the PR description"
+            exit 1
+          fi
+          echo "::notice::No committed PR-infographic images."
+          echo "review_status=[]" >> "$GITHUB_OUTPUT"

.github/workflows/install-e2e-run.yml

@@ -0,0 +1,122 @@
+name: Install & Update E2E (reusable)
+
+# Runs ONE update route against ONE starting commit, in the dev sandbox, with a
+# real install (uv, a managed Python, Node, the venv) behind it.
+#
+# Reusable so callers can fan out over the combinations that matter -- update
+# from the tip vs. from an older release, `hermes update` vs. re-running the
+# installer -- without duplicating the runner setup. Each leg is independent:
+# its own sandbox, its own install, nothing rewound or shared.
+#
+# Call it:
+#
+#   jobs:
+#     tip:
+#       uses: ./.github/workflows/install-e2e-run.yml
+#       with:
+#         route: update
+#         install-ref: refs/heads/main
+
+on:
+  workflow_call:
+    inputs:
+      route:
+        description: 'Update path to exercise: update (hermes update) or installer (re-run install.sh).'
+        required: true
+        type: string
+      install-ref:
+        description: 'What to install before updating: a branch, a tag (v2026.7.7), or a SHA reachable from main.'
+        required: false
+        type: string
+        default: refs/heads/main
+      runner:
+        description: 'Runner label.'
+        required: false
+        type: string
+        default: ubuntu-latest
+      timeout-minutes:
+        description: 'Job timeout. A cold run installs real toolchains twice.'
+        required: false
+        type: number
+        default: 45
+
+permissions:
+  contents: read
+
+jobs:
+  e2e:
+    name: ${{ inputs.route }} from ${{ inputs.install-ref }}
+    runs-on: ${{ inputs.runner }}
+    timeout-minutes: ${{ inputs.timeout-minutes }}
+
+    steps:
+      # Full history: the sandbox fetches the starting commit and the test
+      # compares against this commit, so a shallow clone is not enough.
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 0
+
+      # bubblewrap + slirp4netns are what the sandbox is built on; util-linux
+      # supplies the `unshare` that builds the multi-uid userns for the
+      # user-level (non-root) install.
+      - name: Install sandbox dependencies
+        run: |
+          set -euo pipefail
+          sudo apt-get update -qq
+          sudo apt-get install -y -qq bubblewrap slirp4netns uidmap util-linux
+
+      # Ubuntu 24.04 restricts unprivileged user namespaces through AppArmor,
+      # which is exactly what bwrap needs. Report the state before touching it
+      # so a future runner-image change is visible in the log rather than
+      # silently altering what this job proves.
+      - name: Permit unprivileged user namespaces
+        run: |
+          set -euo pipefail
+          echo "--- kernel userns settings (before)"
+          sysctl kernel.unprivileged_userns_clone 2>/dev/null || echo "  (sysctl absent)"
+          sysctl kernel.apparmor_restrict_unprivileged_userns 2>/dev/null || echo "  (sysctl absent)"
+          if sysctl -n kernel.apparmor_restrict_unprivileged_userns >/dev/null 2>&1; then
+            sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
+          fi
+          echo "--- subuid/subgid for $(id -un)"
+          grep "^$(id -un):" /etc/subuid /etc/subgid || echo "  (none — sandbox will say so)"
+
+      - name: Run install + update E2E
+        run: |
+          set -euo pipefail
+          tests/install/install-update-e2e.sh \
+            --route '${{ inputs.route }}' \
+            --install-ref '${{ inputs.install-ref }}'
+        env:
+          # Outside the workspace on purpose: the script creates this directory
+          # up front, and an untracked dir inside the repo makes the worktree
+          # dirty -- which dev-sandbox reacts to by snapshotting the working
+          # copy into a fresh fake-main commit on every invocation, moving the
+          # update target mid-run.
+          HERMES_E2E_LOG_DIR: ${{ runner.temp }}/e2e-logs
+
+      # Artifact names cannot contain '/', and install-ref may be a full ref
+      # like refs/heads/main. GitHub Actions expressions have no string-replace
+      # function, so build the safe name here. Runs even on failure -- that is
+      # exactly when the logs are wanted.
+      - name: Build artifact name
+        if: always()
+        id: artifact
+        run: |
+          set -euo pipefail
+          safe_ref='${{ inputs.install-ref }}'
+          safe_ref="${safe_ref//\//-}"
+          echo "name=install-e2e-${{ inputs.route }}-${safe_ref}" >> "$GITHUB_OUTPUT"
+
+      # The installer's own transcripts say far more than the assertion that
+      # tripped when a real install breaks.
+      - name: Upload installer logs
+        if: always()
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          # Unique per leg: a matrix over releases runs this workflow several
+          # times per route, and same-named artifacts collide.
+          name: ${{ steps.artifact.outputs.name }}-${{ github.sha }}
+          path: ${{ runner.temp }}/e2e-logs
+          retention-days: 14
+          if-no-files-found: ignore

.github/workflows/install-e2e.yml

@@ -0,0 +1,110 @@
+name: Install & Update E2E
+
+# Can a user on a released version get to this commit?
+#
+# For each release we sample, a leg installs that release through the real
+# `curl | install.sh` one-liner (uv, a managed Python, Node, the venv) inside
+# scripts/dev-sandbox.sh, then applies one update route and requires the
+# checkout to land on this commit with a working `hermes`.
+#
+# The starting versions are chosen at runtime from the repo's release tags
+# (scripts/sandbox/pick-release-tags.sh): newest, oldest, and a spread between.
+# A hardcoded list would stop covering the newest release the day after it
+# ships, and would pin an "oldest" that nobody still runs.
+#
+# Triggers:
+#   * every 12 hours, so upstream drift (a new uv, a Node bump, a PyPI change)
+#     surfaces on a schedule rather than in someone's review cycle;
+#   * when a release tag is created -- the moment the set of versions users can
+#     update FROM changes, and the moment a broken updater would strand them;
+#   * manually, where you can pick the route and how many releases to sample.
+#
+# Deliberately NOT on pull_request: a leg takes ~11 minutes of real toolchain
+# installation, and the matrix multiplies that. Updating is release-shaped work,
+# so it is gated on releases and the clock instead.
+
+on:
+  workflow_dispatch:
+    inputs:
+      route:
+        description: 'Which update route to exercise.'
+        required: false
+        type: choice
+        default: both
+        options: [both, update, installer]
+      tag-count:
+        description: 'How many release tags to sample (newest, oldest, and a spread between).'
+        required: false
+        type: string
+        default: '5'
+  schedule:
+    # Every 12 hours, off the hour to avoid the top-of-hour runner crunch.
+    - cron: '20 7,19 * * *'
+  push:
+    tags:
+      # Release tags only: the repo also carries backup/* and one-off tags.
+      - 'v[0-9]+.[0-9]+.[0-9]+'
+      - 'v[0-9]+.[0-9]+.[0-9]+.[0-9]+'
+
+permissions:
+  contents: read
+
+concurrency:
+  group: install-e2e-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  # Which released versions do we test updating FROM? Resolved once and shared
+  # by both route matrices, so the two routes cover the same set.
+  pick-releases:
+    name: Pick release tags
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    outputs:
+      tags: ${{ steps.pick.outputs.tags }}
+    steps:
+      # This job only reads tag names and runs one script, so take the cheap
+      # checkout: no blobs (filter), no other files (sparse), but DO fetch tags
+      # -- they are the whole input, and the default shallow checkout has none.
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          filter: blob:none
+          fetch-tags: true
+          sparse-checkout: scripts/sandbox/pick-release-tags.sh
+          sparse-checkout-cone-mode: false
+      - id: pick
+        run: |
+          set -euo pipefail
+          tags="$(scripts/sandbox/pick-release-tags.sh --count '${{ inputs.tag-count || 5 }}')"
+          echo "Testing updates from: $tags"
+          echo "tags=$tags" >> "$GITHUB_OUTPUT"
+
+  # `hermes update` -- the route most users take.
+  update:
+    if: github.event_name != 'workflow_dispatch' || inputs.route != 'installer'
+    needs: pick-releases
+    strategy:
+      # One release breaking is worth knowing about even if another already
+      # failed, so let every leg report.
+      fail-fast: false
+      matrix:
+        install-ref: ${{ fromJSON(needs.pick-releases.outputs.tags) }}
+    uses: ./.github/workflows/install-e2e-run.yml
+    with:
+      route: update
+      install-ref: ${{ matrix.install-ref }}
+
+  # Re-running the curl one-liner over an existing checkout: autostash + pull
+  # rather than the updater's own git handling.
+  installer:
+    if: github.event_name != 'workflow_dispatch' || inputs.route != 'update'
+    needs: pick-releases
+    strategy:
+      fail-fast: false
+      max-parallel: 3
+      matrix:
+        install-ref: ${{ fromJSON(needs.pick-releases.outputs.tags) }}
+    uses: ./.github/workflows/install-e2e-run.yml
+    with:
+      route: installer
+      install-ref: ${{ matrix.install-ref }}

.github/workflows/installer-tests.yml

@@ -0,0 +1,46 @@
+name: Installer tests
+
+# scripts/install.ps1's PowerShell tests. They exercise the installer as a real
+# subprocess, and every path contract they assert (8.3 short-name aliases,
+# Git Bash layouts, provider-cmdlet behavior) is Windows-specific — so they need
+# a Windows runner. Before this workflow existed the files were in the tree but
+# nothing ever ran them.
+
+on:
+  workflow_call:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: installer-tests-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  powershell:
+    name: PowerShell installer tests
+    runs-on: windows-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      # Windows PowerShell 5.1 as well as pwsh 7: install.ps1 is delivered via
+      # `irm | iex` into whatever shell the user already has, and 5.1 is what
+      # ships with Windows. A construct that only parses under 7 is a broken
+      # installer for most of the people hitting it.
+      - name: 8.3 short-path normalization (pwsh 7)
+        shell: pwsh
+        run: pwsh -NoProfile -ExecutionPolicy Bypass -File scripts/tests/test-install-ps1-longpath.ps1
+
+      - name: 8.3 short-path normalization (Windows PowerShell 5.1)
+        shell: powershell
+        run: powershell -NoProfile -ExecutionPolicy Bypass -File scripts/tests/test-install-ps1-longpath.ps1
+
+      - name: System Node and npm compatibility (pwsh 7)
+        shell: pwsh
+        run: pwsh -NoProfile -ExecutionPolicy Bypass -File scripts/tests/test-install-ps1-node-compatibility.ps1
+
+      - name: System Node and npm compatibility (Windows PowerShell 5.1)
+        shell: powershell
+        run: powershell -NoProfile -ExecutionPolicy Bypass -File scripts/tests/test-install-ps1-node-compatibility.ps1

.github/workflows/js-autofix.yml

@@ -0,0 +1,276 @@
+name: auto-fix lint issues & formatting
+
+# On push to main (or manual trigger), run `npm run fix` on each workspace
+# package and apply any changes via a PR.
+#
+# Fixable lint issues (import sorting, unused imports, curly braces, etc.) are
+# auto-corrected on merge so PRs aren't blocked by them. The PR-time eslint
+# check in typecheck.yml fails only when un-fixable errors remain.
+#
+# NOTE: App token pushes DO trigger further workflow runs (unlike
+# secrets.GITHUB_TOKEN). The concurrency group (ts-autofix-${{ github.ref }})
+# with cancel-in-progress: true prevents an infinite loop — a re-triggered
+# run cancels the in-flight one, and since the second run finds no new fixes
+# (the first run already applied them), it exits with an empty patch.
+#
+# ── Security model: two-job split ───────────────────────────────────────────
+#
+# The eslint process executes repo code (eslint.config.mjs, package.json
+# scripts, installed plugins). To prevent a malicious PR from getting arbitrary
+# code execution on a runner with push access, the work is split:
+#
+#   1. generate-patch (unprivileged, contents: read only)
+#      Checks out, installs deps, runs eslint --fix, produces a .patch artifact.
+#      Worst case: malicious code runs here on an ephemeral runner with zero
+#      push permissions.
+#
+#   2. apply-patch (privileged, contents: write + pull-requests: write)
+#      Checks out, downloads the patch artifact, applies it, pushes to the
+#      bot/js-autofix branch, creates/updates a PR, and enables auto-merge.
+#      This job never runs npm, never installs anything, never executes any
+#      repo code. The only input it trusts is the patch artifact.
+#      Skipped entirely when generate-patch reports no fixes (has-fixes != true).
+#      The PR auto-merges (squash) once CI passes. If CI fails or main moves,
+#      the PR is auto-closed and the branch deleted — the next run re-applies
+#      on the current state.
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - '**/*.js'
+      - '**/*.cjs'
+      - '**/*.mjs'
+      - '**/*.ts'
+      - '**/*.tsx'
+      - 'package.json'
+      - 'package-lock.json'
+  workflow_dispatch:
+
+permissions:
+  contents: read # default; apply-patch job overrides to write
+
+concurrency:
+  group: ts-autofix-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  generate-patch:
+    name: Generate eslint --fix patch
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    outputs:
+      has-fixes: ${{ steps.produce-patch.outputs.has-fixes }}
+    # No permissions override → inherits workflow-level contents: read.
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: 26
+          cache: npm
+
+      - name: grab npm 12
+        run: |
+          npm i -g npm@12
+
+      # --ignore-scripts: eslint only needs TS sources + eslint packages.
+      - uses: ./.github/actions/retry
+        with:
+          command: npm ci --ignore-scripts
+
+      - name: npm run fix in all workspaces
+        # continue-on-error: if un-fixable errors exist on main, we still want
+        # to commit whatever fixes were applied. The PR-time check in
+        # typecheck.yml is what blocks un-fixable errors from landing.
+        continue-on-error: true
+        run: npm run fix
+
+      - name: Produce patch
+        id: produce-patch
+        run: |
+          # Exclude every file that the dep-version-gate ruleset guards
+          # (package manifests, eslint configs, workflow files). A patch
+          # that contains one of these files makes the bot PR wait for a
+          # team review, and auto-merge then stops. The check step in
+          # typecheck.yml still reports their lint errors.
+          # The (glob) magic makes "**/" also match files at the repo
+          # root, which plain pathspec wildcards do not.
+          EXCLUDES=(
+            ':(exclude,glob)**/package.json'
+            ':(exclude,glob)**/package-lock.json'
+            ':(exclude,glob)**/eslint.config.*'
+            ':(exclude,glob).github/**'
+          )
+          if git diff --quiet -- . "${EXCLUDES[@]}"; then
+            echo "No fixes needed."
+            echo "has-fixes=false" >> "$GITHUB_OUTPUT"
+            # Empty patch signals "nothing to do" to apply-patch.
+            : > js-fix.patch
+          else
+            git diff -- . "${EXCLUDES[@]}" > js-fix.patch
+            echo "has-fixes=true" >> "$GITHUB_OUTPUT"
+            echo "Patch size: $(wc -c < js-fix.patch) bytes"
+
+            # Reject patches that touch anything outside JS/TS/JSON sources.
+            # `npm run fix` should only ever modify those; anything else means
+            # eslint/prettier or a plugin went rogue and we refuse to ship it.
+            BAD=$(git diff --name-only -- . "${EXCLUDES[@]}" | grep -vE '\.(js|cjs|mjs|ts|tsx|json)$' || true)
+            if [ -n "$BAD" ]; then
+              echo "::error::Refusing to upload patch — touches disallowed files:"
+              echo "$BAD"
+              exit 1
+            fi
+          fi
+
+      - name: Upload patch artifact
+        uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4
+        with:
+          name: js-fix-patch
+          path: js-fix.patch
+          retention-days: 1
+          include-hidden-files: true
+
+  apply-patch:
+    name: Apply patch
+    needs: generate-patch
+    # Skip entirely when generate-patch found no fixes — saves a runner,
+    # avoids a redundant checkout/download, and keeps the job graph honest.
+    if: needs.generate-patch.outputs.has-fixes == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    environment: trusted-automation
+    permissions:
+      contents: write # needed to push to bot/js-autofix
+      pull-requests: write # needed for PR creation + auto-merge
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Get GitHub App token
+        id: app-token
+        uses: ./.github/actions/get-app-token
+        with:
+          client-id: ${{ vars.APP_CLIENT_ID }}
+          private-key: ${{ secrets.APP_PRIVATE_KEY }}
+
+      - name: Download patch
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: js-fix-patch
+          # ${{ runner.temp }} expands in with: params (shell-style $VAR does not).
+          # download-artifact's path is a *directory* — the artifact's js-fix.patch
+          # file lands inside it, so $RUNNER_TEMP/js-fix.patch resolves correctly
+          # in the run step below.
+          path: ${{ runner.temp }}
+
+      - name: Apply patch and push to bot branch
+        env:
+          BOT_BRANCH: bot/js-autofix
+        run: |
+          set -euo pipefail
+
+          # Empty patch = nothing to do.
+          if [ ! -s "$RUNNER_TEMP/js-fix.patch" ]; then
+            echo "Patch is empty. No fixes to apply."
+            exit 0
+          fi
+
+          # Apply the patch produced by the unprivileged job.
+          git apply --check "$RUNNER_TEMP/js-fix.patch" || {
+            echo "::error::Patch does not apply cleanly. Branch may have moved."
+            exit 1
+          }
+          git apply "$RUNNER_TEMP/js-fix.patch"
+
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add -A
+          git commit -m "fmt(js): \`npm run fix\` on merge"
+
+          # Push to the dedicated bot branch. Force-push is safe here:
+          # bot/js-autofix is a bot-only branch that gets rewritten each run.
+          # If the branch was deleted after a previous PR merge, this
+          # recreates it.
+          git push --force origin HEAD:"$BOT_BRANCH"
+
+      - name: Create/update PR and enable auto-merge
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+          BOT_BRANCH: bot/js-autofix
+        run: |
+          set -euo pipefail
+
+          # Create PR if one doesn't exist. If it already exists, the
+          # force-push above already updated it with the latest fixes.
+          PR_NUM=$(gh pr list --head "$BOT_BRANCH" --state open --json number --jq '.[0].number' 2>/dev/null || true)
+          if [ -z "$PR_NUM" ]; then
+            # gh pr create prints the PR URL. Extract the number from it
+            # (https://github.com/<org>/<repo>/pull/<number>).
+            PR_URL=$(gh pr create \
+              --head "$BOT_BRANCH" --base main \
+              --title 'fmt(js): `npm run fix` auto-fix' \
+              --body 'Auto-generated by the `auto-fix lint issues & formatting` workflow. Auto-merges (squash) once CI passes. If CI fails or `main` moves, the PR is auto-closed and the branch deleted — the next run re-applies on the current state.')
+            PR_NUM=$(echo "$PR_URL" | grep -oE '[0-9]+$')
+          fi
+
+          # Enable auto-merge (squash). If already enabled, this is a no-op.
+          gh pr merge "$PR_NUM" --auto --squash || true
+
+      - name: Wait for merge, auto-close on failure or stale
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+          START_SHA: ${{ github.sha }}
+        run: |
+          set -euo pipefail
+
+          PR_NUM=$(gh pr list --head bot/js-autofix --state open --json number --jq '.[0].number' 2>/dev/null || true)
+          if [ -z "$PR_NUM" ]; then
+            echo "No open PR. Nothing to wait for."
+            exit 0
+          fi
+
+          echo "Waiting for PR #$PR_NUM to merge..."
+
+          # Poll every 15s for up to ~10 minutes. Auto-merge will handle the
+          # PR even if this job times out — the polling is for cleanup only
+          # (auto-close on CI failure, conflicts, or main moving).
+          for i in $(seq 1 40); do
+            sleep 15
+
+            STATE=$(gh pr view "$PR_NUM" --json state --jq '.state')
+            if [ "$STATE" = "MERGED" ] || [ "$STATE" = "CLOSED" ]; then
+              echo "PR #$PR_NUM is $STATE."
+              exit 0
+            fi
+
+            # If main moved, the PR may have already merged (which moves
+            # main) or another commit landed. Re-check state first.
+            CURRENT_SHA=$(gh api "repos/${{ github.repository }}/branches/main" --jq '.commit.sha')
+            if [ "$CURRENT_SHA" != "$START_SHA" ]; then
+              STATE=$(gh pr view "$PR_NUM" --json state --jq '.state')
+              if [ "$STATE" = "MERGED" ]; then
+                echo "PR #$PR_NUM merged (main moved to $CURRENT_SHA)."
+                exit 0
+              fi
+              echo "Main moved ($START_SHA → $CURRENT_SHA). Closing stale PR."
+              gh pr close "$PR_NUM" --delete-branch || true
+              exit 0
+            fi
+
+            # If CI checks failed, close + delete the branch.
+            if gh pr checks "$PR_NUM" 2>/dev/null | grep -qi "fail"; then
+              echo "CI failed on PR #$PR_NUM. Closing + deleting branch."
+              gh pr close "$PR_NUM" --delete-branch
+              exit 0
+            fi
+
+            # If PR is conflicted, close + delete the branch.
+            MERGEABLE=$(gh pr view "$PR_NUM" --json mergeable --jq '.mergeable')
+            if [ "$MERGEABLE" = "CONFLICTING" ]; then
+              echo "PR #$PR_NUM is conflicted. Closing + deleting branch."
+              gh pr close "$PR_NUM" --delete-branch
+              exit 0
+            fi
+          done
+
+          echo "Timeout reached. Auto-merge will handle PR #$PR_NUM if CI passes."

.github/workflows/js-tests.yml

@@ -0,0 +1,83 @@
+# .github/workflows/js-tests.yml
+name: JS Tests
+
+on:
+  workflow_call:
+
+jobs:
+  check:
+    name: JS & TS checks
+    # One 32-core job replaces a 14-leg matrix. The matrix spread about 612s
+    # of check payload over 4-core runners. It paid about 371s of repeated
+    # setup to do it: 14 checkouts, 14 node installs, 14 node_modules
+    # restores.
+    #
+    # One larger runner installs one time. vitest, tsc and eslint each size
+    # their own worker pool from the core count.
+    runs-on: ubuntu-latest-32-core
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: 26
+          cache: npm
+
+      - name: grab npm 12
+        run: |
+          # No-op once the bundled npm is already 12.x — saves ~5-15s/job and
+          # keeps the installed major aligned with the npm12 cache-key tag.
+          npm --version | grep -q '^12\.' || npm i -g npm@12
+
+      # The ``cache: npm`` option of ``setup-node`` caches only the ~/.npm
+      # tarball cache. The job then extracts the full workspace node_modules
+      # again and runs the postinstalls again, which includes the Electron
+      # binary fetch. This caches the installed tree itself, keyed on the
+      # lockfile, and skips ``npm ci`` on an exact hit. There are no
+      # restore-keys: a partial hit leaves a stale tree, so anything other
+      # than an exact lockfile match reinstalls from the start.
+      #
+      # This install runs WITH scripts, so the tree holds the postinstall
+      # artifacts. The postinstall of electron unpacks its binary into
+      # node_modules/electron/dist, which is inside the cached tree.
+      #
+      # The ~/.cache/electron download cache stays out of the key on purpose.
+      # ``npm ci`` is skipped on a hit, so nothing reads that cache. It only
+      # makes the archive larger.
+      - name: Restore node_modules
+        id: node-modules-cache
+        uses: actions/cache@0400d5f644dc74513175e3cd8d07132dd4860809 # v4.2.4
+        with:
+          path: |
+            node_modules
+            apps/*/node_modules
+            ui-tui/node_modules
+            ui-tui/packages/*/node_modules
+            tests-js/node_modules
+            web/node_modules
+          key: node-modules-scripts-${{ runner.os }}-node26-npm12-${{ hashFiles('package-lock.json') }}
+
+      - uses: ./.github/actions/retry
+        if: steps.node-modules-cache.outputs.cache-hit != 'true'
+        with:
+          command: npm ci
+
+      # Every check runs at the same time. The step fails only after all of
+      # them finish. There are two reasons this is not ``npm run --ws check``.
+      #
+      #   * ``--ws`` is serial and stops at the first workspace that fails. A
+      #     run then reports one failure, where the matrix this replaced
+      #     reported every failure together.
+      #   * The unit of work is a CHECK, and not a workspace. apps/desktop is
+      #     most of the payload, and its own ``check`` is a serial && chain.
+      #     A spread across workspaces alone leaves that chain as the long
+      #     pole. This expands the ``check:*`` sub-scripts of a package, so
+      #     its lint, ui, electron and plugin suites all run together. That
+      #     is the same selection rule the old matrix job used.
+      #
+      # Discovery is ``npm query .workspace``. A new package or a new
+      # ``check:*`` script needs no change here. An empty list is an error and
+      # not an empty run, because an empty run reports green after it checks
+      # nothing.
+      - name: Run all workspace checks
+        run: node .github/scripts/run-workspace-checks.mjs

.github/workflows/label-rerun.yml

@@ -0,0 +1,87 @@
+name: Label rerun
+
+# When the ``ci-reviewed`` label is added to a PR, rerun all failed jobs in
+# the latest CI run. This re-evaluates ``review-labels`` (which now sees the
+# label) and GitHub reruns the dependent ``all-checks-pass`` gate.
+#
+# ``gh run rerun`` only works on a completed run. Thus this waits when the
+# run is still in progress. The wait is now short. The two slowest jobs are
+# the 40-minute comment poller and the 45-minute image build. Each one moved
+# to its own workflow, so a CI run ends when its required jobs end.
+#
+# The review comment updates without help. The poller in
+# ci-review-comment.yml watches the CI run through the API. It gets the
+# rerun results.
+
+on:
+  pull_request:
+    types: [labeled]
+
+permissions:
+  actions: write
+  pull-requests: read
+
+concurrency:
+  group: label-rerun-${{ github.event.pull_request.number }}
+  cancel-in-progress: true
+
+jobs:
+  rerun-review-labels:
+    name: Rerun review-labels job
+    if: github.event.label.name == 'ci-reviewed'
+    runs-on: ubuntu-latest
+    timeout-minutes: 40
+    steps:
+      - name: Wait for CI run to finish, then rerun failed jobs
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REPO: ${{ github.repository }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+        run: |
+          set -uo pipefail
+
+          # Find the latest CI run for this PR's head SHA.
+          RUN_INFO=$(gh run list \
+            --repo "$REPO" \
+            --commit "$HEAD_SHA" \
+            --workflow ci.yaml \
+            --limit 1 \
+            --json databaseId,status \
+            --jq '.[0] | "\(.databaseId) \(.status)"' 2>/dev/null || true)
+
+          if [ -z "$RUN_INFO" ]; then
+            echo "No CI run found for this PR — nothing to rerun."
+            exit 0
+          fi
+
+          # Split "RUN_ID STATUS" into two vars. Read STATUS from RUN_INFO,
+          # not from the truncated RUN_ID. Both values came from the same
+          # var before, which made STATUS the run id. Thus the wait branch
+          # always ran.
+          RUN_ID="${RUN_INFO%% *}"
+          STATUS="${RUN_INFO##* }"
+
+          echo "Latest CI run: $RUN_ID (status: $STATUS)"
+
+          # If the run is still in progress, wait for it to finish.
+          # gh run rerun only works on completed runs — if we try while it's
+          # running, GitHub rejects with "cannot be rerun; This workflow is
+          # already running".
+          if [ "$STATUS" != "completed" ]; then
+            echo "Run is $STATUS — waiting for completion (this may take a while)..."
+            # gh run watch --exit-status exits non-zero if the run fails,
+            # which is expected (the label gate fails). Don't let that kill
+            # the workflow — we WANT to rerun failed jobs.
+            timeout 2100 gh run watch "$RUN_ID" --repo "$REPO" --interval 15 || true
+
+            # Verify it's actually completed now.
+            STATUS=$(gh run view "$RUN_ID" --repo "$REPO" --json status --jq '.status' 2>/dev/null || echo "unknown")
+            if [ "$STATUS" != "completed" ]; then
+              echo "Run is still $STATUS after wait — giving up."
+              exit 0
+            fi
+          fi
+
+          echo "Run completed. Rerunning all failed jobs..."
+          gh run rerun "$RUN_ID" --repo "$REPO" --failed || true
+          echo "Done. GitHub will rerun review-labels and all dependent jobs."

.github/workflows/lint.yml

@@ -0,0 +1,180 @@
+name: Lint (ruff + ty)
+
+# Two things here:
+#   1. Advisory diff — ruff + ty diagnostics as a diff vs the target branch.
+#      Writes a Markdown summary to the run page. Exit zero always.
+#   2. Blocking ``ruff check .`` — enforces the explicit rules in
+#      ``[tool.ruff.lint.select]`` (currently PLW1514). Failure blocks merge.
+#      Separate job so the advisory diff still runs even when enforcement
+#      fails.
+#
+# CI-sensitive file review was previously here as a ``ci-review`` job but
+# has moved to ``review-labels.yml`` so it can be rerun independently.
+
+on:
+  workflow_call:
+    inputs:
+      event_name:
+        description: The event name from the calling orchestrator (pull_request or push).
+        type: string
+        required: true
+
+permissions:
+  contents: read
+
+concurrency:
+  group: lint-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  lint-diff:
+    name: ruff + ty diff
+    if: inputs.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 0 # need full history for merge-base + worktree
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # 8.2.0
+        with:
+          # Pinned: unpinned setup-uv fetches a 'latest' manifest from
+          # raw.githubusercontent.com every job; transient fetch failures
+          # fail the job (2026-07-28 incident). Keep in sync with tests.yml.
+          version: "0.9.28"
+
+      - name: Install ruff + ty
+        uses: ./.github/actions/retry
+        with:
+          command: uv tool install ruff && uv tool install ty
+
+      - name: Determine base ref
+        id: base
+        run: |
+          # For PRs, diff against the merge base with the target branch.
+          # For pushes to main, diff against the previous commit on main.
+          if [ "${{ inputs.event_name }}" = "pull_request" ]; then
+            BASE_SHA=$(git merge-base "origin/${{ github.base_ref }}" HEAD)
+            BASE_REF="origin/${{ github.base_ref }}"
+          else
+            BASE_SHA=$(git rev-parse HEAD~1 2>/dev/null || git rev-parse HEAD)
+            BASE_REF="HEAD~1"
+          fi
+          echo "sha=${BASE_SHA}" >> "$GITHUB_OUTPUT"
+          echo "ref=${BASE_REF}" >> "$GITHUB_OUTPUT"
+          echo "Base SHA: ${BASE_SHA}"
+          echo "Base ref: ${BASE_REF}"
+
+      - name: Run ruff + ty on HEAD
+        run: |
+          mkdir -p .lint-reports/head
+          ruff check --output-format json --exit-zero \
+            > .lint-reports/head/ruff.json || true
+          ty check --output-format gitlab --exit-zero \
+            > .lint-reports/head/ty.json || true
+          echo "HEAD ruff: $(wc -c < .lint-reports/head/ruff.json) bytes"
+          echo "HEAD ty:   $(wc -c < .lint-reports/head/ty.json) bytes"
+
+      - name: Run ruff + ty on base (via git worktree)
+        run: |
+          mkdir -p .lint-reports/base
+          # Use a worktree so we don't clobber the main checkout. If the basex
+          # SHA is identical to HEAD (e.g. first commit), skip and leave the
+          # base reports empty — the diff script handles missing files.
+          HEAD_SHA=$(git rev-parse HEAD)
+          BASE_SHA="${{ steps.base.outputs.sha }}"
+          if [ "$BASE_SHA" = "$HEAD_SHA" ]; then
+            echo "Base SHA == HEAD SHA, skipping base scan."
+            echo '[]' > .lint-reports/base/ruff.json
+            echo '[]' > .lint-reports/base/ty.json
+          else
+            git worktree add --detach /tmp/lint-base "$BASE_SHA"
+            (
+              cd /tmp/lint-base
+              ruff check --output-format json --exit-zero \
+                > "$GITHUB_WORKSPACE/.lint-reports/base/ruff.json" || true
+              ty check --output-format gitlab --exit-zero \
+                > "$GITHUB_WORKSPACE/.lint-reports/base/ty.json" || true
+            )
+            git worktree remove --force /tmp/lint-base
+          fi
+          echo "base ruff: $(wc -c < .lint-reports/base/ruff.json) bytes"
+          echo "base ty:   $(wc -c < .lint-reports/base/ty.json) bytes"
+
+      - name: Generate diff summary
+        env:
+          HEAD_REF: ${{ inputs.event_name == 'pull_request' && github.head_ref || github.ref_name }}
+        run: |
+          python scripts/lint_diff.py \
+            --base-ruff .lint-reports/base/ruff.json \
+            --head-ruff .lint-reports/head/ruff.json \
+            --base-ty   .lint-reports/base/ty.json \
+            --head-ty   .lint-reports/head/ty.json \
+            --base-ref  "${{ steps.base.outputs.ref }}" \
+            --head-ref  "$HEAD_REF" \
+            --output    .lint-reports/summary.md
+          cat .lint-reports/summary.md >> "$GITHUB_STEP_SUMMARY"
+
+  ruff-blocking:
+    # Enforce the rules in pyproject.toml [tool.ruff.lint.select]. Currently
+    # PLW1514 (unspecified-encoding) — catches bare ``open()`` /
+    # ``read_text()`` / ``write_text()`` calls that default to locale
+    # encoding on Windows. Failure here blocks merge; the advisory
+    # ``lint-diff`` job above runs independently so reviewers still get
+    # the diff comment even when enforcement fails.
+    name: ruff enforcement (blocking)
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # 8.2.0
+        with:
+          # Pinned: unpinned setup-uv fetches a 'latest' manifest from
+          # raw.githubusercontent.com every job; transient fetch failures
+          # fail the job (2026-07-28 incident). Keep in sync with tests.yml.
+          version: "0.9.28"
+
+      - name: Install ruff
+        uses: ./.github/actions/retry
+        with:
+          command: uv tool install ruff
+
+      - name: ruff check .
+        # No --exit-zero, no || true. Exit code propagates to the job,
+        # which propagates to the required-check gate.
+        run: |
+          ruff check .
+
+  windows-footguns:
+    # Static guardrails on Windows-unsafe Python primitives — os.kill(pid, 0),
+    # os.killpg, os.setsid, signal.SIGKILL without getattr fallback,
+    # shebang scripts via subprocess, bare open() without encoding=, etc.
+    # See scripts/check-windows-footguns.py for the full rule list.
+    name: Windows footguns (blocking)
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # 8.2.0
+        with:
+          # Pinned: unpinned setup-uv fetches a 'latest' manifest from
+          # raw.githubusercontent.com every job; transient fetch failures
+          # fail the job (2026-07-28 incident). Keep in sync with tests.yml.
+          version: "0.9.28"
+
+      - name: Set up Python 3.11
+        uses: ./.github/actions/retry
+        with:
+          command: uv python install 3.11
+
+      - name: Run footgun checker
+        run: python scripts/check-windows-footguns.py --all

.github/workflows/lockfile-diff.yml

@@ -0,0 +1,107 @@
+name: Lockfile diff
+
+# Advisory PR comment showing the *semantic* diff of package-lock.json
+# changes — which packages were added/removed/updated and their versions.
+# The raw textual diff of a lockfile is unreadable (npm reorders entries
+# and rewrites integrity hashes), so scripts/ci/lockfile_diff.py parses
+# the ``packages`` map at the merge base and at HEAD and set-diffs the
+# {install path: version} maps instead.
+#
+# The semantic diff is exposed as a workflow_call output ``review_status``
+# (a JSON array in the unified status format) and an artifact
+# (``lockfile-diff`` containing the markdown fragment) for the step
+# summary.
+#
+# Never blocking — this is review signal, not enforcement.
+
+on:
+  workflow_call:
+    outputs:
+      changed:
+        description: Whether package-lock.json changed relative to the target branch.
+        value: ${{ jobs.diff.outputs.changed }}
+      review_status:
+        description: JSON array of review status objects for the unified PR comment.
+        value: ${{ jobs.diff.outputs.review_status }}
+
+permissions:
+  contents: read
+
+concurrency:
+  group: lockfile-diff-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  diff:
+    name: package-lock.json semantic diff
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    outputs:
+      changed: ${{ steps.diff.outputs.changed }}
+      review_status: ${{ steps.emit-status.outputs.review_status }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 0 # need history for the merge base
+
+      - name: Generate semantic lockfile diff
+        id: diff
+        run: |
+          set -euo pipefail
+          # Three-dot semantics by hand: diff from the merge base with the
+          # target branch to the PR head, so changes that landed on main
+          # after the branch point don't show up as this PR's doing.
+          BASE_SHA=$(git merge-base "origin/${{ github.base_ref }}" HEAD)
+          echo "Merge base: ${BASE_SHA}"
+          python3 scripts/ci/lockfile_diff.py \
+            --base "$BASE_SHA" \
+            --head HEAD \
+            --output /tmp/lockfile-diff.md
+          if [ -s /tmp/lockfile-diff.md ]; then
+            echo "changed=true" >> "$GITHUB_OUTPUT"
+            {
+              echo "## package-lock.json semantic diff"
+              echo ""
+              cat /tmp/lockfile-diff.md
+            } >> "$GITHUB_STEP_SUMMARY"
+          else
+            echo "changed=false" >> "$GITHUB_OUTPUT"
+            : > /tmp/lockfile-diff.md
+          fi
+
+      - name: Emit review_status
+        id: emit-status
+        run: |
+          set -euo pipefail
+          CHANGED="${{ steps.diff.outputs.changed }}"
+          STATUS="[]"
+
+          if [ "$CHANGED" = "true" ]; then
+            CONTENT=$(cat /tmp/lockfile-diff.md | python3 -c "import sys,json; print(json.dumps(sys.stdin.read()))")
+            STATUS="[{\"source\":\"lockfile-diff\",\"results\":[{\"kind\":\"action_required\",\"title\":\"package-lock.json\",\"summary\":\"Locked npm dependency versions changed.\",\"detail\":${CONTENT},\"how_to_fix\":\"Add the \`ci-reviewed\` label after verifying the version changes are expected.\"}]}]"
+          else
+            STATUS="[]"
+          fi
+
+          echo "review_status=${STATUS}" >> "$GITHUB_OUTPUT"
+          echo "review_status=${STATUS}" > review-status.json
+
+      - name: Upload review status artifact
+        if: always() && steps.emit-status.outcome != 'skipped'
+        continue-on-error: true
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: review-status-lockfile-diff
+          path: review-status.json
+          retention-days: 1
+          overwrite: true
+          if-no-files-found: ignore
+
+      - name: Upload diff artifact
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: lockfile-diff
+          path: /tmp/lockfile-diff.md
+          retention-days: 1
+          overwrite: true

.github/workflows/nix.yml

@@ -0,0 +1,119 @@
+name: Nix flake check
+
+# Builds every output of the flake: the package, the devShell, and the 21
+# checks under nix/checks.nix — module evaluation, option parity, .env
+# assembly, service argv, and the rest.
+#
+# This workflow owns its triggers and ci.yml does not call it, for the reason
+# docker.yml gives: a reusable-workflow call holds the caller run in progress
+# for the full build, and GitHub refuses `gh run rerun` on a run that is still
+# in progress. One slow advisory job in the CI lane blocks every rerun of the
+# fast required jobs beside it. A separate run reruns and cancels on its own.
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+# PR runs collapse to the newest commit. A push to main is never cancelled:
+# each one saves the store cache that later PRs restore from, so cancelling a
+# merge would leave the next PR to build from nothing.
+concurrency:
+  group: nix-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  # A `paths:` filter cannot gate this workflow correctly. The flake packages
+  # the product, and nine of the checks then run the built binary, so a change
+  # to hermes_cli/ alone can fail `nix flake check` without touching one file
+  # under nix/. The `nix` lane therefore follows python_prod as well as the
+  # flake inputs. On push the classifier fails open and every lane is true.
+  detect:
+    name: Detect affected areas
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    outputs:
+      nix: ${{ steps.classify.outputs.nix }}
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Detect affected areas
+        id: classify
+        uses: ./.github/actions/detect-changes
+        with:
+          github-token: ${{ github.token }}
+
+  flake-check:
+    name: nix flake check
+    needs: [detect]
+    if: needs.detect.outputs.nix == 'true'
+    # The build compiles the package and its whole dependency closure, so this
+    # takes minutes and not seconds when the cache misses. `nix flake check`
+    # builds 21 checks, and --max-jobs defaults to the core count. It uses the
+    # wider runner with no more configuration.
+    runs-on: ubuntu-latest-32-core
+    timeout-minutes: 60
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Install Nix
+        uses: cachix/install-nix-action@630ae543ea3a38a9a4166f03376c02c50f408342 # v31.11.0
+        with:
+          extra_nix_config: |
+            experimental-features = nix-command flakes
+            # A store path that does not substitute is a cache miss and not a
+            # build failure. Build it here instead.
+            fallback = true
+            # Each source archive is fetched one time in a run, and not one
+            # time for each evaluation.
+            tarball-ttl = 3600
+
+      # Restores /nix/store from the GitHub Actions cache. The store holds the
+      # whole dependency closure, so a hit turns a build of several minutes
+      # into a short evaluation.
+      #
+      # The Magic Nix Cache is not an option here. Its free tier ended in
+      # February 2025 with the GitHub cache API that it was built on. This
+      # action uses the current API and needs no account and no secret.
+      - name: Restore and save the Nix store
+        uses: nix-community/cache-nix-action@7df957e333c1e5da7721f60227dbba6d06080569 # v7
+        with:
+          # The closure changes when the flake inputs change or when the
+          # dependencies of the project change. The key hashes both, so an
+          # edit to the source alone keeps the hit.
+          primary-key: nix-${{ runner.os }}-${{ hashFiles('flake.lock', 'nix/**', 'pyproject.toml', 'uv.lock') }}
+          # On a miss, restore the newest store for this runner. Most of the
+          # closure — Python, node, each transitive library — survives a bump
+          # of the lockfile, so an old store still removes most of the work.
+          restore-prefixes-first-match: nix-${{ runner.os }}-
+
+          # Save from main only. A cache that a PR writes is visible to that
+          # PR alone and never to another branch, so a save there spends the
+          # 10 GB quota of the repository and helps no later run. A PR still
+          # restores: it reads the cache that the merge to main wrote. This is
+          # the same rule that docker.yml applies to `cache-to`.
+          save: ${{ github.event_name != 'pull_request' }}
+
+          # Collect garbage before the save, so the store stays inside the
+          # 10 GB quota of the repository. Without a limit the store grows at
+          # each merge until GitHub removes the entry, and the next PR then
+          # gets nothing. This number is the size of the store and not the
+          # size of the compressed archive.
+          gc-max-store-size-linux: 5G
+
+          # Delete the caches that this key replaces. GitHub removes caches by
+          # least recent use across the whole repository, so a Nix store that
+          # is never purged pushes out the caches of the other workflows.
+          purge: true
+          purge-prefixes: nix-${{ runner.os }}-
+          purge-created: 0
+          purge-primary-key: never
+
+      - name: nix flake check
+        # --print-build-logs: a check that fails then prints the assertion
+        # that failed, and not only the derivation that failed to build.
+        run: nix flake check --print-build-logs

.github/workflows/osv-scanner.yml

@@ -0,0 +1,141 @@
+name: OSV-Scanner
+
+# Scans lockfiles (uv.lock, package-lock.json) against the OSV vulnerability
+# database. Runs on every PR/push (via the ci.yml orchestrator's workflow_call)
+# and on a weekly schedule against main.
+#
+# This is detection-only — OSV-Scanner does NOT open PRs or modify pins.
+# It reports known CVEs in currently-pinned dependency versions so we can
+# decide when and how to patch on our own schedule. Our pinning strategy
+# (full SHA / exact version) is preserved; only the notification signal
+# is added.
+#
+# Complements the supply-chain-audit.yml workflow (which scans for malicious
+# code patterns in PR diffs) by covering the orthogonal "currently-pinned
+# dep became known-vulnerable" case.
+#
+# Uses Google's officially-recommended reusable workflow, pinned by SHA.
+# Findings land in the repo's Security tab (Code Scanning > OSV-Scanner).
+# fail-on-vuln is disabled so the job does not block merges on pre-existing
+# vulnerabilities in pinned deps that we may need to patch deliberately.
+#
+# The reusable workflow can't emit custom outputs, so a wrapper job
+# downloads the SARIF result and summarizes the vulnerability count into
+# a review_status for the unified PR comment.
+
+on:
+  workflow_call:
+  schedule:
+    # Weekly scan against main — catches CVEs published after merge for
+    # deps that haven't changed since.
+    - cron: '0 9 * * 1'
+  workflow_dispatch:
+
+permissions:
+  # Required to upload SARIF file to CodeQL. See: https://github.com/github/codeql-action/issues/2117
+  actions: read
+  contents: read
+  security-events: write
+
+jobs:
+  scan:
+    name: Scan lockfiles
+    uses: google/osv-scanner-action/.github/workflows/osv-scanner-reusable.yml@9a498708959aeaef5ef730655706c5a1df1edbc2 # v2.3.8
+    with:
+      # Scan explicit lockfiles rather than recursing, so we only look at
+      # the five sources of truth and skip vendored / test / worktree dirs.
+      scan-args: |-
+        --lockfile=uv.lock
+        --lockfile=package-lock.json
+        --lockfile=website/package-lock.json
+        --lockfile=plugins/platforms/photon/sidecar/package-lock.json
+        --lockfile=scripts/whatsapp-bridge/package-lock.json
+      # The upstream reusable workflow uploads this exact file under its
+      # fixed artifact name, which the wrapper downloads below.
+      results-file-name: osv-results.sarif
+      fail-on-vuln: false
+
+  emit-status:
+    name: Emit review status
+    runs-on: ubuntu-latest
+    needs: scan
+    if: always()
+    outputs:
+      review_status: ${{ steps.emit.outputs.review_status }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Download SARIF result
+        uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093 # v4
+        with:
+          name: OSV Scanner SARIF file
+          path: /tmp/osv-results
+        continue-on-error: true
+
+      - name: Emit review_status
+        id: emit
+        run: |
+          set -euo pipefail
+          STATUS="[]"
+
+          if [ -f /tmp/osv-results/osv-results.sarif ]; then
+            # Count vulnerabilities from the SARIF file
+            VULN_COUNT=$(python3 -c "
+          import json, sys
+          try:
+              with open('/tmp/osv-results/osv-results.sarif') as f:
+                  data = json.load(f)
+              count = 0
+              vulns = []
+              for run in data.get('runs', []):
+                  for result in run.get('results', []):
+                      count += 1
+                      rule_id = result.get('ruleId', 'unknown')
+                      message = result.get('message', {}).get('text', '')
+                      loc = result.get('locations', [{}])[0].get('physicalLocation', {}).get('artifactLocation', {}).get('uri', '')
+                      vulns.append(f'- {rule_id} in {loc}: {message}')
+              print(count)
+              if vulns:
+                  print('\n'.join(vulns[:20]), file=sys.stderr)
+          except Exception:
+              print(0)
+          ")
+
+            VULN_DETAIL=""
+            if [ "$VULN_COUNT" -gt 0 ] 2>/dev/null; then
+              VULN_PLURAL=$([ "$VULN_COUNT" -eq 1 ] && echo "y" || echo "ies")
+              VULN_DETAIL=$(python3 -c "
+          import json, sys
+          try:
+              with open('/tmp/osv-results/osv-results.sarif') as f:
+                  data = json.load(f)
+              vulns = []
+              for run in data.get('runs', []):
+                  for result in run.get('results', []):
+                      rule_id = result.get('ruleId', 'unknown')
+                      loc = result.get('locations', [{}])[0].get('physicalLocation', {}).get('artifactLocation', {}).get('uri', '')
+                      vulns.append(f'- {rule_id} in {loc}')
+              print(json.dumps('\n'.join(vulns[:20])))
+          except Exception:
+              print(json.dumps(''))
+          ")
+              STATUS="[{\"source\":\"osv scan\",\"results\":[{\"kind\":\"warning\",\"title\":\"OSV vulnerability scan\",\"summary\":\"${VULN_COUNT} known vulnerabilit${VULN_PLURAL} found in pinned dependencies.\",\"detail\":${VULN_DETAIL},\"how_to_fix\":\"Review the findings in the [Security tab](../../security/code-scanning). Update the affected dependencies if a patched version is available.\"}]}]"
+            else
+              STATUS="[]"
+            fi
+          fi
+
+          echo "review_status=${STATUS}" >> "$GITHUB_OUTPUT"
+          echo "review_status=${STATUS}" > review-status.json
+
+      - name: Upload review status artifact
+        if: always() && steps.emit.outcome != 'skipped'
+        continue-on-error: true
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: review-status-osv-scanner
+          path: review-status.json
+          retention-days: 1
+          overwrite: true
+          if-no-files-found: ignore

.github/workflows/profile-artifact-check.yml

@@ -0,0 +1,21 @@
+name: Profile Artifact Boundary
+
+# A reusable, unconditional guard for the incident class in #92457. Ignore
+# files reduce accidental staging; this job is the enforcement boundary that
+# still catches `git add -f` and generated files present during a build.
+
+on:
+  workflow_call:
+
+permissions:
+  contents: read
+
+jobs:
+  check-profile-artifacts:
+    name: Reject profile archives
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - name: Reject profile exports in the checkout
+        run: python3 scripts/ci/check_profile_archive_boundary.py

.github/workflows/publish-e2e-evidence.yml

@@ -0,0 +1,80 @@
+name: Publish E2E evidence
+
+# This runs only from the default branch after CI completes. It intentionally
+# checks out main, never the PR ref, and treats the downloaded artifact as
+# untrusted input before uploading validated GitHub attachments.
+on:
+  workflow_run:
+    workflows: [CI]
+    types: [completed]
+
+permissions:
+  actions: read
+  contents: read
+  pull-requests: write
+
+concurrency:
+  group: publish-e2e-evidence-${{ github.event.workflow_run.id }}
+  cancel-in-progress: false
+
+jobs:
+  publish:
+    name: Publish inline E2E evidence
+    if: github.event.workflow_run.event == 'pull_request'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment: gh-image
+    steps:
+      - name: Check out trusted publisher
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          ref: ${{ github.event.repository.default_branch }}
+          persist-credentials: false
+
+      # v1.2.0 resolves to 44f4b93ecbbe22de6c45fa2f62f519aee564ca8c.
+      - name: Install gh-image
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: gh extension install drogers0/gh-image --pin v1.2.0
+
+      - name: Download and attach evidence
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GITHUB_TOKEN: ${{ github.token }}
+          GH_SESSION_TOKEN: ${{ secrets.GH_IMAGE_SESSION_TOKEN }}
+          SOURCE_REPO: ${{ github.repository }}
+          SOURCE_RUN_ID: ${{ github.event.workflow_run.id }}
+          HEAD_OWNER: ${{ github.event.workflow_run.head_repository.owner.login }}
+          HEAD_BRANCH: ${{ github.event.workflow_run.head_branch }}
+          HEAD_SHA: ${{ github.event.workflow_run.head_sha }}
+        run: |
+          set -euo pipefail
+
+          # The run's own ``pull_requests`` payload is always empty for a
+          # fork PR, so resolve the PR from its head reference instead.
+          # The head-SHA match skips runs that a newer push superseded.
+          PR_NUMBER=$(gh api -X GET "repos/$SOURCE_REPO/pulls" \
+            -f head="$HEAD_OWNER:$HEAD_BRANCH" -f state=open \
+            --jq '.[] | select(.head.sha == $ENV.HEAD_SHA) | .number' \
+            | head -n1)
+          if [ -z "$PR_NUMBER" ]; then
+            echo "No open pull request has head $HEAD_OWNER:$HEAD_BRANCH at $HEAD_SHA (CI run $SOURCE_RUN_ID)."
+            exit 0
+          fi
+
+          ARTIFACT_NAME=$(gh api "repos/$SOURCE_REPO/actions/runs/$SOURCE_RUN_ID/artifacts" \
+            --jq '.artifacts[] | select(.expired == false and (.name | startswith("e2e-evidence-"))) | .name' \
+            | python3 -c 'import sys; print(next(iter(sys.stdin), "").strip())')
+          if [ -z "$ARTIFACT_NAME" ]; then
+            echo "No E2E evidence artifact was produced for CI run $SOURCE_RUN_ID."
+            exit 0
+          fi
+
+          EVIDENCE_DIR="$RUNNER_TEMP/e2e-evidence"
+          mkdir -p "$EVIDENCE_DIR"
+          gh run download "$SOURCE_RUN_ID" --repo "$SOURCE_REPO" --name "$ARTIFACT_NAME" --dir "$EVIDENCE_DIR"
+
+          python3 scripts/ci/publish_e2e_evidence.py \
+            --evidence-dir "$EVIDENCE_DIR" \
+            --source-repo "$SOURCE_REPO" \
+            --pr-number "$PR_NUMBER"

.github/workflows/review-labels.yml

@@ -0,0 +1,123 @@
+name: Review labels
+
+# Require explicit maintainer review when CI-sensitive files or the MCP
+# catalog change. Previously this was split across two jobs in two
+# workflows: ``ci-review`` in lint.yml (gated on ``ci_review``) and
+# ``mcp-catalog-review`` in supply-chain-audit.yml (gated on
+# ``mcp_catalog``). Both checked for their own label.
+#
+# Now consolidated: a single ``ci-reviewed`` label covers both. The
+# comment sections tell the reviewer exactly what to verify per area,
+# so one label is enough — the human reads the comment, not the label
+# name.
+#
+# Outputs:
+#   ci_reviewed    — "true" / "false" / "" (empty when neither lane ran)
+#   review_status  — JSON array of status objects consumed by the review
+#                    comment assembler. See scripts/ci/emit_review_status.py.
+
+on:
+  workflow_call:
+    inputs:
+      ci_review:
+        description: Whether CI-sensitive files (eslint config, workflows, actions) changed.
+        type: boolean
+        default: false
+      ci_review_files:
+        description: JSON list of CI-sensitive files changed by the pull request.
+        type: string
+        default: '[]'
+      mcp_catalog:
+        description: Whether the MCP catalog / installer changed.
+        type: boolean
+        default: false
+      supply_chain:
+        description: Whether the critical supply-chain scan found a risk requiring review.
+        type: boolean
+        default: false
+    outputs:
+      ci_reviewed:
+        description: Whether the ci-reviewed label is present. Empty when neither input was true.
+        value: ${{ jobs.check.outputs.ci_reviewed }}
+      review_status:
+        description: JSON array of status objects for the review comment assembler.
+        value: ${{ jobs.check.outputs.review_status }}
+
+permissions:
+  contents: read
+  pull-requests: read # read PR labels
+
+jobs:
+  check:
+    name: Review label gate
+    if: inputs.ci_review || inputs.mcp_catalog || inputs.supply_chain
+    runs-on: ubuntu-latest
+    timeout-minutes: 2
+    outputs:
+      ci_reviewed: ${{ steps.label-check.outputs.ci_reviewed }}
+      review_status: ${{ steps.build-status.outputs.review_status }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Check ci-reviewed label
+        id: label-check
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REPO: ${{ github.repository }}
+        run: |
+          set -euo pipefail
+          PR="${{ github.event.pull_request.number }}"
+          LABELS=$(gh pr view "$PR" --repo "$REPO" --json labels --jq '.labels[].name' || true)
+
+          if echo "$LABELS" | grep -Fxq 'ci-reviewed'; then
+            echo "ci-reviewed label present."
+            echo "ci_reviewed=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "ci-reviewed label missing."
+            echo "ci_reviewed=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Build review_status JSON
+        id: build-status
+        env:
+          CI_REVIEW: ${{ inputs.ci_review }}
+          CI_REVIEW_FILES: ${{ inputs.ci_review_files }}
+          MCP_CATALOG: ${{ inputs.mcp_catalog }}
+          SUPPLY_CHAIN: ${{ inputs.supply_chain }}
+          LABEL_PRESENT: ${{ steps.label-check.outputs.ci_reviewed }}
+          REPO_URL: ${{ github.server_url }}/${{ github.repository }}
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+        run: |
+          set -euo pipefail
+          args=()
+          if [ "$CI_REVIEW" = "true" ]; then args+=(--ci-review); fi
+          args+=(--ci-review-files "$CI_REVIEW_FILES")
+          if [ "$MCP_CATALOG" = "true" ]; then args+=(--mcp-catalog); fi
+          if [ "$SUPPLY_CHAIN" = "true" ]; then args+=(--supply-chain); fi
+          if [ "$LABEL_PRESENT" = "true" ]; then args+=(--label-present); fi
+
+          # Write to both $GITHUB_OUTPUT and review-status.json for the
+          # live comment poller to pick up as an artifact.
+          python3 scripts/ci/emit_review_status.py "${args[@]}" \
+            --repo-url "$REPO_URL" --base-sha "$BASE_SHA" --head-sha "$HEAD_SHA" \
+            --output "$GITHUB_OUTPUT"
+          grep '^review_status=' "$GITHUB_OUTPUT" > review-status.json
+
+      - name: Upload review status artifact
+        if: always() && steps.build-status.outcome != 'skipped'
+        continue-on-error: true
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: review-status-review-labels
+          path: review-status.json
+          retention-days: 1
+          overwrite: true
+          if-no-files-found: ignore
+
+      - name: Fail on missing label
+        if: steps.label-check.outputs.ci_reviewed != 'true'
+        run: |
+          echo "::error::CI-sensitive changes require the ci-reviewed label. Add the label and re-run this check."
+          exit 1

.github/workflows/rust-tests.yml

@@ -0,0 +1,76 @@
+# .github/workflows/rust-tests.yml
+name: Rust tests
+
+# `cargo test` for the Tauri bootstrap installer (Hermes-Setup). Nothing in CI
+# compiled this crate before: `.rs` lives under `apps/`, so the change
+# classifier matched it as `frontend` and ran the TypeScript matrix, which
+# cannot notice a Rust error. The crate's unit tests existed in the tree and had
+# never run.
+#
+# Linux runner on purpose. The pipe-drain tests in src/powershell.rs need a real
+# process tree whose grandchild inherits the parent's stdout, and their fixture
+# is `#[cfg(unix)]`; the Windows half of that same contract is covered by
+# `-SelfTestPipeDrain` in scripts/desktop-update/windows.ps1 on the Windows
+# lane. A Windows runner here would compile them out and report green over zero
+# coverage.
+
+on:
+  workflow_call:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: rust-tests-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  bootstrap-installer:
+    name: cargo test (bootstrap installer)
+    # cargo builds codegen units and test binaries in parallel across the
+    # cores. This lane also builds the crate from the start when Cargo.toml
+    # changes.
+    runs-on: ubuntu-latest-32-core
+    timeout-minutes: 30
+    defaults:
+      run:
+        working-directory: apps/bootstrap-installer/src-tauri
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      # Tauri links against the system webkit2gtk on Linux, so the crate does
+      # not compile without these even for `cargo test --lib`.
+      - name: Install Tauri system dependencies
+        working-directory: .
+        run: |
+          sudo apt-get update
+          sudo apt-get install --no-install-recommends -y \
+            libwebkit2gtk-4.1-dev \
+            libappindicator3-dev \
+            librsvg2-dev \
+            libxdo-dev \
+            libssl-dev \
+            patchelf
+
+      # Keyed on Cargo.toml, not Cargo.lock: apps/bootstrap-installer/.gitignore
+      # excludes the lockfile (a create-tauri-app scaffold default), so there is
+      # nothing pinned to hash and `--locked` cannot be used. That also means
+      # this crate re-resolves its whole dependency graph on every build, which
+      # is a real gap for a signed installer given the pinning policy in
+      # AGENTS.md — tracking separately rather than widening this PR.
+      #
+      # No restore-keys: a partial hit leaves a stale target dir, and cargo
+      # re-resolves correctly on top of a Cargo.toml-keyed hit anyway.
+      - name: Restore cargo cache
+        uses: actions/cache@0400d5f644dc74513175e3cd8d07132dd4860809 # v4.2.4
+        with:
+          path: |
+            ~/.cargo/registry
+            ~/.cargo/git
+            apps/bootstrap-installer/src-tauri/target
+          key: cargo-${{ runner.os }}-${{ hashFiles('apps/bootstrap-installer/src-tauri/Cargo.toml') }}
+
+      # --lib only: the integration/bin targets would need a built frontend
+      # (vite dist) that this lane deliberately does not produce.
+      - name: cargo test
+        run: cargo test --lib

.github/workflows/skills-index-freshness.yml

@@ -0,0 +1,167 @@
+name: Skills Index Freshness Check
+
+# Belt-and-suspenders for the twice-daily build_skills_index pipeline.
+# If the live /docs/api/skills-index.json ever goes more than 26 hours
+# stale OR the file disappears entirely OR a major source has collapsed,
+# this workflow opens a GitHub issue so we hear about it before users do.
+#
+# Triggered every 4 hours so we catch a stuck cron within one tick.
+
+on:
+  schedule:
+    - cron: '0 */4 * * *'
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  issues: write
+
+jobs:
+  check-freshness:
+    if: github.repository == 'NousResearch/hermes-agent'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    environment: trusted-automation
+    steps:
+      # `Get GitHub App token` below is a LOCAL composite action
+      # (./.github/actions/get-app-token), so the repository must be on disk
+      # before it can be resolved. Without this checkout the job dies with
+      # "Can't find 'action.yml' ... under .github/actions/get-app-token"
+      # every time the probe is non-ok — i.e. exactly when the watchdog is
+      # supposed to file its issue.
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Probe live index
+        id: probe
+        run: |
+          set -e
+          URL="https://hermes-agent.nousresearch.com/docs/api/skills-index.json"
+          echo "Probing $URL"
+          # -L follows redirects; -f fails on HTTP errors; -s suppresses progress
+          if ! curl -fsSL --retry 3 --retry-delay 10 -o /tmp/skills-index.json "$URL"; then
+            echo "status=fetch-failed" >> "$GITHUB_OUTPUT"
+            echo "detail=Could not download $URL" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+          # Validate + extract generated_at and per-source counts
+          python3 <<'PY' >> "$GITHUB_OUTPUT"
+          import json, sys
+          from datetime import datetime, timezone
+
+          try:
+              with open("/tmp/skills-index.json") as f:
+                  data = json.load(f)
+          except Exception as e:
+              print(f"status=parse-failed")
+              print(f"detail=JSON decode error: {e}")
+              sys.exit(0)
+
+          generated_at = data.get("generated_at", "")
+          total = data.get("skill_count", 0)
+          skills = data.get("skills", [])
+          if not isinstance(skills, list):
+              print("status=invalid-shape")
+              print(f"detail=skills field is not a list (got {type(skills).__name__})")
+              sys.exit(0)
+
+          # Per-source counts
+          from collections import Counter
+          by_src = Counter(s.get("source", "") for s in skills)
+
+          # Freshness
+          age_hours = None
+          try:
+              ts = datetime.fromisoformat(generated_at.replace("Z", "+00:00"))
+              age_hours = (datetime.now(timezone.utc) - ts).total_seconds() / 3600
+          except Exception:
+              pass
+
+          # Floors — same as build_skills_index.py EXPECTED_FLOORS.
+          floors = {
+              "skills.sh": 100,
+              "lobehub": 100,
+              "clawhub": 50,
+              "official": 50,
+              "github": 30,
+              "browse-sh": 50,
+          }
+          issues = []
+          if age_hours is not None and age_hours > 26:
+              issues.append(f"Index is {age_hours:.1f}h old (limit 26h)")
+          for src, floor in floors.items():
+              count = by_src.get(src, 0)
+              if src == "skills.sh":
+                  count = by_src.get("skills.sh", 0) + by_src.get("skills-sh", 0)
+              if count < floor:
+                  issues.append(f"{src}: {count} < {floor}")
+          if total < 1500:
+              issues.append(f"total skills: {total} < 1500")
+
+          if issues:
+              detail = "; ".join(issues)
+              print("status=degraded")
+              # GITHUB_OUTPUT doesn't allow newlines without explicit delimiter
+              print(f"detail={detail}")
+          else:
+              print("status=ok")
+              print(f"detail=Index OK — {total} skills, generated {generated_at}")
+              by_summary = ", ".join(f"{k}={v}" for k, v in by_src.most_common(8))
+              print(f"summary={by_summary}")
+          PY
+
+      - name: Report status
+        run: |
+          echo "Probe status: ${{ steps.probe.outputs.status }}"
+          echo "Detail:       ${{ steps.probe.outputs.detail }}"
+          if [ -n "${{ steps.probe.outputs.summary }}" ]; then
+            echo "Summary:      ${{ steps.probe.outputs.summary }}"
+          fi
+
+      - name: Get GitHub App token
+        if: steps.probe.outputs.status != 'ok'
+        id: app-token
+        uses: ./.github/actions/get-app-token
+        with:
+          client-id: ${{ vars.APP_CLIENT_ID }}
+          private-key: ${{ secrets.APP_PRIVATE_KEY }}
+
+      - name: Open issue on degraded / failed probe
+        if: steps.probe.outputs.status != 'ok'
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+          STATUS: ${{ steps.probe.outputs.status }}
+          DETAIL: ${{ steps.probe.outputs.detail }}
+        run: |
+          # Find existing open issue by title prefix so we don't spam — we
+          # append a comment instead of opening a new one each tick.
+          TITLE_PREFIX="[skills-index-watchdog]"
+          existing=$(gh issue list \
+            --repo "${{ github.repository }}" \
+            --state open \
+            --search "in:title \"$TITLE_PREFIX\"" \
+            --json number,title \
+            --jq '.[] | select(.title | startswith("'"$TITLE_PREFIX"'")) | .number' \
+            | head -1)
+          BODY="Automated freshness probe failed.
+
+          **Status:** \`$STATUS\`
+          **Detail:** $DETAIL
+
+          The Skills Hub at /docs/skills depends on \`/docs/api/skills-index.json\`.
+          The unified index is rebuilt by \`.github/workflows/skills-index.yml\` (cron 6/18 UTC)
+          and \`.github/workflows/deploy-site.yml\` (on every push affecting website/skills).
+          If this issue keeps reopening, check the latest runs:
+
+          - https://github.com/${{ github.repository }}/actions/workflows/skills-index.yml
+          - https://github.com/${{ github.repository }}/actions/workflows/deploy-site.yml
+
+          This issue was opened by \`.github/workflows/skills-index-freshness.yml\`. Close it once the underlying problem is fixed; the next probe will reopen if it's still broken."
+          if [ -n "$existing" ]; then
+            echo "Appending to existing issue #$existing"
+            gh issue comment "$existing" --repo "${{ github.repository }}" --body "Probe still failing at $(date -u +%FT%TZ): \`$STATUS\` — $DETAIL"
+          else
+            echo "Opening new watchdog issue"
+            gh issue create --repo "${{ github.repository }}" \
+              --title "$TITLE_PREFIX Skills index is stale or degraded ($STATUS)" \
+              --body "$BODY"
+          fi

.github/workflows/skills-index.yml

@@ -0,0 +1,82 @@
+name: Build Skills Index
+
+on:
+  schedule:
+    # Run twice daily: 6 AM and 6 PM UTC
+    - cron: "0 6,18 * * *"
+  workflow_dispatch: # Manual trigger
+  push:
+    branches: [main]
+    paths:
+      - "scripts/build_skills_index.py"
+      - ".github/workflows/skills-index.yml"
+
+permissions:
+  contents: read
+  actions: write # to trigger deploy-site.yml on schedule
+
+jobs:
+  build-index:
+    # Only run on the upstream repository, not on forks
+    if: github.repository == 'NousResearch/hermes-agent'
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    environment: trusted-automation
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Get GitHub App token
+        id: app-token
+        uses: ./.github/actions/get-app-token
+        with:
+          client-id: ${{ vars.APP_CLIENT_ID }}
+          private-key: ${{ secrets.APP_PRIVATE_KEY }}
+
+      - uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405 # v6.2.0
+        with:
+          python-version: "3.11"
+
+      - name: Install dependencies
+        uses: ./.github/actions/retry
+        with:
+          command: pip install httpx==0.28.1 pyyaml==6.0.2
+
+      - name: Build skills index
+        env:
+          GITHUB_TOKEN: ${{ steps.app-token.outputs.token }}
+        run: python scripts/build_skills_index.py
+
+      - name: Upload index artifact
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: skills-index
+          path: website/static/api/skills-index.json
+          retention-days: 7
+
+  # Re-trigger the docs deploy so the refreshed index lands on the live site.
+  # The deploy itself is owned by deploy-site.yml (which crawls and deploys
+  # everything in one pipeline); we just kick it on a schedule.
+  trigger-deploy:
+    needs: build-index
+    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    environment: trusted-automation
+    steps:
+      # Required: `Get GitHub App token` is a LOCAL composite action
+      # (./.github/actions/get-app-token) and cannot resolve without the repo
+      # checked out. `build-index` above already does this; this job did not,
+      # so the scheduled deploy re-trigger never fired.
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Get GitHub App token
+        id: app-token
+        uses: ./.github/actions/get-app-token
+        with:
+          client-id: ${{ vars.APP_CLIENT_ID }}
+          private-key: ${{ secrets.APP_PRIVATE_KEY }}
+
+      - name: Trigger Deploy Site workflow
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+        run: gh workflow run deploy-site.yml --repo ${{ github.repository }} -f skills_index_run_id=${{ github.run_id }}

.github/workflows/supply-chain-audit.yml

@@ -0,0 +1,308 @@
+name: Supply Chain Audit
+
+# Narrow, high-signal scanner. Only fires on critical indicators of supply
+# chain attacks (e.g. the litellm-style payloads). Low-signal heuristics
+# (plain base64, plain exec/eval, dependency/Dockerfile/workflow edits,
+# Actions version unpinning, outbound POST/PUT) were intentionally
+# removed — they fired on nearly every PR and trained reviewers to ignore
+# the scanner. Keep this file's checks ruthlessly narrow: if you find
+# yourself adding WARNING-tier patterns here again, make a separate
+# advisory-only workflow instead.
+#
+# Path-gating is handled centrally by the ``ci.yml`` orchestrator's
+# ``detect`` job. The orchestrator passes ``scan`` / ``deps`` booleans as
+# inputs; this workflow's jobs gate on those inputs instead of re-computing
+# the diff. MCP catalog review was previously here but has moved to
+# ``review-labels.yml`` so it can be rerun independently.
+#
+# Outputs:
+#   review_status      — JSON array of status objects consumed by the review
+#                         comment assembler (scripts/ci/assemble_review_comment.py).
+#   critical_findings  — "true" when the narrow critical-pattern scan found
+#                         something. The review-label gate consumes this and
+#                         owns the action-required result, so adding
+#                         ``ci-reviewed`` can heal the run on rerun.
+
+on:
+  workflow_call:
+    inputs:
+      event_name:
+        description: The event name from the calling orchestrator.
+        type: string
+        required: true
+      scan:
+        description: Whether supply-chain-relevant files changed.
+        type: boolean
+        required: true
+      deps:
+        description: Whether pyproject.toml changed.
+        type: boolean
+        required: true
+    outputs:
+      review_status:
+        description: JSON array of review status objects for the review comment assembler.
+        value: ${{ jobs.aggregate.outputs.review_status }}
+      critical_findings:
+        description: Whether the critical-pattern scan found a risk requiring maintainer review.
+        value: ${{ jobs.aggregate.outputs.critical_findings }}
+
+permissions:
+  pull-requests: write
+  contents: read
+
+jobs:
+  scan:
+    name: Scan PR for critical supply chain risks
+    if: inputs.scan
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    outputs:
+      review_status: ${{ steps.emit-status.outputs.review_status }}
+      critical_findings: ${{ steps.scan.outputs.found }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 0
+
+      - name: Scan diff for critical patterns
+        id: scan
+        env:
+          GH_TOKEN: ${{ github.token }}
+          CI_REVIEWED: ${{ contains(github.event.pull_request.labels.*.name, 'ci-reviewed') }}
+        run: |
+          set -euo pipefail
+
+          BASE="${{ github.event.pull_request.base.sha }}"
+          HEAD="${{ github.event.pull_request.head.sha }}"
+
+          # Added lines only, excluding lockfiles.
+          # Three-point diff (base...head) diffs from the merge base to HEAD,
+          # so only changes introduced by this PR are included — not changes
+          # that landed on main after the PR branched off.
+          DIFF=$(git diff "$BASE"..."$HEAD" -- . ':!uv.lock' ':!*.lock' ':!package-lock.json' ':!yarn.lock' || true)
+
+          FINDINGS=""
+
+          # --- .pth files (auto-execute on Python startup) ---
+          # The exact mechanism used in the litellm supply chain attack:
+          # https://github.com/BerriAI/litellm/issues/24512
+          PTH_FILES=$(git diff --diff-filter=d --name-only "$BASE"..."$HEAD" | grep '\.pth$' || true)
+          if [ -n "$PTH_FILES" ]; then
+            FINDINGS="${FINDINGS}
+          ### 🚨 CRITICAL: .pth file added or modified
+          Python \`.pth\` files in \`site-packages/\` execute automatically when the interpreter starts — no import required.
+
+          **Files:**
+          \`\`\`
+          ${PTH_FILES}
+          \`\`\`
+          "
+          fi
+
+          # --- base64 decode + exec/eval on the same line (the litellm attack pattern) ---
+          B64_EXEC_HITS=$(echo "$DIFF" | grep -n '^+' | grep -iE 'base64\.(b64decode|decodebytes|urlsafe_b64decode)' | grep -iE 'exec\(|eval\(' | head -10 || true)
+          if [ -n "$B64_EXEC_HITS" ]; then
+            FINDINGS="${FINDINGS}
+          ### 🚨 CRITICAL: base64 decode + exec/eval combo
+          Base64-decoded strings passed directly to exec/eval — the signature of hidden credential-stealing payloads.
+
+          **Matches:**
+          \`\`\`
+          ${B64_EXEC_HITS}
+          \`\`\`
+          "
+          fi
+
+          # --- subprocess with encoded/obfuscated command argument ---
+          PROC_HITS=$(echo "$DIFF" | grep -n '^+' | grep -E 'subprocess\.(Popen|call|run)\s*\(' | grep -iE 'base64|\\x[0-9a-f]{2}|chr\(' | head -10 || true)
+          if [ -n "$PROC_HITS" ]; then
+            FINDINGS="${FINDINGS}
+          ### 🚨 CRITICAL: subprocess with encoded/obfuscated command
+          Subprocess calls whose command strings are base64- or hex-encoded are a strong indicator of payload execution.
+
+          **Matches:**
+          \`\`\`
+          ${PROC_HITS}
+          \`\`\`
+          "
+          fi
+
+          # --- Install-hook files (setup.py/sitecustomize/usercustomize/__init__.pth) ---
+          # These execute during pip install or interpreter startup.
+          # Anchored at repo root: only the top-level setup.py/setup.cfg run during
+          # `pip install`, and only top-level sitecustomize.py/usercustomize.py are
+          # auto-loaded by the interpreter via site.py. Any nested file with the
+          # same name (e.g. hermes_cli/setup.py — the CLI setup wizard) is unrelated
+          # and produced false positives that trained reviewers to ignore the scanner.
+          SETUP_HITS=$(git diff --diff-filter=d --name-only "$BASE"..."$HEAD" | grep -E '^(setup\.py|setup\.cfg|sitecustomize\.py|usercustomize\.py|__init__\.pth)$' || true)
+          # A maintainer-applied ci-reviewed label records the manual review
+          # required for intentional changes to an install hook. The scanner
+          # still blocks every unreviewed addition or modification.
+          if [ -n "$SETUP_HITS" ] && [ "$CI_REVIEWED" != "true" ]; then
+            FINDINGS="${FINDINGS}
+          ### 🚨 CRITICAL: Install-hook file added or modified
+          These files can execute code during package installation or interpreter startup.
+
+          **Files:**
+          \`\`\`
+          ${SETUP_HITS}
+          \`\`\`
+          "
+          fi
+
+          if [ -n "$FINDINGS" ]; then
+            echo "found=true" >> "$GITHUB_OUTPUT"
+            echo "$FINDINGS" > /tmp/findings.md
+          else
+            echo "found=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Emit review_status
+        id: emit-status
+        if: always()
+        env:
+          FOUND: ${{ steps.scan.outputs.found }}
+        run: |
+          python3 - <<'PYEOF'
+          import json, os
+
+          # The review-label gate renders and blocks critical findings. Keep
+          # this scan a fact-finder so adding ci-reviewed can rerun the gate
+          # without requiring the scanner itself to fail again.
+          status = []
+
+          with open(os.environ["GITHUB_OUTPUT"], "a", encoding="utf-8") as f:
+              f.write(f"review_status={json.dumps(status)}\n")
+          PYEOF
+
+
+  dep-bounds:
+    name: Check PyPI dependency upper bounds
+    if: inputs.deps
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    outputs:
+      review_status: ${{ steps.emit-status.outputs.review_status }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        with:
+          fetch-depth: 0
+
+      - name: Check for unbounded PyPI deps
+        id: bounds
+        run: |
+          set -euo pipefail
+
+          BASE="${{ github.event.pull_request.base.sha }}"
+          HEAD="${{ github.event.pull_request.head.sha }}"
+
+          # Only check added lines in pyproject.toml
+          ADDED=$(git diff "$BASE"..."$HEAD" -- pyproject.toml | grep '^+' | grep -v '^+++' || true)
+
+          if [ -z "$ADDED" ]; then
+            echo "found=false" >> "$GITHUB_OUTPUT"
+            exit 0
+          fi
+
+          # Match PyPI dep specs that have >= and no < ceiling.
+          # Pattern: "package>=version" without a following ",<" bound.
+          # Excludes git+ URLs (which use commit SHAs) and comments.
+          UNBOUNDED=$(echo "$ADDED" | grep -oE '"[a-zA-Z0-9_-]+(\[[^\]]*\])?>=[ 0-9.]+"' | grep -v ',<' || true)
+
+          if [ -n "$UNBOUNDED" ]; then
+            echo "found=true" >> "$GITHUB_OUTPUT"
+            echo "$UNBOUNDED" > /tmp/unbounded.txt
+          else
+            echo "found=false" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Emit review_status
+        id: emit-status
+        if: always()
+        env:
+          FOUND: ${{ steps.bounds.outputs.found }}
+        run: |
+          python3 - <<'PYEOF'
+          import json, os
+
+          found = os.environ.get("FOUND", "") == "true"
+
+          if found:
+              with open("/tmp/unbounded.txt", encoding="utf-8") as f:
+                  detail = f.read()
+              status = [{
+                  "source": "supply chain",
+                  "results": [{
+                      "kind": "action_required",
+                      "title": "Unbounded PyPI dependencies",
+                      "summary": "This PR adds PyPI dependencies without upper bounds.",
+                      "detail": detail,
+                      "how_to_fix": 'Add a `<next_major` upper bound, e.g. `"package>=1.2.0,<2"`. See CONTRIBUTING.md dependency pinning policy.'
+                  }]
+              }]
+          else:
+              status = []
+
+          with open(os.environ["GITHUB_OUTPUT"], "a", encoding="utf-8") as f:
+              f.write(f"review_status={json.dumps(status)}\n")
+          PYEOF
+
+      - name: Fail on unbounded deps
+        if: steps.bounds.outputs.found == 'true'
+        run: |
+          echo "::error::PyPI dependencies without upper bounds detected. Add <next_major ceiling per CONTRIBUTING.md policy."
+          exit 1
+
+  aggregate:
+    name: Aggregate review statuses
+    needs: [scan, dep-bounds]
+    if: always()
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    outputs:
+      review_status: ${{ steps.merge.outputs.review_status }}
+      critical_findings: ${{ steps.merge.outputs.critical_findings }}
+    steps:
+      - name: Merge review statuses
+        id: merge
+        env:
+          SCAN_STATUS: ${{ needs.scan.outputs.review_status }}
+          DEP_STATUS: ${{ needs.dep-bounds.outputs.review_status }}
+          CRITICAL_FINDINGS: ${{ needs.scan.outputs.critical_findings }}
+        run: |
+          python3 - <<'PYEOF'
+          import json, os
+
+          merged = []
+          for key in ("SCAN_STATUS", "DEP_STATUS"):
+              raw = os.environ.get(key, "")
+              if not raw:
+                  continue
+              try:
+                  data = json.loads(raw)
+              except (json.JSONDecodeError, TypeError):
+                  continue
+              if isinstance(data, list):
+                  merged.extend(data)
+
+          with open(os.environ["GITHUB_OUTPUT"], "a", encoding="utf-8") as f:
+              f.write(f"review_status={json.dumps(merged)}\n")
+              f.write("critical_findings=" + os.environ.get("CRITICAL_FINDINGS", "false") + "\n")
+
+          # Write review-status.json for the live comment poller artifact.
+          with open("review-status.json", "w", encoding="utf-8") as f:
+              f.write(f"review_status={json.dumps(merged)}\n")
+          PYEOF
+
+      - name: Upload review status artifact
+        if: always() && steps.merge.outcome != 'skipped'
+        continue-on-error: true
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: review-status-supply-chain
+          path: review-status.json
+          retention-days: 1
+          overwrite: true
+          if-no-files-found: ignore

.github/workflows/tests-os.yml

@@ -0,0 +1,181 @@
+name: OS-specific tests
+
+# Runs the tests that can only be trusted on their own host OS.
+#
+# The main Python suite (.github/workflows/tests.yml) runs on
+# ubuntu-latest and covers everything that is either platform-agnostic or
+# genuinely Linux-specific. Tests whose subject is macOS- or
+# Windows-specific behaviour carry a marker (see the ``_OS_MARKS`` block
+# comment in tests/conftest.py) and are SKIPPED on Linux, because faking
+# ``sys.platform`` on a Linux runner selects the branch under test without
+# reproducing any of the OS behaviour that branch exists for. This workflow
+# is where those markers actually execute:
+#
+#   macos    → ``-m macos_only``     on macos-latest
+#   windows  → ``-m windows_only``   on windows-latest
+#
+# Deliberately NOT sliced. The marked set is small (tens of tests, not
+# thousands), so one plain ``pytest`` process per OS is both faster and far
+# less machinery than the per-file parallel runner the Linux lane uses.
+# If either lane grows past its timeout, that is the signal to reach for
+# scripts/run_tests.sh here too.
+#
+# Each lane FAILS when it selects zero tests (pytest exit code 5). Without
+# that guard, a renamed marker or a bad selector would report a green job
+# that ran nothing — the exact silent-coverage-loss failure this workflow
+# exists to prevent.
+
+on:
+  workflow_call:
+    inputs:
+      desktop_updater:
+        description: >-
+          Run the Windows desktop-update hand-off integration tests
+          (tests/test_desktop_update_windows_*.py). These spawn the real
+          scripts/desktop-update/windows.ps1 and poll its loopback server, so
+          they carry process-timing noise a shared runner amplifies; the
+          caller gates them on the classifier's desktop_updater lane so a PR
+          that never touched that surface cannot be failed by it. Push /
+          dispatch runs fail open (classifier sets every lane true).
+        type: boolean
+        required: false
+        default: true
+
+permissions:
+  contents: read
+
+concurrency:
+  group: tests-os-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  os-tests:
+    name: ${{ matrix.name }}
+    runs-on: ${{ matrix.runner }}
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - name: macOS-only tests
+            runner: macos-latest
+            marker: macos_only
+          - name: Windows-only tests
+            runner: windows-latest-32-core
+            marker: windows_only
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # 8.2.0
+        with:
+          # Pinned for the same reason as the Linux lane: unpinned, setup-uv
+          # resolves "latest" by fetching a manifest on every job and a
+          # transient fetch failure fails the whole job.
+          version: "0.9.28"
+          enable-cache: true
+          cache-dependency-glob: |
+            pyproject.toml
+            uv.lock
+
+      - name: Set up Python 3.11
+        uses: ./.github/actions/retry
+        with:
+          command: uv python install 3.11
+
+      - name: Install dependencies
+        # Same extras as the Linux test lane so an OS-marked test can import
+        # anything its Linux siblings can. ``[all]`` is deliberately
+        # Windows/macOS-installable (see the policy comment on the extra in
+        # pyproject.toml — matrix/python-olm was removed from it precisely
+        # because it could not build here).
+        uses: ./.github/actions/retry
+        with:
+          command: uv sync --locked --python 3.11 --extra all --extra dev --extra anthropic --extra mistral --extra fal --extra modal --extra daytona --extra hindsight --extra parallel-web
+
+      - name: Minimize uv cache
+        run: uv cache prune --ci
+
+      - name: Run ${{ matrix.marker }} tests
+        # Two-step selection:
+        #
+        #   1. scripts/ci/list_os_marked_tests.py narrows WHICH FILES are
+        #      imported. ``-m`` filters after collection, and collection
+        #      imports every module under tests/ — on this host that would
+        #      drag ~900 unrelated test modules through import, where a
+        #      single unrelated ImportError would fail a job whose own
+        #      subject is fine. The helper exits non-zero if the marker
+        #      matches no file at all.
+        #   2. ``-m`` decides WHICH TESTS run, and stays authoritative.
+        #      Passing it on the command line REPLACES pyproject's
+        #      ``-m 'not integration'`` addopts (same option, last wins) —
+        #      hence repeating ``not integration``, or the integration
+        #      suite would return through the side door.
+        #
+        # ``--timeout-method`` needs no override: tests/conftest.py's
+        # pytest_configure already downgrades the signal-based timer on
+        # Windows, which has no SIGALRM.
+        shell: bash
+        run: |
+          set -uo pipefail
+
+          LIST="${RUNNER_TEMP:-.}/selected-tests.txt"
+
+          # Process substitution would hide the helper's exit status, so write
+          # to a file and check it explicitly.
+          if ! uv run --no-sync python scripts/ci/list_os_marked_tests.py \
+                 "${{ matrix.marker }}" > "$LIST"; then
+            echo "::error::could not enumerate ${{ matrix.marker }} test files"
+            exit 1
+          fi
+          if [ ! -s "$LIST" ]; then
+            echo "::error::empty ${{ matrix.marker }} file list"
+            exit 1
+          fi
+
+          # Deliberately NOT `mapfile`: that is a bash 4 builtin and the macOS
+          # runner's /bin/bash is 3.2. Word-splitting is safe here because the
+          # helper emits repo-relative test paths, which contain no spaces.
+          # shellcheck disable=SC2046
+          set -- $(cat "$LIST")
+          echo "selected $# file(s) for ${{ matrix.marker }}:"
+          cat "$LIST"
+
+          # ``shell: bash`` runs this script with ``-e`` injected, which
+          # ``set -uo pipefail`` above does not clear. A bare pytest call
+          # would therefore abort the script on any non-zero exit and the
+          # exit-5 branch below would be unreachable dead code — the job
+          # would still fail red, but the diagnostic would never print.
+          # Desktop-update hand-off integration tests spawn the real
+          # windows.ps1; deselect them unless the PR touched that surface
+          # (see the workflow_call input). ``--ignore-glob`` keeps the file
+          # list above intact, so a renamed test file still trips the
+          # zero-tests guard rather than silently vanishing.
+          # (bash 3.2 on the macOS runner: an empty array under ``set -u`` is
+          # an unbound-variable error, hence the ``${arr[@]+...}`` idiom.)
+          EXTRA_ARGS=()
+          if [ "${{ inputs.desktop_updater }}" != "true" ]; then
+            echo "desktop_updater lane off: skipping tests/test_desktop_update_windows_*.py"
+            EXTRA_ARGS+=(--ignore-glob='*test_desktop_update_windows_*.py')
+          fi
+
+          status=0
+          uv run --no-sync python -m pytest \
+            "$@" \
+            ${EXTRA_ARGS[@]+"${EXTRA_ARGS[@]}"} \
+            -m "${{ matrix.marker }} and not integration" \
+            -v --tb=short || status=$?
+          if [ "$status" -eq 5 ]; then
+            echo "::error::No tests matched -m ${{ matrix.marker }}. Either the" \
+                 "marker was renamed/dropped or selection is broken — this job" \
+                 "must never pass without running its OS's tests."
+            exit 1
+          fi
+          exit "$status"
+        env:
+          # Belt-and-suspenders with tests/conftest.py's env blanking: no
+          # test may reach a real provider API.
+          OPENROUTER_API_KEY: ""
+          OPENAI_API_KEY: ""
+          NOUS_API_KEY: ""

.github/workflows/tests.yml

@@ -0,0 +1,196 @@
+name: Tests
+
+on:
+  workflow_call:
+
+permissions:
+  contents: read
+
+# Cancel in-progress runs for the same ref
+concurrency:
+  group: tests-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    name: Run tests
+    # One 96-core runner for the whole suite. There is no slicing. Slicing
+    # existed to spread the suite over 4-core runners. It cost a matrix job, a
+    # duration cache, a per-slice artifact and a merge job to do it.
+    #
+    # 96 cores clear the floor that the slowest single test file sets (about
+    # 82s). A second slice divides work that is already at that floor, and
+    # adds a second setup.
+    runs-on: ubuntu-latest-96-core
+    timeout-minutes: 30
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Install ripgrep (prebuilt binary)
+        run: |
+          set -euo pipefail
+          RG_VERSION=15.1.0
+          RG_SHA256=1c9297be4a084eea7ecaedf93eb03d058d6faae29bbc57ecdaf5063921491599
+          RG_TARBALL=ripgrep-${RG_VERSION}-x86_64-unknown-linux-musl.tar.gz
+          curl -sSfL --retry 3 --retry-delay 5 -o "$RG_TARBALL" \
+            "https://github.com/BurntSushi/ripgrep/releases/download/${RG_VERSION}/${RG_TARBALL}"
+          echo "${RG_SHA256}  ${RG_TARBALL}" | sha256sum -c -
+          tar -xzf "$RG_TARBALL"
+          sudo mv "ripgrep-${RG_VERSION}-x86_64-unknown-linux-musl/rg" /usr/local/bin/rg
+          rm -rf "$RG_TARBALL" "ripgrep-${RG_VERSION}-x86_64-unknown-linux-musl"
+          rg --version
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # 8.2.0
+        with:
+          # Pin the uv version: unpinned, setup-uv resolves "latest" by
+          # fetching a manifest from raw.githubusercontent.com on EVERY job —
+          # a transient fetch failure fails the whole job (2026-07-28 slice-5
+          # incident). Pinned, the binary downloads directly; no manifest hop.
+          version: "0.9.28"
+          # Persist uv's download/wheel cache (~/.cache/uv) across runs.
+          # Keyed on the dependency manifests, so the cache is reused until
+          # pyproject.toml or uv.lock changes. `uv sync` still runs every
+          # time, but resolves from the warm cache instead of re-downloading
+          # and re-building wheels.
+          enable-cache: true
+          cache-dependency-glob: |
+            pyproject.toml
+            uv.lock
+
+      - name: Set up Python 3.11
+        uses: ./.github/actions/retry
+        with:
+          command: uv python install 3.11
+
+      - name: Install dependencies
+        # `uv sync --locked` installs the exact pinned set from uv.lock (and
+        # fails if the lock is out of sync with pyproject.toml), giving a
+        # reproducible env. It also creates .venv itself, so no separate
+        # `uv venv` step is needed.
+        #
+        # The trailing extras beyond all/dev are the lazy-install features
+        # (tools/lazy_deps.py) that tests exercise for real: provider.anthropic,
+        # stt/tts.mistral, image.fal, terminal.modal, terminal.daytona,
+        # memory.hindsight, search.parallel. The hermetic test env forbids
+        # mid-run pip installs (HERMES_DISABLE_LAZY_INSTALLS=1 in
+        # tests/conftest.py), so the SDKs those tests need must be in the
+        # venv up front — resolved from uv.lock like everything else, which
+        # also honors the exact supply-chain pins these extras carry.
+        uses: ./.github/actions/retry
+        with:
+          command: uv sync --locked --python 3.11 --extra all --extra dev --extra anthropic --extra mistral --extra fal --extra modal --extra daytona --extra hindsight --extra parallel-web
+
+      - name: Minimize uv cache
+        # Optimized for CI: prunes pre-built wheels that are cheap to
+        # re-download, keeping the persisted cache small and fast to restore.
+        run: uv cache prune --ci
+
+      - name: Run tests
+        # Per-file isolation via scripts/run_tests.sh: each test file runs
+        # in its own freshly-spawned `python -m pytest <file>` subprocess
+        # with bounded parallelism. No xdist, no shared workers, no
+        # module-level state leakage between files.
+        #
+        # No --files: the runner discovers the suite itself. The discovered
+        # set is identical to the list the removed matrix job used to pass in.
+        run: |
+          source .venv/bin/activate
+          scripts/run_tests.sh
+        env:
+          # This is the maximum number of test FILES that run together.
+          # run_tests_parallel.py starts one pytest subprocess for each file
+          # from a single ThreadPoolExecutor, so this value IS the limit. The
+          # default is cpu_count*2, which is 192 here.
+          #
+          # Measured on this runner (96-core EPYC 7763, 377GB). Whole suite,
+          # two repetitions for each value. See run 32549672063:
+          #
+          #     workers   x cores   mean
+          #        48       0.5x    138s
+          #        96       1.0x    126s   <- fastest
+          #       144       1.5x    132s
+          #       192       2.0x    132s
+          #       240       2.5x    140s
+          #       288       3.0x    142s
+          #
+          # One worker for each core wins. The curve is shallow: 126s to 142s
+          # across a 6x range. The suite has sufficient concurrency at this
+          # size. The remaining time is the slowest files plus the setup.
+          # Workers above the core count only add contention.
+          HERMES_TEST_WORKERS: 96
+          # Ensure tests don't accidentally call real APIs
+          OPENROUTER_API_KEY: ""
+          OPENAI_API_KEY: ""
+          NOUS_API_KEY: ""
+
+  e2e:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Install ripgrep (prebuilt binary)
+        run: |
+          set -euo pipefail
+          RG_VERSION=15.1.0
+          RG_SHA256=1c9297be4a084eea7ecaedf93eb03d058d6faae29bbc57ecdaf5063921491599
+          RG_TARBALL=ripgrep-${RG_VERSION}-x86_64-unknown-linux-musl.tar.gz
+          curl -sSfL --retry 3 --retry-delay 5 -o "$RG_TARBALL" \
+            "https://github.com/BurntSushi/ripgrep/releases/download/${RG_VERSION}/${RG_TARBALL}"
+          echo "${RG_SHA256}  ${RG_TARBALL}" | sha256sum -c -
+          tar -xzf "$RG_TARBALL"
+          sudo mv "ripgrep-${RG_VERSION}-x86_64-unknown-linux-musl/rg" /usr/local/bin/rg
+          rm -rf "$RG_TARBALL" "ripgrep-${RG_VERSION}-x86_64-unknown-linux-musl"
+          rg --version
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # 8.2.0
+        with:
+          # Pin the uv version: unpinned, setup-uv resolves "latest" by
+          # fetching a manifest from raw.githubusercontent.com on EVERY job —
+          # a transient fetch failure fails the whole job (2026-07-28 slice-5
+          # incident). Pinned, the binary downloads directly; no manifest hop.
+          version: "0.9.28"
+          # Persist uv's download/wheel cache (~/.cache/uv) across runs.
+          # Keyed on the dependency manifests, so the cache is reused until
+          # pyproject.toml or uv.lock changes. `uv sync` still runs every
+          # time, but resolves from the warm cache instead of re-downloading
+          # and re-building wheels.
+          enable-cache: true
+          cache-dependency-glob: |
+            pyproject.toml
+            uv.lock
+
+      - name: Set up Python 3.11
+        run: uv python install 3.11
+
+      - name: Install dependencies
+        # `uv sync --locked` installs the exact pinned set from uv.lock (and
+        # fails if the lock is out of sync with pyproject.toml), giving a
+        # reproducible env. It also creates .venv itself, so no separate
+        # `uv venv` step is needed.
+        #
+        # Same extras as the test job's sync above: the hermetic test env
+        # forbids mid-run pip installs (HERMES_DISABLE_LAZY_INSTALLS=1 in
+        # tests/conftest.py), so lazy-install SDKs exercised by tests must be
+        # in the venv up front.
+        uses: ./.github/actions/retry
+        with:
+          command: uv sync --locked --python 3.11 --extra all --extra dev --extra anthropic --extra mistral --extra fal --extra modal --extra daytona --extra hindsight --extra parallel-web
+
+      - name: Minimize uv cache
+        # Optimized for CI: prunes pre-built wheels that are cheap to
+        # re-download, keeping the persisted cache small and fast to restore.
+        run: uv cache prune --ci
+
+      - name: Run e2e tests
+        run: |
+          source .venv/bin/activate
+          python -m pytest tests/e2e/ -v --tb=short
+        env:
+          OPENROUTER_API_KEY: ""
+          OPENAI_API_KEY: ""
+          NOUS_API_KEY: ""

.github/workflows/uv-lockfile-check.yml

@@ -0,0 +1,180 @@
+name: uv.lock check
+
+# Verify uv.lock is in sync with pyproject.toml.  Blocking check — PRs
+# that modify pyproject.toml without regenerating uv.lock (or vice versa)
+# must not merge, because the Docker build's `uv sync --frozen` step will
+# fail on a stale lockfile and we'd rather catch it here than in the
+# docker workflow on main.
+#
+# ─────────────────────────────────────────────────────────────────────────
+# IMPORTANT: this check runs against the MERGED state, not just your branch
+# ─────────────────────────────────────────────────────────────────────────
+#
+# For `pull_request` events, GitHub checks out `refs/pull/<N>/merge` by
+# default — a synthetic commit that merges your PR branch into the CURRENT
+# state of `main`.  That means the pyproject.toml evaluated here is
+# `main's pyproject.toml + your PR's changes to pyproject.toml`, not just
+# what's on your branch.
+#
+# Failure mode this creates: if `main` has advanced since you branched
+# (e.g. someone merged a PR that added a dep to pyproject.toml + its
+# corresponding uv.lock entries), your branch's uv.lock is missing those
+# new entries.  `uv lock --check` resolves against the merged pyproject
+# and sees a lockfile that doesn't cover all the current deps → fails
+# with "The lockfile at uv.lock needs to be updated."
+#
+# This can be confusing: `uv lock --check` passes locally (your branch
+# is internally consistent) but fails in CI (merged state isn't).
+#
+# Fix is to sync your branch with main and regenerate the lockfile:
+#
+#     git fetch origin main
+#     git rebase origin/main      # or merge, whatever the repo prefers
+#     uv lock                     # regenerates uv.lock against new pyproject.toml
+#     git add uv.lock
+#     git commit -m "chore: refresh uv.lock after rebase onto main"
+#     git push --force-with-lease # if you rebased
+#
+# If you also changed pyproject.toml in your PR, `uv lock` handles that
+# at the same time — one regeneration covers both your changes and the
+# drift from main.
+#
+# This is the correct behavior!  The check is protecting main's Docker
+# build: a post-merge build would see the same merged state and fail
+# the same way.  Better to catch it here than after merge.
+
+on:
+  workflow_call:
+    outputs:
+      review_status:
+        description: "JSON review status for the review-status aggregator"
+        value: ${{ jobs.check.outputs.review_status }}
+
+permissions:
+  contents: read
+
+concurrency:
+  group: uv-lockfile-check-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  check:
+    name: uv lock --check
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    outputs:
+      review_status: ${{ steps.verify.outputs.review_status }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # 8.2.0
+        with:
+          # Pinned: unpinned setup-uv fetches a 'latest' manifest from
+          # raw.githubusercontent.com every job; transient fetch failures
+          # fail the job (2026-07-28 incident). Keep in sync with tests.yml.
+          version: "0.9.28"
+
+      # `uv lock --check` re-resolves the project from pyproject.toml and
+      # compares the result to uv.lock, exiting non-zero if they disagree.
+      # No network writes, no file modifications.
+      #
+      # On PRs this runs against the merge commit (see comment at the top
+      # of this file) — failures often mean "your branch is behind main,
+      # rebase and regenerate uv.lock."
+      - name: Verify uv.lock is up-to-date
+        id: verify
+        run: |
+          # uv lock --check re-resolves against PyPI (network). Retry so a
+          # registry blip doesn't read as "lockfile stale". A genuinely stale
+          # lockfile fails all attempts (deterministic), costing only seconds.
+          #
+          # Backoff rather than a flat 10s: three attempts inside ~20s all
+          # land in the same blip. 5/15/45s spans ~65s instead.
+          #
+          # Network failure and a real desync are also reported differently.
+          # uv says "Request failed after N retries" when it can't reach the
+          # registry, versus "lockfile needs to be updated" when the lock is
+          # genuinely stale. Only the second is the contributor's to fix, so
+          # an unreachable registry says so instead of sending them to
+          # `uv lock` with nothing to regenerate.
+          ok=false
+          net_fail=false
+          delays=(5 15 45)
+          for i in 1 2 3; do
+            if uv lock --check >lock-check.log 2>&1; then
+              ok=true
+              net_fail=false
+              cat lock-check.log
+              break
+            fi
+            cat lock-check.log
+            if grep -qiE "Request failed after|Failed to fetch|error sending request|connection (reset|closed)|timed out" lock-check.log; then
+              net_fail=true
+            else
+              # Deterministic failure (a real desync) — retrying just prints
+              # the same error twice more.
+              net_fail=false
+              break
+            fi
+            [ "$i" = 3 ] && break
+            echo "::warning::uv lock --check could not reach the registry (attempt $i); retrying in ${delays[$((i-1))]}s"
+            sleep "${delays[$((i-1))]}"
+          done
+          if [ "$ok" != true ] && [ "$net_fail" = true ]; then
+            echo "::error title=uv.lock check could not reach PyPI::Registry unreachable after 3 attempts — infrastructure failure, not a stale lockfile. Re-run the job."
+            review_status='[{"source":"uv.lock check","results":[{"kind":"action_required","title":"uv.lock check could not reach PyPI","summary":"`uv lock --check` could not reach the package registry after 3 attempts. This is an infrastructure failure, not a stale lockfile.","how_to_fix":"Re-run the failed job. No change to `uv.lock` is needed."}]}]'
+            echo "review_status=${review_status}" >> "$GITHUB_OUTPUT"
+            echo "review_status=${review_status}" > review-status.json
+            exit 1
+          fi
+          if [ "$ok" != true ]; then
+            cat <<'EOF' >> "$GITHUB_STEP_SUMMARY"
+          ## ❌ uv.lock is out of sync with pyproject.toml
+
+          **If this is a PR:** this check runs against the merged state
+          (your branch + current `main`), not just your branch.  If
+          `uv lock --check` passes locally, your branch is likely behind
+          `main` — recent changes to `pyproject.toml` on `main` aren't
+          reflected in your branch's `uv.lock` yet.
+
+          To fix, sync with main and regenerate the lockfile:
+
+          ```bash
+          git fetch origin main
+          git rebase origin/main   # or `git merge origin/main`
+          uv lock                  # regenerate against new pyproject.toml
+          git add uv.lock
+          git commit -m "chore: refresh uv.lock after syncing with main"
+          git push --force-with-lease  # drop --force-with-lease if you merged
+          ```
+
+          **If you only changed pyproject.toml:** run `uv lock` locally
+          and commit the result.
+
+          This check is blocking because the Docker image build uses
+          `uv sync --frozen --extra all`, which rejects stale lockfiles
+          — catching it here avoids a ~15 min failed docker run
+          on `main` post-merge.
+          EOF
+            echo "::error title=uv.lock out of sync::Run \`uv lock\` locally and commit the result. If on a PR, sync with main first."
+            review_status='[{"source":"uv.lock check","results":[{"kind":"action_required","title":"uv.lock out of sync","summary":"uv.lock is out of sync with pyproject.toml.","how_to_fix":"Run `uv lock` locally and commit the result. If on a PR, sync with main first:\n```\ngit fetch origin main\ngit rebase origin/main\nuv lock\ngit add uv.lock\ngit commit -m \"chore: refresh uv.lock\"\n```\n"}]}]'
+            echo "review_status=${review_status}" >> "$GITHUB_OUTPUT"
+            echo "review_status=${review_status}" > review-status.json
+            exit 1
+          fi
+          review_status='[]'
+          echo "review_status=${review_status}" >> "$GITHUB_OUTPUT"
+          echo "review_status=${review_status}" > review-status.json
+
+      - name: Upload review status artifact
+        if: always() && steps.verify.outcome != 'skipped'
+        continue-on-error: true
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: review-status-uv-lockfile
+          path: review-status.json
+          retention-days: 1
+          overwrite: true
+          if-no-files-found: ignore

.github/workflows/windows-venv-e2e.yml

@@ -0,0 +1,80 @@
+name: Windows venv-holder live E2E
+
+# ON-DEMAND ONLY (fleet-update #91277, venv-holder consolidation work).
+#
+# Runs the live venv-holder E2E suite on a real windows-latest runner:
+# spawns actual processes with realistic Hermes argv shapes and drives the
+# REAL detection/classification/exemption code against the live process
+# table — the coverage that cannot exist on the Linux lanes and that the
+# maintainer cannot exercise locally before the work reaches main.
+#
+# Deliberately NOT wired to pull_request/main: it fires only on pushes to
+# wine2e/** working branches, so it costs nothing on normal PRs. Delete or
+# keep dormant after the venv-holder work lands.
+
+on:
+  push:
+    branches:
+      - "wine2e/**"
+
+permissions:
+  contents: read
+
+concurrency:
+  group: windows-venv-e2e-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  venv-holder-e2e:
+    name: venv-holder live E2E (windows-latest)
+    runs-on: windows-latest
+    timeout-minutes: 25
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@fac544c07dec837d0ccb6301d7b5580bf5edae39 # 8.2.0
+        with:
+          version: "0.9.28"
+          enable-cache: true
+          cache-dependency-glob: |
+            pyproject.toml
+            uv.lock
+
+      - name: Set up Python 3.11
+        uses: ./.github/actions/retry
+        with:
+          command: uv python install 3.11
+
+      - name: Install dependencies
+        uses: ./.github/actions/retry
+        with:
+          command: uv sync --locked --python 3.11 --extra dev --extra messaging
+
+      - name: Run venv-holder live E2E
+        shell: bash
+        run: |
+          set -uo pipefail
+          uv run --no-sync python -m pytest \
+            tests/hermes_cli/test_venv_holder_windows_live.py \
+            tests/hermes_cli/test_taskkill_identity_windows_live.py \
+            tests/hermes_cli/test_git_trampoline_windows_live.py \
+            "tests/hermes_cli/test_managed_uv.py::TestWindowsRuntimeSelfLock" \
+            -o addopts= -v -p no:cacheprovider
+
+      - name: Run Telegram CLOSE-WAIT reconnect live E2E (#87057)
+        shell: bash
+        run: |
+          set -uo pipefail
+          uv run --no-sync python -m pytest \
+            tests/gateway/test_telegram_closewait_windows_live.py \
+            -o addopts= -v -p no:cacheprovider
+
+      - name: Run background-executor spawn parity live E2E (#70716)
+        shell: bash
+        run: |
+          set -uo pipefail
+          uv run --no-sync python -m pytest \
+            tests/tools/test_process_registry_windows_live.py \
+            -o addopts= -v -p no:cacheprovider

.gitignore

@@ -0,0 +1,222 @@
+.DS_Store
+/venv/
+/venv.old/
+/venv.stale.runtime-*/
+/bin/
+/.hermes-runtime/
+/_pycache/
+*.pyc*
+__pycache__/
+act/
+.act-sandbox-agent.*
+.venv/
+.venv
+.vscode/
+.env
+.op.env
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+.env.development
+.env.test
+.hermes-docker/
+.notebooklm-home/
+.notebooklm-cli-venv/
+.notebooklm-playwright/
+.pip-cache/
+.uv-cache/
+compose.hermes.local.yml
+export*
+__pycache__/model_tools.cpython-310.pyc
+__pycache__/web_tools.cpython-310.pyc
+logs/
+data/
+# Bundled community plugin index seed (shipped as package data) — the bare
+# `data/` pattern above would otherwise swallow it.
+!hermes_cli/data/
+!hermes_cli/data/plugin_index.json
+.pytest_cache/
+test_durations.json
+.pytest-cache/
+tmp/
+temp_vision_images/
+hermes-*/*
+examples/
+tests/quick_test_dataset.jsonl
+tests/sample_dataset.jsonl
+run_datagen_kimik2-thinking.sh
+run_datagen_megascience_glm4-6.sh
+run_datagen_sonnet.sh
+source-data/*
+run_datagen_megascience_glm4-6.sh
+data/*
+# No trailing slash: also matches node_modules SYMLINKS (worktrees often
+# symlink node_modules to the main checkout; the dir-only pattern let one
+# slip into a commit and break `npm ci` on CI with ENOTDIR).
+node_modules
+browser-use/
+agent-browser/
+# Private keys
+*.ppk
+*.pem
+privvy*
+images/
+__pycache__/
+hermes_agent.egg-info/
+wandb/
+testlogs
+playwright-report/
+test-results/
+# Playwright visual regression baselines — cached from main in CI, not committed
+*-snapshots/
+
+# CLI config (may contain sensitive SSH paths)
+cli-config.yaml
+
+# Skills Hub state (lives in ~/.hermes/skills/.hub/ at runtime, but just in case)
+skills/.hub/
+ignored/
+.worktrees/
+environments/benchmarks/evals/
+
+# Web UI build output
+hermes_cli/web_dist/
+# Cross-process web UI build lock (flock target, always empty)
+.web_ui_build.lock
+apps/desktop/build/
+apps/desktop/dist/
+
+# tsc-emitted artifacts (a stray `tsc -b` compiles into src/, and vite then
+# resolves the stale .js OVER the .tsx — never track these)
+apps/desktop/src/**/*.js
+apps/desktop/src/**/*.js.map
+apps/desktop/src/**/*.d.ts
+# EXCEPT bundled plain-ESM plugin entries (adopted SDK-consumer plugins,
+# e.g. hermes-bots): plugin.js IS the source, not tsc output. No .tsx
+# sibling exists, so the stale-shadow hazard above cannot apply.
+!apps/desktop/src/plugins/*/plugin.js
+!apps/desktop/src/global.d.ts
+!apps/desktop/src/vite-env.d.ts
+
+# Build/debug artifacts that must never be committed
+/log.txt
+/sqlite_leak_fix.png
+/*.png.bak
+*.tar.gz
+*.tgz
+apps/shared/src/**/*.js
+apps/shared/src/**/*.js.map
+apps/shared/src/**/*.d.ts
+apps/desktop/release/
+# stage-and-swap Desktop rebuild output (#86443); removed after the swap, but
+# a killed build must not leave the checkout dirty
+apps/desktop/.staging-*/
+*.tsbuildinfo
+
+# Web UI assets — synced from @nous-research/ui at build time via
+# `npm run sync-assets` (see web/package.json).
+web/public/fonts/
+web/public/ds-assets/
+
+# Release script temp files
+.release_notes.md
+mini-swe-agent/
+
+# Nix
+.direnv/
+.nix-stamps/
+result
+website/static/api/skills-index.json
+# skills.json + skills-meta.json are build artifacts emitted by
+# website/scripts/extract-skills.py during prebuild — keep them out of
+# git for the same reason as skills-index.json (large, generated, change
+# every build).
+website/static/api/skills.json
+website/static/api/skills-meta.json
+# automation-blueprints-index.json is a build artifact emitted by
+# website/scripts/extract-automation-blueprints.py during prebuild.
+website/static/api/automation-blueprints-index.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/*
+# Working directory for the Hermes Agent's session state (~/.hermes/ at runtime;
+# also created in-repo when an agent operates in this checkout). Plans, audit
+# logs, and per-session caches are never artifacts of the codebase.
+.hermes/
+
+# Desktop/bootstrap install marker written into the managed checkout root by the
+# bootstrap installer. It is Hermes-managed runtime state, never a code change —
+# ignore it so `hermes update`'s `git stash push --include-untracked` does not
+# treat it as a local edit and autostash it on every run (#38529).
+.hermes-bootstrap-complete
+
+# Persistent dev sandbox dir (scripts/dev-sandbox.sh --persistent)
+.hermes-sandbox/
+# Sandbox dirs used by the install/update E2E (tests/install/). The suffix is
+# the route name, so each route gets its own tree and two can run at once.
+.hermes-sandbox-e2e*/
+
+# Interrupted-update breadcrumb + recovery lock written next to the shared venv
+# by `hermes update` / launch-time self-heal. Runtime state, never a code change
+# — ignore so `git status` stays clean and update's autostash skips them.
+.update-incomplete
+.update-incomplete.lock
+
+# Checkout fingerprint the __pycache__ tree was last validated against
+# (launch-time stale-bytecode sweep). Runtime state, never a code change.
+.bytecode-fingerprint
+.bytecode-fingerprint.tmp
+
+# Installer-written method stamp in the managed checkout root (scripts/install.sh).
+# Runtime metadata only — never a code change. Ignore so `git status` stays clean
+# and `hermes update`'s untracked autostash does not treat it as a local edit (#66189 / #54855).
+/.install_method
+
+# Tool Search live-test harness output — non-deterministic model transcripts,
+# regenerated by scripts/tool_search_livetest.py. Never an artifact of the repo.
+scripts/out/
+
+# Per-release changelog drafts. These exist only transiently during a release
+# cut (passed to `gh release create --notes-file`); the GitHub Release itself
+# stores the published notes. They are not a build artifact and must never be
+# committed to the repo root. See the hermes-release skill.
+RELEASE_v*.md
+
+# Desktop demo-run scratch output (hermes writes demo/*.txt during recorded
+# walkthroughs). Throwaway artifacts, never part of the app.
+apps/desktop/demo/
+
+# PR infographics are rendered locally and embedded in PR descriptions via the
+# image-provider (fal.media) URL — they are NEVER committed to the repo. The
+# PR body is the archive. See the hermes-agent-dev skill's
+# pr-infographic-workflow reference (storage rule + lapse #8 / #COMMIT-1).
+#
+# Spelling variants are listed because a single `infographic/` pattern was
+# sidestepped by an `infograficos/` directory (#70552). .gitignore is only
+# the first line of defence and cannot stop `git add -f` at all — the
+# infographic-check CI job is what actually enforces this.
+infographic/
+infographics/
+infograficos/
+infografico/
+native/fts5_cjk/*.so
+# Runtime marker written by hermes update when a lazy dependency refresh is
+# interrupted; consumed by launch-time recovery. Never commit it (was tracked
+# by accident via 3a69e34702, removed in the #72002 salvage).
+.lazy-refresh-incomplete
+.skills_prompt_snapshot.json
+
+# Disposable profile created by scripts/probe_active_session_exclusivity.py
+.probe-home/

.hadolint.yaml

@@ -0,0 +1,36 @@
+# hadolint configuration for the Hermes Agent Dockerfile.
+# See https://github.com/hadolint/hadolint#configure for rules.
+#
+# We want hadolint to surface NEW Dockerfile lint regressions, but we
+# don't want to rewrite the existing image to silence rules that are
+# either intentional or pragmatic tradeoffs for this project. Each
+# ignore below has a one-line justification.
+failure-threshold: warning
+
+ignored:
+  # Pin versions in apt get install. We intentionally don't pin common
+  # tools (curl, git, openssh-client, etc.) — security updates flow in
+  # via the periodic base-image rebuild, and pinning would lock us to
+  # superseded patch releases. Same rationale as nearly every distro-
+  # base official image (python, node, debian).
+  - DL3008
+  # Use WORKDIR to switch to a directory. The image uses `(cd web && …)`
+  # / `(cd ../ui-tui && …)` inline subshells for one-off build steps
+  # because they don't affect later RUN commands; promoting them to
+  # full WORKDIR switches with restores would obscure intent.
+  - DL3003
+  # Multiple consecutive RUN instructions. The `touch README.md` + `uv
+  # sync` split is intentional — `touch` is cheap, `uv sync` is the
+  # expensive layer-cached step we want isolated, and merging them
+  # would invalidate the cache for trivial changes.
+  - DL3059
+  # Last USER should not be root. /init (s6-overlay) runs as root so the
+  # stage2 hook can usermod/groupmod and chown the data volume per
+  # HERMES_UID at runtime; each supervised service then drops to the
+  # hermes user via `s6-setuidgid`.
+  - DL3002
+
+# Require explicit base-image pins (SHA256) — we already do this.
+trustedRegistries:
+  - docker.io
+  - ghcr.io

.mailmap

@@ -0,0 +1,109 @@
+# .mailmap — canonical author mapping for git shortlog / git log / GitHub
+# Format: Canonical Name <canonical@email> <commit@email>
+# See: https://git-scm.com/docs/gitmailmap
+#
+# This maps commit emails to GitHub noreply addresses so that:
+# 1. `git shortlog -sn` shows deduplicated contributor counts
+# 2. GitHub's contributor graph can attribute commits correctly
+# 3. Contributors with personal/work emails get proper credit
+#
+# When adding entries: use the contributor's GitHub noreply email as canonical
+# so GitHub can link commits to their profile.
+
+# === Teknium (multiple emails) ===
+Teknium <127238744+teknium1@users.noreply.github.com> <teknium1@gmail.com>
+Teknium <127238744+teknium1@users.noreply.github.com> <teknium@nousresearch.com>
+
+# === Contributors — personal/work emails mapped to GitHub noreply ===
+# Format: Canonical Name <GH-noreply> <commit-email>
+
+# Verified via GH API email search
+kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com> <kshitijkapoorr@gmail.com>
+luyao618 <364939526@qq.com> <364939526@qq.com>
+ethernet8023 <arilotter@gmail.com> <arilotter@gmail.com>
+nicoloboschi <boschi1997@gmail.com> <boschi1997@gmail.com>
+cherifya <chef.ya@gmail.com> <chef.ya@gmail.com>
+BongSuCHOI <chlqhdtn98@gmail.com> <chlqhdtn98@gmail.com>
+dsocolobsky <dsocolobsky@gmail.com> <dsocolobsky@gmail.com>
+pefontana <fontana.pedro93@gmail.com> <fontana.pedro93@gmail.com>
+Helmi <frank@helmschrott.de> <frank@helmschrott.de>
+hata1234 <hata1234@gmail.com> <hata1234@gmail.com>
+
+# Verified via PR investigation / salvage PR bodies
+DeployFaith <agents@kylefrench.dev> <agents@kylefrench.dev>
+flobo3 <floptopbot33@gmail.com> <floptopbot33@gmail.com>
+gaixianggeng <gaixg94@gmail.com> <gaixg94@gmail.com>
+KUSH42 <xush@xush.org> <xush@xush.org>
+konsisumer <der@konsi.org> <der@konsi.org>
+WorldInnovationsDepartment <vorvul.danylo@gmail.com> <vorvul.danylo@gmail.com>
+m0n5t3r <iacobs@m0n5t3r.info> <iacobs@m0n5t3r.info>
+sprmn24 <oncuevtv@gmail.com> <oncuevtv@gmail.com>
+fancydirty <fancydirty@gmail.com> <fancydirty@gmail.com>
+fxfitz <francis.x.fitzpatrick@gmail.com> <francis.x.fitzpatrick@gmail.com>
+limars874 <limars874@gmail.com> <limars874@gmail.com>
+AaronWong1999 <aaronwong1999@icloud.com> <aaronwong1999@icloud.com>
+dippwho <dipp.who@gmail.com> <dipp.who@gmail.com>
+duerzy <duerzy@gmail.com> <duerzy@gmail.com>
+geoffwellman <geoff.wellman@gmail.com> <geoff.wellman@gmail.com>
+hcshen0111 <shenhaocheng19990111@gmail.com> <shenhaocheng19990111@gmail.com>
+jamesarch <han.shan@live.cn> <han.shan@live.cn>
+stephenschoettler <stephenschoettler@gmail.com> <stephenschoettler@gmail.com>
+Tranquil-Flow <tranquil_flow@protonmail.com> <tranquil_flow@protonmail.com>
+Dusk1e <yusufalweshdemir@gmail.com> <yusufalweshdemir@gmail.com>
+Awsh1 <ysfalweshcan@gmail.com> <ysfalweshcan@gmail.com>
+WAXLYY <ysfwaxlycan@gmail.com> <ysfwaxlycan@gmail.com>
+donrhmexe <don.rhm@gmail.com> <don.rhm@gmail.com>
+hqhq1025 <1506751656@qq.com> <1506751656@qq.com>
+BlackishGreen33 <s5460703@gmail.com> <s5460703@gmail.com>
+tomqiaozc <zqiao@microsoft.com> <zqiao@microsoft.com>
+MagicRay1217 <mingjwan@microsoft.com> <mingjwan@microsoft.com>
+aaronagent <1115117931@qq.com> <1115117931@qq.com>
+YoungYang963 <young@YoungdeMacBook-Pro.local> <young@YoungdeMacBook-Pro.local>
+LongOddCode <haolong@microsoft.com> <haolong@microsoft.com>
+Cafexss <coffeemjj@gmail.com> <coffeemjj@gmail.com>
+Cygra <sjtuwbh@gmail.com> <sjtuwbh@gmail.com>
+DomGrieco <dgrieco@redhat.com> <dgrieco@redhat.com>
+
+# Duplicate email mapping (same person, multiple emails)
+Sertug17 <104278804+Sertug17@users.noreply.github.com> <srhtsrht17@gmail.com>
+yyovil <birdiegyal@gmail.com> <tanishq231003@gmail.com>
+DomGrieco <dgrieco@redhat.com> <dgrieco@redhat.com>
+dsocolobsky <dsocolobsky@gmail.com> <dylan.socolobsky@lambdaclass.com>
+olafthiele <programming@olafthiele.com> <olafthiele@gmail.com>
+
+# Verified via git display name matching GH contributor username
+cokemine <aptx4561@gmail.com> <aptx4561@gmail.com>
+dalianmao000 <dalianmao0107@gmail.com> <dalianmao0107@gmail.com>
+emozilla <emozilla@nousresearch.com> <emozilla@nousresearch.com>
+jjovalle99 <juan.ovalle@mistral.ai> <juan.ovalle@mistral.ai>
+kagura-agent <kagura.chen28@gmail.com> <kagura.chen28@gmail.com>
+spniyant <niyant@spicefi.xyz> <niyant@spicefi.xyz>
+olafthiele <programming@olafthiele.com> <programming@olafthiele.com>
+r266-tech <r2668940489@gmail.com> <r2668940489@gmail.com>
+xingkongliang <tianliangjay@gmail.com> <tianliangjay@gmail.com>
+win4r <win4r@outlook.com> <win4r@outlook.com>
+zhouboli <zhouboli@gmail.com> <zhouboli@gmail.com>
+yongtenglei <yongtenglei@gmail.com> <yongtenglei@gmail.com>
+
+# Nous Research team
+benbarclay <ben@nousresearch.com> <ben@nousresearch.com>
+yoniebans <jonny@nousresearch.com> <jonny@nousresearch.com>
+
+# GH contributor list verified
+spideystreet <dhicham.pro@gmail.com> <dhicham.pro@gmail.com>
+dorukardahan <dorukardahan@hotmail.com> <dorukardahan@hotmail.com>
+MustafaKara7 <karamusti912@gmail.com> <karamusti912@gmail.com>
+Hmbown <hmbown@gmail.com> <hmbown@gmail.com>
+kamil-gwozdz <kamil@gwozdz.me> <kamil@gwozdz.me>
+kira-ariaki <kira@ariaki.me> <kira@ariaki.me>
+knopki <knopki@duck.com> <knopki@duck.com>
+Unayung <unayung@gmail.com> <unayung@gmail.com>
+SeeYangZhi <yangzhi.see@gmail.com> <yangzhi.see@gmail.com>
+Julientalbot <julien.talbot@ergonomia.re> <julien.talbot@ergonomia.re>
+lesterli <lisicheng168@gmail.com> <lisicheng168@gmail.com>
+JiayuuWang <jiayuw794@gmail.com> <jiayuw794@gmail.com>
+tesseracttars-creator <tesseracttars@gmail.com> <tesseracttars@gmail.com>
+xinbenlv <zzn+pa@zzn.im> <zzn+pa@zzn.im>
+SaulJWu <saul.jj.wu@gmail.com> <saul.jj.wu@gmail.com>
+angelos <angelos@oikos.lan.home.malaiwah.com> <angelos@oikos.lan.home.malaiwah.com>
+MestreY0d4-Uninter <241404605+MestreY0d4-Uninter@users.noreply.github.com> <MestreY0d4-Uninter@users.noreply.github.com>

.npmrc

@@ -0,0 +1,63 @@
+# needed to prevent bad npm that has min-release-age but not exclude
+engine-strict=true
+
+min-release-age=14
+# allow assistant-ui packages & a couple specific deps since they update a LOT.
+# remove this when we stabilize (or we haven't updated in 2 wks)
+min-release-age-exclude[]=@assistant-ui/*
+min-release-age-exclude[]=assistant-cloud
+min-release-age-exclude[]=assistant-stream
+min-release-age-exclude[]=@radix-ui/*
+min-release-age-exclude[]=radix-ui
+min-release-age-exclude[]=safe-content-frame
+
+# react-router 8.3.0 includes fixes for vulns. remove this when 8.3.0 is > 2wks old.
+min-release-age-exclude[]=react-router
+
+# eslint 10.8.0 includes fixes for vulns. remove this when 10.8.0 is > 2wks old.
+min-release-age-exclude[]=eslint
+min-release-age-exclude[]=@eslint/*
+
+# tar 7.5.21 includes fixes for vulns. remove this when 7.5.21 is > 2wks  old
+min-release-age-exclude[]=tar
+
+# concurrently 10.0.4 includes fixes for vulns. remove this when 10.0.4 is > 2wks  old
+min-release-age-exclude[]=concurrently
+
+# fast-uri 3.1.4 includes fixes for vulns. remove this when 3.1.4 is > 2wks  old
+min-release-age-exclude[]=fast-uri
+
+# minimatch 10.2.6 includes fixes for vulns. remove this when 10.2.6 is > 2wks  old
+min-release-age-exclude[]=minimatch
+
+
+# brace-expansion 5.0.9 includes fixes for vulns. remove this when 5.0.9 is > 2wks  old
+min-release-age-exclude[]=brace-expansion
+
+# js-yaml 4.3.1 includes fixes for GHSA-5p4m-2wfm-xmqj. remove when > 2wks old (rel 2026-07-31)
+min-release-age-exclude[]=js-yaml
+
+# nanoid 3.3.17 includes fixes for GHSA-2v37-7h3g-55p8. remove when > 2wks old (rel 2026-08-03)
+min-release-age-exclude[]=nanoid
+
+# mermaid 11.16.1 includes fixes for 5 GHSAs. remove when > 2wks old (rel 2026-08-04)
+min-release-age-exclude[]=mermaid
+
+# dompurify 3.4.13 includes fixes for GHSA-55q2-fjhq-7xh7. remove when > 2wks old (rel 2026-08-03)
+min-release-age-exclude[]=dompurify
+
+# vite 8.2.0 is the first release depending on rolldown >= 1.2.1, which fixes
+# a rolldown panic that breaks `npm run build` in apps/desktop
+# (rolldown/rolldown#10337 — a regression in 1.1.5, the version vite 8.1.5
+# pins as ~1.1.5). @oxc-project/types is here because rolldown 1.2.1 pins it
+# as `=0.142.0` — an exact pin, so no older release satisfies it and the age
+# gate would fail the whole install with ETARGET.
+# remove these once vite 8.2.0 is > 2wks old.
+min-release-age-exclude[]=vite
+min-release-age-exclude[]=rolldown
+min-release-age-exclude[]=@rolldown/*
+min-release-age-exclude[]=@oxc-project/types
+
+# ink needs
+min-release-age-exclude[]=lightningcss
+min-release-age-exclude[]=postcss

.nvmrc

@@ -0,0 +1 @@
+26

.prettierignore

@@ -0,0 +1,4 @@
+# Lockfiles must never be reformatted — main has a repo rule requiring
+# team approval when lockfiles change, so an autofix PR touching one
+# would hang waiting for review.
+package-lock.json

.prettierrc

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

.python-version

@@ -0,0 +1 @@
+3.11

CONTRIBUTING.es.md

@@ -0,0 +1,602 @@
+# Contribuir a Hermes Agent
+
+¡Gracias por contribuir a Hermes Agent! Esta guía cubre todo lo que necesitas: configurar tu entorno de desarrollo, entender la arquitectura, decidir qué construir y conseguir que tu PR sea aceptado.
+
+---
+
+## Prioridades de Contribución
+
+Valoramos las contribuciones en este orden:
+
+1. **Correcciones de errores** — bloqueos, comportamiento incorrecto, pérdida de datos. Siempre la máxima prioridad.
+2. **Compatibilidad entre plataformas** — macOS, diferentes distribuciones de Linux y WSL2 en Windows. Queremos que Hermes funcione en todas partes.
+3. **Fortalecimiento de seguridad** — inyección de shell, inyección de prompts, traversal de rutas, escalada de privilegios. Ver [Consideraciones de Seguridad](#consideraciones-de-seguridad).
+4. **Rendimiento y robustez** — lógica de reintento, manejo de errores, degradación elegante.
+5. **Nuevas habilidades** — pero solo las ampliamente útiles. Ver [¿Debería ser una Habilidad o una Herramienta?](#debería-ser-una-habilidad-o-una-herramienta)
+6. **Nuevas herramientas** — raramente necesarias. La mayoría de las capacidades deberían ser habilidades. Ver más abajo.
+7. **Documentación** — correcciones, aclaraciones, nuevos ejemplos.
+
+---
+
+## ¿Debería ser una Habilidad o una Herramienta?
+
+Esta es la pregunta más común para los nuevos colaboradores. La respuesta casi siempre es **habilidad**.
+
+### Hazlo una Habilidad cuando:
+
+- La capacidad se puede expresar como instrucciones + comandos de shell + herramientas existentes
+- Envuelve una CLI externa o API que el agente puede llamar a través de `terminal` o `web_extract`
+- No necesita integración personalizada de Python ni gestión de claves API integrada en el agente
+- Ejemplos: búsqueda en arXiv, flujos de trabajo de git, gestión de Docker, procesamiento de PDF, email a través de herramientas CLI
+
+### Hazlo una Herramienta cuando:
+
+- Requiere integración de extremo a extremo con claves API, flujos de autenticación o configuración de múltiples componentes gestionada por el harness del agente
+- Necesita lógica de procesamiento personalizada que debe ejecutarse con precisión en cada ocasión (no "mejor esfuerzo" de la interpretación del LLM)
+- Maneja datos binarios, streaming o eventos en tiempo real que no pueden pasar por el terminal
+- Ejemplos: automatización de navegador (gestión de sesiones Browserbase), TTS (codificación de audio + entrega en plataforma), análisis de visión (manejo de imágenes base64)
+
+### ¿Debería la Habilidad estar incluida?
+
+Las habilidades incluidas (en `skills/`) se envían con cada instalación de Hermes. Deben ser **ampliamente útiles para la mayoría de los usuarios**:
+
+- Manejo de documentos, investigación web, flujos de trabajo de desarrollo comunes, administración de sistemas
+- Usadas regularmente por una amplia gama de personas
+
+Si tu habilidad es oficial y útil pero no universalmente necesaria (ej., una integración de servicio de pago, una dependencia pesada), ponla en **`optional-skills/`** — se envía con el repositorio pero no está activada por defecto. Los usuarios pueden descubrirla a través de `hermes skills browse` (etiquetada como "oficial") e instalarla con `hermes skills install` (sin advertencia de terceros, confianza integrada).
+
+Si tu habilidad es especializada, contribuida por la comunidad o de nicho, es mejor para un **Skills Hub** — súbela a un registro de habilidades y compártela en el [Discord de Nous Research](https://discord.gg/NousResearch). Los usuarios pueden instalarla con `hermes skills install`.
+
+---
+
+## Proveedores de Memoria: Publicar como Plugin Independiente
+
+**Ya no aceptamos nuevos proveedores de memoria en este repositorio.** El conjunto de proveedores integrados en `plugins/memory/` (honcho, mem0, supermemory, byterover, hindsight, holographic, openviking, retaindb) está cerrado. Si quieres añadir un nuevo backend de memoria, publícalo como un **repositorio de plugin independiente** que los usuarios instalen en `~/.hermes/plugins/` (o a través de un entry point de pip).
+
+Los plugins de memoria independientes:
+
+- Implementan el mismo ABC `MemoryProvider` (`agent/memory_provider.py`) — `sync_turn`, `prefetch`, `shutdown` y opcionalmente `post_setup(hermes_home, config)` para integración con el asistente de configuración
+- Usan el mismo sistema de descubrimiento — `discover_memory_providers()` los recoge desde directorios de plugins de usuario/proyecto y entry points de pip
+- Se integran con `hermes memory setup` a través de `post_setup()` — sin necesidad de tocar el código base
+- Pueden registrar sus propios subcomandos CLI a través de `register_cli(subparser)` en un archivo `cli.py`
+- Obtienen todos los mismos hooks de ciclo de vida y plomería de configuración que los proveedores incluidos en el árbol
+
+Los PRs que añadan un nuevo directorio bajo `plugins/memory/` serán cerrados con un puntero para publicar el proveedor como su propio repositorio. Los proveedores en árbol existentes se mantienen; las correcciones de errores para ellos son bienvenidas.
+
+Esto no es una barra de calidad — es una decisión de acoplamiento y mantenimiento. Los proveedores de memoria son el tipo de plugin más común y no deberían vivir todos en este árbol.
+
+---
+
+## Configuración del Desarrollo
+
+### Prerequisitos
+
+| Requisito | Notas |
+|-----------|-------|
+| **Git** | Con la extensión `git-lfs` instalada |
+| **Python 3.11–3.13** | uv lo instalará si falta |
+| **uv** | Gestor de paquetes Python rápido ([instalar](https://docs.astral.sh/uv/)) |
+| **Node.js 20+** | Opcional — necesario para herramientas de navegador y puente WhatsApp (coincide con los engines de `package.json` raíz) |
+
+### Clonar e instalar
+
+```bash
+git clone https://github.com/NousResearch/hermes-agent.git
+cd hermes-agent
+
+# Crear venv con Python 3.11
+uv venv venv --python 3.11
+export VIRTUAL_ENV="$(pwd)/venv"
+
+# Instalar con todos los extras (mensajería, cron, menús CLI, herramientas de desarrollo)
+uv pip install -e ".[all,dev]"
+
+# Opcional: herramientas de navegador
+npm install
+```
+
+### Configurar para desarrollo
+
+```bash
+mkdir -p ~/.hermes/{cron,sessions,logs,memories,skills}
+cp cli-config.yaml.example ~/.hermes/config.yaml
+touch ~/.hermes/.env
+
+# Añadir al menos una clave de proveedor LLM:
+echo "OPENROUTER_API_KEY=***" >> ~/.hermes/.env
+```
+
+### Ejecutar
+
+```bash
+# Enlace simbólico para acceso global
+mkdir -p ~/.local/bin
+ln -sf "$(pwd)/venv/bin/hermes" ~/.local/bin/hermes
+
+# Verificar
+hermes doctor
+hermes chat -q "Hola"
+```
+
+### Ejecutar tests
+
+```bash
+# Preferido — coincide con CI (entorno hermético, 4 workers xdist); ver AGENTS.md
+scripts/run_tests.sh
+
+# Alternativa (activa el venv primero). El wrapper sigue recomendándose
+# para paridad con GitHub Actions antes de abrir un PR:
+pytest tests/ -v
+```
+
+---
+
+## Estructura del Proyecto
+
+```
+hermes-agent/
+├── run_agent.py              # Clase AIAgent — bucle de conversación central, despacho de herramientas, persistencia de sesión
+├── cli.py                    # Clase HermesCLI — TUI interactiva, integración prompt_toolkit
+├── model_tools.py            # Orquestación de herramientas (capa delgada sobre tools/registry.py)
+├── toolsets.py               # Agrupaciones y presets de herramientas (hermes-cli, hermes-telegram, etc.)
+├── hermes_state.py           # Base de datos de sesiones SQLite con búsqueda de texto completo FTS5, títulos de sesión
+├── batch_runner.py           # Procesamiento en lote paralelo para generación de trayectorias
+│
+├── agent/                    # Internos del agente (módulos extraídos)
+│   ├── prompt_builder.py         # Ensamblaje del prompt del sistema (identidad, habilidades, archivos de contexto, memoria)
+│   ├── context_compressor.py     # Auto-resumición al acercarse a los límites de contexto
+│   ├── auxiliary_client.py       # Resuelve clientes OpenAI auxiliares (resumición, visión)
+│   ├── display.py                # KawaiiSpinner, formateo del progreso de herramientas
+│   ├── model_metadata.py         # Longitudes de contexto del modelo, estimación de tokens
+│   └── trajectory.py             # Ayudantes para guardar trayectorias
+│
+├── hermes_cli/               # Implementaciones de comandos CLI
+│   ├── main.py                   # Punto de entrada, análisis de argumentos, despacho de comandos
+│   ├── config.py                 # Gestión de configuración, migración, definiciones de variables de entorno
+│   ├── setup.py                  # Asistente de configuración interactivo
+│   ├── auth.py                   # Resolución de proveedor, OAuth, Nous Portal
+│   ├── models.py                 # Listas de selección de modelos de OpenRouter
+│   ├── banner.py                 # Banner de bienvenida, arte ASCII
+│   ├── commands.py               # Registro central de comandos de barra (CommandDef), autocompletado, ayudantes del gateway
+│   ├── callbacks.py              # Callbacks interactivos (aclarar, sudo, aprobación)
+│   ├── doctor.py                 # Diagnósticos
+│   ├── skills_hub.py             # CLI del Skills Hub + comando de barra /skills
+│   └── skin_engine.py            # Motor de skins/temas — personalización visual de CLI basada en datos
+│
+├── tools/                    # Implementaciones de herramientas (auto-registradas)
+│   ├── registry.py               # Registro central de herramientas (esquemas, manejadores, despacho)
+│   ├── approval.py               # Detección de comandos peligrosos + aprobación por sesión
+│   ├── terminal_tool.py          # Orquestación del terminal (sudo, ciclo de vida del entorno, backends)
+│   ├── file_operations.py        # read_file, write_file, búsqueda, patch, etc.
+│   ├── web_tools.py              # web_search, web_extract (Paralelo/Firecrawl + resumición Gemini)
+│   ├── vision_tools.py           # Análisis de imágenes a través de modelos multimodales
+│   ├── delegate_tool.py          # Lanzamiento de subagentes y ejecución paralela de tareas
+│   ├── code_execution_tool.py    # Python sandboxado con acceso a herramientas vía RPC
+│   ├── session_search_tool.py    # Búsqueda en conversaciones pasadas con FTS5 + ventanas ancladas
+│   ├── cronjob_tools.py          # Gestión de tareas programadas
+│   ├── skill_tools.py            # Búsqueda, carga y gestión de habilidades
+│   └── environments/             # Backends de ejecución del terminal
+│       ├── base.py                   # ABC BaseEnvironment
+│       ├── local.py, docker.py, ssh.py, singularity.py, modal.py, daytona.py
+│
+├── gateway/                  # Gateway de mensajería
+│   ├── run.py                    # GatewayRunner — ciclo de vida de plataformas, enrutamiento de mensajes, cron
+│   ├── config.py                 # Resolución de configuración de plataformas
+│   ├── session.py                # Almacén de sesiones, prompts de contexto, políticas de reset
+│   └── platforms/                # Adaptadores de plataformas
+│       ├── telegram.py, discord_adapter.py, slack.py, whatsapp.py
+│
+├── scripts/                  # Scripts del instalador y puente
+│   ├── install.sh                # Instalador Linux/macOS
+│   ├── install.ps1               # Instalador Windows PowerShell
+│   └── whatsapp-bridge/          # Puente WhatsApp Node.js (Baileys)
+│
+├── skills/                   # Habilidades incluidas (copiadas a ~/.hermes/skills/ en la instalación)
+├── optional-skills/          # Habilidades opcionales oficiales (descubribles vía hub, no activadas por defecto)
+├── tests/                    # Suite de tests
+├── website/                  # Sitio de documentación (hermes-agent.nousresearch.com)
+│
+├── cli-config.yaml.example   # Configuración de ejemplo (copiada a ~/.hermes/config.yaml)
+└── AGENTS.md                 # Guía de desarrollo para asistentes de codificación IA
+```
+
+### Configuración del usuario (almacenada en `~/.hermes/`)
+
+| Ruta | Propósito |
+|------|-----------|
+| `~/.hermes/config.yaml` | Configuración (modelo, terminal, toolsets, compresión, etc.) |
+| `~/.hermes/.env` | Claves API y secretos |
+| `~/.hermes/auth.json` | Credenciales OAuth (Nous Portal) |
+| `~/.hermes/skills/` | Todas las habilidades activas (incluidas + instaladas desde hub + creadas por el agente) |
+| `~/.hermes/memories/` | Memoria persistente (MEMORY.md, USER.md) |
+| `~/.hermes/state.db` | Base de datos de sesiones SQLite |
+| `~/.hermes/sessions/` | Índice de enrutamiento del gateway (`sessions.json`), migas de pan de solicitudes, transcripciones `*.jsonl` del gateway y (opcionalmente) snapshots JSON por sesión cuando `sessions.write_json_snapshots: true` está configurado. Los snapshots por sesión están desactivados por defecto; state.db es canónica. |
+| `~/.hermes/cron/` | Datos de trabajos programados |
+| `~/.hermes/whatsapp/session/` | Credenciales del puente WhatsApp |
+
+---
+
+## Descripción General de la Arquitectura
+
+### Bucle Central
+
+```
+Mensaje del usuario → AIAgent._run_agent_loop()
+  ├── Construir prompt del sistema (prompt_builder.py)
+  ├── Construir kwargs de API (modelo, mensajes, herramientas, configuración de razonamiento)
+  ├── Llamar al LLM (API compatible con OpenAI)
+  ├── Si tool_calls en la respuesta:
+  │     ├── Ejecutar cada herramienta a través del despacho del registro
+  │     ├── Añadir resultados de herramientas a la conversación
+  │     └── Volver a la llamada al LLM
+  ├── Si respuesta de texto:
+  │     ├── Persistir sesión en DB
+  │     └── Devolver final_response
+  └── Compresión de contexto si se acerca al límite de tokens
+```
+
+### Patrones de Diseño Clave
+
+- **Herramientas auto-registradas**: Cada archivo de herramienta llama a `registry.register()` en el momento de importación. `model_tools.py` activa el descubrimiento importando todos los módulos de herramientas.
+- **Agrupación en toolsets**: Las herramientas se agrupan en toolsets (`web`, `terminal`, `file`, `browser`, etc.) que pueden habilitarse/deshabilitarse por plataforma.
+- **Persistencia de sesión**: Todas las conversaciones se almacenan en SQLite (`hermes_state.py`) con búsqueda de texto completo y títulos de sesión únicos.
+- **Inyección efímera**: Los prompts del sistema y los mensajes de relleno se inyectan en el momento de la llamada API, nunca se persisten en la base de datos ni en los logs.
+- **Abstracción de proveedor**: El agente funciona con cualquier API compatible con OpenAI. La resolución del proveedor ocurre en el momento de la inicialización.
+- **Enrutamiento de proveedor**: Al usar OpenRouter, `provider_routing` en config.yaml controla la selección del proveedor.
+
+---
+
+## Estilo de Código
+
+- **PEP 8** con excepciones prácticas (no imponemos longitud de línea estricta)
+- **Comentarios**: Solo cuando se explica la intención no obvia, compromisos o peculiaridades de API. No narres lo que hace el código
+- **Manejo de errores**: Captura excepciones específicas. Registra con `logger.warning()`/`logger.error()` — usa `exc_info=True` para errores inesperados
+- **Multiplataforma**: Nunca asumas Unix. Ver [Compatibilidad Multiplataforma](#compatibilidad-multiplataforma)
+
+---
+
+## Añadir una Nueva Herramienta
+
+Antes de escribir una herramienta, pregúntate: [¿debería ser una habilidad en su lugar?](#debería-ser-una-habilidad-o-una-herramienta)
+
+Las herramientas se auto-registran en el registro central. Cada archivo de herramienta co-localiza su esquema, manejador y registro:
+
+```python
+"""my_tool — Breve descripción de lo que hace esta herramienta."""
+
+import json
+from tools.registry import registry
+
+
+def my_tool(param1: str, param2: int = 10, **kwargs) -> str:
+    """Manejador. Devuelve un resultado en cadena (a menudo JSON)."""
+    result = do_work(param1, param2)
+    return json.dumps(result)
+
+
+MY_TOOL_SCHEMA = {
+    "type": "function",
+    "function": {
+        "name": "my_tool",
+        "description": "Qué hace esta herramienta y cuándo debería usarla el agente.",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "param1": {"type": "string", "description": "Qué es param1"},
+                "param2": {"type": "integer", "description": "Qué es param2", "default": 10},
+            },
+            "required": ["param1"],
+        },
+    },
+}
+
+
+def _check_requirements() -> bool:
+    """Devuelve True si las dependencias de esta herramienta están disponibles."""
+    return True
+
+
+registry.register(
+    name="my_tool",
+    toolset="my_toolset",
+    schema=MY_TOOL_SCHEMA,
+    handler=lambda args, **kw: my_tool(**args, **kw),
+    check_fn=_check_requirements,
+)
+```
+
+**Conectar a un toolset (requerido):** Las herramientas integradas se auto-descubren: cualquier
+archivo `tools/*.py` que contenga una llamada de nivel superior `registry.register(...)` es
+importado por `discover_builtin_tools()` en `tools/registry.py` cuando `model_tools`
+se carga. **No** hay una lista de importaciones manual en `model_tools.py` que mantener.
+
+Todavía debes añadir el nombre de la herramienta a la lista apropiada en `toolsets.py`
+(por ejemplo `_HERMES_CORE_TOOLS` o un toolset dedicado); de lo contrario la herramienta
+se registra pero nunca se expone al agente.
+
+Consulta `AGENTS.md` (sección **Adding New Tools**) para rutas conscientes del perfil y
+orientación sobre plugins vs. núcleo.
+
+---
+
+## Añadir una Habilidad
+
+Las habilidades incluidas viven en `skills/` organizadas por categoría. Las habilidades opcionales oficiales usan la misma estructura en `optional-skills/`:
+
+```
+skills/
+├── research/
+│   └── arxiv/
+│       ├── SKILL.md              # Requerido: instrucciones principales
+│       └── scripts/              # Opcional: scripts auxiliares
+│           └── search_arxiv.py
+├── productivity/
+│   └── ocr-and-documents/
+│       ├── SKILL.md
+│       ├── scripts/
+│       └── references/
+└── ...
+```
+
+### Formato de SKILL.md
+
+```markdown
+---
+name: my-skill
+description: Breve descripción (mostrada en los resultados de búsqueda de habilidades)
+version: 1.0.0
+author: Tu Nombre
+license: MIT
+platforms: [macos, linux]          # Opcional — restringir a plataformas de SO específicas
+required_environment_variables:    # Opcional — metadatos de configuración segura al cargar
+  - name: MY_API_KEY
+    prompt: Clave API
+    help: Dónde obtenerla
+    required_for: funcionalidad completa
+prerequisites:                     # Requisitos de tiempo de ejecución heredados opcionales
+  env_vars: [MY_API_KEY]
+  commands: [curl, jq]
+metadata:
+  hermes:
+    tags: [Categoría, Subcategoría, Palabras clave]
+    related_skills: [other-skill-name]
+    fallback_for_toolsets: [web]
+    requires_toolsets: [terminal]
+---
+
+# Título de la Habilidad
+
+Introducción breve.
+
+## Cuándo Usar
+Condiciones de activación — ¿cuándo debería el agente cargar esta habilidad?
+
+## Referencia Rápida
+Tabla de comandos o llamadas API comunes.
+
+## Procedimiento
+Instrucciones paso a paso que el agente sigue.
+
+## Problemas Conocidos
+Modos de fallo conocidos y cómo manejarlos.
+
+## Verificación
+Cómo confirma el agente que funcionó.
+```
+
+### Estándares de autoría de habilidades (OBLIGATORIOS)
+
+Todo skill nuevo o modernizado — incluido, opcional o contribuido — debe cumplir estos estándares antes del merge:
+
+1. **`description` ≤ 60 caracteres, una oración, termina con punto.** Las descripciones largas saturan la UI de listado de habilidades. Indica la capacidad, no la implementación. Sin palabras de marketing ("potente", "completo", "fluido", "avanzado").
+
+2. **Las herramientas referenciadas en el cuerpo de SKILL.md deben ser herramientas nativas de Hermes o servidores MCP que la habilidad espere explícitamente.** Usa los nombres de herramientas en comillas invertidas: `` `terminal` ``, `` `web_extract` ``, `` `web_search` ``, `` `read_file` ``, `` `write_file` ``, etc.
+
+3. **El campo `platforms:` auditado contra las importaciones reales del script.** Las habilidades que usen primitivos solo de POSIX deben declarar sus plataformas soportadas.
+
+4. **`author` da crédito primero al colaborador humano.**
+
+5. **El cuerpo de SKILL.md usa el orden moderno de secciones:** título, intro de 2-3 oraciones, luego: `## Cuándo Usar`, `## Prerequisitos`, `## Cómo Ejecutar`, `## Referencia Rápida`, `## Procedimiento`, `## Problemas Conocidos`, `## Verificación`.
+
+6. **Los scripts van en `scripts/`, las referencias en `references/`, las plantillas en `templates/`.**
+
+7. **Los tests viven en `tests/skills/test_<skill>_skill.py`** y usan solo stdlib + pytest + `unittest.mock`. Sin llamadas de red en vivo.
+
+8. **Las adiciones a `.env.example` están aisladas en un bloque claramente delimitado.**
+
+---
+
+## Añadir una Skin / Tema
+
+Hermes usa un sistema de skins basado en datos — no se necesitan cambios de código para añadir una nueva skin.
+
+**Opción A: Skin de usuario (archivo YAML)**
+
+Crea `~/.hermes/skins/<nombre>.yaml`:
+
+```yaml
+name: mitema
+description: Breve descripción del tema
+
+colors:
+  banner_border: "#HEX"
+  banner_title: "#HEX"
+  banner_accent: "#HEX"
+  banner_dim: "#HEX"
+  banner_text: "#HEX"
+  response_border: "#HEX"
+
+spinner:
+  waiting_faces: ["(⚔)", "(⛨)"]
+  thinking_faces: ["(⚔)", "(⌁)"]
+  thinking_verbs: ["forjando", "planeando"]
+
+branding:
+  agent_name: "Mi Agente"
+  welcome: "Mensaje de bienvenida"
+  response_label: " ⚔ Agente "
+  prompt_symbol: "⚔"
+
+tool_prefix: "╎"
+```
+
+Todos los campos son opcionales — los valores faltantes se heredan de la skin predeterminada.
+
+**Opción B: Skin integrada**
+
+Añade al dict `_BUILTIN_SKINS` en `hermes_cli/skin_engine.py`. Usa el mismo esquema que arriba pero como dict de Python.
+
+**Activar:**
+- CLI: `/skin mitema` o establece `display.skin: mitema` en config.yaml
+
+---
+
+## Compatibilidad Multiplataforma
+
+Hermes se ejecuta en Linux, macOS y Windows nativo (además de WSL2). Al escribir código
+que toca el SO, asume que *cualquier* plataforma puede alcanzar tu ruta de código.
+
+> **Antes de hacer PR:** ejecuta `scripts/check-windows-footguns.py` para detectar
+> los patrones inseguros comunes de Windows en tu diff. Es basado en grep y barato;
+> CI también lo ejecuta en cada PR.
+
+### Reglas críticas
+
+1. **Nunca llames `os.kill(pid, 0)` para comprobaciones de liveness.** En Windows **NO es una operación sin efecto**. Usa `psutil.pid_exists(pid)` en su lugar.
+
+2. **Usa `shutil.which()` antes de hacer shell — no asumas que Windows tiene las herramientas que tiene Linux.** `ps`, `kill`, `grep`, `awk`, etc. simplemente no existen en Windows.
+
+3. **`termios` y `fcntl` son solo de Unix.** Siempre captura tanto `ImportError` como `NotImplementedError`.
+
+4. **Codificación de archivos.** Windows puede guardar archivos `.env` en `cp1252`. Siempre maneja errores de codificación.
+
+5. **Gestión de procesos.** `os.setsid()`, `os.killpg()`, `os.fork()`, `os.getuid()` y el manejo de señales POSIX difieren en Windows.
+
+6. **Señales que no existen en Windows:** `SIGALRM`, `SIGCHLD`, `SIGHUP`, `SIGUSR1`, `SIGUSR2`, etc.
+
+7. **Separadores de ruta.** Usa `pathlib.Path` en lugar de concatenación de cadenas con `/`.
+
+8. **Los enlaces simbólicos necesitan privilegios elevados en Windows** (a menos que el Modo Desarrollador esté activado).
+
+9. **Los modos de archivo POSIX (0o600, 0o644, etc.) NO se aplican en NTFS** por defecto.
+
+10. **Los daemons de fondo desacoplados en Windows necesitan `pythonw.exe`, NO `python.exe`.**
+
+---
+
+## Consideraciones de Seguridad
+
+Hermes tiene acceso al terminal. La seguridad importa.
+
+### Protecciones existentes
+
+| Capa | Implementación |
+|------|---------------|
+| **Piping de contraseña sudo** | Usa `shlex.quote()` para prevenir inyección de shell |
+| **Detección de comandos peligrosos** | Patrones regex en `tools/approval.py` con flujo de aprobación del usuario |
+| **Inyección de prompts en cron** | Escáner en `tools/cronjob_tools.py` bloquea patrones de anulación de instrucciones |
+| **Lista de denegación de escritura** | Rutas protegidas resueltas a través de `os.path.realpath()` para prevenir bypass de enlaces simbólicos |
+| **Skills Guard** | Escáner de seguridad para habilidades instaladas desde el hub (`tools/skills_guard.py`) |
+| **Sandbox de ejecución de código** | El proceso hijo `execute_code` se ejecuta con claves API eliminadas del entorno |
+| **Fortalecimiento de contenedor** | Docker: todas las capacidades eliminadas, sin escalada de privilegios, límites de PID, tmpfs de tamaño limitado |
+
+### Al contribuir código sensible a la seguridad
+
+- **Siempre usa `shlex.quote()`** al interpolar entrada del usuario en comandos de shell
+- **Resuelve enlaces simbólicos** con `os.path.realpath()` antes de comprobaciones de control de acceso basadas en rutas
+- **No registres secretos.** Las claves API, tokens y contraseñas nunca deben aparecer en la salida de log
+- **Captura excepciones amplias** alrededor de la ejecución de herramientas para que un solo fallo no bloquee el bucle del agente
+- **Prueba en todas las plataformas** si tu cambio toca rutas de archivos, gestión de procesos o comandos de shell
+
+### Política de fijación de dependencias (fortalecimiento de la cadena de suministro)
+
+Tras el [compromiso de la cadena de suministro de litellm](https://github.com/BerriAI/litellm/issues/24512) en marzo de 2026 y la [campaña del gusano Mini Shai-Hulud](https://socket.dev/blog/tanstack-npm-packages-compromised-mini-shai-hulud-supply-chain-attack) en mayo de 2026, todas las dependencias deben seguir estas reglas:
+
+| Tipo de fuente | Tratamiento requerido | Justificación |
+|---|---|---|
+| **Paquete PyPI** | `>=suelo,<siguiente_mayor` | Las versiones de PyPI son inmutables una vez publicadas, pero pueden empujarse nuevas versiones en tu rango. |
+| **URL de Git** | SHA completo del commit | Las ramas y etiquetas son refs mutables; el SHA está direccionado por contenido. |
+| **GitHub Actions** | SHA completo del commit + comentario de versión | Las etiquetas de acción son refs mutables. Fija como `uses: owner/action@<sha>  # vX.Y.Z` |
+| **Instalaciones pip solo de CI** | `==exacto` | Builds de CI herméticos; el cambio es aceptable. |
+
+**Cada nueva dependencia de PyPI en un PR debe tener un límite superior `<siguiente_mayor`.** Los PRs que añadan especificaciones `>=X.Y.Z` sin límite superior serán rechazados.
+
+---
+
+## Proceso de Pull Request
+
+### Nomenclatura de ramas
+
+```
+fix/descripcion        # Correcciones de errores
+feat/descripcion       # Nuevas funcionalidades
+docs/descripcion       # Documentación
+test/descripcion       # Tests
+refactor/descripcion   # Reestructuración de código
+```
+
+### Antes de enviar
+
+1. **Ejecutar tests**: `scripts/run_tests.sh` (recomendado; igual que CI) o `pytest tests/ -v` con el venv del proyecto activado
+2. **Probar manualmente**: Ejecuta `hermes` y ejercita la ruta de código que cambiaste
+3. **Verificar impacto multiplataforma**: Si tocas E/S de archivos, gestión de procesos o manejo del terminal, considera macOS, Linux y WSL2
+4. **Mantén los PRs enfocados**: Un cambio lógico por PR. No mezcles una corrección de error con una refactorización con una nueva funcionalidad.
+
+### Descripción del PR
+
+Incluye:
+- **Qué** cambió y **por qué**
+- **Cómo probarlo** (pasos de reproducción para errores, ejemplos de uso para funcionalidades)
+- **Qué plataformas** probaste
+- Referencia cualquier issue relacionado
+
+### Mensajes de commit
+
+Usamos [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+<tipo>(<alcance>): <descripción>
+```
+
+| Tipo | Usar para |
+|------|-----------|
+| `fix` | Correcciones de errores |
+| `feat` | Nuevas funcionalidades |
+| `docs` | Documentación |
+| `test` | Tests |
+| `refactor` | Reestructuración de código (sin cambio de comportamiento) |
+| `chore` | Build, CI, actualizaciones de dependencias |
+
+Alcances: `cli`, `gateway`, `tools`, `skills`, `agent`, `install`, `whatsapp`, `security`, etc.
+
+Ejemplos:
+```
+fix(cli): prevenir bloqueo en save_config_value cuando el modelo es una cadena
+feat(gateway): añadir aislamiento de sesión multi-usuario de WhatsApp
+fix(security): prevenir inyección de shell en el piping de contraseña sudo
+test(tools): añadir tests unitarios para file_operations
+```
+
+---
+
+## Reportar Issues
+
+- Usa [GitHub Issues](https://github.com/NousResearch/hermes-agent/issues)
+- Incluye: SO, versión de Python, versión de Hermes (`hermes --version`), traza de error completa
+- Incluye pasos para reproducir
+- Verifica los issues existentes antes de crear duplicados
+- Para vulnerabilidades de seguridad, por favor reporta de forma privada
+
+---
+
+## Comunidad
+
+- **Discord**: [discord.gg/NousResearch](https://discord.gg/NousResearch) — para preguntas, mostrar proyectos y compartir habilidades
+- **GitHub Discussions**: Para propuestas de diseño y discusiones de arquitectura
+- **Skills Hub**: Sube habilidades especializadas a un registro y compártelas con la comunidad
+
+---
+
+## Licencia
+
+Al contribuir, aceptas que tus contribuciones serán licenciadas bajo la [Licencia MIT](LICENSE).

CONTRIBUTING.md

@@ -0,0 +1,993 @@
+# Contributing to Hermes Agent
+
+Thank you for contributing to Hermes Agent! This guide covers everything you need: setting up your dev environment, understanding the architecture, deciding what to build, and getting your PR merged.
+
+---
+
+## Contribution Priorities
+
+We value contributions in this order:
+
+1. **Bug fixes** — crashes, incorrect behavior, data loss. Always top priority.
+2. **Cross-platform compatibility** — macOS, different Linux distros, and WSL2 on Windows. We want Hermes to work everywhere.
+3. **Security hardening** — shell injection, prompt injection, path traversal, privilege escalation. See [Security](#security-considerations).
+4. **Performance and robustness** — retry logic, error handling, graceful degradation.
+5. **New skills** — but only broadly useful ones. See [Should it be a Skill or a Tool?](#should-it-be-a-skill-or-a-tool)
+6. **New tools** — rarely needed. Most capabilities should be skills. See below.
+7. **Documentation** — fixes, clarifications, new examples.
+
+---
+
+## Before You Start: Search First
+
+A quick search before you build saves your time and keeps the PR queue clean — duplicates are common here, so it's worth a minute up front.
+
+- **Search both open *and* merged PRs and issues** for your topic or error symptom — the duplicate-check in the PR template fires at review time, after you've already done the work:
+  ```bash
+  gh search issues --repo NousResearch/hermes-agent "<your terms>"
+  gh search prs --repo NousResearch/hermes-agent --state all "<your terms>"
+  ```
+  Or use the web UI: [issues](https://github.com/NousResearch/hermes-agent/issues?q=) · [PRs (all states)](https://github.com/NousResearch/hermes-agent/pulls?q=is%3Apr).
+- **The issue tracker can lag the code.** Many requested features are already implemented in-tree, so also search the source (`search_files`, or your editor's grep) for the capability before proposing it.
+- **If an open PR already addresses it**, consider reviewing or improving that one instead of opening a competing duplicate.
+- **For larger work**, comment on the issue to signal you're working on it, so others don't start the same thing.
+
+Related: #38284 covers the agent-side analog — Hermes itself checking existing issues and PRs before deep self-troubleshooting. This section is the human-contributor complement.
+
+---
+
+## Should it be a Skill or a Tool?
+
+This is the most common question for new contributors. The answer is almost always **skill**.
+
+### Make it a Skill when:
+
+- The capability can be expressed as instructions + shell commands + existing tools
+- It wraps an external CLI or API that the agent can call via `terminal` or `web_extract`
+- It doesn't need custom Python integration or API key management baked into the agent
+- Examples: arXiv search, git workflows, Docker management, PDF processing, email via CLI tools
+
+### Make it a Tool when:
+
+- It requires end-to-end integration with API keys, auth flows, or multi-component configuration managed by the agent harness
+- It needs custom processing logic that must execute precisely every time (not "best effort" from LLM interpretation)
+- It handles binary data, streaming, or real-time events that can't go through the terminal
+- Examples: browser automation (Browserbase session management), TTS (audio encoding + platform delivery), vision analysis (base64 image handling)
+
+### Should the Skill be bundled?
+
+Bundled skills (in `skills/`) ship with every Hermes install. They should be **broadly useful to most users**:
+
+- Document handling, web research, common dev workflows, system administration
+- Used regularly by a wide range of people
+
+If your skill is official and useful but not universally needed (e.g., a paid service integration, a heavyweight dependency), put it in **`optional-skills/`** — it ships with the repo but isn't activated by default. Users can discover it via `hermes skills browse` (labeled "official") and install it with `hermes skills install` (no third-party warning, built-in trust).
+
+If your skill is specialized, community-contributed, or niche, it's better suited for a **Skills Hub** — upload it to a skills registry and share it in the [Nous Research Discord](https://discord.gg/NousResearch). Users can install it with `hermes skills install`.
+
+---
+
+## Memory Providers: Ship as a Standalone Plugin
+
+**We are no longer accepting new memory providers into this repo.** The set of built-in providers under `plugins/memory/` (honcho, mem0, supermemory, byterover, hindsight, holographic, openviking, retaindb) is closed. If you want to add a new memory backend, publish it as a **standalone plugin repo** that users install into `~/.hermes/plugins/` (or via a pip entry point).
+
+Standalone memory plugins:
+
+- Implement the same `MemoryProvider` ABC (`agent/memory_provider.py`) — `sync_turn`, `prefetch`, `shutdown`, and optionally `post_setup(hermes_home, config)` for setup-wizard integration
+- Use the same discovery system — `discover_memory_providers()` picks them up from user/project plugin directories and pip entry points
+- Integrate with `hermes memory setup` via `post_setup()` — no need to touch core code
+- Can register their own CLI subcommands via `register_cli(subparser)` in a `cli.py` file
+- Get all the same lifecycle hooks and config plumbing as in-tree providers
+
+PRs that add a new directory under `plugins/memory/` will be closed with a pointer to publish the provider as its own repo. Existing in-tree providers stay; bug fixes to them are welcome.
+
+This isn't a quality bar — it's a coupling-and-maintenance decision. Memory providers are the most common plugin type and they shouldn't all live in this tree.
+
+---
+
+## Third-Party Product Integrations: Ship as a Standalone Plugin
+
+The same rule extends to **any plugin that integrates someone else's product or project** — observability/metrics backends, vendor SaaS connectors, analytics dashboards, paid-service tie-ins, and similar third-party integrations. **These do not land in this repo.**
+
+The reason is maintenance load, not quality. Every external product absorbed into the core tree becomes ours to keep working against a fast-moving codebase, for a backend we don't own and can't control. Hermes ships a lot and the core moves quickly; coupling third-party products into it creates an open-ended burden on the maintainers.
+
+Publish these as a **standalone plugin repo** instead:
+
+- Implement the relevant ABC and use the existing plugin discovery path (`~/.hermes/plugins/`, project `.hermes/plugins/`, or a pip entry point) — see [Build a Hermes Plugin](https://hermes-agent.nousresearch.com/docs/guides/build-a-hermes-plugin)
+- Register lifecycle hooks (`pre_tool_call`, `post_tool_call`, `pre_llm_call`, `post_llm_call`, `on_session_start`, `on_session_end`), tools (`ctx.register_tool`), and CLI subcommands (`ctx.register_cli_command`) through the surface we already expose — no core changes needed
+- If your plugin needs a capability the framework doesn't expose, that's a feature request to **widen the generic plugin surface** (a new hook or `ctx` method) — never special-case your plugin in core
+- Promote it in the [Nous Research Discord](https://discord.gg/NousResearch) `#plugins-skills-and-skins` channel so users can find and install it
+
+A well-built third-party-product plugin can clear automated review and still be closed for this reason — it's a placement decision, not a verdict on the code. PRs that add such a directory under `plugins/` will be closed with a pointer to publish it as its own repo.
+
+---
+
+## Development Setup
+
+### Prerequisites
+
+| Requirement | Notes |
+|-------------|-------|
+| **Git** | With the `git-lfs` extension installed |
+| **Python 3.11–3.13** | uv will install it if missing |
+| **uv** | Fast Python package manager ([install](https://docs.astral.sh/uv/)) |
+| **Node.js 20+** | Optional — needed for browser tools and WhatsApp bridge (matches root `package.json` engines) |
+
+### Install with the standard installer
+
+For most contributors, the best development bootstrap is the same path users
+take: run the standard installer, then work inside the repository it cloned.
+The installer creates the Hermes venv, wires the `hermes` command, stamps the
+install method for `hermes update`, and clones the full git project into
+`$HERMES_HOME/hermes-agent` (usually `~/.hermes/hermes-agent`). That keeps your
+development environment on the same layout the CLI, updater, lazy dependency
+installer, gateway, and docs assume.
+
+```bash
+curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
+cd "${HERMES_HOME:-$HOME/.hermes}/hermes-agent"
+
+# Add dev/test extras on top of the standard install.
+uv pip install -e ".[all,dev]"
+
+# Optional: docs site + workspace dependencies.
+npm install
+```
+
+After that, create branches and run tests from that checkout:
+
+```bash
+git checkout -b fix/description
+scripts/run_tests.sh
+```
+
+### Manual clone fallback
+
+Use this only if you intentionally do not want Hermes' managed install layout
+(for example, a throwaway clone inside a container or CI job). If you install
+this way, make sure you run the `hermes` entrypoint from this venv; running the
+system `python3 -m hermes_cli.main` can pick up unrelated system Python
+packages.
+
+Create the venv **outside** the cloned source tree. A venv that lives inside
+the directory the agent operates from can be wiped by a relative-path command
+the agent runs against its own checkout (`rm -rf venv`, `uv venv venv`, etc.),
+which silently destroys the running runtime mid-session. Keeping it outside the
+tree means no relative path from the workspace resolves to it.
+
+```bash
+git clone https://github.com/NousResearch/hermes-agent.git
+cd hermes-agent
+
+# Create venv with Python 3.11, OUTSIDE the source tree
+uv venv ~/.hermes/venvs/hermes-dev --python 3.11
+export VIRTUAL_ENV="$HOME/.hermes/venvs/hermes-dev"
+export PATH="$VIRTUAL_ENV/bin:$PATH"
+
+# Install with all extras (messaging, cron, CLI menus, dev tools)
+uv pip install -e ".[all,dev]"
+
+# Optional: workspace / docs dependencies
+npm install
+```
+
+### Configure for development
+
+```bash
+mkdir -p ~/.hermes/{cron,sessions,logs,memories,skills}
+cp cli-config.yaml.example ~/.hermes/config.yaml
+touch ~/.hermes/.env
+
+# Add at minimum an LLM provider key:
+echo "OPENROUTER_API_KEY=***" >> ~/.hermes/.env
+```
+
+### Run
+
+```bash
+# The standard installer already put `hermes` on PATH.
+hermes doctor
+hermes chat -q "Hello"
+```
+
+If you used the manual clone fallback, run `./hermes` from the checkout or
+symlink this clone's venv explicitly:
+
+```bash
+mkdir -p ~/.local/bin
+ln -sf "$(pwd)/venv/bin/hermes" ~/.local/bin/hermes
+```
+
+### Run tests
+
+```bash
+# Preferred — matches CI (hermetic `env -i`, per-file subprocess isolation
+# via run_tests_parallel.py, worker count auto-scaled); see AGENTS.md
+scripts/run_tests.sh
+
+# Alternative (activate the venv first). The wrapper is still recommended
+# for parity with GitHub Actions before you open a PR:
+pytest tests/ -v
+```
+
+---
+
+## Project Structure
+
+```
+hermes-agent/
+├── run_agent.py              # AIAgent class — core conversation loop, tool dispatch, session persistence
+├── cli.py                    # HermesCLI class — interactive TUI, prompt_toolkit integration
+├── model_tools.py            # Tool orchestration (thin layer over tools/registry.py)
+├── toolsets.py               # Tool groupings and presets (hermes-cli, hermes-telegram, etc.)
+├── hermes_state.py           # SQLite session database with FTS5 full-text search, session titles
+├── batch_runner.py           # Parallel batch processing for trajectory generation
+│
+├── agent/                    # Agent internals (extracted modules)
+│   ├── prompt_builder.py         # System prompt assembly (identity, skills, context files, memory)
+│   ├── context_compressor.py     # Auto-summarization when approaching context limits
+│   ├── auxiliary_client.py       # Resolves auxiliary OpenAI clients (summarization, vision)
+│   ├── display.py                # KawaiiSpinner, tool progress formatting
+│   ├── model_metadata.py         # Model context lengths, token estimation
+│   └── trajectory.py             # Trajectory saving helpers
+│
+├── hermes_cli/               # CLI command implementations
+│   ├── main.py                   # Entry point, argument parsing, command dispatch
+│   ├── config.py                 # Config management, migration, env var definitions
+│   ├── setup.py                  # Interactive setup wizard
+│   ├── auth.py                   # Provider resolution, OAuth, Nous Portal
+│   ├── models.py                 # OpenRouter model selection lists
+│   ├── banner.py                 # Welcome banner, ASCII art
+│   ├── commands.py               # Central slash command registry (CommandDef), autocomplete, gateway helpers
+│   ├── callbacks.py              # Interactive callbacks (clarify, sudo, approval)
+│   ├── doctor.py                 # Diagnostics
+│   ├── skills_hub.py             # Skills Hub CLI + /skills slash command
+│   └── skin_engine.py            # Skin/theme engine — data-driven CLI visual customization
+│
+├── tools/                    # Tool implementations (self-registering)
+│   ├── registry.py               # Central tool registry (schemas, handlers, dispatch)
+│   ├── approval.py               # Dangerous command detection + per-session approval
+│   ├── terminal_tool.py          # Terminal orchestration (sudo, env lifecycle, backends)
+│   ├── file_operations.py        # read_file, write_file, search, patch, etc.
+│   ├── web_tools.py              # web_search, web_extract (Parallel/Firecrawl + Gemini summarization)
+│   ├── vision_tools.py           # Image analysis via multimodal models
+│   ├── delegate_tool.py          # Subagent spawning and parallel task execution
+│   ├── code_execution_tool.py    # Sandboxed Python with RPC tool access
+│   ├── session_search_tool.py    # Search past conversations with FTS5 + anchored windows
+│   ├── cronjob_tools.py          # Scheduled task management
+│   ├── skill_tools.py            # Skill search, load, manage
+│   └── environments/             # Terminal execution backends
+│       ├── base.py                   # BaseEnvironment ABC
+│       ├── local.py, docker.py, ssh.py, singularity.py, modal.py, daytona.py
+│
+├── gateway/                  # Messaging gateway
+│   ├── run.py                    # GatewayRunner — platform lifecycle, message routing, cron
+│   ├── config.py                 # Platform configuration resolution
+│   ├── session.py                # Session store, context prompts, reset policies
+│   └── platforms/                # Platform adapters
+│       ├── telegram.py, discord_adapter.py, slack.py, whatsapp.py
+│
+├── scripts/                  # Installer and bridge scripts
+│   ├── install.sh                # Linux/macOS installer
+│   ├── install.ps1               # Windows PowerShell installer
+│   └── whatsapp-bridge/          # Node.js WhatsApp bridge (Baileys)
+│
+├── skills/                   # Bundled skills (copied to ~/.hermes/skills/ on install)
+├── optional-skills/          # Official optional skills (discoverable via hub, not activated by default)
+├── tests/                    # Test suite
+├── website/                  # Documentation site (hermes-agent.nousresearch.com)
+│
+├── cli-config.yaml.example   # Example configuration (copied to ~/.hermes/config.yaml)
+└── AGENTS.md                 # Development guide for AI coding assistants
+```
+
+### User configuration (stored in `~/.hermes/`)
+
+| Path | Purpose |
+|------|---------|
+| `~/.hermes/config.yaml` | Settings (model, terminal, toolsets, compression, etc.) |
+| `~/.hermes/.env` | API keys and secrets |
+| `~/.hermes/auth.json` | OAuth credentials (Nous Portal) |
+| `~/.hermes/skills/` | All active skills (bundled + hub-installed + agent-created) |
+| `~/.hermes/memories/` | Persistent memory (MEMORY.md, USER.md) |
+| `~/.hermes/state.db` | SQLite session database |
+| `~/.hermes/sessions/` | Gateway routing index (`sessions.json`), request-dump breadcrumbs, gateway `*.jsonl` transcripts, and (optionally) per-session JSON snapshots when `sessions.write_json_snapshots: true` is set. The per-session snapshots are off by default; state.db is canonical. |
+| `~/.hermes/cron/` | Scheduled job data |
+| `~/.hermes/whatsapp/session/` | WhatsApp bridge credentials |
+
+---
+
+## Architecture Overview
+
+### Core Loop
+
+```
+User message → AIAgent._run_agent_loop()
+  ├── Build system prompt (prompt_builder.py)
+  ├── Build API kwargs (model, messages, tools, reasoning config)
+  ├── Call LLM (OpenAI-compatible API)
+  ├── If tool_calls in response:
+  │     ├── Execute each tool via registry dispatch
+  │     ├── Add tool results to conversation
+  │     └── Loop back to LLM call
+  ├── If text response:
+  │     ├── Persist session to DB
+  │     └── Return final_response
+  └── Context compression if approaching token limit
+```
+
+### Key Design Patterns
+
+- **Self-registering tools**: Each tool file calls `registry.register()` at import time. `model_tools.py` triggers discovery by importing all tool modules.
+- **Toolset grouping**: Tools are grouped into toolsets (`web`, `terminal`, `file`, `browser`, etc.) that can be enabled/disabled per platform.
+- **Session persistence**: All conversations are stored in SQLite (`hermes_state.py`) with full-text search and unique session titles. Per-session JSON snapshots in `~/.hermes/sessions/` were superseded by the SQLite store and are off by default; opt back in with `sessions.write_json_snapshots: true` if you have external tooling that consumes the JSON files directly.
+- **Ephemeral injection**: System prompts and prefill messages are injected at API call time, never persisted to the database or logs.
+- **Provider abstraction**: The agent works with any OpenAI-compatible API. Provider resolution happens at init time (Nous Portal OAuth, OpenRouter API key, or custom endpoint).
+- **Provider routing**: When using OpenRouter, `provider_routing` in config.yaml controls provider selection (sort by throughput/latency/price, allow/ignore specific providers, data retention policies). These are injected as `extra_body.provider` in API requests.
+
+---
+
+## Code Style
+
+- **PEP 8** with practical exceptions (we don't enforce strict line length)
+- **Comments**: Only when explaining non-obvious intent, trade-offs, or API quirks. Don't narrate what the code does — `# increment counter` adds nothing
+- **Error handling**: Catch specific exceptions. Log with `logger.warning()`/`logger.error()` — use `exc_info=True` for unexpected errors so stack traces appear in logs
+- **Cross-platform**: Never assume Unix. See [Cross-Platform Compatibility](#cross-platform-compatibility)
+
+---
+
+## Adding a New Tool
+
+Before writing a tool, ask: [should this be a skill instead?](#should-it-be-a-skill-or-a-tool)
+
+Tools self-register with the central registry. Each tool file co-locates its schema, handler, and registration:
+
+```python
+"""my_tool — Brief description of what this tool does."""
+
+import json
+from tools.registry import registry
+
+
+def my_tool(param1: str, param2: int = 10, **kwargs) -> str:
+    """Handler. Returns a string result (often JSON)."""
+    result = do_work(param1, param2)
+    return json.dumps(result)
+
+
+MY_TOOL_SCHEMA = {
+    "type": "function",
+    "function": {
+        "name": "my_tool",
+        "description": "What this tool does and when the agent should use it.",
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "param1": {"type": "string", "description": "What param1 is"},
+                "param2": {"type": "integer", "description": "What param2 is", "default": 10},
+            },
+            "required": ["param1"],
+        },
+    },
+}
+
+
+def _check_requirements() -> bool:
+    """Return True if this tool's dependencies are available."""
+    return True
+
+
+registry.register(
+    name="my_tool",
+    toolset="my_toolset",
+    schema=MY_TOOL_SCHEMA,
+    handler=lambda args, **kw: my_tool(**args, **kw),
+    check_fn=_check_requirements,
+)
+```
+
+**Wire into a toolset (required):** Built-in tools are auto-discovered: any
+`tools/*.py` file that contains a top-level `registry.register(...)` call is
+imported by `discover_builtin_tools()` in `tools/registry.py` when `model_tools`
+loads. There is **no** manual import list in `model_tools.py` to maintain.
+
+You must still add the tool name to the appropriate list in `toolsets.py`
+(for example `_HERMES_CORE_TOOLS` or a dedicated toolset); otherwise the tool
+registers but is never exposed to the agent. If you introduce a new toolset,
+add it in `toolsets.py` and wire it into the relevant platform presets.
+
+See `AGENTS.md` (section **Adding New Tools**) for profile-aware paths and
+plugin vs core guidance.
+
+---
+
+## Adding a Skill
+
+Bundled skills live in `skills/` organized by category. Official optional skills use the same structure in `optional-skills/`:
+
+```
+skills/
+├── research/
+│   └── arxiv/
+│       ├── SKILL.md              # Required: main instructions
+│       └── scripts/              # Optional: helper scripts
+│           └── search_arxiv.py
+├── productivity/
+│   └── ocr-and-documents/
+│       ├── SKILL.md
+│       ├── scripts/
+│       └── references/
+└── ...
+```
+
+### SKILL.md format
+
+```markdown
+---
+name: my-skill
+description: Brief description (shown in skill search results)
+version: 1.0.0
+author: Your Name
+license: MIT
+platforms: [macos, linux]          # Optional — restrict to specific OS platforms
+                                   #   Valid: macos, linux, windows
+                                   #   Omit to load on all platforms (default)
+required_environment_variables:    # Optional — secure setup-on-load metadata
+  - name: MY_API_KEY
+    prompt: API key
+    help: Where to get it
+    required_for: full functionality
+prerequisites:                     # Optional legacy runtime requirements
+  env_vars: [MY_API_KEY]           #   Backward-compatible alias for required env vars
+  commands: [curl, jq]             #   Advisory only; does not hide the skill
+metadata:
+  hermes:
+    tags: [Category, Subcategory, Keywords]
+    related_skills: [other-skill-name]
+    fallback_for_toolsets: [web]       # Optional — show only when toolset is unavailable
+    requires_toolsets: [terminal]      # Optional — show only when toolset is available
+---
+
+# Skill Title
+
+Brief intro.
+
+## When to Use
+Trigger conditions — when should the agent load this skill?
+
+## Prerequisites
+Env vars, install steps, MCP setup, API key sourcing.
+
+## How to Run
+Canonical invocation through the `terminal` tool.
+
+## Quick Reference
+Table of common commands or API calls.
+
+## Procedure
+Step-by-step instructions the agent follows.
+
+## Pitfalls
+Known failure modes and how to handle them.
+
+## Verification
+How the agent confirms it worked.
+```
+
+### Platform-specific skills
+
+Skills can declare which OS platforms they support via the `platforms` frontmatter field. Skills with this field are automatically hidden from the system prompt, `skills_list()`, and slash commands on incompatible platforms.
+
+```yaml
+platforms: [macos]            # macOS only (e.g., iMessage, Apple Reminders)
+platforms: [macos, linux]     # macOS and Linux
+platforms: [windows]          # Windows only
+```
+
+If the field is omitted or empty, the skill loads on all platforms (backward compatible). See `skills/apple/` for examples of macOS-only skills.
+
+### Conditional skill activation
+
+Skills can declare conditions that control when they appear in the system prompt, based on which tools and toolsets are available in the current session. This is primarily used for **fallback skills** — alternatives that should only be shown when a primary tool is unavailable.
+
+Four fields are supported under `metadata.hermes`:
+
+```yaml
+metadata:
+  hermes:
+    fallback_for_toolsets: [web]      # Show ONLY when these toolsets are unavailable
+    requires_toolsets: [terminal]     # Show ONLY when these toolsets are available
+    fallback_for_tools: [web_search]  # Show ONLY when these specific tools are unavailable
+    requires_tools: [terminal]        # Show ONLY when these specific tools are available
+```
+
+**Semantics:**
+- `fallback_for_*`: The skill is a backup. It is **hidden** when the listed tools/toolsets are available, and **shown** when they are unavailable. Use this for free alternatives to premium tools.
+- `requires_*`: The skill needs certain tools to function. It is **hidden** when the listed tools/toolsets are unavailable. Use this for skills that depend on specific capabilities (e.g., a skill that only makes sense with terminal access).
+- If both are specified, both conditions must be satisfied for the skill to appear.
+- If neither is specified, the skill is always shown (backward compatible).
+
+**Examples:**
+
+```yaml
+# DuckDuckGo search — shown when Firecrawl (web toolset) is unavailable
+metadata:
+  hermes:
+    fallback_for_toolsets: [web]
+
+# Smart home skill — only useful when terminal is available
+metadata:
+  hermes:
+    requires_toolsets: [terminal]
+
+# Local browser fallback — shown when Browserbase is unavailable
+metadata:
+  hermes:
+    fallback_for_toolsets: [browser]
+```
+
+The filtering happens at prompt build time in `agent/prompt_builder.py`. The `build_skills_system_prompt()` function receives the set of available tools and toolsets from the agent and uses `_skill_should_show()` to evaluate each skill's conditions.
+
+### Skill setup metadata
+
+Skills can declare secure setup-on-load metadata via the `required_environment_variables` frontmatter field. Missing values do not hide the skill from discovery; they trigger a CLI-only secure prompt when the skill is actually loaded.
+
+```yaml
+required_environment_variables:
+  - name: TENOR_API_KEY
+    prompt: Tenor API key
+    help: Get a key from https://developers.google.com/tenor
+    required_for: full functionality
+```
+
+The user may skip setup and keep loading the skill. Hermes only exposes metadata (`stored_as`, `skipped`, `validated`) to the model — never the secret value.
+
+Legacy `prerequisites.env_vars` remains supported and is normalized into the new representation.
+
+```yaml
+prerequisites:
+  env_vars: [TENOR_API_KEY]       # Legacy alias for required_environment_variables
+  commands: [curl, jq]            # Advisory CLI checks
+```
+
+Gateway and messaging sessions never collect secrets in-band; they instruct the user to run `hermes setup` or update `~/.hermes/.env` locally.
+
+**When to declare required environment variables:**
+- The skill uses an API key or token that should be collected securely at load time
+- The skill can still be useful if the user skips setup, but may degrade gracefully
+
+**When to declare command prerequisites:**
+- The skill relies on a CLI tool that may not be installed (e.g., `himalaya`, `openhue`, `ddgs`)
+- Treat command checks as guidance, not discovery-time hiding
+
+See `skills/gifs/gif-search/` and `skills/email/himalaya/` for examples.
+
+### Skill authoring standards (HARDLINE)
+
+Every new or modernized skill — bundled, optional, or contributed — must meet these standards before merge. Reviewers reject PRs that violate them.
+
+1. **`description` ≤ 60 characters, one sentence, ends with a period.** Long descriptions bloat the skill listing UI and dilute the model's attention when many skills are loaded. State the capability, not the implementation. No marketing words ("powerful", "comprehensive", "seamless", "advanced"). Don't repeat the skill name. Verify with:
+   ```python
+   import re, pathlib
+   m = re.search(r'^description: (.*)$',
+                 pathlib.Path('skills/<cat>/<name>/SKILL.md').read_text(),
+                 re.MULTILINE)
+   assert len(m.group(1)) <= 60, len(m.group(1))
+   ```
+
+   Good: `Search arXiv papers by keyword, author, category, or ID.`
+   Bad: `A powerful and comprehensive skill that allows the agent to search arXiv for relevant academic papers using various criteria including keywords, authors, and categories.`
+
+2. **Tools referenced in SKILL.md prose must be native Hermes tools or MCP servers the skill explicitly expects.** When the skill needs a capability, point at the proper tool by name in backticks: `` `terminal` ``, `` `web_extract` ``, `` `web_search` ``, `` `read_file` ``, `` `write_file` ``, `` `patch` ``, `` `search_files` ``, `` `vision_analyze` ``, `` `browser_navigate` ``, `` `delegate_task` ``, `` `image_generate` ``, `` `text_to_speech` ``, `` `cronjob` ``, `` `memory` ``, `` `skill_view` ``, `` `todo` ``, `` `execute_code` ``.
+
+   Do NOT name shell utilities the agent already has wrapped:
+
+   | Don't say | Say |
+   |---|---|
+   | `grep`, `rg` | `search_files` |
+   | `cat`, `head`, `tail` | `read_file` |
+   | `sed`, `awk` | `patch` |
+   | `find`, `ls` | `search_files` (with `target='files'`) |
+   | `curl` for content extraction | `web_extract` |
+   | `echo > file`, `cat <<EOF` | `write_file` |
+
+   If the skill depends on an MCP server, name the MCP server and document its setup in `## Prerequisites`. Third-party CLIs (e.g. `ffmpeg`, `gh`, a specific SDK) are fine to invoke from inside script files, but the prose should frame the interaction as "invoke through the `terminal` tool", not as a manual shell session.
+
+3. **`platforms:` gating audited against actual script imports.** Skills that use POSIX-only primitives (`fcntl`, `termios`, `os.setsid`, `os.kill(pid, 0)` for liveness, `/proc`, hardcoded `/tmp` paths, `signal.SIGKILL`, bash heredocs, `osascript`, `apt`, `systemctl`) must declare their supported platforms via the `platforms:` frontmatter. Default posture is to fix it cross-platform first — `tempfile.gettempdir()`, `pathlib.Path`, `psutil.pid_exists()`, Python-level filtering instead of `grep`. Gate to a narrower set only when the dependency is genuinely platform-bound (e.g. `osascript` is macOS-only, `/proc` is Linux-only).
+
+4. **`author` credits the human contributor first.** For external contributions, the contributor's real name + GitHub handle goes first (`Jane Doe (jane-doe)`); "Hermes Agent" is the secondary collaborator. If the contributor's commit shows "Hermes Agent" as author because they used Hermes to draft the skill, replace it with their actual name — credit the human, not the tool.
+
+5. **SKILL.md body uses the modern section order.** `# <Skill> Skill` title, 2-3 sentence intro stating what it does and what it doesn't do, then:
+   - `## When to Use` — trigger conditions
+   - `## Prerequisites` — env vars, install steps, MCP setup, API key sourcing
+   - `## How to Run` — canonical invocation through the `terminal` tool
+   - `## Quick Reference` — flat command/API reference
+   - `## Procedure` — numbered steps with copy-paste commands
+   - `## Pitfalls` — known limits, rate limits, things that look broken but aren't
+   - `## Verification` — single command that proves the skill works
+
+   Target ~200 lines for a complex skill, ~100 lines for a simple one. Cut redundant intro fluff, marketing prose, and re-explanations of env vars already documented in `## Prerequisites`.
+
+6. **Scripts go in `scripts/`, references in `references/`, templates in `templates/`.** Don't expect the model to inline-write parsers, XML walkers, or non-trivial logic every call — ship a helper script. Reference scripts from SKILL.md by path relative to the skill directory.
+
+7. **Tests live at `tests/skills/test_<skill>_skill.py`** and use only stdlib + pytest + `unittest.mock`. No live network calls. Run via `scripts/run_tests.sh tests/skills/test_<skill>_skill.py -q`. Must pass under the hermetic CI env (no API keys leaking through). Use `monkeypatch` and `tmp_path` for any env-var or filesystem dependencies.
+
+8. **`.env.example` additions are isolated to a clearly delimited block.** Don't touch the surrounding file — contributor-supplied `.env.example` versions are usually stale, and edits outside the skill's own block will be dropped during salvage. Comment all values with `#` (it's documentation, not live config).
+
+### Skill guidelines
+
+- **No external dependencies unless absolutely necessary.** Prefer stdlib Python, curl, and existing Hermes tools (`web_extract`, `terminal`, `read_file`).
+- **Progressive disclosure.** Put the most common workflow first. Edge cases and advanced usage go at the bottom.
+- **Include helper scripts** for XML/JSON parsing or complex logic — don't expect the LLM to write parsers inline every time.
+- **Test it.** Run `hermes --toolsets skills -q "Use the X skill to do Y"` and verify the agent follows the instructions correctly.
+
+---
+
+## Adding a Skin / Theme
+
+Hermes uses a data-driven skin system — no code changes needed to add a new skin.
+
+**Option A: User skin (YAML file)**
+
+Create `~/.hermes/skins/<name>.yaml`:
+
+```yaml
+name: mytheme
+description: Short description of the theme
+
+colors:
+  banner_border: "#HEX"     # Panel border color
+  banner_title: "#HEX"      # Panel title color
+  banner_accent: "#HEX"     # Section header color
+  banner_dim: "#HEX"        # Muted/dim text color
+  banner_text: "#HEX"       # Body text color
+  response_border: "#HEX"   # Response box border
+
+spinner:
+  waiting_faces: ["(⚔)", "(⛨)"]
+  thinking_faces: ["(⚔)", "(⌁)"]
+  thinking_verbs: ["forging", "plotting"]
+  wings:                     # Optional left/right decorations
+    - ["⟪⚔", "⚔⟫"]
+
+branding:
+  agent_name: "My Agent"
+  welcome: "Welcome message"
+  response_label: " ⚔ Agent "
+  prompt_symbol: "⚔"
+
+tool_prefix: "╎"             # Tool output line prefix
+```
+
+All fields are optional — missing values inherit from the default skin.
+
+**Option B: Built-in skin**
+
+Add to `_BUILTIN_SKINS` dict in `hermes_cli/skin_engine.py`. Use the same schema as above but as a Python dict. Built-in skins ship with the package and are always available.
+
+**Activating:**
+- CLI: `/skin mytheme` or set `display.skin: mytheme` in config.yaml
+- Config: `display: { skin: mytheme }`
+
+See `hermes_cli/skin_engine.py` for the full schema and existing skins as examples.
+
+---
+
+## Cross-Platform Compatibility
+
+Hermes runs on Linux, macOS, and native Windows (plus WSL2). When writing code
+that touches the OS, assume *any* platform can hit your code path.
+
+> **Before you PR:** run `scripts/check-windows-footguns.py` to catch the
+> common Windows-unsafe patterns in your diff. It's grep-based and cheap;
+> CI runs it on every PR too.
+
+### Critical rules
+
+1. **Never call `os.kill(pid, 0)` for liveness checks.** `os.kill(pid, 0)`
+   is a standard POSIX idiom to check "is this PID alive" — the signal 0
+   is a no-op permission check. **On Windows it is NOT a no-op.** Python's
+   Windows `os.kill` maps `sig=0` to `CTRL_C_EVENT` (they collide at the
+   integer value 0) and routes it through `GenerateConsoleCtrlEvent(0, pid)`,
+   which broadcasts Ctrl+C to the **entire console process group** containing
+   the target PID. "Probe if alive" silently becomes "kill the target and
+   often unrelated processes sharing its console." See [bpo-14484](https://bugs.python.org/issue14484)
+   (open since 2012 — will never be fixed for compat reasons).
+
+   **Preferred:** use `psutil` (a core dependency — always available):
+
+   ```python
+   import psutil
+   if psutil.pid_exists(pid):
+       # process is alive — safe on every platform
+       ...
+   ```
+
+   If you specifically need the hermes wrapper (it has a stdlib fallback
+   for scaffold-phase imports before pip install finishes), use
+   `gateway.status._pid_exists(pid)`. It calls `psutil.pid_exists` first
+   and falls back to a hand-rolled `OpenProcess + WaitForSingleObject`
+   dance on Windows only when psutil is somehow missing.
+
+   Audit grep for new callsites: `rg "os\.kill\([^,]+,\s*0\s*\)"`. Any hit
+   in non-test code is presumptively a Windows silent-kill bug.
+
+2. **Use `shutil.which()` before shelling out — don't assume Windows has
+   tools Linux has.** `wmic` was removed in Windows 10 21H1 and later. `ps`,
+   `kill`, `grep`, `awk`, `fuser`, `lsof`, `pgrep`, and most POSIX CLI tools
+   simply don't exist on Windows. Test availability with
+   `shutil.which("tool")` and fall back to a Windows-native equivalent —
+   usually PowerShell via `subprocess.run(["powershell", "-NoProfile",
+   "-Command", ...])`.
+
+   For process enumeration: PowerShell's `Get-CimInstance Win32_Process` is
+   the modern replacement for `wmic process`. See
+   `hermes_cli/gateway.py::_scan_gateway_pids` for the pattern.
+   ```
+
+3. **File encoding.** Windows may save `.env` files in `cp1252`. Always
+   handle encoding errors:
+   ```python
+   try:
+       load_dotenv(env_path)
+   except UnicodeDecodeError:
+       load_dotenv(env_path, encoding="latin-1")
+   ```
+   Config files (`config.yaml`) may be saved with a UTF-8 BOM by Notepad and
+   similar editors — use `encoding="utf-8-sig"` when reading files that
+   could have been touched by a Windows GUI editor.
+
+4. **Process management.** `os.setsid()`, `os.killpg()`, `os.fork()`,
+   `os.getuid()`, and POSIX signal handling differ on Windows. Guard with
+   `platform.system()`, `sys.platform`, or `hasattr(os, "setsid")`:
+   ```python
+   if platform.system() != "Windows":
+       kwargs["preexec_fn"] = os.setsid
+   else:
+       kwargs["creationflags"] = subprocess.CREATE_NEW_PROCESS_GROUP
+   ```
+
+   **Preferred:** for killing a process AND its children (what `os.killpg`
+   does on POSIX), use `psutil` — it works on every platform:
+   ```python
+   import psutil
+   try:
+       parent = psutil.Process(pid)
+       # Kill children first (leaf-up), then the parent.
+       for child in parent.children(recursive=True):
+           child.kill()
+       parent.kill()
+   except psutil.NoSuchProcess:
+       pass
+   ```
+
+5. **Signals that don't exist on Windows: `SIGALRM`, `SIGCHLD`, `SIGHUP`,
+   `SIGUSR1`, `SIGUSR2`, `SIGPIPE`, `SIGQUIT`, `SIGKILL`.** Python's
+   `signal` module raises `AttributeError` at import time if you reference
+   them on Windows. Use `getattr(signal, "SIGKILL", signal.SIGTERM)` or
+   gate the whole block behind a platform check. `loop.add_signal_handler`
+   raises `NotImplementedError` on Windows — always catch it.
+
+6. **Path separators.** Use `pathlib.Path` instead of string concatenation
+   with `/`. Forward slashes work almost everywhere on Windows, but
+   `subprocess.run(["cmd.exe", "/c", ...])` and other shell contexts can
+   require backslashes — convert with `str(path)` at the subprocess boundary,
+   not inside Python logic.
+
+7. **Symlinks need elevated privileges on Windows** (unless Developer Mode is
+   on). Tests that create symlinks need `@pytest.mark.skipif(sys.platform ==
+   "win32", reason="Symlinks require elevated privileges on Windows")`.
+
+8. **POSIX file modes (0o600, 0o644, etc.) are NOT enforced on NTFS** by
+   default. Tests that assert on `stat().st_mode & 0o777` must skip on
+   Windows — the concept doesn't translate. Use ACLs (`icacls`, `pywin32`)
+   for Windows secret-file protection if needed.
+
+9. **Detached background daemons on Windows need `pythonw.exe`, NOT
+    `python.exe`.** `python.exe` always allocates or attaches to a console,
+    which makes it vulnerable to `CTRL_C_EVENT` broadcasts from any sibling
+    process. `pythonw.exe` is the no-console variant. Combine with
+    `CREATE_NO_WINDOW | DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP |
+    CREATE_BREAKAWAY_FROM_JOB` in `subprocess.Popen(creationflags=...)`.
+    See `hermes_cli/gateway_windows.py::_spawn_detached` for the reference
+    implementation.
+
+10. **`subprocess.Popen` with `.cmd` or `.bat` shims needs `shutil.which`
+    to resolve.** Passing `"agent-browser"` to `Popen` on Windows finds
+    the extensionless POSIX shebang shim in `node_modules/.bin/`, which
+    `CreateProcessW` can't execute — you'll get `WinError 193 "not a valid
+    Win32 application"`. Use `shutil.which("agent-browser", path=local_bin)`
+    which honors PATHEXT and picks the `.CMD` variant on Windows.
+
+11. **Don't use shell shebangs as a way to run Python.** `#!/usr/bin/env
+    python` only works when the file is executed through a Unix shell.
+    `subprocess.run(["./myscript.py"])` on Windows fails even if the file
+    has a shebang line. Always invoke Python explicitly:
+    `[sys.executable, "myscript.py"]`.
+
+12. **Shell commands in installers.** If you change `scripts/install.sh`,
+    make the equivalent change in `scripts/install.ps1`. The two scripts
+    are the canonical example of "works on Linux does not mean works on
+    Windows" and have drifted multiple times — keep them in lockstep.
+
+13. **Known paths that are OneDrive-redirected on Windows:** Desktop,
+    Documents, Pictures, Videos. The "real" path when OneDrive Backup is
+    enabled is `%USERPROFILE%\OneDrive\Desktop` (etc.), NOT
+    `%USERPROFILE%\Desktop` (which exists as an empty husk). Resolve the
+    real location via `ctypes` + `SHGetKnownFolderPath` or by reading the
+    `Shell Folders` registry key — never assume `~/Desktop`.
+
+14. **CRLF vs LF in generated scripts.** Windows `cmd.exe` and `schtasks`
+    parse line-by-line; mixed or LF-only line endings can break multi-line
+    `.cmd` / `.bat` files. Use `open(path, "w", encoding="utf-8",
+    newline="\r\n")` — or `open(path, "wb")` + explicit bytes — when
+    generating scripts Windows will execute.
+
+15. **Two different quoting schemes in one command line.** `subprocess.run
+    (["schtasks", "/TR", some_cmd])` → schtasks itself parses `/TR`, AND
+    the `some_cmd` string is re-parsed by `cmd.exe` when the task fires.
+    Different parsers, different escape rules. Use two separate quoting
+    helpers and never cross them. See `hermes_cli/gateway_windows.py::
+    _quote_cmd_script_arg` and `_quote_schtasks_arg` for the reference
+    pair.
+
+### Testing cross-platform
+
+Tests that excercise behavior on specific platforms must run on their target platforms.
+
+```python
+@pytest.mark.linux_only
+@pytest.mark.macos_only
+@pytest.mark.windows_only
+```
+Avoid monkeypatching `sys.platform` unless absolutely needed, but if you do, also patch `platform.system()` / `platform.release()` / `platform.mac_ver()`.
+Symlinks, 0o600 permissions, SIGALRM, os.setsid/fork are all unix-only.
+
+---
+
+## Security Considerations
+
+Hermes has terminal access. Security matters.
+
+### Existing protections
+
+| Layer | Implementation |
+|-------|---------------|
+| **Sudo password piping** | Uses `shlex.quote()` to prevent shell injection |
+| **Dangerous command detection** | Regex patterns in `tools/approval.py` with user approval flow |
+| **Cron prompt injection** | Scanner in `tools/cronjob_tools.py` blocks instruction-override patterns |
+| **Write deny list** | Protected paths (`~/.ssh/authorized_keys`, `/etc/shadow`) resolved via `os.path.realpath()` to prevent symlink bypass |
+| **Skills guard** | Security scanner for hub-installed skills (`tools/skills_guard.py`) |
+| **Code execution sandbox** | `execute_code` child process runs with API keys stripped from environment |
+| **Container hardening** | Docker: all capabilities dropped, no privilege escalation, PID limits, size-limited tmpfs |
+
+### When contributing security-sensitive code
+
+- **Always use `shlex.quote()`** when interpolating user input into shell commands
+- **Resolve symlinks** with `os.path.realpath()` before path-based access control checks
+- **Don't log secrets.** API keys, tokens, and passwords should never appear in log output
+- **Catch broad exceptions** around tool execution so a single failure doesn't crash the agent loop
+- **Test on all platforms** if your change touches file paths, process management, or shell commands
+
+If your PR affects security, note it explicitly in the description.
+
+### Dependency pinning policy (supply chain hardening)
+
+After the [litellm supply chain compromise](https://github.com/BerriAI/litellm/issues/24512) in March 2026 and the [Mini Shai-Hulud worm campaign](https://socket.dev/blog/tanstack-npm-packages-compromised-mini-shai-hulud-supply-chain-attack) in May 2026, all dependencies must follow these rules:
+
+| Source type | Required treatment | Rationale |
+|---|---|---|
+| **PyPI package** | `>=floor,<next_major` | PyPI versions are immutable once published, but new versions can be pushed into your range. A `<next_major` ceiling stops a 1.x install from upgrading to a malicious 2.0.0. |
+| **Git URL** (atroposlib, tinker, yc-bench, Baileys) | Full commit SHA | Branches and tags are mutable refs; SHA is content-addressed. |
+| **GitHub Actions** | Full commit SHA + version comment | Action tags are mutable refs (e.g. tj-actions/changed-files March 2025). Pin as `uses: owner/action@<sha>  # vX.Y.Z` |
+| **CI-only pip installs** | `==exact` | Hermetic CI builds; churn is acceptable. |
+
+**Every new PyPI dependency in a PR must have a `<next_major` upper bound.** PRs adding unbounded `>=X.Y.Z` specs will be rejected by reviewers. The `supply-chain-audit.yml` CI workflow also flags dependency manifest changes for manual review.
+
+**How to determine the ceiling:**
+- If the package is at version `1.x.y`, use `<2`.
+- If the package is at version `0.x.y` (pre-1.0), use `<0.(current_minor + 2)` — e.g. if current is `0.29.x`, use `<0.32`. This gives ~2 minor versions of headroom while keeping the window small enough that a hostile takeover version is unlikely to land inside it.
+- Exception: packages with very stable APIs (e.g. `aiohttp-socks`) can use `<1` at reviewer discretion.
+
+**Examples:**
+```toml
+# ✅ Correct — post-1.0
+"openai>=2.21.0,<3"
+"pydantic>=2.12.5,<3"
+
+# ✅ Correct — pre-1.0 (tight minor window)
+"asyncpg>=0.29,<0.32"
+"aiosqlite>=0.20,<0.23"
+"hindsight-client>=0.4.22,<0.5"
+
+# ❌ Rejected — no upper bound
+"some-package>=1.2.3"
+
+# ❌ Rejected — too tight (blocks legitimate patches)
+"some-package==1.2.3"
+
+# ❌ Rejected — too loose for pre-1.0 (allows 80 minor versions)
+"some-package>=0.20,<1"
+```
+
+**Reference PRs:** #2796 (litellm removal), #2810 (upper bounds pass), #9801 (SHA pinning + supply-chain-audit CI).
+
+---
+
+## Pull Request Process
+
+### Branch naming
+
+```
+fix/description        # Bug fixes
+feat/description       # New features
+docs/description       # Documentation
+test/description       # Tests
+refactor/description   # Code restructuring
+```
+
+### Before submitting
+
+1. **Run tests**: `scripts/run_tests.sh` (recommended; same as CI) or `pytest tests/ -v` with the project venv activated
+2. **Test manually**: Run `hermes` and exercise the code path you changed
+3. **Check cross-platform impact**: If you touch file I/O, process management, or terminal handling, consider macOS, Linux, and WSL2
+4. **Keep PRs focused**: One logical change per PR. Don't mix a bug fix with a refactor with a new feature.
+
+### PR description
+
+Include:
+- **What** changed and **why**
+- **How to test** it (reproduction steps for bugs, usage examples for features)
+- **What platforms** you tested on
+- Reference any related issues
+
+### Commit messages
+
+We use [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+<type>(<scope>): <description>
+```
+
+| Type | Use for |
+|------|---------|
+| `fix` | Bug fixes |
+| `feat` | New features |
+| `docs` | Documentation |
+| `test` | Tests |
+| `refactor` | Code restructuring (no behavior change) |
+| `chore` | Build, CI, dependency updates |
+
+Scopes: `cli`, `gateway`, `tools`, `skills`, `agent`, `install`, `whatsapp`, `security`, etc.
+
+Examples:
+```
+fix(cli): prevent crash in save_config_value when model is a string
+feat(gateway): add WhatsApp multi-user session isolation
+fix(security): prevent shell injection in sudo password piping
+test(tools): add unit tests for file_operations
+```
+
+---
+
+## Reporting Issues
+
+- Use [GitHub Issues](https://github.com/NousResearch/hermes-agent/issues)
+- Include: OS, Python version, Hermes version (`hermes --version`), full error traceback
+- Include steps to reproduce
+- Check existing issues before creating duplicates
+- For security vulnerabilities, please report privately
+
+---
+
+## Community
+
+- **Discord**: [discord.gg/NousResearch](https://discord.gg/NousResearch) — for questions, showcasing projects, and sharing skills
+- **GitHub Discussions**: For design proposals and architecture discussions
+- **Skills Hub**: Upload specialized skills to a registry and share them with the community
+
+---
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE).

Dockerfile

@@ -0,0 +1,465 @@
+# Debian 13 still ships SQLite 3.46.1, which contains the upstream WAL-reset
+# corruption bug. Build a pinned shared library for the runtime image instead
+# of relying on a distro backport that trixie does not currently provide.
+# See #70480 and https://sqlite.org/wal.html#walresetbug.
+FROM debian:13.4 AS sqlite_build
+ARG SQLITE_AUTOCONF_VERSION=3530400
+ARG SQLITE_SHA256=0e9483900e92cd5de8fd48d16bf9200145a61f7fd5be542a5ac81d8a9516eb9c
+RUN apt-get -o Acquire::Retries=3 update && \
+    apt-get -o Acquire::Retries=3 install -y --no-install-recommends \
+        build-essential ca-certificates curl && \
+    rm -rf /var/lib/apt/lists/* && \
+    (curl -fsSL --retry 1 --retry-all-errors --connect-timeout 15 --max-time 60 \
+        -o /tmp/sqlite.tar.gz \
+        "https://sqlite.org/2026/sqlite-autoconf-${SQLITE_AUTOCONF_VERSION}.tar.gz" || \
+     curl -fsSL --retry 3 --retry-all-errors --connect-timeout 15 --max-time 120 \
+        -o /tmp/sqlite.tar.gz \
+        "https://sources.buildroot.net/sqlite/sqlite-autoconf-${SQLITE_AUTOCONF_VERSION}.tar.gz") && \
+    printf '%s  %s\n' "${SQLITE_SHA256}" /tmp/sqlite.tar.gz > /tmp/sqlite.sha256 && \
+    sha256sum -c /tmp/sqlite.sha256 && \
+    tar -xzf /tmp/sqlite.tar.gz -C /tmp && \
+    cd "/tmp/sqlite-autoconf-${SQLITE_AUTOCONF_VERSION}" && \
+    CFLAGS="-O2 \
+        -DSQLITE_ENABLE_FTS3 \
+        -DSQLITE_ENABLE_FTS3_PARENTHESIS \
+        -DSQLITE_ENABLE_FTS4 \
+        -DSQLITE_ENABLE_FTS5 \
+        -DSQLITE_ENABLE_RTREE \
+        -DSQLITE_ENABLE_GEOPOLY \
+        -DSQLITE_ENABLE_COLUMN_METADATA \
+        -DSQLITE_ENABLE_UNLOCK_NOTIFY \
+        -DSQLITE_ENABLE_DBSTAT_VTAB \
+        -DSQLITE_ENABLE_DBPAGE_VTAB \
+        -DSQLITE_ENABLE_MATH_FUNCTIONS \
+        -DSQLITE_ENABLE_PREUPDATE_HOOK \
+        -DSQLITE_ENABLE_SESSION \
+        -DSQLITE_SECURE_DELETE \
+        -DSQLITE_THREADSAFE=1 \
+        -DSQLITE_MAX_VARIABLE_NUMBER=250000" \
+        ./configure --prefix=/opt/sqlite-fixed --disable-static && \
+    make -j"$(nproc)" && \
+    make install
+
+FROM ghcr.io/astral-sh/uv:0.11.6-python3.13-trixie@sha256:b3c543b6c4f23a5f2df22866bd7857e5d304b67a564f4feab6ac22044dde719b AS uv_source
+# Node 26 source stage. Debian trixie's bundled nodejs is pinned to 20.x
+# which reached EOL in April 2026 — we copy node + npm from the upstream
+# node:26 image instead (Hermes pins its toolchain to Node 26 everywhere).
+# Bookworm-based slim image used so the produced binary links
+# against glibc 2.36, which runs cleanly on our Debian 13 (trixie, glibc
+# 2.41) runtime.  Bumping to a new Node major is a one-line ARG change; see
+# #4977.
+FROM node:26-bookworm-slim@sha256:9e6f9357d371591e32ab6f2d8a26d63bdd0d17c29eee3f4f3e7e454d9634bf73 AS node_source
+FROM debian:13.4
+
+# Disable Python stdout buffering to ensure logs are printed immediately.
+# Do not write .pyc files at runtime: /opt/hermes is immutable in the
+# published container and writable state belongs under /opt/data.
+ENV PYTHONUNBUFFERED=1
+ENV PYTHONDONTWRITEBYTECODE=1
+
+# Store Playwright browsers outside the volume mount so the build-time
+# install survives the /opt/data volume overlay at runtime.
+ENV PLAYWRIGHT_BROWSERS_PATH=/opt/hermes/.playwright
+
+# Install system dependencies in one layer, clear APT cache.
+# tini was previously PID 1 to reap orphaned zombie processes (MCP stdio
+# subprocesses, git, bun, etc.) that would otherwise accumulate when hermes
+# ran as PID 1. See #15012. Phase 2 of the s6-overlay supervision plan
+# replaces tini with s6-overlay's /init (PID 1 = s6-svscan), which reaps
+# zombies non-blockingly on SIGCHLD and additionally supervises the main
+# hermes process, the dashboard, and per-profile gateways.
+RUN apt-get -o Acquire::Retries=3 update && \
+    apt-get -o Acquire::Retries=3 install -y --no-install-recommends \
+    ca-certificates curl iputils-ping python3 python-is-python3 ripgrep ffmpeg gcc g++ make cmake python3-dev python3-venv libffi-dev libolm-dev libatomic1 procps git openssh-client docker-cli xz-utils && \
+    rm -rf /var/lib/apt/lists/*
+
+# Prefer the fixed SQLite over Debian's vulnerable libsqlite3.so.0. Keep the
+# public library name stable so both the system interpreter and the uv-created
+# venv resolve the replacement without changing Python import paths.
+COPY --from=sqlite_build /opt/sqlite-fixed/lib/libsqlite3.so.3.53.4 /usr/local/lib/
+RUN ln -sf libsqlite3.so.3.53.4 /usr/local/lib/libsqlite3.so.0 && \
+    ln -sf libsqlite3.so.3.53.4 /usr/local/lib/libsqlite3.so && \
+    printf '/usr/local/lib\n' > /etc/ld.so.conf.d/000-sqlite-fixed.conf && \
+    ldconfig && \
+    python3 -c "import sqlite3, sys; \
+v = sqlite3.sqlite_version_info; \
+sys.exit(f'linked SQLite {sqlite3.sqlite_version} still has the WAL-reset bug') if v < (3, 51, 3) else None; \
+db = sqlite3.connect(':memory:'); \
+db.execute(\"CREATE VIRTUAL TABLE docs USING fts5(content, tokenize='trigram')\"); \
+db.execute(\"INSERT INTO docs VALUES ('hermes')\"); \
+sys.exit('SQLite FTS5 trigram self-test failed') if db.execute(\"SELECT count(*) FROM docs WHERE docs MATCH 'erm'\").fetchone()[0] != 1 else None; \
+db.close()"
+
+# ---------- s6-overlay install ----------
+# s6-overlay provides supervision for the main hermes process, the dashboard,
+# and per-profile gateways. /init becomes PID 1 below — see ENTRYPOINT.
+#
+# Multi-arch: BuildKit auto-populates TARGETARCH (amd64 / arm64). s6-overlay
+# uses tarball names keyed on the kernel arch string (x86_64 / aarch64), so
+# we map between them inline. The noarch + symlinks tarballs are
+# architecture-independent and reused as-is.
+#
+# We use `curl` instead of `ADD` for ALL three tarballs: `ADD` evaluates its
+# URL at parse time (no ARG / TARGETARCH substitution) and — critically for
+# CI reliability — cannot retry, so a single GitHub-release CDN blip fails
+# the whole 15-45 min build. curl -fsSL --retry 3 self-heals those blips,
+# and every tarball is still checksum-verified below before extraction.
+ARG TARGETARCH
+ARG S6_OVERLAY_VERSION=3.2.3.0
+ARG S6_OVERLAY_NOARCH_SHA256=b720f9d9340efc8bb07528b9743813c836e4b02f8693d90241f047998b4c53cf
+ARG S6_OVERLAY_X86_64_SHA256=a93f02882c6ed46b21e7adb5c0add86154f01236c93cd82c7d682722e8840563
+ARG S6_OVERLAY_AARCH64_SHA256=0952056ff913482163cc30e35b2e944b507ba1025d78f5becbb89367bf344581
+ARG S6_OVERLAY_SYMLINKS_SHA256=a60dc5235de3ecbcf874b9c1f18d73263ab99b289b9329aa950e8729c4789f0e
+RUN set -eu; \
+    case "${TARGETARCH:-amd64}" in \
+        amd64) s6_arch="x86_64"; s6_arch_sha="${S6_OVERLAY_X86_64_SHA256}" ;; \
+        arm64) s6_arch="aarch64"; s6_arch_sha="${S6_OVERLAY_AARCH64_SHA256}" ;; \
+        *) echo "Unsupported TARGETARCH=${TARGETARCH} for s6-overlay" >&2; exit 1 ;; \
+    esac; \
+    base="https://github.com/just-containers/s6-overlay/releases/download/v${S6_OVERLAY_VERSION}"; \
+    curl -fsSL --retry 3 -o /tmp/s6-overlay-noarch.tar.xz \
+        "${base}/s6-overlay-noarch.tar.xz"; \
+    curl -fsSL --retry 3 -o /tmp/s6-overlay-symlinks-noarch.tar.xz \
+        "${base}/s6-overlay-symlinks-noarch.tar.xz"; \
+    curl -fsSL --retry 3 -o /tmp/s6-overlay-arch.tar.xz \
+        "${base}/s6-overlay-${s6_arch}.tar.xz"; \
+    { \
+        printf '%s  %s\n' "${S6_OVERLAY_NOARCH_SHA256}" /tmp/s6-overlay-noarch.tar.xz; \
+        printf '%s  %s\n' "${s6_arch_sha}" /tmp/s6-overlay-arch.tar.xz; \
+        printf '%s  %s\n' "${S6_OVERLAY_SYMLINKS_SHA256}" /tmp/s6-overlay-symlinks-noarch.tar.xz; \
+    } > /tmp/s6-overlay.sha256; \
+    sha256sum -c /tmp/s6-overlay.sha256; \
+    tar -C / -Jxpf /tmp/s6-overlay-noarch.tar.xz; \
+    tar -C / -Jxpf /tmp/s6-overlay-arch.tar.xz; \
+    tar -C / -Jxpf /tmp/s6-overlay-symlinks-noarch.tar.xz; \
+    rm /tmp/s6-overlay-*.tar.xz /tmp/s6-overlay.sha256
+
+# #34192 / #66679: backward-compat shim for orchestration templates that
+# still reference the legacy /usr/bin/tini entrypoint (Hostinger's
+# 'Hermes WebUI' catalog, NAS compose projects that preserve an old
+# entrypoint on image update, etc.). A plain symlink to /init made the
+# path exist, but forwarded tini flags like `-g` into s6-overlay's
+# rc.init as the container CMD (`rc.init: 91: -g: not found`) and
+# boot-looped any `restart: unless-stopped` deploy. The shim strips the
+# tini CLI surface, then exec's /init + main-wrapper — see
+# docker/tini-shim.sh. Safe to drop once the affected catalogs are
+# updated.
+COPY --chmod=0755 docker/tini-shim.sh /usr/bin/tini
+
+# Non-root user for runtime; UID can be overridden via HERMES_UID at runtime
+RUN useradd -u 10000 -m -d /opt/data hermes
+
+COPY --chmod=0755 --from=uv_source /usr/local/bin/uv /usr/local/bin/uvx /usr/local/bin/
+
+# Node 26: copy the node binary plus the bundled npm JS install from the
+# upstream image.  npm and npx are recreated as symlinks because they're
+# symlinks in the source image (and need to live on PATH).
+#
+# No corepack: Node unbundled it upstream, so node:26 ships only npm in
+# /usr/local/lib/node_modules.  Nothing here needs it — no package.json
+# declares a `packageManager`, and no build step shells out to yarn or pnpm.
+#
+# See node_source stage at the top of the file for the version-bump
+# rationale (#4977).
+COPY --chmod=0755 --from=node_source /usr/local/bin/node /usr/local/bin/
+COPY --from=node_source /usr/local/lib/node_modules/npm /usr/local/lib/node_modules/npm
+RUN ln -sf /usr/local/lib/node_modules/npm/bin/npm-cli.js /usr/local/bin/npm && \
+    ln -sf /usr/local/lib/node_modules/npm/bin/npx-cli.js /usr/local/bin/npx
+
+WORKDIR /opt/hermes
+
+# ---------- Layer-cached dependency install ----------
+# Copy only package manifests first so npm install + Playwright are cached
+# unless the lockfiles themselves change.
+#
+# ui-tui/packages/hermes-ink/ is copied IN FULL (not just its manifests)
+# because it is referenced as a `file:` workspace dependency from
+# ui-tui/package.json.  Copying the tree up front lets npm resolve the
+# workspace to real content instead of stopping at a bare package.json.
+COPY package.json package-lock.json ./
+COPY web/package.json web/
+COPY ui-tui/package.json ui-tui/
+COPY ui-tui/packages/hermes-ink/ ui-tui/packages/hermes-ink/
+# apps/shared/ is copied IN FULL because web/package.json references it as a
+# `file:` workspace dependency (same pattern as hermes-ink above).
+COPY apps/shared/ apps/shared/
+
+# `npm_config_install_links=false` forces npm to install `file:` deps as
+# symlinks instead of copies.  This is the default since npm 10+, which is
+# what the image ships now (via the node:22 source stage).  We set it
+# explicitly anyway as defense-in-depth: the previous Debian-bundled npm
+# 9.x defaulted to install-as-copy, which produced a hidden
+# node_modules/.package-lock.json that permanently disagreed with the root
+# lock on the @hermes/ink entry, tripped the TUI launcher's
+# `_tui_need_npm_install()` check on every startup, and triggered a
+# runtime `npm install` that then failed with EACCES.  Keeping the env
+# guards against a future regression if the source npm version changes.
+ENV npm_config_install_links=false
+
+RUN npm install --prefer-offline --no-audit --fetch-retries=5 && \
+    for i in 1 2 3; do \
+        npx playwright install --with-deps chromium --only-shell && break || \
+        { [ "$i" = 3 ] && exit 1; echo "playwright install failed (attempt $i); retrying in 10s"; sleep 10; }; \
+    done && \
+    npm cache clean --force
+
+# ---------- Photon iMessage sidecar deps (baked, NS-606) ----------
+# The photon plugin's Node sidecar needs its own node_modules
+# (spectrum-ts). The install tree is immutable at runtime, so a lazy
+# `npm ci` on first connect would hit EROFS — bake the deps here instead
+# (deterministic installs, NS-559). The patch script is copied alongside
+# the manifests because package.json's postinstall runs it, which also
+# means the spectrum-ts patch is applied at build time. Layer-cached:
+# only re-runs when the sidecar manifests/patch change.
+COPY plugins/platforms/photon/sidecar/package.json \
+     plugins/platforms/photon/sidecar/package-lock.json \
+     plugins/platforms/photon/sidecar/patch-spectrum-mixed-attachments.mjs \
+     plugins/platforms/photon/sidecar/
+RUN cd plugins/platforms/photon/sidecar && \
+    npm ci --no-audit --fetch-retries=5 && \
+    npm cache clean --force
+
+# ---------- Layer-cached Python dependency install ----------
+# Copy only pyproject.toml + uv.lock so the Python dep resolve + wheel
+# download + native-extension compile layer is cached unless those inputs
+# change.  Before this split the Python install sat after `COPY . .`, so
+# every source-only commit re-did ~4-5 min of dep work on cold builds.
+#
+# README.md is referenced by pyproject.toml's `readme =` field, but it's
+# excluded from the build context by .dockerignore's `*.md`.  uv's build
+# frontend stats the readme path during dep resolution, so we `touch` an
+# empty placeholder — the real README is restored by `COPY . .` below.
+#
+# `uv sync --frozen --no-install-project --extra all --extra messaging --extra otlp`
+# installs the deps reachable through the composite `[all]` extra
+# (handpicked set intended for the production image — excludes `[dev]`),
+# plus gateway messaging adapters that should work in the published image
+# without a first-boot lazy install.  We do NOT use `--all-extras`:
+# that would pull in `[rl]` (atroposlib + tinker + torch + wandb from
+# git), `[yc-bench]` (another git dep), and `[termux-all]` (Android
+# redundancy), none of which belong in the published container.
+#
+# Provider packages (anthropic, bedrock, azure-identity) are included
+# so Docker users can use these providers without requiring runtime
+# lazy-install access to PyPI (often blocked in containerized envs).
+#
+# The [otlp] extra contains the SDK/exporter imported by Hermes when Gateway
+# Health export is enabled. Collector and observability-backend dependencies
+# remain external and are not part of the Hermes production image.
+#
+# The hindsight memory provider's client (hindsight-client) is baked in
+# for the same reason: it lazy-installs into /opt/hermes/.venv at first
+# use, which lives inside the (immutable) image layer rather than the
+# mounted /opt/data volume, so it is lost on every container recreate /
+# image update and recall/retain then fails with
+# `ModuleNotFoundError: No module named 'hindsight_client'` (#38128).
+#
+# The Matrix gateway's deps ([matrix] extra) are baked in because
+# python-olm (transitive via mautrix[encryption]) builds from source on
+# Python/image combinations without usable wheels.  The Docker image is
+# Linux-only, so keeping the native libolm/build-toolchain packages here
+# avoids the cross-platform failures that kept [matrix] out of [all]
+# while still making Matrix work in the published container. Fixes #30399.
+#
+# The editable link is created after the source copy below.
+COPY pyproject.toml uv.lock ./
+RUN touch ./README.md
+RUN uv sync --frozen --no-install-project --extra all --extra messaging --extra otlp --extra anthropic --extra bedrock --extra azure-identity --extra hindsight --extra matrix
+
+# ---------- Frontend build (cached independently from Python source) ----------
+# Copy only the frontend source trees first so that Python-only changes don't
+# invalidate the (relatively slow) web + ui-tui build layer.
+COPY web/ web/
+COPY ui-tui/ ui-tui/
+COPY apps/shared/ apps/shared/
+RUN cd web && npm run build && \
+    cd ../ui-tui && npm run build
+
+# ---------- Source code ----------
+# .dockerignore excludes node_modules, so the installs above survive.
+# --link decouples this layer from parents for cache purposes; --chmod bakes
+# the final read-only permissions at copy time so we skip the separate
+# `chmod -R` pass that previously walked ~30k files across the venv +
+# node_modules + source (21s amd64 / 222s arm64 — #49113).  `a+rX,go-w`
+# gives the non-root hermes user read + traverse but no write; root retains
+# write so the build steps below don't need chmod u+w dances.
+COPY --link --chmod=a+rX,go-w . .
+
+# ---------- Permissions ----------
+# Link hermes-agent itself (editable). Deps are already installed in the
+# cached layer above; `--no-deps` makes this a fast egg-link creation with no
+# resolution or downloads.
+RUN uv pip install --no-cache-dir --no-deps -e "."
+
+# Wire the exec shim and install-method stamp.  Files under /opt/hermes are
+# already root-owned (COPY, uv sync, npm install all run as root) and
+# read-only for the hermes user (go-w from the --chmod above).
+
+USER root
+RUN mkdir -p /opt/hermes/bin && \
+    cp /opt/hermes/docker/hermes-exec-shim.sh /opt/hermes/bin/hermes && \
+    chmod 0755 /opt/hermes /opt/hermes/bin/hermes && \
+    printf 'docker\n' > /opt/hermes/.install_method
+# The ``.install_method`` stamp is baked next to the running code (the install
+# tree), NOT into $HERMES_HOME. $HERMES_HOME (/opt/data) is a shared data
+# volume that is commonly bind-mounted from the host and even shared with a
+# host-side Desktop/CLI install; stamping it at boot used to clobber that
+# host install's marker and wrongly block its ``hermes update``. A code-scoped
+# stamp is read first by detect_install_method() and is immune to the share.
+# Start as root so the s6-overlay stage2 hook can usermod/groupmod and chown
+# the data volume. Each supervised service then drops to the hermes user via
+# `s6-setuidgid hermes` in its run script. If HERMES_UID is unset, services
+# run as the default hermes user (UID 10000).
+
+# ---------- Bake image provenance + build-time git revision ----------
+# The versioned, non-secret provenance marker is the authoritative runtime
+# signal that this filesystem came from an immutable image.  It deliberately
+# lives outside both /opt/hermes (which operators sometimes bind-mount as a
+# checkout) and /opt/data (the mutable HERMES_HOME volume).
+# .dockerignore excludes .git, so `git rev-parse HEAD` from inside the
+# container always returns nothing — meaning `hermes dump` reports
+# "(unknown)" and the startup banner drops its `· upstream <sha>` suffix.
+# That makes support triage from container bug reports impossible:
+# we can't tell which commit the user is actually running.
+#
+# Fix: write the commit SHA passed via the HERMES_GIT_SHA build-arg to
+# /opt/hermes/.hermes_build_sha at build time, and have
+# hermes_cli/build_info.py read it at runtime.  Both `hermes dump` and
+# banner.get_git_banner_state() try the baked SHA first, then fall back
+# to live `git rev-parse` for source installs (unchanged behaviour).
+#
+# The arg is optional — local `docker build` without --build-arg omits the
+# SHA file (and records a null provenance revision), so build-info falls back
+# to live-git lookup.  CI
+# (.github/workflows/docker.yml) passes ${{ github.sha }} so
+# every published image has it.
+ARG HERMES_GIT_SHA=
+RUN set -eu; \
+    if [ -n "${HERMES_GIT_SHA}" ]; then \
+        printf '%s\n' "${HERMES_GIT_SHA}" > /opt/hermes/.hermes_build_sha; \
+    fi; \
+    mkdir -p /etc/hermes; \
+    HERMES_GIT_SHA="${HERMES_GIT_SHA}" python3 -c 'import json, os, pathlib, tomllib; project = tomllib.loads(pathlib.Path("/opt/hermes/pyproject.toml").read_text(encoding="utf-8"))["project"]; marker = pathlib.Path("/etc/hermes/image-provenance.json"); marker.write_text(json.dumps({"schema": 1, "deployment_kind": "image", "manager": "docker", "image": "nousresearch/hermes-agent", "version": project["version"], "revision": os.environ.get("HERMES_GIT_SHA") or None}, sort_keys=True, separators=(",", ":")) + "\n", encoding="utf-8"); marker.chmod(0o444)'
+
+# ---------- s6-overlay service wiring ----------
+# Static services declared at build time: main-hermes + dashboard.
+# Per-profile gateway services are registered dynamically at runtime by
+# the profile create/delete hooks (Phase 4); they live under
+# /run/service/ (tmpfs) and are reconciled on container restart by
+# /etc/cont-init.d/02-reconcile-profiles (Phase 4 Task 4.0).
+COPY docker/s6-rc.d/ /etc/s6-overlay/s6-rc.d/
+
+# stage2-hook handles UID/GID remap, volume chown, config seeding,
+# skills sync — all the work the old entrypoint.sh did before
+# `exec hermes`. Wired in as cont-init.d/01- so it
+# runs before user services start.
+#
+# 02-reconcile-profiles re-creates per-profile gateway s6 service
+# slots from $HERMES_HOME/profiles/<name>/ after a container restart
+# (the /run/service/ scandir is tmpfs and wiped on restart). Phase 4.
+RUN mkdir -p /etc/cont-init.d && \
+    printf '#!/command/with-contenv sh\nexec /opt/hermes/docker/stage2-hook.sh\n' \
+        > /etc/cont-init.d/01-hermes-setup && \
+    chmod +x /etc/cont-init.d/01-hermes-setup
+COPY --chmod=0755 docker/cont-init.d/015-supervise-perms /etc/cont-init.d/015-supervise-perms
+COPY --chmod=0755 docker/cont-init.d/02-reconcile-profiles /etc/cont-init.d/02-reconcile-profiles
+
+# ---------- Runtime ----------
+ENV HERMES_WEB_DIST=/opt/hermes/hermes_cli/web_dist
+# Point the TUI launcher at the prebuilt bundle baked at build time (Layer 8:
+# `ui-tui && npm run build`). This makes _make_tui_argv take the prebuilt-bundle
+# fast path (`node --expose-gc /opt/hermes/ui-tui/dist/entry.js`) and skip the
+# _tui_need_npm_install / runtime `npm install` branch entirely — exactly the
+# nix/packaged-release path the launcher was designed for.
+#
+# Why this is required (not just an optimization): the root package-lock.json
+# describes the WHOLE monorepo workspace set (root + web + ui-tui + apps/*),
+# but the image only installs root/web/ui-tui (apps/* — the desktop app — is
+# never `npm install`ed here). So the actualized node_modules permanently
+# disagrees with the canonical lock, _tui_need_npm_install() returns True on
+# every launch, and the runtime `npm install` it triggers (a) can never
+# converge against the partial monorepo and (b) races itself across concurrent
+# embedded-chat (/api/pty) connections → ENOTEMPTY → the chat tab dies with a
+# 502 / "[session ended]". Pointing at the prebuilt bundle sidesteps the whole
+# check. (A separate launcher hardening is tracked independently.)
+ENV HERMES_TUI_DIR=/opt/hermes/ui-tui
+ENV HERMES_HOME=/opt/data
+ENV HERMES_WRITE_SAFE_ROOT=/opt/data
+ENV HERMES_DISABLE_LAZY_INSTALLS=1
+# The published image seals /opt/hermes (root-owned, read-only) so a runtime
+# lazy install can't mutate the agent's own venv and brick it. But opt-in
+# backends (Firecrawl web search, Exa, Feishu, …) keep their SDKs in
+# tools/lazy_deps.py — deliberately NOT baked into [all] (see pyproject.toml
+# policy 2026-05-12: one quarantined release must not break every install).
+# Redirect those lazy installs to a writable dir on the durable data volume.
+# lazy_deps appends this dir to the END of sys.path, so a package installed
+# here can only ADD modules — it can never shadow or downgrade a core module,
+# so the sealed-venv guarantee holds even with installs re-enabled. The dir
+# is seeded + chowned to the hermes user by docker/stage2-hook.sh and lives
+# on the /opt/data volume, so it persists across container recreates / image
+# updates (an ABI stamp invalidates it if a rebuild bumps the interpreter).
+ENV HERMES_LAZY_INSTALL_TARGET=/opt/data/lazy-packages
+
+# `docker exec` privilege-drop shim. When operators run
+# `docker exec <c> hermes ...` they default to root, and any file the
+# command writes under $HERMES_HOME (auth.json, .env, config.yaml) ends
+# up root-owned and unreadable to the supervised gateway (UID 10000).
+# The shim lives at /opt/hermes/bin/hermes, sits earliest on PATH, and
+# transparently re-exec's the real venv binary via `s6-setuidgid hermes`
+# when invoked as root. Non-root callers (supervised processes,
+# `--user hermes`, etc.) hit the short-circuit path with no overhead.
+# Recursion is impossible because the shim exec's the venv binary by
+# absolute path (/opt/hermes/.venv/bin/hermes). See the shim source for
+# the opt-out env var (HERMES_DOCKER_EXEC_AS_ROOT=1).
+COPY --chmod=0755 docker/hermes-exec-shim.sh /opt/hermes/bin/hermes
+COPY --chmod=0755 docker/entrypoint-dispatch.sh /opt/hermes/docker/entrypoint-dispatch.sh
+
+# Pre-s6 entrypoint.sh did `source .venv/bin/activate` which exported
+# the venv bin onto PATH; Architecture B's main-wrapper.sh does the
+# same for the container's main process, but `docker exec` and our
+# cont-init.d scripts don't pass through the wrapper. Expose the venv
+# bin globally so `docker exec <container> hermes ...` and any
+# subprocess that doesn't activate the venv first still find hermes.
+#
+# /opt/hermes/bin is prepended ahead of the venv so the privilege-drop
+# shim wins PATH resolution. The shim's last act is to exec the venv
+# binary by absolute path, so this PATH ordering is transparent to
+# every other consumer.
+ENV PATH="/opt/hermes/bin:/opt/hermes/.venv/bin:/opt/data/.local/bin:${PATH}"
+RUN mkdir -p /opt/data
+VOLUME [ "/opt/data" ]
+
+# The image ENTRYPOINT is a tiny dispatcher rather than `/init` directly.
+# When the image really owns PID 1 (normal Docker / Podman), the dispatcher
+# execs `/init` and preserves the full s6 supervision tree. When a platform
+# wraps the image entrypoint under its own PID-1 init (Fly Machines,
+# `docker run --init`, some schedulers), `/init` would abort with
+# `can only run as pid 1`; in that case the dispatcher falls back to
+# `stage2-hook.sh` + `main-wrapper.sh` directly so foreground commands still
+# work. See #38349.
+#
+# On the PID-1 path, s6-overlay's /init sets up the supervision tree, runs
+# /etc/cont-init.d/* (our stage2 hook), starts s6-rc services declared in
+# /etc/s6-overlay/s6-rc.d/, then exec's its remaining argv as the container's
+# "main program" with stdin/stdout/stderr inherited (this is what makes
+# interactive --tui work). When the main program exits, /init begins stage 3
+# shutdown and the container exits with the program's exit code. Replaces
+# tini — see Phase 2 of docs/plans/2026-05-07-s6-overlay-dynamic-subagent-gateways.md.
+#
+# We use the ENTRYPOINT+CMD split rather than CMD alone so the
+# wrapper is prepended to user-supplied args automatically:
+#
+#   docker run <image>                  → entrypoint-dispatch.sh   (CMD default)
+#   docker run <image> chat -q "hi"     → entrypoint-dispatch.sh chat -q hi
+#   docker run <image> sleep infinity   → entrypoint-dispatch.sh sleep infinity
+#   docker run <image> --tui            → entrypoint-dispatch.sh --tui
+#
+# main-wrapper.sh handles arg routing (bare-exec vs. hermes
+# subcommand vs. no-args), drops to the hermes user via s6-setuidgid,
+# and exec's the final program so its exit code becomes the container
+# exit code. The dispatcher preserves that contract across both the
+# supervised PID-1 path and the non-PID-1 fallback path. Without the
+# wrapper-as-ENTRYPOINT, leading-dash args like `--version` would be
+# intercepted by /init's POSIX shell.
+ENTRYPOINT [ "/opt/hermes/docker/entrypoint-dispatch.sh" ]
+CMD [ ]

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Nous Research
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.AITURK.md

@@ -0,0 +1,55 @@
+# AITURK IDE
+
+TurkServis'in Hermes Agent tabanlı masaüstü geliştirme ortamı.
+
+- Ürün sürümü: **1.0.0-beta.1**, ilk paket hedefi Windows x64.
+- Varsayılan dil Türkçe; ayarlardan diğer dillere geçilebilir.
+- İlk kurulum, sohbet, dosyalar, terminal ve temel ayarlar Türkçeleştirilmiştir.
+  Henüz çevrilmeyen gelişmiş ekranlar ve üçüncü taraf eklentiler İngilizceye döner.
+- AITURK logosu, turkuaz tema, ayrı uygulama kimliği ve veri dizini kullanılır.
+- TurkServis bağlantısı `https://ai.turkservis.online/v1` üzerinden kullanıcının
+  kendi API anahtarını doğrular ve hesabına açık modelleri dinamik olarak getirir.
+  Kaynakta veya kurulum paketinde müşteri API anahtarı bulunmaz.
+- Bu bağlantı model sağlayıcısıdır; yerel ajan ve dosya araçları bilgisayarda
+  çalışır. Uzak Hermes gateway bağlantısı farklı bir özelliktir.
+
+## Veri ve güncellemeler
+
+Windows ajan verisi `%LOCALAPPDATA%/TurkServis/AITURK-IDE/agent` altında tutulur.
+`AITURK_IDE_HOME` açıkça başka bir konum seçmek için kullanılabilir.
+Mevcut Hermes kurulumu ve `HERMES_HOME` dizini otomatik olarak devralınmaz.
+Masaüstü kurulum aşaması küresel `hermes` komutunu değiştirmez.
+
+Paketli uygulama güncellemeleri resmî AITURK paketleriyle yapılır; Hermes kaynak
+güncellemesi masaüstü markasını değiştiremez. Kaldırma Windows uygulama
+yöneticisinden yapılır; ajan verisi ayrıca silinmedikçe korunur.
+
+## Geliştirme ve doğrulama
+
+Node.js sürümü için `apps/desktop/package.json` içindeki `engines` alanını kullanın.
+Depo kökünde bağımlılıkları kurun; masaüstü alt klasöründe ayrı kurulum yapmayın.
+
+```sh
+npm ci
+npm run typecheck --workspace=apps/desktop
+npm run test --workspace=apps/desktop -- electron/aiturk-product.test.ts src/i18n/tr.test.tsx src/i18n/runtime.test.ts src/i18n/languages.test.ts src/i18n/plugin-i18n.test.tsx src/components/onboarding/aiturk-provider.test.tsx
+npm run build --workspace=apps/desktop
+npm run builder --workspace=apps/desktop -- --win nsis --x64 --publish never
+```
+
+Dağıtılacak derleme temiz, yayımlanmış Git commit'inden üretilmelidir. İlk açılış
+ajan kurulumunu paketteki `install-stamp.json` commit'ine sabitler. Windows
+imzası ve temiz kurulum doğrulanmadan bir paket doğrulanmış üretim sürümü diye
+sunulmamalıdır. macOS ve Linux paketleri bu beta kapsamında doğrulanmamıştır.
+
+## Lisans ve kaynak
+
+Bu çatal Apache-2.0 değil **MIT** lisanslıdır. Asıl kaynak:
+[NousResearch/hermes-agent](https://github.com/NousResearch/hermes-agent),
+temel commit `63279301bcbdc185c1b07b98a9312eb0c862f26d`.
+Nous Research telif bildirimi ve MIT metni [LICENSE](LICENSE) dosyasında korunur;
+paket ayrıca `assets/NOTICE.txt` ve `assets/LICENSE.txt` içerir.
+AITURK/TurkServis dağıtımı Nous Research tarafından onaylanmış bir ürün değildir.
+
+[AITURK kaynak deposu](https://gitea.twinpay.one/yilsem/aiturk-hermes-ide)
+· [TurkServis](https://turkservis.online)

README.es.md

@@ -0,0 +1,220 @@
+<p align="center">
+  <img src="assets/banner.png" alt="Hermes Agent" width="100%">
+</p>
+
+# Hermes Agent ☤
+<p align="center">
+  <a href="https://hermes-agent.nousresearch.com/">Hermes Agent</a> | <a href="https://hermes-agent.nousresearch.com/">Hermes Desktop</a>
+</p>
+<p align="center">
+  <a href="https://hermes-agent.nousresearch.com/docs/"><img src="https://img.shields.io/badge/Docs-hermes--agent.nousresearch.com-FFD700?style=for-the-badge" alt="Documentación"></a>
+  <a href="https://discord.gg/NousResearch"><img src="https://img.shields.io/badge/Discord-5865F2?style=for-the-badge&logo=discord&logoColor=white" alt="Discord"></a>
+  <a href="https://github.com/NousResearch/hermes-agent/blob/main/LICENSE"><img src="https://img.shields.io/badge/Licencia-MIT-green?style=for-the-badge" alt="Licencia: MIT"></a>
+  <a href="https://nousresearch.com"><img src="https://img.shields.io/badge/Creado%20por-Nous%20Research-blueviolet?style=for-the-badge" alt="Creado por Nous Research"></a>
+  <a href="README.md"><img src="https://img.shields.io/badge/Lang-English-blue?style=for-the-badge" alt="English"></a>
+  <a href="README.zh-CN.md"><img src="https://img.shields.io/badge/Lang-中文-red?style=for-the-badge" alt="中文"></a>
+  <a href="README.ur-pk.md"><img src="https://img.shields.io/badge/Lang-اردو-green?style=for-the-badge" alt="اردو"></a>
+</p>
+
+**El agente de IA con mejora continua creado por [Nous Research](https://nousresearch.com).** Es el único agente con un bucle de aprendizaje integrado: crea habilidades a partir de la experiencia, las mejora durante el uso, se impulsa a sí mismo a persistir el conocimiento, busca en sus propias conversaciones pasadas y construye un modelo cada vez más profundo de quién eres a lo largo de las sesiones. Ejecútalo en un VPS de $5, un clúster de GPUs o infraestructura sin servidor que cuesta casi nada cuando está inactivo. No está atado a tu laptop — habla con él desde Telegram mientras trabaja en una VM en la nube.
+
+Usa cualquier modelo que quieras — [Nous Portal](https://portal.nousresearch.com), [OpenRouter](https://openrouter.ai) (más de 200 modelos), [NovitaAI](https://novita.ai), [NVIDIA NIM](https://build.nvidia.com) (Nemotron), [Xiaomi MiMo](https://platform.xiaomimimo.com), [z.ai/GLM](https://z.ai), [Kimi/Moonshot](https://platform.moonshot.ai), [MiniMax](https://www.minimax.io), [Hugging Face](https://huggingface.co), OpenAI, o tu propio endpoint. Cambia con `hermes model` — sin cambios de código, sin dependencias.
+
+<table>
+<tr><td><b>Una interfaz de terminal real</b></td><td>TUI completa con edición multilínea, autocompletado de comandos, historial de conversaciones, interrupción y redirección, y salida de herramientas en streaming.</td></tr>
+<tr><td><b>Vive donde tú vives</b></td><td>Telegram, Discord, Slack, WhatsApp, Signal y CLI — todo desde un único proceso gateway. Transcripción de notas de voz, continuidad de conversación entre plataformas.</td></tr>
+<tr><td><b>Un bucle de aprendizaje cerrado</b></td><td>Memoria curada por el agente con recordatorios periódicos. Creación autónoma de habilidades tras tareas complejas. Las habilidades mejoran solas durante el uso. Búsqueda FTS5 de sesiones con resumención por LLM para recuperación entre sesiones. Modelado de usuario dialéctico <a href="https://github.com/plastic-labs/honcho">Honcho</a>. Compatible con el estándar abierto de <a href="https://agentskills.io">agentskills.io</a>.</td></tr>
+<tr><td><b>Automatizaciones programadas</b></td><td>Planificador cron integrado con entrega a cualquier plataforma. Informes diarios, copias de seguridad nocturnas, auditorías semanales — todo en lenguaje natural, ejecutándose de forma autónoma.</td></tr>
+<tr><td><b>Delega y paraleliza</b></td><td>Lanza subagentes aislados para flujos de trabajo paralelos. Escribe scripts de Python que llaman a herramientas vía RPC, convirtiendo pipelines de múltiples pasos en turnos de coste cero de contexto.</td></tr>
+<tr><td><b>Funciona en cualquier lugar, no solo en tu laptop</b></td><td>Seis backends de terminal — local, Docker, SSH, Singularity, Modal y Daytona. Daytona y Modal ofrecen persistencia sin servidor — el entorno de tu agente hiberna cuando está inactivo y se activa bajo demanda, costando casi nada entre sesiones. Ejecútalo en un VPS de $5 o un clúster de GPUs.</td></tr>
+<tr><td><b>Listo para investigación</b></td><td>Generación de trayectorias en lote, compresión de trayectorias para entrenar la próxima generación de modelos de llamadas a herramientas.</td></tr>
+</table>
+
+---
+
+## Instalación rápida
+
+### Linux, macOS, WSL2, Termux
+
+```bash
+curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
+```
+
+### Windows (nativo, PowerShell)
+
+> **Nota:** En Windows nativo, Hermes funciona sin WSL — la CLI, el gateway, la TUI y las herramientas funcionan de forma nativa. Si prefieres usar WSL2, el comando de Linux/macOS de arriba también funciona allí. ¿Encontraste un error? Por favor [crea un issue](https://github.com/NousResearch/hermes-agent/issues).
+
+Ejecuta esto en PowerShell:
+
+```powershell
+iex (irm https://hermes-agent.nousresearch.com/install.ps1)
+```
+
+El instalador se encarga de todo: uv, Python 3.11, Node.js, ripgrep, ffmpeg, **y un Git Bash portátil** (MinGit, descomprimido en `%LOCALAPPDATA%\hermes\git` — no requiere administrador, completamente aislado de cualquier instalación de Git del sistema). Hermes usa este Git Bash incluido para ejecutar comandos de shell.
+
+Si ya tienes Git instalado, el instalador lo detecta y lo usa en su lugar. De lo contrario, una descarga de ~45MB de MinGit es todo lo que necesitas — no tocará ni interferirá con ningún Git del sistema.
+
+> **Android / Termux:** La ruta manual probada está documentada en la [guía de Termux](https://hermes-agent.nousresearch.com/docs/getting-started/termux). En Termux, Hermes instala el extra `.[termux]` curado porque el extra completo `.[all]` actualmente incluye dependencias de voz incompatibles con Android.
+>
+> **Windows:** Windows nativo es totalmente compatible — el comando de PowerShell de arriba instala todo. Si prefieres usar WSL2, el comando de Linux también funciona allí. La instalación nativa de Windows se encuentra en `%LOCALAPPDATA%\hermes`; WSL2 instala en `~/.hermes` como en Linux.
+
+Después de la instalación:
+
+```bash
+source ~/.bashrc    # recargar shell (o: source ~/.zshrc)
+hermes              # ¡empieza a chatear!
+```
+
+---
+
+## Primeros pasos
+
+```bash
+hermes              # CLI interactiva — inicia una conversación
+hermes model        # Elige tu proveedor y modelo LLM
+hermes tools        # Configura qué herramientas están habilitadas
+hermes config set   # Establece valores de configuración individuales
+hermes gateway      # Inicia el gateway de mensajería (Telegram, Discord, etc.)
+hermes setup        # Ejecuta el asistente de configuración completo
+hermes claw migrate # Migra desde OpenClaw (si vienes de OpenClaw)
+hermes update       # Actualiza a la última versión
+hermes doctor       # Diagnostica cualquier problema
+```
+
+📖 **[Documentación completa →](https://hermes-agent.nousresearch.com/docs/)**
+
+---
+
+## Evita la colección de claves API — Nous Portal
+
+Hermes funciona con cualquier proveedor que quieras — eso no cambiará. Pero si prefieres no recopilar cinco claves API separadas para el modelo, búsqueda web, generación de imágenes, TTS y un navegador en la nube, **[Nous Portal](https://portal.nousresearch.com)** las cubre todas bajo una sola suscripción:
+
+- **Más de 300 modelos** — elige cualquiera con `/model <nombre>`
+- **Tool Gateway** — búsqueda web (Firecrawl), generación de imágenes (FAL), texto a voz (OpenAI), navegador en la nube (Browser Use), todo enrutado a través de tu suscripción. Sin cuentas adicionales.
+
+Un comando desde una instalación nueva:
+
+```bash
+hermes setup --portal
+```
+
+Esto te autentica vía OAuth, establece Nous como tu proveedor y activa el Tool Gateway. Comprueba qué está conectado en cualquier momento con `hermes portal info`. Detalles completos en la [página de documentación del Tool Gateway](https://hermes-agent.nousresearch.com/docs/user-guide/features/tool-gateway).
+
+Puedes seguir usando tus propias claves por herramienta cuando quieras — el gateway es por backend, no todo o nada.
+
+---
+
+## Referencia rápida: CLI vs Mensajería
+
+Hermes tiene dos puntos de entrada: inicia la interfaz de terminal con `hermes`, o ejecuta el gateway y habla con él desde Telegram, Discord, Slack, WhatsApp, Signal o Email. Una vez en una conversación, muchos comandos de barra son compartidos entre ambas interfaces.
+
+| Acción                              | CLI                                           | Plataformas de mensajería                                                         |
+| ----------------------------------- | --------------------------------------------- | --------------------------------------------------------------------------------- |
+| Empezar a chatear                   | `hermes`                                      | Ejecuta `hermes gateway setup` + `hermes gateway start`, luego envía un mensaje al bot |
+| Nueva conversación                  | `/new` o `/reset`                             | `/new` o `/reset`                                                                 |
+| Cambiar modelo                      | `/model [proveedor:modelo]`                   | `/model [proveedor:modelo]`                                                       |
+| Establecer personalidad             | `/personality [nombre]`                       | `/personality [nombre]`                                                           |
+| Reintentar o deshacer último turno  | `/retry`, `/undo`                             | `/retry`, `/undo`                                                                 |
+| Comprimir contexto / ver uso        | `/compress`, `/usage`, `/insights [--days N]` | `/compress`, `/usage`, `/insights [days]`                                         |
+| Explorar habilidades                | `/skills` o `/<nombre-habilidad>`             | `/<nombre-habilidad>`                                                             |
+| Interrumpir trabajo actual          | `Ctrl+C` o enviar un nuevo mensaje            | `/stop` o enviar un nuevo mensaje                                                 |
+| Estado específico de plataforma     | `/platforms`                                  | `/status`, `/sethome`                                                             |
+
+Para las listas de comandos completas, consulta la [guía de CLI](https://hermes-agent.nousresearch.com/docs/user-guide/cli) y la [guía del Gateway de Mensajería](https://hermes-agent.nousresearch.com/docs/user-guide/messaging).
+
+---
+
+## Documentación
+
+Toda la documentación está en **[hermes-agent.nousresearch.com/docs](https://hermes-agent.nousresearch.com/docs/)**:
+
+| Sección                                                                                             | Contenido                                                    |
+| --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ |
+| [Inicio rápido](https://hermes-agent.nousresearch.com/docs/getting-started/quickstart)              | Instalar → configurar → primera conversación en 2 minutos   |
+| [Uso de CLI](https://hermes-agent.nousresearch.com/docs/user-guide/cli)                             | Comandos, atajos de teclado, personalidades, sesiones        |
+| [Configuración](https://hermes-agent.nousresearch.com/docs/user-guide/configuration)               | Archivo de configuración, proveedores, modelos, todas las opciones |
+| [Gateway de Mensajería](https://hermes-agent.nousresearch.com/docs/user-guide/messaging)           | Telegram, Discord, Slack, WhatsApp, Signal, Home Assistant   |
+| [Seguridad](https://hermes-agent.nousresearch.com/docs/user-guide/security)                        | Aprobación de comandos, emparejamiento por DM, aislamiento en contenedor |
+| [Herramientas y Toolsets](https://hermes-agent.nousresearch.com/docs/user-guide/features/tools)   | Más de 40 herramientas, sistema de toolsets, backends de terminal |
+| [Sistema de Habilidades](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills)   | Memoria procedimental, Skills Hub, creación de habilidades   |
+| [Memoria](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory)                   | Memoria persistente, perfiles de usuario, mejores prácticas  |
+| [Integración MCP](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp)              | Conecta cualquier servidor MCP para capacidades extendidas   |
+| [Programación Cron](https://hermes-agent.nousresearch.com/docs/user-guide/features/cron)           | Tareas programadas con entrega a plataforma                  |
+| [Archivos de Contexto](https://hermes-agent.nousresearch.com/docs/user-guide/features/context-files) | Contexto de proyecto que da forma a cada conversación      |
+| [Arquitectura](https://hermes-agent.nousresearch.com/docs/developer-guide/architecture)            | Estructura del proyecto, bucle del agente, clases principales |
+| [Contribuir](https://hermes-agent.nousresearch.com/docs/developer-guide/contributing)              | Configuración de desarrollo, proceso de PR, estilo de código |
+| [Referencia de CLI](https://hermes-agent.nousresearch.com/docs/reference/cli-commands)             | Todos los comandos y flags                                   |
+| [Variables de Entorno](https://hermes-agent.nousresearch.com/docs/reference/environment-variables) | Referencia completa de variables de entorno                  |
+
+---
+
+## Migración desde OpenClaw
+
+Si vienes de OpenClaw, Hermes puede importar automáticamente tu configuración, memorias, habilidades y claves API.
+
+**Durante la configuración inicial:** El asistente de configuración (`hermes setup`) detecta automáticamente `~/.openclaw` y ofrece migrar antes de que comience la configuración.
+
+**En cualquier momento después de instalar:**
+
+```bash
+hermes claw migrate              # Migración interactiva (preset completo)
+hermes claw migrate --dry-run    # Vista previa de qué se migraría
+hermes claw migrate --preset user-data   # Migrar sin secretos
+hermes claw migrate --overwrite  # Sobreescribir conflictos existentes
+```
+
+Qué se importa:
+
+- **SOUL.md** — archivo de personalidad
+- **Memorias** — entradas de MEMORY.md y USER.md
+- **Habilidades** — habilidades creadas por el usuario → `~/.hermes/skills/openclaw-imports/`
+- **Lista de comandos permitidos** — patrones de aprobación
+- **Configuración de mensajería** — configuración de plataformas, usuarios permitidos, directorio de trabajo
+- **Claves API** — secretos en lista de permitidos (Telegram, OpenRouter, OpenAI, Anthropic, ElevenLabs)
+- **Assets de TTS** — archivos de audio del espacio de trabajo
+- **Instrucciones del espacio de trabajo** — AGENTS.md (con `--workspace-target`)
+
+Consulta `hermes claw migrate --help` para todas las opciones, o usa la habilidad `openclaw-migration` para una migración guiada interactiva por el agente con vistas previas de dry-run.
+
+---
+
+## Contribuir
+
+¡Las contribuciones son bienvenidas! Consulta la [Guía de Contribución](CONTRIBUTING.es.md) para la configuración del desarrollo, el estilo de código y el proceso de PR.
+
+Inicio rápido para colaboradores — clona y comienza con `setup-hermes.sh`:
+
+```bash
+git clone https://github.com/NousResearch/hermes-agent.git
+cd hermes-agent
+./setup-hermes.sh     # instala uv, crea venv, instala .[all], enlaza ~/.local/bin/hermes
+./hermes              # detecta automáticamente el venv, no necesitas hacer `source` primero
+```
+
+Ruta manual (equivalente a lo anterior):
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+uv venv .venv --python 3.11
+source .venv/bin/activate
+uv pip install -e ".[all,dev]"
+scripts/run_tests.sh
+```
+
+---
+
+## Comunidad
+
+- 💬 [Discord](https://discord.gg/NousResearch)
+- 📚 [Skills Hub](https://agentskills.io)
+- 🐛 [Issues](https://github.com/NousResearch/hermes-agent/issues)
+- 🔌 [computer-use-linux](https://github.com/avifenesh/computer-use-linux) — Servidor MCP de control de escritorio Linux para Hermes y otros hosts MCP, con árboles de accesibilidad AT-SPI, entrada Wayland/X11, capturas de pantalla y targeting de ventanas del compositor.
+- 🔌 [HermesClaw](https://github.com/AaronWong1999/hermesclaw) — Puente WeChat comunitario: Ejecuta Hermes Agent y OpenClaw en la misma cuenta de WeChat.
+
+---
+
+## Licencia
+
+MIT — ver [LICENSE](LICENSE).
+
+Creado por [Nous Research](https://nousresearch.com).

README.md

@@ -0,0 +1,271 @@
+# AITURK IDE · TurkServis
+
+Türkçe varsayılan arayüz, AITURK markası ve TurkServis model bağlantısı içeren
+Hermes Agent çatalı. Kurulum, kapsam ve lisans için [AITURK belgesini](README.AITURK.md) okuyun.
+
+Aşağıdaki belgeler Hermes Agent üst projesine aittir.
+
+<p align="center">
+  <img src="assets/banner.png" alt="Hermes Agent" width="100%">
+</p>
+
+# Hermes Agent ☤
+<p align="center">
+  <a href="https://hermes-agent.nousresearch.com/">Hermes Agent</a> | <a href="https://hermes-agent.nousresearch.com/">Hermes Desktop</a>
+</p>
+<p align="center">
+  <a href="https://hermes-agent.nousresearch.com/docs/"><img src="https://img.shields.io/badge/Docs-hermes--agent.nousresearch.com-FFD700?style=for-the-badge" alt="Documentation"></a>
+  <a href="https://discord.gg/NousResearch"><img src="https://img.shields.io/badge/Discord-5865F2?style=for-the-badge&logo=discord&logoColor=white" alt="Discord"></a>
+  <a href="https://github.com/NousResearch/hermes-agent/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-green?style=for-the-badge" alt="License: MIT"></a>
+  <a href="https://nousresearch.com"><img src="https://img.shields.io/badge/Built%20by-Nous%20Research-blueviolet?style=for-the-badge" alt="Built by Nous Research"></a>
+  <a href="README.zh-CN.md"><img src="https://img.shields.io/badge/Lang-中文-red?style=for-the-badge" alt="中文"></a>
+  <a href="README.ur-pk.md"><img src="https://img.shields.io/badge/Lang-اردو-green?style=for-the-badge" alt="اردو"></a>
+  <a href="README.es.md"><img src="https://img.shields.io/badge/Lang-Español-orange?style=for-the-badge" alt="Español"></a>
+</p>
+
+**The self-improving AI agent built by [Nous Research](https://nousresearch.com).** It's the only agent with a built-in learning loop — it creates skills from experience, improves them during use, nudges itself to persist knowledge, searches its own past conversations, and builds a deepening model of who you are across sessions. Run it on a $5 VPS, a GPU cluster, or serverless infrastructure that costs nearly nothing when idle. It's not tied to your laptop — talk to it from Telegram while it works on a cloud VM.
+
+Use any model you want — [Nous Portal](https://portal.nousresearch.com), OpenRouter, OpenAI, your own endpoint, and [many others](https://hermes-agent.nousresearch.com/docs/integrations/providers). Switch with `hermes model` — no code changes, no lock-in.
+
+<table>
+<tr><td><b>A real terminal interface</b></td><td>Full TUI with multiline editing, slash-command autocomplete, conversation history, interrupt-and-redirect, and streaming tool output.</td></tr>
+<tr><td><b>Lives where you do</b></td><td>Telegram, Discord, Slack, WhatsApp, Signal, and CLI — all from a single gateway process. Voice memo transcription, cross-platform conversation continuity.</td></tr>
+<tr><td><b>A closed learning loop</b></td><td>Agent-curated memory with periodic nudges. Autonomous skill creation after complex tasks. Skills self-improve during use. FTS5 session search with LLM summarization for cross-session recall. <a href="https://github.com/plastic-labs/honcho">Honcho</a> dialectic user modeling. Compatible with the <a href="https://agentskills.io">agentskills.io</a> open standard.</td></tr>
+<tr><td><b>Scheduled automations</b></td><td>Built-in cron scheduler with delivery to any platform. Daily reports, nightly backups, weekly audits — all in natural language, running unattended.</td></tr>
+<tr><td><b>Delegates and parallelizes</b></td><td>Spawn isolated subagents for parallel workstreams. Write Python scripts that call tools via RPC, collapsing multi-step pipelines into zero-context-cost turns.</td></tr>
+<tr><td><b>Runs anywhere, not just your laptop</b></td><td>Seven terminal backends — local, Docker, SSH, Singularity, Modal, Daytona, and Vercel Sandbox. Daytona and Modal offer serverless persistence — your agent's environment hibernates when idle and wakes on demand, costing nearly nothing between sessions. Run it on a $5 VPS or a GPU cluster.</td></tr>
+<tr><td><b>Research-ready</b></td><td>Batch trajectory generation, trajectory compression for training the next generation of tool-calling models.</td></tr>
+</table>
+
+---
+
+## Quick Install
+
+### Linux, macOS, WSL2, Termux
+
+```bash
+curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
+```
+
+### Windows (native, PowerShell)
+
+> **Heads up:** Native Windows runs Hermes without WSL — CLI, gateway, TUI, and tools all work natively. If you'd rather use WSL2, the Linux/macOS one-liner above works there too. Found a bug? Please [file issues](https://github.com/NousResearch/hermes-agent/issues).
+
+Run this in PowerShell:
+
+```powershell
+iex (irm https://hermes-agent.nousresearch.com/install.ps1)
+```
+
+The installer handles everything: uv, Python 3.11, Node.js, ripgrep, ffmpeg, **and a portable Git Bash** (MinGit, unpacked to `%LOCALAPPDATA%\hermes\git` — no admin required, completely isolated from any system Git install). Hermes uses this bundled Git Bash to run shell commands.
+
+If you already have Git installed, the installer detects it and uses that instead. Otherwise a ~45MB MinGit download is all you need — it won't touch or interfere with any system Git.
+
+> **Android / Termux:** The tested manual path is documented in the [Termux guide](https://hermes-agent.nousresearch.com/docs/getting-started/termux). On Termux, Hermes installs a curated `.[termux]` extra because the full `.[all]` extra currently pulls Android-incompatible voice dependencies.
+>
+> **Windows:** Native Windows is fully supported — the PowerShell one-liner above installs everything. If you'd rather use WSL2, the Linux command works there too. Native Windows install lives under `%LOCALAPPDATA%\hermes`; WSL2 installs under `~/.hermes` as on Linux.
+
+After installation:
+
+```bash
+source ~/.bashrc    # reload shell (or: source ~/.zshrc)
+hermes              # start chatting!
+```
+
+### Troubleshooting
+
+#### Windows Defender or antivirus flags `uv.exe` as malware
+
+If your antivirus (Bitdefender, Windows Defender, etc.) quarantines `uv.exe` from the Hermes `bin` folder (`%LOCALAPPDATA%\hermes\bin\uv.exe`), this is a **false positive**. The file is Astral's `uv` — the Rust Python package manager Hermes bundles to manage its Python environment. ML-based antivirus engines commonly flag unsigned Rust binaries that download and install packages.
+
+**To verify your copy is authentic:**
+
+```powershell
+# Install GitHub CLI if needed
+winget install --id GitHub.cli
+
+# Login to GitHub
+gh auth login
+
+# Run verification
+$uv = "$env:LOCALAPPDATA\hermes\bin\uv.exe"
+$ver = (& $uv --version).Split(' ')[1]
+[Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
+$zip = "$env:TEMP\uv.zip"
+Invoke-WebRequest "https://github.com/astral-sh/uv/releases/download/$ver/uv-x86_64-pc-windows-msvc.zip" -OutFile $zip -UseBasicParsing
+gh attestation verify $zip --repo astral-sh/uv
+Expand-Archive $zip "$env:TEMP\uv_x" -Force
+(Get-FileHash "$env:TEMP\uv_x\uv.exe").Hash -eq (Get-FileHash $uv).Hash
+```
+
+If attestation says "Verification succeeded" and the last line prints `True`, you're good.
+
+**To whitelist Hermes:**
+- **Windows Defender:** Run PowerShell as Admin → `Add-MpPreference -ExclusionPath "$env:LOCALAPPDATA\hermes\bin"`
+- **Bitdefender:** Add an exception in the Bitdefender console (Protection > Antivirus > Settings > Manage Exceptions)
+- Whitelist the **folder**, not the file hash — Hermes updates `uv` and the hash changes every version
+
+For more context, see the upstream Astral reports: [astral-sh/uv#13553](https://github.com/astral-sh/uv/issues/13553), [astral-sh/uv#15011](https://github.com/astral-sh/uv/issues/15011), [astral-sh/uv#10079](https://github.com/astral-sh/uv/issues/10079).
+
+---
+
+## Getting Started
+
+```bash
+hermes              # Interactive CLI — start a conversation
+hermes model        # Choose your LLM provider and model
+hermes tools        # Configure which tools are enabled
+hermes config set   # Set individual config values
+hermes config get   # Print individual config values
+hermes gateway      # Start the messaging gateway (Telegram, Discord, etc.)
+hermes setup        # Run the full setup wizard (configures everything at once)
+hermes claw migrate # Migrate from OpenClaw (if coming from OpenClaw)
+hermes update       # Update to the latest version
+hermes doctor       # Diagnose any issues
+```
+
+📖 **[Full documentation →](https://hermes-agent.nousresearch.com/docs/)**
+
+---
+
+## Skip the API-key collection — Nous Portal
+
+Hermes works with whatever provider you want — that's not changing. But if you'd rather not collect five separate API keys for the model, web search, image generation, TTS, and a cloud browser, **[Nous Portal](https://portal.nousresearch.com)** covers all of them under one subscription:
+
+- **300+ models** — pick any of them with `/model <name>`
+- **Tool Gateway** — web search (Firecrawl), image generation (FAL), text-to-speech (OpenAI), cloud browser (Browser Use), all routed through your sub. No extra accounts.
+
+One command from a fresh install:
+
+```bash
+hermes setup --portal
+```
+
+That logs you in via OAuth, sets Nous as your provider, and turns on the Tool Gateway. Check what's wired up any time with `hermes portal info`. Full details on the [Tool Gateway docs page](https://hermes-agent.nousresearch.com/docs/user-guide/features/tool-gateway).
+
+You can still bring your own keys per-tool whenever you want — the gateway is per-backend, not all-or-nothing.
+
+---
+
+## CLI vs Messaging Quick Reference
+
+Hermes has two entry points: start the terminal UI with `hermes`, or run the gateway and talk to it from Telegram, Discord, Slack, WhatsApp, Signal, or Email. Once you're in a conversation, many slash commands are shared across both interfaces.
+
+| Action                         | CLI                                           | Messaging platforms                                                              |
+| ------------------------------ | --------------------------------------------- | -------------------------------------------------------------------------------- |
+| Start chatting                 | `hermes`                                      | Run `hermes gateway setup` + `hermes gateway start`, then send the bot a message |
+| Start fresh conversation       | `/new` or `/reset`                            | `/new` or `/reset`                                                               |
+| Change model                   | `/model [provider:model]`                     | `/model [provider:model]`                                                        |
+| Set a personality              | `/personality [name]`                         | `/personality [name]`                                                            |
+| Retry or undo the last turn    | `/retry`, `/undo`                             | `/retry`, `/undo`                                                                |
+| Compress context / check usage | `/compress`, `/usage`, `/insights [--days N]` | `/compress`, `/usage`, `/insights [days]`                                        |
+| Browse skills                  | `/skills` or `/<skill-name>`                  | `/<skill-name>`                                                                  |
+| Interrupt current work         | `Ctrl+C` or send a new message                | `/stop` or send a new message                                                    |
+| Platform-specific status       | `/platforms`                                  | `/status`, `/sethome`                                                            |
+
+For the full command lists, see the [CLI guide](https://hermes-agent.nousresearch.com/docs/user-guide/cli) and the [Messaging Gateway guide](https://hermes-agent.nousresearch.com/docs/user-guide/messaging).
+
+---
+
+## Documentation
+
+All documentation lives at **[hermes-agent.nousresearch.com/docs](https://hermes-agent.nousresearch.com/docs/)**:
+
+| Section                                                                                             | What's Covered                                             |
+| --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
+| [Quickstart](https://hermes-agent.nousresearch.com/docs/getting-started/quickstart)                 | Install → setup → first conversation in 2 minutes          |
+| [CLI Usage](https://hermes-agent.nousresearch.com/docs/user-guide/cli)                              | Commands, keybindings, personalities, sessions             |
+| [Configuration](https://hermes-agent.nousresearch.com/docs/user-guide/configuration)                | Config file, providers, models, all options                |
+| [Messaging Gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging)                | Telegram, Discord, Slack, WhatsApp, Signal, Home Assistant |
+| [Security](https://hermes-agent.nousresearch.com/docs/user-guide/security)                          | Command approval, DM pairing, container isolation          |
+| [Tools & Toolsets](https://hermes-agent.nousresearch.com/docs/user-guide/features/tools)            | 40+ tools, toolset system, terminal backends               |
+| [Skills System](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills)              | Procedural memory, Skills Hub, creating skills             |
+| [Memory](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory)                     | Persistent memory, user profiles, best practices           |
+| [MCP Integration](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp)               | Connect any MCP server for extended capabilities           |
+| [Cron Scheduling](https://hermes-agent.nousresearch.com/docs/user-guide/features/cron)              | Scheduled tasks with platform delivery                     |
+| [Context Files](https://hermes-agent.nousresearch.com/docs/user-guide/features/context-files)       | Project context that shapes every conversation             |
+| [Architecture](https://hermes-agent.nousresearch.com/docs/developer-guide/architecture)             | Project structure, agent loop, key classes                 |
+| [Contributing](https://hermes-agent.nousresearch.com/docs/developer-guide/contributing)             | Development setup, PR process, code style                  |
+| [CLI Reference](https://hermes-agent.nousresearch.com/docs/reference/cli-commands)                  | All commands and flags                                     |
+| [Environment Variables](https://hermes-agent.nousresearch.com/docs/reference/environment-variables) | Complete env var reference                                 |
+
+---
+
+## Migrating from OpenClaw
+
+If you're coming from OpenClaw, Hermes can automatically import your settings, memories, skills, and API keys.
+
+**During first-time setup:** The setup wizard (`hermes setup`) automatically detects `~/.openclaw` and offers to migrate before configuration begins.
+
+**Anytime after install:**
+
+```bash
+hermes claw migrate              # Interactive migration (full preset)
+hermes claw migrate --dry-run    # Preview what would be migrated
+hermes claw migrate --preset user-data   # Migrate without secrets
+hermes claw migrate --overwrite  # Overwrite existing conflicts
+```
+
+What gets imported:
+
+- **SOUL.md** — persona file
+- **Memories** — MEMORY.md and USER.md entries
+- **Skills** — user-created skills → `~/.hermes/skills/openclaw-imports/`
+- **Command allowlist** — approval patterns
+- **Messaging settings** — platform configs, allowed users, working directory
+- **API keys** — allowlisted secrets (Telegram, OpenRouter, OpenAI, Anthropic, ElevenLabs)
+- **TTS assets** — workspace audio files
+- **Workspace instructions** — AGENTS.md (with `--workspace-target`)
+
+See `hermes claw migrate --help` for all options, or use the `openclaw-migration` skill for an interactive agent-guided migration with dry-run previews.
+
+---
+
+## Contributing
+
+We welcome contributions! See the [Contributing Guide](https://hermes-agent.nousresearch.com/docs/developer-guide/contributing) for development setup, code style, and PR process.
+
+Quick start for contributors — use the standard installer, then work from the
+full git checkout it creates at `$HERMES_HOME/hermes-agent` (usually
+`~/.hermes/hermes-agent`). This matches the layout used by `hermes update`, the
+managed venv, lazy dependencies, gateway, and docs tooling.
+
+```bash
+curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
+cd "${HERMES_HOME:-$HOME/.hermes}/hermes-agent"
+uv pip install -e ".[all,dev]"
+scripts/run_tests.sh
+```
+
+Manual clone fallback (for throwaway clones/CI where you intentionally do not
+want the managed install layout):
+
+Create the venv outside the cloned source tree — a venv inside the directory
+the agent operates from can be wiped by a relative-path command the agent runs
+against its own checkout, destroying the running runtime mid-session.
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+uv venv ~/.hermes/venvs/hermes-dev --python 3.11
+source ~/.hermes/venvs/hermes-dev/bin/activate
+uv pip install -e ".[all,dev]"
+scripts/run_tests.sh
+```
+
+---
+
+## Community
+
+- 💬 [Discord](https://discord.gg/NousResearch)
+- 📚 [Skills Hub](https://agentskills.io)
+- 🐛 [Issues](https://github.com/NousResearch/hermes-agent/issues)
+- 🔌 [computer-use-linux](https://github.com/avifenesh/computer-use-linux) — Linux desktop-control MCP server for Hermes and other MCP hosts, with AT-SPI accessibility trees, Wayland/X11 input, screenshots, and compositor window targeting.
+- 🔌 [HermesClaw](https://github.com/AaronWong1999/hermesclaw) — Community WeChat bridge: Run Hermes Agent and OpenClaw on the same WeChat account.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).
+
+Built by [Nous Research](https://nousresearch.com).

README.ur-pk.md

@@ -0,0 +1,261 @@
+<div dir="rtl">
+
+<p align="center">
+  <img src="assets/banner.png" alt="Hermes Agent" width="100%">
+</p>
+
+# ہرمیس ایجنٹ ☤ (Hermes Agent)
+
+<p align="center">
+  <a href="https://hermes-agent.nousresearch.com/docs/"><img src="https://img.shields.io/badge/Docs-hermes--agent.nousresearch.com-FFD700?style=for-the-badge" alt="Documentation"></a>
+  <a href="https://discord.gg/NousResearch"><img src="https://img.shields.io/badge/Discord-5865F2?style=for-the-badge&logo=discord&logoColor=white" alt="Discord"></a>
+  <a href="https://github.com/NousResearch/hermes-agent/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-green?style=for-the-badge" alt="License: MIT"></a>
+  <a href="https://nousresearch.com"><img src="https://img.shields.io/badge/Built%20by-Nous%20Research-blueviolet?style=for-the-badge" alt="Built by Nous Research"></a>
+  <a href="README.md"><img src="https://img.shields.io/badge/Lang-English-lightgrey?style=for-the-badge" alt="English"></a>
+  <a href="README.zh-CN.md"><img src="https://img.shields.io/badge/Lang-中文-red?style=for-the-badge" alt="中文"></a>
+</p>
+
+**[نوس ریسرچ (Nous Research)](https://nousresearch.com) کا تیار کردہ خود کو بہتر بنانے والا اے آئی (AI) ایجنٹ۔** یہ واحد ایجنٹ ہے جس میں سیکھنے کا عمل (learning loop) پہلے سے موجود ہے — یہ اپنے تجربات سے نئی مہارتیں (skills) بناتا ہے، استعمال کے دوران ان کو بہتر کرتا ہے، معلومات کو محفوظ رکھنے کے لیے خود کو یاد دہانی کرواتا ہے، اپنی پرانی بات چیت کو تلاش کر سکتا ہے، اور مختلف سیشنز کے دوران آپ کے بارے میں ایک گہری سمجھ پیدا کرتا ہے۔ اسے $5 والے VPS پر چلائیں، GPU کلسٹر پر، یا سرور لیس (serverless) انفراسٹرکچر پر جس کی قیمت استعمال نہ ہونے پر تقریباً صفر ہے۔ یہ آپ کے لیپ ٹاپ تک محدود نہیں ہے — آپ ٹیلی گرام (Telegram) سے اس کے ساتھ بات چیت کر سکتے ہیں جبکہ یہ کلاؤڈ VM پر کام کر رہا ہو۔
+
+آپ اپنی مرضی کا کوئی بھی ماڈل استعمال کر سکتے ہیں — [Nous Portal](https://portal.nousresearch.com)، [OpenRouter](https://openrouter.ai) (200 سے زائد ماڈلز)، [NovitaAI](https://novita.ai) (ماڈل API، ایجنٹ سینڈ باکس، اور GPU کلاؤڈ کے لیے اے آئی مقامی کلاؤڈ)، [NVIDIA NIM](https://build.nvidia.com) (Nemotron)، [Xiaomi MiMo](https://platform.xiaomimimo.com)، [z.ai/GLM](https://z.ai)، [Kimi/Moonshot](https://platform.moonshot.ai)، [MiniMax](https://www.minimax.io)، [Hugging Face](https://huggingface.co)، OpenAI، یا اپنا حسب ضرورت اینڈ پوائنٹ (endpoint) استعمال کریں۔ ماڈل تبدیل کرنے کے لیے صرف `hermes model` استعمال کریں — کسی کوڈ کو تبدیل کرنے کی ضرورت نہیں، کوئی پابندی نہیں۔
+
+<table>
+<tr><td><b>حقیقی ٹرمینل انٹرفیس</b></td><td>مکمل TUI جس میں ملٹی لائن ایڈیٹنگ، سلیش-کمانڈ آٹو کمپلیٹ، بات چیت کی ہسٹری، انٹرپٹ اور ری ڈائریکٹ، اور سٹریمنگ ٹول آؤٹ پٹ شامل ہے۔</td></tr>
+<tr><td><b>یہ وہاں موجود ہے جہاں آپ ہیں</b></td><td>ٹیلی گرام، ڈسکارڈ (Discord)، سلیک (Slack)، واٹس ایپ (WhatsApp)، سگنل (Signal)، اور CLI — سب ایک ہی گیٹ وے پروسیس سے کام کرتے ہیں۔ وائس میمو (Voice memo) ٹرانسکرپشن، کراس پلیٹ فارم بات چیت کا تسلسل۔</td></tr>
+<tr><td><b>سیکھنے کا ایک مکمل عمل</b></td><td>ایجنٹ کی اپنی ترتیب دی گئی میموری، جس میں وہ خود کو وقتاً فوقتاً یاد دہانی کرواتا ہے۔ پیچیدہ کاموں کے بعد خود کار طریقے سے مہارت (skill) کی تخلیق۔ استعمال کے دوران مہارتوں میں بہتری۔ LLM سمرائزیشن کے ساتھ FTS5 سیشن سرچ تاکہ پرانے سیشنز کی یاددہانی کی جا سکے۔ <a href="https://github.com/plastic-labs/honcho">Honcho</a> کے ذریعے صارف کی ماڈلنگ۔ <a href="https://agentskills.io">agentskills.io</a> اوپن سٹینڈرڈ کے ساتھ مکمل مطابقت۔</td></tr>
+<tr><td><b>شیڈول کی گئی خودکار کارروائیاں</b></td><td>بلٹ ان (Built-in) کرون (cron) شیڈیولر جو کسی بھی پلیٹ فارم پر ڈیلیوری کے لیے استعمال ہو سکتا ہے۔ روزانہ کی رپورٹس، رات کے بیک اپس، ہفتہ وار آڈٹس — یہ سب کچھ قدرتی زبان (natural language) میں اور بغیر کسی نگرانی کے کام کرتا ہے۔</td></tr>
+<tr><td><b>کام کی تقسیم اور متوازی عمل</b></td><td>متوازی (parallel) کاموں کے لیے الگ سے ذیلی ایجنٹس (subagents) بنائیں۔ پائتھون (Python) سکرپٹس لکھیں جو RPC کے ذریعے ٹولز کو استعمال کریں، تاکہ کئی مراحل پر مشتمل کاموں کو بغیر کسی سیاق و سباق (context) کے خرچ کے، ایک ہی باری میں انجام دیا جا سکے۔</td></tr>
+<tr><td><b>کہیں بھی چلائیں، صرف اپنے لیپ ٹاپ پر نہیں</b></td><td>چھ (Six) ٹرمینل بیک اینڈز — لوکل، Docker، SSH، Singularity، Modal، اور Daytona۔ ڈیٹونا (Daytona) اور موڈل (Modal) سرور لیس (serverless) فعالیت پیش کرتے ہیں — جب آپ کا ایجنٹ فارغ ہوتا ہے تو اس کا ماحول سلیپ (hibernate) ہو جاتا ہے اور ضرورت پڑنے پر خود بخود جاگ جاتا ہے، جس کی وجہ سے سیشنز کے درمیان لاگت تقریباً صفر رہتی ہے۔ اسے $5 والے VPS یا GPU کلسٹر پر چلائیں۔</td></tr>
+<tr><td><b>تحقیق کے لیے تیار</b></td><td>بیچ (Batch) ٹریجیکٹری (trajectory) جنریشن، اگلی نسل کے ٹول کالنگ ماڈلز کی تربیت کے لیے ٹریجیکٹری کمپریشن۔</td></tr>
+</table>
+
+---
+
+## فوری انسٹالیشن (Quick Install)
+
+### لینکس (Linux)، میک او ایس (macOS)، ڈبلیو ایس ایل ٹو (WSL2)، ٹرمکس (Termux)
+
+<div dir="ltr">
+
+```bash
+curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
+```
+
+</div>
+
+### ونڈوز (نیٹو، پاور شیل)
+
+> **توجہ فرمائیں:** مقامی ونڈوز (Native Windows) پر ہرمیس بغیر WSL کے چلتا ہے — CLI، گیٹ وے، TUI، اور ٹولز سب مقامی طور پر کام کرتے ہیں۔ اگر آپ WSL2 استعمال کرنا پسند کرتے ہیں، تو اوپر دی گئی لینکس/میک او ایس کی کمانڈ وہاں بھی کام کرے گی۔ کوئی مسئلہ نظر آیا؟ براہ کرم [مسائل (issues) درج کریں](https://github.com/NousResearch/hermes-agent/issues)۔
+
+اسے پاور شیل (PowerShell) میں چلائیں:
+
+<div dir="ltr">
+
+```powershell
+iex (irm https://hermes-agent.nousresearch.com/install.ps1)
+```
+
+</div>
+
+انسٹالر سب کچھ خود سنبھالتا ہے: uv، Python 3.11، Node.js، ripgrep، ffmpeg، **اور ایک پورٹ ایبل (portable) گٹ بیش (Git Bash)** (یعنی MinGit، جو `%LOCALAPPDATA%\hermes\git` میں ان پیک ہوتا ہے — اس کے لیے ایڈمن کی اجازت درکار نہیں، اور یہ سسٹم کے کسی بھی گٹ انسٹال سے بالکل الگ ہے)۔ ہرمیس اس بنڈل شدہ گٹ بیش کو شیل کمانڈز چلانے کے لیے استعمال کرتا ہے۔
+
+اگر آپ کے پاس پہلے سے گٹ (Git) انسٹال ہے، تو انسٹالر اسے شناخت کر لیتا ہے اور اسے ہی استعمال کرتا ہے۔ بصورت دیگر آپ کو صرف ~45MB کے MinGit ڈاؤنلوڈ کی ضرورت ہوگی — یہ آپ کے سسٹم کے گٹ پر کوئی اثر نہیں ڈالے گا۔
+
+> **اینڈرائیڈ (Android) / ٹرمکس (Termux):** ٹیسٹ کیا گیا مینوئل طریقہ [Termux گائیڈ](https://hermes-agent.nousresearch.com/docs/getting-started/termux) میں موجود ہے۔ ٹرمکس پر ہرمیس ایک مخصوص `.[termux]` ایکسٹرا انسٹال کرتا ہے کیونکہ مکمل `.[all]` ایکسٹرا میں ایسی وائس ڈیپینڈینسیز شامل ہیں جو اینڈرائیڈ کے ساتھ مطابقت نہیں رکھتیں۔
+>
+> **ونڈوز (Windows):** مقامی ونڈوز کی مکمل سپورٹ موجود ہے — اوپر دی گئی پاور شیل کی کمانڈ سب کچھ انسٹال کر دیتی ہے۔ اگر آپ WSL2 استعمال کرنا چاہتے ہیں، تو لینکس کی کمانڈ وہاں کام کرتی ہے۔ مقامی ونڈوز میں انسٹالیشن `%LOCALAPPDATA%\hermes` میں ہوتی ہے؛ جبکہ WSL2 میں لینکس کی طرح `~/.hermes` میں ہوتی ہے۔ ہرمیس کا وہ واحد فیچر جسے فی الحال خاص طور پر WSL2 کی ضرورت ہے وہ براؤزر پر مبنی ڈیش بورڈ چیٹ پین ہے (یہ POSIX PTY استعمال کرتا ہے — کلاسک CLI اور گیٹ وے دونوں مقامی طور پر چلتے ہیں)۔
+
+انسٹالیشن کے بعد:
+
+<div dir="ltr">
+
+```bash
+source ~/.bashrc    # شیل کو ری لوڈ کریں (یا: source ~/.zshrc)
+hermes              # بات چیت شروع کریں!
+```
+
+</div>
+
+---
+
+## آغاز کریں (Getting Started)
+
+<div dir="ltr">
+
+```bash
+hermes              # انٹرایکٹو CLI — بات چیت شروع کریں
+hermes model        # اپنا LLM پرووائیڈر اور ماڈل منتخب کریں
+hermes tools        # کنفیگر کریں کہ کون سے ٹولز ایکٹو ہیں
+hermes config set   # انفرادی کنفگ (config) ویلیوز سیٹ کریں
+hermes gateway      # میسجنگ گیٹ وے شروع کریں (ٹیلی گرام، ڈسکارڈ، وغیرہ)
+hermes setup        # مکمل سیٹ اپ وزرڈ چلائیں (یہ سب کچھ ایک ساتھ کنفیگر کر دے گا)
+hermes claw migrate # OpenClaw سے مائیگریٹ کریں (اگر آپ OpenClaw سے آ رہے ہیں)
+hermes update       # لیٹسٹ ورژن پر اپ ڈیٹ کریں
+hermes doctor       # کسی بھی مسئلے کی تشخیص کریں
+```
+
+</div>
+
+📖 **[مکمل دستاویزات →](https://hermes-agent.nousresearch.com/docs/)**
+
+---
+
+## API-کیز اکٹھی کرنے سے بچیں — Nous Portal
+
+ہرمیس آپ کے پسندیدہ پرووائیڈر کے ساتھ کام کرتا ہے — یہ چیز تبدیل نہیں ہو رہی۔ لیکن اگر آپ ماڈل، ویب سرچ، امیج جنریشن، TTS، اور کلاؤڈ براؤزر کے لیے پانچ الگ الگ API کیز جمع نہیں کرنا چاہتے، تو **[Nous Portal](https://portal.nousresearch.com)** ان سب کو ایک ہی سبسکرپشن کے تحت کور کرتا ہے:
+
+- **300+ ماڈلز** — ان میں سے کوئی بھی ماڈل `/model <name>` کے ذریعے منتخب کریں
+- **ٹول گیٹ وے (Tool Gateway)** — ویب سرچ (Firecrawl)، امیج جنریشن (FAL)، ٹیکسٹ ٹو سپیچ (OpenAI)، کلاؤڈ براؤزر (Browser Use)، یہ سب آپ کی سبسکرپشن کے ذریعے چلتے ہیں۔ کسی اضافی اکاؤنٹ کی ضرورت نہیں۔
+
+نئی انسٹالیشن کے بعد بس ایک کمانڈ کی ضرورت ہے:
+
+<div dir="ltr">
+
+```bash
+hermes setup --portal
+```
+
+</div>
+
+یہ آپ کو OAuth کے ذریعے لاگ ان کرواتا ہے، Nous کو آپ کا پرووائیڈر مقرر کرتا ہے، اور ٹول گیٹ وے کو آن کر دیتا ہے۔ `hermes portal info` کمانڈ استعمال کر کے آپ کسی بھی وقت چیک کر سکتے ہیں کہ کون کون سی سروسز منسلک ہیں۔ مکمل تفصیلات [Tool Gateway دستاویزات کے صفحے](https://hermes-agent.nousresearch.com/docs/user-guide/features/tool-gateway) پر موجود ہیں۔
+
+آپ اب بھی کسی بھی ٹول کے لیے اپنی مرضی کی API کیز استعمال کر سکتے ہیں — گیٹ وے ہر سروس کے لیے الگ الگ کام کرتا ہے، ایسا نہیں کہ یا تو سب کچھ استعمال کریں یا کچھ بھی نہیں۔
+
+---
+
+## CLI بمقابلہ میسجنگ فوری حوالہ
+
+ہرمیس کے دو بنیادی انٹر فیس ہیں: آپ ٹرمینل UI کو `hermes` کے ساتھ شروع کریں، یا گیٹ وے چلا کر اس کے ساتھ ٹیلی گرام، ڈسکارڈ، سلیک، واٹس ایپ، سگنل، یا ای میل کے ذریعے بات کریں۔ جب آپ کسی بات چیت میں ہوتے ہیں، تو بہت سی سلیش (slash) کمانڈز دونوں انٹرفیسز میں ایک جیسی ہوتی ہیں۔
+
+<div dir="ltr">
+
+| کارروائی (Action)                         | سی ایل آئی (CLI)                              | میسجنگ پلیٹ فارمز (Messaging platforms)                                          |
+| --------------------------------------- | --------------------------------------------- | -------------------------------------------------------------------------------- |
+| بات چیت شروع کریں                       | `hermes`                                      | `hermes gateway setup` اور `hermes gateway start` چلائیں، پھر بوٹ کو میسج بھیجیں |
+| نئی بات چیت شروع کریں                   | `/new` یا `/reset`                            | `/new` یا `/reset`                                                               |
+| ماڈل تبدیل کریں                         | `/model [provider:model]`                     | `/model [provider:model]`                                                        |
+| پرسنلٹی (Personality) سیٹ کریں           | `/personality [name]`                         | `/personality [name]`                                                            |
+| پچھلی باری کو دوبارہ یا منسوخ (undo) کریں | `/retry`، `/undo`                             | `/retry`، `/undo`                                                                |
+| کانٹیکسٹ (context) کمپریس کریں / استعمال چیک کریں | `/compress`، `/usage`، `/insights [--days N]` | `/compress`، `/usage`، `/insights [days]`                                        |
+| مہارتیں (Skills) براؤز کریں             | `/skills` یا `/<skill-name>`                  | `/<skill-name>`                                                                  |
+| موجودہ کام کو روکیں                     | `Ctrl+C` دبائیں یا نیا میسج بھیجیں            | `/stop` یا نیا میسج بھیجیں                                                       |
+| پلیٹ فارم کے لحاظ سے سٹیٹس              | `/platforms`                                  | `/status`، `/sethome`                                                            |
+
+</div>
+
+مکمل کمانڈ لسٹ کے لیے، [CLI گائیڈ](https://hermes-agent.nousresearch.com/docs/user-guide/cli) اور [میسجنگ گیٹ وے گائیڈ](https://hermes-agent.nousresearch.com/docs/user-guide/messaging) دیکھیں۔
+
+---
+
+## دستاویزات (Documentation)
+
+تمام دستاویزات **[hermes-agent.nousresearch.com/docs](https://hermes-agent.nousresearch.com/docs/)** پر موجود ہیں:
+
+<div dir="ltr">
+
+| سیکشن (Section)                                                                                     | تفصیل (What's Covered)                                     |
+| --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
+| [فوری آغاز (Quickstart)](https://hermes-agent.nousresearch.com/docs/getting-started/quickstart)     | انسٹالیشن → سیٹ اپ → 2 منٹ میں پہلی بات چیت شروع کریں       |
+| [CLI کا استعمال](https://hermes-agent.nousresearch.com/docs/user-guide/cli)                         | کمانڈز، کی بائنڈنگز (keybindings)، پرسنلٹیز (personalities)، سیشنز |
+| [کنفیگریشن (Configuration)](https://hermes-agent.nousresearch.com/docs/user-guide/configuration)    | کنفگ فائل، پرووائیڈرز، ماڈلز، اور تمام آپشنز               |
+| [میسجنگ گیٹ وے](https://hermes-agent.nousresearch.com/docs/user-guide/messaging)                    | ٹیلی گرام، ڈسکارڈ، سلیک، واٹس ایپ، سگنل، ہوم اسسٹنٹ         |
+| [سیکیورٹی (Security)](https://hermes-agent.nousresearch.com/docs/user-guide/security)              | کمانڈ کی منظوری، DM پیئرنگ (pairing)، کنٹینر آئسولیشن       |
+| [ٹولز اور ٹول سیٹس](https://hermes-agent.nousresearch.com/docs/user-guide/features/tools)          | 40 سے زائد ٹولز، ٹول سیٹ سسٹم، ٹرمینل بیک اینڈز             |
+| [مہارتوں کا سسٹم (Skills System)](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills)| پروسیجرل (Procedural) میموری، سکلز ہب، نئی مہارتیں بنانا    |
+| [میموری (Memory)](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory)            | مستقل میموری، یوزر پروفائلز، بہترین طریقہ کار              |
+| [MCP انضمام (Integration)](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp)      | صلاحیتوں کو بڑھانے کے لیے کسی بھی MCP سرور کو جوڑیں        |
+| [کرون (Cron) شیڈیولنگ](https://hermes-agent.nousresearch.com/docs/user-guide/features/cron)         | پلیٹ فارم ڈیلیوری کے ساتھ شیڈول کیے گئے کام                 |
+| [کانٹیکسٹ (Context) فائلز](https://hermes-agent.nousresearch.com/docs/user-guide/features/context-files)| پروجیکٹ کا سیاق و سباق (context) جو ہر بات چیت پر اثر انداز ہوتا ہے |
+| [آرکیٹیکچر (Architecture)](https://hermes-agent.nousresearch.com/docs/developer-guide/architecture) | پروجیکٹ کا ڈھانچہ، ایجنٹ لوپ، اہم کلاسز                    |
+| [تعاون (Contributing)](https://hermes-agent.nousresearch.com/docs/developer-guide/contributing)     | ڈیویلپمنٹ سیٹ اپ، PR کا طریقہ کار، کوڈنگ کا انداز          |
+| [CLI حوالہ جات (Reference)](https://hermes-agent.nousresearch.com/docs/reference/cli-commands)      | تمام کمانڈز اور فلیگز (flags)                              |
+| [انوائرمنٹ ویری ایبلز](https://hermes-agent.nousresearch.com/docs/reference/environment-variables)  | مکمل انوائرمنٹ ویری ایبل حوالہ جات                         |
+
+</div>
+
+---
+
+## OpenClaw سے منتقلی
+
+اگر آپ OpenClaw سے منتقل ہو رہے ہیں، تو ہرمیس آپ کی سیٹنگز، یادیں (memories)، مہارتیں (skills)، اور API کیز کو خود بخود امپورٹ کر سکتا ہے۔
+
+**پہلی بار سیٹ اپ کے دوران:** سیٹ اپ وزرڈ (`hermes setup`) خود بخود `~/.openclaw` کو پہچان لیتا ہے اور کنفیگریشن شروع ہونے سے پہلے مائیگریٹ (migrate) کرنے کا آپشن دیتا ہے۔
+
+**انسٹالیشن کے بعد کسی بھی وقت:**
+
+<div dir="ltr">
+
+```bash
+hermes claw migrate              # انٹرایکٹو مائیگریشن (مکمل پری سیٹ)
+hermes claw migrate --dry-run    # جائزہ لیں کہ کیا کیا مائیگریٹ ہوگا
+hermes claw migrate --preset user-data   # حساس معلومات (secrets) کے بغیر مائیگریٹ کریں
+hermes claw migrate --overwrite  # موجودہ متصادم فائلوں کو اوور رائٹ کریں
+```
+
+</div>
+
+جو چیزیں امپورٹ ہوتی ہیں:
+
+- **SOUL.md** — پرسونا (persona) فائل
+- **میموریز (Memories)** — MEMORY.md اور USER.md کی اندراجات
+- **مہارتیں (Skills)** — صارف کی بنائی گئی مہارتیں → `~/.hermes/skills/openclaw-imports/`
+- **کمانڈ الاؤ لسٹ (allowlist)** — منظوری کے پیٹرنز (approval patterns)
+- **میسجنگ سیٹنگز** — پلیٹ فارم کنفیگریشنز، اجازت یافتہ صارفین، ورکنگ ڈائریکٹری
+- **API کیز** — الاؤ لسٹ شدہ حساس معلومات (ٹیلی گرام، OpenRouter، OpenAI، Anthropic، ElevenLabs)
+- **TTS اثاثے** — ورک اسپیس کی آڈیو فائلیں
+- **ورک اسپیس کی ہدایات** — AGENTS.md (`--workspace-target` کے ساتھ)
+
+تمام آپشنز دیکھنے کے لیے `hermes claw migrate --help` استعمال کریں، یا انٹرایکٹو ایجنٹ کی مدد سے مائیگریٹ کرنے کے لیے `openclaw-migration` سکل کا استعمال کریں (جس میں ڈرائی رن (dry-run) پریویوز شامل ہیں)۔
+
+---
+
+## تعاون کریں (Contributing)
+
+ہم آپ کے تعاون کا خیرمقدم کرتے ہیں! ڈیویلپمنٹ سیٹ اپ، کوڈ کے انداز اور PR کے طریقہ کار کے لیے براہ کرم ہماری [Contributing گائیڈ](https://hermes-agent.nousresearch.com/docs/developer-guide/contributing) دیکھیں۔
+
+معاونین (contributors) کے لیے فوری آغاز — کلون (clone) کریں اور `setup-hermes.sh` چلائیں:
+
+<div dir="ltr">
+
+```bash
+git clone https://github.com/NousResearch/hermes-agent.git
+cd hermes-agent
+./setup-hermes.sh     # uv کو انسٹال کرتا ہے، venv بناتا ہے، .[all] کو انسٹال کرتا ہے، اور ~/.local/bin/hermes کا سیم لنک (symlink) بناتا ہے
+./hermes              # خود بخود venv کی شناخت کرتا ہے، پہلے `source` کرنے کی ضرورت نہیں
+```
+
+</div>
+
+مینوئل طریقہ (اوپر والے طریقے کے مساوی):
+
+<div dir="ltr">
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+uv venv .venv --python 3.11
+source .venv/bin/activate
+uv pip install -e ".[all,dev]"
+scripts/run_tests.sh
+```
+
+</div>
+
+---
+
+## کمیونٹی (Community)
+
+- 💬 [ڈسکارڈ (Discord)](https://discord.gg/NousResearch)
+- 📚 [سکلز ہب (Skills Hub)](https://agentskills.io)
+- 🐛 [مسائل (Issues)](https://github.com/NousResearch/hermes-agent/issues)
+- 🔌 [computer-use-linux](https://github.com/avifenesh/computer-use-linux) — ہرمیس اور دیگر MCP ہوسٹس کے لیے لینکس (Linux) ڈیسک ٹاپ کنٹرول MCP سرور، جس میں AT-SPI ایکسیسیبلٹی ٹریز، Wayland/X11 ان پٹ، سکرین شاٹس، اور کمپوزیٹر ونڈو ٹارگیٹنگ شامل ہے۔
+- 🔌 [HermesClaw](https://github.com/AaronWong1999/hermesclaw) — کمیونٹی وی چیٹ (WeChat) برج: ہرمیس ایجنٹ اور OpenClaw کو ایک ہی وی چیٹ اکاؤنٹ پر چلائیں۔
+
+---
+
+## لائسنس (License)
+
+MIT — تفصیلات کے لیے [LICENSE](LICENSE) دیکھیں۔
+
+[نوس ریسرچ (Nous Research)](https://nousresearch.com) کی جانب سے تیار کردہ۔
+
+</div>

README.zh-CN.md

@@ -0,0 +1,208 @@
+<p align="center">
+  <img src="assets/banner.png" alt="Hermes Agent" width="100%">
+</p>
+
+# Hermes Agent ☤
+
+<p align="center">
+  <a href="https://hermes-agent.nousresearch.com/docs/"><img src="https://img.shields.io/badge/Docs-hermes--agent.nousresearch.com-FFD700?style=for-the-badge" alt="Documentation"></a>
+  <a href="https://discord.gg/NousResearch"><img src="https://img.shields.io/badge/Discord-5865F2?style=for-the-badge&logo=discord&logoColor=white" alt="Discord"></a>
+  <a href="https://github.com/NousResearch/hermes-agent/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-green?style=for-the-badge" alt="License: MIT"></a>
+  <a href="https://nousresearch.com"><img src="https://img.shields.io/badge/Built%20by-Nous%20Research-blueviolet?style=for-the-badge" alt="Built by Nous Research"></a>
+  <a href="README.md"><img src="https://img.shields.io/badge/Lang-English-lightgrey?style=for-the-badge" alt="English"></a>
+  <a href="README.ur-pk.md"><img src="https://img.shields.io/badge/Lang-اردو-green?style=for-the-badge" alt="اردو"></a>
+</p>
+
+**由 [Nous Research](https://nousresearch.com) 构建的自进化 AI 代理。** 它是唯一内置学习闭环的智能代理——从经验中创建技能，在使用中改进技能，主动持久化知识，搜索过往对话，并在跨会话中逐步构建对你的深度理解。可以在 $5 的 VPS 上运行，也可以在 GPU 集群上运行，或者使用几乎零成本的 Serverless 基础设施。它不绑定你的笔记本——你可以在 Telegram 上与它对话，而它在云端 VM 上工作。
+
+支持任意模型——[Nous Portal](https://portal.nousresearch.com)、[OpenRouter](https://openrouter.ai)（200+ 模型）、[NVIDIA NIM](https://build.nvidia.com)（Nemotron）、[小米 MiMo](https://platform.xiaomimimo.com)、[z.ai/GLM](https://z.ai)、[Kimi/Moonshot](https://platform.moonshot.ai)、[MiniMax](https://www.minimax.io)、[Hugging Face](https://huggingface.co)、OpenAI，或自定义端点。使用 `hermes model` 即可切换——无需改代码，无锁定。
+
+<table>
+<tr><td><b>真正的终端界面</b></td><td>完整的 TUI，支持多行编辑、斜杠命令自动补全、对话历史、中断重定向和流式工具输出。</td></tr>
+<tr><td><b>随你所在</b></td><td>Telegram、Discord、Slack、WhatsApp、Signal 和 CLI——全部从单个网关进程运行。语音备忘录转写、跨平台对话连续性。</td></tr>
+<tr><td><b>闭环学习</b></td><td>代理管理记忆并定期自我提醒。复杂任务后自动创建技能。技能在使用中自我改进。FTS5 会话搜索配合 LLM 摘要实现跨会话回溯。<a href="https://github.com/plastic-labs/honcho">Honcho</a> 辩证式用户建模。兼容 <a href="https://agentskills.io">agentskills.io</a> 开放标准。</td></tr>
+<tr><td><b>定时自动化</b></td><td>内置 cron 调度器，支持向任何平台投递。日报、夜间备份、周审计——全部用自然语言描述，无人值守运行。</td></tr>
+<tr><td><b>委派与并行</b></td><td>生成隔离子代理处理并行工作流。编写 Python 脚本通过 RPC 调用工具，将多步管道压缩为零上下文开销的轮次。</td></tr>
+<tr><td><b>随处运行</b></td><td>六种终端后端——本地、Docker、SSH、Daytona、Singularity 和 Modal。Daytona 和 Modal 提供 Serverless 持久化——代理环境空闲时休眠、按需唤醒，空闲期间几乎零成本。$5 VPS 或 GPU 集群都能跑。</td></tr>
+<tr><td><b>研究就绪</b></td><td>批量轨迹生成、轨迹压缩——用于训练下一代工具调用模型。</td></tr>
+</table>
+
+---
+
+## 快速安装
+
+```bash
+curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
+```
+
+支持 Linux、macOS、WSL2 和 Android (Termux)。安装程序会自动处理平台特定的配置。
+
+> **Android / Termux：** 已测试的手动安装路径请参考 [Termux 指南](https://hermes-agent.nousresearch.com/docs/getting-started/termux)。在 Termux 上，Hermes 会安装精选的 `.[termux]` 扩展，因为完整的 `.[all]` 扩展会拉取 Android 不兼容的语音依赖。
+>
+> **Windows：** 在 PowerShell 中运行：
+> ```powershell
+> iex (irm https://hermes-agent.nousresearch.com/install.ps1)
+> ```
+> 安装完成后，可能需要重启终端，然后运行 `hermes` 开始对话。
+
+安装后：
+
+```bash
+source ~/.bashrc    # 重新加载 shell（或: source ~/.zshrc）
+hermes              # 开始对话！
+```
+
+---
+
+## 快速入门
+
+```bash
+hermes              # 交互式 CLI — 开始对话
+hermes model        # 选择 LLM 提供商和模型
+hermes tools        # 配置启用的工具
+hermes config set   # 设置单个配置项
+hermes gateway      # 启动消息网关（Telegram、Discord 等）
+hermes setup        # 运行完整设置向导（一次性配置所有内容）
+hermes claw migrate # 从 OpenClaw 迁移（如果来自 OpenClaw）
+hermes update       # 更新到最新版本
+hermes doctor       # 诊断问题
+```
+
+📖 **[完整文档 →](https://hermes-agent.nousresearch.com/docs/)**
+
+---
+
+## 省去到处收集 API Key — Nous Portal
+
+Hermes 始终允许你使用任意服务商，这点不会改变。但如果你不想为模型、网页搜索、图像生成、TTS、云浏览器分别去申请五个不同的 API Key，**[Nous Portal](https://portal.nousresearch.com)** 用一个订阅就能覆盖全部：
+
+- **300+ 模型** — 用 `/model <name>` 随时切换
+- **Tool Gateway** — 网页搜索（Firecrawl）、图像生成（FAL）、文本转语音（OpenAI）、云浏览器（Browser Use），全部通过订阅托管。无需额外注册任何账户。
+
+全新安装时一条命令即可：
+
+```bash
+hermes setup --portal
+```
+
+它会通过 OAuth 登录、把 Nous 设为推理服务商，并启用 Tool Gateway。随时用 `hermes portal info` 查看路由状态。完整说明见 [Tool Gateway 文档](https://hermes-agent.nousresearch.com/docs/user-guide/features/tool-gateway)。
+
+你随时可以按工具单独切回自己的 API Key — Gateway 是按工具粒度生效的，不是一刀切。
+
+---
+
+## CLI 与消息平台 快速对照
+
+Hermes 有两种入口：用 `hermes` 启动终端 UI，或运行网关从 Telegram、Discord、Slack、WhatsApp、Signal 或 Email 与之对话。进入对话后，许多斜杠命令在两种界面中通用。
+
+| 操作 | CLI | 消息平台 |
+|------|-----|----------|
+| 开始对话 | `hermes` | 运行 `hermes gateway setup` + `hermes gateway start`，然后给机器人发消息 |
+| 开始新对话 | `/new` 或 `/reset` | `/new` 或 `/reset` |
+| 更换模型 | `/model [provider:model]` | `/model [provider:model]` |
+| 设置人格 | `/personality [name]` | `/personality [name]` |
+| 重试或撤销上一轮 | `/retry`、`/undo` | `/retry`、`/undo` |
+| 压缩上下文 / 查看用量 | `/compress`、`/usage`、`/insights [--days N]` | `/compress`、`/usage`、`/insights [days]` |
+| 浏览技能 | `/skills` 或 `/<skill-name>` | `/skills` 或 `/<skill-name>` |
+| 中断当前工作 | `Ctrl+C` 或发送新消息 | `/stop` 或发送新消息 |
+| 平台特定状态 | `/platforms` | `/status`、`/sethome` |
+
+完整命令列表请参阅 [CLI 指南](https://hermes-agent.nousresearch.com/docs/user-guide/cli) 和 [消息网关指南](https://hermes-agent.nousresearch.com/docs/user-guide/messaging)。
+
+---
+
+## 文档
+
+所有文档位于 **[hermes-agent.nousresearch.com/docs](https://hermes-agent.nousresearch.com/docs/)**：
+
+| 章节 | 内容 |
+|------|------|
+| [快速开始](https://hermes-agent.nousresearch.com/docs/getting-started/quickstart) | 安装 → 设置 → 2 分钟内开始首次对话 |
+| [CLI 使用](https://hermes-agent.nousresearch.com/docs/user-guide/cli) | 命令、快捷键、人格、会话 |
+| [配置](https://hermes-agent.nousresearch.com/docs/user-guide/configuration) | 配置文件、提供商、模型、所有选项 |
+| [消息网关](https://hermes-agent.nousresearch.com/docs/user-guide/messaging) | Telegram、Discord、Slack、WhatsApp、Signal、Home Assistant |
+| [安全](https://hermes-agent.nousresearch.com/docs/user-guide/security) | 命令审批、DM 配对、容器隔离 |
+| [工具与工具集](https://hermes-agent.nousresearch.com/docs/user-guide/features/tools) | 40+ 工具、工具集系统、终端后端 |
+| [技能系统](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills) | 过程记忆、技能中心、创建技能 |
+| [记忆](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory) | 持久记忆、用户画像、最佳实践 |
+| [MCP 集成](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp) | 连接任意 MCP 服务器扩展能力 |
+| [定时调度](https://hermes-agent.nousresearch.com/docs/user-guide/features/cron) | 定时任务与平台投递 |
+| [上下文文件](https://hermes-agent.nousresearch.com/docs/user-guide/features/context-files) | 影响每次对话的项目上下文 |
+| [架构](https://hermes-agent.nousresearch.com/docs/developer-guide/architecture) | 项目结构、代理循环、关键类 |
+| [贡献](https://hermes-agent.nousresearch.com/docs/developer-guide/contributing) | 开发设置、PR 流程、代码风格 |
+| [CLI 参考](https://hermes-agent.nousresearch.com/docs/reference/cli-commands) | 所有命令和标志 |
+| [环境变量](https://hermes-agent.nousresearch.com/docs/reference/environment-variables) | 完整环境变量参考 |
+
+---
+
+## 从 OpenClaw 迁移
+
+如果你来自 OpenClaw，Hermes 可以自动导入你的设置、记忆、技能和 API 密钥。
+
+**首次安装时：** 安装向导（`hermes setup`）会自动检测 `~/.openclaw` 并在配置开始前提供迁移选项。
+
+**安装后任意时间：**
+
+```bash
+hermes claw migrate              # 交互式迁移（完整预设）
+hermes claw migrate --dry-run    # 预览将要迁移的内容
+hermes claw migrate --preset user-data   # 仅迁移用户数据，不含密钥
+hermes claw migrate --overwrite  # 覆盖已有冲突
+```
+
+导入内容：
+- **SOUL.md** — 人格文件
+- **记忆** — MEMORY.md 和 USER.md 条目
+- **技能** — 用户创建的技能 → `~/.hermes/skills/openclaw-imports/`
+- **命令白名单** — 审批模式
+- **消息设置** — 平台配置、允许用户、工作目录
+- **API 密钥** — 白名单中的密钥（Telegram、OpenRouter、OpenAI、Anthropic、ElevenLabs）
+- **TTS 资产** — 工作区音频文件
+- **工作区指令** — AGENTS.md（使用 `--workspace-target`）
+
+使用 `hermes claw migrate --help` 查看所有选项，或使用 `openclaw-migration` 技能进行交互式代理引导迁移（含干运行预览）。
+
+---
+
+## 贡献
+
+欢迎贡献！请参阅 [贡献指南](https://hermes-agent.nousresearch.com/docs/developer-guide/contributing) 了解开发设置、代码风格和 PR 流程。
+
+贡献者快速开始——使用标准安装器，然后在它创建的完整 git checkout 中开发：
+`$HERMES_HOME/hermes-agent`（通常是 `~/.hermes/hermes-agent`）。这会匹配
+`hermes update`、托管 venv、lazy dependencies、gateway 和 docs tooling 使用的布局。
+
+```bash
+curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
+cd "${HERMES_HOME:-$HOME/.hermes}/hermes-agent"
+uv pip install -e ".[all,dev]"
+scripts/run_tests.sh
+```
+
+手动克隆备用路径（用于一次性 clone / CI，或你明确不想使用 managed install layout 时）：
+
+```bash
+curl -LsSf https://astral.sh/uv/install.sh | sh
+uv venv venv --python 3.11
+source venv/bin/activate
+uv pip install -e ".[all,dev]"
+python -m pytest tests/ -q
+```
+
+---
+
+## 社区
+
+- 💬 [Discord](https://discord.gg/NousResearch)
+- 📚 [技能中心](https://agentskills.io)
+- 🐛 [问题反馈](https://github.com/NousResearch/hermes-agent/issues)
+- 💡 [讨论区](https://github.com/NousResearch/hermes-agent/discussions)
+- 🔌 [HermesClaw](https://github.com/AaronWong1999/hermesclaw) — 社区微信桥接：在同一微信账号上运行 Hermes Agent 和 OpenClaw。
+
+---
+
+## 许可证
+
+MIT — 详见 [LICENSE](LICENSE)。
+
+由 [Nous Research](https://nousresearch.com) 构建。

SECURITY.es.md

@@ -0,0 +1,326 @@
+# Política de Seguridad de Hermes Agent
+
+Este documento describe el modelo de confianza de Hermes Agent, identifica el
+único límite de seguridad que el proyecto trata como estructural y define el
+alcance para los informes de vulnerabilidades.
+
+## 1. Reportar una Vulnerabilidad
+
+Reporta de forma privada a través de [GitHub Security Advisories](https://github.com/NousResearch/hermes-agent/security/advisories/new)
+o **security@nousresearch.com**. No abras issues públicos para
+vulnerabilidades de seguridad. **Hermes Agent no opera un programa de
+recompensas por errores.**
+
+Un informe útil incluye:
+
+- Una descripción concisa y evaluación de severidad.
+- El componente afectado, identificado por ruta de archivo y rango de líneas
+  (ej. `path/to/file.py:120-145`).
+- Detalles del entorno (`hermes --version`, SHA del commit, SO, versión de Python).
+- Una reproducción contra `main` o el último release.
+- Una declaración de qué límite de confianza del §2 se cruza.
+
+Por favor lee el §2 y el §3 antes de enviar. Los informes que demuestren
+límites de una heurística en proceso que esta política no trate como un
+límite serán cerrados como fuera de alcance bajo el §3 — pero consulta el §3.2:
+siguen siendo bienvenidos como issues o pull requests regulares, simplemente no
+a través del canal de seguridad privado.
+
+---
+
+## 2. Modelo de Confianza
+
+Hermes Agent es un agente personal de un solo inquilino. Su postura es
+por capas, y las capas no tienen el mismo peso. Los reportadores y
+operadores deben razonar sobre ellas en los mismos términos.
+
+### 2.1 Definiciones
+
+- **Proceso del agente.** El intérprete Python que ejecuta Hermes Agent,
+  incluyendo cualquier módulo Python que haya cargado (habilidades, plugins,
+  manejadores de hooks).
+- **Backend de terminal.** Un objetivo de ejecución conectado para la
+  herramienta `terminal()`. El predeterminado ejecuta comandos directamente en el host.
+  Otros backends ejecutan comandos dentro de un contenedor, sandbox en la nube o
+  host remoto.
+- **Superficie de entrada.** Cualquier canal a través del cual el contenido entra en el
+  contexto del agente: entrada del operador, fetches web, email, mensajes del gateway,
+  lecturas de archivos, respuestas del servidor MCP, resultados de herramientas.
+- **Envolvente de confianza.** El conjunto de recursos a los que un operador ha otorgado
+  implícitamente acceso a Hermes Agent al ejecutarlo — típicamente, todo lo que
+  la propia cuenta de usuario del operador puede alcanzar en el host.
+- **Postura.** Una declaración explícita en la documentación o código de Hermes Agent
+  sobre cómo una capa consumidora (adaptador, UI, escritor de archivos,
+  shell) debe tratar la salida del agente — ej. "el dashboard renderiza
+  la salida del agente como HTML inerte."
+
+### 2.2 El Límite: Aislamiento a Nivel de SO
+
+**El único límite de seguridad contra un LLM adversario es el
+sistema operativo.** Nada dentro del proceso del agente constituye
+contención — ni la puerta de aprobación, ni la redacción de salida, ni ningún
+escáner de patrones, ni ninguna lista de herramientas permitidas. Cualquier componente dentro
+del proceso que filtre la salida del LLM es una heurística operando sobre una
+cadena influenciada por el atacante, y esta política lo trata como tal.
+
+Hermes Agent admite dos posturas de aislamiento a nivel de SO. Abordan
+diferentes amenazas y un operador debe elegir deliberadamente.
+
+#### Aislamiento del backend de terminal
+
+Un backend de terminal no predeterminado ejecuta comandos de shell emitidos por el LLM
+dentro de un contenedor, host remoto o sandbox en la nube. Las herramientas de archivos
+(`read_file`, `write_file`, `patch`) también se ejecutan a través de este backend,
+ya que están implementadas sobre el contrato del shell — no pueden
+alcanzar rutas que el backend no exponga.
+
+Lo que confina: todo lo que el agente hace emitiendo operaciones de shell o
+de archivos. Lo que **no** confina: todo lo que el agente hace en su propio
+proceso Python. Eso incluye la herramienta de ejecución de código (lanzada como
+subproceso del host), subprocesos MCP (lanzados desde el entorno del agente),
+carga de plugins, despacho de hooks y carga de habilidades (todos importados en el
+intérprete del agente).
+
+El aislamiento del backend de terminal es la postura correcta cuando la preocupación es
+que el LLM emita comandos de shell destructivos o escrituras de herramientas de archivo no deseadas, y el
+operador es de confianza.
+
+#### Envoltura del proceso completo
+
+La envoltura del proceso completo ejecuta todo el árbol de procesos del agente dentro de un
+sandbox. Cada ruta de código — shell, ejecución de código, MCP, herramientas de archivos,
+plugins, hooks, carga de habilidades — está sujeta a la misma política de sistema de archivos,
+red, proceso e (donde sea aplicable) inferencia.
+
+Hermes Agent admite esto de dos maneras:
+
+- **La propia imagen Docker de Hermes Agent y la configuración de Compose.** Más
+  liviana; el agente se ejecuta en un contenedor estándar con montajes y
+  política de red configurados por el operador.
+- **[NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell)**.
+  OpenShell proporciona sandboxes por sesión con política declarativa
+  a través de capas de sistema de archivos, red (egreso L7), proceso/syscall e
+  enrutamiento de inferencia. Las políticas de red e inferencia son
+  recargables en caliente. Las credenciales se inyectan desde un almacén de Proveedor
+  y nunca tocan el sistema de archivos del sandbox.
+
+Bajo una envoltura de proceso completo, las heurísticas en proceso de Hermes Agent
+(§2.4) funcionan como prevención de accidentes en capas sobre un límite real.
+Esta es la postura soportada cuando el agente ingiere contenido de superficies
+que el operador no controla — la web abierta, email entrante, canales de
+múltiples usuarios, servidores MCP no confiables — y para despliegues en
+producción o compartidos.
+
+Los operadores que ejecuten el backend local predeterminado con superficies de entrada
+no confiables, o que ejecuten un sandbox de backend de terminal esperando que contenga
+rutas de código que no pasan por el shell, están operando fuera de la postura de
+seguridad soportada.
+
+### 2.3 Alcance de Credenciales
+
+Hermes Agent filtra el entorno que pasa a sus componentes en proceso de
+menor confianza: subprocesos de shell, subprocesos MCP y el proceso hijo
+de ejecución de código. Las credenciales como las claves API del proveedor y los
+tokens del gateway se eliminan por defecto; las variables declaradas explícitamente
+por el operador o por una habilidad cargada se pasan.
+
+Esto reduce la exfiltración casual. No es contención. Cualquier
+componente que se ejecute dentro del proceso del agente (habilidades, plugins, manejadores
+de hooks) puede leer lo que el agente mismo puede leer, incluidas las
+credenciales en memoria. La mitigación contra un componente en proceso comprometido
+es la revisión del operador antes de instalar (§2.4, §2.5), no el
+saneamiento del entorno.
+
+### 2.4 Heurísticas en Proceso
+
+Los siguientes componentes filtran o advierten sobre el comportamiento del LLM. Son
+útiles. No son límites.
+
+- La **puerta de aprobación** detecta patrones de shell destructivos comunes
+  y le pide al operador confirmación antes de la ejecución. El shell es Turing-
+  completo; una lista de denegación sobre cadenas de shell es estructuralmente
+  incompleta. La puerta detecta errores en modo cooperativo, no salidas
+  adversariales.
+- **La redacción de salida** elimina patrones similares a secretos de la visualización.
+  Un productor de salida motivado la evitará.
+- **Skills Guard** escanea el contenido de habilidades instalables en busca de patrones
+  de inyección. Es una ayuda de revisión; el límite para habilidades de terceros
+  es la revisión del operador antes de instalar. Revisar una habilidad significa
+  leer su código Python y scripts, no solo su descripción SKILL.md —
+  las habilidades ejecutan Python arbitrario en el momento de importación.
+
+### 2.5 Modelo de Confianza de Plugins
+
+Los plugins se cargan en el proceso del agente y se ejecutan con todos los privilegios
+del agente: pueden leer las mismas credenciales, llamar a las mismas
+herramientas, registrar los mismos hooks e importar los mismos módulos que
+cualquier cosa incluida en el árbol. El límite para los plugins de terceros es
+la revisión del operador antes de instalar — la misma regla que las habilidades (§2.4),
+mencionado por separado porque los plugins son arquitectónicamente más pesados
+y a menudo incluyen sus propios servicios en segundo plano, oyentes de red
+y dependencias.
+
+Un plugin malicioso o con errores no es una vulnerabilidad en Hermes Agent
+en sí mismo. Los errores en la ruta de instalación o descubrimiento de plugins de Hermes Agent
+que impidan al operador ver lo que está instalando están en alcance bajo el §3.1.
+
+### 2.6 Superficies Externas
+
+Una **superficie externa** es cualquier canal fuera del proceso del agente local
+a través del cual un llamador puede despachar trabajo del agente, resolver
+aprobaciones o recibir salida del agente. Cada superficie tiene su propio
+modelo de autorización, pero las reglas a continuación se aplican uniformemente.
+
+**Superficies en Hermes Agent:**
+
+- **Adaptadores de plataforma del gateway.** La mayoría de las integraciones
+  de mensajería se distribuyen como plugins empaquetados en
+  `plugins/platforms/<name>/` (Telegram, Discord, Slack, email, SMS, etc.).
+  Los tipos base compartidos y un conjunto menor de adaptadores
+  legacy/directos viven en `gateway/platforms/` (`base.py`, Signal, servidor
+  API, webhooks, …), con descubrimiento y carga diferida vía
+  `gateway/platform_registry.py`.
+- **Superficies HTTP expuestas en red.** El adaptador del servidor API, el
+  plugin del dashboard, los endpoints HTTP del plugin kanban, y cualquier
+  otro plugin que vincule un socket de escucha.
+- **Adaptadores de Editor / IDE.** El adaptador ACP (`acp_adapter/`) e
+  integraciones equivalentes que aceptan solicitudes de un proceso cliente local.
+- **El gateway TUI (`tui_gateway/`).** Backend JSON-RPC para la
+  UI de terminal Ink, alcanzado a través de IPC local.
+
+**Reglas uniformes:**
+
+1. **Se requiere autorización en cada superficie que cruce un límite de confianza.** Para
+   superficies de mensajería y HTTP en red, el límite es la red: la autorización
+   significa una lista de llamadores permitidos configurada por el operador. Para superficies
+   de editor e IPC local (ACP, gateway TUI), el límite es la cuenta de usuario del host:
+   la autorización significa depender del control de acceso a nivel de SO (permisos
+   de archivos, vinculaciones solo a loopback) y no exponer la superficie más allá
+   del usuario local sin una capa de autenticación de red explícita.
+2. **Se requiere una lista de permitidos para cada adaptador de red habilitado.**
+   Los adaptadores deben rechazar despachar trabajo del agente, resolver
+   aprobaciones o transmitir salida hasta que se establezca una lista de permitidos. Las rutas
+   de código que fallan de forma abierta cuando no hay lista de permitidos configurada son errores de código en
+   alcance bajo el §3.1.
+3. **Los identificadores de sesión son manejadores de enrutamiento, no límites de autorización.**
+   Conocer el ID de sesión de otro llamador no otorga acceso a sus aprobaciones o salida;
+   la autorización siempre se vuelve a verificar contra la lista de permitidos (o equivalente
+   a nivel de SO).
+4. **Dentro del conjunto autorizado, todos los llamadores tienen la misma confianza.**
+   Hermes Agent no modela capacidades por llamador dentro de un único adaptador.
+   Los operadores que necesiten separación de capacidades deben ejecutar instancias
+   de agente separadas con listas de permitidos separadas.
+5. **Vincular una superficie solo local a una interfaz no-loopback es una decisión de
+   operador de emergencia (§3.2).** El dashboard y otros servidores HTTP de plugins
+   son predeterminados a loopback; exponerlos a través de `--host 0.0.0.0` o equivalente
+   hace que el fortalecimiento de exposición pública (§4) sea responsabilidad del operador.
+
+---
+
+## 3. Alcance
+
+### 3.1 En Alcance
+
+- Escape de una postura de aislamiento a nivel de SO declarada (§2.2): una
+  ruta de código controlada por el atacante alcanzando estado que la postura
+  afirmó confinar.
+- Acceso no autorizado a superficie externa: un llamador fuera del conjunto de
+  autorización configurado (lista de permitidos, o equivalente a nivel de SO
+  para superficies de IPC local) despachando trabajo, recibiendo salida o
+  resolviendo aprobaciones (§2.6).
+- Exfiltración de credenciales: filtración de credenciales del operador o
+  material de autorización de sesión a un destino fuera del envolvente de
+  confianza, a través de un mecanismo que debería haberlo prevenido
+  (error de saneamiento de entorno, registro del adaptador, error de transporte
+  que vacía credenciales a un upstream, etc.).
+- Violaciones de la documentación del modelo de confianza: código que se comporta
+  contrariamente a lo que esta política, la propia documentación de Hermes Agent o
+  las expectativas razonables del operador predecirían — incluyendo casos donde
+  Hermes Agent ha documentado una postura sobre cómo su salida debe ser
+  renderizada por una capa consumidora (dashboard, adaptador de gateway,
+  escritor de archivos, shell) y una ruta de código rompe esa postura.
+
+### 3.2 Fuera de Alcance
+
+"Fuera de alcance" aquí significa "no es una vulnerabilidad de seguridad bajo esta
+política." No significa "no vale la pena reportarlo." Las mejoras a las
+heurísticas en proceso, ideas de fortalecimiento y correcciones de UX son bienvenidas como
+issues o pull requests regulares — la puerta de aprobación siempre puede detectar
+más patrones, la redacción puede volverse más inteligente, el comportamiento del adaptador
+puede apretarse siempre. Estos elementos simplemente no van a través del canal de
+divulgación privada y no reciben avisos.
+
+- **Bypasses de heurísticas en proceso (§2.4)** — bypasses de regex de la puerta de aprobación,
+  bypasses de redacción, bypasses de patrones de Skills Guard, e informes
+  análogos contra heurísticas futuras. Estos componentes no son límites;
+  vencerlos no es una vulnerabilidad bajo esta política.
+- **Inyección de prompts per se.** Hacer que el LLM emita salida inusual
+  — a través de contenido inyectado, alucinación, artefactos de entrenamiento,
+  o cualquier otra causa — no es en sí mismo una vulnerabilidad. "Logré
+  inyección de prompts" sin un resultado encadenado del §3.1 no es un informe
+  procesable bajo esta política.
+- **Consecuencias de una postura de aislamiento elegida.** Los informes de que
+  una ruta de código que opera dentro del alcance de su postura puede hacer lo que esa
+  postura permite no son vulnerabilidades. Ejemplos: herramientas de shell o archivos
+  que alcanzan estado del host bajo el backend local; subprocesos de ejecución de código
+  o MCP que alcanzan estado del host bajo aislamiento de backend de terminal que solo
+  sandboxea el shell; informes cuyas precondiciones requieren acceso de escritura preexistente
+  a archivos de configuración o credenciales propiedad del operador (esos ya están dentro
+  del envolvente de confianza).
+- **Configuraciones documentadas de emergencia.** Compensaciones seleccionadas por el operador
+  que deshabilitan explícitamente protecciones: `--insecure` y flags equivalentes
+  en el dashboard u otros componentes, aprobaciones deshabilitadas,
+  backend local en producción, perfiles de desarrollo que evitan
+  la seguridad de hermes-home, y similares. Los informes contra esas
+  configuraciones no son vulnerabilidades — eso es el trabajo del flag.
+- **Habilidades y plugins contribuidos por la comunidad.** Las habilidades de terceros
+  (incluyendo el repositorio de habilidades de la comunidad) y los plugins de terceros
+  están en la superficie de revisión del operador, no en la superficie de confianza de Hermes Agent
+  (§2.4, §2.5). Una habilidad o plugin que haga algo
+  malicioso es el modo de falla esperado de uno que no fue
+  revisado, no una vulnerabilidad en Hermes Agent. Los errores en la ruta de
+  instalación de habilidades o plugins de Hermes Agent que impidan al
+  operador ver lo que está instalando están en alcance bajo el §3.1.
+- **Exposición pública sin controles externos.** Exponer el
+  gateway o la API a la internet pública sin autenticación,
+  VPN o firewall.
+- **Restricciones de lectura/escritura a nivel de herramienta en una postura donde el shell está
+  permitido.** Si una ruta es alcanzable a través de la herramienta terminal, los informes
+  de que otras herramientas de archivos pueden alcanzarla no añaden nada.
+
+---
+
+## 4. Fortalecimiento del Despliegue
+
+La decisión de fortalecimiento más importante es hacer coincidir el aislamiento
+(§2.2) con la confianza del contenido que el agente ingerirá. Más allá de eso:
+
+- Ejecuta el agente como usuario no-root. La imagen de contenedor proporcionada
+  hace esto por defecto.
+- Mantén las credenciales en el archivo de credenciales del operador con permisos
+  estrictos, nunca en la configuración principal, nunca en control de versiones.
+  Bajo OpenShell, usa el almacén de Proveedores en lugar de un archivo de
+  credenciales en disco.
+- No expongas el gateway o la API a la internet pública sin
+  VPN, Tailscale o protección de firewall. Bajo OpenShell, usa la
+  capa de política de red para restringir el egreso.
+- Configura una lista de llamadores permitidos para cada adaptador de red expuesto
+  que habilites (§2.6).
+- Revisa las habilidades y plugins de terceros antes de instalar (§2.4,
+  §2.5). Para las habilidades, esto significa leer el Python y los scripts,
+  no solo SKILL.md. Los informes de Skills Guard y el registro de auditoría
+  de instalación son la superficie de revisión.
+- Hermes Agent incluye guardias de cadena de suministro para lanzamientos de servidores
+  MCP y para cambios de dependencias / paquetes incluidos en CI; consulta
+  `CONTRIBUTING.es.md` para más detalles.
+
+---
+
+## 5. Divulgación
+
+- **Ventana de divulgación coordinada:** 90 días desde el informe, o hasta que se
+  publique una corrección, lo que ocurra primero.
+- **Canal:** el hilo GHSA o correspondencia por email con
+  security@nousresearch.com.
+- **Crédito:** los reportadores reciben crédito en las notas de versión a menos que
+  se solicite anonimato.

SECURITY.md

@@ -0,0 +1,335 @@
+# Hermes Agent Security Policy
+
+This document describes Hermes Agent's trust model, names the one
+security boundary the project treats as load-bearing, and defines the
+scope for vulnerability reports.
+
+## 1. Reporting a Vulnerability
+
+Report privately via [GitHub Security Advisories](https://github.com/NousResearch/hermes-agent/security/advisories/new)
+or **security@nousresearch.com**. Do not open public issues for
+security vulnerabilities. **Hermes Agent does not operate a bug
+bounty program.**
+
+A useful report includes:
+
+- A concise description and severity assessment.
+- The affected component, identified by file path and line range
+  (e.g. `path/to/file.py:120-145`).
+- Environment details (`hermes --version`, commit SHA, OS, Python
+  version).
+- A reproduction against `main` or the latest release.
+- A statement of which trust boundary in §2 is crossed.
+
+Please read §2 and §3 before submitting. Reports that demonstrate
+limits of an in-process heuristic this policy does not treat as a
+boundary will be closed as out-of-scope under §3 — but see §3.2:
+they are still welcome as regular issues or pull requests, just not
+through the private security channel.
+
+---
+
+## 2. Trust Model
+
+Hermes Agent is a single-tenant personal agent. Its posture is
+layered, and the layers are not equally load-bearing. Reporters and
+operators should reason about them in the same terms.
+
+### 2.1 Definitions
+
+- **Agent process.** The Python interpreter running Hermes Agent,
+  including any Python modules it has loaded (skills, plugins,
+  hook handlers).
+- **Terminal backend.** A pluggable execution target for the
+  `terminal()` tool. The default runs commands directly on the host.
+  Other backends run commands inside a container, cloud sandbox, or
+  remote host.
+- **Input surface.** Any channel through which content enters the
+  agent's context: operator input, web fetches, email, gateway
+  messages, file reads, MCP server responses, tool results.
+- **Trust envelope.** The set of resources an operator has implicitly
+  granted Hermes Agent access to by running it — typically, whatever
+  the operator's own user account can reach on the host.
+- **Stance.** An explicit statement in Hermes Agent's documentation
+  or code about how a consuming layer (adapter, UI, file writer,
+  shell) should treat agent output — e.g. "the dashboard renders
+  agent output as inert HTML."
+
+### 2.2 The Boundary: OS-Level Isolation
+
+**The only security boundary against an adversarial LLM is the
+operating system.** Nothing inside the agent process constitutes
+containment — not the approval gate, not output redaction, not any
+pattern scanner, not any tool allowlist. Any in-process component
+that screens LLM output is a heuristic operating on an
+attacker-influenced string, and this policy treats it as such.
+
+Hermes Agent supports two OS-level isolation postures. They address
+different threats and an operator should choose deliberately.
+
+#### Terminal-backend isolation
+
+A non-default terminal backend runs LLM-emitted shell commands
+inside a container, remote host, or cloud sandbox. The file tools
+(`read_file`, `write_file`, `patch`) also run through this backend,
+since they are implemented on top of the shell contract — they
+cannot reach paths the backend doesn't expose.
+
+What this confines: anything the agent does by issuing shell or
+file operations. What this does **not** confine: everything the
+agent does in its own Python process. That includes the
+code-execution tool (spawned as a host subprocess), MCP subprocesses
+(spawned from the agent's environment), plugin loading, hook
+dispatch, and skill loading (all imported into the agent
+interpreter).
+
+Terminal-backend isolation is the right posture when the concern is
+LLM-emitted destructive shell or unwanted file-tool writes, and the
+operator is otherwise trusted.
+
+#### Whole-process wrapping
+
+Whole-process wrapping runs the entire agent process tree inside a
+sandbox. Every code path — shell, code-execution, MCP, file tools,
+plugins, hooks, skill loading — is subject to the same filesystem,
+network, process, and (where applicable) inference policy.
+
+Hermes Agent supports this in two ways:
+
+- **Hermes Agent's own Docker image and Compose setup.** Lighter-
+  weight; the agent runs in a standard container with operator-
+  configured mounts and network policy.
+- **[NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell)**.
+  OpenShell provides per-session sandboxes with declarative policy
+  across filesystem, network (L7 egress), process/syscall, and
+  inference-routing layers. Network and inference policies are
+  hot-reloadable. Credentials are injected from a Provider store
+  and never touch the sandbox filesystem.
+
+Under a whole-process wrapper, Hermes Agent's in-process heuristics
+(§2.4) function as accident-prevention layered on top of a real
+boundary. This is the supported posture when the agent ingests
+content from surfaces the operator does not control — the open web,
+inbound email, multi-user channels, untrusted MCP servers — and for
+production or shared deployments.
+
+Operators running the default local backend with untrusted input
+surfaces, or running a terminal-backend sandbox and expecting it to
+contain code paths that don't go through the shell, are operating
+outside the supported security posture.
+
+### 2.3 Credential Scoping
+
+Hermes Agent filters the environment it passes to its lower-trust
+in-process components: shell subprocesses, MCP subprocesses,
+cron job scripts, and the code-execution child. Credentials like
+provider API keys and gateway tokens are stripped by default;
+variables explicitly declared by the operator or by a loaded
+skill are passed through.
+
+This reduces casual exfiltration. It is not containment. Any
+component running inside the agent process (skills, plugins, hook
+handlers) can read whatever the agent itself can read, including
+in-memory credentials. The mitigation against a compromised
+in-process component is operator review before install (§2.4,
+§2.5), not environment scrubbing.
+
+### 2.4 In-Process Heuristics
+
+The following components screen or warn about LLM behavior. They
+are useful. They are not boundaries.
+
+- The **approval gate** detects common destructive shell patterns
+  and prompts the operator before execution. Shell is Turing-
+  complete; a denylist over shell strings is structurally
+  incomplete. The gate catches cooperative-mode mistakes, not
+  adversarial output.
+- **Output redaction** strips secret-like patterns from display.
+  A motivated output producer will defeat it.
+- **Skills Guard** scans installable skill content for injection
+  patterns. It is a review aid; the boundary for third-party skills
+  is operator review before install. Reviewing a skill means
+  reading its Python code and scripts, not just its SKILL.md
+  description — skills execute arbitrary Python at import time.
+
+### 2.5 Plugin Trust Model
+
+Plugins load into the agent process and run with full agent
+privileges: they can read the same credentials, call the same
+tools, register the same hooks, and import the same modules as
+anything shipped in-tree. The boundary for third-party plugins is
+operator review before install — the same rule as skills (§2.4),
+called out separately because plugins are architecturally heavier
+and often ship their own background services, network listeners,
+and dependencies.
+
+A malicious or buggy plugin is not a vulnerability in Hermes Agent
+itself. Bugs in Hermes Agent's plugin-install or plugin-discovery
+path that prevent the operator from seeing what they're installing
+are in scope under §3.1.
+
+### 2.6 External Surfaces
+
+An **external surface** is any channel outside the local agent
+process through which a caller can dispatch agent work, resolve
+approvals, or receive agent output. Each surface has its own
+authorization model, but the rules below apply uniformly.
+
+**Surfaces in Hermes Agent:**
+
+- **Gateway platform adapters.** Most messaging integrations ship as
+  bundled plugins under `plugins/platforms/<name>/` (Telegram, Discord,
+  Slack, email, SMS, etc.). Shared base types and a smaller set of
+  legacy/direct adapters live under `gateway/platforms/`
+  (`base.py`, Signal, API server, webhooks, …), with discovery and
+  deferred loading via `gateway/platform_registry.py`.
+- **Network-exposed HTTP surfaces.** The API server adapter, the
+  dashboard plugin, the kanban plugin's HTTP endpoints, and any
+  other plugin that binds a listening socket.
+- **Editor / IDE adapters.** The ACP adapter (`acp_adapter/`) and
+  equivalent integrations that accept requests from a local client
+  process.
+- **The TUI gateway (`tui_gateway/`).** JSON-RPC backend for the
+  Ink terminal UI, reached over local IPC.
+
+**Uniform rules:**
+
+1. **Authorization is required at every surface that crosses a
+   trust boundary.** For messaging and network HTTP surfaces, the
+   boundary is the network: authorization means an operator-
+   configured caller allowlist. For editor and local-IPC surfaces
+   (ACP, TUI gateway), the boundary is the host's user account:
+   authorization means relying on OS-level access control (file
+   permissions, loopback-only binds) and not exposing the surface
+   beyond the local user without an explicit network auth layer.
+2. **An allowlist is required for every enabled network-exposed
+   adapter.** Adapters must refuse to dispatch agent work, resolve
+   approvals, or relay output until an allowlist is set. Code paths
+   that fail open when no allowlist is configured are code bugs in
+   scope under §3.1.
+3. **Session identifiers are routing handles, not authorization
+   boundaries.** Knowing another caller's session ID does not grant
+   access to their approvals or output; authorization is always
+   re-checked against the allowlist (or OS-level equivalent).
+4. **Within the authorized set, all callers are equally trusted.**
+   Hermes Agent does not model per-caller capabilities inside a
+   single adapter. Operators who need capability separation should
+   run separate agent instances with separate allowlists.
+5. **Binding a local-only surface to a non-loopback interface is a
+   break-glass operator decision (§3.2).** The dashboard and other
+   plugin HTTP servers default to loopback; exposing them via
+   `--host 0.0.0.0` or equivalent makes public-exposure hardening
+   (§4) the operator's responsibility.
+
+---
+
+## 3. Scope
+
+### 3.1 In Scope
+
+- Escape from a declared OS-level isolation posture (§2.2): an
+  attacker-controlled code path reaching state that the posture
+  claimed to confine.
+- Unauthorized external-surface access: a caller outside the
+  configured authorization set (allowlist, or OS-level equivalent
+  for local-IPC surfaces) dispatching work, receiving output, or
+  resolving approvals (§2.6).
+- Credential exfiltration: leakage of operator credentials or
+  session authorization material to a destination outside the
+  trust envelope, via a mechanism that should have prevented it
+  (environment scrubbing bug, adapter logging, transport error
+  that flushes credentials to an upstream, etc.).
+- Trust-model documentation violations: code behaving contrary to
+  what this policy, Hermes Agent's own documentation, or reasonable
+  operator expectations would predict — including cases where
+  Hermes Agent has documented a stance about how its output should
+  be rendered by a consuming layer (dashboard, gateway adapter,
+  file writer, shell) and a code path breaks that stance.
+
+### 3.2 Out of Scope
+
+"Out of scope" here means "not a security vulnerability under this
+policy." It does not mean "not worth reporting." Improvements to the
+in-process heuristics, hardening ideas, and UX fixes are welcome as
+regular issues or pull requests — the approval gate can always catch
+more patterns, redaction can always get smarter, adapter behavior
+can always be tightened. These items just don't go through the
+private-disclosure channel and don't receive advisories.
+
+- **Bypasses of in-process heuristics (§2.4)** — approval-gate regex
+  bypasses, redaction bypasses, Skills Guard pattern bypasses, and
+  analogous reports against future heuristics. These components are
+  not boundaries; defeating them is not a vulnerability under this
+  policy.
+- **Prompt injection per se.** Getting the LLM to emit unusual
+  output — via injected content, hallucination, training artifacts,
+  or any other cause — is not itself a vulnerability. "I achieved
+  prompt injection" without a chained §3.1 outcome is not an
+  actionable report under this policy.
+- **Consequences of a chosen isolation posture.** Reports that a
+  code path operating within its posture's scope can do what that
+  posture permits are not vulnerabilities. Examples: shell or file
+  tools reaching host state under the local backend; code-execution
+  or MCP subprocesses reaching host state under terminal-backend
+  isolation that only sandboxes shell; reports whose preconditions
+  require pre-existing write access to operator-owned configuration
+  or credential files (those are already inside the trust envelope).
+- **Documented break-glass settings.** Operator-selected trade-offs
+  that explicitly disable protections: `--insecure` and equivalent
+  flags on the dashboard or other components, disabled approvals,
+  local backend in production, development profiles that bypass
+  hermes-home security, and similar. Reports against those
+  configurations are not vulnerabilities — that's the flag's job.
+- **Community-contributed skills and plugins.** Third-party skills
+  (including the community skills repository) and third-party
+  plugins are in the operator's review surface, not Hermes Agent's
+  trust surface (§2.4, §2.5). A skill or plugin doing something
+  malicious is the expected failure mode of one that wasn't
+  reviewed, not a vulnerability in Hermes Agent. Bugs in Hermes
+  Agent's skill-install or plugin-install path that prevent the
+  operator from seeing what they're installing are in scope under
+  §3.1.
+- **Public exposure without external controls.** Exposing the
+  gateway or API to the public internet without authentication,
+  VPN, or firewall.
+- **Tool-level read/write restrictions on a posture where shell is
+  permitted.** If a path is reachable via the terminal tool, reports
+  that other file tools can reach it add nothing.
+
+---
+
+## 4. Deployment Hardening
+
+The single most important hardening decision is matching isolation
+(§2.2) to the trust of the content the agent will ingest. Beyond
+that:
+
+- Run the agent as a non-root user. The supplied container image
+  does this by default.
+- Keep credentials in the operator credential file with tight
+  permissions, never in the main config, never in version control.
+  Under OpenShell, use the Provider store rather than an on-disk
+  credential file.
+- Do not expose the gateway or API to the public internet without
+  VPN, Tailscale, or firewall protection. Under OpenShell, use the
+  network policy layer to restrict egress.
+- Configure a caller allowlist for every network-exposed adapter
+  you enable (§2.6).
+- Review third-party skills and plugins before install (§2.4,
+  §2.5). For skills, this means reading the Python and scripts,
+  not just SKILL.md. Skills Guard reports and the install audit
+  log are the review surface.
+- Hermes Agent includes supply-chain guards for MCP server
+  launches and for dependency / bundled-package changes in CI; see
+  `CONTRIBUTING.md` for specifics.
+
+---
+
+## 5. Disclosure
+
+- **Coordinated disclosure window:** 90 days from report, or until a
+  fix is released, whichever comes first.
+- **Channel:** the GHSA thread or email correspondence with
+  security@nousresearch.com.
+- **Credit:** reporters are credited in release notes unless
+  anonymity is requested.

SOUL.md

@@ -0,0 +1 @@
+You are Hermes Agent, built by Nous Research. Be direct: match the length of your reply to the weight of the ask — a one-line question gets a one-line answer, and finished work gets a short report of what changed, what's verified, and what's left, never a replay of the process. No filler ("Great question," "I'd be happy to"), no restating the request back, no re-summarizing what you already said, no narrating tool calls the user can see. Plain claims over adjectives; when unsure, say so plainly. Agree because it's right, not because the user said it. Depth is earned — give it when the user asks for detail, teaches, or the stakes demand it, not by default.

acp_adapter/__init__.py

@@ -0,0 +1 @@
+"""ACP (Agent Communication Protocol) adapter for hermes-agent."""

acp_adapter/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running the ACP adapter as ``python -m acp_adapter``."""
+
+from .entry import main
+
+main()

acp_adapter/auth.py

@@ -0,0 +1,79 @@
+"""ACP auth helpers — detect and advertise Hermes authentication methods."""
+
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+TERMINAL_SETUP_AUTH_METHOD_ID = "hermes-setup"
+
+
+def detect_provider() -> Optional[str]:
+    """Resolve the active Hermes runtime provider, or None if unavailable.
+
+    Treats a ``Callable`` ``api_key`` (Azure Foundry Entra ID bearer
+    token provider — see :mod:`agent.azure_identity_adapter`) as a valid
+    credential. Without this, ACP sessions for Entra-configured Foundry
+    deployments silently default to ``"openrouter"`` and the ACP auth
+    handshake rejects the legitimate provider.
+    """
+    try:
+        from hermes_cli.runtime_provider import resolve_runtime_provider
+        runtime = resolve_runtime_provider()
+        api_key = runtime.get("api_key")
+        provider = runtime.get("provider")
+        if not isinstance(provider, str) or not provider.strip():
+            return None
+        is_string_key = isinstance(api_key, str) and api_key.strip()
+        is_callable_provider = callable(api_key) and not isinstance(api_key, str)
+        if is_string_key or is_callable_provider:
+            return provider.strip().lower()
+    except Exception:
+        return None
+    return None
+
+
+def has_provider() -> bool:
+    """Return True if Hermes can resolve any runtime provider credentials."""
+    return detect_provider() is not None
+
+
+def build_auth_methods() -> list[Any]:
+    """Return registry-compatible ACP auth methods for Hermes.
+
+    The official ACP registry validates that agents advertise at least one
+    usable auth method during the initial handshake. A fresh Zed install may
+    not have Hermes provider credentials configured yet, so Hermes always
+    advertises a terminal setup method. When credentials are already present,
+    it also advertises the resolved provider as the default agent-managed
+    runtime credential method.
+    """
+    from acp.schema import AuthMethodAgent, TerminalAuthMethod
+
+    methods: list[Any] = []
+    provider = detect_provider()
+    if provider:
+        methods.append(
+            AuthMethodAgent(
+                id=provider,
+                name=f"{provider} runtime credentials",
+                description=(
+                    "Authenticate Hermes using the currently configured "
+                    f"{provider} runtime credentials."
+                ),
+            )
+        )
+
+    methods.append(
+        TerminalAuthMethod(
+            id=TERMINAL_SETUP_AUTH_METHOD_ID,
+            name="Configure Hermes provider",
+            description=(
+                "Open Hermes' interactive model/provider setup in a terminal. "
+                "Use this when Hermes has not been configured on this machine yet."
+            ),
+            type="terminal",
+            args=["--setup"],
+        )
+    )
+    return methods

acp_adapter/edit_approval.py

@@ -0,0 +1,338 @@
+"""Pre-execution ACP edit approval helpers.
+
+This module is intentionally isolated from the generic tool registry.  ACP binds
+an edit approval requester in a ContextVar for the duration of one ACP agent run;
+CLI, gateway, and other sessions leave it unset and therefore bypass this guard.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+import re
+import tempfile
+from concurrent.futures import TimeoutError as FutureTimeout
+from contextvars import ContextVar, Token
+from dataclasses import dataclass
+from itertools import count
+from pathlib import Path
+from typing import Any, Callable
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class EditProposal:
+    """A proposed single-file edit that can be shown to an ACP client."""
+
+    tool_name: str
+    path: str
+    old_text: str | None
+    new_text: str
+    arguments: dict[str, Any]
+
+
+EditApprovalRequester = Callable[[EditProposal], bool]
+
+_EDIT_APPROVAL_REQUESTER: ContextVar[EditApprovalRequester | None] = ContextVar(
+    "ACP_EDIT_APPROVAL_REQUESTER",
+    default=None,
+)
+_PERMISSION_REQUEST_IDS = count(1)
+
+
+SENSITIVE_AUTO_APPROVE_NAMES = {".env", ".env.local", ".env.production", "id_rsa", "id_ed25519"}
+AUTO_APPROVE_ASK = "ask"
+AUTO_APPROVE_WORKSPACE = "workspace_session"
+AUTO_APPROVE_SESSION = "session"
+
+
+def set_edit_approval_requester(requester: EditApprovalRequester | None) -> Token:
+    """Bind an ACP edit approval requester for the current context."""
+
+    return _EDIT_APPROVAL_REQUESTER.set(requester)
+
+
+def reset_edit_approval_requester(token: Token) -> None:
+    """Restore a previous edit approval requester binding."""
+
+    _EDIT_APPROVAL_REQUESTER.reset(token)
+
+
+def clear_edit_approval_requester() -> None:
+    """Clear the current requester; primarily used by tests."""
+
+    _EDIT_APPROVAL_REQUESTER.set(None)
+
+
+def get_edit_approval_requester() -> EditApprovalRequester | None:
+    return _EDIT_APPROVAL_REQUESTER.get()
+
+
+def _read_text_if_exists(path: str) -> str | None:
+    p = Path(path).expanduser()
+    if not p.exists():
+        return None
+    if not p.is_file():
+        raise OSError(f"Cannot edit non-file path: {path}")
+    return p.read_text(encoding="utf-8", errors="replace")
+
+
+def _proposal_for_write_file(arguments: dict[str, Any]) -> EditProposal:
+    path = str(arguments.get("path") or "")
+    if not path:
+        raise ValueError("path required")
+    content = arguments.get("content")
+    if content is None:
+        raise ValueError("content required")
+    return EditProposal(
+        tool_name="write_file",
+        path=path,
+        old_text=_read_text_if_exists(path),
+        new_text=str(content),
+        arguments=dict(arguments),
+    )
+
+
+def _proposal_for_patch_replace(arguments: dict[str, Any]) -> EditProposal:
+    path = str(arguments.get("path") or "")
+    if not path:
+        raise ValueError("path required")
+    old_string = arguments.get("old_string")
+    new_string = arguments.get("new_string")
+    if old_string is None or new_string is None:
+        raise ValueError("old_string and new_string required")
+
+    old_text = _read_text_if_exists(path)
+    if old_text is None:
+        raise ValueError(f"Failed to read file: {path}")
+
+    from tools.fuzzy_match import fuzzy_find_and_replace
+
+    new_text, match_count, _strategy, error = fuzzy_find_and_replace(
+        old_text,
+        str(old_string),
+        str(new_string),
+        bool(arguments.get("replace_all", False)),
+    )
+    if error or match_count == 0:
+        raise ValueError(error or f"Could not find match for old_string in {path}")
+
+    return EditProposal(
+        tool_name="patch",
+        path=path,
+        old_text=old_text,
+        new_text=new_text,
+        arguments=dict(arguments),
+    )
+
+
+def _extract_v4a_patch_paths(patch_body: str) -> list[str]:
+    paths: list[str] = []
+    for match in re.finditer(
+        r'^\*\*\*\s+(?:Update|Add|Delete)\s+File:\s*(.+)$',
+        patch_body,
+        re.MULTILINE,
+    ):
+        path = match.group(1).strip()
+        if path:
+            paths.append(path)
+    for match in re.finditer(
+        r'^\*\*\*\s+Move\s+File:\s*(.+?)\s*->\s*(.+)$',
+        patch_body,
+        re.MULTILINE,
+    ):
+        src = match.group(1).strip()
+        dst = match.group(2).strip()
+        if src:
+            paths.append(src)
+        if dst:
+            paths.append(dst)
+    return paths
+
+
+def _proposal_for_patch_v4a(arguments: dict[str, Any]) -> EditProposal:
+    patch_body = arguments.get("patch")
+    if not isinstance(patch_body, str) or not patch_body:
+        raise ValueError("patch content required")
+
+    paths = _extract_v4a_patch_paths(patch_body)
+    if not paths:
+        raise ValueError("no file paths found in V4A patch")
+
+    proposal_path = paths[0] if len(paths) == 1 else ", ".join(paths)
+    old_text = _read_text_if_exists(paths[0]) if len(paths) == 1 else None
+    return EditProposal(
+        tool_name="patch",
+        path=proposal_path,
+        old_text=old_text,
+        # ACP only supports a single diff payload here.  Surface the exact V4A
+        # patch content before execution so patch-mode calls are permissioned
+        # and denied patches cannot mutate.
+        new_text=patch_body,
+        arguments=dict(arguments),
+    )
+
+
+def build_edit_proposal(tool_name: str, arguments: dict[str, Any]) -> EditProposal | None:
+    """Return an edit proposal for supported file mutation calls."""
+
+    if tool_name == "write_file":
+        return _proposal_for_write_file(arguments)
+    if tool_name == "patch":
+        mode = arguments.get("mode", "replace")
+        if mode == "replace":
+            return _proposal_for_patch_replace(arguments)
+        if mode == "patch":
+            return _proposal_for_patch_v4a(arguments)
+    return None
+
+
+def _is_sensitive_auto_approve_path(path: str) -> bool:
+    parts = Path(path).expanduser().parts
+    lowered = {part.lower() for part in parts}
+    if ".git" in lowered or ".ssh" in lowered:
+        return True
+    return Path(path).name.lower() in SENSITIVE_AUTO_APPROVE_NAMES
+
+
+def should_auto_approve_edit(proposal: EditProposal, policy: str, cwd: str | None = None) -> bool:
+    """Return whether an ACP edit proposal may bypass the prompt for this session.
+
+    This is intentionally session-scoped and conservative: sensitive paths still
+    ask even under autonomous policies.
+    """
+
+    policy = str(policy or AUTO_APPROVE_ASK).strip()
+    if policy == AUTO_APPROVE_ASK or _is_sensitive_auto_approve_path(proposal.path):
+        return False
+    path = Path(proposal.path).expanduser().resolve(strict=False)
+    if policy == AUTO_APPROVE_SESSION:
+        return True
+    if policy == AUTO_APPROVE_WORKSPACE:
+        # `/tmp` is the POSIX path but tempfile.gettempdir() is the real one on
+        # every platform: `/private/tmp` on macOS (because `/tmp` is a symlink
+        # and Path.resolve() follows it) and the per-user Temp dir on Windows.
+        tmp_root = Path(tempfile.gettempdir()).resolve(strict=False)
+        try:
+            path.relative_to(tmp_root)
+            return True
+        except ValueError:
+            pass
+        if cwd:
+            root = Path(cwd).expanduser().resolve(strict=False)
+            try:
+                path.relative_to(root)
+                return True
+            except ValueError:
+                return False
+    return False
+
+
+def maybe_require_edit_approval(tool_name: str, arguments: dict[str, Any]) -> str | None:
+    """Run ACP edit approval if bound.
+
+    Returns a JSON tool-error string when the edit must be blocked, otherwise
+    ``None`` so dispatch can continue.  Requester exceptions deny by default.
+    """
+
+    requester = get_edit_approval_requester()
+    if requester is None:
+        return None
+
+    try:
+        proposal = build_edit_proposal(tool_name, arguments)
+    except Exception as exc:
+        logger.warning("Could not build ACP edit approval proposal for %s: %s", tool_name, exc)
+        return json.dumps({"error": f"Edit approval denied: could not prepare diff ({exc})"}, ensure_ascii=False)
+
+    if proposal is None:
+        return None
+
+    try:
+        approved = bool(requester(proposal))
+    except Exception as exc:
+        logger.warning("ACP edit approval requester failed: %s", exc)
+        approved = False
+
+    if approved:
+        return None
+    return json.dumps({"error": "Edit approval denied by ACP client; file was not modified."}, ensure_ascii=False)
+
+
+def build_acp_edit_tool_call(proposal: EditProposal):
+    """Build the ToolCallUpdate payload for ACP request_permission."""
+
+    import acp
+
+    tool_call_id = f"edit-approval-{next(_PERMISSION_REQUEST_IDS)}"
+    return acp.update_tool_call(
+        tool_call_id,
+        title=f"Approve edit: {proposal.path}",
+        kind="edit",
+        status="pending",
+        content=[
+            acp.tool_diff_content(
+                path=proposal.path,
+                old_text=proposal.old_text,
+                new_text=proposal.new_text,
+            )
+        ],
+        raw_input={"tool": proposal.tool_name, "arguments": proposal.arguments},
+    )
+
+
+def make_acp_edit_approval_requester(
+    request_permission_fn: Callable,
+    loop: asyncio.AbstractEventLoop,
+    session_id: str,
+    timeout: float = 60.0,
+    auto_approve_getter: Callable[[], tuple[str, str | None]] | None = None,
+) -> EditApprovalRequester:
+    """Return a sync requester that bridges edit proposals to ACP permissions."""
+
+    def _requester(proposal: EditProposal) -> bool:
+        from acp.schema import PermissionOption
+        from agent.async_utils import safe_schedule_threadsafe
+
+        if auto_approve_getter is not None:
+            try:
+                policy, cwd = auto_approve_getter()
+                if should_auto_approve_edit(proposal, policy, cwd):
+                    logger.info("Auto-approved ACP edit under policy %s: %s", policy, proposal.path)
+                    return True
+            except Exception:
+                logger.debug("ACP edit auto-approval policy check failed", exc_info=True)
+
+        options = [
+            PermissionOption(option_id="allow_once", kind="allow_once", name="Allow edit"),
+            PermissionOption(option_id="deny", kind="reject_once", name="Deny"),
+        ]
+        tool_call = build_acp_edit_tool_call(proposal)
+        coro = request_permission_fn(
+            session_id=session_id,
+            tool_call=tool_call,
+            options=options,
+        )
+        future = safe_schedule_threadsafe(
+            coro,
+            loop,
+            logger=logger,
+            log_message="Edit approval request: failed to schedule on loop",
+        )
+        if future is None:
+            return False
+        try:
+            response = future.result(timeout=timeout)
+        except (FutureTimeout, Exception) as exc:
+            future.cancel()
+            logger.warning("Edit approval request timed out or failed: %s", exc)
+            return False
+        outcome = getattr(response, "outcome", None)
+        return (
+            getattr(outcome, "outcome", None) == "selected"
+            and getattr(outcome, "option_id", None) == "allow_once"
+        )
+
+    return _requester

acp_adapter/entry.py

@@ -0,0 +1,282 @@
+"""CLI entry point for the hermes-agent ACP adapter.
+
+Loads environment variables from ``~/.hermes/.env``, configures logging
+to write to stderr (so stdout is reserved for ACP JSON-RPC transport),
+and starts the ACP agent server.
+
+Usage::
+
+    python -m acp_adapter.entry
+    # or
+    hermes acp
+    # or
+    hermes-acp
+"""
+
+# IMPORTANT: hermes_bootstrap must be the very first import — UTF-8 stdio
+# on Windows.  No-op on POSIX.  See hermes_bootstrap.py for full rationale.
+try:
+    import hermes_bootstrap  # noqa: F401
+except ModuleNotFoundError:
+    # Graceful fallback when hermes_bootstrap isn't registered in the venv
+    # yet — happens during partial ``hermes update`` where git-reset landed
+    # new code but ``uv pip install -e .`` didn't finish.  Missing bootstrap
+    # means UTF-8 stdio setup is skipped on Windows; POSIX is unaffected.
+    pass
+else:
+    # Stop a ``utils/``/``proxy/``/``ui/`` package in the launch directory from
+    # shadowing Hermes's own modules — ``hermes acp`` can be started from any
+    # cwd, including a project that has same-named packages on its path.
+    hermes_bootstrap.harden_import_path()
+
+import argparse
+import asyncio
+import logging
+import os
+import sys
+from pathlib import Path
+from hermes_constants import get_hermes_home
+
+
+# Methods clients send as periodic liveness probes. They are not part of the
+# ACP schema, so the acp router correctly returns JSON-RPC -32601 to the
+# caller — but the supervisor task that dispatches the request then surfaces
+# the raised RequestError via ``logging.exception("Background task failed")``,
+# which dumps a traceback to stderr every probe interval. Clients like
+# acp-bridge already treat the -32601 response as "agent alive", so the
+# traceback is pure noise. We keep the protocol response intact and only
+# silence the stderr noise for this specific benign case.
+_BENIGN_PROBE_METHODS = frozenset({"ping", "health", "healthcheck"})
+
+
+class _BenignProbeMethodFilter(logging.Filter):
+    """Suppress acp 'Background task failed' tracebacks caused by unknown
+    liveness-probe methods (e.g. ``ping``) while leaving every other
+    background-task error — including method_not_found for any non-probe
+    method — visible in stderr.
+    """
+
+    def filter(self, record: logging.LogRecord) -> bool:
+        if record.getMessage() != "Background task failed":
+            return True
+        exc_info = record.exc_info
+        if not exc_info:
+            return True
+        exc = exc_info[1]
+        # Imported lazily so this module stays importable when the optional
+        # ``agent-client-protocol`` dependency is not installed.
+        try:
+            from acp.exceptions import RequestError
+        except ImportError:
+            return True
+        if not isinstance(exc, RequestError):
+            return True
+        if getattr(exc, "code", None) != -32601:
+            return True
+        data = getattr(exc, "data", None)
+        method = data.get("method") if isinstance(data, dict) else None
+        return method not in _BENIGN_PROBE_METHODS
+
+
+def _setup_logging() -> None:
+    """Route all logging to stderr so stdout stays clean for ACP stdio."""
+    from agent.redact import RedactingFormatter
+
+    handler = logging.StreamHandler(sys.stderr)
+    handler.setFormatter(
+        RedactingFormatter(
+            "%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+            datefmt="%Y-%m-%d %H:%M:%S",
+        )
+    )
+    handler.addFilter(_BenignProbeMethodFilter())
+    root = logging.getLogger()
+    root.handlers.clear()
+    root.addHandler(handler)
+    root.setLevel(logging.INFO)
+
+    # Quiet down noisy libraries
+    logging.getLogger("httpx").setLevel(logging.WARNING)
+    logging.getLogger("httpcore").setLevel(logging.WARNING)
+    logging.getLogger("openai").setLevel(logging.WARNING)
+
+
+def _load_env() -> None:
+    """Load .env from HERMES_HOME (default ``~/.hermes``)."""
+    from hermes_cli.env_loader import load_hermes_dotenv
+
+    hermes_home = get_hermes_home()
+    loaded = load_hermes_dotenv(hermes_home=hermes_home)
+    if loaded:
+        for env_file in loaded:
+            logging.getLogger(__name__).info("Loaded env from %s", env_file)
+    else:
+        logging.getLogger(__name__).info(
+            "No .env found at %s, using system env", hermes_home / ".env"
+        )
+
+
+def _parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        prog="hermes-acp",
+        description="Run Hermes Agent as an ACP stdio server.",
+    )
+    parser.add_argument("--version", action="store_true", help="Print Hermes version and exit")
+    parser.add_argument(
+        "--check",
+        action="store_true",
+        help="Verify ACP dependencies and adapter imports, then exit",
+    )
+    parser.add_argument(
+        "--setup",
+        action="store_true",
+        help="Run interactive Hermes provider/model setup for ACP terminal auth",
+    )
+    parser.add_argument(
+        "--setup-browser",
+        action="store_true",
+        help="Install agent-browser + Playwright Chromium into ~/.hermes/node/ "
+             "for browser tool support. Idempotent.",
+    )
+    parser.add_argument(
+        "--yes",
+        "-y",
+        action="store_true",
+        dest="assume_yes",
+        help="Accept all prompts (currently used by --setup-browser to skip the "
+             "~400 MB Chromium download confirmation).",
+    )
+    return parser.parse_args(argv)
+
+
+def _print_version() -> None:
+    from hermes_cli import __version__ as hermes_version
+
+    print(hermes_version)
+
+
+def _run_check() -> None:
+    import acp  # noqa: F401
+    from acp_adapter.server import HermesACPAgent  # noqa: F401
+
+    print("Hermes ACP check OK")
+
+
+def _run_setup() -> None:
+    from hermes_cli.main import main as hermes_main
+
+    old_argv = sys.argv[:]
+    try:
+        sys.argv = [old_argv[0] if old_argv else "hermes", "model"]
+        hermes_main()
+    finally:
+        sys.argv = old_argv
+
+    # Offer browser-tools install as a follow-up. The terminal auth method
+    # is the one supported first-run UX for registry installs, so this is
+    # the natural moment to ask. Skip silently if stdin isn't a TTY (the
+    # answer can't be collected anyway).
+    if not sys.stdin.isatty():
+        return
+    try:
+        reply = input(
+            "\nInstall browser tools? Downloads agent-browser (npm) and "
+            "optionally Playwright Chromium (~400 MB). [y/N] "
+        ).strip().lower()
+    except (EOFError, KeyboardInterrupt):
+        return
+    if reply in {"y", "yes"}:
+        _run_setup_browser(assume_yes=False)
+
+
+def _run_setup_browser(assume_yes: bool = False) -> int:
+    """Bootstrap agent-browser + Chromium.
+
+    Routes through dep_ensure -> install.{sh,ps1} --ensure, sharing code
+    with the runtime lazy installer.
+
+    Returns 0 on success, 1 on failure.
+    """
+    from hermes_cli.dep_ensure import ensure_dependency
+
+    try:
+        node_ok = ensure_dependency("node", interactive=not assume_yes)
+        if not node_ok:
+            print("Node.js installation failed — cannot proceed with browser tools.",
+                  file=sys.stderr)
+            return 1
+
+        browser_ok = ensure_dependency("browser", interactive=not assume_yes)
+        if not browser_ok:
+            print("Browser tools installation failed.", file=sys.stderr)
+            return 1
+
+        return 0
+    except OSError as exc:
+        print(f"Browser bootstrap failed: {exc}", file=sys.stderr)
+        return 1
+
+
+def main(argv: list[str] | None = None) -> None:
+    """Entry point: load env, configure logging, run the ACP agent."""
+    args = _parse_args(argv)
+    if args.version:
+        _print_version()
+        return
+    if args.check:
+        _run_check()
+        return
+    if args.setup:
+        _run_setup()
+        return
+    if args.setup_browser:
+        rc = _run_setup_browser(assume_yes=args.assume_yes)
+        if rc != 0:
+            sys.exit(rc)
+        return
+
+    _setup_logging()
+    _load_env()
+
+    logger = logging.getLogger(__name__)
+    logger.info("Starting hermes-agent ACP adapter")
+
+    # Ensure the project root is on sys.path so ``from run_agent import AIAgent`` works
+    project_root = str(Path(__file__).resolve().parent.parent)
+    if project_root not in sys.path:
+        sys.path.insert(0, project_root)
+
+    import acp
+    from .server import HermesACPAgent
+
+    # MCP tool discovery from config.yaml — fire-and-forget in a
+    # background daemon thread so the ACP server becomes responsive
+    # immediately while MCP servers connect.  Previously this blocked
+    # asyncio.run() for 2-5 s.  (ACP also registers per-session MCP
+    # servers dynamically via asyncio.to_thread inside the event loop;
+    # that path is unaffected.)  Moved from model_tools.py module scope
+    # to avoid freezing the gateway's loop on lazy import (#16856).
+    # Metadata-only hosts can opt out of unrelated global MCP startup.
+    if os.environ.get("HERMES_ACP_SKIP_CONFIGURED_MCP", "").strip() != "1":
+        try:
+            from hermes_cli.mcp_startup import start_background_mcp_discovery
+
+            start_background_mcp_discovery(
+                logger=logger,
+                thread_name="acp-mcp-discovery",
+            )
+        except Exception:
+            logger.debug("MCP tool discovery failed at ACP startup", exc_info=True)
+
+    agent = HermesACPAgent()
+    try:
+        asyncio.run(acp.run_agent(agent, use_unstable_protocol=True))
+    except KeyboardInterrupt:
+        logger.info("Shutting down (KeyboardInterrupt)")
+    except Exception:
+        logger.exception("ACP agent crashed")
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()

acp_adapter/events.py

@@ -0,0 +1,279 @@
+"""Callback factories for bridging AIAgent events to ACP notifications.
+
+Each factory returns a callable with the signature that AIAgent expects
+for its callbacks. Internally, the callbacks push ACP session updates
+to the client via ``conn.session_update()`` using
+``asyncio.run_coroutine_threadsafe()`` (since AIAgent runs in a worker
+thread while the event loop lives on the main thread).
+"""
+
+import asyncio
+import json
+import logging
+from collections import deque
+from typing import Any, Callable, Deque, Dict
+
+import acp
+from acp.schema import AgentPlanUpdate, PlanEntry
+
+from .tools import (
+    build_tool_complete,
+    build_tool_start,
+    make_tool_call_id,
+)
+
+logger = logging.getLogger(__name__)
+
+
+def _json_loads_maybe_prefix(value: str) -> Any:
+    """Parse a JSON object even when Hermes appended a human hint after it."""
+    text = value.strip()
+    try:
+        return json.loads(text)
+    except Exception:
+        decoder = json.JSONDecoder()
+        data, _ = decoder.raw_decode(text)
+        return data
+
+
+def _build_plan_update_from_todo_result(result: Any) -> AgentPlanUpdate | None:
+    """Translate Hermes' todo tool result into ACP's native plan update.
+
+    Zed renders ``sessionUpdate: plan`` as its first-class task/todo panel. The
+    Hermes agent already maintains task state through the ``todo`` tool, so the
+    ACP adapter should expose that state natively instead of only as a generic
+    tool-call transcript block.
+    """
+    if not isinstance(result, str) or not result.strip():
+        return None
+
+    try:
+        data = _json_loads_maybe_prefix(result)
+    except Exception:
+        return None
+
+    if not isinstance(data, dict) or not isinstance(data.get("todos"), list):
+        return None
+
+    todos = data["todos"]
+    if not todos:
+        return AgentPlanUpdate(session_update="plan", entries=[])
+
+    status_map = {
+        "pending": "pending",
+        "in_progress": "in_progress",
+        "completed": "completed",
+        # ACP plans only support pending/in_progress/completed. Preserve
+        # cancelled tasks as terminal entries instead of dropping them and
+        # making the client's full-list replacement lose visible context.
+        "cancelled": "completed",
+    }
+    entries: list[PlanEntry] = []
+    for item in todos:
+        if not isinstance(item, dict):
+            continue
+        content = str(item.get("content") or item.get("id") or "").strip()
+        if not content:
+            continue
+        raw_status = str(item.get("status") or "pending").strip()
+        status = status_map.get(raw_status, "pending")
+        if raw_status == "cancelled":
+            content = f"[cancelled] {content}"
+        entries.append(PlanEntry(content=content, priority="medium", status=status))
+
+    return AgentPlanUpdate(session_update="plan", entries=entries)
+
+
+def _send_update(
+    conn: acp.Client,
+    session_id: str,
+    loop: asyncio.AbstractEventLoop,
+    update: Any,
+) -> None:
+    """Fire-and-forget an ACP session update from a worker thread."""
+    from agent.async_utils import safe_schedule_threadsafe
+
+    future = safe_schedule_threadsafe(
+        conn.session_update(session_id, update),
+        loop,
+        logger=logger,
+        log_message="Failed to send ACP update",
+    )
+    if future is None:
+        return
+    try:
+        future.result(timeout=5)
+    except Exception:
+        logger.debug("Failed to send ACP update", exc_info=True)
+
+
+# ------------------------------------------------------------------
+# Tool progress callback
+# ------------------------------------------------------------------
+
+def make_tool_progress_cb(
+    conn: acp.Client,
+    session_id: str,
+    loop: asyncio.AbstractEventLoop,
+    tool_call_ids: Dict[str, Deque[str]],
+    tool_call_meta: Dict[str, Dict[str, Any]],
+    edit_approval_policy_getter: Callable[[], tuple[str, str | None]] | None = None,
+) -> Callable:
+    """Create a ``tool_progress_callback`` for AIAgent.
+
+    Signature expected by AIAgent::
+
+        tool_progress_callback(event_type: str, name: str, preview: str, args: dict, **kwargs)
+
+    Emits ``ToolCallStart`` for ``tool.started`` events and tracks IDs in a FIFO
+    queue per tool name so duplicate/parallel same-name calls still complete
+    against the correct ACP tool call.  Other event types (``tool.completed``,
+    ``reasoning.available``) are silently ignored.
+    """
+
+    def _tool_progress(event_type: str, name: str = None, preview: str = None, args: Any = None, **kwargs) -> None:
+        # Only emit ACP ToolCallStart for tool.started; ignore other event types
+        if event_type != "tool.started":
+            return
+        if isinstance(args, str):
+            try:
+                args = json.loads(args)
+            except (json.JSONDecodeError, TypeError):
+                args = {"raw": args}
+        if not isinstance(args, dict):
+            args = {}
+
+        tc_id = make_tool_call_id()
+        queue = tool_call_ids.get(name)
+        if queue is None:
+            queue = deque()
+            tool_call_ids[name] = queue
+        elif isinstance(queue, str):
+            queue = deque([queue])
+            tool_call_ids[name] = queue
+        queue.append(tc_id)
+
+        snapshot = None
+        if name in {"write_file", "patch", "skill_manage"}:
+            try:
+                from agent.display import capture_local_edit_snapshot
+
+                snapshot = capture_local_edit_snapshot(name, args)
+            except Exception:
+                logger.debug("Failed to capture ACP edit snapshot for %s", name, exc_info=True)
+        tool_call_meta[tc_id] = {"args": args, "snapshot": snapshot}
+
+        edit_diff = None
+        if name in {"write_file", "patch"} and edit_approval_policy_getter is not None:
+            try:
+                from acp_adapter.edit_approval import build_edit_proposal, should_auto_approve_edit
+
+                proposal = build_edit_proposal(name, args)
+                if proposal is not None:
+                    policy, cwd = edit_approval_policy_getter()
+                    if should_auto_approve_edit(proposal, policy, cwd):
+                        edit_diff = proposal
+            except Exception:
+                logger.debug("Failed to prepare auto-approved ACP edit diff for %s", name, exc_info=True)
+
+        update = build_tool_start(tc_id, name, args, edit_diff=edit_diff)
+        _send_update(conn, session_id, loop, update)
+
+    return _tool_progress
+
+
+# ------------------------------------------------------------------
+# Thinking callback
+# ------------------------------------------------------------------
+
+def make_thinking_cb(
+    conn: acp.Client,
+    session_id: str,
+    loop: asyncio.AbstractEventLoop,
+) -> Callable:
+    """Create a ``thinking_callback`` for AIAgent."""
+
+    def _thinking(text: str) -> None:
+        if not text:
+            return
+        update = acp.update_agent_thought_text(text)
+        _send_update(conn, session_id, loop, update)
+
+    return _thinking
+
+
+# ------------------------------------------------------------------
+# Step callback
+# ------------------------------------------------------------------
+
+def make_step_cb(
+    conn: acp.Client,
+    session_id: str,
+    loop: asyncio.AbstractEventLoop,
+    tool_call_ids: Dict[str, Deque[str]],
+    tool_call_meta: Dict[str, Dict[str, Any]],
+) -> Callable:
+    """Create a ``step_callback`` for AIAgent.
+
+    Signature expected by AIAgent::
+
+        step_callback(api_call_count: int, prev_tools: list)
+    """
+
+    def _step(api_call_count: int, prev_tools: Any = None) -> None:
+        if prev_tools and isinstance(prev_tools, list):
+            for tool_info in prev_tools:
+                tool_name = None
+                result = None
+                function_args = None
+
+                if isinstance(tool_info, dict):
+                    tool_name = tool_info.get("name") or tool_info.get("function_name")
+                    result = tool_info.get("result") or tool_info.get("output")
+                    function_args = tool_info.get("arguments") or tool_info.get("args")
+                elif isinstance(tool_info, str):
+                    tool_name = tool_info
+
+                queue = tool_call_ids.get(tool_name or "")
+                if isinstance(queue, str):
+                    queue = deque([queue])
+                    tool_call_ids[tool_name] = queue
+                if tool_name and queue:
+                    tc_id = queue.popleft()
+                    meta = tool_call_meta.pop(tc_id, {})
+                    update = build_tool_complete(
+                        tc_id,
+                        tool_name,
+                        result=str(result) if result is not None else None,
+                        function_args=function_args or meta.get("args"),
+                        snapshot=meta.get("snapshot"),
+                    )
+                    _send_update(conn, session_id, loop, update)
+                    if tool_name == "todo":
+                        plan_update = _build_plan_update_from_todo_result(result)
+                        if plan_update is not None:
+                            _send_update(conn, session_id, loop, plan_update)
+                    if not queue:
+                        tool_call_ids.pop(tool_name, None)
+
+    return _step
+
+
+# ------------------------------------------------------------------
+# Agent message callback
+# ------------------------------------------------------------------
+
+def make_message_cb(
+    conn: acp.Client,
+    session_id: str,
+    loop: asyncio.AbstractEventLoop,
+) -> Callable:
+    """Create a callback that streams agent response text to the editor."""
+
+    def _message(text: str) -> None:
+        if not text:
+            return
+        update = acp.update_agent_message_text(text)
+        _send_update(conn, session_id, loop, update)
+
+    return _message

acp_adapter/permissions.py

@@ -0,0 +1,190 @@
+"""ACP permission bridging for Hermes dangerous-command approvals."""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from concurrent.futures import TimeoutError as FutureTimeout
+from itertools import count
+from typing import Callable
+
+from acp.schema import (
+    AllowedOutcome,
+    PermissionOption,
+)
+
+logger = logging.getLogger(__name__)
+
+# Maps ACP permission option ids to Hermes approval result strings.
+# Option ids are stable across both the ``allow_permanent=True`` and
+# ``allow_permanent=False`` paths even though the option list differs.
+_OPTION_ID_TO_HERMES = {
+    "allow_once": "once",
+    "allow_session": "session",
+    "allow_always": "always",
+    "deny": "deny",
+    "deny_always": "deny",
+}
+
+_PERMISSION_REQUEST_IDS = count(1)
+
+
+def _permission_option_supports_kind(kind: str) -> bool:
+    """Return whether the installed ACP SDK accepts a permission option kind."""
+    try:
+        PermissionOption(option_id="__probe__", kind=kind, name="probe")
+    except Exception:
+        return False
+    return True
+
+
+def _build_permission_options(
+    *, allow_permanent: bool, allow_session: bool = True,
+    smart_denied: bool = False,
+) -> list[PermissionOption]:
+    """Return ACP options that match Hermes approval semantics."""
+    # A gate that re-asks every time (allow_session=False, e.g. protected
+    # agent-instruction writes) collapses to the same two options as a
+    # Smart DENY override — the editor must not offer a scope Hermes
+    # discards, or every subsequent write re-prompts (#81887).
+    once_only = smart_denied or not allow_session
+    options = [PermissionOption(
+        option_id="allow_once", kind="allow_once", name="Allow once",
+    )]
+    if not once_only:
+        options.append(PermissionOption(
+            option_id="allow_session",
+            # ACP has no session-scoped kind, so use the closest persistent
+            # hint while keeping Hermes semantics in the option id.
+            kind="allow_always",
+            name="Allow for session",
+        ))
+    if allow_permanent and not once_only:
+        options.append(
+            PermissionOption(
+                option_id="allow_always",
+                kind="allow_always",
+                name="Allow always",
+            ),
+        )
+    options.append(PermissionOption(option_id="deny", kind="reject_once", name="Deny"))
+    if not once_only and _permission_option_supports_kind("reject_always"):
+        options.append(
+            PermissionOption(
+                option_id="deny_always",
+                kind="reject_always",
+                name="Deny always",
+            ),
+        )
+    return options
+
+
+def _build_permission_tool_call(command: str, description: str):
+    """Return the ACP tool-call update attached to a permission request.
+
+    ``request_permission`` expects a ``ToolCallUpdate`` payload — produced
+    by ``_acp.update_tool_call`` — not a ``ToolCallStart``. Each request
+    gets a unique ``perm-check-N`` id so concurrent requests don't collide.
+    """
+    import acp as _acp
+
+    tool_call_id = f"perm-check-{next(_PERMISSION_REQUEST_IDS)}"
+    title = f"{description}: {command}" if description else command
+    content_text = f"{description}\n$ {command}" if description else f"$ {command}"
+    return _acp.update_tool_call(
+        tool_call_id,
+        title=title,
+        kind="execute",
+        status="pending",
+        content=[_acp.tool_content(_acp.text_block(content_text))],
+        raw_input={"command": command, "description": description},
+    )
+
+
+def _map_outcome_to_hermes(outcome: object, *, allowed_option_ids: set[str]) -> str:
+    """Map an ACP permission outcome into Hermes approval strings."""
+    if not isinstance(outcome, AllowedOutcome):
+        return "deny"
+
+    option_id = outcome.option_id
+    if option_id not in allowed_option_ids:
+        logger.warning("Permission request returned unknown option_id: %s", option_id)
+        return "deny"
+    return _OPTION_ID_TO_HERMES.get(option_id, "deny")
+
+
+def make_approval_callback(
+    request_permission_fn: Callable,
+    loop: asyncio.AbstractEventLoop,
+    session_id: str,
+    timeout: float = 60.0,
+) -> Callable[..., str]:
+    """
+    Return a Hermes-compatible approval callback that bridges to ACP.
+
+    The callback accepts ``command`` and ``description`` plus optional
+    keyword arguments such as ``allow_permanent`` used by
+    ``tools.approval.prompt_dangerous_approval()``.
+
+    Args:
+        request_permission_fn: The ACP connection's ``request_permission`` coroutine.
+        loop: The event loop on which the ACP connection lives.
+        session_id: Current ACP session id.
+        timeout: Seconds to wait for a response before auto-denying.
+    """
+
+    def _callback(
+        command: str,
+        description: str,
+        *,
+        allow_permanent: bool = True,
+        allow_session: bool = True,
+        smart_denied: bool = False,
+        **_: object,
+    ) -> str:
+        from agent.async_utils import safe_schedule_threadsafe
+
+        options = _build_permission_options(
+            allow_permanent=allow_permanent,
+            allow_session=allow_session,
+            smart_denied=smart_denied,
+        )
+
+        tool_call = _build_permission_tool_call(command, description)
+        coro = request_permission_fn(
+            session_id=session_id,
+            tool_call=tool_call,
+            options=options,
+        )
+        future = safe_schedule_threadsafe(
+            coro, loop,
+            logger=logger,
+            log_message="Permission request: failed to schedule on loop",
+        )
+        if future is None:
+            return "deny"
+
+        try:
+            response = future.result(timeout=timeout)
+        except FutureTimeout:
+            future.cancel()
+            logger.warning("Permission request timed out after %ss", timeout)
+            # Distinct from an explicit deny: the client never answered.
+            # tools.approval callers report this as "timed out without user
+            # response" instead of a user denial.
+            return "timeout"
+        except Exception as exc:
+            future.cancel()
+            logger.warning("Permission request failed: %s", exc)
+            return "deny"
+
+        if response is None:
+            return "deny"
+
+        allowed_option_ids = {option.option_id for option in options}
+        return _map_outcome_to_hermes(
+            response.outcome,
+            allowed_option_ids=allowed_option_ids,
+        )
+
+    return _callback

acp_adapter/provenance.py

@@ -0,0 +1,127 @@
+"""Derive ACP session-provenance metadata from the existing compression chain.
+
+This is an additive Hermes extension surfaced under ACP ``_meta.hermes`` so
+existing ACP clients ignore it. It carries no new persisted state: everything
+is derived on demand from the ``sessions`` table (``parent_session_id`` /
+``end_reason``), which already models compression-continuation chains.
+
+The ACP/editor ``session_id`` stays the stable public handle. When context
+compression rotates the internal Hermes head, ``build_session_provenance`` lets
+a client see the previous/current internal ids and the lineage root without
+parsing status text, guessing from token drops, or reading ``state.db``.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, Optional
+
+# Bound defensive walks; compression chains this deep are pathological.
+_MAX_WALK = 100
+
+
+def build_session_provenance(
+    db: Any,
+    acp_session_id: str,
+    current_hermes_session_id: str,
+    *,
+    previous_hermes_session_id: Optional[str] = None,
+) -> Optional[Dict[str, Any]]:
+    """Build ``_meta.hermes.sessionProvenance`` for an ACP session.
+
+    Args:
+        db: A ``SessionDB`` (must expose ``get_session``).
+        acp_session_id: The stable ACP/editor-facing session handle.
+        current_hermes_session_id: The live internal Hermes DB session id
+            (``state.agent.session_id``).
+        previous_hermes_session_id: The internal id from before the most recent
+            turn, when known. Supplied by ``prompt()`` to flag a rotation.
+
+    Returns:
+        A dict suitable for ``{"hermes": {"sessionProvenance": <dict>}}`` under
+        ACP ``_meta``, or ``None`` if the session can't be read.
+    """
+    try:
+        row = db.get_session(current_hermes_session_id)
+    except Exception:
+        return None
+    if not row:
+        return None
+
+    parent_id = row.get("parent_session_id")
+    end_reason = row.get("end_reason")
+
+    # Walk parents to the lineage root and count compression depth. Only
+    # compression-split parents (parent.end_reason == 'compression') count
+    # toward depth — delegate/branch children share the parent_session_id
+    # column but are not compaction boundaries.
+    root_id = current_hermes_session_id
+    compression_depth = 0
+    cursor_parent = parent_id
+    seen = {current_hermes_session_id}
+    for _ in range(_MAX_WALK):
+        if not cursor_parent or cursor_parent in seen:
+            break
+        seen.add(cursor_parent)
+        try:
+            prow = db.get_session(cursor_parent)
+        except Exception:
+            prow = None
+        if not prow:
+            break
+        root_id = cursor_parent
+        if prow.get("end_reason") == "compression":
+            compression_depth += 1
+        cursor_parent = prow.get("parent_session_id")
+
+    # A session is a compression continuation when its parent was ended with
+    # end_reason='compression'. Determine that from the immediate parent.
+    is_continuation = False
+    if parent_id:
+        try:
+            immediate_parent = db.get_session(parent_id)
+        except Exception:
+            immediate_parent = None
+        if immediate_parent and immediate_parent.get("end_reason") == "compression":
+            is_continuation = True
+
+    rotated = bool(
+        previous_hermes_session_id
+        and previous_hermes_session_id != current_hermes_session_id
+    )
+
+    provenance: Dict[str, Any] = {
+        "acpSessionId": acp_session_id,
+        "currentHermesSessionId": current_hermes_session_id,
+        "rootHermesSessionId": root_id,
+        "parentHermesSessionId": parent_id,
+        "sessionKind": "continuation" if is_continuation else "root",
+        "compressionDepth": compression_depth,
+    }
+    if previous_hermes_session_id:
+        provenance["previousHermesSessionId"] = previous_hermes_session_id
+    if rotated:
+        # The head moved during the last turn. The only mechanism that rotates
+        # the internal id mid-turn is compression-driven session splitting.
+        provenance["reason"] = "compression"
+        provenance["creatorKind"] = "compression"
+
+    return provenance
+
+
+def session_provenance_meta(
+    db: Any,
+    acp_session_id: str,
+    current_hermes_session_id: str,
+    *,
+    previous_hermes_session_id: Optional[str] = None,
+) -> Optional[Dict[str, Any]]:
+    """Return a ready ``_meta`` payload: ``{"hermes": {"sessionProvenance": ...}}``."""
+    prov = build_session_provenance(
+        db,
+        acp_session_id,
+        current_hermes_session_id,
+        previous_hermes_session_id=previous_hermes_session_id,
+    )
+    if prov is None:
+        return None
+    return {"hermes": {"sessionProvenance": prov}}

acp_adapter/session.py

@@ -0,0 +1,695 @@
+"""ACP session manager — maps ACP sessions to Hermes AIAgent instances.
+
+Sessions are persisted to the shared SessionDB (``~/.hermes/state.db``) so they
+survive process restarts and appear in ``session_search``.  When the editor
+reconnects after idle/restart, the ``load_session`` / ``resume_session`` calls
+find the persisted session in the database and restore the full conversation
+history.
+"""
+from __future__ import annotations
+
+from hermes_constants import get_hermes_home
+
+import copy
+import json
+import logging
+import os
+import re
+import sys
+import time
+import uuid
+from datetime import datetime, timezone
+from dataclasses import dataclass, field
+from threading import Lock
+from typing import Any, Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+
+def _translate_acp_cwd(cwd: str) -> str:
+    """Translate Windows ACP cwd values when Hermes itself is running in WSL.
+
+    Windows ACP clients can launch ``hermes acp`` inside WSL while still sending
+    editor workspaces as Windows drive paths (``E:\\Projects``) or
+    ``\\\\wsl.localhost\\`` UNC paths. Store and execute against the POSIX form so
+    agents, tools, and persisted ACP sessions all agree on the usable workspace.
+    Native Linux/macOS keeps the original cwd unchanged.
+    """
+    from hermes_constants import translate_cwd_for_wsl_backend
+
+    return translate_cwd_for_wsl_backend(str(cwd))
+
+
+def _normalize_cwd_for_compare(cwd: str | None) -> str:
+    raw = str(cwd or ".").strip()
+    if not raw:
+        raw = "."
+    expanded = os.path.expanduser(raw)
+
+    # Normalize Windows drive paths into the equivalent WSL mount form so
+    # ACP history filters match the same workspace across Windows and WSL.
+    from hermes_constants import windows_path_to_wsl
+
+    translated = windows_path_to_wsl(expanded)
+    if translated is not None:
+        expanded = translated
+    elif re.match(r"^/mnt/[A-Za-z]/", expanded):
+        expanded = f"/mnt/{expanded[5].lower()}/{expanded[7:]}"
+
+    # Resolve symlink aliases so equivalent spellings of the same directory
+    # compare equal — macOS reports editor workspaces as ``/var/...`` while
+    # sessions get stored under ``/private/var/...`` (and ``/tmp`` vs
+    # ``/private/tmp``), which made ACP history filters silently drop a
+    # workspace's own sessions. ``os.path.realpath`` is lexical for missing
+    # paths (strict=False), so cwds that don't exist on this host — e.g.
+    # WSL-translated Windows drives — keep the previous normpath behavior.
+    # Ported from PrimeIntellect-ai/prime-agent#628.
+    try:
+        return os.path.realpath(expanded)
+    except OSError:
+        return os.path.normpath(expanded)
+
+
+def _build_session_title(title: Any, preview: Any, cwd: str | None) -> str:
+    explicit = str(title or "").strip()
+    if explicit:
+        return explicit
+    preview_text = str(preview or "").strip()
+    if preview_text:
+        return preview_text
+    leaf = os.path.basename(str(cwd or "").rstrip("/\\"))
+    return leaf or "New thread"
+
+
+def _format_updated_at(value: Any) -> str | None:
+    if value is None:
+        return None
+    if isinstance(value, str) and value.strip():
+        return value
+    try:
+        return datetime.fromtimestamp(float(value), tz=timezone.utc).isoformat()
+    except Exception:
+        return None
+
+
+def _updated_at_sort_key(value: Any) -> float:
+    if value is None:
+        return float("-inf")
+    if isinstance(value, (int, float)):
+        return float(value)
+    raw = str(value).strip()
+    if not raw:
+        return float("-inf")
+    try:
+        return datetime.fromisoformat(raw.replace("Z", "+00:00")).timestamp()
+    except Exception:
+        try:
+            return float(raw)
+        except Exception:
+            return float("-inf")
+
+
+def _acp_stderr_print(*args, **kwargs) -> None:
+    """Best-effort human-readable output sink for ACP stdio sessions.
+
+    ACP reserves stdout for JSON-RPC frames, so any incidental CLI/status output
+    from AIAgent must be redirected away from stdout. Route it to stderr instead.
+    """
+    kwargs = dict(kwargs)
+    kwargs.setdefault("file", sys.stderr)
+    print(*args, **kwargs)
+
+
+def _register_task_cwd(task_id: str, cwd: str) -> None:
+    """Bind a task/session id to the editor's working directory for tools.
+
+    Zed can launch Hermes from a Windows workspace while the ACP process runs
+    inside WSL. In that case ACP sends cwd as e.g. ``E:\\Projects\\POTI``;
+    local tools need the WSL mount equivalent or subprocess creation fails
+    before the command can run.
+    """
+    if not task_id:
+        return
+    try:
+        from tools.terminal_tool import register_task_env_overrides
+        register_task_env_overrides(task_id, {"cwd": _translate_acp_cwd(cwd)})
+    except Exception:
+        logger.debug("Failed to register ACP task cwd override", exc_info=True)
+
+
+def _expand_acp_enabled_toolsets(
+    toolsets: List[str] | None = None,
+    mcp_server_names: List[str] | None = None,
+) -> List[str]:
+    """Return ACP toolsets plus explicit MCP server toolsets for this session."""
+    expanded: List[str] = []
+    for name in list(toolsets or ["hermes-acp"]):
+        if name and name not in expanded:
+            expanded.append(name)
+
+    for server_name in list(mcp_server_names or []):
+        toolset_name = f"mcp-{server_name}"
+        if server_name and toolset_name not in expanded:
+            expanded.append(toolset_name)
+
+    return expanded
+
+
+def _clear_task_cwd(task_id: str) -> None:
+    """Remove task-specific cwd overrides for an ACP session."""
+    if not task_id:
+        return
+    try:
+        from tools.terminal_tool import clear_task_env_overrides
+        clear_task_env_overrides(task_id)
+    except Exception:
+        logger.debug("Failed to clear ACP task cwd override", exc_info=True)
+
+
+@dataclass
+class SessionState:
+    """Tracks per-session state for an ACP-managed Hermes agent."""
+
+    session_id: str
+    agent: Any  # AIAgent instance
+    cwd: str = "."
+    model: str = ""
+    history: List[Dict[str, Any]] = field(default_factory=list)
+    cancel_event: Any = None  # threading.Event
+    is_running: bool = False
+    queued_prompts: List[str] = field(default_factory=list)
+    runtime_lock: Any = field(default_factory=Lock)
+    current_prompt_text: str = ""
+    interrupted_prompt_text: str = ""
+
+
+class SessionManager:
+    """Thread-safe manager for ACP sessions backed by Hermes AIAgent instances.
+
+    Sessions are held in-memory for fast access **and** persisted to the
+    shared SessionDB so they survive process restarts and are searchable
+    via ``session_search``.
+    """
+
+    def __init__(self, agent_factory=None, db=None):
+        """
+        Args:
+            agent_factory: Optional callable that creates an AIAgent-like object.
+                           Used by tests. When omitted, a real AIAgent is created
+                           using the current Hermes runtime provider configuration.
+            db:            Optional SessionDB instance. When omitted, the default
+                           SessionDB (``~/.hermes/state.db``) is lazily created.
+        """
+        self._sessions: Dict[str, SessionState] = {}
+        self._lock = Lock()
+        self._agent_factory = agent_factory
+        self._db_instance = db  # None → lazy-init on first use
+
+    # ---- public API ---------------------------------------------------------
+
+    def create_session(self, cwd: str = ".") -> SessionState:
+        """Create a new session with a unique ID and a fresh AIAgent."""
+        import threading
+
+        cwd = _translate_acp_cwd(cwd)
+        session_id = str(uuid.uuid4())
+        agent = self._make_agent(session_id=session_id, cwd=cwd)
+        state = SessionState(
+            session_id=session_id,
+            agent=agent,
+            cwd=cwd,
+            model=getattr(agent, "model", "") or "",
+            cancel_event=threading.Event(),
+        )
+        with self._lock:
+            self._sessions[session_id] = state
+        _register_task_cwd(session_id, cwd)
+        self._persist(state)
+        logger.info("Created ACP session %s (cwd=%s)", session_id, cwd)
+        return state
+
+    def get_session(self, session_id: str) -> Optional[SessionState]:
+        """Return the session for *session_id*, or ``None``.
+
+        If the session is not in memory but exists in the database (e.g. after
+        a process restart), it is transparently restored.
+        """
+        with self._lock:
+            state = self._sessions.get(session_id)
+        if state is not None:
+            return state
+        # Attempt to restore from database.
+        return self._restore(session_id)
+
+    def remove_session(self, session_id: str) -> bool:
+        """Remove a session from memory and database. Returns True if it existed."""
+        with self._lock:
+            existed = self._sessions.pop(session_id, None) is not None
+        db_existed = self._delete_persisted(session_id)
+        if existed or db_existed:
+            _clear_task_cwd(session_id)
+        return existed or db_existed
+
+    def fork_session(self, session_id: str, cwd: str = ".") -> Optional[SessionState]:
+        """Deep-copy a session's history into a new session."""
+        import threading
+
+        cwd = _translate_acp_cwd(cwd)
+        original = self.get_session(session_id)  # checks DB too
+        if original is None:
+            return None
+
+        new_id = str(uuid.uuid4())
+        agent = self._make_agent(
+            session_id=new_id,
+            cwd=cwd,
+            model=original.model or None,
+        )
+        state = SessionState(
+            session_id=new_id,
+            agent=agent,
+            cwd=cwd,
+            model=getattr(agent, "model", original.model) or original.model,
+            history=copy.deepcopy(original.history),
+            cancel_event=threading.Event(),
+        )
+        with self._lock:
+            self._sessions[new_id] = state
+        _register_task_cwd(new_id, cwd)
+        self._persist(state)
+        logger.info("Forked ACP session %s -> %s", session_id, new_id)
+        return state
+
+    def list_sessions(self, cwd: str | None = None) -> List[Dict[str, Any]]:
+        """Return lightweight info dicts for all sessions (memory + database)."""
+        normalized_cwd = _normalize_cwd_for_compare(cwd) if cwd else None
+        db = self._get_db()
+        persisted_rows: dict[str, dict[str, Any]] = {}
+
+        if db is not None:
+            try:
+                for row in db.list_sessions_rich(source="acp", limit=1000):
+                    persisted_rows[str(row["id"])] = dict(row)
+            except Exception:
+                logger.debug("Failed to load ACP sessions from DB", exc_info=True)
+
+        # Collect in-memory sessions first.
+        with self._lock:
+            seen_ids = set(self._sessions.keys())
+            results = []
+            for s in self._sessions.values():
+                history_len = len(s.history)
+                if history_len <= 0:
+                    continue
+                if normalized_cwd and _normalize_cwd_for_compare(s.cwd) != normalized_cwd:
+                    continue
+                persisted = persisted_rows.get(s.session_id, {})
+                preview = next(
+                    (
+                        str(msg.get("content") or "").strip()
+                        for msg in s.history
+                        if msg.get("role") == "user" and str(msg.get("content") or "").strip()
+                    ),
+                    persisted.get("preview") or "",
+                )
+                results.append(
+                    {
+                        "session_id": s.session_id,
+                        "cwd": s.cwd,
+                        "model": s.model,
+                        "history_len": history_len,
+                        "title": _build_session_title(persisted.get("title"), preview, s.cwd),
+                        "updated_at": _format_updated_at(
+                            persisted.get("last_active") or persisted.get("started_at") or time.time()
+                        ),
+                    }
+                )
+
+        # Merge any persisted sessions not currently in memory.
+        for sid, row in persisted_rows.items():
+            if sid in seen_ids:
+                continue
+            message_count = int(row.get("message_count") or 0)
+            if message_count <= 0:
+                continue
+            # Extract cwd from model_config JSON.
+            session_cwd = "."
+            mc = row.get("model_config")
+            if mc:
+                try:
+                    session_cwd = json.loads(mc).get("cwd", ".")
+                except (json.JSONDecodeError, TypeError):
+                    pass
+            if normalized_cwd and _normalize_cwd_for_compare(session_cwd) != normalized_cwd:
+                continue
+            results.append({
+                "session_id": sid,
+                "cwd": session_cwd,
+                "model": row.get("model") or "",
+                "history_len": message_count,
+                "title": _build_session_title(row.get("title"), row.get("preview"), session_cwd),
+                "updated_at": _format_updated_at(row.get("last_active") or row.get("started_at")),
+            })
+
+        results.sort(key=lambda item: _updated_at_sort_key(item.get("updated_at")), reverse=True)
+        return results
+
+    def update_cwd(self, session_id: str, cwd: str) -> Optional[SessionState]:
+        """Update the working directory for a session and its tool overrides."""
+        cwd = _translate_acp_cwd(cwd)
+        state = self.get_session(session_id)  # checks DB too
+        if state is None:
+            return None
+        state.cwd = cwd
+        _register_task_cwd(session_id, cwd)
+        self._persist(state)
+        return state
+
+    def cleanup(self) -> None:
+        """Remove all sessions (memory and database) and clear task-specific cwd overrides."""
+        with self._lock:
+            session_ids = list(self._sessions.keys())
+            self._sessions.clear()
+        for session_id in session_ids:
+            _clear_task_cwd(session_id)
+            self._delete_persisted(session_id)
+        # Also remove any DB-only ACP sessions not currently in memory.
+        db = self._get_db()
+        if db is not None:
+            try:
+                rows = db.search_sessions(source="acp", limit=10000)
+                for row in rows:
+                    sid = row["id"]
+                    _clear_task_cwd(sid)
+                    db.delete_session(sid)
+            except Exception:
+                logger.debug("Failed to cleanup ACP sessions from DB", exc_info=True)
+
+    def save_session(self, session_id: str) -> None:
+        """Persist the current state of a session to the database.
+
+        Called by the server after prompt completion, slash commands that
+        mutate history, and model switches.
+        """
+        with self._lock:
+            state = self._sessions.get(session_id)
+        if state is not None:
+            self._persist(state)
+
+    # ---- persistence via SessionDB ------------------------------------------
+
+    def _get_db(self):
+        """Lazily initialise and return the SessionDB instance.
+
+        Returns ``None`` if the DB is unavailable (e.g. import error in a
+        minimal test environment).
+
+        Note: we resolve ``HERMES_HOME`` dynamically rather than relying on
+        the module-level ``DEFAULT_DB_PATH`` constant, because that constant
+        is evaluated at import time and won't reflect env-var changes made
+        later (e.g. by the test fixture ``_isolate_hermes_home``).
+        """
+        if self._db_instance is not None:
+            return self._db_instance
+        try:
+            from hermes_state import SessionDB
+            hermes_home = get_hermes_home()
+            self._db_instance = SessionDB(db_path=hermes_home / "state.db")
+            return self._db_instance
+        except Exception:
+            logger.debug("SessionDB unavailable for ACP persistence", exc_info=True)
+            return None
+
+    def _persist(self, state: SessionState) -> None:
+        """Write session state to the database.
+
+        Creates the session record if it doesn't exist, then replaces all
+        stored messages with the current in-memory history.
+        """
+        db = self._get_db()
+        if db is None:
+            return
+
+        # Ensure model is a plain string (not a MagicMock or other proxy).
+        model_str = str(state.model) if state.model else None
+        session_meta = {"cwd": state.cwd}
+        provider = getattr(state.agent, "provider", None)
+        base_url = getattr(state.agent, "base_url", None)
+        api_mode = getattr(state.agent, "api_mode", None)
+        if isinstance(provider, str) and provider.strip():
+            session_meta["provider"] = provider.strip()
+        if isinstance(base_url, str) and base_url.strip():
+            session_meta["base_url"] = base_url.strip()
+        if isinstance(api_mode, str) and api_mode.strip():
+            session_meta["api_mode"] = api_mode.strip()
+        cwd_json = json.dumps(session_meta)
+
+        try:
+            # Ensure the session record exists.
+            existing = db.get_session(state.session_id)
+            if existing is None:
+                db.create_session(
+                    session_id=state.session_id,
+                    source="acp",
+                    model=model_str,
+                    model_config={"cwd": state.cwd},
+                )
+            else:
+                # Update model_config (contains cwd) if changed.
+                try:
+                    db.update_session_meta(state.session_id, cwd_json, model_str)
+                except Exception:
+                    logger.debug("Failed to update ACP session metadata", exc_info=True)
+
+            # When the agent owns persistence to this same SessionDB it has
+            # already flushed the live transcript incrementally during
+            # run_conversation (append_message), and it preserves pre-compaction
+            # turns non-destructively via archive_and_compact() — keeping them on
+            # disk as searchable active=0/compacted=1 rows. Calling
+            # replace_messages() here would then be a redundant double-write that
+            # DELETEs exactly those archived rows (and, after a compression-driven
+            # id rotation where agent.session_id no longer equals
+            # state.session_id, clobbers the ended parent transcript) — silent
+            # data loss for any ACP conversation long enough to compress.
+            #
+            # Only fall back to the destructive atomic replace when the agent is
+            # NOT persisting itself to this DB (e.g. a test agent factory, or a
+            # fresh create/fork whose copied history the agent has not flushed
+            # yet). That path still rolls back on a mid-rewrite failure so the
+            # previously persisted conversation survives (salvaged from #13675).
+            agent = state.agent
+            agent_db = getattr(agent, "_session_db", None)
+            agent_owns_persistence = (
+                agent_db is not None
+                and agent_db is db
+                and bool(getattr(agent, "_session_db_created", False))
+            )
+            if not agent_owns_persistence:
+                # Even when the current agent doesn't "own" persistence, the
+                # session on disk may already carry compaction-archived rows —
+                # e.g. after a model switch or a /restore, both of which mint a
+                # fresh agent with _session_db_created=False (so the check above
+                # is False) yet leave the durable archived transcript in place.
+                # A full-history replace would DELETE those archived rows just
+                # like the owned-agent case. Guard against it by replacing ONLY
+                # the live (active=1) set unconditionally: on a fresh
+                # create/fork every row is active=1, so active-only replace is
+                # behaviorally identical to the full replace — and when archived
+                # rows DO exist they survive. An existence probe here
+                # (has_archived_messages) would fail OPEN into the destructive
+                # replace on any DB error and can race a concurrent
+                # archive_and_compact — the same probe failure mode #80216's
+                # /retry fix (gateway/slash_commands.py) deliberately avoids.
+                db.replace_messages(
+                    state.session_id, state.history, active_only=True
+                )
+        except Exception:
+            logger.warning("Failed to persist ACP session %s", state.session_id, exc_info=True)
+
+    def _restore(self, session_id: str) -> Optional[SessionState]:
+        """Load a session from the database into memory, recreating the AIAgent."""
+        import threading
+
+        db = self._get_db()
+        if db is None:
+            return None
+
+        try:
+            row = db.get_session(session_id)
+        except Exception:
+            logger.debug("Failed to query DB for ACP session %s", session_id, exc_info=True)
+            return None
+
+        if row is None:
+            return None
+
+        # Only restore ACP sessions.
+        if row.get("source") != "acp":
+            return None
+
+        # Extract cwd from model_config.
+        cwd = "."
+        requested_provider = row.get("billing_provider")
+        restored_base_url = row.get("billing_base_url")
+        restored_api_mode = None
+        mc = row.get("model_config")
+        if mc:
+            try:
+                meta = json.loads(mc)
+                if isinstance(meta, dict):
+                    cwd = meta.get("cwd", ".")
+                    requested_provider = meta.get("provider") or requested_provider
+                    restored_base_url = meta.get("base_url") or restored_base_url
+                    restored_api_mode = meta.get("api_mode") or restored_api_mode
+            except (json.JSONDecodeError, TypeError):
+                pass
+
+        model = row.get("model") or None
+
+        # Load conversation history. repair_alternation: this restore feeds
+        # LIVE REPLAY — the loaded list becomes the resumed agent's working
+        # conversation. A durable ``user;user`` violation left in state.db would
+        # otherwise re-fire the pre-request defensive repair on every request
+        # for the rest of the session (see hermes_state.get_messages_as_conversation).
+        try:
+            history = db.get_messages_as_conversation(
+                session_id, repair_alternation=True
+            )
+        except Exception:
+            logger.warning("Failed to load messages for ACP session %s", session_id, exc_info=True)
+            history = []
+
+        try:
+            agent = self._make_agent(
+                session_id=session_id,
+                cwd=cwd,
+                model=model,
+                requested_provider=requested_provider,
+                base_url=restored_base_url,
+                api_mode=restored_api_mode,
+            )
+        except Exception:
+            logger.warning("Failed to recreate agent for ACP session %s", session_id, exc_info=True)
+            return None
+
+        state = SessionState(
+            session_id=session_id,
+            agent=agent,
+            cwd=cwd,
+            model=model or getattr(agent, "model", "") or "",
+            history=history,
+            cancel_event=threading.Event(),
+        )
+        with self._lock:
+            self._sessions[session_id] = state
+        _register_task_cwd(session_id, cwd)
+        logger.info("Restored ACP session %s from DB (%d messages)", session_id, len(history))
+        return state
+
+    def _delete_persisted(self, session_id: str) -> bool:
+        """Delete a session from the database. Returns True if it existed."""
+        db = self._get_db()
+        if db is None:
+            return False
+        try:
+            return db.delete_session(session_id)
+        except Exception:
+            logger.debug("Failed to delete ACP session %s from DB", session_id, exc_info=True)
+            return False
+
+    # ---- internal -----------------------------------------------------------
+
+    def _make_agent(
+        self,
+        *,
+        session_id: str,
+        cwd: str,
+        model: str | None = None,
+        requested_provider: str | None = None,
+        base_url: str | None = None,
+        api_mode: str | None = None,
+    ):
+        if self._agent_factory is not None:
+            return self._agent_factory()
+
+        from run_agent import AIAgent
+        from hermes_cli.config import load_config
+        from hermes_cli.runtime_provider import resolve_runtime_provider
+
+        config = load_config()
+        model_cfg = config.get("model")
+        default_model = ""
+        config_provider = None
+        if isinstance(model_cfg, dict):
+            default_model = str(model_cfg.get("default") or default_model)
+            config_provider = model_cfg.get("provider")
+        elif isinstance(model_cfg, str) and model_cfg.strip():
+            default_model = model_cfg.strip()
+
+        configured_mcp_servers = [
+            name
+            for name, cfg in (config.get("mcp_servers") or {}).items()
+            if not isinstance(cfg, dict) or cfg.get("enabled", True) is not False
+        ]
+
+        kwargs = {
+            "platform": "acp",
+            "enabled_toolsets": _expand_acp_enabled_toolsets(
+                ["hermes-acp"],
+                mcp_server_names=configured_mcp_servers,
+            ),
+            "quiet_mode": True,
+            "session_id": session_id,
+            "session_db": self._get_db(),
+            "model": model or default_model,
+        }
+
+        try:
+            runtime = resolve_runtime_provider(requested=requested_provider or config_provider)
+            kwargs.update(
+                {
+                    "provider": runtime.get("provider"),
+                    "api_mode": api_mode or runtime.get("api_mode"),
+                    "base_url": base_url or runtime.get("base_url"),
+                    "api_key": runtime.get("api_key"),
+                    "command": runtime.get("command"),
+                    "args": list(runtime.get("args") or []),
+                }
+            )
+        except Exception:
+            logger.debug("ACP session falling back to default provider resolution", exc_info=True)
+
+        _register_task_cwd(session_id, cwd)
+
+        # Bounded wait for background MCP discovery so already-spawning fast
+        # servers land in the agent's tool snapshot.  ACP entry.py fires
+        # discovery in a background daemon thread (start_background_mcp_discovery);
+        # the agent snapshots tools once at build (run_agent/agent_init) and
+        # never re-reads the registry, so without this join a reachable-but-
+        # slow configured server would be invisible for the whole session.
+        # ``ensure_mcp_discovery_before_agent_build`` also (re)starts discovery
+        # when the entry.py spawn never ran or exited with zero connected
+        # servers (the retry-after-zero-connected allowance), making this
+        # construction site self-sufficient.  Bounded by
+        # ``mcp_discovery_timeout`` (config.yaml, default ~1.5s) so a dead
+        # server can't block — servers that miss the bound are picked up by
+        # the automatic late-refresh (see HermesACPAgent._schedule_mcp_late_refresh).
+        try:
+            from hermes_cli.mcp_startup import ensure_mcp_discovery_before_agent_build
+
+            ensure_mcp_discovery_before_agent_build(
+                logger=logger,
+                thread_name="acp-mcp-discovery",
+            )
+        except Exception:
+            logger.debug("ACP: bounded MCP discovery wait failed", exc_info=True)
+
+        agent = AIAgent(**kwargs)
+        # Codex app-server sessions are spawned lazily on the first turn. Stamp
+        # the ACP workspace onto the agent so the Codex runtime starts from the
+        # editor/session cwd instead of the Hermes daemon's process cwd.
+        agent.session_cwd = cwd
+        # ACP stdio transport requires stdout to remain protocol-only JSON-RPC.
+        # Route any incidental human-readable agent output to stderr instead.
+        agent._print_fn = _acp_stderr_print
+        return agent

agent/__init__.py

@@ -0,0 +1,8 @@
+"""Agent internals -- extracted modules from run_agent.py.
+
+These modules contain pure utility functions and self-contained classes
+that were previously embedded in the 3,600-line run_agent.py. Extracting
+them makes run_agent.py focused on the AIAgent orchestrator class.
+"""
+
+from . import jiter_preload as _jiter_preload  # noqa: F401

agent/account_usage.py

@@ -0,0 +1,902 @@
+from __future__ import annotations
+
+import logging
+import math
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING, Any, Optional
+
+import httpx
+
+from agent.anthropic_adapter import _is_oauth_token, resolve_anthropic_token
+from hermes_cli.auth import AuthError, _read_codex_tokens, resolve_codex_runtime_credentials
+from hermes_cli.runtime_provider import resolve_runtime_provider
+
+if TYPE_CHECKING:
+    from typing import TypeGuard
+
+logger = logging.getLogger(__name__)
+
+
+def _utc_now() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+@dataclass(frozen=True)
+class AccountUsageWindow:
+    label: str
+    used_percent: Optional[float] = None
+    reset_at: Optional[datetime] = None
+    detail: Optional[str] = None
+
+
+@dataclass(frozen=True)
+class AccountUsageSnapshot:
+    provider: str
+    source: str
+    fetched_at: datetime
+    title: str = "Account limits"
+    plan: Optional[str] = None
+    windows: tuple[AccountUsageWindow, ...] = ()
+    details: tuple[str, ...] = ()
+    unavailable_reason: Optional[str] = None
+
+    @property
+    def available(self) -> bool:
+        return bool(self.windows or self.details) and not self.unavailable_reason
+
+
+def _title_case_slug(value: Optional[str]) -> Optional[str]:
+    cleaned = str(value or "").strip()
+    if not cleaned:
+        return None
+    return cleaned.replace("_", " ").replace("-", " ").title()
+
+
+def _parse_dt(value: Any) -> Optional[datetime]:
+    if value in {None, ""}:
+        return None
+    if isinstance(value, (int, float)):
+        return datetime.fromtimestamp(float(value), tz=timezone.utc)
+    if isinstance(value, str):
+        text = value.strip()
+        if not text:
+            return None
+        if text.endswith("Z"):
+            text = text[:-1] + "+00:00"
+        try:
+            dt = datetime.fromisoformat(text)
+            return dt if dt.tzinfo else dt.replace(tzinfo=timezone.utc)
+        except ValueError:
+            return None
+    return None
+
+
+def _format_reset(dt: Optional[datetime]) -> str:
+    if not dt:
+        return "unknown"
+    local_dt = dt.astimezone()
+    delta = dt - _utc_now()
+    total_seconds = int(delta.total_seconds())
+    if total_seconds <= 0:
+        return f"now ({local_dt.strftime('%Y-%m-%d %H:%M %Z')})"
+    hours, rem = divmod(total_seconds, 3600)
+    minutes = rem // 60
+    if hours >= 24:
+        days, hours = divmod(hours, 24)
+        rel = f"in {days}d {hours}h"
+    elif hours > 0:
+        rel = f"in {hours}h {minutes}m"
+    else:
+        rel = f"in {minutes}m"
+    return f"{rel} ({local_dt.strftime('%Y-%m-%d %H:%M %Z')})"
+
+
+def render_account_usage_lines(snapshot: Optional[AccountUsageSnapshot], *, markdown: bool = False) -> list[str]:
+    if not snapshot:
+        return []
+    header = f"📈 {'**' if markdown else ''}{snapshot.title}{'**' if markdown else ''}"
+    lines = [header]
+    if snapshot.plan:
+        lines.append(f"Provider: {snapshot.provider} ({snapshot.plan})")
+    else:
+        lines.append(f"Provider: {snapshot.provider}")
+    for window in snapshot.windows:
+        if window.used_percent is None:
+            base = f"{window.label}: unavailable"
+        else:
+            remaining = max(0, round(100 - float(window.used_percent)))
+            used = max(0, round(float(window.used_percent)))
+            base = f"{window.label}: {remaining}% remaining ({used}% used)"
+        if window.reset_at:
+            base += f" • resets {_format_reset(window.reset_at)}"
+        elif window.detail:
+            base += f" • {window.detail}"
+        lines.append(base)
+    for detail in snapshot.details:
+        lines.append(detail)
+    if snapshot.unavailable_reason:
+        lines.append(f"Unavailable: {snapshot.unavailable_reason}")
+    return lines
+
+
+def _fmt_usd(d: float) -> str:
+    return f"${d:,.2f}"
+
+
+def _is_finite_num(v: Any) -> TypeGuard[float]:
+    """True iff v is a real numeric value (int or float, not bool, not NaN/Inf).
+
+    Typed as a ``TypeGuard[float]`` so the type checker narrows ``v`` to a real
+    number in the positive branch — callers can then do arithmetic / pass it to
+    ``_fmt_usd`` without a None-operand warning.
+    """
+    return isinstance(v, (int, float)) and not isinstance(v, bool) and math.isfinite(v)
+
+
+def build_nous_credits_snapshot(account_info) -> Optional[AccountUsageSnapshot]:
+    """Map a NousPortalAccountInfo into an AccountUsageSnapshot for /usage.
+
+    Shows dollar magnitudes (subscription / top-up / total) + renewal date + a
+    portal CTA. When the portal supplies a subscription denominator
+    (``monthly_credits``), also emits a subscription-usage window so the renderer
+    shows a real ``% used`` gauge; when it's absent (older portals) the view
+    gracefully degrades to magnitudes-only. Returns None when there's no usable
+    account info to show (fail-open: caller just shows nothing).
+    """
+    try:
+        from hermes_cli.nous_account import nous_portal_topup_url
+
+        if account_info is None or not getattr(account_info, "logged_in", False):
+            return None
+
+        access = getattr(account_info, "paid_service_access_info", None)
+        sub = getattr(account_info, "subscription", None)
+
+        windows: list[AccountUsageWindow] = []
+        details: list[str] = []
+
+        # Subscription usage gauge — only when the portal supplies a positive
+        # monthly_credits denominator AND a finite remaining balance that does
+        # not exceed the cap. Money math is on float dollars (allowed: numeric
+        # account fields, NOT a server-provided *_usd string). used = cap -
+        # remaining; clamp [0,100] so a debt balance (remaining < 0) reads 100%.
+        # Excluded on purpose:
+        #   - non-finite values (NaN/Infinity slip past isinstance and json.loads
+        #     parses bare NaN/Infinity by default) → would render "$nan"/"$inf"
+        #     and a falsely-confident gauge;
+        #   - remaining > cap (rollover balance spanning the period) → monthly_credits
+        #     is no longer a meaningful denominator, and "$X of $Y left" with X>Y
+        #     reads as a contradiction. Both fall back to the magnitudes lines.
+        if sub is not None:
+            monthly_credits = getattr(sub, "monthly_credits", None)
+            sub_remaining = getattr(sub, "credits_remaining", None)
+            if (
+                _is_finite_num(monthly_credits)
+                and monthly_credits > 0
+                and _is_finite_num(sub_remaining)
+                and sub_remaining <= monthly_credits
+            ):
+                used = monthly_credits - sub_remaining
+                used_pct = max(0.0, min(100.0, used / monthly_credits * 100.0))
+                windows.append(
+                    AccountUsageWindow(
+                        label="Subscription",
+                        used_percent=used_pct,
+                        detail=f"{_fmt_usd(sub_remaining)} of {_fmt_usd(monthly_credits)} left",
+                    )
+                )
+
+        if access is not None:
+            sub_credits = getattr(access, "subscription_credits_remaining", None)
+            if _is_finite_num(sub_credits):
+                details.append(f"Subscription credits: {_fmt_usd(sub_credits)}")
+            purchased = getattr(access, "purchased_credits_remaining", None)
+            if _is_finite_num(purchased):
+                details.append(f"Top-up credits: {_fmt_usd(purchased)}")
+            total_usable = getattr(access, "total_usable_credits", None)
+            if _is_finite_num(total_usable):
+                details.append(f"Total usable: {_fmt_usd(total_usable)}")
+
+        if sub is not None:
+            rollover = getattr(sub, "rollover_credits", None)
+            if _is_finite_num(rollover) and rollover > 0:
+                details.append(f"Rollover: {_fmt_usd(rollover)}")
+            period_end = getattr(sub, "current_period_end", None)
+            if period_end:
+                details.append(f"Renews: {period_end}")
+
+        paid = getattr(account_info, "paid_service_access", None)
+        if paid is False:
+            details.append("Status: access depleted — top up to restore")
+
+        if not windows and not details:
+            return None
+
+        details.append(f"Top up: {nous_portal_topup_url(account_info)}")
+        details.append("(or run /topup)")
+
+        plan = getattr(sub, "plan", None) if sub is not None else None
+        return AccountUsageSnapshot(
+            provider="nous",
+            source="portal-account",
+            fetched_at=_utc_now(),
+            title="Nous credits",
+            plan=plan,
+            windows=tuple(windows),
+            details=tuple(details),
+        )
+    except (AttributeError, TypeError):
+        return None
+
+
+def nous_credits_lines(*, markdown: bool = False, timeout: float = 10.0) -> list[str]:
+    """Return rendered Nous-credits /usage lines, or [] when there's nothing to show.
+
+    Account-independent of any live agent: gated on "a Nous account is logged in"
+    (a cheap local auth-state check), then a wall-clock-bounded portal fetch. Shared
+    by the CLI ``_show_usage`` and the TUI ``session.usage`` RPC so both surfaces show
+    the same block regardless of session API-call count or resume state. Fail-open:
+    any auth/portal hiccup or timeout returns [] (the caller shows nothing).
+
+    Dev override: when HERMES_DEV_CREDITS_FIXTURE selects a fixture state, /usage
+    renders from that fixture instead of the real portal (so the block + gauge are
+    testable without a live account). Throwaway scaffolding.
+    """
+    # Dev fixture short-circuit — render /usage from the injected state, no portal.
+    try:
+        from agent.credits_tracker import dev_fixture_credits_state
+
+        fixture = dev_fixture_credits_state()
+    except Exception:
+        fixture = None
+    if fixture is not None:
+        snapshot = _snapshot_from_credits_state(fixture)
+        return render_account_usage_lines(snapshot, markdown=markdown)
+
+    try:
+        from hermes_cli.auth import get_provider_auth_state
+
+        tok = (get_provider_auth_state("nous") or {}).get("access_token")
+        if not (isinstance(tok, str) and tok.strip()):
+            return []
+    except Exception:
+        return []
+    try:
+        import concurrent.futures
+
+        from hermes_cli.nous_account import get_nous_portal_account_info
+
+        with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
+            account = pool.submit(
+                get_nous_portal_account_info, force_fresh=True
+            ).result(timeout=timeout)
+        snapshot = build_nous_credits_snapshot(account)
+        return render_account_usage_lines(snapshot, markdown=markdown)
+    except Exception:
+        # Fail-open (caller shows nothing), but leave a breadcrumb so a dead
+        # /usage credits block is diagnosable in agent.log without a dev flag.
+        logger.debug("credits ▸ /usage portal fetch/render failed (fail-open)", exc_info=True)
+        return []
+
+
+def _snapshot_from_credits_state(state) -> Optional[AccountUsageSnapshot]:
+    """Map a header-shaped CreditsState (e.g. a dev fixture) to the /usage snapshot.
+
+    Renders the same magnitudes + monthly-grant % window the portal path produces,
+    so HERMES_DEV_CREDITS_FIXTURE can exercise /usage without a live account. The
+    *_usd strings are mock display values here (not server balance to compute on);
+    the % comes from CreditsState.used_fraction (micros math). Fail-open → None.
+    """
+    try:
+        if state is None:
+            return None
+
+        windows: list[AccountUsageWindow] = []
+        details: list[str] = []
+
+        uf = getattr(state, "used_fraction", None)
+        if isinstance(uf, (int, float)) and math.isfinite(uf):
+            cap_usd = getattr(state, "subscription_limit_usd", None)
+            sub_usd = getattr(state, "subscription_usd", None)
+            detail = None
+            if sub_usd and cap_usd:
+                detail = f"${sub_usd} of ${cap_usd} left"
+            windows.append(
+                AccountUsageWindow(
+                    label="Subscription",
+                    used_percent=max(0.0, min(100.0, uf * 100.0)),
+                    detail=detail,
+                )
+            )
+
+        sub_usd = getattr(state, "subscription_usd", None)
+        if sub_usd:
+            details.append(f"Subscription credits: ${sub_usd}")
+        purchased_usd = getattr(state, "purchased_usd", None)
+        if purchased_usd:
+            details.append(f"Top-up credits: ${purchased_usd}")
+        remaining_usd = getattr(state, "remaining_usd", None)
+        if remaining_usd:
+            details.append(f"Total usable: ${remaining_usd}")
+        if getattr(state, "paid_access", True) is False:
+            details.append("Status: access depleted — top up to restore")
+
+        if not windows and not details:
+            return None
+
+        details.append("(dev fixture — HERMES_DEV_CREDITS_FIXTURE)")
+        return AccountUsageSnapshot(
+            provider="nous",
+            source="dev-fixture",
+            fetched_at=_utc_now(),
+            title="Nous credits",
+            windows=tuple(windows),
+            details=tuple(details),
+        )
+    except (AttributeError, TypeError):
+        return None
+
+
+@dataclass(frozen=True)
+class CreditsView:
+    """Surface-agnostic data for the ``/topup`` balance view.
+
+    One portal fetch, one parse — consumed identically by the CLI panel, the
+    gateway button, and any other money surface. Fail-open: when not logged in
+    or the portal is unreachable, ``logged_in`` is False / ``topup_url`` is None
+    and callers degrade gracefully.
+    """
+
+    logged_in: bool
+    balance_lines: tuple[str, ...] = ()
+    identity_line: Optional[str] = None
+    topup_url: Optional[str] = None
+    depleted: bool = False
+
+
+def build_credits_view(*, markdown: bool = False, timeout: float = 10.0) -> CreditsView:
+    """Build the /topup balance view: balance block + identity line + top-up URL.
+
+    Reuses the same account fetch + snapshot + URL builder as the /usage credits
+    block, so the numbers always match. The balance block is the rendered
+    snapshot MINUS its trailing top-up/command-hint lines (the /topup surface
+    supplies its own affordance). Fail-open → ``CreditsView(logged_in=False)``.
+    """
+    not_logged_in = CreditsView(logged_in=False)
+    try:
+        from hermes_cli.auth import get_provider_auth_state
+
+        tok = (get_provider_auth_state("nous") or {}).get("access_token")
+        if not (isinstance(tok, str) and tok.strip()):
+            return not_logged_in
+    except Exception:
+        return not_logged_in
+
+    try:
+        import concurrent.futures
+
+        from hermes_cli.nous_account import (
+            get_nous_portal_account_info,
+            nous_portal_topup_url,
+        )
+
+        with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
+            account = pool.submit(get_nous_portal_account_info, force_fresh=True).result(
+                timeout=timeout
+            )
+    except Exception:
+        logger.debug("credits ▸ /topup portal fetch failed (fail-open)", exc_info=True)
+        return not_logged_in
+
+    if account is None or not getattr(account, "logged_in", False):
+        return not_logged_in
+
+    snapshot = build_nous_credits_snapshot(account)
+    # Balance lines = the snapshot block minus the two trailing affordance lines
+    # ("Top up: <url>" + "(or run /topup)") that build_nous_credits_snapshot
+    # appends for the /usage surface. /topup renders its own button/panel.
+    balance_lines: list[str] = []
+    if snapshot is not None:
+        rendered = render_account_usage_lines(snapshot, markdown=markdown)
+        balance_lines = [
+            line
+            for line in rendered
+            if not line.lstrip().startswith("Top up:")
+            and not line.lstrip().startswith("(or run")
+        ]
+
+    # Identity line — shown before any open (roadmap §4.4).
+    email = getattr(account, "email", None)
+    org_name = getattr(account, "org_name", None)
+    who: list[str] = []
+    if email:
+        who.append(str(email))
+    if org_name:
+        who.append(f"org {org_name}")
+    identity_line = ("Topping up as " + " / ".join(who)) if who else None
+
+    return CreditsView(
+        logged_in=True,
+        balance_lines=tuple(balance_lines),
+        identity_line=identity_line,
+        topup_url=nous_portal_topup_url(account),
+        depleted=getattr(account, "paid_service_access", None) is False,
+    )
+
+
+def _codex_backend_urls(base_url: str) -> tuple[str, str, str]:
+    """Resolve the Codex backend endpoints (usage, reset-credits list, consume).
+
+    Mirrors the Codex CLI's PathStyle split (codex-rs backend-client): base URLs
+    containing ``/backend-api`` use the ChatGPT ``/wham/...`` paths; everything
+    else uses ``/api/codex/...``.
+    """
+    normalized = (base_url or "").strip().rstrip("/")
+    if not normalized:
+        normalized = "https://chatgpt.com/backend-api/codex"
+    if normalized.endswith("/codex"):
+        normalized = normalized[: -len("/codex")]
+    prefix = normalized + ("/wham" if "/backend-api" in normalized else "/api/codex")
+    return (
+        prefix + "/usage",
+        prefix + "/rate-limit-reset-credits",
+        prefix + "/rate-limit-reset-credits/consume",
+    )
+
+
+def _resolve_codex_usage_url(base_url: str) -> str:
+    return _codex_backend_urls(base_url)[0]
+
+
+def _resolve_codex_usage_credentials(
+    base_url: Optional[str],
+    api_key: Optional[str],
+) -> tuple[str, str, Optional[str]]:
+    """Resolve Codex quota credentials from the native runtime path.
+
+    Prefer explicit live-agent credentials, then the legacy singleton OAuth
+    state, then the credential pool.  Hermes's native OAuth setup now stores
+    device-code logins in the pool, so quota diagnostics must not depend only
+    on the older singleton store.
+    """
+    explicit_key = str(api_key or "").strip()
+    if explicit_key:
+        return explicit_key, str(base_url or "").strip(), None
+
+    # Tier 2: the native runtime resolver. It ALREADY falls back to the
+    # credential pool when the singleton is empty (see
+    # ``resolve_codex_runtime_credentials`` — issue #32992), so in a pool-only
+    # setup this returns a usable ``source="credential_pool"`` token.
+    #
+    # Only ``AuthError`` ("no creds" / rate-limited) is caught so tier 3 can
+    # run: a broad ``except Exception`` would (a) mask a transient refresh /
+    # network failure and silently hand back a DIFFERENT pool account's usage,
+    # and (b) hide genuine programming errors. A refresh/network error must
+    # propagate — the outer ``fetch_account_usage`` guard fails open (shows
+    # nothing this turn) rather than reporting the wrong account.
+    #
+    # The ``account_id`` (for the ``ChatGPT-Account-Id`` header) is read
+    # best-effort: a partial/missing singleton token store must not sink an
+    # otherwise-usable resolver credential and force a header-less pool fallback.
+    try:
+        creds = resolve_codex_runtime_credentials(refresh_if_expiring=True)
+        account_id: Optional[str] = None
+        try:
+            token_data = _read_codex_tokens()
+            tokens = token_data.get("tokens") or {}
+            account_id = str(tokens.get("account_id", "") or "").strip() or None
+        except AuthError:
+            # Pool-only creds carry no singleton account_id; header is optional.
+            logger.debug("codex ▸ /usage account_id read failed (best-effort)", exc_info=True)
+        return creds["api_key"], str(creds.get("base_url", "") or "").strip(), account_id
+    except AuthError:
+        logger.debug("codex ▸ /usage runtime resolver returned no creds; trying pool", exc_info=True)
+
+    # Tier 3: direct pool select. Reached only when the resolver itself raises
+    # AuthError (e.g. singleton missing AND its own pool read found nothing at
+    # resolve time, but a pool entry is usable now). Pool credentials have no
+    # account_id concept, so the ChatGPT-Account-Id header is intentionally
+    # omitted here.
+    from agent.credential_pool import load_pool
+
+    pool = load_pool("openai-codex")
+    entry = pool.select()
+    if entry is None:
+        raise RuntimeError("No available openai-codex credential in credential pool")
+    return entry.runtime_api_key, str(entry.runtime_base_url or base_url or "").strip(), None
+
+
+def _fetch_codex_account_usage(
+    base_url: Optional[str] = None,
+    api_key: Optional[str] = None,
+) -> Optional[AccountUsageSnapshot]:
+    token, resolved_base_url, account_id = _resolve_codex_usage_credentials(base_url, api_key)
+    headers = {
+        "Authorization": f"Bearer {token}",
+        "Accept": "application/json",
+        "User-Agent": "codex-cli",
+    }
+    if account_id:
+        headers["ChatGPT-Account-Id"] = account_id
+    with httpx.Client(timeout=15.0) as client:
+        response = client.get(_resolve_codex_usage_url(resolved_base_url), headers=headers)
+        response.raise_for_status()
+    payload = response.json() or {}
+    rate_limit = payload.get("rate_limit") or {}
+    windows: list[AccountUsageWindow] = []
+    for key, label in (("primary_window", "Session"), ("secondary_window", "Weekly")):
+        window = rate_limit.get(key) or {}
+        used = window.get("used_percent")
+        if used is None:
+            continue
+        windows.append(
+            AccountUsageWindow(
+                label=label,
+                used_percent=float(used),
+                reset_at=_parse_dt(window.get("reset_at")),
+            )
+        )
+    details: list[str] = []
+    reset_credits = payload.get("rate_limit_reset_credits") or {}
+    banked = reset_credits.get("available_count")
+    if isinstance(banked, (int, float)) and int(banked) > 0:
+        count = int(banked)
+        plural = "s" if count != 1 else ""
+        details.append(
+            f"You have {count} reset{plural} banked - use /usage reset to activate"
+        )
+    credits = payload.get("credits") or {}
+    if credits.get("has_credits"):
+        balance = credits.get("balance")
+        if isinstance(balance, (int, float)):
+            details.append(f"Credits balance: ${float(balance):.2f}")
+        elif credits.get("unlimited"):
+            details.append("Credits balance: unlimited")
+    return AccountUsageSnapshot(
+        provider="openai-codex",
+        source="usage_api",
+        fetched_at=_utc_now(),
+        plan=_title_case_slug(payload.get("plan_type")),
+        windows=tuple(windows),
+        details=tuple(details),
+    )
+
+
+@dataclass(frozen=True)
+class CodexResetRedeemResult:
+    """Outcome of a `/usage reset` attempt against the Codex backend."""
+
+    status: str  # reset | nothing_to_reset | no_credit | already_redeemed |
+    #              not_exhausted | no_credits_banked | unavailable
+    message: str
+    available_count: int = 0
+    windows_reset: int = 0
+
+    @property
+    def redeemed(self) -> bool:
+        return self.status == "reset"
+
+
+# Client-side guard threshold: a rate-limit window only counts as exhausted
+# when it is fully used. Below this, redeeming a banked reset wastes most of
+# its value, so we block and point at --force instead.
+_CODEX_WINDOW_EXHAUSTED_PERCENT = 100.0
+
+
+def redeem_codex_reset_credit(
+    *,
+    base_url: Optional[str] = None,
+    api_key: Optional[str] = None,
+    force: bool = False,
+) -> CodexResetRedeemResult:
+    """Redeem one banked Codex rate-limit reset credit (`/usage reset`).
+
+    Flow (mirrors the Codex CLI's reset-credits picker, codex-rs
+    ``backend-client``):
+
+    1. ``GET .../usage`` — read the current windows + banked credit count.
+    2. Guard: zero banked credits → refuse. No window fully used and not
+       ``force`` → refuse with a warning (a banked reset restores the WHOLE
+       5h + weekly allowance; burning it early wastes it). The backend has
+       the same protection (``nothing_to_reset`` doesn't consume the
+       credit), but failing fast client-side gives a clearer message.
+    3. ``POST .../rate-limit-reset-credits/consume`` with a fresh UUID
+       idempotency key (``redeem_request_id``). No ``credit_id`` — the
+       backend picks the next available credit, exactly like the CLI's
+       default "Full reset" option.
+
+    Never raises: every failure mode returns a ``CodexResetRedeemResult``
+    with a user-renderable message.
+    """
+    import uuid
+
+    try:
+        token, resolved_base_url, account_id = _resolve_codex_usage_credentials(base_url, api_key)
+    except Exception:
+        return CodexResetRedeemResult(
+            status="unavailable",
+            message="No Codex credentials available. Run `hermes auth` to sign in with your ChatGPT account.",
+        )
+    usage_url, _credits_url, consume_url = _codex_backend_urls(resolved_base_url)
+    headers = {
+        "Authorization": f"Bearer {token}",
+        "Accept": "application/json",
+        "User-Agent": "codex-cli",
+    }
+    if account_id:
+        headers["ChatGPT-Account-Id"] = account_id
+
+    try:
+        with httpx.Client(timeout=15.0) as client:
+            usage_resp = client.get(usage_url, headers=headers)
+            usage_resp.raise_for_status()
+            payload = usage_resp.json() or {}
+
+            reset_credits = payload.get("rate_limit_reset_credits") or {}
+            raw_count = reset_credits.get("available_count")
+            available = int(raw_count) if isinstance(raw_count, (int, float)) else 0
+            if available <= 0:
+                return CodexResetRedeemResult(
+                    status="no_credits_banked",
+                    message="No banked reset credits on this account — nothing to redeem.",
+                )
+
+            rate_limit = payload.get("rate_limit") or {}
+            worst_used: Optional[float] = None
+            for key in ("primary_window", "secondary_window"):
+                used = (rate_limit.get(key) or {}).get("used_percent")
+                if isinstance(used, (int, float)):
+                    worst_used = max(worst_used or 0.0, float(used))
+            exhausted = worst_used is not None and worst_used >= _CODEX_WINDOW_EXHAUSTED_PERCENT
+            if not exhausted and not force:
+                usage_note = (
+                    f"your busiest window is only {worst_used:.0f}% used"
+                    if worst_used is not None
+                    else "your current usage could not be confirmed as exhausted"
+                )
+                plural = "s" if available != 1 else ""
+                return CodexResetRedeemResult(
+                    status="not_exhausted",
+                    message=(
+                        f"⚠️ Not redeeming: {usage_note}. A banked reset restores your FULL "
+                        f"5h + weekly limits, so spending it now would waste most of it. "
+                        f"You have {available} reset{plural} banked. "
+                        f"Use `/usage reset --force` to redeem anyway."
+                    ),
+                    available_count=available,
+                )
+
+            consume_resp = client.post(
+                consume_url,
+                headers={**headers, "Content-Type": "application/json"},
+                json={"redeem_request_id": str(uuid.uuid4())},
+            )
+            consume_resp.raise_for_status()
+            body = consume_resp.json() or {}
+    except httpx.HTTPStatusError as exc:
+        code = exc.response.status_code
+        if code in (401, 403):
+            return CodexResetRedeemResult(
+                status="unavailable",
+                message=(
+                    "Codex backend rejected the request (HTTP "
+                    f"{code}). Reset credits require ChatGPT-account (OAuth) auth — "
+                    "run `hermes auth` and sign in with your ChatGPT account."
+                ),
+            )
+        return CodexResetRedeemResult(
+            status="unavailable",
+            message=f"Codex backend error (HTTP {code}) — try again shortly.",
+        )
+    except Exception as exc:
+        return CodexResetRedeemResult(
+            status="unavailable",
+            message=f"Could not reach the Codex backend: {exc}",
+        )
+
+    code = str(body.get("code", "") or "").strip().lower()
+    windows_reset = body.get("windows_reset")
+    windows_reset = int(windows_reset) if isinstance(windows_reset, (int, float)) else 0
+    remaining = max(0, available - 1)
+    plural = "s" if remaining != 1 else ""
+    if code == "reset":
+        # The redeemed reset restores the account's quota upstream — lift any
+        # persisted pool cooldowns so Hermes doesn't keep the credential
+        # frozen behind the now-stale ``last_error_reset_at`` (issue #43747).
+        try:
+            from hermes_cli.auth import clear_codex_pool_quota_cooldowns
+
+            clear_codex_pool_quota_cooldowns()
+        except Exception:
+            logger.debug(
+                "Failed to clear Codex pool cooldowns after reset redemption",
+                exc_info=True,
+            )
+        return CodexResetRedeemResult(
+            status="reset",
+            message=(
+                f"✅ Reset redeemed — your usage limits have been reset. "
+                f"{remaining} banked reset{plural} remaining."
+            ),
+            available_count=remaining,
+            windows_reset=windows_reset,
+        )
+    if code == "nothing_to_reset":
+        return CodexResetRedeemResult(
+            status="nothing_to_reset",
+            message=(
+                "Backend reports nothing to reset — your limits aren't exhausted. "
+                "The credit was NOT spent."
+            ),
+            available_count=available,
+        )
+    if code == "no_credit":
+        return CodexResetRedeemResult(
+            status="no_credit",
+            message="Backend reports no available reset credit on this account.",
+        )
+    if code == "already_redeemed":
+        return CodexResetRedeemResult(
+            status="already_redeemed",
+            message="This redemption was already processed — no additional credit was spent.",
+            available_count=remaining,
+        )
+    return CodexResetRedeemResult(
+        status="unavailable",
+        message=f"Unexpected response from the Codex backend: {body!r}",
+    )
+
+
+def _fetch_anthropic_account_usage() -> Optional[AccountUsageSnapshot]:
+    token = (resolve_anthropic_token() or "").strip()
+    if not token:
+        return None
+    if not _is_oauth_token(token):
+        return AccountUsageSnapshot(
+            provider="anthropic",
+            source="oauth_usage_api",
+            fetched_at=_utc_now(),
+            unavailable_reason="Anthropic account limits are only available for OAuth-backed Claude accounts.",
+        )
+    headers = {
+        "Authorization": f"Bearer {token}",
+        "Accept": "application/json",
+        "Content-Type": "application/json",
+        "anthropic-beta": "oauth-2025-04-20",
+        "User-Agent": "claude-code/2.1.0",
+    }
+    with httpx.Client(timeout=15.0) as client:
+        response = client.get("https://api.anthropic.com/api/oauth/usage", headers=headers)
+        response.raise_for_status()
+    payload = response.json() or {}
+    windows: list[AccountUsageWindow] = []
+    mapping = (
+        ("five_hour", "Current session"),
+        ("seven_day", "Current week"),
+        ("seven_day_opus", "Opus week"),
+        ("seven_day_sonnet", "Sonnet week"),
+    )
+    for key, label in mapping:
+        window = payload.get(key) or {}
+        util = window.get("utilization")
+        if util is None:
+            continue
+        used = float(util) * 100 if float(util) <= 1 else float(util)
+        windows.append(
+            AccountUsageWindow(
+                label=label,
+                used_percent=used,
+                reset_at=_parse_dt(window.get("resets_at")),
+            )
+        )
+    details: list[str] = []
+    extra = payload.get("extra_usage") or {}
+    if extra.get("is_enabled"):
+        used_credits = extra.get("used_credits")
+        monthly_limit = extra.get("monthly_limit")
+        currency = extra.get("currency") or "USD"
+        if isinstance(used_credits, (int, float)) and isinstance(monthly_limit, (int, float)):
+            details.append(
+                f"Extra usage: {used_credits:.2f} / {monthly_limit:.2f} {currency}"
+            )
+    return AccountUsageSnapshot(
+        provider="anthropic",
+        source="oauth_usage_api",
+        fetched_at=_utc_now(),
+        windows=tuple(windows),
+        details=tuple(details),
+    )
+
+
+def _fetch_openrouter_account_usage(base_url: Optional[str], api_key: Optional[str]) -> Optional[AccountUsageSnapshot]:
+    runtime = resolve_runtime_provider(
+        requested="openrouter",
+        explicit_base_url=base_url,
+        explicit_api_key=api_key,
+    )
+    token = str(runtime.get("api_key", "") or "").strip()
+    if not token:
+        return None
+    normalized = str(runtime.get("base_url", "") or "").rstrip("/")
+    credits_url = f"{normalized}/credits"
+    key_url = f"{normalized}/key"
+    headers = {
+        "Authorization": f"Bearer {token}",
+        "Accept": "application/json",
+    }
+    with httpx.Client(timeout=10.0) as client:
+        credits_resp = client.get(credits_url, headers=headers)
+        credits_resp.raise_for_status()
+        credits = (credits_resp.json() or {}).get("data") or {}
+        try:
+            key_resp = client.get(key_url, headers=headers)
+            key_resp.raise_for_status()
+            key_data = (key_resp.json() or {}).get("data") or {}
+        except Exception:
+            key_data = {}
+    total_credits = float(credits.get("total_credits") or 0.0)
+    total_usage = float(credits.get("total_usage") or 0.0)
+    details = [f"Credits balance: ${max(0.0, total_credits - total_usage):.2f}"]
+    windows: list[AccountUsageWindow] = []
+    limit = key_data.get("limit")
+    limit_remaining = key_data.get("limit_remaining")
+    limit_reset = str(key_data.get("limit_reset") or "").strip()
+    usage = key_data.get("usage")
+    if (
+        isinstance(limit, (int, float))
+        and float(limit) > 0
+        and isinstance(limit_remaining, (int, float))
+        and 0 <= float(limit_remaining) <= float(limit)
+    ):
+        limit_value = float(limit)
+        remaining_value = float(limit_remaining)
+        used_percent = ((limit_value - remaining_value) / limit_value) * 100
+        detail_parts = [f"${remaining_value:.2f} of ${limit_value:.2f} remaining"]
+        if limit_reset:
+            detail_parts.append(f"resets {limit_reset}")
+        windows.append(
+            AccountUsageWindow(
+                label="API key quota",
+                used_percent=used_percent,
+                detail=" • ".join(detail_parts),
+            )
+        )
+    if isinstance(usage, (int, float)):
+        usage_parts = [f"API key usage: ${float(usage):.2f} total"]
+        for value, label in (
+            (key_data.get("usage_daily"), "today"),
+            (key_data.get("usage_weekly"), "this week"),
+            (key_data.get("usage_monthly"), "this month"),
+        ):
+            if isinstance(value, (int, float)) and float(value) > 0:
+                usage_parts.append(f"${float(value):.2f} {label}")
+        details.append(" • ".join(usage_parts))
+    return AccountUsageSnapshot(
+        provider="openrouter",
+        source="credits_api",
+        fetched_at=_utc_now(),
+        windows=tuple(windows),
+        details=tuple(details),
+    )
+
+
+def fetch_account_usage(
+    provider: Optional[str],
+    *,
+    base_url: Optional[str] = None,
+    api_key: Optional[str] = None,
+) -> Optional[AccountUsageSnapshot]:
+    normalized = str(provider or "").strip().lower()
+    if normalized in {"", "auto", "custom"}:
+        return None
+    try:
+        if normalized == "openai-codex":
+            return _fetch_codex_account_usage(base_url=base_url, api_key=api_key)
+        if normalized == "anthropic":
+            return _fetch_anthropic_account_usage()
+        if normalized == "openrouter":
+            return _fetch_openrouter_account_usage(base_url, api_key)
+    except Exception:
+        return None
+    return None

agent/acp_openai_bridge.py

@@ -0,0 +1,287 @@
+"""OpenAI-shape bridge shared by Hermes' ACP clients.
+
+An ACP agent (``copilot --acp``, and the ACP CLIs that reach Hermes as
+providers) speaks the Agent Client Protocol, which has no OpenAI-style
+``tools``/``tool_calls`` channel: a prompt is text, and a response is text plus
+the agent's *own* tool notifications. Hermes' agentic surface — ``memory``,
+``todo``, ``skill_manage`` and friends — is dispatched from OpenAI-shaped
+``tool_calls``, so on an ACP provider it can only work if the schemas travel
+*into* the prompt as text and the calls are parsed back *out* of the response
+text.
+
+``agent/copilot_acp_client.py`` already carried a private copy of that bridge.
+This module is that code, lifted verbatim into one place so every ACP client
+shares it instead of re-deriving the wire contract:
+
+* :func:`render_tool_bridge_sections` — prompt sections describing the
+  forwarded tools and the ``<tool_call>{...}</tool_call>`` contract.
+* :func:`extract_tool_calls_from_text` — parse those blocks back into
+  ``ChatCompletionMessageToolCall`` objects and return the response text with
+  the blocks stripped.
+* :func:`completion_to_stream_chunks` — re-shape a one-shot ACP response as
+  OpenAI stream chunks for callers that asked for ``stream=True`` (an ACP turn
+  is inherently one-shot from Hermes' perspective).
+
+The one axis clients differ on is *which* tools they forward, so
+``render_tool_bridge_sections`` takes an optional allowlist. A CLI with no tools
+of its own (Copilot) forwards everything Hermes offers; a CLI that is an
+autonomous agent with its own read/edit/execute tools must forward only Hermes'
+agent-level tools, because re-offering the overlapping ones makes Hermes re-run
+work the agent already finished.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from types import SimpleNamespace
+from typing import Any, Iterable
+
+from openai.types.chat.chat_completion_message_tool_call import (
+    ChatCompletionMessageToolCall,
+    Function,
+)
+
+TOOL_CALL_BLOCK_RE = re.compile(r"<tool_call>\s*(\{.*?\})\s*</tool_call>", re.DOTALL)
+TOOL_CALL_JSON_RE = re.compile(
+    r"\{\s*\"id\"\s*:\s*\"[^\"]+\"\s*,\s*\"type\"\s*:\s*\"function\"\s*,\s*\"function\"\s*:\s*\{.*?\}\s*\}",
+    re.DOTALL,
+)
+
+# The contract sentence shared by every ACP client: how to emit a call.
+TOOL_CALL_CONTRACT = (
+    "Available tools (OpenAI function schema). "
+    "When using a tool, emit ONLY <tool_call>{...}</tool_call> with one JSON object "
+    "containing id/type/function{name,arguments}. arguments must be a JSON string."
+)
+
+__all__ = [
+    "TOOL_CALL_BLOCK_RE",
+    "TOOL_CALL_JSON_RE",
+    "TOOL_CALL_CONTRACT",
+    "StreamChunks",
+    "build_openai_tool_call",
+    "tool_specs_from_openai_tools",
+    "render_tool_bridge_sections",
+    "extract_tool_calls_from_text",
+    "completion_to_stream_chunks",
+]
+
+
+class StreamChunks(list):
+    """Stream chunks that can still carry response-level attributes.
+
+    Hermes reads provider-level extras off the object returned by
+    ``chat.completions.create`` (e.g. ``hermes_projected_messages``, consumed by
+    ``agent/provider_projection.py``). A plain list of chunks would silently drop
+    them on the ``stream=True`` path, so ACP clients return this instead and copy
+    the extras onto it.
+    """
+
+
+def completion_to_stream_chunks(completion: SimpleNamespace) -> StreamChunks:
+    """Convert a one-shot ACP response into OpenAI-style stream chunks.
+
+    Response-level attributes other than ``choices``/``usage``/``model`` are
+    copied onto the returned object so nothing a caller reads off the completion
+    is lost when it asked to stream.
+    """
+    choice = completion.choices[0]
+    message = choice.message
+    tool_call_deltas = None
+    if message.tool_calls:
+        tool_call_deltas = []
+        for index, tool_call in enumerate(message.tool_calls):
+            tool_call_deltas.append(
+                SimpleNamespace(
+                    index=index,
+                    id=getattr(tool_call, "id", None),
+                    type=getattr(tool_call, "type", "function"),
+                    function=SimpleNamespace(
+                        name=getattr(tool_call.function, "name", None),
+                        arguments=getattr(tool_call.function, "arguments", None),
+                    ),
+                )
+            )
+
+    delta = SimpleNamespace(
+        role="assistant",
+        content=message.content or None,
+        tool_calls=tool_call_deltas,
+        reasoning_content=getattr(message, "reasoning_content", None),
+        reasoning=getattr(message, "reasoning", None),
+    )
+    data_chunk = SimpleNamespace(
+        choices=[
+            SimpleNamespace(
+                index=0,
+                delta=delta,
+                finish_reason=choice.finish_reason,
+            )
+        ],
+        model=completion.model,
+        usage=None,
+    )
+    usage_chunk = SimpleNamespace(
+        choices=[],
+        model=completion.model,
+        usage=completion.usage,
+    )
+    chunks = StreamChunks([data_chunk, usage_chunk])
+    for key, value in vars(completion).items():
+        if key not in ("choices", "usage", "model"):
+            setattr(chunks, key, value)
+    return chunks
+
+
+def build_openai_tool_call(
+    *,
+    call_id: str,
+    name: str,
+    arguments: str,
+) -> ChatCompletionMessageToolCall:
+    """Build an OpenAI-compatible tool-call object for downstream handling."""
+    return ChatCompletionMessageToolCall(
+        id=call_id,
+        call_id=call_id,
+        response_item_id=None,
+        type="function",
+        function=Function(name=name, arguments=arguments),
+    )
+
+
+def tool_specs_from_openai_tools(
+    tools: list[dict[str, Any]] | None,
+    *,
+    allowlist: Iterable[str] | None = None,
+) -> list[dict[str, Any]]:
+    """Flatten OpenAI ``tools`` into ``{name, description, parameters}`` specs.
+
+    Malformed entries are skipped. When ``allowlist`` is given, only tools whose
+    name is in it survive — that is how a client forwards just Hermes'
+    agent-level tools instead of the whole toolset.
+    """
+    allowed = {str(n).strip() for n in allowlist} if allowlist is not None else None
+    specs: list[dict[str, Any]] = []
+    for t in tools or []:
+        if not isinstance(t, dict):
+            continue
+        fn = t.get("function") or {}
+        if not isinstance(fn, dict):
+            continue
+        name = fn.get("name")
+        if not isinstance(name, str) or not name.strip():
+            continue
+        name = name.strip()
+        if allowed is not None and name not in allowed:
+            continue
+        specs.append(
+            {
+                "name": name,
+                "description": fn.get("description", ""),
+                "parameters": fn.get("parameters", {}),
+            }
+        )
+    return specs
+
+
+def render_tool_bridge_sections(
+    tools: list[dict[str, Any]] | None,
+    tool_choice: Any = None,
+    *,
+    allowlist: Iterable[str] | None = None,
+) -> list[str]:
+    """Prompt sections that carry the forwarded tool schemas + choice hint.
+
+    Returns an empty list when no tool survives filtering and no choice hint was
+    requested, so callers can splice the result into their section list
+    unconditionally.
+    """
+    specs = tool_specs_from_openai_tools(tools, allowlist=allowlist)
+    sections: list[str] = []
+    if specs:
+        sections.append(
+            TOOL_CALL_CONTRACT + "\n" + json.dumps(specs, ensure_ascii=False)
+        )
+    if tool_choice is not None:
+        sections.append(f"Tool choice hint: {json.dumps(tool_choice, ensure_ascii=False)}")
+    return sections
+
+
+def extract_tool_calls_from_text(
+    text: str,
+) -> tuple[list[ChatCompletionMessageToolCall], str]:
+    """Pull ``<tool_call>`` blocks out of an ACP response.
+
+    Returns ``(tool_calls, cleaned_text)`` where ``cleaned_text`` is the
+    response with the consumed blocks removed, so the assistant message doesn't
+    show raw JSON to the user.
+    """
+    if not isinstance(text, str) or not text.strip():
+        return [], ""
+
+    extracted: list[ChatCompletionMessageToolCall] = []
+    consumed_spans: list[tuple[int, int]] = []
+
+    def _try_add_tool_call(raw_json: str) -> None:
+        try:
+            obj = json.loads(raw_json)
+        except Exception:
+            return
+        if not isinstance(obj, dict):
+            return
+        fn = obj.get("function")
+        if not isinstance(fn, dict):
+            return
+        fn_name = fn.get("name")
+        if not isinstance(fn_name, str) or not fn_name.strip():
+            return
+        fn_args = fn.get("arguments", "{}")
+        if not isinstance(fn_args, str):
+            fn_args = json.dumps(fn_args, ensure_ascii=False)
+        call_id = obj.get("id")
+        if not isinstance(call_id, str) or not call_id.strip():
+            call_id = f"acp_call_{len(extracted)+1}"
+
+        extracted.append(
+            build_openai_tool_call(
+                call_id=call_id,
+                name=fn_name.strip(),
+                arguments=fn_args,
+            )
+        )
+
+    for m in TOOL_CALL_BLOCK_RE.finditer(text):
+        raw = m.group(1)
+        _try_add_tool_call(raw)
+        consumed_spans.append((m.start(), m.end()))
+
+    # Only try bare-JSON fallback when no XML blocks were found.
+    if not extracted:
+        for m in TOOL_CALL_JSON_RE.finditer(text):
+            raw = m.group(0)
+            _try_add_tool_call(raw)
+            consumed_spans.append((m.start(), m.end()))
+
+    if not consumed_spans:
+        return extracted, text.strip()
+
+    consumed_spans.sort()
+    merged: list[tuple[int, int]] = []
+    for start, end in consumed_spans:
+        if not merged or start > merged[-1][1]:
+            merged.append((start, end))
+        else:
+            merged[-1] = (merged[-1][0], max(merged[-1][1], end))
+
+    parts: list[str] = []
+    cursor = 0
+    for start, end in merged:
+        if cursor < start:
+            parts.append(text[cursor:start])
+        cursor = max(cursor, end)
+    if cursor < len(text):
+        parts.append(text[cursor:])
+
+    cleaned = "\n".join(p.strip() for p in parts if p and p.strip()).strip()
+    return extracted, cleaned

agent/anthropic_endpoints.py

@@ -0,0 +1,258 @@
+"""Endpoint-family detection for Anthropic-compatible base URLs.
+
+Hermes talks to a dozen services that speak the Anthropic Messages API but
+differ in auth style, accepted beta headers, and request quirks: MiniMax,
+Kimi/Moonshot, DeepSeek, OpenCode, Azure AI Foundry, the Nous portal, Bedrock.
+Every one of those differences is decided by inspecting the configured base
+URL, so the predicates live together here instead of being scattered through
+client construction and message conversion.
+
+Pure functions over a base-URL string - no I/O, no SDK, no credentials - which
+is what lets both ``agent/anthropic_adapter.py`` and
+``agent/anthropic_message_convert.py`` depend on this module without a cycle.
+
+``agent.anthropic_adapter`` re-exports every name below.
+"""
+
+from urllib.parse import urlparse
+
+from utils import base_url_host_matches, base_url_hostname
+
+
+def _normalize_base_url_text(base_url) -> str:
+    """Normalize SDK/base transport URL values to a plain string for inspection.
+
+    Some client objects expose ``base_url`` as an ``httpx.URL`` instead of a raw
+    string.  Provider/auth detection should accept either shape.
+    """
+    if not base_url:
+        return ""
+    return str(base_url).strip()
+
+
+def _is_third_party_anthropic_endpoint(base_url: str | None) -> bool:
+    """Return True for non-Anthropic endpoints using the Anthropic Messages API.
+
+    Third-party proxies (Microsoft Foundry, AWS Bedrock, self-hosted) authenticate
+    with their own API keys via x-api-key, not Anthropic OAuth tokens. OAuth
+    detection should be skipped for these endpoints.
+    """
+    normalized = _normalize_base_url_text(base_url)
+    if not normalized:
+        return False  # No base_url = direct Anthropic API
+    normalized = normalized.rstrip("/").lower()
+    if "anthropic.com" in normalized:
+        return False  # Direct Anthropic API — OAuth applies
+    return True  # Any other endpoint is a third-party proxy
+
+
+def _is_kimi_coding_endpoint(base_url: str | None) -> bool:
+    """Return True for Kimi's /coding endpoint that requires claude-code UA."""
+    normalized = _normalize_base_url_text(base_url)
+    if not normalized:
+        return False
+    return normalized.rstrip("/").lower().startswith("https://api.kimi.com/coding")
+
+
+def _is_opencode_endpoint(base_url: str | None) -> bool:
+    """Return True for OpenCode's Zen/Go relay (opencode.ai)."""
+    return base_url_host_matches(base_url or "", "opencode.ai")
+
+
+# Model-name prefixes that identify the Kimi / Moonshot family.  Covers
+# - official slugs: ``kimi-k2.5``, ``kimi_thinking``, ``moonshot-v1-8k``
+# - common release lines: ``k1.5-...``, ``k2-thinking``, ``k25-...``, ``k2.5-...``,
+#   and the bare Coding Plan slug ``k3`` (plus ``k3.x``/``k3-...`` variants)
+# Matched case-insensitively against the post-``normalize_model_name`` form,
+# so a caller's ``provider/vendor/model`` slug is handled the same as a
+# bare name.
+_KIMI_FAMILY_MODEL_PREFIXES = (
+    "kimi-", "kimi_",
+    "moonshot-", "moonshot_",
+    "k1.", "k1-",
+    "k2.", "k2-",
+    "k25", "k2.5",
+    "k3.", "k3-",
+)
+
+# Bare release slugs with no separator suffix (Kimi Coding Plan serves K3
+# as the exact slug ``k3``). Kept exact-match so unrelated model names that
+# merely start with the same characters don't get misclassified.
+_KIMI_FAMILY_EXACT_SLUGS = frozenset({"k3"})
+
+
+def _model_name_is_kimi_family(model: str | None) -> bool:
+    if not isinstance(model, str):
+        return False
+    m = model.strip().lower()
+    if not m:
+        return False
+    # Strip vendor prefix (e.g. ``moonshotai/kimi-k2.5`` → ``kimi-k2.5``)
+    if "/" in m:
+        m = m.rsplit("/", 1)[-1]
+    if m in _KIMI_FAMILY_EXACT_SLUGS:
+        return True
+    return m.startswith(_KIMI_FAMILY_MODEL_PREFIXES)
+
+
+def _is_kimi_family_endpoint(base_url: str | None, model: str | None = None) -> bool:
+    """Return True for any Kimi / Moonshot Anthropic-Messages-speaking endpoint.
+
+    Broader than ``_is_kimi_coding_endpoint`` — matches:
+
+    - Kimi's official ``/coding`` URL (legacy check, preserved)
+    - Any ``api.kimi.com`` / ``moonshot.ai`` / ``moonshot.cn`` host
+    - Custom or proxied endpoints whose *model* name is in the Kimi / Moonshot
+      family (``kimi-*``, ``moonshot-*``, ``k1.*``, ``k2.*``, …).  Users with
+      ``api_mode: anthropic_messages`` on a private gateway fronting Kimi
+      fall into this branch — the upstream still enforces Kimi's thinking
+      semantics (reasoning_content required on every replayed tool-call
+      message) regardless of the gateway's hostname.
+
+    Used to decide whether to drop Anthropic's ``thinking`` kwarg and to
+    preserve unsigned reasoning_content-derived thinking blocks on replay.
+    See hermes-agent#13848, #17057.
+    """
+    if _is_kimi_coding_endpoint(base_url):
+        return True
+    for _domain in ("api.kimi.com", "moonshot.ai", "moonshot.cn"):
+        if base_url_host_matches(base_url or "", _domain):
+            return True
+    if _model_name_is_kimi_family(model):
+        return True
+    return False
+
+
+def _is_deepseek_anthropic_endpoint(base_url: str | None) -> bool:
+    """Return True for DeepSeek's Anthropic-compatible endpoint.
+
+    DeepSeek's ``/anthropic`` route speaks the Anthropic Messages protocol
+    but, when thinking mode is enabled, requires the ``thinking`` blocks
+    from prior assistant turns to round-trip on subsequent requests — the
+    generic third-party path strips them and triggers HTTP 400::
+
+        The content[].thinking in the thinking mode must be passed back
+        to the API.
+
+    Per DeepSeek's published compatibility matrix the blocks are unsigned
+    (no Anthropic-proprietary signature, no ``redacted_thinking`` support),
+    so this endpoint is handled with the same strip-signed / keep-unsigned
+    policy used for Kimi's ``/coding`` endpoint.  The match is pinned to
+    the ``/anthropic`` path so the OpenAI-compatible ``api.deepseek.com``
+    base URL (which never reaches this adapter) is not misclassified.
+    See hermes-agent#16748.
+    """
+    if not base_url_host_matches(base_url or "", "api.deepseek.com"):
+        return False
+    normalized = _normalize_base_url_text(base_url)
+    if not normalized:
+        return False
+    return "/anthropic" in normalized.rstrip("/").lower()
+
+
+def _is_nous_portal_endpoint(base_url: str | None) -> bool:
+    """Return True for Nous Portal's Anthropic Messages route.
+
+    Portal serves its ``anthropic/*`` catalog natively at
+    ``https://inference-api.nousresearch.com/v1/messages``.  Portal-specific
+    behaviours key off this: Bearer JWT auth, verbatim catalog model ids,
+    and native thinking-signature replay.
+
+    Trusted hosts only:
+
+    1. Prod hostname ``inference-api.nousresearch.com``
+    2. The operator-set ``NOUS_INFERENCE_BASE_URL`` hostname (staging/preview)
+
+    Lookalikes such as ``inference-api.nousresearch.com.attacker.test`` are
+    rejected (hostname match, not substring).
+    """
+    if base_url_host_matches(base_url or "", "inference-api.nousresearch.com"):
+        return True
+    try:
+        from hermes_cli.auth import _nous_inference_env_override
+
+        override = _nous_inference_env_override()
+    except Exception:
+        return False
+    if not override:
+        return False
+    # Exact host equality (not subdomain) so the env override can't broaden
+    # into sibling hosts the operator did not set.
+    override_host = base_url_hostname(override)
+    return bool(override_host) and base_url_hostname(base_url or "") == override_host
+
+
+def _requires_bearer_auth(base_url: str | None) -> bool:
+    """Return True for Anthropic-compatible providers that require Bearer auth.
+
+    Some third-party /anthropic endpoints implement Anthropic's Messages API but
+    require Authorization: Bearer instead of Anthropic's native x-api-key header.
+    MiniMax's global and China Anthropic-compatible endpoints, Azure AI
+    Foundry's Anthropic-style endpoint, Palantir Foundry's LLM proxy, and Nous
+    Portal's Messages route follow this pattern.
+    """
+    if _is_nous_portal_endpoint(base_url):
+        return True
+    normalized = _normalize_base_url_text(base_url)
+    if not normalized:
+        return False
+    normalized = normalized.rstrip("/").lower()
+    return (
+        normalized.startswith(("https://api.minimax.io/anthropic", "https://api.minimaxi.com/anthropic"))
+        or "azure.com" in normalized
+        # Palantir Foundry LLM proxy (<org>.palantirfoundry.com/api/v2/llm/proxy/anthropic)
+        # rejects x-api-key with 401 and requires Authorization: Bearer.
+        # Hostname match (not substring) so e.g. evil.com/palantirfoundry
+        # paths don't trigger Bearer auth.
+        or base_url_host_matches(normalized, "palantirfoundry.com")
+        # CommandCode's /provider/v1/messages endpoint uses Bearer auth,
+        # not Anthropic's native x-api-key header. Hostname match for the
+        # same reason as above.
+        or base_url_host_matches(normalized, "api.commandcode.ai")
+    )
+
+
+def _base_url_needs_context_1m_beta(base_url: str | None) -> bool:
+    """Return True for endpoints that still gate 1M context behind a beta."""
+    normalized = _normalize_base_url_text(base_url).lower()
+    if not normalized:
+        return False
+    return "azure.com" in normalized
+
+
+def _is_minimax_anthropic_endpoint(base_url: str | None) -> bool:
+    """Return True for MiniMax's Anthropic-compatible endpoints.
+
+    MiniMax rejects the fine-grained-tool-streaming and context-1m betas;
+    those need to be stripped even though MiniMax also uses Bearer auth.
+    """
+    normalized = _normalize_base_url_text(base_url)
+    if not normalized:
+        return False
+    normalized = normalized.rstrip("/").lower()
+    return normalized.startswith(
+        ("https://api.minimax.io/anthropic", "https://api.minimaxi.com/anthropic")
+    )
+
+
+def _is_azure_anthropic_endpoint(base_url: str | None) -> bool:
+    """Return True for Azure-hosted Anthropic Messages endpoints.
+
+    Covers both the modern Foundry host family (``*.services.ai.azure.*``)
+    and the legacy Azure OpenAI host family (``*.openai.azure.*``) when
+    serving Anthropic's ``/anthropic`` route. Used to opt-in those hosts
+    to the ``api-version`` query-param plumbing required by Azure.
+
+    Intentionally avoids a finite allow-list of TLD suffixes so it works
+    across sovereign / private Azure clouds.
+    """
+    normalized = _normalize_base_url_text(base_url)
+    if not normalized:
+        return False
+    parsed = urlparse(normalized)
+    host = (parsed.hostname or "").lower().rstrip(".")
+    path = (parsed.path or "").lower()
+    host_padded = f".{host}."
+    is_foundry_host = ".services.ai.azure." in host_padded
+    is_legacy_azoai_host = ".openai.azure." in host_padded
+    return (is_foundry_host or is_legacy_azoai_host) and "/anthropic" in path

agent/async_utils.py

@@ -0,0 +1,84 @@
+"""Async/sync bridging helpers.
+
+The codebase has ~30 sites that schedule a coroutine onto an event loop from a
+worker thread via :func:`asyncio.run_coroutine_threadsafe`.  That function can
+raise :class:`RuntimeError` (e.g. the loop was closed during a shutdown race),
+and when it does the coroutine object is never awaited and never closed —
+which triggers a ``"coroutine '<name>' was never awaited"`` RuntimeWarning and
+leaks the coroutine's frame until GC.
+
+:func:`safe_schedule_threadsafe` wraps the call, closes the coroutine on
+scheduling failure, and returns ``None`` (instead of a half-formed future) so
+callers can branch cleanly:
+
+    fut = safe_schedule_threadsafe(coro, loop)
+    if fut is None:
+        return  # or fallback behavior
+    fut.result(timeout=5)
+
+The helper deliberately does NOT also handle ``future.result()`` failures —
+that is a separate concern.  Once the loop has accepted the coroutine, its
+lifecycle belongs to the loop, not the scheduling thread.
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+from concurrent.futures import Future
+from typing import Any, Coroutine, Optional
+
+
+_DEFAULT_LOGGER = logging.getLogger(__name__)
+
+
+def safe_schedule_threadsafe(
+    coro: Coroutine[Any, Any, Any],
+    loop: Optional[asyncio.AbstractEventLoop],
+    *,
+    logger: Optional[logging.Logger] = None,
+    log_message: str = "Failed to schedule coroutine on loop",
+    log_level: int = logging.DEBUG,
+) -> Optional[Future]:
+    """Schedule ``coro`` on ``loop`` from a sync context, leak-safe.
+
+    Returns the :class:`concurrent.futures.Future` on success, or ``None`` if
+    the loop is missing or :func:`asyncio.run_coroutine_threadsafe` raised
+    (e.g. the loop was closed during a shutdown race).  In all failure paths
+    the coroutine is :meth:`close`-d so it does not trigger
+    ``"coroutine was never awaited"`` warnings or leak its frame.
+
+    Callers retain full control over what to do with the returned future
+    (call ``.result(timeout=...)``, attach ``add_done_callback``, ignore it
+    fire-and-forget, etc.).
+    """
+    log = logger if logger is not None else _DEFAULT_LOGGER
+
+    if loop is None:
+        if asyncio.iscoroutine(coro):
+            coro.close()
+        log.log(log_level, "%s: loop is None", log_message)
+        return None
+
+    try:
+        return asyncio.run_coroutine_threadsafe(coro, loop)
+    except Exception as exc:
+        if asyncio.iscoroutine(coro):
+            coro.close()
+        log.log(log_level, "%s: %s", log_message, exc)
+        return None
+
+
+def consume_detached_task_result(task: "asyncio.Future[Any]") -> None:
+    """Retrieve a detached task's result without surfacing cancellation.
+
+    Used as an ``add_done_callback`` on tasks that were cancelled and
+    detached (e.g. an adapter close path that swallows ``CancelledError``
+    past its teardown deadline). Observing ``task.exception()`` prevents
+    "exception was never retrieved" noise on the event loop; cancellation
+    and any terminal error are deliberately swallowed — the task's owner
+    already gave up on it.
+    """
+    try:
+        task.exception()
+    except (asyncio.CancelledError, Exception):
+        pass

agent/aux_accounting.py

@@ -0,0 +1,138 @@
+"""Ambient session-accounting context for auxiliary LLM calls.
+
+Auxiliary calls (vision, compression, title generation, web_extract,
+session_search, ...) funnel through ``agent.auxiliary_client`` which has no
+session handle — so their token usage was historically discarded, leaving
+dashboard analytics blind to aux model spend (issue #23270).
+
+Instead of threading ``session_db``/``session_id`` parameters through every
+aux call site, the agent loop publishes them here (mirroring the Nous Portal
+conversation context in ``agent.portal_tags``) and the auxiliary client
+records usage at its single response-validation chokepoint.
+
+ContextVar semantics give us the right isolation for free:
+
+* concurrent agents in one process (gateway sessions, delegate subagents)
+  never see each other's accounting context;
+* worker threads spawned via ``tools.thread_context.propagate_context_to_thread``
+  (MoA fan-out, background review) inherit the parent turn's context;
+* asyncio tasks inherit the context of the code that created them.
+
+MoA reference/aggregator slots are explicitly EXCLUDED from recording:
+``agent/conversation_loop.py`` already folds MoA advisor usage and cost into
+the main loop's ``update_token_counts`` delta, so recording them here would
+double-count (see ``_EXCLUDED_TASKS``).
+"""
+
+from __future__ import annotations
+
+import logging
+from contextvars import ContextVar
+from typing import Any, Optional
+
+logger = logging.getLogger(__name__)
+
+# (session_db, session_id) for the active agent turn, or None outside one.
+_accounting: ContextVar[Optional[tuple]] = ContextVar(
+    "aux_accounting_context", default=None
+)
+
+# Aux tasks whose usage is already accounted by the main loop — recording
+# them here would double-count. MoA advisor/aggregator usage is folded into
+# conversation_loop's update_token_counts delta (tokens AND cost).
+_EXCLUDED_TASKS = frozenset({"moa_reference", "moa_aggregator"})
+
+
+def set_accounting_context(session_db: Any, session_id: Optional[str]):
+    """Publish the active session's accounting handles for aux usage recording.
+
+    Called by the agent loop at turn entry. Returns the ContextVar token so
+    callers can ``reset_accounting_context(token)`` on turn exit. Publishing
+    ``None`` handles (no DB / no session id) clears the context.
+    """
+    if session_db is None or not session_id:
+        return _accounting.set(None)
+    return _accounting.set((session_db, session_id))
+
+
+def reset_accounting_context(token) -> None:
+    """Restore the previous accounting context (pair with ``set_...``)."""
+    try:
+        _accounting.reset(token)
+    except Exception:
+        _accounting.set(None)
+
+
+def get_accounting_context() -> Optional[tuple]:
+    """Return ``(session_db, session_id)`` for the active turn, or ``None``."""
+    return _accounting.get()
+
+
+def record_aux_usage(
+    response: Any,
+    task: Optional[str],
+    *,
+    provider: Optional[str] = None,
+    base_url: Optional[str] = None,
+) -> None:
+    """Record an auxiliary response's token usage against the ambient session.
+
+    Called from the auxiliary client's response-validation chokepoint. Strictly
+    best-effort: any failure is swallowed (accounting must never break an aux
+    call). No-ops when:
+
+    * no accounting context is published (call is outside any agent turn),
+    * the task is main-loop-accounted (MoA slots — see ``_EXCLUDED_TASKS``),
+    * the response carries no usage object.
+
+    The model is read from ``response.model`` (accurate even after the aux
+    client's provider-fallback chains); *provider*/*base_url* reflect the
+    originally-resolved route and are best-effort.
+    """
+    try:
+        if not task or task in _EXCLUDED_TASKS:
+            return
+        ctx = _accounting.get()
+        if ctx is None:
+            return
+        session_db, session_id = ctx
+        raw_usage = getattr(response, "usage", None)
+        if raw_usage is None:
+            return
+
+        from agent.usage_pricing import estimate_usage_cost, normalize_usage
+
+        usage = normalize_usage(raw_usage, provider=provider)
+        if not (
+            usage.input_tokens or usage.output_tokens
+            or usage.cache_read_tokens or usage.cache_write_tokens
+            or usage.reasoning_tokens
+        ):
+            return
+
+        model = str(getattr(response, "model", "") or "") or "unknown"
+        estimated_cost = None
+        try:
+            cost = estimate_usage_cost(
+                model, usage, provider=provider, base_url=base_url
+            )
+            if cost.amount_usd is not None:
+                estimated_cost = float(cost.amount_usd)
+        except Exception:
+            logger.debug("Aux usage cost estimation failed", exc_info=True)
+
+        session_db.record_auxiliary_usage(
+            session_id,
+            task,
+            model=model,
+            billing_provider=provider,
+            billing_base_url=base_url,
+            input_tokens=usage.input_tokens,
+            output_tokens=usage.output_tokens,
+            cache_read_tokens=usage.cache_read_tokens,
+            cache_write_tokens=usage.cache_write_tokens,
+            reasoning_tokens=usage.reasoning_tokens,
+            estimated_cost_usd=estimated_cost,
+        )
+    except Exception:
+        logger.debug("Aux usage recording failed (non-fatal)", exc_info=True)

agent/azure_identity_adapter.py

@@ -0,0 +1,571 @@
+"""Microsoft Entra ID adapter for Microsoft Foundry.
+
+Provides keyless authentication for Microsoft Foundry deployments using the
+`azure-identity` SDK's `DefaultAzureCredential` chain (env service principal
+→ workload identity → managed identity → VS Code → Azure CLI → azd →
+PowerShell → broker).
+
+Architecture mirrors `agent/bedrock_adapter.py`:
+
+* Lazy import. `azure-identity` is only loaded when ``model.auth_mode =
+  entra_id`` is selected. Users who stick with `AZURE_FOUNDRY_API_KEY`
+  never pay the import cost.
+* SDK-callable contract. The public entry point ``build_token_provider``
+  returns a zero-arg callable produced by ``get_bearer_token_provider`` —
+  this is exactly the value Microsoft's documented sample plugs into
+  ``OpenAI(api_key=token_provider, base_url=...)``. The OpenAI SDK calls
+  it before every request, so token refresh is transparent.
+* Three explicit consumer-side helpers (display / cache / http-bearer)
+  rather than one generic "materialize" function — splitting them by
+  purpose prevents accidental token-minting in logging paths or token
+  leakage into cache keys / dashboard JSON.
+* No persisted JWT. ``azure-identity`` caches in-process and (where
+  available) in the OS keychain or ``~/.IdentityService``. Hermes does
+  not duplicate that storage in ``auth.json``.
+
+Reference: https://learn.microsoft.com/azure/ai-foundry/foundry-models/how-to/configure-entra-id
+
+Requires: ``azure-identity`` (optional dependency — only needed when
+``model.auth_mode = entra_id``).
+"""
+
+from __future__ import annotations
+
+import functools
+import logging
+import os
+import threading
+from dataclasses import dataclass
+from typing import Any, Callable, Dict, Optional
+
+logger = logging.getLogger(__name__)
+
+# Microsoft-documented scope for Foundry inference auth. Both the new
+# Foundry portal and the legacy Azure OpenAI managed-identity docs use
+# this scope for ALL Foundry endpoint shapes (*.openai.azure.com,
+# *.services.ai.azure.com, *.ai.azure.com). The older control-plane
+# scope ``https://cognitiveservices.azure.com/.default`` is for ARM
+# resource management and is rejected for inference by newer
+# resources — users with that requirement override via
+# ``model.entra.scope`` in config.yaml.
+SCOPE_AI_AZURE_DEFAULT = "https://ai.azure.com/.default"
+
+# ---------------------------------------------------------------------------
+# Lazy SDK import — only loaded when the Entra path is actually used.
+# ---------------------------------------------------------------------------
+
+_AZURE_IDENTITY_FEATURE = "provider.azure_identity"
+
+
+def has_azure_identity_installed() -> bool:
+    """Return True if `azure-identity` can be imported right now.
+
+    Cheap check — does not walk the credential chain.
+    """
+    try:
+        import azure.identity  # noqa: F401
+        return True
+    except Exception:
+        return False
+
+
+def _require_azure_identity():
+    """Import ``azure.identity``, lazy-installing it if allowed.
+
+    Raises ``ImportError`` with a clear actionable message when the
+    package is missing and lazy installs are disabled.
+    """
+    try:
+        import azure.identity as _ai
+        return _ai
+    except ImportError:
+        try:
+            from tools.lazy_deps import ensure, FeatureUnavailable
+        except ImportError as exc:
+            raise ImportError(
+                "The 'azure-identity' package is required for Azure AI "
+                "Foundry Entra ID authentication. Install it with: "
+                "pip install azure-identity"
+            ) from exc
+
+        try:
+            ensure(_AZURE_IDENTITY_FEATURE, prompt=False)
+        except FeatureUnavailable as exc:
+            raise ImportError(
+                "The 'azure-identity' package is required for Azure AI "
+                "Foundry Entra ID authentication. " + str(exc)
+            ) from exc
+
+        # Retry import after lazy install.
+        import azure.identity as _ai  # noqa: WPS440
+        return _ai
+
+
+def reset_credential_cache() -> None:
+    """Clear the cached ``DefaultAzureCredential``. Used by tests and
+    profile switches.
+
+    Defensive against tests that ``monkeypatch.setattr`` over
+    ``build_credential`` with a plain (non-lru-cached) function — those
+    won't expose ``cache_clear()`` until pytest reverts the patch.
+    """
+    cache_clear = getattr(build_credential, "cache_clear", None)
+    if callable(cache_clear):
+        cache_clear()
+
+
+# ---------------------------------------------------------------------------
+# Token-provider construction
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class EntraIdentityConfig:
+    """Serializable Entra ID config.
+
+    Captures the Hermes-managed Entra knobs we need outside Azure SDK
+    environment configuration. Everything else
+    (tenant ID, service principal secret, federated token file, sovereign
+    cloud authority, etc.) flows through azure-identity's standard
+    ``AZURE_*`` env vars — see the Bedrock pattern in
+    ``hermes_cli/runtime_provider.py:1310-1377`` for the analogous
+    "let the SDK read env" approach.
+
+    ``scope`` is Microsoft's documented Foundry inference audience. Almost
+    everyone uses the default; sovereign-cloud / non-standard tenants can
+    override via ``model.entra.scope``. Identity selection (user-assigned
+    managed identity, workload identity, service principal, tenant, authority)
+    stays in the standard Azure SDK env vars such as ``AZURE_CLIENT_ID``.
+
+    ``exclude_interactive_browser`` is kept as an internal constructor knob
+    so probes stay non-interactive by default. It is not written by the setup
+    wizard.
+
+    The dataclass is frozen so it's hashable for ``functools.lru_cache``
+    keying, and serializable across multiprocessing boundaries (workers
+    rebuild the credential inside their own process).
+    """
+
+    scope: str = SCOPE_AI_AZURE_DEFAULT
+    exclude_interactive_browser: bool = True
+
+    def __post_init__(self) -> None:
+        scope = str(self.scope or "").strip() or SCOPE_AI_AZURE_DEFAULT
+        object.__setattr__(self, "scope", scope)
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "scope": self.scope,
+            "exclude_interactive_browser": self.exclude_interactive_browser,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Optional[Dict[str, Any]],
+                  *, default_scope: Optional[str] = None) -> "EntraIdentityConfig":
+        data = data or {}
+        scope = str(data.get("scope") or "").strip() or default_scope or SCOPE_AI_AZURE_DEFAULT
+        exclude_browser = bool(data.get("exclude_interactive_browser", True))
+        return cls(
+            scope=scope,
+            exclude_interactive_browser=exclude_browser,
+        )
+
+
+def _build_default_credential(config: EntraIdentityConfig) -> Any:
+    """Construct a ``DefaultAzureCredential`` for ``config``.
+
+    Only Hermes-selected knobs are passed as kwargs. Everything else
+    (tenant, service principal secret, federated token file, sovereign
+    cloud authority, etc.) is read by ``azure-identity`` from the
+    standard ``AZURE_*`` environment variables — see Microsoft's
+    documented credential resolution chain. Users configure those in
+    ``~/.hermes/.env`` or the deployment environment.
+    """
+    ai = _require_azure_identity()
+    kwargs: Dict[str, Any] = {}
+    # SDK default is True (browser excluded); only pass when the user
+    # explicitly opts in to interactive browser auth.
+    if not config.exclude_interactive_browser:
+        kwargs["exclude_interactive_browser_credential"] = False
+    return ai.DefaultAzureCredential(**kwargs)
+
+
+@functools.lru_cache(maxsize=1)
+def build_credential(config: EntraIdentityConfig) -> Any:
+    """Return the cached ``DefaultAzureCredential`` for ``config``.
+
+    Hermes processes use exactly one Entra config at a time (the
+    ``model.entra.*`` block in config.yaml drives every aux task,
+    subagent, and credential probe in the session). ``maxsize=1`` is
+    intentional: it reflects the actual usage pattern and keeps the
+    cache trivially small.
+
+    ``EntraIdentityConfig`` is a frozen dataclass, so it's hashable and
+    safe as an LRU-cache key. ``functools.lru_cache`` is thread-safe in
+    CPython.
+
+    If two distinct configs are ever passed (tests do this; production
+    rarely), the LRU eviction handles it correctly — each call still
+    returns a credential matching its config; only one is cached at a
+    time. Use :func:`reset_credential_cache` to clear (e.g. in tests).
+    """
+    return _build_default_credential(config)
+
+
+def build_token_provider(scope: Optional[str] = None,
+                         *,
+                         config: Optional[EntraIdentityConfig] = None,
+                         base_url: Optional[str] = None,
+                         exclude_interactive_browser: bool = True,
+                         ) -> Callable[[], str]:
+    """Return a zero-arg callable that mints a fresh Entra bearer JWT.
+
+    The returned callable is exactly what Microsoft's documented Foundry
+    sample expects::
+
+        from openai import OpenAI
+        client = OpenAI(
+            base_url="https://my-resource.openai.azure.com/openai/v1/",
+            api_key=build_token_provider(),
+        )
+
+    Scope resolution order:
+      1. ``config.scope`` when a config object is supplied
+      2. explicit ``scope`` kwarg
+      3. ``SCOPE_AI_AZURE_DEFAULT`` (Microsoft's documented Foundry scope)
+
+    ``base_url`` is unused today and kept for back-compat. Tenant /
+    service-principal / sovereign-cloud configuration flows through
+    ``azure-identity``'s standard ``AZURE_*`` environment variables —
+    see :func:`_build_default_credential` for the rationale.
+
+    NOT serializable across process boundaries. For multiprocessing
+    workers, serialize the ``EntraIdentityConfig`` and rebuild the
+    provider inside the worker.
+    """
+    ai = _require_azure_identity()
+    if config is None:
+        config = EntraIdentityConfig(
+            scope=scope or SCOPE_AI_AZURE_DEFAULT,
+            exclude_interactive_browser=exclude_interactive_browser,
+        )
+    credential = build_credential(config)
+    return ai.get_bearer_token_provider(credential, config.scope)
+
+
+# ---------------------------------------------------------------------------
+# Credential probing
+# ---------------------------------------------------------------------------
+
+
+def has_azure_identity_credentials(scope: Optional[str] = None,
+                                   *,
+                                   config: Optional[EntraIdentityConfig] = None,
+                                   timeout_seconds: float = 10.0,
+                                   allow_install: bool = True,
+                                   **overrides: Any) -> bool:
+    """Best-effort probe: can `DefaultAzureCredential` mint a token now?
+
+    Runs ``credential.get_token(scope)`` under a thread-based timeout so
+    a slow token service can't hang the caller. Returns False on any
+    error — never raises. Use for ``hermes doctor`` /
+    ``hermes auth status`` / wizard preflight.
+
+    ``allow_install``: when True (default) and ``azure-identity`` is not
+    importable, the adapter triggers the standard lazy-install path
+    (subject to ``security.allow_lazy_installs``) before probing. Set
+    False to make this strictly an "is installed?" check — used on hot
+    paths like CLI startup where we never want pip to run.
+
+    NOT used by ``is_provider_configured()`` — that path is structural
+    only (no token mint), so CLI startup doesn't pay this latency.
+    """
+    if not has_azure_identity_installed():
+        if not allow_install:
+            return False
+        try:
+            _require_azure_identity()
+        except ImportError as exc:
+            logger.debug("azure-identity lazy install unavailable: %s", exc)
+            return False
+    if config is None:
+        effective_scope = (scope or "").strip() or SCOPE_AI_AZURE_DEFAULT
+        config = EntraIdentityConfig(scope=effective_scope, **overrides)
+
+    result = {"ok": False}
+
+    def _probe() -> None:
+        try:
+            credential = build_credential(config)
+            tok = credential.get_token(config.scope)
+            result["ok"] = bool(getattr(tok, "token", None))
+        except Exception as exc:
+            logger.debug("Entra credential probe failed: %s", exc)
+            result["ok"] = False
+
+    thread = threading.Thread(target=_probe, daemon=True)
+    thread.start()
+    thread.join(timeout=max(0.01, timeout_seconds))
+    if thread.is_alive():
+        logger.debug("Entra token service probe timed out after %ss", timeout_seconds)
+        return False
+    return bool(result.get("ok"))
+
+
+def describe_active_credential(config: Optional[EntraIdentityConfig] = None,
+                               *,
+                               scope: Optional[str] = None,
+                               timeout_seconds: float = 10.0,
+                               allow_install: bool = True,
+                               **overrides: Any) -> Dict[str, Any]:
+    """Return diagnostic info about the active credential chain.
+
+    Best-effort: runs ``get_token()`` and inspects what came back.
+    Designed for ``hermes doctor`` and the wizard preflight — never
+    raises, returns ``{"ok": False, "error": ...}`` on failure.
+
+    ``allow_install``: when True (default) and ``azure-identity`` is not
+    importable, the adapter triggers the standard lazy-install path
+    (subject to ``security.allow_lazy_installs``) before probing. The
+    install failure is surfaced as the diagnostic error when it fails.
+    Set False for hot CLI paths that should never trigger pip.
+
+    ``azure-identity`` doesn't expose the winning inner credential as
+    a public field, so we report a coarse picture (env vars present,
+    token expiry, claims-derived tenant) rather than the credential
+    class name. Users wanting the precise class can run with
+    ``AZURE_LOG_LEVEL=DEBUG``.
+    """
+    info: Dict[str, Any] = {"ok": False}
+    if not has_azure_identity_installed():
+        if not allow_install:
+            info["error"] = "azure-identity not installed"
+            info["hint"] = (
+                "pip install azure-identity (or rely on lazy install at "
+                "first use)"
+            )
+            return info
+        try:
+            _require_azure_identity()
+        except ImportError as exc:
+            info["error"] = str(exc) or "azure-identity not installed"
+            info["hint"] = (
+                "pip install azure-identity manually, or enable lazy "
+                "installs (security.allow_lazy_installs: true in "
+                "config.yaml)."
+            )
+            return info
+
+    if config is None:
+        effective_scope = (scope or "").strip() or SCOPE_AI_AZURE_DEFAULT
+        config = EntraIdentityConfig(scope=effective_scope, **overrides)
+
+    info["scope"] = config.scope
+    # Tenant / authority / service-principal config flow through the
+    # standard ``AZURE_*`` env vars; surface them below.
+    if os.environ.get("AZURE_TENANT_ID", "").strip():
+        info["tenant_id_env"] = os.environ["AZURE_TENANT_ID"].strip()
+
+    # Surface which env-var sources are present without minting yet.
+    # Credential-bearing vars (AZURE_CLIENT_SECRET, AZURE_FEDERATED_TOKEN_FILE)
+    # are read through the profile secret scope so a multiplexed profile's
+    # diagnostics don't report another profile's env-bridged credentials;
+    # unscoped CLI probes keep the legacy env read (Slack pattern).
+    def _scoped_env(name: str) -> str:
+        try:
+            from agent.secret_scope import UnscopedSecretError, get_secret
+
+            try:
+                return (get_secret(name) or "").strip()
+            except UnscopedSecretError:
+                pass
+        except Exception:
+            pass
+        return os.environ.get(name, "").strip()
+
+    env_sources = []
+    if _scoped_env("AZURE_FEDERATED_TOKEN_FILE"):
+        env_sources.append("WorkloadIdentityCredential (AZURE_FEDERATED_TOKEN_FILE)")
+    if (os.environ.get("AZURE_CLIENT_ID", "").strip()
+            and _scoped_env("AZURE_CLIENT_SECRET")
+            and os.environ.get("AZURE_TENANT_ID", "").strip()):
+        env_sources.append("EnvironmentCredential (client secret)")
+    if os.environ.get("IDENTITY_ENDPOINT", "").strip() or os.environ.get("MSI_ENDPOINT", "").strip():
+        env_sources.append("ManagedIdentityCredential (IDENTITY_ENDPOINT)")
+    info["env_sources"] = env_sources
+
+    # Now try minting.
+    result: Dict[str, Any] = {}
+
+    def _probe() -> None:
+        try:
+            credential = build_credential(config)
+            tok = credential.get_token(config.scope)
+            result["token"] = tok
+        except Exception as exc:
+            result["error"] = str(exc)
+
+    thread = threading.Thread(target=_probe, daemon=True)
+    thread.start()
+    thread.join(timeout=max(0.01, timeout_seconds))
+    if thread.is_alive():
+        info["error"] = f"Token probe timed out after {timeout_seconds:.0f}s"
+        info["hint"] = (
+            "DefaultAzureCredential can be slow when the token service is unreachable "
+            "or when az login state is stale. Try `az login` or set "
+            "AZURE_CLIENT_ID / AZURE_TENANT_ID / AZURE_CLIENT_SECRET."
+        )
+        return info
+
+    if "error" in result:
+        info["error"] = result["error"]
+        return info
+
+    token = result.get("token")
+    if token is None:
+        info["error"] = "credential chain exhausted"
+        return info
+
+    info["ok"] = True
+    info["expires_on"] = getattr(token, "expires_on", None)
+    return info
+
+
+# ---------------------------------------------------------------------------
+# Consumer-side helpers — split by purpose to prevent accidental token
+# minting in logging / cache-key / dashboard paths.
+# ---------------------------------------------------------------------------
+
+
+def is_token_provider(value: Any) -> bool:
+    """Return True when ``value`` is a callable Entra token provider.
+
+    Used at the seams where a consumer must decide between
+    string-API-key semantics and bearer-callable semantics.
+    """
+    return callable(value) and not isinstance(value, str)
+
+
+def materialize_bearer_for_http(value: Any) -> str:
+    """Return a fresh Bearer JWT for a manual HTTP request.
+
+    Only call this at sites that must construct an ``Authorization``
+    header outside the OpenAI SDK (e.g. ``hermes_cli/azure_detect.py``).
+    Calls the callable exactly once and returns the resulting token.
+
+    **Anthropic SDK integration:** the Anthropic Python SDK does not
+    accept a ``Callable[[], str]`` for ``auth_token``. Instead,
+    :func:`build_bearer_http_client` returns an ``httpx.Client`` whose
+    request event hook calls this function and rewrites the
+    ``Authorization`` header per request — and that client is passed to
+    the Anthropic SDK via ``http_client=...``. See
+    :func:`agent.anthropic_adapter.build_anthropic_client` for the
+    consumer.
+
+    Raises ``ValueError`` if ``value`` is not a callable token provider
+    or non-empty string.
+    """
+    if is_token_provider(value):
+        token = value()
+        if not isinstance(token, str) or not token:
+            raise ValueError("token provider returned empty value")
+        return token
+    if isinstance(value, str) and value:
+        return value
+    raise ValueError("no usable api_key / token provider")
+
+
+def build_bearer_http_client(token_provider: Callable[[], str], **httpx_kwargs: Any) -> Any:
+    """Return an ``httpx.Client`` that mints a fresh Entra bearer JWT
+    per outbound request.
+
+    The Anthropic SDK (≤ 0.86.0 at the time of writing) stores
+    ``api_key`` / ``auth_token`` as static strings and computes the
+    ``Authorization`` header at construction time. To get per-request
+    token refresh (the Microsoft-recommended Foundry pattern for
+    callable bearer providers), we install an httpx ``request`` event
+    hook on a custom client and pass that client to the SDK via
+    ``http_client=...``. The hook:
+
+      1. Calls :func:`materialize_bearer_for_http` to mint a fresh JWT
+         (azure-identity caches internally — this is cheap when the
+         cached token is still valid).
+      2. Strips any pre-set ``Authorization`` / ``api-key`` /
+         ``x-api-key`` headers the SDK may have added (avoids
+         conflicting auth values).
+      3. Sets ``Authorization: Bearer <fresh-jwt>``.
+
+    ``token_provider`` must be a zero-arg callable returning a string —
+    typically the result of :func:`build_token_provider`.
+
+    ``httpx_kwargs`` are forwarded verbatim to ``httpx.Client(...)`` so
+    callers can attach a ``timeout``, ``transport``, ``proxy``, etc.
+
+    Raises ``ImportError`` if ``httpx`` is not installed (it is a
+    transitive dependency of both ``openai`` and ``anthropic`` SDKs, so
+    in practice always available when this helper is reached).
+    """
+    if not is_token_provider(token_provider):
+        raise ValueError(
+            "build_bearer_http_client requires a zero-arg callable "
+            "token provider"
+        )
+
+    try:
+        import httpx
+    except ImportError as exc:  # pragma: no cover — httpx ships with openai/anthropic
+        raise ImportError(
+            "httpx is required for Entra ID bearer auth on Microsoft Foundry "
+            "Anthropic-style endpoints. It is normally a transitive "
+            "dependency of the openai/anthropic SDKs."
+        ) from exc
+
+    def _inject_bearer(request: "httpx.Request") -> None:
+        try:
+            token = materialize_bearer_for_http(token_provider)
+        except ValueError as exc:
+            # Token provider failed (chain exhausted, token service unreachable,
+            # az login expired, etc.). Strip any auth headers the SDK
+            # may have set — including our own placeholder sentinel
+            # ``entra-id-bearer-via-http-hook`` from
+            # ``_build_anthropic_client_with_bearer_hook`` — so the
+            # outbound request hits Azure with NO Authorization rather
+            # than with the placeholder. Azure returns a clean 401
+            # "missing auth" that is easier to diagnose than a 401
+            # against the sentinel string, and the sentinel never
+            # appears in upstream access logs.
+            #
+            # Log at WARNING (not DEBUG) so the misconfiguration is
+            # visible at default log levels.
+            logger.warning(
+                "Bearer hook: Entra ID token provider returned empty (%s) "
+                "— stripping Authorization headers. Azure will respond 401. "
+                "Run `hermes doctor` or `az login` to recover.",
+                exc,
+            )
+            for header_name in ("Authorization", "authorization", "Api-Key", "api-key", "X-Api-Key", "x-api-key"):
+                request.headers.pop(header_name, None)
+            return
+        for header_name in ("Authorization", "authorization", "Api-Key", "api-key", "X-Api-Key", "x-api-key"):
+            request.headers.pop(header_name, None)
+        request.headers["Authorization"] = f"Bearer {token}"
+
+    return httpx.Client(
+        event_hooks={"request": [_inject_bearer]},
+        **httpx_kwargs,
+    )
+
+
+__all__ = [
+    "EntraIdentityConfig",
+    "SCOPE_AI_AZURE_DEFAULT",
+    "build_bearer_http_client",
+    "build_credential",
+    "build_token_provider",
+    "describe_active_credential",
+    "has_azure_identity_credentials",
+    "has_azure_identity_installed",
+    "is_token_provider",
+    "materialize_bearer_for_http",
+    "reset_credential_cache",
+]

agent/backend_identity.py

@@ -0,0 +1,204 @@
+"""Single owner for backend identity and failure-scoped skip decisions.
+
+Every fallback / dedup / skip / quarantine decision in Hermes ultimately asks
+one question: **"is this candidate the same backend as the one that failed,
+along the axis that failure invalidated?"**  Before this module, that
+question was re-implemented inline at six call sites across four subsystems,
+each comparing whatever string was locally convenient (provider label,
+provider+model, base_url+model, ...).  Each incident fixed one site while the
+others kept the bug: #22548 (same-shim aliases), #70893 (xai-oauth vs xai —
+same host, distinct credential), #59561 (aux chain skipped sibling models),
+#72468 (aux main-model safety net, same bug three weeks later), #62984 /
+#54250 / #57584 (dedup ignoring base_url strands multi-endpoint pools).
+
+The root insight: "provider" conflates three independent identity axes, and
+each failure class invalidates a different one:
+
+* **credential surface** — auth 401 / payment 402 kill everything sharing the
+  credential (every model, every host reached with that key/token).
+* **endpoint** — DNS failure / connection refused kill everything behind the
+  URL, regardless of model or credential.
+* **model deployment** — timeout / overload / rate limit / model-incompatible
+  kill ONE model's deployment.  A sibling model behind the same URL is an
+  independent deployment (real incident: aux ``glm-5.2`` hung and timed out
+  while main ``macaron-v1-venti`` on the identical endpoint was serving
+  448K-token turns).
+
+Call sites should build :class:`BackendIdentity` values, classify the failure
+with :func:`classify_failure_scope`, and ask :func:`should_skip_candidate`.
+Do not re-implement any comparison inline — extend THIS module instead.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from enum import Enum
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+
+class FailureScope(Enum):
+    """Which identity axis a failure invalidates."""
+
+    #: Timeout, overload/429, connection blip, model-incompatible, invalid
+    #: response: evidence against ONE model deployment only.
+    MODEL = "model"
+    #: Auth 401 / payment 402: evidence against the shared credential —
+    #: every model reached with it is equally dead.
+    CREDENTIAL = "credential"
+    #: DNS / connection-refused / unreachable host: evidence against the
+    #: endpoint — every model behind the URL is equally dead.
+    ENDPOINT = "endpoint"
+
+
+#: Reason strings already used by auxiliary_client's except-chain, mapped to
+#: scopes. Unknown reasons default to MODEL — the least-invalidating scope —
+#: so an unrecognized failure never over-skips viable candidates.
+_REASON_SCOPES = {
+    "auth error": FailureScope.CREDENTIAL,
+    "payment error": FailureScope.CREDENTIAL,
+    "rate limit": FailureScope.MODEL,
+    "model incompatible with route": FailureScope.MODEL,
+    "invalid provider response": FailureScope.MODEL,
+    "connection error": FailureScope.MODEL,
+    "timeout": FailureScope.MODEL,
+}
+
+
+def classify_failure_scope(reason: Optional[str]) -> FailureScope:
+    """Map a human-readable failure reason to the identity axis it kills."""
+    return _REASON_SCOPES.get((reason or "").strip().lower(), FailureScope.MODEL)
+
+
+def _norm_provider(value: Optional[str]) -> str:
+    return (value or "").strip().lower()
+
+
+def _norm_model(value: Optional[str]) -> str:
+    return (value or "").strip().lower()
+
+
+def _norm_base_url(value: Optional[str]) -> str:
+    return (value or "").strip().rstrip("/").lower()
+
+
+@dataclass(frozen=True)
+class BackendIdentity:
+    """Normalized identity of one (provider, model, endpoint) deployment.
+
+    Empty fields mean "unknown" — comparisons treat an unknown axis as
+    non-distinguishing (it can neither prove sameness nor difference on its
+    own; the remaining axes decide).
+    """
+
+    provider: str = ""
+    model: str = ""
+    base_url: str = ""
+
+    @classmethod
+    def build(
+        cls,
+        provider: Optional[str] = None,
+        model: Optional[str] = None,
+        base_url: Optional[str] = None,
+    ) -> "BackendIdentity":
+        return cls(
+            provider=_norm_provider(provider),
+            model=_norm_model(model),
+            base_url=_norm_base_url(base_url),
+        )
+
+
+def _both_first_class(a: BackendIdentity, b: BackendIdentity) -> bool:
+    """True when both providers are distinct registered first-class providers.
+
+    Two different registry providers have distinct credential surfaces even
+    when they share an inference host (xai-oauth vs xai, openai-codex vs
+    openai-api) — #70893.  Custom/shim aliases are NOT in the registry, so
+    two aliases pointing at one URL still count as the same backend (#22548).
+    """
+    if not a.provider or not b.provider or a.provider == b.provider:
+        return False
+    try:
+        from hermes_cli.auth import PROVIDER_REGISTRY
+
+        return a.provider in PROVIDER_REGISTRY and b.provider in PROVIDER_REGISTRY
+    except Exception:
+        return False
+
+
+def same_credential_surface(a: BackendIdentity, b: BackendIdentity) -> bool:
+    """Do two identities share the credential a 401/402 just invalidated?
+
+    Conservative on purpose: an unprovable axis must answer "different"
+    (try the candidate — worst case one wasted RTT) rather than "same"
+    (skip — worst case stranded failover). Two distinct custom labels at
+    one URL may carry different per-entry api_keys, so a shared URL alone
+    never proves a shared credential; it is only used as a weak signal
+    when a provider label is missing entirely.
+    """
+    if a.provider and b.provider:
+        # Same label = same configured credential. Different labels =
+        # different credential config (first-class registry providers
+        # explicitly so — #70893; custom entries can each carry their own
+        # api_key, so sameness is unprovable and we must not skip).
+        return a.provider == b.provider
+    # Provider unknown on a side: same explicit URL is the best signal left.
+    return bool(a.base_url and a.base_url == b.base_url)
+
+
+def same_endpoint(a: BackendIdentity, b: BackendIdentity) -> bool:
+    """Do two identities sit behind the endpoint that just went unreachable?"""
+    if a.base_url and b.base_url:
+        return a.base_url == b.base_url
+    # An unknown base_url inherits the provider default → same provider
+    # label implies the same default endpoint.
+    return bool(a.provider and a.provider == b.provider)
+
+
+def same_deployment(a: BackendIdentity, b: BackendIdentity) -> bool:
+    """Are these the exact same model deployment (the thing a timeout kills)?
+
+    Provider+model must match; the base_url axis distinguishes only when BOTH
+    sides carry an explicit URL (#62984: same provider+model on two different
+    explicit URLs is two deployments — a pool).  A side with an unknown URL
+    inherits the provider default and cannot prove difference.
+    """
+    if not (a.provider and b.provider and a.provider == b.provider):
+        # Same-host different-label shims: same URL + same model IS the same
+        # deployment even when the alias labels differ (#22548) — unless both
+        # labels are first-class registry providers (#70893).
+        if (
+            a.base_url
+            and a.base_url == b.base_url
+            and a.model
+            and a.model == b.model
+            and not _both_first_class(a, b)
+        ):
+            return True
+        return False
+    if not (a.model and b.model and a.model == b.model):
+        return False
+    if a.base_url and b.base_url and a.base_url != b.base_url:
+        return False  # distinct explicit endpoints — a pool, not a dup
+    return True
+
+
+def should_skip_candidate(
+    candidate: BackendIdentity,
+    failed: BackendIdentity,
+    scope: FailureScope = FailureScope.MODEL,
+) -> bool:
+    """THE skip predicate: would trying ``candidate`` just repeat the failure?
+
+    True when the candidate is the same backend as ``failed`` along the axis
+    ``scope`` says the failure invalidated.  Every fallback/dedup/skip site
+    must call this instead of comparing labels inline.
+    """
+    if scope is FailureScope.CREDENTIAL:
+        return same_credential_surface(candidate, failed)
+    if scope is FailureScope.ENDPOINT:
+        return same_endpoint(candidate, failed)
+    return same_deployment(candidate, failed)

agent/battery.py

@@ -0,0 +1,131 @@
+"""System-battery read-out for the CLI/TUI status bar.
+
+Reads the host battery through ``psutil`` (already a Hermes dependency) and
+exposes a compact, colour-coded label.  Everything degrades to "unavailable"
+when there is no battery (desktops, servers, VMs) or when the read fails, so
+callers can render the result unconditionally and simply show nothing.
+
+The status bar repaints often (every keystroke and on a ~1s idle refresh), so
+:func:`read_battery` memoises the last reading for a few seconds instead of
+hitting ``psutil`` on every frame.
+"""
+
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass
+from typing import Optional
+
+
+@dataclass(frozen=True)
+class BatteryStatus:
+    """A single battery reading.
+
+    ``available`` is False on machines without a battery (or when the read
+    failed).  ``percent`` is clamped to 0-100.  ``plugged`` is True when on AC
+    power, False on battery, and None when the platform can't tell.
+    """
+
+    available: bool
+    percent: Optional[int] = None
+    plugged: Optional[bool] = None
+
+    @property
+    def charging(self) -> bool:
+        return bool(self.plugged)
+
+
+UNAVAILABLE = BatteryStatus(available=False)
+
+# Colour buckets, mirroring the status-bar context styles but inverted (a full
+# battery is "good", an empty one is "critical").
+CATEGORY_GOOD = "good"
+CATEGORY_WARN = "warn"
+CATEGORY_BAD = "bad"
+CATEGORY_CRITICAL = "critical"
+CATEGORY_DIM = "dim"
+
+_CACHE_TTL_SECONDS = 8.0
+_cache: Optional[tuple[float, BatteryStatus]] = None
+
+
+def _read_battery_uncached() -> BatteryStatus:
+    try:
+        import psutil
+    except Exception:
+        return UNAVAILABLE
+
+    # ``sensors_battery`` is missing on some platforms/builds of psutil.
+    reader = getattr(psutil, "sensors_battery", None)
+    if reader is None:
+        return UNAVAILABLE
+
+    try:
+        batt = reader()
+    except Exception:
+        return UNAVAILABLE
+
+    if batt is None:
+        return UNAVAILABLE
+
+    percent: Optional[int] = None
+    raw_percent = getattr(batt, "percent", None)
+    if raw_percent is not None:
+        try:
+            percent = max(0, min(100, int(round(float(raw_percent)))))
+        except (TypeError, ValueError):
+            percent = None
+
+    plugged = getattr(batt, "power_plugged", None)
+    if plugged is not None:
+        plugged = bool(plugged)
+
+    return BatteryStatus(available=True, percent=percent, plugged=plugged)
+
+
+def read_battery(use_cache: bool = True) -> BatteryStatus:
+    """Return the current battery status (cached for a few seconds)."""
+    global _cache
+    if use_cache and _cache is not None:
+        ts, cached = _cache
+        if time.monotonic() - ts < _CACHE_TTL_SECONDS:
+            return cached
+
+    status = _read_battery_uncached()
+    _cache = (time.monotonic(), status)
+    return status
+
+
+def clear_cache() -> None:
+    """Drop the memoised reading (used by tests)."""
+    global _cache
+    _cache = None
+
+
+def battery_category(status: BatteryStatus) -> str:
+    """Bucket a reading into a colour category: good/warn/bad/critical/dim."""
+    if not status.available or status.percent is None:
+        return CATEGORY_DIM
+    # On AC power the level isn't a concern — always read as healthy.
+    if status.charging:
+        return CATEGORY_GOOD
+    pct = status.percent
+    if pct <= 10:
+        return CATEGORY_CRITICAL
+    if pct <= 20:
+        return CATEGORY_BAD
+    if pct <= 50:
+        return CATEGORY_WARN
+    return CATEGORY_GOOD
+
+
+def battery_glyph(status: BatteryStatus) -> str:
+    """Return the leading glyph: a bolt while charging, else a battery."""
+    return "\u26a1" if status.charging else "\U0001f50b"  # ⚡ / 🔋
+
+
+def format_battery(status: BatteryStatus) -> str:
+    """Return a compact label like ``🔋 82%`` / ``⚡ 82%`` (empty if N/A)."""
+    if not status.available or status.percent is None:
+        return ""
+    return f"{battery_glyph(status)} {status.percent}%"

agent/billing_links.py

@@ -0,0 +1,124 @@
+"""Provider-agnostic billing/credit recovery links.
+
+Maps a billing-classified failure onto a recovery link + label. *Detection*
+is not done here — that is :mod:`agent.error_classifier`
+(``FailoverReason.billing``), the single source of truth for "credit wall vs.
+rate limit / auth / transport". The resulting :class:`BillingBlock` rides the
+turn result and the gateway ``message.complete`` event so every surface (CLI,
+TUI, desktop) renders one structured signal instead of re-parsing error text.
+"""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from typing import Optional
+
+from utils import base_url_host_matches
+
+
+@dataclass
+class BillingBlock:
+    """Structured billing-wall descriptor shared across every surface.
+
+    ``is_nous`` is the routing bit: Nous has a first-class in-app billing surface
+    (desktop Settings → Billing, TUI/CLI ``/topup``), so surfaces prefer that over
+    ``billing_url``; third-party providers have no in-app flow, so ``billing_url``
+    is the deep link the user actually needs.
+    """
+
+    provider: str
+    provider_label: str
+    model: str
+    billing_url: Optional[str]
+    is_nous: bool
+    message: str
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+@dataclass(frozen=True)
+class _Provider:
+    label: str
+    url: str
+    slugs: tuple[str, ...]
+    hosts: tuple[str, ...] = ()
+
+
+# Single source of truth: internal slug(s) + base_url host(s) → billing page.
+# Curated "add credits / manage billing" landing pages, not marketing homes.
+# Hosts back the OpenAI-compatible fallback where the slug is a generic bucket
+# (e.g. "openai_compatible") but base_url reveals the real upstream. An unknown
+# provider degrades to a readable label with no invented URL.
+_PROVIDERS: tuple[_Provider, ...] = (
+    _Provider("OpenAI", "https://platform.openai.com/settings/organization/billing", ("openai",), ("api.openai.com",)),
+    _Provider("Anthropic", "https://console.anthropic.com/settings/billing", ("anthropic",), ("api.anthropic.com",)),
+    _Provider("OpenRouter", "https://openrouter.ai/settings/credits", ("openrouter",), ("openrouter.ai",)),
+    _Provider("xAI", "https://console.x.ai/team/default/billing", ("xai", "xai-oauth"), ("api.x.ai",)),
+    _Provider("DeepSeek", "https://platform.deepseek.com/top_up", ("deepseek",), ("api.deepseek.com",)),
+    _Provider("Groq", "https://console.groq.com/settings/billing", ("groq",), ("api.groq.com",)),
+    _Provider("Mistral", "https://console.mistral.ai/billing", ("mistral",), ("api.mistral.ai",)),
+    _Provider("Together AI", "https://api.together.ai/settings/billing", ("together",), ("api.together.ai", "api.together.xyz")),
+    _Provider("Fireworks AI", "https://fireworks.ai/account/billing", ("fireworks",), ("fireworks.ai",)),
+    _Provider("Perplexity", "https://www.perplexity.ai/settings/api", ("perplexity",), ("perplexity.ai",)),
+    _Provider("Google AI", "https://aistudio.google.com/app/billing", ("google", "gemini"), ("generativelanguage.googleapis.com",)),
+    _Provider("Cohere", "https://dashboard.cohere.com/billing", ("cohere",)),
+    _Provider("Moonshot AI", "https://platform.moonshot.ai/console/pay", ("moonshot",)),
+    _Provider("NVIDIA", "https://build.nvidia.com/settings/billing", ("nvidia",)),
+)
+
+_BY_SLUG: dict[str, _Provider] = {slug: p for p in _PROVIDERS for slug in p.slugs}
+
+
+def is_nous_inference_route(provider: str, base_url: str) -> bool:
+    """True when the failing route is the Nous-managed inference gateway."""
+    if (provider or "").strip().lower() == "nous":
+        return True
+    return base_url_host_matches(str(base_url or ""), "inference-api.nousresearch.com")
+
+
+def _nous_billing_url() -> Optional[str]:
+    """Best-effort Nous portal billing URL (text-surface fallback; Nous prefers the in-app flow)."""
+    try:
+        from hermes_cli.nous_account import nous_portal_billing_url
+
+        return nous_portal_billing_url(None)
+    except Exception:
+        return "https://portal.nousresearch.com/billing"
+
+
+def _resolve_provider_link(slug: str, base_url: str) -> tuple[str, Optional[str]]:
+    """Resolve ``(label, url)``: exact slug → base_url host → readable-label fallback."""
+    hit = _BY_SLUG.get(slug)
+    if hit:
+        return hit.label, hit.url
+
+    base = str(base_url or "")
+    for p in _PROVIDERS:
+        if any(base_url_host_matches(base, host) for host in p.hosts):
+            return p.label, p.url
+
+    return slug.replace("_", " ").replace("-", " ").strip().title() or "your provider", None
+
+
+def build_billing_block(
+    *,
+    provider: str,
+    base_url: str,
+    model: str,
+    message: str = "",
+) -> BillingBlock:
+    """Build the billing descriptor for a billing-classified failure.
+
+    ``message`` is the guidance already assembled by the agent loop
+    (:func:`agent.conversation_loop._billing_or_entitlement_message`), carried
+    through unchanged so every surface shows identical copy.
+    """
+    slug = (provider or "").strip().lower()
+    model = (model or "").strip()
+
+    if is_nous_inference_route(slug, base_url):
+        return BillingBlock(slug or "nous", "Nous Portal", model, _nous_billing_url(), True, message or "")
+
+    label, url = _resolve_provider_link(slug, base_url)
+    return BillingBlock(slug, label, model, url, False, message or "")

agent/billing_usage.py

@@ -0,0 +1,323 @@
+"""Shared dollar-denominated usage model for the billing/subscription surfaces.
+
+The single source of truth behind the ``/usage`` and ``/subscription`` usage
+bars (TUI + CLI). User feedback (Jun 2026): the terminal surfaces show
+**dollars**, never "credits", and every usage bar must make the monthly
+subscription allowance and separately-purchased top-up dollars distinctly
+visible.
+
+Data source: the NAS account-info fetch (``NousPortalAccountInfo``), whose
+``paid_service_access_info`` carries the three dollar magnitudes we render
+(despite the legacy ``*_credits`` field names, these are USD floats):
+
+  - ``subscription_credits_remaining``  -> plan dollars left this month
+  - ``purchased_credits_remaining``     -> top-up dollars left (rolls over)
+  - ``total_usable_credits``            -> total spendable
+
+plus ``subscription.monthly_credits`` (the plan's monthly $ allowance, the
+denominator for the "% used" plan bar) and ``current_period_end`` (renewal).
+
+Design: two SEPARATE bars (decided with the user) rather than one crammed
+three-segment bar — at terminal widths three same-glyph density segments are
+unreadable. The plan bar is "spent vs allowance this month" (carries % used);
+the top-up bar is "money you bought, doesn't expire". Each gets full
+resolution and a single fill glyph, so the bar is never ambiguous and never
+relies on color.
+
+Fail-open everywhere: any missing/non-finite field degrades to fewer bars or a
+magnitudes-only view; a logged-out / unreachable portal yields
+``available=False`` and the surface shows nothing.
+"""
+
+from __future__ import annotations
+
+import logging
+import math
+import os
+from dataclasses import dataclass
+from typing import Any, Optional
+
+logger = logging.getLogger(__name__)
+
+# Below this TOTAL spendable ($), a paid account is flagged "low" — the alert
+# state that nudges top-up/upgrade before a mid-run cutoff. Product threshold
+# (user feedback): "any amount below $5 should be an alert status."
+LOW_BALANCE_THRESHOLD_USD = 5.0
+
+
+def _finite(value: Any) -> Optional[float]:
+    """Return value as a float iff it's a real finite number (not bool/NaN/Inf)."""
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        return None
+    f = float(value)
+    return f if math.isfinite(f) else None
+
+
+def _fmt_usd(value: Optional[float]) -> str:
+    """``$X.YY`` for display. ``None`` -> ``$0.00`` (callers gate on presence)."""
+    return f"${(value or 0.0):,.2f}"
+
+
+def format_renews(value: Optional[str]) -> Optional[str]:
+    """Format an ISO date/timestamp as a human date, e.g. ``Jul 24, 2026``.
+
+    Accepts ``2026-07-24``, ``2026-07-24T11:05:01.000Z``, etc. Returns the raw
+    string unchanged if it can't be parsed (never raises), and ``None`` for
+    empty input.
+    """
+    if not value:
+        return None
+    from datetime import datetime
+
+    text = str(value).strip()
+    if not text:
+        return None
+    iso = text[:-1] + "+00:00" if text.endswith("Z") else text
+    try:
+        dt = datetime.fromisoformat(iso)
+    except ValueError:
+        # Fall back to a bare date prefix (YYYY-MM-DD) if present.
+        try:
+            dt = datetime.strptime(text[:10], "%Y-%m-%d")
+        except ValueError:
+            return text
+    # %-d isn't portable to Windows; build the day without a leading zero.
+    return f"{dt.strftime('%b')} {dt.day}, {dt.year}"
+
+
+@dataclass(frozen=True)
+class UsageBar:
+    """One full-resolution bar: ``spent`` of ``total``, plus a remaining figure.
+
+    ``kind`` is ``"plan"`` (monthly allowance, shows % used) or ``"topup"``
+    (purchased dollars, no denominator — ``spent`` is 0 and ``total`` ==
+    ``remaining`` so it renders as a full bar of available balance).
+    """
+
+    kind: str  # "plan" | "topup"
+    remaining_usd: float
+    total_usd: float
+    spent_usd: float = 0.0
+
+    @property
+    def pct_used(self) -> Optional[int]:
+        if self.kind != "plan" or self.total_usd <= 0:
+            return None
+        return max(0, min(100, round(self.spent_usd / self.total_usd * 100)))
+
+    @property
+    def fill_fraction(self) -> float:
+        """Fraction of the bar that should read as 'remaining' (filled)."""
+        if self.total_usd <= 0:
+            return 0.0
+        return max(0.0, min(1.0, self.remaining_usd / self.total_usd))
+
+
+@dataclass(frozen=True)
+class UsageModel:
+    """Surface-agnostic dollar usage model shared by /usage and /subscription.
+
+    ``status`` classifies the account for copy selection:
+      - ``"free"``     : no paid access / no subscription (free models only)
+      - ``"low"``      : paid, but total spendable < $5 (ALERT)
+      - ``"healthy"``  : paid, total spendable >= $5
+      - ``"depleted"`` : paid access lost (balance exhausted)
+    """
+
+    available: bool
+    status: str = "free"
+    plan_name: Optional[str] = None
+    renews_at: Optional[str] = None
+    renews_display: Optional[str] = None
+    subscription_remaining_usd: Optional[float] = None
+    topup_remaining_usd: Optional[float] = None
+    total_spendable_usd: Optional[float] = None
+    plan_bar: Optional[UsageBar] = None
+    topup_bar: Optional[UsageBar] = None
+
+    @property
+    def has_topup(self) -> bool:
+        return bool(self.topup_remaining_usd and self.topup_remaining_usd > 0)
+
+
+def usage_model_from_account(account_info: Any) -> UsageModel:
+    """Build a :class:`UsageModel` from a ``NousPortalAccountInfo``. Fail-open.
+
+    Returns ``UsageModel(available=False)`` when there's no usable account info
+    (logged out, no entitlement block). Never raises.
+    """
+    try:
+        if account_info is None or not getattr(account_info, "logged_in", False):
+            return UsageModel(available=False)
+
+        access = getattr(account_info, "paid_service_access_info", None)
+        sub = getattr(account_info, "subscription", None)
+        paid = getattr(account_info, "paid_service_access", None)
+
+        sub_remaining = _finite(getattr(access, "subscription_credits_remaining", None)) if access else None
+        topup_remaining = _finite(getattr(access, "purchased_credits_remaining", None)) if access else None
+        total_usable = _finite(getattr(access, "total_usable_credits", None)) if access else None
+
+        plan_name = getattr(sub, "plan", None) if sub is not None else None
+        renews_at = getattr(sub, "current_period_end", None) if sub is not None else None
+        monthly = _finite(getattr(sub, "monthly_credits", None)) if sub is not None else None
+
+        has_subscription = bool(plan_name) or (monthly is not None and monthly > 0)
+
+        # Total spendable: prefer the server's total; else sum the parts we have.
+        if total_usable is not None:
+            total_spendable = total_usable
+        else:
+            parts = [v for v in (sub_remaining, topup_remaining) if v is not None]
+            total_spendable = sum(parts) if parts else None
+
+        # Status classification.
+        if paid is False:
+            status = "depleted"
+        elif not has_subscription and not (topup_remaining and topup_remaining > 0):
+            # No plan and no purchased balance -> free-models-only.
+            status = "free"
+        elif total_spendable is not None and total_spendable < LOW_BALANCE_THRESHOLD_USD:
+            status = "low"
+        else:
+            status = "healthy"
+
+        # Plan bar — only with a positive monthly allowance AND a remaining we
+        # can place on it. spent = cap - remaining, clamped (a debt/over-cap
+        # balance reads as fully spent rather than a nonsensical negative).
+        plan_bar: Optional[UsageBar] = None
+        if monthly is not None and monthly > 0 and sub_remaining is not None:
+            remaining = max(0.0, min(monthly, sub_remaining))
+            plan_bar = UsageBar(
+                kind="plan",
+                remaining_usd=remaining,
+                total_usd=monthly,
+                spent_usd=max(0.0, monthly - sub_remaining),
+            )
+
+        # Top-up bar — only when there are purchased dollars to show. No
+        # denominator (top-up has no monthly cap), so it renders full = balance.
+        topup_bar: Optional[UsageBar] = None
+        if topup_remaining is not None and topup_remaining > 0:
+            topup_bar = UsageBar(
+                kind="topup",
+                remaining_usd=topup_remaining,
+                total_usd=topup_remaining,
+                spent_usd=0.0,
+            )
+
+        return UsageModel(
+            available=True,
+            status=status,
+            plan_name=plan_name,
+            renews_at=renews_at,
+            renews_display=format_renews(renews_at),
+            subscription_remaining_usd=sub_remaining,
+            topup_remaining_usd=topup_remaining,
+            total_spendable_usd=total_spendable,
+            plan_bar=plan_bar,
+            topup_bar=topup_bar,
+        )
+    except Exception:
+        logger.debug("usage ▸ model build failed (fail-open)", exc_info=True)
+        return UsageModel(available=False)
+
+
+def build_usage_model(*, timeout: float = 10.0) -> UsageModel:
+    """Fetch account-info and build the shared usage model. Fail-open.
+
+    Dev override: ``HERMES_DEV_CREDITS_FIXTURE`` short-circuits to a fixture so
+    every usage state is testable without a live account (mirrors the existing
+    ``/usage`` credits-block fixture path).
+    """
+    fixture = _dev_fixture_usage_model()
+    if fixture is not None:
+        return fixture
+
+    try:
+        from hermes_cli.auth import get_provider_auth_state
+
+        tok = (get_provider_auth_state("nous") or {}).get("access_token")
+        if not (isinstance(tok, str) and tok.strip()):
+            return UsageModel(available=False)
+    except Exception:
+        return UsageModel(available=False)
+
+    try:
+        import concurrent.futures
+
+        from hermes_cli.nous_account import get_nous_portal_account_info
+
+        with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
+            account = pool.submit(get_nous_portal_account_info, force_fresh=True).result(timeout=timeout)
+        return usage_model_from_account(account)
+    except Exception:
+        logger.debug("usage ▸ portal fetch failed (fail-open)", exc_info=True)
+        return UsageModel(available=False)
+
+
+# =============================================================================
+# Dev fixtures (throwaway scaffolding — env-var driven, no live portal)
+# =============================================================================
+
+
+def _dev_fixture_usage_model() -> Optional[UsageModel]:
+    """Map ``HERMES_DEV_CREDITS_FIXTURE`` to a usage model for offline UX work.
+
+    Recognized names: ``free | healthy | low | topup | depleted``. Returns
+    ``None`` when the env var is unset (real portal path runs).
+    """
+    name = (os.getenv("HERMES_DEV_CREDITS_FIXTURE") or "").strip().lower()
+    if not name:
+        return None
+
+    if name == "free":
+        return UsageModel(available=True, status="free", plan_name=None)
+
+    if name in ("healthy", "mid"):
+        return UsageModel(
+            available=True,
+            status="healthy",
+            plan_name="Plus",
+            renews_at="2026-07-01",
+            subscription_remaining_usd=14.0,
+            total_spendable_usd=14.0,
+            plan_bar=UsageBar(kind="plan", remaining_usd=14.0, total_usd=20.0, spent_usd=6.0),
+        )
+
+    if name in ("topup", "top-up"):
+        return UsageModel(
+            available=True,
+            status="healthy",
+            plan_name="Plus",
+            renews_at="2026-07-01",
+            subscription_remaining_usd=14.0,
+            topup_remaining_usd=12.0,
+            total_spendable_usd=26.0,
+            plan_bar=UsageBar(kind="plan", remaining_usd=14.0, total_usd=20.0, spent_usd=6.0),
+            topup_bar=UsageBar(kind="topup", remaining_usd=12.0, total_usd=12.0, spent_usd=0.0),
+        )
+
+    if name == "low":
+        return UsageModel(
+            available=True,
+            status="low",
+            plan_name="Plus",
+            renews_at="2026-07-01",
+            subscription_remaining_usd=3.4,
+            total_spendable_usd=3.4,
+            plan_bar=UsageBar(kind="plan", remaining_usd=3.4, total_usd=20.0, spent_usd=16.6),
+        )
+
+    if name == "depleted":
+        return UsageModel(
+            available=True,
+            status="depleted",
+            plan_name="Plus",
+            renews_at="2026-07-01",
+            subscription_remaining_usd=0.0,
+            total_spendable_usd=0.0,
+            plan_bar=UsageBar(kind="plan", remaining_usd=0.0, total_usd=20.0, spent_usd=20.0),
+        )
+
+    return None