refactor(mcp): bind lifecycle to recorded runtime

src/lib/actions/sandbox/gateway-target.ts

@@ -4,6 +4,7 @@
 import { GATEWAY_PORT } from "../../core/ports";
 import {
   resolveGatewayName,
+  resolveGatewayPortFromName,
   resolveSandboxGatewayName,
   type SandboxGatewayBinding,
 } from "../../onboard/gateway-binding";
@@ -31,6 +32,20 @@ export function getPersistedSandboxTargetGatewayName(sandbox: SandboxGatewayBind
   return resolveSandboxGatewayName(sandbox);
 }
 
+/** Resolve the complete canonical gateway binding from one persisted sandbox row. */
+export function getPersistedSandboxTargetGateway(sandbox: SandboxGatewayBinding): {
+  gatewayName: string;
+  gatewayPort: number;
+  selectedInProcess: boolean;
+} {
+  const gatewayName = getPersistedSandboxTargetGatewayName(sandbox);
+  const gatewayPort = resolveGatewayPortFromName(gatewayName);
+  if (gatewayPort === null) {
+    throw new Error(`Invalid persisted OpenShell gateway '${gatewayName}'.`);
+  }
+  return { gatewayName, gatewayPort, selectedInProcess: gatewayPort === GATEWAY_PORT };
+}
+
 export function gatewayNamePattern(gatewayName: string): RegExp {
   return new RegExp(
     `Gateway:\\s+${gatewayName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}(?=\\s|$)`,

src/lib/actions/sandbox/mcp-bridge-adapter-deepagents-capability.ts

@@ -2,14 +2,20 @@
 // SPDX-License-Identifier: Apache-2.0
 
 import { McpBridgeError } from "./mcp-bridge-contracts";
+import type { McpProviderInspectionRuntimeSelection } from "./mcp-bridge-provider-inspection";
 import { executeSandboxCommand } from "./process-recovery";
 
 const DEEPAGENTS_MCP_CAPABILITY_MARKER = "NEMOCLAW_DEEPAGENTS_MCP_CAPABILITY=2";
 const DEEPAGENTS_MCP_CAPABILITY_COMMAND =
   "/usr/local/bin/deepagents-code --nemoclaw-mcp-capability";
 
-export function assertDeepAgentsMcpMutationRuntimeCapability(sandboxName: string): void {
-  const result = executeSandboxCommand(sandboxName, DEEPAGENTS_MCP_CAPABILITY_COMMAND);
+export function assertDeepAgentsMcpMutationRuntimeCapability(
+  sandboxName: string,
+  runtimeSelection: McpProviderInspectionRuntimeSelection,
+): void {
+  const result = executeSandboxCommand(sandboxName, DEEPAGENTS_MCP_CAPABILITY_COMMAND, {
+    runtimeSelection,
+  });
   if (result?.status !== 0 || result.stdout.trim() !== DEEPAGENTS_MCP_CAPABILITY_MARKER) {
     throw new McpBridgeError(
       `LangChain Deep Agents Code sandbox '${sandboxName}' does not contain managed MCP capability v2. Rebuild the sandbox before changing authenticated MCP state.`,

src/lib/actions/sandbox/mcp-bridge-adapter-deepagents-command.ts

@@ -5,16 +5,18 @@ import type { McpBridgeEntry } from "../../state/registry";
 import type { AdapterMutationOptions } from "./mcp-bridge-adapter-inspection";
 import { McpBridgeError } from "./mcp-bridge-contracts";
 import { redactBridgeSecretsForDisplay } from "./mcp-bridge-output";
+import type { McpProviderInspectionRuntimeSelection } from "./mcp-bridge-provider-inspection";
 import { executeSandboxCommand } from "./process-recovery";
 
 export function runDeepAgentsAdapterCommand(
   sandboxName: string,
   entry: Pick<McpBridgeEntry, "env">,
   command: string,
   failureMessage: string,
+  runtimeSelection: McpProviderInspectionRuntimeSelection,
   options: AdapterMutationOptions = {},
 ): string {
-  const result = executeSandboxCommand(sandboxName, command);
+  const result = executeSandboxCommand(sandboxName, command, { runtimeSelection });
   const output = redactBridgeSecretsForDisplay(
     [result?.stdout, result?.stderr].filter(Boolean).join("\n").trim(),
     entry,

src/lib/actions/sandbox/mcp-bridge-adapter-deepagents-inspection.ts

@@ -3,6 +3,7 @@
 
 import type { McpBridgeEntry } from "../../state/registry";
 import type { McpAttachedCredentialRevision } from "./mcp-bridge-provider-readiness";
+import type { McpProviderInspectionRuntimeSelection } from "./mcp-bridge-provider-inspection";
 import {
   type AdapterRegistrationInspection,
   inspectAdapterRegistrationCommand,
@@ -12,11 +13,13 @@ import { buildDeepAgentsMcpStatusCommand } from "./mcp-bridge-adapter-status";
 export function inspectDeepAgentsAdapterRegistration(
   sandboxName: string,
   entry: McpBridgeEntry,
+  runtimeSelection: McpProviderInspectionRuntimeSelection,
   credentialRevision?: McpAttachedCredentialRevision,
 ): AdapterRegistrationInspection {
   return inspectAdapterRegistrationCommand(
     sandboxName,
     entry,
     buildDeepAgentsMcpStatusCommand(entry, credentialRevision),
+    runtimeSelection,
   );
 }

src/lib/actions/sandbox/mcp-bridge-adapter-deepagents-registration.ts

@@ -19,6 +19,7 @@
   pythonJsonLiteral,
 } from "./mcp-bridge-adapter-status";
 import type { McpAttachedCredentialRevision } from "./mcp-bridge-provider-readiness";
+import type { McpProviderInspectionRuntimeSelection } from "./mcp-bridge-provider-inspection";
 import { McpBridgeError } from "./mcp-bridge-contracts";
 
 export function buildDeepAgentsMcpRegisterCommand(
@@ -224,9 +225,15 @@
 function verifyDeepAgentsAdapterRegistration(
   sandboxName: string,
   entry: McpBridgeEntry,
+  runtimeSelection: McpProviderInspectionRuntimeSelection,
   credentialRevision?: McpAttachedCredentialRevision,
 ): void {
-  const inspection = inspectDeepAgentsAdapterRegistration(sandboxName, entry, credentialRevision);
+  const inspection = inspectDeepAgentsAdapterRegistration(
+    sandboxName,
+    entry,
+    runtimeSelection,
+    credentialRevision,
+  );
   if (inspection.state === "registered") return;
   const detail = inspection.state === "error" ? inspection.detail : inspection.state;
   throw new McpBridgeError(
@@ -237,6 +244,7 @@
 export function registerDeepAgentsAdapter(
   sandboxName: string,
   entry: McpBridgeEntry,
+  runtimeSelection: McpProviderInspectionRuntimeSelection,
   envValues: Record<string, string> = {},
   replaceExisting = false,
   teardownRollback = false,
@@ -253,6 +261,7 @@
       credentialRevision,
     ),
     `Deep Agents Code MCP config registration failed for '${entry.server}'.`,
+    runtimeSelection,
     { envValues },
   );
   if (teardownRollback) {
@@ -262,7 +271,7 @@
       );
     }
   } else {
-    verifyDeepAgentsAdapterRegistration(sandboxName, entry, credentialRevision);
+    verifyDeepAgentsAdapterRegistration(sandboxName, entry, runtimeSelection, credentialRevision);
   }
 }
 
@@ -285,7 +294,7 @@
   }
   const entry = managedEntries[0];
   const commandEntry: Pick<McpBridgeEntry, "env"> = entry ?? { env: [] };
   const runtimeKind = runDeepAgentsAdapterCommand(
     sandboxName,
     commandEntry,
     buildDeepAgentsMcpRuntimeKindCommand(),
@@ -298,8 +307,8 @@
   if (runtimeKind !== "v2") {
     throw new McpBridgeError("Could not identify the managed Deep Agents MCP runtime.");
   }
   assertDeepAgentsMcpMutationRuntimeCapability(sandboxName);
   runDeepAgentsAdapterCommand(
     sandboxName,
     commandEntry,
     buildDeepAgentsMcpRegisterCommand(entry, true, managedEntries, false, undefined, {
@@ -308,6 +317,6 @@
     "Deep Agents Code managed MCP projection repair failed.",
   );
   for (const managedEntry of managedEntries) {
     verifyDeepAgentsAdapterRegistration(sandboxName, managedEntry);
   }
 }

src/lib/actions/sandbox/mcp-bridge-adapter-deepagents-teardown.ts

@@ -3,6 +3,7 @@
 
 import type { McpBridgeEntry } from "../../state/registry";
 import { runDeepAgentsAdapterCommand } from "./mcp-bridge-adapter-deepagents-command";
+import type { McpProviderInspectionRuntimeSelection } from "./mcp-bridge-provider-inspection";
 import {
   DEEPAGENTS_LEGACY_CONFIG_HELPERS,
   DEEPAGENTS_LEGACY_MCP_CONFIG_PATH,
@@ -167,13 +168,15 @@ export function buildDeepAgentsMcpRemoveCommand(
 export function unregisterDeepAgentsAdapter(
   sandboxName: string,
   entry: McpBridgeEntry,
+  runtimeSelection: McpProviderInspectionRuntimeSelection,
   options: AdapterMutationOptions = {},
 ): AdapterRemovalOutcome {
   const stdout = runDeepAgentsAdapterCommand(
     sandboxName,
     entry,
     buildDeepAgentsMcpRemoveCommand(entry, options.force === true, options.teardown === true),
     `Deep Agents Code MCP config removal failed for '${entry.server}'.`,
+    runtimeSelection,
     options,
   );
   const marker = stdout.match(/NEMOCLAW_DEEPAGENTS_MCP_REMOVAL=(removed|absent|unowned)/);

src/lib/actions/sandbox/mcp-bridge-adapter-hermes-branding.test.ts

@@ -3,33 +3,109 @@
 
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
+import { setProviderCommandRuntimeHooksForTest } from "../../adapters/openshell/provider-command";
+import type { McpBridgeEntry } from "../../state/registry";
+
 const mocks = vi.hoisted(() => ({
-  runOpenshellProviderCommand: vi.fn(),
+  getSandboxOrThrow: vi.fn(),
+  runOpenshell: vi.fn(),
 }));
 
-vi.mock("../../adapters/openshell/provider-command", () => ({
-  runOpenshellProviderCommand: mocks.runOpenshellProviderCommand,
+vi.mock("./mcp-bridge-state", () => ({
+  getSandboxOrThrow: mocks.getSandboxOrThrow,
 }));
 
-import { assertHermesMcpMutationRuntimeCapability } from "./mcp-bridge-adapter-hermes";
+import {
+  assertHermesMcpMutationRuntimeCapability,
+  unregisterHermesAdapter,
+} from "./mcp-bridge-adapter-hermes";
+
+const entry: McpBridgeEntry = {
+  server: "github",
+  agent: "hermes",
+  adapter: "hermes-config",
+  url: "https://api.githubcopilot.com/mcp/",
+  env: ["GITHUB_TOKEN"],
+  providerName: "alpha-mcp-github",
+  providerId: "11111111-2222-4333-8444-555555555555",
+  policyName: "mcp-bridge-github",
+  addedAt: new Date(0).toISOString(),
+};
+
+const runtimeSelection = { gatewayName: "nemoclaw-8091", workspace: "default" };
 
 describe("Hermes MCP recovery guidance", () => {
   beforeEach(() => {
     vi.stubEnv("NEMOCLAW_INVOKED_AS", "nemohermes");
-    mocks.runOpenshellProviderCommand.mockReset().mockReturnValue({
+    mocks.getSandboxOrThrow.mockReset().mockReturnValue({
+      agent: "hermes",
+      gatewayName: "nemoclaw-8091",
+      name: "alpha",
+    });
+    mocks.runOpenshell.mockReset().mockReturnValue({
       status: 1,
       stdout: "",
       stderr: "Hermes gateway is not running under the managed service lifecycle",
     });
+    setProviderCommandRuntimeHooksForTest({ runOpenshell: mocks.runOpenshell });
   });
 
   afterEach(() => {
+    setProviderCommandRuntimeHooksForTest({});
     vi.unstubAllEnvs();
   });
 
   it("uses the invoked CLI name when the managed lifecycle is unavailable", () => {
-    expect(() => assertHermesMcpMutationRuntimeCapability("alpha")).toThrow(
+    expect(() => assertHermesMcpMutationRuntimeCapability("alpha", runtimeSelection)).toThrow(
       "Run `nemohermes alpha recover` and retry.",
     );
   });
+
+  it("pins Hermes MCP lifecycle commands to the recorded runtime target (#10514)", () => {
+    vi.stubEnv("OPENSHELL_GATEWAY", "ambient-gateway");
+    vi.stubEnv("OPENSHELL_GATEWAY_ENDPOINT", "https://ambient.invalid");
+    vi.stubEnv("OPENSHELL_GATEWAY_INSECURE", "true");
+    vi.stubEnv("OPENSHELL_LOCAL_TLS_DIR", "/ambient/tls");
+    vi.stubEnv("OPENSHELL_TOKEN", "ambient-token");
+    vi.stubEnv("OPENSHELL_WORKSPACE", "ambient-workspace");
+    mocks.runOpenshell.mockImplementation((_args, options) => {
+      expect(options).toEqual(
+        expect.objectContaining({
+          env: expect.objectContaining({
+            OPENSHELL_GATEWAY: "nemoclaw-8091",
+            OPENSHELL_WORKSPACE: "default",
+          }),
+          replaceEnv: true,
+        }),
+      );
+      expect(options?.env).not.toHaveProperty("OPENSHELL_GATEWAY_ENDPOINT");
+      expect(options?.env).not.toHaveProperty("OPENSHELL_GATEWAY_INSECURE");
+      expect(options?.env).not.toHaveProperty("OPENSHELL_LOCAL_TLS_DIR");
+      expect(options?.env).not.toHaveProperty("OPENSHELL_TOKEN");
+      return {
+        status: 0,
+        stdout: JSON.stringify({ changed: true, ok: true, reloaded: true }),
+        stderr: "",
+      };
+    });
+
+    expect(() =>
+      assertHermesMcpMutationRuntimeCapability("alpha", runtimeSelection),
+    ).not.toThrow();
+    expect(() => unregisterHermesAdapter("alpha", entry, runtimeSelection)).not.toThrow();
+    expect(mocks.runOpenshell).toHaveBeenCalledTimes(2);
+  });
+
+  it("refuses host-local recovery when the selected Hermes gateway is not ready (#10514)", () => {
+    mocks.runOpenshell.mockReturnValue({
+      status: 1,
+      stdout: "",
+      stderr: "Hermes gateway is not running for managed MCP reload",
+    });
+
+    expect(() => assertHermesMcpMutationRuntimeCapability("alpha", runtimeSelection)).toThrow(
+      "NemoClaw did not attempt host-local supervisor recovery.",
+    );
+    expect(mocks.runOpenshell).toHaveBeenCalledTimes(3);
+  });
 });