@stigmer/runner 3.15.3-dev.20260914121148 → 3.16.0

package/src/__test-utils__/harness-contract/runtime-contract.ts

@@ -19,7 +19,9 @@
  * the facts the runtime owes on it: the terminal phase, the copy
  * (`terminal-table.ts` `TERMINAL_COPY`, byte-pinned), `status.error`,
  * `completedAt`, "the step after never runs", the whole-activity heartbeat,
- * one bind for an engine-minted harness, the slim return. What is NOT
+ * one bind for an engine-minted harness, the slim return, and — on every
+ * arm, whatever the outcome — a transcript that streams nothing once the
+ * turn has settled ({@link assertTranscriptStreamsNothing}). What is NOT
  * asserted here is engine cadence — how many IN_PROGRESS persists precede
  * the WAITING write, the exact setup labels beyond the runtime's own, the
  * exact price a vendor's table yields — because those are a subject's facts;
@@ -216,13 +218,47 @@ export class RuntimeExecutionDriver {
   }
 }
 
-/** The final full status the record holds; an arm that persisted nothing is a failure, named. */
+/**
+ * The final full status the record holds, checked for the one fact every
+ * settled turn owes its transcript before the arm reads anything else. An
+ * arm that persisted nothing is a failure, named.
+ */
 function finalStatusOf(harness: RuntimeContractHarness, driver: RuntimeExecutionDriver): AgentExecutionStatus {
   const final = driver.record.lastFullStatus;
   if (!final) throw new Error(`${harness.subject.name}: the runtime persisted no full status`);
+  assertTranscriptStreamsNothing(harness.subject.name, final);
   return final;
 }
 
+/**
+ * No streaming flag survives a settled turn — on any message, any tool-call
+ * row, in the root transcript or a sub-agent's — however the turn ended. A
+ * flag left on is a spinner the console never stops. The runtime closes
+ * them once, after `runTurn` returns, on every path (`harness/run-turn.ts`),
+ * so the fact holds for every subject and every outcome, and every arm
+ * checks it through {@link finalStatusOf}. Before the runtime owned that
+ * close, this fired on both real adapters' internal-failure arm: a turn that
+ * failed before its settle left its last message streaming. Exported so the
+ * kit's self-check can hand it a status that still streams and prove it
+ * fires.
+ */
+export function assertTranscriptStreamsNothing(subjectName: string, status: AgentExecutionStatus): void {
+  const streaming: string[] = [];
+  const sweep = (scope: string, messages: AgentExecutionStatus["messages"]): void => {
+    messages.forEach((m, i) => {
+      if (m.isStreaming) streaming.push(`${scope}messages[${i}]`);
+      for (const tc of m.toolCalls) {
+        if (tc.isStreaming) streaming.push(`${scope}messages[${i}].toolCalls[${tc.id}]`);
+      }
+    });
+  };
+  sweep("", status.messages);
+  for (const sub of status.subAgentExecutions) sweep(`subAgentExecutions[${sub.id}].`, sub.messages);
+  if (streaming.length > 0) {
+    throw new Error(`${subjectName}: a settled turn's transcript is still streaming at ${streaming.join(", ")}`);
+  }
+}
+
 /** What every arm hands back so a subject's file can add its own facts. */
 export interface RuntimeArmResult {
   readonly driver: RuntimeExecutionDriver;
@@ -357,11 +393,11 @@ export async function assertFileReviewRoundTrip(harness: RuntimeContractHarness,
   expect(rows.get(keepId)?.fileChangeSetId, `${subject.name}: a flowed row is badged with the change set`).toBe(changeSetId);
   expect(rows.get(dropId)?.fileChangeSetId).toBe(changeSetId);
   expect(rows.get(keepId)?.status, `${subject.name}: a flowed row is COMPLETED, never gated`).toBe(ToolCallStatus.TOOL_CALL_COMPLETED);
-  // The strip is the runtime's, attached on its writes (Q-M4-7). Its COUNT is
+  // The strip is the runtime's, attached on its writes. Its COUNT is
   // the capture floor's: a real engine's first persist precedes its first
   // write and both writes land within one floor interval, so the pause can
-  // honestly read "0 files" beside a two-file candidate (F-M4-3, recorded
-  // for S5: whether the terminal write should bypass the floor). The arm
+  // honestly read "0 files" beside a two-file candidate (#1114: whether the
+  // terminal write should bypass the floor). The arm
   // asserts the ownership, not the floor.
   expect(afterCapture.fileChangeProgress?.changeSetId, `${subject.name}: the runtime carries this turn's strip`).toBe(changeSetId);
   expect(afterCapture.completedAt, `${subject.name}: a review pause is not complete`).toBe("");
@@ -374,7 +410,7 @@ export async function assertFileReviewRoundTrip(harness: RuntimeContractHarness,
   const second = await driver.turn([]);
   expect(slimOf(subject, second).phase, `${subject.name}: a pure file-review resume completes without the engine`).toBe("EXECUTION_COMPLETED");
   // The kept file is the engine-not-re-run witness: a subject that counts
-  // executions by reading its ledger off disk (the native one, Q-M3-4) reads
+  // executions by reading its ledger off disk (the native one) reads
   // the DISCARDED file's count as 0 now, because the reconcile just restored
   // that file to its baseline — which is the reconcile working, not the
   // engine forgetting.
@@ -398,7 +434,7 @@ export async function assertFileReviewRoundTrip(harness: RuntimeContractHarness,
  * settles the row SKIPPED (a REJECT row carries `error: "Rejected by user"`),
  * so no WAITING row survives on a finished execution. This is the proto
  * contract as of stigmer#197 and the runtime's own write
- * (`harness/approval-decisions.ts`); before S3 M1 the runtime FAILED a
+ * (`harness/approval-decisions.ts`); before #1096 the runtime FAILED a
  * REJECTed reinvocation before any engine ran.
  */
 export async function assertNonExecutingDecisionSettlesSkipped(
@@ -440,14 +476,14 @@ export async function assertNonExecutingDecisionSettlesSkipped(
  * the next message), `error` starting with the cross-repo prefix Stigmer
  * Cloud's channel delivery matches on, the user copy as the one system row,
  * `completedAt` stamped, RETURNED (a retry would spend the same budget), and
- * the step after the limit never processed. Before S3 M1 the native harness
- * RETURNED this terminal without persisting it (M0 finding F-M0-4); the
+ * the step after the limit never processed. Before #1096 the native harness
+ * RETURNED this terminal without persisting it; the
  * runtime's arm is the one persisted terminal.
  *
  * The execution SETS the budget it exhausts: the record carries the smallest
  * valid `max_tool_rounds` (an unbounded execution has no limit to reach — on
  * native `resolveRecursionLimit(0)` is unlimited, and the first run of this
- * arm against it spun until the test timed out; S3 M3 F-M3-3). The fake
+ * arm against it spun until the test timed out). The fake
  * exhausts whatever budget it is given; a real engine spins its cheapest
  * ungated tool until the graph stops it.
  */
@@ -625,12 +661,12 @@ const STALL_CLOCK_INTERVAL_MS = 25;
  * park is reported while the chunks the engine produced before parking are
  * still in its event pipeline ahead of the adapter's loop, so activity marks
  * land AFTER a single tick and a frozen clock reads idle 0 from then on
- * (S3 M3 F-M3-5, measured on the native adapter: 35 marks at the park, 37
+ * (measured on the native adapter: 35 marks at the park, 37
  * within 10 ms). A pull-based double's park implies everything before it
  * was seen; a real stall is wall time passing while the engine is silent,
  * whichever shape the engine has. The interval advances a SCRIPTED clock —
  * the kit's rule against timers is about stopping a turn on a guess, which
- * this never does (Q-M3-7).
+ * this never does.
  */
 export async function assertStallFailsTheTurn(harness: RuntimeContractHarness, label = "rt-stall"): Promise<RuntimeArmResult> {
   const { subject, clock } = harness;
@@ -692,7 +728,7 @@ export async function assertCostCapTerminates(harness: RuntimeContractHarness, l
 /**
  * A platform STOP answered to a mid-turn persist: the turn completes early
  * with the platform-stop row and no error, and the step after the STOP never
- * runs — the awaited `requestPersist` at work (Q-M3-2). The persist the
+ * runs — the awaited `requestPersist` at work. The persist the
  * control plane answers is the one carrying a completed `read`: the discrete
  * event every harness flushes on (the Cursor golden's lever), where a bare
  * assistant message may ride an engine's cadence to the settle persist, too
@@ -786,7 +822,7 @@ export async function assertFailedSurfaceWritesItsCopy(harness: RuntimeContractH
 
 /**
  * A rejected `bindHarnessState` (the session write refused) ends the turn
- * FAILED on the internal surface with nothing executed (Q-S2-11, R3).
+ * FAILED on the internal surface with nothing executed.
  * Engine-minted harnesses only: a deterministic one never binds.
  */
 export async function assertRejectedBindFails(harness: RuntimeContractHarness, label = "rt-bind-rejects"): Promise<RuntimeArmResult> {
@@ -884,7 +920,7 @@ export interface RuntimeContractOptions {
    * to wait for (`scenario.cancelled()`, an SDK-side cancel); the arm is
    * registered SKIPPED otherwise. On by default; the native subject turns it
    * off (no LangGraph path ends a turn `cancelled` — a stop is the runtime's
-   * and settles `interrupted`; S3 M3 F-M3-2).
+   * and settles `interrupted`).
    */
   readonly engineCancel?: boolean;
 }
@@ -968,7 +1004,7 @@ export function describeHarnessRuntimeContract(harness: RuntimeContractHarness,
         await assertFailedSurfaceWritesItsCopy(harness, surface, FAILURE_MESSAGES[surface]);
       });
     }
-    it.skipIf(subject.adapter.capabilities.stateIdSource !== "engine-minted")("a rejected bindHarnessState ends the turn failed with nothing executed (Q-S2-11)", async () => {
+    it.skipIf(subject.adapter.capabilities.stateIdSource !== "engine-minted")("a rejected bindHarnessState ends the turn failed with nothing executed", async () => {
       clock.reset();
       await assertRejectedBindFails(harness);
     });

package/src/__test-utils__/harness-contract/scripted-adapter.ts

@@ -22,8 +22,12 @@
  *
  * What is deliberately simple here and would be real work in an adapter:
  * "executing" a side effect is incrementing a counter; the engine state id is
- * a counter too; the transcript rows are built with the shared proto
- * factories. What is NOT simplified is the contract behaviour itself —
+ * a counter too; there is no engine event to translate, so each step emits
+ * the canonical `TranscriptEvent`s a translator would (a run for a `say`, a
+ * start and a finish for a tool, a proposal for a gate) straight into
+ * `sink.transcript` — the one way any harness creates a transcript row, and
+ * the whole of what a real adapter's translator adds on top of this file.
+ * What is NOT simplified is the contract behaviour itself —
  * settling with an outcome and never rejecting, stopping at every step
  * boundary and inside a hang, binding before the first persist, executing an
  * approval exactly once, refusing to resume a state it never minted — because
@@ -34,8 +38,8 @@
  * is on the row (the server's field) and the transition follows from it with
  * no engine knowledge, so it belongs to the runtime — one writer per field,
  * as `approvalDecisionsOf` is the runtime's one reader and
- * `terminalizeNonExecutingDecisions` its one writer (S2 M4, Q-M4-1; landed at
- * S3 M1, `harness/approval-decisions.ts`). An adapter's whole duty for a
+ * `terminalizeNonExecutingDecisions` its one writer (landed in #1096,
+ * `harness/approval-decisions.ts`). An adapter's whole duty for a
  * non-executing decision is to not execute.
  *
  * Scenarios are arranged PER SESSION (the engine is per session in every real
@@ -57,7 +61,7 @@ import type { HarnessAdapter, TurnInput, TurnOutcome, TurnSink } from "../../har
 import { DEEP_AGENT_VISION_PROFILE } from "../../shared/attachment-vision.js";
 import type { ProposedAction } from "../approval-contract/types.js";
 import { testConfig } from "../config-fixture.js";
-import { aiMessage, findToolCallRow, toolCall, waitingToolCall } from "../proto-helpers.js";
+import { findToolCallRow } from "../proto-helpers.js";
 import type { EngineView, HarnessContractSubject, ScenarioStep, TurnScenario } from "./types.js";
 
 export interface ScriptedHarnessOptions {
@@ -101,6 +105,8 @@ export class ScriptedHarnessAdapter implements HarnessAdapter {
   private readonly executions = new Map<string, number>();
   private readonly hangWaiters: Array<() => void> = [];
   private mintCounter = 0;
+  /** One `runId` per `say`, as an engine mints one per model run; the builder keys a message on it. */
+  private runCounter = 0;
 
   constructor(options: ScriptedHarnessOptions) {
     this.name = options.name ?? `scripted(${options.pausePrimitive}, ${options.stateIdSource})`;
@@ -211,7 +217,12 @@ export class ScriptedHarnessAdapter implements HarnessAdapter {
   private async play(step: ScenarioStep, input: TurnInput, sink: TurnSink): Promise<TurnOutcome | undefined> {
     switch (step.kind) {
       case "say": {
-        sink.status.messages.push(aiMessage(step.text));
+        // One model run: start, its text, finish — the shape every
+        // translator emits for an assistant message.
+        const runId = `run-${++this.runCounter}`;
+        sink.transcript.apply({ kind: "message_start", runId });
+        sink.transcript.apply({ kind: "text_delta", runId, text: step.text });
+        sink.transcript.apply({ kind: "message_finish", runId });
         sink.recordActivity();
         // Awaited, as the Cursor loop awaits its own: a platform STOP the
         // runtime reads from this write aborts the signal before the next
@@ -223,14 +234,12 @@ export class ScriptedHarnessAdapter implements HarnessAdapter {
         if (step.flows) return this.flowingWrite(step.toolCallId, step.action, input, sink);
         return this.propose(step.toolCallId, step.action, input, sink);
       case "read": {
-        // Ungated: the row lands COMPLETED at once, the effect counts as run,
-        // and the persist is awaited like `say`'s — a real engine's tool call
-        // is the discrete event its loop flushes on.
-        const message = aiMessage("");
-        const row = toolCall(step.toolCallId, "read", ToolCallStatus.TOOL_CALL_COMPLETED);
-        row.result = `contents of ${step.path}`;
-        message.toolCalls.push(row);
-        sink.status.messages.push(message);
+        // Ungated: the row starts and finishes at once, the effect counts as
+        // run, and the persist is awaited like `say`'s — a real engine's tool
+        // call is the discrete event its loop flushes on. The builder puts
+        // the row on the message whose text preceded it.
+        sink.transcript.apply({ kind: "tool_started", callId: step.toolCallId, name: "read", input: { path: step.path }, mcpServerSlug: "" });
+        sink.transcript.apply({ kind: "tool_finished", callId: step.toolCallId, result: `contents of ${step.path}` });
         this.executions.set(step.toolCallId, this.executionCount(step.toolCallId) + 1);
         sink.recordActivity("read");
         await sink.requestPersist();
@@ -279,12 +288,18 @@ export class ScriptedHarnessAdapter implements HarnessAdapter {
     switch (decision) {
       case ApprovalAction.UNSPECIFIED: {
         // Propose: surface the gated call as a WAITING row and stop the turn.
-        // Never write a second row for the same id on a resumed turn.
-        if (!existing) {
-          const message = aiMessage("");
-          message.toolCalls.push(waitingToolCall(toolCallId, action.kind, `Approve ${action.kind} ${action.resource}?`));
-          sink.status.messages.push(message);
-        }
+        // `approval_proposed` is an upsert by id — a resumed turn that
+        // re-proposes reopens the seeded row, never writes a second one. No
+        // `args` on purpose: a `write` carrying whole-file content would make
+        // the runtime's exact-apply eligible on APPROVE, and this fake's
+        // execution count would then measure a path the engine never ran.
+        sink.transcript.apply({
+          kind: "approval_proposed",
+          callId: toolCallId,
+          name: action.kind,
+          mcpServerSlug: "",
+          message: `Approve ${action.kind} ${action.resource}?`,
+        });
         sink.recordActivity();
         sink.requestPersist();
         return { kind: "awaiting_approval" };
@@ -292,7 +307,7 @@ export class ScriptedHarnessAdapter implements HarnessAdapter {
       case ApprovalAction.APPROVE:
       case ApprovalAction.APPROVE_ALL: {
         this.executions.set(toolCallId, this.executionCount(toolCallId) + 1);
-        this.completeRow(existing, toolCallId, action, sink);
+        this.completeRow(toolCallId, action, sink);
         return undefined;
       }
       case ApprovalAction.SKIP:
@@ -321,11 +336,8 @@ export class ScriptedHarnessAdapter implements HarnessAdapter {
     const file = join(input.workspace.primaryDir, action.resource);
     await mkdir(dirname(file), { recursive: true });
     await writeFile(file, `${toolCallId}\n`);
-    const message = aiMessage("");
-    const row = toolCall(toolCallId, "write", ToolCallStatus.TOOL_CALL_COMPLETED);
-    row.args = { path: action.resource };
-    message.toolCalls.push(row);
-    sink.status.messages.push(message);
+    sink.transcript.apply({ kind: "tool_started", callId: toolCallId, name: "write", input: { path: action.resource }, mcpServerSlug: "" });
+    sink.transcript.apply({ kind: "tool_finished", callId: toolCallId, result: "" });
     this.executions.set(toolCallId, this.executionCount(toolCallId) + 1);
     sink.recordActivity("write");
     await sink.requestPersist();
@@ -333,22 +345,14 @@ export class ScriptedHarnessAdapter implements HarnessAdapter {
   }
 
   /**
-   * Report the executed action on its row, as a real engine's completion
-   * event does. The row normally exists (the runtime seeded the status with
-   * last turn's WAITING row); a decision with no row is a runtime that decided
-   * out of band, and the adapter still records what happened rather than
-   * losing the fact.
+   * Report the executed action on its row, as a real engine's re-issue does:
+   * a start (which flips the seeded WAITING row to RUNNING — or creates the
+   * row when a runtime decided out of band and no row exists, so the fact is
+   * recorded rather than lost) and a finish.
    */
-  private completeRow(existing: ToolCall | undefined, toolCallId: string, action: ProposedAction, sink: TurnSink): void {
-    if (existing) {
-      existing.status = ToolCallStatus.TOOL_CALL_COMPLETED;
-    } else {
-      const message = aiMessage("");
-      const row = waitingToolCall(toolCallId, action.kind, "");
-      row.status = ToolCallStatus.TOOL_CALL_COMPLETED;
-      message.toolCalls.push(row);
-      sink.status.messages.push(message);
-    }
+  private completeRow(toolCallId: string, action: ProposedAction, sink: TurnSink): void {
+    sink.transcript.apply({ kind: "tool_started", callId: toolCallId, name: action.kind, input: {}, mcpServerSlug: "" });
+    sink.transcript.apply({ kind: "tool_finished", callId: toolCallId, result: "" });
     sink.recordActivity();
     sink.requestPersist();
   }
@@ -360,8 +364,8 @@ export interface ScriptedSubject extends HarnessContractSubject {
 }
 
 /**
- * The fake declares the `deep-agent` row: in S2 the runtime served that row
- * through this fake alone; since S3 M3 the real native adapter takes it over
+ * The fake declares the `deep-agent` row: in #1070 the runtime served that row
+ * through this fake alone; since #1096 the real native adapter takes it over
  * in the runtime half
  * (`execute-deep-agent/__test-utils__/contract-subject.ts`), and the fake
  * keeps declaring it so the kit's self-check runs a full subject under both

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