@stigmer/runner 3.12.2 → 3.12.4

package/src/middleware/tool-intent.ts

@@ -0,0 +1,174 @@
+/**
+ * Tool-intent middleware — model-authored intent titles for shell tool calls
+ * (issue #276).
+ *
+ * The thread UI titles every shell row with the bare category label ("Shell");
+ * only the model knows *why* it is running a command, so a host-side rename
+ * can never close that gap. This middleware lets the model author the title:
+ * at model-call time it presents a schema-extended clone of the shell tool
+ * that adds one optional `description` argument. The model fills it in, the
+ * argument rides the tool call's args verbatim through checkpoints and the
+ * persisted ToolCall proto (no new state, no proto change), and the React SDK
+ * renders it as the row title with the command as secondary text.
+ *
+ * Why this seam:
+ * - The `execute` tool is owned by the deepagents library; its schema is not
+ *   ours to edit. `wrapModelCall` is the framework's intended point for
+ *   reshaping the model-visible tool list — langchain's own llmToolSelector
+ *   middleware swaps `request.tools` through exactly this hook.
+ * - Execution is untouched by construction: the agent's ToolNode is built
+ *   once from the ORIGINAL tools, and the original schema parses with strip
+ *   semantics, so the extra argument is dropped before the backend's
+ *   `execute(command)` ever runs. Approval fingerprints are equally
+ *   unaffected (`description` is not a salient arg field).
+ * - The argument name deliberately matches the Cursor harness, whose built-in
+ *   Shell tool already carries a model-authored `description` — both
+ *   harnesses converge on one wire key and the SDK reads a single field.
+ *
+ * The swapped-in declaration is a `StructuredToolParams` object — langchain's
+ * first-class shape for a non-executable, bind-time-only tool definition
+ * ("the most minimal interface … to be passed to a LLM for tool calling").
+ * A same-name RUNNABLE replacement is rejected by the agent's wrapModelCall
+ * validation (it would threaten ToolNode execution identity); a params
+ * object is exactly the declaration-without-execution the validation exists
+ * to protect, and the graph keeps executing the untouched original. Schema
+ * extension happens at the JSON-schema level via @langchain/core's interop
+ * serializer — the runner's zod (v3) must never construct fields inside the
+ * library's zod (v4) schema object.
+ */
+
+import { toJsonSchema } from "@langchain/core/utils/json_schema";
+import { ToolKind } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { classifyTool } from "../shared/tool-kind.js";
+import type { StigmerMiddleware } from "./types.js";
+
+/**
+ * The wire name of the intent argument. Shared with the Cursor harness's
+ * built-in Shell tool and read by the SDK's tool presentation layer — the
+ * three surfaces must agree on this key.
+ */
+export const INTENT_ARG = "description";
+
+/**
+ * The behavior-shaping prompt for the intent argument (owner-approved
+ * wording, issue #276). This is prompt engineering, not documentation:
+ * changing it changes what the model writes into every shell row title.
+ */
+export const INTENT_ARG_PROMPT =
+  "A short present-tense phrase describing what this command does and why, " +
+  "shown to the user as the title of this action (5-10 words, e.g. " +
+  "'Run unit tests for the parser'). Do not restate the command syntax.";
+
+/** Structural shape of a bindable structured tool, checked at runtime. */
+interface StructuredToolLike {
+  readonly name: string;
+  readonly description: string;
+  readonly schema: unknown;
+}
+
+function isStructuredToolLike(candidate: unknown): candidate is StructuredToolLike {
+  if (candidate == null || typeof candidate !== "object") return false;
+  const t = candidate as Record<string, unknown>;
+  return (
+    typeof t.name === "string" &&
+    typeof t.description === "string" &&
+    "schema" in t
+  );
+}
+
+interface JsonObjectSchema {
+  readonly type: "object";
+  readonly properties?: Record<string, unknown>;
+  readonly [key: string]: unknown;
+}
+
+function isJsonObjectSchema(schema: unknown): schema is JsonObjectSchema {
+  return (
+    schema != null &&
+    typeof schema === "object" &&
+    (schema as Record<string, unknown>).type === "object"
+  );
+}
+
+/**
+ * Returns a bind-time `StructuredToolParams` declaration for `original`
+ * whose schema carries the optional intent argument, or `original` itself
+ * when the tool is not a shell tool, is not schema-extendable, or already
+ * defines an argument with that name (a real argument must never be
+ * shadowed by presentation metadata).
+ *
+ * Unexpected schemas pass through unchanged on purpose: a missing intent
+ * title degrades to today's rendering, while a mangled schema would break
+ * the tool for the whole execution.
+ */
+function maybeExtendShellTool(original: unknown): unknown {
+  if (!isStructuredToolLike(original)) return original;
+  if (classifyTool(original.name) !== ToolKind.SHELL) return original;
+
+  let jsonSchema: unknown;
+  try {
+    jsonSchema = toJsonSchema(original.schema as Parameters<typeof toJsonSchema>[0]);
+  } catch {
+    return original;
+  }
+  if (!isJsonObjectSchema(jsonSchema)) return original;
+
+  const properties = jsonSchema.properties ?? {};
+  if (INTENT_ARG in properties) return original;
+
+  // A plain frozen declaration, deliberately NOT an executable tool: the
+  // graph's ToolNode executes the ORIGINAL registered tool (it is built from
+  // the registered tools, not from the model request), and the agent's
+  // wrapModelCall validation only forbids swapping same-name EXECUTABLE
+  // instances. `isStructuredToolParams` recognizes this shape, so every
+  // provider's bindTools converts it exactly like a structured tool.
+  return Object.freeze({
+    name: original.name,
+    description: original.description,
+    schema: {
+      ...jsonSchema,
+      properties: {
+        ...properties,
+        [INTENT_ARG]: { type: "string", description: INTENT_ARG_PROMPT },
+      },
+    },
+  });
+}
+
+/**
+ * Creates the middleware. Install on the parent stack AND on every sub-agent
+ * stack (subagent-wiring.ts) — sub-agent shell rows render in the same
+ * thread and must carry the same titles.
+ */
+export function createToolIntentMiddleware(): StigmerMiddleware {
+  // One clone per original tool instance: repeated model calls (and repeated
+  // turns on the same graph) bind a referentially stable clone instead of
+  // re-serializing the schema every round.
+  const cloneCache = new WeakMap<object, unknown>();
+
+  const extendCached = (candidate: unknown): unknown => {
+    if (candidate == null || typeof candidate !== "object") return candidate;
+    const cached = cloneCache.get(candidate);
+    if (cached !== undefined) return cached;
+    const extended = maybeExtendShellTool(candidate);
+    cloneCache.set(candidate, extended);
+    return extended;
+  };
+
+  return {
+    name: "StigmerToolIntentMiddleware",
+    async wrapModelCall(request, handler) {
+      const tools = request.tools;
+      if (!tools || tools.length === 0) return handler(request);
+
+      let changed = false;
+      const mapped = tools.map((t) => {
+        const extended = extendCached(t);
+        if (extended !== t) changed = true;
+        return extended;
+      });
+
+      return handler(changed ? { ...request, tools: mapped } : request);
+    },
+  };
+}

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}` +

package/src/runner-manager.ts

@@ -32,6 +32,11 @@ import type { WorkerActivities } from "./worker.js";
 import { resolveWorkflowSource, OTEL_WORKFLOW_INTERCEPTOR_MODULE } from "./workflow-source.js";
 import { resolveRunnerBootstrap, refreshRunnerAccessToken } from "./bootstrap.js";
 import { assertLlmBackendsPreflight } from "./preflight.js";
+import {
+  captureRunnerSecrets,
+  getRunnerSecret,
+  setRunnerSecret,
+} from "./shared/runner-credential-store.js";
 import { createRunnerTokenCoordinator } from "./runner-token-coordinator.js";
 // Per-task-queue in-flight activity tracking lives in ./in-flight.ts so the
 // activity interceptor (no manager-closure handle) and unit tests can reach it.
@@ -214,6 +219,12 @@ export async function createStigmerRunnerManager(
 ): Promise<StigmerRunnerManager> {
   validateManagerOptions(options);
 
+  // Take custody of runner secrets BEFORE anything else can read them from
+  // env — and before any agent code could spawn with them (#508). Runs here
+  // (not only in main.ts) because this factory is a public library boot door:
+  // in-process embedders like the desktop never execute main.ts.
+  captureRunnerSecrets();
+
   const { registerStigmerDeepagentsProfiles } = await import(
     "./activities/execute-deep-agent/deepagents-profiles.js"
   );
@@ -365,7 +376,7 @@ export async function createStigmerRunnerManager(
   if (
     !bootstrap.payloadEncryption &&
     bootstrap.runnerAccessToken &&
-    !process.env.STIGMER_PAYLOAD_ENCRYPTION_KEY
+    !getRunnerSecret("STIGMER_PAYLOAD_ENCRYPTION_KEY")
   ) {
     console.warn(
       "[runner-manager] Server minted a runner token but returned no payload " +
@@ -530,6 +541,13 @@ export async function createStigmerRunnerManager(
       await removeManaged(
         sessions, sessionId, SESSION_QUEUE_PREFIX + sessionId, "session",
       );
+      // The session is done on this host — release its parked agent (and
+      // the executor + MCP subprocesses the lease pins) immediately rather
+      // than waiting out the idle TTL (#215).
+      const { evictSessionAgent } = await import(
+        "./activities/execute-cursor/agent-session-cache.js"
+      );
+      evictSessionAgent(sessionId);
     },
 
     activeSessions(): string[] {
@@ -585,12 +603,11 @@ export async function createStigmerRunnerManager(
       // 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
+      // process.env.STIGMER_TOKEN write, #508): per-call readers like
+      // call-llm and the registry headers resolve the current token there.
       tokenRef.current = token;
-      if (token) {
-        process.env.STIGMER_TOKEN = token;
-      } else {
-        delete process.env.STIGMER_TOKEN;
-      }
+      setRunnerSecret("STIGMER_TOKEN", token);
       tokenCoordinator.onControlPlaneTokenChanged(token);
       console.log("[runner-manager] Auth token updated");
     },
@@ -629,6 +646,12 @@ export async function createStigmerRunnerManager(
       }
 
       await Promise.all(shutdownPromises);
+      // Workers are drained — release every parked session agent so their
+      // executor leases dispose (stdio MCP subprocesses die with them) (#215).
+      const { closeAllCachedAgents } = await import(
+        "./activities/execute-cursor/agent-session-cache.js"
+      );
+      closeAllCachedAgents();
       sessions.clear();
       workflowExecutions.clear();
       poolControl = null;

package/src/runner.ts

@@ -20,6 +20,10 @@ import { DEFAULT_CURSOR_AGENT_RESOLVE_TIMEOUT_MS, DEFAULT_CURSOR_STREAM_STALL_TI
 import type { WorkerActivities } from "./worker.js";
 import { resolveRunnerBootstrap } from "./bootstrap.js";
 import { assertLlmBackendsPreflight } from "./preflight.js";
+import {
+  captureRunnerSecrets,
+  setRunnerSecret,
+} from "./shared/runner-credential-store.js";
 import { markBoot, emitRunnerBootTiming } from "./shared/cold-start-timing.js";
 
 /**
@@ -118,11 +122,12 @@ 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: activity gRPC clients read {@code tokenRef} per request,
- * env-reading call sites (call-llm, registry-endpoint) read
- * {@code process.env.STIGMER_TOKEN} per call, artifact storage resolves the
- * ref per call, and the two Cursor SDK interceptors are updated directly —
- * a static runner has no {@code RunnerTokenCoordinator} minting a separate
- * proxy credential, so its x-stigmer-auth IS this token.
+ * 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 are updated directly — a static runner has no
+ * {@code RunnerTokenCoordinator} minting a separate proxy credential, so its
+ * x-stigmer-auth IS this token.
  */
 async function startStaticSandboxTokenRenewal(
   config: Config,
@@ -157,7 +162,9 @@ async function startStaticSandboxTokenRenewal(
       client.getRunnerScopedToken({ renewal: true }, currentToken),
     applyToken: (token) => {
       tokenRef.current = token;
-      process.env.STIGMER_TOKEN = token;
+      // Store write replaced the process.env.STIGMER_TOKEN write (#508) —
+      // same per-call readers (call-llm, registry headers), no env exposure.
+      setRunnerSecret("STIGMER_TOKEN", token);
       updateInterceptorToken(token);
       updateHttp2InterceptorToken(token);
     },
@@ -190,6 +197,12 @@ export async function createStigmerRunner(
 ): Promise<StigmerRunner> {
   validateOptions(options);
 
+  // Take custody of runner secrets BEFORE anything else can read them from
+  // env — and before any agent code could spawn with them (#508). Runs here
+  // (not only in main.ts) because this factory is a public library boot door
+  // for in-process embedders.
+  captureRunnerSecrets();
+
   const { registerStigmerDeepagentsProfiles } = await import(
     "./activities/execute-deep-agent/deepagents-profiles.js"
   );
@@ -327,6 +340,12 @@ export async function createStigmerRunner(
       emitRunnerBootTiming({ task_queue: config.taskQueue, mode: config.mode });
       await worker.run();
       console.log("Worker stopped");
+      // The worker has drained — release any parked session agent so its
+      // executor lease disposes with the process (#215).
+      const { closeAllCachedAgents } = await import(
+        "./activities/execute-cursor/agent-session-cache.js"
+      );
+      closeAllCachedAgents();
     },
     shutdown() {
       tokenRenewal?.stop();

package/src/shared/__tests__/model-client.test.ts

@@ -23,6 +23,7 @@ vi.mock("@langchain/openai", () => ({
 
 import { buildChatModel } from "../model-client.js";
 import { _resetRegistryCache } from "../model-registry.js";
+import { ServiceTier } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 
 interface MockModel {
   id: string;
@@ -306,6 +307,18 @@ describe("buildChatModel", () => {
       expect(lastAnthropicArgs().apiKey).toBe("");
     });
 
+    it("does NOT send service_tier on a backend adapter — tiers are Anthropic-first-party billing, and Vertex/Bedrock/Foundry have no tier dimension", async () => {
+      mockRegistryResponse([
+        { id: "claude-sonnet-4.6", apiModelId: "claude-sonnet-4-6", provider: "anthropic" },
+      ]);
+
+      await buildChatModel({ modelName: "claude-sonnet-4.6", serviceTier: ServiceTier.STANDARD });
+
+      const args = lastAnthropicArgs();
+      expect(typeof args.createClient).toBe("function");
+      expect(args).not.toHaveProperty("invocationKwargs");
+    });
+
     it("yields to the proxy: a proxied call never consults the backend var", async () => {
       mockRegistryResponse([
         { id: "claude-sonnet-4.6", apiModelId: "claude-sonnet-4-6", provider: "anthropic" },
@@ -359,4 +372,90 @@ describe("buildChatModel", () => {
     await expect(buildChatModel({ modelName: "claude-sonnet-4.6" }))
       .rejects.toThrow(/STIGMER_ANTHROPIC_BACKEND="verteks" is not a supported backend/);
   });
+
+  describe("service tier (stigmer/stigmer#361)", () => {
+    // The #357 contract on the native harness: when the caller passes the
+    // execution's effective tier, every provider request pins it
+    // explicitly, so the provider ACCOUNT's default can never pick the
+    // price. Each provider has its own spelling; both are pinned here so
+    // a wrapper upgrade that moves the slot fails loudly.
+
+    it("OpenAI: STANDARD pins service_tier 'default' — never 'auto', which would re-open the account-default hole", async () => {
+      mockRegistryResponse([
+        { id: "gpt-4.1", apiModelId: "gpt-4.1", provider: "openai" },
+      ]);
+
+      await buildChatModel({ modelName: "gpt-4.1", serviceTier: ServiceTier.STANDARD });
+
+      const args = mockOpenAICtor.mock.calls.at(-1)?.[0] as Record<string, unknown>;
+      expect(args).toMatchObject({ service_tier: "default" });
+    });
+
+    it("OpenAI: FAST pins service_tier 'priority'", async () => {
+      mockRegistryResponse([
+        { id: "gpt-4.1", apiModelId: "gpt-4.1", provider: "openai" },
+      ]);
+
+      await buildChatModel({ modelName: "gpt-4.1", serviceTier: ServiceTier.FAST });
+
+      const args = mockOpenAICtor.mock.calls.at(-1)?.[0] as Record<string, unknown>;
+      expect(args).toMatchObject({ service_tier: "priority" });
+    });
+
+    it("Anthropic: STANDARD rides invocationKwargs as 'standard_only' — priority capacity is never consumed implicitly", async () => {
+      mockRegistryResponse([
+        { id: "claude-haiku-4.5", apiModelId: "claude-haiku-4-5-20251001", provider: "anthropic" },
+      ]);
+
+      await buildChatModel({ modelName: "claude-haiku-4.5", serviceTier: ServiceTier.STANDARD });
+
+      expect(lastAnthropicArgs()).toMatchObject({
+        invocationKwargs: { service_tier: "standard_only" },
+      });
+    });
+
+    it("Anthropic: FAST rides invocationKwargs as 'auto' — use purchased priority capacity when available", async () => {
+      mockRegistryResponse([
+        { id: "claude-haiku-4.5", apiModelId: "claude-haiku-4-5-20251001", provider: "anthropic" },
+      ]);
+
+      await buildChatModel({ modelName: "claude-haiku-4.5", serviceTier: ServiceTier.FAST });
+
+      expect(lastAnthropicArgs()).toMatchObject({
+        invocationKwargs: { service_tier: "auto" },
+      });
+    });
+
+    it("an omitted tier sends NO tier parameter on either provider — platform-internal utility calls stay untiered", async () => {
+      mockRegistryResponse([
+        { id: "gpt-4.1", apiModelId: "gpt-4.1", provider: "openai" },
+      ]);
+      await buildChatModel({ modelName: "gpt-4.1" });
+      const openAiArgs = mockOpenAICtor.mock.calls.at(-1)?.[0] as Record<string, unknown>;
+      expect(openAiArgs).not.toHaveProperty("service_tier");
+
+      mockRegistryResponse([
+        { id: "claude-haiku-4.5", apiModelId: "claude-haiku-4-5-20251001", provider: "anthropic" },
+      ]);
+      await buildChatModel({ modelName: "claude-haiku-4.5" });
+      expect(lastAnthropicArgs()).not.toHaveProperty("invocationKwargs");
+    });
+
+    it("the tier rides the proxy path too — the request body parameter is what the proxy meters", async () => {
+      mockRegistryResponse([
+        { id: "claude-haiku-4.5", apiModelId: "claude-haiku-4-5-20251001", provider: "anthropic" },
+      ]);
+
+      await buildChatModel({
+        modelName: "claude-haiku-4.5",
+        proxyEndpoint: "https://api.stigmer.ai",
+        stigmerToken: "token",
+        serviceTier: ServiceTier.STANDARD,
+      });
+
+      expect(lastAnthropicArgs()).toMatchObject({
+        invocationKwargs: { service_tier: "standard_only" },
+      });
+    });
+  });
 });

package/src/shared/__tests__/runner-credential-store.test.ts

@@ -0,0 +1,155 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import {
+  captureRunnerSecrets,
+  getRunnerSecret,
+  setRunnerSecret,
+  runnerSecretsEnvView,
+  resetRunnerSecretsForTests,
+} from "../runner-credential-store.js";
+import {
+  RUNNER_CREDENTIAL_ENV_KEYS,
+  RUNNER_ENCRYPTION_ENV_KEYS,
+  RUNNER_SECRET_ENV_KEYS,
+} from "../runner-credential-keys.js";
+
+/** Snapshot/restore of every env slot these tests touch. */
+const savedEnv = new Map<string, string | undefined>();
+
+beforeEach(() => {
+  resetRunnerSecretsForTests();
+  for (const key of RUNNER_SECRET_ENV_KEYS) {
+    savedEnv.set(key, process.env[key]);
+    delete process.env[key];
+  }
+});
+
+afterEach(() => {
+  resetRunnerSecretsForTests();
+  for (const [key, value] of savedEnv) {
+    if (value === undefined) {
+      delete process.env[key];
+    } else {
+      process.env[key] = value;
+    }
+  }
+  savedEnv.clear();
+});
+
+describe("captureRunnerSecrets", () => {
+  it("moves every listed secret out of process.env and into the store", () => {
+    // Plant a value for every name in the source-of-truth list, so a key
+    // added to runner-credential-keys.ts is covered here automatically —
+    // the #385 test idiom, applied to custody.
+    for (const key of RUNNER_SECRET_ENV_KEYS) {
+      process.env[key] = `boot-${key}`;
+    }
+
+    captureRunnerSecrets();
+
+    for (const key of RUNNER_SECRET_ENV_KEYS) {
+      expect(
+        process.env[key],
+        `'${key}' must not remain in process.env after capture — anything ` +
+        `left there is readable by every agent shell command (issue #508)`,
+      ).toBeUndefined();
+      expect(getRunnerSecret(key)).toBe(`boot-${key}`);
+    }
+  });
+
+  it("is idempotent — a second capture cannot re-freeze rotated values", () => {
+    process.env.STIGMER_TOKEN = "boot-token";
+    captureRunnerSecrets();
+    setRunnerSecret("STIGMER_TOKEN", "rotated-token");
+
+    // A late (buggy or racing) boot-door call must be a no-op.
+    process.env.STIGMER_TOKEN = "stale-replant";
+    captureRunnerSecrets();
+
+    expect(getRunnerSecret("STIGMER_TOKEN")).toBe("rotated-token");
+    // The replant stays in env (capture did not consume it) — the live-env
+    // fallback below deliberately does NOT apply when the store holds a
+    // value, so rotation always wins.
+    expect(process.env.STIGMER_TOKEN).toBe("stale-replant");
+    delete process.env.STIGMER_TOKEN;
+  });
+
+  it("scrubs the encryption keys, not only the #385 credentials (issue #508)", () => {
+    // Pins the #508 scope widening by name. The parameterized test above
+    // would pass even if the combined list regressed to the 8 credentials;
+    // this one cannot.
+    for (const key of [
+      "STIGMER_PAYLOAD_ENCRYPTION_KEY",
+      "STIGMER_PAYLOAD_ENCRYPTION_SECONDARY_KEY",
+    ]) {
+      expect(RUNNER_ENCRYPTION_ENV_KEYS, `'${key}' must be a captured secret`).toContain(key);
+    }
+    for (const key of [...RUNNER_CREDENTIAL_ENV_KEYS, ...RUNNER_ENCRYPTION_ENV_KEYS]) {
+      expect(RUNNER_SECRET_ENV_KEYS, `'${key}' must be in the scrub list`).toContain(key);
+    }
+  });
+});
+
+describe("getRunnerSecret", () => {
+  it("falls back to a live process.env value the capture never saw", () => {
+    captureRunnerSecrets();
+    // Custody rule 2: a value planted after boot behaves like the env read
+    // the store replaced (test/embedder compatibility) — production only
+    // sets these at process start, so this path is dead there.
+    process.env.STIGMER_TOKEN = "late-planted";
+
+    expect(getRunnerSecret("STIGMER_TOKEN")).toBe("late-planted");
+  });
+
+  it("returns undefined for an absent secret", () => {
+    captureRunnerSecrets();
+    expect(getRunnerSecret("STIGMER_TOKEN")).toBeUndefined();
+  });
+});
+
+describe("setRunnerSecret", () => {
+  it("carries the rotation channel: set updates, null clears", () => {
+    captureRunnerSecrets();
+
+    setRunnerSecret("STIGMER_TOKEN", "minted-1");
+    expect(getRunnerSecret("STIGMER_TOKEN")).toBe("minted-1");
+
+    setRunnerSecret("STIGMER_TOKEN", "minted-2");
+    expect(getRunnerSecret("STIGMER_TOKEN")).toBe("minted-2");
+
+    setRunnerSecret("STIGMER_TOKEN", null);
+    expect(getRunnerSecret("STIGMER_TOKEN")).toBeUndefined();
+  });
+
+  it("never lets a rotated value sit in process.env, even if a writer beats the boot capture", () => {
+    process.env.STIGMER_TOKEN = "boot-token";
+
+    // No captureRunnerSecrets() call yet — the writer forces it.
+    setRunnerSecret("STIGMER_TOKEN", "rotated-early");
+
+    expect(process.env.STIGMER_TOKEN).toBeUndefined();
+    expect(getRunnerSecret("STIGMER_TOKEN")).toBe("rotated-early");
+  });
+});
+
+describe("runnerSecretsEnvView", () => {
+  it("merges captured secrets over process.env without writing them back", () => {
+    process.env.STIGMER_TOKEN = "boot-token";
+    captureRunnerSecrets();
+
+    const view = runnerSecretsEnvView();
+
+    expect(view.STIGMER_TOKEN).toBe("boot-token");
+    expect(view.PATH).toBe(process.env.PATH);
+    expect(
+      process.env.STIGMER_TOKEN,
+      "building the view must not re-plant secrets into process.env",
+    ).toBeUndefined();
+  });
+
+  it("reflects rotation", () => {
+    captureRunnerSecrets();
+    setRunnerSecret("STIGMER_TOKEN", "rotated");
+
+    expect(runnerSecretsEnvView().STIGMER_TOKEN).toBe("rotated");
+  });
+});