@stigmer/runner 3.4.1 → 3.5.0

package/src/activities/__tests__/attach-session.test.ts

@@ -0,0 +1,133 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import type { Config } from "../../config.js";
+import type { PoolAttachTarget } from "../../pool-member.js";
+
+/**
+ * The activity factory constructs a real StigmerClient; mock the module so no
+ * transport is opened and the exchange call is observable.
+ */
+const getRunnerScopedToken = vi.fn();
+vi.mock("../../client/stigmer-client.js", () => ({
+  StigmerClient: class {
+    getRunnerScopedToken = getRunnerScopedToken;
+  },
+}));
+
+import { createAttachSessionActivities } from "../attach-session.js";
+import {
+  registerPoolMemberContext,
+  clearPoolMemberContext,
+} from "../../pool-member.js";
+
+const config = {
+  stigmerBackendEndpoint: "http://localhost:7234",
+  stigmerToken: "pool-tok",
+} as unknown as Config;
+
+function fakeManager(): PoolAttachTarget & {
+  addSession: ReturnType<typeof vi.fn>;
+  updateToken: ReturnType<typeof vi.fn>;
+} {
+  return {
+    addSession: vi.fn().mockResolvedValue(undefined),
+    updateToken: vi.fn(),
+  };
+}
+
+describe("attach-session activities", () => {
+  beforeEach(() => {
+    getRunnerScopedToken.mockReset();
+  });
+
+  afterEach(() => {
+    clearPoolMemberContext();
+  });
+
+  describe("outside a pool member (inert state)", () => {
+    it("ProbePoolMember fails fast without a pool context", async () => {
+      const { ProbePoolMember } = createAttachSessionActivities(config);
+      await expect(ProbePoolMember()).rejects.toThrow(/outside a pool member/);
+    });
+
+    it("AttachSession fails fast without a pool context", async () => {
+      const { AttachSession } = createAttachSessionActivities(config);
+      await expect(AttachSession("ses_1")).rejects.toThrow(/outside a pool member/);
+      expect(getRunnerScopedToken).not.toHaveBeenCalled();
+    });
+  });
+
+  describe("ProbePoolMember", () => {
+    it("returns the member id as proof of polling", async () => {
+      registerPoolMemberContext({
+        memberId: "pm_1", poolToken: "pool-tok", manager: fakeManager(),
+      });
+      const { ProbePoolMember } = createAttachSessionActivities(config);
+
+      await expect(ProbePoolMember()).resolves.toBe("pm_1");
+    });
+  });
+
+  describe("AttachSession", () => {
+    it("exchanges with the pool credential, applies the session token, then adds the session", async () => {
+      const manager = fakeManager();
+      registerPoolMemberContext({ memberId: "pm_1", poolToken: "pool-tok", manager });
+      getRunnerScopedToken.mockResolvedValue({ token: "session-tok", expiresInSeconds: 90000 });
+      const { AttachSession } = createAttachSessionActivities(config);
+
+      const ack = await AttachSession("ses_1");
+
+      expect(ack).toBe("session:ses_1");
+      expect(getRunnerScopedToken).toHaveBeenCalledWith(
+        { poolClaimSessionId: "ses_1" },
+        "pool-tok",
+      );
+      expect(manager.updateToken).toHaveBeenCalledWith("session-tok");
+      expect(manager.addSession).toHaveBeenCalledWith("ses_1");
+      // The session worker must poll with the session credential already in
+      // place — a reversed order would serve the first activity with the
+      // powerless pool token.
+      expect(manager.updateToken.mock.invocationCallOrder[0]!)
+        .toBeLessThan(manager.addSession.mock.invocationCallOrder[0]!);
+    });
+
+    it("rejects an empty session id", async () => {
+      registerPoolMemberContext({
+        memberId: "pm_1", poolToken: "pool-tok", manager: fakeManager(),
+      });
+      const { AttachSession } = createAttachSessionActivities(config);
+
+      await expect(AttachSession("")).rejects.toThrow(/requires a session id/);
+    });
+
+    it("fails hard when the server mints nothing — a pool token cannot serve session work", async () => {
+      const manager = fakeManager();
+      registerPoolMemberContext({ memberId: "pm_1", poolToken: "pool-tok", manager });
+      getRunnerScopedToken.mockResolvedValue(undefined);
+      const { AttachSession } = createAttachSessionActivities(config);
+
+      await expect(AttachSession("ses_1")).rejects.toThrow(/minted no session token/);
+      expect(manager.updateToken).not.toHaveBeenCalled();
+      expect(manager.addSession).not.toHaveBeenCalled();
+    });
+
+    it("propagates an exchange failure so the control plane discards the member", async () => {
+      const manager = fakeManager();
+      registerPoolMemberContext({ memberId: "pm_1", poolToken: "pool-tok", manager });
+      getRunnerScopedToken.mockRejectedValue(new Error("claim not found"));
+      const { AttachSession } = createAttachSessionActivities(config);
+
+      await expect(AttachSession("ses_1")).rejects.toThrow("claim not found");
+      expect(manager.addSession).not.toHaveBeenCalled();
+    });
+
+    it("propagates a session-worker failure after the token was applied", async () => {
+      const manager = fakeManager();
+      manager.addSession.mockRejectedValue(new Error("worker create failed"));
+      registerPoolMemberContext({ memberId: "pm_1", poolToken: "pool-tok", manager });
+      getRunnerScopedToken.mockResolvedValue({ token: "session-tok" });
+      const { AttachSession } = createAttachSessionActivities(config);
+
+      await expect(AttachSession("ses_1")).rejects.toThrow("worker create failed");
+    });
+  });
+});

package/src/activities/__tests__/discover-mcp-server.test.ts

@@ -283,7 +283,7 @@ describe("DiscoverMcpServer activity", () => {
 
       const result = await discoverMcpServer(
         { mcpServerId: "mcp-123" },
-        { stigmerClient: mockClient as any },
+        { stigmerClient: mockClient as any, transportPosture: "stdio-allowed" },
       );
 
       expect(result.tools).toHaveLength(2);
@@ -295,6 +295,29 @@ describe("DiscoverMcpServer activity", () => {
       expect(result.newToolsFingerprint).toHaveLength(64);
     });
 
+    it("refuses to spawn a stdio server under a forbidding transport posture", async () => {
+      // Discovery spawns the same subprocess an execution would, so a cloud
+      // runner enforces the local-runner-only rule here too — nothing is
+      // spawned before the guard fires.
+      const { discoverMcpServer } = await import("../discover-mcp-server.js");
+      const { McpTransportError } = await import("../../shared/mcp-transport-guard.js");
+
+      const mockClient = makeMockStigmerClient({
+        mcpServer: makeMcpServer({
+          metadata: { slug: "filesystem" },
+          spec: makeStdioSpec("npx", ["-y", "@modelcontextprotocol/server-filesystem"]),
+        }),
+      });
+
+      await expect(
+        discoverMcpServer(
+          { mcpServerId: "mcp-123" },
+          { stigmerClient: mockClient as any, transportPosture: "stdio-forbidden" },
+        ),
+      ).rejects.toThrow(McpTransportError);
+      expect(mockInitializeConnections).not.toHaveBeenCalled();
+    });
+
     it("discovers tools and resource templates from an HTTP server", async () => {
       const { discoverMcpServer } = await import("../discover-mcp-server.js");
 
@@ -317,7 +340,7 @@ describe("DiscoverMcpServer activity", () => {
 
       const result = await discoverMcpServer(
         { mcpServerId: "mcp-456" },
-        { stigmerClient: mockClient as any },
+        { stigmerClient: mockClient as any, transportPosture: "stdio-allowed" },
       );
 
       expect(result.tools).toHaveLength(1);
@@ -338,7 +361,7 @@ describe("DiscoverMcpServer activity", () => {
       });
 
       await expect(
-        discoverMcpServer({ mcpServerId: "mcp-bad" }, { stigmerClient: mockClient as any }),
+        discoverMcpServer({ mcpServerId: "mcp-bad" }, { stigmerClient: mockClient as any, transportPosture: "stdio-allowed" }),
       ).rejects.toThrow("not found or has no spec");
     });
 
@@ -353,7 +376,7 @@ describe("DiscoverMcpServer activity", () => {
       });
 
       await expect(
-        discoverMcpServer({ mcpServerId: "mcp-noconfig" }, { stigmerClient: mockClient as any }),
+        discoverMcpServer({ mcpServerId: "mcp-noconfig" }, { stigmerClient: mockClient as any, transportPosture: "stdio-allowed" }),
       ).rejects.toThrow("no valid server type configured");
     });
 
@@ -381,7 +404,7 @@ describe("DiscoverMcpServer activity", () => {
 
       const result = await discoverMcpServer(
         { mcpServerId: "mcp-env", executionContextId: "ctx-abc" },
-        { stigmerClient: mockClient as any },
+        { stigmerClient: mockClient as any, transportPosture: "stdio-allowed" },
       );
 
       expect(result.tools).toEqual([]);
@@ -404,7 +427,7 @@ describe("DiscoverMcpServer activity", () => {
 
       await discoverMcpServer(
         { mcpServerId: "mcp-no-env" },
-        { stigmerClient: mockClient as any },
+        { stigmerClient: mockClient as any, transportPosture: "stdio-allowed" },
       );
 
       expect(mockClient.getExecutionContextByExecutionId).not.toHaveBeenCalled();
@@ -430,7 +453,7 @@ describe("DiscoverMcpServer activity", () => {
 
       const result = await discoverMcpServer(
         { mcpServerId: "mcp-no-res" },
-        { stigmerClient: mockClient as any },
+        { stigmerClient: mockClient as any, transportPosture: "stdio-allowed" },
       );
 
       expect(result.tools).toHaveLength(1);
@@ -464,7 +487,7 @@ describe("DiscoverMcpServer activity", () => {
 
       const result = await discoverMcpServer(
         { mcpServerId: "mcp-existing" },
-        { stigmerClient: mockClient as any },
+        { stigmerClient: mockClient as any, transportPosture: "stdio-allowed" },
       );
 
       expect(result.previousToolsFingerprint).not.toBe("");
@@ -499,7 +522,7 @@ describe("DiscoverMcpServer activity", () => {
 
       const result = await discoverMcpServer(
         { mcpServerId: "mcp-fp" },
-        { stigmerClient: mockClient as any },
+        { stigmerClient: mockClient as any, transportPosture: "stdio-allowed" },
       );
 
       const expected = toolsFingerprint(result.tools);
@@ -522,7 +545,7 @@ describe("DiscoverMcpServer activity", () => {
 
       const result = await discoverMcpServer(
         { mcpServerId: "mcp-empty" },
-        { stigmerClient: mockClient as any },
+        { stigmerClient: mockClient as any, transportPosture: "stdio-allowed" },
       );
 
       expect(result.newToolsFingerprint).toBe("");
@@ -541,7 +564,7 @@ describe("DiscoverMcpServer activity", () => {
       mockInitializeConnections.mockRejectedValue(new Error("Connection refused"));
 
       await expect(
-        discoverMcpServer({ mcpServerId: "mcp-fail" }, { stigmerClient: mockClient as any }),
+        discoverMcpServer({ mcpServerId: "mcp-fail" }, { stigmerClient: mockClient as any, transportPosture: "stdio-allowed" }),
       ).rejects.toThrow("Connection refused");
 
       expect(mockClose).toHaveBeenCalled();

package/src/activities/attach-session.ts

@@ -0,0 +1,112 @@
+/**
+ * Warm-pool attach activities.
+ *
+ * Registered in the standard activity set (both runner and runner-manager
+ * copies) but functional only inside a pool member: they read the pool
+ * context registered by the pool boot path (see pool-member.ts) and fail
+ * fast everywhere else. The control plane schedules them on the member's
+ * control queue `sandbox:{memberId}`, which only a pool member ever polls.
+ *
+ * Activity contracts (invoked by the cloud ClaimPoolMemberWorkflow):
+ *
+ *   Name:   "ProbePoolMember"
+ *   Input:  none
+ *   Output: string (the member id — proof the member is booted and polling)
+ *
+ *   Name:   "AttachSession"
+ *   Input:  (sessionId: string)
+ *   Output: string (the session task queue now being polled)
+ *
+ * AttachSession is the claim hand-off: exchange the member's pool_sandbox
+ * credential for the session's sandbox token (the control plane authorizes
+ * against the claim record), push the session token to every credential sink
+ * via the manager, then start the session worker. From the returned ack
+ * onward the member serves `session:{sessionId}` like any provisioned
+ * sandbox. The control worker keeps polling its (now permanently idle)
+ * control queue — the claim deleted the pool row, so nothing dispatches
+ * there again, and the worker disappears with the next pod restart; tearing
+ * down the worker an activity is running on would deadlock the teardown.
+ */
+
+import type { Config } from "../config.js";
+import { StigmerClient } from "../client/stigmer-client.js";
+import { activityStarted, activityFinished } from "../idle-watchdog.js";
+import { getPoolMemberContext } from "../pool-member.js";
+import { TimingRecorder, emitTimingLog } from "../shared/cold-start-timing.js";
+
+export function createAttachSessionActivities(config: Config) {
+  const client = new StigmerClient({
+    endpoint: config.stigmerBackendEndpoint,
+    token: config.stigmerToken,
+    tokenRef: config.stigmerTokenRef,
+    runnerTokenRef: config.stigmerRunnerTokenRef,
+  });
+
+  return {
+    ProbePoolMember: async (): Promise<string> => {
+      activityStarted();
+      try {
+        const pool = getPoolMemberContext();
+        if (!pool) {
+          throw new Error(
+            "ProbePoolMember invoked outside a pool member (no pool context registered)",
+          );
+        }
+        return pool.memberId;
+      } finally {
+        activityFinished();
+      }
+    },
+
+    AttachSession: async (sessionId: string): Promise<string> => {
+      activityStarted();
+      const timing = new TimingRecorder();
+      try {
+        const pool = getPoolMemberContext();
+        if (!pool) {
+          throw new Error(
+            "AttachSession invoked outside a pool member (no pool context registered)",
+          );
+        }
+        if (!sessionId) {
+          throw new Error("AttachSession requires a session id");
+        }
+
+        const scoped = await client.getRunnerScopedToken(
+          { poolClaimSessionId: sessionId },
+          pool.poolToken,
+        );
+        timing.mark("exchange_token");
+        if (!scoped) {
+          // Unlike the desktop exchange, there is no credential to fall back
+          // to: a pool token cannot serve session work, so an empty mint is a
+          // hard failure and the control plane discards this member.
+          throw new Error(
+            "control plane minted no session token for the pool claim " +
+              `(member=${pool.memberId}, session=${sessionId})`,
+          );
+        }
+
+        pool.manager.updateToken(scoped.token);
+        timing.mark("token_applied");
+
+        await pool.manager.addSession(sessionId);
+        timing.mark("session_worker_added");
+
+        const taskQueue = `session:${sessionId}`;
+        emitTimingLog("pool_attach", {
+          pool_member_id: pool.memberId,
+          session_id: sessionId,
+          task_queue: taskQueue,
+        }, timing);
+        console.log(
+          `[attach-session] Pool member ${pool.memberId} attached to session ` +
+            `${sessionId} (queue=${taskQueue})`,
+        );
+        return taskQueue;
+      } finally {
+        activityFinished();
+      }
+    },
+  };
+}

package/src/activities/discover-mcp-server.ts

@@ -24,6 +24,11 @@ import { activityStarted, activityFinished } from "../idle-watchdog.js";
 import { StigmerClient } from "../client/stigmer-client.js";
 import { mcpServerToResolved } from "../shared/mcp-resolver.js";
 import { toMcpClientConfig } from "../shared/mcp-manager.js";
+import {
+  assertTransportAllowed,
+  resolveMcpTransportPosture,
+  type McpTransportPosture,
+} from "../shared/mcp-transport-guard.js";
 import { detectOAuthChallenge } from "../shared/mcp-oauth-detect.js";
 import { withTimeout } from "../shared/with-timeout.js";
 import type { McpServer } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
@@ -205,6 +210,14 @@ export function injectPlatformEnv(
 
 export interface DiscoverDeps {
   stigmerClient: StigmerClient;
+  /**
+   * Whether stdio servers may be spawned here (derive via
+   * resolveMcpTransportPosture(config.mode)). Discovery spawns the same
+   * subprocess an execution would, so it enforces the same
+   * local-runner-only rule — a cloud runner refuses stdio even for
+   * tool enumeration.
+   */
+  transportPosture: McpTransportPosture;
 }
 
 export async function discoverMcpServer(
@@ -246,6 +259,8 @@ export async function discoverMcpServer(
     );
   }
 
+  assertTransportAllowed(resolved.slug, resolved.connectionType, deps.transportPosture);
+
   const connectionConfig = toMcpClientConfig([resolved]);
   const { tools, resourceTemplates } = await connectAndDiscover(
     slug,
@@ -435,7 +450,10 @@ export function createDiscoverMcpServerActivities(config: Config) {
     ): Promise<DiscoverMcpServerOutput> => {
       activityStarted();
       try {
-        return await discoverMcpServer(input, { stigmerClient });
+        return await discoverMcpServer(input, {
+          stigmerClient,
+          transportPosture: resolveMcpTransportPosture(config.mode),
+        });
       } finally {
         activityFinished();
       }

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

@@ -171,6 +171,83 @@ describe("fetch-interceptor", () => {
     });
   });
 
+  describe("cursor_models_fetch timing", () => {
+    beforeEach(() => {
+      installFetchInterceptor({ proxyEndpoint: PROXY_ENDPOINT, stigmerToken: STIGMER_TOKEN });
+    });
+
+    /**
+     * Collect emitted `cursor_models_fetch` timing lines from a console.log
+     * spy, ignoring every other log line (install banner, warnings, other
+     * timelines).
+     */
+    function timingLines(spy: ReturnType<typeof vi.spyOn>): Array<Record<string, unknown>> {
+      const lines: Array<Record<string, unknown>> = [];
+      for (const call of spy.mock.calls) {
+        if (typeof call[0] !== "string") continue;
+        try {
+          const parsed = JSON.parse(call[0]) as Record<string, unknown>;
+          if (parsed.stigmer_timing === "cursor_models_fetch") lines.push(parsed);
+        } catch {
+          // Not a JSON log line — ignore.
+        }
+      }
+      return lines;
+    }
+
+    it("emits one timing line for a Cursor-domain /v1/models call, carrying execution_id", async () => {
+      const spy = vi.spyOn(console, "log").mockImplementation(() => {});
+      const executionContext = getExecutionContext();
+
+      await executionContext.run({ executionId: "exec-models-1" }, async () => {
+        await globalThis.fetch("https://api.cursor.com/v1/models", { method: "GET" });
+      });
+
+      const lines = timingLines(spy);
+      expect(lines).toHaveLength(1);
+      expect(lines[0]!.execution_id).toBe("exec-models-1");
+      expect(lines[0]!.http_status).toBe(200);
+      expect(lines[0]!.total_ms).toBeTypeOf("number");
+      const segments = lines[0]!.segments as Array<{ name: string }>;
+      expect(segments.map((s) => s.name)).toEqual(["models_fetch"]);
+    });
+
+    it("emits for the proxy-endpoint-targeted /v1/models form too", async () => {
+      const spy = vi.spyOn(console, "log").mockImplementation(() => {});
+
+      await globalThis.fetch(`${PROXY_ENDPOINT}/v1/models`, { method: "GET" });
+
+      // The fetch itself was rewritten through the proxy path AND timed.
+      expect(calls[0]!.url).toBe(
+        `${PROXY_ENDPOINT}/v1/proxy/cursor/api.cursor.com/v1/models`,
+      );
+      expect(timingLines(spy)).toHaveLength(1);
+    });
+
+    it("omits execution_id (rather than fabricating one) outside an execution context", async () => {
+      const spy = vi.spyOn(console, "log").mockImplementation(() => {});
+
+      await globalThis.fetch("https://api.cursor.com/v1/models", { method: "GET" });
+
+      const lines = timingLines(spy);
+      expect(lines).toHaveLength(1);
+      // undefined context values are dropped by JSON.stringify.
+      expect("execution_id" in lines[0]!).toBe(false);
+    });
+
+    it("does NOT emit for other rewritten REST paths", async () => {
+      const spy = vi.spyOn(console, "log").mockImplementation(() => {});
+
+      await globalThis.fetch(
+        "https://api2.cursor.sh/auth/exchange_user_api_key",
+        { method: "POST" },
+      );
+
+      expect(calls).toHaveLength(1);
+      expect(timingLines(spy)).toHaveLength(0);
+    });
+  });
+
   describe("passthrough (no interception)", () => {
     beforeEach(() => {
       installFetchInterceptor({ proxyEndpoint: PROXY_ENDPOINT, stigmerToken: STIGMER_TOKEN });

package/src/activities/execute-cursor/__tests__/sdk-warmup.test.ts

@@ -0,0 +1,45 @@
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { warmCursorSdkStateStores } from "../sdk-warmup.js";
+
+const sdkMock = vi.hoisted(() => ({
+  createAgentPlatform: vi.fn(),
+}));
+
+vi.mock("@cursor/sdk", () => ({
+  createAgentPlatform: sdkMock.createAgentPlatform,
+}));
+
+describe("warmCursorSdkStateStores", () => {
+  beforeEach(() => {
+    sdkMock.createAgentPlatform.mockReset();
+  });
+
+  it("constructs a throwaway platform on a temp-dir state root", async () => {
+    sdkMock.createAgentPlatform.mockResolvedValue({});
+
+    const result = await warmCursorSdkStateStores();
+
+    expect(result.warmed).toBe(true);
+    expect(result.error).toBeUndefined();
+    expect(result.durationMs).toBeGreaterThanOrEqual(0);
+
+    expect(sdkMock.createAgentPlatform).toHaveBeenCalledTimes(1);
+    const options = sdkMock.createAgentPlatform.mock.calls[0]![0] as {
+      workspaceRef: string;
+      stateRoot: string;
+    };
+    // The synthetic ref must never collide with real session platforms,
+    // which are keyed `stigmer-session:{sessionId}`.
+    expect(options.workspaceRef).toBe("stigmer-warm:boot");
+    expect(options.stateRoot).toContain("cursor-sdk-warm-");
+  });
+
+  it("never throws — a failed warm-up reports instead of crashing the member", async () => {
+    sdkMock.createAgentPlatform.mockRejectedValue(new Error("sqlite binding missing"));
+
+    const result = await warmCursorSdkStateStores();
+
+    expect(result.warmed).toBe(false);
+    expect(result.error).toBe("sqlite binding missing");
+  });
+});

package/src/activities/execute-cursor/connect-backfill.ts

@@ -12,6 +12,7 @@
 import type { McpResolutionResult } from "./mcp-resolver.js";
 import { toCursorMcpConfig } from "./mcp-resolver.js";
 import type { StigmerClient } from "../../client/stigmer-client.js";
+import type { McpTransportPosture } from "../../shared/mcp-transport-guard.js";
 import type { McpServerUsage } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
 import { backfillMcpServersIfNeeded as sharedBackfill } from "../../shared/connect-backfill.js";
 
@@ -25,6 +26,7 @@ export async function backfillMcpServersIfNeeded(
   usages: McpServerUsage[],
   envVars: Record<string, string>,
   org: string,
+  transportPosture: McpTransportPosture,
   onHeartbeat?: () => void,
   secretKeys?: ReadonlySet<string>,
 ): Promise<McpResolutionResult> {
@@ -34,6 +36,7 @@ export async function backfillMcpServersIfNeeded(
     usages,
     envVars,
     org,
+    transportPosture,
     onHeartbeat,
     secretKeys,
   );

package/src/activities/execute-cursor/fetch-interceptor.ts

@@ -17,6 +17,18 @@
 
 import { AsyncLocalStorage } from "node:async_hooks";
 
+import { TimingRecorder, emitTimingLog } from "../../shared/cold-start-timing.js";
+
+/**
+ * The one REST path worth timing individually: the Cursor SDK calls
+ * GET /v1/models inside Agent.create/Agent.resume purely to validate the
+ * model id, and in proxy mode that is a runner → Stigmer → Cursor double
+ * hop sitting inside the resolve_agent setup segment (issue #209). The
+ * emitted `cursor_models_fetch` timeline splits that network cost out of
+ * the segment total without touching the SDK.
+ */
+const MODELS_PATH = "/v1/models";
+
 const CURSOR_DOMAINS = [
   "api2.cursor.sh",
   "api.cursor.com",
@@ -246,10 +258,15 @@ async function fetchWithUrlRewrite(
   const rewrittenUrl = rewriteUrl(url, config.proxyEndpoint);
   const rewrittenInit = replaceAuth(init, config);
   const path = extractPath(url);
+  const modelsTiming = path === MODELS_PATH ? new TimingRecorder() : undefined;
 
   try {
     const response = await originalFetch(rewrittenUrl, rewrittenInit);
 
+    if (modelsTiming) {
+      emitModelsFetchTiming(modelsTiming, config, response.status);
+    }
+
     if (!response.ok) {
       if (isNonCriticalPath(path)) {
         console.debug(
@@ -272,6 +289,28 @@ async function fetchWithUrlRewrite(
   }
 }
 
+/**
+ * Emit the `cursor_models_fetch` timeline for one proxied GET /v1/models.
+ *
+ * `execution_id` comes from the AsyncLocalStorage execution context — the
+ * whole ExecuteCursor activity runs inside runWithExecutionContext, so the
+ * value is correct even with concurrent activities on one runner process.
+ * `recordTimingMetric` deliberately ignores this event (no mapped OTel
+ * instrument): it is a forensic stdout line only, joined to the
+ * execution_setup timeline by execution_id in cold-start-baseline analysis.
+ */
+function emitModelsFetchTiming(
+  timing: TimingRecorder,
+  config: ProxyConfig,
+  httpStatus: number,
+): void {
+  timing.mark("models_fetch");
+  emitTimingLog("cursor_models_fetch", {
+    execution_id: executionContext.getStore()?.executionId ?? config.executionId,
+    http_status: httpStatus,
+  }, timing);
+}
+
 /**
  * Connect-RPC-via-fetch path: inject x-stigmer-auth for BiDi proxy
  * authentication without rewriting the URL or replacing authorization.