@stigmer/runner 0.1.0-dev.20261017020314.g644422724c27

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

@@ -0,0 +1,336 @@
+/**
+ * Unit tests for the local agent's create/resume options and the
+ * transport-recovery wrapper (`session-lifecycle.ts`).
+ *
+ * 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`. The agent's built-in tool restriction (`tools` /
+ * `disallowedTools`) is pinned on create AND on every resume path, because
+ * the SDK does not persist it: a resume without it would silently restore the
+ * whole toolset.
+ */
+
+import { describe, it, expect, afterEach, vi } from "vitest";
+import { mkdtempSync, rmSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+vi.mock("@cursor/sdk", () => ({
+  Agent: {
+    create: vi.fn(async () => ({ agentId: "agent-created" })),
+    resume: vi.fn(async () => ({ agentId: "agent-resumed" })),
+  },
+}));
+
+import { Agent } from "@cursor/sdk";
+import type { AgentOptions } from "@cursor/sdk";
+import { SqliteLocalAgentStore } from "@cursor/sdk/sqlite";
+import {
+  createAgent,
+  resumeAgent,
+  resolveAgent,
+  resolveAgentWithTransportRecovery,
+} from "../session-lifecycle.js";
+import type { CreateAgentOptions } from "../session-lifecycle.js";
+import { releaseAllSessionStores } from "../session-store.js";
+
+const tempRoots: string[] = [];
+
+function freshWorkspaceRoot(): string {
+  const dir = mkdtempSync(join(tmpdir(), "stigmer-stateroot-test-"));
+  tempRoots.push(dir);
+  return dir;
+}
+
+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 });
+  }
+});
+
+function lastCreateOptions(): AgentOptions {
+  return vi.mocked(Agent.create).mock.calls.at(-1)![0];
+}
+
+function lastResumeCall(): [string, Partial<AgentOptions> | undefined] {
+  return vi.mocked(Agent.resume).mock.calls.at(-1)! as [string, Partial<AgentOptions> | undefined];
+}
+
+// ---------------------------------------------------------------------------
+// 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
+// agent in the runner's own working directory and loading the "project"
+// 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). 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("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, 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,
+      workspaceDirs: ["/work/repo-a"],
+      workspaceRootDir,
+    });
+
+    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("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",
+      workspaceDirs: ["/work/repo-a"],
+      workspaceRootDir,
+    });
+
+    const [agentId, callOptions] = lastResumeCall();
+    expect(agentId).toBe("agent-123");
+    // 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("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", "/work/repo-c"],
+      workspaceRootDir,
+    });
+
+    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"]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// The tool restriction on create and every resume
+// ---------------------------------------------------------------------------
+
+describe("the built-in tool restriction rides every create and resume", () => {
+  function options(restriction: Pick<CreateAgentOptions, "tools" | "disallowedTools">): CreateAgentOptions {
+    return {
+      apiKey: "key",
+      model: "gpt-test",
+      sessionId: "ses-tools-test",
+      workspaceDirs: ["/work/repo-a"],
+      workspaceRootDir: freshWorkspaceRoot(),
+      ...restriction,
+    };
+  }
+
+  it("createAgent passes tools and disallowedTools as given", async () => {
+    await createAgent(options({ tools: ["read", "grep", "mcp"] }));
+    expect(lastCreateOptions().tools).toEqual(["read", "grep", "mcp"]);
+    expect(lastCreateOptions()).not.toHaveProperty("disallowedTools");
+
+    await createAgent(options({ disallowedTools: ["shell"] }));
+    expect(lastCreateOptions().disallowedTools).toEqual(["shell"]);
+    expect(lastCreateOptions()).not.toHaveProperty("tools");
+  });
+
+  it("an agent with no lists sends neither field (an empty tools would mean no built-ins at all)", async () => {
+    await createAgent(options({}));
+    expect(lastCreateOptions()).not.toHaveProperty("tools");
+    expect(lastCreateOptions()).not.toHaveProperty("disallowedTools");
+  });
+
+  it("resolveAgent re-passes the restriction on resume", async () => {
+    await resolveAgent("agent-123", options({ tools: ["read"], disallowedTools: ["readLints"] }), "local");
+    const [, callOptions] = lastResumeCall();
+    expect(callOptions?.tools).toEqual(["read"]);
+    expect(callOptions?.disallowedTools).toEqual(["readLints"]);
+  });
+
+  it("resolveAgent passes it to the fresh agent created after a failed resume", async () => {
+    vi.mocked(Agent.resume).mockRejectedValueOnce(new Error("agent unknown"));
+    const resolution = await resolveAgent("agent-gone", options({ tools: ["read", "shell"] }), "local");
+    expect(resolution.reason).toBe("created_after_resume_failure");
+    expect(lastCreateOptions().tools).toEqual(["read", "shell"]);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Transport recovery on agent-resolution timeout
+//
+// Regression: a stale HTTP/2 session to the proxy hangs Agent.create/resume
+// forever (prod incident, Jul 2026). The wrapper bounds each attempt, resets
+// the transport on the first expiry, and retries once. Only TimeoutError
+// triggers recovery — deterministic failures must propagate untouched.
+// ---------------------------------------------------------------------------
+
+describe("resolveAgentWithTransportRecovery", () => {
+  const TIMEOUT_MS = 1_000;
+  const hang = () => new Promise<never>(() => {});
+
+  function recoveryOptions(overrides?: {
+    harnessStateId?: string;
+    resetTransport?: () => void;
+  }) {
+    const createOptions: CreateAgentOptions = {
+      apiKey: "key",
+      model: "gpt-test",
+      workspaceDirs: ["/work/repo-a"],
+      sessionId: "ses-recovery-test",
+      workspaceRootDir: freshWorkspaceRoot(),
+    };
+    return {
+      harnessStateId: overrides?.harnessStateId ?? "",
+      createOptions,
+      mode: "local" as const,
+      timeoutMs: TIMEOUT_MS,
+      buildTimeoutMessage: (finalAttempt: boolean) =>
+        finalAttempt ? "final attempt timed out" : "first attempt timed out",
+      resetTransport: overrides?.resetTransport ?? vi.fn(),
+    };
+  }
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("passes the resolution through untouched when the first attempt succeeds", async () => {
+    const resetTransport = vi.fn();
+
+    const resolution = await resolveAgentWithTransportRecovery(
+      recoveryOptions({ resetTransport }),
+    );
+
+    expect(resolution.agentId).toBe("agent-created");
+    expect(resolution.reason).toBe("created_first_execution");
+    expect(resetTransport).not.toHaveBeenCalled();
+  });
+
+  it("resets the transport exactly once and recovers when the first attempt hangs", async () => {
+    vi.useFakeTimers();
+    const resetTransport = vi.fn();
+    vi.mocked(Agent.create).mockImplementationOnce(hang as any);
+
+    const promise = resolveAgentWithTransportRecovery(recoveryOptions({ resetTransport }));
+
+    await vi.advanceTimersByTimeAsync(TIMEOUT_MS + 1);
+    const resolution = await promise;
+
+    expect(resolution.agentId).toBe("agent-created");
+    expect(resetTransport).toHaveBeenCalledTimes(1);
+  });
+
+  it("retries resume-first so a transport hiccup does not discard conversation context", async () => {
+    vi.useFakeTimers();
+    const resetTransport = vi.fn();
+    vi.mocked(Agent.resume).mockImplementationOnce(hang as any);
+
+    const promise = resolveAgentWithTransportRecovery(
+      recoveryOptions({ harnessStateId: "agent-prior-turn", resetTransport }),
+    );
+
+    await vi.advanceTimersByTimeAsync(TIMEOUT_MS + 1);
+    const resolution = await promise;
+
+    // The load-bearing assertion: the retry went through Agent.resume again
+    // (only the transport was suspect, not the agent handle), so the native
+    // conversation context survives the recovery.
+    expect(resolution.reason).toBe("resumed_successfully");
+    expect(resolution.agentId).toBe("agent-resumed");
+    expect(resetTransport).toHaveBeenCalledTimes(1);
+  });
+
+  it("rejects with the final-attempt message when both attempts hang; transport reset only once", async () => {
+    vi.useFakeTimers();
+    const resetTransport = vi.fn();
+    vi.mocked(Agent.create)
+      .mockImplementationOnce(hang as any)
+      .mockImplementationOnce(hang as any);
+
+    const promise = resolveAgentWithTransportRecovery(recoveryOptions({ resetTransport }));
+    const rejection = expect(promise).rejects.toThrow("final attempt timed out");
+
+    await vi.advanceTimersByTimeAsync(TIMEOUT_MS + 1); // first attempt expires
+    await vi.advanceTimersByTimeAsync(TIMEOUT_MS + 1); // retry expires
+    await rejection;
+
+    expect(resetTransport).toHaveBeenCalledTimes(1);
+  });
+
+  it("propagates a non-timeout error immediately without touching the transport", async () => {
+    const resetTransport = vi.fn();
+    const authFailure = new Error("401 unauthorized");
+    vi.mocked(Agent.create).mockRejectedValueOnce(authFailure);
+
+    await expect(
+      resolveAgentWithTransportRecovery(recoveryOptions({ resetTransport })),
+    ).rejects.toBe(authFailure);
+
+    expect(resetTransport).not.toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,220 @@
+/**
+ * Unit tests for `session-store.ts`: where a session's Cursor SDK store lives,
+ * and the lifetime the runner owns for it (stigmer/stigmer#1053).
+ *
+ * The location rules are correctness-critical: the state root 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 never collide.
+ *
+ * The lifetime rules are what a revert of the adapter's release hooks would
+ * break: one open per session however many activities ask, the SAME instance
+ * on every ask, a release that disposes and forgets so the next ask reopens, a
+ * failed open that is not remembered, and a re-acquire under a different root
+ * that releases the store it held. `SessionStores` takes the opener, so these
+ * run against a recording fake and no SQLite file.
+ */
+
+import { describe, it, expect, afterEach } from "vitest";
+import { mkdtempSync, rmSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { SessionStores, resolveSessionStoreLocation, type ReleasableStore, type SessionStoreLocation } from "../session-store.js";
+
+const tempRoots: string[] = [];
+
+function freshWorkspaceRoot(): string {
+  const dir = mkdtempSync(join(tmpdir(), "stigmer-session-store-test-"));
+  tempRoots.push(dir);
+  return dir;
+}
+
+afterEach(() => {
+  for (const dir of tempRoots.splice(0)) {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+describe("resolveSessionStoreLocation", () => {
+  it("derives the state root under the workspace volume (not $HOME), created eagerly", () => {
+    const workspaceRootDir = freshWorkspaceRoot();
+    const location = resolveSessionStoreLocation("ses-123", workspaceRootDir);
+
+    expect(location.stateRoot).toBe(join(workspaceRootDir, ".stigmer", "cursor-sdk-state", "ses-123"));
+    expect(location.stateRoot.startsWith(workspaceRootDir)).toBe(true);
+    // Created eagerly to prevent ENOENT on the SDK's first write.
+    expect(existsSync(location.stateRoot)).toBe(true);
+    expect(location.workspaceRef).toBe("stigmer-session:ses-123");
+  });
+
+  it("isolates two sessions sharing one workspace volume into distinct stores", () => {
+    const workspaceRootDir = freshWorkspaceRoot();
+    const a = resolveSessionStoreLocation("ses-aaa", workspaceRootDir);
+    const b = resolveSessionStoreLocation("ses-bbb", workspaceRootDir);
+
+    expect(a.stateRoot).not.toBe(b.stateRoot);
+    expect(a.workspaceRef).not.toBe(b.workspaceRef);
+    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(() => resolveSessionStoreLocation("", workspaceRootDir)).toThrow(/sessionId is required/);
+  });
+
+  it("throws on an empty workspaceRootDir (state must live on the durable volume)", () => {
+    expect(() => resolveSessionStoreLocation("ses-123", "")).toThrow(/workspaceRootDir is required/);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// The lifetime
+// ---------------------------------------------------------------------------
+
+class FakeStore implements ReleasableStore {
+  disposeCalls = 0;
+  constructor(readonly location: SessionStoreLocation) {}
+  get stateRoot(): string {
+    return this.location.stateRoot;
+  }
+  async dispose(): Promise<void> {
+    this.disposeCalls++;
+  }
+}
+
+/** A recording opener; `failNext` makes the next open reject once. */
+function recordingOpener() {
+  const opened: FakeStore[] = [];
+  let failNext: Error | undefined;
+  const open = async (location: SessionStoreLocation): Promise<FakeStore> => {
+    if (failNext) {
+      const err = failNext;
+      failNext = undefined;
+      throw err;
+    }
+    const store = new FakeStore(location);
+    opened.push(store);
+    return store;
+  };
+  return { open, opened, fail: (err: Error) => (failNext = err) };
+}
+
+describe("SessionStores", () => {
+  it("opens once per session and hands the same instance to every later acquire, concurrent ones included", async () => {
+    const workspaceRootDir = freshWorkspaceRoot();
+    const { open, opened } = recordingOpener();
+    const stores = new SessionStores(open);
+
+    // Two activities racing on one session (the agent cache's documented race).
+    const [a, b] = await Promise.all([
+      stores.acquire("ses-1", workspaceRootDir),
+      stores.acquire("ses-1", workspaceRootDir),
+    ]);
+    const c = await stores.acquire("ses-1", workspaceRootDir);
+
+    expect(opened).toHaveLength(1);
+    expect(a).toBe(b);
+    expect(b).toBe(c);
+    expect(a.location.workspaceRef).toBe("stigmer-session:ses-1");
+    expect(stores.size).toBe(1);
+  });
+
+  it("keeps one store per session, not one per process", async () => {
+    const workspaceRootDir = freshWorkspaceRoot();
+    const { open, opened } = recordingOpener();
+    const stores = new SessionStores(open);
+
+    const a = await stores.acquire("ses-a", workspaceRootDir);
+    const b = await stores.acquire("ses-b", workspaceRootDir);
+
+    expect(opened).toHaveLength(2);
+    expect(a).not.toBe(b);
+    expect(stores.size).toBe(2);
+  });
+
+  it("release disposes the session's store and forgets it, so a later acquire reopens", async () => {
+    const workspaceRootDir = freshWorkspaceRoot();
+    const { open, opened } = recordingOpener();
+    const stores = new SessionStores(open);
+
+    const first = await stores.acquire("ses-1", workspaceRootDir);
+    await stores.release("ses-1");
+
+    expect(first.disposeCalls).toBe(1);
+    expect(stores.size).toBe(0);
+
+    const second = await stores.acquire("ses-1", workspaceRootDir);
+    expect(second).not.toBe(first);
+    expect(opened).toHaveLength(2);
+  });
+
+  it("release of a session with no store is a no-op", async () => {
+    const { open, opened } = recordingOpener();
+    const stores = new SessionStores(open);
+
+    await expect(stores.release("ses-unknown")).resolves.toBeUndefined();
+    expect(opened).toHaveLength(0);
+  });
+
+  it("releaseAll disposes every held store and empties the map (worker shutdown)", async () => {
+    const workspaceRootDir = freshWorkspaceRoot();
+    const { open, opened } = recordingOpener();
+    const stores = new SessionStores(open);
+
+    await stores.acquire("ses-a", workspaceRootDir);
+    await stores.acquire("ses-b", workspaceRootDir);
+    await stores.releaseAll();
+
+    expect(opened.map((s) => s.disposeCalls)).toEqual([1, 1]);
+    expect(stores.size).toBe(0);
+  });
+
+  it("does not remember a failed open: the next acquire retries", async () => {
+    const workspaceRootDir = freshWorkspaceRoot();
+    const { open, opened, fail } = recordingOpener();
+    const stores = new SessionStores(open);
+
+    fail(new Error("disk full"));
+    await expect(stores.acquire("ses-1", workspaceRootDir)).rejects.toThrow("disk full");
+    expect(stores.size).toBe(0);
+
+    const store = await stores.acquire("ses-1", workspaceRootDir);
+    expect(opened).toEqual([store]);
+    expect(stores.size).toBe(1);
+  });
+
+  it("a re-acquire under a different workspace volume releases the held store and opens the new one", async () => {
+    const rootA = freshWorkspaceRoot();
+    const rootB = freshWorkspaceRoot();
+    const { open, opened } = recordingOpener();
+    const stores = new SessionStores(open);
+
+    const onA = await stores.acquire("ses-1", rootA);
+    const onB = await stores.acquire("ses-1", rootB);
+
+    // The handle for the old binding can never serve the new one (the same
+    // rule the agent cache applies to a fingerprint mismatch).
+    expect(onB).not.toBe(onA);
+    expect(onA.disposeCalls).toBe(1);
+    expect(onB.stateRoot.startsWith(rootB)).toBe(true);
+    expect(opened).toHaveLength(2);
+    expect(stores.size).toBe(1);
+  });
+
+  it("a dispose that throws is swallowed: the store is forgotten either way", async () => {
+    const workspaceRootDir = freshWorkspaceRoot();
+    const stores = new SessionStores(async (location) => {
+      const store = new FakeStore(location);
+      store.dispose = async () => {
+        throw new Error("handle already closed");
+      };
+      return store;
+    });
+
+    await stores.acquire("ses-1", workspaceRootDir);
+    await expect(stores.release("ses-1")).resolves.toBeUndefined();
+    expect(stores.size).toBe(0);
+  });
+});