@stigmer/runner 3.15.3-dev.20260914100347 → 3.15.3-dev.20260916211208

package/src/activities/execute-cursor/cursor-capabilities.ts

@@ -18,7 +18,7 @@
  *  - File review under the `cursor` harness id, with the two files the gate
  *    writes into the repo excluded from the mid-run progress diff
  *    ({@link CURSOR_RUNNER_OWNED_PATHS}). The capture itself is the runtime's
- *    (`harness/capture.ts`, S3 M4); this adapter contributes only the hook
+ *    (`harness/capture.ts`, since #1096); this adapter contributes only the hook
  *    sidecar it binds as the runtime's CAS observations (`turn-setup.ts`).
  */
 

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

@@ -1,57 +1,91 @@
 /**
- * Cursor SDK event recorder for capturing raw SDKMessage events.
+ * The raw recording of the Cursor translator's input — both SDK channels, in
+ * arrival order — for checking the translator against what the real SDK sends.
  *
- * Activated by the CURSOR_EVENT_RECORD_DIR environment variable. When set,
- * the Cursor streaming loop records every SDKMessage and flushes them
- * atomically to a JSONL file after the stream completes.
+ * Off unless `CURSOR_EVENT_RECORD_DIR` is set: `turn-settle.ts` reads the env
+ * once per turn and hands the directory in, so this module touches no process
+ * state and its tests need no env. When off, {@link createCursorEventRecorder}
+ * returns undefined and the loop's `recorder?.record(...)` costs nothing.
  *
- * This is development infrastructure for validating the agent_id-based
- * sub-agent routing hypothesis. The captured events reveal whether
- * sub-agent events carry distinct agent_id values and whether they
- * flow through the parent's run.stream() at all.
+ * Two channels, one sequence. The Cursor SDK hands the runner a turn on two
+ * channels: the discrete `run.stream()` `SDKMessage`s (message boundaries, tool
+ * calls, the result) and the fine-grained `onDelta` `InteractionUpdate`s (text
+ * and thinking tokens, live shell output, tool-call completion instants,
+ * usage). The translator (`translator.ts`) reads both, and the questions a
+ * recording exists to answer — what shape `shell-output-delta` carries, whether
+ * `tool-call-completed` arrives before or after the stream's own completed
+ * `tool_call` — are questions about the ORDER across channels. So the recorder
+ * owns one monotonic `seq` and stamps every line with its `channel`; a reader
+ * sorts nothing, it reads the file top to bottom. Until #1097's live-run gate
+ * this module recorded the stream channel alone, under the loop's own
+ * event counter, which could not place a delta relative to a stream event.
  *
- * Mirrors the native harness's v3-event-recorder.ts / V3_EVENT_RECORD_DIR.
+ * Output: `<dir>/<executionId>.cursor-events.jsonl`, one JSON object per line,
+ * flushed once after the stream completes (`turn-settle.ts`). Payloads pass
+ * through {@link safeClone} so a cyclic event cannot fail the flush. The native
+ * harness's `v3-event-recorder.ts` is the same idea for its one channel.
  */
 
 import { writeFile, mkdir } from "node:fs/promises";
 import { join } from "node:path";
-import type { SDKMessage } from "@cursor/sdk";
+import type { InteractionUpdate, SDKMessage } from "@cursor/sdk";
+
+/** Which of the SDK's two channels a recorded line came from. */
+export type CursorRecordedChannel = "stream" | "delta";
 
 export interface CursorEventRecorder {
-  record(event: SDKMessage, seq: number): void;
+  /** A discrete `run.stream()` event, sequenced with the deltas around it. */
+  record(event: SDKMessage): void;
+  /** An `onDelta` update, sequenced with the stream events around it. */
+  recordDelta(update: InteractionUpdate): void;
+  /** Write every recorded line, once. A no-op when nothing was recorded. */
   flush(): Promise<void>;
 }
 
 /**
- * Create a recorder if CURSOR_EVENT_RECORD_DIR is set, otherwise undefined.
- * The caller does `recorder?.record(event, seq)` — zero overhead when off.
+ * Create a recorder for `recordDir`, or undefined when there is none (the
+ * env var unset or empty) — the caller does `recorder?.record(event)`.
  */
 export function createCursorEventRecorder(
   executionId: string,
+  recordDir: string | undefined,
 ): CursorEventRecorder | undefined {
-  const recordDir = process.env.CURSOR_EVENT_RECORD_DIR;
   if (!recordDir) return undefined;
   return new FileCursorEventRecorder(executionId, recordDir);
 }
 
 class FileCursorEventRecorder implements CursorEventRecorder {
   private readonly lines: string[] = [];
+  /** The one arrival counter both channels share (the header's reason). */
+  private seq = 0;
 
   constructor(
     private readonly executionId: string,
     private readonly outputDir: string,
   ) {}
 
-  record(event: SDKMessage, seq: number): void {
-    const entry = {
-      seq,
-      capturedAt: new Date().toISOString(),
-      type: event.type,
+  record(event: SDKMessage): void {
+    this.append("stream", event.type, {
       agent_id: event.agent_id,
       run_id: event.run_id,
       event: safeClone(event),
-    };
-    this.lines.push(JSON.stringify(entry));
+    });
+  }
+
+  recordDelta(update: InteractionUpdate): void {
+    this.append("delta", update.type, { update: safeClone(update) });
+  }
+
+  private append(channel: CursorRecordedChannel, type: string, payload: Record<string, unknown>): void {
+    this.lines.push(
+      JSON.stringify({
+        seq: this.seq++,
+        capturedAt: new Date().toISOString(),
+        channel,
+        type,
+        ...payload,
+      }),
+    );
   }
 
   async flush(): Promise<void> {
@@ -59,15 +93,10 @@ class FileCursorEventRecorder implements CursorEventRecorder {
 
     await mkdir(this.outputDir, { recursive: true });
 
-    const filePath = join(
-      this.outputDir,
-      `${this.executionId}.cursor-events.jsonl`,
-    );
+    const filePath = join(this.outputDir, `${this.executionId}.cursor-events.jsonl`);
 
     await writeFile(filePath, this.lines.join("\n") + "\n");
-    console.log(
-      `CursorEventRecorder: flushed ${this.lines.length} events to ${filePath}`,
-    );
+    console.log(`CursorEventRecorder: flushed ${this.lines.length} lines to ${filePath}`);
   }
 }
 

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

@@ -65,7 +65,7 @@ interface ProxyConfig {
    * manager's token coordinator), so a rotation reaches the next request
    * without a call into this module. Which credential it is differs per
    * root — the static root's control-plane token, the manager's minted
-   * runner token (Q-S2-7) — and this module never knows which.
+   * runner token — and this module never knows which.
    */
   proxyTokenRef: { readonly current: string | null };
   executionId?: string;

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

@@ -64,7 +64,7 @@ interface Http2InterceptorConfig {
    * installed this interceptor owns the ref and rotates it in place, so a
    * rotation reaches the next `request()` on an already-open session without
    * a call into this module (see fetch-interceptor.ts for the two roots'
-   * bindings, Q-S2-7).
+   * bindings).
    */
   proxyTokenRef: { readonly current: string | null };
 }

package/src/activities/execute-cursor/prompt-builder.ts

@@ -6,7 +6,7 @@
  * user message and persist in the agent's own conversation store; a resumed
  * agent receives only what is per-turn).
  *
- * What is this harness's and what is shared (S3 M5, Q-S3-10 / Q-M5-2):
+ * What is this harness's and what is shared (since #1096):
  *  - Shared through `shared/prompt-sections.ts`: WHICH standing sections
  *    render and in WHAT order (`standingContextSections`) and the input-files
  *    bullet and disclosure lines (`inputFileLines`). Their WORDS come from
@@ -70,7 +70,7 @@ const RUNNER_PATH_MARKERS = [
 ] as const;
 
 // The prompt renders the attachment resolver's own result type — a local
-// structural twin (`AttachmentPromptEntry`) lived here until S3 M5 and the
+// structural twin (`AttachmentPromptEntry`) lived here until #1096 and the
 // projection into it was the one reason `turn-setup.ts` had a
 // `prepareAttachmentPrompt` step; the twin dropped the size, so this
 // harness's input-files line never carried it. One type, one truth: the
@@ -315,7 +315,7 @@ export function buildReinvocationPrompt(
     } else if (action === ApprovalAction.REJECT) {
       // A REJECT denies the tool and the run continues (stigmer#197); the
       // runtime settles its row SKIPPED. Told apart from a SKIP in the prose
-      // so the model reads a refusal, not an omission (S3 M1, Q-S3-2).
+      // so the model reads a refusal, not an omission (since #1096).
       rejected.push(describeApproval(pa));
     }
   }
@@ -566,8 +566,8 @@ export function formatWorkspaceContext(dirs: string[]): string {
 /**
  * The `<input_files>` section: this harness's intro around the shared lines
  * (`prompt-sections.ts` `inputFileLines` says what each bullet and disclosure
- * carries and why). The size on each bullet is new to this harness at S3 M5
- * (Q-M5-3): the twin this builder rendered from had dropped it.
+ * carries and why). The size on each bullet is new to this harness in #1096:
+ * the twin this builder rendered from had dropped it.
  */
 export function formatInputFiles(
   attachments: readonly ResolvedAttachment[],
@@ -755,7 +755,7 @@ export function buildToolApprovalRuleFile(): string {
 // ---------------------------------------------------------------------------
 // Prompt selection — which of the four shapes a turn sends, from how the
 // agent resolved and whether the turn carries adjudicated approvals. Moved
-// from `index.ts` at S2 M3b, body unchanged; `__tests__/build-prompt.test.ts`
+// from `index.ts` in #1070, body unchanged; `__tests__/build-prompt.test.ts`
 // pins every branch.
 // ---------------------------------------------------------------------------
 

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

@@ -3,10 +3,19 @@
  *
  * The first `Agent.create` in a pod pays the SDK's platform construction:
  * four SQLite-backed stores (run/checkpoint/event stores + notifier) whose
- * first use loads the sqlite native binding and compiles the schema
- * migrations. The 2026-07-30 instrumented baseline (issue #209) measured
- * this at ~1.2s of the ~2.4s `resolve_agent` segment, with a 624ms floor —
- * roughly half the cost is per-process warm-up, not per-session work.
+ * first use compiles the schema migrations. The 2026-07-30 instrumented
+ * baseline (issue #209, @cursor/sdk 1.0.13) measured this at ~1.2s of the
+ * ~2.4s `resolve_agent` segment, with a 624ms floor — roughly half the cost
+ * was per-process warm-up, not per-session work. Part of that floor was the
+ * `sqlite3` native binding's load; since 1.0.31 (stigmer/stigmer#1053) the
+ * SDK's stores run on `node:sqlite`, which is inside the Node binary, and the
+ * session's store is opened by the runner itself (`session-store.ts`,
+ * `SqliteLocalAgentStore.open`) rather than through the platform this
+ * warm-up constructs. What this warm-up still saves at 1.0.31 is therefore a
+ * measurement, not a known quantity: its `durationMs` and the cold-start
+ * timeline answer it, and the harness program carries the question of
+ * whether to warm through the store the runner actually opens, or through
+ * the SDK's own `prewarmLocalWorkspace`, or not at all.
  *
  * Pool members idle between boot and claim, so constructing one throwaway
  * platform there moves that per-process cost off the user-visible path.
@@ -32,8 +41,8 @@ export interface SdkWarmupResult {
 
 /**
  * Construct (and abandon) one SDK agent platform on a throwaway temp-dir
- * state root, forcing the sqlite native binding + store schema work to
- * happen now instead of inside the first user-facing `Agent.create`.
+ * state root, forcing the store schema work to happen now instead of inside
+ * the first user-facing `Agent.create`.
  *
  * Total by construction — warm-up is an optimization and must never affect
  * the member's ability to serve. The throwaway state root is a few KB on

package/src/activities/execute-cursor/service-tier.ts

@@ -53,8 +53,7 @@ const AUTO_MODEL_IDS = new Set(["default", "auto"]);
  * the served variant deterministic while leaving effort knobs on their
  * catalog defaults. `fast` changes the per-token price; `thinking` is
  * price-neutral but changes token consumption and must never follow the
- * account default. Sourced from the Cursor catalog survey
- * (stigmer-cloud _projects/2026-08/20260806.04.model-service-tier).
+ * account default. Sourced from a survey of the Cursor catalog (2026-08).
  */
 const FAST_PARAM_ID = "fast";
 const THINKING_PARAM_ID = "thinking";

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

@@ -3,59 +3,63 @@
  *
  * SessionSpec.harness_state_id stores the Cursor agentId. This module handles
  * creating new agents (first execution), resuming existing agents
- * (subsequent executions), graceful fallback on resume failure, and
- * cleaning up agents (session deletion).
+ * (subsequent executions) and graceful fallback on resume failure.
  *
  * Two execution modes:
  *
- * - Local mode: Agent.create({ local: { cwd } }) with explicit
- *   platform.workspaceRef/stateRoot for deterministic store keying.
- *   Produces agent- prefixed IDs.
+ * - Local mode: Agent.create({ local: { cwd, dirs, store, ... } }) over the
+ *   session's own SQLite store (`session-store.ts`). Produces agent- prefixed
+ *   IDs.
  *
  * - Cloud mode (feature-flagged): Agent.create({ cloud: { repos } })
- *   for git-backed workspaces. Produces bc- prefixed IDs. No platform
- *   options — cloud state lives on Cursor's servers, not local SQLite.
+ *   for git-backed workspaces. Produces bc- prefixed IDs. No store — cloud
+ *   state lives on Cursor's servers, not local SQLite.
  *
- * Key SDK limitation: mcpServers are NOT persisted across Agent.resume().
- * They must be passed again on every resume call.
+ * Nothing under `local` survives Agent.resume(): `cwd`, `dirs`,
+ * `settingSources`, `store` and `enableAgentRetries` are re-supplied on every
+ * resume, exactly like `mcpServers`, `agents` and the model params. Omitting
+ * `cwd` re-roots the resumed agent at process.cwd() and loads the "project"
+ * setting source (the .cursor/hooks.json carrying the HITL approval hook) from
+ * the wrong directory, silently disabling the gate on every resumed turn;
+ * omitting `store` would make the SDK look the agent up in a default store
+ * derived from `cwd`, not the one the session's records are in.
  *
- * Platform store keying (local only): The Cursor SDK defaults to
- * process.cwd() for its internal state root lookup. In cloud sandboxes,
- * process.cwd() is the runner's app directory, not the workspace — causing
- * Agent.resume() to fail with "Agent not found". We pass explicit
- * platform.workspaceRef and platform.stateRoot derived from the Stigmer
- * sessionId to ensure deterministic store lookup regardless of process.cwd().
+ * Durability model: the session's SQLite store (agent records, runs,
+ * checkpoints) is the source of truth for conversation continuation. It lives
+ * under the durable workspace volume (`session-store.ts`) so Agent.resume()
+ * survives pod restart, reschedule, and snapshot restore. When resume
+ * nonetheless fails (store lost, corrupted, or agent unknown), this module
+ * creates a fresh agent and the caller starts a new turn from the user message
+ * plus re-injected instructions — there is no separate continuation store.
  *
- * Durability model: the SDK's local SQLite store (agent records, runs,
- * checkpoints) is the source of truth for conversation continuation. It is
- * persisted under the durable workspace volume (see resolvePlatformOptions)
- * so Agent.resume() survives pod restart, reschedule, and snapshot restore.
- * When resume nonetheless fails (store lost, corrupted, or agent unknown),
- * this module creates a fresh agent and the caller starts a new turn from
- * the user message plus re-injected instructions — there is no separate
- * continuation store.
+ * Retries are the runner's, not the SDK's. `@cursor/sdk` 1.0.31 defaults
+ * `enableAgentRetries` to true for headless embedders (1.0.13 defaulted it to
+ * false); the runner already owns recovery from a dead or stalled transport —
+ * `withTimeout` around agent resolution, `resolveAgentWithTransportRecovery`
+ * (reset the transport, retry once), the two recovery spines in
+ * `turn-settle.ts`, and the stall detector — so the SDK's layer is pinned OFF
+ * to keep one retry authority and the 1.0.13 timing of every provider fault.
+ * Whether to adopt the SDK's retries and delete ours is an open design
+ * question for the harness program, recorded there; it is not decided here.
  */
 
-import { mkdirSync } from "node:fs";
-import { join } from "node:path";
-
 import { Agent } from "@cursor/sdk";
 import type {
   SDKAgent,
-  CursorAgentPlatformOptions,
   AgentDefinition,
+  LocalAgentOptions,
   ModelParameterValue,
 } from "@cursor/sdk";
+import type { SqliteLocalAgentStore } from "@cursor/sdk/sqlite";
 import { withTimeout, TimeoutError } from "../../shared/with-timeout.js";
 import type { CloudRepo } from "../../shared/blueprint-resolver.js";
 import type { CursorMcpServerConfig } from "./cursor-mcp-config.js";
+import { sessionStore } from "./session-store.js";
 
 // ---------------------------------------------------------------------------
 // Constants
 // ---------------------------------------------------------------------------
 
-const CURSOR_SDK_STATE_DIR = ".stigmer/cursor-sdk-state";
-
 /**
  * Cursor SDK setting sources loaded for LOCAL agents.
  *
@@ -199,64 +203,41 @@ export interface AgentResolution {
 // ---------------------------------------------------------------------------
 
 /**
- * Compute deterministic platform options for a Stigmer session.
- *
- * workspaceRef is a synthetic identifier (not a filesystem path) that
- * ensures the SDK's platform cache key is stable across activity
- * invocations regardless of process.cwd().
+ * The `local` options a session's agent is created AND resumed with — one
+ * builder so the two calls cannot drift (see the module header for why every
+ * field is re-supplied on resume).
  *
- * stateRoot is a session-isolated directory under the durable workspace
- * volume ({workspaceRootDir}/.stigmer/cursor-sdk-state/{sessionId}) where
- * the SDK persists its SQLite stores (agent records, runs, checkpoints).
- * Placing it on the workspace volume (rather than $HOME) makes native
- * Agent.resume() survive pod restart/reschedule and snapshot restore, and
- * keys it by sessionId so sessions sharing one volume (e.g. the child agent
- * executions of a workflow sandbox) never collide. Created eagerly to
- * prevent ENOENT on first SDK write.
- *
- * Both inputs are required and must be non-empty: the stateRoot is keyed by
- * sessionId, so an empty sessionId would collapse every session sharing the
- * volume onto the same store and corrupt their conversation state.
+ * Workspaces: the SDK takes ONE primary `cwd` (the default shell's directory
+ * and the agent's store scoping) plus `dirs` for the other roots of a
+ * multi-root workspace, merged cwd-first with duplicates dropped, so rules,
+ * skills and hooks load from every root. The session's first workspace
+ * directory is the primary, as it was when the SDK took the whole array.
  */
-export function resolvePlatformOptions(
+async function localAgentOptions(
   sessionId: string,
   workspaceRootDir: string,
-): CursorAgentPlatformOptions {
-  if (!sessionId) {
-    throw new Error(
-      "resolvePlatformOptions: sessionId is required but was empty. The Cursor SDK " +
-      "state store is keyed by sessionId; an empty value would collide across sessions " +
-      "sharing a workspace volume (e.g. a workflow sandbox's child agent executions).",
-    );
-  }
-  if (!workspaceRootDir) {
-    throw new Error(
-      "resolvePlatformOptions: workspaceRootDir is required but was empty. The Cursor " +
-      "SDK state store must live on the durable workspace volume to survive restarts.",
-    );
-  }
-  const stateRoot = join(workspaceRootDir, CURSOR_SDK_STATE_DIR, sessionId);
-  mkdirSync(stateRoot, { recursive: true });
+  workspaceDirs: readonly string[],
+): Promise<LocalAgentOptions & { readonly store: SqliteLocalAgentStore }> {
+  const [cwd, ...dirs] = workspaceDirs;
+  const store = await sessionStore(sessionId, workspaceRootDir);
   return {
-    workspaceRef: `stigmer-session:${sessionId}`,
-    stateRoot,
+    cwd,
+    ...(dirs.length > 0 ? { dirs } : {}),
+    settingSources: [...LOCAL_SETTING_SOURCES],
+    store,
+    // The runner is the one retry authority (module header).
+    enableAgentRetries: false,
   };
 }
 
 /**
  * Create a new local Cursor Agent for the first execution in a session.
- *
- * Supports multi-workspace: passes string[] when multiple dirs, string when single.
  */
 export async function createAgent(options: CreateAgentOptions): Promise<SDKAgent> {
-  const cwd = options.workspaceDirs.length === 1
-    ? options.workspaceDirs[0]
-    : options.workspaceDirs;
-
-  const platform = resolvePlatformOptions(options.sessionId, options.workspaceRootDir);
+  const local = await localAgentOptions(options.sessionId, options.workspaceRootDir, options.workspaceDirs);
   console.log(
-    `createAgent: sessionId=${options.sessionId}, workspaceRef=${platform.workspaceRef}, ` +
-    `stateRoot=${platform.stateRoot}, process.cwd=${process.cwd()}`,
+    `createAgent: sessionId=${options.sessionId}, workspaceRef=${local.store.workspaceRef}, ` +
+    `stateRoot=${local.store.stateRoot}, process.cwd=${process.cwd()}`,
   );
 
   return Agent.create({
@@ -264,10 +245,9 @@ export async function createAgent(options: CreateAgentOptions): Promise<SDKAgent
     // Always a full selection — id AND params. A bare { id } would let the
     // catalog's default variant (account-influenced) pick the price (#357).
     model: { id: options.model, params: options.modelParams },
-    local: { cwd, settingSources: [...LOCAL_SETTING_SOURCES] },
+    local,
     mcpServers: options.mcpServers as Record<string, any>,
     agents: options.agents,
-    platform,
   });
 }
 
@@ -278,14 +258,10 @@ export async function createAgent(options: CreateAgentOptions): Promise<SDKAgent
  * propagate or fall back to a fresh agent with continuation context.
  */
 export async function resumeAgent(options: ResumeAgentOptions): Promise<SDKAgent> {
-  const cwd = options.workspaceDirs.length === 1
-    ? options.workspaceDirs[0]
-    : options.workspaceDirs;
-
-  const platform = resolvePlatformOptions(options.sessionId, options.workspaceRootDir);
+  const local = await localAgentOptions(options.sessionId, options.workspaceRootDir, options.workspaceDirs);
   console.log(
     `resumeAgent: agentId=${options.agentId}, sessionId=${options.sessionId}, ` +
-    `workspaceRef=${platform.workspaceRef}, stateRoot=${platform.stateRoot}, ` +
+    `workspaceRef=${local.store.workspaceRef}, stateRoot=${local.store.stateRoot}, ` +
     `process.cwd=${process.cwd()}`,
   );
 
@@ -296,16 +272,9 @@ export async function resumeAgent(options: ResumeAgentOptions): Promise<SDKAgent
     // ledger, #357), but an id-only resume would fall back to the catalog
     // default variant for the new turns.
     model: options.model ? { id: options.model, params: options.modelParams } : undefined,
-    // Neither cwd nor settingSources survive Agent.resume(); both must be
-    // re-supplied every turn. Omitting cwd makes the SDK fall back to
-    // process.cwd(), which re-roots the agent in the runner's own working
-    // directory and loads the "project" setting source — the .cursor/hooks.json
-    // carrying the HITL approval hook — from that wrong directory, silently
-    // disabling the approval gate on every resumed turn.
-    local: { cwd, settingSources: [...LOCAL_SETTING_SOURCES] },
+    local,
     mcpServers: options.mcpServers as Record<string, any>,
     agents: options.agents,
-    platform,
   });
 }
 
@@ -317,7 +286,7 @@ export async function resumeAgent(options: ResumeAgentOptions): Promise<SDKAgent
  * Create a new cloud Cursor Agent for git-backed sessions.
  *
  * Cloud agents (bc- prefix) run on Cursor's servers with cloned repos.
- * No platform options — cloud state lives server-side, not in local SQLite.
+ * No store — cloud state lives server-side, not in local SQLite.
  * Model is optional — Cursor resolves the caller's configured default
  * when omitted.
  */
@@ -341,7 +310,7 @@ export async function createCloudAgent(options: CreateCloudAgentOptions): Promis
  *
  * Throws on failure — the caller (resolveAgent) decides whether to
  * propagate or fall back to a fresh cloud agent with continuation context.
- * No platform options — cloud state lives server-side.
+ * No store — cloud state lives server-side.
  */
 export async function resumeCloudAgent(options: ResumeCloudAgentOptions): Promise<SDKAgent> {
   console.log(
@@ -365,8 +334,8 @@ export async function resumeCloudAgent(options: ResumeCloudAgentOptions): Promis
  * graceful fallback if resume fails.
  *
  * The mode parameter determines which create/resume functions are used:
- * - "local": createAgent / resumeAgent (with platform options)
- * - "cloud": createCloudAgent / resumeCloudAgent (no platform options)
+ * - "local": createAgent / resumeAgent (over the session's store)
+ * - "cloud": createCloudAgent / resumeCloudAgent (no store)
  *
  * When harnessStateId is non-empty (subsequent execution):
  *   1. Attempt Agent.resume with mode-appropriate options.
@@ -536,18 +505,3 @@ export async function resolveAgentWithTransportRecovery(
     return attempt(true);
   }
 }
-
-/**
- * Dispose a Cursor Agent when a session is deleted.
- * Best-effort: logs and swallows errors.
- */
-export async function disposeAgent(agentId: string, apiKey: string): Promise<void> {
-  try {
-    await Agent.archive(agentId, { apiKey });
-  } catch (err) {
-    console.warn(
-      `Failed to archive Cursor agent ${agentId}:`,
-      err instanceof Error ? err.message : err,
-    );
-  }
-}