@stigmer/runner 3.10.0 → 3.11.1-dev.20260812192248

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);
@@ -408,7 +416,45 @@ describe("DiscoverMcpServer activity", () => {
       );
 
       expect(result.tools).toEqual([]);
-      expect(mockClient.getExecutionContextByExecutionId).toHaveBeenCalledWith("ctx-abc");
+      // No payload-carried token -> the read goes out without a per-call
+      // credential (the cloud shape, where the ambient credential applies).
+      expect(mockClient.getExecutionContextByExecutionId).toHaveBeenCalledWith("ctx-abc", undefined);
+    });
+
+    it("presents the payload-carried EC token on the ExecutionContext read (oss#535)", async () => {
+      const { discoverMcpServer } = await import("../discover-mcp-server.js");
+
+      const mockClient = makeMockStigmerClient({
+        mcpServer: makeMcpServer({
+          metadata: { slug: "with-token" },
+          spec: makeStdioSpec("npx", ["server"]),
+        }),
+        executionContext: {
+          spec: {
+            data: {
+              API_KEY: { value: "secret-123", isSecret: true },
+            },
+          },
+        },
+      });
+
+      const mockMcpClient = makeMockMcpClient({ tools: [] });
+      mockInitializeConnections.mockResolvedValue({});
+      mockGetClient.mockResolvedValue(mockMcpClient);
+
+      await discoverMcpServer(
+        {
+          mcpServerId: "mcp-env",
+          executionContextId: "ctx-abc",
+          executionContextToken: "scoped-ec-token",
+        },
+        { stigmerClient: mockClient as any, transportPosture: "stdio-allowed" },
+      );
+
+      expect(mockClient.getExecutionContextByExecutionId).toHaveBeenCalledWith(
+        "ctx-abc",
+        "scoped-ec-token",
+      );
     });
 
     it("discovers a caller-identity-templating server via the anonymous sentinel", async () => {
@@ -600,6 +646,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 +782,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
   // ─────────────────────────────────────────────────────────────────────────

package/src/activities/__tests__/error-classifier.test.ts

@@ -7,7 +7,13 @@
  */
 
 import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
-import { synthesizeError, formatClassifiedError, shouldRetryWithFreshAgent } from "../execute-cursor/error-classifier.js";
+import {
+  synthesizeError,
+  formatClassifiedError,
+  shouldRetryWithFreshAgent,
+  DETAIL_FREE_FALLBACK_USER_PREFIX,
+  TRANSPORT_TIMEOUT_USER_PREFIX,
+} from "../execute-cursor/error-classifier.js";
 
 describe("synthesizeError", () => {
   let consoleLogSpy: ReturnType<typeof vi.spyOn>;
@@ -213,7 +219,7 @@ describe("synthesizeError", () => {
 
     expect(result.category).toBe("unknown");
     expect(result.source).toBe("fallback");
-    expect(result.message).toContain("no detail from SDK");
+    expect(result.message).toContain(DETAIL_FREE_FALLBACK_USER_PREFIX);
     expect(result.message).toContain("claude-sonnet-4");
   });
 
@@ -261,6 +267,92 @@ describe("synthesizeError", () => {
     expect(result.message).toContain("agentId=agent-123");
   });
 
+  // The exact prod shape from oss#492: the Composer 2.5 capacity incident
+  // rejected every run with a bare { status: "error" } — all five detail
+  // channels empty, fresh agent (the poisoned-handle retry produces this
+  // same shape with isResumedHandle: false). End users read this message
+  // verbatim in embedded surfaces, so it must lead with actionable copy,
+  // keep the diagnostic parenthetical for operators, and be retryable
+  // (provider capacity is transient).
+  it("detail-free failure on a fresh agent leads with user-facing copy and is retryable (oss#492)", () => {
+    const result = synthesizeError({
+      sdkError: undefined,
+      sdkResultFields: undefined,
+      streamErrorMessage: undefined,
+      capturedRejection: undefined,
+      conversationErrorText: undefined,
+      isResumedHandle: false,
+      fallbackContext: { model: "composer-2.5", mode: "local", agentId: "agent-abc" },
+    });
+
+    expect(result.category).toBe("unknown");
+    expect(result.source).toBe("fallback");
+    expect(result.retryable).toBe(true);
+    expect(result.message.startsWith(DETAIL_FREE_FALLBACK_USER_PREFIX)).toBe(true);
+    // Diagnostic context survives for operators (and the env integration
+    // test's Model= matcher).
+    expect(result.message).toContain("Model=composer-2.5");
+    expect(result.message).toContain("mode=local");
+    expect(result.message).toContain("agentId=agent-abc");
+  });
+
+  // sdk-react's isInterruptedError reframes any error containing the phrase
+  // "retry or resume" as a neutral resumable notice instead of a failure
+  // alert. A capacity failure must render as a failure — guard the copy
+  // (formatted end-to-end, tail included) against ever matching that regex.
+  it("user-facing fallback copy never trips the sdk-react interrupted-error reframe", () => {
+    const interruptedReframe = /\[StallTimeoutError\]|execution interrupted|retry or resume/i;
+    for (const prefix of [DETAIL_FREE_FALLBACK_USER_PREFIX, TRANSPORT_TIMEOUT_USER_PREFIX]) {
+      expect(prefix).not.toMatch(interruptedReframe);
+    }
+    const formatted = formatClassifiedError(synthesizeError({
+      sdkResultFields: undefined,
+      streamErrorMessage: undefined,
+      capturedRejection: undefined,
+      isResumedHandle: false,
+      fallbackContext,
+    }));
+    expect(formatted).not.toMatch(interruptedReframe);
+  });
+
+  // ---------------------------------------------------------------------------
+  // Transport-timeout heuristic (0 messages, ~default SDK timeout)
+  // ---------------------------------------------------------------------------
+
+  it("classifies a 0-message ~30s failure as retryable network with user-facing copy", () => {
+    const result = synthesizeError({
+      sdkResultFields: undefined,
+      streamErrorMessage: undefined,
+      capturedRejection: undefined,
+      isResumedHandle: false,
+      fallbackContext,
+      durationMs: 30012,
+      messageCount: 0,
+    });
+
+    expect(result.category).toBe("network");
+    expect(result.source).toBe("fallback");
+    expect(result.retryable).toBe(true);
+    expect(result.message.startsWith(TRANSPORT_TIMEOUT_USER_PREFIX)).toBe(true);
+    expect(result.message).toContain("30012ms");
+    expect(result.message).toContain("Model=claude-sonnet-4");
+  });
+
+  it("does not apply the transport heuristic outside the default-timeout window", () => {
+    const result = synthesizeError({
+      sdkResultFields: undefined,
+      streamErrorMessage: undefined,
+      capturedRejection: undefined,
+      isResumedHandle: false,
+      fallbackContext,
+      durationMs: 120000,
+      messageCount: 0,
+    });
+
+    expect(result.category).toBe("unknown");
+    expect(result.message.startsWith(DETAIL_FREE_FALLBACK_USER_PREFIX)).toBe(true);
+  });
+
   // ---------------------------------------------------------------------------
   // Source priority
   // ---------------------------------------------------------------------------

package/src/activities/__tests__/run-command.test.ts

@@ -0,0 +1,221 @@
+/**
+ * Env contract tests for the workflow `run` task (oss#384).
+ *
+ * These spawn REAL subprocesses through the RunShell / RunScript
+ * activities and inspect the environment the child actually received —
+ * the leak-reproduction style established by the #256 fix (PR #383).
+ * Subprocess output is env variable NAMES only, never values.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { createRunCommandActivities } from "../run-command.js";
+import { buildRunEnv, RUN_ENV_BASE_KEYS } from "../run-env.js";
+import { RuntimePlaceholderResolutionError } from "../../workflow-engine/resolve.js";
+
+/**
+ * Credentials planted into the runner process env before each test.
+ * Includes a name outside every known denylist to prove the contract
+ * is declare-to-receive, not deny-known-names.
+ */
+const PLANTED_SENTINELS: Record<string, string> = {
+  STIGMER_RUNNER_HITL_SECRET: "sentinel-hitl",
+  STIGMER_TOKEN: "sentinel-token",
+  CURSOR_API_KEY: "sentinel-cursor",
+  ANTHROPIC_API_KEY: "sentinel-anthropic",
+  OPERATOR_PRIVATE_CREDENTIAL: "sentinel-arbitrary",
+};
+
+const PRINT_ENV_KEYS_SHELL = `node -p 'JSON.stringify(Object.keys(process.env))'`;
+const PRINT_ENV_KEYS_SCRIPT = `console.log(JSON.stringify(Object.keys(process.env)))`;
+
+const activities = createRunCommandActivities();
+
+async function childEnvKeysViaShell(
+  environment?: Record<string, string>,
+  runtimeEnv: Record<string, unknown> = {},
+): Promise<string[]> {
+  const stdout = await activities.RunShell({
+    mode: "shell",
+    command: PRINT_ENV_KEYS_SHELL,
+    environment,
+    runtimeEnv,
+  });
+  return JSON.parse(String(stdout)) as string[];
+}
+
+async function childEnvKeysViaScript(
+  environment?: Record<string, string>,
+  runtimeEnv: Record<string, unknown> = {},
+): Promise<string[]> {
+  const stdout = await activities.RunScript({
+    mode: "script",
+    language: "js",
+    code: PRINT_ENV_KEYS_SCRIPT,
+    environment,
+    runtimeEnv,
+  });
+  return JSON.parse(String(stdout)) as string[];
+}
+
+describe("run task env contract (oss#384)", () => {
+  const saved: Record<string, string | undefined> = {};
+
+  beforeEach(() => {
+    for (const [key, value] of Object.entries(PLANTED_SENTINELS)) {
+      saved[key] = process.env[key];
+      process.env[key] = value;
+    }
+  });
+
+  afterEach(() => {
+    for (const key of Object.keys(PLANTED_SENTINELS)) {
+      if (saved[key] === undefined) {
+        delete process.env[key];
+      } else {
+        process.env[key] = saved[key];
+      }
+    }
+  });
+
+  describe("RunShell", () => {
+    it("does not leak runner process credentials to the child", async () => {
+      const keys = await childEnvKeysViaShell();
+
+      for (const sentinel of Object.keys(PLANTED_SENTINELS)) {
+        expect(keys, `runner credential "${sentinel}" leaked to shell child`)
+          .not.toContain(sentinel);
+      }
+    });
+
+    it("provides the minimal base env and the declared overlay", async () => {
+      const keys = await childEnvKeysViaShell({ DECLARED_VAR: "value" });
+
+      for (const base of RUN_ENV_BASE_KEYS) {
+        if (process.env[base] !== undefined) {
+          expect(keys, `base key "${base}" missing from shell child`).toContain(base);
+        }
+      }
+      expect(keys).toContain("DECLARED_VAR");
+    });
+
+    it("resolves ${.secrets.KEY} placeholders in declared values just-in-time", async () => {
+      const stdout = await activities.RunShell({
+        mode: "shell",
+        command: `node -p 'process.env.API_KEY'`,
+        environment: { API_KEY: "${.secrets.TEST_API_KEY}" },
+        runtimeEnv: { TEST_API_KEY: "resolved-secret-value" },
+      });
+
+      expect(stdout).toBe("resolved-secret-value");
+    });
+
+    it("fails non-retryably, naming the variable, when a placeholder key is missing", async () => {
+      await expect(
+        activities.RunShell({
+          mode: "shell",
+          command: "true",
+          environment: { API_KEY: "${.secrets.NOT_PROVIDED}" },
+          runtimeEnv: {},
+        }),
+      ).rejects.toMatchObject({
+        nonRetryable: true,
+        type: "RUN_ENV_UNRESOLVED_PLACEHOLDER",
+        message: expect.stringContaining("NOT_PROVIDED"),
+      });
+    });
+  });
+
+  describe("RunScript", () => {
+    it("does not leak runner process credentials to the child", async () => {
+      const keys = await childEnvKeysViaScript();
+
+      for (const sentinel of Object.keys(PLANTED_SENTINELS)) {
+        expect(keys, `runner credential "${sentinel}" leaked to script child`)
+          .not.toContain(sentinel);
+      }
+    });
+
+    it("provides the minimal base env and the declared overlay", async () => {
+      const keys = await childEnvKeysViaScript({ DECLARED_VAR: "value" });
+
+      for (const base of RUN_ENV_BASE_KEYS) {
+        if (process.env[base] !== undefined) {
+          expect(keys, `base key "${base}" missing from script child`).toContain(base);
+        }
+      }
+      expect(keys).toContain("DECLARED_VAR");
+    });
+
+    it("resolves ${.env_vars.KEY} placeholders in declared values just-in-time", async () => {
+      const stdout = await activities.RunScript({
+        mode: "script",
+        language: "js",
+        code: "console.log(process.env.REGION)",
+        environment: { REGION: "${.env_vars.DEPLOY_REGION}" },
+        runtimeEnv: { DEPLOY_REGION: "us-east-1" },
+      });
+
+      expect(stdout).toBe("us-east-1");
+    });
+  });
+});
+
+describe("buildRunEnv", () => {
+  it("copies only the base keys present in the runner env", () => {
+    const base = {
+      PATH: "/usr/bin",
+      HOME: "/home/runner",
+      TERM: "xterm",
+    };
+
+    const env = buildRunEnv(undefined, {}, base);
+
+    expect(env).toEqual({ PATH: "/usr/bin", HOME: "/home/runner", TERM: "xterm" });
+  });
+
+  it("never copies undeclared runner variables — the oss#384 tripwire", () => {
+    // Guards against a future reintroduction of `{ ...process.env }`:
+    // credentials must be structurally absent, whatever their names.
+    const base = {
+      PATH: "/usr/bin",
+      STIGMER_RUNNER_HITL_SECRET: "secret",
+      ANY_FUTURE_CREDENTIAL: "secret",
+    };
+
+    const env = buildRunEnv({ DECLARED: "yes" }, {}, base);
+
+    expect(Object.keys(env).sort()).toEqual(["DECLARED", "PATH"]);
+  });
+
+  it("lets a declared variable override a base variable", () => {
+    const base = { PATH: "/usr/bin" };
+
+    const env = buildRunEnv({ PATH: "/custom/bin" }, {}, base);
+
+    expect(env.PATH).toBe("/custom/bin");
+  });
+
+  it("passes non-placeholder declared values through untouched", () => {
+    const env = buildRunEnv(
+      { LITERAL: "plain-value", TEMPLATED: "prefix-${.secrets.KEY}-suffix" },
+      { KEY: "mid" },
+      {},
+    );
+
+    expect(env.LITERAL).toBe("plain-value");
+    expect(env.TEMPLATED).toBe("prefix-mid-suffix");
+  });
+
+  it("throws a named error for a missing placeholder key", () => {
+    expect(() =>
+      buildRunEnv({ API_KEY: "${.secrets.MISSING}" }, {}, {}),
+    ).toThrowError(RuntimePlaceholderResolutionError);
+
+    try {
+      buildRunEnv({ API_KEY: "${.secrets.MISSING}" }, {}, {});
+    } catch (err) {
+      expect((err as RuntimePlaceholderResolutionError).variableName).toBe("MISSING");
+      expect((err as Error).message).toContain('environment "API_KEY"');
+    }
+  });
+});