@stigmer/runner 3.15.3-dev.20260914121148 → 3.16.0

package/src/harness/__tests__/transcript-writers.test.ts

@@ -0,0 +1,191 @@
+/**
+ * Pins who may CREATE a transcript row: an `AgentMessage`, a `ToolCall` or a
+ * `SubAgentExecution` on the execution status. Two writers, and no third:
+ *
+ *  - `src/harness/transcript/` — the one transcript builder, which every
+ *    harness folds its engine's events through (`TurnSink.transcript`);
+ *  - `src/harness/terminal-table.ts` — the runtime's terminal system rows
+ *    (the pause copy, the failure copy), which are not transcript facts of
+ *    any engine and never were.
+ *
+ * Why it matters (#1097's founding promise): the promise that a
+ * third harness is "a translator and nothing else" holds only while there
+ * is exactly one place a row comes from. A module that builds a row itself
+ * — an adapter pushing an AI message with a WAITING call, a settle
+ * synthesizing a SYSTEM line — is a second copy of the folding rule, and
+ * the two copies drift (the memo counted three such copies before this
+ * entry). The rule is about CREATION. Amending a row a builder created —
+ * flipping a WAITING row SKIPPED, stamping a change-set id, marking a
+ * sub-agent CANCELLED, the Cursor boundary's identity-based collapses — is
+ * legitimate, and the modules that do it are named in `TurnSink`'s header;
+ * a fence over them would be a list, not a rule.
+ *
+ * A reinvocation's prior rows are not an exception: the runtime seeds them
+ * THROUGH the builder (`TranscriptBuilder.seed`, from `turn-context.ts`
+ * `seedFromPersistedStatus`), so the seed indexes what it appends and this
+ * list stays at two. (For one commit the seed pushed rows itself and was
+ * the third name here.)
+ *
+ * The rule is read off the TypeScript syntax tree, as the import fences are
+ * (`import-direction.test.ts`): a schema named in a header comment, or a
+ * `.messages.push(` in prose, cannot trip it; a row built through any of the
+ * three schemas, or an array push onto `messages` / `subAgentExecutions`
+ * wherever the array is reached from, cannot slip past it.
+ */
+
+import { describe, it, expect } from "vitest";
+import { join, relative, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+import ts from "typescript";
+
+import { readSource, typeScriptFilesUnder } from "../../__test-utils__/module-specifiers.js";
+
+const SRC_ROOT = fileURLToPath(new URL("../../", import.meta.url));
+
+/** The proto schemas a transcript row is created through; naming one is creating one. */
+const ROW_SCHEMAS: ReadonlySet<string> = new Set(["AgentMessageSchema", "ToolCallSchema", "SubAgentExecutionSchema"]);
+
+/** The status arrays a created row is pushed onto. */
+const ROW_ARRAYS: ReadonlySet<string> = new Set(["messages", "subAgentExecutions"]);
+
+/** The modules allowed to create rows, relative to `src/`: a directory (every file under it) or a file. */
+const ALLOWED_CREATORS: readonly string[] = [
+  join("harness", "transcript") + sep,
+  join("harness", "terminal-table.ts"),
+];
+
+/** Every row-creating construct in `source`, in source order: `names <Schema>` or `pushes onto .<array>`. */
+export function transcriptRowWrites(fileName: string, source: string): string[] {
+  const sourceFile = ts.createSourceFile(fileName, source, ts.ScriptTarget.Latest, /* setParentNodes */ false);
+  const writes: string[] = [];
+  const visit = (node: ts.Node): void => {
+    if (ts.isIdentifier(node) && ROW_SCHEMAS.has(node.text)) {
+      const write = `names ${node.text}`;
+      if (!writes.includes(write)) writes.push(write);
+    } else if (
+      ts.isCallExpression(node) &&
+      ts.isPropertyAccessExpression(node.expression) &&
+      node.expression.name.text === "push" &&
+      ts.isPropertyAccessExpression(node.expression.expression) &&
+      ROW_ARRAYS.has(node.expression.expression.name.text)
+    ) {
+      const write = `pushes onto .${node.expression.expression.name.text}`;
+      if (!writes.includes(write)) writes.push(write);
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sourceFile);
+  return writes;
+}
+
+function isAllowedCreator(relativeFile: string): boolean {
+  return ALLOWED_CREATORS.some((allowed) => (allowed.endsWith(sep) ? relativeFile.startsWith(allowed) : relativeFile === allowed));
+}
+
+interface Offence {
+  readonly file: string;
+  readonly writes: readonly string[];
+}
+
+interface Sweep {
+  readonly visited: string[];
+  readonly creators: string[];
+  readonly offences: Offence[];
+}
+
+/** Production modules only: tests and test utilities build rows freely (fixtures, goldens' drivers). */
+function sweep(): Sweep {
+  const visited: string[] = [];
+  const creators: string[] = [];
+  const offences: Offence[] = [];
+  for (const file of typeScriptFilesUnder(SRC_ROOT, new Set(["__tests__", "__test-utils__"]))) {
+    const relativeFile = relative(SRC_ROOT, file);
+    visited.push(relativeFile);
+    const writes = transcriptRowWrites(file, readSource(file));
+    if (writes.length === 0) continue;
+    creators.push(relativeFile);
+    if (!isAllowedCreator(relativeFile)) offences.push({ file: relativeFile, writes });
+  }
+  return { visited, creators, offences };
+}
+
+function describeOffences(offences: readonly Offence[]): string {
+  return offences.map((o) => `  ${o.file}: ${o.writes.join(", ")}`).join("\n");
+}
+
+describe("transcriptRowWrites (the checker itself)", () => {
+  const file = join(SRC_ROOT, "activities", "some-harness", "settle.ts");
+
+  it.each([
+    ["a message built through its schema", 'const m = create(AgentMessageSchema, { content: "x" });', "names AgentMessageSchema"],
+    ["a tool call built through its schema", "const tc = create(ToolCallSchema, { id });", "names ToolCallSchema"],
+    ["a sub-agent row built through its schema", "const row = create(SubAgentExecutionSchema, { id });", "names SubAgentExecutionSchema"],
+    ["a schema merely imported", 'import { AgentMessageSchema } from "@stigmer/protos/x_pb";', "names AgentMessageSchema"],
+    ["a push onto the root transcript", "status.messages.push(msg);", "pushes onto .messages"],
+    ["a push onto a nested transcript", "scope.row.messages.push(msg);", "pushes onto .messages"],
+    ["a spread push", "sink.status.messages.push(...seed.messages);", "pushes onto .messages"],
+    ["a push onto the sub-agent rows", "this.proto.subAgentExecutions.push(row);", "pushes onto .subAgentExecutions"],
+  ])("flags %s", (_label, source, expected) => {
+    expect(transcriptRowWrites(file, source)).toEqual([expected]);
+  });
+
+  it.each([
+    ["a schema named in a comment", "// built through AgentMessageSchema elsewhere\nconst x = 1;"],
+    ["a push described in a comment", "// the builder does status.messages.push(msg)\nconst x = 1;"],
+    ["a schema named in a string", 'const hint = "AgentMessageSchema";'],
+    ["a read of the transcript", "const last = status.messages.at(-1);"],
+    ["a push onto an unrelated array", "status.artifacts.push(artifact);"],
+    ["a push onto a bare `messages` local", "messages.push(m);"],
+    ["the message TYPE, not its schema", 'import type { AgentMessage } from "@stigmer/protos/x_pb";'],
+    ["an in-place amendment of a row", "row.status = ToolCallStatus.TOOL_CALL_SKIPPED;"],
+  ])("does not flag %s", (_label, source) => {
+    expect(transcriptRowWrites(file, source)).toEqual([]);
+  });
+
+  it("names each construct once, in source order", () => {
+    const source = [
+      "const a = create(AgentMessageSchema, {});",
+      "const b = create(ToolCallSchema, {});",
+      "const c = create(AgentMessageSchema, {});",
+      "a.toolCalls.push(b); status.messages.push(a); status.messages.push(c);",
+    ].join("\n");
+    expect(transcriptRowWrites(file, source)).toEqual(["names AgentMessageSchema", "names ToolCallSchema", "pushes onto .messages"]);
+  });
+});
+
+describe("only the transcript builder and the terminal table create transcript rows", () => {
+  const result = sweep();
+
+  it("inspected production modules across src/ and skipped the test trees (the walk is rooted where it claims)", () => {
+    expect(result.visited).toEqual(
+      expect.arrayContaining([
+        join("harness", "run-turn.ts"),
+        join("harness", "transcript", "builder.ts"),
+        join("activities", "execute-cursor", "boundary-rows.ts"),
+        join("activities", "execute-deep-agent", "hitl.ts"),
+        join("shared", "exact-apply.ts"),
+      ]),
+    );
+    expect(
+      result.visited.some((f) => f.includes(`${sep}__tests__${sep}`) || f.includes(`${sep}__test-utils__${sep}`)),
+      "the production sweep must skip the test trees",
+    ).toBe(false);
+  });
+
+  it("found the allowed creators (the checker sees the rows it exists to see)", () => {
+    expect(result.creators).toEqual(
+      expect.arrayContaining([
+        join("harness", "transcript", "builder.ts"),
+        join("harness", "transcript", "state.ts"),
+        join("harness", "terminal-table.ts"),
+      ]),
+    );
+  });
+
+  it("finds no creator outside the allow-list", () => {
+    expect(
+      result.offences,
+      `a transcript row is created through TurnSink.transcript, never built in place:\n${describeOffences(result.offences)}`,
+    ).toEqual([]);
+  });
+});

package/src/harness/__tests__/turn-attachments-vision.test.ts

@@ -2,7 +2,7 @@
  * Pins which model the attachment phase asks the registry about when it
  * sizes the vision budget (`turn-context.ts` `resolveTurnAttachments`): the
  * model the execution named, or the registry's default when it named none —
- * the model the native harness will build in that case. Before S3 M1 the
+ * the model the native harness will build in that case. Before #1096 the
  * phase asked about the raw executionConfig name, so an execution with no
  * model named asked about `""` (always "unknown", read as sighted) while the
  * native orchestrator asked about the resolved default (its `setup.ts`,
@@ -29,14 +29,17 @@ import { DEEP_AGENT_VISION_PROFILE } from "../../shared/attachment-vision.js";
 import { TimingRecorder } from "../../shared/cold-start-timing.js";
 import { mockStigmerClient } from "../../__test-utils__/mock-client.js";
 import { testConfig } from "../../__test-utils__/config-fixture.js";
+import { TranscriptBuilder } from "../transcript/builder.js";
 import { resolveTurnAttachments, type ResolutionDeps } from "../turn-context.js";
 
 function deps(): ResolutionDeps {
+  const status = create(AgentExecutionStatusSchema, {});
   return {
     input: { executionId: "aex_1", threadId: "", turnSeq: 0 },
     client: mockStigmerClient(),
     config: testConfig(),
-    status: create(AgentExecutionStatusSchema, {}),
+    status,
+    transcript: new TranscriptBuilder("aex_1", status),
     artifactStorage: undefined,
     timing: new TimingRecorder(),
     signal: new AbortController().signal,

package/src/harness/__tests__/turn-context.test.ts

@@ -14,13 +14,13 @@
  *    (`activities/execute-cursor/__tests__/approval-state.test.ts`), because
  *    `src/harness/` never imports `src/activities/`, tests included.
  *  - `decideReinvocation`: the three ways a resume proceeds (any decision
- *    runs the agent — REJECT included since S3 M1 —, a clean file-review
+ *    runs the agent — REJECT included since #1096 —, a clean file-review
  *    resume completes, a failed or partially discarded one completes with
  *    its facts carried).
  *  - `regeneratesApprovedWrites`: which pause primitives make the runner pin
  *    an approved whole-file write's bytes itself (the engine re-runs the
  *    model) and which never do (the engine applies the exact args it paused
- *    on). S3 M2a, Q-M2a-3.
+ *    on).
  *
  * The phases that fetch and provision are exercised end to end by the
  * hermetic goldens (`activities/execute-cursor/__tests__/hermetic/`), which
@@ -163,10 +163,10 @@ describe("decideReinvocation", () => {
     expect(decideReinvocation(facts())).toBeUndefined();
   });
 
-  it("a REJECT runs the agent like any other decision — the run continues without the tool (stigmer#197; S3 M1, Q-S3-2)", () => {
-    // Until S3 M1 this returned `{ kind: "rejected-by-user" }` and the runtime
+  it("a REJECT runs the agent like any other decision — the run continues without the tool (stigmer#197)", () => {
+    // Until #1096 this returned `{ kind: "rejected-by-user" }` and the runtime
     // FAILED the execution before any engine ran, contradicting the proto, the
-    // conformance suite and the native harness (S2 M4 finding F1).
+    // conformance suite and the native harness.
     const decisions = new Map([
       ["tc-1", ApprovalAction.APPROVE],
       ["tc-2", ApprovalAction.REJECT],

package/src/harness/approval-decisions.ts

@@ -34,7 +34,7 @@
  *
  * This is the contract as of stigmer#197: REJECT denies the tool and the run
  * CONTINUES; it never fails the execution. The native harness proved it
- * (`hitl.ts` `reconcileNonExecutingDecisions`, moved here at S3 M1) and the
+ * (`hitl.ts` `reconcileNonExecutingDecisions`, moved here in #1096) and the
  * conformance suite (`agentexecution-approval.conformance.test.ts`) is its
  * arbiter for both harnesses.
  */

package/src/harness/capabilities.ts

@@ -15,8 +15,8 @@
  * the Cursor builder renders the session's first user message), and the
  * shared prompt glue (`shared/prompt-sections.ts`) is written so that
  * placement stays each adapter's. The runtime would branch on it only if it
- * ever composed prompts itself — the S4/S5 unification question, not a phase
- * that exists (S3 M5, Q-M5-6).
+ * ever composed prompts itself — an open unification question (#1135), not a
+ * phase that exists.
  *
  * The matrix the contract was designed against (2026-09; Claude and Codex are
  * the surveyed SDKs, not built harnesses):
@@ -53,12 +53,22 @@ import type { VisionProfile } from "../shared/attachment-vision.js";
  *  - `deny-and-retry`: an out-of-process hook denies the tool, the adapter
  *    records the denial, cancels the run, and re-runs with grants on the next
  *    invocation.
- *  - `callback`: an in-process callback decides per tool; the runtime still
- *    returns `awaiting_approval` and reinvokes, so the adapter answers the
- *    callback with "deny, stop" and resumes with the decisions.
- *  - `none`: the engine offers no gate; the runtime confines it to
- *    capture-only work (a read-only sandbox) and gated actions never reach
- *    the engine.
+ *  - `callback`: an in-process callback decides per tool. The intended shape
+ *    is the `interrupt` one seen from the runtime: the turn still ends
+ *    `awaiting_approval` and reinvokes, and the adapter answers the callback
+ *    with "deny, stop" and resumes with the decisions.
+ *  - `none`: the engine offers no gate. The intended shape is that the
+ *    runtime confines such a harness to capture-only work (a read-only
+ *    sandbox) so a gated action never reaches the engine.
+ *
+ * Two of the four are built and two are reserved. `interrupt` (native) and
+ * `deny-and-retry` (Cursor) each have a real adapter and the contract kit
+ * runs under both. `callback` and `none` come from the 2026-09 survey of the
+ * Claude and Codex SDKs: the type carries them so an adapter can declare
+ * them, but no adapter does, and the runtime reads `pausePrimitive` in one
+ * place only (`turn-context.ts` `regeneratesApprovedWrites`, which returns
+ * false for `none`). The capture-only confinement for `none` is design
+ * still to be done before the first gate-less harness lands.
  */
 export type PausePrimitive = "interrupt" | "deny-and-retry" | "callback" | "none";
 
@@ -78,9 +88,9 @@ export type StateIdSource = "deterministic" | "engine-minted";
  * workspace-relative paths the harness writes into the repo that a turn's
  * diff must never show (Cursor's transient `.cursor/hooks.json`). Declared
  * once per adapter, read by `harness/capture.ts` (the pin, the progress
- * slice, the candidate) and `turn-context.ts` (the reconcile). Ruled Q-M2-6
- * as an argument, homed here at S2 M3; the capture joined the reconcile as a
- * reader at S3 M4.
+ * slice, the candidate) and `turn-context.ts` (the reconcile). First passed
+ * as an argument, then homed here as a capability (#1070); the capture joined
+ * the reconcile as a reader in #1096.
  */
 export interface FileReviewIdentity {
   readonly harnessId: string;

package/src/harness/capture.ts

@@ -21,7 +21,7 @@
  * that the runtime cannot read is what its engine observed touching
  * CAS-owned paths (`TurnSink.bindCasObservations`).
  *
- * Until S3 M4 both adapters carried this whole act (Cursor in its
+ * Until #1096 both adapters carried this whole act (Cursor in its
  * `turn-boundary.ts` between the stream and `run.wait()`, the deep-agent in
  * its `turn-settle.ts`), each with its own evidence source and its own
  * scoping rules for the provenance and the stamp. The two rules here are the
@@ -33,7 +33,7 @@
  *    position, because on BOTH engines an approved command executes on the
  *    row the runtime seeded for it (the deep-agent's builder and Cursor's
  *    translator both reconcile the re-attempt onto the seeded WAITING row),
- *    at its prior position; a positional scope misses it (F-M4-P3: Cursor's
+ *    at its prior position; a positional scope misses it (Cursor's
  *    did, so its auto-keep never qualified a gated-then-approved command).
  *    "Executed" is a COMPLETED row. "Consented" is the row's own
  *    server-authored `approval_action` — the seeded row keeps its id and its
@@ -50,10 +50,10 @@
  * The substrate and the ledger authoring (`shared/filereview/capture.ts`,
  * `cas-touched.ts`, `progress.ts`); the resume-time reconcile
  * (`turn-context.ts` `reconcileReinvocation`, already the runtime's since
- * S2); the outcome matrix that turns "a review is pending" into a phase
+ * #1070); the outcome matrix that turns "a review is pending" into a phase
  * (`run-turn.ts`, through `terminal-table.ts` `awaitingReviewArm`).
  *
- * TWO GAPS THIS MODULE DOES NOT CLOSE (recorded for S5, S3 M4 F-M4-P-gaps)
+ * TWO GAPS THIS MODULE DOES NOT CLOSE (recorded as #1115)
  * ----------------------------------------------------------------------
  * A turn that ends `interrupted` is not captured (a stop fired; the tree may
  * be mid-edit). So a platform STOP returns COMPLETED with unreviewed edits

package/src/harness/persist-chokepoint.ts

@@ -15,7 +15,7 @@
  *     the tree is read at most once per floor interval and only re-attached
  *     when it moved (`shared/filereview/progress.ts`), so a write that
  *     changed nothing on disk carries the snapshot it already had. Before
- *     S3 M4 each adapter's stream loop did this before its own persists; the
+ *     #1096 each adapter's stream loop did this before its own persists; the
  *     runtime owns the capture now, so the display field it derives is
  *     refreshed where every other runtime-owned field is — here.
  *  3. `streaming_usage` is refreshed from the accumulator when it has turns,
@@ -23,7 +23,7 @@
  *  4. `persistStatus` (`shared/status.ts`): tool-output offload, the
  *     aggregate size cap, transient retry, oversize recovery. Never rejects.
  *  5. A Temporal heartbeat, so a long streaming turn's liveness is proven by
- *     the writes it makes (Q-S2-10).
+ *     the writes it makes.
  *  6. The control plane's answer: STOP becomes the runtime's platform-stop
  *     cause on the stop controller, which aborts the adapter's signal.
  *
@@ -34,7 +34,7 @@
  * and resolves when that follow-up has. The promise it returns therefore
  * always means "the state as of my request is on the control plane", which
  * is what lets the Cursor loop await it and see a STOP before it pulls the
- * next event, exactly as its own inline persist did (Q-M3-2).
+ * next event, exactly as its own inline persist did.
  *
  * The runtime's terminal writes use the same path (`write()`), so the
  * secret backstop and the usage summary ride the final status too, as they

package/src/harness/registry.ts

@@ -10,7 +10,7 @@
  * dials the control plane, and `shutdownHarnesses` runs them in reverse so
  * what was set up last is torn down first.
  *
- * Error posture, ruled at the entry's gate (Q-S1-10):
+ * Error posture (fixed in #1064):
  *  - Boot validates the whole table BEFORE booting anything (a duplicate name
  *    is a configuration defect, and a half-booted worker is the worst state to
  *    discover it in), then fails fast at the first adapter that rejects. A
@@ -23,7 +23,7 @@
  * turn runtime (`run-turn.ts`). The table of real rows is NOT here: it lives
  * at the source root (`src/harness-adapters.ts`), because a row imports its
  * adapter from `activities/` and nothing under `src/harness/` may
- * (`__tests__/import-direction.test.ts`; Q-M3-1). The registry knows rows,
+ * (`__tests__/import-direction.test.ts`). The registry knows rows,
  * never which adapters exist.
  *
  * `HarnessName` lives here and not in `types.ts` on purpose: the wire

package/src/harness/run-turn.ts

@@ -3,7 +3,10 @@
  * every harness, with the engine behind the adapter contract (`types.ts`).
  *
  * What runs here and nowhere else: the activity's identity and its
- * execution-scoped context; the status and the single persist chokepoint;
+ * execution-scoped context; the status, the one transcript builder over it
+ * (born with the status, seeded by the reinvocation phase, handed to the
+ * adapter as `sink.transcript`, finalized once the adapter returns) and the
+ * single persist chokepoint;
  * the periodic heartbeat; the stop controller and its four producers (the
  * stall watchdog, the cost cap, the platform STOP, Temporal's cancellation);
  * the resolution phases (`turn-context.ts`) composed into the `TurnInput`;
@@ -24,9 +27,8 @@
  * registry row, not a branch.
  *
  * Extracted from `activities/execute-cursor/index.ts` `executeCursorInner`
- * (S2 M3; the milestone log in stigmer-cloud
- * `_projects/2026-09/20260911.03.sp.turn-runtime-extraction/` has every
- * ruling). Its twelve resolution phases came out at M2; what came out here is
+ * in #1070, whose body carries the reasoning behind each phase. Its twelve
+ * resolution phases came out first; what came out here is
  * everything between them and after the engine: the seventeen hermetic
  * goldens under `execute-cursor/__tests__/hermetic/` pin the result byte
  * for byte, and `__tests__/run-turn.test.ts` proves the table against the
@@ -81,6 +83,7 @@ import {
   workspaceLockTimeoutArm,
   type TerminalArm,
 } from "./terminal-table.js";
+import { TranscriptBuilder } from "./transcript/builder.js";
 import { resolveTurnContext, type ResolutionDeps, type TurnFrame, type TurnSettlement } from "./turn-context.js";
 import type { HarnessAdapter, TurnInput, TurnSink } from "./types.js";
 import { UsageAccumulator } from "./usage-accumulator.js";
@@ -148,6 +151,15 @@ async function runTurn(deps: TurnRuntimeDeps, input: NormalizedActivityInput): P
     startedAt: utcTimestamp(),
   });
 
+  // The one transcript builder of this turn, born with the status and before
+  // any phase, so it exists for everything that writes a row or an output
+  // onto the status: the write-back coordinator (phase 2c), the seed of a
+  // reinvocation's prior rows (phase 3, through `seed()`, which indexes them
+  // as it appends), the adapter (`sink.transcript`), and the epilogue. One
+  // constructor call per turn; a second builder over the same status would
+  // index the same rows twice.
+  const transcript = new TranscriptBuilder(executionId, status);
+
   // Cold-start timeline of this turn's setup: one mark after each phase, the
   // adapter's own segments marked through the sink, emitted by the adapter
   // once its engine is resolved (an early return skips it — partial setups
@@ -254,7 +266,7 @@ async function runTurn(deps: TurnRuntimeDeps, input: NormalizedActivityInput): P
         );
         // The execution completes here, so its answer rides the slim as it
         // does from `completeTurn`: the seed carried the transcript and any
-        // structured output the paused turn resolved (Q-M4-8).
+        // structured output the paused turn resolved.
         return { kind: "return", value: completionSlim(lastAssistantText()) };
       }
       default: {
@@ -274,7 +286,7 @@ async function runTurn(deps: TurnRuntimeDeps, input: NormalizedActivityInput): P
     // The stall watchdog: the periodic heartbeat proves the process is alive,
     // not that the engine is progressing; if the engine wedges, nothing
     // arrives and the turn would hang forever. Armed for the adapter's whole
-    // stretch (Q-M3-13) and reset by every `recordActivity`; on stall the
+    // stretch and reset by every `recordActivity`; on stall the
     // signal aborts, the adapter cancels its run, and the table reports the
     // stall with the last detail the adapter named.
     watchdog = startStallWatchdog(config.cursorStreamStallTimeoutMs, (idleMs) => {
@@ -288,6 +300,7 @@ async function runTurn(deps: TurnRuntimeDeps, input: NormalizedActivityInput): P
 
     const sink: TurnSink = {
       status,
+      transcript,
       stopSignal: stop.signal,
       setupTiming,
       requestPersist: () => chokepoint.request(),
@@ -343,6 +356,16 @@ async function runTurn(deps: TurnRuntimeDeps, input: NormalizedActivityInput): P
     armedWatchdog.stop();
     heartbeatPhase = "epilogue";
 
+    // The stream is over, however it ended: nothing on the transcript is
+    // still streaming. Here and not only in the adapters' settles, because
+    // this is the one place that sees every path — a turn that failed before
+    // its settle, or ended on a thrown budget, used to persist its last
+    // message with the flag on, a spinner the console never stopped (the
+    // kit's settled-transcript fact caught it on both real adapters).
+    // Idempotent: an adapter that persists on the settled rows mid-settle
+    // finalizes first, as the Cursor harness does before `run.wait()`.
+    transcript.finalize();
+
     // The capture boundary, ONCE, over whatever the whole turn left on the
     // tree — unless a stop fired mid-turn (`interrupted`: the tree may be
     // mid-edit and the pause or drain reinvokes this same turn). Before the
@@ -381,7 +404,7 @@ async function runTurn(deps: TurnRuntimeDeps, input: NormalizedActivityInput): P
         // approval or file-review signal and reinvokes.
         return settleWith(awaitingApprovalArm());
       case "tool_call_limit": {
-        // A review wins over the terminal (Q-M4-2): the limit's copy rides
+        // A review wins over the terminal: the limit's copy rides
         // the transcript and the reinvocation's reconcile completes the turn.
         const settledLimit = await settleWith(reviewPending ? awaitingReviewArm(toolCallLimitArm()) : toolCallLimitArm());
         console.log(`${activityName} terminated (tool-call limit): execution=${executionId}${reviewPending ? ", review pending" : ""}`);
@@ -459,7 +482,7 @@ async function runTurn(deps: TurnRuntimeDeps, input: NormalizedActivityInput): P
   /**
    * The engine finished AND left a reviewable change: the structured output
    * is resolved now, before the WAITING persist, so the resume that
-   * reconciles the review completes with it (Q-M4-8 closes Q-M2a-5); then
+   * reconciles the review completes with it; then
    * the review pause. Nothing else of the completion epilogue runs here —
    * the plan artifact and the write-back belong to the settlement that
    * actually completes the execution.
@@ -530,7 +553,7 @@ async function runTurn(deps: TurnRuntimeDeps, input: NormalizedActivityInput): P
    * unless the adapter already did (the deep-agent's `structuredResponse`):
    * extracted from the final text through the tiers below. Runs where the
    * engine has FINISHED speaking — a completed turn, and a completed turn
-   * the runtime pauses for file review (Q-M4-8: the pure-reconcile
+   * the runtime pauses for file review (the pure-reconcile
    * COMPLETED then carries it, on every harness).
    */
   async function resolveStructuredOutput(turn: TurnInput, finalText: string | undefined): Promise<void> {
@@ -663,6 +686,7 @@ async function runTurn(deps: TurnRuntimeDeps, input: NormalizedActivityInput): P
       client,
       config,
       status,
+      transcript,
       artifactStorage,
       timing: setupTiming,
       signal: cancellationSignal,

package/src/harness/stop-controller.ts

@@ -14,7 +14,7 @@
  *
  * Nothing here is engine-specific and nothing here persists; the Cursor
  * orchestrator kept the same facts as flags on its stream state
- * (`turn-stream.ts` `TurnStreamState`, before S2 M3 moved them out).
+ * (`turn-stream.ts` `TurnStreamState`, before #1070 moved them out).
  */
 
 import type { StallTimeoutError } from "../shared/stall-watchdog.js";

package/src/harness/terminal-table.ts

@@ -9,7 +9,7 @@
  * for byte, `activities/execute-cursor/__tests__/hermetic/`), and a table a
  * reader can scan is how that contract stays reviewable. The native
  * harness once kept one function per arm (`streaming-terminal.ts`, retired
- * at S3 M2b); since S3 M2a both harnesses' turns end through this one table.
+ * in #1096); since #1096 both harnesses' turns end through this one table.
  *
  * The throw-vs-return rule, unchanged from the orchestrator it replaces:
  *  - RETURN when a Temporal retry would only repeat the outcome — a stall
@@ -25,9 +25,9 @@
  * is persisted exactly once, by `run-turn.ts`'s `settleWith` — the one
  * writer of a terminal. The orchestrator this table replaced appended the
  * three THROW arms' rows twice (its throw fell into its own catch, which
- * wrote the copy again); S2 reproduced that on purpose so the goldens could
- * pin the wire byte for byte, and the PR after S2 removed it with a reviewed
- * golden regeneration (stigmer#1054, Q-S2-4).
+ * wrote the copy again); #1070 reproduced that on purpose so the goldens could
+ * pin the wire byte for byte, and the PR after it removed it with a reviewed
+ * golden regeneration (stigmer#1054).
  */
 
 import { create } from "@bufbuild/protobuf";
@@ -174,7 +174,7 @@ export function infrastructureCancelArm(): TerminalArm {
  * The engine proposed at least one gated side effect and stopped: the
  * WAITING_APPROVAL rows are already on the transcript. Not an error, not
  * complete, no copy; RETURN to the workflow, which waits for the approval
- * signal and reinvokes with the decisions. Until S3 M4 this was an inline
+ * signal and reinvokes with the decisions. Until #1096 this was an inline
  * phase flip in `run-turn.ts`; it is an arm because every way an activity
  * ends belongs in this one table.
  */
@@ -193,11 +193,11 @@ export function awaitingApprovalArm(): TerminalArm {
  * tool-call-limit copy; an `engine`-surface failure has none), never its
  * phase, its `error` or its completion stamp, and the resume's reconcile
  * settles the execution COMPLETED as every pure file-review resume does
- * (`fileReviewResolvedArm`). Until S3 M4 only the Cursor harness behaved so,
+ * (`fileReviewResolvedArm`). Until #1096 only the Cursor harness behaved so,
  * and only because its boundary ran before it consulted its engine's
  * result; the deep-agent wrote FAILED with the edits applied and unreviewed.
  * Stated cost: the cloud's `status.error` prefix match for a tool-call limit
- * does not fire when that limit left edits (Q-M4-2).
+ * does not fire when that limit left edits.
  */
 export function awaitingReviewArm(deferred?: TerminalArm): TerminalArm {
   return {