@stigmer/runner 3.1.7 → 3.1.8

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

@@ -14,18 +14,20 @@
  */
 
 import { Command } from "@langchain/langgraph";
-import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import type { AgentExecution, AgentExecutionStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
 import {
   ApprovalAction,
   ToolCallStatus,
 } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
-import type { ToolCall } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import type { AgentMessage } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
 
 // APPROVE_ALL resumes the interrupted tool exactly like APPROVE. Its
 // "auto-approve the rest of the run" effect is realized in setup.ts (the
 // approval gate is disabled for the whole execution once any APPROVE_ALL
 // decision exists), not here — this map only resolves the currently
-// interrupted tool calls.
+// interrupted tool calls. REJECT resumes the gate too (the gate returns a
+// denial ToolMessage that the model reads); it denies a single tool, it does
+// NOT fail the run — see reconcileNonExecutingDecisions for the terminal status.
 const ACTION_MAP: ReadonlyMap<ApprovalAction, string> = new Map([
   [ApprovalAction.APPROVE, "approve"],
   [ApprovalAction.APPROVE_ALL, "approve"],
@@ -36,8 +38,6 @@ const ACTION_MAP: ReadonlyMap<ApprovalAction, string> = new Map([
 export interface ResumeResult {
   readonly graphInput: Command | Record<string, unknown>;
   readonly isResumeFromApproval: boolean;
-  readonly hasRejection: boolean;
-  readonly rejectionReason: string;
 }
 
 export interface GraphStateSnapshot {
@@ -87,8 +87,6 @@ export function resolveResumeInput(
     return {
       graphInput: { messages: [{ role: "user", content: userMessage }] },
       isResumeFromApproval: false,
-      hasRejection: false,
-      rejectionReason: "",
     };
   }
 
@@ -97,14 +95,10 @@ export function resolveResumeInput(
     return {
       graphInput: { messages: [{ role: "user", content: userMessage }] },
       isResumeFromApproval: false,
-      hasRejection: false,
-      rejectionReason: "",
     };
   }
 
   const resumeDict: Record<string, { action: string; comment?: string }> = {};
-  let hasRejection = false;
-  let rejectionReason = "";
 
   for (const intr of pendingInterrupts) {
     const toolCallId = intr.toolCallId;
@@ -118,32 +112,22 @@ export function resolveResumeInput(
       action: actionStr,
       ...(decision.comment ? { comment: decision.comment } : {}),
     };
-
-    if (decision.action === ApprovalAction.REJECT) {
-      hasRejection = true;
-      rejectionReason = decision.comment || "Rejected by user";
-    }
   }
 
   if (Object.keys(resumeDict).length === 0) {
     return {
       graphInput: { messages: [{ role: "user", content: userMessage }] },
       isResumeFromApproval: false,
-      hasRejection: false,
-      rejectionReason: "",
     };
   }
 
   console.log(
-    `[hitl] Building resume for ${Object.keys(resumeDict).length} interrupt(s), ` +
-    `rejection=${hasRejection}`,
+    `[hitl] Building resume for ${Object.keys(resumeDict).length} interrupt(s)`,
   );
 
   return {
     graphInput: new Command({ resume: resumeDict }),
     isResumeFromApproval: true,
-    hasRejection,
-    rejectionReason,
   };
 }
 
@@ -207,31 +191,45 @@ function extractApprovalDecisions(
 }
 
 /**
- * Reconcile tool call statuses after resume decisions are applied.
+ * Terminalize tool calls whose approval decision is non-executing — SKIP or
+ * REJECT — so a denied or skipped call is never left stuck at WAITING_APPROVAL.
+ *
+ * This is the single, authoritative, checkpointer-independent reconciliation of
+ * the two decisions that never run the tool: their outcome is fully determined
+ * by the recorded decision (ToolCall.approval_action), not by any graph event.
+ * APPROVE / APPROVE_ALL are intentionally NOT handled here — the tool actually
+ * executes, and real tool events (v3 tool_started → tool_finished) terminalize
+ * it in place.
+ *
+ * Why a decision-derived reconciler rather than the resumed stream: on the
+ * durable path (sqlite local / http cloud) the gate returns a denial/skip
+ * ToolMessage WITHOUT an on_tool_start/on_tool_end pair, and on the memory path
+ * the graph replays without ever re-driving the gate — so in both cases the
+ * seeded WAITING_APPROVAL row is never flipped by the stream and would persist
+ * on a COMPLETED execution. Folding the recorded decision into a terminal status
+ * makes every checkpointer backend behave identically by construction.
  *
- * Updates the StatusBuilder's tool call entries to reflect the approval
- * outcomes: APPROVE → RUNNING, SKIP → SKIPPED, REJECT → FAILED.
+ * REJECT and SKIP share TOOL_CALL_SKIPPED as the terminal status (the tool did
+ * not run); they stay distinguishable by ToolCall.approval_action and by the
+ * append-only approval-event stream (REJECTED vs SKIPPED). Idempotent: a row
+ * already resolved carries the same decision and re-resolves identically.
  */
-export function reconcileToolCallStatuses(
-  toolCalls: ReadonlyMap<string, ToolCall>,
-  decisions: ReadonlyMap<string, ApprovalDecisionEntry>,
-): void {
-  for (const [toolCallId, decision] of decisions) {
-    const tc = toolCalls.get(toolCallId);
-    if (!tc) continue;
-
-    switch (decision.action) {
-      case ApprovalAction.APPROVE:
-      case ApprovalAction.APPROVE_ALL:
-        tc.status = ToolCallStatus.TOOL_CALL_RUNNING;
-        break;
-      case ApprovalAction.SKIP:
-        tc.status = ToolCallStatus.TOOL_CALL_SKIPPED;
-        break;
-      case ApprovalAction.REJECT:
-        tc.status = ToolCallStatus.TOOL_CALL_FAILED;
-        tc.error = `Rejected by user: ${decision.comment || "no reason given"}`;
-        break;
+export function reconcileNonExecutingDecisions(status: AgentExecutionStatus): void {
+  const apply = (messages: readonly AgentMessage[]): void => {
+    for (const msg of messages) {
+      for (const tc of msg.toolCalls) {
+        if (tc.approvalAction === ApprovalAction.SKIP) {
+          tc.status = ToolCallStatus.TOOL_CALL_SKIPPED;
+        } else if (tc.approvalAction === ApprovalAction.REJECT) {
+          tc.status = ToolCallStatus.TOOL_CALL_SKIPPED;
+          if (!tc.error) tc.error = "Rejected by user";
+        }
+      }
     }
+  };
+
+  apply(status.messages);
+  for (const subAgent of status.subAgentExecutions) {
+    apply(subAgent.messages);
   }
 }

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

@@ -47,7 +47,7 @@ import { StatusBuilder } from "./status-builder.js";
 import { InlinePublisher } from "./inline-publisher.js";
 import { WriteBackCoordinator } from "../../shared/workspace/writeback-coordinator.js";
 import { processPostStream } from "./post-stream.js";
-import { resolveResumeInput, type GraphStateSnapshot } from "./hitl.js";
+import { resolveResumeInput, reconcileNonExecutingDecisions, type GraphStateSnapshot } from "./hitl.js";
 import { captureApprovalArtifacts } from "./approval-file-change.js";
 import {
   applyCaptureDecisions,
@@ -85,6 +85,7 @@ export function createDeepAgentActivities(config: Config) {
     endpoint: config.stigmerBackendEndpoint,
     token: config.stigmerToken,
     tokenRef: config.stigmerTokenRef,
+    runnerTokenRef: config.stigmerRunnerTokenRef,
   });
 
   const streamingConfig = loadStreamingConfig();
@@ -151,23 +152,6 @@ export function createDeepAgentActivities(config: Config) {
           setup.execution.spec!.message,
         );
 
-        if (resume.hasRejection) {
-          const failedStatus = create(AgentExecutionStatusSchema, {
-            phase: ExecutionPhase.EXECUTION_FAILED,
-            error: `Execution rejected: ${resume.rejectionReason}`,
-            completedAt: utcTimestamp(),
-            messages: [
-              create(AgentMessageSchema, {
-                type: MessageType.MESSAGE_SYSTEM,
-                content: `Execution rejected by user: ${resume.rejectionReason}`,
-                timestamp: utcTimestamp(),
-              }),
-            ],
-          });
-          await persistStatus(client, executionId, failedStatus, { offload: statusOffload });
-          return slimStatus(failedStatus);
-        }
-
         const effectiveInput = resume.isResumeFromApproval
           ? resume.graphInput
           : setup.langgraphInput;
@@ -313,11 +297,13 @@ export function createDeepAgentActivities(config: Config) {
               // Complete now and push only the approved tree — NO model re-run.
               //
               // The discriminator is the PERSISTED transcript, not the live graph
-              // checkpoint: the memory checkpointer (OSS local / desktop) recreates
-              // the checkpoint empty each invocation, so a graphState-based check
-              // would wrongly fire for a mixed turn. A mixed turn leaves
-              // WAITING_APPROVAL tool rows in the transcript; a pure file-review
-              // turn leaves none.
+              // checkpoint: it must behave identically across checkpointer
+              // backends, but the live checkpoint does not — the memory backend
+              // (opt-in, tests) recreates it empty each invocation while the
+              // durable backends (sqlite local / http cloud) preserve it, so a
+              // graphState-based check would diverge and could wrongly fire for a
+              // mixed turn. A mixed turn leaves WAITING_APPROVAL tool rows in the
+              // transcript; a pure file-review turn leaves none.
               initialStatus.phase = ExecutionPhase.EXECUTION_COMPLETED;
               initialStatus.completedAt = utcTimestamp();
               if (writebackCoordinator) {
@@ -469,6 +455,16 @@ export function createDeepAgentActivities(config: Config) {
           initialStatus.subAgentExecutions,
         );
 
+        // Terminalize any tool call the user SKIPPED or REJECTED at the gate.
+        // These decisions never run the tool, so the resumed stream leaves the
+        // seeded WAITING_APPROVAL row untouched (the gate returns a ToolMessage
+        // with no on_tool_start on http; the memory replay never re-drives the
+        // gate). Folding the recorded decision into a terminal status here makes
+        // reject/skip resolve identically on both checkpointers — see
+        // reconcileNonExecutingDecisions. Runs before the WAITING-detection and
+        // completion persists below so the terminal status is what is persisted.
+        reconcileNonExecutingDecisions(initialStatus);
+
         // Turn boundary (capture mode): capture the candidate change set from the
         // git diff and author CANDIDATE_CAPTURED, then stamp the flowed file-edit
         // rows with the change set id — they stay visible in place as
@@ -917,10 +913,11 @@ async function processCaptureWriteback(
  *
  * The decision is therefore driven solely by whether the server already holds
  * committed history for this execution — NOT by the live graph checkpoint, which
- * the two checkpointers leave in different states for the same continuation:
- *   - durable (http): the checkpoint survives, the graph resumes via
- *     Command(resume), and streamEvents re-emits only post-checkpoint events;
- *   - memory (the OSS local / desktop default): the checkpoint is recreated
+ * the checkpointer backends leave in different states for the same continuation:
+ *   - durable (sqlite, the OSS local / desktop default; and http in cloud): the
+ *     checkpoint survives, the graph resumes via Command(resume), and
+ *     streamEvents re-emits only post-checkpoint events;
+ *   - memory (ephemeral, opt-in — used by tests): the checkpoint is recreated
  *     empty every invocation, so the graph REPLAYS from scratch and the blind
  *     FIFO turns advance one gate at a time.
  * Keying on the live checkpoint skipped seeding on that memory-replay path, so a
@@ -960,6 +957,18 @@ async function cleanup(setup: SetupResult | null): Promise<void> {
     }
   }
 
+  // Close the checkpointer's backing resources. Only the durable sqlite saver
+  // holds an OS handle (an open DB file); memory/http savers have no close(),
+  // so this is duck-typed and best-effort.
+  const closable = setup.checkpointer as { close?: () => void } | undefined;
+  if (closable && typeof closable.close === "function") {
+    try {
+      closable.close();
+    } catch (err) {
+      console.warn("[ExecuteDeepAgent] Checkpointer cleanup failed:", err);
+    }
+  }
+
   // Drop the workspace→platform `.stigmer` symlink so an attached repo is
   // left untouched between turns (issue #173 semantics; a multi-turn session
   // recreates it next turn). Runs in the activity finally, BEFORE the

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

@@ -34,7 +34,7 @@ import { CasCaptureObserver } from "./cas-capture-observer.js";
 import { isGitWorkTree, isPathCapturable } from "../../shared/filereview/git-substrate.js";
 import { deriveCaptureMode } from "../../shared/filereview/capture.js";
 import { resolveWorkspacePath } from "../../shared/file-change.js";
-import { ensurePlatformDir } from "../../shared/workspace/platform-dir.js";
+import { ensurePlatformDir, ensureCheckpointDbPath } from "../../shared/workspace/platform-dir.js";
 import { resolveSessionWorkspaceRoot } from "../../shared/workspace/session-root.js";
 import { buildWorkspaceFileTree } from "../../shared/workspace/file-tree.js";
 import { reportSetupProgress } from "../../shared/status.js";
@@ -75,6 +75,12 @@ import { transformAndCompileSubagents } from "./subagent-transformer.js";
 
 export interface SetupResult {
   readonly agentGraph: AgentGraph;
+  /**
+   * The checkpoint saver backing agentGraph. Retained so the activity can close
+   * it in cleanup — the durable sqlite saver holds an open file handle. Backends
+   * without a handle (memory/http) are duck-typed for an optional close().
+   */
+  readonly checkpointer: BaseCheckpointSaver;
   readonly langgraphConfig: Record<string, unknown>;
   readonly langgraphInput: Record<string, unknown>;
   readonly execution: AgentExecution;
@@ -191,11 +197,17 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
     const modelName = execution.spec!.executionConfig?.modelName
       || await getDefaultModel();
 
-    // Step 4: Create checkpointer
+    // Step 4: Create checkpointer. The durable local (sqlite) backend keys its
+    // file per session — a session has exactly one thread (`thread-{sessionId}`),
+    // so checkpoint lifetime tracks session lifetime. The saver is closed in the
+    // activity cleanup (see index.ts), alongside the MCP connection.
     const checkpointer = await createCheckpointer({
       type: config.checkpointerType,
       proxyEndpoint: config.checkpointerProxyEndpoint ?? undefined,
       authToken: config.stigmerToken ?? undefined,
+      sqlitePath: config.checkpointerType === "sqlite"
+        ? await ensureCheckpointDbPath(sessionId)
+        : undefined,
     });
 
     // Step 5: Resolve environment
@@ -595,6 +607,7 @@ export async function performSetup(deps: SetupDependencies): Promise<SetupResult
 
     return {
       agentGraph,
+      checkpointer,
       langgraphConfig,
       langgraphInput,
       execution,

package/src/activities/hydrate-workflow-execution.ts

@@ -33,6 +33,7 @@ export function createHydrateWorkflowActivities(config: Config) {
     endpoint: config.stigmerBackendEndpoint,
     token: config.stigmerToken,
     tokenRef: config.stigmerTokenRef,
+    runnerTokenRef: config.stigmerRunnerTokenRef,
   });
 
   return {
@@ -264,9 +265,16 @@ async function fetchAndFlattenEnv(
   client: StigmerClient,
   executionId: string,
 ): Promise<Record<string, unknown>> {
+  // A desktop runner exchanges its bootstrap credential for a token scoped to
+  // this workflow execution, so cloud's decrypt gate binds the read (#156).
+  // No-op for cloud sandbox and OSS runners.
+  const scopedToken = await client.acquireScopedRunnerToken({
+    workflowExecutionId: executionId,
+  });
+
   let execCtx;
   try {
-    execCtx = await client.getExecutionContextByExecutionId(executionId);
+    execCtx = await client.getExecutionContextByExecutionId(executionId, scopedToken);
   } catch (err: unknown) {
     // ConnectError uses numeric Code.NotFound (5); match the pattern
     // from execute-cursor/env-resolver.ts.

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

@@ -20,9 +20,35 @@ vi.mock("@connectrpc/connect", () => ({
 }));
 
 import { StigmerClient } from "../stigmer-client.js";
+import { ExecutionContextQueryController } from "@stigmer/protos/ai/stigmer/agentic/executioncontext/v1/query_pb";
+import { PlatformQueryController } from "@stigmer/protos/ai/stigmer/platform/v1/server_info_pb";
 
-function makeRequest(): { header: Map<string, string> } {
-  return { header: new Map() };
+function makeRequest(
+  serviceTypeName = "ai.stigmer.agentic.session.v1.SessionQueryController",
+  methodName = "get",
+): { header: Map<string, string>; service: { typeName: string }; method: { name: string } } {
+  return {
+    header: new Map(),
+    service: { typeName: serviceTypeName },
+    method: { name: methodName },
+  };
+}
+
+/** A request targeting the ExecutionContext query service (runner-credential path). */
+function makeExecutionContextRequest() {
+  return makeRequest(ExecutionContextQueryController.typeName, "getByExecutionId");
+}
+
+/** A request for the scoped-token exchange (runner-credential path, #156). */
+function makeScopedTokenExchangeRequest() {
+  return makeRequest(PlatformQueryController.typeName, "getRunnerScopedToken");
+}
+
+/** An unsigned JWT-shaped token carrying the given token_type claim. */
+function fakeTokenOfType(tokenType: string): string {
+  const b64 = (obj: Record<string, unknown>) =>
+    Buffer.from(JSON.stringify(obj)).toString("base64url");
+  return `${b64({ alg: "RS256" })}.${b64({ token_type: tokenType })}.sig`;
 }
 
 async function runInterceptor(req: ReturnType<typeof makeRequest>) {
@@ -120,6 +146,217 @@ describe("StigmerClient", () => {
     });
   });
 
+  describe("runnerTokenRef (ExecutionContext credential selection)", () => {
+    // Cloud gates ExecutionContext secret decryption on a runner-class
+    // token_type claim (stigmer-cloud#152). These tests pin the selection
+    // policy: the runner credential is used for the ExecutionContext query
+    // service only, and only when present.
+
+    it("uses the runner credential for ExecutionContext reads", async () => {
+      const tokenRef: TokenRef = { current: "control-plane-tok" };
+      const runnerRef: TokenRef = { current: "runner-tok" };
+      new StigmerClient({
+        endpoint: "http://localhost",
+        token: null,
+        tokenRef,
+        runnerTokenRef: runnerRef,
+      });
+
+      const req = makeExecutionContextRequest();
+      await runInterceptor(req);
+      expect(req.header.get("authorization")).toBe("Bearer runner-tok");
+    });
+
+    it("keeps the control-plane token for every other service", async () => {
+      const tokenRef: TokenRef = { current: "control-plane-tok" };
+      const runnerRef: TokenRef = { current: "runner-tok" };
+      new StigmerClient({
+        endpoint: "http://localhost",
+        token: null,
+        tokenRef,
+        runnerTokenRef: runnerRef,
+      });
+
+      const req = makeRequest();
+      await runInterceptor(req);
+      expect(req.header.get("authorization")).toBe("Bearer control-plane-tok");
+    });
+
+    it("falls back to the control-plane token when no runner credential exists (OSS/local)", async () => {
+      const tokenRef: TokenRef = { current: "control-plane-tok" };
+      const runnerRef: TokenRef = { current: null };
+      new StigmerClient({
+        endpoint: "http://localhost",
+        token: null,
+        tokenRef,
+        runnerTokenRef: runnerRef,
+      });
+
+      const req = makeExecutionContextRequest();
+      await runInterceptor(req);
+      expect(req.header.get("authorization")).toBe("Bearer control-plane-tok");
+    });
+
+    it("propagates runner-credential refreshes on subsequent requests", async () => {
+      const runnerRef: TokenRef = { current: "minted-v1" };
+      new StigmerClient({
+        endpoint: "http://localhost",
+        token: null,
+        runnerTokenRef: runnerRef,
+      });
+
+      const req1 = makeExecutionContextRequest();
+      await runInterceptor(req1);
+      expect(req1.header.get("authorization")).toBe("Bearer minted-v1");
+
+      runnerRef.current = "minted-v2";
+
+      const req2 = makeExecutionContextRequest();
+      await runInterceptor(req2);
+      expect(req2.header.get("authorization")).toBe("Bearer minted-v2");
+    });
+
+    it("uses the runner credential for the scoped-token exchange (#156)", async () => {
+      // The exchange requires the embedded_runner bootstrap credential; the
+      // control-plane token (the user's Auth0 token) would be denied.
+      const tokenRef: TokenRef = { current: "control-plane-tok" };
+      const runnerRef: TokenRef = { current: "runner-tok" };
+      new StigmerClient({
+        endpoint: "http://localhost",
+        token: null,
+        tokenRef,
+        runnerTokenRef: runnerRef,
+      });
+
+      const req = makeScopedTokenExchangeRequest();
+      await runInterceptor(req);
+      expect(req.header.get("authorization")).toBe("Bearer runner-tok");
+    });
+
+    it("keeps the control-plane token for other platform-service methods", async () => {
+      const tokenRef: TokenRef = { current: "control-plane-tok" };
+      const runnerRef: TokenRef = { current: "runner-tok" };
+      new StigmerClient({
+        endpoint: "http://localhost",
+        token: null,
+        tokenRef,
+        runnerTokenRef: runnerRef,
+      });
+
+      const req = makeRequest(PlatformQueryController.typeName, "getRunnerBootstrapConfig");
+      await runInterceptor(req);
+      expect(req.header.get("authorization")).toBe("Bearer control-plane-tok");
+    });
+  });
+
+  describe("per-call credential precedence (#156)", () => {
+    it("never overwrites an authorization header set via call options", async () => {
+      // The scoped-token flow authenticates individual ExecutionContext reads
+      // with a per-execution credential. Concurrent sessions in one runner
+      // process mean the process-wide selection below must not clobber it.
+      const runnerRef: TokenRef = { current: "process-wide-runner-tok" };
+      new StigmerClient({
+        endpoint: "http://localhost",
+        token: "process-wide-tok",
+        runnerTokenRef: runnerRef,
+      });
+
+      const req = makeExecutionContextRequest();
+      req.header.set("authorization", "Bearer per-call-scoped-tok");
+      await runInterceptor(req);
+
+      expect(req.header.get("authorization")).toBe("Bearer per-call-scoped-tok");
+    });
+  });
+
+  describe("acquireScopedRunnerToken", () => {
+    function clientWithRunnerCredential(token: string | null): StigmerClient {
+      return new StigmerClient({
+        endpoint: "http://localhost",
+        token: null,
+        runnerTokenRef: { current: token },
+      });
+    }
+
+    it("exchanges when holding an embedded_runner bootstrap credential", async () => {
+      const client = clientWithRunnerCredential(fakeTokenOfType("embedded_runner"));
+      vi.spyOn(client, "getRunnerScopedToken").mockResolvedValue({
+        token: "scoped-tok",
+        expiresInSeconds: 14400,
+      });
+
+      const token = await client.acquireScopedRunnerToken({ agentExecutionId: "aex_1" });
+
+      expect(token).toBe("scoped-tok");
+      expect(client.getRunnerScopedToken).toHaveBeenCalledWith({ agentExecutionId: "aex_1" });
+    });
+
+    it("skips the exchange for an already-scoped sandbox credential (cloud sandbox runner)", async () => {
+      const client = clientWithRunnerCredential(fakeTokenOfType("sandbox"));
+      const spy = vi.spyOn(client, "getRunnerScopedToken");
+
+      const token = await client.acquireScopedRunnerToken({ agentExecutionId: "aex_1" });
+
+      expect(token).toBeUndefined();
+      expect(spy).not.toHaveBeenCalled();
+    });
+
+    it("skips the exchange when no runner credential exists (OSS/local)", async () => {
+      const client = clientWithRunnerCredential(null);
+      const spy = vi.spyOn(client, "getRunnerScopedToken");
+
+      const token = await client.acquireScopedRunnerToken({ workflowExecutionId: "wfx_1" });
+
+      expect(token).toBeUndefined();
+      expect(spy).not.toHaveBeenCalled();
+    });
+
+    it("falls back (undefined) when the server mints no token", async () => {
+      const client = clientWithRunnerCredential(fakeTokenOfType("embedded_runner"));
+      vi.spyOn(client, "getRunnerScopedToken").mockResolvedValue(undefined);
+
+      const token = await client.acquireScopedRunnerToken({ agentExecutionId: "aex_1" });
+
+      expect(token).toBeUndefined();
+    });
+
+    it("falls back (undefined) when the exchange fails, instead of failing the execution", async () => {
+      const client = clientWithRunnerCredential(fakeTokenOfType("embedded_runner"));
+      vi.spyOn(client, "getRunnerScopedToken").mockRejectedValue(new Error("boom"));
+
+      const token = await client.acquireScopedRunnerToken({ agentExecutionId: "aex_1" });
+
+      expect(token).toBeUndefined();
+    });
+  });
+
+  describe("getExecutionContextByExecutionId per-call credential", () => {
+    it("passes the scoped token as a per-call authorization header", async () => {
+      const client = new StigmerClient({ endpoint: "http://localhost", token: null });
+      const getByExecutionId = vi.fn().mockResolvedValue({});
+      // Reach into the private generated client: the mocked createClient()
+      // returned {}, so install the method it would have provided.
+      (client as any).executionContextQuery = { getByExecutionId };
+
+      await client.getExecutionContextByExecutionId("aex_1", "scoped-tok");
+
+      expect(getByExecutionId).toHaveBeenCalledWith(
+        expect.anything(),
+        { headers: { authorization: "Bearer scoped-tok" } },
+      );
+    });
+
+    it("passes no call options without a scoped token", async () => {
+      const client = new StigmerClient({ endpoint: "http://localhost", token: null });
+      const getByExecutionId = vi.fn().mockResolvedValue({});
+      (client as any).executionContextQuery = { getByExecutionId };
+
+      await client.getExecutionContextByExecutionId("aex_1");
+
+      expect(getByExecutionId).toHaveBeenCalledWith(expect.anything(), undefined);
+    });
+  });
+
   describe("updateToken", () => {
     it("does not affect tokenRef-based resolution", async () => {
       const ref: TokenRef = { current: "from-ref" };

package/src/client/__tests__/token-claims.test.ts

@@ -0,0 +1,45 @@
+import { describe, it, expect } from "vitest";
+import { tokenTypeOf, isEmbeddedRunnerToken } from "../token-claims.js";
+
+/** Build an unsigned JWT-shaped token with the given payload. */
+function fakeJwt(payload: Record<string, unknown>): string {
+  const b64 = (obj: Record<string, unknown>) =>
+    Buffer.from(JSON.stringify(obj)).toString("base64url");
+  return `${b64({ alg: "RS256", typ: "JWT" })}.${b64(payload)}.signature`;
+}
+
+describe("tokenTypeOf", () => {
+  it("extracts the token_type claim", () => {
+    expect(tokenTypeOf(fakeJwt({ token_type: "embedded_runner" }))).toBe("embedded_runner");
+    expect(tokenTypeOf(fakeJwt({ token_type: "sandbox" }))).toBe("sandbox");
+  });
+
+  it("returns undefined for tokens without the claim (e.g. a user's Auth0 token)", () => {
+    expect(tokenTypeOf(fakeJwt({ sub: "user-1" }))).toBeUndefined();
+  });
+
+  it("returns undefined for a non-string claim value", () => {
+    expect(tokenTypeOf(fakeJwt({ token_type: 42 }))).toBeUndefined();
+  });
+
+  it("returns undefined for null, empty, and malformed tokens", () => {
+    expect(tokenTypeOf(null)).toBeUndefined();
+    expect(tokenTypeOf(undefined)).toBeUndefined();
+    expect(tokenTypeOf("")).toBeUndefined();
+    expect(tokenTypeOf("not-a-jwt")).toBeUndefined();
+    expect(tokenTypeOf("only.two")).toBeUndefined();
+    expect(tokenTypeOf("a.%%%not-base64%%%.c")).toBeUndefined();
+  });
+});
+
+describe("isEmbeddedRunnerToken", () => {
+  it("is true only for token_type=embedded_runner", () => {
+    expect(isEmbeddedRunnerToken(fakeJwt({ token_type: "embedded_runner" }))).toBe(true);
+    // A cloud sandbox runner's credential is already scoped — must not gate in.
+    expect(isEmbeddedRunnerToken(fakeJwt({ token_type: "sandbox" }))).toBe(false);
+    expect(isEmbeddedRunnerToken(fakeJwt({ token_type: "workflow_sandbox" }))).toBe(false);
+    // A user token has no token_type claim at all.
+    expect(isEmbeddedRunnerToken(fakeJwt({ sub: "user-1" }))).toBe(false);
+    expect(isEmbeddedRunnerToken(null)).toBe(false);
+  });
+});