fix(hermes): align dashboard WhatsApp session path

agents/hermes/Dockerfile

@@ -21,6 +21,13 @@ RUN ./install-reviewed-runtime.sh \
 RUN chown -R root:root /opt/mcp-tool-discovery-runtime \
     && chmod -R a=rX /opt/mcp-tool-discovery-runtime
 
+FROM mcp-tool-discovery-runtime AS runtime-preload-builder
+WORKDIR /opt/nemoclaw-root
+COPY tsconfig.runtime-preloads.json /opt/nemoclaw-root/
+COPY src/lib/messaging/channels/ /opt/nemoclaw-root/src/lib/messaging/channels/
+RUN ln -s /opt/mcp-tool-discovery-runtime/node_modules /opt/nemoclaw-root/node_modules \
+    && /opt/mcp-tool-discovery-runtime/node_modules/.bin/tsc -p tsconfig.runtime-preloads.json
+
 FROM mcp-tool-discovery-runtime AS managed-startup-runtime-builder
 WORKDIR /opt/nemoclaw-managed-startup-build
 COPY src/lib/core/json-types.ts src/lib/core/ports.ts ./src/lib/core/
@@ -136,6 +143,7 @@ COPY agents/hermes/mcp-config-transaction.py /usr/local/lib/nemoclaw/hermes-mcp-
 COPY src/lib/actions/sandbox/openshell-child-visible-credentials.v0.0.85.json /usr/local/lib/nemoclaw/openshell-child-visible-credentials.v0.0.85.json
 COPY scripts/state-dir-guard.py /usr/local/lib/nemoclaw/state-dir-guard.py
 COPY nemoclaw-blueprint/scripts/*.js /usr/local/lib/nemoclaw/preloads/
+COPY --from=runtime-preload-builder /opt/nemoclaw-root/dist/lib/messaging/channels/ /usr/local/lib/nemoclaw/preloads-compiled-channels/
 
 FROM scratch AS hermes-wrapper-payload
 
@@ -317,6 +325,12 @@ RUN chmod 755 /usr/local/bin/nemoclaw-start /usr/local/bin/nemoclaw-managed-star
     && chmod 444 /usr/local/lib/nemoclaw/entrypoint-env-wrapper.sh /usr/local/lib/nemoclaw/gateway-supervisor.sh /usr/local/lib/nemoclaw/build-hermes-mcp-digest.py \
     && chmod 444 /usr/local/lib/nemoclaw/patch-hermes-langfuse-credentials.mts \
     && chmod 444 /usr/local/lib/nemoclaw/openshell-child-visible-credentials.v0.0.85.json \
+    && test -d /usr/local/lib/nemoclaw/preloads-compiled-channels \
+    && runtime_preload_found="$(find /usr/local/lib/nemoclaw/preloads-compiled-channels -path '*/runtime/*.js' -type f -print -quit)" \
+    && test -n "$runtime_preload_found" \
+    && find /usr/local/lib/nemoclaw/preloads-compiled-channels -path '*/runtime/*.js' -type f \
+        -exec sh -c 'for file do target="/usr/local/lib/nemoclaw/preloads/$(basename "$file")"; [ ! -e "$target" ] || { echo "ERROR: duplicate messaging runtime preload basename: $target" >&2; exit 1; }; cp "$file" "$target"; done' sh {} + \
+    && rm -rf /usr/local/lib/nemoclaw/preloads-compiled-channels \
     && if [ -d /usr/local/lib/nemoclaw/preloads ]; then \
         chown -R 0:0 /usr/local/lib/nemoclaw/preloads \
         && find /usr/local/lib/nemoclaw/preloads -type f -exec chmod 444 {} + \
@@ -1082,6 +1096,7 @@ RUN check_metadata() { \
     && check_metadata /usr/local/lib/nemoclaw/managed-bootstrap-trampoline.sh 'root:root 444' \
     && check_metadata /usr/local/bin/nemoclaw-gateway-control 'root:root 700' \
     && check_metadata /usr/local/lib/nemoclaw/preloads/sandbox-safety-net.js 'root:root 444' \
+    && check_metadata /usr/local/lib/nemoclaw/preloads/whatsapp-hermes-session.js 'root:root 444' \
     && check_metadata /usr/local/lib/nemoclaw/hermes-wrapper.py 'root:root 755' \
     && check_metadata /usr/local/lib/nemoclaw/validate-hermes-cli-adapter.py 'root:root 755' \
     && check_metadata /usr/local/share/nemoclaw/hermes-cli-adapter-v1.json 'root:root 444' \

agents/hermes/start.sh

@@ -359,6 +359,14 @@ verify_hermes_config_integrity() {
 
 # configure_messaging_channels is provided by sandbox-init.sh (shared).
 
+prepare_hermes_messaging_runtime() {
+  write_messaging_runtime_setup_plan || return 1
+  apply_messaging_runtime_env_aliases || return 1
+  install_messaging_runtime_preloads || return 1
+  verify_messaging_runtime_secret_scans || return 1
+  write_runtime_shell_env
+}
+
 print_dashboard_urls() {
   local api_url dashboard_url
   api_url="http://127.0.0.1:${PUBLIC_PORT}/v1"
@@ -1770,6 +1778,12 @@ if [ -f /opt/hermes/ui-tui/dist/entry.js ]; then
   export HERMES_TUI_DIR="/opt/hermes/ui-tui"
 fi
 TUIENVEOF
+    if type emit_messaging_connect_runtime_preload_exports >/dev/null 2>&1; then
+      emit_messaging_connect_runtime_preload_exports
+    fi
+    if type emit_messaging_connect_runtime_command_router >/dev/null 2>&1; then
+      emit_messaging_connect_runtime_command_router
+    fi
     for _ca_env_name in SSL_CERT_FILE CURL_CA_BUNDLE REQUESTS_CA_BUNDLE GIT_SSL_CAINFO NODE_EXTRA_CA_CERTS; do
       _ca_env_value="${!_ca_env_name:-}"
       if [ -n "$_ca_env_value" ]; then
@@ -1779,7 +1793,7 @@ TUIENVEOF
     cat <<'GUARDENVEOF'
 # nemoclaw-configure-guard begin
 hermes() {
-  case "$1" in
+  case "${1:-}" in
     setup|doctor)
       echo "Error: 'hermes $1' cannot modify config inside the sandbox." >&2
       echo "NemoClaw manages sandbox config from the host for integrity checks." >&2
@@ -1789,6 +1803,14 @@ hermes() {
       return 1
       ;;
   esac
+  if type _nemoclaw_messaging_runtime_command_module >/dev/null 2>&1; then
+    local _nemoclaw_runtime_module
+    _nemoclaw_runtime_module="$(_nemoclaw_messaging_runtime_command_module hermes "$@")" || return $?
+    if [ -n "$_nemoclaw_runtime_module" ]; then
+      /usr/local/bin/node "$_nemoclaw_runtime_module"
+      return $?
+    fi
+  fi
   command hermes "$@"
 }
 # nemoclaw-configure-guard end
@@ -2161,7 +2183,7 @@ validate_running_hermes_boundary() {
   validate_hermes_runtime_env_secret_boundary || return 1
   HERMES_RESTART_FAILURE_CODE=preload-missing
   # shellcheck disable=SC2119
-  validate_tmp_permissions || return 1
+  validate_messaging_runtime_tmp_permissions || return 1
 }
 
 prepare_hermes_gateway_restart() {
@@ -2875,6 +2897,7 @@ prepare_hermes_nonroot_runtime() {
   refresh_hermes_runtime_config_hashes compat || return 1
   inspect_hermes_mcp_integrity "${HERMES_DIR}/.config-hash" || return 1
   configure_messaging_channels || return 1
+  prepare_hermes_messaging_runtime || return 1
   prepare_tirith_marker_retry || return 1
 }
 
@@ -2887,6 +2910,7 @@ prepare_hermes_root_runtime() {
   validate_hermes_runtime_env_secret_boundary || return 1
   refresh_hermes_provider_placeholders both || return 1
   configure_messaging_channels || return 1
+  prepare_hermes_messaging_runtime || return 1
   prepare_tirith_marker_retry || return 1
 }
 
@@ -3241,7 +3265,7 @@ if [ "$(id -u)" -ne 0 ]; then
 
   # Defence-in-depth: verify /tmp file permissions before launching services.
   # shellcheck disable=SC2119
-  validate_tmp_permissions
+  validate_messaging_runtime_tmp_permissions
 
   # Start Hermes gateway. Messaging egress goes directly through OpenShell.
   umask 0007
@@ -3284,7 +3308,7 @@ prepare_restricted_log /tmp/gateway.log gateway:gateway 600
 
 # Defence-in-depth: verify /tmp file permissions before launching services.
 # shellcheck disable=SC2119
-validate_tmp_permissions
+validate_messaging_runtime_tmp_permissions
 
 # Start Hermes gateway. Messaging egress goes directly through OpenShell.
 launch_hermes_gateway

ci/test-file-size-budget.json

@@ -7,7 +7,7 @@
     "src/lib/onboard/preflight.test.ts": 1904,
     "test/generate-openclaw-config.test.ts": 1941,
     "test/install-preflight.test.ts": 3921,
-    "test/nemoclaw-start.test.ts": 4817,
+    "test/nemoclaw-start.test.ts": 4765,
     "test/onboard-messaging.test.ts": 2043,
     "test/onboard-selection.test.ts": 4769
   }

docs/manage-sandboxes/set-up-whatsapp.mdx

@@ -23,9 +23,14 @@ openclaw channels login --channel whatsapp
 ```
 </AgentOnly>
 <AgentOnly variant="hermes">
+In the NemoClaw-managed connect shell, run:
 ```bash
 hermes whatsapp
 ```
+This command opens QR pairing directly at `/sandbox/.hermes/platforms/whatsapp/session`.
+It reads the WhatsApp mode and sender allowlist from the NemoClaw-managed `/sandbox/.hermes/.env` file without modifying that file.
+Pairing therefore does not cause configuration drift during later host-side `config set --restart` operations or gateway restarts.
+This route applies only to the managed connect shell; direct Hermes executable invocation uses upstream behavior.
 </AgentOnly>
 
 <AgentOnly variant="openclaw">

scripts/check-messaging-plan-image-boundary.mts

@@ -127,6 +127,7 @@ export function createMessagingBoundaryPlan(agent: unknown) {
       ],
       runtimeSetup: {
         nodePreloads: [OPENCLAW_RUNTIME_PRELOAD],
+        commandRoutes: [],
         envAliases: [],
         secretScans: [],
       },
@@ -175,7 +176,7 @@ export function createMessagingBoundaryPlan(agent: unknown) {
         value: { manager: "hermes-uv-pip", spec: HERMES_AIOHTTP_PACKAGE_SPEC },
       },
     ],
-    runtimeSetup: { nodePreloads: [], envAliases: [], secretScans: [] },
+    runtimeSetup: { nodePreloads: [], commandRoutes: [], envAliases: [], secretScans: [] },
   };
 }
 
@@ -313,14 +314,15 @@ function assertReducedRuntimeArtifact(text: string, agent: MessagingBoundaryAgen
   if (
     !isObject(runtimeSetup) ||
     !Array.isArray(runtimeSetup.nodePreloads) ||
+    !Array.isArray(runtimeSetup.commandRoutes) ||
     !Array.isArray(runtimeSetup.envAliases) ||
     !Array.isArray(runtimeSetup.secretScans)
   ) {
     throw new Error("reduced runtime plan is missing the normalized runtimeSetup arrays");
   }
   assertAllowedKeys(
     runtimeSetup,
-    ["nodePreloads", "envAliases", "secretScans"],
+    ["nodePreloads", "commandRoutes", "envAliases", "secretScans"],
     "reduced runtime plan runtimeSetup",
   );
   assertRuntimeSetupEntryAllowlist(
@@ -336,6 +338,11 @@ function assertReducedRuntimeArtifact(text: string, agent: MessagingBoundaryAgen
     ],
     "nodePreloads",
   );
+  assertRuntimeSetupEntryAllowlist(
+    runtimeSetup.commandRoutes,
+    ["channelId", "command", "args", "module", "source"],
+    "commandRoutes",
+  );
   assertRuntimeSetupEntryAllowlist(
     runtimeSetup.envAliases,
     ["channelId", "envKey", "match", "value", "message"],
@@ -346,7 +353,11 @@ function assertReducedRuntimeArtifact(text: string, agent: MessagingBoundaryAgen
     ["channelId", "path", "pattern", "message", "exitCode"],
     "secretScans",
   );
-  if (runtimeSetup.envAliases.length !== 0 || runtimeSetup.secretScans.length !== 0) {
+  if (
+    runtimeSetup.commandRoutes.length !== 0 ||
+    runtimeSetup.envAliases.length !== 0 ||
+    runtimeSetup.secretScans.length !== 0
+  ) {
     throw new Error("reduced runtime plan contains unexpected Teams runtime setup entries");
   }
   if (agent === "openclaw") {