@stigmer/runner 3.11.0 → 3.12.0

package/src/activities/run-command.ts

@@ -5,8 +5,11 @@
  * - RunScript: writes inline code to a temp file, executes via node/python
  * - RunShell: executes a shell command directly
  *
- * Both resolve runtime placeholders (JIT secrets) before execution
- * and capture stdout as the activity result.
+ * The child environment follows the declare-to-receive contract in
+ * run-env.ts: a minimal base plus the task's declared `environment`,
+ * with runtime placeholders (JIT secrets) resolved here in the activity
+ * so secret values never enter Temporal history. Both activities capture
+ * stdout as the activity result.
  */
 
 import { execFile, exec } from "node:child_process";
@@ -16,7 +19,9 @@ import { join } from "node:path";
 import { promisify } from "node:util";
 import { ApplicationFailure } from "@temporalio/activity";
 import type { RunCommandConfig } from "../workflow-engine/types.js";
+import { RuntimePlaceholderResolutionError } from "../workflow-engine/resolve.js";
 import { startHeartbeat } from "../shared/heartbeat.js";
+import { buildRunEnv } from "./run-env.js";
 
 const execFileAsync = promisify(execFile);
 const execAsync = promisify(exec);
@@ -49,7 +54,7 @@ async function runScriptImpl(config: RunCommandConfig): Promise<unknown> {
 
   const language = config.language!;
   const code = config.code!;
-  const env = buildEnv(config.environment);
+  const env = buildTaskEnv(config);
 
   const ext = language === "js" ? ".js" : ".py";
   const interpreter = language === "js" ? "node" : "python3";
@@ -94,7 +99,7 @@ async function runShellImpl(config: RunCommandConfig): Promise<unknown> {
   const fullCommand = args.length > 0
     ? `${command} ${args.join(" ")}`
     : command;
-  const env = buildEnv(config.environment);
+  const env = buildTaskEnv(config);
 
   try {
     const { stdout } = await execAsync(fullCommand, {
@@ -116,16 +121,24 @@ async function runShellImpl(config: RunCommandConfig): Promise<unknown> {
   }
 }
 
-function buildEnv(
-  taskEnv?: Record<string, string>,
-): Record<string, string | undefined> {
-  const base = { ...process.env };
-  if (taskEnv) {
-    for (const [k, v] of Object.entries(taskEnv)) {
-      base[k] = v;
+/**
+ * Build the child env per the run-env.ts contract, translating a missing
+ * placeholder key into a non-retryable failure — retrying cannot conjure
+ * a variable the workflow's runtime env does not have.
+ */
+function buildTaskEnv(config: RunCommandConfig): Record<string, string> {
+  try {
+    return buildRunEnv(config.environment, config.runtimeEnv);
+  } catch (err: unknown) {
+    if (err instanceof RuntimePlaceholderResolutionError) {
+      throw ApplicationFailure.nonRetryable(
+        err.message,
+        "RUN_ENV_UNRESOLVED_PLACEHOLDER",
+        { variable: err.variableName },
+      );
     }
+    throw err;
   }
-  return base;
 }
 
 function buildArgsList(args: unknown): string[] {

package/src/activities/run-env.ts

@@ -0,0 +1,79 @@
+/**
+ * Environment contract for the workflow `run` task (shell and script modes).
+ *
+ * Declare-to-receive, the same rule the stdio MCP contract adopted after
+ * #256 (PR #383): the child process sees ONLY
+ *
+ *   1. a minimal base copied from the runner process
+ *      ({@link RUN_ENV_BASE_KEYS} — the six variables the MCP SDK pins),
+ *   2. the task's declared `environment` map, with `${.secrets.KEY}` /
+ *      `${.env_vars.KEY}` placeholders resolved just-in-time from the
+ *      workflow's runtime env. Resolution happens here in the activity,
+ *      never in the deterministic workflow phase, so secret values stay
+ *      out of Temporal history.
+ *
+ * Runner credentials (STIGMER_TOKEN, the HITL secret, provider keys) are
+ * structurally absent rather than denylisted — a workflow-authored
+ * `printenv` cannot read what was never passed (oss#384). A missing
+ * placeholder key fails loudly: running a command with a silently-empty
+ * credential produces cryptic downstream failures.
+ *
+ * Placeholders resolve only in declared environment VALUES, never in
+ * `command` / `code` strings — argv is visible to `ps` on the host, so
+ * the environment is the sanctioned channel for secrets.
+ */
+
+import { resolveRuntimePlaceholdersStrict } from "../workflow-engine/resolve.js";
+
+/**
+ * Base variables copied from the runner process when present — the same
+ * six the MCP SDK provides to stdio servers, so "undeclared subprocess
+ * environment" has one platform-wide answer. `PATH` keeps interpreters
+ * and tools findable; the rest keep shells and language runtimes sane.
+ */
+export const RUN_ENV_BASE_KEYS: readonly string[] = [
+  "HOME",
+  "LOGNAME",
+  "PATH",
+  "SHELL",
+  "TERM",
+  "USER",
+];
+
+/**
+ * Build the environment for a run task's child process: minimal base +
+ * declared overlay with strict placeholder resolution (declared wins on
+ * conflict with the base).
+ *
+ * @throws RuntimePlaceholderResolutionError when a declared value
+ *   references a runtime key that does not exist.
+ */
+export function buildRunEnv(
+  declaredEnv: Readonly<Record<string, string>> | undefined,
+  runtimeEnv: Readonly<Record<string, unknown>>,
+  baseEnv: NodeJS.ProcessEnv = process.env,
+): Record<string, string> {
+  const env: Record<string, string> = {};
+
+  for (const key of RUN_ENV_BASE_KEYS) {
+    const value = baseEnv[key];
+    if (value !== undefined) env[key] = value;
+  }
+
+  if (!declaredEnv || Object.keys(declaredEnv).length === 0) {
+    // The only case whose behavior changed in oss#384 (previously the
+    // child inherited the full runner env) — leave a trace for operators.
+    console.log("run task declares no environment — child receives the minimal base env only");
+    return env;
+  }
+
+  for (const [key, value] of Object.entries(declaredEnv)) {
+    env[key] = resolveRuntimePlaceholdersStrict(
+      value,
+      runtimeEnv,
+      `environment "${key}"`,
+    );
+  }
+
+  return env;
+}

package/src/bootstrap.ts

@@ -120,6 +120,11 @@ export async function resolveRunnerBootstrap(
     // (OSS / no signing key) and is handled by the runner, not treated as fatal.
     runnerAccessToken: discovered.runnerAccessToken,
     runnerAccessTokenExpiresInSeconds: discovered.runnerAccessTokenExpiresInSeconds,
+    // Server-managed payload-encryption keys ride the same best-effort lane:
+    // absent on OSS (env-configured keys) and on cloud servers predating key
+    // management. Note the explicit-address and localhost branches above return
+    // none by construction — key management only exists where discovery does.
+    payloadEncryption: discovered.payloadEncryption,
   };
 }
 

package/src/client/__tests__/stigmer-client.test.ts

@@ -45,10 +45,11 @@ function makeScopedTokenExchangeRequest() {
 }
 
 /** An unsigned JWT-shaped token carrying the given token_type claim. */
-function fakeTokenOfType(tokenType: string): string {
+function fakeTokenOfType(tokenType?: string): string {
   const b64 = (obj: Record<string, unknown>) =>
     Buffer.from(JSON.stringify(obj)).toString("base64url");
-  return `${b64({ alg: "RS256" })}.${b64({ token_type: tokenType })}.sig`;
+  const claims = tokenType === undefined ? {} : { token_type: tokenType };
+  return `${b64({ alg: "RS256" })}.${b64(claims)}.sig`;
 }
 
 /**
@@ -310,14 +311,64 @@ describe("StigmerClient", () => {
       expect(spy).not.toHaveBeenCalled();
     });
 
-    it("skips the exchange when no runner credential exists (OSS/local)", async () => {
+    // NOTE (oss#535): the no-credential arm previously pinned "skip the
+    // exchange" — correct while OSS neither minted nor redacted. Since
+    // oss#535 the OSS server redacts EC reads by default and mints
+    // execution-scoped tokens on this exchange, so a credential-less runner
+    // must now ASK, and fall back to the tokenless read only when the server
+    // answers not-minted (pre-oss#535 OSS) or refuses (cloud refusing a
+    // non-runner credential — the legacy desktop degrade).
+    it("exchanges best-effort when no runner credential exists and uses a minted token (oss#535)", async () => {
       const client = clientWithRunnerCredential(null);
-      const spy = vi.spyOn(client, "getRunnerScopedToken");
+      vi.spyOn(client, "getRunnerScopedToken").mockResolvedValue({
+        token: "oss-scoped-tok",
+        expiresInSeconds: 3600,
+      });
+
+      const token = await client.acquireScopedRunnerToken({ workflowExecutionId: "wfx_1" });
+
+      expect(token).toBe("oss-scoped-tok");
+      expect(client.getRunnerScopedToken).toHaveBeenCalledWith({ workflowExecutionId: "wfx_1" });
+    });
+
+    it("proceeds tokenless when a credential-less exchange is answered not-minted (pre-oss#535 server)", async () => {
+      const client = clientWithRunnerCredential(null);
+      vi.spyOn(client, "getRunnerScopedToken").mockResolvedValue(undefined);
 
       const token = await client.acquireScopedRunnerToken({ workflowExecutionId: "wfx_1" });
 
       expect(token).toBeUndefined();
-      expect(spy).not.toHaveBeenCalled();
+    });
+
+    it("proceeds tokenless when a credential-less exchange is refused (cloud refusing a non-runner credential)", async () => {
+      const client = clientWithRunnerCredential(null);
+      vi.spyOn(client, "getRunnerScopedToken").mockRejectedValue(new Error("permission denied"));
+
+      const token = await client.acquireScopedRunnerToken({ agentExecutionId: "aex_1" });
+
+      expect(token).toBeUndefined();
+    });
+
+    it("treats a non-JWT process token as no runner credential (the harness/proxy token shape)", async () => {
+      // e.g. the conformance harness boots the runner with a mock proxy
+      // token that is not a Stigmer-minted JWT; the best-effort arm must
+      // still ask the server for a scoped token.
+      const client = clientWithRunnerCredential("not-a-jwt-proxy-token");
+      vi.spyOn(client, "getRunnerScopedToken").mockResolvedValue({ token: "scoped-tok" });
+
+      const token = await client.acquireScopedRunnerToken({ agentExecutionId: "aex_1" });
+
+      expect(token).toBe("scoped-tok");
+    });
+
+    it("treats a claim-less user JWT as no runner credential (legacy desktop shape)", async () => {
+      const client = clientWithRunnerCredential(fakeTokenOfType(undefined));
+      vi.spyOn(client, "getRunnerScopedToken").mockResolvedValue(undefined);
+
+      const token = await client.acquireScopedRunnerToken({ agentExecutionId: "aex_1" });
+
+      expect(token).toBeUndefined();
+      expect(client.getRunnerScopedToken).toHaveBeenCalled();
     });
 
     it("throws when the server mints no token — the bootstrap credential no longer decrypts (stigmer-cloud#218)", async () => {
@@ -432,6 +483,54 @@ describe("StigmerClient", () => {
     });
   });
 
+  describe("sendWorkflowSignal", () => {
+    function clientWithWorkflowCommand() {
+      const client = new StigmerClient({ endpoint: "http://localhost", token: null });
+      const sendSignal = vi.fn().mockResolvedValue({});
+      // Reach into the private generated client: the mocked createClient()
+      // returned {}, so install the method it would have provided.
+      (client as any).workflowExecutionCommand = { sendSignal };
+      return { client, rpc: sendSignal };
+    }
+
+    it("builds SendSignalInput with execution addressing and the payload verbatim", async () => {
+      const { client, rpc } = clientWithWorkflowCommand();
+      const payload = { type: "approval.granted", data: { ok: true } };
+
+      await client.sendWorkflowSignal("wfx_1", "approval_resolved", payload);
+
+      const input = rpc.mock.calls[0]![0];
+      expect(input.executionId).toBe("wfx_1");
+      expect(input.signalName).toBe("approval_resolved");
+      expect(input.payload).toEqual(payload);
+    });
+
+    it("sends no idempotency key (oss#442: failed-delivery claims are never released)", async () => {
+      const { client, rpc } = clientWithWorkflowCommand();
+
+      await client.sendWorkflowSignal("wfx_1", "ping", undefined);
+
+      const input = rpc.mock.calls[0]![0];
+      expect(input.idempotencyKey).toBe("");
+    });
+
+    it("passes the per-call timeout through to the RPC", async () => {
+      const { client, rpc } = clientWithWorkflowCommand();
+
+      await client.sendWorkflowSignal("wfx_1", "ping", undefined, { timeoutMs: 30_000 });
+
+      expect(rpc).toHaveBeenCalledWith(expect.anything(), { timeoutMs: 30_000 });
+    });
+
+    it("passes an undefined timeout when no options are supplied", async () => {
+      const { client, rpc } = clientWithWorkflowCommand();
+
+      await client.sendWorkflowSignal("wfx_1", "ping", undefined);
+
+      expect(rpc).toHaveBeenCalledWith(expect.anything(), { timeoutMs: undefined });
+    });
+  });
+
   describe("updateToken", () => {
     it("does not affect tokenRef-based resolution", async () => {
       const ref: TokenRef = { current: "from-ref" };

package/src/client/stigmer-client.ts

@@ -44,7 +44,8 @@ import type { UpdateStatusResponse } from "@stigmer/protos/ai/stigmer/agentic/ag
 import { WorkflowExecutionCommandController } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/command_pb";
 import { WorkflowExecutionQueryController } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/query_pb";
 import type { WorkflowExecution, WorkflowExecutionStatus } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
-import { WorkflowExecutionUpdateStatusInputSchema, GetEventLogRequestSchema } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/io_pb";
+import { WorkflowExecutionUpdateStatusInputSchema, GetEventLogRequestSchema, SendSignalInputSchema } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/io_pb";
+import type { JsonObject } from "@bufbuild/protobuf";
 import { WorkflowQueryController } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/query_pb";
 import type { Workflow } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/api_pb";
 import { WorkflowInstanceQueryController } from "@stigmer/protos/ai/stigmer/agentic/workflowinstance/v1/query_pb";
@@ -52,9 +53,29 @@ import type { WorkflowInstance } from "@stigmer/protos/ai/stigmer/agentic/workfl
 import { PlatformQueryController, GetRunnerScopedTokenInputSchema, TokenRenewalSchema } from "@stigmer/protos/ai/stigmer/platform/v1/server_info_pb";
 import { ChannelMessageQueryController } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/message_query_pb";
 import type { ChannelTemplate, MessagingChannel } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/message_io_pb";
-import { isEmbeddedRunnerToken } from "./token-claims.js";
+import { TOKEN_TYPE_EMBEDDED_RUNNER, tokenTypeOf } from "./token-claims.js";
 import { assertCreateRequirements, assertReferenceRequirements } from "./server-contracts.js";
 
+/**
+ * Server-managed Temporal payload-encryption keys for this runner.
+ *
+ * Minted once per caller identity and persisted by the control plane, so
+ * every boot of the same identity's runners receives the SAME key — the
+ * persistence Temporal replay requires across runner restarts. The secondary
+ * pair is present only during a rotation window (decrypt-only; new payloads
+ * are written under the primary).
+ */
+export interface BootstrapPayloadEncryptionKeys {
+  /** Base64-encoded 32-byte AES-256 key. */
+  key: string;
+  /** Key id stamped on payloads encrypted under {@link key}. */
+  keyId: string;
+  /** Previous key of this identity, present during rotation windows. */
+  secondaryKey?: string;
+  /** Key id of {@link secondaryKey}; present exactly when it is. */
+  secondaryKeyId?: string;
+}
+
 /**
  * Everything an embedded runner needs to bootstrap: Temporal coordinates plus
  * its own minted access token.
@@ -62,7 +83,10 @@ import { assertCreateRequirements, assertReferenceRequirements } from "./server-
  * The Temporal coordinates are always present. The access token is optional: the
  * server only mints one when it has a Cursor proxy to authenticate against
  * (cloud) and a signing key configured — OSS and misconfigured servers omit it,
- * and the runner keeps using its existing token in that case.
+ * and the runner keeps using its existing token in that case. Payload-encryption
+ * keys follow the same presence contract: absent when the server does not manage
+ * runner keys (OSS uses env-configured keys; older cloud servers predate key
+ * management).
  */
 export interface RunnerBootstrapConfig {
   temporalAddress: string;
@@ -71,15 +95,18 @@ export interface RunnerBootstrapConfig {
   runnerAccessToken?: string;
   /** Lifetime of {@link runnerAccessToken} in seconds; absent/0 when no token. */
   runnerAccessTokenExpiresInSeconds?: number;
+  /** Server-managed payload-encryption keys; absent when not managed by the server. */
+  payloadEncryption?: BootstrapPayloadEncryptionKeys;
 }
 
 /**
  * A runner token scoped to one unit of dispatched work (issue #156).
  *
- * Minted on demand by the control plane when the runner exchanges its
- * bootstrap credential at task start; presented for the ExecutionContext
- * fetch of exactly that execution. Absent when the server does not mint
- * (OSS, or no signing key) — the runner keeps its existing credential.
+ * Minted on demand by the control plane at task start — a desktop runner
+ * exchanges its bootstrap credential, an OSS runner asks with no credential
+ * at all (oss#535) — and presented for the ExecutionContext fetch of exactly
+ * that execution. Absent when the server does not mint (pre-oss#535 OSS, or
+ * a refused credential class) — the runner keeps its existing credential.
  */
 export interface RunnerScopedToken {
   token: string;
@@ -272,6 +299,18 @@ export class StigmerClient {
       runnerAccessToken: res.runnerAccessToken || undefined,
       runnerAccessTokenExpiresInSeconds:
         res.runnerAccessTokenExpiresInSeconds || undefined,
+      // Same presence contract, grouped so callers make ONE presence check.
+      // Key without id (or vice versa) is a server contract violation the
+      // encryption config loader rejects — not silently dropped here, so the
+      // breakage is diagnosable at the fail-closed boundary.
+      payloadEncryption: res.payloadEncryptionKey
+        ? {
+            key: res.payloadEncryptionKey,
+            keyId: res.payloadEncryptionKeyId,
+            secondaryKey: res.payloadEncryptionSecondaryKey || undefined,
+            secondaryKeyId: res.payloadEncryptionSecondaryKeyId || undefined,
+          }
+        : undefined,
     };
   }
 
@@ -313,14 +352,16 @@ export class StigmerClient {
   }
 
   /**
-   * Exchange this runner's bootstrap credential for a token scoped to one
-   * unit of dispatched work (issue #156).
+   * Exchange this runner's credential for a token scoped to one unit of
+   * dispatched work (issue #156).
    *
-   * The call authenticates with the runner credential (see the interceptor);
-   * the server verifies it is an embedded_runner token and that its identity
-   * can view the named execution, then mints the same session/execution-scoped
-   * sandbox token a cloud sandbox runner receives at provisioning. Returns
-   * undefined when the server does not mint (OSS, or no signing key) —
+   * The call authenticates with the runner credential (see the interceptor).
+   * Cloud verifies it is an embedded_runner token and that its identity can
+   * view the named execution, then mints the same session/execution-scoped
+   * sandbox token a cloud sandbox runner receives at provisioning. OSS mints
+   * an execution-scoped token for any caller (oss#535 — a lane discriminator
+   * on a single-user server, not a trust boundary). Returns undefined when
+   * the server does not mint (pre-oss#535 OSS, or an unserved scope arm) —
    * presence-based, like the bootstrap token fields.
    *
    * `callerToken` authenticates the exchange per-call instead of the
@@ -354,26 +395,44 @@ export class StigmerClient {
    * Acquire a scoped runner token for an ExecutionContext read, if this
    * runner's credential situation calls for one.
    *
-   * The gate is the credential itself: only an unscoped embedded_runner
-   * bootstrap token needs exchanging. A cloud sandbox runner's credential is
-   * already scoped (skip — the exchange would rightly refuse it), and an
-   * OSS/local runner holds no runner-class credential at all (skip — the
-   * server neither mints nor redacts).
+   * The gate is the credential itself, three ways:
+   *
+   * 1. An unscoped embedded_runner bootstrap token MUST be exchanged, and a
+   *    failed exchange is a hard error, not a fallback: since the #156
+   *    item-3 flip (stigmer-cloud#218) the bootstrap credential no longer
+   *    decrypts, so a read that "fell back" would silently receive redacted
+   *    placeholders and the execution would run against junk secret values —
+   *    strictly worse than failing here with the real reason. The
+   *    secret-delivery call sites let this error fail the activity;
+   *    opportunistic consumers that can genuinely proceed without a scoped
+   *    token (attachment credential, channel discovery) catch it at the
+   *    call site, where their degrade-to-empty contract lives.
+   *
+   * 2. Any other runner-class credential is already scoped (a cloud
+   *    sandbox/pool/connect token) — skip; the exchange would rightly
+   *    refuse it and the ambient credential decrypts on its own.
    *
-   * A failed exchange is a hard error, not a fallback: since the #156 item-3
-   * flip (stigmer-cloud#218) the bootstrap credential no longer decrypts, so
-   * a read that "fell back" would silently receive redacted placeholders and
-   * the execution would run against junk secret values — strictly worse than
-   * failing here with the real reason. The secret-delivery call sites let
-   * this error fail the activity; opportunistic consumers that can genuinely
-   * proceed without a scoped token (attachment credential, channel
-   * discovery) catch it at the call site, where their degrade-to-empty
-   * contract lives.
+   * 3. No runner-class credential at all (OSS/local, where the process
+   *    token is absent or carries no token_type claim) — attempt the
+   *    exchange best-effort (oss#535): a current OSS server mints an
+   *    execution-scoped token here, which is the ONLY way this runner can
+   *    read decrypted secrets from its redact-by-default EC RPCs. A server
+   *    that answers "not minted" (pre-oss#535 OSS, which also does not
+   *    redact) or refuses the exchange (cloud refusing a non-runner
+   *    credential — the legacy desktop degrade, which reads redacted today
+   *    regardless) falls through to the tokenless read, preserving each
+   *    old pairing's exact behavior.
    */
   async acquireScopedRunnerToken(
     scope: RunnerScopedTokenScope,
   ): Promise<string | undefined> {
-    if (!isEmbeddedRunnerToken(this.runnerTokenRef?.current)) {
+    // Inspect the same credential chain the EC read's interceptor would use.
+    const ambientTokenType = tokenTypeOf(
+      this.runnerTokenRef?.current ?? this.tokenRef?.current ?? this.currentToken,
+    );
+    const isEmbeddedRunner = ambientTokenType === TOKEN_TYPE_EMBEDDED_RUNNER;
+    if (ambientTokenType !== undefined && !isEmbeddedRunner) {
+      // Case 2: an already-scoped runner-class credential.
       return undefined;
     }
     const scopeDescription =
@@ -386,6 +445,11 @@ export class StigmerClient {
     try {
       scoped = await this.getRunnerScopedToken(scope);
     } catch (err) {
+      if (!isEmbeddedRunner) {
+        // Case 3: best-effort — a refusal means the server does not serve
+        // this credential class; the tokenless read is today's behavior.
+        return undefined;
+      }
       throw new Error(
         `Scoped runner token exchange failed for ${scopeDescription}: ` +
         `${err instanceof Error ? err.message : String(err)}. ` +
@@ -395,6 +459,11 @@ export class StigmerClient {
       );
     }
     if (!scoped) {
+      if (!isEmbeddedRunner) {
+        // Case 3: a server that mints nothing for this scope also does not
+        // redact for this runner (pre-oss#535 OSS) — proceed tokenless.
+        return undefined;
+      }
       throw new Error(
         `Server minted no scoped runner token for ${scopeDescription}. ` +
         "The bootstrap credential cannot read ExecutionContext secrets " +
@@ -552,6 +621,36 @@ export class StigmerClient {
     return this.workflowExecutionCommand.updateStatus(input);
   }
 
+  /**
+   * Deliver a named signal to another workflow execution through the
+   * server's SendSignal lane (validate → phase gate → relay via the
+   * outer orchestrator). This is the ONLY sanctioned path for
+   * runner-originated signals: a direct Temporal client would bypass
+   * both the authorization boundary and the payload-encryption design
+   * (per-identity runner keys make sender-side encryption fail closed
+   * at receivers holding a different key — see oss#517).
+   *
+   * Deliberately sends no idempotency_key: the server's dedupe claim is
+   * not released when delivery fails (oss#442), so a key here would
+   * poison the exact retry it exists to protect — and emit envelope ids
+   * regenerate per activity attempt anyway. Revisit once oss#442 lands.
+   */
+  async sendWorkflowSignal(
+    executionId: string,
+    signalName: string,
+    payload: JsonObject | undefined,
+    options?: { timeoutMs?: number },
+  ): Promise<WorkflowExecution> {
+    const input = create(SendSignalInputSchema, {
+      executionId,
+      signalName,
+      payload,
+    });
+    return this.workflowExecutionCommand.sendSignal(input, {
+      timeoutMs: options?.timeoutMs,
+    });
+  }
+
   async getWorkflowExecution(executionId: string): Promise<WorkflowExecution> {
     return this.workflowExecutionQuery.get({ value: executionId });
   }

package/src/config.ts

@@ -61,11 +61,12 @@ export interface Config {
   readonly stigmerBackendEndpoint: string;
   readonly stigmerToken: string | null;
   /**
-   * The MCP bridge endpoint for the runner-synthesized datastore
-   * records attachment (STIGMER_MCP_BRIDGE_ENDPOINT, e.g.
-   * https://mcp.stigmer.ai). Null selects the OSS/local shape: a
-   * spawned `stigmer mcp-server` stdio child against the local backend.
-   * See shared/datastore-attachment.ts.
+   * The MCP bridge endpoint for the runner-synthesized attachments —
+   * channel messaging and conversation participation
+   * (STIGMER_MCP_BRIDGE_ENDPOINT, e.g. https://mcp.stigmer.ai). Null
+   * selects the OSS/local shape: a spawned `stigmer mcp-server` stdio
+   * child against the local backend. See shared/channel-attachment.ts
+   * and shared/conversation-attachment.ts.
    */
   readonly mcpBridgeEndpoint: string | null;
   /**