@stigmer/runner 3.15.2 → 3.15.3-dev.20260914121148

package/src/activities/execute-cursor/__tests__/cursor-hook-protocol-live.test.ts

@@ -0,0 +1,163 @@
+/**
+ * Live ground truth for the hook protocol the approval gate rides on — the
+ * standing instrument an `@cursor/sdk` bump runs before it is trusted
+ * (stigmer/stigmer#1053, the first bump; every later one inherits this).
+ *
+ * WHY THIS EXISTS. The Stigmer HITL gate on the Cursor harness is a
+ * `.cursor/hooks.json` `preToolUse` hook (`hook-script.ts`) that reads the
+ * SDK's stdin payload and answers `{"permission": "allow" | "deny"}`. Three
+ * facts about that payload are load-bearing and none is a TypeScript type:
+ *
+ *  1. `tool_name` is the HOOK taxonomy, PascalCase (`Write`, `Shell`, `Delete`;
+ *     the stream taxonomy is lowercase `edit`, `shell`, `delete`) — the gated
+ *     set `BUILT_IN_GATED` (`approval-policy.ts`) is spelled in it.
+ *  2. `tool_input` is an OBJECT for built-in tools (a JSON STRING for MCP
+ *     tools under `beforeMCPExecution`) — the hook's identity token and the
+ *     denial ledger's captured args are computed from it.
+ *  3. `hook_event_name` discriminates `preToolUse` from `beforeMCPExecution`.
+ *
+ * The hermetic tests prove the runner's handling of the shapes CAPTURED at
+ * 1.0.13 (`cursor-hook-harness.ts` `hookWrite`, `hookShell`, ...). They cannot
+ * see the SDK move. This test runs one real turn that edits a file and runs a
+ * shell command under an allow-everything observation hook, then asserts the
+ * three facts on what the real SDK sent. A `tool_name` outside the gated set
+ * for a write-, shell- or delete-class action is the one outcome that must
+ * stop a bump: the gate would let it through.
+ *
+ * Skipped without CURSOR_API_KEY (the cursor-sdk-auth-smoke.test.ts
+ * convention) — it spends real credits for one short turn. Findings are
+ * PRINTED as well as asserted, so a bump's PR can quote the shapes seen.
+ *
+ * Run with: CURSOR_API_KEY=<key> npx vitest run cursor-hook-protocol-live
+ */
+import { describe, it, expect } from "vitest";
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { approvalCategory } from "../approval-policy.js";
+
+const CURSOR_API_KEY = process.env.CURSOR_API_KEY ?? "";
+const describeWithCursorKey = CURSOR_API_KEY ? describe : describe.skip;
+
+/** One hook invocation as the SDK wrote it to the hook's stdin. */
+interface HookInvocation {
+  readonly hook_event_name?: unknown;
+  readonly tool_name?: unknown;
+  readonly tool_input?: unknown;
+}
+
+/**
+ * An observation-only preToolUse/beforeMCPExecution hook: appends every
+ * invocation's stdin JSON to a log file and ALLOWS everything, so the turn
+ * runs to completion and every gated action is seen exactly as the gate would
+ * see it.
+ */
+function installObservationHook(workspaceRoot: string, logPath: string): void {
+  const hooksDir = join(workspaceRoot, ".cursor");
+  mkdirSync(hooksDir, { recursive: true });
+  const scriptPath = join(hooksDir, "observe-hook.sh");
+  writeFileSync(
+    scriptPath,
+    `#!/bin/bash\nINPUT=$(cat)\nprintf '%s\\n' "$INPUT" >> "${logPath}" 2>/dev/null || true\necho '{"permission":"allow"}'\n`,
+    "utf-8",
+  );
+  chmodSync(scriptPath, 0o755);
+  writeFileSync(
+    join(hooksDir, "hooks.json"),
+    JSON.stringify({
+      version: 1,
+      hooks: {
+        preToolUse: [{ command: scriptPath }],
+        beforeMCPExecution: [{ command: scriptPath }],
+      },
+    }),
+    "utf-8",
+  );
+}
+
+function readInvocations(logPath: string): HookInvocation[] {
+  if (!existsSync(logPath)) return [];
+  const invocations: HookInvocation[] = [];
+  for (const line of readFileSync(logPath, "utf-8").split("\n")) {
+    if (!line.trim()) continue;
+    try {
+      invocations.push(JSON.parse(line) as HookInvocation);
+    } catch {
+      /* a partial line from a hook the SDK cut off; nothing to read */
+    }
+  }
+  return invocations;
+}
+
+describeWithCursorKey("Cursor SDK hook protocol (live ground truth)", () => {
+  it("delivers PascalCase tool_name, an object tool_input and hook_event_name for a file edit and a shell command", async () => {
+    const { Agent } = await import("@cursor/sdk");
+    const { SqliteLocalAgentStore } = await import("@cursor/sdk/sqlite");
+
+    const workspaceRoot = mkdtempSync(join(tmpdir(), "stigmer-hook-protocol-"));
+    const stateRoot = join(workspaceRoot, ".sdk-state");
+    mkdirSync(stateRoot, { recursive: true });
+    const hookLog = join(workspaceRoot, "hook-invocations.jsonl");
+    installObservationHook(workspaceRoot, hookLog);
+
+    // Mirror the runner's arrangement (session-lifecycle.ts): local cwd, the
+    // "project" setting source that loads .cursor/hooks.json, the session's
+    // own store, the SDK's retries off.
+    const agent = await Agent.create({
+      apiKey: CURSOR_API_KEY,
+      model: { id: "composer-2.5" },
+      local: {
+        cwd: workspaceRoot,
+        settingSources: ["project"],
+        store: await SqliteLocalAgentStore.open({ workspaceRef: `hook-protocol-${Date.now()}`, stateRoot }),
+        enableAgentRetries: false,
+      },
+    });
+
+    const run = await agent.send(
+      "Do exactly two things, in order, without asking questions: " +
+        "(1) create a file named probe.txt in the workspace containing the single line 'hook probe'; " +
+        "(2) run the shell command `cat probe.txt`. Then reply with the word done.",
+    );
+    for await (const _event of run.stream()) {
+      /* drain: the hook log is the evidence, not the stream */
+    }
+    const result = await run.wait();
+    agent.close();
+
+    const invocations = readInvocations(hookLog);
+
+    // ---- Findings dump (what a bump's PR quotes) ----
+    console.log(`[hook-protocol] run status: ${result.status}`);
+    for (const inv of invocations) {
+      console.log(
+        `[hook-protocol] ${String(inv.hook_event_name)}:${String(inv.tool_name)} ` +
+          `tool_input=${typeof inv.tool_input} ${JSON.stringify(inv.tool_input).slice(0, 200)}`,
+      );
+    }
+
+    // The SDK boundary must not hang, and the turn must have reached the hook.
+    expect(["finished", "error", "cancelled"]).toContain(result.status);
+    expect(invocations.length, "the observation hook saw no tool call — hooks.json was not loaded").toBeGreaterThan(0);
+
+    const builtIns = invocations.filter((inv) => inv.hook_event_name === "preToolUse");
+    expect(builtIns.length, "no preToolUse invocation: the built-in tools did not reach the hook").toBeGreaterThan(0);
+    for (const inv of builtIns) {
+      // Fact 3: the discriminator is present and spelled as the script branches on it.
+      expect(inv.hook_event_name).toBe("preToolUse");
+      // Fact 1: the hook taxonomy is PascalCase.
+      expect(typeof inv.tool_name).toBe("string");
+      expect(inv.tool_name as string).toMatch(/^[A-Z]/);
+      // Fact 2: built-in tool_input is an object, not a JSON string.
+      expect(typeof inv.tool_input).toBe("object");
+      expect(inv.tool_input).not.toBeNull();
+    }
+
+    // The gate's reach: the write and the shell the prompt forced must have
+    // arrived under names the gate classifies. A write- or shell-class action
+    // under an unclassified name is the outcome that stops a bump.
+    const categories = builtIns.map((inv) => approvalCategory(inv.tool_name as string));
+    expect(categories, "the file write reached the hook under a name the gate classifies as write").toContain("write");
+    expect(categories, "the shell command reached the hook under a name the gate classifies as shell").toContain("shell");
+  }, 300_000);
+});

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

@@ -12,6 +12,7 @@
 
 import { describe, it, expect } from "vitest";
 import { Agent } from "@cursor/sdk";
+import { SqliteLocalAgentStore } from "@cursor/sdk/sqlite";
 import { mkdirSync } from "node:fs";
 import { join } from "node:path";
 import { tmpdir } from "node:os";
@@ -31,10 +32,10 @@ describeWithCursorKey("Cursor SDK Authentication Smoke Test", () => {
     const agent = await Agent.create({
       apiKey: CURSOR_API_KEY,
       model: { id: "claude-sonnet-4" },
-      local: { cwd: stateRoot },
-      platform: {
-        workspaceRef: `auth-test-${Date.now()}`,
-        stateRoot,
+      local: {
+        cwd: stateRoot,
+        // 1.0.31: the store is caller-owned (`session-store.ts` in production).
+        store: await SqliteLocalAgentStore.open({ workspaceRef: `auth-test-${Date.now()}`, stateRoot }),
       },
     });
 
@@ -50,10 +51,10 @@ describeWithCursorKey("Cursor SDK Authentication Smoke Test", () => {
     const agent = await Agent.create({
       apiKey: CURSOR_API_KEY,
       model: { id: "claude-sonnet-4" },
-      local: { cwd: stateRoot },
-      platform: {
-        workspaceRef: `send-test-${Date.now()}`,
-        stateRoot,
+      local: {
+        cwd: stateRoot,
+        // 1.0.31: the store is caller-owned (`session-store.ts` in production).
+        store: await SqliteLocalAgentStore.open({ workspaceRef: `send-test-${Date.now()}`, stateRoot }),
       },
     });
 
@@ -76,10 +77,10 @@ describeWithCursorKey("Cursor SDK Authentication Smoke Test", () => {
 
     const agent = await Agent.create({
       apiKey: CURSOR_API_KEY,
-      local: { cwd: stateRoot },
-      platform: {
-        workspaceRef: `default-model-test-${Date.now()}`,
-        stateRoot,
+      local: {
+        cwd: stateRoot,
+        // 1.0.31: the store is caller-owned (`session-store.ts` in production).
+        store: await SqliteLocalAgentStore.open({ workspaceRef: `default-model-test-${Date.now()}`, stateRoot }),
       },
     });
 

package/src/activities/execute-cursor/__tests__/hermetic/deny-and-retry.test.ts

@@ -50,6 +50,9 @@ import {
 vi.mock("@cursor/sdk", async () =>
   (await import("../../__test-utils__/scripted-sdk.js")).scriptedCursorSdkModule(),
 );
+vi.mock("@cursor/sdk/sqlite", async () =>
+  (await import("../../__test-utils__/scripted-sdk.js")).scriptedCursorSqliteModule(),
+);
 vi.mock("../../../../client/stigmer-client.js", async () =>
   (await import("../../../../__test-utils__/hermetic-activity.js")).hermeticStigmerClientModule(),
 );
@@ -137,7 +140,7 @@ describe.skipIf(!hasBash)("ExecuteCursor hermetic — deny-and-retry approval ro
           step.event(ev2.toolCall(CALL_TURN_2, "shell", "running", SHELL_ARGS)),
           step.event(ev2.toolCall(CALL_TURN_2, "shell", "completed", SHELL_ARGS, BUILD_OUTPUT)),
           step.event(ev2.assistant(FINAL_TEXT)),
-          step.turnEnded({ inputTokens: 3_100, outputTokens: 60 }),
+          step.turnEnded({ inputTokens: 3_100, outputTokens: 60, cacheReadTokens: 0, cacheWriteTokens: 0 }),
           step.finished({ result: FINAL_TEXT, model: { id: FIXTURE.model, params: [] } }),
         ],
       ],

package/src/activities/execute-cursor/__tests__/hermetic/file-review-capture.test.ts

@@ -42,6 +42,9 @@ import { ExecutionPhase, ToolCallStatus } from "@stigmer/protos/ai/stigmer/agent
 vi.mock("@cursor/sdk", async () =>
   (await import("../../__test-utils__/scripted-sdk.js")).scriptedCursorSdkModule(),
 );
+vi.mock("@cursor/sdk/sqlite", async () =>
+  (await import("../../__test-utils__/scripted-sdk.js")).scriptedCursorSqliteModule(),
+);
 vi.mock("../../../../client/stigmer-client.js", async () =>
   (await import("../../../../__test-utils__/hermetic-activity.js")).hermeticStigmerClientModule(),
 );
@@ -116,7 +119,7 @@ describe.skipIf(!hasBash)("ExecuteCursor hermetic — file-review capture on a g
           step.event(ev.toolCall(CALL_ID, "edit", "running", { path: FILE, content: AFTER })),
           step.event(ev.toolCall(CALL_ID, "edit", "completed", { path: FILE, content: AFTER }, "ok")),
           step.event(ev.assistant("Done — notes.md now records the review.")),
-          step.turnEnded({ inputTokens: 2_400, outputTokens: 70 }),
+          step.turnEnded({ inputTokens: 2_400, outputTokens: 70, cacheReadTokens: 0, cacheWriteTokens: 0 }),
           step.finished({ result: "Done", model: { id: FIXTURE.model, params: [] } }),
         ],
       ],

package/src/activities/execute-cursor/__tests__/hermetic/harness-contract.test.ts

@@ -55,6 +55,9 @@ import { ApprovalAction, ToolCallStatus } from "@stigmer/protos/ai/stigmer/agent
 vi.mock("@cursor/sdk", async () =>
   (await import("../../__test-utils__/scripted-sdk.js")).scriptedCursorSdkModule(),
 );
+vi.mock("@cursor/sdk/sqlite", async () =>
+  (await import("../../__test-utils__/scripted-sdk.js")).scriptedCursorSqliteModule(),
+);
 vi.mock("../../../../client/stigmer-client.js", async () =>
   (await import("../../../../__test-utils__/hermetic-activity.js")).hermeticStigmerClientModule(),
 );

package/src/activities/execute-cursor/__tests__/hermetic/pause-vs-shutdown.test.ts

@@ -54,6 +54,9 @@ import { ExecutionPhase, MessageType } from "@stigmer/protos/ai/stigmer/agentic/
 vi.mock("@cursor/sdk", async () =>
   (await import("../../__test-utils__/scripted-sdk.js")).scriptedCursorSdkModule(),
 );
+vi.mock("@cursor/sdk/sqlite", async () =>
+  (await import("../../__test-utils__/scripted-sdk.js")).scriptedCursorSqliteModule(),
+);
 vi.mock("../../../../client/stigmer-client.js", async () =>
   (await import("../../../../__test-utils__/hermetic-activity.js")).hermeticStigmerClientModule(),
 );

package/src/activities/execute-cursor/__tests__/hermetic/plain-turn.test.ts

@@ -37,6 +37,9 @@ import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecutio
 vi.mock("@cursor/sdk", async () =>
   (await import("../../__test-utils__/scripted-sdk.js")).scriptedCursorSdkModule(),
 );
+vi.mock("@cursor/sdk/sqlite", async () =>
+  (await import("../../__test-utils__/scripted-sdk.js")).scriptedCursorSqliteModule(),
+);
 vi.mock("../../../../client/stigmer-client.js", async () =>
   (await import("../../../../__test-utils__/hermetic-activity.js")).hermeticStigmerClientModule(),
 );
@@ -93,7 +96,7 @@ describe("ExecuteCursor hermetic — plain turn", () => {
             run_id: RUN_ID,
             message: { role: "assistant", content: [{ type: "text", text: ASSISTANT_TEXT }] },
           }),
-          step.turnEnded({ inputTokens: 1_200, outputTokens: 40 }),
+          step.turnEnded({ inputTokens: 1_200, outputTokens: 40, cacheReadTokens: 0, cacheWriteTokens: 0 }),
           step.finished({
             result: ASSISTANT_TEXT,
             model: {

package/src/activities/execute-cursor/__tests__/hermetic/recovery-fresh-agent.test.ts

@@ -33,6 +33,9 @@ import { ExecutionPhase } from "@stigmer/protos/ai/stigmer/agentic/agentexecutio
 vi.mock("@cursor/sdk", async () =>
   (await import("../../__test-utils__/scripted-sdk.js")).scriptedCursorSdkModule(),
 );
+vi.mock("@cursor/sdk/sqlite", async () =>
+  (await import("../../__test-utils__/scripted-sdk.js")).scriptedCursorSqliteModule(),
+);
 vi.mock("../../../../client/stigmer-client.js", async () =>
   (await import("../../../../__test-utils__/hermetic-activity.js")).hermeticStigmerClientModule(),
 );
@@ -104,7 +107,7 @@ describe("ExecuteCursor hermetic — poisoned-handle recovery on a fresh agent",
         [
           step.event(evFresh.init()),
           step.event(evFresh.assistant(FINAL_TEXT)),
-          step.turnEnded({ inputTokens: 2_800, outputTokens: 55 }),
+          step.turnEnded({ inputTokens: 2_800, outputTokens: 55, cacheReadTokens: 0, cacheWriteTokens: 0 }),
           step.finished({ result: FINAL_TEXT, model: { id: FIXTURE.model, params: [] } }),
         ],
       ],

package/src/activities/execute-cursor/__tests__/hermetic/run-wait-arms.test.ts

@@ -44,6 +44,9 @@ import { ExecutionPhase, MessageType } from "@stigmer/protos/ai/stigmer/agentic/
 vi.mock("@cursor/sdk", async () =>
   (await import("../../__test-utils__/scripted-sdk.js")).scriptedCursorSdkModule(),
 );
+vi.mock("@cursor/sdk/sqlite", async () =>
+  (await import("../../__test-utils__/scripted-sdk.js")).scriptedCursorSqliteModule(),
+);
 vi.mock("../../../../client/stigmer-client.js", async () =>
   (await import("../../../../__test-utils__/hermetic-activity.js")).hermeticStigmerClientModule(),
 );
@@ -175,7 +178,7 @@ describe("ExecuteCursor hermetic — the run.wait() arms on a created agent", ()
         [
           step.event(evFresh.init()),
           step.event(evFresh.assistant(FINAL_TEXT)),
-          step.turnEnded({ inputTokens: 2_200, outputTokens: 30 }),
+          step.turnEnded({ inputTokens: 2_200, outputTokens: 30, cacheReadTokens: 0, cacheWriteTokens: 0 }),
           step.finished({ result: FINAL_TEXT, model: { id: FIXTURE.model, params: [] } }),
         ],
       ],

package/src/activities/execute-cursor/__tests__/hermetic/stream-self-stop-arms.test.ts

@@ -64,6 +64,9 @@ import {
 vi.mock("@cursor/sdk", async () =>
   (await import("../../__test-utils__/scripted-sdk.js")).scriptedCursorSdkModule(),
 );
+vi.mock("@cursor/sdk/sqlite", async () =>
+  (await import("../../__test-utils__/scripted-sdk.js")).scriptedCursorSqliteModule(),
+);
 vi.mock("../../../../client/stigmer-client.js", async () =>
   (await import("../../../../__test-utils__/hermetic-activity.js")).hermeticStigmerClientModule(),
 );
@@ -213,7 +216,7 @@ describe("ExecuteCursor hermetic — the stream loop's self-stop arms", () => {
           step.event(ev.init()),
           step.event(ev.assistant("Reading the whole repository first.")),
           // 600 000 input tokens at the fixture's $1/M base rate = $0.60 > $0.50.
-          step.turnEnded({ inputTokens: 600_000, outputTokens: 0 }),
+          step.turnEnded({ inputTokens: 600_000, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0 }),
           step.event(ev.assistant(NEVER_SEEN)),
           step.finished({ result: NEVER_SEEN }),
         ],

package/src/activities/execute-cursor/__tests__/hermetic/thrown-error-arms.test.ts

@@ -49,6 +49,9 @@ import { ExecutionPhase, MessageType } from "@stigmer/protos/ai/stigmer/agentic/
 vi.mock("@cursor/sdk", async () =>
   (await import("../../__test-utils__/scripted-sdk.js")).scriptedCursorSdkModule(),
 );
+vi.mock("@cursor/sdk/sqlite", async () =>
+  (await import("../../__test-utils__/scripted-sdk.js")).scriptedCursorSqliteModule(),
+);
 vi.mock("../../../../client/stigmer-client.js", async () =>
   (await import("../../../../__test-utils__/hermetic-activity.js")).hermeticStigmerClientModule(),
 );

package/src/activities/execute-cursor/__tests__/hermetic/tool-call.test.ts

@@ -28,6 +28,9 @@ import { ExecutionPhase, ToolCallStatus } from "@stigmer/protos/ai/stigmer/agent
 vi.mock("@cursor/sdk", async () =>
   (await import("../../__test-utils__/scripted-sdk.js")).scriptedCursorSdkModule(),
 );
+vi.mock("@cursor/sdk/sqlite", async () =>
+  (await import("../../__test-utils__/scripted-sdk.js")).scriptedCursorSqliteModule(),
+);
 vi.mock("../../../../client/stigmer-client.js", async () =>
   (await import("../../../../__test-utils__/hermetic-activity.js")).hermeticStigmerClientModule(),
 );
@@ -86,7 +89,7 @@ describe("ExecuteCursor hermetic — ungated tool call", () => {
           step.event(ev.toolCall(CALL_ID, "read", "running", READ_ARGS)),
           step.event(ev.toolCall(CALL_ID, "read", "completed", READ_ARGS, READ_RESULT)),
           step.event(ev.assistant(ASSISTANT_TEXT)),
-          step.turnEnded({ inputTokens: 2_000, outputTokens: 90 }),
+          step.turnEnded({ inputTokens: 2_000, outputTokens: 90, cacheReadTokens: 0, cacheWriteTokens: 0 }),
           step.finished({ result: ASSISTANT_TEXT, model: { id: FIXTURE.model, params: [] } }),
         ],
       ],

package/src/activities/execute-cursor/__tests__/hermetic/unattributed-hook-block.test.ts

@@ -45,6 +45,9 @@ import {
 vi.mock("@cursor/sdk", async () =>
   (await import("../../__test-utils__/scripted-sdk.js")).scriptedCursorSdkModule(),
 );
+vi.mock("@cursor/sdk/sqlite", async () =>
+  (await import("../../__test-utils__/scripted-sdk.js")).scriptedCursorSqliteModule(),
+);
 vi.mock("../../../../client/stigmer-client.js", async () =>
   (await import("../../../../__test-utils__/hermetic-activity.js")).hermeticStigmerClientModule(),
 );
@@ -123,7 +126,7 @@ describe("ExecuteCursor hermetic — unattributed hook block (#205)", () => {
           // failed with its generic hook-block text. Our ledger never saw it.
           step.event(ev.toolCall(CALL_ID, "shell", "error", SHELL_ARGS, HOOK_BLOCK_ERROR)),
           step.event(ev.assistant(FINAL_TEXT)),
-          step.turnEnded({ inputTokens: 1_500, outputTokens: 40 }),
+          step.turnEnded({ inputTokens: 1_500, outputTokens: 40, cacheReadTokens: 0, cacheWriteTokens: 0 }),
           step.finished({ result: FINAL_TEXT }),
         ],
       ],

package/src/activities/execute-cursor/__tests__/hermetic/workspace-lock-timeout.test.ts

@@ -35,6 +35,9 @@ import { ExecutionPhase, MessageType } from "@stigmer/protos/ai/stigmer/agentic/
 vi.mock("@cursor/sdk", async () =>
   (await import("../../__test-utils__/scripted-sdk.js")).scriptedCursorSdkModule(),
 );
+vi.mock("@cursor/sdk/sqlite", async () =>
+  (await import("../../__test-utils__/scripted-sdk.js")).scriptedCursorSqliteModule(),
+);
 vi.mock("../../../../client/stigmer-client.js", async () =>
   (await import("../../../../__test-utils__/hermetic-activity.js")).hermeticStigmerClientModule(),
 );

package/src/activities/execute-cursor/__tests__/session-lifecycle.test.ts

@@ -1,10 +1,15 @@
 /**
- * Unit tests for resolvePlatformOptions — the Cursor SDK stateRoot derivation.
+ * Unit tests for the local agent's create/resume options and the
+ * transport-recovery wrapper (`session-lifecycle.ts`).
  *
- * stateRoot is keyed by sessionId and rooted at the durable workspace volume so
- * native Agent.resume() survives restart/snapshot-restore and so sessions that
- * share one volume (e.g. a workflow sandbox's child agent executions) never
- * collide. These invariants are correctness-critical, hence the explicit tests.
+ * The SDK module is a `vi.fn` stub so the assertions read the exact options
+ * the adapter hands `Agent.create` / `Agent.resume`. The SDK's sqlite entry is
+ * NOT mocked here on purpose: `createAgent` opens the session's REAL
+ * `SqliteLocalAgentStore` (`node:sqlite`, no network) under a temp workspace
+ * volume, so this file is also where the store the runner ships with is
+ * proven to open, be reused, and dispose — the hermetic goldens double it.
+ * The store's keying and lifetime rules have their own arms in
+ * `session-store.test.ts`.
  */
 
 import { describe, it, expect, afterEach, vi } from "vitest";
@@ -20,13 +25,15 @@ vi.mock("@cursor/sdk", () => ({
 }));
 
 import { Agent } from "@cursor/sdk";
+import type { AgentOptions } from "@cursor/sdk";
+import { SqliteLocalAgentStore } from "@cursor/sdk/sqlite";
 import {
-  resolvePlatformOptions,
   createAgent,
   resumeAgent,
   resolveAgentWithTransportRecovery,
 } from "../session-lifecycle.js";
 import type { CreateAgentOptions } from "../session-lifecycle.js";
+import { releaseAllSessionStores } from "../session-store.js";
 
 const tempRoots: string[] = [];
 
@@ -36,50 +43,25 @@ function freshWorkspaceRoot(): string {
   return dir;
 }
 
-afterEach(() => {
+afterEach(async () => {
+  // Release every store before its directory goes, so the sqlite handles are
+  // closed when the temp roots are removed (and no test inherits a store).
+  await releaseAllSessionStores();
   for (const dir of tempRoots.splice(0)) {
     rmSync(dir, { recursive: true, force: true });
   }
 });
 
-describe("resolvePlatformOptions", () => {
-  it("derives stateRoot under the workspace volume (not $HOME)", () => {
-    const workspaceRootDir = freshWorkspaceRoot();
-    const opts = resolvePlatformOptions("ses-123", workspaceRootDir);
-
-    expect(opts.stateRoot).toBe(
-      join(workspaceRootDir, ".stigmer", "cursor-sdk-state", "ses-123"),
-    );
-    expect(opts.stateRoot.startsWith(workspaceRootDir)).toBe(true);
-    // Created eagerly to prevent ENOENT on first SDK write.
-    expect(existsSync(opts.stateRoot!)).toBe(true);
-    expect(opts.workspaceRef).toBe("stigmer-session:ses-123");
-  });
-
-  it("isolates two sessions sharing one workspace volume into distinct stores", () => {
-    const workspaceRootDir = freshWorkspaceRoot();
-    const a = resolvePlatformOptions("ses-aaa", workspaceRootDir);
-    const b = resolvePlatformOptions("ses-bbb", workspaceRootDir);
-
-    expect(a.stateRoot).not.toBe(b.stateRoot);
-    expect(a.workspaceRef).not.toBe(b.workspaceRef);
-    // Both live under the same shared volume but in session-keyed subdirs.
-    expect(a.stateRoot!.startsWith(join(workspaceRootDir, ".stigmer"))).toBe(true);
-    expect(b.stateRoot!.startsWith(join(workspaceRootDir, ".stigmer"))).toBe(true);
-  });
-
-  it("throws on an empty sessionId (would collide across sessions on a shared volume)", () => {
-    const workspaceRootDir = freshWorkspaceRoot();
-    expect(() => resolvePlatformOptions("", workspaceRootDir)).toThrow(/sessionId is required/);
-  });
+function lastCreateOptions(): AgentOptions {
+  return vi.mocked(Agent.create).mock.calls.at(-1)![0];
+}
 
-  it("throws on an empty workspaceRootDir (state must live on the durable volume)", () => {
-    expect(() => resolvePlatformOptions("ses-123", "")).toThrow(/workspaceRootDir is required/);
-  });
-});
+function lastResumeCall(): [string, Partial<AgentOptions> | undefined] {
+  return vi.mocked(Agent.resume).mock.calls.at(-1)! as [string, Partial<AgentOptions> | undefined];
+}
 
 // ---------------------------------------------------------------------------
-// Workspace binding across create/resume
+// The local options across create/resume
 //
 // Regression: Agent.resume() does not persist local.cwd. When resumeAgent()
 // omitted it, the SDK fell back to process.cwd() — re-rooting the resumed
@@ -87,17 +69,33 @@ describe("resolvePlatformOptions", () => {
 // setting source (the .cursor/hooks.json carrying the HITL approval hook)
 // from that wrong directory. Result: on every resumed turn, file edits and
 // shell commands ran unguarded with no approval card (observed in production
-// execution aex_01ktr5na07f5xtmn0dz3mfjtdp).
+// execution aex_01ktr5na07f5xtmn0dz3mfjtdp). The same rule now covers the
+// store (#1053): a resume without it would look the agent up in a default
+// store derived from cwd, not the one the session's records are in.
 // ---------------------------------------------------------------------------
 
-describe("workspace binding on create/resume", () => {
+describe("local options on create/resume", () => {
   const baseOptions = {
     apiKey: "key",
     sessionId: "ses-cwd-test",
     model: "gpt-test",
   };
 
-  it("createAgent passes the single workspace dir as local.cwd", async () => {
+  it("createAgent passes the single workspace dir as local.cwd, with no dirs", async () => {
+    const workspaceRootDir = freshWorkspaceRoot();
+    await createAgent({
+      ...baseOptions,
+      workspaceDirs: ["/work/repo-a"],
+      workspaceRootDir,
+    });
+
+    const { local } = lastCreateOptions();
+    expect(local?.cwd).toBe("/work/repo-a");
+    expect(local).not.toHaveProperty("dirs");
+    expect(local?.settingSources).toContain("project");
+  });
+
+  it("createAgent opens the session's real SQLite store under the workspace volume and passes it as local.store", async () => {
     const workspaceRootDir = freshWorkspaceRoot();
     await createAgent({
       ...baseOptions,
@@ -105,13 +103,37 @@ describe("workspace binding on create/resume", () => {
       workspaceRootDir,
     });
 
-    const callOptions = vi.mocked(Agent.create).mock.calls.at(-1)![0] as any;
-    expect(callOptions.local.cwd).toBe("/work/repo-a");
-    expect(callOptions.local.settingSources).toContain("project");
+    const store = lastCreateOptions().local?.store;
+    expect(store).toBeInstanceOf(SqliteLocalAgentStore);
+    const sqlite = store as SqliteLocalAgentStore;
+    expect(sqlite.workspaceRef).toBe("stigmer-session:ses-cwd-test");
+    expect(sqlite.stateRoot).toBe(join(workspaceRootDir, ".stigmer", "cursor-sdk-state", "ses-cwd-test"));
+    // The SDK's layout lands where the runner said, not under $HOME.
+    expect(existsSync(sqlite.stateRoot)).toBe(true);
   });
 
-  it("resumeAgent re-supplies local.cwd (not persisted by Agent.resume)", async () => {
+  it("createAgent pins the SDK's own retries off (the runner is the retry authority)", async () => {
     const workspaceRootDir = freshWorkspaceRoot();
+    await createAgent({
+      ...baseOptions,
+      workspaceDirs: ["/work/repo-a"],
+      workspaceRootDir,
+    });
+
+    // 1.0.31 defaults this to true for headless embedders; an absent field
+    // would silently stack the SDK's transport retries under the runner's.
+    expect(lastCreateOptions().local?.enableAgentRetries).toBe(false);
+  });
+
+  it("resumeAgent re-supplies cwd, settingSources, store and the retry pin (nothing under local survives Agent.resume)", async () => {
+    const workspaceRootDir = freshWorkspaceRoot();
+    await createAgent({
+      ...baseOptions,
+      workspaceDirs: ["/work/repo-a"],
+      workspaceRootDir,
+    });
+    const createdWith = lastCreateOptions().local?.store;
+
     await resumeAgent({
       ...baseOptions,
       agentId: "agent-123",
@@ -119,25 +141,31 @@ describe("workspace binding on create/resume", () => {
       workspaceRootDir,
     });
 
-    const [agentId, callOptions] = vi.mocked(Agent.resume).mock.calls.at(-1)! as [string, any];
+    const [agentId, callOptions] = lastResumeCall();
     expect(agentId).toBe("agent-123");
-    // The load-bearing assertion: without cwd the SDK re-roots the agent at
-    // process.cwd() and the project HITL hook never loads on resumed turns.
-    expect(callOptions.local.cwd).toBe("/work/repo-a");
-    expect(callOptions.local.settingSources).toContain("project");
+    // The load-bearing assertions: without cwd the SDK re-roots the agent at
+    // process.cwd() and the project HITL hook never loads on resumed turns;
+    // without the SAME store it looks the agent up somewhere else.
+    expect(callOptions?.local?.cwd).toBe("/work/repo-a");
+    expect(callOptions?.local?.settingSources).toContain("project");
+    expect(callOptions?.local?.store).toBe(createdWith);
+    expect(callOptions?.local?.enableAgentRetries).toBe(false);
   });
 
-  it("resumeAgent passes multiple workspace dirs as an array cwd", async () => {
+  it("passes a multi-root workspace as cwd (the first dir) plus dirs (the rest)", async () => {
     const workspaceRootDir = freshWorkspaceRoot();
     await resumeAgent({
       ...baseOptions,
       agentId: "agent-456",
-      workspaceDirs: ["/work/repo-a", "/work/repo-b"],
+      workspaceDirs: ["/work/repo-a", "/work/repo-b", "/work/repo-c"],
       workspaceRootDir,
     });
 
-    const callOptions = vi.mocked(Agent.resume).mock.calls.at(-1)![1] as any;
-    expect(callOptions.local.cwd).toEqual(["/work/repo-a", "/work/repo-b"]);
+    const [, callOptions] = lastResumeCall();
+    // The SDK merges cwd-first with duplicates dropped, so this is the array
+    // the SDK took whole at 1.0.13, in the same order.
+    expect(callOptions?.local?.cwd).toBe("/work/repo-a");
+    expect(callOptions?.local?.dirs).toEqual(["/work/repo-b", "/work/repo-c"]);
   });
 });