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

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

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

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

@@ -15,7 +15,12 @@
  * So a turn is a SCRIPT of ordered steps, one of four kinds:
  *
  *  - `event(SDKMessage)`     — yielded from `stream()`
- *  - `delta(update)`         — fired through `onDelta` (usage, `turn-ended`)
+ *  - `delta(update)`         — fired through `onDelta`: any `InteractionUpdate`
+ *                              (the `turn-ended` usage the loop prices; the
+ *                              tool-call timings, shell output and completion
+ *                              status the transcript folds — #1097 widened
+ *                              the step from `turn-ended` alone so the delta
+ *                              channel has an end-to-end net)
  *  - `effect(fn)`            — the side effect the SDK would have performed
  *                              (run the real hook, write a workspace file,
  *                              cancel the activity from the outside)
@@ -24,16 +29,12 @@
  * The same shape as the native harness's `__test-utils__/scripted-model.ts`
  * (`ScriptStep`, driven in order), applied to the SDK's event surface.
  *
- * Typing: `SDKMessage`, `Run`, `RunResult` and `SDKAgent` are the SDK's own
- * types (`@cursor/sdk` 1.0.13, concrete in `messages.d.ts` / `run.d.ts` /
- * `agent.d.ts`), so a script that drifts from the real event shape fails
- * `tsc`. The delta channel is the exception: `InteractionUpdate` re-exports
- * from `@anysphere/cursor-sdk-shared`, a workspace package the published SDK
- * does not ship, so under `skipLibCheck` it resolves to `any` — in production
- * code too (`turn-stream.ts`, `delta-enricher.ts` read it untyped). The one
- * delta this double emits, the `turn-ended` usage, is therefore typed HERE
- * ({@link TurnEndedUsageDelta}) against what `turn-stream.ts` reads from it,
- * and that gap is recorded in the entry's findings rather than papered over.
+ * Typing: `SDKMessage`, `Run`, `RunResult`, `SDKAgent` and the delta channel's
+ * `InteractionUpdate` are the SDK's own types (`@cursor/sdk` 1.0.31, concrete
+ * in `messages.d.ts` / `run.d.ts` / `agent.d.ts` / the vendored `delta-types`),
+ * so a script that drifts from the real event shape fails `tsc`. (At 1.0.13
+ * the delta types resolved to `any` and the one delta this double emitted was
+ * typed locally; stigmer/stigmer#1053 closed that gap.)
  *
  * Cancellation: `run.cancel()` is how the harness stops a turn (first denial,
  * cost cap, stall). The double honours it the way the SDK does — the stream
@@ -50,6 +51,9 @@
  */
 
 import type {
+  AgentUsage,
+  GetUsageOptions,
+  InteractionUpdate,
   ModelSelection,
   Run,
   RunOperation,
@@ -59,6 +63,7 @@ import type {
   SDKMessage,
   SDKUserMessage,
   SendOptions,
+  TurnEndedUpdate,
 } from "@cursor/sdk";
 import type { ConversationTurn } from "@cursor/sdk";
 
@@ -66,21 +71,6 @@ import type { ConversationTurn } from "@cursor/sdk";
 // Script steps
 // ---------------------------------------------------------------------------
 
-/**
- * The `turn-ended` delta as `turn-stream.ts` reads it (`update.type ===
- * "turn-ended" && update.usage` -> `usageAccumulator.addTurn(update.usage)`).
- * See the module header for why this is typed locally.
- */
-export interface TurnEndedUsageDelta {
-  readonly type: "turn-ended";
-  readonly usage: {
-    readonly inputTokens?: number;
-    readonly outputTokens?: number;
-    readonly cacheWriteTokens?: number;
-    readonly cacheReadTokens?: number;
-  };
-}
-
 /** What an `effect` step can reach: the run it is part of. */
 export interface EffectContext {
   readonly run: ScriptedRun;
@@ -89,7 +79,7 @@ export interface EffectContext {
 
 export type ScriptStep =
   | { readonly kind: "event"; readonly event: SDKMessage }
-  | { readonly kind: "delta"; readonly update: TurnEndedUsageDelta }
+  | { readonly kind: "delta"; readonly update: InteractionUpdate }
   | { readonly kind: "effect"; readonly label: string; readonly run: (ctx: EffectContext) => void | Promise<void> }
   | { readonly kind: "result"; readonly result: Omit<RunResult, "id"> };
 
@@ -101,7 +91,12 @@ export const step = {
   event(event: SDKMessage): ScriptStep {
     return { kind: "event", event };
   },
-  turnEnded(usage: TurnEndedUsageDelta["usage"]): ScriptStep {
+  /** Any delta the SDK fires through `onDelta` between stream events: tool-call timings, shell output, a completion's status. */
+  delta(update: InteractionUpdate): ScriptStep {
+    return { kind: "delta", update };
+  },
+  /** The `turn-ended` delta `turn-stream.ts` prices; the SDK's shape, all four counts stated. */
+  turnEnded(usage: NonNullable<TurnEndedUpdate["usage"]>): ScriptStep {
     return { kind: "delta", update: { type: "turn-ended", usage } };
   },
   effect(label: string, run: (ctx: EffectContext) => void | Promise<void>): ScriptStep {
@@ -145,6 +140,10 @@ export function sdkEvents(agentId: string, runId: string) {
     status(status: "CREATING" | "RUNNING" | "FINISHED" | "ERROR" | "CANCELLED" | "EXPIRED", message?: string): SDKMessage {
       return { type: "status", ...base, status, message };
     },
+    /** The SDK's `task` event: a status line about the run in the agent's own voice, which the transcript shows as a SYSTEM message. */
+    task(text: string, status?: string): SDKMessage {
+      return { type: "task", ...base, text, status };
+    },
   };
 }
 
@@ -224,7 +223,7 @@ export class ScriptedRun implements Run {
           yield s.event;
           break;
         case "delta":
-          await this.onDelta?.({ update: s.update as never });
+          await this.onDelta?.({ update: s.update });
           break;
         case "effect":
           await s.run({ run: this, agent: this.agent });
@@ -365,4 +364,11 @@ export class ScriptedCursorAgent implements SDKAgent {
   async downloadArtifact(_path: string): Promise<Buffer> {
     throw new Error("ScriptedCursorAgent: artifacts are not part of the scripted surface");
   }
+
+  async getUsage(_options?: GetUsageOptions): Promise<AgentUsage> {
+    // The harness prices the `turn-ended` delta itself (`usage-pricing.ts`) and
+    // never asks the SDK for billed usage; a call here is a test bug, like a
+    // `send()` with no script.
+    throw new Error("ScriptedCursorAgent: getUsage() is not part of the scripted surface");
+  }
 }

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

@@ -1,11 +1,16 @@
 /**
  * The `@cursor/sdk` module a hermetic `ExecuteCursor` run imports — every
- * runtime surface the activity path touches, backed by scripted agents.
+ * runtime surface the activity path touches, backed by scripted agents — and
+ * the `@cursor/sdk/sqlite` module beside it, backed by a store that holds
+ * nothing.
  *
- * The activity reaches the SDK at three runtime sites and nowhere else:
+ * The activity reaches the SDK at four runtime sites and nowhere else:
  *
- *  - `session-lifecycle.ts`: `Agent.create(options)`, `Agent.resume(id, options)`,
- *    `Agent.archive(id, ...)` — the agent handle.
+ *  - `session-lifecycle.ts`: `Agent.create(options)`, `Agent.resume(id, options)`
+ *    — the agent handle.
+ *  - `session-store.ts`: `SqliteLocalAgentStore.open({ workspaceRef, stateRoot })`
+ *    from `@cursor/sdk/sqlite` — the session's store the handle is created and
+ *    resumed over (`local.store`).
  *  - `service-tier.ts`: `Cursor.models.list({ apiKey })` — the catalog the
  *    variant params (`fast`, `thinking`) are pinned from.
  *  - `index.ts` outer catch: `import("@cursor/sdk")` for `CursorSdkError`, the
@@ -13,35 +18,42 @@
  *
  * Neither the SDK nor the client is injectable into the activity (the real
  * seam arrives with the harness contract; parent Q1/Q2), so — exactly as the
- * native activity tests already do for their boundary modules — the module is
- * substituted with `vi.mock`. Three existing tests each mock ONE of these
+ * native activity tests already do for their boundary modules — the modules
+ * are substituted with `vi.mock`. Three existing tests each mock ONE of these
  * surfaces (`session-lifecycle.test.ts`, `service-tier.test.ts`,
- * `sdk-warmup.test.ts`); a whole-activity run needs all three at once, which is
- * what this module is.
+ * `sdk-warmup.test.ts`); a whole-activity run needs all of them at once, which
+ * is what this module is.
  *
- * `vi.mock` is hoisted and must appear in the test file; the factory can
- * `await import()` this module and return {@link scriptedCursorSdkModule}. The
- * module's statics read the {@link ScriptedCursorSdk} bound for the current
+ * `vi.mock` is hoisted and must appear in the test file, once per module id
+ * (a subpath is its own module id, so `@cursor/sdk/sqlite` needs its own
+ * `vi.mock`); the factories `await import()` this module and return
+ * {@link scriptedCursorSdkModule} and {@link scriptedCursorSqliteModule}. The
+ * modules' statics read the {@link ScriptedCursorSdk} bound for the current
  * scenario ({@link bindScriptedSdk}), so one test file can run several
- * scenarios with different agents against the same mocked module.
+ * scenarios with different agents against the same mocked modules.
  *
  * Resolution rules a scenario declares, mirroring what the real SDK does:
  *  - `Agent.create` hands out the agent declared for the session it is asked
- *    for (`agentForSession`, when the scenario resolves agents per session —
- *    the harness contract kit runs several sessions concurrently on one
- *    adapter, and the order their creates arrive in is real I/O timing), else
- *    the NEXT unclaimed agent in `agents` (turn 1 of a fresh session; the fresh
- *    agent of a poisoned-handle recovery) — unless the scenario declared a
- *    `createFailure`, which the FIRST create throws instead (the SDK refusing
+ *    for (`agentForWorkspaceRef`, when the scenario resolves agents per
+ *    session — the harness contract kit runs several sessions concurrently on
+ *    one adapter, and the order their creates arrive in is real I/O timing),
+ *    else the NEXT unclaimed agent in `agents` (turn 1 of a fresh session; the
+ *    fresh agent of a poisoned-handle recovery) — unless the scenario declared
+ *    a `createFailure`, which the FIRST create throws instead (the SDK refusing
  *    to mint an agent: a 401 on the key, a validation error).
  *  - `Agent.resume(id)` hands back the agent with that id if the scenario
  *    declared it (in `agents` or `resumableAgents`, or handed out for a
  *    session), else throws — `resolveAgent` then falls back to `create`, which
  *    is the production shape of a lost handle.
  *  - `Cursor.models.list` answers the scenario's catalog.
+ *  - `SqliteLocalAgentStore.open` hands out a {@link ScriptedLocalAgentStore}
+ *    carrying the ref and root it was asked for, and records the open; its
+ *    `dispose()` is recorded too, so a scenario can assert the adapter's
+ *    session-store lifetime (`releaseSession`, `shutdown`).
  */
 
 import type { AgentOptions, ModelListItem, SDKAgent } from "@cursor/sdk";
+import type { SqliteLocalAgentStore, SqliteLocalAgentStoreOptions } from "@cursor/sdk/sqlite";
 import type { ScriptedCursorAgent } from "./scripted-agent.js";
 
 export interface ScriptedSdkOptions {
@@ -50,12 +62,12 @@ export interface ScriptedSdkOptions {
   /**
    * The agent `Agent.create` hands out for the session the create names,
    * consulted before the ordered list. The SDK's create options carry the
-   * session as `platform.workspaceRef` (`session-lifecycle.ts`
-   * `resolvePlatformOptions`: `stigmer-session:<sessionId>`), so the resolver
-   * is keyed by that ref — a scenario computes the ref the same way the
-   * adapter does. `undefined` falls through to the list. Consulted live on
-   * every create, so a scenario may mint the session's agent only when it
-   * learns of the session.
+   * session as the store's `workspaceRef` (`local.store`, opened by
+   * `session-store.ts`: `stigmer-session:<sessionId>`), so the resolver is
+   * keyed by that ref — a scenario computes the ref the same way the adapter
+   * does (`resolveSessionStoreLocation`). `undefined` falls through to the
+   * list. Consulted live on every create, so a scenario may mint the session's
+   * agent only when it learns of the session.
    */
   readonly agentForWorkspaceRef?: (workspaceRef: string) => ScriptedCursorAgent | undefined;
   /**
@@ -82,21 +94,46 @@ export interface RecordedResolution {
 }
 
 /**
- * The `platform.workspaceRef` a create names, read defensively: the platform
- * option's type re-exports from the unshipped `@anysphere/cursor-sdk-local-runtime`
- * and resolves to `any` under `skipLibCheck` (the same gap `scripted-agent.ts`
- * records for the delta channel), so the shape is checked here, not assumed.
+ * The session a create names: the `workspaceRef` of the store it passes as
+ * `local.store`. In a hermetic run that store is the one this module's sqlite
+ * double opened; anything else (a test that mocks `@cursor/sdk` with its own
+ * stub and passes no store) names no session and falls through to the list.
  */
 function workspaceRefOf(options: AgentOptions): string | undefined {
-  const platform: unknown = (options as { platform?: unknown }).platform;
-  if (typeof platform !== "object" || platform === null) return undefined;
-  const ref = (platform as { workspaceRef?: unknown }).workspaceRef;
-  return typeof ref === "string" ? ref : undefined;
+  const store = options.local?.store;
+  return store instanceof ScriptedLocalAgentStore ? store.workspaceRef : undefined;
+}
+
+/**
+ * The `@cursor/sdk/sqlite` store the adapter opens per session, holding
+ * nothing: the scripted agents carry their own state, so the store only has
+ * to be the thing `Agent.create` / `Agent.resume` are handed and the thing
+ * `releaseSession` / `shutdown` dispose. `open` and `dispose` are recorded on
+ * the bound {@link ScriptedCursorSdk} for lifetime assertions.
+ */
+export class ScriptedLocalAgentStore {
+  disposeCalls = 0;
+
+  constructor(
+    readonly workspaceRef: string,
+    readonly stateRoot: string,
+  ) {}
+
+  static async open(options: SqliteLocalAgentStoreOptions): Promise<ScriptedLocalAgentStore> {
+    const store = new ScriptedLocalAgentStore(options.workspaceRef, options.stateRoot ?? "");
+    current().stores.push(store);
+    return store;
+  }
+
+  async dispose(): Promise<void> {
+    this.disposeCalls++;
+  }
 }
 
 export class ScriptedCursorSdk {
   readonly resolutions: RecordedResolution[] = [];
-  readonly archived: string[] = [];
+  /** Every store `SqliteLocalAgentStore.open` handed out, in order. */
+  readonly stores: ScriptedLocalAgentStore[] = [];
   private nextCreate = 0;
   private createFailurePending: boolean;
   private readonly byId = new Map<string, ScriptedCursorAgent>();
@@ -145,10 +182,6 @@ export class ScriptedCursorSdk {
     return agent;
   }
 
-  archive(agentId: string): void {
-    this.archived.push(agentId);
-  }
-
   listModels(): readonly ModelListItem[] {
     return this.options.catalog;
   }
@@ -242,7 +275,6 @@ export function scriptedCursorSdkModule(): Record<string, unknown> {
       create: async (options: AgentOptions): Promise<SDKAgent> => current().create(options),
       resume: async (agentId: string, options?: Partial<AgentOptions>): Promise<SDKAgent> =>
         current().resume(agentId, options),
-      archive: async (agentId: string): Promise<void> => current().archive(agentId),
     },
     Cursor: {
       models: {
@@ -252,3 +284,27 @@ export function scriptedCursorSdkModule(): Record<string, unknown> {
     CursorSdkError: ScriptedCursorSdkError,
   };
 }
+
+/**
+ * The factory a test passes to `vi.mock("@cursor/sdk/sqlite", ...)`, beside
+ * the one above:
+ *
+ * ```ts
+ * vi.mock("@cursor/sdk/sqlite", async () =>
+ *   (await import("../../__test-utils__/scripted-sdk.js")).scriptedCursorSqliteModule(),
+ * );
+ * ```
+ *
+ * The one export the runner reads from that entry (`session-store.ts`). The
+ * class is exported under the SDK's name so `session-store.ts`'s dynamic
+ * import destructures it unchanged; its type is the SDK's, which is why
+ * {@link ScriptedLocalAgentStore} carries `workspaceRef`, `stateRoot` and
+ * `dispose()` — the members the runner touches — and nothing else.
+ */
+export function scriptedCursorSqliteModule(): Record<string, unknown> {
+  return {
+    SqliteLocalAgentStore: ScriptedLocalAgentStore satisfies {
+      open(options: SqliteLocalAgentStoreOptions): Promise<Pick<SqliteLocalAgentStore, "workspaceRef" | "stateRoot" | "dispose">>;
+    },
+  };
+}

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

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

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

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

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

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

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

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