@stigmer/runner 3.10.0 → 3.11.0

package/src/__tests__/preflight.test.ts

@@ -11,8 +11,12 @@
  *   the desktop Run dialog via the IPC handshake.
  */
 
-import { describe, expect, it } from "vitest";
-import { isNodeSqliteAvailable, preflightNodeRuntime } from "../preflight.js";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import {
+  isNodeSqliteAvailable,
+  preflightNodeRuntime,
+  assertLlmBackendsPreflight,
+} from "../preflight.js";
 
 describe("preflightNodeRuntime", () => {
   it("passes (returns null) when node:sqlite is available", () => {
@@ -39,3 +43,47 @@ describe("preflightNodeRuntime", () => {
     expect(preflightNodeRuntime() === null).toBe(isNodeSqliteAvailable());
   });
 });
+
+describe("assertLlmBackendsPreflight", () => {
+  // This is the gate both runner factories run at construction — the throw
+  // is what a misconfigured deployment sees instead of accepting work. The
+  // per-case parse/prereq tables live in shared/__tests__/llm-backend.test.ts;
+  // here we pin the wrapper's contract: throw on fatal, warn on precedence,
+  // silent when clean, and options-proxy treated like the env proxy.
+  afterEach(() => {
+    vi.unstubAllEnvs();
+    vi.restoreAllMocks();
+  });
+
+  /** Pin the vars this gate reads so ambient shell env cannot leak in. */
+  function stubBackendEnv(vars: Record<string, string>) {
+    vi.stubEnv("STIGMER_PROXY_ENDPOINT", "");
+    vi.stubEnv("STIGMER_ANTHROPIC_BACKEND", "");
+    vi.stubEnv("STIGMER_OPENAI_BACKEND", "");
+    vi.stubEnv("CLOUD_ML_REGION", "");
+    for (const [key, value] of Object.entries(vars)) {
+      vi.stubEnv(key, value);
+    }
+  }
+
+  it("passes silently for an unconfigured deployment", () => {
+    stubBackendEnv({});
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    expect(() => assertLlmBackendsPreflight(null)).not.toThrow();
+    expect(warn).not.toHaveBeenCalled();
+  });
+
+  it("throws the actionable message for a misconfigured backend", () => {
+    stubBackendEnv({ STIGMER_ANTHROPIC_BACKEND: "vertex" });
+    expect(() => assertLlmBackendsPreflight(null)).toThrow(/CLOUD_ML_REGION/);
+  });
+
+  it("warns instead of throwing when an options-supplied proxy makes the var inert", () => {
+    stubBackendEnv({ STIGMER_ANTHROPIC_BACKEND: "vertex" });
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    expect(() => assertLlmBackendsPreflight("https://api.stigmer.ai")).not.toThrow();
+    expect(warn).toHaveBeenCalledWith(
+      expect.stringContaining("STIGMER_ANTHROPIC_BACKEND=vertex is ignored"),
+    );
+  });
+});

package/src/activities/__tests__/call-llm.test.ts

@@ -5,6 +5,45 @@ import { _resetRegistryCache } from "../../shared/model-registry.js";
 const originalFetch = globalThis.fetch;
 const originalEnv = { ...process.env };
 
+const { vertexCreateRequests } = vi.hoisted(() => ({
+  vertexCreateRequests: [] as Array<Record<string, unknown>>,
+}));
+
+// Mocked at the SDK class (the vertex-adapter.test.ts pattern) so no real
+// google-auth credential resolution ever runs inside a unit test — locally
+// it fails fast, but in CI it can probe the GCE metadata server. ChatAnthropic
+// consumes the client's parsed event stream, so the streaming arm returns a
+// plain async generator of Anthropic stream events.
+vi.mock("@anthropic-ai/vertex-sdk", () => ({
+  AnthropicVertex: class {
+    readonly messages = {
+      create: async (request: Record<string, unknown>) => {
+        vertexCreateRequests.push(request);
+        if (request.stream === true) {
+          return (async function* () {
+            yield { type: "message_start", message: { id: "msg_vertex_call_llm", type: "message", role: "assistant", model: request.model, content: [], stop_reason: null, stop_sequence: null, usage: { input_tokens: 11, output_tokens: 1 } } };
+            yield { type: "content_block_start", index: 0, content_block: { type: "text", text: "" } };
+            yield { type: "content_block_delta", index: 0, delta: { type: "text_delta", text: "Vertex direct." } };
+            yield { type: "content_block_stop", index: 0 };
+            yield { type: "message_delta", delta: { stop_reason: "end_turn", stop_sequence: null }, usage: { output_tokens: 4 } };
+            yield { type: "message_stop" };
+          })();
+        }
+        return {
+          id: "msg_vertex_call_llm",
+          type: "message",
+          role: "assistant",
+          model: request.model,
+          content: [{ type: "text", text: "Vertex direct." }],
+          stop_reason: "end_turn",
+          stop_sequence: null,
+          usage: { input_tokens: 11, output_tokens: 4 },
+        };
+      },
+    };
+  },
+}));
+
 describe("callLlmAction", () => {
   let mockFetch: ReturnType<typeof vi.fn>;
 
@@ -16,6 +55,12 @@ describe("callLlmAction", () => {
     delete process.env.STIGMER_TOKEN;
     delete process.env.OPENAI_API_KEY;
     delete process.env.ANTHROPIC_API_KEY;
+    // Deterministic regardless of the developer's shell: a leaked
+    // STIGMER_ANTHROPIC_BACKEND=vertex would reroute every direct-mode test.
+    delete process.env.STIGMER_ANTHROPIC_BACKEND;
+    delete process.env.STIGMER_OPENAI_BACKEND;
+    delete process.env.CLOUD_ML_REGION;
+    vertexCreateRequests.length = 0;
   });
 
   afterEach(() => {
@@ -234,6 +279,36 @@ describe("callLlmAction", () => {
     });
   });
 
+  describe("direct mode — Anthropic on the vertex backend", () => {
+    it("serves the call with no ANTHROPIC_API_KEY anywhere (ADC is the credential path)", async () => {
+      // The regression pin for the backend-blind key check: a correctly
+      // configured Vertex deployment holds no Anthropic key, and llm_call
+      // tasks must not fail with LLM_MISSING_API_KEY before construction.
+      process.env.STIGMER_ANTHROPIC_BACKEND = "vertex";
+      process.env.CLOUD_ML_REGION = "global";
+      mockFetchWithRegistry(() => {
+        throw new Error("unexpected fetch: vertex traffic must go through the SDK client");
+      });
+
+      const result = await callLlmAction(baseAnthropicConfig, {}, "exec-1");
+
+      expect(result.result).toBe("Vertex direct.");
+      expect(result.provider).toBe("anthropic");
+      expect(result.input_tokens).toBe(11);
+      expect(result.output_tokens).toBe(4);
+      expect(vertexCreateRequests.length).toBeGreaterThan(0);
+    });
+
+    it("keeps the LLM_MISSING_API_KEY contract on the public backend, now naming the backend remedy", async () => {
+      const err = await callLlmAction(baseAnthropicConfig, {}, "exec-1").catch((e: unknown) => e as Error & { type?: string });
+
+      expect(err).toBeInstanceOf(Error);
+      expect((err as { type?: string }).type).toBe("LLM_MISSING_API_KEY");
+      expect((err as Error).message).toContain("ANTHROPIC_API_KEY");
+      expect((err as Error).message).toContain("STIGMER_ANTHROPIC_BACKEND=vertex");
+    });
+  });
+
   describe("proxy mode", () => {
     it("routes through proxy when endpoint is set", async () => {
       process.env.STIGMER_PROXY_ENDPOINT = "https://proxy.stigmer.ai";

package/src/activities/__tests__/classify-tool-approvals.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect, vi, beforeEach } from "vitest";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
 import type { ClassifyToolApprovalsInput, ToolDescriptor } from "../classify-tool-approvals.js";
 
 vi.mock("../../idle-watchdog.js", () => ({
@@ -597,6 +597,122 @@ describe("ClassifyToolApprovals activity", () => {
       expect(headers).not.toHaveProperty("X-Stigmer-Mcp-Server-Id");
     });
   });
+
+  describe("direct mode (no proxy)", () => {
+    // The regression suite for the stigmerBackendEndpoint-as-LLM-proxy bug:
+    // an unproxied runner must call the provider directly with the real key,
+    // and must fail closed with one clear message when it has none.
+    const directOptions = { proxyEndpoint: null, stigmerToken: null, primaryModel: "gpt-4.1" };
+
+    beforeEach(() => {
+      // Deterministic regardless of the developer's shell: blank reads as
+      // missing, and backend/proxy vars must not leak in from outside.
+      vi.stubEnv("OPENAI_API_KEY", "");
+      vi.stubEnv("ANTHROPIC_API_KEY", "");
+      vi.stubEnv("STIGMER_ANTHROPIC_BACKEND", "");
+      vi.stubEnv("STIGMER_OPENAI_BACKEND", "");
+      vi.stubEnv("STIGMER_PROXY_ENDPOINT", "");
+    });
+
+    afterEach(() => {
+      vi.unstubAllEnvs();
+    });
+
+    it("fails closed without any credential path: every tool gated, no client constructed", async () => {
+      const { ChatAnthropic } = await import("@langchain/anthropic");
+      const { ChatOpenAI } = await import("@langchain/openai");
+      const { classifyTools } = await import("../classify-tool-approvals.js");
+      const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+
+      const tools: ToolDescriptor[] = [
+        { name: "search_code", description: "Search code" },
+        { name: "delete_file", description: "Delete a file" },
+      ];
+
+      const result = await classifyTools(
+        { tools, serverName: "github", serverDescription: "GitHub", mcpServerId: null },
+        directOptions,
+      );
+
+      expect(result).toEqual([
+        { tool_name: "search_code", requires_approval: true, message: "Execute search_code" },
+        { tool_name: "delete_file", requires_approval: true, message: "Execute delete_file" },
+      ]);
+      expect(ChatOpenAI).not.toHaveBeenCalled();
+      expect(ChatAnthropic).not.toHaveBeenCalled();
+      expect(mockInvoke).not.toHaveBeenCalled();
+      // The message must name the model and provider (classification's
+      // provider follows the economy model, not the operator's key) and
+      // carry the predicate's remedy text.
+      expect(warn).toHaveBeenCalledWith(expect.stringContaining("'gpt-4o-mini' (openai)"));
+      expect(warn).toHaveBeenCalledWith(expect.stringContaining("OPENAI_API_KEY"));
+      warn.mockRestore();
+    });
+
+    it("uses the provider key directly — no proxy baseURL, no Authorization header", async () => {
+      vi.stubEnv("OPENAI_API_KEY", "sk-direct-test");
+      const { ChatOpenAI } = await import("@langchain/openai");
+      const { classifyTools } = await import("../classify-tool-approvals.js");
+
+      mockInvoke.mockResolvedValueOnce({
+        approvals: [{ tool_name: "t", requires_approval: false, message: "" }],
+      });
+
+      const result = await classifyTools(
+        { tools: [{ name: "t", description: "d" }], serverName: "s", serverDescription: "", mcpServerId: null },
+        directOptions,
+      );
+
+      expect(result).toEqual([]);
+      const args = vi.mocked(ChatOpenAI).mock.calls.at(-1)?.[0] as Record<string, unknown>;
+      expect(args.apiKey).toBe("sk-direct-test");
+      // The bug this suite pins: the gRPC control-plane endpoint must never
+      // reappear as a baseURL/Authorization transport override.
+      expect(args).not.toHaveProperty("configuration");
+    });
+
+    it("routes an Anthropic economy model directly through ChatAnthropic with the real key", async () => {
+      vi.stubEnv("ANTHROPIC_API_KEY", "sk-ant-direct");
+      const { ChatAnthropic } = await import("@langchain/anthropic");
+      const { getSummarizationModel } = await import("../../shared/model-registry.js");
+      vi.mocked(getSummarizationModel).mockResolvedValueOnce("claude-haiku-4.5");
+      const { classifyTools } = await import("../classify-tool-approvals.js");
+
+      mockInvoke.mockResolvedValueOnce({
+        approvals: [{ tool_name: "t", requires_approval: false, message: "" }],
+      });
+
+      await classifyTools(
+        { tools: [{ name: "t", description: "d" }], serverName: "s", serverDescription: "", mcpServerId: null },
+        directOptions,
+      );
+
+      const args = vi.mocked(ChatAnthropic).mock.calls.at(-1)?.[0] as Record<string, unknown>;
+      expect(args.apiKey).toBe("sk-ant-direct");
+      expect(args).not.toHaveProperty("clientOptions");
+    });
+
+    it("defers an un-inferable economy model to the per-batch fail-closed path", async () => {
+      // Real scenario: the registry-empty fallback returns the primary model
+      // verbatim (model-registry.ts), whatever its name. The pre-check must
+      // not guess a provider — the batch path owns the precise error.
+      const { getSummarizationModel } = await import("../../shared/model-registry.js");
+      vi.mocked(getSummarizationModel).mockResolvedValueOnce("mystery-model");
+      const { classifyTools } = await import("../classify-tool-approvals.js");
+      const error = vi.spyOn(console, "error").mockImplementation(() => {});
+
+      const result = await classifyTools(
+        { tools: [{ name: "t", description: "d" }], serverName: "s", serverDescription: "", mcpServerId: null },
+        directOptions,
+      );
+
+      expect(result).toEqual([
+        { tool_name: "t", requires_approval: true, message: "Execute t" },
+      ]);
+      expect(error).toHaveBeenCalled();
+      error.mockRestore();
+    });
+  });
 });
 
 // ─────────────────────────────────────────────────────────────────────────────

package/src/activities/__tests__/discover-mcp-server.hang.test.ts

@@ -0,0 +1,103 @@
+/**
+ * Regression pin for issue #239's hang mechanism, against the REAL MCP client
+ * stack (no @langchain/mcp-adapters mock — that's why this lives in its own
+ * file, apart from discover-mcp-server.test.ts's mocked suite).
+ *
+ * The monday.com failure shape: the endpoint answers the streamable-HTTP
+ * initialize POST with a 4xx, mcp-adapters automatically falls back to SSE at
+ * the same URL, the endpoint accepts the stream and never sends the legacy
+ * `endpoint` event — and the MCP SDK's SSEClientTransport has no timer of its
+ * own, so initialization hangs forever. Before the transport-aware init bound,
+ * that hang rode until Temporal killed the activity opaquely; this test pins
+ * that discovery now fails fast (in fake time) with an error that names the
+ * endpoint.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { createServer, type Server } from "node:http";
+
+vi.mock("../../idle-watchdog.js", () => ({
+  activityStarted: vi.fn(),
+  activityFinished: vi.fn(),
+}));
+
+// classifyHttpOAuthFailure re-probes the endpoint on the failure path; keep it
+// deterministic here (its own behavior is covered by mcp-oauth-detect tests).
+vi.mock("../../shared/mcp-oauth-detect.js", () => ({
+  detectOAuthChallenge: vi.fn().mockResolvedValue(null),
+}));
+
+describe("discovery against a 4xx-then-silent-SSE endpoint (issue #239)", () => {
+  let server: Server;
+  let url: string;
+
+  beforeEach(async () => {
+    server = createServer((req, res) => {
+      if (req.method === "POST") {
+        // monday-shaped: reject the streamable-HTTP initialize outright.
+        res.writeHead(405, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ error: "method not allowed" }));
+        return;
+      }
+      // The SSE fallback: accept the stream, never send an `endpoint` event.
+      res.writeHead(200, {
+        "Content-Type": "text/event-stream",
+        "Cache-Control": "no-cache",
+        Connection: "keep-alive",
+      });
+      res.write(": silent stream\n\n");
+    });
+    await new Promise<void>((resolve) => server.listen(0, "127.0.0.1", resolve));
+    const address = server.address();
+    if (typeof address === "string" || address === null) throw new Error("no port");
+    url = `http://127.0.0.1:${address.port}/mcp`;
+  });
+
+  afterEach(() => {
+    // closeAllConnections: the hung SSE stream is a live socket that would
+    // otherwise keep server.close() (and the vitest worker) waiting.
+    server.closeAllConnections();
+    server.close();
+    vi.useRealTimers();
+  });
+
+  it("fails within the HTTP init bound with an endpoint-naming error", async () => {
+    const { discoverMcpServer } = await import("../discover-mcp-server.js");
+
+    const stigmerClient = {
+      getMcpServer: vi.fn().mockResolvedValue({
+        metadata: { slug: "monday", id: "mcp-monday" },
+        spec: {
+          serverType: {
+            case: "http",
+            value: { url, headers: {}, queryParams: {}, timeoutSeconds: 0 },
+          },
+          env: {},
+          pinnedToolApprovals: [],
+        },
+        status: undefined,
+      }),
+      getExecutionContextByExecutionId: vi.fn(),
+    };
+
+    // shouldAdvanceTime keeps real I/O flowing (the POST → 405 → SSE fallback
+    // happens over real sockets) while letting the test jump the 60s bound.
+    vi.useFakeTimers({ shouldAdvanceTime: true });
+
+    const promise = discoverMcpServer(
+      { mcpServerId: "mcp-monday" },
+      { stigmerClient: stigmerClient as never, transportPosture: "stdio-forbidden" },
+    );
+    // Attach the rejection expectation BEFORE advancing so the rejection is
+    // never momentarily unhandled.
+    const expectation = expect(promise).rejects.toThrow(
+      new RegExp(`at ${url.replaceAll(".", "\\.")}.*did not complete MCP initialization`, "s"),
+    );
+
+    // Give the real client a beat to reach the hang (POST + fallback), then
+    // jump past the 30s HTTP bound in fake time.
+    await new Promise((resolve) => setTimeout(resolve, 250));
+    await vi.advanceTimersByTimeAsync(31_000);
+
+    await expectation;
+  }, 15_000);
+});

package/src/activities/__tests__/discover-mcp-server.test.ts

@@ -10,6 +10,14 @@ vi.mock("../../idle-watchdog.js", () => ({
   activityFinished: vi.fn(),
 }));
 
+// The factory starts a Temporal heartbeat loop; outside an activity context
+// its ticks would throw, so replace it with a stop-spy and assert the
+// start/stop contract instead.
+const mockHeartbeatStop = vi.fn();
+vi.mock("../../shared/heartbeat.js", () => ({
+  startHeartbeat: vi.fn(() => ({ stop: mockHeartbeatStop, cancelled: false, workerShutdown: false })),
+}));
+
 const mockInitializeConnections = vi.fn();
 const mockGetClient = vi.fn();
 const mockClose = vi.fn().mockResolvedValue(undefined);
@@ -600,6 +608,122 @@ describe("DiscoverMcpServer activity", () => {
       expect(result.newToolsFingerprint).toBe("");
     });
 
+    it("fails closed when the EC read errors and the server requires credentials", async () => {
+      // Issue #239: limping ahead with an empty env either died later as an
+      // opaque PlaceholderResolutionError or dialed the endpoint with a
+      // garbage credential and wedged in the 4xx → SSE-fallback limbo. The
+      // failure must name the root cause: credential delivery.
+      const { discoverMcpServer, CredentialResolutionError } = await import("../discover-mcp-server.js");
+
+      const spec = makeHttpSpec("https://mcp.monday.com/mcp");
+      spec.env = { MONDAY_ACCESS_TOKEN: { isSecret: true } };
+      const mockClient = makeMockStigmerClient({
+        mcpServer: makeMcpServer({ metadata: { slug: "monday" }, spec }),
+      });
+      mockClient.getExecutionContextByExecutionId = vi
+        .fn()
+        .mockRejectedValue(new Error("PERMISSION_DENIED: not scope-bound"));
+
+      await expect(
+        discoverMcpServer(
+          { mcpServerId: "mcp-monday", executionContextId: "ctx-1" },
+          { stigmerClient: mockClient as any, transportPosture: "stdio-forbidden" },
+        ),
+      ).rejects.toThrow(CredentialResolutionError);
+      expect(mockInitializeConnections).not.toHaveBeenCalled();
+    });
+
+    it("keeps the lenient path when the EC read errors but no env is declared", async () => {
+      const { discoverMcpServer } = await import("../discover-mcp-server.js");
+
+      const mockClient = makeMockStigmerClient({
+        mcpServer: makeMcpServer({
+          metadata: { slug: "no-env" },
+          spec: makeHttpSpec("https://mcp.example.com"),
+        }),
+      });
+      mockClient.getExecutionContextByExecutionId = vi
+        .fn()
+        .mockRejectedValue(new Error("transient"));
+
+      mockInitializeConnections.mockResolvedValue({});
+      mockGetClient.mockResolvedValue(makeMockMcpClient({ tools: [] }));
+
+      const result = await discoverMcpServer(
+        { mcpServerId: "mcp-lenient", executionContextId: "ctx-2" },
+        { stigmerClient: mockClient as any, transportPosture: "stdio-forbidden" },
+      );
+      expect(result.tools).toEqual([]);
+    });
+
+    it("keeps the lenient path when all declared env vars are optional", async () => {
+      // Caller-identity-style servers declare only optional keys; discovery
+      // legitimately proceeds without an EC for them (the injections below
+      // resolveEnvVarsForDiscovery supply the values).
+      const { discoverMcpServer } = await import("../discover-mcp-server.js");
+
+      const spec = makeHttpSpec("https://mcp.example.com");
+      spec.env = { STIGMER_CALLER_IDENTITY_KIND: { optional: true } };
+      const mockClient = makeMockStigmerClient({
+        mcpServer: makeMcpServer({ metadata: { slug: "optional-only" }, spec }),
+      });
+      mockClient.getExecutionContextByExecutionId = vi
+        .fn()
+        .mockRejectedValue(new Error("transient"));
+
+      mockInitializeConnections.mockResolvedValue({});
+      mockGetClient.mockResolvedValue(makeMockMcpClient({ tools: [] }));
+
+      const result = await discoverMcpServer(
+        { mcpServerId: "mcp-optional", executionContextId: "ctx-3" },
+        { stigmerClient: mockClient as any, transportPosture: "stdio-forbidden" },
+      );
+      expect(result.tools).toEqual([]);
+    });
+
+    it("fails closed when the EC is empty and the server requires credentials", async () => {
+      const { discoverMcpServer, CredentialResolutionError } = await import("../discover-mcp-server.js");
+
+      const spec = makeHttpSpec("https://mcp.monday.com/mcp");
+      spec.env = { MONDAY_ACCESS_TOKEN: { isSecret: true } };
+      const mockClient = makeMockStigmerClient({
+        mcpServer: makeMcpServer({ metadata: { slug: "monday" }, spec }),
+        executionContext: { spec: { data: {} } },
+      });
+
+      const promise = discoverMcpServer(
+        { mcpServerId: "mcp-monday", executionContextId: "ctx-4" },
+        { stigmerClient: mockClient as any, transportPosture: "stdio-forbidden" },
+      );
+      await expect(promise).rejects.toThrow(CredentialResolutionError);
+      await expect(promise).rejects.toThrow(/delivered no credentials/);
+      expect(mockInitializeConnections).not.toHaveBeenCalled();
+    });
+
+    it("fails closed when a delivered credential is the redaction sentinel", async () => {
+      // A redacted value means the server-side decrypt gate refused this
+      // runner's credential class/scope — dialing with the literal sentinel
+      // can only produce a misleading 401 (the issue-#239 M2 mechanism).
+      const { discoverMcpServer, CredentialResolutionError } = await import("../discover-mcp-server.js");
+
+      const spec = makeHttpSpec("https://mcp.monday.com/mcp");
+      spec.env = { MONDAY_ACCESS_TOKEN: { isSecret: true } };
+      const mockClient = makeMockStigmerClient({
+        mcpServer: makeMcpServer({ metadata: { slug: "monday" }, spec }),
+        executionContext: {
+          spec: { data: { MONDAY_ACCESS_TOKEN: { value: "***REDACTED***", isSecret: true } } },
+        },
+      });
+
+      const promise = discoverMcpServer(
+        { mcpServerId: "mcp-monday", executionContextId: "ctx-5" },
+        { stigmerClient: mockClient as any, transportPosture: "stdio-forbidden" },
+      );
+      await expect(promise).rejects.toThrow(CredentialResolutionError);
+      await expect(promise).rejects.toThrow(/MONDAY_ACCESS_TOKEN.*delivered redacted|delivered redacted.*MONDAY_ACCESS_TOKEN/s);
+      expect(mockInitializeConnections).not.toHaveBeenCalled();
+    });
+
     it("closes MCP client even when discovery fails", async () => {
       const { discoverMcpServer } = await import("../discover-mcp-server.js");
 
@@ -620,6 +744,85 @@ describe("DiscoverMcpServer activity", () => {
     });
   });
 
+  // ─────────────────────────────────────────────────────────────────────────
+  // Transport-aware init bounds (issue #239)
+  // ─────────────────────────────────────────────────────────────────────────
+
+  describe("transport-aware init bounds", () => {
+    it("bounds HTTP endpoints at 30s and stdio at 270s", async () => {
+      // HTTP has no cold-start excuse: a healthy endpoint completes the MCP
+      // handshake in seconds, so a short bound converts the silent-SSE hang
+      // into a fast actionable failure. stdio keeps the cold-start allowance
+      // (issue #243). The OSS server's connect-workflow budget (connectTimeout,
+      // controller/connect.go — pinned there) is derived from the stdio bound
+      // + the classification floor, so both bounds stay reachable under it.
+      const { initTimeoutMsFor } = await import("../discover-mcp-server.js");
+      expect(initTimeoutMsFor("http")).toBe(30_000);
+      expect(initTimeoutMsFor("sse")).toBe(30_000);
+      expect(initTimeoutMsFor("stdio")).toBe(270_000);
+    });
+
+    it("names the endpoint URL in the HTTP timeout message", async () => {
+      const { initTimeoutMessageFor } = await import("../discover-mcp-server.js");
+      const message = initTimeoutMessageFor("monday", {
+        slug: "monday",
+        connectionType: "http",
+        url: "https://mcp.monday.com/mcp",
+        toolApprovals: [],
+        pinnedToolApprovals: [],
+        toolApprovalOverrides: [],
+        discoveredCapabilitiesEmpty: true,
+      });
+      expect(message).toContain("https://mcp.monday.com/mcp");
+      expect(message).toContain("30s");
+      expect(message).toContain("SSE fallback");
+    });
+
+    it("names the command in the stdio timeout message", async () => {
+      const { initTimeoutMessageFor } = await import("../discover-mcp-server.js");
+      const message = initTimeoutMessageFor("filesystem", {
+        slug: "filesystem",
+        connectionType: "stdio",
+        command: "npx",
+        toolApprovals: [],
+        pinnedToolApprovals: [],
+        toolApprovalOverrides: [],
+        discoveredCapabilitiesEmpty: true,
+      });
+      expect(message).toContain("npx");
+      expect(message).toContain("270s");
+      expect(message).toContain("cold start");
+    });
+  });
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // Heartbeat contract (issue #239)
+  // ─────────────────────────────────────────────────────────────────────────
+
+  describe("heartbeat contract", () => {
+    it("starts a heartbeat for the activity and stops it on completion", async () => {
+      // The connect workflow proxies this activity with a 60s heartbeatTimeout.
+      // Without a heartbeat loop, any discovery slower than 60s was killed by
+      // Temporal with an opaque heartbeat timeout — never reaching the
+      // actionable init-timeout errors (issues #239/#243).
+      const { createDiscoverMcpServerActivities } = await import("../discover-mcp-server.js");
+      const { startHeartbeat } = await import("../../shared/heartbeat.js");
+
+      vi.mocked(startHeartbeat).mockClear();
+      mockHeartbeatStop.mockClear();
+
+      const { DiscoverMcpServerCapabilities } = createDiscoverMcpServerActivities(makeConfig());
+      try {
+        await DiscoverMcpServerCapabilities({ mcpServerId: "test" });
+      } catch {
+        // Expected — no real backend behind the factory's own client.
+      }
+
+      expect(startHeartbeat).toHaveBeenCalledTimes(1);
+      expect(mockHeartbeatStop).toHaveBeenCalledTimes(1);
+    });
+  });
+
   // ─────────────────────────────────────────────────────────────────────────
   // Idle Watchdog Integration
   // ─────────────────────────────────────────────────────────────────────────