refactor(cli): reduce onboard shell implementation

src/lib/core/require-value.ts

@@ -0,0 +1,9 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+export function requireValue<T>(value: T | null | undefined, message: string): T {
+  if (value === null || value === undefined) {
+    throw new Error(message);
+  }
+  return value;
+}

src/lib/onboard/agent-selection.ts

@@ -0,0 +1,33 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import type { AgentDefinition } from "../agent/defs";
+
+export interface SelectOnboardAgentDeps {
+  resolveAgent(options: {
+    agentFlag?: string | null;
+    session?: { agent?: string | null } | null;
+  }): AgentDefinition | null;
+  loadAgent(name: string): AgentDefinition;
+  isNonInteractive(): boolean;
+  note(message: string): void;
+}
+
+export function createSelectOnboardAgent(deps: SelectOnboardAgentDeps) {
+  return async function selectOnboardAgent({
+    agentFlag = null,
+    session = null,
+  }: {
+    agentFlag?: string | null;
+    session?: { agent?: string | null } | null;
+    resume?: boolean;
+    canPrompt?: boolean;
+  } = {}): Promise<AgentDefinition | null> {
+    const agent = deps.resolveAgent({ agentFlag, session });
+    if (deps.isNonInteractive()) {
+      const displayName = agent?.displayName || deps.loadAgent("openclaw").displayName;
+      deps.note(`  [non-interactive] Agent: ${displayName}`);
+    }
+    return agent;
+  };
+}

src/lib/onboard/base-image.ts

@@ -0,0 +1,37 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { ROOT } from "../runner";
+import {
+  buildLocalBaseTag,
+  defaultOpenclawBaseDockerfile,
+  resolveSandboxBaseImage,
+  OPENCLAW_SANDBOX_BASE_IMAGE as SANDBOX_BASE_IMAGE,
+} from "../sandbox-base-image";
+import { getInstalledOpenshellVersion } from "./openshell-version";
+
+/**
+ * Resolve a compatible sandbox-base image and pin it to a repo digest when
+ * possible. PR-branch validation first tries a source-SHA tag, then latest,
+ * and finally a local Dockerfile.base build when the OpenShell Docker driver
+ * requires a newer glibc than the published image provides.
+ */
+export function pullAndResolveBaseImageDigest(
+  options: { requireOpenshellSandboxAbi?: boolean } = {},
+): { digest: string | null; ref: string; source?: string; glibcVersion?: string | null } | null {
+  return resolveSandboxBaseImage({
+    imageName: SANDBOX_BASE_IMAGE,
+    dockerfilePath: defaultOpenclawBaseDockerfile(ROOT),
+    localTag: buildLocalBaseTag("nemoclaw-sandbox-base-local", ROOT),
+    envVar: "NEMOCLAW_SANDBOX_BASE_IMAGE_REF",
+    label: "OpenClaw sandbox base image",
+    requireOpenshellSandboxAbi: options.requireOpenshellSandboxAbi === true,
+    rootDir: ROOT,
+  });
+}
+
+export function getStableGatewayImageRef(versionOutput: string | null = null): string | null {
+  const version = getInstalledOpenshellVersion(versionOutput);
+  if (!version) return null;
+  return `ghcr.io/nvidia/openshell/cluster:${version}`;
+}