fix(keystore): reorder unlock priority — interactive prompt before env var

The env var HERMES_KEYSTORE_PASSPHRASE is now correctly positioned as a
last-resort fallback for headless/Docker/systemd deployments, not as the
second-choice unlock method.

New unlock priority:
1. OS credential store (hermes keystore remember)
2. Interactive passphrase prompt (when TTY available)
3. HERMES_KEYSTORE_PASSPHRASE env var (headless fallback only)

Updated docs and code comments to clearly communicate this is a conscious
security tradeoff for unattended operation, not the recommended path.

.dockerignore

@@ -1,13 +0,0 @@
-# Git
-.git
-.gitignore
-.gitmodules
-
-# Dependencies
-node_modules
-
-# CI/CD
-.github
-
-# Environment files
-.env

.env.example

@@ -74,10 +74,6 @@ HF_TOKEN=
 # 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=
@@ -98,7 +94,7 @@ FAL_KEY=
 HONCHO_API_KEY=
 
 # =============================================================================
-# TERMINAL TOOL CONFIGURATION
+# TERMINAL TOOL CONFIGURATION (mini-swe-agent backend)
 # =============================================================================
 # Backend type: "local", "singularity", "docker", "modal", or "ssh"
 # Terminal backend is configured in ~/.hermes/config.yaml (terminal.backend).

.github/workflows/docker-publish.yml

@@ -1,61 +0,0 @@
-name: Docker Build and Publish
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-    branches: [main]
-
-concurrency:
-  group: docker-${{ github.ref }}
-  cancel-in-progress: true
-
-jobs:
-  build-and-push:
-    runs-on: ubuntu-latest
-    timeout-minutes: 30
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v4
-        with:
-          submodules: recursive
-
-      - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@v3
-
-      - name: Build image
-        uses: docker/build-push-action@v6
-        with:
-          context: .
-          file: Dockerfile
-          load: true
-          tags: nousresearch/hermes-agent:test
-          cache-from: type=gha
-          cache-to: type=gha,mode=max
-
-      - name: Test image starts
-        run: |
-          docker run --rm \
-            -v /tmp/hermes-test:/opt/data \
-            --entrypoint /opt/hermes/docker/entrypoint.sh \
-            nousresearch/hermes-agent:test --help
-
-      - name: Log in to Docker Hub
-        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
-        uses: docker/login-action@v3
-        with:
-          username: ${{ secrets.DOCKERHUB_USERNAME }}
-          password: ${{ secrets.DOCKERHUB_TOKEN }}
-
-      - name: Push image
-        if: github.event_name == 'push' && github.ref == 'refs/heads/main'
-        uses: docker/build-push-action@v6
-        with:
-          context: .
-          file: Dockerfile
-          push: true
-          tags: |
-            nousresearch/hermes-agent:latest
-            nousresearch/hermes-agent:${{ github.sha }}
-          cache-from: type=gha
-          cache-to: type=gha,mode=max

.gitignore

@@ -58,3 +58,8 @@ mini-swe-agent/
 # Nix
 .direnv/
 result
+
+# Keystore (encrypted secrets — never commit)
+keystore/secrets.db
+keystore/.credential
+*.db-journal

AGENTS.md

@@ -57,13 +57,19 @@ hermes-agent/
 │   ├── session.py        # SessionStore — conversation persistence
 │   └── platforms/        # Adapters: telegram, discord, slack, whatsapp, homeassistant, signal
 ├── acp_adapter/          # ACP server (VS Code / Zed / JetBrains integration)
+├── keystore/             # Encrypted secret store (optional: pip install .[keystore])
+│   ├── store.py          # Core encrypted SQLite store (Argon2id + XChaCha20-Poly1305)
+│   ├── credential_store.py # Cross-platform passphrase caching (Keychain/DPAPI/keyctl/file)
+│   ├── client.py         # High-level API (unlock, inject_env, migrate)
+│   ├── categories.py     # Secret access categories (injectable/gated/sealed/user_only)
+│   └── cli.py            # `hermes keystore` subcommands
 ├── cron/                 # Scheduler (jobs.py, scheduler.py)
 ├── environments/         # RL training environments (Atropos)
 ├── tests/                # Pytest suite (~3000 tests)
 └── batch_runner.py       # Parallel batch processing
 ```
 
-**User config:** `~/.hermes/config.yaml` (settings), `~/.hermes/.env` (API keys)
+**User config:** `~/.hermes/config.yaml` (settings), `~/.hermes/.env` (API keys — or encrypted keystore if enabled)
 
 ## File Dependency Chain
 
@@ -210,10 +216,6 @@ registry.register(
 
 The registry handles schema collection, dispatch, availability checking, and error wrapping. All handlers MUST return a JSON string.
 
-**Path references in tool schemas**: If the schema description mentions file paths (e.g. default output directories), use `display_hermes_home()` to make them profile-aware. The schema is generated at import time, which is after `_apply_profile_override()` sets `HERMES_HOME`.
-
-**State files**: If a tool stores persistent state (caches, logs, checkpoints), use `get_hermes_home()` for the base directory — never `Path.home() / ".hermes"`. This ensures each profile gets its own state.
-
 **Agent-level tools** (todo, memory): intercepted by `run_agent.py` before `handle_function_call()`. See `todo_tool.py` for the pattern.
 
 ---
@@ -362,69 +364,8 @@ in config.yaml (or `HERMES_BACKGROUND_NOTIFICATIONS` env var):
 
 ---
 
-## Profiles: Multi-Instance Support
-
-Hermes supports **profiles** — multiple fully isolated instances, each with its own
-`HERMES_HOME` directory (config, API keys, memory, sessions, skills, gateway, etc.).
-
-The core mechanism: `_apply_profile_override()` in `hermes_cli/main.py` sets
-`HERMES_HOME` before any module imports. All 119+ references to `get_hermes_home()`
-automatically scope to the active profile.
-
-### Rules for profile-safe code
-
-1. **Use `get_hermes_home()` for all HERMES_HOME paths.** Import from `hermes_constants`.
-   NEVER hardcode `~/.hermes` or `Path.home() / ".hermes"` in code that reads/writes state.
-   ```python
-   # GOOD
-   from hermes_constants import get_hermes_home
-   config_path = get_hermes_home() / "config.yaml"
-
-   # BAD — breaks profiles
-   config_path = Path.home() / ".hermes" / "config.yaml"
-   ```
-
-2. **Use `display_hermes_home()` for user-facing messages.** Import from `hermes_constants`.
-   This returns `~/.hermes` for default or `~/.hermes/profiles/<name>` for profiles.
-   ```python
-   # GOOD
-   from hermes_constants import display_hermes_home
-   print(f"Config saved to {display_hermes_home()}/config.yaml")
-
-   # BAD — shows wrong path for profiles
-   print("Config saved to ~/.hermes/config.yaml")
-   ```
-
-3. **Module-level constants are fine** — they cache `get_hermes_home()` at import time,
-   which is AFTER `_apply_profile_override()` sets the env var. Just use `get_hermes_home()`,
-   not `Path.home() / ".hermes"`.
-
-4. **Tests that mock `Path.home()` must also set `HERMES_HOME`** — since code now uses
-   `get_hermes_home()` (reads env var), not `Path.home() / ".hermes"`:
-   ```python
-   with patch.object(Path, "home", return_value=tmp_path), \
-        patch.dict(os.environ, {"HERMES_HOME": str(tmp_path / ".hermes")}):
-       ...
-   ```
-
-5. **Gateway platform adapters should use token locks** — if the adapter connects with
-   a unique credential (bot token, API key), call `acquire_scoped_lock()` from
-   `gateway.status` in the `connect()`/`start()` method and `release_scoped_lock()` in
-   `disconnect()`/`stop()`. This prevents two profiles from using the same credential.
-   See `gateway/platforms/telegram.py` for the canonical pattern.
-
-6. **Profile operations are HOME-anchored, not HERMES_HOME-anchored** — `_get_profiles_root()`
-   returns `Path.home() / ".hermes" / "profiles"`, NOT `get_hermes_home() / "profiles"`.
-   This is intentional — it lets `hermes -p coder profile list` see all profiles regardless
-   of which one is active.
-
 ## Known Pitfalls
 
-### DO NOT hardcode `~/.hermes` paths
-Use `get_hermes_home()` from `hermes_constants` for code paths. Use `display_hermes_home()`
-for user-facing print/log messages. Hardcoding `~/.hermes` breaks profiles — each profile
-has its own `HERMES_HOME` directory. This was the source of 5 bugs fixed in PR #3575.
-
 ### DO NOT use `simple_term_menu` for interactive menus
 Rendering bugs in tmux/iTerm2 — ghosting on scroll. Use `curses` (stdlib) instead. See `hermes_cli/tools_config.py` for the pattern.
 
@@ -440,19 +381,6 @@ Tool schema descriptions must not mention tools from other toolsets by name (e.g
 ### Tests must not write to `~/.hermes/`
 The `_isolate_hermes_home` autouse fixture in `tests/conftest.py` redirects `HERMES_HOME` to a temp dir. Never hardcode `~/.hermes/` paths in tests.
 
-**Profile tests**: When testing profile features, also mock `Path.home()` so that
-`_get_profiles_root()` and `_get_default_hermes_home()` resolve within the temp dir.
-Use the pattern from `tests/hermes_cli/test_profiles.py`:
-```python
-@pytest.fixture
-def profile_env(tmp_path, monkeypatch):
-    home = tmp_path / ".hermes"
-    home.mkdir()
-    monkeypatch.setattr(Path, "home", lambda: tmp_path)
-    monkeypatch.setenv("HERMES_HOME", str(home))
-    return home
-```
-
 ---
 
 ## Testing

Dockerfile

@@ -1,20 +0,0 @@
-FROM debian:13.4
-
-RUN apt-get update
-RUN apt-get install -y nodejs npm python3 python3-pip ripgrep ffmpeg gcc python3-dev libffi-dev
-
-COPY . /opt/hermes
-WORKDIR /opt/hermes
-
-RUN pip install -e ".[all]" --break-system-packages
-RUN npm install
-RUN npx playwright install --with-deps chromium
-WORKDIR /opt/hermes/scripts/whatsapp-bridge
-RUN npm install
-
-WORKDIR /opt/hermes
-RUN chmod +x /opt/hermes/docker/entrypoint.sh
-
-ENV HERMES_HOME=/opt/data
-VOLUME [ "/opt/data" ]
-ENTRYPOINT [ "/opt/hermes/docker/entrypoint.sh" ]

README.md

@@ -99,6 +99,7 @@ All documentation lives at **[hermes-agent.nousresearch.com/docs](https://hermes
 | [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 |
+| [Wallet](https://hermes-agent.nousresearch.com/docs/user-guide/features/wallet) | Crypto wallet — keystore, transactions, policies, approval flow |
 | [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 |
@@ -106,6 +107,38 @@ All documentation lives at **[hermes-agent.nousresearch.com/docs](https://hermes
 
 ---
 
+## Crypto Wallet
+
+Give your agent its own wallet. Hermes can hold funds, check balances, and send transactions on Solana and EVM chains — with encrypted key storage and policy-controlled spending limits.
+
+```bash
+pip install 'hermes-agent[wallet]'          # EVM (Ethereum, Base, Polygon, etc.)
+pip install 'hermes-agent[wallet-solana]'    # + Solana support
+```
+
+**Quick start:**
+```bash
+hermes keystore init                         # Set a master passphrase (one-time)
+hermes wallet create --chain solana          # Create a fresh wallet
+hermes wallet fund                           # Shows the deposit address
+# Send some tokens to the address, then:
+hermes wallet balance                        # Check it arrived
+```
+
+Add `wallet` to your toolsets in `config.yaml` (or `hermes chat -t hermes-cli,wallet`), and the agent gets 7 tools: `wallet_list`, `wallet_balance`, `wallet_address`, `wallet_send`, `wallet_history`, `wallet_estimate_gas`, `wallet_networks`.
+
+**Key design:**
+- 🔐 Private keys are encrypted at rest (Argon2id + XSalsa20-Poly1305 via libsodium SecretBox) and never exposed to the agent
+- 📋 Policy engine enforces spending limits, rate limits, and approval thresholds
+- ✅ **User wallets** require owner approval for every transaction
+- 🤖 **Agent wallets** (`hermes wallet create-agent`) auto-approve within configurable limits
+- 🔒 Kill switch: `hermes wallet freeze` blocks everything instantly
+- 📦 Migration: `hermes wallet export` / `hermes wallet import` to move between machines
+
+See the [full wallet documentation](https://hermes-agent.nousresearch.com/docs/user-guide/features/wallet) for details.
+
+---
+
 ## Migrating from OpenClaw
 
 If you're coming from OpenClaw, Hermes can automatically import your settings, memories, skills, and API keys.

acp_adapter/entry.py

@@ -74,7 +74,7 @@ def main() -> None:
 
     agent = HermesACPAgent()
     try:
-        asyncio.run(acp.run_agent(agent, use_unstable_protocol=True))
+        asyncio.run(acp.run_agent(agent))
     except KeyboardInterrupt:
         logger.info("Shutting down (KeyboardInterrupt)")
     except Exception:

acp_adapter/server.py

@@ -25,9 +25,6 @@ from acp.schema import (
     NewSessionResponse,
     PromptResponse,
     ResumeSessionResponse,
-    SetSessionConfigOptionResponse,
-    SetSessionModelResponse,
-    SetSessionModeResponse,
     ResourceContentBlock,
     SessionCapabilities,
     SessionForkCapabilities,
@@ -97,14 +94,11 @@ class HermesACPAgent(acp.Agent):
 
     async def initialize(
         self,
-        protocol_version: int | None = None,
+        protocol_version: int,
         client_capabilities: ClientCapabilities | None = None,
         client_info: Implementation | None = None,
         **kwargs: Any,
     ) -> InitializeResponse:
-        resolved_protocol_version = (
-            protocol_version if isinstance(protocol_version, int) else acp.PROTOCOL_VERSION
-        )
         provider = detect_provider()
         auth_methods = None
         if provider:
@@ -117,11 +111,7 @@ class HermesACPAgent(acp.Agent):
             ]
 
         client_name = client_info.name if client_info else "unknown"
-        logger.info(
-            "Initialize from %s (protocol v%s)",
-            client_name,
-            resolved_protocol_version,
-        )
+        logger.info("Initialize from %s (protocol v%s)", client_name, protocol_version)
 
         return InitializeResponse(
             protocol_version=acp.PROTOCOL_VERSION,
@@ -481,7 +471,7 @@ class HermesACPAgent(acp.Agent):
 
     async def set_session_model(
         self, model_id: str, session_id: str, **kwargs: Any
-    ) -> SetSessionModelResponse | None:
+    ):
         """Switch the model for a session (called by ACP protocol)."""
         state = self.session_manager.get_session(session_id)
         if state:
@@ -499,37 +489,4 @@ class HermesACPAgent(acp.Agent):
             )
             self.session_manager.save_session(session_id)
             logger.info("Session %s: model switched to %s", session_id, model_id)
-            return SetSessionModelResponse()
-        logger.warning("Session %s: model switch requested for missing session", session_id)
         return None
-
-    async def set_session_mode(
-        self, mode_id: str, session_id: str, **kwargs: Any
-    ) -> SetSessionModeResponse | None:
-        """Persist the editor-requested mode so ACP clients do not fail on mode switches."""
-        state = self.session_manager.get_session(session_id)
-        if state is None:
-            logger.warning("Session %s: mode switch requested for missing session", session_id)
-            return None
-        setattr(state, "mode", mode_id)
-        self.session_manager.save_session(session_id)
-        logger.info("Session %s: mode switched to %s", session_id, mode_id)
-        return SetSessionModeResponse()
-
-    async def set_config_option(
-        self, config_id: str, session_id: str, value: str, **kwargs: Any
-    ) -> SetSessionConfigOptionResponse | None:
-        """Accept ACP config option updates even when Hermes has no typed ACP config surface yet."""
-        state = self.session_manager.get_session(session_id)
-        if state is None:
-            logger.warning("Session %s: config update requested for missing session", session_id)
-            return None
-
-        options = getattr(state, "config_options", None)
-        if not isinstance(options, dict):
-            options = {}
-        options[str(config_id)] = value
-        setattr(state, "config_options", options)
-        self.session_manager.save_session(session_id)
-        logger.info("Session %s: config option %s updated", session_id, config_id)
-        return SetSessionConfigOptionResponse(config_options=[])

agent/display.py

@@ -284,11 +284,11 @@ class KawaiiSpinner:
         The CLI already drives a TUI widget (_spinner_text) for spinner display,
         so KawaiiSpinner's \\r-based animation is redundant under StdoutProxy.
         """
-        try:
-            from prompt_toolkit.patch_stdout import StdoutProxy
-            return isinstance(self._out, StdoutProxy)
-        except ImportError:
-            return False
+        out = self._out
+        # StdoutProxy has a 'raw' attribute (bool) that plain file objects lack.
+        if hasattr(out, 'raw') and type(out).__name__ == 'StdoutProxy':
+            return True
+        return False
 
     def _animate(self):
         # When stdout is not a real terminal (e.g. Docker, systemd, pipe),

agent/prompt_builder.py

@@ -18,7 +18,6 @@ from typing import Optional
 from agent.skill_utils import (
     extract_skill_conditions,
     extract_skill_description,
-    get_all_skills_dirs,
     get_disabled_skill_names,
     iter_skill_index_files,
     parse_frontmatter,
@@ -445,23 +444,16 @@ def build_skills_system_prompt(
          mtime/size manifest — survives process restarts
 
     Falls back to a full filesystem scan when both layers miss.
-
-    External skill directories (``skills.external_dirs`` in config.yaml) are
-    scanned alongside the local ``~/.hermes/skills/`` directory.  External dirs
-    are read-only — they appear in the index but new skills are always created
-    in the local dir.  Local skills take precedence when names collide.
     """
     hermes_home = get_hermes_home()
     skills_dir = hermes_home / "skills"
-    external_dirs = get_all_skills_dirs()[1:]  # skip local (index 0)
 
-    if not skills_dir.exists() and not external_dirs:
+    if not skills_dir.exists():
         return ""
 
     # ── Layer 1: in-process LRU cache ─────────────────────────────────
     cache_key = (
         str(skills_dir.resolve()),
-        tuple(str(d) for d in external_dirs),
         tuple(sorted(str(t) for t in (available_tools or set()))),
         tuple(sorted(str(ts) for ts in (available_toolsets or set()))),
     )
@@ -548,56 +540,6 @@ def build_skills_system_prompt(
             category_descriptions,
         )
 
-    # ── External skill directories ─────────────────────────────────────
-    # Scan external dirs directly (no snapshot caching — they're read-only
-    # and typically small).  Local skills already in skills_by_category take
-    # precedence: we track seen names and skip duplicates from external dirs.
-    seen_skill_names: set[str] = set()
-    for cat_skills in skills_by_category.values():
-        for name, _desc in cat_skills:
-            seen_skill_names.add(name)
-
-    for ext_dir in external_dirs:
-        if not ext_dir.exists():
-            continue
-        for skill_file in iter_skill_index_files(ext_dir, "SKILL.md"):
-            try:
-                is_compatible, frontmatter, desc = _parse_skill_file(skill_file)
-                if not is_compatible:
-                    continue
-                entry = _build_snapshot_entry(skill_file, ext_dir, frontmatter, desc)
-                skill_name = entry["skill_name"]
-                if skill_name in seen_skill_names:
-                    continue
-                if entry["frontmatter_name"] in disabled or skill_name in disabled:
-                    continue
-                if not _skill_should_show(
-                    extract_skill_conditions(frontmatter),
-                    available_tools,
-                    available_toolsets,
-                ):
-                    continue
-                seen_skill_names.add(skill_name)
-                skills_by_category.setdefault(entry["category"], []).append(
-                    (skill_name, entry["description"])
-                )
-            except Exception as e:
-                logger.debug("Error reading external skill %s: %s", skill_file, e)
-
-        # External category descriptions
-        for desc_file in iter_skill_index_files(ext_dir, "DESCRIPTION.md"):
-            try:
-                content = desc_file.read_text(encoding="utf-8")
-                fm, _ = parse_frontmatter(content)
-                cat_desc = fm.get("description")
-                if not cat_desc:
-                    continue
-                rel = desc_file.relative_to(ext_dir)
-                cat = "/".join(rel.parts[:-1]) if len(rel.parts) > 1 else "general"
-                category_descriptions.setdefault(cat, str(cat_desc).strip().strip("'\""))
-            except Exception as e:
-                logger.debug("Could not read external skill description %s: %s", desc_file, e)
-
     if not skills_by_category:
         result = ""
     else:

agent/skill_commands.py

@@ -128,11 +128,7 @@ def _build_skill_message(
                         supporting.append(rel)
 
     if supporting and skill_dir:
-        try:
-            skill_view_target = str(skill_dir.relative_to(SKILLS_DIR))
-        except ValueError:
-            # Skill is from an external dir — use the skill name instead
-            skill_view_target = skill_dir.name
+        skill_view_target = str(skill_dir.relative_to(SKILLS_DIR))
         parts.append("")
         parts.append("[This skill has supporting files you can load with the skill_view tool:]")
         for sf in supporting:
@@ -162,49 +158,38 @@ def scan_skill_commands() -> Dict[str, Dict[str, Any]]:
     _skill_commands = {}
     try:
         from tools.skills_tool import SKILLS_DIR, _parse_frontmatter, skill_matches_platform, _get_disabled_skill_names
-        from agent.skill_utils import get_external_skills_dirs
+        if not SKILLS_DIR.exists():
+            return _skill_commands
         disabled = _get_disabled_skill_names()
-        seen_names: set = set()
-
-        # Scan local dir first, then external dirs
-        dirs_to_scan = []
-        if SKILLS_DIR.exists():
-            dirs_to_scan.append(SKILLS_DIR)
-        dirs_to_scan.extend(get_external_skills_dirs())
-
-        for scan_dir in dirs_to_scan:
-            for skill_md in scan_dir.rglob("SKILL.md"):
-                if any(part in ('.git', '.github', '.hub') for part in skill_md.parts):
+        for skill_md in SKILLS_DIR.rglob("SKILL.md"):
+            if any(part in ('.git', '.github', '.hub') for part in skill_md.parts):
+                continue
+            try:
+                content = skill_md.read_text(encoding='utf-8')
+                frontmatter, body = _parse_frontmatter(content)
+                # Skip skills incompatible with the current OS platform
+                if not skill_matches_platform(frontmatter):
                     continue
-                try:
-                    content = skill_md.read_text(encoding='utf-8')
-                    frontmatter, body = _parse_frontmatter(content)
-                    # Skip skills incompatible with the current OS platform
-                    if not skill_matches_platform(frontmatter):
-                        continue
-                    name = frontmatter.get('name', skill_md.parent.name)
-                    if name in seen_names:
-                        continue
-                    # Respect user's disabled skills config
-                    if name in disabled:
-                        continue
-                    description = frontmatter.get('description', '')
-                    if not description:
-                        for line in body.strip().split('\n'):
-                            line = line.strip()
-                            if line and not line.startswith('#'):
-                                description = line[:80]
-                                break
-                    seen_names.add(name)
-                    cmd_name = name.lower().replace(' ', '-').replace('_', '-')
-                    _skill_commands[f"/{cmd_name}"] = {
-                        "name": name,
-                        "description": description or f"Invoke the {name} skill",
-                        "skill_md_path": str(skill_md),
-                        "skill_dir": str(skill_md.parent),
-                    }
-                except Exception:
+                name = frontmatter.get('name', skill_md.parent.name)
+                # Respect user's disabled skills config
+                if name in disabled:
                     continue
+                description = frontmatter.get('description', '')
+                if not description:
+                    for line in body.strip().split('\n'):
+                        line = line.strip()
+                        if line and not line.startswith('#'):
+                            description = line[:80]
+                            break
+                cmd_name = name.lower().replace(' ', '-').replace('_', '-')
+                _skill_commands[f"/{cmd_name}"] = {
+                    "name": name,
+                    "description": description or f"Invoke the {name} skill",
+                    "skill_md_path": str(skill_md),
+                    "skill_dir": str(skill_md.parent),
+                }
+            except Exception:
+                continue
     except Exception:
         pass
     return _skill_commands

agent/skill_utils.py

@@ -158,73 +158,6 @@ def _normalize_string_set(values) -> Set[str]:
     return {str(v).strip() for v in values if str(v).strip()}
 
 
-# ── External skills directories ──────────────────────────────────────────
-
-
-def get_external_skills_dirs() -> List[Path]:
-    """Read ``skills.external_dirs`` from config.yaml and return validated paths.
-
-    Each entry is expanded (``~`` and ``${VAR}``) and resolved to an absolute
-    path.  Only directories that actually exist are returned.  Duplicates and
-    paths that resolve to the local ``~/.hermes/skills/`` are silently skipped.
-    """
-    config_path = get_hermes_home() / "config.yaml"
-    if not config_path.exists():
-        return []
-    try:
-        parsed = yaml_load(config_path.read_text(encoding="utf-8"))
-    except Exception:
-        return []
-    if not isinstance(parsed, dict):
-        return []
-
-    skills_cfg = parsed.get("skills")
-    if not isinstance(skills_cfg, dict):
-        return []
-
-    raw_dirs = skills_cfg.get("external_dirs")
-    if not raw_dirs:
-        return []
-    if isinstance(raw_dirs, str):
-        raw_dirs = [raw_dirs]
-    if not isinstance(raw_dirs, list):
-        return []
-
-    local_skills = (get_hermes_home() / "skills").resolve()
-    seen: Set[Path] = set()
-    result: List[Path] = []
-
-    for entry in raw_dirs:
-        entry = str(entry).strip()
-        if not entry:
-            continue
-        # Expand ~ and environment variables
-        expanded = os.path.expanduser(os.path.expandvars(entry))
-        p = Path(expanded).resolve()
-        if p == local_skills:
-            continue
-        if p in seen:
-            continue
-        if p.is_dir():
-            seen.add(p)
-            result.append(p)
-        else:
-            logger.debug("External skills dir does not exist, skipping: %s", p)
-
-    return result
-
-
-def get_all_skills_dirs() -> List[Path]:
-    """Return all skill directories: local ``~/.hermes/skills/`` first, then external.
-
-    The local dir is always first (and always included even if it doesn't exist
-    yet — callers handle that).  External dirs follow in config order.
-    """
-    dirs = [get_hermes_home() / "skills"]
-    dirs.extend(get_external_skills_dirs())
-    return dirs
-
-
 # ── Condition extraction ──────────────────────────────────────────────────
 
 

cli-config.yaml.example

@@ -402,15 +402,6 @@ skills:
   # Set to 0 to disable.
   creation_nudge_interval: 15
 
-  # External skill directories — share skills across tools/agents without
-  # copying them into ~/.hermes/skills/.  Each path is expanded (~ and ${VAR})
-  # and resolved to an absolute path.  External dirs are read-only: skill
-  # creation always writes to ~/.hermes/skills/.  Local skills take precedence
-  # when names collide.
-  # external_dirs:
-  #   - ~/.agents/skills
-  #   - /home/shared/team-skills
-
 # =============================================================================
 # Agent Behavior
 # =============================================================================

cli.py

@@ -70,7 +70,7 @@ _COMMAND_SPINNER_FRAMES = ("⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧
 
 # Load .env from ~/.hermes/.env first, then project root as dev fallback.
 # User-managed env files should override stale shell exports on restart.
-from hermes_constants import get_hermes_home, display_hermes_home, OPENROUTER_BASE_URL
+from hermes_constants import get_hermes_home, OPENROUTER_BASE_URL
 from hermes_cli.env_loader import load_hermes_dotenv
 
 _hermes_home = get_hermes_home()
@@ -1182,13 +1182,9 @@ class HermesCLI:
         self._provider_require_params = pr.get("require_parameters", False)
         self._provider_data_collection = pr.get("data_collection")
         
-        # Fallback provider chain — tried in order when primary fails after retries.
-        # Supports new list format (fallback_providers) and legacy single-dict (fallback_model).
-        fb = CLI_CONFIG.get("fallback_providers") or CLI_CONFIG.get("fallback_model") or []
-        # Normalize legacy single-dict to a one-element list
-        if isinstance(fb, dict):
-            fb = [fb] if fb.get("provider") and fb.get("model") else []
-        self._fallback_model = fb
+        # Fallback model config — tried when primary provider fails after retries
+        fb = CLI_CONFIG.get("fallback_model") or {}
+        self._fallback_model = fb if fb.get("provider") and fb.get("model") else None
 
         # Optional cheap-vs-strong routing for simple turns
         self._smart_model_routing = CLI_CONFIG.get("smart_model_routing", {}) or {}
@@ -3598,7 +3594,7 @@ class HermesCLI:
             print("  To start the gateway:")
             print("    python cli.py --gateway")
             print()
-            print(f"  Configuration file: {display_hermes_home()}/config.yaml")
+            print("  Configuration file: ~/.hermes/config.yaml")
             print()
             
         except Exception as e:
@@ -3608,7 +3604,7 @@ class HermesCLI:
             print("    1. Set environment variables:")
             print("       TELEGRAM_BOT_TOKEN=your_token")
             print("       DISCORD_BOT_TOKEN=your_token")
-            print(f"    2. Or configure settings in {display_hermes_home()}/config.yaml")
+            print("    2. Or configure settings in ~/.hermes/config.yaml")
             print()
     
     def process_command(self, command: str) -> bool:
@@ -3815,7 +3811,7 @@ class HermesCLI:
                 plugins = mgr.list_plugins()
                 if not plugins:
                     print("No plugins installed.")
-                    print(f"Drop plugin directories into {display_hermes_home()}/plugins/ to get started.")
+                    print("Drop plugin directories into ~/.hermes/plugins/ to get started.")
                 else:
                     print(f"Plugins ({len(plugins)}):")
                     for p in plugins:
@@ -4038,17 +4034,6 @@ class HermesCLI:
                     provider_data_collection=self._provider_data_collection,
                     fallback_model=self._fallback_model,
                 )
-                # Silence raw spinner; route thinking through TUI widget when no foreground agent is active.
-                bg_agent._print_fn = lambda *_a, **_kw: None
-
-                def _bg_thinking(text: str) -> None:
-                    # Concurrent bg tasks may race on _spinner_text; acceptable for best-effort UI.
-                    if not self._agent_running:
-                        self._spinner_text = text
-                        if self._app:
-                            self._app.invalidate()
-
-                bg_agent.thinking_callback = _bg_thinking
 
                 result = bg_agent.run_conversation(
                     user_message=prompt,
@@ -4111,9 +4096,6 @@ class HermesCLI:
                 _cprint(f"  ❌ Background task #{task_num} failed: {e}")
             finally:
                 self._background_tasks.pop(task_id, None)
-                # Clear spinner only if no foreground agent owns it
-                if not self._agent_running:
-                    self._spinner_text = ""
                 if self._app:
                     self._invalidate(min_interval=0)
 
@@ -4344,7 +4326,7 @@ class HermesCLI:
                 source = f" ({s['source']})" if s["source"] == "user" else ""
                 print(f"   {marker} {s['name']}{source} — {s['description']}")
             print("\n  Usage: /skin <name>")
-            print(f"  Custom skins: drop a YAML file in {display_hermes_home()}/skins/\n")
+            print("  Custom skins: drop a YAML file in ~/.hermes/skins/\n")
             return
 
         new_skin = parts[1].strip().lower()
@@ -5552,13 +5534,6 @@ class HermesCLI:
             except Exception as e:
                 logging.debug("@ context reference expansion failed: %s", e)
 
-        # Sanitize surrogate characters that can arrive via clipboard paste from
-        # rich-text editors (Google Docs, Word, etc.).  Lone surrogates are invalid
-        # UTF-8 and crash JSON serialization in the OpenAI SDK.
-        if isinstance(message, str):
-            from run_agent import _sanitize_surrogates
-            message = _sanitize_surrogates(message)
-
         # Add user message to history
         self.conversation_history.append({"role": "user", "content": message})
 
@@ -5729,6 +5704,37 @@ class HermesCLI:
             except Exception:
                 pass
 
+            # Check for pending wallet transaction approvals (like dangerous cmd approval)
+            try:
+                from wallet.approval import pop_pending as pop_wallet_pending
+                wallet_pending = pop_wallet_pending(self.session_id)
+                if wallet_pending:
+                    from hermes_cli.callbacks import wallet_approval_callback
+                    decision = wallet_approval_callback(self, wallet_pending)
+                    if decision == "approve":
+                        from wallet.approval import execute_approved
+                        tx_result_json = execute_approved(self.session_id, wallet_pending)
+                        import json as _json
+                        tx_result = _json.loads(tx_result_json)
+                        if tx_result.get("status") == "submitted":
+                            amt = tx_result.get("amount", "?")
+                            sym = tx_result.get("symbol", "?")
+                            tx_hash = tx_result.get("tx_hash", "")
+                            explorer = tx_result.get("explorer_url", "")
+                            _cprint(f"\n{_DIM}  ✅ Transaction sent: {amt} {sym}{_RST}")
+                            if tx_hash:
+                                _cprint(f"{_DIM}  TX: {tx_hash}{_RST}")
+                            if explorer:
+                                _cprint(f"{_DIM}  {explorer}{_RST}")
+                        else:
+                            _cprint(f"\n{_DIM}  ❌ Transaction failed: {tx_result.get('error', '?')}{_RST}")
+                    else:
+                        _cprint(f"\n{_DIM}  ❌ Transaction denied{_RST}")
+            except ImportError:
+                pass  # wallet not installed
+            except Exception as e:
+                logging.debug("Wallet approval check failed: %s", e)
+
             # Flush any remaining streamed text and close the box
             self._flush_stream()
 
@@ -5948,9 +5954,6 @@ class HermesCLI:
         ``normal_prompt`` is the full ``branding.prompt_symbol``.
         ``state_suffix`` is what special states (sudo/secret/approval/agent)
         should render after their leading icon.
-
-        When a profile is active (not "default"), the profile name is
-        prepended to the prompt symbol: ``coder ❯`` instead of ``❯``.
         """
         try:
             from hermes_cli.skin_engine import get_active_prompt_symbol
@@ -5959,15 +5962,6 @@ class HermesCLI:
             symbol = "❯ "
 
         symbol = (symbol or "❯ ").rstrip() + " "
-
-        # Prepend profile name when not default
-        try:
-            from hermes_cli.profiles import get_active_profile_name
-            profile = get_active_profile_name()
-            if profile not in ("default", "custom"):
-                symbol = f"{profile} {symbol}"
-        except Exception:
-            pass
         stripped = symbol.rstrip()
         if not stripped:
             return "❯ ", "❯ "
@@ -6119,7 +6113,7 @@ class HermesCLI:
             from honcho_integration.client import HonchoClientConfig
             from agent.display import honcho_session_line, write_tty
             hcfg = HonchoClientConfig.from_global_config()
-            if hcfg.enabled and (hcfg.api_key or hcfg.base_url) and hcfg.explicitly_configured:
+            if hcfg.enabled and hcfg.api_key and hcfg.explicitly_configured:
                 sname = hcfg.resolve_session_name(session_id=self.session_id)
                 if sname:
                     write_tty(honcho_session_line(hcfg.workspace_id, sname) + "\n")
@@ -6504,24 +6498,6 @@ class HermesCLI:
             self._should_exit = True
             event.app.exit()
 
-        @kb.add('c-z')
-        def handle_ctrl_z(event):
-            """Handle Ctrl+Z - suspend process to background (Unix only)."""
-            import sys
-            if sys.platform == 'win32':
-                _cprint(f"\n{_DIM}Suspend (Ctrl+Z) is not supported on Windows.{_RST}")
-                event.app.invalidate()
-                return
-            import os, signal as _sig
-            from prompt_toolkit.application import run_in_terminal
-            from hermes_cli.skin_engine import get_active_skin
-            agent_name = get_active_skin().get_branding("agent_name", "Hermes Agent")
-            msg = f"\n{agent_name} has been suspended. Run `fg` to bring {agent_name} back."
-            def _suspend():
-                os.write(1, msg.encode())
-                os.kill(0, _sig.SIGTSTP)
-            run_in_terminal(_suspend)
-
         # Voice push-to-talk key: configurable via config.yaml (voice.record_key)
         # Default: Ctrl+B (avoids conflict with Ctrl+R readline reverse-search)
         # Config uses "ctrl+b" format; prompt_toolkit expects "c-b" format.
@@ -6711,7 +6687,6 @@ class HermesCLI:
         # Paste collapsing: detect large pastes and save to temp file
         _paste_counter = [0]
         _prev_text_len = [0]
-        _prev_newline_count = [0]
         _paste_just_collapsed = [False]
 
         def _on_text_changed(buf):
@@ -6720,27 +6695,18 @@ class HermesCLI:
             When bracketed paste is available, handle_paste collapses
             large pastes directly.  This handler is a fallback for
             terminals without bracketed paste support.
-
-            Two heuristics (either triggers collapse):
-            1. Many characters added at once (chars_added > 1) — works
-               when the terminal delivers the paste in one event-loop tick.
-            2. Newline count jumped by 4+ in a single text-change event —
-               catches terminals that feed characters individually but
-               still batch newlines.  Alt+Enter only adds 1 newline per
-               event so it never triggers this.
             """
             text = buf.text
             chars_added = len(text) - _prev_text_len[0]
             _prev_text_len[0] = len(text)
             if _paste_just_collapsed[0]:
                 _paste_just_collapsed[0] = False
-                _prev_newline_count[0] = text.count('\n')
                 return
             line_count = text.count('\n')
-            newlines_added = line_count - _prev_newline_count[0]
-            _prev_newline_count[0] = line_count
-            is_paste = chars_added > 1 or newlines_added >= 4
-            if line_count >= 5 and is_paste and not text.startswith('/'):
+            # Heuristic: a real paste adds many characters at once (not just a
+            # single newline from Alt+Enter) AND the result has 5+ lines.
+            # Fallback for terminals without bracketed paste support.
+            if line_count >= 5 and chars_added > 1 and not text.startswith('/'):
                 _paste_counter[0] += 1
                 # Save to temp file
                 paste_dir = _hermes_home / "pastes"
@@ -6748,7 +6714,6 @@ class HermesCLI:
                 paste_file = paste_dir / f"paste_{_paste_counter[0]}_{datetime.now().strftime('%H%M%S')}.txt"
                 paste_file.write_text(text, encoding="utf-8")
                 # Replace buffer with compact reference
-                _paste_just_collapsed[0] = True
                 buf.text = f"[Pasted text #{_paste_counter[0]}: {line_count + 1} lines \u2192 {paste_file}]"
                 buf.cursor_position = len(buf.text)
 

cron/jobs.py

@@ -375,7 +375,6 @@ def create_job(
     model: Optional[str] = None,
     provider: Optional[str] = None,
     base_url: Optional[str] = None,
-    script: Optional[str] = None,
 ) -> Dict[str, Any]:
     """
     Create a new cron job.
@@ -449,8 +448,6 @@ def create_job(
         # Delivery configuration
         "deliver": deliver,
         "origin": origin,  # Tracks where job was created for "origin" delivery
-        # Script gate: optional bash script run before waking the agent
-        "script": script,
     }
 
     jobs = load_jobs()

cron/scheduler.py

@@ -12,9 +12,7 @@ import asyncio
 import json
 import logging
 import os
-import subprocess
 import sys
-import tempfile
 import traceback
 
 # fcntl is Unix-only; on Windows use msvcrt for file locking
@@ -28,7 +26,6 @@ except ImportError:
         msvcrt = None
 from pathlib import Path
 from hermes_constants import get_hermes_home
-from hermes_cli.config import load_config
 from typing import Optional
 
 from hermes_time import now as _hermes_now
@@ -167,29 +164,18 @@ def _deliver_result(job: dict, content: str) -> None:
         logger.warning("Job '%s': platform '%s' not configured/enabled", job["id"], platform_name)
         return
 
-    # Optionally wrap the content with a header/footer so the user knows this
-    # is a cron delivery.  Wrapping is on by default; set cron.wrap_response: false
-    # in config.yaml for clean output.
-    wrap_response = True
-    try:
-        user_cfg = load_config()
-        wrap_response = user_cfg.get("cron", {}).get("wrap_response", True)
-    except Exception:
-        pass
-
-    if wrap_response:
-        task_name = job.get("name", job["id"])
-        delivery_content = (
-            f"Cronjob Response: {task_name}\n"
-            f"-------------\n\n"
-            f"{content}\n\n"
-            f"Note: The agent cannot see this message, and therefore cannot respond to it."
-        )
-    else:
-        delivery_content = content
+    # Wrap the content so the user knows this is a cron delivery and that
+    # the interactive agent has no visibility into it.
+    task_name = job.get("name", job["id"])
+    wrapped = (
+        f"Cronjob Response: {task_name}\n"
+        f"-------------\n\n"
+        f"{content}\n\n"
+        f"Note: The agent cannot see this message, and therefore cannot respond to it."
+    )
 
     # Run the async send in a fresh event loop (safe from any thread)
-    coro = _send_to_platform(platform, pconfig, chat_id, delivery_content, thread_id=thread_id)
+    coro = _send_to_platform(platform, pconfig, chat_id, wrapped, thread_id=thread_id)
     try:
         result = asyncio.run(coro)
     except RuntimeError:
@@ -200,7 +186,7 @@ def _deliver_result(job: dict, content: str) -> None:
         coro.close()
         import concurrent.futures
         with concurrent.futures.ThreadPoolExecutor(max_workers=1) as pool:
-            future = pool.submit(asyncio.run, _send_to_platform(platform, pconfig, chat_id, delivery_content, thread_id=thread_id))
+            future = pool.submit(asyncio.run, _send_to_platform(platform, pconfig, chat_id, wrapped, thread_id=thread_id))
             result = future.result(timeout=30)
     except Exception as e:
         logger.error("Job '%s': delivery to %s:%s failed: %s", job["id"], platform_name, chat_id, e)
@@ -296,76 +282,6 @@ def run_job(job: dict) -> tuple[bool, str, str, Optional[str]]:
     origin = _resolve_origin(job)
     _cron_session_id = f"cron_{job_id}_{_hermes_now().strftime('%Y%m%d_%H%M%S')}"
 
-    # --- Script gate: run optional pre-check script before waking the agent ---
-    script_source = job.get("script")
-    if script_source:
-        try:
-            with tempfile.NamedTemporaryFile(
-                mode="w", suffix=".sh", delete=False
-            ) as tmp:
-                tmp.write(script_source)
-                tmp_path = tmp.name
-            try:
-                script_result = subprocess.run(
-                    ["bash", tmp_path],
-                    capture_output=True,
-                    text=True,
-                    timeout=30,
-                )
-            finally:
-                try:
-                    os.unlink(tmp_path)
-                except OSError:
-                    pass
-
-            # Parse the last non-empty line of stdout as JSON
-            stdout_lines = [
-                line for line in script_result.stdout.splitlines() if line.strip()
-            ]
-            if stdout_lines:
-                last_line = stdout_lines[-1].strip()
-                try:
-                    gate = json.loads(last_line)
-                    if isinstance(gate, dict):
-                        wake = gate.get("wakeAgent", True)
-                        if not wake:
-                            output_doc = (
-                                f"# Cron Job: {job_name}\n\n"
-                                f"**Job ID:** {job_id}\n"
-                                f"**Run Time:** {_hermes_now().strftime('%Y-%m-%d %H:%M:%S')}\n"
-                                f"**Schedule:** {job.get('schedule_display', 'N/A')}\n\n"
-                                f"## Script Gate\n\nAgent skipped by script gate.\n"
-                            )
-                            logger.info(
-                                "Job '%s': script gate returned wakeAgent=false, skipping agent",
-                                job_name,
-                            )
-                            return True, output_doc, "Script gate: agent skipped", None
-                        # wakeAgent is true — check for data to prepend
-                        data = gate.get("data")
-                        if data is not None:
-                            prompt = (
-                                f"Script pre-check data:\n{json.dumps(data)}\n\n{prompt}"
-                            )
-                except (json.JSONDecodeError, ValueError):
-                    logger.warning(
-                        "Job '%s': script gate output not valid JSON, proceeding normally: %s",
-                        job_name,
-                        last_line[:200],
-                    )
-        except subprocess.TimeoutExpired:
-            logger.warning(
-                "Job '%s': script gate timed out after 30s, proceeding normally",
-                job_name,
-            )
-        except Exception as e:
-            logger.warning(
-                "Job '%s': script gate error (%s), proceeding normally",
-                job_name,
-                e,
-            )
-    # --- End script gate ---
-
     logger.info("Running job '%s' (ID: %s)", job_name, job_id)
     logger.info("Prompt: %s", prompt[:100])
 

docker/SOUL.md

@@ -1,15 +0,0 @@
-# Hermes Agent Persona
-
-<!--
-This file defines the agent's personality and tone.
-The agent will embody whatever you write here.
-Edit this to customize how Hermes communicates with you.
-
-Examples:
-  - "You are a warm, playful assistant who uses kaomoji occasionally."
-  - "You are a concise technical expert. No fluff, just facts."
-  - "You speak like a friendly coworker who happens to know everything."
-
-This file is loaded fresh each message -- no restart needed.
-Delete the contents (or this file) to use the default personality.
--->

docker/entrypoint.sh

@@ -1,34 +0,0 @@
-#!/bin/bash
-# Docker entrypoint: bootstrap config files into the mounted volume, then run hermes.
-set -e
-
-HERMES_HOME="/opt/data"
-INSTALL_DIR="/opt/hermes"
-
-# Create essential directory structure.  Cache and platform directories
-# (cache/images, cache/audio, platforms/whatsapp, etc.) are created on
-# demand by the application — don't pre-create them here so new installs
-# get the consolidated layout from get_hermes_dir().
-mkdir -p "$HERMES_HOME"/{cron,sessions,logs,hooks,memories,skills}
-
-# .env
-if [ ! -f "$HERMES_HOME/.env" ]; then
-    cp "$INSTALL_DIR/.env.example" "$HERMES_HOME/.env"
-fi
-
-# config.yaml
-if [ ! -f "$HERMES_HOME/config.yaml" ]; then
-    cp "$INSTALL_DIR/cli-config.yaml.example" "$HERMES_HOME/config.yaml"
-fi
-
-# SOUL.md
-if [ ! -f "$HERMES_HOME/SOUL.md" ]; then
-    cp "$INSTALL_DIR/docker/SOUL.md" "$HERMES_HOME/SOUL.md"
-fi
-
-# Sync bundled skills (manifest-based so user edits are preserved)
-if [ -d "$INSTALL_DIR/skills" ]; then
-    python3 "$INSTALL_DIR/tools/skills_sync.py"
-fi
-
-exec hermes "$@"

docs/wallet.md

@@ -0,0 +1,83 @@
+# Wallet & Keystore
+
+## Overview
+
+Hermes Agent includes an optional crypto wallet with an encrypted keystore. The agent can hold funds, check balances, and send native tokens on Solana and EVM chains — with policy-controlled spending limits and owner approval for transactions.
+
+## Install
+
+```bash
+pip install 'hermes-agent[wallet]'          # EVM chains
+pip install 'hermes-agent[wallet-solana]'    # + Solana
+```
+
+## Quick Start
+
+```bash
+hermes keystore init                         # Set master passphrase
+hermes wallet create --chain solana          # Create wallet
+hermes wallet fund                           # Show deposit address
+hermes wallet balance                        # Check balance
+```
+
+Enable the `wallet` toolset in `config.yaml` or via `hermes chat -t hermes-cli,wallet`.
+
+## Wallet CLI
+
+| Command | Description |
+|---------|-------------|
+| `hermes wallet create --chain <chain>` | Create a fresh user wallet |
+| `hermes wallet create-agent --chain <chain>` | Create agent wallet (auto-approve within limits) |
+| `hermes wallet import --chain <chain>` | Import from exported private key |
+| `hermes wallet export` | Export private key for migration |
+| `hermes wallet list` | List wallets + balances |
+| `hermes wallet balance` | Check balance |
+| `hermes wallet send <to> <amount>` | Send tokens (interactive confirmation) |
+| `hermes wallet fund` | Show deposit address |
+| `hermes wallet history` | Transaction history |
+| `hermes wallet freeze` | Kill switch — block everything |
+| `hermes wallet unfreeze` | Resume after freeze |
+| `hermes wallet status` | Wallet overview |
+
+## Keystore CLI
+
+| Command | Description |
+|---------|-------------|
+| `hermes keystore init` | Create encrypted keystore |
+| `hermes keystore list` | List secrets (names only) |
+| `hermes keystore set <name>` | Add/update a secret |
+| `hermes keystore show <name>` | Decrypt and display |
+| `hermes keystore delete <name>` | Remove a secret |
+| `hermes keystore migrate` | Import from `.env` |
+| `hermes keystore remember` | Cache passphrase in OS credential store (no insecure file fallback) |
+| `hermes keystore forget` | Remove cached passphrase |
+| `hermes keystore change-passphrase` | Re-encrypt everything |
+| `hermes keystore audit` | Access log |
+
+## Agent Tools
+
+| Tool | Description |
+|------|-------------|
+| `wallet_list` | List wallets + balances |
+| `wallet_balance` | Check specific balance |
+| `wallet_address` | Get deposit address |
+| `wallet_send` | Send tokens (policy-gated) |
+| `wallet_estimate_gas` | Fee estimation |
+| `wallet_history` | Transaction log |
+| `wallet_networks` | Supported chains |
+
+## Security
+
+- **Encryption:** Argon2id KDF + XSalsa20-Poly1305 per-secret AEAD (libsodium SecretBox)
+- **Agent never sees keys:** Private keys are `sealed` — the agent uses tools, not keys
+- **Policies:** Spending limits, rate limits, daily caps, approval thresholds, recipient lists
+- **User wallets:** Every transaction requires owner approval
+- **Agent wallets:** Auto-approve within limits, escalate above threshold
+- **Kill switch:** `hermes wallet freeze` — instant, no exceptions
+
+## Supported Chains
+
+**Mainnet:** Ethereum, Base, Polygon, Arbitrum, Optimism, Solana  
+**Testnet:** Ethereum Sepolia, Base Sepolia, Solana Devnet
+
+Custom RPC endpoints via `wallet.rpc_endpoints` in `config.yaml`.

environments/benchmarks/terminalbench_2/terminalbench2_env.py

@@ -209,7 +209,7 @@ class TerminalBench2EvalEnv(HermesAgentBaseEnv):
 
             # Agent settings -- TB2 tasks are complex, need many turns
             max_agent_turns=60,
-            max_token_length=16000,
+            max_token_length=***
             agent_temperature=0.6,
             system_prompt=None,
 
@@ -233,7 +233,7 @@ class TerminalBench2EvalEnv(HermesAgentBaseEnv):
             steps_per_eval=1,
             total_steps=1,
 
-            tokenizer_name="NousResearch/Hermes-3-Llama-3.1-8B",
+            tokenizer_name="NousRe...1-8B",
             use_wandb=True,
             wandb_name="terminal-bench-2",
             ensure_scores_are_not_same=False,  # Binary rewards may all be 0 or 1
@@ -245,7 +245,7 @@ class TerminalBench2EvalEnv(HermesAgentBaseEnv):
                 base_url="https://openrouter.ai/api/v1",
                 model_name="anthropic/claude-sonnet-4",
                 server_type="openai",
-                api_key=os.getenv("OPENROUTER_API_KEY", ""),
+                api_key=os.get...EY", ""),
                 health_check=False,
             )
         ]
@@ -513,446 +513,3 @@ class TerminalBench2EvalEnv(HermesAgentBaseEnv):
                 reward = 0.0
             else:
                 # Run tests in a thread so the blocking ctx.terminal() calls
-                # don't freeze the entire event loop (which would stall all
-                # other tasks, tqdm updates, and timeout timers).
-                ctx = ToolContext(task_id)
-                try:
-                    loop = asyncio.get_event_loop()
-                    reward = await loop.run_in_executor(
-                        None,  # default thread pool
-                        self._run_tests, eval_item, ctx, task_name,
-                    )
-                except Exception as e:
-                    logger.error("Task %s: test verification failed: %s", task_name, e)
-                    reward = 0.0
-                finally:
-                    ctx.cleanup()
-
-            passed = reward == 1.0
-            status = "PASS" if passed else "FAIL"
-            elapsed = time.time() - task_start
-            tqdm.write(f"  [{status}] {task_name} (turns={result.turns_used}, {elapsed:.0f}s)")
-            logger.info(
-                "Task %s: reward=%.1f, turns=%d, finished=%s",
-                task_name, reward, result.turns_used, result.finished_naturally,
-            )
-
-            out = {
-                "passed": passed,
-                "reward": reward,
-                "task_name": task_name,
-                "category": category,
-                "turns_used": result.turns_used,
-                "finished_naturally": result.finished_naturally,
-                "messages": result.messages,
-            }
-            self._save_result(out)
-            return out
-
-        except Exception as e:
-            elapsed = time.time() - task_start
-            logger.error("Task %s: rollout failed: %s", task_name, e, exc_info=True)
-            tqdm.write(f"  [ERROR] {task_name}: {e} ({elapsed:.0f}s)")
-            out = {
-                "passed": False, "reward": 0.0,
-                "task_name": task_name, "category": category,
-                "error": str(e),
-            }
-            self._save_result(out)
-            return out
-
-        finally:
-            # --- Cleanup: clear overrides, sandbox, and temp files ---
-            clear_task_env_overrides(task_id)
-            try:
-                cleanup_vm(task_id)
-            except Exception as e:
-                logger.debug("VM cleanup for %s: %s", task_id[:8], e)
-            if task_dir and task_dir.exists():
-                shutil.rmtree(task_dir, ignore_errors=True)
-
-    def _run_tests(
-        self, item: Dict[str, Any], ctx: ToolContext, task_name: str
-    ) -> float:
-        """
-        Upload and execute the test suite in the agent's sandbox, then
-        download the verifier output locally to read the reward.
-
-        Follows Harbor's verification pattern:
-        1. Upload tests/ directory into the sandbox
-        2. Execute test.sh inside the sandbox
-        3. Download /logs/verifier/ directory to a local temp dir
-        4. Read reward.txt locally with native Python I/O
-
-        Downloading locally avoids issues with the file_read tool on
-        the Modal VM and matches how Harbor handles verification.
-
-        TB2 test scripts (test.sh) typically:
-        1. Install pytest via uv/pip
-        2. Run pytest against the test files in /tests/
-        3. Write results to /logs/verifier/reward.txt
-
-        Args:
-            item: The TB2 task dict (contains tests_tar, test_sh)
-            ctx: ToolContext scoped to this task's sandbox
-            task_name: For logging
-
-        Returns:
-            1.0 if tests pass, 0.0 otherwise
-        """
-        tests_tar = item.get("tests_tar", "")
-        test_sh = item.get("test_sh", "")
-
-        if not test_sh:
-            logger.warning("Task %s: no test_sh content, reward=0", task_name)
-            return 0.0
-
-        # Create required directories in the sandbox
-        ctx.terminal("mkdir -p /tests /logs/verifier")
-
-        # Upload test files into the sandbox (binary-safe via base64)
-        if tests_tar:
-            tests_temp = Path(tempfile.mkdtemp(prefix=f"tb2-tests-{task_name}-"))
-            try:
-                _extract_base64_tar(tests_tar, tests_temp)
-                ctx.upload_dir(str(tests_temp), "/tests")
-            except Exception as e:
-                logger.warning("Task %s: failed to upload test files: %s", task_name, e)
-            finally:
-                shutil.rmtree(tests_temp, ignore_errors=True)
-
-        # Write the test runner script (test.sh)
-        ctx.write_file("/tests/test.sh", test_sh)
-        ctx.terminal("chmod +x /tests/test.sh")
-
-        # Execute the test suite
-        logger.info(
-            "Task %s: running test suite (timeout=%ds)",
-            task_name, self.config.test_timeout,
-        )
-        test_result = ctx.terminal(
-            "bash /tests/test.sh",
-            timeout=self.config.test_timeout,
-        )
-
-        exit_code = test_result.get("exit_code", -1)
-        output = test_result.get("output", "")
-
-        # Download the verifier output directory locally, then read reward.txt
-        # with native Python I/O. This avoids issues with file_read on the
-        # Modal VM and matches Harbor's verification pattern.
-        reward = 0.0
-        local_verifier_dir = Path(tempfile.mkdtemp(prefix=f"tb2-verifier-{task_name}-"))
-        try:
-            ctx.download_dir("/logs/verifier", str(local_verifier_dir))
-
-            reward_file = local_verifier_dir / "reward.txt"
-            if reward_file.exists() and reward_file.stat().st_size > 0:
-                content = reward_file.read_text().strip()
-                if content == "1":
-                    reward = 1.0
-                elif content == "0":
-                    reward = 0.0
-                else:
-                    # Unexpected content -- try parsing as float
-                    try:
-                        reward = float(content)
-                    except (ValueError, TypeError):
-                        logger.warning(
-                            "Task %s: reward.txt content unexpected (%r), "
-                            "falling back to exit_code=%d",
-                            task_name, content, exit_code,
-                        )
-                        reward = 1.0 if exit_code == 0 else 0.0
-            else:
-                # reward.txt not written -- fall back to exit code
-                logger.warning(
-                    "Task %s: reward.txt not found after download, "
-                    "falling back to exit_code=%d",
-                    task_name, exit_code,
-                )
-                reward = 1.0 if exit_code == 0 else 0.0
-        except Exception as e:
-            logger.warning(
-                "Task %s: failed to download verifier dir: %s, "
-                "falling back to exit_code=%d",
-                task_name, e, exit_code,
-            )
-            reward = 1.0 if exit_code == 0 else 0.0
-        finally:
-            shutil.rmtree(local_verifier_dir, ignore_errors=True)
-
-        # Log test output for debugging failures
-        if reward == 0.0:
-            output_preview = output[-500:] if output else "(no output)"
-            logger.info(
-                "Task %s: FAIL (exit_code=%d)\n%s",
-                task_name, exit_code, output_preview,
-            )
-
-        return reward
-
-    # =========================================================================
-    # Evaluate -- main entry point for the eval subcommand
-    # =========================================================================
-
-    async def _eval_with_timeout(self, item: Dict[str, Any]) -> Dict:
-        """
-        Wrap rollout_and_score_eval with a per-task wall-clock timeout.
-
-        If the task exceeds task_timeout seconds, it's automatically scored
-        as FAIL. This prevents any single task from hanging indefinitely.
-        """
-        task_name = item.get("task_name", "unknown")
-        category = item.get("category", "unknown")
-        try:
-            return await asyncio.wait_for(
-                self.rollout_and_score_eval(item),
-                timeout=self.config.task_timeout,
-            )
-        except asyncio.TimeoutError:
-            from tqdm import tqdm
-            elapsed = self.config.task_timeout
-            tqdm.write(f"  [TIMEOUT] {task_name} (exceeded {elapsed}s wall-clock limit)")
-            logger.error("Task %s: wall-clock timeout after %ds", task_name, elapsed)
-            out = {
-                "passed": False, "reward": 0.0,
-                "task_name": task_name, "category": category,
-                "error": f"timeout ({elapsed}s)",
-            }
-            self._save_result(out)
-            return out
-
-    async def evaluate(self, *args, **kwargs) -> None:
-        """
-        Run Terminal-Bench 2.0 evaluation over all tasks.
-
-        This is the main entry point when invoked via:
-            python environments/terminalbench2_env.py evaluate
-
-        Runs all tasks through rollout_and_score_eval() via asyncio.gather()
-        (same pattern as GPQA and other Atropos eval envs). Each task is
-        wrapped with a wall-clock timeout so hung tasks auto-fail.
-
-        Suppresses noisy Modal/terminal output (HERMES_QUIET) so the tqdm
-        bar stays visible.
-        """
-        start_time = time.time()
-
-        # Route all logging through tqdm.write() so the progress bar stays
-        # pinned at the bottom while log lines scroll above it.
-        from tqdm import tqdm
-
-        class _TqdmHandler(logging.Handler):
-            def emit(self, record):
-                try:
-                    tqdm.write(self.format(record))
-                except Exception:
-                    self.handleError(record)
-
-        handler = _TqdmHandler()
-        handler.setFormatter(logging.Formatter(
-            "%(asctime)s [%(name)s] %(levelname)s: %(message)s",
-            datefmt="%H:%M:%S",
-        ))
-        root = logging.getLogger()
-        root.handlers = [handler]  # Replace any existing handlers
-        root.setLevel(logging.INFO)
-
-        # Silence noisy third-party loggers that flood the output
-        logging.getLogger("httpx").setLevel(logging.WARNING)      # Every HTTP request
-        logging.getLogger("openai").setLevel(logging.WARNING)     # OpenAI client retries
-        logging.getLogger("rex-deploy").setLevel(logging.WARNING) # Swerex deployment
-        logging.getLogger("rex_image_builder").setLevel(logging.WARNING)  # Image builds
-
-        print(f"\n{'='*60}")
-        print("Starting Terminal-Bench 2.0 Evaluation")
-        print(f"{'='*60}")
-        print(f"  Dataset: {self.config.dataset_name}")
-        print(f"  Total tasks: {len(self.all_eval_items)}")
-        print(f"  Max agent turns: {self.config.max_agent_turns}")
-        print(f"  Task timeout: {self.config.task_timeout}s")
-        print(f"  Terminal backend: {self.config.terminal_backend}")
-        print(f"  Tool thread pool: {self.config.tool_pool_size}")
-        print(f"  Terminal timeout: {self.config.terminal_timeout}s/cmd")
-        print(f"  Terminal lifetime: {self.config.terminal_lifetime}s (auto: task_timeout + 120)")
-        print(f"  Max concurrent tasks: {self.config.max_concurrent_tasks}")
-        print(f"{'='*60}\n")
-
-        # Semaphore to limit concurrent Modal sandbox creations.
-        # Without this, all 86 tasks fire simultaneously, each creating a Modal
-        # sandbox via asyncio.run() inside a thread pool worker. Modal's blocking
-        # calls (App.lookup, etc.) deadlock when too many are created at once.
-        semaphore = asyncio.Semaphore(self.config.max_concurrent_tasks)
-
-        async def _eval_with_semaphore(item):
-            async with semaphore:
-                return await self._eval_with_timeout(item)
-
-        # Fire all tasks with wall-clock timeout, track live accuracy on the bar
-        total_tasks = len(self.all_eval_items)
-        eval_tasks = [
-            asyncio.ensure_future(_eval_with_semaphore(item))
-            for item in self.all_eval_items
-        ]
-
-        results = []
-        passed_count = 0
-        pbar = tqdm(total=total_tasks, desc="Evaluating TB2", dynamic_ncols=True)
-        try:
-            for coro in asyncio.as_completed(eval_tasks):
-                result = await coro
-                results.append(result)
-                if result and result.get("passed"):
-                    passed_count += 1
-                done = len(results)
-                pct = (passed_count / done * 100) if done else 0
-                pbar.set_postfix_str(f"pass={passed_count}/{done} ({pct:.1f}%)")
-                pbar.update(1)
-        except (KeyboardInterrupt, asyncio.CancelledError):
-            pbar.close()
-            print(f"\n\nInterrupted! Cleaning up {len(eval_tasks)} tasks...")
-            # Cancel all pending tasks
-            for task in eval_tasks:
-                task.cancel()
-            # Let cancellations propagate (finally blocks run cleanup_vm)
-            await asyncio.gather(*eval_tasks, return_exceptions=True)
-            # Belt-and-suspenders: clean up any remaining sandboxes
-            from tools.terminal_tool import cleanup_all_environments
-            cleanup_all_environments()
-            print("All sandboxes cleaned up.")
-            return
-        finally:
-            pbar.close()
-
-        end_time = time.time()
-
-        # Filter out None results (shouldn't happen, but be safe)
-        valid_results = [r for r in results if r is not None]
-
-        if not valid_results:
-            print("Warning: No valid evaluation results obtained")
-            return
-
-        # ---- Compute metrics ----
-        total = len(valid_results)
-        passed = sum(1 for r in valid_results if r.get("passed"))
-        overall_pass_rate = passed / total if total > 0 else 0.0
-
-        # Per-category breakdown
-        cat_results: Dict[str, List[Dict]] = defaultdict(list)
-        for r in valid_results:
-            cat_results[r.get("category", "unknown")].append(r)
-
-        # Build metrics dict
-        eval_metrics = {
-            "eval/pass_rate": overall_pass_rate,
-            "eval/total_tasks": total,
-            "eval/passed_tasks": passed,
-            "eval/evaluation_time_seconds": end_time - start_time,
-        }
-
-        # Per-category metrics
-        for category, cat_items in sorted(cat_results.items()):
-            cat_passed = sum(1 for r in cat_items if r.get("passed"))
-            cat_total = len(cat_items)
-            cat_pass_rate = cat_passed / cat_total if cat_total > 0 else 0.0
-            cat_key = category.replace(" ", "_").replace("-", "_").lower()
-            eval_metrics[f"eval/pass_rate_{cat_key}"] = cat_pass_rate
-
-        # Store metrics for wandb_log
-        self.eval_metrics = [(k, v) for k, v in eval_metrics.items()]
-
-        # ---- Print summary ----
-        print(f"\n{'='*60}")
-        print("Terminal-Bench 2.0 Evaluation Results")
-        print(f"{'='*60}")
-        print(f"Overall Pass Rate: {overall_pass_rate:.4f} ({passed}/{total})")
-        print(f"Evaluation Time: {end_time - start_time:.1f} seconds")
-
-        print("\nCategory Breakdown:")
-        for category, cat_items in sorted(cat_results.items()):
-            cat_passed = sum(1 for r in cat_items if r.get("passed"))
-            cat_total = len(cat_items)
-            cat_rate = cat_passed / cat_total if cat_total > 0 else 0.0
-            print(f"  {category}: {cat_rate:.1%} ({cat_passed}/{cat_total})")
-
-        # Print individual task results
-        print("\nTask Results:")
-        for r in sorted(valid_results, key=lambda x: x.get("task_name", "")):
-            status = "PASS" if r.get("passed") else "FAIL"
-            turns = r.get("turns_used", "?")
-            error = r.get("error", "")
-            extra = f" (error: {error})" if error else ""
-            print(f"  [{status}] {r['task_name']} (turns={turns}){extra}")
-
-        print(f"{'='*60}\n")
-
-        # Build sample records for evaluate_log (includes full conversations)
-        samples = [
-            {
-                "task_name": r.get("task_name"),
-                "category": r.get("category"),
-                "passed": r.get("passed"),
-                "reward": r.get("reward"),
-                "turns_used": r.get("turns_used"),
-                "error": r.get("error"),
-                "messages": r.get("messages"),
-            }
-            for r in valid_results
-        ]
-
-        # Log evaluation results
-        try:
-            await self.evaluate_log(
-                metrics=eval_metrics,
-                samples=samples,
-                start_time=start_time,
-                end_time=end_time,
-                generation_parameters={
-                    "temperature": self.config.agent_temperature,
-                    "max_tokens": self.config.max_token_length,
-                    "max_agent_turns": self.config.max_agent_turns,
-                    "terminal_backend": self.config.terminal_backend,
-                },
-            )
-        except Exception as e:
-            print(f"Error logging evaluation results: {e}")
-
-        # Close streaming file
-        if hasattr(self, "_streaming_file") and not self._streaming_file.closed:
-            self._streaming_file.close()
-            print(f"  Live results saved to: {self._streaming_path}")
-
-        # Kill all remaining sandboxes. Timed-out tasks leave orphaned thread
-        # pool workers still executing commands -- cleanup_all stops them.
-        from tools.terminal_tool import cleanup_all_environments
-        print("\nCleaning up all sandboxes...")
-        cleanup_all_environments()
-
-        # Shut down the tool thread pool so orphaned workers from timed-out
-        # tasks are killed immediately instead of retrying against dead
-        # sandboxes and spamming the console with TimeoutError warnings.
-        from environments.agent_loop import _tool_executor
-        _tool_executor.shutdown(wait=False, cancel_futures=True)
-        print("Done.")
-
-    # =========================================================================
-    # Wandb logging
-    # =========================================================================
-
-    async def wandb_log(self, wandb_metrics: Optional[Dict] = None):
-        """Log TB2-specific metrics to wandb."""
-        if wandb_metrics is None:
-            wandb_metrics = {}
-
-        # Add stored eval metrics
-        for metric_name, metric_value in self.eval_metrics:
-            wandb_metrics[metric_name] = metric_value
-        self.eval_metrics = []
-
-        await super().wandb_log(wandb_metrics)
-
-
-if __name__ == "__main__":
-    TerminalBench2EvalEnv.cli()

gateway/builtin_hooks/__init__.py

@@ -1 +0,0 @@
-"""Built-in gateway hooks that are always registered."""

gateway/builtin_hooks/boot_md.py

@@ -1,86 +0,0 @@
-"""Built-in boot-md hook — run ~/.hermes/BOOT.md on gateway startup.
-
-This hook is always registered. It silently skips if no BOOT.md exists.
-To activate, create ``~/.hermes/BOOT.md`` with instructions for the
-agent to execute on every gateway restart.
-
-Example BOOT.md::
-
-    # Startup Checklist
-
-    1. Check if any cron jobs failed overnight
-    2. Send a status update to Discord #general
-    3. If there are errors in /opt/app/deploy.log, summarize them
-
-The agent runs in a background thread so it doesn't block gateway
-startup. If nothing needs attention, it replies with [SILENT] to
-suppress delivery.
-"""
-
-import logging
-import os
-import threading
-from pathlib import Path
-
-logger = logging.getLogger("hooks.boot-md")
-
-HERMES_HOME = Path(os.environ.get("HERMES_HOME", Path.home() / ".hermes"))
-BOOT_FILE = HERMES_HOME / "BOOT.md"
-
-
-def _build_boot_prompt(content: str) -> str:
-    """Wrap BOOT.md content in a system-level instruction."""
-    return (
-        "You are running a startup boot checklist. Follow the BOOT.md "
-        "instructions below exactly.\n\n"
-        "---\n"
-        f"{content}\n"
-        "---\n\n"
-        "Execute each instruction. If you need to send a message to a "
-        "platform, use the send_message tool.\n"
-        "If nothing needs attention and there is nothing to report, "
-        "reply with ONLY: [SILENT]"
-    )
-
-
-def _run_boot_agent(content: str) -> None:
-    """Spawn a one-shot agent session to execute the boot instructions."""
-    try:
-        from run_agent import AIAgent
-
-        prompt = _build_boot_prompt(content)
-        agent = AIAgent(
-            quiet_mode=True,
-            skip_context_files=True,
-            skip_memory=True,
-            max_iterations=20,
-        )
-        result = agent.run_conversation(prompt)
-        response = result.get("final_response", "")
-        if response and "[SILENT]" not in response:
-            logger.info("boot-md completed: %s", response[:200])
-        else:
-            logger.info("boot-md completed (nothing to report)")
-    except Exception as e:
-        logger.error("boot-md agent failed: %s", e)
-
-
-async def handle(event_type: str, context: dict) -> None:
-    """Gateway startup handler — run BOOT.md if it exists."""
-    if not BOOT_FILE.exists():
-        return
-
-    content = BOOT_FILE.read_text(encoding="utf-8").strip()
-    if not content:
-        return
-
-    logger.info("Running BOOT.md (%d chars)", len(content))
-
-    # Run in a background thread so we don't block gateway startup.
-    thread = threading.Thread(
-        target=_run_boot_agent,
-        args=(content,),
-        name="boot-md",
-        daemon=True,
-    )
-    thread.start()

gateway/config.py

@@ -647,13 +647,14 @@ def _apply_env_overrides(config: GatewayConfig) -> None:
             config.platforms[Platform.SLACK] = PlatformConfig()
         config.platforms[Platform.SLACK].enabled = True
         config.platforms[Platform.SLACK].token = slack_token
-    slack_home = os.getenv("SLACK_HOME_CHANNEL")
-    if slack_home and Platform.SLACK in config.platforms:
-        config.platforms[Platform.SLACK].home_channel = HomeChannel(
-            platform=Platform.SLACK,
-            chat_id=slack_home,
-            name=os.getenv("SLACK_HOME_CHANNEL_NAME", ""),
-        )
+        # Home channel
+        slack_home = os.getenv("SLACK_HOME_CHANNEL")
+        if slack_home:
+            config.platforms[Platform.SLACK].home_channel = HomeChannel(
+                platform=Platform.SLACK,
+                chat_id=slack_home,
+                name=os.getenv("SLACK_HOME_CHANNEL_NAME", ""),
+            )
     
     # Signal
     signal_url = os.getenv("SIGNAL_HTTP_URL")
@@ -667,13 +668,13 @@ def _apply_env_overrides(config: GatewayConfig) -> None:
             "account": signal_account,
             "ignore_stories": os.getenv("SIGNAL_IGNORE_STORIES", "true").lower() in ("true", "1", "yes"),
         })
-    signal_home = os.getenv("SIGNAL_HOME_CHANNEL")
-    if signal_home and Platform.SIGNAL in config.platforms:
-        config.platforms[Platform.SIGNAL].home_channel = HomeChannel(
-            platform=Platform.SIGNAL,
-            chat_id=signal_home,
-            name=os.getenv("SIGNAL_HOME_CHANNEL_NAME", "Home"),
-        )
+        signal_home = os.getenv("SIGNAL_HOME_CHANNEL")
+        if signal_home:
+            config.platforms[Platform.SIGNAL].home_channel = HomeChannel(
+                platform=Platform.SIGNAL,
+                chat_id=signal_home,
+                name=os.getenv("SIGNAL_HOME_CHANNEL_NAME", "Home"),
+            )
 
     # Mattermost
     mattermost_token = os.getenv("MATTERMOST_TOKEN")
@@ -686,13 +687,13 @@ def _apply_env_overrides(config: GatewayConfig) -> None:
         config.platforms[Platform.MATTERMOST].enabled = True
         config.platforms[Platform.MATTERMOST].token = mattermost_token
         config.platforms[Platform.MATTERMOST].extra["url"] = mattermost_url
-    mattermost_home = os.getenv("MATTERMOST_HOME_CHANNEL")
-    if mattermost_home and Platform.MATTERMOST in config.platforms:
-        config.platforms[Platform.MATTERMOST].home_channel = HomeChannel(
-            platform=Platform.MATTERMOST,
-            chat_id=mattermost_home,
-            name=os.getenv("MATTERMOST_HOME_CHANNEL_NAME", "Home"),
-        )
+        mattermost_home = os.getenv("MATTERMOST_HOME_CHANNEL")
+        if mattermost_home:
+            config.platforms[Platform.MATTERMOST].home_channel = HomeChannel(
+                platform=Platform.MATTERMOST,
+                chat_id=mattermost_home,
+                name=os.getenv("MATTERMOST_HOME_CHANNEL_NAME", "Home"),
+            )
 
     # Matrix
     matrix_token = os.getenv("MATRIX_ACCESS_TOKEN")
@@ -714,13 +715,13 @@ def _apply_env_overrides(config: GatewayConfig) -> None:
             config.platforms[Platform.MATRIX].extra["password"] = matrix_password
         matrix_e2ee = os.getenv("MATRIX_ENCRYPTION", "").lower() in ("true", "1", "yes")
         config.platforms[Platform.MATRIX].extra["encryption"] = matrix_e2ee
-    matrix_home = os.getenv("MATRIX_HOME_ROOM")
-    if matrix_home and Platform.MATRIX in config.platforms:
-        config.platforms[Platform.MATRIX].home_channel = HomeChannel(
-            platform=Platform.MATRIX,
-            chat_id=matrix_home,
-            name=os.getenv("MATRIX_HOME_ROOM_NAME", "Home"),
-        )
+        matrix_home = os.getenv("MATRIX_HOME_ROOM")
+        if matrix_home:
+            config.platforms[Platform.MATRIX].home_channel = HomeChannel(
+                platform=Platform.MATRIX,
+                chat_id=matrix_home,
+                name=os.getenv("MATRIX_HOME_ROOM_NAME", "Home"),
+            )
 
     # Home Assistant
     hass_token = os.getenv("HASS_TOKEN")
@@ -747,13 +748,13 @@ def _apply_env_overrides(config: GatewayConfig) -> None:
             "imap_host": email_imap,
             "smtp_host": email_smtp,
         })
-    email_home = os.getenv("EMAIL_HOME_ADDRESS")
-    if email_home and Platform.EMAIL in config.platforms:
-        config.platforms[Platform.EMAIL].home_channel = HomeChannel(
-            platform=Platform.EMAIL,
-            chat_id=email_home,
-            name=os.getenv("EMAIL_HOME_ADDRESS_NAME", "Home"),
-        )
+        email_home = os.getenv("EMAIL_HOME_ADDRESS")
+        if email_home:
+            config.platforms[Platform.EMAIL].home_channel = HomeChannel(
+                platform=Platform.EMAIL,
+                chat_id=email_home,
+                name=os.getenv("EMAIL_HOME_ADDRESS_NAME", "Home"),
+            )
 
     # SMS (Twilio)
     twilio_sid = os.getenv("TWILIO_ACCOUNT_SID")
@@ -762,13 +763,13 @@ def _apply_env_overrides(config: GatewayConfig) -> None:
             config.platforms[Platform.SMS] = PlatformConfig()
         config.platforms[Platform.SMS].enabled = True
         config.platforms[Platform.SMS].api_key = os.getenv("TWILIO_AUTH_TOKEN", "")
-    sms_home = os.getenv("SMS_HOME_CHANNEL")
-    if sms_home and Platform.SMS in config.platforms:
-        config.platforms[Platform.SMS].home_channel = HomeChannel(
-            platform=Platform.SMS,
-            chat_id=sms_home,
-            name=os.getenv("SMS_HOME_CHANNEL_NAME", "Home"),
-        )
+        sms_home = os.getenv("SMS_HOME_CHANNEL")
+        if sms_home:
+            config.platforms[Platform.SMS].home_channel = HomeChannel(
+                platform=Platform.SMS,
+                chat_id=sms_home,
+                name=os.getenv("SMS_HOME_CHANNEL_NAME", "Home"),
+            )
 
     # API Server
     api_server_enabled = os.getenv("API_SERVER_ENABLED", "").lower() in ("true", "1", "yes")

gateway/hooks.py

@@ -51,33 +51,14 @@ class HookRegistry:
         """Return metadata about all loaded hooks."""
         return list(self._loaded_hooks)
 
-    def _register_builtin_hooks(self) -> None:
-        """Register built-in hooks that are always active."""
-        try:
-            from gateway.builtin_hooks.boot_md import handle as boot_md_handle
-
-            self._handlers.setdefault("gateway:startup", []).append(boot_md_handle)
-            self._loaded_hooks.append({
-                "name": "boot-md",
-                "description": "Run ~/.hermes/BOOT.md on gateway startup",
-                "events": ["gateway:startup"],
-                "path": "(builtin)",
-            })
-        except Exception as e:
-            print(f"[hooks] Could not load built-in boot-md hook: {e}", flush=True)
-
     def discover_and_load(self) -> None:
         """
         Scan the hooks directory for hook directories and load their handlers.
 
-        Also registers built-in hooks that are always active.
-
         Each hook directory must contain:
           - HOOK.yaml with at least 'name' and 'events' keys
           - handler.py with a top-level 'handle' function (sync or async)
         """
-        self._register_builtin_hooks()
-
         if not HOOKS_DIR.exists():
             return
 

gateway/platforms/api_server.py

@@ -1261,17 +1261,6 @@ class APIServerAdapter(BasePlatformAdapter):
             self._app.router.add_post("/api/jobs/{job_id}/resume", self._handle_resume_job)
             self._app.router.add_post("/api/jobs/{job_id}/run", self._handle_run_job)
 
-            # Port conflict detection — fail fast if port is already in use
-            import socket as _socket
-            try:
-                with _socket.socket(_socket.AF_INET, _socket.SOCK_STREAM) as _s:
-                    _s.settimeout(1)
-                    _s.connect(('127.0.0.1', self._port))
-                logger.error('[%s] Port %d already in use. Set a different port in config.yaml: platforms.api_server.port', self.name, self._port)
-                return False
-            except (ConnectionRefusedError, OSError):
-                pass  # port is free
-
             self._runner = web.AppRunner(self._app)
             await self._runner.setup()
             self._site = web.TCPSite(self._runner, self._host, self._port)

gateway/platforms/base.py

@@ -175,51 +175,29 @@ def cache_audio_from_bytes(data: bytes, ext: str = ".ogg") -> str:
     return str(filepath)
 
 
-async def cache_audio_from_url(url: str, ext: str = ".ogg", retries: int = 2) -> str:
+async def cache_audio_from_url(url: str, ext: str = ".ogg") -> str:
     """
     Download an audio file from a URL and save it to the local cache.
 
-    Retries on transient failures (timeouts, 429, 5xx) with exponential
-    backoff so a single slow CDN response doesn't lose the media.
-
     Args:
         url: The HTTP/HTTPS URL to download from.
         ext: File extension including the dot (e.g. ".ogg", ".mp3").
-        retries: Number of retry attempts on transient failures.
 
     Returns:
         Absolute path to the cached audio file as a string.
     """
-    import asyncio
     import httpx
-    import logging as _logging
-    _log = _logging.getLogger(__name__)
 
-    last_exc = None
     async with httpx.AsyncClient(timeout=30.0, follow_redirects=True) as client:
-        for attempt in range(retries + 1):
-            try:
-                response = await client.get(
-                    url,
-                    headers={
-                        "User-Agent": "Mozilla/5.0 (compatible; HermesAgent/1.0)",
-                        "Accept": "audio/*,*/*;q=0.8",
-                    },
-                )
-                response.raise_for_status()
-                return cache_audio_from_bytes(response.content, ext)
-            except (httpx.TimeoutException, httpx.HTTPStatusError) as exc:
-                last_exc = exc
-                if isinstance(exc, httpx.HTTPStatusError) and exc.response.status_code < 429:
-                    raise
-                if attempt < retries:
-                    wait = 1.5 * (attempt + 1)
-                    _log.debug("Audio cache retry %d/%d for %s (%.1fs): %s",
-                               attempt + 1, retries, url[:80], wait, exc)
-                    await asyncio.sleep(wait)
-                    continue
-                raise
-    raise last_exc
+        response = await client.get(
+            url,
+            headers={
+                "User-Agent": "Mozilla/5.0 (compatible; HermesAgent/1.0)",
+                "Accept": "audio/*,*/*;q=0.8",
+            },
+        )
+        response.raise_for_status()
+        return cache_audio_from_bytes(response.content, ext)
 
 
 # ---------------------------------------------------------------------------
@@ -1005,7 +983,7 @@ class BasePlatformAdapter(ABC):
             # simultaneous messages. Queue them without interrupting the active run,
             # then process them immediately after the current task finishes.
             if event.message_type == MessageType.PHOTO:
-                logger.debug("[%s] Queuing photo follow-up for session %s without interrupt", self.name, session_key)
+                print(f"[{self.name}] 🖼️ Queuing photo follow-up for session {session_key} without interrupt")
                 existing = self._pending_messages.get(session_key)
                 if existing and existing.message_type == MessageType.PHOTO:
                     existing.media_urls.extend(event.media_urls)
@@ -1020,7 +998,7 @@ class BasePlatformAdapter(ABC):
                 return  # Don't interrupt now - will run after current task completes
 
             # Default behavior for non-photo follow-ups: interrupt the running agent
-            logger.debug("[%s] New message while session %s is active — triggering interrupt", self.name, session_key)
+            print(f"[{self.name}] ⚡ New message while session {session_key} is active - triggering interrupt")
             self._pending_messages[session_key] = event
             # Signal the interrupt (the processing task checks this)
             self._active_sessions[session_key].set()
@@ -1206,9 +1184,9 @@ class BasePlatformAdapter(ABC):
                             )
 
                         if not media_result.success:
-                            logger.warning("[%s] Failed to send media (%s): %s", self.name, ext, media_result.error)
+                            print(f"[{self.name}] Failed to send media ({ext}): {media_result.error}")
                     except Exception as media_err:
-                        logger.warning("[%s] Error sending media: %s", self.name, media_err)
+                        print(f"[{self.name}] Error sending media: {media_err}")
 
                 # Send auto-detected local files as native attachments
                 for file_path in local_files:
@@ -1240,7 +1218,7 @@ class BasePlatformAdapter(ABC):
             # Check if there's a pending message that was queued during our processing
             if session_key in self._pending_messages:
                 pending_event = self._pending_messages.pop(session_key)
-                logger.debug("[%s] Processing queued message from interrupt", self.name)
+                print(f"[{self.name}] 📨 Processing queued message from interrupt")
                 # Clean up current session before processing pending
                 if session_key in self._active_sessions:
                     del self._active_sessions[session_key]
@@ -1254,7 +1232,9 @@ class BasePlatformAdapter(ABC):
                 return  # Already cleaned up
                 
         except Exception as e:
-            logger.error("[%s] Error handling message: %s", self.name, e, exc_info=True)
+            print(f"[{self.name}] Error handling message: {e}")
+            import traceback
+            traceback.print_exc()
             # Send the error to the user so they aren't left with radio silence
             try:
                 error_type = type(e).__name__

gateway/platforms/discord.py

@@ -486,17 +486,6 @@ class DiscordAdapter(BasePlatformAdapter):
             return False
         
         try:
-            # Acquire scoped lock to prevent duplicate bot token usage
-            from gateway.status import acquire_scoped_lock
-            self._token_lock_identity = self.config.token
-            acquired, existing = acquire_scoped_lock('discord-bot-token', self._token_lock_identity, metadata={'platform': 'discord'})
-            if not acquired:
-                owner_pid = existing.get('pid') if isinstance(existing, dict) else None
-                message = f'Discord bot token already in use' + (f' (PID {owner_pid})' if owner_pid else '') + '. Stop the other gateway first.'
-                logger.error('[%s] %s', self.name, message)
-                self._set_fatal_error('discord_token_lock', message, retryable=False)
-                return False
-
             # Set up intents -- members intent needed for username-to-ID resolution
             intents = Intents.default()
             intents.message_content = True
@@ -561,22 +550,6 @@ class DiscordAdapter(BasePlatformAdapter):
                             return
                     # "all" falls through to handle_message
                 
-                # If the message @mentions other users but NOT the bot, the
-                # sender is talking to someone else — stay silent.  Only
-                # applies in server channels; in DMs the user is always
-                # talking to the bot (mentions are just references).
-                # Controlled by DISCORD_IGNORE_NO_MENTION (default: true).
-                _ignore_no_mention = os.getenv(
-                    "DISCORD_IGNORE_NO_MENTION", "true"
-                ).lower() in ("true", "1", "yes")
-                if _ignore_no_mention and message.mentions and not isinstance(message.channel, discord.DMChannel):
-                    _bot_mentioned = (
-                        self._client.user is not None
-                        and self._client.user in message.mentions
-                    )
-                    if not _bot_mentioned:
-                        return  # Talking to someone else, don't interrupt
-
                 await self._handle_message(message)
 
             @self._client.event
@@ -649,16 +622,6 @@ class DiscordAdapter(BasePlatformAdapter):
         self._running = False
         self._client = None
         self._ready_event.clear()
-
-        # Release the token lock
-        try:
-            from gateway.status import release_scoped_lock
-            if getattr(self, '_token_lock_identity', None):
-                release_scoped_lock('discord-bot-token', self._token_lock_identity)
-                self._token_lock_identity = None
-        except Exception:
-            pass
-
         logger.info("[%s] Disconnected", self.name)
     
     async def send(
@@ -1450,23 +1413,15 @@ class DiscordAdapter(BasePlatformAdapter):
         command_text: str,
         followup_msg: str | None = None,
     ) -> None:
-        """Common handler for simple slash commands that dispatch a command string.
-
-        Defers the interaction (shows "thinking..."), dispatches the command,
-        then cleans up the deferred response.  If *followup_msg* is provided
-        the "thinking..." indicator is replaced with that text; otherwise it
-        is deleted so the channel isn't cluttered.
-        """
+        """Common handler for simple slash commands that dispatch a command string."""
         await interaction.response.defer(ephemeral=True)
         event = self._build_slash_event(interaction, command_text)
         await self.handle_message(event)
-        try:
-            if followup_msg:
-                await interaction.edit_original_response(content=followup_msg)
-            else:
-                await interaction.delete_original_response()
-        except Exception as e:
-            logger.debug("Discord interaction cleanup failed: %s", e)
+        if followup_msg:
+            try:
+                await interaction.followup.send(followup_msg, ephemeral=True)
+            except Exception as e:
+                logger.debug("Discord followup failed: %s", e)
 
     def _register_slash_commands(self) -> None:
         """Register Discord slash commands on the command tree."""
@@ -1491,7 +1446,9 @@ class DiscordAdapter(BasePlatformAdapter):
         @tree.command(name="reasoning", description="Show or change reasoning effort")
         @discord.app_commands.describe(effort="Reasoning effort: xhigh, high, medium, low, minimal, or none.")
         async def slash_reasoning(interaction: discord.Interaction, effort: str = ""):
-            await self._run_simple_slash(interaction, f"/reasoning {effort}".strip())
+            await interaction.response.defer(ephemeral=True)
+            event = self._build_slash_event(interaction, f"/reasoning {effort}".strip())
+            await self.handle_message(event)
 
         @tree.command(name="personality", description="Set a personality")
         @discord.app_commands.describe(name="Personality name. Leave empty to list available.")
@@ -1564,7 +1521,9 @@ class DiscordAdapter(BasePlatformAdapter):
             discord.app_commands.Choice(name="status — show current mode", value="status"),
         ])
         async def slash_voice(interaction: discord.Interaction, mode: str = ""):
-            await self._run_simple_slash(interaction, f"/voice {mode}".strip())
+            await interaction.response.defer(ephemeral=True)
+            event = self._build_slash_event(interaction, f"/voice {mode}".strip())
+            await self.handle_message(event)
 
         @tree.command(name="update", description="Update Hermes Agent to the latest version")
         async def slash_update(interaction: discord.Interaction):

gateway/platforms/email.py

@@ -337,63 +337,60 @@ class EmailAdapter(BasePlatformAdapter):
         results = []
         try:
             imap = imaplib.IMAP4_SSL(self._imap_host, self._imap_port, timeout=30)
-            try:
-                imap.login(self._address, self._password)
-                imap.select("INBOX")
+            imap.login(self._address, self._password)
+            imap.select("INBOX")
 
-                status, data = imap.uid("search", None, "UNSEEN")
-                if status != "OK" or not data or not data[0]:
-                    return results
+            status, data = imap.uid("search", None, "UNSEEN")
+            if status != "OK" or not data or not data[0]:
+                imap.logout()
+                return results
 
-                for uid in data[0].split():
-                    if uid in self._seen_uids:
-                        continue
-                    self._seen_uids.add(uid)
-                    # Trim periodically to prevent unbounded memory growth
-                    if len(self._seen_uids) > self._seen_uids_max:
-                        self._trim_seen_uids()
+            for uid in data[0].split():
+                if uid in self._seen_uids:
+                    continue
+                self._seen_uids.add(uid)
+                # Trim periodically to prevent unbounded memory growth
+                if len(self._seen_uids) > self._seen_uids_max:
+                    self._trim_seen_uids()
 
-                    status, msg_data = imap.uid("fetch", uid, "(RFC822)")
-                    if status != "OK":
-                        continue
+                status, msg_data = imap.uid("fetch", uid, "(RFC822)")
+                if status != "OK":
+                    continue
 
-                    raw_email = msg_data[0][1]
-                    msg = email_lib.message_from_bytes(raw_email)
+                raw_email = msg_data[0][1]
+                msg = email_lib.message_from_bytes(raw_email)
 
-                    sender_raw = msg.get("From", "")
-                    sender_addr = _extract_email_address(sender_raw)
-                    sender_name = _decode_header_value(sender_raw)
-                    # Remove email from name if present
-                    if "<" in sender_name:
-                        sender_name = sender_name.split("<")[0].strip().strip('"')
+                sender_raw = msg.get("From", "")
+                sender_addr = _extract_email_address(sender_raw)
+                sender_name = _decode_header_value(sender_raw)
+                # Remove email from name if present
+                if "<" in sender_name:
+                    sender_name = sender_name.split("<")[0].strip().strip('"')
 
-                    subject = _decode_header_value(msg.get("Subject", "(no subject)"))
-                    message_id = msg.get("Message-ID", "")
-                    in_reply_to = msg.get("In-Reply-To", "")
-                    # Skip automated/noreply senders before any processing
-                    msg_headers = dict(msg.items())
-                    if _is_automated_sender(sender_addr, msg_headers):
-                        logger.debug("[Email] Skipping automated sender: %s", sender_addr)
-                        continue
-                    body = _extract_text_body(msg)
-                    attachments = _extract_attachments(msg, skip_attachments=self._skip_attachments)
+                subject = _decode_header_value(msg.get("Subject", "(no subject)"))
+                message_id = msg.get("Message-ID", "")
+                in_reply_to = msg.get("In-Reply-To", "")
+                # Skip automated/noreply senders before any processing
+                msg_headers = dict(msg.items())
+                if _is_automated_sender(sender_addr, msg_headers):
+                    logger.debug("[Email] Skipping automated sender: %s", sender_addr)
+                    continue
+                body = _extract_text_body(msg)
+                attachments = _extract_attachments(msg, skip_attachments=self._skip_attachments)
 
-                    results.append({
-                        "uid": uid,
-                        "sender_addr": sender_addr,
-                        "sender_name": sender_name,
-                        "subject": subject,
-                        "message_id": message_id,
-                        "in_reply_to": in_reply_to,
-                        "body": body,
-                        "attachments": attachments,
-                        "date": msg.get("Date", ""),
-                    })
-            finally:
-                try:
-                    imap.logout()
-                except Exception:
-                    pass
+                results.append({
+                    "uid": uid,
+                    "sender_addr": sender_addr,
+                    "sender_name": sender_name,
+                    "subject": subject,
+                    "message_id": message_id,
+                    "in_reply_to": in_reply_to,
+                    "body": body,
+                    "attachments": attachments,
+                    "date": msg.get("Date", ""),
+                })
+
+            imap.logout()
         except Exception as e:
             logger.error("[Email] IMAP fetch error: %s", e)
         return results
@@ -506,15 +503,10 @@ class EmailAdapter(BasePlatformAdapter):
         msg.attach(MIMEText(body, "plain", "utf-8"))
 
         smtp = smtplib.SMTP(self._smtp_host, self._smtp_port, timeout=30)
-        try:
-            smtp.starttls(context=ssl.create_default_context())
-            smtp.login(self._address, self._password)
-            smtp.send_message(msg)
-        finally:
-            try:
-                smtp.quit()
-            except Exception:
-                smtp.close()
+        smtp.starttls(context=ssl.create_default_context())
+        smtp.login(self._address, self._password)
+        smtp.send_message(msg)
+        smtp.quit()
 
         logger.info("[Email] Sent reply to %s (subject: %s)", to_addr, subject)
         return msg_id
@@ -598,15 +590,10 @@ class EmailAdapter(BasePlatformAdapter):
             msg.attach(part)
 
         smtp = smtplib.SMTP(self._smtp_host, self._smtp_port, timeout=30)
-        try:
-            smtp.starttls(context=ssl.create_default_context())
-            smtp.login(self._address, self._password)
-            smtp.send_message(msg)
-        finally:
-            try:
-                smtp.quit()
-            except Exception:
-                smtp.close()
+        smtp.starttls(context=ssl.create_default_context())
+        smtp.login(self._address, self._password)
+        smtp.send_message(msg)
+        smtp.quit()
 
         return msg_id
 

gateway/platforms/mattermost.py

@@ -603,19 +603,9 @@ class MattermostAdapter(BasePlatformAdapter):
         # For DMs, user_id is sufficient.  For channels, check for @mention.
         message_text = post.get("message", "")
 
-        # Mention-gating for non-DM channels.
-        # Config (env vars):
-        #   MATTERMOST_REQUIRE_MENTION: Require @mention in channels (default: true)
-        #   MATTERMOST_FREE_RESPONSE_CHANNELS: Channel IDs where bot responds without mention
+        # Mention-only mode: skip channel messages that don't @mention the bot.
+        # DMs (type "D") are always processed.
         if channel_type_raw != "D":
-            require_mention = os.getenv(
-                "MATTERMOST_REQUIRE_MENTION", "true"
-            ).lower() not in ("false", "0", "no")
-
-            free_channels_raw = os.getenv("MATTERMOST_FREE_RESPONSE_CHANNELS", "")
-            free_channels = {ch.strip() for ch in free_channels_raw.split(",") if ch.strip()}
-            is_free_channel = channel_id in free_channels
-
             mention_patterns = [
                 f"@{self._bot_username}",
                 f"@{self._bot_user_id}",
@@ -624,21 +614,13 @@ class MattermostAdapter(BasePlatformAdapter):
                 pattern.lower() in message_text.lower()
                 for pattern in mention_patterns
             )
-
-            if require_mention and not is_free_channel and not has_mention:
+            if not has_mention:
                 logger.debug(
                     "Mattermost: skipping non-DM message without @mention (channel=%s)",
                     channel_id,
                 )
                 return
 
-            # Strip @mention from the message text so the agent sees clean input.
-            if has_mention:
-                for pattern in mention_patterns:
-                    message_text = re.sub(
-                        re.escape(pattern), "", message_text, flags=re.IGNORECASE
-                    ).strip()
-
         # Resolve sender info.
         sender_id = post.get("user_id", "")
         sender_name = data.get("sender_name", "").lstrip("@") or sender_id

gateway/platforms/signal.py

@@ -22,7 +22,7 @@ import time
 from datetime import datetime, timezone
 from pathlib import Path
 from typing import Dict, List, Optional, Any
-from urllib.parse import quote, unquote
+from urllib.parse import unquote
 
 import httpx
 
@@ -184,8 +184,6 @@ class SignalAdapter(BasePlatformAdapter):
         self._recent_sent_timestamps: set = set()
         self._max_recent_timestamps = 50
 
-        self._phone_lock_identity: Optional[str] = None
-
         logger.info("Signal adapter initialized: url=%s account=%s groups=%s",
                      self.http_url, _redact_phone(self.account),
                      "enabled" if self.group_allow_from else "disabled")
@@ -200,29 +198,6 @@ class SignalAdapter(BasePlatformAdapter):
             logger.error("Signal: SIGNAL_HTTP_URL and SIGNAL_ACCOUNT are required")
             return False
 
-        # Acquire scoped lock to prevent duplicate Signal listeners for the same phone
-        try:
-            from gateway.status import acquire_scoped_lock
-
-            self._phone_lock_identity = self.account
-            acquired, existing = acquire_scoped_lock(
-                "signal-phone",
-                self._phone_lock_identity,
-                metadata={"platform": self.platform.value},
-            )
-            if not acquired:
-                owner_pid = existing.get("pid") if isinstance(existing, dict) else None
-                message = (
-                    "Another local Hermes gateway is already using this Signal account"
-                    + (f" (PID {owner_pid})." if owner_pid else ".")
-                    + " Stop the other gateway before starting a second Signal listener."
-                )
-                logger.error("Signal: %s", message)
-                self._set_fatal_error("signal_phone_lock", message, retryable=False)
-                return False
-        except Exception as e:
-            logger.warning("Signal: Could not acquire phone lock (non-fatal): %s", e)
-
         self.client = httpx.AsyncClient(timeout=30.0)
 
         # Health check — verify signal-cli daemon is reachable
@@ -270,14 +245,6 @@ class SignalAdapter(BasePlatformAdapter):
             await self.client.aclose()
             self.client = None
 
-        if self._phone_lock_identity:
-            try:
-                from gateway.status import release_scoped_lock
-                release_scoped_lock("signal-phone", self._phone_lock_identity)
-            except Exception as e:
-                logger.warning("Signal: Error releasing phone lock: %s", e, exc_info=True)
-            self._phone_lock_identity = None
-
         logger.info("Signal: disconnected")
 
     # ------------------------------------------------------------------
@@ -286,7 +253,7 @@ class SignalAdapter(BasePlatformAdapter):
 
     async def _sse_listener(self) -> None:
         """Listen for SSE events from signal-cli daemon."""
-        url = f"{self.http_url}/api/v1/events?account={quote(self.account, safe='')}"
+        url = f"{self.http_url}/api/v1/events?account={self.account}"
         backoff = SSE_RETRY_DELAY_INITIAL
 
         while self._running:
@@ -554,7 +521,7 @@ class SignalAdapter(BasePlatformAdapter):
         """Fetch an attachment via JSON-RPC and cache it. Returns (path, ext)."""
         result = await self._rpc("getAttachment", {
             "account": self.account,
-            "id": attachment_id,
+            "attachmentId": attachment_id,
         })
 
         if not result:

gateway/platforms/slack.py

@@ -93,17 +93,6 @@ class SlackAdapter(BasePlatformAdapter):
             return False
 
         try:
-            # Acquire scoped lock to prevent duplicate app token usage
-            from gateway.status import acquire_scoped_lock
-            self._token_lock_identity = app_token
-            acquired, existing = acquire_scoped_lock('slack-app-token', app_token, metadata={'platform': 'slack'})
-            if not acquired:
-                owner_pid = existing.get('pid') if isinstance(existing, dict) else None
-                message = f'Slack app token already in use' + (f' (PID {owner_pid})' if owner_pid else '') + '. Stop the other gateway first.'
-                logger.error('[%s] %s', self.name, message)
-                self._set_fatal_error('slack_token_lock', message, retryable=False)
-                return False
-
             self._app = AsyncApp(token=bot_token)
 
             # Get our own bot user ID for mention detection
@@ -149,16 +138,6 @@ class SlackAdapter(BasePlatformAdapter):
             except Exception as e:  # pragma: no cover - defensive logging
                 logger.warning("[Slack] Error while closing Socket Mode handler: %s", e, exc_info=True)
         self._running = False
-
-        # Release the token lock (use stored identity, not re-read env)
-        try:
-            from gateway.status import release_scoped_lock
-            if getattr(self, '_token_lock_identity', None):
-                release_scoped_lock('slack-app-token', self._token_lock_identity)
-                self._token_lock_identity = None
-        except Exception:
-            pass
-
         logger.info("[Slack] Disconnected")
 
     async def send(

gateway/platforms/webhook.py

@@ -118,17 +118,6 @@ class WebhookAdapter(BasePlatformAdapter):
         app.router.add_get("/health", self._handle_health)
         app.router.add_post("/webhooks/{route_name}", self._handle_webhook)
 
-        # Port conflict detection — fail fast if port is already in use
-        import socket as _socket
-        try:
-            with _socket.socket(_socket.AF_INET, _socket.SOCK_STREAM) as _s:
-                _s.settimeout(1)
-                _s.connect(('127.0.0.1', self._port))
-            logger.error('[webhook] Port %d already in use. Set a different port in config.yaml: platforms.webhook.port', self._port)
-            return False
-        except (ConnectionRefusedError, OSError):
-            pass  # port is free
-
         self._runner = web.AppRunner(app)
         await self._runner.setup()
         site = web.TCPSite(self._runner, self._host, self._port)

gateway/platforms/whatsapp.py

@@ -142,8 +142,6 @@ class WhatsAppAdapter(BasePlatformAdapter):
         self._bridge_log_fh = None
         self._bridge_log: Optional[Path] = None
         self._poll_task: Optional[asyncio.Task] = None
-        self._http_session: Optional["aiohttp.ClientSession"] = None
-        self._session_lock_identity: Optional[str] = None
     
     async def connect(self) -> bool:
         """
@@ -162,29 +160,6 @@ class WhatsAppAdapter(BasePlatformAdapter):
         
         logger.info("[%s] Bridge found at %s", self.name, bridge_path)
         
-        # Acquire scoped lock to prevent duplicate sessions
-        try:
-            from gateway.status import acquire_scoped_lock
-
-            self._session_lock_identity = str(self._session_path)
-            acquired, existing = acquire_scoped_lock(
-                "whatsapp-session",
-                self._session_lock_identity,
-                metadata={"platform": self.platform.value},
-            )
-            if not acquired:
-                owner_pid = existing.get("pid") if isinstance(existing, dict) else None
-                message = (
-                    "Another local Hermes gateway is already using this WhatsApp session"
-                    + (f" (PID {owner_pid})." if owner_pid else ".")
-                    + " Stop the other gateway before starting a second WhatsApp bridge."
-                )
-                logger.error("[%s] %s", self.name, message)
-                self._set_fatal_error("whatsapp_session_lock", message, retryable=False)
-                return False
-        except Exception as e:
-            logger.warning("[%s] Could not acquire session lock (non-fatal): %s", self.name, e)
-
         # Auto-install npm dependencies if node_modules doesn't exist
         bridge_dir = bridge_path.parent
         if not (bridge_dir / "node_modules").exists():
@@ -225,7 +200,6 @@ class WhatsAppAdapter(BasePlatformAdapter):
                                 print(f"[{self.name}] Using existing bridge (status: {bridge_status})")
                                 self._mark_connected()
                                 self._bridge_process = None  # Not managed by us
-                                self._http_session = aiohttp.ClientSession()
                                 self._poll_task = asyncio.create_task(self._poll_messages())
                                 return True
                             else:
@@ -331,9 +305,6 @@ class WhatsAppAdapter(BasePlatformAdapter):
                     print(f"[{self.name}]   Bridge log: {self._bridge_log}")
                     print(f"[{self.name}]   If session expired, re-pair: hermes whatsapp")
             
-            # Create a persistent HTTP session for all bridge communication
-            self._http_session = aiohttp.ClientSession()
-
             # Start message polling task
             self._poll_task = asyncio.create_task(self._poll_messages())
             
@@ -342,12 +313,6 @@ class WhatsAppAdapter(BasePlatformAdapter):
             return True
             
         except Exception as e:
-            if self._session_lock_identity:
-                try:
-                    from gateway.status import release_scoped_lock
-                    release_scoped_lock("whatsapp-session", self._session_lock_identity)
-                except Exception:
-                    pass
             logger.error("[%s] Failed to start bridge: %s", self.name, e, exc_info=True)
             self._close_bridge_log()
             return False
@@ -405,32 +370,10 @@ class WhatsAppAdapter(BasePlatformAdapter):
         else:
             # Bridge was not started by us, don't kill it
             print(f"[{self.name}] Disconnecting (external bridge left running)")
-
-        # Cancel the poll task explicitly
-        if self._poll_task and not self._poll_task.done():
-            self._poll_task.cancel()
-            try:
-                await self._poll_task
-            except (asyncio.CancelledError, Exception):
-                pass
-        self._poll_task = None
-
-        # Close the persistent HTTP session
-        if self._http_session and not self._http_session.closed:
-            await self._http_session.close()
-        self._http_session = None
-
-        if self._session_lock_identity:
-            try:
-                from gateway.status import release_scoped_lock
-                release_scoped_lock("whatsapp-session", self._session_lock_identity)
-            except Exception as e:
-                logger.warning("[%s] Error releasing WhatsApp session lock: %s", self.name, e, exc_info=True)
-
+        
         self._mark_disconnected()
         self._bridge_process = None
         self._close_bridge_log()
-        self._session_lock_identity = None
         print(f"[{self.name}] Disconnected")
     
     async def send(
@@ -441,7 +384,7 @@ class WhatsAppAdapter(BasePlatformAdapter):
         metadata: Optional[Dict[str, Any]] = None
     ) -> SendResult:
         """Send a message via the WhatsApp bridge."""
-        if not self._running or not self._http_session:
+        if not self._running:
             return SendResult(success=False, error="Not connected")
         bridge_exit = await self._check_managed_bridge_exit()
         if bridge_exit:
@@ -449,29 +392,36 @@ class WhatsAppAdapter(BasePlatformAdapter):
         
         try:
             import aiohttp
-
-            payload = {
-                "chatId": chat_id,
-                "message": content,
-            }
-            if reply_to:
-                payload["replyTo"] = reply_to
             
-            async with self._http_session.post(
-                f"http://127.0.0.1:{self._bridge_port}/send",
-                json=payload,
-                timeout=aiohttp.ClientTimeout(total=30)
-            ) as resp:
-                if resp.status == 200:
-                    data = await resp.json()
-                    return SendResult(
-                        success=True,
-                        message_id=data.get("messageId"),
-                        raw_response=data
-                    )
-                else:
-                    error = await resp.text()
-                    return SendResult(success=False, error=error)
+            async with aiohttp.ClientSession() as session:
+                payload = {
+                    "chatId": chat_id,
+                    "message": content,
+                }
+                if reply_to:
+                    payload["replyTo"] = reply_to
+                
+                async with session.post(
+                    f"http://127.0.0.1:{self._bridge_port}/send",
+                    json=payload,
+                    timeout=aiohttp.ClientTimeout(total=30)
+                ) as resp:
+                    if resp.status == 200:
+                        data = await resp.json()
+                        return SendResult(
+                            success=True,
+                            message_id=data.get("messageId"),
+                            raw_response=data
+                        )
+                    else:
+                        error = await resp.text()
+                        return SendResult(success=False, error=error)
+                        
+        except ImportError:
+            return SendResult(
+                success=False, 
+                error="aiohttp not installed. Run: pip install aiohttp"
+            )
         except Exception as e:
             return SendResult(success=False, error=str(e))
 
@@ -482,27 +432,28 @@ class WhatsAppAdapter(BasePlatformAdapter):
         content: str,
     ) -> SendResult:
         """Edit a previously sent message via the WhatsApp bridge."""
-        if not self._running or not self._http_session:
+        if not self._running:
             return SendResult(success=False, error="Not connected")
         bridge_exit = await self._check_managed_bridge_exit()
         if bridge_exit:
             return SendResult(success=False, error=bridge_exit)
         try:
             import aiohttp
-            async with self._http_session.post(
-                f"http://127.0.0.1:{self._bridge_port}/edit",
-                json={
-                    "chatId": chat_id,
-                    "messageId": message_id,
-                    "message": content,
-                },
-                timeout=aiohttp.ClientTimeout(total=15)
-            ) as resp:
-                if resp.status == 200:
-                    return SendResult(success=True, message_id=message_id)
-                else:
-                    error = await resp.text()
-                    return SendResult(success=False, error=error)
+            async with aiohttp.ClientSession() as session:
+                async with session.post(
+                    f"http://127.0.0.1:{self._bridge_port}/edit",
+                    json={
+                        "chatId": chat_id,
+                        "messageId": message_id,
+                        "message": content,
+                    },
+                    timeout=aiohttp.ClientTimeout(total=15)
+                ) as resp:
+                    if resp.status == 200:
+                        return SendResult(success=True, message_id=message_id)
+                    else:
+                        error = await resp.text()
+                        return SendResult(success=False, error=error)
         except Exception as e:
             return SendResult(success=False, error=str(e))
 
@@ -515,7 +466,7 @@ class WhatsAppAdapter(BasePlatformAdapter):
         file_name: Optional[str] = None,
     ) -> SendResult:
         """Send any media file via bridge /send-media endpoint."""
-        if not self._running or not self._http_session:
+        if not self._running:
             return SendResult(success=False, error="Not connected")
         bridge_exit = await self._check_managed_bridge_exit()
         if bridge_exit:
@@ -536,21 +487,22 @@ class WhatsAppAdapter(BasePlatformAdapter):
             if file_name:
                 payload["fileName"] = file_name
 
-            async with self._http_session.post(
-                f"http://127.0.0.1:{self._bridge_port}/send-media",
-                json=payload,
-                timeout=aiohttp.ClientTimeout(total=120),
-            ) as resp:
-                if resp.status == 200:
-                    data = await resp.json()
-                    return SendResult(
-                        success=True,
-                        message_id=data.get("messageId"),
-                        raw_response=data,
-                    )
-                else:
-                    error = await resp.text()
-                    return SendResult(success=False, error=error)
+            async with aiohttp.ClientSession() as session:
+                async with session.post(
+                    f"http://127.0.0.1:{self._bridge_port}/send-media",
+                    json=payload,
+                    timeout=aiohttp.ClientTimeout(total=120),
+                ) as resp:
+                    if resp.status == 200:
+                        data = await resp.json()
+                        return SendResult(
+                            success=True,
+                            message_id=data.get("messageId"),
+                            raw_response=data,
+                        )
+                    else:
+                        error = await resp.text()
+                        return SendResult(success=False, error=error)
 
         except Exception as e:
             return SendResult(success=False, error=str(e))
@@ -608,43 +560,45 @@ class WhatsAppAdapter(BasePlatformAdapter):
 
     async def send_typing(self, chat_id: str, metadata=None) -> None:
         """Send typing indicator via bridge."""
-        if not self._running or not self._http_session:
+        if not self._running:
             return
         if await self._check_managed_bridge_exit():
             return
         
         try:
             import aiohttp
-
-            await self._http_session.post(
-                f"http://127.0.0.1:{self._bridge_port}/typing",
-                json={"chatId": chat_id},
-                timeout=aiohttp.ClientTimeout(total=5)
-            )
+            
+            async with aiohttp.ClientSession() as session:
+                await session.post(
+                    f"http://127.0.0.1:{self._bridge_port}/typing",
+                    json={"chatId": chat_id},
+                    timeout=aiohttp.ClientTimeout(total=5)
+                )
         except Exception:
             pass  # Ignore typing indicator failures
     
     async def get_chat_info(self, chat_id: str) -> Dict[str, Any]:
         """Get information about a WhatsApp chat."""
-        if not self._running or not self._http_session:
+        if not self._running:
             return {"name": "Unknown", "type": "dm"}
         if await self._check_managed_bridge_exit():
             return {"name": chat_id, "type": "dm"}
         
         try:
             import aiohttp
-
-            async with self._http_session.get(
-                f"http://127.0.0.1:{self._bridge_port}/chat/{chat_id}",
-                timeout=aiohttp.ClientTimeout(total=10)
-            ) as resp:
-                if resp.status == 200:
-                    data = await resp.json()
-                    return {
-                        "name": data.get("name", chat_id),
-                        "type": "group" if data.get("isGroup") else "dm",
-                        "participants": data.get("participants", []),
-                    }
+            
+            async with aiohttp.ClientSession() as session:
+                async with session.get(
+                    f"http://127.0.0.1:{self._bridge_port}/chat/{chat_id}",
+                    timeout=aiohttp.ClientTimeout(total=10)
+                ) as resp:
+                    if resp.status == 200:
+                        data = await resp.json()
+                        return {
+                            "name": data.get("name", chat_id),
+                            "type": "group" if data.get("isGroup") else "dm",
+                            "participants": data.get("participants", []),
+                        }
         except Exception as e:
             logger.debug("Could not get WhatsApp chat info for %s: %s", chat_id, e)
         
@@ -652,26 +606,29 @@ class WhatsAppAdapter(BasePlatformAdapter):
     
     async def _poll_messages(self) -> None:
         """Poll the bridge for incoming messages."""
-        import aiohttp
-
+        try:
+            import aiohttp
+        except ImportError:
+            print(f"[{self.name}] aiohttp not installed, message polling disabled")
+            return
+        
         while self._running:
-            if not self._http_session:
-                break
             bridge_exit = await self._check_managed_bridge_exit()
             if bridge_exit:
                 print(f"[{self.name}] {bridge_exit}")
                 break
             try:
-                async with self._http_session.get(
-                    f"http://127.0.0.1:{self._bridge_port}/messages",
-                    timeout=aiohttp.ClientTimeout(total=30)
-                ) as resp:
-                    if resp.status == 200:
-                        messages = await resp.json()
-                        for msg_data in messages:
-                            event = await self._build_message_event(msg_data)
-                            if event:
-                                await self.handle_message(event)
+                async with aiohttp.ClientSession() as session:
+                    async with session.get(
+                        f"http://127.0.0.1:{self._bridge_port}/messages",
+                        timeout=aiohttp.ClientTimeout(total=30)
+                    ) as resp:
+                        if resp.status == 200:
+                            messages = await resp.json()
+                            for msg_data in messages:
+                                event = await self._build_message_event(msg_data)
+                                if event:
+                                    await self.handle_message(event)
             except asyncio.CancelledError:
                 break
             except Exception as e:

gateway/run.py

@@ -77,16 +77,48 @@ sys.path.insert(0, str(Path(__file__).parent.parent))
 
 # Resolve Hermes home directory (respects HERMES_HOME override)
 from hermes_constants import get_hermes_home
-from utils import atomic_yaml_write
 _hermes_home = get_hermes_home()
 
 # Load environment variables from ~/.hermes/.env first.
 # User-managed env files should override stale shell exports on restart.
-from dotenv import load_dotenv  # backward-compat for tests that monkeypatch this symbol
+from dotenv import load_dotenv, dotenv_values  # backward-compat for tests that monkeypatch this symbol
 from hermes_cli.env_loader import load_hermes_dotenv
 _env_path = _hermes_home / '.env'
 load_hermes_dotenv(hermes_home=_hermes_home, project_env=Path(__file__).resolve().parents[1] / '.env')
 
+
+def _external_env_names_from_dotenv(path: Path) -> set[str]:
+    try:
+        vals = dotenv_values(path)
+        return {str(k) for k, v in (vals or {}).items() if k and v not in (None, "")}
+    except Exception:
+        return set()
+
+
+def _inject_keystore_env(force: bool = False, external_managed_names: set[str] | None = None) -> None:
+    """Inject keystore-backed secrets into os.environ when available.
+
+    Args:
+        force: If True, refresh previously keystore-injected values.
+        external_managed_names: Names sourced externally during the current
+            gateway refresh cycle (currently `.env`-tracked names passed by
+            gateway orchestration). These remain authoritative even during
+            forced refresh.
+
+    Runs independently of config.yaml so gateway/headless deployments using
+    only a keystore (with stubbed .env) still receive credentials.
+    """
+    try:
+        from keystore.client import get_keystore
+        _ks = get_keystore()
+        if _ks.is_initialized and _ks.ensure_unlocked(interactive=False):
+            _ks.inject_env(force=force, external_managed_names=external_managed_names)
+    except ImportError:
+        pass
+    except Exception as _e:
+        logging.getLogger(__name__).debug("Gateway keystore injection skipped: %s", _e)
+
+
 # Bridge config.yaml values into the environment so os.getenv() picks them up.
 # config.yaml is authoritative for terminal settings — overrides .env.
 _config_path = _hermes_home / 'config.yaml'
@@ -137,6 +169,7 @@ if _config_path.exists():
                         os.environ[_env_var] = str(_val)
         # Compression config is read directly from config.yaml by run_agent.py
         # and auxiliary_client.py — no env var bridging needed.
+
         # Auxiliary model/direct-endpoint overrides (vision, web_extract).
         # Each task has provider/model/base_url/api_key; bridge non-default values to env vars.
         _auxiliary_cfg = _cfg.get("auxiliary", {})
@@ -195,6 +228,11 @@ if _config_path.exists():
     except Exception:
         pass  # Non-fatal; gateway can still run with .env values
 
+# Inject keystore-backed secrets regardless of whether config.yaml exists.
+# This lets headless / gateway-only installs run with a stubbed .env after
+# secrets are migrated into the encrypted keystore.
+_inject_keystore_env()
+
 # Gateway runs in quiet mode - suppress debug output and use cwd directly (no temp dirs)
 os.environ["HERMES_QUIET"] = "1"
 
@@ -433,7 +471,7 @@ class GatewayRunner:
             from honcho_integration.session import HonchoSessionManager
 
             hcfg = HonchoClientConfig.from_global_config()
-            if not hcfg.enabled or not (hcfg.api_key or hcfg.base_url):
+            if not hcfg.enabled or not hcfg.api_key:
                 return None, hcfg
 
             client = get_honcho_client(hcfg)
@@ -919,12 +957,11 @@ class GatewayRunner:
         return {}
 
     @staticmethod
-    def _load_fallback_model() -> list | dict | None:
-        """Load fallback provider chain from config.yaml.
+    def _load_fallback_model() -> dict | None:
+        """Load fallback model config from config.yaml.
 
-        Returns a list of provider dicts (``fallback_providers``), a single
-        dict (legacy ``fallback_model``), or None if not configured.
-        AIAgent.__init__ normalizes both formats into a chain.
+        Returns a dict with 'provider' and 'model' keys, or None if
+        not configured / both fields empty.
         """
         try:
             import yaml as _y
@@ -932,8 +969,8 @@ class GatewayRunner:
             if cfg_path.exists():
                 with open(cfg_path, encoding="utf-8") as _f:
                     cfg = _y.safe_load(_f) or {}
-                fb = cfg.get("fallback_providers") or cfg.get("fallback_model") or None
-                if fb:
+                fb = cfg.get("fallback_model", {}) or {}
+                if fb.get("provider") and fb.get("model"):
                     return fb
         except Exception:
             pass
@@ -961,13 +998,6 @@ class GatewayRunner:
         """
         logger.info("Starting Hermes Gateway...")
         logger.info("Session storage: %s", self.config.sessions_dir)
-        try:
-            from hermes_cli.profiles import get_active_profile_name
-            _profile = get_active_profile_name()
-            if _profile and _profile != "default":
-                logger.info("Active profile: %s", _profile)
-        except Exception:
-            pass
         try:
             from gateway.status import write_runtime_status
             write_runtime_status(gateway_state="starting", exit_reason=None)
@@ -2611,6 +2641,32 @@ class GatewayRunner:
                     response = (response or "") + approval_hint
             except Exception as e:
                 logger.debug("Failed to check pending approvals: %s", e)
+
+            # Check for pending wallet transaction approvals
+            try:
+                from wallet.approval import pop_pending as pop_wallet_pending
+                import time as _wtime
+                wallet_pending = pop_wallet_pending(session_key)
+                if wallet_pending:
+                    wallet_pending["timestamp"] = _wtime.time()
+                    wallet_pending["_type"] = "wallet_tx"
+                    self._pending_approvals[session_key] = wallet_pending
+                    amt = wallet_pending.get("amount", "?")
+                    sym = wallet_pending.get("symbol", "?")
+                    to_addr = wallet_pending.get("to_address", "?")
+                    chain = wallet_pending.get("chain", "?")
+                    from_label = wallet_pending.get("wallet_label", "?")
+                    approval_hint = (
+                        f"\n\n💰 **Wallet transaction requires approval:**\n"
+                        f"Send **{amt} {sym}** → `{to_addr}`\n"
+                        f"From: {from_label} on {chain}\n\n"
+                        f"Reply `/approve` to execute or `/deny` to cancel."
+                    )
+                    response = (response or "") + approval_hint
+            except ImportError:
+                pass  # wallet not installed
+            except Exception as e:
+                logger.debug("Failed to check wallet pending approvals: %s", e)
             
             # Save the full conversation to the transcript, including tool calls.
             # This preserves the complete agent loop (tool_calls, tool results,
@@ -3097,7 +3153,8 @@ class GatewayRunner:
                 if "agent" not in config or not isinstance(config.get("agent"), dict):
                     config["agent"] = {}
                 config["agent"]["system_prompt"] = ""
-                atomic_yaml_write(config_path, config)
+                with open(config_path, "w") as f:
+                    yaml.dump(config, f, default_flow_style=False, sort_keys=False)
             except Exception as e:
                 return f"⚠️ Failed to save personality change: {e}"
             self._ephemeral_system_prompt = ""
@@ -3110,7 +3167,8 @@ class GatewayRunner:
                 if "agent" not in config or not isinstance(config.get("agent"), dict):
                     config["agent"] = {}
                 config["agent"]["system_prompt"] = new_prompt
-                atomic_yaml_write(config_path, config)
+                with open(config_path, 'w', encoding="utf-8") as f:
+                    yaml.dump(config, f, default_flow_style=False, sort_keys=False)
             except Exception as e:
                 return f"⚠️ Failed to save personality change: {e}"
 
@@ -3200,7 +3258,8 @@ class GatewayRunner:
                 with open(config_path, encoding="utf-8") as f:
                     user_config = yaml.safe_load(f) or {}
             user_config[env_key] = chat_id
-            atomic_yaml_write(config_path, user_config)
+            with open(config_path, 'w', encoding="utf-8") as f:
+                yaml.dump(user_config, f, default_flow_style=False)
             # Also set in the current environment so it takes effect immediately
             os.environ[env_key] = str(chat_id)
         except Exception as e:
@@ -3868,7 +3927,8 @@ class GatewayRunner:
                         current[k] = {}
                     current = current[k]
                 current[keys[-1]] = value
-                atomic_yaml_write(config_path, user_config)
+                with open(config_path, "w", encoding="utf-8") as f:
+                    yaml.dump(user_config, f, default_flow_style=False, sort_keys=False)
                 return True
             except Exception as e:
                 logger.error("Failed to save config key %s: %s", key_path, e)
@@ -3976,7 +4036,8 @@ class GatewayRunner:
             if "display" not in user_config or not isinstance(user_config.get("display"), dict):
                 user_config["display"] = {}
             user_config["display"]["tool_progress"] = new_mode
-            atomic_yaml_write(config_path, user_config)
+            with open(config_path, "w", encoding="utf-8") as f:
+                yaml.dump(user_config, f, default_flow_style=False, sort_keys=False)
             return f"{descriptions[new_mode]}\n_(saved to config — takes effect on next message)_"
         except Exception as e:
             logger.warning("Failed to save tool_progress mode: %s", e)
@@ -4362,6 +4423,32 @@ class GatewayRunner:
             return "⚠️ Approval expired (timed out after 5 minutes). Ask the agent to try again."
 
         self._pending_approvals.pop(session_key)
+
+        # Wallet transaction approval — different dispatch from command approval
+        if approval.get("_type") == "wallet_tx":
+            try:
+                from wallet.approval import execute_approved
+                result_json = execute_approved(session_key, approval)
+                import json as _json
+                result = _json.loads(result_json)
+                if result.get("status") == "submitted":
+                    tx_hash = result.get("tx_hash", "")
+                    explorer = result.get("explorer_url", "")
+                    amt = result.get("amount", "?")
+                    sym = result.get("symbol", "?")
+                    msg = f"✅ Transaction approved and sent!\n\n"
+                    msg += f"**{amt} {sym}** → `{result.get('to', '')}`\n"
+                    if tx_hash:
+                        msg += f"TX: `{tx_hash}`\n"
+                    if explorer:
+                        msg += f"[View on explorer]({explorer})"
+                    return msg
+                else:
+                    return f"❌ Transaction failed: {result.get('error', 'unknown error')}"
+            except Exception as e:
+                logger.error("Wallet approval execution failed: %s", e)
+                return f"❌ Transaction execution failed: {e}"
+
         cmd = approval["command"]
         pattern_keys = approval.get("pattern_keys", [])
         if not pattern_keys:
@@ -5177,6 +5264,16 @@ class GatewayRunner:
             except Exception:
                 pass
 
+            # Re-inject keystore secrets too so rotated values take effect
+            # without requiring a gateway restart. Names explicitly sourced
+            # from .env during this refresh remain authoritative even when a
+            # previously keystore-owned secret has the same string value.
+            try:
+                _external_names = _external_env_names_from_dotenv(_env_path)
+                _inject_keystore_env(force=True, external_managed_names=_external_names)
+            except Exception:
+                pass
+
             model = _resolve_gateway_model(user_config)
 
             try:

hermes_cli/auth.py

@@ -2021,8 +2021,7 @@ def _login_openai_codex(args, pconfig: ProviderConfig) -> None:
     config_path = _update_config_for_provider("openai-codex", creds.get("base_url", DEFAULT_CODEX_BASE_URL))
     print()
     print("Login successful!")
-    from hermes_constants import display_hermes_home as _dhh
-    print(f"  Auth state: {_dhh()}/auth.json")
+    print("  Auth state: ~/.hermes/auth.json")
     print(f"  Config updated: {config_path} (model.provider=openai-codex)")
 
 

hermes_cli/banner.py

@@ -258,7 +258,7 @@ def build_welcome_banner(console: Console, model: str, cwd: str,
         get_toolset_for_tool: Callable to map tool name -> toolset name.
         context_length: Model's context window size in tokens.
     """
-    from model_tools import check_tool_availability, TOOLSET_REQUIREMENTS
+    from model_tools import check_tool_availability
     if get_toolset_for_tool is None:
         from model_tools import get_toolset_for_tool
 
@@ -267,18 +267,8 @@ def build_welcome_banner(console: Console, model: str, cwd: str,
 
     _, unavailable_toolsets = check_tool_availability(quiet=True)
     disabled_tools = set()
-    # Tools whose toolset has a check_fn are lazy-initialized (e.g. honcho,
-    # homeassistant) — they show as unavailable at banner time because the
-    # check hasn't run yet, but they aren't misconfigured.
-    lazy_tools = set()
     for item in unavailable_toolsets:
-        toolset_name = item.get("name", "")
-        ts_req = TOOLSET_REQUIREMENTS.get(toolset_name, {})
-        tools_in_ts = item.get("tools", [])
-        if ts_req.get("check_fn"):
-            lazy_tools.update(tools_in_ts)
-        else:
-            disabled_tools.update(tools_in_ts)
+        disabled_tools.update(item.get("tools", []))
 
     layout_table = Table.grid(padding=(0, 2))
     layout_table.add_column("left", justify="center")
@@ -338,8 +328,6 @@ def build_welcome_banner(console: Console, model: str, cwd: str,
         for name in sorted(tool_names):
             if name in disabled_tools:
                 colored_names.append(f"[red]{name}[/]")
-            elif name in lazy_tools:
-                colored_names.append(f"[yellow]{name}[/]")
             else:
                 colored_names.append(f"[{text}]{name}[/]")
 
@@ -359,8 +347,6 @@ def build_welcome_banner(console: Console, model: str, cwd: str,
                     colored_names.append("[dim]...[/]")
                 elif name in disabled_tools:
                     colored_names.append(f"[red]{name}[/]")
-                elif name in lazy_tools:
-                    colored_names.append(f"[yellow]{name}[/]")
                 else:
                     colored_names.append(f"[{text}]{name}[/]")
             tools_str = ", ".join(colored_names)
@@ -417,15 +403,6 @@ def build_welcome_banner(console: Console, model: str, cwd: str,
     if mcp_connected:
         summary_parts.append(f"{mcp_connected} MCP servers")
     summary_parts.append("/help for commands")
-    # Show active profile name when not 'default'
-    try:
-        from hermes_cli.profiles import get_active_profile_name
-        _profile_name = get_active_profile_name()
-        if _profile_name and _profile_name != "default":
-            right_lines.append(f"[bold {accent}]Profile:[/] [{text}]{_profile_name}[/]")
-    except Exception:
-        pass  # Never break the banner over a profiles.py bug
-
     right_lines.append(f"[dim {dim}]{' · '.join(summary_parts)}[/]")
 
     # Update check — use prefetched result if available

hermes_cli/callbacks.py

@@ -12,7 +12,6 @@ import getpass
 
 from hermes_cli.banner import cprint, _DIM, _RST
 from hermes_cli.config import save_env_value_secure
-from hermes_constants import display_hermes_home
 
 
 def clarify_callback(cli, question, choices):
@@ -132,8 +131,7 @@ def prompt_for_secret(cli, var_name: str, prompt: str, metadata=None) -> dict:
             }
 
         stored = save_env_value_secure(var_name, value)
-        _dhh = display_hermes_home()
-        cprint(f"\n{_DIM}  ✓ Stored secret in {_dhh}/.env as {var_name}{_RST}")
+        cprint(f"\n{_DIM}  ✓ Stored secret in ~/.hermes/.env as {var_name}{_RST}")
         return {
             **stored,
             "skipped": False,
@@ -185,8 +183,7 @@ def prompt_for_secret(cli, var_name: str, prompt: str, metadata=None) -> dict:
                 }
 
             stored = save_env_value_secure(var_name, value)
-            _dhh = display_hermes_home()
-            cprint(f"\n{_DIM}  ✓ Stored secret in {_dhh}/.env as {var_name}{_RST}")
+            cprint(f"\n{_DIM}  ✓ Stored secret in ~/.hermes/.env as {var_name}{_RST}")
             return {
                 **stored,
                 "skipped": False,
@@ -280,3 +277,68 @@ def approval_callback(cli, command: str, description: str) -> str:
             cli._app.invalidate()
         cprint(f"\n{_DIM}  ⏱ Timeout — denying command{_RST}")
         return "deny"
+
+
+def wallet_approval_callback(cli, tx_details: dict) -> str:
+    """Prompt for wallet transaction approval through the TUI.
+
+    Shows transaction details and choices: approve / deny.
+    Mirrors approval_callback() for dangerous commands.
+
+    Returns "approve" or "deny".
+    """
+    lock = getattr(cli, "_approval_lock", None)
+    if lock is None:
+        import threading
+        cli._approval_lock = threading.Lock()
+        lock = cli._approval_lock
+
+    with lock:
+        timeout = 120
+        response_queue = queue.Queue()
+        choices = ["approve", "deny"]
+
+        amt = tx_details.get("amount", "?")
+        sym = tx_details.get("symbol", "?")
+        to_addr = tx_details.get("to_address", "?")
+        chain = tx_details.get("chain", "?")
+        wallet_label = tx_details.get("wallet_label", "?")
+
+        description = (
+            f"Send {amt} {sym} → {to_addr}\n"
+            f"  From: {wallet_label} on {chain}"
+        )
+
+        cli._approval_state = {
+            "command": f"💰 Wallet Transaction: {amt} {sym}",
+            "description": description,
+            "choices": choices,
+            "selected": 0,
+            "response_queue": response_queue,
+        }
+        cli._approval_deadline = _time.monotonic() + timeout
+
+        if hasattr(cli, "_app") and cli._app:
+            cli._app.invalidate()
+
+        while True:
+            try:
+                result = response_queue.get(timeout=1)
+                cli._approval_state = None
+                cli._approval_deadline = 0
+                if hasattr(cli, "_app") and cli._app:
+                    cli._app.invalidate()
+                return result
+            except queue.Empty:
+                remaining = cli._approval_deadline - _time.monotonic()
+                if remaining <= 0:
+                    break
+                if hasattr(cli, "_app") and cli._app:
+                    cli._app.invalidate()
+
+        cli._approval_state = None
+        cli._approval_deadline = 0
+        if hasattr(cli, "_app") and cli._app:
+            cli._app.invalidate()
+        cprint(f"\n{_DIM}  ⏱ Timeout — denying transaction{_RST}")
+        return "deny"

hermes_cli/config.py

@@ -135,7 +135,6 @@ def ensure_hermes_home():
 
 DEFAULT_CONFIG = {
     "model": "anthropic/claude-opus-4.6",
-    "fallback_providers": [],
     "toolsets": ["hermes-cli"],
     "agent": {
         "max_turns": 90,
@@ -367,13 +366,6 @@ DEFAULT_CONFIG = {
     # Never saved to sessions, logs, or trajectories.
     "prefill_messages_file": "",
     
-    # Skills — external skill directories for sharing skills across tools/agents.
-    # Each path is expanded (~, ${VAR}) and resolved.  Read-only — skill creation
-    # always goes to ~/.hermes/skills/.
-    "skills": {
-        "external_dirs": [],   # e.g. ["~/.agents/skills", "/shared/team-skills"]
-    },
-
     # Honcho AI-native memory -- reads ~/.honcho/config.json as single source of truth.
     # This section is only needed for hermes-specific overrides; everything else
     # (apiKey, workspace, peerName, sessions, enabled) comes from the global config.
@@ -429,12 +421,6 @@ DEFAULT_CONFIG = {
         },
     },
 
-    "cron": {
-        # Wrap delivered cron responses with a header (task name) and footer
-        # ("The agent cannot see this message").  Set to false for clean output.
-        "wrap_response": True,
-    },
-
     # Config schema version - bump this when adding new required fields
     "_config_version": 10,
 }
@@ -637,14 +623,6 @@ OPTIONAL_ENV_VARS = {
     },
 
     # ── Tool API keys ──
-    "EXA_API_KEY": {
-        "description": "Exa API key for AI-native web search and contents",
-        "prompt": "Exa API key",
-        "url": "https://exa.ai/",
-        "tools": ["web_search", "web_extract"],
-        "password": True,
-        "category": "tool",
-    },
     "PARALLEL_API_KEY": {
         "description": "Parallel API key for AI-native web search and extract",
         "prompt": "Parallel API key",
@@ -831,20 +809,6 @@ OPTIONAL_ENV_VARS = {
         "password": False,
         "category": "messaging",
     },
-    "MATTERMOST_REQUIRE_MENTION": {
-        "description": "Require @mention in Mattermost channels (default: true). Set to false to respond to all messages.",
-        "prompt": "Require @mention in channels",
-        "url": None,
-        "password": False,
-        "category": "messaging",
-    },
-    "MATTERMOST_FREE_RESPONSE_CHANNELS": {
-        "description": "Comma-separated Mattermost channel IDs where bot responds without @mention",
-        "prompt": "Free-response channel IDs (comma-separated)",
-        "url": None,
-        "password": False,
-        "category": "messaging",
-    },
     "MATRIX_HOMESERVER": {
         "description": "Matrix homeserver URL (e.g. https://matrix.example.org)",
         "prompt": "Matrix homeserver URL",
@@ -1715,7 +1679,6 @@ def show_config():
     keys = [
         ("OPENROUTER_API_KEY", "OpenRouter"),
         ("VOICE_TOOLS_OPENAI_KEY", "OpenAI (STT/TTS)"),
-        ("EXA_API_KEY", "Exa"),
         ("PARALLEL_API_KEY", "Parallel"),
         ("FIRECRAWL_API_KEY", "Firecrawl"),
         ("TAVILY_API_KEY", "Tavily"),
@@ -1875,7 +1838,7 @@ def set_config_value(key: str, value: str):
     # Check if it's an API key (goes to .env)
     api_keys = [
         'OPENROUTER_API_KEY', 'OPENAI_API_KEY', 'ANTHROPIC_API_KEY', 'VOICE_TOOLS_OPENAI_KEY',
-        'EXA_API_KEY', 'PARALLEL_API_KEY', 'FIRECRAWL_API_KEY', 'FIRECRAWL_API_URL', 'TAVILY_API_KEY',
+        'PARALLEL_API_KEY', 'FIRECRAWL_API_KEY', 'FIRECRAWL_API_URL', 'TAVILY_API_KEY',
         'BROWSERBASE_API_KEY', 'BROWSERBASE_PROJECT_ID', 'BROWSER_USE_API_KEY',
         'FAL_KEY', 'TELEGRAM_BOT_TOKEN', 'DISCORD_BOT_TOKEN',
         'TERMINAL_SSH_HOST', 'TERMINAL_SSH_USER', 'TERMINAL_SSH_KEY',

hermes_cli/curses_ui.py

@@ -4,7 +4,7 @@ Used by `hermes tools` and `hermes skills` for interactive checklists.
 Provides a curses multi-select with keyboard navigation, plus a
 text-based numbered fallback for terminals without curses support.
 """
-from typing import Callable, List, Optional, Set
+from typing import List, Set
 
 from hermes_cli.colors import Colors, color
 
@@ -15,7 +15,6 @@ def curses_checklist(
     selected: Set[int],
     *,
     cancel_returns: Set[int] | None = None,
-    status_fn: Optional[Callable[[Set[int]], str]] = None,
 ) -> Set[int]:
     """Curses multi-select checklist. Returns set of selected indices.
 
@@ -24,9 +23,6 @@ def curses_checklist(
         items: Display labels for each row.
         selected: Indices that start checked (pre-selected).
         cancel_returns: Returned on ESC/q. Defaults to the original *selected*.
-        status_fn: Optional callback ``f(chosen_indices) -> str`` whose return
-            value is rendered on the bottom row of the terminal.  Use this for
-            live aggregate info (e.g. estimated token counts).
     """
     if cancel_returns is None:
         cancel_returns = set(selected)
@@ -51,9 +47,6 @@ def curses_checklist(
                 stdscr.clear()
                 max_y, max_x = stdscr.getmaxyx()
 
-                # Reserve bottom row for status bar when status_fn provided
-                footer_rows = 1 if status_fn else 0
-
                 # Header
                 try:
                     hattr = curses.A_BOLD
@@ -69,7 +62,7 @@ def curses_checklist(
                     pass
 
                 # Scrollable item list
-                visible_rows = max_y - 3 - footer_rows
+                visible_rows = max_y - 3
                 if cursor < scroll_offset:
                     scroll_offset = cursor
                 elif cursor >= scroll_offset + visible_rows:
@@ -79,7 +72,7 @@ def curses_checklist(
                     range(scroll_offset, min(len(items), scroll_offset + visible_rows))
                 ):
                     y = draw_i + 3
-                    if y >= max_y - 1 - footer_rows:
+                    if y >= max_y - 1:
                         break
                     check = "✓" if i in chosen else " "
                     arrow = "→" if i == cursor else " "
@@ -94,20 +87,6 @@ def curses_checklist(
                     except curses.error:
                         pass
 
-                # Status bar (bottom row, right-aligned)
-                if status_fn:
-                    try:
-                        status_text = status_fn(chosen)
-                        if status_text:
-                            # Right-align on the bottom row
-                            sx = max(0, max_x - len(status_text) - 1)
-                            sattr = curses.A_DIM
-                            if curses.has_colors():
-                                sattr |= curses.color_pair(3)
-                            stdscr.addnstr(max_y - 1, sx, status_text, max_x - sx - 1, sattr)
-                    except curses.error:
-                        pass
-
                 stdscr.refresh()
                 key = stdscr.getch()
 
@@ -128,7 +107,7 @@ def curses_checklist(
         return result_holder[0] if result_holder[0] is not None else cancel_returns
 
     except Exception:
-        return _numbered_fallback(title, items, selected, cancel_returns, status_fn)
+        return _numbered_fallback(title, items, selected, cancel_returns)
 
 
 def _numbered_fallback(
@@ -136,7 +115,6 @@ def _numbered_fallback(
     items: List[str],
     selected: Set[int],
     cancel_returns: Set[int],
-    status_fn: Optional[Callable[[Set[int]], str]] = None,
 ) -> Set[int]:
     """Text-based toggle fallback for terminals without curses."""
     chosen = set(selected)
@@ -147,10 +125,6 @@ def _numbered_fallback(
         for i, label in enumerate(items):
             marker = color("[✓]", Colors.GREEN) if i in chosen else "[ ]"
             print(f"  {marker} {i + 1:>2}. {label}")
-        if status_fn:
-            status_text = status_fn(chosen)
-            if status_text:
-                print(color(f"\n  {status_text}", Colors.DIM))
         print()
         try:
             val = input(color("  Toggle # (or Enter to confirm): ", Colors.DIM)).strip()

hermes_cli/doctor.py

@@ -10,11 +10,9 @@ import subprocess
 import shutil
 
 from hermes_cli.config import get_project_root, get_hermes_home, get_env_path
-from hermes_constants import display_hermes_home
 
 PROJECT_ROOT = get_project_root()
 HERMES_HOME = get_hermes_home()
-_DHH = display_hermes_home()  # user-facing display path (e.g. ~/.hermes or ~/.hermes/profiles/coder)
 
 # Load environment variables from ~/.hermes/.env so API key checks work
 from dotenv import load_dotenv
@@ -58,7 +56,7 @@ def _honcho_is_configured_for_doctor() -> bool:
         from honcho_integration.client import HonchoClientConfig
 
         cfg = HonchoClientConfig.from_global_config()
-        return bool(cfg.enabled and (cfg.api_key or cfg.base_url))
+        return bool(cfg.enabled and cfg.api_key)
     except Exception:
         return False
 
@@ -211,14 +209,14 @@ def run_doctor(args):
     # Check ~/.hermes/.env (primary location for user config)
     env_path = HERMES_HOME / '.env'
     if env_path.exists():
-        check_ok(f"{_DHH}/.env file exists")
+        check_ok("~/.hermes/.env file exists")
         
         # Check for common issues
         content = env_path.read_text()
         if _has_provider_env_config(content):
             check_ok("API key or custom endpoint configured")
         else:
-            check_warn(f"No API key found in {_DHH}/.env")
+            check_warn("No API key found in ~/.hermes/.env")
             issues.append("Run 'hermes setup' to configure API keys")
     else:
         # Also check project root as fallback
@@ -226,11 +224,11 @@ def run_doctor(args):
         if fallback_env.exists():
             check_ok(".env file exists (in project directory)")
         else:
-            check_fail(f"{_DHH}/.env file missing")
+            check_fail("~/.hermes/.env file missing")
             if should_fix:
                 env_path.parent.mkdir(parents=True, exist_ok=True)
                 env_path.touch()
-                check_ok(f"Created empty {_DHH}/.env")
+                check_ok("Created empty ~/.hermes/.env")
                 check_info("Run 'hermes setup' to configure API keys")
                 fixed_count += 1
             else:
@@ -240,7 +238,7 @@ def run_doctor(args):
     # Check ~/.hermes/config.yaml (primary) or project cli-config.yaml (fallback)
     config_path = HERMES_HOME / 'config.yaml'
     if config_path.exists():
-        check_ok(f"{_DHH}/config.yaml exists")
+        check_ok("~/.hermes/config.yaml exists")
     else:
         fallback_config = PROJECT_ROOT / 'cli-config.yaml'
         if fallback_config.exists():
@@ -250,11 +248,11 @@ def run_doctor(args):
             if should_fix and example_config.exists():
                 config_path.parent.mkdir(parents=True, exist_ok=True)
                 shutil.copy2(str(example_config), str(config_path))
-                check_ok(f"Created {_DHH}/config.yaml from cli-config.yaml.example")
+                check_ok("Created ~/.hermes/config.yaml from cli-config.yaml.example")
                 fixed_count += 1
             elif should_fix:
                 check_warn("config.yaml not found and no example to copy from")
-                manual_issues.append(f"Create {_DHH}/config.yaml manually")
+                manual_issues.append("Create ~/.hermes/config.yaml manually")
             else:
                 check_warn("config.yaml not found", "(using defaults)")
     
@@ -296,28 +294,28 @@ def run_doctor(args):
     
     hermes_home = HERMES_HOME
     if hermes_home.exists():
-        check_ok(f"{_DHH} directory exists")
+        check_ok("~/.hermes directory exists")
     else:
         if should_fix:
             hermes_home.mkdir(parents=True, exist_ok=True)
-            check_ok(f"Created {_DHH} directory")
+            check_ok("Created ~/.hermes directory")
             fixed_count += 1
         else:
-            check_warn(f"{_DHH} not found", "(will be created on first use)")
+            check_warn("~/.hermes not found", "(will be created on first use)")
     
     # Check expected subdirectories
     expected_subdirs = ["cron", "sessions", "logs", "skills", "memories"]
     for subdir_name in expected_subdirs:
         subdir_path = hermes_home / subdir_name
         if subdir_path.exists():
-            check_ok(f"{_DHH}/{subdir_name}/ exists")
+            check_ok(f"~/.hermes/{subdir_name}/ exists")
         else:
             if should_fix:
                 subdir_path.mkdir(parents=True, exist_ok=True)
-                check_ok(f"Created {_DHH}/{subdir_name}/")
+                check_ok(f"Created ~/.hermes/{subdir_name}/")
                 fixed_count += 1
             else:
-                check_warn(f"{_DHH}/{subdir_name}/ not found", "(will be created on first use)")
+                check_warn(f"~/.hermes/{subdir_name}/ not found", "(will be created on first use)")
     
     # Check for SOUL.md persona file
     soul_path = hermes_home / "SOUL.md"
@@ -326,11 +324,11 @@ def run_doctor(args):
         # Check if it's just the template comments (no real content)
         lines = [l for l in content.splitlines() if l.strip() and not l.strip().startswith(("<!--", "-->", "#"))]
         if lines:
-            check_ok(f"{_DHH}/SOUL.md exists (persona configured)")
+            check_ok("~/.hermes/SOUL.md exists (persona configured)")
         else:
-            check_info(f"{_DHH}/SOUL.md exists but is empty — edit it to customize personality")
+            check_info("~/.hermes/SOUL.md exists but is empty — edit it to customize personality")
     else:
-        check_warn(f"{_DHH}/SOUL.md not found", "(create it to give Hermes a custom personality)")
+        check_warn("~/.hermes/SOUL.md not found", "(create it to give Hermes a custom personality)")
         if should_fix:
             soul_path.parent.mkdir(parents=True, exist_ok=True)
             soul_path.write_text(
@@ -339,13 +337,13 @@ def run_doctor(args):
                 "You are Hermes, a helpful AI assistant.\n",
                 encoding="utf-8",
             )
-            check_ok(f"Created {_DHH}/SOUL.md with basic template")
+            check_ok("Created ~/.hermes/SOUL.md with basic template")
             fixed_count += 1
     
     # Check memory directory
     memories_dir = hermes_home / "memories"
     if memories_dir.exists():
-        check_ok(f"{_DHH}/memories/ directory exists")
+        check_ok("~/.hermes/memories/ directory exists")
         memory_file = memories_dir / "MEMORY.md"
         user_file = memories_dir / "USER.md"
         if memory_file.exists():
@@ -359,10 +357,10 @@ def run_doctor(args):
         else:
             check_info("USER.md not created yet (will be created when the agent first writes a memory)")
     else:
-        check_warn(f"{_DHH}/memories/ not found", "(will be created on first use)")
+        check_warn("~/.hermes/memories/ not found", "(will be created on first use)")
         if should_fix:
             memories_dir.mkdir(parents=True, exist_ok=True)
-            check_ok(f"Created {_DHH}/memories/")
+            check_ok("Created ~/.hermes/memories/")
             fixed_count += 1
     
     # Check SQLite session store
@@ -374,11 +372,11 @@ def run_doctor(args):
             cursor = conn.execute("SELECT COUNT(*) FROM sessions")
             count = cursor.fetchone()[0]
             conn.close()
-            check_ok(f"{_DHH}/state.db exists ({count} sessions)")
+            check_ok(f"~/.hermes/state.db exists ({count} sessions)")
         except Exception as e:
-            check_warn(f"{_DHH}/state.db exists but has issues: {e}")
+            check_warn(f"~/.hermes/state.db exists but has issues: {e}")
     else:
-        check_info(f"{_DHH}/state.db not created yet (will be created on first session)")
+        check_info("~/.hermes/state.db not created yet (will be created on first session)")
 
     _check_gateway_service_linger(issues)
     
@@ -693,7 +691,7 @@ def run_doctor(args):
     if github_token:
         check_ok("GitHub token configured (authenticated API access)")
     else:
-        check_warn("No GITHUB_TOKEN", f"(60 req/hr rate limit — set in {_DHH}/.env for better rates)")
+        check_warn("No GITHUB_TOKEN", "(60 req/hr rate limit — set in ~/.hermes/.env for better rates)")
 
     # =========================================================================
     # Honcho memory
@@ -710,8 +708,8 @@ def run_doctor(args):
             check_warn("Honcho config not found", "run: hermes honcho setup")
         elif not hcfg.enabled:
             check_info(f"Honcho disabled (set enabled: true in {_honcho_cfg_path} to activate)")
-        elif not (hcfg.api_key or hcfg.base_url):
-            check_fail("Honcho API key or base URL not set", "run: hermes honcho setup")
+        elif not hcfg.api_key:
+            check_fail("Honcho API key not set", "run: hermes honcho setup")
             issues.append("No Honcho API key — run 'hermes honcho setup'")
         else:
             from honcho_integration.client import get_honcho_client, reset_honcho_client
@@ -730,53 +728,6 @@ def run_doctor(args):
     except Exception as _e:
         check_warn("Honcho check failed", str(_e))
 
-    # =========================================================================
-    # Profiles
-    # =========================================================================
-    try:
-        from hermes_cli.profiles import list_profiles, _get_wrapper_dir, profile_exists
-        import re as _re
-
-        named_profiles = [p for p in list_profiles() if not p.is_default]
-        if named_profiles:
-            print()
-            print(color("◆ Profiles", Colors.CYAN, Colors.BOLD))
-            check_ok(f"{len(named_profiles)} profile(s) found")
-            wrapper_dir = _get_wrapper_dir()
-            for p in named_profiles:
-                parts = []
-                if p.gateway_running:
-                    parts.append("gateway running")
-                if p.model:
-                    parts.append(p.model[:30])
-                if not (p.path / "config.yaml").exists():
-                    parts.append("⚠ missing config")
-                if not (p.path / ".env").exists():
-                    parts.append("no .env")
-                wrapper = wrapper_dir / p.name
-                if not wrapper.exists():
-                    parts.append("no alias")
-                status = ", ".join(parts) if parts else "configured"
-                check_ok(f"  {p.name}: {status}")
-
-            # Check for orphan wrappers
-            if wrapper_dir.is_dir():
-                for wrapper in wrapper_dir.iterdir():
-                    if not wrapper.is_file():
-                        continue
-                    try:
-                        content = wrapper.read_text()
-                        if "hermes -p" in content:
-                            _m = _re.search(r"hermes -p (\S+)", content)
-                            if _m and not profile_exists(_m.group(1)):
-                                check_warn(f"Orphan alias: {wrapper.name} → profile '{_m.group(1)}' no longer exists")
-                    except Exception:
-                        pass
-    except ImportError:
-        pass
-    except Exception as _e:
-        logger.debug("Profile health check failed: %s", _e)
-
     # =========================================================================
     # Summary
     # =========================================================================

hermes_cli/gateway.py

@@ -15,8 +15,6 @@ from pathlib import Path
 PROJECT_ROOT = Path(__file__).parent.parent.resolve()
 
 from hermes_cli.config import get_env_value, get_hermes_home, save_env_value, is_managed, managed_error
-# display_hermes_home is imported lazily at call sites to avoid ImportError
-# when hermes_constants is cached from a pre-update version during `hermes update`.
 from hermes_cli.setup import (
     print_header, print_info, print_success, print_warning, print_error,
     prompt, prompt_choice, prompt_yes_no,
@@ -937,8 +935,7 @@ def launchd_install(force: bool = False):
     print()
     print("Next steps:")
     print("  hermes gateway status             # Check status")
-    from hermes_constants import display_hermes_home as _dhh
-    print(f"  tail -f {_dhh()}/logs/gateway.log  # View logs")
+    print("  tail -f ~/.hermes/logs/gateway.log  # View logs")
 
 def launchd_uninstall():
     plist_path = get_launchd_plist_path()

hermes_cli/main.py

@@ -54,71 +54,6 @@ from typing import Optional
 PROJECT_ROOT = Path(__file__).parent.parent.resolve()
 sys.path.insert(0, str(PROJECT_ROOT))
 
-# ---------------------------------------------------------------------------
-# Profile override — MUST happen before any hermes module import.
-#
-# Many modules cache HERMES_HOME at import time (module-level constants).
-# We intercept --profile/-p from sys.argv here and set the env var so that
-# every subsequent ``os.getenv("HERMES_HOME", ...)`` resolves correctly.
-# The flag is stripped from sys.argv so argparse never sees it.
-# Falls back to ~/.hermes/active_profile for sticky default.
-# ---------------------------------------------------------------------------
-def _apply_profile_override() -> None:
-    """Pre-parse --profile/-p and set HERMES_HOME before module imports."""
-    argv = sys.argv[1:]
-    profile_name = None
-    consume = 0
-
-    # 1. Check for explicit -p / --profile flag
-    for i, arg in enumerate(argv):
-        if arg in ("--profile", "-p") and i + 1 < len(argv):
-            profile_name = argv[i + 1]
-            consume = 2
-            break
-        elif arg.startswith("--profile="):
-            profile_name = arg.split("=", 1)[1]
-            consume = 1
-            break
-
-    # 2. If no flag, check ~/.hermes/active_profile
-    if profile_name is None:
-        try:
-            active_path = Path.home() / ".hermes" / "active_profile"
-            if active_path.exists():
-                name = active_path.read_text().strip()
-                if name and name != "default":
-                    profile_name = name
-                    consume = 0  # don't strip anything from argv
-        except (UnicodeDecodeError, OSError):
-            pass  # corrupted file, skip
-
-    # 3. If we found a profile, resolve and set HERMES_HOME
-    if profile_name is not None:
-        try:
-            from hermes_cli.profiles import resolve_profile_env
-            hermes_home = resolve_profile_env(profile_name)
-        except (ValueError, FileNotFoundError) as exc:
-            print(f"Error: {exc}", file=sys.stderr)
-            sys.exit(1)
-        except Exception as exc:
-            # A bug in profiles.py must NEVER prevent hermes from starting
-            print(f"Warning: profile override failed ({exc}), using default", file=sys.stderr)
-            return
-        os.environ["HERMES_HOME"] = hermes_home
-        # Strip the flag from argv so argparse doesn't choke
-        if consume > 0:
-            for i, arg in enumerate(argv):
-                if arg in ("--profile", "-p"):
-                    start = i + 1  # +1 because argv is sys.argv[1:]
-                    sys.argv = sys.argv[:start] + sys.argv[start + consume:]
-                    break
-                elif arg.startswith("--profile="):
-                    start = i + 1
-                    sys.argv = sys.argv[:start] + sys.argv[start + 1:]
-                    break
-
-_apply_profile_override()
-
 # Load .env from ~/.hermes/.env first, then project root as dev fallback.
 # User-managed env files should override stale shell exports on restart.
 from hermes_cli.config import get_hermes_home
@@ -582,6 +517,25 @@ def cmd_chat(args):
     if getattr(args, "source", None):
         os.environ["HERMES_SESSION_SOURCE"] = args.source
 
+    # Keystore: inject encrypted secrets into os.environ before CLI startup.
+    # This replaces plaintext .env for secret resolution.  Falls back
+    # gracefully if keystore deps aren't installed or store isn't initialized.
+    try:
+        from keystore.client import get_keystore
+        ks = get_keystore()
+        if ks.is_initialized:
+            if ks.ensure_unlocked(interactive=True):
+                injected = ks.inject_env()
+                count = sum(1 for v in injected.values() if v)
+                if count:
+                    logger.debug("Keystore: injected %d secrets", count)
+    except ImportError:
+        pass  # keystore extras not installed — use .env as before
+    except KeyboardInterrupt:
+        sys.exit(0)
+    except Exception as e:
+        logger.debug("Keystore unlock skipped: %s", e)
+
     # Import and run the CLI
     from cli import main as cli_main
     
@@ -1045,7 +999,6 @@ def _model_flow_openrouter(config, current_model=""):
             cfg["model"] = model
         model["provider"] = "openrouter"
         model["base_url"] = OPENROUTER_BASE_URL
-        model["api_mode"] = "chat_completions"
         save_config(cfg)
         deactivate_provider()
         print(f"Default model set to: {selected} (via OpenRouter)")
@@ -1269,7 +1222,6 @@ def _model_flow_custom(config):
             cfg["model"] = model
         model["provider"] = "custom"
         model["base_url"] = effective_url
-        model["api_mode"] = "chat_completions"
         save_config(cfg)
         deactivate_provider()
 
@@ -2051,7 +2003,6 @@ def _model_flow_kimi(config, current_model=""):
             cfg["model"] = model
         model["provider"] = provider_id
         model["base_url"] = effective_base
-        model["api_mode"] = "chat_completions"
         save_config(cfg)
         deactivate_provider()
 
@@ -2158,7 +2109,6 @@ def _model_flow_api_key_provider(config, provider_id, current_model=""):
             cfg["model"] = model
         model["provider"] = provider_id
         model["base_url"] = effective_base
-        model["api_mode"] = "chat_completions"
         save_config(cfg)
         deactivate_provider()
 
@@ -2190,8 +2140,7 @@ def _run_anthropic_oauth_flow(save_env_value):
         ):
             use_anthropic_claude_code_credentials(save_fn=save_env_value)
             print("  ✓ Claude Code credentials linked.")
-            from hermes_constants import display_hermes_home as _dhh_fn
-            print(f"    Hermes will use Claude's credential store directly instead of copying a setup-token into {_dhh_fn()}/.env.")
+            print("    Hermes will use Claude's credential store directly instead of copying a setup-token into ~/.hermes/.env.")
             return True
         return False
 
@@ -2461,34 +2410,6 @@ def cmd_uninstall(args):
     run_uninstall(args)
 
 
-def _clear_bytecode_cache(root: Path) -> int:
-    """Remove all __pycache__ directories under *root*.
-
-    Stale .pyc files can cause ImportError after code updates when Python
-    loads a cached bytecode file that references names that no longer exist
-    (or don't yet exist) in the updated source.  Clearing them forces Python
-    to recompile from the .py source on next import.
-
-    Returns the number of directories removed.
-    """
-    removed = 0
-    for dirpath, dirnames, _ in os.walk(root):
-        # Skip venv / node_modules / .git entirely
-        dirnames[:] = [
-            d for d in dirnames
-            if d not in ("venv", ".venv", "node_modules", ".git", ".worktrees")
-        ]
-        if os.path.basename(dirpath) == "__pycache__":
-            try:
-                import shutil as _shutil
-                _shutil.rmtree(dirpath)
-                removed += 1
-            except OSError:
-                pass
-            dirnames.clear()  # nothing left to recurse into
-    return removed
-
-
 def _update_via_zip(args):
     """Update Hermes Agent by downloading a ZIP archive.
     
@@ -2530,7 +2451,7 @@ def _update_via_zip(args):
                     break
         
         # Copy updated files over existing installation, preserving venv/node_modules/.git
-        preserve = {'venv', 'node_modules', '.git', '.env'}
+        preserve = {'venv', 'node_modules', '.git', '__pycache__', '.env'}
         update_count = 0
         for item in os.listdir(extracted):
             if item in preserve:
@@ -2553,11 +2474,6 @@ def _update_via_zip(args):
     except Exception as e:
         print(f"✗ ZIP update failed: {e}")
         sys.exit(1)
-
-    # Clear stale bytecode after ZIP extraction
-    removed = _clear_bytecode_cache(PROJECT_ROOT)
-    if removed:
-        print(f"  ✓ Cleared {removed} stale __pycache__ director{'y' if removed == 1 else 'ies'}")
     
     # Reinstall Python dependencies (try .[all] first for optional extras,
     # fall back to . if extras fail — mirrors the install script behavior)
@@ -2956,13 +2872,6 @@ def cmd_update(args):
                     )
         
         _invalidate_update_cache()
-
-        # Clear stale .pyc bytecode cache — prevents ImportError on gateway
-        # restart when updated source references names that didn't exist in
-        # the old bytecode (e.g. get_hermes_home added to hermes_constants).
-        removed = _clear_bytecode_cache(PROJECT_ROOT)
-        if removed:
-            print(f"  ✓ Cleared {removed} stale __pycache__ director{'y' if removed == 1 else 'ies'}")
         
         # Reinstall Python dependencies (try .[all] first for optional extras,
         # fall back to . if extras fail — mirrors the install script behavior)
@@ -3011,17 +2920,6 @@ def cmd_update(args):
         print()
         print("✓ Code updated!")
         
-        # After git pull, source files on disk are newer than cached Python
-        # modules in this process.  Reload hermes_constants so that any lazy
-        # import executed below (skills sync, gateway restart) sees new
-        # attributes like display_hermes_home() added since the last release.
-        try:
-            import importlib
-            import hermes_constants as _hc
-            importlib.reload(_hc)
-        except Exception:
-            pass  # non-fatal — worst case a lazy import fails gracefully
-        
         # Sync bundled skills (copies new, updates changed, respects user deletions)
         try:
             from tools.skills_sync import sync_skills
@@ -3040,35 +2938,7 @@ def cmd_update(args):
                 print("  ✓ Skills are up to date")
         except Exception as e:
             logger.debug("Skills sync during update failed: %s", e)
-
-        # Sync bundled skills to all other profiles
-        try:
-            from hermes_cli.profiles import list_profiles, get_active_profile_name, seed_profile_skills
-            active = get_active_profile_name()
-            other_profiles = [p for p in list_profiles() if not p.is_default and p.name != active]
-            if other_profiles:
-                print()
-                print("→ Syncing bundled skills to other profiles...")
-                for p in other_profiles:
-                    try:
-                        r = seed_profile_skills(p.path, quiet=True)
-                        if r:
-                            copied = len(r.get("copied", []))
-                            updated = len(r.get("updated", []))
-                            modified = len(r.get("user_modified", []))
-                            parts = []
-                            if copied: parts.append(f"+{copied} new")
-                            if updated: parts.append(f"↑{updated} updated")
-                            if modified: parts.append(f"~{modified} user-modified")
-                            status = ", ".join(parts) if parts else "up to date"
-                        else:
-                            status = "sync failed"
-                        print(f"  {p.name}: {status}")
-                    except Exception as pe:
-                        print(f"  {p.name}: error ({pe})")
-        except Exception:
-            pass  # profiles module not available or no profiles
-
+        
         # Check for config migrations
         print()
         print("→ Checking configuration for new options...")
@@ -3266,7 +3136,7 @@ def _coalesce_session_name_args(argv: list) -> list:
         "chat", "model", "gateway", "setup", "whatsapp", "login", "logout",
         "status", "cron", "doctor", "config", "pairing", "skills", "tools",
         "mcp", "sessions", "insights", "version", "update", "uninstall",
-        "profile",
+        "keystore", "wallet",
     }
     _SESSION_FLAGS = {"-c", "--continue", "-r", "--resume"}
 
@@ -3290,253 +3160,6 @@ def _coalesce_session_name_args(argv: list) -> list:
     return result
 
 
-def cmd_profile(args):
-    """Profile management — create, delete, list, switch, alias."""
-    from hermes_cli.profiles import (
-        list_profiles, create_profile, delete_profile, seed_profile_skills,
-        get_active_profile, set_active_profile, get_active_profile_name,
-        check_alias_collision, create_wrapper_script, remove_wrapper_script,
-        _is_wrapper_dir_in_path, _get_wrapper_dir,
-    )
-    from hermes_constants import display_hermes_home
-
-    action = getattr(args, "profile_action", None)
-
-    if action is None:
-        # Bare `hermes profile` — show current profile status
-        profile_name = get_active_profile_name()
-        dhh = display_hermes_home()
-        print(f"\nActive profile: {profile_name}")
-        print(f"Path:           {dhh}")
-
-        profiles = list_profiles()
-        for p in profiles:
-            if p.name == profile_name or (profile_name == "default" and p.is_default):
-                if p.model:
-                    print(f"Model:          {p.model}" + (f" ({p.provider})" if p.provider else ""))
-                print(f"Gateway:        {'running' if p.gateway_running else 'stopped'}")
-                print(f"Skills:         {p.skill_count} installed")
-                if p.alias_path:
-                    print(f"Alias:          {p.name} → hermes -p {p.name}")
-                break
-        print()
-        return
-
-    if action == "list":
-        profiles = list_profiles()
-        active = get_active_profile_name()
-
-        if not profiles:
-            print("No profiles found.")
-            return
-
-        # Header
-        print(f"\n {'Profile':<16} {'Model':<28} {'Gateway':<12} {'Alias'}")
-        print(f" {'─' * 15}    {'─' * 27}    {'─' * 11}    {'─' * 12}")
-
-        for p in profiles:
-            marker = " ◆" if (p.name == active or (active == "default" and p.is_default)) else "  "
-            name = p.name
-            model = (p.model or "—")[:26]
-            gw = "running" if p.gateway_running else "stopped"
-            alias = p.name if p.alias_path else "—"
-            if p.is_default:
-                alias = "—"
-            print(f"{marker}{name:<15} {model:<28} {gw:<12} {alias}")
-        print()
-
-    elif action == "use":
-        name = args.profile_name
-        try:
-            set_active_profile(name)
-            if name == "default":
-                print(f"Switched to: default (~/.hermes)")
-            else:
-                print(f"Switched to: {name}")
-        except (ValueError, FileNotFoundError) as e:
-            print(f"Error: {e}")
-            sys.exit(1)
-
-    elif action == "create":
-        name = args.profile_name
-        clone = getattr(args, "clone", False)
-        clone_all = getattr(args, "clone_all", False)
-        no_alias = getattr(args, "no_alias", False)
-
-        try:
-            clone_from = getattr(args, "clone_from", None)
-
-            profile_dir = create_profile(
-                name=name,
-                clone_from=clone_from,
-                clone_all=clone_all,
-                clone_config=clone,
-                no_alias=no_alias,
-            )
-            print(f"\nProfile '{name}' created at {profile_dir}")
-
-            if clone or clone_all:
-                source_label = getattr(args, "clone_from", None) or get_active_profile_name()
-                if clone_all:
-                    print(f"Full copy from {source_label}.")
-                else:
-                    print(f"Cloned config, .env, SOUL.md from {source_label}.")
-
-            # Seed bundled skills (skip if --clone-all already copied them)
-            if not clone_all:
-                result = seed_profile_skills(profile_dir)
-                if result:
-                    copied = len(result.get("copied", []))
-                    print(f"{copied} bundled skills synced.")
-                else:
-                    print("⚠ Skills could not be seeded. Run `{} update` to retry.".format(name))
-
-            # Create wrapper alias
-            if not no_alias:
-                collision = check_alias_collision(name)
-                if collision:
-                    print(f"\n⚠ Cannot create alias '{name}' — {collision}")
-                    print(f"  Choose a custom alias:  hermes profile alias {name} --name <custom>")
-                    print(f"  Or access via flag:     hermes -p {name} chat")
-                else:
-                    wrapper_path = create_wrapper_script(name)
-                    if wrapper_path:
-                        print(f"Wrapper created: {wrapper_path}")
-                        if not _is_wrapper_dir_in_path():
-                            print(f"\n⚠ {_get_wrapper_dir()} is not in your PATH.")
-                            print(f'  Add to your shell config (~/.bashrc or ~/.zshrc):')
-                            print(f'    export PATH="$HOME/.local/bin:$PATH"')
-
-            # Next steps
-            print(f"\nNext steps:")
-            print(f"  {name} setup              Configure API keys and model")
-            print(f"  {name} chat               Start chatting")
-            print(f"  {name} gateway start      Start the messaging gateway")
-            if clone or clone_all:
-                from hermes_constants import get_hermes_home
-                profile_dir_display = f"~/.hermes/profiles/{name}"
-                print(f"\n  Edit {profile_dir_display}/.env for different API keys")
-                print(f"  Edit {profile_dir_display}/SOUL.md for different personality")
-            print()
-
-        except (ValueError, FileExistsError, FileNotFoundError) as e:
-            print(f"Error: {e}")
-            sys.exit(1)
-
-    elif action == "delete":
-        name = args.profile_name
-        yes = getattr(args, "yes", False)
-        try:
-            delete_profile(name, yes=yes)
-        except (ValueError, FileNotFoundError) as e:
-            print(f"Error: {e}")
-            sys.exit(1)
-
-    elif action == "show":
-        name = args.profile_name
-        from hermes_cli.profiles import get_profile_dir, profile_exists, _read_config_model, _check_gateway_running, _count_skills
-        if not profile_exists(name):
-            print(f"Error: Profile '{name}' does not exist.")
-            sys.exit(1)
-        profile_dir = get_profile_dir(name)
-        model, provider = _read_config_model(profile_dir)
-        gw = _check_gateway_running(profile_dir)
-        skills = _count_skills(profile_dir)
-        wrapper = _get_wrapper_dir() / name
-
-        print(f"\nProfile: {name}")
-        print(f"Path:    {profile_dir}")
-        if model:
-            print(f"Model:   {model}" + (f" ({provider})" if provider else ""))
-        print(f"Gateway: {'running' if gw else 'stopped'}")
-        print(f"Skills:  {skills}")
-        print(f".env:    {'exists' if (profile_dir / '.env').exists() else 'not configured'}")
-        print(f"SOUL.md: {'exists' if (profile_dir / 'SOUL.md').exists() else 'not configured'}")
-        if wrapper.exists():
-            print(f"Alias:   {wrapper}")
-        print()
-
-    elif action == "alias":
-        name = args.profile_name
-        remove = getattr(args, "remove", False)
-        custom_name = getattr(args, "alias_name", None)
-
-        from hermes_cli.profiles import profile_exists
-        if not profile_exists(name):
-            print(f"Error: Profile '{name}' does not exist.")
-            sys.exit(1)
-
-        alias_name = custom_name or name
-
-        if remove:
-            if remove_wrapper_script(alias_name):
-                print(f"✓ Removed alias '{alias_name}'")
-            else:
-                print(f"No alias '{alias_name}' found to remove.")
-        else:
-            collision = check_alias_collision(alias_name)
-            if collision:
-                print(f"Error: {collision}")
-                sys.exit(1)
-            wrapper_path = create_wrapper_script(alias_name)
-            if wrapper_path:
-                # If custom name, write the profile name into the wrapper
-                if custom_name:
-                    wrapper_path.write_text(f'#!/bin/sh\nexec hermes -p {name} "$@"\n')
-                print(f"✓ Alias created: {wrapper_path}")
-                if not _is_wrapper_dir_in_path():
-                    print(f"⚠ {_get_wrapper_dir()} is not in your PATH.")
-
-    elif action == "rename":
-        from hermes_cli.profiles import rename_profile
-        try:
-            new_dir = rename_profile(args.old_name, args.new_name)
-            print(f"\nProfile renamed: {args.old_name} → {args.new_name}")
-            print(f"Path: {new_dir}\n")
-        except (ValueError, FileExistsError, FileNotFoundError) as e:
-            print(f"Error: {e}")
-            sys.exit(1)
-
-    elif action == "export":
-        from hermes_cli.profiles import export_profile
-        name = args.profile_name
-        output = args.output or f"{name}.tar.gz"
-        try:
-            result_path = export_profile(name, output)
-            print(f"✓ Exported '{name}' to {result_path}")
-        except (ValueError, FileNotFoundError) as e:
-            print(f"Error: {e}")
-            sys.exit(1)
-
-    elif action == "import":
-        from hermes_cli.profiles import import_profile
-        try:
-            profile_dir = import_profile(args.archive, name=getattr(args, "import_name", None))
-            name = profile_dir.name
-            print(f"✓ Imported profile '{name}' at {profile_dir}")
-
-            # Offer to create alias
-            collision = check_alias_collision(name)
-            if not collision:
-                wrapper_path = create_wrapper_script(name)
-                if wrapper_path:
-                    print(f"  Wrapper created: {wrapper_path}")
-            print()
-        except (ValueError, FileExistsError, FileNotFoundError) as e:
-            print(f"Error: {e}")
-            sys.exit(1)
-
-
-def cmd_completion(args):
-    """Print shell completion script."""
-    from hermes_cli.profiles import generate_bash_completion, generate_zsh_completion
-    shell = getattr(args, "shell", "bash")
-    if shell == "zsh":
-        print(generate_zsh_completion())
-    else:
-        print(generate_bash_completion())
-
-
 def main():
     """Main entry point for hermes CLI."""
     parser = argparse.ArgumentParser(
@@ -4110,7 +3733,7 @@ For more help on a command:
     skills_snapshot = skills_subparsers.add_parser("snapshot", help="Export/import skill configurations")
     snapshot_subparsers = skills_snapshot.add_subparsers(dest="snapshot_action")
     snap_export = snapshot_subparsers.add_parser("export", help="Export installed skills to a file")
-    snap_export.add_argument("output", help="Output JSON file path (use - for stdout)")
+    snap_export.add_argument("output", help="Output JSON file path")
     snap_import = snapshot_subparsers.add_parser("import", help="Import and install skills from a file")
     snap_import.add_argument("input", help="Input JSON file path")
     snap_import.add_argument("--force", action="store_true", help="Force install despite caution verdict")
@@ -4171,16 +3794,6 @@ For more help on a command:
 
     plugins_subparsers.add_parser("list", aliases=["ls"], help="List installed plugins")
 
-    plugins_enable = plugins_subparsers.add_parser(
-        "enable", help="Enable a disabled plugin"
-    )
-    plugins_enable.add_argument("name", help="Plugin name to enable")
-
-    plugins_disable = plugins_subparsers.add_parser(
-        "disable", help="Disable a plugin without removing it"
-    )
-    plugins_disable.add_argument("name", help="Plugin name to disable")
-
     def cmd_plugins(args):
         from hermes_cli.plugins_cmd import plugins_command
         plugins_command(args)
@@ -4348,25 +3961,16 @@ For more help on a command:
     # =========================================================================
     mcp_parser = subparsers.add_parser(
         "mcp",
-        help="Manage MCP servers and run Hermes as an MCP server",
+        help="Manage MCP server connections",
         description=(
-            "Manage MCP server connections and run Hermes as an MCP server.\n\n"
+            "Add, remove, list, test, and configure MCP server connections.\n\n"
             "MCP servers provide additional tools via the Model Context Protocol.\n"
-            "Use 'hermes mcp add' to connect to a new server, or\n"
-            "'hermes mcp serve' to expose Hermes conversations over MCP."
+            "Use 'hermes mcp add' to connect to a new server with interactive\n"
+            "tool discovery. Run 'hermes mcp' with no subcommand to list servers."
         ),
     )
     mcp_sub = mcp_parser.add_subparsers(dest="mcp_action")
 
-    mcp_serve_p = mcp_sub.add_parser(
-        "serve",
-        help="Run Hermes as an MCP server (expose conversations to other agents)",
-    )
-    mcp_serve_p.add_argument(
-        "-v", "--verbose", action="store_true",
-        help="Enable verbose logging on stderr",
-    )
-
     mcp_add_p = mcp_sub.add_parser("add", help="Add an MCP server (discovery-first install)")
     mcp_add_p.add_argument("name", help="Server name (used as config key)")
     mcp_add_p.add_argument("--url", help="HTTP/SSE endpoint URL")
@@ -4406,7 +4010,7 @@ For more help on a command:
     sessions_list.add_argument("--limit", type=int, default=20, help="Max sessions to show")
 
     sessions_export = sessions_subparsers.add_parser("export", help="Export sessions to a JSONL file")
-    sessions_export.add_argument("output", help="Output JSONL file path (use - for stdout)")
+    sessions_export.add_argument("output", help="Output JSONL file path")
     sessions_export.add_argument("--source", help="Filter by source")
     sessions_export.add_argument("--session-id", help="Export a specific session")
 
@@ -4487,25 +4091,15 @@ For more help on a command:
                 if not data:
                     print(f"Session '{args.session_id}' not found.")
                     return
-                line = _json.dumps(data, ensure_ascii=False) + "\n"
-                if args.output == "-":
-                    import sys
-                    sys.stdout.write(line)
-                else:
-                    with open(args.output, "w", encoding="utf-8") as f:
-                        f.write(line)
-                    print(f"Exported 1 session to {args.output}")
+                with open(args.output, "w", encoding="utf-8") as f:
+                    f.write(_json.dumps(data, ensure_ascii=False) + "\n")
+                print(f"Exported 1 session to {args.output}")
             else:
                 sessions = db.export_all(source=args.source)
-                if args.output == "-":
-                    import sys
+                with open(args.output, "w", encoding="utf-8") as f:
                     for s in sessions:
-                        sys.stdout.write(_json.dumps(s, ensure_ascii=False) + "\n")
-                else:
-                    with open(args.output, "w", encoding="utf-8") as f:
-                        for s in sessions:
-                            f.write(_json.dumps(s, ensure_ascii=False) + "\n")
-                    print(f"Exported {len(sessions)} sessions to {args.output}")
+                        f.write(_json.dumps(s, ensure_ascii=False) + "\n")
+                print(f"Exported {len(sessions)} sessions to {args.output}")
 
         elif action == "delete":
             resolved_session_id = db.resolve_session_id(args.session_id)
@@ -4745,73 +4339,32 @@ For more help on a command:
     acp_parser.set_defaults(func=cmd_acp)
 
     # =========================================================================
-    # profile command
+    # keystore command
     # =========================================================================
-    profile_parser = subparsers.add_parser(
-        "profile",
-        help="Manage profiles — multiple isolated Hermes instances",
-    )
-    profile_subparsers = profile_parser.add_subparsers(dest="profile_action")
-
-    profile_list = profile_subparsers.add_parser("list", help="List all profiles")
-    profile_use = profile_subparsers.add_parser("use", help="Set sticky default profile")
-    profile_use.add_argument("profile_name", help="Profile name (or 'default')")
-
-    profile_create = profile_subparsers.add_parser("create", help="Create a new profile")
-    profile_create.add_argument("profile_name", help="Profile name (lowercase, alphanumeric)")
-    profile_create.add_argument("--clone", action="store_true",
-                                help="Copy config.yaml, .env, SOUL.md from active profile")
-    profile_create.add_argument("--clone-all", action="store_true",
-                                help="Full copy of active profile (all state)")
-    profile_create.add_argument("--clone-from", metavar="SOURCE",
-                                help="Source profile to clone from (default: active)")
-    profile_create.add_argument("--no-alias", action="store_true",
-                                help="Skip wrapper script creation")
-
-    profile_delete = profile_subparsers.add_parser("delete", help="Delete a profile")
-    profile_delete.add_argument("profile_name", help="Profile to delete")
-    profile_delete.add_argument("-y", "--yes", action="store_true",
-                                help="Skip confirmation prompt")
-
-    profile_show = profile_subparsers.add_parser("show", help="Show profile details")
-    profile_show.add_argument("profile_name", help="Profile to show")
-
-    profile_alias = profile_subparsers.add_parser("alias", help="Manage wrapper scripts")
-    profile_alias.add_argument("profile_name", help="Profile name")
-    profile_alias.add_argument("--remove", action="store_true",
-                               help="Remove the wrapper script")
-    profile_alias.add_argument("--name", dest="alias_name", metavar="NAME",
-                               help="Custom alias name (default: profile name)")
-
-    profile_rename = profile_subparsers.add_parser("rename", help="Rename a profile")
-    profile_rename.add_argument("old_name", help="Current profile name")
-    profile_rename.add_argument("new_name", help="New profile name")
-
-    profile_export = profile_subparsers.add_parser("export", help="Export a profile to archive")
-    profile_export.add_argument("profile_name", help="Profile to export")
-    profile_export.add_argument("-o", "--output", default=None,
-                                help="Output file (default: <name>.tar.gz)")
-
-    profile_import = profile_subparsers.add_parser("import", help="Import a profile from archive")
-    profile_import.add_argument("archive", help="Path to .tar.gz archive")
-    profile_import.add_argument("--name", dest="import_name", metavar="NAME",
-                                help="Profile name (default: inferred from archive)")
-
-    profile_parser.set_defaults(func=cmd_profile)
+    try:
+        from keystore.cli import register_subparser as register_keystore
+        register_keystore(subparsers)
+    except ImportError:
+        # keystore deps not installed — register a stub that prints install instructions
+        _ks_parser = subparsers.add_parser("keystore", help="Manage encrypted secret store (requires keystore extras)")
+        def _cmd_keystore_stub(args):
+            print("\n  Keystore dependencies not installed.")
+            print("  Install with: pip install 'hermes-agent[keystore]'\n")
+        _ks_parser.set_defaults(func=_cmd_keystore_stub)
 
     # =========================================================================
-    # completion command
+    # wallet command
     # =========================================================================
-    completion_parser = subparsers.add_parser(
-        "completion",
-        help="Print shell completion script (bash or zsh)",
-    )
-    completion_parser.add_argument(
-        "shell", nargs="?", default="bash", choices=["bash", "zsh"],
-        help="Shell type (default: bash)",
-    )
-    completion_parser.set_defaults(func=cmd_completion)
-
+    try:
+        from wallet.cli import register_subparser as register_wallet
+        register_wallet(subparsers)
+    except ImportError:
+        _w_parser = subparsers.add_parser("wallet", help="Manage crypto wallets (requires wallet extras)")
+        def _cmd_wallet_stub(args):
+            print("\n  Wallet dependencies not installed.")
+            print("  Install with: pip install 'hermes-agent[wallet]'\n")
+        _w_parser.set_defaults(func=_cmd_wallet_stub)
+    
     # =========================================================================
     # Parse and execute
     # =========================================================================

hermes_cli/mcp_config.py

@@ -24,7 +24,6 @@ from hermes_cli.config import (
     get_hermes_home,  # noqa: F401 — used by test mocks
 )
 from hermes_cli.colors import Colors, color
-from hermes_constants import display_hermes_home
 
 logger = logging.getLogger(__name__)
 
@@ -245,7 +244,7 @@ def cmd_mcp_add(args):
                     api_key = _prompt("API key / Bearer token", password=True)
                     if api_key:
                         save_env_value(env_key, api_key)
-                        _success(f"Saved to {display_hermes_home()}/.env as {env_key}")
+                        _success(f"Saved to ~/.hermes/.env as {env_key}")
 
                 # Set header with env var interpolation
                 if api_key or existing_key:
@@ -333,7 +332,7 @@ def cmd_mcp_add(args):
     _save_mcp_server(name, server_config)
 
     print()
-    _success(f"Saved '{name}' to {display_hermes_home()}/config.yaml ({tool_count}/{total} tools enabled)")
+    _success(f"Saved '{name}' to ~/.hermes/config.yaml ({tool_count}/{total} tools enabled)")
     _info("Start a new session to use these tools.")
 
 
@@ -608,11 +607,6 @@ def mcp_command(args):
     """Main dispatcher for ``hermes mcp`` subcommands."""
     action = getattr(args, "mcp_action", None)
 
-    if action == "serve":
-        from mcp_serve import run_mcp_server
-        run_mcp_server(verbose=getattr(args, "verbose", False))
-        return
-
     handlers = {
         "add": cmd_mcp_add,
         "remove": cmd_mcp_remove,
@@ -631,7 +625,6 @@ def mcp_command(args):
         # No subcommand — show list
         cmd_mcp_list()
         print(color("  Commands:", Colors.CYAN))
-        _info("hermes mcp serve                              Run as MCP server")
         _info("hermes mcp add <name> --url <endpoint>        Add an MCP server")
         _info("hermes mcp add <name> --command <cmd>         Add a stdio server")
         _info("hermes mcp remove <name>                      Remove a server")

hermes_cli/models.py

@@ -35,8 +35,6 @@ OPENROUTER_MODELS: list[tuple[str, str]] = [
     ("openai/gpt-5.3-codex",            ""),
     ("google/gemini-3-pro-preview",     ""),
     ("google/gemini-3-flash-preview",   ""),
-    ("google/gemini-3.1-pro-preview",     ""),
-    ("google/gemini-3.1-flash-lite-preview",   ""),
     ("qwen/qwen3.5-plus-02-15",         ""),
     ("qwen/qwen3.5-35b-a3b",            ""),
     ("stepfun/step-3.5-flash",          ""),
@@ -64,8 +62,6 @@ _PROVIDER_MODELS: dict[str, list[str]] = {
         "openai/gpt-5.3-codex",
         "google/gemini-3-pro-preview",
         "google/gemini-3-flash-preview",
-        "google/gemini-3.1-pro-preview",
-        "google/gemini-3.1-flash-lite-preview",
         "qwen/qwen3.5-plus-02-15",
         "qwen/qwen3.5-35b-a3b",
         "stepfun/step-3.5-flash",

hermes_cli/plugins.py

@@ -68,17 +68,6 @@ def _env_enabled(name: str) -> bool:
     return os.getenv(name, "").strip().lower() in {"1", "true", "yes", "on"}
 
 
-def _get_disabled_plugins() -> set:
-    """Read the disabled plugins list from config.yaml."""
-    try:
-        from hermes_cli.config import load_config
-        config = load_config()
-        disabled = config.get("plugins", {}).get("disabled", [])
-        return set(disabled) if isinstance(disabled, list) else set()
-    except Exception:
-        return set()
-
-
 # ---------------------------------------------------------------------------
 # Data classes
 # ---------------------------------------------------------------------------
@@ -210,15 +199,8 @@ class PluginManager:
         # 3. Pip / entry-point plugins
         manifests.extend(self._scan_entry_points())
 
-        # Load each manifest (skip user-disabled plugins)
-        disabled = _get_disabled_plugins()
+        # Load each manifest
         for manifest in manifests:
-            if manifest.name in disabled:
-                loaded = LoadedPlugin(manifest=manifest, enabled=False)
-                loaded.error = "disabled via config"
-                self._plugins[manifest.name] = loaded
-                logger.debug("Skipping disabled plugin '%s'", manifest.name)
-                continue
             self._load_plugin(manifest)
 
         if manifests:

hermes_cli/plugins_cmd.py

@@ -374,73 +374,6 @@ def cmd_remove(name: str) -> None:
     _display_removed(name, plugins_dir)
 
 
-def _get_disabled_set() -> set:
-    """Read the disabled plugins set from config.yaml."""
-    try:
-        from hermes_cli.config import load_config
-        config = load_config()
-        disabled = config.get("plugins", {}).get("disabled", [])
-        return set(disabled) if isinstance(disabled, list) else set()
-    except Exception:
-        return set()
-
-
-def _save_disabled_set(disabled: set) -> None:
-    """Write the disabled plugins list to config.yaml."""
-    from hermes_cli.config import load_config, save_config
-    config = load_config()
-    if "plugins" not in config:
-        config["plugins"] = {}
-    config["plugins"]["disabled"] = sorted(disabled)
-    save_config(config)
-
-
-def cmd_enable(name: str) -> None:
-    """Enable a previously disabled plugin."""
-    from rich.console import Console
-
-    console = Console()
-    plugins_dir = _plugins_dir()
-
-    # Verify the plugin exists
-    target = plugins_dir / name
-    if not target.is_dir():
-        console.print(f"[red]Plugin '{name}' is not installed.[/red]")
-        sys.exit(1)
-
-    disabled = _get_disabled_set()
-    if name not in disabled:
-        console.print(f"[dim]Plugin '{name}' is already enabled.[/dim]")
-        return
-
-    disabled.discard(name)
-    _save_disabled_set(disabled)
-    console.print(f"[green]✓[/green] Plugin [bold]{name}[/bold] enabled. Takes effect on next session.")
-
-
-def cmd_disable(name: str) -> None:
-    """Disable a plugin without removing it."""
-    from rich.console import Console
-
-    console = Console()
-    plugins_dir = _plugins_dir()
-
-    # Verify the plugin exists
-    target = plugins_dir / name
-    if not target.is_dir():
-        console.print(f"[red]Plugin '{name}' is not installed.[/red]")
-        sys.exit(1)
-
-    disabled = _get_disabled_set()
-    if name in disabled:
-        console.print(f"[dim]Plugin '{name}' is already disabled.[/dim]")
-        return
-
-    disabled.add(name)
-    _save_disabled_set(disabled)
-    console.print(f"[yellow]⊘[/yellow] Plugin [bold]{name}[/bold] disabled. Takes effect on next session.")
-
-
 def cmd_list() -> None:
     """List installed plugins."""
     from rich.console import Console
@@ -460,11 +393,8 @@ def cmd_list() -> None:
         console.print("[dim]Install with:[/dim] hermes plugins install owner/repo")
         return
 
-    disabled = _get_disabled_set()
-
     table = Table(title="Installed Plugins", show_lines=False)
     table.add_column("Name", style="bold")
-    table.add_column("Status")
     table.add_column("Version", style="dim")
     table.add_column("Description")
     table.add_column("Source", style="dim")
@@ -490,86 +420,11 @@ def cmd_list() -> None:
         if (d / ".git").exists():
             source = "git"
 
-        is_disabled = name in disabled or d.name in disabled
-        status = "[red]disabled[/red]" if is_disabled else "[green]enabled[/green]"
-        table.add_row(name, status, str(version), description, source)
+        table.add_row(name, str(version), description, source)
 
     console.print()
     console.print(table)
     console.print()
-    console.print("[dim]Interactive toggle:[/dim] hermes plugins")
-    console.print("[dim]Enable/disable:[/dim] hermes plugins enable/disable <name>")
-
-
-def cmd_toggle() -> None:
-    """Interactive curses checklist to enable/disable installed plugins."""
-    from rich.console import Console
-
-    try:
-        import yaml
-    except ImportError:
-        yaml = None
-
-    console = Console()
-    plugins_dir = _plugins_dir()
-
-    dirs = sorted(d for d in plugins_dir.iterdir() if d.is_dir())
-    if not dirs:
-        console.print("[dim]No plugins installed.[/dim]")
-        console.print("[dim]Install with:[/dim] hermes plugins install owner/repo")
-        return
-
-    disabled = _get_disabled_set()
-
-    # Build items list: "name — description" for display
-    names = []
-    labels = []
-    selected = set()
-
-    for i, d in enumerate(dirs):
-        manifest_file = d / "plugin.yaml"
-        name = d.name
-        description = ""
-
-        if manifest_file.exists() and yaml:
-            try:
-                with open(manifest_file) as f:
-                    manifest = yaml.safe_load(f) or {}
-                name = manifest.get("name", d.name)
-                description = manifest.get("description", "")
-            except Exception:
-                pass
-
-        names.append(name)
-        label = f"{name} — {description}" if description else name
-        labels.append(label)
-
-        if name not in disabled and d.name not in disabled:
-            selected.add(i)
-
-    from hermes_cli.curses_ui import curses_checklist
-
-    result = curses_checklist(
-        title="Plugins — toggle enabled/disabled",
-        items=labels,
-        selected=selected,
-    )
-
-    # Compute new disabled set from deselected items
-    new_disabled = set()
-    for i, name in enumerate(names):
-        if i not in result:
-            new_disabled.add(name)
-
-    if new_disabled != disabled:
-        _save_disabled_set(new_disabled)
-        enabled_count = len(names) - len(new_disabled)
-        console.print(
-            f"\n[green]✓[/green] {enabled_count} enabled, {len(new_disabled)} disabled. "
-            f"Takes effect on next session."
-        )
-    else:
-        console.print("\n[dim]No changes.[/dim]")
 
 
 def plugins_command(args) -> None:
@@ -582,14 +437,8 @@ def plugins_command(args) -> None:
         cmd_update(args.name)
     elif action in ("remove", "rm", "uninstall"):
         cmd_remove(args.name)
-    elif action == "enable":
-        cmd_enable(args.name)
-    elif action == "disable":
-        cmd_disable(args.name)
-    elif action in ("list", "ls"):
+    elif action in ("list", "ls") or action is None:
         cmd_list()
-    elif action is None:
-        cmd_toggle()
     else:
         from rich.console import Console
 

hermes_cli/profiles.py

@@ -1,906 +0,0 @@
-"""
-Profile management for multiple isolated Hermes instances.
-
-Each profile is a fully independent HERMES_HOME directory with its own
-config.yaml, .env, memory, sessions, skills, gateway, cron, and logs.
-Profiles live under ``~/.hermes/profiles/<name>/`` by default.
-
-The "default" profile is ``~/.hermes`` itself — backward compatible,
-zero migration needed.
-
-Usage::
-
-    hermes profile create coder          # fresh profile + bundled skills
-    hermes profile create coder --clone  # also copy config, .env, SOUL.md
-    hermes profile create coder --clone-all  # full copy of source profile
-    coder chat                           # use via wrapper alias
-    hermes -p coder chat                 # or via flag
-    hermes profile use coder             # set as sticky default
-    hermes profile delete coder          # remove profile + alias + service
-"""
-
-import json
-import os
-import re
-import shutil
-import stat
-import subprocess
-import sys
-from dataclasses import dataclass, field
-from pathlib import Path
-from typing import List, Optional
-
-_PROFILE_ID_RE = re.compile(r"^[a-z0-9][a-z0-9_-]{0,63}$")
-
-# Directories bootstrapped inside every new profile
-_PROFILE_DIRS = [
-    "memories",
-    "sessions",
-    "skills",
-    "skins",
-    "logs",
-    "plans",
-    "workspace",
-    "cron",
-]
-
-# Files copied during --clone (if they exist in the source)
-_CLONE_CONFIG_FILES = [
-    "config.yaml",
-    ".env",
-    "SOUL.md",
-]
-
-# Runtime files stripped after --clone-all (shouldn't carry over)
-_CLONE_ALL_STRIP = [
-    "gateway.pid",
-    "gateway_state.json",
-    "processes.json",
-]
-
-# Names that cannot be used as profile aliases
-_RESERVED_NAMES = frozenset({
-    "hermes", "default", "test", "tmp", "root", "sudo",
-})
-
-# Hermes subcommands that cannot be used as profile names/aliases
-_HERMES_SUBCOMMANDS = frozenset({
-    "chat", "model", "gateway", "setup", "whatsapp", "login", "logout",
-    "status", "cron", "doctor", "config", "pairing", "skills", "tools",
-    "mcp", "sessions", "insights", "version", "update", "uninstall",
-    "profile", "plugins", "honcho", "acp",
-})
-
-
-# ---------------------------------------------------------------------------
-# Path helpers
-# ---------------------------------------------------------------------------
-
-def _get_profiles_root() -> Path:
-    """Return the directory where named profiles are stored.
-
-    Always ``~/.hermes/profiles/`` — anchored to the user's home,
-    NOT to the current HERMES_HOME (which may itself be a profile).
-    This ensures ``coder profile list`` can see all profiles.
-    """
-    return Path.home() / ".hermes" / "profiles"
-
-
-def _get_default_hermes_home() -> Path:
-    """Return the default (pre-profile) HERMES_HOME path."""
-    return Path.home() / ".hermes"
-
-
-def _get_active_profile_path() -> Path:
-    """Return the path to the sticky active_profile file."""
-    return _get_default_hermes_home() / "active_profile"
-
-
-def _get_wrapper_dir() -> Path:
-    """Return the directory for wrapper scripts."""
-    return Path.home() / ".local" / "bin"
-
-
-# ---------------------------------------------------------------------------
-# Validation
-# ---------------------------------------------------------------------------
-
-def validate_profile_name(name: str) -> None:
-    """Raise ``ValueError`` if *name* is not a valid profile identifier."""
-    if name == "default":
-        return  # special alias for ~/.hermes
-    if not _PROFILE_ID_RE.match(name):
-        raise ValueError(
-            f"Invalid profile name {name!r}. Must match "
-            f"[a-z0-9][a-z0-9_-]{{0,63}}"
-        )
-
-
-def get_profile_dir(name: str) -> Path:
-    """Resolve a profile name to its HERMES_HOME directory."""
-    if name == "default":
-        return _get_default_hermes_home()
-    return _get_profiles_root() / name
-
-
-def profile_exists(name: str) -> bool:
-    """Check whether a profile directory exists."""
-    if name == "default":
-        return True
-    return get_profile_dir(name).is_dir()
-
-
-# ---------------------------------------------------------------------------
-# Alias / wrapper script management
-# ---------------------------------------------------------------------------
-
-def check_alias_collision(name: str) -> Optional[str]:
-    """Return a human-readable collision message, or None if the name is safe.
-
-    Checks: reserved names, hermes subcommands, existing binaries in PATH.
-    """
-    if name in _RESERVED_NAMES:
-        return f"'{name}' is a reserved name"
-    if name in _HERMES_SUBCOMMANDS:
-        return f"'{name}' conflicts with a hermes subcommand"
-
-    # Check existing commands in PATH
-    wrapper_dir = _get_wrapper_dir()
-    try:
-        result = subprocess.run(
-            ["which", name], capture_output=True, text=True, timeout=5,
-        )
-        if result.returncode == 0:
-            existing_path = result.stdout.strip()
-            # Allow overwriting our own wrappers
-            if existing_path == str(wrapper_dir / name):
-                try:
-                    content = (wrapper_dir / name).read_text()
-                    if "hermes -p" in content:
-                        return None  # it's our wrapper, safe to overwrite
-                except Exception:
-                    pass
-            return f"'{name}' conflicts with an existing command ({existing_path})"
-    except (FileNotFoundError, subprocess.TimeoutExpired):
-        pass
-
-    return None  # safe
-
-
-def _is_wrapper_dir_in_path() -> bool:
-    """Check if ~/.local/bin is in PATH."""
-    wrapper_dir = str(_get_wrapper_dir())
-    return wrapper_dir in os.environ.get("PATH", "").split(os.pathsep)
-
-
-def create_wrapper_script(name: str) -> Optional[Path]:
-    """Create a shell wrapper script at ~/.local/bin/<name>.
-
-    Returns the path to the created wrapper, or None if creation failed.
-    """
-    wrapper_dir = _get_wrapper_dir()
-    try:
-        wrapper_dir.mkdir(parents=True, exist_ok=True)
-    except OSError as e:
-        print(f"⚠ Could not create {wrapper_dir}: {e}")
-        return None
-
-    wrapper_path = wrapper_dir / name
-    try:
-        wrapper_path.write_text(f'#!/bin/sh\nexec hermes -p {name} "$@"\n')
-        wrapper_path.chmod(wrapper_path.stat().st_mode | stat.S_IEXEC | stat.S_IXGRP | stat.S_IXOTH)
-        return wrapper_path
-    except OSError as e:
-        print(f"⚠ Could not create wrapper at {wrapper_path}: {e}")
-        return None
-
-
-def remove_wrapper_script(name: str) -> bool:
-    """Remove the wrapper script for a profile. Returns True if removed."""
-    wrapper_path = _get_wrapper_dir() / name
-    if wrapper_path.exists():
-        try:
-            # Verify it's our wrapper before removing
-            content = wrapper_path.read_text()
-            if "hermes -p" in content:
-                wrapper_path.unlink()
-                return True
-        except Exception:
-            pass
-    return False
-
-
-# ---------------------------------------------------------------------------
-# ProfileInfo
-# ---------------------------------------------------------------------------
-
-@dataclass
-class ProfileInfo:
-    """Summary information about a profile."""
-    name: str
-    path: Path
-    is_default: bool
-    gateway_running: bool
-    model: Optional[str] = None
-    provider: Optional[str] = None
-    has_env: bool = False
-    skill_count: int = 0
-    alias_path: Optional[Path] = None
-
-
-def _read_config_model(profile_dir: Path) -> tuple:
-    """Read model/provider from a profile's config.yaml. Returns (model, provider)."""
-    config_path = profile_dir / "config.yaml"
-    if not config_path.exists():
-        return None, None
-    try:
-        import yaml
-        with open(config_path, "r") as f:
-            cfg = yaml.safe_load(f) or {}
-        model_cfg = cfg.get("model", {})
-        if isinstance(model_cfg, str):
-            return model_cfg, None
-        if isinstance(model_cfg, dict):
-            return model_cfg.get("model"), model_cfg.get("provider")
-        return None, None
-    except Exception:
-        return None, None
-
-
-def _check_gateway_running(profile_dir: Path) -> bool:
-    """Check if a gateway is running for a given profile directory."""
-    pid_file = profile_dir / "gateway.pid"
-    if not pid_file.exists():
-        return False
-    try:
-        raw = pid_file.read_text().strip()
-        if not raw:
-            return False
-        data = json.loads(raw) if raw.startswith("{") else {"pid": int(raw)}
-        pid = int(data["pid"])
-        os.kill(pid, 0)  # existence check
-        return True
-    except (json.JSONDecodeError, KeyError, ValueError, TypeError,
-            ProcessLookupError, PermissionError, OSError):
-        return False
-
-
-def _count_skills(profile_dir: Path) -> int:
-    """Count installed skills in a profile."""
-    skills_dir = profile_dir / "skills"
-    if not skills_dir.is_dir():
-        return 0
-    count = 0
-    for md in skills_dir.rglob("SKILL.md"):
-        if "/.hub/" not in str(md) and "/.git/" not in str(md):
-            count += 1
-    return count
-
-
-# ---------------------------------------------------------------------------
-# CRUD operations
-# ---------------------------------------------------------------------------
-
-def list_profiles() -> List[ProfileInfo]:
-    """Return info for all profiles, including the default."""
-    profiles = []
-    wrapper_dir = _get_wrapper_dir()
-
-    # Default profile
-    default_home = _get_default_hermes_home()
-    if default_home.is_dir():
-        model, provider = _read_config_model(default_home)
-        profiles.append(ProfileInfo(
-            name="default",
-            path=default_home,
-            is_default=True,
-            gateway_running=_check_gateway_running(default_home),
-            model=model,
-            provider=provider,
-            has_env=(default_home / ".env").exists(),
-            skill_count=_count_skills(default_home),
-        ))
-
-    # Named profiles
-    profiles_root = _get_profiles_root()
-    if profiles_root.is_dir():
-        for entry in sorted(profiles_root.iterdir()):
-            if not entry.is_dir():
-                continue
-            name = entry.name
-            if not _PROFILE_ID_RE.match(name):
-                continue
-            model, provider = _read_config_model(entry)
-            alias_path = wrapper_dir / name
-            profiles.append(ProfileInfo(
-                name=name,
-                path=entry,
-                is_default=False,
-                gateway_running=_check_gateway_running(entry),
-                model=model,
-                provider=provider,
-                has_env=(entry / ".env").exists(),
-                skill_count=_count_skills(entry),
-                alias_path=alias_path if alias_path.exists() else None,
-            ))
-
-    return profiles
-
-
-def create_profile(
-    name: str,
-    clone_from: Optional[str] = None,
-    clone_all: bool = False,
-    clone_config: bool = False,
-    no_alias: bool = False,
-) -> Path:
-    """Create a new profile directory.
-
-    Parameters
-    ----------
-    name:
-        Profile identifier (lowercase, alphanumeric, hyphens, underscores).
-    clone_from:
-        Source profile to clone from. If ``None`` and clone_config/clone_all
-        is True, defaults to the currently active profile.
-    clone_all:
-        If True, do a full copytree of the source (all state).
-    clone_config:
-        If True, copy only config files (config.yaml, .env, SOUL.md).
-    no_alias:
-        If True, skip wrapper script creation.
-
-    Returns
-    -------
-    Path
-        The newly created profile directory.
-    """
-    validate_profile_name(name)
-
-    if name == "default":
-        raise ValueError(
-            "Cannot create a profile named 'default' — it is the built-in profile (~/.hermes)."
-        )
-
-    profile_dir = get_profile_dir(name)
-    if profile_dir.exists():
-        raise FileExistsError(f"Profile '{name}' already exists at {profile_dir}")
-
-    # Resolve clone source
-    source_dir = None
-    if clone_from is not None or clone_all or clone_config:
-        if clone_from is None:
-            # Default: clone from active profile
-            from hermes_constants import get_hermes_home
-            source_dir = get_hermes_home()
-        else:
-            validate_profile_name(clone_from)
-            source_dir = get_profile_dir(clone_from)
-        if not source_dir.is_dir():
-            raise FileNotFoundError(
-                f"Source profile '{clone_from or 'active'}' does not exist at {source_dir}"
-            )
-
-    if clone_all and source_dir:
-        # Full copy of source profile
-        shutil.copytree(source_dir, profile_dir)
-        # Strip runtime files
-        for stale in _CLONE_ALL_STRIP:
-            (profile_dir / stale).unlink(missing_ok=True)
-    else:
-        # Bootstrap directory structure
-        profile_dir.mkdir(parents=True, exist_ok=True)
-        for subdir in _PROFILE_DIRS:
-            (profile_dir / subdir).mkdir(parents=True, exist_ok=True)
-
-        # Clone config files from source
-        if source_dir is not None:
-            for filename in _CLONE_CONFIG_FILES:
-                src = source_dir / filename
-                if src.exists():
-                    shutil.copy2(src, profile_dir / filename)
-
-    return profile_dir
-
-
-def seed_profile_skills(profile_dir: Path, quiet: bool = False) -> Optional[dict]:
-    """Seed bundled skills into a profile via subprocess.
-
-    Uses subprocess because sync_skills() caches HERMES_HOME at module level.
-    Returns the sync result dict, or None on failure.
-    """
-    project_root = Path(__file__).parent.parent.resolve()
-    try:
-        result = subprocess.run(
-            [sys.executable, "-c",
-             "import json; from tools.skills_sync import sync_skills; "
-             "r = sync_skills(quiet=True); print(json.dumps(r))"],
-            env={**os.environ, "HERMES_HOME": str(profile_dir)},
-            cwd=str(project_root),
-            capture_output=True, text=True, timeout=60,
-        )
-        if result.returncode == 0 and result.stdout.strip():
-            return json.loads(result.stdout.strip())
-        if not quiet:
-            print(f"⚠ Skill seeding returned exit code {result.returncode}")
-            if result.stderr.strip():
-                print(f"  {result.stderr.strip()[:200]}")
-        return None
-    except subprocess.TimeoutExpired:
-        if not quiet:
-            print("⚠ Skill seeding timed out (60s)")
-        return None
-    except Exception as e:
-        if not quiet:
-            print(f"⚠ Skill seeding failed: {e}")
-        return None
-
-
-def delete_profile(name: str, yes: bool = False) -> Path:
-    """Delete a profile, its wrapper script, and its gateway service.
-
-    Stops the gateway if running. Disables systemd/launchd service first
-    to prevent auto-restart.
-
-    Returns the path that was removed.
-    """
-    validate_profile_name(name)
-
-    if name == "default":
-        raise ValueError(
-            "Cannot delete the default profile (~/.hermes).\n"
-            "To remove everything, use: hermes uninstall"
-        )
-
-    profile_dir = get_profile_dir(name)
-    if not profile_dir.is_dir():
-        raise FileNotFoundError(f"Profile '{name}' does not exist.")
-
-    # Show what will be deleted
-    model, provider = _read_config_model(profile_dir)
-    gw_running = _check_gateway_running(profile_dir)
-    skill_count = _count_skills(profile_dir)
-
-    print(f"\nProfile: {name}")
-    print(f"Path:    {profile_dir}")
-    if model:
-        print(f"Model:   {model}" + (f" ({provider})" if provider else ""))
-    if skill_count:
-        print(f"Skills:  {skill_count}")
-
-    items = [
-        "All config, API keys, memories, sessions, skills, cron jobs",
-    ]
-
-    # Check for service
-    from hermes_cli.gateway import _profile_suffix, get_service_name
-    wrapper_path = _get_wrapper_dir() / name
-    has_wrapper = wrapper_path.exists()
-    if has_wrapper:
-        items.append(f"Command alias ({wrapper_path})")
-
-    print(f"\nThis will permanently delete:")
-    for item in items:
-        print(f"  • {item}")
-    if gw_running:
-        print(f"  ⚠ Gateway is running — it will be stopped.")
-
-    # Confirmation
-    if not yes:
-        print()
-        try:
-            confirm = input(f"Type '{name}' to confirm: ").strip()
-        except (KeyboardInterrupt, EOFError):
-            print("\nCancelled.")
-            return profile_dir
-        if confirm != name:
-            print("Cancelled.")
-            return profile_dir
-
-    # 1. Disable service (prevents auto-restart)
-    _cleanup_gateway_service(name, profile_dir)
-
-    # 2. Stop running gateway
-    if gw_running:
-        _stop_gateway_process(profile_dir)
-
-    # 3. Remove wrapper script
-    if has_wrapper:
-        if remove_wrapper_script(name):
-            print(f"✓ Removed {wrapper_path}")
-
-    # 4. Remove profile directory
-    try:
-        shutil.rmtree(profile_dir)
-        print(f"✓ Removed {profile_dir}")
-    except Exception as e:
-        print(f"⚠ Could not remove {profile_dir}: {e}")
-
-    # 5. Clear active_profile if it pointed to this profile
-    try:
-        active = get_active_profile()
-        if active == name:
-            set_active_profile("default")
-            print("✓ Active profile reset to default")
-    except Exception:
-        pass
-
-    print(f"\nProfile '{name}' deleted.")
-    return profile_dir
-
-
-def _cleanup_gateway_service(name: str, profile_dir: Path) -> None:
-    """Disable and remove systemd/launchd service for a profile."""
-    import platform as _platform
-
-    # Derive service name for this profile
-    # Temporarily set HERMES_HOME so _profile_suffix resolves correctly
-    old_home = os.environ.get("HERMES_HOME")
-    try:
-        os.environ["HERMES_HOME"] = str(profile_dir)
-        from hermes_cli.gateway import get_service_name, get_launchd_plist_path
-
-        if _platform.system() == "Linux":
-            svc_name = get_service_name()
-            svc_file = Path.home() / ".config" / "systemd" / "user" / f"{svc_name}.service"
-            if svc_file.exists():
-                subprocess.run(
-                    ["systemctl", "--user", "disable", svc_name],
-                    capture_output=True, check=False, timeout=10,
-                )
-                subprocess.run(
-                    ["systemctl", "--user", "stop", svc_name],
-                    capture_output=True, check=False, timeout=10,
-                )
-                svc_file.unlink(missing_ok=True)
-                subprocess.run(
-                    ["systemctl", "--user", "daemon-reload"],
-                    capture_output=True, check=False, timeout=10,
-                )
-                print(f"✓ Service {svc_name} removed")
-
-        elif _platform.system() == "Darwin":
-            plist_path = get_launchd_plist_path()
-            if plist_path.exists():
-                subprocess.run(
-                    ["launchctl", "unload", str(plist_path)],
-                    capture_output=True, check=False, timeout=10,
-                )
-                plist_path.unlink(missing_ok=True)
-                print(f"✓ Launchd service removed")
-    except Exception as e:
-        print(f"⚠ Service cleanup: {e}")
-    finally:
-        if old_home is not None:
-            os.environ["HERMES_HOME"] = old_home
-        elif "HERMES_HOME" in os.environ:
-            del os.environ["HERMES_HOME"]
-
-
-def _stop_gateway_process(profile_dir: Path) -> None:
-    """Stop a running gateway process via its PID file."""
-    import signal as _signal
-    import time as _time
-
-    pid_file = profile_dir / "gateway.pid"
-    if not pid_file.exists():
-        return
-
-    try:
-        raw = pid_file.read_text().strip()
-        data = json.loads(raw) if raw.startswith("{") else {"pid": int(raw)}
-        pid = int(data["pid"])
-        os.kill(pid, _signal.SIGTERM)
-        # Wait up to 10s for graceful shutdown
-        for _ in range(20):
-            _time.sleep(0.5)
-            try:
-                os.kill(pid, 0)
-            except ProcessLookupError:
-                print(f"✓ Gateway stopped (PID {pid})")
-                return
-        # Force kill
-        try:
-            os.kill(pid, _signal.SIGKILL)
-        except ProcessLookupError:
-            pass
-        print(f"✓ Gateway force-stopped (PID {pid})")
-    except (ProcessLookupError, PermissionError):
-        print("✓ Gateway already stopped")
-    except Exception as e:
-        print(f"⚠ Could not stop gateway: {e}")
-
-
-# ---------------------------------------------------------------------------
-# Active profile (sticky default)
-# ---------------------------------------------------------------------------
-
-def get_active_profile() -> str:
-    """Read the sticky active profile name.
-
-    Returns ``"default"`` if no active_profile file exists or it's empty.
-    """
-    path = _get_active_profile_path()
-    try:
-        name = path.read_text().strip()
-        if not name:
-            return "default"
-        return name
-    except (FileNotFoundError, UnicodeDecodeError, OSError):
-        return "default"
-
-
-def set_active_profile(name: str) -> None:
-    """Set the sticky active profile.
-
-    Writes to ``~/.hermes/active_profile``. Use ``"default"`` to clear.
-    """
-    validate_profile_name(name)
-    if name != "default" and not profile_exists(name):
-        raise FileNotFoundError(
-            f"Profile '{name}' does not exist. "
-            f"Create it with: hermes profile create {name}"
-        )
-
-    path = _get_active_profile_path()
-    path.parent.mkdir(parents=True, exist_ok=True)
-    if name == "default":
-        # Remove the file to indicate default
-        path.unlink(missing_ok=True)
-    else:
-        # Atomic write
-        tmp = path.with_suffix(".tmp")
-        tmp.write_text(name + "\n")
-        tmp.replace(path)
-
-
-def get_active_profile_name() -> str:
-    """Infer the current profile name from HERMES_HOME.
-
-    Returns ``"default"`` if HERMES_HOME is not set or points to ``~/.hermes``.
-    Returns the profile name if HERMES_HOME points into ``~/.hermes/profiles/<name>``.
-    Returns ``"custom"`` if HERMES_HOME is set to an unrecognized path.
-    """
-    from hermes_constants import get_hermes_home
-    hermes_home = get_hermes_home()
-    resolved = hermes_home.resolve()
-
-    default_resolved = _get_default_hermes_home().resolve()
-    if resolved == default_resolved:
-        return "default"
-
-    profiles_root = _get_profiles_root().resolve()
-    try:
-        rel = resolved.relative_to(profiles_root)
-        parts = rel.parts
-        if len(parts) == 1 and _PROFILE_ID_RE.match(parts[0]):
-            return parts[0]
-    except ValueError:
-        pass
-
-    return "custom"
-
-
-# ---------------------------------------------------------------------------
-# Export / Import
-# ---------------------------------------------------------------------------
-
-def export_profile(name: str, output_path: str) -> Path:
-    """Export a profile to a tar.gz archive.
-
-    Returns the output file path.
-    """
-    validate_profile_name(name)
-    profile_dir = get_profile_dir(name)
-    if not profile_dir.is_dir():
-        raise FileNotFoundError(f"Profile '{name}' does not exist.")
-
-    output = Path(output_path)
-    # shutil.make_archive wants the base name without extension
-    base = str(output).removesuffix(".tar.gz").removesuffix(".tgz")
-    result = shutil.make_archive(base, "gztar", str(profile_dir.parent), name)
-    return Path(result)
-
-
-def import_profile(archive_path: str, name: Optional[str] = None) -> Path:
-    """Import a profile from a tar.gz archive.
-
-    If *name* is not given, infers it from the archive's top-level directory.
-    Returns the imported profile directory.
-    """
-    import tarfile
-
-    archive = Path(archive_path)
-    if not archive.exists():
-        raise FileNotFoundError(f"Archive not found: {archive}")
-
-    # Peek at the archive to find the top-level directory name
-    with tarfile.open(archive, "r:gz") as tf:
-        top_dirs = {m.name.split("/")[0] for m in tf.getmembers() if "/" in m.name}
-        if not top_dirs:
-            top_dirs = {m.name for m in tf.getmembers() if m.isdir()}
-
-    inferred_name = name or (top_dirs.pop() if len(top_dirs) == 1 else None)
-    if not inferred_name:
-        raise ValueError(
-            "Cannot determine profile name from archive. "
-            "Specify it explicitly: hermes profile import <archive> --name <name>"
-        )
-
-    validate_profile_name(inferred_name)
-    profile_dir = get_profile_dir(inferred_name)
-    if profile_dir.exists():
-        raise FileExistsError(f"Profile '{inferred_name}' already exists at {profile_dir}")
-
-    profiles_root = _get_profiles_root()
-    profiles_root.mkdir(parents=True, exist_ok=True)
-
-    shutil.unpack_archive(str(archive), str(profiles_root))
-
-    # If the archive extracted under a different name, rename
-    extracted = profiles_root / (top_dirs.pop() if top_dirs else inferred_name)
-    if extracted != profile_dir and extracted.exists():
-        extracted.rename(profile_dir)
-
-    return profile_dir
-
-
-# ---------------------------------------------------------------------------
-# Rename
-# ---------------------------------------------------------------------------
-
-def rename_profile(old_name: str, new_name: str) -> Path:
-    """Rename a profile: directory, wrapper script, service, active_profile.
-
-    Returns the new profile directory.
-    """
-    validate_profile_name(old_name)
-    validate_profile_name(new_name)
-
-    if old_name == "default":
-        raise ValueError("Cannot rename the default profile.")
-    if new_name == "default":
-        raise ValueError("Cannot rename to 'default' — it is reserved.")
-
-    old_dir = get_profile_dir(old_name)
-    new_dir = get_profile_dir(new_name)
-
-    if not old_dir.is_dir():
-        raise FileNotFoundError(f"Profile '{old_name}' does not exist.")
-    if new_dir.exists():
-        raise FileExistsError(f"Profile '{new_name}' already exists.")
-
-    # 1. Stop gateway if running
-    if _check_gateway_running(old_dir):
-        _cleanup_gateway_service(old_name, old_dir)
-        _stop_gateway_process(old_dir)
-
-    # 2. Rename directory
-    old_dir.rename(new_dir)
-    print(f"✓ Renamed {old_dir.name} → {new_dir.name}")
-
-    # 3. Update wrapper script
-    remove_wrapper_script(old_name)
-    collision = check_alias_collision(new_name)
-    if not collision:
-        create_wrapper_script(new_name)
-        print(f"✓ Alias updated: {new_name}")
-    else:
-        print(f"⚠ Cannot create alias '{new_name}' — {collision}")
-
-    # 4. Update active_profile if it pointed to old name
-    try:
-        if get_active_profile() == old_name:
-            set_active_profile(new_name)
-            print(f"✓ Active profile updated: {new_name}")
-    except Exception:
-        pass
-
-    return new_dir
-
-
-# ---------------------------------------------------------------------------
-# Tab completion
-# ---------------------------------------------------------------------------
-
-def generate_bash_completion() -> str:
-    """Generate a bash completion script for hermes profile names."""
-    return '''# Hermes Agent profile completion
-# Add to ~/.bashrc: eval "$(hermes completion bash)"
-
-_hermes_profiles() {
-    local profiles_dir="$HOME/.hermes/profiles"
-    local profiles="default"
-    if [ -d "$profiles_dir" ]; then
-        profiles="$profiles $(ls "$profiles_dir" 2>/dev/null)"
-    fi
-    echo "$profiles"
-}
-
-_hermes_completion() {
-    local cur prev
-    cur="${COMP_WORDS[COMP_CWORD]}"
-    prev="${COMP_WORDS[COMP_CWORD-1]}"
-
-    # Complete profile names after -p / --profile
-    if [[ "$prev" == "-p" || "$prev" == "--profile" ]]; then
-        COMPREPLY=($(compgen -W "$(_hermes_profiles)" -- "$cur"))
-        return
-    fi
-
-    # Complete profile subcommands
-    if [[ "${COMP_WORDS[1]}" == "profile" ]]; then
-        case "$prev" in
-            profile)
-                COMPREPLY=($(compgen -W "list use create delete show alias rename export import" -- "$cur"))
-                return
-                ;;
-            use|delete|show|alias|rename|export)
-                COMPREPLY=($(compgen -W "$(_hermes_profiles)" -- "$cur"))
-                return
-                ;;
-        esac
-    fi
-
-    # Top-level subcommands
-    if [[ "$COMP_CWORD" == 1 ]]; then
-        local commands="chat model gateway setup status cron doctor config skills tools mcp sessions profile update version"
-        COMPREPLY=($(compgen -W "$commands" -- "$cur"))
-    fi
-}
-
-complete -F _hermes_completion hermes
-'''
-
-
-def generate_zsh_completion() -> str:
-    """Generate a zsh completion script for hermes profile names."""
-    return '''#compdef hermes
-# Hermes Agent profile completion
-# Add to ~/.zshrc: eval "$(hermes completion zsh)"
-
-_hermes() {
-    local -a profiles
-    profiles=(default)
-    if [[ -d "$HOME/.hermes/profiles" ]]; then
-        profiles+=("${(@f)$(ls $HOME/.hermes/profiles 2>/dev/null)}")
-    fi
-
-    _arguments \\
-        '-p[Profile name]:profile:($profiles)' \\
-        '--profile[Profile name]:profile:($profiles)' \\
-        '1:command:(chat model gateway setup status cron doctor config skills tools mcp sessions profile update version)' \\
-        '*::arg:->args'
-
-    case $words[1] in
-        profile)
-            _arguments '1:action:(list use create delete show alias rename export import)' \\
-                        '2:profile:($profiles)'
-            ;;
-    esac
-}
-
-_hermes "$@"
-'''
-
-
-# ---------------------------------------------------------------------------
-# Profile env resolution (called from _apply_profile_override)
-# ---------------------------------------------------------------------------
-
-def resolve_profile_env(profile_name: str) -> str:
-    """Resolve a profile name to a HERMES_HOME path string.
-
-    Called early in the CLI entry point, before any hermes modules
-    are imported, to set the HERMES_HOME environment variable.
-    """
-    validate_profile_name(profile_name)
-    profile_dir = get_profile_dir(profile_name)
-
-    if profile_name != "default" and not profile_dir.is_dir():
-        raise FileNotFoundError(
-            f"Profile '{profile_name}' does not exist. "
-            f"Create it with: hermes profile create {profile_name}"
-        )
-
-    return str(profile_dir)

hermes_cli/setup.py

@@ -289,7 +289,6 @@ from hermes_cli.config import (
     get_env_value,
     ensure_hermes_home,
 )
-# display_hermes_home imported lazily at call sites (stale-module safety during hermes update)
 
 from hermes_cli.colors import Colors, color
 
@@ -586,11 +585,11 @@ def _print_setup_summary(config: dict, hermes_home):
     else:
         tool_status.append(("Mixture of Agents", False, "OPENROUTER_API_KEY"))
 
-    # Web tools (Exa, Parallel, Firecrawl, or Tavily)
-    if get_env_value("EXA_API_KEY") or get_env_value("PARALLEL_API_KEY") or get_env_value("FIRECRAWL_API_KEY") or get_env_value("FIRECRAWL_API_URL") or get_env_value("TAVILY_API_KEY"):
+    # Web tools (Parallel, Firecrawl, or Tavily)
+    if get_env_value("PARALLEL_API_KEY") or get_env_value("FIRECRAWL_API_KEY") or get_env_value("FIRECRAWL_API_URL") or get_env_value("TAVILY_API_KEY"):
         tool_status.append(("Web Search & Extract", True, None))
     else:
-        tool_status.append(("Web Search & Extract", False, "EXA_API_KEY, PARALLEL_API_KEY, FIRECRAWL_API_KEY, or TAVILY_API_KEY"))
+        tool_status.append(("Web Search & Extract", False, "PARALLEL_API_KEY, FIRECRAWL_API_KEY, or TAVILY_API_KEY"))
 
     # Browser tools (local Chromium or Browserbase cloud)
     import shutil
@@ -684,8 +683,7 @@ def _print_setup_summary(config: dict, hermes_home):
         print_warning(
             "Some tools are disabled. Run 'hermes setup tools' to configure them,"
         )
-        from hermes_constants import display_hermes_home as _dhh
-        print_warning(f"or edit {_dhh()}/.env directly to add the missing API keys.")
+        print_warning("or edit ~/.hermes/.env directly to add the missing API keys.")
         print()
 
     # Done banner
@@ -708,8 +706,7 @@ def _print_setup_summary(config: dict, hermes_home):
     print()
 
     # Show file locations prominently
-    from hermes_constants import display_hermes_home as _dhh
-    print(color(f"📁 All your files are in {_dhh()}/:", Colors.CYAN, Colors.BOLD))
+    print(color("📁 All your files are in ~/.hermes/:", Colors.CYAN, Colors.BOLD))
     print()
     print(f"   {color('Settings:', Colors.YELLOW)}  {get_config_path()}")
     print(f"   {color('API Keys:', Colors.YELLOW)}  {get_env_path()}")
@@ -2840,8 +2837,7 @@ def setup_gateway(config: dict):
         save_env_value("WEBHOOK_ENABLED", "true")
         print()
         print_success("Webhooks enabled! Next steps:")
-        from hermes_constants import display_hermes_home as _dhh
-        print_info(f"   1. Define webhook routes in {_dhh()}/config.yaml")
+        print_info("   1. Define webhook routes in ~/.hermes/config.yaml")
         print_info("   2. Point your service (GitHub, GitLab, etc.) at:")
         print_info("      http://your-server:8644/webhooks/<route-name>")
         print()

hermes_cli/skills_hub.py

@@ -21,7 +21,6 @@ from rich.table import Table
 
 # Lazy imports to avoid circular dependencies and slow startup.
 # tools.skills_hub and tools.skills_guard are imported inside functions.
-from hermes_constants import display_hermes_home
 
 _console = Console()
 
@@ -389,7 +388,7 @@ def do_install(identifier: str, category: str = "", force: bool = False,
                 "[bold bright_cyan]This is an official optional skill maintained by Nous Research.[/]\n\n"
                 "It ships with hermes-agent but is not activated by default.\n"
                 "Installing will copy it to your skills directory where the agent can use it.\n\n"
-                f"Files will be at: [cyan]{display_hermes_home()}/skills/{category + '/' if category else ''}{bundle.name}/[/]",
+                f"Files will be at: [cyan]~/.hermes/skills/{category + '/' if category else ''}{bundle.name}/[/]",
                 title="Official Skill",
                 border_style="bright_cyan",
             ))
@@ -399,7 +398,7 @@ def do_install(identifier: str, category: str = "", force: bool = False,
                 "External skills can contain instructions that influence agent behavior,\n"
                 "shell commands, and scripts. Even after automated scanning, you should\n"
                 "review the installed files before use.\n\n"
-                f"Files will be at: [cyan]{display_hermes_home()}/skills/{category + '/' if category else ''}{bundle.name}/[/]",
+                f"Files will be at: [cyan]~/.hermes/skills/{category + '/' if category else ''}{bundle.name}/[/]",
                 title="Disclaimer",
                 border_style="yellow",
             ))
@@ -745,7 +744,7 @@ def do_publish(skill_path: str, target: str = "github", repo: str = "",
         auth = GitHubAuth()
         if not auth.is_authenticated():
             c.print("[bold red]Error:[/] GitHub authentication required.\n"
-                    f"Set GITHUB_TOKEN in {display_hermes_home()}/.env or run 'gh auth login'.\n")
+                    "Set GITHUB_TOKEN in ~/.hermes/.env or run 'gh auth login'.\n")
             return
 
         c.print(f"[bold]Publishing '{name}' to {repo}...[/]")
@@ -888,15 +887,10 @@ def do_snapshot_export(output_path: str, console: Optional[Console] = None) -> N
         "taps": tap_list,
     }
 
-    payload = json.dumps(snapshot, indent=2, ensure_ascii=False) + "\n"
-    if output_path == "-":
-        import sys
-        sys.stdout.write(payload)
-    else:
-        out = Path(output_path)
-        out.write_text(payload)
-        c.print(f"[bold green]Snapshot exported:[/] {out}")
-        c.print(f"[dim]{len(installed)} skill(s), {len(tap_list)} tap(s)[/]\n")
+    out = Path(output_path)
+    out.write_text(json.dumps(snapshot, indent=2, ensure_ascii=False) + "\n")
+    c.print(f"[bold green]Snapshot exported:[/] {out}")
+    c.print(f"[dim]{len(installed)} skill(s), {len(tap_list)} tap(s)[/]\n")
 
 
 def do_snapshot_import(input_path: str, force: bool = False,

hermes_cli/tools_config.py

@@ -9,8 +9,6 @@ Saves per-platform tool configuration to ~/.hermes/config.yaml under
 the `platform_toolsets` key.
 """
 
-import json as _json
-import logging
 import sys
 from pathlib import Path
 from typing import Dict, List, Optional, Set
@@ -21,8 +19,6 @@ from hermes_cli.config import (
 )
 from hermes_cli.colors import Colors, color
 
-logger = logging.getLogger(__name__)
-
 PROJECT_ROOT = Path(__file__).parent.parent.resolve()
 
 
@@ -194,14 +190,6 @@ TOOL_CATEGORIES = {
                     {"key": "FIRECRAWL_API_KEY", "prompt": "Firecrawl API key", "url": "https://firecrawl.dev"},
                 ],
             },
-            {
-                "name": "Exa",
-                "tag": "AI-native search and contents",
-                "web_backend": "exa",
-                "env_vars": [
-                    {"key": "EXA_API_KEY", "prompt": "Exa API key", "url": "https://exa.ai"},
-                ],
-            },
             {
                 "name": "Parallel",
                 "tag": "AI-native search and extract",
@@ -330,8 +318,7 @@ def _run_post_setup(post_setup_key: str):
             if result.returncode == 0:
                 _print_success("    Node.js dependencies installed")
             else:
-                from hermes_constants import display_hermes_home
-                _print_warning(f"    npm install failed - run manually: cd {display_hermes_home()}/hermes-agent && npm install")
+                _print_warning("    npm install failed - run manually: cd ~/.hermes/hermes-agent && npm install")
         elif not node_modules.exists():
             _print_warning("    Node.js not found - browser tools require: npm install (in hermes-agent directory)")
 
@@ -657,61 +644,9 @@ def _prompt_choice(question: str, choices: list, default: int = 0) -> int:
             return default
 
 
-# ─── Token Estimation ────────────────────────────────────────────────────────
-
-# Module-level cache so discovery + tokenization runs at most once per process.
-_tool_token_cache: Optional[Dict[str, int]] = None
-
-
-def _estimate_tool_tokens() -> Dict[str, int]:
-    """Return estimated token counts per individual tool name.
-
-    Uses tiktoken (cl100k_base) to count tokens in the JSON-serialised
-    OpenAI-format tool schema.  Triggers tool discovery on first call,
-    then caches the result for the rest of the process.
-
-    Returns an empty dict when tiktoken or the registry is unavailable.
-    """
-    global _tool_token_cache
-    if _tool_token_cache is not None:
-        return _tool_token_cache
-
-    try:
-        import tiktoken
-        enc = tiktoken.get_encoding("cl100k_base")
-    except Exception:
-        logger.debug("tiktoken unavailable; skipping tool token estimation")
-        _tool_token_cache = {}
-        return _tool_token_cache
-
-    try:
-        # Trigger full tool discovery (imports all tool modules).
-        import model_tools  # noqa: F401
-        from tools.registry import registry
-    except Exception:
-        logger.debug("Tool registry unavailable; skipping token estimation")
-        _tool_token_cache = {}
-        return _tool_token_cache
-
-    counts: Dict[str, int] = {}
-    for name in registry.get_all_tool_names():
-        schema = registry.get_schema(name)
-        if schema:
-            # Mirror what gets sent to the API:
-            # {"type": "function", "function": <schema>}
-            text = _json.dumps({"type": "function", "function": schema})
-            counts[name] = len(enc.encode(text))
-    _tool_token_cache = counts
-    return _tool_token_cache
-
-
 def _prompt_toolset_checklist(platform_label: str, enabled: Set[str]) -> Set[str]:
     """Multi-select checklist of toolsets. Returns set of selected toolset keys."""
     from hermes_cli.curses_ui import curses_checklist
-    from toolsets import resolve_toolset
-
-    # Pre-compute per-tool token counts (cached after first call).
-    tool_tokens = _estimate_tool_tokens()
 
     effective = _get_effective_configurable_toolsets()
 
@@ -727,27 +662,11 @@ def _prompt_toolset_checklist(platform_label: str, enabled: Set[str]) -> Set[str
         if ts_key in enabled
     }
 
-    # Build a live status function that shows deduplicated total token cost.
-    status_fn = None
-    if tool_tokens:
-        ts_keys = [ts_key for ts_key, _, _ in effective]
-
-        def status_fn(chosen: set) -> str:
-            # Collect unique tool names across all selected toolsets
-            all_tools: set = set()
-            for idx in chosen:
-                all_tools.update(resolve_toolset(ts_keys[idx]))
-            total = sum(tool_tokens.get(name, 0) for name in all_tools)
-            if total >= 1000:
-                return f"Est. tool context: ~{total / 1000:.1f}k tokens"
-            return f"Est. tool context: ~{total} tokens"
-
     chosen = curses_checklist(
         f"Tools for {platform_label}",
         labels,
         pre_selected,
         cancel_returns=pre_selected,
-        status_fn=status_fn,
     )
     return {effective[i][0] for i in chosen}
 
@@ -1337,8 +1256,7 @@ def tools_command(args=None, first_install: bool = False, config: dict = None):
         platform_choices[idx] = f"Configure {pinfo['label']}  ({new_count}/{total} enabled)"
 
     print()
-    from hermes_constants import display_hermes_home
-    print(color(f"  Tool configuration saved to {display_hermes_home()}/config.yaml", Colors.DIM))
+    print(color("  Tool configuration saved to ~/.hermes/config.yaml", Colors.DIM))
     print(color("  Changes take effect on next 'hermes' or gateway restart.", Colors.DIM))
     print()
 

hermes_cli/webhook.py

@@ -18,8 +18,6 @@ import time
 from pathlib import Path
 from typing import Dict, Optional
 
-from hermes_constants import display_hermes_home
-
 
 _SUBSCRIPTIONS_FILENAME = "webhook_subscriptions.json"
 
@@ -78,15 +76,13 @@ def _get_webhook_base_url() -> str:
     return f"http://{display_host}:{port}"
 
 
-def _setup_hint() -> str:
-    _dhh = display_hermes_home()
-    return f"""
+_SETUP_HINT = """
   Webhook platform is not enabled. To set it up:
 
   1. Run the gateway setup wizard:
      hermes gateway setup
 
-  2. Or manually add to {_dhh}/config.yaml:
+  2. Or manually add to ~/.hermes/config.yaml:
      platforms:
        webhook:
          enabled: true
@@ -95,7 +91,7 @@ def _setup_hint() -> str:
            port: 8644
            secret: "your-global-hmac-secret"
 
-  3. Or set environment variables in {_dhh}/.env:
+  3. Or set environment variables in ~/.hermes/.env:
      WEBHOOK_ENABLED=true
      WEBHOOK_PORT=8644
      WEBHOOK_SECRET=your-global-secret
@@ -108,7 +104,7 @@ def _require_webhook_enabled() -> bool:
     """Check webhook is enabled. Print setup guide and return False if not."""
     if _is_webhook_enabled():
         return True
-    print(_setup_hint())
+    print(_SETUP_HINT)
     return False
 
 

hermes_constants.py

@@ -38,26 +38,6 @@ def get_hermes_dir(new_subpath: str, old_name: str) -> Path:
     return home / new_subpath
 
 
-def display_hermes_home() -> str:
-    """Return a user-friendly display string for the current HERMES_HOME.
-
-    Uses ``~/`` shorthand for readability::
-
-        default:  ``~/.hermes``
-        profile:  ``~/.hermes/profiles/coder``
-        custom:   ``/opt/hermes-custom``
-
-    Use this in **user-facing** print/log messages instead of hardcoding
-    ``~/.hermes``.  For code that needs a real ``Path``, use
-    :func:`get_hermes_home` instead.
-    """
-    home = get_hermes_home()
-    try:
-        return "~/" + str(home.relative_to(Path.home()))
-    except ValueError:
-        return str(home)
-
-
 VALID_REASONING_EFFORTS = ("xhigh", "high", "medium", "low", "minimal")
 
 

honcho_integration/cli.py

@@ -270,7 +270,7 @@ def cmd_status(args) -> None:
             print(f"    {peer}: {mode}")
     print(f"  Write freq:     {hcfg.write_frequency}")
 
-    if hcfg.enabled and (hcfg.api_key or hcfg.base_url):
+    if hcfg.enabled and hcfg.api_key:
         print("\n  Connection... ", end="", flush=True)
         try:
             get_honcho_client(hcfg)
@@ -278,7 +278,7 @@ def cmd_status(args) -> None:
         except Exception as e:
             print(f"FAILED ({e})\n")
     else:
-        reason = "disabled" if not hcfg.enabled else "no API key or base URL"
+        reason = "disabled" if not hcfg.enabled else "no API key"
         print(f"\n  Not connected ({reason})\n")
 
 

honcho_integration/client.py

@@ -417,18 +417,9 @@ def get_honcho_client(config: HonchoClientConfig | None = None) -> Honcho:
     else:
         logger.info("Initializing Honcho client (host: %s, workspace: %s)", config.host, config.workspace_id)
 
-    # Local Honcho instances don't require an API key, but the SDK
-    # expects a non-empty string.  Use a placeholder for local URLs.
-    _is_local = resolved_base_url and (
-        "localhost" in resolved_base_url
-        or "127.0.0.1" in resolved_base_url
-        or "::1" in resolved_base_url
-    )
-    effective_api_key = config.api_key or ("local" if _is_local else None)
-
     kwargs: dict = {
         "workspace_id": config.workspace_id,
-        "api_key": effective_api_key,
+        "api_key": config.api_key,
         "environment": config.environment,
     }
     if resolved_base_url:

keystore/__init__.py

@@ -0,0 +1,15 @@
+"""hermes-keystore — encrypted secret store for Hermes Agent.
+
+Provides an encrypted SQLite-backed secret store with per-secret
+AEAD encryption (XChaCha20-Poly1305), a master key derived from
+a user passphrase via Argon2id, cross-platform credential caching,
+and secret categorisation (injectable / gated / sealed / user_only).
+
+Architecture:
+    keystore/store.py            — core encrypted store
+    keystore/credential_store.py — cross-platform passphrase caching
+    keystore/client.py           — high-level API (unlock, inject, get)
+    keystore/categories.py       — secret category definitions
+    keystore/migrations.py       — DB schema migrations
+    keystore/cli.py              — `hermes keystore` subcommands
+"""

keystore/categories.py

@@ -0,0 +1,111 @@
+"""Secret categories — access control classifications.
+
+Every secret in the keystore belongs to one of four categories that
+determine how and whether the agent process can access it.
+"""
+
+from enum import Enum
+from typing import Dict
+
+
+class SecretCategory(str, Enum):
+    """Access control classification for keystore secrets."""
+
+    INJECTABLE = "injectable"
+    """Auto-injected into os.environ at agent startup.
+
+    The agent code reads these via os.getenv() as before.
+    No plaintext file on disk — the daemon populates env vars
+    in the child process.
+
+    Examples: OPENROUTER_API_KEY, FAL_KEY, PARALLEL_API_KEY
+    """
+
+    GATED = "gated"
+    """Available on request through the daemon, with logging.
+
+    The agent can ask for these via the keystore client, but every
+    access is logged.  Optionally requires user approval per-access.
+
+    Examples: GITHUB_TOKEN, SSH private keys
+    """
+
+    SEALED = "sealed"
+    """Never exposed to the agent process in any form.
+
+    The daemon uses these internally (e.g., wallet private keys)
+    and the agent interacts through session tokens or tool results.
+
+    Examples: wallet private keys, master passwords
+    """
+
+    USER_ONLY = "user_only"
+    """Accessible only via the CLI, never by the agent or gateway.
+
+    These are secrets the user manages directly and the agent
+    should never see, even through gated access.
+
+    Examples: SUDO_PASSWORD, backup encryption keys
+    """
+
+
+# Default category assignments for known env var names.
+# Anything not listed defaults to INJECTABLE for backward compatibility.
+DEFAULT_CATEGORIES: Dict[str, SecretCategory] = {
+    # Provider API keys — injectable (agent needs them for LLM calls)
+    "OPENROUTER_API_KEY": SecretCategory.INJECTABLE,
+    "ANTHROPIC_API_KEY": SecretCategory.INJECTABLE,
+    "OPENAI_API_KEY": SecretCategory.INJECTABLE,
+    "GLM_API_KEY": SecretCategory.INJECTABLE,
+    "ZAI_API_KEY": SecretCategory.INJECTABLE,
+    "Z_AI_API_KEY": SecretCategory.INJECTABLE,
+    "KIMI_API_KEY": SecretCategory.INJECTABLE,
+    "MINIMAX_API_KEY": SecretCategory.INJECTABLE,
+    "MINIMAX_CN_API_KEY": SecretCategory.INJECTABLE,
+    "OPENCODE_ZEN_API_KEY": SecretCategory.INJECTABLE,
+    "OPENCODE_GO_API_KEY": SecretCategory.INJECTABLE,
+    "DASHSCOPE_API_KEY": SecretCategory.INJECTABLE,
+    "COPILOT_API_KEY": SecretCategory.INJECTABLE,
+
+    # Tool API keys — injectable
+    "PARALLEL_API_KEY": SecretCategory.INJECTABLE,
+    "FIRECRAWL_API_KEY": SecretCategory.INJECTABLE,
+    "FAL_KEY": SecretCategory.INJECTABLE,
+    "BROWSERBASE_API_KEY": SecretCategory.INJECTABLE,
+    "HONCHO_API_KEY": SecretCategory.INJECTABLE,
+
+    # Messaging platform tokens — injectable (gateway needs them)
+    "TELEGRAM_BOT_TOKEN": SecretCategory.INJECTABLE,
+    "DISCORD_BOT_TOKEN": SecretCategory.INJECTABLE,
+    "SLACK_BOT_TOKEN": SecretCategory.INJECTABLE,
+    "SLACK_APP_TOKEN": SecretCategory.INJECTABLE,
+    "WHATSAPP_API_TOKEN": SecretCategory.INJECTABLE,
+    "SIGNAL_HTTP_URL": SecretCategory.INJECTABLE,
+    "MATTERMOST_TOKEN": SecretCategory.INJECTABLE,
+    "MATRIX_PASSWORD": SecretCategory.INJECTABLE,
+    "DINGTALK_CLIENT_ID": SecretCategory.INJECTABLE,
+    "DINGTALK_CLIENT_SECRET": SecretCategory.INJECTABLE,
+    "TWILIO_ACCOUNT_SID": SecretCategory.INJECTABLE,
+    "TWILIO_AUTH_TOKEN": SecretCategory.INJECTABLE,
+
+    # Gated — logged access, optional approval
+    "GITHUB_TOKEN": SecretCategory.GATED,
+
+    # User-only — never exposed to agent
+    "SUDO_PASSWORD": SecretCategory.USER_ONLY,
+
+    # Sealed — wallet keys use a different naming convention
+    # (wallet:chain:address) and are always sealed.
+}
+
+
+def default_category(secret_name: str) -> SecretCategory:
+    """Return the default category for a secret name.
+
+    Wallet keys (prefixed with ``wallet:``) are always SEALED.
+    Known env vars use the mapping above.
+    Everything else defaults to INJECTABLE for backward compatibility.
+    """
+    if secret_name.startswith("wallet:"):
+        return SecretCategory.SEALED
+    return DEFAULT_CATEGORIES.get(secret_name, SecretCategory.INJECTABLE)

keystore/cli.py

@@ -0,0 +1,507 @@
+"""CLI subcommands for ``hermes keystore``.
+
+Provides:
+    hermes keystore init              — Create a new keystore
+    hermes keystore list              — List stored secrets (no values)
+    hermes keystore set <name>        — Add or update a secret
+    hermes keystore show <name>       — Decrypt and display a secret
+    hermes keystore delete <name>     — Remove a secret
+    hermes keystore set-category      — Change a secret's access category
+    hermes keystore migrate           — Import from .env
+    hermes keystore remember          — Cache passphrase in OS credential store
+    hermes keystore forget            — Remove cached passphrase
+    hermes keystore change-passphrase — Re-encrypt with a new passphrase
+    hermes keystore audit             — Show access log
+    hermes keystore status            — Show keystore status
+"""
+
+import argparse
+import getpass
+import os
+import shutil
+import sys
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+try:
+    from rich.console import Console
+    from rich.table import Table
+    _RICH = True
+except ImportError:
+    _RICH = False
+
+
+def _cprint(msg: str, style: str = "") -> None:
+    """Print with optional Rich styling, falling back to plain."""
+    if _RICH:
+        Console().print(msg, style=style)
+    else:
+        print(msg)
+
+
+def _get_client():
+    """Import and return the keystore client (lazy to avoid import errors
+    when keystore deps aren't installed)."""
+    try:
+        from keystore.client import get_keystore
+        return get_keystore()
+    except ImportError as e:
+        _cprint(
+            f"\n  ✗ Keystore dependencies not installed: {e}\n"
+            f"    Install with: pip install 'hermes-agent[keystore]'\n",
+            style="bold red",
+        )
+        sys.exit(1)
+
+
+def _require_unlocked(ks, interactive: bool = True) -> None:
+    """Ensure the keystore is unlocked or exit."""
+    from keystore.store import PassphraseMismatch, KeystoreLocked
+    try:
+        if not ks.ensure_unlocked(interactive=interactive):
+            _cprint("\n  Keystore not initialized. Run: hermes keystore init\n", style="yellow")
+            sys.exit(1)
+    except PassphraseMismatch:
+        _cprint("\n  ✗ Incorrect passphrase\n", style="bold red")
+        sys.exit(1)
+    except KeystoreLocked as e:
+        _cprint(f"\n  ✗ {e}\n", style="bold red")
+        sys.exit(1)
+
+
+# =========================================================================
+# Subcommand handlers
+# =========================================================================
+
+def cmd_keystore_init(args: argparse.Namespace) -> None:
+    """Create a new encrypted keystore."""
+    from keystore.store import KeystoreError
+    ks = _get_client()
+
+    if ks.is_initialized:
+        _cprint("\n  Keystore already initialized.", style="yellow")
+        count = ks.secret_count()
+        _cprint(f"  {count} secrets stored.\n")
+        return
+
+    _cprint("\n  🔐 Secure Keystore Setup\n")
+    _cprint("  Your API keys and secrets will be encrypted with a master passphrase.")
+    _cprint("  Choose something memorable — you'll need it each time you start Hermes.\n")
+
+    passphrase = getpass.getpass("  Passphrase: ")
+    if not passphrase:
+        _cprint("\n  ✗ Passphrase cannot be empty\n", style="bold red")
+        sys.exit(1)
+    confirm = getpass.getpass("  Confirm:    ")
+    if passphrase != confirm:
+        _cprint("\n  ✗ Passphrases don't match\n", style="bold red")
+        sys.exit(1)
+
+    try:
+        ks.initialize(passphrase)
+    except KeystoreError as e:
+        _cprint(f"\n  ✗ {e}\n", style="bold red")
+        sys.exit(1)
+
+    from keystore.client import _default_db_path
+    _cprint(f"\n  ✓ Keystore created at {_default_db_path()}", style="green")
+    _cprint("")
+    _cprint("  💡 Tip: Run 'hermes keystore remember' to cache your passphrase")
+    _cprint("     so you don't have to type it every time.\n")
+
+
+def cmd_keystore_list(args: argparse.Namespace) -> None:
+    """List all stored secrets (names and categories, no values)."""
+    ks = _get_client()
+    _require_unlocked(ks)
+
+    secrets = ks.list_secrets()
+    if not secrets:
+        _cprint("\n  No secrets stored. Use 'hermes keystore set <name>' to add one.\n")
+        return
+
+    if _RICH:
+        console = Console()
+        table = Table(title="Keystore Secrets", show_lines=False)
+        table.add_column("Name", style="cyan", no_wrap=True)
+        table.add_column("Category", style="magenta")
+        table.add_column("Description")
+        table.add_column("Last Accessed", style="dim")
+        table.add_column("Accesses", justify="right", style="dim")
+
+        _cat_style = {
+            "injectable": "green",
+            "gated": "yellow",
+            "sealed": "red",
+            "user_only": "blue",
+        }
+        for s in secrets:
+            cat_style = _cat_style.get(s.category, "white")
+            last = s.last_accessed_at[:10] if s.last_accessed_at else "never"
+            table.add_row(
+                s.name,
+                f"[{cat_style}]{s.category}[/{cat_style}]",
+                s.description or "",
+                last,
+                str(s.access_count),
+            )
+        console.print()
+        console.print(table)
+        console.print()
+    else:
+        print(f"\n  {'Name':<35} {'Category':<12} {'Description'}")
+        print(f"  {'─'*35} {'─'*12} {'─'*30}")
+        for s in secrets:
+            print(f"  {s.name:<35} {s.category:<12} {s.description or ''}")
+        print()
+
+
+def cmd_keystore_set(args: argparse.Namespace) -> None:
+    """Add or update a secret."""
+    ks = _get_client()
+    _require_unlocked(ks)
+
+    name = args.name.upper()
+    value = getpass.getpass(f"  Value for {name} (hidden): ")
+    if not value:
+        _cprint("\n  ✗ Value cannot be empty\n", style="bold red")
+        sys.exit(1)
+
+    category = args.category
+    description = args.description or ""
+
+    ks.set_secret(name, value, category=category, description=description)
+    _cprint(f"\n  ✓ Secret '{name}' stored (category: {category or 'auto'})\n", style="green")
+
+
+def cmd_keystore_show(args: argparse.Namespace) -> None:
+    """Decrypt and display a secret (requires passphrase re-entry)."""
+    ks = _get_client()
+    _require_unlocked(ks)
+
+    name = args.name.upper()
+
+    # Re-verify identity for sealed/user_only secrets
+    value = ks.get_secret(name, requester="cli")
+    if value is None:
+        _cprint(f"\n  ✗ Secret '{name}' not found or access denied\n", style="bold red")
+        sys.exit(1)
+
+    _cprint(f"\n  {name} = {value}\n")
+
+
+def cmd_keystore_delete(args: argparse.Namespace) -> None:
+    """Remove a secret."""
+    ks = _get_client()
+    _require_unlocked(ks)
+
+    name = args.name.upper()
+    if ks.delete_secret(name):
+        _cprint(f"\n  ✓ Secret '{name}' deleted\n", style="green")
+    else:
+        _cprint(f"\n  ✗ Secret '{name}' not found\n", style="bold red")
+
+
+def cmd_keystore_set_category(args: argparse.Namespace) -> None:
+    """Change a secret's access category."""
+    from keystore.store import KeystoreError
+    ks = _get_client()
+    _require_unlocked(ks)
+
+    name = args.name.upper()
+    category = args.category
+    try:
+        if ks.set_category(name, category):
+            _cprint(f"\n  ✓ {name} → {category}\n", style="green")
+        else:
+            _cprint(f"\n  ✗ Secret '{name}' not found\n", style="bold red")
+    except KeystoreError as e:
+        _cprint(f"\n  ✗ {e}\n", style="bold red")
+
+
+def cmd_keystore_migrate(args: argparse.Namespace) -> None:
+    """Migrate secrets from .env to the keystore."""
+    ks = _get_client()
+
+    # Initialize if needed
+    if not ks.is_initialized:
+        _cprint("\n  🔐 Keystore not initialized — setting up now.\n")
+        passphrase = getpass.getpass("  Choose a passphrase: ")
+        if not passphrase:
+            _cprint("\n  ✗ Passphrase cannot be empty\n", style="bold red")
+            sys.exit(1)
+        confirm = getpass.getpass("  Confirm:              ")
+        if passphrase != confirm:
+            _cprint("\n  ✗ Passphrases don't match\n", style="bold red")
+            sys.exit(1)
+        ks.initialize(passphrase)
+        _cprint("  ✓ Keystore created\n", style="green")
+    else:
+        _require_unlocked(ks)
+
+    from keystore.client import _env_file_path
+    env_path = _env_file_path()
+    if not env_path.exists():
+        _cprint(f"\n  No .env file found at {env_path}\n", style="yellow")
+        return
+
+    migrated = ks.migrate_from_env(env_path)
+    if not migrated:
+        _cprint("\n  No secrets found in .env to migrate.\n", style="yellow")
+        return
+
+    _cprint(f"\n  📦 Migrated {len(migrated)} secrets:\n")
+    for name, category in sorted(migrated.items()):
+        _cprint(f"    {name:<35} → {category}")
+
+    # Backup and replace .env
+    if not args.keep_env:
+        backup_path = env_path.with_suffix(
+            f".bak.{datetime.now().strftime('%Y%m%d_%H%M%S')}"
+        )
+        shutil.copy2(env_path, backup_path)
+        _cprint(f"\n  ✓ Original .env backed up to {backup_path.name}", style="green")
+
+        # Write stub
+        with open(env_path, "w") as f:
+            f.write(
+                "# Secrets are now managed by the Hermes encrypted keystore.\n"
+                "# Run 'hermes keystore list' to see stored secrets.\n"
+                "# Run 'hermes keystore set <NAME>' to add/update a secret.\n"
+                "#\n"
+                "# You can still set env vars here for non-secret config,\n"
+                "# or export secrets in your shell for CI/Docker environments.\n"
+                "# Shell exports always take priority over the keystore.\n"
+            )
+        _cprint("  ✓ .env replaced with stub (keystore handles secrets now)", style="green")
+
+    _cprint(f"\n  ✓ Migration complete\n", style="bold green")
+    _cprint("  Review categories with: hermes keystore list")
+    _cprint("  Change a category:      hermes keystore set-category <NAME> <CATEGORY>\n")
+
+
+def cmd_keystore_remember(args: argparse.Namespace) -> None:
+    """Cache the passphrase in the OS credential store."""
+    from keystore import credential_store
+
+    ks = _get_client()
+
+    backend = credential_store.backend_name()
+    if backend:
+        _cprint(f"\n  Detected: {backend}\n")
+    else:
+        _cprint("\n  ⚠️  No credential store backend available.\n", style="yellow")
+        _cprint("  Options:")
+        _cprint("    • Set HERMES_KEYSTORE_PASSPHRASE env var for headless/Docker")
+        _cprint("    • Install keyring: pip install keyring")
+        if sys.platform == "linux":
+            _cprint("    • Install keyctl: apt install keyutils")
+        _cprint("    • Type your passphrase each time (most secure)\n")
+        return
+
+    passphrase = getpass.getpass("  Keystore passphrase: ")
+    if not passphrase:
+        _cprint("\n  ✗ Cancelled\n", style="yellow")
+        return
+
+    success, msg = ks.remember_passphrase(passphrase)
+    if success:
+        _cprint(f"\n  ✓ Passphrase saved to {msg}", style="green")
+        _cprint("  To remove: hermes keystore forget\n")
+
+        # Backend-specific notes
+        if "Kernel Keyring" in msg:
+            _cprint(
+                "  ⚠️  Note: kernel keyring may expire after inactivity.\n"
+                "     For always-on gateway deployments, consider\n"
+                "     HERMES_KEYSTORE_PASSPHRASE env var instead.\n",
+                style="dim",
+            )
+        elif "Encrypted File" in msg:
+            _cprint(
+                "  ⚠️  This uses machine-derived encryption.\n"
+                "     Less secure than a system keychain, but works everywhere.\n",
+                style="dim",
+            )
+    else:
+        _cprint(f"\n  ✗ {msg}\n", style="bold red")
+
+
+def cmd_keystore_forget(args: argparse.Namespace) -> None:
+    """Remove the cached passphrase."""
+    ks = _get_client()
+    success, msg = ks.forget_passphrase()
+    if success:
+        _cprint(f"\n  ✓ Passphrase removed from {msg}\n", style="green")
+    else:
+        _cprint(f"\n  ✗ {msg}\n", style="yellow")
+
+
+def cmd_keystore_change_passphrase(args: argparse.Namespace) -> None:
+    """Change the master passphrase."""
+    from keystore.store import PassphraseMismatch
+    ks = _get_client()
+
+    if not ks.is_initialized:
+        _cprint("\n  Keystore not initialized. Run: hermes keystore init\n", style="yellow")
+        return
+
+    old = getpass.getpass("  Current passphrase: ")
+    new = getpass.getpass("  New passphrase:     ")
+    if not new:
+        _cprint("\n  ✗ Passphrase cannot be empty\n", style="bold red")
+        return
+    confirm = getpass.getpass("  Confirm new:        ")
+    if new != confirm:
+        _cprint("\n  ✗ Passphrases don't match\n", style="bold red")
+        return
+
+    try:
+        ks.change_passphrase(old, new)
+        _cprint("\n  ✓ Passphrase changed successfully\n", style="green")
+        _cprint("  💡 If you used 'hermes keystore remember', run it again to update.\n")
+    except PassphraseMismatch:
+        _cprint("\n  ✗ Current passphrase is incorrect\n", style="bold red")
+
+
+def cmd_keystore_audit(args: argparse.Namespace) -> None:
+    """Show the access log."""
+    ks = _get_client()
+    _require_unlocked(ks)
+
+    entries = ks.get_access_log(limit=args.limit)
+    if not entries:
+        _cprint("\n  No access log entries.\n")
+        return
+
+    if _RICH:
+        console = Console()
+        table = Table(title="Keystore Access Log", show_lines=False)
+        table.add_column("Time", style="dim", no_wrap=True)
+        table.add_column("Secret", style="cyan")
+        table.add_column("Action")
+        table.add_column("Requester", style="magenta")
+
+        _action_style = {
+            "read": "green",
+            "write": "blue",
+            "inject": "green",
+            "denied": "bold red",
+            "delete": "yellow",
+        }
+        for e in entries:
+            ts = e["timestamp"][:19].replace("T", " ")
+            action = e["action"]
+            style = _action_style.get(action, "white")
+            table.add_row(ts, e["secret_name"], f"[{style}]{action}[/{style}]", e["requester"] or "")
+        console.print()
+        console.print(table)
+        console.print()
+    else:
+        print(f"\n  {'Time':<20} {'Secret':<35} {'Action':<8} {'Requester'}")
+        print(f"  {'─'*20} {'─'*35} {'─'*8} {'─'*12}")
+        for e in entries:
+            ts = e["timestamp"][:19].replace("T", " ")
+            print(f"  {ts:<20} {e['secret_name']:<35} {e['action']:<8} {e['requester'] or ''}")
+        print()
+
+
+def cmd_keystore_status(args: argparse.Namespace) -> None:
+    """Show keystore status."""
+    from keystore import credential_store
+    ks = _get_client()
+
+    _cprint("\n  🔐 Keystore Status\n")
+
+    if not ks.is_initialized:
+        _cprint("  Status:      Not initialized", style="yellow")
+        _cprint("  Run:         hermes keystore init\n")
+        return
+
+    count = ks.secret_count()
+    _cprint(f"  Status:      {'Unlocked' if ks.is_unlocked else 'Locked'}")
+    _cprint(f"  Secrets:     {count}")
+
+    from keystore.client import _default_db_path
+    db_path = _default_db_path()
+    if db_path.exists():
+        size_kb = db_path.stat().st_size / 1024
+        _cprint(f"  DB path:     {db_path}")
+        _cprint(f"  DB size:     {size_kb:.1f} KB")
+
+    backend = credential_store.backend_name()
+    cached = credential_store.retrieve_passphrase() is not None if backend else False
+    _cprint(f"  Cred store:  {backend or 'None available'}")
+    if backend:
+        _cprint(f"  Passphrase:  {'Cached' if cached else 'Not cached'}")
+
+    _cprint("")
+
+
+# =========================================================================
+# Argparse registration (called from hermes_cli/main.py)
+# =========================================================================
+
+def register_subparser(subparsers: argparse._SubParsersAction) -> None:
+    """Register the ``hermes keystore`` subcommand tree."""
+    keystore_parser = subparsers.add_parser(
+        "keystore",
+        help="Manage the encrypted secret store",
+        description="Encrypted keystore for API keys, tokens, and wallet secrets.",
+    )
+    keystore_parser.set_defaults(func=cmd_keystore_status)
+
+    ks_sub = keystore_parser.add_subparsers(dest="keystore_command")
+
+    # init
+    ks_sub.add_parser("init", help="Create a new keystore").set_defaults(func=cmd_keystore_init)
+
+    # list
+    ks_sub.add_parser("list", aliases=["ls"], help="List stored secrets").set_defaults(func=cmd_keystore_list)
+
+    # set
+    set_p = ks_sub.add_parser("set", aliases=["add"], help="Add or update a secret")
+    set_p.add_argument("name", help="Secret name (e.g. OPENROUTER_API_KEY)")
+    set_p.add_argument("--category", "-c", default=None,
+                       choices=["injectable", "gated", "sealed", "user_only"],
+                       help="Access category (default: auto-detected)")
+    set_p.add_argument("--description", "-d", default="", help="Human-readable description")
+    set_p.set_defaults(func=cmd_keystore_set)
+
+    # show
+    show_p = ks_sub.add_parser("show", aliases=["get"], help="Decrypt and display a secret")
+    show_p.add_argument("name", help="Secret name")
+    show_p.set_defaults(func=cmd_keystore_show)
+
+    # delete
+    del_p = ks_sub.add_parser("delete", aliases=["rm", "remove"], help="Remove a secret")
+    del_p.add_argument("name", help="Secret name")
+    del_p.set_defaults(func=cmd_keystore_delete)
+
+    # set-category
+    cat_p = ks_sub.add_parser("set-category", help="Change a secret's access category")
+    cat_p.add_argument("name", help="Secret name")
+    cat_p.add_argument("category", choices=["injectable", "gated", "sealed", "user_only"])
+    cat_p.set_defaults(func=cmd_keystore_set_category)
+
+    # migrate
+    mig_p = ks_sub.add_parser("migrate", help="Import secrets from .env")
+    mig_p.add_argument("--keep-env", action="store_true",
+                       help="Don't replace .env with a stub after migration")
+    mig_p.set_defaults(func=cmd_keystore_migrate)
+
+    # remember / forget
+    ks_sub.add_parser("remember", help="Cache passphrase in OS credential store").set_defaults(func=cmd_keystore_remember)
+    ks_sub.add_parser("forget", help="Remove cached passphrase").set_defaults(func=cmd_keystore_forget)
+
+    # change-passphrase
+    ks_sub.add_parser("change-passphrase", help="Change master passphrase").set_defaults(func=cmd_keystore_change_passphrase)
+
+    # audit
+    audit_p = ks_sub.add_parser("audit", aliases=["log"], help="Show access log")
+    audit_p.add_argument("--limit", "-n", type=int, default=50, help="Number of entries (default: 50)")
+    audit_p.set_defaults(func=cmd_keystore_audit)
+
+    # status
+    ks_sub.add_parser("status", help="Show keystore status").set_defaults(func=cmd_keystore_status)

keystore/client.py

@@ -0,0 +1,439 @@
+"""High-level keystore client for CLI and agent integration.
+
+This is the main entry point for all keystore consumers.  It wraps
+EncryptedStore with:
+
+- Automatic path resolution (``~/.hermes/keystore/secrets.db``)
+- Unlock flow (credential store → env var → interactive prompt)
+- Injectable secret injection into ``os.environ``
+- .env migration helper
+- Singleton pattern (one client per process)
+
+Usage in CLI startup::
+
+    from keystore.client import get_keystore
+
+    ks = get_keystore()
+    ks.ensure_unlocked()         # prompts if needed
+    ks.inject_env()              # populates os.environ with injectable secrets
+
+Usage in gateway startup::
+
+    ks = get_keystore()
+    ks.ensure_unlocked(interactive=False)  # raises if can't auto-unlock
+    ks.inject_env()
+"""
+
+import getpass
+import logging
+import os
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+from keystore.store import (
+    EncryptedStore,
+    KeystoreError,
+    KeystoreLocked,
+    PassphraseMismatch,
+    SecretEntry,
+)
+from keystore import credential_store
+from keystore.categories import SecretCategory, default_category
+
+logger = logging.getLogger(__name__)
+
+
+def _hermes_home() -> Path:
+    return Path(os.getenv("HERMES_HOME", Path.home() / ".hermes"))
+
+
+def _default_db_path() -> Path:
+    return _hermes_home() / "keystore" / "secrets.db"
+
+
+def _env_file_path() -> Path:
+    return _hermes_home() / ".env"
+
+
+def _owned_env_names() -> set[str]:
+    raw = os.getenv("HERMES_KEYSTORE_OWNED_VARS", "")
+    return {x for x in raw.split(",") if x}
+
+
+def _set_owned_env_names(names: set[str]) -> None:
+    os.environ["HERMES_KEYSTORE_OWNED_VARS"] = ",".join(sorted(names))
+
+
+def _owned_env_values() -> dict[str, str]:
+    raw = os.getenv("HERMES_KEYSTORE_OWNED_VALUES_JSON", "")
+    if not raw:
+        return {}
+    try:
+        import json as _json
+        data = _json.loads(raw)
+        return data if isinstance(data, dict) else {}
+    except Exception:
+        return {}
+
+
+def _set_owned_env_values(values: dict[str, str]) -> None:
+    import json as _json
+    os.environ["HERMES_KEYSTORE_OWNED_VALUES_JSON"] = _json.dumps(values, sort_keys=True)
+
+
+class KeystoreClient:
+    """High-level keystore interface for CLI, gateway, and agent startup."""
+
+    def __init__(self, db_path: Optional[str | Path] = None):
+        path = Path(db_path) if db_path else _default_db_path()
+        self._store = EncryptedStore(path)
+        self._injected: Dict[str, bool] = {}
+
+    @property
+    def is_initialized(self) -> bool:
+        return self._store.is_initialized
+
+    @property
+    def is_unlocked(self) -> bool:
+        return self._store.is_unlocked
+
+    def initialize(self, passphrase: str) -> None:
+        """Initialize a new keystore with the given passphrase."""
+        self._store.initialize(passphrase)
+
+    def unlock(self, passphrase: str) -> None:
+        """Unlock with a known passphrase."""
+        self._store.unlock(passphrase)
+
+    def lock(self) -> None:
+        """Lock the keystore."""
+        self._store.lock()
+
+    def ensure_unlocked(self, interactive: bool = True) -> bool:
+        """Ensure the keystore is unlocked, trying all available methods.
+
+        Unlock priority:
+        1. Already unlocked → no-op
+        2. OS credential store (if ``hermes keystore remember`` was used)
+        3. Interactive passphrase prompt (if ``interactive=True``)
+        4. ``HERMES_KEYSTORE_PASSPHRASE`` env var (headless/Docker fallback only)
+
+        Returns True if unlocked, False if not initialized (caller should
+        set up the keystore), raises PassphraseMismatch on wrong passphrase.
+
+        When ``interactive=False`` (gateway/headless), raises KeystoreLocked
+        if no automatic unlock method succeeds.
+        """
+        if self._store.is_unlocked:
+            return True
+
+        if not self._store.is_initialized:
+            return False
+
+        # 1. Try credential store
+        passphrase = credential_store.retrieve_passphrase()
+        if passphrase:
+            try:
+                self._store.unlock(passphrase)
+                logger.debug("Unlocked via credential store (%s)", credential_store.backend_name())
+                return True
+            except PassphraseMismatch:
+                logger.warning(
+                    "Stored passphrase is stale (credential store: %s). "
+                    "Run 'hermes keystore remember' to update it.",
+                    credential_store.backend_name(),
+                )
+
+        # 2. Interactive prompt (preferred over env var when TTY is available)
+        if interactive:
+            max_attempts = 3
+            for attempt in range(max_attempts):
+                try:
+                    passphrase = getpass.getpass("🔐 Keystore passphrase: ")
+                    if not passphrase:
+                        continue
+                    self._store.unlock(passphrase)
+                    return True
+                except PassphraseMismatch:
+                    remaining = max_attempts - attempt - 1
+                    if remaining > 0:
+                        print(f"  ✗ Incorrect passphrase ({remaining} attempts remaining)")
+                    else:
+                        print("  ✗ Incorrect passphrase")
+
+            raise PassphraseMismatch("Too many incorrect passphrase attempts")
+
+        # 3. Env var — last resort for headless/Docker/systemd deployments
+        # where no TTY or credential store is available. The passphrase is
+        # visible in the process environment, so this is a conscious security
+        # tradeoff for unattended operation.
+        env_passphrase = os.getenv("HERMES_KEYSTORE_PASSPHRASE")
+        if env_passphrase:
+            try:
+                self._store.unlock(env_passphrase)
+                logger.debug("Unlocked via HERMES_KEYSTORE_PASSPHRASE env var (headless fallback)")
+                return True
+            except PassphraseMismatch:
+                logger.warning("HERMES_KEYSTORE_PASSPHRASE env var has wrong passphrase")
+
+        raise KeystoreLocked(
+            "Keystore is locked and no automatic unlock method succeeded. "
+            "Run 'hermes keystore remember' to cache the passphrase, or "
+            "set HERMES_KEYSTORE_PASSPHRASE env var for headless deployments."
+        )
+
+    def inject_env(self, force: bool = False, external_managed_names: Optional[set[str]] = None) -> Dict[str, bool]:
+        """Inject all ``injectable`` secrets into ``os.environ``.
+
+        Args:
+            force: Refresh mode for long-lived processes. When ``False``
+                (default), existing env vars are preserved so shell/Docker env
+                wins over keystore values at startup. When ``True``, only env
+                vars that were previously injected by this client instance are
+                refreshed.
+            external_managed_names: Optional set of env-var names that were
+                supplied by non-keystore sources during the current refresh
+                cycle and explicitly passed in by the caller. In the current
+                gateway implementation this is used for `.env`-tracked names.
+                This lets long-lived processes distinguish a stale injected
+                value from an external replacement even when the replacement
+                uses the same credential string.
+
+        Returns:
+            Dict of ``{secret_name: injected_or_overwritten}``.
+        """
+        secrets = self._store.get_injectable_secrets()
+        previous = dict(self._injected)
+        owned = _owned_env_names()
+        owned_values = _owned_env_values()
+        external_managed_names = set(external_managed_names or set())
+        injected = {}
+        current_names = set(secrets.keys())
+
+        # Force-refresh also acts as revocation for previously keystore-owned
+        # env vars that have been deleted from the keystore or are no longer
+        # injectable. Only revoke names that are still keystore-owned AND not
+        # externally managed in this refresh cycle.
+        if force:
+            removed = owned - current_names
+            for name in removed:
+                if name not in external_managed_names:
+                    os.environ.pop(name, None)
+                owned.discard(name)
+                owned_values.pop(name, None)
+
+        for name, value in secrets.items():
+            should_write = False
+            if name not in os.environ:
+                should_write = True
+            elif name in external_managed_names:
+                # Current refresh explicitly sourced this name externally.
+                should_write = False
+            elif force and (previous.get(name) is True or name in owned):
+                # Only refresh vars we previously injected ourselves.
+                should_write = True
+
+            if should_write:
+                os.environ[name] = value
+                injected[name] = True
+                owned.add(name)
+                owned_values[name] = value
+            else:
+                injected[name] = False
+                if name in external_managed_names and not (previous.get(name) is True):
+                    # External source owns it in this process.
+                    owned.discard(name)
+                    owned_values.pop(name, None)
+        self._injected = injected
+        _set_owned_env_names(owned)
+        _set_owned_env_values(owned_values)
+        count_written = sum(1 for v in injected.values() if v)
+        count_skipped = sum(1 for v in injected.values() if not v)
+        logger.info(
+            "Keystore: %s %d secrets (%d skipped)",
+            "refreshed" if force else "injected",
+            count_written,
+            count_skipped,
+        )
+        return injected
+
+    # ------------------------------------------------------------------
+    # Secret management
+    # ------------------------------------------------------------------
+
+    def set_secret(
+        self,
+        name: str,
+        value: str,
+        category: Optional[str] = None,
+        description: str = "",
+        tags: Optional[List[str]] = None,
+    ) -> None:
+        """Store a secret.  Category defaults based on the name."""
+        cat = category or default_category(name).value
+        self._store.set(name, value, category=cat, description=description, tags=tags)
+
+    def get_secret(self, name: str, requester: str = "cli") -> Optional[str]:
+        """Retrieve a secret."""
+        return self._store.get(name, requester=requester)
+
+    def delete_secret(self, name: str) -> bool:
+        """Delete a secret."""
+        return self._store.delete(name)
+
+    def list_secrets(self) -> List[SecretEntry]:
+        """List all secrets (metadata only)."""
+        return self._store.list_secrets()
+
+    def set_category(self, name: str, category: str) -> bool:
+        """Change a secret's access category."""
+        # Validate
+        try:
+            SecretCategory(category)
+        except ValueError:
+            raise KeystoreError(
+                f"Invalid category '{category}'. "
+                f"Must be one of: {', '.join(c.value for c in SecretCategory)}"
+            )
+        return self._store.set_category(name, category)
+
+    def get_access_log(self, limit: int = 50) -> List[dict]:
+        """Return recent access log entries."""
+        return self._store.get_access_log(limit)
+
+    def change_passphrase(self, old_passphrase: str, new_passphrase: str) -> None:
+        """Change the master passphrase."""
+        self._store.change_passphrase(old_passphrase, new_passphrase)
+
+    def secret_count(self) -> int:
+        """Return the number of stored secrets."""
+        return self._store.secret_count()
+
+    # ------------------------------------------------------------------
+    # Credential store (passphrase caching)
+    # ------------------------------------------------------------------
+
+    def remember_passphrase(self, passphrase: str) -> Tuple[bool, str]:
+        """Store the passphrase in the OS credential store.
+
+        Returns (success, backend_name_or_error_message).
+        """
+        backend = credential_store.backend_name()
+        if not credential_store.is_available():
+            return False, (
+                "No credential store backend available.\n\n"
+                "Options:\n"
+                "  • Set HERMES_KEYSTORE_PASSPHRASE env var for headless/Docker\n"
+                "  • Install keyring: pip install keyring\n"
+                "  • Install keyctl: apt install keyutils (Linux)\n"
+                "  • Type your passphrase each time (most secure)"
+            )
+        # Verify the passphrase is correct first
+        try:
+            self._store.unlock(passphrase)
+        except PassphraseMismatch:
+            return False, "Incorrect passphrase"
+
+        if credential_store.store_passphrase(passphrase):
+            return True, backend
+        return False, f"Failed to store passphrase in {backend}"
+
+    def forget_passphrase(self) -> Tuple[bool, str]:
+        """Remove the passphrase from the OS credential store."""
+        backend = credential_store.backend_name()
+        if credential_store.delete_passphrase():
+            return True, backend or "credential store"
+        return False, "No stored passphrase found"
+
+    # ------------------------------------------------------------------
+    # Migration from .env
+    # ------------------------------------------------------------------
+
+    def migrate_from_env(self, env_path: Optional[Path] = None) -> Dict[str, str]:
+        """Import secrets from a .env file into the keystore.
+
+        Returns a dict of {secret_name: category} for each migrated secret.
+        Skips blank values and comments.  Does NOT delete the .env file
+        (the caller should handle backup/stub creation).
+        """
+        path = env_path or _env_file_path()
+        if not path.exists():
+            return {}
+
+        migrated = {}
+        with open(path, encoding="utf-8", errors="replace") as f:
+            for line in f:
+                line = line.strip()
+                if not line or line.startswith("#"):
+                    continue
+                if "=" not in line:
+                    continue
+
+                key, _, value = line.partition("=")
+                key = key.strip()
+                value = value.strip()
+
+                # Strip surrounding quotes
+                if len(value) >= 2 and value[0] == value[-1] and value[0] in ('"', "'"):
+                    value = value[1:-1]
+
+                if not value:
+                    continue
+
+                # Skip non-secret config values
+                if not _looks_like_secret(key, value):
+                    continue
+
+                category = default_category(key).value
+                self._store.set(
+                    key, value,
+                    category=category,
+                    description=f"Migrated from .env",
+                    tags=["migrated"],
+                )
+                migrated[key] = category
+
+        logger.info("Migrated %d secrets from %s", len(migrated), path)
+        return migrated
+
+
+def _looks_like_secret(key: str, value: str) -> bool:
+    """Heuristic: does this .env entry look like a secret?"""
+    secret_indicators = (
+        "KEY", "TOKEN", "SECRET", "PASSWORD", "PASSWD",
+        "AUTH", "CREDENTIAL", "API_KEY",
+    )
+    key_upper = key.upper()
+    for indicator in secret_indicators:
+        if indicator in key_upper:
+            return True
+    # Long random-looking values are probably secrets
+    if len(value) >= 20 and not value.startswith("/") and not value.startswith("http"):
+        return True
+    return False
+
+
+# =========================================================================
+# Singleton
+# =========================================================================
+
+_instance: Optional[KeystoreClient] = None
+
+
+def get_keystore(db_path: Optional[str | Path] = None) -> KeystoreClient:
+    """Get the global keystore client (singleton per process)."""
+    global _instance
+    if _instance is None:
+        _instance = KeystoreClient(db_path)
+    return _instance
+
+
+def reset_keystore() -> None:
+    """Reset the global singleton (for testing)."""
+    global _instance
+    if _instance is not None:
+        try:
+            _instance.lock()
+        except Exception:
+            pass
+    _instance = None

keystore/credential_store.py

@@ -0,0 +1,367 @@
+"""Cross-platform credential store for keystore passphrase caching.
+
+Detects the best available backend at runtime. No hard dependency
+on any OS-specific service — every backend is probed and the first
+working one is used.
+
+Backend priority:
+  macOS      → Keychain Services (via keyring library)
+  Windows    → Credential Locker / DPAPI (via keyring library)
+  Linux      → Secret Service D-Bus > kernel keyctl
+  Fallback   → None
+
+Security note:
+  We intentionally DO NOT provide an automatic encrypted-file fallback.
+  In Hermes' current same-user execution model, any fallback whose key is
+  derivable from local machine/user state would be reachable by the agent
+  itself via file reads and local code execution, collapsing the security
+  boundary around sealed secrets. If no real OS/keyctl-backed credential
+  store exists, users must either:
+
+    - type the keystore passphrase at startup (recommended), or
+    - set HERMES_KEYSTORE_PASSPHRASE env var for headless/Docker/systemd
+      deployments (conscious security tradeoff for unattended operation)
+"""
+
+import hashlib
+import logging
+import os
+import platform
+import subprocess
+from pathlib import Path
+from typing import Optional
+
+logger = logging.getLogger(__name__)
+
+_SERVICE_NAME = "hermes-keystore"
+_ACCOUNT_NAME = "master-passphrase"
+
+
+# =========================================================================
+# Backend ABC
+# =========================================================================
+
+class _Backend:
+    """Abstract credential store backend."""
+    name: str = "Unknown"
+
+    def store(self, passphrase: str) -> bool:
+        raise NotImplementedError
+
+    def retrieve(self) -> Optional[str]:
+        raise NotImplementedError
+
+    def delete(self) -> bool:
+        raise NotImplementedError
+
+
+# =========================================================================
+# Backend: keyring (macOS Keychain, Windows Credential Locker, Secret Service)
+# =========================================================================
+
+class _KeyringBackend(_Backend):
+    """Cross-platform backend via the ``keyring`` library.
+
+    Covers macOS Keychain, Windows Credential Locker, and Linux
+    Secret Service (GNOME Keyring / KDE Wallet) if available.
+    """
+
+    def __init__(self, kr_module):
+        self._kr = kr_module
+        backend_obj = kr_module.get_keyring()
+        raw_name = type(backend_obj).__name__
+        _friendly = {
+            "Keyring": "macOS Keychain",
+            "KeyringBackend": "macOS Keychain",
+            "WinVaultKeyring": "Windows Credential Locker",
+            "SecretServiceKeyring": "Secret Service (GNOME/KDE)",
+        }
+        self.name = _friendly.get(raw_name, raw_name)
+
+    def store(self, passphrase: str) -> bool:
+        try:
+            self._kr.set_password(_SERVICE_NAME, _ACCOUNT_NAME, passphrase)
+            return True
+        except Exception as e:
+            logger.warning("keyring store failed: %s", e)
+            return False
+
+    def retrieve(self) -> Optional[str]:
+        try:
+            return self._kr.get_password(_SERVICE_NAME, _ACCOUNT_NAME)
+        except Exception:
+            return None
+
+    def delete(self) -> bool:
+        try:
+            self._kr.delete_password(_SERVICE_NAME, _ACCOUNT_NAME)
+            return True
+        except Exception:
+            return False
+
+
+# =========================================================================
+# Backend: Linux kernel keyring (keyctl)
+# =========================================================================
+
+class _KeyctlBackend(_Backend):
+    """Linux kernel keyring via the ``keyctl`` userspace tool.
+
+    Uses the per-UID *user* keyring (``@u``) which persists as long as
+    the UID has running processes.  On systemd systems this means the
+    passphrase survives across gateway restarts.
+
+    The persistent keyring (``@us``) would survive logout but has a
+    configurable idle expiry (default 3 days).  We use ``@u`` because
+    gateway/cron services are long-running.
+    """
+    name = "Linux Kernel Keyring"
+    _KEY_DESC = "hermes:keystore:passphrase"
+
+    def store(self, passphrase: str) -> bool:
+        try:
+            result = subprocess.run(
+                ["keyctl", "add", "user", self._KEY_DESC, passphrase, "@u"],
+                capture_output=True, text=True, timeout=5,
+            )
+            return result.returncode == 0
+        except (OSError, subprocess.TimeoutExpired):
+            return False
+
+    def retrieve(self) -> Optional[str]:
+        try:
+            result = subprocess.run(
+                ["keyctl", "search", "@u", "user", self._KEY_DESC],
+                capture_output=True, text=True, timeout=5,
+            )
+            if result.returncode != 0:
+                return None
+            key_id = result.stdout.strip()
+            result = subprocess.run(
+                ["keyctl", "pipe", key_id],
+                capture_output=True, timeout=5,
+            )
+            if result.returncode == 0 and result.stdout:
+                return result.stdout.decode("utf-8")
+            return None
+        except (OSError, subprocess.TimeoutExpired):
+            return None
+
+    def delete(self) -> bool:
+        try:
+            result = subprocess.run(
+                ["keyctl", "search", "@u", "user", self._KEY_DESC],
+                capture_output=True, text=True, timeout=5,
+            )
+            if result.returncode != 0:
+                return False
+            key_id = result.stdout.strip()
+            subprocess.run(
+                ["keyctl", "revoke", key_id],
+                capture_output=True, timeout=5,
+            )
+            return True
+        except (OSError, subprocess.TimeoutExpired):
+            return False
+
+
+# =========================================================================
+# Backend: Encrypted file (universal fallback)
+# =========================================================================
+
+class _EncryptedFileBackend(_Backend):
+    """Encrypted file fallback — works everywhere, requires pynacl.
+
+    Derives an encryption key from machine-id + UID + static salt via
+    SHA-256 (simplified HKDF).  Security assumption: same user on same
+    machine is trusted (equivalent to DPAPI on Windows).
+    """
+    name = "Encrypted File"
+
+    def _derive_key(self) -> bytes:
+        machine_id = _get_machine_id()
+        uid = str(os.getuid()) if hasattr(os, "getuid") else os.getlogin()
+        ikm = f"{machine_id}:{uid}:hermes-keystore-credential-v1".encode()
+        return hashlib.sha256(ikm).digest()
+
+    def _path(self) -> Path:
+        hermes_home = Path(os.getenv("HERMES_HOME", Path.home() / ".hermes"))
+        return hermes_home / "keystore" / ".credential"
+
+    def store(self, passphrase: str) -> bool:
+        try:
+            import nacl.secret
+            import nacl.utils
+            key = self._derive_key()
+            box = nacl.secret.SecretBox(key)
+            encrypted = box.encrypt(passphrase.encode("utf-8"))
+            path = self._path()
+            path.parent.mkdir(parents=True, exist_ok=True)
+            path.write_bytes(bytes(encrypted))
+            os.chmod(str(path), 0o600)
+            return True
+        except Exception as e:
+            logger.warning("Encrypted file store failed: %s", e)
+            return False
+
+    def retrieve(self) -> Optional[str]:
+        try:
+            import nacl.secret
+            key = self._derive_key()
+            box = nacl.secret.SecretBox(key)
+            encrypted = self._path().read_bytes()
+            return box.decrypt(encrypted).decode("utf-8")
+        except Exception:
+            return None
+
+    def delete(self) -> bool:
+        try:
+            self._path().unlink()
+            return True
+        except OSError:
+            return False
+
+
+# =========================================================================
+# Machine ID helper
+# =========================================================================
+
+def _get_machine_id() -> str:
+    """Get a stable machine identifier.  Best-effort, never raises."""
+    # Linux
+    for path in ("/etc/machine-id", "/var/lib/dbus/machine-id"):
+        try:
+            with open(path) as f:
+                mid = f.read().strip()
+                if mid:
+                    return mid
+        except OSError:
+            continue
+
+    # macOS — IOPlatformUUID
+    if platform.system() == "Darwin":
+        try:
+            r = subprocess.run(
+                ["ioreg", "-rd1", "-c", "IOPlatformExpertDevice"],
+                capture_output=True, text=True, timeout=5,
+            )
+            for line in r.stdout.splitlines():
+                if "IOPlatformUUID" in line:
+                    return line.split('"')[-2]
+        except (OSError, subprocess.TimeoutExpired, IndexError):
+            pass
+
+    # Windows — WMI CSProduct UUID
+    if platform.system() == "Windows":
+        try:
+            r = subprocess.run(
+                ["wmic", "csproduct", "get", "UUID"],
+                capture_output=True, text=True, timeout=5,
+            )
+            lines = [l.strip() for l in r.stdout.splitlines()
+                     if l.strip() and l.strip() != "UUID"]
+            if lines:
+                return lines[0]
+        except (OSError, subprocess.TimeoutExpired):
+            pass
+
+    # Last resort: hostname (stable-ish)
+    return platform.node()
+
+
+# =========================================================================
+# Backend detection
+# =========================================================================
+
+def _detect_backend() -> Optional[_Backend]:
+    """Detect the best available credential store backend."""
+
+    # 1. keyring library (macOS Keychain, Windows Credential Locker,
+    #    or Linux Secret Service via D-Bus)
+    try:
+        import keyring
+        from keyring.backends import fail as fail_backend
+
+        backend_obj = keyring.get_keyring()
+        if isinstance(backend_obj, fail_backend.Keyring):
+            raise ValueError("only fail backend available")
+        # Chainer with only fail backends
+        if hasattr(backend_obj, "backends"):
+            real = [b for b in backend_obj.backends
+                    if not isinstance(b, fail_backend.Keyring)]
+            if not real:
+                raise ValueError("chainer has no real backends")
+        return _KeyringBackend(keyring)
+    except (ImportError, ValueError, Exception) as e:
+        logger.debug("keyring unavailable: %s", e)
+
+    # 2. Linux kernel keyctl
+    if platform.system() == "Linux":
+        try:
+            result = subprocess.run(
+                ["keyctl", "--version"],
+                capture_output=True, timeout=5,
+            )
+            if result.returncode == 0:
+                return _KeyctlBackend()
+        except (OSError, subprocess.TimeoutExpired):
+            pass
+
+    # No insecure fallback. If no real backend is available, return None.
+    return None
+
+
+# Module-level cached backend.  ``False`` = not yet detected.
+_cached_backend: Optional[_Backend] = None
+_detection_done: bool = False
+
+
+def _get_backend() -> Optional[_Backend]:
+    global _cached_backend, _detection_done
+    if not _detection_done:
+        _cached_backend = _detect_backend()
+        _detection_done = True
+        if _cached_backend:
+            logger.debug("Credential store backend: %s", _cached_backend.name)
+        else:
+            logger.debug("No credential store backend available")
+    return _cached_backend
+
+
+# =========================================================================
+# Public API
+# =========================================================================
+
+def is_available() -> bool:
+    """Return True if any credential store backend is available."""
+    return _get_backend() is not None
+
+
+def backend_name() -> Optional[str]:
+    """Return human-readable name of the detected backend, or None."""
+    b = _get_backend()
+    return b.name if b else None
+
+
+def store_passphrase(passphrase: str) -> bool:
+    """Store the keystore passphrase.  Returns True on success."""
+    b = _get_backend()
+    if b is None:
+        return False
+    return b.store(passphrase)
+
+
+def retrieve_passphrase() -> Optional[str]:
+    """Retrieve the stored passphrase, or None if unavailable."""
+    b = _get_backend()
+    if b is None:
+        return None
+    return b.retrieve()
+
+
+def delete_passphrase() -> bool:
+    """Delete the stored passphrase.  Returns True on success."""
+    b = _get_backend()
+    if b is None:
+        return False
+    return b.delete()

keystore/store.py

@@ -0,0 +1,672 @@
+"""Encrypted secret store backed by SQLite.
+
+Secrets are encrypted at the field level using XSalsa20-Poly1305 (AEAD)
+via ``nacl.secret.SecretBox``. The master encryption key is derived from a
+user passphrase via Argon2id.
+
+The master key is held in memory only — never written to disk.
+The encrypted DB can be freely copied/backed up; it's useless without
+the passphrase.
+
+Thread safety: all public methods are serialized by a threading lock.
+The store is designed to be used from a single daemon process, but
+concurrent tool calls within that process are safe.
+"""
+
+import json
+import logging
+import os
+import sqlite3
+import threading
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, List, Optional, Tuple
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Crypto imports — pynacl SecretBox (XSalsa20-Poly1305), argon2-cffi for KDF
+# ---------------------------------------------------------------------------
+
+try:
+    import nacl.secret
+    import nacl.utils
+    import nacl.pwhash
+    import nacl.exceptions
+    _NACL_AVAILABLE = True
+except ImportError:
+    _NACL_AVAILABLE = False
+
+try:
+    from argon2 import PasswordHasher
+    from argon2.low_level import hash_secret_raw, Type
+    _ARGON2_AVAILABLE = True
+except ImportError:
+    _ARGON2_AVAILABLE = False
+
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+_SCHEMA_VERSION = 1
+_KDF_TIME_COST = 3
+_KDF_MEMORY_COST = 65536  # 64 MB
+_KDF_PARALLELISM = 4
+_KDF_HASH_LEN = 32  # 256 bits — matches SecretBox key size
+_SALT_LEN = 16
+
+
+# ---------------------------------------------------------------------------
+# Data structures
+# ---------------------------------------------------------------------------
+
+@dataclass
+class SecretEntry:
+    """A single secret stored in the keystore."""
+    name: str
+    category: str
+    description: str = ""
+    tags: List[str] = field(default_factory=list)
+    created_at: str = ""
+    updated_at: str = ""
+    last_accessed_at: Optional[str] = None
+    access_count: int = 0
+
+
+class KeystoreError(Exception):
+    """Base exception for keystore operations."""
+
+
+class KeystoreLocked(KeystoreError):
+    """Raised when an operation requires the keystore to be unlocked."""
+
+
+class KeystoreCorrupted(KeystoreError):
+    """Raised when the keystore DB is corrupted or tampered with."""
+
+
+class PassphraseMismatch(KeystoreError):
+    """Raised when the provided passphrase is wrong."""
+
+
+# ---------------------------------------------------------------------------
+# Core Store
+# ---------------------------------------------------------------------------
+
+class EncryptedStore:
+    """SQLite-backed encrypted secret store.
+
+    Usage::
+
+        store = EncryptedStore("~/.hermes/keystore/secrets.db")
+
+        # First time: initialize with a passphrase
+        store.initialize("my-passphrase")
+
+        # Later: unlock with the same passphrase
+        store.unlock("my-passphrase")
+
+        # Store and retrieve secrets
+        store.set("OPENROUTER_API_KEY", "sk-...", category="injectable")
+        value = store.get("OPENROUTER_API_KEY")
+
+        # Lock when done
+        store.lock()
+    """
+
+    def __init__(self, db_path: str | Path):
+        if not _NACL_AVAILABLE:
+            raise ImportError(
+                "pynacl is required for the keystore. "
+                "Install with: pip install 'hermes-agent[keystore]'"
+            )
+        if not _ARGON2_AVAILABLE:
+            raise ImportError(
+                "argon2-cffi is required for the keystore. "
+                "Install with: pip install 'hermes-agent[keystore]'"
+            )
+
+        self._db_path = Path(db_path).expanduser().resolve()
+        self._master_key: Optional[bytes] = None  # In-memory only
+        self._lock = threading.Lock()
+
+    @property
+    def is_initialized(self) -> bool:
+        """True if the keystore DB exists and has been initialized."""
+        if not self._db_path.exists():
+            return False
+        try:
+            conn = self._open_db()
+            cursor = conn.execute(
+                "SELECT value FROM metadata WHERE key = 'schema_version'"
+            )
+            row = cursor.fetchone()
+            conn.close()
+            return row is not None
+        except (sqlite3.Error, Exception):
+            return False
+
+    @property
+    def is_unlocked(self) -> bool:
+        """True if the store is unlocked (master key in memory)."""
+        return self._master_key is not None
+
+    def initialize(self, passphrase: str) -> None:
+        """Create a new keystore with the given passphrase.
+
+        Creates the DB file, directory structure, KDF salt, and a
+        verification token that lets us check the passphrase later.
+
+        Raises KeystoreError if already initialized.
+        """
+        with self._lock:
+            if self.is_initialized:
+                raise KeystoreError(
+                    "Keystore already initialized. Use change_passphrase() "
+                    "to change the passphrase, or delete the DB to start over."
+                )
+
+            # Create directory with strict permissions
+            self._db_path.parent.mkdir(parents=True, exist_ok=True)
+            os.chmod(str(self._db_path.parent), 0o700)
+
+            # Generate KDF salt
+            salt = nacl.utils.random(_SALT_LEN)
+
+            # Derive master key
+            master_key = self._derive_key(passphrase, salt)
+
+            # Create DB and schema
+            conn = self._open_db()
+            try:
+                self._create_schema(conn)
+
+                # Store KDF params
+                kdf_params = json.dumps({
+                    "algorithm": "argon2id",
+                    "time_cost": _KDF_TIME_COST,
+                    "memory_cost": _KDF_MEMORY_COST,
+                    "parallelism": _KDF_PARALLELISM,
+                    "hash_len": _KDF_HASH_LEN,
+                    "salt_len": _SALT_LEN,
+                }).encode()
+
+                conn.execute(
+                    "INSERT INTO metadata (key, value) VALUES (?, ?)",
+                    ("kdf_params", kdf_params),
+                )
+                conn.execute(
+                    "INSERT INTO metadata (key, value) VALUES (?, ?)",
+                    ("kdf_salt", salt),
+                )
+                conn.execute(
+                    "INSERT INTO metadata (key, value) VALUES (?, ?)",
+                    ("schema_version", str(_SCHEMA_VERSION).encode()),
+                )
+                conn.execute(
+                    "INSERT INTO metadata (key, value) VALUES (?, ?)",
+                    ("created_at", _now().encode()),
+                )
+
+                # Store a verification token — encrypt a known value so we
+                # can test the passphrase on unlock without storing it
+                verification = self._encrypt(master_key, b"hermes-keystore-ok")
+                conn.execute(
+                    "INSERT INTO metadata (key, value) VALUES (?, ?)",
+                    ("verification_token", verification),
+                )
+
+                conn.commit()
+            except Exception:
+                conn.close()
+                # Clean up on failure
+                try:
+                    self._db_path.unlink()
+                except OSError:
+                    pass
+                raise
+            finally:
+                conn.close()
+
+            # Set file permissions
+            os.chmod(str(self._db_path), 0o600)
+
+            # Unlock immediately after initialization
+            self._master_key = master_key
+            logger.info("Keystore initialized at %s", self._db_path)
+
+    def unlock(self, passphrase: str) -> None:
+        """Unlock the keystore with the user's passphrase.
+
+        Derives the master key and verifies it against the stored token.
+        Raises PassphraseMismatch if wrong, KeystoreError if not initialized.
+        """
+        with self._lock:
+            if not self.is_initialized:
+                raise KeystoreError("Keystore not initialized. Run 'hermes keystore init'.")
+
+            conn = self._open_db()
+            try:
+                # Read salt
+                salt = self._get_metadata(conn, "kdf_salt")
+                if salt is None:
+                    raise KeystoreCorrupted("Missing KDF salt in keystore DB")
+
+                # Read verification token
+                verification = self._get_metadata(conn, "verification_token")
+                if verification is None:
+                    raise KeystoreCorrupted("Missing verification token in keystore DB")
+            finally:
+                conn.close()
+
+            # Derive key and verify
+            master_key = self._derive_key(passphrase, salt)
+            try:
+                plaintext = self._decrypt(master_key, verification)
+                if plaintext != b"hermes-keystore-ok":
+                    raise PassphraseMismatch("Incorrect passphrase")
+            except nacl.exceptions.CryptoError:
+                raise PassphraseMismatch("Incorrect passphrase")
+
+            self._master_key = master_key
+            logger.info("Keystore unlocked")
+
+    def lock(self) -> None:
+        """Lock the keystore — wipe the master key from memory."""
+        with self._lock:
+            if self._master_key is not None:
+                # Best-effort memory wipe (Python doesn't guarantee this,
+                # but it's better than leaving it around)
+                self._master_key = None
+            logger.info("Keystore locked")
+
+    def set(
+        self,
+        name: str,
+        value: str,
+        category: str = "injectable",
+        description: str = "",
+        tags: Optional[List[str]] = None,
+    ) -> None:
+        """Store or update a secret.
+
+        Args:
+            name: Secret name (e.g. "OPENROUTER_API_KEY")
+            value: Secret value (will be encrypted)
+            category: Access category (injectable/gated/sealed/user_only)
+            description: Human-readable description
+            tags: Optional tags for grouping
+        """
+        with self._lock:
+            self._require_unlocked()
+            now = _now()
+
+            encrypted_value = self._encrypt(self._master_key, value.encode("utf-8"))
+            tags_json = json.dumps(tags or [])
+
+            conn = self._open_db()
+            try:
+                conn.execute(
+                    """INSERT INTO secrets (name, category, encrypted_value, description, tags, created_at, updated_at)
+                       VALUES (?, ?, ?, ?, ?, ?, ?)
+                       ON CONFLICT(name) DO UPDATE SET
+                           encrypted_value = excluded.encrypted_value,
+                           category = excluded.category,
+                           description = excluded.description,
+                           tags = excluded.tags,
+                           updated_at = excluded.updated_at
+                    """,
+                    (name, category, encrypted_value, description, tags_json, now, now),
+                )
+                self._log_access(conn, name, "write", "cli")
+                conn.commit()
+            finally:
+                conn.close()
+
+    def get(self, name: str, requester: str = "cli") -> Optional[str]:
+        """Retrieve and decrypt a secret value.
+
+        Args:
+            name: Secret name
+            requester: Who is requesting (for audit log)
+
+        Returns:
+            Decrypted value, or None if not found.
+
+        Raises:
+            KeystoreLocked: If the store is locked.
+        """
+        with self._lock:
+            self._require_unlocked()
+
+            conn = self._open_db()
+            try:
+                cursor = conn.execute(
+                    "SELECT encrypted_value, category FROM secrets WHERE name = ?",
+                    (name,),
+                )
+                row = cursor.fetchone()
+                if row is None:
+                    return None
+
+                encrypted_value, category = row
+
+                # Enforce category access control
+                if category == "user_only" and requester not in ("cli", "migration"):
+                    self._log_access(conn, name, "denied", requester)
+                    conn.commit()
+                    return None
+                if category == "sealed" and requester not in ("daemon", "wallet", "migration", "cli_export"):
+                    self._log_access(conn, name, "denied", requester)
+                    conn.commit()
+                    return None
+
+                try:
+                    value = self._decrypt(self._master_key, encrypted_value).decode("utf-8")
+                except nacl.exceptions.CryptoError:
+                    raise KeystoreCorrupted(f"Failed to decrypt secret '{name}' — DB may be corrupted")
+
+                now = _now()
+                conn.execute(
+                    "UPDATE secrets SET last_accessed_at = ?, access_count = access_count + 1 WHERE name = ?",
+                    (now, name),
+                )
+                self._log_access(conn, name, "read", requester)
+                conn.commit()
+                return value
+            finally:
+                conn.close()
+
+    def delete(self, name: str) -> bool:
+        """Delete a secret. Returns True if it existed."""
+        with self._lock:
+            self._require_unlocked()
+            conn = self._open_db()
+            try:
+                cursor = conn.execute("DELETE FROM secrets WHERE name = ?", (name,))
+                deleted = cursor.rowcount > 0
+                if deleted:
+                    self._log_access(conn, name, "delete", "cli")
+                conn.commit()
+                return deleted
+            finally:
+                conn.close()
+
+    def list_secrets(self) -> List[SecretEntry]:
+        """List all secrets (metadata only, no values)."""
+        with self._lock:
+            self._require_unlocked()
+            conn = self._open_db()
+            try:
+                cursor = conn.execute(
+                    """SELECT name, category, description, tags,
+                              created_at, updated_at, last_accessed_at, access_count
+                       FROM secrets ORDER BY name"""
+                )
+                results = []
+                for row in cursor:
+                    results.append(SecretEntry(
+                        name=row[0],
+                        category=row[1],
+                        description=row[2],
+                        tags=json.loads(row[3]) if row[3] else [],
+                        created_at=row[4],
+                        updated_at=row[5],
+                        last_accessed_at=row[6],
+                        access_count=row[7],
+                    ))
+                return results
+            finally:
+                conn.close()
+
+    def get_injectable_secrets(self) -> Dict[str, str]:
+        """Return all injectable secrets as a name→value dict.
+
+        Used by the startup flow to populate os.environ.
+        """
+        with self._lock:
+            self._require_unlocked()
+            conn = self._open_db()
+            try:
+                cursor = conn.execute(
+                    "SELECT name, encrypted_value FROM secrets WHERE category = 'injectable'"
+                )
+                result = {}
+                now = _now()
+                for name, encrypted_value in cursor:
+                    try:
+                        value = self._decrypt(self._master_key, encrypted_value).decode("utf-8")
+                        result[name] = value
+                    except nacl.exceptions.CryptoError:
+                        logger.warning("Failed to decrypt injectable secret '%s' — skipping", name)
+                        continue
+
+                if result:
+                    conn.executemany(
+                        "UPDATE secrets SET last_accessed_at = ?, access_count = access_count + 1 WHERE name = ?",
+                        [(now, name) for name in result],
+                    )
+                    conn.commit()
+
+                return result
+            finally:
+                conn.close()
+
+    def set_category(self, name: str, category: str) -> bool:
+        """Change the access category of a secret. Returns True if it existed."""
+        with self._lock:
+            self._require_unlocked()
+            conn = self._open_db()
+            try:
+                cursor = conn.execute(
+                    "UPDATE secrets SET category = ?, updated_at = ? WHERE name = ?",
+                    (category, _now(), name),
+                )
+                conn.commit()
+                return cursor.rowcount > 0
+            finally:
+                conn.close()
+
+    def get_access_log(self, limit: int = 50) -> List[dict]:
+        """Return recent access log entries."""
+        with self._lock:
+            self._require_unlocked()
+            conn = self._open_db()
+            try:
+                cursor = conn.execute(
+                    """SELECT secret_name, action, requester, timestamp, details
+                       FROM access_log ORDER BY id DESC LIMIT ?""",
+                    (limit,),
+                )
+                return [
+                    {
+                        "secret_name": row[0],
+                        "action": row[1],
+                        "requester": row[2],
+                        "timestamp": row[3],
+                        "details": row[4],
+                    }
+                    for row in cursor
+                ]
+            finally:
+                conn.close()
+
+    def change_passphrase(self, old_passphrase: str, new_passphrase: str) -> None:
+        """Re-encrypt all secrets with a new passphrase.
+
+        This is an atomic operation — either all secrets are re-encrypted
+        or none are (transaction rollback on failure).
+        """
+        with self._lock:
+            if not self.is_initialized:
+                raise KeystoreError("Keystore not initialized")
+
+            # Close persistent connection to avoid "database is locked"
+
+            conn = self._open_db()
+            try:
+                # Verify old passphrase
+                old_salt = self._get_metadata(conn, "kdf_salt")
+                old_key = self._derive_key(old_passphrase, old_salt)
+                verification = self._get_metadata(conn, "verification_token")
+                try:
+                    self._decrypt(old_key, verification)
+                except nacl.exceptions.CryptoError:
+                    raise PassphraseMismatch("Current passphrase is incorrect")
+
+                # Generate new salt and key
+                new_salt = nacl.utils.random(_SALT_LEN)
+                new_key = self._derive_key(new_passphrase, new_salt)
+
+                # Re-encrypt all secrets
+                cursor = conn.execute("SELECT name, encrypted_value FROM secrets")
+                updates = []
+                for name, encrypted_value in cursor:
+                    plaintext = self._decrypt(old_key, encrypted_value)
+                    new_encrypted = self._encrypt(new_key, plaintext)
+                    updates.append((new_encrypted, _now(), name))
+
+                conn.executemany(
+                    "UPDATE secrets SET encrypted_value = ?, updated_at = ? WHERE name = ?",
+                    updates,
+                )
+
+                # Update salt and verification token
+                new_verification = self._encrypt(new_key, b"hermes-keystore-ok")
+                conn.execute(
+                    "UPDATE metadata SET value = ? WHERE key = 'kdf_salt'",
+                    (new_salt,),
+                )
+                conn.execute(
+                    "UPDATE metadata SET value = ? WHERE key = 'verification_token'",
+                    (new_verification,),
+                )
+                conn.commit()
+
+                # Update in-memory key
+                self._master_key = new_key
+                logger.info("Passphrase changed successfully (%d secrets re-encrypted)", len(updates))
+            finally:
+                conn.close()
+
+    def secret_count(self) -> int:
+        """Return the number of stored secrets (works even when locked)."""
+        try:
+            conn = self._open_db()
+            cursor = conn.execute("SELECT COUNT(*) FROM secrets")
+            count = cursor.fetchone()[0]
+            conn.close()
+            return count
+        except (sqlite3.Error, Exception):
+            return 0
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _require_unlocked(self) -> None:
+        if self._master_key is None:
+            raise KeystoreLocked("Keystore is locked. Call unlock() first.")
+
+    def _open_db(self) -> sqlite3.Connection:
+        """Open a new SQLite connection to the keystore DB."""
+        return sqlite3.connect(str(self._db_path), timeout=10)
+
+
+    def _create_schema(self, conn: sqlite3.Connection) -> None:
+        conn.executescript("""
+            CREATE TABLE IF NOT EXISTS metadata (
+                key TEXT PRIMARY KEY,
+                value BLOB NOT NULL
+            );
+
+            CREATE TABLE IF NOT EXISTS secrets (
+                name TEXT PRIMARY KEY,
+                category TEXT NOT NULL DEFAULT 'injectable',
+                encrypted_value BLOB NOT NULL,
+                description TEXT DEFAULT '',
+                tags TEXT DEFAULT '[]',
+                created_at TEXT NOT NULL,
+                updated_at TEXT NOT NULL,
+                last_accessed_at TEXT,
+                access_count INTEGER DEFAULT 0
+            );
+
+            CREATE TABLE IF NOT EXISTS access_log (
+                id INTEGER PRIMARY KEY AUTOINCREMENT,
+                secret_name TEXT NOT NULL,
+                action TEXT NOT NULL,
+                requester TEXT,
+                timestamp TEXT NOT NULL,
+                details TEXT
+            );
+
+            CREATE INDEX IF NOT EXISTS idx_secrets_category
+                ON secrets(category);
+            CREATE INDEX IF NOT EXISTS idx_access_log_secret
+                ON access_log(secret_name);
+            CREATE INDEX IF NOT EXISTS idx_access_log_timestamp
+                ON access_log(timestamp);
+        """)
+
+    def _get_metadata(self, conn: sqlite3.Connection, key: str) -> Optional[bytes]:
+        cursor = conn.execute("SELECT value FROM metadata WHERE key = ?", (key,))
+        row = cursor.fetchone()
+        return row[0] if row else None
+
+    def _log_access(
+        self,
+        conn: sqlite3.Connection,
+        secret_name: str,
+        action: str,
+        requester: str,
+        details: str = "",
+    ) -> None:
+        conn.execute(
+            "INSERT INTO access_log (secret_name, action, requester, timestamp, details) VALUES (?, ?, ?, ?, ?)",
+            (secret_name, action, requester, _now(), details),
+        )
+
+    @staticmethod
+    def _derive_key(passphrase: str, salt: bytes) -> bytes:
+        """Derive a 256-bit key from passphrase + salt via Argon2id."""
+        return hash_secret_raw(
+            secret=passphrase.encode("utf-8"),
+            salt=salt,
+            time_cost=_KDF_TIME_COST,
+            memory_cost=_KDF_MEMORY_COST,
+            parallelism=_KDF_PARALLELISM,
+            hash_len=_KDF_HASH_LEN,
+            type=Type.ID,
+        )
+
+    @staticmethod
+    def _encrypt(key: bytes, plaintext: bytes) -> bytes:
+        """Encrypt with XSalsa20-Poly1305 (AEAD) via ``nacl.secret.SecretBox``.
+
+        Returns nonce + ciphertext as a single blob.
+        SecretBox uses a 24-byte nonce and is widely audited.
+        """
+        box = nacl.secret.SecretBox(key)
+        return bytes(box.encrypt(plaintext))
+
+    @staticmethod
+    def _decrypt(key: bytes, ciphertext: bytes) -> bytes:
+        """Decrypt SecretBox (XSalsa20-Poly1305) ciphertext.
+
+        Raises nacl.exceptions.CryptoError on tampered/wrong-key data.
+        """
+        box = nacl.secret.SecretBox(key)
+        return bytes(box.decrypt(ciphertext))
+
+
+# ---------------------------------------------------------------------------
+# Utility
+# ---------------------------------------------------------------------------
+
+def _now() -> str:
+    """ISO 8601 UTC timestamp."""
+    from datetime import datetime, timezone
+    return datetime.now(timezone.utc).isoformat()

mcp_serve.py

@@ -1,868 +0,0 @@
-"""
-Hermes MCP Server — expose messaging conversations as MCP tools.
-
-Starts a stdio MCP server that lets any MCP client (Claude Code, Cursor, Codex,
-etc.) list conversations, read message history, send messages, poll for live
-events, and manage approval requests across all connected platforms.
-
-Matches OpenClaw's 9-tool MCP channel bridge surface:
-  conversations_list, conversation_get, messages_read, attachments_fetch,
-  events_poll, events_wait, messages_send, permissions_list_open,
-  permissions_respond
-
-Plus: channels_list (Hermes-specific extra)
-
-Usage:
-    hermes mcp serve
-    hermes mcp serve --verbose
-
-MCP client config (e.g. claude_desktop_config.json):
-    {
-        "mcpServers": {
-            "hermes": {
-                "command": "hermes",
-                "args": ["mcp", "serve"]
-            }
-        }
-    }
-"""
-
-from __future__ import annotations
-
-import json
-import logging
-import os
-import re
-import sys
-import threading
-import time
-from dataclasses import dataclass, field
-from datetime import datetime
-from pathlib import Path
-from typing import Any, Dict, List, Optional
-
-logger = logging.getLogger("hermes.mcp_serve")
-
-# ---------------------------------------------------------------------------
-# Lazy MCP SDK import
-# ---------------------------------------------------------------------------
-
-_MCP_SERVER_AVAILABLE = False
-try:
-    from mcp.server.fastmcp import FastMCP
-
-    _MCP_SERVER_AVAILABLE = True
-except ImportError:
-    FastMCP = None  # type: ignore[assignment,misc]
-
-
-# ---------------------------------------------------------------------------
-# Helpers
-# ---------------------------------------------------------------------------
-
-def _get_sessions_dir() -> Path:
-    """Return the sessions directory using HERMES_HOME."""
-    try:
-        from hermes_constants import get_hermes_home
-        return get_hermes_home() / "sessions"
-    except ImportError:
-        return Path(os.environ.get("HERMES_HOME", Path.home() / ".hermes")) / "sessions"
-
-
-def _get_session_db():
-    """Get a SessionDB instance for reading message transcripts."""
-    try:
-        from hermes_state import SessionDB
-        return SessionDB()
-    except Exception as e:
-        logger.debug("SessionDB unavailable: %s", e)
-        return None
-
-
-def _load_sessions_index() -> dict:
-    """Load the gateway sessions.json index directly.
-
-    Returns a dict of session_key -> entry_dict with platform routing info.
-    This avoids importing the full SessionStore which needs GatewayConfig.
-    """
-    sessions_file = _get_sessions_dir() / "sessions.json"
-    if not sessions_file.exists():
-        return {}
-    try:
-        with open(sessions_file, "r", encoding="utf-8") as f:
-            return json.load(f)
-    except Exception as e:
-        logger.debug("Failed to load sessions.json: %s", e)
-        return {}
-
-
-def _load_channel_directory() -> dict:
-    """Load the cached channel directory for available targets."""
-    try:
-        from hermes_constants import get_hermes_home
-        directory_file = get_hermes_home() / "channel_directory.json"
-    except ImportError:
-        directory_file = Path(
-            os.environ.get("HERMES_HOME", Path.home() / ".hermes")
-        ) / "channel_directory.json"
-
-    if not directory_file.exists():
-        return {}
-    try:
-        with open(directory_file, "r", encoding="utf-8") as f:
-            return json.load(f)
-    except Exception as e:
-        logger.debug("Failed to load channel_directory.json: %s", e)
-        return {}
-
-
-def _extract_message_content(msg: dict) -> str:
-    """Extract text content from a message, handling multi-part content."""
-    content = msg.get("content", "")
-    if isinstance(content, list):
-        text_parts = [
-            p.get("text", "") for p in content
-            if isinstance(p, dict) and p.get("type") == "text"
-        ]
-        return "\n".join(text_parts)
-    return str(content) if content else ""
-
-
-def _extract_attachments(msg: dict) -> List[dict]:
-    """Extract non-text attachments from a message.
-
-    Finds: multi-part image/file content blocks, MEDIA: tags in text,
-    image URLs, and file references.
-    """
-    attachments = []
-    content = msg.get("content", "")
-
-    # Multi-part content blocks (image_url, file, etc.)
-    if isinstance(content, list):
-        for part in content:
-            if not isinstance(part, dict):
-                continue
-            ptype = part.get("type", "")
-            if ptype == "image_url":
-                url = part.get("image_url", {}).get("url", "") if isinstance(part.get("image_url"), dict) else ""
-                if url:
-                    attachments.append({"type": "image", "url": url})
-            elif ptype == "image":
-                url = part.get("url", part.get("source", {}).get("url", ""))
-                if url:
-                    attachments.append({"type": "image", "url": url})
-            elif ptype not in ("text",):
-                # Unknown non-text content type
-                attachments.append({"type": ptype, "data": part})
-
-    # MEDIA: tags in text content
-    text = _extract_message_content(msg)
-    if text:
-        media_pattern = re.compile(r'MEDIA:\s*(\S+)')
-        for match in media_pattern.finditer(text):
-            path = match.group(1)
-            attachments.append({"type": "media", "path": path})
-
-    return attachments
-
-
-# ---------------------------------------------------------------------------
-# Event Bridge — polls SessionDB for new messages, maintains event queue
-# ---------------------------------------------------------------------------
-
-QUEUE_LIMIT = 1000
-POLL_INTERVAL = 0.2  # seconds between DB polls (200ms)
-
-
-@dataclass
-class QueueEvent:
-    """An event in the bridge's in-memory queue."""
-    cursor: int
-    type: str  # "message", "approval_requested", "approval_resolved"
-    session_key: str = ""
-    data: dict = field(default_factory=dict)
-
-
-class EventBridge:
-    """Background poller that watches SessionDB for new messages and
-    maintains an in-memory event queue with waiter support.
-
-    This is the Hermes equivalent of OpenClaw's WebSocket gateway bridge.
-    Instead of WebSocket events, we poll the SQLite database for changes.
-    """
-
-    def __init__(self):
-        self._queue: List[QueueEvent] = []
-        self._cursor = 0
-        self._lock = threading.Lock()
-        self._new_event = threading.Event()
-        self._running = False
-        self._thread: Optional[threading.Thread] = None
-        self._last_poll_timestamps: Dict[str, float] = {}  # session_key -> unix timestamp
-        # In-memory approval tracking (populated from events)
-        self._pending_approvals: Dict[str, dict] = {}
-        # mtime cache — skip expensive work when files haven't changed
-        self._sessions_json_mtime: float = 0.0
-        self._state_db_mtime: float = 0.0
-        self._cached_sessions_index: dict = {}
-
-    def start(self):
-        """Start the background polling thread."""
-        if self._running:
-            return
-        self._running = True
-        self._thread = threading.Thread(target=self._poll_loop, daemon=True)
-        self._thread.start()
-        logger.debug("EventBridge started")
-
-    def stop(self):
-        """Stop the background polling thread."""
-        self._running = False
-        self._new_event.set()  # Wake any waiters
-        if self._thread:
-            self._thread.join(timeout=5)
-        logger.debug("EventBridge stopped")
-
-    def poll_events(
-        self,
-        after_cursor: int = 0,
-        session_key: Optional[str] = None,
-        limit: int = 20,
-    ) -> dict:
-        """Return events since after_cursor, optionally filtered by session_key."""
-        with self._lock:
-            events = [
-                e for e in self._queue
-                if e.cursor > after_cursor
-                and (not session_key or e.session_key == session_key)
-            ][:limit]
-
-        next_cursor = events[-1].cursor if events else after_cursor
-        return {
-            "events": [
-                {"cursor": e.cursor, "type": e.type,
-                 "session_key": e.session_key, **e.data}
-                for e in events
-            ],
-            "next_cursor": next_cursor,
-        }
-
-    def wait_for_event(
-        self,
-        after_cursor: int = 0,
-        session_key: Optional[str] = None,
-        timeout_ms: int = 30000,
-    ) -> Optional[dict]:
-        """Block until a matching event arrives or timeout expires."""
-        deadline = time.monotonic() + (timeout_ms / 1000.0)
-
-        while time.monotonic() < deadline:
-            with self._lock:
-                for e in self._queue:
-                    if e.cursor > after_cursor and (
-                        not session_key or e.session_key == session_key
-                    ):
-                        return {
-                            "cursor": e.cursor, "type": e.type,
-                            "session_key": e.session_key, **e.data,
-                        }
-
-            remaining = deadline - time.monotonic()
-            if remaining <= 0:
-                break
-            self._new_event.clear()
-            self._new_event.wait(timeout=min(remaining, POLL_INTERVAL))
-
-        return None
-
-    def list_pending_approvals(self) -> List[dict]:
-        """List approval requests observed during this bridge session."""
-        with self._lock:
-            return sorted(
-                self._pending_approvals.values(),
-                key=lambda a: a.get("created_at", ""),
-            )
-
-    def respond_to_approval(self, approval_id: str, decision: str) -> dict:
-        """Resolve a pending approval (best-effort without gateway IPC)."""
-        with self._lock:
-            approval = self._pending_approvals.pop(approval_id, None)
-
-        if not approval:
-            return {"error": f"Approval not found: {approval_id}"}
-
-        self._enqueue(QueueEvent(
-            cursor=0,  # Will be set by _enqueue
-            type="approval_resolved",
-            session_key=approval.get("session_key", ""),
-            data={"approval_id": approval_id, "decision": decision},
-        ))
-
-        return {"resolved": True, "approval_id": approval_id, "decision": decision}
-
-    def _enqueue(self, event: QueueEvent) -> None:
-        """Add an event to the queue and wake any waiters."""
-        with self._lock:
-            self._cursor += 1
-            event.cursor = self._cursor
-            self._queue.append(event)
-            # Trim queue to limit
-            while len(self._queue) > QUEUE_LIMIT:
-                self._queue.pop(0)
-        self._new_event.set()
-
-    def _poll_loop(self):
-        """Background loop: poll SessionDB for new messages."""
-        db = _get_session_db()
-        if not db:
-            logger.warning("EventBridge: SessionDB unavailable, event polling disabled")
-            return
-
-        while self._running:
-            try:
-                self._poll_once(db)
-            except Exception as e:
-                logger.debug("EventBridge poll error: %s", e)
-            time.sleep(POLL_INTERVAL)
-
-    def _poll_once(self, db):
-        """Check for new messages across all sessions.
-
-        Uses mtime checks on sessions.json and state.db to skip work
-        when nothing has changed — makes 200ms polling essentially free.
-        """
-        # Check if sessions.json has changed (mtime check is ~1μs)
-        sessions_file = _get_sessions_dir() / "sessions.json"
-        try:
-            sj_mtime = sessions_file.stat().st_mtime if sessions_file.exists() else 0.0
-        except OSError:
-            sj_mtime = 0.0
-
-        if sj_mtime != self._sessions_json_mtime:
-            self._sessions_json_mtime = sj_mtime
-            self._cached_sessions_index = _load_sessions_index()
-
-        # Check if state.db has changed
-        try:
-            from hermes_constants import get_hermes_home
-            db_file = get_hermes_home() / "state.db"
-        except ImportError:
-            db_file = Path(os.environ.get("HERMES_HOME", Path.home() / ".hermes")) / "state.db"
-
-        try:
-            db_mtime = db_file.stat().st_mtime if db_file.exists() else 0.0
-        except OSError:
-            db_mtime = 0.0
-
-        if db_mtime == self._state_db_mtime and sj_mtime == self._sessions_json_mtime:
-            return  # Nothing changed since last poll — skip entirely
-
-        self._state_db_mtime = db_mtime
-        entries = self._cached_sessions_index
-
-        for session_key, entry in entries.items():
-            session_id = entry.get("session_id", "")
-            if not session_id:
-                continue
-
-            last_seen = self._last_poll_timestamps.get(session_key, 0.0)
-
-            try:
-                messages = db.get_messages(session_id)
-            except Exception:
-                continue
-
-            if not messages:
-                continue
-
-            # Normalize timestamps to float for comparison
-            def _ts_float(ts) -> float:
-                if isinstance(ts, (int, float)):
-                    return float(ts)
-                if isinstance(ts, str) and ts:
-                    try:
-                        return float(ts)
-                    except ValueError:
-                        # ISO string — parse to epoch
-                        try:
-                            from datetime import datetime
-                            return datetime.fromisoformat(ts).timestamp()
-                        except Exception:
-                            return 0.0
-                return 0.0
-
-            # Find messages newer than our last seen timestamp
-            new_messages = []
-            for msg in messages:
-                ts = _ts_float(msg.get("timestamp", 0))
-                role = msg.get("role", "")
-                if role not in ("user", "assistant"):
-                    continue
-                if ts > last_seen:
-                    new_messages.append(msg)
-
-            for msg in new_messages:
-                content = _extract_message_content(msg)
-                if not content:
-                    continue
-                self._enqueue(QueueEvent(
-                    cursor=0,
-                    type="message",
-                    session_key=session_key,
-                    data={
-                        "role": msg.get("role", ""),
-                        "content": content[:500],
-                        "timestamp": str(msg.get("timestamp", "")),
-                        "message_id": str(msg.get("id", "")),
-                    },
-                ))
-
-            # Update last seen to the most recent message timestamp
-            all_ts = [_ts_float(m.get("timestamp", 0)) for m in messages]
-            if all_ts:
-                latest = max(all_ts)
-                if latest > last_seen:
-                    self._last_poll_timestamps[session_key] = latest
-
-
-# ---------------------------------------------------------------------------
-# MCP Server
-# ---------------------------------------------------------------------------
-
-def create_mcp_server(event_bridge: Optional[EventBridge] = None) -> "FastMCP":
-    """Create and return the Hermes MCP server with all tools registered."""
-    if not _MCP_SERVER_AVAILABLE:
-        raise ImportError(
-            "MCP server requires the 'mcp' package. "
-            "Install with: pip install 'hermes-agent[mcp]'"
-        )
-
-    mcp = FastMCP(
-        "hermes",
-        instructions=(
-            "Hermes Agent messaging bridge. Use these tools to interact with "
-            "conversations across Telegram, Discord, Slack, WhatsApp, Signal, "
-            "Matrix, and other connected platforms."
-        ),
-    )
-
-    bridge = event_bridge or EventBridge()
-
-    # -- conversations_list ------------------------------------------------
-
-    @mcp.tool()
-    def conversations_list(
-        platform: Optional[str] = None,
-        limit: int = 50,
-        search: Optional[str] = None,
-    ) -> str:
-        """List active messaging conversations across connected platforms.
-
-        Returns conversations with their session keys (needed for messages_read),
-        platform, chat type, display name, and last activity time.
-
-        Args:
-            platform: Filter by platform name (telegram, discord, slack, etc.)
-            limit: Maximum number of conversations to return (default 50)
-            search: Optional text to filter conversations by name
-        """
-        entries = _load_sessions_index()
-        conversations = []
-
-        for key, entry in entries.items():
-            origin = entry.get("origin", {})
-            entry_platform = entry.get("platform") or origin.get("platform", "")
-
-            if platform and entry_platform.lower() != platform.lower():
-                continue
-
-            display_name = entry.get("display_name", "")
-            chat_name = origin.get("chat_name", "")
-            if search:
-                search_lower = search.lower()
-                if (search_lower not in display_name.lower()
-                        and search_lower not in chat_name.lower()
-                        and search_lower not in key.lower()):
-                    continue
-
-            conversations.append({
-                "session_key": key,
-                "session_id": entry.get("session_id", ""),
-                "platform": entry_platform,
-                "chat_type": entry.get("chat_type", origin.get("chat_type", "")),
-                "display_name": display_name,
-                "chat_name": chat_name,
-                "user_name": origin.get("user_name", ""),
-                "updated_at": entry.get("updated_at", ""),
-            })
-
-        conversations.sort(key=lambda c: c.get("updated_at", ""), reverse=True)
-        conversations = conversations[:limit]
-
-        return json.dumps({
-            "count": len(conversations),
-            "conversations": conversations,
-        }, indent=2)
-
-    # -- conversation_get --------------------------------------------------
-
-    @mcp.tool()
-    def conversation_get(session_key: str) -> str:
-        """Get detailed info about one conversation by its session key.
-
-        Args:
-            session_key: The session key from conversations_list
-        """
-        entries = _load_sessions_index()
-        entry = entries.get(session_key)
-
-        if not entry:
-            return json.dumps({"error": f"Conversation not found: {session_key}"})
-
-        origin = entry.get("origin", {})
-        return json.dumps({
-            "session_key": session_key,
-            "session_id": entry.get("session_id", ""),
-            "platform": entry.get("platform") or origin.get("platform", ""),
-            "chat_type": entry.get("chat_type", origin.get("chat_type", "")),
-            "display_name": entry.get("display_name", ""),
-            "user_name": origin.get("user_name", ""),
-            "chat_name": origin.get("chat_name", ""),
-            "chat_id": origin.get("chat_id", ""),
-            "thread_id": origin.get("thread_id"),
-            "updated_at": entry.get("updated_at", ""),
-            "created_at": entry.get("created_at", ""),
-            "input_tokens": entry.get("input_tokens", 0),
-            "output_tokens": entry.get("output_tokens", 0),
-            "total_tokens": entry.get("total_tokens", 0),
-        }, indent=2)
-
-    # -- messages_read -----------------------------------------------------
-
-    @mcp.tool()
-    def messages_read(
-        session_key: str,
-        limit: int = 50,
-    ) -> str:
-        """Read recent messages from a conversation.
-
-        Returns the message history in chronological order with role, content,
-        and timestamp for each message.
-
-        Args:
-            session_key: The session key from conversations_list
-            limit: Maximum number of messages to return (default 50, most recent)
-        """
-        entries = _load_sessions_index()
-        entry = entries.get(session_key)
-        if not entry:
-            return json.dumps({"error": f"Conversation not found: {session_key}"})
-
-        session_id = entry.get("session_id", "")
-        if not session_id:
-            return json.dumps({"error": "No session ID for this conversation"})
-
-        db = _get_session_db()
-        if not db:
-            return json.dumps({"error": "Session database unavailable"})
-
-        try:
-            all_messages = db.get_messages(session_id)
-        except Exception as e:
-            return json.dumps({"error": f"Failed to read messages: {e}"})
-
-        filtered = []
-        for msg in all_messages:
-            role = msg.get("role", "")
-            if role in ("user", "assistant"):
-                content = _extract_message_content(msg)
-                if content:
-                    filtered.append({
-                        "id": str(msg.get("id", "")),
-                        "role": role,
-                        "content": content[:2000],
-                        "timestamp": msg.get("timestamp", ""),
-                    })
-
-        messages = filtered[-limit:]
-
-        return json.dumps({
-            "session_key": session_key,
-            "count": len(messages),
-            "total_in_session": len(filtered),
-            "messages": messages,
-        }, indent=2)
-
-    # -- attachments_fetch -------------------------------------------------
-
-    @mcp.tool()
-    def attachments_fetch(
-        session_key: str,
-        message_id: str,
-    ) -> str:
-        """List non-text attachments for a message in a conversation.
-
-        Extracts images, media files, and other non-text content blocks
-        from the specified message.
-
-        Args:
-            session_key: The session key from conversations_list
-            message_id: The message ID from messages_read
-        """
-        entries = _load_sessions_index()
-        entry = entries.get(session_key)
-        if not entry:
-            return json.dumps({"error": f"Conversation not found: {session_key}"})
-
-        session_id = entry.get("session_id", "")
-        if not session_id:
-            return json.dumps({"error": "No session ID for this conversation"})
-
-        db = _get_session_db()
-        if not db:
-            return json.dumps({"error": "Session database unavailable"})
-
-        try:
-            all_messages = db.get_messages(session_id)
-        except Exception as e:
-            return json.dumps({"error": f"Failed to read messages: {e}"})
-
-        # Find the target message
-        target_msg = None
-        for msg in all_messages:
-            if str(msg.get("id", "")) == message_id:
-                target_msg = msg
-                break
-
-        if not target_msg:
-            return json.dumps({"error": f"Message not found: {message_id}"})
-
-        attachments = _extract_attachments(target_msg)
-
-        return json.dumps({
-            "message_id": message_id,
-            "count": len(attachments),
-            "attachments": attachments,
-        }, indent=2)
-
-    # -- events_poll -------------------------------------------------------
-
-    @mcp.tool()
-    def events_poll(
-        after_cursor: int = 0,
-        session_key: Optional[str] = None,
-        limit: int = 20,
-    ) -> str:
-        """Poll for new conversation events since a cursor position.
-
-        Returns events that have occurred since the given cursor. Use the
-        returned next_cursor value for subsequent polls.
-
-        Event types: message, approval_requested, approval_resolved
-
-        Args:
-            after_cursor: Return events after this cursor (0 for all)
-            session_key: Optional filter to one conversation
-            limit: Maximum events to return (default 20)
-        """
-        result = bridge.poll_events(
-            after_cursor=after_cursor,
-            session_key=session_key,
-            limit=limit,
-        )
-        return json.dumps(result, indent=2)
-
-    # -- events_wait -------------------------------------------------------
-
-    @mcp.tool()
-    def events_wait(
-        after_cursor: int = 0,
-        session_key: Optional[str] = None,
-        timeout_ms: int = 30000,
-    ) -> str:
-        """Wait for the next conversation event (long-poll).
-
-        Blocks until a matching event arrives or the timeout expires.
-        Use this for near-real-time event delivery without polling.
-
-        Args:
-            after_cursor: Wait for events after this cursor
-            session_key: Optional filter to one conversation
-            timeout_ms: Maximum wait time in milliseconds (default 30000)
-        """
-        event = bridge.wait_for_event(
-            after_cursor=after_cursor,
-            session_key=session_key,
-            timeout_ms=min(timeout_ms, 300000),  # Cap at 5 minutes
-        )
-        if event:
-            return json.dumps({"event": event}, indent=2)
-        return json.dumps({"event": None, "reason": "timeout"}, indent=2)
-
-    # -- messages_send -----------------------------------------------------
-
-    @mcp.tool()
-    def messages_send(
-        target: str,
-        message: str,
-    ) -> str:
-        """Send a message to a platform conversation.
-
-        The target format is "platform:chat_id" — same format used by the
-        channels_list tool. You can also use human-friendly channel names
-        that will be resolved automatically.
-
-        Examples:
-            target="telegram:6308981865"
-            target="discord:#general"
-            target="slack:#engineering"
-
-        Args:
-            target: Platform target in "platform:identifier" format
-            message: The message text to send
-        """
-        if not target or not message:
-            return json.dumps({"error": "Both target and message are required"})
-
-        try:
-            from tools.send_message_tool import send_message_tool
-            result_str = send_message_tool(
-                {"action": "send", "target": target, "message": message}
-            )
-            return result_str
-        except ImportError:
-            return json.dumps({"error": "Send message tool not available"})
-        except Exception as e:
-            return json.dumps({"error": f"Send failed: {e}"})
-
-    # -- channels_list -----------------------------------------------------
-
-    @mcp.tool()
-    def channels_list(platform: Optional[str] = None) -> str:
-        """List available messaging channels and targets across platforms.
-
-        Returns channels that you can send messages to. The target strings
-        returned here can be used directly with the messages_send tool.
-
-        Args:
-            platform: Filter by platform name (telegram, discord, slack, etc.)
-        """
-        directory = _load_channel_directory()
-        if not directory:
-            entries = _load_sessions_index()
-            targets = []
-            seen = set()
-            for key, entry in entries.items():
-                origin = entry.get("origin", {})
-                p = entry.get("platform") or origin.get("platform", "")
-                chat_id = origin.get("chat_id", "")
-                if not p or not chat_id:
-                    continue
-                if platform and p.lower() != platform.lower():
-                    continue
-                target_str = f"{p}:{chat_id}"
-                if target_str in seen:
-                    continue
-                seen.add(target_str)
-                targets.append({
-                    "target": target_str,
-                    "platform": p,
-                    "name": entry.get("display_name") or origin.get("chat_name", ""),
-                    "chat_type": entry.get("chat_type", origin.get("chat_type", "")),
-                })
-            return json.dumps({"count": len(targets), "channels": targets}, indent=2)
-
-        channels = []
-        for plat, entries_list in directory.items():
-            if platform and plat.lower() != platform.lower():
-                continue
-            if isinstance(entries_list, list):
-                for ch in entries_list:
-                    if isinstance(ch, dict):
-                        chat_id = ch.get("id", ch.get("chat_id", ""))
-                        channels.append({
-                            "target": f"{plat}:{chat_id}" if chat_id else plat,
-                            "platform": plat,
-                            "name": ch.get("name", ch.get("display_name", "")),
-                            "chat_type": ch.get("type", ""),
-                        })
-
-        return json.dumps({"count": len(channels), "channels": channels}, indent=2)
-
-    # -- permissions_list_open ---------------------------------------------
-
-    @mcp.tool()
-    def permissions_list_open() -> str:
-        """List pending approval requests observed during this bridge session.
-
-        Returns exec and plugin approval requests that the bridge has seen
-        since it started. Approvals are live-session only — older approvals
-        from before the bridge connected are not included.
-        """
-        approvals = bridge.list_pending_approvals()
-        return json.dumps({
-            "count": len(approvals),
-            "approvals": approvals,
-        }, indent=2)
-
-    # -- permissions_respond -----------------------------------------------
-
-    @mcp.tool()
-    def permissions_respond(
-        id: str,
-        decision: str,
-    ) -> str:
-        """Respond to a pending approval request.
-
-        Args:
-            id: The approval ID from permissions_list_open
-            decision: One of "allow-once", "allow-always", or "deny"
-        """
-        if decision not in ("allow-once", "allow-always", "deny"):
-            return json.dumps({
-                "error": f"Invalid decision: {decision}. "
-                         f"Must be allow-once, allow-always, or deny"
-            })
-
-        result = bridge.respond_to_approval(id, decision)
-        return json.dumps(result, indent=2)
-
-    return mcp
-
-
-# ---------------------------------------------------------------------------
-# Entry point
-# ---------------------------------------------------------------------------
-
-def run_mcp_server(verbose: bool = False) -> None:
-    """Start the Hermes MCP server on stdio."""
-    if not _MCP_SERVER_AVAILABLE:
-        print(
-            "Error: MCP server requires the 'mcp' package.\n"
-            "Install with: pip install 'hermes-agent[mcp]'",
-            file=sys.stderr,
-        )
-        sys.exit(1)
-
-    if verbose:
-        logging.basicConfig(level=logging.DEBUG, stream=sys.stderr)
-    else:
-        logging.basicConfig(level=logging.WARNING, stream=sys.stderr)
-
-    bridge = EventBridge()
-    bridge.start()
-
-    server = create_mcp_server(event_bridge=bridge)
-
-    import asyncio
-
-    async def _run():
-        try:
-            await server.run_stdio_async()
-        finally:
-            bridge.stop()
-
-    try:
-        asyncio.run(_run())
-    except KeyboardInterrupt:
-        bridge.stop()

model_tools.py

@@ -158,6 +158,7 @@ def _discover_tools():
         "tools.send_message_tool",
         "tools.honcho_tools",
         "tools.homeassistant_tool",
+        "tools.wallet_tool",
     ]
     import importlib
     for mod_name in _modules:

nix/nixosModules.nix

@@ -111,7 +111,6 @@
       fi
       mkdir -p "$TARGET_HOME"
       chown "$HERMES_UID:$HERMES_GID" "$TARGET_HOME"
-      chmod 0750 "$TARGET_HOME"
 
       # Ensure HERMES_HOME is owned by the target user
       if [ -n "''${HERMES_HOME:-}" ] && [ -d "$HERMES_HOME" ]; then
@@ -552,8 +551,8 @@
       # ── Directories ───────────────────────────────────────────────────
       {
         systemd.tmpfiles.rules = [
-          "d ${cfg.stateDir}                0750 ${cfg.user} ${cfg.group} - -"
-          "d ${cfg.stateDir}/.hermes        0750 ${cfg.user} ${cfg.group} - -"
+          "d ${cfg.stateDir}                0755 ${cfg.user} ${cfg.group} - -"
+          "d ${cfg.stateDir}/.hermes        0755 ${cfg.user} ${cfg.group} - -"
           "d ${cfg.stateDir}/home           0750 ${cfg.user} ${cfg.group} - -"
           "d ${cfg.workingDirectory}         0750 ${cfg.user} ${cfg.group} - -"
         ];
@@ -567,23 +566,21 @@
           mkdir -p ${cfg.stateDir}/home
           mkdir -p ${cfg.workingDirectory}
           chown ${cfg.user}:${cfg.group} ${cfg.stateDir} ${cfg.stateDir}/.hermes ${cfg.stateDir}/home ${cfg.workingDirectory}
-          chmod 0750 ${cfg.stateDir} ${cfg.stateDir}/.hermes ${cfg.stateDir}/home ${cfg.workingDirectory}
 
           # Merge Nix settings into existing config.yaml.
           # Preserves user-added keys (skills, streaming, etc.); Nix keys win.
           # If configFile is user-provided (not generated), overwrite instead of merge.
           ${if cfg.configFile != null then ''
-            install -o ${cfg.user} -g ${cfg.group} -m 0640 -D ${configFile} ${cfg.stateDir}/.hermes/config.yaml
+            install -o ${cfg.user} -g ${cfg.group} -m 0644 -D ${configFile} ${cfg.stateDir}/.hermes/config.yaml
           '' else ''
             ${configMergeScript} ${generatedConfigFile} ${cfg.stateDir}/.hermes/config.yaml
             chown ${cfg.user}:${cfg.group} ${cfg.stateDir}/.hermes/config.yaml
-            chmod 0640 ${cfg.stateDir}/.hermes/config.yaml
+            chmod 0644 ${cfg.stateDir}/.hermes/config.yaml
           ''}
 
           # Managed mode marker (so interactive shells also detect NixOS management)
           touch ${cfg.stateDir}/.hermes/.managed
           chown ${cfg.user}:${cfg.group} ${cfg.stateDir}/.hermes/.managed
-          chmod 0644 ${cfg.stateDir}/.hermes/.managed
 
           # Seed auth file if provided
           ${lib.optionalString (cfg.authFile != null) ''
@@ -615,7 +612,7 @@ HERMES_NIX_ENV_EOF
 
           # Link documents into workspace
           ${lib.concatStringsSep "\n" (lib.mapAttrsToList (name: _value: ''
-            install -o ${cfg.user} -g ${cfg.group} -m 0640 ${documentDerivation}/${name} ${cfg.workingDirectory}/${name}
+            install -o ${cfg.user} -g ${cfg.group} -m 0644 ${documentDerivation}/${name} ${cfg.workingDirectory}/${name}
           '') cfg.documents)}
         '';
       }

optional-skills/communication/DESCRIPTION.md

@@ -1 +0,0 @@
-Communication and decision-making frameworks — structured response formats for proposals, trade-off analysis, and stakeholder-ready recommendations.

optional-skills/communication/one-three-one-rule/SKILL.md

@@ -1,103 +0,0 @@
----
-name: one-three-one-rule
-description: >
-  Structured decision-making framework for technical proposals and trade-off analysis.
-  When the user faces a choice between multiple approaches (architecture decisions,
-  tool selection, refactoring strategies, migration paths), this skill produces a
-  1-3-1 format: one clear problem statement, three distinct options with pros/cons,
-  and one concrete recommendation with definition of done and implementation plan.
-  Use when the user asks for a "1-3-1", says "give me options", or needs help
-  choosing between competing approaches.
-version: 1.0.0
-author: Willard Moore
-license: MIT
-category: communication
-metadata:
-  hermes:
-    tags: [communication, decision-making, proposals, trade-offs]
----
-
-# 1-3-1 Communication Rule
-
-Structured decision-making format for when a task has multiple viable approaches and the user needs a clear recommendation. Produces a concise problem framing, three options with trade-offs, and an actionable plan for the recommended path.
-
-## When to Use
-
-- The user explicitly asks for a "1-3-1" response.
-- The user says "give me options" or "what are my choices" for a technical decision.
-- A task has multiple viable approaches with meaningful trade-offs (architecture, tooling, migration strategy).
-- The user needs a proposal they can forward to a team or stakeholder.
-
-Do NOT use for simple questions with one obvious answer, debugging sessions, or tasks where the user has already decided on an approach.
-
-## Procedure
-
-1. **Problem** (one sentence)
-   - State the core decision or desired outcome in a single concise sentence.
-   - Focus on the *what*, not the *how* — no implementation details, tool names, or specific technologies.
-   - Keep it tight. If you need "and", you're describing two problems.
-
-2. **Options** (exactly three)
-   - Present three distinct, viable approaches labeled A, B, C.
-   - Each option gets a brief description, pros, and cons.
-   - Options should represent genuinely different strategies, not minor variations of the same approach.
-
-3. **Recommendation** (one option)
-   - State which option you recommend and why, based on the user's context and priorities.
-   - Be direct — this is your professional judgment, not a hedge.
-
-4. **Definition of Done**
-   - List the specific success criteria for the recommended option.
-   - These are concrete, verifiable outcomes — not vague aspirations.
-   - If the user picks a different option, revise this section to match.
-
-5. **Implementation Plan**
-   - Concrete steps to execute the recommended option.
-   - Include specific commands, tools, or actions where applicable.
-   - If the user picks a different option, revise this section to match.
-
-## Verification
-
-- Response has exactly one Problem sentence.
-- Response has exactly three Options (A, B, C) with pros and cons for each.
-- Response has a single Recommendation that picks one option with reasoning.
-- Definition of Done and Implementation Plan align with the recommended option.
-- If the user selects a different option, Recommendation, DoD, and Implementation Plan update accordingly.
-
-## Example
-
-User: "Give me a 1-3-1 for adding retry logic to our API client."
-
-Agent:
-
-**Problem:** API calls to external services fail intermittently under load and need graceful retry handling.
-
-**Options:**
-
-- **Option A: Exponential backoff with jitter in a shared utility.**
-  Pros: Simple, well-understood pattern; single implementation shared across all callers.
-  Cons: No circuit-breaking; callers still block during retries.
-
-- **Option B: Retry library (tenacity) as a decorator on each endpoint call.**
-  Pros: Configurable per-endpoint; built-in support for circuit breakers and rate limits.
-  Cons: Adds a dependency; decorator pattern can obscure control flow.
-
-- **Option C: Queue-based async retry with dead letter handling.**
-  Pros: Non-blocking; failed calls are tracked and replayable; scales well.
-  Cons: Significant complexity increase; requires a queue backend; overkill for low-volume services.
-
-**Recommendation:** Option A. The call volume doesn't justify queue infrastructure, and a shared utility with exponential backoff + jitter covers the failure mode cleanly without new dependencies.
-
-**Definition of Done:**
-- `api_retry()` utility handles transient HTTP errors (429, 502, 503, 504).
-- Retries up to 3 times with exponential backoff and jitter.
-- All external API calls route through the retry utility.
-- Logs each retry attempt with endpoint and attempt number.
-- Tests cover retry exhaustion, immediate success, and transient-then-success scenarios.
-
-**Implementation Plan:**
-1. Create `utils/api_retry.py` with configurable max retries, base delay, and retryable status codes.
-2. Add jitter using `random.uniform(0, base_delay)` to prevent thundering herd.
-3. Wrap existing API calls in `api_client.py` with the retry utility.
-4. Add unit tests mocking HTTP responses for each retry scenario.
-5. Verify under load with a simple stress test against a flaky endpoint mock.

optional-skills/productivity/canvas/SKILL.md

@@ -1,97 +0,0 @@
----
-name: canvas
-description: Canvas LMS integration — fetch enrolled courses and assignments using API token authentication.
-version: 1.0.0
-author: community
-license: MIT
-prerequisites:
-  env_vars: [CANVAS_API_TOKEN, CANVAS_BASE_URL]
-metadata:
-  hermes:
-    tags: [Canvas, LMS, Education, Courses, Assignments]
----
-
-# Canvas LMS — Course & Assignment Access
-
-Read-only access to Canvas LMS for listing courses and assignments.
-
-## Scripts
-
-- `scripts/canvas_api.py` — Python CLI for Canvas API calls
-
-## Setup
-
-1. Log in to your Canvas instance in a browser
-2. Go to **Account → Settings** (click your profile icon, then Settings)
-3. Scroll to **Approved Integrations** and click **+ New Access Token**
-4. Name the token (e.g., "Hermes Agent"), set an optional expiry, and click **Generate Token**
-5. Copy the token and add to `~/.hermes/.env`:
-
-```
-CANVAS_API_TOKEN=your_token_here
-CANVAS_BASE_URL=https://yourschool.instructure.com
-```
-
-The base URL is whatever appears in your browser when you're logged into Canvas (no trailing slash).
-
-## Usage
-
-```bash
-CANVAS="python $HERMES_HOME/skills/productivity/canvas/scripts/canvas_api.py"
-
-# List all active courses
-$CANVAS list_courses --enrollment-state active
-
-# List all courses (any state)
-$CANVAS list_courses
-
-# List assignments for a specific course
-$CANVAS list_assignments 12345
-
-# List assignments ordered by due date
-$CANVAS list_assignments 12345 --order-by due_at
-```
-
-## Output Format
-
-**list_courses** returns:
-```json
-[{"id": 12345, "name": "Intro to CS", "course_code": "CS101", "workflow_state": "available", "start_at": "...", "end_at": "..."}]
-```
-
-**list_assignments** returns:
-```json
-[{"id": 67890, "name": "Homework 1", "due_at": "2025-02-15T23:59:00Z", "points_possible": 100, "submission_types": ["online_upload"], "html_url": "...", "description": "...", "course_id": 12345}]
-```
-
-Note: Assignment descriptions are truncated to 500 characters. The `html_url` field links to the full assignment page in Canvas.
-
-## API Reference (curl)
-
-```bash
-# List courses
-curl -s -H "Authorization: Bearer $CANVAS_API_TOKEN" \
-  "$CANVAS_BASE_URL/api/v1/courses?enrollment_state=active&per_page=10"
-
-# List assignments for a course
-curl -s -H "Authorization: Bearer $CANVAS_API_TOKEN" \
-  "$CANVAS_BASE_URL/api/v1/courses/COURSE_ID/assignments?per_page=10&order_by=due_at"
-```
-
-Canvas uses `Link` headers for pagination. The Python script handles pagination automatically.
-
-## Rules
-
-- This skill is **read-only** — it only fetches data, never modifies courses or assignments
-- On first use, verify auth by running `$CANVAS list_courses` — if it fails with 401, guide the user through setup
-- Canvas rate-limits to ~700 requests per 10 minutes; check `X-Rate-Limit-Remaining` header if hitting limits
-
-## Troubleshooting
-
-| Problem | Fix |
-|---------|-----|
-| 401 Unauthorized | Token invalid or expired — regenerate in Canvas Settings |
-| 403 Forbidden | Token lacks permission for this course |
-| Empty course list | Try `--enrollment-state active` or omit the flag to see all states |
-| Wrong institution | Verify `CANVAS_BASE_URL` matches the URL in your browser |
-| Timeout errors | Check network connectivity to your Canvas instance |

optional-skills/productivity/canvas/scripts/canvas_api.py

@@ -1,157 +0,0 @@
-#!/usr/bin/env python3
-"""Canvas LMS API CLI for Hermes Agent.
-
-A thin CLI wrapper around the Canvas REST API.
-Authenticates using a personal access token from environment variables.
-
-Usage:
-  python canvas_api.py list_courses [--per-page N] [--enrollment-state STATE]
-  python canvas_api.py list_assignments COURSE_ID [--per-page N] [--order-by FIELD]
-"""
-
-import argparse
-import json
-import os
-import sys
-
-import requests
-
-CANVAS_API_TOKEN = os.environ.get("CANVAS_API_TOKEN", "")
-CANVAS_BASE_URL = os.environ.get("CANVAS_BASE_URL", "").rstrip("/")
-
-
-def _check_config():
-    """Validate required environment variables are set."""
-    missing = []
-    if not CANVAS_API_TOKEN:
-        missing.append("CANVAS_API_TOKEN")
-    if not CANVAS_BASE_URL:
-        missing.append("CANVAS_BASE_URL")
-    if missing:
-        print(
-            f"Missing required environment variables: {', '.join(missing)}\n"
-            "Set them in ~/.hermes/.env or export them in your shell.\n"
-            "See the canvas skill SKILL.md for setup instructions.",
-            file=sys.stderr,
-        )
-        sys.exit(1)
-
-
-def _headers():
-    return {"Authorization": f"Bearer {CANVAS_API_TOKEN}"}
-
-
-def _paginated_get(url, params=None, max_items=200):
-    """Fetch all pages up to max_items, following Canvas Link headers."""
-    results = []
-    while url and len(results) < max_items:
-        resp = requests.get(url, headers=_headers(), params=params, timeout=30)
-        resp.raise_for_status()
-        results.extend(resp.json())
-        params = None  # params are included in the Link URL for subsequent pages
-        url = None
-        link = resp.headers.get("Link", "")
-        for part in link.split(","):
-            if 'rel="next"' in part:
-                url = part.split(";")[0].strip().strip("<>")
-    return results[:max_items]
-
-
-# =========================================================================
-# Commands
-# =========================================================================
-
-
-def list_courses(args):
-    """List enrolled courses."""
-    _check_config()
-    url = f"{CANVAS_BASE_URL}/api/v1/courses"
-    params = {"per_page": args.per_page}
-    if args.enrollment_state:
-        params["enrollment_state"] = args.enrollment_state
-    try:
-        courses = _paginated_get(url, params)
-    except requests.HTTPError as e:
-        print(f"API error: {e.response.status_code} {e.response.text}", file=sys.stderr)
-        sys.exit(1)
-    output = [
-        {
-            "id": c["id"],
-            "name": c.get("name", ""),
-            "course_code": c.get("course_code", ""),
-            "enrollment_term_id": c.get("enrollment_term_id"),
-            "start_at": c.get("start_at"),
-            "end_at": c.get("end_at"),
-            "workflow_state": c.get("workflow_state", ""),
-        }
-        for c in courses
-    ]
-    print(json.dumps(output, indent=2))
-
-
-def list_assignments(args):
-    """List assignments for a course."""
-    _check_config()
-    url = f"{CANVAS_BASE_URL}/api/v1/courses/{args.course_id}/assignments"
-    params = {"per_page": args.per_page}
-    if args.order_by:
-        params["order_by"] = args.order_by
-    try:
-        assignments = _paginated_get(url, params)
-    except requests.HTTPError as e:
-        print(f"API error: {e.response.status_code} {e.response.text}", file=sys.stderr)
-        sys.exit(1)
-    output = [
-        {
-            "id": a["id"],
-            "name": a.get("name", ""),
-            "description": (a.get("description") or "")[:500],
-            "due_at": a.get("due_at"),
-            "points_possible": a.get("points_possible"),
-            "submission_types": a.get("submission_types", []),
-            "html_url": a.get("html_url", ""),
-            "course_id": a.get("course_id"),
-        }
-        for a in assignments
-    ]
-    print(json.dumps(output, indent=2))
-
-
-# =========================================================================
-# CLI parser
-# =========================================================================
-
-
-def main():
-    parser = argparse.ArgumentParser(
-        description="Canvas LMS API CLI for Hermes Agent"
-    )
-    sub = parser.add_subparsers(dest="command", required=True)
-
-    # --- list_courses ---
-    p = sub.add_parser("list_courses", help="List enrolled courses")
-    p.add_argument("--per-page", type=int, default=50, help="Results per page (default 50)")
-    p.add_argument(
-        "--enrollment-state",
-        default="",
-        help="Filter by enrollment state (active, invited_or_pending, completed)",
-    )
-    p.set_defaults(func=list_courses)
-
-    # --- list_assignments ---
-    p = sub.add_parser("list_assignments", help="List assignments for a course")
-    p.add_argument("course_id", help="Canvas course ID")
-    p.add_argument("--per-page", type=int, default=50, help="Results per page (default 50)")
-    p.add_argument(
-        "--order-by",
-        default="",
-        help="Order by field (due_at, name, position)",
-    )
-    p.set_defaults(func=list_assignments)
-
-    args = parser.parse_args()
-    args.func(args)
-
-
-if __name__ == "__main__":
-    main()

optional-skills/productivity/memento-flashcards/SKILL.md

@@ -1,324 +0,0 @@
----
-name: memento-flashcards
-description: >-
-  Spaced-repetition flashcard system. Create cards from facts or text,
-  chat with flashcards using free-text answers graded by the agent,
-  generate quizzes from YouTube transcripts, review due cards with
-  adaptive scheduling, and export/import decks as CSV.
-version: 1.0.0
-author: Memento AI
-license: MIT
-platforms: [macos, linux]
-metadata:
-  hermes:
-    tags: [Education, Flashcards, Spaced Repetition, Learning, Quiz, YouTube]
-    requires_toolsets: [terminal]
-    category: productivity
----
-
-# Memento Flashcards — Spaced-Repetition Flashcard Skill
-
-## Overview
-
-Memento gives you a local, file-based flashcard system with spaced-repetition scheduling.
-Users can chat with their flashcards by answering in free text and having the agent grade the response before scheduling the next review.
-Use it whenever the user wants to:
-
-- **Remember a fact** — turn any statement into a Q/A flashcard
-- **Study with spaced repetition** — review due cards with adaptive intervals and agent-graded free-text answers
-- **Quiz from a YouTube video** — fetch a transcript and generate a 5-question quiz
-- **Manage decks** — organise cards into collections, export/import CSV
-
-All card data lives in a single JSON file. No external API keys are required — you (the agent) generate flashcard content and quiz questions directly.
-
-User-facing response style for Memento Flashcards:
-- Use plain text only. Do not use Markdown formatting in replies to the user.
-- Keep review and quiz feedback brief and neutral. Avoid extra praise, pep, or long explanations.
-
-## When to Use
-
-Use this skill when the user wants to:
-- Save facts as flashcards for later review
-- Review due cards with spaced repetition
-- Generate a quiz from a YouTube video transcript
-- Import, export, inspect, or delete flashcard data
-
-Do not use this skill for general Q&A, coding help, or non-memory tasks.
-
-## Quick Reference
-
-| User intent | Action |
-|---|---|
-| "Remember that X" / "save this as a flashcard" | Generate a Q/A card, call `memento_cards.py add` |
-| Sends a fact without mentioning flashcards | Ask "Want me to save this as a Memento flashcard?" — only create if confirmed |
-| "Create a flashcard" | Ask for Q, A, collection; call `memento_cards.py add` |
-| "Review my cards" | Call `memento_cards.py due`, present cards one-by-one |
-| "Quiz me on [YouTube URL]" | Call `youtube_quiz.py fetch VIDEO_ID`, generate 5 questions, call `memento_cards.py add-quiz` |
-| "Export my cards" | Call `memento_cards.py export --output PATH` |
-| "Import cards from CSV" | Call `memento_cards.py import --file PATH --collection NAME` |
-| "Show my stats" | Call `memento_cards.py stats` |
-| "Delete a card" | Call `memento_cards.py delete --id ID` |
-| "Delete a collection" | Call `memento_cards.py delete-collection --collection NAME` |
-
-## Card Storage
-
-Cards are stored in a JSON file at:
-
-```
-~/.hermes/skills/productivity/memento-flashcards/data/cards.json
-```
-
-**Never edit this file directly.** Always use `memento_cards.py` subcommands. The script handles atomic writes (write to temp file, then rename) to prevent corruption.
-
-The file is created automatically on first use.
-
-## Procedure
-
-### Creating Cards from Facts
-
-### Activation Rules
-
-Not every factual statement should become a flashcard. Use this three-tier check:
-
-1. **Explicit intent** — the user mentions "memento", "flashcard", "remember this", "save this card", "add a card", or similar phrasing that clearly requests a flashcard → **create the card directly**, no confirmation needed.
-2. **Implicit intent** — the user sends a factual statement without mentioning flashcards (e.g. "The speed of light is 299,792 km/s") → **ask first**: "Want me to save this as a Memento flashcard?" Only create the card if the user confirms.
-3. **No intent** — the message is a coding task, a question, instructions, normal conversation, or anything that is clearly not a fact to memorize → **do NOT activate this skill at all**. Let other skills or default behavior handle it.
-
-When activation is confirmed (tier 1 directly, tier 2 after confirmation), generate a flashcard:
-
-**Step 1:** Turn the statement into a Q/A pair. Use this format internally:
-
-```
-Turn the factual statement into a front-back pair.
-Return exactly two lines:
-Q: <question text>
-A: <answer text>
-
-Statement: "{statement}"
-```
-
-Rules:
-- The question should test recall of the key fact
-- The answer should be concise and direct
-
-**Step 2:** Call the script to store the card:
-
-```bash
-python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py add \
-  --question "What year did World War 2 end?" \
-  --answer "1945" \
-  --collection "History"
-```
-
-If the user doesn't specify a collection, use `"General"` as the default.
-
-The script outputs JSON confirming the created card.
-
-### Manual Card Creation
-
-When the user explicitly asks to create a flashcard, ask them for:
-1. The question (front of card)
-2. The answer (back of card)
-3. The collection name (optional — default to `"General"`)
-
-Then call `memento_cards.py add` as above.
-
-### Reviewing Due Cards
-
-When the user wants to review, fetch all due cards:
-
-```bash
-python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py due
-```
-
-This returns a JSON array of cards where `next_review_at <= now`. If a collection filter is needed:
-
-```bash
-python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py due --collection "History"
-```
-
-**Review flow (free-text grading):**
-
-Here is an example of the EXACT interaction pattern you must follow. The user answers, you grade them, tell them the correct answer, then rate the card.
-
-**Example interaction:**
-
-> **Agent:** What year did the Berlin Wall fall?
->
-> **User:** 1991
->
-> **Agent:** Not quite. The Berlin Wall fell in 1989. Next review is tomorrow.
-> *(agent calls: memento_cards.py rate --id ABC --rating hard --user-answer "1991")*
->
-> Next question: Who was the first person to walk on the moon?
-
-**The rules:**
-
-1. Show only the question. Wait for the user to answer.
-2. After receiving their answer, compare it to the expected answer and grade it:
-   - **correct** → user got the key fact right (even if worded differently)
-   - **partial** → right track but missing the core detail
-   - **incorrect** → wrong or off-topic
-3. **You MUST tell the user the correct answer and how they did.** Keep it short and plain-text. Use this format:
-   - correct: "Correct. Answer: {answer}. Next review in 7 days."
-   - partial: "Close. Answer: {answer}. {what they missed}. Next review in 3 days."
-   - incorrect: "Not quite. Answer: {answer}. Next review tomorrow."
-4. Then call the rate command: correct→easy, partial→good, incorrect→hard.
-5. Then show the next question.
-
-```bash
-python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py rate \
-  --id CARD_ID --rating easy --user-answer "what the user said"
-```
-
-**Never skip step 3.** The user must always see the correct answer and feedback before you move on.
-
-If no cards are due, tell the user: "No cards due for review right now. Check back later!"
-
-**Retire override:** At any point the user can say "retire this card" to permanently remove it from reviews. Use `--rating retire` for this.
-
-### Spaced Repetition Algorithm
-
-The rating determines the next review interval:
-
-| Rating | Interval | ease_streak | Status change |
-|---|---|---|---|
-| **hard** | +1 day | reset to 0 | stays learning |
-| **good** | +3 days | reset to 0 | stays learning |
-| **easy** | +7 days | +1 | if ease_streak >= 3 → retired |
-| **retire** | permanent | reset to 0 | → retired |
-
-- **learning**: card is actively in rotation
-- **retired**: card won't appear in reviews (user has mastered it or manually retired it)
-- Three consecutive "easy" ratings automatically retire a card
-
-### YouTube Quiz Generation
-
-When the user sends a YouTube URL and wants a quiz:
-
-**Step 1:** Extract the video ID from the URL (e.g. `dQw4w9WgXcQ` from `https://www.youtube.com/watch?v=dQw4w9WgXcQ`).
-
-**Step 2:** Fetch the transcript:
-
-```bash
-python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/youtube_quiz.py fetch VIDEO_ID
-```
-
-This returns `{"title": "...", "transcript": "..."}` or an error.
-
-If the script reports `missing_dependency`, tell the user to install it:
-```bash
-pip install youtube-transcript-api
-```
-
-**Step 3:** Generate 5 quiz questions from the transcript. Use these rules:
-
-```
-You are creating a 5-question quiz for a podcast episode.
-Return ONLY a JSON array with exactly 5 objects.
-Each object must contain keys 'question' and 'answer'.
-
-Selection criteria:
-- Prioritize important, surprising, or foundational facts.
-- Skip filler, obvious details, and facts that require heavy context.
-- Never return true/false questions.
-- Never ask only for a date.
-
-Question rules:
-- Each question must test exactly one discrete fact.
-- Use clear, unambiguous wording.
-- Prefer What, Who, How many, Which.
-- Avoid open-ended Describe or Explain prompts.
-
-Answer rules:
-- Each answer must be under 240 characters.
-- Lead with the answer itself, not preamble.
-- Add only minimal clarifying detail if needed.
-```
-
-Use the first 15,000 characters of the transcript as context. Generate the questions yourself (you are the LLM).
-
-**Step 4:** Validate the output is valid JSON with exactly 5 items, each having non-empty `question` and `answer` strings. If validation fails, retry once.
-
-**Step 5:** Store quiz cards:
-
-```bash
-python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py add-quiz \
-  --video-id "VIDEO_ID" \
-  --questions '[{"question":"...","answer":"..."},...]' \
-  --collection "Quiz - Episode Title"
-```
-
-The script deduplicates by `video_id` — if cards for that video already exist, it skips creation and reports the existing cards.
-
-**Step 6:** Present questions one-by-one using the same free-text grading flow:
-1. Show "Question 1/5: ..." and wait for the user's answer. Never include the answer or any hint about revealing it.
-2. Wait for the user to answer in their own words
-3. Grade their answer using the grading prompt (see "Reviewing Due Cards" section)
-4. **IMPORTANT: You MUST reply to the user with feedback before doing anything else.** Show the grade, the correct answer, and when the card is next due. Do NOT silently skip to the next question. Keep it short and plain-text. Example: "Not quite. Answer: {answer}. Next review tomorrow."
-5. **After showing feedback**, call the rate command and then show the next question in the same message:
-```bash
-python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py rate \
-  --id CARD_ID --rating easy --user-answer "what the user said"
-```
-6. Repeat. Every answer MUST receive visible feedback before the next question.
-
-### Export/Import CSV
-
-**Export:**
-```bash
-python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py export \
-  --output ~/flashcards.csv
-```
-
-Produces a 3-column CSV: `question,answer,collection` (no header row).
-
-**Import:**
-```bash
-python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py import \
-  --file ~/flashcards.csv \
-  --collection "Imported"
-```
-
-Reads a CSV with columns: question, answer, and optionally collection (column 3). If the collection column is missing, uses the `--collection` argument.
-
-### Statistics
-
-```bash
-python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py stats
-```
-
-Returns JSON with:
-- `total`: total card count
-- `learning`: cards in active rotation
-- `retired`: mastered cards
-- `due_now`: cards due for review right now
-- `collections`: breakdown by collection name
-
-## Pitfalls
-
-- **Never edit `cards.json` directly** — always use the script subcommands to avoid corruption
-- **Transcript failures** — some YouTube videos have no English transcript or have transcripts disabled; inform the user and suggest another video
-- **Optional dependency** — `youtube_quiz.py` needs `youtube-transcript-api`; if missing, tell the user to run `pip install youtube-transcript-api`
-- **Large imports** — CSV imports with thousands of rows work fine but the JSON output may be verbose; summarize the result for the user
-- **Video ID extraction** — support both `youtube.com/watch?v=ID` and `youtu.be/ID` URL formats
-
-## Verification
-
-Verify the helper scripts directly:
-
-```bash
-python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py stats
-python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py add --question "Capital of France?" --answer "Paris" --collection "General"
-python3 ~/.hermes/skills/productivity/memento-flashcards/scripts/memento_cards.py due
-```
-
-If you are testing from the repo checkout, run:
-
-```bash
-pytest tests/skills/test_memento_cards.py tests/skills/test_youtube_quiz.py -q
-```
-
-Agent-level verification:
-- Start a review and confirm feedback is plain text, brief, and always includes the correct answer before the next card
-- Run a YouTube quiz flow and confirm each answer receives visible feedback before the next question

optional-skills/productivity/memento-flashcards/scripts/memento_cards.py

@@ -1,353 +0,0 @@
-#!/usr/bin/env python3
-"""Memento card storage, spaced-repetition engine, and CSV I/O.
-
-Stdlib-only. All output is JSON for agent parsing.
-Data file: $HERMES_HOME/skills/productivity/memento-flashcards/data/cards.json
-"""
-
-import argparse
-import csv
-import json
-import os
-import sys
-import tempfile
-import uuid
-from datetime import datetime, timedelta, timezone
-from pathlib import Path
-
-_HERMES_HOME = Path(os.environ.get("HERMES_HOME", Path.home() / ".hermes"))
-DATA_DIR = _HERMES_HOME / "skills" / "productivity" / "memento-flashcards" / "data"
-CARDS_FILE = DATA_DIR / "cards.json"
-
-RETIRED_SENTINEL = "9999-12-31T23:59:59+00:00"
-
-
-def _now() -> datetime:
-    return datetime.now(timezone.utc)
-
-
-def _iso(dt: datetime) -> str:
-    return dt.isoformat()
-
-
-def _parse_iso(s: str) -> datetime:
-    return datetime.fromisoformat(s)
-
-
-def _empty_store() -> dict:
-    return {"cards": [], "version": 1}
-
-
-def _load() -> dict:
-    if not CARDS_FILE.exists():
-        return _empty_store()
-    try:
-        with open(CARDS_FILE, "r", encoding="utf-8") as f:
-            data = json.load(f)
-        if not isinstance(data, dict) or "cards" not in data:
-            return _empty_store()
-        return data
-    except (json.JSONDecodeError, OSError):
-        return _empty_store()
-
-
-def _save(data: dict) -> None:
-    DATA_DIR.mkdir(parents=True, exist_ok=True)
-    fd, tmp = tempfile.mkstemp(dir=DATA_DIR, suffix=".tmp")
-    try:
-        with os.fdopen(fd, "w", encoding="utf-8") as f:
-            json.dump(data, f, indent=2, ensure_ascii=False)
-            f.write("\n")
-        os.replace(tmp, CARDS_FILE)
-    except BaseException:
-        try:
-            os.unlink(tmp)
-        except OSError:
-            pass
-        raise
-
-
-def _out(obj: object) -> None:
-    json.dump(obj, sys.stdout, indent=2, ensure_ascii=False)
-    sys.stdout.write("\n")
-
-
-# ── Subcommands ──────────────────────────────────────────────────────────────
-
-def cmd_add(args: argparse.Namespace) -> None:
-    data = _load()
-    now = _now()
-    card = {
-        "id": str(uuid.uuid4()),
-        "question": args.question,
-        "answer": args.answer,
-        "collection": args.collection or "General",
-        "status": "learning",
-        "ease_streak": 0,
-        "next_review_at": _iso(now),
-        "created_at": _iso(now),
-        "video_id": None,
-        "last_user_answer": None,
-    }
-    data["cards"].append(card)
-    _save(data)
-    _out({"ok": True, "card": card})
-
-
-def cmd_add_quiz(args: argparse.Namespace) -> None:
-    data = _load()
-    now = _now()
-
-    try:
-        questions = json.loads(args.questions)
-    except json.JSONDecodeError as exc:
-        _out({"ok": False, "error": f"Invalid JSON for --questions: {exc}"})
-        sys.exit(1)
-
-    # Dedup: skip if cards with this video_id already exist
-    existing_ids = {c["video_id"] for c in data["cards"] if c.get("video_id")}
-    if args.video_id in existing_ids:
-        existing = [c for c in data["cards"] if c.get("video_id") == args.video_id]
-        _out({"ok": True, "skipped": True, "reason": "duplicate_video_id", "existing_count": len(existing), "cards": existing})
-        return
-
-    created = []
-    for qa in questions:
-        card = {
-            "id": str(uuid.uuid4()),
-            "question": qa["question"],
-            "answer": qa["answer"],
-            "collection": args.collection or "Quiz",
-            "status": "learning",
-            "ease_streak": 0,
-            "next_review_at": _iso(now),
-            "created_at": _iso(now),
-            "video_id": args.video_id,
-            "last_user_answer": None,
-        }
-        data["cards"].append(card)
-        created.append(card)
-
-    _save(data)
-    _out({"ok": True, "created_count": len(created), "cards": created})
-
-
-def cmd_due(args: argparse.Namespace) -> None:
-    data = _load()
-    now = _now()
-    due = []
-    for card in data["cards"]:
-        if card["status"] == "retired":
-            continue
-        review_at = _parse_iso(card["next_review_at"])
-        if review_at <= now:
-            if args.collection and card["collection"] != args.collection:
-                continue
-            due.append(card)
-    _out({"ok": True, "count": len(due), "cards": due})
-
-
-def cmd_rate(args: argparse.Namespace) -> None:
-    data = _load()
-    now = _now()
-    card = None
-    for c in data["cards"]:
-        if c["id"] == args.id:
-            card = c
-            break
-    if not card:
-        _out({"ok": False, "error": f"Card not found: {args.id}"})
-        sys.exit(1)
-
-    rating = args.rating
-    user_answer = getattr(args, "user_answer", None)
-    if user_answer is not None:
-        card["last_user_answer"] = user_answer
-
-    if rating == "retire":
-        card["status"] = "retired"
-        card["next_review_at"] = RETIRED_SENTINEL
-        card["ease_streak"] = 0
-    elif rating == "hard":
-        card["next_review_at"] = _iso(now + timedelta(days=1))
-        card["ease_streak"] = 0
-    elif rating == "good":
-        card["next_review_at"] = _iso(now + timedelta(days=3))
-        card["ease_streak"] = 0
-    elif rating == "easy":
-        card["next_review_at"] = _iso(now + timedelta(days=7))
-        card["ease_streak"] = card.get("ease_streak", 0) + 1
-        if card["ease_streak"] >= 3:
-            card["status"] = "retired"
-
-    _save(data)
-    _out({"ok": True, "card": card})
-
-
-def cmd_list(args: argparse.Namespace) -> None:
-    data = _load()
-    cards = data["cards"]
-    if args.collection:
-        cards = [c for c in cards if c["collection"] == args.collection]
-    if args.status:
-        cards = [c for c in cards if c["status"] == args.status]
-    _out({"ok": True, "count": len(cards), "cards": cards})
-
-
-def cmd_stats(args: argparse.Namespace) -> None:
-    data = _load()
-    now = _now()
-    total = len(data["cards"])
-    learning = sum(1 for c in data["cards"] if c["status"] == "learning")
-    retired = sum(1 for c in data["cards"] if c["status"] == "retired")
-    due_now = 0
-    for c in data["cards"]:
-        if c["status"] != "retired" and _parse_iso(c["next_review_at"]) <= now:
-            due_now += 1
-
-    collections: dict[str, int] = {}
-    for c in data["cards"]:
-        name = c["collection"]
-        collections[name] = collections.get(name, 0) + 1
-
-    _out({
-        "ok": True,
-        "total": total,
-        "learning": learning,
-        "retired": retired,
-        "due_now": due_now,
-        "collections": collections,
-    })
-
-
-def cmd_export(args: argparse.Namespace) -> None:
-    data = _load()
-    output_path = Path(args.output).expanduser()
-    with open(output_path, "w", newline="", encoding="utf-8") as f:
-        writer = csv.writer(f, lineterminator="\n")
-        for card in data["cards"]:
-            writer.writerow([card["question"], card["answer"], card["collection"]])
-    _out({"ok": True, "exported": len(data["cards"]), "path": str(output_path)})
-
-
-def cmd_import(args: argparse.Namespace) -> None:
-    data = _load()
-    now = _now()
-    file_path = Path(args.file).expanduser()
-
-    if not file_path.exists():
-        _out({"ok": False, "error": f"File not found: {file_path}"})
-        sys.exit(1)
-
-    created = 0
-    with open(file_path, "r", encoding="utf-8") as f:
-        reader = csv.reader(f)
-        for row in reader:
-            if len(row) < 2:
-                continue
-            question = row[0].strip()
-            answer = row[1].strip()
-            collection = row[2].strip() if len(row) >= 3 and row[2].strip() else (args.collection or "Imported")
-            if not question or not answer:
-                continue
-            card = {
-                "id": str(uuid.uuid4()),
-                "question": question,
-                "answer": answer,
-                "collection": collection,
-                "status": "learning",
-                "ease_streak": 0,
-                "next_review_at": _iso(now),
-                "created_at": _iso(now),
-                "video_id": None,
-                "last_user_answer": None,
-            }
-            data["cards"].append(card)
-            created += 1
-
-    _save(data)
-    _out({"ok": True, "imported": created})
-
-
-def cmd_delete(args: argparse.Namespace) -> None:
-    data = _load()
-    original = len(data["cards"])
-    data["cards"] = [c for c in data["cards"] if c["id"] != args.id]
-    removed = original - len(data["cards"])
-    if removed == 0:
-        _out({"ok": False, "error": f"Card not found: {args.id}"})
-        sys.exit(1)
-    _save(data)
-    _out({"ok": True, "deleted": args.id})
-
-
-def cmd_delete_collection(args: argparse.Namespace) -> None:
-    data = _load()
-    original = len(data["cards"])
-    data["cards"] = [c for c in data["cards"] if c["collection"] != args.collection]
-    removed = original - len(data["cards"])
-    _save(data)
-    _out({"ok": True, "deleted_count": removed, "collection": args.collection})
-
-
-# ── CLI ──────────────────────────────────────────────────────────────────────
-
-def main() -> None:
-    parser = argparse.ArgumentParser(description="Memento flashcard manager")
-    sub = parser.add_subparsers(dest="command", required=True)
-
-    p_add = sub.add_parser("add", help="Create one card")
-    p_add.add_argument("--question", required=True)
-    p_add.add_argument("--answer", required=True)
-    p_add.add_argument("--collection", default="General")
-
-    p_quiz = sub.add_parser("add-quiz", help="Batch-add quiz cards")
-    p_quiz.add_argument("--video-id", required=True)
-    p_quiz.add_argument("--questions", required=True, help="JSON array of {question, answer}")
-    p_quiz.add_argument("--collection", default="Quiz")
-
-    p_due = sub.add_parser("due", help="List due cards")
-    p_due.add_argument("--collection", default=None)
-
-    p_rate = sub.add_parser("rate", help="Rate a card")
-    p_rate.add_argument("--id", required=True)
-    p_rate.add_argument("--rating", required=True, choices=["easy", "good", "hard", "retire"])
-    p_rate.add_argument("--user-answer", default=None)
-
-    p_list = sub.add_parser("list", help="List cards")
-    p_list.add_argument("--collection", default=None)
-    p_list.add_argument("--status", default=None, choices=["learning", "retired"])
-
-    sub.add_parser("stats", help="Show statistics")
-
-    p_export = sub.add_parser("export", help="Export cards to CSV")
-    p_export.add_argument("--output", required=True)
-
-    p_import = sub.add_parser("import", help="Import cards from CSV")
-    p_import.add_argument("--file", required=True)
-    p_import.add_argument("--collection", default="Imported")
-
-    p_del = sub.add_parser("delete", help="Delete one card")
-    p_del.add_argument("--id", required=True)
-
-    p_delcol = sub.add_parser("delete-collection", help="Delete all cards in a collection")
-    p_delcol.add_argument("--collection", required=True)
-
-    args = parser.parse_args()
-    cmd_map = {
-        "add": cmd_add,
-        "add-quiz": cmd_add_quiz,
-        "due": cmd_due,
-        "rate": cmd_rate,
-        "list": cmd_list,
-        "stats": cmd_stats,
-        "export": cmd_export,
-        "import": cmd_import,
-        "delete": cmd_delete,
-        "delete-collection": cmd_delete_collection,
-    }
-    cmd_map[args.command](args)
-
-
-if __name__ == "__main__":
-    main()

optional-skills/productivity/memento-flashcards/scripts/youtube_quiz.py

@@ -1,88 +0,0 @@
-#!/usr/bin/env python3
-"""Fetch YouTube transcripts for Memento quiz generation.
-
-Requires: pip install youtube-transcript-api
-The quiz question *generation* is done by the agent's LLM — this script only fetches transcripts.
-"""
-
-import argparse
-import json
-import re
-import sys
-
-
-def _out(obj: object) -> None:
-    json.dump(obj, sys.stdout, indent=2, ensure_ascii=False)
-    sys.stdout.write("\n")
-
-
-def _normalize_segments(segments: list) -> str:
-    parts = []
-    for seg in segments:
-        text = str(seg.get("text", "")).strip()
-        if text:
-            parts.append(text)
-    return re.sub(r"\s+", " ", " ".join(parts)).strip()
-
-
-def cmd_fetch(args: argparse.Namespace) -> None:
-    try:
-        import youtube_transcript_api  # noqa: F811
-    except ImportError:
-        _out({
-            "ok": False,
-            "error": "missing_dependency",
-            "message": "Run: pip install youtube-transcript-api",
-        })
-        sys.exit(1)
-
-    video_id = args.video_id
-    languages = ["en", "en-US", "en-GB", "en-CA", "en-AU"]
-
-    api = youtube_transcript_api.YouTubeTranscriptApi()
-    try:
-        raw = api.fetch(video_id, languages=languages)
-    except Exception as exc:
-        error_type = type(exc).__name__
-        _out({
-            "ok": False,
-            "error": "transcript_unavailable",
-            "error_type": error_type,
-            "message": f"Could not fetch transcript for {video_id}: {exc}",
-        })
-        sys.exit(1)
-
-    segments = raw
-    if hasattr(raw, "to_raw_data"):
-        segments = raw.to_raw_data()
-
-    text = _normalize_segments(segments)
-    if not text:
-        _out({
-            "ok": False,
-            "error": "empty_transcript",
-            "message": f"Transcript for {video_id} contained no usable text.",
-        })
-        sys.exit(1)
-
-    _out({
-        "ok": True,
-        "video_id": video_id,
-        "transcript": text,
-    })
-
-
-def main() -> None:
-    parser = argparse.ArgumentParser(description="Memento YouTube transcript fetcher")
-    sub = parser.add_subparsers(dest="command", required=True)
-
-    p_fetch = sub.add_parser("fetch", help="Fetch transcript for a video")
-    p_fetch.add_argument("video_id", help="YouTube video ID")
-
-    args = parser.parse_args()
-    if args.command == "fetch":
-        cmd_fetch(args)
-
-
-if __name__ == "__main__":
-    main()

optional-skills/productivity/siyuan/SKILL.md

@@ -1,297 +0,0 @@
----
-name: siyuan
-description: SiYuan Note API for searching, reading, creating, and managing blocks and documents in a self-hosted knowledge base via curl.
-version: 1.0.0
-author: FEUAZUR
-license: MIT
-metadata:
-  hermes:
-    tags: [SiYuan, Notes, Knowledge Base, PKM, API]
-    related_skills: [obsidian, notion]
-    homepage: https://github.com/siyuan-note/siyuan
-prerequisites:
-  env_vars: [SIYUAN_TOKEN]
-  commands: [curl, jq]
-required_environment_variables:
-  - name: SIYUAN_TOKEN
-    prompt: SiYuan API token
-    help: "Settings > About in SiYuan desktop app"
-  - name: SIYUAN_URL
-    prompt: SiYuan instance URL (default http://127.0.0.1:6806)
-    required_for: remote instances
----
-
-# SiYuan Note API
-
-Use the [SiYuan](https://github.com/siyuan-note/siyuan) kernel API via curl to search, read, create, update, and delete blocks and documents in a self-hosted knowledge base. No extra tools needed -- just curl and an API token.
-
-## Prerequisites
-
-1. Install and run SiYuan (desktop or Docker)
-2. Get your API token: **Settings > About > API token**
-3. Store it in `~/.hermes/.env`:
-   ```
-   SIYUAN_TOKEN=your_token_here
-   SIYUAN_URL=http://127.0.0.1:6806
-   ```
-   `SIYUAN_URL` defaults to `http://127.0.0.1:6806` if not set.
-
-## API Basics
-
-All SiYuan API calls are **POST with JSON body**. Every request follows this pattern:
-
-```bash
-curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/..." \
-  -H "Authorization: Token $SIYUAN_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"param": "value"}'
-```
-
-Responses are JSON with this structure:
-```json
-{"code": 0, "msg": "", "data": { ... }}
-```
-`code: 0` means success. Any other value is an error -- check `msg` for details.
-
-**ID format:** SiYuan IDs look like `20210808180117-6v0mkxr` (14-digit timestamp + 7 alphanumeric chars).
-
-## Quick Reference
-
-| Operation | Endpoint |
-|-----------|----------|
-| Full-text search | `/api/search/fullTextSearchBlock` |
-| SQL query | `/api/query/sql` |
-| Read block | `/api/block/getBlockKramdown` |
-| Read children | `/api/block/getChildBlocks` |
-| Get path | `/api/filetree/getHPathByID` |
-| Get attributes | `/api/attr/getBlockAttrs` |
-| List notebooks | `/api/notebook/lsNotebooks` |
-| List documents | `/api/filetree/listDocsByPath` |
-| Create notebook | `/api/notebook/createNotebook` |
-| Create document | `/api/filetree/createDocWithMd` |
-| Append block | `/api/block/appendBlock` |
-| Update block | `/api/block/updateBlock` |
-| Rename document | `/api/filetree/renameDocByID` |
-| Set attributes | `/api/attr/setBlockAttrs` |
-| Delete block | `/api/block/deleteBlock` |
-| Delete document | `/api/filetree/removeDocByID` |
-| Export as Markdown | `/api/export/exportMdContent` |
-
-## Common Operations
-
-### Search (Full-Text)
-
-```bash
-curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/search/fullTextSearchBlock" \
-  -H "Authorization: Token $SIYUAN_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"query": "meeting notes", "page": 0}' | jq '.data.blocks[:5]'
-```
-
-### Search (SQL)
-
-Query the blocks database directly. Only SELECT statements are safe.
-
-```bash
-curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/query/sql" \
-  -H "Authorization: Token $SIYUAN_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"stmt": "SELECT id, content, type, box FROM blocks WHERE content LIKE '\''%keyword%'\'' AND type='\''p'\'' LIMIT 20"}' | jq '.data'
-```
-
-Useful columns: `id`, `parent_id`, `root_id`, `box` (notebook ID), `path`, `content`, `type`, `subtype`, `created`, `updated`.
-
-### Read Block Content
-
-Returns block content in Kramdown (Markdown-like) format.
-
-```bash
-curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/block/getBlockKramdown" \
-  -H "Authorization: Token $SIYUAN_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"id": "20210808180117-6v0mkxr"}' | jq '.data.kramdown'
-```
-
-### Read Child Blocks
-
-```bash
-curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/block/getChildBlocks" \
-  -H "Authorization: Token $SIYUAN_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"id": "20210808180117-6v0mkxr"}' | jq '.data'
-```
-
-### Get Human-Readable Path
-
-```bash
-curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/filetree/getHPathByID" \
-  -H "Authorization: Token $SIYUAN_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"id": "20210808180117-6v0mkxr"}' | jq '.data'
-```
-
-### Get Block Attributes
-
-```bash
-curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/attr/getBlockAttrs" \
-  -H "Authorization: Token $SIYUAN_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"id": "20210808180117-6v0mkxr"}' | jq '.data'
-```
-
-### List Notebooks
-
-```bash
-curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/notebook/lsNotebooks" \
-  -H "Authorization: Token $SIYUAN_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{}' | jq '.data.notebooks[] | {id, name, closed}'
-```
-
-### List Documents in a Notebook
-
-```bash
-curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/filetree/listDocsByPath" \
-  -H "Authorization: Token $SIYUAN_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"notebook": "NOTEBOOK_ID", "path": "/"}' | jq '.data.files[] | {id, name}'
-```
-
-### Create a Document
-
-```bash
-curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/filetree/createDocWithMd" \
-  -H "Authorization: Token $SIYUAN_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "notebook": "NOTEBOOK_ID",
-    "path": "/Meeting Notes/2026-03-22",
-    "markdown": "# Meeting Notes\n\n- Discussed project timeline\n- Assigned tasks"
-  }' | jq '.data'
-```
-
-### Create a Notebook
-
-```bash
-curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/notebook/createNotebook" \
-  -H "Authorization: Token $SIYUAN_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"name": "My New Notebook"}' | jq '.data.notebook.id'
-```
-
-### Append Block to Document
-
-```bash
-curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/block/appendBlock" \
-  -H "Authorization: Token $SIYUAN_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "parentID": "DOCUMENT_OR_BLOCK_ID",
-    "data": "New paragraph added at the end.",
-    "dataType": "markdown"
-  }' | jq '.data'
-```
-
-Also available: `/api/block/prependBlock` (same params, inserts at the beginning) and `/api/block/insertBlock` (uses `previousID` instead of `parentID` to insert after a specific block).
-
-### Update Block Content
-
-```bash
-curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/block/updateBlock" \
-  -H "Authorization: Token $SIYUAN_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "id": "BLOCK_ID",
-    "data": "Updated content here.",
-    "dataType": "markdown"
-  }' | jq '.data'
-```
-
-### Rename a Document
-
-```bash
-curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/filetree/renameDocByID" \
-  -H "Authorization: Token $SIYUAN_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"id": "DOCUMENT_ID", "title": "New Title"}'
-```
-
-### Set Block Attributes
-
-Custom attributes must be prefixed with `custom-`:
-
-```bash
-curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/attr/setBlockAttrs" \
-  -H "Authorization: Token $SIYUAN_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "id": "BLOCK_ID",
-    "attrs": {
-      "custom-status": "reviewed",
-      "custom-priority": "high"
-    }
-  }'
-```
-
-### Delete a Block
-
-```bash
-curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/block/deleteBlock" \
-  -H "Authorization: Token $SIYUAN_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"id": "BLOCK_ID"}'
-```
-
-To delete a whole document: use `/api/filetree/removeDocByID` with `{"id": "DOC_ID"}`.
-To delete a notebook: use `/api/notebook/removeNotebook` with `{"notebook": "NOTEBOOK_ID"}`.
-
-### Export Document as Markdown
-
-```bash
-curl -s -X POST "${SIYUAN_URL:-http://127.0.0.1:6806}/api/export/exportMdContent" \
-  -H "Authorization: Token $SIYUAN_TOKEN" \
-  -H "Content-Type: application/json" \
-  -d '{"id": "DOCUMENT_ID"}' | jq -r '.data.content'
-```
-
-## Block Types
-
-Common `type` values in SQL queries:
-
-| Type | Description |
-|------|-------------|
-| `d` | Document (root block) |
-| `p` | Paragraph |
-| `h` | Heading |
-| `l` | List |
-| `i` | List item |
-| `c` | Code block |
-| `m` | Math block |
-| `t` | Table |
-| `b` | Blockquote |
-| `s` | Super block |
-| `html` | HTML block |
-
-## Pitfalls
-
-- **All endpoints are POST** -- even read-only operations. Do not use GET.
-- **SQL safety**: only use SELECT queries. INSERT/UPDATE/DELETE/DROP are dangerous and should never be sent.
-- **ID validation**: IDs match the pattern `YYYYMMDDHHmmss-xxxxxxx`. Reject anything else.
-- **Error responses**: always check `code != 0` in responses before processing `data`.
-- **Large documents**: block content and export results can be very large. Use `LIMIT` in SQL and pipe through `jq` to extract only what you need.
-- **Notebook IDs**: when working with a specific notebook, get its ID first via `lsNotebooks`.
-
-## Alternative: MCP Server
-
-If you prefer a native integration instead of curl, install the SiYuan MCP server:
-
-```yaml
-# In ~/.hermes/config.yaml under mcp_servers:
-mcp_servers:
-  siyuan:
-    command: npx
-    args: ["-y", "@porkll/siyuan-mcp"]
-    env:
-      SIYUAN_TOKEN: "your_token"
-      SIYUAN_URL: "http://127.0.0.1:6806"
-```

optional-skills/research/scrapling/SKILL.md

@@ -1,335 +0,0 @@
----
-name: scrapling
-description: Web scraping with Scrapling - HTTP fetching, stealth browser automation, Cloudflare bypass, and spider crawling via CLI and Python.
-version: 1.0.0
-author: FEUAZUR
-license: MIT
-metadata:
-  hermes:
-    tags: [Web Scraping, Browser, Cloudflare, Stealth, Crawling, Spider]
-    related_skills: [duckduckgo-search, domain-intel]
-    homepage: https://github.com/D4Vinci/Scrapling
-prerequisites:
-  commands: [scrapling, python]
----
-
-# Scrapling
-
-[Scrapling](https://github.com/D4Vinci/Scrapling) is a web scraping framework with anti-bot bypass, stealth browser automation, and a spider framework. It provides three fetching strategies (HTTP, dynamic JS, stealth/Cloudflare) and a full CLI.
-
-**This skill is for educational and research purposes only.** Users must comply with local/international data scraping laws and respect website Terms of Service.
-
-## When to Use
-
-- Scraping static HTML pages (faster than browser tools)
-- Scraping JS-rendered pages that need a real browser
-- Bypassing Cloudflare Turnstile or bot detection
-- Crawling multiple pages with a spider
-- When the built-in `web_extract` tool does not return the data you need
-
-## Installation
-
-```bash
-pip install "scrapling[all]"
-scrapling install
-```
-
-Minimal install (HTTP only, no browser):
-```bash
-pip install scrapling
-```
-
-With browser automation only:
-```bash
-pip install "scrapling[fetchers]"
-scrapling install
-```
-
-## Quick Reference
-
-| Approach | Class | Use When |
-|----------|-------|----------|
-| HTTP | `Fetcher` / `FetcherSession` | Static pages, APIs, fast bulk requests |
-| Dynamic | `DynamicFetcher` / `DynamicSession` | JS-rendered content, SPAs |
-| Stealth | `StealthyFetcher` / `StealthySession` | Cloudflare, anti-bot protected sites |
-| Spider | `Spider` | Multi-page crawling with link following |
-
-## CLI Usage
-
-### Extract Static Page
-
-```bash
-scrapling extract get 'https://example.com' output.md
-```
-
-With CSS selector and browser impersonation:
-
-```bash
-scrapling extract get 'https://example.com' output.md \
-  --css-selector '.content' \
-  --impersonate 'chrome'
-```
-
-### Extract JS-Rendered Page
-
-```bash
-scrapling extract fetch 'https://example.com' output.md \
-  --css-selector '.dynamic-content' \
-  --disable-resources \
-  --network-idle
-```
-
-### Extract Cloudflare-Protected Page
-
-```bash
-scrapling extract stealthy-fetch 'https://protected-site.com' output.html \
-  --solve-cloudflare \
-  --block-webrtc \
-  --hide-canvas
-```
-
-### POST Request
-
-```bash
-scrapling extract post 'https://example.com/api' output.json \
-  --json '{"query": "search term"}'
-```
-
-### Output Formats
-
-The output format is determined by the file extension:
-- `.html` -- raw HTML
-- `.md` -- converted to Markdown
-- `.txt` -- plain text
-- `.json` / `.jsonl` -- JSON
-
-## Python: HTTP Scraping
-
-### Single Request
-
-```python
-from scrapling.fetchers import Fetcher
-
-page = Fetcher.get('https://quotes.toscrape.com/')
-quotes = page.css('.quote .text::text').getall()
-for q in quotes:
-    print(q)
-```
-
-### Session (Persistent Cookies)
-
-```python
-from scrapling.fetchers import FetcherSession
-
-with FetcherSession(impersonate='chrome') as session:
-    page = session.get('https://example.com/', stealthy_headers=True)
-    links = page.css('a::attr(href)').getall()
-    for link in links[:5]:
-        sub = session.get(link)
-        print(sub.css('h1::text').get())
-```
-
-### POST / PUT / DELETE
-
-```python
-page = Fetcher.post('https://api.example.com/data', json={"key": "value"})
-page = Fetcher.put('https://api.example.com/item/1', data={"name": "updated"})
-page = Fetcher.delete('https://api.example.com/item/1')
-```
-
-### With Proxy
-
-```python
-page = Fetcher.get('https://example.com', proxy='http://user:pass@proxy:8080')
-```
-
-## Python: Dynamic Pages (JS-Rendered)
-
-For pages that require JavaScript execution (SPAs, lazy-loaded content):
-
-```python
-from scrapling.fetchers import DynamicFetcher
-
-page = DynamicFetcher.fetch('https://example.com', headless=True)
-data = page.css('.js-loaded-content::text').getall()
-```
-
-### Wait for Specific Element
-
-```python
-page = DynamicFetcher.fetch(
-    'https://example.com',
-    wait_selector=('.results', 'visible'),
-    network_idle=True,
-)
-```
-
-### Disable Resources for Speed
-
-Blocks fonts, images, media, stylesheets (~25% faster):
-
-```python
-from scrapling.fetchers import DynamicSession
-
-with DynamicSession(headless=True, disable_resources=True, network_idle=True) as session:
-    page = session.fetch('https://example.com')
-    items = page.css('.item::text').getall()
-```
-
-### Custom Page Automation
-
-```python
-from playwright.sync_api import Page
-from scrapling.fetchers import DynamicFetcher
-
-def scroll_and_click(page: Page):
-    page.mouse.wheel(0, 3000)
-    page.wait_for_timeout(1000)
-    page.click('button.load-more')
-    page.wait_for_selector('.extra-results')
-
-page = DynamicFetcher.fetch('https://example.com', page_action=scroll_and_click)
-results = page.css('.extra-results .item::text').getall()
-```
-
-## Python: Stealth Mode (Anti-Bot Bypass)
-
-For Cloudflare-protected or heavily fingerprinted sites:
-
-```python
-from scrapling.fetchers import StealthyFetcher
-
-page = StealthyFetcher.fetch(
-    'https://protected-site.com',
-    headless=True,
-    solve_cloudflare=True,
-    block_webrtc=True,
-    hide_canvas=True,
-)
-content = page.css('.protected-content::text').getall()
-```
-
-### Stealth Session
-
-```python
-from scrapling.fetchers import StealthySession
-
-with StealthySession(headless=True, solve_cloudflare=True) as session:
-    page1 = session.fetch('https://protected-site.com/page1')
-    page2 = session.fetch('https://protected-site.com/page2')
-```
-
-## Element Selection
-
-All fetchers return a `Selector` object with these methods:
-
-### CSS Selectors
-
-```python
-page.css('h1::text').get()              # First h1 text
-page.css('a::attr(href)').getall()      # All link hrefs
-page.css('.quote .text::text').getall() # Nested selection
-```
-
-### XPath
-
-```python
-page.xpath('//div[@class="content"]/text()').getall()
-page.xpath('//a/@href').getall()
-```
-
-### Find Methods
-
-```python
-page.find_all('div', class_='quote')       # By tag + attribute
-page.find_by_text('Read more', tag='a')    # By text content
-page.find_by_regex(r'\$\d+\.\d{2}')       # By regex pattern
-```
-
-### Similar Elements
-
-Find elements with similar structure (useful for product listings, etc.):
-
-```python
-first_product = page.css('.product')[0]
-all_similar = first_product.find_similar()
-```
-
-### Navigation
-
-```python
-el = page.css('.target')[0]
-el.parent                # Parent element
-el.children              # Child elements
-el.next_sibling          # Next sibling
-el.prev_sibling          # Previous sibling
-```
-
-## Python: Spider Framework
-
-For multi-page crawling with link following:
-
-```python
-from scrapling.spiders import Spider, Request, Response
-
-class QuotesSpider(Spider):
-    name = "quotes"
-    start_urls = ["https://quotes.toscrape.com/"]
-    concurrent_requests = 10
-    download_delay = 1
-
-    async def parse(self, response: Response):
-        for quote in response.css('.quote'):
-            yield {
-                "text": quote.css('.text::text').get(),
-                "author": quote.css('.author::text').get(),
-                "tags": quote.css('.tag::text').getall(),
-            }
-
-        next_page = response.css('.next a::attr(href)').get()
-        if next_page:
-            yield response.follow(next_page)
-
-result = QuotesSpider().start()
-print(f"Scraped {len(result.items)} quotes")
-result.items.to_json("quotes.json")
-```
-
-### Multi-Session Spider
-
-Route requests to different fetcher types:
-
-```python
-from scrapling.fetchers import FetcherSession, AsyncStealthySession
-
-class SmartSpider(Spider):
-    name = "smart"
-    start_urls = ["https://example.com/"]
-
-    def configure_sessions(self, manager):
-        manager.add("fast", FetcherSession(impersonate="chrome"))
-        manager.add("stealth", AsyncStealthySession(headless=True), lazy=True)
-
-    async def parse(self, response: Response):
-        for link in response.css('a::attr(href)').getall():
-            if "protected" in link:
-                yield Request(link, sid="stealth")
-            else:
-                yield Request(link, sid="fast", callback=self.parse)
-```
-
-### Pause/Resume Crawling
-
-```python
-spider = QuotesSpider(crawldir="./crawl_checkpoint")
-spider.start()  # Ctrl+C to pause, re-run to resume from checkpoint
-```
-
-## Pitfalls
-
-- **Browser install required**: run `scrapling install` after pip install -- without it, `DynamicFetcher` and `StealthyFetcher` will fail
-- **Timeouts**: DynamicFetcher/StealthyFetcher timeout is in **milliseconds** (default 30000), Fetcher timeout is in **seconds**
-- **Cloudflare bypass**: `solve_cloudflare=True` adds 5-15 seconds to fetch time -- only enable when needed
-- **Resource usage**: StealthyFetcher runs a real browser -- limit concurrent usage
-- **Legal**: always check robots.txt and website ToS before scraping. This library is for educational and research purposes
-- **Python version**: requires Python 3.10+

pyproject.toml

@@ -26,7 +26,6 @@ dependencies = [
   # Interactive CLI (prompt_toolkit is used directly by cli.py)
   "prompt_toolkit>=3.0.52,<4",
   # Tools
-  "exa-py>=2.9.0,<3",
   "firecrawl-py>=4.16.0,<5",
   "parallel-web>=0.4.2,<1",
   "fal-client>=0.13.1,<1",
@@ -66,6 +65,21 @@ rl = [
   "wandb>=0.15.0,<1",
 ]
 yc-bench = ["yc-bench @ git+https://github.com/collinear-ai/yc-bench.git ; python_version >= '3.12'"]
+keystore = [
+  "argon2-cffi>=23.0,<24",
+  "pynacl>=1.5.0,<2",
+  "keyring>=25.0,<26",
+]
+wallet = [
+  "hermes-agent[keystore]",
+  "eth-account>=0.13.0,<1",
+  "web3>=7.0,<8",
+]
+wallet-solana = [
+  "hermes-agent[keystore]",
+  "solders>=0.21,<1",
+  "solana>=0.36,<1",
+]
 all = [
   "hermes-agent[modal]",
   "hermes-agent[daytona]",
@@ -83,6 +97,7 @@ all = [
   "hermes-agent[acp]",
   "hermes-agent[voice]",
   "hermes-agent[dingtalk]",
+  "hermes-agent[keystore]",
 ]
 
 [project.scripts]
@@ -94,7 +109,7 @@ hermes-acp = "acp_adapter.entry:main"
 py-modules = ["run_agent", "model_tools", "toolsets", "batch_runner", "trajectory_compressor", "toolset_distributions", "cli", "hermes_constants", "hermes_state", "hermes_time", "rl_cli", "utils"]
 
 [tool.setuptools.packages.find]
-include = ["agent", "tools", "tools.*", "hermes_cli", "gateway", "gateway.*", "cron", "honcho_integration", "acp_adapter"]
+include = ["agent", "tools", "tools.*", "hermes_cli", "gateway", "gateway.*", "cron", "honcho_integration", "acp_adapter", "keystore", "wallet", "wallet.*"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]

run_agent.py

@@ -368,48 +368,6 @@ _BUDGET_WARNING_RE = re.compile(
 )
 
 
-# Regex to match lone surrogate code points (U+D800..U+DFFF).
-# These are invalid in UTF-8 and cause UnicodeEncodeError when the OpenAI SDK
-# serialises messages to JSON.  Common source: clipboard paste from Google Docs
-# or other rich-text editors on some platforms.
-_SURROGATE_RE = re.compile(r'[\ud800-\udfff]')
-
-
-def _sanitize_surrogates(text: str) -> str:
-    """Replace lone surrogate code points with U+FFFD (replacement character).
-
-    Surrogates are invalid in UTF-8 and will crash ``json.dumps()`` inside the
-    OpenAI SDK.  This is a fast no-op when the text contains no surrogates.
-    """
-    if _SURROGATE_RE.search(text):
-        return _SURROGATE_RE.sub('\ufffd', text)
-    return text
-
-
-def _sanitize_messages_surrogates(messages: list) -> bool:
-    """Sanitize surrogate characters from all string content in a messages list.
-
-    Walks message dicts in-place.  Returns True if any surrogates were found
-    and replaced, False otherwise.
-    """
-    found = False
-    for msg in messages:
-        if not isinstance(msg, dict):
-            continue
-        content = msg.get("content")
-        if isinstance(content, str) and _SURROGATE_RE.search(content):
-            msg["content"] = _SURROGATE_RE.sub('\ufffd', content)
-            found = True
-        elif isinstance(content, list):
-            for part in content:
-                if isinstance(part, dict):
-                    text = part.get("text")
-                    if isinstance(text, str) and _SURROGATE_RE.search(text):
-                        part["text"] = _SURROGATE_RE.sub('\ufffd', text)
-                        found = True
-    return found
-
-
 def _strip_budget_warnings_from_history(messages: list) -> None:
     """Remove budget pressure warnings from tool-result messages in-place.
 
@@ -896,30 +854,16 @@ class AIAgent:
             except Exception as e:
                 raise RuntimeError(f"Failed to initialize OpenAI client: {e}")
         
-        # Provider fallback chain — ordered list of backup providers tried
-        # when the primary is exhausted (rate-limit, overload, connection
-        # failure).  Supports both legacy single-dict ``fallback_model`` and
-        # new list ``fallback_providers`` format.
-        if isinstance(fallback_model, list):
-            self._fallback_chain = [
-                f for f in fallback_model
-                if isinstance(f, dict) and f.get("provider") and f.get("model")
-            ]
-        elif isinstance(fallback_model, dict) and fallback_model.get("provider") and fallback_model.get("model"):
-            self._fallback_chain = [fallback_model]
-        else:
-            self._fallback_chain = []
-        self._fallback_index = 0
+        # Provider fallback — a single backup model/provider tried when the
+        # primary is exhausted (rate-limit, overload, connection failure).
+        # Config shape: {"provider": "openrouter", "model": "anthropic/claude-sonnet-4"}
+        self._fallback_model = fallback_model if isinstance(fallback_model, dict) else None
         self._fallback_activated = False
-        # Legacy attribute kept for backward compat (tests, external callers)
-        self._fallback_model = self._fallback_chain[0] if self._fallback_chain else None
-        if self._fallback_chain and not self.quiet_mode:
-            if len(self._fallback_chain) == 1:
-                fb = self._fallback_chain[0]
-                print(f"🔄 Fallback model: {fb['model']} ({fb['provider']})")
-            else:
-                print(f"🔄 Fallback chain ({len(self._fallback_chain)} providers): " +
-                      " → ".join(f"{f['model']} ({f['provider']})" for f in self._fallback_chain))
+        if self._fallback_model:
+            fb_p = self._fallback_model.get("provider", "")
+            fb_m = self._fallback_model.get("model", "")
+            if fb_p and fb_m and not self.quiet_mode:
+                print(f"🔄 Fallback model: {fb_m} ({fb_p})")
 
         # Get available tools with filtering
         self.tools = get_tool_definitions(
@@ -1098,8 +1042,8 @@ class AIAgent:
                     else:
                         if not hcfg.enabled:
                             logger.debug("Honcho disabled in global config")
-                        elif not (hcfg.api_key or hcfg.base_url):
-                            logger.debug("Honcho enabled but no API key or base URL configured")
+                        elif not hcfg.api_key:
+                            logger.debug("Honcho enabled but no API key configured")
                         else:
                             logger.debug("Honcho enabled but missing API key or disabled in config")
             except Exception as e:
@@ -2306,14 +2250,8 @@ class AIAgent:
     # ── Honcho integration helpers ──
 
     def _honcho_should_activate(self, hcfg) -> bool:
-        """Return True when Honcho should be active.
-
-        Self-hosted Honcho may be configured with a base_url and no API key,
-        so activation should accept either credential style.
-        """
-        if not hcfg or not hcfg.enabled:
-            return False
-        if not (hcfg.api_key or hcfg.base_url):
+        """Return True when remote Honcho should be active."""
+        if not hcfg or not hcfg.enabled or not hcfg.api_key:
             return False
         return True
 
@@ -4332,26 +4270,25 @@ class AIAgent:
     # ── Provider fallback ──────────────────────────────────────────────────
 
     def _try_activate_fallback(self) -> bool:
-        """Switch to the next fallback model/provider in the chain.
+        """Switch to the configured fallback model/provider.
 
-        Called when the current model is failing after retries.  Swaps the
+        Called when the primary model is failing after retries.  Swaps the
         OpenAI client, model slug, and provider in-place so the retry loop
-        can continue with the new backend.  Advances through the chain on
-        each call; returns False when exhausted.
+        can continue with the new backend.  One-shot: returns False if
+        already activated or not configured.
 
         Uses the centralized provider router (resolve_provider_client) for
         auth resolution and client construction — no duplicated provider→key
         mappings.
         """
-        if self._fallback_index >= len(self._fallback_chain):
+        if self._fallback_activated or not self._fallback_model:
             return False
 
-        fb = self._fallback_chain[self._fallback_index]
-        self._fallback_index += 1
+        fb = self._fallback_model
         fb_provider = (fb.get("provider") or "").strip().lower()
         fb_model = (fb.get("model") or "").strip()
         if not fb_provider or not fb_model:
-            return self._try_activate_fallback()  # skip invalid, try next
+            return False
 
         # Use centralized router for client construction.
         # raw_codex=True because the main agent needs direct responses.stream()
@@ -4364,7 +4301,7 @@ class AIAgent:
                 logging.warning(
                     "Fallback to %s failed: provider not configured",
                     fb_provider)
-                return self._try_activate_fallback()  # try next in chain
+                return False
 
             # Determine api_mode from provider / base URL
             fb_api_mode = "chat_completions"
@@ -4439,8 +4376,8 @@ class AIAgent:
             )
             return True
         except Exception as e:
-            logging.error("Failed to activate fallback %s: %s", fb_model, e)
-            return self._try_activate_fallback()  # try next in chain
+            logging.error("Failed to activate fallback model: %s", e)
+            return False
 
     # ── End provider fallback ──────────────────────────────────────────────
 
@@ -4721,10 +4658,9 @@ class AIAgent:
         api_kwargs = {
             "model": self.model,
             "messages": sanitized_messages,
+            "tools": self.tools if self.tools else None,
             "timeout": float(os.getenv("HERMES_API_TIMEOUT", 1800.0)),
         }
-        if self.tools:
-            api_kwargs["tools"] = self.tools
 
         if self.max_tokens is not None:
             api_kwargs.update(self._max_tokens_param(self.max_tokens))
@@ -6023,14 +5959,6 @@ class AIAgent:
         # Installed once, transparent when streams are healthy, prevents crash on write.
         _install_safe_stdio()
 
-        # Sanitize surrogate characters from user input.  Clipboard paste from
-        # rich-text editors (Google Docs, Word, etc.) can inject lone surrogates
-        # that are invalid UTF-8 and crash JSON serialization in the OpenAI SDK.
-        if isinstance(user_message, str):
-            user_message = _sanitize_surrogates(user_message)
-        if isinstance(persist_user_message, str):
-            persist_user_message = _sanitize_surrogates(persist_user_message)
-
         # Store stream callback for _interruptible_api_call to pick up
         self._stream_callback = stream_callback
         self._persist_user_message_idx = None
@@ -6047,7 +5975,6 @@ class AIAgent:
         self._codex_incomplete_retries = 0
         self._last_content_with_tools = None
         self._mute_post_response = False
-        self._surrogate_sanitized = False
         # NOTE: _turns_since_memory and _iters_since_skill are NOT reset here.
         # They are initialized in __init__ and must persist across run_conversation
         # calls so that nudge logic accumulates correctly in CLI mode.
@@ -6544,9 +6471,9 @@ class AIAgent:
                         # Eager fallback: empty/malformed responses are a common
                         # rate-limit symptom.  Switch to fallback immediately
                         # rather than retrying with extended backoff.
-                        if self._fallback_index < len(self._fallback_chain):
+                        if not self._fallback_activated:
                             self._emit_status("⚠️ Empty/malformed response — switching to fallback...")
-                        if self._try_activate_fallback():
+                        if not self._fallback_activated and self._try_activate_fallback():
                             retry_count = 0
                             continue
 
@@ -6883,24 +6810,6 @@ class AIAgent:
                     if self.thinking_callback:
                         self.thinking_callback("")
 
-                    # -----------------------------------------------------------
-                    # Surrogate character recovery.  UnicodeEncodeError happens
-                    # when the messages contain lone surrogates (U+D800..U+DFFF)
-                    # that are invalid UTF-8.  Common source: clipboard paste
-                    # from Google Docs or similar rich-text editors.  We sanitize
-                    # the entire messages list in-place and retry once.
-                    # -----------------------------------------------------------
-                    if isinstance(api_error, UnicodeEncodeError) and not getattr(self, '_surrogate_sanitized', False):
-                        self._surrogate_sanitized = True
-                        if _sanitize_messages_surrogates(messages):
-                            self._vprint(
-                                f"{self.log_prefix}⚠️  Stripped invalid surrogate characters from messages. Retrying...",
-                                force=True,
-                            )
-                            continue
-                        # Surrogates weren't in messages — might be in system
-                        # prompt or prefill.  Fall through to normal error path.
-
                     status_code = getattr(api_error, "status_code", None)
                     if (
                         self.api_mode == "codex_responses"
@@ -6940,10 +6849,8 @@ class AIAgent:
                         print(f"{self.log_prefix}   Auth method: {auth_method}")
                         print(f"{self.log_prefix}   Token prefix: {key[:12]}..." if key and len(key) > 12 else f"{self.log_prefix}   Token: (empty or short)")
                         print(f"{self.log_prefix}   Troubleshooting:")
-                        from hermes_constants import display_hermes_home as _dhh_fn
-                        _dhh = _dhh_fn()
-                        print(f"{self.log_prefix}     • Check ANTHROPIC_TOKEN in {_dhh}/.env for Hermes-managed OAuth/setup tokens")
-                        print(f"{self.log_prefix}     • Check ANTHROPIC_API_KEY in {_dhh}/.env for API keys or legacy token values")
+                        print(f"{self.log_prefix}     • Check ANTHROPIC_TOKEN in ~/.hermes/.env for Hermes-managed OAuth/setup tokens")
+                        print(f"{self.log_prefix}     • Check ANTHROPIC_API_KEY in ~/.hermes/.env for API keys or legacy token values")
                         print(f"{self.log_prefix}     • For API keys: verify at https://console.anthropic.com/settings/keys")
                         print(f"{self.log_prefix}     • For Claude Code: run 'claude /login' to refresh, then retry")
                         print(f"{self.log_prefix}     • Clear stale keys: hermes config set ANTHROPIC_TOKEN \"\"")
@@ -7009,7 +6916,7 @@ class AIAgent:
                         or "usage limit" in error_msg
                         or "quota" in error_msg
                     )
-                    if is_rate_limited and self._fallback_index < len(self._fallback_chain):
+                    if is_rate_limited and not self._fallback_activated:
                         self._emit_status("⚠️ Rate limited — switching to fallback provider...")
                         if self._try_activate_fallback():
                             retry_count = 0
@@ -7171,13 +7078,8 @@ class AIAgent:
                     # 529 (Anthropic overloaded) is also transient.
                     # Also catch local validation errors (ValueError, TypeError) — these
                     # are programming bugs, not transient failures.
-                    # Exclude UnicodeEncodeError — it's a ValueError subclass but is
-                    # handled separately by the surrogate sanitization path above.
                     _RETRYABLE_STATUS_CODES = {413, 429, 529}
-                    is_local_validation_error = (
-                        isinstance(api_error, (ValueError, TypeError))
-                        and not isinstance(api_error, UnicodeEncodeError)
-                    )
+                    is_local_validation_error = isinstance(api_error, (ValueError, TypeError))
                     # Detect generic 400s from Anthropic OAuth (transient server-side failures).
                     # Real invalid_request_error responses include a descriptive message;
                     # transient ones contain only "Error" or are empty. (ref: issue #1608)
@@ -7245,10 +7147,7 @@ class AIAgent:
                             retry_count = 0
                             continue
                         _final_summary = self._summarize_api_error(api_error)
-                        if is_rate_limited:
-                            self._vprint(f"{self.log_prefix}❌ Rate limit persisted after {max_retries} retries. Please try again later.", force=True)
-                        else:
-                            self._vprint(f"{self.log_prefix}❌ Max retries ({max_retries}) exceeded. Giving up.", force=True)
+                        self._vprint(f"{self.log_prefix}❌ Max retries ({max_retries}) exceeded. Giving up.", force=True)
                         self._vprint(f"{self.log_prefix}   💀 Final error: {_final_summary}", force=True)
 
                         # Detect SSE stream-drop pattern (e.g. "Network
@@ -7308,22 +7207,8 @@ class AIAgent:
                             "error": _final_summary,
                         }
 
-                    # For rate limits, respect the Retry-After header if present
-                    _retry_after = None
-                    if is_rate_limited:
-                        _resp_headers = getattr(getattr(api_error, "response", None), "headers", None)
-                        if _resp_headers and hasattr(_resp_headers, "get"):
-                            _ra_raw = _resp_headers.get("retry-after") or _resp_headers.get("Retry-After")
-                            if _ra_raw:
-                                try:
-                                    _retry_after = min(int(_ra_raw), 120)  # Cap at 2 minutes
-                                except (TypeError, ValueError):
-                                    pass
-                    wait_time = _retry_after if _retry_after else min(2 ** retry_count, 60)
-                    if is_rate_limited:
-                        self._emit_status(f"⏱️ Rate limit reached. Waiting {wait_time}s before retry (attempt {retry_count + 1}/{max_retries})...")
-                    else:
-                        self._emit_status(f"⏳ Retrying in {wait_time}s (attempt {retry_count}/{max_retries})...")
+                    wait_time = min(2 ** retry_count, 60)  # Exponential backoff: 2s, 4s, 8s, 16s, 32s, 60s, 60s
+                    self._emit_status(f"⏳ Retrying in {wait_time}s (attempt {retry_count}/{max_retries})...")
                     logger.warning(
                         "Retrying API call in %ss (attempt %s/%s) %s error=%s",
                         wait_time,

skills/productivity/google-workspace/SKILL.md

@@ -4,11 +4,6 @@ description: Gmail, Calendar, Drive, Contacts, Sheets, and Docs integration via
 version: 1.0.0
 author: Nous Research
 license: MIT
-required_credential_files:
-  - path: google_token.json
-    description: Google OAuth2 token (created by setup script)
-  - path: google_client_secret.json
-    description: Google OAuth2 client credentials (downloaded from Google Cloud Console)
 metadata:
   hermes:
     tags: [Google, Gmail, Calendar, Drive, Sheets, Docs, Contacts, Email, OAuth]

skills/research/duckduckgo-search/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: duckduckgo-search
-description: Free web search via DuckDuckGo — text, news, images, videos. No API key needed. Prefer the `ddgs` CLI when installed; use the Python DDGS library only after verifying that `ddgs` is available in the current runtime.
-version: 1.3.0
+description: Free web search via DuckDuckGo — text, news, images, videos. No API key needed. Use the Python DDGS library or CLI to search, then web_extract for full content.
+version: 1.2.0
 author: gamedevCloudy
 license: MIT
 metadata:
@@ -9,96 +9,26 @@ metadata:
     tags: [search, duckduckgo, web-search, free, fallback]
     related_skills: [arxiv]
     fallback_for_toolsets: [web]
+prerequisites:
+  commands: [ddgs]
 ---
 
 # DuckDuckGo Search
 
 Free web search using DuckDuckGo. **No API key required.**
 
-Preferred when `web_search` is unavailable or unsuitable (for example when `FIRECRAWL_API_KEY` is not set). Can also be used as a standalone search path when DuckDuckGo results are specifically desired.
+Preferred when `web_search` tool is unavailable or unsuitable (no `FIRECRAWL_API_KEY` set). Can also be used as a standalone search tool.
 
-## Detection Flow
-
-Check what is actually available before choosing an approach:
+## Setup
 
 ```bash
-# Check CLI availability
-command -v ddgs >/dev/null && echo "DDGS_CLI=installed" || echo "DDGS_CLI=missing"
-```
-
-Decision tree:
-1. If `ddgs` CLI is installed, prefer `terminal` + `ddgs`
-2. If `ddgs` CLI is missing, do not assume `execute_code` can import `ddgs`
-3. If the user wants DuckDuckGo specifically, install `ddgs` first in the relevant environment
-4. Otherwise fall back to built-in web/browser tools
-
-Important runtime note:
-- Terminal and `execute_code` are separate runtimes
-- A successful shell install does not guarantee `execute_code` can import `ddgs`
-- Never assume third-party Python packages are preinstalled inside `execute_code`
-
-## Installation
-
-Install `ddgs` only when DuckDuckGo search is specifically needed and the runtime does not already provide it.
-
-```bash
-# Python package + CLI entrypoint
+# Install the ddgs package (one-time)
 pip install ddgs
-
-# Verify CLI
-ddgs --help
 ```
 
-If a workflow depends on Python imports, verify that same runtime can import `ddgs` before using `from ddgs import DDGS`.
+## Python API (Primary)
 
-## Method 1: CLI Search (Preferred)
-
-Use the `ddgs` command via `terminal` when it exists. This is the preferred path because it avoids assuming the `execute_code` sandbox has the `ddgs` Python package installed.
-
-```bash
-# Text search
-ddgs text -k "python async programming" -m 5
-
-# News search
-ddgs news -k "artificial intelligence" -m 5
-
-# Image search
-ddgs images -k "landscape photography" -m 10
-
-# Video search
-ddgs videos -k "python tutorial" -m 5
-
-# With region filter
-ddgs text -k "best restaurants" -m 5 -r us-en
-
-# Recent results only (d=day, w=week, m=month, y=year)
-ddgs text -k "latest AI news" -m 5 -t w
-
-# JSON output for parsing
-ddgs text -k "fastapi tutorial" -m 5 -o json
-```
-
-### CLI Flags
-
-| Flag | Description | Example |
-|------|-------------|---------|
-| `-k` | Keywords (query) — **required** | `-k "search terms"` |
-| `-m` | Max results | `-m 5` |
-| `-r` | Region | `-r us-en` |
-| `-t` | Time limit | `-t w` (week) |
-| `-s` | Safe search | `-s off` |
-| `-o` | Output format | `-o json` |
-
-## Method 2: Python API (Only After Verification)
-
-Use the `DDGS` class in `execute_code` or another Python runtime only after verifying that `ddgs` is installed there. Do not assume `execute_code` includes third-party packages by default.
-
-Safe wording:
-- "Use `execute_code` with `ddgs` after installing or verifying the package if needed"
-
-Avoid saying:
-- "`execute_code` includes `ddgs`"
-- "DuckDuckGo search works by default in `execute_code`"
+Use the `DDGS` class in `execute_code` for structured results with typed fields.
 
 **Important:** `max_results` must always be passed as a **keyword argument** — positional usage raises an error on all methods.
 
@@ -146,7 +76,7 @@ from ddgs import DDGS
 with DDGS() as ddgs:
     for r in ddgs.images("semiconductor chip", max_results=5):
         print(r["title"])
-        print(r["image"])
+        print(r["image"])       # direct image URL
         print(r.get("thumbnail", ""))
         print(r.get("source", ""))
         print()
@@ -164,9 +94,9 @@ from ddgs import DDGS
 with DDGS() as ddgs:
     for r in ddgs.videos("FastAPI tutorial", max_results=5):
         print(r["title"])
-        print(r.get("content", ""))
-        print(r.get("duration", ""))
-        print(r.get("provider", ""))
+        print(r.get("content", ""))       # video URL
+        print(r.get("duration", ""))       # e.g. "26:03"
+        print(r.get("provider", ""))       # YouTube, etc.
         print(r.get("published", ""))
         print()
 ```
@@ -182,17 +112,50 @@ Returns: `title`, `content`, `description`, `duration`, `provider`, `published`,
 | `images()` | Visuals, diagrams | title, image, thumbnail, url |
 | `videos()` | Tutorials, demos | title, content, duration, provider |
 
-## Workflow: Search then Extract
+## CLI (Alternative)
 
-DuckDuckGo returns titles, URLs, and snippets — not full page content. To get full page content, search first and then extract the most relevant URL with `web_extract`, browser tools, or curl.
-
-CLI example:
+Use the `ddgs` command via terminal when you don't need structured field access.
 
 ```bash
-ddgs text -k "fastapi deployment guide" -m 3 -o json
+# Text search
+ddgs text -k "python async programming" -m 5
+
+# News search
+ddgs news -k "artificial intelligence" -m 5
+
+# Image search
+ddgs images -k "landscape photography" -m 10
+
+# Video search
+ddgs videos -k "python tutorial" -m 5
+
+# With region filter
+ddgs text -k "best restaurants" -m 5 -r us-en
+
+# Recent results only (d=day, w=week, m=month, y=year)
+ddgs text -k "latest AI news" -m 5 -t w
+
+# JSON output for parsing
+ddgs text -k "fastapi tutorial" -m 5 -o json
 ```
 
-Python example, only after verifying `ddgs` is installed in that runtime:
+### CLI Flags
+
+| Flag | Description | Example |
+|------|-------------|---------|
+| `-k` | Keywords (query) — **required** | `-k "search terms"` |
+| `-m` | Max results | `-m 5` |
+| `-r` | Region | `-r us-en` |
+| `-t` | Time limit | `-t w` (week) |
+| `-s` | Safe search | `-s off` |
+| `-o` | Output format | `-o json` |
+
+## Workflow: Search then Extract
+
+DuckDuckGo returns titles, URLs, and snippets — not full page content. To get full content, follow up with `web_extract`:
+
+1. **Search** with ddgs to find relevant URLs
+2. **Extract** content using the `web_extract` tool (if available) or curl
 
 ```python
 from ddgs import DDGS
@@ -201,37 +164,25 @@ with DDGS() as ddgs:
     results = list(ddgs.text("fastapi deployment guide", max_results=3))
     for r in results:
         print(r["title"], "->", r["href"])
-```
 
-Then extract the best URL with `web_extract` or another content-retrieval tool.
+# Then use web_extract tool on the best URL
+```
 
 ## Limitations
 
 - **Rate limiting**: DuckDuckGo may throttle after many rapid requests. Add a short delay between searches if needed.
-- **No content extraction**: `ddgs` returns snippets, not full page content. Use `web_extract`, browser tools, or curl for the full article/page.
+- **No content extraction**: ddgs returns snippets, not full page content. Use `web_extract` or curl for that.
 - **Results quality**: Generally good but less configurable than Firecrawl's search.
 - **Availability**: DuckDuckGo may block requests from some cloud IPs. If searches return empty, try different keywords or wait a few seconds.
-- **Field variability**: Return fields may vary between results or `ddgs` versions. Use `.get()` for optional fields to avoid `KeyError`.
-- **Separate runtimes**: A successful `ddgs` install in terminal does not automatically mean `execute_code` can import it.
-
-## Troubleshooting
-
-| Problem | Likely Cause | What To Do |
-|---------|--------------|------------|
-| `ddgs: command not found` | CLI not installed in the shell environment | Install `ddgs`, or use built-in web/browser tools instead |
-| `ModuleNotFoundError: No module named 'ddgs'` | Python runtime does not have the package installed | Do not use Python DDGS there until that runtime is prepared |
-| Search returns nothing | Temporary rate limiting or poor query | Wait a few seconds, retry, or adjust the query |
-| CLI works but `execute_code` import fails | Terminal and `execute_code` are different runtimes | Keep using CLI, or separately prepare the Python runtime |
+- **Field variability**: Return fields may vary between results or ddgs versions. Use `.get()` for optional fields to avoid KeyError.
 
 ## Pitfalls
 
 - **`max_results` is keyword-only**: `ddgs.text("query", 5)` raises an error. Use `ddgs.text("query", max_results=5)`.
-- **Do not assume the CLI exists**: Check `command -v ddgs` before using it.
-- **Do not assume `execute_code` can import `ddgs`**: `from ddgs import DDGS` may fail with `ModuleNotFoundError` unless that runtime was prepared separately.
-- **Package name**: The package is `ddgs` (previously `duckduckgo-search`). Install with `pip install ddgs`.
 - **Don't confuse `-k` and `-m`** (CLI): `-k` is for keywords, `-m` is for max results count.
-- **Empty results**: If `ddgs` returns nothing, it may be rate-limited. Wait a few seconds and retry.
+- **Package name**: The package is `ddgs` (was previously `duckduckgo-search`). Install with `pip install ddgs`.
+- **Empty results**: If ddgs returns nothing, it may be rate-limited. Wait a few seconds and retry.
 
 ## Validated With
 
-Validated examples against `ddgs==9.11.2` semantics. Skill guidance now treats CLI availability and Python import availability as separate concerns so the documented workflow matches actual runtime behavior.
+Smoke-tested with `ddgs==9.11.2` on Python 3.13. All four methods (text, news, images, videos) confirmed working with keyword `max_results`.

tests/acp/test_entry.py

@@ -1,20 +0,0 @@
-"""Tests for acp_adapter.entry startup wiring."""
-
-import acp
-
-from acp_adapter import entry
-
-
-def test_main_enables_unstable_protocol(monkeypatch):
-    calls = {}
-
-    async def fake_run_agent(agent, **kwargs):
-        calls["kwargs"] = kwargs
-
-    monkeypatch.setattr(entry, "_setup_logging", lambda: None)
-    monkeypatch.setattr(entry, "_load_env", lambda: None)
-    monkeypatch.setattr(acp, "run_agent", fake_run_agent)
-
-    entry.main()
-
-    assert calls["kwargs"]["use_unstable_protocol"] is True

tests/acp/test_server.py

@@ -8,7 +8,6 @@ from unittest.mock import MagicMock, AsyncMock, patch
 import pytest
 
 import acp
-from acp.agent.router import build_agent_router
 from acp.schema import (
     AgentCapabilities,
     AuthenticateResponse,
@@ -19,8 +18,6 @@ from acp.schema import (
     NewSessionResponse,
     PromptResponse,
     ResumeSessionResponse,
-    SetSessionConfigOptionResponse,
-    SetSessionModeResponse,
     SessionInfo,
     TextContentBlock,
     Usage,
@@ -171,74 +168,6 @@ class TestListAndFork:
         assert fork_resp.session_id != new_resp.session_id
 
 
-# ---------------------------------------------------------------------------
-# session configuration / model routing
-# ---------------------------------------------------------------------------
-
-
-class TestSessionConfiguration:
-    @pytest.mark.asyncio
-    async def test_set_session_mode_returns_response(self, agent):
-        new_resp = await agent.new_session(cwd="/tmp")
-        resp = await agent.set_session_mode(mode_id="chat", session_id=new_resp.session_id)
-        state = agent.session_manager.get_session(new_resp.session_id)
-
-        assert isinstance(resp, SetSessionModeResponse)
-        assert getattr(state, "mode", None) == "chat"
-
-    @pytest.mark.asyncio
-    async def test_set_config_option_returns_response(self, agent):
-        new_resp = await agent.new_session(cwd="/tmp")
-        resp = await agent.set_config_option(
-            config_id="approval_mode",
-            session_id=new_resp.session_id,
-            value="auto",
-        )
-        state = agent.session_manager.get_session(new_resp.session_id)
-
-        assert isinstance(resp, SetSessionConfigOptionResponse)
-        assert getattr(state, "config_options", {}) == {"approval_mode": "auto"}
-        assert resp.config_options == []
-
-    @pytest.mark.asyncio
-    async def test_router_accepts_stable_session_config_methods(self, agent):
-        new_resp = await agent.new_session(cwd="/tmp")
-        router = build_agent_router(agent)
-
-        mode_result = await router(
-            "session/set_mode",
-            {"modeId": "chat", "sessionId": new_resp.session_id},
-            False,
-        )
-        config_result = await router(
-            "session/set_config_option",
-            {
-                "configId": "approval_mode",
-                "sessionId": new_resp.session_id,
-                "value": "auto",
-            },
-            False,
-        )
-
-        assert mode_result == {}
-        assert config_result == {"configOptions": []}
-
-    @pytest.mark.asyncio
-    async def test_router_accepts_unstable_model_switch_when_enabled(self, agent):
-        new_resp = await agent.new_session(cwd="/tmp")
-        router = build_agent_router(agent, use_unstable_protocol=True)
-
-        result = await router(
-            "session/set_model",
-            {"modelId": "gpt-5.4", "sessionId": new_resp.session_id},
-            False,
-        )
-        state = agent.session_manager.get_session(new_resp.session_id)
-
-        assert result == {}
-        assert state.model == "gpt-5.4"
-
-
 # ---------------------------------------------------------------------------
 # prompt
 # ---------------------------------------------------------------------------

tests/agent/test_external_skills.py

@@ -1,157 +0,0 @@
-"""Tests for external skill directories (skills.external_dirs config)."""
-
-import json
-import os
-from pathlib import Path
-from unittest.mock import patch
-
-import pytest
-
-
-@pytest.fixture
-def external_skills_dir(tmp_path):
-    """Create a temp dir with a sample external skill."""
-    ext_dir = tmp_path / "external-skills"
-    skill_dir = ext_dir / "my-external-skill"
-    skill_dir.mkdir(parents=True)
-    (skill_dir / "SKILL.md").write_text(
-        "---\nname: my-external-skill\ndescription: A skill from an external directory\n---\n\n# My External Skill\n\nDo external things.\n"
-    )
-    return ext_dir
-
-
-@pytest.fixture
-def hermes_home(tmp_path):
-    """Create a minimal HERMES_HOME with config."""
-    home = tmp_path / ".hermes"
-    home.mkdir()
-    (home / "skills").mkdir()
-    return home
-
-
-class TestGetExternalSkillsDirs:
-    def test_empty_config(self, hermes_home):
-        (hermes_home / "config.yaml").write_text("skills:\n  external_dirs: []\n")
-        with patch.dict(os.environ, {"HERMES_HOME": str(hermes_home)}):
-            from agent.skill_utils import get_external_skills_dirs
-            result = get_external_skills_dirs()
-        assert result == []
-
-    def test_nonexistent_dir_skipped(self, hermes_home):
-        (hermes_home / "config.yaml").write_text(
-            "skills:\n  external_dirs:\n    - /nonexistent/path\n"
-        )
-        with patch.dict(os.environ, {"HERMES_HOME": str(hermes_home)}):
-            from agent.skill_utils import get_external_skills_dirs
-            result = get_external_skills_dirs()
-        assert result == []
-
-    def test_valid_dir_returned(self, hermes_home, external_skills_dir):
-        (hermes_home / "config.yaml").write_text(
-            f"skills:\n  external_dirs:\n    - {external_skills_dir}\n"
-        )
-        with patch.dict(os.environ, {"HERMES_HOME": str(hermes_home)}):
-            from agent.skill_utils import get_external_skills_dirs
-            result = get_external_skills_dirs()
-        assert len(result) == 1
-        assert result[0] == external_skills_dir.resolve()
-
-    def test_duplicate_dirs_deduplicated(self, hermes_home, external_skills_dir):
-        (hermes_home / "config.yaml").write_text(
-            f"skills:\n  external_dirs:\n    - {external_skills_dir}\n    - {external_skills_dir}\n"
-        )
-        with patch.dict(os.environ, {"HERMES_HOME": str(hermes_home)}):
-            from agent.skill_utils import get_external_skills_dirs
-            result = get_external_skills_dirs()
-        assert len(result) == 1
-
-    def test_local_skills_dir_excluded(self, hermes_home):
-        local_skills = hermes_home / "skills"
-        (hermes_home / "config.yaml").write_text(
-            f"skills:\n  external_dirs:\n    - {local_skills}\n"
-        )
-        with patch.dict(os.environ, {"HERMES_HOME": str(hermes_home)}):
-            from agent.skill_utils import get_external_skills_dirs
-            result = get_external_skills_dirs()
-        assert result == []
-
-    def test_no_config_file(self, hermes_home):
-        # No config.yaml at all
-        with patch.dict(os.environ, {"HERMES_HOME": str(hermes_home)}):
-            from agent.skill_utils import get_external_skills_dirs
-            result = get_external_skills_dirs()
-        assert result == []
-
-    def test_string_value_converted_to_list(self, hermes_home, external_skills_dir):
-        (hermes_home / "config.yaml").write_text(
-            f"skills:\n  external_dirs: {external_skills_dir}\n"
-        )
-        with patch.dict(os.environ, {"HERMES_HOME": str(hermes_home)}):
-            from agent.skill_utils import get_external_skills_dirs
-            result = get_external_skills_dirs()
-        assert len(result) == 1
-
-
-class TestGetAllSkillsDirs:
-    def test_local_always_first(self, hermes_home, external_skills_dir):
-        (hermes_home / "config.yaml").write_text(
-            f"skills:\n  external_dirs:\n    - {external_skills_dir}\n"
-        )
-        with patch.dict(os.environ, {"HERMES_HOME": str(hermes_home)}):
-            from agent.skill_utils import get_all_skills_dirs
-            result = get_all_skills_dirs()
-        assert result[0] == hermes_home / "skills"
-        assert result[1] == external_skills_dir.resolve()
-
-
-class TestExternalSkillsInFindAll:
-    def test_external_skills_found(self, hermes_home, external_skills_dir):
-        (hermes_home / "config.yaml").write_text(
-            f"skills:\n  external_dirs:\n    - {external_skills_dir}\n"
-        )
-        local_skills = hermes_home / "skills"
-        with (
-            patch.dict(os.environ, {"HERMES_HOME": str(hermes_home)}),
-            patch("tools.skills_tool.SKILLS_DIR", local_skills),
-        ):
-            from tools.skills_tool import _find_all_skills
-            skills = _find_all_skills()
-        names = [s["name"] for s in skills]
-        assert "my-external-skill" in names
-
-    def test_local_takes_precedence(self, hermes_home, external_skills_dir):
-        """If the same skill name exists locally and externally, local wins."""
-        local_skills = hermes_home / "skills"
-        local_skill = local_skills / "my-external-skill"
-        local_skill.mkdir(parents=True)
-        (local_skill / "SKILL.md").write_text(
-            "---\nname: my-external-skill\ndescription: Local version\n---\n\nLocal.\n"
-        )
-        (hermes_home / "config.yaml").write_text(
-            f"skills:\n  external_dirs:\n    - {external_skills_dir}\n"
-        )
-        with (
-            patch.dict(os.environ, {"HERMES_HOME": str(hermes_home)}),
-            patch("tools.skills_tool.SKILLS_DIR", local_skills),
-        ):
-            from tools.skills_tool import _find_all_skills
-            skills = _find_all_skills()
-        matching = [s for s in skills if s["name"] == "my-external-skill"]
-        assert len(matching) == 1
-        assert matching[0]["description"] == "Local version"
-
-
-class TestExternalSkillView:
-    def test_skill_view_finds_external(self, hermes_home, external_skills_dir):
-        (hermes_home / "config.yaml").write_text(
-            f"skills:\n  external_dirs:\n    - {external_skills_dir}\n"
-        )
-        local_skills = hermes_home / "skills"
-        with (
-            patch.dict(os.environ, {"HERMES_HOME": str(hermes_home)}),
-            patch("tools.skills_tool.SKILLS_DIR", local_skills),
-        ):
-            from tools.skills_tool import skill_view
-            result = json.loads(skill_view("my-external-skill"))
-        assert result["success"] is True
-        assert "external things" in result["content"]

tests/agent/test_prompt_builder.py

@@ -5,8 +5,6 @@ import importlib
 import logging
 import sys
 
-import pytest
-
 from agent.prompt_builder import (
     _scan_context_content,
     _truncate_content,
@@ -196,7 +194,7 @@ class TestParseSkillFile:
         )
         from unittest.mock import patch
 
-        with patch("agent.skill_utils.sys") as mock_sys:
+        with patch("tools.skills_tool.sys") as mock_sys:
             mock_sys.platform = "linux"
             is_compat, _, _ = _parse_skill_file(skill_file)
         assert is_compat is False
@@ -236,6 +234,9 @@ class TestPromptBuilderImports:
 # =========================================================================
 
 
+import pytest
+
+
 class TestBuildSkillsSystemPrompt:
     @pytest.fixture(autouse=True)
     def _clear_skills_cache(self):
@@ -295,7 +296,7 @@ class TestBuildSkillsSystemPrompt:
 
         from unittest.mock import patch
 
-        with patch("agent.skill_utils.sys") as mock_sys:
+        with patch("tools.skills_tool.sys") as mock_sys:
             mock_sys.platform = "linux"
             result = build_skills_system_prompt()
 
@@ -573,10 +574,6 @@ class TestBuildContextFilesPrompt:
         result = build_context_files_prompt(cwd=str(tmp_path))
         assert "Lowercase claude rules" in result
 
-    @pytest.mark.skipif(
-        sys.platform == "darwin",
-        reason="APFS default volume is case-insensitive; CLAUDE.md and claude.md alias the same path",
-    )
     def test_claude_md_uppercase_takes_priority(self, tmp_path):
         (tmp_path / "CLAUDE.md").write_text("From uppercase.")
         (tmp_path / "claude.md").write_text("From lowercase.")

tests/agent/test_skill_commands.py

@@ -246,10 +246,20 @@ Generate some audio.
     def test_preserves_remaining_remote_setup_warning(self, tmp_path, monkeypatch):
         monkeypatch.setenv("TERMINAL_ENV", "ssh")
         monkeypatch.delenv("TENOR_API_KEY", raising=False)
+
+        def fake_secret_callback(var_name, prompt, metadata=None):
+            os.environ[var_name] = "stored-in-test"
+            return {
+                "success": True,
+                "stored_as": var_name,
+                "validated": False,
+                "skipped": False,
+            }
+
         monkeypatch.setattr(
             skills_tool_module,
             "_secret_capture_callback",
-            None,
+            fake_secret_callback,
             raising=False,
         )
 

tests/cron/test_scheduler.py

@@ -167,32 +167,6 @@ class TestDeliverResultWrapping:
         sent_content = send_mock.call_args.kwargs.get("content") or send_mock.call_args[0][-1]
         assert "Cronjob Response: abc-123" in sent_content
 
-    def test_delivery_skips_wrapping_when_config_disabled(self):
-        """When cron.wrap_response is false, deliver raw content without header/footer."""
-        from gateway.config import Platform
-
-        pconfig = MagicMock()
-        pconfig.enabled = True
-        mock_cfg = MagicMock()
-        mock_cfg.platforms = {Platform.TELEGRAM: pconfig}
-
-        with patch("gateway.config.load_gateway_config", return_value=mock_cfg), \
-             patch("tools.send_message_tool._send_to_platform", new=AsyncMock(return_value={"success": True})) as send_mock, \
-             patch("cron.scheduler.load_config", return_value={"cron": {"wrap_response": False}}):
-            job = {
-                "id": "test-job",
-                "name": "daily-report",
-                "deliver": "origin",
-                "origin": {"platform": "telegram", "chat_id": "123"},
-            }
-            _deliver_result(job, "Clean output only.")
-
-        send_mock.assert_called_once()
-        sent_content = send_mock.call_args.kwargs.get("content") or send_mock.call_args[0][-1]
-        assert sent_content == "Clean output only."
-        assert "Cronjob Response" not in sent_content
-        assert "The agent cannot see" not in sent_content
-
     def test_no_mirror_to_session_call(self):
         """Cron deliveries should NOT mirror into the gateway session."""
         from gateway.config import Platform

tests/cron/test_script_gate.py

@@ -1,429 +0,0 @@
-"""Tests for the cron job script gate feature.
-
-The script gate allows cron jobs to run an optional bash script before waking
-the agent. The script's last stdout line is parsed as JSON:
-  - {"wakeAgent": false}         → skip the agent entirely
-  - {"wakeAgent": true}          → proceed normally
-  - {"wakeAgent": true, "data":…} → prepend data to the prompt
-  - errors / invalid JSON        → proceed normally (don't block)
-"""
-
-import json
-import subprocess
-import sys
-from pathlib import Path
-from unittest.mock import MagicMock, patch
-
-import pytest
-
-# Ensure project root is importable
-sys.path.insert(0, str(Path(__file__).resolve().parent.parent.parent))
-
-from cron.scheduler import run_job
-
-
-def _make_job(script=None, prompt="Test prompt", job_id="test123", name="test-job"):
-    """Build a minimal job dict for testing."""
-    job = {
-        "id": job_id,
-        "name": name,
-        "prompt": prompt,
-        "schedule_display": "every 5m",
-        "enabled": True,
-        "state": "scheduled",
-        "skills": [],
-    }
-    if script is not None:
-        job["script"] = script
-    return job
-
-
-# We need to mock out the heavy agent machinery so tests stay fast.
-# The script gate runs BEFORE the agent is created, so we can detect
-# whether the agent was created at all.
-
-_AGENT_RUN_SENTINEL = "agent-ran-ok"
-
-
-class _FakeAgent:
-    """Lightweight stand-in for AIAgent."""
-
-    def __init__(self, **kwargs):
-        self.kwargs = kwargs
-
-    def run_conversation(self, prompt):
-        return {"final_response": _AGENT_RUN_SENTINEL}
-
-
-def _patch_agent():
-    """Return a context manager that replaces AIAgent with _FakeAgent."""
-    return patch("cron.scheduler.AIAgent", _FakeAgent)
-
-
-def _patch_deps():
-    """Patch all heavy imports that run_job pulls in so tests don't need real config."""
-    # SessionDB
-    mock_session_db = MagicMock()
-    mock_session_db.return_value = MagicMock()
-
-    patches = [
-        _patch_agent(),
-        patch("cron.scheduler.SessionDB", mock_session_db, create=True),
-        # dotenv
-        patch("cron.scheduler.load_dotenv", create=True),
-        # config
-        patch("cron.scheduler.resolve_runtime_provider", return_value={
-            "api_key": "fake", "base_url": None, "provider": None,
-            "api_mode": None, "command": None, "args": [],
-        }, create=True),
-        patch("cron.scheduler.resolve_turn_route", return_value={
-            "model": "test-model",
-            "runtime": {
-                "api_key": "fake", "base_url": None, "provider": None,
-                "api_mode": None, "command": None, "args": [],
-            },
-        }, create=True),
-    ]
-    return patches
-
-
-def _run_with_patches(job):
-    """Run a job with all heavy deps mocked out, return the 4-tuple result."""
-    # We'll mock at a higher level: just mock the parts after the script gate
-    # Since there are many transitive imports, let's mock run_job's internals
-    # by monkeypatching the AIAgent and other imports inside run_job.
-
-    # Simpler approach: directly test the script gate logic by extracting it,
-    # or mock at the subprocess level and let the real function flow.
-    # Actually let's just mock the AIAgent import inside run_job.
-
-    with patch("run_agent.AIAgent", _FakeAgent):
-        with patch("cron.scheduler._hermes_home", Path("/tmp/hermes-test")):
-            # Mock the heavy imports that happen inside run_job's try block
-            with patch.dict("os.environ", {
-                "HERMES_MODEL": "test-model",
-            }):
-                with patch("cron.scheduler._build_job_prompt") as mock_build:
-                    # Let _build_job_prompt return the raw prompt so we can
-                    # inspect what gets modified by the script gate.
-                    mock_build.side_effect = lambda j: j.get("prompt", "")
-
-                    # We need to handle the internal imports in run_job
-                    # The cleanest approach: mock the entire agent creation path
-                    mock_agent_instance = MagicMock()
-                    mock_agent_instance.run_conversation.return_value = {
-                        "final_response": _AGENT_RUN_SENTINEL
-                    }
-
-                    # Patch all the things run_job imports internally
-                    with patch("cron.scheduler.AIAgent", return_value=mock_agent_instance, create=True):
-                        try:
-                            result = run_job(job)
-                        except Exception:
-                            # If internal imports fail, the script gate still
-                            # should have run. For wakeAgent=false tests the
-                            # early return happens before any agent code.
-                            raise
-                    return result, mock_agent_instance
-
-
-# ---------------------------------------------------------------------------
-# Actual tests
-# ---------------------------------------------------------------------------
-
-
-class TestScriptGateSkipsAgent:
-    """Script returning wakeAgent=false should skip the agent entirely."""
-
-    def test_wake_agent_false_returns_early(self):
-        job = _make_job(script='echo \'{"wakeAgent": false}\'')
-        # The script gate returns before AIAgent is even imported,
-        # so we only need minimal mocking.
-        with patch("cron.scheduler._build_job_prompt", side_effect=lambda j: j.get("prompt", "")):
-            # Mock SessionDB to avoid real DB
-            with patch("cron.scheduler.SessionDB", create=True):
-                success, output, response, error = run_job(job)
-
-        assert success is True
-        assert "Script gate: agent skipped" in response
-        assert error is None
-        assert "Script Gate" in output
-
-    def test_wake_agent_false_with_extra_stdout(self):
-        """Script may print other lines; only last non-empty counts."""
-        job = _make_job(script='echo "checking..."\necho ""\necho \'{"wakeAgent": false}\'')
-        with patch("cron.scheduler._build_job_prompt", side_effect=lambda j: j.get("prompt", "")):
-            with patch("cron.scheduler.SessionDB", create=True):
-                success, output, response, error = run_job(job)
-
-        assert success is True
-        assert "Script gate: agent skipped" in response
-
-
-class TestScriptGateProceeds:
-    """Script returning wakeAgent=true should let the agent run."""
-
-    def test_wake_agent_true_runs_agent(self):
-        job = _make_job(script='echo \'{"wakeAgent": true}\'')
-        try:
-            result, mock_agent = _run_with_patches(job)
-            success, output, response, error = result
-            # Agent should have been called
-            mock_agent.run_conversation.assert_called_once()
-            assert success is True
-        except Exception:
-            # If import fails due to missing deps, that's OK — the key thing
-            # is that the script gate didn't return early. We verify by
-            # checking it doesn't return the skip message.
-            pass
-
-
-class TestScriptGateDataPrepend:
-    """Script returning wakeAgent=true with data should prepend to prompt."""
-
-    def test_data_prepended_to_prompt(self):
-        data = {"changed_files": ["a.py", "b.py"], "count": 2}
-        script = f'echo \'{{"wakeAgent": true, "data": {json.dumps(data)}}}\''
-        job = _make_job(script=script, prompt="Analyze changes")
-
-        with patch("cron.scheduler._build_job_prompt", side_effect=lambda j: j.get("prompt", "")):
-            with patch("cron.scheduler.SessionDB", create=True):
-                # Mock the AIAgent so we can capture the prompt passed to it
-                captured_prompts = []
-
-                class CapturingAgent:
-                    def __init__(self, **kwargs):
-                        pass
-                    def run_conversation(self, prompt):
-                        captured_prompts.append(prompt)
-                        return {"final_response": "done"}
-
-                # We need to mock all the internal imports of run_job
-                import importlib
-                with patch("dotenv.load_dotenv", create=True):
-                    with patch("builtins.__import__", wraps=__builtins__.__import__ if hasattr(__builtins__, '__import__') else __import__):
-                        # Actually, let's use a more targeted approach
-                        pass
-
-        # Better approach: test the script gate logic directly with subprocess
-        # and verify the prompt transformation
-        script_code = f'echo \'{{"wakeAgent": true, "data": {json.dumps(data)}}}\''
-        result = subprocess.run(
-            ["bash", "-c", script_code],
-            capture_output=True, text=True, timeout=10,
-        )
-        stdout_lines = [l for l in result.stdout.splitlines() if l.strip()]
-        last_line = stdout_lines[-1].strip()
-        gate = json.loads(last_line)
-
-        assert gate["wakeAgent"] is True
-        assert gate["data"] == data
-
-        # Now verify the prompt transformation logic
-        prompt = "Analyze changes"
-        gate_data = gate.get("data")
-        if gate_data is not None:
-            prompt = f"Script pre-check data:\n{json.dumps(gate_data)}\n\n{prompt}"
-
-        assert prompt.startswith("Script pre-check data:")
-        assert '"changed_files"' in prompt
-        assert prompt.endswith("Analyze changes")
-
-
-class TestScriptGateTimeout:
-    """Script timing out should not block — agent proceeds normally."""
-
-    def test_timeout_proceeds(self):
-        # Use a script that sleeps longer than the timeout
-        job = _make_job(script="sleep 60")
-
-        # Mock subprocess.run to raise TimeoutExpired
-        with patch("cron.scheduler._build_job_prompt", side_effect=lambda j: j.get("prompt", "")):
-            with patch("cron.scheduler.SessionDB", create=True):
-                with patch("cron.scheduler.subprocess.run",
-                           side_effect=subprocess.TimeoutExpired(cmd="bash", timeout=30)):
-                    # The function should proceed past the script gate.
-                    # It will fail on the agent imports, but NOT on the script gate.
-                    try:
-                        result = run_job(job)
-                        # If we get here, check it wasn't a script-gate skip
-                        success, output, response, error = result
-                        assert "Script gate: agent skipped" not in response
-                    except Exception:
-                        # Expected: internal imports may fail in test env.
-                        # The important thing is TimeoutExpired didn't propagate.
-                        pass
-
-
-class TestScriptGateInvalidJSON:
-    """Script with non-JSON output should not block — agent proceeds."""
-
-    def test_invalid_json_proceeds(self):
-        job = _make_job(script='echo "this is not json"')
-
-        with patch("cron.scheduler._build_job_prompt", side_effect=lambda j: j.get("prompt", "")):
-            with patch("cron.scheduler.SessionDB", create=True):
-                try:
-                    result = run_job(job)
-                    success, output, response, error = result
-                    assert "Script gate: agent skipped" not in response
-                except Exception:
-                    # Agent creation may fail in test env, but script gate
-                    # should not have blocked.
-                    pass
-
-    def test_empty_stdout_proceeds(self):
-        job = _make_job(script='true')  # produces no output
-
-        with patch("cron.scheduler._build_job_prompt", side_effect=lambda j: j.get("prompt", "")):
-            with patch("cron.scheduler.SessionDB", create=True):
-                try:
-                    result = run_job(job)
-                    success, output, response, error = result
-                    assert "Script gate: agent skipped" not in response
-                except Exception:
-                    pass
-
-
-class TestNoScriptField:
-    """Jobs without a script field should behave normally."""
-
-    def test_no_script_normal(self):
-        job = _make_job()  # no script
-        assert "script" not in job
-
-        try:
-            result, mock_agent = _run_with_patches(job)
-            success, output, response, error = result
-            mock_agent.run_conversation.assert_called_once()
-        except Exception:
-            pass
-
-    def test_none_script_normal(self):
-        job = _make_job(script=None)
-        # script=None should be treated same as missing
-        assert job.get("script") is None
-
-        try:
-            result, mock_agent = _run_with_patches(job)
-            success, output, response, error = result
-            mock_agent.run_conversation.assert_called_once()
-        except Exception:
-            pass
-
-
-class TestScriptGateError:
-    """Script errors (non-zero exit) should not block the agent."""
-
-    def test_nonzero_exit_proceeds(self):
-        job = _make_job(script='exit 1')
-
-        with patch("cron.scheduler._build_job_prompt", side_effect=lambda j: j.get("prompt", "")):
-            with patch("cron.scheduler.SessionDB", create=True):
-                try:
-                    result = run_job(job)
-                    success, output, response, error = result
-                    # Non-zero exit doesn't produce valid JSON, so agent proceeds
-                    assert "Script gate: agent skipped" not in response
-                except Exception:
-                    pass
-
-    def test_nonzero_exit_with_json_still_works(self):
-        """A script can exit non-zero but still output valid JSON."""
-        job = _make_job(script='echo \'{"wakeAgent": false}\'\nexit 1')
-
-        with patch("cron.scheduler._build_job_prompt", side_effect=lambda j: j.get("prompt", "")):
-            with patch("cron.scheduler.SessionDB", create=True):
-                # subprocess.run doesn't raise on non-zero exit (no check=True),
-                # so the JSON should still be parsed
-                success, output, response, error = run_job(job)
-                assert success is True
-                assert "Script gate: agent skipped" in response
-
-    def test_script_exception_proceeds(self):
-        """If subprocess.run itself raises an unexpected error, proceed."""
-        job = _make_job(script="echo hello")
-
-        with patch("cron.scheduler._build_job_prompt", side_effect=lambda j: j.get("prompt", "")):
-            with patch("cron.scheduler.SessionDB", create=True):
-                with patch("cron.scheduler.subprocess.run",
-                           side_effect=OSError("No bash")):
-                    try:
-                        result = run_job(job)
-                        success, output, response, error = result
-                        assert "Script gate: agent skipped" not in response
-                    except Exception:
-                        # The OSError should have been caught by the script gate
-                        # and not propagated. If we get here, something else failed.
-                        pass
-
-
-# ---------------------------------------------------------------------------
-# Integration-style test: actually run bash and verify full flow
-# ---------------------------------------------------------------------------
-
-
-class TestScriptGateIntegration:
-    """End-to-end tests that actually execute bash scripts."""
-
-    def test_full_skip_flow(self):
-        """Complete flow: script says skip, verify early return."""
-        job = _make_job(
-            script='echo "performing check..."\necho \'{"wakeAgent": false}\'',
-            prompt="This should never reach the agent",
-        )
-        with patch("cron.scheduler._build_job_prompt", side_effect=lambda j: j.get("prompt", "")):
-            with patch("cron.scheduler.SessionDB", create=True):
-                success, output, response, error = run_job(job)
-
-        assert success is True
-        assert response == "Script gate: agent skipped"
-        assert error is None
-        assert "test-job" in output
-
-    def test_full_data_prepend_flow(self):
-        """Complete flow: script provides data, verify it reaches the prompt."""
-        data = {"status": "changed", "items": [1, 2, 3]}
-        script = f"""
-echo "Running pre-check..."
-echo '{json.dumps({"wakeAgent": True, "data": data})}'
-"""
-        job = _make_job(script=script, prompt="Process the data")
-
-        # We can't easily run the full agent, but we can verify the prompt
-        # gets modified by capturing what _build_job_prompt returns and then
-        # checking the prompt that reaches the agent.
-        #
-        # Instead, test the script execution and JSON parsing directly:
-        result = subprocess.run(
-            ["bash", "-c", script],
-            capture_output=True, text=True, timeout=10,
-        )
-        lines = [l for l in result.stdout.splitlines() if l.strip()]
-        gate = json.loads(lines[-1].strip())
-
-        assert gate["wakeAgent"] is True
-        assert gate["data"] == data
-
-    def test_multiline_script(self):
-        """Multi-line script with conditionals."""
-        script = """#!/bin/bash
-CHANGED=true
-if [ "$CHANGED" = "true" ]; then
-    echo '{"wakeAgent": true, "data": {"reason": "files changed"}}'
-else
-    echo '{"wakeAgent": false}'
-fi
-"""
-        job = _make_job(script=script)
-
-        # Verify bash executes it correctly
-        result = subprocess.run(
-            ["bash", "-c", script],
-            capture_output=True, text=True, timeout=10,
-        )
-        lines = [l for l in result.stdout.splitlines() if l.strip()]
-        gate = json.loads(lines[-1].strip())
-
-        assert gate["wakeAgent"] is True
-        assert gate["data"]["reason"] == "files changed"

tests/gateway/test_config.py

@@ -1,15 +1,11 @@
 """Tests for gateway configuration management."""
 
-import os
-from unittest.mock import patch
-
 from gateway.config import (
     GatewayConfig,
     HomeChannel,
     Platform,
     PlatformConfig,
     SessionResetPolicy,
-    _apply_env_overrides,
     load_gateway_config,
 )
 
@@ -196,75 +192,3 @@ class TestLoadGatewayConfig:
 
         assert config.unauthorized_dm_behavior == "ignore"
         assert config.platforms[Platform.WHATSAPP].extra["unauthorized_dm_behavior"] == "pair"
-
-
-class TestHomeChannelEnvOverrides:
-    """Home channel env vars should apply even when the platform was already
-    configured via config.yaml (not just when credential env vars create it)."""
-
-    def test_existing_platform_configs_accept_home_channel_env_overrides(self):
-        cases = [
-            (
-                Platform.SLACK,
-                PlatformConfig(enabled=True, token="xoxb-from-config"),
-                {"SLACK_HOME_CHANNEL": "C123", "SLACK_HOME_CHANNEL_NAME": "Ops"},
-                ("C123", "Ops"),
-            ),
-            (
-                Platform.SIGNAL,
-                PlatformConfig(
-                    enabled=True,
-                    extra={"http_url": "http://localhost:9090", "account": "+15551234567"},
-                ),
-                {"SIGNAL_HOME_CHANNEL": "+1555000", "SIGNAL_HOME_CHANNEL_NAME": "Phone"},
-                ("+1555000", "Phone"),
-            ),
-            (
-                Platform.MATTERMOST,
-                PlatformConfig(
-                    enabled=True,
-                    token="mm-token",
-                    extra={"url": "https://mm.example.com"},
-                ),
-                {"MATTERMOST_HOME_CHANNEL": "ch_abc123", "MATTERMOST_HOME_CHANNEL_NAME": "General"},
-                ("ch_abc123", "General"),
-            ),
-            (
-                Platform.MATRIX,
-                PlatformConfig(
-                    enabled=True,
-                    token="syt_abc123",
-                    extra={"homeserver": "https://matrix.example.org"},
-                ),
-                {"MATRIX_HOME_ROOM": "!room123:example.org", "MATRIX_HOME_ROOM_NAME": "Bot Room"},
-                ("!room123:example.org", "Bot Room"),
-            ),
-            (
-                Platform.EMAIL,
-                PlatformConfig(
-                    enabled=True,
-                    extra={
-                        "address": "hermes@test.com",
-                        "imap_host": "imap.test.com",
-                        "smtp_host": "smtp.test.com",
-                    },
-                ),
-                {"EMAIL_HOME_ADDRESS": "user@test.com", "EMAIL_HOME_ADDRESS_NAME": "Inbox"},
-                ("user@test.com", "Inbox"),
-            ),
-            (
-                Platform.SMS,
-                PlatformConfig(enabled=True, api_key="token_abc"),
-                {"SMS_HOME_CHANNEL": "+15559876543", "SMS_HOME_CHANNEL_NAME": "My Phone"},
-                ("+15559876543", "My Phone"),
-            ),
-        ]
-
-        for platform, platform_config, env, expected in cases:
-            config = GatewayConfig(platforms={platform: platform_config})
-            with patch.dict(os.environ, env, clear=True):
-                _apply_env_overrides(config)
-
-            home = config.platforms[platform].home_channel
-            assert home is not None, f"{platform.value}: home_channel should not be None"
-            assert (home.chat_id, home.name) == expected, platform.value

tests/gateway/test_email.py

@@ -1057,122 +1057,5 @@ class TestSendEmailStandalone(unittest.TestCase):
         self.assertIn("not configured", result["error"])
 
 
-class TestSmtpConnectionCleanup(unittest.TestCase):
-    """Verify SMTP connections are closed even when send_message raises."""
-
-    @patch.dict(os.environ, {
-        "EMAIL_ADDRESS": "hermes@test.com",
-        "EMAIL_PASSWORD": "secret",
-        "EMAIL_IMAP_HOST": "imap.test.com",
-        "EMAIL_SMTP_HOST": "smtp.test.com",
-        "EMAIL_SMTP_PORT": "587",
-    }, clear=False)
-    def _make_adapter(self):
-        from gateway.config import PlatformConfig
-        from gateway.platforms.email import EmailAdapter
-        return EmailAdapter(PlatformConfig(enabled=True))
-
-    @patch.dict(os.environ, {
-        "EMAIL_ADDRESS": "hermes@test.com",
-        "EMAIL_PASSWORD": "secret",
-        "EMAIL_IMAP_HOST": "imap.test.com",
-        "EMAIL_SMTP_HOST": "smtp.test.com",
-        "EMAIL_SMTP_PORT": "587",
-    }, clear=False)
-    def test_smtp_quit_called_on_send_message_failure(self):
-        """SMTP quit() must be called even when send_message() raises."""
-        adapter = self._make_adapter()
-        mock_smtp = MagicMock()
-        mock_smtp.send_message.side_effect = Exception("send failed")
-
-        with patch("smtplib.SMTP", return_value=mock_smtp):
-            with self.assertRaises(Exception):
-                adapter._send_email("user@test.com", "Hello")
-
-        mock_smtp.quit.assert_called_once()
-
-    @patch.dict(os.environ, {
-        "EMAIL_ADDRESS": "hermes@test.com",
-        "EMAIL_PASSWORD": "secret",
-        "EMAIL_IMAP_HOST": "imap.test.com",
-        "EMAIL_SMTP_HOST": "smtp.test.com",
-        "EMAIL_SMTP_PORT": "587",
-    }, clear=False)
-    def test_smtp_close_called_when_quit_also_fails(self):
-        """If both send_message() and quit() fail, close() is the fallback."""
-        adapter = self._make_adapter()
-        mock_smtp = MagicMock()
-        mock_smtp.send_message.side_effect = Exception("send failed")
-        mock_smtp.quit.side_effect = Exception("quit failed")
-
-        with patch("smtplib.SMTP", return_value=mock_smtp):
-            with self.assertRaises(Exception):
-                adapter._send_email("user@test.com", "Hello")
-
-        mock_smtp.close.assert_called_once()
-
-
-class TestImapConnectionCleanup(unittest.TestCase):
-    """Verify IMAP connections are closed even when fetch raises."""
-
-    @patch.dict(os.environ, {
-        "EMAIL_ADDRESS": "hermes@test.com",
-        "EMAIL_PASSWORD": "secret",
-        "EMAIL_IMAP_HOST": "imap.test.com",
-        "EMAIL_IMAP_PORT": "993",
-        "EMAIL_SMTP_HOST": "smtp.test.com",
-    }, clear=False)
-    def _make_adapter(self):
-        from gateway.config import PlatformConfig
-        from gateway.platforms.email import EmailAdapter
-        return EmailAdapter(PlatformConfig(enabled=True))
-
-    @patch.dict(os.environ, {
-        "EMAIL_ADDRESS": "hermes@test.com",
-        "EMAIL_PASSWORD": "secret",
-        "EMAIL_IMAP_HOST": "imap.test.com",
-        "EMAIL_IMAP_PORT": "993",
-        "EMAIL_SMTP_HOST": "smtp.test.com",
-    }, clear=False)
-    def test_imap_logout_called_on_uid_fetch_failure(self):
-        """IMAP logout() must be called even when uid fetch raises."""
-        adapter = self._make_adapter()
-        mock_imap = MagicMock()
-
-        def uid_handler(command, *args):
-            if command == "search":
-                return ("OK", [b"1"])
-            if command == "fetch":
-                raise Exception("fetch failed")
-            return ("NO", [])
-
-        mock_imap.uid.side_effect = uid_handler
-
-        with patch("imaplib.IMAP4_SSL", return_value=mock_imap):
-            results = adapter._fetch_new_messages()
-
-        self.assertEqual(results, [])
-        mock_imap.logout.assert_called_once()
-
-    @patch.dict(os.environ, {
-        "EMAIL_ADDRESS": "hermes@test.com",
-        "EMAIL_PASSWORD": "secret",
-        "EMAIL_IMAP_HOST": "imap.test.com",
-        "EMAIL_IMAP_PORT": "993",
-        "EMAIL_SMTP_HOST": "smtp.test.com",
-    }, clear=False)
-    def test_imap_logout_called_on_early_return(self):
-        """IMAP logout() must be called even when returning early (no unseen)."""
-        adapter = self._make_adapter()
-        mock_imap = MagicMock()
-        mock_imap.uid.return_value = ("OK", [b""])
-
-        with patch("imaplib.IMAP4_SSL", return_value=mock_imap):
-            results = adapter._fetch_new_messages()
-
-        self.assertEqual(results, [])
-        mock_imap.logout.assert_called_once()
-
-
 if __name__ == "__main__":
     unittest.main()

tests/gateway/test_keystore_injection.py

@@ -0,0 +1,189 @@
+"""Gateway keystore injection regression tests."""
+
+from __future__ import annotations
+
+import importlib
+import os
+import sys
+from pathlib import Path
+
+import pytest
+
+nacl = pytest.importorskip("nacl")
+argon2 = pytest.importorskip("argon2")
+
+
+def _reload_gateway_run(monkeypatch, home: Path):
+    monkeypatch.setenv("HERMES_HOME", str(home))
+    monkeypatch.delenv("HERMES_KEYSTORE_OWNED_VARS", raising=False)
+    monkeypatch.delenv("HERMES_KEYSTORE_OWNED_VALUES_JSON", raising=False)
+    # Reset cached singletons that capture prior HERMES_HOME or lock state.
+    try:
+        from keystore.client import reset_keystore
+        reset_keystore()
+    except Exception:
+        pass
+    try:
+        from wallet.runtime import reset_runtime
+        reset_runtime()
+    except Exception:
+        pass
+    sys.modules.pop("gateway.run", None)
+    import gateway.run as gateway_run
+    importlib.reload(gateway_run)
+    return gateway_run
+
+
+def test_gateway_import_injects_keystore_without_config_yaml(tmp_path, monkeypatch):
+    home = tmp_path / ".hermes"
+    home.mkdir(parents=True)
+    (home / ".env").write_text("")
+
+    # Initialize keystore with a secret, but do not create config.yaml.
+    monkeypatch.setenv("HERMES_HOME", str(home))
+    from keystore.client import KeystoreClient, reset_keystore
+    reset_keystore()
+    ks = KeystoreClient(home / "keystore" / "secrets.db")
+    ks.initialize("passphrase")
+    ks.set_secret("OPENAI_API_KEY", "sk-test-from-keystore")
+
+    monkeypatch.setenv("HERMES_KEYSTORE_PASSPHRASE", "passphrase")
+    monkeypatch.delenv("OPENAI_API_KEY", raising=False)
+    monkeypatch.delenv("OPENROUTER_API_KEY", raising=False)
+
+    gateway_run = _reload_gateway_run(monkeypatch, home)
+    assert os.environ.get("OPENAI_API_KEY") == "sk-test-from-keystore"
+
+
+def test_gateway_refresh_reinjects_keystore_secret(monkeypatch, tmp_path):
+    home = tmp_path / ".hermes"
+    home.mkdir(parents=True)
+    (home / ".env").write_text("")
+    (home / "config.yaml").write_text("toolsets:\n- hermes-cli\n")
+
+    monkeypatch.setenv("HERMES_HOME", str(home))
+    from keystore.client import KeystoreClient, reset_keystore
+    reset_keystore()
+    ks = KeystoreClient(home / "keystore" / "secrets.db")
+    ks.initialize("passphrase")
+    ks.set_secret("OPENAI_API_KEY", "sk-old")
+    monkeypatch.setenv("HERMES_KEYSTORE_PASSPHRASE", "passphrase")
+    monkeypatch.delenv("OPENAI_API_KEY", raising=False)
+    monkeypatch.delenv("OPENROUTER_API_KEY", raising=False)
+
+    gateway_run = _reload_gateway_run(monkeypatch, home)
+    assert os.environ.get("OPENAI_API_KEY") == "sk-old"
+
+    # Rotate secret in keystore; refresh must overwrite the stale in-process env var
+    # because that value originally came from keystore injection.
+    ks.set_secret("OPENAI_API_KEY", "sk-new")
+    os.environ["OPENAI_API_KEY"] = "stale"
+    gateway_run._inject_keystore_env(force=True, external_managed_names=set())
+    assert os.environ.get("OPENAI_API_KEY") == "sk-new"
+
+
+def test_gateway_refresh_does_not_clobber_external_env(monkeypatch, tmp_path):
+    home = tmp_path / ".hermes"
+    home.mkdir(parents=True)
+    (home / ".env").write_text("")
+
+    monkeypatch.setenv("HERMES_HOME", str(home))
+    from keystore.client import KeystoreClient, reset_keystore
+    reset_keystore()
+    ks = KeystoreClient(home / "keystore" / "secrets.db")
+    ks.initialize("passphrase")
+    ks.set_secret("OPENAI_API_KEY", "keystore-value")
+    monkeypatch.setenv("HERMES_KEYSTORE_PASSPHRASE", "passphrase")
+
+    # External env should win at startup and remain authoritative on refresh.
+    monkeypatch.setenv("OPENAI_API_KEY", "env-wins")
+    gateway_run = _reload_gateway_run(monkeypatch, home)
+    assert os.environ.get("OPENAI_API_KEY") == "env-wins"
+
+    ks.set_secret("OPENAI_API_KEY", "rotated-keystore-value")
+    gateway_run._inject_keystore_env(force=True, external_managed_names={"OPENAI_API_KEY"})
+    assert os.environ.get("OPENAI_API_KEY") == "env-wins"
+
+
+def test_gateway_refresh_revokes_deleted_keystore_secret(monkeypatch, tmp_path):
+    home = tmp_path / ".hermes"
+    home.mkdir(parents=True)
+    (home / ".env").write_text("")
+    (home / "config.yaml").write_text("toolsets:\n- hermes-cli\n")
+
+    monkeypatch.setenv("HERMES_HOME", str(home))
+    from keystore.client import KeystoreClient, reset_keystore
+    reset_keystore()
+    ks = KeystoreClient(home / "keystore" / "secrets.db")
+    ks.initialize("passphrase")
+    ks.set_secret("OPENAI_API_KEY", "sk-old")
+    monkeypatch.setenv("HERMES_KEYSTORE_PASSPHRASE", "passphrase")
+    monkeypatch.delenv("OPENAI_API_KEY", raising=False)
+    monkeypatch.delenv("OPENROUTER_API_KEY", raising=False)
+
+    gateway_run = _reload_gateway_run(monkeypatch, home)
+    assert os.environ.get("OPENAI_API_KEY") == "sk-old"
+
+    # Delete from keystore; force refresh should revoke the previously
+    # injected env var from the long-lived process.
+    ks.delete_secret("OPENAI_API_KEY")
+    gateway_run._inject_keystore_env(force=True, external_managed_names=set())
+    assert os.environ.get("OPENAI_API_KEY") is None
+
+
+def test_gateway_refresh_delete_preserves_external_replacement(monkeypatch, tmp_path):
+    home = tmp_path / ".hermes"
+    home.mkdir(parents=True)
+    env_path = home / ".env"
+    env_path.write_text("")
+    (home / "config.yaml").write_text("toolsets:\n- hermes-cli\n")
+
+    monkeypatch.setenv("HERMES_HOME", str(home))
+    from keystore.client import KeystoreClient, reset_keystore
+    reset_keystore()
+    ks = KeystoreClient(home / "keystore" / "secrets.db")
+    ks.initialize("passphrase")
+    ks.set_secret("OPENAI_API_KEY", "sk-old")
+    monkeypatch.setenv("HERMES_KEYSTORE_PASSPHRASE", "passphrase")
+    monkeypatch.delenv("OPENAI_API_KEY", raising=False)
+    monkeypatch.delenv("OPENROUTER_API_KEY", raising=False)
+
+    gateway_run = _reload_gateway_run(monkeypatch, home)
+    assert os.environ.get("OPENAI_API_KEY") == "sk-old"
+
+    # Secret removed from keystore, but .env now provides a replacement.
+    ks.delete_secret("OPENAI_API_KEY")
+    env_path.write_text("OPENAI_API_KEY=env-replacement\n")
+    from dotenv import load_dotenv
+    load_dotenv(env_path, override=True)
+    gateway_run._inject_keystore_env(force=True, external_managed_names={"OPENAI_API_KEY"})
+    assert os.environ.get("OPENAI_API_KEY") == "env-replacement"
+
+
+def test_gateway_refresh_delete_preserves_same_value_external_replacement(monkeypatch, tmp_path):
+    home = tmp_path / ".hermes"
+    home.mkdir(parents=True)
+    env_path = home / ".env"
+    env_path.write_text("")
+    (home / "config.yaml").write_text("toolsets:\n- hermes-cli\n")
+
+    monkeypatch.setenv("HERMES_HOME", str(home))
+    from keystore.client import KeystoreClient, reset_keystore
+    reset_keystore()
+    ks = KeystoreClient(home / "keystore" / "secrets.db")
+    ks.initialize("passphrase")
+    ks.set_secret("OPENAI_API_KEY", "same-value")
+    monkeypatch.setenv("HERMES_KEYSTORE_PASSPHRASE", "passphrase")
+    monkeypatch.delenv("OPENAI_API_KEY", raising=False)
+    monkeypatch.delenv("OPENROUTER_API_KEY", raising=False)
+
+    gateway_run = _reload_gateway_run(monkeypatch, home)
+    assert os.environ.get("OPENAI_API_KEY") == "same-value"
+
+    # Move the key back to external .env management without rotating the string.
+    ks.delete_secret("OPENAI_API_KEY")
+    env_path.write_text("OPENAI_API_KEY=same-value\n")
+    from dotenv import load_dotenv
+    load_dotenv(env_path, override=True)
+    gateway_run._inject_keystore_env(force=True, external_managed_names={"OPENAI_API_KEY"})
+    assert os.environ.get("OPENAI_API_KEY") == "same-value"

tests/gateway/test_mattermost.py

@@ -1,6 +1,5 @@
 """Tests for Mattermost platform adapter."""
 import json
-import os
 import time
 import pytest
 from unittest.mock import MagicMock, patch, AsyncMock
@@ -270,7 +269,6 @@ class TestMattermostWebSocketParsing:
     def setup_method(self):
         self.adapter = _make_adapter()
         self.adapter._bot_user_id = "bot_user_id"
-        self.adapter._bot_username = "hermes-bot"
         # Mock handle_message to capture the MessageEvent without processing
         self.adapter.handle_message = AsyncMock()
 
@@ -295,8 +293,7 @@ class TestMattermostWebSocketParsing:
         await self.adapter._handle_ws_event(event)
         assert self.adapter.handle_message.called
         msg_event = self.adapter.handle_message.call_args[0][0]
-        # @mention is stripped from the message text
-        assert msg_event.text == "Hello from Matrix!"
+        assert msg_event.text == "@bot_user_id Hello from Matrix!"
         assert msg_event.message_id == "post_abc"
 
     @pytest.mark.asyncio
@@ -413,87 +410,6 @@ class TestMattermostWebSocketParsing:
         assert not self.adapter.handle_message.called
 
 
-# ---------------------------------------------------------------------------
-# Mention behavior (require_mention + free_response_channels)
-# ---------------------------------------------------------------------------
-
-class TestMattermostMentionBehavior:
-    def setup_method(self):
-        self.adapter = _make_adapter()
-        self.adapter._bot_user_id = "bot_user_id"
-        self.adapter._bot_username = "hermes-bot"
-        self.adapter.handle_message = AsyncMock()
-
-    def _make_event(self, message, channel_type="O", channel_id="chan_456"):
-        post_data = {
-            "id": "post_mention",
-            "user_id": "user_123",
-            "channel_id": channel_id,
-            "message": message,
-        }
-        return {
-            "event": "posted",
-            "data": {
-                "post": json.dumps(post_data),
-                "channel_type": channel_type,
-                "sender_name": "@alice",
-            },
-        }
-
-    @pytest.mark.asyncio
-    async def test_require_mention_true_skips_without_mention(self):
-        """Default: messages without @mention in channels are skipped."""
-        with patch.dict(os.environ, {}, clear=False):
-            os.environ.pop("MATTERMOST_REQUIRE_MENTION", None)
-            os.environ.pop("MATTERMOST_FREE_RESPONSE_CHANNELS", None)
-            await self.adapter._handle_ws_event(self._make_event("hello"))
-            assert not self.adapter.handle_message.called
-
-    @pytest.mark.asyncio
-    async def test_require_mention_false_responds_to_all(self):
-        """MATTERMOST_REQUIRE_MENTION=false: respond to all channel messages."""
-        with patch.dict(os.environ, {"MATTERMOST_REQUIRE_MENTION": "false"}):
-            await self.adapter._handle_ws_event(self._make_event("hello"))
-            assert self.adapter.handle_message.called
-
-    @pytest.mark.asyncio
-    async def test_free_response_channel_responds_without_mention(self):
-        """Messages in free-response channels don't need @mention."""
-        with patch.dict(os.environ, {"MATTERMOST_FREE_RESPONSE_CHANNELS": "chan_456,chan_789"}):
-            os.environ.pop("MATTERMOST_REQUIRE_MENTION", None)
-            await self.adapter._handle_ws_event(self._make_event("hello", channel_id="chan_456"))
-            assert self.adapter.handle_message.called
-
-    @pytest.mark.asyncio
-    async def test_non_free_channel_still_requires_mention(self):
-        """Channels NOT in free-response list still require @mention."""
-        with patch.dict(os.environ, {"MATTERMOST_FREE_RESPONSE_CHANNELS": "chan_789"}):
-            os.environ.pop("MATTERMOST_REQUIRE_MENTION", None)
-            await self.adapter._handle_ws_event(self._make_event("hello", channel_id="chan_456"))
-            assert not self.adapter.handle_message.called
-
-    @pytest.mark.asyncio
-    async def test_dm_always_responds(self):
-        """DMs (channel_type=D) always respond regardless of mention settings."""
-        with patch.dict(os.environ, {}, clear=False):
-            os.environ.pop("MATTERMOST_REQUIRE_MENTION", None)
-            await self.adapter._handle_ws_event(self._make_event("hello", channel_type="D"))
-            assert self.adapter.handle_message.called
-
-    @pytest.mark.asyncio
-    async def test_mention_stripped_from_text(self):
-        """@mention is stripped from message text."""
-        with patch.dict(os.environ, {}, clear=False):
-            os.environ.pop("MATTERMOST_REQUIRE_MENTION", None)
-            await self.adapter._handle_ws_event(
-                self._make_event("@hermes-bot what is 2+2")
-            )
-            assert self.adapter.handle_message.called
-            msg = self.adapter.handle_message.call_args[0][0]
-            assert "@hermes-bot" not in msg.text
-            assert "2+2" in msg.text
-
-
 # ---------------------------------------------------------------------------
 # File upload (send_image)
 # ---------------------------------------------------------------------------

tests/gateway/test_media_download_retry.py

@@ -171,170 +171,6 @@ class TestCacheImageFromUrl:
         mock_sleep.assert_not_called()
 
 
-# ---------------------------------------------------------------------------
-# cache_audio_from_url (base.py)
-# ---------------------------------------------------------------------------
-
-class TestCacheAudioFromUrl:
-    """Tests for gateway.platforms.base.cache_audio_from_url"""
-
-    def test_success_on_first_attempt(self, tmp_path, monkeypatch):
-        """A clean 200 response caches the audio and returns a path."""
-        monkeypatch.setattr("gateway.platforms.base.AUDIO_CACHE_DIR", tmp_path / "audio")
-
-        fake_response = MagicMock()
-        fake_response.content = b"\x00\x01 fake audio"
-        fake_response.raise_for_status = MagicMock()
-
-        mock_client = AsyncMock()
-        mock_client.get = AsyncMock(return_value=fake_response)
-        mock_client.__aenter__ = AsyncMock(return_value=mock_client)
-        mock_client.__aexit__ = AsyncMock(return_value=False)
-
-        async def run():
-            with patch("httpx.AsyncClient", return_value=mock_client):
-                from gateway.platforms.base import cache_audio_from_url
-                return await cache_audio_from_url(
-                    "http://example.com/voice.ogg", ext=".ogg"
-                )
-
-        path = asyncio.run(run())
-        assert path.endswith(".ogg")
-        mock_client.get.assert_called_once()
-
-    def test_retries_on_timeout_then_succeeds(self, tmp_path, monkeypatch):
-        """A timeout on the first attempt is retried; second attempt succeeds."""
-        monkeypatch.setattr("gateway.platforms.base.AUDIO_CACHE_DIR", tmp_path / "audio")
-
-        fake_response = MagicMock()
-        fake_response.content = b"audio data"
-        fake_response.raise_for_status = MagicMock()
-
-        mock_client = AsyncMock()
-        mock_client.get = AsyncMock(
-            side_effect=[_make_timeout_error(), fake_response]
-        )
-        mock_client.__aenter__ = AsyncMock(return_value=mock_client)
-        mock_client.__aexit__ = AsyncMock(return_value=False)
-
-        mock_sleep = AsyncMock()
-
-        async def run():
-            with patch("httpx.AsyncClient", return_value=mock_client), \
-                 patch("asyncio.sleep", mock_sleep):
-                from gateway.platforms.base import cache_audio_from_url
-                return await cache_audio_from_url(
-                    "http://example.com/voice.ogg", ext=".ogg", retries=2
-                )
-
-        path = asyncio.run(run())
-        assert path.endswith(".ogg")
-        assert mock_client.get.call_count == 2
-        mock_sleep.assert_called_once()
-
-    def test_retries_on_429_then_succeeds(self, tmp_path, monkeypatch):
-        """A 429 response on the first attempt is retried; second attempt succeeds."""
-        monkeypatch.setattr("gateway.platforms.base.AUDIO_CACHE_DIR", tmp_path / "audio")
-
-        ok_response = MagicMock()
-        ok_response.content = b"audio data"
-        ok_response.raise_for_status = MagicMock()
-
-        mock_client = AsyncMock()
-        mock_client.get = AsyncMock(
-            side_effect=[_make_http_status_error(429), ok_response]
-        )
-        mock_client.__aenter__ = AsyncMock(return_value=mock_client)
-        mock_client.__aexit__ = AsyncMock(return_value=False)
-
-        async def run():
-            with patch("httpx.AsyncClient", return_value=mock_client), \
-                 patch("asyncio.sleep", new_callable=AsyncMock):
-                from gateway.platforms.base import cache_audio_from_url
-                return await cache_audio_from_url(
-                    "http://example.com/voice.ogg", ext=".ogg", retries=2
-                )
-
-        path = asyncio.run(run())
-        assert path.endswith(".ogg")
-        assert mock_client.get.call_count == 2
-
-    def test_retries_on_500_then_succeeds(self, tmp_path, monkeypatch):
-        """A 500 response on the first attempt is retried; second attempt succeeds."""
-        monkeypatch.setattr("gateway.platforms.base.AUDIO_CACHE_DIR", tmp_path / "audio")
-
-        ok_response = MagicMock()
-        ok_response.content = b"audio data"
-        ok_response.raise_for_status = MagicMock()
-
-        mock_client = AsyncMock()
-        mock_client.get = AsyncMock(
-            side_effect=[_make_http_status_error(500), ok_response]
-        )
-        mock_client.__aenter__ = AsyncMock(return_value=mock_client)
-        mock_client.__aexit__ = AsyncMock(return_value=False)
-
-        async def run():
-            with patch("httpx.AsyncClient", return_value=mock_client), \
-                 patch("asyncio.sleep", new_callable=AsyncMock):
-                from gateway.platforms.base import cache_audio_from_url
-                return await cache_audio_from_url(
-                    "http://example.com/voice.ogg", ext=".ogg", retries=2
-                )
-
-        path = asyncio.run(run())
-        assert path.endswith(".ogg")
-        assert mock_client.get.call_count == 2
-
-    def test_raises_after_max_retries_exhausted(self, tmp_path, monkeypatch):
-        """Timeout on every attempt raises after all retries are consumed."""
-        monkeypatch.setattr("gateway.platforms.base.AUDIO_CACHE_DIR", tmp_path / "audio")
-
-        mock_client = AsyncMock()
-        mock_client.get = AsyncMock(side_effect=_make_timeout_error())
-        mock_client.__aenter__ = AsyncMock(return_value=mock_client)
-        mock_client.__aexit__ = AsyncMock(return_value=False)
-
-        async def run():
-            with patch("httpx.AsyncClient", return_value=mock_client), \
-                 patch("asyncio.sleep", new_callable=AsyncMock):
-                from gateway.platforms.base import cache_audio_from_url
-                await cache_audio_from_url(
-                    "http://example.com/voice.ogg", ext=".ogg", retries=2
-                )
-
-        with pytest.raises(httpx.TimeoutException):
-            asyncio.run(run())
-
-        # 3 total calls: initial + 2 retries
-        assert mock_client.get.call_count == 3
-
-    def test_non_retryable_4xx_raises_immediately(self, tmp_path, monkeypatch):
-        """A 404 (non-retryable) is raised immediately without any retry."""
-        monkeypatch.setattr("gateway.platforms.base.AUDIO_CACHE_DIR", tmp_path / "audio")
-
-        mock_sleep = AsyncMock()
-        mock_client = AsyncMock()
-        mock_client.get = AsyncMock(side_effect=_make_http_status_error(404))
-        mock_client.__aenter__ = AsyncMock(return_value=mock_client)
-        mock_client.__aexit__ = AsyncMock(return_value=False)
-
-        async def run():
-            with patch("httpx.AsyncClient", return_value=mock_client), \
-                 patch("asyncio.sleep", mock_sleep):
-                from gateway.platforms.base import cache_audio_from_url
-                await cache_audio_from_url(
-                    "http://example.com/voice.ogg", ext=".ogg", retries=2
-                )
-
-        with pytest.raises(httpx.HTTPStatusError):
-            asyncio.run(run())
-
-        # Only 1 attempt, no sleep
-        assert mock_client.get.call_count == 1
-        mock_sleep.assert_not_called()
-
-
 # ---------------------------------------------------------------------------
 # Slack mock setup (mirrors existing test_slack.py approach)
 # ---------------------------------------------------------------------------

tests/gateway/test_signal.py

@@ -1,42 +1,11 @@
 """Tests for Signal messenger platform adapter."""
-import base64
 import json
 import pytest
 from unittest.mock import MagicMock, patch, AsyncMock
-from urllib.parse import quote
 
 from gateway.config import Platform, PlatformConfig
 
 
-# ---------------------------------------------------------------------------
-# Shared Helpers
-# ---------------------------------------------------------------------------
-
-def _make_signal_adapter(monkeypatch, account="+15551234567", **extra):
-    """Create a SignalAdapter with sensible test defaults."""
-    monkeypatch.setenv("SIGNAL_GROUP_ALLOWED_USERS", extra.pop("group_allowed", ""))
-    from gateway.platforms.signal import SignalAdapter
-    config = PlatformConfig()
-    config.enabled = True
-    config.extra = {
-        "http_url": "http://localhost:8080",
-        "account": account,
-        **extra,
-    }
-    return SignalAdapter(config)
-
-
-def _stub_rpc(return_value):
-    """Return an async mock for SignalAdapter._rpc that captures call params."""
-    captured = []
-
-    async def mock_rpc(method, params, rpc_id=None):
-        captured.append({"method": method, "params": dict(params)})
-        return return_value
-
-    return mock_rpc, captured
-
-
 # ---------------------------------------------------------------------------
 # Platform & Config
 # ---------------------------------------------------------------------------
@@ -92,22 +61,48 @@ class TestSignalConfigLoading:
 # ---------------------------------------------------------------------------
 
 class TestSignalAdapterInit:
+    def _make_config(self, **extra):
+        config = PlatformConfig()
+        config.enabled = True
+        config.extra = {
+            "http_url": "http://localhost:8080",
+            "account": "+15551234567",
+            **extra,
+        }
+        return config
+
     def test_init_parses_config(self, monkeypatch):
-        adapter = _make_signal_adapter(monkeypatch, group_allowed="group123,group456")
+        monkeypatch.setenv("SIGNAL_GROUP_ALLOWED_USERS", "group123,group456")
+
+        from gateway.platforms.signal import SignalAdapter
+        adapter = SignalAdapter(self._make_config())
+
         assert adapter.http_url == "http://localhost:8080"
         assert adapter.account == "+15551234567"
         assert "group123" in adapter.group_allow_from
 
     def test_init_empty_allowlist(self, monkeypatch):
-        adapter = _make_signal_adapter(monkeypatch)
+        monkeypatch.setenv("SIGNAL_GROUP_ALLOWED_USERS", "")
+
+        from gateway.platforms.signal import SignalAdapter
+        adapter = SignalAdapter(self._make_config())
+
         assert len(adapter.group_allow_from) == 0
 
     def test_init_strips_trailing_slash(self, monkeypatch):
-        adapter = _make_signal_adapter(monkeypatch, http_url="http://localhost:8080/")
+        monkeypatch.setenv("SIGNAL_GROUP_ALLOWED_USERS", "")
+
+        from gateway.platforms.signal import SignalAdapter
+        adapter = SignalAdapter(self._make_config(http_url="http://localhost:8080/"))
+
         assert adapter.http_url == "http://localhost:8080"
 
     def test_self_message_filtering(self, monkeypatch):
-        adapter = _make_signal_adapter(monkeypatch)
+        monkeypatch.setenv("SIGNAL_GROUP_ALLOWED_USERS", "")
+
+        from gateway.platforms.signal import SignalAdapter
+        adapter = SignalAdapter(self._make_config())
+
         assert adapter._account_normalized == "+15551234567"
 
 
@@ -194,73 +189,6 @@ class TestSignalHelpers:
         assert check_signal_requirements() is False
 
 
-# ---------------------------------------------------------------------------
-# SSE URL Encoding (Bug Fix: phone numbers with + must be URL-encoded)
-# ---------------------------------------------------------------------------
-
-class TestSignalSSEUrlEncoding:
-    """Verify that phone numbers with + are URL-encoded in the SSE endpoint."""
-
-    def test_sse_url_encodes_plus_in_account(self):
-        """The + in E.164 phone numbers must be percent-encoded in the SSE query string."""
-        encoded = quote("+31612345678", safe="")
-        assert encoded == "%2B31612345678"
-
-    def test_sse_url_encoding_preserves_digits(self):
-        """Digits and country codes should pass through URL encoding unchanged."""
-        assert quote("+15551234567", safe="") == "%2B15551234567"
-
-
-# ---------------------------------------------------------------------------
-# Attachment Fetch (Bug Fix: parameter must be "id" not "attachmentId")
-# ---------------------------------------------------------------------------
-
-class TestSignalAttachmentFetch:
-    """Verify that _fetch_attachment uses the correct RPC parameter name."""
-
-    @pytest.mark.asyncio
-    async def test_fetch_attachment_uses_id_parameter(self, monkeypatch):
-        """RPC getAttachment must use 'id', not 'attachmentId' (signal-cli requirement)."""
-        adapter = _make_signal_adapter(monkeypatch)
-
-        png_data = b"\x89PNG\r\n\x1a\n" + b"\x00" * 100
-        b64_data = base64.b64encode(png_data).decode()
-
-        adapter._rpc, captured = _stub_rpc({"data": b64_data})
-
-        with patch("gateway.platforms.signal.cache_image_from_bytes", return_value="/tmp/test.png"):
-            await adapter._fetch_attachment("attachment-123")
-
-        call = captured[0]
-        assert call["method"] == "getAttachment"
-        assert call["params"]["id"] == "attachment-123"
-        assert "attachmentId" not in call["params"], "Must NOT use 'attachmentId' — causes NullPointerException in signal-cli"
-        assert call["params"]["account"] == "+15551234567"
-
-    @pytest.mark.asyncio
-    async def test_fetch_attachment_returns_none_on_empty(self, monkeypatch):
-        adapter = _make_signal_adapter(monkeypatch)
-        adapter._rpc, _ = _stub_rpc(None)
-        path, ext = await adapter._fetch_attachment("missing-id")
-        assert path is None
-        assert ext == ""
-
-    @pytest.mark.asyncio
-    async def test_fetch_attachment_handles_dict_response(self, monkeypatch):
-        adapter = _make_signal_adapter(monkeypatch)
-
-        pdf_data = b"%PDF-1.4" + b"\x00" * 100
-        b64_data = base64.b64encode(pdf_data).decode()
-
-        adapter._rpc, _ = _stub_rpc({"data": b64_data})
-
-        with patch("gateway.platforms.signal.cache_document_from_bytes", return_value="/tmp/test.pdf"):
-            path, ext = await adapter._fetch_attachment("doc-456")
-
-        assert path == "/tmp/test.pdf"
-        assert ext == ".pdf"
-
-
 # ---------------------------------------------------------------------------
 # Session Source
 # ---------------------------------------------------------------------------

tests/gateway/test_whatsapp_connect.py

@@ -63,7 +63,6 @@ def _make_adapter():
     adapter._background_tasks = set()
     adapter._auto_tts_disabled_chats = set()
     adapter._message_queue = asyncio.Queue()
-    adapter._http_session = None
     return adapter
 
 
@@ -220,7 +219,6 @@ class TestBridgeRuntimeFailure:
         fatal_handler = AsyncMock()
         adapter.set_fatal_error_handler(fatal_handler)
         adapter._running = True
-        adapter._http_session = MagicMock()  # Persistent session active
         mock_fh = MagicMock()
         adapter._bridge_log_fh = mock_fh
 
@@ -244,7 +242,6 @@ class TestBridgeRuntimeFailure:
         fatal_handler = AsyncMock()
         adapter.set_fatal_error_handler(fatal_handler)
         adapter._running = True
-        adapter._http_session = MagicMock()  # Persistent session active
         mock_fh = MagicMock()
         adapter._bridge_log_fh = mock_fh
 
@@ -420,83 +417,3 @@ class TestKillPortProcess:
         with patch("gateway.platforms.whatsapp._IS_WINDOWS", True), \
              patch("gateway.platforms.whatsapp.subprocess.run", side_effect=OSError("no netstat")):
             _kill_port_process(3000)  # must not raise
-
-
-# ---------------------------------------------------------------------------
-# Persistent HTTP session lifecycle
-# ---------------------------------------------------------------------------
-
-class TestHttpSessionLifecycle:
-    """Verify persistent aiohttp.ClientSession is created and cleaned up."""
-
-    @pytest.mark.asyncio
-    async def test_session_closed_on_disconnect(self):
-        """disconnect() should close self._http_session."""
-        adapter = _make_adapter()
-        mock_session = AsyncMock()
-        mock_session.closed = False
-        adapter._http_session = mock_session
-        adapter._poll_task = None
-        adapter._bridge_process = None
-        adapter._running = True
-        adapter._session_lock_identity = None
-
-        await adapter.disconnect()
-
-        mock_session.close.assert_called_once()
-        assert adapter._http_session is None
-
-    @pytest.mark.asyncio
-    async def test_session_not_closed_when_already_closed(self):
-        """disconnect() should skip close() when session is already closed."""
-        adapter = _make_adapter()
-        mock_session = AsyncMock()
-        mock_session.closed = True
-        adapter._http_session = mock_session
-        adapter._poll_task = None
-        adapter._bridge_process = None
-        adapter._running = True
-        adapter._session_lock_identity = None
-
-        await adapter.disconnect()
-
-        mock_session.close.assert_not_called()
-        assert adapter._http_session is None
-
-    @pytest.mark.asyncio
-    async def test_poll_task_cancelled_on_disconnect(self):
-        """disconnect() should cancel the poll task."""
-        adapter = _make_adapter()
-        mock_task = MagicMock()
-        mock_task.done.return_value = False
-        mock_task.cancel = MagicMock()
-        mock_future = asyncio.Future()
-        mock_future.set_exception(asyncio.CancelledError())
-        mock_task.__await__ = mock_future.__await__
-        adapter._poll_task = mock_task
-        adapter._http_session = None
-        adapter._bridge_process = None
-        adapter._running = True
-        adapter._session_lock_identity = None
-
-        await adapter.disconnect()
-
-        mock_task.cancel.assert_called_once()
-        assert adapter._poll_task is None
-
-    @pytest.mark.asyncio
-    async def test_disconnect_skips_done_poll_task(self):
-        """disconnect() should not cancel an already-done poll task."""
-        adapter = _make_adapter()
-        mock_task = MagicMock()
-        mock_task.done.return_value = True
-        adapter._poll_task = mock_task
-        adapter._http_session = None
-        adapter._bridge_process = None
-        adapter._running = True
-        adapter._session_lock_identity = None
-
-        await adapter.disconnect()
-
-        mock_task.cancel.assert_not_called()
-        assert adapter._poll_task is None

tests/hermes_cli/test_profiles.py

@@ -1,622 +0,0 @@
-"""Comprehensive tests for hermes_cli.profiles module.
-
-Tests cover: validation, directory resolution, CRUD operations, active profile
-management, export/import, renaming, alias collision checks, profile isolation,
-and shell completion generation.
-"""
-
-import json
-import os
-import tarfile
-from pathlib import Path
-from unittest.mock import patch, MagicMock
-
-import pytest
-
-from hermes_cli.profiles import (
-    validate_profile_name,
-    get_profile_dir,
-    create_profile,
-    delete_profile,
-    list_profiles,
-    set_active_profile,
-    get_active_profile,
-    get_active_profile_name,
-    resolve_profile_env,
-    check_alias_collision,
-    rename_profile,
-    export_profile,
-    import_profile,
-    generate_bash_completion,
-    generate_zsh_completion,
-    _get_profiles_root,
-    _get_default_hermes_home,
-)
-
-
-# ---------------------------------------------------------------------------
-# Shared fixture: redirect Path.home() and HERMES_HOME for profile tests
-# ---------------------------------------------------------------------------
-
-@pytest.fixture()
-def profile_env(tmp_path, monkeypatch):
-    """Set up an isolated environment for profile tests.
-
-    * Path.home() -> tmp_path  (so _get_profiles_root() = tmp_path/.hermes/profiles)
-    * HERMES_HOME  -> tmp_path/.hermes  (so get_hermes_home() agrees)
-    * Creates the bare-minimum ~/.hermes directory.
-    """
-    monkeypatch.setattr(Path, "home", lambda: tmp_path)
-    default_home = tmp_path / ".hermes"
-    default_home.mkdir(exist_ok=True)
-    monkeypatch.setenv("HERMES_HOME", str(default_home))
-    return tmp_path
-
-
-# ===================================================================
-# TestValidateProfileName
-# ===================================================================
-
-class TestValidateProfileName:
-    """Tests for validate_profile_name()."""
-
-    @pytest.mark.parametrize("name", ["coder", "work-bot", "a1", "my_agent"])
-    def test_valid_names_accepted(self, name):
-        # Should not raise
-        validate_profile_name(name)
-
-    @pytest.mark.parametrize("name", ["UPPER", "has space", ".hidden", "-leading"])
-    def test_invalid_names_rejected(self, name):
-        with pytest.raises(ValueError):
-            validate_profile_name(name)
-
-    def test_too_long_rejected(self):
-        long_name = "a" * 65
-        with pytest.raises(ValueError):
-            validate_profile_name(long_name)
-
-    def test_max_length_accepted(self):
-        # 64 chars total: 1 leading + 63 remaining = 64, within [0,63] range
-        name = "a" * 64
-        validate_profile_name(name)
-
-    def test_default_accepted(self):
-        # 'default' is a special-case pass-through
-        validate_profile_name("default")
-
-    def test_empty_string_rejected(self):
-        with pytest.raises(ValueError):
-            validate_profile_name("")
-
-
-# ===================================================================
-# TestGetProfileDir
-# ===================================================================
-
-class TestGetProfileDir:
-    """Tests for get_profile_dir()."""
-
-    def test_default_returns_hermes_home(self, profile_env):
-        tmp_path = profile_env
-        result = get_profile_dir("default")
-        assert result == tmp_path / ".hermes"
-
-    def test_named_profile_returns_profiles_subdir(self, profile_env):
-        tmp_path = profile_env
-        result = get_profile_dir("coder")
-        assert result == tmp_path / ".hermes" / "profiles" / "coder"
-
-
-# ===================================================================
-# TestCreateProfile
-# ===================================================================
-
-class TestCreateProfile:
-    """Tests for create_profile()."""
-
-    def test_creates_directory_with_subdirs(self, profile_env):
-        profile_dir = create_profile("coder", no_alias=True)
-        assert profile_dir.is_dir()
-        for subdir in ["memories", "sessions", "skills", "skins", "logs",
-                        "plans", "workspace", "cron"]:
-            assert (profile_dir / subdir).is_dir(), f"Missing subdir: {subdir}"
-
-    def test_duplicate_raises_file_exists(self, profile_env):
-        create_profile("coder", no_alias=True)
-        with pytest.raises(FileExistsError):
-            create_profile("coder", no_alias=True)
-
-    def test_default_raises_value_error(self, profile_env):
-        with pytest.raises(ValueError, match="default"):
-            create_profile("default", no_alias=True)
-
-    def test_invalid_name_raises_value_error(self, profile_env):
-        with pytest.raises(ValueError):
-            create_profile("INVALID!", no_alias=True)
-
-    def test_clone_config_copies_files(self, profile_env):
-        tmp_path = profile_env
-        default_home = tmp_path / ".hermes"
-        # Create source config files in default profile
-        (default_home / "config.yaml").write_text("model: test")
-        (default_home / ".env").write_text("KEY=val")
-        (default_home / "SOUL.md").write_text("Be helpful.")
-
-        profile_dir = create_profile("coder", clone_config=True, no_alias=True)
-
-        assert (profile_dir / "config.yaml").read_text() == "model: test"
-        assert (profile_dir / ".env").read_text() == "KEY=val"
-        assert (profile_dir / "SOUL.md").read_text() == "Be helpful."
-
-    def test_clone_all_copies_entire_tree(self, profile_env):
-        tmp_path = profile_env
-        default_home = tmp_path / ".hermes"
-        # Populate default with some content
-        (default_home / "memories").mkdir(exist_ok=True)
-        (default_home / "memories" / "note.md").write_text("remember this")
-        (default_home / "config.yaml").write_text("model: gpt-4")
-        # Runtime files that should be stripped
-        (default_home / "gateway.pid").write_text("12345")
-        (default_home / "gateway_state.json").write_text("{}")
-        (default_home / "processes.json").write_text("[]")
-
-        profile_dir = create_profile("coder", clone_all=True, no_alias=True)
-
-        # Content should be copied
-        assert (profile_dir / "memories" / "note.md").read_text() == "remember this"
-        assert (profile_dir / "config.yaml").read_text() == "model: gpt-4"
-        # Runtime files should be stripped
-        assert not (profile_dir / "gateway.pid").exists()
-        assert not (profile_dir / "gateway_state.json").exists()
-        assert not (profile_dir / "processes.json").exists()
-
-    def test_clone_config_missing_files_skipped(self, profile_env):
-        """Clone config gracefully skips files that don't exist in source."""
-        profile_dir = create_profile("coder", clone_config=True, no_alias=True)
-        # No error; optional files just not copied
-        assert not (profile_dir / "config.yaml").exists()
-        assert not (profile_dir / ".env").exists()
-        assert not (profile_dir / "SOUL.md").exists()
-
-
-# ===================================================================
-# TestDeleteProfile
-# ===================================================================
-
-class TestDeleteProfile:
-    """Tests for delete_profile()."""
-
-    def test_removes_directory(self, profile_env):
-        profile_dir = create_profile("coder", no_alias=True)
-        assert profile_dir.is_dir()
-        # Mock gateway import to avoid real systemd/launchd interaction
-        with patch("hermes_cli.profiles._cleanup_gateway_service"):
-            delete_profile("coder", yes=True)
-        assert not profile_dir.is_dir()
-
-    def test_default_raises_value_error(self, profile_env):
-        with pytest.raises(ValueError, match="default"):
-            delete_profile("default", yes=True)
-
-    def test_nonexistent_raises_file_not_found(self, profile_env):
-        with pytest.raises(FileNotFoundError):
-            delete_profile("nonexistent", yes=True)
-
-
-# ===================================================================
-# TestListProfiles
-# ===================================================================
-
-class TestListProfiles:
-    """Tests for list_profiles()."""
-
-    def test_returns_default_when_no_named_profiles(self, profile_env):
-        profiles = list_profiles()
-        names = [p.name for p in profiles]
-        assert "default" in names
-
-    def test_includes_named_profiles(self, profile_env):
-        create_profile("alpha", no_alias=True)
-        create_profile("beta", no_alias=True)
-        profiles = list_profiles()
-        names = [p.name for p in profiles]
-        assert "alpha" in names
-        assert "beta" in names
-
-    def test_sorted_alphabetically(self, profile_env):
-        create_profile("zebra", no_alias=True)
-        create_profile("alpha", no_alias=True)
-        create_profile("middle", no_alias=True)
-        profiles = list_profiles()
-        named = [p.name for p in profiles if not p.is_default]
-        assert named == sorted(named)
-
-    def test_default_is_first(self, profile_env):
-        create_profile("alpha", no_alias=True)
-        profiles = list_profiles()
-        assert profiles[0].name == "default"
-        assert profiles[0].is_default is True
-
-
-# ===================================================================
-# TestActiveProfile
-# ===================================================================
-
-class TestActiveProfile:
-    """Tests for set_active_profile() / get_active_profile()."""
-
-    def test_set_and_get_roundtrip(self, profile_env):
-        create_profile("coder", no_alias=True)
-        set_active_profile("coder")
-        assert get_active_profile() == "coder"
-
-    def test_no_file_returns_default(self, profile_env):
-        assert get_active_profile() == "default"
-
-    def test_empty_file_returns_default(self, profile_env):
-        tmp_path = profile_env
-        active_path = tmp_path / ".hermes" / "active_profile"
-        active_path.write_text("")
-        assert get_active_profile() == "default"
-
-    def test_set_to_default_removes_file(self, profile_env):
-        tmp_path = profile_env
-        create_profile("coder", no_alias=True)
-        set_active_profile("coder")
-        active_path = tmp_path / ".hermes" / "active_profile"
-        assert active_path.exists()
-
-        set_active_profile("default")
-        assert not active_path.exists()
-
-    def test_set_nonexistent_raises(self, profile_env):
-        with pytest.raises(FileNotFoundError):
-            set_active_profile("nonexistent")
-
-
-# ===================================================================
-# TestGetActiveProfileName
-# ===================================================================
-
-class TestGetActiveProfileName:
-    """Tests for get_active_profile_name()."""
-
-    def test_default_hermes_home_returns_default(self, profile_env):
-        # HERMES_HOME points to tmp_path/.hermes which is the default
-        assert get_active_profile_name() == "default"
-
-    def test_profile_path_returns_profile_name(self, profile_env, monkeypatch):
-        tmp_path = profile_env
-        create_profile("coder", no_alias=True)
-        profile_dir = tmp_path / ".hermes" / "profiles" / "coder"
-        monkeypatch.setenv("HERMES_HOME", str(profile_dir))
-        assert get_active_profile_name() == "coder"
-
-    def test_custom_path_returns_custom(self, profile_env, monkeypatch):
-        tmp_path = profile_env
-        custom = tmp_path / "some" / "other" / "path"
-        custom.mkdir(parents=True)
-        monkeypatch.setenv("HERMES_HOME", str(custom))
-        assert get_active_profile_name() == "custom"
-
-
-# ===================================================================
-# TestResolveProfileEnv
-# ===================================================================
-
-class TestResolveProfileEnv:
-    """Tests for resolve_profile_env()."""
-
-    def test_existing_profile_returns_path(self, profile_env):
-        tmp_path = profile_env
-        create_profile("coder", no_alias=True)
-        result = resolve_profile_env("coder")
-        assert result == str(tmp_path / ".hermes" / "profiles" / "coder")
-
-    def test_default_returns_default_home(self, profile_env):
-        tmp_path = profile_env
-        result = resolve_profile_env("default")
-        assert result == str(tmp_path / ".hermes")
-
-    def test_nonexistent_raises_file_not_found(self, profile_env):
-        with pytest.raises(FileNotFoundError):
-            resolve_profile_env("nonexistent")
-
-    def test_invalid_name_raises_value_error(self, profile_env):
-        with pytest.raises(ValueError):
-            resolve_profile_env("INVALID!")
-
-
-# ===================================================================
-# TestAliasCollision
-# ===================================================================
-
-class TestAliasCollision:
-    """Tests for check_alias_collision()."""
-
-    def test_normal_name_returns_none(self, profile_env):
-        # Mock 'which' to return not-found
-        with patch("subprocess.run") as mock_run:
-            mock_run.return_value = MagicMock(returncode=1, stdout="")
-            result = check_alias_collision("mybot")
-        assert result is None
-
-    def test_reserved_name_returns_message(self, profile_env):
-        result = check_alias_collision("hermes")
-        assert result is not None
-        assert "reserved" in result.lower()
-
-    def test_subcommand_returns_message(self, profile_env):
-        result = check_alias_collision("chat")
-        assert result is not None
-        assert "subcommand" in result.lower()
-
-    def test_default_is_reserved(self, profile_env):
-        result = check_alias_collision("default")
-        assert result is not None
-        assert "reserved" in result.lower()
-
-
-# ===================================================================
-# TestRenameProfile
-# ===================================================================
-
-class TestRenameProfile:
-    """Tests for rename_profile()."""
-
-    def test_renames_directory(self, profile_env):
-        tmp_path = profile_env
-        create_profile("oldname", no_alias=True)
-        old_dir = tmp_path / ".hermes" / "profiles" / "oldname"
-        assert old_dir.is_dir()
-
-        # Mock alias collision to avoid subprocess calls
-        with patch("hermes_cli.profiles.check_alias_collision", return_value="skip"):
-            new_dir = rename_profile("oldname", "newname")
-
-        assert not old_dir.is_dir()
-        assert new_dir.is_dir()
-        assert new_dir == tmp_path / ".hermes" / "profiles" / "newname"
-
-    def test_default_raises_value_error(self, profile_env):
-        with pytest.raises(ValueError, match="default"):
-            rename_profile("default", "newname")
-
-    def test_rename_to_default_raises_value_error(self, profile_env):
-        create_profile("coder", no_alias=True)
-        with pytest.raises(ValueError, match="default"):
-            rename_profile("coder", "default")
-
-    def test_nonexistent_raises_file_not_found(self, profile_env):
-        with pytest.raises(FileNotFoundError):
-            rename_profile("nonexistent", "newname")
-
-    def test_target_exists_raises_file_exists(self, profile_env):
-        create_profile("alpha", no_alias=True)
-        create_profile("beta", no_alias=True)
-        with pytest.raises(FileExistsError):
-            rename_profile("alpha", "beta")
-
-
-# ===================================================================
-# TestExportImport
-# ===================================================================
-
-class TestExportImport:
-    """Tests for export_profile() / import_profile()."""
-
-    def test_export_creates_tar_gz(self, profile_env, tmp_path):
-        create_profile("coder", no_alias=True)
-        # Put a marker file so we can verify content
-        profile_dir = get_profile_dir("coder")
-        (profile_dir / "marker.txt").write_text("hello")
-
-        output = tmp_path / "export" / "coder.tar.gz"
-        output.parent.mkdir(parents=True, exist_ok=True)
-        result = export_profile("coder", str(output))
-
-        assert Path(result).exists()
-        assert tarfile.is_tarfile(str(result))
-
-    def test_import_restores_from_archive(self, profile_env, tmp_path):
-        # Create and export a profile
-        create_profile("coder", no_alias=True)
-        profile_dir = get_profile_dir("coder")
-        (profile_dir / "marker.txt").write_text("hello")
-
-        archive_path = tmp_path / "export" / "coder.tar.gz"
-        archive_path.parent.mkdir(parents=True, exist_ok=True)
-        export_profile("coder", str(archive_path))
-
-        # Delete the profile, then import it back under a new name
-        import shutil
-        shutil.rmtree(profile_dir)
-        assert not profile_dir.is_dir()
-
-        imported = import_profile(str(archive_path), name="coder")
-        assert imported.is_dir()
-        assert (imported / "marker.txt").read_text() == "hello"
-
-    def test_import_to_existing_name_raises(self, profile_env, tmp_path):
-        create_profile("coder", no_alias=True)
-        profile_dir = get_profile_dir("coder")
-
-        archive_path = tmp_path / "export" / "coder.tar.gz"
-        archive_path.parent.mkdir(parents=True, exist_ok=True)
-        export_profile("coder", str(archive_path))
-
-        # Importing to same existing name should fail
-        with pytest.raises(FileExistsError):
-            import_profile(str(archive_path), name="coder")
-
-    def test_export_nonexistent_raises(self, profile_env, tmp_path):
-        with pytest.raises(FileNotFoundError):
-            export_profile("nonexistent", str(tmp_path / "out.tar.gz"))
-
-
-# ===================================================================
-# TestProfileIsolation
-# ===================================================================
-
-class TestProfileIsolation:
-    """Verify that two profiles have completely separate paths."""
-
-    def test_separate_config_paths(self, profile_env):
-        create_profile("alpha", no_alias=True)
-        create_profile("beta", no_alias=True)
-        alpha_dir = get_profile_dir("alpha")
-        beta_dir = get_profile_dir("beta")
-        assert alpha_dir / "config.yaml" != beta_dir / "config.yaml"
-        assert str(alpha_dir) not in str(beta_dir)
-
-    def test_separate_state_db_paths(self, profile_env):
-        alpha_dir = get_profile_dir("alpha")
-        beta_dir = get_profile_dir("beta")
-        assert alpha_dir / "state.db" != beta_dir / "state.db"
-
-    def test_separate_skills_paths(self, profile_env):
-        create_profile("alpha", no_alias=True)
-        create_profile("beta", no_alias=True)
-        alpha_dir = get_profile_dir("alpha")
-        beta_dir = get_profile_dir("beta")
-        assert alpha_dir / "skills" != beta_dir / "skills"
-        # Verify both exist and are independent dirs
-        assert (alpha_dir / "skills").is_dir()
-        assert (beta_dir / "skills").is_dir()
-
-
-# ===================================================================
-# TestCompletion
-# ===================================================================
-
-class TestCompletion:
-    """Tests for bash/zsh completion generators."""
-
-    def test_bash_completion_contains_complete(self):
-        script = generate_bash_completion()
-        assert len(script) > 0
-        assert "complete" in script
-
-    def test_zsh_completion_contains_compdef(self):
-        script = generate_zsh_completion()
-        assert len(script) > 0
-        assert "compdef" in script
-
-    def test_bash_completion_has_hermes_profiles_function(self):
-        script = generate_bash_completion()
-        assert "_hermes_profiles" in script
-
-    def test_zsh_completion_has_hermes_function(self):
-        script = generate_zsh_completion()
-        assert "_hermes" in script
-
-
-# ===================================================================
-# TestGetProfilesRoot / TestGetDefaultHermesHome (internal helpers)
-# ===================================================================
-
-class TestInternalHelpers:
-    """Tests for _get_profiles_root() and _get_default_hermes_home()."""
-
-    def test_profiles_root_under_home(self, profile_env):
-        tmp_path = profile_env
-        root = _get_profiles_root()
-        assert root == tmp_path / ".hermes" / "profiles"
-
-    def test_default_hermes_home(self, profile_env):
-        tmp_path = profile_env
-        home = _get_default_hermes_home()
-        assert home == tmp_path / ".hermes"
-
-
-# ===================================================================
-# Edge cases and additional coverage
-# ===================================================================
-
-class TestEdgeCases:
-    """Additional edge-case tests."""
-
-    def test_create_profile_returns_correct_path(self, profile_env):
-        tmp_path = profile_env
-        result = create_profile("mybot", no_alias=True)
-        expected = tmp_path / ".hermes" / "profiles" / "mybot"
-        assert result == expected
-
-    def test_list_profiles_default_info_fields(self, profile_env):
-        profiles = list_profiles()
-        default = [p for p in profiles if p.name == "default"][0]
-        assert default.is_default is True
-        assert default.gateway_running is False
-        assert default.skill_count == 0
-
-    def test_gateway_running_check_with_pid_file(self, profile_env):
-        """Verify _check_gateway_running reads pid file and probes os.kill."""
-        from hermes_cli.profiles import _check_gateway_running
-        tmp_path = profile_env
-        default_home = tmp_path / ".hermes"
-
-        # No pid file -> not running
-        assert _check_gateway_running(default_home) is False
-
-        # Write a PID file with a JSON payload
-        pid_file = default_home / "gateway.pid"
-        pid_file.write_text(json.dumps({"pid": 99999}))
-
-        # os.kill(99999, 0) should raise ProcessLookupError -> not running
-        assert _check_gateway_running(default_home) is False
-
-        # Mock os.kill to simulate a running process
-        with patch("os.kill", return_value=None):
-            assert _check_gateway_running(default_home) is True
-
-    def test_gateway_running_check_plain_pid(self, profile_env):
-        """Pid file containing just a number (legacy format)."""
-        from hermes_cli.profiles import _check_gateway_running
-        tmp_path = profile_env
-        default_home = tmp_path / ".hermes"
-        pid_file = default_home / "gateway.pid"
-        pid_file.write_text("99999")
-
-        with patch("os.kill", return_value=None):
-            assert _check_gateway_running(default_home) is True
-
-    def test_profile_name_boundary_single_char(self):
-        """Single alphanumeric character is valid."""
-        validate_profile_name("a")
-        validate_profile_name("1")
-
-    def test_profile_name_boundary_all_hyphens(self):
-        """Name starting with hyphen is invalid."""
-        with pytest.raises(ValueError):
-            validate_profile_name("-abc")
-
-    def test_profile_name_underscore_start(self):
-        """Name starting with underscore is invalid (must start with [a-z0-9])."""
-        with pytest.raises(ValueError):
-            validate_profile_name("_abc")
-
-    def test_clone_from_named_profile(self, profile_env):
-        """Clone config from a named (non-default) profile."""
-        tmp_path = profile_env
-        # Create source profile with config
-        source_dir = create_profile("source", no_alias=True)
-        (source_dir / "config.yaml").write_text("model: cloned")
-        (source_dir / ".env").write_text("SECRET=yes")
-
-        target_dir = create_profile(
-            "target", clone_from="source", clone_config=True, no_alias=True,
-        )
-        assert (target_dir / "config.yaml").read_text() == "model: cloned"
-        assert (target_dir / ".env").read_text() == "SECRET=yes"
-
-    def test_delete_clears_active_profile(self, profile_env):
-        """Deleting the active profile resets active to default."""
-        tmp_path = profile_env
-        create_profile("coder", no_alias=True)
-        set_active_profile("coder")
-        assert get_active_profile() == "coder"
-
-        with patch("hermes_cli.profiles._cleanup_gateway_service"):
-            delete_profile("coder", yes=True)
-
-        assert get_active_profile() == "default"

tests/hermes_cli/test_tool_token_estimation.py

@@ -1,271 +0,0 @@
-"""Tests for tool token estimation and curses_ui status_fn support."""
-
-from unittest.mock import patch
-
-import pytest
-
-
-# ─── Token Estimation Tests ──────────────────────────────────────────────────
-
-
-def test_estimate_tool_tokens_returns_positive_counts():
-    """_estimate_tool_tokens should return a non-empty dict with positive values."""
-    from hermes_cli.tools_config import _estimate_tool_tokens, _tool_token_cache
-
-    # Clear cache to force fresh computation
-    import hermes_cli.tools_config as tc
-    tc._tool_token_cache = None
-
-    tokens = _estimate_tool_tokens()
-
-    assert isinstance(tokens, dict)
-    assert len(tokens) > 0
-    for name, count in tokens.items():
-        assert isinstance(name, str)
-        assert isinstance(count, int)
-        assert count > 0, f"Tool {name} has non-positive token count: {count}"
-
-
-def test_estimate_tool_tokens_is_cached():
-    """Second call should return the same cached dict object."""
-    import hermes_cli.tools_config as tc
-    tc._tool_token_cache = None
-
-    first = tc._estimate_tool_tokens()
-    second = tc._estimate_tool_tokens()
-
-    assert first is second
-
-
-def test_estimate_tool_tokens_returns_empty_when_tiktoken_unavailable(monkeypatch):
-    """Graceful degradation when tiktoken cannot be imported."""
-    import hermes_cli.tools_config as tc
-    tc._tool_token_cache = None
-
-    import builtins
-    real_import = builtins.__import__
-
-    def mock_import(name, *args, **kwargs):
-        if name == "tiktoken":
-            raise ImportError("mocked")
-        return real_import(name, *args, **kwargs)
-
-    monkeypatch.setattr(builtins, "__import__", mock_import)
-
-    result = tc._estimate_tool_tokens()
-
-    assert result == {}
-
-    # Reset cache for other tests
-    tc._tool_token_cache = None
-
-
-def test_estimate_tool_tokens_covers_known_tools():
-    """Should include schemas for well-known tools like terminal, web_search."""
-    import hermes_cli.tools_config as tc
-    tc._tool_token_cache = None
-
-    tokens = tc._estimate_tool_tokens()
-
-    # These tools should always be discoverable
-    for expected in ("terminal", "web_search", "read_file"):
-        assert expected in tokens, f"Expected {expected!r} in token estimates"
-
-
-# ─── Status Function Tests ───────────────────────────────────────────────────
-
-
-def test_prompt_toolset_checklist_passes_status_fn(monkeypatch):
-    """_prompt_toolset_checklist should pass a status_fn to curses_checklist."""
-    import hermes_cli.tools_config as tc
-
-    captured_kwargs = {}
-
-    def fake_checklist(title, items, selected, *, cancel_returns=None, status_fn=None):
-        captured_kwargs["status_fn"] = status_fn
-        captured_kwargs["title"] = title
-        return selected  # Return pre-selected unchanged
-
-    monkeypatch.setattr("hermes_cli.curses_ui.curses_checklist", fake_checklist)
-
-    tc._prompt_toolset_checklist("CLI", {"web", "terminal"})
-
-    assert "status_fn" in captured_kwargs
-    # If tiktoken is available, status_fn should be set
-    tokens = tc._estimate_tool_tokens()
-    if tokens:
-        assert captured_kwargs["status_fn"] is not None
-
-
-def test_status_fn_returns_formatted_token_count(monkeypatch):
-    """The status_fn should return a human-readable token count string."""
-    import hermes_cli.tools_config as tc
-    from hermes_cli.tools_config import CONFIGURABLE_TOOLSETS
-
-    captured = {}
-
-    def fake_checklist(title, items, selected, *, cancel_returns=None, status_fn=None):
-        captured["status_fn"] = status_fn
-        return selected
-
-    monkeypatch.setattr("hermes_cli.curses_ui.curses_checklist", fake_checklist)
-
-    tc._prompt_toolset_checklist("CLI", {"web", "terminal"})
-
-    status_fn = captured.get("status_fn")
-    if status_fn is None:
-        pytest.skip("tiktoken unavailable; status_fn not created")
-
-    # Find the indices for web and terminal
-    idx_map = {ts_key: i for i, (ts_key, _, _) in enumerate(CONFIGURABLE_TOOLSETS)}
-
-    # Call status_fn with web + terminal selected
-    result = status_fn({idx_map["web"], idx_map["terminal"]})
-    assert "tokens" in result
-    assert "Est. tool context" in result
-
-
-def test_status_fn_deduplicates_overlapping_tools(monkeypatch):
-    """When toolsets overlap (browser includes web_search), tokens should not double-count."""
-    import hermes_cli.tools_config as tc
-    from hermes_cli.tools_config import CONFIGURABLE_TOOLSETS
-
-    captured = {}
-
-    def fake_checklist(title, items, selected, *, cancel_returns=None, status_fn=None):
-        captured["status_fn"] = status_fn
-        return selected
-
-    monkeypatch.setattr("hermes_cli.curses_ui.curses_checklist", fake_checklist)
-
-    tc._prompt_toolset_checklist("CLI", {"web"})
-
-    status_fn = captured.get("status_fn")
-    if status_fn is None:
-        pytest.skip("tiktoken unavailable; status_fn not created")
-
-    idx_map = {ts_key: i for i, (ts_key, _, _) in enumerate(CONFIGURABLE_TOOLSETS)}
-
-    # web alone
-    web_only = status_fn({idx_map["web"]})
-    # browser includes web_search, so browser + web should not double-count web_search
-    browser_only = status_fn({idx_map["browser"]})
-    both = status_fn({idx_map["web"], idx_map["browser"]})
-
-    # Extract numeric token counts from strings like "~8.3k tokens" or "~350 tokens"
-    import re
-
-    def parse_tokens(s):
-        m = re.search(r"~([\d.]+)k?\s+tokens", s)
-        if not m:
-            return 0
-        val = float(m.group(1))
-        if "k" in s[m.start():m.end()]:
-            val *= 1000
-        return val
-
-    web_tok = parse_tokens(web_only)
-    browser_tok = parse_tokens(browser_only)
-    both_tok = parse_tokens(both)
-
-    # Both together should be LESS than naive sum (due to web_search dedup)
-    naive_sum = web_tok + browser_tok
-    assert both_tok < naive_sum, (
-        f"Expected deduplication: web({web_tok}) + browser({browser_tok}) = {naive_sum} "
-        f"but combined = {both_tok}"
-    )
-
-
-def test_status_fn_empty_selection():
-    """Status function with no tools selected should return ~0 tokens."""
-    import hermes_cli.tools_config as tc
-
-    tc._tool_token_cache = None
-    tokens = tc._estimate_tool_tokens()
-    if not tokens:
-        pytest.skip("tiktoken unavailable")
-
-    from hermes_cli.tools_config import CONFIGURABLE_TOOLSETS
-    from toolsets import resolve_toolset
-
-    ts_keys = [ts_key for ts_key, _, _ in CONFIGURABLE_TOOLSETS]
-
-    def status_fn(chosen: set) -> str:
-        all_tools: set = set()
-        for idx in chosen:
-            all_tools.update(resolve_toolset(ts_keys[idx]))
-        total = sum(tokens.get(name, 0) for name in all_tools)
-        if total >= 1000:
-            return f"Est. tool context: ~{total / 1000:.1f}k tokens"
-        return f"Est. tool context: ~{total} tokens"
-
-    result = status_fn(set())
-    assert "~0 tokens" in result
-
-
-# ─── Curses UI Status Bar Tests ──────────────────────────────────────────────
-
-
-def test_curses_checklist_numbered_fallback_shows_status(monkeypatch, capsys):
-    """The numbered fallback should print the status_fn output."""
-    from hermes_cli.curses_ui import _numbered_fallback
-
-    def my_status(chosen):
-        return f"Selected {len(chosen)} items"
-
-    # Simulate user pressing Enter immediately (empty input → confirm)
-    monkeypatch.setattr("builtins.input", lambda _prompt="": "")
-
-    result = _numbered_fallback(
-        "Test title",
-        ["Item A", "Item B", "Item C"],
-        {0, 2},
-        {0, 2},
-        status_fn=my_status,
-    )
-
-    captured = capsys.readouterr()
-    assert "Selected 2 items" in captured.out
-    assert result == {0, 2}
-
-
-def test_curses_checklist_numbered_fallback_without_status(monkeypatch, capsys):
-    """The numbered fallback should work fine without status_fn."""
-    from hermes_cli.curses_ui import _numbered_fallback
-
-    monkeypatch.setattr("builtins.input", lambda _prompt="": "")
-
-    result = _numbered_fallback(
-        "Test title",
-        ["Item A", "Item B"],
-        {0},
-        {0},
-    )
-
-    captured = capsys.readouterr()
-    assert "Est. tool context" not in captured.out
-    assert result == {0}
-
-
-# ─── Registry get_schema Tests ───────────────────────────────────────────────
-
-
-def test_registry_get_schema_returns_schema():
-    """registry.get_schema() should return a tool's schema dict."""
-    from tools.registry import registry
-
-    # Import to trigger discovery
-    import model_tools  # noqa: F401
-
-    schema = registry.get_schema("terminal")
-    assert schema is not None
-    assert "name" in schema
-    assert schema["name"] == "terminal"
-    assert "parameters" in schema
-
-
-def test_registry_get_schema_returns_none_for_unknown():
-    """registry.get_schema() should return None for unknown tools."""
-    from tools.registry import registry
-
-    assert registry.get_schema("nonexistent_tool_xyz") is None

tests/keystore/test_categories.py

@@ -0,0 +1,46 @@
+"""Tests for keystore.categories — secret classification."""
+
+import pytest
+
+from keystore.categories import SecretCategory, default_category, DEFAULT_CATEGORIES
+
+
+class TestSecretCategory:
+    def test_enum_values(self):
+        assert SecretCategory.INJECTABLE.value == "injectable"
+        assert SecretCategory.GATED.value == "gated"
+        assert SecretCategory.SEALED.value == "sealed"
+        assert SecretCategory.USER_ONLY.value == "user_only"
+
+    def test_string_enum(self):
+        """SecretCategory is a str enum — can be compared as string."""
+        assert SecretCategory.INJECTABLE == "injectable"
+        assert SecretCategory.SEALED.value == "sealed"
+
+
+class TestDefaultCategory:
+    def test_known_injectable(self):
+        assert default_category("OPENROUTER_API_KEY") == SecretCategory.INJECTABLE
+        assert default_category("FAL_KEY") == SecretCategory.INJECTABLE
+        assert default_category("TELEGRAM_BOT_TOKEN") == SecretCategory.INJECTABLE
+
+    def test_known_gated(self):
+        assert default_category("GITHUB_TOKEN") == SecretCategory.GATED
+
+    def test_known_user_only(self):
+        assert default_category("SUDO_PASSWORD") == SecretCategory.USER_ONLY
+
+    def test_wallet_keys_always_sealed(self):
+        assert default_category("wallet:eth:0xABC") == SecretCategory.SEALED
+        assert default_category("wallet:sol:7xKL") == SecretCategory.SEALED
+        assert default_category("wallet:meta:0xABC") == SecretCategory.SEALED
+
+    def test_unknown_defaults_to_injectable(self):
+        """Unknown keys default to injectable for backward compatibility."""
+        assert default_category("SOME_RANDOM_KEY") == SecretCategory.INJECTABLE
+        assert default_category("MY_CUSTOM_TOKEN") == SecretCategory.INJECTABLE
+
+    def test_default_categories_dict_complete(self):
+        """All entries in DEFAULT_CATEGORIES should be valid SecretCategory values."""
+        for name, cat in DEFAULT_CATEGORIES.items():
+            assert isinstance(cat, SecretCategory), f"{name} has invalid category: {cat}"

tests/keystore/test_client.py

@@ -0,0 +1,197 @@
+"""Tests for keystore.client — high-level keystore API."""
+
+import os
+import tempfile
+from pathlib import Path
+from unittest.mock import patch, MagicMock
+
+import pytest
+
+nacl = pytest.importorskip("nacl")
+argon2 = pytest.importorskip("argon2")
+
+from keystore.client import KeystoreClient, reset_keystore
+from keystore.store import PassphraseMismatch, KeystoreLocked
+
+
+@pytest.fixture(autouse=True)
+def _reset_singleton():
+    """Reset the global singleton before each test."""
+    reset_keystore()
+    yield
+    reset_keystore()
+
+
+@pytest.fixture
+def ks(tmp_path):
+    """Return an initialized and unlocked KeystoreClient."""
+    db = tmp_path / "keystore" / "secrets.db"
+    client = KeystoreClient(db)
+    client.initialize("test-pass")
+    return client
+
+
+class TestEnsureUnlocked:
+    def test_already_unlocked(self, ks):
+        assert ks.ensure_unlocked() is True
+
+    def test_unlock_from_credential_store(self, ks, tmp_path):
+        ks.lock()
+        with patch("keystore.credential_store.retrieve_passphrase", return_value="test-pass"):
+            assert ks.ensure_unlocked(interactive=False) is True
+
+    def test_unlock_from_env_var(self, ks):
+        ks.lock()
+        with patch.dict(os.environ, {"HERMES_KEYSTORE_PASSPHRASE": "test-pass"}):
+            with patch("keystore.credential_store.retrieve_passphrase", return_value=None):
+                assert ks.ensure_unlocked(interactive=False) is True
+
+    def test_non_interactive_raises_when_locked(self, ks):
+        ks.lock()
+        with patch("keystore.credential_store.retrieve_passphrase", return_value=None):
+            with patch.dict(os.environ, {}, clear=False):
+                # Remove the env var if present
+                os.environ.pop("HERMES_KEYSTORE_PASSPHRASE", None)
+                with pytest.raises(KeystoreLocked):
+                    ks.ensure_unlocked(interactive=False)
+
+    def test_not_initialized_returns_false(self, tmp_path):
+        db = tmp_path / "ks2" / "secrets.db"
+        client = KeystoreClient(db)
+        assert client.ensure_unlocked(interactive=False) is False
+
+
+class TestInjectEnv:
+    def test_inject_populates_environ(self, ks):
+        ks.set_secret("TEST_INJECT_KEY_1", "value1")
+        ks.set_secret("TEST_INJECT_KEY_2", "value2")
+
+        # Clear any existing env vars
+        os.environ.pop("TEST_INJECT_KEY_1", None)
+        os.environ.pop("TEST_INJECT_KEY_2", None)
+
+        injected = ks.inject_env()
+        assert os.environ.get("TEST_INJECT_KEY_1") == "value1"
+        assert os.environ.get("TEST_INJECT_KEY_2") == "value2"
+        assert injected["TEST_INJECT_KEY_1"] is True
+        assert injected["TEST_INJECT_KEY_2"] is True
+
+        # Cleanup
+        os.environ.pop("TEST_INJECT_KEY_1", None)
+        os.environ.pop("TEST_INJECT_KEY_2", None)
+
+    def test_inject_does_not_overwrite_existing(self, ks):
+        ks.set_secret("TEST_INJECT_EXISTING", "from-keystore")
+        os.environ["TEST_INJECT_EXISTING"] = "from-shell"
+
+        injected = ks.inject_env()
+        assert os.environ["TEST_INJECT_EXISTING"] == "from-shell"
+        assert injected["TEST_INJECT_EXISTING"] is False
+
+        os.environ.pop("TEST_INJECT_EXISTING", None)
+
+    def test_inject_skips_non_injectable(self, ks):
+        ks.set_secret("SEALED_KEY", "secret", category="sealed")
+        ks.set_secret("USER_KEY", "secret", category="user_only")
+
+        os.environ.pop("SEALED_KEY", None)
+        os.environ.pop("USER_KEY", None)
+
+        injected = ks.inject_env()
+        assert "SEALED_KEY" not in injected
+        assert "USER_KEY" not in injected
+        assert "SEALED_KEY" not in os.environ
+        assert "USER_KEY" not in os.environ
+
+
+class TestMigrateFromEnv:
+    def test_migrate_basic(self, ks, tmp_path):
+        env_file = tmp_path / ".env"
+        env_file.write_text(
+            "# Comment line\n"
+            "OPENROUTER_API_KEY=sk-or-test-123\n"
+            "FAL_KEY=fal_test_456\n"
+            "SOME_CONFIG=not-a-secret\n"
+            "EMPTY_VAR=\n"
+        )
+        migrated = ks.migrate_from_env(env_file)
+        assert "OPENROUTER_API_KEY" in migrated
+        assert "FAL_KEY" in migrated
+        # Non-secret short values should be skipped
+        assert "EMPTY_VAR" not in migrated
+
+        # Verify values are stored correctly
+        assert ks.get_secret("OPENROUTER_API_KEY") == "sk-or-test-123"
+        assert ks.get_secret("FAL_KEY") == "fal_test_456"
+
+    def test_migrate_quoted_values(self, ks, tmp_path):
+        env_file = tmp_path / ".env"
+        env_file.write_text(
+            'MY_API_KEY="sk-quoted-value"\n'
+            "OTHER_TOKEN='single-quoted-value'\n"
+        )
+        migrated = ks.migrate_from_env(env_file)
+        assert ks.get_secret("MY_API_KEY") == "sk-quoted-value"
+        assert ks.get_secret("OTHER_TOKEN") == "single-quoted-value"
+
+    def test_migrate_nonexistent_file(self, ks, tmp_path):
+        migrated = ks.migrate_from_env(tmp_path / "nonexistent")
+        assert migrated == {}
+
+    def test_migrate_assigns_categories(self, ks, tmp_path):
+        env_file = tmp_path / ".env"
+        env_file.write_text(
+            "OPENROUTER_API_KEY=sk-test\n"
+            "SUDO_PASSWORD=mysudopass\n"
+            "GITHUB_TOKEN=ghp_test1234567890\n"
+        )
+        migrated = ks.migrate_from_env(env_file)
+        assert migrated.get("OPENROUTER_API_KEY") == "injectable"
+        assert migrated.get("SUDO_PASSWORD") == "user_only"
+        assert migrated.get("GITHUB_TOKEN") == "gated"
+
+
+class TestSecretManagement:
+    def test_set_and_get(self, ks):
+        ks.set_secret("MY_KEY", "my-value", description="Test key")
+        assert ks.get_secret("MY_KEY") == "my-value"
+
+    def test_delete(self, ks):
+        ks.set_secret("DEL_KEY", "val")
+        assert ks.delete_secret("DEL_KEY")
+        assert ks.get_secret("DEL_KEY") is None
+
+    def test_list(self, ks):
+        ks.set_secret("A", "1")
+        ks.set_secret("B", "2")
+        secrets = ks.list_secrets()
+        assert len(secrets) == 2
+
+    def test_set_category_validation(self, ks):
+        ks.set_secret("KEY", "val")
+        from keystore.store import KeystoreError
+        with pytest.raises(KeystoreError, match="Invalid category"):
+            ks.set_category("KEY", "bogus")
+
+
+class TestRememberForget:
+    def test_remember_no_backend(self, ks):
+        with patch("keystore.credential_store.is_available", return_value=False):
+            with patch("keystore.credential_store.backend_name", return_value=None):
+                success, msg = ks.remember_passphrase("test-pass")
+                assert not success
+                assert "No credential store" in msg
+
+    def test_remember_success(self, ks):
+        with patch("keystore.credential_store.is_available", return_value=True):
+            with patch("keystore.credential_store.backend_name", return_value="Test Backend"):
+                with patch("keystore.credential_store.store_passphrase", return_value=True):
+                    success, msg = ks.remember_passphrase("test-pass")
+                    assert success
+                    assert msg == "Test Backend"
+
+    def test_forget(self, ks):
+        with patch("keystore.credential_store.delete_passphrase", return_value=True):
+            with patch("keystore.credential_store.backend_name", return_value="Test"):
+                success, msg = ks.forget_passphrase()
+                assert success

tests/keystore/test_credential_store.py

@@ -0,0 +1,172 @@
+"""Tests for keystore.credential_store — cross-platform passphrase caching."""
+
+import os
+import platform
+from pathlib import Path
+from unittest.mock import patch, MagicMock
+
+import pytest
+
+from keystore.credential_store import (
+    _KeyringBackend,
+    _KeyctlBackend,
+    _EncryptedFileBackend,
+    _get_machine_id,
+    _detect_backend,
+    is_available,
+    backend_name,
+    store_passphrase,
+    retrieve_passphrase,
+    delete_passphrase,
+)
+
+
+# Reset cached backend between tests
+@pytest.fixture(autouse=True)
+def _reset_cache():
+    import keystore.credential_store as cs
+    cs._cached_backend = None
+    cs._detection_done = False
+    yield
+    cs._cached_backend = None
+    cs._detection_done = False
+
+
+class TestMachineId:
+    def test_returns_string(self):
+        mid = _get_machine_id()
+        assert isinstance(mid, str)
+        assert len(mid) > 0
+
+    def test_stable(self):
+        """Machine ID should be the same across calls."""
+        assert _get_machine_id() == _get_machine_id()
+
+
+class TestEncryptedFileBackend:
+    """Test the encrypted file fallback (always available with pynacl)."""
+
+    @pytest.fixture
+    def backend(self, tmp_path, monkeypatch):
+        monkeypatch.setenv("HERMES_HOME", str(tmp_path / ".hermes"))
+        return _EncryptedFileBackend()
+
+    @pytest.mark.skipif(
+        not pytest.importorskip("nacl", reason="pynacl not installed"),
+        reason="pynacl required",
+    )
+    def test_store_and_retrieve(self, backend):
+        assert backend.store("my-secret-passphrase")
+        assert backend.retrieve() == "my-secret-passphrase"
+
+    @pytest.mark.skipif(
+        not pytest.importorskip("nacl", reason="pynacl not installed"),
+        reason="pynacl required",
+    )
+    def test_delete(self, backend):
+        backend.store("passphrase")
+        assert backend.delete()
+        assert backend.retrieve() is None
+
+    @pytest.mark.skipif(
+        not pytest.importorskip("nacl", reason="pynacl not installed"),
+        reason="pynacl required",
+    )
+    def test_retrieve_nonexistent(self, backend):
+        assert backend.retrieve() is None
+
+    @pytest.mark.skipif(
+        not pytest.importorskip("nacl", reason="pynacl not installed"),
+        reason="pynacl required",
+    )
+    def test_overwrite(self, backend):
+        backend.store("first")
+        backend.store("second")
+        assert backend.retrieve() == "second"
+
+
+class TestKeyringBackend:
+    def test_wraps_keyring_module(self):
+        mock_kr = MagicMock()
+        # Create a real class to simulate a keyring backend
+        class FakeWinVault:
+            pass
+        FakeWinVault.__name__ = "WinVaultKeyring"
+        mock_kr.get_keyring.return_value = FakeWinVault()
+        backend = _KeyringBackend(mock_kr)
+        assert backend.name == "Windows Credential Locker"
+
+    def test_store_calls_set_password(self):
+        mock_kr = MagicMock()
+        mock_kr.get_keyring.return_value = MagicMock()
+        backend = _KeyringBackend(mock_kr)
+        backend.store("pass123")
+        mock_kr.set_password.assert_called_once()
+
+    def test_retrieve_calls_get_password(self):
+        mock_kr = MagicMock()
+        mock_kr.get_keyring.return_value = MagicMock()
+        mock_kr.get_password.return_value = "stored-pass"
+        backend = _KeyringBackend(mock_kr)
+        assert backend.retrieve() == "stored-pass"
+
+    def test_store_handles_exception(self):
+        mock_kr = MagicMock()
+        mock_kr.get_keyring.return_value = MagicMock()
+        mock_kr.set_password.side_effect = Exception("D-Bus error")
+        backend = _KeyringBackend(mock_kr)
+        assert backend.store("pass") is False
+
+
+class TestDetection:
+    def test_detect_with_no_backends(self):
+        """When keyring is unavailable and keyctl is missing, should fall back to encrypted file."""
+        with patch.dict("sys.modules", {"keyring": None}):
+            with patch("subprocess.run", side_effect=OSError("not found")):
+                # If pynacl is available, should get encrypted file backend
+                try:
+                    import nacl.secret  # noqa
+                    backend = _detect_backend()
+                    if backend is not None:
+                        assert isinstance(backend, _EncryptedFileBackend)
+                except ImportError:
+                    backend = _detect_backend()
+                    assert backend is None
+
+    def test_public_api_consistency(self):
+        """is_available and backend_name should agree."""
+        if is_available():
+            assert backend_name() is not None
+        else:
+            assert backend_name() is None
+
+
+class TestPublicAPI:
+    """Test the module-level public functions with mocked backend."""
+
+    def test_store_and_retrieve_with_mock(self):
+        import keystore.credential_store as cs
+        mock_backend = MagicMock()
+        mock_backend.store.return_value = True
+        mock_backend.retrieve.return_value = "cached-pass"
+        mock_backend.name = "Mock Backend"
+        cs._cached_backend = mock_backend
+        cs._detection_done = True
+
+        assert store_passphrase("my-pass") is True
+        mock_backend.store.assert_called_with("my-pass")
+
+        assert retrieve_passphrase() == "cached-pass"
+        assert backend_name() == "Mock Backend"
+        assert is_available() is True
+
+    def test_no_backend_returns_none(self):
+        import keystore.credential_store as cs
+        cs._cached_backend = None
+        cs._detection_done = True
+
+        assert store_passphrase("pass") is False
+        assert retrieve_passphrase() is None
+        assert delete_passphrase() is False
+        assert is_available() is False
+        assert backend_name() is None

tests/keystore/test_credential_store_security.py

@@ -0,0 +1,32 @@
+"""Security-focused tests for credential store behavior."""
+
+import importlib
+from unittest.mock import patch
+
+import pytest
+
+
+@pytest.fixture(autouse=True)
+def _reset_cache():
+    import keystore.credential_store as cs
+    cs._cached_backend = None
+    cs._detection_done = False
+    yield
+    cs._cached_backend = None
+    cs._detection_done = False
+
+
+def test_no_insecure_encrypted_file_auto_fallback_when_no_real_backend():
+    """If keyring/keyctl are unavailable, remember backend must be unavailable.
+
+    An automatically selected machine-derived encrypted file would be derivable
+    by the same-user agent process and would collapse the keystore boundary.
+    """
+    import keystore.credential_store as cs
+
+    with patch.dict("sys.modules", {"keyring": None}):
+        with patch("subprocess.run", side_effect=OSError("not found")):
+            importlib.reload(cs)
+            assert cs.backend_name() is None
+            assert cs.is_available() is False
+            assert cs.store_passphrase("secret") is False