@stigmer/runner 3.12.3 → 3.12.4

package/src/activities/execute-cursor/agent-session-cache.ts

@@ -0,0 +1,229 @@
+/**
+ * Session-keyed Cursor agent cache — keeps the SDK executor (and its stdio
+ * MCP server processes) alive across turns of the SAME session (#215).
+ *
+ * Why this exists: the SDK's local executor cache is refcounted and keyed
+ * by the full acquisition config (workingDirectory, hashed apiKey,
+ * settingSources, mcpServers, customSubagents). `agent.close()` releases
+ * the agent's lease; at refcount zero the executor is DISPOSED and every
+ * stdio MCP server is killed. The activity used to close on every terminal
+ * path, so each turn re-acquired the executor and re-spawned every MCP
+ * server inside `agent.send()` — a measured 2.2–3.2s per-turn tax
+ * (`turn_first_event`'s `send_returned` segment).
+ *
+ * Ownership model — exclusive checkout, explicit lifetime:
+ * - A finishing turn PARKS its healthy agent here (`cacheSessionAgent`);
+ *   the next activity for the session CHECKS IT OUT (`takeCachedAgent`),
+ *   removing it from the cache, so two concurrent activities can never
+ *   share one Agent handle — the loser of the race resolves its own.
+ * - The cached agent is reused only when the acquisition FINGERPRINT
+ *   matches. Any config drift (rotated credential, edited MCP servers,
+ *   model change, different workspace) closes the parked agent and forces
+ *   a fresh resolve — correctness by construction: a reused executor would
+ *   otherwise keep serving the OLD config.
+ * - Failure paths never park: a suspect agent is closed where it failed
+ *   (the pre-existing close sites), and `evictSessionAgent` clears any
+ *   parked entry when a session's state is replaced out from under it.
+ * - Idle TTL + LRU cap bound memory on multi-session hosts (the desktop
+ *   runner-manager hosts many sessions per process; a cloud sandbox is
+ *   session-pinned and holds at most one entry). Worker shutdown closes
+ *   everything (`closeAllCachedAgents`).
+ */
+
+import { createHash } from "node:crypto";
+
+/** The slice of SDKAgent this cache needs — close() releases the executor lease. */
+export interface CacheableAgent {
+  readonly agentId: string;
+  close(): void;
+}
+
+interface CachedSessionAgent {
+  readonly agent: CacheableAgent;
+  readonly fingerprint: string;
+  readonly evictTimer: NodeJS.Timeout;
+  /** Insertion-order tiebreaker for the LRU cap. */
+  readonly parkedAt: number;
+}
+
+/**
+ * Default idle lifetime for a parked agent. Long enough to cover human
+ * think-time between turns and approval round-trips; short enough that an
+ * abandoned session does not pin MCP subprocesses for hours.
+ */
+const DEFAULT_IDLE_TTL_MS = 30 * 60 * 1000;
+
+/**
+ * Ceiling on concurrently parked agents (each holds an executor + its MCP
+ * subprocesses). Cloud sandboxes never approach it (one session per pod);
+ * it protects long-lived desktop runner-managers.
+ */
+const MAX_PARKED_AGENTS = 32;
+
+function resolveIdleTtlMs(): number {
+  const parsed = Number.parseInt(process.env.STIGMER_CURSOR_AGENT_CACHE_TTL_MS ?? "", 10);
+  return parsed > 0 ? parsed : DEFAULT_IDLE_TTL_MS;
+}
+
+const parkedAgents = new Map<string, CachedSessionAgent>();
+
+function closeQuietly(agent: CacheableAgent): void {
+  try {
+    agent.close();
+  } catch {
+    /* best effort — the lease release is advisory on an already-dead agent */
+  }
+}
+
+/**
+ * Fingerprint of everything that determines whether a parked agent can
+ * serve the next turn as-is: the SDK executor cache key inputs PLUS the
+ * per-agent options resume() re-supplies (model selection, sub-agents).
+ * The API key contributes only as a hash — the fingerprint must never be
+ * a secret-bearing value (it appears in no logs, but defense in depth).
+ */
+export function computeAgentFingerprint(createOptions: Record<string, unknown>): string {
+  const { apiKey, ...rest } = createOptions;
+  const material = {
+    ...rest,
+    apiKeyHash:
+      typeof apiKey === "string" && apiKey.length > 0
+        ? createHash("sha256").update(apiKey).digest("hex")
+        : undefined,
+  };
+  return createHash("sha256").update(stableStringify(material)).digest("hex");
+}
+
+/** Deterministic JSON: object keys sorted recursively (the SDK's own idiom). */
+function stableStringify(value: unknown): string {
+  return JSON.stringify(sortKeys(value));
+}
+
+function sortKeys(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(sortKeys);
+  if (value !== null && typeof value === "object" && value.constructor === Object) {
+    return Object.fromEntries(
+      Object.keys(value as Record<string, unknown>)
+        .sort()
+        .map((k) => [k, sortKeys((value as Record<string, unknown>)[k])]),
+    );
+  }
+  return value;
+}
+
+/**
+ * Exclusive checkout: returns the parked agent for the session and removes
+ * it from the cache, or undefined when there is nothing reusable.
+ *
+ * A parked agent is reusable only when BOTH hold:
+ * - `fingerprint` matches (config identical to what the agent was built with);
+ * - `expectedAgentId`, when non-empty, matches the parked agent (the
+ *   session's harnessStateId is the source of truth — a recovery in another
+ *   activity may have replaced the agent since this one was parked).
+ *
+ * A mismatch on either closes the parked agent: it can never serve this
+ * session again, and holding it would only pin dead MCP processes.
+ */
+export function takeCachedAgent(
+  sessionId: string,
+  fingerprint: string,
+  expectedAgentId: string,
+): CacheableAgent | undefined {
+  const entry = parkedAgents.get(sessionId);
+  if (!entry) return undefined;
+
+  parkedAgents.delete(sessionId);
+  clearTimeout(entry.evictTimer);
+
+  const agentMatches = expectedAgentId === "" || entry.agent.agentId === expectedAgentId;
+  if (entry.fingerprint !== fingerprint || !agentMatches) {
+    console.log(
+      `agent-session-cache: parked agent for session=${sessionId} not reusable ` +
+      `(fingerprintMatch=${entry.fingerprint === fingerprint}, agentIdMatch=${agentMatches}) — closing`,
+    );
+    closeQuietly(entry.agent);
+    return undefined;
+  }
+
+  return entry.agent;
+}
+
+/**
+ * Parks a healthy agent for the session's next turn. Replaces (and closes)
+ * any agent already parked for the session; evicts the oldest entry when
+ * the cap is reached.
+ */
+export function cacheSessionAgent(
+  sessionId: string,
+  agent: CacheableAgent,
+  fingerprint: string,
+): void {
+  if (!sessionId) {
+    // No stable key to reuse by — release the lease as before the cache.
+    closeQuietly(agent);
+    return;
+  }
+
+  const displaced = parkedAgents.get(sessionId);
+  if (displaced) {
+    clearTimeout(displaced.evictTimer);
+    closeQuietly(displaced.agent);
+  }
+
+  if (parkedAgents.size >= MAX_PARKED_AGENTS) {
+    let oldestKey: string | undefined;
+    let oldestAt = Infinity;
+    for (const [key, entry] of parkedAgents) {
+      if (entry.parkedAt < oldestAt) {
+        oldestAt = entry.parkedAt;
+        oldestKey = key;
+      }
+    }
+    if (oldestKey !== undefined) evictSessionAgent(oldestKey);
+  }
+
+  const ttlMs = resolveIdleTtlMs();
+  const evictTimer = setTimeout(() => evictSessionAgent(sessionId), ttlMs);
+  // Never keep the process alive just to evict an idle agent.
+  evictTimer.unref?.();
+
+  parkedAgents.set(sessionId, {
+    agent,
+    fingerprint,
+    evictTimer,
+    parkedAt: Date.now(),
+  });
+}
+
+/** Closes and forgets the parked agent for a session, if any. */
+export function evictSessionAgent(sessionId: string): void {
+  const entry = parkedAgents.get(sessionId);
+  if (!entry) return;
+  parkedAgents.delete(sessionId);
+  clearTimeout(entry.evictTimer);
+  closeQuietly(entry.agent);
+  console.log(`agent-session-cache: evicted parked agent for session=${sessionId}`);
+}
+
+/** Worker shutdown: release every parked lease so executors dispose cleanly. */
+export function closeAllCachedAgents(): void {
+  for (const [sessionId, entry] of parkedAgents) {
+    clearTimeout(entry.evictTimer);
+    closeQuietly(entry.agent);
+    console.log(`agent-session-cache: closed parked agent for session=${sessionId} (shutdown)`);
+  }
+  parkedAgents.clear();
+}
+
+/** Test seam. */
+export function _resetAgentSessionCacheForTests(): void {
+  for (const entry of parkedAgents.values()) {
+    clearTimeout(entry.evictTimer);
+  }
+  parkedAgents.clear();
+}
+
+/** Test seam. */
+export function _parkedAgentCountForTests(): number {
+  return parkedAgents.size;
+}

package/src/activities/execute-cursor/index.ts

@@ -41,6 +41,7 @@ import type { Config } from "../../config.js";
 import { StigmerClient } from "../../client/stigmer-client.js";
 import { describeExecutionError } from "../../shared/model-error.js";
 import { resolveAgentWithTransportRecovery } from "./session-lifecycle.js";
+import { cacheSessionAgent, computeAgentFingerprint, takeCachedAgent } from "./agent-session-cache.js";
 import type { AgentResolution, AgentResolutionReason, CreateAgentOptions, CreateCloudAgentOptions } from "./session-lifecycle.js";
 import { CursorMode } from "@stigmer/protos/ai/stigmer/agentic/session/v1/enum_pb";
 import { determineCursorMode, isCloudMode } from "./cursor-mode.js";
@@ -134,7 +135,8 @@ import { statusProtoWriter } from "../../shared/execution-status-writer.js";
 import { setInterceptorExecutionId, runWithExecutionContext } from "./fetch-interceptor.js";
 import { closeProxySessions } from "./http2-interceptor.js";
 import { resolveModelId, ensureLoaded as ensurePricingLoaded } from "./model-pricing.js";
-import { resolveEffectiveServiceTier, resolveServiceTierParams } from "./service-tier.js";
+import { resolveEffectiveServiceTier } from "../../shared/service-tier.js";
+import { resolveServiceTierParams } from "./service-tier.js";
 import { UsageAccumulator } from "./usage-accumulator.js";
 import { StreamingUsageSummarySchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/usage_pb";
 import { activityStarted, activityFinished } from "../../idle-watchdog.js";
@@ -1052,21 +1054,52 @@ async function executeCursorInner(
     // is the largest user-visible setup segment; this split keeps its
     // historical meaning — the SDK call was already 98%+ of it).
     setupTiming.mark("prepare_agent");
-    let resolution: AgentResolution = await resolveAgentWithTransportRecovery({
-      harnessStateId: threadId,
-      createOptions,
-      mode: agentMode,
-      timeoutMs: config.agentResolveTimeoutMs,
-      buildTimeoutMessage: (finalAttempt) =>
-        `Cursor agent ${threadId ? "resume" : "create"} timed out after ${resolveTimeoutSeconds}s ` +
-        `(${config.proxyEndpoint ? `via proxy ${config.proxyEndpoint}` : "direct Cursor API connection"}). ` +
-        `The transport connection is likely dead. ` +
-        (finalAttempt
-          ? `An automatic retry on a fresh transport connection also timed out. ` +
-            `Retry the message later; if this persists, check proxy and network health.`
-          : `Resetting the transport and retrying automatically.`),
-      resetTransport: closeProxySessions,
-    });
+
+    // Phase 8a: Reuse the previous turn's agent when this session parked one
+    // (#215). A checkout hit skips Agent.resume() AND — the real win — keeps
+    // the SDK executor lease alive, so agent.send() below re-acquires the
+    // warm executor instead of re-spawning every stdio MCP server (the
+    // measured 2.2–3.2s `send_returned` tax). The fingerprint covers the
+    // full acquisition config, so any drift (rotated credential, edited MCP
+    // servers, model change) falls through to a fresh resolve.
+    const agentFingerprint = computeAgentFingerprint(
+      createOptions as unknown as Record<string, unknown>,
+    );
+    const parkedAgent = takeCachedAgent(sessionId, agentFingerprint, threadId ?? "");
+    let resolution: AgentResolution;
+    if (parkedAgent) {
+      console.log(
+        `ExecuteCursor reusing parked session agent: execution=${executionId}, ` +
+        `session=${sessionId}, agentId=${parkedAgent.agentId}`,
+      );
+      resolution = {
+        agent: parkedAgent as AgentResolution["agent"],
+        agentId: parkedAgent.agentId,
+        isNew: false,
+        resumed: true,
+        mode: agentMode,
+        // The parked handle IS the live conversation — every consumer of
+        // "resumed_successfully" (prompt selection, poisoned-handle
+        // recovery eligibility) wants exactly those semantics.
+        reason: "resumed_successfully",
+      };
+    } else {
+      resolution = await resolveAgentWithTransportRecovery({
+        harnessStateId: threadId,
+        createOptions,
+        mode: agentMode,
+        timeoutMs: config.agentResolveTimeoutMs,
+        buildTimeoutMessage: (finalAttempt) =>
+          `Cursor agent ${threadId ? "resume" : "create"} timed out after ${resolveTimeoutSeconds}s ` +
+          `(${config.proxyEndpoint ? `via proxy ${config.proxyEndpoint}` : "direct Cursor API connection"}). ` +
+          `The transport connection is likely dead. ` +
+          (finalAttempt
+            ? `An automatic retry on a fresh transport connection also timed out. ` +
+              `Retry the message later; if this persists, check proxy and network health.`
+            : `Resetting the transport and retrying automatically.`),
+        resetTransport: closeProxySessions,
+      });
+    }
 
     console.log(
       `ExecuteCursor agent resolved: execution=${executionId}, ` +
@@ -1462,7 +1495,9 @@ async function executeCursorInner(
           timestamp: utcTimestamp(),
         }));
         await persist(status);
-        try { resolution.agent.close(); } catch { /* best effort */ }
+        // Clean terminal: the conversation continues on the next message,
+        // so park the healthy agent for that turn (#215).
+        cacheSessionAgent(sessionId ?? "", resolution.agent, agentFingerprint);
         console.warn(
           `ExecuteCursor terminated (cost cap): execution=${executionId}, ` +
           `estimatedCostUsd=${estimated.toFixed(4)}, maxCostUsd=${maxCostUsd.toFixed(2)}`,
@@ -1527,7 +1562,8 @@ async function executeCursorInner(
           timestamp: utcTimestamp(),
         }));
         await persist(status);
-        try { resolution.agent.close(); } catch { /* best effort */ }
+        // Clean terminal — park for the session's next turn (#215).
+        cacheSessionAgent(sessionId ?? "", resolution.agent, agentFingerprint);
         console.log(`ExecuteCursor completed (platform stop): execution=${executionId}`);
         return { kind: "return" };
       }
@@ -1573,6 +1609,12 @@ async function executeCursorInner(
     const enterApprovalPause = async (boundary: TurnBoundaryResult) => {
       status.phase = ExecutionPhase.EXECUTION_WAITING_FOR_APPROVAL;
       await persist(status);
+      // The approval-resume reinvocation is the cache's best case: park the
+      // agent so the resumed turn skips the full executor rebuild (#215).
+      // (This path previously dropped the handle without close() — the
+      // lease leaked; parking makes the lifetime explicit.) An absent
+      // sessionId falls back to "" — the cache closes the lease immediately.
+      cacheSessionAgent(sessionId ?? "", resolution.agent, agentFingerprint);
       console.log(
         `ExecuteCursor returning WAITING_FOR_APPROVAL: ${boundary.deniedToolCallCount} gated tool(s), ` +
         `${boundary.capturedChangeCount} file card(s) pending`,
@@ -2088,8 +2130,12 @@ async function executeCursorInner(
         (status.error ? `, error=${status.error}` : ""),
     );
 
-    // Release SDK executor lease to prevent cache buildup across workflow tasks
-    try { resolution.agent.close(); } catch { /* best effort */ }
+    // Park the agent (with its executor lease) for the session's next turn
+    // instead of closing it — the idle TTL / shutdown hooks in
+    // agent-session-cache own the eventual release, so cache buildup across
+    // sessions stays bounded while turns of ONE session stop paying the
+    // executor + MCP re-spawn tax (#215).
+    cacheSessionAgent(sessionId ?? "", resolution.agent, agentFingerprint);
 
     const slim = slimStatus(status) as Record<string, unknown>;
     if (finalText !== undefined) {

package/src/activities/execute-cursor/service-tier.ts

@@ -20,19 +20,17 @@
  * rides the same proxy fetch-interceptor as every other SDK call, so it
  * works identically in proxy and direct modes.
  *
- * UNSPECIFIED resolves to STANDARD here and ONLY here — every upstream
- * layer preserves the caller's raw enum so "user chose standard" stays
- * distinguishable from "platform default" all the way to the ledger.
+ * The harness-neutral halves — the tier enum semantics, and the single
+ * UNSPECIFIED→STANDARD resolution point — live in
+ * `shared/service-tier.ts` since #361 extended tiers to the native
+ * harness; this module keeps only the Cursor-catalog translation.
  */
 
 import { Cursor } from "@cursor/sdk";
 import type { ModelListItem, ModelParameterValue } from "@cursor/sdk";
 import { ServiceTier } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 
-/**
- * The effective tier after platform-default resolution: never UNSPECIFIED.
- */
-export type EffectiveServiceTier = ServiceTier.STANDARD | ServiceTier.FAST;
+import { serviceTierLabel, type EffectiveServiceTier } from "../../shared/service-tier.js";
 
 /**
  * Catalog ids that mean "Cursor picks the model" (Auto). Auto's single
@@ -72,28 +70,6 @@ export function resetCatalogCacheForTests(): void {
   inflightCatalogFetch = null;
 }
 
-/**
- * Resolve the configured tier to its effective value. The single place in
- * the platform where UNSPECIFIED becomes STANDARD.
- */
-export function resolveEffectiveServiceTier(
-  configured: ServiceTier | undefined,
-): EffectiveServiceTier {
-  return configured === ServiceTier.FAST ? ServiceTier.FAST : ServiceTier.STANDARD;
-}
-
-/** Human-readable tier label for logs and error messages. */
-export function serviceTierLabel(tier: ServiceTier): string {
-  switch (tier) {
-    case ServiceTier.FAST:
-      return "fast";
-    case ServiceTier.STANDARD:
-      return "standard";
-    default:
-      return "unspecified";
-  }
-}
-
 async function listCatalogModels(apiKey: string): Promise<readonly ModelListItem[]> {
   const now = Date.now();
   if (catalogCache && catalogCache.apiKey === apiKey && catalogCache.expiresAt > now) {

package/src/activities/execute-cursor/skill-resolver.ts

@@ -232,7 +232,7 @@ async function writeSkillMount(
     for (const entry of entries) {
       const filePath = join(skillDir, entry.path);
       await mkdir(dirname(filePath), { recursive: true });
-      await writeFile(filePath, entry.content, "utf-8");
+      await writeFile(filePath, entry.content);
     }
   }
 

package/src/activities/execute-deep-agent/setup.ts

@@ -72,6 +72,7 @@ import { getRunnerHitlMasterSecret } from "../../shared/fingerprint-secret.js";
 import { getModelPricing, ensureLoaded as ensurePricingLoaded } from "../../shared/model-pricing.js";
 import { getDefaultModel, getModelVisionCapability } from "../../shared/model-registry.js";
 import { buildChatModel } from "../../shared/model-client.js";
+import { resolveEffectiveServiceTier } from "../../shared/service-tier.js";
 import {
   loadArtifactStorageConfig,
   resolveUsableArtifactStorage,
@@ -580,11 +581,22 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
     // The operator's STIGMER_LLM_REQUEST_TIMEOUT_MS bound is applied inside
     // buildChatModel (#468) — the sub-agent modelFactory below silently
     // dropped it when each caller parsed the env itself.
+    //
+    // The service tier resolves ONCE here (UNSPECIFIED → explicit
+    // STANDARD, shared/service-tier.ts) and rides every model this
+    // execution constructs — the primary below AND the sub-agent factory —
+    // so the provider account's default can never pick the price of any
+    // turn (#361, the native half of #357's contract). Sub-agents inherit
+    // it because the tier is an attribute of the EXECUTION's bill, and
+    // sub-agent calls land on the same ledger.
+    const serviceTier = resolveEffectiveServiceTier(
+      execution.spec!.executionConfig?.serviceTier);
     const { model } = await buildChatModel({
       modelName,
       proxyEndpoint: config.proxyEndpoint ?? undefined,
       stigmerToken: config.stigmerToken ?? undefined,
       headerScope: { executionId },
+      serviceTier,
     });
     timing.mark("build_model");
 
@@ -776,6 +788,9 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
             proxyEndpoint: config.proxyEndpoint ?? undefined,
             stigmerToken: config.stigmerToken ?? undefined,
             headerScope: { executionId },
+            // The execution's tier, inherited: sub-agent calls bill to the
+            // same execution (#361 — see the Step 9 resolution comment).
+            serviceTier,
           })).model,
         // Presence of shellEnv is the shell-capability switch for sub-agent
         // backends too (undefined in plan mode; see buildShellEnv above).

package/src/activities/execute-deep-agent/shell-env.ts

@@ -1,19 +1,22 @@
 /**
  * Shell environment for the native harness `execute` tool.
  *
- * Per-execution snapshot: runner-manager rotates `STIGMER_TOKEN` in
- * `process.env` at runtime, so this must run inside setup for each execution,
- * never once at process start.
+ * Since #508's boot capture, runner secrets never LIVE in `process.env`, so
+ * the denylist below is defense-in-depth: it keeps this surface safe even if
+ * something re-plants a secret in the environment after boot (a test, an
+ * embedder, a future regression). Still built per execution — the snapshot
+ * must reflect the env as it is now, not at process start.
  */
 
-import { RUNNER_CREDENTIAL_ENV_KEYS } from "../../shared/runner-credential-keys.js";
+import { RUNNER_SECRET_ENV_KEYS } from "../../shared/runner-credential-keys.js";
 
 /**
  * Runner-internal keys that must never reach agent shell commands: every
- * credential the runner holds for its own outbound calls (issue #385). The
- * names — and the rule for adding one — live in runner-credential-keys.ts.
+ * credential the runner holds for its own outbound calls (issue #385) plus
+ * the runner's encryption keys (issue #508). The names — and the rules for
+ * adding one — live in runner-credential-keys.ts.
  */
-export const SHELL_ENV_DENYLIST: readonly string[] = RUNNER_CREDENTIAL_ENV_KEYS;
+export const SHELL_ENV_DENYLIST: readonly string[] = RUNNER_SECRET_ENV_KEYS;
 
 /**
  * Build the environment map passed to deepagents' LocalShellBackend.

package/src/config.ts

@@ -53,6 +53,7 @@ export const DEFAULT_CURSOR_AGENT_RESOLVE_TIMEOUT_MS = 120_000;
 // three construction sites — mirrors DEFAULT_CURSOR_STREAM_STALL_TIMEOUT_MS).
 export { DEFAULT_WORKSPACE_LOCK_TIMEOUT_MS } from "./shared/workspace/workspace-lock.js";
 import { DEFAULT_WORKSPACE_LOCK_TIMEOUT_MS } from "./shared/workspace/workspace-lock.js";
+import { getRunnerSecret } from "./shared/runner-credential-store.js";
 
 export interface Config {
   readonly taskQueue: string;
@@ -158,9 +159,13 @@ export function loadConfig(): Config {
       : requireEnv("STIGMER_BACKEND_ENDPOINT"),
   );
 
-  const stigmerToken = (mode === "cloud" || proxyActive)
-    ? requireEnv("STIGMER_TOKEN")
-    : (process.env.STIGMER_TOKEN ?? null);
+  // Secrets resolve through the credential store, not process.env — the
+  // boot capture has already moved them out of the environment (#508).
+  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 mcpBridgeEndpoint = process.env.STIGMER_MCP_BRIDGE_ENDPOINT ?? null;
 
@@ -170,8 +175,8 @@ export function loadConfig(): Config {
   // the SDK's authorization header (Cursor access token) passes through to
   // api2.cursor.sh unchanged.
   const cursorApiKey = proxyActive
-    ? (process.env.CURSOR_API_KEY ?? stigmerToken ?? "proxy-managed")
-    : (process.env.CURSOR_API_KEY ?? "");
+    ? (getRunnerSecret("CURSOR_API_KEY") ?? stigmerToken ?? "proxy-managed")
+    : (getRunnerSecret("CURSOR_API_KEY") ?? "");
 
   const workspaceRootDir = resolveWorkspaceRootDir();
 

package/src/encryption/config.ts

@@ -25,6 +25,8 @@
  * on the next runner boot — there is no live re-key.
  */
 
+import { getRunnerSecret } from "../shared/runner-credential-store.js";
+
 export interface EncryptionKey {
   readonly keyId: string;
   /** 32-byte AES-256 key. */
@@ -75,14 +77,18 @@ const AES_256_KEY_BYTES = 32;
 export function loadPayloadEncryptionConfig(
   bootstrap?: BootstrapKeyMaterial,
 ): PayloadEncryptionConfig | undefined {
-  const rawKey = process.env[KEY_ENV];
+  // Key VALUES resolve through the credential store (the #508 boot capture
+  // moves them out of process.env — agent shells must not read them); the
+  // *_KEY_ID companions are rotation bookkeeping, not secrets, and stay
+  // plain env reads.
+  const rawKey = getRunnerSecret(KEY_ENV);
   if (rawKey) {
     const primary: EncryptionKey = {
       keyId: requireKeyId(KEY_ID_ENV),
       key: parseKey(rawKey, KEY_ENV),
     };
 
-    const rawSecondary = process.env[SECONDARY_KEY_ENV];
+    const rawSecondary = getRunnerSecret(SECONDARY_KEY_ENV);
     const secondary: EncryptionKey | undefined = rawSecondary
       ? {
           keyId: requireKeyId(SECONDARY_KEY_ID_ENV),

package/src/main.ts

@@ -32,6 +32,10 @@ import { createInterface } from "node:readline";
 import { preflightNodeRuntime } from "./preflight.js";
 import { markBoot, emitRunnerBootTiming } from "./shared/cold-start-timing.js";
 import { loadConfig } from "./config.js";
+import {
+  captureRunnerSecrets,
+  getRunnerSecret,
+} from "./shared/runner-credential-store.js";
 import { initTracing, initMetrics } from "./otel.js";
 import { createStigmerRunner } from "./runner.js";
 import { createStigmerRunnerManager } from "./runner-manager.js";
@@ -214,11 +218,12 @@ async function runPoolMode(
   });
 
   // Sandbox credential self-renewal (see sandbox-token-renewal.ts). Watches
-  // the env var because manager.updateToken keeps it in lockstep with the
-  // manager's internal ref: a blank member's pool_sandbox token parks the
-  // loop, the claim's updateToken swaps in a renewable session token, and
-  // from then on renewal applies fresh tokens back through the same
-  // updateToken (which also cascades to the proxy-credential coordinator).
+  // the credential store because manager.updateToken keeps it in lockstep
+  // with the manager's internal ref: a blank member's pool_sandbox token
+  // parks the loop, the claim's updateToken swaps in a renewable session
+  // token, and from then on renewal applies fresh tokens back through the
+  // same updateToken (which also cascades to the proxy-credential
+  // coordinator).
   const { startSandboxTokenRenewal } = await import("./sandbox-token-renewal.js");
   const { StigmerClient } = await import("./client/stigmer-client.js");
   const renewalClient = new StigmerClient({
@@ -226,7 +231,7 @@ async function runPoolMode(
     token: null,
   });
   const tokenRenewal = startSandboxTokenRenewal({
-    getToken: () => process.env.STIGMER_TOKEN ?? null,
+    getToken: () => getRunnerSecret("STIGMER_TOKEN") ?? null,
     renew: (currentToken) =>
       renewalClient.getRunnerScopedToken({ renewal: true }, currentToken),
     applyToken: (token) => manager.updateToken(token),
@@ -449,6 +454,11 @@ async function main(): Promise<void> {
 
   checkBuildFreshness();
 
+  // Take custody of runner secrets before the config load reads them (#508).
+  // The factories capture too (they are the library boot doors); doing it
+  // here as well keeps main.ts's own late readers store-only from the start.
+  captureRunnerSecrets();
+
   const config = loadConfig();
   markBoot("config_loaded");
 

package/src/payload-codecs.ts

@@ -15,6 +15,7 @@
 import type { PayloadCodec } from "@temporalio/common";
 import type { Config } from "./config.js";
 import type { BootstrapKeyMaterial } from "./encryption/config.js";
+import { getRunnerSecret } from "./shared/runner-credential-store.js";
 
 export async function createPayloadCodecs(
   config: Config,
@@ -30,7 +31,7 @@ export async function createPayloadCodecs(
   const encryptionConfig = loadPayloadEncryptionConfig(bootstrapKeys);
   if (encryptionConfig) {
     codecs.push(new EncryptionPayloadCodec(encryptionConfig));
-    const source = process.env.STIGMER_PAYLOAD_ENCRYPTION_KEY ? "env" : "bootstrap";
+    const source = getRunnerSecret("STIGMER_PAYLOAD_ENCRYPTION_KEY") ? "env" : "bootstrap";
     console.log(
       `[runner] Payload encryption enabled (source=${source}, ` +
         `key_id=${encryptionConfig.primary.keyId}` +