@stigmer/runner 3.15.3-dev.20260914121148 → 3.16.0

package/src/activities/execute-cursor/turn-settle.ts

@@ -1,9 +1,10 @@
 /**
  * The Cursor harness's settle — from a consumed stream to a `TurnOutcome`.
  *
- * In order: the post-stream finalize (transcript, enrichments, sub-agents,
- * the usage snapshot's carrier, the recorder flush, one persist so the UI
- * sees settled rows); the runtime's stop, if it fired, settled as
+ * In order: the post-stream finalize (the last queued deltas drained, the
+ * transcript's streaming flags closed, a stopped turn's sub-agents cancelled,
+ * the recorder flush, one persist so the UI sees settled rows); the runtime's
+ * stop, if it fired, settled as
  * `interrupted` with nothing further; the turn boundary (`turn-boundary.ts`)
  * that overlays the hook's denials as WAITING rows, ending `awaiting_approval`
  * when a denial pauses or failing on an unattributed hook block (#205);
@@ -18,12 +19,15 @@
  * `terminal-table.ts`); capture the turn's file changes or decide whether a
  * review is pending — the runtime's too (`harness/capture.ts`, once over the
  * whole turn after this settle returns, so a recovery's edits reach review
- * without the boundary being re-entered for them; S3 M4). The outcome carries
+ * without the boundary being re-entered for them; since #1096). The outcome carries
  * what the runtime cannot read from the status (`failed`'s message and
- * surface, `cancelled`). It does mutate `sink.status`'s transcript rows,
- * which are this harness's to write.
+ * surface, `cancelled`). The transcript's rows are CREATED through the shared
+ * `TranscriptBuilder` (#1097: this harness's translator emits, the builder
+ * folds; until then the accumulator, the enricher and the todo tracker wrote
+ * them here); the boundary AMENDS rows it owns by identity and proposes its
+ * gate through the same builder.
  *
- * Moved from `index.ts` `executeCursorInner` phases 11 to 13 at S2 M3b; the
+ * Moved from `index.ts` `executeCursorInner` phases 11 to 13 in #1070; the
  * bodies are the orchestrator's, with the runtime's arms taken out.
  */
 
@@ -35,8 +39,8 @@ import { StreamingUsageSummarySchema } from "@stigmer/protos/ai/stigmer/agentic/
 import type { TurnInput, TurnOutcome, TurnSink } from "../../harness/types.js";
 import { TimingRecorder, emitTimingLog } from "../../shared/cold-start-timing.js";
 import { StreamingUpdateScheduler, loadStreamingConfig } from "../../shared/streaming-scheduler.js";
+import { cancelInProgressSubAgentProtos } from "../../shared/subagent-rows.js";
 import { createCursorEventRecorder } from "./cursor-event-recorder.js";
-import { DeltaEnricher } from "./delta-enricher.js";
 import {
   extractRunErrorSources,
   formatClassifiedError,
@@ -44,9 +48,9 @@ import {
   synthesizeError,
 } from "./error-classifier.js";
 import { closeProxySessions } from "./http2-interceptor.js";
-import { MessageAccumulator, collapseRedundantToolCallTwins } from "./message-translator.js";
+import { collapseRedundantToolCallTwins } from "./boundary-rows.js";
 import { clearCapturedRejection, getCapturedRejection } from "./rejection-capture.js";
-import { TodoTracker } from "./todo-tracker.js";
+import { CursorTranslator } from "./translator.js";
 import { runTurnBoundary, type TurnBoundaryResult } from "./turn-boundary.js";
 import {
   consumeCursorTurnStream,
@@ -80,21 +84,32 @@ export async function streamAndSettle(frame: CursorTurnFrame): Promise<TurnOutco
   const { executionId, sessionId, blueprint, workspace, mcp } = input;
   const { status } = sink;
 
-  const deltaEnricher = new DeltaEnricher();
-  const todoTracker = new TodoTracker(status.todos);
-  const eventRecorder = createCursorEventRecorder(executionId);
+  // The runtime's one transcript builder over the turn's status, and this
+  // harness's translator over the run's approval posture and the seeded
+  // transcript (a resumed agent's re-issued call is matched onto its seeded
+  // WAITING row by identity). Both live for the whole turn — the
+  // primary stream and both recovery retries fold into them.
+  const transcript = sink.transcript;
+  const translator = new CursorTranslator({
+    policies: mcp.policies,
+    leases: { global: mcp.leases.global, categories: mcp.leases.categories },
+    seeded: status.messages,
+  });
+  // The raw recording of both SDK channels, on only when the env names a dir
+  // (the recorder reads no process state itself, so its tests need no env).
+  const eventRecorder = createCursorEventRecorder(executionId, process.env.CURSOR_EVENT_RECORD_DIR);
 
   // The two recovery retries (poisoned-handle / transport-timeout) below run at
   // most once per turn; this guard is the latch.
   let alreadyRetriedWithFreshAgent = false;
 
-  // The shared onDelta only needs the sink/pricer/enricher/state subset, and
-  // it is wired at SEND time — before the accumulator exists — so it takes the
-  // narrow deps. The primary send and both retry sends reuse this object.
+  // The shared onDelta needs the sink/pricer/translator/recorder/state subset
+  // and is wired at SEND time. The primary send and both retry sends reuse this object.
   const onDeltaDeps: TurnOnDeltaDeps = {
     sink,
     usagePricer: engine.usagePricer,
-    deltaEnricher,
+    translator,
+    eventRecorder,
     promptEstimatedTokens: prompt.promptEstimatedTokens,
     executionId,
     state: streamState,
@@ -138,15 +153,9 @@ export async function streamAndSettle(frame: CursorTurnFrame): Promise<TurnOutco
 
   // Everything at an index >= this was produced by THIS turn's stream — the
   // positional scope the boundary's #205 attribution and #965 settle read.
-  // Snapshotted before the accumulator can append.
+  // Snapshotted before the builder can append.
   const turnStartMessageIndex = status.messages.length;
 
-  const accumulator = new MessageAccumulator(status.messages, {
-    mergedPolicies: mcp.policies,
-    provenance: { globalBypass: mcp.leases.global, leasedCategories: mcp.leases.categories },
-    workspaceRoot: workspace.primaryDir,
-    subAgentExecutions: status.subAgentExecutions,
-  });
   // Shared cadence with the native harness: discrete state changes force a
   // flush; high-frequency token deltas ride this scheduler's time cadence
   // (env-tunable via STREAMING_* — see loadStreamingConfig).
@@ -156,27 +165,29 @@ export async function streamAndSettle(frame: CursorTurnFrame): Promise<TurnOutco
   // state. Consumed by the primary stream here and by both recovery retries.
   const streamDeps: CursorTurnStreamDeps = {
     ...onDeltaDeps,
-    accumulator,
-    todoTracker,
-    eventRecorder,
     scheduler,
     hitlDir: gate.hitlDir,
   };
 
   // Post-stream finalize, shared by the primary turn and both recovery retries:
-  // finalize the transcript + streaming flags, mark any in-flight sub-agent
-  // CANCELLED on a stopped turn, keep the usage summary's carrier current,
+  // fold the deltas that arrived after the last stream event (a completion
+  // the delta channel reported last was lost before #1097), close every
+  // streaming flag, mark any in-flight sub-agent CANCELLED on a stopped turn,
   // flush the recorder, and persist so the UI sees the settled rows.
   const finalizeStreamPhase = async (): Promise<void> => {
-    accumulator.finalize();
-    deltaEnricher.finalize(status.messages);
+    for (const fact of translator.drainDeltas()) transcript.apply(fact);
+    // The runtime finalizes once `runTurn` returns, on every path; this
+    // harness finalizes EARLIER too because it persists on the settled rows
+    // right below, before `run.wait()` and the boundary, and the console's
+    // spinner must stop before that wait. Idempotent.
+    transcript.finalize();
     // A stopped turn (pause, shutdown, stall, cost cap, platform stop) aborts
     // the Cursor SDK run, so any sub-agent the parent had delegated is no
     // longer executing. Mark it CANCELLED rather than leaving a permanent
-    // IN_PROGRESS "zombie" in the final snapshot (parity with the native
-    // harness's cancelSubAgents()).
+    // IN_PROGRESS "zombie" in the final snapshot, through the one shared act
+    // (parity with the native settle).
     if (sink.stopSignal.aborted) {
-      accumulator.cancelInProgressSubAgents();
+      cancelInProgressSubAgentProtos(status.subAgentExecutions);
     }
     await eventRecorder?.flush();
     console.log(
@@ -196,6 +207,7 @@ export async function streamAndSettle(frame: CursorTurnFrame): Promise<TurnOutco
   const runBoundary = (denialSettled?: Promise<void>): Promise<TurnBoundaryResult> =>
     runTurnBoundary({
       status,
+      transcript,
       executionId,
       hitlDir: gate.hitlDir,
       primaryWorkspaceDir: workspace.primaryDir,

package/src/activities/execute-cursor/turn-setup.ts

@@ -22,7 +22,7 @@
  * resolved, over the runtime's timeline (`sink.setupTiming`), so the one
  * timeline reads end to end.
  *
- * Moved from `index.ts` `executeCursorInner` phases 4c to 10c at S2 M3b; the
+ * Moved from `index.ts` `executeCursorInner` phases 4c to 10c in #1070; the
  * step bodies are the orchestrator's, verbatim where nothing changed.
  */
 
@@ -286,7 +286,7 @@ export async function installGate(input: TurnInput, sink: TurnSink, rows: Adjudi
 /**
  * Resolve the Cursor agent (parked, created, resumed, or created after a
  * resume failure), emit the cold-start line, and bind a NEW agent's id
- * through the sink before anything else runs (Q-S2-11: a rejected bind ends
+ * through the sink before anything else runs (a rejected bind ends
  * the turn `failed`; the sink rejects and the caller's catch names it).
  *
  * The requested name and the effective tier and thinking mode are the
@@ -446,7 +446,7 @@ export async function resolveEngine(input: TurnInput, sink: TurnSink, config: Cu
   // A NEW agent's id is bound at once, before anything else runs, so a crash
   // mid-turn still resumes on the next invocation. The mode is this
   // harness's field on the session record, set before the runtime writes it
-  // (one writer per field, Q-S2-11); the runtime sets harness_state_id and
+  // (one writer per field); the runtime sets harness_state_id and
   // clears the slug.
   if (resolution.isNew && resolution.agentId) {
     if (blueprint.sessionSpec.cursorMode === CursorMode.UNSPECIFIED) {
@@ -459,8 +459,8 @@ export async function resolveEngine(input: TurnInput, sink: TurnSink, config: Cu
       // receives the engine only when this returns) and its id was never
       // saved, so no later turn can resume it: close it here, or its executor
       // lease and MCP subprocesses outlive the failed turn with nothing to
-      // release them (S2 M4, Q-M4-8). Then let the rejection settle the turn
-      // `failed` as R3 rules.
+      // release them (found by the contract kit in #1070). Then let the
+      // rejection settle the turn `failed`, as the contract states.
       try {
         resolution.agent.close();
       } catch {

package/src/activities/execute-cursor/turn-stream.ts

@@ -10,20 +10,29 @@
  * retry froze the UI and mis-handled a mid-retry pause. One loop removes that
  * drift by construction.
  *
+ * The transcript (since #1097): every stream event goes through the harness's
+ * translator (`translator.ts`) into the shared `TranscriptBuilder`
+ * (`harness/transcript/builder.ts`), and the delta channel's facts, which the
+ * translator QUEUES as they arrive in `onDelta`, are drained into the builder
+ * after each stream event — never during an awaited persist, where a row
+ * write would land on a row the offload is replacing.
+ * Until #1097 this loop fed three writers of its own (the message accumulator,
+ * the delta enricher, the todo tracker), the Cursor copy of the folding rule.
+ *
  * What the loop asks of the runtime, through the sink (`harness/types.ts`):
  * `recordActivity()` per event (with the tool name) and per delta, so the
  * runtime's stall watchdog measures the engine; `reportUsage()` per
  * `turn-ended` delta, priced here at the requested variant's rates
  * (`usage-pricing.ts`), so the runtime accounts and enforces the cost cap;
  * `requestPersist()` where a discrete change or the streaming cadence says
- * so (`shared/persist-decision.ts` over this loop's own dirty flags), AWAITED,
+ * so (`shared/persist-decision.ts` over the builder's dirty flag), AWAITED,
  * so a platform STOP the runtime reads from that write aborts the signal
  * before the next event is pulled; and `stopSignal`, checked at every event
  * boundary and listened to inside the pull, where an abort cancels the SDK
  * run — the one way a wedged stream is unblocked, and the same act for every
  * cause of stopping (the runtime knows why; this loop never does).
  *
- * Until S2 M3 this loop armed its own stall watchdog, enforced the cost cap,
+ * Until #1070 this loop armed its own stall watchdog, enforced the cost cap,
  * read STOP from its own persist, and told a pause from the activity's
  * cancellation signal; every one of those is the runtime's now, and the loop
  * reports only `completed`, `first-denial` or `interrupted`.
@@ -33,9 +42,7 @@ import type { SDKMessage, InteractionUpdate } from "@cursor/sdk";
 import type { TurnSink } from "../../harness/types.js";
 import { shouldPersistStreamingStatus } from "../../shared/persist-decision.js";
 import { approvalDenials, readDenialLedger } from "./approval-state.js";
-import type { MessageAccumulator } from "./message-translator.js";
-import type { DeltaEnricher } from "./delta-enricher.js";
-import type { TodoTracker } from "./todo-tracker.js";
+import type { CursorTranslator } from "./translator.js";
 import type { StreamingUpdateScheduler } from "../../shared/streaming-scheduler.js";
 import type { CursorUsagePricer } from "./usage-pricing.js";
 import type { createCursorEventRecorder } from "./cursor-event-recorder.js";
@@ -74,7 +81,7 @@ export interface TurnStreamState {
   denialCancelSettled: Promise<void> | undefined;
   /** Written by: the loop (a stream ERROR status event) + the retry setup (reset). Read by: error classification. */
   streamErrorMessage: string | undefined;
-  /** Written by: the loop. Read by: the event recorder, the persist cadence, and logs. */
+  /** Written by: the loop. Read by: the persist cadence and logs. */
   eventCount: number;
   /** Written + read by: onDelta (log the first turn's context attribution exactly once). */
   firstTurnAttributionLogged: boolean;
@@ -92,24 +99,25 @@ export function newTurnStreamState(): TurnStreamState {
 }
 
 /**
- * The subset of collaborators the shared onDelta needs. Broken out from
- * CursorTurnStreamDeps because the primary send happens BEFORE the accumulator
- * exists — onDelta only touches the sink, the pricer, the enricher, and state.
+ * The subset of collaborators the shared onDelta needs — the sink, the
+ * pricer, the translator (which queues the delta's transcript facts), the
+ * recorder (which sequences the delta with the stream events around it) and
+ * the state. Broken out from CursorTurnStreamDeps so the send that wires
+ * onDelta needs nothing of the stream loop.
  */
 export interface TurnOnDeltaDeps {
   readonly sink: TurnSink;
   /** This harness's pricing of a `turn-ended` delta at the requested variant's rates. */
   readonly usagePricer: CursorUsagePricer;
-  readonly deltaEnricher: DeltaEnricher;
+  readonly translator: CursorTranslator;
+  /** The raw recording of both channels (`cursor-event-recorder.ts`); undefined when recording is off. */
+  readonly eventRecorder: CursorTurnEventRecorder | undefined;
   readonly promptEstimatedTokens: number;
   readonly executionId: string;
   readonly state: TurnStreamState;
 }
 
 export interface CursorTurnStreamDeps extends TurnOnDeltaDeps {
-  readonly accumulator: MessageAccumulator;
-  readonly todoTracker: TodoTracker;
-  readonly eventRecorder: CursorTurnEventRecorder | undefined;
   readonly scheduler: StreamingUpdateScheduler;
   /** Session HITL dir holding the denial ledger; undefined → no gate installed → no first-denial stop. */
   readonly hitlDir: string | undefined;
@@ -119,17 +127,21 @@ export interface CursorTurnStreamDeps extends TurnOnDeltaDeps {
  * Build the shared onDelta callback. The Cursor SDK's fine-grained delta channel
  * carries token usage, live shell output, and precise tool-call timings; it also
  * fires far more often than discrete stream events, so it is where the runtime's
- * stall timer is reset during a long model generation.
+ * stall timer is reset during a long model generation. Usage is priced here
+ * (a loop concern); the transcript facts are the translator's to queue.
  */
 export function makeCursorTurnOnDelta(
   deps: TurnOnDeltaDeps,
 ): (event: { update: InteractionUpdate }) => void {
-  const { sink, usagePricer, deltaEnricher, promptEstimatedTokens, executionId, state } = deps;
+  const { sink, usagePricer, translator, eventRecorder, promptEstimatedTokens, executionId, state } = deps;
   return ({ update }) => {
     // Progress on the delta channel too: a long model generation emits token
     // deltas but few discrete stream events, and resetting only in the stream
     // loop would false-positive a stall.
     sink.recordActivity();
+    // Recorded on arrival, before anything reads it, so the file's order is
+    // the SDK's order across both channels.
+    eventRecorder?.recordDelta(update);
     if (update.type === "turn-ended" && update.usage) {
       // The running estimate advances only here; the runtime enforces the cap
       // and aborts the signal, which the loop reads at the next boundary.
@@ -146,7 +158,7 @@ export function makeCursorTurnOnDelta(
         );
       }
     }
-    deltaEnricher.processDelta(update);
+    translator.observeDelta(update);
   };
 }
 
@@ -164,16 +176,14 @@ export async function consumeCursorTurnStream(
 ): Promise<TurnStreamReason> {
   const {
     sink,
-    accumulator,
-    todoTracker,
-    deltaEnricher,
+    translator,
     eventRecorder,
     scheduler,
     hitlDir,
     executionId,
     state,
   } = deps;
-  const { status, stopSignal } = sink;
+  const { stopSignal, transcript } = sink;
 
   // The runtime's stop, whatever its cause, ends the run through the SDK's
   // own cancel: that is what unblocks a wedged `for await` (a stall), and it
@@ -205,14 +215,13 @@ export async function consumeCursorTurnStream(
       // naming the tool so a stall's copy can say `last tool: shell`.
       sink.recordActivity(event.type === "tool_call" && typeof event.name === "string" ? event.name : undefined);
 
-      eventRecorder?.record(event, state.eventCount);
+      eventRecorder?.record(event);
 
-      accumulator.processEvent(event);
-      todoTracker.processEvent(event);
-
-      if (event.type === "tool_call" && event.name === "task") {
-        accumulator.trackSubAgentExecution(event as Extract<SDKMessage, { type: "tool_call" }>);
-      }
+      // The stream event, then the deltas that arrived since the last one —
+      // the enricher's order, kept so a completion the delta channel reported
+      // in the same window as the stream's own defers to the stream's instant.
+      for (const fact of translator.translate(event)) transcript.apply(fact);
+      for (const fact of translator.drainDeltas()) transcript.apply(fact);
 
       // First-denial stop (HITL clean pause). In CAPTURE mode this fires only for
       // an IRREVERSIBLE tool the hook still gates (shell, MCP, or a gitignored
@@ -228,7 +237,7 @@ export async function consumeCursorTurnStream(
       // post-denial reaction (thinking, narration, a workaround shell) stream and
       // persist live (production case aex_01kwj07f7g23c3wp9sn8496z5g). The
       // tool_call-event read stays as the backstop for platforms where fs.watch
-      // is unreliable; the current event was already accumulated above, so the
+      // is unreliable; the current event was already folded above, so the
       // anchor's own row is always present for the turn-boundary gate overlay.
       if (!state.firstDenialDetected && hitlDir && (state.denialLedgerDirty || event.type === "tool_call")) {
         state.denialLedgerDirty = false;
@@ -262,7 +271,6 @@ export async function consumeCursorTurnStream(
         }
       }
 
-      deltaEnricher.applyEnrichments(status.messages);
       state.eventCount++;
 
       if (event.type === "status") {
@@ -278,27 +286,22 @@ export async function consumeCursorTurnStream(
         }
       }
 
-      const shouldPersist = shouldPersistStreamingStatus(
-        {
-          deltaEnricherDirty: deltaEnricher.isDirty,
-          todosDirty: todoTracker.isDirty,
-          contentDirty: accumulator.isDirty,
-        },
-        scheduler,
-        state.eventCount,
-      );
+      // The builder's one flag is the discrete signal, as on native
+      // (`shared/persist-decision.ts`).
+      const shouldPersist = shouldPersistStreamingStatus(transcript.dirty, scheduler, state.eventCount);
       if (shouldPersist) {
-        // The accumulator upserts sub-agent rows into `status.subAgentExecutions`
-        // in place (wrapped by reference at construction), so every persist
-        // already carries delegation, IN_PROGRESS included. The runtime attaches
-        // the mid-run file-change progress on this write (the chokepoint's
-        // step 2), as it does on every write.
+        // Cleared as the write is requested, not after it lands (the same
+        // order as the native loop): a change that folds while the write is
+        // in flight must dirty the next one.
+        transcript.markPersisted();
+        // The builder upserts sub-agent rows into `status.subAgentExecutions`
+        // in place (the status's own array), so every persist already carries
+        // delegation, IN_PROGRESS included. The runtime attaches the mid-run
+        // file-change progress on this write (the chokepoint's step 2), as it
+        // does on every write.
         // Awaited: the runtime reads the control plane's answer to this write,
         // and a STOP must be seen at the next event boundary, not one event late.
         await sink.requestPersist();
-        deltaEnricher.markPersisted();
-        todoTracker.markPersisted();
-        accumulator.markPersisted();
         scheduler.markUpdateSent(state.eventCount);
       }
     }

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

@@ -25,17 +25,17 @@
  * on why `stopSignal` aborted, never writes a phase or a terminal copy, never
  * imports `@temporalio/*` (`__tests__/adapter-is-temporal-free.test.ts`).
  *
- * Engine disposition, one rule per outcome (Q-S2-6): the agent is PARKED
+ * Engine disposition, one rule per outcome: the agent is PARKED
  * for the session's next turn on every exit but a failure — `completed`,
  * `cancelled`, `awaiting_approval` and `interrupted` alike (a wedged handle
  * after a stall is caught by the poisoned-handle recovery on the next turn;
- * before S2 a pause, a shutdown and a stall dropped the handle, leaking the
+ * before #1070 a pause, a shutdown and a stall dropped the handle, leaking the
  * executor lease). A `failed` turn keeps the orchestrator's three
  * dispositions: an engine-reported failure parks (a bad key is not a bad
  * handle), a user-actionable failure closes, an internal failure drops.
  *
- * Extracted from `index.ts` `executeCursorInner` at S2 M3b and moved out of
- * `adapter.ts` at S2 M5; the seventeen hermetic goldens under `__tests__/hermetic/`
+ * Extracted from `index.ts` `executeCursorInner` and moved out of
+ * `adapter.ts` in #1070; the seventeen hermetic goldens under `__tests__/hermetic/`
  * pin the result byte for byte.
  */
 
@@ -67,7 +67,7 @@ export async function runCursorTurn(input: TurnInput, sink: TurnSink, config: Cu
   closeProxySessions();
   // The module-level fallback the interceptors read when no execution
   // context is entered (the runtime enters one around the whole activity;
-  // the SDK warm-up in main.ts has none). Deprecated; an S5 footprint item.
+  // the SDK warm-up in main.ts has none). Deprecated; its removal is #1132.
   setInterceptorExecutionId(executionId);
 
   if (sink.stopSignal.aborted) return { kind: "interrupted" };

package/src/activities/execute-cursor/usage-pricing.ts

@@ -4,11 +4,11 @@
  * basis on the priced delta the runtime accumulates.
  *
  * The runtime cannot price without the vendor's table and variant semantics,
- * and it must not import them (Q-S2-12), so the adapter hands
+ * and it must not import them, so the adapter hands
  * `TurnSink.reportUsage` a delta that already carries `estimatedCostUsd`
  * and the basis (`model`, the catalog-validated id; `requestedModelParams`,
  * the JSON of the params sent with every create/resume) the runtime writes
- * into `streaming_usage`. Split out of the accumulator at S2 M3
+ * into `streaming_usage`. Split out of the accumulator in #1070
  * (`harness/usage-accumulator.ts` keeps the sums); the arithmetic and the
  * rounding are unchanged, so the estimate is byte-for-byte the old one.
  *

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

@@ -10,7 +10,7 @@
  * module owns the ENGINE — what the model will do on its next call — and
  * reports what really happened. The adapter under test is the production
  * one, untouched; the model client is the one module doubled
- * (`scripted-model-module.ts`, S3 M0 ruling Q-M0-1), and the tools the model
+ * (`scripted-model-module.ts`), and the tools the model
  * calls are deepagents' real built-ins over the real gate.
  *
  * ── The engine is per execution, and its memory is the conversation ────────
@@ -28,7 +28,7 @@
  * checkpoint IS the engine's memory, which is why the same plan is right on
  * a `Command(resume)` (the tool result is in the transcript before the model
  * is asked) and on a later turn of the same thread (an approved-and-run call
- * is not proposed again — Cursor's "obedient model" of Q-M4-4, derived
+ * is not proposed again — Cursor's subject's "obedient model", derived
  * instead of stored).
  *
  * ── The translation, one rule per word ──────────────────────────────────────

package/src/activities/execute-deep-agent/__test-utils__/hermetic-deep-agent.ts

@@ -41,25 +41,30 @@
  *    network. A scenario picks one; the HITL arms record both.
  *
  * The ONE knowledge of production this driver holds is `activityFactory`: how
- * to obtain the `ExecuteDeepAgent` function from a `Config`. Since S3 M2a it
+ * to obtain the `ExecuteDeepAgent` function from a `Config`. Since #1096 it
  * is the harness registry's: the native adapter booted and bound to its
  * byte-pinned activity name through `createHarnessActivities`, exactly the
- * way the composition roots bind it since S3 M2b through `harness-adapters.ts`
+ * way the composition roots bind it since #1096 through `harness-adapters.ts`
  * (and the way the Cursor driver binds its own, `hermetic-cursor.ts`). The
- * orchestrator this adapter replaced (`index.ts`, `setup.ts`) was deleted at
- * M2b; the goldens moved once, with the M2a flip, each hunk quoted with its
- * ruling in its test's header (Q-M2a-1), and the switch of the roots moved
- * none (Q-M2b-4).
+ * orchestrator this adapter replaced (`index.ts`, `setup.ts`) was deleted in
+ * #1096; the goldens moved once, with the flip onto the runtime, each hunk
+ * quoted with its reason in its test's header, and the switch of the roots
+ * moved none.
  *
  * `boot` registers the deepagents harness profiles as production does
- * (S3 M2a F-M2a-14: the orchestrator-driven runs never did, so deepagents
- * auto-injected its ungated `general-purpose` sub-agent into every M0
+ * (found in #1096: the orchestrator-driven runs never did, so deepagents
+ * auto-injected its ungated `general-purpose` sub-agent into every earlier
  * scenario; the scripted model never delegated to it).
  *
- * Determinism beyond S0's: the clock ticks once per model turn (the scripted
+ * Determinism beyond the Cursor driver's (#1048): the clock ticks once per model turn (the scripted
  * model's `onTurn`), so status timestamps and the persist cadence land on the
  * same instants every run; a scenario's interruption (pause, worker shutdown)
- * is scheduled on a model turn through the same hook, never on a timer.
+ * is scheduled on a model turn through the same hook, never on a timer. And
+ * a turn does not begin — the clock does not tick — until the loop has
+ * persisted the previous turn's tool results settled
+ * (`ExecutionRecord.whenToolCallsSettled`): the ground a real model's latency
+ * gives for free, without which the producer runs ahead of a consumer that is
+ * awaiting a slow persist and the stamps of one turn straddle the next tick.
  */
 
 import { rmSync } from "node:fs";
@@ -174,7 +179,7 @@ export function sessionWorkspaceDir(env: HermeticEnvironment): string {
 /** The `ExecuteDeepAgent` function as the runner serves it: the typed object OR the legacy positional pair. */
 export type ExecuteDeepAgentFn = (arg0: ExecuteActivityInput | string, arg1?: string) => Promise<unknown>;
 
-/** How the driver obtains the activity from a `Config` — the one seam M2 flips. */
+/** How the driver obtains the activity from a `Config` — the one seam the move onto the runtime flipped. */
 export type ActivityFactory = (config: Config) => Promise<ExecuteDeepAgentFn>;
 
 /**
@@ -225,6 +230,13 @@ export class DeepAgentScenario {
   ) {
     this.model = new ScriptedModel(script, [], {
       onTurn: async (info) => {
+        // A real model answers long after the loop has folded and persisted
+        // the tool results it is answering; a scripted one answers at once and
+        // lets the producer run a turn ahead of the consumer. Wait for that
+        // ground before ticking, so every stamp of the previous turn precedes
+        // this turn's instant, whatever the persist's I/O took (the barrier's
+        // own header on `ExecutionRecord` carries the whole reason).
+        await this.record.whenToolCallsSettled(info.priorToolCallIds);
         this.clock.tick();
         if (onTurn && this.controls) await onTurn(info, this.controls);
       },

package/src/activities/execute-deep-agent/__test-utils__/hitl-script.ts

@@ -29,7 +29,7 @@ export const EXECUTE_CALL_B: ScriptedToolCall = {
 
 /** The gate's copy for a SHELL built-in (`CATEGORY_APPROVAL_MESSAGE.shell` over the args). */
 export function executeApprovalMessage(call: ScriptedToolCall): string {
-  return `Execute command: ${String(call.args.command)}`;
+  return `Run command: ${String(call.args.command)}`;
 }
 
 /** Round 0 of every gated arm: one text block and the gated `execute` A. */

package/src/activities/execute-deep-agent/__test-utils__/scripted-model-module.ts

@@ -9,8 +9,7 @@
  * (`shared/extract-structured-output.ts`). None of them takes a model as an
  * argument, so the one seam a hermetic run has is this module — the native analog of the Cursor
  * driver's `vi.mock("@cursor/sdk")`: the vendor engine doubled where the
- * runner imports it, and nothing else (S3 M0 ruling Q-M0-1, amending
- * Q-S3-11).
+ * runner imports it, and nothing else.
  *
  * `vi.mock` is hoisted and must live in the test file; the factory can
  * `await import()` this module:
@@ -33,7 +32,7 @@
  * header), so a test that runs several executions at once — the harness
  * contract kit's concurrency invariant — routes each build to that
  * execution's own engine through the id production already sends, and
- * through nothing added for the test (S3 M3).
+ * through nothing added for the test.
  */
 
 import type { BuildChatModelOptions, BuiltChatModel } from "../../../shared/model-client.js";

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

@@ -28,7 +28,7 @@
  * indexing left to the caller — for a consumer whose plan is not "turn k on
  * round k" but "the first step the conversation does not yet show" (the
  * harness contract kit's native subject, whose one execution spans many
- * kit turns on one sqlite thread, S3 M3).
+ * kit turns on one sqlite thread).
  *
  * A turn may END the model call instead of finishing the message
  * ({@link TurnEnding}): `fail` throws after its chunks (a provider error
@@ -46,8 +46,8 @@
  * and otherwise falls back to a synthesized final-message event sequence
  * (`@langchain/langgraph` `pregel/messages-v2.js` `emitFinalMessage`). The
  * fallback spreads a `tool_call` block's `args` OBJECT into the
- * `tool_call_chunk` fields the runner's normalizer reads as a JSON STRING
- * (`v3-protocol-normalizer.ts` `argsChunk`), which no real provider does.
+ * `tool_call_chunk` fields the runner's translator reads as a JSON STRING
+ * (`translator.ts` `argsChunk`), which no real provider does.
  * Streaming keeps the double on the production event path: `@langchain/core`
  * `language_models/compat.js` `convertChunksToEvents` turns the chunks below
  * into `message-start`, per-block `content-block-start` / `-delta` /
@@ -181,6 +181,13 @@ export type ScriptSelector = (boundToolNames: string[], context: ScriptRoleConte
 export interface ScriptedTurnInfo {
   readonly boundToolNames: readonly string[];
   readonly round: number;
+  /**
+   * The ids of the tool calls the transcript's last AI message made — the
+   * calls whose results this turn answers. Empty on a role's first turn and
+   * after a text-only turn. Read from the transcript the engine hands the
+   * model, never from the script, so it is what the engine actually ran.
+   */
+  readonly priorToolCallIds: readonly string[];
 }
 
 export interface ScriptedModelOptions {
@@ -240,7 +247,11 @@ export class ScriptedModel extends BaseChatModel {
   /** The turn for this transcript, after the driver hook has run. */
   private async turnFor(messages: BaseMessage[]): Promise<ScriptedTurn> {
     const round = completedToolRounds(messages);
-    await this.options.onTurn?.({ boundToolNames: this.toolNames, round });
+    await this.options.onTurn?.({
+      boundToolNames: this.toolNames,
+      round,
+      priorToolCallIds: priorToolCallIds(messages),
+    });
     const context: ScriptRoleContext = { systemPrompt: systemPromptOf(messages) };
     return resolveTurn(this.select(this.toolNames, context), { round, transcript: messages, toolNames: this.toolNames });
   }
@@ -347,6 +358,16 @@ export function completedToolRounds(messages: readonly BaseMessage[]): number {
   return rounds;
 }
 
+/** The tool-call ids on the transcript's last AI message; `[]` when there is none or it made no calls. */
+export function priorToolCallIds(messages: readonly BaseMessage[]): string[] {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const m = messages[i];
+    if (!isAIMessage(m)) continue;
+    return (m.tool_calls ?? []).flatMap((call) => (call.id ? [call.id] : []));
+  }
+  return [];
+}
+
 /** What one model call knows when it picks its turn. */
 interface TurnRequest {
   readonly round: number;