@stigmer/runner 3.0.1

package/src/activities/execute-cursor/__tests__/hitl-ledger.test.ts

@@ -0,0 +1,298 @@
+/**
+ * Unit tests for the Cursor-harness HITL denial-ledger flow.
+ *
+ * These cover the architecture the platform converges on: the preToolUse hook
+ * records denials to a ledger, the runner marks the gated tool calls
+ * WAITING_APPROVAL, and the backend projects pending_approvals from that
+ * tool-call status. The tests are deterministic and need no Cursor API key.
+ *
+ * Specifically they pin:
+ * - the denial ledger reset/read contract (per-turn freshness, tolerant parse)
+ * - token-correlated overlay of WAITING_APPROVAL onto streamed tool calls,
+ *   INCLUDING the regression where a denied tool was reported as "completed"
+ *   (the green-checkmark bug) — it must become WAITING_APPROVAL, not success
+ * - synthesis of a tool call when a denial produced no stream event
+ * - reconstruction of adjudicated approvals from tool calls on reinvocation
+ *   (pending_approvals is empty by then because the backend cleared it)
+ * - the generated hook script wiring (records denials in both deny branches)
+ */
+
+import { describe, it, expect, afterEach } from "vitest";
+import { create } from "@bufbuild/protobuf";
+import { mkdtempSync, rmSync } from "node:fs";
+import { writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  AgentMessageSchema,
+  ToolCallSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import type {
+  AgentMessage,
+  ToolCall,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import {
+  MessageType,
+  ToolCallStatus,
+  ApprovalAction,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+import {
+  resetDenialLedger,
+  readDenialLedger,
+  denialLedgerPath,
+  reconstructAdjudicatedApprovals,
+  grantToken,
+} from "../approval-state.js";
+import { reconcileDeniedToolCalls } from "../message-translator.js";
+import { generateHookScript } from "../hook-script.js";
+import type { MergedToolPolicy } from "../approval-policy.js";
+
+const tempDirs: string[] = [];
+
+afterEach(() => {
+  for (const dir of tempDirs.splice(0)) {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+function makeWorkspace(): string {
+  const dir = mkdtempSync(join(tmpdir(), "hitl-ledger-"));
+  tempDirs.push(dir);
+  return dir;
+}
+
+function toolCall(overrides: Partial<ToolCall>): ToolCall {
+  return create(ToolCallSchema, {
+    id: "call-1",
+    name: "Write",
+    status: ToolCallStatus.TOOL_CALL_COMPLETED,
+    ...overrides,
+  });
+}
+
+function aiMessageWith(toolCalls: ToolCall[]): AgentMessage {
+  return create(AgentMessageSchema, {
+    type: MessageType.MESSAGE_AI,
+    content: "",
+    toolCalls,
+  });
+}
+
+describe("denial ledger reset/read", () => {
+  it("reset creates an empty ledger that reads as no denials", async () => {
+    const ws = makeWorkspace();
+    const path = await resetDenialLedger(ws);
+    expect(path).toBe(denialLedgerPath(ws));
+    expect(await readDenialLedger(ws)).toEqual([]);
+  });
+
+  it("returns no denials when the ledger file does not exist", async () => {
+    const ws = makeWorkspace();
+    expect(await readDenialLedger(ws)).toEqual([]);
+  });
+
+  it("parses appended JSONL denials and tolerates blank/partial lines", async () => {
+    const ws = makeWorkspace();
+    await resetDenialLedger(ws);
+    const writeToken = grantToken("Write", "gated.txt");
+    const shellToken = grantToken("Shell", "rm -rf build");
+    // Simulate the hook appending records, including a trailing partial line.
+    await writeFile(
+      denialLedgerPath(ws),
+      `{"toolName":"Write","token":"${writeToken}"}\n` +
+        `\n` +
+        `{"toolName":"Shell","token":"${shellToken}"}\n` +
+        `{"toolName":"Partial","tok`,
+      "utf-8",
+    );
+
+    const entries = await readDenialLedger(ws);
+    expect(entries).toEqual([
+      { toolName: "Write", token: writeToken },
+      { toolName: "Shell", token: shellToken },
+    ]);
+  });
+});
+
+describe("reconcileDeniedToolCalls", () => {
+  it("overlays WAITING_APPROVAL onto a denied tool reported as completed (the green-check bug)", () => {
+    const tc = toolCall({
+      id: "c1",
+      name: "Write",
+      status: ToolCallStatus.TOOL_CALL_COMPLETED,
+      completedAt: "2026-06-07T00:00:00Z",
+      result: "wrote file",
+      args: { path: "gated.txt" },
+      argsPreview: JSON.stringify({ path: "gated.txt" }),
+    });
+    const messages = [aiMessageWith([tc])];
+
+    const reconciled = reconcileDeniedToolCalls(messages, [
+      { toolName: "Write", token: grantToken("Write", "gated.txt") },
+    ]);
+
+    expect(reconciled).toHaveLength(1);
+    expect(tc.status).toBe(ToolCallStatus.TOOL_CALL_WAITING_APPROVAL);
+    expect(tc.requiresApproval).toBe(true);
+    expect(tc.approvalMessage).toContain("gated.txt");
+    expect(tc.approvalRequestedAt).not.toBe("");
+    // The tool never actually ran — terminal/result fields must be cleared so the
+    // UI does not render it as a completed success.
+    expect(tc.completedAt).toBe("");
+    expect(tc.result).toBe("");
+    expect(tc.error).toBe("");
+  });
+
+  it("resolves the MCP policy message for a denied MCP tool", () => {
+    const tc = toolCall({
+      id: "c1",
+      name: "apply_x",
+      mcpServerSlug: "planton",
+      status: ToolCallStatus.TOOL_CALL_COMPLETED,
+    });
+    const messages = [aiMessageWith([tc])];
+    const policies = new Map<string, MergedToolPolicy>([
+      ["planton/apply_x", {
+        toolName: "apply_x",
+        mcpServerSlug: "planton",
+        requiresApproval: true,
+        approvalMessage: "Apply infrastructure change",
+      }],
+    ]);
+
+    // MCP tools are keyed name-only (mirrors the grant convention).
+    reconcileDeniedToolCalls(messages, [
+      { toolName: "apply_x", token: grantToken("apply_x", "") },
+    ], policies);
+
+    expect(tc.status).toBe(ToolCallStatus.TOOL_CALL_WAITING_APPROVAL);
+    expect(tc.approvalMessage).toBe("Apply infrastructure change");
+  });
+
+  it("leaves non-denied tool calls untouched while overlaying the denied one", () => {
+    const denied = toolCall({
+      id: "c1",
+      name: "Write",
+      status: ToolCallStatus.TOOL_CALL_COMPLETED,
+      args: { path: "gated.txt" },
+    });
+    const allowed = toolCall({
+      id: "c2",
+      name: "Read",
+      status: ToolCallStatus.TOOL_CALL_COMPLETED,
+      args: { path: "readme.md" },
+    });
+    const messages = [aiMessageWith([denied, allowed])];
+
+    const reconciled = reconcileDeniedToolCalls(messages, [
+      { toolName: "Write", token: grantToken("Write", "gated.txt") },
+    ]);
+
+    // Only the denied call is gated; the read-only call keeps its status and no
+    // spurious approval is synthesized (the ledger token matched a real call).
+    expect(reconciled).toHaveLength(1);
+    expect(denied.status).toBe(ToolCallStatus.TOOL_CALL_WAITING_APPROVAL);
+    expect(allowed.status).toBe(ToolCallStatus.TOOL_CALL_COMPLETED);
+    expect(messages[0].toolCalls).toHaveLength(2);
+  });
+
+  it("collapses repeated denials of the same resource to a single approval", () => {
+    const first = toolCall({ id: "c1", name: "Write", args: { path: "gated.txt" } });
+    const second = toolCall({ id: "c2", name: "Write", args: { path: "gated.txt" } });
+    const messages = [aiMessageWith([first, second])];
+
+    const reconciled = reconcileDeniedToolCalls(messages, [
+      { toolName: "Write", token: grantToken("Write", "gated.txt") },
+    ]);
+
+    // One approval anchor (so the backend gate resolves cleanly on one decision).
+    expect(reconciled).toHaveLength(1);
+    expect(first.status).toBe(ToolCallStatus.TOOL_CALL_WAITING_APPROVAL);
+    expect(second.status).toBe(ToolCallStatus.TOOL_CALL_COMPLETED);
+  });
+
+  it("synthesizes a WAITING_APPROVAL tool call when a denial produced no stream event", () => {
+    const messages = [aiMessageWith([])];
+
+    const reconciled = reconcileDeniedToolCalls(messages, [
+      { toolName: "Shell", token: grantToken("Shell", "rm -rf build") },
+    ]);
+
+    expect(reconciled).toHaveLength(1);
+    const synthesized = messages[0].toolCalls[0];
+    expect(synthesized.status).toBe(ToolCallStatus.TOOL_CALL_WAITING_APPROVAL);
+    expect(synthesized.requiresApproval).toBe(true);
+    expect(synthesized.name).toBe("Shell");
+    expect(synthesized.approvalMessage).toContain("rm -rf build");
+  });
+
+  it("is a no-op when the ledger is empty", () => {
+    const tc = toolCall({ id: "c1", status: ToolCallStatus.TOOL_CALL_COMPLETED });
+    const messages = [aiMessageWith([tc])];
+    expect(reconcileDeniedToolCalls(messages, [])).toEqual([]);
+    expect(tc.status).toBe(ToolCallStatus.TOOL_CALL_COMPLETED);
+  });
+});
+
+describe("reconstructAdjudicatedApprovals", () => {
+  it("reads decisions and rebuilds pending approvals from adjudicated tool calls", () => {
+    const approved = toolCall({
+      id: "c1",
+      name: "Write",
+      status: ToolCallStatus.TOOL_CALL_WAITING_APPROVAL,
+      approvalAction: ApprovalAction.APPROVE,
+      approvalMessage: "Write file: gated.txt",
+      argsPreview: JSON.stringify({ path: "gated.txt" }),
+    });
+    const undecided = toolCall({
+      id: "c2",
+      name: "Shell",
+      status: ToolCallStatus.TOOL_CALL_WAITING_APPROVAL,
+      approvalAction: ApprovalAction.UNSPECIFIED,
+    });
+    const unrelated = toolCall({
+      id: "c3",
+      name: "Read",
+      status: ToolCallStatus.TOOL_CALL_COMPLETED,
+      approvalAction: ApprovalAction.APPROVE,
+    });
+    const messages = [aiMessageWith([approved, undecided, unrelated])];
+
+    const { pendingApprovals, decisions } = reconstructAdjudicatedApprovals(messages);
+
+    expect([...decisions.entries()]).toEqual([["c1", ApprovalAction.APPROVE]]);
+    expect(pendingApprovals).toHaveLength(1);
+    expect(pendingApprovals[0].toolCallId).toBe("c1");
+    expect(pendingApprovals[0].toolName).toBe("Write");
+    expect(pendingApprovals[0].argsPreview).toBe(JSON.stringify({ path: "gated.txt" }));
+  });
+
+  it("returns nothing when no tool call carries a decision", () => {
+    const tc = toolCall({
+      id: "c1",
+      status: ToolCallStatus.TOOL_CALL_WAITING_APPROVAL,
+      approvalAction: ApprovalAction.UNSPECIFIED,
+    });
+    const { pendingApprovals, decisions } = reconstructAdjudicatedApprovals([aiMessageWith([tc])]);
+    expect(pendingApprovals).toEqual([]);
+    expect(decisions.size).toBe(0);
+  });
+});
+
+describe("generateHookScript ledger wiring", () => {
+  it("wires the ledger path and records denials in both deny branches", () => {
+    const script = generateHookScript(
+      "/ws/.cursor/hooks/stigmer-approval-state.json",
+      "/ws/.cursor/hooks/stigmer-denials.jsonl",
+    );
+
+    expect(script).toContain('LEDGER_FILE="/ws/.cursor/hooks/stigmer-denials.jsonl"');
+    expect(script).toContain("record_denial()");
+    // One definition + a call in the gated-built-in branch + a call in the MCP
+    // branch = 3 occurrences.
+    const occurrences = script.split("record_denial").length - 1;
+    expect(occurrences).toBeGreaterThanOrEqual(3);
+  });
+});

package/src/activities/execute-cursor/__tests__/http2-interceptor.test.ts

@@ -0,0 +1,360 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { createRequire } from "node:module";
+import type http2Type from "node:http2";
+import { installHttp2Interceptor, uninstallHttp2Interceptor, updateHttp2InterceptorToken, assertHttp2ConnectPatched } from "../http2-interceptor.js";
+import { getExecutionContext } from "../fetch-interceptor.js";
+
+const require = createRequire(import.meta.url);
+const http2: typeof http2Type = require("node:http2");
+
+const PROXY_ENDPOINT = "https://proxy.example.com:8443";
+const STIGMER_TOKEN = "test-stigmer-jwt-token";
+const NON_PROXY_AUTHORITY = "https://temporal.internal:7233";
+
+interface RequestCall {
+  authority: string | URL;
+  headers?: http2Type.OutgoingHttpHeaders;
+}
+
+/**
+ * Creates a mock http2.connect that records request() calls.
+ * Must be installed BEFORE installHttp2Interceptor() so the interceptor
+ * chains through it (it captures http2.connect at install time).
+ */
+function createMockConnect() {
+  const calls: RequestCall[] = [];
+  const mockStream = {} as http2Type.ClientHttp2Stream;
+
+  const mockConnect = ((authority: string | URL) => {
+    const session = {
+      request(headers?: http2Type.OutgoingHttpHeaders) {
+        calls.push({ authority, headers });
+        return mockStream;
+      },
+      close() {},
+      destroy() {},
+      once() { return session; },
+      on() { return session; },
+    } as unknown as http2Type.ClientHttp2Session;
+    return session;
+  }) as typeof http2.connect;
+
+  return { calls, mockStream, mockConnect };
+}
+
+describe("http2-interceptor", () => {
+  const trueOriginalConnect = http2.connect;
+
+  afterEach(() => {
+    uninstallHttp2Interceptor();
+    http2.connect = trueOriginalConnect;
+  });
+
+  describe("installHttp2Interceptor", () => {
+    it("is a no-op when proxyEndpoint is undefined", () => {
+      const before = http2.connect;
+      installHttp2Interceptor({ proxyEndpoint: undefined, stigmerToken: STIGMER_TOKEN });
+      expect(http2.connect).toBe(before);
+    });
+
+    it("is a no-op when proxyEndpoint is empty string", () => {
+      const before = http2.connect;
+      installHttp2Interceptor({ proxyEndpoint: "", stigmerToken: STIGMER_TOKEN });
+      expect(http2.connect).toBe(before);
+    });
+
+    it("is a no-op when stigmerToken is undefined", () => {
+      const before = http2.connect;
+      installHttp2Interceptor({ proxyEndpoint: PROXY_ENDPOINT, stigmerToken: undefined });
+      expect(http2.connect).toBe(before);
+    });
+
+    it("replaces http2.connect when proxyEndpoint and stigmerToken are valid", () => {
+      const before = http2.connect;
+      installHttp2Interceptor({ proxyEndpoint: PROXY_ENDPOINT, stigmerToken: STIGMER_TOKEN });
+      expect(http2.connect).not.toBe(before);
+    });
+  });
+
+  describe("uninstallHttp2Interceptor", () => {
+    it("restores the connect function that was active at install time", () => {
+      const { mockConnect } = createMockConnect();
+      http2.connect = mockConnect;
+
+      installHttp2Interceptor({ proxyEndpoint: PROXY_ENDPOINT, stigmerToken: STIGMER_TOKEN });
+      expect(http2.connect).not.toBe(mockConnect);
+
+      uninstallHttp2Interceptor();
+      expect(http2.connect).toBe(mockConnect);
+    });
+  });
+
+  describe("header injection", () => {
+    let mock: ReturnType<typeof createMockConnect>;
+
+    beforeEach(() => {
+      mock = createMockConnect();
+      http2.connect = mock.mockConnect;
+      installHttp2Interceptor({ proxyEndpoint: PROXY_ENDPOINT, stigmerToken: STIGMER_TOKEN });
+    });
+
+    it("injects x-stigmer-execution-id and x-stigmer-auth when context is active and target is proxy", async () => {
+      const executionContext = getExecutionContext();
+      await executionContext.run({ executionId: "exec-abc-123" }, async () => {
+        const session = http2.connect(PROXY_ENDPOINT);
+        session.request({ ":method": "POST", ":path": "/agent.v1.AgentService/Run" });
+      });
+
+      expect(mock.calls).toHaveLength(1);
+      expect(mock.calls[0].headers).toMatchObject({
+        ":method": "POST",
+        ":path": "/agent.v1.AgentService/Run",
+        "x-stigmer-auth": `Bearer ${STIGMER_TOKEN}`,
+        "x-stigmer-execution-id": "exec-abc-123",
+      });
+    });
+
+    it("injects x-stigmer-auth but NOT x-stigmer-execution-id when no execution context is active", () => {
+      const session = http2.connect(PROXY_ENDPOINT);
+      session.request({ ":method": "POST", ":path": "/agent.v1.AgentService/Run" });
+
+      expect(mock.calls).toHaveLength(1);
+      expect(mock.calls[0].headers).toHaveProperty("x-stigmer-auth", `Bearer ${STIGMER_TOKEN}`);
+      expect(mock.calls[0].headers).not.toHaveProperty("x-stigmer-execution-id");
+    });
+
+    it("does NOT inject header when target is not the proxy endpoint", async () => {
+      const executionContext = getExecutionContext();
+      await executionContext.run({ executionId: "exec-xyz-789" }, async () => {
+        const session = http2.connect(NON_PROXY_AUTHORITY);
+        session.request({ ":method": "POST", ":path": "/temporal.api.v1/StartWorkflow" });
+      });
+
+      expect(mock.calls).toHaveLength(1);
+      expect(mock.calls[0].headers).not.toHaveProperty("x-stigmer-execution-id");
+    });
+
+    it("injects x-stigmer-auth without modifying existing authorization header", async () => {
+      const executionContext = getExecutionContext();
+      await executionContext.run({ executionId: "exec-preserve" }, async () => {
+        const session = http2.connect(PROXY_ENDPOINT);
+        session.request({
+          ":method": "POST",
+          ":path": "/agent.v1.AgentService/Run",
+          "authorization": "Bearer original-cursor-token",
+          "content-type": "application/connect+proto",
+        });
+      });
+
+      expect(mock.calls[0].headers).toMatchObject({
+        ":method": "POST",
+        ":path": "/agent.v1.AgentService/Run",
+        "authorization": "Bearer original-cursor-token",
+        "x-stigmer-auth": `Bearer ${STIGMER_TOKEN}`,
+        "content-type": "application/connect+proto",
+        "x-stigmer-execution-id": "exec-preserve",
+      });
+    });
+
+    it("handles request() with no headers argument", async () => {
+      const executionContext = getExecutionContext();
+      await executionContext.run({ executionId: "exec-no-headers" }, async () => {
+        const session = http2.connect(PROXY_ENDPOINT);
+        session.request();
+      });
+
+      expect(mock.calls).toHaveLength(1);
+      expect(mock.calls[0].headers).toMatchObject({
+        "x-stigmer-execution-id": "exec-no-headers",
+      });
+    });
+
+    it("returns the stream from the underlying session.request()", async () => {
+      const executionContext = getExecutionContext();
+      let returnedStream: http2Type.ClientHttp2Stream | undefined;
+
+      await executionContext.run({ executionId: "exec-return" }, async () => {
+        const session = http2.connect(PROXY_ENDPOINT);
+        returnedStream = session.request({});
+      });
+
+      expect(returnedStream).toBe(mock.mockStream);
+    });
+  });
+
+  describe("connection reuse with different execution contexts", () => {
+    let mock: ReturnType<typeof createMockConnect>;
+
+    beforeEach(() => {
+      mock = createMockConnect();
+      http2.connect = mock.mockConnect;
+      installHttp2Interceptor({ proxyEndpoint: PROXY_ENDPOINT, stigmerToken: STIGMER_TOKEN });
+    });
+
+    it("different requests on same session get execution IDs from their respective ALS contexts", async () => {
+      const executionContext = getExecutionContext();
+      const session = http2.connect(PROXY_ENDPOINT);
+
+      await executionContext.run({ executionId: "exec-first" }, async () => {
+        session.request({ ":path": "/agent.v1.AgentService/Run" });
+      });
+
+      await executionContext.run({ executionId: "exec-second" }, async () => {
+        session.request({ ":path": "/agent.v1.AgentService/Run" });
+      });
+
+      expect(mock.calls).toHaveLength(2);
+      expect(mock.calls[0].headers).toMatchObject({ "x-stigmer-execution-id": "exec-first" });
+      expect(mock.calls[1].headers).toMatchObject({ "x-stigmer-execution-id": "exec-second" });
+    });
+
+    it("request outside any context on a proxy session has auth but no execution ID", async () => {
+      const executionContext = getExecutionContext();
+      const session = http2.connect(PROXY_ENDPOINT);
+
+      await executionContext.run({ executionId: "exec-scoped" }, async () => {
+        session.request({ ":path": "/first" });
+      });
+
+      session.request({ ":path": "/second" });
+
+      expect(mock.calls[0].headers).toHaveProperty("x-stigmer-execution-id", "exec-scoped");
+      expect(mock.calls[0].headers).toHaveProperty("x-stigmer-auth", `Bearer ${STIGMER_TOKEN}`);
+      expect(mock.calls[1].headers).not.toHaveProperty("x-stigmer-execution-id");
+      expect(mock.calls[1].headers).toHaveProperty("x-stigmer-auth", `Bearer ${STIGMER_TOKEN}`);
+    });
+  });
+
+  describe("proxy endpoint parsing", () => {
+    it("matches https with explicit port", async () => {
+      const mock = createMockConnect();
+      http2.connect = mock.mockConnect;
+      installHttp2Interceptor({ proxyEndpoint: "https://proxy.example.com:9443", stigmerToken: STIGMER_TOKEN });
+
+      const executionContext = getExecutionContext();
+      await executionContext.run({ executionId: "exec-port" }, async () => {
+        const session = http2.connect("https://proxy.example.com:9443");
+        session.request({});
+      });
+
+      expect(mock.calls[0].headers).toHaveProperty("x-stigmer-execution-id", "exec-port");
+    });
+
+    it("matches https with default port (443)", async () => {
+      const mock = createMockConnect();
+      http2.connect = mock.mockConnect;
+      installHttp2Interceptor({ proxyEndpoint: "https://proxy.example.com", stigmerToken: STIGMER_TOKEN });
+
+      const executionContext = getExecutionContext();
+      await executionContext.run({ executionId: "exec-default-port" }, async () => {
+        const session = http2.connect("https://proxy.example.com");
+        session.request({});
+      });
+
+      expect(mock.calls[0].headers).toHaveProperty("x-stigmer-execution-id", "exec-default-port");
+    });
+
+    it("matches http with explicit port", async () => {
+      const mock = createMockConnect();
+      http2.connect = mock.mockConnect;
+      installHttp2Interceptor({ proxyEndpoint: "http://localhost:9090", stigmerToken: STIGMER_TOKEN });
+
+      const executionContext = getExecutionContext();
+      await executionContext.run({ executionId: "exec-http" }, async () => {
+        const session = http2.connect("http://localhost:9090");
+        session.request({});
+      });
+
+      expect(mock.calls[0].headers).toHaveProperty("x-stigmer-execution-id", "exec-http");
+    });
+
+    it("does not match when port differs", async () => {
+      const mock = createMockConnect();
+      http2.connect = mock.mockConnect;
+      installHttp2Interceptor({ proxyEndpoint: "https://proxy.example.com:8443", stigmerToken: STIGMER_TOKEN });
+
+      const executionContext = getExecutionContext();
+      await executionContext.run({ executionId: "exec-wrong-port" }, async () => {
+        const session = http2.connect("https://proxy.example.com:9999");
+        session.request({});
+      });
+
+      expect(mock.calls[0].headers).not.toHaveProperty("x-stigmer-execution-id");
+    });
+  });
+
+  describe("updateHttp2InterceptorToken", () => {
+    let mock: ReturnType<typeof createMockConnect>;
+
+    beforeEach(() => {
+      mock = createMockConnect();
+      http2.connect = mock.mockConnect;
+      installHttp2Interceptor({ proxyEndpoint: PROXY_ENDPOINT, stigmerToken: STIGMER_TOKEN });
+    });
+
+    it("subsequent requests use the updated token", () => {
+      const session = http2.connect(PROXY_ENDPOINT);
+      session.request({ ":path": "/agent.v1.AgentService/Run" });
+
+      expect(mock.calls[0].headers).toHaveProperty("x-stigmer-auth", `Bearer ${STIGMER_TOKEN}`);
+
+      const refreshedToken = "refreshed-stigmer-jwt-token";
+      updateHttp2InterceptorToken(refreshedToken);
+
+      session.request({ ":path": "/agent.v1.AgentService/Run" });
+
+      expect(mock.calls[1].headers).toHaveProperty("x-stigmer-auth", `Bearer ${refreshedToken}`);
+    });
+
+    it("new sessions after token update use the updated token", () => {
+      updateHttp2InterceptorToken("new-token-value");
+
+      const session = http2.connect(PROXY_ENDPOINT);
+      session.request({ ":path": "/aiserver.v1.AnalyticsService/BootstrapStatsig" });
+
+      expect(mock.calls[0].headers).toHaveProperty("x-stigmer-auth", "Bearer new-token-value");
+    });
+
+    it("is a no-op when interceptor is not installed", () => {
+      uninstallHttp2Interceptor();
+      // Should not throw
+      updateHttp2InterceptorToken("orphan-token");
+
+      const session = http2.connect(PROXY_ENDPOINT);
+      session.request({ ":path": "/test" });
+
+      expect(mock.calls[0].headers).not.toHaveProperty("x-stigmer-auth");
+    });
+  });
+
+  describe("assertHttp2ConnectPatched", () => {
+    // The node:http2 ESM namespace is a one-time, process-global snapshot taken
+    // at the module's FIRST `import` (see header comment in http2-interceptor.ts
+    // and CASE A/B in the probe). That makes the positive "configured + in-sync"
+    // path impossible to assert deterministically inside a shared test process
+    // — it is guaranteed by load order (interceptor installed before connect-node
+    // imports node:http2) and exercised by the boot guard in the runner
+    // factories. Here we cover the two deterministic contracts: it is a no-op
+    // when unconfigured (no import, so it never freezes the facade), and it
+    // throws when the frozen facade is out of sync with the patched connect.
+
+    it("resolves without throwing (and without importing node:http2) when unconfigured", async () => {
+      uninstallHttp2Interceptor();
+      await expect(assertHttp2ConnectPatched()).resolves.toBeUndefined();
+    });
+
+    it("throws when the ESM facade is out of sync with the patched connect (load-order regression)", async () => {
+      // Freeze the ESM facade to the pre-patch connect, simulating connect-node
+      // importing node:http2 before installHttp2Interceptor() ran.
+      await import("node:http2");
+
+      const mock = createMockConnect();
+      http2.connect = mock.mockConnect;
+      installHttp2Interceptor({ proxyEndpoint: PROXY_ENDPOINT, stigmerToken: STIGMER_TOKEN });
+
+      await expect(assertHttp2ConnectPatched()).rejects.toThrow(
+        /node:http2 ESM facade is unpatched/,
+      );
+    });
+  });
+});