@stigmer/runner 3.10.0 → 3.11.0

package/src/activities/__tests__/workflow-event-activities.test.ts

@@ -7,11 +7,15 @@ import type { WorkflowEventDescriptor } from "../../workflow-engine/types.js";
 
 const mockGetEventLogHighWaterMark = vi.fn<(executionId: string) => Promise<bigint>>();
 const mockGetWorkflowExecution = vi.fn<(executionId: string) => Promise<unknown>>();
+const mockUpdateStatus = vi.fn<(input: unknown) => Promise<unknown>>();
 
 vi.mock("../../client/stigmer-client.js", () => ({
   StigmerClient: vi.fn().mockImplementation(() => ({
     getEventLogHighWaterMark: (...args: unknown[]) => mockGetEventLogHighWaterMark(...(args as [string])),
     getWorkflowExecution: (...args: unknown[]) => mockGetWorkflowExecution(...(args as [string])),
+    workflowExecutionCommand: {
+      updateStatus: (...args: unknown[]) => mockUpdateStatus(args[0]),
+    },
   })),
 }));
 
@@ -29,8 +33,9 @@ describe("initSequenceFromEventLog", () => {
     mockGetEventLogHighWaterMark.mockReset();
   });
 
-  it("sets counter to 0 when executionId is empty", async () => {
-    await initSequenceFromEventLog("");
+  it("returns 0 and resets the legacy counter when executionId is empty", async () => {
+    const highWaterMark = await initSequenceFromEventLog("");
+    expect(highWaterMark).toBe(0);
 
     const evt = toProtoEvent({
       type: "task_started",
@@ -43,10 +48,11 @@ describe("initSequenceFromEventLog", () => {
     expect(mockGetEventLogHighWaterMark).not.toHaveBeenCalled();
   });
 
-  it("sets counter to 0 when server returns no events", async () => {
+  it("returns 0 when server has no events", async () => {
     mockGetEventLogHighWaterMark.mockResolvedValue(BigInt(0));
 
-    await initSequenceFromEventLog("wfx_test-1");
+    const highWaterMark = await initSequenceFromEventLog("wfx_test-1");
+    expect(highWaterMark).toBe(0);
 
     const evt = toProtoEvent({
       type: "task_started",
@@ -58,7 +64,15 @@ describe("initSequenceFromEventLog", () => {
     expect(evt.sequenceNumber).toBe(BigInt(1));
   });
 
-  it("continues from high-water mark when events exist", async () => {
+  it("returns the high-water mark as a plain number (Temporal payload converter cannot carry BigInt)", async () => {
+    mockGetEventLogHighWaterMark.mockResolvedValue(BigInt(42));
+
+    const highWaterMark = await initSequenceFromEventLog("wfx_recovery-1");
+    expect(highWaterMark).toBe(42);
+    expect(typeof highWaterMark).toBe("number");
+  });
+
+  it("seeds the legacy counter so pre-patch replays continue from N+1", async () => {
     mockGetEventLogHighWaterMark.mockResolvedValue(BigInt(42));
 
     await initSequenceFromEventLog("wfx_recovery-1");
@@ -87,7 +101,8 @@ describe("initSequenceFromEventLog", () => {
   it("handles large sequence numbers", async () => {
     mockGetEventLogHighWaterMark.mockResolvedValue(BigInt(999999));
 
-    await initSequenceFromEventLog("wfx_large-seq");
+    const highWaterMark = await initSequenceFromEventLog("wfx_large-seq");
+    expect(highWaterMark).toBe(999999);
 
     const evt = toProtoEvent({
       type: "task_started",
@@ -112,7 +127,52 @@ describe("toProtoEvent", () => {
   });
 
   describe("sequence numbering", () => {
-    it("assigns monotonically increasing sequence numbers", () => {
+    it("honors the workflow-assigned sequenceNumber when stamped on the descriptor", () => {
+      const evt = toProtoEvent({
+        type: "task_started",
+        taskName: "t1",
+        occurredAt: NOW,
+        taskKind: "set",
+        attemptNumber: 1,
+        sequenceNumber: 77,
+      });
+
+      expect(evt.sequenceNumber).toBe(BigInt(77));
+    });
+
+    it("workflow-assigned sequences are stable across conversions (retry idempotency)", () => {
+      const desc: WorkflowEventDescriptor = {
+        type: "task_started",
+        taskName: "t1",
+        occurredAt: NOW,
+        taskKind: "set",
+        attemptNumber: 1,
+        sequenceNumber: 5,
+      };
+
+      // Simulates an activity retry re-converting the same descriptors:
+      // the sequence must not change between attempts.
+      expect(toProtoEvent(desc).sequenceNumber).toBe(BigInt(5));
+      expect(toProtoEvent(desc).sequenceNumber).toBe(BigInt(5));
+    });
+
+    it("a stamped descriptor does not consume the legacy counter", () => {
+      const unstamped: WorkflowEventDescriptor = {
+        type: "task_started",
+        taskName: "t",
+        occurredAt: NOW,
+        taskKind: "set",
+        attemptNumber: 1,
+      };
+
+      const e1 = toProtoEvent(unstamped);
+      toProtoEvent({ ...unstamped, sequenceNumber: 99 });
+      const e2 = toProtoEvent(unstamped);
+
+      expect(e2.sequenceNumber).toBe(e1.sequenceNumber + BigInt(1));
+    });
+
+    it("legacy path: assigns monotonically increasing sequence numbers when unstamped", () => {
       const desc: WorkflowEventDescriptor = {
         type: "task_started",
         taskName: "t1",
@@ -130,7 +190,7 @@ describe("toProtoEvent", () => {
       expect(e3.sequenceNumber).toBe(BigInt(3));
     });
 
-    it("resets to 1 after re-initializing with empty executionId", async () => {
+    it("legacy path: resets to 1 after re-initializing with empty executionId", async () => {
       toProtoEvent({
         type: "task_started",
         taskName: "t",
@@ -654,8 +714,13 @@ describe("toProtoEvent", () => {
 });
 
 describe("emitWorkflowEvents", () => {
+  beforeEach(() => {
+    mockUpdateStatus.mockReset();
+  });
+
   it("returns silently for empty events array", async () => {
     await expect(emitWorkflowEvents("exec-1", [])).resolves.toBeUndefined();
+    expect(mockUpdateStatus).not.toHaveBeenCalled();
   });
 
   it("returns silently for empty executionId", async () => {
@@ -667,6 +732,40 @@ describe("emitWorkflowEvents", () => {
       attemptNumber: 1,
     }];
     await expect(emitWorkflowEvents("", events)).resolves.toBeUndefined();
+    expect(mockUpdateStatus).not.toHaveBeenCalled();
+  });
+
+  it("sends workflow-assigned sequence numbers through to the RPC", async () => {
+    mockUpdateStatus.mockResolvedValue({});
+
+    await emitWorkflowEvents("exec-1", [{
+      type: "task_started",
+      taskName: "t",
+      occurredAt: NOW,
+      taskKind: "set",
+      attemptNumber: 1,
+      sequenceNumber: 12,
+    }]);
+
+    expect(mockUpdateStatus).toHaveBeenCalledTimes(1);
+    const input = mockUpdateStatus.mock.calls[0][0] as { events: { sequenceNumber: bigint }[] };
+    expect(input.events).toHaveLength(1);
+    expect(input.events[0].sequenceNumber).toBe(BigInt(12));
+  });
+
+  it("propagates RPC errors so the local activity retry policy fires", async () => {
+    mockUpdateStatus.mockRejectedValue(new Error("server unavailable"));
+
+    const events: WorkflowEventDescriptor[] = [{
+      type: "task_started",
+      taskName: "t",
+      occurredAt: NOW,
+      taskKind: "set",
+      attemptNumber: 1,
+      sequenceNumber: 1,
+    }];
+
+    await expect(emitWorkflowEvents("exec-1", events)).rejects.toThrow("server unavailable");
   });
 });
 

package/src/activities/call-llm.ts

@@ -31,6 +31,7 @@ import {
 import { computeLlmCostMicros, ensureLoaded as ensurePricingLoaded } from "../shared/model-pricing.js";
 import { resolveToApiModelId } from "../shared/model-registry.js";
 import { buildChatModel } from "../shared/model-client.js";
+import { checkDirectCredentials } from "../shared/llm-backend.js";
 import { classifyModelCallError } from "../shared/model-error.js";
 
 export interface LlmCallConfig {
@@ -169,23 +170,15 @@ export async function callLlmAction(
     `structured=${!!config.response_schema} execution=${executionId}`,
   );
 
-  // Direct mode (no proxy) requires the provider's own API key. Validated here
-  // rather than in buildChatModel so the shared module stays free of Temporal
-  // failure types.
+  // Direct mode (no proxy) requires a usable credential path — the provider's
+  // own API key, or a configured model backend that authenticates itself
+  // (vertex uses Google ADC; requiring an Anthropic key there would reject a
+  // correctly-configured deployment). Validated here rather than in
+  // buildChatModel so the shared module stays free of Temporal failure types.
   if (!proxyActive) {
-    if (provider === "openai" && !process.env.OPENAI_API_KEY) {
-      throw ApplicationFailure.nonRetryable(
-        `OPENAI_API_KEY is not set and no proxy is configured. ` +
-        `Set the API key in your environment or connect to a Stigmer Cloud deployment.`,
-        "LLM_MISSING_API_KEY",
-      );
-    }
-    if (provider === "anthropic" && !process.env.ANTHROPIC_API_KEY) {
-      throw ApplicationFailure.nonRetryable(
-        `ANTHROPIC_API_KEY is not set and no proxy is configured. ` +
-        `Set the API key in your environment or connect to a Stigmer Cloud deployment.`,
-        "LLM_MISSING_API_KEY",
-      );
+    const missing = checkDirectCredentials(provider);
+    if (missing !== null) {
+      throw ApplicationFailure.nonRetryable(missing, "LLM_MISSING_API_KEY");
     }
   }
 

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

@@ -23,6 +23,8 @@ import { SystemMessage, HumanMessage } from "@langchain/core/messages";
 import { activityStarted, activityFinished } from "../idle-watchdog.js";
 import { getSummarizationModel } from "../shared/model-registry.js";
 import { buildChatModel } from "../shared/model-client.js";
+import { checkDirectCredentials } from "../shared/llm-backend.js";
+import { tryInferProvider } from "../shared/llm-proxy.js";
 import type { Config } from "../config.js";
 
 const BATCH_SIZE = 40;
@@ -149,7 +151,8 @@ Output one classification per tool, maintaining the input order.`;
 // ─────────────────────────────────────────────────────────────────────────────
 
 export interface ClassifyToolsOptions {
-  proxyEndpoint: string;
+  /** Null when the deployment has no proxy — the runner calls providers directly. */
+  proxyEndpoint: string | null;
   stigmerToken: string | null;
   primaryModel: string;
 }
@@ -166,6 +169,26 @@ export async function classifyTools(
 
   const model = await getSummarizationModel(options.primaryModel);
 
+  // Direct mode with no credential path fails closed up front, with one
+  // actionable message instead of a provider 401 per batch. The message
+  // names the economy model and its provider because classification's
+  // provider follows the economy-model resolution, not the operator's key:
+  // "OPENAI_API_KEY is missing" is baffling to an operator holding an
+  // Anthropic key unless the log says which model classification wanted.
+  if (!options.proxyEndpoint) {
+    const provider = tryInferProvider(model);
+    const missing = provider === null ? null : checkDirectCredentials(provider);
+    if (missing !== null) {
+      console.warn(
+        `[ClassifyToolApprovals] Cannot classify ${tools.length} tool(s) for ` +
+        `'${serverName}': the classifier model '${model}' (${provider}) has no ` +
+        `credential path — failing closed, every tool requires approval until ` +
+        `a reconnect re-classifies it. ${missing}`,
+      );
+      return fallbackApprovals(tools);
+    }
+  }
+
   const batches: ToolDescriptor[][] = [];
   for (let i = 0; i < tools.length; i += BATCH_SIZE) {
     batches.push(tools.slice(i, i + BATCH_SIZE));
@@ -236,7 +259,7 @@ interface ClassifyBatchParams {
   serverName: string;
   serverDescription: string;
   model: string;
-  proxyEndpoint: string;
+  proxyEndpoint: string | null;
   stigmerToken: string | null;
   mcpServerId: string | null;
   batchIdx: number;
@@ -256,7 +279,7 @@ async function classifyBatch(params: ClassifyBatchParams): Promise<ToolApprovalR
   // primary this routes to Claude, not the hardcoded OpenAI path it used to.
   const { model: llm } = await buildChatModel({
     modelName: model,
-    proxyEndpoint,
+    proxyEndpoint: proxyEndpoint ?? undefined,
     stigmerToken: stigmerToken ?? undefined,
     headerScope: { mcpServerId: mcpServerId ?? undefined },
     maxTokens,
@@ -388,8 +411,15 @@ export function createClassifyToolApprovalsActivities(config: Config) {
           `[ClassifyToolApprovals] Activity started: ${input.tools.length} tools for '${input.serverName}'`,
         );
 
+        // Only a real proxy is an LLM proxy. stigmerBackendEndpoint (the
+        // gRPC control plane) serves no /v1/proxy/llm route — coercing it
+        // into one here used to 404 every classification in unproxied OSS
+        // and silently disable the vertex backend for this activity. (The
+        // registry fetch legitimately falls back to the backend endpoint —
+        // see shared/registry-endpoint.ts — because the control plane DOES
+        // serve /v1/proxy/model-registry; that fallback does not port here.)
         return await classifyTools(input, {
-          proxyEndpoint: config.proxyEndpoint ?? config.stigmerBackendEndpoint,
+          proxyEndpoint: config.proxyEndpoint,
           stigmerToken: config.stigmerToken,
           primaryModel: config.primaryModel,
         });

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

@@ -22,7 +22,7 @@ import { createHash } from "node:crypto";
 import { MultiServerMCPClient } from "@langchain/mcp-adapters";
 import { activityStarted, activityFinished } from "../idle-watchdog.js";
 import { StigmerClient } from "../client/stigmer-client.js";
-import { mcpServerToResolved } from "../shared/mcp-resolver.js";
+import { mcpServerToResolved, type ResolvedMcpServer } from "../shared/mcp-resolver.js";
 import { toMcpClientConfig } from "../shared/mcp-manager.js";
 import {
   assertTransportAllowed,
@@ -31,11 +31,44 @@ import {
 } from "../shared/mcp-transport-guard.js";
 import { detectOAuthChallenge } from "../shared/mcp-oauth-detect.js";
 import { injectAnonymousCallerIdentityForDiscovery } from "../shared/caller-identity.js";
+import { startHeartbeat } from "../shared/heartbeat.js";
 import { withTimeout } from "../shared/with-timeout.js";
 import type { McpServer } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import type { EnvVarDeclaration } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/spec_pb";
 import type { Config } from "../config.js";
 
-const SESSION_INIT_TIMEOUT_MS = 270_000;
+/**
+ * MCP session-init bounds, per transport (issue #239).
+ *
+ * A remote endpoint that accepts a connection but never completes the MCP
+ * handshake would otherwise hang initialization forever: the MCP SDK's SSE
+ * transport resolves only on the server's `endpoint` event, with no timer of
+ * its own, and mcp-adapters silently falls back to SSE whenever the
+ * streamable-HTTP POST is answered with a 4xx (monday.com's endpoint did
+ * exactly this — 4xx on POST, then a silently-open SSE stream).
+ *
+ * HTTP endpoints get a short bound: there is nothing to install or compile,
+ * so a healthy endpoint completes the handshake in seconds — a short bound is
+ * what converts the silent hang into a fast, actionable failure (with room for
+ * the 10s OAuth re-probe on the failure path). stdio servers keep the generous
+ * bound because their first run may compile or install packages (`go run`,
+ * `npx`) — the cold-start case (issue #243). The OSS server's connect-workflow
+ * run timeout (connectTimeout, controller/connect.go) is derived from the
+ * stdio bound + the classification floor, so both errors stay reachable.
+ */
+const HTTP_INIT_TIMEOUT_MS = 30_000;
+const STDIO_INIT_TIMEOUT_MS = 270_000;
+
+/**
+ * The server-side secret-redaction sentinel. Byte-for-byte the value both
+ * editions substitute for secret values a caller may not decrypt
+ * (`SecretEncryptionService.REDACTED_MARKER` in stigmer-cloud,
+ * `RedactedMarker` in the OSS Go server). Discovery dialing an
+ * endpoint with a redacted credential is guaranteed to fail confusingly
+ * (e.g. `Authorization: Bearer ***REDACTED***` → 401 → SSE-fallback limbo),
+ * so it is refused up front with an actionable error instead.
+ */
+const REDACTED_MARKER = "***REDACTED***";
 
 const PLATFORM_INJECTABLE_MAP: Record<string, string> = {
   STIGMER_SERVER_ADDRESS: "STIGMER_MCP_PUBLIC_ENDPOINT",
@@ -95,6 +128,28 @@ export interface ToolApprovalDict {
   message: string;
 }
 
+/**
+ * Raised when the credentials a server declares could not be delivered to
+ * discovery — the ExecutionContext read failed, came back empty, or returned
+ * redacted values (issue #239).
+ *
+ * Exists because the alternative is strictly worse: proceeding without the
+ * declared credentials either dies later as an opaque
+ * PlaceholderResolutionError (when a header/arg templates the missing var) or
+ * dials the endpoint with a garbage credential and strands the connect in the
+ * 4xx → SSE-fallback limbo this file's init bounds exist to contain. Failing
+ * here names the ROOT cause — credential delivery — instead of its downstream
+ * symptom. The message is user-facing and self-contained: it survives the
+ * Temporal boundary and the Go/Java connect wrappers include it in the
+ * user-facing failure text.
+ */
+export class CredentialResolutionError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "CredentialResolutionError";
+  }
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Tools Fingerprint (pure, deterministic, safe in workflow code)
 // ─────────────────────────────────────────────────────────────────────────────
@@ -242,14 +297,15 @@ export async function discoverMcpServer(
   const slug = mcpServer.metadata?.slug || mcpServerId;
   const previousState = extractPreviousState(mcpServer);
 
+  const declaredEnv = mcpServer.spec.env ?? {};
   const envVars = await resolveEnvVarsForDiscovery(
     stigmerClient,
     executionContextId ?? null,
+    slug,
+    declaredEnv,
   );
 
-  const declaredEnvKeys = mcpServer.spec.env
-    ? new Set(Object.keys(mcpServer.spec.env))
-    : new Set<string>();
+  const declaredEnvKeys = new Set(Object.keys(declaredEnv));
   const platformEnv = injectPlatformEnv(declaredEnvKeys, envVars);
 
   // Discovery runs with no session, so every declared caller-identity key
@@ -277,6 +333,7 @@ export async function discoverMcpServer(
   const { tools, resourceTemplates } = await connectAndDiscover(
     slug,
     connectionConfig,
+    resolved,
   );
 
   const newFp = toolsFingerprint(tools);
@@ -300,51 +357,144 @@ export async function discoverMcpServer(
 // Env Var Resolution
 // ─────────────────────────────────────────────────────────────────────────────
 
+/**
+ * Resolve the discovery env from the connect flow's ExecutionContext,
+ * failing CLOSED when a server's declared credentials cannot be delivered.
+ *
+ * The strictness is keyed on whether the server declares any NON-OPTIONAL
+ * env var ("credentials expected"):
+ *
+ * - Credentials expected + the EC read errors, or the EC is missing/empty →
+ *   {@link CredentialResolutionError}. The backend only creates a connect EC
+ *   when it resolved credentials to deliver, so an unreadable or empty EC is
+ *   a delivery failure (auth/scope refusal, transient backend error), never a
+ *   normal state. Limping ahead was issue #239's failure mode: discovery died
+ *   later as an opaque PlaceholderResolutionError or a doomed dial.
+ * - Any delivered value equal to the redaction sentinel →
+ *   {@link CredentialResolutionError}, regardless of optionality. A redacted
+ *   value means the server-side decrypt gate refused THIS runner's credential
+ *   class/scope and fell closed to redaction — dialing with the literal
+ *   sentinel can only produce a misleading 401.
+ * - No non-optional declarations → the old lenient path (warn and continue):
+ *   servers declaring nothing (or only optional/injected keys like the
+ *   caller-identity family) legitimately discover without an EC.
+ */
 async function resolveEnvVarsForDiscovery(
   client: StigmerClient,
   executionContextId: string | null,
+  slug: string,
+  declaredEnv: Record<string, EnvVarDeclaration>,
 ): Promise<Record<string, string>> {
+  const requiredKeys = Object.entries(declaredEnv)
+    .filter(([, decl]) => !decl.optional)
+    .map(([key]) => key);
+  const credentialsExpected = requiredKeys.length > 0;
+
   if (!executionContextId) return {};
 
+  let execCtx: Awaited<ReturnType<typeof client.getExecutionContextByExecutionId>>;
   try {
-    const execCtx = await client.getExecutionContextByExecutionId(
-      executionContextId,
-    );
-
-    if (!execCtx?.spec?.data || Object.keys(execCtx.spec.data).length === 0) {
-      console.warn(
-        `[DiscoverMcpServer] ExecutionContext '${executionContextId}' not found ` +
-        `or empty — MCP server may not require environment variables`,
+    execCtx = await client.getExecutionContextByExecutionId(executionContextId);
+  } catch (err) {
+    const cause = err instanceof Error ? err.message : String(err);
+    if (credentialsExpected) {
+      throw new CredentialResolutionError(
+        `Could not resolve the credentials MCP server '${slug}' requires ` +
+        `(${requiredKeys.join(", ")}): the connect credential store was ` +
+        `unreadable (${cause}). This is a platform-side delivery failure, ` +
+        `not a problem with your credentials — retry the connect, and if it ` +
+        `persists, re-run the OAuth sign-in or re-enter the credentials.`,
       );
-      return {};
     }
+    console.warn(
+      `[DiscoverMcpServer] Failed to resolve ExecutionContext '${executionContextId}': ` +
+      `${cause}`,
+    );
+    return {};
+  }
 
-    const envVars: Record<string, string> = {};
-    for (const [key, execValue] of Object.entries(execCtx.spec.data)) {
-      envVars[key] = execValue.value;
+  const data = execCtx?.spec?.data ?? {};
+  if (Object.keys(data).length === 0) {
+    if (credentialsExpected) {
+      throw new CredentialResolutionError(
+        `MCP server '${slug}' requires ${requiredKeys.join(", ")}, but the ` +
+        `connect flow delivered no credentials. Re-run the OAuth sign-in ` +
+        `(or re-enter the credentials) and connect again.`,
+      );
     }
-
-    console.log(
-      `[DiscoverMcpServer] Resolved ${Object.keys(envVars).length} env var(s) ` +
-      `from ExecutionContext '${executionContextId}'`,
-    );
-    return envVars;
-  } catch (err) {
     console.warn(
-      `[DiscoverMcpServer] Failed to resolve ExecutionContext '${executionContextId}': ` +
-      `${err instanceof Error ? err.message : err}`,
+      `[DiscoverMcpServer] ExecutionContext '${executionContextId}' not found ` +
+      `or empty — MCP server may not require environment variables`,
     );
     return {};
   }
+
+  const redactedKeys = Object.entries(data)
+    .filter(([, execValue]) => execValue.value === REDACTED_MARKER)
+    .map(([key]) => key);
+  if (redactedKeys.length > 0) {
+    throw new CredentialResolutionError(
+      `The credentials for MCP server '${slug}' were delivered redacted ` +
+      `(${redactedKeys.join(", ")}): the platform refused to decrypt them ` +
+      `for this runner. This is a platform-side authorization failure — ` +
+      `retry the connect, and report it if it persists.`,
+    );
+  }
+
+  const envVars: Record<string, string> = {};
+  for (const [key, execValue] of Object.entries(data)) {
+    envVars[key] = execValue.value;
+  }
+
+  console.log(
+    `[DiscoverMcpServer] Resolved ${Object.keys(envVars).length} env var(s) ` +
+    `from ExecutionContext '${executionContextId}'`,
+  );
+  return envVars;
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
 // MCP Connection + Enumeration
 // ─────────────────────────────────────────────────────────────────────────────
 
+/**
+ * Pick the session-init bound for a resolved server's transport.
+ *
+ * Exported for tests; pure so the timeout choice (the load-bearing half of
+ * the issue-#239 fix) can be pinned without wiring a slow clock.
+ */
+export function initTimeoutMsFor(connectionType: ResolvedMcpServer["connectionType"]): number {
+  return connectionType === "stdio" ? STDIO_INIT_TIMEOUT_MS : HTTP_INIT_TIMEOUT_MS;
+}
+
+/**
+ * The user-facing message for a session-init timeout. Names the endpoint (or
+ * command) so the failure is diagnosable from the message alone, and explains
+ * the known silent-hang shape for HTTP endpoints — issue #239's mechanism.
+ */
+export function initTimeoutMessageFor(slug: string, resolved: ResolvedMcpServer): string {
+  const seconds = Math.round(initTimeoutMsFor(resolved.connectionType) / 1000);
+  if (resolved.connectionType === "stdio") {
+    return (
+      `MCP server '${slug}' (command: ${resolved.command}) did not complete ` +
+      `MCP initialization within ${seconds}s. If this server requires ` +
+      `compilation or package installation on first run (e.g. go run, npx), ` +
+      `the cold start may have exceeded the discovery timeout.`
+    );
+  }
+  return (
+    `MCP server '${slug}' at ${resolved.url} did not complete MCP ` +
+    `initialization within ${seconds}s. The endpoint accepted the connection ` +
+    `but never finished the handshake — commonly an endpoint that rejects ` +
+    `streamable HTTP while leaving its SSE fallback stream silently open. ` +
+    `Verify the URL points at a live streamable-HTTP MCP endpoint.`
+  );
+}
+
 async function connectAndDiscover(
   slug: string,
   connectionConfig: ReturnType<typeof toMcpClientConfig>,
+  resolved: ResolvedMcpServer,
 ): Promise<{
   tools: DiscoveredToolResult[];
   resourceTemplates: DiscoveredResourceTemplateResult[];
@@ -354,12 +504,10 @@ async function connectAndDiscover(
   const resourceTemplates: DiscoveredResourceTemplateResult[] = [];
 
   try {
-    const timeoutMessage =
-      `MCP server '${slug}' did not respond within ` +
-      `${Math.round(SESSION_INIT_TIMEOUT_MS / 1000)}s. If this server requires compilation or ` +
-      `package installation on first run (e.g. go run, npx), the cold ` +
-      `start may have exceeded the discovery timeout.`;
-    await withTimeout(SESSION_INIT_TIMEOUT_MS, timeoutMessage, async () => {
+    await withTimeout(
+      initTimeoutMsFor(resolved.connectionType),
+      () => initTimeoutMessageFor(slug, resolved),
+      async () => {
       await client.initializeConnections();
 
       const mcpClient = await client.getClient(slug);
@@ -461,12 +609,22 @@ export function createDiscoverMcpServerActivities(config: Config) {
       input: DiscoverMcpServerInput,
     ): Promise<DiscoverMcpServerOutput> => {
       activityStarted();
+      // The connect workflow proxies this activity with a 60s heartbeatTimeout,
+      // so it MUST heartbeat: before this loop existed, any discovery slower
+      // than 60s (stdio cold start — issue #243) or wedged on a silent remote
+      // (issue #239) was killed by Temporal with an opaque heartbeat timeout
+      // instead of reaching this file's actionable init-timeout errors.
+      const hb = startHeartbeat(15_000, () => ({
+        phase: "discovering_mcp_server",
+        mcpServerId: input.mcpServerId,
+      }));
       try {
         return await discoverMcpServer(input, {
           stigmerClient,
           transportPosture: resolveMcpTransportPosture(config.mode),
         });
       } finally {
+        hb.stop();
         activityFinished();
       }
     },

package/src/activities/execute-cursor/__test-utils__/cursor-hook-harness.ts

@@ -108,6 +108,14 @@ export interface CursorHookHarnessOptions {
    * non-pausing "unattended" kind and the adapt-and-explain agent message.
    */
   unattendedSkip?: boolean;
+  /**
+   * Per-server enabled_tools allow-lists (issue #350) — restricted servers
+   * only. The hook's manifest arm denies a beforeMCPExecution call whose
+   * mcp_server_name is listed here with a tool name outside its list (kind
+   * "disabled", ahead of every approval bypass). hookMcp payloads carry
+   * mcp_server_name "srv".
+   */
+  mcpServerEnabledTools?: Record<string, string[]>;
 }
 
 /**
@@ -170,6 +178,7 @@ export function setupCursorHookHarness(opts: CursorHookHarnessOptions = {}): Cur
       opts.captureIgnored ?? false,
       opts.gitWorkspace ?? true,
       opts.unattendedSkip ?? false,
+      opts.mcpServerEnabledTools ?? {},
     );
     writeFileSync(statePath, JSON.stringify(state), "utf-8");
   }

package/src/activities/execute-cursor/__tests__/approval-gate.test.ts

@@ -219,6 +219,20 @@ describe("buildApprovalState", () => {
     expect((state as unknown as Record<string, unknown>).builtInGatedList).toBeUndefined();
   });
 
+  it("carries the enabled_tools manifest (issue #350) and defaults it to empty", () => {
+    // Default: no restriction — the hook's disabled arm is inert.
+    const bare = buildApprovalState(mcpPolicies, false, new Set());
+    expect(bare.mcpServerEnabledTools).toEqual({});
+
+    // Restricted servers ride through verbatim for the hook's server-scoped
+    // membership check.
+    const restricted = buildApprovalState(
+      mcpPolicies, false, new Set(), undefined, false, false, true, false,
+      { planton: ["get_cloud_resource"] },
+    );
+    expect(restricted.mcpServerEnabledTools).toEqual({ planton: ["get_cloud_resource"] });
+  });
+
   it("emits the CONTENT token when a grant carries a content digest", () => {
     const grants = [{ toolName: "edit", mcpServerSlug: "", key: "write", salient: "/x/gated.txt", contentDigest: "deadbeef", sourceToolCallId: "consent-1" }];
     const state = buildApprovalState(mcpPolicies, false, new Set(), grants);