@stigmer/runner 3.15.3-dev.20260914121148 → 3.16.0

package/src/activities/execute-cursor/__test-utils__/hermetic-cursor.ts

@@ -42,6 +42,18 @@
  * the SDK double (`ScriptedSdkOptions`); an SDK-side cancel or a mid-stream
  * wedge as an `effect` step on the run. Nothing here is a switch in production
  * code — every knob is a value the production path already reads.
+ *
+ * Two postures, two entries, one turn runner. `beginCursorScenario` is the
+ * hermetic posture: the SDK doubled by the scenario file's `vi.mock`, the
+ * clock scripted, goldens byte-stable. `beginLiveCursorScenario` is the live
+ * posture (#1097's live-run gate): the scenario file mocks ONLY the
+ * client, the real `@cursor/sdk` runs under the real activity on the real
+ * clock with a real member key, and what the activity persists is read back
+ * from the same record. A live scenario therefore has no `sdk` and no `clock`
+ * — the type says which posture a file is in — and `runCursorTurn` reads only
+ * what both have. The registry fixture's `live` pass-through and the
+ * environment's `eventRecordingDir` are the live posture's two other
+ * seams, each on the module that owns the concern.
  */
 
 import { execFileSync } from "node:child_process";
@@ -216,20 +228,27 @@ export function resetCursorModuleState(): void {
   _resetRegistryCache();
 }
 
-export interface CursorScenario {
+/** What both postures share: the environment, the record the activity persists into, the runner's `Config`. */
+export interface CursorScenarioBase {
   readonly env: HermeticEnvironment;
-  readonly clock: ScriptedClock;
   readonly record: ExecutionRecord;
-  readonly sdk: ScriptedCursorSdk;
   /** The runner this scenario runs on: the OSS posture plus the scenario's knobs. */
   readonly config: Config;
 }
 
-export interface CursorScenarioOptions {
-  readonly env: HermeticEnvironment;
+/** The hermetic posture: the SDK double and the scripted clock beside the shared three. */
+export interface CursorScenario extends CursorScenarioBase {
   readonly clock: ScriptedClock;
+  readonly sdk: ScriptedCursorSdk;
+}
+
+/** The live posture (header): the shared three and nothing doubled but the client. */
+export type LiveCursorScenario = CursorScenarioBase;
+
+/** The options both postures take. */
+interface CursorScenarioBaseOptions {
+  readonly env: HermeticEnvironment;
   readonly record: ExecutionRecord;
-  readonly sdk: ScriptedSdkOptions;
   /**
    * Control-plane facets the scenario opts INTO, or faults it injects, over
    * the record's everyday answers (`ExecutionRecord.client`): a rejecting
@@ -245,21 +264,50 @@ export interface CursorScenarioOptions {
   readonly config?: Partial<Config>;
 }
 
-/** Bind the record and the SDK for a scenario; resets the harness caches first. */
-export function beginCursorScenario(options: CursorScenarioOptions): CursorScenario {
+export interface CursorScenarioOptions extends CursorScenarioBaseOptions {
+  readonly clock: ScriptedClock;
+  readonly sdk: ScriptedSdkOptions;
+}
+
+export interface LiveCursorScenarioOptions extends CursorScenarioBaseOptions {
+  /** The real member key the real SDK authenticates with; becomes `config.cursorApiKey`. */
+  readonly apiKey: string;
+}
+
+/**
+ * What every scenario begins with: the harness caches dropped, the record
+ * bound as the control plane the activity will talk to, the OSS `Config`
+ * over the environment with the scenario's knobs laid on top.
+ */
+function beginScenarioBase(options: CursorScenarioBaseOptions): CursorScenarioBase {
   resetCursorModuleState();
-  const sdk = new ScriptedCursorSdk(options.sdk);
-  bindScriptedSdk(sdk);
   bindHermeticClient(options.record.client(options.clientOverrides));
   return {
     env: options.env,
-    clock: options.clock,
     record: options.record,
-    sdk,
     config: { ...hermeticCursorConfig(options.env), ...options.config },
   };
 }
 
+/** Bind the record and the SDK double for a hermetic scenario; resets the harness caches first. */
+export function beginCursorScenario(options: CursorScenarioOptions): CursorScenario {
+  const base = beginScenarioBase(options);
+  const sdk = new ScriptedCursorSdk(options.sdk);
+  bindScriptedSdk(sdk);
+  return { ...base, clock: options.clock, sdk };
+}
+
+/**
+ * Bind the record for a live scenario; resets the harness caches first. No
+ * SDK double is built or bound — the scenario file must NOT mock `@cursor/sdk`
+ * — and no clock is installed. The key lands on the `Config` exactly where
+ * the OSS runner's direct mode reads it (`turn-setup.ts`, `config.cursorApiKey`).
+ */
+export function beginLiveCursorScenario(options: LiveCursorScenarioOptions): LiveCursorScenario {
+  const base = beginScenarioBase(options);
+  return { ...base, config: { ...base.config, cursorApiKey: options.apiKey } };
+}
+
 export interface CursorTurnOptions {
   /** Empty for a first invocation; the agent id for a HITL reinvocation. */
   readonly threadId?: string;
@@ -269,13 +317,15 @@ export interface CursorTurnOptions {
 }
 
 /**
- * Run ONE `ExecuteCursor` invocation for the scenario: the real Cursor
- * adapter under the real turn runtime, as the composition roots wire them.
- * Built per invocation (the registry constructs its client, which is the one
- * bound at `beginCursorScenario`; the adapter boots on the scenario's config).
+ * Run ONE `ExecuteCursor` invocation for the scenario — either posture: the
+ * real Cursor adapter under the real turn runtime, as the composition roots
+ * wire them. Built per invocation (the registry constructs its client, which
+ * is the one bound at `begin*CursorScenario`; the adapter boots on the
+ * scenario's config). Reads only the record and the config, which both
+ * postures have.
  */
 export async function runCursorTurn(
-  scenario: CursorScenario,
+  scenario: CursorScenarioBase,
   options: CursorTurnOptions = {},
 ): Promise<ActivityInvocation> {
   // Imported lazily so the scenario file's `vi.mock` declarations are in

package/src/activities/execute-cursor/__test-utils__/scripted-agent.ts

@@ -15,7 +15,12 @@
  * So a turn is a SCRIPT of ordered steps, one of four kinds:
  *
  *  - `event(SDKMessage)`     — yielded from `stream()`
- *  - `delta(update)`         — fired through `onDelta` (usage, `turn-ended`)
+ *  - `delta(update)`         — fired through `onDelta`: any `InteractionUpdate`
+ *                              (the `turn-ended` usage the loop prices; the
+ *                              tool-call timings, shell output and completion
+ *                              status the transcript folds — #1097 widened
+ *                              the step from `turn-ended` alone so the delta
+ *                              channel has an end-to-end net)
  *  - `effect(fn)`            — the side effect the SDK would have performed
  *                              (run the real hook, write a workspace file,
  *                              cancel the activity from the outside)
@@ -25,10 +30,10 @@
  * (`ScriptStep`, driven in order), applied to the SDK's event surface.
  *
  * Typing: `SDKMessage`, `Run`, `RunResult`, `SDKAgent` and the delta channel's
- * `TurnEndedUpdate` are the SDK's own types (`@cursor/sdk` 1.0.31, concrete in
- * `messages.d.ts` / `run.d.ts` / `agent.d.ts` / the vendored `delta-types`),
+ * `InteractionUpdate` are the SDK's own types (`@cursor/sdk` 1.0.31, concrete
+ * in `messages.d.ts` / `run.d.ts` / `agent.d.ts` / the vendored `delta-types`),
  * so a script that drifts from the real event shape fails `tsc`. (At 1.0.13
- * the delta types resolved to `any` and the one delta this double emits was
+ * the delta types resolved to `any` and the one delta this double emitted was
  * typed locally; stigmer/stigmer#1053 closed that gap.)
  *
  * Cancellation: `run.cancel()` is how the harness stops a turn (first denial,
@@ -48,6 +53,7 @@
 import type {
   AgentUsage,
   GetUsageOptions,
+  InteractionUpdate,
   ModelSelection,
   Run,
   RunOperation,
@@ -73,7 +79,7 @@ export interface EffectContext {
 
 export type ScriptStep =
   | { readonly kind: "event"; readonly event: SDKMessage }
-  | { readonly kind: "delta"; readonly update: TurnEndedUpdate }
+  | { readonly kind: "delta"; readonly update: InteractionUpdate }
   | { readonly kind: "effect"; readonly label: string; readonly run: (ctx: EffectContext) => void | Promise<void> }
   | { readonly kind: "result"; readonly result: Omit<RunResult, "id"> };
 
@@ -85,6 +91,10 @@ export const step = {
   event(event: SDKMessage): ScriptStep {
     return { kind: "event", event };
   },
+  /** Any delta the SDK fires through `onDelta` between stream events: tool-call timings, shell output, a completion's status. */
+  delta(update: InteractionUpdate): ScriptStep {
+    return { kind: "delta", update };
+  },
   /** The `turn-ended` delta `turn-stream.ts` prices; the SDK's shape, all four counts stated. */
   turnEnded(usage: NonNullable<TurnEndedUpdate["usage"]>): ScriptStep {
     return { kind: "delta", update: { type: "turn-ended", usage } };
@@ -130,6 +140,10 @@ export function sdkEvents(agentId: string, runId: string) {
     status(status: "CREATING" | "RUNNING" | "FINISHED" | "ERROR" | "CANCELLED" | "EXPIRED", message?: string): SDKMessage {
       return { type: "status", ...base, status, message };
     },
+    /** The SDK's `task` event: a status line about the run in the agent's own voice, which the transcript shows as a SYSTEM message. */
+    task(text: string, status?: string): SDKMessage {
+      return { type: "task", ...base, text, status };
+    },
   };
 }
 

package/src/activities/execute-cursor/__tests__/approval-gate.test.ts

@@ -1,5 +1,6 @@
 /**
- * @regression file-hitl-phase0 — pins file-edit HITL fix #6 (see _projects/2026-06/20260630.01.file-change-hitl-redesign/tasks/T01_3_regression-manifest.md)
+ * @regression file-hitl-phase0 — pins content-exact approval identity: approving
+ * one edit never lets a DIFFERENT edit to the same path ride the grant.
  *
  * Unit tests for the Cursor-harness HITL approval gate logic.
  *

package/src/activities/execute-cursor/__tests__/approval-state.test.ts

@@ -1,5 +1,6 @@
 /**
- * @regression file-hitl-phase0 — pins file-edit HITL fix #6 (see _projects/2026-06/20260630.01.file-change-hitl-redesign/tasks/T01_3_regression-manifest.md)
+ * @regression file-hitl-phase0 — pins content-exact approval identity: approving
+ * one edit never lets a DIFFERENT edit to the same path ride the grant.
  *
  * Resume-grant identity round-trip — the H1 lock.
  *
@@ -21,7 +22,7 @@
  *  - the resume grant via {@link buildApprovalGrants} -> parseArgs(argsPreview)
  *    (the JSON-string preview only).
  * They agree today only because both derive from the same stream `event.args`.
- * This suite drives the REAL stream path ({@link buildToolCallProto}) so any
+ * This suite drives the REAL stream path (the translator into the builder) so any
  * future change that lets the dual path diverge fails here, loudly, per category.
  *
  * Deterministic; no Cursor API key, no bash. The hook-side half of the equality
@@ -42,11 +43,9 @@ import {
 } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import type { SDKMessage } from "@cursor/sdk";
 
-import {
-  buildToolCallProto,
-  reconcileDeniedToolCalls,
-  toolCallIdentityToken,
-} from "../message-translator.js";
+import { reconcileDeniedToolCalls } from "../boundary-rows.js";
+import { builderOver, foldCursorEvents } from "../__test-utils__/fold.js";
+import { toolCallIdentityToken } from "../approval-state.js";
 import {
   buildApprovalGrants,
   buildApprovalState,
@@ -96,7 +95,7 @@ function mcpEvent(
  * and return the two identities that must be equal: the token the hook recorded
  * when it denied the gated call, and the grant token a resume mints after the
  * user approves it. Mirrors the activity's real sequence:
- *   buildToolCallProto (stream) -> deny overlay (reconcileDeniedToolCalls) ->
+ *   translator + builder (stream) -> deny overlay (reconcileDeniedToolCalls) ->
  *   persist APPROVE -> reconstructAdjudicatedApprovals -> buildApprovalGrants.
  */
 async function roundTrip(event: Extract<SDKMessage, { type: "tool_call" }>): Promise<{
@@ -105,7 +104,7 @@ async function roundTrip(event: Extract<SDKMessage, { type: "tool_call" }>): Pro
   resumeStateToken: string | undefined;
   grant: ApprovalGrant;
 }> {
-  const tc = buildToolCallProto(event);
+  const tc = foldCursorEvents([event]).rows()[0];
 
   // The gated turn: the hook denies the call, recording its identity token. The
   // runner's overlay (reconcileDeniedToolCalls) flips the same call to
@@ -120,7 +119,8 @@ async function roundTrip(event: Extract<SDKMessage, { type: "tool_call" }>): Pro
     toolCalls: [tc],
   });
   const ledger: DeniedLedgerEntry[] = [{ toolName: tc.name, token: denialToken }];
-  const denied = await reconcileDeniedToolCalls([msg], ledger);
+  const messages: AgentMessage[] = [msg];
+  const denied = await reconcileDeniedToolCalls(messages, builderOver(messages), ledger);
   expect(denied, "the overlay must match the denial token and surface the gate").toHaveLength(1);
 
   // The user approves; the backend persists the decision on the tool call.
@@ -130,7 +130,6 @@ async function roundTrip(event: Extract<SDKMessage, { type: "tool_call" }>): Pro
   // transcript (pending_approvals is already cleared by this point) and mint the
   // grants the next turn's hook reads. The content digest threads through so the
   // grant reproduces the content-exact denial identity.
-  const messages: AgentMessage[] = [msg];
   const { pendingApprovals, decisions, contentDigests } = reconstructAdjudicatedApprovals(messages);
   const grants = buildApprovalGrants(pendingApprovals, decisions, contentDigests);
   expect(grants, "an approved tool must yield exactly one grant").toHaveLength(1);
@@ -234,12 +233,8 @@ describe("Cursor resume-grant identity round-trip (H1 lock)", () => {
     // The exact bug this change fixes: approving the rename must NOT authorize
     // the TODO edit. They share a path (same coarse token) but differ in content,
     // so the content-exact identity distinguishes them.
-    const rename = buildToolCallProto(
-      builtInEvent("c1", "edit", { path: "/work/notes.md", old_string: "Planton Cloud", new_string: "Planton" }),
-    );
-    const todo = buildToolCallProto(
-      builtInEvent("c2", "edit", { path: "/work/notes.md", old_string: "", new_string: "## TODO\n" }),
-    );
+    const rename = foldCursorEvents([builtInEvent("c1", "edit", { path: "/work/notes.md", old_string: "Planton Cloud", new_string: "Planton" })]).rows()[0];
+    const todo = foldCursorEvents([builtInEvent("c2", "edit", { path: "/work/notes.md", old_string: "", new_string: "## TODO\n" })]).rows()[0];
     const renameToken = toolCallIdentityToken(rename);
     const todoToken = toolCallIdentityToken(todo);
 
@@ -252,9 +247,7 @@ describe("Cursor resume-grant identity round-trip (H1 lock)", () => {
     );
     // Re-issuing the SAME rename content reproduces its identity (identical
     // re-attempt is allowed; a drifted one re-gates).
-    const renameAgain = buildToolCallProto(
-      builtInEvent("c3", "edit", { path: "/work/notes.md", old_string: "Planton Cloud", new_string: "Planton" }),
-    );
+    const renameAgain = foldCursorEvents([builtInEvent("c3", "edit", { path: "/work/notes.md", old_string: "Planton Cloud", new_string: "Planton" })]).rows()[0];
     expect(toolCallIdentityToken(renameAgain)).toBe(renameToken);
   });
 
@@ -263,7 +256,7 @@ describe("Cursor resume-grant identity round-trip (H1 lock)", () => {
     event: Extract<SDKMessage, { type: "tool_call" }>,
     action: ApprovalAction,
   ): AgentMessage {
-    const tc = buildToolCallProto(event);
+    const tc = foldCursorEvents([event]).rows()[0];
     tc.status = ToolCallStatus.TOOL_CALL_WAITING_APPROVAL;
     tc.requiresApproval = true;
     tc.approvalAction = action;

package/src/activities/execute-cursor/__tests__/build-prompt.test.ts

@@ -544,7 +544,7 @@ describe("attachments on a resumed turn (T04 — the mid-session WhatsApp case)"
         ],
       }),
     );
-    // The size precedes the disclosure (the shared line, S3 M5 Q-M5-3).
+    // The size precedes the disclosure (the shared line, since #1096).
     expect(prompt).toContain(
       "- `.stigmer/inputs/report-2.pdf` (1024 bytes) (renamed from duplicate 'report.pdf')",
     );
@@ -778,8 +778,8 @@ describe("buildReinvocationPrompt", () => {
     expect(prompt).toContain("Continue the rest of the task");
   });
 
-  it("names a REJECTED action as a refusal, apart from the skipped ones, and still continues the task (stigmer#197; S3 M1)", () => {
-    // A REJECT denies the tool and the run continues; before S3 M1 the
+  it("names a REJECTED action as a refusal, apart from the skipped ones, and still continues the task (stigmer#197)", () => {
+    // A REJECT denies the tool and the run continues; before #1096 the
     // runtime failed the reinvocation before this prompt was ever built, so
     // the prompt had no REJECT arm.
     const decisions = new Map<string, ApprovalAction>([

package/src/activities/execute-cursor/__tests__/coarse-fingerprint.test.ts

@@ -1,5 +1,6 @@
 /**
- * @regression file-hitl-phase0 — pins file-edit HITL fix #6 (see _projects/2026-06/20260630.01.file-change-hitl-redesign/tasks/T01_3_regression-manifest.md)
+ * @regression file-hitl-phase0 — pins content-exact approval identity: approving
+ * one edit never lets a DIFFERENT edit to the same path ride the grant.
  *
  * Slice D — the Cursor grant token / fingerprint as the substrate-coarsened
  * projection of the shared canonical action.

package/src/activities/execute-cursor/__tests__/cursor-event-recorder.test.ts

@@ -0,0 +1,142 @@
+/**
+ * The Cursor event recorder's contract (`cursor-event-recorder.ts`): off when
+ * no directory is named; both SDK channels in ONE file under ONE arrival
+ * counter, each line saying which channel it came from; the file named by the
+ * execution; a cyclic payload recorded as a marker rather than failing the
+ * flush. The native recorder's `v3-event-recorder.test.ts` is the sibling.
+ *
+ * The ordering arm is the reason the recorder exists in this shape: a delta
+ * that arrives between two stream events must read between them in the file,
+ * because "does `tool-call-completed` precede the stream's own completion" is
+ * a question only the arrival order can answer.
+ */
+import { describe, it, expect, beforeEach } from "vitest";
+import { mkdtemp, readFile, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import type { InteractionUpdate, SDKMessage } from "@cursor/sdk";
+import { createCursorEventRecorder } from "../cursor-event-recorder.js";
+
+/** A stream event carrying only what the recorder reads; the rest is payload. */
+function streamEvent(type: string, extra: Record<string, unknown> = {}): SDKMessage {
+  return { type, agent_id: "agent-1", run_id: "run-1", ...extra } as unknown as SDKMessage;
+}
+
+function delta(type: string, extra: Record<string, unknown> = {}): InteractionUpdate {
+  return { type, ...extra } as unknown as InteractionUpdate;
+}
+
+interface RecordedLine {
+  readonly seq: number;
+  readonly capturedAt: string;
+  readonly channel: "stream" | "delta";
+  readonly type: string;
+  readonly agent_id?: string;
+  readonly run_id?: string;
+  readonly event?: Record<string, unknown>;
+  readonly update?: Record<string, unknown>;
+}
+
+async function readLines(dir: string, executionId: string): Promise<RecordedLine[]> {
+  const content = await readFile(join(dir, `${executionId}.cursor-events.jsonl`), "utf-8");
+  return content
+    .split("\n")
+    .filter((line) => line.length > 0)
+    .map((line) => JSON.parse(line) as RecordedLine);
+}
+
+describe("createCursorEventRecorder", () => {
+  it("returns undefined when no directory is named (recording off)", () => {
+    expect(createCursorEventRecorder("exec-1", undefined)).toBeUndefined();
+    expect(createCursorEventRecorder("exec-1", "")).toBeUndefined();
+  });
+
+  it("returns a recorder with both channels and a flush when a directory is named", () => {
+    const recorder = createCursorEventRecorder("exec-1", "/tmp/unused");
+    expect(recorder).toBeDefined();
+    expect(recorder!.record).toBeInstanceOf(Function);
+    expect(recorder!.recordDelta).toBeInstanceOf(Function);
+    expect(recorder!.flush).toBeInstanceOf(Function);
+  });
+});
+
+describe("CursorEventRecorder", () => {
+  let dir: string;
+
+  beforeEach(async () => {
+    dir = await mkdtemp(join(tmpdir(), "cursor-recorder-test-"));
+  });
+
+  it("flush writes nothing when nothing was recorded", async () => {
+    const recorder = createCursorEventRecorder("exec-empty", dir)!;
+    await recorder.flush();
+    expect(await readdir(dir)).toHaveLength(0);
+  });
+
+  it("sequences both channels in ONE file in arrival order, each line naming its channel", async () => {
+    const recorder = createCursorEventRecorder("exec-order", dir)!;
+
+    recorder.record(streamEvent("tool_call", { subtype: "started", call_id: "c1" }));
+    recorder.recordDelta(delta("shell-output-delta", { event: { chunk: "hook probe\n" } }));
+    recorder.recordDelta(delta("tool-call-completed", { toolCall: { id: "c1" } }));
+    recorder.record(streamEvent("tool_call", { subtype: "completed", call_id: "c1" }));
+    recorder.record(streamEvent("result"));
+
+    await recorder.flush();
+    const lines = await readLines(dir, "exec-order");
+
+    expect(lines.map((l) => l.seq)).toEqual([0, 1, 2, 3, 4]);
+    expect(lines.map((l) => `${l.channel}:${l.type}`)).toEqual([
+      "stream:tool_call",
+      "delta:shell-output-delta",
+      "delta:tool-call-completed",
+      "stream:tool_call",
+      "stream:result",
+    ]);
+    for (const line of lines) expect(line.capturedAt).toBeTruthy();
+  });
+
+  it("a stream line carries the event's agent and run ids and the whole event; a delta line the whole update", async () => {
+    const recorder = createCursorEventRecorder("exec-shape", dir)!;
+
+    recorder.record(streamEvent("assistant", { content: "hi" }));
+    recorder.recordDelta(delta("turn-ended", { usage: { inputTokens: 12 } }));
+
+    await recorder.flush();
+    const [stream, deltaLine] = await readLines(dir, "exec-shape");
+
+    expect(stream!.agent_id).toBe("agent-1");
+    expect(stream!.run_id).toBe("run-1");
+    expect(stream!.event).toMatchObject({ type: "assistant", content: "hi" });
+    expect(stream!.update).toBeUndefined();
+
+    expect(deltaLine!.update).toEqual({ type: "turn-ended", usage: { inputTokens: 12 } });
+    expect(deltaLine!.event).toBeUndefined();
+    expect(deltaLine!.agent_id).toBeUndefined();
+  });
+
+  it("names the file by execution id and creates the directory if it does not exist", async () => {
+    const nested = join(dir, "nested", "deep");
+    const recorder = createCursorEventRecorder("exec-mkdir", nested)!;
+
+    recorder.record(streamEvent("system"));
+    await recorder.flush();
+
+    expect(await readdir(nested)).toEqual(["exec-mkdir.cursor-events.jsonl"]);
+  });
+
+  it("records a cyclic payload as a serialization marker instead of failing the flush", async () => {
+    const recorder = createCursorEventRecorder("exec-cyclic", dir)!;
+
+    const cyclic: Record<string, unknown> = { type: "custom", a: 1 };
+    cyclic.self = cyclic;
+    recorder.record(cyclic as unknown as SDKMessage);
+
+    await recorder.flush();
+    const [line] = await readLines(dir, "exec-cyclic");
+
+    expect(line!.type).toBe("custom");
+    expect(line!.event).toMatchObject({ _serializationError: true });
+    expect((line!.event as { keys: string[] }).keys).toContain("a");
+  });
+});

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

@@ -1,11 +1,22 @@
 /**
- * Test that reproduces the desktop runner's EXACT execution path.
+ * Live probe: which of the SDK's calls a `globalThis.fetch` interceptor can
+ * see. A fetch wrapper that notes any call to a cursor.sh / cursor.com URL is
+ * installed, then `Agent.create()` runs (local mode, no model named).
  *
- * Simulates proxy mode: fetch interceptor installed, apiKey="proxy-managed",
- * to verify whether the proxy rewriting actually intercepts @cursor/sdk calls.
+ * What the one arm proves: `Agent.create()` completes WITHOUT a global-fetch
+ * call to a Cursor URL — its transport is connect-node over Node's HTTP/2, so
+ * a fetch-level interceptor alone cannot rewrite it. That is why the adapter
+ * installs BOTH interceptors in proxy mode (`fetch-interceptor.ts` and
+ * `http2-interceptor.ts`). Measured true at SDK 1.0.31 on 2026-09-16 (#1097's
+ * live run, 1/1).
  *
- * Expected result: THIS TEST WILL FAIL because @cursor/sdk uses connect-node
- * (Node.js native HTTP), not globalThis.fetch. The fetch interceptor never fires.
+ * What it does NOT prove: that the fetch interceptor is useless. A reading of
+ * the 1.0.31 bundle the same day found the SDK's cloud-api client and its
+ * token exchange on global `fetch`, on paths this arm never exercises; the
+ * fetch interceptor exists for those.
+ *
+ * Skipped without `CURSOR_API_KEY`; the suite never runs it. Run it by hand:
+ *   CURSOR_API_KEY=<key> npx vitest run src/activities/execute-cursor/__tests__/cursor-fetch-interceptor-bypass.test.ts
  */
 
 import { describe, it, expect, beforeAll, afterAll } from "vitest";
@@ -39,7 +50,7 @@ describeWithCursorKey("Fetch Interceptor vs Connect-Node Transport", () => {
     globalThis.fetch = originalFetch;
   });
 
-  it("Agent.create() does NOT go through globalThis.fetch (proving interceptor is useless)", async () => {
+  it("Agent.create() completes without a globalThis.fetch call to a Cursor URL", async () => {
     const { Agent } = await import("@cursor/sdk");
     const { SqliteLocalAgentStore } = await import("@cursor/sdk/sqlite");
 
@@ -58,8 +69,8 @@ describeWithCursorKey("Fetch Interceptor vs Connect-Node Transport", () => {
     expect(agent.agentId).toBeTruthy();
     console.log(`Agent created: ${agent.agentId}, interceptCalled=${interceptCalled}`);
 
-    // This assertion proves the fetch interceptor pattern is broken:
-    // connect-node uses Node.js http module, NOT globalThis.fetch
+    // The create path is connect-node over Node's HTTP/2, not globalThis.fetch;
+    // see the header for what this does and does not say about proxy mode.
     expect(interceptCalled).toBe(false);
   }, 30_000);
 });

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

@@ -1,13 +1,15 @@
 /**
- * Minimal smoke test to verify Cursor SDK authentication works with a real API key.
+ * Live smoke: the Cursor SDK authenticates and completes a round trip on a
+ * real member key. Three arms, each isolating one fact:
+ *  1. `Agent.create()` with a model named succeeds — the key is valid;
+ *  2. `agent.send()` runs to a completed result — the agent executes and the
+ *     transport completes the round trip;
+ *  3. `Agent.create()` with no model named succeeds — the catalog default
+ *     resolves.
  *
- * Tests three things in isolation:
- * 1. Agent.create() succeeds (proves the API key is valid)
- * 2. agent.send() produces a response (proves the agent can execute)
- * 3. The connect-node transport works end-to-end
- *
- * Run with: CURSOR_API_KEY=<key> npx tsx --test this-file.ts
- * Or via the test script: npm run test:cursor-auth
+ * Skipped without `CURSOR_API_KEY`; the suite never runs it. Run it by hand:
+ *   CURSOR_API_KEY=<key> npx vitest run src/activities/execute-cursor/__tests__/cursor-sdk-auth-smoke.test.ts
+ * Last run green 3/3 on 2026-09-16 at SDK 1.0.31 (#1097's live run).
  */
 
 import { describe, it, expect } from "vitest";