@stigmer/runner 3.1.6 → 3.1.8

package/src/client/stigmer-client.ts

@@ -48,7 +48,8 @@ import { WorkflowQueryController } from "@stigmer/protos/ai/stigmer/agentic/work
 import type { Workflow } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/api_pb";
 import { WorkflowInstanceQueryController } from "@stigmer/protos/ai/stigmer/agentic/workflowinstance/v1/query_pb";
 import type { WorkflowInstance } from "@stigmer/protos/ai/stigmer/agentic/workflowinstance/v1/api_pb";
-import { PlatformQueryController } from "@stigmer/protos/ai/stigmer/platform/v1/server_info_pb";
+import { PlatformQueryController, GetRunnerScopedTokenInputSchema } from "@stigmer/protos/ai/stigmer/platform/v1/server_info_pb";
+import { isEmbeddedRunnerToken } from "./token-claims.js";
 import { assertCreateRequirements, assertReferenceRequirements } from "./server-contracts.js";
 
 /**
@@ -69,6 +70,28 @@ export interface RunnerBootstrapConfig {
   runnerAccessTokenExpiresInSeconds?: number;
 }
 
+/**
+ * A runner token scoped to one unit of dispatched work (issue #156).
+ *
+ * Minted on demand by the control plane when the runner exchanges its
+ * bootstrap credential at task start; presented for the ExecutionContext
+ * fetch of exactly that execution. Absent when the server does not mint
+ * (OSS, or no signing key) — the runner keeps its existing credential.
+ */
+export interface RunnerScopedToken {
+  token: string;
+  /** Lifetime in seconds from issuance; absent/0 when the server omitted it. */
+  expiresInSeconds?: number;
+}
+
+/**
+ * Names the unit of dispatched work a scoped runner token should serve.
+ * Exactly one id must be set — mirrors the proto oneof.
+ */
+export type RunnerScopedTokenScope =
+  | { agentExecutionId: string }
+  | { workflowExecutionId: string };
+
 /**
  * A shared mutable token reference. When provided, the interceptor
  * reads from this on every request, enabling token updates to
@@ -82,6 +105,13 @@ export interface StigmerClientOptions {
   endpoint: string;
   token: string | null;
   tokenRef?: TokenRef;
+  /**
+   * Optional runner credential (a server-minted token with a runner-class
+   * `token_type` claim). When populated, ExecutionContext reads authenticate
+   * with this instead of the control-plane token — see the interceptor in the
+   * constructor for why the credential differs per service.
+   */
+  runnerTokenRef?: TokenRef;
 }
 
 export class StigmerClient {
@@ -106,15 +136,49 @@ export class StigmerClient {
   private readonly platformQuery: Client<typeof PlatformQueryController>;
 
   private readonly tokenRef: TokenRef | null;
+  private readonly runnerTokenRef: TokenRef | null;
 
   constructor(options: StigmerClientOptions) {
     this.currentToken = options.token;
     this.tokenRef = options.tokenRef ?? null;
+    this.runnerTokenRef = options.runnerTokenRef ?? null;
     this.transport = createGrpcTransport({
       baseUrl: options.endpoint,
       interceptors: [
+        // Credential selection lives here — one tested decision point — rather
+        // than at call sites. Precedence:
+        //
+        // 1. An explicit per-call credential (an authorization header set via
+        //    CallOptions) always wins. The scoped-token flow (issue #156)
+        //    authenticates each ExecutionContext read with a token minted for
+        //    that specific execution; concurrent sessions in one runner process
+        //    make a shared mutable ref unusable for this — session A's read
+        //    must never go out with session B's token.
+        //
+        // 2. The runner credential (runnerTokenRef) authenticates the services
+        //    that require a runner-class token_type claim: ExecutionContext
+        //    reads carry decrypted secrets on cloud, and the server gates that
+        //    decrypt on runner class + scope (stigmer-cloud#152/#155); the
+        //    scoped-token exchange itself requires the embedded_runner
+        //    bootstrap credential (a desktop runner's control-plane token is
+        //    the user's own Auth0 token, which the server correctly treats as
+        //    a browsing user).
+        //
+        // 3. Everything else uses the control-plane token. Falls through
+        //    unchanged when no runner token exists (OSS/local, where the
+        //    server enforces no auth).
         (next) => async (req) => {
-          const token = this.tokenRef?.current ?? this.currentToken;
+          if (req.header.has("authorization")) {
+            return next(req);
+          }
+          const usesRunnerCredential =
+            req.service.typeName === ExecutionContextQueryController.typeName ||
+            (req.service.typeName === PlatformQueryController.typeName &&
+              req.method.name === PlatformQueryController.method.getRunnerScopedToken.name);
+          const token =
+            (usesRunnerCredential ? this.runnerTokenRef?.current : null)
+            ?? this.tokenRef?.current
+            ?? this.currentToken;
           if (token) {
             req.header.set("authorization", `Bearer ${token}`);
           }
@@ -180,12 +244,97 @@ export class StigmerClient {
     return this.executionCommand.updateStatus(input);
   }
 
-  async getExecutionContextByExecutionId(executionId: string): Promise<ExecutionContext> {
+  /**
+   * Fetch the ExecutionContext for an execution.
+   *
+   * When a scoped runner token is supplied (issue #156), the read
+   * authenticates with it per-call instead of the process-wide credential:
+   * on cloud the decrypt gate releases secrets only to a runner token whose
+   * scope binds it to this very execution, and one desktop runner process
+   * serves many sessions concurrently, so the credential cannot live in a
+   * shared ref.
+   */
+  async getExecutionContextByExecutionId(
+    executionId: string,
+    scopedToken?: string,
+  ): Promise<ExecutionContext> {
     return this.executionContextQuery.getByExecutionId(
       create(ExecutionContextExecutionIdInputSchema, { executionId }),
+      scopedToken
+        ? { headers: { authorization: `Bearer ${scopedToken}` } }
+        : undefined,
     );
   }
 
+  /**
+   * Exchange this runner's bootstrap credential for a token scoped to one
+   * unit of dispatched work (issue #156).
+   *
+   * The call authenticates with the runner credential (see the interceptor);
+   * the server verifies it is an embedded_runner token and that its identity
+   * can view the named execution, then mints the same session/execution-scoped
+   * sandbox token a cloud sandbox runner receives at provisioning. Returns
+   * undefined when the server does not mint (OSS, or no signing key) —
+   * presence-based, like the bootstrap token fields.
+   */
+  async getRunnerScopedToken(
+    scope: RunnerScopedTokenScope,
+  ): Promise<RunnerScopedToken | undefined> {
+    const input = create(GetRunnerScopedTokenInputSchema,
+      "agentExecutionId" in scope
+        ? { scope: { case: "agentExecutionId", value: scope.agentExecutionId } }
+        : { scope: { case: "workflowExecutionId", value: scope.workflowExecutionId } });
+    const res = await this.platformQuery.getRunnerScopedToken(input);
+    if (!res.runnerScopedToken) {
+      return undefined;
+    }
+    return {
+      token: res.runnerScopedToken,
+      expiresInSeconds: res.expiresInSeconds || undefined,
+    };
+  }
+
+  /**
+   * Acquire a scoped runner token for an ExecutionContext read, if this
+   * runner's credential situation calls for one.
+   *
+   * The gate is the credential itself: only an unscoped embedded_runner
+   * bootstrap token needs exchanging. A cloud sandbox runner's credential is
+   * already scoped (skip — the exchange would rightly refuse it), and an
+   * OSS/local runner holds no runner-class credential at all (skip — the
+   * server neither mints nor redacts).
+   *
+   * Failure falls back rather than failing the execution: returning undefined
+   * makes the read authenticate with the bootstrap credential, which remains
+   * decrypt-eligible until issue #156 item 3 removes it — at that point this
+   * fallback stops yielding secrets and executions surface the warning below.
+   */
+  async acquireScopedRunnerToken(
+    scope: RunnerScopedTokenScope,
+  ): Promise<string | undefined> {
+    if (!isEmbeddedRunnerToken(this.runnerTokenRef?.current)) {
+      return undefined;
+    }
+    try {
+      const scoped = await this.getRunnerScopedToken(scope);
+      if (!scoped) {
+        console.warn(
+          "[stigmer-client] Server minted no scoped runner token; " +
+          "falling back to the bootstrap credential for the ExecutionContext read",
+        );
+        return undefined;
+      }
+      return scoped.token;
+    } catch (err) {
+      console.warn(
+        "[stigmer-client] Scoped runner token exchange failed; " +
+        "falling back to the bootstrap credential for the ExecutionContext read: " +
+        `${err instanceof Error ? err.message : err}`,
+      );
+      return undefined;
+    }
+  }
+
   async getSession(sessionId: string): Promise<Session> {
     return this.sessionQuery.get({ value: sessionId });
   }

package/src/client/token-claims.ts

@@ -0,0 +1,42 @@
+/**
+ * Read-only claim inspection for the runner's own credentials.
+ *
+ * The runner never verifies signatures — the server does that. It only needs
+ * to look at its own token's `token_type` claim to decide which credential
+ * flow applies (e.g. "do I hold an unscoped bootstrap credential that must be
+ * exchanged for a scoped one before an ExecutionContext read?"). Claim names
+ * and values mirror the server's single source of truth,
+ * `StigmerTokenType` (stigmer-cloud, api-authentication).
+ */
+
+/** The `token_type` claim value of a bootstrap-minted embedded runner token. */
+export const TOKEN_TYPE_EMBEDDED_RUNNER = "embedded_runner";
+
+const CLAIM_TOKEN_TYPE = "token_type";
+
+/**
+ * Extract the `token_type` claim from a JWT without verifying it.
+ *
+ * Returns undefined for null/malformed tokens and for tokens without the
+ * claim (e.g. a user's Auth0 token) — callers branch on the specific value,
+ * so "unknown" and "absent" collapse to the same answer.
+ */
+export function tokenTypeOf(token: string | null | undefined): string | undefined {
+  if (!token) return undefined;
+  const parts = token.split(".");
+  if (parts.length !== 3) return undefined;
+  try {
+    const payload = JSON.parse(
+      Buffer.from(parts[1]!, "base64url").toString("utf8"),
+    ) as Record<string, unknown>;
+    const tokenType = payload[CLAIM_TOKEN_TYPE];
+    return typeof tokenType === "string" ? tokenType : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Whether the token is a bootstrap-minted `embedded_runner` credential. */
+export function isEmbeddedRunnerToken(token: string | null | undefined): boolean {
+  return tokenTypeOf(token) === TOKEN_TYPE_EMBEDDED_RUNNER;
+}

package/src/config.ts

@@ -73,7 +73,7 @@ export interface Config {
   readonly maxConcurrentActivities: number;
   readonly idleTimeoutSeconds: number | null;
   readonly cloudModeEnabled: boolean;
-  readonly checkpointerType: "memory" | "http";
+  readonly checkpointerType: "memory" | "http" | "sqlite";
   readonly checkpointerProxyEndpoint: string | null;
   readonly primaryModel: string;
   /**
@@ -97,6 +97,14 @@ export interface Config {
   readonly workspaceLockTimeoutMs: number;
   /** Shared mutable token reference for dynamic token updates (manager mode). */
   readonly stigmerTokenRef?: { current: string | null };
+  /**
+   * Shared mutable reference to the runner credential (manager mode): the
+   * server-minted runner token once adopted, tracking the control-plane token
+   * in lockstep before that. StigmerClient authenticates ExecutionContext
+   * reads with it so the server's runner-class decrypt gate recognizes a
+   * desktop runner (see stigmer-client.ts).
+   */
+  readonly stigmerRunnerTokenRef?: { current: string | null };
 }
 
 export function loadConfig(): Config {
@@ -146,8 +154,13 @@ export function loadConfig(): Config {
   const idleTimeoutRaw = process.env.STIGMER_IDLE_TIMEOUT_SECONDS;
   const idleTimeoutSeconds = idleTimeoutRaw ? parseInt(idleTimeoutRaw, 10) : null;
 
-  const checkpointerType = (process.env.STIGMER_CHECKPOINTER_TYPE as "memory" | "http" | undefined)
-    ?? (mode === "cloud" ? "http" : "memory");
+  // Local/OSS default is the durable SQLite saver so HITL/pause/transient-recovery
+  // resume across ExecuteDeepAgent invocations (stigmer/stigmer#204); cloud stays
+  // on the proxy-backed http saver. STIGMER_CHECKPOINTER_TYPE overrides explicitly
+  // (e.g. "memory" for ephemeral test runs).
+  const checkpointerType =
+    (process.env.STIGMER_CHECKPOINTER_TYPE as "memory" | "http" | "sqlite" | undefined)
+    ?? (mode === "cloud" ? "http" : "sqlite");
   const checkpointerProxyEndpoint = process.env.STIGMER_CHECKPOINTER_PROXY_ENDPOINT
     ?? proxyEndpoint;
 

package/src/middleware/__tests__/approval-gate.test.ts

@@ -168,12 +168,19 @@ describe("ApprovalGateMiddleware", () => {
 
     mockedInterrupt.mockReturnValue({ action: "reject", comment: "too dangerous" });
 
+    // Spy handler so we can prove the tool never executes on reject.
+    const handler = vi.fn(passthrough);
     const req = makeRequest({ name: "tool_b" });
-    const result = await mw.wrapToolCall!(req, passthrough);
+    const result = await mw.wrapToolCall!(req, handler);
 
     expect(result).toBeInstanceOf(ToolMessage);
     expect((result as ToolMessage).content).toContain("rejected");
     expect((result as ToolMessage).content).toContain("too dangerous");
+    // The tool is denied — the handler (execution) must NOT run.
+    expect(handler).not.toHaveBeenCalled();
+    // REJECT denies one tool and continues the run; it does not terminate the
+    // execution (issue #197) — the old "Execution will be terminated" copy is gone.
+    expect((result as ToolMessage).content).not.toContain("terminated");
   });
 
   describe("platform tool defaults", () => {

package/src/middleware/approval-gate.ts

@@ -288,9 +288,16 @@ export function createApprovalGateMiddleware(
       }
 
       if (action === "reject") {
-        const comment = response.comment ?? "rejected by user";
+        // REJECT denies THIS tool call and continues the run (it does not
+        // terminate the execution — see APPROVAL_ACTION_REJECT in enum.proto).
+        // Feed the user's objection back so the model adapts rather than
+        // retrying. Distinct from SKIP only by the strength of the signal.
+        const comment = response.comment ?? "";
+        const rejectMessage = comment
+          ? `Tool '${toolName}' was rejected by the user: ${comment}. Do not retry it; proceed by taking their objection into account.`
+          : `Tool '${toolName}' was rejected by the user. Do not retry it; proceed by taking their objection into account.`;
         return new ToolMessage({
-          content: `Tool '${toolName}' was rejected: ${comment}. Execution will be terminated.`,
+          content: rejectMessage,
           tool_call_id: toolCall.id,
           name: toolName,
         });

package/src/runner-manager.ts

@@ -94,8 +94,8 @@ export interface RunnerManagerOptions {
   /** Max wait for the per-workspace turn lock (ms). @default 900000 */
   readonly workspaceLockTimeoutMs?: number;
 
-  /** Checkpointer type for LangGraph agent state. @default "memory" (or "http" if proxyEndpoint is set) */
-  readonly checkpointerType?: "memory" | "http";
+  /** Checkpointer type for LangGraph agent state. @default "sqlite" (or "http" if proxyEndpoint is set) */
+  readonly checkpointerType?: "memory" | "http" | "sqlite";
 
   /** Checkpointer proxy endpoint. Falls back to proxyEndpoint. */
   readonly checkpointerProxyEndpoint?: string;
@@ -202,7 +202,16 @@ export async function createStigmerRunnerManager(
   // installed) — see that module for the two-writer rationale and the staleness
   // history it guards.
   const tokenRef = { current: options.stigmerToken ?? null };
-  const baseConfig = mapManagerOptionsToConfig(options, tokenRef);
+  // `runnerTokenRef` mirrors the coordinator's proxy credential for gRPC use:
+  // the minted runner token (token_type=embedded_runner) once adopted, tracking
+  // the control-plane token in lockstep before that. StigmerClient authenticates
+  // ExecutionContext reads with it so cloud's runner-class decrypt gate
+  // (stigmer-cloud#152) recognizes the desktop runner — its control-plane token
+  // is the user's own Auth0 token, which the server treats as a browsing user
+  // and answers with redacted secrets. Pre-mint the ref equals the control-plane
+  // token, which is exactly what the client would fall back to anyway.
+  const runnerTokenRef = { current: options.stigmerToken ?? null };
+  const baseConfig = mapManagerOptionsToConfig(options, tokenRef, runnerTokenRef);
 
   // Install the Cursor SDK interceptors BEFORE resolving Temporal coordinates.
   // Coordinate discovery dials the control plane via StigmerClient, which loads
@@ -235,14 +244,17 @@ export async function createStigmerRunnerManager(
   await assertHttp2ConnectPatched();
 
   // The token coordinator owns the proxy credential (x-stigmer-auth) and its
-  // refresh lifecycle. It writes ONLY the interceptors and re-mints using the
-  // always-fresh control-plane token in `tokenRef` — never the (possibly
-  // expired) minted token itself, so a slept-past-TTL runner recovers without a
-  // restart.
+  // refresh lifecycle. It writes ONLY its sinks (the interceptors plus the gRPC
+  // runner-credential ref) and re-mints using the always-fresh control-plane
+  // token in `tokenRef` — never the (possibly expired) minted token itself, so
+  // a slept-past-TTL runner recovers without a restart.
   const tokenCoordinator = createRunnerTokenCoordinator({
     applyProxyToken: (token) => {
       updateInterceptorToken(token);
       updateHttp2InterceptorToken(token);
+      // Third sink: keeps the ExecutionContext-read credential in lockstep with
+      // the proxy credential across mint and refresh (see runnerTokenRef above).
+      runnerTokenRef.current = token;
     },
     reMint: () =>
       refreshRunnerAccessToken({
@@ -545,6 +557,7 @@ function validateManagerOptions(options: RunnerManagerOptions): void {
 export function mapManagerOptionsToConfig(
   options: RunnerManagerOptions,
   tokenRef?: { current: string | null },
+  runnerTokenRef?: { current: string | null },
 ): Config {
   const proxyActive = !!options.proxyEndpoint;
 
@@ -563,6 +576,7 @@ export function mapManagerOptionsToConfig(
     stigmerBackendEndpoint: normalizeEndpoint(options.stigmerEndpoint),
     stigmerToken: options.stigmerToken ?? null,
     stigmerTokenRef: tokenRef,
+    stigmerRunnerTokenRef: runnerTokenRef,
     cursorApiKey: proxyActive
       ? (options.cursorApiKey ?? "proxy-managed")
       : (options.cursorApiKey ?? ""),
@@ -573,7 +587,7 @@ export function mapManagerOptionsToConfig(
     idleTimeoutSeconds: null,
     cloudModeEnabled: options.cloudModeEnabled ?? false,
     checkpointerType:
-      options.checkpointerType ?? (proxyActive ? "http" : "memory"),
+      options.checkpointerType ?? (proxyActive ? "http" : "sqlite"),
     checkpointerProxyEndpoint:
       options.checkpointerProxyEndpoint ?? options.proxyEndpoint ?? null,
     primaryModel: options.primaryModel ?? "gpt-4.1",

package/src/runner.ts

@@ -72,8 +72,8 @@ export interface StigmerRunnerOptions {
   /** Max wait for the per-workspace turn lock (ms). @default 900000 */
   readonly workspaceLockTimeoutMs?: number;
 
-  /** Checkpointer type for LangGraph agent state. @default "memory" (or "http" if proxyEndpoint is set) */
-  readonly checkpointerType?: "memory" | "http";
+  /** Checkpointer type for LangGraph agent state. @default "sqlite" (or "http" if proxyEndpoint is set) */
+  readonly checkpointerType?: "memory" | "http" | "sqlite";
 
   /** Checkpointer proxy endpoint. Falls back to proxyEndpoint. */
   readonly checkpointerProxyEndpoint?: string;
@@ -270,7 +270,7 @@ export function mapOptionsToConfig(options: StigmerRunnerOptions): Config {
     idleTimeoutSeconds: null,
     cloudModeEnabled: options.cloudModeEnabled ?? false,
     checkpointerType: options.checkpointerType
-      ?? (proxyActive ? "http" : "memory"),
+      ?? (proxyActive ? "http" : "sqlite"),
     checkpointerProxyEndpoint: options.checkpointerProxyEndpoint
       ?? options.proxyEndpoint
       ?? null,

package/src/shared/__tests__/mcp-oauth-detect.test.ts

@@ -0,0 +1,147 @@
+/**
+ * Unit tests for the HTTP MCP OAuth-challenge classifier.
+ *
+ * Verifies that `detectOAuthChallenge` recognizes a real MCP OAuth challenge
+ * (401 + `WWW-Authenticate: Bearer ...` per RFC 9728), and does NOT misfire on
+ * a plain invalid-token 401, a success, a non-OAuth error, or a network fault —
+ * so it can only ever turn an opaque failure into a clearer one, never mask a
+ * different cause.
+ */
+
+import { afterEach, describe, it, expect, vi } from "vitest";
+import {
+  OAuthRequiredError,
+  detectOAuthChallenge,
+  isOAuthChallenge,
+  parseResourceMetadataUrl,
+} from "../mcp-oauth-detect.js";
+
+function mockFetchOnce(response: {
+  status: number;
+  wwwAuthenticate?: string;
+}): void {
+  const headers = new Headers();
+  if (response.wwwAuthenticate !== undefined) {
+    headers.set("www-authenticate", response.wwwAuthenticate);
+  }
+  vi.stubGlobal(
+    "fetch",
+    vi.fn(async () =>
+      new Response(null, { status: response.status, headers }),
+    ),
+  );
+}
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  vi.restoreAllMocks();
+});
+
+describe("isOAuthChallenge", () => {
+  it("matches the MCP auth spec Bearer + OAuth realm challenge", () => {
+    expect(
+      isOAuthChallenge('Bearer realm="OAuth", resource_metadata="https://x/.well-known/oauth-protected-resource"'),
+    ).toBe(true);
+  });
+
+  it("matches a Bearer challenge that only advertises resource_metadata", () => {
+    expect(
+      isOAuthChallenge('Bearer resource_metadata="https://x/.well-known/oauth-protected-resource"'),
+    ).toBe(true);
+  });
+
+  it("does not match a plain Bearer 401 (invalid API key, not an OAuth requirement)", () => {
+    expect(isOAuthChallenge('Bearer error="invalid_token"')).toBe(false);
+  });
+
+  it("does not match a non-Bearer scheme", () => {
+    expect(isOAuthChallenge('Basic realm="oauth"')).toBe(false);
+  });
+
+  it("is empty-safe", () => {
+    expect(isOAuthChallenge("")).toBe(false);
+  });
+});
+
+describe("parseResourceMetadataUrl", () => {
+  it("extracts the resource_metadata URL", () => {
+    expect(
+      parseResourceMetadataUrl(
+        'Bearer realm="OAuth", resource_metadata="https://mcp.notion.com/.well-known/oauth-protected-resource/mcp"',
+      ),
+    ).toBe("https://mcp.notion.com/.well-known/oauth-protected-resource/mcp");
+  });
+
+  it("returns undefined when absent", () => {
+    expect(parseResourceMetadataUrl('Bearer realm="OAuth"')).toBeUndefined();
+  });
+});
+
+describe("detectOAuthChallenge", () => {
+  it("returns an OAuthRequiredError for a 401 OAuth challenge", async () => {
+    mockFetchOnce({
+      status: 401,
+      wwwAuthenticate:
+        'Bearer realm="OAuth", resource_metadata="https://mcp.notion.com/.well-known/oauth-protected-resource/mcp"',
+    });
+
+    const result = await detectOAuthChallenge("https://mcp.notion.com/mcp", {}, "notion");
+
+    expect(result).toBeInstanceOf(OAuthRequiredError);
+    expect(result?.serverSlug).toBe("notion");
+    expect(result?.resourceMetadataUrl).toBe(
+      "https://mcp.notion.com/.well-known/oauth-protected-resource/mcp",
+    );
+    // The message is self-contained and carries the "requires OAuth" marker the
+    // connect wrappers key on.
+    expect(result?.message).toContain("requires OAuth");
+    expect(result?.message).toContain("notion");
+  });
+
+  it("returns null for a 401 that is NOT an OAuth challenge (invalid static token)", async () => {
+    mockFetchOnce({ status: 401, wwwAuthenticate: 'Bearer error="invalid_token"' });
+    expect(
+      await detectOAuthChallenge("https://api.example.com/mcp", {}, "example"),
+    ).toBeNull();
+  });
+
+  it("returns null on a non-401 response", async () => {
+    mockFetchOnce({ status: 200 });
+    expect(
+      await detectOAuthChallenge("https://api.example.com/mcp", {}, "example"),
+    ).toBeNull();
+  });
+
+  it("returns null (never throws) when the probe itself fails", async () => {
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => {
+        throw new Error("network down");
+      }),
+    );
+    expect(
+      await detectOAuthChallenge("https://api.example.com/mcp", {}, "example"),
+    ).toBeNull();
+  });
+
+  it("forwards the resolved headers to the probe request", async () => {
+    const fetchMock = vi.fn(
+      async (_url: string | URL, _init?: RequestInit) =>
+        new Response(null, { status: 200 }),
+    );
+    vi.stubGlobal("fetch", fetchMock);
+
+    await detectOAuthChallenge(
+      "https://api.example.com/mcp",
+      { Authorization: "Bearer stale-token" },
+      "example",
+    );
+
+    expect(fetchMock).toHaveBeenCalledOnce();
+    const init = fetchMock.mock.calls[0]?.[1];
+    expect((init?.headers as Record<string, string>).Authorization).toBe(
+      "Bearer stale-token",
+    );
+    expect(init?.method).toBe("POST");
+  });
+});

package/src/shared/__tests__/tool-row.test.ts

@@ -11,6 +11,7 @@ import { AgentMessageSchema, ToolCallSchema } from "@stigmer/protos/ai/stigmer/a
 import { SubAgentExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/subagent_pb";
 import { ToolCallStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import {
+  collectSettledToolCallIds,
   collectSubAgentToolCallIds,
   hideToolCallRow,
   isToolCallRowHidden,
@@ -354,3 +355,37 @@ describe("collectSubAgentToolCallIds", () => {
     expect([...collectSubAgentToolCallIds([sa]).values()].sort()).toEqual(["tc-a", "tc-b"]);
   });
 });
+
+describe("collectSettledToolCallIds", () => {
+  function msgWith(id: string, status: ToolCallStatus) {
+    return create(AgentMessageSchema, {
+      type: 1, // MESSAGE_AI
+      toolCalls: [create(ToolCallSchema, { id, name: "Shell", status })],
+    });
+  }
+
+  it("collects every terminal status and skips every live one", () => {
+    const ids = collectSettledToolCallIds([
+      msgWith("tc-completed", ToolCallStatus.TOOL_CALL_COMPLETED),
+      msgWith("tc-failed", ToolCallStatus.TOOL_CALL_FAILED),
+      msgWith("tc-skipped", ToolCallStatus.TOOL_CALL_SKIPPED),
+      msgWith("tc-pending", ToolCallStatus.TOOL_CALL_PENDING),
+      msgWith("tc-running", ToolCallStatus.TOOL_CALL_RUNNING),
+      msgWith("tc-gated", ToolCallStatus.TOOL_CALL_WAITING_APPROVAL),
+    ]);
+    expect([...ids].sort()).toEqual(["tc-completed", "tc-failed", "tc-skipped"]);
+  });
+
+  it("treats a server-settled INTERRUPTED row as settled (recovery provenance scoping)", () => {
+    // A FAILED-then-recovered execution seeds INTERRUPTED rows from the prior
+    // invocation. For turn-boundary provenance those are PRIOR-turn history —
+    // scoping them as this-turn would mis-attribute a dead call to the
+    // resuming turn's change set. (The Cursor monotonic guard makes the
+    // opposite call for the same status so a replayed event can still advance
+    // the row; see isTerminalToolStatus in message-translator.ts.)
+    const ids = collectSettledToolCallIds([
+      msgWith("tc-interrupted", ToolCallStatus.TOOL_CALL_INTERRUPTED),
+    ]);
+    expect(ids.has("tc-interrupted")).toBe(true);
+  });
+});

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

@@ -1,14 +1,40 @@
-import { describe, it, expect } from "vitest";
+import { describe, it, expect, afterEach } from "vitest";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { MemorySaver } from "@langchain/langgraph-checkpoint";
 import { createCheckpointer, CheckpointerCreationError } from "../factory.js";
 import { HttpCheckpointSaver } from "../http-saver.js";
+import { SqliteCheckpointSaver } from "../sqlite-saver.js";
 
 describe("createCheckpointer", () => {
+  const tempDirs: string[] = [];
+  afterEach(() => {
+    for (const d of tempDirs.splice(0)) rmSync(d, { recursive: true, force: true });
+  });
+
   it("returns MemorySaver for type=memory", async () => {
     const saver = await createCheckpointer({ type: "memory" });
     expect(saver).toBeInstanceOf(MemorySaver);
   });
 
+  it("returns SqliteCheckpointSaver for type=sqlite", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "stigmer-cp-factory-"));
+    tempDirs.push(dir);
+    const saver = await createCheckpointer({
+      type: "sqlite",
+      sqlitePath: join(dir, "checkpoints.db"),
+    });
+    expect(saver).toBeInstanceOf(SqliteCheckpointSaver);
+    (saver as SqliteCheckpointSaver).close();
+  });
+
+  it("throws CheckpointerCreationError when sqlite is missing sqlitePath", async () => {
+    await expect(
+      createCheckpointer({ type: "sqlite" }),
+    ).rejects.toThrow(CheckpointerCreationError);
+  });
+
   it("returns HttpCheckpointSaver for type=http", async () => {
     const saver = await createCheckpointer({
       type: "http",