@stigmer/runner 3.15.3-dev.20260916211208 → 3.16.1-dev.20260917224426

package/src/interceptors/run-credential-activity.ts

@@ -0,0 +1,67 @@
+/**
+ * The activity boundary's ONE entry into the run-credential store.
+ *
+ * Every activity a worker runs — the server-dispatched turn activities, the
+ * server-dispatched GenerateSessionSubject, and every local or remote
+ * activity the runner's own serverless-workflow engine schedules — passes
+ * through this inbound interceptor. It reads the run credential from
+ * whichever channel the dispatch used (`shared/run-credential.ts`: the
+ * Temporal header the runner's workflow stamps, else the input object's
+ * key the server's workflow sets) and runs the activity inside
+ * `withRunCredential`, so that every control-plane request the activity
+ * makes — however deep, however detached — is made as the run's human.
+ *
+ * Header before input: a runner-dispatched activity's header is the nearer
+ * authority; in practice a dispatch carries exactly one of the two. An
+ * activity whose dispatch carried neither runs with no credential in the
+ * store, and the client falls back to the process credential exactly as it
+ * did before the store existed — an older server, and the cloud, see no
+ * change.
+ *
+ * Both worker roots (`worker.ts`, `runner-manager.ts`) register this
+ * unconditionally; it is inert without a credential. It logs nothing: a
+ * credential is never written to a log, and the arguments it inspects may
+ * carry anything.
+ */
+
+import type { ActivityInterceptorsFactory } from "@temporalio/worker";
+import { defaultPayloadConverter } from "@temporalio/common";
+
+import {
+  RUN_CREDENTIAL_HEADER,
+  readRunCredentialFromInput,
+} from "../shared/run-credential.js";
+import { withRunCredential } from "../shared/run-credential-store.js";
+
+/** The inbound interceptor factory both worker roots register. */
+export const runCredentialActivityInterceptor: ActivityInterceptorsFactory =
+  () => ({
+    inbound: {
+      async execute(input, next) {
+        const credential =
+          readRunCredentialFromHeader(input.headers[RUN_CREDENTIAL_HEADER]) ??
+          readRunCredentialFromInput(input.args[0]);
+        if (credential === undefined) {
+          return next(input);
+        }
+        return withRunCredential(credential, () => next(input));
+      },
+    },
+  });
+
+/**
+ * The credential a header payload carries, or `undefined` when there is no
+ * such header or it does not decode to a non-empty string. Decoding uses the
+ * default converter, never the worker's data converter: headers bypass the
+ * payload codecs by SDK design, and the stamping side encodes with the same
+ * default converter.
+ */
+function readRunCredentialFromHeader(payload: unknown): string | undefined {
+  if (payload === undefined) {
+    return undefined;
+  }
+  const value: unknown = defaultPayloadConverter.fromPayload(
+    payload as Parameters<typeof defaultPayloadConverter.fromPayload>[0],
+  );
+  return typeof value === "string" && value !== "" ? value : undefined;
+}

package/src/runner-manager.ts

@@ -29,7 +29,12 @@ import { DEFAULT_CURSOR_AGENT_RESOLVE_TIMEOUT_MS, DEFAULT_CURSOR_STREAM_STALL_TI
 // desktop manager never calls emitRunnerBootTiming, so marks cost nothing).
 import { markBoot } from "./shared/cold-start-timing.js";
 import type { WorkerActivities } from "./worker.js";
-import { resolveWorkflowSource, OTEL_WORKFLOW_INTERCEPTOR_MODULE } from "./workflow-source.js";
+import {
+  resolveWorkflowSource,
+  runCredentialWorkflowInterceptorModule,
+  OTEL_WORKFLOW_INTERCEPTOR_MODULE,
+} from "./workflow-source.js";
+import { runCredentialActivityInterceptor } from "./interceptors/run-credential-activity.js";
 import { resolveRunnerBootstrap, refreshRunnerAccessToken } from "./bootstrap.js";
 import { assertLlmBackendsPreflight } from "./preflight.js";
 import {
@@ -816,9 +821,14 @@ async function buildInterceptorConfig(): Promise<InterceptorConfig> {
     "./interceptors/workflow-metrics-sink.js"
   );
 
-  const activityInterceptors: ActivityInterceptorsFactory[] = [];
+  // The run credential's two ends (shared/run-credential.ts), always on and
+  // inert without a credential — the same pair the static root registers
+  // (worker.ts). The workflow module reaches the bundle through
+  // `workflowInterceptorModules` on the runtime path and is baked in on the
+  // pre-built path (scripts/bundle-slim.mjs).
+  const activityInterceptors: ActivityInterceptorsFactory[] = [runCredentialActivityInterceptor];
   let sinks: InjectedSinks<any> = { ...createWorkflowMetricsSinks() };
-  const workflowInterceptorModules: string[] = [];
+  const workflowInterceptorModules: string[] = [runCredentialWorkflowInterceptorModule()];
 
   // In-flight activity counter: keeps a session/wfexec worker alive while one of
   // its activities (notably the long ExecuteCursor) is running, so a view close

package/src/shared/__tests__/channel-attachment.test.ts

@@ -28,6 +28,7 @@ import {
   type ChannelMessagingInfo,
 } from "../channel-attachment.js";
 import type { ResolvedMcpServer } from "../mcp-resolver.js";
+import { STDIO_CREDENTIAL_ENV } from "../synthesized-attachment.js";
 
 function channel(slug: string): MessagingChannel {
   return { channel: slug, provider: "whatsapp" } as MessagingChannel;
@@ -158,9 +159,20 @@ describe("synthesizeChannelAttachment", () => {
     });
   });
 
+  it("the stdio child receives the run's credential as its startup bearer — the memory attachment's twin, one carrier", () => {
+    const attachment = synthesizeChannelAttachment([info("isc-whatsapp", [])], {
+      bridgeEndpoint: null,
+      credential: "run-credential",
+      backendEndpoint: "http://localhost:7234",
+    });
+    expect(attachment?.env).toMatchObject({ [STDIO_CREDENTIAL_ENV]: "run-credential" });
+  });
+
   it("pins the cross-repo strings the mcp-server side guards too", () => {
     expect(CHANNEL_ATTACHMENT_SLUG).toBe("stigmer-channels");
     expect(CHANNELS_ROUTE).toBe("/channels");
+    // The mcp-server's startup-credential variable (mcp-server/src/config.ts).
+    expect(STDIO_CREDENTIAL_ENV).toBe("STIGMER_API_KEY");
   });
 
   it("is approval-free by construction: zero entries in the merged approval map", () => {

package/src/shared/__tests__/memory-attachment.test.ts

@@ -30,6 +30,7 @@ import {
   type MemoryCaptureContext,
 } from "../memory-attachment.js";
 import type { ResolvedMcpServer } from "../mcp-resolver.js";
+import { STDIO_CREDENTIAL_ENV } from "../synthesized-attachment.js";
 
 const context: MemoryCaptureContext = {
   org: "acme",
@@ -117,6 +118,22 @@ describe("synthesizeMemoryAttachment", () => {
     });
   });
 
+  it("the stdio child receives the run's credential as its startup bearer — the same credential the bridge shape presents per request", () => {
+    const attachment = synthesizeMemoryAttachment(enabled, context, {
+      ...ossOptions,
+      credential: "run-credential",
+    });
+    expect(attachment?.connectionType).toBe("stdio");
+    expect(attachment?.env).toMatchObject({
+      [STDIO_CREDENTIAL_ENV]: "run-credential",
+      STIGMER_MCP_ROSTER: "memory",
+    });
+    // The child's environment is byte-for-byte today's when the run carried no credential.
+    expect(synthesizeMemoryAttachment(enabled, context, ossOptions)?.env).not.toHaveProperty(
+      STDIO_CREDENTIAL_ENV,
+    );
+  });
+
   it("omits empty context fields from the carrier — best-effort attribution, never blank entries", () => {
     const partial: MemoryCaptureContext = {
       org: "acme",

package/src/shared/__tests__/run-credential.test.ts

@@ -0,0 +1,111 @@
+/**
+ * The run credential's wire reader and its store (`run-credential.ts`,
+ * `run-credential-store.ts`).
+ *
+ * The property that matters is the last arm: two activities whose awaits
+ * interleave in one process each see their own credential and never the
+ * other's. That is what lets one shared `StigmerClient` — one per worker for
+ * the turn activities — present the right run's credential per request.
+ */
+
+import { describe, expect, it } from "vitest";
+
+import {
+  RUN_CREDENTIAL_HEADER,
+  RUN_CREDENTIAL_INPUT_KEY,
+  readRunCredentialFromInput,
+} from "../run-credential.js";
+import {
+  currentRunCredential,
+  withRunCredential,
+} from "../run-credential-store.js";
+
+describe("readRunCredentialFromInput", () => {
+  it("reads a non-empty string under the wire key", () => {
+    expect(
+      readRunCredentialFromInput({ [RUN_CREDENTIAL_INPUT_KEY]: "cred-1" }),
+    ).toBe("cred-1");
+  });
+
+  it("answers undefined for the positional string shape the turn activities also accept", () => {
+    expect(readRunCredentialFromInput("aex_123")).toBeUndefined();
+  });
+
+  it("answers undefined for a credential-less object — an older server's dispatch", () => {
+    expect(
+      readRunCredentialFromInput({ execution_id: "aex_123", thread_id: "" }),
+    ).toBeUndefined();
+  });
+
+  it("answers undefined for an empty string, null, undefined and a non-string value", () => {
+    expect(
+      readRunCredentialFromInput({ [RUN_CREDENTIAL_INPUT_KEY]: "" }),
+    ).toBeUndefined();
+    expect(readRunCredentialFromInput(null)).toBeUndefined();
+    expect(readRunCredentialFromInput(undefined)).toBeUndefined();
+    expect(
+      readRunCredentialFromInput({ [RUN_CREDENTIAL_INPUT_KEY]: 42 }),
+    ).toBeUndefined();
+  });
+
+  it("does not read the connect lane's camelCase per-call token", () => {
+    expect(
+      readRunCredentialFromInput({ executionContextToken: "connect-token" }),
+    ).toBeUndefined();
+  });
+
+  it("pins the wire vocabulary as bytes", () => {
+    expect(RUN_CREDENTIAL_INPUT_KEY).toBe("execution_context_token");
+    expect(RUN_CREDENTIAL_HEADER).toBe("stigmer-run-credential");
+  });
+});
+
+describe("run-credential store", () => {
+  it("is empty outside any activity", () => {
+    expect(currentRunCredential()).toBeUndefined();
+  });
+
+  it("is visible to everything the wrapped function awaits, and gone after", async () => {
+    let inner: string | undefined;
+    await withRunCredential("cred-a", async () => {
+      await Promise.resolve();
+      inner = await (async () => currentRunCredential())();
+    });
+    expect(inner).toBe("cred-a");
+    expect(currentRunCredential()).toBeUndefined();
+  });
+
+  it("is inherited by a promise created inside the scope and settled after it", async () => {
+    let detached: Promise<string | undefined> | undefined;
+    await withRunCredential("cred-b", async () => {
+      detached = new Promise((resolve) =>
+        setTimeout(() => resolve(currentRunCredential()), 5),
+      );
+    });
+    expect(await detached).toBe("cred-b");
+  });
+
+  it("never crosses between two activities whose awaits interleave", async () => {
+    const seen: Array<[string, string | undefined]> = [];
+    const activity = async (name: string, ticks: number) => {
+      for (let i = 0; i < ticks; i++) {
+        await new Promise((resolve) => setTimeout(resolve, 1));
+        seen.push([name, currentRunCredential()]);
+      }
+    };
+    await Promise.all([
+      withRunCredential("cred-1", () => activity("one", 4)),
+      withRunCredential("cred-2", () => activity("two", 4)),
+      activity("none", 4),
+    ]);
+    expect(seen.filter(([name]) => name === "one").map(([, c]) => c)).toEqual(
+      Array(4).fill("cred-1"),
+    );
+    expect(seen.filter(([name]) => name === "two").map(([, c]) => c)).toEqual(
+      Array(4).fill("cred-2"),
+    );
+    expect(seen.filter(([name]) => name === "none").map(([, c]) => c)).toEqual(
+      Array(4).fill(undefined),
+    );
+  });
+});

package/src/shared/activity-input.ts

@@ -15,6 +15,9 @@
  * then the control planes; once both are everywhere, drop the positional branch
  * (and the `string` arms below).
  */
+
+import type { RUN_CREDENTIAL_INPUT_KEY } from "./run-credential.js";
+
 export interface ExecuteActivityInput {
   readonly execution_id: string;
   readonly thread_id: string;
@@ -27,8 +30,26 @@ export interface ExecuteActivityInput {
    * from it. Absent on the legacy positional wire shape (defaults to 0).
    */
   readonly turn_seq?: number;
+  /**
+   * The run credential the server minted for this execution at dispatch,
+   * handed on from the workflow input; absent when the dispatch carried none
+   * (an older server; the cloud). Not normalized here and never read by an
+   * activity: the activity boundary enters it into the run-credential store
+   * before the activity runs (`interceptors/run-credential-activity.ts`), and
+   * the control-plane client presents it per request (`run-credential.ts`).
+   */
+  readonly execution_context_token?: string;
 }
 
+/**
+ * Compile-time fence: the key the boundary reads
+ * (`RUN_CREDENTIAL_INPUT_KEY`) is a key of this input. The type keeps the
+ * literal so the wire shape stays readable; this line fails to type-check the
+ * day the two disagree.
+ */
+type _RunCredentialKeyIsOnTheWire =
+  ExecuteActivityInput[typeof RUN_CREDENTIAL_INPUT_KEY];
+
 export interface NormalizedActivityInput {
   readonly executionId: string;
   readonly threadId: string;

package/src/shared/channel-attachment.ts

@@ -11,13 +11,16 @@
  * model composes template sends in context without spending a tool
  * round (DD-003 D5).
  *
- * Two connection shapes, one roster (the records pattern):
+ * Two connection shapes, one roster (the records pattern), one
+ * credential — the run's own — presented on both:
  *   - Bridge endpoint configured (cloud): Streamable HTTP against the
- *     bridge's /channels route with the execution's own session-scoped
- *     credential as the Bearer token.
+ *     bridge's /channels route with the run's credential as the Bearer
+ *     token.
  *   - No bridge endpoint (OSS/local): a spawned `stigmer mcp-server`
- *     stdio child with STIGMER_MCP_ROSTER=channels. In practice OSS
- *     answers the discovery read with an empty list (DD-006 D3), so
+ *     stdio child with STIGMER_MCP_ROSTER=channels and the run's
+ *     credential as its startup credential (synthesized-attachment.ts
+ *     `stdioCredentialEnv`, the memory attachment's twin). In practice
+ *     OSS answers the discovery read with an empty list (DD-006 D3), so
  *     this shape only serves local deployments that grow a messaging
  *     runtime later — it exists for symmetry with the deployment
  *     topology, not for a live OSS path today.
@@ -42,7 +45,11 @@ import type {
 } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/message_io_pb";
 import type { StigmerClient } from "../client/stigmer-client.js";
 import type { ResolvedMcpServer } from "./mcp-resolver.js";
-import { grpcTarget, type SynthesizedAttachmentOptions } from "./synthesized-attachment.js";
+import {
+  grpcTarget,
+  stdioCredentialEnv,
+  type SynthesizedAttachmentOptions,
+} from "./synthesized-attachment.js";
 
 /**
  * The synthesized attachment's slug. Reserved: a user McpServer with
@@ -151,6 +158,7 @@ export function synthesizeChannelAttachment(
     env: {
       STIGMER_MCP_ROSTER: "channels",
       STIGMER_SERVER_ADDRESS: grpcTarget(options.backendEndpoint),
+      ...stdioCredentialEnv(options.credential),
     },
   };
 }

package/src/shared/filereview/progress.ts

@@ -24,6 +24,19 @@
  * plus a `changed` flag, so the hybrid can merge both slices even when only one
  * moved (a `ProgressDelta | undefined` would drop the unchanged slice).
  *
+ * WHAT A CAPTURE MAY SEE
+ * ----------------------
+ * A capture rides a persist, and the persist that a tool's start dirtied runs
+ * while that tool may still be writing: the engine does not wait for the
+ * runtime's write to land before it runs the tool. So one snapshot can precede
+ * a tool's write (a turn behind), straddle it (the path present, the counts of
+ * a half-written file), or follow it (the next tool's file already there).
+ * That is accepted, not fixed: the strip is a latest-wins display field and the
+ * next capture converges it, while capturing only between tools would take the
+ * strip's liveness away during exactly the long-running tools it exists for.
+ * A consumer — a console, a test — reads the strip for what it converges to
+ * while the set is CAPTURING, never for what one capture happened to show.
+ *
  * SECRET SAFETY
  * -------------
  * No file bodies are ever carried. A secret-like path ({@link isSecretLikePath})

package/src/shared/memory-attachment.ts

@@ -12,22 +12,29 @@
  * ZERO facts is a meaningful state: memory is on, nothing stored yet —
  * the tool is offered so the first fact can be proposed.
  *
- * Two connection shapes, one roster (the channels pattern):
+ * Two connection shapes, one roster (the channels pattern), one
+ * credential — the run's own — presented on both:
  *   - Bridge endpoint configured (cloud): Streamable HTTP against the
- *     bridge's /memory route with the execution's own session-scoped
- *     credential as the Bearer token, plus the capture context as
- *     per-request headers.
+ *     bridge's /memory route with the run's credential as the Bearer
+ *     token, plus the capture context as per-request headers.
  *   - No bridge endpoint (OSS/local): a spawned `stigmer mcp-server`
- *     stdio child with STIGMER_MCP_ROSTER=memory, plus the capture
- *     context as STIGMER_MEMORY_* env.
+ *     stdio child with STIGMER_MCP_ROSTER=memory, the run's credential
+ *     as its startup credential (synthesized-attachment.ts
+ *     `stdioCredentialEnv`), plus the capture context as
+ *     STIGMER_MEMORY_* env. Without the credential a server that signs
+ *     people in refuses every `remember` as nobody's (stigmer#1147);
+ *     with it the memory is the run's person's, which the server derives
+ *     from the credential and nothing the child says.
  *
  * The capture context (org + agent/session/execution ids) is
  * attribution, never authorization (the Stage 3 provenance decision,
  * owner-ratified 2026-08-22): the cloud create handler accepts it only
  * from a session-sandbox credential and overrides session/org with the
- * token's own claims; the OSS server stores it under the local
- * single-user trust model. The subject is never threaded — the server
- * derives it from the credential (DD-005 D2).
+ * token's own claims; the OSS server under sign-in admits it from the
+ * run's credential and proves the session off the run's row, and stores
+ * it as given under the local single-user trust model. The subject is
+ * never threaded — the server derives it from the credential (DD-005
+ * D2).
  *
  * Approval-free by construction (the synthesized-attachment contract):
  * the tool only ever creates a PROPOSAL the user must confirm through
@@ -44,7 +51,11 @@
 
 import type { RecalledMemories } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/spec_pb";
 import type { ResolvedMcpServer } from "./mcp-resolver.js";
-import { grpcTarget, type SynthesizedAttachmentOptions } from "./synthesized-attachment.js";
+import {
+  grpcTarget,
+  stdioCredentialEnv,
+  type SynthesizedAttachmentOptions,
+} from "./synthesized-attachment.js";
 
 /**
  * The synthesized attachment's slug. Reserved: a user McpServer with
@@ -149,6 +160,7 @@ export function synthesizeMemoryAttachment(
     env: {
       STIGMER_MCP_ROSTER: "memory",
       STIGMER_SERVER_ADDRESS: grpcTarget(options.backendEndpoint),
+      ...stdioCredentialEnv(options.credential),
       ...nonEmptyEntries([
         [MEMORY_ORG_ENV, context.org],
         [MEMORY_AGENT_ID_ENV, context.agentId],

package/src/shared/run-credential-store.ts

@@ -0,0 +1,45 @@
+/**
+ * The run credential of the activity that is running — an `AsyncLocalStorage`
+ * the activity boundary enters once and the control-plane transport reads
+ * per request.
+ *
+ * Why a store and not a parameter: the runner serves many executions in one
+ * process, and the `StigmerClient` a request goes out on is shared — one per
+ * worker for the turn activities (`harness/registry.ts`), one per call or a
+ * module singleton for the engine's activities. A credential baked into a
+ * client would be the wrong run's the moment two runs share it; a credential
+ * read from the async context of the request is always the run whose
+ * activity made the request, and a client cached across runs stays correct.
+ * `shared/execution-context.ts` is the same shape for the execution id, with
+ * a different owner (the turn runtime enters it INSIDE the turn) and a
+ * different reader (the Cursor proxy interceptors) — two facts, two stores.
+ *
+ * Exactly one writer — `interceptors/run-credential-activity.ts`, the
+ * activity inbound interceptor both worker roots register — and exactly one
+ * reader — the auth interceptor in `client/stigmer-client.ts`. Nothing else
+ * may read this: a user task's outbound HTTP (`activities/call-http.ts`) must
+ * never carry the run's credential, and the way that stays true is that no
+ * code path but the control-plane client asks for it.
+ */
+
+import { AsyncLocalStorage } from "node:async_hooks";
+
+const runCredential = new AsyncLocalStorage<string>();
+
+/** Run `fn` with `credential` as the run credential of everything it awaits. */
+export function withRunCredential<T>(
+  credential: string,
+  fn: () => Promise<T>,
+): Promise<T> {
+  return runCredential.run(credential, fn);
+}
+
+/**
+ * The run credential of the activity this request belongs to; `undefined`
+ * outside any activity (boot, renewal loops) and inside an activity whose
+ * dispatch carried none (an older server; the cloud, whose runner credential
+ * is provisioned, not dispatched).
+ */
+export function currentRunCredential(): string | undefined {
+  return runCredential.getStore();
+}

package/src/shared/run-credential.ts

@@ -0,0 +1,70 @@
+/**
+ * The run credential's wire vocabulary — the two places a dispatch can carry
+ * it, and the one reader of both.
+ *
+ * A run credential is the token the control plane mints for ONE execution at
+ * dispatch (`execution_context_token` on the workflow input, 2026-09-16) so
+ * that the runner — one long-lived process keyed with one operator's API key,
+ * serving every member's runs — can act as the run's own human on that run's
+ * RPCs. Under a server with sign-in on, the credential's bearer IS the run's
+ * person for as long as the run lives; on an older server no credential
+ * arrives and the runner behaves exactly as before. The runner never decodes
+ * or judges the credential: it presents, the server judges
+ * (`client/token-claims.ts`).
+ *
+ * Two hops carry it, one channel each:
+ *
+ *   - The SERVER's dispatches — the Execute* turn activities and
+ *     GenerateSessionSubject — carry it on the activity INPUT under
+ *     {@link RUN_CREDENTIAL_INPUT_KEY}, the same key the workflow inputs use
+ *     (a cross-component wire contract; the server's
+ *     temporal/agentexecution/workflows/invoke-agent-execution.ts builds it).
+ *   - The RUNNER's own dispatches — every activity the serverless-workflow
+ *     engine schedules from `workflows/execute-from-execution.ts` — carry it
+ *     as a Temporal activity HEADER, {@link RUN_CREDENTIAL_HEADER}, stamped by
+ *     the workflow interceptor in `workflows/interceptors/run-credential.ts`.
+ *     Headers, not arguments: the engine hands `execution_id` to ten local
+ *     activities positionally, and a credential threaded the same way is a
+ *     field every future activity has to remember. A header reaches all of
+ *     them, and the next one, with no signature learning the word.
+ *
+ * One reader for both: `interceptors/run-credential-activity.ts` enters the
+ * store (`run-credential-store.ts`) at the activity boundary, and
+ * `client/stigmer-client.ts` reads it per request. No activity body touches
+ * a credential.
+ *
+ * ISOLATE-SAFE BY CONTRACT: this module is imported by workflow code that
+ * runs inside Temporal's deterministic V8 sandbox. It must import nothing
+ * from Node and hold no mutable state; the store lives in its own module for
+ * exactly that reason.
+ */
+
+/**
+ * The snake_case key under which a dispatch's input object carries the run
+ * credential. Byte-pinned: the same name on both invoke workflow inputs, on
+ * `ExecuteActivityInput`, on `GenerateSessionSubjectInput` and on the connect
+ * lane's input (where it names a DIFFERENT, clocked token that this reader
+ * never sees — that lane hands its token per call).
+ */
+export const RUN_CREDENTIAL_INPUT_KEY = "execution_context_token" as const;
+
+/**
+ * The Temporal activity header the runner's own workflow stamps on every
+ * activity it schedules for a run. Byte-pinned wire vocabulary: a rename
+ * strands every in-flight run's activities on the process credential.
+ */
+export const RUN_CREDENTIAL_HEADER = "stigmer-run-credential" as const;
+
+/**
+ * The run credential an activity input carries, or `undefined` when the
+ * argument is not an object carrying a non-empty string under the key —
+ * positional string arguments, the connect lane's camelCase input, and an
+ * older server's credential-less object all answer `undefined`.
+ */
+export function readRunCredentialFromInput(arg: unknown): string | undefined {
+  if (arg === null || typeof arg !== "object") {
+    return undefined;
+  }
+  const value = (arg as Record<string, unknown>)[RUN_CREDENTIAL_INPUT_KEY];
+  return typeof value === "string" && value !== "" ? value : undefined;
+}

package/src/shared/synthesized-attachment.ts

@@ -28,9 +28,14 @@ export interface SynthesizedAttachmentOptions {
    */
   bridgeEndpoint: string | null;
   /**
-   * The execution's session-scoped credential (the sandbox token a
-   * cloud runner holds, or the desktop runner's exchanged scoped
-   * token). Null attaches no Authorization header (OSS/local).
+   * The credential of the RUN this attachment serves — the run's own
+   * credential the server minted at dispatch (the OSS shape), or the
+   * session-scoped sandbox token a cloud runner holds. Both connection
+   * shapes present it: as the Bearer on the bridge's per-request path,
+   * and as the stdio child's startup credential (`stdioCredentialEnv`),
+   * so what the child writes on the person's behalf is stamped as that
+   * person and not refused as nobody's on a server that signs people in.
+   * Null presents nothing (a run whose dispatch carried no credential).
    */
   credential: string | null;
   /**
@@ -40,6 +45,36 @@ export interface SynthesizedAttachmentOptions {
   backendEndpoint: string;
 }
 
+/**
+ * The mcp-server's startup-credential variable — the ONE name the stdio
+ * child reads its bearer from (mcp-server/src/config.ts `STIGMER_API_KEY`;
+ * the value is any bearer the server honours, an `stk_` key for an IDE
+ * client, the run's credential here). Cross-repo string, pinned on both
+ * sides (the TOOL_CALL_LIMIT precedent).
+ */
+export const STDIO_CREDENTIAL_ENV = "STIGMER_API_KEY";
+
+/**
+ * The stdio child's startup-credential entry: `{ STIGMER_API_KEY }` when the
+ * attachment holds a credential, nothing when it holds none — so a
+ * credential-less run's child environment is byte-for-byte today's, and
+ * the two stdio shapes cannot disagree on the carrier.
+ *
+ * The exposure, stated once: the credential sits in a first-party child's
+ * process environment on the runner host, readable by the same OS user.
+ * That is the runner's own trust boundary (the runner process holds the
+ * same credential), and the child is `stigmer mcp-server`, never a
+ * third-party server — those receive only their declared env (oss#256,
+ * mcp-manager.ts). The alternative was the operator's API key.
+ */
+export function stdioCredentialEnv(
+  credential: string | null,
+): Record<string, string> {
+  return credential !== null && credential !== ""
+    ? { [STDIO_CREDENTIAL_ENV]: credential }
+    : {};
+}
+
 /**
  * Inject a synthesized attachment into a resolved server list — AFTER
  * resolve + backfill (see the module header). A user server shadowing

package/src/worker.ts

@@ -18,7 +18,12 @@ import { createRequire } from "node:module";
 import { NativeConnection, Worker, type ActivityInterceptorsFactory, type InjectedSinks } from "@temporalio/worker";
 import type { PayloadCodec } from "@temporalio/common";
 import type { Config } from "./config.js";
-import { resolveWorkflowSource, OTEL_WORKFLOW_INTERCEPTOR_MODULE } from "./workflow-source.js";
+import {
+  resolveWorkflowSource,
+  runCredentialWorkflowInterceptorModule,
+  OTEL_WORKFLOW_INTERCEPTOR_MODULE,
+} from "./workflow-source.js";
+import { runCredentialActivityInterceptor } from "./interceptors/run-credential-activity.js";
 
 export interface WorkerActivities {
   [key: string]: (...args: any[]) => Promise<unknown>;
@@ -42,9 +47,16 @@ export async function startWorker(opts: StartWorkerOptions): Promise<Worker> {
 
   const workflowSource = resolveWorkflowSource();
 
-  const activityInterceptors: ActivityInterceptorsFactory[] = [];
+  // The run credential's two ends (shared/run-credential.ts): the workflow
+  // side lifts a run's credential onto every activity it schedules, the
+  // activity side enters it for the client to present. Always on; inert
+  // without a credential. Workflow-side modules must live INSIDE the
+  // workflow bundle — a pre-built bundle has it baked in
+  // (scripts/bundle-slim.mjs); only the runtime path registers it here.
+  const activityInterceptors: ActivityInterceptorsFactory[] = [runCredentialActivityInterceptor];
   let sinks: InjectedSinks<any> = { ...createWorkflowMetricsSinks() };
-  const workflowInterceptorModules: string[] = [];
+  const workflowInterceptorModules: string[] =
+    workflowSource.kind === "runtime" ? [runCredentialWorkflowInterceptorModule()] : [];
 
   if (process.env.OTEL_EXPORTER_OTLP_ENDPOINT) {
     const {

package/src/workflow-source.ts

@@ -44,6 +44,21 @@ export type WorkflowSource =
 export const OTEL_WORKFLOW_INTERCEPTOR_MODULE =
   "@temporalio/interceptors-opentelemetry/lib/workflow-interceptors";
 
+/**
+ * Path of the runner's own workflow interceptor — the one that carries a
+ * run's credential from the workflow input to every activity it schedules
+ * (`workflows/interceptors/run-credential.ts`). Always registered, unlike
+ * the OTel module: it is inert without a credential and load-bearing with
+ * one. Resolved beside this module so the tsc dist and the slim artifact
+ * both find their own compiled copy; the build script names the source
+ * file itself.
+ */
+export function runCredentialWorkflowInterceptorModule(): string {
+  return fileURLToPath(
+    new URL("./workflows/interceptors/run-credential.js", import.meta.url),
+  );
+}
+
 export function resolveWorkflowSource(): WorkflowSource {
   const explicit = process.env.STIGMER_WORKFLOW_BUNDLE;
   if (explicit) {