@stigmer/server 3.38.0 → 3.38.1

package/src/domain/mcpserver/__tests__/store-faults.test.ts

@@ -0,0 +1,333 @@
+/**
+ * Pins the store-fault contract every MCP server load shares: a typed
+ * ResourceNotFoundError answers NotFound with the domain's pinned copy
+ * (`mcp_server not found: <id>`), and any other store failure is an
+ * infrastructure fault answered as a sanitized Internal, never a NotFound
+ * that tells a client the server does not exist (stigmer/stigmer#1345).
+ *
+ * The surfaces: connect, startConnect (its first load, and the attach arm's
+ * re-read after this lane lost the start race), initiateOAuthConnect,
+ * completeOAuthConnect, and updateVisibility's load step, reached through the
+ * registered handler on an in-process router. completeOAuthConnect loads
+ * after the pending state is consumed and the code exchanged, so its fault
+ * copy sends the user back through the connect flow. The composed suites
+ * reach only a real store, which cannot fail selectively, so each surface
+ * runs here against a store whose read throws. Every other dependency is
+ * untouchable: a load that fails must stop the call before any of them.
+ *
+ * Out of scope: the NotFound copy itself (wire contract, pinned by the
+ * mcpserver conformance suites and the domain's other tests) and the OAuth
+ * grant-store reads (stigmer/stigmer#1360).
+ */
+import { create } from "@bufbuild/protobuf";
+import type { ConnectError } from "@connectrpc/connect";
+import { Code, createClient, createRouterTransport } from "@connectrpc/connect";
+import { describe, expect, it, vi } from "vitest";
+
+import type { OutboundFetch } from "@stigmer/outbound/egress";
+import { McpServerSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import { McpServerCommandController } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/command_pb";
+import {
+  CompleteOAuthConnectInputSchema,
+  ConnectInputSchema,
+  InitiateOAuthConnectInputSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/io_pb";
+import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
+
+import { createLogger } from "../../../boot/logger.js";
+import { SecretService } from "../../../encryption/encryption.js";
+import { createApiResourceInterceptor } from "../../../pipeline/interceptors/apiresource.js";
+import { createVerifierChainInterceptor } from "../../../pipeline/interceptors/auth.js";
+import {
+  errorOf,
+  failingStore,
+  testCallerIdentity,
+  untouchable,
+} from "../../../pipeline/__tests__/support.js";
+import { newPermissiveSingleTeamAuthorizer } from "../../../pipeline/steps/authorize.js";
+import { ResourceNotFoundError } from "../../../store/interface.js";
+import type {
+  PendingOAuthState,
+  PendingOAuthStateStore,
+  Store,
+} from "../../../store/interface.js";
+
+import { completeOAuthConnect } from "../complete-oauth-connect.js";
+import type { McpServerConnectDeps } from "../connect.js";
+import { connect } from "../connect.js";
+import { registerMcpServerServices } from "../controller.js";
+import type { ConnectRun, McpServerConnectEngine } from "../engine.js";
+import { initiateOAuthConnect } from "../initiate-oauth-connect.js";
+import { startConnect } from "../start-connect.js";
+
+const silentLogger = createLogger({
+  level: "error",
+  pretty: false,
+  write: () => {},
+});
+
+const SERVER_ID = "mcps_storefault";
+const ORG = "acme";
+
+const NOT_FOUND_COPY = `mcp_server not found: ${SERVER_ID}`;
+const LOAD_FAULT_COPY = "failed to load mcp server";
+const CALLBACK_FAULT_COPY =
+  "failed to load mcp server — please retry the connect flow";
+
+const MISSING = (): Error =>
+  new ResourceNotFoundError(`mcp_server/${SERVER_ID}`);
+const LOCKED = (): Error => new Error("SQLITE_BUSY: database is locked");
+
+/**
+ * The connect slice's dependencies with every field untouchable except the
+ * ones a surface names: a load that fails must stop the call before the
+ * engine, the environments, the grant store or the network.
+ */
+function connectDeps(
+  overrides: Partial<McpServerConnectDeps>,
+): McpServerConnectDeps {
+  return {
+    store: untouchable("store"),
+    logger: silentLogger,
+    authorizer: newPermissiveSingleTeamAuthorizer(),
+    engineState: untouchable("engineState"),
+    environmentReader: untouchable("environmentReader"),
+    executionContext: untouchable("executionContext"),
+    runnerAuth: untouchable("runnerAuth"),
+    managedEnv: untouchable("managedEnv"),
+    oauthGrants: untouchable("oauthGrants"),
+    pendingOAuthStates: untouchable("pendingOAuthStates"),
+    secretService: untouchable("secretService"),
+    oauthRedirectUri: "http://127.0.0.1:8234/auth/oauth/callback",
+    outboundFetch: untouchable("outboundFetch"),
+    ...overrides,
+  };
+}
+
+/** A plaintext pending state for SERVER_ID; a keyless SecretService unseals it to itself. */
+const PENDING_STATE: PendingOAuthState = {
+  state: "state_storefault",
+  codeVerifier: "verifier_storefault",
+  clientId: "client_storefault",
+  clientSecret: "",
+  tokenEndpoint: "https://auth.example.test/token",
+  mcpServerId: SERVER_ID,
+  identityAccountId: "",
+  targetEnvVar: "MCP_ACCESS_TOKEN",
+  authMethod: "mcp_oauth",
+  tokenAuthMethod: "",
+  redirectUri: "http://127.0.0.1:8234/auth/oauth/callback",
+  org: ORG,
+  createdAt: 0,
+};
+
+const pendingStates: PendingOAuthStateStore = {
+  save: () => Promise.reject(new Error("pendingOAuthStates.save reached")),
+  getAndDelete: () => Promise.resolve(PENDING_STATE),
+  cleanupExpired: () =>
+    Promise.reject(new Error("pendingOAuthStates.cleanupExpired reached")),
+};
+
+/** The provider's token endpoint: the exchange succeeds, so the load is next. */
+const tokenEndpoint: OutboundFetch = () =>
+  Promise.resolve(
+    new Response(
+      JSON.stringify({ access_token: "at_storefault", token_type: "bearer" }),
+      { status: 200 },
+    ),
+  );
+
+const connectInput = () =>
+  create(ConnectInputSchema, { mcpServerId: SERVER_ID, org: ORG });
+
+/**
+ * The direct handlers' entry loads. Each validates its input first, so the
+ * inputs carry every field the handler requires; completeOAuthConnect also
+ * consumes the pending state, unseals it and exchanges the code before its
+ * load, so its fakes answer those three steps.
+ */
+const HANDLER_LOADS: ReadonlyArray<
+  readonly [string, string, (store: Store) => Promise<unknown>]
+> = [
+  [
+    "connect",
+    LOAD_FAULT_COPY,
+    (store) =>
+      connect(connectDeps({ store }), connectInput(), testCallerIdentity()),
+  ],
+  [
+    "startConnect — the first load",
+    LOAD_FAULT_COPY,
+    (store) =>
+      startConnect(
+        connectDeps({ store }),
+        connectInput(),
+        testCallerIdentity(),
+      ),
+  ],
+  [
+    "initiateOAuthConnect",
+    LOAD_FAULT_COPY,
+    (store) =>
+      initiateOAuthConnect(
+        connectDeps({ store }),
+        create(InitiateOAuthConnectInputSchema, {
+          mcpServerId: SERVER_ID,
+          org: ORG,
+        }),
+        testCallerIdentity(),
+      ),
+  ],
+  [
+    "completeOAuthConnect — after the code exchange",
+    CALLBACK_FAULT_COPY,
+    (store) =>
+      completeOAuthConnect(
+        connectDeps({
+          store,
+          pendingOAuthStates: pendingStates,
+          secretService: SecretService.create(undefined),
+          outboundFetch: tokenEndpoint,
+        }),
+        create(CompleteOAuthConnectInputSchema, {
+          mcpServerId: SERVER_ID,
+          state: PENDING_STATE.state,
+          authorizationCode: "code_storefault",
+        }),
+        testCallerIdentity(),
+      ),
+  ],
+];
+
+describe.each(HANDLER_LOADS)("%s", (_surface, faultCopy, run) => {
+  it("a missing server answers NotFound with the domain's copy", async () => {
+    const error = await errorOf(() => run(failingStore(MISSING())));
+
+    expect(error.code).toBe(Code.NotFound);
+    expect(error.rawMessage).toBe(NOT_FOUND_COPY);
+  });
+
+  it("any other store failure answers a sanitized Internal", async () => {
+    const error = await errorOf(() => run(failingStore(LOCKED())));
+
+    expect(error.code).toBe(Code.Internal);
+    expect(error.rawMessage).toBe(faultCopy);
+  });
+});
+
+describe("startConnect — the attach arm's re-read after losing the start race", () => {
+  /** No env and no auth block: prepareConnect creates no ExecutionContext and reads no grant. */
+  const SERVER = create(McpServerSchema, {
+    metadata: { id: SERVER_ID, name: "Store Fault", org: ORG },
+    spec: {
+      serverType: { case: "stdio", value: { command: "npx", args: [] } },
+    },
+  });
+
+  async function attachError(reReadError: Error): Promise<ConnectError> {
+    const attached: ConnectRun = {
+      workflowId: `stigmer/mcp-server/connect/${SERVER_ID}`,
+      attached: true,
+      result: () =>
+        Promise.reject(new Error("result reached on the attach arm")),
+    };
+    const startOrAttachConnect = vi.fn<
+      McpServerConnectEngine["startOrAttachConnect"]
+    >(() => Promise.resolve(attached));
+    const engine: McpServerConnectEngine = {
+      startOrAttachConnect,
+      isConnectRunRunning: () =>
+        Promise.reject(
+          new Error("isConnectRunRunning reached without a CONNECTING record"),
+        ),
+      hasRunnerQueuePollers: () => Promise.resolve(true),
+    };
+    const getResource = vi
+      .fn()
+      .mockResolvedValueOnce(SERVER)
+      .mockRejectedValueOnce(reReadError);
+
+    const error = await errorOf(() =>
+      startConnect(
+        connectDeps({
+          store: { getResource } as unknown as Store,
+          engineState: () => ({ connected: true, engine }),
+        }),
+        connectInput(),
+        testCallerIdentity(),
+      ),
+    );
+
+    // The start ran once and the store was read twice: the failure is the
+    // re-read's, not the first load's.
+    expect(startOrAttachConnect).toHaveBeenCalledTimes(1);
+    expect(getResource).toHaveBeenCalledTimes(2);
+    return error;
+  }
+
+  it("a server deleted since the first load answers NotFound with the domain's copy", async () => {
+    const error = await attachError(MISSING());
+
+    expect(error.code).toBe(Code.NotFound);
+    expect(error.rawMessage).toBe(NOT_FOUND_COPY);
+  });
+
+  it("any other store failure answers a sanitized Internal", async () => {
+    const error = await attachError(LOCKED());
+
+    expect(error.code).toBe(Code.Internal);
+    expect(error.rawMessage).toBe(LOAD_FAULT_COPY);
+  });
+});
+
+describe("updateVisibility — LoadMcpServerForVisibilityUpdate", () => {
+  /**
+   * The registered handler on an in-process router (the artifact domain's
+   * harness): the verifier chain stamps the trusted-local caller and the
+   * apiresource interceptor the kind, then Authorize and ValidateProto run
+   * and the load is the first step that reads the store. The connect slice
+   * is never reached.
+   */
+  function updateVisibilityError(store: Store): Promise<ConnectError> {
+    const transport = createRouterTransport(
+      (router) => {
+        registerMcpServerServices(router, {
+          store,
+          logger: silentLogger,
+          authorizer: newPermissiveSingleTeamAuthorizer(),
+          authorizationLifecycle: undefined,
+          connect: untouchable("connect"),
+        });
+      },
+      {
+        router: {
+          interceptors: [
+            createVerifierChainInterceptor([], [], silentLogger),
+            createApiResourceInterceptor(),
+          ],
+        },
+      },
+    );
+    const command = createClient(McpServerCommandController, transport);
+    return errorOf(() =>
+      command.updateVisibility({
+        resourceId: SERVER_ID,
+        visibility: ApiResourceVisibility.visibility_private,
+      }),
+    );
+  }
+
+  it("a missing server answers NotFound with the domain's copy", async () => {
+    const error = await updateVisibilityError(failingStore(MISSING()));
+
+    expect(error.code).toBe(Code.NotFound);
+    expect(error.rawMessage).toBe(NOT_FOUND_COPY);
+  });
+
+  it("any other store failure answers a sanitized Internal", async () => {
+    const error = await updateVisibilityError(failingStore(LOCKED()));
+
+    expect(error.code).toBe(Code.Internal);
+    expect(error.rawMessage).toBe(LOAD_FAULT_COPY);
+  });
+});

package/src/domain/mcpserver/complete-oauth-connect.ts

@@ -14,8 +14,8 @@
  * pin). Disclosed divergence; the Go-side issue files at wrap-up.
  *
  * Proven by mcpserver-connect.conformance.test.ts
- * (CONFORMANCE_TARGET=local-execution) and
- * __tests__/complete-oauth-connect.test.ts.
+ * (CONFORMANCE_TARGET=local-execution), __tests__/oauth-handshake.test.ts
+ * and __tests__/store-faults.test.ts.
  */
 import { create } from "@bufbuild/protobuf";
 
@@ -42,6 +42,7 @@ import {
 } from "../../pipeline/errors.js";
 import { authorizeDirect } from "../../pipeline/steps/authorize.js";
 import type { PendingOAuthState } from "../../store/interface.js";
+import { ResourceNotFoundError } from "../../store/interface.js";
 import type { McpServerConnectDeps } from "./connect.js";
 import { exchangeCode } from "./oauth/token.js";
 
@@ -147,8 +148,16 @@ export async function completeOAuthConnect(
       mcpServerId,
       McpServerSchema,
     );
-  } catch {
-    throw notFoundError("mcp_server", mcpServerId);
+  } catch (error) {
+    if (error instanceof ResourceNotFoundError) {
+      throw notFoundError("mcp_server", mcpServerId);
+    }
+    // The pending state is consumed and the code exchanged by now, so a
+    // retry of this call can only fail: the copy names the way back.
+    throw internalError(
+      error,
+      "failed to load mcp server — please retry the connect flow",
+    );
   }
 
   let org = pendingState.org;

package/src/domain/mcpserver/connect.ts

@@ -12,7 +12,8 @@
  * (engine.ts) and never registers a worker.
  *
  * Proven by mcpserver-connect.conformance.test.ts
- * (CONFORMANCE_TARGET=local-execution) and __tests__/connect.test.ts.
+ * (CONFORMANCE_TARGET=local-execution), __tests__/connect.test.ts and
+ * __tests__/store-faults.test.ts.
  */
 import type { OutboundFetch } from "@stigmer/outbound/egress";
 import { create } from "@bufbuild/protobuf";
@@ -269,8 +270,11 @@ export async function connect(
       mcpServerId,
       McpServerSchema,
     );
-  } catch {
-    throw notFoundError("mcp_server", mcpServerId);
+  } catch (error) {
+    if (error instanceof ResourceNotFoundError) {
+      throw notFoundError("mcp_server", mcpServerId);
+    }
+    throw internalError(error, "failed to load mcp server");
   }
 
   // The annotation's can_connect check after the load and BEFORE the engine

package/src/domain/mcpserver/controller.ts

@@ -106,6 +106,7 @@ import {
   newValidateVisibilityUpdateStep,
 } from "../../pipeline/steps/validate-visibility.js";
 import type { Store } from "../../store/interface.js";
+import { ResourceNotFoundError } from "../../store/interface.js";
 import { completeOAuthConnect } from "./complete-oauth-connect.js";
 import { connect, startBestEffortConnect } from "./connect.js";
 import type { McpServerConnectDeps } from "./connect.js";
@@ -479,7 +480,7 @@ async function updateVisibility(
   return reqCtx.get(UPDATE_VISIBILITY_MCP_SERVER_KEY) as McpServer;
 }
 
-/** Loads the server by resource_id; ANY load failure → NotFound. */
+/** Loads the server by resource_id; a missing one answers NotFound, a store fault Internal. */
 function newLoadMcpServerForVisibilityUpdateStep(
   store: Store,
 ): PipelineStep<UpdateVisibilityDesc> {
@@ -494,8 +495,11 @@ function newLoadMcpServerForVisibilityUpdateStep(
           input.resourceId,
           McpServerSchema,
         );
-      } catch {
-        throw notFoundError("mcp_server", input.resourceId);
+      } catch (error) {
+        if (error instanceof ResourceNotFoundError) {
+          throw notFoundError("mcp_server", input.resourceId);
+        }
+        throw internalError(error, "failed to load mcp server");
       }
       ctx.set(UPDATE_VISIBILITY_MCP_SERVER_KEY, mcpServer);
     },

package/src/domain/mcpserver/get-oauth-grant-status.ts

@@ -10,7 +10,7 @@
  *
  * Proven by mcpserver-oauth.conformance.test.ts
  * (CONFORMANCE_TARGET=local) and
- * __tests__/get-oauth-grant-status.test.ts.
+ * __tests__/oauth-handshake.test.ts.
  */
 import { create } from "@bufbuild/protobuf";
 

package/src/domain/mcpserver/initiate-oauth-connect.ts

@@ -8,8 +8,8 @@
  * credentials and build the auth URL from its endpoints.
  *
  * Proven by mcpserver-oauth.conformance.test.ts
- * (CONFORMANCE_TARGET=local) and
- * __tests__/initiate-oauth-connect.test.ts.
+ * (CONFORMANCE_TARGET=local), __tests__/oauth-handshake.test.ts and
+ * __tests__/store-faults.test.ts.
  */
 import { create } from "@bufbuild/protobuf";
 import { randomBytes } from "node:crypto";
@@ -40,6 +40,7 @@ import {
 } from "../../pipeline/errors.js";
 import { authorizeDirect } from "../../pipeline/steps/authorize.js";
 import type { PendingOAuthState } from "../../store/interface.js";
+import { ResourceNotFoundError } from "../../store/interface.js";
 import { resolveOAuthAppRef } from "../oauthapp/refresolution.js";
 import { tokenAuthMethodFromSpec } from "./connect.js";
 import type { McpServerConnectDeps } from "./connect.js";
@@ -73,8 +74,11 @@ export async function initiateOAuthConnect(
       mcpServerId,
       McpServerSchema,
     );
-  } catch {
-    throw notFoundError("mcp_server", mcpServerId);
+  } catch (error) {
+    if (error instanceof ResourceNotFoundError) {
+      throw notFoundError("mcp_server", mcpServerId);
+    }
+    throw internalError(error, "failed to load mcp server");
   }
 
   // The annotation's can_connect check AFTER the load — the Java

package/src/domain/mcpserver/start-connect.ts

@@ -21,8 +21,8 @@
  * which is both the repair and the caller's intent.
  *
  * Proven by mcpserver-connect.conformance.test.ts
- * (CONFORMANCE_TARGET=local-execution) and
- * __tests__/start-connect.test.ts.
+ * (CONFORMANCE_TARGET=local-execution), __tests__/connect.test.ts and
+ * __tests__/store-faults.test.ts.
  */
 import type { McpServer } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
 import { McpServerSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
@@ -84,8 +84,11 @@ export async function startConnect(
       mcpServerId,
       McpServerSchema,
     );
-  } catch {
-    throw notFoundError("mcp_server", mcpServerId);
+  } catch (error) {
+    if (error instanceof ResourceNotFoundError) {
+      throw notFoundError("mcp_server", mcpServerId);
+    }
+    throw internalError(error, "failed to load mcp server");
   }
 
   // The annotation's can_connect check after the load and BEFORE the engine
@@ -165,8 +168,11 @@ export async function startConnect(
         mcpServerId,
         McpServerSchema,
       );
-    } catch {
-      throw notFoundError("mcp_server", mcpServerId);
+    } catch (error) {
+      if (error instanceof ResourceNotFoundError) {
+        throw notFoundError("mcp_server", mcpServerId);
+      }
+      throw internalError(error, "failed to load mcp server");
     }
   }
 

package/src/domain/platform/__tests__/platform.test.ts

@@ -14,7 +14,9 @@
  *     executioncontext decrypt lane uses, bound to exactly the named
  *     execution id;
  *   - getRunnerBootstrapConfig echoes the configured Temporal coordinates
- *     with the token fields empty (minting a proxy token is cloud-only);
+ *     with the token fields empty (minting a proxy token is cloud-only),
+ *     and publishes the runner-bootstrap address rather than the one the
+ *     server dials when the two differ (stigmer#1357);
  *   - getServerInfo reports the build stamp by default and the release a
  *     library consumer states through ComposeOptions.version otherwise
  *     (stigmer#1168: unbundled, the stamp is always "dev"), and a
@@ -278,11 +280,61 @@ describe("platform domain (composed with a stated version)", () => {
   });
 });
 
+/**
+ * stigmer#1357 through the real stack: a server that dials Temporal by a
+ * name its runners cannot resolve publishes the address they can, from
+ * the environment through loadConfig and the composition root to the
+ * wire. The composed-server arm above is the default: with no override,
+ * the published address is the server's own.
+ */
+describe("platform domain (composed for runners off the server's network)", () => {
+  let server: ComposedServer;
+  let client: PlatformClient;
+  let dir: string;
+
+  beforeAll(async () => {
+    dir = mkdtempSync(
+      path.join(tmpdir(), "platform-domain-runner-address-test-"),
+    );
+    vi.stubEnv("STIGMER_ENCRYPTION_KEY", ENC_KEY.toString("base64"));
+    server = await composeServer({
+      config: loadConfig({
+        STIGMER_MODEL_REGISTRY_REFRESH: "off",
+        DB_PATH: path.join(dir, "stigmer.db"),
+        ARTIFACT_LOCAL_BASE_PATH: path.join(dir, "artifacts"),
+        TEMPORAL_HOST_PORT: "127.0.0.1:7777",
+        TEMPORAL_NAMESPACE: "conformance-ns",
+        STIGMER_RUNNER_BOOTSTRAP_TEMPORAL_ADDRESS: "temporal.example.test:7233",
+      }),
+      logger: silentLogger,
+      portOverride: 0,
+      host: "127.0.0.1",
+    });
+    const port = await server.start();
+    client = createClient(
+      PlatformQueryController,
+      createGrpcTransport({ baseUrl: `http://127.0.0.1:${port}` }),
+    );
+  });
+
+  afterAll(async () => {
+    await server.shutdown();
+    rmSync(dir, { recursive: true, force: true });
+    vi.unstubAllEnvs();
+  });
+
+  it("getRunnerBootstrapConfig publishes the runner-bootstrap address, with the server's namespace", async () => {
+    const config = await client.getRunnerBootstrapConfig({});
+    expect(config.temporalAddress).toBe("temporal.example.test:7233");
+    expect(config.temporalNamespace).toBe("conformance-ns");
+  });
+});
+
 describe("platform domain (keyless runner-token service)", () => {
   it("a keyless service answers not-minted — fail-soft, never an error", async () => {
     const transport = createRouterTransport((router) => {
       registerPlatformServices(router, {
-        temporalHostPort: "localhost:7233",
+        runnerBootstrapTemporalAddress: "localhost:7233",
         temporalNamespace: "default",
         runnerAuthService: newExecutionScopedRunnerCredentialProvider(
           RunnerAuthService.create(undefined),
@@ -318,7 +370,7 @@ describe("platform domain (license status)", () => {
   function clientWith(provider: LicenseStatusProvider) {
     const transport = createRouterTransport((router) => {
       registerPlatformServices(router, {
-        temporalHostPort: "localhost:7233",
+        runnerBootstrapTemporalAddress: "localhost:7233",
         temporalNamespace: "default",
         runnerAuthService: newExecutionScopedRunnerCredentialProvider(
           RunnerAuthService.create(undefined),

package/src/domain/platform/controller.ts

@@ -78,12 +78,14 @@ import { TOKEN_TYPE_EXECUTION_SCOPED } from "../../runnerauth/runnerauth.js";
 
 export interface PlatformControllerDeps {
   /**
-   * Temporal coordinates this server runs against, published to embedded
-   * runners. In OSS the server and its runners are co-located, so the
-   * address the server itself dials is the one runners should dial too —
-   * no internal/external split (unlike Stigmer Cloud).
+   * The Temporal coordinates published to embedded runners. The address
+   * is the one a runner should dial, which is not always the one this
+   * server dials: a clustered server reaches Temporal by an internal name
+   * its desktop runners cannot resolve (stigmer#1357). The composition
+   * root passes config.runnerBootstrapTemporalAddress, which defaults to
+   * the server's own address; the namespace is the server's.
    */
-  readonly temporalHostPort: string;
+  readonly runnerBootstrapTemporalAddress: string;
   readonly temporalNamespace: string;
   /**
    * Mints the execution-scoped tokens getRunnerScopedToken hands to
@@ -202,7 +204,9 @@ async function getLicenseStatus(
 
 /**
  * Go GetRunnerBootstrapConfig: the Temporal coordinates an embedded runner
- * should connect to so it can self-bootstrap from a token alone. The
+ * should connect to so it can self-bootstrap from a token alone: the
+ * address deps name for runners, never assumed to be the server's own
+ * (the proto's "the one reachable by the caller"). The
  * RunnerAccessToken / TokenType / RunnerAccessTokenExpiresInSeconds fields
  * are intentionally left empty in OSS: minting an iss=stigmer proxy token
  * is a cloud-only capability (OSS has no Cursor BiDi proxy to authenticate
@@ -221,7 +225,7 @@ async function getRunnerBootstrapConfig(
   ctx: HandlerContext,
 ): Promise<GetRunnerBootstrapConfigOutput> {
   const output = create(GetRunnerBootstrapConfigOutputSchema, {
-    temporalAddress: deps.temporalHostPort,
+    temporalAddress: deps.runnerBootstrapTemporalAddress,
     temporalNamespace: deps.temporalNamespace,
   });
   const bootstrapCredentials =