refactor(cli): extract credentials and list runtime bits

src/lib/gateway-runtime-action.ts

@@ -0,0 +1,112 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+const { startGatewayForRecovery } = require("./onboard") as {
+  startGatewayForRecovery: () => Promise<void>;
+};
+import { OPENSHELL_OPERATION_TIMEOUT_MS, OPENSHELL_PROBE_TIMEOUT_MS } from "./openshell-timeouts";
+import { stripAnsi } from "./openshell";
+import { captureOpenshell, runOpenshell } from "./openshell-runtime";
+
+function hasNamedGateway(output = ""): boolean {
+  return stripAnsi(output).includes("Gateway: nemoclaw");
+}
+
+function getActiveGatewayName(output = ""): string | null {
+  const match = stripAnsi(output).match(/^\s*Gateway:\s+(.+?)\s*$/m);
+  return match ? match[1].trim() : null;
+}
+
+export function getNamedGatewayLifecycleState() {
+  const status = captureOpenshell(["status"], { timeout: OPENSHELL_PROBE_TIMEOUT_MS });
+  const gatewayInfo = captureOpenshell(["gateway", "info", "-g", "nemoclaw"], {
+    timeout: OPENSHELL_PROBE_TIMEOUT_MS,
+  });
+  const cleanStatus = stripAnsi(status.output);
+  const activeGateway = getActiveGatewayName(status.output);
+  const connected = /^\s*Status:\s*Connected\b/im.test(cleanStatus);
+  const named = hasNamedGateway(gatewayInfo.output);
+  const refusing = /Connection refused|client error \(Connect\)|tcp connect error/i.test(
+    cleanStatus,
+  );
+  if (connected && activeGateway === "nemoclaw" && named) {
+    return {
+      state: "healthy_named",
+      status: status.output,
+      gatewayInfo: gatewayInfo.output,
+      activeGateway,
+    };
+  }
+  if (activeGateway === "nemoclaw" && named && refusing) {
+    return {
+      state: "named_unreachable",
+      status: status.output,
+      gatewayInfo: gatewayInfo.output,
+      activeGateway,
+    };
+  }
+  if (activeGateway === "nemoclaw" && named) {
+    return {
+      state: "named_unhealthy",
+      status: status.output,
+      gatewayInfo: gatewayInfo.output,
+      activeGateway,
+    };
+  }
+  if (connected) {
+    return {
+      state: "connected_other",
+      status: status.output,
+      gatewayInfo: gatewayInfo.output,
+      activeGateway,
+    };
+  }
+  return {
+    state: "missing_named",
+    status: status.output,
+    gatewayInfo: gatewayInfo.output,
+    activeGateway,
+  };
+}
+
+/** Attempt to recover the named NemoClaw gateway after a restart or connectivity loss. */
+export async function recoverNamedGatewayRuntime() {
+  const before = getNamedGatewayLifecycleState();
+  if (before.state === "healthy_named") {
+    return { recovered: true, before, after: before, attempted: false };
+  }
+
+  runOpenshell(["gateway", "select", "nemoclaw"], {
+    ignoreError: true,
+    timeout: OPENSHELL_OPERATION_TIMEOUT_MS,
+  });
+  let after = getNamedGatewayLifecycleState();
+  if (after.state === "healthy_named") {
+    process.env.OPENSHELL_GATEWAY = "nemoclaw";
+    return { recovered: true, before, after, attempted: true, via: "select" };
+  }
+
+  const shouldStartGateway = [before.state, after.state].some((state) =>
+    ["missing_named", "named_unhealthy", "named_unreachable", "connected_other"].includes(state),
+  );
+
+  if (shouldStartGateway) {
+    try {
+      await startGatewayForRecovery();
+    } catch {
+      // Fall through to the lifecycle re-check below so we preserve the
+      // existing recovery result shape and emit the correct classification.
+    }
+    runOpenshell(["gateway", "select", "nemoclaw"], {
+      ignoreError: true,
+      timeout: OPENSHELL_OPERATION_TIMEOUT_MS,
+    });
+    after = getNamedGatewayLifecycleState();
+    if (after.state === "healthy_named") {
+      process.env.OPENSHELL_GATEWAY = "nemoclaw";
+      return { recovered: true, before, after, attempted: true, via: "start" };
+    }
+  }
+
+  return { recovered: false, before, after, attempted: true };
+}

src/lib/global-cli-actions.ts

@@ -13,6 +13,7 @@ import {
   runSetupAction as executeSetupAction,
   runSetupSparkAction as executeSetupSparkAction,
 } from "./onboard-action";
+import { recoverNamedGatewayRuntime as recoverNamedGatewayRuntimeAction } from "./gateway-runtime-action";
 import { getNemoClawRuntimeBridge } from "./nemoclaw-runtime-bridge";
 import { help, version } from "./root-help-action";
 
@@ -53,7 +54,13 @@ export function showVersion(): void {
 }
 
 export async function recoverNamedGatewayRuntime(): Promise<{ recovered: boolean }> {
-  return getNemoClawRuntimeBridge().recoverNamedGatewayRuntime();
+  const runtime = getNemoClawRuntimeBridge() as {
+    recoverNamedGatewayRuntime?: () => Promise<{ recovered: boolean }>;
+  };
+  if (typeof runtime.recoverNamedGatewayRuntime === "function") {
+    return runtime.recoverNamedGatewayRuntime();
+  }
+  return recoverNamedGatewayRuntimeAction();
 }
 
 export function runOpenshellProviderCommand(

src/lib/list-command-deps.ts

@@ -9,13 +9,12 @@ import { parseGatewayInference } from "./inference-config";
 import { OPENSHELL_PROBE_TIMEOUT_MS } from "./openshell-timeouts";
 import { parseSshProcesses, createSystemDeps } from "./sandbox-session-state";
 import { resolveOpenshell } from "./resolve-openshell";
-
-import { getNemoClawRuntimeBridge } from "./nemoclaw-runtime-bridge";
+import { captureOpenshell } from "./openshell-runtime";
+import { recoverRegistryEntries } from "./registry-recovery-action";
 
 export function buildListCommandDeps(): ListSandboxesCommandDeps {
   const opsBinList = resolveOpenshell();
   const sessionDeps = opsBinList ? createSystemDeps(opsBinList) : null;
-  const runtime = getNemoClawRuntimeBridge();
 
   // Cache the SSH process probe once for all sandboxes — avoids spawning ps
   // per sandbox row. The getSshProcesses() call is the expensive part (5s timeout).
@@ -32,10 +31,10 @@ export function buildListCommandDeps(): ListSandboxesCommandDeps {
   };
 
   return {
-    recoverRegistryEntries: () => runtime.recoverRegistryEntries(),
+    recoverRegistryEntries: () => recoverRegistryEntries(),
     getLiveInference: () =>
       parseGatewayInference(
-        runtime.captureOpenshell(["inference", "get"], {
+        captureOpenshell(["inference", "get"], {
           ignoreError: true,
           timeout: OPENSHELL_PROBE_TIMEOUT_MS,
         }).output,

src/lib/nemoclaw-runtime-bridge.ts

@@ -3,31 +3,17 @@
 
 /* v8 ignore start -- transitional bridge until command actions are extracted from src/nemoclaw.ts. */
 
-import type { RecoveryResult } from "./inventory-commands";
-
 export interface SpawnLikeResult {
   status: number | null;
   stdout?: string | Buffer;
   stderr?: string | Buffer;
 }
 
-export interface GatewayRecoveryResult {
-  recovered: boolean;
-}
-
 export interface SandboxConnectOptions {
   probeOnly?: boolean;
 }
 
 export interface NemoClawRuntimeBridge {
-  captureOpenshell: (
-    args: string[],
-    opts?: { ignoreError?: boolean; timeout?: number },
-  ) => { status: number | null; output: string };
-  recoverNamedGatewayRuntime: () => Promise<GatewayRecoveryResult>;
-  recoverRegistryEntries: (options?: {
-    requestedSandboxName?: string | null;
-  }) => Promise<RecoveryResult>;
   runOpenshell: (
     args: string[],
     opts?: {

src/lib/policy-channel-actions.ts

@@ -8,7 +8,7 @@ import path from "node:path";
 
 import { CLI_DISPLAY_NAME, CLI_NAME } from "./branding";
 import { getCredential, prompt as askPrompt } from "./credentials";
-import { getNemoClawRuntimeBridge } from "./nemoclaw-runtime-bridge";
+import { recoverNamedGatewayRuntime } from "./gateway-runtime-action";
 const { isNonInteractive } = require("./onboard") as { isNonInteractive: () => boolean };
 const onboardProviders = require("./onboard-providers");
 import * as policies from "./policies";
@@ -284,7 +284,7 @@ async function applyChannelAddToGatewayAndRegistry(
   channelName: string,
   acquired: Record<string, string>,
 ): Promise<void> {
-  const recovery = await getNemoClawRuntimeBridge().recoverNamedGatewayRuntime();
+  const recovery = await recoverNamedGatewayRuntime();
   if (!recovery.recovered) {
     console.error(
       `  Could not reach the ${CLI_DISPLAY_NAME} OpenShell gateway. Tokens were staged`,
@@ -324,7 +324,7 @@ async function applyChannelRemoveToGatewayAndRegistry(
   channelName: string,
   channelTokenKeys: string[],
 ): Promise<void> {
-  const recovery = await getNemoClawRuntimeBridge().recoverNamedGatewayRuntime();
+  const recovery = await recoverNamedGatewayRuntime();
   if (!recovery.recovered) {
     console.error(
       `  Could not reach the ${CLI_DISPLAY_NAME} OpenShell gateway to delete the bridge.`,