From 9dd9ef0ec99a87f078f7272b4323df5440b4b3f9 Mon Sep 17 00:00:00 2001
From: Austin Pickett <pickett.austin@gmail.com>
Date: Wed, 10 Jun 2026 20:43:22 -0400
Subject: [PATCH 01/28] fix(web): profiles page modal (#43858)

* fix(web): profiles page modal

* chore: drop unrelated package-lock.json changes

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

---------

Co-authored-by: Cursor <cursoragent@cursor.com>
---
 web/src/pages/ProfilesPage.tsx | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

diff --git a/web/src/pages/ProfilesPage.tsx b/web/src/pages/ProfilesPage.tsx
index 463e5a4120b8..bda2515528f0 100644
--- a/web/src/pages/ProfilesPage.tsx
+++ b/web/src/pages/ProfilesPage.tsx
@@ -794,7 +794,7 @@ export default function ProfilesPage() {
           <div
             className={cn(
               themedBody,
-              "relative w-full max-w-md border border-border bg-card shadow-2xl flex flex-col max-h-[90vh] overflow-y-auto",
+              "relative w-full max-w-md border border-border bg-card shadow-2xl flex flex-col max-h-[90vh]",
             )}
           >
             <Button
@@ -816,7 +816,7 @@ export default function ProfilesPage() {
               </h2>
             </header>
 
-            <div className="p-5 grid gap-4">
+            <div className="min-h-0 overflow-y-auto p-5 grid gap-4">
               <div className="grid gap-2">
                 <Label htmlFor="profile-name">{t.profiles.name}</Label>
 
@@ -1207,7 +1207,7 @@ export default function ProfilesPage() {
           <div
             className={cn(
               themedBody,
-              "relative w-full max-w-lg border border-border bg-card shadow-2xl flex flex-col max-h-[90vh] overflow-y-auto",
+              "relative w-full max-w-lg border border-border bg-card shadow-2xl flex flex-col max-h-[90vh]",
             )}
           >
             <Button
@@ -1234,7 +1234,12 @@ export default function ProfilesPage() {
               </h2>
             </header>
 
-            <div className="p-5 grid gap-4">
+            <div
+              className={cn(
+                "p-5 grid gap-4",
+                editorKind === "soul" && "min-h-0 overflow-y-auto",
+              )}
+            >
               {editorKind === "model" &&
                 (modelChoices !== null && modelChoices.length === 0 ? (
                   <p className="text-xs text-muted-foreground">{L.modelNone}</p>

From 615ad97928f042d401b83142fd7d9daf50f48915 Mon Sep 17 00:00:00 2001
From: xxxigm <54813621+xxxigm@users.noreply.github.com>
Date: Thu, 11 Jun 2026 08:21:38 +0700
Subject: [PATCH 02/28] fix(streaming): stop socket read timeout from
 preempting stale-stream detector (#43570)

* fix(streaming): stop socket read timeout from preempting stale-stream detector

The stale-stream detector is deliberately scaled to 180-300s so reasoning
models (e.g. Opus) can pause mid-stream during extended thinking. But the
httpx socket read timeout stayed at a flat 120s for cloud providers and fired
first, tearing down healthy reasoning streams before the detector (which owns
retry + diagnostics) could act. Symptom: every Copilot/Opus turn dies with
ReadTimeout at a consistent ~125s and never completes.

Floor the cloud socket read timeout at the stale-stream timeout so it can no
longer fire before the detector. Local providers and explicit
HERMES_STREAM_READ_TIMEOUT / request_timeout_seconds overrides are unchanged.

* test(streaming): pin read-timeout >= stale-stream invariant for cloud reasoning streams

Cover the contract that the httpx socket read timeout is never shorter than
the stale-stream detector for cloud providers on the default: small contexts
floor to 180s, >=50K to 240s, >=100K to 300s; explicit overrides win; local
providers and the unresolved-value fallback are unaffected.
---
 agent/chat_completion_helpers.py              |  28 +++++
 tests/agent/test_stream_read_timeout_floor.py | 111 ++++++++++++++++++
 2 files changed, 139 insertions(+)
 create mode 100644 tests/agent/test_stream_read_timeout_floor.py

diff --git a/agent/chat_completion_helpers.py b/agent/chat_completion_helpers.py
index ce066d55640c..783e85b3e938 100644
--- a/agent/chat_completion_helpers.py
+++ b/agent/chat_completion_helpers.py
@@ -1698,6 +1698,14 @@ def interruptible_streaming_api_call(agent, api_kwargs: dict, *, on_first_delta=
     # poll loop uses this to detect stale connections that keep receiving
     # SSE keep-alive pings but no actual data.
     last_chunk_time = {"t": time.time()}
+    # Stale-stream patience, shared between the httpx socket read timeout
+    # (built in ``_call_chat_completions`` below) and the stale-stream detector
+    # (computed further down, before the worker thread starts).  Initialized
+    # here so the read-timeout builder can floor itself at the stale value and
+    # never fire before the detector.  ``None`` until the detector value is
+    # resolved, so the builder degrades to its plain default if it ever runs
+    # first.
+    _stream_stale_timeout = None
 
     def _fire_first_delta():
         if not first_delta_fired["done"] and on_first_delta:
@@ -1734,6 +1742,26 @@ def interruptible_streaming_api_call(agent, api_kwargs: dict, *, on_first_delta=
                     "Local provider detected (%s) — stream read timeout raised to %.0fs",
                     agent.base_url, _stream_read_timeout,
                 )
+            elif (
+                _stream_read_timeout == 120.0
+                and _stream_stale_timeout is not None
+                and _stream_stale_timeout != float("inf")
+                and _stream_stale_timeout > _stream_read_timeout
+            ):
+                # Cloud reasoning models (e.g. Opus) routinely pause mid-stream
+                # for minutes during extended thinking.  The stale-stream
+                # detector is deliberately scaled up to tolerate this (180–300s,
+                # see the stale-timeout block below), but the raw httpx socket
+                # read timeout defaulted to a flat 120s and fired *first* —
+                # tearing down a healthy reasoning stream before the stale
+                # detector (which owns retry + diagnostics) could act.  Keep the
+                # socket read timeout in step with the detector so it no longer
+                # preempts it.
+                _stream_read_timeout = _stream_stale_timeout
+                logger.debug(
+                    "Cloud reasoning stream — read timeout raised to %.0fs to "
+                    "match stale-stream detector", _stream_read_timeout,
+                )
         # Cap connect/pool at 60s even when provider timeout is higher.
         # connect/pool cover TCP handshake, not model inference.
         _conn_cap = min(_base_timeout, 60.0) if _provider_timeout_cfg is not None else 30.0
diff --git a/tests/agent/test_stream_read_timeout_floor.py b/tests/agent/test_stream_read_timeout_floor.py
new file mode 100644
index 000000000000..0949866a0461
--- /dev/null
+++ b/tests/agent/test_stream_read_timeout_floor.py
@@ -0,0 +1,111 @@
+"""Stream read timeout must never preempt the stale-stream detector.
+
+Reasoning models (e.g. Opus) routinely pause mid-stream for minutes during
+extended thinking.  The stale-stream detector is deliberately scaled up to
+tolerate this (180s base, raised to 240s/300s for large contexts).  The httpx
+socket read timeout, however, defaulted to a flat 120s for cloud providers and
+fired *first* — tearing down a healthy reasoning stream before the stale
+detector (which owns retry + diagnostics) could act.
+
+These tests pin the invariant: for a cloud provider on the default read
+timeout, the httpx socket read timeout is floored at the stale-stream timeout
+so it can never fire before the detector.  They mirror the inline logic in
+``agent/chat_completion_helpers.py`` (the real builder lives deep inside a
+worker thread, so — like ``test_local_stream_timeout.py`` — the resolution is
+reproduced here rather than driven end-to-end).
+"""
+
+import os
+
+import pytest
+
+from agent.model_metadata import is_local_endpoint
+
+
+def _resolve_stale_timeout(base_url, est_tokens, stale_base=180.0):
+    """Mirror of the stale-stream detector resolution."""
+    if stale_base == 180.0 and base_url and is_local_endpoint(base_url):
+        return float("inf")  # detector disabled for local providers
+    if est_tokens > 100_000:
+        return max(stale_base, 300.0)
+    if est_tokens > 50_000:
+        return max(stale_base, 240.0)
+    return stale_base
+
+
+def _resolve_read_timeout(base_url, stale_timeout, base_timeout=1800.0):
+    """Mirror of the httpx socket read-timeout builder (cloud branch)."""
+    read_timeout = float(os.getenv("HERMES_STREAM_READ_TIMEOUT", 120.0))
+    if read_timeout == 120.0 and base_url and is_local_endpoint(base_url):
+        read_timeout = base_timeout
+    elif (
+        read_timeout == 120.0
+        and stale_timeout is not None
+        and stale_timeout != float("inf")
+        and stale_timeout > read_timeout
+    ):
+        read_timeout = stale_timeout
+    return read_timeout
+
+
+CLOUD_URLS = [
+    "https://api.githubcopilot.com",
+    "https://api.openai.com",
+    "https://openrouter.ai/api",
+    "https://api.anthropic.com",
+]
+
+
+class TestCloudReadTimeoutFloor:
+    @pytest.fixture(autouse=True)
+    def _clear_env(self):
+        with pytest.MonkeyPatch.context() as mp:
+            mp.delenv("HERMES_STREAM_READ_TIMEOUT", raising=False)
+            yield
+
+    @pytest.mark.parametrize("base_url", CLOUD_URLS)
+    @pytest.mark.parametrize("est_tokens", [0, 10_000, 60_000, 150_000])
+    def test_read_timeout_never_below_stale(self, base_url, est_tokens):
+        """Core invariant: the socket read timeout >= the stale detector."""
+        stale = _resolve_stale_timeout(base_url, est_tokens)
+        read = _resolve_read_timeout(base_url, stale)
+        assert read >= stale
+
+    @pytest.mark.parametrize("base_url", CLOUD_URLS)
+    def test_small_context_floored_to_stale_base(self, base_url):
+        """Reported case: ~120s timeouts on Copilot are raised to the 180s base."""
+        stale = _resolve_stale_timeout(base_url, est_tokens=37_000)
+        read = _resolve_read_timeout(base_url, stale)
+        assert read == 180.0
+
+    @pytest.mark.parametrize("base_url", CLOUD_URLS)
+    def test_large_context_tracks_scaled_stale(self, base_url):
+        """Big contexts scale the stale detector; the read timeout follows."""
+        assert _resolve_read_timeout(base_url, _resolve_stale_timeout(base_url, 60_000)) == 240.0
+        assert _resolve_read_timeout(base_url, _resolve_stale_timeout(base_url, 150_000)) == 300.0
+
+    def test_user_override_is_respected(self):
+        """An explicit HERMES_STREAM_READ_TIMEOUT is never overridden by the floor."""
+        with pytest.MonkeyPatch.context() as mp:
+            mp.setenv("HERMES_STREAM_READ_TIMEOUT", "90")
+            stale = _resolve_stale_timeout("https://api.githubcopilot.com", est_tokens=0)
+            assert _resolve_read_timeout("https://api.githubcopilot.com", stale) == 90.0
+
+
+class TestLocalUnaffected:
+    @pytest.fixture(autouse=True)
+    def _clear_env(self):
+        with pytest.MonkeyPatch.context() as mp:
+            mp.delenv("HERMES_STREAM_READ_TIMEOUT", raising=False)
+            yield
+
+    def test_local_still_raised_to_base(self):
+        """Local providers keep their existing behavior (raise to base timeout)."""
+        stale = _resolve_stale_timeout("http://localhost:11434", est_tokens=0)
+        assert stale == float("inf")  # detector disabled for local
+        read = _resolve_read_timeout("http://localhost:11434", stale)
+        assert read == 1800.0  # not clamped by inf
+
+    def test_stale_none_falls_back_to_default(self):
+        """If the stale value is unresolved, the read timeout keeps its default."""
+        assert _resolve_read_timeout("https://api.githubcopilot.com", None) == 120.0

From 3ffbdfbcc0dce5b859411666677e0f86d583dda0 Mon Sep 17 00:00:00 2001
From: brooklyn! <brooklyn.bb.nicholson@gmail.com>
Date: Wed, 10 Jun 2026 20:49:24 -0500
Subject: [PATCH 03/28] desktop: registry-driven slash commands + first-class
 /resume & /handoff (#42351)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* desktop: surface /tools, /save, /personality and fix /help skill count

Move /tools and /save out of TERMINAL_ONLY_COMMANDS and /personality out of
ADVANCED_COMMANDS so they appear in the desktop slash palette and execute via
the existing slash.exec → command.dispatch fallback. The backend gateway already
accepts these through slash.exec (none are in _PENDING_INPUT_COMMANDS or the
skill list), so no backend change is required.

Recompute skill_count in filterDesktopCommandsCatalog from the filtered pairs.
Previously the /help footer echoed the unfiltered backend total — e.g. "60
skill commands available" while only ~29 actually appeared in the rendered
list, because the desktop hides terminal-only, picker-owned, and advanced
commands.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* desktop: keep slash popover live while typing args

The trigger regex `(?:^|[\s])([@/])([^\s@/]*)$` stopped matching the moment
the user typed a space after a slash command, so the popover never showed arg
completions for `/personality`, `/tools`, etc. — even though the backend's
`complete.slash` already returns them with a `replace_from` indicator.

Split the trigger detection so `/` allows args (`/cmd arg1 arg2`) while `@`
keeps the strict no-space behavior. Restrict the slash command name to
`[a-zA-Z][\w-]*` so file paths like `src/foo/bar` don't accidentally trigger
the popover.

Rewrite arg-completion items in useSlashCompletions to insert the full
`/personality alice` token instead of stranding `/alice`: when `replace_from`
is past the command base, prepend the existing prefix to each item's text so
the chip serializer produces a coherent replacement.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* cli: complete toolset names after /tools enable|disable

SlashCommandCompleter previously only auto-derived the first subcommand level
from args_hint, so `/tools enable <tab>` yielded nothing — the user had to
remember every toolset key (web, file, spotify, …) and every MCP server prefix.

Add `_tools_completions` that handles both stages: subcommand (list|disable|enable)
and tool name. Filter by current enable state so `/tools enable <tab>` only
offers disabled toolsets and `/tools disable <tab>` only offers enabled ones —
no point suggesting a no-op. MCP server prefixes (server:) come from the
saved mcp_servers config; per-tool completion under a server would require
runtime MCP introspection and is left as follow-up.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* desktop: registry-driven slash commands with first-class pickers

Collapse the if/else slash dispatch into one DESKTOP_COMMAND_SPECS table
that drives popover suggestions, per-type composer pills, and execution.

- /resume, /sessions, /switch: inline session completions (like /skin) plus
  a "Browse all sessions…" entry that opens a dedicated session picker overlay
- /handoff: inline platform completion + handoff.request/handoff.state
  gateway bridge so desktop reaches CLI parity
- colored per-type pills (command/skill/theme) in the composer
- strip ANSI and fix width/alignment of slash output in the chat panel

* desktop: fold repeated slash session/output boilerplate into one helper

runExec, /title, /help and the unavailable case each re-derived the same
ensure-session → bail-with-notify → build-renderSlashOutput dance.
withSlashOutput() returns {sessionId, render} or null, so each handler is
a two-line resolve instead of an eight-line preamble.

* desktop: keep backend meta on slash arg completions

Arg suggestions (/personality <name>, /tools enable <toolset>, /handoff
<platform>) were having their meta overwritten with the parent command's
registry description: desktopSlashDescription("/personality none") canonicalizes
back to /personality and returns its blurb. Skip the lookup for arg rows so the
backend's own display_meta ("clear personality overlay", etc.) survives.

* cli: list real personalities in /personality completion

_personality_completions resolved load_config().agent.personalities — but that
schema has no agent.personalities key, so completion always returned just
`none` even though the runtime (load_cli_config().agent.personalities) ships a
dozen built-ins (helpful, kawaii, pirate, …). Read from the same source the
command actually applies, so `/personality ` surfaces the real options.

* desktop: expand bare arg-commands to their options on pick

Picking a command like /personality from the slash popover committed it
immediately instead of advancing to its argument list. Mark arg-taking
commands (/skin, /resume, /handoff, /personality, /tools) in the registry
and, when one is picked bare, insert "/cmd " as plain text and re-open the
popover on its inline options — mirroring typing "/cmd " by hand. Arg picks
(serialized text already contains a space) still commit a single pill.

Also realign trigger-popover loading test with the redesigned popover (the
/help empty-state hint shows when resolved, not while the spinner is up);
the merge from main reintroduced the pre-redesign expectation.

* tui_gateway: fold session-db close into a context manager

Both handoff RPCs repeated the same `db, close_db = _session_db_handle()`
+ `finally: if close_db: db.close()` dance. Turn the helper into a
`_session_db` contextmanager that owns the close, so callers just
`with _session_db(session) as db:`.

* desktop: unblock handoff retries and exact resume ids

Clear timed-out desktop handoffs through the gateway so retries are not stuck behind a pending row, and let typed /resume session ids bypass the loaded sidebar cache.

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 .../app/chat/composer/completion-drawer.tsx   |  31 +-
 .../hooks/use-live-completion-adapter.ts      |   7 +
 .../composer/hooks/use-slash-completions.ts   | 145 +++-
 apps/desktop/src/app/chat/composer/index.tsx  | 106 ++-
 .../src/app/chat/composer/rich-editor.ts      |  23 +-
 .../app/chat/composer/skin-slash-popover.tsx  |  61 --
 .../src/app/chat/composer/text-utils.test.ts  |  27 +
 .../src/app/chat/composer/text-utils.ts       |  22 +-
 .../chat/composer/trigger-popover.test.tsx    |  10 +-
 .../src/app/chat/composer/trigger-popover.tsx | 120 +++-
 apps/desktop/src/app/desktop-controller.tsx   |   3 +
 .../src/app/session-picker-overlay.tsx        |  32 +
 .../session/hooks/use-prompt-actions.test.tsx |  81 ++-
 .../app/session/hooks/use-prompt-actions.ts   | 631 ++++++++++++------
 apps/desktop/src/app/types.ts                 |  20 +
 .../assistant-ui/directive-text.tsx           |  44 +-
 .../src/components/assistant-ui/thread.tsx    |  28 +-
 .../desktop/src/components/session-picker.tsx | 108 +++
 apps/desktop/src/i18n/en.ts                   |   9 +-
 apps/desktop/src/i18n/ja.ts                   |   9 +-
 apps/desktop/src/i18n/types.ts                |   7 +
 apps/desktop/src/i18n/zh-hant.ts              |   9 +-
 apps/desktop/src/i18n/zh.ts                   |   9 +-
 apps/desktop/src/lib/ansi.ts                  |  11 +
 .../src/lib/desktop-slash-commands.test.ts    |  56 +-
 .../desktop/src/lib/desktop-slash-commands.ts | 384 +++++++----
 apps/desktop/src/store/session.ts             |   2 +
 hermes_cli/commands.py                        | 143 +++-
 tests/hermes_cli/test_commands.py             | 163 +++++
 tests/test_tui_gateway_server.py              |  41 ++
 tui_gateway/server.py                         | 168 +++++
 31 files changed, 1973 insertions(+), 537 deletions(-)
 delete mode 100644 apps/desktop/src/app/chat/composer/skin-slash-popover.tsx
 create mode 100644 apps/desktop/src/app/session-picker-overlay.tsx
 create mode 100644 apps/desktop/src/components/session-picker.tsx

diff --git a/apps/desktop/src/app/chat/composer/completion-drawer.tsx b/apps/desktop/src/app/chat/composer/completion-drawer.tsx
index 8b23c54f879b..d7738cb82a7e 100644
--- a/apps/desktop/src/app/chat/composer/completion-drawer.tsx
+++ b/apps/desktop/src/app/chat/composer/completion-drawer.tsx
@@ -3,32 +3,25 @@ import { ComposerPrimitive } from '@assistant-ui/react'
 import type { ReactNode } from 'react'
 
 export const COMPLETION_DRAWER_CLASS = [
-  'absolute bottom-[calc(100%+0.25rem)] left-0 z-50',
-  'w-60 max-w-[calc(100vw-2rem)]',
-  'max-h-[min(23rem,calc(100vh-8rem))] overflow-y-auto overscroll-contain',
-  'rounded-lg border border-(--ui-stroke-secondary)',
-  'bg-[color-mix(in_srgb,var(--ui-bg-elevated)_96%,transparent)]',
-  'p-1 text-xs text-popover-foreground shadow-md',
+  'absolute bottom-[calc(100%+0.375rem)] left-0 z-50',
+  'w-80 max-w-[calc(100vw-2rem)]',
+  'max-h-[min(22rem,calc(100vh-8rem))] overflow-y-auto overscroll-contain',
+  'rounded-xl border border-(--ui-stroke-secondary)',
+  'bg-[color-mix(in_srgb,var(--ui-bg-elevated)_97%,transparent)]',
+  'p-1 text-xs text-popover-foreground shadow-lg',
   'backdrop-blur-md'
 ].join(' ')
 
 export const COMPLETION_DRAWER_BELOW_CLASS = [
-  'absolute left-0 top-[calc(100%+0.25rem)] z-50',
-  'w-60 max-w-[calc(100vw-2rem)]',
-  'max-h-[min(23rem,calc(100vh-8rem))] overflow-y-auto overscroll-contain',
-  'rounded-lg border border-(--ui-stroke-secondary)',
-  'bg-[color-mix(in_srgb,var(--ui-bg-elevated)_96%,transparent)]',
-  'p-1 text-xs text-popover-foreground shadow-md',
+  'absolute left-0 top-[calc(100%+0.375rem)] z-50',
+  'w-80 max-w-[calc(100vw-2rem)]',
+  'max-h-[min(22rem,calc(100vh-8rem))] overflow-y-auto overscroll-contain',
+  'rounded-xl border border-(--ui-stroke-secondary)',
+  'bg-[color-mix(in_srgb,var(--ui-bg-elevated)_97%,transparent)]',
+  'p-1 text-xs text-popover-foreground shadow-lg',
   'backdrop-blur-md'
 ].join(' ')
 
-export const COMPLETION_DRAWER_ROW_CLASS = [
-  'relative flex cursor-default select-none items-center gap-2 rounded-md px-2 py-1',
-  'w-full min-w-0 text-left text-xs outline-hidden transition-colors',
-  'hover:bg-(--ui-bg-tertiary)',
-  'data-[highlighted]:bg-(--ui-bg-tertiary) data-[highlighted]:text-foreground'
-].join(' ')
-
 export function ComposerCompletionDrawer({
   adapter,
   ariaLabel,
diff --git a/apps/desktop/src/app/chat/composer/hooks/use-live-completion-adapter.ts b/apps/desktop/src/app/chat/composer/hooks/use-live-completion-adapter.ts
index fbeca7d59ee2..6da699b602a1 100644
--- a/apps/desktop/src/app/chat/composer/hooks/use-live-completion-adapter.ts
+++ b/apps/desktop/src/app/chat/composer/hooks/use-live-completion-adapter.ts
@@ -5,6 +5,13 @@ export interface CompletionEntry {
   text: string
   display?: unknown
   meta?: unknown
+  /** Optional section label (e.g. "Commands", "Skills"). The popover renders a
+   *  header whenever this changes between consecutive items, so the fetcher must
+   *  emit entries already grouped contiguously. */
+  group?: string
+  /** Optional completion-action id. When set, picking the item runs that action
+   *  (e.g. opening an overlay) instead of inserting a chip + waiting for submit. */
+  action?: string
 }
 
 export interface CompletionPayload {
diff --git a/apps/desktop/src/app/chat/composer/hooks/use-slash-completions.ts b/apps/desktop/src/app/chat/composer/hooks/use-slash-completions.ts
index f3344158097b..b0bac82825c1 100644
--- a/apps/desktop/src/app/chat/composer/hooks/use-slash-completions.ts
+++ b/apps/desktop/src/app/chat/composer/hooks/use-slash-completions.ts
@@ -2,12 +2,17 @@ import type { Unstable_TriggerAdapter, Unstable_TriggerItem } from '@assistant-u
 import { useCallback } from 'react'
 
 import type { HermesGateway } from '@/hermes'
+import { sessionTitle } from '@/lib/chat-runtime'
 import {
   type CommandsCatalogLike,
+  desktopSkinSlashCompletions,
   desktopSlashDescription,
+  type DesktopThemeCommandOption,
   filterDesktopCommandsCatalog,
+  isDesktopSlashExtensionCommand,
   isDesktopSlashSuggestion
 } from '@/lib/desktop-slash-commands'
+import { $sessions } from '@/store/session'
 
 import type { CompletionEntry, CompletionPayload } from './use-live-completion-adapter'
 import { useLiveCompletionAdapter } from './use-live-completion-adapter'
@@ -16,7 +21,10 @@ interface SlashItemMetadata extends Record<string, string> {
   command: string
   display: string
   meta: string
+  group: string
   rawText: string
+  /** Completion-action id; empty for ordinary insert-a-chip completions. */
+  action: string
 }
 
 function textValue(value: unknown, fallback = ''): string {
@@ -38,12 +46,21 @@ function commandText(value: string): string {
   return value.startsWith('/') ? value : `/${value}`
 }
 
+/** How many recent sessions to surface inline before the "Browse all…" entry. */
+const SESSION_INLINE_LIMIT = 7
+
 /** Live `/` completions backed by the gateway's `complete.slash` RPC. */
-export function useSlashCompletions(options: { gateway: HermesGateway | null }): {
+export function useSlashCompletions(options: {
+  gateway: HermesGateway | null
+  /** Desktop theme list — `/skin` is owned client-side, so its arg completions
+   *  come from here, not the backend (whose skin list is CLI/TUI-only). */
+  skinThemes?: DesktopThemeCommandOption[]
+  activeSkin?: string
+}): {
   adapter: Unstable_TriggerAdapter
   loading: boolean
 } {
-  const { gateway } = options
+  const { gateway, skinThemes, activeSkin } = options
   const enabled = Boolean(gateway)
 
   const fetcher = useCallback(
@@ -54,34 +71,136 @@ export function useSlashCompletions(options: { gateway: HermesGateway | null }):
 
       const text = `/${query}`
 
+      // The desktop owns /skin entirely (client-side theme context). Surface its
+      // theme list inside this single popover instead of a bespoke one, and skip
+      // the backend skin completions (which describe CLI/TUI skins that don't
+      // apply here). Matches once we're past `/skin ` into the arg stage.
+      const skinArg = /^\/skin\s+(.*)$/is.exec(text)
+
+      if (skinArg && skinThemes) {
+        const items = desktopSkinSlashCompletions(skinThemes, activeSkin ?? '', skinArg[1] ?? '').map(entry => ({
+          text: entry.text,
+          display: entry.display,
+          meta: entry.meta,
+          group: 'Themes'
+        }))
+
+        return { items, query }
+      }
+
+      // /resume (and its aliases) completes recent sessions inline — the same
+      // client-side list the picker overlay shows — instead of the backend
+      // (whose /resume opens an interactive TUI picker we can't render here).
+      const sessionArg = /^\/(?:resume|sessions|switch)\s+(.*)$/is.exec(text)
+
+      if (sessionArg) {
+        const needle = (sessionArg[1] ?? '').trim().toLowerCase()
+
+        const matches = (
+          needle
+            ? $sessions.get().filter(
+                session =>
+                  sessionTitle(session).toLowerCase().includes(needle) ||
+                  (session.preview ?? '').toLowerCase().includes(needle) ||
+                  session.id.toLowerCase().includes(needle)
+              )
+            : $sessions.get()
+        ).slice(0, SESSION_INLINE_LIMIT)
+
+        const items: CompletionEntry[] = matches.map(session => ({
+          text: `/resume ${session.id}`,
+          display: sessionTitle(session),
+          meta: (session.preview ?? '').trim(),
+          group: 'Sessions'
+        }))
+
+        // Trailing "more" affordance (Cursor-style): picking it opens the full
+        // session picker overlay directly. `text` stays a bare `/resume` so that
+        // submitting it (Enter) still opens the overlay if the action is skipped.
+        items.push({
+          text: '/resume',
+          display: 'Browse all sessions…',
+          meta: '',
+          group: 'Sessions',
+          action: 'session-picker'
+        })
+
+        return { items, query }
+      }
+
       try {
         if (!query) {
           const catalog = filterDesktopCommandsCatalog(await gateway.request<CommandsCatalogLike>('commands.catalog'))
 
-          const items = (catalog.pairs ?? []).map(([command, meta]) => ({
-            text: command,
-            display: command,
-            meta
-          }))
+          // Prefer the categorized layout so the popover renders section headers
+          // (Session, Tools & Skills, ...). Fall back to the flat list when the
+          // backend didn't categorize.
+          const sections = catalog.categories?.length
+            ? catalog.categories
+            : [{ name: '', pairs: catalog.pairs ?? [] }]
+
+          const items = sections.flatMap(section =>
+            section.pairs.map(([command, meta]) => ({
+              text: command,
+              display: command,
+              group: section.name || undefined,
+              meta
+            }))
+          )
 
           return { items, query }
         }
 
-        const result = await gateway.request<{ items?: CompletionEntry[] }>('complete.slash', { text })
+        const result = await gateway.request<{ items?: CompletionEntry[]; replace_from?: number }>(
+          'complete.slash',
+          { text }
+        )
 
-        const items = (result.items ?? [])
-          .filter(item => isDesktopSlashSuggestion(item.text))
+        // Arg-completion items (replace_from > 1) carry just the arg stub —
+        // e.g. complete.slash returns `{text: "alice"}` for `/personality alic`
+        // with replace_from = 14. Rewrite those entries so the popover inserts
+        // the full `/personality alice` token instead of stranding `/alice`.
+        const replaceFrom = typeof result.replace_from === 'number' ? result.replace_from : 1
+        const isArgCompletion = replaceFrom > 1
+        const prefix = isArgCompletion ? text.slice(0, replaceFrom) : ''
+
+        const decorated = (result.items ?? [])
+          .map(item => {
+            if (!isArgCompletion) {
+              return item
+            }
+
+            const argText = typeof item.text === 'string' ? item.text : ''
+
+            return { ...item, text: `${prefix}${argText}` }
+          })
+          .filter(item => isArgCompletion || isDesktopSlashSuggestion(item.text))
           .map(item => ({
             ...item,
-            meta: desktopSlashDescription(item.text, textValue(item.meta))
+            // Arg suggestions (e.g. `/handoff <platform>`) live under one
+            // header; otherwise split skills out from built-in commands.
+            group: isArgCompletion ? 'Options' : isDesktopSlashExtensionCommand(item.text) ? 'Skills' : 'Commands',
+            // Arg items carry their own meta (the personality/toolset/platform
+            // blurb). Only command rows get the registry description — looking
+            // one up for `/personality none` would clobber it with the parent
+            // command's text.
+            meta: isArgCompletion ? textValue(item.meta) : desktopSlashDescription(item.text, textValue(item.meta))
           }))
 
+        // Keep each group contiguous so headers render once: Commands before
+        // Skills (stable within a group, preserving backend relevance order).
+        const groupOrder = ['Commands', 'Skills', 'Options']
+
+        const items = isArgCompletion
+          ? decorated
+          : [...decorated].sort((a, b) => groupOrder.indexOf(a.group) - groupOrder.indexOf(b.group))
+
         return { items, query }
       } catch {
         return { items: [], query }
       }
     },
-    [gateway]
+    [gateway, skinThemes, activeSkin]
   )
 
   const toItem = useCallback((entry: CompletionEntry, index: number): Unstable_TriggerItem => {
@@ -93,6 +212,8 @@ export function useSlashCompletions(options: { gateway: HermesGateway | null }):
       command,
       display,
       meta,
+      group: textValue(entry.group),
+      action: textValue(entry.action),
       // Provide rawText so hermesDirectiveFormatter.serialize uses the
       // direct-insertion path instead of the legacy @type:id fallback.
       // Without this, the item.id (which includes a "|index" suffix for
diff --git a/apps/desktop/src/app/chat/composer/index.tsx b/apps/desktop/src/app/chat/composer/index.tsx
index d8b06a68d377..bf9488348376 100644
--- a/apps/desktop/src/app/chat/composer/index.tsx
+++ b/apps/desktop/src/app/chat/composer/index.tsx
@@ -13,13 +13,14 @@ import {
   useState
 } from 'react'
 
-import { hermesDirectiveFormatter } from '@/components/assistant-ui/directive-text'
+import { hermesDirectiveFormatter, type SlashChipKind } from '@/components/assistant-ui/directive-text'
 import { Button } from '@/components/ui/button'
 import { useMediaQuery } from '@/hooks/use-media-query'
 import { useResizeObserver } from '@/hooks/use-resize-observer'
 import { useI18n } from '@/i18n'
 import { chatMessageText } from '@/lib/chat-messages'
 import { SLASH_COMMAND_RE } from '@/lib/chat-runtime'
+import { desktopSlashCommandTakesArgs } from '@/lib/desktop-slash-commands'
 import { DATA_IMAGE_URL_RE } from '@/lib/embedded-images'
 import { triggerHaptic } from '@/lib/haptics'
 import { cn } from '@/lib/utils'
@@ -40,8 +41,9 @@ import {
   shouldAutoDrainOnSettle,
   updateQueuedPrompt
 } from '@/store/composer-queue'
-import { $gatewayState, $messages } from '@/store/session'
+import { $gatewayState, $messages, setSessionPickerOpen } from '@/store/session'
 import { $threadScrolledUp } from '@/store/thread-scroll'
+import { useTheme } from '@/themes'
 
 import { extractDroppedFiles, HERMES_PATHS_MIME, partitionDroppedFiles } from '../hooks/use-composer-actions'
 
@@ -74,9 +76,9 @@ import {
   placeCaretEnd,
   refChipElement,
   renderComposerContents,
-  RICH_INPUT_SLOT
+  RICH_INPUT_SLOT,
+  slashChipElement
 } from './rich-editor'
-import { SkinSlashPopover } from './skin-slash-popover'
 import { detectTrigger, extractClipboardImageBlobs, textBeforeCaret, type TriggerState } from './text-utils'
 import { ComposerTriggerPopover } from './trigger-popover'
 import type { ChatBarProps } from './types'
@@ -95,6 +97,30 @@ const COMPOSER_FADE_BACKGROUND =
 
 const pickPlaceholder = (pool: readonly string[]) => pool[Math.floor(Math.random() * pool.length)]
 
+/** Completion items can carry an `action` (set in use-slash-completions) that
+ *  runs a side effect on pick instead of inserting a chip — e.g. the session
+ *  picker's "Browse all…" entry opens the overlay. Table-driven so new action
+ *  items are a registry row, not a composer branch. */
+const COMPLETION_ACTIONS: Record<string, () => void> = {
+  'session-picker': () => setSessionPickerOpen(true)
+}
+
+/** Map a picked `/` completion to its pill accent. Driven by the completion
+ *  group set in use-slash-completions (Skills / Themes / Commands|Options). */
+function slashChipKindForItem(item: Unstable_TriggerItem): SlashChipKind {
+  const group = (item.metadata as { group?: unknown } | undefined)?.group
+
+  if (group === 'Skills') {
+    return 'skill'
+  }
+
+  if (group === 'Themes') {
+    return 'theme'
+  }
+
+  return 'command'
+}
+
 interface QueueEditState {
   attachments: ComposerAttachment[]
   draft: string
@@ -162,8 +188,9 @@ export function ChatBar({
 
   const narrow = useMediaQuery('(max-width: 30rem)')
 
+  const { availableThemes, themeName } = useTheme()
   const at = useAtCompletions({ gateway: gateway ?? null, sessionId: sessionId ?? null, cwd: cwd ?? null })
-  const slash = useSlashCompletions({ gateway: gateway ?? null })
+  const slash = useSlashCompletions({ activeSkin: themeName, gateway: gateway ?? null, skinThemes: availableThemes })
 
   const stacked = expanded || narrow || tight
   const trimmedDraft = draft.trim()
@@ -171,10 +198,12 @@ export function ChatBar({
   const canSubmit = busy || hasComposerPayload
   const editingQueuedPrompt = queueEdit ? (queuedPrompts.find(entry => entry.id === queueEdit.entryId) ?? null) : null
   const busyAction = busy && hasComposerPayload ? 'queue' : 'stop'
+
   // Steer only makes sense mid-turn, text-only (the gateway can't carry images
   // into a tool result) and never for a slash command (those execute inline).
   const canSteer =
     busy && !!onSteer && attachments.length === 0 && trimmedDraft.length > 0 && !SLASH_COMMAND_RE.test(trimmedDraft)
+
   const showHelpHint = draft === '?'
 
   const { t } = useI18n()
@@ -462,12 +491,6 @@ export function ChatBar({
     })
   }, [])
 
-  const selectSkinSlashCommand = (command: string) => {
-    draftRef.current = command
-    aui.composer().setText(command)
-    requestMainFocus()
-  }
-
   const handlePaste = (event: ClipboardEvent<HTMLDivElement>) => {
     const imageBlobs = extractClipboardImageBlobs(event.clipboardData)
 
@@ -620,16 +643,50 @@ export function ChatBar({
       return
     }
 
+    // Action items (e.g. "Browse all sessions…") run a side effect instead of
+    // inserting a chip: strip the typed trigger token, then fire the action.
+    const completionAction = (item.metadata as { action?: unknown } | undefined)?.action
+    const runAction = typeof completionAction === 'string' ? COMPLETION_ACTIONS[completionAction] : undefined
+
+    if (runAction) {
+      const current = composerPlainText(editor)
+      const prefix = current.slice(0, Math.max(0, current.length - trigger.tokenLength))
+
+      renderComposerContents(editor, prefix)
+      placeCaretEnd(editor)
+      draftRef.current = composerPlainText(editor)
+      aui.composer().setText(draftRef.current)
+      closeTrigger()
+      runAction()
+      requestMainFocus()
+
+      return
+    }
+
     const serialized = hermesDirectiveFormatter.serialize(item)
     const starter = serialized.endsWith(':')
+
+    // Picking a bare arg-taking command (e.g. `/personality`) shouldn't commit
+    // it — expand to its options step so the popover shows the inline list, just
+    // as typing `/personality ` by hand would. A serialized value with a space is
+    // already an arg pick (`/personality alice`), so it commits normally.
+    const command = (item.metadata as { command?: string } | undefined)?.command ?? ''
+
+    const expandsToArgs =
+      trigger.kind === '/' && !serialized.includes(' ') && desktopSlashCommandTakesArgs(command)
+
     const text = starter || serialized.endsWith(' ') ? serialized : `${serialized} `
     const directive = !starter && serialized.match(/^@([^:]+):(.+)$/)
+    // No pill while expanding — the bare command stays plain text until an arg
+    // is picked, at which point a single pill is emitted for the full command.
+    const slashKind = !expandsToArgs && trigger.kind === '/' ? slashChipKindForItem(item) : null
+    const keepTriggerOpen = starter || expandsToArgs
 
     const finish = () => {
       draftRef.current = composerPlainText(editor)
       aui.composer().setText(draftRef.current)
       requestMainFocus()
-      starter ? window.setTimeout(refreshTrigger, 0) : closeTrigger()
+      keepTriggerOpen ? window.setTimeout(refreshTrigger, 0) : closeTrigger()
     }
 
     const sel = window.getSelection()
@@ -639,7 +696,20 @@ export function ChatBar({
 
     if (!sel || !range || node?.nodeType !== Node.TEXT_NODE || offset < trigger.tokenLength) {
       const current = composerPlainText(editor)
-      renderComposerContents(editor, `${current.slice(0, Math.max(0, current.length - trigger.tokenLength))}${text}`)
+      const prefix = current.slice(0, Math.max(0, current.length - trigger.tokenLength))
+
+      if (slashKind) {
+        // Two-step arg picks (e.g. `/handoff` pill already inserted, now picking
+        // the platform) land here because the caret sits past a contenteditable
+        // chip. Rebuild the prefix and re-emit a single pill for the full command.
+        renderComposerContents(editor, prefix)
+        editor.append(slashChipElement(serialized, slashKind), document.createTextNode(' '))
+        placeCaretEnd(editor)
+
+        return finish()
+      }
+
+      renderComposerContents(editor, `${prefix}${text}`)
       placeCaretEnd(editor)
 
       return finish()
@@ -650,8 +720,13 @@ export function ChatBar({
     replaceRange.setEnd(node, offset)
     replaceRange.deleteContents()
 
-    if (directive) {
-      const chip = refChipElement(directive[1], directive[2])
+    const chip = slashKind
+      ? slashChipElement(serialized, slashKind)
+      : directive
+        ? refChipElement(directive[1], directive[2])
+        : null
+
+    if (chip) {
       const space = document.createTextNode(' ')
       const fragment = document.createDocumentFragment()
       fragment.append(chip, space)
@@ -1515,7 +1590,6 @@ export function ChatBar({
               onPick={replaceTriggerWithChip}
             />
           )}
-          <SkinSlashPopover draft={draft} onSelect={selectSkinSlashCommand} />
           {activeQueueSessionKey && queuedPrompts.length > 0 && (
             // Out of flow so the queue never inflates the composer's measured
             // height (that drives thread bottom padding → chat resizes on
diff --git a/apps/desktop/src/app/chat/composer/rich-editor.ts b/apps/desktop/src/app/chat/composer/rich-editor.ts
index 38ab85d0f353..ea6382f9abd1 100644
--- a/apps/desktop/src/app/chat/composer/rich-editor.ts
+++ b/apps/desktop/src/app/chat/composer/rich-editor.ts
@@ -10,7 +10,10 @@ import {
   DIRECTIVE_CHIP_CLASS,
   directiveIconElement,
   directiveIconSvg,
-  formatRefValue
+  formatRefValue,
+  slashChipClass,
+  type SlashChipKind,
+  slashIconElement
 } from '@/components/assistant-ui/directive-text'
 
 export const RICH_INPUT_SLOT = 'composer-rich-input'
@@ -77,6 +80,24 @@ export function refChipElement(kind: string, rawValue: string, displayLabel?: st
   return chip
 }
 
+/** A non-editable pill for a picked slash command (`/skin nous`, `/tropes`).
+ *  `data-ref-text` carries the literal command so `composerPlainText` round-trips
+ *  it back to the exact text that gets submitted. */
+export function slashChipElement(command: string, kind: SlashChipKind, label?: string) {
+  const chip = document.createElement('span')
+  const text = document.createElement('span')
+
+  chip.contentEditable = 'false'
+  chip.dataset.refText = command
+  chip.dataset.slashKind = kind
+  chip.className = slashChipClass(kind)
+  text.className = 'truncate'
+  text.textContent = label || command
+  chip.append(slashIconElement(kind), text)
+
+  return chip
+}
+
 function appendTextWithBreaks(target: DocumentFragment | HTMLElement, text: string) {
   const lines = text.split('\n')
 
diff --git a/apps/desktop/src/app/chat/composer/skin-slash-popover.tsx b/apps/desktop/src/app/chat/composer/skin-slash-popover.tsx
deleted file mode 100644
index 2bfc27e51ad4..000000000000
--- a/apps/desktop/src/app/chat/composer/skin-slash-popover.tsx
+++ /dev/null
@@ -1,61 +0,0 @@
-import { useI18n } from '@/i18n'
-import { desktopSkinSlashCompletions } from '@/lib/desktop-slash-commands'
-import { triggerHaptic } from '@/lib/haptics'
-import { useTheme } from '@/themes/context'
-
-import { COMPLETION_DRAWER_CLASS, COMPLETION_DRAWER_ROW_CLASS, CompletionDrawerEmpty } from './completion-drawer'
-
-interface SkinSlashPopoverProps {
-  draft: string
-  onSelect: (command: string) => void
-}
-
-export function SkinSlashPopover({ draft, onSelect }: SkinSlashPopoverProps) {
-  const { t } = useI18n()
-  const c = t.composer
-  const { availableThemes, themeName } = useTheme()
-  const match = draft.match(/^\/skin\s+(\S*)$/i)
-
-  if (!match) {
-    return null
-  }
-
-  const items = desktopSkinSlashCompletions(availableThemes, themeName, match[1] ?? '')
-
-  return (
-    <div
-      aria-label={c.themeSuggestions}
-      className={COMPLETION_DRAWER_CLASS}
-      data-slot="composer-skin-completion-drawer"
-      data-state="open"
-      role="listbox"
-    >
-      <div className="grid gap-0.5 pt-0.5">
-        {items.length === 0 ? (
-          <CompletionDrawerEmpty title={c.noMatchingThemes}>
-            {c.themeTryPre}
-            <span className="font-mono text-foreground/80">/skin list</span>
-            {c.themeTryPost}
-          </CompletionDrawerEmpty>
-        ) : (
-          items.map(item => (
-            <button
-              className={COMPLETION_DRAWER_ROW_CLASS}
-              key={item.text}
-              onClick={() => {
-                triggerHaptic('selection')
-                onSelect(item.text)
-              }}
-              onMouseDown={event => event.preventDefault()}
-              role="option"
-              type="button"
-            >
-              <span className="shrink-0 font-mono font-medium leading-5 text-foreground">{item.display}</span>
-              <span className="min-w-0 truncate leading-5 text-muted-foreground/80">{item.meta}</span>
-            </button>
-          ))
-        )}
-      </div>
-    </div>
-  )
-}
diff --git a/apps/desktop/src/app/chat/composer/text-utils.test.ts b/apps/desktop/src/app/chat/composer/text-utils.test.ts
index 5ef677f4d0fe..f80e6db4385d 100644
--- a/apps/desktop/src/app/chat/composer/text-utils.test.ts
+++ b/apps/desktop/src/app/chat/composer/text-utils.test.ts
@@ -22,6 +22,33 @@ describe('detectTrigger', () => {
   it('returns null for plain text', () => {
     expect(detectTrigger('hello there')).toBeNull()
   })
+
+  it('keeps the slash trigger live while typing args', () => {
+    expect(detectTrigger('/personality ')).toEqual({
+      kind: '/',
+      query: 'personality ',
+      tokenLength: 13
+    })
+    expect(detectTrigger('/personality alic')).toEqual({
+      kind: '/',
+      query: 'personality alic',
+      tokenLength: 17
+    })
+    expect(detectTrigger('/tools enable foo')).toEqual({
+      kind: '/',
+      query: 'tools enable foo',
+      tokenLength: 17
+    })
+  })
+
+  it('does not treat file-style paths as slash triggers', () => {
+    expect(detectTrigger('src/foo/bar')).toBeNull()
+    expect(detectTrigger('/path/to/file')).toBeNull()
+  })
+
+  it('still anchors at-mention triggers strictly at the token edge', () => {
+    expect(detectTrigger('@file:path with space')).toBeNull()
+  })
 })
 
 describe('extractClipboardImageBlobs', () => {
diff --git a/apps/desktop/src/app/chat/composer/text-utils.ts b/apps/desktop/src/app/chat/composer/text-utils.ts
index e9a8fb6aaee7..4535d6963c3a 100644
--- a/apps/desktop/src/app/chat/composer/text-utils.ts
+++ b/apps/desktop/src/app/chat/composer/text-utils.ts
@@ -6,7 +6,13 @@ export interface TriggerState {
   tokenLength: number
 }
 
-const TRIGGER_RE = /(?:^|[\s])([@/])([^\s@/]*)$/
+// `@` triggers stop at the first whitespace — `@file:path` and `@diff` are
+// single tokens. `/` triggers keep going so the popover stays live while the
+// user types args (`/personality alic` → arg completer suggests `alice`).
+// Restricting the slash command name to `[a-zA-Z][\w-]*` avoids matching file
+// paths like `src/foo/bar`.
+const AT_TRIGGER_RE = /(?:^|[\s])(@)([^\s@/]*)$/
+const SLASH_TRIGGER_RE = /(?:^|[\s])(\/)((?:[a-zA-Z][\w-]*(?:\s+\S*)*)?)$/
 
 /** Stable key for paste dedupe — `items` and `files` often mirror the same image as different objects. */
 export function blobDedupeKey(blob: Blob): string {
@@ -97,11 +103,17 @@ export function textBeforeCaret(editor: HTMLDivElement): string | null {
 }
 
 export function detectTrigger(textBefore: string): TriggerState | null {
-  const match = TRIGGER_RE.exec(textBefore)
+  const slash = SLASH_TRIGGER_RE.exec(textBefore)
 
-  if (!match) {
-    return null
+  if (slash) {
+    return { kind: '/', query: slash[2], tokenLength: 1 + slash[2].length }
   }
 
-  return { kind: match[1] as '@' | '/', query: match[2], tokenLength: 1 + match[2].length }
+  const at = AT_TRIGGER_RE.exec(textBefore)
+
+  if (at) {
+    return { kind: '@', query: at[2], tokenLength: 1 + at[2].length }
+  }
+
+  return null
 }
diff --git a/apps/desktop/src/app/chat/composer/trigger-popover.test.tsx b/apps/desktop/src/app/chat/composer/trigger-popover.test.tsx
index 9acc43f7f198..3aefbfee0a5b 100644
--- a/apps/desktop/src/app/chat/composer/trigger-popover.test.tsx
+++ b/apps/desktop/src/app/chat/composer/trigger-popover.test.tsx
@@ -34,9 +34,17 @@ describe('ComposerTriggerPopover i18n', () => {
   })
 
   it('renders localized loading copy for slash commands', () => {
-    const { container } = renderPopover('/', true)
+    renderPopover('/', true)
 
+    // While loading the popover shows only the spinner + loading copy — the
+    // `/help` empty-state hint is reserved for the resolved (not-loading) state.
     expect(screen.getByText('查找中…')).toBeTruthy()
+  })
+
+  it('renders the slash empty-state hint when not loading', () => {
+    const { container } = renderPopover('/')
+
+    expect(screen.getByText('没有匹配项。')).toBeTruthy()
     expect(container.textContent).toContain('/help')
   })
 })
diff --git a/apps/desktop/src/app/chat/composer/trigger-popover.tsx b/apps/desktop/src/app/chat/composer/trigger-popover.tsx
index a09190dd6b3c..1099c0748ba3 100644
--- a/apps/desktop/src/app/chat/composer/trigger-popover.tsx
+++ b/apps/desktop/src/app/chat/composer/trigger-popover.tsx
@@ -1,5 +1,7 @@
 import type { Unstable_TriggerItem } from '@assistant-ui/core'
+import { Fragment } from 'react'
 
+import { BrailleSpinner } from '@/components/ui/braille-spinner'
 import { Codicon } from '@/components/ui/codicon'
 import { useI18n } from '@/i18n'
 import { cn } from '@/lib/utils'
@@ -7,7 +9,6 @@ import { cn } from '@/lib/utils'
 import {
   COMPLETION_DRAWER_BELOW_CLASS,
   COMPLETION_DRAWER_CLASS,
-  COMPLETION_DRAWER_ROW_CLASS,
   CompletionDrawerEmpty
 } from './completion-drawer'
 
@@ -23,11 +24,7 @@ const AT_ICON_BY_TYPE: Record<string, string> = {
   url: 'globe'
 }
 
-function completionIcon(kind: '@' | '/', item: Unstable_TriggerItem) {
-  if (kind === '/') {
-    return 'terminal'
-  }
-
+function atIcon(item: Unstable_TriggerItem) {
   const meta = item.metadata as { rawText?: string } | undefined
   const raw = meta?.rawText || item.label
 
@@ -42,6 +39,18 @@ function completionIcon(kind: '@' | '/', item: Unstable_TriggerItem) {
   return AT_ICON_BY_TYPE[item.type] || AT_ICON_BY_TYPE.simple
 }
 
+interface RowMeta {
+  display?: string
+  group?: string
+  meta?: string
+}
+
+const ROW_BASE_CLASS = [
+  'relative flex w-full cursor-default select-none rounded-md px-2 py-1 text-left',
+  'outline-hidden transition-colors hover:bg-(--ui-bg-tertiary)',
+  'data-[highlighted]:bg-(--ui-bg-tertiary) data-[highlighted]:text-foreground'
+].join(' ')
+
 interface ComposerTriggerPopoverProps {
   activeIndex: number
   items: readonly Unstable_TriggerItem[]
@@ -63,6 +72,9 @@ export function ComposerTriggerPopover({
 }: ComposerTriggerPopoverProps) {
   const { t } = useI18n()
   const copy = t.composer
+  const isSlash = kind === '/'
+
+  let lastGroup: string | undefined
 
   return (
     <div
@@ -73,41 +85,79 @@ export function ComposerTriggerPopover({
       role="listbox"
     >
       {items.length === 0 ? (
-        <CompletionDrawerEmpty title={loading ? copy.lookupLoading : copy.lookupNoMatches}>
-          {kind === '@' ? (
-            <>
-              {copy.lookupTry} <span className="font-mono text-foreground/80">@file:</span> {copy.lookupOr}{' '}
-              <span className="font-mono text-foreground/80">@folder:</span>.
-            </>
-          ) : (
-            <>
-              {copy.lookupTry} <span className="font-mono text-foreground/80">/help</span>.
-            </>
-          )}
-        </CompletionDrawerEmpty>
+        loading ? (
+          <div className="flex items-center gap-2 px-2 py-1.5 text-(--ui-text-tertiary)">
+            <BrailleSpinner ariaLabel={copy.lookupLoading} className="text-foreground/70" spinner="braille" />
+            <span>{copy.lookupLoading}</span>
+          </div>
+        ) : (
+          <CompletionDrawerEmpty title={copy.lookupNoMatches}>
+            {kind === '@' ? (
+              <>
+                {copy.lookupTry} <span className="font-mono text-foreground/80">@file:</span> {copy.lookupOr}{' '}
+                <span className="font-mono text-foreground/80">@folder:</span>.
+              </>
+            ) : (
+              <>
+                {copy.lookupTry} <span className="font-mono text-foreground/80">/help</span>.
+              </>
+            )}
+          </CompletionDrawerEmpty>
+        )
       ) : (
         items.map((item, index) => {
-          const meta = item.metadata as { display?: string; meta?: string } | undefined
-          const display = meta?.display ?? (kind === '/' ? `/${item.label}` : item.label)
+          const meta = item.metadata as RowMeta | undefined
+          const display = meta?.display ?? (isSlash ? `/${item.label}` : item.label)
           const description = meta?.meta || item.description
+          const group = meta?.group?.trim()
+          const showHeader = isSlash && Boolean(group) && group !== lastGroup
+          const isFirstHeader = lastGroup === undefined
+          lastGroup = group || lastGroup
+          const active = index === activeIndex
 
           return (
-            <button
-              className={cn(COMPLETION_DRAWER_ROW_CLASS, index === activeIndex && 'bg-(--ui-bg-tertiary)')}
-              data-highlighted={index === activeIndex ? '' : undefined}
-              key={item.id}
-              onClick={() => onPick(item)}
-              onMouseEnter={() => onHover(index)}
-              type="button"
-            >
-              <span className="grid size-3.5 shrink-0 place-items-center text-(--ui-text-tertiary)">
-                <Codicon name={completionIcon(kind, item)} size="0.875rem" />
-              </span>
-              <span className="min-w-0 shrink truncate font-mono font-medium leading-5 text-foreground">{display}</span>
-              {description && (
-                <span className="min-w-0 flex-1 truncate leading-5 text-(--ui-text-tertiary)">{description}</span>
+            <Fragment key={item.id}>
+              {showHeader && (
+                <div
+                  className={cn(
+                    'select-none px-2 pb-0.5 text-[0.625rem] font-semibold uppercase tracking-wider text-(--ui-text-tertiary)',
+                    isFirstHeader ? 'pt-0.5' : 'pt-2'
+                  )}
+                >
+                  {group}
+                </div>
               )}
-            </button>
+              <button
+                className={cn(ROW_BASE_CLASS, isSlash ? 'flex-col gap-0' : 'items-center gap-2')}
+                data-highlighted={active ? '' : undefined}
+                onClick={() => onPick(item)}
+                onMouseEnter={() => onHover(index)}
+                type="button"
+              >
+                {isSlash ? (
+                  <>
+                    <span className="truncate text-[0.8125rem] font-medium leading-snug text-foreground">{display}</span>
+                    {description && (
+                      <span className="truncate text-[0.6875rem] leading-snug text-(--ui-text-tertiary)">
+                        {description}
+                      </span>
+                    )}
+                  </>
+                ) : (
+                  <>
+                    <span className="grid size-4 shrink-0 place-items-center text-(--ui-text-tertiary)">
+                      <Codicon name={atIcon(item)} size="0.875rem" />
+                    </span>
+                    <span className="min-w-0 shrink truncate font-mono font-medium leading-5 text-foreground">
+                      {display}
+                    </span>
+                    {description && (
+                      <span className="min-w-0 flex-1 truncate leading-5 text-(--ui-text-tertiary)">{description}</span>
+                    )}
+                  </>
+                )}
+              </button>
+            </Fragment>
           )
         })
       )}
diff --git a/apps/desktop/src/app/desktop-controller.tsx b/apps/desktop/src/app/desktop-controller.tsx
index ab4f3f0eb0e7..0da266395449 100644
--- a/apps/desktop/src/app/desktop-controller.tsx
+++ b/apps/desktop/src/app/desktop-controller.tsx
@@ -98,6 +98,7 @@ import { RightSidebarPane } from './right-sidebar'
 import { $terminalTakeover } from './right-sidebar/store'
 import { PersistentTerminal, TerminalSlot } from './right-sidebar/terminal/persistent'
 import { CRON_ROUTE, NEW_CHAT_ROUTE, routeSessionId, sessionRoute, SETTINGS_ROUTE } from './routes'
+import { SessionPickerOverlay } from './session-picker-overlay'
 import { SessionSwitcher } from './session-switcher'
 import { useContextSuggestions } from './session/hooks/use-context-suggestions'
 import { useCwdActions } from './session/hooks/use-cwd-actions'
@@ -694,6 +695,7 @@ export function DesktopController() {
     handleSkinCommand,
     refreshSessions,
     requestGateway,
+    resumeStoredSession: resumeSession,
     selectedStoredSessionIdRef,
     startFreshSessionDraft,
     sttEnabled,
@@ -829,6 +831,7 @@ export function DesktopController() {
         />
       )}
       <ModelPickerOverlay gateway={gatewayRef.current || undefined} onSelect={selectModel} />
+      <SessionPickerOverlay onResume={resumeSession} />
       <ModelVisibilityOverlay gateway={gatewayRef.current || undefined} onOpenProviders={openProviderSettings} />
       <UpdatesOverlay />
       <GatewayConnectingOverlay />
diff --git a/apps/desktop/src/app/session-picker-overlay.tsx b/apps/desktop/src/app/session-picker-overlay.tsx
new file mode 100644
index 000000000000..65344fcac26b
--- /dev/null
+++ b/apps/desktop/src/app/session-picker-overlay.tsx
@@ -0,0 +1,32 @@
+import { useStore } from '@nanostores/react'
+
+import { SessionPickerDialog } from '@/components/session-picker'
+import { $gatewayState, $selectedStoredSessionId, $sessionPickerOpen, setSessionPickerOpen } from '@/store/session'
+
+interface SessionPickerOverlayProps {
+  onResume: (storedSessionId: string) => void
+}
+
+/**
+ * Mounts the session picker that `/resume` (and `/sessions`, `/switch`) opens —
+ * the desktop equivalent of the TUI's sessions overlay. Resuming runs through
+ * the same `resumeSession` path the sidebar uses.
+ */
+export function SessionPickerOverlay({ onResume }: SessionPickerOverlayProps) {
+  const open = useStore($sessionPickerOpen)
+  const gatewayOpen = useStore($gatewayState) === 'open'
+  const activeStoredSessionId = useStore($selectedStoredSessionId)
+
+  if (!gatewayOpen) {
+    return null
+  }
+
+  return (
+    <SessionPickerDialog
+      activeStoredSessionId={activeStoredSessionId}
+      onOpenChange={setSessionPickerOpen}
+      onResume={onResume}
+      open={open}
+    />
+  )
+}
diff --git a/apps/desktop/src/app/session/hooks/use-prompt-actions.test.tsx b/apps/desktop/src/app/session/hooks/use-prompt-actions.test.tsx
index 96af1e8400eb..3418e0bad807 100644
--- a/apps/desktop/src/app/session/hooks/use-prompt-actions.test.tsx
+++ b/apps/desktop/src/app/session/hooks/use-prompt-actions.test.tsx
@@ -1,6 +1,6 @@
 import { cleanup, render, waitFor } from '@testing-library/react'
 import type { MutableRefObject } from 'react'
-import { useEffect } from 'react'
+import { useEffect, useRef } from 'react'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 
 import { $composerAttachments, type ComposerAttachment } from '@/store/composer'
@@ -55,6 +55,7 @@ function Harness({
   onSeedState,
   refreshSessions,
   requestGateway,
+  resumeStoredSession,
   storedSessionId
 }: {
   busyRef?: MutableRefObject<boolean>
@@ -62,6 +63,7 @@ function Harness({
   onSeedState?: (state: Record<string, unknown>) => void
   refreshSessions: () => Promise<void>
   requestGateway: <T>(method: string, params?: Record<string, unknown>) => Promise<T>
+  resumeStoredSession?: (storedSessionId: string) => Promise<void> | void
   storedSessionId?: null | string
 }) {
   const activeSessionIdRef: MutableRefObject<string | null> = { current: RUNTIME_SESSION_ID }
@@ -69,6 +71,12 @@ function Harness({
     current: storedSessionId === undefined ? RUNTIME_SESSION_ID : storedSessionId
   }
   const localBusyRef = busyRef ?? { current: false }
+  const stateRef = useRef({
+    messages: [],
+    busy: false,
+    awaitingResponse: false,
+    interrupted: true
+  } as never)
 
   const actions = usePromptActions({
     activeSessionId: RUNTIME_SESSION_ID,
@@ -79,17 +87,14 @@ function Harness({
     handleSkinCommand: () => '',
     refreshSessions,
     requestGateway,
+    resumeStoredSession: resumeStoredSession ?? (() => undefined),
     selectedStoredSessionIdRef,
     startFreshSessionDraft: () => undefined,
     sttEnabled: false,
     updateSessionState: (_sessionId, updater) => {
       // Seed with interrupted:true so we can prove a fresh submit clears it.
-      const next = updater({
-        messages: [],
-        busy: false,
-        awaitingResponse: false,
-        interrupted: true
-      } as never) as unknown as Record<string, unknown>
+      const next = updater(stateRef.current) as unknown as Record<string, unknown>
+      stateRef.current = next as never
       onSeedState?.(next)
 
       return next as never
@@ -190,6 +195,68 @@ describe('usePromptActions /title', () => {
   })
 })
 
+describe('usePromptActions desktop slash pickers', () => {
+  beforeEach(() => {
+    setSessions(() => [sessionInfo({ id: '20260610_120000_abcdef', title: 'Loaded session' })])
+  })
+
+  afterEach(() => {
+    cleanup()
+    vi.useRealTimers()
+    vi.restoreAllMocks()
+  })
+
+  it('resumes an exact session id even when it is not in the loaded sidebar cache', async () => {
+    const resumeStoredSession = vi.fn(async () => undefined)
+    const requestGateway = vi.fn(async () => ({}) as never)
+
+    let handle: HarnessHandle | null = null
+    render(
+      <Harness
+        onReady={h => (handle = h)}
+        refreshSessions={async () => undefined}
+        requestGateway={requestGateway}
+        resumeStoredSession={resumeStoredSession}
+      />
+    )
+
+    await handle!.submitText('/resume 20260610_130000_123abc')
+
+    expect(resumeStoredSession).toHaveBeenCalledWith('20260610_130000_123abc')
+    expect(requestGateway).not.toHaveBeenCalledWith('slash.exec', expect.anything())
+  })
+
+  it('marks a timed-out handoff as failed so the next attempt can retry', async () => {
+    vi.useFakeTimers()
+    const calls: { method: string; params?: Record<string, unknown> }[] = []
+    const requestGateway = vi.fn(async (method: string, params?: Record<string, unknown>) => {
+      calls.push({ method, params })
+
+      if (method === 'handoff.state') {
+        return { state: 'pending' } as never
+      }
+
+      return {} as never
+    })
+
+    let handle: HarnessHandle | null = null
+    render(<Harness onReady={h => (handle = h)} refreshSessions={async () => undefined} requestGateway={requestGateway} />)
+
+    const result = handle!.submitText('/handoff telegram')
+    await vi.advanceTimersByTimeAsync(61_000)
+    await result
+
+    expect(calls.some(call => call.method === 'handoff.request')).toBe(true)
+    expect(calls).toContainEqual({
+      method: 'handoff.fail',
+      params: {
+        error: expect.stringContaining('Timed out'),
+        session_id: RUNTIME_SESSION_ID
+      }
+    })
+  })
+})
+
 describe('usePromptActions submit / queue drain semantics', () => {
   afterEach(() => {
     cleanup()
diff --git a/apps/desktop/src/app/session/hooks/use-prompt-actions.ts b/apps/desktop/src/app/session/hooks/use-prompt-actions.ts
index 167f0d3224fa..15831bb41891 100644
--- a/apps/desktop/src/app/session/hooks/use-prompt-actions.ts
+++ b/apps/desktop/src/app/session/hooks/use-prompt-actions.ts
@@ -4,20 +4,24 @@ import { type MutableRefObject, useCallback, useEffect, useRef } from 'react'
 
 import { getProfiles, transcribeAudio } from '@/hermes'
 import { translateNow, type Translations, useI18n } from '@/i18n'
+import { stripAnsi } from '@/lib/ansi'
 import { branchGroupForUser, type ChatMessage, chatMessageText, textPart } from '@/lib/chat-messages'
 import {
   optimisticAttachmentRef,
   parseCommandDispatch,
   parseSlashCommand,
   pathLabel,
+  sessionTitle,
   SLASH_COMMAND_RE
 } from '@/lib/chat-runtime'
 import {
   type CommandsCatalogLike,
+  type DesktopActionId,
+  type DesktopPickerId,
   desktopSlashUnavailableMessage,
   filterDesktopCommandsCatalog,
   isDesktopSlashCommand,
-  isModelPickerCommand
+  resolveDesktopCommand
 } from '@/lib/desktop-slash-commands'
 import { triggerHaptic } from '@/lib/haptics'
 import { setMutableRef } from '@/lib/mutable-ref'
@@ -38,11 +42,13 @@ import {
   $busy,
   $connection,
   $messages,
+  $sessions,
   $yoloActive,
   setAwaitingResponse,
   setBusy,
   setMessages,
   setModelPickerOpen,
+  setSessionPickerOpen,
   setSessions,
   setYoloActive
 } from '@/store/session'
@@ -50,12 +56,30 @@ import {
 import type {
   ClientSessionState,
   FileAttachResponse,
+  HandoffFailResponse,
+  HandoffRequestResponse,
+  HandoffStateResponse,
   ImageAttachResponse,
   SessionSteerResponse,
   SessionTitleResponse,
   SlashExecResponse
 } from '../../types'
 
+interface HandoffResult {
+  ok: boolean
+  error?: string
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, ms))
+}
+
+function isSessionIdCandidate(value: string): boolean {
+  const trimmed = value.trim()
+
+  return /^\d{8}_\d{6}_[A-Fa-f0-9]{6}$/.test(trimmed) || /^[A-Fa-f0-9]{32}$/.test(trimmed)
+}
+
 function blobToDataUrl(blob: Blob): Promise<string> {
   return new Promise((resolve, reject) => {
     const reader = new FileReader()
@@ -245,6 +269,7 @@ interface PromptActionsOptions {
   handleSkinCommand: (arg: string) => string
   refreshSessions: () => Promise<void>
   requestGateway: <T>(method: string, params?: Record<string, unknown>) => Promise<T>
+  resumeStoredSession: (storedSessionId: string) => Promise<void> | void
   selectedStoredSessionIdRef: MutableRefObject<string | null>
   startFreshSessionDraft: () => void
   sttEnabled: boolean
@@ -260,6 +285,15 @@ interface SubmitTextOptions {
   fromQueue?: boolean
 }
 
+/** Everything a slash handler needs about the invocation it's serving. */
+interface SlashActionCtx {
+  arg: string
+  command: string
+  name: string
+  recordInput: boolean
+  sessionHint?: string
+}
+
 function renderCommandsCatalog(catalog: CommandsCatalogLike, copy: Translations['desktop']): string {
   const desktopCatalog = filterDesktopCommandsCatalog(catalog)
 
@@ -310,6 +344,7 @@ export function usePromptActions({
   handleSkinCommand,
   refreshSessions,
   requestGateway,
+  resumeStoredSession,
   selectedStoredSessionIdRef,
   startFreshSessionDraft,
   sttEnabled,
@@ -320,7 +355,11 @@ export function usePromptActions({
 
   const appendSessionTextMessage = useCallback(
     (sessionId: string, role: ChatMessage['role'], text: string) => {
-      const body = text.trim()
+      // Strip ANSI: slash-command output from the backend worker carries SGR
+      // color codes (e.g. "Unknown command" in red). The ESC byte is invisible
+      // in the chat panel, so without this the `[1;31m…[0m` payload leaks as
+      // literal text.
+      const body = stripAnsi(text).trim()
 
       if (!body) {
         return
@@ -696,230 +735,124 @@ export function usePromptActions({
     ]
   )
 
+  // Queue a handoff of this session to a messaging platform and watch it to
+  // a terminal state. We only write the request through the gateway; the
+  // separate `hermes gateway` process performs the actual transfer, so we
+  // poll `handoff.state` (mirror of the CLI's block-poll) for the result.
+  const handoffSession = useCallback(
+    async (
+      platform: string,
+      options?: { onProgress?: (state: string) => void; sessionId?: string }
+    ): Promise<HandoffResult> => {
+      const sid = options?.sessionId || activeSessionIdRef.current
+
+      if (!sid) {
+        return { error: copy.sessionUnavailable, ok: false }
+      }
+
+      const target = platform.trim().toLowerCase()
+
+      if (!target) {
+        return { error: copy.handoff.failed(''), ok: false }
+      }
+
+      try {
+        options?.onProgress?.('pending')
+        await requestGateway<HandoffRequestResponse>('handoff.request', {
+          platform: target,
+          session_id: sid
+        })
+      } catch (err) {
+        return { error: inlineErrorMessage(err, copy.handoff.failed(target)), ok: false }
+      }
+
+      const deadline = Date.now() + 60_000
+      let lastState = 'pending'
+
+      while (Date.now() < deadline) {
+        await delay(800)
+
+        let record: HandoffStateResponse
+
+        try {
+          record = await requestGateway<HandoffStateResponse>('handoff.state', { session_id: sid })
+        } catch {
+          continue
+        }
+
+        const state = record.state || 'pending'
+
+        if (state !== lastState) {
+          options?.onProgress?.(state)
+          lastState = state
+        }
+
+        if (state === 'completed') {
+          appendSessionTextMessage(sid, 'system', copy.handoff.systemNote(target))
+          notify({ kind: 'success', message: copy.handoff.success(target) })
+
+          return { ok: true }
+        }
+
+        if (state === 'failed') {
+          return { error: record.error || copy.handoff.failed(target), ok: false }
+        }
+      }
+
+      const cleanup = await requestGateway<HandoffFailResponse>('handoff.fail', {
+        error: copy.handoff.timedOut,
+        session_id: sid
+      }).catch(() => null)
+
+      if (cleanup?.state === 'completed') {
+        appendSessionTextMessage(sid, 'system', copy.handoff.systemNote(target))
+        notify({ kind: 'success', message: copy.handoff.success(target) })
+
+        return { ok: true }
+      }
+
+      return { error: copy.handoff.timedOut, ok: false }
+    },
+    [activeSessionIdRef, appendSessionTextMessage, copy, requestGateway]
+  )
+
   const executeSlashCommand = useCallback(
     async (rawCommand: string, options?: { sessionId?: string; recordInput?: boolean }) => {
-      const runSlash = async (commandText: string, sessionHint?: string, recordInput = true): Promise<void> => {
-        const command = commandText.trim()
-        const { name, arg } = parseSlashCommand(command)
-        const normalizedName = name.toLowerCase()
+      const ensureSessionId = async (sessionHint?: string) =>
+        sessionHint || activeSessionIdRef.current || (await createBackendSessionForSend())
 
-        if (!name) {
-          const sessionId = sessionHint || activeSessionIdRef.current || (await createBackendSessionForSend())
-
-          if (sessionId) {
-            appendSessionTextMessage(sessionId, 'system', copy.emptySlashCommand)
-          }
-
-          return
-        }
-
-        if (normalizedName === 'new' || normalizedName === 'reset') {
-          startFreshSessionDraft()
-
-          return
-        }
-
-        if (normalizedName === 'branch' || normalizedName === 'fork') {
-          await branchCurrentSession()
-
-          return
-        }
-
-        // /yolo maps to the status-bar YOLO control — a per-session approval
-        // bypass, same scope as the TUI's Shift+Tab. With no session yet we arm
-        // it locally; the session-create path applies it on the first message.
-        if (normalizedName === 'yolo') {
-          const sid = sessionHint || activeSessionIdRef.current
-          const next = !$yoloActive.get()
-
-          if (!sid) {
-            setYoloActive(next)
-            notify({ kind: 'success', message: next ? copy.yoloArmed : copy.yoloOff })
-
-            return
-          }
-
-          try {
-            const active = await setSessionYolo(requestGateway, sid, next)
-            appendSessionTextMessage(sid, 'system', copy.yoloSystem(active))
-          } catch {
-            notify({ kind: 'error', title: copy.yoloTitle, message: copy.yoloToggleFailed })
-          }
-
-          return
-        }
-
-        // /model opens the desktop model picker overlay — the same full
-        // provider+model picker reachable from the status-bar model button —
-        // instead of the headless prompt_toolkit modal the slash worker can't
-        // render. With explicit args (`/model <name> [--provider ...]`) run the
-        // switch directly through slash.exec so power users can still type it.
-        if (isModelPickerCommand(`/${normalizedName}`)) {
-          if (!arg.trim()) {
-            setModelPickerOpen(true)
-
-            return
-          }
-
-          const sid = sessionHint || activeSessionIdRef.current || (await createBackendSessionForSend())
-
-          if (!sid) {
-            notify({ kind: 'error', title: 'Session unavailable', message: 'Could not create a new session' })
-
-            return
-          }
-
-          try {
-            const result = await requestGateway<SlashExecResponse>('slash.exec', {
-              session_id: sid,
-              command: command.replace(/^\/+/, '')
-            })
-
-            const body = result?.output || `/${name}: model switched`
-            appendSessionTextMessage(
-              sid,
-              'system',
-              recordInput ? slashStatusText(command, body) : body
-            )
-          } catch (err) {
-            appendSessionTextMessage(
-              sid,
-              'system',
-              `error: ${err instanceof Error ? err.message : String(err)}`
-            )
-          }
-
-          return
-        }
-
-        if (normalizedName === 'skin' && !sessionHint && !activeSessionIdRef.current) {
-          notify({ kind: 'success', message: handleSkinCommand(arg) })
-
-          return
-        }
-
-        // /profile selects which profile new chats open in — no app relaunch.
-        // A profile is per-session now, so an existing thread can't change its
-        // profile mid-stream; `/profile <name>` instead points the next new chat
-        // (and the current empty draft) at that profile's backend.
-        if (normalizedName === 'profile') {
-          const target = arg.trim()
-          const current = normalizeProfileKey($activeGatewayProfile.get())
-
-          if (!target) {
-            notify({
-              kind: 'success',
-              message: copy.profileStatus(current)
-            })
-
-            return
-          }
-
-          try {
-            const { profiles } = await getProfiles()
-            const match = profiles.find(profile => profile.name === target)
-
-            if (!match) {
-              notify({
-                kind: 'error',
-                title: copy.unknownProfile,
-                message: copy.noProfileNamed(target, profiles.map(profile => profile.name).join(', '))
-              })
-
-              return
-            }
-
-            const key = normalizeProfileKey(match.name)
-
-            $newChatProfile.set(key)
-            // Swap the live gateway now so an empty draft sends into this
-            // profile immediately; an existing thread keeps its own profile.
-            await ensureGatewayProfile(key)
-            notify({ kind: 'success', message: copy.newChatsProfile(match.name) })
-          } catch (err) {
-            notifyError(err, copy.setProfileFailed)
-          }
-
-          return
-        }
-
-        const sessionId = sessionHint || activeSessionIdRef.current || (await createBackendSessionForSend())
+      // Resolve the target session plus a writer for inline slash output, or
+      // notify + return null when none can be created. Folds the ensure / bail /
+      // build-renderSlashOutput boilerplate every exec-style handler repeats.
+      const withSlashOutput = async (
+        ctx: SlashActionCtx
+      ): Promise<{ render: (text: string) => void; sessionId: string } | null> => {
+        const sessionId = await ensureSessionId(ctx.sessionHint)
 
         if (!sessionId) {
-          notify({
-            kind: 'error',
-            title: copy.sessionUnavailable,
-            message: copy.createSessionFailed
-          })
+          notify({ kind: 'error', title: copy.sessionUnavailable, message: copy.createSessionFailed })
 
+          return null
+        }
+
+        const render = (text: string) =>
+          appendSessionTextMessage(sessionId, 'system', ctx.recordInput ? slashStatusText(ctx.command, text) : text)
+
+        return { render, sessionId }
+      }
+
+      // `exec` commands (and unknown skill / quick commands the backend owns)
+      // run on the gateway and render their text output inline. This is the only
+      // path that talks to slash.exec / command.dispatch.
+      async function runExec(ctx: SlashActionCtx): Promise<void> {
+        const { arg, command, name } = ctx
+        const resolved = await withSlashOutput(ctx)
+
+        if (!resolved) {
           return
         }
 
-        const renderSlashOutput = (text: string) =>
-          appendSessionTextMessage(sessionId, 'system', recordInput ? slashStatusText(command, text) : text)
-
-        // /title <name> renames the session. Route through the gateway's
-        // `session.title` RPC — the same path the TUI uses — NOT the REST
-        // renameSession endpoint and NOT the slash worker.
-        //
-        // Why not the slash worker: it's a separate HermesCLI subprocess whose
-        // SQLite write to the shared state.db can silently fail (notably on
-        // Windows), and it never refreshes the sidebar.
-        //
-        // Why not REST renameSession: `sessionId` here is the *runtime* session
-        // id returned by session.create — it is NOT the stored DB `sessions.id`,
-        // and session.create deliberately does not persist a DB row until the
-        // first turn. The REST PATCH endpoint resolves against the sessions
-        // table, so a runtime id (or a brand-new, not-yet-persisted session)
-        // 404s with "Session not found" on every platform. See #38508 / #38576.
-        //
-        // session.title maps the runtime id to the in-memory session, writes
-        // through the gateway's own DB connection, and QUEUES the title
-        // (`pending: true`) when the row isn't persisted yet — so it works for a
-        // fresh chat too. refreshSessions() then pulls the authoritative title
-        // back into the sidebar. A bare `/title` (no arg) still falls through to
-        // the worker to display the current title.
-        if (normalizedName === 'title' && arg) {
-          try {
-            const result = await requestGateway<SessionTitleResponse>('session.title', {
-              session_id: sessionId,
-              title: arg
-            })
-
-            const finalTitle = (result?.title || arg).trim()
-            const queued = result?.pending === true
-
-            setSessions(prev => prev.map(s => (s.id === sessionId ? { ...s, title: finalTitle || null } : s)))
-            await refreshSessions().catch(() => undefined)
-            renderSlashOutput(
-              finalTitle
-                ? `Session title set: ${finalTitle}${queued ? ' (queued while session initializes)' : ''}`
-                : 'Session title cleared.'
-            )
-          } catch (err) {
-            renderSlashOutput(`error: ${err instanceof Error ? err.message : String(err)}`)
-          }
-
-          return
-        }
-
-        if (normalizedName === 'skin') {
-          renderSlashOutput(handleSkinCommand(arg))
-
-          return
-        }
-
-        if (name === 'help' || name === 'commands') {
-          try {
-            const catalog = await requestGateway<CommandsCatalogLike>('commands.catalog', { session_id: sessionId })
-
-            renderSlashOutput(renderCommandsCatalog(catalog, copy))
-          } catch (err) {
-            renderSlashOutput(`error: ${err instanceof Error ? err.message : String(err)}`)
-          }
-
-          return
-        }
+        const { render: renderSlashOutput, sessionId } = resolved
 
         if (!isDesktopSlashCommand(name)) {
           renderSlashOutput(desktopSlashUnavailableMessage(name) || `/${name} is not available in the desktop app.`)
@@ -943,11 +876,7 @@ export function usePromptActions({
 
         try {
           const dispatch = parseCommandDispatch(
-            await requestGateway<unknown>('command.dispatch', {
-              session_id: sessionId,
-              name,
-              arg
-            })
+            await requestGateway<unknown>('command.dispatch', { session_id: sessionId, name, arg })
           )
 
           if (!dispatch) {
@@ -994,6 +923,261 @@ export function usePromptActions({
         }
       }
 
+      // One handler per `action` command. Adding a desktop-native command is a
+      // registry row in desktop-slash-commands.ts plus an entry here — never a
+      // new branch in a dispatch ladder.
+      const actionHandlers: Record<DesktopActionId, (ctx: SlashActionCtx) => Promise<void>> = {
+        new: async () => {
+          startFreshSessionDraft()
+        },
+        branch: async () => {
+          await branchCurrentSession()
+        },
+        // /yolo maps to the status-bar YOLO control — a per-session approval
+        // bypass, same scope as the TUI's Shift+Tab. With no session yet we arm
+        // it locally; the session-create path applies it on the first message.
+        yolo: async ({ sessionHint }) => {
+          const sid = sessionHint || activeSessionIdRef.current
+          const next = !$yoloActive.get()
+
+          if (!sid) {
+            setYoloActive(next)
+            notify({ kind: 'success', message: next ? copy.yoloArmed : copy.yoloOff })
+
+            return
+          }
+
+          try {
+            const active = await setSessionYolo(requestGateway, sid, next)
+            appendSessionTextMessage(sid, 'system', copy.yoloSystem(active))
+          } catch {
+            notify({ kind: 'error', title: copy.yoloTitle, message: copy.yoloToggleFailed })
+          }
+        },
+        // /handoff hands this session to a messaging platform. The platform is
+        // completed inline in the slash popover (backend _handoff_completions),
+        // so there is no overlay: `/handoff <platform>` runs the desktop's own
+        // handoff RPC. cli_only on the backend, so it must not reach slash.exec.
+        handoff: async ({ arg, command, recordInput, sessionHint }) => {
+          const platform = arg.trim()
+
+          if (!platform) {
+            notify({ kind: 'success', message: copy.handoff.pickPlatform })
+
+            return
+          }
+
+          const sid = sessionHint || activeSessionIdRef.current
+
+          if (!sid) {
+            notify({ kind: 'error', title: copy.sessionUnavailable, message: copy.createSessionFailed })
+
+            return
+          }
+
+          const result = await handoffSession(platform, { sessionId: sid })
+
+          if (!result.ok && result.error) {
+            appendSessionTextMessage(sid, 'system', recordInput ? slashStatusText(command, result.error) : result.error)
+          }
+        },
+        // /profile selects which profile new chats open in — no app relaunch.
+        // A profile is per-session now, so an existing thread can't change its
+        // profile mid-stream; `/profile <name>` points the next new chat (and
+        // the current empty draft) at that profile's backend.
+        profile: async ({ arg }) => {
+          const target = arg.trim()
+          const current = normalizeProfileKey($activeGatewayProfile.get())
+
+          if (!target) {
+            notify({ kind: 'success', message: copy.profileStatus(current) })
+
+            return
+          }
+
+          try {
+            const { profiles } = await getProfiles()
+            const match = profiles.find(profile => profile.name === target)
+
+            if (!match) {
+              notify({
+                kind: 'error',
+                title: copy.unknownProfile,
+                message: copy.noProfileNamed(target, profiles.map(profile => profile.name).join(', '))
+              })
+
+              return
+            }
+
+            const key = normalizeProfileKey(match.name)
+
+            $newChatProfile.set(key)
+            await ensureGatewayProfile(key)
+            notify({ kind: 'success', message: copy.newChatsProfile(match.name) })
+          } catch (err) {
+            notifyError(err, copy.setProfileFailed)
+          }
+        },
+        skin: async ({ arg, command, recordInput, sessionHint }) => {
+          const sid = sessionHint || activeSessionIdRef.current
+          const message = handleSkinCommand(arg)
+
+          // No session to print into yet — surface it as a toast instead of
+          // spinning up a backend session just to change the theme.
+          if (!sid) {
+            notify({ kind: 'success', message })
+
+            return
+          }
+
+          appendSessionTextMessage(sid, 'system', recordInput ? slashStatusText(command, message) : message)
+        },
+        // /title <name> renames via the gateway's session.title RPC — the same
+        // path the TUI uses, NOT REST renameSession (which 404s on runtime ids)
+        // nor the slash worker (whose DB write can silently fail). Bare /title
+        // shows the current title, which the worker owns, so delegate to exec.
+        title: async ctx => {
+          if (!ctx.arg) {
+            await runExec(ctx)
+
+            return
+          }
+
+          const resolved = await withSlashOutput(ctx)
+
+          if (!resolved) {
+            return
+          }
+
+          const { render: renderSlashOutput, sessionId } = resolved
+          const { arg } = ctx
+
+          try {
+            const result = await requestGateway<SessionTitleResponse>('session.title', {
+              session_id: sessionId,
+              title: arg
+            })
+
+            const finalTitle = (result?.title || arg).trim()
+            const queued = result?.pending === true
+
+            setSessions(prev => prev.map(s => (s.id === sessionId ? { ...s, title: finalTitle || null } : s)))
+            await refreshSessions().catch(() => undefined)
+            renderSlashOutput(
+              finalTitle
+                ? `Session title set: ${finalTitle}${queued ? ' (queued while session initializes)' : ''}`
+                : 'Session title cleared.'
+            )
+          } catch (err) {
+            renderSlashOutput(`error: ${err instanceof Error ? err.message : String(err)}`)
+          }
+        },
+        help: async ctx => {
+          const resolved = await withSlashOutput(ctx)
+
+          if (!resolved) {
+            return
+          }
+
+          const { render: renderSlashOutput, sessionId } = resolved
+
+          try {
+            const catalog = await requestGateway<CommandsCatalogLike>('commands.catalog', { session_id: sessionId })
+
+            renderSlashOutput(renderCommandsCatalog(catalog, copy))
+          } catch (err) {
+            renderSlashOutput(`error: ${err instanceof Error ? err.message : String(err)}`)
+          }
+        }
+      }
+
+      // Picker commands open a desktop overlay; a typed arg is resolved by that
+      // picker so the command never dead-ends or falls through to the backend.
+      const openPicker = async (pickerId: DesktopPickerId, ctx: SlashActionCtx): Promise<void> => {
+        if (pickerId === 'model') {
+          if (!ctx.arg.trim()) {
+            setModelPickerOpen(true)
+
+            return
+          }
+
+          // Power users can still type `/model <name>` — run it on the backend.
+          await runExec(ctx)
+
+          return
+        }
+
+        // session picker — /resume, /sessions, /switch
+        const query = ctx.arg.trim()
+
+        if (!query) {
+          setSessionPickerOpen(true)
+
+          return
+        }
+
+        const sessions = $sessions.get()
+        const lower = query.toLowerCase()
+
+        const match =
+          sessions.find(session => session.id === query) ||
+          sessions.find(session => sessionTitle(session).toLowerCase().includes(lower)) ||
+          sessions.find(session => (session.preview ?? '').toLowerCase().includes(lower))
+
+        if (!match) {
+          if (isSessionIdCandidate(query)) {
+            await resumeStoredSession(query)
+
+            return
+          }
+
+          notify({ kind: 'error', message: copy.resumeFailed })
+
+          return
+        }
+
+        await resumeStoredSession(match.id)
+      }
+
+      // The whole dispatcher: resolve the command's desktop surface, then act on
+      // its kind. No per-command ladder — behavior lives in the registry.
+      async function runSlash(commandText: string, sessionHint?: string, recordInput = true): Promise<void> {
+        const command = commandText.trim()
+        const { name, arg } = parseSlashCommand(command)
+
+        if (!name) {
+          const sessionId = await ensureSessionId(sessionHint)
+
+          if (sessionId) {
+            appendSessionTextMessage(sessionId, 'system', copy.emptySlashCommand)
+          }
+
+          return
+        }
+
+        const ctx: SlashActionCtx = { arg, command, name, recordInput, sessionHint }
+        const surface = resolveDesktopCommand(`/${name}`)?.surface
+
+        switch (surface?.kind) {
+          case 'unavailable': {
+            const resolved = await withSlashOutput(ctx)
+            resolved?.render(desktopSlashUnavailableMessage(name) || `/${name} is not available in the desktop app.`)
+
+            return
+          }
+
+          case 'picker':
+            return openPicker(surface.picker, ctx)
+
+          case 'action':
+            return actionHandlers[surface.action](ctx)
+
+          default:
+            // exec spec, or an unknown skill / quick command the backend owns.
+            return runExec(ctx)
+        }
+      }
+
       await runSlash(rawCommand, options?.sessionId, options?.recordInput ?? true)
     },
     [
@@ -1004,8 +1188,10 @@ export function usePromptActions({
       copy,
       createBackendSessionForSend,
       handleSkinCommand,
+      handoffSession,
       refreshSessions,
       requestGateway,
+      resumeStoredSession,
       startFreshSessionDraft,
       submitPromptText
     ]
@@ -1314,6 +1500,7 @@ export function usePromptActions({
     cancelRun,
     editMessage,
     handleThreadMessagesChange,
+    handoffSession,
     reloadFromMessage,
     steerPrompt,
     submitText,
diff --git a/apps/desktop/src/app/types.ts b/apps/desktop/src/app/types.ts
index 672beb9a0898..01694dc82208 100644
--- a/apps/desktop/src/app/types.ts
+++ b/apps/desktop/src/app/types.ts
@@ -61,6 +61,26 @@ export interface SessionTitleResponse {
   session_key?: string
 }
 
+export interface HandoffRequestResponse {
+  queued?: boolean
+  session_key?: string
+  platform?: string
+  // Human-readable home channel name for the destination platform.
+  home_name?: string
+}
+
+export interface HandoffStateResponse {
+  // '' | 'pending' | 'running' | 'completed' | 'failed'
+  state?: string
+  platform?: string
+  error?: string
+}
+
+export interface HandoffFailResponse {
+  failed?: boolean
+  state?: string
+}
+
 export interface ExecCommandDispatchResponse {
   type: 'exec' | 'plugin'
   output?: string
diff --git a/apps/desktop/src/components/assistant-ui/directive-text.tsx b/apps/desktop/src/components/assistant-ui/directive-text.tsx
index 79f772d450fe..b870913b012f 100644
--- a/apps/desktop/src/components/assistant-ui/directive-text.tsx
+++ b/apps/desktop/src/components/assistant-ui/directive-text.tsx
@@ -63,7 +63,7 @@ export function directiveIconSvg(type: string) {
   return `<svg ${SVG_ATTRS} class="size-3 shrink-0 opacity-80">${inner}</svg>`
 }
 
-export function directiveIconElement(type: string) {
+function iconElementFromPaths(paths: string[]) {
   const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg')
   svg.setAttribute('class', 'size-3 shrink-0 opacity-80')
   svg.setAttribute('fill', 'none')
@@ -74,7 +74,7 @@ export function directiveIconElement(type: string) {
   svg.setAttribute('viewBox', '0 0 24 24')
   svg.setAttribute('xmlns', 'http://www.w3.org/2000/svg')
 
-  for (const d of iconPathsFor(type)) {
+  for (const d of paths) {
     const path = document.createElementNS('http://www.w3.org/2000/svg', 'path')
     path.setAttribute('d', d)
     svg.append(path)
@@ -83,6 +83,46 @@ export function directiveIconElement(type: string) {
   return svg
 }
 
+export function directiveIconElement(type: string) {
+  return iconElementFromPaths(iconPathsFor(type))
+}
+
+/** Per-type slash-command pill styling. The composer inserts these chips when a
+ *  command is picked; the kind drives a theme-aware accent so commands, skills,
+ *  and themes read distinctly (Cursor-style). */
+export type SlashChipKind = 'command' | 'skill' | 'theme'
+
+const SLASH_ICON_PATHS: Record<SlashChipKind, string[]> = {
+  command: ['M5 7l5 5l-5 5', 'M12 19l7 0'],
+  skill: ['M13 3l0 7l6 0l-8 11l0 -7l-6 0l8 -11'],
+  theme: [
+    'M3 21v-4a4 4 0 1 1 4 4h-4',
+    'M21 3a16 16 0 0 0 -12.8 10.2',
+    'M21 3a16 16 0 0 1 -10.2 12.8',
+    'M10.6 9a9 9 0 0 1 4.4 4.4'
+  ]
+}
+
+const SLASH_CHIP_VARIANT: Record<SlashChipKind, string> = {
+  command:
+    'bg-[color-mix(in_srgb,var(--ui-accent)_14%,transparent)] text-[color-mix(in_srgb,var(--ui-accent)_82%,var(--foreground))]',
+  skill:
+    'bg-[color-mix(in_srgb,var(--ui-warm)_18%,transparent)] text-[color-mix(in_srgb,var(--ui-warm)_82%,var(--foreground))]',
+  theme:
+    'bg-[color-mix(in_srgb,var(--ui-accent-secondary)_16%,transparent)] text-[color-mix(in_srgb,var(--ui-accent-secondary)_82%,var(--foreground))]'
+}
+
+export const SLASH_CHIP_BASE_CLASS =
+  'mx-0.5 inline-flex max-w-64 items-center gap-1 rounded px-1.5 py-0.5 align-middle text-[0.86em] font-medium leading-none'
+
+export function slashChipClass(kind: SlashChipKind): string {
+  return `${SLASH_CHIP_BASE_CLASS} ${SLASH_CHIP_VARIANT[kind]}`
+}
+
+export function slashIconElement(kind: SlashChipKind) {
+  return iconElementFromPaths(SLASH_ICON_PATHS[kind])
+}
+
 const DirectiveIcon: FC<{ type: string }> = ({ type }) => (
   <svg
     className="size-3 shrink-0 opacity-80"
diff --git a/apps/desktop/src/components/assistant-ui/thread.tsx b/apps/desktop/src/components/assistant-ui/thread.tsx
index 32b7729f6372..03273a915b38 100644
--- a/apps/desktop/src/components/assistant-ui/thread.tsx
+++ b/apps/desktop/src/components/assistant-ui/thread.tsx
@@ -929,22 +929,42 @@ const SystemMessage: FC = () => {
   const slashStatus = text.match(SLASH_STATUS_RE)
 
   if (slashStatus?.groups) {
+    const output = slashStatus.groups.output.trim()
+    // Single-line status (e.g. "model → x") reads best centered inline; padded
+    // multiline output (catalogs, usage tables) needs left-aligned, wider room
+    // or the column alignment breaks.
+    const multiline = output.includes('\n')
+
     return (
       <MessagePrimitive.Root
-        className="max-w-[min(86%,44rem)] self-center px-2 py-0.5 text-center text-[0.6875rem] leading-5 text-muted-foreground/60"
+        className={cn(
+          'w-[60%] max-w-[44rem] self-center px-2 py-0.5 text-[0.6875rem] leading-5 text-muted-foreground/60',
+          multiline ? 'text-left' : 'text-center'
+        )}
         data-role="system"
         data-slot="aui_system-message-root"
       >
         <span className="font-mono text-muted-foreground/55">{slashStatus.groups.command}</span>
-        <span className="mx-1.5 text-muted-foreground/35">·</span>
-        <LinkifiedText className="whitespace-pre-wrap" explicitOnly pretty={false} text={slashStatus.groups.output.trim()} />
+        {multiline ? (
+          <LinkifiedText className="mt-0.5 block whitespace-pre-wrap" explicitOnly pretty={false} text={output} />
+        ) : (
+          <>
+            <span className="mx-1.5 text-muted-foreground/35">·</span>
+            <LinkifiedText className="whitespace-pre-wrap" explicitOnly pretty={false} text={output} />
+          </>
+        )}
       </MessagePrimitive.Root>
     )
   }
 
+  const multiline = text.includes('\n')
+
   return (
     <MessagePrimitive.Root
-      className="max-w-[min(86%,44rem)] self-center px-2 py-0.5 text-center text-[0.6875rem] leading-5 text-muted-foreground/55"
+      className={cn(
+        'w-[60%] max-w-[44rem] self-center px-2 py-0.5 text-[0.6875rem] leading-5 text-muted-foreground/55',
+        multiline ? 'text-left' : 'text-center'
+      )}
       data-role="system"
       data-slot="aui_system-message-root"
     >
diff --git a/apps/desktop/src/components/session-picker.tsx b/apps/desktop/src/components/session-picker.tsx
new file mode 100644
index 000000000000..048fa32a2089
--- /dev/null
+++ b/apps/desktop/src/components/session-picker.tsx
@@ -0,0 +1,108 @@
+import { useQuery } from '@tanstack/react-query'
+import { Dialog as DialogPrimitive } from 'radix-ui'
+import { useEffect, useMemo, useState } from 'react'
+
+import { Command, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList } from '@/components/ui/command'
+import { listSessions } from '@/hermes'
+import { useI18n } from '@/i18n'
+import { sessionTitle } from '@/lib/chat-runtime'
+import { Check, MessageCircle } from '@/lib/icons'
+import { cn } from '@/lib/utils'
+
+interface SessionPickerDialogProps {
+  /** Stored id of the session currently open, so it can be flagged in the list. */
+  activeStoredSessionId?: string | null
+  onOpenChange: (open: boolean) => void
+  onResume: (storedSessionId: string) => void
+  open: boolean
+}
+
+/**
+ * Desktop equivalent of the TUI's sessions overlay (`/resume`, `/sessions`,
+ * `/switch`): a focused, type-to-filter list of recent sessions that resumes
+ * the picked one. Mirrors the command palette's cmdk surface but scoped to
+ * sessions only, so `/resume` feels first-class instead of falling through to
+ * the headless slash worker (which can't render the picker).
+ */
+export function SessionPickerDialog({
+  activeStoredSessionId,
+  onOpenChange,
+  onResume,
+  open
+}: SessionPickerDialogProps) {
+  const { t } = useI18n()
+  const [search, setSearch] = useState('')
+
+  const sessionsQuery = useQuery({
+    enabled: open,
+    queryFn: () => listSessions(200, 1, 'exclude'),
+    queryKey: ['session-picker', 'sessions']
+  })
+
+  useEffect(() => {
+    if (!open) {
+      setSearch('')
+    }
+  }, [open])
+
+  const sessions = useMemo(() => sessionsQuery.data?.sessions ?? [], [sessionsQuery.data])
+
+  return (
+    <DialogPrimitive.Root onOpenChange={onOpenChange} open={open}>
+      <DialogPrimitive.Portal>
+        <DialogPrimitive.Overlay className="fixed inset-0 z-[200] bg-black/15 backdrop-blur-[1px] data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:animate-in data-[state=open]:fade-in-0" />
+        <DialogPrimitive.Content
+          aria-describedby={undefined}
+          className="fixed left-1/2 top-[14vh] z-[210] w-[min(40rem,calc(100vw-2rem))] -translate-x-1/2 overflow-hidden rounded-xl border border-(--ui-stroke-secondary) bg-(--ui-chat-bubble-background) shadow-lg duration-150 data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=closed]:zoom-out-95 data-[state=open]:animate-in data-[state=open]:fade-in-0 data-[state=open]:slide-in-from-top-2 data-[state=open]:zoom-in-95"
+        >
+          <DialogPrimitive.Title className="sr-only">{t.commandCenter.sections.sessions}</DialogPrimitive.Title>
+          <Command className="bg-transparent" loop>
+            <CommandInput
+              onValueChange={setSearch}
+              placeholder={t.commandCenter.searchPlaceholder}
+              value={search}
+            />
+            <CommandList className="max-h-[min(24rem,60vh)]">
+              <CommandEmpty>{t.commandCenter.noResults}</CommandEmpty>
+              <CommandGroup
+                className="**:[[cmdk-group-heading]]:uppercase **:[[cmdk-group-heading]]:tracking-wider **:[[cmdk-group-heading]]:text-[0.6875rem] **:[[cmdk-group-heading]]:text-muted-foreground/70"
+                heading={t.commandCenter.sections.sessions}
+              >
+                {sessions.map(session => {
+                  const title = sessionTitle(session)
+                  const preview = session.preview?.trim()
+
+                  return (
+                    <CommandItem
+                      className="gap-2.5"
+                      key={session.id}
+                      onSelect={() => {
+                        onResume(session.id)
+                        onOpenChange(false)
+                      }}
+                      value={`${title} ${preview ?? ''} ${session.id}`}
+                    >
+                      <MessageCircle className="size-4 shrink-0 text-muted-foreground" />
+                      <span className="flex min-w-0 flex-col leading-snug">
+                        <span className="truncate">{title}</span>
+                        {preview ? (
+                          <span className="truncate text-xs text-muted-foreground/70">{preview}</span>
+                        ) : null}
+                      </span>
+                      <Check
+                        className={cn(
+                          'ml-auto size-4 shrink-0 text-foreground',
+                          session.id !== activeStoredSessionId && 'invisible'
+                        )}
+                      />
+                    </CommandItem>
+                  )
+                })}
+              </CommandGroup>
+            </CommandList>
+          </Command>
+        </DialogPrimitive.Content>
+      </DialogPrimitive.Portal>
+    </DialogPrimitive.Root>
+  )
+}
diff --git a/apps/desktop/src/i18n/en.ts b/apps/desktop/src/i18n/en.ts
index 5aaf090d7e66..5a18d47efa97 100644
--- a/apps/desktop/src/i18n/en.ts
+++ b/apps/desktop/src/i18n/en.ts
@@ -1778,7 +1778,14 @@ export const en: Translations = {
     clipboard: 'Clipboard',
     noClipboardImage: 'No image found in clipboard',
     clipboardPasteFailed: 'Clipboard paste failed',
-    dropFiles: 'Drop files'
+    dropFiles: 'Drop files',
+    handoff: {
+      pickPlatform: 'Choose a destination',
+      success: platform => `Handed off to ${platform}. Resume here anytime.`,
+      systemNote: platform => `↻ Handed off to ${platform} — resume here anytime.`,
+      failed: error => `Handoff failed: ${error}`,
+      timedOut: 'Timed out waiting for the gateway. Is `hermes gateway` running?'
+    }
   },
 
   errors: {
diff --git a/apps/desktop/src/i18n/ja.ts b/apps/desktop/src/i18n/ja.ts
index 956788067ede..36634a6c0251 100644
--- a/apps/desktop/src/i18n/ja.ts
+++ b/apps/desktop/src/i18n/ja.ts
@@ -1914,7 +1914,14 @@ export const ja = defineLocale({
     clipboard: 'クリップボード',
     noClipboardImage: 'クリップボードに画像が見つかりません',
     clipboardPasteFailed: 'クリップボードからの貼り付けに失敗しました',
-    dropFiles: 'ファイルをドロップ'
+    dropFiles: 'ファイルをドロップ',
+    handoff: {
+      pickPlatform: '送信先を選択',
+      success: platform => `${platform} に引き継ぎました。いつでもここで再開できます。`,
+      systemNote: platform => `↻ ${platform} に引き継ぎました — いつでもここで再開できます。`,
+      failed: error => `引き継ぎに失敗しました: ${error}`,
+      timedOut: 'ゲートウェイの待機がタイムアウトしました。`hermes gateway` は起動していますか？'
+    }
   },
 
   errors: {
diff --git a/apps/desktop/src/i18n/types.ts b/apps/desktop/src/i18n/types.ts
index 77424e426ac8..7a10e5f3d1c2 100644
--- a/apps/desktop/src/i18n/types.ts
+++ b/apps/desktop/src/i18n/types.ts
@@ -1437,6 +1437,13 @@ export interface Translations {
     noClipboardImage: string
     clipboardPasteFailed: string
     dropFiles: string
+    handoff: {
+      pickPlatform: string
+      success: (platform: string) => string
+      systemNote: (platform: string) => string
+      failed: (error: string) => string
+      timedOut: string
+    }
   }
 
   errors: {
diff --git a/apps/desktop/src/i18n/zh-hant.ts b/apps/desktop/src/i18n/zh-hant.ts
index 9f045c4d0228..830dc475134e 100644
--- a/apps/desktop/src/i18n/zh-hant.ts
+++ b/apps/desktop/src/i18n/zh-hant.ts
@@ -1873,7 +1873,14 @@ export const zhHant = defineLocale({
     clipboard: '剪貼簿',
     noClipboardImage: '剪貼簿中沒有圖片',
     clipboardPasteFailed: '剪貼簿貼上失敗',
-    dropFiles: '拖曳檔案'
+    dropFiles: '拖曳檔案',
+    handoff: {
+      pickPlatform: '選擇目標平台',
+      success: platform => `已移交到 ${platform}。隨時可在此處恢復。`,
+      systemNote: platform => `↻ 已移交到 ${platform} — 隨時可在此處恢復。`,
+      failed: error => `移交失敗：${error}`,
+      timedOut: '等待閘道逾時。`hermes gateway` 是否正在執行？'
+    }
   },
 
   errors: {
diff --git a/apps/desktop/src/i18n/zh.ts b/apps/desktop/src/i18n/zh.ts
index f6b119a27771..dbad00cf5d11 100644
--- a/apps/desktop/src/i18n/zh.ts
+++ b/apps/desktop/src/i18n/zh.ts
@@ -1956,7 +1956,14 @@ export const zh: Translations = {
     clipboard: '剪贴板',
     noClipboardImage: '剪贴板中没有图片',
     clipboardPasteFailed: '粘贴剪贴板失败',
-    dropFiles: '拖放文件'
+    dropFiles: '拖放文件',
+    handoff: {
+      pickPlatform: '选择目标平台',
+      success: platform => `已移交到 ${platform}。随时可在此处恢复。`,
+      systemNote: platform => `↻ 已移交到 ${platform} — 随时可在此处恢复。`,
+      failed: error => `移交失败：${error}`,
+      timedOut: '等待网关超时。`hermes gateway` 是否正在运行？'
+    }
   },
 
   errors: {
diff --git a/apps/desktop/src/lib/ansi.ts b/apps/desktop/src/lib/ansi.ts
index f30987ec6053..c7770e8b7778 100644
--- a/apps/desktop/src/lib/ansi.ts
+++ b/apps/desktop/src/lib/ansi.ts
@@ -173,3 +173,14 @@ export function hasAnsiCodes(input: string): boolean {
   // eslint-disable-next-line no-control-regex
   return /\x1b\[/.test(input)
 }
+
+/** Remove all ANSI escape sequences, returning plain text. Use when output is
+ *  rendered as text (e.g. chat system messages) rather than styled segments —
+ *  otherwise the ESC byte is invisible and the `[1;31m…` payload leaks through. */
+export function stripAnsi(input: string): string {
+  if (!input) {
+    return input
+  }
+
+  return input.replace(OTHER_ESCAPE_RE, '').replace(CSI_RE, '')
+}
diff --git a/apps/desktop/src/lib/desktop-slash-commands.test.ts b/apps/desktop/src/lib/desktop-slash-commands.test.ts
index de0e72ec28b4..d37738173ce9 100644
--- a/apps/desktop/src/lib/desktop-slash-commands.test.ts
+++ b/apps/desktop/src/lib/desktop-slash-commands.test.ts
@@ -7,7 +7,9 @@ import {
   filterDesktopCommandsCatalog,
   isDesktopSlashCommand,
   isDesktopSlashSuggestion,
-  isModelPickerCommand
+  isModelPickerCommand,
+  isPickerCommand,
+  resolveDesktopCommand
 } from './desktop-slash-commands'
 
 describe('desktop slash command curation', () => {
@@ -38,6 +40,18 @@ describe('desktop slash command curation', () => {
     expect(isDesktopSlashSuggestion('/curator')).toBe(false)
   })
 
+  it('surfaces /tools, /save, and /personality on the desktop', () => {
+    expect(isDesktopSlashSuggestion('/tools')).toBe(true)
+    expect(isDesktopSlashSuggestion('/save')).toBe(true)
+    expect(isDesktopSlashSuggestion('/personality')).toBe(true)
+    expect(isDesktopSlashCommand('/tools')).toBe(true)
+    expect(isDesktopSlashCommand('/save')).toBe(true)
+    expect(isDesktopSlashCommand('/personality')).toBe(true)
+    expect(desktopSlashUnavailableMessage('/tools')).toBeNull()
+    expect(desktopSlashUnavailableMessage('/save')).toBeNull()
+    expect(desktopSlashUnavailableMessage('/personality')).toBeNull()
+  })
+
   it('allows aliases to execute without cluttering the popover', () => {
     expect(isDesktopSlashSuggestion('/reset')).toBe(false)
     expect(isDesktopSlashCommand('/reset')).toBe(true)
@@ -74,6 +88,24 @@ describe('desktop slash command curation', () => {
       ['/new', 'Start a new desktop chat'],
       ['/ship-it', 'Run release checklist']
     ])
+    // skill_count is recomputed from the filtered output (only /ship-it is an
+    // extension command — /new is a built-in) so the /help footer matches what
+    // the user actually sees rather than echoing the unfiltered backend total.
+    expect(filtered.skill_count).toBe(1)
+  })
+
+  it('recomputes skill_count to reflect only extensions surfaced on desktop', () => {
+    const filtered = filterDesktopCommandsCatalog({
+      pairs: [
+        ['/new', 'Start a new session'],
+        ['/clear', 'Clear terminal screen'],
+        ['/gif-search', 'Search for a gif'],
+        ['/ship-it', 'Run release checklist']
+      ],
+      skill_count: 12
+    })
+
+    expect(filtered.pairs?.map(([cmd]) => cmd)).toEqual(['/new', '/gif-search', '/ship-it'])
     expect(filtered.skill_count).toBe(2)
   })
 
@@ -123,4 +155,26 @@ describe('desktop slash command curation', () => {
     expect(isModelPickerCommand('/new')).toBe(false)
     expect(isModelPickerCommand('/skills')).toBe(false)
   })
+
+  it('gives /resume (and its aliases) a first-class session picker surface', () => {
+    expect(isPickerCommand('/resume', 'session')).toBe(true)
+    expect(isPickerCommand('/sessions', 'session')).toBe(true)
+    expect(isPickerCommand('/switch', 'session')).toBe(true)
+    // Unlike /model, /resume shows in the popover; its aliases stay hidden.
+    expect(isDesktopSlashSuggestion('/resume')).toBe(true)
+    expect(isDesktopSlashSuggestion('/sessions')).toBe(false)
+    expect(isDesktopSlashCommand('/switch')).toBe(true)
+    // The session picker is distinct from the model picker.
+    expect(isModelPickerCommand('/resume')).toBe(false)
+  })
+
+  it('resolves commands and aliases to their declared surface', () => {
+    expect(resolveDesktopCommand('/new')?.surface).toEqual({ kind: 'action', action: 'new' })
+    expect(resolveDesktopCommand('/reset')?.surface).toEqual({ kind: 'action', action: 'new' })
+    expect(resolveDesktopCommand('/resume')?.surface).toEqual({ kind: 'picker', picker: 'session' })
+    expect(resolveDesktopCommand('/usage')?.surface).toEqual({ kind: 'exec' })
+    expect(resolveDesktopCommand('/clear')?.surface).toEqual({ kind: 'unavailable', reason: 'terminal' })
+    // Skill / quick commands aren't in the registry.
+    expect(resolveDesktopCommand('/gif-search')).toBeNull()
+  })
 })
diff --git a/apps/desktop/src/lib/desktop-slash-commands.ts b/apps/desktop/src/lib/desktop-slash-commands.ts
index e373ac94317f..d898a6c83f16 100644
--- a/apps/desktop/src/lib/desktop-slash-commands.ts
+++ b/apps/desktop/src/lib/desktop-slash-commands.ts
@@ -22,110 +22,161 @@ export interface DesktopThemeCommandOption {
   name: string
 }
 
-const DESKTOP_COMMAND_META = [
-  ['/agents', 'Show active desktop sessions and running tasks'],
-  ['/background', 'Run a prompt in the background'],
-  ['/branch', 'Branch the latest message into a new chat'],
-  ['/compress', 'Compress this conversation context'],
-  ['/debug', 'Create a debug report'],
-  ['/goal', 'Manage the standing goal for this session'],
-  ['/help', 'Show desktop slash commands'],
-  ['/new', 'Start a new desktop chat'],
-  ['/profile', 'Switch the active Hermes profile'],
-  ['/queue', 'Queue a prompt for the next turn'],
-  ['/resume', 'Resume a saved session'],
-  ['/retry', 'Retry the last user message'],
-  ['/rollback', 'List or restore filesystem checkpoints'],
-  ['/skin', 'Switch desktop theme or cycle to the next one'],
-  ['/status', 'Show current session status'],
-  ['/steer', 'Steer the current run after the next tool call'],
-  ['/stop', 'Stop running background processes'],
-  ['/title', 'Rename the current session'],
-  ['/undo', 'Remove the last user/assistant exchange'],
-  ['/usage', 'Show token usage for this session'],
-  ['/version', 'Show Hermes Agent version'],
-  ['/yolo', 'Toggle YOLO — auto-approve dangerous commands']
-] as const
+/**
+ * Local client action a command resolves to. Each id maps to exactly one
+ * handler in the dispatcher (`use-prompt-actions`), so adding a command never
+ * means adding a branch to a switch ladder — you add a row here + a handler
+ * keyed by the id.
+ */
+export type DesktopActionId =
+  | 'branch'
+  | 'handoff'
+  | 'help'
+  | 'new'
+  | 'profile'
+  | 'skin'
+  | 'title'
+  | 'yolo'
 
-const DESKTOP_COMMANDS: ReadonlySet<string> = new Set(DESKTOP_COMMAND_META.map(([command]) => command))
+/** A command fulfilled by opening a desktop overlay picker. */
+export type DesktopPickerId = 'model' | 'session'
 
-const DESKTOP_ALIASES = new Map([
-  ['/bg', '/background'],
-  ['/btw', '/background'],
-  ['/fork', '/branch'],
-  ['/q', '/queue'],
-  ['/reload_mcp', '/reload-mcp'],
-  ['/reload_skills', '/reload-skills'],
-  ['/reset', '/new'],
-  ['/tasks', '/agents']
-])
+/** Why a known Hermes command has no desktop UI surface. */
+export type DesktopUnavailableReason = 'advanced' | 'messaging' | 'settings' | 'terminal'
 
-const DESKTOP_COMMAND_DESCRIPTIONS: ReadonlyMap<string, string> = new Map(DESKTOP_COMMAND_META)
+/**
+ * How the desktop fulfils a command. This is the single discriminator the
+ * dispatcher, popover, pills, and pickers all read — no parallel block-lists.
+ *
+ * - `action`     → handled by a local client handler (new chat, branch, …)
+ * - `picker`     → opens an overlay (`/model`, `/resume`); a typed arg is
+ *                  resolved by that picker instead of falling through
+ * - `exec`       → runs on the backend via slash.exec / command.dispatch and
+ *                  renders its text output inline
+ * - `unavailable`→ a known command with genuinely no desktop UI (terminal-only,
+ *                  messaging-only, …); shows a reason instead of executing
+ */
+export type DesktopCommandSurface =
+  | { kind: 'action'; action: DesktopActionId }
+  | { kind: 'picker'; picker: DesktopPickerId }
+  | { kind: 'exec' }
+  | { kind: 'unavailable'; reason: DesktopUnavailableReason }
 
-const PICKER_OWNED_COMMANDS = new Set(['/model'])
+export interface DesktopCommandSpec {
+  /** Canonical command, leading slash included (e.g. `/resume`). */
+  name: string
+  /** Popover/help label; omitted for unavailable commands (never surfaced). */
+  description?: string
+  aliases?: string[]
+  surface: DesktopCommandSurface
+  /**
+   * Hide from the slash popover / completions while still letting it execute.
+   * Used for picker commands reachable from chrome (the model picker lives on
+   * the status bar), so the popover doesn't dead-end on inline completion.
+   */
+  hidden?: boolean
+  /**
+   * The command has an inline options "screen" (theme / personality / session /
+   * platform / toolset list). Picking the bare command in the popover expands to
+   * that argument step instead of committing — mirroring typing `/<cmd> ` by hand.
+   */
+  args?: boolean
+}
 
-const TERMINAL_ONLY_COMMANDS = new Set([
-  '/browser',
-  '/busy',
-  '/clear',
-  '/commands',
-  '/compact',
-  '/config',
-  '/copy',
-  '/cron',
-  '/details',
-  '/exit',
-  '/footer',
-  '/gateway',
-  '/gquota',
-  '/history',
-  '/image',
-  '/indicator',
-  '/logs',
-  '/mouse',
-  '/paste',
-  '/platforms',
-  '/plugins',
-  '/quit',
-  '/redraw',
-  '/reload',
-  '/restart',
-  '/save',
-  '/sb',
-  '/set-home',
-  '/sethome',
-  '/snap',
-  '/snapshot',
-  '/statusbar',
-  '/toolsets',
-  '/tools',
-  '/update',
-  '/verbose'
-])
+const exec = (): DesktopCommandSurface => ({ kind: 'exec' })
+const action = (id: DesktopActionId): DesktopCommandSurface => ({ kind: 'action', action: id })
+const picker = (id: DesktopPickerId): DesktopCommandSurface => ({ kind: 'picker', picker: id })
+const unavailable = (reason: DesktopUnavailableReason): DesktopCommandSurface => ({ kind: 'unavailable', reason })
 
-const MESSAGING_ONLY_COMMANDS = new Set(['/approve', '/deny'])
+/**
+ * THE source of truth for desktop slash commands. Everything below — execution
+ * gating, popover suggestions, catalog filtering, pill grouping, and the
+ * dispatcher's behavior — derives from this one table.
+ */
+const DESKTOP_COMMAND_SPECS: readonly DesktopCommandSpec[] = [
+  // Local client actions
+  { name: '/new', description: 'Start a new desktop chat', aliases: ['/reset'], surface: action('new') },
+  { name: '/branch', description: 'Branch the latest message into a new chat', aliases: ['/fork'], surface: action('branch') },
+  { name: '/yolo', description: 'Toggle YOLO — auto-approve dangerous commands', surface: action('yolo') },
+  { name: '/handoff', description: 'Hand off this session to a messaging platform', surface: action('handoff'), args: true },
+  { name: '/profile', description: 'Switch the active Hermes profile', surface: action('profile') },
+  { name: '/skin', description: 'Switch desktop theme or cycle to the next one', surface: action('skin'), args: true },
+  { name: '/title', description: 'Rename the current session', surface: action('title') },
+  { name: '/help', description: 'Show desktop slash commands', aliases: ['/commands'], surface: action('help') },
 
-const SETTINGS_OWNED_COMMANDS = new Set(['/skills'])
+  // Overlay pickers
+  { name: '/model', description: 'Switch the model for this session', surface: picker('model'), hidden: true },
+  {
+    name: '/resume',
+    description: 'Resume a saved session',
+    aliases: ['/sessions', '/switch'],
+    surface: picker('session'),
+    args: true
+  },
 
-const ADVANCED_COMMANDS = new Set([
-  '/curator',
-  '/fast',
-  '/insights',
-  '/kanban',
-  '/personality',
-  '/reasoning',
-  '/reload-mcp',
-  '/reload-skills',
-  '/voice'
-])
+  // Backend-executed commands that render useful inline output
+  { name: '/agents', description: 'Show active desktop sessions and running tasks', aliases: ['/tasks'], surface: exec() },
+  { name: '/background', description: 'Run a prompt in the background', aliases: ['/bg', '/btw'], surface: exec() },
+  { name: '/compress', description: 'Compress this conversation context', surface: exec() },
+  { name: '/debug', description: 'Create a debug report', surface: exec() },
+  { name: '/goal', description: 'Manage the standing goal for this session', surface: exec() },
+  { name: '/personality', description: 'Switch personality for this session', surface: exec(), args: true },
+  { name: '/queue', description: 'Queue a prompt for the next turn', aliases: ['/q'], surface: exec() },
+  { name: '/retry', description: 'Retry the last user message', surface: exec() },
+  { name: '/rollback', description: 'List or restore filesystem checkpoints', surface: exec() },
+  { name: '/save', description: 'Save the current transcript to JSON', surface: exec() },
+  { name: '/status', description: 'Show current session status', surface: exec() },
+  { name: '/steer', description: 'Steer the current run after the next tool call', surface: exec() },
+  { name: '/stop', description: 'Stop running background processes', surface: exec() },
+  { name: '/tools', description: 'List or toggle tools available to the agent', surface: exec(), args: true },
+  { name: '/undo', description: 'Remove the last user/assistant exchange', surface: exec() },
+  { name: '/usage', description: 'Show token usage for this session', surface: exec() },
+  { name: '/version', description: 'Show Hermes Agent version', surface: exec() },
 
-const BLOCKED_COMMANDS = new Set([
-  ...PICKER_OWNED_COMMANDS,
-  ...TERMINAL_ONLY_COMMANDS,
-  ...MESSAGING_ONLY_COMMANDS,
-  ...SETTINGS_OWNED_COMMANDS,
-  ...ADVANCED_COMMANDS
-])
+  // No desktop surface, but carry an alias (underscore spelling variants).
+  { name: '/reload-mcp', aliases: ['/reload_mcp'], surface: unavailable('advanced') },
+  { name: '/reload-skills', aliases: ['/reload_skills'], surface: unavailable('advanced') }
+]
+
+// Known commands with no desktop surface (and no alias) — a flat name list
+// per reason beats 40 identical object literals.
+const NO_DESKTOP_SURFACE: Record<DesktopUnavailableReason, readonly string[]> = {
+  terminal: [
+    '/browser', '/busy', '/clear', '/compact', '/config', '/copy', '/cron', '/details',
+    '/exit', '/footer', '/gateway', '/gquota', '/history', '/image', '/indicator', '/logs',
+    '/mouse', '/paste', '/platforms', '/plugins', '/quit', '/redraw', '/reload', '/restart',
+    '/sb', '/set-home', '/sethome', '/snap', '/snapshot', '/statusbar', '/toolsets', '/update', '/verbose'
+  ],
+  messaging: ['/approve', '/deny'],
+  settings: ['/skills'],
+  advanced: ['/curator', '/fast', '/insights', '/kanban', '/reasoning', '/voice']
+}
+
+const ALL_SPECS: readonly DesktopCommandSpec[] = [
+  ...DESKTOP_COMMAND_SPECS,
+  ...(Object.entries(NO_DESKTOP_SURFACE) as [DesktopUnavailableReason, readonly string[]][]).flatMap(
+    ([reason, names]) => names.map(name => ({ name, surface: unavailable(reason) }))
+  )
+]
+
+const SPEC_BY_NAME = new Map<string, DesktopCommandSpec>(ALL_SPECS.map(spec => [spec.name, spec]))
+
+const ALIAS_TO_CANONICAL = new Map<string, string>(
+  ALL_SPECS.flatMap(spec => (spec.aliases ?? []).map(alias => [alias, spec.name] as const))
+)
+
+const UNAVAILABLE_MESSAGE: Record<DesktopUnavailableReason, (command: string) => string> = {
+  advanced: command =>
+    `${command} is not shown in the desktop slash palette. Use the relevant desktop control or terminal interface instead.`,
+  messaging: command => `${command} is only used from messaging platforms.`,
+  settings: command => `${command} is managed from the desktop sidebar.`,
+  terminal: command => `${command} is only available in the terminal interface.`
+}
+
+const PICKER_UNAVAILABLE_MESSAGE: Record<DesktopPickerId, (command: string) => string> = {
+  model: command => `${command} uses the desktop model picker instead of a slash command.`,
+  session: command => `${command} uses the desktop session picker instead of a slash command.`
+}
 
 function normalizeCommand(command: string): string {
   const trimmed = command.trim()
@@ -137,27 +188,25 @@ function normalizeCommand(command: string): string {
 export function canonicalDesktopSlashCommand(command: string): string {
   const normalized = normalizeCommand(command)
 
-  return DESKTOP_ALIASES.get(normalized) || normalized
+  return ALIAS_TO_CANONICAL.get(normalized) || normalized
 }
 
-export function isDesktopSlashCommand(command: string): boolean {
+/** Resolve a command (or alias) to its desktop spec, or null for unknown/extension commands. */
+export function resolveDesktopCommand(command: string): DesktopCommandSpec | null {
+  return SPEC_BY_NAME.get(canonicalDesktopSlashCommand(command)) ?? null
+}
+
+function isKnownHermesSlashCommand(command: string): boolean {
   const normalized = normalizeCommand(command)
-  const canonical = canonicalDesktopSlashCommand(normalized)
 
-  if (BLOCKED_COMMANDS.has(normalized) || BLOCKED_COMMANDS.has(canonical)) {
-    return false
-  }
-
-  return DESKTOP_COMMANDS.has(canonical) || !isKnownHermesSlashCommand(normalized)
+  return SPEC_BY_NAME.has(normalized) || ALIAS_TO_CANONICAL.has(normalized)
 }
 
 /**
  * An "extension" command is anything the backend surfaces that is NOT one of
  * Hermes' built-in slash commands — i.e. skill commands (`/gif-search`,
  * `/codex`, …) and user-defined quick commands. These are user-activated, so
- * they should appear in the desktop slash palette even though they aren't in
- * the curated `DESKTOP_COMMANDS` allow-list. This mirrors the predicate in
- * `isDesktopSlashCommand` that already lets them EXECUTE when typed.
+ * they appear in the desktop slash palette and execute when typed.
  */
 export function isDesktopSlashExtensionCommand(command: string): boolean {
   const normalized = normalizeCommand(command)
@@ -169,63 +218,85 @@ export function isDesktopSlashExtensionCommand(command: string): boolean {
   return !isKnownHermesSlashCommand(normalized)
 }
 
-export function isDesktopSlashSuggestion(command: string): boolean {
-  const normalized = normalizeCommand(command)
-  const canonical = canonicalDesktopSlashCommand(normalized)
+/** Gates execution: true unless the command is a known no-desktop-surface command. */
+export function isDesktopSlashCommand(command: string): boolean {
+  const spec = resolveDesktopCommand(command)
 
-  // Surface skill / quick commands (extensions the backend provides) alongside
-  // the curated built-ins. Built-in aliases stay hidden so the popover isn't
-  // cluttered with duplicates.
-  if (isDesktopSlashExtensionCommand(normalized)) {
-    return true
+  if (spec) {
+    return spec.surface.kind !== 'unavailable'
   }
 
-  return DESKTOP_COMMANDS.has(canonical) && !DESKTOP_ALIASES.has(normalized)
+  return isDesktopSlashExtensionCommand(command)
+}
+
+/** Gates discovery in the popover/completions. */
+export function isDesktopSlashSuggestion(command: string): boolean {
+  const normalized = normalizeCommand(command)
+
+  // Aliases stay hidden so the popover isn't cluttered with duplicates.
+  if (ALIAS_TO_CANONICAL.has(normalized)) {
+    return false
+  }
+
+  const spec = SPEC_BY_NAME.get(normalized)
+
+  if (spec) {
+    return spec.surface.kind !== 'unavailable' && !spec.hidden
+  }
+
+  // Skill / quick commands the backend provides.
+  return isDesktopSlashExtensionCommand(normalized)
 }
 
 /**
- * True for commands the desktop fulfils by opening the model picker overlay
- * (e.g. `/model`) rather than executing a slash command. The caller opens the
- * picker UI instead of printing the "uses the desktop model picker" notice.
+ * True for commands the desktop fulfils by opening an overlay picker
+ * (`/model`, `/resume`/`/sessions`/`/switch`). Optionally pin to one picker.
  */
-export function isModelPickerCommand(command: string): boolean {
-  const normalized = normalizeCommand(command)
-  const canonical = canonicalDesktopSlashCommand(normalized)
+export function isPickerCommand(command: string, picker?: DesktopPickerId): boolean {
+  const surface = resolveDesktopCommand(command)?.surface
 
-  return PICKER_OWNED_COMMANDS.has(canonical)
+  if (surface?.kind !== 'picker') {
+    return false
+  }
+
+  return picker ? surface.picker === picker : true
+}
+
+/** Back-compat shim for the model picker check. */
+export function isModelPickerCommand(command: string): boolean {
+  return isPickerCommand(command, 'model')
 }
 
 export function desktopSlashUnavailableMessage(command: string): string | null {
-  const normalized = normalizeCommand(command)
-  const canonical = canonicalDesktopSlashCommand(normalized)
+  const canonical = canonicalDesktopSlashCommand(command)
+  const surface = SPEC_BY_NAME.get(canonical)?.surface
 
-  if (PICKER_OWNED_COMMANDS.has(canonical)) {
-    return `/${canonical.slice(1)} uses the desktop model picker instead of a slash command.`
+  if (!surface) {
+    return null
   }
 
-  if (SETTINGS_OWNED_COMMANDS.has(canonical)) {
-    return `/${canonical.slice(1)} is managed from the desktop sidebar.`
+  if (surface.kind === 'unavailable') {
+    return UNAVAILABLE_MESSAGE[surface.reason](canonical)
   }
 
-  if (MESSAGING_ONLY_COMMANDS.has(canonical)) {
-    return `/${canonical.slice(1)} is only used from messaging platforms.`
-  }
-
-  if (ADVANCED_COMMANDS.has(canonical)) {
-    return `/${canonical.slice(1)} is not shown in the desktop slash palette. Use the relevant desktop control or terminal interface instead.`
-  }
-
-  if (TERMINAL_ONLY_COMMANDS.has(normalized) || TERMINAL_ONLY_COMMANDS.has(canonical)) {
-    return `/${canonical.slice(1)} is only available in the terminal interface.`
+  if (surface.kind === 'picker') {
+    return PICKER_UNAVAILABLE_MESSAGE[surface.picker](canonical)
   }
 
   return null
 }
 
 export function desktopSlashDescription(command: string, fallback = ''): string {
-  const canonical = canonicalDesktopSlashCommand(command)
+  return SPEC_BY_NAME.get(canonicalDesktopSlashCommand(command))?.description || fallback
+}
 
-  return DESKTOP_COMMAND_DESCRIPTIONS.get(canonical) || fallback
+/**
+ * True when picking the bare command should expand to its inline argument
+ * options (theme / personality / session / platform / toolset) rather than
+ * committing immediately. Lets the popover act as a two-step picker.
+ */
+export function desktopSlashCommandTakesArgs(command: string): boolean {
+  return resolveDesktopCommand(command)?.args ?? false
 }
 
 export function desktopSkinSlashCompletions(
@@ -274,13 +345,36 @@ export function filterDesktopCommandsCatalog(catalog: CommandsCatalogLike): Comm
     ?.filter(([command]) => isDesktopSlashSuggestion(command))
     .map(([command, description]) => [command, desktopSlashDescription(command, description)] as [string, string])
 
+  // Recount skill commands from the filtered output so /help's footer reflects
+  // what the user actually sees. Backend's skill_count includes commands the
+  // desktop hides (terminal-only, picker-owned, advanced), producing a footer
+  // like "60 skill commands available" while only ~29 appear in the list.
+  const filteredCommands = new Set<string>()
+
+  for (const section of categories ?? []) {
+    for (const [command] of section.pairs) {
+      filteredCommands.add(canonicalDesktopSlashCommand(command))
+    }
+  }
+
+  for (const [command] of pairs ?? []) {
+    filteredCommands.add(canonicalDesktopSlashCommand(command))
+  }
+
+  let skillCount = 0
+
+  for (const command of filteredCommands) {
+    if (isDesktopSlashExtensionCommand(command)) {
+      skillCount += 1
+    }
+  }
+
+  const hasSkillCount = catalog.skill_count !== undefined || skillCount > 0
+
   return {
     ...catalog,
     ...(categories ? { categories } : {}),
-    ...(pairs ? { pairs } : {})
+    ...(pairs ? { pairs } : {}),
+    ...(hasSkillCount ? { skill_count: skillCount } : {})
   }
 }
-
-function isKnownHermesSlashCommand(command: string): boolean {
-  return DESKTOP_COMMANDS.has(command) || DESKTOP_ALIASES.has(command) || BLOCKED_COMMANDS.has(command)
-}
diff --git a/apps/desktop/src/store/session.ts b/apps/desktop/src/store/session.ts
index 6df96946bf1c..4139915cea2c 100644
--- a/apps/desktop/src/store/session.ts
+++ b/apps/desktop/src/store/session.ts
@@ -200,6 +200,7 @@ export const $availablePersonalities = atom<string[]>([])
 export const $introSeed = atom(0)
 export const $contextSuggestions = atom<ContextSuggestion[]>([])
 export const $modelPickerOpen = atom(false)
+export const $sessionPickerOpen = atom(false)
 
 export const setConnection = (next: Updater<HermesConnection | null>) => updateAtom($connection, next)
 export const setGatewayState = (next: Updater<string>) => updateAtom($gatewayState, next)
@@ -249,6 +250,7 @@ export const setAvailablePersonalities = (next: Updater<string[]>) => updateAtom
 export const setIntroSeed = (next: Updater<number>) => updateAtom($introSeed, next)
 export const setContextSuggestions = (next: Updater<ContextSuggestion[]>) => updateAtom($contextSuggestions, next)
 export const setModelPickerOpen = (next: Updater<boolean>) => updateAtom($modelPickerOpen, next)
+export const setSessionPickerOpen = (next: Updater<boolean>) => updateAtom($sessionPickerOpen, next)
 
 // Watchdog tracking — when does a "working" session count as stuck?
 // Long-running tool calls (LLM inference, long shell commands, web fetches)
diff --git a/hermes_cli/commands.py b/hermes_cli/commands.py
index f23d1960da77..aded4d41d81c 100644
--- a/hermes_cli/commands.py
+++ b/hermes_cli/commands.py
@@ -1544,12 +1544,140 @@ class SlashCommandCompleter(Completer):
         except Exception:
             pass
 
+    @staticmethod
+    def _tools_completions(sub_text: str, sub_lower: str):
+        """Yield completions for /tools — subcommand + toolset/MCP-server name.
+
+        Handles both ``/tools <tab>`` (suggesting ``list|disable|enable``) and
+        ``/tools enable <tab>`` / ``/tools disable <tab>`` (suggesting toolset
+        keys and MCP server prefixes, filtered by current enable state so the
+        user only sees actionable options).
+        """
+        SUBS = ("list", "disable", "enable")
+        parts = sub_text.split()
+        trailing_space = sub_text.endswith(" ")
+
+        # Subcommand stage: zero words typed, or completing the first word.
+        if len(parts) == 0 or (len(parts) == 1 and not trailing_space):
+            partial = sub_text if not trailing_space else ""
+            for sub in SUBS:
+                if sub.startswith(partial.lower()) and sub != partial.lower():
+                    yield Completion(sub, start_position=-len(partial), display=sub)
+            return
+
+        subcommand = parts[0].lower()
+        if subcommand not in ("enable", "disable"):
+            return
+
+        partial = "" if trailing_space else parts[-1]
+        partial_lower = partial.lower()
+        already = set(parts[1:] if trailing_space else parts[1:-1])
+
+        try:
+            from hermes_cli.config import load_config
+            from hermes_cli.tools_config import (
+                CONFIGURABLE_TOOLSETS,
+                _get_platform_tools,
+                _get_plugin_toolset_keys,
+            )
+
+            config = load_config()
+            enabled = _get_platform_tools(config, "cli", include_default_mcp_servers=False)
+
+            for ts_key, label, _desc in CONFIGURABLE_TOOLSETS:
+                if ts_key in already or not ts_key.startswith(partial_lower):
+                    continue
+                is_on = ts_key in enabled
+                if subcommand == "enable" and is_on:
+                    continue
+                if subcommand == "disable" and not is_on:
+                    continue
+                yield Completion(
+                    ts_key,
+                    start_position=-len(partial),
+                    display=ts_key,
+                    display_meta=label,
+                )
+
+            for ts_key in sorted(_get_plugin_toolset_keys()):
+                if ts_key in already or not ts_key.startswith(partial_lower):
+                    continue
+                is_on = ts_key in enabled
+                if subcommand == "enable" and is_on:
+                    continue
+                if subcommand == "disable" and not is_on:
+                    continue
+                yield Completion(
+                    ts_key,
+                    start_position=-len(partial),
+                    display=ts_key,
+                    display_meta="plugin toolset",
+                )
+
+            mcp_servers = config.get("mcp_servers") or {}
+            if isinstance(mcp_servers, dict):
+                for server in sorted(mcp_servers):
+                    prefix = f"{server}:"
+                    if prefix in already or not prefix.startswith(partial_lower):
+                        continue
+                    yield Completion(
+                        prefix,
+                        start_position=-len(partial),
+                        display=prefix,
+                        display_meta=f"MCP server '{server}'",
+                    )
+        except Exception:
+            return
+
+    @staticmethod
+    def _handoff_completions(sub_text: str, sub_lower: str):
+        """Yield platform completions for /handoff.
+
+        Offers connected (enabled + configured) gateway platforms. A recorded
+        home channel is NOT required to list a platform — it's often learned at
+        runtime — so the meta hints whether one is set yet. Completes only the
+        first arg (the platform); once one is chosen, stop.
+        """
+        parts = sub_text.split()
+        trailing_space = sub_text.endswith(" ")
+        if len(parts) > 1 or (len(parts) == 1 and trailing_space):
+            return
+        partial = "" if (not parts or trailing_space) else parts[-1]
+        partial_lower = partial.lower()
+        try:
+            from gateway.config import load_gateway_config
+
+            gw = load_gateway_config()
+            platforms = gw.get_connected_platforms()
+        except Exception:
+            return
+        for platform in platforms:
+            name = platform.value
+            if not name.startswith(partial_lower):
+                continue
+            try:
+                home = gw.get_home_channel(platform)
+            except Exception:
+                home = None
+            meta = f"→ {home.name}" if home and getattr(home, "name", None) else "send this session here"
+            yield Completion(
+                name,
+                start_position=-len(partial),
+                display=name,
+                display_meta=meta,
+            )
+
     @staticmethod
     def _personality_completions(sub_text: str, sub_lower: str):
         """Yield completions for /personality from configured personalities."""
         try:
-            from hermes_cli.config import load_config
-            personalities = load_config().get("agent", {}).get("personalities", {})
+            # Resolve from the same source the runtime applies personalities —
+            # agent.personalities via the CLI config (which ships the built-ins).
+            # load_config()'s schema has no agent.personalities, so the completer
+            # used to come back empty even with personalities available.
+            from cli import load_cli_config
+
+            personalities = (load_cli_config().get("agent") or {}).get("personalities", {}) or {}
             if "none".startswith(sub_lower) and "none" != sub_lower:
                 yield Completion(
                     "none",
@@ -1602,6 +1730,17 @@ class SlashCommandCompleter(Completer):
                     yield from self._personality_completions(sub_text, sub_lower)
                     return
 
+            # /tools needs multi-word completion (subcommand + toolset name)
+            # so it handles both stages itself, bypassing the single-word
+            # SUBCOMMANDS branch below.
+            if base_cmd == "/tools":
+                yield from self._tools_completions(sub_text, sub_lower)
+                return
+
+            if base_cmd == "/handoff":
+                yield from self._handoff_completions(sub_text, sub_lower)
+                return
+
             # Static subcommand completions
             if " " not in sub_text and base_cmd in SUBCOMMANDS and self._command_allowed(base_cmd):
                 for sub in SUBCOMMANDS[base_cmd]:
diff --git a/tests/hermes_cli/test_commands.py b/tests/hermes_cli/test_commands.py
index 6a63ebe73e5b..62c2be4ab79b 100644
--- a/tests/hermes_cli/test_commands.py
+++ b/tests/hermes_cli/test_commands.py
@@ -691,6 +691,169 @@ class TestSubcommandCompletion:
         completions = _completions(SlashCommandCompleter(), "/help ")
         assert completions == []
 
+    def test_tools_subcommand_completion(self):
+        """`/tools ` should suggest list, disable, enable."""
+        completions = _completions(SlashCommandCompleter(), "/tools ")
+        texts = {c.text for c in completions}
+        assert texts == {"list", "disable", "enable"}
+
+    def test_tools_subcommand_prefix_filters(self):
+        completions = _completions(SlashCommandCompleter(), "/tools en")
+        texts = {c.text for c in completions}
+        assert texts == {"enable"}
+
+    def test_tools_enable_completes_toolset_names(self, monkeypatch):
+        """`/tools enable ` should suggest currently-disabled toolsets."""
+        from hermes_cli import commands as commands_mod
+
+        # `web` is enabled, `spotify` is disabled — enabling should only offer
+        # the disabled ones.
+        monkeypatch.setattr(
+            "hermes_cli.tools_config._get_platform_tools",
+            lambda *_a, **_k: {"web", "file"},
+        )
+        monkeypatch.setattr("hermes_cli.config.load_config", lambda: {})
+        monkeypatch.setattr(
+            "hermes_cli.tools_config._get_plugin_toolset_keys",
+            lambda: set(),
+        )
+
+        completions = _completions(SlashCommandCompleter(), "/tools enable ")
+        texts = {c.text for c in completions}
+        # Should include disabled toolsets, exclude already-enabled ones.
+        assert "web" not in texts
+        assert "file" not in texts
+        assert "spotify" in texts
+
+    def test_tools_disable_completes_enabled_toolsets_only(self, monkeypatch):
+        monkeypatch.setattr(
+            "hermes_cli.tools_config._get_platform_tools",
+            lambda *_a, **_k: {"web", "file"},
+        )
+        monkeypatch.setattr("hermes_cli.config.load_config", lambda: {})
+        monkeypatch.setattr(
+            "hermes_cli.tools_config._get_plugin_toolset_keys",
+            lambda: set(),
+        )
+
+        completions = _completions(SlashCommandCompleter(), "/tools disable ")
+        texts = {c.text for c in completions}
+        # Should include enabled toolsets, exclude disabled ones.
+        assert texts == {"web", "file"}
+
+    def test_tools_enable_partial_filters(self, monkeypatch):
+        monkeypatch.setattr(
+            "hermes_cli.tools_config._get_platform_tools",
+            lambda *_a, **_k: set(),
+        )
+        monkeypatch.setattr("hermes_cli.config.load_config", lambda: {})
+        monkeypatch.setattr(
+            "hermes_cli.tools_config._get_plugin_toolset_keys",
+            lambda: set(),
+        )
+
+        completions = _completions(SlashCommandCompleter(), "/tools enable sp")
+        texts = {c.text for c in completions}
+        assert texts == {"spotify"}
+
+    def test_tools_enable_skips_already_listed(self, monkeypatch):
+        """If the user already typed a name, don't suggest it again."""
+        monkeypatch.setattr(
+            "hermes_cli.tools_config._get_platform_tools",
+            lambda *_a, **_k: set(),
+        )
+        monkeypatch.setattr("hermes_cli.config.load_config", lambda: {})
+        monkeypatch.setattr(
+            "hermes_cli.tools_config._get_plugin_toolset_keys",
+            lambda: set(),
+        )
+
+        completions = _completions(SlashCommandCompleter(), "/tools enable spotify ")
+        texts = {c.text for c in completions}
+        assert "spotify" not in texts
+
+    def test_tools_suggests_mcp_server_prefixes(self, monkeypatch):
+        monkeypatch.setattr(
+            "hermes_cli.tools_config._get_platform_tools",
+            lambda *_a, **_k: set(),
+        )
+        monkeypatch.setattr(
+            "hermes_cli.config.load_config",
+            lambda: {"mcp_servers": {"github": {}, "linear": {}}},
+        )
+        monkeypatch.setattr(
+            "hermes_cli.tools_config._get_plugin_toolset_keys",
+            lambda: set(),
+        )
+
+        completions = _completions(SlashCommandCompleter(), "/tools enable git")
+        texts = {c.text for c in completions}
+        assert "github:" in texts
+
+    def _fake_gateway(self, monkeypatch, platforms):
+        """Patch load_gateway_config with a fake whose connected platforms are
+        the keys of `platforms` (name -> home as None or a (chat_id, name) tuple).
+        """
+        from types import SimpleNamespace
+
+        enums = {name: SimpleNamespace(value=name) for name in platforms}
+        homes = {
+            name: (None if home is None else SimpleNamespace(chat_id=home[0], name=home[1]))
+            for name, home in platforms.items()
+        }
+        fake = SimpleNamespace(
+            get_connected_platforms=lambda: list(enums.values()),
+            get_home_channel=lambda p: homes[p.value],
+        )
+        monkeypatch.setattr("gateway.config.load_gateway_config", lambda: fake)
+
+    def test_handoff_completes_connected_platforms(self, monkeypatch):
+        """`/handoff ` offers connected platforms, with or without a home channel."""
+        self._fake_gateway(
+            monkeypatch,
+            {
+                "telegram": ("123", "Me"),
+                "discord": None,  # no home channel yet -> still listed
+            },
+        )
+
+        texts = {c.text for c in _completions(SlashCommandCompleter(), "/handoff ")}
+        assert texts == {"telegram", "discord"}
+
+    def test_handoff_filters_by_prefix(self, monkeypatch):
+        self._fake_gateway(
+            monkeypatch,
+            {
+                "telegram": ("1", "H"),
+                "signal": ("2", "H"),
+            },
+        )
+
+        texts = {c.text for c in _completions(SlashCommandCompleter(), "/handoff te")}
+        assert texts == {"telegram"}
+
+    def test_handoff_no_completion_after_platform_chosen(self, monkeypatch):
+        self._fake_gateway(monkeypatch, {"telegram": ("1", "H")})
+        assert _completions(SlashCommandCompleter(), "/handoff telegram ") == []
+
+    def test_handoff_completion_swallows_config_errors(self, monkeypatch):
+        def _boom():
+            raise RuntimeError("no gateway config")
+
+        monkeypatch.setattr("gateway.config.load_gateway_config", _boom)
+        assert _completions(SlashCommandCompleter(), "/handoff ") == []
+
+    def test_personality_completes_configured_personalities(self):
+        """`/personality ` lists real personalities, not just `none`.
+
+        Regression: the completer read load_config().agent.personalities, a path
+        that never exists, so it always came back empty. It must resolve from the
+        CLI config the runtime actually applies (which ships built-ins).
+        """
+        texts = {c.text for c in _completions(SlashCommandCompleter(), "/personality ")}
+        assert "none" in texts
+        assert len(texts) > 1
+
 
 # ── Ghost text (SlashCommandAutoSuggest) ────────────────────────────────
 
diff --git a/tests/test_tui_gateway_server.py b/tests/test_tui_gateway_server.py
index 3b95b8dceb8c..c510c4ef230f 100644
--- a/tests/test_tui_gateway_server.py
+++ b/tests/test_tui_gateway_server.py
@@ -86,6 +86,47 @@ def test_session_context_uses_session_cwd(monkeypatch, tmp_path):
         server._sessions.pop(sid, None)
 
 
+def test_handoff_fail_marks_only_inflight_rows(monkeypatch):
+    class DbContext:
+        def __init__(self, db):
+            self.db = db
+
+        def __enter__(self):
+            return self.db
+
+        def __exit__(self, *_args):
+            return False
+
+    class FakeDb:
+        def __init__(self, state):
+            self.state = state
+            self.failed_with = None
+
+        def get_handoff_state(self, _key):
+            return {"state": self.state, "platform": "telegram", "error": None}
+
+        def fail_handoff(self, _key, error):
+            self.failed_with = error
+            self.state = "failed"
+
+    sid = "rt-handoff"
+    server._sessions[sid] = {"session_key": "stored-handoff"}
+    try:
+        pending = FakeDb("pending")
+        monkeypatch.setattr(server, "_session_db", lambda _session: DbContext(pending))
+        result = server._methods["handoff.fail"]("r1", {"session_id": sid, "error": "timed out"})
+        assert result["result"] == {"failed": True, "state": "failed"}
+        assert pending.failed_with == "timed out"
+
+        completed = FakeDb("completed")
+        monkeypatch.setattr(server, "_session_db", lambda _session: DbContext(completed))
+        result = server._methods["handoff.fail"]("r2", {"session_id": sid, "error": "late timeout"})
+        assert result["result"] == {"failed": False, "state": "completed"}
+        assert completed.failed_with is None
+    finally:
+        server._sessions.pop(sid, None)
+
+
 def test_session_context_explicit_cwd_for_ephemeral_task(monkeypatch, tmp_path):
     """Background/preview tasks use ephemeral ids absent from `_sessions`, so the
     parent workspace is passed explicitly; it must pin instead of clearing back
diff --git a/tui_gateway/server.py b/tui_gateway/server.py
index 390c31b092e0..5af8530abc5b 100644
--- a/tui_gateway/server.py
+++ b/tui_gateway/server.py
@@ -1,5 +1,6 @@
 import atexit
 import concurrent.futures
+import contextlib
 import contextvars
 import copy
 import inspect
@@ -1171,6 +1172,34 @@ def _ensure_session_db_row(session: dict) -> None:
                 pass
 
 
+@contextlib.contextmanager
+def _session_db(session: dict):
+    """Yield the SessionDB that owns this session's row (profile-aware).
+
+    Mirrors :func:`_ensure_session_db_row`: a remote/profile session persists
+    into its own profile's ``state.db`` (a fresh handle we close on exit);
+    everything else borrows the shared ``_get_db()`` handle (left open). Yields
+    None when the db is unavailable.
+    """
+    db, close_db = None, False
+    profile_home = session.get("profile_home")
+    if profile_home:
+        from hermes_state import SessionDB
+
+        try:
+            db, close_db = SessionDB(db_path=Path(profile_home) / "state.db"), True
+        except Exception:
+            logger.debug("failed to open profile db for session", exc_info=True)
+    else:
+        db = _get_db()
+    try:
+        yield db
+    finally:
+        if close_db and db is not None:
+            with contextlib.suppress(Exception):
+                db.close()
+
+
 def _set_session_cwd(session: dict, cwd: str) -> str:
     resolved = os.path.abspath(os.path.expanduser(str(cwd)))
     if not os.path.isdir(resolved):
@@ -4193,6 +4222,145 @@ def _(rid, params: dict) -> dict:
         return _err(rid, 5007, str(e))
 
 
+@method("handoff.request")
+def _(rid, params: dict) -> dict:
+    """Queue a handoff of this session to a messaging platform.
+
+    Desktop parity with the CLI ``/handoff`` command: we only write
+    ``handoff_state='pending'`` onto the persisted session row. The actual
+    transfer is performed by the separate ``hermes gateway`` process, whose
+    ``_handoff_watcher`` claims the row, re-binds the session to the platform's
+    home channel, and forges a synthetic turn. The desktop then polls
+    ``handoff.state`` for the terminal result.
+    """
+    session, err = _sess_nowait(params, rid)
+    if err:
+        return err
+    if session.get("running"):
+        return _err(
+            rid,
+            4009,
+            "session busy — wait for the current turn to finish, then retry the handoff",
+        )
+
+    platform_name = (params.get("platform", "") or "").strip().lower()
+    if not platform_name:
+        return _err(rid, 4023, "platform required")
+
+    # Validate against the live gateway config — an unconfigured platform or a
+    # missing home channel would leave the handoff pending forever, so reject
+    # up front with a clear, actionable message (mirrors cli.py).
+    try:
+        from gateway.config import Platform, load_gateway_config
+    except Exception as e:  # pragma: no cover — gateway pkg always ships
+        return _err(rid, 5021, f"could not load gateway config: {e}")
+    try:
+        platform = Platform(platform_name)
+    except (ValueError, KeyError):
+        return _err(rid, 4024, f"unknown platform '{platform_name}'")
+    try:
+        gw_config = load_gateway_config()
+    except Exception as e:
+        return _err(rid, 5021, f"could not load gateway config: {e}")
+    pcfg = gw_config.platforms.get(platform)
+    if not pcfg or not pcfg.enabled:
+        return _err(
+            rid,
+            4025,
+            f"platform '{platform_name}' is not configured/enabled in the gateway",
+        )
+    home = gw_config.get_home_channel(platform)
+    if not home or not home.chat_id:
+        return _err(
+            rid,
+            4026,
+            f"no home channel configured for {platform_name} — set one with "
+            "/sethome on the destination chat first",
+        )
+
+    # The watcher transfers a persisted DB row, so make sure one exists even
+    # for a brand-new empty chat (mirrors the CLI's set_session_title stub).
+    _ensure_session_db_row(session)
+
+    with _session_db(session) as db:
+        if db is None:
+            return _db_unavailable_error(rid, code=5007)
+        key = session["session_key"]
+        try:
+            if not db.get_session(key):
+                db.set_session_title(key, f"handoff-{key[:8]}")
+            ok = db.request_handoff(key, platform_name)
+        except Exception as e:
+            return _err(rid, 5007, str(e))
+
+    if not ok:
+        return _err(
+            rid,
+            4027,
+            "session is already in flight for handoff — wait for it to settle, then retry",
+        )
+    return _ok(
+        rid,
+        {
+            "queued": True,
+            "session_key": key,
+            "platform": platform_name,
+            "home_name": home.name,
+        },
+    )
+
+
+@method("handoff.state")
+def _(rid, params: dict) -> dict:
+    """Poll the handoff state for a session.
+
+    Returns ``{state, platform, error}`` where ``state`` is one of
+    ``pending|running|completed|failed`` (or empty when no handoff record
+    exists). Desktop polls this after ``handoff.request``.
+    """
+    session, err = _sess_nowait(params, rid)
+    if err:
+        return err
+    with _session_db(session) as db:
+        if db is None:
+            return _db_unavailable_error(rid, code=5007)
+        record = db.get_handoff_state(session["session_key"])
+
+    record = record or {}
+    return _ok(
+        rid,
+        {
+            "state": record.get("state") or "",
+            "platform": record.get("platform") or "",
+            "error": record.get("error") or "",
+        },
+    )
+
+
+@method("handoff.fail")
+def _(rid, params: dict) -> dict:
+    """Mark an in-flight handoff as failed so the user can retry.
+
+    Desktop calls this when its bounded poll times out. Only pending/running
+    rows are changed so a late success from the gateway watcher is not clobbered.
+    """
+    session, err = _sess_nowait(params, rid)
+    if err:
+        return err
+    reason = str(params.get("error") or "handoff failed").strip()[:500]
+    with _session_db(session) as db:
+        if db is None:
+            return _db_unavailable_error(rid, code=5007)
+        key = session["session_key"]
+        record = db.get_handoff_state(key) or {}
+        state = record.get("state") or ""
+        if state in {"pending", "running"}:
+            db.fail_handoff(key, reason)
+            return _ok(rid, {"failed": True, "state": "failed"})
+
+    return _ok(rid, {"failed": False, "state": state})
+
+
 @method("session.usage")
 def _(rid, params: dict) -> dict:
     session, err = _sess_nowait(params, rid)

From fe54960142d1e6edc9e43299c0e8889964f4e837 Mon Sep 17 00:00:00 2001
From: brooklyn! <brooklyn.bb.nicholson@gmail.com>
Date: Wed, 10 Jun 2026 21:35:38 -0500
Subject: [PATCH 04/28] desktop: un-truncate the active slash/@ row so long
 descriptions stay readable (#43926)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Follow-up to #42351. Slash command rows render the command label and
description with `truncate`, so skill commands and longer blurbs were
clipped with no way to read the full text. Rather than add a floating
tooltip (which overlaps the popover and only helps the mouse), the active
row — the one reached by keyboard arrows or hover, since onMouseEnter
already sets activeIndex — now drops truncation and wraps inline
(whitespace-normal break-words). Idle rows stay single-line/truncated so
the list reads compact.
---
 .../src/app/chat/composer/trigger-popover.tsx | 19 +++++++++++++++++--
 1 file changed, 17 insertions(+), 2 deletions(-)

diff --git a/apps/desktop/src/app/chat/composer/trigger-popover.tsx b/apps/desktop/src/app/chat/composer/trigger-popover.tsx
index 1099c0748ba3..dffa1ae77459 100644
--- a/apps/desktop/src/app/chat/composer/trigger-popover.tsx
+++ b/apps/desktop/src/app/chat/composer/trigger-popover.tsx
@@ -136,9 +136,24 @@ export function ComposerTriggerPopover({
               >
                 {isSlash ? (
                   <>
-                    <span className="truncate text-[0.8125rem] font-medium leading-snug text-foreground">{display}</span>
+                    {/* Active row (keyboard nav or hover) un-truncates inline so
+                        long command names / descriptions stay readable without a
+                        floating tooltip. */}
+                    <span
+                      className={cn(
+                        'text-[0.8125rem] font-medium leading-snug text-foreground',
+                        active ? 'whitespace-normal break-words' : 'truncate'
+                      )}
+                    >
+                      {display}
+                    </span>
                     {description && (
-                      <span className="truncate text-[0.6875rem] leading-snug text-(--ui-text-tertiary)">
+                      <span
+                        className={cn(
+                          'text-[0.6875rem] leading-snug text-(--ui-text-tertiary)',
+                          active ? 'whitespace-normal break-words' : 'truncate'
+                        )}
+                      >
                         {description}
                       </span>
                     )}

From e0e25717116c818d22f05a1875fe44960b189ad7 Mon Sep 17 00:00:00 2001
From: Matt Harris <mharris@parallel.ai>
Date: Fri, 29 May 2026 17:51:52 -0400
Subject: [PATCH 05/28] =?UTF-8?q?feat(web):=20Parallel-backed=20web=20sear?=
 =?UTF-8?q?ch=20&=20extract=20=E2=80=94=20free=20Search=20MCP=20when=20key?=
 =?UTF-8?q?less,=20v1=20REST=20when=20keyed?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Make Parallel the web search/extract backend with a zero-setup free tier:

- Keyless (no PARALLEL_API_KEY): web_search/web_extract work out of the box via
  Parallel's free hosted Search MCP (search.parallel.ai/mcp), and parallel
  becomes the default backend when no other web credentials are configured
  (ahead of ddgs, which is search-only). A small hand-rolled Streamable-HTTP
  JSON-RPC client speaks the MCP's web_search/web_fetch tools; the existing
  web_search/web_extract tools are the only tools registered.
- Keyed (PARALLEL_API_KEY set): uses the Parallel v1 REST endpoints
  (client.search / client.extract with advanced_settings.full_content) — no beta.
  Bumps parallel-web 0.4.2 -> 0.6.0.
- Attribution: on the free path only, results carry provider/attribution and the
  CLI tool line reads "Parallel search" / "Parallel fetch"; the paid path is
  unbranded.
- Selection/registration: web tools register unconditionally (free MCP backstop)
  while check_web_api_key remains a real usability probe; explicit per-capability
  backends are honored (so misconfig surfaces) rather than masked by the fallback.

Tested: live web_search/web_extract against search.parallel.ai in keyless and
keyed modes; unit suites for the MCP client, backend selection, and display
labeling; full agent run shows the "Parallel search" label on the free path.
---
 agent/display.py                              |  22 +-
 hermes_cli/tools_config.py                    |   9 +-
 plugins/web/parallel/provider.py              | 470 ++++++++++++++++--
 pyproject.toml                                |   2 +-
 tests/agent/test_display.py                   |  41 ++
 tests/hermes_cli/test_tools_config.py         |  13 +
 .../plugins/web/test_parallel_keyless_mcp.py  | 382 ++++++++++++++
 .../web/test_web_search_provider_plugins.py   |  27 +-
 tests/tools/test_web_providers.py             |  73 ++-
 tests/tools/test_web_providers_ddgs.py        |   8 +-
 tests/tools/test_web_providers_searxng.py     |   7 +-
 tests/tools/test_web_tools_config.py          |  98 +++-
 tools/lazy_deps.py                            |   2 +-
 tools/web_tools.py                            | 142 +++++-
 uv.lock                                       |   8 +-
 15 files changed, 1206 insertions(+), 98 deletions(-)
 create mode 100644 tests/plugins/web/test_parallel_keyless_mcp.py

diff --git a/agent/display.py b/agent/display.py
index 8514279888ea..84c8509faed2 100644
--- a/agent/display.py
+++ b/agent/display.py
@@ -858,6 +858,20 @@ def _detect_tool_failure(tool_name: str, result: str | None) -> tuple[bool, str]
     return False, ""
 
 
+def _used_free_parallel(result: str | None) -> bool:
+    """True when a web result came from Parallel's free Search MCP.
+
+    Only the keyless Parallel path tags its result with ``provider="parallel"``;
+    the paid REST path and every other provider omit it. Used to label the tool
+    line "Parallel search" / "Parallel fetch" exactly when the free MCP served
+    the call.
+    """
+    if not isinstance(result, str) or '"provider"' not in result:
+        return False
+    data = safe_json_loads(result)
+    return isinstance(data, dict) and str(data.get("provider", "")).lower() == "parallel"
+
+
 def get_cute_tool_message(
     tool_name: str, args: dict, duration: float, result: str | None = None,
 ) -> str:
@@ -895,15 +909,17 @@ def get_cute_tool_message(
         return f"{line}{failure_suffix}"
 
     if tool_name == "web_search":
-        return _wrap(f"┊ 🔍 search    {_trunc(args.get('query', ''), 42)}  {dur}")
+        verb = "Parallel search" if _used_free_parallel(result) else "search"
+        return _wrap(f"┊ 🔍 {verb:<9} {_trunc(args.get('query', ''), 42)}  {dur}")
     if tool_name == "web_extract":
+        verb = "Parallel fetch" if _used_free_parallel(result) else "fetch"
         urls = args.get("urls", [])
         if urls:
             url = urls[0] if isinstance(urls, list) else str(urls)
             domain = url.replace("https://", "").replace("http://", "").split("/")[0]
             extra = f" +{len(urls)-1}" if len(urls) > 1 else ""
-            return _wrap(f"┊ 📄 fetch     {_trunc(domain, 35)}{extra}  {dur}")
-        return _wrap(f"┊ 📄 fetch     pages  {dur}")
+            return _wrap(f"┊ 📄 {verb:<9} {_trunc(domain, 35)}{extra}  {dur}")
+        return _wrap(f"┊ 📄 {verb:<9} pages  {dur}")
     if tool_name == "terminal":
         return _wrap(f"┊ 💻 $         {_trunc(args.get('command', ''), 42)}  {dur}")
     if tool_name == "process":
diff --git a/hermes_cli/tools_config.py b/hermes_cli/tools_config.py
index ae97dbf54a29..01d4ba727931 100644
--- a/hermes_cli/tools_config.py
+++ b/hermes_cli/tools_config.py
@@ -2178,8 +2178,13 @@ def _toolset_needs_configuration_prompt(
         tts_cfg = config.get("tts", {})
         return not isinstance(tts_cfg, dict) or "provider" not in tts_cfg
     if ts_key == "web":
-        web_cfg = config.get("web", {})
-        return not isinstance(web_cfg, dict) or "backend" not in web_cfg
+        # Web works out of the box via Parallel's free Search MCP (no key), so
+        # don't force setup just because ``web.backend`` is unset — only prompt
+        # when web isn't actually usable (e.g. an explicit backend configured
+        # without its credentials). Lazy import: web_tools is heavy and most
+        # tools_config callers don't need it.
+        from tools.web_tools import check_web_api_key
+        return not check_web_api_key()
     if ts_key == "browser":
         browser_cfg = config.get("browser", {})
         return not isinstance(browser_cfg, dict) or "cloud_provider" not in browser_cfg
diff --git a/plugins/web/parallel/provider.py b/plugins/web/parallel/provider.py
index 38578e6b52c3..20c4291d77b9 100644
--- a/plugins/web/parallel/provider.py
+++ b/plugins/web/parallel/provider.py
@@ -1,14 +1,20 @@
 """Parallel.ai web search + content extraction — plugin form.
 
-Subclasses :class:`agent.web_search_provider.WebSearchProvider`. Uses two
-distinct Parallel SDK clients:
+Subclasses :class:`agent.web_search_provider.WebSearchProvider`.
 
-- ``Parallel`` (sync)        — for :meth:`search`
-- ``AsyncParallel`` (async)  — for :meth:`extract`
+Search runs on one of two transports, picked by credential:
 
-This is the first plugin to exercise the **async-extract** code path in
-the ABC: :meth:`extract` is declared ``async def``, and the dispatcher
-in :func:`tools.web_tools.web_extract_tool` detects coroutines via
+- **No key →** the free hosted Search MCP at ``https://search.parallel.ai/mcp``
+  (anonymous Streamable-HTTP JSON-RPC). This makes ``web_search`` work out of
+  the box with zero setup, which is why ``parallel`` is the keyless default
+  backend in :func:`tools.web_tools._get_backend`.
+- **``PARALLEL_API_KEY`` →** the ``parallel`` SDK's v1 ``search`` / ``extract``
+  REST endpoints (objective-tuned, mode-selectable, higher rate limits).
+
+Extract mirrors search: keyed uses the async SDK (``AsyncParallel``) v1
+``extract``; keyless uses the free MCP's ``web_fetch``. :meth:`extract` is
+declared ``async def`` and the dispatcher in
+:func:`tools.web_tools.web_extract_tool` detects coroutines via
 :func:`inspect.iscoroutinefunction` and awaits.
 
 Config keys this provider responds to::
@@ -17,25 +23,63 @@ Config keys this provider responds to::
       search_backend: "parallel"      # explicit per-capability
       extract_backend: "parallel"     # explicit per-capability
       backend: "parallel"             # shared fallback
-      # Optional: search mode (default "agentic"; also "fast" or "one-shot")
-      # via the PARALLEL_SEARCH_MODE env var.
+      # Optional: search mode (default "advanced"; also "basic")
+      # via the PARALLEL_SEARCH_MODE env var. REST path only.
 
 Env vars::
 
-    PARALLEL_API_KEY=...             # https://parallel.ai (required)
-    PARALLEL_SEARCH_MODE=agentic     # optional: agentic|fast|one-shot
+    PARALLEL_API_KEY=...             # https://parallel.ai (optional — unlocks
+                                     # the v1 REST Search API; without it,
+                                     # search and extract use the free MCP)
+    PARALLEL_SEARCH_MODE=advanced    # optional: basic|advanced (legacy
+                                     # fast/one-shot map to basic, agentic to
+                                     # advanced). REST path only.
 """
 
 from __future__ import annotations
 
+import asyncio
+import json
 import logging
 import os
+import uuid
 from typing import Any, Dict, List
 
+import httpx
+
 from agent.web_search_provider import WebSearchProvider
 
 logger = logging.getLogger(__name__)
 
+# Free hosted Search MCP — anonymous-friendly, used when no PARALLEL_API_KEY is
+# configured. Docs: https://docs.parallel.ai/integrations/mcp/search-mcp
+_MCP_SEARCH_URL = "https://search.parallel.ai/mcp"
+_MCP_PROTOCOL_VERSION = "2025-06-18"
+_MCP_CLIENT_NAME = "hermes-agent"
+_MCP_CLIENT_VERSION = "1.0.0"
+# Identify free-tier traffic at the HTTP layer. Without this, httpx sends a
+# generic ``python-httpx/<version>`` User-Agent and hermes usage is only visible
+# via the JSON-RPC ``clientInfo`` payload.
+_MCP_USER_AGENT = f"{_MCP_CLIENT_NAME}/{_MCP_CLIENT_VERSION}"
+_MCP_TIMEOUT_SECONDS = 30.0
+
+# Free-tier attribution. The hosted Search MCP is free to use; surfacing this
+# on keyless results credits Parallel and matches the free-tier terms
+# (https://parallel.ai/customer-terms).
+_FREE_MCP_ATTRIBUTION = (
+    "Search powered by the free Parallel Web Search MCP (https://parallel.ai)."
+)
+
+
+def _new_session_id() -> str:
+    """Mint a fresh Parallel ``session_id`` for a single tool call.
+
+    Per-call rather than process-global: one process serves many unrelated
+    chats in the gateway/batch runners, and a shared id would pool their
+    searches into one Parallel session.
+    """
+    return f"hermes-agent-{uuid.uuid4().hex}"
+
 # Module-level note: the canonical cache slots ``_parallel_client`` and
 # ``_async_parallel_client`` live on :mod:`tools.web_tools` so tests that do
 # ``tools.web_tools._parallel_client = None`` between cases see fresh state.
@@ -133,11 +177,319 @@ _get_async_parallel_client = _get_async_client
 
 
 def _resolve_search_mode() -> str:
-    """Return the validated PARALLEL_SEARCH_MODE value (default "agentic")."""
-    mode = os.getenv("PARALLEL_SEARCH_MODE", "agentic").lower().strip()
-    if mode not in {"fast", "one-shot", "agentic"}:
-        mode = "agentic"
-    return mode
+    """Return the validated v1 search mode (default "advanced").
+
+    V1 collapses the three Beta modes into two. We accept the v1 values
+    directly and map the legacy Beta values for back-compat with anyone who
+    still sets ``PARALLEL_SEARCH_MODE=fast|one-shot|agentic``:
+
+    - ``fast`` / ``one-shot`` → ``basic``  (lower latency)
+    - ``agentic``             → ``advanced`` (higher quality, the v1 default)
+    """
+    mode = os.getenv("PARALLEL_SEARCH_MODE", "advanced").lower().strip()
+    if mode == "basic" or mode in {"fast", "one-shot"}:
+        return "basic"
+    # advanced, legacy "agentic", and anything unrecognized → the v1 default.
+    return "advanced"
+
+
+# ---------------------------------------------------------------------------
+# Free Search MCP transport (keyless path)
+# ---------------------------------------------------------------------------
+#
+# A small hand-rolled Streamable-HTTP JSON-RPC client for the hosted Search
+# MCP, rather than the full MCP-client subsystem: we only call two tools
+# (``web_search`` / ``web_fetch``), so keeping it inline lets web_search and
+# web_extract stay ordinary tools with the MCP endpoint as just their wire
+# protocol.
+
+
+def _mcp_headers(
+    session_id: str | None,
+    api_key: str | None,
+    protocol_version: str | None = None,
+) -> Dict[str, str]:
+    """Headers for an MCP request.
+
+    A Bearer token is attached only when we actually hold a key — the free
+    endpoint is anonymous, and sending an empty/garbage token would make it
+    401 instead of serving the anonymous tier. After ``initialize`` the
+    Streamable-HTTP spec expects the negotiated ``MCP-Protocol-Version`` on
+    every follow-up request, so we echo it once known.
+    """
+    headers = {
+        "Content-Type": "application/json",
+        "Accept": "application/json, text/event-stream",
+        "User-Agent": _MCP_USER_AGENT,
+    }
+    if session_id:
+        headers["Mcp-Session-Id"] = session_id
+    if protocol_version:
+        headers["MCP-Protocol-Version"] = protocol_version
+    if api_key:
+        headers["Authorization"] = f"Bearer {api_key}"
+    return headers
+
+
+def _iter_mcp_messages(text: str):
+    """Yield JSON-RPC message dicts from a plain-JSON or SSE response body.
+
+    Handles ``application/json`` (a single object) and ``text/event-stream``
+    (SSE: events separated by blank lines; an event's one-or-more ``data:``
+    lines concatenate into a single JSON payload). Unparseable chunks and
+    non-``data`` SSE fields (``event:``/``id:``/comments) are skipped.
+    """
+    def _emit(payload):
+        # Streamable HTTP allows batching responses/notifications into a JSON
+        # array — flatten so callers always see individual message dicts.
+        if isinstance(payload, list):
+            yield from payload
+        elif payload is not None:
+            yield payload
+
+    body = (text or "").strip()
+    if not body:
+        return
+    if body.startswith("{") or body.startswith("["):
+        try:
+            parsed = json.loads(body)
+        except json.JSONDecodeError:
+            return
+        yield from _emit(parsed)
+        return
+
+    data_lines: List[str] = []
+
+    def _flush():
+        if not data_lines:
+            return None
+        try:
+            return json.loads("\n".join(data_lines))
+        except json.JSONDecodeError:
+            return None
+
+    for raw in body.split("\n"):
+        line = raw.rstrip("\r")
+        if line.startswith("data:"):
+            data_lines.append(line[len("data:"):].lstrip())
+        elif line.strip() == "":  # event boundary
+            yield from _emit(_flush())
+            data_lines = []
+    yield from _emit(_flush())
+
+
+def _mcp_response_envelope(text: str, request_id: str) -> Dict[str, Any]:
+    """Select the JSON-RPC response for *request_id* from an MCP response body.
+
+    Streamable-HTTP servers may emit progress/log notifications before the
+    final result, so we scan the whole stream and return the result/error
+    message whose ``id`` matches our request. Falls back to the last
+    result/error-bearing message if no id matches; ``{}`` if none is present.
+    """
+    fallback: Dict[str, Any] = {}
+    for msg in _iter_mcp_messages(text):
+        if not isinstance(msg, dict) or not ("result" in msg or "error" in msg):
+            continue
+        if msg.get("id") == request_id:
+            return msg
+        fallback = msg
+    return fallback
+
+
+def _mcp_payload(envelope: Dict[str, Any]) -> Dict[str, Any]:
+    """Extract the tool result payload from a ``tools/call`` envelope.
+
+    Prefers ``structuredContent`` (authoritative machine-readable form);
+    otherwise scans text blocks for the first JSON-parseable one. Raises on a
+    JSON-RPC error or a tool-level ``isError``.
+    """
+    if "error" in envelope:
+        raise RuntimeError(f"Parallel MCP error: {str(envelope['error'])[:500]}")
+    result = envelope.get("result") or {}
+    if result.get("isError"):
+        raise RuntimeError(f"Parallel MCP tool error: {str(result)[:500]}")
+
+    structured = result.get("structuredContent")
+    if isinstance(structured, dict):
+        return structured
+
+    for block in result.get("content", []) or []:
+        if isinstance(block, dict) and block.get("type") == "text":
+            text = str(block.get("text") or "")
+            if not text:
+                continue
+            try:
+                return json.loads(text)
+            except json.JSONDecodeError:
+                continue
+    raise RuntimeError(
+        f"Parallel MCP returned no parseable content: {str(result)[:500]}"
+    )
+
+
+def _mcp_call(
+    tool_name: str, arguments: Dict[str, Any], api_key: str | None
+) -> Dict[str, Any]:
+    """Run the MCP handshake then a single ``tools/call`` and return its payload.
+
+    initialize → (capture ``Mcp-Session-Id``) → notifications/initialized →
+    tools/call ``tool_name``. Returns the parsed tool payload dict (see
+    :func:`_mcp_payload`). A Bearer token is attached only when *api_key* is set.
+    """
+    with httpx.Client(timeout=_MCP_TIMEOUT_SECONDS) as client:
+        # 1. initialize — capture the server-assigned MCP session id.
+        init_id = str(uuid.uuid4())
+        init = client.post(
+            _MCP_SEARCH_URL,
+            headers=_mcp_headers(None, api_key),
+            json={
+                "jsonrpc": "2.0",
+                "id": init_id,
+                "method": "initialize",
+                "params": {
+                    "protocolVersion": _MCP_PROTOCOL_VERSION,
+                    "capabilities": {},
+                    "clientInfo": {
+                        "name": _MCP_CLIENT_NAME,
+                        "version": _MCP_CLIENT_VERSION,
+                    },
+                },
+            },
+        )
+        init.raise_for_status()
+        # Only echo a session id the server actually issued. Stateless
+        # Streamable-HTTP servers may omit it; inventing one and sending it on
+        # follow-up requests can get those requests rejected (the server never
+        # created that session). When absent, the Mcp-Session-Id header is simply
+        # omitted (see _mcp_headers). This is separate from the tool-arg
+        # ``session_id`` below, which is a client-minted rate-limit/grouping id.
+        mcp_session_id = init.headers.get("mcp-session-id")
+        init_env = _mcp_response_envelope(init.text, init_id)
+        # Echo the negotiated protocol version on every post-init request, per
+        # the Streamable-HTTP spec (servers may enforce it).
+        negotiated_version = (
+            (init_env.get("result") or {}).get("protocolVersion")
+            or _MCP_PROTOCOL_VERSION
+        )
+
+        # 2. notifications/initialized — required handshake ack.
+        client.post(
+            _MCP_SEARCH_URL,
+            headers=_mcp_headers(mcp_session_id, api_key, negotiated_version),
+            json={"jsonrpc": "2.0", "method": "notifications/initialized"},
+        )
+
+        # 3. tools/call.
+        call_id = str(uuid.uuid4())
+        call = client.post(
+            _MCP_SEARCH_URL,
+            headers=_mcp_headers(mcp_session_id, api_key, negotiated_version),
+            json={
+                "jsonrpc": "2.0",
+                "id": call_id,
+                "method": "tools/call",
+                "params": {"name": tool_name, "arguments": arguments},
+            },
+        )
+        call.raise_for_status()
+        return _mcp_payload(_mcp_response_envelope(call.text, call_id))
+
+
+def _mcp_web_search(query: str, limit: int, api_key: str | None) -> Dict[str, Any]:
+    """Run a ``web_search`` tool call against the hosted Search MCP.
+
+    Returns the standard provider search shape
+    (``{"success": True, "data": {"web": [...]}}``). The MCP serves a fixed
+    result count, so ``limit`` is applied client-side. The MCP requires
+    ``objective`` (REST treats it as optional), so we mirror the query.
+    """
+    payload = _mcp_call(
+        "web_search",
+        {
+            "objective": query,
+            "search_queries": [query],
+            "session_id": _new_session_id(),
+        },
+        api_key,
+    )
+
+    web_results: List[Dict[str, Any]] = []
+    for i, result in enumerate((payload.get("results") or [])[: max(limit, 1)]):
+        if not isinstance(result, dict):
+            continue
+        excerpts = result.get("excerpts") or []
+        web_results.append(
+            {
+                "url": result.get("url") or "",
+                "title": result.get("title") or "",
+                "description": " ".join(excerpts) if excerpts else "",
+                "position": i + 1,
+            }
+        )
+
+    # Credit the free tier (anonymous path only — keyed search uses REST and
+    # carries no attribution).
+    return {
+        "success": True,
+        "data": {"web": web_results},
+        "provider": "parallel",
+        "attribution": _FREE_MCP_ATTRIBUTION,
+    }
+
+
+def _mcp_web_fetch(urls: List[str], api_key: str | None) -> List[Dict[str, Any]]:
+    """Run a ``web_fetch`` tool call against the hosted Search MCP.
+
+    Returns the per-URL extract shape that
+    :func:`tools.web_tools.web_extract_tool` expects — exactly one row per input
+    URL, in request order (including duplicates). We pass ``full_content=True``
+    so the page body comes back as markdown (matching the keyed SDK path and
+    what extract callers/summarizers expect), falling back to excerpts only when
+    full content is absent. Any input the MCP didn't return is emitted as a
+    per-URL error row.
+    """
+    payload = _mcp_call(
+        "web_fetch",
+        {"urls": list(urls), "full_content": True, "session_id": _new_session_id()},
+        api_key,
+    )
+
+    # Index the response by URL, then emit one row per *input* URL in order so
+    # duplicates and positional alignment with the request list are preserved.
+    by_url: Dict[str, Dict[str, Any]] = {}
+    for item in payload.get("results") or []:
+        if isinstance(item, dict) and item.get("url"):
+            by_url.setdefault(item["url"], item)
+
+    results: List[Dict[str, Any]] = []
+    for url in urls:
+        item = by_url.get(url)
+        if item is None:
+            results.append(
+                {
+                    "url": url,
+                    "title": "",
+                    "content": "",
+                    "error": "extraction failed (no content returned)",
+                    "metadata": {"sourceURL": url},
+                }
+            )
+            continue
+        title = item.get("title") or ""
+        # Prefer the full page body; fall back to joined excerpts (mirrors the
+        # keyed SDK extract path).
+        content = item.get("full_content") or "\n\n".join(item.get("excerpts") or [])
+        results.append(
+            {
+                "url": url,
+                "title": title,
+                "content": content,
+                "raw_content": content,
+                "metadata": {"sourceURL": url, "title": title},
+            }
+        )
+
+    return results
 
 
 class ParallelWebSearchProvider(WebSearchProvider):
@@ -152,7 +504,14 @@ class ParallelWebSearchProvider(WebSearchProvider):
         return "Parallel"
 
     def is_available(self) -> bool:
-        """Return True when ``PARALLEL_API_KEY`` is set to a non-empty value."""
+        """Return True when ``PARALLEL_API_KEY`` is set.
+
+        Deliberately key-based: this gates the registry's active-provider walk
+        and the ``hermes tools`` picker (auto-selecting Parallel for a user who
+        hasn't named it), so it must not claim availability on the keyless path.
+        The keyless free-MCP path is reached independently via
+        :func:`tools.web_tools._get_backend`'s ``parallel`` terminal default.
+        """
         return bool(os.getenv("PARALLEL_API_KEY", "").strip())
 
     def supports_search(self) -> bool:
@@ -164,9 +523,11 @@ class ParallelWebSearchProvider(WebSearchProvider):
     def search(self, query: str, limit: int = 5) -> Dict[str, Any]:
         """Execute a Parallel search (sync).
 
-        Uses the ``beta.search`` endpoint with the configured mode
-        (``PARALLEL_SEARCH_MODE`` env var, default "agentic"). Limit is
-        capped at 20 server-side.
+        With ``PARALLEL_API_KEY`` set, uses the v1 ``search`` REST endpoint with
+        the configured mode (``PARALLEL_SEARCH_MODE`` env var, default
+        "advanced"; limit requested via advanced_settings.max_results, capped at
+        20). Without a key, falls back to the free hosted Search MCP so search
+        still works with zero setup.
         """
         try:
             from tools.interrupt import is_interrupted
@@ -174,19 +535,31 @@ class ParallelWebSearchProvider(WebSearchProvider):
             if is_interrupted():
                 return {"success": False, "error": "Interrupted"}
 
+            api_key = os.getenv("PARALLEL_API_KEY", "").strip()
+            if not api_key:
+                logger.info(
+                    "Parallel search (free MCP): '%s' (limit=%d)", query, limit
+                )
+                return _mcp_web_search(query, limit, api_key=None)
+
             mode = _resolve_search_mode()
             logger.info(
-                "Parallel search: '%s' (mode=%s, limit=%d)", query, mode, limit
+                "Parallel search (v1 REST): '%s' (mode=%s, limit=%d)",
+                query, mode, limit,
             )
-            response = _get_sync_client().beta.search(
+            # v1 Search API. Request the caller's limit via max_results (capped
+            # at 20) so we don't rely on the API default — the slice below can
+            # only trim, not ask for more.
+            response = _get_sync_client().search(
                 search_queries=[query],
                 objective=query,
                 mode=mode,
-                max_results=min(limit, 20),
+                session_id=_new_session_id(),
+                advanced_settings={"max_results": min(max(limit, 1), 20)},
             )
 
             web_results = []
-            for i, result in enumerate(response.results or []):
+            for i, result in enumerate((response.results or [])[: max(limit, 1)]):
                 excerpts = result.excerpts or []
                 web_results.append(
                     {
@@ -197,6 +570,8 @@ class ParallelWebSearchProvider(WebSearchProvider):
                     }
                 )
 
+            # Paid/REST path: no attribution and no "[Parallel]" label — the
+            # branding is specifically for the free Search MCP tier.
             return {"success": True, "data": {"web": web_results}}
         except ValueError as exc:
             return {"success": False, "error": str(exc)}
@@ -212,7 +587,12 @@ class ParallelWebSearchProvider(WebSearchProvider):
     async def extract(
         self, urls: List[str], **kwargs: Any
     ) -> List[Dict[str, Any]]:
-        """Extract content from one or more URLs via the async SDK.
+        """Extract content from one or more URLs.
+
+        With ``PARALLEL_API_KEY`` set, uses the async SDK's v1 ``extract`` for
+        full page content. Without a key, falls back to the free hosted Search
+        MCP's ``web_fetch`` tool so extraction works with zero setup, mirroring
+        the keyless search path.
 
         Returns the legacy list-of-results shape that
         :func:`tools.web_tools.web_extract_tool` expects: one entry per
@@ -227,10 +607,21 @@ class ParallelWebSearchProvider(WebSearchProvider):
                     {"url": u, "error": "Interrupted", "title": ""} for u in urls
                 ]
 
-            logger.info("Parallel extract: %d URL(s)", len(urls))
-            response = await _get_async_client().beta.extract(
+            api_key = os.getenv("PARALLEL_API_KEY", "").strip()
+            if not api_key:
+                logger.info(
+                    "Parallel extract (free MCP web_fetch): %d URL(s)", len(urls)
+                )
+                # _mcp_web_fetch is sync httpx; run off the event loop.
+                return await asyncio.to_thread(_mcp_web_fetch, list(urls), None)
+
+            logger.info("Parallel extract (v1 REST): %d URL(s)", len(urls))
+            # v1 Extract API (client.extract, /v1/extract); full_content is set
+            # via advanced_settings.
+            response = await _get_async_client().extract(
                 urls=urls,
-                full_content=True,
+                advanced_settings={"full_content": True},
+                session_id=_new_session_id(),
             )
 
             results: List[Dict[str, Any]] = []
@@ -251,13 +642,20 @@ class ParallelWebSearchProvider(WebSearchProvider):
                 )
 
             for error in response.errors or []:
+                err_url = getattr(error, "url", "") or ""
+                err_msg = (
+                    getattr(error, "message", None)
+                    or getattr(error, "content", None)
+                    or getattr(error, "error_type", None)
+                    or "extraction failed"
+                )
                 results.append(
                     {
-                        "url": error.url or "",
+                        "url": err_url,
                         "title": "",
                         "content": "",
-                        "error": error.content or error.error_type or "extraction failed",
-                        "metadata": {"sourceURL": error.url or ""},
+                        "error": err_msg,
+                        "metadata": {"sourceURL": err_url},
                     }
                 )
 
@@ -279,12 +677,16 @@ class ParallelWebSearchProvider(WebSearchProvider):
     def get_setup_schema(self) -> Dict[str, Any]:
         return {
             "name": "Parallel",
-            "badge": "paid",
-            "tag": "Objective-tuned search + parallel page extraction.",
+            "badge": "free",
+            "tag": (
+                "Free web search + extraction via Parallel's hosted Search MCP "
+                "— no key needed. Add PARALLEL_API_KEY for the v1 REST Search "
+                "API (richer modes, higher limits)."
+            ),
             "env_vars": [
                 {
                     "key": "PARALLEL_API_KEY",
-                    "prompt": "Parallel API key",
+                    "prompt": "Parallel API key (optional — unlocks the v1 REST Search API)",
                     "url": "https://parallel.ai",
                 },
             ],
diff --git a/pyproject.toml b/pyproject.toml
index b2a486aefd0f..e5bf882d87a4 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -122,7 +122,7 @@ anthropic = ["anthropic==0.87.0"]  # CVE-2026-34450, CVE-2026-34452
 # search provider (configured via `hermes tools` or config.yaml).
 exa = ["exa-py==2.10.2"]
 firecrawl = ["firecrawl-py==4.17.0"]
-parallel-web = ["parallel-web==0.4.2"]
+parallel-web = ["parallel-web==0.6.0"]
 # Image generation backends
 fal = ["fal-client==0.13.1"]
 # Edge TTS — default TTS provider but still optional (users can pick
diff --git a/tests/agent/test_display.py b/tests/agent/test_display.py
index 994aae286484..0203e38b3cd7 100644
--- a/tests/agent/test_display.py
+++ b/tests/agent/test_display.py
@@ -12,6 +12,7 @@ from agent.display import (
     set_tool_preview_max_len,
     _render_inline_unified_diff,
     _summarize_rendered_diff_sections,
+    _used_free_parallel,
     render_edit_diff_with_delta,
 )
 
@@ -171,6 +172,46 @@ class TestCuteToolMessagePreviewLength:
         assert "[error]" not in line
 
 
+class TestWebProviderLabel:
+    """The free-path "Parallel search"/"Parallel fetch" verb labeling."""
+
+    def test_free_search_verb_is_parallel(self):
+        result = json.dumps({"success": True, "data": {"web": []}, "provider": "parallel"})
+        line = get_cute_tool_message("web_search", {"query": "hello"}, 0.1, result=result)
+        assert "Parallel search" in line
+        assert "hello" in line
+
+    def test_paid_search_verb_is_plain(self):
+        result = json.dumps({"success": True, "data": {"web": [{"url": "u"}]}})
+        line = get_cute_tool_message("web_search", {"query": "hi"}, 0.1, result=result)
+        assert "Parallel" not in line
+        assert "search" in line
+
+    def test_missing_result_verb_is_plain(self):
+        line = get_cute_tool_message("web_search", {"query": "hello"}, 0.1)
+        assert "Parallel" not in line
+        assert "search" in line
+
+    def test_helper_is_parallel_free_specific(self):
+        # Only Parallel's free MCP path marks results; nothing else does.
+        assert _used_free_parallel(json.dumps({"provider": "parallel"})) is True
+        assert _used_free_parallel(json.dumps({"provider": "exa"})) is False
+        assert _used_free_parallel(json.dumps({"provider": "firecrawl"})) is False
+        assert _used_free_parallel(json.dumps({"success": True, "data": {}})) is False
+        assert _used_free_parallel('not json') is False
+        assert _used_free_parallel(None) is False
+
+    def test_free_extract_verb_is_parallel(self):
+        result = json.dumps({"results": [{"url": "u", "content": "x"}], "provider": "parallel"})
+        line = get_cute_tool_message("web_extract", {"urls": ["https://a.test"]}, 0.1, result=result)
+        assert "Parallel fetch" in line
+
+    def test_paid_extract_verb_is_plain(self):
+        result = json.dumps({"results": [{"url": "u", "content": "x"}]})
+        line = get_cute_tool_message("web_extract", {"urls": ["https://a.test"]}, 0.1, result=result)
+        assert "Parallel" not in line
+
+
 class TestEditDiffPreview:
     def test_extract_edit_diff_for_patch(self):
         diff = extract_edit_diff("patch", '{"success": true, "diff": "--- a/x\\n+++ b/x\\n"}')
diff --git a/tests/hermes_cli/test_tools_config.py b/tests/hermes_cli/test_tools_config.py
index 5b24d2b6ebd2..3a68c9758973 100644
--- a/tests/hermes_cli/test_tools_config.py
+++ b/tests/hermes_cli/test_tools_config.py
@@ -975,6 +975,19 @@ def test_toolset_has_keys_treats_no_key_providers_as_configured():
     assert _toolset_has_keys("computer_use", config) is True
 
 
+def test_web_no_prompt_when_usable_keyless():
+    """Fresh install: web works via the free Parallel MCP, so enabling the web
+    toolset should not force provider setup."""
+    with patch("tools.web_tools.check_web_api_key", return_value=True):
+        assert _toolset_needs_configuration_prompt("web", {}) is False
+
+
+def test_web_no_prompt_when_extract_backend_is_extract_capable():
+    with patch("tools.web_tools.check_web_api_key", return_value=True):
+        cfg = {"web": {"extract_backend": "parallel"}}
+        assert _toolset_needs_configuration_prompt("web", cfg) is False
+
+
 def test_computer_use_needs_configuration_when_cua_driver_post_setup_pending():
     """No-key providers can still need setup when their post_setup is unsatisfied.
 
diff --git a/tests/plugins/web/test_parallel_keyless_mcp.py b/tests/plugins/web/test_parallel_keyless_mcp.py
new file mode 100644
index 000000000000..49975c47f2f0
--- /dev/null
+++ b/tests/plugins/web/test_parallel_keyless_mcp.py
@@ -0,0 +1,382 @@
+"""Keyless Parallel search via the free hosted Search MCP.
+
+Covers the transport added in ``plugins/web/parallel/provider.py`` that lets
+``web_search`` work with no ``PARALLEL_API_KEY``:
+
+- ``_mcp_headers``  — Bearer attached only when a key is held
+- ``_decode_mcp_envelope`` — plain-JSON and SSE (``data:``) response bodies
+- ``_mcp_payload`` — structuredContent preferred, text-block JSON fallback, errors
+- ``_mcp_web_search`` — full handshake (mocked transport) → standard search shape
+- ``ParallelWebSearchProvider.search`` — keyless path routes to the MCP
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from unittest.mock import patch
+
+import pytest
+
+import plugins.web.parallel.provider as pp
+
+
+# ─── _mcp_headers ──────────────────────────────────────────────────────────
+
+class TestMcpHeaders:
+    def test_anonymous_has_no_authorization(self):
+        h = pp._mcp_headers(session_id=None, api_key=None)
+        assert "Authorization" not in h
+        assert h["Accept"] == "application/json, text/event-stream"
+        assert "Mcp-Session-Id" not in h
+
+    def test_identifies_hermes_via_user_agent(self):
+        # Free-tier traffic is attributable at the HTTP layer (not just via the
+        # JSON-RPC clientInfo payload), on both the anonymous and keyed paths.
+        assert pp._mcp_headers(session_id=None, api_key=None)["User-Agent"].startswith(
+            "hermes-agent/"
+        )
+        assert pp._mcp_headers(session_id="sid", api_key="pk-live")["User-Agent"].startswith(
+            "hermes-agent/"
+        )
+
+    def test_session_id_and_bearer_when_present(self):
+        h = pp._mcp_headers(session_id="sid-123", api_key="pk-live")
+        assert h["Mcp-Session-Id"] == "sid-123"
+        assert h["Authorization"] == "Bearer pk-live"
+
+
+# ─── SSE / JSON-RPC parsing ──────────────────────────────────────────────────
+
+class TestMcpResponseParsing:
+    def test_plain_json_matched_by_id(self):
+        body = '{"jsonrpc":"2.0","id":"abc","result":{"ok":true}}'
+        assert pp._mcp_response_envelope(body, "abc")["result"]["ok"] is True
+
+    def test_sse_selects_response_for_request_id_skipping_notifications(self):
+        # A progress notification (no id) precedes the real result; an unrelated
+        # response id is also present. We must pick the one matching our id.
+        body = (
+            'event: message\ndata: {"jsonrpc":"2.0","method":"notifications/progress","params":{"p":1}}\n\n'
+            'event: message\ndata: {"jsonrpc":"2.0","id":"other","result":{"ok":false}}\n\n'
+            'event: message\ndata: {"jsonrpc":"2.0","id":"req-1","result":{"ok":true}}\n\n'
+        )
+        env = pp._mcp_response_envelope(body, "req-1")
+        assert env["result"]["ok"] is True
+
+    def test_sse_multiline_data_concatenated(self):
+        body = 'data: {"jsonrpc":"2.0","id":"x",\ndata: "result":{"n":42}}\n\n'
+        assert pp._mcp_response_envelope(body, "x")["result"]["n"] == 42
+
+    def test_falls_back_to_last_result_when_id_absent(self):
+        body = '{"jsonrpc":"2.0","id":"server-chose","result":{"ok":true}}'
+        # request id doesn't match, but there's a single result → use it
+        assert pp._mcp_response_envelope(body, "mismatch")["result"]["ok"] is True
+
+    def test_empty_body(self):
+        assert pp._mcp_response_envelope("", "x") == {}
+        assert pp._mcp_response_envelope("   ", "x") == {}
+
+    def test_batched_json_array_flattened(self):
+        # Streamable HTTP may batch messages into a JSON array.
+        body = ('[{"jsonrpc":"2.0","method":"notifications/progress"},'
+                '{"jsonrpc":"2.0","id":"req-9","result":{"ok":true}}]')
+        assert pp._mcp_response_envelope(body, "req-9")["result"]["ok"] is True
+
+    def test_batched_sse_data_array_flattened(self):
+        body = 'data: [{"jsonrpc":"2.0","id":"a","result":{"n":1}}]\n\n'
+        assert pp._mcp_response_envelope(body, "a")["result"]["n"] == 1
+
+
+# ─── _mcp_payload ────────────────────────────────────────────────────────────
+
+class TestMcpPayload:
+    def test_prefers_structured_content(self):
+        env = {"result": {"structuredContent": {"results": [{"url": "u"}]},
+                          "content": [{"type": "text", "text": "ignored"}]}}
+        assert pp._mcp_payload(env) == {"results": [{"url": "u"}]}
+
+    def test_parses_text_block_json(self):
+        inner = {"search_id": "s1", "results": [{"url": "u", "title": "t"}]}
+        env = {"result": {"content": [{"type": "text", "text": json.dumps(inner)}]}}
+        assert pp._mcp_payload(env)["search_id"] == "s1"
+
+    def test_raises_on_jsonrpc_error(self):
+        with pytest.raises(RuntimeError, match="Parallel MCP error"):
+            pp._mcp_payload({"error": {"code": -32000, "message": "boom"}})
+
+    def test_raises_on_tool_iserror(self):
+        with pytest.raises(RuntimeError, match="Parallel MCP tool error"):
+            pp._mcp_payload({"result": {"isError": True, "content": []}})
+
+
+# ─── _mcp_web_search (mocked transport) ──────────────────────────────────────
+
+class _FakeResponse:
+    def __init__(self, *, text="", headers=None):
+        self.text = text
+        self.headers = headers or {}
+
+    def raise_for_status(self):
+        return None
+
+
+class _FakeClient:
+    """Stands in for httpx.Client: replays init → ack → tools/call."""
+
+    def __init__(self, search_payload, init_session_id="server-sid"):
+        self._search_payload = search_payload
+        self._init_session_id = init_session_id
+        self.calls = []
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *exc):
+        return False
+
+    def post(self, url, headers=None, json=None):
+        self.calls.append({"headers": headers, "json": json})
+        req = json or {}
+        method = req.get("method")
+        req_id = req.get("id")
+        if method == "initialize":
+            # Echo the request id, as the real server does.
+            return _FakeResponse(
+                text=json_dumps({"jsonrpc": "2.0", "id": req_id,
+                                 "result": {"protocolVersion": "2099-01-01"}}),
+                headers=(
+                    {"mcp-session-id": self._init_session_id}
+                    if self._init_session_id is not None
+                    else {}
+                ),
+            )
+        if method == "notifications/initialized":
+            return _FakeResponse(text="")
+        # tools/call
+        envelope = {"jsonrpc": "2.0", "id": req_id, "result": {
+            "content": [{"type": "text", "text": json_dumps(self._search_payload)}],
+        }}
+        return _FakeResponse(text=json_dumps(envelope))
+
+
+def json_dumps(obj):
+    return json.dumps(obj)
+
+
+class TestMcpWebSearch:
+    def _payload(self, n):
+        return {"search_id": "s", "results": [
+            {"url": f"https://ex/{i}", "title": f"t{i}",
+             "excerpts": [f"a{i}", f"b{i}"]}
+            for i in range(n)
+        ]}
+
+    def test_returns_standard_shape_and_handshake(self):
+        fake = _FakeClient(self._payload(3))
+        with patch.object(pp.httpx, "Client", return_value=fake):
+            out = pp._mcp_web_search("hello", limit=5, api_key=None)
+
+        assert out["success"] is True
+        # Free-tier results credit Parallel.
+        assert "Parallel" in out["attribution"]
+        web = out["data"]["web"]
+        assert [r["position"] for r in web] == [1, 2, 3]
+        assert web[0]["url"] == "https://ex/0"
+        assert web[0]["description"] == "a0 b0"  # excerpts joined
+        # handshake order
+        methods = [c["json"].get("method") for c in fake.calls]
+        assert methods == ["initialize", "notifications/initialized", "tools/call"]
+        # session id from the initialize response header is reused
+        assert fake.calls[-1]["headers"]["Mcp-Session-Id"] == "server-sid"
+
+    def test_stateless_server_no_session_header_not_invented(self):
+        # A stateless Streamable-HTTP server may omit mcp-session-id on
+        # initialize; we must NOT invent one (sending an unissued session id can
+        # get follow-up requests rejected). The follow-ups carry no header.
+        fake = _FakeClient(self._payload(1), init_session_id=None)
+        with patch.object(pp.httpx, "Client", return_value=fake):
+            out = pp._mcp_web_search("hello", limit=5, api_key=None)
+        assert out["success"] is True
+        follow_ups = [c for c in fake.calls if c["json"].get("method") != "initialize"]
+        assert follow_ups, "expected notifications/initialized + tools/call"
+        assert all("Mcp-Session-Id" not in c["headers"] for c in follow_ups)
+        # anonymous → no Authorization on any call
+        assert all("Authorization" not in c["headers"] for c in fake.calls)
+        # tools/call mirrors query into objective + search_queries
+        args = fake.calls[-1]["json"]["params"]["arguments"]
+        assert args["objective"] == "hello"
+        assert args["search_queries"] == ["hello"]
+
+    def test_limit_is_applied_client_side(self):
+        fake = _FakeClient(self._payload(10))
+        with patch.object(pp.httpx, "Client", return_value=fake):
+            out = pp._mcp_web_search("q", limit=2, api_key=None)
+        assert len(out["data"]["web"]) == 2
+
+    def test_bearer_attached_when_key_present(self):
+        fake = _FakeClient(self._payload(1))
+        with patch.object(pp.httpx, "Client", return_value=fake):
+            pp._mcp_web_search("q", limit=1, api_key="pk-live")
+        assert all(c["headers"]["Authorization"] == "Bearer pk-live" for c in fake.calls)
+
+    def test_negotiated_protocol_version_echoed_post_init(self):
+        fake = _FakeClient(self._payload(1))
+        with patch.object(pp.httpx, "Client", return_value=fake):
+            pp._mcp_web_search("q", limit=1, api_key=None)
+        # initialize request doesn't carry the (not-yet-negotiated) version...
+        assert "MCP-Protocol-Version" not in fake.calls[0]["headers"]
+        # ...but notifications/initialized and tools/call echo the negotiated one.
+        assert fake.calls[1]["headers"]["MCP-Protocol-Version"] == "2099-01-01"
+        assert fake.calls[-1]["headers"]["MCP-Protocol-Version"] == "2099-01-01"
+
+
+# ─── provider.search keyless routing ─────────────────────────────────────────
+
+class TestProviderKeylessSearch:
+    def test_search_without_key_uses_mcp(self, monkeypatch):
+        monkeypatch.delenv("PARALLEL_API_KEY", raising=False)
+        captured = {}
+
+        def _fake(query, limit, api_key):
+            captured.update(query=query, limit=limit, api_key=api_key)
+            return {"success": True, "data": {"web": []}}
+
+        monkeypatch.setattr(pp, "_mcp_web_search", _fake)
+        out = pp.ParallelWebSearchProvider().search("kittens", limit=4)
+        assert out["success"] is True
+        assert captured == {"query": "kittens", "limit": 4, "api_key": None}
+
+    def test_is_available_reflects_key(self, monkeypatch):
+        # is_available() gates the registry's active-provider walk + picker, so
+        # it's key-based (keyless dispatch is handled by _get_backend, not this).
+        monkeypatch.delenv("PARALLEL_API_KEY", raising=False)
+        assert pp.ParallelWebSearchProvider().is_available() is False
+        monkeypatch.setenv("PARALLEL_API_KEY", "k")
+        assert pp.ParallelWebSearchProvider().is_available() is True
+
+
+# ─── web_fetch (keyless extract) ─────────────────────────────────────────────
+
+class TestMcpWebFetch:
+    def _payload(self, urls):
+        return {"extract_id": "e1", "results": [
+            {"url": u, "title": f"T{i}", "publish_date": None,
+             "excerpts": [f"chunk-a-{i}", f"chunk-b-{i}"]}
+            for i, u in enumerate(urls)
+        ]}
+
+    def test_maps_to_extract_shape(self):
+        urls = ["https://a.test", "https://b.test"]
+        fake = _FakeClient(self._payload(urls))
+        with patch.object(pp.httpx, "Client", return_value=fake):
+            out = pp._mcp_web_fetch(urls, api_key=None)
+        assert [r["url"] for r in out] == urls
+        assert out[0]["content"] == "chunk-a-0\n\nchunk-b-0"
+        assert out[0]["raw_content"] == out[0]["content"]
+        assert out[0]["metadata"] == {"sourceURL": "https://a.test", "title": "T0"}
+        # tools/call targeted web_fetch, requesting full page bodies.
+        args = fake.calls[-1]["json"]["params"]
+        assert args["name"] == "web_fetch"
+        assert args["arguments"]["urls"] == urls
+        assert args["arguments"]["full_content"] is True
+        assert args["arguments"]["session_id"].startswith("hermes-agent-")
+
+    def test_prefers_full_content_over_excerpts(self):
+        payload = {"results": [
+            {"url": "https://a.test", "title": "T",
+             "excerpts": ["snippet"], "full_content": "the entire page body"},
+        ]}
+        fake = _FakeClient(payload)
+        with patch.object(pp.httpx, "Client", return_value=fake):
+            out = pp._mcp_web_fetch(["https://a.test"], api_key=None)
+        assert out[0]["content"] == "the entire page body"
+
+    def test_missing_url_becomes_error_entry(self):
+        # Server returns only one of the two requested URLs.
+        fake = _FakeClient(self._payload(["https://a.test"]))
+        with patch.object(pp.httpx, "Client", return_value=fake):
+            out = pp._mcp_web_fetch(["https://a.test", "https://missing.test"], api_key=None)
+        assert len(out) == 2
+        missing = [r for r in out if r["url"] == "https://missing.test"][0]
+        assert "error" in missing
+        assert missing["content"] == ""
+
+    def test_preserves_order_and_duplicate_inputs(self):
+        # MCP returns each unique URL once; output must still be one row per
+        # input, in order, including the duplicate.
+        fake = _FakeClient(self._payload(["https://a.test", "https://b.test"]))
+        urls = ["https://b.test", "https://a.test", "https://b.test"]
+        with patch.object(pp.httpx, "Client", return_value=fake):
+            out = pp._mcp_web_fetch(urls, api_key=None)
+        assert [r["url"] for r in out] == urls  # one row per input, in order
+        assert all("error" not in r for r in out)  # all three resolved
+
+    def test_extract_without_key_uses_web_fetch(self, monkeypatch):
+        monkeypatch.delenv("PARALLEL_API_KEY", raising=False)
+        captured = {}
+
+        def _fake(urls, api_key):
+            captured.update(urls=list(urls), api_key=api_key)
+            return [{"url": urls[0], "title": "", "content": "x",
+                     "raw_content": "x", "metadata": {}}]
+
+        monkeypatch.setattr(pp, "_mcp_web_fetch", _fake)
+        out = asyncio.run(pp.ParallelWebSearchProvider().extract(["https://x.test"]))
+        assert out[0]["content"] == "x"
+        assert captured == {"urls": ["https://x.test"], "api_key": None}
+
+
+# ─── keyed v1 REST search ────────────────────────────────────────────────────
+
+class TestKeyedV1Search:
+    def test_passes_max_results_and_omits_branding(self, monkeypatch):
+        monkeypatch.setenv("PARALLEL_API_KEY", "pk-live")
+        monkeypatch.delenv("PARALLEL_SEARCH_MODE", raising=False)
+        captured = {}
+
+        class _Res:
+            def __init__(self, url):
+                self.url, self.title, self.excerpts = url, "T", ["x"]
+
+        class _Resp:
+            results = [_Res(f"https://r/{i}") for i in range(10)]
+
+        class _Client:
+            def search(self, **kw):
+                captured.update(kw)
+                return _Resp()
+
+        monkeypatch.setattr(pp, "_get_sync_client", lambda: _Client())
+        out = pp.ParallelWebSearchProvider().search("q", limit=7)
+
+        assert out["success"] is True
+        # honors the caller's limit via advanced_settings.max_results
+        assert captured["advanced_settings"] == {"max_results": 7}
+        assert captured["mode"] == "advanced"            # v1 default
+        assert captured["session_id"].startswith("hermes-agent-")  # per-call id
+        assert len(out["data"]["web"]) == 7              # client-side slice
+        # paid path: no free-tier attribution, no [Parallel] label signal
+        assert "attribution" not in out
+        assert "provider" not in out
+
+
+# ─── v1 search mode mapping ──────────────────────────────────────────────────
+
+class TestResolveSearchMode:
+    @pytest.mark.parametrize("env,expected", [
+        (None, "advanced"),        # default
+        ("advanced", "advanced"),
+        ("basic", "basic"),
+        ("fast", "basic"),         # legacy → basic
+        ("one-shot", "basic"),     # legacy → basic
+        ("agentic", "advanced"),   # legacy → advanced
+        ("garbage", "advanced"),   # invalid → default
+        ("BASIC", "basic"),        # case-insensitive
+    ])
+    def test_mode_mapping(self, monkeypatch, env, expected):
+        if env is None:
+            monkeypatch.delenv("PARALLEL_SEARCH_MODE", raising=False)
+        else:
+            monkeypatch.setenv("PARALLEL_SEARCH_MODE", env)
+        assert pp._resolve_search_mode() == expected
diff --git a/tests/plugins/web/test_web_search_provider_plugins.py b/tests/plugins/web/test_web_search_provider_plugins.py
index 2177d875c4b1..2d74b2a18137 100644
--- a/tests/plugins/web/test_web_search_provider_plugins.py
+++ b/tests/plugins/web/test_web_search_provider_plugins.py
@@ -193,11 +193,16 @@ class TestIsAvailable:
         assert p.is_available() is True
 
     def test_parallel_requires_api_key(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """is_available() is key-based — it gates the registry's active-provider
+        walk/picker. (Keyless search/extract still work via the free MCP through
+        _get_backend's terminal default, independent of this flag.)
+        """
         _ensure_plugins_loaded()
         from agent.web_search_registry import get_provider
 
         p = get_provider("parallel")
         assert p is not None
+        monkeypatch.delenv("PARALLEL_API_KEY", raising=False)
         assert p.is_available() is False
         monkeypatch.setenv("PARALLEL_API_KEY", "real")
         assert p.is_available() is True
@@ -422,17 +427,33 @@ class TestErrorResponseShapes:
         assert result.get("success") is False
         assert "error" in result
 
-    def test_parallel_extract_returns_per_url_errors_when_unconfigured(self) -> None:
+    def test_parallel_extract_keyless_uses_mcp_web_fetch(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """Without a key, extract routes to the free MCP web_fetch tool rather
+        than erroring. The MCP transport is mocked so the test stays offline."""
         _ensure_plugins_loaded()
         from agent.web_search_registry import get_provider
+        import plugins.web.parallel.provider as parallel_provider
+
+        monkeypatch.delenv("PARALLEL_API_KEY", raising=False)
+        captured = {}
+
+        def _fake_fetch(urls, api_key):
+            captured["urls"] = list(urls)
+            captured["api_key"] = api_key
+            return [{"url": urls[0], "title": "Example", "content": "body",
+                     "raw_content": "body", "metadata": {"sourceURL": urls[0]}}]
+
+        monkeypatch.setattr(parallel_provider, "_mcp_web_fetch", _fake_fetch)
 
         p = get_provider("parallel")
         assert p is not None
         result = asyncio.run(p.extract(["https://example.com"]))
         assert isinstance(result, list)
-        assert len(result) == 1
-        assert "error" in result[0]
         assert result[0]["url"] == "https://example.com"
+        assert result[0]["content"] == "body"
+        assert captured == {"urls": ["https://example.com"], "api_key": None}
 
     def test_firecrawl_extract_returns_per_url_errors_when_unconfigured(self) -> None:
         _ensure_plugins_loaded()
diff --git a/tests/tools/test_web_providers.py b/tests/tools/test_web_providers.py
index bd3cce8754aa..230f909b5fea 100644
--- a/tests/tools/test_web_providers.py
+++ b/tests/tools/test_web_providers.py
@@ -167,6 +167,21 @@ class TestPerCapabilityBackendSelection:
         monkeypatch.setenv("TAVILY_API_KEY", "test-key")
         assert web_tools._get_search_backend() == "tavily"
 
+    def test_explicit_extract_backend_honored_when_unavailable(self, monkeypatch):
+        """An explicit per-capability backend is honored even with no creds, so
+        its setup error surfaces instead of silently rerouting to the keyless
+        Parallel default (which would send user URLs to a different provider)."""
+        from tools import web_tools
+
+        monkeypatch.setattr(web_tools, "_load_web_config", lambda: {
+            "extract_backend": "firecrawl",
+        })
+        for key in ("FIRECRAWL_API_KEY", "FIRECRAWL_API_URL", "FIRECRAWL_GATEWAY_URL"):
+            monkeypatch.delenv(key, raising=False)
+        monkeypatch.setattr(web_tools, "_is_tool_gateway_ready", lambda: False, raising=False)
+        # Resolves to firecrawl (not parallel) despite firecrawl being unavailable.
+        assert web_tools._get_extract_backend() == "firecrawl"
+
     def test_falls_back_to_generic_backend_when_extract_backend_empty(self, monkeypatch):
         from tools import web_tools
 
@@ -177,7 +192,7 @@ class TestPerCapabilityBackendSelection:
         monkeypatch.setenv("PARALLEL_API_KEY", "test-key")
         assert web_tools._get_extract_backend() == "parallel"
 
-    def test_search_backend_ignored_when_not_available(self, monkeypatch):
+    def test_explicit_search_backend_honored_when_unavailable(self, monkeypatch):
         from tools import web_tools
 
         monkeypatch.setattr(web_tools, "_load_web_config", lambda: {
@@ -186,8 +201,10 @@ class TestPerCapabilityBackendSelection:
         })
         monkeypatch.delenv("EXA_API_KEY", raising=False)
         monkeypatch.setenv("FIRECRAWL_API_KEY", "fc-key")
-        # Should fall back to firecrawl since exa isn't configured
-        assert web_tools._get_search_backend() == "firecrawl"
+        # The explicit per-capability choice (exa) is honored even though it's
+        # unavailable, so its setup error surfaces — we don't silently reroute
+        # to the shared backend (or the keyless Parallel default).
+        assert web_tools._get_search_backend() == "exa"
 
     def test_fully_backward_compatible_with_web_backend_only(self, monkeypatch):
         from tools import web_tools
@@ -291,25 +308,55 @@ class TestUnconfiguredErrorEnvelopeParity:
         ):
             monkeypatch.delenv(k, raising=False)
 
-    def test_unconfigured_search_emits_top_level_error(self, monkeypatch):
-        """``web_search_tool`` with no creds returns ``{"error": "Error searching web: ..."}``
-        — matching main's ``tool_error()`` envelope, not a per-result shape.
+    def test_extract_empty_urls_does_not_raise(self, monkeypatch):
+        """Regression: empty (or fully SSRF-blocked) URL sets skip the dispatch
+        branch; the free-Parallel flag must still be initialized so the tool
+        returns an error envelope instead of UnboundLocalError."""
+        import asyncio
+        from tools import web_tools
+        self._clear_web_creds(monkeypatch)
+        monkeypatch.setattr(web_tools, "_load_web_config", lambda: {})
+        out = asyncio.run(web_tools.web_extract_tool([], "markdown"))
+        # The key assertion is that it returns a normal error envelope (a
+        # string) rather than raising UnboundLocalError.
+        assert isinstance(out, str)
+        result = json.loads(out)
+        assert "error" in result
+
+    def test_unconfigured_search_falls_back_to_free_parallel(self, monkeypatch):
+        """``web_search_tool`` with no creds routes to Parallel's free Search
+        MCP rather than erroring. The MCP transport is mocked so the test
+        stays offline; we assert dispatch landed on parallel and returned the
+        standard search envelope.
         """
         from tools import web_tools
+        import plugins.web.parallel.provider as parallel_provider
 
         self._clear_web_creds(monkeypatch)
-        # Reset firecrawl client cache so the unconfigured state is re-evaluated
         monkeypatch.setattr(web_tools, "_firecrawl_client", None, raising=False)
         monkeypatch.setattr(web_tools, "_firecrawl_client_config", None, raising=False)
         monkeypatch.setattr(web_tools, "_load_web_config", lambda: {})
 
+        captured = {}
+
+        def _fake_mcp(query, limit, api_key):
+            captured["query"] = query
+            captured["api_key"] = api_key
+            return {
+                "success": True,
+                "data": {"web": [
+                    {"url": "https://example.com", "title": "Example",
+                     "description": "hit", "position": 1},
+                ]},
+            }
+
+        monkeypatch.setattr(parallel_provider, "_mcp_web_search", _fake_mcp)
+
         result = json.loads(web_tools.web_search_tool("hello world", limit=3))
-        assert "error" in result, f"expected top-level 'error' key, got {result}"
-        # ``Error searching web:`` prefix comes from web_tools' top-level except handler
-        assert "Error searching web:" in result["error"]
-        assert "FIRECRAWL_API_KEY" in result["error"]
-        # No per-result burying
-        assert "results" not in result
+        assert result.get("success") is True, f"expected success, got {result}"
+        assert result["data"]["web"][0]["url"] == "https://example.com"
+        # Keyless path: dispatched to parallel with no Bearer token.
+        assert captured == {"query": "hello world", "api_key": None}
 
 
 class TestDispatchersTriggerPluginDiscovery:
diff --git a/tests/tools/test_web_providers_ddgs.py b/tests/tools/test_web_providers_ddgs.py
index 283a25f0a1be..1050a4e554a5 100644
--- a/tests/tools/test_web_providers_ddgs.py
+++ b/tests/tools/test_web_providers_ddgs.py
@@ -190,7 +190,11 @@ class TestDDGSBackendWiring:
         monkeypatch.setattr(web_tools, "_ddgs_package_importable", lambda: True)
         assert web_tools._get_backend() == "exa"
 
-    def test_auto_detect_picks_ddgs_as_last_resort(self, monkeypatch):
+    def test_auto_detect_prefers_keyless_parallel_over_ddgs(self, monkeypatch):
+        # With no credentials, keyless Parallel is the auto-detect default even
+        # when the ddgs package is installed — ddgs is search-only (can't
+        # extract), so Parallel is preferred so both search and extract work.
+        # ddgs remains reachable via an explicit web.backend=ddgs.
         from tools import web_tools
         monkeypatch.setattr(web_tools, "_load_web_config", lambda: {})
         for key in ("FIRECRAWL_API_KEY", "FIRECRAWL_API_URL", "PARALLEL_API_KEY",
@@ -198,7 +202,7 @@ class TestDDGSBackendWiring:
             monkeypatch.delenv(key, raising=False)
         monkeypatch.setattr(web_tools, "_is_tool_gateway_ready", lambda: False)
         monkeypatch.setattr(web_tools, "_ddgs_package_importable", lambda: True)
-        assert web_tools._get_backend() == "ddgs"
+        assert web_tools._get_backend() == "parallel"
 
     def test_check_web_api_key_true_when_ddgs_configured(self, monkeypatch):
         from tools import web_tools
diff --git a/tests/tools/test_web_providers_searxng.py b/tests/tools/test_web_providers_searxng.py
index e093532bf377..2877d56b868c 100644
--- a/tests/tools/test_web_providers_searxng.py
+++ b/tests/tools/test_web_providers_searxng.py
@@ -313,7 +313,9 @@ class TestCheckWebApiKey:
         )
         assert web_tools.check_web_api_key() is True
 
-    def test_no_credentials_fails(self, monkeypatch):
+    def test_no_credentials_usable_via_free_parallel(self, monkeypatch):
+        """No credentials → check_web_api_key True: the keyless Parallel free MCP
+        services calls, so web is usable out of the box."""
         from tools import web_tools
         monkeypatch.setattr(web_tools, "_load_web_config", lambda: {})
         monkeypatch.delenv("FIRECRAWL_API_KEY", raising=False)
@@ -324,7 +326,8 @@ class TestCheckWebApiKey:
         monkeypatch.delenv("SEARXNG_URL", raising=False)
         monkeypatch.setattr(web_tools, "_is_tool_gateway_ready", lambda: False)
         monkeypatch.setattr(web_tools, "check_firecrawl_api_key", lambda: False)
-        assert web_tools.check_web_api_key() is False
+        monkeypatch.setattr(web_tools, "_ddgs_package_importable", lambda: False)
+        assert web_tools.check_web_api_key() is True
 
 
 # ---------------------------------------------------------------------------
diff --git a/tests/tools/test_web_tools_config.py b/tests/tools/test_web_tools_config.py
index 28323122aca0..c9a6b3b31a33 100644
--- a/tests/tools/test_web_tools_config.py
+++ b/tests/tools/test_web_tools_config.py
@@ -384,11 +384,14 @@ class TestBackendSelection:
              patch.dict(os.environ, {"FIRECRAWL_API_KEY": "fc-test"}):
             assert _get_backend() == "firecrawl"
 
-    def test_fallback_no_keys_defaults_to_firecrawl(self):
-        """No keys, no config → 'firecrawl' (will fail at client init)."""
+    def test_fallback_no_keys_defaults_to_parallel(self):
+        """No credentials, no config → 'parallel' (free Search MCP works
+        keyless). Selection is purely credential-based."""
         from tools.web_tools import _get_backend
-        with patch("tools.web_tools._load_web_config", return_value={}):
-            assert _get_backend() == "firecrawl"
+        with patch("tools.web_tools._load_web_config", return_value={}), \
+             patch("tools.web_tools._is_tool_gateway_ready", return_value=False), \
+             patch("tools.web_tools._ddgs_package_importable", return_value=False):
+            assert _get_backend() == "parallel"
 
     def test_invalid_config_falls_through_to_fallback(self):
         """web.backend=invalid → ignored, uses key-based fallback."""
@@ -623,9 +626,74 @@ class TestCheckWebApiKey:
             from tools.web_tools import check_web_api_key
             assert check_web_api_key() is True
 
-    def test_no_keys_returns_false(self):
+    def test_no_keys_usable_via_free_parallel(self):
+        """No credentials → check_web_api_key True: selection resolves to the
+        keyless Parallel free MCP, which genuinely services calls (web works out
+        of the box). check_web_api_key is a usability probe, not a key check."""
         from tools.web_tools import check_web_api_key
-        assert check_web_api_key() is False
+        with patch("tools.web_tools._load_web_config", return_value={}), \
+             patch("tools.web_tools._is_tool_gateway_ready", return_value=False), \
+             patch("tools.web_tools._ddgs_package_importable", return_value=False), \
+             patch.dict(os.environ, {}, clear=False):
+            for k in ("PARALLEL_API_KEY", "FIRECRAWL_API_KEY", "FIRECRAWL_API_URL",
+                      "TAVILY_API_KEY", "EXA_API_KEY", "SEARXNG_URL", "BRAVE_SEARCH_API_KEY"):
+                os.environ.pop(k, None)
+            assert check_web_api_key() is True
+
+    def test_typo_extract_backend_not_masked_by_parallel(self):
+        """A typo'd per-capability backend is honored (so dispatch errors)
+        rather than silently falling through to keyless Parallel."""
+        from tools.web_tools import _get_extract_backend, check_web_api_key
+        with patch("tools.web_tools._load_web_config",
+                   return_value={"extract_backend": "parrallel"}):
+            assert _get_extract_backend() == "parrallel"   # not "parallel"
+            assert check_web_api_key() is False            # unknown → unusable
+
+    def test_keyless_parallel_unusable_when_provider_disabled(self):
+        """If the bundled web-parallel provider is disabled/unregistered, the
+        keyless free-MCP path must NOT report web as usable — otherwise setup is
+        skipped but web tools fail at runtime with no provider."""
+        from tools.web_tools import check_web_api_key
+        with patch("tools.web_tools._load_web_config", return_value={}), \
+             patch("tools.web_tools._parallel_provider_registered", return_value=False), \
+             patch("tools.web_tools._is_tool_gateway_ready", return_value=False), \
+             patch("tools.web_tools.check_firecrawl_api_key", return_value=False), \
+             patch("tools.web_tools._ddgs_package_importable", return_value=False), \
+             patch.dict(os.environ, {}, clear=False):
+            for var in (
+                "PARALLEL_API_KEY", "FIRECRAWL_API_KEY", "FIRECRAWL_API_URL",
+                "TAVILY_API_KEY", "EXA_API_KEY", "BRAVE_SEARCH_API_KEY", "SEARXNG_URL",
+            ):
+                os.environ.pop(var, None)
+            assert check_web_api_key() is False
+
+    def test_extract_autodetect_skips_search_only_for_keyless_parallel(self):
+        """A search-only env credential (SEARXNG_URL) must not shadow the keyless
+        Parallel free-MCP extract fallback: extract auto-detect skips search-only
+        backends, so _get_extract_backend resolves to parallel (which can fetch),
+        while search auto-detect still prefers the configured searxng."""
+        from tools.web_tools import _get_extract_backend, _get_search_backend
+        with patch("tools.web_tools._load_web_config", return_value={}), \
+             patch.dict(os.environ, {}, clear=False):
+            for var in (
+                "PARALLEL_API_KEY", "FIRECRAWL_API_KEY", "FIRECRAWL_API_URL",
+                "TAVILY_API_KEY", "EXA_API_KEY", "BRAVE_SEARCH_API_KEY",
+            ):
+                os.environ.pop(var, None)
+            os.environ["SEARXNG_URL"] = "http://localhost:8080"
+            with patch("tools.web_tools._is_tool_gateway_ready", return_value=False):
+                assert _get_search_backend() == "searxng"
+                assert _get_extract_backend() == "parallel"
+
+    def test_configured_but_unavailable_backend_reports_unusable(self):
+        """An explicitly configured backend with no creds (exa, no key) →
+        check_web_api_key False so diagnostics flag the misconfiguration —
+        even though the tools stay registered."""
+        from tools.web_tools import check_web_api_key
+        with patch("tools.web_tools._load_web_config", return_value={"backend": "exa"}), \
+             patch.dict(os.environ, {}, clear=False):
+            os.environ.pop("EXA_API_KEY", None)
+            assert check_web_api_key() is False
 
     def test_both_keys_returns_true(self):
         with patch.dict(os.environ, {
@@ -688,12 +756,18 @@ class TestCheckWebApiKey:
 
         assert refresh_calls == []
 
-    def test_configured_backend_must_match_available_provider(self):
-        with patch("tools.web_tools._load_web_config", return_value={"backend": "parallel"}):
-            with patch("tools.web_tools._read_nous_access_token", return_value="nous-token"):
-                with patch.dict(os.environ, {"FIRECRAWL_GATEWAY_URL": "http://127.0.0.1:3002"}, clear=False):
-                    from tools.web_tools import check_web_api_key
-                    assert check_web_api_key() is False
+    def test_web_tools_registered_even_when_configured_backend_unavailable(self):
+        # Registration is unconditional (web_tools_registered) so an explicitly
+        # configured but unavailable backend (exa without EXA_API_KEY) keeps the
+        # tools registered to surface exa's setup error at call time — while the
+        # readiness probe (check_web_api_key) honestly reports not-configured.
+        from tools.web_tools import web_tools_registered, check_web_api_key
+        assert web_tools_registered() is True
+        with patch("tools.web_tools._load_web_config", return_value={"backend": "exa"}), \
+             patch.dict(os.environ, {}, clear=False):
+            os.environ.pop("EXA_API_KEY", None)
+            assert web_tools_registered() is True
+            assert check_web_api_key() is False
 
     def test_configured_firecrawl_backend_accepts_managed_gateway(self):
         with patch("tools.web_tools._load_web_config", return_value={"backend": "firecrawl"}):
diff --git a/tools/lazy_deps.py b/tools/lazy_deps.py
index e4b0a9a57f0e..76f146c7869c 100644
--- a/tools/lazy_deps.py
+++ b/tools/lazy_deps.py
@@ -90,7 +90,7 @@ LAZY_DEPS: dict[str, tuple[str, ...]] = {
     # ─── Web search backends ───────────────────────────────────────────────
     "search.exa": ("exa-py==2.10.2",),
     "search.firecrawl": ("firecrawl-py==4.17.0",),
-    "search.parallel": ("parallel-web==0.4.2",),
+    "search.parallel": ("parallel-web==0.6.0",),
 
     # ─── TTS providers ─────────────────────────────────────────────────────
     # Pinned to exact versions to match pyproject.toml's no-ranges policy
diff --git a/tools/web_tools.py b/tools/web_tools.py
index 133489b0a892..6bf522f33ecf 100644
--- a/tools/web_tools.py
+++ b/tools/web_tools.py
@@ -141,15 +141,35 @@ def _load_web_config() -> dict:
     except (ImportError, Exception):
         return {}
 
-def _get_backend() -> str:
+# Recognized web backend names (config values accepted in ``web.backend`` /
+# ``web.search_backend`` / ``web.extract_backend``). Kept as a single source of
+# truth for config validation across the selection helpers.
+_KNOWN_WEB_BACKENDS = frozenset(
+    {"parallel", "firecrawl", "tavily", "exa", "searxng", "brave-free", "ddgs", "xai"}
+)
+
+# Backends that only service web_search (their provider's ``supports_extract()``
+# is False). They are skipped during *extract* auto-detect so a search-only
+# credential (e.g. SEARXNG_URL) does not shadow the keyless Parallel free-MCP
+# fallback, which would otherwise leave web_extract broken on a no-key install.
+_SEARCH_ONLY_BACKENDS = frozenset({"searxng", "brave-free", "ddgs", "xai"})
+
+
+def _get_backend(capability: str = "search") -> str:
     """Determine which web backend to use (shared fallback).
 
     Reads ``web.backend`` from config.yaml (set by ``hermes tools``).
     Falls back to whichever API key is present for users who configured
     keys manually without running setup.
+
+    ``capability`` ("search" | "extract") only affects auto-detect: for
+    ``extract`` we skip search-only backends (``_SEARCH_ONLY_BACKENDS``) so a
+    search-only credential never shadows the keyless Parallel free-MCP extract
+    fallback. An explicit ``web.backend`` value is honored as-is (explicit wins,
+    surfacing that backend's own search-only error rather than rerouting).
     """
     configured = (_load_web_config().get("backend") or "").lower().strip()
-    if configured in {"parallel", "firecrawl", "tavily", "exa", "searxng", "brave-free", "ddgs", "xai"}:
+    if configured in _KNOWN_WEB_BACKENDS:
         return configured
 
     # Fallback for manual / legacy config — pick the highest-priority
@@ -158,7 +178,8 @@ def _get_backend() -> str:
     # pre-empted by a Nous OAuth token whose subscription tier may not
     # actually grant web-search access (the gateway then fails at runtime
     # with "no subscription" and the tool returns an error to the agent
-    # without falling back). Free-tier backends trail the paid ones.
+    # without falling back). Free-tier backends (searxng / brave-free /
+    # keyless parallel / ddgs) trail the keyed ones.
     backend_candidates = (
         ("tavily", _has_env("TAVILY_API_KEY")),
         ("exa", _has_env("EXA_API_KEY")),
@@ -167,13 +188,24 @@ def _get_backend() -> str:
         ("firecrawl", _is_tool_gateway_ready()),
         ("searxng", _has_env("SEARXNG_URL")),
         ("brave-free", _has_env("BRAVE_SEARCH_API_KEY")),
+        # Keyless Parallel free MCP — always available, the intended no-key
+        # default for both search and extract. Ahead of ddgs (search-only, so it
+        # can't service web_extract); ddgs stays reachable via web.backend=ddgs.
+        ("parallel", True),
         ("ddgs", _ddgs_package_importable()),
     )
     for backend, available in backend_candidates:
-        if available:
-            return backend
+        if not available:
+            continue
+        # For extract, skip search-only backends so the keyless Parallel
+        # free-MCP fallback (which can fetch URLs) is reached instead.
+        if capability == "extract" and backend in _SEARCH_ONLY_BACKENDS:
+            continue
+        return backend
 
-    return "firecrawl"  # default (backward compat)
+    # Defensive terminal (the keyless ``parallel`` candidate above is always
+    # available, so this is effectively unreachable).
+    return "parallel"
 
 
 def _get_search_backend() -> str:
@@ -204,14 +236,19 @@ def _get_extract_backend() -> str:
 def _get_capability_backend(capability: str) -> str:
     """Shared helper for per-capability backend selection.
 
-    Reads ``web.{capability}_backend`` from config; if set and available,
-    uses it. Otherwise falls through to the shared ``_get_backend()``.
+    Reads ``web.{capability}_backend`` from config. Any explicit value is
+    honored **regardless of availability** — including unrecognized typos like
+    ``parrallel`` — so the dispatcher surfaces that backend's own setup/config
+    error rather than silently rerouting to the keyless Parallel default (which
+    would send user queries to a different provider and hide the
+    misconfiguration). This matches ``web_search_registry``'s "explicit config
+    wins" rule. Only an *unset* value falls through to ``_get_backend()``.
     """
     cfg = _load_web_config()
     specific = (cfg.get(f"{capability}_backend") or "").lower().strip()
-    if specific and _is_backend_available(specific):
+    if specific:
         return specific
-    return _get_backend()
+    return _get_backend(capability)
 
 
 def _is_backend_available(backend: str) -> bool:
@@ -219,6 +256,8 @@ def _is_backend_available(backend: str) -> bool:
     if backend == "exa":
         return _has_env("EXA_API_KEY")
     if backend == "parallel":
+        # Credential probe: True only with a real key. The keyless free-MCP
+        # fallback is handled by _get_backend()'s terminal default, not here.
         return _has_env("PARALLEL_API_KEY")
     if backend == "firecrawl":
         return check_firecrawl_api_key()
@@ -972,11 +1011,19 @@ async def web_extract_tool(
             else:
                 safe_urls.append(url)
 
+        # Tracks the free-tier Parallel extract path (no key → web_fetch via the
+        # hosted Search MCP) so we can credit Parallel in the output/UI. Bound
+        # here so empty/all-blocked inputs (which skip dispatch) stay defined.
+        _free_parallel_extract = False
+
         # Dispatch only safe URLs to the configured backend
         if not safe_urls:
             results = []
         else:
             backend = _get_extract_backend()
+            _free_parallel_extract = (
+                backend == "parallel" and not _has_env("PARALLEL_API_KEY")
+            )
 
             # All seven providers (brave-free, ddgs, searxng, exa, parallel,
             # tavily, firecrawl) now live as plugins. The dispatcher is a
@@ -1150,6 +1197,14 @@ async def web_extract_tool(
             for r in response.get("results", [])
         ]
         trimmed_response = {"results": trimmed_results}
+        if _free_parallel_extract:
+            # Credit Parallel's free Search MCP (drives the "[Parallel]" UI tag
+            # + lets the model cite the source). Free tier only.
+            trimmed_response["provider"] = "parallel"
+            trimmed_response["attribution"] = (
+                "Extraction powered by the free Parallel Web Search MCP "
+                "(https://parallel.ai)."
+            )
 
         if trimmed_response.get("results") == []:
             result_json = tool_error("Content was inaccessible or not found")
@@ -1181,16 +1236,61 @@ async def web_extract_tool(
         return tool_error(error_msg)
 
 
-# Convenience function to check Firecrawl credentials
+def web_tools_registered() -> bool:
+    """Whether the web tools should be registered. Always True.
+
+    Registration is decoupled from credential readiness: with no credentials,
+    search/extract fall back to Parallel's free hosted Search MCP, and an
+    explicitly configured-but-unavailable backend must stay registered so
+    dispatch surfaces that backend's own setup error rather than the tool
+    silently vanishing. For "is web actually configured?" use
+    :func:`check_web_api_key`.
+    """
+    return True
+
+
+def _parallel_provider_registered() -> bool:
+    """True when the bundled ``web-parallel`` provider is registered/enabled.
+
+    Plugin discovery skips disabled plugins, so a disabled (``plugins.disabled``)
+    or otherwise-unregistered parallel provider yields ``None`` here.
+    """
+    _ensure_web_plugins_loaded()
+    try:
+        from agent.web_search_registry import get_provider
+
+        return get_provider("parallel") is not None
+    except Exception:  # noqa: BLE001
+        return False
+
+
+def _backend_usable(backend: str) -> bool:
+    """True when *backend* can service calls. Keyless Parallel counts (free MCP).
+
+    Unknown/typo'd backend names are not usable (so an explicit typo is reported
+    as a config problem rather than masked by the keyless fallback).
+    """
+    if backend == "parallel" and not _has_env("PARALLEL_API_KEY"):
+        # Keyless Parallel is only genuinely usable when its provider is actually
+        # registered/enabled. If web-parallel is disabled or discovery failed,
+        # report unusable so setup is not skipped and the user is not left with
+        # web tools that fail at runtime ("No web search provider configured").
+        return _parallel_provider_registered()
+    return _is_backend_available(backend)
+
+
 def check_web_api_key() -> bool:
-    """Check whether the configured web backend is available."""
-    configured = _load_web_config().get("backend", "").lower().strip()
-    if configured in {"exa", "parallel", "firecrawl", "tavily", "searxng", "brave-free", "ddgs", "xai"}:
-        return _is_backend_available(configured)
-    return any(
-        _is_backend_available(backend)
-        for backend in ("exa", "parallel", "firecrawl", "tavily", "searxng", "brave-free", "ddgs", "xai")
-    )
+    """Usability probe: True when the selected web backends can service calls.
+
+    Probes the backends that :func:`_get_search_backend` /
+    :func:`_get_extract_backend` actually select (not just shared
+    ``web.backend``), so an explicit per-capability backend with missing
+    credentials — or a typo'd name — reports unusable instead of being masked by
+    the keyless Parallel fallback. Keyless Parallel itself genuinely services
+    calls, so a zero-setup install reports usable. Distinct from
+    :func:`web_tools_registered` (always True — whether the tool is offered).
+    """
+    return _backend_usable(_get_search_backend()) and _backend_usable(_get_extract_backend())
 
 
 def check_auxiliary_model() -> bool:
@@ -1358,7 +1458,7 @@ registry.register(
     toolset="web",
     schema=WEB_SEARCH_SCHEMA,
     handler=lambda args, **kw: web_search_tool(args.get("query", ""), limit=args.get("limit", 5)),
-    check_fn=check_web_api_key,
+    check_fn=web_tools_registered,
     requires_env=_web_requires_env(),
     emoji="🔍",
     max_result_size_chars=100_000,
@@ -1369,7 +1469,7 @@ registry.register(
     schema=WEB_EXTRACT_SCHEMA,
     handler=lambda args, **kw: web_extract_tool(
         args.get("urls", [])[:5] if isinstance(args.get("urls"), list) else [], "markdown"),
-    check_fn=check_web_api_key,
+    check_fn=web_tools_registered,
     requires_env=_web_requires_env(),
     is_async=True,
     emoji="📄",
diff --git a/uv.lock b/uv.lock
index 55d7da4a4a84..f90a3a4270cb 100644
--- a/uv.lock
+++ b/uv.lock
@@ -1653,7 +1653,7 @@ requires-dist = [
     { name = "numpy", marker = "extra == 'voice'", specifier = "==2.4.3" },
     { name = "openai", specifier = "==2.24.0" },
     { name = "packaging", specifier = "==26.0" },
-    { name = "parallel-web", marker = "extra == 'parallel-web'", specifier = "==0.4.2" },
+    { name = "parallel-web", marker = "extra == 'parallel-web'", specifier = "==0.6.0" },
     { name = "pathspec", specifier = "==1.1.1" },
     { name = "pillow", specifier = "==12.2.0" },
     { name = "prompt-toolkit", specifier = "==3.0.52" },
@@ -2690,7 +2690,7 @@ wheels = [
 
 [[package]]
 name = "parallel-web"
-version = "0.4.2"
+version = "0.6.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "anyio" },
@@ -2700,9 +2700,9 @@ dependencies = [
     { name = "sniffio" },
     { name = "typing-extensions" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/24/50/fb9b28a679e01682006b5259abff96de3d16e114e9447a7793fec31715de/parallel_web-0.4.2.tar.gz", hash = "sha256:599b5a8f387dc35c7dc8c81e372eadf6958a40acacea58bf170dfc663c003da7", size = 140026, upload-time = "2026-03-09T22:24:35.448Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/7f/81/101c961fe6665212df01fb39a70ebb379dc33529c7bc9210675c0f525139/parallel_web-0.6.0.tar.gz", hash = "sha256:f8aecd3f1958090090c4516881cefea4f55c40948ba3bb99217ca9a6d4263225", size = 173149, upload-time = "2026-05-06T19:13:09.782Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/a0/3e/2218fa29637781b8e7ac35a928108ff2614ddd40879389d3af2caa725af5/parallel_web-0.4.2-py3-none-any.whl", hash = "sha256:aa3a4a9aecc08972c5ce9303271d4917903373dff4dd277d9a3e30f9cff53346", size = 144012, upload-time = "2026-03-09T22:24:33.979Z" },
+    { url = "https://files.pythonhosted.org/packages/a2/7c/7e8b63a0e90efaf567a818fca86c6ad3a85711f8995d2657b51b0cae2351/parallel_web-0.6.0-py3-none-any.whl", hash = "sha256:dc5342ef7262bd2e9f85eb7eace32833bd3d7e3af0bf5fbd780d1ea8c8d9ceb0", size = 199217, upload-time = "2026-05-06T19:13:08.316Z" },
 ]
 
 [[package]]

From 0a5762c78d11f4d6626dbf99da5f62cc34cfe2c4 Mon Sep 17 00:00:00 2001
From: Teknium <127238744+teknium1@users.noreply.github.com>
Date: Wed, 10 Jun 2026 15:13:42 -0700
Subject: [PATCH 06/28] fix(web): genericize free-MCP client identity per
 telemetry policy

Replace the hermes-identifying clientInfo/User-Agent/session-id prefix on
the keyless Parallel Search MCP path with a neutral 'mcp-web-client'
identity. Project policy forbids third-party usage attribution without an
explicit user opt-in (see telemetry PR policy); MCP requires a clientInfo,
so a generic one satisfies the spec without attributing traffic.

Also adds the contributor AUTHOR_MAP entry and refreshes uv.lock against
current main (parallel-web 0.6.0).
---
 plugins/web/parallel/provider.py              | 15 +++++++-----
 scripts/release.py                            |  1 +
 .../plugins/web/test_parallel_keyless_mcp.py  | 23 ++++++++++---------
 3 files changed, 22 insertions(+), 17 deletions(-)

diff --git a/plugins/web/parallel/provider.py b/plugins/web/parallel/provider.py
index 20c4291d77b9..7a15b3d3f80a 100644
--- a/plugins/web/parallel/provider.py
+++ b/plugins/web/parallel/provider.py
@@ -55,11 +55,13 @@ logger = logging.getLogger(__name__)
 # configured. Docs: https://docs.parallel.ai/integrations/mcp/search-mcp
 _MCP_SEARCH_URL = "https://search.parallel.ai/mcp"
 _MCP_PROTOCOL_VERSION = "2025-06-18"
-_MCP_CLIENT_NAME = "hermes-agent"
+# Deliberately generic client identity. Project policy (see the telemetry PR
+# policy in AGENTS.md) forbids third-party usage attribution without an
+# explicit user opt-in, so neither clientInfo nor the User-Agent names
+# hermes. MCP requires *a* clientInfo; a neutral one satisfies the spec
+# without attributing traffic.
+_MCP_CLIENT_NAME = "mcp-web-client"
 _MCP_CLIENT_VERSION = "1.0.0"
-# Identify free-tier traffic at the HTTP layer. Without this, httpx sends a
-# generic ``python-httpx/<version>`` User-Agent and hermes usage is only visible
-# via the JSON-RPC ``clientInfo`` payload.
 _MCP_USER_AGENT = f"{_MCP_CLIENT_NAME}/{_MCP_CLIENT_VERSION}"
 _MCP_TIMEOUT_SECONDS = 30.0
 
@@ -76,9 +78,10 @@ def _new_session_id() -> str:
 
     Per-call rather than process-global: one process serves many unrelated
     chats in the gateway/batch runners, and a shared id would pool their
-    searches into one Parallel session.
+    searches into one Parallel session. The prefix is deliberately generic
+    (no hermes attribution — telemetry policy).
     """
-    return f"hermes-agent-{uuid.uuid4().hex}"
+    return f"{_MCP_CLIENT_NAME}-{uuid.uuid4().hex}"
 
 # Module-level note: the canonical cache slots ``_parallel_client`` and
 # ``_async_parallel_client`` live on :mod:`tools.web_tools` so tests that do
diff --git a/scripts/release.py b/scripts/release.py
index cd0fe475d5dc..68ad134d6cdb 100755
--- a/scripts/release.py
+++ b/scripts/release.py
@@ -75,6 +75,7 @@ AUTHOR_MAP = {
     "129007007+HeLLGURD@users.noreply.github.com": "HeLLGURD",
     "290859878+synapsesx@users.noreply.github.com": "synapsesx",
     "dirtyren@users.noreply.github.com": "dirtyren",
+    "mharris@parallel.ai": "NormallyGaussian",
     "ted.malone@outlook.com": "temalo",
     "adityamalik2833@gmail.com": "alarcritty",
     "islam666@users.noreply.github.com": "islam666",
diff --git a/tests/plugins/web/test_parallel_keyless_mcp.py b/tests/plugins/web/test_parallel_keyless_mcp.py
index 49975c47f2f0..8495df144b46 100644
--- a/tests/plugins/web/test_parallel_keyless_mcp.py
+++ b/tests/plugins/web/test_parallel_keyless_mcp.py
@@ -30,15 +30,16 @@ class TestMcpHeaders:
         assert h["Accept"] == "application/json, text/event-stream"
         assert "Mcp-Session-Id" not in h
 
-    def test_identifies_hermes_via_user_agent(self):
-        # Free-tier traffic is attributable at the HTTP layer (not just via the
-        # JSON-RPC clientInfo payload), on both the anonymous and keyed paths.
-        assert pp._mcp_headers(session_id=None, api_key=None)["User-Agent"].startswith(
-            "hermes-agent/"
-        )
-        assert pp._mcp_headers(session_id="sid", api_key="pk-live")["User-Agent"].startswith(
-            "hermes-agent/"
-        )
+    def test_user_agent_is_generic_not_hermes(self):
+        # Telemetry policy: no third-party usage attribution without opt-in.
+        # The UA must be set (not python-httpx default) but must not name
+        # hermes, on both the anonymous and keyed paths.
+        for ua in (
+            pp._mcp_headers(session_id=None, api_key=None)["User-Agent"],
+            pp._mcp_headers(session_id="sid", api_key="pk-live")["User-Agent"],
+        ):
+            assert ua == f"{pp._MCP_CLIENT_NAME}/{pp._MCP_CLIENT_VERSION}"
+            assert "hermes" not in ua.lower()
 
     def test_session_id_and_bearer_when_present(self):
         h = pp._mcp_headers(session_id="sid-123", api_key="pk-live")
@@ -280,7 +281,7 @@ class TestMcpWebFetch:
         assert args["name"] == "web_fetch"
         assert args["arguments"]["urls"] == urls
         assert args["arguments"]["full_content"] is True
-        assert args["arguments"]["session_id"].startswith("hermes-agent-")
+        assert args["arguments"]["session_id"].startswith(f"{pp._MCP_CLIENT_NAME}-")
 
     def test_prefers_full_content_over_excerpts(self):
         payload = {"results": [
@@ -354,7 +355,7 @@ class TestKeyedV1Search:
         # honors the caller's limit via advanced_settings.max_results
         assert captured["advanced_settings"] == {"max_results": 7}
         assert captured["mode"] == "advanced"            # v1 default
-        assert captured["session_id"].startswith("hermes-agent-")  # per-call id
+        assert captured["session_id"].startswith(f"{pp._MCP_CLIENT_NAME}-")  # per-call id
         assert len(out["data"]["web"]) == 7              # client-side slice
         # paid path: no free-tier attribution, no [Parallel] label signal
         assert "attribution" not in out

From acd7932c0fc5f98331f01af6073115e6cf3ccf9d Mon Sep 17 00:00:00 2001
From: Teknium <127238744+teknium1@users.noreply.github.com>
Date: Wed, 10 Jun 2026 19:54:44 -0700
Subject: [PATCH 07/28] docs: cross-link write-approval gate from skills,
 configuration, and slash-command docs (#43801)

The memory/skill write-approval gate (#38199, #43354, #43452) was only
documented inside features/memory.md. Surface it everywhere users will
actually look:

- features/skills.md: new 'Gating agent skill writes' section under
  skill_manage, with the staging semantics, review commands, and the
  distinction from skills.guard_agent_created
- configuration.md: memory.write_approval added to the Memory
  Configuration block; new 'Write approval for skill writes' subsection
  next to the guard_agent_created scanner
- reference/slash-commands.md: /memory and /skills review subcommands in
  both the CLI and messaging tables; Notes updated since /skills
  pending/approve/reject/diff/approval now works on the gateway
- features/memory.md: cross-link to the new skills section
---
 website/docs/reference/slash-commands.md   |  8 +++--
 website/docs/user-guide/configuration.md   | 14 ++++++++
 website/docs/user-guide/features/memory.md |  1 +
 website/docs/user-guide/features/skills.md | 37 ++++++++++++++++++++++
 4 files changed, 58 insertions(+), 2 deletions(-)

diff --git a/website/docs/reference/slash-commands.md b/website/docs/reference/slash-commands.md
index 44a9a303a624..a9951263d7ff 100644
--- a/website/docs/reference/slash-commands.md
+++ b/website/docs/reference/slash-commands.md
@@ -86,7 +86,8 @@ Type `/` in the CLI to open the autocomplete menu. Built-in commands are case-in
 | `/tools [list\|disable\|enable] [name...]` | Manage tools: list available tools, or disable/enable specific tools for the current session. Disabling a tool removes it from the agent's toolset and triggers a session reset. |
 | `/toolsets` | List available toolsets |
 | `/browser [connect\|disconnect\|status]` | Manage a local Chromium-family CDP connection. `connect` attaches browser tools to a running Chrome, Brave, Chromium, or Edge instance (default: `http://127.0.0.1:9222`). `disconnect` detaches. `status` shows current connection. Auto-launches a supported Chromium-family browser if no debugger is detected. |
-| `/skills` | Search, install, inspect, or manage skills from online registries |
+| `/skills` | Search, install, inspect, or manage skills from online registries. Also the review surface for the skill write-approval gate: `/skills pending`, `/skills diff <id>`, `/skills approve <id>`, `/skills reject <id>`, `/skills approval on\|off`. See [Gating agent skill writes](/user-guide/features/skills#gating-agent-skill-writes-skillswrite_approval). |
+| `/memory [pending\|approve\|reject\|approval]` | Review pending memory writes staged by the write-approval gate (`memory.write_approval`) and toggle the gate. See [Controlling memory writes](/user-guide/features/memory#controlling-memory-writes-write_approval). |
 | `/bundles` | List configured skill bundles — `/<name>` slash aliases that preload several skills at once. Configure under `bundles:` in `~/.hermes/config.yaml`. See [Skill Bundles](/user-guide/features/skills#skill-bundles). |
 | `/cron` | Manage scheduled tasks (list, add/create, edit, pause, resume, run, remove) |
 | `/curator` | Background skill maintenance — `status`, `run`, `pin`, `archive`. See [Curator](/user-guide/features/curator). |
@@ -222,6 +223,8 @@ The messaging gateway supports the following built-in commands inside Telegram,
 | `/goal <text>` | Set a standing goal Hermes works toward across turns — our take on the Ralph loop. A judge model checks after each turn; if not done, Hermes auto-continues until it is, you pause/clear it, or the turn budget (default 20) is hit. Subcommands: `/goal status`, `/goal pause`, `/goal resume`, `/goal clear`. Safe to run mid-agent for status/pause/clear; setting a new goal requires `/stop` first. See [Persistent Goals](/user-guide/features/goals). |
 | `/footer [on\|off\|status]` | Toggle the runtime-metadata footer on final replies (shows model, context %, and cwd). |
 | `/curator [status\|run\|pin\|archive]` | Background skill maintenance controls. |
+| `/memory [pending\|approve\|reject\|approval]` | Review pending memory writes staged by the write-approval gate (`memory.write_approval`) — approve or reject them right in chat — and toggle the gate with `/memory approval on\|off`. See [Controlling memory writes](/user-guide/features/memory#controlling-memory-writes-write_approval). |
+| `/skills [pending\|approve\|reject\|diff\|approval]` | Review pending **skill** writes staged by the write-approval gate (`skills.write_approval`). Shows a one-line gist per staged write; `/skills diff <id>` is truncated for chat — read the full diff on the CLI or in `~/.hermes/pending/skills/<id>.json`. Only appears when the gate is on (or staged writes remain); search/install stay CLI-only. |
 | `/kanban <action>` | Drive the multi-profile, multi-project collaboration board from chat — identical argument surface to the CLI. Bypasses the running-agent guard, so `/kanban unblock t_abc`, `/kanban comment t_abc "…"`, `/kanban list --mine`, `/kanban boards switch <slug>`, etc. work mid-turn. `/kanban create …` auto-subscribes the originating chat to the new task's terminal events. See [Kanban slash command](/user-guide/features/kanban#kanban-slash-command). |
 | `/reload-mcp` (alias: `/reload_mcp`) | Reload MCP servers from config. |
 | `/yolo` | Toggle YOLO mode — skip all dangerous command approval prompts. |
@@ -236,7 +239,8 @@ The messaging gateway supports the following built-in commands inside Telegram,
 
 ## Notes
 
-- `/skin`, `/snapshot`, `/gquota`, `/reload`, `/tools`, `/toolsets`, `/browser`, `/config`, `/cron`, `/skills`, `/platforms`, `/paste`, `/image`, `/statusbar`, `/plugins`, `/busy`, `/indicator`, `/redraw`, `/clear`, `/history`, `/save`, `/copy`, `/handoff`, and `/quit` are **CLI-only** commands.
+- `/skin`, `/snapshot`, `/gquota`, `/reload`, `/tools`, `/toolsets`, `/browser`, `/config`, `/cron`, `/platforms`, `/paste`, `/image`, `/statusbar`, `/plugins`, `/busy`, `/indicator`, `/redraw`, `/clear`, `/history`, `/save`, `/copy`, `/handoff`, and `/quit` are **CLI-only** commands.
+- `/skills` is **CLI-only for search/browse/install**; its write-approval review subcommands (`pending`, `approve`, `reject`, `diff`, `approval`) also work on messaging platforms when `skills.write_approval` is on. `/memory` works on **both** surfaces.
 - `/verbose` is **CLI-only by default**, but can be enabled for messaging platforms by setting `display.tool_progress_command: true` in `config.yaml`. When enabled, it cycles the `display.tool_progress` mode and saves to config.
 - `/sethome`, `/update`, `/restart`, `/approve`, `/deny`, `/topic`, and `/commands` are **messaging-only** commands.
 - `/status`, `/version`, `/background`, `/queue`, `/steer`, `/voice`, `/reload-mcp`, `/reload-skills`, `/rollback`, `/debug`, `/fast`, `/footer`, `/curator`, `/kanban`, `/sessions`, and `/yolo` work in **both** the CLI and the messaging gateway.
diff --git a/website/docs/user-guide/configuration.md b/website/docs/user-guide/configuration.md
index 4b2d2c40e93f..062eb53d3447 100644
--- a/website/docs/user-guide/configuration.md
+++ b/website/docs/user-guide/configuration.md
@@ -533,6 +533,17 @@ skills:
 
 When on, any flagged `skill_manage` write surfaces as an approval prompt with the scanner's rationale. Accepted writes land; denied writes return an explanatory error to the agent.
 
+### Write approval for skill writes
+
+Independent of the content scanner above, `skills.write_approval` gates **every** agent skill write (create / edit / patch / delete / supporting files) behind your explicit approval — the same approve/deny mechanism as dangerous commands:
+
+```yaml
+skills:
+  write_approval: false   # false = write freely (default) | true = stage every write for review
+```
+
+When on, skill writes are staged under `~/.hermes/pending/skills/` and reviewed with `/skills pending`, `/skills diff <id>`, `/skills approve <id>`, `/skills reject <id>` — from the CLI or any messaging platform. Toggle at runtime with `/skills approval on|off`. Memory has the same gate (`memory.write_approval`, below). Full walkthrough: [Gating agent skill writes](/user-guide/features/skills#gating-agent-skill-writes-skillswrite_approval).
+
 ## Memory Configuration
 
 ```yaml
@@ -541,8 +552,11 @@ memory:
   user_profile_enabled: true
   memory_char_limit: 2200   # ~800 tokens
   user_char_limit: 1375     # ~500 tokens
+  write_approval: false     # true = require approval before any memory write
 ```
 
+With `memory.write_approval: true`, memory writes need your approval before they land: interactive CLI turns prompt inline; messaging sessions and the background self-improvement review stage the write for `/memory pending` → `/memory approve <id>` / `/memory reject <id>` review. Toggle at runtime with `/memory approval on|off`. See [Controlling memory writes](/user-guide/features/memory#controlling-memory-writes-write_approval).
+
 ## File Read Safety
 
 Controls how much content a single `read_file` call can return. Reads that exceed the limit are rejected with an error telling the agent to use `offset` and `limit` for a smaller range. This prevents a single read of a minified JS bundle or large data file from flooding the context window.
diff --git a/website/docs/user-guide/features/memory.md b/website/docs/user-guide/features/memory.md
index b4814d2a178f..1f0ee16942f4 100644
--- a/website/docs/user-guide/features/memory.md
+++ b/website/docs/user-guide/features/memory.md
@@ -270,6 +270,7 @@ inline, but the full diff stays out-of-band:
 On a messaging platform, approve a skill from its gist + metadata, or open
 `/skills diff` on the CLI / dashboard / the staged file under
 `~/.hermes/pending/skills/<id>.json` when you want to read the whole change.
+Full details in [Gating agent skill writes](/user-guide/features/skills#gating-agent-skill-writes-skillswrite_approval).
 
 
 ## External Memory Providers
diff --git a/website/docs/user-guide/features/skills.md b/website/docs/user-guide/features/skills.md
index 8a5209c6944e..6cfbafee3c3a 100644
--- a/website/docs/user-guide/features/skills.md
+++ b/website/docs/user-guide/features/skills.md
@@ -401,6 +401,43 @@ The agent can create, update, and delete its own skills via the `skill_manage` t
 The `patch` action is preferred for updates — it's more token-efficient than `edit` because only the changed text appears in the tool call.
 :::
 
+### Gating agent skill writes (`skills.write_approval`)
+
+By default the agent writes skills freely — including from the [background
+self-improvement review](/user-guide/features/memory#controlling-memory-writes-write_approval)
+that runs after a turn. If you'd rather approve every skill write first
+(small models that misjudge what they learned, secure environments, or just
+wanting eyes on the self-improvement loop), turn on the write-approval gate:
+
+```yaml
+skills:
+  write_approval: false     # false = write freely (default) | true = require approval
+```
+
+When `write_approval: true`, every `skill_manage` write (create / edit /
+patch / delete / write_file / remove_file) is **staged** instead of committed —
+a SKILL.md is too large to review inline, so staging applies regardless of
+whether the write came from a foreground turn or the background review.
+Staged writes survive restarts under `~/.hermes/pending/skills/` and are
+reviewed with the same familiar approve/deny flow as dangerous commands:
+
+```
+/skills pending             # list staged skill writes + a one-line gist each
+/skills diff <id>           # full unified diff (best viewed in CLI or dashboard)
+/skills approve <id>        # apply it (or 'all')
+/skills reject <id>         # drop it (or 'all')
+/skills approval on         # turn the gate on (or 'off') and persist it
+```
+
+The review surface works in the interactive CLI and on messaging platforms
+(diff output is truncated for chat bubbles — read the full diff on the CLI or
+in the pending JSON file). Memory writes have the same gate under
+`memory.write_approval` — see [Controlling memory writes](/user-guide/features/memory#controlling-memory-writes-write_approval).
+
+> The separate `skills.guard_agent_created` setting is a content scanner
+> (dangerous-pattern heuristics), not an approval gate — the two are
+> independent. See [Guard on agent-created skill writes](/user-guide/configuration#guard-on-agent-created-skill-writes).
+
 ## Skills Hub
 
 Browse, search, install, and manage skills from online registries, `skills.sh`, direct well-known skill endpoints, and official optional skills.

From 18d61bd06e062049f524d6b1d3a51956db2cf1ea Mon Sep 17 00:00:00 2001
From: Roger <roger@roger.local>
Date: Wed, 10 Jun 2026 13:00:45 -0400
Subject: [PATCH 08/28] fix(desktop): persist composer drafts across reloads

Save in-progress composer text to browser localStorage per chat session and restore it when the desktop composer remounts. Keep the draft when submit is rejected or throws, and clear it only after the prompt is accepted.
---
 apps/desktop/src/app/chat/composer/index.tsx | 54 ++++++++++++++++-
 apps/desktop/src/store/composer.test.ts      | 42 ++++++++++++-
 apps/desktop/src/store/composer.ts           | 62 ++++++++++++++++++++
 3 files changed, 154 insertions(+), 4 deletions(-)

diff --git a/apps/desktop/src/app/chat/composer/index.tsx b/apps/desktop/src/app/chat/composer/index.tsx
index bf9488348376..05fa4a451bce 100644
--- a/apps/desktop/src/app/chat/composer/index.tsx
+++ b/apps/desktop/src/app/chat/composer/index.tsx
@@ -24,7 +24,14 @@ import { desktopSlashCommandTakesArgs } from '@/lib/desktop-slash-commands'
 import { DATA_IMAGE_URL_RE } from '@/lib/embedded-images'
 import { triggerHaptic } from '@/lib/haptics'
 import { cn } from '@/lib/utils'
-import { $composerAttachments, clearComposerAttachments, type ComposerAttachment } from '@/store/composer'
+import {
+  $composerAttachments,
+  clearComposerAttachments,
+  clearPersistedComposerDraft,
+  type ComposerAttachment,
+  readPersistedComposerDraft,
+  writePersistedComposerDraft
+} from '@/store/composer'
 import {
   browseBackward,
   browseForward,
@@ -160,6 +167,7 @@ export function ChatBar({
   const scrolledUp = useStore($threadScrolledUp)
   const sessionMessages = useStore($messages)
   const activeQueueSessionKey = queueSessionKey || sessionId || null
+  const draftPersistenceScope = activeQueueSessionKey || null
 
   const queuedPrompts = useMemo(
     () => (activeQueueSessionKey ? (queuedPromptsBySession[activeQueueSessionKey] ?? []) : []),
@@ -171,6 +179,7 @@ export function ChatBar({
   const editorRef = useRef<HTMLDivElement | null>(null)
   const draftRef = useRef(draft)
   const previousBusyRef = useRef(busy)
+  const skipNextDraftPersistScopeRef = useRef<string | null>(null)
   const drainingQueueRef = useRef(false)
   const urlInputRef = useRef<HTMLInputElement | null>(null)
 
@@ -1097,6 +1106,22 @@ export function ChatBar({
     }
   }
 
+  useEffect(() => {
+    const persisted = readPersistedComposerDraft(draftPersistenceScope)
+    skipNextDraftPersistScopeRef.current = draftPersistenceScope
+    loadIntoComposer(persisted, [])
+  }, [draftPersistenceScope]) // eslint-disable-line react-hooks/exhaustive-deps
+
+  useEffect(() => {
+    if (skipNextDraftPersistScopeRef.current === draftPersistenceScope) {
+      skipNextDraftPersistScopeRef.current = null
+
+      return
+    }
+
+    writePersistedComposerDraft(draftPersistenceScope, draft)
+  }, [draft, draftPersistenceScope])
+
   const beginQueuedEdit = (entry: QueuedPromptEntry) => {
     if (!activeQueueSessionKey || queueEdit) {
       return
@@ -1323,8 +1348,10 @@ export function ChatBar({
     // input event; refresh it from the editor once more to also cover an
     // in-flight keystroke that hasn't fired its input event yet.
     const editor = editorRef.current
+
     if (editor) {
       const domText = composerPlainText(editor)
+
       if (domText !== draftRef.current) {
         draftRef.current = domText
         aui.composer().setText(domText)
@@ -1348,7 +1375,17 @@ export function ChatBar({
         const submitted = text
         triggerHaptic('submit')
         clearDraft()
-        void onSubmit(submitted)
+        void Promise.resolve(onSubmit(submitted)).then(accepted => {
+          if (accepted === false) {
+            loadIntoComposer(submitted, [])
+            writePersistedComposerDraft(draftPersistenceScope, submitted)
+          } else {
+            clearPersistedComposerDraft(draftPersistenceScope)
+          }
+        }).catch(() => {
+          loadIntoComposer(submitted, [])
+          writePersistedComposerDraft(draftPersistenceScope, submitted)
+        })
       } else if (payloadPresent) {
         queueCurrentDraft()
       } else {
@@ -1361,11 +1398,22 @@ export function ChatBar({
       void drainNextQueued()
     } else if (payloadPresent) {
       const submitted = text
+      const submittedAttachments = cloneAttachments(attachments)
       triggerHaptic('submit')
       resetBrowseState(sessionId)
       clearDraft()
       clearComposerAttachments()
-      void onSubmit(submitted, { attachments })
+      void Promise.resolve(onSubmit(submitted, { attachments: submittedAttachments })).then(accepted => {
+        if (accepted === false) {
+          loadIntoComposer(submitted, submittedAttachments)
+          writePersistedComposerDraft(draftPersistenceScope, submitted)
+        } else {
+          clearPersistedComposerDraft(draftPersistenceScope)
+        }
+      }).catch(() => {
+        loadIntoComposer(submitted, submittedAttachments)
+        writePersistedComposerDraft(draftPersistenceScope, submitted)
+      })
     }
 
     focusInput()
diff --git a/apps/desktop/src/store/composer.test.ts b/apps/desktop/src/store/composer.test.ts
index 83f0a3feb96f..7bb44c74bd06 100644
--- a/apps/desktop/src/store/composer.test.ts
+++ b/apps/desktop/src/store/composer.test.ts
@@ -3,9 +3,13 @@ import { afterEach, describe, expect, it } from 'vitest'
 import {
   $composerAttachments,
   addComposerAttachment,
+  clearPersistedComposerDraft,
   type ComposerAttachment,
+  composerDraftStorageKey,
+  readPersistedComposerDraft,
   removeComposerAttachment,
-  updateComposerAttachment
+  updateComposerAttachment,
+  writePersistedComposerDraft
 } from './composer'
 
 function attachment(overrides: Partial<ComposerAttachment> & Pick<ComposerAttachment, 'id'>): ComposerAttachment {
@@ -41,3 +45,39 @@ describe('updateComposerAttachment', () => {
     expect($composerAttachments.get()).toHaveLength(0)
   })
 })
+
+describe('persisted composer drafts', () => {
+  afterEach(() => {
+    window.localStorage.clear()
+  })
+
+  it('stores and restores text drafts per session scope', () => {
+    writePersistedComposerDraft('session-a', 'almost submitted prompt')
+    writePersistedComposerDraft('session-b', 'other draft')
+
+    expect(readPersistedComposerDraft('session-a')).toBe('almost submitted prompt')
+    expect(readPersistedComposerDraft('session-b')).toBe('other draft')
+  })
+
+  it('uses a stable new-session key when no session id exists yet', () => {
+    writePersistedComposerDraft(null, 'first prompt draft')
+
+    expect(window.localStorage.getItem(composerDraftStorageKey(null))).toBe('first prompt draft')
+    expect(readPersistedComposerDraft(undefined)).toBe('first prompt draft')
+  })
+
+  it('removes empty drafts instead of leaving stale text behind', () => {
+    writePersistedComposerDraft('session-a', 'saved')
+    writePersistedComposerDraft('session-a', '')
+
+    expect(readPersistedComposerDraft('session-a')).toBe('')
+    expect(window.localStorage.getItem(composerDraftStorageKey('session-a'))).toBeNull()
+  })
+
+  it('can explicitly clear a saved draft after submit', () => {
+    writePersistedComposerDraft('session-a', 'saved')
+    clearPersistedComposerDraft('session-a')
+
+    expect(readPersistedComposerDraft('session-a')).toBe('')
+  })
+})
diff --git a/apps/desktop/src/store/composer.ts b/apps/desktop/src/store/composer.ts
index 6b2b58ccb8d3..5af98a49e3b4 100644
--- a/apps/desktop/src/store/composer.ts
+++ b/apps/desktop/src/store/composer.ts
@@ -21,6 +21,68 @@ export const $composerDraft = atom('')
 export const $composerAttachments = atom<ComposerAttachment[]>([])
 export const $composerTerminalSelections = atom<Record<string, string>>({})
 
+const COMPOSER_DRAFT_STORAGE_PREFIX = 'hermes:composer-draft:v1:'
+const NEW_SESSION_DRAFT_SCOPE = '__new__'
+
+function storageScope(scope: string | null | undefined): string {
+  const trimmed = scope?.trim()
+
+  return trimmed || NEW_SESSION_DRAFT_SCOPE
+}
+
+function browserStorage(): Storage | null {
+  if (typeof window === 'undefined') {
+    return null
+  }
+
+  try {
+    return window.localStorage
+  } catch {
+    return null
+  }
+}
+
+export function composerDraftStorageKey(scope: string | null | undefined): string {
+  return `${COMPOSER_DRAFT_STORAGE_PREFIX}${encodeURIComponent(storageScope(scope))}`
+}
+
+export function readPersistedComposerDraft(scope: string | null | undefined): string {
+  try {
+    return browserStorage()?.getItem(composerDraftStorageKey(scope)) ?? ''
+  } catch {
+    return ''
+  }
+}
+
+export function writePersistedComposerDraft(scope: string | null | undefined, value: string) {
+  try {
+    const storage = browserStorage()
+
+    if (!storage) {
+      return
+    }
+
+    const key = composerDraftStorageKey(scope)
+
+    if (value.length === 0) {
+      storage.removeItem(key)
+    } else {
+      storage.setItem(key, value)
+    }
+  } catch {
+    // Draft persistence is a safety net only; storage quota/private-mode errors
+    // must never break typing or submission.
+  }
+}
+
+export function clearPersistedComposerDraft(scope: string | null | undefined) {
+  try {
+    browserStorage()?.removeItem(composerDraftStorageKey(scope))
+  } catch {
+    // Best-effort only.
+  }
+}
+
 export function setComposerDraft(value: string) {
   $composerDraft.set(value)
 }

From 3d14f01fd674ab2add062d3a302c30a6b457b791 Mon Sep 17 00:00:00 2001
From: Teknium <127238744+teknium1@users.noreply.github.com>
Date: Wed, 10 Jun 2026 19:57:09 -0700
Subject: [PATCH 09/28] fix(desktop): debounce per-keystroke draft persistence
 writes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The salvaged draft-persistence effect wrote to localStorage on every
keystroke — the composer's per-keystroke path was deliberately slimmed
down previously, so debounce the write (400ms) and flush pending text on
scope change/unmount so a fast session switch can't drop trailing
keystrokes. Also add AUTHOR_MAP entry for the salvaged commit.
---
 apps/desktop/src/app/chat/composer/index.tsx | 33 +++++++++++++++++++-
 scripts/release.py                           |  1 +
 2 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/apps/desktop/src/app/chat/composer/index.tsx b/apps/desktop/src/app/chat/composer/index.tsx
index 05fa4a451bce..5530ffb60aef 100644
--- a/apps/desktop/src/app/chat/composer/index.tsx
+++ b/apps/desktop/src/app/chat/composer/index.tsx
@@ -137,6 +137,10 @@ interface QueueEditState {
 
 const cloneAttachments = (attachments: ComposerAttachment[]) => attachments.map(a => ({ ...a }))
 
+// How long the composer waits after the last keystroke before persisting the
+// draft to localStorage. Scope-change/unmount flushes bypass the delay.
+const DRAFT_PERSIST_DEBOUNCE_MS = 400
+
 export function ChatBar({
   busy,
   cwd,
@@ -180,6 +184,7 @@ export function ChatBar({
   const draftRef = useRef(draft)
   const previousBusyRef = useRef(busy)
   const skipNextDraftPersistScopeRef = useRef<string | null>(null)
+  const pendingDraftPersistRef = useRef<{ scope: string | null; value: string } | null>(null)
   const drainingQueueRef = useRef(false)
   const urlInputRef = useRef<HTMLInputElement | null>(null)
 
@@ -1119,9 +1124,35 @@ export function ChatBar({
       return
     }
 
-    writePersistedComposerDraft(draftPersistenceScope, draft)
+    // Debounce the localStorage write: the composer's per-keystroke path was
+    // deliberately slimmed down (see the draftRef sync comment above), so we
+    // don't touch storage on every keypress. The pending ref below is flushed
+    // on scope change / unmount so a fast session switch can't drop the
+    // trailing keystrokes.
+    pendingDraftPersistRef.current = { scope: draftPersistenceScope, value: draft }
+
+    const handle = window.setTimeout(() => {
+      pendingDraftPersistRef.current = null
+      writePersistedComposerDraft(draftPersistenceScope, draft)
+    }, DRAFT_PERSIST_DEBOUNCE_MS)
+
+    return () => window.clearTimeout(handle)
   }, [draft, draftPersistenceScope])
 
+  // Flush any pending debounced draft write when leaving a session scope or
+  // unmounting, so the departing session's latest text is always persisted.
+  useEffect(
+    () => () => {
+      const pending = pendingDraftPersistRef.current
+
+      if (pending) {
+        pendingDraftPersistRef.current = null
+        writePersistedComposerDraft(pending.scope, pending.value)
+      }
+    },
+    [draftPersistenceScope]
+  )
+
   const beginQueuedEdit = (entry: QueuedPromptEntry) => {
     if (!activeQueueSessionKey || queueEdit) {
       return
diff --git a/scripts/release.py b/scripts/release.py
index 68ad134d6cdb..10ed7b658a2f 100755
--- a/scripts/release.py
+++ b/scripts/release.py
@@ -76,6 +76,7 @@ AUTHOR_MAP = {
     "290859878+synapsesx@users.noreply.github.com": "synapsesx",
     "dirtyren@users.noreply.github.com": "dirtyren",
     "mharris@parallel.ai": "NormallyGaussian",
+    "roger@roger.local": "mollusk",
     "ted.malone@outlook.com": "temalo",
     "adityamalik2833@gmail.com": "alarcritty",
     "islam666@users.noreply.github.com": "islam666",

From 914befa9aaae46f2709373bc3d7352e813a18c54 Mon Sep 17 00:00:00 2001
From: Teknium <127238744+teknium1@users.noreply.github.com>
Date: Wed, 10 Jun 2026 15:36:51 -0700
Subject: [PATCH 10/28] feat(dashboard): profile-scoped skills & toolsets
 management
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

'Set as active' on the Profiles page only flips the sticky active_profile
file (future CLI/gateway runs) — it never retargets the running dashboard
process. The skills/toolsets endpoints called bare load_config()/
save_config(), so after 'activating' a profile in the web UI, deactivating
a skill silently wrote into the dashboard's own profile and the activated
profile was untouched.

Backend:
- _profile_scope() context manager on the skills/toolsets endpoints:
  context-local HERMES_HOME override for call-time config resolution +
  cron-style locked swap of tools.skills_tool's import-time SKILLS_DIR
- profile param on /api/skills, /api/skills/toggle, /api/tools/toolsets*
  (list/toggle/config/provider/env), hub sources/search installed-state
- hub install/uninstall/update spawn 'hermes -p <profile> skills ...' so
  the child rebinds skills_hub.SKILLS_DIR at import (the override cannot
  reach import-time globals); profile validated -> 404/400 before spawn

Frontend:
- Skills page: profile selector (deep-linkable /skills?profile=<name>),
  amber banner naming the managed profile, threaded through skill toggles,
  toolset drawer, and hub browser
- Profiles page: 'Manage skills & tools' action per card; 'Set as active'
  toast now says it applies to new CLI/gateway runs only

Omitted profile keeps legacy behavior (dashboard's own profile).
---
 hermes_cli/web_server.py                      | 327 ++++++++++++------
 .../test_web_server_skills_profiles.py        | 210 +++++++++++
 web/src/components/ToolsetConfigDrawer.tsx    |  15 +-
 web/src/i18n/en.ts                            |   4 +
 web/src/i18n/types.ts                         |   6 +
 web/src/lib/api.ts                            |  66 ++--
 web/src/pages/ProfilesPage.tsx                |  34 +-
 web/src/pages/SkillsPage.tsx                  | 152 +++++++-
 8 files changed, 662 insertions(+), 152 deletions(-)
 create mode 100644 tests/hermes_cli/test_web_server_skills_profiles.py

diff --git a/hermes_cli/web_server.py b/hermes_cli/web_server.py
index e1f1c62051df..f7cc695874ad 100644
--- a/hermes_cli/web_server.py
+++ b/hermes_cli/web_server.py
@@ -9,7 +9,7 @@ Usage:
     python -m hermes_cli.main web --port 8080
 """
 
-from contextlib import asynccontextmanager
+from contextlib import asynccontextmanager, contextmanager
 
 import asyncio
 import base64
@@ -7373,6 +7373,24 @@ async def prune_checkpoints():
 
 class SkillInstallRequest(BaseModel):
     identifier: str
+    profile: Optional[str] = None
+
+
+def _profile_cli_args(profile: Optional[str]) -> List[str]:
+    """Return ``["-p", <name>]`` for a validated non-default profile.
+
+    Hub install/uninstall/update run in a fresh ``hermes`` subprocess, and
+    ``_apply_profile_override()`` reads ``-p`` from argv in the child — the
+    only mechanism that reaches import-time-bound globals like
+    ``skills_hub.SKILLS_DIR``. Empty/"current" means the dashboard's own
+    profile (no args, legacy behavior).
+    """
+    requested = (profile or "").strip()
+    if not requested or requested.lower() == "current":
+        return []
+    from hermes_cli import profiles as profiles_mod
+    _resolve_profile_dir(requested)
+    return ["-p", profiles_mod.normalize_profile_name(requested)]
 
 
 @app.post("/api/skills/hub/install")
@@ -7381,7 +7399,12 @@ async def install_skill_hub(body: SkillInstallRequest):
     if not identifier:
         raise HTTPException(status_code=400, detail="identifier is required")
     try:
-        proc = _spawn_hermes_action(["skills", "install", identifier], "skills-install")
+        proc = _spawn_hermes_action(
+            _profile_cli_args(body.profile) + ["skills", "install", identifier],
+            "skills-install",
+        )
+    except HTTPException:
+        raise
     except Exception as exc:
         _log.exception("Failed to spawn skills install")
         raise HTTPException(status_code=500, detail=f"Failed to install skill: {exc}")
@@ -7390,6 +7413,7 @@ async def install_skill_hub(body: SkillInstallRequest):
 
 class SkillUninstallRequest(BaseModel):
     name: str
+    profile: Optional[str] = None
 
 
 @app.post("/api/skills/hub/uninstall")
@@ -7398,17 +7422,31 @@ async def uninstall_skill_hub(body: SkillUninstallRequest):
     if not name:
         raise HTTPException(status_code=400, detail="name is required")
     try:
-        proc = _spawn_hermes_action(["skills", "uninstall", name, "--yes"], "skills-uninstall")
+        proc = _spawn_hermes_action(
+            _profile_cli_args(body.profile) + ["skills", "uninstall", name, "--yes"],
+            "skills-uninstall",
+        )
+    except HTTPException:
+        raise
     except Exception as exc:
         _log.exception("Failed to spawn skills uninstall")
         raise HTTPException(status_code=500, detail=f"Failed to uninstall skill: {exc}")
     return {"ok": True, "pid": proc.pid, "name": "skills-uninstall"}
 
 
+class SkillsUpdateRequest(BaseModel):
+    profile: Optional[str] = None
+
+
 @app.post("/api/skills/hub/update")
-async def update_skills_hub():
+async def update_skills_hub(body: Optional[SkillsUpdateRequest] = None):
     try:
-        proc = _spawn_hermes_action(["skills", "update"], "skills-update")
+        profile = body.profile if body else None
+        proc = _spawn_hermes_action(
+            _profile_cli_args(profile) + ["skills", "update"], "skills-update"
+        )
+    except HTTPException:
+        raise
     except Exception as exc:
         _log.exception("Failed to spawn skills update")
         raise HTTPException(status_code=500, detail=f"Failed to update skills: {exc}")
@@ -7443,17 +7481,25 @@ def _skill_meta_to_payload(m) -> dict:
     }
 
 
-def _installed_hub_identifiers() -> dict:
+def _installed_hub_identifiers(profile: Optional[str] = None) -> dict:
     """Map identifier -> installed lock entry for hub-installed skills.
 
-    Lets the UI mark search results that are already installed.  Best-effort:
-    returns an empty dict if the lock file can't be read.
+    Lets the UI mark search results that are already installed.  Scoped to
+    ``profile``'s skills/.hub/lock.json when provided (HubLockFile takes an
+    explicit path, sidestepping the import-time LOCK_FILE binding).
+    Best-effort: returns an empty dict if the lock file can't be read.
     """
     try:
         from tools.skills_hub import HubLockFile
 
+        requested = (profile or "").strip()
+        if requested and requested.lower() != "current":
+            profile_dir = _resolve_profile_dir(requested)
+            lock = HubLockFile(profile_dir / "skills" / ".hub" / "lock.json")
+        else:
+            lock = HubLockFile()
         out = {}
-        for entry in HubLockFile().list_installed():
+        for entry in lock.list_installed():
             ident = entry.get("identifier")
             if ident:
                 out[ident] = {
@@ -7467,13 +7513,14 @@ def _installed_hub_identifiers() -> dict:
 
 
 @app.get("/api/skills/hub/sources")
-async def list_skills_hub_sources():
+async def list_skills_hub_sources(profile: Optional[str] = None):
     """List the configured skill-hub sources and installed-skill provenance.
 
     Gives the dashboard something to show BEFORE a search runs — which hubs
     are wired up, their trust tier, and a set of featured skills pulled from
     the centralized index (zero extra API calls).  Without this the Browse-hub
     tab is a blank page with no indication it's even connected to anything.
+    ``profile`` scopes the installed-skill provenance to that profile.
     """
 
     def _run():
@@ -7514,18 +7561,22 @@ async def list_skills_hub_sources():
             "sources": out,
             "index_available": index_available,
             "featured": featured,
-            "installed": _installed_hub_identifiers(),
+            "installed": _installed_hub_identifiers(profile),
         }
 
     try:
         return await asyncio.to_thread(_run)
+    except HTTPException:
+        raise
     except Exception as exc:
         _log.exception("skills hub sources listing failed")
         raise HTTPException(status_code=502, detail=f"Hub sources failed: {exc}")
 
 
 @app.get("/api/skills/hub/search")
-async def search_skills_hub(q: str = "", source: str = "all", limit: int = 20):
+async def search_skills_hub(
+    q: str = "", source: str = "all", limit: int = 20, profile: Optional[str] = None
+):
     """Search the skill hub across all configured sources.
 
     Network-bound (parallel source search); runs in a thread so the FastAPI
@@ -7560,11 +7611,13 @@ async def search_skills_hub(q: str = "", source: str = "all", limit: int = 20):
             "results": [_skill_meta_to_payload(m) for m in deduped],
             "source_counts": source_counts,
             "timed_out": timed_out,
-            "installed": _installed_hub_identifiers(),
+            "installed": _installed_hub_identifiers(profile),
         }
 
     try:
         return await asyncio.to_thread(_run)
+    except HTTPException:
+        raise
     except Exception as exc:
         _log.exception("skills hub search failed")
         raise HTTPException(status_code=502, detail=f"Hub search failed: {exc}")
@@ -8333,21 +8386,75 @@ async def describe_profile_auto_endpoint(name: str, body: ProfileDescribeAuto):
 
 # ---------------------------------------------------------------------------
 # Skills & Tools endpoints
+#
+# Every read/write below accepts an optional ``profile`` query param so the
+# dashboard can manage ANY profile's skills/toolsets, not just the profile
+# the dashboard process happens to be running under. Without this, "Set as
+# active" on the Profiles page (which only flips the sticky ``active_profile``
+# file for FUTURE CLI/gateway invocations) misled users into thinking skill
+# toggles would land in the activated profile — they silently wrote into the
+# dashboard's own config instead. See _profile_scope() for the mechanism.
 # ---------------------------------------------------------------------------
 
 
+_SKILLS_PROFILE_LOCK = threading.RLock()
+
+
+@contextmanager
+def _profile_scope(profile: Optional[str]):
+    """Scope config + skill-directory resolution to ``profile`` for one request.
+
+    Two seams must be redirected for skills/toolsets endpoints:
+
+    1. ``load_config``/``save_config`` resolve ``get_hermes_home()`` at call
+       time — the context-local override from ``set_hermes_home_override``
+       reaches them (same pattern as ``_write_profile_model``).
+    2. ``tools.skills_tool`` binds ``SKILLS_DIR`` at import time, so the
+       override CANNOT reach it. Like ``_call_cron_for_profile`` does for
+       cron's module globals, temporarily retarget it under a lock and
+       restore it immediately after.
+
+    ``profile`` of None/""/"current" means "the dashboard's own profile" —
+    a no-op scope, preserving existing behavior for old clients.
+    """
+    requested = (profile or "").strip()
+    if not requested or requested.lower() == "current":
+        yield None
+        return
+
+    profile_dir = _resolve_profile_dir(requested)
+
+    from hermes_constants import set_hermes_home_override, reset_hermes_home_override
+    from tools import skills_tool as _skills_tool
+
+    token = set_hermes_home_override(str(profile_dir))
+    with _SKILLS_PROFILE_LOCK:
+        old_home = _skills_tool.HERMES_HOME
+        old_skills_dir = _skills_tool.SKILLS_DIR
+        _skills_tool.HERMES_HOME = profile_dir
+        _skills_tool.SKILLS_DIR = profile_dir / "skills"
+        try:
+            yield profile_dir
+        finally:
+            _skills_tool.HERMES_HOME = old_home
+            _skills_tool.SKILLS_DIR = old_skills_dir
+            reset_hermes_home_override(token)
+
+
 class SkillToggle(BaseModel):
     name: str
     enabled: bool
+    profile: Optional[str] = None
 
 
 @app.get("/api/skills")
-async def get_skills():
+async def get_skills(profile: Optional[str] = None):
     from tools.skills_tool import _find_all_skills
     from hermes_cli.skills_config import get_disabled_skills
-    config = load_config()
-    disabled = get_disabled_skills(config)
-    skills = _find_all_skills(skip_disabled=True)
+    with _profile_scope(profile):
+        config = load_config()
+        disabled = get_disabled_skills(config)
+        skills = _find_all_skills(skip_disabled=True)
     for s in skills:
         s["enabled"] = s["name"] not in disabled
     return skills
@@ -8356,18 +8463,19 @@ async def get_skills():
 @app.put("/api/skills/toggle")
 async def toggle_skill(body: SkillToggle):
     from hermes_cli.skills_config import get_disabled_skills, save_disabled_skills
-    config = load_config()
-    disabled = get_disabled_skills(config)
-    if body.enabled:
-        disabled.discard(body.name)
-    else:
-        disabled.add(body.name)
-    save_disabled_skills(config, disabled)
+    with _profile_scope(body.profile):
+        config = load_config()
+        disabled = get_disabled_skills(config)
+        if body.enabled:
+            disabled.discard(body.name)
+        else:
+            disabled.add(body.name)
+        save_disabled_skills(config, disabled)
     return {"ok": True, "name": body.name, "enabled": body.enabled}
 
 
 @app.get("/api/tools/toolsets")
-async def get_toolsets():
+async def get_toolsets(profile: Optional[str] = None):
     from hermes_cli.tools_config import (
         _get_effective_configurable_toolsets,
         _get_platform_tools,
@@ -8376,12 +8484,13 @@ async def get_toolsets():
     )
     from toolsets import resolve_toolset
 
-    config = load_config()
-    enabled_toolsets = _get_platform_tools(
-        config,
-        "cli",
-        include_default_mcp_servers=False,
-    )
+    with _profile_scope(profile):
+        config = load_config()
+        enabled_toolsets = _get_platform_tools(
+            config,
+            "cli",
+            include_default_mcp_servers=False,
+        )
     result = []
     for name, label, desc in _get_effective_configurable_toolsets():
         try:
@@ -8403,6 +8512,7 @@ async def get_toolsets():
 
 class ToolsetToggle(BaseModel):
     enabled: bool
+    profile: Optional[str] = None
 
 
 @app.put("/api/tools/toolsets/{name}")
@@ -8411,7 +8521,8 @@ async def toggle_toolset(name: str, body: ToolsetToggle):
 
     Persists to ``platform_toolsets.cli`` via the same ``_save_platform_tools``
     helper the CLI ``hermes tools`` picker uses, so the GUI and CLI stay in
-    lockstep. Returns 400 for unknown toolset keys.
+    lockstep. Scoped to ``body.profile`` when provided. Returns 400 for
+    unknown toolset keys.
     """
     from hermes_cli.tools_config import (
         _get_effective_configurable_toolsets,
@@ -8423,20 +8534,21 @@ async def toggle_toolset(name: str, body: ToolsetToggle):
     if name not in valid:
         raise HTTPException(status_code=400, detail=f"Unknown toolset: {name}")
 
-    config = load_config()
-    enabled = set(
-        _get_platform_tools(config, "cli", include_default_mcp_servers=False)
-    )
-    if body.enabled:
-        enabled.add(name)
-    else:
-        enabled.discard(name)
-    _save_platform_tools(config, "cli", enabled)
+    with _profile_scope(body.profile):
+        config = load_config()
+        enabled = set(
+            _get_platform_tools(config, "cli", include_default_mcp_servers=False)
+        )
+        if body.enabled:
+            enabled.add(name)
+        else:
+            enabled.discard(name)
+        _save_platform_tools(config, "cli", enabled)
     return {"ok": True, "name": name, "enabled": body.enabled}
 
 
 @app.get("/api/tools/toolsets/{name}/config")
-async def get_toolset_config(name: str):
+async def get_toolset_config(name: str, profile: Optional[str] = None):
     """Return the provider matrix + key status for a toolset's config panel.
 
     Surfaces the same provider rows the CLI ``hermes tools`` picker shows
@@ -8457,38 +8569,39 @@ async def get_toolset_config(name: str):
     if name not in valid:
         raise HTTPException(status_code=400, detail=f"Unknown toolset: {name}")
 
-    config = load_config()
-    cat = TOOL_CATEGORIES.get(name)
-    providers = []
-    active_provider = None
-    if cat:
-        for prov in _visible_providers(cat, config, force_fresh=True):
-            env_vars = [
-                {
-                    "key": e["key"],
-                    "prompt": e.get("prompt", e["key"]),
-                    "url": e.get("url"),
-                    "default": e.get("default"),
-                    "is_set": bool(get_env_value(e["key"])),
-                }
-                for e in prov.get("env_vars", [])
-            ]
-            # Surface the same active-provider determination the CLI picker
-            # uses (``_is_provider_active``) so the GUI highlights the provider
-            # actually written to config (e.g. web.backend), not just the first
-            # keyless one in the list.
-            is_active = _is_provider_active(prov, config, force_fresh=True)
-            if is_active and active_provider is None:
-                active_provider = prov["name"]
-            providers.append({
-                "name": prov["name"],
-                "badge": prov.get("badge", ""),
-                "tag": prov.get("tag", ""),
-                "env_vars": env_vars,
-                "post_setup": prov.get("post_setup"),
-                "requires_nous_auth": bool(prov.get("requires_nous_auth")),
-                "is_active": is_active,
-            })
+    with _profile_scope(profile):
+        config = load_config()
+        cat = TOOL_CATEGORIES.get(name)
+        providers = []
+        active_provider = None
+        if cat:
+            for prov in _visible_providers(cat, config, force_fresh=True):
+                env_vars = [
+                    {
+                        "key": e["key"],
+                        "prompt": e.get("prompt", e["key"]),
+                        "url": e.get("url"),
+                        "default": e.get("default"),
+                        "is_set": bool(get_env_value(e["key"])),
+                    }
+                    for e in prov.get("env_vars", [])
+                ]
+                # Surface the same active-provider determination the CLI picker
+                # uses (``_is_provider_active``) so the GUI highlights the provider
+                # actually written to config (e.g. web.backend), not just the first
+                # keyless one in the list.
+                is_active = _is_provider_active(prov, config, force_fresh=True)
+                if is_active and active_provider is None:
+                    active_provider = prov["name"]
+                providers.append({
+                    "name": prov["name"],
+                    "badge": prov.get("badge", ""),
+                    "tag": prov.get("tag", ""),
+                    "env_vars": env_vars,
+                    "post_setup": prov.get("post_setup"),
+                    "requires_nous_auth": bool(prov.get("requires_nous_auth")),
+                    "is_active": is_active,
+                })
     return {
         "name": name,
         "has_category": cat is not None,
@@ -8499,6 +8612,7 @@ async def get_toolset_config(name: str):
 
 class ToolsetProviderSelect(BaseModel):
     provider: str
+    profile: Optional[str] = None
 
 
 @app.put("/api/tools/toolsets/{name}/provider")
@@ -8520,17 +8634,19 @@ async def select_toolset_provider(name: str, body: ToolsetProviderSelect):
     if name not in valid:
         raise HTTPException(status_code=400, detail=f"Unknown toolset: {name}")
 
-    config = load_config()
-    try:
-        apply_provider_selection(name, body.provider, config)
-    except KeyError as exc:
-        raise HTTPException(status_code=400, detail=str(exc).strip('"'))
-    save_config(config)
+    with _profile_scope(body.profile):
+        config = load_config()
+        try:
+            apply_provider_selection(name, body.provider, config)
+        except KeyError as exc:
+            raise HTTPException(status_code=400, detail=str(exc).strip('"'))
+        save_config(config)
     return {"ok": True, "name": name, "provider": body.provider}
 
 
 class ToolsetEnvUpdate(BaseModel):
     env: Dict[str, str]
+    profile: Optional[str] = None
 
 
 @app.put("/api/tools/toolsets/{name}/env")
@@ -8556,34 +8672,35 @@ async def save_toolset_env(name: str, body: ToolsetEnvUpdate):
     if name not in valid_ts:
         raise HTTPException(status_code=400, detail=f"Unknown toolset: {name}")
 
-    config = load_config()
-    cat = TOOL_CATEGORIES.get(name)
-    allowed: set[str] = set()
-    if cat:
-        for prov in _visible_providers(cat, config, force_fresh=True):
-            for e in prov.get("env_vars", []):
-                allowed.add(e["key"])
+    with _profile_scope(body.profile):
+        config = load_config()
+        cat = TOOL_CATEGORIES.get(name)
+        allowed: set[str] = set()
+        if cat:
+            for prov in _visible_providers(cat, config, force_fresh=True):
+                for e in prov.get("env_vars", []):
+                    allowed.add(e["key"])
 
-    unknown = [k for k in body.env if k not in allowed]
-    if unknown:
-        raise HTTPException(
-            status_code=400,
-            detail=f"Unknown env var(s) for toolset {name}: {', '.join(sorted(unknown))}",
-        )
+        unknown = [k for k in body.env if k not in allowed]
+        if unknown:
+            raise HTTPException(
+                status_code=400,
+                detail=f"Unknown env var(s) for toolset {name}: {', '.join(sorted(unknown))}",
+            )
 
-    saved: List[str] = []
-    skipped: List[str] = []
-    for key, value in body.env.items():
-        if value and value.strip():
-            try:
-                save_env_value(key, value.strip())
-            except ValueError as exc:
-                raise HTTPException(status_code=400, detail=str(exc))
-            saved.append(key)
-        else:
-            skipped.append(key)
+        saved: List[str] = []
+        skipped: List[str] = []
+        for key, value in body.env.items():
+            if value and value.strip():
+                try:
+                    save_env_value(key, value.strip())
+                except ValueError as exc:
+                    raise HTTPException(status_code=400, detail=str(exc))
+                saved.append(key)
+            else:
+                skipped.append(key)
 
-    status = {k: bool(get_env_value(k)) for k in allowed}
+        status = {k: bool(get_env_value(k)) for k in allowed}
     return {"ok": True, "name": name, "saved": saved, "skipped": skipped, "is_set": status}
 
 
diff --git a/tests/hermes_cli/test_web_server_skills_profiles.py b/tests/hermes_cli/test_web_server_skills_profiles.py
new file mode 100644
index 000000000000..9a131bbb2460
--- /dev/null
+++ b/tests/hermes_cli/test_web_server_skills_profiles.py
@@ -0,0 +1,210 @@
+"""Regression tests for dashboard profile-scoped skills/toolsets management.
+
+"Set as active" on the Profiles page only flips the sticky ``active_profile``
+file (future CLI/gateway runs) — it never retargets the running dashboard
+process. Before the ``profile`` parameter existed, toggling a skill after
+"activating" a profile silently wrote into the dashboard's own config.
+These tests pin the new behavior: reads and writes land in the REQUESTED
+profile's HERMES_HOME, and the dashboard's own profile stays untouched.
+"""
+import pytest
+import yaml
+
+
+def _write_skill(skills_dir, name, description="test skill"):
+    d = skills_dir / name
+    d.mkdir(parents=True, exist_ok=True)
+    (d / "SKILL.md").write_text(
+        f"---\nname: {name}\ndescription: {description}\n---\n\n# {name}\n",
+        encoding="utf-8",
+    )
+
+
+@pytest.fixture
+def isolated_profiles(tmp_path, monkeypatch, _isolate_hermes_home):
+    """Isolated default home + one named profile, each with its own skills."""
+    from hermes_constants import get_hermes_home
+    from hermes_cli import profiles
+
+    default_home = get_hermes_home()
+    profiles_root = default_home / "profiles"
+    worker_home = profiles_root / "worker_alpha"
+    for home in (default_home, worker_home):
+        (home / "skills").mkdir(parents=True, exist_ok=True)
+        (home / "config.yaml").write_text("{}\n", encoding="utf-8")
+
+    _write_skill(default_home / "skills", "dashboard-skill")
+    _write_skill(worker_home / "skills", "worker-skill")
+
+    monkeypatch.setattr(profiles, "_get_default_hermes_home", lambda: default_home)
+    monkeypatch.setattr(profiles, "_get_profiles_root", lambda: profiles_root)
+    return {"default": default_home, "worker_alpha": worker_home}
+
+
+@pytest.fixture
+def client(monkeypatch, isolated_profiles):
+    try:
+        from starlette.testclient import TestClient
+    except ImportError:
+        pytest.skip("fastapi/starlette not installed")
+
+    import hermes_state
+    from hermes_constants import get_hermes_home
+    from hermes_cli.web_server import app, _SESSION_HEADER_NAME, _SESSION_TOKEN
+
+    monkeypatch.setattr(hermes_state, "DEFAULT_DB_PATH", get_hermes_home() / "state.db")
+    c = TestClient(app)
+    c.headers[_SESSION_HEADER_NAME] = _SESSION_TOKEN
+    return c
+
+
+def _load_cfg(home):
+    return yaml.safe_load((home / "config.yaml").read_text()) or {}
+
+
+class TestProfileScopedSkills:
+    def test_skills_list_scopes_to_requested_profile(self, client, isolated_profiles):
+        resp = client.get("/api/skills", params={"profile": "worker_alpha"})
+        assert resp.status_code == 200
+        names = {s["name"] for s in resp.json()}
+        assert "worker-skill" in names
+        assert "dashboard-skill" not in names
+
+    def test_skills_list_without_profile_uses_dashboard_home(
+        self, client, isolated_profiles
+    ):
+        resp = client.get("/api/skills")
+        assert resp.status_code == 200
+        names = {s["name"] for s in resp.json()}
+        assert "dashboard-skill" in names
+        assert "worker-skill" not in names
+
+    def test_toggle_writes_into_target_profile_only(self, client, isolated_profiles):
+        resp = client.put(
+            "/api/skills/toggle",
+            json={"name": "worker-skill", "enabled": False, "profile": "worker_alpha"},
+        )
+        assert resp.status_code == 200
+        assert resp.json() == {"ok": True, "name": "worker-skill", "enabled": False}
+
+        worker_cfg = _load_cfg(isolated_profiles["worker_alpha"])
+        assert "worker-skill" in worker_cfg.get("skills", {}).get("disabled", [])
+        # The dashboard's own config must stay untouched — this was the bug.
+        default_cfg = _load_cfg(isolated_profiles["default"])
+        assert "worker-skill" not in default_cfg.get("skills", {}).get("disabled", [])
+
+    def test_toggle_reenable_round_trip(self, client, isolated_profiles):
+        for enabled in (False, True):
+            client.put(
+                "/api/skills/toggle",
+                json={
+                    "name": "worker-skill",
+                    "enabled": enabled,
+                    "profile": "worker_alpha",
+                },
+            )
+        worker_cfg = _load_cfg(isolated_profiles["worker_alpha"])
+        assert "worker-skill" not in worker_cfg.get("skills", {}).get("disabled", [])
+
+    def test_unknown_profile_returns_404(self, client, isolated_profiles):
+        resp = client.get("/api/skills", params={"profile": "no_such_profile"})
+        assert resp.status_code == 404
+
+    def test_invalid_profile_name_returns_400(self, client, isolated_profiles):
+        resp = client.get("/api/skills", params={"profile": "Bad Name!"})
+        assert resp.status_code == 400
+
+    def test_scope_restores_module_globals(self, client, isolated_profiles):
+        """The SKILLS_DIR swap is per-request; the module global must be
+        restored even after a scoped call (cron-style locked swap)."""
+        import tools.skills_tool as skills_tool
+
+        before = skills_tool.SKILLS_DIR
+        client.get("/api/skills", params={"profile": "worker_alpha"})
+        assert skills_tool.SKILLS_DIR == before
+
+
+class TestProfileScopedToolsets:
+    def test_toolset_toggle_scopes_to_profile(self, client, isolated_profiles):
+        resp = client.put(
+            "/api/tools/toolsets/x_search",
+            json={"enabled": True, "profile": "worker_alpha"},
+        )
+        assert resp.status_code == 200
+
+        worker_cfg = _load_cfg(isolated_profiles["worker_alpha"])
+        assert "x_search" in worker_cfg.get("platform_toolsets", {}).get("cli", [])
+        default_cfg = _load_cfg(isolated_profiles["default"])
+        assert "x_search" not in default_cfg.get("platform_toolsets", {}).get("cli", [])
+
+        listing = client.get(
+            "/api/tools/toolsets", params={"profile": "worker_alpha"}
+        ).json()
+        assert {t["name"]: t for t in listing}["x_search"]["enabled"] is True
+        # Unscoped listing reflects the dashboard's own (untouched) config.
+        listing = client.get("/api/tools/toolsets").json()
+        assert {t["name"]: t for t in listing}["x_search"]["enabled"] is False
+
+    def test_toolset_toggle_unknown_profile_404(self, client, isolated_profiles):
+        resp = client.put(
+            "/api/tools/toolsets/x_search",
+            json={"enabled": True, "profile": "ghost"},
+        )
+        assert resp.status_code == 404
+
+
+class TestProfileScopedHubActions:
+    def test_hub_install_spawns_with_profile_flag(
+        self, client, isolated_profiles, monkeypatch
+    ):
+        """Hub installs must go through a fresh ``hermes -p <profile>``
+        subprocess — the in-process scope can't reach skills_hub's
+        import-time SKILLS_DIR binding."""
+        import hermes_cli.web_server as web_server
+
+        calls = []
+
+        class _FakeProc:
+            pid = 4242
+
+        def _fake_spawn(subcommand, name):
+            calls.append((list(subcommand), name))
+            return _FakeProc()
+
+        monkeypatch.setattr(web_server, "_spawn_hermes_action", _fake_spawn)
+        resp = client.post(
+            "/api/skills/hub/install",
+            json={"identifier": "official/demo", "profile": "worker_alpha"},
+        )
+        assert resp.status_code == 200
+        assert calls == [
+            (["-p", "worker_alpha", "skills", "install", "official/demo"], "skills-install")
+        ]
+
+    def test_hub_install_without_profile_keeps_legacy_argv(
+        self, client, isolated_profiles, monkeypatch
+    ):
+        import hermes_cli.web_server as web_server
+
+        calls = []
+
+        class _FakeProc:
+            pid = 4242
+
+        monkeypatch.setattr(
+            web_server,
+            "_spawn_hermes_action",
+            lambda subcommand, name: calls.append(list(subcommand)) or _FakeProc(),
+        )
+        resp = client.post(
+            "/api/skills/hub/install", json={"identifier": "official/demo"}
+        )
+        assert resp.status_code == 200
+        assert calls == [["skills", "install", "official/demo"]]
+
+    def test_hub_install_unknown_profile_404(self, client, isolated_profiles):
+        resp = client.post(
+            "/api/skills/hub/install",
+            json={"identifier": "official/demo", "profile": "ghost"},
+        )
+        assert resp.status_code == 404
diff --git a/web/src/components/ToolsetConfigDrawer.tsx b/web/src/components/ToolsetConfigDrawer.tsx
index 42e58d589f5b..5bbcba618662 100644
--- a/web/src/components/ToolsetConfigDrawer.tsx
+++ b/web/src/components/ToolsetConfigDrawer.tsx
@@ -20,6 +20,9 @@ import { cn, themedBody } from "@/lib/utils";
 interface Props {
   /** The toolset whose backends are being configured. */
   toolset: ToolsetInfo;
+  /** Optional profile to scope config reads/writes to (Skills page profile
+   *  selector). Omitted = the dashboard process's own profile. */
+  profile?: string;
   onClose: () => void;
   /** Called after a toggle/provider/key change so the parent grid refreshes. */
   onChanged: () => void;
@@ -31,7 +34,7 @@ interface Props {
  * the toolset on/off, pick a provider, enter API keys, and run a provider's
  * post-setup install hook (npm/pip/binary) with a live log tail.
  */
-export function ToolsetConfigDrawer({ toolset, onClose, onChanged }: Props) {
+export function ToolsetConfigDrawer({ toolset, profile, onClose, onChanged }: Props) {
   const { toast, showToast } = useToast();
   const [config, setConfig] = useState<ToolsetConfig | null>(null);
   const [loading, setLoading] = useState(true);
@@ -60,7 +63,7 @@ export function ToolsetConfigDrawer({ toolset, onClose, onChanged }: Props) {
     // react-hooks/set-state-in-effect — setState only fires inside the
     // async .then/.catch/.finally callbacks.
     return api
-      .getToolsetConfig(toolset.name)
+      .getToolsetConfig(toolset.name, profile)
       .then((cfg) => {
         setConfig(cfg);
         setActiveProvider(cfg.active_provider);
@@ -72,7 +75,7 @@ export function ToolsetConfigDrawer({ toolset, onClose, onChanged }: Props) {
       })
       .catch(() => showToast("Failed to load toolset config", "error"))
       .finally(() => setLoading(false));
-  }, [toolset.name, showToast]);
+  }, [toolset.name, profile, showToast]);
 
   useEffect(() => {
     void loadConfig();
@@ -121,7 +124,7 @@ export function ToolsetConfigDrawer({ toolset, onClose, onChanged }: Props) {
   const handleToggle = async (next: boolean) => {
     setToggling(true);
     try {
-      await api.toggleToolset(toolset.name, next);
+      await api.toggleToolset(toolset.name, next, profile);
       setEnabled(next);
       showToast(
         `${toolset.label || toolset.name} ${next ? "enabled" : "disabled"}`,
@@ -138,7 +141,7 @@ export function ToolsetConfigDrawer({ toolset, onClose, onChanged }: Props) {
   const handleSelectProvider = async (provider: ToolsetProvider) => {
     setSelecting(provider.name);
     try {
-      await api.selectToolsetProvider(toolset.name, provider.name);
+      await api.selectToolsetProvider(toolset.name, provider.name, profile);
       setActiveProvider(provider.name);
       showToast(`Provider set to ${provider.name}`, "success");
       onChanged();
@@ -164,7 +167,7 @@ export function ToolsetConfigDrawer({ toolset, onClose, onChanged }: Props) {
     }
     setSavingProvider(provider.name);
     try {
-      const res = await api.saveToolsetEnv(toolset.name, env);
+      const res = await api.saveToolsetEnv(toolset.name, env, profile);
       setIsSet((prev) => ({ ...prev, ...res.is_set }));
       // Clear saved drafts so the inputs reset to the "saved" placeholder.
       setDrafts((prev) => {
diff --git a/web/src/i18n/en.ts b/web/src/i18n/en.ts
index 4f593487fd39..39cf80d6995e 100644
--- a/web/src/i18n/en.ts
+++ b/web/src/i18n/en.ts
@@ -408,6 +408,10 @@ export const en: Translations = {
     setupNeeded: "Setup needed",
     disabledForCli: "Disabled for CLI",
     more: "+{count} more",
+    profileSelector: "Profile",
+    currentProfile: "current ({name})",
+    managingProfile:
+      "Managing profile \u201c{name}\u201d — toggles apply to that profile, not this dashboard\u2019s.",
   },
 
   config: {
diff --git a/web/src/i18n/types.ts b/web/src/i18n/types.ts
index 14bc41f2d085..cac5688bdc6d 100644
--- a/web/src/i18n/types.ts
+++ b/web/src/i18n/types.ts
@@ -404,6 +404,8 @@ export interface Translations {
     modelSaved?: string;
     modelSelect?: string;
     actions?: string;
+    manageSkills?: string;
+    activeSetHint?: string;
   };
 
   // ── Skills page ──
@@ -425,6 +427,10 @@ export interface Translations {
     setupNeeded: string;
     disabledForCli: string;
     more: string;
+    /** Optional — fall back to English literals until translated. */
+    profileSelector?: string;
+    currentProfile?: string;
+    managingProfile?: string;
   };
 
   // ── Config page ──
diff --git a/web/src/lib/api.ts b/web/src/lib/api.ts
index 37a8f15eba26..7cde6eb78f95 100644
--- a/web/src/lib/api.ts
+++ b/web/src/lib/api.ts
@@ -249,6 +249,14 @@ export async function buildWsUrl(
   return `${proto}//${window.location.host}${BASE}${path}?${qs}`;
 }
 
+/** Build a ``?profile=<name>`` query suffix, or "" when unset.
+ *
+ * Used by the skills/toolsets endpoints so the dashboard can manage a
+ * profile other than the one the server process runs under. */
+function profileQuery(profile?: string): string {
+  return profile ? `?profile=${encodeURIComponent(profile)}` : "";
+}
+
 export const api = {
   getStatus: () => fetchJSON<StatusResponse>("/api/status"),
   /**
@@ -542,43 +550,49 @@ export const api = {
     ),
 
   // Skills & Toolsets
-  getSkills: () => fetchJSON<SkillInfo[]>("/api/skills"),
-  toggleSkill: (name: string, enabled: boolean) =>
+  //
+  // All calls accept an optional ``profile`` so the Skills page can manage
+  // any profile's skills/toolsets — not just the one the dashboard process
+  // runs under. Omitted/empty profile = the dashboard's own profile.
+  getSkills: (profile?: string) =>
+    fetchJSON<SkillInfo[]>(`/api/skills${profileQuery(profile)}`),
+  toggleSkill: (name: string, enabled: boolean, profile?: string) =>
     fetchJSON<{ ok: boolean }>("/api/skills/toggle", {
       method: "PUT",
       headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ name, enabled }),
+      body: JSON.stringify({ name, enabled, profile: profile || undefined }),
     }),
-  getToolsets: () => fetchJSON<ToolsetInfo[]>("/api/tools/toolsets"),
-  toggleToolset: (name: string, enabled: boolean) =>
+  getToolsets: (profile?: string) =>
+    fetchJSON<ToolsetInfo[]>(`/api/tools/toolsets${profileQuery(profile)}`),
+  toggleToolset: (name: string, enabled: boolean, profile?: string) =>
     fetchJSON<{ ok: boolean; name: string; enabled: boolean }>(
       `/api/tools/toolsets/${encodeURIComponent(name)}`,
       {
         method: "PUT",
         headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ enabled }),
+        body: JSON.stringify({ enabled, profile: profile || undefined }),
       },
     ),
-  getToolsetConfig: (name: string) =>
+  getToolsetConfig: (name: string, profile?: string) =>
     fetchJSON<ToolsetConfig>(
-      `/api/tools/toolsets/${encodeURIComponent(name)}/config`,
+      `/api/tools/toolsets/${encodeURIComponent(name)}/config${profileQuery(profile)}`,
     ),
-  selectToolsetProvider: (name: string, provider: string) =>
+  selectToolsetProvider: (name: string, provider: string, profile?: string) =>
     fetchJSON<{ ok: boolean; name: string; provider: string }>(
       `/api/tools/toolsets/${encodeURIComponent(name)}/provider`,
       {
         method: "PUT",
         headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ provider }),
+        body: JSON.stringify({ provider, profile: profile || undefined }),
       },
     ),
-  saveToolsetEnv: (name: string, env: Record<string, string>) =>
+  saveToolsetEnv: (name: string, env: Record<string, string>, profile?: string) =>
     fetchJSON<ToolsetEnvResult>(
       `/api/tools/toolsets/${encodeURIComponent(name)}/env`,
       {
         method: "PUT",
         headers: { "Content-Type": "application/json" },
-        body: JSON.stringify({ env }),
+        body: JSON.stringify({ env, profile: profile || undefined }),
       },
     ),
   runToolsetPostSetup: (name: string, key: string) =>
@@ -986,26 +1000,34 @@ export const api = {
     fetchJSON<ActionResponse>("/api/ops/checkpoints/prune", { method: "POST" }),
 
   // ── Admin: Skills hub ───────────────────────────────────────────────
-  installSkillFromHub: (identifier: string) =>
+  // ``profile`` scopes install/uninstall/update and the installed-state
+  // annotations to that profile (omitted = the dashboard's own profile).
+  installSkillFromHub: (identifier: string, profile?: string) =>
     fetchJSON<ActionResponse>("/api/skills/hub/install", {
       method: "POST",
       headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ identifier }),
+      body: JSON.stringify({ identifier, profile: profile || undefined }),
     }),
-  uninstallSkillFromHub: (name: string) =>
+  uninstallSkillFromHub: (name: string, profile?: string) =>
     fetchJSON<ActionResponse>("/api/skills/hub/uninstall", {
       method: "POST",
       headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ name }),
+      body: JSON.stringify({ name, profile: profile || undefined }),
     }),
-  updateSkillsFromHub: () =>
-    fetchJSON<ActionResponse>("/api/skills/hub/update", { method: "POST" }),
-  searchSkillsHub: (q: string, source = "all", limit = 20) =>
+  updateSkillsFromHub: (profile?: string) =>
+    fetchJSON<ActionResponse>("/api/skills/hub/update", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ profile: profile || undefined }),
+    }),
+  searchSkillsHub: (q: string, source = "all", limit = 20, profile?: string) =>
     fetchJSON<SkillHubSearchResponse>(
-      `/api/skills/hub/search?q=${encodeURIComponent(q)}&source=${encodeURIComponent(source)}&limit=${limit}`,
+      `/api/skills/hub/search?q=${encodeURIComponent(q)}&source=${encodeURIComponent(source)}&limit=${limit}${profile ? `&profile=${encodeURIComponent(profile)}` : ""}`,
+    ),
+  getSkillHubSources: (profile?: string) =>
+    fetchJSON<SkillHubSourcesResponse>(
+      `/api/skills/hub/sources${profileQuery(profile)}`,
     ),
-  getSkillHubSources: () =>
-    fetchJSON<SkillHubSourcesResponse>("/api/skills/hub/sources"),
   previewSkillFromHub: (identifier: string) =>
     fetchJSON<SkillHubPreview>(
       `/api/skills/hub/preview?identifier=${encodeURIComponent(identifier)}`,
diff --git a/web/src/pages/ProfilesPage.tsx b/web/src/pages/ProfilesPage.tsx
index bda2515528f0..a1e69bfbcc84 100644
--- a/web/src/pages/ProfilesPage.tsx
+++ b/web/src/pages/ProfilesPage.tsx
@@ -22,6 +22,7 @@ import {
   X,
 } from "lucide-react";
 import spinners from "unicode-animations";
+import { useNavigate } from "react-router-dom";
 import { H2 } from "@nous-research/ui/ui/components/typography/h2";
 import { api } from "@/lib/api";
 import type { ActiveProfileInfo, ProfileInfo } from "@/lib/api";
@@ -96,6 +97,7 @@ function ProfileActionsMenu({
   onEditDescription,
   onEditModel,
   onEditSoul,
+  onManageSkills,
   onRename,
   onSetActive,
 }: ProfileActionsMenuProps) {
@@ -201,6 +203,16 @@ function ProfileActionsMenu({
             {labels.editSoul}
           </button>
 
+          <button
+            type="button"
+            role="menuitem"
+            className={itemClass}
+            onClick={run(onManageSkills)}
+          >
+            <Package className="h-4 w-4" />
+            {labels.manageSkills}
+          </button>
+
           <button
             type="button"
             role="menuitem"
@@ -241,6 +253,7 @@ function ProfileActionsMenu({
 }
 
 export default function ProfilesPage() {
+  const navigate = useNavigate();
   const [profiles, setProfiles] = useState<ProfileInfo[]>([]);
   const [activeInfo, setActiveInfo] = useState<ActiveProfileInfo | null>(null);
   const [loading, setLoading] = useState(true);
@@ -291,6 +304,10 @@ export default function ProfilesPage() {
       modelSaved: p.modelSaved ?? "Model updated",
       modelSelect: p.modelSelect ?? "Select a model",
       actions: p.actions ?? "Actions",
+      manageSkills: p.manageSkills ?? "Manage skills & tools",
+      activeSetHint:
+        p.activeSetHint ??
+        "Applies to new CLI/gateway runs. This dashboard still manages its own profile — use “Manage skills & tools” to edit {name}.",
     };
   }, [t.profiles]);
 
@@ -480,7 +497,14 @@ export default function ProfilesPage() {
       // The backend normalizes/validates the name; trust the canonical
       // value it returns rather than the raw input.
       const { active } = await api.setActiveProfile(name);
-      showToast(`${L.activeSet}: ${active}`, "success");
+      // "Set as active" only flips the sticky default for FUTURE CLI/gateway
+      // invocations — it does NOT retarget this running dashboard. Say so,
+      // or users assume skill/tool toggles now apply to the activated
+      // profile (they don't — that's what "Manage skills & tools" is for).
+      showToast(
+        `${L.activeSet}: ${active} — ${L.activeSetHint.replace("{name}", active)}`,
+        "success",
+      );
       setActiveInfo((prev) =>
         prev ? { ...prev, active } : { active, current: active },
       );
@@ -1110,6 +1134,7 @@ export default function ProfilesPage() {
                             editModel: L.editModel,
                             editDescription: L.editDescription,
                             editSoul: t.profiles.editSoul,
+                            manageSkills: L.manageSkills,
                             openInTerminal: t.profiles.openInTerminal,
                             rename: t.profiles.rename,
                             delete: t.common.delete,
@@ -1121,6 +1146,11 @@ export default function ProfilesPage() {
                           onEditDescription={() => openDescEditor(p)}
                           onEditModel={() => openModelEditor(p)}
                           onEditSoul={() => openSoulEditor(p.name)}
+                          onManageSkills={() =>
+                            navigate(
+                              `/skills?profile=${encodeURIComponent(p.name)}`,
+                            )
+                          }
                           onRename={() => {
                             setRenamingFrom(p.name);
                             setRenameTo(p.name);
@@ -1375,6 +1405,7 @@ interface ProfileActionsMenuProps {
     editDescription: string;
     editModel: string;
     editSoul: string;
+    manageSkills: string;
     openInTerminal: string;
     rename: string;
     setActive: string;
@@ -1385,6 +1416,7 @@ interface ProfileActionsMenuProps {
   onEditDescription: () => void;
   onEditModel: () => void;
   onEditSoul: () => void;
+  onManageSkills: () => void;
   onRename: () => void;
   onSetActive: () => void;
 }
diff --git a/web/src/pages/SkillsPage.tsx b/web/src/pages/SkillsPage.tsx
index 4ece3105f760..c3a5d324e157 100644
--- a/web/src/pages/SkillsPage.tsx
+++ b/web/src/pages/SkillsPage.tsx
@@ -25,6 +25,7 @@ import {
   AlertTriangle,
   Sparkles,
   Loader2,
+  Users,
 } from "lucide-react";
 import { api } from "@/lib/api";
 import type {
@@ -35,7 +36,9 @@ import type {
   SkillHubInstalledEntry,
   SkillHubPreview,
   SkillHubScan,
+  ProfileInfo,
 } from "@/lib/api";
+import { useSearchParams } from "react-router-dom";
 import { ToolsetConfigDrawer } from "@/components/ToolsetConfigDrawer";
 import { useToast } from "@nous-research/ui/hooks/use-toast";
 import { Toast } from "@nous-research/ui/ui/components/toast";
@@ -133,21 +136,79 @@ export default function SkillsPage() {
   const { t } = useI18n();
   const { setAfterTitle, setEnd } = usePageHeader();
 
+  // ── Profile scoping ──
+  // The dashboard process runs under ONE profile, but skills/toolsets are
+  // per-profile state. Without an explicit selector, users who "activated"
+  // a profile on the Profiles page (which only affects FUTURE CLI/gateway
+  // runs) toggled skills here and silently wrote into the dashboard's own
+  // profile. The selector makes the write target explicit and deep-linkable
+  // via /skills?profile=<name>.
+  const [searchParams, setSearchParams] = useSearchParams();
+  const [profiles, setProfiles] = useState<ProfileInfo[]>([]);
+  const [currentProfile, setCurrentProfile] = useState<string>("");
+  const urlProfile = searchParams.get("profile") ?? "";
+  // "" = the dashboard's own profile (legacy behavior).
+  const selectedProfile = urlProfile;
+
+  const setSelectedProfile = useCallback(
+    (name: string) => {
+      setSearchParams(
+        (prev) => {
+          const next = new URLSearchParams(prev);
+          if (name) next.set("profile", name);
+          else next.delete("profile");
+          return next;
+        },
+        { replace: true },
+      );
+    },
+    [setSearchParams],
+  );
+
+  // The profile actually being managed, for display purposes.
+  const managedProfile = selectedProfile || currentProfile || "default";
+  const managingOtherProfile =
+    !!selectedProfile && selectedProfile !== currentProfile;
+
   useEffect(() => {
-    Promise.all([api.getSkills(), api.getToolsets()])
+    // Profile list + the dashboard's own profile, for the selector. Failure
+    // leaves the selector hidden — the page still works profile-unscoped.
+    api
+      .getProfiles()
+      .then((res) => setProfiles(res.profiles))
+      .catch(() => {});
+    api
+      .getActiveProfile()
+      .then((info) => setCurrentProfile(info.current || "default"))
+      .catch(() => setCurrentProfile("default"));
+  }, []);
+
+  useEffect(() => {
+    // Promise-chain shape: setState fires only inside async callbacks so the
+    // effect body stays lint-clean (react-hooks/set-state-in-effect). On a
+    // profile switch the old list stays visible until the new one arrives.
+    let cancelled = false;
+    Promise.all([
+      api.getSkills(selectedProfile || undefined),
+      api.getToolsets(selectedProfile || undefined),
+    ])
       .then(([s, tsets]) => {
+        if (cancelled) return;
         setSkills(s);
         setToolsets(tsets);
       })
-      .catch(() => showToast(t.common.loading, "error"))
-      .finally(() => setLoading(false));
-  }, []);
+      .catch(() => !cancelled && showToast(t.common.loading, "error"))
+      .finally(() => !cancelled && setLoading(false));
+    return () => {
+      cancelled = true;
+    };
+  }, [selectedProfile]);
 
   /* ---- Toggle skill ---- */
   const handleToggleSkill = async (skill: SkillInfo) => {
     setTogglingSkills((prev) => new Set(prev).add(skill.name));
     try {
-      await api.toggleSkill(skill.name, !skill.enabled);
+      await api.toggleSkill(skill.name, !skill.enabled, selectedProfile || undefined);
       setSkills((prev) =>
         prev.map((s) =>
           s.name === skill.name ? { ...s, enabled: !s.enabled } : s,
@@ -233,10 +294,37 @@ export default function SkillsPage() {
       return;
     }
     setAfterTitle(
-      <span className="whitespace-nowrap text-xs text-muted-foreground">
+      <span className="flex items-center gap-2 whitespace-nowrap text-xs text-muted-foreground">
         {t.skills.enabledOf
           .replace("{enabled}", String(enabledCount))
           .replace("{total}", String(skills.length))}
+        {profiles.length > 1 && (
+          <span className="flex items-center gap-1">
+            <Users className="h-3 w-3" />
+            <select
+              aria-label={t.skills.profileSelector ?? "Profile"}
+              className="h-6 rounded-none border border-border bg-background px-1 text-xs text-foreground"
+              value={selectedProfile}
+              onChange={(e: React.ChangeEvent<HTMLSelectElement>) =>
+                setSelectedProfile(e.target.value)
+              }
+            >
+              <option value="">
+                {(t.skills.currentProfile ?? "current ({name})").replace(
+                  "{name}",
+                  currentProfile || "default",
+                )}
+              </option>
+              {profiles
+                .filter((p) => p.name !== currentProfile)
+                .map((p) => (
+                  <option key={p.name} value={p.name}>
+                    {p.name}
+                  </option>
+                ))}
+            </select>
+          </span>
+        )}
       </span>,
     );
     setEnd(
@@ -265,7 +353,19 @@ export default function SkillsPage() {
       setAfterTitle(null);
       setEnd(null);
     };
-  }, [enabledCount, loading, search, setAfterTitle, setEnd, skills.length, t]);
+  }, [
+    enabledCount,
+    loading,
+    search,
+    setAfterTitle,
+    setEnd,
+    skills.length,
+    t,
+    profiles,
+    selectedProfile,
+    currentProfile,
+    setSelectedProfile,
+  ]);
 
   const filteredToolsets = useMemo(() => {
     return toolsets.filter(
@@ -291,6 +391,18 @@ export default function SkillsPage() {
       <PluginSlot name="skills:top" />
       <Toast toast={toast} />
 
+      {managingOtherProfile && (
+        <div className="flex items-center gap-2 border border-amber-500/40 bg-amber-500/10 px-3 py-2 text-xs text-amber-300">
+          <Users className="h-3.5 w-3.5 shrink-0" />
+          <span>
+            {(
+              t.skills.managingProfile ??
+              "Managing profile “{name}” — toggles apply to that profile, not this dashboard’s."
+            ).replace("{name}", managedProfile)}
+          </span>
+        </div>
+      )}
+
       <div className="flex flex-col sm:flex-row sm:items-start gap-4">
         <aside aria-label={t.skills.title} className="sm:w-56 sm:shrink-0">
           <div className="sm:sticky sm:top-0">
@@ -540,13 +652,14 @@ export default function SkillsPage() {
               )}
             </>
           ) : (
-            <HubBrowser showToast={showToast} />
+            <HubBrowser showToast={showToast} profile={selectedProfile || undefined} />
           )}
         </div>
       </div>
       {configToolset && (
         <ToolsetConfigDrawer
           toolset={configToolset}
+          profile={selectedProfile || undefined}
           onClose={() => setConfigToolset(null)}
           onChanged={() => void refreshToolsets()}
         />
@@ -668,8 +781,11 @@ const SEVERITY_TONE: Record<string, "destructive" | "warning" | "secondary" | "o
 
 function HubBrowser({
   showToast,
+  profile,
 }: {
   showToast: (msg: string, kind: "success" | "error") => void;
+  /** Optional profile scoping installs + installed-state badges. */
+  profile?: string;
 }) {
   const [query, setQuery] = useState("");
   const [results, setResults] = useState<SkillHubResult[]>([]);
@@ -699,7 +815,7 @@ function HubBrowser({
   useEffect(() => {
     let cancelled = false;
     api
-      .getSkillHubSources()
+      .getSkillHubSources(profile)
       .then((r) => {
         if (cancelled) return;
         setSources(r.sources);
@@ -715,7 +831,7 @@ function HubBrowser({
     return () => {
       cancelled = true;
     };
-  }, []);
+  }, [profile]);
 
   /* ---- Search ---- */
   const runSearch = useCallback(async () => {
@@ -725,7 +841,7 @@ function HubBrowser({
     setSearched(true);
     const t0 = performance.now();
     try {
-      const r = await api.searchSkillsHub(q);
+      const r = await api.searchSkillsHub(q, "all", 20, profile);
       setResults(r.results);
       setSourceCounts(r.source_counts || {});
       setTimedOut(r.timed_out || []);
@@ -739,7 +855,7 @@ function HubBrowser({
       setSearchMs(Math.round(performance.now() - t0));
       setSearching(false);
     }
-  }, [query, showToast]);
+  }, [query, showToast, profile]);
 
   /* ---- Poll a spawned action's log until it exits ---- */
   useEffect(() => {
@@ -757,7 +873,7 @@ function HubBrowser({
         } else {
           // Install finished — refresh installed-state so badges update.
           api
-            .getSkillHubSources()
+            .getSkillHubSources(profile)
             .then((r) => !cancelled && setInstalled(r.installed))
             .catch(() => {});
         }
@@ -770,12 +886,12 @@ function HubBrowser({
       cancelled = true;
       if (timer) clearTimeout(timer);
     };
-  }, [action]);
+  }, [action, profile]);
 
   const install = useCallback(
     async (identifier: string) => {
       try {
-        const res = await api.installSkillFromHub(identifier);
+        const res = await api.installSkillFromHub(identifier, profile);
         showToast(`Installing ${identifier}…`, "success");
         setActionLog([]);
         setActionRunning(true);
@@ -785,12 +901,12 @@ function HubBrowser({
         showToast(`Install failed: ${e}`, "error");
       }
     },
-    [showToast],
+    [showToast, profile],
   );
 
   const updateAll = useCallback(async () => {
     try {
-      const res = await api.updateSkillsFromHub();
+      const res = await api.updateSkillsFromHub(profile);
       showToast("Updating installed skills…", "success");
       setActionLog([]);
       setActionRunning(true);
@@ -798,7 +914,7 @@ function HubBrowser({
     } catch (e) {
       showToast(`Update failed: ${e}`, "error");
     }
-  }, [showToast]);
+  }, [showToast, profile]);
 
   const isInstalled = useCallback(
     (identifier: string) => Boolean(installed[identifier]),

From ad9012097b422ffc968a53748e08c205715aa322 Mon Sep 17 00:00:00 2001
From: Teknium <127238744+teknium1@users.noreply.github.com>
Date: Wed, 10 Jun 2026 15:43:19 -0700
Subject: [PATCH 11/28] fix(dashboard): dedupe useNavigate import/declaration
 in ProfilesPage

tsc -b (run by the Docker image build, unlike local vite-only checks)
rejected the duplicate identifier.
---
 web/src/pages/ProfilesPage.tsx | 2 --
 1 file changed, 2 deletions(-)

diff --git a/web/src/pages/ProfilesPage.tsx b/web/src/pages/ProfilesPage.tsx
index a1e69bfbcc84..29220ea96396 100644
--- a/web/src/pages/ProfilesPage.tsx
+++ b/web/src/pages/ProfilesPage.tsx
@@ -22,7 +22,6 @@ import {
   X,
 } from "lucide-react";
 import spinners from "unicode-animations";
-import { useNavigate } from "react-router-dom";
 import { H2 } from "@nous-research/ui/ui/components/typography/h2";
 import { api } from "@/lib/api";
 import type { ActiveProfileInfo, ProfileInfo } from "@/lib/api";
@@ -260,7 +259,6 @@ export default function ProfilesPage() {
   const { toast, showToast } = useToast();
   const { t } = useI18n();
   const { setEnd } = usePageHeader();
-  const navigate = useNavigate();
 
   // Locale strings with English fallbacks. The enriched keys are optional in
   // the i18n type so untranslated locales don't break the build — they render

From 65ddc7c4a1dc32a1ad5e9e732618c5a0f3ef3bf4 Mon Sep 17 00:00:00 2001
From: Brooklyn Nicholson <brooklyn.bb.nicholson@gmail.com>
Date: Wed, 10 Jun 2026 22:41:34 -0500
Subject: [PATCH 12/28] fix(desktop): retain composer attachments per session
 scope + guard programmatic drafts
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The salvaged draft persistence scoped text per session but reset the
composer's attachments to [] on every scope change, so a staged image or
file was silently dropped when you switched sessions and never restored on
return — inconsistent with the "drafts survive session switches" promise
and a real paper-cut given remote staging cost.

Retain attachments per scope in an in-memory map (keyed by the same scope
as the text draft) since blobs / object URLs / live upload state can't be
serialized to localStorage. Entering a scope restores its stashed chips;
leaving stashes the current ones; an accepted submit clears the scope.
This survives session switches (the case users hit) without pretending to
survive a full reload, which attachments fundamentally can't.

Also guard the debounced text write so browsing sent-message history or
editing a queued prompt (both swap the composer to recalled text via
loadIntoComposer) no longer clobbers the genuine in-progress draft in
storage.

Co-authored-by: mollusk <roger@roger.local>
Co-authored-by: Teknium <127238744+teknium1@users.noreply.github.com>
---
 apps/desktop/src/app/chat/composer/index.tsx | 28 +++++++++++-
 apps/desktop/src/store/composer.test.ts      | 48 ++++++++++++++++++++
 apps/desktop/src/store/composer.ts           | 32 +++++++++++++
 3 files changed, 106 insertions(+), 2 deletions(-)

diff --git a/apps/desktop/src/app/chat/composer/index.tsx b/apps/desktop/src/app/chat/composer/index.tsx
index 5530ffb60aef..169c22236b8a 100644
--- a/apps/desktop/src/app/chat/composer/index.tsx
+++ b/apps/desktop/src/app/chat/composer/index.tsx
@@ -28,8 +28,11 @@ import {
   $composerAttachments,
   clearComposerAttachments,
   clearPersistedComposerDraft,
+  clearStashedComposerAttachments,
   type ComposerAttachment,
   readPersistedComposerDraft,
+  stashComposerAttachments,
+  takeComposerAttachments,
   writePersistedComposerDraft
 } from '@/store/composer'
 import {
@@ -1111,10 +1114,20 @@ export function ChatBar({
     }
   }
 
+  // Restore a scope's draft (persisted text + in-memory attachments) when we
+  // enter it, and stash the attachments back when we leave. Text rides through
+  // localStorage so it survives reloads; attachments carry live blobs/upload
+  // state that can't serialize, so they're retained in memory only — enough to
+  // survive a session switch, which is the case users actually hit.
   useEffect(() => {
     const persisted = readPersistedComposerDraft(draftPersistenceScope)
+    const restoredAttachments = takeComposerAttachments(draftPersistenceScope)
     skipNextDraftPersistScopeRef.current = draftPersistenceScope
-    loadIntoComposer(persisted, [])
+    loadIntoComposer(persisted, restoredAttachments)
+
+    return () => {
+      stashComposerAttachments(draftPersistenceScope, $composerAttachments.get())
+    }
   }, [draftPersistenceScope]) // eslint-disable-line react-hooks/exhaustive-deps
 
   useEffect(() => {
@@ -1124,6 +1137,15 @@ export function ChatBar({
       return
     }
 
+    // Don't persist programmatically-loaded text: browsing sent-message
+    // history or editing a queued prompt swaps the composer to recalled text,
+    // and persisting that would clobber the genuine in-progress draft (which
+    // history keeps in its own snapshot and restores on the way back). Leaving
+    // the prior pending write untouched keeps the real draft in storage.
+    if (isBrowsingHistory(sessionId) || queueEdit) {
+      return
+    }
+
     // Debounce the localStorage write: the composer's per-keystroke path was
     // deliberately slimmed down (see the draftRef sync comment above), so we
     // don't touch storage on every keypress. The pending ref below is flushed
@@ -1137,7 +1159,7 @@ export function ChatBar({
     }, DRAFT_PERSIST_DEBOUNCE_MS)
 
     return () => window.clearTimeout(handle)
-  }, [draft, draftPersistenceScope])
+  }, [draft, draftPersistenceScope, queueEdit, sessionId])
 
   // Flush any pending debounced draft write when leaving a session scope or
   // unmounting, so the departing session's latest text is always persisted.
@@ -1412,6 +1434,7 @@ export function ChatBar({
             writePersistedComposerDraft(draftPersistenceScope, submitted)
           } else {
             clearPersistedComposerDraft(draftPersistenceScope)
+            clearStashedComposerAttachments(draftPersistenceScope)
           }
         }).catch(() => {
           loadIntoComposer(submitted, [])
@@ -1440,6 +1463,7 @@ export function ChatBar({
           writePersistedComposerDraft(draftPersistenceScope, submitted)
         } else {
           clearPersistedComposerDraft(draftPersistenceScope)
+          clearStashedComposerAttachments(draftPersistenceScope)
         }
       }).catch(() => {
         loadIntoComposer(submitted, submittedAttachments)
diff --git a/apps/desktop/src/store/composer.test.ts b/apps/desktop/src/store/composer.test.ts
index 7bb44c74bd06..05ecef225586 100644
--- a/apps/desktop/src/store/composer.test.ts
+++ b/apps/desktop/src/store/composer.test.ts
@@ -4,10 +4,13 @@ import {
   $composerAttachments,
   addComposerAttachment,
   clearPersistedComposerDraft,
+  clearStashedComposerAttachments,
   type ComposerAttachment,
   composerDraftStorageKey,
   readPersistedComposerDraft,
   removeComposerAttachment,
+  stashComposerAttachments,
+  takeComposerAttachments,
   updateComposerAttachment,
   writePersistedComposerDraft
 } from './composer'
@@ -81,3 +84,48 @@ describe('persisted composer drafts', () => {
     expect(readPersistedComposerDraft('session-a')).toBe('')
   })
 })
+
+describe('stashed composer attachments', () => {
+  afterEach(() => {
+    clearStashedComposerAttachments('session-a')
+    clearStashedComposerAttachments('session-b')
+    clearStashedComposerAttachments(null)
+  })
+
+  it('retains and restores attachments per session scope', () => {
+    stashComposerAttachments('session-a', [attachment({ id: 'file:a' })])
+    stashComposerAttachments('session-b', [attachment({ id: 'image:b', kind: 'image' })])
+
+    expect(takeComposerAttachments('session-a').map(a => a.id)).toEqual(['file:a'])
+    expect(takeComposerAttachments('session-b').map(a => a.id)).toEqual(['image:b'])
+  })
+
+  it('shares a stable new-session scope with the text draft helpers', () => {
+    stashComposerAttachments(null, [attachment({ id: 'file:new' })])
+
+    expect(takeComposerAttachments(undefined).map(a => a.id)).toEqual(['file:new'])
+  })
+
+  it('returns cloned attachments so callers cannot mutate the stash', () => {
+    stashComposerAttachments('session-a', [attachment({ id: 'file:a', label: 'orig.pdf' })])
+
+    const taken = takeComposerAttachments('session-a')
+    taken[0]!.label = 'mutated.pdf'
+
+    expect(takeComposerAttachments('session-a')[0]?.label).toBe('orig.pdf')
+  })
+
+  it('drops the scope entry when stashing an empty set', () => {
+    stashComposerAttachments('session-a', [attachment({ id: 'file:a' })])
+    stashComposerAttachments('session-a', [])
+
+    expect(takeComposerAttachments('session-a')).toEqual([])
+  })
+
+  it('clears a scope explicitly after an accepted submit', () => {
+    stashComposerAttachments('session-a', [attachment({ id: 'file:a' })])
+    clearStashedComposerAttachments('session-a')
+
+    expect(takeComposerAttachments('session-a')).toEqual([])
+  })
+})
diff --git a/apps/desktop/src/store/composer.ts b/apps/desktop/src/store/composer.ts
index 5af98a49e3b4..ba78ac43e220 100644
--- a/apps/desktop/src/store/composer.ts
+++ b/apps/desktop/src/store/composer.ts
@@ -83,6 +83,38 @@ export function clearPersistedComposerDraft(scope: string | null | undefined) {
   }
 }
 
+// Attachments can't ride along in localStorage the way text does — they carry
+// live blobs, object URLs, and in-flight upload state that don't serialize and
+// are tied to the running app. So we retain them per scope in an in-memory map
+// instead: a session switch restores the chips you'd staged, even though they
+// (unlike text) cannot survive a full app reload.
+const composerAttachmentsByScope = new Map<string, ComposerAttachment[]>()
+
+const cloneComposerAttachments = (attachments: ComposerAttachment[]): ComposerAttachment[] =>
+  attachments.map(attachment => ({ ...attachment }))
+
+export function stashComposerAttachments(scope: string | null | undefined, attachments: ComposerAttachment[]) {
+  const key = storageScope(scope)
+
+  if (attachments.length === 0) {
+    composerAttachmentsByScope.delete(key)
+
+    return
+  }
+
+  composerAttachmentsByScope.set(key, cloneComposerAttachments(attachments))
+}
+
+export function takeComposerAttachments(scope: string | null | undefined): ComposerAttachment[] {
+  const stashed = composerAttachmentsByScope.get(storageScope(scope))
+
+  return stashed ? cloneComposerAttachments(stashed) : []
+}
+
+export function clearStashedComposerAttachments(scope: string | null | undefined) {
+  composerAttachmentsByScope.delete(storageScope(scope))
+}
+
 export function setComposerDraft(value: string) {
   $composerDraft.set(value)
 }

From aaccaada282bdf42d8a38e5f49bfa2b6e27efd63 Mon Sep 17 00:00:00 2001
From: RaumfahrerSpiffy <56406949+RaumfahrerSpiffy@users.noreply.github.com>
Date: Sat, 30 May 2026 19:37:27 -0400
Subject: [PATCH 13/28] fix(anthropic): preserve interleaved thinking/tool_use
 block order on replay

Interleaved-thinking turns (adaptive thinking, Claude 4.6+/Opus 4.8) emit
content blocks like:

    thinking_1(signed) tool_use_1 thinking_2(signed) tool_use_2

Anthropic signs each thinking block against the turn content preceding it
at its position. normalize_response split the turn into two parallel lists
(reasoning_details + tool_calls), discarding cross-type order, and
_convert_assistant_message rebuilt it as [all thinking][text][all tool_use].
That moved thinking_2 ahead of tool_use_1, invalidating its signature, so
Anthropic rejected the latest assistant message with HTTP 400:

    messages.N.content.M: `thinking` or `redacted_thinking` blocks in the
    latest assistant message cannot be modified.

Observed repeatedly in agent.conversation_loop against api.anthropic.com /
claude-opus-4-8, recurring across sessions on multi-thinking-block turns.

Fix: carry a verbatim, order-preserving copy of the turn's content blocks
(anthropic_content_blocks) end-to-end - capture in normalize_response,
persist/restore through state.db, and replay unchanged for the latest
assistant message. Gated to turns that actually interleave signed thinking
with tool_use, so normal turns are unaffected.

Adds 3 regression tests including a SQLite round-trip covering the
crash-recovery reload path.
---
 agent/anthropic_adapter.py                    |  23 ++
 agent/chat_completion_helpers.py              |  12 +
 agent/transports/anthropic.py                 |  37 ++-
 agent/transports/types.py                     |  12 +
 hermes_state.py                               |  31 ++-
 run_agent.py                                  |   1 +
 .../test_anthropic_thinking_block_order.py    | 235 ++++++++++++++++++
 7 files changed, 344 insertions(+), 7 deletions(-)
 create mode 100644 tests/agent/test_anthropic_thinking_block_order.py

diff --git a/agent/anthropic_adapter.py b/agent/anthropic_adapter.py
index e64bc54bc90a..25ee73580f78 100644
--- a/agent/anthropic_adapter.py
+++ b/agent/anthropic_adapter.py
@@ -1692,6 +1692,29 @@ def _convert_assistant_message(m: Dict[str, Any]) -> Dict[str, Any]:
     reasoning_content injection for Kimi/DeepSeek endpoints.
     """
     content = m.get("content", "")
+    # Anthropic interleaved-thinking fast path: when this turn carries a
+    # verbatim, order-preserving block list (set by normalize_response only
+    # for turns that interleave SIGNED thinking with tool_use), replay it
+    # unchanged. Reconstructing from the parallel reasoning_details +
+    # tool_calls fields front-loads thinking and reorders signed blocks,
+    # which Anthropic rejects with HTTP 400 ("thinking ... blocks in the
+    # latest assistant message cannot be modified"). Block order — and thus
+    # each thinking block's signature — must survive verbatim. tool_use IDs
+    # are sanitized to match the tool_result IDs produced elsewhere; the
+    # downstream mcp_ prefixing pass handles tool names on these blocks.
+    ordered_blocks = m.get("anthropic_content_blocks")
+    if isinstance(ordered_blocks, list) and ordered_blocks:
+        replayed: List[Dict[str, Any]] = []
+        for b in ordered_blocks:
+            if not isinstance(b, dict):
+                continue
+            blk = copy.deepcopy(b)
+            if blk.get("type") == "tool_use" and "id" in blk:
+                blk["id"] = _sanitize_tool_id(blk.get("id", ""))
+            replayed.append(blk)
+        if replayed:
+            return {"role": "assistant", "content": replayed}
+
     blocks = _extract_preserved_thinking_blocks(m)
     if content:
         if isinstance(content, list):
diff --git a/agent/chat_completion_helpers.py b/agent/chat_completion_helpers.py
index 783e85b3e938..dcf9e24fc8da 100644
--- a/agent/chat_completion_helpers.py
+++ b/agent/chat_completion_helpers.py
@@ -952,6 +952,18 @@ def build_assistant_message(agent, assistant_message, finish_reason: str) -> dic
         if preserved:
             msg["reasoning_details"] = preserved
 
+    # Anthropic interleaved-thinking replay: when a turn interleaves signed
+    # thinking blocks with tool_use, the parallel reasoning_details +
+    # tool_calls fields lose the cross-type ordering, and reconstruction
+    # front-loads thinking — reordering signed blocks and triggering HTTP 400
+    # ("thinking ... blocks in the latest assistant message cannot be
+    # modified"). Carry the verbatim ordered block list so the adapter can
+    # replay the latest assistant message unchanged. See
+    # agent/transports/anthropic.py and agent/anthropic_adapter.py.
+    ordered_blocks = getattr(assistant_message, "anthropic_content_blocks", None)
+    if ordered_blocks:
+        msg["anthropic_content_blocks"] = ordered_blocks
+
     # Codex Responses API: preserve encrypted reasoning items for
     # multi-turn continuity. These get replayed as input on the next turn.
     codex_items = getattr(assistant_message, "codex_reasoning_items", None)
diff --git a/agent/transports/anthropic.py b/agent/transports/anthropic.py
index d77ae63ef327..e7c99751c7c5 100644
--- a/agent/transports/anthropic.py
+++ b/agent/transports/anthropic.py
@@ -94,13 +94,27 @@ class AnthropicTransport(ProviderTransport):
         reasoning_parts = []
         reasoning_details = []
         tool_calls = []
+        # Verbatim, order-preserving copy of every content block in the turn.
+        # Anthropic signs each thinking block against the turn content that
+        # PRECEDES it at its position; when a turn interleaves thinking and
+        # tool_use (adaptive/interleaved thinking, Claude 4.6+), the parallel
+        # reasoning_details + tool_calls lists below lose that cross-type
+        # ordering. Replaying the latest assistant message in the wrong order
+        # invalidates the signatures -> HTTP 400 "thinking ... blocks in the
+        # latest assistant message cannot be modified". Preserve the exact
+        # block sequence here so the adapter can replay it unchanged. See
+        # tests/agent/test_anthropic_thinking_block_order.py.
+        ordered_blocks = []
 
         for block in response.content:
+            block_dict = _to_plain_data(block)
+            if isinstance(block_dict, dict):
+                ordered_blocks.append(block_dict)
             if block.type == "text":
                 text_parts.append(block.text)
-            elif block.type == "thinking":
-                reasoning_parts.append(block.thinking)
-                block_dict = _to_plain_data(block)
+            elif block.type in ("thinking", "redacted_thinking"):
+                if block.type == "thinking":
+                    reasoning_parts.append(block.thinking)
                 if isinstance(block_dict, dict):
                     reasoning_details.append(block_dict)
             elif block.type == "tool_use":
@@ -130,6 +144,23 @@ class AnthropicTransport(ProviderTransport):
         provider_data = {}
         if reasoning_details:
             provider_data["reasoning_details"] = reasoning_details
+        # Only worth carrying the ordered-blocks channel when the turn
+        # actually interleaves signed thinking with tool_use — that's the
+        # only shape the parallel lists reconstruct incorrectly. A turn that
+        # is purely text, or thinking-then-tools with a single leading
+        # thinking block, replays correctly without it.
+        _has_signed_thinking = any(
+            isinstance(b, dict)
+            and b.get("type") in ("thinking", "redacted_thinking")
+            and (b.get("signature") or b.get("data"))
+            for b in ordered_blocks
+        )
+        _has_tool_use = any(
+            isinstance(b, dict) and b.get("type") == "tool_use"
+            for b in ordered_blocks
+        )
+        if _has_signed_thinking and _has_tool_use:
+            provider_data["anthropic_content_blocks"] = ordered_blocks
 
         return NormalizedResponse(
             content="\n".join(text_parts) if text_parts else None,
diff --git a/agent/transports/types.py b/agent/transports/types.py
index 2deb157535b4..6ad20f2376d1 100644
--- a/agent/transports/types.py
+++ b/agent/transports/types.py
@@ -121,6 +121,18 @@ class NormalizedResponse:
         pd = self.provider_data or {}
         return pd.get("reasoning_details")
 
+    @property
+    def anthropic_content_blocks(self):
+        """Verbatim, order-preserving Anthropic content blocks for a turn.
+
+        Present only when an Anthropic turn interleaves signed thinking with
+        tool_use — the one shape the parallel reasoning_details + tool_calls
+        lists reconstruct in the wrong order, invalidating thinking-block
+        signatures on replay. See agent/transports/anthropic.py.
+        """
+        pd = self.provider_data or {}
+        return pd.get("anthropic_content_blocks")
+
     @property
     def codex_reasoning_items(self):
         pd = self.provider_data or {}
diff --git a/hermes_state.py b/hermes_state.py
index bda6eeacd628..7b8a2bfcfb4b 100644
--- a/hermes_state.py
+++ b/hermes_state.py
@@ -488,6 +488,7 @@ CREATE TABLE IF NOT EXISTS messages (
     reasoning TEXT,
     reasoning_content TEXT,
     reasoning_details TEXT,
+    anthropic_content_blocks TEXT,
     codex_reasoning_items TEXT,
     codex_message_items TEXT,
     platform_message_id TEXT,
@@ -2240,6 +2241,7 @@ class SessionDB:
         reasoning: str = None,
         reasoning_content: str = None,
         reasoning_details: Any = None,
+        anthropic_content_blocks: Any = None,
         codex_reasoning_items: Any = None,
         codex_message_items: Any = None,
         platform_message_id: str = None,
@@ -2262,6 +2264,10 @@ class SessionDB:
             json.dumps(reasoning_details)
             if reasoning_details else None
         )
+        anthropic_content_blocks_json = (
+            json.dumps(anthropic_content_blocks)
+            if anthropic_content_blocks else None
+        )
         codex_items_json = (
             json.dumps(codex_reasoning_items)
             if codex_reasoning_items else None
@@ -2284,9 +2290,10 @@ class SessionDB:
             cursor = conn.execute(
                 """INSERT INTO messages (session_id, role, content, tool_call_id,
                    tool_calls, tool_name, timestamp, token_count, finish_reason,
-                   reasoning, reasoning_content, reasoning_details, codex_reasoning_items,
+                   reasoning, reasoning_content, reasoning_details, anthropic_content_blocks,
+                   codex_reasoning_items,
                    codex_message_items, platform_message_id, observed)
-                   VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
+                   VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
                 (
                     session_id,
                     role,
@@ -2300,6 +2307,7 @@ class SessionDB:
                     reasoning,
                     reasoning_content,
                     reasoning_details_json,
+                    anthropic_content_blocks_json,
                     codex_items_json,
                     codex_message_items_json,
                     platform_message_id,
@@ -2348,6 +2356,9 @@ class SessionDB:
                 role = msg.get("role", "unknown")
                 tool_calls = msg.get("tool_calls")
                 reasoning_details = msg.get("reasoning_details") if role == "assistant" else None
+                anthropic_content_blocks = (
+                    msg.get("anthropic_content_blocks") if role == "assistant" else None
+                )
                 codex_reasoning_items = (
                     msg.get("codex_reasoning_items") if role == "assistant" else None
                 )
@@ -2358,6 +2369,9 @@ class SessionDB:
                 reasoning_details_json = (
                     json.dumps(reasoning_details) if reasoning_details else None
                 )
+                anthropic_content_blocks_json = (
+                    json.dumps(anthropic_content_blocks) if anthropic_content_blocks else None
+                )
                 codex_items_json = (
                     json.dumps(codex_reasoning_items) if codex_reasoning_items else None
                 )
@@ -2374,9 +2388,10 @@ class SessionDB:
                 conn.execute(
                     """INSERT INTO messages (session_id, role, content, tool_call_id,
                        tool_calls, tool_name, timestamp, token_count, finish_reason,
-                       reasoning, reasoning_content, reasoning_details, codex_reasoning_items,
+                       reasoning, reasoning_content, reasoning_details, anthropic_content_blocks,
+                       codex_reasoning_items,
                        codex_message_items, platform_message_id, observed)
-                       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
+                       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
                     (
                         session_id,
                         role,
@@ -2390,6 +2405,7 @@ class SessionDB:
                         msg.get("reasoning") if role == "assistant" else None,
                         msg.get("reasoning_content") if role == "assistant" else None,
                         reasoning_details_json,
+                        anthropic_content_blocks_json,
                         codex_items_json,
                         codex_message_items_json,
                         platform_msg_id,
@@ -2732,6 +2748,7 @@ class SessionDB:
             rows = self._conn.execute(
                 "SELECT role, content, tool_call_id, tool_calls, tool_name, "
                 "finish_reason, reasoning, reasoning_content, reasoning_details, "
+                "anthropic_content_blocks, "
                 "codex_reasoning_items, codex_message_items, platform_message_id, observed "
                 f"FROM messages WHERE session_id IN ({placeholders})"
                 f"{active_clause} ORDER BY id",
@@ -2779,6 +2796,12 @@ class SessionDB:
                     except (json.JSONDecodeError, TypeError):
                         logger.warning("Failed to deserialize reasoning_details, falling back to None")
                         msg["reasoning_details"] = None
+                if row["anthropic_content_blocks"]:
+                    try:
+                        msg["anthropic_content_blocks"] = json.loads(row["anthropic_content_blocks"])
+                    except (json.JSONDecodeError, TypeError):
+                        logger.warning("Failed to deserialize anthropic_content_blocks, falling back to None")
+                        msg["anthropic_content_blocks"] = None
                 if row["codex_reasoning_items"]:
                     try:
                         msg["codex_reasoning_items"] = json.loads(row["codex_reasoning_items"])
diff --git a/run_agent.py b/run_agent.py
index e81bf3b93e7e..eda39064c551 100644
--- a/run_agent.py
+++ b/run_agent.py
@@ -1597,6 +1597,7 @@ class AIAgent:
                     reasoning=msg.get("reasoning") if role == "assistant" else None,
                     reasoning_content=msg.get("reasoning_content") if role == "assistant" else None,
                     reasoning_details=msg.get("reasoning_details") if role == "assistant" else None,
+                    anthropic_content_blocks=msg.get("anthropic_content_blocks") if role == "assistant" else None,
                     codex_reasoning_items=msg.get("codex_reasoning_items") if role == "assistant" else None,
                     codex_message_items=msg.get("codex_message_items") if role == "assistant" else None,
                 )
diff --git a/tests/agent/test_anthropic_thinking_block_order.py b/tests/agent/test_anthropic_thinking_block_order.py
new file mode 100644
index 000000000000..a02c5a9eb77e
--- /dev/null
+++ b/tests/agent/test_anthropic_thinking_block_order.py
@@ -0,0 +1,235 @@
+"""Regression test for the Anthropic interleaved thinking-block 400.
+
+Reproduces: HTTP 400 ``messages.N.content.M: thinking or redacted_thinking
+blocks in the latest assistant message cannot be modified. These blocks must
+remain as they were in the original response.``
+
+Root cause under test
+----------------------
+With adaptive / interleaved thinking (Claude 4.6+, e.g. Opus 4.8), a single
+assistant turn can emit content blocks in an interleaved order::
+
+    thinking_1 (signed) · tool_use_1 · thinking_2 (signed) · tool_use_2
+
+Anthropic signs each thinking block against the turn content that precedes it
+at its position.  ``thinking_2`` is signed with ``tool_use_1`` before it.
+
+``AnthropicTransport.normalize_response`` (agent/transports/anthropic.py)
+splits the turn into two *parallel* lists — ``reasoning_details`` (thinking
+blocks) and ``tool_calls`` (tool_use blocks) — discarding the cross-type
+ordering.  ``run_agent`` stores those as separate fields on the assistant
+message.  On replay, ``_convert_assistant_message`` (agent/anthropic_adapter.py)
+rebuilds the content as ``[all thinking][text][all tool_use]``, which reorders
+``thinking_2`` ahead of ``tool_use_1``.  The signature no longer matches its
+original position, so Anthropic rejects the latest assistant message with the
+400 above.
+
+This test asserts that an interleaved turn round-trips through
+normalize_response -> stored message -> convert_messages_to_anthropic with its
+block order preserved.  It FAILS on the current code (documenting the bug) and
+should PASS once block ordering is preserved on replay.
+"""
+
+import json
+from types import SimpleNamespace
+
+import pytest
+
+from agent.transports import get_transport
+from agent.anthropic_adapter import convert_messages_to_anthropic
+
+
+def _thinking_block(text: str, signature: str) -> SimpleNamespace:
+    """A signed Anthropic thinking block, shaped like the SDK object."""
+    return SimpleNamespace(type="thinking", thinking=text, signature=signature)
+
+
+def _tool_use_block(block_id: str, name: str, payload: dict) -> SimpleNamespace:
+    return SimpleNamespace(type="tool_use", id=block_id, name=name, input=payload)
+
+
+def _interleaved_response() -> SimpleNamespace:
+    """An assistant turn with thinking interleaved between two tool_use blocks."""
+    return SimpleNamespace(
+        content=[
+            _thinking_block("Plan: inspect file A first.", "sig-AAA"),
+            _tool_use_block("toolu_1", "read_file", {"path": "a.py"}),
+            _thinking_block("A looked fine; now inspect B.", "sig-BBB"),
+            _tool_use_block("toolu_2", "read_file", {"path": "b.py"}),
+        ],
+        stop_reason="tool_use",
+        usage=None,
+    )
+
+
+def _stored_assistant_message(normalized) -> dict:
+    """Reconstruct the OpenAI-style assistant message the way run_agent stores it.
+
+    run_agent.py persists assistant turns as separate fields: content,
+    reasoning_details (from provider_data), and tool_calls.  See
+    run_agent.py L1513-1516 and hermes_state.py.
+    """
+    provider_data = normalized.provider_data or {}
+    tool_calls = []
+    for tc in (normalized.tool_calls or []):
+        tool_calls.append({
+            "id": tc.id,
+            "type": "function",
+            "function": {"name": tc.name, "arguments": tc.arguments},
+        })
+    msg = {
+        "role": "assistant",
+        "content": normalized.content or "",
+        "reasoning_details": provider_data.get("reasoning_details"),
+        "tool_calls": tool_calls,
+    }
+    # build_assistant_message lifts the verbatim ordered-block channel onto
+    # the stored message; mirror that here.
+    blocks = provider_data.get("anthropic_content_blocks")
+    if blocks:
+        msg["anthropic_content_blocks"] = blocks
+    return msg
+
+
+def _original_block_order(response) -> list:
+    """The (type, key) sequence of the original interleaved response."""
+    order = []
+    for b in response.content:
+        if b.type == "thinking":
+            order.append(("thinking", b.signature))
+        elif b.type == "tool_use":
+            order.append(("tool_use", b.id))
+    return order
+
+
+def _replayed_block_order(assistant_content) -> list:
+    order = []
+    for b in assistant_content:
+        if not isinstance(b, dict):
+            continue
+        if b.get("type") in ("thinking", "redacted_thinking"):
+            order.append(("thinking", b.get("signature")))
+        elif b.get("type") == "tool_use":
+            order.append(("tool_use", b.get("id")))
+    return order
+
+
+class TestInterleavedThinkingBlockOrder:
+    def test_normalize_response_loses_interleaving(self):
+        """Confirm the lossy split: normalize_response stores thinking and
+        tool_use in independent fields with no positional linkage."""
+        transport = get_transport("anthropic_messages")
+        normalized = transport.normalize_response(_interleaved_response())
+
+        # Both thinking blocks are captured...
+        details = (normalized.provider_data or {}).get("reasoning_details")
+        assert details is not None and len(details) == 2
+        # ...and both tool calls...
+        assert normalized.tool_calls is not None and len(normalized.tool_calls) == 2
+        # ...but they live in separate fields. There is no single ordered
+        # structure recording that thinking_2 sat between the two tool calls.
+        # (This is the structural precondition for the reorder bug.)
+
+    def test_interleaved_order_preserved_on_replay(self):
+        """The latest assistant message must replay blocks in their ORIGINAL
+        order, or Anthropic rejects the signed thinking blocks with a 400.
+
+        FAILS on current code: _convert_assistant_message front-loads all
+        thinking blocks, producing
+            thinking_1 · thinking_2 · tool_use_1 · tool_use_2
+        instead of the original
+            thinking_1 · tool_use_1 · thinking_2 · tool_use_2
+        """
+        response = _interleaved_response()
+        original_order = _original_block_order(response)
+
+        transport = get_transport("anthropic_messages")
+        normalized = transport.normalize_response(response)
+        assistant_msg = _stored_assistant_message(normalized)
+
+        # Build a minimal conversation where this assistant turn is the LATEST
+        # assistant message (the one whose signed blocks are sent verbatim).
+        messages = [
+            {"role": "user", "content": "Inspect a.py and b.py."},
+            assistant_msg,
+            {"role": "tool", "tool_call_id": "toolu_1", "content": "a.py: ok"},
+            {"role": "tool", "tool_call_id": "toolu_2", "content": "b.py: ok"},
+        ]
+
+        _system, anthropic_messages = convert_messages_to_anthropic(
+            messages,
+            base_url=None,             # direct Anthropic
+            model="claude-opus-4-8",   # adaptive thinking family
+        )
+
+        # Find the (latest) assistant message in the converted output.
+        assistant_out = [m for m in anthropic_messages if m.get("role") == "assistant"]
+        assert assistant_out, "no assistant message in converted output"
+        replayed_order = _replayed_block_order(assistant_out[-1]["content"])
+
+        assert replayed_order == original_order, (
+            "Interleaved thinking/tool_use order was not preserved on replay.\n"
+            f"  original: {original_order}\n"
+            f"  replayed: {replayed_order}\n"
+            "Anthropic signs thinking blocks against their original position; "
+            "reordering invalidates the signature -> HTTP 400 'thinking blocks "
+            "in the latest assistant message cannot be modified'."
+        )
+
+    def test_interleaved_order_survives_db_roundtrip(self, tmp_path):
+        """The ordered-block channel must survive SQLite persistence + reload.
+
+        This is the exact path that fails after a gateway crash: the session
+        is reloaded from state.db via get_messages_as_conversation, then
+        replayed. If the verbatim block list is dropped or not deserialized,
+        the reconstruction reorders signed thinking blocks -> HTTP 400.
+        """
+        import hermes_state
+
+        response = _interleaved_response()
+        original_order = _original_block_order(response)
+
+        transport = get_transport("anthropic_messages")
+        normalized = transport.normalize_response(response)
+        assistant_msg = _stored_assistant_message(normalized)
+
+        db = hermes_state.SessionDB(tmp_path / "state.db")
+        sid = "sess_roundtrip"
+        db.create_session(sid, source="test")
+        db.append_message(
+            session_id=sid,
+            role="assistant",
+            content=assistant_msg["content"],
+            tool_calls=assistant_msg["tool_calls"],
+            reasoning_details=assistant_msg.get("reasoning_details"),
+            anthropic_content_blocks=assistant_msg.get("anthropic_content_blocks"),
+        )
+        db.append_message(session_id=sid, role="tool", tool_call_id="toolu_1", content="a ok")
+        db.append_message(session_id=sid, role="tool", tool_call_id="toolu_2", content="b ok")
+
+        # Reload via the conversation-restore path used on resume / crash recovery.
+        loaded = db.get_messages_as_conversation(sid)
+        reloaded_assistant = [m for m in loaded if m.get("role") == "assistant"]
+        assert reloaded_assistant, "no assistant message after DB reload"
+        # The ordered-block channel must come back as a deserialized list.
+        blocks = reloaded_assistant[0].get("anthropic_content_blocks")
+        assert isinstance(blocks, list) and len(blocks) == 4, (
+            "anthropic_content_blocks was not persisted/deserialized correctly"
+        )
+
+        _system, anthropic_messages = convert_messages_to_anthropic(
+            loaded, base_url=None, model="claude-opus-4-8",
+        )
+        assistant_out = [m for m in anthropic_messages if m.get("role") == "assistant"]
+        assert assistant_out, "no assistant message in converted output"
+        replayed_order = _replayed_block_order(assistant_out[-1]["content"])
+
+        assert replayed_order == original_order, (
+            "Interleaved block order was lost across the SQLite round-trip.\n"
+            f"  original: {original_order}\n"
+            f"  replayed: {replayed_order}"
+        )
+
+
+if __name__ == "__main__":
+    raise SystemExit(pytest.main([__file__, "-v"]))

From 529bb1c3d516f7580af39d6095f0a7d97f7e9ad5 Mon Sep 17 00:00:00 2001
From: RaumfahrerSpiffy <56406949+RaumfahrerSpiffy@users.noreply.github.com>
Date: Sat, 30 May 2026 23:13:32 -0400
Subject: [PATCH 14/28] fix(anthropic): strip output-only SDK fields from
 replayed content blocks
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

HTTP 400 "messages.N.content.M.text.parsed_output: Extra inputs are not
permitted" on the native Anthropic transport. Anthropic SDK 0.87.0 response
blocks carry output-only attributes the Messages *input* schema forbids: text
blocks get `parsed_output` and `citations=None`, tool_use blocks get `caller`.
normalize_response captured blocks verbatim via _to_plain_data and replayed
them as request input on the next turn, so the forbidden fields leaked back ->
400. Like the earlier thinking-block bug, one poisoned turn wedges every
subsequent request in the session (even the diagnostic turn), recoverable only
by switching models or deleting the session.

This is a defect in the anthropic_content_blocks channel added for the
interleaved-thinking fix: it preserved block ORDER correctly but copied every
SDK attribute, including output-only ones.

Fix — whitelist input-permitted fields per block type at all three leak points:
- agent/transports/anthropic.py normalize_response: sanitize at CAPTURE so the
  poison never persists to state.db (defence-in-depth).
- agent/anthropic_adapter.py _sanitize_replay_block (new): whitelist used on the
  ordered-blocks replay path; also recovers already-poisoned stored sessions.
- agent/anthropic_adapter.py _convert_content_part_to_anthropic: a stored
  `text` part is rebuilt from whitelisted fields instead of dict(part) verbatim
  (this was the exact content.N.text.parsed_output failure locus).

Whitelist not blacklist, so future SDK output-only fields can't reintroduce it.
Block order and thinking-block signatures are preserved (the reason the channel
exists). Adds tests/agent/test_anthropic_output_field_leak.py; full adapter
suite green (163 tests). Existing poisoned state.db rows scrubbed out-of-band.
---
 agent/anthropic_adapter.py                    | 85 +++++++++++++---
 agent/transports/anthropic.py                 | 18 +++-
 .../agent/test_anthropic_output_field_leak.py | 96 +++++++++++++++++++
 3 files changed, 182 insertions(+), 17 deletions(-)
 create mode 100644 tests/agent/test_anthropic_output_field_leak.py

diff --git a/agent/anthropic_adapter.py b/agent/anthropic_adapter.py
index 25ee73580f78..a95fd2f10f4f 100644
--- a/agent/anthropic_adapter.py
+++ b/agent/anthropic_adapter.py
@@ -1571,6 +1571,15 @@ def _convert_content_part_to_anthropic(part: Any) -> Optional[Dict[str, Any]]:
 
     if ptype == "input_text":
         block: Dict[str, Any] = {"type": "text", "text": part.get("text", "")}
+    elif ptype == "text":
+        # A stored Anthropic text block. Rebuild from whitelisted fields only —
+        # SDK response text blocks carry output-only siblings (parsed_output,
+        # citations=None) that the Messages INPUT schema rejects with HTTP 400
+        # "Extra inputs are not permitted". Do NOT dict(part) it verbatim.
+        block = {"type": "text", "text": part.get("text", "")}
+        cits = part.get("citations")
+        if isinstance(cits, list) and cits:
+            block["citations"] = cits
     elif ptype in {"image_url", "input_image"}:
         image_value = part.get("image_url", {})
         url = image_value.get("url", "") if isinstance(image_value, dict) else str(image_value or "")
@@ -1685,6 +1694,58 @@ def _content_parts_to_anthropic_blocks(parts: Any) -> List[Dict[str, Any]]:
     return out
 
 
+def _sanitize_replay_block(b: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+    """Strip output-only fields from a stored Anthropic content block so it is
+    valid as REQUEST input on replay.
+
+    The SDK response objects carry output-only attributes that the Messages
+    *input* schema forbids ("Extra inputs are not permitted"): text blocks get
+    ``parsed_output``/``citations`` (when null), tool_use blocks get ``caller``,
+    etc. ``normalize_response`` captured blocks verbatim via ``_to_plain_data``,
+    so these leak back as input on the next turn → HTTP 400.
+
+    Whitelist per type (NOT a blacklist) so future SDK output-only fields can't
+    reintroduce the bug. Returns a clean block, or None to drop it.
+    """
+    if not isinstance(b, dict):
+        return None
+    btype = b.get("type")
+    if btype == "text":
+        out: Dict[str, Any] = {"type": "text", "text": b.get("text", "")}
+        # citations is input-valid ONLY when it's a non-empty list; the SDK
+        # emits citations=None on responses, which the input schema rejects.
+        cits = b.get("citations")
+        if isinstance(cits, list) and cits:
+            out["citations"] = cits
+        if isinstance(b.get("cache_control"), dict):
+            out["cache_control"] = b["cache_control"]
+        return out
+    if btype == "thinking":
+        out = {"type": "thinking", "thinking": b.get("thinking", "")}
+        if b.get("signature"):
+            out["signature"] = b["signature"]
+        return out
+    if btype == "redacted_thinking":
+        # Only valid with its data payload; drop if missing.
+        return {"type": "redacted_thinking", "data": b["data"]} if b.get("data") else None
+    if btype == "tool_use":
+        out = {
+            "type": "tool_use",
+            "id": _sanitize_tool_id(b.get("id", "")),
+            "name": b.get("name", ""),
+            "input": b.get("input", {}),
+        }
+        if isinstance(b.get("cache_control"), dict):
+            out["cache_control"] = b["cache_control"]
+        return out
+    if btype == "image":
+        src = b.get("source")
+        return {"type": "image", "source": src} if isinstance(src, dict) else None
+    # Unknown/unsupported block type on the input path — drop rather than risk
+    # another "Extra inputs are not permitted".
+    return None
+
+
 def _convert_assistant_message(m: Dict[str, Any]) -> Dict[str, Any]:
     """Convert an assistant message to Anthropic content blocks.
 
@@ -1694,24 +1755,20 @@ def _convert_assistant_message(m: Dict[str, Any]) -> Dict[str, Any]:
     content = m.get("content", "")
     # Anthropic interleaved-thinking fast path: when this turn carries a
     # verbatim, order-preserving block list (set by normalize_response only
-    # for turns that interleave SIGNED thinking with tool_use), replay it
-    # unchanged. Reconstructing from the parallel reasoning_details +
-    # tool_calls fields front-loads thinking and reorders signed blocks,
-    # which Anthropic rejects with HTTP 400 ("thinking ... blocks in the
-    # latest assistant message cannot be modified"). Block order — and thus
-    # each thinking block's signature — must survive verbatim. tool_use IDs
-    # are sanitized to match the tool_result IDs produced elsewhere; the
-    # downstream mcp_ prefixing pass handles tool names on these blocks.
+    # for turns that interleave SIGNED thinking with tool_use), replay it.
+    # Each block is run through _sanitize_replay_block to strip output-only
+    # SDK fields (parsed_output, caller, citations=None, …) that the Messages
+    # INPUT schema forbids — replaying them verbatim caused HTTP 400 "Extra
+    # inputs are not permitted" (text.parsed_output). Block ORDER is preserved
+    # (the reason this channel exists); only forbidden sibling fields are
+    # dropped, leaving thinking signatures and tool_use id/name/input intact.
     ordered_blocks = m.get("anthropic_content_blocks")
     if isinstance(ordered_blocks, list) and ordered_blocks:
         replayed: List[Dict[str, Any]] = []
         for b in ordered_blocks:
-            if not isinstance(b, dict):
-                continue
-            blk = copy.deepcopy(b)
-            if blk.get("type") == "tool_use" and "id" in blk:
-                blk["id"] = _sanitize_tool_id(blk.get("id", ""))
-            replayed.append(blk)
+            clean = _sanitize_replay_block(b)
+            if clean is not None:
+                replayed.append(clean)
         if replayed:
             return {"role": "assistant", "content": replayed}
 
diff --git a/agent/transports/anthropic.py b/agent/transports/anthropic.py
index e7c99751c7c5..3a209f2d753b 100644
--- a/agent/transports/anthropic.py
+++ b/agent/transports/anthropic.py
@@ -84,7 +84,7 @@ class AnthropicTransport(ProviderTransport):
         to OpenAI finish_reason, and collects reasoning_details in provider_data.
         """
         import json
-        from agent.anthropic_adapter import _to_plain_data
+        from agent.anthropic_adapter import _to_plain_data, _sanitize_replay_block
         from agent.transports.types import ToolCall
 
         strip_tool_prefix = kwargs.get("strip_tool_prefix", False)
@@ -108,14 +108,26 @@ class AnthropicTransport(ProviderTransport):
 
         for block in response.content:
             block_dict = _to_plain_data(block)
+            clean_block = None
             if isinstance(block_dict, dict):
-                ordered_blocks.append(block_dict)
+                # Sanitize at capture so output-only SDK fields (parsed_output,
+                # caller, citations=None, …) never persist to state.db and leak
+                # back as request input on replay → HTTP 400 "Extra inputs are
+                # not permitted". Defence-in-depth with the replay-side sanitize.
+                clean_block = _sanitize_replay_block(block_dict)
+                if clean_block is not None:
+                    ordered_blocks.append(clean_block)
             if block.type == "text":
                 text_parts.append(block.text)
             elif block.type in ("thinking", "redacted_thinking"):
                 if block.type == "thinking":
                     reasoning_parts.append(block.thinking)
-                if isinstance(block_dict, dict):
+                # Use the sanitized block (clean_block) for reasoning_details too,
+                # since _extract_preserved_thinking_blocks replays these on the
+                # non-ordered path. Falls back to raw only if sanitize dropped it.
+                if isinstance(clean_block, dict):
+                    reasoning_details.append(clean_block)
+                elif isinstance(block_dict, dict):
                     reasoning_details.append(block_dict)
             elif block.type == "tool_use":
                 name = block.name
diff --git a/tests/agent/test_anthropic_output_field_leak.py b/tests/agent/test_anthropic_output_field_leak.py
new file mode 100644
index 000000000000..a691f34ec0b8
--- /dev/null
+++ b/tests/agent/test_anthropic_output_field_leak.py
@@ -0,0 +1,96 @@
+"""Regression: output-only SDK fields must not leak into Anthropic request input.
+
+Reproduces HTTP 400 `messages.N.content.M.text.parsed_output: Extra inputs are
+not permitted`. Anthropic SDK response blocks carry output-only attributes
+(text blocks: `parsed_output`, `citations=None`; tool_use blocks: `caller`)
+that the Messages *input* schema forbids. normalize_response captured blocks
+verbatim via _to_plain_data and replayed them as input → 400.
+
+Fix: whitelist input-permitted fields per block type at three points —
+normalize_response capture, _sanitize_replay_block (ordered-blocks replay), and
+_convert_content_part_to_anthropic (content-list replay).
+"""
+import sys, os
+sys.path.insert(0, os.path.expanduser("~/.hermes/hermes-agent"))
+
+import pytest
+from agent.anthropic_adapter import (
+    _sanitize_replay_block,
+    _convert_content_part_to_anthropic,
+    _convert_assistant_message,
+)
+
+FORBIDDEN = {"parsed_output", "caller"}
+
+
+def _assert_clean(block):
+    """No forbidden output-only key, and no null citations, anywhere."""
+    assert isinstance(block, dict)
+    for k in FORBIDDEN:
+        assert k not in block, f"forbidden field {k!r} survived: {block}"
+    if "citations" in block:
+        assert isinstance(block["citations"], list) and block["citations"], \
+            "citations must be a non-empty list if present (None/[] is input-invalid)"
+
+
+class TestSanitizeReplayBlock:
+    def test_text_block_strips_parsed_output_and_null_citations(self):
+        poisoned = {"type": "text", "text": "hi", "parsed_output": None, "citations": None}
+        out = _sanitize_replay_block(poisoned)
+        _assert_clean(out)
+        assert out == {"type": "text", "text": "hi"}
+
+    def test_tool_use_strips_caller(self):
+        poisoned = {"type": "tool_use", "id": "toolu_1", "name": "read_file",
+                    "input": {"path": "a"}, "caller": {"type": "agent"}}
+        out = _sanitize_replay_block(poisoned)
+        _assert_clean(out)
+        assert out["name"] == "read_file" and out["input"] == {"path": "a"}
+
+    def test_thinking_preserves_signature(self):
+        b = {"type": "thinking", "thinking": "x", "signature": "sig-AAA"}
+        out = _sanitize_replay_block(b)
+        assert out == {"type": "thinking", "thinking": "x", "signature": "sig-AAA"}
+
+    def test_text_keeps_real_citations(self):
+        real = [{"type": "char_location", "cited_text": "q"}]
+        out = _sanitize_replay_block({"type": "text", "text": "t", "citations": real})
+        assert out["citations"] == real
+
+    def test_unknown_type_dropped(self):
+        assert _sanitize_replay_block({"type": "server_tool_use", "foo": 1}) is None
+
+
+class TestContentPartConversion:
+    def test_stored_text_block_with_parsed_output_cleaned(self):
+        # The exact content.N.text.parsed_output failure shape.
+        part = {"type": "text", "text": "hello", "parsed_output": None, "citations": None}
+        out = _convert_content_part_to_anthropic(part)
+        _assert_clean(out)
+
+
+class TestAssistantReplay:
+    def test_interleaved_blocks_replayed_clean_and_ordered(self):
+        m = {
+            "role": "assistant",
+            "anthropic_content_blocks": [
+                {"type": "thinking", "thinking": "plan", "signature": "s1"},
+                {"type": "text", "text": "doing it", "parsed_output": None, "citations": None},
+                {"type": "tool_use", "id": "toolu_1", "name": "read_file",
+                 "input": {"path": "a"}, "caller": {"type": "agent"}},
+            ],
+        }
+        out = _convert_assistant_message(m)
+        blocks = out["content"]
+        # order preserved
+        assert [b["type"] for b in blocks] == ["thinking", "text", "tool_use"]
+        # every block clean
+        for b in blocks:
+            _assert_clean(b)
+        # signature + tool fields intact
+        assert blocks[0]["signature"] == "s1"
+        assert blocks[2]["name"] == "read_file"
+
+
+if __name__ == "__main__":
+    raise SystemExit(pytest.main([__file__, "-v"]))

From 7a1eed8268a7cb9112c8e4a29c868009d7137315 Mon Sep 17 00:00:00 2001
From: RaumfahrerSpiffy <56406949+RaumfahrerSpiffy@users.noreply.github.com>
Date: Sun, 31 May 2026 21:45:18 -0400
Subject: [PATCH 15/28] fix(anthropic): redact replayed tool inputs and broaden
 thinking-replay 400 recovery
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two additive hardening changes on the interleaved-thinking replay path
introduced by this PR's anthropic_content_blocks channel. Both are scoped
to that channel's blast radius; neither changes correct behavior.

1. Replay-time tool-input re-sourcing (credential safety).
   The ordered-block channel captures each tool_use `input` from the RAW
   API response in normalize_response, which is NOT credential-redacted.
   The parallel tool_calls[].function.arguments IS redacted at storage
   time (build_assistant_message, #19798). The verbatim-replay fast path
   in _convert_assistant_message replayed the raw block input, so a secret
   a model inlined into a tool call (e.g. an Authorization header value
   passed inside a terminal command) would ride back onto the wire even
   though it is redacted everywhere else in history. Re-source tool_use
   input from the redacted tool_calls map by
   sanitized id; interleave order (the reason this channel exists) is
   unaffected. Adapted from #36071, which re-sources tool inputs the same
   way on its replay path.

2. Broaden the thinking-replay 400 classifier (defense-in-depth).
   error_classifier only matched "signature" + "thinking", so the
   frozen-block variant — "thinking ... blocks in the latest assistant
   message cannot be modified. These blocks must remain as they were in
   the original response." — carried no "signature" token and fell through
   to a non-retryable abort. The anthropic_content_blocks channel prevents
   the reorder that triggers this 400 at the source, but if any future
   mutator reintroduces it, the turn now self-heals via the existing
   strip-reasoning-and-retry recovery instead of crash-looping. A negative
   case ensures an unrelated "cannot be modified" 400 (no "thinking") is
   not swept in. Mirrors the classifier broadening in #36087 and #36071.

Tests
- tests/agent/test_anthropic_thinking_block_order.py: a replay test
  asserting an inlined secret is redacted on the wire while interleave
  order is preserved.
- tests/agent/test_error_classifier.py: three cases — frozen-block 400
  native and via OpenRouter route to thinking_signature/retryable; an
  unrelated "cannot be modified" 400 does not.
Both grafts verified RED (tests fail with the change reverted) then GREEN.
Full adapter, transport, classifier and output-field-leak suites pass.

Co-authored-by: AlexanderBFoley <92330381+AlexanderBFoley@users.noreply.github.com>
---
 agent/anthropic_adapter.py                    | 34 ++++++-
 .../test_anthropic_thinking_block_order.py    | 99 +++++++++++++++++++
 2 files changed, 131 insertions(+), 2 deletions(-)

diff --git a/agent/anthropic_adapter.py b/agent/anthropic_adapter.py
index a95fd2f10f4f..8476ef67f57f 100644
--- a/agent/anthropic_adapter.py
+++ b/agent/anthropic_adapter.py
@@ -1764,11 +1764,41 @@ def _convert_assistant_message(m: Dict[str, Any]) -> Dict[str, Any]:
     # dropped, leaving thinking signatures and tool_use id/name/input intact.
     ordered_blocks = m.get("anthropic_content_blocks")
     if isinstance(ordered_blocks, list) and ordered_blocks:
+        # Re-source each tool_use input from the stored tool_calls map rather
+        # than the captured block. The ordered-blocks list captures tool_use
+        # input from the RAW API response (normalize_response), which is NOT
+        # credential-redacted; tool_calls[].function.arguments IS redacted at
+        # storage time (build_assistant_message, #19798). Replaying the raw
+        # block input would resurrect a secret the model inlined into a tool
+        # call (e.g. terminal(command="curl -H 'Authorization: Bearer sk-...'")
+        # onto the wire, even though the same value is redacted everywhere else
+        # in history. Keying by sanitized tool id preserves interleave order
+        # (the reason this channel exists) while swapping in the redacted
+        # input. Adapted from #36071 (replay-time tool-input re-sourcing).
+        redacted_input_by_id: Dict[str, Any] = {}
+        for tc in m.get("tool_calls", []) or []:
+            if not isinstance(tc, dict):
+                continue
+            fn = tc.get("function", {}) or {}
+            raw_args = fn.get("arguments", "{}")
+            try:
+                parsed_args = json.loads(raw_args) if isinstance(raw_args, str) else raw_args
+            except (json.JSONDecodeError, ValueError):
+                parsed_args = {}
+            redacted_input_by_id[_sanitize_tool_id(tc.get("id", ""))] = parsed_args
         replayed: List[Dict[str, Any]] = []
         for b in ordered_blocks:
             clean = _sanitize_replay_block(b)
-            if clean is not None:
-                replayed.append(clean)
+            if clean is None:
+                continue
+            if clean.get("type") == "tool_use":
+                # Override raw (un-redacted) input with the redacted copy when
+                # we have one for this id; fall back to the sanitized block
+                # input only if the tool_call is missing (shape mismatch).
+                redacted = redacted_input_by_id.get(clean.get("id", ""))
+                if redacted is not None:
+                    clean["input"] = redacted
+            replayed.append(clean)
         if replayed:
             return {"role": "assistant", "content": replayed}
 
diff --git a/tests/agent/test_anthropic_thinking_block_order.py b/tests/agent/test_anthropic_thinking_block_order.py
index a02c5a9eb77e..3d090983f006 100644
--- a/tests/agent/test_anthropic_thinking_block_order.py
+++ b/tests/agent/test_anthropic_thinking_block_order.py
@@ -231,5 +231,104 @@ class TestInterleavedThinkingBlockOrder:
         )
 
 
+class TestInterleavedReplayCredentialRedaction:
+    """The verbatim-replay fast path must not leak un-redacted secrets.
+
+    anthropic_content_blocks captures each tool_use ``input`` from the RAW API
+    response (normalize_response), which is NOT credential-redacted. The
+    parallel tool_calls[].function.arguments IS redacted at storage time
+    (build_assistant_message, #19798). If the fast path replays the block's raw
+    input verbatim, a secret the model inlined into a tool call rides back onto
+    the wire — even though it is redacted everywhere else in history. The fix
+    re-sources tool_use input from the redacted tool_calls map by id.
+    """
+
+    def test_tool_use_input_resourced_from_redacted_tool_calls(self):
+        REDACTED = "[REDACTED_SECRET]"
+        # Ordered channel: raw input carries the live secret (as captured from
+        # the unredacted API response).
+        ordered = [
+            {"type": "thinking", "thinking": "Call the API.", "signature": "sig-AAA"},
+            {
+                "type": "tool_use",
+                "id": "toolu_1",
+                "name": "terminal",
+                "input": {"command": "curl -H 'Authorization: Bearer sk-LIVE-SECRET-123'"},
+            },
+            {"type": "thinking", "thinking": "Now the second call.", "signature": "sig-BBB"},
+            {
+                "type": "tool_use",
+                "id": "toolu_2",
+                "name": "terminal",
+                "input": {"command": "echo done"},
+            },
+        ]
+        # Stored tool_calls: arguments already redacted (the #19798 path).
+        assistant_msg = {
+            "role": "assistant",
+            "content": "",
+            "reasoning_details": [b for b in ordered if b["type"] == "thinking"],
+            "tool_calls": [
+                {
+                    "id": "toolu_1",
+                    "type": "function",
+                    "function": {
+                        "name": "terminal",
+                        "arguments": json.dumps(
+                            {"command": f"curl -H 'Authorization: Bearer {REDACTED}'"}
+                        ),
+                    },
+                },
+                {
+                    "id": "toolu_2",
+                    "type": "function",
+                    "function": {
+                        "name": "terminal",
+                        "arguments": json.dumps({"command": "echo done"}),
+                    },
+                },
+            ],
+            "anthropic_content_blocks": ordered,
+        }
+        messages = [
+            {"role": "user", "content": "Hit the API twice."},
+            assistant_msg,
+            {"role": "tool", "tool_call_id": "toolu_1", "content": "200 OK"},
+            {"role": "tool", "tool_call_id": "toolu_2", "content": "done"},
+        ]
+
+        _system, anthropic_messages = convert_messages_to_anthropic(
+            messages, base_url=None, model="claude-opus-4-8",
+        )
+        assistant_out = [m for m in anthropic_messages if m.get("role") == "assistant"]
+        assert assistant_out, "no assistant message in converted output"
+        blocks = assistant_out[-1]["content"]
+
+        tool_uses = {b["id"]: b for b in blocks if b.get("type") == "tool_use"}
+        assert set(tool_uses) == {"toolu_1", "toolu_2"}, "tool_use blocks missing/renamed"
+
+        # The replayed input must be the REDACTED value, not the live secret.
+        replayed_cmd = tool_uses["toolu_1"]["input"]["command"]
+        assert "sk-LIVE-SECRET-123" not in replayed_cmd, (
+            "Un-redacted secret leaked onto the wire via the verbatim-replay "
+            "fast path. tool_use input must be re-sourced from the redacted "
+            "tool_calls map, not the raw captured block."
+        )
+        assert REDACTED in replayed_cmd
+
+        # Interleave order is still preserved (the reason the channel exists).
+        order = [
+            ("thinking", b.get("signature")) if b.get("type") == "thinking"
+            else ("tool_use", b.get("id"))
+            for b in blocks if b.get("type") in ("thinking", "tool_use")
+        ]
+        assert order == [
+            ("thinking", "sig-AAA"),
+            ("tool_use", "toolu_1"),
+            ("thinking", "sig-BBB"),
+            ("tool_use", "toolu_2"),
+        ]
+
+
 if __name__ == "__main__":
     raise SystemExit(pytest.main([__file__, "-v"]))

From efcbbde48c38acbf3489ec1f7fc91ce1a30822f4 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Wed, 10 Jun 2026 19:59:57 -0700
Subject: [PATCH 16/28] refactor: keep anthropic_content_blocks in-memory only
 (no state.db column)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Drop the hermes_state.py column + persistence plumbing from the salvaged
interleaved-thinking fix. The ordered-block channel covers the failure
window in-memory (turn replayed within the live conversation loop). A
session reloaded from disk after a crash falls back to reconstruction;
if that replay 400s, the thinking-signature recovery (#43667) strips
reasoning_details and retries — one degraded call in a rare resume path
instead of a schema column. Replaces the DB-roundtrip test with a
fallback-shape test.
---
 hermes_state.py                               | 31 ++-------
 run_agent.py                                  |  1 -
 .../test_anthropic_thinking_block_order.py    | 64 +++++++------------
 3 files changed, 26 insertions(+), 70 deletions(-)

diff --git a/hermes_state.py b/hermes_state.py
index 7b8a2bfcfb4b..bda6eeacd628 100644
--- a/hermes_state.py
+++ b/hermes_state.py
@@ -488,7 +488,6 @@ CREATE TABLE IF NOT EXISTS messages (
     reasoning TEXT,
     reasoning_content TEXT,
     reasoning_details TEXT,
-    anthropic_content_blocks TEXT,
     codex_reasoning_items TEXT,
     codex_message_items TEXT,
     platform_message_id TEXT,
@@ -2241,7 +2240,6 @@ class SessionDB:
         reasoning: str = None,
         reasoning_content: str = None,
         reasoning_details: Any = None,
-        anthropic_content_blocks: Any = None,
         codex_reasoning_items: Any = None,
         codex_message_items: Any = None,
         platform_message_id: str = None,
@@ -2264,10 +2262,6 @@ class SessionDB:
             json.dumps(reasoning_details)
             if reasoning_details else None
         )
-        anthropic_content_blocks_json = (
-            json.dumps(anthropic_content_blocks)
-            if anthropic_content_blocks else None
-        )
         codex_items_json = (
             json.dumps(codex_reasoning_items)
             if codex_reasoning_items else None
@@ -2290,10 +2284,9 @@ class SessionDB:
             cursor = conn.execute(
                 """INSERT INTO messages (session_id, role, content, tool_call_id,
                    tool_calls, tool_name, timestamp, token_count, finish_reason,
-                   reasoning, reasoning_content, reasoning_details, anthropic_content_blocks,
-                   codex_reasoning_items,
+                   reasoning, reasoning_content, reasoning_details, codex_reasoning_items,
                    codex_message_items, platform_message_id, observed)
-                   VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
+                   VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
                 (
                     session_id,
                     role,
@@ -2307,7 +2300,6 @@ class SessionDB:
                     reasoning,
                     reasoning_content,
                     reasoning_details_json,
-                    anthropic_content_blocks_json,
                     codex_items_json,
                     codex_message_items_json,
                     platform_message_id,
@@ -2356,9 +2348,6 @@ class SessionDB:
                 role = msg.get("role", "unknown")
                 tool_calls = msg.get("tool_calls")
                 reasoning_details = msg.get("reasoning_details") if role == "assistant" else None
-                anthropic_content_blocks = (
-                    msg.get("anthropic_content_blocks") if role == "assistant" else None
-                )
                 codex_reasoning_items = (
                     msg.get("codex_reasoning_items") if role == "assistant" else None
                 )
@@ -2369,9 +2358,6 @@ class SessionDB:
                 reasoning_details_json = (
                     json.dumps(reasoning_details) if reasoning_details else None
                 )
-                anthropic_content_blocks_json = (
-                    json.dumps(anthropic_content_blocks) if anthropic_content_blocks else None
-                )
                 codex_items_json = (
                     json.dumps(codex_reasoning_items) if codex_reasoning_items else None
                 )
@@ -2388,10 +2374,9 @@ class SessionDB:
                 conn.execute(
                     """INSERT INTO messages (session_id, role, content, tool_call_id,
                        tool_calls, tool_name, timestamp, token_count, finish_reason,
-                       reasoning, reasoning_content, reasoning_details, anthropic_content_blocks,
-                       codex_reasoning_items,
+                       reasoning, reasoning_content, reasoning_details, codex_reasoning_items,
                        codex_message_items, platform_message_id, observed)
-                       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
+                       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
                     (
                         session_id,
                         role,
@@ -2405,7 +2390,6 @@ class SessionDB:
                         msg.get("reasoning") if role == "assistant" else None,
                         msg.get("reasoning_content") if role == "assistant" else None,
                         reasoning_details_json,
-                        anthropic_content_blocks_json,
                         codex_items_json,
                         codex_message_items_json,
                         platform_msg_id,
@@ -2748,7 +2732,6 @@ class SessionDB:
             rows = self._conn.execute(
                 "SELECT role, content, tool_call_id, tool_calls, tool_name, "
                 "finish_reason, reasoning, reasoning_content, reasoning_details, "
-                "anthropic_content_blocks, "
                 "codex_reasoning_items, codex_message_items, platform_message_id, observed "
                 f"FROM messages WHERE session_id IN ({placeholders})"
                 f"{active_clause} ORDER BY id",
@@ -2796,12 +2779,6 @@ class SessionDB:
                     except (json.JSONDecodeError, TypeError):
                         logger.warning("Failed to deserialize reasoning_details, falling back to None")
                         msg["reasoning_details"] = None
-                if row["anthropic_content_blocks"]:
-                    try:
-                        msg["anthropic_content_blocks"] = json.loads(row["anthropic_content_blocks"])
-                    except (json.JSONDecodeError, TypeError):
-                        logger.warning("Failed to deserialize anthropic_content_blocks, falling back to None")
-                        msg["anthropic_content_blocks"] = None
                 if row["codex_reasoning_items"]:
                     try:
                         msg["codex_reasoning_items"] = json.loads(row["codex_reasoning_items"])
diff --git a/run_agent.py b/run_agent.py
index eda39064c551..e81bf3b93e7e 100644
--- a/run_agent.py
+++ b/run_agent.py
@@ -1597,7 +1597,6 @@ class AIAgent:
                     reasoning=msg.get("reasoning") if role == "assistant" else None,
                     reasoning_content=msg.get("reasoning_content") if role == "assistant" else None,
                     reasoning_details=msg.get("reasoning_details") if role == "assistant" else None,
-                    anthropic_content_blocks=msg.get("anthropic_content_blocks") if role == "assistant" else None,
                     codex_reasoning_items=msg.get("codex_reasoning_items") if role == "assistant" else None,
                     codex_message_items=msg.get("codex_message_items") if role == "assistant" else None,
                 )
diff --git a/tests/agent/test_anthropic_thinking_block_order.py b/tests/agent/test_anthropic_thinking_block_order.py
index 3d090983f006..5455b3339a76 100644
--- a/tests/agent/test_anthropic_thinking_block_order.py
+++ b/tests/agent/test_anthropic_thinking_block_order.py
@@ -176,59 +176,39 @@ class TestInterleavedThinkingBlockOrder:
             "in the latest assistant message cannot be modified'."
         )
 
-    def test_interleaved_order_survives_db_roundtrip(self, tmp_path):
-        """The ordered-block channel must survive SQLite persistence + reload.
+    def test_replay_falls_back_gracefully_without_ordered_blocks(self):
+        """Without the ordered-block channel, conversion must not crash.
 
-        This is the exact path that fails after a gateway crash: the session
-        is reloaded from state.db via get_messages_as_conversation, then
-        replayed. If the verbatim block list is dropped or not deserialized,
-        the reconstruction reorders signed thinking blocks -> HTTP 400.
+        The channel is intentionally NOT persisted to state.db (in-memory
+        only): a session reloaded from disk after a crash loses the field
+        and falls back to reconstruction. That replay may take one HTTP 400,
+        which the thinking-signature recovery (#43667) absorbs by stripping
+        reasoning_details and retrying. This test pins the fallback shape:
+        conversion still produces a valid assistant message from the
+        parallel reasoning_details + tool_calls fields.
         """
-        import hermes_state
-
         response = _interleaved_response()
-        original_order = _original_block_order(response)
-
         transport = get_transport("anthropic_messages")
         normalized = transport.normalize_response(response)
         assistant_msg = _stored_assistant_message(normalized)
+        # Simulate a disk reload: the in-memory-only channel is gone.
+        assistant_msg.pop("anthropic_content_blocks", None)
 
-        db = hermes_state.SessionDB(tmp_path / "state.db")
-        sid = "sess_roundtrip"
-        db.create_session(sid, source="test")
-        db.append_message(
-            session_id=sid,
-            role="assistant",
-            content=assistant_msg["content"],
-            tool_calls=assistant_msg["tool_calls"],
-            reasoning_details=assistant_msg.get("reasoning_details"),
-            anthropic_content_blocks=assistant_msg.get("anthropic_content_blocks"),
-        )
-        db.append_message(session_id=sid, role="tool", tool_call_id="toolu_1", content="a ok")
-        db.append_message(session_id=sid, role="tool", tool_call_id="toolu_2", content="b ok")
-
-        # Reload via the conversation-restore path used on resume / crash recovery.
-        loaded = db.get_messages_as_conversation(sid)
-        reloaded_assistant = [m for m in loaded if m.get("role") == "assistant"]
-        assert reloaded_assistant, "no assistant message after DB reload"
-        # The ordered-block channel must come back as a deserialized list.
-        blocks = reloaded_assistant[0].get("anthropic_content_blocks")
-        assert isinstance(blocks, list) and len(blocks) == 4, (
-            "anthropic_content_blocks was not persisted/deserialized correctly"
-        )
-
+        messages = [
+            assistant_msg,
+            {"role": "tool", "tool_call_id": "toolu_1", "content": "a ok"},
+            {"role": "tool", "tool_call_id": "toolu_2", "content": "b ok"},
+        ]
         _system, anthropic_messages = convert_messages_to_anthropic(
-            loaded, base_url=None, model="claude-opus-4-8",
+            messages, base_url=None, model="claude-opus-4-8",
         )
         assistant_out = [m for m in anthropic_messages if m.get("role") == "assistant"]
         assert assistant_out, "no assistant message in converted output"
-        replayed_order = _replayed_block_order(assistant_out[-1]["content"])
-
-        assert replayed_order == original_order, (
-            "Interleaved block order was lost across the SQLite round-trip.\n"
-            f"  original: {original_order}\n"
-            f"  replayed: {replayed_order}"
-        )
+        content = assistant_out[-1]["content"]
+        assert isinstance(content, list) and content, "fallback produced empty content"
+        # Reconstruction keeps both tool_use blocks (answered by results).
+        tool_ids = [b.get("id") for b in content if isinstance(b, dict) and b.get("type") == "tool_use"]
+        assert set(tool_ids) == {"toolu_1", "toolu_2"}
 
 
 class TestInterleavedReplayCredentialRedaction:

From 68ffedb6a967b78d59bf776061cbd3f20ab3c213 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Wed, 10 Jun 2026 20:01:12 -0700
Subject: [PATCH 17/28] chore(release): map Spaceman-Spiffy for #35586 salvage

---
 scripts/release.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/scripts/release.py b/scripts/release.py
index 68ad134d6cdb..40bc154d0fb1 100755
--- a/scripts/release.py
+++ b/scripts/release.py
@@ -944,6 +944,7 @@ AUTHOR_MAP = {
     "michel.belleau@malaiwah.com": "malaiwah",
     "gnanasekaran.sekareee@gmail.com": "gnanam1990",
     "jz.pentest@gmail.com": "0xyg3n",
+    "56406949+RaumfahrerSpiffy@users.noreply.github.com": "Spaceman-Spiffy",  # PR #35586 (renamed account)
     "ian@culling.ca": "ianculling",  # PR #36087
     "7093928+0xyg3n@users.noreply.github.com": "0xyg3n",
     "nftpoetrist@gmail.com": "nftpoetrist",  # PR #18982

From 7d8d000b1921cb1c14aa137a41bd96203992e2c0 Mon Sep 17 00:00:00 2001
From: Teknium <127238744+teknium1@users.noreply.github.com>
Date: Wed, 10 Jun 2026 20:46:17 -0700
Subject: [PATCH 18/28] revert(cron): remove per-job profile support (PR
 #28124) (#43956)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Fully removes the cron per-job 'profile' arg added in #28124: the
cronjob tool schema field, CLI --profile flags on cron create/edit,
job-record storage/validation, the scheduler's _job_profile_context
wrapper, and the script-runner env override. Sequential-partition
logic reverts to workdir-only.

The context-local HERMES_HOME override in hermes_constants and the
subprocess bridging in tools/environments/local.py are kept — they
now have other consumers (dashboard multi-profile, TUI gateway).
---
 cron/jobs.py                             |  44 ---
 cron/scheduler.py                        | 123 +------
 hermes_cli/cron.py                       |   9 -
 hermes_cli/subcommands/cron.py           |   8 -
 tests/cron/test_cron_profile.py          | 449 -----------------------
 tests/cron/test_parallel_pool.py         |   6 +-
 tests/cron/test_scheduler.py             |   2 +-
 tests/hermes_cli/test_cron.py            |   6 -
 tools/cronjob_tools.py                   |  13 -
 website/docs/user-guide/features/cron.md |  31 +-
 10 files changed, 19 insertions(+), 672 deletions(-)
 delete mode 100644 tests/cron/test_cron_profile.py

diff --git a/cron/jobs.py b/cron/jobs.py
index 866dacc41dfc..52d9367ff84e 100644
--- a/cron/jobs.py
+++ b/cron/jobs.py
@@ -150,9 +150,6 @@ def _normalize_job_record(job: Dict[str, Any]) -> Dict[str, Any]:
         state = "scheduled" if normalized.get("enabled", True) else "paused"
     normalized["state"] = state
 
-    profile = _coerce_job_text(normalized.get("profile")).strip()
-    normalized["profile"] = profile or None
-
     return normalized
 
 
@@ -523,30 +520,6 @@ def _normalize_workdir(workdir: Optional[str]) -> Optional[str]:
     return str(resolved)
 
 
-def _normalize_profile(profile: Optional[str]) -> Optional[str]:
-    """Normalize and validate an optional cron job profile name.
-
-    Empty / None disables per-job profile selection. Otherwise the profile name
-    is canonicalized with the same rules as ``hermes -p`` and must refer to an
-    existing profile at create/update time. ``default`` is the built-in root
-    profile and is always valid.
-    """
-    if profile is None:
-        return None
-    raw = str(profile).strip()
-    if not raw:
-        return None
-
-    from hermes_cli.profiles import normalize_profile_name, resolve_profile_env
-
-    normalized = normalize_profile_name(raw)
-    # resolve_profile_env validates the canonical name and checks that named
-    # profiles exist. Store only the stable profile id, not the filesystem path,
-    # so profile directories can move with the Hermes root.
-    resolve_profile_env(normalized)
-    return normalized
-
-
 def create_job(
     prompt: Optional[str],
     schedule: str,
@@ -563,7 +536,6 @@ def create_job(
     context_from: Optional[Union[str, List[str]]] = None,
     enabled_toolsets: Optional[List[str]] = None,
     workdir: Optional[str] = None,
-    profile: Optional[str] = None,
     no_agent: bool = False,
 ) -> Dict[str, Any]:
     """
@@ -605,11 +577,6 @@ def create_job(
                 With ``no_agent=True``, ``workdir`` is still applied as the
                 script's cwd so relative paths inside the script behave
                 predictably.
-        profile: Optional Hermes profile name. When set, the job runs with
-                that profile's HERMES_HOME so profile-specific config,
-                credentials, scripts, skills, and memory paths resolve
-                consistently. ``default`` selects the root profile; empty /
-                None preserves the scheduler's existing behaviour.
         no_agent: When True, skip the agent entirely — run ``script`` on schedule
                 and deliver its stdout directly. Empty stdout = silent (no
                 delivery). Requires ``script`` to be set. Ideal for classic
@@ -647,7 +614,6 @@ def create_job(
     normalized_toolsets = [str(t).strip() for t in enabled_toolsets if str(t).strip()] if enabled_toolsets else None
     normalized_toolsets = normalized_toolsets or None
     normalized_workdir = _normalize_workdir(workdir)
-    normalized_profile = _normalize_profile(profile)
     normalized_no_agent = bool(no_agent)
 
     # no_agent jobs are meaningless without a script — the script IS the job.
@@ -702,7 +668,6 @@ def create_job(
         "origin": origin,  # Tracks where job was created for "origin" delivery
         "enabled_toolsets": normalized_toolsets,
         "workdir": normalized_workdir,
-        "profile": normalized_profile,
     }
 
     jobs = load_jobs()
@@ -792,15 +757,6 @@ def update_job(job_id: str, updates: Dict[str, Any]) -> Optional[Dict[str, Any]]
             else:
                 updates["workdir"] = _normalize_workdir(_wd)
 
-        # Validate / normalize profile if present in updates.  Empty string or
-        # None both mean "clear the field" (restore old behaviour).
-        if "profile" in updates:
-            _profile = updates["profile"]
-            if _profile is None or _profile == "" or _profile is False:
-                updates["profile"] = None
-            else:
-                updates["profile"] = _normalize_profile(_profile)
-
         updated = _apply_skill_fields({**job, **updates})
         schedule_changed = "schedule" in updates
 
diff --git a/cron/scheduler.py b/cron/scheduler.py
index b784847dec31..edabf97e84be 100644
--- a/cron/scheduler.py
+++ b/cron/scheduler.py
@@ -19,7 +19,6 @@ import shutil
 import subprocess
 import sys
 import threading
-from contextlib import contextmanager
 
 # fcntl is Unix-only; on Windows use msvcrt for file locking
 try:
@@ -166,7 +165,7 @@ _parallel_pool_max_workers: Optional[int] = None
 _running_job_ids: set = set()
 _running_lock = threading.Lock()
 
-# Sequential (env/context-mutating) cron jobs — workdir/profile jobs that touch
+# Sequential (env-mutating) cron jobs — workdir jobs that touch
 # process-global runtime state — must run one at a time, but must NOT block the
 # ticker thread.  A persistent single-thread executor preserves ordering across
 # ticks while keeping dispatch fire-and-forget, the same as the parallel pool.
@@ -190,10 +189,10 @@ def _get_parallel_pool(max_workers: Optional[int]) -> concurrent.futures.ThreadP
 def _get_sequential_pool() -> concurrent.futures.ThreadPoolExecutor:
     """Return (or create) the persistent single-thread sequential pool.
 
-    A single worker guarantees env/context-mutating jobs never overlap, even
+    A single worker guarantees env-mutating jobs never overlap, even
     across ticks: a job queued by a newer tick waits for the previous tick's
-    sequential jobs to finish rather than corrupting their os.environ /
-    profile state.
+    sequential jobs to finish rather than corrupting their os.environ
+    state.
     """
     global _sequential_pool
     if _sequential_pool is None:
@@ -235,71 +234,6 @@ def _get_lock_paths() -> tuple[Path, Path]:
     return lock_dir, lock_dir / ".tick.lock"
 
 
-@contextmanager
-def _job_profile_context(job_id: str, profile: Optional[str]):
-    """Temporarily run a job under a specific Hermes profile.
-
-    Cron jobs are stored and scheduled by the profile running the scheduler, but
-    an individual job can opt into a different runtime profile. While active,
-    the scheduler's test/override hook and a context-local Hermes home override
-    both point at the resolved profile directory so _get_hermes_home(),
-    .env/config loading, script resolution, AIAgent construction, and downstream
-    get_hermes_home() callers agree on the same home.
-
-    Some existing provider/config paths still load profile .env values through
-    os.environ, so profile jobs also snapshot and restore the process
-    environment on exit. tick() runs profile jobs sequentially to keep that
-    temporary mutation isolated from other scheduled jobs.
-    """
-    raw_profile = str(profile or "").strip()
-    if not raw_profile:
-        yield None
-        return
-
-    global _hermes_home
-    prior_override = _hermes_home
-    env_snapshot = os.environ.copy()
-
-    from hermes_cli.profiles import normalize_profile_name, resolve_profile_env
-    from hermes_constants import reset_hermes_home_override, set_hermes_home_override
-
-    normalized_profile = normalize_profile_name(raw_profile)
-    try:
-        profile_home = Path(resolve_profile_env(normalized_profile)).resolve()
-    except (FileNotFoundError, ValueError) as exc:
-        logger.warning(
-            "Job '%s': configured profile %r no longer valid (%s) — "
-            "falling back to scheduler default",
-            job_id, raw_profile, exc,
-        )
-        yield None
-        return
-
-    override_token = None
-    try:
-        override_token = set_hermes_home_override(profile_home)
-        _hermes_home = profile_home
-        logger.info(
-            "Job '%s': using Hermes profile '%s' (%s)",
-            job_id,
-            normalized_profile,
-            profile_home,
-        )
-        yield normalized_profile
-    finally:
-        _hermes_home = prior_override
-        if override_token is not None:
-            reset_hermes_home_override(override_token)
-        # Delta-based restore: remove added keys, restore changed keys.
-        # Avoids a brief window where other threads see an empty env.
-        added = set(os.environ.keys()) - set(env_snapshot.keys())
-        for k in added:
-            os.environ.pop(k, None)
-        for k, v in env_snapshot.items():
-            if os.environ.get(k) != v:
-                os.environ[k] = v
-
-
 def _resolve_origin(job: dict) -> Optional[dict]:
     """Extract origin info from a job, preserving any extra routing metadata.
 
@@ -1032,17 +966,6 @@ def _run_job_script(script_path: str) -> tuple[bool, str]:
     else:
         argv = [sys.executable, str(path)]
 
-    run_env = os.environ.copy()
-    run_env["HERMES_HOME"] = str(_get_hermes_home())
-    try:
-        from hermes_constants import get_subprocess_home
-
-        profile_home = get_subprocess_home()
-        if profile_home:
-            run_env["HOME"] = profile_home
-    except Exception:
-        pass
-
     try:
         popen_kwargs = {"creationflags": windows_hide_flags()} if sys.platform == "win32" else {}
         result = subprocess.run(
@@ -1051,7 +974,6 @@ def _run_job_script(script_path: str) -> tuple[bool, str]:
             text=True,
             timeout=script_timeout,
             cwd=str(path.parent),
-            env=run_env,
             **popen_kwargs,
         )
         stdout = (result.stdout or "").strip()
@@ -1381,13 +1303,6 @@ def _scan_assembled_cron_prompt(
 
 
 def run_job(job: dict) -> tuple[bool, str, str, Optional[str]]:
-    """Execute a single cron job, applying any per-job profile override."""
-    job_id = job["id"]
-    with _job_profile_context(job_id, job.get("profile")):
-        return _run_job_impl(job)
-
-
-def _run_job_impl(job: dict) -> tuple[bool, str, str, Optional[str]]:
     """
     Execute a single cron job.
     
@@ -1624,9 +1539,8 @@ def _run_job_impl(job: dict) -> tuple[bool, str, str, Optional[str]]:
     #     .cursorrules from the job's project dir, AND
     #   - the terminal, file, and code-exec tools run commands from there.
     #
-    # tick() serializes jobs that mutate process-global runtime state (workdir
-    # and/or profile jobs) outside the parallel pool, so mutating
-    # os.environ["TERMINAL_CWD"] here is safe for those jobs. For workdir-less
+    # tick() serializes workdir-jobs outside the parallel pool, so mutating
+    # os.environ["TERMINAL_CWD"] here is safe for those jobs.  For workdir-less
     # jobs we leave TERMINAL_CWD untouched — preserves the original behaviour
     # (skip_context_files=True, tools use whatever cwd the scheduler has).
     _job_workdir = (job.get("workdir") or "").strip() or None
@@ -2173,21 +2087,12 @@ def tick(verbose: bool = True, adapters=None, loop=None, sync: bool = True) -> i
                 mark_job_run(job["id"], False, str(e))
                 return False
 
-        # Partition due jobs: jobs with a per-job workdir and/or profile touch
-        # process-global runtime state inside run_job. Workdir jobs temporarily
-        # set os.environ["TERMINAL_CWD"]; profile jobs use a context-local
-        # Hermes home override, scheduler _hermes_home hook, and temporary
-        # profile .env load into os.environ with snapshot/restore. They MUST run
-        # sequentially to avoid corrupting each other. Jobs without either field
-        # stay parallel-safe.
-        sequential_jobs = [
-            j for j in due_jobs
-            if (j.get("workdir") or "").strip() or (j.get("profile") or "").strip()
-        ]
-        parallel_jobs = [
-            j for j in due_jobs
-            if not ((j.get("workdir") or "").strip() or (j.get("profile") or "").strip())
-        ]
+        # Partition due jobs: those with a per-job workdir mutate
+        # os.environ["TERMINAL_CWD"] inside run_job, which is process-global —
+        # so they MUST run sequentially to avoid corrupting each other.  Jobs
+        # without a workdir leave env untouched and stay parallel-safe.
+        sequential_jobs = [j for j in due_jobs if (j.get("workdir") or "").strip()]
+        parallel_jobs = [j for j in due_jobs if not (j.get("workdir") or "").strip()]
 
         _results: list = []
         _all_futures: list = []
@@ -2216,9 +2121,9 @@ def tick(verbose: bool = True, adapters=None, loop=None, sync: bool = True) -> i
 
             return pool.submit(_run_and_release)
 
-        # Sequential pass for env/context-mutating (workdir/profile) jobs.
+        # Sequential pass for env-mutating (workdir) jobs.
         # Queued to a persistent single-thread pool so they run one at a time
-        # WITHOUT blocking the ticker thread — a long workdir/profile job no
+        # WITHOUT blocking the ticker thread — a long workdir job no
         # longer starves the rest of the schedule (same fix as the parallel
         # pass, just serialized).  The in-flight guard prevents a still-running
         # job from being re-queued on the next tick.
diff --git a/hermes_cli/cron.py b/hermes_cli/cron.py
index 683fc73fb73d..717c1e97658d 100644
--- a/hermes_cli/cron.py
+++ b/hermes_cli/cron.py
@@ -120,9 +120,6 @@ def cron_list(show_all: bool = False):
         workdir = job.get("workdir")
         if workdir:
             print(f"    Workdir:   {workdir}")
-        profile = job.get("profile")
-        if profile:
-            print(f"    Profile:   {profile}")
 
         # Execution history
         last_status = job.get("last_status")
@@ -221,7 +218,6 @@ def cron_create(args):
         skills=_normalize_skills(getattr(args, "skill", None), getattr(args, "skills", None)),
         script=getattr(args, "script", None),
         workdir=getattr(args, "workdir", None),
-        profile=getattr(args, "profile", None),
         no_agent=getattr(args, "no_agent", False) or None,
     )
     if not result.get("success"):
@@ -239,8 +235,6 @@ def cron_create(args):
         print("  Mode: no-agent (script stdout delivered directly)")
     if job_data.get("workdir"):
         print(f"  Workdir: {job_data['workdir']}")
-    if job_data.get("profile"):
-        print(f"  Profile: {job_data['profile']}")
     print(f"  Next run: {result['next_run_at']}")
     return 0
 
@@ -286,7 +280,6 @@ def cron_edit(args):
         skills=final_skills,
         script=getattr(args, "script", None),
         workdir=getattr(args, "workdir", None),
-        profile=getattr(args, "profile", None),
         no_agent=getattr(args, "no_agent", None),
     )
     if not result.get("success"):
@@ -307,8 +300,6 @@ def cron_edit(args):
         print("  Mode: no-agent (script stdout delivered directly)")
     if updated.get("workdir"):
         print(f"  Workdir: {updated['workdir']}")
-    if updated.get("profile"):
-        print(f"  Profile: {updated['profile']}")
     return 0
 
 
diff --git a/hermes_cli/subcommands/cron.py b/hermes_cli/subcommands/cron.py
index 33dd10158f3b..c50b3401462b 100644
--- a/hermes_cli/subcommands/cron.py
+++ b/hermes_cli/subcommands/cron.py
@@ -70,10 +70,6 @@ def build_cron_parser(subparsers, *, cmd_cron: Callable) -> None:
         "--workdir",
         help="Absolute path for the job to run from. Injects AGENTS.md / CLAUDE.md / .cursorrules from that directory and uses it as the cwd for terminal/file/code_exec tools. Omit to preserve old behaviour (no project context files).",
     )
-    cron_create.add_argument(
-        "--profile",
-        help="Hermes profile name to run the job under. Use 'default' for the root profile. Named profiles must already exist. Omit to preserve the scheduler's existing profile.",
-    )
 
     # cron edit
     cron_edit = cron_subparsers.add_parser(
@@ -138,10 +134,6 @@ def build_cron_parser(subparsers, *, cmd_cron: Callable) -> None:
         "--workdir",
         help="Absolute path for the job to run from (injects AGENTS.md etc. and sets terminal cwd). Pass empty string to clear.",
     )
-    cron_edit.add_argument(
-        "--profile",
-        help="Hermes profile name to run the job under. Use 'default' for the root profile. Pass empty string to clear.",
-    )
 
     # lifecycle actions
     cron_pause = cron_subparsers.add_parser("pause", help="Pause a scheduled job")
diff --git a/tests/cron/test_cron_profile.py b/tests/cron/test_cron_profile.py
deleted file mode 100644
index 677082e2410a..000000000000
--- a/tests/cron/test_cron_profile.py
+++ /dev/null
@@ -1,449 +0,0 @@
-"""Tests for per-job profile support in cron jobs.
-
-Covers data-layer validation/storage, cronjob tool plumbing, scheduler runtime
-HERMES_HOME scoping, and tick() serialization for profile jobs.
-"""
-
-from __future__ import annotations
-
-import json
-import os
-
-import pytest
-
-
-@pytest.fixture()
-def isolated_cron_profile_home(tmp_path, monkeypatch):
-    """Create an isolated Hermes root with a named profile and temp cron store."""
-    root = tmp_path / "hermes-root"
-    profile_home = root / "profiles" / "support"
-    profile_home.mkdir(parents=True)
-    (root / "cron").mkdir(parents=True)
-
-    monkeypatch.setenv("HERMES_HOME", str(root))
-    monkeypatch.setattr("cron.jobs.CRON_DIR", root / "cron")
-    monkeypatch.setattr("cron.jobs.JOBS_FILE", root / "cron" / "jobs.json")
-    monkeypatch.setattr("cron.jobs.OUTPUT_DIR", root / "cron" / "output")
-
-    return root, profile_home
-
-
-class TestNormalizeProfile:
-    def test_none_and_empty_return_none(self, isolated_cron_profile_home):
-        from cron.jobs import _normalize_profile
-
-        assert _normalize_profile(None) is None
-        assert _normalize_profile("") is None
-        assert _normalize_profile("   ") is None
-
-    def test_default_profile_is_valid_and_normalized(self, isolated_cron_profile_home):
-        from cron.jobs import _normalize_profile
-
-        assert _normalize_profile("Default") == "default"
-
-    def test_named_profile_must_exist_and_is_normalized(self, isolated_cron_profile_home):
-        from cron.jobs import _normalize_profile
-
-        assert _normalize_profile("Support") == "support"
-
-    def test_invalid_profile_name_is_rejected(self, isolated_cron_profile_home):
-        from cron.jobs import _normalize_profile
-
-        with pytest.raises(ValueError):
-            _normalize_profile("invalid!")
-
-    def test_missing_named_profile_is_rejected(self, isolated_cron_profile_home):
-        from cron.jobs import _normalize_profile
-
-        with pytest.raises(FileNotFoundError):
-            _normalize_profile("missing")
-
-
-class TestCreateAndUpdateJobProfile:
-    def test_create_stores_profile_id(self, isolated_cron_profile_home):
-        from cron.jobs import create_job, get_job
-
-        job = create_job(prompt="hello", schedule="every 1h", profile="Support")
-        stored = get_job(job["id"])
-
-        assert stored is not None
-        assert stored["profile"] == "support"
-
-    def test_create_without_profile_preserves_old_behaviour(self, isolated_cron_profile_home):
-        from cron.jobs import create_job, get_job
-
-        job = create_job(prompt="hello", schedule="every 1h")
-        stored = get_job(job["id"])
-
-        assert stored is not None
-        assert stored.get("profile") is None
-
-    def test_create_accepts_explicit_default(self, isolated_cron_profile_home):
-        from cron.jobs import create_job, get_job
-
-        job = create_job(prompt="hello", schedule="every 1h", profile="default")
-        stored = get_job(job["id"])
-
-        assert stored is not None
-        assert stored["profile"] == "default"
-
-    def test_update_sets_and_clears_profile(self, isolated_cron_profile_home):
-        from cron.jobs import create_job, get_job, update_job
-
-        job = create_job(prompt="x", schedule="every 1h")
-        update_job(job["id"], {"profile": "Support"})
-        stored = get_job(job["id"])
-        assert stored is not None
-        assert stored["profile"] == "support"
-
-        update_job(job["id"], {"profile": ""})
-        stored = get_job(job["id"])
-        assert stored is not None
-        assert stored["profile"] is None
-
-    def test_update_rejects_missing_profile(self, isolated_cron_profile_home):
-        from cron.jobs import create_job, update_job
-
-        job = create_job(prompt="x", schedule="every 1h")
-        with pytest.raises(FileNotFoundError):
-            update_job(job["id"], {"profile": "missing"})
-
-
-class TestCronjobToolProfile:
-    def test_create_and_list_with_profile(self, isolated_cron_profile_home):
-        from tools.cronjob_tools import cronjob
-
-        created = json.loads(
-            cronjob(
-                action="create",
-                prompt="hi",
-                schedule="every 1h",
-                profile="Support",
-            )
-        )
-        assert created["success"] is True
-        assert created["job"]["profile"] == "support"
-
-        listing = json.loads(cronjob(action="list"))
-        assert listing["jobs"][0]["profile"] == "support"
-
-    def test_update_clears_profile_with_empty_string(self, isolated_cron_profile_home):
-        from tools.cronjob_tools import cronjob
-
-        created = json.loads(
-            cronjob(
-                action="create",
-                prompt="hi",
-                schedule="every 1h",
-                profile="Support",
-            )
-        )
-        updated = json.loads(
-            cronjob(action="update", job_id=created["job_id"], profile="")
-        )
-
-        assert updated["success"] is True
-        assert "profile" not in updated["job"]
-
-    def test_schema_advertises_profile(self):
-        from tools.cronjob_tools import CRONJOB_SCHEMA
-
-        assert "profile" in CRONJOB_SCHEMA["parameters"]["properties"]
-        desc = CRONJOB_SCHEMA["parameters"]["properties"]["profile"]["description"]
-        desc_lower = desc.lower()
-        assert "hermes profile" in desc_lower
-        assert "context-local" in desc_lower
-        assert "subprocess" in desc_lower
-        assert "temporarily sets hermes_home" not in desc_lower
-
-
-class TestRunJobProfileContext:
-    @staticmethod
-    def _install_agent_stubs(monkeypatch, observed: dict):
-        import sys
-        import cron.scheduler as sched
-
-        class FakeAgent:
-            def __init__(self, **kwargs):
-                from hermes_constants import get_hermes_home
-
-                observed["env_home_during_init"] = os.environ.get("HERMES_HOME")
-                observed["profile_env_only_during_init"] = os.environ.get(
-                    "HERMES_PROFILE_TEST_ONLY"
-                )
-                observed["profile_env_shared_during_init"] = os.environ.get(
-                    "HERMES_PROFILE_TEST_SHARED"
-                )
-                observed["hermes_home_during_init"] = str(get_hermes_home())
-                observed["scheduler_home_during_init"] = str(sched._get_hermes_home())
-                observed["skip_context_files"] = kwargs.get("skip_context_files")
-
-            def run_conversation(self, *_a, **_kw):
-                from hermes_constants import get_hermes_home
-
-                observed["env_home_during_run"] = os.environ.get("HERMES_HOME")
-                observed["profile_env_only_during_run"] = os.environ.get(
-                    "HERMES_PROFILE_TEST_ONLY"
-                )
-                observed["profile_env_shared_during_run"] = os.environ.get(
-                    "HERMES_PROFILE_TEST_SHARED"
-                )
-                observed["hermes_home_during_run"] = str(get_hermes_home())
-                observed["scheduler_home_during_run"] = str(sched._get_hermes_home())
-                return {"final_response": "done", "messages": []}
-
-            def get_activity_summary(self):
-                return {"seconds_since_activity": 0.0}
-
-            def close(self):
-                observed["closed"] = True
-
-        fake_mod = type(sys)("run_agent")
-        fake_mod.AIAgent = FakeAgent
-        monkeypatch.setitem(sys.modules, "run_agent", fake_mod)
-
-        from hermes_cli import runtime_provider as runtime_provider
-
-        monkeypatch.setattr(
-            runtime_provider,
-            "resolve_runtime_provider",
-            lambda **_kw: {
-                "provider": "test",
-                "api_key": "test-key",
-                "base_url": "http://test.local",
-                "api_mode": "chat_completions",
-            },
-        )
-
-        monkeypatch.setattr(sched, "_build_job_prompt", lambda job, prerun_script=None: "hi")
-        monkeypatch.setattr(sched, "_resolve_origin", lambda job: None)
-        monkeypatch.setattr(sched, "_resolve_delivery_target", lambda job: None)
-        monkeypatch.setattr(sched, "_resolve_cron_enabled_toolsets", lambda job, cfg: None)
-        monkeypatch.setattr(sched, "_hermes_home", None)
-        monkeypatch.setenv("HERMES_CRON_TIMEOUT", "0")
-
-        import dotenv
-
-        def fake_load_dotenv(path, *_a, **_kw):
-            observed.setdefault("dotenv_paths", []).append(str(path))
-            return True
-
-        monkeypatch.setattr(dotenv, "load_dotenv", fake_load_dotenv)
-
-    def test_run_job_sets_and_restores_profile_home(
-        self, isolated_cron_profile_home, monkeypatch
-    ):
-        import cron.scheduler as sched
-
-        root, profile_home = isolated_cron_profile_home
-        observed: dict = {}
-        self._install_agent_stubs(monkeypatch, observed)
-
-        job = {
-            "id": "abc",
-            "name": "profile-job",
-            "profile": "support",
-            "schedule_display": "manual",
-        }
-
-        success, _output, response, error = sched.run_job(job)
-
-        assert success is True, f"run_job failed: error={error!r} response={response!r}"
-        assert observed["dotenv_paths"] == [str(profile_home / ".env")]
-        assert observed["env_home_during_init"] == str(root)
-        assert observed["env_home_during_run"] == str(root)
-        assert observed["hermes_home_during_init"] == str(profile_home.resolve())
-        assert observed["hermes_home_during_run"] == str(profile_home.resolve())
-        assert observed["scheduler_home_during_init"] == str(profile_home.resolve())
-        assert observed["scheduler_home_during_run"] == str(profile_home.resolve())
-        assert observed["skip_context_files"] is True
-        assert os.environ["HERMES_HOME"] == str(root)
-        assert sched._get_hermes_home() == root
-
-    def test_profile_dotenv_environment_is_restored(
-        self, isolated_cron_profile_home, monkeypatch
-    ):
-        import dotenv
-        import cron.scheduler as sched
-
-        root, profile_home = isolated_cron_profile_home
-        observed: dict = {}
-        self._install_agent_stubs(monkeypatch, observed)
-        monkeypatch.setenv("HERMES_PROFILE_TEST_SHARED", "outer")
-        monkeypatch.delenv("HERMES_PROFILE_TEST_ONLY", raising=False)
-
-        def fake_load_dotenv(path, *_a, **_kw):
-            observed.setdefault("dotenv_paths", []).append(str(path))
-            os.environ["HERMES_PROFILE_TEST_SHARED"] = "profile-value"
-            os.environ["HERMES_PROFILE_TEST_ONLY"] = "profile-only"
-            os.environ["HERMES_CRON_TIMEOUT"] = "123"
-            return True
-
-        monkeypatch.setattr(dotenv, "load_dotenv", fake_load_dotenv)
-
-        job = {
-            "id": "env-profile",
-            "name": "profile-env-job",
-            "profile": "support",
-            "schedule_display": "manual",
-        }
-
-        success, _output, _response, error = sched.run_job(job)
-
-        assert success is True, error
-        assert observed["dotenv_paths"] == [str(profile_home / ".env")]
-        assert observed["profile_env_only_during_init"] == "profile-only"
-        assert observed["profile_env_shared_during_init"] == "profile-value"
-        assert observed["profile_env_only_during_run"] == "profile-only"
-        assert observed["profile_env_shared_during_run"] == "profile-value"
-        assert os.environ["HERMES_PROFILE_TEST_SHARED"] == "outer"
-        assert "HERMES_PROFILE_TEST_ONLY" not in os.environ
-        assert os.environ["HERMES_CRON_TIMEOUT"] == "0"
-        assert os.environ["HERMES_HOME"] == str(root)
-        assert sched._get_hermes_home() == root
-
-    def test_no_agent_profile_uses_profile_scripts_dir_and_restores_env(
-        self, isolated_cron_profile_home, monkeypatch
-    ):
-        import cron.scheduler as sched
-
-        root, profile_home = isolated_cron_profile_home
-        scripts_dir = profile_home / "scripts"
-        scripts_dir.mkdir(parents=True)
-        (scripts_dir / "print_home.py").write_text(
-            "import os\nprint(os.environ.get('HERMES_HOME', ''))\n",
-            encoding="utf-8",
-        )
-        monkeypatch.setattr(sched, "_hermes_home", None)
-
-        job = {
-            "id": "script1",
-            "name": "profile-script",
-            "profile": "support",
-            "script": "print_home.py",
-            "no_agent": True,
-        }
-
-        success, _doc, response, error = sched.run_job(job)
-
-        assert success is True, error
-        assert response.strip() == str(profile_home.resolve())
-        assert os.environ["HERMES_HOME"] == str(root)
-        assert sched._get_hermes_home() == root
-
-    def test_run_job_without_profile_leaves_hermes_home_untouched(
-        self, isolated_cron_profile_home, monkeypatch
-    ):
-        import cron.scheduler as sched
-
-        root, _profile_home = isolated_cron_profile_home
-        observed: dict = {}
-        self._install_agent_stubs(monkeypatch, observed)
-
-        job = {
-            "id": "noprof",
-            "name": "no-profile-job",
-            "profile": None,
-            "schedule_display": "manual",
-        }
-
-        success, *_ = sched.run_job(job)
-
-        assert success is True
-        assert observed["hermes_home_during_init"] == str(root)
-        assert os.environ["HERMES_HOME"] == str(root)
-
-    def test_run_job_falls_back_on_missing_runtime_profile(
-        self, isolated_cron_profile_home, monkeypatch
-    ):
-        import cron.scheduler as sched
-
-        root, _profile_home = isolated_cron_profile_home
-        observed: dict = {}
-        self._install_agent_stubs(monkeypatch, observed)
-
-        job = {
-            "id": "missing-profile",
-            "name": "missing-profile-job",
-            "profile": "missing",
-            "schedule_display": "manual",
-        }
-
-        # Should succeed with fallback, not raise
-        success, _output, response, error = sched.run_job(job)
-
-        assert success is True, f"run_job should fallback, not fail: error={error!r}"
-        # Verify it used the default home, not the missing profile
-        assert observed["hermes_home_during_init"] == str(root)
-        assert os.environ["HERMES_HOME"] == str(root)
-
-
-class TestTickProfilePartition:
-    def test_profile_and_workdir_combined(self, isolated_cron_profile_home, monkeypatch):
-        """Both profile and workdir set — verify both are applied and restored."""
-        import cron.scheduler as sched
-
-        root, profile_home = isolated_cron_profile_home
-        observed: dict = {}
-        TestRunJobProfileContext._install_agent_stubs(monkeypatch, observed)
-        fake_workdir = str(root / "myproject")
-        (root / "myproject").mkdir()
-
-        job = {
-            "id": "combo",
-            "name": "combo-job",
-            "profile": "support",
-            "workdir": fake_workdir,
-            "schedule_display": "manual",
-        }
-
-        success, _output, _response, error = sched.run_job(job)
-
-        assert success is True, error
-        assert observed["hermes_home_during_init"] == str(profile_home.resolve())
-        assert os.environ.get("TERMINAL_CWD", "") != fake_workdir, \
-            "TERMINAL_CWD should be restored after job"
-        assert os.environ["HERMES_HOME"] == str(root)
-        assert sched._get_hermes_home() == root
-
-    def test_profile_jobs_run_sequentially(self, isolated_cron_profile_home, monkeypatch):
-        import threading
-        import cron.scheduler as sched
-
-        # Two profile jobs (both sequential) + one parallel job.
-        profile_a = {"id": "a", "name": "A", "profile": "default"}
-        profile_b = {"id": "b", "name": "B", "profile": "default"}
-        parallel_job = {"id": "c", "name": "C", "profile": None}
-
-        monkeypatch.setattr(sched, "get_due_jobs", lambda: [profile_a, profile_b, parallel_job])
-        monkeypatch.setattr(sched, "advance_next_run", lambda *_a, **_kw: None)
-
-        calls: list[tuple[str, str]] = []
-        order_lock = threading.Lock()
-
-        def fake_run_job(job):
-            with order_lock:
-                calls.append((job["id"], threading.current_thread().name))
-            return True, "output", "response", None
-
-        monkeypatch.setattr(sched, "run_job", fake_run_job)
-        monkeypatch.setattr(sched, "save_job_output", lambda _jid, _o: None)
-        monkeypatch.setattr(sched, "mark_job_run", lambda *_a, **_kw: None)
-        monkeypatch.setattr(sched, "_deliver_result", lambda *_a, **_kw: None)
-
-        n = sched.tick(verbose=False)
-
-        assert n == 3
-        ids = [job_id for job_id, _thread_name in calls]
-        # Sequential profile jobs preserve submission order relative to each
-        # other (single-thread pool).
-        assert ids.index("a") < ids.index("b")
-        # Sequential (profile) jobs run on the persistent single-thread
-        # cron-seq pool — NOT the main thread — so a long profile job never
-        # blocks the ticker.  Parallel jobs run on the cron-parallel pool.
-        for jid in ("a", "b"):
-            seq_thread = next(t for job_id, t in calls if job_id == jid)
-            assert seq_thread != threading.current_thread().name
-            assert seq_thread.startswith("cron-seq"), seq_thread
-        par_thread = next(t for job_id, t in calls if job_id == "c")
-        assert par_thread.startswith("cron-parallel"), par_thread
diff --git a/tests/cron/test_parallel_pool.py b/tests/cron/test_parallel_pool.py
index 146853c4a00e..01e65adc4fbc 100644
--- a/tests/cron/test_parallel_pool.py
+++ b/tests/cron/test_parallel_pool.py
@@ -172,10 +172,10 @@ class TestSyncMode:
 
 
 class TestSequentialPool:
-    """Sequential (workdir/profile) jobs use the persistent cron-seq pool.
+    """Sequential (workdir) jobs use the persistent cron-seq pool.
 
-    Verifies the follow-up fix: env/context-mutating jobs no longer run inline
-    in the ticker thread, so a long workdir/profile job can't starve the
+    Verifies the follow-up fix: env-mutating jobs no longer run inline
+    in the ticker thread, so a long workdir job can't starve the
     schedule the same way the parallel path used to.
     """
 
diff --git a/tests/cron/test_scheduler.py b/tests/cron/test_scheduler.py
index 8056d3c49e27..df66467959ec 100644
--- a/tests/cron/test_scheduler.py
+++ b/tests/cron/test_scheduler.py
@@ -1487,7 +1487,7 @@ class TestRunJobConfigLogging:
         }
 
         # Mock heavy post-yaml work so the test only exercises the warning
-        # path. Without these mocks, _run_job_impl continues into provider
+        # path. Without these mocks, run_job continues into provider
         # resolution and MCP discovery, both of which can spawn subprocesses
         # / hit the network and have caused this test to time out on CI
         # (>30s wall clock) under load. See PR #33661 follow-up.
diff --git a/tests/hermes_cli/test_cron.py b/tests/hermes_cli/test_cron.py
index aa4f6b116f14..442433f768f4 100644
--- a/tests/hermes_cli/test_cron.py
+++ b/tests/hermes_cli/test_cron.py
@@ -55,7 +55,6 @@ class TestCronCommandLifecycle:
                 repeat=None,
                 skill=None,
                 skills=["maps", "blogwatcher"],
-                profile="default",
                 clear_skills=False,
             )
         )
@@ -64,7 +63,6 @@ class TestCronCommandLifecycle:
         assert updated["name"] == "Edited Job"
         assert updated["prompt"] == "Revised prompt"
         assert updated["schedule_display"] == "every 120m"
-        assert updated["profile"] == "default"
 
         cron_command(
             Namespace(
@@ -77,14 +75,12 @@ class TestCronCommandLifecycle:
                 repeat=None,
                 skill=None,
                 skills=None,
-                profile="",
                 clear_skills=True,
             )
         )
         cleared = get_job(job["id"])
         assert cleared["skills"] == []
         assert cleared["skill"] is None
-        assert cleared["profile"] is None
 
         out = capsys.readouterr().out
         assert "Updated job" in out
@@ -100,7 +96,6 @@ class TestCronCommandLifecycle:
                 repeat=None,
                 skill=None,
                 skills=["blogwatcher", "maps"],
-                profile="default",
             )
         )
         out = capsys.readouterr().out
@@ -110,7 +105,6 @@ class TestCronCommandLifecycle:
         assert len(jobs) == 1
         assert jobs[0]["skills"] == ["blogwatcher", "maps"]
         assert jobs[0]["name"] == "Skill combo"
-        assert jobs[0]["profile"] == "default"
 
     def test_list_does_not_crash_when_repeat_is_null(self, tmp_cron_dir, capsys):
         """A one-shot job can be persisted with ``"repeat": null``. `cron
diff --git a/tools/cronjob_tools.py b/tools/cronjob_tools.py
index 2ec497607150..7ec31b806c46 100644
--- a/tools/cronjob_tools.py
+++ b/tools/cronjob_tools.py
@@ -459,8 +459,6 @@ def _format_job(job: Dict[str, Any]) -> Dict[str, Any]:
         result["enabled_toolsets"] = job["enabled_toolsets"]
     if job.get("workdir"):
         result["workdir"] = job["workdir"]
-    if job.get("profile"):
-        result["profile"] = job["profile"]
     return result
 
 
@@ -483,7 +481,6 @@ def cronjob(
     context_from: Optional[Union[str, List[str]]] = None,
     enabled_toolsets: Optional[List[str]] = None,
     workdir: Optional[str] = None,
-    profile: Optional[str] = None,
     no_agent: Optional[bool] = None,
     task_id: str = None,
 ) -> str:
@@ -550,7 +547,6 @@ def cronjob(
                 context_from=context_from,
                 enabled_toolsets=enabled_toolsets or None,
                 workdir=_normalize_optional_job_value(workdir),
-                profile=_normalize_optional_job_value(profile),
                 no_agent=_no_agent,
             )
             return json.dumps(
@@ -685,10 +681,6 @@ def cronjob(
                 # Empty string clears the field (restores old behaviour);
                 # otherwise pass raw — update_job() validates / normalizes.
                 updates["workdir"] = _normalize_optional_job_value(workdir) or None
-            if profile is not None:
-                # Empty string clears the field (restores old behaviour);
-                # otherwise pass raw — update_job() validates / normalizes.
-                updates["profile"] = _normalize_optional_job_value(profile) or None
             if no_agent is not None:
                 # Toggling no_agent on/off at update time. If flipping to True,
                 # we need a script to already exist on the job (or be part of
@@ -842,10 +834,6 @@ Important safety rule: cron-run sessions should not recursively schedule more cr
                 "type": "string",
                 "description": "Optional absolute path to run the job from. When set, AGENTS.md / CLAUDE.md / .cursorrules from that directory are injected into the system prompt, and the terminal/file/code_exec tools use it as their working directory — useful for running a job inside a specific project repo. Must be an absolute path that exists. When unset (default), preserves the original behaviour: no project context files, tools use the scheduler's cwd. On update, pass an empty string to clear. Jobs with workdir run sequentially (not parallel) to keep per-job directories isolated."
             },
-            "profile": {
-                "type": "string",
-                "description": "Optional Hermes profile name to run the job under. When set, the scheduler resolves that profile, applies a context-local Hermes home override, loads that profile's config/.env for the run, and bridges HERMES_HOME into subprocesses. Any temporary process-environment changes from profile .env loading are restored after the job exits. Use 'default' for the root Hermes profile. Named profiles must already exist. When unset (default), preserves the scheduler's existing profile. On update, pass an empty string to clear. Jobs with profile run sequentially (not parallel) to keep profile-scoped runtime state isolated."
-            },
         },
         "required": ["action"]
     }
@@ -900,7 +888,6 @@ registry.register(
         context_from=args.get("context_from"),
         enabled_toolsets=args.get("enabled_toolsets"),
         workdir=args.get("workdir"),
-        profile=args.get("profile"),
         no_agent=args.get("no_agent"),
         task_id=kw.get("task_id"),
     ))(),
diff --git a/website/docs/user-guide/features/cron.md b/website/docs/user-guide/features/cron.md
index cbefde68a9e4..cc398580a9cb 100644
--- a/website/docs/user-guide/features/cron.md
+++ b/website/docs/user-guide/features/cron.md
@@ -125,35 +125,6 @@ When `workdir` is set:
 Jobs with a `workdir` run sequentially on the scheduler tick, not in the parallel pool. This is deliberate: the cron worker applies the job workdir through process-global terminal state, so two workdir jobs running at the same time would corrupt each other's cwd. Workdir-less jobs still run in parallel as before.
 :::
 
-## Running cron jobs in a specific profile
-
-By default a cron job inherits whichever Hermes profile owned the gateway / CLI that created it. Pass `--profile <name>` (CLI) or `profile=` (cronjob tool) to re-target the job at a different profile — the scheduler resolves that profile's `HERMES_HOME`, temporarily switches into it for the duration of the run, loads its `.env` + `config.yaml`, and executes the job there:
-
-```bash
-# Pin a job to the `night-ops` profile regardless of where it was scheduled
-hermes cron create "every 1d at 03:00" \
-  "Tail the security log and flag anomalies" \
-  --profile night-ops
-```
-
-```python
-# From a chat, via the cronjob tool
-cronjob(
-    action="create",
-    schedule="every 1d at 03:00",
-    prompt="Tail the security log and flag anomalies",
-    profile="night-ops",
-)
-```
-
-Use `--profile default` to explicitly pin to the root Hermes profile. The named profile must already exist; the scheduler refuses to create profiles on the fly. To clear a profile pin during `cron edit`, pass an empty string (`--profile ""` or `profile=""`) — the job reverts to running in whatever profile the scheduler itself is in.
-
-If the pinned profile is later deleted, the scheduler logs a warning and falls back to running the job in its current profile rather than crashing — so a stale `profile` reference never wedges a job.
-
-:::note Serialization
-Jobs with a `profile` set also run sequentially, for the same reason as `workdir`-pinned jobs: switching `HERMES_HOME` is a process-global mutation, so two profile-pinned jobs running in parallel would race each other. Unpinned jobs still run in the normal parallel pool.
-:::
-
 ## Editing jobs
 
 You do not need to delete and recreate jobs just to change them.
@@ -223,7 +194,7 @@ What they do:
 - `resume` — re-enable the job and compute the next future run
 - `run` — trigger the job on the next scheduler tick
 - `remove` — delete it entirely
-- `edit` — modify schedule, prompt, profile, delivery, etc.
+- `edit` — modify schedule, prompt, delivery, etc.
 
 **Name-based lookup.** All four mutating verbs (`pause`, `resume`, `run`, `remove`, `edit`) plus the agent's `cronjob` tool now accept a job **name** (case-insensitive) in place of the hex ID. The agent and CLI both prefer an exact ID match if one exists; ambiguous name matches (multiple jobs sharing the same name) are refused with the full list of candidate IDs so you can pick one explicitly. Names are not unique, so this guard is load-bearing — it prevents silently mutating the wrong job when two share a name.
 

From fdc0d1956636d0c90cb53192f8acebf2e5459ee1 Mon Sep 17 00:00:00 2001
From: Brooklyn Nicholson <brooklyn.bb.nicholson@gmail.com>
Date: Wed, 10 Jun 2026 22:58:50 -0500
Subject: [PATCH 19/28] =?UTF-8?q?fix(desktop):=20make=20draft=20persistenc?=
 =?UTF-8?q?e=20actually=20fire=20=E2=80=94=20new-chat=20sentinel,=20reload?=
 =?UTF-8?q?=20flush,=20session-switch=20clears?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Manual testing of the salvaged draft persistence showed none of it worked
end-to-end. Three distinct bugs, all invisible to the store-level unit
tests:

1. New-chat drafts were never written. The skip-one-persist sentinel was
   reset to null after consuming, but null IS a real scope (the unsaved
   new-session draft) — so in a new chat every persist run matched the
   "consumed" sentinel and bailed. This silently killed the headline
   #38498 fix. Use undefined as the no-skip sentinel, which can never
   collide with a scope.

2. Cmd+R inside the debounce window dropped the trailing text. React does
   not run effect cleanups on a page reload, so the flush-on-unmount
   never fired; with the 400ms debounce that meant type-then-reload lost
   the draft every time. Flush pending writes on pagehide.

3. Session switch/new/resume/branch paths in use-session-actions cleared
   the composer stores synchronously with the session-id updates. React
   batches those, so by the time ChatBar's scope-change cleanup ran to
   stash the departing session's attachments, the store was already
   empty — the stash recorded [] and the chips were lost anyway. The
   composer's per-scope restore now owns composer contents wholesale on
   scope change, so drop the upstream clears (clearComposerDraft only
   touched the vestigial $composerDraft atom nothing reads).

Co-authored-by: mollusk <roger@roger.local>
Co-authored-by: Teknium <127238744+teknium1@users.noreply.github.com>
---
 apps/desktop/src/app/chat/composer/index.tsx  | 31 +++++++++++++------
 .../app/session/hooks/use-session-actions.ts  | 19 +++++-------
 2 files changed, 30 insertions(+), 20 deletions(-)

diff --git a/apps/desktop/src/app/chat/composer/index.tsx b/apps/desktop/src/app/chat/composer/index.tsx
index 169c22236b8a..e55e50192054 100644
--- a/apps/desktop/src/app/chat/composer/index.tsx
+++ b/apps/desktop/src/app/chat/composer/index.tsx
@@ -186,7 +186,11 @@ export function ChatBar({
   const editorRef = useRef<HTMLDivElement | null>(null)
   const draftRef = useRef(draft)
   const previousBusyRef = useRef(busy)
-  const skipNextDraftPersistScopeRef = useRef<string | null>(null)
+  // `undefined` = no skip pending. The sentinel must be distinguishable from a
+  // real scope, and `null` IS a real scope (the unsaved-new-session draft):
+  // resetting to null made every persist run in a new chat match the consumed
+  // sentinel and bail, so new-chat drafts were never written at all.
+  const skipNextDraftPersistScopeRef = useRef<string | null | undefined>(undefined)
   const pendingDraftPersistRef = useRef<{ scope: string | null; value: string } | null>(null)
   const drainingQueueRef = useRef(false)
   const urlInputRef = useRef<HTMLInputElement | null>(null)
@@ -1132,7 +1136,7 @@ export function ChatBar({
 
   useEffect(() => {
     if (skipNextDraftPersistScopeRef.current === draftPersistenceScope) {
-      skipNextDraftPersistScopeRef.current = null
+      skipNextDraftPersistScopeRef.current = undefined
 
       return
     }
@@ -1161,19 +1165,28 @@ export function ChatBar({
     return () => window.clearTimeout(handle)
   }, [draft, draftPersistenceScope, queueEdit, sessionId])
 
-  // Flush any pending debounced draft write when leaving a session scope or
-  // unmounting, so the departing session's latest text is always persisted.
-  useEffect(
-    () => () => {
+  // Flush any pending debounced draft write when leaving a session scope,
+  // unmounting, or the window unloading, so the latest text is always
+  // persisted. The pagehide listener is load-bearing: React does NOT run
+  // effect cleanups on a page reload, so without it a Cmd+R inside the
+  // debounce window silently dropped everything typed in the last 400ms.
+  useEffect(() => {
+    const flushPendingDraftPersist = () => {
       const pending = pendingDraftPersistRef.current
 
       if (pending) {
         pendingDraftPersistRef.current = null
         writePersistedComposerDraft(pending.scope, pending.value)
       }
-    },
-    [draftPersistenceScope]
-  )
+    }
+
+    window.addEventListener('pagehide', flushPendingDraftPersist)
+
+    return () => {
+      window.removeEventListener('pagehide', flushPendingDraftPersist)
+      flushPendingDraftPersist()
+    }
+  }, [draftPersistenceScope])
 
   const beginQueuedEdit = (entry: QueuedPromptEntry) => {
     if (!activeQueueSessionKey || queueEdit) {
diff --git a/apps/desktop/src/app/session/hooks/use-session-actions.ts b/apps/desktop/src/app/session/hooks/use-session-actions.ts
index 51ee90924aec..f049223b1f43 100644
--- a/apps/desktop/src/app/session/hooks/use-session-actions.ts
+++ b/apps/desktop/src/app/session/hooks/use-session-actions.ts
@@ -8,7 +8,6 @@ import { type ChatMessage, chatMessageText, preserveLocalAssistantErrors, toChat
 import { normalizePersonalityValue } from '@/lib/chat-runtime'
 import { embeddedImageUrls, textWithoutEmbeddedImages } from '@/lib/embedded-images'
 import { setSessionYolo } from '@/lib/yolo-session'
-import { clearComposerAttachments, clearComposerDraft } from '@/store/composer'
 import { clearQueuedPrompts } from '@/store/composer-queue'
 import { $pinnedSessionIds } from '@/store/layout'
 import { clearNotifications, notify, notifyError } from '@/store/notifications'
@@ -19,7 +18,6 @@ import {
   $messages,
   $sessions,
   $yoloActive,
-  workspaceCwdForNewSession,
   sessionPinId,
   setActiveSessionId,
   setAwaitingResponse,
@@ -41,7 +39,8 @@ import {
   setSessionStartedAt,
   setSessionsTotal,
   setTurnStartedAt,
-  setYoloActive
+  setYoloActive,
+  workspaceCwdForNewSession
 } from '@/store/session'
 import { reportBackendContract } from '@/store/updates'
 import type { SessionCreateResponse, SessionInfo, SessionResumeResponse, UsageStats } from '@/types/hermes'
@@ -329,8 +328,10 @@ export function useSessionActions({
       setYoloActive(false)
       setCurrentCwd(workspaceCwdForNewSession())
       setCurrentBranch('')
-      clearComposerDraft()
-      clearComposerAttachments()
+      // Composer contents are owned by ChatBar's per-scope draft persistence:
+      // the scope change triggered by the session-id updates above stashes the
+      // departing session's attachments and restores this scope's draft.
+      // Clearing here would wipe the departing stash before it's saved.
       setFreshDraftReady(true)
     },
     [activeSessionIdRef, busyRef, navigate, selectedStoredSessionIdRef]
@@ -352,11 +353,13 @@ export function useSessionActions({
         // Pass the owning profile so a new chat under a non-launch profile (global
         // remote mode) builds its agent + persists against THAT profile's home/db.
         const newChatProfile = $newChatProfile.get()
+
         const created = await requestGateway<SessionCreateResponse>('session.create', {
           cols: 96,
           ...(cwd && { cwd }),
           ...(newChatProfile ? { profile: newChatProfile } : {})
         })
+
         const stored = created.stored_session_id ?? null
 
         if (
@@ -475,8 +478,6 @@ export function useSessionActions({
         setCurrentCwd(cachedState.cwd)
         setCurrentBranch(cachedState.branch)
         setSessionStartedAt(Date.now())
-        clearComposerDraft()
-        clearComposerAttachments()
 
         try {
           const usage = await requestGateway<UsageStats>('session.usage', { session_id: cachedRuntimeId })
@@ -606,8 +607,6 @@ export function useSessionActions({
           }),
           storedSessionId
         )
-        clearComposerDraft()
-        clearComposerAttachments()
       } catch (err) {
         if (!isCurrentResume()) {
           return
@@ -730,8 +729,6 @@ export function useSessionActions({
         selectedStoredSessionIdRef.current = routedSessionId
         navigate(sessionRoute(routedSessionId))
 
-        clearComposerDraft()
-        clearComposerAttachments()
         const runtimeInfo = applyRuntimeInfo(branched.info)
 
         patchSessionWorkspace(routedSessionId, runtimeInfo?.cwd)

From 3e74f75e41ecd5a3b937d692ba7dcffbf77304f6 Mon Sep 17 00:00:00 2001
From: brooklyn! <brooklyn.bb.nicholson@gmail.com>
Date: Wed, 10 Jun 2026 23:06:44 -0500
Subject: [PATCH 20/28] feat(agent): coding-context posture across
 CLI/TUI/desktop/ACP (#43316)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* feat(agent): coding-context posture with per-model edit-format tuning

Hermes detects when it's running in a coding context — an interactive
surface (CLI, TUI, ACP, desktop) sitting in a code workspace (git repo or
recognised project root) — and shifts into a coding posture. Outside that
(chat platforms, non-workspaces) nothing changes.

The posture is modelled as a frozen RuntimeMode selected from a small
ContextProfile registry (coding/general). A profile is data: the toolset to
collapse to, the operating brief to inject, and seams for model routing and
memory. Every domain reads the same resolved object instead of re-probing
git/config on its own:

- System prompt — RuntimeMode.system_blocks(): an operating brief (gather
  context before editing, edit through tools not chat, verify with terminal,
  cap retry loops) plus a live git/workspace snapshot, built once and baked
  into the stable prompt tier so per-conversation caching is preserved.
- Per-model edit-format tuning — the brief nudges each model family toward
  the patch mode it handles best: OpenAI/Codex toward mode='patch' (V4A
  multi-file diffs), Anthropic toward mode='replace' (string replacement).
  The model id rides on RuntimeMode; unknown families keep neutral wording.
- Skill index — non-coding skill categories are pruned from the prompt's
  skill index (discovery-only; skills_list/skill_view still reach the full
  catalog, with a disclosure note).
- Toolset — only under the opt-in 'focus' mode does the posture collapse to
  the coding toolset + enabled MCP servers; the default posture is
  prompt-only and never overrides configured toolsets.

Activation via agent.coding_context: auto (default), focus, on, off.
Subagents inherit the posture for free via toolset inheritance + the shared
prompt builder. Detection is not memoized so a long-lived gateway/TUI
process can't pin a stale posture across working directories.

* feat(agent): cover new-file authoring in the coding edit-format nudge

The per-model edit-format guidance only addressed editing existing code
(patch mode='patch' vs 'replace'), but authoring a brand-new file —
write_file, not patch — is a large fraction of real coding work and the
nudge was silent on it. Surfaced when building a single-file artifact where
the dominant operation was write_file and the steering offered no guidance.

Both family lines now lead with "author new files with write_file; for
edits to existing code prefer ...". Tests assert write_file appears in each
family's brief; unknown families still get neutral wording.

* docs(agent): correct memoization docstring + clarify TUI config-load asymmetry

* feat(agent): sharpen the coding posture — verify-loop facts, wider edit steering, $HOME guard

Tuning pass on the coding posture from dogfooding it as a harness:

- Workspace snapshot now hands the model its verify loop up front:
  detected manifests + package manager (lockfile sniff), the exact
  verify commands (package.json scripts, Makefile targets,
  scripts/run_tests.sh, pytest config), and which context files
  (AGENTS.md / CLAUDE.md / .cursorrules) exist at the root. Marker-only
  (non-git) projects get the snapshot too instead of nothing. The
  "verify before claiming done" brief line was the highest-value piece
  in evals — this turns it from advice into an executable loop instead
  of making the model rediscover the test command every session. Still
  stat-cheap, size-guarded reads, built once at prompt time.

- Edit-format steering covers the families Hermes actually serves:
  Gemini and open-weight coding models (DeepSeek, Qwen, Kimi, GLM,
  Grok, Hermes, Llama, Mistral, Devstral, MiniMax) steer to
  mode='replace' — their RL scaffolds use str_replace-style editors.
  Previously only GPT/Codex and Claude families got steering; the
  models Hermes users disproportionately run all fell to neutral.

- Operating brief gains four behaviors elite harnesses encode: batch
  independent reads/searches in one turn; fix root causes and the bug
  class (sibling call paths), not the reported site; no drive-by
  refactors/renames/reformatting; never read, print, or commit secrets.
  Plus a patch-failure escalation ladder: after the same region fails
  twice, rewrite the enclosing function/file with write_file instead of
  a third patch attempt.

- $HOME dotfiles guard: a git repo rooted exactly at the home directory
  (or a marker sitting in it, e.g. a global ~/AGENTS.md) is user config,
  not a code workspace — without the guard, every session anywhere under
  a dotfiles-managed home silently flipped to the coding posture. Real
  projects under such a home still detect via their own markers/repos;
  'on' mode bypasses the guard.
---
 agent/coding_context.py            | 700 +++++++++++++++++++++++++++++
 agent/prompt_builder.py            |  31 +-
 agent/system_prompt.py             |  32 ++
 cli.py                             |  18 +-
 hermes_cli/config.py               |  13 +
 hermes_cli/tools_config.py         |   4 +
 tests/agent/test_coding_context.py | 405 +++++++++++++++++
 tests/agent/test_prompt_builder.py |  36 ++
 tests/agent/test_system_prompt.py  |  41 ++
 toolsets.py                        |  27 ++
 tui_gateway/server.py              |  16 +
 11 files changed, 1319 insertions(+), 4 deletions(-)
 create mode 100644 agent/coding_context.py
 create mode 100644 tests/agent/test_coding_context.py

diff --git a/agent/coding_context.py b/agent/coding_context.py
new file mode 100644
index 000000000000..f0ed3296a03c
--- /dev/null
+++ b/agent/coding_context.py
@@ -0,0 +1,700 @@
+"""Coding-context awareness — base Hermes, every interactive surface.
+
+When the user runs Hermes inside a code workspace (CLI, TUI, desktop app, or an
+editor over ACP), Hermes shifts into a **coding posture**. This module is the
+single place that decides whether we're in that posture and what it implies,
+so the rest of the codebase never re-derives "are we coding?" on its own.
+
+Architecture — one seam, many consumers
+----------------------------------------
+The posture is modelled as a frozen :class:`RuntimeMode` selected from a small
+:class:`ContextProfile` registry (today: ``coding`` and ``general``). A profile
+is *data* — it declares the toolset to collapse to, the operating brief to
+inject, and hints for other domains (model routing, memory, subagents). Every
+domain reads the same resolved object instead of probing git/config itself:
+
+  * **System prompt** — ``RuntimeMode.system_blocks()`` → the operating brief +
+    a live git/workspace snapshot (``agent/system_prompt.py``).
+  * **Toolset** — ``RuntimeMode.toolset_selection()`` → the ``coding`` toolset
+    plus the user's enabled MCP servers (``cli.py`` / ``tui_gateway``). Only
+    under the opt-in ``focus`` mode: the default posture is prompt-only and
+    never touches the user's configured toolsets (toolsets like messaging /
+    smart-home / music are off-by-default anyway, and someone who explicitly
+    enabled image-gen or Spotify shouldn't lose it for being in a git repo).
+  * **Delegation** — subagents inherit the parent's toolset and run through the
+    same prompt builder, so the coding posture propagates to children for free.
+  * **Model / memory / compression** — declared on the profile
+    (``model_hint``, ``memory_policy``) as the extension seam; consumers read
+    ``mode.profile`` rather than re-deciding.
+
+Cache safety
+------------
+The mode is resolved **once** and is immutable. The workspace snapshot is built
+once at prompt-build time and baked into the *stable* system-prompt tier — never
+re-probed per turn (that would shatter the prompt cache). Branch and dirty state
+drift mid-session, so the brief tells the model to re-check with ``git`` before
+acting on the snapshot. A ``/coding`` flip therefore only takes effect next
+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.
+  * ``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.
+  * ``off`` — disable entirely.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import re
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Optional
+
+logger = logging.getLogger("hermes.coding_context")
+
+CODING_TOOLSET = "coding"
+
+# Surfaces where a coding posture makes sense under ``auto``. Messaging
+# platforms (telegram, discord, slack, …) are intentionally absent — a chat bot
+# in a group is not pair-programming.
+INTERACTIVE_CODING_PLATFORMS = {"cli", "tui", "acp", "desktop", ""}
+
+# Project-root signals that mark a directory as a code workspace even when it
+# isn't (yet) a git repo. Cheap filename checks — no parsing.
+_PROJECT_MARKERS = (
+    "pyproject.toml", "setup.py", "setup.cfg", "requirements.txt",
+    "package.json", "tsconfig.json", "deno.json",
+    "Cargo.toml", "go.mod", "pom.xml", "build.gradle", "build.gradle.kts",
+    "Gemfile", "composer.json", "mix.exs", "pubspec.yaml",
+    "CMakeLists.txt", "Makefile", "Dockerfile",
+    "AGENTS.md", "CLAUDE.md", ".cursorrules",
+)
+
+# Agent-instruction files surfaced separately from manifests in the snapshot.
+_CONTEXT_FILES = ("AGENTS.md", "CLAUDE.md", ".cursorrules")
+
+# Lockfile → package manager, checked in priority order.
+_PY_LOCKFILES = (("uv.lock", "uv"), ("poetry.lock", "poetry"), ("Pipfile.lock", "pipenv"))
+_JS_LOCKFILES = (
+    ("pnpm-lock.yaml", "pnpm"), ("bun.lockb", "bun"), ("bun.lock", "bun"),
+    ("yarn.lock", "yarn"), ("package-lock.json", "npm"),
+)
+
+# package.json scripts / Makefile targets worth surfacing as verify commands.
+_VERIFY_TARGETS = ("test", "tests", "lint", "typecheck", "check", "build", "fmt", "format")
+_MAX_VERIFY_COMMANDS = 8
+_MAX_FACT_FILE_BYTES = 256 * 1024
+
+_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
+# 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.
+_EDIT_FORMAT_GUIDANCE: dict[str, tuple[tuple[str, ...], str]] = {
+    "patch": (
+        ("gpt", "codex"),
+        "- Edit format: author new files with `write_file`; for edits to "
+        "existing code prefer `patch` with `mode='patch'` (V4A multi-file diff) "
+        "for structured or multi-file changes — it's the diff format you handle "
+        "most reliably. Use `mode='replace'` for a single small swap.",
+    ),
+    "replace": (
+        ("claude", "sonnet", "opus", "haiku",
+         "gemini", "gemma", "deepseek", "qwen", "kimi", "glm", "grok",
+         "hermes", "llama", "mistral", "devstral", "minimax"),
+        "- Edit format: author new files with `write_file`; for edits to "
+        "existing code prefer `patch` in `mode='replace'` — match a unique "
+        "snippet and swap it. Reach for `mode='patch'` (V4A) only when an edit "
+        "genuinely spans several files at once.",
+    ),
+}
+
+
+def _model_family(model: Optional[str]) -> Optional[str]:
+    """Classify a model id into an edit-format family key, or ``None``.
+
+    Used to steer the coding posture toward the edit tool format a model was
+    trained on. Family-agnostic by design: an unrecognised model gets ``None``
+    and the operating brief's neutral edit wording applies.
+    """
+    if not model:
+        return None
+    lowered = model.lower()
+    for family, (needles, _line) in _EDIT_FORMAT_GUIDANCE.items():
+        if any(n in lowered for n in needles):
+            return family
+    return None
+
+
+def _edit_format_line(model: Optional[str]) -> str:
+    """The edit-format guidance line for this model's family (``""`` if none)."""
+    family = _model_family(model)
+    if family is None:
+        return ""
+    return _EDIT_FORMAT_GUIDANCE[family][1]
+
+
+# Operating brief for the coding posture. Tool names referenced here (read_file,
+# search_files, patch, write_file, terminal, todo) are in the coding toolset and
+# in _HERMES_CORE_TOOLS, so they're present on every surface this fires on.
+CODING_AGENT_GUIDANCE = (
+    "You are a coding agent pairing with the user inside their codebase. "
+    "Operate like a careful senior engineer.\n"
+    "\n"
+    "Gather context first:\n"
+    "- Read the relevant files with `read_file` and locate code with "
+    "`search_files` before changing anything. Trace a symbol to its definition "
+    "and usages rather than guessing its shape.\n"
+    "- Batch independent lookups: when several reads/searches don't depend on "
+    "each other, issue them together in one turn instead of one at a time.\n"
+    "- Never invent files, symbols, APIs, or imports. If you haven't seen it in "
+    "the repo, go look. Don't assume a library is available — check the project "
+    "manifest (pyproject.toml / package.json / Cargo.toml / go.mod) and how "
+    "neighbouring files import it.\n"
+    "\n"
+    "Make changes through the tools, not the chat:\n"
+    "- Edit with `patch`/`write_file`. Do NOT print code blocks to the user as "
+    "a substitute for editing — apply the change, then summarise it. Only show "
+    "code when the user explicitly asks to see it.\n"
+    "- Match the project's existing style and conventions; AGENTS.md / "
+    "CLAUDE.md / .cursorrules already in context win over your defaults. Touch "
+    "only what the task needs — no drive-by refactors, renames, or reformatting "
+    "— and add any imports/dependencies your code requires.\n"
+    "- If an edit fails to apply, re-read the file to get the current exact "
+    "contents before retrying — don't repeat a stale patch. If the same region "
+    "fails twice, rewrite the enclosing function or file with `write_file` "
+    "instead of attempting a third patch.\n"
+    "\n"
+    "Verify, and know when to stop:\n"
+    "- Use `terminal` for git, builds, tests, and inspection. Run the relevant "
+    "tests/linter/build and confirm they pass before claiming the work is done.\n"
+    "- Fix root causes, not symptoms: when you find a bug, check sibling call "
+    "paths for the same flaw and fix the class, not just the reported site.\n"
+    "- When fixing linter/type errors on a file, stop after about three "
+    "attempts on the same file and ask the user rather than looping.\n"
+    "- Track multi-step work with `todo`. Reference code as `path:line` instead "
+    "of pasting whole files.\n"
+    "\n"
+    "Respect the user's repo: don't commit, push, or rewrite history unless "
+    "asked, and never read, print, or commit secrets — leave `.env` and "
+    "credential files alone unless the user explicitly asks. The Workspace "
+    "block below is a snapshot from session start — re-run `git status`/"
+    "`git branch` before relying on it. Be concise: lead with the change or "
+    "answer, not a preamble."
+)
+
+
+# ── Context profiles (declarative posture definitions) ──────────────────────
+
+
+@dataclass(frozen=True)
+class ContextProfile:
+    """A named operating posture. Pure data — consumers read these fields.
+
+    ``toolset``      — collapse to this toolset (+ enabled MCP) when no explicit
+                       selection is pinned; ``None`` keeps the platform default.
+    ``guidance``     — operating brief injected into the stable system prompt;
+                       ``""`` injects nothing.
+    ``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.
+    """
+
+    name: str
+    toolset: Optional[str] = None
+    guidance: str = ""
+    model_hint: Optional[str] = None
+    memory_policy: str = "default"
+    hidden_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.
+_NON_CODING_SKILL_CATEGORIES = (
+    "apple", "communication", "cooking", "creative", "email", "finance",
+    "gaming", "gifs", "health", "media", "music", "note-taking",
+    "productivity", "shopping", "smart-home", "social-media", "travel",
+    "yuanbao",
+)
+
+
+GENERAL_PROFILE = ContextProfile(name="general")
+CODING_PROFILE = ContextProfile(
+    name="coding",
+    toolset=CODING_TOOLSET,
+    guidance=CODING_AGENT_GUIDANCE,
+    model_hint="coding",
+    memory_policy="project",
+    hidden_skill_categories=_NON_CODING_SKILL_CATEGORIES,
+)
+
+_PROFILES: dict[str, ContextProfile] = {
+    GENERAL_PROFILE.name: GENERAL_PROFILE,
+    CODING_PROFILE.name: CODING_PROFILE,
+}
+
+
+def get_profile(name: str) -> ContextProfile:
+    """Return a registered profile, falling back to ``general``."""
+    return _PROFILES.get(name, GENERAL_PROFILE)
+
+
+# ── Helpers ─────────────────────────────────────────────────────────────────
+
+
+def _coding_mode(config: Optional[dict[str, Any]]) -> str:
+    """Return the normalized ``agent.coding_context`` mode (auto/focus/on/off)."""
+    if config is None:
+        try:
+            from hermes_cli.config import load_config
+
+            config = load_config()
+        except Exception:
+            config = {}
+    raw = ((config or {}).get("agent", {}) or {}).get("coding_context", "auto")
+    mode = str(raw).strip().lower()
+    if mode in {"focus", "strict", "lean"}:
+        return "focus"
+    if mode in {"on", "true", "yes", "1", "always"}:
+        return "on"
+    if mode in {"off", "false", "no", "0", "never"}:
+        return "off"
+    return "auto"
+
+
+def _resolve_cwd(cwd: Optional[str | Path]) -> Path:
+    if cwd:
+        return Path(cwd).expanduser()
+    try:
+        from agent.runtime_cwd import resolve_agent_cwd
+
+        return resolve_agent_cwd()
+    except Exception:
+        return Path(os.getcwd())
+
+
+def _git_root(cwd: Path) -> Optional[Path]:
+    current = cwd.resolve()
+    for parent in [current, *current.parents]:
+        if (parent / ".git").exists():
+            return parent
+    return None
+
+
+def _home() -> Optional[Path]:
+    try:
+        return Path.home().resolve()
+    except (OSError, RuntimeError):
+        return None
+
+
+def _marker_root(cwd: Path) -> Optional[Path]:
+    """Nearest ancestor that looks like a project root, or ``None``.
+
+    Walks up at most a few levels so a manifest in the workspace root counts
+    even when the user is in a subdirectory. ``$HOME`` itself is skipped — a
+    Makefile or AGENTS.md sitting in the home directory is global user config,
+    not a project-root signal.
+    """
+    current = cwd.resolve()
+    home = _home()
+    for depth, parent in enumerate([current, *current.parents]):
+        if depth > 6:
+            break
+        if parent == home:
+            continue
+        for marker in _PROJECT_MARKERS:
+            if (parent / marker).exists():
+                return parent
+    return None
+
+
+def _detect_profile_name(mode: str, platform: str, cwd_str: str) -> str:
+    """Resolve which profile applies.
+
+    ``auto``/``focus``: coding when the surface is interactive AND the cwd is a
+    code workspace (a git repo or a recognised project root). ``on``: always
+    coding. ``off``: always general.
+
+    A git repo rooted at ``$HOME`` (the dotfiles pattern) is NOT a workspace
+    signal — without the guard, every session anywhere under a dotfiles-managed
+    home directory would silently flip to the coding posture.
+
+    Detection is intentionally not memoized: it's a handful of ``stat`` calls,
+    and callers resolve the mode once per session anyway. Caching here would
+    risk a stale posture if a long-lived process (gateway/TUI) serves sessions
+    from different working directories.
+    """
+    if mode == "off":
+        return GENERAL_PROFILE.name
+    if mode == "on":
+        return CODING_PROFILE.name
+    if platform and platform.strip().lower() not in INTERACTIVE_CODING_PLATFORMS:
+        return GENERAL_PROFILE.name
+    cwd = Path(cwd_str)
+    git_root = _git_root(cwd)
+    if git_root is not None and git_root == _home():
+        git_root = None  # dotfiles repo at $HOME — not a code workspace
+    if git_root is not None or _marker_root(cwd) is not None:
+        return CODING_PROFILE.name
+    return GENERAL_PROFILE.name
+
+
+# ── RuntimeMode (the seam) ──────────────────────────────────────────────────
+
+
+@dataclass(frozen=True)
+class RuntimeMode:
+    """The resolved operating posture for a session. Immutable by construction.
+
+    Built once via :func:`resolve_runtime_mode` and consumed by every domain
+    that cares about the coding/general distinction. Never mutate or re-resolve
+    mid-session — that would break the prompt cache.
+    """
+
+    profile: ContextProfile
+    surface: str
+    cwd: Path
+    # The normalized ``agent.coding_context`` mode this posture was resolved
+    # under (auto/focus/on/off). Toolset collapse is gated on ``focus``.
+    config_mode: str = "auto"
+    # The model id this session runs (e.g. "anthropic/claude-opus-4.8"). Used
+    # only to steer edit-format guidance toward the model's family — see
+    # ``_edit_format_line``. Fixed for the session, so cache-safe.
+    model: Optional[str] = None
+
+    @property
+    def kind(self) -> str:
+        return self.profile.name
+
+    @property
+    def is_coding(self) -> bool:
+        return self.profile.name == CODING_PROFILE.name
+
+    def toolset_selection(self, config: Optional[dict[str, Any]] = None) -> Optional[list[str]]:
+        """Toolset list for this posture, or ``None`` to keep the platform default.
+
+        Non-``None`` only under the opt-in ``focus`` mode. The default posture
+        is prompt-only: most strippable toolsets are off-by-default anyway, and
+        a user who explicitly enabled one (image-gen for frontend/game assets,
+        messaging for build notifications, …) keeps it while coding.
+
+        Callers apply this only when the user hasn't pinned an explicit
+        selection (``--toolsets``, ``HERMES_TUI_TOOLSETS``, …); they never
+        override a pin. Returns the profile's toolset plus enabled MCP servers.
+        """
+        if self.config_mode != "focus":
+            return None
+        if self.profile.toolset is None:
+            return None
+        return [self.profile.toolset, *_enabled_mcp_servers(config)]
+
+    def system_blocks(self) -> list[str]:
+        """Stable system-prompt blocks for this posture (brief + workspace).
+
+        The operating brief carries a model-family edit-format nudge appended
+        to it (one cached string, not a separate block) so the model is steered
+        toward the `patch` mode it handles best — see ``_edit_format_line``.
+        """
+        if not self.is_coding:
+            return []
+        blocks: list[str] = []
+        if self.profile.guidance:
+            brief = self.profile.guidance
+            edit_line = _edit_format_line(self.model)
+            if edit_line:
+                brief = f"{brief}\n{edit_line}"
+            blocks.append(brief)
+        workspace = build_coding_workspace_block(self.cwd)
+        if workspace:
+            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 resolve_runtime_mode(
+    *,
+    platform: Optional[str] = None,
+    cwd: Optional[str | Path] = None,
+    config: Optional[dict[str, Any]] = None,
+    model: Optional[str] = None,
+) -> RuntimeMode:
+    """Resolve the operating posture once. Cheap — a handful of ``stat`` calls.
+
+    This is the single entry point every domain should call. The returned
+    object is immutable and safe to cache for the session. Detection itself is
+    intentionally *not* memoized (see ``_detect_profile_name``) so a long-lived
+    process can't pin a stale posture; callers resolve once per session and
+    hold the result. ``model`` is recorded only to steer edit-format guidance;
+    it never affects detection.
+    """
+    resolved_cwd = _resolve_cwd(cwd)
+    mode = _coding_mode(config)
+    name = _detect_profile_name(
+        mode, (platform or "").strip().lower(), str(resolved_cwd)
+    )
+    return RuntimeMode(
+        profile=get_profile(name),
+        surface=platform or "",
+        cwd=resolved_cwd,
+        config_mode=mode,
+        model=model,
+    )
+
+
+# ── Back-compat surface (thin wrappers over RuntimeMode) ────────────────────
+
+
+def is_coding_context(
+    *,
+    platform: Optional[str] = None,
+    cwd: Optional[str | Path] = None,
+    config: Optional[dict[str, Any]] = None,
+) -> bool:
+    """Whether Hermes should operate in its coding posture right now."""
+    return resolve_runtime_mode(platform=platform, cwd=cwd, config=config).is_coding
+
+
+def coding_selection(
+    *,
+    platform: Optional[str] = None,
+    cwd: Optional[str | Path] = None,
+    config: Optional[dict[str, Any]] = None,
+) -> Optional[list[str]]:
+    """Toolset selection for the coding posture.
+
+    ``None`` unless the user opted into ``focus`` mode AND the posture is
+    active — the default coding posture never overrides configured toolsets.
+    """
+    return resolve_runtime_mode(
+        platform=platform, cwd=cwd, config=config
+    ).toolset_selection(config)
+
+
+def coding_system_blocks(
+    *,
+    platform: Optional[str] = None,
+    cwd: Optional[str | Path] = None,
+    config: Optional[dict[str, Any]] = None,
+    model: Optional[str] = None,
+) -> list[str]:
+    """Stable system-prompt blocks for the current posture (empty when general).
+
+    ``model`` steers the brief's edit-format nudge toward the model's family.
+    """
+    return resolve_runtime_mode(
+        platform=platform, cwd=cwd, config=config, model=model
+    ).system_blocks()
+
+
+def coding_hidden_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.
+
+    Empty outside the coding posture. Discovery-only: hidden skills remain
+    loadable via ``skills_list`` / ``skill_view``.
+    """
+    return resolve_runtime_mode(
+        platform=platform, cwd=cwd, config=config
+    ).hidden_skill_categories()
+
+
+def _enabled_mcp_servers(config: Optional[dict[str, Any]]) -> list[str]:
+    """Names of MCP servers the user has enabled — kept in the coding posture.
+
+    MCP servers (figma, browser, tophat, …) are explicitly configured and part
+    of the coding workflow, not noise to strip.
+    """
+    try:
+        from hermes_cli.config import read_raw_config
+        from hermes_cli.tools_config import _parse_enabled_flag
+
+        servers = read_raw_config().get("mcp_servers") or {}
+        return [
+            str(name)
+            for name, cfg in servers.items()
+            if isinstance(cfg, dict)
+            and _parse_enabled_flag(cfg.get("enabled", True), default=True)
+        ]
+    except Exception:
+        return []
+
+
+# ── git/workspace probe ─────────────────────────────────────────────────────
+
+
+def _git(cwd: Path, *args: str) -> str:
+    try:
+        out = subprocess.run(
+            ["git", "-C", str(cwd), *args],
+            capture_output=True,
+            text=True,
+            timeout=_GIT_TIMEOUT,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return ""
+    return out.stdout.strip() if out.returncode == 0 else ""
+
+
+def _parse_status(porcelain: str) -> tuple[dict[str, str], dict[str, int]]:
+    """Parse ``git status --porcelain=2 --branch`` into branch + counts."""
+    branch: dict[str, str] = {}
+    counts = {"staged": 0, "modified": 0, "untracked": 0, "conflicts": 0}
+    for line in porcelain.splitlines():
+        if line.startswith("# branch.head"):
+            branch["head"] = line.split(maxsplit=2)[-1]
+        elif line.startswith("# branch.upstream"):
+            branch["upstream"] = line.split(maxsplit=2)[-1]
+        elif line.startswith("# branch.ab"):
+            parts = line.split()
+            branch["ahead"], branch["behind"] = parts[2].lstrip("+"), parts[3].lstrip("-")
+        elif line.startswith(("1 ", "2 ")):
+            xy = line.split(maxsplit=2)[1]
+            if xy[0] != ".":
+                counts["staged"] += 1
+            if xy[1] != ".":
+                counts["modified"] += 1
+        elif line.startswith("u "):
+            counts["conflicts"] += 1
+        elif line.startswith("? "):
+            counts["untracked"] += 1
+    return branch, counts
+
+
+def _read_small(path: Path) -> str:
+    """Read a small text file, or ``""`` — never raises, never reads huge files."""
+    try:
+        if not path.is_file() or path.stat().st_size > _MAX_FACT_FILE_BYTES:
+            return ""
+        return path.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return ""
+
+
+def _project_facts(root: Path) -> list[str]:
+    """Detected project facts for the workspace snapshot.
+
+    The point is to hand the model its *verify loop* up front — which manifest,
+    which package manager, and the exact test/lint/build commands — instead of
+    making it rediscover them every session. Cheap: stat calls plus reads of a
+    couple of small files; built once at prompt-build time (cache-safe).
+    """
+    facts: list[str] = []
+
+    manifests = [m for m in _PROJECT_MARKERS if m not in _CONTEXT_FILES and (root / m).is_file()]
+    package_managers = [
+        pm for lock, pm in (*_PY_LOCKFILES, *_JS_LOCKFILES) if (root / lock).is_file()
+    ]
+    if manifests:
+        line = f"- Project: {', '.join(manifests[:6])}"
+        if package_managers:
+            line += f" ({'/'.join(dict.fromkeys(package_managers))})"
+        facts.append(line)
+
+    verify: list[str] = []
+    if (root / "scripts" / "run_tests.sh").is_file():
+        verify.append("scripts/run_tests.sh")
+    if (root / "package.json").is_file():
+        try:
+            scripts = json.loads(_read_small(root / "package.json") or "{}").get("scripts") or {}
+        except (json.JSONDecodeError, AttributeError):
+            scripts = {}
+        js_pm = next((pm for lock, pm in _JS_LOCKFILES if (root / lock).is_file()), "npm")
+        verify.extend(f"{js_pm} run {name}" for name in _VERIFY_TARGETS if name in scripts)
+    if (root / "pytest.ini").is_file() or "[tool.pytest" in _read_small(root / "pyproject.toml"):
+        verify.append("pytest")
+    makefile = _read_small(root / "Makefile")
+    if makefile:
+        verify.extend(
+            f"make {name}" for name in _VERIFY_TARGETS
+            if re.search(rf"^{re.escape(name)}\s*:", makefile, re.MULTILINE)
+        )
+    if verify:
+        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)}")
+
+    return facts
+
+
+def build_coding_workspace_block(cwd: Optional[str | Path] = None) -> str:
+    """Workspace snapshot for the system prompt (empty outside a workspace).
+
+    Git state (branch/status/commits) when the cwd is in a repo, plus detected
+    project facts (manifest, package manager, verify commands, context files)
+    — so marker-only (non-git) projects still get a snapshot.
+    """
+    resolved = _resolve_cwd(cwd)
+    git_root = _git_root(resolved)
+    root = git_root or _marker_root(resolved)
+    if root is None:
+        return ""
+
+    lines = ["Workspace (snapshot at session start — re-check with `git` before acting on it):"]
+    lines.append(f"- Root: {root}")
+
+    if git_root is not None:
+        branch, counts = _parse_status(_git(root, "status", "--porcelain=2", "--branch"))
+        head = branch.get("head", "")
+        if head and head != "(detached)":
+            line = f"- Branch: {head}"
+            if branch.get("upstream"):
+                line += f" \u2192 {branch['upstream']}"
+                ahead, behind = branch.get("ahead", "0"), branch.get("behind", "0")
+                if ahead != "0" or behind != "0":
+                    line += f" (ahead {ahead}, behind {behind})"
+            lines.append(line)
+        elif head == "(detached)":
+            lines.append("- Branch: (detached HEAD)")
+
+        # Linked worktree: the per-worktree git dir differs from the shared common dir.
+        git_dir, common_dir = _git(root, "rev-parse", "--git-dir"), _git(root, "rev-parse", "--git-common-dir")
+        if git_dir and common_dir and Path(git_dir).resolve() != Path(common_dir).resolve():
+            main_tree = Path(common_dir).resolve().parent
+            lines.append(f"- Worktree: linked (primary tree at {main_tree})")
+
+        dirty = [f"{n} {label}" for label, n in (
+            ("staged", counts["staged"]), ("modified", counts["modified"]),
+            ("untracked", counts["untracked"]), ("conflicts", counts["conflicts"]),
+        ) if n]
+        lines.append(f"- Status: {', '.join(dirty) if dirty else 'clean'}")
+
+        recent = _git(root, "log", "-3", "--pretty=%h %s")
+        if recent:
+            lines.append("- Recent commits:")
+            lines.extend(f"    {c}" for c in recent.splitlines())
+
+    lines.extend(_project_facts(root))
+    return "\n".join(lines)
diff --git a/agent/prompt_builder.py b/agent/prompt_builder.py
index cc62c13f9dd6..202c05cb225c 100644
--- a/agent/prompt_builder.py
+++ b/agent/prompt_builder.py
@@ -1101,11 +1101,12 @@ 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,
 ) -> str:
     """Build a compact skill index for the system prompt.
 
     Two-layer cache:
-      1. In-process LRU dict keyed by (skills_dir, tools, toolsets)
+      1. In-process LRU dict keyed by (skills_dir, tools, toolsets, hidden)
       2. Disk snapshot (``.skills_prompt_snapshot.json``) validated by
          mtime/size manifest — survives process restarts
 
@@ -1115,6 +1116,12 @@ def build_skills_system_prompt(
     scanned alongside the local ``~/.hermes/skills/`` directory.  External dirs
     are read-only — they appear in the index but new skills are always created
     in the local dir.  Local skills take precedence when names collide.
+
+    ``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.
     """
     skills_dir = get_skills_dir()
     external_dirs = get_all_skills_dirs()[1:]  # skip local (index 0)
@@ -1139,6 +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 ())),
     )
     with _SKILLS_PROMPT_CACHE_LOCK:
         cached = _SKILLS_PROMPT_CACHE.get(cache_key)
@@ -1272,6 +1280,26 @@ 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.
+    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 not skills_by_category:
         result = ""
     else:
@@ -1320,6 +1348,7 @@ def build_skills_system_prompt(
             "</available_skills>\n"
             "\n"
             "Only proceed without loading a skill if genuinely none are relevant to the task."
+            + hidden_note
         )
 
     # ── Store in LRU cache ────────────────────────────────────────────
diff --git a/agent/system_prompt.py b/agent/system_prompt.py
index 4038716df487..0c6da6c22438 100644
--- a/agent/system_prompt.py
+++ b/agent/system_prompt.py
@@ -191,9 +191,21 @@ 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()
+        try:
+            from agent.coding_context import coding_hidden_skill_categories
+
+            _hidden_cats = coding_hidden_skill_categories(
+                platform=agent.platform, cwd=resolve_context_cwd()
+            )
+        except Exception:
+            _hidden_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,
         )
     else:
         skills_prompt = ""
@@ -221,6 +233,26 @@ def build_system_prompt_parts(agent: Any, system_message: Optional[str] = None)
     if _env_hints:
         stable_parts.append(_env_hints)
 
+    # Coding posture (base Hermes, any interactive coding surface in a code
+    # workspace — see agent/coding_context.py). The operating brief + the live
+    # git/workspace snapshot are built once here and cached for the session;
+    # the snapshot is never re-probed per turn (that would break the prompt
+    # cache), so the brief tells the model to re-check git before relying on it.
+    if agent.valid_tool_names:
+        try:
+            from agent.coding_context import coding_system_blocks
+
+            stable_parts.extend(
+                coding_system_blocks(
+                    platform=agent.platform,
+                    cwd=resolve_context_cwd(),
+                    model=agent.model,
+                )
+            )
+        except Exception:
+            # Coding-context probing must never block prompt build.
+            pass
+
     # Local Python toolchain probe — names python/pip/uv/PEP-668 state when
     # something is non-default so the model can pick the right install
     # strategy without discovering by failure.  Emits a single line; emits
diff --git a/cli.py b/cli.py
index 641c200ad3d5..412374ef29cc 100644
--- a/cli.py
+++ b/cli.py
@@ -13336,9 +13336,21 @@ def main(
                 else:
                     toolsets_list.append(str(t))
     else:
-        # Use the shared resolver so MCP servers are included at runtime
-        from hermes_cli.tools_config import _get_platform_tools
-        toolsets_list = sorted(_get_platform_tools(CLI_CONFIG, "cli"))
+        # Coding posture (base Hermes): with no explicit --toolsets, collapse
+        # to the coding toolset (+ enabled MCP servers) when sitting in a code
+        # workspace. See agent/coding_context.py.
+        _coding = None
+        try:
+            from agent.coding_context import coding_selection
+            _coding = coding_selection(platform="cli", config=CLI_CONFIG)
+        except Exception:
+            _coding = None
+        if _coding is not None:
+            toolsets_list = _coding
+        else:
+            # Use the shared resolver so MCP servers are included at runtime
+            from hermes_cli.tools_config import _get_platform_tools
+            toolsets_list = sorted(_get_platform_tools(CLI_CONFIG, "cli"))
     
     parsed_skills = _parse_skills_argument(skills)
 
diff --git a/hermes_cli/config.py b/hermes_cli/config.py
index 494c5ddfe3ab..c88400e05b25 100644
--- a/hermes_cli/config.py
+++ b/hermes_cli/config.py
@@ -863,6 +863,19 @@ DEFAULT_CONFIG = {
         # identity slot (SOUL.md). Empty by default. The HERMES_ENVIRONMENT_HINT
         # env var overrides this (build-time/container mechanism).
         "environment_hint": "",
+        # Coding posture — on interactive coding surfaces (CLI, TUI, desktop
+        # app, ACP) in a code workspace, Hermes adds a coding operating brief
+        # + a live git/workspace snapshot to the system prompt. See
+        # agent/coding_context.py.
+        #   "auto" (default) — prompt-only posture when the surface is
+        #                      interactive AND cwd is a code workspace.
+        #                      Toolsets are never touched; messaging platforms
+        #                      unaffected.
+        #   "focus"          — auto + collapse the toolset to the lean coding
+        #                      set (+ enabled MCP servers). Explicit opt-in.
+        #   "on"             — force the prompt posture everywhere.
+        #   "off"            — disable entirely.
+        "coding_context": "auto",
         # Staged inactivity warning: send a warning to the user at this
         # threshold before escalating to a full timeout.  The warning fires
         # once per run and does not interrupt the agent.  0 = disable warning.
diff --git a/hermes_cli/tools_config.py b/hermes_cli/tools_config.py
index 01d4ba727931..d71fd5edb738 100644
--- a/hermes_cli/tools_config.py
+++ b/hermes_cli/tools_config.py
@@ -1437,6 +1437,10 @@ def _get_platform_tools(
             continue
         if ts_def.get("includes"):
             continue
+        # Posture toolsets (e.g. ``coding``) are session-level selections made
+        # by agent/coding_context.py — not per-platform capabilities to recover.
+        if ts_def.get("posture"):
+            continue
         ts_tools = set(resolve_toolset(ts_key))
         if not ts_tools or not ts_tools.issubset(platform_tool_universe):
             continue
diff --git a/tests/agent/test_coding_context.py b/tests/agent/test_coding_context.py
new file mode 100644
index 000000000000..ab88e391ad15
--- /dev/null
+++ b/tests/agent/test_coding_context.py
@@ -0,0 +1,405 @@
+"""Tests for agent.coding_context — RuntimeMode seam, resolver, toolset, git probe."""
+
+import json
+import subprocess
+from pathlib import Path
+
+import pytest
+
+from agent import coding_context as cc
+
+
+def _git_init(path):
+    env = {
+        "GIT_AUTHOR_NAME": "t", "GIT_AUTHOR_EMAIL": "t@t",
+        "GIT_COMMITTER_NAME": "t", "GIT_COMMITTER_EMAIL": "t@t",
+    }
+    for args in (
+        ["init", "-q", "-b", "main"],
+        ["commit", "-q", "--allow-empty", "-m", "init commit"],
+    ):
+        subprocess.run(["git", "-C", str(path), *args], check=True, env={**env, "HOME": str(path)})
+
+
+# ── resolver ──────────────────────────────────────────────────────────────
+
+class TestIsCodingContext:
+    def test_off_never_activates(self, tmp_path):
+        _git_init(tmp_path)
+        cfg = {"agent": {"coding_context": "off"}}
+        assert cc.is_coding_context(platform="cli", cwd=tmp_path, config=cfg) is False
+
+    def test_on_forces_even_without_git(self, tmp_path):
+        cfg = {"agent": {"coding_context": "on"}}
+        assert cc.is_coding_context(platform="telegram", cwd=tmp_path, config=cfg) is True
+
+    def test_auto_requires_git_repo(self, tmp_path):
+        cfg = {"agent": {"coding_context": "auto"}}
+        assert cc.is_coding_context(platform="cli", cwd=tmp_path, config=cfg) is False
+        _git_init(tmp_path)
+        assert cc.is_coding_context(platform="cli", cwd=tmp_path, config=cfg) is True
+
+    def test_auto_skips_messaging_surfaces(self, tmp_path):
+        _git_init(tmp_path)
+        cfg = {"agent": {"coding_context": "auto"}}
+        assert cc.is_coding_context(platform="discord", cwd=tmp_path, config=cfg) is False
+        assert cc.is_coding_context(platform="tui", cwd=tmp_path, config=cfg) is True
+
+    def test_default_mode_is_auto(self, tmp_path):
+        # Unknown/missing value normalizes to auto.
+        _git_init(tmp_path)
+        assert cc.is_coding_context(platform="cli", cwd=tmp_path, config={}) is True
+
+
+# ── toolset substitution ────────────────────────────────────────────────────
+
+class TestCodingSelection:
+    def test_selects_coding_under_focus(self, tmp_path):
+        _git_init(tmp_path)
+        cfg = {"agent": {"coding_context": "focus"}}
+        out = cc.coding_selection(platform="cli", cwd=tmp_path, config=cfg)
+        assert out is not None
+        assert out[0] == cc.CODING_TOOLSET
+
+    def test_auto_is_prompt_only(self, tmp_path):
+        # Default posture must never override the user's configured toolsets —
+        # off-by-default toolsets are already off, and explicit opt-ins
+        # (image-gen, spotify, …) survive entering a code workspace.
+        _git_init(tmp_path)
+        cfg = {"agent": {"coding_context": "auto"}}
+        assert cc.coding_selection(platform="cli", cwd=tmp_path, config=cfg) is None
+        # …while the prompt posture is still active.
+        assert cc.is_coding_context(platform="cli", cwd=tmp_path, config=cfg) is True
+
+    def test_on_is_prompt_only(self, tmp_path):
+        cfg = {"agent": {"coding_context": "on"}}
+        assert cc.coding_selection(platform="cli", cwd=tmp_path, config=cfg) is None
+        assert cc.is_coding_context(platform="cli", cwd=tmp_path, config=cfg) is True
+
+    def test_focus_requires_workspace(self, tmp_path):
+        # focus inherits auto's detection gate — bare dir stays general.
+        cfg = {"agent": {"coding_context": "focus"}}
+        assert cc.coding_selection(platform="cli", cwd=tmp_path, config=cfg) is None
+
+    def test_none_when_inactive(self, tmp_path):
+        cfg = {"agent": {"coding_context": "off"}}
+        assert cc.coding_selection(platform="cli", cwd=tmp_path, config=cfg) is None
+
+    def test_coding_toolset_is_registered(self):
+        from toolsets import resolve_toolset
+
+        tools = resolve_toolset(cc.CODING_TOOLSET)
+        # Coding essentials present…
+        for t in ("read_file", "write_file", "patch", "search_files", "terminal", "todo"):
+            assert t in tools
+        # …and the noise is gone.
+        for t in ("send_message", "text_to_speech", "image_generate", "computer_use"):
+            assert t not in tools
+
+
+# ── git/workspace probe ─────────────────────────────────────────────────────
+
+class TestWorkspaceBlock:
+    def test_empty_outside_repo(self, tmp_path):
+        assert cc.build_coding_workspace_block(tmp_path) == ""
+
+    def test_reports_branch_and_clean_status(self, tmp_path):
+        _git_init(tmp_path)
+        block = cc.build_coding_workspace_block(tmp_path)
+        assert "Workspace" in block
+        assert f"Root: {tmp_path.resolve()}" in block or "Root:" in block
+        assert "Branch: main" in block
+        assert "Status: clean" in block
+        assert "init commit" in block
+
+    def test_reports_dirty_counts(self, tmp_path):
+        _git_init(tmp_path)
+        (tmp_path / "untracked.txt").write_text("hi")
+        block = cc.build_coding_workspace_block(tmp_path)
+        assert "untracked" in block
+        assert "clean" not in block.split("Status:")[1].splitlines()[0]
+
+
+# ── project facts (verify-loop detection) ───────────────────────────────────
+
+class TestProjectFacts:
+    def test_package_json_scripts_surface_verify_commands(self, tmp_path):
+        _git_init(tmp_path)
+        (tmp_path / "package.json").write_text(
+            json.dumps({"scripts": {"test": "vitest", "lint": "eslint .", "dev": "vite"}})
+        )
+        (tmp_path / "pnpm-lock.yaml").write_text("")
+        block = cc.build_coding_workspace_block(tmp_path)
+        assert "Project: package.json (pnpm)" in block
+        assert "pnpm run test" in block and "pnpm run lint" in block
+        # Non-verify scripts (dev servers, …) stay out of the snapshot.
+        assert "run dev" not in block
+
+    def test_pytest_config_and_run_tests_script(self, tmp_path):
+        _git_init(tmp_path)
+        (tmp_path / "pyproject.toml").write_text("[tool.pytest.ini_options]\n")
+        scripts = tmp_path / "scripts"
+        scripts.mkdir()
+        (scripts / "run_tests.sh").write_text("#!/bin/sh\n")
+        block = cc.build_coding_workspace_block(tmp_path)
+        assert "scripts/run_tests.sh" in block
+        assert "pytest" in block.split("Verify:")[1]
+
+    def test_makefile_verify_targets_only(self, tmp_path):
+        _git_init(tmp_path)
+        (tmp_path / "Makefile").write_text("test:\n\tgo test ./...\n\ndeploy:\n\t./deploy.sh\n")
+        block = cc.build_coding_workspace_block(tmp_path)
+        assert "make test" in block
+        assert "make deploy" not in block
+
+    def test_context_files_listed(self, tmp_path):
+        _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
+
+    def test_marker_only_project_gets_snapshot_without_git(self, tmp_path):
+        # A non-git project (manifest only) still gets a workspace snapshot —
+        # just without the git lines.
+        (tmp_path / "package.json").write_text("{}")
+        block = cc.build_coding_workspace_block(tmp_path)
+        assert f"Root: {tmp_path.resolve()}" in block
+        assert "package.json" in block
+        assert "Branch:" not in block and "Status:" not in block
+
+    def test_malformed_package_json_is_ignored(self, tmp_path):
+        _git_init(tmp_path)
+        (tmp_path / "package.json").write_text("{not json")
+        block = cc.build_coding_workspace_block(tmp_path)
+        assert "Project: package.json" in block
+        assert "Verify:" not in block
+
+
+# ── $HOME dotfiles guard ────────────────────────────────────────────────────
+
+class TestHomeDotfilesGuard:
+    def test_dotfiles_repo_at_home_is_not_coding(self, tmp_path, monkeypatch):
+        home = tmp_path / "home"
+        home.mkdir()
+        _git_init(home)
+        monkeypatch.setattr(Path, "home", lambda: home)
+        cfg = {"agent": {"coding_context": "auto"}}
+        assert cc.is_coding_context(platform="cli", cwd=home, config=cfg) is False
+        # …and a plain subdirectory of the dotfiles repo stays general too.
+        docs = home / "Documents"
+        docs.mkdir()
+        assert cc.is_coding_context(platform="cli", cwd=docs, config=cfg) is False
+
+    def test_marker_at_home_is_not_a_project_signal(self, tmp_path, monkeypatch):
+        home = tmp_path / "home"
+        home.mkdir()
+        (home / "Makefile").write_text("all:\n")
+        monkeypatch.setattr(Path, "home", lambda: home)
+        cfg = {"agent": {"coding_context": "auto"}}
+        assert cc.is_coding_context(platform="cli", cwd=home, config=cfg) is False
+
+    def test_real_project_under_dotfiles_home_still_detects(self, tmp_path, monkeypatch):
+        home = tmp_path / "home"
+        home.mkdir()
+        _git_init(home)
+        monkeypatch.setattr(Path, "home", lambda: home)
+        proj = home / "www" / "app"
+        proj.mkdir(parents=True)
+        (proj / "package.json").write_text("{}")
+        cfg = {"agent": {"coding_context": "auto"}}
+        assert cc.is_coding_context(platform="cli", cwd=proj, config=cfg) is True
+
+    def test_on_mode_bypasses_the_guard(self, tmp_path, monkeypatch):
+        home = tmp_path / "home"
+        home.mkdir()
+        monkeypatch.setattr(Path, "home", lambda: home)
+        cfg = {"agent": {"coding_context": "on"}}
+        assert cc.is_coding_context(platform="cli", cwd=home, config=cfg) is True
+
+
+# ── prompt assembly integration ─────────────────────────────────────────────
+
+class TestStatusParsing:
+    def test_parse_status_counts_and_branch(self):
+        porcelain = (
+            "# branch.head feature\n"
+            "# branch.upstream origin/feature\n"
+            "# branch.ab +2 -1\n"
+            "1 M. N... 100644 100644 100644 aaa bbb staged.py\n"
+            "1 .M N... 100644 100644 100644 ccc ddd modified.py\n"
+            "? new.py\n"
+            "u UU N... 1 2 3 abc def conflict.py\n"
+        )
+        branch, counts = cc._parse_status(porcelain)
+        assert branch["head"] == "feature"
+        assert branch["upstream"] == "origin/feature"
+        assert branch["ahead"] == "2" and branch["behind"] == "1"
+        assert counts["staged"] == 1
+        assert counts["modified"] == 1
+        assert counts["untracked"] == 1
+        assert counts["conflicts"] == 1
+
+
+# ── RuntimeMode seam ────────────────────────────────────────────────────────
+
+class TestRuntimeMode:
+    def test_resolves_coding_in_repo(self, tmp_path):
+        _git_init(tmp_path)
+        mode = cc.resolve_runtime_mode(platform="cli", cwd=tmp_path, config={})
+        assert mode.is_coding is True
+        assert mode.kind == "coding"
+        assert mode.profile is cc.CODING_PROFILE
+
+    def test_resolves_general_outside_workspace(self, tmp_path):
+        mode = cc.resolve_runtime_mode(platform="cli", cwd=tmp_path, config={})
+        assert mode.is_coding is False
+        assert mode.kind == "general"
+        # General posture pins no toolset and injects no blocks.
+        assert mode.toolset_selection() is None
+        assert mode.system_blocks() == []
+
+    def test_is_frozen(self, tmp_path):
+        mode = cc.resolve_runtime_mode(platform="cli", cwd=tmp_path, config={})
+        with pytest.raises(Exception):
+            mode.profile = cc.CODING_PROFILE  # type: ignore[misc]
+
+    def test_system_blocks_include_brief_and_workspace(self, tmp_path):
+        _git_init(tmp_path)
+        mode = cc.resolve_runtime_mode(platform="cli", cwd=tmp_path, config={"agent": {"coding_context": "on"}})
+        blocks = mode.system_blocks()
+        assert any("coding agent" in b for b in blocks)
+        assert any("Workspace" in b for b in blocks)
+
+    def test_toolset_selection_gated_on_focus(self, tmp_path):
+        _git_init(tmp_path)
+        focus = cc.resolve_runtime_mode(platform="cli", cwd=tmp_path, config={"agent": {"coding_context": "focus"}})
+        sel = focus.toolset_selection()
+        assert sel and sel[0] == cc.CODING_TOOLSET
+        # auto/on resolve the coding profile but stay prompt-only.
+        for raw in ("auto", "on"):
+            mode = cc.resolve_runtime_mode(platform="cli", cwd=tmp_path, config={"agent": {"coding_context": raw}})
+            assert mode.is_coding is True
+            assert mode.toolset_selection() is None
+
+
+# ── edit-format steering (per-model harness tuning) ──────────────────────────
+
+class TestEditFormatSteering:
+    def test_family_detection(self):
+        assert cc._model_family("openai/gpt-5.4") == "patch"
+        assert cc._model_family("openai/codex-mini") == "patch"
+        assert cc._model_family("anthropic/claude-opus-4.8") == "replace"
+        assert cc._model_family("anthropic/claude-sonnet-4") == "replace"
+        # Gemini + open-weight coding models (RL'd on str_replace-style
+        # editors) steer to replace, not neutral.
+        for m in (
+            "google/gemini-3-pro", "deepseek-v3.2", "qwen3-coder",
+            "moonshot/kimi-k2", "zai/glm-4.6", "nousresearch/hermes-4-405b",
+        ):
+            assert cc._model_family(m) == "replace"
+        # Unknown family and no model both fall through to neutral wording.
+        assert cc._model_family("acme/foo-1") is None
+        assert cc._model_family(None) is None
+        assert cc._model_family("") is None
+
+    def test_openai_family_gets_v4a_nudge(self, tmp_path):
+        _git_init(tmp_path)
+        mode = cc.resolve_runtime_mode(
+            platform="cli", cwd=tmp_path,
+            config={"agent": {"coding_context": "on"}}, model="openai/gpt-5.4",
+        )
+        brief = mode.system_blocks()[0]
+        assert "mode='patch'" in brief
+        assert "V4A" in brief
+        assert "write_file" in brief  # new files authored, not patched
+
+    def test_anthropic_family_gets_replace_nudge(self, tmp_path):
+        _git_init(tmp_path)
+        mode = cc.resolve_runtime_mode(
+            platform="cli", cwd=tmp_path,
+            config={"agent": {"coding_context": "on"}},
+            model="anthropic/claude-opus-4.8",
+        )
+        brief = mode.system_blocks()[0]
+        assert "mode='replace'" in brief
+        assert "write_file" in brief  # new files authored, not patched
+
+    def test_unknown_model_keeps_neutral_brief(self, tmp_path):
+        # No edit-format line appended — brief equals the bare profile guidance.
+        _git_init(tmp_path)
+        mode = cc.resolve_runtime_mode(
+            platform="cli", cwd=tmp_path,
+            config={"agent": {"coding_context": "on"}}, model="acme/foo-1",
+        )
+        assert mode.system_blocks()[0] == cc.CODING_AGENT_GUIDANCE
+
+    def test_no_model_keeps_neutral_brief(self, tmp_path):
+        _git_init(tmp_path)
+        mode = cc.resolve_runtime_mode(
+            platform="cli", cwd=tmp_path,
+            config={"agent": {"coding_context": "on"}},
+        )
+        assert mode.system_blocks()[0] == cc.CODING_AGENT_GUIDANCE
+
+    def test_general_posture_emits_nothing_regardless_of_model(self, tmp_path):
+        # Edit steering only fires inside the coding posture.
+        mode = cc.resolve_runtime_mode(
+            platform="telegram", cwd=tmp_path, config={}, model="openai/gpt-5.4",
+        )
+        assert mode.system_blocks() == []
+
+
+# ── profile registry ────────────────────────────────────────────────────────
+
+class TestProfiles:
+    def test_registered_profiles(self):
+        assert cc.get_profile("coding") is cc.CODING_PROFILE
+        assert cc.get_profile("general") is cc.GENERAL_PROFILE
+
+    def test_unknown_profile_falls_back_to_general(self):
+        assert cc.get_profile("nonsense") is cc.GENERAL_PROFILE
+
+    def test_coding_profile_shape(self):
+        # The coding profile declares the seams other domains read.
+        assert cc.CODING_PROFILE.toolset == cc.CODING_TOOLSET
+        assert cc.CODING_PROFILE.guidance
+        assert cc.CODING_PROFILE.model_hint == "coding"
+        # General is inert.
+        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).
+        _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()
+
+
+# ── detection signals ───────────────────────────────────────────────────────
+
+class TestDetection:
+    @pytest.mark.parametrize("marker", ["pyproject.toml", "package.json", "go.mod", "AGENTS.md"])
+    def test_project_manifest_triggers_without_git(self, tmp_path, marker):
+        (tmp_path / marker).write_text("x")
+        cfg = {"agent": {"coding_context": "auto"}}
+        assert cc.is_coding_context(platform="cli", cwd=tmp_path, config=cfg) is True
+
+    def test_marker_in_parent_counts_from_subdir(self, tmp_path):
+        (tmp_path / "pyproject.toml").write_text("x")
+        sub = tmp_path / "src" / "pkg"
+        sub.mkdir(parents=True)
+        cfg = {"agent": {"coding_context": "auto"}}
+        assert cc.is_coding_context(platform="cli", cwd=sub, config=cfg) is True
+
+    def test_bare_dir_is_not_coding(self, tmp_path):
+        cfg = {"agent": {"coding_context": "auto"}}
+        assert cc.is_coding_context(platform="cli", cwd=tmp_path, config=cfg) is False
diff --git a/tests/agent/test_prompt_builder.py b/tests/agent/test_prompt_builder.py
index 856a047253f2..744a91780290 100644
--- a/tests/agent/test_prompt_builder.py
+++ b/tests/agent/test_prompt_builder.py
@@ -276,6 +276,42 @@ 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."""
+        monkeypatch.setenv("HERMES_HOME", str(tmp_path))
+        for cat, name in (("social-media", "tweet-stuff"), ("github", "pr-review")):
+            d = tmp_path / "skills" / cat / name
+            d.mkdir(parents=True)
+            (d / "SKILL.md").write_text(
+                f"---\nname: {name}\ndescription: Does {name} things\n---\n"
+            )
+
+        result = build_skills_system_prompt(
+            hidden_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
+
+    def test_hidden_categories_prune_nested_and_miss_cache_separately(
+        self, monkeypatch, tmp_path
+    ):
+        monkeypatch.setenv("HERMES_HOME", str(tmp_path))
+        d = tmp_path / "skills" / "social-media" / "twitter" / "thread-writer"
+        d.mkdir(parents=True)
+        (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"})
+        )
+        assert "thread-writer" not in pruned
+        # Unfiltered call must not be served from the filtered cache entry.
+        full = build_skills_system_prompt()
+        assert "thread-writer" in full
+
     def test_excludes_incompatible_platform_skills(self, monkeypatch, tmp_path):
         """Skills with platforms: [macos] should not appear on Linux."""
         monkeypatch.setenv("HERMES_HOME", str(tmp_path))
diff --git a/tests/agent/test_system_prompt.py b/tests/agent/test_system_prompt.py
index 75bf28b54d88..b9e1439e1a94 100644
--- a/tests/agent/test_system_prompt.py
+++ b/tests/agent/test_system_prompt.py
@@ -55,3 +55,44 @@ class TestContextFileCwd:
     def test_configured_dir_when_terminal_cwd_set(self, monkeypatch, tmp_path):
         monkeypatch.setenv("TERMINAL_CWD", str(tmp_path))
         assert _captured_context_cwd(_make_agent()) == tmp_path
+
+
+def _stable_prompt(agent):
+    with (
+        patch("run_agent.load_soul_md", return_value=""),
+        patch("run_agent.build_nous_subscription_prompt", return_value=""),
+        patch("run_agent.build_environment_hints", return_value=""),
+        patch("run_agent.build_context_files_prompt", return_value=""),
+    ):
+        return build_system_prompt_parts(agent)["stable"]
+
+
+class TestCodingContextBlock:
+    def test_injected_when_active(self, monkeypatch, tmp_path):
+        import subprocess
+
+        subprocess.run(["git", "-C", str(tmp_path), "init", "-q"], check=True)
+        monkeypatch.setenv("TERMINAL_CWD", str(tmp_path))
+        agent = _make_agent(valid_tool_names=["read_file"], platform="cli")
+        stable = _stable_prompt(agent)
+        assert "coding agent" in stable
+        assert "Workspace" in stable
+
+    def test_absent_when_off(self, monkeypatch, tmp_path):
+        import subprocess
+
+        subprocess.run(["git", "-C", str(tmp_path), "init", "-q"], check=True)
+        monkeypatch.setenv("TERMINAL_CWD", str(tmp_path))
+        agent = _make_agent(valid_tool_names=["read_file"], platform="cli")
+        # Drive the real path: force the resolved mode to "off" via config.
+        with patch("agent.coding_context._coding_mode", return_value="off"):
+            stable = _stable_prompt(agent)
+        assert "coding agent" not in stable
+
+    def test_absent_without_tools(self, monkeypatch, tmp_path):
+        import subprocess
+
+        subprocess.run(["git", "-C", str(tmp_path), "init", "-q"], check=True)
+        monkeypatch.setenv("TERMINAL_CWD", str(tmp_path))
+        agent = _make_agent(valid_tool_names=[], platform="cli")
+        assert "coding agent" not in _stable_prompt(agent)
diff --git a/toolsets.py b/toolsets.py
index 901b072f46ce..5c67bfb21148 100644
--- a/toolsets.py
+++ b/toolsets.py
@@ -339,6 +339,33 @@ TOOLSETS = {
         "tools": [],
         "includes": ["web", "vision", "image_gen"]
     },
+
+    # Coding posture (base Hermes — CLI/TUI/desktop/ACP). Auto-selected in a
+    # code workspace; see agent/coding_context.py. Keeps everything you reach
+    # for while pairing on code and drops the rest (messaging, tts, image_gen,
+    # spotify, home-assistant, cron, computer-use).
+    "coding": {
+        "description": "Coding-focused toolset: files, terminal, search, web docs, skills, todo, delegate, vision, browser",
+        "tools": [
+            "web_search", "web_extract",
+            "terminal", "process", "read_terminal",
+            "read_file", "write_file", "patch", "search_files",
+            "vision_analyze",
+            "skills_list", "skill_view", "skill_manage",
+            "browser_navigate", "browser_snapshot", "browser_click",
+            "browser_type", "browser_scroll", "browser_back",
+            "browser_press", "browser_get_images",
+            "browser_vision", "browser_console", "browser_cdp", "browser_dialog",
+            "todo", "memory",
+            "session_search", "clarify",
+            "execute_code", "delegate_task",
+        ],
+        "includes": [],
+        # Posture toolset: selected per-session by agent/coding_context.py,
+        # never auto-recovered into per-platform tool config (see the
+        # non-configurable-toolset recovery loop in hermes_cli/tools_config.py).
+        "posture": True,
+    },
     
     # ==========================================================================
     # Full Hermes toolsets (CLI + messaging platforms)
diff --git a/tui_gateway/server.py b/tui_gateway/server.py
index 5af8530abc5b..d932e98510f5 100644
--- a/tui_gateway/server.py
+++ b/tui_gateway/server.py
@@ -1680,6 +1680,22 @@ def _load_enabled_toolsets() -> list[str] | None:
     cfg = None
     fallback_notice = None
 
+    # Coding posture (base Hermes): with no explicit pin, collapse to the
+    # coding toolset (+ enabled MCP servers) when sitting in a code workspace.
+    # The desktop app and `hermes --tui` both land here. See
+    # agent/coding_context.py. No config is loaded yet at this point, so we let
+    # coding_selection() load it lazily (cli.py passes its already-resolved
+    # CLI_CONFIG instead, purely to avoid a redundant read).
+    if not explicit:
+        try:
+            from agent.coding_context import coding_selection
+
+            selection = coding_selection(platform="tui")
+            if selection is not None:
+                return selection
+        except Exception:
+            pass
+
     try:
         from toolsets import validate_toolset
     except Exception:

From c710868fbca9bdf7adb155c68ecbdd74858ede9f Mon Sep 17 00:00:00 2001
From: Brooklyn Nicholson <brooklyn.bb.nicholson@gmail.com>
Date: Wed, 10 Jun 2026 23:39:35 -0500
Subject: [PATCH 21/28] refactor(desktop): decouple composer from session
 lifecycle entirely
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The composer is a single global surface that sits ABOVE the thread: its
contents follow the user across session switches and are never touched
by session lifecycle. Switching threads doesn't change the render.

Replaces the per-scope draft choreography (scoped storage keys, attachment
stash map, skip-sentinel, restore-on-scope-change effect) with:
- one global localStorage key so an unsent draft survives app reloads
- a one-shot restore on mount
- nothing else — session switches simply don't touch the composer

Verified E2E via CDP with real sidebar clicks + real keystrokes:
typed draft survives A->B->A switching and a full page reload.
---
 apps/desktop/src/app/chat/composer/index.tsx | 78 +++++++------------
 apps/desktop/src/store/composer.test.ts      | 82 ++++----------------
 apps/desktop/src/store/composer.ts           | 64 +++------------
 3 files changed, 50 insertions(+), 174 deletions(-)

diff --git a/apps/desktop/src/app/chat/composer/index.tsx b/apps/desktop/src/app/chat/composer/index.tsx
index e55e50192054..511713d086f3 100644
--- a/apps/desktop/src/app/chat/composer/index.tsx
+++ b/apps/desktop/src/app/chat/composer/index.tsx
@@ -28,11 +28,8 @@ import {
   $composerAttachments,
   clearComposerAttachments,
   clearPersistedComposerDraft,
-  clearStashedComposerAttachments,
   type ComposerAttachment,
   readPersistedComposerDraft,
-  stashComposerAttachments,
-  takeComposerAttachments,
   writePersistedComposerDraft
 } from '@/store/composer'
 import {
@@ -174,7 +171,6 @@ export function ChatBar({
   const scrolledUp = useStore($threadScrolledUp)
   const sessionMessages = useStore($messages)
   const activeQueueSessionKey = queueSessionKey || sessionId || null
-  const draftPersistenceScope = activeQueueSessionKey || null
 
   const queuedPrompts = useMemo(
     () => (activeQueueSessionKey ? (queuedPromptsBySession[activeQueueSessionKey] ?? []) : []),
@@ -186,12 +182,7 @@ export function ChatBar({
   const editorRef = useRef<HTMLDivElement | null>(null)
   const draftRef = useRef(draft)
   const previousBusyRef = useRef(busy)
-  // `undefined` = no skip pending. The sentinel must be distinguishable from a
-  // real scope, and `null` IS a real scope (the unsaved-new-session draft):
-  // resetting to null made every persist run in a new chat match the consumed
-  // sentinel and bail, so new-chat drafts were never written at all.
-  const skipNextDraftPersistScopeRef = useRef<string | null | undefined>(undefined)
-  const pendingDraftPersistRef = useRef<{ scope: string | null; value: string } | null>(null)
+  const pendingDraftPersistRef = useRef<string | null>(null)
   const drainingQueueRef = useRef(false)
   const urlInputRef = useRef<HTMLInputElement | null>(null)
 
@@ -1118,65 +1109,50 @@ export function ChatBar({
     }
   }
 
-  // Restore a scope's draft (persisted text + in-memory attachments) when we
-  // enter it, and stash the attachments back when we leave. Text rides through
-  // localStorage so it survives reloads; attachments carry live blobs/upload
-  // state that can't serialize, so they're retained in memory only — enough to
-  // survive a session switch, which is the case users actually hit.
+  // The composer deliberately does NOT react to session switches: it sits
+  // above the thread and its contents follow the user. The only restore is a
+  // one-shot on mount so an unsent draft survives an app reload.
   useEffect(() => {
-    const persisted = readPersistedComposerDraft(draftPersistenceScope)
-    const restoredAttachments = takeComposerAttachments(draftPersistenceScope)
-    skipNextDraftPersistScopeRef.current = draftPersistenceScope
-    loadIntoComposer(persisted, restoredAttachments)
+    const persisted = readPersistedComposerDraft()
 
-    return () => {
-      stashComposerAttachments(draftPersistenceScope, $composerAttachments.get())
+    if (persisted && !draftRef.current.trim()) {
+      loadIntoComposer(persisted, $composerAttachments.get())
     }
-  }, [draftPersistenceScope]) // eslint-disable-line react-hooks/exhaustive-deps
+  }, []) // eslint-disable-line react-hooks/exhaustive-deps
 
   useEffect(() => {
-    if (skipNextDraftPersistScopeRef.current === draftPersistenceScope) {
-      skipNextDraftPersistScopeRef.current = undefined
-
-      return
-    }
-
     // Don't persist programmatically-loaded text: browsing sent-message
     // history or editing a queued prompt swaps the composer to recalled text,
     // and persisting that would clobber the genuine in-progress draft (which
-    // history keeps in its own snapshot and restores on the way back). Leaving
-    // the prior pending write untouched keeps the real draft in storage.
+    // history keeps in its own snapshot and restores on the way back).
     if (isBrowsingHistory(sessionId) || queueEdit) {
       return
     }
 
     // Debounce the localStorage write: the composer's per-keystroke path was
     // deliberately slimmed down (see the draftRef sync comment above), so we
-    // don't touch storage on every keypress. The pending ref below is flushed
-    // on scope change / unmount so a fast session switch can't drop the
-    // trailing keystrokes.
-    pendingDraftPersistRef.current = { scope: draftPersistenceScope, value: draft }
+    // don't touch storage on every keypress.
+    pendingDraftPersistRef.current = draft
 
     const handle = window.setTimeout(() => {
       pendingDraftPersistRef.current = null
-      writePersistedComposerDraft(draftPersistenceScope, draft)
+      writePersistedComposerDraft(draft)
     }, DRAFT_PERSIST_DEBOUNCE_MS)
 
     return () => window.clearTimeout(handle)
-  }, [draft, draftPersistenceScope, queueEdit, sessionId])
+  }, [draft, queueEdit, sessionId])
 
-  // Flush any pending debounced draft write when leaving a session scope,
-  // unmounting, or the window unloading, so the latest text is always
-  // persisted. The pagehide listener is load-bearing: React does NOT run
-  // effect cleanups on a page reload, so without it a Cmd+R inside the
-  // debounce window silently dropped everything typed in the last 400ms.
+  // Flush any pending debounced write on unmount or window unload. The
+  // pagehide listener is load-bearing: React does NOT run effect cleanups on
+  // a page reload, so without it a Cmd+R inside the debounce window would
+  // silently drop everything typed in the last 400ms.
   useEffect(() => {
     const flushPendingDraftPersist = () => {
       const pending = pendingDraftPersistRef.current
 
-      if (pending) {
+      if (pending !== null) {
         pendingDraftPersistRef.current = null
-        writePersistedComposerDraft(pending.scope, pending.value)
+        writePersistedComposerDraft(pending)
       }
     }
 
@@ -1186,7 +1162,7 @@ export function ChatBar({
       window.removeEventListener('pagehide', flushPendingDraftPersist)
       flushPendingDraftPersist()
     }
-  }, [draftPersistenceScope])
+  }, [])
 
   const beginQueuedEdit = (entry: QueuedPromptEntry) => {
     if (!activeQueueSessionKey || queueEdit) {
@@ -1444,14 +1420,13 @@ export function ChatBar({
         void Promise.resolve(onSubmit(submitted)).then(accepted => {
           if (accepted === false) {
             loadIntoComposer(submitted, [])
-            writePersistedComposerDraft(draftPersistenceScope, submitted)
+            writePersistedComposerDraft(submitted)
           } else {
-            clearPersistedComposerDraft(draftPersistenceScope)
-            clearStashedComposerAttachments(draftPersistenceScope)
+            clearPersistedComposerDraft()
           }
         }).catch(() => {
           loadIntoComposer(submitted, [])
-          writePersistedComposerDraft(draftPersistenceScope, submitted)
+          writePersistedComposerDraft(submitted)
         })
       } else if (payloadPresent) {
         queueCurrentDraft()
@@ -1473,14 +1448,13 @@ export function ChatBar({
       void Promise.resolve(onSubmit(submitted, { attachments: submittedAttachments })).then(accepted => {
         if (accepted === false) {
           loadIntoComposer(submitted, submittedAttachments)
-          writePersistedComposerDraft(draftPersistenceScope, submitted)
+          writePersistedComposerDraft(submitted)
         } else {
-          clearPersistedComposerDraft(draftPersistenceScope)
-          clearStashedComposerAttachments(draftPersistenceScope)
+          clearPersistedComposerDraft()
         }
       }).catch(() => {
         loadIntoComposer(submitted, submittedAttachments)
-        writePersistedComposerDraft(draftPersistenceScope, submitted)
+        writePersistedComposerDraft(submitted)
       })
     }
 
diff --git a/apps/desktop/src/store/composer.test.ts b/apps/desktop/src/store/composer.test.ts
index 05ecef225586..efa9fcba4db1 100644
--- a/apps/desktop/src/store/composer.test.ts
+++ b/apps/desktop/src/store/composer.test.ts
@@ -4,13 +4,10 @@ import {
   $composerAttachments,
   addComposerAttachment,
   clearPersistedComposerDraft,
-  clearStashedComposerAttachments,
+  COMPOSER_DRAFT_STORAGE_KEY,
   type ComposerAttachment,
-  composerDraftStorageKey,
   readPersistedComposerDraft,
   removeComposerAttachment,
-  stashComposerAttachments,
-  takeComposerAttachments,
   updateComposerAttachment,
   writePersistedComposerDraft
 } from './composer'
@@ -49,83 +46,30 @@ describe('updateComposerAttachment', () => {
   })
 })
 
-describe('persisted composer drafts', () => {
+describe('persisted composer draft', () => {
   afterEach(() => {
     window.localStorage.clear()
   })
 
-  it('stores and restores text drafts per session scope', () => {
-    writePersistedComposerDraft('session-a', 'almost submitted prompt')
-    writePersistedComposerDraft('session-b', 'other draft')
+  it('stores and restores the draft', () => {
+    writePersistedComposerDraft('almost submitted prompt')
 
-    expect(readPersistedComposerDraft('session-a')).toBe('almost submitted prompt')
-    expect(readPersistedComposerDraft('session-b')).toBe('other draft')
-  })
-
-  it('uses a stable new-session key when no session id exists yet', () => {
-    writePersistedComposerDraft(null, 'first prompt draft')
-
-    expect(window.localStorage.getItem(composerDraftStorageKey(null))).toBe('first prompt draft')
-    expect(readPersistedComposerDraft(undefined)).toBe('first prompt draft')
+    expect(readPersistedComposerDraft()).toBe('almost submitted prompt')
+    expect(window.localStorage.getItem(COMPOSER_DRAFT_STORAGE_KEY)).toBe('almost submitted prompt')
   })
 
   it('removes empty drafts instead of leaving stale text behind', () => {
-    writePersistedComposerDraft('session-a', 'saved')
-    writePersistedComposerDraft('session-a', '')
+    writePersistedComposerDraft('saved')
+    writePersistedComposerDraft('')
 
-    expect(readPersistedComposerDraft('session-a')).toBe('')
-    expect(window.localStorage.getItem(composerDraftStorageKey('session-a'))).toBeNull()
+    expect(readPersistedComposerDraft()).toBe('')
+    expect(window.localStorage.getItem(COMPOSER_DRAFT_STORAGE_KEY)).toBeNull()
   })
 
   it('can explicitly clear a saved draft after submit', () => {
-    writePersistedComposerDraft('session-a', 'saved')
-    clearPersistedComposerDraft('session-a')
+    writePersistedComposerDraft('saved')
+    clearPersistedComposerDraft()
 
-    expect(readPersistedComposerDraft('session-a')).toBe('')
-  })
-})
-
-describe('stashed composer attachments', () => {
-  afterEach(() => {
-    clearStashedComposerAttachments('session-a')
-    clearStashedComposerAttachments('session-b')
-    clearStashedComposerAttachments(null)
-  })
-
-  it('retains and restores attachments per session scope', () => {
-    stashComposerAttachments('session-a', [attachment({ id: 'file:a' })])
-    stashComposerAttachments('session-b', [attachment({ id: 'image:b', kind: 'image' })])
-
-    expect(takeComposerAttachments('session-a').map(a => a.id)).toEqual(['file:a'])
-    expect(takeComposerAttachments('session-b').map(a => a.id)).toEqual(['image:b'])
-  })
-
-  it('shares a stable new-session scope with the text draft helpers', () => {
-    stashComposerAttachments(null, [attachment({ id: 'file:new' })])
-
-    expect(takeComposerAttachments(undefined).map(a => a.id)).toEqual(['file:new'])
-  })
-
-  it('returns cloned attachments so callers cannot mutate the stash', () => {
-    stashComposerAttachments('session-a', [attachment({ id: 'file:a', label: 'orig.pdf' })])
-
-    const taken = takeComposerAttachments('session-a')
-    taken[0]!.label = 'mutated.pdf'
-
-    expect(takeComposerAttachments('session-a')[0]?.label).toBe('orig.pdf')
-  })
-
-  it('drops the scope entry when stashing an empty set', () => {
-    stashComposerAttachments('session-a', [attachment({ id: 'file:a' })])
-    stashComposerAttachments('session-a', [])
-
-    expect(takeComposerAttachments('session-a')).toEqual([])
-  })
-
-  it('clears a scope explicitly after an accepted submit', () => {
-    stashComposerAttachments('session-a', [attachment({ id: 'file:a' })])
-    clearStashedComposerAttachments('session-a')
-
-    expect(takeComposerAttachments('session-a')).toEqual([])
+    expect(readPersistedComposerDraft()).toBe('')
   })
 })
diff --git a/apps/desktop/src/store/composer.ts b/apps/desktop/src/store/composer.ts
index ba78ac43e220..35d372521cc7 100644
--- a/apps/desktop/src/store/composer.ts
+++ b/apps/desktop/src/store/composer.ts
@@ -21,14 +21,10 @@ export const $composerDraft = atom('')
 export const $composerAttachments = atom<ComposerAttachment[]>([])
 export const $composerTerminalSelections = atom<Record<string, string>>({})
 
-const COMPOSER_DRAFT_STORAGE_PREFIX = 'hermes:composer-draft:v1:'
-const NEW_SESSION_DRAFT_SCOPE = '__new__'
-
-function storageScope(scope: string | null | undefined): string {
-  const trimmed = scope?.trim()
-
-  return trimmed || NEW_SESSION_DRAFT_SCOPE
-}
+// The composer is a single global surface that sits ABOVE the thread: its
+// contents follow the user across session switches and are never touched by
+// session lifecycle. One storage key makes the draft survive app reloads.
+export const COMPOSER_DRAFT_STORAGE_KEY = 'hermes:composer-draft:v2'
 
 function browserStorage(): Storage | null {
   if (typeof window === 'undefined') {
@@ -42,19 +38,15 @@ function browserStorage(): Storage | null {
   }
 }
 
-export function composerDraftStorageKey(scope: string | null | undefined): string {
-  return `${COMPOSER_DRAFT_STORAGE_PREFIX}${encodeURIComponent(storageScope(scope))}`
-}
-
-export function readPersistedComposerDraft(scope: string | null | undefined): string {
+export function readPersistedComposerDraft(): string {
   try {
-    return browserStorage()?.getItem(composerDraftStorageKey(scope)) ?? ''
+    return browserStorage()?.getItem(COMPOSER_DRAFT_STORAGE_KEY) ?? ''
   } catch {
     return ''
   }
 }
 
-export function writePersistedComposerDraft(scope: string | null | undefined, value: string) {
+export function writePersistedComposerDraft(value: string) {
   try {
     const storage = browserStorage()
 
@@ -62,12 +54,10 @@ export function writePersistedComposerDraft(scope: string | null | undefined, va
       return
     }
 
-    const key = composerDraftStorageKey(scope)
-
     if (value.length === 0) {
-      storage.removeItem(key)
+      storage.removeItem(COMPOSER_DRAFT_STORAGE_KEY)
     } else {
-      storage.setItem(key, value)
+      storage.setItem(COMPOSER_DRAFT_STORAGE_KEY, value)
     }
   } catch {
     // Draft persistence is a safety net only; storage quota/private-mode errors
@@ -75,46 +65,14 @@ export function writePersistedComposerDraft(scope: string | null | undefined, va
   }
 }
 
-export function clearPersistedComposerDraft(scope: string | null | undefined) {
+export function clearPersistedComposerDraft() {
   try {
-    browserStorage()?.removeItem(composerDraftStorageKey(scope))
+    browserStorage()?.removeItem(COMPOSER_DRAFT_STORAGE_KEY)
   } catch {
     // Best-effort only.
   }
 }
 
-// Attachments can't ride along in localStorage the way text does — they carry
-// live blobs, object URLs, and in-flight upload state that don't serialize and
-// are tied to the running app. So we retain them per scope in an in-memory map
-// instead: a session switch restores the chips you'd staged, even though they
-// (unlike text) cannot survive a full app reload.
-const composerAttachmentsByScope = new Map<string, ComposerAttachment[]>()
-
-const cloneComposerAttachments = (attachments: ComposerAttachment[]): ComposerAttachment[] =>
-  attachments.map(attachment => ({ ...attachment }))
-
-export function stashComposerAttachments(scope: string | null | undefined, attachments: ComposerAttachment[]) {
-  const key = storageScope(scope)
-
-  if (attachments.length === 0) {
-    composerAttachmentsByScope.delete(key)
-
-    return
-  }
-
-  composerAttachmentsByScope.set(key, cloneComposerAttachments(attachments))
-}
-
-export function takeComposerAttachments(scope: string | null | undefined): ComposerAttachment[] {
-  const stashed = composerAttachmentsByScope.get(storageScope(scope))
-
-  return stashed ? cloneComposerAttachments(stashed) : []
-}
-
-export function clearStashedComposerAttachments(scope: string | null | undefined) {
-  composerAttachmentsByScope.delete(storageScope(scope))
-}
-
 export function setComposerDraft(value: string) {
   $composerDraft.set(value)
 }

From 292192f7d7263ab429ce57dce754e34c83902de3 Mon Sep 17 00:00:00 2001
From: Brooklyn Nicholson <brooklyn.bb.nicholson@gmail.com>
Date: Wed, 10 Jun 2026 23:47:32 -0500
Subject: [PATCH 22/28] refactor(desktop): tidy composer draft persistence

- DRY the duplicated submit-restore blocks into dispatchSubmit()
- inline localStorage access (drop browserStorage indirection);
  clearPersistedComposerDraft delegates to write('')
- drop stale per-scope-stash comment in use-session-actions
---
 apps/desktop/src/app/chat/composer/index.tsx  | 67 ++++++++-----------
 .../app/session/hooks/use-session-actions.ts  |  6 +-
 apps/desktop/src/store/composer.ts            | 39 +++--------
 3 files changed, 37 insertions(+), 75 deletions(-)

diff --git a/apps/desktop/src/app/chat/composer/index.tsx b/apps/desktop/src/app/chat/composer/index.tsx
index 511713d086f3..ae4f78099cbd 100644
--- a/apps/desktop/src/app/chat/composer/index.tsx
+++ b/apps/desktop/src/app/chat/composer/index.tsx
@@ -137,8 +137,8 @@ interface QueueEditState {
 
 const cloneAttachments = (attachments: ComposerAttachment[]) => attachments.map(a => ({ ...a }))
 
-// How long the composer waits after the last keystroke before persisting the
-// draft to localStorage. Scope-change/unmount flushes bypass the delay.
+// Quiet period after the last keystroke before persisting the draft;
+// unmount/pagehide flushes bypass it.
 const DRAFT_PERSIST_DEBOUNCE_MS = 400
 
 export function ChatBar({
@@ -1109,9 +1109,9 @@ export function ChatBar({
     }
   }
 
-  // The composer deliberately does NOT react to session switches: it sits
-  // above the thread and its contents follow the user. The only restore is a
-  // one-shot on mount so an unsent draft survives an app reload.
+  // The composer sits above the thread and does NOT react to session
+  // switches; the only restore is a one-shot on mount so drafts survive
+  // app reloads.
   useEffect(() => {
     const persisted = readPersistedComposerDraft()
 
@@ -1120,18 +1120,14 @@ export function ChatBar({
     }
   }, []) // eslint-disable-line react-hooks/exhaustive-deps
 
+  // Debounced draft persistence. Skipped for programmatically-loaded text
+  // (history browsing, queued-prompt edits) so recalled text never clobbers
+  // the genuine in-progress draft.
   useEffect(() => {
-    // Don't persist programmatically-loaded text: browsing sent-message
-    // history or editing a queued prompt swaps the composer to recalled text,
-    // and persisting that would clobber the genuine in-progress draft (which
-    // history keeps in its own snapshot and restores on the way back).
     if (isBrowsingHistory(sessionId) || queueEdit) {
       return
     }
 
-    // Debounce the localStorage write: the composer's per-keystroke path was
-    // deliberately slimmed down (see the draftRef sync comment above), so we
-    // don't touch storage on every keypress.
     pendingDraftPersistRef.current = draft
 
     const handle = window.setTimeout(() => {
@@ -1142,10 +1138,10 @@ export function ChatBar({
     return () => window.clearTimeout(handle)
   }, [draft, queueEdit, sessionId])
 
-  // Flush any pending debounced write on unmount or window unload. The
-  // pagehide listener is load-bearing: React does NOT run effect cleanups on
-  // a page reload, so without it a Cmd+R inside the debounce window would
-  // silently drop everything typed in the last 400ms.
+  // Flush any pending debounced write on unmount or unload. The pagehide
+  // listener is load-bearing: React does NOT run effect cleanups on a page
+  // reload, so without it a Cmd+R inside the debounce window drops the
+  // trailing keystrokes.
   useEffect(() => {
     const flushPendingDraftPersist = () => {
       const pending = pendingDraftPersistRef.current
@@ -1380,6 +1376,19 @@ export function ChatBar({
     setQueueEdit(null)
   }, [activeQueueSessionKey, editingQueuedPrompt, queueEdit]) // eslint-disable-line react-hooks/exhaustive-deps
 
+  // Submit, restoring the composer (and its persisted draft) if the gateway
+  // rejects or the submit throws — typed text is never lost to a failed send.
+  const dispatchSubmit = (text: string, attachments?: ComposerAttachment[]) => {
+    const restore = () => {
+      loadIntoComposer(text, attachments ?? [])
+      writePersistedComposerDraft(text)
+    }
+
+    void Promise.resolve(attachments ? onSubmit(text, { attachments }) : onSubmit(text))
+      .then(accepted => void (accepted === false ? restore() : clearPersistedComposerDraft()))
+      .catch(restore)
+  }
+
   const submitDraft = () => {
     // Source the text from the DOM editor, not React state. The AUI composer
     // state (`draft`) and the derived `hasComposerPayload` lag the DOM by a
@@ -1414,20 +1423,9 @@ export function ChatBar({
       // /send directives).  Queuing them would make every slash command wait
       // for the current turn to finish, which is how the TUI never behaves.
       if (!attachments.length && SLASH_COMMAND_RE.test(text.trim())) {
-        const submitted = text
         triggerHaptic('submit')
         clearDraft()
-        void Promise.resolve(onSubmit(submitted)).then(accepted => {
-          if (accepted === false) {
-            loadIntoComposer(submitted, [])
-            writePersistedComposerDraft(submitted)
-          } else {
-            clearPersistedComposerDraft()
-          }
-        }).catch(() => {
-          loadIntoComposer(submitted, [])
-          writePersistedComposerDraft(submitted)
-        })
+        dispatchSubmit(text)
       } else if (payloadPresent) {
         queueCurrentDraft()
       } else {
@@ -1439,23 +1437,12 @@ export function ChatBar({
     } else if (!payloadPresent && queuedPrompts.length > 0) {
       void drainNextQueued()
     } else if (payloadPresent) {
-      const submitted = text
       const submittedAttachments = cloneAttachments(attachments)
       triggerHaptic('submit')
       resetBrowseState(sessionId)
       clearDraft()
       clearComposerAttachments()
-      void Promise.resolve(onSubmit(submitted, { attachments: submittedAttachments })).then(accepted => {
-        if (accepted === false) {
-          loadIntoComposer(submitted, submittedAttachments)
-          writePersistedComposerDraft(submitted)
-        } else {
-          clearPersistedComposerDraft()
-        }
-      }).catch(() => {
-        loadIntoComposer(submitted, submittedAttachments)
-        writePersistedComposerDraft(submitted)
-      })
+      dispatchSubmit(text, submittedAttachments)
     }
 
     focusInput()
diff --git a/apps/desktop/src/app/session/hooks/use-session-actions.ts b/apps/desktop/src/app/session/hooks/use-session-actions.ts
index f049223b1f43..e2e4b28ff3c7 100644
--- a/apps/desktop/src/app/session/hooks/use-session-actions.ts
+++ b/apps/desktop/src/app/session/hooks/use-session-actions.ts
@@ -328,10 +328,8 @@ export function useSessionActions({
       setYoloActive(false)
       setCurrentCwd(workspaceCwdForNewSession())
       setCurrentBranch('')
-      // Composer contents are owned by ChatBar's per-scope draft persistence:
-      // the scope change triggered by the session-id updates above stashes the
-      // departing session's attachments and restores this scope's draft.
-      // Clearing here would wipe the departing stash before it's saved.
+      // Never clear the composer here: it sits above the thread and its
+      // contents (text + attachments) follow the user across session changes.
       setFreshDraftReady(true)
     },
     [activeSessionIdRef, busyRef, navigate, selectedStoredSessionIdRef]
diff --git a/apps/desktop/src/store/composer.ts b/apps/desktop/src/store/composer.ts
index 35d372521cc7..cb79cf540afd 100644
--- a/apps/desktop/src/store/composer.ts
+++ b/apps/desktop/src/store/composer.ts
@@ -26,53 +26,30 @@ export const $composerTerminalSelections = atom<Record<string, string>>({})
 // session lifecycle. One storage key makes the draft survive app reloads.
 export const COMPOSER_DRAFT_STORAGE_KEY = 'hermes:composer-draft:v2'
 
-function browserStorage(): Storage | null {
-  if (typeof window === 'undefined') {
-    return null
-  }
-
-  try {
-    return window.localStorage
-  } catch {
-    return null
-  }
-}
-
 export function readPersistedComposerDraft(): string {
   try {
-    return browserStorage()?.getItem(COMPOSER_DRAFT_STORAGE_KEY) ?? ''
+    return window.localStorage.getItem(COMPOSER_DRAFT_STORAGE_KEY) ?? ''
   } catch {
     return ''
   }
 }
 
+// Empty drafts remove the key. Persistence is a safety net only — storage
+// errors (quota, private mode) must never break typing or submission.
 export function writePersistedComposerDraft(value: string) {
   try {
-    const storage = browserStorage()
-
-    if (!storage) {
-      return
-    }
-
-    if (value.length === 0) {
-      storage.removeItem(COMPOSER_DRAFT_STORAGE_KEY)
+    if (value) {
+      window.localStorage.setItem(COMPOSER_DRAFT_STORAGE_KEY, value)
     } else {
-      storage.setItem(COMPOSER_DRAFT_STORAGE_KEY, value)
+      window.localStorage.removeItem(COMPOSER_DRAFT_STORAGE_KEY)
     }
-  } catch {
-    // Draft persistence is a safety net only; storage quota/private-mode errors
-    // must never break typing or submission.
-  }
-}
-
-export function clearPersistedComposerDraft() {
-  try {
-    browserStorage()?.removeItem(COMPOSER_DRAFT_STORAGE_KEY)
   } catch {
     // Best-effort only.
   }
 }
 
+export const clearPersistedComposerDraft = () => writePersistedComposerDraft('')
+
 export function setComposerDraft(value: string) {
   $composerDraft.set(value)
 }

From d7d281fa37e417895580a16163f591fc08c0464b Mon Sep 17 00:00:00 2001
From: Brooklyn Nicholson <brooklyn.bb.nicholson@gmail.com>
Date: Thu, 11 Jun 2026 00:01:06 -0500
Subject: [PATCH 23/28] feat(desktop): strict per-thread drafts on decoupled
 composer
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Keyed draft stash (Map + localStorage mirror) behind the live composer:
switching threads stashes the departing draft and restores the entering
one; empty threads show an empty box. Session lifecycle never clears
composer state — the scope swap is the only coupling.

Co-authored-by: mollusk <roger@roger.local>
Co-authored-by: Teknium <127238744+teknium1@users.noreply.github.com>
---
 apps/desktop/src/app/chat/composer/index.tsx  | 87 ++++++++++++-------
 .../app/session/hooks/use-session-actions.ts  |  3 +-
 apps/desktop/src/store/composer.test.ts       | 69 +++++++++++----
 apps/desktop/src/store/composer.ts            | 79 +++++++++++++----
 4 files changed, 169 insertions(+), 69 deletions(-)

diff --git a/apps/desktop/src/app/chat/composer/index.tsx b/apps/desktop/src/app/chat/composer/index.tsx
index ae4f78099cbd..c18313a73865 100644
--- a/apps/desktop/src/app/chat/composer/index.tsx
+++ b/apps/desktop/src/app/chat/composer/index.tsx
@@ -27,10 +27,10 @@ import { cn } from '@/lib/utils'
 import {
   $composerAttachments,
   clearComposerAttachments,
-  clearPersistedComposerDraft,
+  clearSessionDraft,
   type ComposerAttachment,
-  readPersistedComposerDraft,
-  writePersistedComposerDraft
+  stashSessionDraft,
+  takeSessionDraft
 } from '@/store/composer'
 import {
   browseBackward,
@@ -182,7 +182,9 @@ export function ChatBar({
   const editorRef = useRef<HTMLDivElement | null>(null)
   const draftRef = useRef(draft)
   const previousBusyRef = useRef(busy)
-  const pendingDraftPersistRef = useRef<string | null>(null)
+  const pendingDraftPersistRef = useRef<{ scope: string | null; text: string } | null>(null)
+  const activeQueueSessionKeyRef = useRef(activeQueueSessionKey)
+  activeQueueSessionKeyRef.current = activeQueueSessionKey
   const drainingQueueRef = useRef(false)
   const urlInputRef = useRef<HTMLInputElement | null>(null)
 
@@ -194,6 +196,8 @@ export function ChatBar({
   const [dragActive, setDragActive] = useState(false)
   const [queueEdit, setQueueEdit] = useState<QueueEditState | null>(null)
   const [focusRequestId, setFocusRequestId] = useState(0)
+  const queueEditRef = useRef(queueEdit)
+  queueEditRef.current = queueEdit
   const dragDepthRef = useRef(0)
   const composingRef = useRef(false) // true during IME composition (CJK input)
   const lastSpokenIdRef = useRef<string | null>(null)
@@ -1109,47 +1113,59 @@ export function ChatBar({
     }
   }
 
-  // The composer sits above the thread and does NOT react to session
-  // switches; the only restore is a one-shot on mount so drafts survive
-  // app reloads.
+  const stashAt = (
+    scope: string | null,
+    text = draftRef.current,
+    attachments = $composerAttachments.get()
+  ) => stashSessionDraft(scope, text, attachments)
+
+  // Per-thread draft swap — the composer's only session coupling. Lifecycle
+  // never clears composer state; this effect alone stashes on leave, restores
+  // on enter. Keyed writes are idempotent, so no skip-sentinel.
   useEffect(() => {
-    const persisted = readPersistedComposerDraft()
+    const { attachments, text } = takeSessionDraft(activeQueueSessionKey)
+    loadIntoComposer(text, attachments)
 
-    if (persisted && !draftRef.current.trim()) {
-      loadIntoComposer(persisted, $composerAttachments.get())
+    return () => {
+      const editing = queueEditRef.current
+
+      if (editing?.sessionKey === activeQueueSessionKey) {
+        stashAt(activeQueueSessionKey, editing.draft, editing.attachments)
+      } else if (!isBrowsingHistory(sessionId)) {
+        stashAt(activeQueueSessionKey)
+      }
     }
-  }, []) // eslint-disable-line react-hooks/exhaustive-deps
+  }, [activeQueueSessionKey]) // eslint-disable-line react-hooks/exhaustive-deps
 
-  // Debounced draft persistence. Skipped for programmatically-loaded text
-  // (history browsing, queued-prompt edits) so recalled text never clobbers
-  // the genuine in-progress draft.
+  // Debounced stash into the active scope. Skipped while browsing history or
+  // editing a queued prompt — recalled text must not clobber the real draft.
   useEffect(() => {
     if (isBrowsingHistory(sessionId) || queueEdit) {
       return
     }
 
-    pendingDraftPersistRef.current = draft
+    pendingDraftPersistRef.current = { scope: activeQueueSessionKey, text: draft }
 
     const handle = window.setTimeout(() => {
       pendingDraftPersistRef.current = null
-      writePersistedComposerDraft(draft)
+      stashAt(activeQueueSessionKey, draft)
     }, DRAFT_PERSIST_DEBOUNCE_MS)
 
     return () => window.clearTimeout(handle)
-  }, [draft, queueEdit, sessionId])
+  }, [activeQueueSessionKey, draft, queueEdit, sessionId])
 
-  // Flush any pending debounced write on unmount or unload. The pagehide
-  // listener is load-bearing: React does NOT run effect cleanups on a page
-  // reload, so without it a Cmd+R inside the debounce window drops the
-  // trailing keystrokes.
+  // pagehide is load-bearing: React skips effect cleanups on reload, so Cmd+R
+  // inside the debounce window would drop trailing keystrokes without this.
   useEffect(() => {
     const flushPendingDraftPersist = () => {
       const pending = pendingDraftPersistRef.current
 
-      if (pending !== null) {
-        pendingDraftPersistRef.current = null
-        writePersistedComposerDraft(pending)
+      if (!pending) {
+        return
       }
+
+      pendingDraftPersistRef.current = null
+      stashAt(pending.scope, pending.text)
     }
 
     window.addEventListener('pagehide', flushPendingDraftPersist)
@@ -1362,30 +1378,35 @@ export function ChatBar({
     }
   }, [busy, drainNextQueued, queuedPrompts.length])
 
-  // Clean up queue edit when its target disappears (session swap or external delete).
+  // Queue-edit cleanup: on session swap the scope effect already stashed the
+  // edit snapshot; only restore into the composer when still on the same scope.
   useEffect(() => {
     if (!queueEdit) {
       return
     }
 
-    if (queueEdit.sessionKey === activeQueueSessionKey && editingQueuedPrompt) {
-      return
+    if (queueEdit.sessionKey === activeQueueSessionKey) {
+      if (editingQueuedPrompt) {
+        return
+      }
+
+      loadIntoComposer(queueEdit.draft, queueEdit.attachments)
     }
 
-    loadIntoComposer(queueEdit.draft, queueEdit.attachments)
     setQueueEdit(null)
   }, [activeQueueSessionKey, editingQueuedPrompt, queueEdit]) // eslint-disable-line react-hooks/exhaustive-deps
 
-  // Submit, restoring the composer (and its persisted draft) if the gateway
-  // rejects or the submit throws — typed text is never lost to a failed send.
   const dispatchSubmit = (text: string, attachments?: ComposerAttachment[]) => {
+    const submittedScope = activeQueueSessionKeyRef.current
+    const submittedAttachments = attachments ?? []
+
     const restore = () => {
-      loadIntoComposer(text, attachments ?? [])
-      writePersistedComposerDraft(text)
+      loadIntoComposer(text, submittedAttachments)
+      stashAt(activeQueueSessionKeyRef.current, text, submittedAttachments)
     }
 
     void Promise.resolve(attachments ? onSubmit(text, { attachments }) : onSubmit(text))
-      .then(accepted => void (accepted === false ? restore() : clearPersistedComposerDraft()))
+      .then(accepted => void (accepted === false ? restore() : clearSessionDraft(submittedScope)))
       .catch(restore)
   }
 
diff --git a/apps/desktop/src/app/session/hooks/use-session-actions.ts b/apps/desktop/src/app/session/hooks/use-session-actions.ts
index e2e4b28ff3c7..5077226aade3 100644
--- a/apps/desktop/src/app/session/hooks/use-session-actions.ts
+++ b/apps/desktop/src/app/session/hooks/use-session-actions.ts
@@ -328,8 +328,7 @@ export function useSessionActions({
       setYoloActive(false)
       setCurrentCwd(workspaceCwdForNewSession())
       setCurrentBranch('')
-      // Never clear the composer here: it sits above the thread and its
-      // contents (text + attachments) follow the user across session changes.
+      // Never clear the composer here — ChatBar's per-thread draft swap owns it.
       setFreshDraftReady(true)
     },
     [activeSessionIdRef, busyRef, navigate, selectedStoredSessionIdRef]
diff --git a/apps/desktop/src/store/composer.test.ts b/apps/desktop/src/store/composer.test.ts
index efa9fcba4db1..08bbb391c950 100644
--- a/apps/desktop/src/store/composer.test.ts
+++ b/apps/desktop/src/store/composer.test.ts
@@ -3,13 +3,13 @@ import { afterEach, describe, expect, it } from 'vitest'
 import {
   $composerAttachments,
   addComposerAttachment,
-  clearPersistedComposerDraft,
-  COMPOSER_DRAFT_STORAGE_KEY,
+  clearSessionDraft,
   type ComposerAttachment,
-  readPersistedComposerDraft,
   removeComposerAttachment,
-  updateComposerAttachment,
-  writePersistedComposerDraft
+  SESSION_DRAFTS_STORAGE_KEY,
+  stashSessionDraft,
+  takeSessionDraft,
+  updateComposerAttachment
 } from './composer'
 
 function attachment(overrides: Partial<ComposerAttachment> & Pick<ComposerAttachment, 'id'>): ComposerAttachment {
@@ -46,30 +46,61 @@ describe('updateComposerAttachment', () => {
   })
 })
 
-describe('persisted composer draft', () => {
+describe('session drafts', () => {
   afterEach(() => {
+    for (const scope of ['session-a', 'session-b', null]) {
+      clearSessionDraft(scope)
+    }
+
     window.localStorage.clear()
   })
 
-  it('stores and restores the draft', () => {
-    writePersistedComposerDraft('almost submitted prompt')
+  it('keeps drafts isolated per session scope', () => {
+    stashSessionDraft('session-a', 'draft a', [])
+    stashSessionDraft('session-b', 'draft b', [attachment({ id: 'image:b', kind: 'image' })])
 
-    expect(readPersistedComposerDraft()).toBe('almost submitted prompt')
-    expect(window.localStorage.getItem(COMPOSER_DRAFT_STORAGE_KEY)).toBe('almost submitted prompt')
+    expect(takeSessionDraft('session-a')).toEqual({ attachments: [], text: 'draft a' })
+    expect(takeSessionDraft('session-b').text).toBe('draft b')
+    expect(takeSessionDraft('session-b').attachments.map(a => a.id)).toEqual(['image:b'])
   })
 
-  it('removes empty drafts instead of leaving stale text behind', () => {
-    writePersistedComposerDraft('saved')
-    writePersistedComposerDraft('')
+  it('scopes the unsaved new-session draft separately from real sessions', () => {
+    stashSessionDraft(null, 'new chat draft', [])
+    stashSessionDraft('session-a', 'session draft', [])
 
-    expect(readPersistedComposerDraft()).toBe('')
-    expect(window.localStorage.getItem(COMPOSER_DRAFT_STORAGE_KEY)).toBeNull()
+    expect(takeSessionDraft(null).text).toBe('new chat draft')
+    expect(takeSessionDraft(undefined).text).toBe('new chat draft')
+    expect(takeSessionDraft('session-a').text).toBe('session draft')
   })
 
-  it('can explicitly clear a saved draft after submit', () => {
-    writePersistedComposerDraft('saved')
-    clearPersistedComposerDraft()
+  it('persists draft text (not attachments) to localStorage', () => {
+    stashSessionDraft('session-a', 'survives reload', [attachment({ id: 'file:a' })])
 
-    expect(readPersistedComposerDraft()).toBe('')
+    const persisted = JSON.parse(window.localStorage.getItem(SESSION_DRAFTS_STORAGE_KEY) ?? '{}') as Record<string, string>
+
+    expect(persisted['session-a']).toBe('survives reload')
+  })
+
+  it('evicts empty drafts instead of leaving stale entries behind', () => {
+    stashSessionDraft('session-a', 'saved', [])
+    stashSessionDraft('session-a', '   ', [])
+
+    expect(takeSessionDraft('session-a')).toEqual({ attachments: [], text: '' })
+  })
+
+  it('clears a stashed draft after an accepted submit', () => {
+    stashSessionDraft('session-a', 'sent prompt', [attachment({ id: 'file:a' })])
+    clearSessionDraft('session-a')
+
+    expect(takeSessionDraft('session-a')).toEqual({ attachments: [], text: '' })
+  })
+
+  it('returns clones so callers cannot mutate the stash', () => {
+    stashSessionDraft('session-a', 'draft', [attachment({ id: 'file:a' })])
+
+    const taken = takeSessionDraft('session-a')
+    taken.attachments[0]!.label = 'mutated'
+
+    expect(takeSessionDraft('session-a').attachments[0]?.label).toBe('doc.pdf')
   })
 })
diff --git a/apps/desktop/src/store/composer.ts b/apps/desktop/src/store/composer.ts
index cb79cf540afd..c40cf867735b 100644
--- a/apps/desktop/src/store/composer.ts
+++ b/apps/desktop/src/store/composer.ts
@@ -21,34 +21,83 @@ export const $composerDraft = atom('')
 export const $composerAttachments = atom<ComposerAttachment[]>([])
 export const $composerTerminalSelections = atom<Record<string, string>>({})
 
-// The composer is a single global surface that sits ABOVE the thread: its
-// contents follow the user across session switches and are never touched by
-// session lifecycle. One storage key makes the draft survive app reloads.
-export const COMPOSER_DRAFT_STORAGE_KEY = 'hermes:composer-draft:v2'
+// Per-thread draft stash for the decoupled composer. Session lifecycle never
+// touches this — only ChatBar's scope swap reads/writes it. Text mirrors to
+// localStorage; attachments are memory-only (blobs, upload state).
+export const SESSION_DRAFTS_STORAGE_KEY = 'hermes:composer-drafts:v3'
 
-export function readPersistedComposerDraft(): string {
+const NEW_SESSION_DRAFT_KEY = '__new__'
+const MAX_PERSISTED_DRAFTS = 50
+const EMPTY_SESSION_DRAFT: SessionDraft = { attachments: [], text: '' }
+
+export interface SessionDraft {
+  attachments: ComposerAttachment[]
+  text: string
+}
+
+const draftKey = (scope: string | null | undefined) => scope?.trim() || NEW_SESSION_DRAFT_KEY
+
+const cloneDraft = (draft: SessionDraft): SessionDraft => ({
+  attachments: draft.attachments.map(attachment => ({ ...attachment })),
+  text: draft.text
+})
+
+function loadPersistedDraftTexts(): [string, SessionDraft][] {
   try {
-    return window.localStorage.getItem(COMPOSER_DRAFT_STORAGE_KEY) ?? ''
+    const raw = window.localStorage.getItem(SESSION_DRAFTS_STORAGE_KEY)
+
+    if (!raw) {
+      return []
+    }
+
+    return Object.entries(JSON.parse(raw) as Record<string, string>).map(([key, text]) => [
+      key,
+      { attachments: [], text }
+    ])
   } catch {
-    return ''
+    return []
   }
 }
 
-// Empty drafts remove the key. Persistence is a safety net only — storage
-// errors (quota, private mode) must never break typing or submission.
-export function writePersistedComposerDraft(value: string) {
+const draftsBySession = new Map<string, SessionDraft>(loadPersistedDraftTexts())
+
+function persistDraftTexts() {
   try {
-    if (value) {
-      window.localStorage.setItem(COMPOSER_DRAFT_STORAGE_KEY, value)
+    const entries = [...draftsBySession]
+      .filter(([, draft]) => draft.text)
+      .slice(-MAX_PERSISTED_DRAFTS)
+      .map(([key, draft]) => [key, draft.text] as const)
+
+    if (entries.length === 0) {
+      window.localStorage.removeItem(SESSION_DRAFTS_STORAGE_KEY)
     } else {
-      window.localStorage.removeItem(COMPOSER_DRAFT_STORAGE_KEY)
+      window.localStorage.setItem(SESSION_DRAFTS_STORAGE_KEY, JSON.stringify(Object.fromEntries(entries)))
     }
   } catch {
-    // Best-effort only.
+    // Best-effort only — quota/private-mode must never break typing.
   }
 }
 
-export const clearPersistedComposerDraft = () => writePersistedComposerDraft('')
+export function stashSessionDraft(scope: string | null | undefined, text: string, attachments: ComposerAttachment[]) {
+  const key = draftKey(scope)
+
+  // Delete-then-set keeps MRU order for MAX_PERSISTED_DRAFTS eviction.
+  draftsBySession.delete(key)
+
+  if (text.trim() || attachments.length > 0) {
+    draftsBySession.set(key, cloneDraft({ attachments, text }))
+  }
+
+  persistDraftTexts()
+}
+
+export function takeSessionDraft(scope: string | null | undefined): SessionDraft {
+  const stashed = draftsBySession.get(draftKey(scope))
+
+  return stashed ? cloneDraft(stashed) : EMPTY_SESSION_DRAFT
+}
+
+export const clearSessionDraft = (scope: string | null | undefined) => stashSessionDraft(scope, '', [])
 
 export function setComposerDraft(value: string) {
   $composerDraft.set(value)

From 975edd414024185809777240cd85e856573f3b6f Mon Sep 17 00:00:00 2001
From: brooklyn! <brooklyn.bb.nicholson@gmail.com>
Date: Thu, 11 Jun 2026 00:01:25 -0500
Subject: [PATCH 24/28] fix(cli): omit --workspace when subpackage has its own
 package-lock.json (#42973) (#43986)

* fix(cli): omit --workspace when subpackage has its own package-lock.json

When ui-tui/ (or web/) contains its own package-lock.json, _workspace_root()
returns the subpackage directory itself.  Passing --workspace ui-tui in that
case fails because npm cannot find a workspace named 'ui-tui' inside ui-tui/.

Fix: skip the --workspace flag when npm_cwd equals the target directory,
running a plain 'npm install' from the standalone project root instead.

Applies the same fix to both _make_tui_argv (TUI) and _build_web_ui (web).

Fixes #42973

* test(cli): fix web workspace-scope fixture + cover own-lockfile fallback (#42973)

The web half of the #42977 fix broke test_npm_install_uses_workspace_web_scope,
which built its fixture with no lockfile anywhere. Without a root lockfile,
_workspace_root(web_dir) already returns web_dir, so the new
"() if npm_cwd == web_dir" branch correctly drops --workspace and the
assertion failed. Model a real workspace checkout instead: the single
package-lock.json lives at the root, so --workspace web scopes the install.

Also add the symmetric web regression test (web/ carrying its own lockfile =>
--workspace must be dropped and the install runs plainly from web_dir via
npm ci), matching the TUI coverage already in test_tui_npm_install.py.

---------

Co-authored-by: liuhao1024 <sunsky.lau@gmail.com>
---
 hermes_cli/main.py                            | 10 ++++-
 ...ds_cron.py => test_cron_parser_builder.py} |  7 ++--
 tests/hermes_cli/test_tui_npm_install.py      | 40 +++++++++++++++++++
 tests/hermes_cli/test_web_ui_build.py         | 35 ++++++++++++++++
 4 files changed, 86 insertions(+), 6 deletions(-)
 rename tests/hermes_cli/{test_subcommands_cron.py => test_cron_parser_builder.py} (94%)

diff --git a/hermes_cli/main.py b/hermes_cli/main.py
index 20728c4f3361..534410559589 100644
--- a/hermes_cli/main.py
+++ b/hermes_cli/main.py
@@ -1623,7 +1623,11 @@ def _make_tui_argv(tui_dir: Path, tui_dev: bool) -> tuple[list[str], Path]:
         npm_cwd = _workspace_root(tui_dir)
         # --workspace ui-tui avoids resolving apps/desktop (Electron + node-pty).
         # See #38772.
-        npm_workspace_args: tuple[str, ...] = ("--workspace", "ui-tui")
+        # When ui-tui/ has its own package-lock.json (e.g. curl install),
+        # _workspace_root() returns tui_dir itself.  Passing --workspace in
+        # that case fails because npm cannot find a workspace named "ui-tui"
+        # inside ui-tui/.  See #42973.
+        npm_workspace_args: tuple[str, ...] = () if npm_cwd == tui_dir else ("--workspace", "ui-tui")
         if termux_startup:
             npm_cwd, npm_workspace_args = _termux_workspace_install_context(
                 tui_dir,
@@ -4642,7 +4646,9 @@ def _build_web_ui(web_dir: Path, *, fatal: bool = False) -> bool:
     # graph (including apps/desktop with its Electron + node-pty deps) is never
     # resolved here.  Without --workspace the root package.json's apps/* glob
     # would pull in desktop on every web build. See #38772.
-    npm_workspace_args: tuple[str, ...] = ("--workspace", "web")
+    # When web/ has its own package-lock.json, _workspace_root() returns
+    # web_dir itself and --workspace would fail.  See #42973.
+    npm_workspace_args: tuple[str, ...] = () if npm_cwd == web_dir else ("--workspace", "web")
     if _is_termux_startup_environment():
         npm_cwd, npm_workspace_args = _termux_workspace_install_context(web_dir)
     r1 = _run_npm_install_deterministic(
diff --git a/tests/hermes_cli/test_subcommands_cron.py b/tests/hermes_cli/test_cron_parser_builder.py
similarity index 94%
rename from tests/hermes_cli/test_subcommands_cron.py
rename to tests/hermes_cli/test_cron_parser_builder.py
index e51a0bb64097..16be898b1a99 100644
--- a/tests/hermes_cli/test_subcommands_cron.py
+++ b/tests/hermes_cli/test_cron_parser_builder.py
@@ -47,20 +47,19 @@ def test_cron_aliases():
 def test_cron_create_options():
     parser = _build()
     ns = parser.parse_args([
-        "cron", "create", "0 9 * * *", "do the thing",
+        "cron", "create", "0 9 * * *", "daily task prompt",
         "--name", "daily", "--deliver", "origin", "--repeat", "3",
         "--skill", "a", "--skill", "b", "--no-agent",
-        "--workdir", "/tmp/x", "--profile", "work",
+        "--workdir", "/tmp/x",
     ])
     assert ns.schedule == "0 9 * * *"
-    assert ns.prompt == "do the thing"
+    assert ns.prompt == "daily task prompt"
     assert ns.name == "daily"
     assert ns.deliver == "origin"
     assert ns.repeat == 3
     assert ns.skills == ["a", "b"]
     assert ns.no_agent is True
     assert ns.workdir == "/tmp/x"
-    assert ns.profile == "work"
 
 
 def test_cron_edit_no_agent_tristate():
diff --git a/tests/hermes_cli/test_tui_npm_install.py b/tests/hermes_cli/test_tui_npm_install.py
index 5d52e4276c41..f9b3cf108fcf 100644
--- a/tests/hermes_cli/test_tui_npm_install.py
+++ b/tests/hermes_cli/test_tui_npm_install.py
@@ -425,3 +425,43 @@ def test_tui_launch_install_uses_workspace_scope(
     install_cmd = npm_calls[0]
     assert "--workspace" in install_cmd
     assert "ui-tui" in install_cmd
+
+def test_make_tui_argv_omits_workspace_when_tui_has_own_lockfile(
+    tmp_path: Path, main_mod, monkeypatch
+) -> None:
+    """When ui-tui/ has its own package-lock.json, _workspace_root returns
+    tui_dir itself.  npm install --workspace ui-tui would fail in that case
+    because npm cannot find a workspace named "ui-tui" inside ui-tui/.
+    The fix omits --workspace and runs plain npm install from tui_dir.
+    See #42973.
+    """
+    tui_dir = tmp_path / "ui-tui"
+    tui_dir.mkdir()
+    (tui_dir / "package.json").write_text("{}")
+    # Simulate curl-install layout: tui_dir has its own lockfile
+    (tui_dir / "package-lock.json").write_text("{}")
+    # Parent also has lockfile (but _workspace_root prefers tui_dir's own)
+    (tmp_path / "package-lock.json").write_text("{}")
+
+    monkeypatch.delenv("TERMUX_VERSION", raising=False)
+    monkeypatch.setenv("PREFIX", "/usr")
+    monkeypatch.setattr(main_mod, "_tui_need_npm_install", lambda _root: True)
+    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)
+
+    main_mod._make_tui_argv(tui_dir, tui_dev=False)
+
+    install_cmd = calls[0][0][0]
+    # Must NOT contain --workspace when npm_cwd == tui_dir
+    assert "--workspace" not in install_cmd, (
+        f"npm install should omit --workspace when tui_dir has its own lockfile, got: {install_cmd}"
+    )
+    assert install_cmd[:2] == ["/bin/npm", "install"]
+    # cwd must be tui_dir (standalone), not parent
+    assert calls[0][1]["cwd"] == str(tui_dir)
diff --git a/tests/hermes_cli/test_web_ui_build.py b/tests/hermes_cli/test_web_ui_build.py
index 0783af22a138..cc20fa61cf38 100644
--- a/tests/hermes_cli/test_web_ui_build.py
+++ b/tests/hermes_cli/test_web_ui_build.py
@@ -142,6 +142,11 @@ class TestBuildWebUISkipsWhenFresh:
 
     def test_npm_install_uses_workspace_web_scope(self, tmp_path):
         web_dir, _ = _make_web_dir(tmp_path)
+        # Real workspace checkout: the single lockfile lives at the root, so
+        # _workspace_root(web_dir) resolves to the parent and --workspace web
+        # scopes the install. (Without a root lockfile, web_dir IS the root and
+        # --workspace would be dropped — see test below and #42973.)
+        (tmp_path / "package-lock.json").write_text("{}", encoding="utf-8")
         mock_cp = __import__("subprocess").CompletedProcess([], 0, stdout="", stderr="")
         build_ok = __import__("subprocess").CompletedProcess([], 0, stdout="", stderr="")
         with patch("hermes_cli.main.shutil.which", return_value="/usr/bin/npm"), \
@@ -153,6 +158,36 @@ class TestBuildWebUISkipsWhenFresh:
         assert "--workspace" in install_cmd
         assert install_cmd[install_cmd.index("--workspace") + 1] == "web"
 
+    def test_web_install_omits_workspace_when_web_has_own_lockfile(
+        self, tmp_path, monkeypatch
+    ):
+        """web/ with its own lockfile => _workspace_root returns web_dir, so
+        --workspace web would fail (npm can't find that workspace from inside
+        web/). The flag must be dropped and the install run plainly from web_dir.
+        Symmetric to the TUI fix in test_tui_npm_install.py. See #42973.
+
+        With web's own lockfile present at cwd, _run_npm_install_deterministic
+        uses ``npm ci`` (not ``npm install``).
+        """
+        web_dir, _ = _make_web_dir(tmp_path)
+        (web_dir / "package-lock.json").write_text("{}", encoding="utf-8")
+        (tmp_path / "package-lock.json").write_text("{}", encoding="utf-8")
+        monkeypatch.delenv("TERMUX_VERSION", raising=False)
+        monkeypatch.setenv("PREFIX", "/usr")
+
+        install_cp = __import__("subprocess").CompletedProcess([], 0, stdout="", stderr="")
+        build_cp = __import__("subprocess").CompletedProcess([], 0, stdout="", stderr="")
+        with patch("hermes_cli.main.shutil.which", return_value="/usr/bin/npm"), \
+             patch("hermes_cli.main.subprocess.run", return_value=install_cp) as mock_run, \
+             patch("hermes_cli.main._run_with_idle_timeout", return_value=build_cp):
+            result = _build_web_ui(web_dir)
+
+        assert result is True
+        args, kwargs = mock_run.call_args
+        assert "--workspace" not in args[0]
+        assert args[0] == ["/usr/bin/npm", "ci", "--silent"]
+        assert kwargs["cwd"] == web_dir
+
     def test_web_build_uses_idle_timeout_helper(self, tmp_path):
         """npm run build now goes through _run_with_idle_timeout (issue #33788).
 

From 13f1efdd15ae583f69c5be986545c026b258607d Mon Sep 17 00:00:00 2001
From: Teknium <127238744+teknium1@users.noreply.github.com>
Date: Wed, 10 Jun 2026 22:30:27 -0700
Subject: [PATCH 25/28] fix(gateway): collapse repeated terminal headers in
 consecutive tool progress blocks (#43968)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

When the agent runs several terminal commands back-to-back, each
progress line repeated the '💻 terminal' header above its fenced code
block, cluttering the progress bubble. Now only the first terminal call
in a streak emits the header; subsequent consecutive terminal calls
render adjacent code blocks. Any other tool (or non-block preview)
resets the streak so the next terminal call gets a fresh header.
---
 gateway/run.py                            | 19 ++++++-
 tests/gateway/test_run_progress_topics.py | 69 +++++++++++++++++++++++
 2 files changed, 86 insertions(+), 2 deletions(-)

diff --git a/gateway/run.py b/gateway/run.py
index 58c68a4b99c5..708106ad8c8b 100644
--- a/gateway/run.py
+++ b/gateway/run.py
@@ -12932,6 +12932,10 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
         last_tool = [None]  # Mutable container for tracking in closure
         last_progress_msg = [None]  # Track last message for dedup
         repeat_count = [0]  # How many times the same message repeated
+        # True when the previously enqueued progress line was a terminal
+        # fenced code block — consecutive terminal calls then drop the
+        # repeated "💻 terminal" header and render back-to-back blocks.
+        last_was_terminal_block = [False]
 
         # ── Discord voice "verbal ack before tool calls" ────────────────
         # When the bot is in a voice channel with the continuous mixer
@@ -13088,7 +13092,13 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
             ):
                 from agent.display import get_tool_preview_max_len
                 _cmd_full = args["command"].rstrip()
-                _code_block_full = f"{emoji} {tool_name}\n```\n{_cmd_full}\n```"
+                # Consecutive terminal calls: drop the repeated
+                # "💻 terminal" header so back-to-back commands render as
+                # adjacent code blocks under a single header.
+                _block_header = (
+                    "" if last_was_terminal_block[0] else f"{emoji} {tool_name}\n"
+                )
+                _code_block_full = f"{_block_header}```\n{_cmd_full}\n```"
                 # Single-line, capped preview for non-verbose modes.
                 _pl = get_tool_preview_max_len()
                 _cap = _pl if _pl > 0 else 40
@@ -13099,13 +13109,15 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
                     _cmd_short = _cmd_short[:_cap - 3] + "..."
                 elif _multiline:
                     _cmd_short = _cmd_short + " ..."
-                _code_block_short = f"{emoji} {tool_name}\n```\n{_cmd_short}\n```"
+                _code_block_short = f"{_block_header}```\n{_cmd_short}\n```"
 
             # Verbose mode: show detailed arguments, respects tool_preview_length
             if progress_mode == "verbose":
                 if _code_block_full is not None:
+                    last_was_terminal_block[0] = True
                     progress_queue.put(_code_block_full)
                     return
+                last_was_terminal_block[0] = False
                 if args:
                     from agent.display import get_tool_preview_max_len
                     _pl = get_tool_preview_max_len()
@@ -13130,6 +13142,7 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
             # fenced block (built above) instead of the truncated preview.
             if _code_block_short is not None:
                 msg = _code_block_short
+                last_was_terminal_block[0] = True
             elif preview:
                 from agent.display import get_tool_preview_max_len
                 _pl = get_tool_preview_max_len()
@@ -13137,8 +13150,10 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
                 if len(preview) > _cap:
                     preview = preview[:_cap - 3] + "..."
                 msg = f"{emoji} {tool_name}: \"{preview}\""
+                last_was_terminal_block[0] = False
             else:
                 msg = f"{emoji} {tool_name}..."
+                last_was_terminal_block[0] = False
             
             # Dedup: collapse consecutive identical progress messages.
             # Common with execute_code where models iterate with the same
diff --git a/tests/gateway/test_run_progress_topics.py b/tests/gateway/test_run_progress_topics.py
index 646ad92976b9..9d20ed5b7932 100644
--- a/tests/gateway/test_run_progress_topics.py
+++ b/tests/gateway/test_run_progress_topics.py
@@ -1488,3 +1488,72 @@ async def test_terminal_progress_no_bash_block_in_verbose_mode(monkeypatch, tmp_
     all_content = " ".join(call["content"] for call in adapter.sent)
     all_content += " ".join(call["content"] for call in adapter.edits)
     assert "```bash" not in all_content
+
+class MultiTerminalCommandAgent:
+    """Emits several consecutive terminal tool.started events, then a
+    different tool, then terminal again — to exercise header collapsing."""
+
+    def __init__(self, **kwargs):
+        self.tool_progress_callback = kwargs.get("tool_progress_callback")
+        self.tools = []
+
+    def run_conversation(self, message, conversation_history=None, task_id=None):
+        cb = self.tool_progress_callback
+        cb("tool.started", "terminal", "echo one", {"command": "echo one"})
+        cb("tool.started", "terminal", "echo two", {"command": "echo two"})
+        cb("tool.started", "terminal", "echo three", {"command": "echo three"})
+        cb("tool.started", "web_search", "query stuff", {"query": "query stuff"})
+        cb("tool.started", "terminal", "echo four", {"command": "echo four"})
+        time.sleep(0.35)
+        return {"final_response": "done", "messages": [], "api_calls": 1}
+
+
+@pytest.mark.asyncio
+async def test_consecutive_terminal_progress_collapses_headers(monkeypatch, tmp_path):
+    """Back-to-back terminal calls render ONE "terminal" header followed by
+    adjacent code blocks; a different tool in between resets the header so the
+    next terminal call gets a fresh one."""
+    monkeypatch.setenv("HERMES_TOOL_PROGRESS_MODE", "all")
+
+    fake_dotenv = types.ModuleType("dotenv")
+    fake_dotenv.load_dotenv = lambda *args, **kwargs: None
+    monkeypatch.setitem(sys.modules, "dotenv", fake_dotenv)
+
+    fake_run_agent = types.ModuleType("run_agent")
+    fake_run_agent.AIAgent = MultiTerminalCommandAgent
+    monkeypatch.setitem(sys.modules, "run_agent", fake_run_agent)
+    import tools.terminal_tool  # noqa: F401 - register terminal emoji
+
+    adapter = CodeBlockProgressAdapter(platform=Platform.TELEGRAM)
+    runner = _make_runner(adapter)
+    gateway_run = importlib.import_module("gateway.run")
+    monkeypatch.setattr(gateway_run, "_hermes_home", tmp_path)
+    monkeypatch.setattr(gateway_run, "_resolve_runtime_agent_kwargs", lambda: {"api_key": "***"})
+
+    source = SessionSource(
+        platform=Platform.TELEGRAM,
+        chat_id="12345",
+        chat_type="dm",
+        thread_id=None,
+    )
+
+    result = await runner._run_agent(
+        message="hello",
+        context_prompt="",
+        history=[],
+        source=source,
+        session_id="sess-terminal-consecutive",
+        session_key="agent:main:telegram:dm:12345",
+    )
+
+    assert result["final_response"] == "done"
+    contents = [call["content"] for call in adapter.sent] + [
+        call["content"] for call in adapter.edits
+    ]
+    final = max(contents, key=len) if contents else ""
+    # All four commands present as code blocks.
+    for cmd in ("echo one", "echo two", "echo three", "echo four"):
+        assert cmd in final
+    # Exactly TWO terminal headers: one for the first run of three calls,
+    # one for the terminal call after web_search broke the streak.
+    assert final.count("terminal\n```") == 2

From fa7f24e8980367c2ca849eb99e1eb2331c7d3699 Mon Sep 17 00:00:00 2001
From: Shannon Sands <shannon.sands.1979@gmail.com>
Date: Thu, 11 Jun 2026 14:54:47 +1000
Subject: [PATCH 26/28] Enable webhooks from dashboard page

---
 hermes_cli/web_server.py                      |  45 ++++-
 .../test_dashboard_admin_endpoints.py         |  90 +++++++++-
 web/src/lib/api.ts                            |  13 ++
 web/src/pages/WebhooksPage.tsx                | 160 ++++++++++++++++--
 4 files changed, 291 insertions(+), 17 deletions(-)

diff --git a/hermes_cli/web_server.py b/hermes_cli/web_server.py
index f7cc695874ad..ef1c15bac934 100644
--- a/hermes_cli/web_server.py
+++ b/hermes_cli/web_server.py
@@ -1707,6 +1707,28 @@ def _spawn_gateway_restart() -> Tuple[subprocess.Popen, bool]:
     return _spawn_hermes_action(["gateway", "restart"], "gateway-restart"), False
 
 
+def _restart_gateway_after_webhook_enable() -> dict[str, Any]:
+    """Best-effort gateway restart after enabling the webhook platform."""
+    try:
+        proc, reused = _spawn_gateway_restart()
+    except Exception as exc:
+        _log.exception("Failed to auto-restart gateway after enabling webhooks")
+        return {
+            "restart_started": False,
+            "restart_error": str(exc),
+        }
+    if reused:
+        _log.info(
+            "Webhook enable: reusing in-flight gateway restart (pid %s)",
+            proc.pid,
+        )
+    return {
+        "restart_started": True,
+        "restart_action": "gateway-restart",
+        "restart_pid": proc.pid,
+    }
+
+
 @app.post("/api/gateway/restart")
 async def restart_gateway():
     """Kick off a ``hermes gateway restart`` in the background."""
@@ -6753,6 +6775,27 @@ async def list_webhooks():
     }
 
 
+@app.post("/api/webhooks/enable")
+async def enable_webhooks():
+    try:
+        _write_platform_enabled("webhook", True)
+    except Exception as exc:
+        _log.exception("Failed to enable webhook platform from dashboard")
+        raise HTTPException(
+            status_code=500,
+            detail="Failed to enable webhook platform.",
+        ) from exc
+
+    restart_result = _restart_gateway_after_webhook_enable()
+    return {
+        "ok": True,
+        "platform": "webhook",
+        "enabled": True,
+        "needs_restart": not restart_result["restart_started"],
+        **restart_result,
+    }
+
+
 @app.post("/api/webhooks")
 async def create_webhook(body: WebhookCreate):
     import re as _re
@@ -6763,7 +6806,7 @@ async def create_webhook(body: WebhookCreate):
     if not wh._is_webhook_enabled():
         raise HTTPException(
             status_code=400,
-            detail="Webhook platform is not enabled. Enable it in messaging settings first.",
+            detail="Webhook platform is not enabled. Enable it from the Webhooks page first.",
         )
 
     name = (body.name or "").strip().lower().replace(" ", "-")
diff --git a/tests/hermes_cli/test_dashboard_admin_endpoints.py b/tests/hermes_cli/test_dashboard_admin_endpoints.py
index 5171f3ade05c..60ee50728a1c 100644
--- a/tests/hermes_cli/test_dashboard_admin_endpoints.py
+++ b/tests/hermes_cli/test_dashboard_admin_endpoints.py
@@ -201,6 +201,91 @@ class TestWebhookEndpoints:
         r = self.client.post("/api/webhooks", json={"name": "gh", "deliver": "log"})
         assert r.status_code == 400
 
+    def test_enable_platform_starts_gateway_restart(self, monkeypatch):
+        import hermes_cli.web_server as ws
+        from hermes_cli.config import load_config
+
+        ws._ACTION_PROCS.pop("gateway-restart", None)
+        restart_calls = []
+
+        class FakeRestartProc:
+            pid = 4242
+
+        def fake_spawn_action(subcommand, name):
+            restart_calls.append((subcommand, name))
+            return FakeRestartProc()
+
+        monkeypatch.setattr(ws, "_spawn_hermes_action", fake_spawn_action)
+
+        r = self.client.post("/api/webhooks/enable")
+
+        assert r.status_code == 200
+        assert r.json() == {
+            "ok": True,
+            "platform": "webhook",
+            "enabled": True,
+            "needs_restart": False,
+            "restart_started": True,
+            "restart_action": "gateway-restart",
+            "restart_pid": 4242,
+        }
+        assert restart_calls == [(["gateway", "restart"], "gateway-restart")]
+        assert load_config()["platforms"]["webhook"]["enabled"] is True
+        assert self.client.get("/api/webhooks").json()["enabled"] is True
+
+    def test_enable_platform_reports_restart_failure_after_save(self, monkeypatch):
+        import hermes_cli.web_server as ws
+        from hermes_cli.config import load_config
+
+        ws._ACTION_PROCS.pop("gateway-restart", None)
+
+        def fail_spawn_action(subcommand, name):
+            assert subcommand == ["gateway", "restart"]
+            assert name == "gateway-restart"
+            raise RuntimeError("supervisor unavailable")
+
+        monkeypatch.setattr(ws, "_spawn_hermes_action", fail_spawn_action)
+
+        r = self.client.post("/api/webhooks/enable")
+
+        assert r.status_code == 200
+        data = r.json()
+        assert data["ok"] is True
+        assert data["platform"] == "webhook"
+        assert data["enabled"] is True
+        assert data["needs_restart"] is True
+        assert data["restart_started"] is False
+        assert "supervisor unavailable" in data["restart_error"]
+        assert load_config()["platforms"]["webhook"]["enabled"] is True
+
+    def test_enable_platform_reuses_inflight_gateway_restart(self, monkeypatch):
+        import hermes_cli.web_server as ws
+        from hermes_cli.config import load_config
+
+        ws._ACTION_PROCS.pop("gateway-restart", None)
+
+        class FakeRunningProc:
+            pid = 5151
+
+            def poll(self):
+                return None
+
+        monkeypatch.setitem(ws._ACTION_PROCS, "gateway-restart", FakeRunningProc())
+
+        def fail_spawn_action(subcommand, name):
+            raise AssertionError("must not spawn a second concurrent restart")
+
+        monkeypatch.setattr(ws, "_spawn_hermes_action", fail_spawn_action)
+
+        r = self.client.post("/api/webhooks/enable")
+
+        assert r.status_code == 200
+        data = r.json()
+        assert data["needs_restart"] is False
+        assert data["restart_started"] is True
+        assert data["restart_pid"] == 5151
+        assert load_config()["platforms"]["webhook"]["enabled"] is True
+
 
 class TestOpsEndpoints:
     @pytest.fixture(autouse=True)
@@ -622,6 +707,10 @@ class TestAdminEndpointsAuthGate:
         resp = self.client.get(path)
         assert resp.status_code in (401, 403)
 
+    def test_webhooks_enable_post_gated(self):
+        resp = self.client.post("/api/webhooks/enable")
+        assert resp.status_code in (401, 403)
+
 
 class TestUpdateCheckEndpoint:
     """``GET /api/hermes/update/check`` reports availability without applying.
@@ -953,4 +1042,3 @@ class TestToolsConfigEndpoints:
                 kwargs["json"] = payload
             r = fn(path, **kwargs)
             assert r.status_code == 401, f"{method} {path} not gated"
-
diff --git a/web/src/lib/api.ts b/web/src/lib/api.ts
index 7cde6eb78f95..a7c308353bb5 100644
--- a/web/src/lib/api.ts
+++ b/web/src/lib/api.ts
@@ -866,6 +866,8 @@ export const api = {
 
   // ── Admin: Webhooks ─────────────────────────────────────────────────
   getWebhooks: () => fetchJSON<WebhooksResponse>("/api/webhooks"),
+  enableWebhooks: () =>
+    fetchJSON<WebhookEnableResponse>("/api/webhooks/enable", { method: "POST" }),
   createWebhook: (body: WebhookCreate) =>
     fetchJSON<WebhookRoute & { secret: string }>("/api/webhooks", {
       method: "POST",
@@ -1288,6 +1290,17 @@ export interface WebhooksResponse {
   subscriptions: WebhookRoute[];
 }
 
+export interface WebhookEnableResponse {
+  ok: boolean;
+  platform: "webhook";
+  enabled: true;
+  needs_restart: boolean;
+  restart_started?: boolean;
+  restart_action?: string;
+  restart_pid?: number | null;
+  restart_error?: string;
+}
+
 export interface WebhookCreate {
   name: string;
   description?: string;
diff --git a/web/src/pages/WebhooksPage.tsx b/web/src/pages/WebhooksPage.tsx
index 13587efd190d..30470f45259a 100644
--- a/web/src/pages/WebhooksPage.tsx
+++ b/web/src/pages/WebhooksPage.tsx
@@ -1,5 +1,14 @@
 import { useCallback, useEffect, useLayoutEffect, useState } from "react";
-import { Webhook, Plus, Trash2, X, Copy, Check } from "lucide-react";
+import {
+  AlertTriangle,
+  Check,
+  Copy,
+  Plus,
+  RotateCw,
+  Trash2,
+  Webhook,
+  X,
+} from "lucide-react";
 import { Badge } from "@nous-research/ui/ui/components/badge";
 import { Button } from "@nous-research/ui/ui/components/button";
 import { Select, SelectOption } from "@nous-research/ui/ui/components/select";
@@ -51,6 +60,11 @@ function CopyButton({ value }: { value: string }) {
 export default function WebhooksPage() {
   const [data, setData] = useState<WebhooksResponse | null>(null);
   const [loading, setLoading] = useState(true);
+  const [enabling, setEnabling] = useState(false);
+  const [restartNeeded, setRestartNeeded] = useState(false);
+  const [restartMessage, setRestartMessage] = useState<string | null>(null);
+  const [restartError, setRestartError] = useState<string | null>(null);
+  const [restarting, setRestarting] = useState(false);
   const { toast, showToast } = useToast();
   const { setEnd } = usePageHeader();
 
@@ -78,7 +92,7 @@ export default function WebhooksPage() {
   const subscriptions = data?.subscriptions ?? [];
 
   const loadWebhooks = useCallback(() => {
-    api
+    return api
       .getWebhooks()
       .then(setData)
       .catch(() => showToast("Failed to load webhooks", "error"))
@@ -89,6 +103,78 @@ export default function WebhooksPage() {
     loadWebhooks();
   }, [loadWebhooks]);
 
+  const watchRestartOutcome = useCallback(async () => {
+    for (let i = 0; i < 20; i++) {
+      await new Promise((resolve) => setTimeout(resolve, 1500));
+      try {
+        const st = await api.getActionStatus("gateway-restart", 5);
+        if (st.running) continue;
+        if (st.exit_code !== 0 && st.exit_code !== null) {
+          setRestartMessage(null);
+          setRestartNeeded(true);
+          setRestartError(`Gateway restart failed with exit ${st.exit_code}.`);
+          showToast(
+            `Gateway restart failed (exit ${st.exit_code}) — restart manually`,
+            "error",
+          );
+        } else {
+          setRestartMessage(null);
+          setRestartNeeded(false);
+          setRestartError(null);
+        }
+        return;
+      } catch {
+        // The dashboard may briefly lose its connection while the gateway restarts.
+      }
+    }
+    setRestartMessage(null);
+  }, [showToast]);
+
+  const handleRestart = useCallback(async () => {
+    setRestarting(true);
+    try {
+      await api.restartGateway();
+      setRestartNeeded(false);
+      setRestartError(null);
+      setRestartMessage("Gateway restarting…");
+      showToast("Gateway restarting…", "success");
+      setTimeout(() => void loadWebhooks(), 4000);
+      void watchRestartOutcome();
+    } catch (e) {
+      setRestartNeeded(true);
+      setRestartError(String(e));
+      showToast(`Failed to restart: ${e}`, "error");
+    } finally {
+      setRestarting(false);
+    }
+  }, [loadWebhooks, showToast, watchRestartOutcome]);
+
+  const handleEnableWebhooks = useCallback(async () => {
+    setEnabling(true);
+    setRestartNeeded(false);
+    setRestartError(null);
+    try {
+      const result = await api.enableWebhooks();
+      await loadWebhooks();
+      if (result.restart_started) {
+        setRestartMessage("Webhooks enabled; gateway restarting…");
+        showToast("Webhooks enabled; gateway restarting…", "success");
+        setTimeout(() => void loadWebhooks(), 4000);
+        void watchRestartOutcome();
+      } else {
+        const detail = result.restart_error ? `: ${result.restart_error}` : ".";
+        setRestartMessage(null);
+        setRestartNeeded(true);
+        setRestartError(`Gateway restart failed${detail}`);
+        showToast(`Webhooks enabled; gateway restart failed${detail}`, "error");
+      }
+    } catch (e) {
+      showToast(`Failed to enable webhooks: ${e}`, "error");
+    } finally {
+      setEnabling(false);
+    }
+  }, [loadWebhooks, showToast, watchRestartOutcome]);
+
   const resetForm = useCallback(() => {
     setName("");
     setDescription("");
@@ -171,7 +257,7 @@ export default function WebhooksPage() {
       <Button
         className="uppercase"
         size="sm"
-        disabled={!enabled}
+        disabled={!enabled || enabling}
         prefix={<Plus />}
         onClick={() => {
           setCreated(null);
@@ -184,7 +270,7 @@ export default function WebhooksPage() {
     return () => {
       setEnd(null);
     };
-  }, [setEnd, enabled, loading]);
+  }, [setEnd, enabled, enabling, loading]);
 
   if (loading) {
     return (
@@ -375,17 +461,61 @@ export default function WebhooksPage() {
       )}
 
       {!enabled && (
-        <Card>
-          <CardContent className="py-6 flex items-start gap-3 text-sm">
-            <Webhook className="h-5 w-5 shrink-0 text-warning" />
-            <div className="flex flex-col gap-1">
-              <span className="font-medium">Webhook platform disabled</span>
-              <span className="text-muted-foreground">
-                The webhook platform must be enabled on the Channels page before
-                you can create subscriptions. Enable it there, then return to
-                this page.
+        <Card className="border-warning/50">
+          <CardContent className="flex flex-col gap-4 py-6 text-sm sm:flex-row sm:items-center sm:justify-between">
+            <div className="flex items-start gap-3">
+              <Webhook className="h-5 w-5 shrink-0 text-warning" />
+              <div className="flex flex-col gap-1">
+                <span className="font-medium">Webhook receiver disabled</span>
+                <span className="text-muted-foreground">
+                  Webhooks are their own gateway platform. Enable them here to
+                  accept incoming HTTP events; chat channels are only needed
+                  when a subscription delivers to Telegram, Discord, Slack, or
+                  another channel.
+                </span>
+              </div>
+            </div>
+            <Button
+              size="sm"
+              className="uppercase shrink-0"
+              onClick={handleEnableWebhooks}
+              disabled={enabling}
+              prefix={enabling ? <Spinner /> : <Webhook className="h-4 w-4" />}
+            >
+              {enabling ? "Enabling…" : "Enable webhooks"}
+            </Button>
+          </CardContent>
+        </Card>
+      )}
+
+      {restartMessage && !restartNeeded && (
+        <Card className="border-border">
+          <CardContent className="flex items-center gap-2 p-4 text-sm text-muted-foreground">
+            <RotateCw className="h-4 w-4 shrink-0 text-warning" />
+            <span>{restartMessage}</span>
+          </CardContent>
+        </Card>
+      )}
+
+      {restartNeeded && (
+        <Card className="border-warning/50">
+          <CardContent className="flex flex-col gap-3 p-4 sm:flex-row sm:items-center sm:justify-between">
+            <div className="flex items-start gap-2 text-sm">
+              <AlertTriangle className="mt-0.5 h-4 w-4 shrink-0 text-warning" />
+              <span>
+                {restartError ??
+                  "Webhooks are enabled, but the gateway still needs a restart before the receiver can come online."}
               </span>
             </div>
+            <Button
+              size="sm"
+              className="uppercase shrink-0"
+              onClick={handleRestart}
+              disabled={restarting}
+              prefix={restarting ? <Spinner /> : <RotateCw className="h-4 w-4" />}
+            >
+              {restarting ? "Restarting…" : "Restart gateway"}
+            </Button>
           </CardContent>
         </Card>
       )}
@@ -400,8 +530,8 @@ export default function WebhooksPage() {
         </H2>
 
         <p className="text-xs text-muted-foreground -mt-1">
-          Disabled webhooks reject incoming events; the gateway hot-reloads
-          changes (no restart needed).
+          Subscription changes hot-reload once the webhook receiver is running.
+          Disabled subscriptions reject incoming events.
         </p>
 
         {subscriptions.length === 0 && (

From 264ac72b676b634c0f63b26af53c90205121bffd Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E9=BC=AC=E5=90=9B=E5=A4=8F=E7=BA=AA?= <470766206@qq.com>
Date: Sun, 7 Jun 2026 20:49:36 +0800
Subject: [PATCH 27/28] fix(gateway,windows): preserve restart watcher env

---
 gateway/run.py                      | 72 +++++++++++++++++++++++++++++
 tests/gateway/test_restart_drain.py | 64 +++++++++++++++++++++++++
 2 files changed, 136 insertions(+)

diff --git a/gateway/run.py b/gateway/run.py
index 708106ad8c8b..ff82fe435825 100644
--- a/gateway/run.py
+++ b/gateway/run.py
@@ -32,6 +32,7 @@ import logging
 import os
 import re
 import shlex
+import site
 import sys
 import signal
 import tempfile
@@ -135,6 +136,60 @@ _GATEWAY_SECRET_PATTERNS = (
 )
 
 
+def _ensure_windows_gateway_venv_imports() -> None:
+    """Make detached Windows gateway runs see the Hermes venv packages.
+
+    Some Windows restart paths run the gateway under uv's base ``pythonw.exe``
+    to avoid the venv launcher respawning a visible console interpreter.  That
+    mode can import the source tree via cwd/PYTHONPATH but still miss optional
+    packages installed only in ``venv/Lib/site-packages`` (notably the MCP SDK).
+    Patch the live process before MCP discovery so tool injection does not
+    depend on every launcher preserving PYTHONPATH perfectly.
+    """
+    if sys.platform != "win32":
+        return
+
+    project_root = Path(__file__).resolve().parent.parent
+    candidates: list[Path] = []
+    if os.environ.get("VIRTUAL_ENV"):
+        candidates.append(Path(os.environ["VIRTUAL_ENV"]))
+    candidates.append(project_root / "venv")
+
+    seen: set[str] = set()
+    for venv_dir in candidates:
+        try:
+            resolved_venv = venv_dir.resolve()
+        except OSError:
+            resolved_venv = venv_dir
+        venv_key = str(resolved_venv).lower()
+        if venv_key in seen:
+            continue
+        seen.add(venv_key)
+
+        site_packages = resolved_venv / "Lib" / "site-packages"
+        if not site_packages.exists():
+            continue
+
+        project_entry = str(project_root)
+        site_entry = str(site_packages)
+        if project_entry not in sys.path:
+            sys.path.insert(0, project_entry)
+        # addsitepackages() semantics matter here: pywin32, used by the MCP
+        # SDK on Windows, relies on .pth processing to expose pywintypes.
+        site.addsitedir(site_entry)
+        if site_entry in sys.path:
+            sys.path.remove(site_entry)
+        insert_at = 1 if sys.path and sys.path[0] == project_entry else 0
+        sys.path.insert(insert_at, site_entry)
+
+        os.environ["VIRTUAL_ENV"] = str(resolved_venv)
+        pythonpath = [project_entry, site_entry]
+        if os.environ.get("PYTHONPATH"):
+            pythonpath.append(os.environ["PYTHONPATH"])
+        os.environ["PYTHONPATH"] = os.pathsep.join(dict.fromkeys(pythonpath))
+        return
+
+
 def _gateway_platform_value(platform: Any) -> str:
     """Return a normalized gateway platform value for enums or raw strings."""
     return str(getattr(platform, "value", platform) or "").strip().lower()
@@ -4255,10 +4310,25 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
                 )
                 """
             ).strip()
+            watcher_env = os.environ.copy()
+            # This watcher is intentionally outside the running gateway. If it
+            # inherits the gateway marker, `hermes gateway restart` refuses to
+            # run as a self-restart loop guard and the gateway stays stopped.
+            watcher_env.pop("_HERMES_GATEWAY", None)
+            project_root = Path(__file__).resolve().parent.parent
+            venv_dir = Path(watcher_env.get("VIRTUAL_ENV") or project_root / "venv")
+            site_packages = venv_dir / "Lib" / "site-packages"
+            if site_packages.exists():
+                watcher_env["VIRTUAL_ENV"] = str(venv_dir)
+                pythonpath = [str(project_root), str(site_packages)]
+                if watcher_env.get("PYTHONPATH"):
+                    pythonpath.append(watcher_env["PYTHONPATH"])
+                watcher_env["PYTHONPATH"] = os.pathsep.join(dict.fromkeys(pythonpath))
             subprocess.Popen(
                 [sys.executable, "-c", watcher, str(current_pid), *cmd_argv],
                 stdout=subprocess.DEVNULL,
                 stderr=subprocess.DEVNULL,
+                env=watcher_env,
                 **windows_detach_popen_kwargs(),
             )
             return
@@ -15910,6 +15980,8 @@ async def start_gateway(config: Optional[GatewayConfig] = None, replace: bool =
     atexit.register(remove_pid_file)
     atexit.register(release_gateway_runtime_lock)
 
+    _ensure_windows_gateway_venv_imports()
+
     # MCP tool discovery — run in an executor so the asyncio event loop
     # stays responsive even when a configured MCP server is slow or
     # unreachable.  discover_mcp_tools() uses a blocking 120s wait
diff --git a/tests/gateway/test_restart_drain.py b/tests/gateway/test_restart_drain.py
index a48e5f737810..32710fdb8979 100644
--- a/tests/gateway/test_restart_drain.py
+++ b/tests/gateway/test_restart_drain.py
@@ -197,6 +197,7 @@ async def test_launch_detached_restart_command_uses_setsid(monkeypatch):
     runner, _adapter = make_restart_runner()
     popen_calls = []
 
+    monkeypatch.setattr(gateway_run.sys, "platform", "linux")
     monkeypatch.setattr(gateway_run, "_resolve_hermes_bin", lambda: ["/usr/bin/hermes"])
     monkeypatch.setattr(gateway_run.os, "getpid", lambda: 321)
     monkeypatch.setattr(shutil, "which", lambda cmd: "/usr/bin/setsid" if cmd == "setsid" else None)
@@ -219,6 +220,69 @@ async def test_launch_detached_restart_command_uses_setsid(monkeypatch):
     assert kwargs["stderr"] is subprocess.DEVNULL
 
 
+def test_windows_gateway_venv_imports_add_site_packages(monkeypatch, tmp_path):
+    venv_dir = tmp_path / "venv"
+    site_packages = venv_dir / "Lib" / "site-packages"
+    pth_extra = tmp_path / "pywin32_system32"
+    site_packages.mkdir(parents=True)
+    pth_extra.mkdir()
+    (site_packages / "pywin32.pth").write_text(str(pth_extra), encoding="utf-8")
+    project_root = str(gateway_run.Path(gateway_run.__file__).resolve().parent.parent)
+
+    monkeypatch.setattr(gateway_run.sys, "platform", "win32")
+    monkeypatch.setattr(gateway_run.sys, "path", ["existing"])
+    monkeypatch.setenv("VIRTUAL_ENV", str(venv_dir))
+    monkeypatch.setenv("PYTHONPATH", "already-there")
+
+    gateway_run._ensure_windows_gateway_venv_imports()
+
+    assert gateway_run.sys.path[:2] == [project_root, str(site_packages)]
+    assert str(pth_extra) in gateway_run.sys.path
+    assert gateway_run.os.environ["VIRTUAL_ENV"] == str(venv_dir.resolve())
+    pythonpath = gateway_run.os.environ["PYTHONPATH"].split(gateway_run.os.pathsep)
+    assert pythonpath[:3] == [project_root, str(site_packages), "already-there"]
+
+
+@pytest.mark.asyncio
+async def test_windows_detached_restart_scrubs_gateway_marker(monkeypatch, tmp_path):
+    runner, _adapter = make_restart_runner()
+    popen_calls = []
+    venv_dir = tmp_path / "venv"
+    site_packages = venv_dir / "Lib" / "site-packages"
+    site_packages.mkdir(parents=True)
+
+    monkeypatch.setattr(gateway_run.sys, "platform", "win32")
+    monkeypatch.setattr(gateway_run, "_resolve_hermes_bin", lambda: ["hermes"])
+    monkeypatch.setattr(gateway_run.os, "getpid", lambda: 321)
+    monkeypatch.setenv("_HERMES_GATEWAY", "1")
+    monkeypatch.setenv("VIRTUAL_ENV", str(venv_dir))
+
+    import hermes_cli._subprocess_compat as subprocess_compat
+
+    monkeypatch.setattr(
+        subprocess_compat,
+        "windows_detach_popen_kwargs",
+        lambda: {},
+    )
+
+    def fake_popen(cmd, **kwargs):
+        popen_calls.append((cmd, kwargs))
+        return MagicMock()
+
+    monkeypatch.setattr(subprocess, "Popen", fake_popen)
+
+    await runner._launch_detached_restart_command()
+
+    assert len(popen_calls) == 1
+    cmd, kwargs = popen_calls[0]
+    assert cmd[-3:] == ["hermes", "gateway", "restart"]
+    assert kwargs["env"].get("_HERMES_GATEWAY") is None
+    assert kwargs["env"]["VIRTUAL_ENV"] == str(venv_dir)
+    assert str(site_packages) in kwargs["env"]["PYTHONPATH"].split(gateway_run.os.pathsep)
+    assert kwargs["stdout"] is subprocess.DEVNULL
+    assert kwargs["stderr"] is subprocess.DEVNULL
+
+
 # ── Shutdown notification tests ──────────────────────────────────────
 
 

From cb2c13055ed9c3f467be61dbef1f3a7a5dcdc5f6 Mon Sep 17 00:00:00 2001
From: teknium1 <127238744+teknium1@users.noreply.github.com>
Date: Wed, 10 Jun 2026 20:54:32 -0700
Subject: [PATCH 28/28] fix(gateway): scrub _HERMES_GATEWAY from POSIX detached
 restart watcher too

Follow-up to the salvaged #41264 (Windows watcher): the setsid/bash detached
restart watcher on Linux/macOS inherits _HERMES_GATEWAY=1 the same way, so
the CLI's self-restart loop guard silently refuses 'hermes gateway restart'
and the gateway never comes back. Scrub the marker from the watcher env on
the POSIX branch as well, and extend the setsid test to assert it.
---
 gateway/run.py                      | 9 +++++++++
 scripts/release.py                  | 1 +
 tests/gateway/test_restart_drain.py | 4 ++++
 3 files changed, 14 insertions(+)

diff --git a/gateway/run.py b/gateway/run.py
index ff82fe435825..897cb85f6523 100644
--- a/gateway/run.py
+++ b/gateway/run.py
@@ -4338,12 +4338,20 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
             f"while kill -0 {current_pid} 2>/dev/null; do sleep 0.2; done; "
             f"{cmd} gateway restart"
         )
+        # Same marker scrub as the Windows watcher above: this watcher runs
+        # `hermes gateway restart` from outside the gateway, but it inherits
+        # _HERMES_GATEWAY=1 from us, and the CLI's self-restart loop guard
+        # refuses to run when that marker is set — silently (DEVNULL), so the
+        # gateway stops and never comes back.
+        watcher_env = os.environ.copy()
+        watcher_env.pop("_HERMES_GATEWAY", None)
         setsid_bin = shutil.which("setsid")
         if setsid_bin:
             subprocess.Popen(
                 [setsid_bin, "bash", "-lc", shell_cmd],
                 stdout=subprocess.DEVNULL,
                 stderr=subprocess.DEVNULL,
+                env=watcher_env,
                 start_new_session=True,
             )
         else:
@@ -4351,6 +4359,7 @@ class GatewayRunner(GatewayAuthorizationMixin, GatewayKanbanWatchersMixin, Gatew
                 ["bash", "-lc", shell_cmd],
                 stdout=subprocess.DEVNULL,
                 stderr=subprocess.DEVNULL,
+                env=watcher_env,
                 start_new_session=True,
             )
 
diff --git a/scripts/release.py b/scripts/release.py
index 16b8bd7cdb84..ff4f4bc6da7a 100755
--- a/scripts/release.py
+++ b/scripts/release.py
@@ -75,6 +75,7 @@ AUTHOR_MAP = {
     "129007007+HeLLGURD@users.noreply.github.com": "HeLLGURD",
     "290859878+synapsesx@users.noreply.github.com": "synapsesx",
     "dirtyren@users.noreply.github.com": "dirtyren",
+    "470766206@qq.com": "youjunxiaji",
     "mharris@parallel.ai": "NormallyGaussian",
     "roger@roger.local": "mollusk",
     "ted.malone@outlook.com": "temalo",
diff --git a/tests/gateway/test_restart_drain.py b/tests/gateway/test_restart_drain.py
index 32710fdb8979..15b948a4f79f 100644
--- a/tests/gateway/test_restart_drain.py
+++ b/tests/gateway/test_restart_drain.py
@@ -200,6 +200,7 @@ async def test_launch_detached_restart_command_uses_setsid(monkeypatch):
     monkeypatch.setattr(gateway_run.sys, "platform", "linux")
     monkeypatch.setattr(gateway_run, "_resolve_hermes_bin", lambda: ["/usr/bin/hermes"])
     monkeypatch.setattr(gateway_run.os, "getpid", lambda: 321)
+    monkeypatch.setenv("_HERMES_GATEWAY", "1")
     monkeypatch.setattr(shutil, "which", lambda cmd: "/usr/bin/setsid" if cmd == "setsid" else None)
 
     def fake_popen(cmd, **kwargs):
@@ -218,6 +219,9 @@ async def test_launch_detached_restart_command_uses_setsid(monkeypatch):
     assert kwargs["start_new_session"] is True
     assert kwargs["stdout"] is subprocess.DEVNULL
     assert kwargs["stderr"] is subprocess.DEVNULL
+    # The watcher must NOT inherit the gateway marker, or the CLI's
+    # self-restart loop guard refuses to run `hermes gateway restart`.
+    assert kwargs["env"].get("_HERMES_GATEWAY") is None
 
 
 def test_windows_gateway_venv_imports_add_site_packages(monkeypatch, tmp_path):