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

package/src/__test-utils__/hermetic-activity.ts

@@ -14,7 +14,7 @@
  * and driven by the framework's own activity environment. Both harnesses now
  * run on it (`execute-cursor/__test-utils__/hermetic-cursor.ts`,
  * `execute-deep-agent/__test-utils__/hermetic-deep-agent.ts`), and the earlier
- * native tests were re-homed onto the native driver (S3 M0), their assertions
+ * native tests were re-homed onto the native driver (#1096), their assertions
  * carried into `execute-deep-agent/__tests__/hermetic/`.
  *
  * What is generic here and what is not: everything an activity touches that is
@@ -55,11 +55,22 @@
  * Determinism: the clock is faked for `Date` ONLY (`vi.useFakeTimers({ toFake:
  * ["Date"] })`) and TICKS — the harness double advances it a fixed quantum per
  * script step through {@link ScriptedClock}. Frozen time would make
- * `delta-enricher.ts`'s persist debounce (`Date.now() - lastPersistTime`) never
+ * the streaming scheduler's cadence (`Date.now()` against its last send) never
  * elapse and silently skip the mid-stream persist path production always runs;
  * a ticking clock runs the same path and lands on the same instants every run.
  * Timers stay real so the periodic heartbeat and the stall watchdog behave.
  *
+ * The live posture (#1097's live-run gate): a `CURSOR_API_KEY`-gated live
+ * instrument keeps all three substitutions above — the real `Context`, the
+ * record behind the client, the temp environment — and drops only the
+ * harness's SDK double, so the REAL activity runs against the REAL vendor SDK
+ * with everything the activity persists still readable from the record.
+ * Two things differ from a hermetic run and both are the caller's explicit
+ * choice: no `ScriptedClock` is installed (the real SDK is not ticked, and a
+ * frozen clock would skip the persist cadence production runs), and the
+ * environment may name an `eventRecordingDir` so the run leaves a recording.
+ * The harness's driver names the entry (`beginLiveCursorScenario`).
+ *
  * Not in scope: this module never edits a production module and never
  * normalizes output. If a golden is not byte-stable, the volatile source is
  * controlled at its origin or the surprise is escalated — never redacted here.
@@ -151,6 +162,8 @@ export class ExecutionRecord {
   private readonly controlSignal: (status: AgentExecutionStatus) => ExecutionControlSignal;
   /** Every `updateStatus` payload, in order, snapshotted at write time. */
   readonly persisted: AgentExecutionStatus[] = [];
+  /** Fired after every full-status `applyStatusUpdate`; {@link whenToolCallsSettled} subscribes here. */
+  private readonly persistListeners = new Set<() => void>();
   /** Setup-progress labels reported before the stream started, in order. */
   readonly setupProgress: string[] = [];
   /**
@@ -205,6 +218,78 @@ export class ExecutionRecord {
     return this.execution.status?.messages.flatMap((m) => m.toolCalls) ?? [];
   }
 
+  /**
+   * Resolves once every one of `ids` is a SETTLED row (not RUNNING) in a status
+   * the activity has persisted — root messages and every sub-agent's alike.
+   * Resolves at once for an empty list or when they already are.
+   *
+   * This is the barrier a real model gives the runtime for free and a
+   * scripted one does not: a model that takes 300 ms to answer never starts
+   * its next turn before the loop has folded and persisted the tool results
+   * it is answering, while `ScriptedModel` answers instantly and LangGraph's
+   * producer can run a whole turn ahead of the consumer while the consumer
+   * awaits one mid-stream persist (on a git workspace that persist shells out
+   * for `file_change_progress`). The stamps the consumer writes at apply time
+   * then land on either side of the scripted clock's next tick depending on
+   * I/O timing — a golden that flips between `:01` and `:02` on the day. The
+   * driver awaits this before it ticks (`hermetic-deep-agent.ts`), so every
+   * stamp of turn N precedes turn N+1's instant, run after run.
+   *
+   * Why "settled" and not "seen": the row's `completedAt` is stamped when the
+   * tool's end event is applied, and the producer calls the next model turn
+   * right after emitting that event, so a barrier on the row merely existing
+   * would still race the completion stamp. The persist that carries the
+   * settled row always exists: a tool's finish forces one (the builder's
+   * force flag), and a turn followed by another turn always has a tool call.
+   *
+   * Bounded by real time (timers are real under the scripted clock): a
+   * scenario that breaks the fact above — a persist that never carries the
+   * row — fails naming the ids still open, never hangs.
+   */
+  whenToolCallsSettled(ids: readonly string[], timeoutMs = 10_000): Promise<void> {
+    const unsettled = (): string[] => {
+      const settled = this.settledToolCallIds();
+      return ids.filter((id) => !settled.has(id));
+    };
+    if (unsettled().length === 0) return Promise.resolve();
+
+    return new Promise<void>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.persistListeners.delete(check);
+        reject(
+          new Error(
+            `ExecutionRecord: tool call(s) ${unsettled().join(", ")} never settled in a persisted status ` +
+              `within ${timeoutMs} ms (${this.persisted.length} persists seen). A model turn was asked to ` +
+              `wait for the results it answers; the loop never persisted them — a scenario or runtime bug.`,
+          ),
+        );
+      }, timeoutMs);
+      const check = (): void => {
+        if (unsettled().length > 0) return;
+        clearTimeout(timer);
+        this.persistListeners.delete(check);
+        resolve();
+      };
+      this.persistListeners.add(check);
+    });
+  }
+
+  /** The ids of every row not RUNNING in the held status, across the root and every sub-agent transcript. */
+  private settledToolCallIds(): Set<string> {
+    const out = new Set<string>();
+    const status = this.execution.status;
+    if (!status) return out;
+    const transcripts = [status.messages, ...status.subAgentExecutions.map((s) => s.messages)];
+    for (const messages of transcripts) {
+      for (const message of messages) {
+        for (const tc of message.toolCalls) {
+          if (tc.status !== ToolCallStatus.TOOL_CALL_RUNNING) out.add(tc.id);
+        }
+      }
+    }
+    return out;
+  }
+
   /** The tool calls currently paused for a decision. */
   waitingToolCalls(): ToolCall[] {
     return this.toolCalls().filter((tc) => tc.status === ToolCallStatus.TOOL_CALL_WAITING_APPROVAL);
@@ -254,6 +339,7 @@ export class ExecutionRecord {
       return ExecutionControlSignal.UNSPECIFIED;
     }
     this.execution.status = clone(AgentExecutionStatusSchema, snapshot);
+    for (const listener of [...this.persistListeners]) listener();
     return this.controlSignal(snapshot);
   }
 
@@ -343,14 +429,30 @@ export function hermeticStigmerClientModule(): { StigmerClient: new () => Stigme
  *    (an absent store flips capture off — a different code path).
  *  - `STIGMER_RUNNER_HITL_SECRET`: the one randomness source on the activity
  *    path, pinned so grant tokens and fingerprints are byte-stable.
- *  - `CURSOR_EVENT_RECORD_DIR` cleared: never write recordings from a test.
+ *  - `CURSOR_EVENT_RECORD_DIR` cleared: never write recordings from a test —
+ *    unless the caller names an `eventRecordingDir`, the live instruments'
+ *    opt-in (below), in which case this environment SETS it. Either way the
+ *    variable has one owner here, and dispose restores it.
  */
 const PINNED_ENV = {
   ARTIFACT_STORAGE_TYPE: "local",
   STIGMER_RUNNER_HITL_SECRET: "hermetic-fixture-secret-do-not-use-in-production",
 } as const;
 
-const CLEARED_ENV = ["CURSOR_EVENT_RECORD_DIR", "STIGMER_PROXY_ENDPOINT", "STIGMER_CLOUD_API_URL"] as const;
+const CLEARED_ENV = ["STIGMER_PROXY_ENDPOINT", "STIGMER_CLOUD_API_URL"] as const;
+
+/** The one name the Cursor recorder is switched on by (`turn-settle.ts` reads it). */
+const CURSOR_EVENT_RECORD_DIR = "CURSOR_EVENT_RECORD_DIR";
+
+export interface HermeticEnvironmentOptions {
+  /**
+   * Where the Cursor event recorder writes this run's raw SDK recording
+   * (`<dir>/<executionId>.cursor-events.jsonl`). Named ONLY by a live
+   * instrument, whose point is a recording of the real SDK; a hermetic
+   * scenario leaves it unset and the variable is cleared for the run.
+   */
+  readonly eventRecordingDir?: string;
+}
 
 export interface HermeticEnvironment {
   /** The temp `HOME` (the runner's `~/.stigmer` lands under it). */
@@ -368,7 +470,7 @@ export interface HermeticEnvironment {
  * `beforeAll`) — the fingerprint secret is memoized per process on first use,
  * and vitest isolates files in forks, so per-file is the natural unit.
  */
-export function createHermeticEnvironment(): HermeticEnvironment {
+export function createHermeticEnvironment(options: HermeticEnvironmentOptions = {}): HermeticEnvironment {
   const root = mkdtempSync(join(tmpdir(), "stigmer-hermetic-"));
   const home = join(root, "home");
   const workspaceRootDir = join(root, "workspaces");
@@ -384,6 +486,7 @@ export function createHermeticEnvironment(): HermeticEnvironment {
   set("LOCAL_ARTIFACT_PATH", artifactPath);
   for (const [k, v] of Object.entries(PINNED_ENV)) set(k, v);
   for (const k of CLEARED_ENV) set(k, undefined);
+  set(CURSOR_EVENT_RECORD_DIR, options.eventRecordingDir);
 
   let disposed = false;
   return {
@@ -411,15 +514,16 @@ export function createHermeticEnvironment(): HermeticEnvironment {
  * advance together; timers stay real (the periodic heartbeat, the stall
  * watchdog, `withTimeout` all need them). The harness double calls
  * {@link ScriptedClock.tick} once per script step, so every clock-based
- * decision on the activity path — status timestamps, the enricher's persist
- * debounce, cache TTLs (`Date`); the streaming scheduler's persist cadence
+ * decision on the activity path — status timestamps, the builder's row
+ * instants, cache TTLs (`Date`); the streaming scheduler's persist cadence
  * (`performance.now()`) — sees the same instants run after run and runs the
  * same branches production runs.
  *
- * Why both (S3 M5, Q-M5-7; F-M2a-20): until M5 only `Date` was faked, so the
+ * Why both (since #1096): until then only `Date` was faked, so the
  * scheduler paced persists on REAL elapsed time and `fileChangeProgress`,
  * which rides persists, could gain or lose a capture under load — a golden
- * flake seen twice across S3. One clock, two faces: `tick` advances through
+ * flake seen twice while the native adapter moved onto the runtime. One clock,
+ * two faces: `tick` advances through
  * the fake clock's own `tick` (`vi.advanceTimersByTime`), which moves both
  * `Date` and `performance.now()`; `vi.setSystemTime` would move `Date` alone
  * (fake-timers keeps `performance` monotonic across a system-time jump), so

package/src/__test-utils__/model-registry-fixture.ts

@@ -23,6 +23,15 @@
  * never consulted and adding an entry is byte-invisible to the other
  * harness's goldens (verified when the native entry landed: Cursor's
  * seventeen unchanged).
+ *
+ * The live posture (`stubRegistryFetch({ live: true })`): a live instrument
+ * runs the real activity against the REAL `@cursor/sdk`, whose cloud-api
+ * client (`Cursor.models.list`, the user-key token exchange) goes through
+ * global `fetch` — only its Connect RPC stream rides connect-node. Such a run
+ * keeps this document for the registry (pricing and tier stay pinned; nothing
+ * a live turn proves lives there) and lets every other URL reach the network
+ * through the `fetch` that was global before the stub. The refusal stays the
+ * default: a hermetic run that grows a network dependency must still fail.
  */
 
 import { vi } from "vitest";
@@ -76,21 +85,36 @@ export const REGISTRY_DOCUMENT = {
   ],
 } as const;
 
+export interface StubRegistryFetchOptions {
+  /**
+   * The live posture (header): every URL that is not the registry reaches the
+   * network through the pre-stub `fetch`. Default false — refuse, and fail the
+   * run.
+   */
+  readonly live?: boolean;
+}
+
 /**
- * Stub `fetch` to answer the registry document and refuse everything else.
- * Returns the URLs fetched, for the "no other network" assertion.
+ * Stub `fetch` to answer the registry document and — by default — refuse
+ * everything else. Returns the URLs fetched, for the "no other network"
+ * assertion (and, in the live posture, for the record of what a real turn
+ * dialled).
  */
-export function stubRegistryFetch(): { readonly urls: string[]; restore(): void } {
+export function stubRegistryFetch(options: StubRegistryFetchOptions = {}): { readonly urls: string[]; restore(): void } {
   const urls: string[] = [];
+  const networkFetch = globalThis.fetch;
   vi.stubGlobal(
     "fetch",
-    vi.fn(async (input: string | URL | Request) => {
+    vi.fn(async (input: string | URL | Request, init?: RequestInit) => {
       const url = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
       urls.push(url);
-      if (!url.includes("/model-registry")) {
-        throw new Error(`hermetic run attempted a non-registry network call: ${url}`);
+      if (url.includes("/model-registry")) {
+        return { ok: true, status: 200, json: async () => REGISTRY_DOCUMENT } as unknown as Response;
+      }
+      if (options.live) {
+        return networkFetch(input, init);
       }
-      return { ok: true, status: 200, json: async () => REGISTRY_DOCUMENT } as unknown as Response;
+      throw new Error(`hermetic run attempted a non-registry network call: ${url}`);
     }),
   );
   return { urls, restore: () => vi.unstubAllGlobals() };

package/src/__test-utils__/module-specifiers.ts

@@ -2,11 +2,14 @@
  * The module specifiers a TypeScript file names, read off its syntax tree —
  * the primitive behind the runner's import fences.
  *
- * Two fences stand on it: `src/harness/` and production `src/shared/` never
+ * Three fences stand on it: `src/harness/` and production `src/shared/` never
  * import `src/activities/` (`harness/__tests__/import-direction.test.ts`,
- * the rule the turn runtime is written under), and the Cursor adapter never
+ * the rule the turn runtime is written under); the Cursor adapter never
  * imports `@temporalio/*` (`execute-cursor/__tests__/adapter-is-temporal-
- * free.test.ts`, what lets the contract kit run it outside an activity).
+ * free.test.ts`, what lets the contract kit run it outside an activity); and
+ * `src/harness/transcript/` names no package outside a short allow-list
+ * (`harness/__tests__/transcript-is-engine-free.test.ts`, what keeps the one
+ * transcript builder engine-neutral).
  *
  * A syntax tree, not a regex, so a path quoted in a header comment cannot
  * trip a fence, and no import form can slip past one: static, type-only,
@@ -84,6 +87,32 @@ export function packageImports(filePath: string, source: string, pkg: string): s
   return moduleSpecifiers(filePath, source).filter((specifier) => specifier === pkg || specifier.startsWith(`${pkg}/`));
 }
 
+/**
+ * The packages `source` names — every specifier that is neither a relative
+ * path nor a `node:` builtin, reduced to its package (`@scope/name` or
+ * `name`, the subpath dropped), deduplicated, in first-appearance order.
+ *
+ * What an ALLOW-list fence compares against, where `packageImports` serves a
+ * deny: a deny-list must be extended for every SDK that does not exist yet,
+ * an allow-list refuses it on the day it is written.
+ */
+export function packageNames(filePath: string, source: string): string[] {
+  const names = new Set<string>();
+  for (const specifier of moduleSpecifiers(filePath, source)) {
+    if (specifier.startsWith(".") || specifier.startsWith("node:")) continue;
+    names.add(packageName(specifier));
+  }
+  return [...names];
+}
+
+/** `@scope/name/sub/path` → `@scope/name`; `name/sub/path` → `name`. */
+function packageName(specifier: string): string {
+  const parts = specifier.split("/");
+  const [first, second] = parts;
+  if (first === undefined) return specifier;
+  return first.startsWith("@") && second !== undefined ? `${first}/${second}` : first;
+}
+
 /** Every `.ts` file under `dir`, sorted, skipping the named directories at any depth. */
 export function typeScriptFilesUnder(dir: string, skipDirectories: ReadonlySet<string>): string[] {
   const files: string[] = [];

package/src/__tests__/harness-boot-order.test.ts

@@ -20,7 +20,7 @@
  * `adapter.ts`'s graph, or a static client import on the registry's, fails
  * the first arm; a `boot` that stopped asserting fails the second.
  *
- * The table has two rows since S3 M2b (2026-09-13): the child boots the
+ * The table has two rows since #1096 (2026-09-13): the child boots the
  * Cursor adapter and then the native deep-agent adapter, whose `boot`
  * registers the deepagents profiles and loads LangChain — after the patch,
  * because it is the second row. A `boot` that reordered the rows, or a

package/src/__tests__/harness-contract.test.ts

@@ -13,7 +13,7 @@
  * halves in its own hermetic file, where the mocks its double needs can be
  * hoisted: the Cursor adapter does so in
  * `activities/execute-cursor/__tests__/hermetic/harness-contract.test.ts`
- * (S2 M4), and the fake's runtime-side half runs in
+ * (since #1070), and the fake's runtime-side half runs in
  * `harness/__tests__/run-turn.test.ts`.
  */
 

package/src/__tests__/runner-manager.test.ts

@@ -33,7 +33,7 @@ describe("mapManagerOptionsToConfig", () => {
     expect(config.checkpointerType).toBe("http");
   });
 
-  it("binds the proxy credential to the runner-token ref, never the control-plane ref (Q-S2-7)", () => {
+  it("binds the proxy credential to the runner-token ref, never the control-plane ref", () => {
     const tokenRef = { current: "control-plane-token" };
     const runnerTokenRef = { current: "control-plane-token" };
     const config = mapManagerOptionsToConfig(

package/src/activities/execute-cursor/__test-utils__/__tests__/scripted-double.test.ts

@@ -1,6 +1,6 @@
 /**
  * The scripted `@cursor/sdk` double's own arms — the surface the harness
- * contract kit's Cursor subject drives, added at S2 M4 beside the golden
+ * contract kit's Cursor subject drives, added in #1070 beside the golden
  * scenarios' declared-up-front surface (which the seventeen goldens prove).
  *
  *  - `arrangeNextTurn` writes the slot the NEXT `send()` consumes, replaces a
@@ -9,17 +9,20 @@
  *  - `nextRunId` names the run the next send will be given, so a script can be
  *    built with matching event ids before the send happens.
  *  - `agentForWorkspaceRef` hands `Agent.create` the agent declared for the
- *    session the create names (via `platform.workspaceRef`), consulted before
- *    the ordered list and registered for `Agent.resume` by id; a create with no
- *    session, or a session the resolver does not know, falls through to the
- *    list as before.
+ *    session the create names (via the `workspaceRef` of the scripted store it
+ *    passes as `local.store`), consulted before the ordered list and
+ *    registered for `Agent.resume` by id; a create with no store, or a session
+ *    the resolver does not know, falls through to the list as before.
+ *  - `ScriptedLocalAgentStore.open` (the `@cursor/sdk/sqlite` double) records
+ *    every open and dispose on the bound SDK, so a scenario can assert the
+ *    adapter's session-store lifetime.
  */
 
 import { describe, it, expect } from "vitest";
 import type { AgentOptions, SDKMessage } from "@cursor/sdk";
 
 import { ScriptedCursorAgent, defaultRunId, sdkEvents, step } from "../scripted-agent.js";
-import { ScriptedCursorSdk } from "../scripted-sdk.js";
+import { ScriptedCursorSdk, ScriptedLocalAgentStore, bindScriptedSdk } from "../scripted-sdk.js";
 
 /** An agent whose declared turns each play the given events and finish. */
 function agent(id: string, turns: SDKMessage[][] = []): ScriptedCursorAgent {
@@ -76,8 +79,14 @@ describe("ScriptedCursorAgent.nextRunId", () => {
 });
 
 describe("ScriptedCursorSdk.agentForWorkspaceRef", () => {
+  // The scripted store carries only the members the runner touches, not the
+  // SDK's whole `LocalAgentStore`, hence the cast — the same one the mocked
+  // module makes when it stands in for `@cursor/sdk/sqlite`.
   const createFor = (workspaceRef: string | undefined): AgentOptions =>
-    ({ apiKey: "k", ...(workspaceRef !== undefined ? { platform: { workspaceRef, stateRoot: "/tmp/x" } } : {}) }) as unknown as AgentOptions;
+    ({
+      apiKey: "k",
+      local: workspaceRef !== undefined ? { store: new ScriptedLocalAgentStore(workspaceRef, "/tmp/x") } : undefined,
+    }) as unknown as AgentOptions;
 
   it("hands out the session's agent before the ordered list and registers it for resume", () => {
     const forSession = agent("session-agent");
@@ -94,9 +103,24 @@ describe("ScriptedCursorSdk.agentForWorkspaceRef", () => {
     expect(sdk.resolutions.map((r) => `${r.kind}:${r.agentId}`)).toEqual(["create:session-agent", "resume:session-agent", "create:listed-agent"]);
   });
 
-  it("a create without a platform ref falls through to the ordered list", () => {
+  it("a create without a store falls through to the ordered list", () => {
     const listed = agent("listed-only");
     const sdk = new ScriptedCursorSdk({ agents: [listed], catalog: [], agentForWorkspaceRef: () => agent("never") });
     expect(sdk.create(createFor(undefined))).toBe(listed);
   });
 });
+
+describe("ScriptedLocalAgentStore (the @cursor/sdk/sqlite double)", () => {
+  it("open hands out a store carrying the ref and root asked for, and records opens and disposes on the bound SDK", async () => {
+    const sdk = new ScriptedCursorSdk({ agents: [], catalog: [] });
+    bindScriptedSdk(sdk);
+
+    const store = await ScriptedLocalAgentStore.open({ workspaceRef: "stigmer-session:ses-9", stateRoot: "/tmp/ses-9" });
+    expect(store.workspaceRef).toBe("stigmer-session:ses-9");
+    expect(store.stateRoot).toBe("/tmp/ses-9");
+    expect(sdk.stores).toEqual([store]);
+
+    await store.dispose();
+    expect(store.disposeCalls).toBe(1);
+  });
+});

package/src/activities/execute-cursor/__test-utils__/contract-subject.ts

@@ -1,7 +1,7 @@
 /**
  * The Cursor harness as a `HarnessContractSubject` — the REAL `createCursorAdapter()`
  * driven through the harness contract kit, with the kit's engine-neutral
- * scenario vocabulary translated onto S0's scripted `@cursor/sdk` double.
+ * scenario vocabulary translated onto the scripted `@cursor/sdk` double (#1048).
  *
  * The sibling of `gateway-substrate.ts` (the Cursor side of the approval
  * contract kit): the kit owns the invariants and the runtime stand-in, this
@@ -59,7 +59,7 @@
  * Every script that does not end in `fail`, `cancelled` or `hang` closes with
  * `finished({ result: <last say> })` so `run.wait()` has an answer.
  *
- * ── Two modelling decisions (S2 M4, Q-M4-4) ─────────────────────────────────
+ * ── Two modelling decisions (#1070) ─────────────────────────────────────────
  * A `propose` for an id this subject has already seen the hook ALLOW emits
  * nothing: the real SDK does not re-run a completed tool on resume — the parked
  * agent's conversation already holds the tool's result. A `propose` whose id
@@ -95,7 +95,7 @@ import type {
 } from "../../../__test-utils__/harness-contract/types.js";
 import type { HermeticEnvironment } from "../../../__test-utils__/hermetic-activity.js";
 import { createCursorAdapter } from "../adapter.js";
-import { resolvePlatformOptions } from "../session-lifecycle.js";
+import { resolveSessionStoreLocation } from "../session-store.js";
 import { hookInputFor, streamArgsFor, STREAM_NAME, type GatedActionKind } from "./cursor-hook-harness.js";
 import { FIXTURE, SDK_CATALOG, hermeticCursorConfig, runWorkspaceHook } from "./hermetic-cursor.js";
 import { ScriptedCursorAgent, sdkEvents, step, type ScriptStep, type ScriptedRun } from "./scripted-agent.js";
@@ -216,9 +216,9 @@ class CursorSubject implements CursorContractSubject {
   private mintAgent(sessionId: string): ScriptedCursorAgent {
     const agent = new ScriptedCursorAgent({ agentId: `agent-kit-${++this.mintCounter}`, turns: [] });
     this.agents.set(sessionId, agent);
-    // The adapter asks the SDK to create an agent for the session under this
-    // ref; the double answers with this agent.
-    const { workspaceRef } = resolvePlatformOptions(sessionId, this.config.workspaceRootDir);
+    // The adapter asks the SDK to create an agent for the session over a store
+    // opened under this ref; the double answers with this agent.
+    const { workspaceRef } = resolveSessionStoreLocation(sessionId, this.config.workspaceRootDir);
     this.agentsByWorkspaceRef.set(workspaceRef, agent);
     return agent;
   }
@@ -248,11 +248,13 @@ class CursorSubject implements CursorContractSubject {
           break;
         case "usage":
           script.push(
+            // The kit's delta leaves a count optional; the SDK's `turn-ended`
+            // states all four, and an absent count is zero, as the pricer reads it.
             step.turnEnded({
-              inputTokens: s.delta.inputTokens,
-              outputTokens: s.delta.outputTokens,
-              cacheReadTokens: s.delta.cacheReadTokens,
-              cacheWriteTokens: s.delta.cacheWriteTokens,
+              inputTokens: s.delta.inputTokens ?? 0,
+              outputTokens: s.delta.outputTokens ?? 0,
+              cacheReadTokens: s.delta.cacheReadTokens ?? 0,
+              cacheWriteTokens: s.delta.cacheWriteTokens ?? 0,
             }),
           );
           break;

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

@@ -0,0 +1,116 @@
+/**
+ * Drive Cursor SDK events through the REAL pair the harness runs in production
+ * — `CursorTranslator` into `TranscriptBuilder` over an `AgentExecutionStatus`
+ * — and hand back what they built. The unit-test seam that replaced
+ * `new <accumulator>(messages, options)` in #1097 (the accumulator folded
+ * rows itself; now the translator emits events and the shared builder folds
+ * them), so the arms that read a row's shape after a sequence of SDK events
+ * keep their shape while the module under them changed.
+ *
+ * The same shape as the native translator's local `feedAll` in
+ * `execute-deep-agent/__tests__/translator-through-builder.test.ts`, shared
+ * here because seven Cursor test files read through it.
+ *
+ * Deltas follow the loop's discipline (`turn-stream.ts`): `observeDelta`
+ * queues, and the queue is drained into the builder after the NEXT stream
+ * event — or at {@link CursorFold.drain} for a caller that wants them applied
+ * now, the settle's own last drain before `finalize()`.
+ */
+
+import { create } from "@bufbuild/protobuf";
+import type { InteractionUpdate, SDKMessage } from "@cursor/sdk";
+import { AgentExecutionStatusSchema, type AgentExecutionStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import type { AgentMessage, ToolCall } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import { TranscriptBuilder } from "../../../harness/transcript/builder.js";
+import { CursorTranslator, type CursorTranslatorOptions } from "../translator.js";
+
+export interface CursorFoldOptions {
+  /** The status to build into; a fresh empty one when omitted. Its `messages` are the translator's seed. */
+  readonly status?: AgentExecutionStatus;
+  /**
+   * An existing `messages` array to build into BY REFERENCE (a test that
+   * hand-built its seeded rows and keeps asserting on the same objects). Wins
+   * over `status`'s own array.
+   */
+  readonly messages?: AgentMessage[];
+  readonly policies?: CursorTranslatorOptions["policies"];
+  readonly leases?: CursorTranslatorOptions["leases"];
+}
+
+export class CursorFold {
+  readonly status: AgentExecutionStatus;
+  readonly translator: CursorTranslator;
+  readonly builder: TranscriptBuilder;
+
+  constructor(options: CursorFoldOptions = {}) {
+    this.status = options.status ?? create(AgentExecutionStatusSchema, {});
+    if (options.messages) this.status.messages = options.messages;
+    this.translator = new CursorTranslator({
+      policies: options.policies ?? new Map(),
+      leases: options.leases ?? { global: false, categories: new Set() },
+      seeded: this.status.messages,
+    });
+    this.builder = new TranscriptBuilder("exec-fold", this.status);
+  }
+
+  /** One stream event, translated and folded, then the deltas queued so far — the loop's order. */
+  event(event: SDKMessage): this {
+    for (const e of this.translator.translate(event)) this.builder.apply(e);
+    this.drain();
+    return this;
+  }
+
+  events(...events: SDKMessage[]): this {
+    for (const e of events) this.event(e);
+    return this;
+  }
+
+  /** One delta, queued — applied at the next {@link event} or {@link drain}. */
+  delta(update: InteractionUpdate): this {
+    this.translator.observeDelta(update);
+    return this;
+  }
+
+  drain(): this {
+    for (const e of this.translator.drainDeltas()) this.builder.apply(e);
+    return this;
+  }
+
+  finalize(): this {
+    this.drain();
+    this.builder.finalize();
+    return this;
+  }
+
+  get messages(): AgentMessage[] {
+    return this.status.messages;
+  }
+
+  /** Every root row, in transcript order. */
+  rows(): ToolCall[] {
+    return this.status.messages.flatMap((m) => m.toolCalls);
+  }
+
+  row(callId: string): ToolCall {
+    const found = this.rows().find((tc) => tc.id === callId);
+    if (!found) throw new Error(`CursorFold: no row ${callId}`);
+    return found;
+  }
+}
+
+/** Fold a sequence of stream events into a fresh transcript; the common one-liner. */
+export function foldCursorEvents(events: readonly SDKMessage[], options: CursorFoldOptions = {}): CursorFold {
+  return new CursorFold(options).events(...events);
+}
+
+/**
+ * A builder over an existing `messages` array, kept BY REFERENCE (the status
+ * is given the array itself, never a copy), so a boundary test that built its
+ * rows by hand can hand them to `reconcileDeniedToolCalls` and keep asserting
+ * on the same objects.
+ */
+export function builderOver(messages: AgentMessage[], executionId = "exec-boundary"): TranscriptBuilder {
+  const status = create(AgentExecutionStatusSchema, {});
+  status.messages = messages;
+  return new TranscriptBuilder(executionId, status);
+}

package/src/activities/execute-cursor/__test-utils__/gateway-substrate.ts

@@ -80,7 +80,7 @@ export function createCursorSubstrate(): GatewaySubstrate {
       enforcesExactContent: true,
       appliesRunLifetimeLease: true,
       // The Cursor hook's deny decision does not carry approval_policy_source;
-      // provenance is projected at message-reconstruction time (message-translator)
+      // provenance is projected at translation time (the Cursor translator)
       // and asserted by the corpus + resolveApprovalProvenance suites instead.
       surfacesGatePolicySource: false,
     },