revert(gateway): remove stale-code self-check and auto-restart

Removes the _detect_stale_code / _trigger_stale_code_restart mechanism
introduced in #17648 and iterated in #19740. On every incoming message
the gateway compared the boot-time git HEAD SHA to the current SHA on
disk, and if they differed it would reply with

    Gateway code was updated in the background --
    restarting this gateway so your next message runs
    on the new code. Please retry in a moment.

and then kick off a graceful restart. This is unwanted behaviour:
users who run a long-lived gateway and do their own ad-hoc git
operations on the checkout end up with their chat interrupted and
the current message dropped every time HEAD moves, with no way to
opt out.

If an operator really needs the old protection against stale
sys.modules after "hermes update", the SIGKILL-survivor sweep in
hermes update (hermes_cli/main.py, also tagged #17648) already
handles the supervisor-respawn case on its own.

Removed:
  gateway/run.py:
    - _STALE_CODE_SENTINELS, _GIT_SHA_CACHE_TTL_SECS
    - _read_git_head_sha(), _compute_repo_mtime() module helpers
    - class-level _boot_wall_time / _boot_repo_mtime / _boot_git_sha /
      _stale_code_restart_triggered defaults
    - __init__ boot-snapshot block (_boot_*, _cached_current_sha*,
      _repo_root_for_staleness, _stale_code_notified)
    - _current_git_sha_cached(), _detect_stale_code(),
      _trigger_stale_code_restart() methods
    - stale-code check + user-facing restart notice at the top of
      _handle_message()
  tests/gateway/test_stale_code_self_check.py (deleted, 412 lines)

No new logic added. Zero remaining references to any removed
symbol. Gateway test suite passes the same 4589 tests it passed
before; the 3 pre-existing unrelated failures (discord free-channel,
feishu bot admission, teams typing) are unchanged by this commit.

.dockerignore

@@ -25,3 +25,7 @@ ui-tui/packages/hermes-ink/dist/
 
 # Runtime data (bind-mounted at /opt/data; must not leak into build context)
 data/
+
+# Compose/profile runtime state (bind-mounted; avoid ownership/secret issues)
+hermes-config/
+runtime/

.github/dependabot.yml

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

.github/workflows/osv-scanner.yml

@@ -0,0 +1,67 @@
+name: OSV-Scanner
+
+# Scans lockfiles (uv.lock, package-lock.json) against the OSV vulnerability
+# database. Runs on every PR that touches a lockfile and on a weekly schedule
+# against main.
+#
+# This is detection-only — OSV-Scanner does NOT open PRs or modify pins.
+# It reports known CVEs in currently-pinned dependency versions so we can
+# decide when and how to patch on our own schedule. Our pinning strategy
+# (full SHA / exact version) is preserved; only the notification signal
+# is added.
+#
+# Complements the existing supply-chain-audit.yml workflow (which scans
+# for malicious code patterns in PR diffs) by covering the orthogonal
+# "currently-pinned dep became known-vulnerable" case.
+#
+# Uses Google's officially-recommended reusable workflow, pinned by SHA.
+# Findings land in the repo's Security tab (Code Scanning > OSV-Scanner).
+# fail-on-vuln is disabled so the job does not block merges on pre-existing
+# vulnerabilities in pinned deps that we may need to patch deliberately.
+
+on:
+  pull_request:
+    branches: [main]
+    paths:
+      - 'uv.lock'
+      - 'pyproject.toml'
+      - 'package.json'
+      - 'package-lock.json'
+      - 'ui-tui/package.json'
+      - 'ui-tui/package-lock.json'
+      - 'website/package.json'
+      - 'website/package-lock.json'
+      - '.github/workflows/osv-scanner.yml'
+  push:
+    branches: [main]
+    paths:
+      - 'uv.lock'
+      - 'pyproject.toml'
+      - 'package.json'
+      - 'package-lock.json'
+      - 'ui-tui/package-lock.json'
+      - 'website/package-lock.json'
+  schedule:
+    # Weekly scan against main — catches CVEs published after merge for
+    # deps that haven't changed since.
+    - cron: '0 9 * * 1'
+  workflow_dispatch:
+
+permissions:
+  # Required by the reusable workflow to upload SARIF to the Security tab.
+  actions: read
+  contents: read
+  security-events: write
+
+jobs:
+  scan:
+    name: Scan lockfiles
+    uses: google/osv-scanner-action/.github/workflows/osv-scanner-reusable.yml@c51854704019a247608d928f370c98740469d4b5  # v2.3.5
+    with:
+      # Scan explicit lockfiles rather than recursing, so we only look at
+      # the three sources of truth and skip vendored / test / worktree dirs.
+      scan-args: |-
+        --lockfile=uv.lock
+        --lockfile=ui-tui/package-lock.json
+        --lockfile=website/package-lock.json
+      fail-on-vuln: false

AGENTS.md

@@ -257,7 +257,16 @@ The dashboard embeds the real `hermes --tui` — **not** a rewrite.  See `hermes
 
 ## Adding New Tools
 
-Requires changes in **2 files**:
+For most custom or local-only tools, do **not** edit Hermes core. Use the plugin
+route instead: create `~/.hermes/plugins/<name>/plugin.yaml` and
+`~/.hermes/plugins/<name>/__init__.py`, then register tools with
+`ctx.register_tool(...)`. Plugin toolsets are discovered automatically and can be
+enabled or disabled without touching `tools/` or `toolsets.py`.
+
+Use the built-in route below only when the user is explicitly contributing a new
+core Hermes tool that should ship in the base system.
+
+Built-in/core tools require changes in **2 files**:
 
 **1. Create `tools/your_tool.py`:**
 ```python

agent/anthropic_adapter.py

@@ -76,6 +76,7 @@ _ADAPTIVE_THINKING_SUBSTRINGS = ("4-6", "4.6", "4-7", "4.7")
 # Models where temperature/top_p/top_k return 400 if set to non-default values.
 # This is the Opus 4.7 contract; future 4.x+ models are expected to follow it.
 _NO_SAMPLING_PARAMS_SUBSTRINGS = ("4-7", "4.7")
+_FAST_MODE_SUPPORTED_SUBSTRINGS = ("opus-4-6", "opus-4.6")
 
 # ── Max output token limits per Anthropic model ───────────────────────
 # Source: Anthropic docs + Cline model catalog.  Anthropic's API requires
@@ -105,6 +106,9 @@ _ANTHROPIC_OUTPUT_LIMITS = {
     "claude-3-haiku":      4_096,
     # Third-party Anthropic-compatible providers
     "minimax":            131_072,
+    # Qwen models via DashScope Anthropic-compatible endpoint
+    # DashScope enforces max_tokens ∈ [1, 65536]
+    "qwen3":               65_536,
 }
 
 # For any model not in the table, assume the highest current limit.
@@ -216,6 +220,17 @@ def _forbids_sampling_params(model: str) -> bool:
     return any(v in model for v in _NO_SAMPLING_PARAMS_SUBSTRINGS)
 
 
+def _supports_fast_mode(model: str) -> bool:
+    """Return True for models that support Anthropic Fast Mode (speed=fast).
+
+    Per Anthropic docs, fast mode is currently supported on Opus 4.6 only.
+    Sending ``speed: "fast"`` to any other Claude model (including Opus 4.7)
+    returns HTTP 400. This guard prevents silently 400'ing when stale config
+    or older callers leave fast mode enabled across a model upgrade.
+    """
+    return any(v in model for v in _FAST_MODE_SUPPORTED_SUBSTRINGS)
+
+
 # Beta headers for enhanced features (sent with ALL auth types).
 # As of Opus 4.7 (2026-04-16), the first two are GA on Claude 4.6+ — the
 # beta headers are still accepted (harmless no-op) but not required. Kept
@@ -1222,6 +1237,14 @@ def _normalize_tool_input_schema(schema: Any) -> Dict[str, Any]:
     ``keep_nullable_hint=False`` because the Anthropic validator does not
     recognize the OpenAPI-style ``nullable: true`` extension and strict
     schema-to-grammar converters may reject unknown keywords.
+
+    Top-level ``oneOf``/``allOf``/``anyOf`` are also stripped here: the
+    Anthropic API rejects union keywords at the schema root with a generic
+    HTTP 400. Several upstream and plugin tools ship schemas with one of
+    these keywords at the top level (commonly for Pydantic discriminated
+    unions). If we land here with those keywords still present after
+    nullable-union stripping, drop them and fall back to a plain object
+    schema so the tool still validates at the Anthropic boundary.
     """
     if not schema:
         return {"type": "object", "properties": {}}
@@ -1231,6 +1254,12 @@ def _normalize_tool_input_schema(schema: Any) -> Dict[str, Any]:
     normalized = strip_nullable_unions(schema, keep_nullable_hint=False)
     if not isinstance(normalized, dict):
         return {"type": "object", "properties": {}}
+    # Strip top-level union keywords that Anthropic's validator rejects.
+    banned = {"oneOf", "allOf", "anyOf"}
+    if banned & normalized.keys():
+        normalized = {k: v for k, v in normalized.items() if k not in banned}
+        if "type" not in normalized:
+            normalized["type"] = "object"
     if normalized.get("type") == "object" and not isinstance(normalized.get("properties"), dict):
         normalized = {**normalized, "properties": {}}
     return normalized
@@ -1915,9 +1944,15 @@ def build_anthropic_kwargs(
 
     # ── Fast mode (Opus 4.6 only) ────────────────────────────────────
     # Adds extra_body.speed="fast" + the fast-mode beta header for ~2.5x
-    # output speed. Only for native Anthropic endpoints — third-party
-    # providers would reject the unknown beta header and speed parameter.
-    if fast_mode and not _is_third_party_anthropic_endpoint(base_url):
+    # output speed. Per Anthropic docs, fast mode is only supported on
+    # Opus 4.6 — Opus 4.7 and other models 400 on the speed parameter.
+    # Only for native Anthropic endpoints — third-party providers would
+    # reject the unknown beta header and speed parameter.
+    if (
+        fast_mode
+        and not _is_third_party_anthropic_endpoint(base_url)
+        and _supports_fast_mode(model)
+    ):
         kwargs.setdefault("extra_body", {})["speed"] = "fast"
         # Build extra_headers with ALL applicable betas (the per-request
         # extra_headers override the client-level anthropic-beta header).

agent/auxiliary_client.py

@@ -1529,7 +1529,7 @@ def _build_codex_client(model: str) -> Tuple[Optional[Any], Optional[str]]:
     return CodexAuxiliaryClient(real_client, model), model
 
 
-def _try_anthropic() -> Tuple[Optional[Any], Optional[str]]:
+def _try_anthropic(explicit_api_key: str = None) -> Tuple[Optional[Any], Optional[str]]:
     try:
         from agent.anthropic_adapter import build_anthropic_client, resolve_anthropic_token
     except ImportError:
@@ -1539,10 +1539,10 @@ def _try_anthropic() -> Tuple[Optional[Any], Optional[str]]:
     if pool_present:
         if entry is None:
             return None, None
-        token = _pool_runtime_api_key(entry)
+        token = explicit_api_key or _pool_runtime_api_key(entry)
     else:
         entry = None
-        token = resolve_anthropic_token()
+        token = explicit_api_key or resolve_anthropic_token()
     if not token:
         return None, None
 
@@ -2336,7 +2336,7 @@ def resolve_provider_client(
 
     if pconfig.auth_type == "api_key":
         if provider == "anthropic":
-            client, default_model = _try_anthropic()
+            client, default_model = _try_anthropic(explicit_api_key=explicit_api_key)
             if client is None:
                 logger.warning("resolve_provider_client: anthropic requested but no Anthropic credentials found")
                 return None, None
@@ -2648,8 +2648,11 @@ def resolve_vision_provider_client(
         return resolved_provider, sync_client, final_model
 
     if resolved_base_url:
+        provider_for_base_override = (
+            requested if requested and requested not in ("", "auto") else "custom"
+        )
         client, final_model = resolve_provider_client(
-            "custom",
+            provider_for_base_override,
             model=resolved_model,
             async_mode=async_mode,
             explicit_base_url=resolved_base_url,
@@ -2657,8 +2660,8 @@ def resolve_vision_provider_client(
             api_mode=resolved_api_mode,
         )
         if client is None:
-            return "custom", None, None
-        return "custom", client, final_model
+            return provider_for_base_override, None, None
+        return provider_for_base_override, client, final_model
 
     if requested == "auto":
         # Vision auto-detection order:

agent/context_compressor.py

@@ -344,6 +344,7 @@ class ContextCompressor(ContextEngine):
         self._last_aux_model_failure_model = None
         self._last_compression_savings_pct = 100.0
         self._ineffective_compression_count = 0
+        self._summary_failure_cooldown_until = 0.0  # transient errors must not block a fresh session
 
     def update_model(
         self,
@@ -553,7 +554,16 @@ class ContextCompressor(ContextEngine):
                     break
                 accumulated += msg_tokens
                 boundary = i
-            prune_boundary = max(boundary, len(result) - min_protect)
+            # Translate the budget walk into a "protected count", apply the
+            # floor in count-space (where `max` reads naturally: protect at
+            # least `min_protect` messages or whatever the budget reserved,
+            # whichever is more), then convert back to a prune boundary.
+            # Doing this in index-space with `max` would invert the direction
+            # (smaller index = MORE protected), so a generous budget would
+            # silently get truncated back down to `min_protect`.
+            budget_protect_count = len(result) - boundary
+            protected_count = max(budget_protect_count, min_protect)
+            prune_boundary = len(result) - protected_count
         else:
             prune_boundary = len(result) - protect_tail_count
 
@@ -569,6 +579,8 @@ class ContextCompressor(ContextEngine):
             # Skip multimodal content (list of content blocks)
             if isinstance(content, list):
                 continue
+            if not isinstance(content, str):
+                continue
             if len(content) < 200:
                 continue
             h = hashlib.md5(content.encode("utf-8", errors="replace")).hexdigest()[:12]
@@ -588,6 +600,8 @@ class ContextCompressor(ContextEngine):
             # Skip multimodal content (list of content blocks)
             if isinstance(content, list):
                 continue
+            if not isinstance(content, str):
+                continue
             if not content or content == _PRUNED_TOOL_PLACEHOLDER:
                 continue
             # Skip already-deduplicated or previously-summarized results
@@ -903,15 +917,19 @@ The user has requested that this compaction PRIORITISE preserving all informatio
                 or "does not exist" in _err_str
                 or "no available channel" in _err_str
             )
+            _is_timeout = (
+                _status in (408, 429, 502, 504)
+                or "timeout" in _err_str
+            )
             if (
-                _is_model_not_found
+                (_is_model_not_found or _is_timeout)
                 and self.summary_model
                 and self.summary_model != self.model
                 and not getattr(self, "_summary_model_fallen_back", False)
             ):
                 self._summary_model_fallen_back = True
                 logging.warning(
-                    "Summary model '%s' not available (%s). "
+                    "Summary model '%s' unavailable (%s). "
                     "Falling back to main model '%s' for compression.",
                     self.summary_model, e, self.model,
                 )

agent/curator.py

@@ -24,11 +24,12 @@ from __future__ import annotations
 import json
 import logging
 import os
+import re
 import tempfile
 import threading
 from datetime import datetime, timedelta, timezone
 from pathlib import Path
-from typing import Any, Callable, Dict, List, Optional, Set
+from typing import Any, Callable, Dict, List, NamedTuple, Optional, Set
 
 from hermes_constants import get_hermes_home
 from tools import skill_usage
@@ -36,6 +37,22 @@ from tools import skill_usage
 logger = logging.getLogger(__name__)
 
 
+def _strip_aux_credential(value: Any) -> Optional[str]:
+    if value is None:
+        return None
+    text = str(value).strip()
+    return text or None
+
+
+class _ReviewRuntimeBinding(NamedTuple):
+    """Provider/model for the curator review fork plus optional per-slot overrides."""
+
+    provider: str
+    model: str
+    explicit_api_key: Optional[str]
+    explicit_base_url: Optional[str]
+
+
 DEFAULT_INTERVAL_HOURS = 24 * 7  # 7 days
 DEFAULT_MIN_IDLE_HOURS = 2
 DEFAULT_STALE_AFTER_DAYS = 30
@@ -453,6 +470,24 @@ def _reports_root() -> Path:
     return root
 
 
+def _needle_in_path_component(needle: str, path: str) -> bool:
+    """Check if *needle* is a complete filename stem or directory name in *path*.
+
+    Unlike simple substring matching, this avoids false positives where short
+    skill names are embedded in longer filenames (e.g. "api" matching
+    "references/api-design.md").  Hyphens and underscores are normalised so
+    "open-webui-setup" matches "open_webui_setup.md".
+    """
+    norm_needle = needle.replace("-", "_")
+    for part in path.replace("\\", "/").split("/"):
+        if not part:
+            continue
+        stem = part.rsplit(".", 1)[0] if "." in part else part
+        if stem.replace("-", "_") == norm_needle:
+            return True
+    return False
+
+
 def _classify_removed_skills(
     removed: List[str],
     added: List[str],
@@ -531,15 +566,29 @@ def _classify_removed_skills(
                 continue
 
             # Look for the removed skill's name in file_path / content / raw.
-            haystacks: List[str] = []
+            # Matching strategy differs by field type:
+            #   file_path — needle must be a complete path component
+            #     (filename stem or directory name), so "api" does NOT
+            #     falsely match "references/api-design.md".
+            #   content fields — word-boundary regex so "test" does NOT
+            #     falsely match "latest" or "testing".
+            haystacks: List[tuple[str, str]] = []
             for key in ("file_path", "file_content", "content", "new_string", "_raw"):
                 v = args.get(key)
                 if isinstance(v, str):
-                    haystacks.append(v)
+                    haystacks.append((key, v))
             hit = False
-            for hay in haystacks:
+            for key, hay in haystacks:
                 for needle in needles:
-                    if needle and needle in hay:
+                    if not needle:
+                        continue
+                    if key == "file_path":
+                        matched = _needle_in_path_component(needle, hay)
+                    else:
+                        matched = bool(
+                            re.search(rf'\b{re.escape(needle)}\b', hay)
+                        )
+                    if matched:
                         hit = True
                         evidence = (
                             f"skill_manage action={args.get('action', '?')} "
@@ -1398,6 +1447,52 @@ def run_curator_review(
     }
 
 
+def _resolve_review_runtime(cfg: Dict[str, Any]) -> _ReviewRuntimeBinding:
+    """Resolve provider/model and per-slot credentials for the curator review fork.
+
+    Same precedence as `_resolve_review_model()`. Non-empty ``api_key`` /
+    ``base_url`` from the active slot are returned as explicit overrides so
+    ``resolve_runtime_provider`` does not silently reuse the main chat
+    credential chain for a routed auxiliary model.
+    """
+    _main = cfg.get("model", {}) if isinstance(cfg.get("model"), dict) else {}
+    _main_provider = _main.get("provider") or "auto"
+    _main_model = _main.get("default") or _main.get("model") or ""
+
+    # 1. Canonical aux task slot
+    _aux = cfg.get("auxiliary", {}) if isinstance(cfg.get("auxiliary"), dict) else {}
+    _cur_task = _aux.get("curator", {}) if isinstance(_aux.get("curator"), dict) else {}
+    _task_provider = (_cur_task.get("provider") or "").strip() or None
+    _task_model = (_cur_task.get("model") or "").strip() or None
+    if _task_provider and _task_provider != "auto" and _task_model:
+        return _ReviewRuntimeBinding(
+            _task_provider,
+            _task_model,
+            _strip_aux_credential(_cur_task.get("api_key")),
+            _strip_aux_credential(_cur_task.get("base_url")),
+        )
+
+    # 2. Legacy curator.auxiliary.{provider,model} (deprecated, pre-unification)
+    _cur = cfg.get("curator", {}) if isinstance(cfg.get("curator"), dict) else {}
+    _legacy = _cur.get("auxiliary", {}) if isinstance(_cur.get("auxiliary"), dict) else {}
+    _legacy_provider = _legacy.get("provider") or None
+    _legacy_model = _legacy.get("model") or None
+    if _legacy_provider and _legacy_model:
+        logger.info(
+            "curator: using deprecated curator.auxiliary.{provider,model} "
+            "config — please migrate to auxiliary.curator.{provider,model}"
+        )
+        return _ReviewRuntimeBinding(
+            str(_legacy_provider),
+            str(_legacy_model),
+            _strip_aux_credential(_legacy.get("api_key")),
+            _strip_aux_credential(_legacy.get("base_url")),
+        )
+
+    # 3. Fall through to the main chat model
+    return _ReviewRuntimeBinding(_main_provider, _main_model, None, None)
+
+
 def _resolve_review_model(cfg: Dict[str, Any]) -> tuple[str, str]:
     """Pick (provider, model) for the curator review fork.
 
@@ -1413,32 +1508,8 @@ def _resolve_review_model(cfg: Dict[str, Any]) -> tuple[str, str]:
       2. Legacy ``curator.auxiliary.{provider,model}`` when both are set
       3. Main ``model.{provider,default/model}`` pair
     """
-    _main = cfg.get("model", {}) if isinstance(cfg.get("model"), dict) else {}
-    _main_provider = _main.get("provider") or "auto"
-    _main_model = _main.get("default") or _main.get("model") or ""
-
-    # 1. Canonical aux task slot
-    _aux = cfg.get("auxiliary", {}) if isinstance(cfg.get("auxiliary"), dict) else {}
-    _cur_task = _aux.get("curator", {}) if isinstance(_aux.get("curator"), dict) else {}
-    _task_provider = (_cur_task.get("provider") or "").strip() or None
-    _task_model = (_cur_task.get("model") or "").strip() or None
-    if _task_provider and _task_provider != "auto" and _task_model:
-        return _task_provider, _task_model
-
-    # 2. Legacy curator.auxiliary.{provider,model} (deprecated, pre-unification)
-    _cur = cfg.get("curator", {}) if isinstance(cfg.get("curator"), dict) else {}
-    _legacy = _cur.get("auxiliary", {}) if isinstance(_cur.get("auxiliary"), dict) else {}
-    _legacy_provider = _legacy.get("provider") or None
-    _legacy_model = _legacy.get("model") or None
-    if _legacy_provider and _legacy_model:
-        logger.info(
-            "curator: using deprecated curator.auxiliary.{provider,model} "
-            "config — please migrate to auxiliary.curator.{provider,model}"
-        )
-        return _legacy_provider, _legacy_model
-
-    # 3. Fall through to the main chat model
-    return _main_provider, _main_model
+    b = _resolve_review_runtime(cfg)
+    return b.provider, b.model
 
 
 def _run_llm_review(prompt: str) -> Dict[str, Any]:
@@ -1477,10 +1548,10 @@ def _run_llm_review(prompt: str) -> Dict[str, Any]:
     # arguments hits an auto-resolution path that fails for OAuth-only
     # providers and for pool-backed credentials.
     #
-    # `_resolve_review_model()` honors `auxiliary.curator.{provider,model}`
+    # `_resolve_review_runtime()` honors `auxiliary.curator.{provider,model,...}`
     # (canonical aux-task slot, wired through `hermes model` → auxiliary
     # picker and the dashboard Models tab), with a legacy fallback to
-    # `curator.auxiliary.{provider,model}`. See docs/user-guide/features/curator.md.
+    # `curator.auxiliary.{provider,model,...}`. See docs/user-guide/features/curator.md.
     _api_key = None
     _base_url = None
     _api_mode = None
@@ -1490,9 +1561,13 @@ def _run_llm_review(prompt: str) -> Dict[str, Any]:
         from hermes_cli.config import load_config
         from hermes_cli.runtime_provider import resolve_runtime_provider
         _cfg = load_config()
-        _provider, _model_name = _resolve_review_model(_cfg)
+        _binding = _resolve_review_runtime(_cfg)
+        _provider, _model_name = _binding.provider, _binding.model
         _rp = resolve_runtime_provider(
-            requested=_provider, target_model=_model_name
+            requested=_provider,
+            target_model=_model_name,
+            explicit_api_key=_binding.explicit_api_key,
+            explicit_base_url=_binding.explicit_base_url,
         )
         _api_key = _rp.get("api_key")
         _base_url = _rp.get("base_url")

agent/error_classifier.py

@@ -520,7 +520,12 @@ def classify_api_error(
 
     is_disconnect = any(p in error_msg for p in _SERVER_DISCONNECT_PATTERNS)
     if is_disconnect and not status_code:
-        is_large = approx_tokens > context_length * 0.6 or approx_tokens > 120000 or num_messages > 200
+        # Absolute token/message-count thresholds are only a proxy for smaller
+        # context windows.  Large-context sessions can have hundreds of
+        # messages while still being far below their actual token budget.
+        is_large = approx_tokens > context_length * 0.6 or (
+            context_length <= 256000 and (approx_tokens > 120000 or num_messages > 200)
+        )
         if is_large:
             return _result(
                 FailoverReason.context_overflow,
@@ -766,7 +771,12 @@ def _classify_400(
         if not err_body_msg:
             err_body_msg = str(body.get("message") or "").strip().lower()
     is_generic = len(err_body_msg) < 30 or err_body_msg in ("error", "")
-    is_large = approx_tokens > context_length * 0.4 or approx_tokens > 80000 or num_messages > 80
+    # Absolute token/message-count thresholds are only a proxy for smaller
+    # context windows.  Large-context sessions can have many messages while
+    # still being far below their actual token budget.
+    is_large = approx_tokens > context_length * 0.4 or (
+        context_length <= 256000 and (approx_tokens > 80000 or num_messages > 80)
+    )
 
     if is_generic and is_large:
         return result_fn(

agent/gemini_native_adapter.py

@@ -679,7 +679,21 @@ def translate_stream_event(event: Dict[str, Any], model: str, tool_call_indices:
     finish_reason_raw = str(cand.get("finishReason") or "")
     if finish_reason_raw:
         mapped = "tool_calls" if tool_call_indices else _map_gemini_finish_reason(finish_reason_raw)
-        chunks.append(_make_stream_chunk(model=model, finish_reason=mapped))
+        finish_chunk = _make_stream_chunk(model=model, finish_reason=mapped)
+        # Attach usage from this event's usageMetadata so the streaming
+        # loop in run_agent.py can record token counts (mirrors the
+        # non-streaming path in translate_gemini_response).
+        usage_meta = event.get("usageMetadata") or {}
+        if usage_meta:
+            finish_chunk.usage = SimpleNamespace(
+                prompt_tokens=int(usage_meta.get("promptTokenCount") or 0),
+                completion_tokens=int(usage_meta.get("candidatesTokenCount") or 0),
+                total_tokens=int(usage_meta.get("totalTokenCount") or 0),
+                prompt_tokens_details=SimpleNamespace(
+                    cached_tokens=int(usage_meta.get("cachedContentTokenCount") or 0),
+                ),
+            )
+        chunks.append(finish_chunk)
     return chunks
 
 

agent/google_oauth.py

@@ -489,16 +489,29 @@ def save_credentials(creds: GoogleCredentials) -> Path:
     """Atomically write creds to disk with 0o600 permissions."""
     path = _credentials_path()
     path.parent.mkdir(parents=True, exist_ok=True)
+    # Tighten parent dir to 0o700 so siblings can't traverse to the creds file.
+    # On Windows this is a no-op (POSIX mode bits aren't enforced); ignore failures.
+    try:
+        os.chmod(path.parent, 0o700)
+    except OSError:
+        pass
     payload = json.dumps(creds.to_dict(), indent=2, sort_keys=True) + "\n"
 
     with _credentials_lock():
         tmp_path = path.with_suffix(f".tmp.{os.getpid()}.{secrets.token_hex(4)}")
         try:
-            with open(tmp_path, "w", encoding="utf-8") as fh:
+            # Create with 0o600 atomically to close the TOCTOU window where the
+            # default umask (often 0o644) would briefly expose tokens to other
+            # local users between open() and chmod().
+            fd = os.open(
+                str(tmp_path),
+                os.O_WRONLY | os.O_CREAT | os.O_EXCL,
+                stat.S_IRUSR | stat.S_IWUSR,
+            )
+            with os.fdopen(fd, "w", encoding="utf-8") as fh:
                 fh.write(payload)
                 fh.flush()
                 os.fsync(fh.fileno())
-            os.chmod(tmp_path, stat.S_IRUSR | stat.S_IWUSR)
             atomic_replace(tmp_path, path)
         finally:
             try:

agent/prompt_builder.py

@@ -183,8 +183,8 @@ SKILLS_GUIDANCE = (
 )
 
 KANBAN_GUIDANCE = (
-    "# You are a Kanban worker\n"
-    "You were spawned by the Hermes Kanban dispatcher to execute ONE task from "
+    "# Kanban task execution protocol\n"
+    "You have been assigned ONE task from "
     "the shared board at `~/.hermes/kanban.db`. Your task id is in "
     "`$HERMES_KANBAN_TASK`; your workspace is `$HERMES_KANBAN_WORKSPACE`. "
     "The `kanban_*` tools in your schema are your primary coordination surface — "

agent/redact.py

@@ -305,13 +305,18 @@ def _redact_form_body(text: str) -> str:
     return _redact_query_string(text.strip())
 
 
-def redact_sensitive_text(text: str, *, force: bool = False) -> str:
+def redact_sensitive_text(text: str, *, force: bool = False, code_file: bool = False) -> str:
     """Apply all redaction patterns to a block of text.
 
     Safe to call on any string -- non-matching text passes through unchanged.
     Disabled by default — enable via security.redact_secrets: true in config.yaml.
     Set force=True for safety boundaries that must never return raw secrets
     regardless of the user's global logging redaction preference.
+
+    Set code_file=True to skip the ENV-assignment and JSON-field regex
+    patterns when the text is known to be source code (e.g. MAX_TOKENS=***
+    constants, "apiKey": "test" fixtures). Prefix patterns, auth headers,
+    private keys, DB connstrings, JWTs, and URL secrets are still redacted.
     """
     if text is None:
         return None
@@ -325,17 +330,18 @@ def redact_sensitive_text(text: str, *, force: bool = False) -> str:
     # Known prefixes (sk-, ghp_, etc.)
     text = _PREFIX_RE.sub(lambda m: _mask_token(m.group(1)), text)
 
-    # ENV assignments: OPENAI_API_KEY=sk-abc...
-    def _redact_env(m):
-        name, quote, value = m.group(1), m.group(2), m.group(3)
-        return f"{name}={quote}{_mask_token(value)}{quote}"
-    text = _ENV_ASSIGN_RE.sub(_redact_env, text)
+    # ENV assignments: OPENAI_API_KEY=***  (skip for code files — false positives)
+    if not code_file:
+        def _redact_env(m):
+            name, quote, value = m.group(1), m.group(2), m.group(3)
+            return f"{name}={quote}{_mask_token(value)}{quote}"
+        text = _ENV_ASSIGN_RE.sub(_redact_env, text)
 
-    # JSON fields: "apiKey": "value"
-    def _redact_json(m):
-        key, value = m.group(1), m.group(2)
-        return f'{key}: "{_mask_token(value)}"'
-    text = _JSON_FIELD_RE.sub(_redact_json, text)
+        # JSON fields: "apiKey": "***"  (skip for code files — false positives)
+        def _redact_json(m):
+            key, value = m.group(1), m.group(2)
+            return f'{key}: "{_mask_token(value)}"'
+        text = _JSON_FIELD_RE.sub(_redact_json, text)
 
     # Authorization headers
     text = _AUTH_HEADER_RE.sub(

agent/title_generator.py

@@ -17,6 +17,7 @@ logger = logging.getLogger(__name__)
 # so silent-drops (e.g. OpenRouter 402 exhausting the fallback chain)
 # become visible instead of piling up as NULL session titles.
 FailureCallback = Callable[[str, BaseException], None]
+TitleCallback = Callable[[str], None]
 
 _TITLE_PROMPT = (
     "Generate a short, descriptive title (3-7 words) for a conversation that starts with the "
@@ -90,6 +91,7 @@ def auto_title_session(
     assistant_response: str,
     failure_callback: Optional[FailureCallback] = None,
     main_runtime: dict = None,
+    title_callback: Optional[TitleCallback] = None,
 ) -> None:
     """Generate and set a session title if one doesn't already exist.
 
@@ -119,6 +121,11 @@ def auto_title_session(
     try:
         session_db.set_session_title(session_id, title)
         logger.debug("Auto-generated session title: %s", title)
+        if title_callback is not None:
+            try:
+                title_callback(title)
+            except Exception:
+                logger.debug("Auto-title callback failed", exc_info=True)
     except Exception as e:
         logger.debug("Failed to set auto-generated title: %s", e)
 
@@ -131,6 +138,7 @@ def maybe_auto_title(
     conversation_history: list,
     failure_callback: Optional[FailureCallback] = None,
     main_runtime: dict = None,
+    title_callback: Optional[TitleCallback] = None,
 ) -> None:
     """Fire-and-forget title generation after the first exchange.
 
@@ -152,7 +160,11 @@ def maybe_auto_title(
     thread = threading.Thread(
         target=auto_title_session,
         args=(session_db, session_id, user_message, assistant_response),
-        kwargs={"failure_callback": failure_callback, "main_runtime": main_runtime},
+        kwargs={
+            "failure_callback": failure_callback,
+            "main_runtime": main_runtime,
+            "title_callback": title_callback,
+        },
         daemon=True,
         name="auto-title",
     )

agent/transports/codex.py

@@ -143,7 +143,18 @@ class ResponsesApiTransport(ProviderTransport):
             kwargs["max_output_tokens"] = max_tokens
 
         if is_xai_responses and session_id:
-            kwargs["extra_headers"] = {"x-grok-conv-id": session_id}
+            existing_extra_headers = kwargs.get("extra_headers")
+            merged_extra_headers: Dict[str, str] = {}
+            if isinstance(existing_extra_headers, dict):
+                merged_extra_headers.update(
+                    {
+                        str(key): str(value)
+                        for key, value in existing_extra_headers.items()
+                        if key and value is not None
+                    }
+                )
+            merged_extra_headers["x-grok-conv-id"] = session_id
+            kwargs["extra_headers"] = merged_extra_headers
 
         return kwargs
 

cli.py

@@ -459,32 +459,19 @@ def load_cli_config() -> Dict[str, Any]:
     if "backend" in terminal_config:
         terminal_config["env_type"] = terminal_config["backend"]
     
-    # Handle special cwd values: "." or "auto" means use current working directory.
-    # Only resolve to the host's CWD for the local backend where the host
-    # filesystem is directly accessible.  For ALL remote/container backends
-    # (ssh, docker, modal, singularity), the host path doesn't exist on the
-    # target -- remove the key so terminal_tool.py uses its per-backend default.
-    #
-    # GUARD: If TERMINAL_CWD is already set to a real absolute path (by the
-    # gateway's config bridge earlier in the process), don't clobber it.
-    # This prevents a lazy import of cli.py during gateway runtime from
-    # rewriting TERMINAL_CWD to the service's working directory.
-    # See issue #10817.
+    # CWD resolution for CLI/TUI. The gateway has its own config bridge in
+    # gateway/run.py but may lazily import cli.py (triggering this code).
+    # Local backend: always os.getcwd(). Use `cd /dir && hermes` to control it.
+    # Non-local with placeholder: pop so terminal_tool uses its per-backend default.
+    # Non-local with explicit path: keep as-is.
     _CWD_PLACEHOLDERS = (".", "auto", "cwd")
-    if terminal_config.get("cwd") in _CWD_PLACEHOLDERS:
-        _existing_cwd = os.environ.get("TERMINAL_CWD", "")
-        if _existing_cwd and _existing_cwd not in _CWD_PLACEHOLDERS and os.path.isabs(_existing_cwd):
-            # Gateway (or earlier startup) already resolved a real path — keep it
-            terminal_config["cwd"] = _existing_cwd
-            defaults["terminal"]["cwd"] = _existing_cwd
-        else:
-            effective_backend = terminal_config.get("env_type", "local")
-            if effective_backend == "local":
-                terminal_config["cwd"] = os.getcwd()
-                defaults["terminal"]["cwd"] = terminal_config["cwd"]
-            else:
-                # Remove so TERMINAL_CWD stays unset → tool picks backend default
-                terminal_config.pop("cwd", None)
+    effective_backend = terminal_config.get("env_type", "local")
+
+    if effective_backend == "local":
+        terminal_config["cwd"] = os.getcwd()
+        defaults["terminal"]["cwd"] = terminal_config["cwd"]
+    elif terminal_config.get("cwd") in _CWD_PLACEHOLDERS:
+        terminal_config.pop("cwd", None)
     
     env_mappings = {
         "env_type": "TERMINAL_ENV",
@@ -517,13 +504,18 @@ def load_cli_config() -> Dict[str, Any]:
         "sudo_password": "SUDO_PASSWORD",
     }
     
-    # Apply config values to env vars so terminal_tool picks them up.
-    # If the config file explicitly has a [terminal] section, those values are
-    # authoritative and override any .env settings.  When using defaults only
-    # (no config file or no terminal section), don't overwrite env vars that
-    # were already set by .env -- the user's .env is the fallback source.
+    # Bridge config → env vars for terminal_tool. TERMINAL_CWD is force-exported
+    # UNLESS we're inside a gateway process (detected by _HERMES_GATEWAY marker)
+    # where it was already set correctly by gateway/run.py's config bridge.
+    _is_gateway = os.environ.get("_HERMES_GATEWAY") == "1"
     for config_key, env_var in env_mappings.items():
         if config_key in terminal_config:
+            if env_var == "TERMINAL_CWD":
+                if _is_gateway:
+                    continue
+                # CLI: always export (overrides stale .env or inherited values)
+                os.environ[env_var] = str(terminal_config[config_key])
+                continue
             if _file_has_terminal_config or env_var not in os.environ:
                 val = terminal_config[config_key]
                 if isinstance(val, list):
@@ -1234,6 +1226,28 @@ def _strip_markdown_syntax(text: str) -> str:
     return plain.strip("\n")
 
 
+_WINDOWS_PATH_WITH_DOT_SEGMENT_RE = re.compile(
+    r"(?i)(?:\b[a-z]:\\|\\\\)[^\s`]*\\\.[^\s`]*"
+)
+
+
+def _preserve_windows_dot_segments_for_markdown(text: str) -> str:
+    r"""Keep Windows path separators before hidden directories in Markdown.
+
+    CommonMark treats ``\.`` as an escaped literal dot, so Rich Markdown would
+    render ``D:\repo\.ai`` as ``D:\repo.ai``.  Doubling only that separator
+    inside Windows path-looking tokens preserves the path without changing
+    ordinary markdown escapes like ``1\. not a list``.
+    """
+    if "\\." not in text:
+        return text
+
+    def _protect(match: re.Match[str]) -> str:
+        return re.sub(r"(?<!\\)\\(?=\.)", r"\\\\", match.group(0))
+
+    return _WINDOWS_PATH_WITH_DOT_SEGMENT_RE.sub(_protect, text)
+
+
 def _render_final_assistant_content(text: str, mode: str = "render"):
     """Render final assistant content as markdown, stripped text, or raw text."""
     from rich.markdown import Markdown
@@ -1245,6 +1259,7 @@ def _render_final_assistant_content(text: str, mode: str = "render"):
         return _rich_text_from_ansi(text or "")
 
     plain = _rich_text_from_ansi(text or "").plain
+    plain = _preserve_windows_dot_segments_for_markdown(plain)
     return Markdown(plain)
 
 
@@ -1513,6 +1528,10 @@ def _detect_file_drop(user_input: str) -> "dict | None":
         or stripped.startswith('"~')
         or stripped.startswith("'/")
         or stripped.startswith("'~")
+        or stripped.startswith('"./')
+        or stripped.startswith('"../')
+        or stripped.startswith("'./")
+        or stripped.startswith("'../")
         or (len(stripped) >= 4 and stripped[0] in ("'", '"') and stripped[2] == ":" and stripped[3] in ("\\", "/") and stripped[1].isalpha())
     )
     if not starts_like_path:
@@ -2560,23 +2579,59 @@ class HermesCLI:
             return f"  {txt}  ({elapsed_str})"
         return f"  {txt}"
 
+    def _voice_record_key_label(self) -> str:
+        """Return the configured voice push-to-talk key formatted for UI.
+
+        Shared helper so every voice-facing status line / placeholder /
+        recording hint advertises the SAME label as the registered
+        prompt_toolkit binding.
+
+        Cached at startup (see ``set_voice_record_key_cache``) rather
+        than re-read per render. Two reasons (Copilot round-13 on
+        #19835):
+
+        * The prompt_toolkit binding is registered once at session
+          start via ``@kb.add(_voice_key)``; re-reading config per
+          render meant the status bar could advertise a new shortcut
+          after a config edit while the actual binding was still the
+          startup chord — exactly the display/binding drift this PR
+          is trying to eliminate.
+        * The label is on the hot render path (status bar + composer
+          placeholder invalidated every 150ms during recording), so
+          reading config on every call added avoidable UI overhead.
+        """
+        return getattr(self, "_voice_record_key_display_cache", None) or "Ctrl+B"
+
+    def set_voice_record_key_cache(self, raw_key: object) -> None:
+        """Populate the voice label cache from a raw ``voice.record_key``.
+
+        Called at CLI startup after the prompt_toolkit binding is
+        registered so the cached label always matches the live binding.
+        """
+        try:
+            from hermes_cli.voice import format_voice_record_key_for_status
+            self._voice_record_key_display_cache = format_voice_record_key_for_status(raw_key)
+        except Exception:
+            self._voice_record_key_display_cache = "Ctrl+B"
+
     def _get_voice_status_fragments(self, width: Optional[int] = None):
         """Return the voice status bar fragments for the interactive TUI."""
         width = width or self._get_tui_terminal_width()
         compact = self._use_minimal_tui_chrome(width=width)
+        label = self._voice_record_key_label()
         if self._voice_recording:
             if compact:
                 return [("class:voice-status-recording", " ● REC ")]
-            return [("class:voice-status-recording", " ● REC  Ctrl+B to stop ")]
+            return [("class:voice-status-recording", f" ● REC  {label} to stop ")]
         if self._voice_processing:
             if compact:
                 return [("class:voice-status", " ◉ STT ")]
             return [("class:voice-status", " ◉ Transcribing... ")]
         if compact:
-            return [("class:voice-status", " 🎤 Ctrl+B ")]
+            return [("class:voice-status", f" 🎤 {label} ")]
         tts = " | TTS on" if self._voice_tts else ""
         cont = " | Continuous" if self._voice_continuous else ""
-        return [("class:voice-status", f" 🎤 Voice mode{tts}{cont}  —  Ctrl+B to record ")]
+        return [("class:voice-status", f" 🎤 Voice mode{tts}{cont}  —  {label} to record ")]
 
     def _build_status_bar_text(self, width: Optional[int] = None) -> str:
         """Return a compact one-line session status string for the TUI footer."""
@@ -4936,7 +4991,7 @@ class HermesCLI:
         except Exception:
             pass
 
-    def new_session(self, silent=False):
+    def new_session(self, silent=False, title=None):
         """Start a fresh session with a new session ID and cleared agent state."""
         if self.agent and self.conversation_history:
             # Trigger memory extraction on the old session before session_id rotates.
@@ -4991,6 +5046,28 @@ class HermesCLI:
                     self.agent._session_db_created = True
                 except Exception:
                     pass
+                if title and self._session_db:
+                    from hermes_state import SessionDB
+                    try:
+                        sanitized = SessionDB.sanitize_title(title)
+                    except ValueError as e:
+                        _cprint(f"  Title rejected: {e}")
+                        sanitized = None
+                        title = None
+                    if sanitized:
+                        try:
+                            self._session_db.set_session_title(self.session_id, sanitized)
+                            self._pending_title = None
+                            title = sanitized
+                        except ValueError as e:
+                            _cprint(f"  {e} — session started untitled.")
+                            title = None
+                        except Exception:
+                            title = None
+                    elif title is not None:
+                        # sanitize_title returned empty (whitespace-only / unprintable)
+                        _cprint("  Title is empty after cleanup — session started untitled.")
+                        title = None
             # Notify memory providers that session_id rotated to a fresh
             # conversation. reset=True signals providers to flush accumulated
             # per-session state (_session_turns, _turn_counter, _document_id).
@@ -5010,7 +5087,10 @@ class HermesCLI:
             self._notify_session_boundary("on_session_reset")
 
         if not silent:
-            print("(^_^)v New session started!")
+            if title:
+                print(f"(^_^)v New session started: {title}")
+            else:
+                print("(^_^)v New session started!")
 
     def _handle_resume_command(self, cmd_original: str) -> None:
         """Handle /resume <session_id_or_title> — switch to a previous session mid-conversation."""
@@ -6286,7 +6366,7 @@ class HermesCLI:
         _cmd_def = _resolve_cmd(_base_word)
         canonical = _cmd_def.name if _cmd_def else _base_word
         
-        if canonical in ("quit", "exit", "q"):
+        if canonical in ("quit", "exit"):
             return False
         elif canonical == "help":
             self.show_help()
@@ -6422,7 +6502,9 @@ class HermesCLI:
                 else:
                     _cprint("  Session database not available.")
         elif canonical == "new":
-            self.new_session()
+            parts = cmd_original.split(maxsplit=1)
+            title = parts[1].strip() if len(parts) > 1 else None
+            self.new_session(title=title)
         elif canonical == "resume":
             self._handle_resume_command(cmd_original)
         elif canonical == "model":
@@ -8224,20 +8306,38 @@ class HermesCLI:
                 return
             self._voice_recording = True
 
-        # Load silence detection params from config
-        voice_cfg = {}
+        # Load silence detection params from config. Shape-safe: a
+        # hand-edited ``voice: true`` / ``voice: cmd+b`` leaves
+        # ``load_config()['voice']`` as a non-dict; coerce to {} so
+        # continuous recording falls back to the documented defaults
+        # instead of crashing on ``.get()``.
+        voice_cfg: dict = {}
         try:
             from hermes_cli.config import load_config
-            voice_cfg = load_config().get("voice", {})
+            _cfg = load_config().get("voice")
+            voice_cfg = _cfg if isinstance(_cfg, dict) else {}
         except Exception:
             pass
 
         if self._voice_recorder is None:
             self._voice_recorder = create_audio_recorder()
 
-        # Apply config-driven silence params
-        self._voice_recorder._silence_threshold = voice_cfg.get("silence_threshold", 200)
-        self._voice_recorder._silence_duration = voice_cfg.get("silence_duration", 3.0)
+        # Apply config-driven silence params (numeric-guarded so YAML
+        # scalar corruption doesn't break recording start-up).
+        #
+        # ``bool`` is explicitly excluded from the numeric check — in
+        # Python bool is a subclass of int, so a hand-edited
+        # ``silence_threshold: true`` would otherwise be forwarded as
+        # ``1`` instead of falling back to the 200 default (Copilot
+        # round-12 on #19835).
+        _threshold = voice_cfg.get("silence_threshold")
+        _duration = voice_cfg.get("silence_duration")
+        self._voice_recorder._silence_threshold = (
+            _threshold if isinstance(_threshold, (int, float)) and not isinstance(_threshold, bool) else 200
+        )
+        self._voice_recorder._silence_duration = (
+            _duration if isinstance(_duration, (int, float)) and not isinstance(_duration, bool) else 3.0
+        )
 
         def _on_silence():
             """Called by AudioRecorder when silence is detected after speech."""
@@ -8263,12 +8363,13 @@ class HermesCLI:
             with self._voice_lock:
                 self._voice_recording = False
             raise
+        _label = self._voice_record_key_label()
         if getattr(self._voice_recorder, "supports_silence_autostop", True):
-            _recording_hint = "auto-stops on silence | Ctrl+B to stop & exit continuous"
+            _recording_hint = f"auto-stops on silence | {_label} to stop & exit continuous"
         elif _is_termux_environment():
-            _recording_hint = "Termux:API capture | Ctrl+B to stop"
+            _recording_hint = f"Termux:API capture | {_label} to stop"
         else:
-            _recording_hint = "Ctrl+B to stop"
+            _recording_hint = f"{_label} to stop"
         _cprint(f"\n{_ACCENT}● Recording...{_RST} {_DIM}({_recording_hint}){_RST}")
 
         # Periodically refresh prompt to update audio level indicator
@@ -8383,6 +8484,17 @@ class HermesCLI:
                         _cprint(f"{_DIM}Voice auto-restart failed: {e}{_RST}")
                 threading.Thread(target=_restart_recording, daemon=True).start()
 
+    def _voice_speak_response_async(self, text: str) -> None:
+        """Schedule TTS and mark it pending before continuous recording can restart."""
+        if not self._voice_tts or not text:
+            return
+        self._voice_tts_done.clear()
+        threading.Thread(
+            target=self._voice_speak_response,
+            args=(text,),
+            daemon=True,
+        ).start()
+
     def _voice_speak_response(self, text: str):
         """Speak the agent's response aloud using TTS (runs in background thread)."""
         if not self._voice_tts:
@@ -8502,10 +8614,12 @@ class HermesCLI:
         with self._voice_lock:
             self._voice_mode = True
 
-        # Check config for auto_tts
+        # Check config for auto_tts (shape-safe — malformed ``voice:`` YAML
+        # leaves ``voice_config`` as a non-dict, so guard before .get()).
         try:
             from hermes_cli.config import load_config
-            voice_config = load_config().get("voice", {})
+            _raw_voice = load_config().get("voice")
+            voice_config = _raw_voice if isinstance(_raw_voice, dict) else {}
             if voice_config.get("auto_tts", False):
                 with self._voice_lock:
                     self._voice_tts = True
@@ -8517,13 +8631,11 @@ class HermesCLI:
         # _voice_message_prefix property and its usage in _process_message().
 
         tts_status = " (TTS enabled)" if self._voice_tts else ""
-        try:
-            from hermes_cli.config import load_config
-            _raw_ptt = load_config().get("voice", {}).get("record_key", "ctrl+b")
-            _ptt_key = _raw_ptt.lower().replace("ctrl+", "c-").replace("alt+", "a-")
-        except Exception:
-            _ptt_key = "c-b"
-        _ptt_display = _ptt_key.replace("c-", "Ctrl+").upper()
+        # Use the startup-pinned cache so the advertised shortcut always
+        # matches the live prompt_toolkit binding — reading live config
+        # here would drift after a mid-session config edit (Copilot
+        # round-14 on #19835, same class as round-13).
+        _ptt_display = self._voice_record_key_label()
         _cprint(f"\n{_ACCENT}Voice mode enabled{tts_status}{_RST}")
         _cprint(f"  {_DIM}{_ptt_display} to start/stop recording{_RST}")
         _cprint(f"  {_DIM}/voice tts  to toggle speech output{_RST}")
@@ -8580,7 +8692,6 @@ class HermesCLI:
 
     def _show_voice_status(self):
         """Show current voice mode status."""
-        from hermes_cli.config import load_config
         from tools.voice_mode import check_voice_requirements
 
         reqs = check_voice_requirements()
@@ -8589,9 +8700,11 @@ class HermesCLI:
         _cprint(f"  Mode:      {'ON' if self._voice_mode else 'OFF'}")
         _cprint(f"  TTS:       {'ON' if self._voice_tts else 'OFF'}")
         _cprint(f"  Recording: {'YES' if self._voice_recording else 'no'}")
-        _raw_key = load_config().get("voice", {}).get("record_key", "ctrl+b")
-        _display_key = _raw_key.replace("ctrl+", "Ctrl+").upper() if "ctrl+" in _raw_key.lower() else _raw_key
-        _cprint(f"  Record key: {_display_key}")
+        # Display the startup-pinned label so /voice status always
+        # matches the live prompt_toolkit binding (Copilot round-14 on
+        # #19835, same class as round-13). Reading live config here
+        # would drift after a mid-session config edit.
+        _cprint(f"  Record key: {self._voice_record_key_label()}")
         _cprint(f"\n  {_BOLD}Requirements:{_RST}")
         for line in reqs["details"].split("\n"):
             _cprint(f"    {line}")
@@ -9543,11 +9656,7 @@ class HermesCLI:
             # Speak response aloud if voice TTS is enabled
             # Skip batch TTS when streaming TTS already handled it
             if self._voice_tts and response and not use_streaming_tts:
-                threading.Thread(
-                    target=self._voice_speak_response,
-                    args=(response,),
-                    daemon=True,
-                ).start()
+                self._voice_speak_response_async(response)
 
 
             # Re-queue the interrupt message (and any that arrived while we were
@@ -10430,7 +10539,92 @@ class HermesCLI:
                 else:
                     self._should_exit = True
                     event.app.exit()
-        
+
+        # Ctrl+Shift+C: no binding needed. Terminal emulators (GNOME Terminal,
+        # iTerm2, kitty, Windows Terminal, etc.) intercept Ctrl+Shift+C before
+        # the keystroke reaches the application's stdin — prompt_toolkit never
+        # sees it, and prompt_toolkit's key spec parser doesn't even recognise
+        # 'c-S-c' anyway (the Shift modifier is meaningless on control-sequence
+        # keys). #19884 added a handler for this; #19895 patched the resulting
+        # startup crash with try/except. Both were based on a misreading of how
+        # terminal key events propagate. Deleting the dead handler outright.
+
+        @kb.add('c-q')  # Ctrl+Q
+        def handle_ctrl_q(event):
+            """Alternative interrupt/exit shortcut (Ctrl+Q).
+
+            Behaves like Ctrl+C: cancels active prompts, interrupts the
+            running agent, or clears the input buffer. Does not support
+            the double-press 'force exit' feature of Ctrl+C.
+            """
+            # Cancel active voice recording.
+            _should_cancel_voice = False
+            _recorder_ref = None
+            with cli_ref._voice_lock:
+                if cli_ref._voice_recording and cli_ref._voice_recorder:
+                    _recorder_ref = cli_ref._voice_recorder
+                    cli_ref._voice_recording = False
+                    cli_ref._voice_continuous = False
+                    _should_cancel_voice = True
+            if _should_cancel_voice:
+                _cprint(f"\n{_DIM}Recording cancelled.{_RST}")
+                threading.Thread(
+                    target=_recorder_ref.cancel, daemon=True
+                ).start()
+                event.app.invalidate()
+                return
+
+            # Cancel sudo prompt
+            if self._sudo_state:
+                self._sudo_state["response_queue"].put("")
+                self._sudo_state = None
+                event.app.invalidate()
+                return
+
+            # Cancel secret prompt
+            if self._secret_state:
+                self._cancel_secret_capture()
+                event.app.current_buffer.reset()
+                event.app.invalidate()
+                return
+
+            # Cancel approval prompt (deny)
+            if self._approval_state:
+                self._approval_state["response_queue"].put("deny")
+                self._approval_state = None
+                event.app.invalidate()
+                return
+
+            # Cancel /model picker
+            if self._model_picker_state:
+                self._close_model_picker()
+                event.app.current_buffer.reset()
+                event.app.invalidate()
+                return
+
+            # Cancel clarify prompt
+            if self._clarify_state:
+                self._clarify_state["response_queue"].put(
+                    "The user cancelled. Use your best judgement to proceed."
+                )
+                self._clarify_state = None
+                self._clarify_freetext = False
+                event.app.current_buffer.reset()
+                event.app.invalidate()
+                return
+
+            if self._agent_running and self.agent:
+                print("\n⚡ Interrupting agent...")
+                self.agent.interrupt()
+            else:
+                if event.app.current_buffer.text or self._attached_images:
+                    event.app.current_buffer.reset()
+                    self._attached_images.clear()
+                    event.app.invalidate()
+                else:
+                    self._should_exit = True
+                    event.app.exit()
+
         @kb.add('c-d')
         def handle_ctrl_d(event):
             """Ctrl+D: delete char under cursor (standard readline behaviour).
@@ -10484,15 +10678,44 @@ class HermesCLI:
             run_in_terminal(_suspend)
 
         # Voice push-to-talk key: configurable via config.yaml (voice.record_key)
-        # Default: Ctrl+B (avoids conflict with Ctrl+R readline reverse-search)
-        # Config uses "ctrl+b" format; prompt_toolkit expects "c-b" format.
+        # Default: Ctrl+B (avoids conflict with Ctrl+R readline reverse-search).
+        # Config spellings (ctrl/control/alt/option/opt) are normalized to
+        # prompt_toolkit's c-x / a-x format via ``normalize_voice_record_key_for_prompt_toolkit``
+        # so the same config value binds identically in the TUI and CLI
+        # (Copilot round-9 review on #19835). ``super``/``win``/``windows``
+        # configs silently fall back to the default here since prompt_toolkit
+        # has no super modifier — log a warning so users notice the
+        # TUI/CLI split instead of a silent mismatch (round-11).
+        _raw_key: object = "ctrl+b"
         try:
             from hermes_cli.config import load_config
-            _raw_key = load_config().get("voice", {}).get("record_key", "ctrl+b")
-            _voice_key = _raw_key.lower().replace("ctrl+", "c-").replace("alt+", "a-")
+            from hermes_cli.voice import (
+                normalize_voice_record_key_for_prompt_toolkit,
+                voice_record_key_from_config,
+            )
+            _raw_key = voice_record_key_from_config(load_config())
+            _voice_key = normalize_voice_record_key_for_prompt_toolkit(_raw_key)
+            if (
+                isinstance(_raw_key, str)
+                and _raw_key.strip().lower().split("+", 1)[0].strip() in {"super", "win", "windows"}
+                and _voice_key == "c-b"
+            ):
+                logger.warning(
+                    "voice.record_key %r uses a TUI-only modifier (super/win); "
+                    "CLI fell back to Ctrl+B. Use ctrl+<key> or alt+<key> for "
+                    "cross-runtime parity.",
+                    _raw_key,
+                )
         except Exception:
             _voice_key = "c-b"
 
+        # Cache the UI label here — same ``_raw_key`` that drives the
+        # prompt_toolkit binding below. Every status / placeholder /
+        # recording-hint render reads this cached value so display can
+        # never drift from the live keybinding even if the user edits
+        # voice.record_key mid-session (Copilot round-13 on #19835).
+        self.set_voice_record_key_cache(_raw_key)
+
         @kb.add(_voice_key)
         def handle_voice_record(event):
             """Toggle voice recording when voice mode is active.
@@ -10795,7 +11018,8 @@ class HermesCLI:
 
         def _get_placeholder():
             if cli_ref._voice_recording:
-                return "recording... Ctrl+B to stop, Ctrl+C to cancel"
+                _label = cli_ref._voice_record_key_label()
+                return f"recording... {_label} to stop, Ctrl+C to cancel"
             if cli_ref._voice_processing:
                 return "transcribing..."
             if cli_ref._sudo_state:
@@ -10815,7 +11039,8 @@ class HermesCLI:
             if cli_ref._agent_running:
                 return "msg=interrupt · /queue · /bg · /steer · Ctrl+C cancel"
             if cli_ref._voice_mode:
-                return "type or Ctrl+B to record"
+                _label = cli_ref._voice_record_key_label()
+                return f"type or {_label} to record"
             return ""
 
         input_area.control.input_processors.append(_PlaceholderProcessor(_get_placeholder))

cron/jobs.py

@@ -420,7 +420,7 @@ def _normalize_workdir(workdir: Optional[str]) -> Optional[str]:
 
 
 def create_job(
-    prompt: str,
+    prompt: Optional[str],
     schedule: str,
     name: Optional[str] = None,
     repeat: Optional[int] = None,
@@ -435,12 +435,14 @@ def create_job(
     context_from: Optional[Union[str, List[str]]] = None,
     enabled_toolsets: Optional[List[str]] = None,
     workdir: Optional[str] = None,
+    no_agent: bool = False,
 ) -> Dict[str, Any]:
     """
     Create a new cron job.
 
     Args:
-        prompt: The prompt to run (must be self-contained, or a task instruction when skill is set)
+        prompt: The prompt to run (must be self-contained, or a task instruction when skill is set).
+                Ignored when ``no_agent=True`` except as an optional name hint.
         schedule: Schedule string (see parse_schedule)
         name: Optional friendly name
         repeat: How many times to run (None = forever, 1 = once)
@@ -451,21 +453,33 @@ def create_job(
         model: Optional per-job model override
         provider: Optional per-job provider override
         base_url: Optional per-job base URL override
-        script: Optional path to a Python script whose stdout is injected into the
-                prompt each run.  The script runs before the agent turn, and its output
-                is prepended as context.  Useful for data collection / change detection.
+        script: Optional path to a script whose stdout feeds the job. With
+                ``no_agent=True`` the script IS the job — its stdout is
+                delivered verbatim. Without ``no_agent``, its stdout is
+                injected into the agent's prompt as context (data-collection /
+                change-detection pattern). Paths resolve under
+                ~/.hermes/scripts/; ``.sh`` / ``.bash`` files run via bash,
+                anything else via Python.
         context_from: Optional job ID (or list of job IDs) whose most recent output
                       is injected into the prompt as context before each run.
                       Useful for chaining cron jobs: job A finds data, job B processes it.
         enabled_toolsets: Optional list of toolset names to restrict the agent to.
                           When set, only tools from these toolsets are loaded, reducing
                           token overhead. When omitted, all default tools are loaded.
+                          Ignored when ``no_agent=True``.
         workdir: Optional absolute path.  When set, the job runs as if launched
                 from that directory: 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
                 (via TERMINAL_CWD).  When unset, the old behaviour is preserved
                 (no context files injected, tools use the scheduler's cwd).
+                With ``no_agent=True``, ``workdir`` is still applied as the
+                script's cwd so relative paths inside the script behave
+                predictably.
+        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
+                watchdogs and periodic alerts that don't need LLM reasoning.
 
     Returns:
         The created job dict
@@ -499,6 +513,16 @@ 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_no_agent = bool(no_agent)
+
+    # no_agent jobs are meaningless without a script — the script IS the job.
+    # Surface this as a clear ValueError at create time so bad configs never
+    # reach the scheduler.
+    if normalized_no_agent and not normalized_script:
+        raise ValueError(
+            "no_agent=True requires a script — with no agent and no script "
+            "there is nothing for the job to run."
+        )
 
     # Normalize context_from: accept str or list of str, store as list or None
     if isinstance(context_from, str):
@@ -508,7 +532,7 @@ def create_job(
     else:
         context_from = None
 
-    label_source = (prompt or (normalized_skills[0] if normalized_skills else None)) or "cron job"
+    label_source = (prompt or (normalized_skills[0] if normalized_skills else None) or (normalized_script if normalized_no_agent else None)) or "cron job"
     job = {
         "id": job_id,
         "name": name or label_source[:50].strip(),
@@ -519,6 +543,7 @@ def create_job(
         "provider": normalized_provider,
         "base_url": normalized_base_url,
         "script": normalized_script,
+        "no_agent": normalized_no_agent,
         "context_from": context_from,
         "schedule": parsed_schedule,
         "schedule_display": parsed_schedule.get("display", schedule),
@@ -785,6 +810,12 @@ def get_due_jobs() -> List[Dict[str, Any]]:
     the job is fast-forwarded to the next future run instead of firing
     immediately.  This prevents a burst of missed jobs on gateway restart.
     """
+    with _jobs_file_lock:
+        return _get_due_jobs_locked()
+
+
+def _get_due_jobs_locked() -> List[Dict[str, Any]]:
+    """Inner implementation of get_due_jobs(); must be called with _jobs_file_lock held."""
     now = _hermes_now()
     raw_jobs = load_jobs()
     jobs = [_apply_skill_fields(j) for j in copy.deepcopy(raw_jobs)]
@@ -797,19 +828,36 @@ def get_due_jobs() -> List[Dict[str, Any]]:
 
         next_run = job.get("next_run_at")
         if not next_run:
+            schedule = job.get("schedule", {})
+            kind = schedule.get("kind")
+
+            # One-shot jobs use a small grace window via the dedicated helper.
             recovered_next = _recoverable_oneshot_run_at(
-                job.get("schedule", {}),
+                schedule,
                 now,
                 last_run_at=job.get("last_run_at"),
             )
+            recovery_kind = "one-shot" if recovered_next else None
+
+            # Recurring jobs reach here only when something — typically a
+            # direct jobs.json edit that bypassed add_job() — left
+            # next_run_at unset.  Without this branch, such jobs are
+            # silently skipped forever; recompute next_run_at from the
+            # schedule so they pick up at their next scheduled tick.
+            if not recovered_next and kind in ("cron", "interval"):
+                recovered_next = compute_next_run(schedule, now.isoformat())
+                if recovered_next:
+                    recovery_kind = kind
+
             if not recovered_next:
                 continue
 
             job["next_run_at"] = recovered_next
             next_run = recovered_next
             logger.info(
-                "Job '%s' had no next_run_at; recovering one-shot run at %s",
+                "Job '%s' had no next_run_at; recovering %s run at %s",
                 job.get("name", job["id"]),
+                recovery_kind,
                 recovered_next,
             )
             for rj in raw_jobs:

cron/scheduler.py

@@ -35,7 +35,7 @@ from typing import List, Optional
 sys.path.insert(0, str(Path(__file__).parent.parent))
 
 from hermes_constants import get_hermes_home
-from hermes_cli.config import load_config
+from hermes_cli.config import load_config, _expand_env_vars
 from hermes_time import now as _hermes_now
 
 logger = logging.getLogger(__name__)
@@ -123,9 +123,19 @@ _LOCK_FILE = _LOCK_DIR / ".tick.lock"
 
 
 def _resolve_origin(job: dict) -> Optional[dict]:
-    """Extract origin info from a job, preserving any extra routing metadata."""
+    """Extract origin info from a job, preserving any extra routing metadata.
+
+    Treats non-dict origins (free-form provenance strings, ints, lists from
+    migration scripts or hand-edited jobs.json) as missing instead of
+    crashing with ``AttributeError`` on ``origin.get(...)``. Without this
+    guard, a job tagged with e.g. ``"combined-digest-replaces-x-and-y"``
+    crashed every fire attempt with
+    ``'str' object has no attribute 'get'`` — ``mark_job_run`` recorded the
+    failure, but the next tick re-loaded the same poisoned origin and
+    crashed identically until the field was patched manually (#18722).
+    """
     origin = job.get("origin")
-    if not origin:
+    if not isinstance(origin, dict):
         return None
     platform = origin.get("platform")
     chat_id = origin.get("chat_id")
@@ -147,6 +157,19 @@ def _get_home_target_chat_id(platform_name: str) -> str:
     return value
 
 
+def _get_home_target_thread_id(platform_name: str) -> Optional[str]:
+    """Return the optional thread/topic ID for a platform home target."""
+    env_var = _HOME_TARGET_ENV_VARS.get(platform_name.lower())
+    if not env_var:
+        return None
+    value = os.getenv(f"{env_var}_THREAD_ID", "").strip()
+    if not value:
+        legacy = _LEGACY_HOME_TARGET_ENV_VARS.get(env_var)
+        if legacy:
+            value = os.getenv(f"{legacy}_THREAD_ID", "").strip()
+    return value or None
+
+
 def _resolve_single_delivery_target(job: dict, deliver_value: str) -> Optional[dict]:
     """Resolve one concrete auto-delivery target for a cron job."""
 
@@ -175,7 +198,7 @@ def _resolve_single_delivery_target(job: dict, deliver_value: str) -> Optional[d
                 return {
                     "platform": platform_name,
                     "chat_id": chat_id,
-                    "thread_id": None,
+                    "thread_id": _get_home_target_thread_id(platform_name),
                 }
         return None
 
@@ -229,7 +252,7 @@ def _resolve_single_delivery_target(job: dict, deliver_value: str) -> Optional[d
     return {
         "platform": platform_name,
         "chat_id": chat_id,
-        "thread_id": None,
+        "thread_id": _get_home_target_thread_id(platform_name),
     }
 
 
@@ -394,7 +417,7 @@ def _deliver_result(job: dict, content: str, adapters=None, loop=None) -> Option
         thread_id = target.get("thread_id")
 
         # Diagnostic: log thread_id for topic-aware delivery debugging
-        origin = job.get("origin") or {}
+        origin = _resolve_origin(job) or {}
         origin_thread = origin.get("thread_id")
         if origin_thread and not thread_id:
             logger.warning(
@@ -553,8 +576,18 @@ def _run_job_script(script_path: str) -> tuple[bool, str]:
     prevent arbitrary script execution via path traversal or absolute
     path injection.
 
+    Supported interpreters (chosen by file extension):
+
+    * ``.sh`` / ``.bash`` — run with ``/bin/bash``
+    * anything else — run with the current Python interpreter
+      (``sys.executable``), preserving the original behaviour for
+      Python-based pre-check and data-collection scripts.
+
+    Shell support lets ``no_agent=True`` jobs ship classic bash watchdogs
+    (the `memory-watchdog.sh` pattern) without wrapping them in Python.
+
     Args:
-        script_path: Path to a Python script.  Relative paths are resolved
+        script_path: Path to the script.  Relative paths are resolved
             against HERMES_HOME/scripts/.  Absolute and ~-prefixed paths
             are also validated to ensure they stay within the scripts dir.
 
@@ -591,9 +624,19 @@ def _run_job_script(script_path: str) -> tuple[bool, str]:
 
     script_timeout = _get_script_timeout()
 
+    # Pick an interpreter by extension.  Bash for .sh/.bash, Python for
+    # everything else.  We deliberately do NOT honour the file's own
+    # shebang: the scripts dir is trusted, but keeping the interpreter
+    # choice explicit here keeps the allowed surface small and auditable.
+    suffix = path.suffix.lower()
+    if suffix in (".sh", ".bash"):
+        argv = ["/bin/bash", str(path)]
+    else:
+        argv = [sys.executable, str(path)]
+
     try:
         result = subprocess.run(
-            [sys.executable, str(path)],
+            argv,
             capture_output=True,
             text=True,
             timeout=script_timeout,
@@ -683,10 +726,8 @@ def _build_job_prompt(job: dict, prerun_script: Optional[tuple] = None) -> str:
                     f"{prompt}"
                 )
             else:
-                prompt = (
-                    "[Script ran successfully but produced no output.]\n\n"
-                    f"{prompt}"
-                )
+                # Script produced no output — nothing to report, skip AI call.
+                return None
         else:
             prompt = (
                 "## Script Error\n"
@@ -759,6 +800,7 @@ def _build_job_prompt(job: dict, prerun_script: Optional[tuple] = None) -> str:
         return prompt
 
     from tools.skills_tool import skill_view
+    from tools.skill_usage import bump_use
 
     parts = []
     skipped: list[str] = []
@@ -770,6 +812,12 @@ def _build_job_prompt(job: dict, prerun_script: Optional[tuple] = None) -> str:
             skipped.append(skill_name)
             continue
 
+        # Bump usage so the curator sees this skill as actively used.
+        try:
+            bump_use(skill_name)
+        except Exception:
+            logger.debug("Cron job: failed to bump skill usage for '%s'", skill_name, exc_info=True)
+
         content = str(loaded.get("content") or "").strip()
         if parts:
             parts.append("")
@@ -802,8 +850,120 @@ def run_job(job: dict) -> tuple[bool, str, str, Optional[str]]:
     Returns:
         Tuple of (success, full_output_doc, final_response, error_message)
     """
+    job_id = job["id"]
+    job_name = job["name"]
+
+    # ---------------------------------------------------------------
+    # no_agent short-circuit — the script IS the job, no LLM involvement.
+    # ---------------------------------------------------------------
+    # This mirrors the classic "run a bash script on a timer, send its
+    # stdout to telegram" watchdog pattern. The agent path is skipped
+    # entirely: no AIAgent, no prompt, no tool loop, no token spend.
+    #
+    # We check this BEFORE importing run_agent / constructing SessionDB so
+    # a pure-script tick never pays for the agent machinery it isn't going
+    # to use. Keep this block self-contained.
+    #
+    # Semantics:
+    #   - script stdout (trimmed) → delivered verbatim as the final message
+    #   - empty stdout            → silent run (no delivery, success=True)
+    #   - non-zero exit / timeout → delivered as an error alert, success=False
+    #   - wakeAgent=false gate    → treated like empty stdout (silent), since
+    #                               the whole point of no_agent is that there
+    #                               is no agent to wake
+    if job.get("no_agent"):
+        script_path = job.get("script")
+        if not script_path:
+            err = "no_agent=True but no script is set for this job"
+            logger.error("Job '%s': %s", job_id, err)
+            return False, "", "", err
+
+        # Apply workdir if configured — lets scripts use predictable relative
+        # paths. For no_agent jobs this is just the subprocess cwd (not an
+        # agent TERMINAL_CWD bridge).
+        _job_workdir = (job.get("workdir") or "").strip() or None
+        _prior_cwd = None
+        if _job_workdir and Path(_job_workdir).is_dir():
+            _prior_cwd = os.getcwd()
+            try:
+                os.chdir(_job_workdir)
+            except OSError:
+                _prior_cwd = None
+
+        try:
+            ok, output = _run_job_script(script_path)
+        finally:
+            if _prior_cwd is not None:
+                try:
+                    os.chdir(_prior_cwd)
+                except OSError:
+                    pass
+
+        now_iso = _hermes_now().strftime("%Y-%m-%d %H:%M:%S")
+
+        if not ok:
+            # Script crashed / timed out / exited non-zero.  Deliver the
+            # error so the user knows the watchdog itself broke — silent
+            # failure for an alerting job is the worst-case outcome.
+            alert = (
+                f"⚠ Cron watchdog '{job_name}' script failed\n\n"
+                f"{output}\n\n"
+                f"Time: {now_iso}"
+            )
+            doc = (
+                f"# Cron Job: {job_name}\n\n"
+                f"**Job ID:** {job_id}\n"
+                f"**Run Time:** {now_iso}\n"
+                f"**Mode:** no_agent (script)\n"
+                f"**Status:** script failed\n\n"
+                f"{output}\n"
+            )
+            return False, doc, alert, output
+
+        # Honour the wakeAgent gate as a silent signal — `wakeAgent: false`
+        # means "nothing to report this tick", same as empty stdout.
+        if not _parse_wake_gate(output):
+            logger.info(
+                "Job '%s' (no_agent): wakeAgent=false gate — silent run", job_id
+            )
+            silent_doc = (
+                f"# Cron Job: {job_name}\n\n"
+                f"**Job ID:** {job_id}\n"
+                f"**Run Time:** {now_iso}\n"
+                f"**Mode:** no_agent (script)\n"
+                f"**Status:** silent (wakeAgent=false)\n"
+            )
+            return True, silent_doc, SILENT_MARKER, None
+
+        if not output.strip():
+            logger.info("Job '%s' (no_agent): empty stdout — silent run", job_id)
+            silent_doc = (
+                f"# Cron Job: {job_name}\n\n"
+                f"**Job ID:** {job_id}\n"
+                f"**Run Time:** {now_iso}\n"
+                f"**Mode:** no_agent (script)\n"
+                f"**Status:** silent (empty output)\n"
+            )
+            return True, silent_doc, SILENT_MARKER, None
+
+        doc = (
+            f"# Cron Job: {job_name}\n\n"
+            f"**Job ID:** {job_id}\n"
+            f"**Run Time:** {now_iso}\n"
+            f"**Mode:** no_agent (script)\n\n"
+            f"---\n\n"
+            f"{output}\n"
+        )
+        return True, doc, output, None
+
+    # ---------------------------------------------------------------
+    # Default (LLM) path — import and construct the agent machinery now
+    # that we know we actually need it. Doing these imports here instead of
+    # at module top keeps no_agent ticks from paying for AIAgent / SessionDB
+    # construction costs.
+    # ---------------------------------------------------------------
     from run_agent import AIAgent
-    
+
     # Initialize SQLite session store so cron job messages are persisted
     # and discoverable via session_search (same pattern as gateway/run.py).
     _session_db = None
@@ -812,9 +972,6 @@ def run_job(job: dict) -> tuple[bool, str, str, Optional[str]]:
         _session_db = SessionDB()
     except Exception as e:
         logger.debug("Job '%s': SQLite session store not available: %s", job.get("id", "?"), e)
-    
-    job_id = job["id"]
-    job_name = job["name"]
 
     # Wake-gate: if this job has a pre-check script, run it BEFORE building
     # the prompt so a ``{"wakeAgent": false}`` response can short-circuit
@@ -839,6 +996,9 @@ def run_job(job: dict) -> tuple[bool, str, str, Optional[str]]:
             return True, silent_doc, SILENT_MARKER, None
 
     prompt = _build_job_prompt(job, prerun_script=prerun_script)
+    if prompt is None:
+        logger.info("Job '%s': script produced no output, skipping AI call.", job_name)
+        return True, "", SILENT_MARKER, None
     origin = _resolve_origin(job)
     _cron_session_id = f"cron_{job_id}_{_hermes_now().strftime('%Y%m%d_%H%M%S')}"
 
@@ -922,6 +1082,7 @@ def run_job(job: dict) -> tuple[bool, str, str, Optional[str]]:
             if os.path.exists(_cfg_path):
                 with open(_cfg_path) as _f:
                     _cfg = yaml.safe_load(_f) or {}
+                _cfg = _expand_env_vars(_cfg)
                 _model_cfg = _cfg.get("model", {})
                 if not job.get("model"):
                     if isinstance(_model_cfg, str):
@@ -974,8 +1135,13 @@ def run_job(job: dict) -> tuple[bool, str, str, Optional[str]]:
         )
         from hermes_cli.auth import AuthError
         try:
+            # Do not inject HERMES_INFERENCE_PROVIDER here. resolve_runtime_provider()
+            # already prefers persisted config over stale shell/env overrides when
+            # no explicit provider is requested. Passing the env var here short-
+            # circuits that precedence and can resurrect old providers (for
+            # example DeepSeek) for cron jobs that do not pin provider/model.
             runtime_kwargs = {
-                "requested": job.get("provider") or os.getenv("HERMES_INFERENCE_PROVIDER"),
+                "requested": job.get("provider"),
             }
             if job.get("base_url"):
                 runtime_kwargs["explicit_base_url"] = job.get("base_url")

docker/entrypoint.sh

@@ -86,6 +86,41 @@ if [ -d "$INSTALL_DIR/skills" ]; then
     python3 "$INSTALL_DIR/tools/skills_sync.py"
 fi
 
+# Optionally start `hermes dashboard` as a side-process.
+#
+# Toggled by HERMES_DASHBOARD=1 (also accepts "true"/"yes", case-insensitive).
+# Host/port/TUI can be overridden via:
+#   HERMES_DASHBOARD_HOST  (default 0.0.0.0 — exposed outside the container)
+#   HERMES_DASHBOARD_PORT  (default 9119, matches `hermes dashboard` default)
+#   HERMES_DASHBOARD_TUI   (already honored by `hermes dashboard` itself)
+#
+# The dashboard is a long-lived server.  We background it *before* the final
+# `exec hermes "$@"` so the user's chosen foreground command (chat, gateway,
+# sleep infinity, …) remains PID-of-interest for the container runtime.  When
+# the container stops the whole process tree is torn down, so no explicit
+# cleanup is needed.
+case "${HERMES_DASHBOARD:-}" in
+    1|true|TRUE|True|yes|YES|Yes)
+        dash_host="${HERMES_DASHBOARD_HOST:-0.0.0.0}"
+        dash_port="${HERMES_DASHBOARD_PORT:-9119}"
+        dash_args=(--host "$dash_host" --port "$dash_port" --no-open)
+        # Binding to anything other than localhost requires --insecure — the
+        # dashboard refuses otherwise because it exposes API keys.  Inside a
+        # container this is the expected deployment (host reaches it via
+        # published port), so opt in automatically.
+        if [ "$dash_host" != "127.0.0.1" ] && [ "$dash_host" != "localhost" ]; then
+            dash_args+=(--insecure)
+        fi
+        echo "Starting hermes dashboard on ${dash_host}:${dash_port} (background)"
+        # Prefix dashboard output so it's distinguishable from the main
+        # process in `docker logs`.  stdbuf keeps the pipe line-buffered.
+        (
+            stdbuf -oL -eL hermes dashboard "${dash_args[@]}" 2>&1 \
+                | sed -u 's/^/[dashboard] /'
+        ) &
+        ;;
+esac
+
 # Final exec: two supported invocation patterns.
 #
 #   docker run <image>                 -> exec `hermes` with no args (legacy default)

docs/plans/2026-05-02-telegram-dm-user-managed-multisession-topics.md

@@ -0,0 +1,473 @@
+# Telegram DM User-Managed Multi-Session Topics Implementation Plan
+
+> **For Hermes:** Use test-driven-development for implementation. Use subagent-driven-development only after this plan is split into small reviewed tasks.
+
+**Goal:** Add an opt-in Telegram DM multi-session mode where Telegram user-created private-chat topics become independent Hermes session lanes, while the root DM becomes a system lobby.
+
+**Architecture:** Rely on Telegram's native private-chat topic UI. Users create new topics with the `+` button; Hermes maps each `message_thread_id` to a separate session lane. Hermes does not create topics for normal `/new` flow and does not try to manage topic lifecycle beyond activation/status, root-lobby behavior, and restoring legacy sessions into a user-created topic.
+
+**Tech Stack:** Hermes gateway, Telegram Bot API 9.4+, python-telegram-bot adapter, SQLite SessionDB / side tables, pytest.
+
+---
+
+## 1. Product decisions
+
+### Accepted
+
+- PR-quality implementation: migrations, tests, docs, backwards compatibility.
+- Use SQLite persistence, not JSON sidecars.
+- Live status suffixes in topic titles are out of MVP.
+- Topic title sync/editing is out of MVP except future-compatible storage if cheap.
+- User creates Telegram topics manually through the Telegram bot interface.
+- `/new` does **not** create Telegram topics.
+- Root/main DM becomes a system lobby after activation.
+- Existing Telegram behavior remains unchanged until the feature is activated/enabled.
+- Migration of old sessions is supported through `/topic` listing and `/topic <session_id>` restore inside a user-created topic.
+
+### Telegram API assumptions verified from Bot API docs
+
+- `getMe` returns bot `User` fields:
+  - `has_topics_enabled`: forum/topic mode enabled in private chats.
+  - `allows_users_to_create_topics`: users may create/delete topics in private chats.
+- `createForumTopic` works for private chats with a user, but MVP does not rely on it for normal flow.
+- `Message.message_thread_id` identifies a topic in private chats.
+- `sendMessage` supports `message_thread_id` for private-chat topics.
+- `pinChatMessage` is allowed in private chats.
+
+---
+
+## 2. Target UX
+
+### 2.1 Activation from root/main DM
+
+User sends:
+
+```text
+/topic
+```
+
+Hermes:
+
+1. calls Telegram `getMe`;
+2. verifies `has_topics_enabled` and `allows_users_to_create_topics`;
+3. enables multi-session topic mode for this Telegram DM user/chat;
+4. sends an onboarding message;
+5. pins the onboarding message if configured;
+6. shows old/unlinked sessions that can be restored into topics.
+
+Suggested onboarding text:
+
+```text
+Multi-session mode is enabled.
+
+Create new Hermes chats with the + button in this bot interface. Each Telegram topic is an independent Hermes session, so you can work on different tasks in parallel.
+
+This main chat is reserved for system commands, status, and session management.
+
+To restore an old session:
+1. Use /topic here to see unlinked sessions.
+2. Create a new topic with the + button.
+3. Send /topic <session_id> inside that topic.
+```
+
+### 2.2 Root/main DM after activation
+
+Root DM is a system lobby.
+
+Allowed/system commands include at least:
+
+- `/topic`
+- `/status`
+- `/sessions` if available
+- `/usage`
+- `/help`
+- `/platforms`
+
+Normal user prompts in root DM do not enter the agent loop. Reply:
+
+```text
+This main chat is reserved for system commands.
+
+To chat with Hermes, create a new topic using the + button in this bot interface. Each topic works as an independent Hermes session.
+```
+
+`/new` in root DM does not create a session/topic. Reply:
+
+```text
+To start a new parallel Hermes chat, create a new topic with the + button in this bot interface.
+
+Each topic is an independent Hermes session. Use /new inside a topic only if you want to replace that topic's current session.
+```
+
+### 2.3 First message in a user-created topic
+
+When a user creates a Telegram topic and sends the first message there:
+
+1. Hermes receives a Telegram DM message with `message_thread_id`.
+2. Hermes derives the existing thread-aware `session_key` from `(platform=telegram, chat_type=dm, chat_id, thread_id)`.
+3. If no binding exists, Hermes creates a fresh Hermes session for this topic lane and persists the binding.
+4. The message runs through the normal agent loop for that lane.
+
+### 2.4 `/new` inside a non-main topic
+
+`/new` remains supported but replaces the session attached to the current topic lane.
+
+Hermes should warn:
+
+```text
+Started a new Hermes session in this topic.
+
+Tip: for parallel work, create a new topic with the + button instead of using /new here. /new replaces the session attached to the current topic.
+```
+
+### 2.5 `/topic` in root/main DM after activation
+
+Shows:
+
+- mode enabled/disabled;
+- last capability check result;
+- whether intro message is pinned if known;
+- count of known topic bindings;
+- list of old/unlinked sessions.
+
+Example:
+
+```text
+Telegram multi-session topics are enabled.
+
+Create new Hermes chats with the + button in this bot interface.
+
+Unlinked previous sessions:
+1. 2026-05-01 Research notes — id: abc123
+2. 2026-04-30 Deploy debugging — id: def456
+3. Untitled session — id: ghi789
+
+To restore one:
+1. Create a new topic with the + button.
+2. Open that topic.
+3. Send /topic <id>
+```
+
+### 2.6 `/topic` inside a non-main topic
+
+Without args, show the current topic binding:
+
+```text
+This topic is linked to:
+Session: Research notes
+ID: abc123
+
+Use /new to replace this topic with a fresh session.
+For parallel work, create another topic with the + button.
+```
+
+### 2.7 `/topic <session_id>` inside a non-main topic
+
+Restore an old/unlinked session into the current user-created topic.
+
+Behavior:
+
+1. reject if not in Telegram DM topic;
+2. verify session belongs to the same Telegram user/chat or is a safe legacy root DM session for this user;
+3. reject if session is already linked to another active topic in MVP;
+4. `SessionStore.switch_session(current_topic_session_key, target_session_id)`;
+5. upsert binding with `managed_mode = restored`;
+6. send two messages into the topic:
+   - session restored confirmation;
+   - last Hermes assistant message if available.
+
+Example:
+
+```text
+Session restored: Research notes
+
+Last Hermes message:
+...
+```
+
+---
+
+## 3. Persistence model
+
+Use SQLite, but topic-mode schema changes are **explicit opt-in migrations**, not automatic startup reconciliation.
+
+Important rollback-safety rule:
+
+- upgrading Hermes and starting the gateway must not create Telegram topic-mode tables or columns;
+- old/default Telegram behavior must keep working on the existing `state.db`;
+- the first `/topic` activation path calls an idempotent explicit migration, then enables topic mode for that chat;
+- if activation fails before the migration is needed, the database remains in the pre-topic-mode shape.
+
+### 3.1 No eager `sessions` table mutation for MVP
+
+Do **not** add `chat_id`, `chat_type`, `thread_id`, or `session_key` columns to `sessions` as part of ordinary `SessionDB()` startup. The existing declarative `_reconcile_columns()` mechanism would add them eagerly on every process start, which violates the managed-migration requirement.
+
+For MVP, keep origin/session-lane data in topic-specific side tables created only by the explicit `/topic` migration. Legacy unlinked sessions can be discovered conservatively from existing data (`source = telegram`, `user_id = current Telegram user`) plus absence from topic bindings.
+
+If future PRs need richer origin metadata for all gateway sessions, introduce it behind a separate explicit migration/command or a compatibility-reviewed schema bump.
+
+### 3.2 Explicit `/topic` migration API
+
+Add an idempotent method such as:
+
+```python
+def apply_telegram_topic_migration(self) -> None: ...
+```
+
+It creates only topic-mode side tables/indexes and records:
+
+```text
+state_meta.telegram_dm_topic_schema_version = 1
+```
+
+This method is called from `/topic` activation/status paths before reading or writing topic-mode state. It is not called from generic `SessionDB.__init__`, gateway startup, CLI startup, or auto-maintenance.
+
+### 3.3 `telegram_dm_topic_mode`
+
+Stores per-user/chat activation state. Created only by `apply_telegram_topic_migration()`.
+
+Suggested fields:
+
+- `chat_id` primary key
+- `user_id`
+- `enabled`
+- `activated_at`
+- `updated_at`
+- `has_topics_enabled`
+- `allows_users_to_create_topics`
+- `capability_checked_at`
+- `intro_message_id`
+- `pinned_message_id`
+
+### 3.4 `telegram_dm_topic_bindings`
+
+Stores Telegram topic/thread to Hermes session binding. Created only by `apply_telegram_topic_migration()`.
+
+Suggested fields:
+
+- `chat_id`
+- `thread_id`
+- `user_id`
+- `session_key`
+- `session_id`
+- `managed_mode`
+  - `auto`
+  - `restored`
+  - `new_replaced`
+- `linked_at`
+- `updated_at`
+
+Recommended constraints:
+
+- primary key `(chat_id, thread_id)`;
+- unique index on `session_id` for MVP to prevent one session linked to multiple topics;
+- index `(user_id, chat_id)` for status/listing.
+
+### 3.5 Unlinked session semantics
+
+For MVP, a session is unlinked if:
+
+- `source = telegram`;
+- `user_id = current Telegram user`;
+- no row in `telegram_dm_topic_bindings` has `session_id = session_id`.
+
+This is intentionally conservative until a future explicit migration adds richer cross-platform origin metadata.
+
+Never dedupe by title.
+
+---
+
+## 4. Config
+
+Suggested config block:
+
+```yaml
+platforms:
+  telegram:
+    extra:
+      multisession_topics:
+        enabled: false
+        mode: user_managed_topics
+        root_chat_behavior: system_lobby
+        pin_intro_message: true
+```
+
+Notes:
+
+- `enabled: false` means existing Telegram behavior is unchanged.
+- Activation via `/topic` may create per-chat enabled state only if global config permits it.
+- `root_chat_behavior: system_lobby` is the MVP behavior for activated chats.
+
+---
+
+## 5. Command behavior summary
+
+### `/topic` root/main DM
+
+- If not activated: capability check, activate, send/pin onboarding, list unlinked sessions.
+- If activated: show status and unlinked sessions.
+
+### `/topic` non-main topic
+
+- Show current binding.
+
+### `/topic <session_id>` root/main DM
+
+Reject with instructions:
+
+```text
+Create a new topic with the + button, open it, then send /topic <session_id> there to restore this session.
+```
+
+### `/topic <session_id>` non-main topic
+
+Restore that session into this topic if ownership/linking checks pass.
+
+### `/new` root/main DM when activated
+
+Reply with instructions to use the `+` button. Do not enter agent loop.
+
+### `/new` non-main topic
+
+Create a new session in the current topic lane, persist/update binding, warn that `+` is preferred for parallel work.
+
+### Normal text root/main DM when activated
+
+Reply with system-lobby instruction. Do not enter agent loop.
+
+### Normal text non-main topic
+
+Normal Hermes agent flow for that topic's session lane.
+
+---
+
+## 6. PR breakdown
+
+### PR 1 — Explicit topic-mode schema migration
+
+**Goal:** Add rollback-safe SQLite support for Telegram topic mode without mutating `state.db` on ordinary upgrade/startup.
+
+**Files likely touched:**
+
+- `hermes_state.py`
+- tests under `tests/`
+
+**Tests first:**
+
+1. opening an old/current DB with `SessionDB()` does not create topic-mode tables or `sessions` origin columns;
+2. calling `apply_telegram_topic_migration()` creates `telegram_dm_topic_mode` and `telegram_dm_topic_bindings` idempotently;
+3. migration records `state_meta.telegram_dm_topic_schema_version = 1`.
+
+### PR 2 — Topic mode activation and binding APIs
+
+**Goal:** Add SQLite persistence for activation and topic bindings.
+
+**Tests first:**
+
+1. enable/check mode row round-trips;
+2. binding upsert and lookup by `(chat_id, user_id, thread_id)`;
+3. linked sessions are excluded from unlinked list.
+
+### PR 3 — `/topic` activation/status command
+
+**Goal:** Implement root activation/status/listing behavior.
+
+**Tests first:**
+
+1. `/topic` in root checks `getMe` capabilities and records activation;
+2. capability failure returns readable instructions;
+3. activated root `/topic` lists unlinked sessions.
+
+### PR 4 — System lobby behavior
+
+**Goal:** Prevent root chat from entering agent loop after activation.
+
+**Tests first:**
+
+1. normal text in activated root returns lobby instruction;
+2. `/new` in activated root returns `+` button instruction;
+3. non-activated root behavior is unchanged.
+
+### PR 5 — Auto-bind user-created topics
+
+**Goal:** First message in non-main topic creates/uses an independent session lane.
+
+**Tests first:**
+
+1. new topic message creates binding with `auto_created`;
+2. repeated topic message reuses same binding/lane;
+3. two topics in same DM do not share sessions.
+
+### PR 6 — Restore legacy sessions into a topic
+
+**Goal:** Implement `/topic <session_id>` in non-main topics.
+
+**Tests first:**
+
+1. root `/topic <id>` rejects with instructions;
+2. topic `/topic <id>` switches current topic lane to target session;
+3. restore rejects sessions from other users/chats;
+4. restore rejects already-linked sessions;
+5. restore emits confirmation and last Hermes assistant message.
+
+### PR 7 — `/new` inside topic updates binding
+
+**Goal:** Keep existing `/new` semantics but persist topic binding replacement.
+
+**Tests first:**
+
+1. `/new` in topic creates a new session for same topic lane;
+2. binding updates to `managed_mode = new_replaced`;
+3. response includes guidance to use `+` for parallel work.
+
+### PR 8 — Docs and polish
+
+**Goal:** Document the feature and Telegram setup.
+
+**Files likely touched:**
+
+- `website/docs/user-guide/messaging/telegram.md`
+- maybe `website/docs/user-guide/sessions.md`
+
+Docs must explain:
+
+- BotFather/Telegram settings for topic mode and user-created topics;
+- `/topic` activation;
+- root system lobby;
+- using `+` for new parallel chats;
+- restoring old sessions with `/topic <id>` inside a topic;
+- limitations.
+
+---
+
+## 7. Testing / quality gates
+
+Run targeted tests after each TDD cycle, then broader tests before completion.
+
+Suggested commands after inspection confirms test paths:
+
+```bash
+python -m pytest tests/test_hermes_state.py -q
+python -m pytest tests/gateway/ -q
+python -m pytest tests/ -o 'addopts=' -q
+```
+
+Do not ship without verifying disabled-feature backwards compatibility.
+
+---
+
+## 8. Definition of done for MVP
+
+- `/topic` activates/checks Telegram DM multi-session mode.
+- Root DM becomes a system lobby after activation.
+- Onboarding message tells users to create new chats with the Telegram `+` button.
+- Onboarding message can be pinned in private chat.
+- User-created topics automatically become independent Hermes session lanes.
+- `/new` in root gives instructions, not a new agent run.
+- `/new` in a topic creates a new session in that topic and warns that `+` is preferred for parallel work.
+- `/topic` in root lists unlinked old sessions.
+- `/topic <session_id>` inside a topic restores that session and sends confirmation + last Hermes assistant message.
+- Ownership checks prevent restoring other users' sessions.
+- Already-linked sessions are not restored into a second topic in MVP.
+- Existing Telegram behavior is unchanged when the feature is disabled.
+- Tests and docs are included.

gateway/config.py

@@ -186,18 +186,24 @@ class HomeChannel:
     Default destination for a platform.
     
     When a cron job specifies deliver="telegram" without a specific chat ID,
-    messages are sent to this home channel.
+    messages are sent to this home channel. Thread-aware platforms may also
+    store a thread/topic ID so the bare platform target routes to the exact
+    conversation where /sethome was run.
     """
     platform: Platform
     chat_id: str
     name: str  # Human-readable name for display
+    thread_id: Optional[str] = None
     
     def to_dict(self) -> Dict[str, Any]:
-        return {
+        result = {
             "platform": self.platform.value,
             "chat_id": self.chat_id,
             "name": self.name,
         }
+        if self.thread_id:
+            result["thread_id"] = self.thread_id
+        return result
     
     @classmethod
     def from_dict(cls, data: Dict[str, Any]) -> "HomeChannel":
@@ -205,6 +211,7 @@ class HomeChannel:
             platform=Platform(data["platform"]),
             chat_id=str(data["chat_id"]),
             name=data.get("name", "Home"),
+            thread_id=str(data["thread_id"]) if data.get("thread_id") else None,
         )
 
 
@@ -839,11 +846,25 @@ def load_gateway_config() -> GatewayConfig:
                         if yaml_key in allow_mentions_cfg and not os.getenv(env_key):
                             os.environ[env_key] = str(allow_mentions_cfg[yaml_key]).lower()
 
+            # Bridge top-level require_mention to Telegram when the telegram: section
+            # does not already provide one.  Users often write "require_mention: true"
+            # at the top level alongside group_sessions_per_user, expecting it to work
+            # the same way (#3979).
+            _tl_require_mention = yaml_cfg.get("require_mention")
+            if _tl_require_mention is not None:
+                _tg_section = yaml_cfg.get("telegram") or {}
+                if "require_mention" not in _tg_section:
+                    _tg_plat = platforms_data.setdefault(Platform.TELEGRAM.value, {})
+                    _tg_extra = _tg_plat.setdefault("extra", {})
+                    _tg_extra.setdefault("require_mention", _tl_require_mention)
+
             # Telegram settings → env vars (env vars take precedence)
             telegram_cfg = yaml_cfg.get("telegram", {})
             if isinstance(telegram_cfg, dict):
-                if "require_mention" in telegram_cfg and not os.getenv("TELEGRAM_REQUIRE_MENTION"):
-                    os.environ["TELEGRAM_REQUIRE_MENTION"] = str(telegram_cfg["require_mention"]).lower()
+                # Prefer telegram.require_mention; fall back to the top-level shorthand.
+                _effective_rm = telegram_cfg.get("require_mention", yaml_cfg.get("require_mention"))
+                if _effective_rm is not None and not os.getenv("TELEGRAM_REQUIRE_MENTION"):
+                    os.environ["TELEGRAM_REQUIRE_MENTION"] = str(_effective_rm).lower()
                 if "mention_patterns" in telegram_cfg and not os.getenv("TELEGRAM_MENTION_PATTERNS"):
                     os.environ["TELEGRAM_MENTION_PATTERNS"] = json.dumps(telegram_cfg["mention_patterns"])
                 frc = telegram_cfg.get("free_response_chats")
@@ -1071,6 +1092,7 @@ def _apply_env_overrides(config: GatewayConfig) -> None:
             platform=Platform.TELEGRAM,
             chat_id=telegram_home,
             name=os.getenv("TELEGRAM_HOME_CHANNEL_NAME", "Home"),
+            thread_id=os.getenv("TELEGRAM_HOME_CHANNEL_THREAD_ID") or None,
         )
     
     # Discord
@@ -1087,6 +1109,7 @@ def _apply_env_overrides(config: GatewayConfig) -> None:
             platform=Platform.DISCORD,
             chat_id=discord_home,
             name=os.getenv("DISCORD_HOME_CHANNEL_NAME", "Home"),
+            thread_id=os.getenv("DISCORD_HOME_CHANNEL_THREAD_ID") or None,
         )
     
     # Reply threading mode for Discord (off/first/all)
@@ -1108,6 +1131,7 @@ def _apply_env_overrides(config: GatewayConfig) -> None:
             platform=Platform.WHATSAPP,
             chat_id=whatsapp_home,
             name=os.getenv("WHATSAPP_HOME_CHANNEL_NAME", "Home"),
+            thread_id=os.getenv("WHATSAPP_HOME_CHANNEL_THREAD_ID") or None,
         )
 
     # Slack
@@ -1135,6 +1159,7 @@ def _apply_env_overrides(config: GatewayConfig) -> None:
             platform=Platform.SLACK,
             chat_id=slack_home,
             name=os.getenv("SLACK_HOME_CHANNEL_NAME", ""),
+            thread_id=os.getenv("SLACK_HOME_CHANNEL_THREAD_ID") or None,
         )
     
     # Signal
@@ -1155,6 +1180,7 @@ def _apply_env_overrides(config: GatewayConfig) -> None:
             platform=Platform.SIGNAL,
             chat_id=signal_home,
             name=os.getenv("SIGNAL_HOME_CHANNEL_NAME", "Home"),
+            thread_id=os.getenv("SIGNAL_HOME_CHANNEL_THREAD_ID") or None,
         )
 
     # Mattermost
@@ -1174,6 +1200,7 @@ def _apply_env_overrides(config: GatewayConfig) -> None:
             platform=Platform.MATTERMOST,
             chat_id=mattermost_home,
             name=os.getenv("MATTERMOST_HOME_CHANNEL_NAME", "Home"),
+            thread_id=os.getenv("MATTERMOST_HOME_CHANNEL_THREAD_ID") or None,
         )
 
     # Matrix
@@ -1205,6 +1232,7 @@ def _apply_env_overrides(config: GatewayConfig) -> None:
             platform=Platform.MATRIX,
             chat_id=matrix_home,
             name=os.getenv("MATRIX_HOME_ROOM_NAME", "Home"),
+            thread_id=os.getenv("MATRIX_HOME_ROOM_THREAD_ID") or None,
         )
 
     # Home Assistant
@@ -1238,6 +1266,7 @@ def _apply_env_overrides(config: GatewayConfig) -> None:
             platform=Platform.EMAIL,
             chat_id=email_home,
             name=os.getenv("EMAIL_HOME_ADDRESS_NAME", "Home"),
+            thread_id=os.getenv("EMAIL_HOME_ADDRESS_THREAD_ID") or None,
         )
 
     # SMS (Twilio)
@@ -1253,6 +1282,7 @@ def _apply_env_overrides(config: GatewayConfig) -> None:
             platform=Platform.SMS,
             chat_id=sms_home,
             name=os.getenv("SMS_HOME_CHANNEL_NAME", "Home"),
+            thread_id=os.getenv("SMS_HOME_CHANNEL_THREAD_ID") or None,
         )
 
     # API Server
@@ -1315,6 +1345,7 @@ def _apply_env_overrides(config: GatewayConfig) -> None:
                 platform=Platform.DINGTALK,
                 chat_id=dingtalk_home,
                 name=os.getenv("DINGTALK_HOME_CHANNEL_NAME", "Home"),
+                thread_id=os.getenv("DINGTALK_HOME_CHANNEL_THREAD_ID") or None,
             )
 
     # Feishu / Lark
@@ -1342,6 +1373,7 @@ def _apply_env_overrides(config: GatewayConfig) -> None:
                 platform=Platform.FEISHU,
                 chat_id=feishu_home,
                 name=os.getenv("FEISHU_HOME_CHANNEL_NAME", "Home"),
+                thread_id=os.getenv("FEISHU_HOME_CHANNEL_THREAD_ID") or None,
             )
 
     # WeCom (Enterprise WeChat)
@@ -1364,6 +1396,7 @@ def _apply_env_overrides(config: GatewayConfig) -> None:
                 platform=Platform.WECOM,
                 chat_id=wecom_home,
                 name=os.getenv("WECOM_HOME_CHANNEL_NAME", "Home"),
+                thread_id=os.getenv("WECOM_HOME_CHANNEL_THREAD_ID") or None,
             )
 
     # WeCom callback mode (self-built apps)
@@ -1422,6 +1455,7 @@ def _apply_env_overrides(config: GatewayConfig) -> None:
                 platform=Platform.WEIXIN,
                 chat_id=weixin_home,
                 name=os.getenv("WEIXIN_HOME_CHANNEL_NAME", "Home"),
+                thread_id=os.getenv("WEIXIN_HOME_CHANNEL_THREAD_ID") or None,
             )
 
     # BlueBubbles (iMessage)
@@ -1445,6 +1479,7 @@ def _apply_env_overrides(config: GatewayConfig) -> None:
             platform=Platform.BLUEBUBBLES,
             chat_id=bluebubbles_home,
             name=os.getenv("BLUEBUBBLES_HOME_CHANNEL_NAME", "Home"),
+            thread_id=os.getenv("BLUEBUBBLES_HOME_CHANNEL_THREAD_ID") or None,
         )
 
     # QQ (Official Bot API v2)
@@ -1482,6 +1517,11 @@ def _apply_env_overrides(config: GatewayConfig) -> None:
                 platform=Platform.QQBOT,
                 chat_id=qq_home,
                 name=os.getenv("QQBOT_HOME_CHANNEL_NAME") or os.getenv(qq_home_name_env, "Home"),
+                thread_id=(
+                    os.getenv("QQBOT_HOME_CHANNEL_THREAD_ID")
+                    or os.getenv("QQ_HOME_CHANNEL_THREAD_ID")
+                    or None
+                ),
             )
 
     # Yuanbao — YUANBAO_APP_ID preferred
@@ -1512,6 +1552,7 @@ def _apply_env_overrides(config: GatewayConfig) -> None:
                 platform=Platform.YUANBAO,
                 chat_id=yuanbao_home,
                 name=os.getenv("YUANBAO_HOME_CHANNEL_NAME", "Home"),
+                thread_id=os.getenv("YUANBAO_HOME_CHANNEL_THREAD_ID") or None,
             )
         yuanbao_dm_policy = os.getenv("YUANBAO_DM_POLICY")
         if yuanbao_dm_policy:

gateway/platforms/api_server.py

@@ -62,6 +62,14 @@ MAX_NORMALIZED_TEXT_LENGTH = 65_536  # 64 KB cap for normalized content parts
 MAX_CONTENT_LIST_SIZE = 1_000  # Max items when content is an array
 
 
+def _coerce_port(value: Any, default: int = DEFAULT_PORT) -> int:
+    """Parse a listen port without letting malformed env/config values crash startup."""
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return default
+
+
 def _normalize_chat_content(
     content: Any, *, _max_depth: int = 10, _depth: int = 0,
 ) -> str:
@@ -573,7 +581,10 @@ class APIServerAdapter(BasePlatformAdapter):
         super().__init__(config, Platform.API_SERVER)
         extra = config.extra or {}
         self._host: str = extra.get("host", os.getenv("API_SERVER_HOST", DEFAULT_HOST))
-        self._port: int = int(extra.get("port", os.getenv("API_SERVER_PORT", str(DEFAULT_PORT))))
+        raw_port = extra.get("port")
+        if raw_port is None:
+            raw_port = os.getenv("API_SERVER_PORT", str(DEFAULT_PORT))
+        self._port: int = _coerce_port(raw_port, DEFAULT_PORT)
         self._api_key: str = extra.get("key", os.getenv("API_SERVER_KEY", ""))
         self._cors_origins: tuple[str, ...] = self._parse_cors_origins(
             extra.get("cors_origins", os.getenv("API_SERVER_CORS_ORIGINS", "")),
@@ -727,10 +738,11 @@ class APIServerAdapter(BasePlatformAdapter):
         gateway platforms), falling back to the hermes-api-server default.
         """
         from run_agent import AIAgent
-        from gateway.run import _resolve_runtime_agent_kwargs, _resolve_gateway_model, _load_gateway_config
+        from gateway.run import _resolve_runtime_agent_kwargs, _resolve_gateway_model, _load_gateway_config, GatewayRunner
         from hermes_cli.tools_config import _get_platform_tools
 
         runtime_kwargs = _resolve_runtime_agent_kwargs()
+        reasoning_config = GatewayRunner._load_reasoning_config()
         model = _resolve_gateway_model()
 
         user_config = _load_gateway_config()
@@ -740,7 +752,6 @@ class APIServerAdapter(BasePlatformAdapter):
 
         # Load fallback provider chain so the API server platform has the
         # same fallback behaviour as Telegram/Discord/Slack (fixes #4954).
-        from gateway.run import GatewayRunner
         fallback_model = GatewayRunner._load_fallback_model()
 
         agent = AIAgent(
@@ -759,6 +770,7 @@ class APIServerAdapter(BasePlatformAdapter):
             tool_complete_callback=tool_complete_callback,
             session_db=self._ensure_session_db(),
             fallback_model=fallback_model,
+            reasoning_config=reasoning_config,
         )
         return agent
 
@@ -2566,21 +2578,39 @@ class APIServerAdapter(BasePlatformAdapter):
                     return r, u
 
                 result, usage = await asyncio.get_running_loop().run_in_executor(None, _run_sync)
-                final_response = result.get("final_response", "") if isinstance(result, dict) else ""
-                q.put_nowait({
-                    "event": "run.completed",
-                    "run_id": run_id,
-                    "timestamp": time.time(),
-                    "output": final_response,
-                    "usage": usage,
-                })
-                self._set_run_status(
-                    run_id,
-                    "completed",
-                    output=final_response,
-                    usage=usage,
-                    last_event="run.completed",
-                )
+                # Check for structured failure (non-retryable client errors like
+                # 401/400 return failed=True instead of raising, so the except
+                # block below never fires — issue #15561).
+                if isinstance(result, dict) and result.get("failed"):
+                    error_msg = result.get("error") or "agent run failed"
+                    q.put_nowait({
+                        "event": "run.failed",
+                        "run_id": run_id,
+                        "timestamp": time.time(),
+                        "error": error_msg,
+                    })
+                    self._set_run_status(
+                        run_id,
+                        "failed",
+                        error=error_msg,
+                        last_event="run.failed",
+                    )
+                else:
+                    final_response = result.get("final_response", "") if isinstance(result, dict) else ""
+                    q.put_nowait({
+                        "event": "run.completed",
+                        "run_id": run_id,
+                        "timestamp": time.time(),
+                        "output": final_response,
+                        "usage": usage,
+                    })
+                    self._set_run_status(
+                        run_id,
+                        "completed",
+                        output=final_response,
+                        usage=usage,
+                        last_event="run.completed",
+                    )
             except asyncio.CancelledError:
                 self._set_run_status(
                     run_id,

gateway/platforms/base.py

@@ -2489,19 +2489,30 @@ class BasePlatformAdapter(ABC):
 
         try:
             response = await self._message_handler(event)
-            # Old adapter task (if any) is cancelled AFTER the runner has
-            # fully handled the command — keeps ordering deterministic.
-            await self.cancel_session_processing(
-                session_key,
-                release_guard=False,
-                discard_pending=False,
-            )
             _text, _eph_ttl = self._unwrap_ephemeral(response)
+            # Send the response BEFORE cancelling the old task so the send
+            # cannot be affected by task-cancellation side effects (race
+            # condition fix — issue #18912).  Previously the send happened
+            # after cancel_session_processing, which could silently drop the
+            # "/new" confirmation when an agent was actively running.
             if _text:
+                logger.info(
+                    "[%s] Sending command '/%s' response (%d chars) to %s",
+                    self.name,
+                    cmd,
+                    len(_text),
+                    event.source.chat_id,
+                )
                 _r = await self._send_with_retry(
                     chat_id=event.source.chat_id,
                     content=_text,
-                    reply_to=event.message_id,
+                    reply_to=(
+                        event.reply_to_message_id
+                        if event.source.platform == Platform.FEISHU
+                        and event.source.thread_id
+                        and event.reply_to_message_id
+                        else event.message_id
+                    ),
                     metadata=thread_meta,
                 )
                 if _eph_ttl > 0 and _r.success and _r.message_id:
@@ -2510,6 +2521,13 @@ class BasePlatformAdapter(ABC):
                         message_id=_r.message_id,
                         ttl_seconds=_eph_ttl,
                     )
+            # Old adapter task (if any) is cancelled AFTER the response has
+            # been sent — keeps ordering deterministic and avoids the race.
+            await self.cancel_session_processing(
+                session_key,
+                release_guard=False,
+                discard_pending=False,
+            )
         except Exception:
             # On failure, restore the original guard if one still exists so
             # we don't leave the session in a half-reset state.
@@ -2594,7 +2612,13 @@ class BasePlatformAdapter(ABC):
                         _r = await self._send_with_retry(
                             chat_id=event.source.chat_id,
                             content=_text,
-                            reply_to=event.message_id,
+                            reply_to=(
+                                event.reply_to_message_id
+                                if event.source.platform == Platform.FEISHU
+                                and event.source.thread_id
+                                and event.reply_to_message_id
+                                else event.message_id
+                            ),
                             metadata=_thread_meta,
                         )
                         if _eph_ttl > 0 and _r.success and _r.message_id:
@@ -2798,10 +2822,15 @@ class BasePlatformAdapter(ABC):
                 # Send the text portion
                 if text_content:
                     logger.info("[%s] Sending response (%d chars) to %s", self.name, len(text_content), event.source.chat_id)
+                    _reply_anchor = (
+                        event.reply_to_message_id
+                        if event.source.platform == Platform.FEISHU and event.source.thread_id and event.reply_to_message_id
+                        else event.message_id
+                    )
                     result = await self._send_with_retry(
                         chat_id=event.source.chat_id,
                         content=text_content,
-                        reply_to=event.message_id,
+                        reply_to=_reply_anchor,
                         metadata=_thread_metadata,
                     )
                     _record_delivery(result)

gateway/platforms/discord.py

@@ -497,6 +497,7 @@ class DiscordAdapter(BasePlatformAdapter):
         self._ready_event = asyncio.Event()
         self._allowed_user_ids: set = set()  # For button approval authorization
         self._allowed_role_ids: set = set()  # For DISCORD_ALLOWED_ROLES filtering
+        self.gateway_runner = None  # Set by gateway/run.py for cross-platform delivery
         # Voice channel state (per-guild)
         self._voice_clients: Dict[int, Any] = {}  # guild_id -> VoiceClient
         self._voice_locks: Dict[int, asyncio.Lock] = {}  # guild_id -> serialize join/leave
@@ -719,11 +720,22 @@ class DiscordAdapter(BasePlatformAdapter):
                         return
                     # If humans are mentioned but we're not → not for us
                     # (preserves old DISCORD_IGNORE_NO_MENTION=true behavior)
+                    # EXCEPT in free-response channels where the bot should
+                    # answer regardless of who is mentioned.
                     _ignore_no_mention = os.getenv(
                         "DISCORD_IGNORE_NO_MENTION", "true"
                     ).lower() in ("true", "1", "yes")
                     if _ignore_no_mention and not _self_mentioned and not _other_bots_mentioned:
-                        return
+                        _channel_id = str(message.channel.id)
+                        _parent_id = None
+                        if hasattr(message.channel, "parent_id") and message.channel.parent_id:
+                            _parent_id = str(message.channel.parent_id)
+                        _free_channels = adapter_self._discord_free_response_channels()
+                        _channel_ids = {_channel_id}
+                        if _parent_id:
+                            _channel_ids.add(_parent_id)
+                        if "*" not in _free_channels and not (_channel_ids & _free_channels):
+                            return
 
                 await self._handle_message(message)
 
@@ -1929,6 +1941,225 @@ class DiscordAdapter(BasePlatformAdapter):
                             return True
         return False
 
+    # ── Slash command authorization ─────────────────────────────────────
+    # Slash commands (``_run_simple_slash`` and ``_handle_thread_create_slash``)
+    # are a separate Discord interaction surface from regular messages and
+    # historically ran with NO authorization check — bypassing every gate
+    # ``on_message`` enforces (DISCORD_ALLOWED_USERS, DISCORD_ALLOWED_ROLES,
+    # DISCORD_ALLOWED_CHANNELS, DISCORD_IGNORED_CHANNELS). Any guild member
+    # could invoke ``/background``, ``/restart``, ``/sethome``, etc. as the
+    # operator. ``_check_slash_authorization`` mirrors the on_message gates
+    # one-for-one so the slash surface honors the same trust boundary.
+    #
+    # By design, this is a no-op for deployments with no allowlist env vars
+    # set — ``_is_allowed_user`` returns True and the channel checks early-out
+    # — preserving the existing "single-tenant, all guild members trusted"
+    # default. Deployments that DO set any DISCORD_ALLOWED_* var get slash
+    # parity with on_message.
+
+    def _evaluate_slash_authorization(
+        self, interaction: "discord.Interaction",
+    ) -> Tuple[bool, Optional[str]]:
+        """Evaluate slash authorization without producing any response.
+
+        Returns ``(allowed, reason)``. ``reason`` is populated only when
+        ``allowed`` is False. This is the shared core used by both the
+        responding wrapper (``_check_slash_authorization``) and side-effect-
+        free callers like the ``/skill`` autocomplete callback, which must
+        return an empty list for unauthorized users instead of leaking an
+        ephemeral rejection per-keystroke.
+
+        Fail-closed semantics for malformed payloads: when an allowlist is
+        configured but the interaction is missing the data needed to
+        evaluate it (no channel id with channel policy active, no user
+        with user/role policy active), the gate REJECTS rather than
+        falling through. Without these guards a guild interaction that
+        happens to deserialize without a channel id would silently bypass
+        ``DISCORD_ALLOWED_CHANNELS`` and a payload missing ``user`` would
+        raise ``AttributeError`` in the user check below, surfacing as
+        an opaque interaction failure rather than a clean rejection.
+        """
+        chan_obj = getattr(interaction, "channel", None)
+        in_dm = isinstance(chan_obj, discord.DMChannel) if chan_obj is not None else False
+
+        # ── Channel scope (mirrors on_message lines 3374-3388) ──
+        # DMs aren't channel-gated — DMs follow on_message's DM lockdown
+        # path which has its own user-allowlist enforcement.
+        if not in_dm:
+            chan_id_raw = getattr(interaction, "channel_id", None) or getattr(
+                chan_obj, "id", None,
+            )
+            channel_ids: set = set()
+            if chan_id_raw is not None:
+                channel_ids.add(str(chan_id_raw))
+                # Mirror on_message: also test the parent channel for threads
+                # so per-channel allow/deny lists work consistently.
+                if isinstance(chan_obj, discord.Thread):
+                    parent_id = self._get_parent_channel_id(chan_obj)
+                    if parent_id:
+                        channel_ids.add(str(parent_id))
+
+            allowed_raw = os.getenv("DISCORD_ALLOWED_CHANNELS", "")
+            if allowed_raw:
+                allowed = {c.strip() for c in allowed_raw.split(",") if c.strip()}
+                if "*" not in allowed:
+                    if not channel_ids:
+                        # Channel policy is configured but the interaction
+                        # has no resolvable channel id. Fail closed.
+                        return (
+                            False,
+                            "channel id missing with DISCORD_ALLOWED_CHANNELS configured",
+                        )
+                    if not (channel_ids & allowed):
+                        return (False, "channel not in DISCORD_ALLOWED_CHANNELS")
+
+            # Ignored beats allowed: even when a thread's parent channel
+            # is on the allowlist, an explicit DISCORD_IGNORED_CHANNELS
+            # entry on the thread or its parent rejects the interaction.
+            ignored_raw = os.getenv("DISCORD_IGNORED_CHANNELS", "")
+            if ignored_raw and channel_ids:
+                ignored = {c.strip() for c in ignored_raw.split(",") if c.strip()}
+                if "*" in ignored or (channel_ids & ignored):
+                    return (False, "channel in DISCORD_IGNORED_CHANNELS")
+
+        # ── User / role allowlist (mirrors on_message line 681) ──
+        user = getattr(interaction, "user", None)
+        allowed_users = getattr(self, "_allowed_user_ids", set()) or set()
+        allowed_roles = getattr(self, "_allowed_role_ids", set()) or set()
+        if user is None or getattr(user, "id", None) is None:
+            # No identifiable user. With any user/role allowlist
+            # configured, fail closed rather than raise AttributeError
+            # on ``interaction.user.id`` below. With no allowlist this
+            # is the existing "no allowlist = everyone" backwards-compat.
+            if allowed_users or allowed_roles:
+                return (False, "missing interaction.user with allowlist configured")
+            return (True, None)
+
+        user_id = str(user.id)
+        if not self._is_allowed_user(user_id, author=user):
+            return (
+                False,
+                "user not in DISCORD_ALLOWED_USERS / DISCORD_ALLOWED_ROLES",
+            )
+
+        return (True, None)
+
+    async def _check_slash_authorization(
+        self, interaction: "discord.Interaction", command_text: str,
+    ) -> bool:
+        """Mirror on_message's user/role/channel gates onto a slash invocation.
+
+        Returns True to proceed. Returns False *after* sending an ephemeral
+        rejection, logging a warning, and scheduling a cross-platform admin
+        alert — the caller must stop on False (the interaction has already
+        been responded to).
+        """
+        allowed, reason = self._evaluate_slash_authorization(interaction)
+        if allowed:
+            return True
+        return await self._reject_slash(
+            interaction, command_text, reason=reason or "unauthorized",
+        )
+
+    async def _reject_slash(
+        self, interaction: "discord.Interaction", command_text: str, *, reason: str,
+    ) -> bool:
+        """Send ephemeral reject + log warning + schedule admin alert. Returns False.
+
+        Tolerates a missing ``interaction.user`` -- the fail-closed branch
+        in ``_evaluate_slash_authorization`` deliberately routes here for
+        malformed payloads (no user) when an allowlist is configured, and
+        ``str(interaction.user.id)`` would raise AttributeError before the
+        ephemeral rejection could be sent.
+        """
+        user = getattr(interaction, "user", None)
+        if user is not None:
+            user_id = str(getattr(user, "id", "?"))
+            user_name = getattr(user, "name", "?")
+        else:
+            user_id = "?"
+            user_name = "?"
+        chan_id = getattr(interaction, "channel_id", None) or getattr(
+            getattr(interaction, "channel", None), "id", None,
+        )
+        guild_id = getattr(interaction, "guild_id", None)
+
+        logger.warning(
+            "[Discord] Unauthorized slash attempt: user=%s id=%s channel=%s "
+            "guild=%s cmd=%r reason=%r",
+            user_name, user_id, chan_id, guild_id, command_text, reason,
+        )
+
+        try:
+            await interaction.response.send_message(
+                "You're not authorized to use this command.",
+                ephemeral=True,
+            )
+        except Exception as e:
+            # Interaction may already be responded to (e.g. caller deferred
+            # before the auth check, or Discord retried). Best-effort only.
+            logger.debug("[Discord] Could not send unauthorized ephemeral: %s", e)
+
+        # Fire-and-forget: don't block the interaction handler on Telegram I/O.
+        try:
+            asyncio.create_task(self._notify_unauthorized_slash(
+                user_name, user_id, chan_id, guild_id, command_text, reason,
+            ))
+        except Exception as e:
+            logger.debug("[Discord] Could not schedule admin notify task: %s", e)
+
+        return False
+
+    async def _notify_unauthorized_slash(
+        self, user_name: str, user_id: str, chan_id, guild_id,
+        command_text: str, reason: str,
+    ) -> None:
+        """Best-effort cross-platform alert to the gateway operator.
+
+        Tries TELEGRAM first (most operators set TELEGRAM_HOME_CHANNEL),
+        then SLACK. Silently no-ops if no other platform is configured
+        with a home channel.
+
+        A soft send failure -- adapter.send() returning a result with
+        ``success=False`` rather than raising -- continues the fallback
+        chain. Treating a SendResult(success=False) as delivered would
+        mean a Telegram outage that the adapter politely surfaces (e.g.
+        rate-limit, auth failure) silently swallows the alert without
+        attempting Slack. Hard exceptions still take the same path via
+        the except branch below.
+        """
+        runner = getattr(self, "gateway_runner", None)
+        if not runner:
+            return
+        for target in (Platform.TELEGRAM, Platform.SLACK):
+            try:
+                adapter = runner.adapters.get(target)
+                if not adapter:
+                    continue
+                home = runner.config.get_home_channel(target)
+                if not home or not getattr(home, "chat_id", None):
+                    continue
+                msg = (
+                    "⚠️ Unauthorized Discord slash attempt\n"
+                    f"User: {user_name} ({user_id})\n"
+                    f"Channel: {chan_id} (guild {guild_id})\n"
+                    f"Command: {command_text}\n"
+                    f"Reason: {reason}"
+                )
+                result = await adapter.send(str(home.chat_id), msg)
+                # Only return on confirmed delivery. SendResult(success=False)
+                # -> continue to the next platform.
+                if getattr(result, "success", None) is False:
+                    logger.debug(
+                        "[Discord] Admin notify via %s returned success=False"
+                        " (error=%r); falling through",
+                        target, getattr(result, "error", None),
+                    )
+                    continue
+                return
+            except Exception as e:
+                logger.debug("[Discord] Admin notify via %s failed: %s", target, e)
+
     async def send_image_file(
         self,
         chat_id: str,
@@ -2316,6 +2547,11 @@ class DiscordAdapter(BasePlatformAdapter):
         except Exception:
             pass  # logging must never block command dispatch
 
+        # Auth gate — must run before defer() so an ephemeral rejection can
+        # be delivered on the still-unresponded interaction.
+        if not await self._check_slash_authorization(interaction, command_text):
+            return
+
         await interaction.response.defer(ephemeral=True)
         event = self._build_slash_event(interaction, command_text)
         await self.handle_message(event)
@@ -2460,7 +2696,8 @@ class DiscordAdapter(BasePlatformAdapter):
             message: str = "",
             auto_archive_duration: int = 1440,
         ):
-            await interaction.response.defer(ephemeral=True)
+            # defer() is performed inside the handler *after* the auth gate
+            # so a rejected invoker can receive an ephemeral rejection.
             await self._handle_thread_create_slash(interaction, name, message, auto_archive_duration)
 
         @tree.command(name="queue", description="Queue a prompt for the next turn (doesn't interrupt)")
@@ -2581,6 +2818,54 @@ class DiscordAdapter(BasePlatformAdapter):
         # supporting up to 25 categories × 25 skills = 625 skills.
         self._register_skill_group(tree)
 
+        # Optional defense-in-depth: hide every slash command from non-admin
+        # guild members in Discord's slash picker. Server-side authorization
+        # (``_check_slash_authorization``) is the actual gate; this is purely
+        # UX so users don't see commands they can't invoke. Off by default
+        # to preserve the slash UX for deployments that intentionally allow
+        # everyone in the guild.
+        if os.getenv("DISCORD_HIDE_SLASH_COMMANDS", "false").strip().lower() in (
+            "true", "1", "yes", "on",
+        ):
+            self._apply_owner_only_visibility(tree)
+
+    def _apply_owner_only_visibility(self, tree) -> None:
+        """Set default_member_permissions=0 on every registered slash command.
+
+        Discord interprets ``Permissions(0)`` as "requires no permissions",
+        which paradoxically means the command is hidden from every guild
+        member except those with the Administrator permission. Server admins
+        can re-grant per user/role via Server Settings → Integrations →
+        <bot> → Permissions.
+
+        Authoritative gate is ``_check_slash_authorization`` on every
+        invocation, which catches stale clients, role grants made by
+        mistake, and direct API calls bypassing Discord's UI hide.
+        """
+        try:
+            no_perms = discord.Permissions(0)
+        except Exception as e:
+            logger.warning(
+                "[Discord] _apply_owner_only_visibility: cannot build Permissions(0): %s",
+                e,
+            )
+            return
+        applied = 0
+        for cmd in tree.get_commands():
+            try:
+                cmd.default_permissions = no_perms
+                applied += 1
+            except Exception as e:
+                logger.debug(
+                    "[Discord] Could not set default_permissions on %r: %s",
+                    getattr(cmd, "name", "?"), e,
+                )
+        logger.info(
+            "[Discord] Hid %d slash command(s) from non-admin guild members "
+            "(opt-in defense in depth via DISCORD_HIDE_SLASH_COMMANDS).",
+            applied,
+        )
+
     def _register_skill_group(self, tree) -> None:
         """Register a single ``/skill`` command with autocomplete on the name.
 
@@ -2635,9 +2920,25 @@ class DiscordAdapter(BasePlatformAdapter):
                 PDFs even if the name doesn't. Discord caps this list at
                 25 entries per query.
 
+                Authorization: a quiet pre-check evaluates the slash
+                allowlists and returns ``[]`` for unauthorized users so
+                the installed skill catalog is not leaked to anyone who
+                can see the command in the picker. Returning a generic
+                empty list here is intentional — sending a per-keystroke
+                ephemeral rejection would produce a barrage of error
+                popups during typing.
+
                 Reads ``self._skill_entries`` so a ``/reload-skills`` run
                 since process start shows up on the very next keystroke.
                 """
+                try:
+                    allowed, _reason = self._evaluate_slash_authorization(interaction)
+                except Exception:
+                    # Defensive: never raise from autocomplete. Fail
+                    # closed by returning an empty suggestion list.
+                    return []
+                if not allowed:
+                    return []
                 q = (current or "").strip().lower()
                 choices: list = []
                 for name, desc, _key in self._skill_entries:
@@ -2664,6 +2965,12 @@ class DiscordAdapter(BasePlatformAdapter):
             async def _skill_handler(
                 interaction: "discord.Interaction", name: str, args: str = "",
             ):
+                # Authorize BEFORE any skill lookup so that known and
+                # unknown skill names produce identical rejections for
+                # unauthorized users (no probing the installed catalog
+                # via "Unknown skill: <name>" responses).
+                if not await self._check_slash_authorization(interaction, "/skill"):
+                    return
                 entry = self._skill_lookup.get(name)
                 if not entry:
                     await interaction.response.send_message(
@@ -2811,6 +3118,9 @@ class DiscordAdapter(BasePlatformAdapter):
         auto_archive_duration: int = 1440,
     ) -> None:
         """Create a Discord thread from a slash command and start a session in it."""
+        if not await self._check_slash_authorization(interaction, "/thread"):
+            return
+        await interaction.response.defer(ephemeral=True)
         result = await self._create_thread(
             interaction,
             name=name,
@@ -3105,6 +3415,7 @@ class DiscordAdapter(BasePlatformAdapter):
             view = ExecApprovalView(
                 session_key=session_key,
                 allowed_user_ids=self._allowed_user_ids,
+                allowed_role_ids=self._allowed_role_ids,
             )
 
             msg = await channel.send(embed=embed, view=view)
@@ -3143,6 +3454,7 @@ class DiscordAdapter(BasePlatformAdapter):
                 session_key=session_key,
                 confirm_id=confirm_id,
                 allowed_user_ids=self._allowed_user_ids,
+                allowed_role_ids=self._allowed_role_ids,
             )
 
             msg = await channel.send(embed=embed, view=view)
@@ -3177,6 +3489,7 @@ class DiscordAdapter(BasePlatformAdapter):
             view = UpdatePromptView(
                 session_key=session_key,
                 allowed_user_ids=self._allowed_user_ids,
+                allowed_role_ids=self._allowed_role_ids,
             )
             msg = await channel.send(embed=embed, view=view)
             return SendResult(success=True, message_id=str(msg.id))
@@ -3234,6 +3547,7 @@ class DiscordAdapter(BasePlatformAdapter):
                 session_key=session_key,
                 on_model_selected=on_model_selected,
                 allowed_user_ids=self._allowed_user_ids,
+                allowed_role_ids=self._allowed_role_ids,
             )
 
             msg = await channel.send(embed=embed, view=view)
@@ -3494,7 +3808,7 @@ class DiscordAdapter(BasePlatformAdapter):
         if not is_thread and not isinstance(message.channel, discord.DMChannel):
             no_thread_channels_raw = os.getenv("DISCORD_NO_THREAD_CHANNELS", "")
             no_thread_channels = {ch.strip() for ch in no_thread_channels_raw.split(",") if ch.strip()}
-            skip_thread = bool(channel_ids & no_thread_channels) or is_free_channel
+            skip_thread = bool(channel_ids & no_thread_channels)
             auto_thread = os.getenv("DISCORD_AUTO_THREAD", "true").lower() in ("true", "1", "yes")
             is_reply_message = getattr(message, "type", None) == discord.MessageType.reply
             if auto_thread and not skip_thread and not is_voice_linked_channel and not is_reply_message:
@@ -3789,6 +4103,72 @@ class DiscordAdapter(BasePlatformAdapter):
 # Discord UI Components (outside the adapter class)
 # ---------------------------------------------------------------------------
 
+
+def _component_check_auth(
+    interaction,
+    allowed_user_ids: Optional[set],
+    allowed_role_ids: Optional[set],
+) -> bool:
+    """Shared user-or-role OR semantics for component view button clicks.
+
+    Mirrors ``DiscordAdapter._is_allowed_user`` / the slash and on_message
+    gates so every Discord interaction surface honors the same trust
+    boundary. Component views (ExecApprovalView, SlashConfirmView,
+    UpdatePromptView, ModelPickerView) used to receive only
+    ``allowed_user_ids``: in role-only deployments
+    (DISCORD_ALLOWED_ROLES set, DISCORD_ALLOWED_USERS empty) the user
+    set was empty and the legacy "no allowlist = allow everyone" branch
+    let any guild member click the buttons -- approving exec commands,
+    cancelling slash confirmations, switching the model.
+
+    Behavior:
+
+      - both allowlists empty -> allow (preserves existing no-allowlist
+        deployments, no regression)
+      - user is in user allowlist -> allow
+      - role allowlist set + user has a role in it -> allow
+      - role allowlist set + interaction.user has no resolvable
+        ``roles`` attribute (e.g. DM context with a role policy active)
+        -> reject (fail closed)
+      - otherwise -> reject
+    """
+    user_set = allowed_user_ids or set()
+    role_set = allowed_role_ids or set()
+    has_users = bool(user_set)
+    has_roles = bool(role_set)
+    if not has_users and not has_roles:
+        return True
+
+    user = getattr(interaction, "user", None)
+    if user is None:
+        return False
+
+    if has_users:
+        try:
+            uid = str(user.id)
+        except AttributeError:
+            uid = ""
+        if uid and uid in user_set:
+            return True
+
+    if has_roles:
+        roles_attr = getattr(user, "roles", None)
+        if roles_attr is None:
+            # Role policy is configured but the interaction doesn't
+            # carry role data (DM-context Member, raw User payload).
+            # Fail closed: a user without a resolvable role list cannot
+            # satisfy a role allowlist.
+            return False
+        try:
+            user_role_ids = {getattr(r, "id", None) for r in roles_attr}
+        except TypeError:
+            return False
+        if user_role_ids & role_set:
+            return True
+
+    return False
+
+
 if DISCORD_AVAILABLE:
 
     class ExecApprovalView(discord.ui.View):
@@ -3801,17 +4181,23 @@ if DISCORD_AVAILABLE:
         Only users in the allowed list can click.  Times out after 5 minutes.
         """
 
-        def __init__(self, session_key: str, allowed_user_ids: set):
+        def __init__(
+            self,
+            session_key: str,
+            allowed_user_ids: set,
+            allowed_role_ids: Optional[set] = None,
+        ):
             super().__init__(timeout=300)  # 5-minute timeout
             self.session_key = session_key
             self.allowed_user_ids = allowed_user_ids
+            self.allowed_role_ids = allowed_role_ids or set()
             self.resolved = False
 
         def _check_auth(self, interaction: discord.Interaction) -> bool:
             """Verify the user clicking is authorized."""
-            if not self.allowed_user_ids:
-                return True  # No allowlist = anyone can approve
-            return str(interaction.user.id) in self.allowed_user_ids
+            return _component_check_auth(
+                interaction, self.allowed_user_ids, self.allowed_role_ids,
+            )
 
         async def _resolve(
             self, interaction: discord.Interaction, choice: str,
@@ -3903,17 +4289,24 @@ if DISCORD_AVAILABLE:
         5 minutes (matches the gateway primitive's timeout).
         """
 
-        def __init__(self, session_key: str, confirm_id: str, allowed_user_ids: set):
+        def __init__(
+            self,
+            session_key: str,
+            confirm_id: str,
+            allowed_user_ids: set,
+            allowed_role_ids: Optional[set] = None,
+        ):
             super().__init__(timeout=300)
             self.session_key = session_key
             self.confirm_id = confirm_id
             self.allowed_user_ids = allowed_user_ids
+            self.allowed_role_ids = allowed_role_ids or set()
             self.resolved = False
 
         def _check_auth(self, interaction: discord.Interaction) -> bool:
-            if not self.allowed_user_ids:
-                return True
-            return str(interaction.user.id) in self.allowed_user_ids
+            return _component_check_auth(
+                interaction, self.allowed_user_ids, self.allowed_role_ids,
+            )
 
         async def _resolve(
             self, interaction: discord.Interaction, choice: str,
@@ -3991,16 +4384,22 @@ if DISCORD_AVAILABLE:
         5-minute timeout on its side).
         """
 
-        def __init__(self, session_key: str, allowed_user_ids: set):
+        def __init__(
+            self,
+            session_key: str,
+            allowed_user_ids: set,
+            allowed_role_ids: Optional[set] = None,
+        ):
             super().__init__(timeout=300)
             self.session_key = session_key
             self.allowed_user_ids = allowed_user_ids
+            self.allowed_role_ids = allowed_role_ids or set()
             self.resolved = False
 
         def _check_auth(self, interaction: discord.Interaction) -> bool:
-            if not self.allowed_user_ids:
-                return True
-            return str(interaction.user.id) in self.allowed_user_ids
+            return _component_check_auth(
+                interaction, self.allowed_user_ids, self.allowed_role_ids,
+            )
 
         async def _respond(
             self, interaction: discord.Interaction, answer: str,
@@ -4077,6 +4476,7 @@ if DISCORD_AVAILABLE:
             session_key: str,
             on_model_selected,
             allowed_user_ids: set,
+            allowed_role_ids: Optional[set] = None,
         ):
             super().__init__(timeout=120)
             self.providers = providers
@@ -4085,15 +4485,16 @@ if DISCORD_AVAILABLE:
             self.session_key = session_key
             self.on_model_selected = on_model_selected
             self.allowed_user_ids = allowed_user_ids
+            self.allowed_role_ids = allowed_role_ids or set()
             self.resolved = False
             self._selected_provider: str = ""
 
             self._build_provider_select()
 
         def _check_auth(self, interaction: discord.Interaction) -> bool:
-            if not self.allowed_user_ids:
-                return True
-            return str(interaction.user.id) in self.allowed_user_ids
+            return _component_check_auth(
+                interaction, self.allowed_user_ids, self.allowed_role_ids,
+            )
 
         def _build_provider_select(self):
             """Build the provider dropdown menu."""

gateway/platforms/email.py

@@ -416,6 +416,18 @@ class EmailAdapter(BasePlatformAdapter):
             logger.debug("[Email] Dropping automated sender at dispatch: %s", sender_addr)
             return
 
+        # Skip senders not in EMAIL_ALLOWED_USERS — prevents the adapter
+        # from creating a MessageEvent (and thus thread context) for senders
+        # that the gateway will never authorize.  Without this early guard,
+        # a race between dispatch and authorization can result in the adapter
+        # sending a reply even though the handler returned None.
+        allowed_raw = os.getenv("EMAIL_ALLOWED_USERS", "").strip()
+        if allowed_raw:
+            allowed = {addr.strip().lower() for addr in allowed_raw.split(",") if addr.strip()}
+            if sender_addr.lower() not in allowed:
+                logger.debug("[Email] Dropping non-allowlisted sender at dispatch: %s", sender_addr)
+                return
+
         subject = msg_data["subject"]
         body = msg_data["body"].strip()
         attachments = msg_data["attachments"]

gateway/platforms/feishu.py

@@ -2757,9 +2757,11 @@ class FeishuAdapter(BasePlatformAdapter):
             if hint:
                 text = f"{hint}\n\n{text}" if text else hint
 
+        thread_id = getattr(message, "thread_id", None) or getattr(message, "root_id", None) or None
         reply_to_message_id = (
             getattr(message, "parent_id", None)
             or getattr(message, "upper_message_id", None)
+            or getattr(message, "root_id", None)
             or None
         )
         reply_to_text = await self._fetch_message_text(reply_to_message_id) if reply_to_message_id else None
@@ -2791,7 +2793,7 @@ class FeishuAdapter(BasePlatformAdapter):
             chat_type=self._resolve_source_chat_type(chat_info=chat_info, event_chat_type=chat_type),
             user_id=sender_profile["user_id"],
             user_name=sender_profile["user_name"],
-            thread_id=getattr(message, "thread_id", None) or None,
+            thread_id=thread_id,
             user_id_alt=sender_profile["user_id_alt"],
             is_bot=is_bot,
         )
@@ -4227,6 +4229,15 @@ class FeishuAdapter(BasePlatformAdapter):
                 if active_reply_to and not self._response_succeeded(response):
                     code = getattr(response, "code", None)
                     if code in _FEISHU_REPLY_FALLBACK_CODES:
+                        if (metadata or {}).get("thread_id"):
+                            logger.warning(
+                                "[Feishu] Reply to %s failed in thread %s (code %s — message withdrawn/missing); "
+                                "skipping top-level fallback to avoid creating a new topic",
+                                active_reply_to,
+                                (metadata or {}).get("thread_id"),
+                                code,
+                            )
+                            return response
                         logger.warning(
                             "[Feishu] Reply to %s failed (code %s — message withdrawn/missing); "
                             "falling back to new message in chat %s",

gateway/platforms/homeassistant.py

@@ -139,7 +139,7 @@ class HomeAssistantAdapter(BasePlatformAdapter):
 
     async def _ws_connect(self) -> bool:
         """Establish WebSocket connection and authenticate."""
-        ws_url = self._hass_url.replace("http://", "ws://").replace("https://", "wss://")
+        ws_url = self._hass_url.replace("https://", "wss://").replace("http://", "ws://")
         ws_url = f"{ws_url}/api/websocket"
 
         self._session = aiohttp.ClientSession(

gateway/platforms/qqbot/adapter.py

@@ -397,13 +397,24 @@ class QQAdapter(BasePlatformAdapter):
             await self._session.close()
         self._session = None
 
-        self._session = aiohttp.ClientSession()
+        # Honor WSL proxy env for QQ WebSocket. Hermes upgrades overwrite this
+        # local patch, so QQ can regress to direct-connect timeouts after update.
+        self._session = aiohttp.ClientSession(trust_env=True)
+        ws_proxy = (
+            os.getenv("WSS_PROXY")
+            or os.getenv("wss_proxy")
+            or os.getenv("HTTPS_PROXY")
+            or os.getenv("https_proxy")
+            or os.getenv("ALL_PROXY")
+            or os.getenv("all_proxy")
+        )
         self._ws = await self._session.ws_connect(
             gateway_url,
             headers={
                 "User-Agent": build_user_agent(),
             },
             timeout=CONNECT_TIMEOUT_SECONDS,
+            proxy=ws_proxy,
         )
         logger.info("[%s] WebSocket connected to %s", self._log_tag, gateway_url)
 

gateway/platforms/signal.py

@@ -192,6 +192,15 @@ class SignalAdapter(BasePlatformAdapter):
         group_allowed_str = os.getenv("SIGNAL_GROUP_ALLOWED_USERS", "")
         self.group_allow_from = set(_parse_comma_list(group_allowed_str))
 
+        # DM allowlist — mirrors SIGNAL_ALLOWED_USERS checked by run.py.
+        # Stored here so the reaction hooks can skip unauthorized senders
+        # (reactions fire before run.py's auth gate, so without this check
+        # every inbound DM from any contact gets a 👀 reaction).
+        # "*" means all users allowed (open mode); empty means no restriction
+        # recorded at adapter level (run.py still enforces auth separately).
+        dm_allowed_str = os.getenv("SIGNAL_ALLOWED_USERS", "*")
+        self.dm_allow_from = set(_parse_comma_list(dm_allowed_str))
+
         # HTTP client
         self.client: Optional[httpx.AsyncClient] = None
 
@@ -1430,8 +1439,28 @@ class SignalAdapter(BasePlatformAdapter):
             return None
         return (author, ts)
 
+    def _reactions_enabled(self, event: "MessageEvent" = None) -> bool:
+        """Check if message reactions are enabled for this event.
+
+        Two gates:
+        1. SIGNAL_REACTIONS env var — set to false/0/no to disable globally.
+        2. DM allowlist — if SIGNAL_ALLOWED_USERS is set, only react to
+           messages from senders in that list.  This prevents unauthorized
+           contacts from seeing the 👀 reaction (which fires before run.py's
+           auth gate and would otherwise reveal that a bot is listening).
+        """
+        if os.getenv("SIGNAL_REACTIONS", "true").lower() in ("false", "0", "no"):
+            return False
+        if event is not None:
+            sender = getattr(getattr(event, "source", None), "user_id", None)
+            if sender and "*" not in self.dm_allow_from and sender not in self.dm_allow_from:
+                return False
+        return True
+
     async def on_processing_start(self, event: MessageEvent) -> None:
         """React with 👀 when processing begins."""
+        if not self._reactions_enabled(event):
+            return
         target = self._extract_reaction_target(event)
         if target:
             await self.send_reaction(event.source.chat_id, "👀", *target)
@@ -1442,6 +1471,8 @@ class SignalAdapter(BasePlatformAdapter):
         On CANCELLED we leave the 👀 in place — no terminal outcome means
         the reaction should keep reflecting "in progress" (matches Telegram).
         """
+        if not self._reactions_enabled(event):
+            return
         if outcome == ProcessingOutcome.CANCELLED:
             return
         target = self._extract_reaction_target(event)

gateway/platforms/slack.py

@@ -528,6 +528,21 @@ class SlackAdapter(BasePlatformAdapter):
                 return False
             lock_acquired = True
 
+            # Close any previous handler before creating a new one so that
+            # calling connect() a second time (e.g. during a gateway restart or
+            # in-process reconnect attempt) does not leave a zombie Socket Mode
+            # connection alive.  Both the old and new connections would otherwise
+            # receive every Slack event and dispatch it twice, producing double
+            # responses — the same bug that affected DiscordAdapter (#18187).
+            if self._handler is not None:
+                try:
+                    await self._handler.close_async()
+                except Exception:
+                    logger.debug("[%s] Failed to close previous Slack handler", self.name)
+                finally:
+                    self._handler = None
+                    self._app = None
+
             # First token is the primary — used for AsyncApp / Socket Mode
             primary_token = bot_tokens[0]
             self._app = AsyncApp(token=primary_token)

gateway/platforms/sms.py

@@ -10,7 +10,7 @@ Shares credentials with the optional telephony skill — same env vars:
 
 Gateway-specific env vars:
   - SMS_WEBHOOK_PORT     (default 8080)
-  - SMS_WEBHOOK_HOST     (default 0.0.0.0)
+  - SMS_WEBHOOK_HOST     (default 127.0.0.1)
   - SMS_WEBHOOK_URL      (public URL for Twilio signature validation — required)
   - SMS_INSECURE_NO_SIGNATURE  (true to disable signature validation — dev only)
   - SMS_ALLOWED_USERS    (comma-separated E.164 phone numbers)
@@ -41,7 +41,7 @@ logger = logging.getLogger(__name__)
 TWILIO_API_BASE = "https://api.twilio.com/2010-04-01/Accounts"
 MAX_SMS_LENGTH = 1600  # ~10 SMS segments
 DEFAULT_WEBHOOK_PORT = 8080
-DEFAULT_WEBHOOK_HOST = "0.0.0.0"
+DEFAULT_WEBHOOK_HOST = "127.0.0.1"
 
 
 def check_sms_requirements() -> bool:
@@ -91,19 +91,23 @@ class SmsAdapter(BasePlatformAdapter):
         from aiohttp import web
 
         if not self._from_number:
-            logger.error("[sms] TWILIO_PHONE_NUMBER not set — cannot send replies")
+            msg = "[sms] TWILIO_PHONE_NUMBER not set — cannot send replies"
+            logger.error(msg)
+            self._set_fatal_error("sms_missing_phone_number", msg, retryable=False)
             return False
 
         insecure_no_sig = os.getenv("SMS_INSECURE_NO_SIGNATURE", "").lower() == "true"
 
         if not self._webhook_url and not insecure_no_sig:
-            logger.error(
+            msg = (
                 "[sms] Refusing to start: SMS_WEBHOOK_URL is required for Twilio "
                 "signature validation. Set it to the public URL configured in your "
                 "Twilio console (e.g. https://example.com/webhooks/twilio). "
                 "For local development without validation, set "
-                "SMS_INSECURE_NO_SIGNATURE=true (NOT recommended for production).",
+                "SMS_INSECURE_NO_SIGNATURE=true (NOT recommended for production)."
             )
+            logger.error(msg)
+            self._set_fatal_error("sms_missing_webhook_url", msg, retryable=False)
             return False
 
         if insecure_no_sig and not self._webhook_url:

gateway/platforms/telegram.py

@@ -688,6 +688,29 @@ class TelegramAdapter(BasePlatformAdapter):
                 )
             return None
 
+    async def rename_dm_topic(
+        self,
+        chat_id: int,
+        thread_id: int,
+        name: str,
+    ) -> None:
+        """Rename a forum topic in a private (DM) chat."""
+        if not self._bot:
+            return
+        try:
+            chat_id_arg = int(chat_id)
+        except (TypeError, ValueError):
+            chat_id_arg = chat_id
+        await self._bot.edit_forum_topic(
+            chat_id=chat_id_arg,
+            message_thread_id=int(thread_id),
+            name=name,
+        )
+        logger.info(
+            "[%s] Renamed DM topic in chat %s thread_id=%s -> '%s'",
+            self.name, chat_id, thread_id, name,
+        )
+
     def _persist_dm_topic_thread_id(self, chat_id: int, topic_name: str, thread_id: int) -> None:
         """Save a newly created thread_id back into config.yaml so it persists across restarts."""
         try:
@@ -2267,13 +2290,54 @@ class TelegramAdapter(BasePlatformAdapter):
                 )
             return SendResult(success=True, message_id=str(msg.message_id))
         except Exception as e:
-            logger.error(
-                "[%s] Failed to send Telegram local image, falling back to base adapter: %s",
-                self.name,
-                e,
-                exc_info=True,
+            error_str = str(e)
+            # Dimension-related errors are the expected case for valid image
+            # files that Telegram just refuses as photos (screenshots, extreme
+            # aspect ratios). Log at INFO because the document fallback is
+            # the correct path. Any other send_photo failure also falls back
+            # to document (rate limits, corrupt file markers, format edge
+            # cases), but at WARNING because it's unexpected and worth
+            # surfacing in logs.
+            is_dim_error = (
+                "Photo_invalid_dimensions" in error_str
+                or "PHOTO_INVALID_DIMENSIONS" in error_str
             )
-            return await super().send_image_file(chat_id, image_path, caption, reply_to)
+            if is_dim_error:
+                logger.info(
+                    "[%s] Image dimensions exceed Telegram photo limits, "
+                    "sending as document: %s",
+                    self.name,
+                    image_path,
+                )
+            else:
+                logger.warning(
+                    "[%s] Failed to send Telegram local image as photo, "
+                    "trying document fallback: %s",
+                    self.name,
+                    e,
+                    exc_info=True,
+                )
+            # Fallback to sending as document (file) — no dimension limit,
+            # only 50MB size limit. If even that fails, fall back to the
+            # base adapter's text-only "Image: /path" rendering.
+            try:
+                return await self.send_document(
+                    chat_id=chat_id,
+                    file_path=image_path,
+                    caption=caption,
+                    file_name=os.path.basename(image_path),
+                    reply_to=reply_to,
+                    metadata=metadata,
+                )
+            except Exception as doc_err:
+                logger.error(
+                    "[%s] Failed to send Telegram local image as document, "
+                    "falling back to base adapter: %s",
+                    self.name,
+                    doc_err,
+                    exc_info=True,
+                )
+                return await super().send_image_file(chat_id, image_path, caption, reply_to)
 
     async def send_document(
         self,

gateway/platforms/wecom.py

@@ -142,6 +142,7 @@ class WeComAdapter(BasePlatformAdapter):
     """WeCom AI Bot adapter backed by a persistent WebSocket connection."""
 
     MAX_MESSAGE_LENGTH = MAX_MESSAGE_LENGTH
+    SUPPORTS_MESSAGE_EDITING = False
     # Threshold for detecting WeCom client-side message splits.
     # When a chunk is near the 4000-char limit, a continuation is almost certain.
     _SPLIT_THRESHOLD = 3900

gateway/platforms/weixin.py

@@ -1333,6 +1333,15 @@ class WeixinAdapter(BasePlatformAdapter):
         if message_id and self._dedup.is_duplicate(message_id):
             return
 
+        # Secondary content-fingerprint dedup for text messages
+        item_list = message.get("item_list") or []
+        text = _extract_text(item_list)
+        if text:
+            content_key = f"content:{sender_id}:{hashlib.md5(text.encode()).hexdigest()}"
+            if self._dedup.is_duplicate(content_key):
+                logger.debug("[%s] Content-dedup: skipping duplicate message from %s", self.name, sender_id)
+                return
+
         chat_type, effective_chat_id = _guess_chat_type(message, self._account_id)
         if chat_type == "group":
             if self._group_policy == "disabled":
@@ -1347,8 +1356,6 @@ class WeixinAdapter(BasePlatformAdapter):
             self._token_store.set(self._account_id, sender_id, context_token)
         asyncio.create_task(self._maybe_fetch_typing_ticket(sender_id, context_token or None))
 
-        item_list = message.get("item_list") or []
-        text = _extract_text(item_list)
         media_paths: List[str] = []
         media_types: List[str] = []
 

gateway/session.py

@@ -1086,19 +1086,22 @@ class SessionStore:
         return len(removed_keys)
 
     def suspend_recently_active(self, max_age_seconds: int = 120) -> int:
-        """Mark recently-active sessions as suspended.
+        """Mark recently-active sessions as resumable after an unexpected exit.
 
-        Called on gateway startup to prevent sessions that were likely
-        in-flight when the gateway last exited from being blindly resumed
-        (#7536).  Only suspends sessions updated within *max_age_seconds*
-        to avoid resetting long-idle sessions that are harmless to resume.
-        Returns the number of sessions that were suspended.
+        Called on gateway startup after a crash or fast restart to preserve
+        in-flight sessions instead of destroying their conversation history
+        (#7536).  Only marks sessions updated within *max_age_seconds* to
+        avoid touching long-idle sessions.  Sets ``resume_pending=True`` so
+        the next incoming message on the same session_key auto-resumes from
+        the existing transcript.
 
-        Entries flagged ``resume_pending=True`` are skipped — those were
-        marked intentionally by the drain-timeout path as recoverable.
-        Terminal escalation for genuinely stuck ``resume_pending`` sessions
-        is handled by the existing ``.restart_failure_counts`` stuck-loop
-        counter, which runs after this method on startup.
+        Entries already flagged ``resume_pending=True`` are skipped.  Entries
+        explicitly ``suspended=True`` (from /stop or stuck-loop escalation)
+        are also skipped.  Terminal escalation for genuinely stuck sessions
+        is still handled by the existing ``.restart_failure_counts`` counter
+        (threshold 3), which runs after this method and sets ``suspended=True``.
+
+        Returns the number of sessions marked resumable.
         """
         from datetime import timedelta
 
@@ -1110,13 +1113,15 @@ class SessionStore:
                 if entry.resume_pending:
                     continue
                 if not entry.suspended and entry.updated_at >= cutoff:
-                    entry.suspended = True
+                    entry.resume_pending = True
+                    entry.resume_reason = "restart_interrupted"
+                    entry.last_resume_marked_at = _now()
                     count += 1
             if count:
                 self._save()
         return count
 
-    def reset_session(self, session_key: str) -> Optional[SessionEntry]:
+    def reset_session(self, session_key: str, display_name: Optional[str] = None) -> Optional[SessionEntry]:
         """Force reset a session, creating a new session ID."""
         db_end_session_id = None
         db_create_kwargs = None
@@ -1140,7 +1145,7 @@ class SessionStore:
                 created_at=now,
                 updated_at=now,
                 origin=old_entry.origin,
-                display_name=old_entry.display_name,
+                display_name=display_name if display_name is not None else old_entry.display_name,
                 platform=old_entry.platform,
                 chat_type=old_entry.chat_type,
                 is_fresh_reset=True,

gateway/status.py

@@ -637,6 +637,8 @@ def release_all_scoped_locks(
 
 _TAKEOVER_MARKER_FILENAME = ".gateway-takeover.json"
 _TAKEOVER_MARKER_TTL_S = 60  # Marker older than this is treated as stale
+_PLANNED_STOP_MARKER_FILENAME = ".gateway-planned-stop.json"
+_PLANNED_STOP_MARKER_TTL_S = 60
 
 
 def _get_takeover_marker_path() -> Path:
@@ -645,6 +647,67 @@ def _get_takeover_marker_path() -> Path:
     return home / _TAKEOVER_MARKER_FILENAME
 
 
+def _get_planned_stop_marker_path() -> Path:
+    """Return the path to the intentional gateway stop marker file."""
+    home = get_hermes_home()
+    return home / _PLANNED_STOP_MARKER_FILENAME
+
+
+def _marker_is_stale(written_at: str, ttl_s: int) -> bool:
+    try:
+        written_dt = datetime.fromisoformat(written_at)
+        age = (datetime.now(timezone.utc) - written_dt).total_seconds()
+        return age > ttl_s
+    except (TypeError, ValueError):
+        return True
+
+
+def _consume_pid_marker_for_self(
+    path: Path,
+    *,
+    pid_field: str,
+    start_time_field: str,
+    ttl_s: int,
+) -> bool:
+    record = _read_json_file(path)
+    if not record:
+        return False
+
+    try:
+        target_pid = int(record[pid_field])
+        target_start_time = record.get(start_time_field)
+        written_at = record.get("written_at") or ""
+    except (KeyError, TypeError, ValueError):
+        try:
+            path.unlink(missing_ok=True)
+        except OSError:
+            pass
+        return False
+
+    if _marker_is_stale(written_at, ttl_s):
+        try:
+            path.unlink(missing_ok=True)
+        except OSError:
+            pass
+        return False
+
+    our_pid = os.getpid()
+    our_start_time = _get_process_start_time(our_pid)
+    matches = (
+        target_pid == our_pid
+        and target_start_time is not None
+        and our_start_time is not None
+        and target_start_time == our_start_time
+    )
+
+    try:
+        path.unlink(missing_ok=True)
+    except OSError:
+        pass
+
+    return matches
+
+
 def write_takeover_marker(target_pid: int) -> bool:
     """Record that ``target_pid`` is being replaced by the current process.
 
@@ -681,59 +744,13 @@ def consume_takeover_marker_for_self() -> bool:
     Always unlinks the marker on match (and on detected staleness) so
     subsequent unrelated signals don't re-trigger.
     """
-    path = _get_takeover_marker_path()
-    record = _read_json_file(path)
-    if not record:
-        return False
-
-    # Any malformed or stale marker → drop it and return False
-    try:
-        target_pid = int(record["target_pid"])
-        target_start_time = record.get("target_start_time")
-        written_at = record.get("written_at") or ""
-    except (KeyError, TypeError, ValueError):
-        try:
-            path.unlink(missing_ok=True)
-        except OSError:
-            pass
-        return False
-
-    # TTL guard: a stale marker older than _TAKEOVER_MARKER_TTL_S is ignored.
-    stale = False
-    try:
-        written_dt = datetime.fromisoformat(written_at)
-        age = (datetime.now(timezone.utc) - written_dt).total_seconds()
-        if age > _TAKEOVER_MARKER_TTL_S:
-            stale = True
-    except (TypeError, ValueError):
-        stale = True  # Unparseable timestamp — treat as stale
-
-    if stale:
-        try:
-            path.unlink(missing_ok=True)
-        except OSError:
-            pass
-        return False
-
-    # Does the marker name THIS process?
-    our_pid = os.getpid()
-    our_start_time = _get_process_start_time(our_pid)
-    matches = (
-        target_pid == our_pid
-        and target_start_time is not None
-        and our_start_time is not None
-        and target_start_time == our_start_time
+    return _consume_pid_marker_for_self(
+        _get_takeover_marker_path(),
+        pid_field="target_pid",
+        start_time_field="target_start_time",
+        ttl_s=_TAKEOVER_MARKER_TTL_S,
     )
 
-    # Consume the marker whether it matched or not — a marker that doesn't
-    # match our identity is stale-for-us anyway.
-    try:
-        path.unlink(missing_ok=True)
-    except OSError:
-        pass
-
-    return matches
-
 
 def clear_takeover_marker() -> None:
     """Remove the takeover marker unconditionally. Safe to call repeatedly."""
@@ -743,6 +760,45 @@ def clear_takeover_marker() -> None:
         pass
 
 
+def write_planned_stop_marker(target_pid: int) -> bool:
+    """Record that ``target_pid`` is being stopped intentionally.
+
+    The gateway exits non-zero for unexpected SIGTERM so service managers can
+    revive it. Service stop commands send the same SIGTERM, so the CLI writes
+    this short-lived marker first to let the target process exit cleanly.
+    """
+    try:
+        target_start_time = _get_process_start_time(target_pid)
+        record = {
+            "target_pid": target_pid,
+            "target_start_time": target_start_time,
+            "stopper_pid": os.getpid(),
+            "written_at": _utc_now_iso(),
+        }
+        _write_json_file(_get_planned_stop_marker_path(), record)
+        return True
+    except (OSError, PermissionError):
+        return False
+
+
+def consume_planned_stop_marker_for_self() -> bool:
+    """Return True when the current process is being intentionally stopped."""
+    return _consume_pid_marker_for_self(
+        _get_planned_stop_marker_path(),
+        pid_field="target_pid",
+        start_time_field="target_start_time",
+        ttl_s=_PLANNED_STOP_MARKER_TTL_S,
+    )
+
+
+def clear_planned_stop_marker() -> None:
+    """Remove the planned-stop marker unconditionally."""
+    try:
+        _get_planned_stop_marker_path().unlink(missing_ok=True)
+    except OSError:
+        pass
+
+
 def get_running_pid(
     pid_path: Optional[Path] = None,
     *,

hermes_cli/__init__.py

@@ -5,11 +5,43 @@ Provides subcommands for:
 - hermes chat          - Interactive chat (same as ./hermes)
 - hermes gateway       - Run gateway in foreground
 - hermes gateway start - Start gateway service
-- hermes gateway stop  - Stop gateway service  
+- hermes gateway stop  - Stop gateway service
 - hermes setup         - Interactive setup wizard
 - hermes status        - Show status of all components
 - hermes cron          - Manage cron jobs
 """
 
+import os
+import sys
+
 __version__ = "0.12.0"
 __release_date__ = "2026.4.30"
+
+
+def _ensure_utf8():
+    """Force UTF-8 stdout/stderr on Windows to prevent UnicodeEncodeError.
+
+    Windows services and terminals default to cp1252, which cannot encode
+    box-drawing characters used in CLI output. This causes unhandled
+    UnicodeEncodeError crashes on gateway startup.
+    """
+    if sys.platform != "win32":
+        return
+    os.environ.setdefault("PYTHONUTF8", "1")
+    os.environ.setdefault("PYTHONIOENCODING", "utf-8")
+    for stream_name in ("stdout", "stderr"):
+        stream = getattr(sys, stream_name, None)
+        if stream is None:
+            continue
+        try:
+            if getattr(stream, "encoding", "").lower().replace("-", "") != "utf8":
+                new_stream = open(
+                    stream.fileno(), "w", encoding="utf-8",
+                    buffering=1, closefd=False,
+                )
+                setattr(sys, stream_name, new_stream)
+        except (AttributeError, OSError):
+            pass
+
+
+_ensure_utf8()

hermes_cli/auth.py

@@ -2589,6 +2589,208 @@ def _poll_for_token(
 # Nous Portal — token refresh, agent key minting, model discovery
 # =============================================================================
 
+# -----------------------------------------------------------------------------
+# Shared Nous token store — lets OAuth credentials persist across profiles
+# so a new `hermes --profile <name> auth add nous --type oauth` can one-tap
+# import instead of running the full device-code flow every time.
+#
+# File lives at ${HERMES_SHARED_AUTH_DIR}/nous_auth.json, defaulting to
+# ~/.hermes/shared/nous_auth.json. It is OUTSIDE any named profile's
+# HERMES_HOME so named profiles (which typically live under
+# ~/.hermes/profiles/<name>/) all see the same file.
+#
+# Written on successful login and on every runtime refresh so the stored
+# refresh_token stays current even if one profile refreshes and rotates it.
+# If ever the stored refresh_token does go stale server-side, import fails
+# gracefully and the user falls back to the normal device-code flow.
+# -----------------------------------------------------------------------------
+
+NOUS_SHARED_STORE_FILENAME = "nous_auth.json"
+
+
+def _nous_shared_auth_dir() -> Path:
+    """Resolve the directory that holds the shared Nous token store.
+
+    Honors ``HERMES_SHARED_AUTH_DIR`` so tests can redirect it to a tmp
+    path without touching the real user's home. Defaults to
+    ``~/.hermes/shared/``.
+    """
+    override = os.getenv("HERMES_SHARED_AUTH_DIR", "").strip()
+    if override:
+        return Path(override).expanduser()
+    return Path.home() / ".hermes" / "shared"
+
+
+def _nous_shared_store_path() -> Path:
+    path = _nous_shared_auth_dir() / NOUS_SHARED_STORE_FILENAME
+    # Seat belt: if pytest is running and this resolves to a path under the
+    # real user's home, refuse rather than silently corrupt cross-profile
+    # state. Tests must set HERMES_SHARED_AUTH_DIR to a tmp_path (conftest
+    # does not do this automatically — mirror the _auth_file_path() guard
+    # so forgetting to set it fails loudly instead of writing to the real
+    # shared store).
+    if os.environ.get("PYTEST_CURRENT_TEST"):
+        real_home_shared = (
+            Path.home() / ".hermes" / "shared" / NOUS_SHARED_STORE_FILENAME
+        ).resolve(strict=False)
+        try:
+            resolved = path.resolve(strict=False)
+        except Exception:
+            resolved = path
+        if resolved == real_home_shared:
+            raise RuntimeError(
+                f"Refusing to touch real user shared Nous auth store during test run: "
+                f"{path}. Set HERMES_SHARED_AUTH_DIR to a tmp_path in your test fixture."
+            )
+    return path
+
+
+def _write_shared_nous_state(state: Dict[str, Any]) -> None:
+    """Persist a minimal copy of the Nous OAuth state to the shared store.
+
+    Best-effort: any failure is swallowed after logging. The shared store
+    is a convenience layer; the per-profile auth.json remains the source
+    of truth.
+
+    We deliberately omit the short-lived ``agent_key`` (24h TTL, profile-
+    specific) — only the long-lived OAuth tokens are cross-profile useful.
+    """
+    refresh_token = state.get("refresh_token")
+    access_token = state.get("access_token")
+    if not (isinstance(refresh_token, str) and refresh_token.strip()):
+        # No refresh_token = nothing worth sharing across profiles
+        return
+    if not (isinstance(access_token, str) and access_token.strip()):
+        return
+
+    shared = {
+        "_schema": 1,
+        "access_token": access_token,
+        "refresh_token": refresh_token,
+        "token_type": state.get("token_type") or "Bearer",
+        "scope": state.get("scope") or DEFAULT_NOUS_SCOPE,
+        "client_id": state.get("client_id") or DEFAULT_NOUS_CLIENT_ID,
+        "portal_base_url": state.get("portal_base_url") or DEFAULT_NOUS_PORTAL_URL,
+        "inference_base_url": state.get("inference_base_url") or DEFAULT_NOUS_INFERENCE_URL,
+        "obtained_at": state.get("obtained_at"),
+        "expires_at": state.get("expires_at"),
+        "updated_at": datetime.now(timezone.utc).isoformat(),
+    }
+    try:
+        path = _nous_shared_store_path()
+        path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = path.with_suffix(path.suffix + ".tmp")
+        tmp.write_text(json.dumps(shared, indent=2, sort_keys=True))
+        try:
+            os.chmod(tmp, 0o600)
+        except OSError:
+            pass
+        os.replace(tmp, path)
+        _oauth_trace(
+            "nous_shared_store_written",
+            path=str(path),
+            refresh_token_fp=_token_fingerprint(refresh_token),
+        )
+    except Exception as exc:
+        logger.debug("Failed to write shared Nous auth store: %s", exc)
+
+
+def _read_shared_nous_state() -> Optional[Dict[str, Any]]:
+    """Return the shared Nous OAuth state if present and well-formed.
+
+    Returns ``None`` when the file is missing, unreadable, malformed, or
+    lacks required fields. Callers should treat ``None`` as "no shared
+    credentials available — fall through to device-code".
+    """
+    try:
+        path = _nous_shared_store_path()
+    except RuntimeError:
+        # Test seat belt tripped — treat as missing
+        return None
+    if not path.is_file():
+        return None
+    try:
+        payload = json.loads(path.read_text())
+    except (OSError, ValueError) as exc:
+        logger.debug("Shared Nous auth store at %s is unreadable: %s", path, exc)
+        return None
+    if not isinstance(payload, dict):
+        return None
+    refresh_token = payload.get("refresh_token")
+    access_token = payload.get("access_token")
+    if not (isinstance(refresh_token, str) and refresh_token.strip()):
+        return None
+    if not (isinstance(access_token, str) and access_token.strip()):
+        return None
+    return payload
+
+
+def _try_import_shared_nous_state(
+    *,
+    timeout_seconds: float = 15.0,
+    min_key_ttl_seconds: int = 5 * 60,
+) -> Optional[Dict[str, Any]]:
+    """Attempt to rehydrate Nous OAuth state from the shared store.
+
+    Reads the shared file (if present), runs a forced refresh+mint using
+    the stored refresh_token to produce a fresh access_token + agent_key
+    scoped to this profile, and returns the full auth_state dict ready
+    for ``persist_nous_credentials()``.
+
+    Returns ``None`` when no shared state is available or the rehydrate
+    fails for any reason (expired refresh_token, portal unreachable,
+    etc.) — caller should then fall through to the normal device-code
+    flow.
+    """
+    shared = _read_shared_nous_state()
+    if not shared:
+        return None
+
+    # Build a full state dict so refresh_nous_oauth_from_state has every
+    # field it needs. force_refresh=True gets us a fresh access_token
+    # for this profile; force_mint=True gets us a fresh agent_key.
+    state: Dict[str, Any] = {
+        "access_token": shared.get("access_token"),
+        "refresh_token": shared.get("refresh_token"),
+        "client_id": shared.get("client_id") or DEFAULT_NOUS_CLIENT_ID,
+        "portal_base_url": shared.get("portal_base_url") or DEFAULT_NOUS_PORTAL_URL,
+        "inference_base_url": shared.get("inference_base_url") or DEFAULT_NOUS_INFERENCE_URL,
+        "token_type": shared.get("token_type") or "Bearer",
+        "scope": shared.get("scope") or DEFAULT_NOUS_SCOPE,
+        "obtained_at": shared.get("obtained_at"),
+        "expires_at": shared.get("expires_at"),
+        "agent_key": None,
+        "agent_key_expires_at": None,
+        "tls": {"insecure": False, "ca_bundle": None},
+    }
+
+    try:
+        refreshed = refresh_nous_oauth_from_state(
+            state,
+            min_key_ttl_seconds=min_key_ttl_seconds,
+            timeout_seconds=timeout_seconds,
+            force_refresh=True,
+            force_mint=True,
+        )
+    except AuthError as exc:
+        _oauth_trace(
+            "nous_shared_import_failed",
+            error_type=type(exc).__name__,
+            error_code=getattr(exc, "code", None),
+        )
+        logger.debug("Shared Nous import failed: %s", exc)
+        return None
+    except Exception as exc:
+        _oauth_trace(
+            "nous_shared_import_failed",
+            error_type=type(exc).__name__,
+        )
+        logger.debug("Shared Nous import failed: %s", exc)
+        return None
+
+    return refreshed
+
+
 def _refresh_access_token(
     *,
     client: httpx.Client,
@@ -2991,6 +3193,12 @@ def persist_nous_credentials(
         _save_provider_state(auth_store, "nous", state)
         _save_auth_store(auth_store)
 
+    # Mirror to the shared store so a new profile can one-tap import
+    # these credentials via `hermes auth add nous --type oauth`. Best-
+    # effort: any I/O failure is logged and swallowed (the per-profile
+    # auth.json is still the source of truth).
+    _write_shared_nous_state(state)
+
     pool = load_pool("nous")
     return next(
         (e for e in pool.entries() if e.source == NOUS_DEVICE_CODE_SOURCE),
@@ -3059,6 +3267,11 @@ def resolve_nous_runtime_credentials(
                 refresh_token_fp=_token_fingerprint(state.get("refresh_token")),
                 access_token_fp=_token_fingerprint(state.get("access_token")),
             )
+            # Mirror post-refresh state to the shared store so sibling
+            # profiles don't hold stale refresh_tokens after rotation.
+            # Best-effort — any failure is logged and swallowed inside
+            # _write_shared_nous_state.
+            _write_shared_nous_state(state)
 
         verify = _resolve_verify(insecure=insecure, ca_bundle=ca_bundle, auth_state=state)
         timeout = httpx.Timeout(timeout_seconds if timeout_seconds else 15.0)
@@ -4283,7 +4496,8 @@ def _minimax_oauth_login(
     print(f"Portal: {portal_base_url}")
 
     with httpx.Client(timeout=httpx.Timeout(timeout_seconds),
-                      headers={"Accept": "application/json"}) as client:
+                      headers={"Accept": "application/json"},
+                      follow_redirects=True) as client:
         code_data = _minimax_request_user_code(
             client, portal_base_url=portal_base_url,
             client_id=pconfig.client_id,
@@ -4360,7 +4574,8 @@ def _refresh_minimax_oauth_state(
         return state
 
     portal_base_url = state["portal_base_url"]
-    with httpx.Client(timeout=httpx.Timeout(timeout_seconds)) as client:
+    with httpx.Client(timeout=httpx.Timeout(timeout_seconds),
+                      follow_redirects=True) as client:
         response = client.post(
             f"{portal_base_url}/oauth/token",
             data={
@@ -4598,17 +4813,47 @@ def _login_nous(args, pconfig: ProviderConfig) -> None:
     )
 
     try:
-        auth_state = _nous_device_code_login(
-            portal_base_url=getattr(args, "portal_url", None),
-            inference_base_url=getattr(args, "inference_url", None),
-            client_id=getattr(args, "client_id", None) or pconfig.client_id,
-            scope=getattr(args, "scope", None) or pconfig.scope,
-            open_browser=not getattr(args, "no_browser", False),
-            timeout_seconds=timeout_seconds,
-            insecure=insecure,
-            ca_bundle=ca_bundle,
-            min_key_ttl_seconds=5 * 60,
-        )
+        auth_state = None
+
+        # Codex-style auto-import: before launching a fresh device-code
+        # flow, check the shared store for an existing Nous credential
+        # from any other profile. If present, offer to rehydrate it.
+        shared = _read_shared_nous_state()
+        if shared:
+            try:
+                shared_path = _nous_shared_store_path()
+            except RuntimeError:
+                shared_path = None
+            print()
+            if shared_path:
+                print(f"Found existing Nous OAuth credentials at {shared_path}")
+            else:
+                print("Found existing shared Nous OAuth credentials")
+            try:
+                do_import = input("Import these credentials? [Y/n]: ").strip().lower()
+            except (EOFError, KeyboardInterrupt):
+                do_import = "y"
+            if do_import in ("", "y", "yes"):
+                print("Rehydrating Nous session from shared credentials...")
+                auth_state = _try_import_shared_nous_state(
+                    timeout_seconds=timeout_seconds,
+                    min_key_ttl_seconds=5 * 60,
+                )
+                if auth_state is None:
+                    print("Could not refresh shared credentials — falling back to device-code login.")
+
+        if auth_state is None:
+            auth_state = _nous_device_code_login(
+                portal_base_url=getattr(args, "portal_url", None),
+                inference_base_url=getattr(args, "inference_url", None),
+                client_id=getattr(args, "client_id", None) or pconfig.client_id,
+                scope=getattr(args, "scope", None) or pconfig.scope,
+                open_browser=not getattr(args, "no_browser", False),
+                timeout_seconds=timeout_seconds,
+                insecure=insecure,
+                ca_bundle=ca_bundle,
+                min_key_ttl_seconds=5 * 60,
+            )
 
         inference_base_url = auth_state["inference_base_url"]
 
@@ -4625,6 +4870,11 @@ def _login_nous(args, pconfig: ProviderConfig) -> None:
             _save_provider_state(auth_store, "nous", auth_state)
             saved_to = _save_auth_store(auth_store)
 
+        # Mirror to the shared store so other profiles can one-tap import
+        # these credentials. Best-effort: any I/O failure is logged and
+        # swallowed inside the helper.
+        _write_shared_nous_state(auth_state)
+
         print()
         print("Login successful!")
         print(f"  Auth state: {saved_to}")

hermes_cli/auth_commands.py

@@ -245,6 +245,47 @@ def auth_add_command(args) -> None:
         return
 
     if provider == "nous":
+        # Codex-style auto-import: if a shared Nous credential lives at
+        # ~/.hermes/shared/nous_auth.json (written by any previous
+        # successful login), offer to import it instead of running the
+        # full device-code flow. This makes `hermes --profile <name>
+        # auth add nous --type oauth` a one-tap operation for users who
+        # run multiple profiles.
+        shared = auth_mod._read_shared_nous_state()
+        if shared:
+            try:
+                path = auth_mod._nous_shared_store_path()
+            except RuntimeError:
+                path = None
+            print()
+            if path:
+                print(f"Found existing Nous OAuth credentials at {path}")
+            else:
+                print("Found existing shared Nous OAuth credentials")
+            try:
+                do_import = input("Import these credentials? [Y/n]: ").strip().lower()
+            except (EOFError, KeyboardInterrupt):
+                do_import = "y"
+            if do_import in ("", "y", "yes"):
+                print("Rehydrating Nous session from shared credentials...")
+                rehydrated = auth_mod._try_import_shared_nous_state(
+                    timeout_seconds=getattr(args, "timeout", None) or 15.0,
+                    min_key_ttl_seconds=max(
+                        60, int(getattr(args, "min_key_ttl_seconds", 5 * 60))
+                    ),
+                )
+                if rehydrated is not None:
+                    custom_label = (getattr(args, "label", None) or "").strip() or None
+                    entry = auth_mod.persist_nous_credentials(rehydrated, label=custom_label)
+                    shown_label = entry.label if entry is not None else label_from_token(
+                        rehydrated.get("access_token", ""), _oauth_default_label(provider, 1),
+                    )
+                    print(f'Imported {provider} OAuth credentials: "{shown_label}"')
+                    return
+                # Rehydrate failed (expired refresh_token, portal down, etc.)
+                # — fall through to device-code flow.
+                print("Could not refresh shared credentials — falling back to device-code login.")
+
         creds = auth_mod._nous_device_code_login(
             portal_base_url=getattr(args, "portal_url", None),
             inference_base_url=getattr(args, "inference_url", None),

hermes_cli/backup.py

@@ -61,6 +61,9 @@ _EXCLUDED_NAMES = {
     "cron.pid",
 }
 
+# zipfile.open() drops Unix mode bits on extract; restore tightens these to 0600.
+_SECRET_FILE_NAMES = {".env", "auth.json", "state.db"}
+
 
 def _should_exclude(rel_path: Path) -> bool:
     """Return True if *rel_path* (relative to hermes root) should be skipped."""
@@ -381,6 +384,8 @@ def run_import(args) -> None:
                 target.parent.mkdir(parents=True, exist_ok=True)
                 with zf.open(member) as src, open(target, "wb") as dst:
                     dst.write(src.read())
+                if target.name in _SECRET_FILE_NAMES:
+                    os.chmod(target, 0o600)
                 restored += 1
             except (PermissionError, OSError) as exc:
                 errors.append(f"  {rel}: {exc}")
@@ -788,9 +793,17 @@ def _prune_pre_update_backups(backup_dir: Path, keep: int) -> int:
     Returns the number of files deleted.  Only touches files matching
     ``pre-update-*.zip`` so hand-made zips dropped in the same directory
     are never touched.
+
+    ``keep`` is floored to 1 because this helper is only called immediately
+    after a fresh backup is written: deleting that backup right after the
+    user paid the disk/CPU cost to create it would leave them worse off
+    than no backup at all (and the wrapper in ``main.py`` would still print
+    a misleading ``Saved: <path>`` line for a file that no longer exists).
+    Operators who genuinely don't want a backup should set
+    ``updates.pre_update_backup: false`` in config — that gates creation.
     """
-    if keep < 0:
-        keep = 0
+    if keep < 1:
+        keep = 1
     if not backup_dir.exists():
         return 0
 

hermes_cli/commands.py

@@ -64,7 +64,9 @@ class CommandDef:
 COMMAND_REGISTRY: list[CommandDef] = [
     # Session
     CommandDef("new", "Start a new session (fresh session ID + history)", "Session",
-               aliases=("reset",)),
+               aliases=("reset",), args_hint="[name]"),
+    CommandDef("topic", "Enable or inspect Telegram DM topic sessions", "Session",
+               gateway_only=True, args_hint="[off|help|session-id]"),
     CommandDef("clear", "Clear screen and start a new session", "Session",
                cli_only=True),
     CommandDef("redraw", "Force a full UI repaint (recovers from terminal drift)", "Session",
@@ -399,6 +401,11 @@ def _is_gateway_available(cmd: CommandDef, config_overrides: set[str] | None = N
     return False
 
 
+def _requires_argument(args_hint: str) -> bool:
+    """Return True when selecting a command without text would be incomplete."""
+    return args_hint.strip().startswith("<")
+
+
 def gateway_help_lines() -> list[str]:
     """Generate gateway help text lines from the registry."""
     overrides = _resolve_config_gates()
@@ -455,7 +462,9 @@ def telegram_bot_commands() -> list[tuple[str, str]]:
 
     Telegram command names cannot contain hyphens, so they are replaced with
     underscores.  Aliases are skipped -- Telegram shows one menu entry per
-    canonical command.
+    canonical command. Commands that require arguments are skipped because
+    selecting a Telegram BotCommand sends only ``/command`` and would execute
+    an incomplete command.
 
     Plugin-registered slash commands are included so plugins get native
     autocomplete in Telegram without touching core code.
@@ -465,10 +474,14 @@ def telegram_bot_commands() -> list[tuple[str, str]]:
     for cmd in COMMAND_REGISTRY:
         if not _is_gateway_available(cmd, overrides):
             continue
+        if _requires_argument(cmd.args_hint):
+            continue
         tg_name = _sanitize_telegram_name(cmd.name)
         if tg_name:
             result.append((tg_name, cmd.description))
-    for name, description, _args_hint in _iter_plugin_command_entries():
+    for name, description, args_hint in _iter_plugin_command_entries():
+        if _requires_argument(args_hint):
+            continue
         tg_name = _sanitize_telegram_name(name)
         if tg_name:
             result.append((tg_name, description))
@@ -502,9 +515,9 @@ def _sanitize_telegram_name(raw: str) -> str:
 
 
 def _clamp_command_names(
-    entries: list[tuple[str, str]],
+    entries: list[tuple[str, ...]],
     reserved: set[str],
-) -> list[tuple[str, str]]:
+) -> list[tuple[str, ...]]:
     """Enforce 32-char command name limit with collision avoidance.
 
     Both Telegram and Discord cap slash command names at 32 characters.
@@ -512,10 +525,15 @@ def _clamp_command_names(
     (against *reserved* names or earlier entries in the same batch), the name is
     shortened to 31 chars and a digit ``0``-``9`` is appended to differentiate.
     If all 10 digit slots are taken the entry is silently dropped.
+
+    Accepts tuples of any length >= 2.  Extra elements beyond ``(name, desc)``
+    (e.g. ``cmd_key``) are passed through unchanged, so callers can attach
+    metadata that survives the rename.
     """
     used: set[str] = set(reserved)
-    result: list[tuple[str, str]] = []
-    for name, desc in entries:
+    result: list[tuple] = []
+    for entry in entries:
+        name, desc, *extra = entry
         if len(name) > _CMD_NAME_LIMIT:
             candidate = name[:_CMD_NAME_LIMIT]
             if candidate in used:
@@ -531,7 +549,7 @@ def _clamp_command_names(
         if name in used:
             continue
         used.add(name)
-        result.append((name, desc))
+        result.append((name, desc, *extra))
     return result
 
 
@@ -651,17 +669,15 @@ def _collect_gateway_skill_entries(
     except Exception:
         pass
 
-    # Clamp names; _clamp_command_names works on (name, desc) pairs so we
-    # need to zip/unzip.
-    skill_pairs = [(n, d) for n, d, _ in skill_triples]
-    key_by_pair = {(n, d): k for n, d, k in skill_triples}
-    skill_pairs = _clamp_command_names(skill_pairs, reserved_names)
+    # Clamp names; cmd_key is passed through as extra payload so it survives
+    # any clamp-induced renames.
+    skill_triples = _clamp_command_names(skill_triples, reserved_names)
 
     # Skills fill remaining slots — only tier that gets trimmed
     remaining = max(0, max_slots - len(all_entries))
-    hidden_count = max(0, len(skill_pairs) - remaining)
-    for n, d in skill_pairs[:remaining]:
-        all_entries.append((n, d, key_by_pair.get((n, d), "")))
+    hidden_count = max(0, len(skill_triples) - remaining)
+    for n, d, k in skill_triples[:remaining]:
+        all_entries.append((n, d, k))
 
     return all_entries[:max_slots], hidden_count
 
@@ -1112,6 +1128,12 @@ class SlashCommandCompleter(Completer):
         except Exception:
             return {}
 
+    # Commands that open pickers when run without arguments.
+    # These should NOT receive a trailing space in completions because:
+    # - The TUI's submit handler applies completions on Enter if input differs
+    # - Adding space makes "/model" → "/model " which blocks picker execution
+    _PICKER_COMMANDS = frozenset({"model", "skin", "personality"})
+
     @staticmethod
     def _completion_text(cmd_name: str, word: str) -> str:
         """Return replacement text for a completion.
@@ -1120,8 +1142,17 @@ class SlashCommandCompleter(Completer):
         returning ``help`` would be a no-op and prompt_toolkit suppresses the
         menu. Appending a trailing space keeps the dropdown visible and makes
         backspacing retrigger it naturally.
+
+        However, commands that open pickers (model, skin, personality) should
+        NOT get a trailing space — the TUI would apply the completion on Enter
+        and block the picker from opening.
         """
-        return f"{cmd_name} " if cmd_name == word else cmd_name
+        if cmd_name != word:
+            return cmd_name
+        # Don't add space for picker commands — allows Enter to execute them
+        if cmd_name in SlashCommandCompleter._PICKER_COMMANDS:
+            return cmd_name
+        return f"{cmd_name} "
 
     @staticmethod
     def _extract_path_word(text: str) -> str | None:

hermes_cli/config.py

@@ -809,6 +809,7 @@ DEFAULT_CONFIG = {
             "enabled": False,
             "fields": ["model", "context_pct", "cwd"],  # Order shown; drop any to hide
         },
+        "copy_shortcut": "auto",  # "auto" (platform default) | "ctrl_c" | "ctrl_shift_c" | "disabled"
     },
 
     # Web dashboard settings
@@ -1286,7 +1287,10 @@ DEFAULT_CONFIG = {
         # for a single update run.
         "pre_update_backup": False,
         # How many pre-update backup zips to retain.  Older ones are pruned
-        # automatically after each successful backup.
+        # automatically after each successful backup.  Values below 1 are
+        # floored to 1 — the backup just created is always preserved.  To
+        # disable backups entirely, set ``pre_update_backup: false`` above
+        # rather than ``backup_keep: 0``.
         "backup_keep": 5,
     },
 
@@ -4675,7 +4679,9 @@ def set_config_value(key: str, value: str):
         "terminal.vercel_runtime": "TERMINAL_VERCEL_RUNTIME",
         "terminal.docker_mount_cwd_to_workspace": "TERMINAL_DOCKER_MOUNT_CWD_TO_WORKSPACE",
         "terminal.docker_run_as_host_user": "TERMINAL_DOCKER_RUN_AS_HOST_USER",
-        "terminal.cwd": "TERMINAL_CWD",
+        # terminal.cwd intentionally excluded — CLI resolves at runtime,
+        # gateway bridges it in gateway/run.py. Persisting to .env causes
+        # stale values to poison child processes.
         "terminal.timeout": "TERMINAL_TIMEOUT",
         "terminal.sandbox_dir": "TERMINAL_SANDBOX_DIR",
         "terminal.persistent_shell": "TERMINAL_PERSISTENT_SHELL",

hermes_cli/cron.py

@@ -93,6 +93,8 @@ def cron_list(show_all: bool = False):
         script = job.get("script")
         if script:
             print(f"    Script:    {script}")
+        if job.get("no_agent"):
+            print(f"    Mode:      {color('no-agent', Colors.DIM)} (script stdout delivered directly)")
         workdir = job.get("workdir")
         if workdir:
             print(f"    Workdir:   {workdir}")
@@ -172,6 +174,7 @@ 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),
+        no_agent=getattr(args, "no_agent", False) or None,
     )
     if not result.get("success"):
         print(color(f"Failed to create job: {result.get('error', 'unknown error')}", Colors.RED))
@@ -184,6 +187,8 @@ def cron_create(args):
     job_data = result.get("job", {})
     if job_data.get("script"):
         print(f"  Script: {job_data['script']}")
+    if job_data.get("no_agent"):
+        print("  Mode: no-agent (script stdout delivered directly)")
     if job_data.get("workdir"):
         print(f"  Workdir: {job_data['workdir']}")
     print(f"  Next run: {result['next_run_at']}")
@@ -225,6 +230,7 @@ def cron_edit(args):
         skills=final_skills,
         script=getattr(args, "script", None),
         workdir=getattr(args, "workdir", None),
+        no_agent=getattr(args, "no_agent", None),
     )
     if not result.get("success"):
         print(color(f"Failed to update job: {result.get('error', 'unknown error')}", Colors.RED))
@@ -240,6 +246,8 @@ def cron_edit(args):
         print("  Skills: none")
     if updated.get("script"):
         print(f"  Script: {updated['script']}")
+    if updated.get("no_agent"):
+        print("  Mode: no-agent (script stdout delivered directly)")
     if updated.get("workdir"):
         print(f"  Workdir: {updated['workdir']}")
     return 0

hermes_cli/curses_ui.py

@@ -156,6 +156,8 @@ def curses_checklist(
         flush_stdin()
         return result_holder[0] if result_holder[0] is not None else cancel_returns
 
+    except KeyboardInterrupt:
+        return cancel_returns
     except Exception:
         return _numbered_fallback(title, items, selected, cancel_returns, status_fn)
 
@@ -278,6 +280,8 @@ def curses_radiolist(
         flush_stdin()
         return result_holder[0] if result_holder[0] is not None else cancel_returns
 
+    except KeyboardInterrupt:
+        return cancel_returns
     except Exception:
         return _radio_numbered_fallback(title, items, selected, cancel_returns)
 
@@ -401,6 +405,8 @@ def curses_single_select(
             return None
         return result_holder[0]
 
+    except KeyboardInterrupt:
+        return None
     except Exception:
         all_items = list(items) + [cancel_label]
         cancel_idx = len(items)

hermes_cli/debug.py

@@ -1,12 +1,19 @@
-"""``hermes debug`` — debug tools for Hermes Agent.
+"""``hermes debug`` debug tools for Hermes Agent.
 
 Currently supports:
     hermes debug share    Upload debug report (system info + logs) to a
                           paste service and print a shareable URL.
+                          By default, log content is run through
+                          ``agent.redact.redact_sensitive_text`` with
+                          ``force=True`` before upload so credentials in
+                          ``~/.hermes/logs/*.log`` are not leaked into
+                          the public paste service. Pass ``--no-redact``
+                          to disable.
 """
 
 import io
 import json
+import logging
 import sys
 import time
 import urllib.error
@@ -19,6 +26,16 @@ from typing import Optional
 from hermes_constants import get_hermes_home
 from utils import atomic_replace
 
+logger = logging.getLogger(__name__)
+
+# Banner prepended to upload-bound log content when redaction is enabled.
+# Visible in the public paste so reviewers know the content was sanitized.
+# Kept short; the trailing newline guarantees the banner sits on its own line.
+_REDACTION_BANNER = (
+    "[hermes debug share: log content redacted at upload time. "
+    "run with --no-redact to disable]\n"
+)
+
 
 # ---------------------------------------------------------------------------
 # Paste services — try paste.rs first, dpaste.com as fallback.
@@ -368,17 +385,40 @@ def _resolve_log_path(log_name: str) -> Optional[Path]:
     return None
 
 
+def _redact_log_text(text: str) -> str:
+    """Run ``redact_sensitive_text`` with ``force=True`` over upload-bound text.
+
+    Uses ``force=True`` so redaction fires regardless of the operator's
+    ``security.redact_secrets`` setting. The local on-disk log file is
+    not modified; only the in-memory copy headed for the public paste
+    service is sanitized. Returns the redacted text (or the original
+    when empty / non-string).
+    """
+    if not text:
+        return text
+    from agent.redact import redact_sensitive_text
+
+    return redact_sensitive_text(text, force=True)
+
+
 def _capture_log_snapshot(
     log_name: str,
     *,
     tail_lines: int,
     max_bytes: int = _MAX_LOG_BYTES,
+    redact: bool = True,
 ) -> LogSnapshot:
     """Capture a log once and derive summary/full-log views from it.
 
     The report tail and standalone log upload must come from the same file
     snapshot. Otherwise a rotation/truncate between reads can make the report
     look newer than the uploaded ``agent.log`` paste.
+
+    When ``redact`` is True (the default), both ``tail_text`` and
+    ``full_text`` are run through ``_redact_log_text`` so the snapshot
+    returned is upload-safe. The on-disk log file is never modified.
+    Pass ``redact=False`` to capture original log content (used by
+    ``hermes debug share --no-redact``).
     """
     log_path = _resolve_log_path(log_name)
     if log_path is None:
@@ -438,18 +478,34 @@ def _capture_log_snapshot(
         if truncated:
             full_text = f"[... truncated — showing last ~{max_bytes // 1024}KB ...]\n{full_text}"
 
+        if redact:
+            tail_text = _redact_log_text(tail_text)
+            full_text = _redact_log_text(full_text)
+
         return LogSnapshot(path=log_path, tail_text=tail_text, full_text=full_text)
     except Exception as exc:
         return LogSnapshot(path=log_path, tail_text=f"(error reading: {exc})", full_text=None)
 
 
-def _capture_default_log_snapshots(log_lines: int) -> dict[str, LogSnapshot]:
-    """Capture all logs used by debug-share exactly once."""
+def _capture_default_log_snapshots(
+    log_lines: int, *, redact: bool = True
+) -> dict[str, LogSnapshot]:
+    """Capture all logs used by debug-share exactly once.
+
+    ``redact`` is forwarded to each ``_capture_log_snapshot`` call so all
+    captured logs share the same redaction policy for a given run.
+    """
     errors_lines = min(log_lines, 100)
     return {
-        "agent": _capture_log_snapshot("agent", tail_lines=log_lines),
-        "errors": _capture_log_snapshot("errors", tail_lines=errors_lines),
-        "gateway": _capture_log_snapshot("gateway", tail_lines=errors_lines),
+        "agent": _capture_log_snapshot(
+            "agent", tail_lines=log_lines, redact=redact
+        ),
+        "errors": _capture_log_snapshot(
+            "errors", tail_lines=errors_lines, redact=redact
+        ),
+        "gateway": _capture_log_snapshot(
+            "gateway", tail_lines=errors_lines, redact=redact
+        ),
     }
 
 
@@ -532,6 +588,7 @@ def run_debug_share(args):
     log_lines = getattr(args, "lines", 200)
     expiry = getattr(args, "expire", 7)
     local_only = getattr(args, "local", False)
+    redact = not getattr(args, "no_redact", False)
 
     if not local_only:
         print(_PRIVACY_NOTICE)
@@ -539,8 +596,16 @@ def run_debug_share(args):
     print("Collecting debug report...")
 
     # Capture dump once — prepended to every paste for context.
+    # The dump is already redacted at extract time via dump.py:_redact;
+    # log_snapshots are redacted by _capture_default_log_snapshots when
+    # redact=True so credentials never reach the public paste service.
     dump_text = _capture_dump()
-    log_snapshots = _capture_default_log_snapshots(log_lines)
+    log_snapshots = _capture_default_log_snapshots(log_lines, redact=redact)
+
+    if redact:
+        logger.info(
+            "hermes debug share: applied force-mode redaction to log snapshots before upload"
+        )
 
     report = collect_debug_report(
         log_lines=log_lines,
@@ -556,6 +621,15 @@ def run_debug_share(args):
     if gateway_log:
         gateway_log = dump_text + "\n\n--- full gateway.log ---\n" + gateway_log
 
+    # Visible banner so reviewers reading the public paste know redaction
+    # was applied at upload time. Banner is omitted under --no-redact.
+    if redact:
+        report = _REDACTION_BANNER + report
+        if agent_log:
+            agent_log = _REDACTION_BANNER + agent_log
+        if gateway_log:
+            gateway_log = _REDACTION_BANNER + gateway_log
+
     if local_only:
         print(report)
         if agent_log:
@@ -666,6 +740,7 @@ def run_debug(args):
         print("  --lines N    Number of log lines to include (default: 200)")
         print("  --expire N   Paste expiry in days (default: 7)")
         print("  --local      Print report locally instead of uploading")
+        print("  --no-redact  Disable upload-time secret redaction (default: redact)")
         print()
         print("Options (delete):")
         print("  <url> ...    One or more paste URLs to delete")

hermes_cli/doctor.py

@@ -935,6 +935,8 @@ def run_doctor(args):
         agent_browser_path = PROJECT_ROOT / "node_modules" / "agent-browser"
         if agent_browser_path.exists():
             check_ok("agent-browser (Node.js)", "(browser automation)")
+        elif shutil.which("agent-browser"):
+            check_ok("agent-browser", "(browser automation)")
         else:
             if _is_termux():
                 check_info("agent-browser is not installed (expected in the tested Termux path)")
@@ -1096,9 +1098,10 @@ def run_doctor(args):
         ("Hugging Face",     ("HF_TOKEN",),                                   "https://router.huggingface.co/v1/models", "HF_BASE_URL", True),
         ("NVIDIA NIM",       ("NVIDIA_API_KEY",),                             "https://integrate.api.nvidia.com/v1/models", "NVIDIA_BASE_URL", True),
         ("Alibaba/DashScope", ("DASHSCOPE_API_KEY",),                         "https://dashscope-intl.aliyuncs.com/compatible-mode/v1/models", "DASHSCOPE_BASE_URL", True),
-        # MiniMax: the /anthropic endpoint doesn't support /models, but the /v1 endpoint does.
+        # MiniMax global: /v1 endpoint supports /models.
         ("MiniMax",          ("MINIMAX_API_KEY",),                            "https://api.minimax.io/v1/models",    "MINIMAX_BASE_URL", True),
-        ("MiniMax (China)",  ("MINIMAX_CN_API_KEY",),                         "https://api.minimaxi.com/v1/models",  "MINIMAX_CN_BASE_URL", True),
+        # MiniMax CN: /v1 endpoint does NOT support /models (returns 404).
+        ("MiniMax (China)",  ("MINIMAX_CN_API_KEY",),                         "https://api.minimaxi.com/v1/models",  "MINIMAX_CN_BASE_URL", False),
         ("Vercel AI Gateway",       ("AI_GATEWAY_API_KEY",),                          "https://ai-gateway.vercel.sh/v1/models", "AI_GATEWAY_BASE_URL", True),
         ("Kilo Code",        ("KILOCODE_API_KEY",),                            "https://api.kilo.ai/api/gateway/models",  "KILOCODE_BASE_URL", True),
         ("OpenCode Zen",     ("OPENCODE_ZEN_API_KEY",),                        "https://opencode.ai/zen/v1/models",  "OPENCODE_ZEN_BASE_URL", True),
@@ -1261,9 +1264,23 @@ def run_doctor(args):
         check_warn("Skills Hub directory not initialized", "(run: hermes skills list)")
 
     from hermes_cli.config import get_env_value
+
+    def _gh_authenticated() -> bool:
+        """Check if gh CLI is authenticated via token file or device flow."""
+        try:
+            result = subprocess.run(
+                ["gh", "auth", "status", "--json", "authenticated"],
+                capture_output=True, timeout=10,
+            )
+            return result.returncode == 0
+        except (FileNotFoundError, subprocess.TimeoutExpired):
+            return False
+
     github_token = get_env_value("GITHUB_TOKEN") or get_env_value("GH_TOKEN")
     if github_token:
         check_ok("GitHub token configured (authenticated API access)")
+    elif _gh_authenticated():
+        check_ok("GitHub authenticated via gh CLI", "(full API access — no GITHUB_TOKEN needed)")
     else:
         check_warn("No GITHUB_TOKEN", f"(60 req/hr rate limit — set in {_DHH}/.env for better rates)")
 

hermes_cli/gateway.py

@@ -237,6 +237,26 @@ def _graceful_restart_via_sigusr1(pid: int, drain_timeout: float) -> bool:
     return False
 
 
+def _get_ancestor_pids() -> set[int]:
+    """Return the set of PIDs in the current process's ancestor chain.
+
+    Walks from the current PID up to PID 1 (init) so that process-table scans
+    never match the calling CLI process or any of its parents.  This prevents
+    ``hermes gateway status`` from falsely counting the ``hermes`` CLI that
+    invoked it as a running gateway instance (see #13242).
+    """
+    ancestors: set[int] = set()
+    pid = os.getpid()
+    # Cap iterations to avoid infinite loops on exotic platforms.
+    for _ in range(64):
+        ancestors.add(pid)
+        parent = _get_parent_pid(pid)
+        if parent is None or parent <= 0 or parent in ancestors:
+            break
+        pid = parent
+    return ancestors
+
+
 def _append_unique_pid(pids: list[int], pid: int | None, exclude_pids: set[int]) -> None:
     if pid is None or pid <= 0:
         return
@@ -252,6 +272,10 @@ def _scan_gateway_pids(exclude_pids: set[int], all_profiles: bool = False) -> li
     a live gateway when the PID file is stale/missing, and ``--all`` sweeps can
     discover gateways outside the current profile.
     """
+    # Exclude the entire ancestor chain so the CLI process that invoked this
+    # scan (e.g. ``hermes gateway status``) is never mistaken for a running
+    # gateway.  See #13242.
+    exclude_pids = exclude_pids | _get_ancestor_pids()
     pids: list[int] = []
     patterns = [
         "hermes_cli.main gateway",
@@ -690,6 +714,32 @@ def _print_gateway_process_mismatch(snapshot: GatewayRuntimeSnapshot) -> None:
     print("  can refuse to start another copy until this process stops.")
 
 
+def _print_other_profiles_gateway_status() -> None:
+    """Print a summary of gateway status across all profiles.
+
+    Shown at the bottom of ``hermes gateway status`` output so users with
+    multiple profiles can tell at a glance which gateways are running and
+    avoid confusing another profile's process with the current one.
+    """
+    try:
+        from hermes_cli.profiles import get_active_profile_name
+
+        current = get_active_profile_name()
+        other_processes = [
+            p for p in find_profile_gateway_processes()
+            if p.profile != current
+        ]
+        if not other_processes:
+            return
+
+        print()
+        print("Other profiles:")
+        for proc in other_processes:
+            print(f"  ✓ {proc.profile:<16s} — PID {proc.pid}")
+    except Exception:
+        pass
+
+
 def kill_gateway_processes(force: bool = False, exclude_pids: set | None = None,
                            all_profiles: bool = False) -> int:
     """Kill any running gateway processes. Returns count killed.
@@ -735,6 +785,12 @@ def stop_profile_gateway() -> bool:
     if pid is None:
         return False
 
+    try:
+        from gateway.status import write_planned_stop_marker
+        write_planned_stop_marker(pid)
+    except Exception:
+        pass
+
     try:
         os.kill(pid, signal.SIGTERM)
     except ProcessLookupError:
@@ -1558,6 +1614,46 @@ def _build_user_local_paths(home: Path, path_entries: list[str]) -> list[str]:
     return [p for p in candidates if p not in path_entries and Path(p).exists()]
 
 
+def _build_wsl_interop_paths(path_entries: list[str]) -> list[str]:
+    """Return WSL Windows interop PATH entries for generated systemd units.
+
+    WSL shells normally inherit Windows PATH entries such as
+    ``/mnt/c/WINDOWS/System32``. systemd user services do not, so gateway tools
+    that call ``powershell.exe``/``cmd.exe`` work in a terminal but fail in the
+    background service unless we persist the relevant entries at install time.
+    """
+    if not is_wsl():
+        return []
+
+    candidates: list[str] = []
+    for entry in os.environ.get("PATH", "").split(os.pathsep):
+        if entry.startswith("/mnt/"):
+            candidates.append(entry)
+
+    for executable in ("powershell.exe", "cmd.exe", "explorer.exe", "wsl.exe"):
+        resolved = shutil.which(executable)
+        if resolved:
+            candidates.append(str(Path(resolved).parent))
+
+    for entry in (
+        "/mnt/c/WINDOWS/system32",
+        "/mnt/c/WINDOWS",
+        "/mnt/c/WINDOWS/System32/Wbem",
+        "/mnt/c/WINDOWS/System32/WindowsPowerShell/v1.0/",
+        "/mnt/c/WINDOWS/System32/OpenSSH/",
+    ):
+        if Path(entry).exists():
+            candidates.append(entry)
+
+    result: list[str] = []
+    seen = set(path_entries)
+    for entry in candidates:
+        if entry and entry not in seen:
+            seen.add(entry)
+            result.append(entry)
+    return result
+
+
 def _remap_path_for_user(path: str, target_home_dir: str) -> str:
     """Remap *path* from the current user's home to *target_home_dir*.
 
@@ -1649,6 +1745,7 @@ def generate_systemd_unit(system: bool = False, run_as_user: str | None = None)
         node_bin = _remap_path_for_user(node_bin, home_dir)
         path_entries = [_remap_path_for_user(p, home_dir) for p in path_entries]
         path_entries.extend(_build_user_local_paths(Path(home_dir), path_entries))
+        path_entries.extend(_build_wsl_interop_paths(path_entries))
         path_entries.extend(common_bin_paths)
         sane_path = ":".join(path_entries)
         return f"""[Unit]
@@ -1688,6 +1785,7 @@ WantedBy=multi-user.target
     hermes_home = str(get_hermes_home().resolve())
     profile_arg = _profile_arg(hermes_home)
     path_entries.extend(_build_user_local_paths(Path.home(), path_entries))
+    path_entries.extend(_build_wsl_interop_paths(path_entries))
     path_entries.extend(common_bin_paths)
     sane_path = ":".join(path_entries)
     return f"""[Unit]
@@ -1921,6 +2019,15 @@ def systemd_uninstall(system: bool = False):
     print(f"✓ {_service_scope_label(system).capitalize()} service uninstalled")
 
 
+def _require_service_installed(action: str, system: bool = False) -> None:
+    unit_path = get_systemd_unit_path(system=system)
+    if not unit_path.exists():
+        scope_flag = " --system" if system else ""
+        print(f"✗ Gateway service is not installed")
+        print(f"  Run: {'sudo ' if system else ''}hermes gateway install{scope_flag}")
+        sys.exit(1)
+
+
 def systemd_start(system: bool = False):
     system = _select_systemd_scope(system)
     if system:
@@ -1930,6 +2037,7 @@ def systemd_start(system: bool = False):
         # reachable (common on fresh RHEL/Debian SSH sessions without linger).
         # Raises UserSystemdUnavailableError with a remediation message.
         _preflight_user_systemd()
+    _require_service_installed("start", system=system)
     refresh_systemd_unit_if_needed(system=system)
     _run_systemctl(["start", get_service_name()], system=system, check=True, timeout=30)
     print(f"✓ {_service_scope_label(system).capitalize()} service started")
@@ -1940,6 +2048,14 @@ def systemd_stop(system: bool = False):
     system = _select_systemd_scope(system)
     if system:
         _require_root_for_system_service("stop")
+    _require_service_installed("stop", system=system)
+    try:
+        from gateway.status import get_running_pid, write_planned_stop_marker
+        pid = get_running_pid(cleanup_stale=False)
+        if pid is not None:
+            write_planned_stop_marker(pid)
+    except Exception:
+        pass
     _run_systemctl(["stop", get_service_name()], system=system, check=True, timeout=90)
     print(f"✓ {_service_scope_label(system).capitalize()} service stopped")
 
@@ -1951,6 +2067,7 @@ def systemd_restart(system: bool = False):
         _require_root_for_system_service("restart")
     else:
         _preflight_user_systemd()
+    _require_service_installed("restart", system=system)
     refresh_systemd_unit_if_needed(system=system)
     from gateway.status import get_running_pid
 
@@ -2300,6 +2417,13 @@ def launchd_start():
 def launchd_stop():
     label = get_launchd_label()
     target = f"{_launchd_domain()}/{label}"
+    try:
+        from gateway.status import get_running_pid, write_planned_stop_marker
+        pid = get_running_pid(cleanup_stale=False)
+        if pid is not None:
+            write_planned_stop_marker(pid)
+    except Exception:
+        pass
     # bootout unloads the service definition so KeepAlive doesn't respawn
     # the process.  A plain `kill SIGTERM` only signals the process — launchd
     # immediately restarts it because KeepAlive.SuccessfulExit = false.
@@ -2442,6 +2566,20 @@ def run_gateway(verbose: int = 0, quiet: bool = False, replace: bool = False):
                  hasn't fully exited yet.
     """
     sys.path.insert(0, str(PROJECT_ROOT))
+
+    # Refresh the systemd unit definition on every boot so that restart
+    # settings (RestartSec, StartLimitIntervalSec, etc.) stay current even
+    # when the process was respawned via exit-code-75 (stale-code or
+    # /restart) rather than through `hermes gateway restart` which already
+    # calls refresh_systemd_unit_if_needed().  Without this, a code update
+    # that ships new unit settings won't take effect until the next manual
+    # `hermes gateway start/restart` — leaving the gateway vulnerable to
+    # the exact failure mode the new settings were meant to prevent.
+    if supports_systemd_services():
+        try:
+            refresh_systemd_unit_if_needed(system=False)
+        except Exception:
+            pass  # best-effort; don't block gateway startup
     
     from gateway.run import start_gateway
     
@@ -4456,6 +4594,9 @@ def _gateway_command_inner(args):
                     print("  hermes gateway install  # Install as user service")
                     print("  sudo hermes gateway install --system  # Install as boot-time system service")
 
+        # Show other profiles' gateway status for multi-profile awareness
+        _print_other_profiles_gateway_status()
+
     elif subcmd == "migrate-legacy":
         # Stop, disable, and remove legacy Hermes gateway unit files from
         # pre-rename installs (e.g. hermes.service). Profile units and

hermes_cli/kanban.py

@@ -169,11 +169,93 @@ def build_parser(parent_subparsers: argparse._SubParsersAction) -> argparse.Argu
             "or docs/hermes-kanban-v1-spec.pdf for the full design."
         ),
     )
+    # --- global --board flag ---
+    # Applies to every subcommand below. When set, scopes all reads and
+    # writes to that board's DB. When omitted, resolves via the
+    # HERMES_KANBAN_BOARD env var, then the persisted current-board
+    # file, then "default". See kanban_db.get_current_board().
+    kanban_parser.add_argument(
+        "--board",
+        default=None,
+        metavar="<slug>",
+        help=(
+            "Board slug to operate on. Defaults to the current board "
+            "(set via `hermes kanban boards switch <slug>` or the "
+            "HERMES_KANBAN_BOARD env var). Use `hermes kanban boards list` "
+            "to see all boards."
+        ),
+    )
     sub = kanban_parser.add_subparsers(dest="kanban_action")
 
     # --- init ---
     sub.add_parser("init", help="Create kanban.db if missing (idempotent)")
 
+    # --- boards (new in v2: multi-project support) ---
+    p_boards = sub.add_parser(
+        "boards",
+        help="Manage kanban boards (one board per project / workstream)",
+        description=(
+            "Boards let you separate unrelated streams of work "
+            "(projects, repos, domains) into isolated queues. Each "
+            "board has its own DB, workspaces directory, and dispatcher "
+            "loop — tasks on one board cannot collide with tasks on "
+            "another. The first board is 'default' and always exists."
+        ),
+    )
+    boards_sub = p_boards.add_subparsers(dest="boards_action")
+
+    b_list = boards_sub.add_parser(
+        "list", aliases=["ls"],
+        help="List all boards with task counts",
+    )
+    b_list.add_argument("--json", action="store_true")
+    b_list.add_argument("--all", action="store_true",
+                        help="Include archived boards too")
+
+    b_create = boards_sub.add_parser(
+        "create", aliases=["new"],
+        help="Create a new board",
+    )
+    b_create.add_argument("slug",
+                          help="Board slug (kebab-case, e.g. atm10-server)")
+    b_create.add_argument("--name", default=None,
+                          help="Human-readable display name (defaults to Title Case of slug)")
+    b_create.add_argument("--description", default=None,
+                          help="Optional description")
+    b_create.add_argument("--icon", default=None,
+                          help="Optional emoji or single-character icon for the dashboard")
+    b_create.add_argument("--color", default=None,
+                          help="Optional hex color (e.g. '#8b5cf6') for the dashboard")
+    b_create.add_argument("--switch", action="store_true",
+                          help="Switch to the new board after creating it")
+
+    b_rm = boards_sub.add_parser(
+        "rm", aliases=["remove", "delete"],
+        help="Archive (default) or delete a board",
+    )
+    b_rm.add_argument("slug")
+    b_rm.add_argument("--delete", action="store_true",
+                      help="Hard-delete the board directory instead of archiving it. "
+                           "Default is to move it to boards/_archived/ so it's recoverable.")
+
+    b_switch = boards_sub.add_parser(
+        "switch", aliases=["use"],
+        help="Set the active board for subsequent CLI calls",
+    )
+    b_switch.add_argument("slug")
+
+    boards_sub.add_parser(
+        "show", aliases=["current"],
+        help="Print the currently-active board slug",
+    )
+
+    b_rename = boards_sub.add_parser(
+        "rename",
+        help="Change a board's human-readable display name (slug is immutable)",
+    )
+    b_rename.add_argument("slug")
+    b_rename.add_argument("name", help="New display name")
+
     # --- create ---
     p_create = sub.add_parser("create", help="Create a new task")
     p_create.add_argument("title", help="Task title")
@@ -366,7 +448,7 @@ def build_parser(parent_subparsers: argparse._SubParsersAction) -> argparse.Argu
     # --- log ---
     p_log = sub.add_parser(
         "log",
-        help="Print the worker log for a task (from $HERMES_HOME/kanban/logs/)",
+        help="Print the worker log for a task (from <kanban-root>/kanban/logs/)",
     )
     p_log.add_argument("task_id")
     p_log.add_argument("--tail", type=int, default=None,
@@ -442,6 +524,38 @@ def kanban_command(args: argparse.Namespace) -> int:
             )
         return 0
 
+    # `--board <slug>` applies to every subcommand below by way of an
+    # env-var pin for the duration of this call. Using HERMES_KANBAN_BOARD
+    # (rather than threading `board=` through 50+ kb.connect() sites)
+    # keeps the patch small and inherits the exact same resolution the
+    # dispatcher uses for workers — consistency is a feature here.
+    board_override = getattr(args, "board", None)
+    if board_override:
+        try:
+            normed = kb._normalize_board_slug(board_override)
+        except ValueError as exc:
+            print(f"kanban: {exc}", file=sys.stderr)
+            return 2
+        if not normed:
+            print("kanban: --board requires a slug", file=sys.stderr)
+            return 2
+        # Boards other than 'default' must already exist — typoed slugs
+        # would otherwise silently create an empty board.
+        if normed != kb.DEFAULT_BOARD and not kb.board_exists(normed):
+            print(
+                f"kanban: board {normed!r} does not exist. "
+                f"Create it with `hermes kanban boards create {normed}`.",
+                file=sys.stderr,
+            )
+            return 1
+        os.environ["HERMES_KANBAN_BOARD"] = normed
+
+    # Boards management doesn't touch the DB at all — dispatch early so
+    # fresh installs that haven't initialized any DB can still use
+    # `hermes kanban boards create …`.
+    if action == "boards":
+        return _dispatch_boards(args)
+
     # Auto-initialize the DB before dispatching any subcommand. init_db
     # is idempotent, so running it every invocation is cheap (one
     # SELECT against sqlite_master when tables already exist) and
@@ -513,6 +627,185 @@ def _profile_author() -> str:
         return "user"
 
 
+# ---------------------------------------------------------------------------
+# Boards management (hermes kanban boards …)
+# ---------------------------------------------------------------------------
+
+def _dispatch_boards(args: argparse.Namespace) -> int:
+    """Handle ``hermes kanban boards <action>``.
+
+    Boards management is deliberately separate from the task-level
+    commands: it operates on the filesystem (board directories,
+    ``current`` pointer, ``board.json``), not on the per-board SQLite
+    DB, so a fresh HERMES_HOME that has never called ``kanban init``
+    can still run ``boards create`` / ``boards list``.
+    """
+    sub = getattr(args, "boards_action", None) or "list"
+    if sub in ("list", "ls"):
+        return _cmd_boards_list(args)
+    if sub in ("create", "new"):
+        return _cmd_boards_create(args)
+    if sub in ("rm", "remove", "delete"):
+        return _cmd_boards_rm(args)
+    if sub in ("switch", "use"):
+        return _cmd_boards_switch(args)
+    if sub in ("show", "current"):
+        return _cmd_boards_show(args)
+    if sub == "rename":
+        return _cmd_boards_rename(args)
+    print(f"kanban boards: unknown action {sub!r}", file=sys.stderr)
+    return 2
+
+
+def _board_task_counts(slug: str) -> dict[str, int]:
+    """Return ``{status: count}`` for a board. Safe to call on an empty DB."""
+    try:
+        path = kb.kanban_db_path(board=slug)
+        if not path.exists():
+            return {}
+        with kb.connect(board=slug) as conn:
+            rows = conn.execute(
+                "SELECT status, COUNT(*) AS n FROM tasks GROUP BY status"
+            ).fetchall()
+        return {r["status"]: int(r["n"]) for r in rows}
+    except Exception:
+        return {}
+
+
+def _cmd_boards_list(args: argparse.Namespace) -> int:
+    include_archived = bool(getattr(args, "all", False))
+    boards = kb.list_boards(include_archived=include_archived)
+    # Enrich each entry with task counts + whether it's the current board.
+    current = kb.get_current_board()
+    for b in boards:
+        b["is_current"] = (b["slug"] == current)
+        b["counts"] = _board_task_counts(b["slug"])
+        b["total"] = sum(b["counts"].values())
+    if getattr(args, "json", False):
+        print(json.dumps(boards, indent=2, ensure_ascii=False))
+        return 0
+    # Human table: marker (•) for current, slug, display name, counts.
+    if not boards:
+        print("(no boards — create one with `hermes kanban boards create <slug>`)")
+        return 0
+    print(f"{'':2s}  {'SLUG':24s}  {'NAME':28s}  COUNTS")
+    for b in boards:
+        marker = "●" if b["is_current"] else " "
+        counts = b["counts"] or {}
+        counts_str = (
+            ", ".join(f"{k}={v}" for k, v in sorted(counts.items()))
+            or "(empty)"
+        )
+        name = b.get("name") or ""
+        if b.get("archived"):
+            name += " [archived]"
+        print(f"{marker:2s}  {b['slug']:24s}  {name:28s}  {counts_str}")
+    print()
+    print(f"Current board: {current}")
+    if len(boards) > 1:
+        print("Switch boards with `hermes kanban boards switch <slug>`.")
+    return 0
+
+
+def _cmd_boards_create(args: argparse.Namespace) -> int:
+    try:
+        normed = kb._normalize_board_slug(args.slug)
+    except ValueError as exc:
+        print(f"kanban boards create: {exc}", file=sys.stderr)
+        return 2
+    if not normed:
+        print("kanban boards create: slug is required", file=sys.stderr)
+        return 2
+    already = kb.board_exists(normed) and normed != kb.DEFAULT_BOARD
+    meta = kb.create_board(
+        normed,
+        name=args.name,
+        description=args.description,
+        icon=args.icon,
+        color=args.color,
+    )
+    verb = "already exists" if already else "created"
+    print(f"Board {meta['slug']!r} {verb}.")
+    print(f"  Display name: {meta.get('name', '')}")
+    print(f"  DB path:      {meta['db_path']}")
+    if getattr(args, "switch", False):
+        kb.set_current_board(meta["slug"])
+        print(f"  Switched to {meta['slug']!r}.")
+    else:
+        print(f"  Use `hermes kanban boards switch {meta['slug']}` to make it current.")
+    return 0
+
+
+def _cmd_boards_rm(args: argparse.Namespace) -> int:
+    try:
+        res = kb.remove_board(args.slug, archive=not getattr(args, "delete", False))
+    except ValueError as exc:
+        print(f"kanban boards rm: {exc}", file=sys.stderr)
+        return 1
+    if res["action"] == "archived":
+        print(f"Board {res['slug']!r} archived → {res['new_path']}")
+        print("Recover by moving the directory back to "
+              "<root>/kanban/boards/<slug>/.")
+    else:
+        print(f"Board {res['slug']!r} deleted.")
+    return 0
+
+
+def _cmd_boards_switch(args: argparse.Namespace) -> int:
+    try:
+        normed = kb._normalize_board_slug(args.slug)
+    except ValueError as exc:
+        print(f"kanban boards switch: {exc}", file=sys.stderr)
+        return 2
+    if not normed:
+        print("kanban boards switch: slug is required", file=sys.stderr)
+        return 2
+    if not kb.board_exists(normed):
+        print(
+            f"kanban boards switch: board {normed!r} does not exist. "
+            f"Create it with `hermes kanban boards create {normed}`.",
+            file=sys.stderr,
+        )
+        return 1
+    kb.set_current_board(normed)
+    print(f"Active board is now {normed!r}.")
+    return 0
+
+
+def _cmd_boards_show(args: argparse.Namespace) -> int:
+    current = kb.get_current_board()
+    meta = kb.read_board_metadata(current)
+    counts = _board_task_counts(current)
+    total = sum(counts.values())
+    print(f"Current board: {current}")
+    print(f"  Display name: {meta.get('name', '')}")
+    if meta.get("description"):
+        print(f"  Description:  {meta['description']}")
+    print(f"  DB path:      {meta['db_path']}")
+    print(f"  Tasks:        {total} total"
+          + (f" ({', '.join(f'{k}={v}' for k, v in sorted(counts.items()))})"
+             if counts else ""))
+    return 0
+
+
+def _cmd_boards_rename(args: argparse.Namespace) -> int:
+    try:
+        normed = kb._normalize_board_slug(args.slug)
+    except ValueError as exc:
+        print(f"kanban boards rename: {exc}", file=sys.stderr)
+        return 2
+    if not normed or not kb.board_exists(normed):
+        print(f"kanban boards rename: board {args.slug!r} does not exist",
+              file=sys.stderr)
+        return 1
+    meta = kb.write_board_metadata(normed, name=args.name)
+    print(f"Board {normed!r} renamed to {meta['name']!r}.")
+    return 0
+
+
+# ---------------------------------------------------------------------------
+
+
 def _parse_duration(val) -> Optional[int]:
     """Parse ``30s`` / ``5m`` / ``2h`` / ``1d`` or a raw integer → seconds.
 
@@ -662,6 +955,21 @@ def _cmd_list(args: argparse.Namespace) -> int:
     if getattr(args, "json", False):
         print(json.dumps([_task_to_dict(t) for t in tasks], indent=2, ensure_ascii=False))
         return 0
+    # Passive discoverability: when the user has multiple boards, surface
+    # which one they're looking at in the list header. Single-board users
+    # never see this — the feature stays invisible until you opt in.
+    try:
+        all_boards = kb.list_boards(include_archived=False)
+    except Exception:
+        all_boards = []
+    if len(all_boards) > 1:
+        current = kb.get_current_board()
+        other_count = len(all_boards) - 1
+        print(
+            f"Board: {current} "
+            f"({other_count} other board{'s' if other_count != 1 else ''} — "
+            f"`hermes kanban boards list`)\n"
+        )
     if not tasks:
         print("(no matching tasks)")
         return 0

hermes_cli/kanban_db.py

@@ -1,8 +1,56 @@
-"""SQLite-backed Kanban board for multi-profile collaboration.
+"""SQLite-backed Kanban board for multi-profile, multi-project collaboration.
 
-The board lives at ``$HERMES_HOME/kanban.db`` (profile-agnostic on purpose:
-multiple profiles on the same machine all see the same board, which IS the
-coordination primitive).
+In a fresh install the board lives at ``<root>/kanban.db`` where
+``<root>`` is the **shared Hermes root** (the parent of any active
+profile). Profiles intentionally collapse onto a shared board: it IS
+the cross-profile coordination primitive. A worker spawned with
+``hermes -p <profile>`` joins the same board as the dispatcher that
+claimed the task. The same applies to ``<root>/kanban/workspaces/`` and
+``<root>/kanban/logs/``.
+
+**Multiple boards (projects):** users can create additional boards to
+separate unrelated streams of work (e.g. one per project / repo / domain).
+Each board is a directory under ``<root>/kanban/boards/<slug>/`` with
+its own ``kanban.db``, ``workspaces/``, and ``logs/``. All boards share
+the profile's Hermes home but are otherwise isolated: a worker spawned
+for a task on board ``atm10-server`` sees only that board's tasks,
+cannot enumerate other boards, and its dispatcher ticks don't touch
+other boards' DBs.
+
+The first (and for single-project users, only) board is ``default``.
+For back-compat its on-disk DB is ``<root>/kanban.db`` (not
+``boards/default/kanban.db``), so installs that predate the boards
+feature keep working with zero migration. See :func:`kanban_db_path`.
+
+Board resolution order (highest precedence first, all optional):
+
+* ``board=`` argument passed directly to :func:`connect` / :func:`init_db`
+  (explicit — used by the CLI ``--board`` flag and the dashboard
+  ``?board=...`` query param).
+* ``HERMES_KANBAN_BOARD`` env var (used by the dispatcher to pin workers
+  to the board their task lives on — workers cannot see other boards).
+* ``HERMES_KANBAN_DB`` env var (pins the DB file path directly — legacy
+  override still honoured; highest precedence when the file path itself
+  is what the caller wants to force).
+* ``<root>/kanban/current`` — a one-line text file holding the slug of
+  the "currently selected" board. Written by ``hermes kanban boards
+  switch <slug>``. When absent, the active board is ``default``.
+
+In standard installs ``<root>`` is ``~/.hermes``. In Docker / custom
+deployments where ``HERMES_HOME`` points outside ``~/.hermes`` (e.g.
+``/opt/hermes``), ``<root>`` is ``HERMES_HOME``. Legacy env-var
+overrides still work:
+
+* ``HERMES_KANBAN_DB`` — pin the database file path directly.
+* ``HERMES_KANBAN_WORKSPACES_ROOT`` — pin the workspaces root directly.
+* ``HERMES_KANBAN_HOME`` — pin the umbrella root that anchors kanban
+  paths. Useful for tests and unusual deployments.
+
+The dispatcher injects ``HERMES_KANBAN_DB``,
+``HERMES_KANBAN_WORKSPACES_ROOT``, and ``HERMES_KANBAN_BOARD`` into
+worker subprocess env so workers converge on the exact DB the
+dispatcher used to claim their task — even under unusual symlink or
+Docker layouts.
 
 Schema is intentionally small: tasks, task_links, task_comments,
 task_events.  The ``workspace_kind`` field decouples coordination from git
@@ -15,6 +63,9 @@ transactions + compare-and-swap (CAS) updates on ``tasks.status`` and
 ``tasks.claim_lock``.  SQLite serializes writers via its WAL lock, so at
 most one claimer can win any given task.  Losers observe zero affected
 rows and move on -- no retry loops, no distributed-lock machinery.
+The CAS coordination is **per-board** — each board is a separate DB,
+so multi-board installs get the same atomicity guarantees without any
+new locking.
 """
 
 from __future__ import annotations
@@ -22,6 +73,7 @@ from __future__ import annotations
 import contextlib
 import json
 import os
+import re
 import secrets
 import sqlite3
 import sys
@@ -61,16 +113,438 @@ _CTX_MAX_COMMENT_BYTES  = 2 * 1024   # 2 KB per comment
 # Paths
 # ---------------------------------------------------------------------------
 
-def kanban_db_path() -> Path:
-    """Return the path to ``kanban.db`` inside the active HERMES_HOME."""
-    from hermes_constants import get_hermes_home
-    return get_hermes_home() / "kanban.db"
+DEFAULT_BOARD = "default"
+
+# Slug validator: lowercase alphanumerics, digits, hyphens; 1–64 chars.
+# Strict enough to stop traversal (`..`) and embedded path separators, loose
+# enough that kebab-case names like ``atm10-server`` or ``hermes-agent``
+# pass without fuss. Board names with display formatting (spaces, emoji)
+# live in ``board.json``; the slug is just the directory name.
+_BOARD_SLUG_RE = re.compile(r"^[a-z0-9][a-z0-9\-_]{0,63}$")
 
 
-def workspaces_root() -> Path:
-    """Return the directory under which ``scratch`` workspaces are created."""
-    from hermes_constants import get_hermes_home
-    return get_hermes_home() / "kanban" / "workspaces"
+def _normalize_board_slug(slug: Optional[str]) -> Optional[str]:
+    """Lowercase + strip a slug; validate; return ``None`` for empty."""
+    if slug is None:
+        return None
+    s = str(slug).strip().lower()
+    if not s:
+        return None
+    if not _BOARD_SLUG_RE.match(s):
+        raise ValueError(
+            f"invalid board slug {slug!r}: must be 1-64 chars, lowercase "
+            f"alphanumerics / hyphens / underscores, not starting with '-' or '_'"
+        )
+    return s
+
+
+def kanban_home() -> Path:
+    """Return the shared Hermes root that anchors the kanban board.
+
+    Resolution order:
+
+    1. ``HERMES_KANBAN_HOME`` env var when set and non-empty (explicit
+       override for tests and unusual deployments).
+    2. ``get_default_hermes_root()``, which already returns ``<root>``
+       when ``HERMES_HOME`` is ``<root>/profiles/<name>``, and returns
+       ``HERMES_HOME`` directly for Docker / custom deployments.
+
+    The kanban board is shared across profiles **by design** (see the
+    module docstring). Resolving the kanban paths through the active
+    profile's ``HERMES_HOME`` would silently fork the board per profile,
+    which breaks the dispatcher / worker handoff.
+    """
+    override = os.environ.get("HERMES_KANBAN_HOME", "").strip()
+    if override:
+        return Path(override).expanduser()
+    from hermes_constants import get_default_hermes_root
+    return get_default_hermes_root()
+
+
+def boards_root() -> Path:
+    """Return ``<root>/kanban/boards`` — the parent of non-default board dirs.
+
+    ``default`` is intentionally NOT under this directory — its DB lives at
+    ``<root>/kanban.db`` for back-compat with pre-boards installs. This
+    function returns the directory where *additional* named boards live,
+    used by :func:`list_boards` to enumerate them.
+    """
+    return kanban_home() / "kanban" / "boards"
+
+
+def current_board_path() -> Path:
+    """Return the path to ``<root>/kanban/current``.
+
+    One-line text file written by ``hermes kanban boards switch <slug>``
+    to persist the user's board selection across CLI invocations. Absent
+    by default (meaning: active board is ``default``).
+    """
+    return kanban_home() / "kanban" / "current"
+
+
+def get_current_board() -> str:
+    """Return the active board slug, honouring the resolution chain.
+
+    Order (highest precedence first):
+
+    1. ``HERMES_KANBAN_BOARD`` env var (set by the dispatcher on worker
+       spawn, or manually for ad-hoc overrides).
+    2. ``<root>/kanban/current`` on disk (set by ``hermes kanban boards
+       switch``).
+    3. ``DEFAULT_BOARD`` (``"default"``).
+
+    A malformed slug at any step falls through to the next layer with a
+    best-effort warning — the dispatcher must never crash because a user
+    hand-edited a file.
+    """
+    env = os.environ.get("HERMES_KANBAN_BOARD", "").strip()
+    if env:
+        try:
+            normed = _normalize_board_slug(env)
+            if normed:
+                return normed
+        except ValueError:
+            pass
+    try:
+        f = current_board_path()
+        if f.exists():
+            val = f.read_text(encoding="utf-8").strip()
+            if val:
+                try:
+                    normed = _normalize_board_slug(val)
+                    if normed:
+                        return normed
+                except ValueError:
+                    pass
+    except OSError:
+        pass
+    return DEFAULT_BOARD
+
+
+def set_current_board(slug: str) -> Path:
+    """Persist ``slug`` as the active board. Returns the file written.
+
+    Writes ``<root>/kanban/current``. The caller should validate the slug
+    exists first (via :func:`board_exists`) — this function does not —
+    so that ``hermes kanban boards switch <typo>`` returns an error
+    instead of silently pointing at nothing.
+    """
+    normed = _normalize_board_slug(slug)
+    if not normed:
+        raise ValueError("board slug is required")
+    path = current_board_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(normed + "\n", encoding="utf-8")
+    return path
+
+
+def clear_current_board() -> None:
+    """Remove ``<root>/kanban/current`` so the active board reverts to ``default``."""
+    try:
+        current_board_path().unlink()
+    except FileNotFoundError:
+        pass
+
+
+def board_dir(board: Optional[str] = None) -> Path:
+    """Return the on-disk directory for ``board``.
+
+    ``default`` is ``<root>/kanban/boards/default/`` **for metadata only**
+    (board.json + workspaces/ + logs/). Its DB file stays at
+    ``<root>/kanban.db`` for back-compat — see :func:`kanban_db_path`.
+
+    All other boards live at ``<root>/kanban/boards/<slug>/`` with
+    everything inside that directory including the ``kanban.db``.
+    """
+    slug = _normalize_board_slug(board) or DEFAULT_BOARD
+    return boards_root() / slug
+
+
+def board_exists(board: Optional[str] = None) -> bool:
+    """Return True if the board has a DB or a metadata dir on disk.
+
+    ``default`` is considered to always exist — its DB is created
+    on first :func:`connect` and there's no way for it to be missing
+    in a configuration where the kanban feature is usable at all.
+    """
+    slug = _normalize_board_slug(board) or DEFAULT_BOARD
+    if slug == DEFAULT_BOARD:
+        return True
+    d = board_dir(slug)
+    return d.is_dir() or (d / "kanban.db").exists()
+
+
+def kanban_db_path(board: Optional[str] = None) -> Path:
+    """Return the path to the ``kanban.db`` for ``board``.
+
+    Resolution (highest precedence first):
+
+    1. ``HERMES_KANBAN_DB`` env var — pins the path directly. Honoured for
+       back-compat and for the dispatcher→worker handoff (defense in
+       depth: dispatcher injects this into worker env so workers are
+       immune to any path-resolution disagreement).
+    2. When ``board`` arg is None, the active board from
+       :func:`get_current_board` is used.
+    3. Board ``default`` → ``<root>/kanban.db`` (back-compat path).
+       Other boards → ``<root>/kanban/boards/<slug>/kanban.db``.
+    """
+    override = os.environ.get("HERMES_KANBAN_DB", "").strip()
+    if override:
+        return Path(override).expanduser()
+    slug = _normalize_board_slug(board)
+    if slug is None:
+        slug = get_current_board()
+    if slug == DEFAULT_BOARD:
+        return kanban_home() / "kanban.db"
+    return board_dir(slug) / "kanban.db"
+
+
+def workspaces_root(board: Optional[str] = None) -> Path:
+    """Return the directory under which ``scratch`` workspaces are created.
+
+    Anchored per-board so workspaces don't leak between projects.
+    ``HERMES_KANBAN_WORKSPACES_ROOT`` pins the path directly (highest
+    precedence) — the dispatcher injects this into worker env.
+
+    ``default`` keeps the legacy path ``<root>/kanban/workspaces/`` so
+    that existing scratch workspaces from before the boards feature are
+    preserved. Other boards use ``<root>/kanban/boards/<slug>/workspaces/``.
+    """
+    override = os.environ.get("HERMES_KANBAN_WORKSPACES_ROOT", "").strip()
+    if override:
+        return Path(override).expanduser()
+    slug = _normalize_board_slug(board)
+    if slug is None:
+        slug = get_current_board()
+    if slug == DEFAULT_BOARD:
+        return kanban_home() / "kanban" / "workspaces"
+    return board_dir(slug) / "workspaces"
+
+
+def worker_logs_dir(board: Optional[str] = None) -> Path:
+    """Return the directory under which per-task worker logs are written.
+
+    ``default`` keeps the legacy path ``<root>/kanban/logs/``. Other
+    boards use ``<root>/kanban/boards/<slug>/logs/``. Logs follow the
+    board — makes ``hermes kanban log`` unambiguous even when multiple
+    boards have tasks with the same id.
+    """
+    slug = _normalize_board_slug(board)
+    if slug is None:
+        slug = get_current_board()
+    if slug == DEFAULT_BOARD:
+        return kanban_home() / "kanban" / "logs"
+    return board_dir(slug) / "logs"
+
+
+def board_metadata_path(board: Optional[str] = None) -> Path:
+    """Return the path to ``board.json`` for ``board``.
+
+    Stores display metadata (display name, description, icon, color,
+    created_at). The on-disk slug is the canonical identity; this file
+    is purely for presentation in the CLI / dashboard.
+    """
+    slug = _normalize_board_slug(board) or DEFAULT_BOARD
+    return board_dir(slug) / "board.json"
+
+
+def _default_board_display_name(slug: str) -> str:
+    """Turn a slug into a reasonable default display name.
+
+    ``atm10-server`` → ``Atm10 Server``. Users can override via
+    ``board.json`` but the default should look presentable in the
+    dashboard without any follow-up editing.
+    """
+    return " ".join(part.capitalize() for part in slug.replace("_", "-").split("-") if part) or slug
+
+
+def read_board_metadata(board: Optional[str] = None) -> dict:
+    """Return ``board.json`` contents (or synthesized defaults).
+
+    Never raises — a missing / malformed ``board.json`` falls back to a
+    synthesised entry so the dashboard always has something to render.
+    Includes the canonical ``slug`` and ``db_path`` so the caller
+    doesn't need to reconstruct them.
+    """
+    slug = _normalize_board_slug(board) or DEFAULT_BOARD
+    meta: dict[str, Any] = {
+        "slug": slug,
+        "name": _default_board_display_name(slug),
+        "description": "",
+        "icon": "",
+        "color": "",
+        "created_at": None,
+        "archived": False,
+    }
+    try:
+        p = board_metadata_path(slug)
+        if p.exists():
+            raw = json.loads(p.read_text(encoding="utf-8"))
+            if isinstance(raw, dict):
+                # Never let the metadata file claim a different slug than
+                # its directory — trust the filesystem.
+                raw["slug"] = slug
+                meta.update(raw)
+    except (OSError, json.JSONDecodeError):
+        pass
+    meta["db_path"] = str(kanban_db_path(slug))
+    return meta
+
+
+def write_board_metadata(
+    board: Optional[str],
+    *,
+    name: Optional[str] = None,
+    description: Optional[str] = None,
+    icon: Optional[str] = None,
+    color: Optional[str] = None,
+    archived: Optional[bool] = None,
+) -> dict:
+    """Create / update ``board.json`` for ``board``.
+
+    Preserves any existing fields not mentioned in the call. Sets
+    ``created_at`` on first write. Returns the resulting metadata dict.
+    """
+    slug = _normalize_board_slug(board) or DEFAULT_BOARD
+    meta = read_board_metadata(slug)
+    # Preserve existing DB-derived fields — they get re-computed each
+    # read but shouldn't be written into board.json.
+    meta.pop("db_path", None)
+    if name is not None:
+        meta["name"] = str(name).strip() or _default_board_display_name(slug)
+    if description is not None:
+        meta["description"] = str(description)
+    if icon is not None:
+        meta["icon"] = str(icon)
+    if color is not None:
+        meta["color"] = str(color)
+    if archived is not None:
+        meta["archived"] = bool(archived)
+    if not meta.get("created_at"):
+        meta["created_at"] = int(time.time())
+    path = board_metadata_path(slug)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(
+        json.dumps(meta, indent=2, ensure_ascii=False) + "\n",
+        encoding="utf-8",
+    )
+    meta["db_path"] = str(kanban_db_path(slug))
+    return meta
+
+
+def create_board(
+    slug: str,
+    *,
+    name: Optional[str] = None,
+    description: Optional[str] = None,
+    icon: Optional[str] = None,
+    color: Optional[str] = None,
+) -> dict:
+    """Create a new board directory + DB + metadata. Idempotent.
+
+    Returns the resulting metadata. Raises :class:`ValueError` for a
+    malformed slug; returns the existing metadata (not an error) if the
+    board already exists — matching ``mkdir -p`` semantics.
+    """
+    normed = _normalize_board_slug(slug)
+    if not normed:
+        raise ValueError("board slug is required")
+    meta = write_board_metadata(
+        normed,
+        name=name,
+        description=description,
+        icon=icon,
+        color=color,
+    )
+    # Touch the DB so list_boards() sees it immediately.
+    init_db(board=normed)
+    return meta
+
+
+def list_boards(*, include_archived: bool = True) -> list[dict]:
+    """Enumerate all boards that exist on disk.
+
+    Always includes ``default`` (even when the ``boards/default/``
+    metadata dir doesn't exist, because its DB is at the legacy path).
+    Other boards are discovered by scanning ``boards/`` for subdirectories
+    that either contain a ``kanban.db`` or a ``board.json``.
+
+    Returns a list of metadata dicts, sorted with ``default`` first and
+    the rest alphabetically.
+    """
+    entries: list[dict] = []
+    seen: set[str] = set()
+
+    # Default board is always first.
+    entries.append(read_board_metadata(DEFAULT_BOARD))
+    seen.add(DEFAULT_BOARD)
+
+    root = boards_root()
+    if root.is_dir():
+        for child in sorted(root.iterdir(), key=lambda p: p.name.lower()):
+            if not child.is_dir():
+                continue
+            slug = child.name
+            # Keep slug normalisation soft for discovery — but skip dirs
+            # that don't parse as valid slugs so we don't surface junk.
+            try:
+                normed = _normalize_board_slug(slug)
+            except ValueError:
+                continue
+            if not normed or normed in seen:
+                continue
+            has_db = (child / "kanban.db").exists()
+            has_meta = (child / "board.json").exists()
+            if not (has_db or has_meta):
+                continue
+            meta = read_board_metadata(normed)
+            if meta.get("archived") and not include_archived:
+                continue
+            entries.append(meta)
+            seen.add(normed)
+    return entries
+
+
+def remove_board(slug: str, *, archive: bool = True) -> dict:
+    """Remove or archive a board.
+
+    ``archive=True`` (default) moves the board's directory to
+    ``<root>/kanban/boards/_archived/<slug>-<timestamp>/`` so the data
+    is recoverable. ``archive=False`` deletes the directory outright.
+
+    The ``default`` board cannot be removed — raises :class:`ValueError`.
+    Returns a summary dict describing what happened (``{"slug", "action",
+    "new_path"}``).
+    """
+    normed = _normalize_board_slug(slug)
+    if not normed:
+        raise ValueError("board slug is required")
+    if normed == DEFAULT_BOARD:
+        raise ValueError("the 'default' board cannot be removed")
+    d = board_dir(normed)
+    if not d.exists():
+        raise ValueError(f"board {normed!r} does not exist")
+
+    # If the user removed the currently-active board, revert to default.
+    if get_current_board() == normed:
+        clear_current_board()
+
+    if archive:
+        archive_root = boards_root() / "_archived"
+        archive_root.mkdir(parents=True, exist_ok=True)
+        ts = int(time.time())
+        target = archive_root / f"{normed}-{ts}"
+        # Avoid collision on rapid double-archives.
+        suffix = 1
+        while target.exists():
+            target = archive_root / f"{normed}-{ts}-{suffix}"
+            suffix += 1
+        d.rename(target)
+        return {"slug": normed, "action": "archived", "new_path": str(target)}
+    else:
+        import shutil
+        shutil.rmtree(d)
+        return {"slug": normed, "action": "deleted", "new_path": ""}
 
 
 # ---------------------------------------------------------------------------
@@ -368,7 +842,11 @@ CREATE INDEX IF NOT EXISTS idx_notify_task           ON kanban_notify_subs(task_
 _INITIALIZED_PATHS: set[str] = set()
 
 
-def connect(db_path: Optional[Path] = None) -> sqlite3.Connection:
+def connect(
+    db_path: Optional[Path] = None,
+    *,
+    board: Optional[str] = None,
+) -> sqlite3.Connection:
     """Open (and initialize if needed) the kanban DB.
 
     WAL mode is enabled on every connection; it's a no-op after the first
@@ -378,8 +856,19 @@ def connect(db_path: Optional[Path] = None) -> sqlite3.Connection:
     fresh installs and test harnesses that construct `connect()`
     directly don't have to remember a separate init step. Subsequent
     connections skip the schema check via a module-level path cache.
+
+    Path resolution:
+
+    * ``db_path`` explicit → used as-is (legacy callers, tests).
+    * ``board`` explicit → resolves to that board's DB.
+    * Neither → :func:`kanban_db_path` resolves via
+      ``HERMES_KANBAN_DB`` env → ``HERMES_KANBAN_BOARD`` env →
+      ``<root>/kanban/current`` → ``default``.
     """
-    path = db_path or kanban_db_path()
+    if db_path is not None:
+        path = db_path
+    else:
+        path = kanban_db_path(board=board)
     path.parent.mkdir(parents=True, exist_ok=True)
     resolved = str(path.resolve())
     needs_init = resolved not in _INITIALIZED_PATHS
@@ -398,7 +887,11 @@ def connect(db_path: Optional[Path] = None) -> sqlite3.Connection:
     return conn
 
 
-def init_db(db_path: Optional[Path] = None) -> Path:
+def init_db(
+    db_path: Optional[Path] = None,
+    *,
+    board: Optional[str] = None,
+) -> Path:
     """Create the schema if it doesn't exist; return the path used.
 
     Kept as a public entry point so CLI ``hermes kanban init`` and the
@@ -409,7 +902,10 @@ def init_db(db_path: Optional[Path] = None) -> Path:
     external tools that upgrade an old DB file — can call this to
     force re-migration.
     """
-    path = db_path or kanban_db_path()
+    if db_path is not None:
+        path = db_path
+    else:
+        path = kanban_db_path(board=board)
     path.parent.mkdir(parents=True, exist_ok=True)
     resolved = str(path.resolve())
     # Clear the cache entry so the underlying connect() re-runs the
@@ -590,6 +1086,15 @@ def _claimer_id() -> str:
 # Task creation / mutation
 # ---------------------------------------------------------------------------
 
+def _canonical_assignee(assignee: Optional[str]) -> Optional[str]:
+    """Lowercase-assignee normalization for Kanban rows (dashboard/CLI parity)."""
+    if assignee is None:
+        return None
+    from hermes_cli.profiles import normalize_profile_name
+
+    return normalize_profile_name(assignee)
+
+
 def create_task(
     conn: sqlite3.Connection,
     *,
@@ -631,6 +1136,7 @@ def create_task(
     (e.g. ``skills=["translation"]`` so the worker loads the
     translation skill regardless of the profile's default config).
     """
+    assignee = _canonical_assignee(assignee)
     if not title or not title.strip():
         raise ValueError("title is required")
     if workspace_kind not in VALID_WORKSPACE_KINDS:
@@ -795,7 +1301,7 @@ def list_tasks(
     params: list[Any] = []
     if assignee is not None:
         query += " AND assignee = ?"
-        params.append(assignee)
+        params.append(_canonical_assignee(assignee))
     if status is not None:
         if status not in VALID_STATUSES:
             raise ValueError(f"status must be one of {sorted(VALID_STATUSES)}")
@@ -819,6 +1325,7 @@ def assign_task(conn: sqlite3.Connection, task_id: str, profile: Optional[str])
     Refuses to reassign a task that's currently running (claim_lock set).
     Reassign after the current run completes if needed.
     """
+    profile = _canonical_assignee(profile)
     with write_txn(conn):
         row = conn.execute(
             "SELECT status, claim_lock FROM tasks WHERE id = ?", (task_id,)
@@ -1513,15 +2020,18 @@ def archive_task(conn: sqlite3.Connection, task_id: str) -> bool:
 # Workspace resolution
 # ---------------------------------------------------------------------------
 
-def resolve_workspace(task: Task) -> Path:
+def resolve_workspace(task: Task, *, board: Optional[str] = None) -> Path:
     """Resolve (and create if needed) the workspace for a task.
 
-    - ``scratch``: a fresh dir under ``$HERMES_HOME/kanban/workspaces/<id>/``.
+    - ``scratch``: a fresh dir under ``<board-root>/workspaces/<id>/``,
+      where ``<board-root>`` is the active board's root. The path is the
+      same for the dispatcher and every profile worker, so handoff is
+      path-stable.
     - ``dir:<path>``: the path stored in ``workspace_path``.  Created
       if missing.  MUST be absolute — relative paths are rejected to
       prevent confused-deputy traversal where ``../../../tmp/attacker``
       resolves against the dispatcher's CWD instead of a meaningful
-      root.  Users who want a HERMES_HOME-relative workspace should
+      root.  Users who want a kanban-root-relative workspace should
       compute the absolute path themselves.
     - ``worktree``: a git worktree at ``workspace_path``.  Not created
       automatically in v1 -- the kanban-worker skill documents
@@ -1543,7 +2053,7 @@ def resolve_workspace(task: Task) -> Path:
                     f"{task.workspace_path!r}; workspace paths must be absolute"
                 )
         else:
-            p = workspaces_root() / task.id
+            p = workspaces_root(board=board) / task.id
         p.mkdir(parents=True, exist_ok=True)
         return p
     if kind == "dir":
@@ -1957,6 +2467,7 @@ def dispatch_once(
     dry_run: bool = False,
     max_spawn: Optional[int] = None,
     failure_limit: int = DEFAULT_SPAWN_FAILURE_LIMIT,
+    board: Optional[str] = None,
 ) -> DispatchResult:
     """Run one dispatcher tick.
 
@@ -1965,15 +2476,17 @@ def dispatch_once(
       2. Reclaim crashed running tasks (host-local PID no longer alive).
       3. Promote todo -> ready where all parents are done.
       4. For each ready task with an assignee, atomically claim and call
-         ``spawn_fn(task, workspace_path) -> Optional[int]``. The return
-         value (if any) is recorded as ``worker_pid`` so subsequent ticks
-         can detect crashes before the TTL expires.
+         ``spawn_fn(task, workspace_path, board) -> Optional[int]``. The
+         return value (if any) is recorded as ``worker_pid`` so subsequent
+         ticks can detect crashes before the TTL expires.
 
     Spawn failures are counted per-task. After ``failure_limit`` consecutive
     failures the task is auto-blocked with the last error as its reason —
     prevents the dispatcher from thrashing forever on an unfixable task.
 
     ``spawn_fn`` defaults to ``_default_spawn``. Tests pass a stub.
+    ``board`` pins workspace/log/db resolution for this tick to a specific
+    board. When omitted, the current-board resolution chain is used.
     """
     result = DispatchResult()
     result.reclaimed = release_stale_claims(conn)
@@ -2000,7 +2513,7 @@ def dispatch_once(
         if claimed is None:
             continue
         try:
-            workspace = resolve_workspace(claimed)
+            workspace = resolve_workspace(claimed, board=board)
         except Exception as exc:
             auto = _record_spawn_failure(
                 conn, claimed.id, f"workspace: {exc}",
@@ -2013,7 +2526,18 @@ def dispatch_once(
         set_workspace_path(conn, claimed.id, str(workspace))
         _spawn = spawn_fn if spawn_fn is not None else _default_spawn
         try:
-            pid = _spawn(claimed, str(workspace))
+            # Back-compat: older spawn_fn signatures accept only
+            # (task, workspace). Test stubs in the suite rely on that.
+            # Introspect the callable and pass `board` only when supported.
+            import inspect
+            try:
+                sig = inspect.signature(_spawn)
+                if "board" in sig.parameters:
+                    pid = _spawn(claimed, str(workspace), board=board)
+                else:
+                    pid = _spawn(claimed, str(workspace))
+            except (TypeError, ValueError):
+                pid = _spawn(claimed, str(workspace))
             if pid:
                 _set_worker_pid(conn, claimed.id, int(pid))
             _clear_spawn_failures(conn, claimed.id)
@@ -2052,33 +2576,60 @@ def _rotate_worker_log(log_path: Path, max_bytes: int) -> None:
         pass
 
 
-def _default_spawn(task: Task, workspace: str) -> Optional[int]:
+def _default_spawn(
+    task: Task,
+    workspace: str,
+    *,
+    board: Optional[str] = None,
+) -> Optional[int]:
     """Fire-and-forget ``hermes -p <profile> chat -q ...`` subprocess.
 
     Returns the spawned child's PID so the dispatcher can detect crashes
     before the claim TTL expires. The child's completion is still observed
     via the ``complete`` / ``block`` transitions the worker writes itself;
     the PID check is a safety net for crashes, OOM kills, and Ctrl+C.
+
+    ``board`` pins the child's kanban context to that board: the child's
+    ``HERMES_KANBAN_DB`` / ``HERMES_KANBAN_BOARD`` / workspaces_root env
+    vars all resolve to the same board the dispatcher claimed the task
+    from. Workers cannot accidentally see other boards.
     """
     import subprocess
     if not task.assignee:
         raise ValueError(f"task {task.id} has no assignee")
 
+    from hermes_cli.profiles import normalize_profile_name
+
+    profile_arg = normalize_profile_name(task.assignee)
+
     prompt = f"work kanban task {task.id}"
     env = dict(os.environ)
     if task.tenant:
         env["HERMES_TENANT"] = task.tenant
     env["HERMES_KANBAN_TASK"] = task.id
     env["HERMES_KANBAN_WORKSPACE"] = workspace
+    # Pin the shared board + workspaces root the dispatcher resolved, so
+    # that even when the worker activates a profile (`hermes -p <name>`
+    # rewrites HERMES_HOME), its kanban paths still match the
+    # dispatcher's. Belt-and-braces with the `get_default_hermes_root()`
+    # resolution in `kanban_home()` — symmetric resolution is the norm,
+    # but unusual symlink / Docker layouts are caught here too.
+    env["HERMES_KANBAN_DB"] = str(kanban_db_path(board=board))
+    env["HERMES_KANBAN_WORKSPACES_ROOT"] = str(workspaces_root(board=board))
+    # Board slug — the final defense-in-depth pin. If the worker ever
+    # resolves kanban paths without the DB / workspaces env vars, the
+    # board slug still forces it to the right directory.
+    resolved_board = _normalize_board_slug(board) or get_current_board()
+    env["HERMES_KANBAN_BOARD"] = resolved_board
     # HERMES_PROFILE is the author the kanban_comment tool defaults to.
     # `hermes -p <assignee>` activates the profile, but the env var is
     # what the tool reads — set it explicitly here so comments are
     # attributed correctly regardless of how the child loads config.
-    env["HERMES_PROFILE"] = task.assignee
+    env["HERMES_PROFILE"] = profile_arg
 
     cmd = [
         "hermes",
-        "-p", task.assignee,
+        "-p", profile_arg,
         # Auto-load the kanban-worker skill so every dispatched worker
         # has the pattern library (good summary/metadata shapes, retry
         # diagnostics, block-reason examples) in its context, even if
@@ -2104,9 +2655,11 @@ def _default_spawn(task: Task, workspace: str) -> Optional[int]:
         "chat",
         "-q", prompt,
     ])
-    # Redirect output to a per-task log under HERMES_HOME/kanban/logs/.
-    from hermes_constants import get_hermes_home
-    log_dir = get_hermes_home() / "kanban" / "logs"
+    # Redirect output to a per-task log under <board-root>/logs/.
+    # Anchored at the board root (not the shared kanban root), so
+    # `hermes kanban log` on a specific board reads its own file and
+    # logs don't collide across boards that happen to share task ids.
+    log_dir = worker_logs_dir(board=board)
     log_dir.mkdir(parents=True, exist_ok=True)
     log_path = log_dir / f"{task.id}.log"
     _rotate_worker_log(log_path, DEFAULT_LOG_ROTATE_BYTES)
@@ -2587,12 +3140,14 @@ def gc_events(
 
 def gc_worker_logs(
     *, older_than_seconds: int = 30 * 24 * 3600,
+    board: Optional[str] = None,
 ) -> int:
     """Delete worker log files older than ``older_than_seconds``. Returns
     the number of files removed. Kept separate from ``gc_events`` because
-    log files live on disk, not in SQLite."""
-    from hermes_constants import get_hermes_home
-    log_dir = get_hermes_home() / "kanban" / "logs"
+    log files live on disk, not in SQLite. Scoped to ``board`` (defaults
+    to the active board) — per-board isolation means deleting logs from
+    board A cannot touch board B's logs."""
+    log_dir = worker_logs_dir(board=board)
     if not log_dir.exists():
         return 0
     cutoff = time.time() - older_than_seconds
@@ -2611,20 +3166,25 @@ def gc_worker_logs(
 # Worker log accessor
 # ---------------------------------------------------------------------------
 
-def worker_log_path(task_id: str) -> Path:
+def worker_log_path(task_id: str, *, board: Optional[str] = None) -> Path:
     """Return the path to a worker's log file. The file may not exist
-    (task never spawned, or log already GC'd)."""
-    from hermes_constants import get_hermes_home
-    return get_hermes_home() / "kanban" / "logs" / f"{task_id}.log"
+    (task never spawned, or log already GC'd).
+
+    When ``board`` is None, resolves via the active board (env var →
+    current-board file → default). The dispatcher always passes the
+    board explicitly to avoid any resolution ambiguity when multiple
+    boards exist."""
+    return worker_logs_dir(board=board) / f"{task_id}.log"
 
 
 def read_worker_log(
     task_id: str, *, tail_bytes: Optional[int] = None,
+    board: Optional[str] = None,
 ) -> Optional[str]:
     """Read the worker log for ``task_id``. Returns None if the file
     doesn't exist. If ``tail_bytes`` is set, only the last N bytes are
     returned (useful for the dashboard drawer which shouldn't page megabytes)."""
-    path = worker_log_path(task_id)
+    path = worker_log_path(task_id, board=board)
     if not path.exists():
         return None
     try:
@@ -2661,7 +3221,8 @@ def list_profiles_on_disk() -> list[str]:
     ``config.yaml`` — a bare dir without config isn't a real profile.
     """
     try:
-        home = Path.home() / ".hermes" / "profiles"
+        from hermes_constants import get_default_hermes_root
+        home = get_default_hermes_root() / "profiles"
     except Exception:
         return []
     if not home.is_dir():

hermes_cli/main.py

@@ -114,6 +114,16 @@ def _apply_profile_override() -> None:
             consume = 1
             break
 
+    # 1b. Reject values that can't be valid profile names (e.g. pytest's
+    # "-p no:xdist" would be misread as profile "no:xdist" otherwise).
+    # Mirrors hermes_cli.profiles._PROFILE_ID_RE so we never call
+    # resolve_profile_env() with a value it must reject + sys.exit on.
+    if profile_name is not None and consume == 2:
+        import re as _re
+        if not _re.match(r"^[a-z0-9][a-z0-9_-]{0,63}$", profile_name):
+            profile_name = None
+            consume = 0
+
     # 1.5 If HERMES_HOME is already set and no explicit flag was given, trust it.
     # This lets child processes (relaunch, subprocess) inherit the parent's
     # profile choice without having to pass --profile again.
@@ -837,7 +847,17 @@ def _print_tui_exit_summary(session_id: Optional[str], active_session_file: Opti
     )
 
 
-_NPM_LOCK_RUNTIME_KEYS = frozenset({"ideallyInert"})
+_NPM_LOCK_RUNTIME_KEYS = frozenset({"ideallyInert", "peer"})
+"""Lockfile fields npm writes non-deterministically at install time.
+
+``ideallyInert`` is npm's runtime annotation for packages it skipped installing
+(per-platform opt-outs).  ``peer`` is dropped from the hidden ``.package-lock.json``
+on dev-dependencies that are *also* declared as peers — the canonical
+``package-lock.json`` records the dual role, but npm 9's actualized tree strips
+it.  Neither key represents a real skew between what was declared and what was
+installed, so we exclude them from the comparison in :func:`_tui_need_npm_install`
+to avoid false-positive reinstalls on every launch.
+"""
 
 
 def _tui_need_npm_install(root: Path) -> bool:
@@ -1042,17 +1062,21 @@ def _make_tui_argv(tui_dir: Path, tui_dev: bool) -> tuple[list[str], Path]:
     if _tui_need_npm_install(tui_dir):
         if not os.environ.get("HERMES_QUIET"):
             print("Installing TUI dependencies…")
+        # Capture stdout as well as stderr — some npm errors (notably EACCES on a
+        # root-owned node_modules in containers) are emitted on stdout, and a
+        # bare "npm install failed." with no preview defeats debugging.  We keep
+        # the failure-only print path so a successful install stays silent.
         result = subprocess.run(
             [npm, "install", "--silent", "--no-fund", "--no-audit", "--progress=false"],
             cwd=str(tui_dir),
-            stdout=subprocess.DEVNULL,
+            stdout=subprocess.PIPE,
             stderr=subprocess.PIPE,
             text=True,
             env={**os.environ, "CI": "1"},
         )
         if result.returncode != 0:
-            err = (result.stderr or "").strip()
-            preview = "\n".join(err.splitlines()[-30:])
+            combined = f"{result.stdout or ''}\n{result.stderr or ''}".strip()
+            preview = "\n".join(combined.splitlines()[-30:])
             print("npm install failed.")
             if preview:
                 print(preview)
@@ -3399,10 +3423,10 @@ def _model_flow_named_custom(config, provider_info):
     print()
 
     print("Fetching available models...")
-    models = fetch_api_models(
-        api_key, base_url, timeout=8.0,
-        api_mode=api_mode or None,
-    )
+    fetch_kwargs = {"timeout": 8.0}
+    if api_mode:
+        fetch_kwargs["api_mode"] = api_mode
+    models = fetch_api_models(api_key, base_url, **fetch_kwargs)
 
     if models:
         default_idx = 0
@@ -6471,13 +6495,29 @@ def _cmd_update_check():
     if sys.platform == "win32":
         git_cmd = ["git", "-c", "windows.appendAtomically=false"]
 
-    print("→ Fetching from origin...")
+    # Fetch both origin and upstream; prefer upstream as the canonical reference
+    print("→ Fetching from upstream...")
     fetch_result = subprocess.run(
-        git_cmd + ["fetch", "origin"],
+        git_cmd + ["fetch", "upstream"],
         cwd=PROJECT_ROOT,
         capture_output=True,
         text=True,
     )
+    if fetch_result.returncode != 0:
+        # Fallback to origin if upstream doesn't exist
+        print("→ Fetching from origin...")
+        fetch_result = subprocess.run(
+            git_cmd + ["fetch", "origin"],
+            cwd=PROJECT_ROOT,
+            capture_output=True,
+            text=True,
+        )
+        upstream_exists = False
+        compare_branch = "origin/main"
+    else:
+        upstream_exists = True
+        compare_branch = "upstream/main"
+
     if fetch_result.returncode != 0:
         stderr = fetch_result.stderr.strip()
         if "Could not resolve host" in stderr or "unable to access" in stderr:
@@ -6485,13 +6525,13 @@ def _cmd_update_check():
         elif "Authentication failed" in stderr or "could not read Username" in stderr:
             print("✗ Authentication failed — check your git credentials or SSH key.")
         else:
-            print("✗ Failed to fetch from origin.")
+            print("✗ Failed to fetch.")
             if stderr:
                 print(f"  {stderr.splitlines()[0]}")
         sys.exit(1)
 
     rev_result = subprocess.run(
-        git_cmd + ["rev-list", "HEAD..origin/main", "--count"],
+        git_cmd + ["rev-list", f"HEAD..{compare_branch}", "--count"],
         cwd=PROJECT_ROOT,
         capture_output=True,
         text=True,
@@ -6503,7 +6543,7 @@ def _cmd_update_check():
         print("✓ Already up to date.")
     else:
         commits_word = "commit" if behind == 1 else "commits"
-        print(f"⚕ Update available: {behind} {commits_word} behind origin/main.")
+        print(f"⚕ Update available: {behind} {commits_word} behind {compare_branch}.")
         from hermes_cli.config import recommended_update_command
         print(f"  Run '{recommended_update_command()}' to install.")
 
@@ -7029,20 +7069,22 @@ def _cmd_update_impl(args, gateway_mode: bool):
         except Exception as e:
             logger.debug("Skills sync during update failed: %s", e)
 
-        # Sync bundled skills to all other profiles
+        # Sync bundled skills to all profiles (including the active one).
+        # seed_profile_skills() uses subprocess with an explicit HERMES_HOME so
+        # it is not affected by sync_skills()'s module-level HERMES_HOME cache,
+        # which means the active profile is reliably synced regardless of whether
+        # the caller's HERMES_HOME env var points at the default or a named profile.
         try:
             from hermes_cli.profiles import (
                 list_profiles,
-                get_active_profile_name,
                 seed_profile_skills,
             )
 
-            active = get_active_profile_name()
-            other_profiles = [p for p in list_profiles() if p.name != active]
-            if other_profiles:
+            all_profiles = list_profiles()
+            if all_profiles:
                 print()
-                print("→ Syncing bundled skills to other profiles...")
-                for p in other_profiles:
+                print("→ Syncing bundled skills to all profiles...")
+                for p in all_profiles:
                     try:
                         r = seed_profile_skills(p.path, quiet=True)
                         if r:
@@ -8638,7 +8680,24 @@ def main():
     )
     cron_create.add_argument(
         "--script",
-        help="Path to a Python script whose stdout is injected into the prompt each run",
+        help=(
+            "Path to a script under ~/.hermes/scripts/. Default mode: "
+            "script stdout is injected into the agent's prompt each run. "
+            "With --no-agent: the script IS the job and its stdout is "
+            "delivered verbatim. .sh/.bash files run via bash, everything "
+            "else via Python."
+        ),
+    )
+    cron_create.add_argument(
+        "--no-agent",
+        dest="no_agent",
+        action="store_true",
+        default=False,
+        help=(
+            "Skip the LLM entirely — run --script on schedule and deliver "
+            "its stdout directly. Empty stdout = silent. Classic watchdog "
+            "pattern (memory alerts, disk alerts, CI pings)."
+        ),
     )
     cron_create.add_argument(
         "--workdir",
@@ -8680,7 +8739,29 @@ def main():
     )
     cron_edit.add_argument(
         "--script",
-        help="Path to a Python script whose stdout is injected into the prompt each run. Pass empty string to clear.",
+        help=(
+            "Path to a script under ~/.hermes/scripts/. Pass empty string to clear. "
+            "With --no-agent the script IS the job; otherwise its stdout is "
+            "injected into the agent's prompt each run."
+        ),
+    )
+    cron_edit.add_argument(
+        "--no-agent",
+        dest="no_agent",
+        action="store_const",
+        const=True,
+        default=None,
+        help=(
+            "Enable no-agent mode on this job (requires --script or an "
+            "existing script on the job)."
+        ),
+    )
+    cron_edit.add_argument(
+        "--agent",
+        dest="no_agent",
+        action="store_const",
+        const=False,
+        help="Disable no-agent mode on this job (reverts to LLM-driven execution).",
     )
     cron_edit.add_argument(
         "--workdir",
@@ -8891,6 +8972,7 @@ Examples:
     hermes debug share --lines 500  Include more log lines
     hermes debug share --expire 30  Keep paste for 30 days
     hermes debug share --local      Print report locally (no upload)
+    hermes debug share --no-redact  Disable upload-time secret redaction
     hermes debug delete <url>       Delete a previously uploaded paste
 """,
     )
@@ -8916,6 +8998,16 @@ Examples:
         action="store_true",
         help="Print the report locally instead of uploading",
     )
+    share_parser.add_argument(
+        "--no-redact",
+        action="store_true",
+        help=(
+            "Disable upload-time secret redaction (default: redact). Logs "
+            "are normally run through agent.redact.redact_sensitive_text "
+            "with force=True before upload so credentials are not leaked "
+            "into the public paste service."
+        ),
+    )
     delete_parser = debug_sub.add_parser(
         "delete",
         help="Delete a paste uploaded by 'hermes debug share'",

hermes_cli/model_switch.py

@@ -904,6 +904,26 @@ def switch_model(
                         if any(m.get("name") == new_model for m in cfg_models if isinstance(m, dict)):
                             override = True
                             break
+        # Also check custom_providers list — models declared there should be accepted
+        # even if the remote /v1/models endpoint doesn't list them.
+        if not override and custom_providers and isinstance(custom_providers, list):
+            for entry in custom_providers:
+                if not isinstance(entry, dict):
+                    continue
+                # Match by provider slug (custom:<name>) or by base_url
+                entry_name = entry.get("name", "")
+                entry_slug = f"custom:{entry_name}" if entry_name else ""
+                entry_url = entry.get("base_url", "")
+                if entry_slug == target_provider or entry_url == base_url:
+                    # Check if the requested model matches the entry's model
+                    entry_model = entry.get("model", "")
+                    entry_models = entry.get("models", {})
+                    if new_model == entry_model:
+                        override = True
+                        break
+                    if isinstance(entry_models, dict) and new_model in entry_models:
+                        override = True
+                        break
         if override:
             validation = {"accepted": True, "persist": True, "recognized": False, "message": validation.get("message", "")}
         else:
@@ -1244,11 +1264,7 @@ def list_authenticated_providers(
                 from hermes_cli.auth import _load_auth_store
                 store = _load_auth_store()
                 providers_store = store.get("providers", {})
-                pool_store = store.get("credential_pool", {})
-                if store and (
-                    pid in providers_store or hermes_slug in providers_store
-                    or pid in pool_store or hermes_slug in pool_store
-                ):
+                if store and (pid in providers_store or hermes_slug in providers_store):
                     has_creds = True
             except Exception as exc:
                 logger.debug("Auth store check failed for %s: %s", pid, exc)
@@ -1344,11 +1360,7 @@ def list_authenticated_providers(
                 from hermes_cli.auth import _load_auth_store
                 _cp_store = _load_auth_store()
                 _cp_providers_store = _cp_store.get("providers", {})
-                _cp_pool_store = _cp_store.get("credential_pool", {})
-                if _cp_store and (
-                    _cp.slug in _cp_providers_store
-                    or _cp.slug in _cp_pool_store
-                ):
+                if _cp_store and _cp.slug in _cp_providers_store:
                     _cp_has_creds = True
             except Exception:
                 pass

hermes_cli/models.py

@@ -1740,10 +1740,20 @@ def model_supports_fast_mode(model_id: Optional[str]) -> bool:
 
 
 def _is_anthropic_fast_model(model_id: Optional[str]) -> bool:
-    """Return True if the model is a Claude model eligible for Anthropic Fast Mode."""
+    """Return True if the model is a Claude model eligible for Anthropic Fast Mode.
+
+    Fast mode is currently supported on Claude Opus 4.6 only. Per Anthropic's
+    docs (https://platform.claude.com/docs/en/build-with-claude/fast-mode):
+    "Fast mode is currently supported on Opus 4.6 only. Sending speed: fast
+    with an unsupported model returns an error." Opus 4.7 explicitly rejects
+    the ``speed`` parameter with HTTP 400.
+    """
     raw = _strip_vendor_prefix(str(model_id or ""))
     base = raw.split(":")[0]
-    return base.startswith("claude-")
+    if not base.startswith("claude-"):
+        return False
+    # Only Opus 4.6 supports fast mode at present.
+    return "opus-4-6" in base or "opus-4.6" in base
 
 
 def resolve_fast_mode_overrides(model_id: Optional[str]) -> dict[str, Any] | None:
@@ -2896,6 +2906,19 @@ def fetch_api_models(
 _OLLAMA_CLOUD_CACHE_TTL = 3600  # 1 hour
 
 
+def _strip_ollama_cloud_suffix(model_id: str) -> str:
+    """Strip :cloud / -cloud suffixes that models.dev appends to Ollama Cloud IDs.
+
+    The live API uses clean IDs (e.g. 'kimi-k2.6') while models.dev sometimes
+    returns them as 'kimi-k2.6:cloud'. Normalising before the dedup merge
+    prevents duplicate entries in the merged model list.
+    """
+    for suffix in (":cloud", "-cloud"):
+        if model_id.endswith(suffix):
+            return model_id[: -len(suffix)]
+    return model_id
+
+
 def _ollama_cloud_cache_path() -> Path:
     """Return the path for the Ollama Cloud model cache."""
     from hermes_constants import get_hermes_home
@@ -2991,9 +3014,10 @@ def fetch_ollama_cloud_models(
                 seen.add(m)
                 merged.append(m)
         for m in mdev_models:
-            if m and m not in seen:
-                seen.add(m)
-                merged.append(m)
+            normalized = _strip_ollama_cloud_suffix(m)
+            if normalized and normalized not in seen:
+                seen.add(normalized)
+                merged.append(normalized)
         if merged:
             _save_ollama_cloud_cache(merged)
             return merged
@@ -3087,7 +3111,7 @@ def validate_requested_model(
             "message": f"Model `{requested}` was not found in LM Studio's model listing.",
         }
 
-    if normalized == "custom":
+    if normalized == "custom" or normalized.startswith("custom:"):
         # Try probing with correct auth for the api_mode.
         if api_mode == "anthropic_messages":
             probe = probe_api_models(api_key, base_url, api_mode=api_mode)
@@ -3185,11 +3209,12 @@ def validate_requested_model(
             if suggestions:
                 suggestion_text = "\n  Similar models: " + ", ".join(f"`{s}`" for s in suggestions)
             return {
-                "accepted": False,
-                "persist": False,
+                "accepted": True,
+                "persist": True,
                 "recognized": False,
                 "message": (
-                    f"Model `{requested}` was not found in the OpenAI Codex model listing."
+                    f"Note: `{requested}` was not found in the OpenAI Codex model listing. "
+                    "It may still work if your ChatGPT/Codex account has access to a newer or hidden model ID."
                     f"{suggestion_text}"
                 ),
             }

hermes_cli/profiles.py

@@ -179,8 +179,33 @@ def _get_wrapper_dir() -> Path:
 # Validation
 # ---------------------------------------------------------------------------
 
+def normalize_profile_name(name: str) -> str:
+    """Return the canonical profile id used on disk and in CLI ``-p`` argv.
+
+    Named profiles are stored lowercase under ``profiles/<id>/``. The special
+    alias ``default`` is matched case-insensitively (``Default`` → ``default``).
+    Dashboards and tools may pass title-cased display labels; normalize before
+    validation, assignment, and subprocess spawn (see issue #18498).
+    """
+    if not isinstance(name, str):
+        name = str(name)
+    stripped = name.strip()
+    if not stripped:
+        raise ValueError("profile name cannot be empty")
+    if stripped.casefold() == "default":
+        return "default"
+    return stripped.lower()
+
+
 def validate_profile_name(name: str) -> None:
-    """Raise ``ValueError`` if *name* is not a valid profile identifier."""
+    """Raise ``ValueError`` if *name* is not a valid profile identifier.
+
+    Validates the input as-given — strict lowercase match. Callers that accept
+    mixed-case or title-cased input from users (dashboard UI, CLI args) should
+    call :func:`normalize_profile_name` first. This separation keeps validate
+    honest about what the on-disk directory name must look like, while
+    ingress-point normalization handles UX flexibility (see #18498).
+    """
     if name == "default":
         return  # special alias for ~/.hermes
     if not _PROFILE_ID_RE.match(name):
@@ -192,16 +217,18 @@ def validate_profile_name(name: str) -> None:
 
 def get_profile_dir(name: str) -> Path:
     """Resolve a profile name to its HERMES_HOME directory."""
-    if name == "default":
+    canon = normalize_profile_name(name)
+    if canon == "default":
         return _get_default_hermes_home()
-    return _get_profiles_root() / name
+    return _get_profiles_root() / canon
 
 
 def profile_exists(name: str) -> bool:
     """Check whether a profile directory exists."""
-    if name == "default":
+    canon = normalize_profile_name(name)
+    if canon == "default":
         return True
-    return get_profile_dir(name).is_dir()
+    return get_profile_dir(canon).is_dir()
 
 
 # ---------------------------------------------------------------------------
@@ -213,28 +240,29 @@ def check_alias_collision(name: str) -> Optional[str]:
 
     Checks: reserved names, hermes subcommands, existing binaries in PATH.
     """
-    if name in _RESERVED_NAMES:
-        return f"'{name}' is a reserved name"
-    if name in _HERMES_SUBCOMMANDS:
-        return f"'{name}' conflicts with a hermes subcommand"
+    canon = normalize_profile_name(name)
+    if canon in _RESERVED_NAMES:
+        return f"'{canon}' is a reserved name"
+    if canon in _HERMES_SUBCOMMANDS:
+        return f"'{canon}' conflicts with a hermes subcommand"
 
     # Check existing commands in PATH
     wrapper_dir = _get_wrapper_dir()
     try:
         result = subprocess.run(
-            ["which", name], capture_output=True, text=True, timeout=5,
+            ["which", canon], capture_output=True, text=True, timeout=5,
         )
         if result.returncode == 0:
             existing_path = result.stdout.strip()
             # Allow overwriting our own wrappers
-            if existing_path == str(wrapper_dir / name):
+            if existing_path == str(wrapper_dir / canon):
                 try:
-                    content = (wrapper_dir / name).read_text()
+                    content = (wrapper_dir / canon).read_text()
                     if "hermes -p" in content:
                         return None  # it's our wrapper, safe to overwrite
                 except Exception:
                     pass
-            return f"'{name}' conflicts with an existing command ({existing_path})"
+            return f"'{canon}' conflicts with an existing command ({existing_path})"
     except (FileNotFoundError, subprocess.TimeoutExpired):
         pass
 
@@ -252,6 +280,7 @@ def create_wrapper_script(name: str) -> Optional[Path]:
 
     Returns the path to the created wrapper, or None if creation failed.
     """
+    canon = normalize_profile_name(name)
     wrapper_dir = _get_wrapper_dir()
     try:
         wrapper_dir.mkdir(parents=True, exist_ok=True)
@@ -259,9 +288,9 @@ def create_wrapper_script(name: str) -> Optional[Path]:
         print(f"⚠ Could not create {wrapper_dir}: {e}")
         return None
 
-    wrapper_path = wrapper_dir / name
+    wrapper_path = wrapper_dir / canon
     try:
-        wrapper_path.write_text(f'#!/bin/sh\nexec hermes -p {name} "$@"\n')
+        wrapper_path.write_text(f'#!/bin/sh\nexec hermes -p {canon} "$@"\n')
         wrapper_path.chmod(wrapper_path.stat().st_mode | stat.S_IEXEC | stat.S_IXGRP | stat.S_IXOTH)
         return wrapper_path
     except OSError as e:
@@ -271,7 +300,7 @@ def create_wrapper_script(name: str) -> Optional[Path]:
 
 def remove_wrapper_script(name: str) -> bool:
     """Remove the wrapper script for a profile. Returns True if removed."""
-    wrapper_path = _get_wrapper_dir() / name
+    wrapper_path = _get_wrapper_dir() / normalize_profile_name(name)
     if wrapper_path.exists():
         try:
             # Verify it's our wrapper before removing
@@ -421,16 +450,17 @@ def create_profile(
     Path
         The newly created profile directory.
     """
-    validate_profile_name(name)
+    canon = normalize_profile_name(name)
+    validate_profile_name(canon)
 
-    if name == "default":
+    if canon == "default":
         raise ValueError(
             "Cannot create a profile named 'default' — it is the built-in profile (~/.hermes)."
         )
 
-    profile_dir = get_profile_dir(name)
+    profile_dir = get_profile_dir(canon)
     if profile_dir.exists():
-        raise FileExistsError(f"Profile '{name}' already exists at {profile_dir}")
+        raise FileExistsError(f"Profile '{canon}' already exists at {profile_dir}")
 
     # Resolve clone source
     source_dir = None
@@ -440,6 +470,7 @@ def create_profile(
             from hermes_constants import get_hermes_home
             source_dir = get_hermes_home()
         else:
+            clone_from = normalize_profile_name(clone_from)
             validate_profile_name(clone_from)
             source_dir = get_profile_dir(clone_from)
         if not source_dir.is_dir():
@@ -540,24 +571,25 @@ def delete_profile(name: str, yes: bool = False) -> Path:
 
     Returns the path that was removed.
     """
-    validate_profile_name(name)
+    canon = normalize_profile_name(name)
+    validate_profile_name(canon)
 
-    if name == "default":
+    if canon == "default":
         raise ValueError(
             "Cannot delete the default profile (~/.hermes).\n"
             "To remove everything, use: hermes uninstall"
         )
 
-    profile_dir = get_profile_dir(name)
+    profile_dir = get_profile_dir(canon)
     if not profile_dir.is_dir():
-        raise FileNotFoundError(f"Profile '{name}' does not exist.")
+        raise FileNotFoundError(f"Profile '{canon}' does not exist.")
 
     # Show what will be deleted
     model, provider = _read_config_model(profile_dir)
     gw_running = _check_gateway_running(profile_dir)
     skill_count = _count_skills(profile_dir)
 
-    print(f"\nProfile: {name}")
+    print(f"\nProfile: {canon}")
     print(f"Path:    {profile_dir}")
     if model:
         print(f"Model:   {model}" + (f" ({provider})" if provider else ""))
@@ -569,7 +601,7 @@ def delete_profile(name: str, yes: bool = False) -> Path:
     ]
 
     # Check for service
-    wrapper_path = _get_wrapper_dir() / name
+    wrapper_path = _get_wrapper_dir() / canon
     has_wrapper = wrapper_path.exists()
     if has_wrapper:
         items.append(f"Command alias ({wrapper_path})")
@@ -584,16 +616,16 @@ def delete_profile(name: str, yes: bool = False) -> Path:
     if not yes:
         print()
         try:
-            confirm = input(f"Type '{name}' to confirm: ").strip()
+            confirm = input(f"Type '{canon}' to confirm: ").strip()
         except (KeyboardInterrupt, EOFError):
             print("\nCancelled.")
             return profile_dir
-        if confirm != name:
+        if confirm != canon:
             print("Cancelled.")
             return profile_dir
 
     # 1. Disable service (prevents auto-restart)
-    _cleanup_gateway_service(name, profile_dir)
+    _cleanup_gateway_service(canon, profile_dir)
 
     # 2. Stop running gateway
     if gw_running:
@@ -601,7 +633,7 @@ def delete_profile(name: str, yes: bool = False) -> Path:
 
     # 3. Remove wrapper script
     if has_wrapper:
-        if remove_wrapper_script(name):
+        if remove_wrapper_script(canon):
             print(f"✓ Removed {wrapper_path}")
 
     # 4. Remove profile directory
@@ -614,13 +646,13 @@ def delete_profile(name: str, yes: bool = False) -> Path:
     # 5. Clear active_profile if it pointed to this profile
     try:
         active = get_active_profile()
-        if active == name:
+        if active == canon:
             set_active_profile("default")
             print("✓ Active profile reset to default")
     except Exception:
         pass
 
-    print(f"\nProfile '{name}' deleted.")
+    print(f"\nProfile '{canon}' deleted.")
     return profile_dir
 
 
@@ -730,22 +762,23 @@ def set_active_profile(name: str) -> None:
 
     Writes to ``~/.hermes/active_profile``. Use ``"default"`` to clear.
     """
-    validate_profile_name(name)
-    if name != "default" and not profile_exists(name):
+    canon = normalize_profile_name(name)
+    validate_profile_name(canon)
+    if canon != "default" and not profile_exists(canon):
         raise FileNotFoundError(
-            f"Profile '{name}' does not exist. "
-            f"Create it with: hermes profile create {name}"
+            f"Profile '{canon}' does not exist. "
+            f"Create it with: hermes profile create {canon}"
         )
 
     path = _get_active_profile_path()
     path.parent.mkdir(parents=True, exist_ok=True)
-    if name == "default":
+    if canon == "default":
         # Remove the file to indicate default
         path.unlink(missing_ok=True)
     else:
         # Atomic write
         tmp = path.with_suffix(".tmp")
-        tmp.write_text(name + "\n")
+        tmp.write_text(canon + "\n")
         tmp.replace(path)
 
 
@@ -811,16 +844,17 @@ def export_profile(name: str, output_path: str) -> Path:
     """
     import tempfile
 
-    validate_profile_name(name)
-    profile_dir = get_profile_dir(name)
+    canon = normalize_profile_name(name)
+    validate_profile_name(canon)
+    profile_dir = get_profile_dir(canon)
     if not profile_dir.is_dir():
-        raise FileNotFoundError(f"Profile '{name}' does not exist.")
+        raise FileNotFoundError(f"Profile '{canon}' does not exist.")
 
     output = Path(output_path)
     # shutil.make_archive wants the base name without extension
     base = str(output).removesuffix(".tar.gz").removesuffix(".tgz")
 
-    if name == "default":
+    if canon == "default":
         # The default profile IS ~/.hermes itself — its parent is ~/ and its
         # directory name is ".hermes", not "default".  We stage a clean copy
         # under a temp dir so the archive contains ``default/...``.
@@ -836,14 +870,14 @@ def export_profile(name: str, output_path: str) -> Path:
 
     # Named profiles — stage a filtered copy to exclude credentials
     with tempfile.TemporaryDirectory() as tmpdir:
-        staged = Path(tmpdir) / name
+        staged = Path(tmpdir) / canon
         _CREDENTIAL_FILES = {"auth.json", ".env"}
         shutil.copytree(
             profile_dir,
             staged,
             ignore=lambda d, contents: _CREDENTIAL_FILES & set(contents),
         )
-        result = shutil.make_archive(base, "gztar", tmpdir, name)
+        result = shutil.make_archive(base, "gztar", tmpdir, canon)
         return Path(result)
 
 
@@ -952,16 +986,17 @@ def import_profile(archive_path: str, name: Optional[str] = None) -> Path:
     # Archives exported from the default profile have "default/" as top-level
     # dir.  Importing as "default" would target ~/.hermes itself — disallow
     # that and guide the user toward a named profile.
-    if inferred_name == "default":
+    canon = normalize_profile_name(inferred_name)
+    validate_profile_name(canon)
+    if canon == "default":
         raise ValueError(
             "Cannot import as 'default' — that is the built-in root profile (~/.hermes). "
             "Specify a different name: hermes profile import <archive> --name <name>"
         )
 
-    validate_profile_name(inferred_name)
-    profile_dir = get_profile_dir(inferred_name)
+    profile_dir = get_profile_dir(canon)
     if profile_dir.exists():
-        raise FileExistsError(f"Profile '{inferred_name}' already exists at {profile_dir}")
+        raise FileExistsError(f"Profile '{canon}' already exists at {profile_dir}")
 
     profiles_root = _get_profiles_root()
     profiles_root.mkdir(parents=True, exist_ok=True)
@@ -977,8 +1012,8 @@ def import_profile(archive_path: str, name: Optional[str] = None) -> Path:
             )
 
         final_source = extracted
-        if archive_root != inferred_name:
-            final_source = staging_root / inferred_name
+        if archive_root != canon:
+            final_source = staging_root / canon
             extracted.rename(final_source)
 
         shutil.move(str(final_source), str(profile_dir))
@@ -1048,25 +1083,27 @@ def rename_profile(old_name: str, new_name: str) -> Path:
 
     Returns the new profile directory.
     """
-    validate_profile_name(old_name)
-    validate_profile_name(new_name)
+    old_canon = normalize_profile_name(old_name)
+    new_canon = normalize_profile_name(new_name)
+    validate_profile_name(old_canon)
+    validate_profile_name(new_canon)
 
-    if old_name == "default":
+    if old_canon == "default":
         raise ValueError("Cannot rename the default profile.")
-    if new_name == "default":
+    if new_canon == "default":
         raise ValueError("Cannot rename to 'default' — it is reserved.")
 
-    old_dir = get_profile_dir(old_name)
-    new_dir = get_profile_dir(new_name)
+    old_dir = get_profile_dir(old_canon)
+    new_dir = get_profile_dir(new_canon)
 
     if not old_dir.is_dir():
-        raise FileNotFoundError(f"Profile '{old_name}' does not exist.")
+        raise FileNotFoundError(f"Profile '{old_canon}' does not exist.")
     if new_dir.exists():
-        raise FileExistsError(f"Profile '{new_name}' already exists.")
+        raise FileExistsError(f"Profile '{new_canon}' already exists.")
 
     # 1. Stop gateway if running
     if _check_gateway_running(old_dir):
-        _cleanup_gateway_service(old_name, old_dir)
+        _cleanup_gateway_service(old_canon, old_dir)
         _stop_gateway_process(old_dir)
 
     # 2. Rename directory
@@ -1074,22 +1111,22 @@ def rename_profile(old_name: str, new_name: str) -> Path:
     print(f"✓ Renamed {old_dir.name} → {new_dir.name}")
 
     # 3. Update profile-scoped Honcho host blocks, preserving aiPeer identity
-    _migrate_honcho_profile_host(old_name, new_name, new_dir)
+    _migrate_honcho_profile_host(old_canon, new_canon, new_dir)
 
     # 4. Update wrapper script
-    remove_wrapper_script(old_name)
-    collision = check_alias_collision(new_name)
+    remove_wrapper_script(old_canon)
+    collision = check_alias_collision(new_canon)
     if not collision:
-        create_wrapper_script(new_name)
-        print(f"✓ Alias updated: {new_name}")
+        create_wrapper_script(new_canon)
+        print(f"✓ Alias updated: {new_canon}")
     else:
-        print(f"⚠ Cannot create alias '{new_name}' — {collision}")
+        print(f"⚠ Cannot create alias '{new_canon}' — {collision}")
 
     # 5. Update active_profile if it pointed to old name
     try:
-        if get_active_profile() == old_name:
-            set_active_profile(new_name)
-            print(f"✓ Active profile updated: {new_name}")
+        if get_active_profile() == old_canon:
+            set_active_profile(new_canon)
+            print(f"✓ Active profile updated: {new_canon}")
     except Exception:
         pass
 
@@ -1191,13 +1228,14 @@ def resolve_profile_env(profile_name: str) -> str:
     Called early in the CLI entry point, before any hermes modules
     are imported, to set the HERMES_HOME environment variable.
     """
-    validate_profile_name(profile_name)
-    profile_dir = get_profile_dir(profile_name)
+    canon = normalize_profile_name(profile_name)
+    validate_profile_name(canon)
+    profile_dir = get_profile_dir(canon)
 
-    if profile_name != "default" and not profile_dir.is_dir():
+    if canon != "default" and not profile_dir.is_dir():
         raise FileNotFoundError(
-            f"Profile '{profile_name}' does not exist. "
-            f"Create it with: hermes profile create {profile_name}"
+            f"Profile '{canon}' does not exist. "
+            f"Create it with: hermes profile create {canon}"
         )
 
     return str(profile_dir)

hermes_cli/pty_bridge.py

@@ -108,9 +108,14 @@ class PtyBridge:
                     "(or pip install -e '.[pty]')."
                 )
             raise PtyUnavailableError("Pseudo-terminals are unavailable.")
-        # Let caller-supplied env fully override inheritance; if they pass
-        # None we inherit the server's env (same semantics as subprocess).
-        spawn_env = os.environ.copy() if env is None else env
+        # PTY-hosted programs expect TERM to describe the terminal type.
+        # CI often runs without TERM in the parent process, which makes
+        # simple terminal probes like `tput cols` fail before winsize reads.
+        # Preserve explicit caller overrides, but backfill a sensible default
+        # when TERM is missing or blank.
+        spawn_env = (os.environ.copy() if env is None else env.copy())
+        if not spawn_env.get("TERM"):
+            spawn_env["TERM"] = "xterm-256color"
         proc = ptyprocess.PtyProcess.spawn(  # type: ignore[union-attr]
             list(argv),
             cwd=cwd,

hermes_cli/setup.py

@@ -964,7 +964,8 @@ def setup_model_provider(config: dict, *, quick: bool = False):
                     )
                 else:
                     _selected_vision_model = prompt("  Vision model (blank = use main/custom default)").strip()
-                save_env_value("AUXILIARY_VISION_MODEL", _selected_vision_model)
+                if _selected_vision_model:
+                    save_env_value("AUXILIARY_VISION_MODEL", _selected_vision_model)
                 print_success(
                     f"Vision configured with {_base_url}"
                     + (f" ({_selected_vision_model})" if _selected_vision_model else "")
@@ -1328,15 +1329,13 @@ def setup_terminal_backend(config: dict):
         print_success("Terminal backend: Local")
         print_info("Commands run directly on this machine.")
 
-        # CWD for messaging
+        # Gateway/cron working directory
         print()
-        print_info("Working directory for messaging sessions:")
-        print_info("  When using Hermes via Telegram/Discord, this is where")
-        print_info(
-            "  the agent starts. CLI mode always starts in the current directory."
-        )
+        print_info("Gateway working directory:")
+        print_info("  Used by Telegram/Discord/cron sessions.")
+        print_info("  CLI/TUI always uses your launch directory instead.")
         current_cwd = cfg_get(config, "terminal", "cwd", default="")
-        cwd = prompt("  Messaging working directory", current_cwd or str(Path.home()))
+        cwd = prompt("  Gateway working directory", current_cwd or str(Path.home()))
         if cwd:
             config["terminal"]["cwd"] = cwd
 
@@ -2049,6 +2048,16 @@ def _setup_slack():
         print_warning("⚠️  No Slack allowlist set - unpaired users will be denied by default.")
         print_info("   Set SLACK_ALLOW_ALL_USERS=true or GATEWAY_ALLOW_ALL_USERS=true only if you intentionally want open workspace access.")
 
+    print()
+    print_info("📬 Home Channel: where Hermes delivers cron job results,")
+    print_info("   cross-platform messages, and notifications.")
+    print_info("   To get a channel ID: open the channel in Slack, then right-click")
+    print_info("   the channel name → Copy link — the ID starts with C (e.g. C01ABC2DE3F).")
+    print_info("   You can also set this later by typing /set-home in a Slack channel.")
+    home_channel = prompt("Home channel ID (leave empty to set later with /set-home)")
+    if home_channel:
+        save_env_value("SLACK_HOME_CHANNEL", home_channel.strip())
+
 
 def _write_slack_manifest_and_instruct():
     """Generate the Slack manifest, write it under HERMES_HOME, and print
@@ -2995,6 +3004,21 @@ def run_setup_wizard(args):
     config = load_config()
     hermes_home = get_hermes_home()
 
+    # Back up existing config before setup modifies it (#3522)
+    config_path = get_config_path()
+    if config_path.exists():
+        from datetime import datetime as _dt
+        _backup_path = config_path.with_suffix(
+            f".yaml.bak.{_dt.now().strftime('%Y%m%d_%H%M%S')}"
+        )
+        try:
+            import shutil
+            shutil.copy2(config_path, _backup_path)
+        except Exception:
+            _backup_path = None
+    else:
+        _backup_path = None
+
     # Detect non-interactive environments (headless SSH, Docker, CI/CD)
     non_interactive = getattr(args, 'non_interactive', False)
     if not non_interactive and not is_interactive_stdin():
@@ -3164,6 +3188,10 @@ def run_setup_wizard(args):
 
     # Save and show summary
     save_config(config)
+    if _backup_path and _backup_path.exists():
+        print_info(f"Previous config backed up to: {_backup_path}")
+        print_info("If setup changed a value you customized, restore it with:")
+        print_info(f"  cp {_backup_path} {config_path}")
     _print_setup_summary(config, hermes_home)
 
     _offer_launch_chat()

hermes_cli/status.py

@@ -122,11 +122,16 @@ def show_status(args):
     print()
     print(color("◆ API Keys", Colors.CYAN, Colors.BOLD))
 
-    keys = {
+    # Values may be a single env var name (str) or a tuple of alternates (first found wins).
+    keys: dict[str, str | tuple[str, ...]] = {
         "OpenRouter": "OPENROUTER_API_KEY",
         "OpenAI": "OPENAI_API_KEY",
-        "NVIDIA": "NVIDIA_API_KEY",
-        "Z.AI/GLM": "GLM_API_KEY",
+        "Anthropic": ("ANTHROPIC_API_KEY", "ANTHROPIC_TOKEN"),
+        "Google / Gemini": ("GOOGLE_API_KEY", "GEMINI_API_KEY"),
+        "DeepSeek": "DEEPSEEK_API_KEY",
+        "xAI / Grok": "XAI_API_KEY",
+        "NVIDIA NIM": "NVIDIA_API_KEY",
+        "Z.AI / GLM": "GLM_API_KEY",
         "Kimi": "KIMI_API_KEY",
         "StepFun Step Plan": "STEPFUN_API_KEY",
         "MiniMax": "MINIMAX_API_KEY",
@@ -142,8 +147,23 @@ def show_status(args):
         "GitHub": "GITHUB_TOKEN",
     }
 
-    for name, env_var in keys.items():
-        value = get_env_value(env_var) or ""
+    def _resolve_env(env_ref) -> str:
+        """Return first non-empty env var value from a str or tuple of names."""
+        if isinstance(env_ref, tuple):
+            for candidate in env_ref:
+                v = get_env_value(candidate) or ""
+                if v:
+                    return v
+            return ""
+        return get_env_value(env_ref) or ""
+
+    for name, env_ref in keys.items():
+        # Anthropic already has a dedicated lookup below; keep that as the
+        # single source of truth (it also resolves OAuth tokens), skip here
+        # so we don't print two "Anthropic" rows.
+        if name == "Anthropic":
+            continue
+        value = _resolve_env(env_ref)
         has_key = bool(value)
         display = redact_key(value) if not show_all else value
         print(f"  {name:<12}  {check_mark(has_key)} {display}")

hermes_cli/tools_config.py

@@ -56,6 +56,7 @@ CONFIGURABLE_TOOLSETS = [
     ("file",            "📁 File Operations",           "read, write, patch, search"),
     ("code_execution",  "⚡ Code Execution",            "execute_code"),
     ("vision",          "👁️  Vision / Image Analysis",  "vision_analyze"),
+    ("video",           "🎬 Video Analysis",            "video_analyze (requires video-capable model)"),
     ("image_gen",       "🎨 Image Generation",          "image_generate"),
     ("moa",             "🧠 Mixture of Agents",         "mixture_of_agents"),
     ("tts",             "🔊 Text-to-Speech",            "text_to_speech"),
@@ -78,7 +79,7 @@ CONFIGURABLE_TOOLSETS = [
 # Toolsets that are OFF by default for new installs.
 # They're still in _HERMES_CORE_TOOLS (available at runtime if enabled),
 # but the setup checklist won't pre-select them for first-time users.
-_DEFAULT_OFF_TOOLSETS = {"moa", "homeassistant", "rl", "spotify", "discord", "discord_admin"}
+_DEFAULT_OFF_TOOLSETS = {"moa", "homeassistant", "rl", "spotify", "discord", "discord_admin", "video"}
 
 # Platform-scoped toolsets: only appear in the `hermes tools` checklist for
 # these platforms, and only resolve/save for these platforms.  A toolset
@@ -1919,21 +1920,27 @@ def _reconfigure_provider(provider: dict, config: dict):
             return
 
     if provider.get("tts_provider"):
-        config.setdefault("tts", {})["provider"] = provider["tts_provider"]
+        tts_cfg = config.setdefault("tts", {})
+        tts_cfg["provider"] = provider["tts_provider"]
+        tts_cfg["use_gateway"] = bool(managed_feature)
         _print_success(f"  TTS provider set to: {provider['tts_provider']}")
 
     if "browser_provider" in provider:
         bp = provider["browser_provider"]
+        browser_cfg = config.setdefault("browser", {})
         if bp == "local":
-            config.setdefault("browser", {})["cloud_provider"] = "local"
+            browser_cfg["cloud_provider"] = "local"
             _print_success("  Browser set to local mode")
         elif bp:
-            config.setdefault("browser", {})["cloud_provider"] = bp
+            browser_cfg["cloud_provider"] = bp
             _print_success(f"  Browser cloud provider set to: {bp}")
+        browser_cfg["use_gateway"] = bool(managed_feature)
 
     # Set web search backend in config if applicable
     if provider.get("web_backend"):
-        config.setdefault("web", {})["backend"] = provider["web_backend"]
+        web_cfg = config.setdefault("web", {})
+        web_cfg["backend"] = provider["web_backend"]
+        web_cfg["use_gateway"] = bool(managed_feature)
         _print_success(f"  Web backend set to: {provider['web_backend']}")
 
     if managed_feature and managed_feature not in ("web", "tts", "browser"):

hermes_cli/voice.py

@@ -27,6 +27,192 @@ import sys
 import threading
 from typing import Any, Callable, Optional
 
+# Modifier aliases mirrored from the TUI parser (``ui-tui/src/lib/platform.ts``)
+# ``_MOD_ALIASES`` table — the contract that removes the cross-runtime
+# mismatch Copilot flagged in round-9 on #19835.
+#
+# ``super``/``win``/``windows`` are intentionally absent: prompt_toolkit
+# has no super/meta modifier for the Cmd key, so those spellings are
+# TUI-only. The normalizer below returns the documented default
+# (``c-b``) for them — a silent fallback was preferred to a hard
+# startup crash (Copilot round-11). The CLI binding site
+# (``_register_voice_handler`` in cli.py) logs a warning when that
+# fallback fires so users see why their TUI-only shortcut isn't
+# bound in the classic CLI.
+_VOICE_MOD_ALIASES = {
+    "ctrl": "c-",
+    "control": "c-",
+    "alt": "a-",
+    "option": "a-",
+    "opt": "a-",
+}
+
+# Named keys prompt_toolkit accepts in ``c-<name>`` / ``a-<name>`` form.
+# Aliases collapse to prompt_toolkit's canonical spelling so the same
+# config value binds identically in both runtimes (Copilot round-10 on
+# #19835).
+_VOICE_NAMED_KEYS = {
+    "space": "space",
+    "spc": "space",
+    "enter": "enter",
+    "return": "enter",
+    "ret": "enter",
+    "tab": "tab",
+    "escape": "escape",
+    "esc": "escape",
+    "backspace": "backspace",
+    "bs": "backspace",
+    "delete": "delete",
+    "del": "delete",
+}
+
+# ``useInputHandlers()`` intercepts these before the voice check runs,
+# so a binding like ``ctrl+c`` (interrupt), ``ctrl+d`` (quit), or
+# ``ctrl+l`` (clear screen) would be advertised in /voice status but
+# never fire push-to-talk — the same blocklist the TUI parser uses.
+_VOICE_RESERVED_CTRL_CHARS = frozenset({"c", "d", "l"})
+
+# On macOS the classic CLI's prompt_toolkit bindings for copy / exit /
+# clear also claim ``a-c`` / ``a-d`` / ``a-l`` via the action-modifier
+# lookup, and hermes-ink reports Alt as ``key.meta`` on many terminals.
+# Mirror the TUI parser's darwin-only reservation so ``option+c`` etc.
+# don't bind Alt+C in the CLI while the TUI silently falls back to
+# Ctrl+B (Copilot round-14 on #19835).
+_VOICE_RESERVED_ALT_CHARS_MAC = frozenset({"c", "d", "l"})
+
+_DEFAULT_PT_KEY = "c-b"
+
+
+def voice_record_key_from_config(cfg: Any) -> Any:
+    """Shape-safe ``cfg.voice.record_key`` lookup.
+
+    ``load_config()`` deep-merges raw YAML and preserves scalar
+    overrides, so a hand-edited ``voice: true`` / ``voice: cmd+b``
+    leaves ``cfg["voice"]`` as a bool/str instead of a dict, and the
+    naive ``.get("voice", {}).get("record_key")`` chain raises
+    AttributeError before voice can even start (Copilot round-11 on
+    #19835). Return ``None`` for malformed shapes so call sites can
+    feed the result straight into the normalizer/formatter and get
+    the documented default.
+    """
+    if not isinstance(cfg, dict):
+        return None
+
+    voice = cfg.get("voice")
+    if not isinstance(voice, dict):
+        return None
+
+    return voice.get("record_key")
+
+
+def normalize_voice_record_key_for_prompt_toolkit(raw: Any) -> str:
+    """Coerce ``voice.record_key`` into prompt_toolkit's ``c-x`` / ``a-x`` format.
+
+    Mirrors the TUI parser contract (``ui-tui/src/lib/platform.ts``)
+    so one config value binds the same shortcut in both runtimes:
+
+    * non-string / empty / typo'd / bare-char / multi-modifier / reserved
+      ``ctrl+c|d|l`` → documented default ``c-b``
+    * single-char keys: ``ctrl+o`` → ``c-o``
+    * named keys: ``ctrl+space`` → ``c-space`` (aliases collapse:
+      ``ctrl+return`` → ``c-enter``)
+    * ``super`` / ``win`` / ``windows`` → ``c-b`` (TUI-only modifiers —
+      prompt_toolkit has no super mod; the CLI binding site is
+      expected to warn when this fallback fires so users see the
+      cross-runtime split, Copilot round-11 on #19835)
+    """
+    if not isinstance(raw, str):
+        return _DEFAULT_PT_KEY
+
+    lowered = raw.strip().lower()
+    if not lowered:
+        return _DEFAULT_PT_KEY
+
+    parts = [p.strip() for p in lowered.split("+") if p.strip()]
+    if not parts:
+        return _DEFAULT_PT_KEY
+
+    # Multi-modifier chords like ``ctrl+alt+r`` bind different shortcuts
+    # in prompt_toolkit (a-c-r form) and hermes-ink rejects them; collapse
+    # to the documented default instead of silently diverging.
+    if len(parts) > 2:
+        return _DEFAULT_PT_KEY
+
+    # Bare char / bare named key (no explicit modifier) — the CLI's
+    # prompt_toolkit binds the raw key without a modifier, which the TUI
+    # parser refuses; reject here too so both runtimes agree.
+    if len(parts) == 1:
+        return _DEFAULT_PT_KEY
+
+    modifier_token, key_token = parts
+
+    # ``super`` / ``win`` / ``windows`` are TUI-only (prompt_toolkit has
+    # no super modifier, so ``@kb.add(super+b)`` crashes the CLI at
+    # startup). Fall back to the documented default here; the CLI
+    # binding site is expected to log a warning when the configured
+    # value is one of these spellings so users know the TUI+CLI
+    # runtimes diverge on that shortcut (Copilot round-11 on #19835).
+    if modifier_token in {"super", "win", "windows"}:
+        return _DEFAULT_PT_KEY
+
+    normalized_mod = _VOICE_MOD_ALIASES.get(modifier_token)
+    if not normalized_mod:
+        return _DEFAULT_PT_KEY
+
+    # Single-char key: reject reserved-ctrl chords that the TUI would
+    # also block at parse time, plus the mac-only alt reservation.
+    if len(key_token) == 1:
+        if normalized_mod == "c-" and key_token in _VOICE_RESERVED_CTRL_CHARS:
+            return _DEFAULT_PT_KEY
+        if (
+            normalized_mod == "a-"
+            and sys.platform == "darwin"
+            and key_token in _VOICE_RESERVED_ALT_CHARS_MAC
+        ):
+            return _DEFAULT_PT_KEY
+        return f"{normalized_mod}{key_token}"
+
+    # Multi-char key token must be a known named key; typos like
+    # ``ctrl+spcae`` fall back to the default rather than being passed
+    # through as ``c-spcae`` (which prompt_toolkit would reject).
+    named = _VOICE_NAMED_KEYS.get(key_token)
+    if not named:
+        return _DEFAULT_PT_KEY
+
+    return f"{normalized_mod}{named}"
+
+
+def format_voice_record_key_for_status(raw: Any) -> str:
+    """Render ``voice.record_key`` for ``/voice status`` in CLI-friendly form.
+
+    Mirrors the TUI's ``formatVoiceRecordKey``: returns ``Ctrl+B`` /
+    ``Alt+Space`` / ``Ctrl+Enter``. Malformed configs surface as the
+    documented default so status never advertises a shortcut that
+    won't bind (Copilot round-10 on #19835).
+    """
+    normalized = normalize_voice_record_key_for_prompt_toolkit(raw)
+
+    if normalized.startswith("c-"):
+        prefix, key = "Ctrl+", normalized[2:]
+    elif normalized.startswith("a-"):
+        prefix, key = "Alt+", normalized[2:]
+    elif "+" in normalized:
+        # ``super+<key>`` / ``win+<key>`` — CLI won't bind them, but
+        # render in title case so status output is still readable.
+        mod, key = normalized.split("+", 1)
+        prefix = mod[0].upper() + mod[1:] + "+"
+    else:
+        return "Ctrl+B"
+
+    if not key:
+        return prefix.rstrip("+")
+
+    if len(key) == 1:
+        return prefix + key.upper()
+
+    return prefix + key[0].upper() + key[1:]
+
+
 from tools.voice_mode import (
     create_audio_recorder,
     is_whisper_hallucination,

hermes_cli/web_server.py

@@ -470,10 +470,23 @@ except (ValueError, TypeError):
     )
     _GATEWAY_HEALTH_TIMEOUT = 3.0
 
+# DEPRECATED (scheduled for removal): GATEWAY_HEALTH_URL / GATEWAY_HEALTH_TIMEOUT.
+# Cross-container / cross-host gateway liveness detection will be folded into a
+# first-class dashboard config key so it's no longer Docker-adjacent lore buried
+# in env vars.  The env vars still work for now so existing Compose deployments
+# don't break.  Do not add new callers — wire new uses through the planned
+# config surface.
+
 
 def _probe_gateway_health() -> tuple[bool, dict | None]:
     """Probe the gateway via its HTTP health endpoint (cross-container).
 
+    .. deprecated::
+        Driven by the deprecated ``GATEWAY_HEALTH_URL`` /
+        ``GATEWAY_HEALTH_TIMEOUT`` env vars.  Scheduled for removal alongside
+        a move to a first-class dashboard config key.  See
+        :data:`_GATEWAY_HEALTH_URL` for context.
+
     Uses ``/health/detailed`` first (returns full state), falling back to
     the simpler ``/health`` endpoint.  Returns ``(is_alive, body_dict)``.
 

hermes_state.py

@@ -2148,6 +2148,388 @@ class SessionDB:
             )
         self._execute_write(_do)
 
+    def apply_telegram_topic_migration(self) -> None:
+        """Create Telegram DM topic-mode tables on explicit /topic opt-in.
+
+        This migration is deliberately not part of automatic SessionDB startup
+        reconciliation. Operators must be able to upgrade Hermes, keep the old
+        Telegram bot behavior running, and only mutate topic-mode state when the
+        user executes /topic to opt into the feature.
+
+        Schema versions:
+          v1 — initial shape (no ON DELETE CASCADE on session_id FK)
+          v2 — session_id FK gets ON DELETE CASCADE so session pruning
+               automatically clears bindings.
+        """
+        def _do(conn):
+            conn.executescript(
+                """
+                CREATE TABLE IF NOT EXISTS telegram_dm_topic_mode (
+                    chat_id TEXT PRIMARY KEY,
+                    user_id TEXT NOT NULL,
+                    enabled INTEGER NOT NULL DEFAULT 1,
+                    activated_at REAL NOT NULL,
+                    updated_at REAL NOT NULL,
+                    has_topics_enabled INTEGER,
+                    allows_users_to_create_topics INTEGER,
+                    capability_checked_at REAL,
+                    intro_message_id TEXT,
+                    pinned_message_id TEXT
+                );
+
+                CREATE TABLE IF NOT EXISTS telegram_dm_topic_bindings (
+                    chat_id TEXT NOT NULL,
+                    thread_id TEXT NOT NULL,
+                    user_id TEXT NOT NULL,
+                    session_key TEXT NOT NULL,
+                    session_id TEXT NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+                    managed_mode TEXT NOT NULL DEFAULT 'auto',
+                    linked_at REAL NOT NULL,
+                    updated_at REAL NOT NULL,
+                    PRIMARY KEY (chat_id, thread_id)
+                );
+
+                CREATE UNIQUE INDEX IF NOT EXISTS idx_telegram_dm_topic_bindings_session
+                ON telegram_dm_topic_bindings(session_id);
+
+                CREATE INDEX IF NOT EXISTS idx_telegram_dm_topic_bindings_user
+                ON telegram_dm_topic_bindings(user_id, chat_id);
+                """
+            )
+
+            # v1 → v2: rebuild telegram_dm_topic_bindings if its session_id FK
+            # lacks ON DELETE CASCADE. SQLite can't ALTER a foreign key, so we
+            # rebuild the table. Only runs once per DB (version gate).
+            current = conn.execute(
+                "SELECT value FROM state_meta WHERE key = ?",
+                ("telegram_dm_topic_schema_version",),
+            ).fetchone()
+            current_version = int(current[0]) if current and str(current[0]).isdigit() else 0
+            if current_version < 2:
+                fk_rows = conn.execute(
+                    "PRAGMA foreign_key_list('telegram_dm_topic_bindings')"
+                ).fetchall()
+                needs_rebuild = any(
+                    row[2] == "sessions" and (row[6] or "") != "CASCADE"
+                    for row in fk_rows
+                )
+                if needs_rebuild:
+                    conn.executescript(
+                        """
+                        CREATE TABLE telegram_dm_topic_bindings_new (
+                            chat_id TEXT NOT NULL,
+                            thread_id TEXT NOT NULL,
+                            user_id TEXT NOT NULL,
+                            session_key TEXT NOT NULL,
+                            session_id TEXT NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
+                            managed_mode TEXT NOT NULL DEFAULT 'auto',
+                            linked_at REAL NOT NULL,
+                            updated_at REAL NOT NULL,
+                            PRIMARY KEY (chat_id, thread_id)
+                        );
+                        INSERT INTO telegram_dm_topic_bindings_new
+                            SELECT chat_id, thread_id, user_id, session_key,
+                                   session_id, managed_mode, linked_at, updated_at
+                            FROM telegram_dm_topic_bindings;
+                        DROP TABLE telegram_dm_topic_bindings;
+                        ALTER TABLE telegram_dm_topic_bindings_new
+                            RENAME TO telegram_dm_topic_bindings;
+                        CREATE UNIQUE INDEX idx_telegram_dm_topic_bindings_session
+                            ON telegram_dm_topic_bindings(session_id);
+                        CREATE INDEX idx_telegram_dm_topic_bindings_user
+                            ON telegram_dm_topic_bindings(user_id, chat_id);
+                        """
+                    )
+
+            conn.execute(
+                "INSERT INTO state_meta (key, value) VALUES (?, ?) "
+                "ON CONFLICT(key) DO UPDATE SET value = excluded.value",
+                ("telegram_dm_topic_schema_version", "2"),
+            )
+        self._execute_write(_do)
+
+    def enable_telegram_topic_mode(
+        self,
+        *,
+        chat_id: str,
+        user_id: str,
+        has_topics_enabled: Optional[bool] = None,
+        allows_users_to_create_topics: Optional[bool] = None,
+    ) -> None:
+        """Enable Telegram DM topic mode for one private chat/user.
+
+        This method intentionally owns the explicit topic migration. Ordinary
+        SessionDB startup must not create these side tables.
+        """
+        self.apply_telegram_topic_migration()
+        now = time.time()
+
+        def _to_int(value: Optional[bool]) -> Optional[int]:
+            if value is None:
+                return None
+            return 1 if value else 0
+
+        def _do(conn):
+            conn.execute(
+                """
+                INSERT INTO telegram_dm_topic_mode (
+                    chat_id, user_id, enabled, activated_at, updated_at,
+                    has_topics_enabled, allows_users_to_create_topics,
+                    capability_checked_at
+                ) VALUES (?, ?, 1, ?, ?, ?, ?, ?)
+                ON CONFLICT(chat_id) DO UPDATE SET
+                    user_id = excluded.user_id,
+                    enabled = 1,
+                    updated_at = excluded.updated_at,
+                    has_topics_enabled = excluded.has_topics_enabled,
+                    allows_users_to_create_topics = excluded.allows_users_to_create_topics,
+                    capability_checked_at = excluded.capability_checked_at
+                """,
+                (
+                    str(chat_id),
+                    str(user_id),
+                    now,
+                    now,
+                    _to_int(has_topics_enabled),
+                    _to_int(allows_users_to_create_topics),
+                    now,
+                ),
+            )
+        self._execute_write(_do)
+
+    def disable_telegram_topic_mode(
+        self,
+        *,
+        chat_id: str,
+        clear_bindings: bool = True,
+    ) -> None:
+        """Disable Telegram DM topic mode for one private chat.
+
+        When ``clear_bindings`` is True (default) the (chat_id, thread_id)
+        bindings for this chat are also cleared so re-enabling later
+        starts from a clean slate. Set to False if the operator wants to
+        preserve bindings for a later re-enable.
+
+        Never creates the topic-mode tables from scratch; if they don't
+        exist there is nothing to disable and the call is a no-op.
+        """
+        def _do(conn):
+            try:
+                conn.execute(
+                    "UPDATE telegram_dm_topic_mode SET enabled = 0, updated_at = ? "
+                    "WHERE chat_id = ?",
+                    (time.time(), str(chat_id)),
+                )
+                if clear_bindings:
+                    conn.execute(
+                        "DELETE FROM telegram_dm_topic_bindings WHERE chat_id = ?",
+                        (str(chat_id),),
+                    )
+            except sqlite3.OperationalError:
+                # Tables don't exist yet — nothing to disable.
+                return
+        self._execute_write(_do)
+
+    def is_telegram_topic_mode_enabled(self, *, chat_id: str, user_id: str) -> bool:
+        """Return whether Telegram DM topic mode is enabled for this chat/user."""
+        with self._lock:
+            try:
+                row = self._conn.execute(
+                    """
+                    SELECT enabled FROM telegram_dm_topic_mode
+                    WHERE chat_id = ? AND user_id = ?
+                    """,
+                    (str(chat_id), str(user_id)),
+                ).fetchone()
+            except sqlite3.OperationalError:
+                return False
+        if row is None:
+            return False
+        enabled = row["enabled"] if isinstance(row, sqlite3.Row) else row[0]
+        return bool(enabled)
+
+    def get_telegram_topic_binding(
+        self,
+        *,
+        chat_id: str,
+        thread_id: str,
+    ) -> Optional[Dict[str, Any]]:
+        """Return the session binding for a Telegram DM topic, if present."""
+        with self._lock:
+            try:
+                row = self._conn.execute(
+                    """
+                    SELECT * FROM telegram_dm_topic_bindings
+                    WHERE chat_id = ? AND thread_id = ?
+                    """,
+                    (str(chat_id), str(thread_id)),
+                ).fetchone()
+            except sqlite3.OperationalError:
+                return None
+        return dict(row) if row else None
+
+    def bind_telegram_topic(
+        self,
+        *,
+        chat_id: str,
+        thread_id: str,
+        user_id: str,
+        session_key: str,
+        session_id: str,
+        managed_mode: str = "auto",
+    ) -> None:
+        """Bind one Telegram DM topic thread to one Hermes session.
+
+        A Hermes session may only be linked to one Telegram topic in MVP.
+        Rebinding the same topic to the same session is idempotent; trying to
+        link the same session to a different topic raises ValueError.
+        """
+        self.apply_telegram_topic_migration()
+        now = time.time()
+        chat_id = str(chat_id)
+        thread_id = str(thread_id)
+        user_id = str(user_id)
+        session_key = str(session_key)
+        session_id = str(session_id)
+
+        def _do(conn):
+            existing_session = conn.execute(
+                """
+                SELECT chat_id, thread_id FROM telegram_dm_topic_bindings
+                WHERE session_id = ?
+                """,
+                (session_id,),
+            ).fetchone()
+            if existing_session is not None:
+                linked_chat = existing_session["chat_id"] if isinstance(existing_session, sqlite3.Row) else existing_session[0]
+                linked_thread = existing_session["thread_id"] if isinstance(existing_session, sqlite3.Row) else existing_session[1]
+                if str(linked_chat) != chat_id or str(linked_thread) != thread_id:
+                    raise ValueError("session is already linked to another Telegram topic")
+
+            conn.execute(
+                """
+                INSERT INTO telegram_dm_topic_bindings (
+                    chat_id, thread_id, user_id, session_key, session_id,
+                    managed_mode, linked_at, updated_at
+                ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+                ON CONFLICT(chat_id, thread_id) DO UPDATE SET
+                    user_id = excluded.user_id,
+                    session_key = excluded.session_key,
+                    session_id = excluded.session_id,
+                    managed_mode = excluded.managed_mode,
+                    updated_at = excluded.updated_at
+                """,
+                (
+                    chat_id,
+                    thread_id,
+                    user_id,
+                    session_key,
+                    session_id,
+                    managed_mode,
+                    now,
+                    now,
+                ),
+            )
+        self._execute_write(_do)
+
+    def is_telegram_session_linked_to_topic(self, *, session_id: str) -> bool:
+        """Return True if a Hermes session is already bound to any Telegram DM topic.
+
+        Read-only: does NOT trigger the telegram-topic migration. If the
+        topic-mode tables have not been created yet (i.e. nobody has run
+        ``/topic`` in this profile), the session is by definition unbound
+        and we return False.
+        """
+        with self._lock:
+            try:
+                row = self._conn.execute(
+                    """
+                    SELECT 1 FROM telegram_dm_topic_bindings
+                    WHERE session_id = ?
+                    LIMIT 1
+                    """,
+                    (str(session_id),),
+                ).fetchone()
+            except sqlite3.OperationalError:
+                return False
+        return row is not None
+
+    def list_unlinked_telegram_sessions_for_user(
+        self,
+        *,
+        chat_id: str,
+        user_id: str,
+        limit: int = 10,
+    ) -> List[Dict[str, Any]]:
+        """List previous Telegram sessions for this user that are not bound to a topic.
+
+        Read-only: does NOT trigger the telegram-topic migration. If the
+        topic-mode tables are absent, fall back to a simpler query that
+        just returns this user's Telegram sessions — there can't be any
+        bindings yet.
+        """
+        with self._lock:
+            try:
+                rows = self._conn.execute(
+                    """
+                    SELECT s.*,
+                        COALESCE(
+                            (SELECT SUBSTR(REPLACE(REPLACE(m.content, X'0A', ' '), X'0D', ' '), 1, 63)
+                             FROM messages m
+                             WHERE m.session_id = s.id AND m.role = 'user' AND m.content IS NOT NULL
+                             ORDER BY m.timestamp, m.id LIMIT 1),
+                            ''
+                        ) AS _preview_raw,
+                        COALESCE(
+                            (SELECT MAX(m2.timestamp) FROM messages m2 WHERE m2.session_id = s.id),
+                            s.started_at
+                        ) AS last_active
+                    FROM sessions s
+                    WHERE s.source = 'telegram'
+                      AND s.user_id = ?
+                      AND NOT EXISTS (
+                          SELECT 1 FROM telegram_dm_topic_bindings b
+                          WHERE b.session_id = s.id
+                      )
+                    ORDER BY last_active DESC, s.started_at DESC
+                    LIMIT ?
+                    """,
+                    (str(user_id), int(limit)),
+                ).fetchall()
+            except sqlite3.OperationalError:
+                # telegram_dm_topic_bindings doesn't exist yet — no bindings
+                # means every telegram session for this user is "unlinked".
+                rows = self._conn.execute(
+                    """
+                    SELECT s.*,
+                        COALESCE(
+                            (SELECT SUBSTR(REPLACE(REPLACE(m.content, X'0A', ' '), X'0D', ' '), 1, 63)
+                             FROM messages m
+                             WHERE m.session_id = s.id AND m.role = 'user' AND m.content IS NOT NULL
+                             ORDER BY m.timestamp, m.id LIMIT 1),
+                            ''
+                        ) AS _preview_raw,
+                        COALESCE(
+                            (SELECT MAX(m2.timestamp) FROM messages m2 WHERE m2.session_id = s.id),
+                            s.started_at
+                        ) AS last_active
+                    FROM sessions s
+                    WHERE s.source = 'telegram'
+                      AND s.user_id = ?
+                    ORDER BY last_active DESC, s.started_at DESC
+                    LIMIT ?
+                    """,
+                    (str(user_id), int(limit)),
+                ).fetchall()
+
+        sessions: List[Dict[str, Any]] = []
+        for row in rows:
+            session = dict(row)
+            raw = str(session.pop("_preview_raw", "") or "").strip()
+            session["preview"] = raw[:60] + ("..." if len(raw) > 60 else "") if raw else ""
+            sessions.append(session)
+        return sessions
+
     # ── Space reclamation ──
 
     def vacuum(self) -> None:

model_tools.py

@@ -511,6 +511,12 @@ def coerce_tool_args(tool_name: str, args: Dict[str, Any]) -> Dict[str, Any]:
 
     Handles ``"type": "integer"``, ``"type": "number"``, ``"type": "boolean"``,
     and union types (``"type": ["integer", "string"]``).
+
+    Also wraps bare scalar values in a single-element list when the schema
+    declares ``"type": "array"``.  Open-weight models (DeepSeek, Qwen, GLM)
+    sometimes emit ``{"urls": "https://a.com"}`` when the tool expects
+    ``{"urls": ["https://a.com"]}``; wrapping here avoids a confusing tool
+    failure on what is otherwise a well-formed call.
     """
     if not args or not isinstance(args, dict):
         return args
@@ -523,13 +529,42 @@ def coerce_tool_args(tool_name: str, args: Dict[str, Any]) -> Dict[str, Any]:
     if not properties:
         return args
 
-    for key, value in args.items():
-        if not isinstance(value, str):
-            continue
+    for key, value in list(args.items()):
         prop_schema = properties.get(key)
         if not prop_schema:
             continue
         expected = prop_schema.get("type")
+
+        # Wrap bare non-list values when the schema declares ``array``.
+        # Strings still go through _coerce_value first so JSON-encoded
+        # arrays (``'["a","b"]'``) get parsed and nullable ``"null"``
+        # becomes ``None`` rather than ``["null"]``.
+        # ``None`` itself is preserved — we don't know whether the model
+        # meant "omit" or "empty list", and tools with sensible defaults
+        # (e.g. read_file's normalize_read_pagination) already handle it.
+        if expected == "array" and value is not None and not isinstance(value, (list, tuple)):
+            if isinstance(value, str):
+                coerced = _coerce_value(value, expected, schema=prop_schema)
+                if coerced is not value:
+                    # _coerce_value handled it (JSON-parsed list or
+                    # nullable "null" → None).
+                    args[key] = coerced
+                    continue
+                args[key] = [value]
+                logger.info(
+                    "coerce_tool_args: wrapped bare string in list for %s.%s",
+                    tool_name, key,
+                )
+                continue
+            args[key] = [value]
+            logger.info(
+                "coerce_tool_args: wrapped bare %s in list for %s.%s",
+                type(value).__name__, tool_name, key,
+            )
+            continue
+
+        if not isinstance(value, str):
+            continue
         if not expected and not _schema_allows_null(prop_schema):
             continue
         coerced = _coerce_value(value, expected, schema=prop_schema)

nix/lib.nix

@@ -163,35 +163,42 @@
       for entry in "''${ENTRIES[@]}"; do
         IFS=":" read -r ATTR FOLDER NIX_FILE <<< "$entry"
         echo "==> .#$ATTR ($FOLDER -> $NIX_FILE)"
-        OUTPUT=$(nix build ".#$ATTR.npmDeps" --no-link --print-build-logs 2>&1)
-        STATUS=$?
-        if [ "$STATUS" -eq 0 ]; then
+
+        # Compute the actual hash from the lockfile directly using
+        # prefetch-npm-deps. This avoids false "ok" from nix build when
+        # an old derivation is cached in a substituter (cachix/cache.nixos.org).
+        LOCK_FILE="$FOLDER/package-lock.json"
+        NEW_HASH=$(${pkgs.lib.getExe pkgs.prefetch-npm-deps} "$LOCK_FILE" 2>/dev/null)
+        if [ -z "$NEW_HASH" ]; then
+          echo "    prefetch-npm-deps failed, falling back to nix build" >&2
+          OUTPUT=$(nix build ".#$ATTR.npmDeps" --no-link --print-build-logs 2>&1)
+          STATUS=$?
+          if [ "$STATUS" -eq 0 ]; then
+            echo "    ok (via nix build)"
+            continue
+          fi
+          NEW_HASH=$(echo "$OUTPUT" | awk '/got:/ {print $2; exit}')
+          if [ -z "$NEW_HASH" ]; then
+            if echo "$OUTPUT" | grep -qE "throttled|HTTP error 418|substituter .* is disabled|some outputs of .* are not valid"; then
+              echo "    skipped (transient cache failure — see primary nix build for real status)" >&2
+              echo "$OUTPUT" | tail -8 >&2
+              continue
+            fi
+            echo "    build failed with no hash mismatch:" >&2
+            echo "$OUTPUT" | tail -40 >&2
+            exit 1
+          fi
+        fi
+
+        OLD_HASH=$(grep -oE 'hash = "sha256-[^"]+"' "$NIX_FILE" | head -1 \
+          | sed -E 's/hash = "(.*)"/\1/')
+
+        if [ "$NEW_HASH" = "$OLD_HASH" ]; then
           echo "    ok"
           continue
         fi
 
-        NEW_HASH=$(echo "$OUTPUT" | awk '/got:/ {print $2; exit}')
-        if [ -z "$NEW_HASH" ]; then
-          # Magic-Nix-Cache occasionally returns HTTP 418 / cache-throttled
-          # mid-run; nix then prints "outputs … not valid, so checking is
-          # not possible" without a `got:` line.  That's an infrastructure
-          # blip, not a stale lockfile — warn + skip rather than failing
-          # the lint.  A real hash mismatch would still surface in the
-          # primary `.#$ATTR` build, which is a separate CI job.
-          if echo "$OUTPUT" | grep -qE "throttled|HTTP error 418|substituter .* is disabled|some outputs of .* are not valid"; then
-            echo "    skipped (transient cache failure — see primary nix build for real status)" >&2
-            echo "$OUTPUT" | tail -8 >&2
-            continue
-          fi
-          echo "    build failed with no hash mismatch:" >&2
-          echo "$OUTPUT" | tail -40 >&2
-          exit 1
-        fi
-
         HASH_LINE=$(grep -n 'hash = "sha256-' "$NIX_FILE" | head -1 | cut -d: -f1)
-        OLD_HASH=$(grep -oE 'hash = "sha256-[^"]+"' "$NIX_FILE" | head -1 \
-          | sed -E 's/hash = "(.*)"/\1/')
-        LOCK_FILE="$FOLDER/package-lock.json"
         echo "    stale: $NIX_FILE:$HASH_LINE $OLD_HASH -> $NEW_HASH"
         STALE=1
 

nix/tui.nix

@@ -4,7 +4,7 @@ let
   src = ../ui-tui;
   npmDeps = pkgs.fetchNpmDeps {
     inherit src;
-    hash = "sha256-a/HGI9OgVcTnZrMXA7xFMGnFoVxyHe95fulVz+WNYB0=";
+    hash = "sha256-MLcLhjTF6dgdvNBtJWzo8Nh19eNh/ZitD2b07nm61Tc=";
   };
 
   npm = hermesNpmLib.mkNpmPassthru { folder = "ui-tui"; attr = "tui"; pname = "hermes-tui"; };

optional-skills/creative/hyperframes/SKILL.md

@@ -0,0 +1,190 @@
+---
+name: hyperframes
+description: Create HTML-based video compositions, animated title cards, social overlays, captioned talking-head videos, audio-reactive visuals, and shader transitions using HyperFrames. HTML is the source of truth for video. Use when the user wants a rendered MP4/WebM from an HTML composition, wants to animate text/logos/charts over media, needs captions synced to audio, wants TTS narration, or wants to convert a website into a video.
+version: 1.0.0
+author: heygen-com
+license: Apache-2.0
+prerequisites:
+  commands: [node, ffmpeg, npx]
+metadata:
+  hermes:
+    tags: [creative, video, animation, html, gsap, motion-graphics]
+    related_skills: [manim-video, meme-generation]
+    category: creative
+    requires_toolsets: [terminal]
+---
+
+# HyperFrames
+
+HTML is the source of truth for video. A composition is an HTML file with `data-*` attributes for timing, a GSAP timeline for animation, and CSS for appearance. The HyperFrames engine captures the page frame-by-frame and encodes to MP4/WebM with FFmpeg.
+
+**Complement to `manim-video`:** Use `manim-video` for mathematical/geometric explainers (equations, 3B1B-style). Use `hyperframes` for motion-graphics, talking-head with captions, product tours, social overlays, shader transitions, and anything driven by real video/audio media.
+
+## When to Use
+
+- User asks for a rendered video from text, a script, or a website
+- Animated title cards, lower thirds, or typographic intros
+- Captioned narration video (TTS + captions synced to waveform)
+- Audio-reactive visuals (beat sync, spectrum bars, pulsing glow)
+- Scene-to-scene transitions (crossfade, wipe, shader warp, flash-through-white)
+- Social overlays (Instagram/TikTok/YouTube style)
+- Website-to-video pipeline (capture a URL, produce a promo)
+- Any HTML/CSS/JS animation that must render deterministically to a video file
+
+Do **not** use this skill for:
+- Pure math/equation animation (→ `manim-video`)
+- Image generation or memes (→ `meme-generation`, image models)
+- Live video conferencing or streaming
+
+## Quick Reference
+
+```bash
+npx hyperframes init my-video               # scaffold a project
+cd my-video
+npx hyperframes lint                        # validate before preview/render
+npx hyperframes preview                     # live-reload browser preview (port 3002)
+npx hyperframes render --output final.mp4   # render to MP4
+npx hyperframes doctor                      # diagnose environment issues
+```
+
+Render flags: `--quality draft|standard|high` · `--fps 24|30|60` · `--format mp4|webm` · `--docker` (reproducible) · `--strict`.
+
+Full CLI reference: [references/cli.md](references/cli.md).
+
+## Setup (one-time)
+
+```bash
+bash "$(dirname "$(find ~/.hermes/skills -path '*/hyperframes/SKILL.md' 2>/dev/null | head -1)")/scripts/setup.sh"
+```
+
+The script:
+1. Verifies Node.js >= 22 and FFmpeg are installed (prints fix instructions if not).
+2. Installs the `hyperframes` CLI globally (`npm install -g hyperframes@>=0.4.2`).
+3. Pre-caches `chrome-headless-shell` via Puppeteer — **required** for best-quality rendering via Chrome's `HeadlessExperimental.beginFrame` capture path.
+4. Runs `npx hyperframes doctor` and reports the result.
+
+See [references/troubleshooting.md](references/troubleshooting.md) if setup fails.
+
+## Procedure
+
+### 1. Plan before writing HTML
+
+Before touching code, articulate at a high level:
+- **What** — narrative arc, key moments, emotional beats
+- **Structure** — compositions, tracks (video/audio/overlays), durations
+- **Visual identity** — colors, fonts, motion character (explosive / cinematic / fluid / technical)
+- **Hero frame** — for each scene, the moment when the most elements are simultaneously visible. This is the static layout you'll build first.
+
+**Visual Identity Gate (HARD-GATE).** Before writing ANY composition HTML, a visual identity must be defined. Do NOT write compositions with default or generic colors (`#333`, `#3b82f6`, `Roboto` are tells that this step was skipped). Check in order:
+
+1. **`DESIGN.md` at project root?** → Use its exact colors, fonts, motion rules, and "What NOT to Do" constraints.
+2. **User named a style** (e.g. "Swiss Pulse", "dark and techy", "luxury brand")? → Generate a minimal `DESIGN.md` with `## Style Prompt`, `## Colors` (3-5 hex with roles), `## Typography` (1-2 families), `## What NOT to Do` (3-5 anti-patterns).
+3. **None of the above?** → Ask 3 questions before writing any HTML:
+   - Mood? (explosive / cinematic / fluid / technical / chaotic / warm)
+   - Light or dark canvas?
+   - Any brand colors, fonts, or visual references?
+
+   Then generate a `DESIGN.md` from the answers. Every composition must trace its palette and typography back to `DESIGN.md` or explicit user direction.
+
+### 2. Scaffold
+
+```bash
+npx hyperframes init my-video --non-interactive
+```
+
+Templates: `blank`, `warm-grain`, `play-mode`, `swiss-grid`, `vignelli`, `decision-tree`, `kinetic-type`, `product-promo`, `nyt-graph`. Pass `--example <name>` to pick one, `--video clip.mp4` or `--audio track.mp3` to seed with media.
+
+### 3. Layout before animation
+
+Write the static HTML+CSS for the **hero frame first** — no GSAP yet. The `.scene-content` container must fill the scene (`width:100%; height:100%; padding:Npx`) with `display:flex` + `gap`. Use padding to push content inward — never `position: absolute; top: Npx` on a content container (content overflows when taller than the remaining space).
+
+Only after the hero frame looks right, add `gsap.from()` entrances (animate **to** the CSS position) and `gsap.to()` exits (animate **from** it).
+
+See [references/composition.md](references/composition.md) for the full data-attribute schema and composition rules.
+
+### 4. Animate with GSAP
+
+Every composition must:
+- Register its timeline: `window.__timelines["<composition-id>"] = tl`
+- Start paused: `gsap.timeline({ paused: true })` — the player controls playback
+- Use finite `repeat` values (no `repeat: -1` — breaks the capture engine). Calculate: `repeat: Math.ceil(duration / cycleDuration) - 1`.
+- Be deterministic — no `Math.random()`, `Date.now()`, or wall-clock logic. Use a seeded PRNG if you need pseudo-randomness.
+- Build synchronously — no `async`/`await`, `setTimeout`, or Promises around timeline construction.
+
+See [references/gsap.md](references/gsap.md) for the core GSAP API (tweens, eases, stagger, timelines).
+
+### 5. Transitions between scenes
+
+Multi-scene compositions require transitions. Rules:
+1. **Always use a transition between scenes** — no jump cuts.
+2. **Always use entrance animations** on every scene element (`gsap.from(...)`).
+3. **Never use exit animations** except on the final scene — the transition IS the exit.
+4. The final scene may fade out.
+
+Use `npx hyperframes add <transition-name>` to install shader transitions (`flash-through-white`, `liquid-wipe`, etc.). Full list: `npx hyperframes add --list`.
+
+### 6. Audio, captions, TTS, audio-reactive, highlighting
+
+- **Audio:** always a separate `<audio>` element (video is `muted playsinline`).
+- **TTS:** `npx hyperframes tts "Script text" --voice af_nova --output narration.wav`. List voices with `--list`. Voice ID first letter encodes language (`a`/`b`=English, `e`=Spanish, `f`=French, `j`=Japanese, `z`=Mandarin, etc.) — the CLI auto-infers the phonemizer locale; pass `--lang` only to override. Non-English phonemization requires `espeak-ng` installed system-wide.
+- **Captions:** `npx hyperframes transcribe narration.wav` → word-level transcript. Pick style from the transcript tone (hype / corporate / tutorial / storytelling / social — see the table in `references/features.md`). **Language rule:** never use `.en` whisper models unless the audio is confirmed English — `.en` translates non-English audio instead of transcribing it. Every caption group MUST have a hard `tl.set(el, { opacity: 0, visibility: "hidden" }, group.end)` kill after its exit tween — otherwise groups leak visible into later ones.
+- **Audio-reactive visuals:** pre-extract audio bands (bass / mid / treble) and sample per-frame inside the timeline with a `for` loop of `tl.call(draw, [], f / fps)` — a single long tween does NOT react to audio. Map bass → `scale` (pulse), treble → `textShadow`/`boxShadow` (glow), overall amplitude → `opacity`/`y`/`backgroundColor`. Avoid equalizer-bar clichés — let content guide the visual, audio drive its behavior.
+- **Marker-style highlighting:** highlight, circle, burst, scribble, sketchout effects for text emphasis are deterministic CSS+GSAP — see `references/features.md#marker-highlighting`. Fully seekable, no animated SVG filters.
+- **Scene transitions:** every multi-scene composition MUST use transitions (no jump cuts). Pick from CSS primitives (push slide, blur crossfade, zoom through, staggered blocks) or shader transitions (`flash-through-white`, `liquid-wipe`, `cross-warp-morph`, `chromatic-split`, etc.) via `npx hyperframes add`. Mood and energy tables live in `references/features.md#transitions`. Do not mix CSS and shader transitions in the same composition.
+
+### 7. Lint, validate, inspect, preview, render
+
+```bash
+npx hyperframes lint              # catches missing data-composition-id, overlapping tracks, unregistered timelines
+npx hyperframes validate          # WCAG contrast audit at 5 timestamps
+npx hyperframes inspect           # visual layout audit — overflow, off-frame elements, occluded text
+npx hyperframes preview           # live browser preview
+npx hyperframes render --quality draft --output draft.mp4    # fast iteration
+npx hyperframes render --quality high --output final.mp4     # final delivery
+```
+
+`hyperframes validate` samples background pixels behind every text element and warns on contrast ratios below 4.5:1 (or 3:1 for large text). `hyperframes inspect` is the layout-side companion — runs the page at multiple timestamps and flags issues that a static lint can't see (a caption that wraps past the safe area only at 4.5s, a card that overflows when its title is the longest variant, an element that ends up behind a transition shader). Run `inspect` especially on compositions with speech bubbles, cards, captions, or tight typography.
+
+### 8. Website-to-video (if the user gives a URL)
+
+Use the 7-step capture-to-video workflow in [references/website-to-video.md](references/website-to-video.md): capture → DESIGN.md → SCRIPT.md → storyboard → composition → render → deliver.
+
+## Pitfalls
+
+- **`HeadlessExperimental.beginFrame' wasn't found`** — Chromium 147+ removed this protocol. Ensure you're on `hyperframes@>=0.4.2` (auto-detects and falls back to screenshot mode). Escape hatch: `export PRODUCER_FORCE_SCREENSHOT=true`. See [hyperframes#294](https://github.com/heygen-com/hyperframes/issues/294) and [references/troubleshooting.md](references/troubleshooting.md).
+- **System Chrome (not `chrome-headless-shell`)** — renders hang for 120s then timeout. Run `npx puppeteer browsers install chrome-headless-shell` (setup.sh does this). `hyperframes doctor` reports which binary will be used.
+- **`repeat: -1` anywhere** — breaks the capture engine. Always compute a finite repeat count.
+- **`gsap.set()` on clip elements that enter later** — the element doesn't exist at page load. Use `tl.set(selector, vars, timePosition)` inside the timeline instead, at or after the clip's `data-start`.
+- **`<br>` inside content text** — forced breaks don't know the rendered font width, so natural wrap + `<br>` double-breaks. Use `max-width` to let text wrap. Exception: short display titles where each word is deliberately on its own line.
+- **Animating `visibility` or `display`** — GSAP can't tween these. Use `autoAlpha` (handles both visibility and opacity).
+- **Calling `video.play()` or `audio.play()`** — the framework owns playback. Never call these yourself.
+- **Building timelines async** — the capture engine reads `window.__timelines` synchronously after page load. Never wrap timeline construction in `async`, `setTimeout`, or a Promise.
+- **Standalone `index.html` wrapped in `<template>`** — hides all content from the browser. Only **sub-compositions** loaded via `data-composition-src` use `<template>`.
+- **Using video for audio** — always muted `<video>` + separate `<audio>`.
+
+## Verification
+
+Before and after rendering:
+
+1. **Lint + validate + inspect pass:** `npx hyperframes lint --strict && npx hyperframes validate && npx hyperframes inspect` (lint catches structural issues, validate catches contrast, inspect catches visual layout / overflow issues — see troubleshooting.md if warnings appear).
+2. **Animation choreography** — for new compositions or significant animation changes, run the animation map. `npx hyperframes init` copies the skill scripts into the project, so the path is project-local:
+   ```bash
+   node skills/hyperframes/scripts/animation-map.mjs <composition-dir> \
+     --out <composition-dir>/.hyperframes/anim-map
+   ```
+   Outputs a single `animation-map.json` with per-tween summaries, ASCII Gantt timeline, stagger detection, dead zones (>1s with no animation), element lifecycles, and flags (`offscreen`, `collision`, `invisible`, `paced-fast` <0.2s, `paced-slow` >2s). Scan summaries and flags — fix or justify each. Skip on small edits.
+3. **File exists + non-zero:** `ls -lh final.mp4`.
+4. **Duration matches `data-duration`:** `ffprobe -v error -show_entries format=duration -of default=nw=1:nk=1 final.mp4`.
+5. **Visual check:** extract a mid-composition frame: `ffmpeg -i final.mp4 -ss 00:00:05 -vframes 1 preview.png`.
+6. **Audio present if expected:** `ffprobe -v error -show_streams -select_streams a -of default=nw=1:nk=1 final.mp4 | head -1`.
+
+If `hyperframes render` fails, run `npx hyperframes doctor` and attach its output when reporting.
+
+## References
+
+- [composition.md](references/composition.md) — data attributes, timeline contract, non-negotiable rules, typography/asset rules
+- [cli.md](references/cli.md) — every CLI command (init, capture, lint, validate, inspect, preview, render, transcribe, tts, doctor, browser, info, upgrade, benchmark)
+- [gsap.md](references/gsap.md) — GSAP core API for HyperFrames (tweens, eases, stagger, timelines, matchMedia)
+- [features.md](references/features.md) — captions, TTS, audio-reactive, marker highlighting, transitions (load on demand)
+- [website-to-video.md](references/website-to-video.md) — 7-step capture-to-video workflow
+- [troubleshooting.md](references/troubleshooting.md) — OpenClaw fix, env vars, common render errors

optional-skills/creative/hyperframes/references/cli.md

@@ -0,0 +1,185 @@
+# HyperFrames CLI
+
+Everything runs through `npx hyperframes` (or the globally-installed `hyperframes` after `npm install -g hyperframes`). Requires Node.js >= 22 and FFmpeg.
+
+## Workflow
+
+1. **Scaffold** — `npx hyperframes init my-video` (or `npx hyperframes capture <url>` if starting from a website)
+2. **Write** — author HTML composition (see `composition.md`)
+3. **Lint** — `npx hyperframes lint`
+4. **Validate** — `npx hyperframes validate` (WCAG contrast audit)
+5. **Inspect** — `npx hyperframes inspect` (visual layout audit)
+6. **Preview** — `npx hyperframes preview`
+7. **Render** — `npx hyperframes render`
+
+Always lint before preview/render — catches missing `data-composition-id`, overlapping tracks, and unregistered timelines.
+
+## init — Scaffold a Project
+
+```bash
+npx hyperframes init my-video                        # interactive wizard
+npx hyperframes init my-video --example warm-grain   # pick an example template
+npx hyperframes init my-video --video clip.mp4       # seed with a video file
+npx hyperframes init my-video --audio track.mp3      # seed with an audio file
+npx hyperframes init my-video --non-interactive      # skip prompts (CI / agent use)
+```
+
+Templates: `blank`, `warm-grain`, `play-mode`, `swiss-grid`, `vignelli`, `decision-tree`, `kinetic-type`, `product-promo`, `nyt-graph`.
+
+`init` creates the correct file structure, copies media, transcribes audio with Whisper, and installs authoring skills. Use it instead of creating files by hand.
+
+## capture — Website → Editable Components
+
+```bash
+npx hyperframes capture https://example.com                  # → captures/example.com/
+npx hyperframes capture https://stripe.com -o stripe-video   # custom output dir
+npx hyperframes capture https://example.com --json           # machine-readable output
+npx hyperframes capture https://example.com --skip-assets    # skip images/SVGs
+```
+
+Captures the site into `captures/<hostname>/capture/` by default, producing `capture/screenshots/`, `capture/assets/`, `capture/extracted/` (tokens.json, visible-text.txt, fonts.json), and a self-contained snapshot.
+
+All downstream steps (DESIGN.md, SCRIPT.md, STORYBOARD, composition) read from the `capture/` subfolder — see `website-to-video.md`.
+
+## lint
+
+```bash
+npx hyperframes lint                # current directory
+npx hyperframes lint ./my-project   # specific project
+npx hyperframes lint --verbose      # include info-level findings
+npx hyperframes lint --json         # machine-readable output
+```
+
+Lints `index.html` and all files in `compositions/`. Reports errors (must fix), warnings (should fix), and info (only with `--verbose`).
+
+## validate
+
+```bash
+npx hyperframes validate                 # WCAG contrast audit at 5 timestamps
+npx hyperframes validate --no-contrast   # skip while iterating
+```
+
+Seeks to 5 timestamps, screenshots the page, samples background pixels behind every text element, and warns on contrast ratios below 4.5:1 (normal text) or 3:1 (large text — 24px+, or 19px+ bold). Run before final render.
+
+## inspect
+
+```bash
+npx hyperframes inspect                 # visual layout audit at 5 timestamps
+npx hyperframes inspect ./my-project    # specific project
+npx hyperframes inspect --json          # agent-readable findings
+npx hyperframes inspect --samples 15    # denser timeline sweep
+npx hyperframes inspect --at 1.5,4,7.25 # explicit hero-frame timestamps
+```
+
+Use this after `lint` and `validate`, especially for compositions with speech bubbles, cards, captions, or tight typography. Reports overflow, off-frame elements, occluded text, contrast warnings, and per-timestamp layout summaries — catches issues that pure timeline lint can't see (e.g., a caption that wraps past the safe area only at a specific timestamp).
+
+`npx hyperframes layout` is a compatibility alias for the same visual inspection pass.
+
+## preview
+
+```bash
+npx hyperframes preview                # serve current directory (port 3002)
+npx hyperframes preview --port 4567    # custom port
+```
+
+Hot-reloads on file changes. Opens the Studio in your browser automatically.
+
+## render
+
+```bash
+npx hyperframes render                              # standard MP4
+npx hyperframes render --output final.mp4           # named output
+npx hyperframes render --quality draft              # fast iteration
+npx hyperframes render --fps 60 --quality high      # final delivery
+npx hyperframes render --format webm                # transparent WebM
+npx hyperframes render --docker                     # byte-identical reproducible render
+```
+
+| Flag           | Options                 | Default                        | Notes                       |
+| -------------- | ----------------------- | ------------------------------ | --------------------------- |
+| `--output`     | path                    | `renders/<name>_<timestamp>.mp4` | Output path                 |
+| `--fps`        | 24, 30, 60              | 30                             | 60fps doubles render time   |
+| `--quality`    | `draft`, `standard`, `high` | standard                   | draft for iterating         |
+| `--format`     | `mp4`, `webm`           | mp4                            | WebM supports transparency  |
+| `--workers`    | 1–8 or `auto`           | auto                           | Each spawns Chrome          |
+| `--docker`     | flag                    | off                            | Reproducible output         |
+| `--gpu`        | flag                    | off                            | GPU-accelerated encoding    |
+| `--strict`     | flag                    | off                            | Fail on lint errors         |
+| `--strict-all` | flag                    | off                            | Fail on errors AND warnings |
+
+**Quality guidance:** `draft` while iterating, `standard` for review, `high` for final delivery.
+
+## transcribe
+
+```bash
+npx hyperframes transcribe audio.mp3
+npx hyperframes transcribe video.mp4 --model medium.en --language en
+npx hyperframes transcribe subtitles.srt     # import existing
+npx hyperframes transcribe subtitles.vtt
+npx hyperframes transcribe openai-response.json
+```
+
+Produces word-level timings suitable for caption components. First run downloads the Whisper model (cached after).
+
+## tts
+
+```bash
+npx hyperframes tts "Text here" --voice af_nova --output narration.wav
+npx hyperframes tts script.txt --voice bf_emma
+npx hyperframes tts "La reunión empieza a las nueve" --voice ef_dora --output es.wav
+npx hyperframes tts "Hello there" --voice af_heart --lang fr-fr --output accented.wav
+npx hyperframes tts --list                    # show all voices
+```
+
+Uses Kokoro (local, no API key). Voice ID first letter encodes language: `a` American English, `b` British English, `e` Spanish, `f` French, `h` Hindi, `i` Italian, `j` Japanese, `p` Brazilian Portuguese, `z` Mandarin. The CLI auto-infers the phonemizer locale from that prefix — pass `--lang` only to override (e.g. stylized accents). Valid `--lang` codes: `en-us`, `en-gb`, `es`, `fr-fr`, `hi`, `it`, `pt-br`, `ja`, `zh`. Non-English phonemization requires `espeak-ng` installed system-wide (`apt-get install espeak-ng` / `brew install espeak-ng`).
+
+## doctor
+
+```bash
+npx hyperframes doctor
+```
+
+Verifies environment:
+- Node.js >= 22
+- FFmpeg present on PATH
+- Available RAM (renders are memory-hungry — 4 GB minimum)
+- Chrome binary resolution (`chrome-headless-shell` preferred over system Chrome)
+- Current `hyperframes` version
+
+Run this **first** when a render fails. See `troubleshooting.md` for interpreting the output.
+
+## browser
+
+```bash
+npx hyperframes browser --install      # install the bundled chrome-headless-shell
+npx hyperframes browser --path         # print the resolved browser binary path
+npx hyperframes browser --clean        # clear the bundled browser cache
+```
+
+## info
+
+```bash
+npx hyperframes info
+```
+
+Prints version, Node version, FFmpeg version, OS, and resolved browser path — useful in bug reports.
+
+## upgrade
+
+```bash
+npx hyperframes upgrade -y
+```
+
+Check for and install updates. Run this if you hit `HeadlessExperimental.beginFrame` errors — the auto-detect fix shipped in `hyperframes@0.4.2` (commit 4c72ba4, March 2026).
+
+## Other
+
+```bash
+npx hyperframes compositions    # list compositions in the project
+npx hyperframes docs            # open documentation in browser
+npx hyperframes benchmark .     # benchmark render performance
+npx hyperframes add <block>     # install a block/component from the catalog
+npx hyperframes add --list      # browse the catalog
+```
+
+Popular catalog blocks: `flash-through-white` (shader transition), `instagram-follow` (social overlay), `data-chart` (animated chart), `lower-third` (talking-head overlay). See [hyperframes.heygen.com/catalog](https://hyperframes.heygen.com/catalog).

optional-skills/creative/hyperframes/references/composition.md

@@ -0,0 +1,129 @@
+# Composition Authoring
+
+HTML structure, data attributes, timeline contract, and non-negotiable rules.
+
+## Root Structure
+
+Standalone `index.html` — the top-level composition. **Does NOT use `<template>`**. Put the `data-composition-id` div directly in `<body>`.
+
+```html
+<!doctype html>
+<html>
+  <body>
+    <div
+      id="stage"
+      data-composition-id="root"
+      data-start="0"
+      data-duration="10"
+      data-width="1920"
+      data-height="1080"
+    >
+      <!-- clips go here -->
+      <video id="clip-1" data-start="0" data-duration="5" data-track-index="0" src="intro.mp4" muted playsinline></video>
+      <img id="logo" data-start="2" data-duration="3" data-track-index="1" src="logo.png" />
+      <audio id="music" data-start="0" data-duration="10" data-track-index="2" data-volume="0.5" src="music.wav"></audio>
+    </div>
+
+    <script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+    <script>
+      window.__timelines = window.__timelines || {};
+      const tl = gsap.timeline({ paused: true });
+      tl.from("#logo", { opacity: 0, y: 40, duration: 0.6 }, 2);
+      window.__timelines["root"] = tl;
+    </script>
+  </body>
+</html>
+```
+
+Sub-compositions loaded via `data-composition-src` **DO** use `<template>`:
+
+```html
+<template id="my-comp-template">
+  <div data-composition-id="my-comp" data-width="1920" data-height="1080">
+    <!-- content + scoped <style> + <script> with window.__timelines["my-comp"] -->
+  </div>
+</template>
+```
+
+Load from the root: `<div id="el-1" data-composition-id="my-comp" data-composition-src="compositions/my-comp.html" data-start="0" data-duration="10" data-track-index="1"></div>`
+
+## Data Attributes
+
+### All clips
+
+| Attribute          | Required                          | Values                                                 |
+| ------------------ | --------------------------------- | ------------------------------------------------------ |
+| `id`               | Yes                               | Unique identifier                                      |
+| `data-start`       | Yes                               | Seconds, or clip ID reference (`"el-1"`, `"intro + 2"`) |
+| `data-duration`    | Required for img/div/compositions | Seconds. Video/audio defaults to media duration.       |
+| `data-track-index` | Yes                               | Integer. Same-track clips cannot overlap.              |
+| `data-media-start` | No                                | Trim offset into source (seconds)                      |
+| `data-volume`      | No                                | 0–1 (default 1)                                        |
+
+`data-track-index` controls timeline layout only — **not** visual layering. Use CSS `z-index` for layering.
+
+### Composition clips
+
+| Attribute                    | Required | Values                                       |
+| ---------------------------- | -------- | -------------------------------------------- |
+| `data-composition-id`        | Yes      | Unique composition ID                        |
+| `data-start`                 | Yes      | Start time (root composition: `"0"`)         |
+| `data-duration`              | Yes      | Takes precedence over GSAP timeline duration |
+| `data-width` / `data-height` | Yes      | Pixel dimensions (1920x1080 or 1080x1920)    |
+| `data-composition-src`       | No       | Path to external HTML file                   |
+
+## Timeline Contract
+
+- Every timeline starts `{ paused: true }` — the player controls playback.
+- Register every timeline: `window.__timelines["<composition-id>"] = tl`.
+- Duration comes from `data-duration`, not from the GSAP timeline length.
+- Framework auto-nests sub-timelines — do NOT manually add them.
+- Never create empty tweens just to set duration.
+
+## Non-Negotiable Rules
+
+1. **Deterministic.** No `Math.random()`, `Date.now()`, or time-based logic. Use a seeded PRNG (e.g. mulberry32) if you need pseudo-randomness.
+2. **GSAP only on visual properties.** `opacity`, `x`, `y`, `scale`, `rotation`, `color`, `backgroundColor`, `borderRadius`, transforms. Never animate `visibility`, `display`, or call `video.play()`/`audio.play()`.
+3. **No property conflicts across timelines.** Never animate the same property on the same element from multiple timelines simultaneously.
+4. **No `repeat: -1`.** Infinite-repeat tweens break the capture engine. Compute `repeat: Math.ceil(duration / cycleDuration) - 1`.
+5. **Synchronous timeline construction.** Never build timelines inside `async`/`await`, `setTimeout`, or Promises. The capture engine reads `window.__timelines` synchronously after page load. Fonts are embedded by the compiler — no need to wait for load.
+6. **Root composition has no `<template>` wrapper.** Only sub-compositions use `<template>`.
+7. **Video is always `muted playsinline`.** Audio is always a separate `<audio>` element — even if it's the same source file.
+8. **Content containers use padding, not absolute positioning.** `.scene-content { width: 100%; height: 100%; padding: Npx; display: flex; flex-direction: column; gap: Npx; box-sizing: border-box }`. Absolute-positioned content containers overflow. Reserve `position: absolute` for decoratives only.
+
+## Scene Transitions
+
+Multi-scene compositions MUST follow all of these:
+
+1. **Always use a transition between scenes.** No jump cuts.
+2. **Always use entrance animations** on every scene element. Every element animates IN via `gsap.from(...)`. No element may appear fully-formed.
+3. **Never use exit animations** (except on the final scene). This means NO `gsap.to()` that animates `opacity` to 0, `y` offscreen, etc. The transition IS the exit. Outgoing scene content must be fully visible at the moment the transition starts.
+4. **Final scene only:** may fade elements out. This is the only scene where `gsap.to(..., { opacity: 0 })` is allowed.
+
+## Typography and Assets
+
+- **Fonts:** write the `font-family` you want in CSS — the compiler embeds supported fonts automatically. Unsupported fonts produce a compiler warning.
+- Add `crossorigin="anonymous"` to external media.
+- For dynamic text sizing, use `window.__hyperframes.fitTextFontSize(text, { maxWidth, fontFamily, fontWeight })`.
+- All project files live at the project root alongside `index.html`. Sub-compositions reference assets with `../`.
+- For rendered video: 60px+ headlines, 20px+ body, 16px+ data labels. `font-variant-numeric: tabular-nums` on number columns. Avoid full-screen linear gradients on dark backgrounds (H.264 banding — use radial or solid + localized glow).
+
+## Animation Guardrails
+
+- Offset the first animation 0.1–0.3s (not `t=0`).
+- Vary eases across entrance tweens — at least 3 different eases per scene.
+- Don't repeat an entrance pattern within a scene.
+
+## Never Do
+
+1. Forget `window.__timelines` registration.
+2. Use video for audio — always muted video + separate `<audio>`.
+3. Nest video inside a timed div — use a non-timed wrapper.
+4. Use `data-layer` (use `data-track-index`) or `data-end` (use `data-duration`).
+5. Animate video element dimensions — animate a wrapper div instead.
+6. Call `play`/`pause`/`seek` on media — framework owns playback.
+7. Create a top-level container without `data-composition-id`.
+8. Use `repeat: -1` on any timeline or tween.
+9. Build timelines asynchronously.
+10. Use `gsap.set()` on elements from later scenes — they don't exist in the DOM at page load. Use `tl.set(selector, vars, timePosition)` inside the timeline at or after the clip's `data-start`.
+11. Use `<br>` in content text — causes unwanted extra breaks when the text wraps naturally. Use `max-width` instead. Exception: short display titles (e.g., "THE\nIMMORTAL\nGAME") where each word is deliberately on its own line.

optional-skills/creative/hyperframes/references/features.md

@@ -0,0 +1,289 @@
+# HyperFrames Feature Reference
+
+Load this file when a composition needs captions, TTS narration, audio-reactive visuals, marker-style text highlighting, or scene transitions. All patterns here are deterministic (no `Math.random()`, no `Date.now()`, no runtime audio analysis) and live on the same GSAP timeline as the rest of the composition.
+
+## Captions
+
+### Language Rule (Non-Negotiable)
+
+**Never use `.en` whisper models unless the audio is confirmed English.** `.en` models TRANSLATE non-English audio into English instead of transcribing it.
+
+- User says the language → `npx hyperframes transcribe audio.mp3 --model small --language <code>` (no `.en`)
+- User confirms English → `--model small.en`
+- Language unknown → `--model small` (auto-detects)
+
+### Style Detection
+
+If the user doesn't specify a caption style, detect it from the transcript tone:
+
+| Tone         | Font mood                | Animation                          | Color                       | Size    |
+| ------------ | ------------------------ | ---------------------------------- | --------------------------- | ------- |
+| Hype / launch   | Heavy condensed, 800-900 | Scale-pop, `back.out(1.7)`, 0.1-0.2s | Bright on dark              | 72-96px |
+| Corporate    | Clean sans, 600-700      | Fade+slide, `power3.out`, 0.3s       | White / neutral + muted accent | 56-72px |
+| Tutorial     | Mono / clean sans, 500-600 | Typewriter or fade, 0.4-0.5s          | High contrast, minimal      | 48-64px |
+| Storytelling | Serif / elegant, 400-500   | Slow fade, `power2.out`, 0.5-0.6s    | Warm muted tones            | 44-56px |
+| Social       | Rounded sans, 700-800    | Bounce, `elastic.out`, word-by-word  | Playful, colored pills      | 56-80px |
+
+### Word Grouping
+
+- High energy: 2-3 words, quick turnover.
+- Conversational: 3-5 words, natural phrases.
+- Measured / calm: 4-6 words.
+
+Break on sentence boundaries, 150ms+ pauses, or a max word count.
+
+### Positioning
+
+- Landscape (1920x1080): bottom 80-120px, centered.
+- Portrait (1080x1920): ~600-700px from bottom, centered.
+- Never cover the subject's face. `position: absolute` (never relative). One caption group visible at a time.
+
+### Text Overflow Prevention
+
+Use the runtime helper so captions never overflow:
+
+```js
+const result = window.__hyperframes.fitTextFontSize(group.text.toUpperCase(), {
+  fontFamily: "Outfit",
+  fontWeight: 900,
+  maxWidth: 1600, // 1600 landscape, 900 portrait
+});
+el.style.fontSize = result.fontSize + "px";
+```
+
+When per-word styling uses `scale > 1.0`, compute `maxWidth = safeWidth / maxScale` to leave headroom. Container needs `overflow: visible` (not `hidden` — hidden clips scaled emphasis words and glow).
+
+### Caption Exit Guarantee
+
+Every group MUST have a hard kill after its exit tween — otherwise groups leak into later ones:
+
+```js
+tl.to(groupEl, { opacity: 0, scale: 0.95, duration: 0.12, ease: "power2.in" }, group.end - 0.12);
+tl.set(groupEl, { opacity: 0, visibility: "hidden" }, group.end); // deterministic kill
+```
+
+### Per-Word Styling
+
+Scan the transcript for words that deserve distinct treatment:
+
+- Brand / product names — larger, unique color.
+- ALL CAPS — scale boost, flash, accent color.
+- Numbers / statistics — bold weight, accent color.
+- Emotional keywords — exaggerated animation (overshoot, bounce).
+- Call-to-action — highlight, underline, color pop.
+
+## TTS (Kokoro-82M)
+
+Local, no API key. Runs on CPU. Model downloads on first use (~311 MB + ~27 MB voices, cached in `~/.cache/hyperframes/tts/`).
+
+### Voice Selection
+
+| Content type  | Voice                   | Why                         |
+| ------------- | ----------------------- | --------------------------- |
+| Product demo  | `af_heart` / `af_nova`  | Warm, professional          |
+| Tutorial      | `am_adam` / `bf_emma`   | Neutral, easy to follow     |
+| Marketing     | `af_sky` / `am_michael` | Energetic or authoritative  |
+| Documentation | `bf_emma` / `bm_george` | Clear British English       |
+| Casual        | `af_heart` / `af_sky`   | Approachable, natural       |
+
+Run `npx hyperframes tts --list` for all 54 voices across 8 languages.
+
+### Multilingual Phonemization
+
+Voice ID first letter encodes language: `a`=American English, `b`=British English, `e`=Spanish, `f`=French, `h`=Hindi, `i`=Italian, `j`=Japanese, `p`=Brazilian Portuguese, `z`=Mandarin. The CLI auto-infers the phonemizer locale from that prefix — you don't need `--lang` when voice and text match.
+
+```bash
+npx hyperframes tts "La reunión empieza a las nueve" --voice ef_dora --output es.wav
+npx hyperframes tts "今日はいい天気ですね"            --voice jf_alpha --output ja.wav
+```
+
+Pass `--lang` only to override auto-detection (e.g. stylized accents):
+
+```bash
+npx hyperframes tts "Hello there" --voice af_heart --lang fr-fr --output accented.wav
+```
+
+Valid `--lang` codes: `en-us`, `en-gb`, `es`, `fr-fr`, `hi`, `it`, `pt-br`, `ja`, `zh`. Non-English phonemization requires `espeak-ng` installed system-wide (`apt-get install espeak-ng` / `brew install espeak-ng`).
+
+### Speed
+
+- `0.7-0.8` — tutorial, complex content
+- `1.0` — natural (default)
+- `1.1-1.2` — intros, upbeat content
+- `1.5+` — rarely appropriate
+
+### TTS + Captions Workflow
+
+```bash
+npx hyperframes tts script.txt --voice af_heart --output narration.wav
+npx hyperframes transcribe narration.wav   # → transcript.json (word-level)
+```
+
+## Audio-Reactive Visuals
+
+Drive visuals from music, voice, or sound. Any GSAP-tweenable property can respond to pre-extracted audio data.
+
+### Data format
+
+```js
+const AUDIO_DATA = {
+  fps: 30,
+  totalFrames: 900,
+  frames: [{ bands: [0.82, 0.45, 0.31, /* ... */] }, /* ... */],
+};
+```
+
+`frames[i].bands[]` are frequency band amplitudes, 0-1. Index 0 = bass, higher indices = treble. Each band is normalized independently across the full track.
+
+### Mapping audio to visuals
+
+| Audio signal           | Visual property                   | Effect                     |
+| ---------------------- | --------------------------------- | -------------------------- |
+| Bass (`bands[0]`)      | `scale`                           | Pulse on beat              |
+| Treble (`bands[12-14]`)| `textShadow`, `boxShadow`         | Glow intensity             |
+| Overall amplitude      | `opacity`, `y`, `backgroundColor` | Breathe, lift, color shift |
+| Mid-range (`bands[4-8]`)| `borderRadius`, `width`          | Shape morphing             |
+
+Any GSAP-tweenable property works — `clipPath`, `filter`, SVG attributes, CSS custom properties. Let content guide the visual and let audio drive its behavior. **Never add** equalizer bars, spectrum analyzers, waveform displays, rainbow cycling, or generic particle systems — they look cheap.
+
+### Sampling pattern (required)
+
+Audio reactivity needs per-frame sampling via a `for` loop of `tl.call()`, NOT a single tween. A single long tween does NOT react to audio:
+
+```js
+for (let f = 0; f < AUDIO_DATA.totalFrames; f++) {
+  tl.call(
+    ((frame) => () => draw(frame))(AUDIO_DATA.frames[f]),
+    [],
+    f / AUDIO_DATA.fps,
+  );
+}
+```
+
+### Gotchas
+
+- **textShadow on a container** with semi-transparent children (e.g. inactive caption words at `rgba(255,255,255,0.3)`) renders a visible glow rectangle behind every child. Apply the glow to active words individually, not to the container.
+- **Subtlety for text** — 3-6% scale variation, soft glow. Heavy pulsing makes text unreadable.
+- **Go bigger on non-text** — backgrounds and shapes can handle 10-30% swings.
+- **Deterministic only** — pre-extracted audio data, no Web Audio API, no runtime analysis.
+
+## Marker-Style Highlighting
+
+Deterministic CSS + GSAP implementations of the classic "highlight / circle / burst / scribble / sketchout" drawing modes for emphasizing text. Fully seekable — no animated SVG filters, no JS timers.
+
+### Highlight (yellow marker sweep)
+
+```html
+<span class="mh-highlight-wrap">
+  <span class="mh-highlight-bar" id="hl-1"></span>
+  <span class="mh-highlight-text">highlighted text</span>
+</span>
+```
+
+```css
+.mh-highlight-wrap { position: relative; display: inline; }
+.mh-highlight-bar {
+  position: absolute; inset: 0 -6px;
+  background: #fdd835; opacity: 0.35;
+  transform: scaleX(0); transform-origin: left center;
+  border-radius: 3px; z-index: 0;
+}
+.mh-highlight-text { position: relative; z-index: 1; }
+```
+
+```js
+tl.to("#hl-1", { scaleX: 1, duration: 0.5, ease: "power2.out" }, 0.6);
+```
+
+Multi-line: apply to `.mh-highlight-bar` with `stagger: 0.3`.
+
+### Circle
+
+Hand-drawn ellipse around a word. Use a positioned `::before` with `border-radius: 50%`, slight rotation, and `clip-path` to avoid covering the letters. Animate `clip-path` or `stroke-dashoffset` on an inline SVG circle.
+
+### Burst
+
+Short radiating lines around a word. Render 6-12 small `<span>` elements positioned in a radial pattern; animate `scaleY` from 0.
+
+### Scribble
+
+A chaotic overlay created by animating `stroke-dashoffset` on an inline SVG `<path>` with a `d` attribute describing a zig-zag. Seed values, never `Math.random()`.
+
+### Sketchout
+
+A rough rectangle outline. Two `<rect>`s with slight `transform` offsets, animated via `stroke-dashoffset`.
+
+All five modes tween CSS transforms or `stroke-dashoffset` only — both tween cleanly, are deterministic, and seek correctly.
+
+## Scene Transitions
+
+Every multi-scene composition MUST use transitions. No jump cuts.
+
+### Energy → primary transition
+
+| Energy                               | CSS primary                  | Shader primary                       | Accent                         | Duration  | Easing                   |
+| ------------------------------------ | ---------------------------- | ------------------------------------ | ------------------------------ | --------- | ------------------------ |
+| **Calm** (wellness, brand, luxury)   | Blur crossfade, focus pull   | Cross-warp morph, thermal distortion | Light leak, circle iris        | 0.5-0.8s  | `sine.inOut`, `power1`   |
+| **Medium** (corporate, SaaS)         | Push slide, staggered blocks | Whip pan, cinematic zoom             | Squeeze, vertical push         | 0.3-0.5s  | `power2`, `power3`       |
+| **High** (promos, sports, launch)    | Zoom through, overexposure   | Ridged burn, glitch, chromatic split | Staggered blocks, gravity drop | 0.15-0.3s | `power4`, `expo`         |
+
+Pick ONE primary (60-70% of scene changes) plus 1-2 accents. Never use a different transition for every scene.
+
+### Mood → transition type
+
+| Mood                     | Transitions                                                                 |
+| ------------------------ | --------------------------------------------------------------------------- |
+| Warm / inviting          | Light leak, blur crossfade, focus pull, film burn · _Shader:_ thermal distortion, cross-warp morph |
+| Cold / clinical          | Squeeze, zoom out, blinds, shutter, grid dissolve · _Shader:_ gravitational lens |
+| Editorial / magazine     | Push slide, vertical push, diagonal split, shutter · _Shader:_ whip pan     |
+| Tech / futuristic        | Grid dissolve, staggered blocks, blinds · _Shader:_ glitch, chromatic split |
+| Tense / edgy             | Glitch, VHS, chromatic aberration, ripple · _Shader:_ ridged burn, domain warp |
+| Playful / fun            | Elastic push, 3D flip, circle iris, morph circle · _Shader:_ swirl vortex, ripple waves |
+| Dramatic / cinematic     | Zoom through, gravity drop, overexposure · _Shader:_ cinematic zoom, gravitational lens |
+| Premium / luxury         | Focus pull, blur crossfade, color dip to black · _Shader:_ cross-warp morph |
+| Retro / analog           | Film burn, light leak, VHS, clock wipe · _Shader:_ light leak               |
+
+### Presets
+
+| Preset     | Duration | Easing            |
+| ---------- | -------- | ----------------- |
+| `snappy`   | 0.2s     | `power4.inOut`    |
+| `smooth`   | 0.4s     | `power2.inOut`    |
+| `gentle`   | 0.6s     | `sine.inOut`      |
+| `dramatic` | 0.5s     | `power3.in` → out |
+| `instant`  | 0.15s    | `expo.inOut`      |
+| `luxe`     | 0.7s     | `power1.inOut`    |
+
+### Install a shader transition
+
+```bash
+npx hyperframes add flash-through-white
+npx hyperframes add --list
+```
+
+### CSS vs shader
+
+- **CSS transitions** animate scene containers with opacity, transforms, `clip-path`, and filters. Simpler to set up.
+- **Shader transitions** composite both scene textures per-pixel on a WebGL canvas — can warp, dissolve, and morph in ways CSS cannot. Import from `@hyperframes/shader-transitions` instead of writing raw GLSL.
+
+Don't mix CSS and shader transitions in the same composition — once a composition uses shader transitions, the WebGL canvas replaces DOM-based scene switching for every transition.
+
+### Shader-compatible CSS rules
+
+Shader transitions capture DOM scenes to WebGL textures via html2canvas. The canvas 2D pipeline doesn't match CSS exactly:
+
+1. No `transparent` keyword in gradients — use the target color at zero alpha: `rgba(200,117,51,0)` not `transparent`. (Canvas interpolates `transparent` as `rgba(0,0,0,0)` creating dark fringes.)
+2. No gradient backgrounds on elements thinner than 4px. Use solid `background-color` on thin accent lines.
+3. No CSS variables (`var()`) on elements visible during capture — html2canvas doesn't reliably resolve custom properties. Use literal color values.
+4. Mark uncapturable decoratives with `data-no-capture` — they stay on the live DOM but are absent from the shader texture.
+5. No gradient opacity below 0.15 — renders differently in canvas vs CSS.
+6. Every `.scene` div must have explicit `background-color`, AND pass the same color as `bgColor` in the `init()` config. Without either, the texture renders as black.
+
+These rules only apply to shader transition compositions. CSS-only compositions have no restrictions.
+
+### Don't
+
+- Mix CSS and shader transitions in one composition.
+- Use exit animations on any scene except the final scene — the transition IS the exit.
+- Introduce a new transition type every scene — pick one primary + 1-2 accents.
+- Use transitions that create visible geometric repetition (grids, hex cells, uniform dots) — they look artificial regardless of the math behind them. Prefer organic noise (FBM, domain warping).

optional-skills/creative/hyperframes/references/gsap.md

@@ -0,0 +1,136 @@
+# GSAP for HyperFrames
+
+GSAP is the animation engine for all HyperFrames compositions. Load from CDN inside the composition:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
+```
+
+## Core Tween Methods
+
+- **`gsap.to(targets, vars)`** — animate from current state to `vars`. Most common.
+- **`gsap.from(targets, vars)`** — animate from `vars` to current state (entrances).
+- **`gsap.fromTo(targets, fromVars, toVars)`** — explicit start and end.
+- **`gsap.set(targets, vars)`** — apply immediately (duration 0). Don't use on clip elements that enter later — use `tl.set(selector, vars, time)` inside the timeline instead.
+
+Always use **camelCase** property names (`backgroundColor`, `rotationX`, not `background-color`).
+
+## Common vars
+
+- **`duration`** — seconds (default 0.5).
+- **`delay`** — seconds before start.
+- **`ease`** — `"power1.out"` (default), `"power3.inOut"`, `"back.out(1.7)"`, `"elastic.out(1, 0.3)"`, `"none"`, `"expo.out"`, `"circ.inOut"`.
+- **`stagger`** — number `0.1` or object: `{ amount: 0.3, from: "center" }`, `{ each: 0.1, from: "random" }`.
+- **`overwrite`** — `false` (default), `true`, or `"auto"`.
+- **`repeat`** — number (never `-1` in HyperFrames). **`yoyo`** — alternates direction with repeat.
+- **`onComplete`**, **`onStart`**, **`onUpdate`** — callbacks.
+- **`immediateRender`** — default `true` for `from()`/`fromTo()`. Set `false` on later tweens targeting the same property+element to avoid overwrite surprises.
+
+## Transforms
+
+Prefer GSAP's transform aliases over raw CSS `transform`:
+
+| GSAP property               | Equivalent                 |
+| --------------------------- | -------------------------- |
+| `x`, `y`, `z`               | translateX/Y/Z (px)        |
+| `xPercent`, `yPercent`      | translateX/Y (%)           |
+| `scale`, `scaleX`, `scaleY` | scale                      |
+| `rotation`                  | rotate (deg)               |
+| `rotationX`, `rotationY`    | 3D rotate                  |
+| `skewX`, `skewY`            | skew                       |
+| `transformOrigin`           | transform-origin           |
+
+- **`autoAlpha`** — prefer over `opacity`. At 0, also sets `visibility: hidden`.
+- **CSS variables** — `"--hue": 180`.
+- **Directional rotation** — `"360_cw"`, `"-170_short"`, `"90_ccw"`.
+- **`clearProps`** — `"all"` or comma-separated; removes inline styles on complete.
+- **Relative values** — `"+=20"`, `"-=10"`, `"*=2"`.
+
+## Function-based Values
+
+```js
+gsap.to(".item", {
+  x: (i, target, targets) => i * 50,
+  stagger: 0.1,
+});
+```
+
+## Easing
+
+Built-in eases: `power1` through `power4`, `back`, `bounce`, `circ`, `elastic`, `expo`, `sine`. Each has `.in`, `.out`, `.inOut`.
+
+Rule of thumb:
+- Entrances: `power3.out`, `expo.out`, `back.out(1.4)`
+- Exits: `power2.in`, `expo.in`
+- Scrubbed sections: `none` (linear)
+- Vary eases across entrance tweens within a scene — at least 3 different eases.
+
+## Defaults
+
+```js
+gsap.defaults({ duration: 0.6, ease: "power2.out" });
+```
+
+## Timelines (HyperFrames primary pattern)
+
+```js
+window.__timelines = window.__timelines || {};
+
+const tl = gsap.timeline({ paused: true, defaults: { duration: 0.6, ease: "power2.out" } });
+
+tl.from(".title",    { y: 50, opacity: 0 }, 0.3);
+tl.from(".subtitle", { y: 30, opacity: 0 }, 0.5);
+tl.from(".cta",      { scale: 0.8, opacity: 0, ease: "back.out(1.7)" }, 0.8);
+
+window.__timelines["root"] = tl;
+```
+
+### Position parameter
+
+Third argument to `.from()` / `.to()` / `.add()`:
+
+- Absolute seconds: `0.5`, `2.1`.
+- Relative to end: `">+0.2"` (0.2s after previous), `"<"` (same time as previous), `"<+0.3"` (0.3s after previous's start).
+- Named labels: `tl.addLabel("act2", 5); tl.from(".x", { y: 30 }, "act2");`
+
+### Nesting
+
+HyperFrames auto-nests sub-composition timelines. **Do not** manually `tl.add(subTl)` — the framework wires sub-timelines into the parent at the sub-composition's `data-start`.
+
+### Playback
+
+The player controls playback. Don't call `tl.play()`, `tl.pause()`, or `tl.reverse()` at construction time. `{ paused: true }` is required.
+
+## Stagger
+
+```js
+// even distribution
+tl.from(".card", { opacity: 0, y: 40, stagger: 0.1 });
+
+// control total amount
+tl.from(".card", { opacity: 0, stagger: { amount: 0.6, from: "center" } });
+
+// deterministic "random" stagger (HyperFrames compositions must be deterministic)
+tl.from(".dot", { opacity: 0, stagger: { each: 0.05, from: "random" } });
+```
+
+`stagger.from`: `"start"` | `"end"` | `"center"` | `"edges"` | `"random"` | index | `[x, y]` for grid.
+
+## Performance
+
+- Animate transforms (`x`, `y`, `scale`, `rotation`, `opacity`) — cheap, GPU-accelerated.
+- Avoid animating `width`, `height`, `top`, `left`, `margin` — causes layout thrash.
+- Avoid box-shadow or filter animations on large elements — expensive.
+- `will-change` is rarely needed; GSAP handles promotion.
+
+## gsap.matchMedia (rarely needed in HyperFrames)
+
+Compositions have fixed dimensions (`data-width`/`data-height`), so responsive breakpoints don't apply. You may still use `matchMedia` for `prefers-reduced-motion` when authoring UI previews, but it's not used in rendered video output.
+
+## Don't Do
+
+- `repeat: -1` anywhere — breaks the capture engine.
+- `Math.random()`, `Date.now()`, performance.now()` inside tween values — non-deterministic.
+- `async` / `setTimeout` / `Promise` around timeline construction — the capture engine reads `window.__timelines` synchronously.
+- Animate `visibility` or `display` directly — use `autoAlpha`.
+- `gsap.set()` on clip elements that enter later in the timeline — they don't exist in the DOM at page-load. Use `tl.set(sel, vars, time)` inside the timeline.

optional-skills/creative/hyperframes/references/troubleshooting.md

@@ -0,0 +1,137 @@
+# Troubleshooting
+
+## `HeadlessExperimental.beginFrame' wasn't found` (first thing to check)
+
+**Symptom:** `npx hyperframes render` fails with:
+
+```
+✗ Render failed
+Protocol error (HeadlessExperimental.beginFrame):
+'HeadlessExperimental.beginFrame' wasn't found
+```
+
+**Cause:** Chromium 147+ removed the `HeadlessExperimental.beginFrame` CDP command. This affected sandbox environments (e.g., OpenClaw, some containerized agent hosts) that ship modern Chromium as the system browser. See [hyperframes#294](https://github.com/heygen-com/hyperframes/issues/294).
+
+**Fix (permanent — preferred):** upgrade.
+
+```bash
+npx hyperframes upgrade -y
+# or
+npm install -g hyperframes@latest
+```
+
+`hyperframes >= 0.4.2` auto-detects whether the resolved browser supports `beginFrame` (checks for `chrome-headless-shell` in the binary path) and falls back to screenshot capture mode when it doesn't. Commit [`4c72ba4`](https://github.com/heygen-com/hyperframes/commit/4c72ba4a36ec2bd6733f7b9cb2a9e63f9fb234b9) (March 2026) shipped this auto-detect.
+
+**Fix (escape hatch — if you can't upgrade):**
+
+```bash
+export PRODUCER_FORCE_SCREENSHOT=true
+npx hyperframes render
+```
+
+This forces screenshot mode regardless of the binary. Screenshot mode is slightly slower but visually identical.
+
+**Fix (prevent — recommended):** install `chrome-headless-shell` so the engine can use the fast BeginFrame path:
+
+```bash
+npx puppeteer browsers install chrome-headless-shell
+# or let the CLI do it
+npx hyperframes browser --install
+```
+
+`scripts/setup.sh` runs this automatically.
+
+## `npx hyperframes render` hangs for 120s then times out
+
+**Cause:** the resolved browser is system Chrome (e.g., `/usr/bin/google-chrome`) and doesn't support the BeginFrame path, but auto-detect also missed it (older `hyperframes` version).
+
+**Fix:**
+1. Check which binary is being used: `npx hyperframes browser --path`
+2. If it's system Chrome, either:
+   - Install `chrome-headless-shell`: `npx hyperframes browser --install`, OR
+   - Set the escape hatch: `export PRODUCER_FORCE_SCREENSHOT=true`, OR
+   - Upgrade: `npx hyperframes upgrade -y`
+
+## `ffmpeg: command not found`
+
+Install FFmpeg via your system package manager:
+
+| OS / distro     | Command                             |
+| --------------- | ----------------------------------- |
+| Ubuntu / Debian | `sudo apt-get install -y ffmpeg`    |
+| Fedora / RHEL   | `sudo dnf install -y ffmpeg`        |
+| Arch            | `sudo pacman -S ffmpeg`             |
+| macOS           | `brew install ffmpeg`               |
+| Windows         | `winget install Gyan.FFmpeg`        |
+
+Verify: `ffmpeg -version`.
+
+## `Node version X is not supported`
+
+HyperFrames requires Node.js >= 22. Check with `node --version`.
+
+- **nvm:** `nvm install 22 && nvm use 22`
+- **Homebrew (macOS):** `brew install node@22 && brew link --overwrite node@22`
+- **apt:** follow [nodesource](https://github.com/nodesource/distributions) for Node 22 LTS.
+
+## `ENOSPC: no space left on device` or OOM kills during render
+
+Renders are memory- and disk-hungry. Minimums:
+
+- **RAM:** 4 GB free (8 GB recommended for 60fps / `--quality high`)
+- **Disk:** 2 GB free scratch space — frames are written to `/tmp` during capture
+
+Mitigations:
+- Lower quality: `--quality draft`.
+- Lower fps: `--fps 24`.
+- Lower worker count: `--workers 1`.
+- Set `TMPDIR` to a volume with more space: `export TMPDIR=/mnt/scratch`.
+
+## Lint passes but the render is blank / black frames
+
+Check the browser console in `preview` — usually:
+- A timeline was registered with the wrong key (`__timelines["typo"]` instead of `__timelines["root"]`).
+- The root composition was wrapped in `<template>` (only sub-compositions use `<template>`).
+- A script tag failed to load — check Network tab in preview.
+
+Run `npx hyperframes lint --verbose` to see info-level findings.
+
+## Contrast warnings from `hyperframes validate`
+
+```
+⚠ WCAG AA contrast warnings (3):
+  · .subtitle "secondary text" — 2.67:1 (need 4.5:1, t=5.3s)
+```
+
+- **Dark backgrounds:** brighten the failing color until it clears 4.5:1 (normal text) or 3:1 (large text — 24px+ or 19px+ bold).
+- **Light backgrounds:** darken it.
+- Stay within the palette family — don't invent a new color, adjust the existing one.
+- Skip the check temporarily with `--no-contrast` if iterating rapidly, but clear it before delivery.
+
+## `Font family 'X' not supported by compiler`
+
+The compiler embeds a curated set of web-safe + open-source fonts. If a font isn't supported, either:
+- Swap to a supported alternative from the warning.
+- Register a custom font via `@font-face` pointing to a `.woff2` in the project directory (the compiler embeds referenced `@font-face` files).
+
+## Video plays back muted or with no audio
+
+Check:
+- The `<video>` element has `muted playsinline` (required — browser autoplay policy).
+- Audio is a **separate** `<audio>` element, not the video element.
+- Audio `data-volume` is set (defaults to 1).
+- The audio file is at the expected path — compositions load relative to their own directory.
+
+## Docker render fails on Linux with rootless Docker
+
+Add `--privileged` or pass `--cap-add=SYS_ADMIN`:
+
+```bash
+npx hyperframes render --docker --docker-args "--cap-add=SYS_ADMIN"
+```
+
+The headless browser needs namespace permissions for sandboxing.
+
+## Bug reports
+
+Include `npx hyperframes info` output + the full error log. File at [github.com/heygen-com/hyperframes](https://github.com/heygen-com/hyperframes/issues).

optional-skills/creative/hyperframes/references/website-to-video.md

@@ -0,0 +1,145 @@
+# Website to Video
+
+Capture a website, produce a professional video from it. Use when the user provides a URL and wants a video — social ad, product tour, 30-second promo, etc.
+
+The workflow has 7 steps. Each produces an artifact that gates the next. **Do not skip steps** — each artifact prevents a downstream failure mode.
+
+## Step 1: Capture & Understand
+
+```bash
+npx hyperframes capture https://example.com -o example-video
+```
+
+Produces `example-video/capture/` with:
+- `capture/screenshots/` — above-the-fold + section screenshots (up to `--max-screenshots`)
+- `capture/assets/` — logos, hero images, background video (if any)
+- `capture/extracted/tokens.json` — colors, fonts, and spacing tokens
+- `capture/extracted/visible-text.txt` — extracted headings, paragraphs, CTAs
+- `capture/extracted/fonts.json` — font families and stacks detected in computed styles
+- `capture/asset-descriptions.md` — auto-generated asset catalog
+
+All subsequent steps read from the `capture/` subfolder — `capture/extracted/tokens.json`, `capture/assets/hero.png`, etc. Never strip the `capture/` prefix when referencing these files.
+
+**Gate:** Print a site summary — name, top 3 colors, primary + display fonts, hero asset path, one-sentence vibe. Keep it in your context — don't re-capture.
+
+## Step 2: Write DESIGN.md
+
+Small brand reference at the project root. 6 sections, ~90 lines. This is the cheat sheet — not the creative plan.
+
+```markdown
+# DESIGN
+
+## Brand
+- Name: Example Co.
+- One-line mission: "…"
+
+## Colors
+- Background: #0B0F14
+- Primary: #00E0A4 (accent, CTA)
+- Secondary: #7A8B9B (body text)
+- Text: #FFFFFF
+
+## Typography
+- Display: "Inter Tight", 700, tight letter-spacing
+- Body: "Inter", 400
+
+## Motion
+- Mood: precise, technical, confident
+- Eases: `power3.out` for entrances, `expo.in` for exits
+
+## Assets
+- Logo: `capture/assets/logo.svg`
+- Hero image: `capture/assets/hero.png`
+
+## What NOT to Do
+- No purple, no pastels, no serif body
+- No playful/bubbly eases (`elastic`, `bounce`)
+- No drop shadows on text
+```
+
+**Gate:** `DESIGN.md` exists in the project directory.
+
+## Step 3: Write SCRIPT.md
+
+Narration script. Story backbone. **Scene durations come from the narration, not from guessing.**
+
+```markdown
+# SCRIPT
+
+## Scene 1 — Hook (0:00–0:04)
+"What if your dashboards wrote themselves?"
+
+## Scene 2 — Problem (0:04–0:11)
+"Teams spend hours stitching together queries, charts, and callouts — every Monday."
+
+## Scene 3 — Solution (0:11–0:22)
+"Example Co. watches your data streams and proposes the dashboard you'd have built — in seconds."
+
+## Scene 4 — CTA (0:22–0:28)
+"Try it free at example.com."
+```
+
+Run `npx hyperframes tts SCRIPT.md --voice af_nova --output narration.wav` to generate TTS audio. Note the exact duration — that's the video's duration.
+
+**Gate:** `SCRIPT.md` + `narration.wav` exist and durations match the plan (±0.3s).
+
+## Step 4: Storyboard
+
+Text-only scene plan: for each scene, describe the hero frame — what's on screen at the scene's most-visible moment.
+
+```markdown
+# STORYBOARD
+
+## Scene 1 (0:00–0:04) — Hook
+Hero frame: giant "WHAT IF YOUR DASHBOARDS WROTE THEMSELVES?" in display font, centered, on near-black. Logo top-left at 40% opacity.
+Entrance: each word staggers in, 0.08s apart.
+Transition out: flash-through-white into Scene 2.
+```
+
+One paragraph per scene. Do NOT skip this step — it's where you catch narrative gaps before writing HTML.
+
+**Gate:** `STORYBOARD.md` exists. Each scene has: hero frame, entrance, transition.
+
+## Step 5: Composition
+
+Write `index.html` scene-by-scene:
+- Each scene is a `<div class="scene scene-N">` positioned absolutely, full-bleed.
+- Static HTML+CSS for the hero frame first (no GSAP).
+- Layer the narration `<audio>` at `data-start="0"` on a high track index.
+- Add a transitions component (`flash-through-white`, `liquid-wipe`, etc.) between each scene.
+- THEN add GSAP entrances (`gsap.from()`), no exits — transitions own the exit.
+- Register `window.__timelines["root"] = tl`.
+
+Install transitions as needed:
+
+```bash
+npx hyperframes add flash-through-white
+```
+
+## Step 6: Render
+
+```bash
+npx hyperframes lint --strict          # must pass
+npx hyperframes validate               # WCAG contrast audit
+npx hyperframes render --quality draft --output draft.mp4
+```
+
+Watch the draft. Note issues in a `REVIEW.md` bullet list (scene, timestamp, issue). Fix, re-render.
+
+When happy:
+
+```bash
+npx hyperframes render --quality high --output final.mp4
+```
+
+## Step 7: Deliver
+
+- Report file path + duration + file size to the user.
+- If the user wants a vertical cut, re-render with a 9:16 composition (`data-width="1080" data-height="1920"`) — typically requires a separate `index-vertical.html` with tighter typography and re-stacked scene layout.
+
+## Common Failure Modes
+
+- **Skipped DESIGN.md** → colors drift scene-to-scene; output feels like "AI slides."
+- **Skipped STORYBOARD.md** → scenes overlap or hero frames collide with transitions.
+- **Exit animations** before transitions → empty frames when the transition fires.
+- **Narration longer than `data-duration`** → audio clips mid-sentence. Update the composition's `data-duration` to match the TTS output length + 0.5s buffer.

optional-skills/creative/hyperframes/scripts/setup.sh

@@ -0,0 +1,135 @@
+#!/usr/bin/env bash
+# HyperFrames setup for Hermes.
+#
+# Verifies Node >= 22 and FFmpeg, installs the `hyperframes` CLI globally,
+# pre-caches `chrome-headless-shell`, and runs `hyperframes doctor`.
+#
+# Pins `hyperframes@>=0.4.2` so the OpenClaw/Chromium-147 fix from
+# https://github.com/heygen-com/hyperframes/issues/294 (commit 4c72ba4)
+# is always present — the engine auto-detects `HeadlessExperimental.beginFrame`
+# support and falls back to screenshot capture otherwise.
+#
+# Idempotent: safe to re-run.
+
+set -euo pipefail
+
+MIN_NODE_MAJOR=22
+MIN_HYPERFRAMES_VERSION="0.4.2"
+
+red()    { printf '\033[31m%s\033[0m\n' "$*"; }
+green()  { printf '\033[32m%s\033[0m\n' "$*"; }
+yellow() { printf '\033[33m%s\033[0m\n' "$*"; }
+bold()   { printf '\033[1m%s\033[0m\n' "$*"; }
+
+bold "==> HyperFrames setup"
+
+# --- 1. Node.js --------------------------------------------------------------
+
+if ! command -v node >/dev/null 2>&1; then
+  red "✗ Node.js is not installed."
+  echo "   Install Node.js >= ${MIN_NODE_MAJOR} (nvm, Homebrew, or your package manager) and re-run."
+  exit 1
+fi
+
+node_version="$(node --version | sed 's/^v//')"
+node_major="$(echo "$node_version" | cut -d. -f1)"
+if [ "$node_major" -lt "$MIN_NODE_MAJOR" ]; then
+  red "✗ Node.js ${node_version} is too old. HyperFrames requires Node.js >= ${MIN_NODE_MAJOR}."
+  echo "   Upgrade with 'nvm install ${MIN_NODE_MAJOR} && nvm use ${MIN_NODE_MAJOR}' or your package manager."
+  exit 1
+fi
+green "✓ Node.js ${node_version}"
+
+# --- 2. FFmpeg ---------------------------------------------------------------
+
+if ! command -v ffmpeg >/dev/null 2>&1; then
+  red "✗ FFmpeg is not installed."
+  case "$(uname -s)" in
+    Linux*)   echo "   sudo apt-get install -y ffmpeg   # Debian/Ubuntu"
+              echo "   sudo dnf install -y ffmpeg       # Fedora/RHEL";;
+    Darwin*)  echo "   brew install ffmpeg";;
+    MINGW*|MSYS*|CYGWIN*) echo "   winget install Gyan.FFmpeg";;
+    *)        echo "   See https://ffmpeg.org/download.html";;
+  esac
+  exit 1
+fi
+green "✓ FFmpeg $(ffmpeg -version 2>&1 | head -1 | awk '{print $3}')"
+
+# --- 3. npm ------------------------------------------------------------------
+
+if ! command -v npm >/dev/null 2>&1; then
+  red "✗ npm is not installed (should ship with Node.js)."
+  exit 1
+fi
+
+# --- 4. Install / upgrade hyperframes CLI -----------------------------------
+
+bold "==> Installing hyperframes CLI (>= ${MIN_HYPERFRAMES_VERSION})"
+
+current_hyperframes=""
+if command -v hyperframes >/dev/null 2>&1; then
+  current_hyperframes="$(hyperframes --version 2>/dev/null | tail -1 | sed 's/^v//')"
+fi
+
+if [ -n "$current_hyperframes" ]; then
+  yellow "   Found hyperframes ${current_hyperframes}"
+fi
+
+# Always install/upgrade to >= MIN version.
+# Using 'latest' so we pick up any newer auto-detect/capture fixes.
+if ! npm install -g "hyperframes@latest" >/dev/null 2>&1; then
+  red "✗ npm install -g hyperframes@latest failed."
+  echo "   Try: sudo npm install -g hyperframes@latest"
+  echo "   Or use a user-scoped npm prefix: npm config set prefix ~/.npm-global && export PATH=\"\$HOME/.npm-global/bin:\$PATH\""
+  exit 1
+fi
+
+installed_version="$(hyperframes --version 2>/dev/null | tail -1 | sed 's/^v//')"
+green "✓ hyperframes ${installed_version} installed globally"
+
+# Sanity-check minimum version.
+version_ge() {
+  # version_ge A B  →  true if A >= B
+  [ "$(printf '%s\n%s\n' "$1" "$2" | sort -V | head -1)" = "$2" ]
+}
+if ! version_ge "$installed_version" "$MIN_HYPERFRAMES_VERSION"; then
+  red "✗ hyperframes ${installed_version} is below required minimum ${MIN_HYPERFRAMES_VERSION}."
+  echo "   Try 'npm install -g hyperframes@latest' or 'sudo npm install -g hyperframes@latest'."
+  exit 1
+fi
+
+# --- 5. Pre-cache chrome-headless-shell --------------------------------------
+#
+# Chromium 147+ removed HeadlessExperimental.beginFrame. System Chrome (e.g.
+# /usr/bin/google-chrome) can't render with the fast path, so the engine
+# auto-detects and falls back to screenshot mode — but BeginFrame mode is
+# faster and produces higher-quality output. Install chrome-headless-shell
+# up front so the engine picks it over system Chrome.
+
+bold "==> Pre-caching chrome-headless-shell (for best render quality)"
+
+if ! npx --yes puppeteer browsers install chrome-headless-shell >/dev/null 2>&1; then
+  yellow "⚠ Could not pre-install chrome-headless-shell."
+  yellow "  Rendering will still work via screenshot-mode fallback (slower)."
+  yellow "  If you hit HeadlessExperimental.beginFrame errors:"
+  yellow "     export PRODUCER_FORCE_SCREENSHOT=true"
+  yellow "  See references/troubleshooting.md."
+else
+  green "✓ chrome-headless-shell installed"
+fi
+
+# --- 6. Doctor ---------------------------------------------------------------
+
+bold "==> Running hyperframes doctor"
+
+if hyperframes doctor; then
+  green "✓ HyperFrames is ready"
+  echo
+  echo "   Scaffold a project:   npx hyperframes init my-video"
+  echo "   Preview:              npx hyperframes preview"
+  echo "   Render:               npx hyperframes render"
+else
+  yellow "⚠ hyperframes doctor reported issues."
+  yellow "  See references/troubleshooting.md or re-run 'hyperframes doctor'."
+  exit 1
+fi

optional-skills/creative/kanban-video-orchestrator/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: kanban-video-orchestrator
+description: Plan, set up, and monitor a multi-agent video production pipeline backed by Hermes Kanban. Use when the user wants to make ANY video — narrative film, product/marketing, music video, explainer, ASCII/terminal art, abstract/generative loop, comic, 3D, real-time/installation — and the work warrants decomposition into specialized profiles (writer, designer, animator, renderer, voice, editor, etc.) coordinated through a kanban board. Performs adaptive discovery to scope the brief, designs an appropriate team for the requested style, generates the setup script that creates Hermes profiles + initial kanban task, then helps monitor execution and intervene when tasks stall or fail. Routes scenes to whichever Hermes rendering / audio / design skill fits each beat (`ascii-video`, `manim-video`, `p5js`, `comfyui`, `touchdesigner-mcp`, `blender-mcp`, `pixel-art`, `baoyu-comic`, `claude-design`, `excalidraw`, `songsee`, `heartmula`, …) plus external APIs for TTS, image-gen, and image-to-video as needed.
+version: 1.0.0
+author: [SHL0MS, alt-glitch]
+license: MIT
+metadata:
+  hermes:
+    tags: [video, kanban, multi-agent, orchestration, production-pipeline]
+    related_skills: [kanban-orchestrator, kanban-worker, ascii-video, manim-video, p5js, comfyui, touchdesigner-mcp, blender-mcp, pixel-art, ascii-art, songwriting-and-ai-music, heartmula, songsee, spotify, youtube-content, claude-design, excalidraw, architecture-diagram, concept-diagrams, baoyu-comic, baoyu-infographic, humanizer, gif-search, meme-generation]
+    credits: |
+      The single-project workspace layout, profile-config patching pattern,
+      SOUL.md-per-profile model, TEAM.md task-graph convention, and
+      `--workspace dir:<path>` discipline are adapted from alt-glitch's
+      original multi-agent video pipeline at
+      https://github.com/NousResearch/kanban-video-pipeline.
+---
+
+# Kanban Video Orchestrator
+
+Wrap any video request — from a 15-second product teaser to a 5-minute narrative
+short to a music video to an ASCII loop — in a Hermes Kanban pipeline that
+decomposes the work to specialized agent profiles.
+
+This skill does **not** render anything itself. It is a meta-pipeline that:
+
+1. **Scopes** the request through targeted discovery
+2. **Designs** an appropriate team (which roles, which tools per role) based on the style
+3. **Generates** a setup script that creates Hermes profiles, project workspace, and the initial kanban task
+4. **Hands off** to the director profile, which decomposes via the kanban
+5. **Monitors** execution, helps intervene when tasks stall or fail
+
+The actual rendering happens inside the kanban once it's running, via whichever
+existing skills + tools fit the scenes — `ascii-video`, `manim-video`, `p5js`,
+`comfyui`, `touchdesigner-mcp`, `blender-mcp`, `songwriting-and-ai-music`,
+`heartmula`, external APIs, or plain Python with PIL + ffmpeg.
+
+## When NOT to use this skill
+
+- The video is one continuous procedural project that needs no specialists. Just write the code directly.
+- The user wants a quick one-shot conversion (e.g. "convert this mp4 to a GIF") — use ffmpeg directly.
+- The output is a static image, GIF, or audio-only artifact — use the matching specific skill (`ascii-art`, `gifs`, `meme-generation`, `songwriting-and-ai-music`).
+- The work fits a single existing skill cleanly (e.g. a pure ASCII video — just use `ascii-video`).
+
+## Workflow
+
+```
+DISCOVER  →  BRIEF  →  TEAM DESIGN  →  SETUP  →  EXECUTE  →  MONITOR
+```
+
+### Step 1 — Discover (ask the right questions)
+
+The discovery process is **adaptive**: ask only what is actually needed. Always
+start with three questions to identify the broad shape:
+
+- **What is the video?** (one-sentence brief)
+- **How long?** (5-30s teaser / 30-90s short / 90s-3min explainer / 3-10min film / longer)
+- **What aspect ratio + target platform?** (1:1 / 9:16 / 16:9; X, IG, YouTube, internal, etc.)
+
+From the answer, classify the style category. The style determines which
+follow-up questions to ask. **Do not ask all questions at once.** Ask 2-4 at a
+time, listen, then proceed. Make reasonable assumptions whenever the user
+implies an answer.
+
+For complete intake patterns and per-style question banks, see
+**[references/intake.md](references/intake.md)**.
+
+### Step 2 — Brief
+
+Once enough is known, produce a structured `brief.md` using the template in
+`assets/brief.md.tmpl`. Stages:
+
+1. **Concept** — the one-sentence pitch + emotional north star
+2. **Scope** — duration, aspect, platform, deadline
+3. **Style** — visual references, brand constraints, tone
+4. **Scenes** — beat-by-beat breakdown (durations, content, target tool)
+5. **Audio** — narration / music / SFX / silent (per scene if needed)
+6. **Deliverables** — file format, resolution, optional alternates (vertical cut, GIF, etc.)
+
+Show the brief to the user for confirmation before designing the team. **The
+brief is the contract** — every downstream task references it.
+
+### Step 3 — Team design
+
+Pick role archetypes from the library that fit this video. **Compose, don't
+clone.** Most videos need 4-7 profiles. The director is always present; the
+rest are picked by what the brief actually requires.
+
+For the role library and per-style team compositions, see
+**[references/role-archetypes.md](references/role-archetypes.md)**.
+
+For mapping role → which Hermes skills + toolsets it loads, see
+**[references/tool-matrix.md](references/tool-matrix.md)**.
+
+### Step 4 — Setup
+
+Generate a setup script (`setup.sh`) and run it. The script:
+
+1. Creates the project workspace (`~/projects/video-pipeline/<slug>/`)
+2. Copies any provided assets into `taste/`, `audio/`, `assets/`
+3. Creates each Hermes profile via `hermes profile create --clone`
+4. Writes per-profile `SOUL.md` (personality + role definition)
+5. Configures profile YAML (toolsets, always_load skills, cwd)
+6. Writes `brief.md`, `TEAM.md`, and `taste/` content
+7. Fires the initial `hermes kanban create` task assigned to the director
+
+Use `scripts/bootstrap_pipeline.py` to generate setup.sh from a brief +
+team-design JSON. See **[references/kanban-setup.md](references/kanban-setup.md)**
+for the setup script structure, profile config patterns, and the critical
+"shared workspace" rule.
+
+### Step 5 — Execute
+
+Run `setup.sh`. Then provide the user with monitoring commands:
+
+```bash
+hermes kanban watch --tenant <project-tenant>     # live events
+hermes kanban list  --tenant <project-tenant>     # board snapshot
+hermes dashboard                                   # visual board UI
+```
+
+The director profile takes over from here, decomposing the work and routing
+tasks to specialist profiles via the kanban toolset.
+
+### Step 6 — Monitor and intervene
+
+Stay engaged — the kanban runs autonomously but a stuck task or bad output
+needs human (or AI) judgment.
+
+Monitoring patterns: poll `kanban list` periodically, inspect any RUNNING task
+that exceeds its expected duration with `kanban show <id>`, and check
+heartbeats. When a worker's output fails review, the standard interventions are:
+
+1. Comment on the worker's task with specific feedback (`kanban_comment`)
+2. Create a re-run task with the original as parent
+3. Adjust the brief's scope and let the director re-decompose
+
+For diagnostic patterns, intervention recipes, and the "task is stuck"
+playbook, see **[references/monitoring.md](references/monitoring.md)**.
+
+## Reference: worked examples
+
+Six concrete pipelines covering very different video styles — narrative film,
+product/marketing, music video, math/algorithm explainer, ASCII video, real-time
+installation — showing how the same workflow yields very different teams and
+task graphs. See **[references/examples.md](references/examples.md)**.
+
+## Critical rules
+
+1. **Discovery before action.** Never start generating a brief or team without
+   asking at least the three baseline questions. A bad brief cascades through
+   the entire pipeline.
+
+2. **Match the team to the video.** Don't reuse the same 4-profile setup for
+   every job. A music video that doesn't have a beat-analysis profile will
+   misfire. A narrative film that doesn't have a writer profile will produce
+   incoherent scenes. See `references/role-archetypes.md`.
+
+3. **One workspace per project.** All profiles for a given video share the same
+   `dir:` workspace. Tasks pass artifacts via shared filesystem and structured
+   handoffs. **Every** `kanban_create` call passes
+   `workspace_kind="dir"` + `workspace_path="<absolute project path>"`.
+
+4. **Tenant every project.** Use a project-specific tenant
+   (`--tenant <project-slug>`). Keeps the dashboard scoped and prevents
+   cross-pollination with other ongoing kanbans.
+
+5. **Respect existing skills.** When a scene fits an existing skill, the
+   relevant renderer should load that skill via `--skill <name>` on its task
+   or `always_load` in its profile. Do not re-derive what a skill already
+   provides.
+
+6. **The director never executes.** Even with the full `kanban + terminal +
+   file` toolset, the director's `SOUL.md` rules forbid it from executing
+   work itself. It decomposes and routes only — every concrete task becomes
+   a `hermes kanban create` call to a specialist profile. The
+   `kanban-orchestrator` skill spells this out further.
+
+7. **Don't over-decompose.** A 30-second product video does NOT need 20 tasks.
+   Aim for the smallest task graph that still parallelizes well and exposes the
+   right human-review gates.
+
+8. **Verify API keys BEFORE firing.** External APIs (TTS, image-gen,
+   image-to-video) need keys in `~/.hermes/.env` or the user's secret store.
+   A worker that hits a missing-key error wastes a task slot. The setup
+   script's `check_key` helper aborts cleanly if a required key is missing.
+
+## File map
+
+```
+SKILL.md                            ← this file (workflow + rules)
+references/
+  intake.md                         ← discovery question banks per style
+  role-archetypes.md                ← role library (writer, designer, animator, …)
+  tool-matrix.md                    ← skill + toolset mapping per role
+  kanban-setup.md                   ← setup script structure & profile config
+  monitoring.md                     ← watch + intervene patterns
+  examples.md                       ← six worked pipelines
+assets/
+  brief.md.tmpl                     ← brief skeleton
+  setup.sh.tmpl                     ← setup script skeleton
+  soul.md.tmpl                      ← profile personality skeleton
+scripts/
+  bootstrap_pipeline.py             ← generate setup.sh from brief + team JSON
+  monitor.py                        ← polling + intervention helpers
+```

optional-skills/creative/kanban-video-orchestrator/assets/brief.md.tmpl

@@ -0,0 +1,79 @@
+# Video Brief — {{TITLE}}
+
+> Slug: `{{SLUG}}` · Tenant: `{{TENANT}}` · Project workspace: `{{WORKSPACE}}`
+
+## 1. Concept
+
+**One-line pitch.** {{ONE_LINE_PITCH}}
+
+**Emotional north star.** {{EMOTIONAL_NORTH_STAR}}
+*(What should the viewer feel walking away?)*
+
+## 2. Scope
+
+| | |
+|---|---|
+| Duration | {{DURATION_S}} seconds |
+| Aspect ratio | {{ASPECT}} |
+| Resolution | {{RESOLUTION}} |
+| Frame rate | {{FPS}} fps |
+| Target platforms | {{PLATFORMS}} |
+| Deadline | {{DEADLINE}} |
+| Quality bar | {{QUALITY_BAR}} *(rough draft / polished / archival)* |
+
+## 3. Style
+
+**Visual references.** {{VISUAL_REFS}}
+
+**Tone.** {{TONE}}
+
+**Brand constraints.** {{BRAND_CONSTRAINTS}}
+*(colors, typography, motion language; or "n/a")*
+
+**Aesthetic rules.**
+{{AESTHETIC_RULES}}
+
+## 4. Scenes
+
+Beat-by-beat breakdown. Each scene gets a row.
+
+| # | Time | Content | Target tool / skill | Audio | Notes |
+|---|------|---------|---------------------|-------|-------|
+| 1 | 0:00–0:0X | {{SCENE_1_CONTENT}} | {{SCENE_1_TOOL}} | {{SCENE_1_AUDIO}} | {{SCENE_1_NOTES}} |
+| 2 | 0:0X–0:0Y | ... | ... | ... | ... |
+
+## 5. Audio
+
+**Approach.** {{AUDIO_APPROACH}}
+*(narration / music-only / synced to track / silent / mixed)*
+
+**Voiceover.** {{VO_DETAILS}}
+*(provider, voice, language, script source — "n/a" if no VO)*
+
+**Music.** {{MUSIC_DETAILS}}
+*(provided track path / commission via Suno / commission via heartmula /
+license-free / "n/a")*
+
+**SFX.** {{SFX_DETAILS}}
+*(generated, library, or "n/a")*
+
+## 6. Deliverables
+
+| Format | Resolution | Notes |
+|--------|-----------|-------|
+| {{PRIMARY_FORMAT}} | {{PRIMARY_RES}} | The main output |
+| {{ALT_FORMAT_1}} | {{ALT_RES_1}} | {{ALT_NOTES_1}} |
+
+**Final filename.** `output/final.mp4`
+*(plus optional `output/final-9x16.mp4`, `output/captions.srt`, etc.)*
+
+## 7. Constraints
+
+- API keys required: {{API_KEYS_REQUIRED}}
+- External dependencies: {{EXT_DEPS}}
+- Source assets to incorporate: {{SOURCE_ASSETS}}
+
+---
+
+**This brief is the contract. The director and every downstream profile read
+it. If the brief changes, the kanban must be re-fired — don't edit live.**

optional-skills/creative/kanban-video-orchestrator/assets/setup.sh.tmpl

@@ -0,0 +1,185 @@
+#!/usr/bin/env bash
+# ═══════════════════════════════════════════════════════════════════════
+# Video Pipeline Setup — {{TITLE}}
+#
+# Generated by kanban-video-orchestrator skill.
+#
+# Slug:      {{SLUG}}
+# Workspace: {{WORKSPACE}}
+# Tenant:    {{TENANT}}
+# ═══════════════════════════════════════════════════════════════════════
+set -euo pipefail
+
+PROJECT_SLUG="{{SLUG}}"
+WORKSPACE="$HOME/projects/video-pipeline/${PROJECT_SLUG}"
+TENANT="{{TENANT}}"
+
+# ─────────────────────────────────────────────────────────────────────
+# 1. Verify required API keys
+# ─────────────────────────────────────────────────────────────────────
+echo "═══ Checking required API keys ═══"
+
+check_key() {
+    local var="$1"
+    local kc_account="${2:-hermes}"
+    local kc_service="${3:-$1}"
+    if grep -q "^${var}=" "$HOME/.hermes/.env" 2>/dev/null && \
+       [ -n "$(grep "^${var}=" "$HOME/.hermes/.env" | cut -d= -f2-)" ]; then
+        echo "  ✓ ${var} (env)"
+        return 0
+    fi
+    if command -v security >/dev/null 2>&1 && \
+       security find-generic-password -a "${kc_account}" -s "${kc_service}" -w >/dev/null 2>&1; then
+        echo "  ✓ ${var} (Keychain ${kc_account}/${kc_service})"
+        return 0
+    fi
+    echo "  ✗ ${var} not set in ~/.hermes/.env or Keychain (${kc_account}/${kc_service})"
+    return 1
+}
+
+# Customize this list per project — only check keys actually used:
+{{KEY_CHECKS}}
+
+# ─────────────────────────────────────────────────────────────────────
+# 2. Create project workspace
+# ─────────────────────────────────────────────────────────────────────
+echo "═══ Creating project workspace ═══"
+mkdir -p "$WORKSPACE"/{taste,audio/{voiceover,sfx},assets,scenes,checkpoints,tools,output}
+{{SCENE_DIRS}}
+echo "  ✓ $WORKSPACE"
+
+# ─────────────────────────────────────────────────────────────────────
+# 3. Create Hermes profiles
+# ─────────────────────────────────────────────────────────────────────
+echo "═══ Creating Hermes profiles ═══"
+
+{{PROFILE_CREATE_COMMANDS}}
+
+# ─────────────────────────────────────────────────────────────────────
+# 4. Configure profiles (toolsets, skills, cwd)
+# ─────────────────────────────────────────────────────────────────────
+echo "═══ Configuring profiles ═══"
+
+configure_profile() {
+    local profile="$1"
+    local toolsets_json="$2"     # JSON array string, e.g. '["kanban","terminal","file"]'
+    local skills_json="$3"       # JSON array string, e.g. '["kanban-worker","ascii-video"]'
+    python3 - "$profile" "$toolsets_json" "$skills_json" "$WORKSPACE" <<'PY'
+"""Patch a Hermes profile config.yaml using PyYAML so we don't depend on the
+exact default-config string format. Validates the patch took effect and exits
+non-zero if anything's off."""
+import json
+import os
+import sys
+
+try:
+    import yaml
+except ImportError:
+    print("ERROR: PyYAML required. pip install pyyaml", file=sys.stderr)
+    sys.exit(1)
+
+profile, toolsets_json, skills_json, workspace = sys.argv[1:5]
+toolsets = json.loads(toolsets_json)
+skills = json.loads(skills_json)
+
+p = os.path.expanduser(f"~/.hermes/profiles/{profile}/config.yaml")
+if not os.path.exists(p):
+    print(f"  ✗ profile config not found: {p}", file=sys.stderr)
+    sys.exit(1)
+
+with open(p) as f:
+    cfg = yaml.safe_load(f) or {}
+
+# Apply our changes — only the keys we actually want to set.
+cfg["toolsets"] = toolsets
+cfg.setdefault("skills", {})
+cfg["skills"]["always_load"] = skills
+
+# Note: we do NOT touch cfg["approvals"] — that's a security-sensitive
+# setting (manual confirmation of tool calls). Workspace cwd is overridden
+# per-task by `--workspace dir:<path>` on `hermes kanban create`, so we
+# don't need to mutate cfg["terminal"]["cwd"] either.
+
+with open(p, "w") as f:
+    yaml.safe_dump(cfg, f, sort_keys=False)
+
+# Validate
+with open(p) as f:
+    after = yaml.safe_load(f)
+errors = []
+if after.get("toolsets") != toolsets:
+    errors.append(f"toolsets mismatch: {after.get('toolsets')!r}")
+if after.get("skills", {}).get("always_load") != skills:
+    errors.append(f"skills.always_load mismatch: {after.get('skills', {}).get('always_load')!r}")
+if errors:
+    print(f"  ✗ {profile}: " + "; ".join(errors), file=sys.stderr)
+    sys.exit(1)
+PY
+    if [ $? -ne 0 ]; then
+        echo "  ✗ failed to configure ${profile}" >&2
+        exit 1
+    fi
+    echo "  ✓ ${profile}"
+}
+
+{{PROFILE_CONFIG_COMMANDS}}
+
+# ─────────────────────────────────────────────────────────────────────
+# 5. Write SOUL.md per profile
+# ─────────────────────────────────────────────────────────────────────
+echo "═══ Writing profile personalities ═══"
+
+{{SOUL_WRITES}}
+
+# ─────────────────────────────────────────────────────────────────────
+# 6. Copy brief, TEAM.md, and any provided assets
+# ─────────────────────────────────────────────────────────────────────
+echo "═══ Writing brief + taste ═══"
+
+cat > "$WORKSPACE/brief.md" <<'BRIEF_EOF'
+{{BRIEF_CONTENTS}}
+BRIEF_EOF
+
+cat > "$WORKSPACE/TEAM.md" <<'TEAM_EOF'
+{{TEAM_CONTENTS}}
+TEAM_EOF
+
+{{TASTE_WRITES}}
+
+{{ASSET_COPIES}}
+
+# ─────────────────────────────────────────────────────────────────────
+# 7. Fire the initial kanban task
+# ─────────────────────────────────────────────────────────────────────
+echo "═══ Firing initial kanban task ═══"
+
+hermes kanban create "Direct production of {{TITLE}}" \
+    --assignee director \
+    --workspace dir:"$WORKSPACE" \
+    --tenant "$TENANT" \
+    --priority 2 \
+    --max-runtime 4h \
+    --body "$(cat <<EOF
+Read brief.md, TEAM.md, and taste/.
+
+Decompose into the team graph defined in TEAM.md.
+
+All child tasks MUST use:
+  workspace_kind="dir"
+  workspace_path="$WORKSPACE"
+  tenant="$TENANT"
+
+Do not execute the work yourself — route every concrete subtask to the
+appropriate profile via kanban_create.
+EOF
+)"
+
+echo ""
+echo "═══ Setup complete ═══"
+echo ""
+echo "Monitor with:"
+echo "  hermes kanban watch --tenant $TENANT"
+echo "  hermes kanban list  --tenant $TENANT"
+echo "  hermes dashboard"
+echo ""
+echo "Workspace: $WORKSPACE"

optional-skills/creative/kanban-video-orchestrator/assets/soul.md.tmpl

@@ -0,0 +1,38 @@
+# {{ROLE_NAME}}
+
+You are the **{{ROLE_NAME}}** for this video production.
+
+## Project context
+
+- **Brief:** read `brief.md` in your CWD
+- **Team graph:** read `TEAM.md` in your CWD
+- **Style spec:** read `taste/brand-guide.md` and `taste/emotional-dna.md` in
+  your CWD
+
+## What you do
+
+{{ROLE_RESPONSIBILITIES}}
+
+## Inputs you read
+
+{{INPUTS_READ}}
+
+## Outputs you produce
+
+{{OUTPUTS_PRODUCED}}
+
+## Tools and skills available
+
+- **Toolsets:** {{TOOLSETS}}
+- **Skills loaded:** {{SKILLS}}
+- **External APIs / CLIs:** {{EXTERNAL_TOOLS}}
+
+## Rules
+
+{{ROLE_RULES}}
+
+{{COMMON_RULES}}
+
+## Common reference commands
+
+{{COMMON_COMMANDS}}

optional-skills/creative/kanban-video-orchestrator/references/examples.md

@@ -0,0 +1,227 @@
+# Worked Examples
+
+Six concrete pipelines covering different video styles. Each shows the team
+composition, task graph, and skill/tool choices the orchestrator would make
+for that brief. **These are illustrative, not templates** — adapt to the
+actual brief.
+
+## Example 1 — Narrative short film (text-to-image → image-to-video → cut)
+
+**Brief:** A 90-second noir-style short. A detective walks through a rainy
+city. Voiceover narration. AI-generated visuals.
+
+**Team:**
+- `director` — vision, decomposition, approval
+- `writer` — script + voiceover copy (loads `humanizer` for natural voice)
+- `storyboarder` — beat-by-beat shot list (loads `excalidraw`)
+- `image-generator` — generates each shot's still via local ComfyUI workflows
+  (loads `comfyui`)
+- `image-to-video-generator` — animates each still (Runway/Kling, OR
+  ComfyUI's AnimateDiff/WAN workflows via `comfyui`)
+- `voice-talent` — narration via ElevenLabs
+- `audio-mixer` — VO + ambient pad
+- `editor` — assembly + transitions
+- `reviewer` — final QA
+
+**Task graph:**
+```
+T0  director         decompose
+T1  writer           script + voiceover.md                    (parent: T0)
+T2  storyboarder     shot list with framing per beat          (parent: T1)
+T3  image-generator  one still per shot (~12 shots)           (parent: T2)
+T4  image-to-video   animate each still                       (parent: T3)
+T5  voice-talent     generate narration audio                 (parent: T1)
+T6  audio-mixer      mix VO + ambient                         (parent: T5)
+T7  editor           cut + transitions + audio mux            (parents: T4, T6)
+T8  reviewer         final QA                                 (parent: T7)
+```
+
+**Key choices:**
+- Local ComfyUI via `comfyui` skill is preferred over external API for
+  cost/control — but external APIs are fine if ComfyUI isn't installed
+- `editor` profile is ffmpeg-only, no Hermes skill required beyond
+  `kanban-worker`
+- Storyboarder produces `storyboard.excalidraw` alongside the markdown
+
+## Example 2 — Product / marketing teaser
+
+**Brief:** A 30-second product teaser for a developer tool. Shows code +
+terminal + UI screen recordings, voiceover, CTA at end. Square 1:1.
+
+**Team:**
+- `director`
+- `copywriter` — taglines, voiceover script, CTA (loads `humanizer`)
+- `concept-artist` — style frames (loads `claude-design` for UI mockups)
+- `renderer-motion-graphics` — animated UI sequences (Remotion CLI)
+- `renderer-ascii` — terminal-style demo scenes (loads `ascii-video`)
+- `voice-talent` — VO via ElevenLabs
+- `editor` — assembly + brand-color treatment
+- `audio-mixer` — VO + light music bed
+- `captioner` — burned subtitles for muted-autoplay platforms
+- `masterer` — produces 1:1 + 9:16 + 16:9 variants
+
+**Task graph:**
+```
+T0  director              decompose
+T1  copywriter            copy.md + cta + vo script               (parent: T0)
+T2  concept-artist        visual-spec.md + style frames           (parent: T1)
+T3a renderer-motion-graphics  scene 1: UI sequence                (parent: T2)
+T3b renderer-ascii        scene 2: terminal demo                  (parent: T2)
+T3c renderer-motion-graphics  scene 3: feature highlight          (parent: T2)
+T3d renderer-motion-graphics  scene 4: CTA card                   (parent: T2)
+T4  voice-talent          narration                                (parent: T1)
+T5  audio-mixer           VO + music bed                          (parent: T4)
+T6  editor                cut + transitions                        (parents: T3*, T5)
+T7  captioner             SRT + burned subtitles                  (parent: T6)
+T8  masterer              1:1, 9:16, 16:9 variants                (parent: T7)
+```
+
+**Key choices:**
+- Multiple specialized renderers (motion-graphics + ASCII) coexist
+- Captioner is included because muted autoplay is the norm on social
+- `claude-design` skill for UI mockups maps directly to the product video idiom
+
+## Example 3 — Music video (synced to provided track)
+
+**Brief:** A 3-minute music video for a provided lo-fi hip-hop track. Visuals
+should pulse with the beat. Generative + ASCII hybrid. Vertical 9:16.
+
+**Team:**
+- `director`
+- `music-supervisor` — analyze track, emit `audio/beats.json` (loads `songsee`)
+- `storyboarder` — beat-aligned shot list (loads `excalidraw`)
+- `renderer-ascii` — ASCII scenes synced to bass kicks (loads `ascii-video`)
+- `renderer-p5js` — generative particle scenes synced to highs (loads `p5js`)
+- `editor` — beat-cut assembly using `beats.json`
+- `reviewer` — sync QA
+
+**Task graph:**
+```
+T0  director              decompose
+T1  music-supervisor      analyze track → beats.json + spectrogram  (parent: T0)
+T2  storyboarder          shot list aligned to beats                (parents: T1, T0)
+T3a renderer-ascii        scene 1: bass-driven ASCII                (parent: T2)
+T3b renderer-p5js         scene 2: high-end particle field          (parent: T2)
+... (more scenes)
+T4  editor                cut to beats + mux track                  (parents: T3*, T1)
+T5  reviewer              sync QA + final approval                  (parent: T4)
+```
+
+**Key choices:**
+- `music-supervisor` runs FIRST — `beats.json` gates the renderers
+- `editor` uses `beats.json` directly to align cuts to bass kicks
+- No voice-talent — music is the audio
+- Two specialized renderers (`ascii-video` + `p5js`) for visual variety
+
+## Example 4 — Math/algorithm explainer
+
+**Brief:** A 2-minute explainer of an algorithm. 3Blue1Brown-style. Animated
+diagrams, equations, narration. Square 1:1.
+
+**Team:**
+- `director`
+- `writer` — narration script (loads `humanizer`)
+- `cinematographer` — visual spec (loads `manim-video`)
+- `renderer-manim` — all animated scenes (loads `manim-video`)
+- `voice-talent` — narration via ElevenLabs
+- `editor` — assembly + audio mux
+- `captioner` — burned subtitles
+
+**Task graph:**
+```
+T0  director           decompose
+T1  writer             script + narration                  (parent: T0)
+T2  cinematographer    visual spec for all scenes           (parent: T1)
+T3a-Tn renderer-manim  scenes 1..N                          (parents: T2)
+T4  voice-talent       narration audio                      (parent: T1)
+T5  editor             cut + mux                            (parents: T3*, T4)
+T6  captioner          SRT + burn                           (parent: T5)
+```
+
+**Key choices:**
+- `manim-video` skill drives both the cinematographer (visual language) and
+  the renderer (actual scene production)
+- The `manim-video` skill's reference docs (animation-design-thinking,
+  scene-planning, equations) auto-load when needed via the renderer's pinned skill
+
+## Example 5 — ASCII video, music-track-only
+
+**Brief:** A 60-second pure-ASCII video reactive to an existing track. No
+voiceover, no other tools. Square 1:1.
+
+**Team:**
+- `director`
+- `music-supervisor` — track analysis (loads `songsee`)
+- `renderer-ascii` — all visuals (loads `ascii-video`)
+- `editor` — assembly + audio mux
+
+**Task graph:**
+```
+T0  director           decompose
+T1  music-supervisor   analyze track                       (parent: T0)
+T2a renderer-ascii     scene 1                             (parents: T1, T0)
+T2b renderer-ascii     scene 2                             (parents: T1, T0)
+T2c renderer-ascii     scene 3                             (parents: T1, T0)
+T3  editor             stitch + mux audio                  (parents: T2*)
+```
+
+**Key choices:**
+- Minimal team (4 profiles) for a focused single-tool project
+- No reviewer — short experimental piece, director approves directly
+- All scenes run through one `renderer-ascii` profile because the `ascii-video`
+  skill covers everything
+
+This example illustrates the rule: **don't over-decompose**. Three scenes
+through one renderer is fine. Don't spawn three renderer profiles.
+
+## Example 6 — Real-time / installation art
+
+**Brief:** A 2-minute audio-reactive visual for a gallery installation. Driven
+by an audio input feed. TouchDesigner-based. 16:9 4K.
+
+**Team:**
+- `director`
+- `cinematographer` — visual language spec (loads `touchdesigner-mcp`)
+- `renderer-touchdesigner` — all visuals + record-to-disk
+  (loads `touchdesigner-mcp`)
+- `audio-mixer` — final loudness pass on the captured audio (optional if
+  pre-mixed source)
+- `editor` — assemble final clip from TouchDesigner recording
+- `reviewer` — visual QA
+
+**Task graph:**
+```
+T0  director                decompose
+T1  cinematographer         TD operator graph spec           (parent: T0)
+T2  renderer-touchdesigner  build TD network + record output (parent: T1)
+T3  editor                  trim + audio mux                 (parent: T2)
+T4  reviewer                final QA                         (parent: T3)
+```
+
+**Key choices:**
+- `touchdesigner-mcp` controls a running TouchDesigner instance — the
+  cinematographer designs the operator graph, renderer builds it
+- Output is a recording from the running TD network, not a render-to-frames
+  process; editor mostly just trims
+
+## Pattern recognition
+
+When the user describes a video, look for these signals to map to an example:
+
+- **Plot, characters, scripted dialogue** → Example 1 (narrative)
+- **Specific product, CTA, brand colors, voiceover** → Example 2 (marketing)
+- **Track file provided, "synced to music"** → Example 3 (music video)
+- **"Explain how X works", math/algorithm/concept walkthrough** → Example 4 (manim explainer)
+- **Terminal aesthetic, ASCII, retro pixel** → Example 5 (ASCII)
+- **"Audio-reactive", "real-time", "installation"** → Example 6 (TouchDesigner)
+- **Comic-style narrative** → use `renderer-comic` (`baoyu-comic` skill)
+- **Retro game / pixel-art aesthetic** → use `renderer-pixel` (`pixel-art` skill)
+- **3D scene, photoreal environment** → use `renderer-3d` (`blender-mcp`)
+- **Generative art, particle system, shader** → use `renderer-p5js` (`p5js`)
+- **AI-generated photoreal stills + animation** → use `renderer-comfyui`
+  (`comfyui`) for both stills and image-to-video
+- **"video about how the system works", recursive demo** → composable from
+  any of the above; the recursion is a rendering technique, not a style
+
+The actual team should be derived from the specific brief — these examples are
+starting points, not endpoints.

optional-skills/creative/kanban-video-orchestrator/references/intake.md

@@ -0,0 +1,166 @@
+# Intake — Discovery Question Banks
+
+The discovery process is **adaptive**. Always start with three baseline
+questions to identify the broad style category, then drill into a per-style
+question bank. Ask 2-4 questions at a time, listen, then proceed. Make
+reasonable assumptions whenever the user implies an answer.
+
+## Tier 0 — Baseline (always ask)
+
+1. **What is the video?** — One-sentence pitch
+2. **How long?** — Approximate duration
+3. **Aspect ratio + target platform?** — 16:9 / 9:16 / 1:1 / 4:5; X, IG, YouTube, internal, etc.
+
+From these answers, classify the style category and pick the relevant Tier 1
+follow-ups. **Do not** continue asking until you have at least these three.
+
+## Style classification
+
+Map the brief to one of these archetypes (or a hybrid):
+
+| Archetype | Tells |
+|-----------|-------|
+| **Narrative film** | Plot, characters, scenes-with-events, dialogue, location |
+| **Product / marketing** | A specific product or feature being shown / sold; CTA at end |
+| **Music video** | A specific track exists; visuals sync to music |
+| **Explainer / educational** | A concept being taught; voiceover-driven |
+| **Tutorial / changelog** | Software demo, terminal-heavy, technical |
+| **ASCII / terminal art** | Retro terminal aesthetic explicit, character-grid |
+| **Abstract / loop** | Generative, no plot, often perfect-loop |
+| **Documentary / interview cut** | Real footage, transcription-driven |
+| **Real-time / installation** | Audio-reactive, gallery installation, VJ output |
+
+If ambiguous, **ask** which category fits — don't guess. Hybrids are common
+(e.g., a product video with a narrative arc); decompose into the dominant
+mode + secondary modifiers.
+
+**Recursive / meta** ("a video that shows its own production") is a
+*rendering technique*, not a separate style — compose it from any of the
+above by adding a two-pass render step where pass 2 uses pass 1's output as
+texture inside the final scene.
+
+## Tier 1 — Per-style follow-ups
+
+### Narrative film
+
+- **Setting / world?** — When and where the story takes place
+- **Characters?** — How many, archetypes, who carries dialogue
+- **Beat list or full script?** — Has the user written the story or do we draft it
+- **Dialogue language?** — Spoken lines, on-screen subs only, silent
+- **Visual generation approach?** — Text-to-image (FAL/Midjourney/Imagen) →
+  image-to-video (Runway/Kling), 3D animation (Blender), 2D animation,
+  procedural, or hybrid
+- **Voice approach?** — TTS (which voice), recorded VO, no dialogue
+- **Music / score?** — Commissioned (via `songwriting-and-ai-music` Suno
+  prompts, or local `heartmula`), licensed track provided, silent
+
+### Product / marketing
+
+- **Product?** — Name, what it does, key feature being shown
+- **Target audience?** — Who's watching, what they care about
+- **CTA?** — Visit URL, install, sign up, etc.
+- **Tone?** — Serious, playful, technical, premium, edgy
+- **Brand assets available?** — Logo files, color palette, fonts, existing footage
+- **Animation style?** — Motion graphics (Remotion / AE-style), screen recording,
+  generative, illustrated
+- **Voiceover?** — Yes (which voice / language) or text-only
+- **Music?** — Track provided, license-free needed, custom-composed
+
+### Music video
+
+- **Track file?** — Path to the audio (essential — we'll analyze BPM + beats)
+- **Track length to use?** — Full song or a section
+- **Genre / energy?** — Tells what visual rhythm and density to use
+- **Lyric / narrative content?** — Are there lyrics to render on screen,
+  or is it purely visual?
+- **Visual reference style?** — Existing music videos / artists for reference
+- **Performer footage?** — None, has clips, will provide
+- **Visual generation approach?** — Per-beat generative, edit-driven cuts of stock
+  footage, illustrated, hybrid
+
+### Explainer / educational
+
+- **What concept is being taught?** — One-sentence concept, key takeaway
+- **Audience expertise?** — Beginner / intermediate / expert
+- **Diagram density?** — Heavy math / formulas / code / abstract concepts
+- **Voiceover?** — TTS / recorded / on-screen text only
+- **Tool preference?** — `manim-video` (math), `p5js` (generative),
+  Remotion (UI motion graphics), `comfyui` (AI-generated visuals),
+  `ascii-video` (technical/retro), hybrid
+- **Pacing?** — Fast and dense (3Blue1Brown) or slow and contemplative
+
+### Tutorial / changelog / software demo
+
+- **Software being demonstrated?** — Name, what it does
+- **Demo script?** — Sequence of commands / screens to show
+- **Terminal-only or with GUI?**
+- **Voiceover for narration?**
+- **Diagram support needed?** — Often these benefit from a diagram skill
+  alongside the screen-capture/render step (`excalidraw`,
+  `architecture-diagram`, `concept-diagrams`)
+
+### ASCII / terminal art
+
+- **Source material?** — Generative / driven by audio / converting existing
+  video / static image starting point
+- **Color palette?** — Brand-driven (gold/black/blue), Matrix green, full
+  rainbow, monochrome
+- **Audio reactivity?** — None / loose mood / tight beat sync / FFT-driven
+- **Character set?** — ASCII only / Unicode block-drawing / mystic glyphs
+- **Loop or narrative?** — Perfect loop or one-shot
+
+### Abstract / loop
+
+- **Mood / emotion?** — One word that captures the feel
+- **Motion type?** — Zoom-into-itself, particle drift, wave, geometric, organic
+- **Loop required?** — Perfect loop (Droste-style) or just satisfying ending
+- **Audio?** — Silent, ambient pad, beat-synced
+
+### Documentary / interview cut
+
+- **Source footage?** — Provided clips, length per clip
+- **Transcript / subtitles?** — Provided or to be generated
+- **Story structure?** — Chronological / thematic / arc
+- **B-roll approach?** — Generated, stock library, none
+
+### Real-time / installation
+
+- **Output environment?** — Gallery wall, projector, screen, web embed
+- **Audio source?** — Live audio input, pre-recorded track, both
+- **Reactivity tightness?** — Mood-level (loose) vs. tight beat-sync vs. live
+  parameter control
+- **Tool preference?** — `touchdesigner-mcp` for full TD operator graphs;
+  `p5js` for web-canvas; `comfyui` for generative-AI fed by audio features
+
+## Tier 2 — Always ask near the end
+
+- **Brand assets path?** — Where logo / color palette / fonts / music library lives
+- **Output format requirements?** — Codec preference, target file size, accepted
+  alternates (vertical cut, GIF, audio-only)
+- **Deadline?** — Affects task `max_runtime_seconds` and acceptable scope
+- **Quality bar?** — Rough draft for review / polished final / archival
+- **Existing footage / assets to reuse?** — Anything that should appear, not just inform
+
+## Reasonable assumption defaults
+
+When the user under-specifies, fill in these defaults rather than asking:
+
+| Question | Default |
+|----------|---------|
+| Frame rate | 30 fps for X / IG; 60 fps for tutorials/explainers; 24 fps for narrative film |
+| Resolution | 1080×1080 for square, 1920×1080 for 16:9, 1080×1920 for 9:16 |
+| Codec | H.264 / yuv420p, CRF 18 |
+| Audio codec | AAC 192 kbps |
+| Voice | Provider's mid-range neutral voice unless brand calls for distinctive timbre |
+| Music | Silent (require user to specify if music is wanted) |
+| Captions | On for explainer/tutorial; off for narrative/abstract unless requested |
+| Quality bar | Polished final unless user says draft |
+
+State the assumption explicitly: *"Assuming 30fps and AAC audio unless you say otherwise — proceed?"*
+
+## Anti-patterns
+
+- **Asking 10 questions at once.** Maximum 4 per turn.
+- **Asking for things the brief already implies.** If the user said "music video for my track," do not ask "is there a track?"
+- **Failing to classify before drilling in.** Tier-1 questions depend on classification; mixing them up wastes turns.
+- **Treating "make a video" as enough to proceed.** Always confirm the three baseline questions.

optional-skills/creative/kanban-video-orchestrator/references/kanban-setup.md

@@ -0,0 +1,276 @@
+# Kanban Setup — Project Bootstrap & Profile Configuration
+
+Once the brief is locked and the team is designed, the next step is producing
+the actual `setup.sh` that creates the project workspace, configures Hermes
+profiles, and fires the initial kanban task.
+
+This file documents the patterns. The companion script
+`scripts/bootstrap_pipeline.py` automates most of it from a structured input
+JSON.
+
+> **Credit:** the single-project-workspace layout, profile-config patching
+> approach, SOUL.md-per-profile convention, and `--workspace dir:<path>` rule
+> are adapted from alt-glitch's original multi-agent video pipeline:
+> [NousResearch/kanban-video-pipeline](https://github.com/NousResearch/kanban-video-pipeline).
+> This skill generalizes those patterns across video styles and replaces the
+> string-replacement config patcher with a PyYAML-based one.
+
+## Project workspace structure
+
+Every video project gets one workspace under `~/projects/video-pipeline/<slug>/`:
+
+```
+~/projects/video-pipeline/<slug>/
+├── brief.md                       ← the contract; all tasks reference
+├── TEAM.md                        ← team composition + task graph (director reads this)
+├── taste/
+│   ├── brand-guide.md             ← color, typography, motion rules
+│   ├── emotional-dna.md           ← what the piece should FEEL like
+│   └── style-frames/              ← optional: visual references
+├── audio/
+│   ├── track.mp3                  ← provided music (if any)
+│   ├── voiceover/                 ← per-line TTS clips
+│   └── sfx/                       ← sound effects
+├── assets/
+│   ├── logos/
+│   ├── fonts/
+│   └── existing-footage/          ← reusable provided clips
+├── scenes/
+│   ├── scene-01/
+│   │   ├── VISUAL_SPEC.md         ← cinematographer's per-scene spec
+│   │   ├── render.py              ← renderer's code (or sketch.html, etc.)
+│   │   ├── checkpoints/           ← preview frames for QA
+│   │   └── clip.mp4               ← the deliverable for this scene
+│   ├── scene-02/...
+│   └── ...
+├── checkpoints/                   ← global review frames
+├── tools/                         ← optional project-local helpers
+└── output/
+    ├── final.mp4                  ← stitched + audio
+    ├── final-noaudio.mp4
+    ├── final-9x16.mp4             ← optional: vertical alternate
+    └── captions.srt               ← optional: subtitle file
+```
+
+**The slug** is derived from the brief title: lowercase, hyphen-separated.
+Example: `q3-product-teaser`, `ascii-mood-loop`, `interview-cut-2026-q1`.
+
+## The setup.sh script
+
+The setup script does six things in order:
+
+1. **Create workspace tree** — all directories above
+2. **Create profiles** — `hermes profile create <name> --clone`
+3. **Configure profiles** — patch each profile's
+   `~/.hermes/profiles/<name>/config.yaml` to set toolsets, always_load skills,
+   and `cwd`
+4. **Write SOUL.md per profile** — the personality + role definition
+5. **Copy any provided assets + write `brief.md`, `TEAM.md`, and `taste/`**
+6. **Fire the initial kanban task** — `hermes kanban create` assigned to the director
+
+See `assets/setup.sh.tmpl` for the skeleton.
+
+### Profile creation pattern
+
+```bash
+hermes profile create director --clone 2>/dev/null || true
+```
+
+The `--clone` flag clones from the active profile (preserving model, base
+config). The `|| true` makes the script idempotent — re-running won't error if
+the profile already exists.
+
+### Profile config patching
+
+Each profile has a YAML config at `~/.hermes/profiles/<name>/config.yaml`. The
+setup script edits exactly two keys:
+
+1. `toolsets:` — replace the default with the role's required toolsets
+2. `skills.always_load:` — list the role's must-load skills (may be empty)
+
+**Do NOT** modify `approvals.mode` (controls user-confirmation of tool calls
+— a security setting that must stay as the user configured it). **Do NOT**
+modify `terminal.cwd` — the kanban dispatcher overrides cwd per-task via
+`--workspace dir:<path>`, so the profile's cwd is irrelevant to the kanban
+work and changing it could break the user's interactive use of the profile.
+
+Use **PyYAML**, not string replacement, so the patch is robust against
+default-config schema drift:
+
+```bash
+configure_profile() {
+    local profile="$1"
+    local toolsets_json="$2"     # JSON array, e.g. '["kanban","terminal","file"]'
+    local skills_json="$3"       # JSON array, e.g. '["kanban-worker","ascii-video"]'
+    python3 - "$profile" "$toolsets_json" "$skills_json" <<'PY'
+import json, os, sys, yaml
+profile, ts_json, sk_json = sys.argv[1:4]
+p = os.path.expanduser(f"~/.hermes/profiles/{profile}/config.yaml")
+with open(p) as f:
+    cfg = yaml.safe_load(f) or {}
+cfg["toolsets"] = json.loads(ts_json)
+cfg.setdefault("skills", {})["always_load"] = json.loads(sk_json)
+with open(p, "w") as f:
+    yaml.safe_dump(cfg, f, sort_keys=False)
+PY
+}
+```
+
+PyYAML must be installed in the user's Python (it ships with most Hermes
+installs). If absent: `pip install pyyaml`.
+
+The setup script should also **validate** the patch by re-reading the file
+and comparing — see `assets/setup.sh.tmpl` for the validation pattern.
+
+### SOUL.md per profile
+
+Each profile gets a `SOUL.md` at `~/.hermes/profiles/<name>/SOUL.md` that
+defines its role, voice, and rules. See `assets/soul.md.tmpl` for the
+template. Customize per role and per project.
+
+The director's SOUL.md should be the most opinionated — its voice flavors
+the entire production. **Critical content for the director's SOUL.md:**
+
+- **Anti-temptation rules:** "Do not execute the work yourself. For every
+  concrete task, create a kanban task and assign it. Decompose, route, comment,
+  approve — that's the whole job." (The `kanban-orchestrator` skill provides
+  the deeper playbook; load it.)
+- **Decomposition steps:** Read `brief.md`, `TEAM.md`, `taste/`. Use the team
+  graph in `TEAM.md` to fan out tasks.
+- **The workspace_path rule** (see below).
+
+Other profiles' SOUL.md is briefer; mostly mechanical: who you are, what you
+read, what you produce, what skills/tools to use, where to write outputs.
+Most non-director profiles should `always_load: kanban-worker` for the
+deeper-than-baseline kanban guidance.
+
+### Initial kanban task
+
+The final action of setup.sh is firing the kanban:
+
+```bash
+hermes kanban create "Direct production of <video title>" \
+    --assignee director \
+    --workspace dir:"$HOME/projects/video-pipeline/${PROJECT_SLUG}" \
+    --tenant ${PROJECT_SLUG} \
+    --priority 2 \
+    --max-runtime 4h \
+    --body "$(cat <<EOF
+Read brief.md, TEAM.md, and taste/.
+Decompose into the team graph defined in TEAM.md.
+All child tasks MUST use:
+  workspace_kind="dir"
+  workspace_path="$HOME/projects/video-pipeline/${PROJECT_SLUG}"
+  tenant="${PROJECT_SLUG}"
+EOF
+)"
+```
+
+The `--workspace dir:<path>` flag is **critical** — it tells the kanban that
+all child tasks share this workspace. Skipping or using `worktree` will
+isolate profiles and break artifact sharing.
+
+## The TEAM.md file
+
+Alongside `brief.md`, write a `TEAM.md` that the director reads. It documents
+the team composition + task graph the orchestrator should follow. This
+removes ambiguity and prevents the director from inventing extra steps.
+
+Example structure (for an ASCII video with a music supervisor and editor):
+
+```markdown
+# Team & Task Graph — <video title>
+
+## Team
+
+- `director` (this profile) — vision, decomposition, approval
+- `cinematographer` — visual spec, quality review (loads `ascii-video`)
+- `renderer-ascii` — ASCII scenes (loads `ascii-video`)
+- `music-supervisor` — track analysis (loads `songsee`)
+- `voice-talent` — narration (uses ElevenLabs API)
+- `audio-mixer` — final mix (ffmpeg)
+- `editor` — assembly (ffmpeg)
+- `reviewer` — final QA gate
+
+## Task Graph
+
+T0: this task — decompose
+ │
+ ├── T1: cinematographer  "Design visual language"            (parent: T0)
+ │    │
+ │    ├── T2a: renderer-ascii   "Scene 1 — title card"        (parent: T1)
+ │    ├── T2b: renderer-ascii   "Scene 2 — main beat"         (parent: T1)
+ │    ├── T2c: renderer-ascii   "Scene 3 — outro"             (parent: T1)
+ │
+ ├── T3: music-supervisor "Analyze track + emit beats.json"   (parent: T0)
+ │
+ ├── T4: voice-talent     "Generate narration"                (parent: T0)
+ │
+ ├── T5: audio-mixer      "Mix VO + bg music"                 (parents: T3, T4)
+ │
+ ├── T6: editor           "Assemble cut + mux audio"          (parents: T2*, T5)
+ │
+ └── T7: reviewer         "Final QA"                          (parent: T6)
+```
+
+The director turns this into actual `kanban_create` calls.
+
+## API-key prerequisites check
+
+Before firing the kanban, verify required keys are available. Check both
+`~/.hermes/.env` and macOS Keychain (if on macOS):
+
+```bash
+check_key() {
+    local var="$1"
+    local kc_account="$2"
+    local kc_service="$3"
+    if grep -q "^${var}=" ~/.hermes/.env 2>/dev/null && \
+       [ -n "$(grep "^${var}=" ~/.hermes/.env | cut -d= -f2-)" ]; then
+        return 0
+    fi
+    if command -v security >/dev/null 2>&1 && \
+       security find-generic-password -a "${kc_account}" -s "${kc_service}" -w >/dev/null 2>&1; then
+        return 0
+    fi
+    echo "ERROR: ${var} not set in ~/.hermes/.env or Keychain (${kc_account}/${kc_service})"
+    return 1
+}
+
+check_key ELEVENLABS_API_KEY hermes ELEVENLABS_API_KEY || exit 1
+check_key OPENROUTER_API_KEY hermes OPENROUTER_API_KEY || exit 1
+# ...
+```
+
+If a key is missing, the script aborts with a clear message rather than
+firing a kanban that will hit credential errors mid-execution.
+
+## Critical rules
+
+1. **`workspace_kind="dir"` + `workspace_path="<absolute>"` on every kanban_create.** Otherwise profiles can't share artifacts.
+
+2. **Tenant every task.** `--tenant <project-slug>` keeps the dashboard scoped
+   and prevents cross-pollination with other ongoing kanbans.
+
+3. **Idempotency keys.** For tasks that should not duplicate on re-run (e.g.,
+   setup creating profiles), use the `idempotency_key` argument or check
+   existence first.
+
+4. **`max_runtime_seconds` per task.** Renderers that get stuck eat compute.
+   Standard defaults:
+   - Renderer task: 1800s (30min)
+   - Editor task: 600s (10min)
+   - Voice-talent task: 300s (5min)
+   - Image-generator task: 600s (10min)
+   - Image-to-video-generator task: 900s (15min)
+
+5. **Heartbeats for long renders.** Tasks expected to run >5min should emit
+   `kanban_heartbeat` periodically with progress. Renderers should report
+   frame counts; the editor should report assembly progress.
+
+6. **The `audio/` and `taste/` dirs are populated BEFORE firing the kanban.**
+   Don't ask the director's pipeline to source these — copy at setup time.
+
+7. **`brief.md` is read-only after setup.** If the brief changes during
+   execution, that's a significant pivot — re-fire the kanban rather than edit
+   live.

optional-skills/creative/kanban-video-orchestrator/references/monitoring.md

@@ -0,0 +1,180 @@
+# Monitoring — Watch the Pipeline + Intervene
+
+After `setup.sh` fires the kanban, the work runs autonomously. The role of
+this skill in the execution phase is to help the user (and the AI overseeing
+the session) detect problems early and intervene effectively.
+
+## Live monitoring commands
+
+```bash
+# Live event stream — task spawns, status changes, heartbeats, completions
+hermes kanban watch --tenant <project-slug>
+
+# Snapshot of the board
+hermes kanban list --tenant <project-slug>
+hermes kanban list --tenant <project-slug> --json     # machine-readable
+
+# Per-status counts + oldest-ready age
+hermes kanban stats --tenant <project-slug>
+
+# Visual dashboard (browser)
+hermes dashboard
+
+# Inspect a specific task (includes comments + events)
+hermes kanban show <task-id>
+
+# Follow a single task's event stream
+hermes kanban tail <task-id>
+```
+
+Verify available subcommands with `hermes kanban --help` — the kanban CLI
+ships with `init / create / list / show / assign / link / unlink / claim /
+comment / complete / block / unblock / archive / tail / dispatch / watch /
+stats / heartbeat / log / runs / context / gc`.
+
+The companion `scripts/monitor.py` polls the kanban via the CLI and surfaces
+common issues (stuck tasks, missing heartbeats, repeated retries, dependency
+deadlocks).
+
+## What to watch for
+
+### Healthy pipeline indicators
+
+- Tasks transition `READY → RUNNING → DONE` in roughly the expected order
+- Renderers emit periodic `kanban_heartbeat` events with progress (e.g. "frame
+  240/720")
+- Each task's runtime is well under its `max_runtime_seconds` cap
+- No task accumulates more than 1 retry
+- Dependency arrows resolve (children unblock as parents complete)
+
+### Warning signs
+
+| Symptom | Likely cause | Action |
+|---------|--------------|--------|
+| Task RUNNING but no heartbeat in 2+ min | Worker stuck, infinite loop, blocked on input | `hermes kanban show <id>` — read the worker's last events. The dispatcher SIGTERMs tasks that exceed their `max-runtime`; if you need to stop one earlier, `hermes kanban block <id>` then `hermes kanban archive <id>`, and create a re-run task. |
+| Same task retried 2+ times | Reproducible failure (missing key, bad spec, broken tool) | `hermes kanban show <id>` to read failure events. Fix root cause before re-running. |
+| RUNNING longer than max_runtime | Task is slow but progressing OR genuinely stuck | Check heartbeats with `hermes kanban tail <id>`. If progressing, the dispatcher will SIGTERM eventually anyway — raise `max-runtime` on a re-created task. |
+| Child task READY but parents still RUNNING for >2× expected | Cascade slow, dependency miswired | Check the dependency graph. Inspect the parent: sometimes it completed but its handoff fields (summary, metadata) were empty so the child has nothing to consume. |
+| New tasks not appearing | Director is hung in decomposition | Inspect director task with `kanban show`. Often a malformed `kanban_create` call. |
+| Specialist tasks completing instantly | Decomposition created tasks without bodies | Director didn't pass enough context. Re-create with explicit body content. |
+| Tasks created but never picked up | Profile not running, or tenant mismatch, or dispatcher not running | Check `hermes profile list` (profile exists?), `hermes status` (gateway/dispatcher up?), and verify tenant. |
+| Specific renderer task fails → review note → renderer redoes → fails again | Brief is asking for the impossible | Pivot the brief, not the renderer. |
+
+## Intervention recipes
+
+### Rejecting bad output
+
+When a renderer ships a clip that doesn't pass review:
+
+```bash
+# 1. Comment on the renderer's task with specific feedback
+hermes kanban comment <renderer-task-id> "Scene 3 looks too sparse \
+— increase visual density. Tighten color palette to brand spec."
+
+# 2. Create a re-render task with the original as parent
+hermes kanban create "Scene 3 — re-render with feedback" \
+    --assignee renderer-ascii \
+    --parent <renderer-task-id> \
+    --workspace dir:"$HOME/projects/video-pipeline/<slug>" \
+    --tenant <slug> \
+    --skill ascii-video \
+    --max-runtime 30m
+```
+
+### Adding a new dependency mid-flight
+
+When the editor needs an asset that wasn't originally planned (e.g., a captions
+file):
+
+```bash
+# 1. Create the new task and capture its id
+NEW_TASK_ID=$(hermes kanban create "Generate SRT captions from voiceover" \
+    --assignee captioner \
+    --workspace dir:"$HOME/projects/video-pipeline/<slug>" \
+    --tenant <slug> \
+    --json | python3 -c "import json,sys;print(json.load(sys.stdin)['id'])")
+
+# 2. Wire it as a parent of the editor's task with `kanban link`
+hermes kanban link "$NEW_TASK_ID" <editor-task-id>
+```
+
+`kanban link` takes `parent_id child_id` (parent first). Use `kanban unlink`
+to remove a dependency.
+
+### Stopping a worker that's stuck
+
+The kanban dispatcher will SIGTERM (then SIGKILL) any task that exceeds its
+`--max-runtime` automatically. To stop one sooner:
+
+```bash
+# Mark blocked so the dispatcher leaves it alone, then archive
+hermes kanban block <task-id>
+hermes kanban archive <task-id>
+
+# Diagnose what happened
+hermes kanban show <task-id>      # task body, comments, recent events
+hermes kanban tail <task-id>      # follow the live event stream
+hermes kanban log <task-id>       # worker process log
+```
+
+After stopping, decide: fix root cause + re-create the task, or skip and
+adjust dependent tasks.
+
+### Pivoting the brief
+
+If during execution the user wants something fundamentally different:
+
+1. Cancel the active director task and all RUNNING children
+2. Edit `brief.md` and `TEAM.md`
+3. Re-fire the initial `hermes kanban create` for the director
+
+Don't try to "edit while running" — the kanban's audit trail makes a clean
+pivot more legible than mid-stream changes.
+
+## Periodic check-in script
+
+A simple polling pattern for hands-off monitoring:
+
+```bash
+while true; do
+    clear
+    hermes kanban list --tenant <slug>
+    echo "---"
+    hermes kanban stats --tenant <slug>
+    sleep 30
+done
+```
+
+For a live event feed, run `hermes kanban watch --tenant <slug>` in a
+separate terminal — it streams task lifecycle events as they happen.
+
+For automated intervention (auto-restart stuck tasks, auto-create re-render on
+review failure), see the `scripts/monitor.py` patterns.
+
+## When to call it done
+
+The pipeline is finished when:
+
+1. All RENDER tasks complete and pass review
+2. The editor's `output/final.mp4` exists and `ffprobe` confirms expected
+   duration + streams
+3. The reviewer (if present) has approved
+4. Optional masterer variants exist
+
+At this point, present the final.mp4 path to the user along with any review
+notes. Do NOT delete the workspace — the user may want to iterate on a single
+scene without re-running the whole pipeline.
+
+## Common gotchas
+
+- **Tenant mismatches.** A task created with the wrong tenant won't appear in
+  monitoring. Always pass `--tenant <slug>` consistently.
+- **Profile process not running.** Tasks queue indefinitely in READY if no
+  worker for that profile is online. Check `hermes profile list` and start
+  any missing profiles.
+- **Workspace permissions.** All profiles need read+write to the workspace
+  directory. `chmod -R u+rw <workspace>` if any worker reports permission
+  errors.
+- **Audio/visual sync.** The editor's clip stitching must match the
+  renderer's actual output durations. Don't hardcode scene durations in
+  the editor — read from the renderer's handoff metadata.

optional-skills/creative/kanban-video-orchestrator/references/role-archetypes.md

@@ -0,0 +1,298 @@
+# Role Archetypes
+
+The library of role archetypes for video production. **Compose a team from this
+list, don't clone a fixed roster.** Most videos need 4-7 profiles. The director
+is always present; everything else is conditional on the brief.
+
+Each role's profile name is by convention `kebab-case` (e.g. `creative-director`,
+`image-generator`). Multiple instances of the same role get descriptive suffixes
+when they need different focus (e.g., `renderer-ascii`, `renderer-3d`).
+
+For toolset + skill mapping per role, see [tool-matrix.md](tool-matrix.md).
+
+## Always present
+
+### director
+
+The vision-holder. Reads the brief and brand guide, decomposes into a task
+graph, comments to steer creative direction, approves the final cut.
+
+- **Toolsets:** kanban, terminal, file
+- **Skills:** `kanban-orchestrator`. The kanban plugin auto-injects baseline
+  orchestration guidance for free; `kanban-orchestrator` is the deeper
+  decomposition playbook. Add `creative-ideation` if the brief is wide-open
+  and needs framing help.
+- **Personality:** Tied to the brand voice — see `assets/soul.md.tmpl`
+
+The director has the same toolset as everyone else, but its `SOUL.md` rules
+**forbid** execution. The "decompose, don't execute" discipline is enforced
+by personality + the kanban-orchestrator skill, not by missing tools.
+
+## Pre-production roles
+
+Pick based on what the brief needs.
+
+### writer / screenwriter
+
+Writes scripts, dialogue, voiceover copy, narration. Use for any video with
+spoken or written words beyond a tagline.
+
+- **Toolsets:** kanban, file
+- **Skills:** `kanban-worker`, `humanizer` (post-process to strip AI-tells)
+- **Outputs:** `script.md`, `narration.md`, `dialogue/scene-NN.md`
+
+### copywriter
+
+Like `writer` but specifically for marketing copy: taglines, CTAs, voiceover
+scripts for product videos.
+
+- **Toolsets:** kanban, file
+- **Skills:** `kanban-worker`, `humanizer`
+- **Outputs:** `copy.md`
+
+### concept-artist / visual-designer
+
+Develops the visual identity: mood board, style frames, color palette
+rationale, typography choices. Produces a `visual-spec.md` that all generators
+follow. Often produces still reference frames using image-generation APIs or
+local skills.
+
+- **Toolsets:** kanban, terminal, file
+- **Skills:** `kanban-worker` plus any project-specific design skill —
+  `claude-design` (UI/web), `sketch` (quick mockup variants),
+  `popular-web-designs` (matching known web aesthetic), `pixel-art` (retro),
+  `ascii-art` (terminal/retro), `excalidraw` (hand-drawn frames),
+  `design-md` (text-based design docs)
+- **Outputs:** `visual-spec.md`, `taste/style-frames/*.png`
+
+### storyboarder
+
+Maps the brief to a beat-by-beat shot list with timing. Critical for narrative
+film and music video. Often pairs with a diagramming tool.
+
+- **Toolsets:** kanban, file
+- **Skills:** `kanban-worker` plus a diagram skill — `excalidraw` (sketch),
+  `architecture-diagram` (technical/system), `concept-diagrams` (educational/
+  scientific)
+- **Outputs:** `storyboard.md` with one row per scene/shot, optional
+  storyboard sketches
+
+### cinematographer / dp
+
+Designs the visual language: framing, color, motion, transitions. Reviews
+generator output for visual consistency. Hands off per-scene `VISUAL_SPEC.md`.
+
+- **Toolsets:** kanban, terminal, file, video, vision
+- **Skills:** `kanban-worker` plus the visual skill that matches the project
+  (e.g., `ascii-video` for ASCII work, `manim-video` for explainers,
+  `touchdesigner-mcp` for real-time visuals, etc.)
+- **Outputs:** `scenes/scene-NN/VISUAL_SPEC.md`, review comments on renderer
+  tasks
+- **Reviews via:** `video_analyze` (sends full clip to multimodal LLM for
+  native review), `vision_analyze` for spot-checking frames, ffprobe summaries
+
+## Production roles
+
+### renderer (generic)
+
+A worker that produces visual content for one or more scenes. Loaded with
+whichever creative skill fits the scene's style. Multiple renderers can run in
+parallel, each pinned to a different skill via `always_load` in their profile
+or `--skill` on the task.
+
+- **Toolsets:** kanban, terminal, file
+- **Skills:** one creative skill (see specialized variants below)
+- **Outputs:** `scenes/scene-NN/clip.mp4`
+
+### Specialized renderer variants
+
+When scenes need very different tools, create specialized renderer profiles
+instead of overloading one. Each loads a different creative skill.
+
+| Variant | Skill | Best for |
+|---------|-------|----------|
+| `renderer-ascii` | `ascii-video` | Terminal aesthetic, retro pixel, audio-reactive grid, video-to-ASCII conversion |
+| `renderer-manim` | `manim-video` | Math, algorithms, 3Blue1Brown-style explainers, equation derivations |
+| `renderer-p5js` | `p5js` | Generative art, particles, shaders, organic motion, web-canvas content |
+| `renderer-comfyui` | `comfyui` | AI-generated stills + video using local ComfyUI workflows (img-to-img, img-to-video, etc.) |
+| `renderer-touchdesigner` | `touchdesigner-mcp` | Real-time, audio-reactive, installation art, VJ-style content |
+| `renderer-3d` | `blender-mcp` *(optional)* | 3D modeling, animation, photoreal environments, character animation |
+| `renderer-pixel` | `pixel-art` | Retro game aesthetic with era-correct palettes |
+| `renderer-comic` | `baoyu-comic` | Knowledge-comic style narrative scenes |
+| `renderer-meme` | `meme-generation` *(optional)* | Meme-style stills for satirical/social content |
+| `renderer-procedural` | (none — Python with PIL + ffmpeg directly) | Custom procedural content where no skill fits |
+| `renderer-video` | (external image-to-video API: Runway / Kling / Luma) | Animating still images in narrative film |
+| `renderer-motion-graphics` | (external — Remotion CLI) | Motion graphics, kinetic typography, UI animations |
+
+For external-API renderers, the profile holds the API client logic; only
+`kanban-worker` is loaded, plus the terminal toolset and the API key.
+
+### image-generator
+
+Specifically for text-to-image generation. Often produces stills that go to
+`renderer-video` for animation.
+
+- **Toolsets:** kanban, terminal, file
+- **Skills:** `kanban-worker`, optionally `comfyui` (drives a local
+  ComfyUI install for image generation)
+- **External APIs (alternative to local ComfyUI):** FAL, Replicate, OpenAI
+  Images, Midjourney
+- **Outputs:** `scenes/scene-NN/stills/*.png`
+
+### image-to-video-generator
+
+Takes still images and animates them via Runway/Kling/Luma APIs, or via
+ComfyUI's image-to-video workflows locally. Almost always follows
+`image-generator` in narrative film pipelines.
+
+- **Toolsets:** kanban, terminal, file
+- **Skills:** `kanban-worker`, optionally `comfyui` (for local image-to-video
+  workflows like AnimateDiff or WAN)
+- **External APIs:** Runway, Kling, Luma, Pika
+- **Outputs:** `scenes/scene-NN/clip.mp4`
+
+### music-supervisor
+
+Sources, analyzes, and prepares the music track. For music videos, also
+produces a beat/BPM map and key-moment timestamps. Uses `songsee` for
+spectrograms when the editor or renderer needs a visual reference of the
+audio's energy.
+
+- **Toolsets:** kanban, terminal, file
+- **Skills:** `kanban-worker`, `songsee` (audio visualization), plus one of:
+  - `songwriting-and-ai-music` — when commissioning lyrics + Suno prompts
+  - `heartmula` — when generating music with the open-source local model
+  - `spotify` — when sourcing existing tracks
+- **Outputs:** `audio/track.mp3`, `audio/beats.json`, optional
+  `audio/track-spectrogram.png`
+
+### voice-talent / narrator
+
+Generates voiceover audio. Calls a TTS API directly; no Hermes skill required
+beyond `kanban-worker`. The user can also supply pre-recorded VO instead of
+generation.
+
+- **Toolsets:** kanban, terminal, file
+- **Skills:** `kanban-worker`
+- **External APIs:** ElevenLabs, OpenAI TTS, etc.
+- **Outputs:** `audio/voiceover/line-NN.mp3`, `audio/voiceover/timeline.mp3`
+
+### foley / sfx-designer
+
+Sound effects and ambient design. Often optional unless the brief calls for
+sound design specifically.
+
+- **Toolsets:** kanban, terminal, file
+- **Skills:** `kanban-worker`, `songsee` for audio-feature visualization when
+  designing to a track
+- **Outputs:** `audio/sfx/*.mp3`
+
+## Post-production roles
+
+### editor
+
+Assembles the final cut from clips. Uses ffmpeg for stitching, fades,
+transitions. Reviews each clip for pacing and quality before assembly.
+
+- **Toolsets:** kanban, terminal, file
+- **Skills:** `kanban-worker`
+- **External tools:** ffmpeg, ffprobe
+- **Outputs:** `output/final.mp4`, `output/final-noaudio.mp4`
+
+### colorist
+
+Color grading. Usually optional — if the renderers already produce
+brand-consistent output and the editor just stitches, the colorist is overkill.
+Worth including for narrative film with hero shots.
+
+- **Toolsets:** kanban, terminal, file
+- **Skills:** `kanban-worker`
+- **Outputs:** `output/final-graded.mp4`
+
+### audio-mixer
+
+Mixes voiceover + music + SFX into a final audio track. Sets levels, ducks
+music under VO, normalizes loudness (LUFS).
+
+- **Toolsets:** kanban, terminal, file
+- **Skills:** `kanban-worker`
+- **External tools:** ffmpeg with `loudnorm` filter, optional `sox`
+- **Outputs:** `audio/final-mix.mp3`
+
+### captioner
+
+Burns subtitles into the video, generates SRT, handles accessibility. Can also
+generate captions from audio via Whisper.
+
+- **Toolsets:** kanban, terminal, file
+- **Skills:** `kanban-worker`
+- **External tools:** Whisper (CLI or API), ffmpeg subtitle filters
+- **Outputs:** `output/captions.srt`, `output/final-captioned.mp4`
+
+### masterer
+
+Final encode + format variants. Produces deliverables for each platform target
+(square for IG, vertical for TikTok, full HD for YouTube, etc.).
+
+- **Toolsets:** kanban, terminal, file
+- **Skills:** `kanban-worker`
+- **Outputs:** `output/final-1080.mp4`, `output/final-9x16.mp4`, etc.
+
+## QA roles
+
+### reviewer
+
+A neutral quality gate. Reads the brief, watches the cut, comments
+specifically on what's off (pacing, sync, brand alignment, technical
+quality). Distinct from the cinematographer (who reviews visuals during
+production) and the editor (who reviews for assembly).
+
+- **Toolsets:** kanban, terminal, file, video, vision
+- **Skills:** `kanban-worker`
+- **Review tools:** `video_analyze` (native clip review via multimodal LLM),
+  `vision_analyze` (frame/thumbnail review), ffprobe
+- **Outputs:** `review-notes.md`, comments on tasks
+
+### brand-cop
+
+Reviews specifically for brand compliance — colors, typography, voice. Use
+when the brand guidelines are detailed and a generic reviewer might miss
+violations.
+
+- **Toolsets:** kanban, file
+- **Skills:** `kanban-worker`
+- **Outputs:** comments + `brand-review.md`
+
+## Composing teams — heuristics
+
+- **Always:** director + at least one renderer + editor.
+- **Add writer** if scripted dialogue / narration / on-screen text exceeds a
+  tagline.
+- **Add storyboarder** if the brief has more than 5 distinct beats and the
+  director hasn't already laid out a beat list.
+- **Add cinematographer** if multiple renderer instances need consistent
+  visual language. (For a single-tool video, the renderer's own skill spec
+  is enough.)
+- **Add image-generator + image-to-video-generator pair** for narrative film
+  with photorealistic visuals.
+- **Add music-supervisor** when music is provided and rhythm matters
+  (music videos always; explainers sometimes).
+- **Add voice-talent** for any voiceover / narrative dialogue.
+- **Add audio-mixer** when there are 2+ audio sources (VO + music, music + SFX).
+- **Add captioner** for accessibility-priority projects (explainer, tutorial,
+  any platform that defaults to muted playback).
+- **Add reviewer** for high-stakes projects. Skip for quick experimental loops.
+- **Add masterer** when multiple platform deliverables are needed.
+
+## Anti-patterns
+
+- **One renderer doing everything.** If scenes use very different tools
+  (ASCII + 3D + motion graphics), use specialized renderer variants. The
+  renderer loads ONE creative skill at a time; mixing styles in a single
+  renderer causes thrashing.
+- **A separate profile per scene.** No. Profiles are per-role, not per-scene.
+  Eight scenes use one or two renderer profiles, not eight.
+- **A "general" profile that does everything.** Worse than no specialization.
+  The kanban routing breaks down if every task fits every profile.
+- **No reviewer for important deliverables.** Saves an hour of pipeline time
+  but ships flaws.

optional-skills/creative/kanban-video-orchestrator/references/tool-matrix.md

@@ -0,0 +1,317 @@
+# Tool Matrix — Skills + Toolsets per Role
+
+Maps each role archetype to the Hermes skills it should `always_load` and the
+toolsets it needs. Only references skills that ship in the public hermes-agent
+repository (under `skills/` or `optional-skills/`). External APIs and CLIs are
+called from the terminal toolset; they don't appear in `always_load`.
+
+## Hermes skills relevant to video production
+
+### Visual / rendering skills (`hermes-agent/skills/creative/`)
+
+| Skill | What it does | Best fit for |
+|-------|--------------|--------------|
+| `ascii-video` | Production pipeline for ASCII art video — generative, audio-reactive, video-to-ASCII | Renderer for ASCII / terminal / retro pixel content; cinematographer for ASCII projects |
+| `ascii-art` | Static ASCII art generation | Concept artist for ASCII style frames; secondary tool for ASCII renderer |
+| `manim-video` | Manim CE animations — math, algorithms, 3Blue1Brown-style explainers | Renderer for math, algorithm walkthroughs, technical concept explainers |
+| `p5js` | p5.js sketches — generative art, shaders, interactive, 3D | Renderer for generative art, particle systems, organic motion, web-canvas content |
+| `comfyui` | Generate images, video, audio with ComfyUI workflows (image-to-image, image-to-video, etc.) | image-generator, image-to-video-generator, or general renderer for AI-generated content |
+| `touchdesigner-mcp` | Control a running TouchDesigner instance — real-time visuals, audio-reactive installation art, VJ | Renderer for real-time/audio-reactive content; installation art; live performance |
+| `blender-mcp` *(optional)* | Control Blender 4.3+ via MCP — 3D modeling, animation, rendering | Renderer for 3D scenes, photoreal environments, character animation |
+| `pixel-art` | Pixel art with era palettes (NES, Game Boy, PICO-8) | Renderer for retro game aesthetic; concept artist for pixel-style frames |
+| `baoyu-comic` | Knowledge-comic generation (educational, biography, tutorial) | Renderer for comic-style narrative; explainer in panel form |
+| `baoyu-infographic` | Infographic generation | Renderer for data-driven explainer scenes |
+| `meme-generation` *(optional)* | Generate meme images by overlaying text on templates | Generator for satirical/social content; meme-style stills |
+
+### Design / pre-production skills (`hermes-agent/skills/creative/`)
+
+| Skill | What it does | Best fit for |
+|-------|--------------|--------------|
+| `claude-design` | Design one-off HTML artifacts (landing, deck, prototype) | Concept artist for product video style frames; storyboarder for UI-heavy content |
+| `design-md` | Design markdown docs | Concept artist documenting visual specs |
+| `popular-web-designs` | Reference patterns for popular web designs | Concept artist; cinematographer when matching a known UI aesthetic |
+| `sketch` | Throwaway HTML mockups (2-3 design variants to compare) | Concept artist exploring directions; storyboarder for UI flows |
+| `excalidraw` | Excalidraw-style hand-drawn diagrams | Storyboarder; concept artist for sketch-style frames |
+| `architecture-diagram` | Software architecture diagrams | Storyboarder for technical content; explainer scenes about systems |
+| `concept-diagrams` *(optional)* | Flat, minimal SVG diagrams (educational visual language; physics, chemistry, math, anatomy, etc.) | Renderer / storyboarder for explainer scenes with clean educational diagrams |
+| `pretext` | Mathematical/scientific content authoring | Writer / cinematographer for technical-explainer pretexts |
+| `creative-ideation` | Constraint-driven project ideation | Director / cinematographer when the brief is wide-open and needs framing |
+| `humanizer` | Strip AI-isms from text, add real voice | Writer / copywriter post-process to avoid AI-tells in scripts and VO copy |
+
+### Audio / media skills (`hermes-agent/skills/creative/` + `skills/media/`)
+
+| Skill | What it does | Best fit for |
+|-------|--------------|--------------|
+| `songwriting-and-ai-music` | Songwriting craft + Suno prompt patterns | Music supervisor when commissioning a track via Suno |
+| `heartmula` | Open-source music generation (Apache-2.0, Suno-like) | Music supervisor generating bespoke tracks without external APIs |
+| `songsee` | Spectrograms, mel/chroma/MFCC of audio files | Music supervisor analyzing tracks; foley-designer designing to a beat; editor visualizing a mix |
+| `spotify` | Spotify control — play, search, queue, manage playlists | Music supervisor sourcing existing tracks; reference research |
+| `youtube-content` | Fetch transcripts + transform to chapters/summaries/posts | Documentary cut, content adaptation, research for explainers |
+| `gif-search` | Find existing GIFs | Editor / concept artist sourcing references |
+| `gifs` | GIF tooling | Masterer producing GIF deliverables |
+
+### Kanban infrastructure (`hermes-agent/skills/devops/`)
+
+| Skill | What it does | When to load |
+|-------|--------------|--------------|
+| `kanban-orchestrator` | Decomposition playbook + anti-temptation rules for orchestrator profiles | Director only |
+| `kanban-worker` | Pitfalls, examples, edge cases for kanban workers (deeper than auto-injected guidance) | Any profile — load when handling tricky multi-step workflows |
+
+The kanban plugin auto-injects baseline orchestration guidance into every
+worker's system prompt — the `kanban_create` fan-out pattern, claim/handoff
+lifecycle, and the "decompose, don't execute" rule for orchestrators.
+`kanban-orchestrator` and `kanban-worker` are deeper playbooks loaded when a
+profile needs them.
+
+## External tools (called from terminal toolset)
+
+These are **not** Hermes skills but external CLIs / APIs that profiles invoke.
+They don't appear in `always_load`; instead the role's terminal commands hit
+them directly.
+
+| Tool | What it does | Profile that uses it |
+|------|--------------|----------------------|
+| `ffmpeg` | Video / audio encode, splice, mux | renderer, editor, audio-mixer, masterer |
+| `ffprobe` | Inspect media | All media-touching profiles |
+| Whisper (CLI or API) | Speech-to-text for captions | captioner |
+| Text-to-image API (FAL / Replicate / OpenAI / Midjourney) | Stills generation | image-generator (alternative to local `comfyui`) |
+| Image-to-video API (Runway / Kling / Luma / Pika) | Animate stills | image-to-video-generator |
+| Text-to-speech API (ElevenLabs / OpenAI TTS / etc.) | Voiceover generation | voice-talent |
+| Suno API or web | Track composition (paired with `songwriting-and-ai-music`) | music-supervisor |
+| Remotion CLI (`npx remotion render`) | React-based motion graphics | renderer-motion-graphics |
+| Manim CE (`manim`) | Math animation render (driven by `manim-video` skill's recipes) | renderer-manim |
+| Blender (`blender -b`) | 3D rendering (alternative to `blender-mcp`) | renderer-3d |
+
+## Built-in Hermes tools for media review
+
+These are native Hermes tools — not invoked via terminal but through their own
+toolsets. Enable them per-profile by adding the toolset to the profile config.
+
+| Tool | Toolset | What it does | Profile that uses it |
+|------|---------|--------------|----------------------|
+| `video_analyze` | `video` (opt-in — `hermes tools enable video`) | Native video understanding — sends full clip to a multimodal LLM (Gemini via OpenRouter) for review without frame extraction. Supports mp4, webm, mov, avi, mkv. 50 MB cap. Model: `AUXILIARY_VIDEO_MODEL` env → `AUXILIARY_VISION_MODEL` fallback. | reviewer, cinematographer, editor |
+| `vision_analyze` | `vision` (core — enabled by default) | Image/frame analysis — review stills, thumbnails, exported frames. Already available to all profiles without opt-in. | reviewer, cinematographer, concept-artist |
+
+## Standard toolset configurations per role
+
+### director
+
+```yaml
+toolsets:
+  - kanban
+  - terminal
+  - file
+skills:
+  always_load:
+    - kanban-orchestrator
+```
+
+The director's terminal access is conventional but the SOUL.md rules forbid
+execution. Audit logs catch violations.
+
+### writer / copywriter
+
+```yaml
+toolsets:
+  - kanban
+  - file
+skills:
+  always_load:
+    - kanban-worker
+    - humanizer            # post-process scripts to strip AI-tells
+```
+
+No terminal — writers don't need it.
+
+### concept-artist
+
+```yaml
+toolsets:
+  - kanban
+  - terminal
+  - file
+skills:
+  always_load:
+    - kanban-worker
+    # plus one or more (style-dependent):
+    # - claude-design       (UI / web product video)
+    # - sketch              (quick mockup variants)
+    # - excalidraw          (hand-drawn frames)
+    # - ascii-art           (ASCII style frames)
+    # - pixel-art           (retro/game aesthetic)
+    # - popular-web-designs (matching known web aesthetic)
+    # - design-md           (text-based design docs)
+```
+
+### storyboarder
+
+```yaml
+toolsets:
+  - kanban
+  - file
+skills:
+  always_load:
+    - kanban-worker
+    # one of:
+    # - excalidraw              (sketch storyboards)
+    # - architecture-diagram    (technical/system content)
+    # - concept-diagrams        (educational / scientific content)
+```
+
+### cinematographer
+
+```yaml
+toolsets:
+  - kanban
+  - terminal
+  - file
+  - video               # video_analyze — review full clips natively
+  - vision              # vision_analyze — review stills / exported frames
+skills:
+  always_load:
+    - kanban-worker
+    # the visual skill that matches the project, e.g.:
+    # - ascii-video            (ASCII projects)
+    # - manim-video            (math/explainer)
+    # - p5js                   (generative)
+    # - comfyui                (AI-generated visuals)
+    # - blender-mcp            (3D)
+    # - touchdesigner-mcp      (real-time/installation)
+```
+
+### renderer (specialized variants)
+
+```yaml
+toolsets:
+  - kanban
+  - terminal
+  - file
+skills:
+  always_load:
+    - kanban-worker
+    # ONE skill per renderer variant (or empty for external-API renderers):
+    # - ascii-video               (renderer-ascii)
+    # - manim-video               (renderer-manim)
+    # - p5js                      (renderer-p5js)
+    # - comfyui                   (renderer-comfyui — img/video AI gen)
+    # - touchdesigner-mcp         (renderer-touchdesigner)
+    # - blender-mcp               (renderer-3d)
+    # - pixel-art                 (renderer-pixel)
+    # - baoyu-comic               (renderer-comic)
+    # - meme-generation           (renderer-meme)
+```
+
+For external-API renderers (image-to-video-generator using Runway, voice-talent
+using ElevenLabs, renderer-motion-graphics using Remotion), `always_load` only
+contains `kanban-worker` — the role's work is API-driven and the API key +
+terminal commands suffice.
+
+For multi-skill renderer setups (rare — usually one variant per skill is
+cleaner) use `--skill <name>` on individual `kanban_create` calls to override
+which skill loads for that specific task.
+
+### image-generator / image-to-video-generator / voice-talent
+
+```yaml
+toolsets:
+  - kanban
+  - terminal
+  - file
+skills:
+  always_load:
+    - kanban-worker
+    # for image-generator that drives ComfyUI locally:
+    # - comfyui
+env_required:
+  # populate based on the chosen API:
+  - FAL_KEY                 # or REPLICATE_API_TOKEN, OPENAI_API_KEY for image-gen
+  - RUNWAY_API_KEY          # or KLING_API_KEY, LUMA_API_KEY for image-to-video
+  - ELEVENLABS_API_KEY      # or OPENAI_API_KEY for TTS
+```
+
+If the user's setup has ComfyUI installed locally, the `comfyui` skill can
+replace the external image-gen API entirely (cheaper, more control, supports
+custom workflows for image-to-video too).
+
+### music-supervisor
+
+```yaml
+toolsets:
+  - kanban
+  - terminal
+  - file
+skills:
+  always_load:
+    - kanban-worker
+    - songsee                         # spectrograms / audio analysis
+    # plus (depending on what the project needs):
+    # - songwriting-and-ai-music      (commissioning Suno tracks)
+    # - heartmula                     (commissioning open-source local generation)
+    # - spotify                       (sourcing existing tracks)
+```
+
+### editor / audio-mixer / captioner / masterer
+
+```yaml
+toolsets:
+  - kanban
+  - terminal
+  - file
+  - video              # video_analyze — editor reviews assembled cuts natively
+  - vision             # vision_analyze — spot-check frames
+skills:
+  always_load:
+    - kanban-worker
+```
+
+These are mostly ffmpeg-driven; no special skill needed beyond `kanban-worker`.
+For captioner add Whisper invocation patterns to the SOUL.md.
+
+### reviewer / brand-cop
+
+```yaml
+toolsets:
+  - kanban
+  - terminal           # for media inspection (ffprobe, etc.)
+  - file
+  - video              # video_analyze — review full clips natively
+  - vision             # vision_analyze — review stills / exported frames
+skills:
+  always_load:
+    - kanban-worker
+```
+
+## API key requirements
+
+Track these in the project setup. The setup script should verify each required
+key is present in `~/.hermes/.env` (or macOS Keychain) before firing the kanban.
+
+| Service | Env var | Used by |
+|---------|---------|---------|
+| ElevenLabs | `ELEVENLABS_API_KEY` | voice-talent |
+| OpenAI | `OPENAI_API_KEY` | image-generator (DALL-E), voice-talent (TTS) |
+| OpenRouter | `OPENROUTER_API_KEY` | reviewer, cinematographer, editor (`video_analyze` routes through `AUXILIARY_VIDEO_MODEL` → OpenRouter) |
+| FAL | `FAL_KEY` | image-generator (FAL flux models) |
+| Replicate | `REPLICATE_API_TOKEN` | image-generator (alternate provider) |
+| Runway | `RUNWAY_API_KEY` | image-to-video-generator |
+| Kling | `KLING_API_KEY` | image-to-video-generator (alternate) |
+| Luma | `LUMA_API_KEY` | image-to-video-generator (alternate) |
+| Suno | `SUNO_API_KEY` | music-supervisor (paired with `songwriting-and-ai-music`) |
+| Spotify | `SPOTIFY_CLIENT_ID` + `SPOTIFY_CLIENT_SECRET` | music-supervisor (paired with `spotify` skill) |
+| Anthropic | `ANTHROPIC_API_KEY` | every Hermes profile (Claude) |
+
+If a key is missing, prompt the user to add it. Storage methods, in order of
+preference: macOS Keychain → `~/.hermes/.env` → environment variable.
+
+## Skill version pinning
+
+If a specific skill version is desired, pass it via the per-task
+`--skill <name>=<version>` flag. The default is whatever's installed.
+
+## Adding a new skill to the matrix
+
+When a new Hermes-public video skill ships:
+
+1. Add a row to the relevant table at the top of this file
+2. If it warrants a specialized renderer variant, add to `role-archetypes.md`
+3. Update relevant per-style examples in `examples.md`

optional-skills/creative/kanban-video-orchestrator/scripts/bootstrap_pipeline.py

@@ -0,0 +1,501 @@
+#!/usr/bin/env python3
+"""
+Bootstrap a video production kanban from a structured plan JSON.
+
+Reads a plan.json describing the team + brief, expands templates from
+../assets/, and writes a setup.sh that creates Hermes profiles and fires the
+initial kanban task.
+
+Profile-config patching, SOUL.md-per-profile, TEAM.md task-graph convention,
+and the `hermes kanban create --workspace dir:` initial-task pattern are
+adapted from alt-glitch's NousResearch/kanban-video-pipeline.
+
+Usage:
+    bootstrap_pipeline.py plan.json [--out setup.sh]
+
+The plan.json schema is documented inline below — see the `validate_plan`
+function. A minimal example:
+
+    {
+      "title": "Q3 Product Teaser",
+      "slug": "q3-product-teaser",
+      "tenant": "q3-product-teaser",
+      "duration_s": 30,
+      "aspect": "1:1",
+      "resolution": "1080x1080",
+      "fps": 30,
+      "team": [
+        {
+          "profile": "director",
+          "role": "director",
+          "toolsets": ["kanban", "terminal", "file"],
+          "skills": [],
+          "responsibilities": "...",
+          "inputs": "brief.md, TEAM.md, taste/",
+          "outputs": "kanban tasks for the team"
+        },
+        ...
+      ],
+      "scenes": [
+        {"n": 1, "time": "0:00-0:08", "content": "...", "tool": "renderer-ascii"},
+        ...
+      ],
+      "audio": {"approach": "voiceover + music bed", "vo": "ElevenLabs Lily",
+                "music": "license-free", "sfx": "n/a"},
+      "deliverables": [
+        {"format": "mp4", "resolution": "1080x1080", "notes": "primary"}
+      ],
+      "api_keys_required": ["ELEVENLABS_API_KEY", "OPENROUTER_API_KEY"],
+      "brief_extra": {
+        "concept_one_liner": "...",
+        "emotional_north_star": "...",
+        "visual_refs": "...",
+        "tone": "...",
+        "brand_constraints": "..."
+      }
+    }
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+from pathlib import Path
+
+ASSETS_DIR = Path(__file__).resolve().parent.parent / "assets"
+
+
+def load_template(name: str) -> str:
+    return (ASSETS_DIR / name).read_text()
+
+
+PROFILE_NAME_RE = re.compile(r"^[a-z0-9][a-z0-9_-]{0,63}$")
+SLUG_RE = re.compile(r"^[a-z0-9][a-z0-9-]+$")
+
+
+def validate_plan(plan: dict) -> list[str]:
+    """Return a list of validation error strings; empty list = valid."""
+    errors = []
+    required_top = ["title", "slug", "tenant", "duration_s", "aspect",
+                    "resolution", "fps", "team", "scenes", "audio",
+                    "deliverables"]
+    for k in required_top:
+        if k not in plan:
+            errors.append(f"missing required key: {k}")
+
+    if "team" in plan:
+        if not isinstance(plan["team"], list) or not plan["team"]:
+            errors.append("team must be a non-empty list")
+        else:
+            roles = [t.get("role") for t in plan["team"]]
+            if "director" not in roles:
+                errors.append("team must include a director role")
+            seen_profiles = set()
+            for i, t in enumerate(plan["team"]):
+                for k in ["profile", "role", "toolsets", "skills",
+                          "responsibilities"]:
+                    if k not in t:
+                        errors.append(f"team[{i}] missing {k}")
+                # Profile name must match Hermes's regex (lowercase
+                # alphanumeric + hyphens + underscores, up to 64 chars).
+                if "profile" in t:
+                    if not PROFILE_NAME_RE.match(t["profile"]):
+                        errors.append(
+                            f"team[{i}].profile {t['profile']!r} must match "
+                            f"[a-z0-9][a-z0-9_-]{{0,63}} per Hermes profile rules"
+                        )
+                    if t["profile"] in seen_profiles:
+                        errors.append(
+                            f"team[{i}].profile {t['profile']!r} is duplicated"
+                        )
+                    seen_profiles.add(t["profile"])
+                # Toolsets / skills must be lists, not strings.
+                if "toolsets" in t and not isinstance(t["toolsets"], list):
+                    errors.append(
+                        f"team[{i}].toolsets must be a list of strings"
+                    )
+                if "skills" in t and not isinstance(t["skills"], list):
+                    errors.append(
+                        f"team[{i}].skills must be a list of strings"
+                    )
+
+    if "slug" in plan:
+        if not SLUG_RE.match(plan["slug"]):
+            errors.append("slug must be lowercase, hyphenated, "
+                          "starting with [a-z0-9]")
+
+    return errors
+
+
+def render_brief(plan: dict) -> str:
+    """Render brief.md from the plan."""
+    tmpl = load_template("brief.md.tmpl")
+    extra = plan.get("brief_extra", {})
+
+    # Scene table rows
+    scene_rows = []
+    for s in plan["scenes"]:
+        scene_rows.append(
+            f"| {s.get('n', '?')} | {s.get('time', '?')} | "
+            f"{s.get('content', '')} | {s.get('tool', '')} | "
+            f"{s.get('audio', '')} | {s.get('notes', '')} |"
+        )
+    scene_table = "\n".join(scene_rows) if scene_rows else "_(none yet)_"
+
+    # Deliverable rows
+    deliv_rows = []
+    for d in plan["deliverables"]:
+        deliv_rows.append(
+            f"| {d.get('format', '?')} | {d.get('resolution', '?')} | "
+            f"{d.get('notes', '')} |"
+        )
+    deliv_table = "\n".join(deliv_rows) if deliv_rows else "_(none)_"
+
+    # Replacements (single-pass)
+    replacements = {
+        "TITLE": plan["title"],
+        "SLUG": plan["slug"],
+        "TENANT": plan["tenant"],
+        "WORKSPACE": f"~/projects/video-pipeline/{plan['slug']}",
+        "ONE_LINE_PITCH": extra.get("concept_one_liner", "_(TBD)_"),
+        "EMOTIONAL_NORTH_STAR": extra.get("emotional_north_star", "_(TBD)_"),
+        "DURATION_S": str(plan["duration_s"]),
+        "ASPECT": plan["aspect"],
+        "RESOLUTION": plan["resolution"],
+        "FPS": str(plan["fps"]),
+        "PLATFORMS": extra.get("platforms", "_(TBD)_"),
+        "DEADLINE": extra.get("deadline", "_(none)_"),
+        "QUALITY_BAR": extra.get("quality_bar", "polished"),
+        "VISUAL_REFS": extra.get("visual_refs", "_(none)_"),
+        "TONE": extra.get("tone", "_(TBD)_"),
+        "BRAND_CONSTRAINTS": extra.get("brand_constraints", "_(none)_"),
+        "AESTHETIC_RULES": extra.get("aesthetic_rules", "_(TBD)_"),
+        "AUDIO_APPROACH": plan["audio"].get("approach", "_(TBD)_"),
+        "VO_DETAILS": plan["audio"].get("vo", "_(n/a)_"),
+        "MUSIC_DETAILS": plan["audio"].get("music", "_(n/a)_"),
+        "SFX_DETAILS": plan["audio"].get("sfx", "_(n/a)_"),
+        "PRIMARY_FORMAT": plan["deliverables"][0]["format"],
+        "PRIMARY_RES": plan["deliverables"][0]["resolution"],
+        "ALT_FORMAT_1": (plan["deliverables"][1]["format"]
+                          if len(plan["deliverables"]) > 1 else "_(none)_"),
+        "ALT_RES_1": (plan["deliverables"][1]["resolution"]
+                       if len(plan["deliverables"]) > 1 else ""),
+        "ALT_NOTES_1": (plan["deliverables"][1].get("notes", "")
+                         if len(plan["deliverables"]) > 1 else ""),
+        "API_KEYS_REQUIRED": ", ".join(plan.get("api_keys_required", [])) or "none",
+        "EXT_DEPS": extra.get("ext_deps", "ffmpeg, Python 3.11+"),
+        "SOURCE_ASSETS": extra.get("source_assets", "_(none)_"),
+    }
+    out = tmpl
+    for k, v in replacements.items():
+        out = out.replace("{{" + k + "}}", str(v))
+
+    # Scene + deliv tables: replace the placeholder row in the template
+    out = re.sub(
+        r"\|\s*1\s*\|\s*0:00–0:0X.+?\n\|\s*2\s*\|.+?\n",
+        scene_table + "\n",
+        out, flags=re.DOTALL,
+    )
+    return out
+
+
+def render_team_md(plan: dict) -> str:
+    """Render TEAM.md from the team list + scene → tool mapping."""
+    lines = [f"# Team & Task Graph — {plan['title']}", "", "## Team", ""]
+    for t in plan["team"]:
+        skills = (
+            f"loads `{', '.join(t['skills'])}`"
+            if t["skills"] else "no skills required"
+        )
+        lines.append(
+            f"- `{t['profile']}` — {t['responsibilities']} ({skills})"
+        )
+    lines.extend(["", "## Task Graph", "", "```"])
+
+    # Build a simple task graph based on conventions
+    profiles_by_role = {t["role"]: t["profile"] for t in plan["team"]}
+    director = profiles_by_role.get("director", "director")
+    lines.append(f"T0  {director} — decompose")
+
+    next_id = 1
+    parents_for_renderer: list[str] = ["T0"]
+
+    if "cinematographer" in profiles_by_role:
+        cid = f"T{next_id}"
+        lines.append(
+            f"{cid:5} {profiles_by_role['cinematographer']} — visual spec for all scenes (parent: T0)"
+        )
+        parents_for_renderer = [cid]
+        next_id += 1
+
+    if "music-supervisor" in profiles_by_role:
+        cid = f"T{next_id}"
+        lines.append(
+            f"{cid:5} {profiles_by_role['music-supervisor']} — track analysis + beats.json (parent: T0)"
+        )
+        next_id += 1
+        ms_id = cid
+    else:
+        ms_id = None
+
+    # Scenes
+    scene_ids = []
+    for s in plan["scenes"]:
+        cid = f"T{next_id}"
+        renderer_profile = s.get("tool") or "renderer"
+        # Lookup the actual profile name
+        for t in plan["team"]:
+            if t["role"] == renderer_profile or t["profile"] == renderer_profile:
+                renderer_profile = t["profile"]
+                break
+        parents = parents_for_renderer + ([ms_id] if ms_id else [])
+        parent_str = ", ".join(parents)
+        lines.append(
+            f"{cid:5} {renderer_profile} — scene {s.get('n', '?')}: "
+            f"{s.get('content', '')[:50]} (parents: {parent_str})"
+        )
+        scene_ids.append(cid)
+        next_id += 1
+
+    # VO + audio mix
+    if "voice-talent" in profiles_by_role:
+        vo_id = f"T{next_id}"
+        lines.append(f"{vo_id:5} {profiles_by_role['voice-talent']} — narration (parent: T0)")
+        next_id += 1
+    else:
+        vo_id = None
+
+    if "audio-mixer" in profiles_by_role:
+        am_id = f"T{next_id}"
+        am_parents = [p for p in [ms_id, vo_id] if p]
+        lines.append(
+            f"{am_id:5} {profiles_by_role['audio-mixer']} — mix audio (parents: {', '.join(am_parents)})"
+        )
+        next_id += 1
+    else:
+        am_id = None
+
+    # Editor
+    if "editor" in profiles_by_role:
+        ed_id = f"T{next_id}"
+        ed_parents = scene_ids + [p for p in [am_id, vo_id, ms_id] if p and p not in scene_ids]
+        lines.append(
+            f"{ed_id:5} {profiles_by_role['editor']} — assemble + mux (parents: {', '.join(ed_parents)})"
+        )
+        next_id += 1
+    else:
+        ed_id = None
+
+    # Captioner
+    if "captioner" in profiles_by_role and ed_id:
+        cap_id = f"T{next_id}"
+        lines.append(
+            f"{cap_id:5} {profiles_by_role['captioner']} — SRT + burn (parent: {ed_id})"
+        )
+        next_id += 1
+        last = cap_id
+    else:
+        last = ed_id
+
+    # Reviewer
+    if "reviewer" in profiles_by_role and last:
+        rv_id = f"T{next_id}"
+        lines.append(
+            f"{rv_id:5} {profiles_by_role['reviewer']} — final QA (parent: {last})"
+        )
+
+    lines.append("```")
+    lines.extend([
+        "",
+        "## Per-task workspace requirement",
+        "",
+        f"All `kanban_create` calls MUST pass:",
+        f"```",
+        f'workspace_kind="dir"',
+        f'workspace_path="$HOME/projects/video-pipeline/{plan["slug"]}"',
+        f'tenant="{plan["tenant"]}"',
+        f"```",
+    ])
+    return "\n".join(lines)
+
+
+def render_setup_sh(plan: dict, brief_md: str, team_md: str) -> str:
+    """Render setup.sh from the plan."""
+    tmpl = load_template("setup.sh.tmpl")
+
+    # API key checks
+    key_checks = []
+    for key in plan.get("api_keys_required", []):
+        key_checks.append(f'check_key {key} hermes {key} || exit 1')
+    key_checks_str = "\n".join(key_checks) if key_checks else "# (no API keys required)"
+
+    # Scene dirs
+    scene_dir_lines = []
+    for s in plan["scenes"]:
+        n = s.get("n", "?")
+        scene_dir_lines.append(f'mkdir -p "$WORKSPACE/scenes/scene-{n:02d}"/checkpoints')
+    scene_dirs = "\n".join(scene_dir_lines) if scene_dir_lines else ""
+
+    # Profile create
+    profile_creates = []
+    for t in plan["team"]:
+        profile_creates.append(
+            f'hermes profile create {t["profile"]} --clone 2>/dev/null || true'
+        )
+
+    # Profile config — emit JSON arrays so the bash function can pass them
+    # safely through to the Python YAML patcher.
+    profile_configs = []
+    for t in plan["team"]:
+        ts_json = json.dumps(t["toolsets"])
+        sk_json = json.dumps(t["skills"])
+        # Use single-quoted bash strings; JSON only contains "/[/], no single
+        # quotes, so this is safe.
+        profile_configs.append(
+            f"configure_profile {t['profile']!r} {ts_json!r} {sk_json!r}"
+        )
+
+    # SOUL writes — uses heredocs per profile
+    soul_writes = []
+    for t in plan["team"]:
+        soul_writes.append(
+            f'cat > "$HOME/.hermes/profiles/{t["profile"]}/SOUL.md" <<\'SOUL_EOF\'\n'
+            f"{render_soul_md(t, plan)}\n"
+            f"SOUL_EOF\n"
+            f'echo "  ✓ SOUL.md for {t["profile"]}"'
+        )
+
+    # Taste writes (placeholder; real content optional)
+    taste_writes = (
+        'cat > "$WORKSPACE/taste/brand-guide.md" <<\'TASTE_EOF\'\n'
+        '# Brand Guide\n\n'
+        '_(Populate with project-specific colors, typography, motion rules)_\n'
+        'TASTE_EOF\n'
+        'cat > "$WORKSPACE/taste/emotional-dna.md" <<\'DNA_EOF\'\n'
+        '# Emotional DNA\n\n'
+        '_(What this piece should FEEL like — populate from the brief.)_\n'
+        'DNA_EOF'
+    )
+
+    # Asset copies — leave empty by default; user fills in
+    asset_copies = "# Add cp/rsync commands here for any provided assets"
+
+    out = tmpl
+    out = out.replace("{{TITLE}}", plan["title"])
+    out = out.replace("{{SLUG}}", plan["slug"])
+    out = out.replace("{{TENANT}}", plan["tenant"])
+    out = out.replace("{{WORKSPACE}}", f"~/projects/video-pipeline/{plan['slug']}")
+    out = out.replace("{{KEY_CHECKS}}", key_checks_str)
+    out = out.replace("{{SCENE_DIRS}}", scene_dirs)
+    out = out.replace("{{PROFILE_CREATE_COMMANDS}}", "\n".join(profile_creates))
+    out = out.replace("{{PROFILE_CONFIG_COMMANDS}}", "\n".join(profile_configs))
+    out = out.replace("{{SOUL_WRITES}}", "\n".join(soul_writes))
+    out = out.replace("{{BRIEF_CONTENTS}}", brief_md)
+    out = out.replace("{{TEAM_CONTENTS}}", team_md)
+    out = out.replace("{{TASTE_WRITES}}", taste_writes)
+    out = out.replace("{{ASSET_COPIES}}", asset_copies)
+
+    return out
+
+
+def render_soul_md(team_member: dict, plan: dict) -> str:
+    """Render a profile's SOUL.md from a team member dict + plan context."""
+    tmpl = load_template("soul.md.tmpl")
+    role = team_member["role"]
+
+    common_rules = (
+        "- **Read the brief and team graph** before doing anything else.\n"
+        "- **Pass `workspace_kind=\"dir\"` and `workspace_path` on every "
+        "`kanban_create` call.** This keeps the team in one shared workspace.\n"
+        f"- **Use tenant `{plan['tenant']}`** on every kanban call.\n"
+        "- **Write outputs to predictable paths.** Other profiles depend on "
+        "your filename conventions.\n"
+        "- **Emit heartbeats** during long-running work. Renderers should "
+        "report frame counts; editors should report assembly progress.\n"
+    )
+
+    if role == "director":
+        common_rules += (
+            "- **Do not execute the work yourself.** For every concrete task, "
+            "create a kanban task and assign it to the appropriate profile.\n"
+            "- **Decompose, route, comment, approve — that's the whole job.**\n"
+            "- **Read TEAM.md** for the canonical task graph. Do not invent "
+            "new roles unless the brief truly demands it.\n"
+            "- **Load the `kanban-orchestrator` skill** for the deeper "
+            "decomposition playbook beyond the auto-injected baseline.\n"
+        )
+
+    common_commands = (
+        "```bash\n"
+        "# Inspect a clip\n"
+        "ffprobe -v quiet -show_entries format=duration -show_entries "
+        "stream=codec_name,width,height,r_frame_rate <file.mp4>\n"
+        "\n"
+        "# Extract a frame for QA\n"
+        "ffmpeg -y -i <input.mp4> -vf \"select='eq(n,30)'\" -vsync vfr <out.png>\n"
+        "```"
+    )
+
+    out = tmpl
+    out = out.replace("{{ROLE_NAME}}", role)
+    out = out.replace("{{ROLE_RESPONSIBILITIES}}", team_member["responsibilities"])
+    out = out.replace("{{INPUTS_READ}}", team_member.get("inputs", "_(see brief)_"))
+    out = out.replace("{{OUTPUTS_PRODUCED}}", team_member.get("outputs", "_(see brief)_"))
+    out = out.replace("{{TOOLSETS}}", ", ".join(team_member["toolsets"]))
+    out = out.replace(
+        "{{SKILLS}}",
+        ", ".join(team_member["skills"]) if team_member["skills"] else "(none)"
+    )
+    out = out.replace(
+        "{{EXTERNAL_TOOLS}}",
+        team_member.get("external_tools", "ffmpeg, ffprobe (via terminal)")
+    )
+    out = out.replace(
+        "{{ROLE_RULES}}",
+        team_member.get("role_rules", "_(see TEAM.md and brief.md)_")
+    )
+    out = out.replace("{{COMMON_RULES}}", common_rules)
+    out = out.replace("{{COMMON_COMMANDS}}", common_commands)
+    return out
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__,
+                                  formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("plan_json", help="Path to plan.json")
+    ap.add_argument("--out", default="setup.sh",
+                    help="Output path for setup.sh (default: ./setup.sh)")
+    ap.add_argument("--brief-out", default=None,
+                    help="Write brief.md alongside (default: skipped)")
+    ap.add_argument("--team-out", default=None,
+                    help="Write TEAM.md alongside (default: skipped)")
+    args = ap.parse_args()
+
+    plan = json.loads(Path(args.plan_json).read_text())
+    errors = validate_plan(plan)
+    if errors:
+        print("Plan validation failed:", file=sys.stderr)
+        for e in errors:
+            print(f"  - {e}", file=sys.stderr)
+        sys.exit(2)
+
+    brief = render_brief(plan)
+    team = render_team_md(plan)
+    setup = render_setup_sh(plan, brief, team)
+
+    Path(args.out).write_text(setup)
+    os.chmod(args.out, 0o755)
+    print(f"Wrote {args.out}")
+
+    if args.brief_out:
+        Path(args.brief_out).write_text(brief)
+        print(f"Wrote {args.brief_out}")
+    if args.team_out:
+        Path(args.team_out).write_text(team)
+        print(f"Wrote {args.team_out}")
+
+
+if __name__ == "__main__":
+    main()

optional-skills/creative/kanban-video-orchestrator/scripts/monitor.py

@@ -0,0 +1,195 @@
+#!/usr/bin/env python3
+"""
+Monitor a running video-production kanban. Polls `hermes kanban list` and
+`events` for a tenant and surfaces issues (stuck tasks, missing heartbeats,
+repeated retries, dependency deadlocks).
+
+Usage:
+    monitor.py --tenant <project-slug> [--interval 30]
+
+Outputs a periodic snapshot to stdout. Sends alerts via stderr when issues
+are detected. Designed to run alongside the kanban — kill with Ctrl-C when
+you're satisfied (or scripted to stop on completion).
+
+This is best-effort observability. It does not auto-restart tasks; intervention
+decisions should remain human/AI-overseen.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import shutil
+import subprocess
+import sys
+import time
+from collections import defaultdict
+from datetime import datetime, timedelta
+
+
+def hermes_available() -> bool:
+    return shutil.which("hermes") is not None
+
+
+def kanban_list(tenant: str) -> list[dict]:
+    """Returns parsed task rows. Falls back to plain stdout parsing if JSON
+    output isn't supported by the installed hermes CLI."""
+    try:
+        out = subprocess.run(
+            ["hermes", "kanban", "list", "--tenant", tenant, "--json"],
+            capture_output=True, text=True, check=False,
+        )
+        if out.returncode == 0 and out.stdout.strip().startswith("["):
+            return json.loads(out.stdout)
+    except (FileNotFoundError, json.JSONDecodeError):
+        pass
+    # Fallback: textual parse of `hermes kanban list`
+    out = subprocess.run(
+        ["hermes", "kanban", "list", "--tenant", tenant],
+        capture_output=True, text=True, check=False,
+    )
+    rows = []
+    for line in out.stdout.splitlines():
+        line = line.strip()
+        if not line or line.startswith("#") or "STATUS" in line.upper():
+            continue
+        parts = line.split()
+        if len(parts) >= 4 and parts[0].startswith("t_"):
+            rows.append({
+                "id": parts[0],
+                "status": parts[1] if len(parts) > 1 else "?",
+                "assignee": parts[2] if len(parts) > 2 else "?",
+                "title": " ".join(parts[3:]) if len(parts) > 3 else "",
+                "started_at": None,
+                "heartbeat_at": None,
+                "max_runtime_s": None,
+            })
+    return rows
+
+
+def kanban_show(task_id: str) -> dict | None:
+    out = subprocess.run(
+        ["hermes", "kanban", "show", task_id, "--json"],
+        capture_output=True, text=True, check=False,
+    )
+    if out.returncode != 0:
+        return None
+    try:
+        return json.loads(out.stdout)
+    except json.JSONDecodeError:
+        return None
+
+
+def detect_issues(tasks: list[dict]) -> list[str]:
+    """Return a list of issue strings, one per concern."""
+    now = datetime.now()
+    issues: list[str] = []
+    by_status = defaultdict(list)
+    for t in tasks:
+        by_status[t.get("status", "?")].append(t)
+
+    # Stuck tasks: RUNNING with no heartbeat in 2 min
+    for t in by_status.get("running", []) + by_status.get("RUNNING", []):
+        hb = t.get("heartbeat_at")
+        if not hb:
+            continue
+        try:
+            hb_dt = datetime.fromisoformat(str(hb).rstrip("Z"))
+        except ValueError:
+            continue
+        if now - hb_dt > timedelta(minutes=2):
+            issues.append(
+                f"STUCK: {t['id']} ({t.get('assignee', '?')}) — "
+                f"no heartbeat in {(now - hb_dt).total_seconds():.0f}s"
+            )
+
+    # Tasks exceeding max_runtime
+    for t in by_status.get("running", []) + by_status.get("RUNNING", []):
+        started = t.get("started_at")
+        max_rt = t.get("max_runtime_s")
+        if not started or not max_rt:
+            continue
+        try:
+            started_dt = datetime.fromisoformat(str(started).rstrip("Z"))
+        except ValueError:
+            continue
+        elapsed = (now - started_dt).total_seconds()
+        if elapsed > max_rt:
+            issues.append(
+                f"OVERTIME: {t['id']} ({t.get('assignee', '?')}) — "
+                f"running {elapsed:.0f}s, cap was {max_rt}s"
+            )
+
+    # Repeated retries
+    for t in tasks:
+        retries = t.get("retries", 0)
+        if retries and retries >= 2:
+            issues.append(
+                f"FLAPPING: {t['id']} ({t.get('assignee', '?')}) — "
+                f"retried {retries}× — fix root cause before next run"
+            )
+
+    return issues
+
+
+def snapshot(tenant: str) -> tuple[list[dict], list[str]]:
+    tasks = kanban_list(tenant)
+    issues = detect_issues(tasks)
+    return tasks, issues
+
+
+def print_snapshot(tasks: list[dict], issues: list[str]):
+    counts = defaultdict(int)
+    for t in tasks:
+        counts[str(t.get("status", "?")).lower()] += 1
+
+    print(f"\n[{datetime.now().strftime('%H:%M:%S')}] "
+          f"Total: {len(tasks)} | "
+          + " | ".join(f"{k}: {v}" for k, v in sorted(counts.items())))
+
+    for t in tasks:
+        bar = "✓" if str(t.get("status", "")).lower() == "done" else \
+              "▶" if str(t.get("status", "")).lower() == "running" else \
+              "·" if str(t.get("status", "")).lower() == "ready" else \
+              "✗" if str(t.get("status", "")).lower() == "failed" else "?"
+        print(f"  {bar} {t.get('id', '?'):14} {t.get('assignee', '?'):20}  "
+              f"{t.get('title', '')[:60]}")
+
+    if issues:
+        print("\n  ⚠  ISSUES:", file=sys.stderr)
+        for i in issues:
+            print(f"     {i}", file=sys.stderr)
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__,
+                                  formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--tenant", required=True,
+                    help="Project tenant slug to monitor")
+    ap.add_argument("--interval", type=int, default=30,
+                    help="Poll interval in seconds (default: 30)")
+    ap.add_argument("--once", action="store_true",
+                    help="Print one snapshot and exit (no polling loop)")
+    args = ap.parse_args()
+
+    if not hermes_available():
+        print("ERROR: 'hermes' CLI not found in PATH", file=sys.stderr)
+        sys.exit(1)
+
+    if args.once:
+        tasks, issues = snapshot(args.tenant)
+        print_snapshot(tasks, issues)
+        sys.exit(0 if not issues else 2)
+
+    print(f"Monitoring tenant '{args.tenant}' every {args.interval}s. "
+          "Ctrl-C to exit.")
+    try:
+        while True:
+            tasks, issues = snapshot(args.tenant)
+            print_snapshot(tasks, issues)
+            time.sleep(args.interval)
+    except KeyboardInterrupt:
+        print("\nStopped.")
+
+
+if __name__ == "__main__":
+    main()

plugins/google_meet/node/server.py

@@ -43,7 +43,7 @@ class NodeServer:
 
     def __init__(
         self,
-        host: str = "0.0.0.0",
+        host: str = "127.0.0.1",
         port: int = 18789,
         token_path: Optional[Path] = None,
         display_name: str = "hermes-meet-node",
@@ -76,6 +76,13 @@ class NodeServer:
             json.dumps({"token": tok, "generated_at": time.time()}, indent=2),
             encoding="utf-8",
         )
+        # Restrict to owner-read-write only — the token grants full RPC
+        # access to the meet bot (start, transcribe, speak in meetings).
+        try:
+            tmp.chmod(0o600)
+        except (OSError, NotImplementedError):
+            # Best-effort on non-POSIX filesystems; mode is set on POSIX.
+            pass
         tmp.replace(self.token_path)
         self._token = tok
         return tok

plugins/hermes-achievements/README.md

@@ -11,6 +11,8 @@ Achievement system for the Hermes Dashboard: collectible, tiered badges generate
 The screenshots use temporary demo tier data to show the full visual range. The plugin itself reads real local Hermes session history by default.
 
 > **Update notice (2026-04-29):** If you installed this plugin before today, update to the latest version. The achievements scan path was refactored for much faster warm loads (snapshot cache + incremental checkpoint scan).
+>
+> **Share cards (2026-05-04, vendored in hermes-agent v0.4.0):** Unlocked achievement cards now have a "Share" button that renders a 1200×630 PNG share card (client-side canvas, no backend, no network) with Download + Copy-to-clipboard actions. Fits X/Twitter, Discord, LinkedIn, Bluesky link-preview dimensions.
 
 ## What it does
 

plugins/hermes-achievements/dashboard/dist/index.js

@@ -66,6 +66,296 @@
     });
   }
 
+  const TIER_HEX = {
+    "Copper": "#b87333",
+    "Silver": "#c0c7d2",
+    "Gold": "#f2c94c",
+    "Diamond": "#67e8f9",
+    "Olympian": "#c084fc",
+  };
+
+  function tierHex(tier) {
+    return TIER_HEX[tier] || "#67e8f9";
+  }
+
+  // Render a LUCIDE icon path fragment into a standalone SVG string with an
+  // explicit stroke color so it can be rasterized onto a <canvas> via Image.
+  // The normal render path uses stroke="currentColor" which browsers honor in
+  // DOM but NOT when the SVG is drawn to a canvas from a data URL.
+  function iconSvgForCanvas(iconKey, strokeColor) {
+    const paths = LUCIDE[iconKey] || LUCIDE.secret;
+    return "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 24 24\" fill=\"none\" " +
+      "stroke=\"" + strokeColor + "\" stroke-width=\"2\" stroke-linecap=\"round\" stroke-linejoin=\"round\">" +
+      paths + "</svg>";
+  }
+
+  function loadSvgImage(svgString) {
+    return new Promise(function (resolve, reject) {
+      const blob = new Blob([svgString], { type: "image/svg+xml;charset=utf-8" });
+      const url = URL.createObjectURL(blob);
+      const img = new Image();
+      img.onload = function () { URL.revokeObjectURL(url); resolve(img); };
+      img.onerror = function (e) { URL.revokeObjectURL(url); reject(e); };
+      img.src = url;
+    });
+  }
+
+  function wrapText(ctx, text, maxWidth) {
+    const words = String(text || "").split(/\s+/).filter(Boolean);
+    const lines = [];
+    let current = "";
+    for (let i = 0; i < words.length; i++) {
+      const candidate = current ? current + " " + words[i] : words[i];
+      if (ctx.measureText(candidate).width <= maxWidth) {
+        current = candidate;
+      } else {
+        if (current) lines.push(current);
+        current = words[i];
+      }
+    }
+    if (current) lines.push(current);
+    return lines;
+  }
+
+  // Build a 1200x630 share card PNG for a single achievement. Returns a Blob.
+  // Pure client-side render via Canvas2D — no external deps, no network.
+  async function buildShareImage(achievement) {
+    const W = 1200;
+    const H = 630;
+    const canvas = document.createElement("canvas");
+    canvas.width = W;
+    canvas.height = H;
+    const ctx = canvas.getContext("2d");
+
+    const tier = achievement.tier || achievement.next_tier || "Copper";
+    const color = tierHex(tier);
+
+    // Background: dark charcoal with a tier-tinted radial highlight on the
+    // top-left, echoing the card visual language.
+    ctx.fillStyle = "#0b0d11";
+    ctx.fillRect(0, 0, W, H);
+    const bgGrad = ctx.createRadialGradient(260, 220, 60, 260, 220, 820);
+    bgGrad.addColorStop(0, color + "33");
+    bgGrad.addColorStop(0.55, color + "0a");
+    bgGrad.addColorStop(1, "#0b0d1100");
+    ctx.fillStyle = bgGrad;
+    ctx.fillRect(0, 0, W, H);
+
+    // Outer border
+    ctx.strokeStyle = color + "66";
+    ctx.lineWidth = 2;
+    ctx.strokeRect(1, 1, W - 2, H - 2);
+
+    // Icon block — 380x380 on the left
+    try {
+      const svg = iconSvgForCanvas(achievement.icon || "secret", color);
+      const iconImg = await loadSvgImage(svg);
+      const ix = 90;
+      const iy = 125;
+      const isize = 380;
+      // Icon glow
+      ctx.save();
+      ctx.shadowColor = color;
+      ctx.shadowBlur = 40;
+      ctx.drawImage(iconImg, ix, iy, isize, isize);
+      ctx.restore();
+    } catch (_) {
+      // Icon render failure is non-fatal; card still useful without it.
+    }
+
+    // Right column text layout
+    const rx = 520;
+    const rMaxWidth = W - rx - 70;
+
+    // Category label (kicker)
+    ctx.fillStyle = "#8b95a8";
+    ctx.font = "600 22px ui-monospace, 'SF Mono', Menlo, monospace";
+    ctx.textBaseline = "top";
+    ctx.fillText((achievement.category || "").toUpperCase(), rx, 112);
+
+    // Achievement name — wrap to 2 lines if needed
+    ctx.fillStyle = "#ffffff";
+    ctx.font = "780 68px system-ui, -apple-system, 'Segoe UI', sans-serif";
+    const nameLines = wrapText(ctx, achievement.name || "Achievement", rMaxWidth).slice(0, 2);
+    let cursorY = 150;
+    for (let i = 0; i < nameLines.length; i++) {
+      ctx.fillText(nameLines[i], rx, cursorY);
+      cursorY += 76;
+    }
+
+    // Tier badge pill
+    const badgeLabel = tier.toUpperCase() + " TIER";
+    ctx.font = "700 22px ui-monospace, 'SF Mono', Menlo, monospace";
+    const badgeWidth = ctx.measureText(badgeLabel).width + 32;
+    const badgeX = rx;
+    const badgeY = cursorY + 14;
+    const badgeH = 40;
+    ctx.fillStyle = color + "1f";
+    ctx.strokeStyle = color;
+    ctx.lineWidth = 1.5;
+    ctx.beginPath();
+    ctx.rect(badgeX, badgeY, badgeWidth, badgeH);
+    ctx.fill();
+    ctx.stroke();
+    ctx.fillStyle = color;
+    ctx.textBaseline = "middle";
+    ctx.fillText(badgeLabel, badgeX + 16, badgeY + badgeH / 2 + 1);
+    ctx.textBaseline = "top";
+
+    // Description — wrap up to 3 lines
+    ctx.fillStyle = "#c3cad6";
+    ctx.font = "400 26px system-ui, -apple-system, 'Segoe UI', sans-serif";
+    const descLines = wrapText(ctx, achievement.description || "", rMaxWidth).slice(0, 3);
+    let descY = badgeY + badgeH + 28;
+    for (let i = 0; i < descLines.length; i++) {
+      ctx.fillText(descLines[i], rx, descY);
+      descY += 34;
+    }
+
+    // Progress / stat line (if meaningful)
+    const progressValue = achievement.progress;
+    const threshold = achievement.next_threshold;
+    let statLine = null;
+    if (progressValue && threshold) {
+      statLine = progressValue.toLocaleString() + " / " + threshold.toLocaleString();
+    } else if (progressValue) {
+      statLine = progressValue.toLocaleString();
+    }
+    if (statLine) {
+      ctx.fillStyle = color;
+      ctx.font = "700 28px ui-monospace, 'SF Mono', Menlo, monospace";
+      ctx.fillText(statLine, rx, descY + 14);
+    }
+
+    // Footer watermark
+    ctx.fillStyle = "#8b95a8";
+    ctx.font = "600 20px ui-monospace, 'SF Mono', Menlo, monospace";
+    ctx.textBaseline = "bottom";
+    ctx.fillText("HERMES AGENT  ·  hermes-agent.nousresearch.com", 70, H - 40);
+
+    // "UNLOCKED" stamp upper-right
+    ctx.textBaseline = "top";
+    ctx.fillStyle = color;
+    ctx.font = "800 24px ui-monospace, 'SF Mono', Menlo, monospace";
+    const stamp = "◆ UNLOCKED";
+    const stampW = ctx.measureText(stamp).width;
+    ctx.fillText(stamp, W - 70 - stampW, 70);
+
+    return await new Promise(function (resolve, reject) {
+      canvas.toBlob(function (blob) {
+        if (blob) resolve(blob); else reject(new Error("canvas.toBlob returned null"));
+      }, "image/png");
+    });
+  }
+
+  function ShareDialog({ achievement, onClose }) {
+    const [status, setStatus] = hooks.useState("rendering"); // rendering | ready | copied | error
+    const [errorMsg, setErrorMsg] = hooks.useState(null);
+    const [previewUrl, setPreviewUrl] = hooks.useState(null);
+    const blobRef = React.useRef(null);
+
+    hooks.useEffect(function () {
+      let cancelled = false;
+      let createdUrl = null;
+      buildShareImage(achievement).then(function (blob) {
+        if (cancelled) return;
+        blobRef.current = blob;
+        createdUrl = URL.createObjectURL(blob);
+        setPreviewUrl(createdUrl);
+        setStatus("ready");
+      }).catch(function (err) {
+        if (cancelled) return;
+        setErrorMsg(String(err && err.message || err));
+        setStatus("error");
+      });
+      return function () {
+        cancelled = true;
+        if (createdUrl) URL.revokeObjectURL(createdUrl);
+      };
+    }, [achievement.id]);
+
+    function download() {
+      if (!blobRef.current) return;
+      const url = URL.createObjectURL(blobRef.current);
+      const a = document.createElement("a");
+      a.href = url;
+      a.download = "hermes-achievement-" + (achievement.id || "badge") + ".png";
+      document.body.appendChild(a);
+      a.click();
+      a.remove();
+      setTimeout(function () { URL.revokeObjectURL(url); }, 1000);
+    }
+
+    async function copyToClipboard() {
+      if (!blobRef.current) return;
+      try {
+        if (!navigator.clipboard || !window.ClipboardItem) {
+          throw new Error("Clipboard image copy not supported in this browser — use Download instead.");
+        }
+        await navigator.clipboard.write([
+          new window.ClipboardItem({ "image/png": blobRef.current }),
+        ]);
+        setStatus("copied");
+        setTimeout(function () { setStatus("ready"); }, 1800);
+      } catch (err) {
+        setErrorMsg(String(err && err.message || err));
+        setStatus("error");
+      }
+    }
+
+    // Build the pre-filled tweet text. Keep it short so X doesn't truncate
+    // when the user hasn't attached the PNG yet — they'll copy-image and
+    // paste in the same flow.
+    function tweetText() {
+      const tierPart = achievement.tier ? (achievement.tier + " tier ") : "";
+      return "Just unlocked " + tierPart + "\"" + achievement.name + "\" in Hermes Agent ☤\n\n" +
+        "@NousResearch · https://hermes-agent.nousresearch.com";
+    }
+
+    function shareOnX() {
+      const url = "https://x.com/intent/post?text=" + encodeURIComponent(tweetText());
+      window.open(url, "_blank", "noopener,noreferrer");
+    }
+
+    return React.createElement("div", {
+      className: "ha-share-backdrop",
+      onClick: function (e) { if (e.target === e.currentTarget) onClose(); },
+    },
+      React.createElement("div", { className: "ha-share-dialog", role: "dialog", "aria-label": "Share achievement" },
+        React.createElement("div", { className: "ha-share-head" },
+          React.createElement("strong", null, "Share: " + achievement.name),
+          React.createElement("button", { className: "ha-share-close", onClick: onClose, "aria-label": "Close" }, "×")
+        ),
+        React.createElement("div", { className: "ha-share-preview" },
+          status === "rendering" && React.createElement("div", { className: "ha-share-placeholder" }, "Rendering…"),
+          previewUrl && React.createElement("img", { src: previewUrl, alt: achievement.name + " share card" })
+        ),
+        status === "error" && React.createElement("div", { className: "ha-share-error" }, errorMsg || "Something went wrong."),
+        React.createElement("div", { className: "ha-share-actions" },
+          React.createElement("button", {
+            className: "ha-share-btn ha-share-btn-primary",
+            onClick: shareOnX,
+            title: "Opens X with a pre-filled post",
+          }, "Share on X"),
+          React.createElement("button", {
+            className: "ha-share-btn",
+            onClick: copyToClipboard,
+            disabled: status !== "ready" && status !== "copied",
+            title: "Copy the image to paste into your post",
+          }, status === "copied" ? "Copied ✓" : "Copy image"),
+          React.createElement("button", {
+            className: "ha-share-btn",
+            onClick: download,
+            disabled: status !== "ready" && status !== "copied",
+          }, "Download PNG")
+        ),
+        React.createElement("p", { className: "ha-share-hint" },
+          "Share on X opens a pre-filled post in a new tab. Click Copy image first if you want the 1200×630 badge attached — X lets you paste it right into the tweet composer. Download PNG saves the file for use anywhere."
+        )
+      )
+    );
+  }
+
   function StatCard(props) {
     return React.createElement(C.Card, { className: "ha-stat" },
       React.createElement(C.CardContent, { className: "ha-stat-content" },
@@ -170,6 +460,7 @@
     const targetTier = achievement.next_tier || achievement.tier;
     const tierLabel = achievement.tier ? achievement.tier : (targetTier ? "Target " + targetTier : (state === "secret" ? "Hidden" : (unlocked ? "Complete" : "Objective")));
     const progressText = state === "secret" ? "hidden" : (progress + (achievement.next_threshold ? " / " + achievement.next_threshold : ""));
+    const [shareOpen, setShareOpen] = hooks.useState(false);
     return React.createElement(C.Card, { className: cn("ha-card", "ha-state-" + state, tierClass(achievement.tier || achievement.next_tier)) },
       React.createElement(C.CardContent, { className: "ha-card-content" },
         React.createElement("div", { className: "ha-card-head" },
@@ -180,7 +471,13 @@
           ),
           React.createElement("div", { className: "ha-badges" },
             React.createElement("span", { className: "ha-state-badge" }, stateLabel),
-            React.createElement("span", { className: "ha-tier-badge" }, tierLabel)
+            React.createElement("span", { className: "ha-tier-badge" }, tierLabel),
+            state === "unlocked" && React.createElement("button", {
+              className: "ha-share-trigger",
+              onClick: function () { setShareOpen(true); },
+              title: "Share this achievement",
+              "aria-label": "Share " + achievement.name,
+            }, "Share")
           )
         ),
         React.createElement("p", { className: "ha-description" }, achievement.description),
@@ -200,7 +497,11 @@
           ),
           React.createElement("span", { className: "ha-progress-text" }, progressText)
         )
-      )
+      ),
+      shareOpen && React.createElement(ShareDialog, {
+        achievement: achievement,
+        onClose: function () { setShareOpen(false); },
+      })
     );
   }
 

plugins/hermes-achievements/dashboard/dist/style.css

@@ -118,3 +118,29 @@
 .ha-scan-banner-text p { margin: .25rem 0 0; font-size: .78rem; line-height: 1.35; color: var(--color-muted-foreground); text-transform: none; letter-spacing: normal; }
 .ha-scan-progress-track { height: .4rem; border: 1px solid color-mix(in srgb, #67e8f9 28%, var(--color-border)); background: rgba(0,0,0,.22); overflow: hidden; }
 .ha-scan-progress-fill { height: 100%; background: linear-gradient(90deg, #67e8f9, color-mix(in srgb, #67e8f9 48%, white)); transition: width .4s ease-out; }
+
+/* Share achievement — trigger button on unlocked cards + modal dialog.
+ * Added to the vendored bundle (on top of the upstream PCinkusz base).
+ * Canvas rendering is pure client-side, no backend, no network.
+ */
+.ha-share-trigger { border: 1px solid color-mix(in srgb, var(--ha-tier) 58%, var(--color-border)); color: var(--ha-tier); background: color-mix(in srgb, var(--ha-tier) 8%, transparent); padding: .18rem .42rem; font-size: .66rem; text-transform: uppercase; letter-spacing: .08em; font-family: var(--font-mono, ui-monospace, monospace); cursor: pointer; margin-top: .05rem; transition: background .12s ease, border-color .12s ease; }
+.ha-share-trigger:hover { background: color-mix(in srgb, var(--ha-tier) 20%, transparent); border-color: var(--ha-tier); }
+.ha-share-trigger:focus-visible { outline: 2px solid var(--ha-tier); outline-offset: 2px; }
+
+.ha-share-backdrop { position: fixed; inset: 0; z-index: 1000; background: rgba(4,6,10,.72); backdrop-filter: blur(6px); display: flex; align-items: center; justify-content: center; padding: 1.5rem; animation: ha-fade-in .14s ease-out; }
+.ha-share-dialog { width: min(760px, 100%); max-height: calc(100vh - 3rem); overflow: auto; border: 1px solid color-mix(in srgb, var(--color-border) 70%, var(--color-ring)); background: color-mix(in srgb, var(--color-card) 94%, #000); box-shadow: 0 24px 60px rgba(0,0,0,.55); display: flex; flex-direction: column; gap: .9rem; padding: 1rem 1.1rem 1.1rem; }
+.ha-share-head { display: flex; align-items: center; justify-content: space-between; gap: .75rem; }
+.ha-share-head strong { font-size: .82rem; text-transform: uppercase; letter-spacing: .1em; font-family: var(--font-mono, ui-monospace, monospace); color: var(--color-foreground); }
+.ha-share-close { width: 1.9rem; height: 1.9rem; display: grid; place-items: center; border: 1px solid var(--color-border); background: transparent; color: var(--color-muted-foreground); font-size: 1.1rem; cursor: pointer; line-height: 1; }
+.ha-share-close:hover { color: var(--color-foreground); border-color: var(--color-ring); }
+.ha-share-preview { position: relative; border: 1px solid var(--color-border); background: #0b0d11; overflow: hidden; aspect-ratio: 1200 / 630; }
+.ha-share-preview img { display: block; width: 100%; height: 100%; object-fit: contain; }
+.ha-share-placeholder { position: absolute; inset: 0; display: grid; place-items: center; color: var(--color-muted-foreground); font-family: var(--font-mono, ui-monospace, monospace); font-size: .82rem; text-transform: uppercase; letter-spacing: .1em; animation: ha-pulse 1.4s ease-in-out infinite; border-radius: 0; }
+.ha-share-error { border: 1px solid #ef4444; color: #fecaca; background: color-mix(in srgb, #ef4444 10%, transparent); padding: .55rem .7rem; font-size: .78rem; font-family: var(--font-mono, ui-monospace, monospace); }
+.ha-share-actions { display: flex; gap: .55rem; flex-wrap: wrap; }
+.ha-share-btn { border: 1px solid var(--color-border); background: color-mix(in srgb, var(--color-card) 72%, transparent); color: var(--color-foreground); padding: .5rem .85rem; font-size: .82rem; font-family: var(--font-mono, ui-monospace, monospace); text-transform: uppercase; letter-spacing: .08em; cursor: pointer; transition: border-color .12s ease, background .12s ease; }
+.ha-share-btn:hover:not(:disabled) { border-color: var(--color-ring); background: color-mix(in srgb, var(--color-primary) 16%, var(--color-card)); }
+.ha-share-btn:disabled { opacity: .5; cursor: not-allowed; }
+.ha-share-btn-primary { border-color: #ffffff; color: #ffffff; background: #000000; }
+.ha-share-btn-primary:hover:not(:disabled) { background: #1a1a1a; border-color: #67e8f9; color: #67e8f9; }
+.ha-share-hint { margin: 0; color: var(--color-muted-foreground); font-size: .76rem; line-height: 1.45; }

plugins/hermes-achievements/dashboard/manifest.json

@@ -3,7 +3,7 @@
   "label": "Achievements",
   "description": "Steam-style achievements for vibe coding and agentic Hermes workflows.",
   "icon": "Star",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "tab": { "path": "/achievements", "position": "after:analytics" },
   "entry": "dist/index.js",
   "css": "dist/style.css",

plugins/image_gen/xai/__init__.py

@@ -203,11 +203,12 @@ class XAIImageGenProvider(ImageGenProvider):
             )
             response.raise_for_status()
         except requests.HTTPError as exc:
-            status = exc.response.status_code if exc.response else 0
+            response = exc.response
+            status = response.status_code if response is not None else 0
             try:
-                err_msg = exc.response.json().get("error", {}).get("message", exc.response.text[:300])
+                err_msg = response.json().get("error", {}).get("message", response.text[:300])
             except Exception:
-                err_msg = exc.response.text[:300] if exc.response else str(exc)
+                err_msg = response.text[:300] if response is not None else str(exc)
             logger.error("xAI image gen failed (%d): %s", status, err_msg)
             return error_response(
                 error=f"xAI image generation failed ({status}): {err_msg}",

plugins/kanban/dashboard/dist/index.js

@@ -63,6 +63,53 @@
   const API = "/api/plugins/kanban";
   const MIME_TASK = "text/x-hermes-task";
 
+  // localStorage key for the user's selected board. Independent of the
+  // CLI's on-disk ``<root>/kanban/current`` pointer so browser users
+  // can inspect any board without shifting the CLI's active board out
+  // from under a terminal they left open.
+  const LS_BOARD_KEY = "hermes.kanban.selectedBoard";
+
+  function readSelectedBoard() {
+    try {
+      const v = window.localStorage.getItem(LS_BOARD_KEY);
+      return (v || "").trim() || null;
+    } catch (_e) { return null; }
+  }
+
+  function writeSelectedBoard(slug) {
+    try {
+      if (slug && slug !== "default") window.localStorage.setItem(LS_BOARD_KEY, slug);
+      else window.localStorage.removeItem(LS_BOARD_KEY);
+    } catch (_e) { /* ignore quota / private mode */ }
+  }
+
+  function withBoard(url, board) {
+    // Append ?board=<slug> when a non-default board is active. Omitted
+    // for default so the URL stays clean and the backend falls through
+    // to its own resolution chain (env var → ``current`` file →
+    // default) which is already correct.
+    if (!board || board === "default") return url;
+    const sep = url.indexOf("?") >= 0 ? "&" : "?";
+    return `${url}${sep}board=${encodeURIComponent(board)}`;
+  }
+
+  // The SDK's Select component fires ``onValueChange(value)`` directly
+  // (it's a shadcn-style popup, not a native <select>). Older plugin
+  // code calls ``onChange({target: {value}})`` which silently never
+  // fires. This helper wires both signatures so a setter works with
+  // either API — use it as:
+  //
+  //   h(Select, {..., ...selectChangeHandler(setState), ...})
+  function selectChangeHandler(setter) {
+    return {
+      onValueChange: function (v) { setter(v == null ? "" : v); },
+      onChange: function (e) {
+        const v = e && e.target ? e.target.value : e;
+        setter(v == null ? "" : v);
+      },
+    };
+  }
+
   // -------------------------------------------------------------------------
   // Minimal safe markdown renderer.
   //
@@ -245,7 +292,19 @@
   // -------------------------------------------------------------------------
 
   function KanbanPage() {
-    const [board, setBoard] = useState(null);
+    const [board, setBoard] = useState(() => readSelectedBoard() || "default");
+    const [boardList, setBoardList] = useState([]);      // [{slug, name, counts, ...}]
+    const [showNewBoard, setShowNewBoard] = useState(false);
+
+    const [kanbanBoard, setKanbanBoard] = useState(null);  // the grid data
+    // Alias so the rest of the function can keep using `board` semantically
+    // for the grid data (card columns + tenants + assignees) without
+    // colliding with the selected-board slug above. History: the old
+    // component had `const [board, setBoard]` for the grid data. We
+    // renamed the grid data to `kanbanBoard` so the more useful name
+    // (`board`) belongs to the selected slug.
+    const boardData = kanbanBoard;
+    const setBoardData = setKanbanBoard;
     const [config, setConfig] = useState(null);
     const [loading, setLoading] = useState(true);
     const [error, setError] = useState(null);
@@ -292,9 +351,9 @@
       if (tenantFilter) qs.set("tenant", tenantFilter);
       if (includeArchived) qs.set("include_archived", "true");
       const url = qs.toString() ? `${API}/board?${qs}` : `${API}/board`;
-      return SDK.fetchJSON(url)
+      return SDK.fetchJSON(withBoard(url, board))
         .then(function (data) {
-          setBoard(data);
+          setBoardData(data);
           cursorRef.current = data.latest_event_id || 0;
           setError(null);
         })
@@ -302,7 +361,26 @@
           setError(String(err && err.message ? err.message : err));
         })
         .finally(function () { setLoading(false); });
-    }, [tenantFilter, includeArchived]);
+    }, [tenantFilter, includeArchived, board]);
+
+    // --- load list of boards for the switcher ------------------------------
+    const loadBoardList = useCallback(function () {
+      return SDK.fetchJSON(`${API}/boards`)
+        .then(function (data) {
+          const boards = (data && data.boards) || [];
+          setBoardList(boards);
+          // If the stored slug isn't in the list any longer (board was
+          // deleted in the CLI while dashboard was open), fall back to
+          // default so the UI doesn't hang on a 404.
+          if (board !== "default" && !boards.find(function (b) { return b.slug === board; })) {
+            setBoard("default");
+            writeSelectedBoard("default");
+          }
+        })
+        .catch(function () { /* non-fatal */ });
+    }, [board]);
+
+    useEffect(function () { loadBoardList(); }, [loadBoardList]);
 
     const scheduleReload = useCallback(function () {
       if (reloadTimerRef.current) return;
@@ -324,16 +402,21 @@
 
     // --- WebSocket ---------------------------------------------------------
     useEffect(function () {
-      if (!board) return undefined;
+      if (!boardData) return undefined;
       wsClosedRef.current = false;
       function openWs() {
         if (wsClosedRef.current) return;
         const token = window.__HERMES_SESSION_TOKEN__ || "";
         const proto = window.location.protocol === "https:" ? "wss:" : "ws:";
-        const qs = new URLSearchParams({
+        const qsParams = {
           since: String(cursorRef.current || 0),
           token: token,
-        });
+        };
+        // Pin the WS stream to the currently-selected board so events
+        // from other boards don't bleed in. Only set for non-default so
+        // single-board installs keep the cleaner URL.
+        if (board && board !== "default") qsParams.board = board;
+        const qs = new URLSearchParams(qsParams);
         const url = `${proto}//${window.location.host}${API}/events?${qs}`;
         let ws;
         try { ws = new WebSocket(url); } catch (_e) { return; }
@@ -372,11 +455,11 @@
         wsClosedRef.current = true;
         try { wsRef.current && wsRef.current.close(); } catch (_e) { /* noop */ }
       };
-    }, [!!board, scheduleReload]);
+    }, [!!boardData, board, scheduleReload]);
 
     // --- filtering ----------------------------------------------------------
     const filteredBoard = useMemo(function () {
-      if (!board) return null;
+      if (!boardData) return null;
       const q = search.trim().toLowerCase();
       const filterTask = function (t) {
         if (assigneeFilter && t.assignee !== assigneeFilter) return false;
@@ -386,18 +469,18 @@
         }
         return true;
       };
-      return Object.assign({}, board, {
-        columns: board.columns.map(function (col) {
+      return Object.assign({}, boardData, {
+        columns: boardData.columns.map(function (col) {
           return Object.assign({}, col, { tasks: col.tasks.filter(filterTask) });
         }),
       });
-    }, [board, assigneeFilter, search]);
+    }, [boardData, assigneeFilter, search]);
 
     // --- actions ------------------------------------------------------------
     const moveTask = useCallback(function (taskId, newStatus) {
       const confirmMsg = DESTRUCTIVE_TRANSITIONS[newStatus];
       if (confirmMsg && !window.confirm(confirmMsg)) return;
-      setBoard(function (b) {
+      setBoardData(function (b) {
         if (!b) return b;
         let moved = null;
         const columns = b.columns.map(function (col) {
@@ -413,7 +496,7 @@
         }
         return Object.assign({}, b, { columns });
       });
-      SDK.fetchJSON(`${API}/tasks/${encodeURIComponent(taskId)}`, {
+      SDK.fetchJSON(withBoard(`${API}/tasks/${encodeURIComponent(taskId)}`, board), {
         method: "PATCH",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({ status: newStatus }),
@@ -421,10 +504,10 @@
         setError(`Move failed: ${err.message || err}`);
         loadBoard();
       });
-    }, [loadBoard]);
+    }, [loadBoard, board]);
 
     const createTask = useCallback(function (body) {
-      return SDK.fetchJSON(`${API}/tasks`, {
+      return SDK.fetchJSON(withBoard(`${API}/tasks`, board), {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify(body),
@@ -437,9 +520,10 @@
           setError("Task created, but: " + res.warning);
         }
         loadBoard();
+        loadBoardList();  // refresh counts in the switcher
         return res;
       });
-    }, [loadBoard]);
+    }, [loadBoard, loadBoardList, board]);
 
     const toggleSelected = useCallback(function (id, additive) {
       setSelectedIds(function (prev) {
@@ -455,7 +539,7 @@
       if (selectedIds.size === 0) return;
       if (confirmMsg && !window.confirm(confirmMsg)) return;
       const body = Object.assign({ ids: Array.from(selectedIds) }, patch);
-      SDK.fetchJSON(`${API}/tasks/bulk`, {
+      SDK.fetchJSON(withBoard(`${API}/tasks/bulk`, board), {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify(body),
@@ -470,14 +554,50 @@
           loadBoard();
         })
         .catch(function (e) { setError(String(e.message || e)); });
-    }, [selectedIds, loadBoard, clearSelected]);
+    }, [selectedIds, loadBoard, clearSelected, board]);
+
+    // --- board switching ----------------------------------------------------
+    const switchBoard = useCallback(function (nextSlug) {
+      if (!nextSlug || nextSlug === board) return;
+      // Optimistic UI: clear the current grid + show loading, reset the
+      // event cursor so the WS reopens aligned to the new board's
+      // latest_event_id on the next loadBoard.
+      setBoardData(null);
+      cursorRef.current = 0;
+      setLoading(true);
+      setBoard(nextSlug);
+      writeSelectedBoard(nextSlug);
+    }, [board]);
+
+    const createNewBoard = useCallback(function (payload) {
+      return SDK.fetchJSON(`${API}/boards`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(payload),
+      }).then(function (res) {
+        loadBoardList();
+        const slug = res && res.board && res.board.slug;
+        if (slug && payload.switch) switchBoard(slug);
+        return res;
+      });
+    }, [loadBoardList, switchBoard]);
+
+    const deleteBoard = useCallback(function (slug) {
+      if (!slug || slug === "default") return Promise.resolve();
+      return SDK.fetchJSON(`${API}/boards/${encodeURIComponent(slug)}`, {
+        method: "DELETE",
+      }).then(function () {
+        loadBoardList();
+        if (board === slug) switchBoard("default");
+      });
+    }, [board, loadBoardList, switchBoard]);
 
     // --- render -------------------------------------------------------------
-    if (loading && !board) {
+    if (loading && !boardData) {
       return h("div", { className: "p-8 text-sm text-muted-foreground" },
         "Loading Kanban board…");
     }
-    if (error && !board) {
+    if (error && !boardData) {
       return h(Card, null,
         h(CardContent, { className: "p-6" },
           h("div", { className: "text-sm text-destructive" },
@@ -493,15 +613,28 @@
 
     return h(ErrorBoundary, null,
       h("div", { className: "hermes-kanban flex flex-col gap-4" },
-        h(BoardToolbar, {
+        h(BoardSwitcher, {
           board: board,
+          boardList: boardList,
+          onSwitch: switchBoard,
+          onNewClick: function () { setShowNewBoard(true); },
+          onDeleteBoard: deleteBoard,
+        }),
+        showNewBoard ? h(NewBoardDialog, {
+          onCancel: function () { setShowNewBoard(false); },
+          onCreate: function (payload) {
+            return createNewBoard(payload).then(function () { setShowNewBoard(false); });
+          },
+        }) : null,
+        h(BoardToolbar, {
+          board: boardData,
           tenantFilter, setTenantFilter,
           assigneeFilter, setAssigneeFilter,
           includeArchived, setIncludeArchived,
           laneByProfile, setLaneByProfile,
           search, setSearch,
           onNudgeDispatch: function () {
-            SDK.fetchJSON(`${API}/dispatch?max=8`, { method: "POST" })
+            SDK.fetchJSON(withBoard(`${API}/dispatch?max=8`, board), { method: "POST" })
               .then(loadBoard)
               .catch(function (e) { setError(String(e.message || e)); });
           },
@@ -509,7 +642,7 @@
         }),
         selectedIds.size > 0 ? h(BulkActionBar, {
           count: selectedIds.size,
-          assignees: (board && board.assignees) || [],
+          assignees: (boardData && boardData.assignees) || [],
           onApply: applyBulk,
           onClear: clearSelected,
         }) : null,
@@ -522,20 +655,215 @@
           onMove: moveTask,
           onOpen: setSelectedTaskId,
           onCreate: createTask,
-          allTasks: board.columns.reduce(function (acc, c) { return acc.concat(c.tasks); }, []),
+          allTasks: boardData.columns.reduce(function (acc, c) { return acc.concat(c.tasks); }, []),
         }),
         selectedTaskId ? h(TaskDrawer, {
           taskId: selectedTaskId,
+          boardSlug: board,
           onClose: function () { setSelectedTaskId(null); },
           onRefresh: loadBoard,
           renderMarkdown: renderMd,
-          allTasks: board.columns.reduce(function (acc, c) { return acc.concat(c.tasks); }, []),
+          allTasks: boardData.columns.reduce(function (acc, c) { return acc.concat(c.tasks); }, []),
           eventTick: taskEventTick[selectedTaskId] || 0,
         }) : null,
       ),
     );
   }
 
+  // -------------------------------------------------------------------------
+  // Board switcher (multi-project)
+  // -------------------------------------------------------------------------
+
+  function BoardSwitcher(props) {
+    const list = props.boardList || [];
+    const current = list.find(function (b) { return b.slug === props.board; });
+    const currentName = current && current.name ? current.name : props.board;
+    const currentTotal = current ? current.total : 0;
+    const hasMultipleBoards = list.length > 1;
+
+    // Hide entirely when only the default board exists AND it's empty —
+    // single-project users never see boards UI unless they ask for it.
+    // We show the [+ New board] affordance as soon as any board has a
+    // task (so the user can discover multi-project before they need it)
+    // OR when any non-default board exists.
+    const totalAcrossAllBoards = list.reduce(function (n, b) { return n + (b.total || 0); }, 0);
+    const shouldShow = hasMultipleBoards || totalAcrossAllBoards > 0;
+    if (!shouldShow) {
+      return h("div", {
+        className: "hermes-kanban-boardswitcher-compact",
+        title: "Boards let you separate unrelated streams of work",
+      },
+        h(Button, {
+          onClick: props.onNewClick,
+          size: "sm",
+          className: "h-7 text-xs",
+        }, "+ New board"),
+      );
+    }
+
+    return h("div", { className: "hermes-kanban-boardswitcher" },
+      h("div", { className: "hermes-kanban-boardswitcher-inner" },
+        h("div", { className: "flex flex-col gap-0.5" },
+          h("div", { className: "text-[11px] uppercase tracking-wider text-muted-foreground" },
+            "Board"),
+          h("div", { className: "flex items-center gap-2" },
+            h(Select, Object.assign({
+              value: props.board,
+              className: "h-8 min-w-[220px]",
+              "aria-label": "Switch kanban board",
+            }, selectChangeHandler(function (v) { if (v) props.onSwitch(v); })),
+              list.map(function (b) {
+                const label = b.total > 0
+                  ? `${b.name || b.slug} · ${b.total}`
+                  : (b.name || b.slug);
+                return h(SelectOption, { key: b.slug, value: b.slug }, label);
+              }),
+            ),
+            h("span", { className: "text-xs text-muted-foreground" },
+              `${currentTotal || 0} task${currentTotal === 1 ? "" : "s"}`),
+          ),
+        ),
+        h("div", { className: "flex-1" }),
+        h(Button, {
+          onClick: props.onNewClick,
+          size: "sm",
+          className: "h-8",
+        }, "+ New board"),
+        props.board !== "default"
+          ? h(Button, {
+            onClick: function () {
+              const msg =
+                `Archive board '${currentName}'? ` +
+                `It will be moved to boards/_archived/ so you can recover it later. ` +
+                `Tasks on this board will no longer appear anywhere in the UI.`;
+              if (window.confirm(msg)) props.onDeleteBoard(props.board);
+            },
+            size: "sm",
+            className: "h-8",
+            title: "Archive this board",
+          }, "Archive")
+          : null,
+      ),
+    );
+  }
+
+  function NewBoardDialog(props) {
+    const [slug, setSlug] = useState("");
+    const [name, setName] = useState("");
+    const [description, setDescription] = useState("");
+    const [icon, setIcon] = useState("");
+    const [switchTo, setSwitchTo] = useState(true);
+    const [submitting, setSubmitting] = useState(false);
+    const [err, setErr] = useState(null);
+
+    // Auto-derive a name from the slug if the user hasn't typed one.
+    const autoName = useMemo(function () {
+      if (!slug) return "";
+      return slug.replace(/[-_]+/g, " ")
+        .split(" ")
+        .filter(Boolean)
+        .map(function (w) { return w[0].toUpperCase() + w.slice(1); })
+        .join(" ");
+    }, [slug]);
+
+    function onSubmit(ev) {
+      if (ev) ev.preventDefault();
+      if (!slug.trim()) { setErr("slug is required"); return; }
+      setSubmitting(true);
+      setErr(null);
+      props.onCreate({
+        slug: slug.trim(),
+        name: name.trim() || autoName || undefined,
+        description: description.trim() || undefined,
+        icon: icon.trim() || undefined,
+        switch: switchTo,
+      }).catch(function (e) {
+        setErr(String(e && e.message ? e.message : e));
+        setSubmitting(false);
+      });
+    }
+
+    return h("div", {
+      className: "hermes-kanban-dialog-backdrop",
+      onClick: function (e) { if (e.target === e.currentTarget) props.onCancel(); },
+    },
+      h("form", {
+        className: "hermes-kanban-dialog",
+        onSubmit: onSubmit,
+      },
+        h("div", { className: "hermes-kanban-dialog-title" }, "New board"),
+        h("div", { className: "text-xs text-muted-foreground mb-2" },
+          "Boards let you separate unrelated streams of work — one per project, repo, or domain. Workers on one board never see another board's tasks."),
+        h("div", { className: "flex flex-col gap-3" },
+          h("div", { className: "flex flex-col gap-1" },
+            h(Label, { className: "text-xs" }, "Slug ",
+              h("span", { className: "text-muted-foreground" },
+                "— lowercase, hyphens, e.g. atm10-server")),
+            h(Input, {
+              value: slug,
+              onChange: function (e) { setSlug(e.target.value.toLowerCase().replace(/[^a-z0-9\-_]/g, "-")); },
+              placeholder: "atm10-server",
+              autoFocus: true,
+              className: "h-8",
+            }),
+          ),
+          h("div", { className: "flex flex-col gap-1" },
+            h(Label, { className: "text-xs" }, "Display name ",
+              h("span", { className: "text-muted-foreground" }, "(optional)")),
+            h(Input, {
+              value: name,
+              onChange: function (e) { setName(e.target.value); },
+              placeholder: autoName || "Display name",
+              className: "h-8",
+            }),
+          ),
+          h("div", { className: "flex flex-col gap-1" },
+            h(Label, { className: "text-xs" }, "Description ",
+              h("span", { className: "text-muted-foreground" }, "(optional)")),
+            h(Input, {
+              value: description,
+              onChange: function (e) { setDescription(e.target.value); },
+              placeholder: "What goes on this board?",
+              className: "h-8",
+            }),
+          ),
+          h("div", { className: "flex flex-col gap-1" },
+            h(Label, { className: "text-xs" }, "Icon ",
+              h("span", { className: "text-muted-foreground" }, "(single character or emoji)")),
+            h(Input, {
+              value: icon,
+              onChange: function (e) { setIcon(e.target.value.slice(0, 4)); },
+              placeholder: "📦",
+              className: "h-8 w-24",
+            }),
+          ),
+          h("label", { className: "flex items-center gap-2 text-xs" },
+            h("input", {
+              type: "checkbox",
+              checked: switchTo,
+              onChange: function (e) { setSwitchTo(e.target.checked); },
+            }),
+            "Switch to this board after creating it",
+          ),
+        ),
+        err ? h("div", { className: "text-xs text-destructive mt-2" }, err) : null,
+        h("div", { className: "hermes-kanban-dialog-actions" },
+          h(Button, {
+            type: "button",
+            onClick: props.onCancel,
+            size: "sm",
+            disabled: submitting,
+          }, "Cancel"),
+          h(Button, {
+            type: "submit",
+            size: "sm",
+            disabled: submitting || !slug.trim(),
+          }, submitting ? "Creating…" : "Create board"),
+        ),
+      ),
+    );
+  }
+
   // -------------------------------------------------------------------------
   // Toolbar
   // -------------------------------------------------------------------------
@@ -555,11 +883,10 @@
       ),
       h("div", { className: "flex flex-col gap-1" },
         h(Label, { className: "text-xs text-muted-foreground" }, "Tenant"),
-        h(Select, {
+        h(Select, Object.assign({
           value: props.tenantFilter,
-          onChange: function (e) { props.setTenantFilter(e.target.value); },
           className: "h-8",
-        },
+        }, selectChangeHandler(props.setTenantFilter)),
           h(SelectOption, { value: "" }, "All tenants"),
           tenants.map(function (t) {
             return h(SelectOption, { key: t, value: t }, t);
@@ -568,11 +895,10 @@
       ),
       h("div", { className: "flex flex-col gap-1" },
         h(Label, { className: "text-xs text-muted-foreground" }, "Assignee"),
-        h(Select, {
+        h(Select, Object.assign({
           value: props.assigneeFilter,
-          onChange: function (e) { props.setAssigneeFilter(e.target.value); },
           className: "h-8",
-        },
+        }, selectChangeHandler(props.setAssigneeFilter)),
           h(SelectOption, { value: "" }, "All profiles"),
           assignees.map(function (a) {
             return h(SelectOption, { key: a, value: a }, a);
@@ -919,6 +1245,12 @@
     const [priority, setPriority] = useState(0);
     const [parent, setParent] = useState("");
     const [skills, setSkills] = useState("");
+    // Workspace controls. `scratch` (default) ignores path; `worktree` optionally
+    // takes a path (dispatcher derives one from the assignee profile otherwise);
+    // `dir` requires a path. Backend enforces the rule — we only hide/show the
+    // input here to save vertical space in the common `scratch` case.
+    const [workspaceKind, setWorkspaceKind] = useState("scratch");
+    const [workspacePath, setWorkspacePath] = useState("");
 
     const submit = function () {
       const trimmed = title.trim();
@@ -938,10 +1270,23 @@
         .map(function (s) { return s.trim(); })
         .filter(function (s) { return s.length > 0; });
       if (skillList.length > 0) body.skills = skillList;
+      // Only send workspace_kind when it's non-default. Keeps the request
+      // shape small and interoperable with older dispatcher versions.
+      if (workspaceKind && workspaceKind !== "scratch") {
+        body.workspace_kind = workspaceKind;
+      }
+      const wpTrim = workspacePath.trim();
+      if (wpTrim) body.workspace_path = wpTrim;
       props.onSubmit(body);
       setTitle(""); setAssignee(""); setPriority(0); setParent(""); setSkills("");
+      setWorkspaceKind("scratch"); setWorkspacePath("");
     };
 
+    const showPathInput = workspaceKind !== "scratch";
+    const pathPlaceholder = workspaceKind === "dir"
+      ? "workspace path (required, e.g. ~/projects/my-app)"
+      : "workspace path (optional, derived from assignee if blank)";
+
     return h("div", { className: "hermes-kanban-inline-create" },
       h(Input, {
         value: title,
@@ -978,6 +1323,24 @@
         title: "Force-load these skills into the worker (in addition to the built-in kanban-worker).",
         className: "h-7 text-xs",
       }),
+      h("div", { className: "flex gap-2" },
+        h(Select, {
+          value: workspaceKind,
+          onChange: function (e) { setWorkspaceKind(e.target.value); },
+          title: "scratch: isolated temp dir (default). worktree: git worktree on the assignee profile. dir: exact path (required below).",
+          className: "h-7 text-xs w-28",
+        },
+          h(SelectOption, { value: "scratch" }, "scratch"),
+          h(SelectOption, { value: "worktree" }, "worktree"),
+          h(SelectOption, { value: "dir" }, "dir"),
+        ),
+        showPathInput ? h(Input, {
+          value: workspacePath,
+          onChange: function (e) { setWorkspacePath(e.target.value); },
+          placeholder: pathPlaceholder,
+          className: "h-7 text-xs flex-1",
+        }) : null,
+      ),
       h(Select, {
         value: parent,
         onChange: function (e) { setParent(e.target.value); },
@@ -1012,18 +1375,33 @@
     const [err, setErr] = useState(null);
     const [newComment, setNewComment] = useState("");
     const [editing, setEditing] = useState(false);
+    // Home-channel notification toggles. homeChannels is the list of platforms
+    // the user has a /sethome on; each entry has a `subscribed` bool telling
+    // us whether this task is currently subscribed via that platform's home.
+    const [homeChannels, setHomeChannels] = useState([]);
+    const [homeBusy, setHomeBusy] = useState({});
+    const boardSlug = props.boardSlug;
 
     const load = useCallback(function () {
-      return SDK.fetchJSON(`${API}/tasks/${encodeURIComponent(props.taskId)}`)
+      return SDK.fetchJSON(withBoard(`${API}/tasks/${encodeURIComponent(props.taskId)}`, boardSlug))
         .then(function (d) { setData(d); setErr(null); })
         .catch(function (e) { setErr(String(e.message || e)); })
         .finally(function () { setLoading(false); });
-    }, [props.taskId]);
+    }, [props.taskId, boardSlug]);
+
+    const loadHomeChannels = useCallback(function () {
+      const qs = new URLSearchParams({ task_id: props.taskId });
+      const url = withBoard(`${API}/home-channels?${qs}`, boardSlug);
+      return SDK.fetchJSON(url)
+        .then(function (d) { setHomeChannels(d.home_channels || []); })
+        .catch(function () { /* silent — endpoint optional on older gateways */ });
+    }, [props.taskId, boardSlug]);
 
     // Reload when the WS stream reports new events for this task id
     // (completion, block, crash, etc. — anything that'd make the drawer
     // show stale data if we only loaded on mount).
     useEffect(function () { load(); }, [load, props.eventTick]);
+    useEffect(function () { loadHomeChannels(); }, [loadHomeChannels]);
     useEffect(function () {
       function onKey(e) { if (e.key === "Escape" && !editing) props.onClose(); }
       window.addEventListener("keydown", onKey);
@@ -1033,7 +1411,7 @@
     const handleComment = function () {
       const body = newComment.trim();
       if (!body) return;
-      SDK.fetchJSON(`${API}/tasks/${encodeURIComponent(props.taskId)}/comments`, {
+      SDK.fetchJSON(withBoard(`${API}/tasks/${encodeURIComponent(props.taskId)}/comments`, boardSlug), {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({ body }),
@@ -1048,7 +1426,7 @@
       if (opts && opts.confirm && !window.confirm(opts.confirm)) {
         return Promise.resolve();
       }
-      return SDK.fetchJSON(`${API}/tasks/${encodeURIComponent(props.taskId)}`, {
+      return SDK.fetchJSON(withBoard(`${API}/tasks/${encodeURIComponent(props.taskId)}`, boardSlug), {
         method: "PATCH",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify(patch),
@@ -1056,7 +1434,7 @@
     };
 
     const addLink = function (parentId) {
-      return SDK.fetchJSON(`${API}/links`, {
+      return SDK.fetchJSON(withBoard(`${API}/links`, boardSlug), {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({ parent_id: parentId, child_id: props.taskId }),
@@ -1065,12 +1443,12 @@
     };
     const removeLink = function (parentId) {
       const qs = new URLSearchParams({ parent_id: parentId, child_id: props.taskId });
-      return SDK.fetchJSON(`${API}/links?${qs}`, { method: "DELETE" })
+      return SDK.fetchJSON(withBoard(`${API}/links?${qs}`, boardSlug), { method: "DELETE" })
         .then(function () { load(); props.onRefresh(); })
         .catch(function (e) { setErr(String(e.message || e)); });
     };
     const addChild = function (childId) {
-      return SDK.fetchJSON(`${API}/links`, {
+      return SDK.fetchJSON(withBoard(`${API}/links`, boardSlug), {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({ parent_id: props.taskId, child_id: childId }),
@@ -1079,11 +1457,48 @@
     };
     const removeChild = function (childId) {
       const qs = new URLSearchParams({ parent_id: props.taskId, child_id: childId });
-      return SDK.fetchJSON(`${API}/links?${qs}`, { method: "DELETE" })
+      return SDK.fetchJSON(withBoard(`${API}/links?${qs}`, boardSlug), { method: "DELETE" })
         .then(function () { load(); props.onRefresh(); })
         .catch(function (e) { setErr(String(e.message || e)); });
     };
 
+    const toggleHomeSubscription = function (platform, currentlySubscribed) {
+      // Optimistic flip + busy flag to keep double-clicks idempotent.
+      setHomeBusy(function (b) { return Object.assign({}, b, { [platform]: true }); });
+      setHomeChannels(function (list) {
+        return list.map(function (h) {
+          return h.platform === platform
+            ? Object.assign({}, h, { subscribed: !currentlySubscribed })
+            : h;
+        });
+      });
+      const method = currentlySubscribed ? "DELETE" : "POST";
+      const url = withBoard(
+        `${API}/tasks/${encodeURIComponent(props.taskId)}/home-subscribe/${encodeURIComponent(platform)}`,
+        boardSlug,
+      );
+      return SDK.fetchJSON(url, { method: method })
+        .then(function () { return loadHomeChannels(); })
+        .catch(function (e) {
+          // Revert optimistic flip on failure.
+          setHomeChannels(function (list) {
+            return list.map(function (h) {
+              return h.platform === platform
+                ? Object.assign({}, h, { subscribed: currentlySubscribed })
+                : h;
+            });
+          });
+          setErr(String(e.message || e));
+        })
+        .finally(function () {
+          setHomeBusy(function (b) {
+            const next = Object.assign({}, b);
+            delete next[platform];
+            return next;
+          });
+        });
+    };
+
     return h("div", { className: "hermes-kanban-drawer-shade", onClick: props.onClose },
       h("div", {
         className: "hermes-kanban-drawer",
@@ -1104,11 +1519,15 @@
           data, editing, setEditing,
           renderMarkdown: props.renderMarkdown,
           allTasks: props.allTasks,
+          boardSlug: boardSlug,
           onPatch: doPatch,
           onAddParent: addLink,
           onRemoveParent: removeLink,
           onAddChild: addChild,
           onRemoveChild: removeChild,
+          homeChannels: homeChannels,
+          homeBusy: homeBusy,
+          onToggleHomeSub: toggleHomeSubscription,
         }) : null,
         data ? h("div", { className: "hermes-kanban-drawer-comment-row" },
           h(Input, {
@@ -1170,6 +1589,11 @@
         t.created_by ? h(MetaRow, { label: "Created by", value: t.created_by }) : null,
       ),
       h(StatusActions, { task: t, onPatch: props.onPatch }),
+      h(HomeSubsSection, {
+        homeChannels: props.homeChannels || [],
+        homeBusy: props.homeBusy || {},
+        onToggle: props.onToggleHomeSub,
+      }),
       h(BodyEditor, {
         task: t,
         renderMarkdown: props.renderMarkdown,
@@ -1216,7 +1640,7 @@
           );
         }),
       ),
-      h(WorkerLogSection, { taskId: t.id }),
+      h(WorkerLogSection, { taskId: t.id, boardSlug: props.boardSlug }),
       h(RunHistorySection, { runs: props.data.runs || [] }),
     );
   }
@@ -1287,10 +1711,10 @@
     const [state, setState] = useState({ loading: false, data: null, err: null });
     const load = useCallback(function () {
       setState({ loading: true, data: null, err: null });
-      SDK.fetchJSON(`${API}/tasks/${encodeURIComponent(props.taskId)}/log?tail=100000`)
+      SDK.fetchJSON(withBoard(`${API}/tasks/${encodeURIComponent(props.taskId)}/log?tail=100000`, props.boardSlug))
         .then(function (d) { setState({ loading: false, data: d, err: null }); })
         .catch(function (e) { setState({ loading: false, data: null, err: String(e.message || e) }); });
-    }, [props.taskId]);
+    }, [props.taskId, props.boardSlug]);
 
     // Auto-load when the section mounts; the user opened the drawer so the
     // cost is one small HTTP round-trip.
@@ -1572,7 +1996,10 @@
     return h("div", { className: "hermes-kanban-actions" },
       b("→ triage",  { status: "triage" },   t.status !== "triage"),
       b("→ ready",   { status: "ready" },    t.status !== "ready"),
-      b("→ running", { status: "running" },  t.status !== "running"),
+      // No direct → running button: /tasks/:id PATCH rejects status=running
+      // with 400 (issue #19535). Tasks enter running only through the
+      // dispatcher's claim_task path, which atomically creates the run row,
+      // claim lock, and worker process metadata.
       b("Block",     { status: "blocked" },
         t.status === "running" || t.status === "ready",
         DESTRUCTIVE_TRANSITIONS.blocked),
@@ -1585,6 +2012,43 @@
     );
   }
 
+
+  // One toggle per gateway platform the user has a home channel set on
+  // (telegram, discord, slack, etc.). Toggling on creates a kanban_notify_subs
+  // row routed to that platform's home; toggling off removes it. Nothing
+  // renders when no platforms have a home configured — this section stays
+  // invisible for users who haven't set one up.
+  function HomeSubsSection(props) {
+    const channels = props.homeChannels || [];
+    if (channels.length === 0) return null;
+    const busy = props.homeBusy || {};
+    return h("div", { className: "hermes-kanban-section" },
+      h("div", { className: "hermes-kanban-section-head" },
+        "Notify home channels"),
+      h("div", { className: "hermes-kanban-home-subs" },
+        channels.map(function (hc) {
+          const isBusy = !!busy[hc.platform];
+          const label = hc.subscribed ? "✓ " + hc.platform : hc.platform;
+          const title = hc.subscribed
+            ? `Sending updates to ${hc.name} (${hc.chat_id}${hc.thread_id ? " / " + hc.thread_id : ""}). Click to stop.`
+            : `Send completed / blocked / gave_up notifications to ${hc.name} (${hc.chat_id}${hc.thread_id ? " / " + hc.thread_id : ""}).`;
+          return h(Button, {
+            key: hc.platform,
+            size: "sm",
+            title: title,
+            disabled: isBusy || !props.onToggle,
+            onClick: function () {
+              if (props.onToggle) props.onToggle(hc.platform, hc.subscribed);
+            },
+            className: hc.subscribed
+              ? "hermes-kanban-home-sub hermes-kanban-home-sub--on"
+              : "hermes-kanban-home-sub",
+          }, label);
+        })
+      )
+    );
+  }
+
   // -------------------------------------------------------------------------
   // Register
   // -------------------------------------------------------------------------

plugins/kanban/dashboard/dist/style.css

@@ -268,7 +268,7 @@
 }
 
 .hermes-kanban-drawer {
-  width: min(480px, 92vw);
+  width: min(var(--hermes-kanban-drawer-width, 640px), 92vw);
   height: 100vh;
   background: var(--color-card);
   border-left: 1px solid var(--color-border);
@@ -334,7 +334,7 @@
 .hermes-kanban-meta-row {
   display: flex;
   gap: 0.5rem;
-  font-size: 0.72rem;
+  font-size: 0.8rem;
 }
 .hermes-kanban-meta-label {
   width: 92px;
@@ -351,6 +351,30 @@
   gap: 0.3rem;
 }
 
+/* ---- Home channel subscription toggles (per-platform, per-task) ----- */
+
+.hermes-kanban-home-subs {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.3rem;
+}
+.hermes-kanban-home-sub {
+  font-family: var(--font-mono, ui-monospace, monospace);
+  text-transform: lowercase;
+  letter-spacing: 0.02em;
+}
+.hermes-kanban-home-sub--on {
+  /* Subscribed toggle — use a strong ring-colored accent so the on/off
+   * distinction reads at a glance, not just from the ✓ prefix. Border +
+   * filled background + bolder weight keep the state obvious across
+   * themes (tested on default teal and NERV orange). */
+  border-color: var(--color-ring);
+  background: color-mix(in srgb, var(--color-ring) 32%, transparent);
+  color: var(--color-foreground);
+  font-weight: 600;
+  box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--color-ring) 40%, transparent);
+}
+
 .hermes-kanban-section {
   display: flex;
   flex-direction: column;
@@ -367,14 +391,15 @@
 
 .hermes-kanban-pre {
   margin: 0;
-  padding: 0.45rem 0.55rem;
+  padding: 0.5rem 0.6rem;
   white-space: pre-wrap;
   word-break: break-word;
   background: color-mix(in srgb, var(--color-foreground) 4%, transparent);
   border: 1px solid var(--color-border);
   border-radius: var(--radius-sm, 0.25rem);
   font-family: var(--font-mono, ui-monospace, monospace);
-  font-size: 0.72rem;
+  font-size: 0.8rem;
+  line-height: 1.5;
   color: var(--color-foreground);
 }
 
@@ -605,8 +630,8 @@
 /* ---- Markdown rendering -------------------------------------------- */
 
 .hermes-kanban-md {
-  font-size: 0.8rem;
-  line-height: 1.55;
+  font-size: 0.85rem;
+  line-height: 1.6;
   color: var(--color-foreground);
 }
 .hermes-kanban-md p  { margin: 0.25rem 0; }
@@ -632,15 +657,22 @@
 }
 .hermes-kanban-md code {
   font-family: var(--font-mono, ui-monospace, monospace);
-  font-size: 0.75rem;
+  font-size: 0.8rem;
   padding: 0.05rem 0.3rem;
   background: color-mix(in srgb, var(--color-foreground) 8%, transparent);
   border-radius: 3px;
+  color: inherit;
 }
+/* Fenced code block. Set a visible background even when --color-foreground
+ * is empty (color-mix falls through to transparent in that case), and force
+ * color: inherit so the text tracks the drawer foreground rather than the
+ * UA default on <code> elements — otherwise themes that don't set
+ * --color-foreground leave code text rendering near-black on dark themes
+ * (see issue #18576). */
 .hermes-kanban-md-code {
   margin: 0.35rem 0;
   padding: 0.5rem 0.6rem;
-  background: color-mix(in srgb, var(--color-foreground) 5%, transparent);
+  background: color-mix(in srgb, currentColor 6%, transparent);
   border: 1px solid var(--color-border);
   border-radius: var(--radius-sm, 0.25rem);
   overflow-x: auto;
@@ -648,8 +680,9 @@
 .hermes-kanban-md-code code {
   background: transparent;
   padding: 0;
-  font-size: 0.75rem;
+  font-size: 0.8rem;
   white-space: pre;
+  color: inherit;
 }
 .hermes-kanban-md strong { font-weight: 600; }
 
@@ -684,11 +717,11 @@
 /* ---- Worker log pane ------------------------------------------------ */
 
 .hermes-kanban-log {
-  max-height: 340px;
+  max-height: 360px;
   overflow: auto;
   white-space: pre;
-  font-size: 0.7rem;
-  line-height: 1.45;
+  font-size: 0.78rem;
+  line-height: 1.5;
 }
 
 
@@ -739,7 +772,8 @@
   color: var(--color-muted-foreground);
 }
 .hermes-kanban-run-summary {
-  font-size: 0.75rem;
+  font-size: 0.82rem;
+  line-height: 1.5;
   padding: 0.2rem 0 0;
   color: var(--color-foreground);
 }
@@ -751,10 +785,65 @@
 }
 .hermes-kanban-run-meta {
   display: block;
-  font-size: 0.65rem;
+  font-size: 0.72rem;
+  line-height: 1.5;
   padding: 0.15rem 0 0;
   color: var(--color-muted-foreground);
   white-space: pre-wrap;
   word-break: break-word;
   font-family: var(--font-mono, ui-monospace, monospace);
 }
+
+/* -------------------------------------------------------------------------
+   Multi-project: board switcher + create-board dialog
+   ------------------------------------------------------------------------- */
+.hermes-kanban-boardswitcher {
+  border: 1px solid var(--color-border, rgba(120, 120, 140, 0.25));
+  border-radius: 0.5rem;
+  padding: 0.6rem 0.85rem;
+  background: var(--color-card-subtle, rgba(255, 255, 255, 0.02));
+}
+.hermes-kanban-boardswitcher-inner {
+  display: flex;
+  align-items: flex-end;
+  gap: 0.75rem;
+  flex-wrap: wrap;
+}
+.hermes-kanban-boardswitcher-compact {
+  display: flex;
+  justify-content: flex-end;
+  padding: 0 0.25rem;
+}
+.hermes-kanban-dialog-backdrop {
+  position: fixed;
+  inset: 0;
+  background: rgba(8, 10, 16, 0.55);
+  backdrop-filter: blur(2px);
+  z-index: 60;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+.hermes-kanban-dialog {
+  background: var(--color-card, #121421);
+  color: var(--color-foreground);
+  border: 1px solid var(--color-border, rgba(120, 120, 140, 0.25));
+  border-radius: 0.5rem;
+  padding: 1.1rem 1.2rem 1rem;
+  width: 28rem;
+  max-width: calc(100vw - 2rem);
+  max-height: calc(100vh - 3rem);
+  overflow: auto;
+  box-shadow: 0 18px 40px rgba(0, 0, 0, 0.5);
+}
+.hermes-kanban-dialog-title {
+  font-size: 1rem;
+  font-weight: 600;
+  margin-bottom: 0.25rem;
+}
+.hermes-kanban-dialog-actions {
+  display: flex;
+  justify-content: flex-end;
+  gap: 0.5rem;
+  margin-top: 1rem;
+}

plugins/kanban/dashboard/plugin_api.py

@@ -72,19 +72,45 @@ def _check_ws_token(provided: Optional[str]) -> bool:
     return hmac.compare_digest(str(provided), str(expected))
 
 
-def _conn():
+def _resolve_board(board: Optional[str]) -> Optional[str]:
+    """Validate and normalise a board slug from a query param.
+
+    Raises :class:`HTTPException` 400 on malformed slugs so the browser
+    sees a clean error instead of a 500. Returns the normalised slug,
+    or ``None`` when the caller omitted the param (which then falls
+    through to the active board inside ``kb.connect()``).
+    """
+    if board is None or board == "":
+        return None
+    try:
+        normed = kanban_db._normalize_board_slug(board)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+    if normed and normed != kanban_db.DEFAULT_BOARD and not kanban_db.board_exists(normed):
+        raise HTTPException(
+            status_code=404,
+            detail=f"board {normed!r} does not exist",
+        )
+    return normed
+
+
+def _conn(board: Optional[str] = None):
     """Open a kanban_db connection, creating the schema on first use.
 
     Every handler that mutates the DB goes through this so the plugin
     self-heals on a fresh install (no user-visible "no such table"
     error if somebody hits POST /tasks before GET /board).
     ``init_db`` is idempotent.
+
+    ``board`` is the query-param slug (already normalised by
+    :func:`_resolve_board`). When ``None`` the active board is used
+    via the resolution chain (env var → ``current`` file → ``default``).
     """
     try:
-        kanban_db.init_db()
+        kanban_db.init_db(board=board)
     except Exception as exc:
         log.warning("kanban init_db failed: %s", exc)
-    return kanban_db.connect()
+    return kanban_db.connect(board=board)
 
 
 # ---------------------------------------------------------------------------
@@ -177,13 +203,19 @@ def _links_for(conn: sqlite3.Connection, task_id: str) -> dict[str, list[str]]:
 def get_board(
     tenant: Optional[str] = Query(None, description="Filter to a single tenant"),
     include_archived: bool = Query(False),
+    board: Optional[str] = Query(None, description="Kanban board slug (omit for current)"),
 ):
     """Return the full board grouped by status column.
 
     ``_conn()`` auto-initializes ``kanban.db`` on first call so a fresh
     install doesn't surface a "failed to load" error on the plugin tab.
+
+    ``board`` selects which board to read from. Omitting it falls
+    through to the active board (``HERMES_KANBAN_BOARD`` env → on-disk
+    ``current`` pointer → ``default``).
     """
-    conn = _conn()
+    board = _resolve_board(board)
+    conn = _conn(board=board)
     try:
         tasks = kanban_db.list_tasks(
             conn, tenant=tenant, include_archived=include_archived
@@ -274,8 +306,9 @@ def get_board(
 # ---------------------------------------------------------------------------
 
 @router.get("/tasks/{task_id}")
-def get_task(task_id: str):
-    conn = _conn()
+def get_task(task_id: str, board: Optional[str] = Query(None)):
+    board = _resolve_board(board)
+    conn = _conn(board=board)
     try:
         task = kanban_db.get_task(conn, task_id)
         if task is None:
@@ -311,8 +344,9 @@ class CreateTaskBody(BaseModel):
 
 
 @router.post("/tasks")
-def create_task(payload: CreateTaskBody):
-    conn = _conn()
+def create_task(payload: CreateTaskBody, board: Optional[str] = Query(None)):
+    board = _resolve_board(board)
+    conn = _conn(board=board)
     try:
         task_id = kanban_db.create_task(
             conn,
@@ -373,8 +407,9 @@ class UpdateTaskBody(BaseModel):
 
 
 @router.patch("/tasks/{task_id}")
-def update_task(task_id: str, payload: UpdateTaskBody):
-    conn = _conn()
+def update_task(task_id: str, payload: UpdateTaskBody, board: Optional[str] = Query(None)):
+    board = _resolve_board(board)
+    conn = _conn(board=board)
     try:
         task = kanban_db.get_task(conn, task_id)
         if task is None:
@@ -414,7 +449,12 @@ def update_task(task_id: str, payload: UpdateTaskBody):
                     ok = _set_status_direct(conn, task_id, "ready")
             elif s == "archived":
                 ok = kanban_db.archive_task(conn, task_id)
-            elif s in ("todo", "running", "triage"):
+            elif s == "running":
+                raise HTTPException(
+                    status_code=400,
+                    detail="Cannot set status to 'running' directly; use the dispatcher/claim path",
+                )
+            elif s in ("todo", "triage"):
                 ok = _set_status_direct(conn, task_id, s)
             else:
                 raise HTTPException(status_code=400, detail=f"unknown status: {s}")
@@ -527,10 +567,11 @@ class CommentBody(BaseModel):
 
 
 @router.post("/tasks/{task_id}/comments")
-def add_comment(task_id: str, payload: CommentBody):
+def add_comment(task_id: str, payload: CommentBody, board: Optional[str] = Query(None)):
     if not payload.body.strip():
         raise HTTPException(status_code=400, detail="body is required")
-    conn = _conn()
+    board = _resolve_board(board)
+    conn = _conn(board=board)
     try:
         if kanban_db.get_task(conn, task_id) is None:
             raise HTTPException(status_code=404, detail=f"task {task_id} not found")
@@ -552,8 +593,9 @@ class LinkBody(BaseModel):
 
 
 @router.post("/links")
-def add_link(payload: LinkBody):
-    conn = _conn()
+def add_link(payload: LinkBody, board: Optional[str] = Query(None)):
+    board = _resolve_board(board)
+    conn = _conn(board=board)
     try:
         kanban_db.link_tasks(conn, payload.parent_id, payload.child_id)
         return {"ok": True}
@@ -564,8 +606,13 @@ def add_link(payload: LinkBody):
 
 
 @router.delete("/links")
-def delete_link(parent_id: str = Query(...), child_id: str = Query(...)):
-    conn = _conn()
+def delete_link(
+    parent_id: str = Query(...),
+    child_id: str = Query(...),
+    board: Optional[str] = Query(None),
+):
+    board = _resolve_board(board)
+    conn = _conn(board=board)
     try:
         ok = kanban_db.unlink_tasks(conn, parent_id, child_id)
         return {"ok": bool(ok)}
@@ -586,7 +633,7 @@ class BulkTaskBody(BaseModel):
 
 
 @router.post("/tasks/bulk")
-def bulk_update(payload: BulkTaskBody):
+def bulk_update(payload: BulkTaskBody, board: Optional[str] = Query(None)):
     """Apply the same patch to every id in ``payload.ids``.
 
     This is an *independent* iteration — per-task failures don't abort
@@ -596,7 +643,8 @@ def bulk_update(payload: BulkTaskBody):
     if not ids:
         raise HTTPException(status_code=400, detail="ids is required")
     results: list[dict] = []
-    conn = _conn()
+    board = _resolve_board(board)
+    conn = _conn(board=board)
     try:
         for tid in ids:
             entry: dict[str, Any] = {"id": tid, "ok": True}
@@ -685,19 +733,169 @@ def get_config():
     }
 
 
+# ---------------------------------------------------------------------------
+# Home-channel subscriptions (per-task, per-platform toggles)
+# ---------------------------------------------------------------------------
+#
+# Home channels are a first-class gateway concept — each configured platform
+# can have exactly one (chat_id, thread_id, name) it considers "home". The
+# dashboard surfaces these as per-task toggles so a user can opt a specific
+# task into receiving terminal notifications (completed / blocked / gave_up)
+# at their telegram/discord/slack home, without touching the CLI.
+#
+# The wire format mirrors kanban_db.add_notify_sub — (task_id, platform,
+# chat_id, thread_id) — so toggle-on creates exactly the same row the
+# `/kanban create` slash command would, and the existing gateway notifier
+# watcher delivers events without any additional plumbing.
+
+
+def _configured_home_channels() -> list[dict]:
+    """Return every platform that has a home_channel set, fully hydrated.
+
+    Reads the live GatewayConfig so env-var overlays (``TELEGRAM_HOME_CHANNEL``
+    etc.) are honored alongside config.yaml. Returns platforms in a stable
+    order and drops platforms without a home.
+    """
+    try:
+        from gateway.config import load_gateway_config
+    except Exception:
+        return []
+    try:
+        gw_cfg = load_gateway_config()
+    except Exception:
+        return []
+    result: list[dict] = []
+    for platform, pcfg in gw_cfg.platforms.items():
+        if not pcfg or not pcfg.home_channel:
+            continue
+        hc = pcfg.home_channel
+        result.append({
+            "platform": platform.value,
+            "chat_id": hc.chat_id,
+            "thread_id": hc.thread_id or "",
+            "name": hc.name or "Home",
+        })
+    # Stable order for deterministic UI — platform name alphabetical.
+    result.sort(key=lambda r: r["platform"])
+    return result
+
+
+def _home_sub_matches(sub: dict, home: dict) -> bool:
+    """True if a notify_subs row corresponds to the given home channel."""
+    return (
+        sub.get("platform") == home["platform"]
+        and str(sub.get("chat_id", "")) == str(home["chat_id"])
+        and str(sub.get("thread_id") or "") == str(home["thread_id"] or "")
+    )
+
+
+@router.get("/home-channels")
+def get_home_channels(
+    task_id: Optional[str] = Query(None),
+    board: Optional[str] = Query(None),
+):
+    """List every platform with a home channel, plus whether *task_id*
+    (if given) is currently subscribed to that home.
+
+    When ``task_id`` is omitted, every entry's ``subscribed`` is ``false``
+    — useful for the "no task selected" state of the UI.
+    """
+    homes = _configured_home_channels()
+    subscribed_homes: set[tuple[str, str, str]] = set()
+    if task_id:
+        board = _resolve_board(board)
+        conn = _conn(board=board)
+        try:
+            subs = kanban_db.list_notify_subs(conn, task_id)
+        finally:
+            conn.close()
+        for sub in subs:
+            key = (
+                str(sub.get("platform") or ""),
+                str(sub.get("chat_id") or ""),
+                str(sub.get("thread_id") or ""),
+            )
+            subscribed_homes.add(key)
+    result = []
+    for home in homes:
+        key = (home["platform"], home["chat_id"], home["thread_id"])
+        result.append({**home, "subscribed": key in subscribed_homes})
+    return {"home_channels": result}
+
+
+@router.post("/tasks/{task_id}/home-subscribe/{platform}")
+def subscribe_home(task_id: str, platform: str, board: Optional[str] = Query(None)):
+    """Subscribe *task_id* to notifications routed to *platform*'s home channel.
+
+    Idempotent — re-subscribing is a no-op at the DB layer. 404 if the
+    platform has no home channel configured. 404 if the task doesn't exist.
+    """
+    homes = _configured_home_channels()
+    home = next((h for h in homes if h["platform"] == platform), None)
+    if not home:
+        raise HTTPException(
+            status_code=404,
+            detail=f"No home channel configured for platform {platform!r}. "
+                   f"Set one from the messenger via /sethome, or configure "
+                   f"gateway.platforms.{platform}.home_channel in config.yaml.",
+        )
+    board = _resolve_board(board)
+    conn = _conn(board=board)
+    try:
+        task = kanban_db.get_task(conn, task_id)
+        if task is None:
+            raise HTTPException(status_code=404, detail=f"task {task_id} not found")
+        kanban_db.add_notify_sub(
+            conn,
+            task_id=task_id,
+            platform=platform,
+            chat_id=home["chat_id"],
+            thread_id=home["thread_id"] or None,
+        )
+        return {"ok": True, "task_id": task_id, "home_channel": home}
+    finally:
+        conn.close()
+
+
+@router.delete("/tasks/{task_id}/home-subscribe/{platform}")
+def unsubscribe_home(task_id: str, platform: str, board: Optional[str] = Query(None)):
+    """Remove any notify subscription on *task_id* that matches *platform*'s home."""
+    homes = _configured_home_channels()
+    home = next((h for h in homes if h["platform"] == platform), None)
+    if not home:
+        raise HTTPException(
+            status_code=404,
+            detail=f"No home channel configured for platform {platform!r}.",
+        )
+    board = _resolve_board(board)
+    conn = _conn(board=board)
+    try:
+        kanban_db.remove_notify_sub(
+            conn,
+            task_id=task_id,
+            platform=platform,
+            chat_id=home["chat_id"],
+            thread_id=home["thread_id"] or None,
+        )
+        return {"ok": True, "task_id": task_id, "home_channel": home}
+    finally:
+        conn.close()
+
+
 # ---------------------------------------------------------------------------
 # Stats (per-profile / per-status counts + oldest-ready age)
 # ---------------------------------------------------------------------------
 
 @router.get("/stats")
-def get_stats():
+def get_stats(board: Optional[str] = Query(None)):
     """Per-status + per-assignee counts + oldest-ready age.
 
     Designed for the dashboard HUD and for router profiles that need to
     answer "is this specialist overloaded?" without scanning the whole
     board themselves.
     """
-    conn = _conn()
+    board = _resolve_board(board)
+    conn = _conn(board=board)
     try:
         return kanban_db.board_stats(conn)
     finally:
@@ -705,7 +903,7 @@ def get_stats():
 
 
 @router.get("/assignees")
-def get_assignees():
+def get_assignees(board: Optional[str] = Query(None)):
     """Known profiles + per-profile task counts.
 
     Returns the union of ``~/.hermes/profiles/*`` on disk and every
@@ -713,7 +911,8 @@ def get_assignees():
     this to populate its assignee dropdown so a freshly-created profile
     appears in the picker before it's been given any task.
     """
-    conn = _conn()
+    board = _resolve_board(board)
+    conn = _conn(board=board)
     try:
         return {"assignees": kanban_db.known_assignees(conn)}
     finally:
@@ -725,7 +924,11 @@ def get_assignees():
 # ---------------------------------------------------------------------------
 
 @router.get("/tasks/{task_id}/log")
-def get_task_log(task_id: str, tail: Optional[int] = Query(None, ge=1, le=2_000_000)):
+def get_task_log(
+    task_id: str,
+    tail: Optional[int] = Query(None, ge=1, le=2_000_000),
+    board: Optional[str] = Query(None),
+):
     """Return the worker's stdout/stderr log.
 
     ``tail`` caps the response size (bytes) so the dashboard drawer
@@ -734,15 +937,16 @@ def get_task_log(task_id: str, tail: Optional[int] = Query(None, ge=1, le=2_000_
     ``_rotate_worker_log`` — a single ``.log.1`` is kept, no further
     generations, so disk usage per task is bounded at ~4 MiB.
     """
-    conn = _conn()
+    board = _resolve_board(board)
+    conn = _conn(board=board)
     try:
         task = kanban_db.get_task(conn, task_id)
     finally:
         conn.close()
     if task is None:
         raise HTTPException(status_code=404, detail=f"task {task_id} not found")
-    content = kanban_db.read_worker_log(task_id, tail_bytes=tail)
-    log_path = kanban_db.worker_log_path(task_id)
+    content = kanban_db.read_worker_log(task_id, tail_bytes=tail, board=board)
+    log_path = kanban_db.worker_log_path(task_id, board=board)
     size = log_path.stat().st_size if log_path.exists() else 0
     return {
         "task_id": task_id,
@@ -760,11 +964,16 @@ def get_task_log(task_id: str, tail: Optional[int] = Query(None, ge=1, le=2_000_
 # ---------------------------------------------------------------------------
 
 @router.post("/dispatch")
-def dispatch(dry_run: bool = Query(False), max_n: int = Query(8, alias="max")):
-    conn = _conn()
+def dispatch(
+    dry_run: bool = Query(False),
+    max_n: int = Query(8, alias="max"),
+    board: Optional[str] = Query(None),
+):
+    board = _resolve_board(board)
+    conn = _conn(board=board)
     try:
         result = kanban_db.dispatch_once(
-            conn, dry_run=dry_run, max_spawn=max_n,
+            conn, dry_run=dry_run, max_spawn=max_n, board=board,
         )
         # DispatchResult is a dataclass.
         try:
@@ -775,6 +984,124 @@ def dispatch(dry_run: bool = Query(False), max_n: int = Query(8, alias="max")):
         conn.close()
 
 
+# ---------------------------------------------------------------------------
+# Boards CRUD (multi-project support)
+# ---------------------------------------------------------------------------
+
+class CreateBoardBody(BaseModel):
+    slug: str
+    name: Optional[str] = None
+    description: Optional[str] = None
+    icon: Optional[str] = None
+    color: Optional[str] = None
+    switch: bool = False
+
+
+class RenameBoardBody(BaseModel):
+    name: Optional[str] = None
+    description: Optional[str] = None
+    icon: Optional[str] = None
+    color: Optional[str] = None
+
+
+def _board_counts(slug: str) -> dict[str, int]:
+    """Return ``{status: count}`` for a board. Safe on an empty DB."""
+    try:
+        path = kanban_db.kanban_db_path(board=slug)
+        if not path.exists():
+            return {}
+        conn = kanban_db.connect(board=slug)
+        try:
+            rows = conn.execute(
+                "SELECT status, COUNT(*) AS n FROM tasks GROUP BY status"
+            ).fetchall()
+            return {r["status"]: int(r["n"]) for r in rows}
+        finally:
+            conn.close()
+    except Exception:
+        return {}
+
+
+@router.get("/boards")
+def list_boards(include_archived: bool = Query(False)):
+    """Return every board on disk with task counts and the active slug."""
+    boards = kanban_db.list_boards(include_archived=include_archived)
+    current = kanban_db.get_current_board()
+    for b in boards:
+        b["is_current"] = (b["slug"] == current)
+        b["counts"] = _board_counts(b["slug"])
+        b["total"] = sum(b["counts"].values())
+    return {"boards": boards, "current": current}
+
+
+@router.post("/boards")
+def create_board_endpoint(payload: CreateBoardBody):
+    """Create a new board. Idempotent — ``slug`` collision returns existing."""
+    try:
+        meta = kanban_db.create_board(
+            payload.slug,
+            name=payload.name,
+            description=payload.description,
+            icon=payload.icon,
+            color=payload.color,
+        )
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+    if payload.switch:
+        try:
+            kanban_db.set_current_board(meta["slug"])
+        except ValueError as exc:
+            raise HTTPException(status_code=400, detail=str(exc))
+    return {"board": meta, "current": kanban_db.get_current_board()}
+
+
+@router.patch("/boards/{slug}")
+def rename_board(slug: str, payload: RenameBoardBody):
+    """Update a board's display metadata (slug is immutable — create a new one to rename the directory)."""
+    try:
+        normed = kanban_db._normalize_board_slug(slug)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+    if not normed or not kanban_db.board_exists(normed):
+        raise HTTPException(status_code=404, detail=f"board {slug!r} does not exist")
+    meta = kanban_db.write_board_metadata(
+        normed,
+        name=payload.name,
+        description=payload.description,
+        icon=payload.icon,
+        color=payload.color,
+    )
+    return {"board": meta}
+
+
+@router.delete("/boards/{slug}")
+def delete_board(slug: str, delete: bool = Query(False, description="Hard-delete instead of archive")):
+    """Archive (default) or hard-delete a board."""
+    try:
+        res = kanban_db.remove_board(slug, archive=not delete)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+    return {"result": res, "current": kanban_db.get_current_board()}
+
+
+@router.post("/boards/{slug}/switch")
+def switch_board(slug: str):
+    """Persist ``slug`` as the active board for subsequent CLI / slash calls.
+
+    Dashboard users pick boards via a client-side ``localStorage`` — this
+    endpoint is for ``/kanban boards switch`` parity so gateway slash
+    commands and the CLI share the same current-board pointer.
+    """
+    try:
+        normed = kanban_db._normalize_board_slug(slug)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc))
+    if not normed or not kanban_db.board_exists(normed):
+        raise HTTPException(status_code=404, detail=f"board {slug!r} does not exist")
+    kanban_db.set_current_board(normed)
+    return {"current": normed}
+
+
 # ---------------------------------------------------------------------------
 # WebSocket: /events?since=<event_id>
 # ---------------------------------------------------------------------------
@@ -802,8 +1129,18 @@ async def stream_events(ws: WebSocket):
         except ValueError:
             cursor = 0
 
+        # Board selection — pinned at the WS handshake; re-subscribe to
+        # switch boards. Changing boards mid-stream would require
+        # reconciling two cursors, so the UI just opens a new WS on
+        # board change.
+        ws_board_raw = ws.query_params.get("board")
+        try:
+            ws_board = kanban_db._normalize_board_slug(ws_board_raw) if ws_board_raw else None
+        except ValueError:
+            ws_board = None
+
         def _fetch_new(cursor_val: int) -> tuple[int, list[dict]]:
-            conn = kanban_db.connect()
+            conn = kanban_db.connect(board=ws_board)
             try:
                 rows = conn.execute(
                     "SELECT id, task_id, run_id, kind, payload, created_at "

plugins/platforms/teams/adapter.py

@@ -509,7 +509,20 @@ class TeamsAdapter(BasePlatformAdapter):
 
         for chunk in chunks:
             try:
-                result = await self._app.send(chat_id, chunk)
+                if reply_to and reply_to.isdigit() and reply_to != "0":
+                    try:
+                        result = await self._app.reply(chat_id, reply_to, chunk)
+                    except Exception as reply_err:
+                        # Group chats 400 on threaded sends; the Teams SDK
+                        # doesn't expose typed HTTP errors, so fall back on
+                        # any exception and log for diagnostics.
+                        logger.debug(
+                            "Teams reply() failed, falling back to flat send: %s",
+                            reply_err,
+                        )
+                        result = await self._app.send(chat_id, chunk)
+                else:
+                    result = await self._app.send(chat_id, chunk)
                 last_message_id = getattr(result, "id", None)
             except Exception as e:
                 return SendResult(success=False, error=str(e), retryable=True)
@@ -592,6 +605,8 @@ def interactive_setup() -> None:
     from hermes_cli.config import (
         get_env_value,
         save_env_value,
+    )
+    from hermes_cli.cli_output import (
         prompt,
         prompt_yes_no,
         print_info,

pyproject.toml

@@ -139,6 +139,7 @@ py-modules = ["run_agent", "model_tools", "toolsets", "batch_runner", "trajector
 
 [tool.setuptools.package-data]
 hermes_cli = ["web_dist/**/*"]
+gateway = ["assets/**/*"]
 
 [tool.setuptools.packages.find]
 include = ["agent", "agent.*", "tools", "tools.*", "hermes_cli", "gateway", "gateway.*", "tui_gateway", "tui_gateway.*", "cron", "acp_adapter", "plugins", "plugins.*"]

run_agent.py

@@ -304,7 +304,8 @@ class IterationBudget:
 
     @property
     def used(self) -> int:
-        return self._used
+        with self._lock:
+            return self._used
 
     @property
     def remaining(self) -> int:
@@ -3611,7 +3612,7 @@ class AIAgent:
                     _parent_runtime = self._current_main_runtime()
                     review_agent = AIAgent(
                         model=self.model,
-                        max_iterations=8,
+                        max_iterations=16,
                         quiet_mode=True,
                         platform=self.platform,
                         provider=self.provider,
@@ -3629,6 +3630,14 @@ class AIAgent:
                     review_agent._user_profile_enabled = self._user_profile_enabled
                     review_agent._memory_nudge_interval = 0
                     review_agent._skill_nudge_interval = 0
+                    # Suppress all status/warning emits from the fork so the
+                    # user only sees the final successful-action summary.
+                    # Without this, mid-review "Iteration budget exhausted",
+                    # rate-limit retries, compression warnings, and other
+                    # lifecycle messages bubble up through _emit_status ->
+                    # _vprint and leak past the stdout redirect (they go via
+                    # _print_fn/status_callback, which bypass sys.stdout).
+                    review_agent.suppress_status_output = True
 
                     review_agent.run_conversation(
                         user_message=prompt,
@@ -5056,6 +5065,23 @@ class AIAgent:
             return tc.get("call_id", "") or tc.get("id", "") or ""
         return getattr(tc, "call_id", "") or getattr(tc, "id", "") or ""
 
+    @staticmethod
+    def _get_tool_call_name_static(tc) -> str:
+        """Extract function name from a tool_call entry (dict or object).
+
+        Gemini's OpenAI-compatibility endpoint requires every `role: tool`
+        message to carry the matching function name. OpenAI/Anthropic/ollama
+        tolerate its absence, so the field is best-effort: callers fall back
+        to "" and the message still works elsewhere.
+        """
+        if isinstance(tc, dict):
+            fn = tc.get("function")
+            if isinstance(fn, dict):
+                return fn.get("name", "") or ""
+            return ""
+        fn = getattr(tc, "function", None)
+        return getattr(fn, "name", "") or ""
+
     _VALID_API_ROLES = frozenset({"system", "user", "assistant", "tool", "function", "developer"})
 
     @staticmethod
@@ -5118,6 +5144,7 @@ class AIAgent:
                         if cid in missing_results:
                             patched.append({
                                 "role": "tool",
+                                "name": AIAgent._get_tool_call_name_static(tc),
                                 "content": "[Result unavailable — see context summary above]",
                                 "tool_call_id": cid,
                             })
@@ -5816,6 +5843,17 @@ class AIAgent:
             return primary_client
         with self._openai_client_lock():
             request_kwargs = dict(self._client_kwargs)
+        # Per-request OpenAI-wire clients (used by both the non-streaming
+        # chat-completions path and the streaming chat-completions path
+        # in `_interruptible_api_call`) should not run the SDK's built-in
+        # retry loop: the agent's outer loop owns retries with credential
+        # rotation, provider fallback, and backoff that the SDK can't
+        # see. Leaving SDK retries on (default 2) compounds with our outer
+        # retries and lets a single hung provider request stretch to ~3x
+        # the per-call timeout before our stale detector reports it.
+        # Shared/primary clients and Anthropic / Bedrock paths are
+        # unaffected (they don't go through here).
+        request_kwargs["max_retries"] = 0
         if (
             base_url_host_matches(str(request_kwargs.get("base_url", "")), "api.githubcopilot.com")
             and self._api_kwargs_have_image_parts(api_kwargs or {})
@@ -8192,6 +8230,7 @@ class AIAgent:
         """True when using an anthropic-compatible endpoint that preserves dots in model names.
         Alibaba/DashScope keeps dots (e.g. qwen3.5-plus).
         MiniMax keeps dots (e.g. MiniMax-M2.7).
+        Xiaomi MiMo keeps dots (e.g. mimo-v2.5, mimo-v2.5-pro).
         OpenCode Go/Zen keeps dots for non-Claude models (e.g. minimax-m2.5-free).
         ZAI/Zhipu keeps dots (e.g. glm-4.7, glm-5.1).
         AWS Bedrock uses dotted inference-profile IDs
@@ -8205,6 +8244,7 @@ class AIAgent:
             "alibaba", "minimax", "minimax-cn",
             "opencode-go", "opencode-zen",
             "zai", "bedrock",
+            "xiaomi",
         }:
             return True
         base = (getattr(self, "base_url", "") or "").lower()
@@ -8214,6 +8254,7 @@ class AIAgent:
             or "minimax" in base
             or "opencode.ai/zen/" in base
             or "bigmodel.cn" in base
+            or "xiaomimimo.com" in base
             # AWS Bedrock runtime endpoints — defense-in-depth when
             # ``provider`` is unset but ``base_url`` still names Bedrock.
             or "bedrock-runtime." in base
@@ -9008,6 +9049,7 @@ class AIAgent:
                             insert_at,
                             {
                                 "role": "tool",
+                                "name": function_name if function_name != "?" else "",
                                 "tool_call_id": tool_call_id,
                                 "content": marker,
                             },
@@ -9412,6 +9454,7 @@ class AIAgent:
             for tc in tool_calls:
                 messages.append({
                     "role": "tool",
+                    "name": tc.function.name,
                     "content": f"[Tool execution cancelled — {tc.function.name} was skipped due to user interrupt]",
                     "tool_call_id": tc.id,
                 })
@@ -9753,6 +9796,7 @@ class AIAgent:
 
             tool_msg = {
                 "role": "tool",
+                "name": name,
                 "content": function_result,
                 "tool_call_id": tc.id,
             }
@@ -9790,6 +9834,7 @@ class AIAgent:
                     skipped_name = skipped_tc.function.name
                     skip_msg = {
                         "role": "tool",
+                        "name": skipped_name,
                         "content": f"[Tool execution cancelled — {skipped_name} was skipped due to user interrupt]",
                         "tool_call_id": skipped_tc.id,
                     }
@@ -10140,6 +10185,7 @@ class AIAgent:
 
             tool_msg = {
                 "role": "tool",
+                "name": function_name,
                 "content": function_result,
                 "tool_call_id": tool_call.id
             }
@@ -10166,6 +10212,7 @@ class AIAgent:
                     skipped_name = skipped_tc.function.name
                     skip_msg = {
                         "role": "tool",
+                        "name": skipped_name,
                         "content": f"[Tool execution skipped — {skipped_name} was not started. User sent a new message]",
                         "tool_call_id": skipped_tc.id
                     }
@@ -10300,7 +10347,10 @@ class AIAgent:
                     provider_preferences["order"] = self.providers_order
                 if self.provider_sort:
                     provider_preferences["sort"] = self.provider_sort
-                if provider_preferences:
+                if provider_preferences and (
+                    (self.provider or "").strip().lower() == "openrouter"
+                    or self._is_openrouter_url()
+                ):
                     summary_extra_body["provider"] = provider_preferences
 
                 if summary_extra_body:
@@ -10418,6 +10468,15 @@ class AIAgent:
         from hermes_logging import set_session_context
         set_session_context(self.session_id)
 
+        # Bind the skill write-origin ContextVar for this thread so tool
+        # handlers (e.g. skill_manage create) can tell whether they are
+        # running inside the background self-improvement review fork vs.
+        # a foreground user-directed turn. Set at the top of each call;
+        # the review fork runs on its own thread with a fresh context,
+        # so the foreground value here does not leak into it.
+        from tools.skill_provenance import set_current_write_origin
+        set_current_write_origin(getattr(self, "_memory_write_origin", "assistant_tool"))
+
         # If the previous turn activated fallback, restore the primary
         # runtime so this turn gets a fresh attempt with the preferred model.
         # No-op when _fallback_activated is False (gateway, first turn, etc.).
@@ -10623,11 +10682,11 @@ class AIAgent:
                     self.model,
                     f"{self.context_compressor.context_length:,}",
                 )
-                if not self.quiet_mode:
-                    self._safe_print(
-                        f"📦 Preflight compression: ~{_preflight_tokens:,} tokens "
-                        f">= {self.context_compressor.threshold_tokens:,} threshold"
-                    )
+                self._emit_status(
+                    f"📦 Preflight compression: ~{_preflight_tokens:,} tokens "
+                    f">= {self.context_compressor.threshold_tokens:,} threshold. "
+                    "This may take a moment."
+                )
                 # May need multiple passes for very large sessions with small
                 # context windows (each pass summarises the middle N turns).
                 for _pass in range(3):
@@ -13076,6 +13135,7 @@ class AIAgent:
                                 content = "Skipped: another tool call in this turn used an invalid name. Please retry this tool call."
                             messages.append({
                                 "role": "tool",
+                                "name": tc.function.name,
                                 "tool_call_id": tc.id,
                                 "content": content,
                             })
@@ -13167,6 +13227,7 @@ class AIAgent:
                                     tool_result = "Skipped: other tool call in this response had invalid JSON."
                                 messages.append({
                                     "role": "tool",
+                                    "name": tc.function.name,
                                     "tool_call_id": tc.id,
                                     "content": tool_result,
                                 })
@@ -13415,9 +13476,22 @@ class AIAgent:
                             m.get("role") == "tool"
                             for m in messages[-5:]  # check recent messages
                         )
+                        # Detect Qwen3/Ollama-style in-content thinking blocks.
+                        # Ollama puts <think> in the content field (not in
+                        # reasoning_content), so _has_structured below would
+                        # miss it.  We check here so thinking-only responses
+                        # after tool calls route to prefill instead of nudge.
+                        _has_inline_thinking = bool(
+                            re.search(
+                                r'<think>|<thinking>|<reasoning>',
+                                final_response or "",
+                                re.IGNORECASE,
+                            )
+                        )
                         if (
                             _prior_was_tool
                             and not getattr(self, "_post_tool_empty_retried", False)
+                            and not _has_inline_thinking  # thinking model still working — let prefill handle
                         ):
                             self._post_tool_empty_retried = True
                             # Clear stale narration so it doesn't resurface
@@ -13457,10 +13531,13 @@ class AIAgent:
                         # continue — the model will see its own reasoning
                         # on the next turn and produce the text portion.
                         # Inspired by clawdbot's "incomplete-text" recovery.
+                        # Also covers Qwen3/Ollama in-content <think> blocks
+                        # (detected above as _has_inline_thinking).
                         _has_structured = bool(
                             getattr(assistant_message, "reasoning", None)
                             or getattr(assistant_message, "reasoning_content", None)
                             or getattr(assistant_message, "reasoning_details", None)
+                            or _has_inline_thinking
                         )
                         if _has_structured and self._thinking_prefill_retries < 2:
                             self._thinking_prefill_retries += 1
@@ -13667,6 +13744,7 @@ class AIAgent:
                             if tc["id"] not in answered_ids:
                                 err_msg = {
                                     "role": "tool",
+                                    "name": AIAgent._get_tool_call_name_static(tc),
                                     "tool_call_id": tc["id"],
                                     "content": f"Error executing tool: {error_msg}",
                                 }

scripts/release.py

@@ -48,12 +48,14 @@ AUTHOR_MAP = {
     "127238744+teknium1@users.noreply.github.com": "teknium1",
     "159539633+MottledShadow@users.noreply.github.com": "MottledShadow",
     "aludwin+gh@gmail.com": "adamludwin",
+    "ngusev@astralinux.ru": "NikolayGusev-astra",
     "2093036+exiao@users.noreply.github.com": "exiao",
     "rylen.anil@gmail.com": "rylena",
     "godnanijatin@gmail.com": "jatingodnani",
     "14046872+tmimmanuel@users.noreply.github.com": "tmimmanuel",
     "657290301@qq.com": "IMHaoyan",
     "revar@users.noreply.github.com": "revaraver",
+    "emelyanenko.kirill@gmail.com": "EmelyanenkoK",
     # Matrix parity salvage batch (April 2026)
     "sr@samirusani": "samrusani",
     "angelclaw@AngelMacBook.local": "angel12",
@@ -67,7 +69,10 @@ AUTHOR_MAP = {
     "nbot@liizfq.top": "liizfq",
     "274096618+hermes-agent-dhabibi@users.noreply.github.com": "dhabibi",
     "dejie.guo@gmail.com": "JayGwod",
+    "133716830+0xKingBack@users.noreply.github.com": "0xKingBack",
+    "daixin1204@gmail.com": "SimbaKingjoe",
     "maxence@groine.fr": "MaxyMoos",
+    "61830395+leprincep35700@users.noreply.github.com": "leprincep35700",
     # OpenViking viking_read salvage (April 2026)
     "hitesh@gmail.com": "htsh",
     "pty819@outlook.com": "pty819",
@@ -94,6 +99,7 @@ AUTHOR_MAP = {
     "252818347@qq.com": "hejuntt1014",
     "uzmpsk.dilekakbas@gmail.com": "dlkakbs",
     "beliefanx@gmail.com": "BeliefanX",
+    "changchun989@proton.me": "changchun989",
     "jefferson@heimdallstrategy.com": "Mind-Dragon",
     "44753291+Nanako0129@users.noreply.github.com": "Nanako0129",
     "steve.westerhouse@origami-analytics.com": "westers",
@@ -338,6 +344,8 @@ AUTHOR_MAP = {
     "haileymarshall005@gmail.com": "haileymarshall",
     "greer.guthrie@gmail.com": "g-guthrie",
     "kennyx102@gmail.com": "bobashopcashier",
+    "77253505+bobashopcashier@users.noreply.github.com": "bobashopcashier",
+    "25355950+megastary@users.noreply.github.com": "megastary",  # PR #18325
     "shokatalishaikh95@gmail.com": "areu01or00",
     "bryan@intertwinesys.com": "bryanyoung",
     "christo.mitov@gmail.com": "christomitov",
@@ -456,6 +464,7 @@ AUTHOR_MAP = {
     "centripetal-star@users.noreply.github.com": "centripetal-star",
     "LeonSGP43@users.noreply.github.com": "LeonSGP43",
     "154585401+LeonSGP43@users.noreply.github.com": "LeonSGP43",
+    "cine.dreamer.one@gmail.com": "LeonSGP43",
     "Lubrsy706@users.noreply.github.com": "Lubrsy706",
     "niyant@spicefi.xyz": "spniyant",
     "olafthiele@gmail.com": "olafthiele",
@@ -505,6 +514,11 @@ AUTHOR_MAP = {
     "michel.belleau@malaiwah.com": "malaiwah",
     "gnanasekaran.sekareee@gmail.com": "gnanam1990",
     "jz.pentest@gmail.com": "0xyg3n",
+    "7093928+0xyg3n@users.noreply.github.com": "0xyg3n",
+    "nftpoetrist@gmail.com": "nftpoetrist",  # PR #18982
+    "millerc79@users.noreply.github.com": "millerc79",  # PR #19033
+    "hermes@example.com": "shellybotmoyer",  # PR #18915 (bot-committed)
+    "exx@example.com": "exxmen",  # PR #19555
     "hypnosis.mda@gmail.com": "Hypn0sis",
     "ywt000818@gmail.com": "OwenYWT",
     "dhandhalyabhavik@gmail.com": "v1k22",
@@ -616,6 +630,98 @@ AUTHOR_MAP = {
     "2114364329@qq.com": "cuyua9",
     "2557058999@qq.com": "Disaster-Terminator",
     "cine.dreamer.one@gmail.com": "LeonSGP43",
+    "zyprothh@gmail.com": "Zyproth",
+    "amitgaur@gmail.com": "amitgaur",
+    "albuquerque.abner@gmail.com": "mrbob-git",
+    "kiala@users.noreply.github.com": "kiala9",
+    "alanxchen@gmail.com": "alanxchen85",
+    "clawbot@clawbots-Mac-mini.local": "John-tip",
+    "der@konsi.org": "konsisumer",
+    "cirwel@The-CIRWEL-Group.local": "CIRWEL",
+    "molvikar8@gmail.com": "molvikar",
+    "nftpoetrist@gmail.com": "nftpoetrist",
+    "dodofun@126.com": "colorcross",
+    "1615063567@qq.com": "zhao0112",
+    "ethanguo.2003@gmail.com": "EthanGuo-coder",
+    "dev0jsh@gmail.com": "tmdgusya",
+    "leavr@163.com": "leavrcn",
+    "17683456+wanazhar@users.noreply.github.com": "wanazhar",
+    "26782336+cixuuz@users.noreply.github.com": "cixuuz",
+    "aleksandr.pasevin@openzeppelin.com": "pasevin",
+    "ubuntu@localhost.localdomain": "holynn-q",
+    "holynn@placeholder.local": "holynn-q",
+    "agent@hermes.local": "jacdevos",
+    "sunsky.lau@gmail.com": "liuhao1024",
+    "qiuqfang98@qq.com": "keepcalmqqf",
+    "261867348+ai-ag2026@users.noreply.github.com": "ai-ag2026",
+    "yanzh.su@gmail.com": "YanzhongSu",
+    "wanderwang@users.noreply.github.com": "WanderWang",
+    "yueheime@gmail.com": "yuehei",
+    "emidomh@gmail.com": "Emidomenge",
+    "2642448440@qq.com": "BlackJulySnow",
+    "4317663+helix4u@users.noreply.github.com": "helix4u",
+    "floptopbot33@gmail.com": "flobo3",
+    "dpaluy@users.noreply.github.com": "dpaluy",
+    "psikonetik@gmail.com": "el-analista",
+    "chenb19870707@gmail.com": "ms-alan",
+    "hex-clawd@users.noreply.github.com": "hex-clawd",
+    "154585401+LeonSGP43@users.noreply.github.com": "LeonSGP43",
+    "barteq@hacknotes.local": "barteqpl",
+    "pama0227@gmail.com": "pama0227",
+    "52785845+ee-blog@users.noreply.github.com": "ee-blog",
+    "simplenamebox@gmail.com": "simplenamebox-ops",
+    "balyan.sid@gmail.com": "alt-glitch",
+    "xdord@xdorddeMac-mini.local": "foreverxdord",
+    "k2767567815@gmail.com": "QifengKuang",
+    "88077783+jjjojoj@users.noreply.github.com": "jjjojoj",
+    "valda@underscore.jp": "valda",
+    "lling486@163.com": "M3RCUR2Y",
+    "buraysandro9@gmail.com": "ygd58",
+    "ideathinklab01-source@users.noreply.github.com": "ideathinklab01-source",
+    "27987889@qq.com": "zng8418",
+    "daniuxie88@proton.me": "DaniuXie",
+    "panchanler@gmail.com": "ChanlerDev",
+    "252620095+briandevans@users.noreply.github.com": "briandevans",
+    "141889580+h0tp-ftw@users.noreply.github.com": "h0tp-ftw",
+    "chinadbo@foxmail.com": "chinadbo",
+    "82637225+kshitijk4poor@users.noreply.github.com": "kshitijk4poor",
+    "xyywtt@gmail.com": "xyiy001",
+    "charliekerfoot@gmail.com": "CharlieKerfoot",
+    "grey0202@users.noreply.github.com": "Grey0202",
+    "vominh1919@gmail.com": "vominh1919",
+    "giwavictor9@gmail.com": "giwaov",
+    "yoimexex@gmail.com": "Yoimex",
+    "76803960+atongrun@users.noreply.github.com": "atongrun",
+    "michaeldanko@icloud.com": "MichaelWDanko",
+    "xudavid429@gmail.com": "YX234",
+    "kathy@Kathy.local": "julysir",
+    "274902531@qq.com": "JanCong",
+    "225304168+e-shizz@users.noreply.github.com": "e-shizz",
+    "vincent_hh@users.noreply.github.com": "VinVC",
+    "1243352777@qq.com": "zons-zhaozhy",
+    "dejie.guo@gmail.com": "JayGwod",
+    "52840391+swithek@users.noreply.github.com": "swithek",
+    "raipratik0101@gmail.com": "PratikRai0101",
+    "code@sasha.id": "sasha-id",
+    "chen.yunbo@xydigit.com": "chenyunbo411",
+    "openclaw@local": "Asce66",
+    "59465365+0xsir0000@users.noreply.github.com": "0xsir0000",
+    "lisanhu2014@hotmail.com": "lisanhu",
+    "0668001438@zte.com.cn": "chenyunbo411",
+    "steven_chanin@alum.mit.edu": "stevenchanin",
+    "fiver@example.com": "halmisen",
+    "mayq0422@gmail.com": "yuqianma",
+    "scott@bubble.local": "bassings",
+    "highland0971@users.noreply.github.com": "highland0971",
+    "sudolewis@gmail.com": "lewislulu",
+    "gaurav2301v@gmail.com": "Gaurav23V",
+    "tranquil_flow@protonmail.com": "Tranquil-Flow",
+    "albert748@gmail.com": "albert748",
+    "ntconguit@gmail.com": "0xharryriddle",
+    "lhysdl@gmail.com": "lhysdl",
+    "shemol@163.com": "SherlockShemol",
+    "clawdia@fmercurio-macstudio.local": "fmercurio",
+    "ricardoporsche001@icloud.com": "Ricardo-M-L",
     "leozeli@qq.com": "leozeli",
     "linlehao@cuhk.edu.cn": "LehaoLin",
     "liutong@isacas.ac.cn": "I3eg1nner",
@@ -673,6 +779,9 @@ AUTHOR_MAP = {
     "web3blind@gmail.com": "web3blind",
     "ztzheng@163.com": "chengoak",  # PR #17467
     "24110240104@m.fudan.edu.cn": "YuShu",  # co-author only
+    "charliekerfoot@gmail.com": "CharlieKerfoot",  # PR #18951
+    # Debug share upload-time redaction (May 2026)
+    "dhuysamen@gmail.com": "GodsBoy",  # PR #19318
 }
 
 

scripts/whatsapp-bridge/package-lock.json

@@ -25,15 +25,15 @@
       }
     },
     "node_modules/@cacheable/memory": {
-      "version": "2.0.7",
-      "resolved": "https://registry.npmjs.org/@cacheable/memory/-/memory-2.0.7.tgz",
-      "integrity": "sha512-RbxnxAMf89Tp1dLhXMS7ceft/PGsDl1Ip7T20z5nZ+pwIAsQ1p2izPjVG69oCLv/jfQ7HDPHTWK0c9rcAWXN3A==",
+      "version": "2.0.8",
+      "resolved": "https://registry.npmjs.org/@cacheable/memory/-/memory-2.0.8.tgz",
+      "integrity": "sha512-FvEb29x5wVwu/Kf93IWwsOOEuhHh6dYCJF3vcKLzXc0KXIW181AOzv6ceT4ZpBHDvAfG60eqb+ekmrnLHIy+jw==",
       "license": "MIT",
       "dependencies": {
-        "@cacheable/utils": "^2.3.3",
-        "@keyv/bigmap": "^1.3.0",
-        "hookified": "^1.14.0",
-        "keyv": "^5.5.5"
+        "@cacheable/utils": "^2.4.0",
+        "@keyv/bigmap": "^1.3.1",
+        "hookified": "^1.15.1",
+        "keyv": "^5.6.0"
       }
     },
     "node_modules/@cacheable/node-cache": {
@@ -51,19 +51,19 @@
       }
     },
     "node_modules/@cacheable/utils": {
-      "version": "2.3.4",
-      "resolved": "https://registry.npmjs.org/@cacheable/utils/-/utils-2.3.4.tgz",
-      "integrity": "sha512-knwKUJEYgIfwShABS1BX6JyJJTglAFcEU7EXqzTdiGCXur4voqkiJkdgZIQtWNFhynzDWERcTYv/sETMu3uJWA==",
+      "version": "2.4.1",
+      "resolved": "https://registry.npmjs.org/@cacheable/utils/-/utils-2.4.1.tgz",
+      "integrity": "sha512-eiFgzCbIneyMlLOmNG4g9xzF7Hv3Mga4LjxjcSC/ues6VYq2+gUbQI8JqNuw/ZM8tJIeIaBGpswAsqV2V7ApgA==",
       "license": "MIT",
       "dependencies": {
-        "hashery": "^1.3.0",
+        "hashery": "^1.5.1",
         "keyv": "^5.6.0"
       }
     },
     "node_modules/@emnapi/runtime": {
-      "version": "1.8.1",
-      "resolved": "https://registry.npmjs.org/@emnapi/runtime/-/runtime-1.8.1.tgz",
-      "integrity": "sha512-mehfKSMWjjNol8659Z8KxEMrdSJDDot5SXMq00dM8BN4o+CLNXQ0xH2V7EchNHV4RmbZLmmPdEaXZc5H2FXmDg==",
+      "version": "1.10.0",
+      "resolved": "https://registry.npmjs.org/@emnapi/runtime/-/runtime-1.10.0.tgz",
+      "integrity": "sha512-ewvYlk86xUoGI0zQRNq/mC+16R1QeDlKQy21Ki3oSYXNgLb45GV1P6A0M+/s6nyCuNDqe5VpaY84BzXGwVbwFA==",
       "license": "MIT",
       "optional": true,
       "peer": true,
@@ -87,9 +87,9 @@
       "license": "BSD-3-Clause"
     },
     "node_modules/@img/colour": {
-      "version": "1.0.0",
-      "resolved": "https://registry.npmjs.org/@img/colour/-/colour-1.0.0.tgz",
-      "integrity": "sha512-A5P/LfWGFSl6nsckYtjw9da+19jB8hkJ6ACTGcDfEJ0aE+l2n2El7dsVM7UVHZQ9s2lmYMWlrS21YLy2IR1LUw==",
+      "version": "1.1.0",
+      "resolved": "https://registry.npmjs.org/@img/colour/-/colour-1.1.0.tgz",
+      "integrity": "sha512-Td76q7j57o/tLVdgS746cYARfSyxk8iEfRxewL9h4OMzYhbW4TAcppl0mT4eyqXddh6L/jwoM75mo7ixa/pCeQ==",
       "license": "MIT",
       "peer": true,
       "engines": {
@@ -617,9 +617,9 @@
       "license": "BSD-3-Clause"
     },
     "node_modules/@protobufjs/codegen": {
-      "version": "2.0.4",
-      "resolved": "https://registry.npmjs.org/@protobufjs/codegen/-/codegen-2.0.4.tgz",
-      "integrity": "sha512-YyFaikqM5sH0ziFZCN3xDC7zeGaB/d0IUb9CATugHWbd1FRFwWwt4ld4OYMPWu5a3Xe01mGAULCdqhMlPl29Jg==",
+      "version": "2.0.5",
+      "resolved": "https://registry.npmjs.org/@protobufjs/codegen/-/codegen-2.0.5.tgz",
+      "integrity": "sha512-zgXFLzW3Ap33e6d0Wlj4MGIm6Ce8O89n/apUaGNB/jx+hw+ruWEp7EwGUshdLKVRCxZW12fp9r40E1mQrf/34g==",
       "license": "BSD-3-Clause"
     },
     "node_modules/@protobufjs/eventemitter": {
@@ -645,9 +645,9 @@
       "license": "BSD-3-Clause"
     },
     "node_modules/@protobufjs/inquire": {
-      "version": "1.1.0",
-      "resolved": "https://registry.npmjs.org/@protobufjs/inquire/-/inquire-1.1.0.tgz",
-      "integrity": "sha512-kdSefcPdruJiFMVSbn801t4vFK7KB/5gd2fYvrxhuJYg8ILrmn9SKSX2tZdV6V+ksulWqS7aXjBcRXl3wHoD9Q==",
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/@protobufjs/inquire/-/inquire-1.1.1.tgz",
+      "integrity": "sha512-mnzgDV26ueAvk7rsbt9L7bE0SuAoqyuys/sMMrmVcN5x9VsxpcG3rqAUSgDyLp0UZlmNfIbQ4fHfCtreVBk8Ew==",
       "license": "BSD-3-Clause"
     },
     "node_modules/@protobufjs/path": {
@@ -663,9 +663,9 @@
       "license": "BSD-3-Clause"
     },
     "node_modules/@protobufjs/utf8": {
-      "version": "1.1.0",
-      "resolved": "https://registry.npmjs.org/@protobufjs/utf8/-/utf8-1.1.0.tgz",
-      "integrity": "sha512-Vvn3zZrhQZkkBE8LSuW3em98c0FwgO4nxzv6OdSxPKJIEKY2bGbHn+mhGIPerzI4twdxaP8/0+06HBpwf345Lw==",
+      "version": "1.1.1",
+      "resolved": "https://registry.npmjs.org/@protobufjs/utf8/-/utf8-1.1.1.tgz",
+      "integrity": "sha512-oOAWABowe8EAbMyWKM0tYDKi8Yaox52D+HWZhAIJqQXbqe0xI/GV7FhLWqlEKreMkfDjshR5FKgi3mnle0h6Eg==",
       "license": "BSD-3-Clause"
     },
     "node_modules/@tokenizer/inflate": {
@@ -714,25 +714,20 @@
       "integrity": "sha512-OvjF+z51L3ov0OyAU0duzsYuvO01PH7x4t6DJx+guahgTnBHkhJdG7soQeTSFLWN3efnHyibZ4Z8l2EuWwJN3A==",
       "license": "MIT"
     },
-    "node_modules/@types/long": {
-      "version": "4.0.2",
-      "resolved": "https://registry.npmjs.org/@types/long/-/long-4.0.2.tgz",
-      "integrity": "sha512-MqTGEo5bj5t157U6fA/BiDynNkn0YknVdh48CMPkTSpFTVmvao5UQmm7uEF6xBEo7qIMAlY/JSleYaE6VOdpaA==",
-      "license": "MIT"
-    },
     "node_modules/@types/node": {
-      "version": "25.3.1",
-      "resolved": "https://registry.npmjs.org/@types/node/-/node-25.3.1.tgz",
-      "integrity": "sha512-hj9YIJimBCipHVfHKRMnvmHg+wfhKc0o4mTtXh9pKBjC8TLJzz0nzGmLi5UJsYAUgSvXFHgb0V2oY10DUFtImw==",
+      "version": "25.6.0",
+      "resolved": "https://registry.npmjs.org/@types/node/-/node-25.6.0.tgz",
+      "integrity": "sha512-+qIYRKdNYJwY3vRCZMdJbPLJAtGjQBudzZzdzwQYkEPQd+PJGixUL5QfvCLDaULoLv+RhT3LDkwEfKaAkgSmNQ==",
       "license": "MIT",
       "dependencies": {
-        "undici-types": "~7.18.0"
+        "undici-types": "~7.19.0"
       }
     },
     "node_modules/@whiskeysockets/baileys": {
       "name": "baileys",
       "version": "7.0.0-rc.9",
       "resolved": "git+ssh://git@github.com/WhiskeySockets/Baileys.git#01047debd81beb20da7b7779b08edcb06aa03770",
+      "integrity": "sha512-letWyB96JHD6NdqpAiseOfaUBi13u8AhiRcKSRqcVjc5Vw5xoPTZGvVnw8K/NvGBFAvyLJkwim9Mjvwzhx/SlA==",
       "hasInstallScript": true,
       "license": "MIT",
       "dependencies": {
@@ -807,9 +802,9 @@
       }
     },
     "node_modules/body-parser": {
-      "version": "1.20.4",
-      "resolved": "https://registry.npmjs.org/body-parser/-/body-parser-1.20.4.tgz",
-      "integrity": "sha512-ZTgYYLMOXY9qKU/57FAo8F+HA2dGX7bqGc71txDRC1rS4frdFI5R7NhluHxH6M0YItAP0sHB4uqAOcYKxO6uGA==",
+      "version": "1.20.5",
+      "resolved": "https://registry.npmjs.org/body-parser/-/body-parser-1.20.5.tgz",
+      "integrity": "sha512-3grm+/2tUOvu2cjJkvsIxrv/wVpfXQW4PsQHYm7yk4vfpu7Ekl6nEsYBoJUL6qDwZUx8wUhQ8tR2qz+ad9c9OA==",
       "license": "MIT",
       "dependencies": {
         "bytes": "~3.1.2",
@@ -820,7 +815,7 @@
         "http-errors": "~2.0.1",
         "iconv-lite": "~0.4.24",
         "on-finished": "~2.4.1",
-        "qs": "~6.14.0",
+        "qs": "~6.15.1",
         "raw-body": "~2.5.3",
         "type-is": "~1.6.18",
         "unpipe": "~1.0.0"
@@ -830,6 +825,21 @@
         "npm": "1.2.8000 || >= 1.4.16"
       }
     },
+    "node_modules/body-parser/node_modules/qs": {
+      "version": "6.15.1",
+      "resolved": "https://registry.npmjs.org/qs/-/qs-6.15.1.tgz",
+      "integrity": "sha512-6YHEFRL9mfgcAvql/XhwTvf5jKcOiiupt2FiJxHkiX1z4j7WL8J/jRHYLluORvc1XxB5rV20KoeK00gVJamspg==",
+      "license": "BSD-3-Clause",
+      "dependencies": {
+        "side-channel": "^1.1.0"
+      },
+      "engines": {
+        "node": ">=0.6"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/ljharb"
+      }
+    },
     "node_modules/bytes": {
       "version": "3.1.2",
       "resolved": "https://registry.npmjs.org/bytes/-/bytes-3.1.2.tgz",
@@ -840,16 +850,16 @@
       }
     },
     "node_modules/cacheable": {
-      "version": "2.3.2",
-      "resolved": "https://registry.npmjs.org/cacheable/-/cacheable-2.3.2.tgz",
-      "integrity": "sha512-w+ZuRNmex9c1TR9RcsxbfTKCjSL0rh1WA5SABbrWprIHeNBdmyQLSYonlDy9gpD+63XT8DgZ/wNh1Smvc9WnJA==",
+      "version": "2.3.4",
+      "resolved": "https://registry.npmjs.org/cacheable/-/cacheable-2.3.4.tgz",
+      "integrity": "sha512-djgxybDbw9fL/ZWMI3+CE8ZilNxcwFkVtDc1gJ+IlOSSWkSMPQabhV/XCHTQ6pwwN6aivXPZ43omTooZiX06Ew==",
       "license": "MIT",
       "dependencies": {
-        "@cacheable/memory": "^2.0.7",
-        "@cacheable/utils": "^2.3.3",
+        "@cacheable/memory": "^2.0.8",
+        "@cacheable/utils": "^2.4.0",
         "hookified": "^1.15.0",
-        "keyv": "^5.5.5",
-        "qified": "^0.6.0"
+        "keyv": "^5.6.0",
+        "qified": "^0.9.0"
       }
     },
     "node_modules/call-bind-apply-helpers": {
@@ -1212,21 +1222,21 @@
       }
     },
     "node_modules/hashery": {
-      "version": "1.5.0",
-      "resolved": "https://registry.npmjs.org/hashery/-/hashery-1.5.0.tgz",
-      "integrity": "sha512-nhQ6ExaOIqti2FDWoEMWARUqIKyjr2VcZzXShrI+A3zpeiuPWzx6iPftt44LhP74E5sW36B75N6VHbvRtpvO6Q==",
+      "version": "1.5.1",
+      "resolved": "https://registry.npmjs.org/hashery/-/hashery-1.5.1.tgz",
+      "integrity": "sha512-iZyKG96/JwPz1N55vj2Ie2vXbhu440zfUfJvSwEqEbeLluk7NnapfGqa7LH0mOsnDxTF85Mx8/dyR6HfqcbmbQ==",
       "license": "MIT",
       "dependencies": {
-        "hookified": "^1.14.0"
+        "hookified": "^1.15.0"
       },
       "engines": {
         "node": ">=20"
       }
     },
     "node_modules/hasown": {
-      "version": "2.0.2",
-      "resolved": "https://registry.npmjs.org/hasown/-/hasown-2.0.2.tgz",
-      "integrity": "sha512-0hJU9SCPvmMzIBdZFqNPXWa6dqh7WdH0cII9y+CyS8rG3nL48Bclra9HmKhVVUHyPWNH5Y7xDwAB7bfgSjkUMQ==",
+      "version": "2.0.3",
+      "resolved": "https://registry.npmjs.org/hasown/-/hasown-2.0.3.tgz",
+      "integrity": "sha512-ej4AhfhfL2Q2zpMmLo7U1Uv9+PyhIZpgQLGT1F9miIGmiCJIoCgSmczFdrc97mWT4kVY72KA+WnnhJ5pghSvSg==",
       "license": "MIT",
       "dependencies": {
         "function-bind": "^1.1.2"
@@ -1327,44 +1337,6 @@
         "protobufjs": "6.8.8"
       }
     },
-    "node_modules/libsignal/node_modules/@types/node": {
-      "version": "10.17.60",
-      "resolved": "https://registry.npmjs.org/@types/node/-/node-10.17.60.tgz",
-      "integrity": "sha512-F0KIgDJfy2nA3zMLmWGKxcH2ZVEtCZXHHdOQs2gSaQ27+lNeEfGxzkIw90aXswATX7AZ33tahPbzy6KAfUreVw==",
-      "license": "MIT"
-    },
-    "node_modules/libsignal/node_modules/long": {
-      "version": "4.0.0",
-      "resolved": "https://registry.npmjs.org/long/-/long-4.0.0.tgz",
-      "integrity": "sha512-XsP+KhQif4bjX1kbuSiySJFNAehNxgLb6hPRGJ9QsUr8ajHkuXGdrHmFUTUUXhDwVX2R5bY4JNZEwbUiMhV+MA==",
-      "license": "Apache-2.0"
-    },
-    "node_modules/libsignal/node_modules/protobufjs": {
-      "version": "6.8.8",
-      "resolved": "https://registry.npmjs.org/protobufjs/-/protobufjs-6.8.8.tgz",
-      "integrity": "sha512-AAmHtD5pXgZfi7GMpllpO3q1Xw1OYldr+dMUlAnffGTAhqkg72WdmSY71uKBF/JuyiKs8psYbtKrhi0ASCD8qw==",
-      "hasInstallScript": true,
-      "license": "BSD-3-Clause",
-      "dependencies": {
-        "@protobufjs/aspromise": "^1.1.2",
-        "@protobufjs/base64": "^1.1.2",
-        "@protobufjs/codegen": "^2.0.4",
-        "@protobufjs/eventemitter": "^1.1.0",
-        "@protobufjs/fetch": "^1.1.0",
-        "@protobufjs/float": "^1.0.2",
-        "@protobufjs/inquire": "^1.1.0",
-        "@protobufjs/path": "^1.1.2",
-        "@protobufjs/pool": "^1.1.0",
-        "@protobufjs/utf8": "^1.1.0",
-        "@types/long": "^4.0.0",
-        "@types/node": "^10.1.0",
-        "long": "^4.0.0"
-      },
-      "bin": {
-        "pbjs": "bin/pbjs",
-        "pbts": "bin/pbts"
-      }
-    },
     "node_modules/long": {
       "version": "5.3.2",
       "resolved": "https://registry.npmjs.org/long/-/long-5.3.2.tgz",
@@ -1372,9 +1344,9 @@
       "license": "Apache-2.0"
     },
     "node_modules/lru-cache": {
-      "version": "11.2.6",
-      "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-11.2.6.tgz",
-      "integrity": "sha512-ESL2CrkS/2wTPfuend7Zhkzo2u0daGJ/A2VucJOgQ/C48S/zB8MMeMHSGKYpXhIjbPxfuezITkaBH1wqv00DDQ==",
+      "version": "11.3.5",
+      "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-11.3.5.tgz",
+      "integrity": "sha512-NxVFwLAnrd9i7KUBxC4DrUhmgjzOs+1Qm50D3oF1/oL+r1NpZ4gA7xvG0/zJ8evR7zIKn4vLf7qTNduWFtCrRw==",
       "license": "BlueOak-1.0.0",
       "engines": {
         "node": "20 || >=22"
@@ -1552,12 +1524,12 @@
       }
     },
     "node_modules/p-queue": {
-      "version": "9.1.0",
-      "resolved": "https://registry.npmjs.org/p-queue/-/p-queue-9.1.0.tgz",
-      "integrity": "sha512-O/ZPaXuQV29uSLbxWBGGZO1mCQXV2BLIwUr59JUU9SoH76mnYvtms7aafH/isNSNGwuEfP6W/4xD0/TJXxrizw==",
+      "version": "9.2.0",
+      "resolved": "https://registry.npmjs.org/p-queue/-/p-queue-9.2.0.tgz",
+      "integrity": "sha512-dWgLE8AH0HjQ9fe74pUkKkvzzYT18Inp4zra3lKHnnwqGvcfcUBrvF2EAVX+envufDNBOzpPq/IBUONDbI7+3g==",
       "license": "MIT",
       "dependencies": {
-        "eventemitter3": "^5.0.1",
+        "eventemitter3": "^5.0.4",
         "p-timeout": "^7.0.0"
       },
       "engines": {
@@ -1648,22 +1620,22 @@
       "license": "MIT"
     },
     "node_modules/protobufjs": {
-      "version": "7.5.4",
-      "resolved": "https://registry.npmjs.org/protobufjs/-/protobufjs-7.5.4.tgz",
-      "integrity": "sha512-CvexbZtbov6jW2eXAvLukXjXUW1TzFaivC46BpWc/3BpcCysb5Vffu+B3XHMm8lVEuy2Mm4XGex8hBSg1yapPg==",
+      "version": "7.5.6",
+      "resolved": "https://registry.npmjs.org/protobufjs/-/protobufjs-7.5.6.tgz",
+      "integrity": "sha512-M71sTMB146U3u0di3yup8iM+zv8yPRNQVr1KK4tyBitl3qFvEGucq/rGDRShD2rsJhtN02RJaJ7j5X5hmy8SJg==",
       "hasInstallScript": true,
       "license": "BSD-3-Clause",
       "dependencies": {
         "@protobufjs/aspromise": "^1.1.2",
         "@protobufjs/base64": "^1.1.2",
-        "@protobufjs/codegen": "^2.0.4",
+        "@protobufjs/codegen": "^2.0.5",
         "@protobufjs/eventemitter": "^1.1.0",
         "@protobufjs/fetch": "^1.1.0",
         "@protobufjs/float": "^1.0.2",
-        "@protobufjs/inquire": "^1.1.0",
+        "@protobufjs/inquire": "^1.1.1",
         "@protobufjs/path": "^1.1.2",
         "@protobufjs/pool": "^1.1.0",
-        "@protobufjs/utf8": "^1.1.0",
+        "@protobufjs/utf8": "^1.1.1",
         "@types/node": ">=13.7.0",
         "long": "^5.0.0"
       },
@@ -1685,17 +1657,23 @@
       }
     },
     "node_modules/qified": {
-      "version": "0.6.0",
-      "resolved": "https://registry.npmjs.org/qified/-/qified-0.6.0.tgz",
-      "integrity": "sha512-tsSGN1x3h569ZSU1u6diwhltLyfUWDp3YbFHedapTmpBl0B3P6U3+Qptg7xu+v+1io1EwhdPyyRHYbEw0KN2FA==",
+      "version": "0.9.1",
+      "resolved": "https://registry.npmjs.org/qified/-/qified-0.9.1.tgz",
+      "integrity": "sha512-n7mar4T0xQ+39dE2vGTAlbxUEpndwPANH0kDef1/MYsB8Bba9wshkybIRx74qgcvKQPEWErf9AqAdYjhzY2Ilg==",
       "license": "MIT",
       "dependencies": {
-        "hookified": "^1.14.0"
+        "hookified": "^2.1.1"
       },
       "engines": {
         "node": ">=20"
       }
     },
+    "node_modules/qified/node_modules/hookified": {
+      "version": "2.2.0",
+      "resolved": "https://registry.npmjs.org/hookified/-/hookified-2.2.0.tgz",
+      "integrity": "sha512-p/LgFzRN5FeoD3DLS6bkUapeye6E4SI6yJs6KetENd18S+FBthqYq2amJUWpt5z0EQwwHemidjY5OqJGEKm5uA==",
+      "license": "MIT"
+    },
     "node_modules/qrcode-terminal": {
       "version": "0.12.0",
       "resolved": "https://registry.npmjs.org/qrcode-terminal/-/qrcode-terminal-0.12.0.tgz",
@@ -1922,13 +1900,13 @@
       }
     },
     "node_modules/side-channel-list": {
-      "version": "1.0.0",
-      "resolved": "https://registry.npmjs.org/side-channel-list/-/side-channel-list-1.0.0.tgz",
-      "integrity": "sha512-FCLHtRD/gnpCiCHEiJLOwdmFP+wzCmDEkc9y7NsYxeF4u7Btsn1ZuwgwJGxImImHicJArLP4R0yX4c2KCrMrTA==",
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/side-channel-list/-/side-channel-list-1.0.1.tgz",
+      "integrity": "sha512-mjn/0bi/oUURjc5Xl7IaWi/OJJJumuoJFQJfDDyO46+hBWsfaVM65TBHq2eoZBhzl9EchxOijpkbRC8SVBQU0w==",
       "license": "MIT",
       "dependencies": {
         "es-errors": "^1.3.0",
-        "object-inspect": "^1.13.3"
+        "object-inspect": "^1.13.4"
       },
       "engines": {
         "node": ">= 0.4"
@@ -2094,9 +2072,9 @@
       }
     },
     "node_modules/undici-types": {
-      "version": "7.18.2",
-      "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.18.2.tgz",
-      "integrity": "sha512-AsuCzffGHJybSaRrmr5eHr81mwJU3kjw6M+uprWvCXiNeN9SOGwQ3Jn8jb8m3Z6izVgknn1R0FTCEAP2QrLY/w==",
+      "version": "7.19.2",
+      "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-7.19.2.tgz",
+      "integrity": "sha512-qYVnV5OEm2AW8cJMCpdV20CDyaN3g0AjDlOGf1OW4iaDEx8MwdtChUp4zu4H0VP3nDRF/8RKWH+IPp9uW0YGZg==",
       "license": "MIT"
     },
     "node_modules/unpipe": {
@@ -2139,9 +2117,9 @@
       "license": "MIT"
     },
     "node_modules/ws": {
-      "version": "8.19.0",
-      "resolved": "https://registry.npmjs.org/ws/-/ws-8.19.0.tgz",
-      "integrity": "sha512-blAT2mjOEIi0ZzruJfIhb3nps74PRWTCz1IjglWEEpQl5XS/UNama6u2/rjFkDDouqr4L67ry+1aGIALViWjDg==",
+      "version": "8.20.0",
+      "resolved": "https://registry.npmjs.org/ws/-/ws-8.20.0.tgz",
+      "integrity": "sha512-sAt8BhgNbzCtgGbt2OxmpuryO63ZoDk/sqaB/znQm94T4fCEsy/yV+7CdC1kJhOU9lboAEU7R3kquuycDoibVA==",
       "license": "MIT",
       "engines": {
         "node": ">=10.0.0"

scripts/whatsapp-bridge/package.json

@@ -12,5 +12,8 @@
     "express": "^4.21.0",
     "qrcode-terminal": "^0.12.0",
     "pino": "^9.0.0"
+  },
+  "overrides": {
+    "protobufjs": "^7.5.5"
   }
 }