docs(agent): verify edit-format steering against current Codex CLI + Claude Code source

Checked ~/agent-codebases (Codex @ 2026-05-30, Claude Code decompiled src):
- Codex: apply_patch is the only file-edit tool; apply_patch.lark is V4A;
  GPT-5.1/5.2(-codex) prompts mandate it; gated per-model via
  ModelInfo.apply_patch_tool_type. No str_replace editor in the repo.
- Claude Code: FileEditTool is old_string/new_string exact replacement with
  unique-match semantics — current Claude models train against str_replace
  in their first-party harness, not just the 2025 API text-editor tool.

agent/agent_runtime_helpers.py

@@ -679,15 +679,28 @@ def recover_with_credential_pool(
         # long-running TUI sessions stuck on stale tokens until the user
         # exited and reopened.
         is_entitlement = agent._is_entitlement_failure(error_context, status_code)
+        _auth_haystack = " ".join(
+            str(error_context.get(k) or "").lower()
+            for k in ("message", "reason", "code", "error")
+            if isinstance(error_context, dict)
+        )
+        if (
+            not is_entitlement
+            and status_code == 403
+            and "oauth authentication is currently not allowed for this organization" in _auth_haystack
+        ):
+            is_entitlement = True
+        if (
+            not is_entitlement
+            and status_code == 403
+            and (agent.provider or "") == "anthropic"
+            and getattr(agent, "api_mode", "") == "anthropic_messages"
+        ):
+            is_entitlement = True
         if not is_entitlement and status_code == 403 and (agent.provider or "") == "xai-oauth":
-            _disambiguator_haystack = " ".join(
-                str(error_context.get(k) or "").lower()
-                for k in ("message", "reason", "code", "error")
-                if isinstance(error_context, dict)
-            )
             _is_xai_auth_failure = (
-                "[wke=unauthenticated:" in _disambiguator_haystack
-                or "oauth2 access token could not be validated" in _disambiguator_haystack
+                "[wke=unauthenticated:" in _auth_haystack
+                or "oauth2 access token could not be validated" in _auth_haystack
             )
             if not _is_xai_auth_failure:
                 is_entitlement = True

agent/bedrock_adapter.py

@@ -208,6 +208,41 @@ def is_stale_connection_error(exc: BaseException) -> bool:
     return False
 
 
+def is_streaming_access_denied_error(exc: BaseException) -> bool:
+    """Return True when AWS denied the ``bedrock:InvokeModelWithResponseStream`` action.
+
+    IAM policies scoped to ``bedrock:InvokeModel`` only (a common least-privilege
+    setup) reject ``converse_stream()`` with an ``AccessDeniedException`` whose
+    message names the streaming action, e.g.::
+
+        User: arn:aws:iam::123456789012:user/x is not authorized to perform:
+        bedrock:InvokeModelWithResponseStream on resource: ...
+
+    This is permanent for the session — retrying the stream can never succeed —
+    so callers should flip to the non-streaming ``converse()`` path (which maps
+    to ``bedrock:InvokeModel``) instead of burning retries.
+
+    Detection is deliberately message-based: boto3 surfaces this as a
+    ``ClientError`` with ``Error.Code == "AccessDeniedException"``, and the
+    AnthropicBedrock SDK wraps the same AWS response in its own exception
+    types, but both preserve the action name in the message.
+    """
+    msg = str(exc).lower()
+    if "invokemodelwithresponsestream" not in msg:
+        return False
+    # ClientError with an explicit access-denied code is the canonical form.
+    try:
+        from botocore.exceptions import ClientError
+    except ImportError:  # pragma: no cover — botocore always present with boto3
+        ClientError = None  # type: ignore[assignment]
+    if ClientError is not None and isinstance(exc, ClientError):
+        code = (getattr(exc, "response", None) or {}).get("Error", {}).get("Code", "")
+        return code in ("AccessDeniedException", "UnauthorizedException")
+    # Wrapped forms (e.g. AnthropicBedrock SDK PermissionDeniedError) — match
+    # on the authorization-failure phrasing AWS uses.
+    return "not authorized" in msg or "accessdenied" in msg
+
+
 # ---------------------------------------------------------------------------
 # AWS credential detection
 # ---------------------------------------------------------------------------
@@ -1003,6 +1038,16 @@ def call_converse_stream(
     try:
         response = client.converse_stream(**kwargs)
     except Exception as exc:
+        if is_streaming_access_denied_error(exc):
+            # IAM allows bedrock:InvokeModel but not
+            # InvokeModelWithResponseStream — permanent for this session.
+            # Fall back to the non-streaming converse() path.
+            logger.info(
+                "bedrock: converse_stream denied by IAM on (region=%s, model=%s) — "
+                "falling back to non-streaming converse().",
+                region, model,
+            )
+            return normalize_converse_response(client.converse(**kwargs))
         if is_stale_connection_error(exc):
             logger.warning(
                 "bedrock: stale-connection error on converse_stream(region=%s, "

agent/chat_completion_helpers.py

@@ -1615,6 +1615,8 @@ def interruptible_streaming_api_call(agent, api_kwargs: dict, *, on_first_delta=
                     _get_bedrock_runtime_client,
                     invalidate_runtime_client,
                     is_stale_connection_error,
+                    is_streaming_access_denied_error,
+                    normalize_converse_response,
                     stream_converse_with_callbacks,
                 )
                 region = api_kwargs.pop("__bedrock_region__", "us-east-1")
@@ -1623,6 +1625,29 @@ def interruptible_streaming_api_call(agent, api_kwargs: dict, *, on_first_delta=
                 try:
                     raw_response = client.converse_stream(**api_kwargs)
                 except Exception as _bedrock_exc:
+                    # IAM policies scoped to bedrock:InvokeModel only (no
+                    # InvokeModelWithResponseStream) reject converse_stream()
+                    # with AccessDeniedException. That denial is permanent for
+                    # the session — fall back to the non-streaming converse()
+                    # inline (it maps to bedrock:InvokeModel) and disable
+                    # streaming for subsequent calls so we don't re-fail every
+                    # turn.
+                    if is_streaming_access_denied_error(_bedrock_exc):
+                        agent._disable_streaming = True
+                        agent._safe_print(
+                            "\n⚠  AWS IAM denied bedrock:InvokeModelWithResponseStream — "
+                            "falling back to non-streaming InvokeModel.\n"
+                            "   Grant that action to restore streaming output.\n"
+                        )
+                        logger.info(
+                            "bedrock: converse_stream denied by IAM (%s) — "
+                            "using non-streaming converse() for this session.",
+                            type(_bedrock_exc).__name__,
+                        )
+                        result["response"] = normalize_converse_response(
+                            client.converse(**api_kwargs)
+                        )
+                        return
                     # Evict the cached client on stale-connection failures
                     # so the outer retry loop builds a fresh client/pool.
                     if is_stale_connection_error(_bedrock_exc):
@@ -2424,9 +2449,34 @@ def interruptible_streaming_api_call(agent, api_kwargs: dict, *, on_first_delta=
                             "stream" in _err_lower
                             and "not supported" in _err_lower
                         )
-                        if _is_stream_unsupported:
+                        # AWS Bedrock (AnthropicBedrock SDK path): IAM policies
+                        # with bedrock:InvokeModel but not
+                        # InvokeModelWithResponseStream reject messages.stream()
+                        # with a permission error naming the streaming action.
+                        # Permanent for the session — flip to non-streaming
+                        # (messages.create() maps to bedrock:InvokeModel).
+                        _is_bedrock_stream_denied = False
+                        if (
+                            not _is_stream_unsupported
+                            and "invokemodelwithresponsestream" in _err_lower
+                        ):
+                            # Cheap message pre-check before importing the
+                            # adapter — bedrock_adapter triggers a lazy boto3
+                            # install at import time, which must not run for
+                            # unrelated providers' stream errors.
+                            from agent.bedrock_adapter import (
+                                is_streaming_access_denied_error,
+                            )
+                            _is_bedrock_stream_denied = (
+                                is_streaming_access_denied_error(e)
+                            )
+                        if _is_stream_unsupported or _is_bedrock_stream_denied:
                             agent._disable_streaming = True
                             agent._safe_print(
+                                "\n⚠  AWS IAM denied bedrock:InvokeModelWithResponseStream. "
+                                "Switching to non-streaming.\n"
+                                "   Grant that action to restore streaming output.\n"
+                                if _is_bedrock_stream_denied else
                                 "\n⚠  Streaming is not supported for this "
                                 "model/provider. Switching to non-streaming.\n"
                                 "   To avoid this delay, set display.streaming: false "

agent/coding_context.py

@@ -38,9 +38,10 @@ session (deferred), the same contract as ``/skills install`` vs ``--now``.
 
 Activation (config ``agent.coding_context``):
 
-  * ``auto`` (default) — posture (brief + snapshot) on an interactive coding
-    surface sitting in a code workspace (git repo or recognised project root).
-    Prompt-only; toolsets untouched.
+  * ``auto`` (default) — posture (brief + snapshot + names-only demotion of
+    non-coding skill categories) on an interactive coding surface sitting in
+    a code workspace (git repo or recognised project root). Prompt-only;
+    toolsets untouched, no skill is ever hidden.
   * ``focus`` — like ``auto``, but additionally collapses the toolset to the
     ``coding`` set + enabled MCP servers. Explicit opt-in for a lean schema.
   * ``on`` — force the posture anywhere (incl. non-workspaces). Prompt-only.
@@ -97,10 +98,26 @@ _GIT_TIMEOUT = 2.5
 
 
 # Per-model edit-format steering. Matching the edit tool format to how a model
-# was trained reduces mistakes and wasted reasoning (OpenAI/Codex handle
-# patch-style diffs best; Anthropic models — and most open-weight coding
-# models, whose RL scaffolds use str_replace-style editors — do best with
-# string-replacement). Our `patch` tool exposes both: mode="patch" (V4A
+# was trained reduces mistakes and wasted reasoning. Documented sources,
+# verified against current first-party agent source (May–Jun 2026):
+# - GPT/Codex → V4A patch: Codex CLI's ONLY file-edit tool is apply_patch and
+#   its grammar (codex-rs/core/src/tools/handlers/apply_patch.lark) is exactly
+#   the V4A format; the GPT-5.1/5.2(-codex) prompts instruct "Use the
+#   `apply_patch` tool to edit files", and OpenAI gates the tool per model via
+#   ModelInfo.apply_patch_tool_type. No str_replace editor exists in Codex.
+#   (Earlier doc: the GPT-4.1 prompting guide ships apply_patch/V4A —
+#   https://developers.openai.com/cookbook/examples/gpt4-1_prompting_guide)
+# - Claude → str_replace: Claude Code's FileEditTool is exact string
+#   replacement (old_string/new_string/replace_all, unique-match semantics) —
+#   current Claude models are RL'd against str_replace editing in their own
+#   first-party harness. Also Anthropic's API text-editor tool
+#   (`str_replace_based_edit_tool`) is schema-less: the schema is built into
+#   the model.
+#   https://platform.claude.com/docs/en/agents-and-tools/tool-use/text-editor-tool
+# - Open-weight coding models → str_replace: the dominant open RL/agentic
+#   scaffolds (SWE-agent, OpenHands ACI) use str_replace-style editors, and
+#   Qwen Code / Gemini CLI ship old_string/new_string `replace` tools.
+# Our `patch` tool exposes both: mode="patch" (V4A
 # multi-file) and mode="replace" (find-and-swap). We nudge each family toward
 # its native format. Unknown families get nothing (the brief's neutral wording
 # stands). Substrings match the model id; aligned with TOOL_USE_ENFORCEMENT_MODELS.
@@ -212,11 +229,13 @@ class ContextProfile:
     ``model_hint``   — routing preference key for smart model routing
                        (extension seam; not yet consumed by the router).
     ``memory_policy``— memory namespace/weighting hint (extension seam).
-    ``hidden_skill_categories`` — skill categories pruned from the system-prompt
-                       skill index while this posture is active. Discovery-only:
-                       nothing is disabled — ``skills_list`` still returns the
-                       full catalog and ``skill_view`` loads anything. Deny-list
-                       semantics so unknown/custom categories stay visible.
+    ``compact_skill_categories`` — skill categories DEMOTED to names-only in
+                       the system-prompt skill index while this posture is
+                       active. Never hidden: every skill name stays visible
+                       (so memory-anchored recall keeps working) — only the
+                       descriptions are dropped to cut index noise. Deny-list
+                       semantics so unknown/custom categories keep full
+                       entries.
     """
 
     name: str
@@ -224,14 +243,14 @@ class ContextProfile:
     guidance: str = ""
     model_hint: Optional[str] = None
     memory_policy: str = "default"
-    hidden_skill_categories: tuple[str, ...] = ()
+    compact_skill_categories: tuple[str, ...] = ()
 
 
-# Skill categories that are clearly not part of a coding workflow. Hidden from
-# the prompt's skill index in the coding posture (deny-list — anything not
-# listed here, incl. custom user categories, stays visible). Coding-adjacent
-# categories (devops, github, mcp, data-science, diagramming, research,
-# security, …) are intentionally absent.
+# Skill categories that are clearly not part of a coding workflow. Demoted to
+# names-only in the prompt's skill index while the coding posture is active
+# (deny-list — anything not listed here, incl. custom user categories, keeps
+# full entries). Coding-adjacent categories (devops, github, mcp,
+# data-science, diagramming, research, security, …) are intentionally absent.
 _NON_CODING_SKILL_CATEGORIES = (
     "apple", "communication", "cooking", "creative", "email", "finance",
     "gaming", "gifs", "health", "media", "music", "note-taking",
@@ -247,7 +266,7 @@ CODING_PROFILE = ContextProfile(
     guidance=CODING_AGENT_GUIDANCE,
     model_hint="coding",
     memory_policy="project",
-    hidden_skill_categories=_NON_CODING_SKILL_CATEGORIES,
+    compact_skill_categories=_NON_CODING_SKILL_CATEGORIES,
 )
 
 _PROFILES: dict[str, ContextProfile] = {
@@ -432,9 +451,20 @@ class RuntimeMode:
             blocks.append(workspace)
         return blocks
 
-    def hidden_skill_categories(self) -> frozenset[str]:
-        """Skill categories to prune from the prompt's skill index (may be empty)."""
-        return frozenset(self.profile.hidden_skill_categories)
+    def compact_skill_categories(self) -> frozenset[str]:
+        """Skill categories to demote to names-only in the prompt's skill index.
+
+        Demoted — never hidden. An earlier revision fully pruned these
+        categories from the index, which caused silent capability loss in a
+        real workflow: agent-created skills are the model's accumulated
+        project memory (server-ops runbooks, learned pitfalls, …), and models
+        do not reliably reach for ``skills_list`` to rediscover what the
+        index stopped showing them. Names-only keeps every skill loadable on
+        recall while still cutting the description noise from the index.
+        """
+        if not self.is_coding:
+            return frozenset()
+        return frozenset(self.profile.compact_skill_categories)
 
 
 def resolve_runtime_mode(
@@ -512,20 +542,21 @@ def coding_system_blocks(
     ).system_blocks()
 
 
-def coding_hidden_skill_categories(
+def coding_compact_skill_categories(
     *,
     platform: Optional[str] = None,
     cwd: Optional[str | Path] = None,
     config: Optional[dict[str, Any]] = None,
 ) -> frozenset[str]:
-    """Skill categories the active posture prunes from the prompt's skill index.
+    """Skill categories the active posture demotes to names-only in the index.
 
-    Empty outside the coding posture. Discovery-only: hidden skills remain
-    loadable via ``skills_list`` / ``skill_view``.
+    Empty outside the coding posture. Demoted — never hidden: every skill
+    name stays in the index and remains loadable via ``skill_view`` /
+    ``skills_list``; only descriptions are dropped.
     """
     return resolve_runtime_mode(
         platform=platform, cwd=cwd, config=config
-    ).hidden_skill_categories()
+    ).compact_skill_categories()
 
 
 def _enabled_mcp_servers(config: Optional[dict[str, Any]]) -> list[str]:
@@ -642,9 +673,9 @@ def _project_facts(root: Path) -> list[str]:
         deduped = list(dict.fromkeys(verify))[:_MAX_VERIFY_COMMANDS]
         facts.append(f"- Verify: {'; '.join(deduped)}")
 
-    context_files = [c for c in _CONTEXT_FILES if (root / c).is_file()]
-    if context_files:
-        facts.append(f"- Context files: {', '.join(context_files)}")
+    # Note: context files (AGENTS.md / CLAUDE.md / .cursorrules) are NOT listed
+    # here — their full contents are already injected into the system prompt as
+    # the Project Context block, so naming them again is redundant.
 
     return facts
 

agent/prompt_builder.py

@@ -1101,7 +1101,7 @@ def _skill_should_show(
 def build_skills_system_prompt(
     available_tools: "set[str] | None" = None,
     available_toolsets: "set[str] | None" = None,
-    hidden_categories: "frozenset[str] | None" = None,
+    compact_categories: "frozenset[str] | None" = None,
 ) -> str:
     """Build a compact skill index for the system prompt.
 
@@ -1117,11 +1117,11 @@ def build_skills_system_prompt(
     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.
 
-    ``hidden_categories`` (e.g. from the coding posture — see
-    agent/coding_context.py) prunes whole categories from the rendered index.
-    Discovery-only: the snapshot stores everything, ``skills_list`` /
-    ``skill_view`` still reach every skill, and a footer note tells the model
-    the full catalog exists.
+    ``compact_categories`` (e.g. from the coding posture — see
+    agent/coding_context.py) demotes whole categories to a names-only line in
+    the rendered index. Nothing is ever hidden: every skill name stays
+    visible and loadable via ``skill_view`` / ``skills_list``; only the
+    descriptions are dropped, and a footer note explains the demotion.
     """
     skills_dir = get_skills_dir()
     external_dirs = get_all_skills_dirs()[1:]  # skip local (index 0)
@@ -1146,7 +1146,7 @@ def build_skills_system_prompt(
         tuple(sorted(str(ts) for ts in (available_toolsets or set()))),
         _platform_hint,
         tuple(sorted(disabled)),
-        tuple(sorted(hidden_categories or ())),
+        tuple(sorted(compact_categories or ())),
     )
     with _SKILLS_PROMPT_CACHE_LOCK:
         cached = _SKILLS_PROMPT_CACHE.get(cache_key)
@@ -1280,38 +1280,44 @@ def build_skills_system_prompt(
             except Exception as e:
                 logger.debug("Could not read external skill description %s: %s", desc_file, e)
 
-    # Posture-driven category pruning (e.g. non-coding skills while pairing on
-    # code). Match on the top-level category segment so nested categories
-    # ("social-media/twitter") are pruned with their parent.
+    # Posture-driven category demotion (e.g. non-coding skills while pairing
+    # on code). Demoted categories stay in the index as a single names-only
+    # line — descriptions are dropped to cut noise, but every skill name
+    # remains visible so memory-anchored recall ("load <name>") keeps working.
+    # NEVER remove entries entirely: agent-created skills are the model's
+    # project memory, and models don't reach for skills_list to rediscover
+    # what the index stops showing them. Match on the top-level category
+    # segment so nested categories ("social-media/twitter") are demoted with
+    # their parent.
+    demoted = frozenset(
+        cat for cat in skills_by_category
+        if cat.split("/", 1)[0] in (compact_categories or frozenset())
+    )
+
     hidden_note = ""
-    if hidden_categories:
-        before = sum(len(v) for v in skills_by_category.values())
-        skills_by_category = {
-            cat: entries
-            for cat, entries in skills_by_category.items()
-            if cat.split("/", 1)[0] not in hidden_categories
-        }
-        pruned = before - sum(len(v) for v in skills_by_category.values())
-        if pruned:
-            hidden_note = (
-                f"\n(Note: {pruned} skill(s) in categories unrelated to the "
-                "current coding context are not listed here. The full catalog "
-                "is available via skills_list if the user asks for something "
-                "outside this list.)"
-            )
+    if demoted:
+        hidden_note = (
+            "\n(Categories marked [names only] are outside the current coding "
+            "context, so their descriptions are omitted — the skills work "
+            "normally and load with skill_view(name) as usual.)"
+        )
 
     if not skills_by_category:
         result = ""
     else:
         index_lines = []
         for category in sorted(skills_by_category.keys()):
+            # Deduplicate and sort skills within each category
+            seen = set()
+            if category in demoted:
+                names = sorted({name for name, _ in skills_by_category[category]})
+                index_lines.append(f"  {category} [names only]: {', '.join(names)}")
+                continue
             cat_desc = category_descriptions.get(category, "")
             if cat_desc:
                 index_lines.append(f"  {category}: {cat_desc}")
             else:
                 index_lines.append(f"  {category}:")
-            # Deduplicate and sort skills within each category
-            seen = set()
             for name, desc in sorted(skills_by_category[category], key=lambda x: x[0]):
                 if name in seen:
                     continue

agent/system_prompt.py

@@ -191,21 +191,22 @@ def build_system_prompt_parts(agent: Any, system_message: Optional[str] = None)
             )
             if toolset
         }
-        # Coding posture prunes non-coding skill categories from the index
-        # (discovery-only — skills_list/skill_view still reach everything).
-        _hidden_cats = frozenset()
+        # Coding posture demotes non-coding skill categories to names-only in
+        # the index (never hidden — skill_view/skills_list reach everything,
+        # and every name stays visible for memory-anchored recall).
+        _compact_cats = frozenset()
         try:
-            from agent.coding_context import coding_hidden_skill_categories
+            from agent.coding_context import coding_compact_skill_categories
 
-            _hidden_cats = coding_hidden_skill_categories(
+            _compact_cats = coding_compact_skill_categories(
                 platform=agent.platform, cwd=resolve_context_cwd()
             )
         except Exception:
-            _hidden_cats = frozenset()
+            _compact_cats = frozenset()
         skills_prompt = _r.build_skills_system_prompt(
             available_tools=agent.valid_tool_names,
             available_toolsets=avail_toolsets,
-            hidden_categories=_hidden_cats or None,
+            compact_categories=_compact_cats or None,
         )
     else:
         skills_prompt = ""

apps/desktop/electron/fs-read-dir.cjs

@@ -0,0 +1,109 @@
+'use strict'
+
+const fs = require('node:fs')
+const path = require('node:path')
+const { resolveDirectoryForIpc } = require('./hardening.cjs')
+
+const FS_READDIR_STAT_CONCURRENCY = 16
+
+// Always-hidden noise (covers non-git projects too; gitignore catches many of
+// these, but the project tree should keep the same hygiene without one).
+const FS_READDIR_HIDDEN = new Set([
+  '.git',
+  '.hg',
+  '.svn',
+  '.cache',
+  '.next',
+  '.turbo',
+  '.venv',
+  '__pycache__',
+  'build',
+  'dist',
+  'node_modules',
+  'target',
+  'venv'
+])
+
+function direntIsDirectory(dirent) {
+  return typeof dirent.isDirectory === 'function' && dirent.isDirectory()
+}
+
+function direntIsFile(dirent) {
+  return typeof dirent.isFile === 'function' && dirent.isFile()
+}
+
+function direntIsSymbolicLink(dirent) {
+  return typeof dirent.isSymbolicLink === 'function' && dirent.isSymbolicLink()
+}
+
+function shouldStatDirent(dirent) {
+  if (direntIsDirectory(dirent)) return false
+
+  return direntIsSymbolicLink(dirent) || !direntIsFile(dirent)
+}
+
+async function entryForDirent(dirent, resolved, fsImpl) {
+  const fullPath = path.join(resolved, dirent.name)
+  let isDirectory = direntIsDirectory(dirent)
+
+  if (!isDirectory && shouldStatDirent(dirent)) {
+    try {
+      isDirectory = (await fsImpl.promises.stat(fullPath)).isDirectory()
+    } catch {
+      isDirectory = false
+    }
+  }
+
+  return { name: dirent.name, path: fullPath, isDirectory }
+}
+
+async function mapWithStatConcurrency(items, mapper) {
+  const results = new Array(items.length)
+  let nextIndex = 0
+
+  async function runWorker() {
+    while (nextIndex < items.length) {
+      const index = nextIndex
+      nextIndex += 1
+      results[index] = await mapper(items[index])
+    }
+  }
+
+  const workerCount = Math.min(FS_READDIR_STAT_CONCURRENCY, items.length)
+  const workers = Array.from({ length: workerCount }, () => runWorker())
+  await Promise.all(workers)
+
+  return results
+}
+
+async function readDirForIpc(dirPath, options = {}) {
+  const fsImpl = options.fs || fs
+  let resolved
+
+  try {
+    ;({ resolvedPath: resolved } = await resolveDirectoryForIpc(dirPath, {
+      fs: fsImpl,
+      purpose: 'Directory read'
+    }))
+  } catch (error) {
+    return { entries: [], error: error?.code || 'read-error' }
+  }
+
+  try {
+    const dirents = await fsImpl.promises.readdir(resolved, { withFileTypes: true })
+    const visibleDirents = dirents.filter(dirent => !FS_READDIR_HIDDEN.has(dirent.name))
+    const entries = await mapWithStatConcurrency(visibleDirents, dirent =>
+      entryForDirent(dirent, resolved, fsImpl)
+    )
+
+    entries.sort((a, b) => Number(b.isDirectory) - Number(a.isDirectory) || a.name.localeCompare(b.name))
+
+    return { entries }
+  } catch (error) {
+    return { entries: [], error: error?.code || 'read-error' }
+  }
+}
+
+module.exports = {
+  readDirForIpc
+}

apps/desktop/electron/fs-read-dir.test.cjs

@@ -0,0 +1,364 @@
+'use strict'
+
+const assert = require('node:assert/strict')
+const fs = require('node:fs')
+const os = require('node:os')
+const path = require('node:path')
+const test = require('node:test')
+const { pathToFileURL } = require('node:url')
+
+const { readDirForIpc } = require('./fs-read-dir.cjs')
+
+function mkTmpDir() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'hermes-fs-read-dir-'))
+}
+
+function fakeDirent(name, flags = {}) {
+  return {
+    name,
+    isDirectory: () => Boolean(flags.directory),
+    isFile: () => Boolean(flags.file),
+    isSymbolicLink: () => Boolean(flags.symlink)
+  }
+}
+
+test('readDirForIpc hides noisy directories and files from the project tree', async () => {
+  const root = mkTmpDir()
+
+  try {
+    fs.mkdirSync(path.join(root, 'node_modules'))
+    fs.mkdirSync(path.join(root, 'src'))
+    fs.writeFileSync(path.join(root, 'target'), 'hidden file')
+    fs.writeFileSync(path.join(root, 'README.md'), 'visible file')
+
+    const result = await readDirForIpc(root)
+
+    assert.equal(result.error, undefined)
+    assert.deepEqual(
+      result.entries.map(entry => entry.name),
+      ['src', 'README.md']
+    )
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true })
+  }
+})
+
+test('readDirForIpc filters a hidden basename whether it is a file or directory', async () => {
+  const dirRoot = mkTmpDir()
+  const fileRoot = mkTmpDir()
+
+  try {
+    fs.mkdirSync(path.join(dirRoot, 'node_modules'))
+    fs.writeFileSync(path.join(dirRoot, 'visible.txt'), 'visible')
+    fs.writeFileSync(path.join(fileRoot, 'node_modules'), 'hidden file')
+    fs.writeFileSync(path.join(fileRoot, 'visible.txt'), 'visible')
+
+    assert.deepEqual(
+      (await readDirForIpc(dirRoot)).entries.map(entry => entry.name),
+      ['visible.txt']
+    )
+    assert.deepEqual(
+      (await readDirForIpc(fileRoot)).entries.map(entry => entry.name),
+      ['visible.txt']
+    )
+  } finally {
+    fs.rmSync(dirRoot, { recursive: true, force: true })
+    fs.rmSync(fileRoot, { recursive: true, force: true })
+  }
+})
+
+test('readDirForIpc returns directories before files and sorts by name within groups', async () => {
+  const root = mkTmpDir()
+
+  try {
+    fs.writeFileSync(path.join(root, 'z.txt'), 'z')
+    fs.mkdirSync(path.join(root, 'src'))
+    fs.writeFileSync(path.join(root, 'a.txt'), 'a')
+    fs.mkdirSync(path.join(root, 'lib'))
+
+    const result = await readDirForIpc(root)
+
+    assert.equal(result.error, undefined)
+    assert.deepEqual(
+      result.entries.map(entry => entry.name),
+      ['lib', 'src', 'a.txt', 'z.txt']
+    )
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true })
+  }
+})
+
+test('readDirForIpc accepts file URLs for directories', async () => {
+  const root = mkTmpDir()
+
+  try {
+    fs.mkdirSync(path.join(root, 'src'))
+    fs.writeFileSync(path.join(root, 'README.md'), 'visible file')
+
+    const result = await readDirForIpc(pathToFileURL(root).toString())
+
+    assert.equal(result.error, undefined)
+    assert.deepEqual(
+      result.entries.map(entry => entry.name),
+      ['src', 'README.md']
+    )
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true })
+  }
+})
+
+test('readDirForIpc returns invalid-path for blank or non-string input', async () => {
+  let readdirCalls = 0
+  const fsImpl = {
+    promises: {
+      readdir: async () => {
+        readdirCalls += 1
+        return []
+      }
+    }
+  }
+
+  assert.deepEqual(await readDirForIpc('', { fs: fsImpl }), { entries: [], error: 'invalid-path' })
+  assert.deepEqual(await readDirForIpc('   ', { fs: fsImpl }), { entries: [], error: 'invalid-path' })
+  assert.deepEqual(await readDirForIpc(null, { fs: fsImpl }), { entries: [], error: 'invalid-path' })
+  assert.equal(readdirCalls, 0)
+})
+
+test('readDirForIpc rejects Windows device paths before readdir', async () => {
+  let readdirCalls = 0
+  const fsImpl = {
+    promises: {
+      readdir: async () => {
+        readdirCalls += 1
+        return []
+      }
+    }
+  }
+
+  assert.deepEqual(await readDirForIpc('\\\\?\\C:\\secret', { fs: fsImpl }), {
+    entries: [],
+    error: 'device-path'
+  })
+  assert.equal(readdirCalls, 0)
+})
+
+test('readDirForIpc returns filesystem error codes instead of throwing', async () => {
+  const root = mkTmpDir()
+
+  try {
+    const result = await readDirForIpc(path.join(root, 'missing'))
+
+    assert.deepEqual(result, { entries: [], error: 'ENOENT' })
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true })
+  }
+})
+
+test('readDirForIpc marks a symlink to a directory as a directory', async t => {
+  const root = mkTmpDir()
+
+  try {
+    fs.mkdirSync(path.join(root, 'actual-dir'))
+
+    try {
+      fs.symlinkSync(path.join(root, 'actual-dir'), path.join(root, 'linked-dir'), 'dir')
+    } catch (error) {
+      if (error?.code === 'EPERM' || error?.code === 'EACCES') {
+        t.skip(`symlink creation is not permitted on this platform (${error.code})`)
+
+        return
+      }
+
+      throw error
+    }
+
+    const result = await readDirForIpc(root)
+    const linked = result.entries.find(entry => entry.name === 'linked-dir')
+
+    assert.equal(result.error, undefined)
+    assert.equal(linked?.isDirectory, true)
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true })
+  }
+})
+
+test('readDirForIpc marks a Windows junction to a directory as a directory', async t => {
+  if (process.platform !== 'win32') {
+    t.skip('junctions are a Windows-specific symlink type')
+
+    return
+  }
+
+  const root = mkTmpDir()
+
+  try {
+    fs.mkdirSync(path.join(root, 'actual-dir'))
+
+    try {
+      fs.symlinkSync(path.join(root, 'actual-dir'), path.join(root, 'junction-dir'), 'junction')
+    } catch (error) {
+      if (error?.code === 'EPERM' || error?.code === 'EACCES') {
+        t.skip(`junction creation is not permitted on this platform (${error.code})`)
+
+        return
+      }
+
+      throw error
+    }
+
+    const result = await readDirForIpc(root)
+    const junction = result.entries.find(entry => entry.name === 'junction-dir')
+
+    assert.equal(result.error, undefined)
+    assert.equal(junction?.isDirectory, true)
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true })
+  }
+})
+
+test('readDirForIpc allows expanding symlink or junction directories outside the project root', async t => {
+  const root = mkTmpDir()
+  const outside = mkTmpDir()
+
+  try {
+    fs.writeFileSync(path.join(outside, 'outside.txt'), 'ok')
+
+    const linkPath = path.join(root, 'outside-link')
+    try {
+      fs.symlinkSync(outside, linkPath, process.platform === 'win32' ? 'junction' : 'dir')
+    } catch (error) {
+      if (error?.code === 'EPERM' || error?.code === 'EACCES') {
+        t.skip(`directory symlink creation is not permitted on this platform (${error.code})`)
+
+        return
+      }
+
+      throw error
+    }
+
+    const result = await readDirForIpc(linkPath)
+
+    assert.equal(result.error, undefined)
+    assert.deepEqual(result.entries, [
+      { name: 'outside.txt', path: path.join(linkPath, 'outside.txt'), isDirectory: false }
+    ])
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true })
+    fs.rmSync(outside, { recursive: true, force: true })
+  }
+})
+
+test('readDirForIpc stats symbolic links and unknown entries without dropping the whole listing', async () => {
+  const input = path.join('virtual-root')
+  const resolved = path.resolve(input)
+  const statCalls = []
+  const fsImpl = {
+    promises: {
+      readdir: async () => [
+        fakeDirent('unknown-entry'),
+        fakeDirent('linked-dir', { symlink: true }),
+        fakeDirent('broken-link', { symlink: true }),
+        fakeDirent('plain.txt', { file: true })
+      ],
+      stat: async fullPath => {
+        if (fullPath === resolved) {
+          return { isDirectory: () => true }
+        }
+
+        statCalls.push(fullPath)
+        if (fullPath.endsWith(`${path.sep}linked-dir`)) {
+          return { isDirectory: () => true }
+        }
+        throw Object.assign(new Error('gone'), { code: 'ENOENT' })
+      }
+    }
+  }
+
+  const result = await readDirForIpc(input, { fs: fsImpl })
+
+  assert.equal(result.error, undefined)
+  assert.deepEqual(
+    statCalls.sort(),
+    [path.join(resolved, 'broken-link'), path.join(resolved, 'linked-dir'), path.join(resolved, 'unknown-entry')].sort()
+  )
+  assert.deepEqual(result.entries, [
+    { name: 'linked-dir', path: path.join(resolved, 'linked-dir'), isDirectory: true },
+    { name: 'broken-link', path: path.join(resolved, 'broken-link'), isDirectory: false },
+    { name: 'plain.txt', path: path.join(resolved, 'plain.txt'), isDirectory: false },
+    { name: 'unknown-entry', path: path.join(resolved, 'unknown-entry'), isDirectory: false }
+  ])
+})
+
+test('readDirForIpc bounds concurrent stats while preserving complete sorted output', async () => {
+  const input = path.join('virtual-root')
+  const resolved = path.resolve(input)
+  const names = Array.from({ length: 105 }, (_, index) => `entry-${String(104 - index).padStart(3, '0')}`)
+  const failedName = 'entry-100'
+  const directoryNames = new Set(names.filter((_, index) => index % 10 === 4))
+  const successfulDirectoryNames = new Set([...directoryNames].filter(name => name !== failedName))
+  const statCalls = []
+  let active = 0
+  let peak = 0
+  let releaseStats
+  let markFirstStatStarted
+  const statsReleased = new Promise(resolve => {
+    releaseStats = resolve
+  })
+  const firstStatStarted = new Promise(resolve => {
+    markFirstStatStarted = resolve
+  })
+  const fsImpl = {
+    promises: {
+      readdir: async () => [
+        fakeDirent('node_modules', { symlink: true }),
+        ...names.map((name, index) => fakeDirent(name, { symlink: index % 2 === 0 }))
+      ],
+      stat: async fullPath => {
+        if (fullPath === resolved) {
+          return { isDirectory: () => true }
+        }
+
+        statCalls.push(fullPath)
+        active += 1
+        peak = Math.max(peak, active)
+        markFirstStatStarted()
+        await statsReleased
+        active -= 1
+
+        const name = path.basename(fullPath)
+        if (name === failedName) {
+          throw Object.assign(new Error('gone'), { code: 'ENOENT' })
+        }
+
+        return { isDirectory: () => successfulDirectoryNames.has(name) }
+      }
+    }
+  }
+
+  const resultPromise = readDirForIpc(input, { fs: fsImpl })
+  await firstStatStarted
+  await new Promise(resolve => setImmediate(resolve))
+  releaseStats()
+  const result = await resultPromise
+
+  const expectedNames = [
+    ...names.filter(name => successfulDirectoryNames.has(name)).sort(),
+    ...names.filter(name => !successfulDirectoryNames.has(name)).sort()
+  ]
+
+  assert.equal(result.error, undefined)
+  assert.equal(result.entries.length, names.length)
+  assert.equal(statCalls.length, names.length)
+  assert.equal(statCalls.some(fullPath => fullPath.endsWith(`${path.sep}node_modules`)), false)
+  assert.ok(peak > 1, `expected concurrent stats, observed peak ${peak}`)
+  assert.ok(peak <= 16, `expected at most 16 concurrent stats, observed peak ${peak}`)
+  assert.deepEqual(
+    result.entries.map(entry => entry.name),
+    expectedNames
+  )
+  assert.equal(result.entries.find(entry => entry.name === failedName)?.isDirectory, false)
+  assert.equal(
+    result.entries.filter(entry => entry.isDirectory).length,
+    successfulDirectoryNames.size
+  )
+})

apps/desktop/electron/git-root.cjs

@@ -0,0 +1,54 @@
+'use strict'
+
+const fs = require('node:fs')
+const path = require('node:path')
+const { resolveRequestedPathForIpc } = require('./hardening.cjs')
+
+function findGitRoot(start, fsImpl = fs) {
+  let dir = start
+
+  for (let i = 0; i < 50; i += 1) {
+    try {
+      if (fsImpl.existsSync(path.join(dir, '.git'))) {
+        return dir
+      }
+    } catch {
+      return null
+    }
+
+    const parent = path.dirname(dir)
+
+    if (parent === dir) {
+      return null
+    }
+
+    dir = parent
+  }
+
+  return null
+}
+
+async function gitRootForIpc(startPath, options = {}) {
+  const fsImpl = options.fs || fs
+  let resolved
+
+  try {
+    resolved = resolveRequestedPathForIpc(startPath, { purpose: 'Git root' })
+  } catch {
+    return null
+  }
+
+  try {
+    const stat = await fsImpl.promises.stat(resolved)
+    const start = stat.isDirectory() ? resolved : path.dirname(resolved)
+
+    return findGitRoot(start, fsImpl)
+  } catch {
+    return findGitRoot(resolved, fsImpl)
+  }
+}
+
+module.exports = {
+  findGitRoot,
+  gitRootForIpc
+}

apps/desktop/electron/git-root.test.cjs

@@ -0,0 +1,40 @@
+'use strict'
+
+const assert = require('node:assert/strict')
+const fs = require('node:fs')
+const os = require('node:os')
+const path = require('node:path')
+const test = require('node:test')
+const { pathToFileURL } = require('node:url')
+
+const { gitRootForIpc } = require('./git-root.cjs')
+
+function mkTmpDir() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'hermes-git-root-'))
+}
+
+test('gitRootForIpc returns null for invalid and device paths', async () => {
+  assert.equal(await gitRootForIpc(''), null)
+  assert.equal(await gitRootForIpc('   '), null)
+  assert.equal(await gitRootForIpc(null), null)
+  assert.equal(await gitRootForIpc('\\\\?\\C:\\secret'), null)
+  assert.equal(await gitRootForIpc('file:///%E0%A4%A'), null)
+})
+
+test('gitRootForIpc resolves directories files missing descendants and file URLs', async t => {
+  const root = mkTmpDir()
+  t.after(() => fs.rmSync(root, { recursive: true, force: true }))
+
+  const gitDir = path.join(root, '.git')
+  const srcDir = path.join(root, 'src')
+  const filePath = path.join(srcDir, 'index.ts')
+  fs.mkdirSync(gitDir)
+  fs.mkdirSync(srcDir)
+  fs.writeFileSync(filePath, 'export {}\n', 'utf8')
+
+  assert.equal(await gitRootForIpc(root), root)
+  assert.equal(await gitRootForIpc(srcDir), root)
+  assert.equal(await gitRootForIpc(filePath), root)
+  assert.equal(await gitRootForIpc(pathToFileURL(filePath).toString()), root)
+  assert.equal(await gitRootForIpc(path.join(srcDir, 'missing.ts')), root)
+})

apps/desktop/electron/hardening.cjs

@@ -106,71 +106,155 @@ function sensitiveFileBlockReason(filePath) {
   return null
 }
 
-function resolveRequestedFilePath(filePath, baseDir = process.cwd(), purpose = 'File read') {
-  const raw = String(filePath || '').trim()
+function ipcPathError(code, message) {
+  const error = new Error(message)
+  error.code = code
+  return error
+}
+
+function rejectUnsafePathSyntax(filePath, purpose = 'File read') {
+  if (typeof filePath !== 'string') {
+    throw ipcPathError('invalid-path', `${purpose} failed: file path is required.`)
+  }
+
+  const raw = filePath.trim()
 
   if (!raw) {
-    throw new Error(`${purpose} failed: file path is required.`)
+    throw ipcPathError('invalid-path', `${purpose} failed: file path is required.`)
   }
 
   if (raw.includes('\0')) {
-    throw new Error(`${purpose} failed: file path is invalid.`)
+    throw ipcPathError('invalid-path', `${purpose} failed: file path is invalid.`)
   }
 
+  const normalized = raw.replace(/\\/g, '/').toLowerCase()
+  if (
+    normalized.startsWith('//?/') ||
+    normalized.startsWith('//./') ||
+    normalized.startsWith('globalroot/device/') ||
+    normalized.includes('/globalroot/device/')
+  ) {
+    throw ipcPathError('device-path', `${purpose} blocked: Windows device paths are not allowed.`)
+  }
+
+  return raw
+}
+
+function resolveRequestedPathForIpc(filePath, options = {}) {
+  const purpose = String(options.purpose || 'File read')
+  const raw = rejectUnsafePathSyntax(filePath, purpose)
+
   if (/^file:/i.test(raw)) {
+    let resolvedPath
     try {
-      return fileURLToPath(raw)
+      const parsed = new URL(raw)
+      if (parsed.protocol !== 'file:') {
+        throw new Error('not a file URL')
+      }
+      resolvedPath = fileURLToPath(parsed)
     } catch {
-      throw new Error(`${purpose} failed: file URL is invalid.`)
+      throw ipcPathError('invalid-path', `${purpose} failed: file URL is invalid.`)
     }
+
+    rejectUnsafePathSyntax(resolvedPath, purpose)
+    return path.resolve(resolvedPath)
   }
 
-  const resolvedBase = path.resolve(String(baseDir || process.cwd()))
-  return path.resolve(resolvedBase, raw)
+  const baseInput = typeof options.baseDir === 'string' && options.baseDir.trim() ? options.baseDir : process.cwd()
+  const safeBaseInput = rejectUnsafePathSyntax(baseInput, purpose)
+  const resolvedBase = path.resolve(safeBaseInput)
+  rejectUnsafePathSyntax(resolvedBase, purpose)
+  const resolvedPath = path.resolve(resolvedBase, raw)
+  rejectUnsafePathSyntax(resolvedPath, purpose)
+
+  return resolvedPath
+}
+
+async function statForIpc(fsImpl, resolvedPath, purpose, typeLabel) {
+  try {
+    return await fsImpl.promises.stat(resolvedPath)
+  } catch (error) {
+    const code = error && typeof error === 'object' ? error.code : ''
+    if (code === 'ENOENT' || code === 'ENOTDIR') {
+      throw ipcPathError(code || 'ENOENT', `${purpose} failed: ${typeLabel} does not exist.`)
+    }
+    throw ipcPathError(code || 'read-error', `${purpose} failed: ${error instanceof Error ? error.message : String(error)}`)
+  }
+}
+
+async function realpathForIpc(fsImpl, resolvedPath, purpose) {
+  if (typeof fsImpl.promises.realpath !== 'function') {
+    return resolvedPath
+  }
+
+  try {
+    const realPath = await fsImpl.promises.realpath(resolvedPath)
+    rejectUnsafePathSyntax(realPath, purpose)
+    return realPath
+  } catch (error) {
+    const code = error && typeof error === 'object' ? error.code : ''
+    throw ipcPathError(code || 'read-error', `${purpose} failed: ${error instanceof Error ? error.message : String(error)}`)
+  }
+}
+
+function rejectSensitiveFilePath(filePath, purpose) {
+  const blockReason = sensitiveFileBlockReason(filePath)
+  if (blockReason) {
+    throw ipcPathError('sensitive-file', `${purpose} blocked for sensitive file: ${blockReason}`)
+  }
+}
+
+async function resolveDirectoryForIpc(dirPath, options = {}) {
+  const purpose = String(options.purpose || 'Directory read')
+  const fsImpl = options.fs || fs
+  const resolvedPath = resolveRequestedPathForIpc(dirPath, { baseDir: options.baseDir, purpose })
+  const stat = await statForIpc(fsImpl, resolvedPath, purpose, 'directory')
+
+  if (!stat.isDirectory()) {
+    throw ipcPathError('ENOTDIR', `${purpose} failed: path is not a directory.`)
+  }
+
+  const realPath = await realpathForIpc(fsImpl, resolvedPath, purpose)
+
+  return { realPath, resolvedPath, stat }
 }
 
 async function resolveReadableFileForIpc(filePath, options = {}) {
   const purpose = String(options.purpose || 'File read')
-  const resolvedPath = resolveRequestedFilePath(filePath, options.baseDir, purpose)
+  const fsImpl = options.fs || fs
+  const resolvedPath = resolveRequestedPathForIpc(filePath, { baseDir: options.baseDir, purpose })
 
   if (options.blockSensitive !== false) {
-    const blockReason = sensitiveFileBlockReason(resolvedPath)
-    if (blockReason) {
-      throw new Error(`${purpose} blocked for sensitive file: ${blockReason}`)
-    }
+    rejectSensitiveFilePath(resolvedPath, purpose)
   }
 
-  let stat
-  try {
-    stat = await fs.promises.stat(resolvedPath)
-  } catch (error) {
-    const code = error && typeof error === 'object' ? error.code : ''
-    if (code === 'ENOENT' || code === 'ENOTDIR') {
-      throw new Error(`${purpose} failed: file does not exist.`)
-    }
-    throw new Error(`${purpose} failed: ${error instanceof Error ? error.message : String(error)}`)
-  }
+  const stat = await statForIpc(fsImpl, resolvedPath, purpose, 'file')
 
   if (stat.isDirectory()) {
-    throw new Error(`${purpose} failed: path points to a directory.`)
+    throw ipcPathError('EISDIR', `${purpose} failed: path points to a directory.`)
   }
 
   if (!stat.isFile()) {
-    throw new Error(`${purpose} failed: only regular files can be read.`)
+    throw ipcPathError('EINVAL', `${purpose} failed: only regular files can be read.`)
+  }
+
+  const realPath = await realpathForIpc(fsImpl, resolvedPath, purpose)
+  if (options.blockSensitive !== false) {
+    rejectSensitiveFilePath(realPath, purpose)
   }
 
   const maxBytes = Number.isFinite(options.maxBytes) && Number(options.maxBytes) > 0 ? Number(options.maxBytes) : null
   if (maxBytes && stat.size > maxBytes) {
-    throw new Error(`${purpose} failed: file is too large (${stat.size} bytes; limit ${maxBytes} bytes).`)
+    throw ipcPathError('EFBIG', `${purpose} failed: file is too large (${stat.size} bytes; limit ${maxBytes} bytes).`)
   }
 
   try {
-    await fs.promises.access(resolvedPath, fs.constants.R_OK)
+    await fsImpl.promises.access(resolvedPath, fs.constants.R_OK)
   } catch {
-    throw new Error(`${purpose} failed: file is not readable.`)
+    throw ipcPathError('EACCES', `${purpose} failed: file is not readable.`)
   }
 
-  return { resolvedPath, stat }
+  return { realPath, resolvedPath, stat }
 }
 
 module.exports = {
@@ -178,7 +262,10 @@ module.exports = {
   DEFAULT_FETCH_TIMEOUT_MS,
   TEXT_PREVIEW_SOURCE_MAX_BYTES,
   encryptDesktopSecret,
+  rejectUnsafePathSyntax,
+  resolveDirectoryForIpc,
   resolveReadableFileForIpc,
+  resolveRequestedPathForIpc,
   resolveTimeoutMs,
   sensitiveFileBlockReason
 }

apps/desktop/electron/hardening.test.cjs

@@ -8,11 +8,20 @@ const { pathToFileURL } = require('node:url')
 const {
   DEFAULT_FETCH_TIMEOUT_MS,
   encryptDesktopSecret,
+  resolveDirectoryForIpc,
   resolveReadableFileForIpc,
+  resolveRequestedPathForIpc,
   resolveTimeoutMs,
   sensitiveFileBlockReason
 } = require('./hardening.cjs')
 
+async function rejectsWithCode(promise, code) {
+  await assert.rejects(promise, error => {
+    assert.equal(error?.code, code)
+    return true
+  })
+}
+
 test('resolveTimeoutMs falls back to defaults and accepts overrides', () => {
   assert.equal(resolveTimeoutMs(undefined), DEFAULT_FETCH_TIMEOUT_MS)
   assert.equal(resolveTimeoutMs(0), DEFAULT_FETCH_TIMEOUT_MS)
@@ -51,6 +60,52 @@ test('sensitiveFileBlockReason blocks obvious secret file patterns', () => {
   assert.match(String(sensitiveFileBlockReason('/tmp/server-cert.pem')), /\.pem/)
 })
 
+test('path helpers reject blank non-string NUL and Windows device syntax', async () => {
+  await rejectsWithCode(resolveReadableFileForIpc('', { purpose: 'File preview' }), 'invalid-path')
+  await rejectsWithCode(resolveReadableFileForIpc('   ', { purpose: 'File preview' }), 'invalid-path')
+  await rejectsWithCode(resolveReadableFileForIpc(null, { purpose: 'File preview' }), 'invalid-path')
+  await rejectsWithCode(resolveReadableFileForIpc(`safe${String.fromCharCode(0)}name.txt`), 'invalid-path')
+
+  const devicePaths = [
+    '\\\\?\\C:\\secret.txt',
+    '\\\\.\\C:\\secret.txt',
+    '\\\\?\\UNC\\server\\share\\secret.txt',
+    'GLOBALROOT/Device/HarddiskVolumeShadowCopy1/secret.txt'
+  ]
+
+  for (const devicePath of devicePaths) {
+    assert.throws(
+      () => resolveRequestedPathForIpc(devicePath, { purpose: 'File preview' }),
+      error => {
+        assert.equal(error?.code, 'device-path')
+        return true
+      }
+    )
+    await rejectsWithCode(resolveReadableFileForIpc(devicePath, { purpose: 'File preview' }), 'device-path')
+  }
+
+  assert.throws(
+    () => resolveRequestedPathForIpc('file:///%E0%A4%A', { purpose: 'File preview' }),
+    error => {
+      assert.equal(error?.code, 'invalid-path')
+      return true
+    }
+  )
+  await rejectsWithCode(resolveReadableFileForIpc('file:///%E0%A4%A', { purpose: 'File preview' }), 'invalid-path')
+})
+
+test('resolveRequestedPathForIpc resolves relative paths from the trimmed base directory', () => {
+  const baseDir = path.join(os.tmpdir(), 'hermes-desktop-base')
+
+  assert.equal(
+    resolveRequestedPathForIpc('notes.txt', {
+      baseDir: `  ${baseDir}  `,
+      purpose: 'File preview'
+    }),
+    path.resolve(baseDir, 'notes.txt')
+  )
+})
+
 test('resolveReadableFileForIpc validates existence type size and sensitivity', async t => {
   const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'hermes-desktop-hardening-'))
   t.after(() => fs.rmSync(tempDir, { recursive: true, force: true }))
@@ -71,6 +126,13 @@ test('resolveReadableFileForIpc validates existence type size and sensitivity',
   })
   assert.equal(fromFileUrl.resolvedPath, textPath)
 
+  const spacedPath = path.join(tempDir, 'notes with spaces.txt')
+  fs.writeFileSync(spacedPath, 'space ok', 'utf8')
+  const fromSpacedFileUrl = await resolveReadableFileForIpc(pathToFileURL(spacedPath).toString(), {
+    purpose: 'File preview'
+  })
+  assert.equal(fromSpacedFileUrl.resolvedPath, spacedPath)
+
   await assert.rejects(
     resolveReadableFileForIpc('missing.txt', {
       baseDir: tempDir,
@@ -114,3 +176,91 @@ test('resolveReadableFileForIpc validates existence type size and sensitivity',
   })
   assert.equal(envTemplate.resolvedPath, envTemplatePath)
 })
+
+test('resolveReadableFileForIpc blocks common sensitive files', async t => {
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'hermes-desktop-sensitive-'))
+  t.after(() => fs.rmSync(tempDir, { recursive: true, force: true }))
+
+  const sshDir = path.join(tempDir, '.ssh')
+  fs.mkdirSync(sshDir)
+
+  const blockedFiles = [
+    path.join(tempDir, '.env'),
+    path.join(tempDir, '.npmrc'),
+    path.join(sshDir, 'id_ed25519'),
+    path.join(tempDir, 'cert.pem'),
+    path.join(tempDir, 'cert.p12'),
+    path.join(tempDir, 'cert.pfx')
+  ]
+
+  for (const filePath of blockedFiles) {
+    fs.writeFileSync(filePath, 'secret', 'utf8')
+    await rejectsWithCode(resolveReadableFileForIpc(filePath, { purpose: 'File preview' }), 'sensitive-file')
+  }
+
+  const allowed = path.join(tempDir, '.env.example')
+  fs.writeFileSync(allowed, 'EXAMPLE_TOKEN=value', 'utf8')
+  assert.equal((await resolveReadableFileForIpc(allowed, { purpose: 'File preview' })).resolvedPath, allowed)
+})
+
+test('resolveReadableFileForIpc blocks symlinks whose realpath is sensitive', async t => {
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'hermes-desktop-realpath-'))
+  t.after(() => fs.rmSync(tempDir, { recursive: true, force: true }))
+
+  const envPath = path.join(tempDir, '.env')
+  const linkPath = path.join(tempDir, 'safe-name.txt')
+  fs.writeFileSync(envPath, 'SECRET_TOKEN=123', 'utf8')
+
+  try {
+    fs.symlinkSync(envPath, linkPath, 'file')
+  } catch (error) {
+    if (error?.code === 'EPERM' || error?.code === 'EACCES') {
+      t.skip(`symlink creation is not permitted on this platform (${error.code})`)
+      return
+    }
+    throw error
+  }
+
+  await rejectsWithCode(resolveReadableFileForIpc(linkPath, { purpose: 'File preview' }), 'sensitive-file')
+})
+
+test('resolveDirectoryForIpc accepts directories and rejects invalid directory targets', async t => {
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'hermes-desktop-dir-'))
+  t.after(() => fs.rmSync(tempDir, { recursive: true, force: true }))
+
+  const directory = path.join(tempDir, 'project')
+  const filePath = path.join(tempDir, 'file.txt')
+  fs.mkdirSync(directory)
+  fs.writeFileSync(filePath, 'not a directory', 'utf8')
+
+  const resolved = await resolveDirectoryForIpc(directory)
+  assert.equal(resolved.resolvedPath, directory)
+  assert.equal(resolved.stat.isDirectory(), true)
+
+  await rejectsWithCode(resolveDirectoryForIpc(filePath), 'ENOTDIR')
+  await rejectsWithCode(resolveDirectoryForIpc(path.join(tempDir, 'missing')), 'ENOENT')
+  await rejectsWithCode(resolveDirectoryForIpc('\\\\?\\C:\\secret'), 'device-path')
+})
+
+test('resolveDirectoryForIpc accepts directory symlinks or junctions', async t => {
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'hermes-desktop-dir-link-'))
+  t.after(() => fs.rmSync(tempDir, { recursive: true, force: true }))
+
+  const directory = path.join(tempDir, 'actual-project')
+  const linkPath = path.join(tempDir, 'linked-project')
+  fs.mkdirSync(directory)
+
+  try {
+    fs.symlinkSync(directory, linkPath, process.platform === 'win32' ? 'junction' : 'dir')
+  } catch (error) {
+    if (error?.code === 'EPERM' || error?.code === 'EACCES') {
+      t.skip(`directory symlink creation is not permitted on this platform (${error.code})`)
+      return
+    }
+    throw error
+  }
+
+  const resolved = await resolveDirectoryForIpc(linkPath)
+  assert.equal(resolved.resolvedPath, linkPath)
+  assert.equal(resolved.stat.isDirectory(), true)
+})

apps/desktop/electron/main.cjs

@@ -22,7 +22,7 @@ const http = require('node:http')
 const https = require('node:https')
 const net = require('node:net')
 const path = require('node:path')
-const { fileURLToPath, pathToFileURL } = require('node:url')
+const { pathToFileURL } = require('node:url')
 const { execFileSync, spawn } = require('node:child_process')
 const { detectRemoteDisplay, isWindowsBinaryPathInWsl, isWslEnvironment } = require('./bootstrap-platform.cjs')
 const { runBootstrap } = require('./bootstrap-runner.cjs')
@@ -31,6 +31,8 @@ const { canImportHermesCli, verifyHermesCli } = require('./backend-probes.cjs')
 const { probeGatewayWebSocket } = require('./gateway-ws-probe.cjs')
 const { serializeJsonBody, setJsonRequestHeaders } = require('./oauth-net-request.cjs')
 const { fetchMarketplaceThemes, searchMarketplaceThemes } = require('./vscode-marketplace.cjs')
+const { readDirForIpc } = require('./fs-read-dir.cjs')
+const { gitRootForIpc } = require('./git-root.cjs')
 const {
   OFFICIAL_REPO_HTTPS_URL,
   isOfficialSshRemote
@@ -65,6 +67,7 @@ const {
   TEXT_PREVIEW_SOURCE_MAX_BYTES,
   encryptDesktopSecret: encryptDesktopSecretStrict,
   resolveReadableFileForIpc,
+  resolveRequestedPathForIpc,
   resolveTimeoutMs
 } = require('./hardening.cjs')
 
@@ -730,7 +733,7 @@ function openExternalUrl(rawUrl) {
   if (parsed.protocol === 'file:') {
     let localPath
     try {
-      localPath = fileURLToPath(parsed.toString())
+      localPath = resolveRequestedPathForIpc(parsed.toString(), { purpose: 'Open external file' })
     } catch {
       return false
     }
@@ -2878,10 +2881,10 @@ async function resourceBufferFromUrl(rawUrl) {
     const buffer = match[2] ? Buffer.from(encoded, 'base64') : Buffer.from(decodeURIComponent(encoded), 'utf8')
     return { buffer, mimeType }
   }
-  if (rawUrl.startsWith('file:')) {
-    const filePath = fileURLToPath(rawUrl)
-    const buffer = await fs.promises.readFile(filePath)
-    return { buffer, mimeType: mimeTypeForPath(filePath) }
+  if (/^file:/i.test(rawUrl)) {
+    const { resolvedPath } = await resolveReadableFileForIpc(rawUrl, { purpose: 'Image file' })
+    const buffer = await fs.promises.readFile(resolvedPath)
+    return { buffer, mimeType: mimeTypeForPath(resolvedPath) }
   }
 
   const parsed = new URL(rawUrl)
@@ -2959,11 +2962,13 @@ function expandUserPath(filePath) {
   return value
 }
 
-function previewFileTarget(rawTarget, baseDir) {
+async function previewFileTarget(rawTarget, baseDir) {
   const raw = String(rawTarget || '').trim()
   const base = baseDir ? path.resolve(expandUserPath(baseDir)) : resolveHermesCwd()
-  const filePath = raw.startsWith('file:') ? fileURLToPath(raw) : path.resolve(base, expandUserPath(raw))
-  let resolved = filePath
+  let resolved = resolveRequestedPathForIpc(/^file:/i.test(raw) ? raw : expandUserPath(raw), {
+    baseDir: base,
+    purpose: 'Preview target'
+  })
 
   if (directoryExists(resolved)) {
     resolved = path.join(resolved, 'index.html')
@@ -2974,6 +2979,8 @@ function previewFileTarget(rawTarget, baseDir) {
     return null
   }
 
+  ;({ resolvedPath: resolved } = await resolveReadableFileForIpc(resolved, { purpose: 'Preview target' }))
+
   const mimeType = mimeTypeForPath(resolved)
   const metadata = previewFileMetadata(resolved, mimeType)
   const isHtml = PREVIEW_HTML_EXTENSIONS.has(ext)
@@ -3019,7 +3026,7 @@ function previewUrlTarget(rawTarget) {
   }
 }
 
-function normalizePreviewTarget(rawTarget, baseDir) {
+async function normalizePreviewTarget(rawTarget, baseDir) {
   const raw = String(rawTarget || '').trim()
 
   if (!raw) {
@@ -3031,20 +3038,15 @@ function normalizePreviewTarget(rawTarget, baseDir) {
       return previewUrlTarget(raw)
     }
 
-    return previewFileTarget(raw, baseDir)
+    return await previewFileTarget(raw, baseDir)
   } catch {
     return null
   }
 }
 
-function filePathFromPreviewUrl(rawUrl) {
-  const filePath = fileURLToPath(String(rawUrl || ''))
-
-  if (!fileExists(filePath)) {
-    throw new Error('Preview file is not readable')
-  }
-
-  return filePath
+async function filePathFromPreviewUrl(rawUrl) {
+  const { resolvedPath } = await resolveReadableFileForIpc(String(rawUrl || ''), { purpose: 'Preview file' })
+  return resolvedPath
 }
 
 function sendPreviewFileChanged(payload) {
@@ -3054,8 +3056,8 @@ function sendPreviewFileChanged(payload) {
   webContents.send('hermes:preview-file-changed', payload)
 }
 
-function watchPreviewFile(rawUrl) {
-  const filePath = filePathFromPreviewUrl(rawUrl)
+async function watchPreviewFile(rawUrl) {
+  const filePath = await filePathFromPreviewUrl(rawUrl)
   const watchDir = path.dirname(filePath)
   const targetName = path.basename(filePath)
   const id = crypto.randomBytes(12).toString('base64url')
@@ -5587,48 +5589,6 @@ ipcMain.handle('hermes:logs:reveal', async () => {
 
 ipcMain.handle('hermes:logs:recent', async () => ({ path: DESKTOP_LOG_PATH, lines: hermesLog.slice(-200) }))
 
-// Always-hidden noise (covers non-git projects too — gitignore would catch
-// these anyway when present, but we want the same hygiene without one).
-const FS_READDIR_HIDDEN = new Set([
-  '.git',
-  '.hg',
-  '.svn',
-  '.cache',
-  '.next',
-  '.turbo',
-  '.venv',
-  '__pycache__',
-  'build',
-  'dist',
-  'node_modules',
-  'target',
-  'venv'
-])
-
-function findGitRoot(start) {
-  let dir = start
-
-  for (let i = 0; i < 50; i += 1) {
-    try {
-      if (fs.existsSync(path.join(dir, '.git'))) {
-        return dir
-      }
-    } catch {
-      return null
-    }
-
-    const parent = path.dirname(dir)
-
-    if (parent === dir) {
-      return null
-    }
-
-    dir = parent
-  }
-
-  return null
-}
-
 function isExecutableFile(filePath) {
   if (!filePath || !path.isAbsolute(filePath)) {
     return false
@@ -5811,46 +5771,9 @@ function disposeTerminalSession(id) {
   return true
 }
 
-ipcMain.handle('hermes:fs:readDir', async (_event, dirPath) => {
-  const resolved = path.resolve(String(dirPath || ''))
+ipcMain.handle('hermes:fs:readDir', async (_event, dirPath) => readDirForIpc(dirPath))
 
-  if (!resolved) {
-    return { entries: [], error: 'invalid-path' }
-  }
-
-  try {
-    const dirents = await fs.promises.readdir(resolved, { withFileTypes: true })
-
-    const entries = dirents
-      .filter(d => {
-        if (FS_READDIR_HIDDEN.has(d.name)) {
-          return false
-        }
-
-        return true
-      })
-      .map(d => ({ name: d.name, path: path.join(resolved, d.name), isDirectory: d.isDirectory() }))
-      .sort((a, b) => Number(b.isDirectory) - Number(a.isDirectory) || a.name.localeCompare(b.name))
-
-    return { entries }
-  } catch (error) {
-    return { entries: [], error: error?.code || 'read-error' }
-  }
-})
-
-ipcMain.handle('hermes:fs:gitRoot', async (_event, startPath) => {
-  const input = String(startPath || '')
-  const resolved = input.startsWith('file:') ? fileURLToPath(input) : path.resolve(input)
-
-  try {
-    const stat = await fs.promises.stat(resolved)
-    const start = stat.isDirectory() ? resolved : path.dirname(resolved)
-
-    return findGitRoot(start)
-  } catch {
-    return findGitRoot(resolved)
-  }
-})
+ipcMain.handle('hermes:fs:gitRoot', async (_event, startPath) => gitRootForIpc(startPath))
 
 ipcMain.handle('hermes:terminal:start', async (event, payload = {}) => {
   if (!nodePty) {

apps/desktop/package.json

@@ -35,7 +35,7 @@
     "test:desktop:nsis": "node scripts/test-desktop.mjs nsis",
     "test:desktop:existing": "node scripts/test-desktop.mjs existing",
     "test:desktop:fresh": "node scripts/test-desktop.mjs fresh",
-    "test:desktop:platforms": "node --test electron/bootstrap-platform.test.cjs electron/hardening.test.cjs electron/backend-probes.test.cjs electron/bootstrap-runner.test.cjs electron/connection-config.test.cjs electron/gateway-ws-probe.test.cjs electron/oauth-net-request.test.cjs electron/desktop-uninstall.test.cjs electron/session-windows.test.cjs electron/workspace-cwd.test.cjs electron/windows-child-process.test.cjs electron/update-remote.test.cjs",
+    "test:desktop:platforms": "node --test electron/bootstrap-platform.test.cjs electron/hardening.test.cjs electron/backend-probes.test.cjs electron/bootstrap-runner.test.cjs electron/connection-config.test.cjs electron/gateway-ws-probe.test.cjs electron/oauth-net-request.test.cjs electron/desktop-uninstall.test.cjs electron/session-windows.test.cjs electron/workspace-cwd.test.cjs electron/fs-read-dir.test.cjs electron/git-root.test.cjs electron/windows-child-process.test.cjs electron/update-remote.test.cjs",
     "typecheck": "tsc -p . --noEmit",
     "lint": "eslint src/ electron/",
     "lint:fix": "eslint src/ electron/ --fix",

apps/desktop/src/app/right-sidebar/files/ipc.test.ts

@@ -0,0 +1,100 @@
+/// <reference types="node" />
+
+import { Buffer } from 'node:buffer'
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import type { HermesReadDirEntry, HermesReadDirResult } from '@/global'
+
+import { clearProjectDirCache, readProjectDir } from './ipc'
+
+const readDir = vi.fn<(path: string) => Promise<HermesReadDirResult>>()
+const readFileDataUrl = vi.fn<(path: string) => Promise<string>>()
+const gitRoot = vi.fn<(path: string) => Promise<string | null>>()
+
+function ok(entries: HermesReadDirEntry[]): HermesReadDirResult {
+  return { entries }
+}
+
+function dataUrl(text: string) {
+  return `data:text/plain;base64,${Buffer.from(text, 'utf8').toString('base64')}`
+}
+
+function installBridge() {
+  ;(
+    window as unknown as {
+      hermesDesktop: {
+        gitRoot: typeof gitRoot
+        readDir: typeof readDir
+        readFileDataUrl: typeof readFileDataUrl
+      }
+    }
+  ).hermesDesktop = { gitRoot, readDir, readFileDataUrl }
+}
+
+describe('readProjectDir', () => {
+  beforeEach(() => {
+    clearProjectDirCache()
+    readDir.mockReset()
+    readFileDataUrl.mockReset()
+    gitRoot.mockReset()
+    installBridge()
+  })
+
+  afterEach(() => {
+    clearProjectDirCache()
+    delete (window as unknown as { hermesDesktop?: unknown }).hermesDesktop
+  })
+
+  it('returns no-bridge when the desktop bridge is unavailable', async () => {
+    delete (window as unknown as { hermesDesktop?: unknown }).hermesDesktop
+
+    await expect(readProjectDir('/repo')).resolves.toEqual({ entries: [], error: 'no-bridge' })
+  })
+
+  it('filters gitignored entries when readDir returns Windows-style paths', async () => {
+    gitRoot.mockResolvedValue('C:\\repo')
+    readDir.mockImplementation(async path => {
+      if (path === 'C:\\repo\\src') {
+        return ok([
+          { name: 'debug.log', path: 'C:\\repo\\src\\debug.log', isDirectory: false },
+          { name: '临时.txt', path: 'C:\\repo\\src\\临时.txt', isDirectory: false },
+          { name: 'keep.ts', path: 'C:\\repo\\src\\keep.ts', isDirectory: false }
+        ])
+      }
+
+      if (path === 'C:/repo') {
+        return ok([{ name: '.gitignore', path: 'C:/repo/.gitignore', isDirectory: false }])
+      }
+
+      if (path === 'C:/repo/src') {
+        return ok([])
+      }
+
+      return ok([])
+    })
+    readFileDataUrl.mockResolvedValue(dataUrl('# Unicode 路径规则\nsrc/*.log\nsrc/临时.txt\n'))
+
+    const result = await readProjectDir('C:\\repo\\src', 'C:\\repo')
+
+    expect(result.entries.map(entry => entry.name)).toEqual(['keep.ts'])
+    expect(gitRoot).toHaveBeenCalledWith('C:/repo')
+    expect(readFileDataUrl).toHaveBeenCalledWith('C:/repo/.gitignore')
+  })
+
+  it('does not fetch .gitignore contents when listings do not contain .gitignore', async () => {
+    gitRoot.mockResolvedValue('/repo')
+    readDir.mockImplementation(async path => {
+      if (path === '/repo/src') {
+        return ok([{ name: 'debug.log', path: '/repo/src/debug.log', isDirectory: false }])
+      }
+
+      return ok([])
+    })
+
+    const result = await readProjectDir('/repo/src', '/repo')
+
+    expect(result.entries.map(entry => entry.name)).toEqual(['debug.log'])
+    expect(readFileDataUrl).not.toHaveBeenCalled()
+  })
+})

apps/desktop/src/app/right-sidebar/files/ipc.ts

@@ -27,7 +27,7 @@ function decodeDataUrl(dataUrl: string) {
 }
 
 function clean(path: string) {
-  return path.replace(/\/+$/, '') || '/'
+  return path.replace(/\\/g, '/').replace(/\/+$/, '') || '/'
 }
 
 /** Strict POSIX-style relative path; null if `child` is not inside `root`. */

apps/desktop/src/app/right-sidebar/files/tree.tsx

@@ -145,7 +145,8 @@ function ProjectTreeRow({
   }
 
   const isFolder = node.data.isDirectory
-  const isPlaceholder = node.data.id.endsWith('::__loading__')
+  const isPlaceholder = Boolean(node.data.placeholder)
+  const isErrorPlaceholder = node.data.placeholder === 'error'
 
   return (
     <div
@@ -210,8 +211,10 @@ function ProjectTreeRow({
       )}
       {!isFolder && <span aria-hidden className="w-3 shrink-0" />}
       <span aria-hidden className="flex w-3.5 items-center justify-center text-(--ui-text-tertiary)">
-        {isPlaceholder ? (
+        {isPlaceholder && !isErrorPlaceholder ? (
           <Codicon name="loading" size="0.75rem" spinning />
+        ) : isErrorPlaceholder ? (
+          <Codicon name="warning" size="0.75rem" />
         ) : isFolder ? (
           <Codicon name={node.isOpen ? 'folder-opened' : 'folder'} size="0.875rem" />
         ) : (

apps/desktop/src/app/right-sidebar/files/use-project-tree.test.ts

@@ -106,7 +106,7 @@ describe('useProjectTree', () => {
     expect(readDir).toHaveBeenCalledTimes(1)
   })
 
-  it('captures per-folder error code and leaves the folder expandable but empty', async () => {
+  it('captures per-folder error code and shows an error placeholder child', async () => {
     readDir.mockResolvedValueOnce(ok([{ name: 'priv', path: '/p/priv', isDirectory: true }]))
     readDir.mockResolvedValueOnce({ entries: [], error: 'EACCES' })
 
@@ -119,7 +119,14 @@ describe('useProjectTree', () => {
     })
 
     expect(result.current.data[0].error).toBe('EACCES')
-    expect(result.current.data[0].children).toEqual([])
+    expect(result.current.data[0].children).toEqual([
+      {
+        id: '/p/priv::__error__',
+        isDirectory: false,
+        name: 'Unable to read (EACCES)',
+        placeholder: 'error'
+      }
+    ])
   })
 
   it('dedupes concurrent loadChildren calls for the same id', async () => {

apps/desktop/src/app/right-sidebar/files/use-project-tree.ts

@@ -14,11 +14,14 @@ export interface TreeNode {
   children?: TreeNode[]
   /** True while a readDir for this folder is in flight. */
   loading?: boolean
+  /** Synthetic loading/error rows are not real filesystem entries. */
+  placeholder?: 'error' | 'loading'
   /** Last error code from readDir (e.g. EACCES). Cleared on next successful load. */
   error?: string
 }
 
 const PLACEHOLDER_ID = '__loading__'
+const ERROR_PLACEHOLDER_ID = '__error__'
 
 function makeNode(path: string, name: string, isDirectory: boolean): TreeNode {
   return { id: path, isDirectory, name }
@@ -43,7 +46,16 @@ function patchNode(nodes: TreeNode[] | undefined | null, id: string, patch: (n:
 }
 
 function placeholderChild(parentId: string): TreeNode {
-  return { id: `${parentId}::${PLACEHOLDER_ID}`, isDirectory: false, name: 'Loading…' }
+  return { id: `${parentId}::${PLACEHOLDER_ID}`, isDirectory: false, name: 'Loading…', placeholder: 'loading' }
+}
+
+function errorChild(parentId: string, error: string | undefined): TreeNode {
+  return {
+    id: `${parentId}::${ERROR_PLACEHOLDER_ID}`,
+    isDirectory: false,
+    name: `Unable to read (${error || 'read-error'})`,
+    placeholder: 'error'
+  }
 }
 
 export interface UseProjectTreeResult {
@@ -227,7 +239,7 @@ export function useProjectTree(cwd: string): UseProjectTreeResult {
             ...n,
             loading: false,
             error: error || undefined,
-            children: error ? [] : entries.map(e => makeNode(e.path, e.name, e.isDirectory))
+            children: error ? [errorChild(n.id, error)] : entries.map(e => makeNode(e.path, e.name, e.isDirectory))
           }))
         }
       })

apps/desktop/src/app/session/hooks/use-message-stream.ts

@@ -64,6 +64,67 @@ interface QueuedStreamDeltas {
   reasoning: string
 }
 
+type SessionRuntimeStatePatch = Partial<
+  Pick<
+    ClientSessionState,
+    | 'branch'
+    | 'cwd'
+    | 'fast'
+    | 'model'
+    | 'personality'
+    | 'provider'
+    | 'reasoningEffort'
+    | 'serviceTier'
+    | 'yolo'
+  >
+>
+
+function sessionInfoStatePatch(payload: GatewayEventPayload | undefined): SessionRuntimeStatePatch {
+  const patch: SessionRuntimeStatePatch = {}
+
+  if (typeof payload?.model === 'string') {
+    patch.model = payload.model || ''
+  }
+
+  if (typeof payload?.provider === 'string') {
+    patch.provider = payload.provider || ''
+  }
+
+  if (typeof payload?.cwd === 'string') {
+    patch.cwd = payload.cwd
+  }
+
+  if (typeof payload?.branch === 'string') {
+    patch.branch = payload.branch
+  }
+
+  if (typeof payload?.personality === 'string') {
+    patch.personality = normalizePersonalityValue(payload.personality)
+  }
+
+  if (typeof payload?.reasoning_effort === 'string') {
+    patch.reasoningEffort = payload.reasoning_effort
+  }
+
+  if (typeof payload?.service_tier === 'string') {
+    patch.serviceTier = payload.service_tier
+  }
+
+  if (typeof payload?.fast === 'boolean') {
+    patch.fast = payload.fast
+  }
+
+  if (typeof payload?.yolo === 'boolean') {
+    patch.yolo = payload.yolo
+  }
+
+  return patch
+}
+
+function hasSessionInfoStatePatch(patch: SessionRuntimeStatePatch): boolean {
+  return Object.keys(patch).length > 0
+}
+
 // Minimum gap between two assistant-text flushes during a stream. Was 16ms
 // (rAF only), which at typical LLM token rates of ~30-80 tok/sec meant every
 // token got its own React commit + Streamdown markdown re-parse, scaling
@@ -628,36 +689,27 @@ export function useMessageStream({
         // Apply session-scoped fields when the event targets the active
         // session, OR when it's a global broadcast and we have no session.
         const apply = explicitSid ? isActiveEvent : !activeSessionIdRef.current
+        const statePatch = sessionInfoStatePatch(payload)
+        const hasStatePatch = hasSessionInfoStatePatch(statePatch)
         const modelChanged = typeof payload?.model === 'string'
         const providerChanged = typeof payload?.provider === 'string'
         const runningChanged = typeof payload?.running === 'boolean'
 
         if (apply) {
-          const runtimeInfo: Partial<
-            Pick<
-              ClientSessionState,
-              'branch' | 'cwd' | 'fast' | 'model' | 'provider' | 'reasoningEffort' | 'serviceTier' | 'yolo'
-            >
-          > = {}
-
           if (modelChanged) {
             setCurrentModel(payload!.model || '')
-            runtimeInfo.model = payload!.model || ''
           }
 
           if (providerChanged) {
             setCurrentProvider(payload!.provider || '')
-            runtimeInfo.provider = payload!.provider || ''
           }
 
           if (typeof payload?.cwd === 'string') {
             setCurrentCwd(payload.cwd)
-            runtimeInfo.cwd = payload.cwd
           }
 
           if (typeof payload?.branch === 'string') {
             setCurrentBranch(payload.branch)
-            runtimeInfo.branch = payload.branch
           }
 
           if (typeof payload?.personality === 'string') {
@@ -666,28 +718,31 @@ export function useMessageStream({
 
           if (typeof payload?.reasoning_effort === 'string') {
             setCurrentReasoningEffort(payload.reasoning_effort)
-            runtimeInfo.reasoningEffort = payload.reasoning_effort
           }
 
           if (typeof payload?.service_tier === 'string') {
             setCurrentServiceTier(payload.service_tier)
-            runtimeInfo.serviceTier = payload.service_tier
           }
 
           if (typeof payload?.fast === 'boolean') {
             setCurrentFastMode(payload.fast)
-            runtimeInfo.fast = payload.fast
           }
 
           if (typeof payload?.yolo === 'boolean') {
             setYoloActive(payload.yolo)
-            runtimeInfo.yolo = payload.yolo
           }
+        }
 
-          if (sessionId && Object.keys(runtimeInfo).length > 0) {
-            updateSessionState(sessionId, state => ({ ...state, ...runtimeInfo }))
-          }
+        if (sessionId && hasStatePatch) {
+          updateSessionState(sessionId, state => ({
+            ...state,
+            ...statePatch,
+            branch: statePatch.branch ?? state.branch,
+            cwd: statePatch.cwd ?? state.cwd
+          }))
+        }
 
+        if (apply) {
           if (runningChanged && sessionId) {
             updateSessionState(sessionId, state => {
               const busy = Boolean(payload!.running)

apps/desktop/src/app/session/hooks/use-session-actions.ts

@@ -43,7 +43,7 @@ import {
   workspaceCwdForNewSession
 } from '@/store/session'
 import { reportBackendContract } from '@/store/updates'
-import type { SessionCreateResponse, SessionInfo, SessionResumeResponse, UsageStats } from '@/types/hermes'
+import type { SessionCreateResponse, SessionInfo, SessionResumeResponse, SessionRuntimeInfo, UsageStats } from '@/types/hermes'
 
 import { NEW_CHAT_ROUTE, sessionRoute, SETTINGS_ROUTE } from '../../routes'
 import type { ClientSessionState, SidebarNavItem } from '../../types'
@@ -209,16 +209,27 @@ function patchSessionWorkspace(sessionId: string, cwd: string | undefined) {
   setSessions(prev => prev.map(session => (session.id === sessionId ? { ...session, cwd } : session)))
 }
 
-function applyRuntimeInfo(info: SessionCreateResponse['info'] | undefined): Partial<
-  Pick<ClientSessionState, 'branch' | 'cwd' | 'fast' | 'model' | 'provider' | 'reasoningEffort' | 'serviceTier' | 'yolo'>
-> | null {
+type SessionRuntimeStatePatch = Partial<
+  Pick<
+    ClientSessionState,
+    | 'branch'
+    | 'cwd'
+    | 'fast'
+    | 'model'
+    | 'personality'
+    | 'provider'
+    | 'reasoningEffort'
+    | 'serviceTier'
+    | 'yolo'
+  >
+>
+
+function applyRuntimeInfo(info: SessionRuntimeInfo | undefined): SessionRuntimeStatePatch | null {
   if (!info) {
     return null
   }
 
-  const sessionState: Partial<
-    Pick<ClientSessionState, 'branch' | 'cwd' | 'fast' | 'model' | 'provider' | 'reasoningEffort' | 'serviceTier' | 'yolo'>
-  > = {}
+  const sessionState: SessionRuntimeStatePatch = {}
 
   reportBackendContract(info.desktop_contract)
 
@@ -226,12 +237,12 @@ function applyRuntimeInfo(info: SessionCreateResponse['info'] | undefined): Part
     requestDesktopOnboarding(info.credential_warning)
   }
 
-  if (info.model) {
+  if (typeof info.model === 'string') {
     setCurrentModel(info.model)
     sessionState.model = info.model
   }
 
-  if (info.provider) {
+  if (typeof info.provider === 'string') {
     setCurrentProvider(info.provider)
     sessionState.provider = info.provider
   }
@@ -247,7 +258,9 @@ function applyRuntimeInfo(info: SessionCreateResponse['info'] | undefined): Part
   }
 
   if (typeof info.personality === 'string') {
-    setCurrentPersonality(normalizePersonalityValue(info.personality))
+    const personality = normalizePersonalityValue(info.personality)
+    setCurrentPersonality(personality)
+    sessionState.personality = personality
   }
 
   if (typeof info.reasoning_effort === 'string') {
@@ -277,6 +290,16 @@ function applyRuntimeInfo(info: SessionCreateResponse['info'] | undefined): Part
   return sessionState
 }
 
+function applyStoredSessionPreviewRuntimeInfo(stored: { model?: null | string } | undefined) {
+  setCurrentModel(stored?.model || '')
+  setCurrentProvider('')
+  setCurrentReasoningEffort('')
+  setCurrentServiceTier('')
+  setCurrentFastMode(false)
+  setYoloActive(false)
+  setCurrentPersonality('')
+}
+
 export function useSessionActions({
   activeSessionId,
   activeSessionIdRef,
@@ -465,15 +488,28 @@ export function useSessionActions({
       const cachedState = cachedRuntimeId && sessionStateByRuntimeIdRef.current.get(cachedRuntimeId)
 
       if (cachedRuntimeId && cachedState) {
+        const stored = $sessions.get().find(session => session.id === storedSessionId)
+        const cachedViewState =
+          !cachedState.model && stored?.model != null
+            ? {
+                ...cachedState,
+                model: stored.model || ''
+              }
+            : cachedState
+
+        if (cachedViewState !== cachedState) {
+          sessionStateByRuntimeIdRef.current.set(cachedRuntimeId, cachedViewState)
+        }
+
         setFreshDraftReady(false)
         clearNotifications()
         setSelectedStoredSessionId(storedSessionId)
         selectedStoredSessionIdRef.current = storedSessionId
         setActiveSessionId(cachedRuntimeId)
         activeSessionIdRef.current = cachedRuntimeId
-        syncSessionStateToView(cachedRuntimeId, cachedState)
-        setCurrentCwd(cachedState.cwd)
-        setCurrentBranch(cachedState.branch)
+        syncSessionStateToView(cachedRuntimeId, cachedViewState)
+        setCurrentCwd(cachedViewState.cwd)
+        setCurrentBranch(cachedViewState.branch)
         setSessionStartedAt(Date.now())
 
         try {
@@ -514,6 +550,7 @@ export function useSessionActions({
       selectedStoredSessionIdRef.current = storedSessionId
       setSessionStartedAt(Date.now())
       const stored = $sessions.get().find(session => session.id === storedSessionId)
+      applyStoredSessionPreviewRuntimeInfo(stored)
 
       if (stored) {
         setCurrentUsage(current => ({

apps/desktop/src/app/session/hooks/use-session-state-cache.test.tsx

@@ -2,7 +2,20 @@ import { act, cleanup, render } from '@testing-library/react'
 import type { MutableRefObject } from 'react'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
-import { $turnStartedAt, setTurnStartedAt } from '@/store/session'
+import {
+  $currentFastMode,
+  $currentModel,
+  $currentProvider,
+  $currentReasoningEffort,
+  $currentServiceTier,
+  $turnStartedAt,
+  setCurrentFastMode,
+  setCurrentModel,
+  setCurrentProvider,
+  setCurrentReasoningEffort,
+  setCurrentServiceTier,
+  setTurnStartedAt
+} from '@/store/session'
 
 import { useSessionStateCache } from './use-session-state-cache'
 
@@ -46,12 +59,22 @@ describe('useSessionStateCache — per-session turn timer', () => {
       return null as unknown as number
     })
     setTurnStartedAt(null)
+    setCurrentModel('')
+    setCurrentProvider('')
+    setCurrentReasoningEffort('')
+    setCurrentServiceTier('')
+    setCurrentFastMode(false)
   })
 
   afterEach(() => {
     cleanup()
     vi.restoreAllMocks()
     setTurnStartedAt(null)
+    setCurrentModel('')
+    setCurrentProvider('')
+    setCurrentReasoningEffort('')
+    setCurrentServiceTier('')
+    setCurrentFastMode(false)
   })
 
   it("keeps a background session's running turn clock and never mirrors it to the view", () => {
@@ -115,4 +138,78 @@ describe('useSessionStateCache — per-session turn timer', () => {
     })
     expect($turnStartedAt.get()).toBeNull()
   })
+
+  it('mirrors the focused session model metadata when switching from a cached session', () => {
+    let cache!: Cache
+    const { rerender } = render(
+      <Harness activeSessionId="fg-runtime" onReady={c => (cache = c)} selectedStoredSessionId="fg-stored" />
+    )
+
+    act(() => {
+      cache.updateSessionState(
+        'bg-runtime',
+        state => ({
+          ...state,
+          fast: true,
+          model: 'anthropic/claude-opus-4.8',
+          provider: 'anthropic',
+          reasoningEffort: 'high',
+          serviceTier: 'priority'
+        }),
+        'bg-stored'
+      )
+    })
+
+    // Background metadata is cached but must not bleed into the visible statusbar.
+    expect($currentModel.get()).toBe('')
+    expect($currentReasoningEffort.get()).toBe('')
+    expect($currentFastMode.get()).toBe(false)
+
+    rerender(<Harness activeSessionId="bg-runtime" onReady={c => (cache = c)} selectedStoredSessionId="bg-stored" />)
+
+    const bgState = cache.sessionStateByRuntimeIdRef.current.get('bg-runtime')
+    expect(bgState).toBeTruthy()
+
+    act(() => {
+      cache.syncSessionStateToView('bg-runtime', bgState!)
+    })
+
+    expect($currentModel.get()).toBe('anthropic/claude-opus-4.8')
+    expect($currentProvider.get()).toBe('anthropic')
+    expect($currentReasoningEffort.get()).toBe('high')
+    expect($currentServiceTier.get()).toBe('priority')
+    expect($currentFastMode.get()).toBe(true)
+  })
+
+  it('clears stale model metadata when the newly focused session has no cached value', () => {
+    setCurrentModel('previous-model')
+    setCurrentProvider('previous-provider')
+    setCurrentReasoningEffort('high')
+    setCurrentServiceTier('priority')
+    setCurrentFastMode(true)
+
+    let cache!: Cache
+    const { rerender } = render(
+      <Harness activeSessionId="fg-runtime" onReady={c => (cache = c)} selectedStoredSessionId="fg-stored" />
+    )
+
+    act(() => {
+      cache.updateSessionState('bg-runtime', state => ({ ...state }), 'bg-stored')
+    })
+
+    rerender(<Harness activeSessionId="bg-runtime" onReady={c => (cache = c)} selectedStoredSessionId="bg-stored" />)
+
+    const bgState = cache.sessionStateByRuntimeIdRef.current.get('bg-runtime')
+    expect(bgState).toBeTruthy()
+
+    act(() => {
+      cache.syncSessionStateToView('bg-runtime', bgState!)
+    })
+
+    expect($currentModel.get()).toBe('')
+    expect($currentProvider.get()).toBe('')
+    expect($currentReasoningEffort.get()).toBe('')
+    expect($currentServiceTier.get()).toBe('')
+    expect($currentFastMode.get()).toBe(false)
+  })
 })

apps/desktop/src/app/session/hooks/use-session-state-cache.ts

@@ -11,6 +11,7 @@ import {
   noteSessionActivity,
   setCurrentFastMode,
   setCurrentModel,
+  setCurrentPersonality,
   setCurrentProvider,
   setCurrentReasoningEffort,
   setCurrentServiceTier,
@@ -53,6 +54,16 @@ interface SessionStateCacheOptions {
   setMessages: (messages: ChatMessage[]) => void
 }
 
+function syncRuntimeMetadataToView(state: ClientSessionState) {
+  setCurrentModel(state.model ?? '')
+  setCurrentProvider(state.provider ?? '')
+  setCurrentReasoningEffort(state.reasoningEffort ?? '')
+  setCurrentServiceTier(state.serviceTier ?? '')
+  setCurrentFastMode(state.fast ?? false)
+  setYoloActive(state.yolo ?? false)
+  setCurrentPersonality(state.personality ?? '')
+}
+
 export function useSessionStateCache({
   activeSessionId,
   busyRef,
@@ -137,12 +148,7 @@ export function useSessionStateCache({
       setMessages(nextMessages)
     }
 
-    setCurrentModel(pending.state.model)
-    setCurrentProvider(pending.state.provider)
-    setCurrentReasoningEffort(pending.state.reasoningEffort)
-    setCurrentServiceTier(pending.state.serviceTier)
-    setCurrentFastMode(pending.state.fast)
-    setYoloActive(pending.state.yolo)
+    syncRuntimeMetadataToView(pending.state)
     setBusy(pending.state.busy)
     setMutableRef(busyRef, pending.state.busy)
     setAwaitingResponse(pending.state.awaitingResponse)
@@ -167,6 +173,7 @@ export function useSessionStateCache({
         return
       }
 
+      syncRuntimeMetadataToView(state)
       pendingViewStateRef.current = { sessionId, state }
 
       // Terminal / attention transitions (turn finished, error, or the agent is

apps/desktop/src/app/types.ts

@@ -129,6 +129,7 @@ export interface ClientSessionState {
   serviceTier: string
   fast: boolean
   yolo: boolean
+  personality: string
   busy: boolean
   awaitingResponse: boolean
   streamId: string | null

apps/desktop/src/lib/chat-runtime.ts

@@ -46,6 +46,7 @@ export function createClientSessionState(
     serviceTier: '',
     fast: false,
     yolo: false,
+    personality: '',
     busy: false,
     awaitingResponse: false,
     streamId: null,

gateway/platforms/telegram.py

@@ -3837,6 +3837,33 @@ class TelegramAdapter(BasePlatformAdapter):
             )
         return error
 
+    def _telegram_media_too_large_note(self, label: str, file_size: Any, max_bytes: int) -> str:
+        limit_mb = max(1, max_bytes // (1024 * 1024))
+        try:
+            size_mb = int(file_size or 0) / (1024 * 1024)
+            size_text = f"{size_mb:.1f} MB"
+        except (TypeError, ValueError):
+            size_text = "unknown size"
+        return (
+            f"[Telegram {label} skipped: file size {size_text} exceeds the "
+            f"{limit_mb} MB limit. Ask the user to send a shorter voice note "
+            "or a smaller audio file.]"
+        )
+
+    def _telegram_media_size_allowed(self, source: Any, label: str) -> tuple[bool, Optional[str]]:
+        """Validate Telegram media size before downloading into memory."""
+        max_bytes = int(getattr(self, "_max_doc_bytes", 20 * 1024 * 1024) or 20 * 1024 * 1024)
+        file_size = getattr(source, "file_size", None)
+        try:
+            size = int(file_size or 0)
+        except (TypeError, ValueError):
+            size = 0
+        if size <= 0:
+            return True, None
+        if size <= max_bytes:
+            return True, None
+        return False, self._telegram_media_too_large_note(label, size, max_bytes)
+
     async def send_voice(
         self,
         chat_id: str,
@@ -5602,6 +5629,12 @@ class TelegramAdapter(BasePlatformAdapter):
         # Download voice/audio messages to cache for STT transcription
         if msg.voice:
             try:
+                allowed, note = self._telegram_media_size_allowed(msg.voice, "voice message")
+                if not allowed:
+                    event.text = self._append_observed_note(event.text, note or "")
+                    logger.info("[Telegram] Skipped oversized user voice (size=%s)", getattr(msg.voice, "file_size", None))
+                    await self.handle_message(event)
+                    return
                 file_obj = await msg.voice.get_file()
                 audio_bytes = await file_obj.download_as_bytearray()
                 cached_path = cache_audio_from_bytes(bytes(audio_bytes), ext=".ogg")
@@ -5612,6 +5645,12 @@ class TelegramAdapter(BasePlatformAdapter):
                 logger.warning("[Telegram] Failed to cache voice: %s", e, exc_info=True)
         elif msg.audio:
             try:
+                allowed, note = self._telegram_media_size_allowed(msg.audio, "audio file")
+                if not allowed:
+                    event.text = self._append_observed_note(event.text, note or "")
+                    logger.info("[Telegram] Skipped oversized user audio (size=%s)", getattr(msg.audio, "file_size", None))
+                    await self.handle_message(event)
+                    return
                 file_obj = await msg.audio.get_file()
                 audio_bytes = await file_obj.download_as_bytearray()
                 cached_path = cache_audio_from_bytes(bytes(audio_bytes), ext=".mp3")

hermes_cli/banner.py

@@ -693,16 +693,27 @@ def build_welcome_banner(console: "Console", model: str, cwd: str,
         right_lines.append("")
         right_lines.append(f"[bold {accent}]MCP Servers[/]")
         for srv in mcp_status:
+            status = srv.get("status")
             if srv["connected"]:
                 right_lines.append(
                     f"[dim {dim}]{srv['name']}[/] [{text}]({srv['transport']})[/] "
                     f"[dim {dim}]—[/] [{text}]{srv['tools']} tool(s)[/]"
                 )
-            elif srv.get("disabled"):
+            elif srv.get("disabled") or status == "disabled":
                 right_lines.append(
                     f"[dim {dim}]{srv['name']}[/] [dim]({srv['transport']})[/] "
                     f"[dim {dim}]— disabled[/]"
                 )
+            elif status == "connecting":
+                right_lines.append(
+                    f"[dim {dim}]{srv['name']}[/] [dim]({srv['transport']})[/] "
+                    f"[yellow]— connecting[/]"
+                )
+            elif status == "configured":
+                right_lines.append(
+                    f"[dim {dim}]{srv['name']}[/] [dim]({srv['transport']})[/] "
+                    f"[dim {dim}]— configured[/]"
+                )
             else:
                 right_lines.append(
                     f"[red]{srv['name']}[/] [dim]({srv['transport']})[/] "

hermes_cli/config.py

@@ -270,6 +270,11 @@ _EXTRA_ENV_KEYS = frozenset({
     "IRC_SERVER", "IRC_PORT", "IRC_NICKNAME", "IRC_CHANNEL",
     "IRC_USE_TLS", "IRC_SERVER_PASSWORD", "IRC_NICKSERV_PASSWORD",
     "TERMINAL_ENV", "TERMINAL_SSH_KEY", "TERMINAL_SSH_PORT",
+    # Deprecated tool-progress env vars — replaced by display.tool_progress in
+    # config.yaml. Kept known here so .env sanitization/reload still handle
+    # them for existing users (gateway reads them as a back-compat fallback),
+    # without surfacing them in user-facing OPTIONAL_ENV_VARS listings.
+    "HERMES_TOOL_PROGRESS", "HERMES_TOOL_PROGRESS_MODE",
     "WHATSAPP_MODE", "WHATSAPP_ENABLED",
     "MATTERMOST_HOME_CHANNEL", "MATTERMOST_HOME_CHANNEL_NAME", "MATTERMOST_REPLY_MODE",
     "MATRIX_PASSWORD", "MATRIX_ENCRYPTION", "MATRIX_DEVICE_ID", "MATRIX_HOME_ROOM",
@@ -3557,21 +3562,11 @@ OPTIONAL_ENV_VARS = {
     },
     # HERMES_TOOL_PROGRESS and HERMES_TOOL_PROGRESS_MODE are deprecated —
     # now configured via display.tool_progress in config.yaml (off|new|all|verbose).
-    # Gateway falls back to these env vars for backward compatibility.
-    "HERMES_TOOL_PROGRESS": {
-        "description": "(deprecated) Use display.tool_progress in config.yaml instead",
-        "prompt": "Tool progress (deprecated — use config.yaml)",
-        "url": None,
-        "password": False,
-        "category": "setting",
-    },
-    "HERMES_TOOL_PROGRESS_MODE": {
-        "description": "(deprecated) Use display.tool_progress in config.yaml instead",
-        "prompt": "Progress mode (deprecated — use config.yaml)",
-        "url": None,
-        "password": False,
-        "category": "setting",
-    },
+    # The gateway still falls back to these env vars for backward compatibility,
+    # so they live in _EXTRA_ENV_KEYS (known to .env sanitization/reload) but
+    # are intentionally NOT listed here: OPTIONAL_ENV_VARS feeds user-facing
+    # surfaces (dashboard keys page, setup checklists) and deprecated knobs
+    # shouldn't be offered there.
     "HERMES_PREFILL_MESSAGES_FILE": {
         "description": "Path to JSON file with ephemeral prefill messages for few-shot priming",
         "prompt": "Prefill messages file path",

hermes_cli/gateway.py

@@ -612,54 +612,13 @@ def find_profile_gateway_processes(
 
 
 def _gateway_run_args_for_profile(profile: str) -> list[str]:
-    python_exe = get_python_path()
-    if is_windows():
-        # uv-created venv launchers are a trap here: ``venv\Scripts\pythonw.exe``
-        # starts hidden but then re-execs the *base* interpreter as a console
-        # ``python.exe`` — and that re-exec is a fresh CreateProcess that does
-        # NOT inherit our CREATE_NO_WINDOW flag, so a blank console window pops
-        # up.  That's exactly what users hit when the gateway is respawned after
-        # a Desktop-GUI ``hermes update``.  Resolve the base ``pythonw.exe``
-        # directly — the same path ``_spawn_detached`` / ``_build_gateway_argv``
-        # take for ``hermes gateway start`` — so the post-update respawn is
-        # windowless.  The matching VIRTUAL_ENV / PYTHONPATH overlay is applied
-        # to the spawn env in ``launch_detached_profile_gateway_restart`` so
-        # imports still resolve without the venv launcher shim.
-        from hermes_cli.gateway_windows import _resolve_detached_python
-
-        python_exe, _venv_dir, _extra_pythonpath = _resolve_detached_python(python_exe)
-    args = [python_exe, "-m", "hermes_cli.main"]
+    args = [get_python_path(), "-m", "hermes_cli.main"]
     if profile != "default":
         args.extend(["--profile", profile])
     args.extend(["gateway", "run", "--replace"])
     return args
 
 
-def _gateway_respawn_env(spawn_env: dict[str, str]) -> dict[str, str]:
-    """Overlay VIRTUAL_ENV / PYTHONPATH so a base-``pythonw.exe`` respawn can
-    import ``hermes_cli`` without the venv launcher shim.
-
-    Returns ``spawn_env`` unchanged on non-Windows so the POSIX spawn path is
-    byte-for-byte identical to the pre-fix behaviour (it inherits ``os.environ``
-    exactly as before).  On Windows it mirrors what ``_build_gateway_argv`` does
-    for ``hermes gateway start``: point VIRTUAL_ENV at the venv and prepend the
-    repo root plus base-interpreter site-packages to PYTHONPATH.
-    """
-    if not is_windows():
-        return spawn_env
-    from hermes_cli.gateway_windows import (
-        _prepend_pythonpath,
-        _resolve_detached_python,
-    )
-
-    _python, venv_dir, extra_pythonpath = _resolve_detached_python(get_python_path())
-    spawn_env["VIRTUAL_ENV"] = str(venv_dir)
-    spawn_env["PYTHONIOENCODING"] = "utf-8"
-    spawn_env["HERMES_GATEWAY_DETACHED"] = "1"
-    _prepend_pythonpath(spawn_env, [str(PROJECT_ROOT), *extra_pythonpath])
-    return spawn_env
-
-
 def launch_detached_profile_gateway_restart(profile: str, old_pid: int) -> bool:
     """Relaunch a manually-run profile gateway after its current PID exits."""
     if old_pid <= 0:
@@ -744,33 +703,14 @@ def launch_detached_profile_gateway_restart(profile: str, old_pid: int) -> bool:
         """
     ).strip()
 
-    # Resolve the watcher interpreter to the windowless base ``pythonw.exe``
-    # on Windows for the same reason as the respawned gateway (see
-    # ``_gateway_run_args_for_profile``): ``sys.executable`` during a
-    # GUI-driven ``hermes update`` is a console ``python.exe`` whose uv venv
-    # launcher re-execs a visible console.  ``_resolve_detached_python`` is a
-    # no-op shape on non-Windows callers because we only consult it under the
-    # ``is_windows()`` guard below.
-    watcher_python = sys.executable
-    if is_windows():
-        from hermes_cli.gateway_windows import _resolve_detached_python
-
-        watcher_python, _wv, _wpp = _resolve_detached_python(sys.executable)
-
     watcher_argv = [
-        watcher_python,
+        sys.executable,
         "-c",
         watcher,
         str(old_pid),
         *_gateway_run_args_for_profile(profile),
     ]
 
-    # The watcher inherits this env and the respawned gateway inherits it from
-    # the watcher, so the base-``pythonw.exe`` legs can import ``hermes_cli``
-    # without the venv launcher shim.  No-op on POSIX (returns os.environ copy
-    # unchanged), preserving the pre-fix spawn behaviour bit-for-bit there.
-    spawn_env = _gateway_respawn_env(dict(os.environ))
-
     # Same platform-aware detach for the watcher process itself — so
     # closing the user's terminal doesn't kill the watcher.
     try:
@@ -778,7 +718,6 @@ def launch_detached_profile_gateway_restart(profile: str, old_pid: int) -> bool:
             watcher_argv,
             stdout=subprocess.DEVNULL,
             stderr=subprocess.DEVNULL,
-            env=spawn_env,
             **windows_detach_popen_kwargs(),
         )
     except OSError:
@@ -797,7 +736,6 @@ def launch_detached_profile_gateway_restart(profile: str, old_pid: int) -> bool:
                 watcher_argv,
                 stdout=subprocess.DEVNULL,
                 stderr=subprocess.DEVNULL,
-                env=spawn_env,
                 **fallback_kwargs,
             )
         except OSError:

hermes_cli/main.py

@@ -334,21 +334,66 @@ sys.path.insert(0, str(PROJECT_ROOT))
 # 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."""
+    """Pre-parse --profile/-p and set HERMES_HOME before imports."""
     argv = sys.argv[1:]
     profile_name = None
     consume = 0
+    profile_index = None
 
-    # 1. Check for explicit -p / --profile flag
-    for i, arg in enumerate(argv):
+    def _inside_mcp_add_args(index: int) -> bool:
+        """True once argv reaches `hermes mcp add ... --args <command argv>`.
+
+        ``mcp add --args`` is command-argv passthrough. Flags after that point
+        belong to the child MCP command (for example Docker MCP Toolkit's
+        ``--profile``), not to Hermes' own profile selector.
+        """
+        try:
+            mcp_index = argv.index("mcp", 0, index)
+            argv.index("add", mcp_index + 1, index)
+        except ValueError:
+            return False
+        return True
+
+    # 1. Check for explicit -p / --profile flag. Historically this worked even
+    # after the subcommand (`hermes chat -p coder`), so keep scanning broadly.
+    # The exception is command-argv passthrough regions such as `mcp add --args`.
+    value_flags = {
+        "-z", "--oneshot",
+        "-m", "--model",
+        "--provider",
+        "-t", "--toolsets",
+        "-r", "--resume",
+        "-s", "--skills",
+    }
+    optional_value_flags = {"-c", "--continue"}
+    i = 0
+    while i < len(argv):
+        arg = argv[i]
+        if arg == "--":
+            break
+        if arg == "--args" and _inside_mcp_add_args(i):
+            break
         if arg in {"--profile", "-p"} and i + 1 < len(argv):
             profile_name = argv[i + 1]
             consume = 2
+            profile_index = i
             break
-        elif arg.startswith("--profile="):
+        if arg.startswith("--profile="):
             profile_name = arg.split("=", 1)[1]
             consume = 1
+            profile_index = i
             break
+        if "=" not in arg and arg in value_flags and i + 1 < len(argv):
+            i += 2
+        elif (
+            "=" not in arg
+            and arg in optional_value_flags
+            and i + 1 < len(argv)
+            and not argv[i + 1].startswith("-")
+        ):
+            i += 2
+        else:
+            i += 1
 
     # 1b. Reject values that can't be valid profile names (e.g. pytest's
     # "-p no:xdist" would be misread as profile "no:xdist" otherwise).
@@ -360,6 +405,7 @@ def _apply_profile_override() -> None:
         if not _re.match(r"^[a-z0-9][a-z0-9_-]{0,63}$", profile_name):
             profile_name = None
             consume = 0
+            profile_index = None
 
     # 1.5 If HERMES_HOME is already set and no explicit flag was given, trust it
     # only when it already points to a specific profile directory.  The
@@ -407,16 +453,9 @@ def _apply_profile_override() -> None:
             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
+        if consume > 0 and profile_index is not None:
+            start = profile_index + 1  # +1 because argv is sys.argv[1:]
+            sys.argv = sys.argv[:start] + sys.argv[start + consume :]
 
 
 _apply_profile_override()
@@ -1523,6 +1562,8 @@ def _ensure_tui_node() -> None:
             env={**os.environ, "HERMES_HOME": hermes_home},
             capture_output=True,
             text=True,
+            encoding="utf-8",
+            errors="replace",
             check=False,
         )
     except (OSError, subprocess.SubprocessError):
@@ -1647,6 +1688,8 @@ def _make_tui_argv(tui_dir: Path, tui_dev: bool) -> tuple[list[str], Path]:
             stdout=subprocess.PIPE,
             stderr=subprocess.PIPE,
             text=True,
+            encoding="utf-8",
+            errors="replace",
             env={**os.environ, "CI": "1"},
         )
         if result.returncode != 0:
@@ -1671,6 +1714,8 @@ def _make_tui_argv(tui_dir: Path, tui_dev: bool) -> tuple[list[str], Path]:
             cwd=str(ink_dir),
             capture_output=True,
             text=True,
+            encoding="utf-8",
+            errors="replace",
         )
         if result.returncode != 0:
             combined = f"{result.stdout or ''}{result.stderr or ''}".strip()
@@ -1699,6 +1744,8 @@ def _make_tui_argv(tui_dir: Path, tui_dev: bool) -> tuple[list[str], Path]:
             cwd=str(tui_dir),
             capture_output=True,
             text=True,
+            encoding="utf-8",
+            errors="replace",
         )
         if result.returncode != 0:
             combined = f"{result.stdout or ''}{result.stderr or ''}".strip()
@@ -2372,6 +2419,8 @@ def cmd_whatsapp(args):
                 stdout=subprocess.DEVNULL,
                 stderr=subprocess.PIPE,
                 text=True,
+                encoding="utf-8",
+                errors="replace",
             )
         except KeyboardInterrupt:
             print("\n  ✗ Install cancelled")

hermes_cli/mcp_config.py

@@ -288,6 +288,8 @@ def cmd_mcp_add(args):
     # hermes_cli/main.py for why the dest is renamed.
     command = getattr(args, "mcp_command", None)
     cmd_args = getattr(args, "args", None) or []
+    if cmd_args and cmd_args[0] == "--":
+        cmd_args = cmd_args[1:]
     auth_type = getattr(args, "auth", None)
     preset_name = getattr(args, "preset", None)
     raw_env = getattr(args, "env", None)

hermes_cli/subcommands/mcp.py

@@ -6,6 +6,7 @@ Handler injected to avoid importing ``main``.
 
 from __future__ import annotations
 
+import argparse
 from typing import Callable
 
 from hermes_cli.subcommands._shared import add_accept_hooks_flag
@@ -52,7 +53,10 @@ def build_mcp_parser(subparsers, *, cmd_mcp: Callable) -> None:
         "--command", dest="mcp_command", help="Stdio command (e.g. npx)"
     )
     mcp_add_p.add_argument(
-        "--args", nargs="*", default=[], help="Arguments for stdio command"
+        "--args",
+        nargs=argparse.REMAINDER,
+        default=[],
+        help="Arguments for stdio command; must be the last option",
     )
     mcp_add_p.add_argument("--auth", choices=["oauth", "header"], help="Auth method")
     mcp_add_p.add_argument("--preset", help="Known MCP preset name")

hermes_cli/web_server.py

@@ -4468,22 +4468,27 @@ def _truncate_token(value: Optional[str], visible: int = 6) -> str:
 
 
 def _anthropic_oauth_status() -> Dict[str, Any]:
-    """Combined status across the three Anthropic credential sources we read.
+    """Status for the "Anthropic API Key" catalog entry.
 
-    Hermes resolves Anthropic creds in this order at runtime:
-    1. ``~/.hermes/.anthropic_oauth.json`` — Hermes-managed PKCE flow
-    2. ``~/.claude/.credentials.json`` — Claude Code CLI credentials (auto)
-    3. ``ANTHROPIC_TOKEN`` / ``ANTHROPIC_API_KEY`` env vars
-    The dashboard reports the highest-priority source that's actually present.
+    Two sources, in priority order:
+    1. ``~/.hermes/.anthropic_oauth.json`` — Hermes-managed PKCE flow (what
+       this entry's Connect button writes)
+    2. ``ANTHROPIC_API_KEY`` → ``ANTHROPIC_TOKEN`` → ``CLAUDE_CODE_OAUTH_TOKEN``
+       env vars (registry order) — from ``.env``, the shell, or an external
+       secret source like Bitwarden (whose keys are injected into the process
+       env during ``load_hermes_dotenv()``, so the same check covers them)
+
+    Claude Code's ``~/.claude/.credentials.json`` is deliberately NOT read
+    here — it has its own dedicated catalog entry (``claude-code`` →
+    ``_claude_code_only_status``). Reporting it under the API-key entry
+    double-counts the token and shadows a real ANTHROPIC_API_KEY.
     """
     try:
         from agent.anthropic_adapter import (
             read_hermes_oauth_credentials,
-            read_claude_code_credentials,
             _HERMES_OAUTH_FILE,
         )
     except ImportError:
-        read_claude_code_credentials = None  # type: ignore
         read_hermes_oauth_credentials = None  # type: ignore
         _HERMES_OAUTH_FILE = None  # type: ignore
 
@@ -4503,29 +4508,33 @@ def _anthropic_oauth_status() -> Dict[str, Any]:
             "has_refresh_token": bool(hermes_creds.get("refreshToken")),
         }
 
-    cc_creds = None
-    if read_claude_code_credentials:
-        try:
-            cc_creds = read_claude_code_credentials()
-        except Exception:
-            cc_creds = None
-    if cc_creds and cc_creds.get("accessToken"):
-        return {
-            "logged_in": True,
-            "source": "claude_code",
-            "source_label": "Claude Code (~/.claude/.credentials.json)",
-            "token_preview": _truncate_token(cc_creds.get("accessToken")),
-            "expires_at": cc_creds.get("expiresAt"),
-            "has_refresh_token": bool(cc_creds.get("refreshToken")),
-        }
+    # Env-var / secret-source path. ``get_env_value`` checks the process
+    # environment first (where Bitwarden-sourced secrets land) then .env.
+    env_var_order: tuple = ("ANTHROPIC_API_KEY", "ANTHROPIC_TOKEN", "CLAUDE_CODE_OAUTH_TOKEN")
+    try:
+        from hermes_cli.auth import PROVIDER_REGISTRY
+        env_var_order = PROVIDER_REGISTRY["anthropic"].api_key_env_vars
+    except (ImportError, KeyError):
+        pass
+    try:
+        from hermes_cli.config import get_env_value
+    except ImportError:
+        get_env_value = None  # type: ignore
+    try:
+        from hermes_cli.env_loader import format_secret_source_suffix
+    except ImportError:
+        format_secret_source_suffix = None  # type: ignore
 
-    env_token = os.getenv("ANTHROPIC_TOKEN") or os.getenv("CLAUDE_CODE_OAUTH_TOKEN")
-    if env_token:
+    for var in env_var_order:
+        value = (get_env_value(var) if get_env_value else None) or os.getenv(var)
+        if not value:
+            continue
+        suffix = format_secret_source_suffix(var) if format_secret_source_suffix else ""
         return {
             "logged_in": True,
             "source": "env_var",
-            "source_label": "ANTHROPIC_TOKEN environment variable",
-            "token_preview": _truncate_token(env_token),
+            "source_label": f"{var}{suffix}",
+            "token_preview": _truncate_token(value),
             "expires_at": None,
             "has_refresh_token": False,
         }

tests/agent/test_bedrock_adapter.py

@@ -1471,3 +1471,127 @@ class TestCallConverseInvalidatesOnStaleError:
         )
 
         assert _bedrock_runtime_client_cache.get("us-east-1") is live_client
+
+
+class TestStreamingAccessDeniedDetection:
+    """is_streaming_access_denied_error() recognizes IAM denials of
+    bedrock:InvokeModelWithResponseStream (InvokeModel-only policies)."""
+
+    def _denied_client_error(self):
+        from botocore.exceptions import ClientError
+        return ClientError(
+            error_response={
+                "Error": {
+                    "Code": "AccessDeniedException",
+                    "Message": (
+                        "User: arn:aws:iam::123456789012:user/x is not "
+                        "authorized to perform: "
+                        "bedrock:InvokeModelWithResponseStream on resource: "
+                        "arn:aws:bedrock:us-east-1::foundation-model/"
+                        "anthropic.claude-3-sonnet-20240229-v1:0"
+                    ),
+                }
+            },
+            operation_name="ConverseStream",
+        )
+
+    def test_matches_access_denied_client_error(self):
+        pytest.importorskip("botocore", reason="botocore required for Bedrock exception tests")
+        from agent.bedrock_adapter import is_streaming_access_denied_error
+        assert is_streaming_access_denied_error(self._denied_client_error()) is True
+
+    def test_ignores_access_denied_for_other_actions(self):
+        """AccessDenied on InvokeModel itself is NOT a streaming-only denial."""
+        pytest.importorskip("botocore", reason="botocore required for Bedrock exception tests")
+        from agent.bedrock_adapter import is_streaming_access_denied_error
+        from botocore.exceptions import ClientError
+        exc = ClientError(
+            error_response={
+                "Error": {
+                    "Code": "AccessDeniedException",
+                    "Message": (
+                        "User is not authorized to perform: bedrock:InvokeModel"
+                    ),
+                }
+            },
+            operation_name="Converse",
+        )
+        assert is_streaming_access_denied_error(exc) is False
+
+    def test_ignores_validation_error_mentioning_action(self):
+        """Non-authz ClientErrors don't match even if the action name appears."""
+        pytest.importorskip("botocore", reason="botocore required for Bedrock exception tests")
+        from agent.bedrock_adapter import is_streaming_access_denied_error
+        from botocore.exceptions import ClientError
+        exc = ClientError(
+            error_response={
+                "Error": {
+                    "Code": "ValidationException",
+                    "Message": "InvokeModelWithResponseStream input malformed",
+                }
+            },
+            operation_name="ConverseStream",
+        )
+        assert is_streaming_access_denied_error(exc) is False
+
+    def test_matches_wrapped_sdk_permission_error(self):
+        """Non-ClientError wrappers (AnthropicBedrock SDK) match on message."""
+        from agent.bedrock_adapter import is_streaming_access_denied_error
+        exc = RuntimeError(
+            "PermissionDeniedError: user is not authorized to perform: "
+            "bedrock:InvokeModelWithResponseStream"
+        )
+        assert is_streaming_access_denied_error(exc) is True
+
+    def test_ignores_unrelated_errors(self):
+        from agent.bedrock_adapter import is_streaming_access_denied_error
+        assert is_streaming_access_denied_error(ValueError("boom")) is False
+        assert is_streaming_access_denied_error(
+            RuntimeError("stream not supported")
+        ) is False
+
+
+class TestCallConverseStreamIamFallback:
+    """call_converse_stream() falls back to converse() when IAM denies the
+    streaming action — InvokeModel-only policies keep working."""
+
+    def test_falls_back_to_converse_on_streaming_denial(self):
+        pytest.importorskip("botocore", reason="botocore required for Bedrock exception tests")
+        from agent.bedrock_adapter import (
+            _bedrock_runtime_client_cache,
+            call_converse_stream,
+            reset_client_cache,
+        )
+        from botocore.exceptions import ClientError
+
+        reset_client_cache()
+        client = MagicMock()
+        client.converse_stream.side_effect = ClientError(
+            error_response={
+                "Error": {
+                    "Code": "AccessDeniedException",
+                    "Message": (
+                        "User is not authorized to perform: "
+                        "bedrock:InvokeModelWithResponseStream"
+                    ),
+                }
+            },
+            operation_name="ConverseStream",
+        )
+        client.converse.return_value = {
+            "output": {"message": {"role": "assistant", "content": [{"text": "hi"}]}},
+            "stopReason": "end_turn",
+            "usage": {"inputTokens": 1, "outputTokens": 1, "totalTokens": 2},
+        }
+        _bedrock_runtime_client_cache["us-east-1"] = client
+
+        result = call_converse_stream(
+            region="us-east-1",
+            model="anthropic.claude-3-sonnet-20240229-v1:0",
+            messages=[{"role": "user", "content": "hi"}],
+        )
+
+        client.converse.assert_called_once()
+        assert result.choices[0].message.content == "hi"
+        # Not a stale connection — client stays cached.
+        assert _bedrock_runtime_client_cache.get("us-east-1") is client

tests/agent/test_coding_context.py

@@ -152,11 +152,14 @@ class TestProjectFacts:
         assert "make test" in block
         assert "make deploy" not in block
 
-    def test_context_files_listed(self, tmp_path):
+    def test_context_files_not_listed(self, tmp_path):
+        # Context files (AGENTS.md etc.) are injected into the system prompt
+        # in full as the Project Context block — naming them in the snapshot
+        # would be redundant.
         _git_init(tmp_path)
         (tmp_path / "AGENTS.md").write_text("# rules")
         block = cc.build_coding_workspace_block(tmp_path)
-        assert "Context files: AGENTS.md" in block
+        assert "Context files:" not in block
 
     def test_marker_only_project_gets_snapshot_without_git(self, tmp_path):
         # A non-git project (manifest only) still gets a workspace snapshot —
@@ -368,20 +371,24 @@ class TestProfiles:
         assert cc.GENERAL_PROFILE.toolset is None
         assert cc.GENERAL_PROFILE.guidance == ""
 
-    def test_skill_pruning_scoped_to_coding_posture(self, tmp_path):
-        # Coding posture hides clearly-non-coding categories; coding-adjacent
-        # ones stay visible (deny-list semantics).
+    def test_skill_demotion_scoped_to_coding_posture(self, tmp_path):
+        # Coding posture demotes clearly-non-coding categories to names-only
+        # in the index (never hides them — agent-created skills are the
+        # model's project memory and must stay recallable by name).
+        # Coding-adjacent categories keep full entries (deny-list semantics).
         _git_init(tmp_path)
-        coding = cc.resolve_runtime_mode(platform="cli", cwd=tmp_path, config={})
-        hidden = coding.hidden_skill_categories()
-        assert "social-media" in hidden and "smart-home" in hidden
-        for kept in ("github", "devops", "software-development", "data-science"):
-            assert kept not in hidden
-        # General posture hides nothing.
-        general = cc.resolve_runtime_mode(
-            platform="telegram", cwd=tmp_path, config={}
-        )
-        assert general.hidden_skill_categories() == frozenset()
+        for raw in ("auto", "on", "focus"):
+            mode = cc.resolve_runtime_mode(
+                platform="cli", cwd=tmp_path, config={"agent": {"coding_context": raw}}
+            )
+            assert mode.is_coding is True
+            compact = mode.compact_skill_categories()
+            assert "social-media" in compact and "smart-home" in compact
+            for kept in ("github", "devops", "software-development", "data-science"):
+                assert kept not in compact
+        # General posture demotes nothing.
+        general = cc.resolve_runtime_mode(platform="telegram", cwd=tmp_path, config={})
+        assert general.compact_skill_categories() == frozenset()
 
 
 # ── detection signals ───────────────────────────────────────────────────────

tests/agent/test_prompt_builder.py

@@ -276,8 +276,14 @@ class TestBuildSkillsSystemPrompt:
         # "search" should appear only once per category
         assert result.count("- search") == 1
 
-    def test_hidden_categories_pruned_with_note(self, monkeypatch, tmp_path):
-        """Posture-driven pruning drops whole categories and discloses it."""
+    def test_compact_categories_demoted_to_names_only(self, monkeypatch, tmp_path):
+        """Posture-driven demotion keeps every skill NAME visible.
+
+        Demoted categories lose their descriptions, never their entries —
+        full pruning caused silent capability loss in a real workflow
+        (agent-created skills are the model's project memory, and models
+        don't rediscover them via skills_list once the index goes quiet).
+        """
         monkeypatch.setenv("HERMES_HOME", str(tmp_path))
         for cat, name in (("social-media", "tweet-stuff"), ("github", "pr-review")):
             d = tmp_path / "skills" / cat / name
@@ -287,14 +293,18 @@ class TestBuildSkillsSystemPrompt:
             )
 
         result = build_skills_system_prompt(
-            hidden_categories=frozenset({"social-media"})
+            compact_categories=frozenset({"social-media"})
         )
-        assert "pr-review" in result
-        assert "tweet-stuff" not in result
-        # Disclosure note so the model knows the full catalog exists.
-        assert "skills_list" in result
+        # Coding-adjacent category keeps its full entry.
+        assert "pr-review" in result and "Does pr-review things" in result
+        # Demoted category: name stays visible, description is dropped.
+        assert "tweet-stuff" in result
+        assert "Does tweet-stuff things" not in result
+        assert "social-media [names only]" in result
+        # Disclosure note explains the demotion and how to load.
+        assert "skill_view" in result
 
-    def test_hidden_categories_prune_nested_and_miss_cache_separately(
+    def test_compact_categories_demote_nested_and_miss_cache_separately(
         self, monkeypatch, tmp_path
     ):
         monkeypatch.setenv("HERMES_HOME", str(tmp_path))
@@ -303,14 +313,16 @@ class TestBuildSkillsSystemPrompt:
         (d / "SKILL.md").write_text(
             "---\nname: thread-writer\ndescription: Write threads\n---\n"
         )
-        # Nested category ("social-media/twitter") pruned via its parent.
-        pruned = build_skills_system_prompt(
-            hidden_categories=frozenset({"social-media"})
+        # Nested category ("social-media/twitter") demoted via its parent:
+        # name visible, description gone.
+        compact = build_skills_system_prompt(
+            compact_categories=frozenset({"social-media"})
         )
-        assert "thread-writer" not in pruned
-        # Unfiltered call must not be served from the filtered cache entry.
+        assert "thread-writer" in compact
+        assert "Write threads" not in compact
+        # Unfiltered call must not be served from the compacted cache entry.
         full = build_skills_system_prompt()
-        assert "thread-writer" in full
+        assert "Write threads" in full
 
     def test_excludes_incompatible_platform_skills(self, monkeypatch, tmp_path):
         """Skills with platforms: [macos] should not appear on Linux."""

tests/gateway/test_telegram_voice_v0_regressions.py

@@ -0,0 +1,71 @@
+import sys
+from pathlib import Path
+from types import SimpleNamespace
+
+import pytest
+
+
+ROOT = Path(__file__).resolve().parents[2]
+if str(ROOT) not in sys.path:
+    sys.path.insert(0, str(ROOT))
+
+from gateway.config import Platform
+from gateway.platforms.telegram import TelegramAdapter
+from gateway.run import GatewayRunner
+from gateway.session import SessionSource
+
+
+def _source():
+    return SessionSource(platform=Platform.TELEGRAM, chat_id="12345", chat_type="dm")
+
+
+def _runner(adapter=None):
+    runner = object.__new__(GatewayRunner)
+    runner.config = SimpleNamespace(
+        stt_enabled=True,
+        group_sessions_per_user=True,
+        thread_sessions_per_user=False,
+    )
+    runner.adapters = {Platform.TELEGRAM: adapter} if adapter else {}
+    runner._consume_pending_native_image_paths = lambda _key: []
+    runner._session_key_for_source = lambda _source: "telegram:dm:12345"
+    runner._thread_metadata_for_source = lambda *_args, **_kwargs: {}
+    runner._reply_anchor_for_event = lambda _event: None
+    return runner
+
+
+def test_telegram_audio_size_gate_rejects_oversized_media_before_download():
+    adapter = object.__new__(TelegramAdapter)
+    adapter._max_doc_bytes = 1024
+
+    allowed, note = adapter._telegram_media_size_allowed(
+        SimpleNamespace(file_size=2048),
+        "voice message",
+    )
+
+    assert allowed is False
+    assert "exceeds" in note
+    assert "voice message" in note
+
+
+@pytest.mark.asyncio
+async def test_voice_tts_is_explicit_audio_reply_opt_in():
+    adapter = SimpleNamespace(
+        _auto_tts_disabled_chats=set(),
+        _auto_tts_enabled_chats=set(),
+    )
+    runner = _runner(adapter)
+    runner._voice_mode = {}
+    runner._voice_provider_mode = {}
+    runner._save_voice_modes = lambda: None
+    runner._save_voice_provider_modes = lambda: None
+
+    event = SimpleNamespace(
+        source=_source(),
+        get_command_args=lambda: "tts",
+    )
+    result = await GatewayRunner._handle_voice_command(runner, event)
+
+    assert runner._voice_mode["telegram:12345"] == "all"
+    assert "12345" in adapter._auto_tts_enabled_chats
+    assert result

tests/hermes_cli/test_apply_profile_override.py

@@ -138,3 +138,80 @@ class TestApplyProfileOverrideHermesHomeGuard:
         _apply_profile_override()
 
         assert os.environ.get("HERMES_HOME") is None
+
+    def test_subcommand_profile_flag_is_not_consumed(self, tmp_path, monkeypatch):
+        """Command argv flags named --profile must stay with that command.
+
+        Docker Desktop's MCP Toolkit uses `docker mcp gateway run --profile ...`.
+        When that argv is passed through `hermes mcp add --args`, the early
+        profile pre-parser must not interpret the Docker profile as a Hermes
+        profile.
+        """
+        hermes_root = tmp_path / ".hermes"
+        hermes_root.mkdir(parents=True, exist_ok=True)
+        argv = [
+            "hermes",
+            "mcp",
+            "add",
+            "docker-research",
+            "--command",
+            "docker",
+            "--args",
+            "mcp",
+            "gateway",
+            "run",
+            "--profile",
+            "research",
+        ]
+
+        monkeypatch.setattr(Path, "home", lambda: tmp_path)
+        monkeypatch.delenv("HERMES_HOME", raising=False)
+        monkeypatch.setattr(sys, "argv", list(argv))
+
+        from hermes_cli.main import _apply_profile_override
+        _apply_profile_override()
+
+        assert os.environ.get("HERMES_HOME") is None
+        assert sys.argv == argv
+
+    def test_profile_after_chat_subcommand_is_still_consumed(self, tmp_path, monkeypatch):
+        """Profile flags historically work after normal Hermes subcommands."""
+        result = _run_apply_profile_override(
+            tmp_path,
+            monkeypatch,
+            hermes_home=None,
+            active_profile="coder",
+            argv=["hermes", "chat", "-p", "coder", "-q", "hello"],
+        )
+
+        assert result is not None
+        assert result.endswith("coder")
+        assert sys.argv == ["hermes", "chat", "-q", "hello"]
+
+    def test_top_level_profile_after_value_flag_is_consumed(self, tmp_path, monkeypatch):
+        """Top-level --profile still works after other top-level value flags."""
+        result = _run_apply_profile_override(
+            tmp_path,
+            monkeypatch,
+            hermes_home=None,
+            active_profile="coder",
+            argv=["hermes", "-m", "gpt-5", "--profile", "coder", "chat"],
+        )
+
+        assert result is not None
+        assert result.endswith("coder")
+        assert sys.argv == ["hermes", "-m", "gpt-5", "chat"]
+
+    def test_top_level_profile_after_continue_flag_is_consumed(self, tmp_path, monkeypatch):
+        """--continue has an optional value, so a following --profile is a flag."""
+        result = _run_apply_profile_override(
+            tmp_path,
+            monkeypatch,
+            hermes_home=None,
+            active_profile="coder",
+            argv=["hermes", "--continue", "--profile", "coder"],
+        )
+
+        assert result is not None
+        assert result.endswith("coder")
+        assert sys.argv == ["hermes", "--continue"]

tests/hermes_cli/test_banner.py

@@ -167,3 +167,36 @@ def test_build_welcome_banner_disabled_mcp_shows_disabled_not_failed():
     assert "broken" in output
     assert "failed" in output
 
+
+def test_build_welcome_banner_configured_mcp_is_not_failed():
+    """A configured MCP server with no connection attempt yet is not a failure."""
+    with (
+        patch.object(model_tools, "check_tool_availability", return_value=(["web"], [])),
+        patch.object(banner, "get_available_skills", return_value={}),
+        patch.object(banner, "get_update_result", return_value=None),
+        patch.object(
+            tools.mcp_tool,
+            "get_mcp_status",
+            return_value=[
+                {
+                    "name": "docker-profile",
+                    "transport": "stdio",
+                    "tools": 0,
+                    "connected": False,
+                    "disabled": False,
+                    "status": "configured",
+                },
+            ],
+        ),
+    ):
+        console = Console(record=True, force_terminal=False, color_system=None, width=160)
+        banner.build_welcome_banner(
+            console=console, model="anthropic/test-model", cwd="/tmp/project",
+            tools=[{"function": {"name": "read_file"}}],
+            get_toolset_for_tool=lambda n: "file",
+        )
+
+    output = console.export_text()
+    assert "docker-profile" in output
+    assert "configured" in output
+    assert "failed" not in output

tests/hermes_cli/test_gateway_update_respawn_pythonw.py

@@ -1,163 +0,0 @@
-"""Regression tests for the post-update gateway respawn interpreter on Windows.
-
-Background
-----------
-When the Desktop GUI runs ``hermes update``, it spawns the post-update
-respawn watcher via
-``hermes_cli.gateway.launch_detached_profile_gateway_restart``.  That watcher
-polls the old gateway PID and, once it exits, respawns the gateway using the
-argv built by ``_gateway_run_args_for_profile``.
-
-The bug: that argv used ``get_python_path()`` — the *console* ``python.exe``.
-For uv-created venvs, even ``venv\\Scripts\\pythonw.exe`` re-execs the base
-interpreter as a console ``python.exe`` (the re-exec is a fresh CreateProcess
-that does NOT inherit ``CREATE_NO_WINDOW``), so a blank console window pops up
-after every GUI-driven update.  ``hermes gateway start`` avoided this by going
-through ``_resolve_detached_python`` to get the *base* ``pythonw.exe`` plus a
-``VIRTUAL_ENV`` / ``PYTHONPATH`` overlay; the post-update respawn path never
-got the same treatment.
-
-These tests lock in:
-  * Windows respawn argv resolves to the base ``pythonw.exe`` (not the venv
-    ``Scripts`` shim, not console ``python.exe``).
-  * The respawn env carries the matching ``VIRTUAL_ENV`` / ``PYTHONPATH`` so a
-    base-interpreter respawn can still import ``hermes_cli``.
-  * POSIX behaviour is byte-for-byte unchanged (argv keeps ``sys.executable``'s
-    resolved path; env overlay is a no-op).
-"""
-
-import sys
-from pathlib import Path
-
-import pytest
-
-import hermes_cli.gateway as gateway
-import hermes_cli.gateway_windows as gateway_windows
-
-
-def _make_uv_venv(tmp_path: Path) -> dict[str, Path]:
-    """Fabricate a uv-style venv layout: venv Scripts python(w).exe + a base
-    interpreter referenced by pyvenv.cfg's ``home`` with its own pythonw.exe."""
-    project = tmp_path / "project"
-    scripts = project / "venv" / "Scripts"
-    site_packages = project / "venv" / "Lib" / "site-packages"
-    base = tmp_path / "uv" / "python" / "cpython-3.11-windows-x86_64-none"
-    for directory in (scripts, site_packages, base):
-        directory.mkdir(parents=True, exist_ok=True)
-
-    venv_python = scripts / "python.exe"
-    venv_pythonw = scripts / "pythonw.exe"
-    base_pythonw = base / "pythonw.exe"
-    for exe in (venv_python, venv_pythonw, base_pythonw):
-        exe.write_text("", encoding="utf-8")
-    (project / "venv" / "pyvenv.cfg").write_text(
-        f"home = {base}\nimplementation = CPython\nuv = 0.11.14\nversion_info = 3.11.15\n",
-        encoding="utf-8",
-    )
-    return {
-        "project": project,
-        "venv_python": venv_python,
-        "venv_pythonw": venv_pythonw,
-        "base_pythonw": base_pythonw,
-        "site_packages": site_packages,
-    }
-
-
-class TestRespawnArgvUsesBasePythonw:
-    def test_windows_uv_venv_resolves_base_pythonw(self, tmp_path, monkeypatch):
-        """The respawn argv must use the base pythonw.exe for a uv venv,
-        never the venv Scripts shim or console python.exe."""
-        layout = _make_uv_venv(tmp_path)
-        monkeypatch.setattr(gateway, "is_windows", lambda: True)
-        monkeypatch.setattr(gateway, "get_python_path", lambda: str(layout["venv_python"]))
-
-        argv = gateway._gateway_run_args_for_profile("default")
-
-        assert argv[0] == str(layout["base_pythonw"])
-        assert argv[0] != str(layout["venv_python"])
-        assert argv[0] != str(layout["venv_pythonw"])
-        assert argv[1:] == ["-m", "hermes_cli.main", "gateway", "run", "--replace"]
-
-    def test_windows_non_default_profile_keeps_profile_arg(self, tmp_path, monkeypatch):
-        layout = _make_uv_venv(tmp_path)
-        monkeypatch.setattr(gateway, "is_windows", lambda: True)
-        monkeypatch.setattr(gateway, "get_python_path", lambda: str(layout["venv_python"]))
-
-        argv = gateway._gateway_run_args_for_profile("work")
-
-        assert argv[0] == str(layout["base_pythonw"])
-        assert argv[1:] == [
-            "-m",
-            "hermes_cli.main",
-            "--profile",
-            "work",
-            "gateway",
-            "run",
-            "--replace",
-        ]
-
-
-class TestRespawnEnvOverlay:
-    def test_windows_overlay_sets_virtualenv_and_pythonpath(self, tmp_path, monkeypatch):
-        """A base-pythonw respawn needs VIRTUAL_ENV + PYTHONPATH so imports
-        resolve without the venv launcher shim."""
-        layout = _make_uv_venv(tmp_path)
-        monkeypatch.setattr(gateway, "is_windows", lambda: True)
-        monkeypatch.setattr(gateway, "get_python_path", lambda: str(layout["venv_python"]))
-
-        env = gateway._gateway_respawn_env({})
-
-        assert env["VIRTUAL_ENV"] == str(layout["project"] / "venv")
-        assert env["HERMES_GATEWAY_DETACHED"] == "1"
-        assert "PYTHONPATH" in env
-        # Repo root and the base-interpreter site-packages must both be on it.
-        assert str(gateway.PROJECT_ROOT) in env["PYTHONPATH"]
-        assert str(layout["site_packages"]) in env["PYTHONPATH"]
-
-    def test_windows_overlay_prepends_to_existing_pythonpath(self, tmp_path, monkeypatch):
-        layout = _make_uv_venv(tmp_path)
-        monkeypatch.setattr(gateway, "is_windows", lambda: True)
-        monkeypatch.setattr(gateway, "get_python_path", lambda: str(layout["venv_python"]))
-        monkeypatch.setenv("PYTHONPATH", "/preexisting/entry")
-
-        env = gateway._gateway_respawn_env({})
-
-        assert env["PYTHONPATH"].endswith("/preexisting/entry")
-        assert str(gateway.PROJECT_ROOT) in env["PYTHONPATH"]
-
-
-class TestPosixUnchanged:
-    """POSIX must be byte-for-byte identical to the pre-fix behaviour."""
-
-    def test_posix_argv_uses_get_python_path_verbatim(self, monkeypatch):
-        monkeypatch.setattr(gateway, "is_windows", lambda: False)
-        monkeypatch.setattr(gateway, "get_python_path", lambda: "/usr/bin/python3")
-
-        argv = gateway._gateway_run_args_for_profile("default")
-
-        assert argv == [
-            "/usr/bin/python3",
-            "-m",
-            "hermes_cli.main",
-            "gateway",
-            "run",
-            "--replace",
-        ]
-
-    def test_posix_env_overlay_is_noop(self, monkeypatch):
-        monkeypatch.setattr(gateway, "is_windows", lambda: False)
-        original = {"PATH": "/usr/bin", "FOO": "bar"}
-
-        result = gateway._gateway_respawn_env(dict(original))
-
-        assert result == original
-
-
-@pytest.mark.skipif(sys.platform != "win32", reason="Windows-specific regression")
-class TestLiveWindowsRespawn:
-    """On a real Windows host the resolver should pick a *windowed* interpreter
-    (pythonw) for the running gateway's own venv, with no console flag needed."""
-
-    def test_resolved_interpreter_is_windowless(self):
-        argv = gateway._gateway_run_args_for_profile("default")
-        assert argv[0].lower().endswith("pythonw.exe")

tests/hermes_cli/test_mcp_add_command_dest.py

@@ -41,6 +41,7 @@ def _build_parser():
     mcp_add.add_argument("name")
     mcp_add.add_argument("--url")
     mcp_add.add_argument("--command", dest="mcp_command")
+    mcp_add.add_argument("--args", nargs=argparse.REMAINDER, default=[])
 
     return parser
 
@@ -85,3 +86,26 @@ class TestMcpAddCommandDest:
         assert args.command == "mcp"
         assert args.mcp_command is None
         assert args.url is None
+
+    def test_args_passthrough_keeps_nested_option_flags(self):
+        """`--args` must keep command flags like Docker MCP's --profile."""
+        parser = _build_parser()
+        args = parser.parse_args(
+            [
+                "mcp",
+                "add",
+                "docker-research",
+                "--command",
+                "docker",
+                "--args",
+                "mcp",
+                "gateway",
+                "run",
+                "--profile",
+                "research",
+            ]
+        )
+
+        assert args.command == "mcp"
+        assert args.mcp_command == "docker"
+        assert args.args == ["mcp", "gateway", "run", "--profile", "research"]

tests/hermes_cli/test_tui_npm_install.py

@@ -26,6 +26,12 @@ def _touch_tui_entry(root: Path) -> None:
     entry.write_text("console.log('tui')")
 
 
+def _assert_utf8_replace_capture(kwargs: dict) -> None:
+    assert kwargs["text"] is True
+    assert kwargs["encoding"] == "utf-8"
+    assert kwargs["errors"] == "replace"
+
+
 def test_need_install_when_ink_missing(tmp_path: Path, main_mod) -> None:
     (tmp_path / "package-lock.json").write_text("{}")
     assert main_mod._tui_need_npm_install(tmp_path) is True
@@ -228,6 +234,8 @@ def test_make_tui_argv_scopes_npm_install_on_termux_workspace(
         "--include-workspace-root=false",
     ]
     assert calls[0][1]["cwd"] == str(tmp_path)
+    _assert_utf8_replace_capture(calls[0][1])
+    _assert_utf8_replace_capture(calls[1][1])
 
 
 def test_make_tui_argv_keeps_desktop_workspace_install_behaviour(
@@ -263,6 +271,8 @@ def test_make_tui_argv_keeps_desktop_workspace_install_behaviour(
         "--progress=false",
     ]
     assert calls[0][1]["cwd"] == str(tmp_path)
+    _assert_utf8_replace_capture(calls[0][1])
+    _assert_utf8_replace_capture(calls[1][1])
 
 
 def test_make_tui_argv_keeps_desktop_always_build_behaviour(
@@ -286,6 +296,35 @@ def test_make_tui_argv_keeps_desktop_always_build_behaviour(
 
     assert calls
     assert calls[0][0][0] == ["/bin/npm", "run", "build"]
+    _assert_utf8_replace_capture(calls[0][1])
+
+
+def test_make_tui_argv_decodes_dev_prebuild_with_utf8_replace(
+    tmp_path: Path, main_mod, monkeypatch
+) -> None:
+    ink_dir = tmp_path / "packages" / "hermes-ink"
+    ink_dir.mkdir(parents=True)
+    tsx = tmp_path / "node_modules" / ".bin" / "tsx"
+    tsx.parent.mkdir(parents=True)
+    tsx.write_text("")
+
+    monkeypatch.setattr(main_mod, "_tui_need_npm_install", lambda _root: False)
+    monkeypatch.setattr(main_mod.shutil, "which", lambda name: f"/bin/{name}")
+    calls = []
+
+    def fake_run(*args, **kwargs):
+        calls.append((args, kwargs))
+        return types.SimpleNamespace(returncode=0, stdout="", stderr="")
+
+    monkeypatch.setattr(main_mod.subprocess, "run", fake_run)
+
+    argv, cwd = main_mod._make_tui_argv(tmp_path, tui_dev=True)
+
+    assert argv == [str(tsx), "src/entry.tsx"]
+    assert cwd == tmp_path
+    assert calls[0][0][0] == ["/bin/npm", "run", "build"]
+    assert calls[0][1]["cwd"] == str(ink_dir)
+    _assert_utf8_replace_capture(calls[0][1])
 
 
 # ── _workspace_root helper ──────────────────────────────────────────

tests/run_agent/test_streaming.py

@@ -1573,3 +1573,87 @@ class TestCopilotACPStreamingDecision:
             _use_streaming = False
 
         assert _use_streaming is True
+
+
+class TestBedrockIamStreamingFallback:
+    """bedrock_converse streaming branch: IAM denial of
+    InvokeModelWithResponseStream falls back to converse() inline and sets
+    _disable_streaming for the rest of the session."""
+
+    def _make_bedrock_agent(self):
+        from run_agent import AIAgent
+
+        agent = AIAgent(
+            api_key="test-key",
+            base_url="https://openrouter.ai/api/v1",
+            model="anthropic.claude-3-sonnet-20240229-v1:0",
+            quiet_mode=True,
+            skip_context_files=True,
+            skip_memory=True,
+        )
+        agent.api_mode = "bedrock_converse"
+        agent._interrupt_requested = False
+        return agent
+
+    def test_iam_denial_falls_back_inline_and_disables_streaming(self):
+        pytest.importorskip("botocore", reason="botocore required for Bedrock tests")
+        from botocore.exceptions import ClientError
+
+        agent = self._make_bedrock_agent()
+
+        client = MagicMock()
+        client.converse_stream.side_effect = ClientError(
+            error_response={
+                "Error": {
+                    "Code": "AccessDeniedException",
+                    "Message": (
+                        "User is not authorized to perform: "
+                        "bedrock:InvokeModelWithResponseStream"
+                    ),
+                }
+            },
+            operation_name="ConverseStream",
+        )
+        client.converse.return_value = {
+            "output": {"message": {"role": "assistant", "content": [{"text": "hi"}]}},
+            "stopReason": "end_turn",
+            "usage": {"inputTokens": 1, "outputTokens": 1, "totalTokens": 2},
+        }
+
+        with patch(
+            "agent.bedrock_adapter._get_bedrock_runtime_client",
+            return_value=client,
+        ):
+            response = agent._interruptible_streaming_api_call(
+                {"modelId": agent.model, "messages": []}
+            )
+
+        client.converse.assert_called_once()
+        assert response.choices[0].message.content == "hi"
+        assert getattr(agent, "_disable_streaming", False) is True
+
+    def test_other_bedrock_errors_still_propagate(self):
+        pytest.importorskip("botocore", reason="botocore required for Bedrock tests")
+        from botocore.exceptions import ClientError
+
+        agent = self._make_bedrock_agent()
+
+        client = MagicMock()
+        client.converse_stream.side_effect = ClientError(
+            error_response={
+                "Error": {"Code": "ThrottlingException", "Message": "slow down"}
+            },
+            operation_name="ConverseStream",
+        )
+
+        with patch(
+            "agent.bedrock_adapter._get_bedrock_runtime_client",
+            return_value=client,
+        ):
+            with pytest.raises(ClientError):
+                agent._interruptible_streaming_api_call(
+                    {"modelId": agent.model, "messages": []}
+                )
+
+        client.converse.assert_not_called()
+        assert getattr(agent, "_disable_streaming", False) is False

tests/tools/test_mcp_tool.py

@@ -82,6 +82,56 @@ class TestLoadMCPConfig:
             assert result == {}
 
 
+class TestMCPStatus:
+    def test_status_distinguishes_configured_connecting_failed_and_disabled(
+        self, monkeypatch
+    ):
+        import tools.mcp_tool as mcp_tool
+
+        monkeypatch.setattr(
+            mcp_tool,
+            "_load_mcp_config",
+            lambda: {
+                "configured": {"command": "docker", "args": ["mcp", "gateway", "run"]},
+                "connecting": {"command": "slow-mcp"},
+                "failed": {"command": "bad-mcp"},
+                "disabled": {"command": "off-mcp", "enabled": False},
+            },
+        )
+        with mcp_tool._lock:
+            saved_servers = dict(mcp_tool._servers)
+            saved_connecting = set(mcp_tool._server_connecting)
+            saved_errors = dict(mcp_tool._server_connect_errors)
+            mcp_tool._servers.clear()
+            mcp_tool._server_connecting.clear()
+            mcp_tool._server_connect_errors.clear()
+            mcp_tool._server_connecting.add("connecting")
+            mcp_tool._server_connect_errors["failed"] = "Connection closed"
+
+        try:
+            statuses = {
+                entry["name"]: entry
+                for entry in mcp_tool.get_mcp_status()
+            }
+        finally:
+            with mcp_tool._lock:
+                mcp_tool._servers.clear()
+                mcp_tool._servers.update(saved_servers)
+                mcp_tool._server_connecting.clear()
+                mcp_tool._server_connecting.update(saved_connecting)
+                mcp_tool._server_connect_errors.clear()
+                mcp_tool._server_connect_errors.update(saved_errors)
+
+        assert statuses["configured"]["status"] == "configured"
+        assert statuses["configured"]["connected"] is False
+        assert statuses["configured"]["disabled"] is False
+        assert statuses["connecting"]["status"] == "connecting"
+        assert statuses["failed"]["status"] == "failed"
+        assert statuses["failed"]["error"] == "Connection closed"
+        assert statuses["disabled"]["status"] == "disabled"
+        assert statuses["disabled"]["disabled"] is True
+
+
 # ---------------------------------------------------------------------------
 # Schema conversion
 # ---------------------------------------------------------------------------
@@ -1378,6 +1428,33 @@ class TestBuildSafeEnv:
         assert "DATABASE_URL" not in result
         assert "API_SECRET" not in result
 
+    def test_windows_location_vars_passed_without_secrets(self):
+        """Windows launcher tools need location vars, but secrets stay filtered."""
+        from tools.mcp_tool import _build_safe_env
+
+        fake_env = {
+            "PATH": r"C:\Windows\System32",
+            "ProgramFiles": r"C:\Program Files",
+            "ProgramData": r"C:\ProgramData",
+            "ProgramW6432": r"C:\Program Files",
+            "LOCALAPPDATA": r"C:\Users\alice\AppData\Local",
+            "APPDATA": r"C:\Users\alice\AppData\Roaming",
+            "USERPROFILE": r"C:\Users\alice",
+            "GITHUB_TOKEN": "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
+            "OPENAI_API_KEY": "sk-proj-abc123",
+        }
+        with patch.dict("os.environ", fake_env, clear=True):
+            result = _build_safe_env(None)
+
+        assert result["ProgramFiles"] == r"C:\Program Files"
+        assert result["ProgramData"] == r"C:\ProgramData"
+        assert result["ProgramW6432"] == r"C:\Program Files"
+        assert result["LOCALAPPDATA"].endswith("Local")
+        assert result["APPDATA"].endswith("Roaming")
+        assert result["USERPROFILE"] == r"C:\Users\alice"
+        assert "GITHUB_TOKEN" not in result
+        assert "OPENAI_API_KEY" not in result
+
 
 # ---------------------------------------------------------------------------
 # _sanitize_error

tools/mcp_tool.py

@@ -268,6 +268,38 @@ _SAFE_ENV_KEYS = frozenset({
     "PATH", "HOME", "USER", "LANG", "LC_ALL", "TERM", "SHELL", "TMPDIR",
 })
 
+_SAFE_ENV_KEYS_CASE_INSENSITIVE = frozenset({
+    # Windows process/location vars. These are needed by launcher-style tools
+    # such as Docker Desktop's MCP plugin discovery, and do not carry secrets.
+    "ALLUSERSPROFILE",
+    "APPDATA",
+    "COMMONPROGRAMFILES",
+    "COMMONPROGRAMFILES(X86)",
+    "COMMONPROGRAMW6432",
+    "COMPUTERNAME",
+    "COMSPEC",
+    "HOMEDRIVE",
+    "HOMEPATH",
+    "LOCALAPPDATA",
+    "NUMBER_OF_PROCESSORS",
+    "OS",
+    "PATHEXT",
+    "PROCESSOR_ARCHITECTURE",
+    "PROGRAMDATA",
+    "PROGRAMFILES",
+    "PROGRAMFILES(X86)",
+    "PROGRAMW6432",
+    "PUBLIC",
+    "SYSTEMDRIVE",
+    "SYSTEMROOT",
+    "TEMP",
+    "TMP",
+    "USERDOMAIN",
+    "USERNAME",
+    "USERPROFILE",
+    "WINDIR",
+})
+
 # Regex for credential patterns to strip from error messages
 _CREDENTIAL_PATTERN = re.compile(
     r"(?:"
@@ -305,7 +337,11 @@ def _build_safe_env(user_env: Optional[dict]) -> dict:
     """
     env = {}
     for key, value in os.environ.items():
-        if key in _SAFE_ENV_KEYS or key.startswith("XDG_"):
+        if (
+            key in _SAFE_ENV_KEYS
+            or key.upper() in _SAFE_ENV_KEYS_CASE_INSENSITIVE
+            or key.startswith("XDG_")
+        ):
             env[key] = value
     if user_env:
         env.update(user_env)
@@ -1986,6 +2022,8 @@ class MCPServerTask:
 # ---------------------------------------------------------------------------
 
 _servers: Dict[str, MCPServerTask] = {}
+_server_connecting: set[str] = set()
+_server_connect_errors: Dict[str, str] = {}
 
 # Circuit breaker: consecutive error counts per server.  After
 # _CIRCUIT_BREAKER_THRESHOLD consecutive failures, the handler returns
@@ -2372,8 +2410,8 @@ _mcp_tool_server_names: Dict[str, str] = {}
 _mcp_loop: Optional[asyncio.AbstractEventLoop] = None
 _mcp_thread: Optional[threading.Thread] = None
 
-# Protects _mcp_loop, _mcp_thread, _servers, _parallel_safe_servers,
-# _mcp_tool_server_names, and _stdio_pids.
+# Protects _mcp_loop, _mcp_thread, _servers, MCP connection status maps,
+# _parallel_safe_servers, _mcp_tool_server_names, and _stdio_pids.
 _lock = threading.Lock()
 
 # PIDs of stdio MCP server subprocesses.  Tracked so we can force-kill
@@ -3517,6 +3555,8 @@ async def _discover_and_register_server(name: str, config: dict) -> List[str]:
         timeout=connect_timeout,
     )
     with _lock:
+        _server_connecting.discard(name)
+        _server_connect_errors.pop(name, None)
         _servers[name] = server
 
     registered_names = _register_server_tools(name, server, config)
@@ -3563,6 +3603,9 @@ def register_mcp_servers(servers: Dict[str, dict]) -> List[str]:
             for k, v in servers.items()
             if k not in _servers and _parse_boolish(v.get("enabled", True), default=True)
         }
+        _server_connecting.update(new_servers)
+        for srv_name in new_servers:
+            _server_connect_errors.pop(srv_name, None)
         # Track which servers opt-in to parallel tool calls (idempotent).
         for srv_name, srv_cfg in servers.items():
             if _parse_boolish(srv_cfg.get("supports_parallel_tool_calls", False), default=False):
@@ -3590,12 +3633,20 @@ def register_mcp_servers(servers: Dict[str, dict]) -> List[str]:
         for name, result in zip(server_names, results):
             if isinstance(result, BaseException):
                 command = new_servers.get(name, {}).get("command")
+                message = _format_connect_error(result)
+                with _lock:
+                    _server_connecting.discard(name)
+                    _server_connect_errors[name] = message
                 logger.warning(
                     "Failed to connect to MCP server '%s'%s: %s",
                     name,
                     f" (command={command})" if command else "",
-                    _format_connect_error(result),
+                    message,
                 )
+            else:
+                with _lock:
+                    _server_connecting.discard(name)
+                    _server_connect_errors.pop(name, None)
 
     # Per-server timeouts are handled inside _discover_and_register_server.
     # The outer timeout is generous: 120s total for parallel discovery.
@@ -3700,8 +3751,10 @@ def is_mcp_tool_parallel_safe(tool_name: str) -> bool:
 def get_mcp_status() -> List[dict]:
     """Return status of all configured MCP servers for banner display.
 
-    Returns a list of dicts with keys: name, transport, tools, connected.
-    Includes both successfully connected servers and configured-but-failed ones.
+    Returns a list of dicts with keys: name, transport, tools, connected,
+    disabled, and status. Includes connected servers, disabled servers,
+    in-flight connection attempts, recorded failures, and servers that are
+    configured but have not been started in this process yet.
     """
     result: List[dict] = []
 
@@ -3712,6 +3765,8 @@ def get_mcp_status() -> List[dict]:
 
     with _lock:
         active_servers = dict(_servers)
+        connecting = set(_server_connecting)
+        connect_errors = dict(_server_connect_errors)
 
     for name, cfg in configured.items():
         transport = cfg.get("transport", "http") if "url" in cfg else "stdio"
@@ -3724,11 +3779,12 @@ def get_mcp_status() -> List[dict]:
                 "tools": len(server._registered_tool_names) if hasattr(server, "_registered_tool_names") else len(server._tools),
                 "connected": True,
                 "disabled": False,
+                "status": "connected",
             }
             if server._sampling:
                 entry["sampling"] = dict(server._sampling.metrics)
             result.append(entry)
-        else:
+        elif not enabled:
             # A server with enabled: false is intentionally not connected — it is
             # disabled, not failed. Surface that distinction so consumers (banner,
             # TUI) can render "disabled" rather than an alarming "failed".
@@ -3737,7 +3793,36 @@ def get_mcp_status() -> List[dict]:
                 "transport": transport,
                 "tools": 0,
                 "connected": False,
-                "disabled": not enabled,
+                "disabled": True,
+                "status": "disabled",
+            })
+        elif name in connecting:
+            result.append({
+                "name": name,
+                "transport": transport,
+                "tools": 0,
+                "connected": False,
+                "disabled": False,
+                "status": "connecting",
+            })
+        elif name in connect_errors:
+            result.append({
+                "name": name,
+                "transport": transport,
+                "tools": 0,
+                "connected": False,
+                "disabled": False,
+                "status": "failed",
+                "error": connect_errors[name],
+            })
+        else:
+            result.append({
+                "name": name,
+                "transport": transport,
+                "tools": 0,
+                "connected": False,
+                "disabled": False,
+                "status": "configured",
             })
 
     return result

ui-tui/src/components/branding.tsx

@@ -254,6 +254,12 @@ export function SessionPanel({ info, maxWidth, sid, t }: SessionPanelProps) {
             <Text color={t.color.text}>
               {s.tools} tool{s.tools === 1 ? '' : 's'}
             </Text>
+          ) : s.disabled || s.status === 'disabled' ? (
+            <Text color={t.color.muted}>disabled</Text>
+          ) : s.status === 'connecting' ? (
+            <Text color={t.color.warn}>connecting</Text>
+          ) : s.status === 'configured' ? (
+            <Text color={t.color.muted}>configured</Text>
           ) : (
             <Text color={t.color.error}>failed</Text>
           )}

ui-tui/src/types.ts

@@ -138,6 +138,8 @@ export type SectionVisibility = Partial<Record<SectionName, DetailsMode>>
 
 export interface McpServerStatus {
   connected: boolean
+  disabled?: boolean
+  status?: 'configured' | 'connecting' | 'connected' | 'disabled' | 'failed'
   name: string
   tools: number
   transport: string

website/docs/reference/cli-commands.md

@@ -1180,7 +1180,7 @@ Manage MCP (Model Context Protocol) server configurations and run Hermes as an M
 | `catalog` | List Nous-approved MCPs (plain text, scriptable). |
 | `install <name>` | Install a catalog entry (e.g. `hermes mcp install n8n`). |
 | `serve [-v\|--verbose]` | Run Hermes as an MCP server — expose conversations to other agents. |
-| `add <name> [--url URL] [--command CMD] [--args ...] [--auth oauth\|header]` | Add a custom MCP server with automatic tool discovery. |
+| `add <name> [--url URL] [--command CMD] [--auth oauth\|header] [--args ...]` | Add a custom MCP server with automatic tool discovery. `--args` passes the remaining argv to the stdio command, so put it last. |
 | `remove <name>` (alias: `rm`) | Remove an MCP server from config. |
 | `list` (alias: `ls`) | List configured MCP servers. |
 | `test <name>` | Test connection to an MCP server. |