Relevant code is in geanylua/glspi_doc.c. I don't see why it doesn't work.

/* Actvate and focus the specified document */
static gint glspi_activate(lua_State* L)
{
	gint idx=-1;
	if (lua_gettop(L)>0) {
		if (lua_isnumber(L,1)) {
			idx=(lua_tonumber(L,1));
			if (idx<0) { /* Negative number refers to (absolute) GtkNotebook index */
				idx=(0-idx)-1;
				if (idx>=gtk_notebook_get_n_pages(NOTEBOOK)) { idx=-1;}
			} else { /* A positive number refers to the geany->documents_array index */
				idx=doc_idx_to_tab_idx(idx-1);
			}

		} else {
			if (lua_isstring(L,1)) {
				idx=doc_idx_to_tab_idx(filename_to_doc_idx(lua_tostring(L, 1)));
			} else {
				if (!lua_isnil(L,1)) { return FAIL_STR_OR_NUM_ARG(1); }
			}
		}
	}
	if (idx>=0) {
		if (idx!=gtk_notebook_get_current_page(NOTEBOOK)) {
			gtk_notebook_set_current_page(NOTEBOOK, idx);
		}
	}
	lua_pushboolean(L, (idx>0));
	return 1;
}

I'm not sure the OPs code should do anything, correct me if I'm wrong, but AFAICT it gets the current document which is the one in the current notebook tab, then sets the notebook tab to that tab, but the code from above:

		if (idx!=gtk_notebook_get_current_page(NOTEBOOK)) {
			gtk_notebook_set_current_page(NOTEBOOK, idx);

makes it do nothing if the current tab == the tab requested == the tab of the current document == the document of the current tab so its guaranteed to do nothing.

Even if it did set the notebook tab GTK does not say it grabs focus, so the Geanylua doc that says:

function activate ( tab_id )                     -- Focus the specified editor tab.

is wrong anyway.

I'm not sure the OPs code should do anything...

In my Lua test code, what I'm interested in is the return value. Even if the function ultimately doesn't have to switch tabs, idx should still be set greater than 0 and return true. But no matter what I send, including numbers that should work, like 1, it returns false.

Even if it did set the notebook tab GTK does not say it grabs focus, so the Geanylua doc... is wrong anyway.

Okay. But the tab isn't changed. Even if focus isn't changed, changing the tab would be an improvement. (eg, if I'm on tab 3, call geany.activate(1), tabs don't change.) Somehow by the end of the function, idx <= 0, causing false to be returned. Maybe the problem is lua_gettop(L)>0 and idx is never changed from its initialized value?

Presumably, this function did work at some time in GeanyLua's past?

But the tab isn't changed ... (eg, if I'm on tab 3, call geany.activate(1), tabs don't change.)

Ok, thats pretty clearly a bug.

The OP seemed to keep using the current document so they would not have changed anything IIUC, so not sure what they meant to describe.

For this bug idx gets values assigned to it all over the place, is there a confusion between the axes, Lua tab index positive starting at 1, Lua doc index negative starting at -1, and notebook page number positive starting at 0 or negative for last, you know usual off by one thingy?

[Edit: maybe there should be two different local variables, lua_idx and notebook_page to avoid confusion.]

The OP seemed to keep using the current document so they would not have changed anything IIUC

Even though that code does not change the tab, the return value should still be true. According to the (erroneous) documentation, the only time it should return false is "if the tab could not be found". That code clearly demonstrates that the document id could be found (so the tab should exist). There is also a demo script info/list-open-files.lua that is supposed to change tabs using geany.activate(), but does not.

maybe there should be two different local variables, lua_idx and notebook_page to avoid confusion

I'll poke at glspi_activate() later to see if I can find where it's misbehaving. If I manage to find the problem, I'll try to rewrite it as you suggest.