@stigmer/runner 3.21.0 → 3.22.1-dev.20260922095755

package/src/runner.ts

@@ -16,7 +16,7 @@
 import { mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { homedir, tmpdir } from "node:os";
-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";
 import type { WorkerActivities } from "./worker.js";
 import { resolveRunnerBootstrap, refreshRunnerAccessToken } from "./bootstrap.js";
@@ -127,17 +127,19 @@ export interface StigmerRunner {
  * Wire up self-renewal for a static cloud sandbox's control-plane credential
  * (see sandbox-token-renewal.ts for the model). The applied token reaches
  * every consumer through the ONE ref: activity gRPC clients read
- * {@code tokenRef} per request, per-call sites (call-llm, registry-endpoint
- * headers) resolve it through the runner credential store (which replaced
- * the process.env.STIGMER_TOKEN channel, #508), artifact storage resolves
- * the ref per call, and the two Cursor SDK interceptors read the same ref per
- * request as {@code Config.proxyTokenRef} — a static runner has no
+ * {@code tokenRef} per request, the artifact store and the checkpoint saver
+ * read it per request, the per-turn model clients read it at build, per-call
+ * sites (call-llm, registry-endpoint headers) resolve it through the runner
+ * credential store (which replaced the process.env.STIGMER_TOKEN channel,
+ * #508), and the two Cursor SDK interceptors read the same ref per request
+ * as {@code Config.proxyTokenRef} — a static runner has no
  * {@code RunnerTokenCoordinator} minting a separate proxy credential, so its
  * x-stigmer-auth IS this token and one write here rotates it everywhere.
+ * Nothing holds the value: `Config` carries the ref alone (config.ts header).
  */
 async function startStaticSandboxTokenRenewal(
   config: Config,
-  tokenRef: { current: string | null },
+  tokenRef: TokenRef,
 ): Promise<{ stop(): void } | null> {
   const { isRenewableSandboxToken, startSandboxTokenRenewal } = await import(
     "./sandbox-token-renewal.js"
@@ -201,20 +203,19 @@ export async function createStigmerRunner(
   // for in-process embedders.
   captureRunnerSecrets();
 
-  const baseConfig = mapOptionsToConfig(options);
-
-  assertLlmBackendsPreflight(baseConfig.proxyEndpoint);
-
   // The control-plane credential lives in a shared mutable ref (as in manager
   // mode) so the sandbox-token renewal below can rotate it in-process:
   // activity clients read the ref per request instead of pinning the boot
-  // token for the pod's whole life. It is ALSO this root's proxy credential
-  // (Config.proxyTokenRef): a static host provides the proxy token itself and
-  // mints no separate one, so the interceptors read this same ref per request.
-  const tokenRef = { current: baseConfig.stigmerToken };
+  // token for the pod's whole life. This root owns the writable object; the
+  // config carries it read-only (mapOptionsToConfig binds it as both the
+  // control-plane and the proxy credential — see there).
+  const tokenRef: TokenRef = { current: options.stigmerToken ?? null };
   // The runner-class credential the bootstrap below may mint (see there); the
   // ref exists from here so the boot config can carry it.
-  const runnerTokenRef: { current: string | null } = { current: null };
+  const runnerTokenRef: TokenRef = { current: null };
+  const bootConfig = mapOptionsToConfig(options, tokenRef, runnerTokenRef);
+
+  assertLlmBackendsPreflight(bootConfig.proxyEndpoint);
 
   // Boot the harnesses BEFORE resolving Temporal coordinates. Coordinate
   // discovery dials the control plane through connect-node, which snapshots
@@ -225,12 +226,6 @@ export async function createStigmerRunner(
   // coordinates, so `bootConfig` carries none yet. The two modules imported
   // here are connect-free by construction (`harness-adapters.ts`,
   // `harness/registry.ts`; `__tests__/harness-boot-order.test.ts`).
-  const bootConfig: Config = {
-    ...baseConfig,
-    stigmerTokenRef: tokenRef,
-    stigmerRunnerTokenRef: runnerTokenRef,
-    proxyTokenRef: tokenRef,
-  };
   const [{ HARNESS_ADAPTERS }, { adaptersOf, bootHarnesses, shutdownHarnesses }] = await Promise.all([
     import("./harness-adapters.js"),
     import("./harness/registry.js"),
@@ -248,7 +243,7 @@ export async function createStigmerRunner(
     explicitAddress: options.temporalAddress,
     explicitNamespace: options.temporalNamespace,
     token: options.stigmerToken,
-    stigmerEndpoint: baseConfig.stigmerBackendEndpoint,
+    stigmerEndpoint: bootConfig.stigmerBackendEndpoint,
   });
 
   // Adopt the bootstrap-minted embedded_runner credential for gRPC runner-class
@@ -271,7 +266,7 @@ export async function createStigmerRunner(
     reMint: () =>
       refreshRunnerAccessToken({
         token: tokenRef.current,
-        stigmerEndpoint: baseConfig.stigmerBackendEndpoint,
+        stigmerEndpoint: bootConfig.stigmerBackendEndpoint,
       }),
   });
   if (coordinates.runnerAccessToken) {
@@ -397,7 +392,19 @@ function validateOptions(options: StigmerRunnerOptions): void {
   // localhost when no token is present.
 }
 
-export function mapOptionsToConfig(options: StigmerRunnerOptions): Config {
+/**
+ * The runtime `Config` for the static root. The refs are the root's: it
+ * creates them before mapping and writes them on every rotation (the
+ * sandbox-token renewal), so a `Config` never carries a credential by value
+ * (config.ts header). `tokenRef` is bound as BOTH the control-plane and the
+ * proxy credential — a static host provides the proxy token itself and mints
+ * no separate one, so the interceptors read this same ref per request.
+ */
+export function mapOptionsToConfig(
+  options: StigmerRunnerOptions,
+  tokenRef: TokenRef,
+  runnerTokenRef: TokenRef,
+): Config {
   const proxyActive = !!options.proxyEndpoint;
 
   // Execution location is independent of proxy transport. An explicit
@@ -413,7 +420,9 @@ export function mapOptionsToConfig(options: StigmerRunnerOptions): Config {
     temporalAddress: options.temporalAddress ?? "",
     temporalNamespace: options.temporalNamespace ?? "default",
     stigmerBackendEndpoint: normalizeEndpoint(options.stigmerEndpoint),
-    stigmerToken: options.stigmerToken ?? null,
+    stigmerTokenRef: tokenRef,
+    stigmerRunnerTokenRef: runnerTokenRef,
+    proxyTokenRef: tokenRef,
     // 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,
@@ -503,14 +512,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/shared/__tests__/artifact-storage-extended.test.ts

@@ -109,7 +109,7 @@ describe("ProxyArtifactStorage", () => {
   });
 
   it("calls presigned-upload-url endpoint on upload", async () => {
-    const storage = new ProxyArtifactStorage("https://proxy.example.com", "tok");
+    const storage = new ProxyArtifactStorage("https://proxy.example.com", { current: "tok" });
 
     globalThis.fetch = vi.fn()
       .mockResolvedValueOnce({
@@ -129,7 +129,7 @@ describe("ProxyArtifactStorage", () => {
   });
 
   it("throws on presign failure", async () => {
-    const storage = new ProxyArtifactStorage("https://proxy.example.com", "tok");
+    const storage = new ProxyArtifactStorage("https://proxy.example.com", { current: "tok" });
 
     globalThis.fetch = vi.fn().mockResolvedValueOnce({
       ok: false,
@@ -143,7 +143,7 @@ describe("ProxyArtifactStorage", () => {
   });
 
   it("calls presigned-download-url for getDownloadUrl", async () => {
-    const storage = new ProxyArtifactStorage("https://proxy.example.com", "tok");
+    const storage = new ProxyArtifactStorage("https://proxy.example.com", { current: "tok" });
 
     globalThis.fetch = vi.fn().mockResolvedValueOnce({
       ok: true,
@@ -155,7 +155,7 @@ describe("ProxyArtifactStorage", () => {
   });
 
   it("download resolves a presigned URL then fetches the bytes", async () => {
-    const storage = new ProxyArtifactStorage("https://proxy.example.com", "tok");
+    const storage = new ProxyArtifactStorage("https://proxy.example.com", { current: "tok" });
 
     globalThis.fetch = vi.fn()
       .mockResolvedValueOnce({
@@ -172,7 +172,7 @@ describe("ProxyArtifactStorage", () => {
   });
 
   it("download throws with HTTP status and key on a failed fetch", async () => {
-    const storage = new ProxyArtifactStorage("https://proxy.example.com", "tok");
+    const storage = new ProxyArtifactStorage("https://proxy.example.com", { current: "tok" });
 
     globalThis.fetch = vi.fn()
       .mockResolvedValueOnce({
@@ -191,7 +191,7 @@ describe("ProxyArtifactStorage", () => {
   });
 
   it("exists returns true when the object is present (presign + ranged GET)", async () => {
-    const storage = new ProxyArtifactStorage("https://proxy.example.com", "tok");
+    const storage = new ProxyArtifactStorage("https://proxy.example.com", { current: "tok" });
 
     // Two-step probe: presign mints the URL, then a ranged GET hits the object.
     // Presign success alone is NOT existence — the object fetch is authoritative.
@@ -207,7 +207,7 @@ describe("ProxyArtifactStorage", () => {
   });
 
   it("exists returns false when the presign endpoint fails", async () => {
-    const storage = new ProxyArtifactStorage("https://proxy.example.com", "tok");
+    const storage = new ProxyArtifactStorage("https://proxy.example.com", { current: "tok" });
 
     globalThis.fetch = vi.fn(async () => new Response("nope", { status: 404 })) as typeof fetch;
 
@@ -233,7 +233,7 @@ describe("createArtifactStorage", () => {
       localPath: "/var/artifacts",
       localServeUrl: "http://localhost:7235",
       proxyEndpoint: "https://proxy.example.com",
-      proxyAuthToken: "token",
+      proxyAuthToken: { current: "token" },
     });
     expect(storage).toBeInstanceOf(ProxyArtifactStorage);
   });
@@ -244,7 +244,7 @@ describe("createArtifactStorage", () => {
       localPath: "/var/artifacts",
       localServeUrl: "http://localhost:7235",
       proxyEndpoint: null,
-      proxyAuthToken: "token",
+      proxyAuthToken: { current: "token" },
     })).toThrow("STIGMER_PROXY_ENDPOINT");
   });
 

package/src/shared/__tests__/artifact-storage.test.ts

@@ -172,7 +172,7 @@ describe("ProxyArtifactStorage", () => {
   });
 
   it("self-describes its URLs as presigned (time-limited, remotely fetchable — issue #532)", () => {
-    const s = new ProxyArtifactStorage("https://proxy.example.com", "tok");
+    const s = new ProxyArtifactStorage("https://proxy.example.com", { current: "tok" });
     expect(s.downloadUrlKind).toBe("presigned");
   });
 
@@ -195,7 +195,7 @@ describe("ProxyArtifactStorage", () => {
       return new Response("not found", { status: 404 });
     }) as typeof fetch;
 
-    const storage = new ProxyArtifactStorage("https://proxy.example.com", "token-123");
+    const storage = new ProxyArtifactStorage("https://proxy.example.com", { current: "token-123" });
     const key = await storage.upload("artifacts/exec-1/f.txt", Buffer.from("data"), "text/plain");
 
     expect(key).toBe("artifacts/exec-1/f.txt");
@@ -237,7 +237,7 @@ describe("ProxyArtifactStorage", () => {
       "content-type": "text/markdown",
       "host": "test-bucket.localhost:9000",
     });
-    const storage = new ProxyArtifactStorage("https://proxy.example.com", "tok");
+    const storage = new ProxyArtifactStorage("https://proxy.example.com", { current: "tok" });
     await storage.upload("artifacts/exec-1/plan.md", Buffer.from("# Plan"), "text/markdown");
 
     const sent = await headersPromise;
@@ -249,7 +249,7 @@ describe("ProxyArtifactStorage", () => {
       "content-type": "text/markdown",
       "host": "test-bucket.localhost:9000",
     });
-    const storage = new ProxyArtifactStorage("https://proxy.example.com", "tok");
+    const storage = new ProxyArtifactStorage("https://proxy.example.com", { current: "tok" });
     await storage.upload("artifacts/exec-1/plan.md", Buffer.from("# Plan"), "text/markdown");
 
     const sent = await headersPromise;
@@ -262,7 +262,7 @@ describe("ProxyArtifactStorage", () => {
       "content-type": ["text/markdown"],
       "host": ["test-bucket.localhost:9000"],
     });
-    const storage = new ProxyArtifactStorage("https://proxy.example.com", "tok");
+    const storage = new ProxyArtifactStorage("https://proxy.example.com", { current: "tok" });
     await storage.upload("artifacts/exec-1/plan.md", Buffer.from("# Plan"), "text/markdown");
 
     const sent = await headersPromise;
@@ -273,7 +273,7 @@ describe("ProxyArtifactStorage", () => {
     const headersPromise = captureUploadHeaders({
       "host": "test-bucket.localhost:9000",
     });
-    const storage = new ProxyArtifactStorage("https://proxy.example.com", "tok");
+    const storage = new ProxyArtifactStorage("https://proxy.example.com", { current: "tok" });
     await storage.upload("artifacts/exec-1/f.bin", Buffer.from("x"), "application/octet-stream");
 
     const sent = await headersPromise;
@@ -285,7 +285,7 @@ describe("ProxyArtifactStorage", () => {
       new Response("forbidden", { status: 403 }),
     ) as typeof fetch;
 
-    const storage = new ProxyArtifactStorage("https://proxy.example.com", "bad-token");
+    const storage = new ProxyArtifactStorage("https://proxy.example.com", { current: "bad-token" });
     await expect(
       storage.upload("key", Buffer.from("x")),
     ).rejects.toThrow("Failed to get presigned upload URL (HTTP 403)");
@@ -307,7 +307,7 @@ describe("ProxyArtifactStorage", () => {
     // delayFn injected to skip the real ~7.75 s of backoff (#468). The
     // degrade contract under test (budget exhaustion still throws the
     // caller-visible error) is unchanged.
-    const storage = new ProxyArtifactStorage("https://proxy.example.com", "tok", {
+    const storage = new ProxyArtifactStorage("https://proxy.example.com", { current: "tok" }, {
       delayFn: async () => {},
     });
     await expect(
@@ -320,7 +320,7 @@ describe("ProxyArtifactStorage", () => {
       new Response(JSON.stringify({ url: "https://r2.example.com/dl" }), { status: 200 }),
     ) as typeof fetch;
 
-    const storage = new ProxyArtifactStorage("https://proxy.example.com", "tok");
+    const storage = new ProxyArtifactStorage("https://proxy.example.com", { current: "tok" });
     const url = await storage.getDownloadUrl("key");
     expect(url).toBe("https://r2.example.com/dl");
   });
@@ -337,7 +337,7 @@ describe("ProxyArtifactStorage", () => {
       return new Response("not found", { status: 404 });
     }) as typeof fetch;
 
-    const storage = new ProxyArtifactStorage("https://proxy.example.com", "tok");
+    const storage = new ProxyArtifactStorage("https://proxy.example.com", { current: "tok" });
     const got = await storage.download("artifacts/exec-1/f.txt");
     expect(got.toString()).toBe("payload-bytes");
   });
@@ -351,7 +351,7 @@ describe("ProxyArtifactStorage", () => {
       return new Response("gone", { status: 404 });
     }) as typeof fetch;
 
-    const storage = new ProxyArtifactStorage("https://proxy.example.com", "tok");
+    const storage = new ProxyArtifactStorage("https://proxy.example.com", { current: "tok" });
     await expect(storage.download("artifacts/exec-1/missing.txt")).rejects.toThrow(
       /Artifact download failed \(HTTP 404\) for key 'artifacts\/exec-1\/missing\.txt'/,
     );
@@ -372,19 +372,19 @@ describe("ProxyArtifactStorage", () => {
 
   it("exists returns true when the object GET is 200", async () => {
     mockProxyFetch(() => new Response(Buffer.from("x"), { status: 200 }));
-    const storage = new ProxyArtifactStorage("https://proxy.example.com", "tok");
+    const storage = new ProxyArtifactStorage("https://proxy.example.com", { current: "tok" });
     expect(await storage.exists("key")).toBe(true);
   });
 
   it("exists returns true when the object GET is 206 (ranged)", async () => {
     mockProxyFetch(() => new Response(Buffer.from("x"), { status: 206 }));
-    const storage = new ProxyArtifactStorage("https://proxy.example.com", "tok");
+    const storage = new ProxyArtifactStorage("https://proxy.example.com", { current: "tok" });
     expect(await storage.exists("key")).toBe(true);
   });
 
   it("exists returns true on 416 (0-byte object, range unsatisfiable but present)", async () => {
     mockProxyFetch(() => new Response("", { status: 416 }));
-    const storage = new ProxyArtifactStorage("https://proxy.example.com", "tok");
+    const storage = new ProxyArtifactStorage("https://proxy.example.com", { current: "tok" });
     expect(await storage.exists("key")).toBe(true);
   });
 
@@ -393,7 +393,7 @@ describe("ProxyArtifactStorage", () => {
     // only the object fetch reveals it is absent. The old exists() returned true
     // here (presign.ok), which crashed the file-review reconcile on the R2 404.
     mockProxyFetch(() => new Response("<Error><Code>NoSuchKey</Code></Error>", { status: 404 }));
-    const storage = new ProxyArtifactStorage("https://proxy.example.com", "tok");
+    const storage = new ProxyArtifactStorage("https://proxy.example.com", { current: "tok" });
     expect(await storage.exists("key")).toBe(false);
   });
 
@@ -411,7 +411,7 @@ describe("ProxyArtifactStorage", () => {
       });
       return new Response(Buffer.from("x"), { status: 206 });
     }) as typeof fetch;
-    const storage = new ProxyArtifactStorage("https://proxy.example.com", "tok");
+    const storage = new ProxyArtifactStorage("https://proxy.example.com", { current: "tok" });
     await storage.exists("key");
     expect(seen).toEqual([{ url: "https://r2.example.com/obj", range: "bytes=0-0", method: "GET" }]);
   });
@@ -420,7 +420,7 @@ describe("ProxyArtifactStorage", () => {
     globalThis.fetch = vi.fn(async () => {
       throw new Error("network unreachable");
     }) as typeof fetch;
-    const storage = new ProxyArtifactStorage("https://proxy.example.com", "tok");
+    const storage = new ProxyArtifactStorage("https://proxy.example.com", { current: "tok" });
     expect(await storage.exists("key")).toBe(false);
   });
 
@@ -428,7 +428,7 @@ describe("ProxyArtifactStorage", () => {
     mockProxyFetch(() => new Response("boom", { status: 500 }));
     // Persistent 500 exhausts the retry budget; delayFn skips the real
     // backoff (#468). The fault-not-an-answer contract is unchanged.
-    const storage = new ProxyArtifactStorage("https://proxy.example.com", "tok", {
+    const storage = new ProxyArtifactStorage("https://proxy.example.com", { current: "tok" }, {
       delayFn: async () => {},
     });
     await expect(storage.exists("key")).rejects.toThrow(
@@ -450,7 +450,7 @@ describe("ProxyArtifactStorage", () => {
     });
 
     function makeStorage() {
-      return new ProxyArtifactStorage("https://proxy.example.com", "tok", {
+      return new ProxyArtifactStorage("https://proxy.example.com", { current: "tok" }, {
         delayFn: async (ms) => {
           recordedDelays.push(ms);
         },
@@ -554,7 +554,7 @@ describe("ProxyArtifactStorage", () => {
         );
       }) as typeof fetch;
 
-      const storage = new ProxyArtifactStorage("https://proxy.example.com", "tok", {
+      const storage = new ProxyArtifactStorage("https://proxy.example.com", { current: "tok" }, {
         requestTimeoutMs: 20,
         delayFn: async (ms) => {
           recordedDelays.push(ms);
@@ -591,7 +591,7 @@ describe("createArtifactStorage", () => {
       localPath: "/tmp/artifacts",
       localServeUrl: "http://localhost:7235",
       proxyEndpoint: "https://proxy.example.com",
-      proxyAuthToken: "token-123",
+      proxyAuthToken: { current: "token-123" },
     };
     const storage = createArtifactStorage(cfg);
     expect(storage).toBeInstanceOf(ProxyArtifactStorage);
@@ -603,7 +603,7 @@ describe("createArtifactStorage", () => {
       localPath: "/tmp/artifacts",
       localServeUrl: "http://localhost:7235",
       proxyEndpoint: null,
-      proxyAuthToken: "token",
+      proxyAuthToken: { current: "token" },
     };
     expect(() => createArtifactStorage(cfg)).toThrow("STIGMER_PROXY_ENDPOINT");
   });
@@ -640,7 +640,7 @@ describe("loadArtifactStorageConfig", () => {
   const baseConfig = {
     mode: "local" as const,
     proxyEndpoint: null,
-    stigmerToken: null,
+    stigmerTokenRef: { current: null },
     taskQueue: "q",
     temporalAddress: "localhost:7233",
     temporalNamespace: "default",
@@ -681,7 +681,7 @@ describe("loadArtifactStorageConfig", () => {
       mode: "cloud",
       proxyEndpoint: "https://proxy.example.com",
       artifactProxyEndpoint: "https://proxy.example.com",
-      stigmerToken: "tok",
+      stigmerTokenRef: { current: "tok" },
     });
     expect(cfg.type).toBe("proxy");
     expect(cfg.proxyEndpoint).toBe("https://proxy.example.com");
@@ -690,16 +690,19 @@ describe("loadArtifactStorageConfig", () => {
   it("uses proxy in local mode when a proxy endpoint is set (desktop case)", () => {
     // The desktop runner executes locally yet proxies its artifacts: storage
     // follows transport (proxyEndpoint), not execution location (mode).
+    const ref = { current: "tok" };
     const cfg = loadArtifactStorageConfig({
       ...baseConfig,
       mode: "local",
       proxyEndpoint: "https://localhost:9090",
       artifactProxyEndpoint: "https://localhost:9090",
-      stigmerToken: "tok",
+      stigmerTokenRef: ref,
     });
     expect(cfg.type).toBe("proxy");
     expect(cfg.proxyEndpoint).toBe("https://localhost:9090");
-    expect(cfg.proxyAuthToken).toBe("tok");
+    // The runner's ref itself, never a copy of its value: a rotation reaches
+    // the store through this same object.
+    expect(cfg.proxyAuthToken).toBe(ref);
   });
 
   it("presigns against the artifact override when split from the LLM proxy endpoint (stigmer#803)", () => {
@@ -711,7 +714,7 @@ describe("loadArtifactStorageConfig", () => {
       ...baseConfig,
       proxyEndpoint: "https://mock-llm.example.com",
       artifactProxyEndpoint: "https://service.example.com",
-      stigmerToken: "tok",
+      stigmerTokenRef: { current: "tok" },
     });
     expect(cfg.type).toBe("proxy");
     expect(cfg.proxyEndpoint).toBe("https://service.example.com");
@@ -724,7 +727,7 @@ describe("loadArtifactStorageConfig", () => {
     const cfg = loadArtifactStorageConfig({
       ...baseConfig,
       proxyEndpoint: "https://proxy.example.com",
-      stigmerToken: "tok",
+      stigmerTokenRef: { current: "tok" },
     });
     expect(cfg.type).toBe("none");
   });
@@ -734,7 +737,7 @@ describe("loadArtifactStorageConfig", () => {
     const cfg = loadArtifactStorageConfig({
       ...baseConfig,
       proxyEndpoint: "https://proxy.example.com",
-      stigmerToken: "tok",
+      stigmerTokenRef: { current: "tok" },
     });
     expect(cfg.type).toBe("proxy");
   });
@@ -838,7 +841,7 @@ describe("resolveUsableArtifactStorage", () => {
       localPath: "/tmp/artifacts",
       localServeUrl: "http://localhost:7235",
       proxyEndpoint: "https://proxy.example.com",
-      proxyAuthToken: "token-123",
+      proxyAuthToken: { current: "token-123" },
     };
 
     const storage = await resolveUsableArtifactStorage(cfg, ctx);

package/src/shared/__tests__/extract-structured-output.test.ts

@@ -24,7 +24,7 @@ const SCHEMA = { type: "object", properties: { answer: { type: "string" } } };
 function makeConfig(overrides: Partial<Config> = {}): Config {
   return {
     proxyEndpoint: null,
-    stigmerToken: null,
+    stigmerTokenRef: { current: null },
     ...overrides,
   } as Config;
 }
@@ -78,7 +78,7 @@ describe("extractStructuredOutput", () => {
 
     const result = await extractStructuredOutput(
       "text", SCHEMA,
-      makeConfig({ proxyEndpoint: "https://api.stigmer.ai", stigmerToken: "tok" }),
+      makeConfig({ proxyEndpoint: "https://api.stigmer.ai", stigmerTokenRef: { current: "tok" } }),
       "gpt-4.1",
     );
 

package/src/shared/artifact-storage.ts

@@ -24,7 +24,7 @@
 import { mkdir, writeFile, readFile, access, rm } from "node:fs/promises";
 import { dirname, join, resolve, sep } from "node:path";
 import { homedir } from "node:os";
-import type { Config } from "../config.js";
+import type { Config, TokenRef } from "../config.js";
 import type { RetryOptions } from "./grpc-retry.js";
 import { fetchWithRetry, type FetchRetryPolicy } from "./http-retry.js";
 
@@ -212,9 +212,7 @@ export class ProxyArtifactStorage implements ArtifactStorage {
    * life — a captured string would silently 401 after the first rotation.
    */
   private get authToken(): string {
-    return typeof this.authTokenSource === "string"
-      ? this.authTokenSource
-      : (this.authTokenSource.current ?? "");
+    return this.authTokenSource.current ?? "";
   }
 
   async upload(key: string, content: Buffer, contentType?: string): Promise<string> {
@@ -343,10 +341,12 @@ export class ProxyArtifactStorage implements ArtifactStorage {
 // ── Factory ──────────────────────────────────────────────────────────
 
 /**
- * The proxy credential, either fixed (a caller-supplied string) or live (a
- * shared mutable ref, read per call — the sandbox token-renewal posture).
+ * The proxy credential: the runner's shared ref, read per call (the
+ * sandbox token-renewal posture; config.ts header). Never a string — a
+ * captured value would present the boot credential after the first
+ * rotation.
  */
-export type ProxyAuthTokenSource = string | { readonly current: string | null };
+export type ProxyAuthTokenSource = Readonly<TokenRef>;
 
 export interface ArtifactStorageConfig {
   readonly type: ArtifactStorageType;
@@ -392,11 +392,9 @@ export function loadArtifactStorageConfig(config: Config): ArtifactStorageConfig
     localPath: process.env.LOCAL_ARTIFACT_PATH ?? defaultLocalArtifactPath(),
     localServeUrl: process.env.LOCAL_ARTIFACT_SERVE_URL ?? "http://localhost:7235",
     proxyEndpoint: type === "proxy" ? (config.artifactProxyEndpoint ?? null) : null,
-    // Prefer the live ref: renewal rotates the token in place and uploads
-    // must present the current credential, not the boot one.
-    proxyAuthToken: type === "proxy"
-      ? (config.stigmerTokenRef ?? config.stigmerToken ?? null)
-      : null,
+    // The live ref: renewal rotates the token in place and uploads must
+    // present the current credential, not the boot one.
+    proxyAuthToken: type === "proxy" ? config.stigmerTokenRef : null,
   };
 }
 
@@ -415,13 +413,10 @@ export function createArtifactStorage(cfg: ArtifactStorageConfig): ArtifactStora
         "Proxy artifact storage requires STIGMER_ARTIFACT_PROXY_ENDPOINT or STIGMER_PROXY_ENDPOINT",
       );
     }
-    const tokenAtBoot = typeof cfg.proxyAuthToken === "string"
-      ? cfg.proxyAuthToken
-      : cfg.proxyAuthToken?.current;
-    if (!tokenAtBoot) {
+    if (!cfg.proxyAuthToken?.current) {
       throw new Error("Proxy artifact storage requires STIGMER_TOKEN");
     }
-    return new ProxyArtifactStorage(cfg.proxyEndpoint, cfg.proxyAuthToken!);
+    return new ProxyArtifactStorage(cfg.proxyEndpoint, cfg.proxyAuthToken);
   }
 
   return new LocalArtifactStorage(cfg.localPath, cfg.localServeUrl);

package/src/shared/checkpointer/__tests__/factory.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect, afterEach } from "vitest";
+import { describe, it, expect, afterEach, vi } from "vitest";
 import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -39,14 +39,14 @@ describe("createCheckpointer", () => {
     const saver = await createCheckpointer({
       type: "http",
       proxyEndpoint: "https://proxy.test",
-      authToken: "tok-123",
+      authToken: { current: "tok-123" },
     });
     expect(saver).toBeInstanceOf(HttpCheckpointSaver);
   });
 
   it("throws CheckpointerCreationError when http is missing proxyEndpoint", async () => {
     await expect(
-      createCheckpointer({ type: "http", authToken: "tok" }),
+      createCheckpointer({ type: "http", authToken: { current: "tok" } }),
     ).rejects.toThrow(CheckpointerCreationError);
   });
 
@@ -56,6 +56,26 @@ describe("createCheckpointer", () => {
     ).rejects.toThrow(CheckpointerCreationError);
   });
 
+  it("throws CheckpointerCreationError when the http credential ref holds nothing at open", async () => {
+    await expect(
+      createCheckpointer({ type: "http", proxyEndpoint: "https://proxy.test", authToken: { current: null } }),
+    ).rejects.toThrow(CheckpointerCreationError);
+  });
+
+  it("hands the http saver the caller's ref itself, so a rotation after open reaches the saver's next request", async () => {
+    const ref = { current: "boot-credential" };
+    const saver = await createCheckpointer({ type: "http", proxyEndpoint: "https://proxy.test", authToken: ref });
+    const fetchSpy = vi.fn().mockResolvedValue({ status: 404, ok: false });
+    vi.stubGlobal("fetch", fetchSpy);
+    try {
+      ref.current = "session-credential";
+      await saver.getTuple({ configurable: { thread_id: "t", checkpoint_ns: "" } });
+      expect(fetchSpy.mock.calls[0][1].headers.Authorization).toBe("Bearer session-credential");
+    } finally {
+      vi.unstubAllGlobals();
+    }
+  });
+
   it("error includes the checkpointer type", async () => {
     try {
       await createCheckpointer({ type: "http" });