feat(onboard): apply startup profiles in managed images

ci/env-var-doc-allowlist.json

@@ -90,5 +90,9 @@
   {
     "name": "NEMOCLAW_DOCKER_GPU_PATCH_NETWORK",
     "reason": "Internal one-process handoff from Docker GPU patch preparation into sandbox creation. Rebuild scopes and restores it; users must not set it."
+  },
+  {
+    "name": "NEMOCLAW_MANAGED_HERMES_HASH_B64",
+    "reason": "Internal one-process transport from the root image applicator to its sandbox-owned Hermes compatibility-hash writer. The value is a bounded base64-encoded hash receipt that only the private internal writer consumes; users must not set it."
   }
 ]

scripts/lib/entrypoint-env-wrapper.sh

@@ -0,0 +1,140 @@
+#!/usr/bin/env bash
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+# Normalize OpenShell's sandbox-create command when an OCI runtime invokes the
+# image ENTRYPOINT with the literal argv:
+#
+#   env NAME=value ... nemoclaw-start [agent command...]
+#
+# This runs before any managed-startup gate. Only environment names emitted by
+# NemoClaw's launch renderer are promoted into the root entrypoint process;
+# interpreter/loader variables such as NODE_OPTIONS, BASH_ENV, PATH, and
+# LD_PRELOAD therefore cannot be smuggled into the trusted profile applicator.
+#
+# Result: NEMOCLAW_ENTRYPOINT_NORMALIZED_ARGV contains the command tail.
+nemoclaw_normalize_entrypoint_env_wrapper() {
+  NEMOCLAW_ENTRYPOINT_NORMALIZED_ARGV=("$@")
+  NEMOCLAW_ENTRYPOINT_NORMALIZED_ARGC="$#"
+  [ "$#" -gt 0 ] || return 0
+
+  case "$1" in
+    nemoclaw-start | /usr/local/bin/nemoclaw-start)
+      shift
+      NEMOCLAW_ENTRYPOINT_NORMALIZED_ARGV=("$@")
+      NEMOCLAW_ENTRYPOINT_NORMALIZED_ARGC="$#"
+      return 0
+      ;;
+    env) ;;
+    *) return 0 ;;
+  esac
+
+  local -a _nemoclaw_original_argv=("$@")
+  local -a _nemoclaw_assignments=()
+  local _nemoclaw_self_index=-1
+  local _nemoclaw_index
+  local _nemoclaw_token
+  local _nemoclaw_name
+  local _nemoclaw_seen_names="|"
+
+  # Locate only the exact self-wrapper grammar. A normal explicit command such
+  # as `env FOO=bar printenv` remains a user command and is not interpreted by
+  # this root entrypoint normalization.
+  for ((_nemoclaw_index = 1; _nemoclaw_index < ${#_nemoclaw_original_argv[@]}; _nemoclaw_index += 1)); do
+    _nemoclaw_token="${_nemoclaw_original_argv[$_nemoclaw_index]}"
+    case "$_nemoclaw_token" in
+      nemoclaw-start | /usr/local/bin/nemoclaw-start)
+        _nemoclaw_self_index="$_nemoclaw_index"
+        break
+        ;;
+      *=*) ;;
+      *) break ;;
+    esac
+  done
+
+  if [ "$_nemoclaw_self_index" -lt 0 ]; then
+    # A managed handoff must never silently degrade into an unmanaged command
+    # because the self-wrapper was absent or malformed.
+    for _nemoclaw_token in "${_nemoclaw_original_argv[@]:1}"; do
+      case "$_nemoclaw_token" in
+        NEMOCLAW_STARTUP_PROFILE_B64=* | NEMOCLAW_CORPORATE_CA_B64=*)
+          printf '%s\n' \
+            '[SECURITY] Malformed managed startup env wrapper; expected nemoclaw-start after assignments.' >&2
+          return 1
+          ;;
+      esac
+    done
+    return 0
+  fi
+
+  if [ "$_nemoclaw_self_index" -gt 65 ]; then
+    printf '%s\n' '[SECURITY] Managed startup env wrapper has too many assignments.' >&2
+    return 1
+  fi
+
+  for ((_nemoclaw_index = 1; _nemoclaw_index < _nemoclaw_self_index; _nemoclaw_index += 1)); do
+    _nemoclaw_token="${_nemoclaw_original_argv[$_nemoclaw_index]}"
+    _nemoclaw_name="${_nemoclaw_token%%=*}"
+    if [ "${#_nemoclaw_token}" -gt 122880 ] \
+      || [[ ! "$_nemoclaw_name" =~ ^[A-Za-z_][A-Za-z0-9_]*$ ]] \
+      || [[ "$_nemoclaw_token" == *$'\n'* ]] \
+      || [[ "$_nemoclaw_token" == *$'\r'* ]]; then
+      printf '%s\n' '[SECURITY] Managed startup env wrapper contains a malformed assignment.' >&2
+      return 1
+    fi
+    case "$_nemoclaw_name" in
+      AWS_EC2_METADATA_DISABLED | \
+        CHAT_UI_URL | \
+        HTTP_PROXY | HTTPS_PROXY | NO_PROXY | \
+        http_proxy | https_proxy | no_proxy | \
+        OPENCLAW_HOME | OPENCLAW_STATE_DIR | OPENCLAW_WORKSPACE_DIR | \
+        NEMOCLAW_AUTO_PAIR_DEADLINE_SECS | \
+        NEMOCLAW_AUTO_PAIR_FAST_DEADLINE_SECS | \
+        NEMOCLAW_AUTO_PAIR_FAST_REENTRY_INTERVAL_SECS | \
+        NEMOCLAW_AUTO_PAIR_FAST_REENTRY_POLLS | \
+        NEMOCLAW_AUTO_PAIR_RUN_TIMEOUT_SECS | \
+        NEMOCLAW_AUTO_PAIR_SLOW_INTERVAL_SECS | \
+        NEMOCLAW_CORPORATE_CA_B64 | \
+        NEMOCLAW_DASHBOARD_BIND | NEMOCLAW_DASHBOARD_PORT | \
+        NEMOCLAW_EXTRA_PLACEHOLDER_KEYS | \
+        NEMOCLAW_HERMES_DASHBOARD | \
+        NEMOCLAW_HERMES_DASHBOARD_INTERNAL_PORT | \
+        NEMOCLAW_HERMES_DASHBOARD_PORT | \
+        NEMOCLAW_HERMES_DASHBOARD_TUI | \
+        NEMOCLAW_MINIMAL_BOOTSTRAP | \
+        NEMOCLAW_OBSERVABILITY | \
+        NEMOCLAW_PROXY_HOST | NEMOCLAW_PROXY_PORT | \
+        NEMOCLAW_SANDBOX_NAME | \
+        NEMOCLAW_STARTUP_PROFILE_B64) ;;
+      *)
+        printf '%s\n' \
+          "[SECURITY] Managed startup env wrapper contains unsupported variable '${_nemoclaw_name}'." >&2
+        return 1
+        ;;
+    esac
+    case "$_nemoclaw_seen_names" in
+      *"|${_nemoclaw_name}|"*)
+        printf '%s\n' \
+          "[SECURITY] Managed startup env wrapper repeats variable '${_nemoclaw_name}'." >&2
+        return 1
+        ;;
+    esac
+    _nemoclaw_assignments+=("$_nemoclaw_token")
+    _nemoclaw_seen_names="${_nemoclaw_seen_names}${_nemoclaw_name}|"
+  done
+
+  # Export only after the complete vector has passed validation so malformed
+  # input cannot leave a partially mutated root process.
+  if [ "$_nemoclaw_self_index" -gt 1 ]; then
+    for _nemoclaw_token in "${_nemoclaw_assignments[@]}"; do
+      export "${_nemoclaw_token?}"
+    done
+  fi
+  # shellcheck disable=SC2034 # output array is consumed by the sourcing entrypoint
+  NEMOCLAW_ENTRYPOINT_NORMALIZED_ARGV=(
+    "${_nemoclaw_original_argv[@]:$((_nemoclaw_self_index + 1))}"
+  )
+  # shellcheck disable=SC2034 # output count is consumed by the sourcing entrypoint
+  NEMOCLAW_ENTRYPOINT_NORMALIZED_ARGC=$((\
+    ${#_nemoclaw_original_argv[@]} - _nemoclaw_self_index - 1))
+}

src/lib/messaging/applier/build/messaging-build-applier.mts

@@ -28,6 +28,11 @@ import { telegramManifest } from "../../channels/telegram/manifest.ts";
 import { wechatManifest } from "../../channels/wechat/manifest.ts";
 import { whatsappManifest } from "../../channels/whatsapp/manifest.ts";
 import type { ChannelAgentPackageRuntimeLockSpec, ChannelManifest } from "../../manifest/types.ts";
+import {
+  selectActiveMessagingChannelIds,
+  selectEnabledMessagingAgentRender,
+  selectEnabledPostAgentInstallBuildFiles,
+} from "../../post-agent-install-selection.ts";
 
 type Env = Record<string, string | undefined>;
 type JsonObject = Record<string, any>;
@@ -341,19 +346,7 @@ export function applyMessagingAgentRenderToLocalFiles(
 
 export function activeChannels(plan: MessagingBuildPlan | null): string[] {
   if (!plan) return [];
-  const seen = new Set<string>();
-  const channels: string[] = [];
-  for (const item of plan.channels) {
-    const channel = String(item.channelId || "")
-      .trim()
-      .toLowerCase();
-    if (!channel || seen.has(channel)) continue;
-    if (item.active === true && item.disabled !== true) {
-      seen.add(channel);
-      channels.push(channel);
-    }
-  }
-  return channels;
+  return selectActiveMessagingChannelIds(plan);
 }
 
 export function messagingRuntimePlanPath(env: Env = process.env): string {
@@ -974,17 +967,17 @@ function resolveAgentRenderTarget(
 }
 
 function enabledAgentRender(plan: MessagingBuildPlan): MessagingRenderEntry[] {
-  const active = new Set(activeChannels(plan));
-  return plan.agentRender.filter(
-    (render) => render.agent === plan.agent && active.has(render.channelId),
-  );
+  return selectEnabledMessagingAgentRender(plan);
 }
 
 function enabledBuildStepsForPhase(
   plan: MessagingBuildPlan | null,
   phase: MessagingHookPhase,
 ): MessagingBuildStep[] {
   if (!plan) return [];
+  if (phase === "post-agent-install") {
+    return selectEnabledPostAgentInstallBuildFiles(plan);
+  }
   return enabledBuildSteps(plan).filter((step) => buildStepMatchesPhase(plan, step, phase));
 }
 
@@ -1714,11 +1707,25 @@ function formatError(error: unknown): string {
 
 export type MessagingBuildPhase = "runtime-setup" | "agent-install" | "post-agent-install";
 
+export interface MessagingBuildPhaseOptions {
+  /**
+   * A managed image already contains the reviewed capability union. Apply only
+   * the explicit render and build-file plan to its durable home directory.
+   */
+  readonly managedStartupRuntime?: boolean;
+}
+
 export function applyMessagingBuildPhase(
   plan: MessagingBuildPlan | null,
   phase: MessagingBuildPhase,
   env: Env = process.env,
+  options: MessagingBuildPhaseOptions = {},
 ): readonly string[] {
+  if (options.managedStartupRuntime && phase !== "post-agent-install") {
+    throw new MessagingBuildApplierError(
+      "Managed startup runtime mode is only valid for post-agent-install",
+    );
+  }
   if (phase === "runtime-setup") {
     const target = writeMessagingRuntimePlanArtifact(plan, messagingRuntimePlanPath(env));
     return target ? [target] : [];
@@ -1732,7 +1739,7 @@ export function applyMessagingBuildPhase(
     ...applyPostAgentInstallBuildFilesToLocalFiles(plan),
   ];
   const appliedTargets = applyPostAgentInstallOutputs();
-  if (plan?.agent === "openclaw") {
+  if (plan?.agent === "openclaw" && !options.managedStartupRuntime) {
     runOpenClawMessagingDoctor(plan, env);
     return uniqueStrings([...appliedTargets, ...applyPostAgentInstallOutputs()]);
   }
@@ -1802,30 +1809,36 @@ export function describeMessagingBuildPhase(
 }
 
 export function main(argv: readonly string[] = process.argv.slice(2)): void {
-  const { agent, phase, dryRun } = parseMessagingBuildArgs(argv);
+  const { agent, phase, dryRun, managedStartupRuntime } = parseMessagingBuildArgs(argv);
   const plan = readMessagingBuildPlanFromEnv(process.env, agent);
   if (dryRun) {
     console.log(JSON.stringify(describeMessagingBuildPhase(plan, phase, process.env), null, 2));
     return;
   }
-  applyMessagingBuildPhase(plan, phase, process.env);
+  applyMessagingBuildPhase(plan, phase, process.env, { managedStartupRuntime });
 }
 
 function parseMessagingBuildArgs(argv: readonly string[]): {
   readonly agent: MessagingAgentId;
   readonly phase: MessagingBuildPhase;
   readonly dryRun: boolean;
+  readonly managedStartupRuntime: boolean;
 } {
   let agent: MessagingAgentId | undefined;
   let phase: MessagingBuildPhase | undefined;
   let dryRun = false;
+  let managedStartupRuntime = false;
 
   for (let index = 0; index < argv.length; index += 1) {
     const arg = argv[index];
     if (arg === "--dry-run") {
       dryRun = true;
       continue;
     }
+    if (arg === "--managed-startup-runtime") {
+      managedStartupRuntime = true;
+      continue;
+    }
     if (arg === "--agent") {
       agent = readAgentArg(argv[index + 1]);
       index += 1;
@@ -1851,10 +1864,17 @@ function parseMessagingBuildArgs(argv: readonly string[]): {
     throw new MessagingBuildApplierError(`Unknown messaging build applier argument: ${arg}`);
   }
 
+  const resolvedPhase = phase ?? "post-agent-install";
+  if (managedStartupRuntime && resolvedPhase !== "post-agent-install") {
+    throw new MessagingBuildApplierError(
+      "--managed-startup-runtime requires --phase post-agent-install",
+    );
+  }
   return {
     agent: agent ?? "openclaw",
-    phase: phase ?? "post-agent-install",
+    phase: resolvedPhase,
     dryRun,
+    managedStartupRuntime,
   };
 }
 

src/lib/messaging/post-agent-install-selection.ts

@@ -0,0 +1,77 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+interface SelectionHook {
+  readonly id: string;
+  readonly phase: string;
+}
+
+interface SelectionChannel {
+  readonly channelId: string;
+  readonly active?: boolean;
+  readonly disabled?: boolean;
+  readonly hooks?: readonly SelectionHook[];
+}
+
+interface SelectionPlanBase {
+  readonly channels: readonly SelectionChannel[];
+}
+
+/**
+ * Canonical active-channel selection for the image applier. Each selection
+ * consumer must resolve the same active channels and mutable outputs.
+ */
+export function selectActiveMessagingChannelIds(plan: SelectionPlanBase): string[] {
+  const seen = new Set<string>();
+  const channels: string[] = [];
+  for (const item of plan.channels) {
+    const channel = String(item.channelId || "")
+      .trim()
+      .toLowerCase();
+    if (!channel || seen.has(channel)) continue;
+    if (item.active === true && item.disabled !== true) {
+      seen.add(channel);
+      channels.push(channel);
+    }
+  }
+  return channels;
+}
+
+export function selectEnabledMessagingAgentRender<
+  Render extends {
+    readonly agent: string;
+    readonly channelId: string;
+  },
+>(
+  plan: SelectionPlanBase & {
+    readonly agent: string;
+    readonly agentRender: readonly Render[];
+  },
+): Render[] {
+  const active = new Set(selectActiveMessagingChannelIds(plan));
+  return plan.agentRender.filter(
+    (render) => render.agent === plan.agent && active.has(render.channelId),
+  );
+}
+
+export function selectEnabledPostAgentInstallBuildFiles<
+  Step extends {
+    readonly channelId: string;
+    readonly kind: string;
+    readonly hookId?: string;
+  },
+>(
+  plan: SelectionPlanBase & {
+    readonly buildSteps: readonly Step[];
+  },
+): Step[] {
+  const active = new Set(selectActiveMessagingChannelIds(plan));
+  return plan.buildSteps.filter((step) => {
+    if (!active.has(step.channelId) || step.kind !== "build-file") return false;
+    if (!step.hookId) return true;
+    const hookPhase = plan.channels
+      .find((channel) => channel.channelId === step.channelId)
+      ?.hooks?.find((hook) => hook.id === step.hookId)?.phase;
+    return hookPhase === undefined || hookPhase === "post-agent-install";
+  });
+}