@stigmer/runner 3.21.0 → 3.22.1-dev.20260922095755

package/src/activities/promote-task-output.ts

@@ -14,7 +14,7 @@
  */
 
 import { StigmerClient } from "../client/stigmer-client.js";
-import { loadConfig } from "../config.js";
+import type { Config } from "../config.js";
 import { create } from "@bufbuild/protobuf";
 import {
   CreateArtifactInputSchema,
@@ -44,20 +44,16 @@ export interface ArtifactCreatedEventDescriptor {
   occurredAt: string;
 }
 
-let cachedClient: StigmerClient | null = null;
+export function createPromoteTaskOutputActivities(config: Config) {
+  // One client for the factory's life, from the runner's injected Config: it
+  // reads the live credential ref per request (config.ts header), so holding
+  // it is safe across every rotation.
+  const client = new StigmerClient({
+    endpoint: config.stigmerBackendEndpoint,
+    tokenRef: config.stigmerTokenRef,
+    runnerTokenRef: config.stigmerRunnerTokenRef,
+  });
 
-function getClient(): StigmerClient {
-  if (!cachedClient) {
-    const config = loadConfig();
-    cachedClient = new StigmerClient({
-      endpoint: config.stigmerBackendEndpoint,
-      token: config.stigmerToken,
-    });
-  }
-  return cachedClient;
-}
-
-export function createPromoteTaskOutputActivities() {
   return {
     /**
      * Check if a task output should be promoted to an artifact. If the
@@ -107,7 +103,7 @@ export function createPromoteTaskOutputActivities() {
         content: new Uint8Array(contentBytes),
       });
 
-      const artifact = await getClient().createArtifact(input);
+      const artifact = await client.createArtifact(input);
       const artifactId = artifact.metadata?.id ?? "";
 
       return {

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

@@ -15,7 +15,7 @@
  */
 
 import { StigmerClient } from "../client/stigmer-client.js";
-import { loadConfig } from "../config.js";
+import type { Config } from "../config.js";
 import { create, fromJson } from "@bufbuild/protobuf";
 import { ValueSchema } from "@bufbuild/protobuf/wkt";
 import {
@@ -136,14 +136,6 @@ function toJsonObject(value: unknown): JsonObject | undefined {
   }
 }
 
-function buildClient(): StigmerClient {
-  const config = loadConfig();
-  return new StigmerClient({
-    endpoint: config.stigmerBackendEndpoint,
-    token: config.stigmerToken,
-  });
-}
-
 /**
  * LEGACY sequence assignment — only for descriptors that arrive without a
  * workflow-assigned `sequenceNumber`, i.e. replays of histories recorded
@@ -181,12 +173,11 @@ function nextSequence(): bigint {
  * Returns a plain number — the value crosses back into the workflow
  * through Temporal's JSON payload converter, which cannot carry BigInt.
  */
-export async function initSequenceFromEventLog(executionId: string): Promise<number> {
+export async function initSequenceFromEventLog(client: StigmerClient, executionId: string): Promise<number> {
   if (!executionId) {
     sequenceCounter = 0;
     return 0;
   }
-  const client = buildClient();
   const highWaterMark = await client.getEventLogHighWaterMark(executionId);
   sequenceCounter = Number(highWaterMark);
   return sequenceCounter;
@@ -417,13 +408,13 @@ export function toProtoEvent(desc: WorkflowEventDescriptor): WorkflowExecutionEv
  * exhausted, so a broken timeline write never fails the run.
  */
 export async function emitWorkflowEvents(
+  client: StigmerClient,
   executionId: string,
   events: WorkflowEventDescriptor[],
   taskStatuses?: TaskStatusEntry[],
 ): Promise<void> {
   if (!executionId || events.length === 0) return;
 
-  const client = buildClient();
   const protoEvents = events.map(toProtoEvent);
 
   const protoTasks = (taskStatuses ?? []).map(ts =>
@@ -507,8 +498,7 @@ function structToPlain(value: JsonObject | undefined): unknown {
  * Unlike emitWorkflowEvents (best-effort), this activity propagates
  * errors — recovery context loading is required for correctness.
  */
-export async function loadRecoveryContext(executionId: string): Promise<RecoveryTaskData[]> {
-  const client = buildClient();
+export async function loadRecoveryContext(client: StigmerClient, executionId: string): Promise<RecoveryTaskData[]> {
   const execution = await client.getWorkflowExecution(executionId);
   const tasks = execution.status?.tasks ?? [];
 
@@ -519,10 +509,19 @@ export async function loadRecoveryContext(executionId: string): Promise<Recovery
   }));
 }
 
-export function createWorkflowEventActivities() {
+export function createWorkflowEventActivities(config: Config) {
+  // One client from the runner's injected Config: it reads the live credential
+  // ref per request (config.ts header), so a rotation reaches these writes.
+  const client = new StigmerClient({
+    endpoint: config.stigmerBackendEndpoint,
+    tokenRef: config.stigmerTokenRef,
+    runnerTokenRef: config.stigmerRunnerTokenRef,
+  });
+
   return {
-    EmitWorkflowEvents: emitWorkflowEvents,
-    ResetEventSequence: initSequenceFromEventLog,
-    LoadRecoveryContext: loadRecoveryContext,
+    EmitWorkflowEvents: (executionId: string, events: WorkflowEventDescriptor[], taskStatuses?: TaskStatusEntry[]) =>
+      emitWorkflowEvents(client, executionId, events, taskStatuses),
+    ResetEventSequence: (executionId: string) => initSequenceFromEventLog(client, executionId),
+    LoadRecoveryContext: (executionId: string) => loadRecoveryContext(client, executionId),
   };
 }

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

@@ -93,20 +93,22 @@ describe("StigmerClient", () => {
       expect(req.header.has("authorization")).toBe(false);
     });
 
-    it("updateToken() changes the token used on subsequent requests", async () => {
-      const client = new StigmerClient({ endpoint: "http://localhost", token: "old" });
+    it("a rotation is a write to the shared ref, never a method on the client: the next request carries the new value", async () => {
+      const ref: TokenRef = { current: "old" };
+      new StigmerClient({ endpoint: "http://localhost", tokenRef: ref });
 
-      client.updateToken("new-tok");
+      ref.current = "new-tok";
 
       const req = makeRequest();
       await runInterceptor(req);
       expect(req.header.get("authorization")).toBe("Bearer new-tok");
     });
 
-    it("updateToken(null) removes the Authorization header", async () => {
-      const client = new StigmerClient({ endpoint: "http://localhost", token: "tok" });
+    it("a ref rotated to null removes the Authorization header", async () => {
+      const ref: TokenRef = { current: "tok" };
+      new StigmerClient({ endpoint: "http://localhost", tokenRef: ref });
 
-      client.updateToken(null);
+      ref.current = null;
 
       const req = makeRequest();
       await runInterceptor(req);
@@ -623,19 +625,6 @@ describe("StigmerClient", () => {
     });
   });
 
-  describe("updateToken", () => {
-    it("does not affect tokenRef-based resolution", async () => {
-      const ref: TokenRef = { current: "from-ref" };
-      const client = new StigmerClient({ endpoint: "http://localhost", token: null, tokenRef: ref });
-
-      client.updateToken("from-update");
-
-      const req = makeRequest();
-      await runInterceptor(req);
-      expect(req.header.get("authorization")).toBe("Bearer from-ref");
-    });
-  });
-
   describe("transport", () => {
     it("exposes transport as a readonly property", () => {
       const client = new StigmerClient({ endpoint: "http://localhost", token: null });

package/src/client/stigmer-client.ts

@@ -55,6 +55,7 @@ import { ChannelMessageQueryController } from "@stigmer/protos/ai/stigmer/agenti
 import type { ChannelTemplate, MessagingChannel } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/message_io_pb";
 import { TOKEN_TYPE_EMBEDDED_RUNNER, tokenTypeOf } from "./token-claims.js";
 import { assertCreateRequirements, assertReferenceRequirements } from "./server-contracts.js";
+import type { TokenRef } from "../config.js";
 import { currentRunCredential } from "../shared/run-credential-store.js";
 
 /**
@@ -151,31 +152,31 @@ function toRunnerScopedTokenOneof(scope: RunnerScopedTokenScope) {
   return { case: "renewal", value: create(TokenRenewalSchema) } as const;
 }
 
-/**
- * A shared mutable token reference. When provided, the interceptor
- * reads from this on every request, enabling token updates to
- * propagate to all clients sharing the same ref.
- */
-export interface TokenRef {
-  current: string | null;
-}
+/** The runner's shared credential reference (config.ts); re-exported for the client's callers. */
+export type { TokenRef };
 
 export interface StigmerClientOptions {
   endpoint: string;
-  token: string | null;
-  tokenRef?: TokenRef;
+  /**
+   * A fixed credential, for a client whose credential never rotates (a
+   * renewal client that authenticates each call explicitly passes `null`).
+   * Runner activities pass {@link tokenRef} instead: the interceptor reads
+   * it on every request, so one rotation reaches every client sharing it.
+   */
+  token?: string | null;
+  tokenRef?: Readonly<TokenRef>;
   /**
    * Optional runner credential (a server-minted token with a runner-class
    * `token_type` claim). When populated, ExecutionContext reads authenticate
    * with this instead of the control-plane token — see the interceptor in the
    * constructor for why the credential differs per service.
    */
-  runnerTokenRef?: TokenRef;
+  runnerTokenRef?: Readonly<TokenRef>;
 }
 
 export class StigmerClient {
   readonly transport: Transport;
-  private currentToken: string | null;
+  private readonly fixedToken: string | null;
   private readonly executionQuery: Client<typeof AgentExecutionQueryController>;
   private readonly executionCommand: Client<typeof AgentExecutionCommandController>;
   private readonly executionContextQuery: Client<typeof ExecutionContextQueryController>;
@@ -195,11 +196,11 @@ export class StigmerClient {
   private readonly platformQuery: Client<typeof PlatformQueryController>;
   private readonly channelMessageQuery: Client<typeof ChannelMessageQueryController>;
 
-  private readonly tokenRef: TokenRef | null;
-  private readonly runnerTokenRef: TokenRef | null;
+  private readonly tokenRef: Readonly<TokenRef> | null;
+  private readonly runnerTokenRef: Readonly<TokenRef> | null;
 
   constructor(options: StigmerClientOptions) {
-    this.currentToken = options.token;
+    this.fixedToken = options.token ?? null;
     this.tokenRef = options.tokenRef ?? null;
     this.runnerTokenRef = options.runnerTokenRef ?? null;
     this.transport = createGrpcTransport({
@@ -274,7 +275,7 @@ export class StigmerClient {
             (isProcessBound ? undefined : currentRunCredential())
             ?? (usesRunnerCredential ? this.runnerTokenRef?.current : null)
             ?? this.tokenRef?.current
-            ?? this.currentToken;
+            ?? this.fixedToken;
           if (token) {
             req.header.set("authorization", `Bearer ${token}`);
           }
@@ -467,7 +468,7 @@ export class StigmerClient {
     }
     // Inspect the same credential chain the EC read's interceptor would use.
     const ambientTokenType = tokenTypeOf(
-      this.runnerTokenRef?.current ?? this.tokenRef?.current ?? this.currentToken,
+      this.runnerTokenRef?.current ?? this.tokenRef?.current ?? this.fixedToken,
     );
     const isEmbeddedRunner = ambientTokenType === TOKEN_TYPE_EMBEDDED_RUNNER;
     if (ambientTokenType !== undefined && !isEmbeddedRunner) {
@@ -762,7 +763,4 @@ export class StigmerClient {
     return this.workflowInstanceQuery.get({ value: instanceId });
   }
 
-  updateToken(token: string | null): void {
-    this.currentToken = token;
-  }
 }

package/src/config.ts

@@ -20,6 +20,21 @@
  *    - CURSOR_API_KEY is NOT required — the proxy injects it.
  *    - The fetch interceptor rewrites outbound Cursor SDK requests.
  *
+ * The credential is never held by value:
+ *
+ * The control-plane credential rotates while the process runs (the manager's
+ * `updateToken` on a pool claim or a host refresh, the static root's
+ * sandbox-token renewal), so `Config` carries it as a shared {@link TokenRef}
+ * and nothing else. Every reader resolves `ref.current` at the moment of use;
+ * a client that makes many requests over its life holds the ref and reads it
+ * per request (the artifact store, the checkpoint saver). The two roots own
+ * the writable ref; readers see it through `Readonly`, so a rotation has one
+ * writer and no copy to go stale. {@link loadConfig} is the environment
+ * boundary and is read once, by `main.ts`: the ref it returns holds the boot
+ * capture that the roots turn into the live ref (a test pins that no other
+ * module imports it). The only by-value reads are the pool boot's, where the
+ * credential the pod BOOTED with is the fact (`main.ts`).
+ *
  * Workspace isolation:
  *
  * WORKSPACE_ROOT_DIR must always resolve to a directory that is NOT the
@@ -58,12 +73,28 @@ export { DEFAULT_WORKSPACE_LOCK_TIMEOUT_MS } from "./shared/workspace/workspace-
 import { DEFAULT_WORKSPACE_LOCK_TIMEOUT_MS } from "./shared/workspace/workspace-lock.js";
 import { getRunnerSecret } from "./shared/runner-credential-store.js";
 
+/**
+ * A shared mutable credential reference. The root that owns a credential
+ * writes `current` on every rotation; every reader resolves it at the moment
+ * of use, so one write reaches all of them (the per-request reads in the
+ * Cursor interceptors, StigmerClient, the artifact store and the checkpoint
+ * saver). `Config` hands readers a `Readonly` view: rotation has one writer.
+ */
+export interface TokenRef {
+  current: string | null;
+}
+
 export interface Config {
   readonly taskQueue: string;
   readonly temporalAddress: string;
   readonly temporalNamespace: string;
   readonly stigmerBackendEndpoint: string;
-  readonly stigmerToken: string | null;
+  /**
+   * The control-plane credential, read per use (the module header). The
+   * static root and the manager both rotate it in place; `main.ts`'s
+   * `loadConfig` result holds the boot capture the roots start from.
+   */
+  readonly stigmerTokenRef: Readonly<TokenRef>;
   /**
    * The MCP bridge endpoint for the runner-synthesized attachments —
    * channel messaging and conversation participation
@@ -74,14 +105,12 @@ export interface Config {
    */
   readonly mcpBridgeEndpoint: string | null;
   /**
-   * Bearer credential for the Cursor SDK's Connect RPC transport.
-   *
-   * - Direct mode: the real Cursor API key (authenticates with Cursor directly).
-   * - Proxy mode: the STIGMER_TOKEN JWT (authenticates with our BiDi proxy,
-   *   which validates it and injects the real Cursor key upstream).
-   *
-   * Named after the CURSOR_API_KEY env var the SDK reads, though in proxy mode
-   * the credential authenticates with the proxy endpoint, not with Cursor.
+   * The Cursor API key for direct mode (authenticates with Cursor directly).
+   * In proxy mode this is a placeholder (`"proxy-managed"` unless the operator
+   * set CURSOR_API_KEY anyway): the credential the SDK transport presents to
+   * the proxy is the control-plane credential, read from
+   * {@link stigmerTokenRef} per turn by the Cursor adapter, never copied here.
+   * Named after the CURSOR_API_KEY env var the SDK reads.
    */
   readonly cursorApiKey: string;
   readonly workspaceRootDir: string;
@@ -136,16 +165,14 @@ export interface Config {
    * See shared/workspace/workspace-lock.ts for the serialization model.
    */
   readonly workspaceLockTimeoutMs: number;
-  /** Shared mutable token reference for dynamic token updates (manager mode). */
-  readonly stigmerTokenRef?: { current: string | null };
   /**
-   * Shared mutable reference to the runner credential (manager mode): the
+   * Shared reference to the runner credential (the roots bind it): the
    * server-minted runner token once adopted, tracking the control-plane token
    * in lockstep before that. StigmerClient authenticates ExecutionContext
    * reads with it so the server's runner-class decrypt gate recognizes a
    * desktop runner (see stigmer-client.ts).
    */
-  readonly stigmerRunnerTokenRef?: { current: string | null };
+  readonly stigmerRunnerTokenRef?: Readonly<TokenRef>;
   /**
    * Shared mutable reference to the credential the Cursor proxy transport
    * sends as `x-stigmer-auth` (the fetch and HTTP/2 interceptors read it per
@@ -158,7 +185,7 @@ export interface Config {
    * Required whenever `proxyEndpoint` is set; the Cursor adapter's
    * boot refuses a proxy without it.
    */
-  readonly proxyTokenRef?: { current: string | null };
+  readonly proxyTokenRef?: Readonly<TokenRef>;
 }
 
 export function loadConfig(): Config {
@@ -186,22 +213,23 @@ export function loadConfig(): Config {
   );
 
   // Secrets resolve through the credential store, not process.env — the
-  // boot capture has already moved them out of the environment (#508).
+  // boot capture has already moved them out of the environment (#508). The
+  // ref holds the boot capture: this function is read once, by main.ts, and
+  // the root it feeds builds the live ref from the value (the module header).
   const stigmerTokenValue = getRunnerSecret("STIGMER_TOKEN");
   if ((mode === "cloud" || proxyActive) && !stigmerTokenValue) {
     throw new Error("Required environment variable STIGMER_TOKEN is not set");
   }
-  const stigmerToken = stigmerTokenValue ?? null;
+  const stigmerTokenRef: TokenRef = { current: stigmerTokenValue ?? null };
 
   const mcpBridgeEndpoint = process.env.STIGMER_MCP_BRIDGE_ENDPOINT ?? null;
 
-  // In proxy mode, pass STIGMER_TOKEN as the SDK's API key. The SDK exchanges
-  // it (via REST proxy → Tomcat → Cursor) for an access token. The HTTP/2
-  // interceptor injects x-stigmer-auth for BiDi proxy authentication while
-  // the SDK's authorization header (Cursor access token) passes through to
-  // api2.cursor.sh unchanged.
+  // In proxy mode the SDK's API key is the control-plane credential, which the
+  // Cursor adapter reads from the ref per turn (execute-cursor/turn-setup.ts);
+  // the placeholder here is the two option mappers' exact value, so the three
+  // construction sites agree and no copy of the credential rides in Config.
   const cursorApiKey = proxyActive
-    ? (getRunnerSecret("CURSOR_API_KEY") ?? stigmerToken ?? "proxy-managed")
+    ? (getRunnerSecret("CURSOR_API_KEY") ?? "proxy-managed")
     : (getRunnerSecret("CURSOR_API_KEY") ?? "");
 
   const workspaceRootDir = resolveWorkspaceRootDir();
@@ -245,7 +273,7 @@ export function loadConfig(): Config {
     temporalAddress,
     temporalNamespace,
     stigmerBackendEndpoint,
-    stigmerToken,
+    stigmerTokenRef,
     mcpBridgeEndpoint,
     cursorApiKey,
     workspaceRootDir,

package/src/harness/registry.ts

@@ -104,7 +104,6 @@ export async function createHarnessActivities(
   const { StigmerClient } = await import("../client/stigmer-client.js");
   const client: StigmerClient = new StigmerClient({
     endpoint: config.stigmerBackendEndpoint,
-    token: config.stigmerToken,
     tokenRef: config.stigmerTokenRef,
     runnerTokenRef: config.stigmerRunnerTokenRef,
   });

package/src/harness/turn-context.ts

@@ -724,9 +724,7 @@ export async function resolveMcpServersAndPolicies(
       `reads; degrading to the ambient credential: ${err instanceof Error ? err.message : err}`,
     );
   }
-  const attachmentCredential = exchangedRunnerToken
-    ?? config.stigmerTokenRef?.current
-    ?? config.stigmerToken;
+  const attachmentCredential = exchangedRunnerToken ?? config.stigmerTokenRef.current;
   const attachmentEndpoints = {
     bridgeEndpoint: config.mcpBridgeEndpoint,
     credential: attachmentCredential,
@@ -1004,7 +1002,7 @@ export function resolveStandingContext(
   const selectRecalledMemories = (): Promise<RecalledMemoriesContent | undefined> => {
     memorySelection ??= selectRecalledFacts(spec.recalledMemories, spec.message, {
       proxyEndpoint: deps.config.proxyEndpoint,
-      stigmerToken: deps.config.stigmerToken,
+      stigmerToken: deps.config.stigmerTokenRef.current,
       executionId: deps.input.executionId,
       priorReport: execution.status?.recalledMemoriesReport,
     }).then((selection) => {

package/src/main.ts

@@ -81,7 +81,7 @@ async function runManagerMode(config: import("./config.js").Config): Promise<voi
       temporalAddress: config.temporalAddress,
       temporalNamespace: config.temporalNamespace,
       stigmerEndpoint: config.stigmerBackendEndpoint,
-      stigmerToken: config.stigmerToken ?? undefined,
+      stigmerToken: config.stigmerTokenRef.current ?? undefined,
       cursorApiKey: config.cursorApiKey || undefined,
       workspaceRootDir: config.workspaceRootDir,
       maxConcurrentActivitiesPerSession: config.maxConcurrentActivities,
@@ -197,7 +197,14 @@ async function runPoolMode(
   // process serves (the control plane rewrites the Secret at claim time, and
   // secretKeyRef env is read only at pod start — so a restart lands here with
   // the post-claim identity). Decide before any expensive boot work.
-  const intent = decidePoolBoot(config.stigmerToken);
+  //
+  // Read by value on purpose — the one place the runner may: the credential
+  // the pod BOOTED with is the fact here. Its class decides the mode, and the
+  // attach exchange must authenticate with the pool credential after the
+  // claim has rotated the live ref to the session's (pool-member.ts,
+  // PoolMemberContext.poolToken). Everything after this line reads the ref.
+  const bootToken = config.stigmerTokenRef.current;
+  const intent = decidePoolBoot(bootToken);
   if (intent.kind === "invalid") {
     throw new Error(`Pool member ${memberId} cannot boot: ${intent.reason}`);
   }
@@ -206,7 +213,7 @@ async function runPoolMode(
     temporalAddress: config.temporalAddress,
     temporalNamespace: config.temporalNamespace,
     stigmerEndpoint: config.stigmerBackendEndpoint,
-    stigmerToken: config.stigmerToken ?? undefined,
+    stigmerToken: config.stigmerTokenRef.current ?? undefined,
     cursorApiKey: config.cursorApiKey || undefined,
     workspaceRootDir: config.workspaceRootDir,
     maxConcurrentActivitiesPerSession: config.maxConcurrentActivities,
@@ -243,7 +250,7 @@ async function runPoolMode(
   if (intent.kind === "pool-control") {
     registerPoolMemberContext({
       memberId,
-      poolToken: config.stigmerToken!,
+      poolToken: bootToken!,
       manager,
     });
     await manager.addPoolControl(memberId);
@@ -332,7 +339,7 @@ async function runStaticMode(config: import("./config.js").Config): Promise<void
     temporalAddress: config.temporalAddress,
     temporalNamespace: config.temporalNamespace,
     stigmerEndpoint: config.stigmerBackendEndpoint,
-    stigmerToken: config.stigmerToken ?? undefined,
+    stigmerToken: config.stigmerTokenRef.current ?? undefined,
     cursorApiKey: config.cursorApiKey || undefined,
     workspaceRootDir: config.workspaceRootDir,
     maxConcurrentActivities: config.maxConcurrentActivities,
@@ -495,7 +502,7 @@ async function main(): Promise<void> {
     : "static";
   console.warn(
     `[runner] mode=${runnerMode}, proxy=${config.proxyEndpoint ?? "none"}, ` +
-    `hasToken=${!!config.stigmerToken}, workspace=${config.workspaceRootDir}, ` +
+    `hasToken=${!!config.stigmerTokenRef.current}, workspace=${config.workspaceRootDir}, ` +
     `taskQueue=${config.taskQueue}`,
   );
 

package/src/runner-manager.ts

@@ -22,7 +22,7 @@ import {
   type InjectedSinks,
   type WorkflowBundleOption,
 } from "@temporalio/worker";
-import type { Config } from "./config.js";
+import type { Config, TokenRef } from "./config.js";
 import { DEFAULT_CURSOR_AGENT_RESOLVE_TIMEOUT_MS, DEFAULT_CURSOR_STREAM_STALL_TIMEOUT_MS, DEFAULT_WORKSPACE_LOCK_TIMEOUT_MS } from "./config.js";
 // Boot marks mirror the static runner's segment names where the work is the
 // same. Inert unless a mode emits the boot timeline (pool mode does; the
@@ -237,7 +237,7 @@ export async function createStigmerRunnerManager(
   // separately by a RunnerTokenCoordinator (created after the harnesses boot)
   // — see that module for the two-writer rationale and the staleness history
   // it guards.
-  const tokenRef = { current: options.stigmerToken ?? null };
+  const tokenRef: TokenRef = { current: options.stigmerToken ?? null };
   // `runnerTokenRef` mirrors the coordinator's proxy credential for gRPC use:
   // the minted runner token (token_type=embedded_runner) once adopted, tracking
   // the control-plane token in lockstep before that. StigmerClient authenticates
@@ -246,7 +246,7 @@ export async function createStigmerRunnerManager(
   // is the user's own Auth0 token, which the server treats as a browsing user
   // and answers with redacted secrets. Pre-mint the ref equals the control-plane
   // token, which is exactly what the client would fall back to anyway.
-  const runnerTokenRef = { current: options.stigmerToken ?? null };
+  const runnerTokenRef: TokenRef = { current: options.stigmerToken ?? null };
   const baseConfig = mapManagerOptionsToConfig(options, tokenRef, runnerTokenRef);
 
   assertLlmBackendsPreflight(baseConfig.proxyEndpoint);
@@ -582,11 +582,16 @@ export async function createStigmerRunnerManager(
     },
 
     updateToken(token: string | null): void {
-      // Writes the control-plane credential. The coordinator decides whether the
-      // proxy credential follows it: only when no token has been minted (so the
-      // pre-mint lockstep is preserved), never once the runner owns a minted
-      // token. See runner-token-coordinator.ts and the staleness changelogs.
-      // The credential store is the second leg of the pair (it replaced the
+      // Writes the control-plane credential. Every reader follows this one
+      // write: the activity clients, the artifact store and the checkpoint
+      // saver read `tokenRef` per request, the per-turn model clients read it
+      // at build, and nothing holds the value (Config carries the ref alone;
+      // config.ts header). The coordinator decides whether the proxy
+      // credential follows it: only when no token has been minted (so the
+      // pre-mint lockstep is preserved — the in-cluster sandbox case, where
+      // nothing is ever minted), never once the runner owns a minted token.
+      // See runner-token-coordinator.ts and the staleness changelogs. The
+      // credential store is the second leg of the pair (it replaced the
       // process.env.STIGMER_TOKEN write, #508): per-call readers like
       // call-llm and the registry headers resolve the current token there.
       tokenRef.current = token;
@@ -677,10 +682,16 @@ function validateManagerOptions(options: RunnerManagerOptions): void {
   // explicit address nor a token is present, discovery falls back to localhost.
 }
 
+/**
+ * The runtime `Config` for the manager root. The refs are the root's: it
+ * creates them before mapping and writes them on every rotation
+ * (`updateToken`, the token coordinator), so a `Config` never carries a
+ * credential by value (config.ts header).
+ */
 export function mapManagerOptionsToConfig(
   options: RunnerManagerOptions,
-  tokenRef?: { current: string | null },
-  runnerTokenRef?: { current: string | null },
+  tokenRef: TokenRef,
+  runnerTokenRef: TokenRef,
 ): Config {
   const proxyActive = !!options.proxyEndpoint;
 
@@ -697,7 +708,6 @@ export function mapManagerOptionsToConfig(
     temporalAddress: options.temporalAddress ?? "",
     temporalNamespace: options.temporalNamespace ?? "default",
     stigmerBackendEndpoint: normalizeEndpoint(options.stigmerEndpoint),
-    stigmerToken: options.stigmerToken ?? null,
     // Env-only like the env-loaded path (loadConfig): the bridge endpoint
     // is deployment topology, not per-session state.
     mcpBridgeEndpoint: process.env.STIGMER_MCP_BRIDGE_ENDPOINT ?? null,
@@ -791,14 +801,14 @@ async function createAllActivities(config: Config): Promise<WorkerActivities> {
     ...createEvaluateExpressionsActivities(),
     ...createCallHttpActivities(),
     ...createCallGrpcActivities(),
-    ...createCallFunctionActivities(),
+    ...createCallFunctionActivities(config),
     ...createCallLlmActivities(),
     ...createCallAgentActivities(config),
-    ...createCallAgentStatusActivities(),
+    ...createCallAgentStatusActivities(config),
     ...createRunCommandActivities(),
     ...createHydrateWorkflowActivities(config),
-    ...createWorkflowEventActivities(),
-    ...createPromoteTaskOutputActivities(),
+    ...createWorkflowEventActivities(config),
+    ...createPromoteTaskOutputActivities(config),
     ...createAttachSessionActivities(config),
   };
 }

package/src/runner-token-coordinator.ts

@@ -7,9 +7,14 @@
  *     Auth0 token), used for Authorization on control-plane gRPC; and
  *   - the proxy token (x-stigmer-auth), used for Cursor-proxy traffic.
  *
- * On most hosts these are the same token. On cloud the control plane mints a
- * dedicated iss=stigmer proxy token during bootstrap; from that point the proxy
- * token is a *separate* credential with its own TTL, owned and refreshed here.
+ * On most hosts these are the same token. When a manager boots WITHOUT a
+ * pinned Temporal address (the desktop runner), bootstrap discovery dials the
+ * control plane and it mints a dedicated iss=stigmer proxy token; from that
+ * point the proxy token is a *separate* credential with its own TTL, owned and
+ * refreshed here. An in-cluster sandbox pod pins its Temporal address, so its
+ * bootstrap returns before any mint and nothing is ever minted: its proxy
+ * credential stays the control-plane credential, in lockstep, for the pod's
+ * whole life — the claim of a pool member rotates both with one write.
  *
  * This coordinator exists because the proxy token's freshness was the subject of
  * two production fixes (stigmer-cloud _changelog 2026-05-26 and 2026-06-01):