fix(inference): validate every runtime adapter port through one shared path (#9545)

## Summary

The Bedrock Runtime adapter was the only one of the three local runtime
adapters that never
validated its configured host port, so
`NEMOCLAW_BEDROCK_RUNTIME_ADAPTER_PORT` could place it on
the Ollama inference port, the Ollama auth proxy port, a port inside the
dashboard allocation
range, or any other configured service port. Its two siblings reject all
of those before spawning
anything. After this change all three adapters reject the same
collisions and produce the same
named errors.

## Related Issue

Fixes #9544

## Changes

`src/lib/core/ports.ts`
- Deleted `validateBedrockRuntimeAdapterPort`,
`validateOpenRouterRuntimeAdapterPort` and
  `validateHttpsPinRuntimeAdapterPort`.
- Added one `CURRENT_RUNTIME_PORT_CONFIGURATION` next to the catalog,
and
`validateRuntimeAdapterPort(ownerEnvVar, port, options =
CURRENT_RUNTIME_PORT_CONFIGURATION)`, which
  calls `validateServicePort(ownerEnvVar, port, options, ownerEnvVar)`.
- `validateLlamaCppPortReservation`'s bottom call now takes that same
object instead of rebuilding the
  ten fields a second time.

`src/lib/inference/bedrock-runtime-adapter.ts`,
`openrouter-runtime-adapter-lifecycle.ts`,
`https-pin-runtime-adapter.ts`
- Deleted all three `validateAdapterPortConfiguration()` helpers and the
eight now-dead port imports in
  each of the two sibling files.
- Each ensure path opens with a direct `validateRuntimeAdapterPort("<its
own env var>", <its own port>)`.

`src/lib/core/ports.test.ts`
- The three near-identical describes collapse into one
`validateRuntimeAdapterPort` describe: an
`ADAPTER_OWNERS` table of the three owner/default/label triples, a
`SHARED_CONFLICTS` table, and a
generated matrix crossing each owner against the shared conflicts *and*
the other two adapters'
defaults. Same assertions as before, one copy. Plus one case proving the
no-options overload
  validates against the live configuration.

`src/lib/inference/runtime-adapter-port-collisions.test.ts`
- Added in `f1f589858` by @prekshivyas. It covers all three public
ensure paths symmetrically, so it
answers the boundary-test request without reintroducing the per-adapter
asymmetry that a
Bedrock-only ensure test would have created. Each case asserts the named
validation error and that
no adapter process is spawned and no pid, token, or state file is
written.

Production is net **+42 / −94 = −52 lines** and is unchanged by the
follow-up commit. Including the
new boundary-test file, the complete PR is **+191 / −141 = +50 lines**
across the repo. An earlier
revision of this description quoted the repo-wide figure from before
that file existed.

## Type of Change

- [x] Code change (feature, bug fix, or refactor)
- [ ] Code change with doc updates
- [ ] Doc only (prose changes, no code sample modifications)
- [ ] Doc only (includes code sample changes)

## Quality Gates

- [x] Tests added or updated for changed behavior
- [ ] Existing tests cover changed behavior — justification:
- [ ] Tests not applicable — justification:
- [x] Sensitive paths changed (security, policy, credentials, preflight,
onboarding, inference, runner, sandbox, or messaging)
- [ ] Sensitive-path review completed or maintainer-approved waiver
recorded — reviewer/approval link/justification:
- [ ] Non-success, skipped, or missing CI check accepted by maintainer —
check name, approval link, and follow-up issue:

## Verification

- [x] PR description includes a `Signed-off-by:` line and every commit
appears as `Verified` in GitHub
- [x] Normal `pre-commit`, `commit-msg`, and `pre-push` hooks passed, or
`npm run validate:pr` passed after refreshing `origin/main` when hooks
were skipped or unavailable
- [x] Targeted behavior tests pass for the current change set, or tests
are marked not applicable above — command/result or justification:
`npx vitest run --project cli src/lib/core/ports.test.ts
src/lib/inference/bedrock-runtime-adapter.test.ts` — 73 passed (73).
      Without the change the nine new cases fail; with it they pass.
`npm run validate:pr` passed, including `Codebase growth guardrails` and
`TypeScript (CLI)`.
- [ ] Applicable broad gate passed — `npm test` for broad
runtime/test-harness changes; `npm run check` for repo-wide
validation/coverage changes — command/result:
- [x] Quality Gates section completed with required justifications or
waivers
- [x] No secrets, API keys, or credentials committed
- [ ] `npm run docs` builds without warnings (doc changes only)
- [ ] Doc pages follow the [style
guide](https://github.com/NVIDIA/NemoClaw/blob/main/docs/CONTRIBUTING.md)
(doc changes only)
- [ ] New doc pages include SPDX header and frontmatter (new pages only)

---

**Note on overlap with #9537:** #9537 restructures the same file and
converges on the same shape — it rewrites
`validateLlamaCppPortReservation` into a direct
`validateServicePort(...)` call. This revision no longer merges cleanly
with it: exactly one file and one region conflict, the doc comment above
`validateLlamaCppPortReservation`. I resolved it in a scratch worktree
and the port tests still pass there. Happy to rebase on #9537 the moment
it lands, or to reorder if you would rather take this one first.

Signed-off-by: Udaya Tejas <udayatejas2004@gmail.com>


<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Bug Fixes**
* Improved port validation for Bedrock, OpenRouter, and HTTPS pin
runtime adapters.
* Prevented runtime adapters from using ports reserved by other services
or adapters.
* Added safeguards against overlapping and conflicting port assignments.
* Ensured adapter startup checks reflect the current service
configuration.
* Prevented conflicting adapters from starting or creating incomplete
runtime state.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Signed-off-by: Udaya Tejas <udayatejas2004@gmail.com>
Signed-off-by: Prekshi Vyas <prekshiv@nvidia.com>
Signed-off-by: Julie Yaunches <jyaunches@nvidia.com>
Co-authored-by: Prekshi Vyas <prekshiv@nvidia.com>
Co-authored-by: Julie Yaunches <jyaunches@nvidia.com>

Author: 3 people

src/lib/core/ports.test.ts

@@ -6,9 +6,8 @@ import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import {
   parseGatewayPort,
   parsePort,
-  validateHttpsPinRuntimeAdapterPort,
   validateLlamaCppPortReservation,
-  validateOpenRouterRuntimeAdapterPort,
+  validateRuntimeAdapterPort,
 } from "./ports";
 
 const GATEWAY_VALIDATION_OPTIONS = {
@@ -181,68 +180,54 @@ describe("validateLlamaCppPortReservation", () => {
   });
 });
 
-describe("validateOpenRouterRuntimeAdapterPort", () => {
-  const ENV_KEY = "NEMOCLAW_OPENROUTER_RUNTIME_ADAPTER_PORT";
+describe("validateRuntimeAdapterPort", () => {
+  const ADAPTER_OWNERS = [
+    ["NEMOCLAW_BEDROCK_RUNTIME_ADAPTER_PORT", 11436, "Bedrock Runtime adapter"],
+    ["NEMOCLAW_OPENROUTER_RUNTIME_ADAPTER_PORT", 11437, "OpenRouter Runtime adapter"],
+    ["NEMOCLAW_HTTPS_PIN_RUNTIME_ADAPTER_PORT", 11438, "HTTPS Pin Runtime adapter"],
+  ] as const;
 
-  it("allows the default OpenRouter Runtime adapter port", () => {
-    expect(() =>
-      validateOpenRouterRuntimeAdapterPort(ENV_KEY, 11437, GATEWAY_VALIDATION_OPTIONS),
-    ).not.toThrow();
-  });
-
-  it.each([
+  const SHARED_CONFLICTS = [
     [8080, "NEMOCLAW_GATEWAY_PORT"],
     [8000, "vLLM / NIM inference"],
     [11434, "Ollama inference"],
     [11435, "Ollama auth proxy"],
-    [11436, "Bedrock Runtime adapter"],
-    [11438, "HTTPS Pin Runtime adapter"],
     [18790, "18789-18799"],
-  ])("rejects OpenRouter adapter overlap with %s", (port, expectedMessage) => {
-    expect(() =>
-      validateOpenRouterRuntimeAdapterPort(ENV_KEY, port, GATEWAY_VALIDATION_OPTIONS),
-    ).toThrow(expectedMessage);
-  });
+  ] as const;
 
-  it("rejects OpenRouter adapter overlap with configured service ports", () => {
+  it.each(ADAPTER_OWNERS)("allows the default port owned by %s", (ownerEnvVar, defaultPort) => {
     expect(() =>
-      validateOpenRouterRuntimeAdapterPort(ENV_KEY, 19001, {
-        ...GATEWAY_VALIDATION_OPTIONS,
-        vllmPort: 19001,
-      }),
-    ).toThrow("NEMOCLAW_VLLM_PORT");
-  });
-});
-
-describe("validateHttpsPinRuntimeAdapterPort", () => {
-  const ENV_KEY = "NEMOCLAW_HTTPS_PIN_RUNTIME_ADAPTER_PORT";
-
-  it("allows the default HTTPS Pin Runtime adapter port", () => {
-    expect(() =>
-      validateHttpsPinRuntimeAdapterPort(ENV_KEY, 11438, GATEWAY_VALIDATION_OPTIONS),
+      validateRuntimeAdapterPort(ownerEnvVar, defaultPort, GATEWAY_VALIDATION_OPTIONS),
     ).not.toThrow();
   });
 
-  it.each([
-    [8080, "NEMOCLAW_GATEWAY_PORT"],
-    [8000, "vLLM / NIM inference"],
-    [11434, "Ollama inference"],
-    [11435, "Ollama auth proxy"],
-    [11436, "Bedrock Runtime adapter"],
-    [11437, "OpenRouter Runtime adapter"],
-    [18790, "18789-18799"],
-  ])("rejects HTTPS Pin adapter overlap with %s", (port, expectedMessage) => {
-    expect(() =>
-      validateHttpsPinRuntimeAdapterPort(ENV_KEY, port, GATEWAY_VALIDATION_OPTIONS),
-    ).toThrow(expectedMessage);
+  it.each(
+    ADAPTER_OWNERS.flatMap(([ownerEnvVar, defaultPort]) =>
+      [
+        ...SHARED_CONFLICTS,
+        ...ADAPTER_OWNERS.filter(([, otherPort]) => otherPort !== defaultPort).map(
+          ([, otherPort, otherLabel]) => [otherPort, otherLabel] as const,
+        ),
+      ].map(([port, expectedMessage]) => [ownerEnvVar, port, expectedMessage] as const),
+    ),
+  )("rejects %s on %d because it overlaps %s", (ownerEnvVar, port, expectedMessage) => {
+    expect(() => validateRuntimeAdapterPort(ownerEnvVar, port, GATEWAY_VALIDATION_OPTIONS)).toThrow(
+      expectedMessage,
+    );
   });
 
-  it("rejects HTTPS Pin adapter overlap with configured service ports", () => {
+  it.each(ADAPTER_OWNERS)("rejects %s on a configured non-default service port", (ownerEnvVar) => {
     expect(() =>
-      validateHttpsPinRuntimeAdapterPort(ENV_KEY, 19001, {
+      validateRuntimeAdapterPort(ownerEnvVar, 19001, {
         ...GATEWAY_VALIDATION_OPTIONS,
         vllmPort: 19001,
       }),
     ).toThrow("NEMOCLAW_VLLM_PORT");
   });
+
+  it("validates against the live port configuration when no options are injected", () => {
+    expect(() =>
+      validateRuntimeAdapterPort("NEMOCLAW_BEDROCK_RUNTIME_ADAPTER_PORT", 11434),
+    ).toThrow("Ollama inference");
+  });
 });

src/lib/core/ports.ts

@@ -233,21 +233,6 @@ export function parseGatewayPort(
   return port;
 }
 
-export function validateOpenRouterRuntimeAdapterPort(
-  envVar: string,
-  port: number,
-  options: RuntimeAdapterPortValidationOptions,
-): void {
-  validateServicePort(envVar, port, options, "NEMOCLAW_OPENROUTER_RUNTIME_ADAPTER_PORT");
-}
-
-export function validateHttpsPinRuntimeAdapterPort(
-  envVar: string,
-  port: number,
-  options: RuntimeAdapterPortValidationOptions,
-): void {
-  validateServicePort(envVar, port, options, "NEMOCLAW_HTTPS_PIN_RUNTIME_ADAPTER_PORT");
-}
 /** OpenShell gateway port (default 8080, override via NEMOCLAW_GATEWAY_PORT). */
 export const GATEWAY_PORT = parseGatewayPort("NEMOCLAW_GATEWAY_PORT", DEFAULT_GATEWAY_PORT, {
   dashboardPort: DASHBOARD_PORT,
@@ -261,6 +246,35 @@ export const GATEWAY_PORT = parseGatewayPort("NEMOCLAW_GATEWAY_PORT", DEFAULT_GA
   httpsPinRuntimeAdapterPort: HTTPS_PIN_RUNTIME_ADAPTER_PORT,
 });
 
+/** The live host-port configuration every runtime adapter is validated against. */
+const CURRENT_RUNTIME_PORT_CONFIGURATION: RuntimeAdapterPortValidationOptions = {
+  gatewayPort: GATEWAY_PORT,
+  dashboardPort: DASHBOARD_PORT,
+  dashboardRangeStart: DASHBOARD_PORT_RANGE_START,
+  dashboardRangeEnd: DASHBOARD_PORT_RANGE_END,
+  vllmPort: VLLM_PORT,
+  ollamaPort: OLLAMA_PORT,
+  ollamaProxyPort: OLLAMA_PROXY_PORT,
+  bedrockRuntimeAdapterPort: BEDROCK_RUNTIME_ADAPTER_PORT,
+  openrouterRuntimeAdapterPort: OPENROUTER_RUNTIME_ADAPTER_PORT,
+  httpsPinRuntimeAdapterPort: HTTPS_PIN_RUNTIME_ADAPTER_PORT,
+};
+
+/**
+ * Reject a runtime adapter port that overlaps the dashboard allocation range, a
+ * reserved service default, or another configured service port. `ownerEnvVar`
+ * names the adapter being validated: it is both the variable reported in the
+ * error and the catalog entry excluded from the self-conflict check. Tests
+ * inject `options`; production callers use the live configuration above.
+ */
+export function validateRuntimeAdapterPort(
+  ownerEnvVar: string,
+  port: number,
+  options: RuntimeAdapterPortValidationOptions = CURRENT_RUNTIME_PORT_CONFIGURATION,
+): void {
+  validateServicePort(ownerEnvVar, port, options, ownerEnvVar);
+}
+
 /** Reject every configurable service collision with fixed llama.cpp attachment port 8081. */
 export function validateLlamaCppPortReservation(
   options: RuntimeAdapterPortValidationOptions,
@@ -275,15 +289,4 @@ export function validateLlamaCppPortReservation(
   }
 }
 
-validateLlamaCppPortReservation({
-  gatewayPort: GATEWAY_PORT,
-  dashboardPort: DASHBOARD_PORT,
-  dashboardRangeStart: DASHBOARD_PORT_RANGE_START,
-  dashboardRangeEnd: DASHBOARD_PORT_RANGE_END,
-  vllmPort: VLLM_PORT,
-  ollamaPort: OLLAMA_PORT,
-  ollamaProxyPort: OLLAMA_PROXY_PORT,
-  bedrockRuntimeAdapterPort: BEDROCK_RUNTIME_ADAPTER_PORT,
-  openrouterRuntimeAdapterPort: OPENROUTER_RUNTIME_ADAPTER_PORT,
-  httpsPinRuntimeAdapterPort: HTTPS_PIN_RUNTIME_ADAPTER_PORT,
-});
+validateLlamaCppPortReservation(CURRENT_RUNTIME_PORT_CONFIGURATION);

src/lib/inference/bedrock-runtime-adapter.ts

@@ -7,7 +7,7 @@ import path from "node:path";
 
 import { BedrockRuntimeClient } from "@aws-sdk/client-bedrock-runtime";
 
-import { BEDROCK_RUNTIME_ADAPTER_PORT } from "../core/ports";
+import { BEDROCK_RUNTIME_ADAPTER_PORT, validateRuntimeAdapterPort } from "../core/ports";
 import { compactText, isLoopbackRemoteAddress } from "../core/url-utils";
 import { run, runCapture, SCRIPTS } from "../runner";
 import { buildSubprocessEnv } from "../subprocess-env";
@@ -379,6 +379,7 @@ export async function ensureBedrockRuntimeAdapter(options: {
   token: string;
   region: string;
 }> {
+  validateRuntimeAdapterPort("NEMOCLAW_BEDROCK_RUNTIME_ADAPTER_PORT", BEDROCK_RUNTIME_ADAPTER_PORT);
   const region = resolveBedrockRuntimeRegion(options.classification);
   const endpointUrl = options.classification.endpointUrl;
   const compatibleCredential = options.compatibleCredential || null;

src/lib/inference/https-pin-runtime-adapter.ts

@@ -42,19 +42,7 @@ import http from "node:http";
 import { BlockList, isIP } from "node:net";
 import path from "node:path";
 
-import {
-  BEDROCK_RUNTIME_ADAPTER_PORT,
-  DASHBOARD_PORT,
-  DASHBOARD_PORT_RANGE_END,
-  DASHBOARD_PORT_RANGE_START,
-  GATEWAY_PORT,
-  HTTPS_PIN_RUNTIME_ADAPTER_PORT,
-  OLLAMA_PORT,
-  OLLAMA_PROXY_PORT,
-  OPENROUTER_RUNTIME_ADAPTER_PORT,
-  VLLM_PORT,
-  validateHttpsPinRuntimeAdapterPort,
-} from "../core/ports";
+import { HTTPS_PIN_RUNTIME_ADAPTER_PORT, validateRuntimeAdapterPort } from "../core/ports";
 import { retryUntilAsync } from "../core/retry";
 import { getVersion } from "../core/version";
 import { ROOT, run, runCapture } from "../runner";
@@ -1467,25 +1455,6 @@ async function withAdapterLock<T>(operation: () => Promise<T>): Promise<T> {
   throw new Error("HTTPS Pin Runtime adapter startup is already in progress");
 }
 
-function validateAdapterPortConfiguration(): void {
-  validateHttpsPinRuntimeAdapterPort(
-    "NEMOCLAW_HTTPS_PIN_RUNTIME_ADAPTER_PORT",
-    HTTPS_PIN_RUNTIME_ADAPTER_PORT,
-    {
-      dashboardPort: DASHBOARD_PORT,
-      dashboardRangeStart: DASHBOARD_PORT_RANGE_START,
-      dashboardRangeEnd: DASHBOARD_PORT_RANGE_END,
-      gatewayPort: GATEWAY_PORT,
-      vllmPort: VLLM_PORT,
-      ollamaPort: OLLAMA_PORT,
-      ollamaProxyPort: OLLAMA_PROXY_PORT,
-      bedrockRuntimeAdapterPort: BEDROCK_RUNTIME_ADAPTER_PORT,
-      openrouterRuntimeAdapterPort: OPENROUTER_RUNTIME_ADAPTER_PORT,
-      httpsPinRuntimeAdapterPort: HTTPS_PIN_RUNTIME_ADAPTER_PORT,
-    },
-  );
-}
-
 async function findReusableAdapterControlToken(
   priorToken: string | null,
   allowedSourceCidrs: readonly string[] = ["127.0.0.1/32"],
@@ -1523,7 +1492,10 @@ async function ensureAdapterProcessLocked(options: {
   routeId: string;
   allowedSourceCidrs: string[];
 }): Promise<string> {
-  validateAdapterPortConfiguration();
+  validateRuntimeAdapterPort(
+    "NEMOCLAW_HTTPS_PIN_RUNTIME_ADAPTER_PORT",
+    HTTPS_PIN_RUNTIME_ADAPTER_PORT,
+  );
   const priorToken = readLocalAdapterTextFile(TOKEN_PATH);
   // The authenticated, build-bound health response is stronger identity
   // evidence than a PID file. Reuse the live adapter even if its PID metadata

src/lib/inference/openrouter-runtime-adapter-lifecycle.ts

@@ -5,19 +5,7 @@ import fs from "node:fs";
 import http from "node:http";
 import path from "node:path";
 
-import {
-  BEDROCK_RUNTIME_ADAPTER_PORT,
-  DASHBOARD_PORT,
-  DASHBOARD_PORT_RANGE_END,
-  DASHBOARD_PORT_RANGE_START,
-  GATEWAY_PORT,
-  HTTPS_PIN_RUNTIME_ADAPTER_PORT,
-  OLLAMA_PORT,
-  OLLAMA_PROXY_PORT,
-  OPENROUTER_RUNTIME_ADAPTER_PORT,
-  VLLM_PORT,
-  validateOpenRouterRuntimeAdapterPort,
-} from "../core/ports";
+import { OPENROUTER_RUNTIME_ADAPTER_PORT, validateRuntimeAdapterPort } from "../core/ports";
 import { run, runCapture } from "../runner";
 import { buildSubprocessEnv } from "../subprocess-env";
 import {
@@ -209,25 +197,6 @@ function adapterRoute(): AdapterRoute {
   };
 }
 
-function validateAdapterPortConfiguration(): void {
-  validateOpenRouterRuntimeAdapterPort(
-    "NEMOCLAW_OPENROUTER_RUNTIME_ADAPTER_PORT",
-    OPENROUTER_RUNTIME_ADAPTER_PORT,
-    {
-      dashboardPort: DASHBOARD_PORT,
-      dashboardRangeStart: DASHBOARD_PORT_RANGE_START,
-      dashboardRangeEnd: DASHBOARD_PORT_RANGE_END,
-      gatewayPort: GATEWAY_PORT,
-      vllmPort: VLLM_PORT,
-      ollamaPort: OLLAMA_PORT,
-      ollamaProxyPort: OLLAMA_PROXY_PORT,
-      bedrockRuntimeAdapterPort: BEDROCK_RUNTIME_ADAPTER_PORT,
-      openrouterRuntimeAdapterPort: OPENROUTER_RUNTIME_ADAPTER_PORT,
-      httpsPinRuntimeAdapterPort: HTTPS_PIN_RUNTIME_ADAPTER_PORT,
-    },
-  );
-}
-
 function resolveAuthorizationHash(
   authorizationToken: string | null | undefined,
   priorState: JsonObject | null,
@@ -247,7 +216,10 @@ function resolveAuthorizationHash(
 async function ensureOpenRouterRuntimeAdapterLocked(
   options: EnsureOpenRouterRuntimeAdapterOptions = {},
 ): Promise<AdapterRoute> {
-  validateAdapterPortConfiguration();
+  validateRuntimeAdapterPort(
+    "NEMOCLAW_OPENROUTER_RUNTIME_ADAPTER_PORT",
+    OPENROUTER_RUNTIME_ADAPTER_PORT,
+  );
   const upstreamBaseUrl = OPENROUTER_ENDPOINT_URL;
   const configHash = adapterConfigHash(upstreamBaseUrl);
   const priorState = readLocalAdapterJsonFile(STATE_PATH);