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

package/src/harness/turn-context.ts

@@ -6,7 +6,7 @@
  * with the engine that will run it: the execution and its session, the
  * agent blueprint, the environment, the workspace and its lock, what the
  * previous turn left waiting for approval, the MCP servers and their
- * approval policies, the attachments, the standing context. Until S2 M2
+ * approval policies, the attachments, the standing context. Until #1070
  * that sequence lived inline in the Cursor orchestrator
  * (`activities/execute-cursor/index.ts` `executeCursorInner`, phases 1 to
  * 9c); the native orchestrator carried a second copy in its `performSetup`.
@@ -16,16 +16,16 @@
  * sequences them, and the adapter runs its own harness-specific steps after
  * the whole record exists.
  *
- * Shape, chosen against the native orchestrator's `setup.ts` (deleted at S3
- * M2b): a typed record built from small functions (the `SetupResult` mold),
+ * Shape, chosen against the native orchestrator's `setup.ts` (deleted in
+ * #1096): a typed record built from small functions (the `SetupResult` mold),
  * never one 775-line `performSetup`. The record is the adapter contract's `TurnInput`
  * (`types.ts`): every phase returns a named slice of it, and
  * {@link resolveTurnContext} composes the whole. There is no wider
  * "runtime-private" record beside it — the lock release and the write-back
  * coordinator a phase produces are the caller's `TurnFrame` resources, set
- * the instant they exist so a `finally` sees them on every path (M2 had a
- * `TurnContext extends TurnInput` for them; once the groups lifted, nothing
- * read the extension after composition, so M3 deleted it).
+ * the instant they exist so a `finally` sees them on every path (a first cut
+ * had a `TurnContext extends TurnInput` for them; once the groups lifted,
+ * nothing read the extension after composition, so #1070 shipped without it).
  *
  * Three rules every phase obeys:
  *
@@ -41,17 +41,17 @@
  *  - Its heartbeat pulse and its cold-start timing marks are its own: the
  *    step name it enters under is the mark name it emits, one vocabulary for
  *    "where in setup are we" in Temporal heartbeat details and the
- *    `execution_setup` log (Q-S2-10).
+ *    `execution_setup` log.
  *
  * What is deliberately NOT here, and where it is instead:
  *
  *  - Cursor's catalog validation of the requested model (`resolveModelId`),
  *    the pricing preload and the MCP env pre-flight warning stay in the
- *    Cursor adapter for S2: each reads a module in the adapter column of the
- *    entry's disposition table, and the runtime carries the REQUESTED model
- *    name so every harness validates against its own catalog (S2 M2 gate,
- *    Q-M2-1). The skill mount was in that list until M3b found it reads the
- *    control plane, which only the runtime holds; it is {@link mountSkills}.
+ *    Cursor adapter: each reads a module that is the adapter's own, and the
+ *    runtime carries the REQUESTED model name so every harness validates
+ *    against its own catalog. The skill mount was in that list until #1070
+ *    found it reads the control plane, which only the runtime holds; it is
+ *    {@link mountSkills}.
  *  - The approval grants, the HITL gate, the capture baseline pin and the
  *    Cursor agent itself (phases 5c, 7, 8a, 9) are the adapter's.
  *  - The memory selection is a memoized thunk, not a value: whether a prompt
@@ -81,7 +81,6 @@ import { resolveBlueprint, type ResolvedBlueprint } from "../shared/blueprint-re
 import { resolveExecutionEnv } from "../shared/env-resolver.js";
 import { provisionSessionWorkspace } from "../shared/workspace/session-provision.js";
 import { WriteBackCoordinator } from "../shared/workspace/writeback-coordinator.js";
-import { statusProtoWriter } from "../shared/execution-status-writer.js";
 import { isGitWorkTree } from "../shared/filereview/git-substrate.js";
 import { applyCaptureDecisions, deriveCaptureMode } from "../shared/filereview/capture.js";
 import { casBlobReader } from "../shared/filereview/cas-substrate.js";
@@ -116,6 +115,7 @@ import { readConversationCatchup } from "../shared/conversation-catchup.js";
 import { selectRecalledFacts } from "../shared/memory-retrieval.js";
 import type { RecalledMemoriesContent } from "../shared/recalled-memories.js";
 import type { FileReviewIdentity, HarnessCapabilities, PausePrimitive, StateIdSource } from "./capabilities.js";
+import type { TranscriptBuilder } from "./transcript/builder.js";
 import type {
   TurnAttachments,
   TurnEnvironment,
@@ -135,7 +135,7 @@ import type {
  * What every phase reads from its caller. The activity's identity and the
  * runtime's own seams; nothing harness-specific. The four function members
  * are the caller's, injected so the phase bodies are the same code under
- * the Cursor orchestrator today and under `run-turn.ts` in M3 (only the
+ * the Cursor orchestrator it left and under `run-turn.ts` (only the
  * binding changes), and so a test can drive a phase without a Temporal
  * activity context.
  */
@@ -151,10 +151,20 @@ export interface ResolutionDeps {
   readonly config: Config;
   /**
    * The one execution status this turn folds into. Phases that carry state
-   * across invocations write here (the seeded transcript, the file-review
-   * reconcile's events, the memory-selection report); nothing else does.
+   * across invocations write the runtime's OWN fields here (the file-review
+   * reconcile's events, the memory-selection report, the seeded singletons);
+   * nothing else does.
    */
   readonly status: AgentExecutionStatus;
+  /**
+   * The one transcript builder over `status`, the caller's, born with the
+   * status. Two phases hand it on: the seed appends a reinvocation's prior
+   * rows through it (so they are indexed as they land), and the workspace
+   * phase gives it to the write-back coordinator as the place a write-back
+   * record is registered. No phase folds an event into it — no engine has
+   * run yet.
+   */
+  readonly transcript: TranscriptBuilder;
   /** Resolved once by the caller before any phase; absent when no substrate works. */
   readonly artifactStorage: ArtifactStorage | undefined;
   /** The cold-start timeline; each phase marks its own segment(s) exactly as before. */
@@ -199,7 +209,7 @@ export interface TurnReinvocation {
  * A turn that ended during resolution, before any harness ran. Each arm
  * names what was decided and carries only the facts the caller's status
  * writes need; the copy, the phase flip, the persist and the slim return are
- * the caller's (the orchestrator today, the runtime's terminal table in M3).
+ * the caller's (the runtime's terminal table).
  *
  *  - `workspace-lock-timeout`: another turn held the primary tree past
  *    `Config.workspaceLockTimeoutMs`. FAILED, returned (a Temporal retry
@@ -238,7 +248,7 @@ export type ReinvocationOutcome =
 /**
  * Whether the engine already holds state for this execution, so this
  * invocation resumes rather than begins. One function keyed on how the
- * harness mints its state id (Q-S2-8):
+ * harness mints its state id:
  *
  *  - `engine-minted` (Cursor: the agent id): the runtime knows nothing until
  *    the adapter binds an id, so a non-empty `threadId` IS the evidence.
@@ -260,7 +270,7 @@ export type ReinvocationOutcome =
  * the exact-apply). An adapter that needs create-vs-resume for its ENGINE
  * reads `input.threadId` itself — for an engine-minted harness that is the
  * same bit, for a deterministic one the engine's checkpoint is the adapter's
- * to consult — so the contract carries no flag with two meanings (Q-M1-7).
+ * to consult — so the contract carries no flag with two meanings.
  */
 export function isReinvocation(
   stateIdSource: StateIdSource,
@@ -299,10 +309,10 @@ export interface ReinvocationFacts {
  * nothing else is complete, because keeping or discarding a file never
  * re-prompts the agent (Cursor-like). `undefined` means "run the agent".
  *
- * Until S3 M1 a REJECT failed the turn here with its own FAILED arm, Cursor's
+ * Until #1096 a REJECT failed the turn here with its own FAILED arm, Cursor's
  * legacy; the proto (`APPROVAL_ACTION_REJECT`: "does NOT fail the run"), the
  * conformance suite and the native harness said otherwise since stigmer#197,
- * and the runtime now agrees (S2 M4 finding F1; Q-S3-2).
+ * and the runtime now agrees.
  */
 export function decideReinvocation(
   facts: ReinvocationFacts,
@@ -326,14 +336,15 @@ export function decideReinvocation(
  *
  * Why the transcript must be seeded: a resumed engine re-issues the
  * previously gated tool calls with brand-new call ids. Without seeding, the
- * harness's accumulator would rebuild the transcript from empty and emit a
+ * harness's transcript builder would rebuild the transcript from empty and emit a
  * status that drops the already-committed tool-call ids. The backend's
  * append-only-at-identity guard rejects any non-terminal update that drops a
  * committed tool-call id, so the resumed progress would never persist: the
  * run stalls in WAITING_FOR_APPROVAL with no pending approvals and the
  * workflow watchdog fails it. Seeding makes the resume status a strict
  * superset; the re-runs are then reconciled in place onto these seeded calls
- * by canonical identity inside the accumulator.
+ * by canonical identity inside the harness's translator (the Cursor translator's
+ * seeded-row match; the native builder's by-id flip).
  *
  * Why the OTHER collections must be seeded too — the server's merge rule
  * (`stigmer-server/src/domain/agentexecution/update-status.ts`): every list
@@ -355,28 +366,32 @@ export function decideReinvocation(
  * `phase`, `startedAt`, `completedAt`, `error` are this turn's fresh
  * terminal, written by the runtime.
  *
- * Every collection is mutated IN PLACE (pushed into, assigned into), never
- * reassigned: the write-back coordinator already wraps this status through
- * `statusProtoWriter`, and the harness's accumulator wraps `messages` and
- * `subAgentExecutions` by reference after this runs, so a reassigned array
- * would leave a wrapper holding the old one. The persisted protos are
- * cloned so the input execution stays immutable.
+ * The transcript half — messages, sub-agent rows, artifacts, write-backs,
+ * todos — goes through the builder's `seed()`, which appends every
+ * collection IN PLACE (the status's own arrays, so every wrapper of the
+ * status keeps seeing every row) and indexes the rows as it appends, so the
+ * upcoming turn's re-issued call reconciles onto its seeded row. The three
+ * singletons are the runtime's own and are set here. The persisted protos
+ * are cloned so the input execution stays immutable.
  *
  * Moved from `execute-cursor/index.ts` `seedCursorTranscriptFromExecution`
- * (messages only) and widened at S3 M1 to what native's whole-status clone
+ * (messages only) and widened in #1096 to what native's whole-status clone
  * (`execute-deep-agent/index.ts` `seedStatusFromExecution`, retired with its
  * orchestrator) always carried, minus the fields above that it carried by
- * accident (Q-S3-16).
+ * accident. Until #1097 the transcript half was pushed straight
+ * onto the status here and the adapters constructed their builders after
+ * this ran — an ordering the builder's index depended on and nothing
+ * enforced; the seed through the builder makes it a non-question.
  */
-export function seedFromPersistedStatus(status: AgentExecutionStatus, execution: AgentExecution): void {
+export function seedFromPersistedStatus(
+  status: AgentExecutionStatus,
+  transcript: TranscriptBuilder,
+  execution: AgentExecution,
+): void {
   const persisted = execution.status;
   if (!persisted || persisted.messages.length === 0) return;
   const seed = clone(AgentExecutionStatusSchema, persisted);
-  status.messages.push(...seed.messages);
-  status.subAgentExecutions.push(...seed.subAgentExecutions);
-  status.artifacts.push(...seed.artifacts);
-  status.workspaceWriteBacks.push(...seed.workspaceWriteBacks);
-  for (const [id, todo] of Object.entries(seed.todos)) status.todos[id] = todo;
+  transcript.seed(seed);
   if (seed.streamingUsage !== undefined) status.streamingUsage = seed.streamingUsage;
   if (seed.recalledMemoriesReport !== undefined) status.recalledMemoriesReport = seed.recalledMemoriesReport;
   if (seed.structuredOutput !== undefined) status.structuredOutput = seed.structuredOutput;
@@ -459,7 +474,7 @@ export async function provisionWorkspace(
 
   const writeback = provision.provisionResults.length > 0
     ? new WriteBackCoordinator({
-        statusWriter: statusProtoWriter(deps.status),
+        writeBacks: deps.transcript,
         executionId: deps.input.executionId,
         sessionId: args.sessionId,
         githubToken: args.envVars.GITHUB_TOKEN ?? "",
@@ -550,7 +565,7 @@ export async function bindTelemetryBaggage(
  *
  * On a reinvocation, first seed the in-progress status from the persisted
  * execution ({@link seedFromPersistedStatus}), BEFORE the harness's
- * accumulator wraps `status.messages`. Then the file-review reconcile (the
+ * transcript builder wraps `status.messages`. Then the file-review reconcile (the
  * dual-source half): every change set the server projected as DECIDED is
  * reconciled from the ledger decisions and the pinned git refs (approved
  * kept at their "after" bytes, rejected snapped back to baseline, all
@@ -583,7 +598,7 @@ export async function reconcileReinvocation(
 
   if (reinvoked) {
     const existingStatus = args.execution.status;
-    seedFromPersistedStatus(deps.status, args.execution);
+    seedFromPersistedStatus(deps.status, deps.transcript, args.execution);
 
     if (args.workspace.captureMode && args.workspace.primaryDir) {
       const decidedSets = (existingStatus?.fileChangeSets ?? []).filter(
@@ -782,10 +797,10 @@ export async function resolveMcpServersAndPolicies(
  * its to render. One progress label for the whole phase, as before.
  *
  * The `.stigmer` link this and the attachment phase create is removed in
- * the runtime's finally, after the harness's own teardown. Until S3 M1 the
+ * the runtime's finally, after the harness's own teardown. Until #1096 the
  * native orchestrator fetched and mounted sub-agent skills itself
  * (`subagent-transformer.ts` with a client); this phase is where that read
- * lives now (Q-S3-5).
+ * lives now.
  */
 export async function mountSkills(
   deps: ResolutionDeps,
@@ -824,8 +839,8 @@ export async function mountSkills(
  * actually see the image. Full model validation is not needed for this. The
  * Cursor harness with no model named builds its own catalog default instead
  * (`resolveModelId("default")`), so for it this is an approximation: today
- * both answers read as sighted, and the exact per-harness default is S4's
- * to declare (S3 M1 finding F-M1-4). The vision profile is the harness's
+ * both answers read as sighted, and the exact per-harness default is not yet
+ * declared. The vision profile is the harness's
  * (each engine accepts different image shapes), so it arrives as an
  * argument.
  */
@@ -878,9 +893,9 @@ export async function resolveTurnAttachments(
  * re-attempts the call — both regenerate. An `interrupt` engine checkpoints
  * AT the call and applies its exact args on `approve`, so a runner-side
  * write would land the same bytes twice and pre-empt a row the engine is
- * about to execute; `none` gates nothing. Until S3 M2a the phase ran for
+ * about to execute; `none` gates nothing. Until #1096 the phase ran for
  * every harness — a deny-and-retry mechanism the native harness would have
- * met on its first deny-gated file approval (F-M2a-2, Q-M2a-3).
+ * met on its first deny-gated file approval.
  */
 export function regeneratesApprovedWrites(pausePrimitive: PausePrimitive): boolean {
   switch (pausePrimitive) {

package/src/harness/types.ts

@@ -21,9 +21,8 @@
  * (`execute-cursor/turn-stream.ts` `CursorTurnStreamDeps`) or a fact the
  * runtime cannot read anywhere else. Nothing here is speculative: where the
  * program's original sketch and the code disagreed, the code won, and the
- * disagreement was ruled at the entry's gate
- * (stigmer-cloud `_projects/2026-09/20260911.02.sp.harness-contract-and-kit/`
- * for S1; `20260911.03.sp.turn-runtime-extraction/` M3 for the growth below).
+ * disagreement was ruled before the code landed (#1064; the growth below in
+ * #1070).
  *
  * What is deliberately NOT on this contract, and why:
  *
@@ -31,11 +30,13 @@
  *    (`maxConcurrentActivities`), so a per-turn teardown method on the
  *    adapter is a race. The adapter owns its per-turn teardown in its own
  *    `finally` inside `runTurn` (the Cursor harness parks its agent there).
- *  - No `isCancelled()`, no `heartbeat(details)`, no `ExecutionStatusWriter`
- *    base. Each would be a second way of saying something `stopSignal`,
- *    `recordActivity()` or `requestPersist()` already says, and two writers of
- *    one fact drift (the native builders' `forceNextUpdate` flag is the same
- *    fact as a `requestPersist()` call).
+ *  - No `isCancelled()`, no `heartbeat(details)`, and the sink does not
+ *    EXTEND a status-writer interface. Each would be a second way of saying
+ *    something `stopSignal`, `recordActivity()` or `requestPersist()` already
+ *    says, and two writers of one fact drift. The transcript builder rides
+ *    the sink as a MEMBER (`transcript`), and the distinction holds: its
+ *    `dirty` is a fact the adapter's persist decision reads, `requestPersist()`
+ *    is the act; one fact, one act, no second writer.
  *  - No `reason` on `interrupted`, no payload on `completed`, no `retryable`
  *    on `failed`. Every cause of stopping is the runtime's own evidence; the
  *    final text and structured output are already folded onto the status;
@@ -53,9 +54,9 @@
  *    propagates it.
  *  - No persist cadence. The runtime's chokepoint is single-flight and
  *    unconditional at settle; WHEN a streaming turn asks for a write is the
- *    adapter's (`shared/persist-decision.ts` over its own dirty flags, since
- *    what counts as a discrete change is engine knowledge). Revisited with
- *    both loops in view at S3 M4 and kept (Q-S3-13): the cadence RULE is
+ *    adapter's (`shared/persist-decision.ts` over the builder's `dirty`
+ *    flag, since WHEN to ask is engine cadence). Revisited with
+ *    both loops in view in #1096 and kept: the cadence RULE is
  *    shared, the timing is the engine's.
  *  - No capture. The file-review capture is the runtime's whole
  *    (`harness/capture.ts`): the baseline before `runTurn`, the candidate
@@ -90,6 +91,7 @@ import type { DeclaredPreferencesContent } from "../shared/declared-preferences.
 import type { RecalledMemoriesContent } from "../shared/recalled-memories.js";
 import type { CasTouchedReader } from "../shared/filereview/cas-touched.js";
 import type { HarnessCapabilities } from "./capabilities.js";
+import type { TranscriptBuilder } from "./transcript/builder.js";
 
 /**
  * One harness, as the runtime sees it. ONE adapter object exists per worker
@@ -325,14 +327,36 @@ export interface TurnInput extends NormalizedActivityInput {
  * one status it folds into. One sink per turn, owned by the runtime; the
  * adapter never constructs one.
  *
- * Field ownership on `status` before the canonical transcript lands (S4):
- * the adapter appends the engine's transcript rows (assistant messages,
- * tool-call rows and their approval status, sub-agent rows, todos); the
- * runtime writes the phase, the terminal system messages, `streamingUsage`,
- * artifacts, write-backs, `fileChangeProgress`, the file-review ledger
- * events and the change-set stamp on a flowed edit row (S3 M4,
- * `harness/capture.ts`). An adapter never writes a phase or a terminal copy:
- * those are Temporal semantics the runtime owns once.
+ * Field ownership on `status` (since #1097, the canonical transcript):
+ *
+ *  - Transcript rows — messages, tool-call rows, sub-agent rows, todos — are
+ *    CREATED through `transcript` and nowhere else: the adapter translates
+ *    its engine's events and applies them; a reinvocation's prior rows are
+ *    seeded through it by the runtime. The one exception, the runtime's own
+ *    terminal system rows (`harness/terminal-table.ts`), is the second name
+ *    on the writer fence's allow-list (`__tests__/transcript-writers.test.ts`).
+ *  - Artifacts and write-backs a turn produces register through `transcript`
+ *    too (the native inline publisher; the runtime's write-back coordinator),
+ *    each dedupe rule owned once. The one artifact written beside it is the
+ *    epilogue's plan artifact (`shared/plan-artifact.ts`), the runtime's,
+ *    which supersedes by the plan's own name rule.
+ *  - Rows may be AMENDED by identity, never created, by the modules that own
+ *    a fact the builder cannot know, and this is the whole list: the runtime's
+ *    `harness/approval-decisions.ts` (a SKIP or REJECT settles its row),
+ *    `harness/capture.ts` (the change-set stamp on a flowed edit row),
+ *    `shared/exact-apply.ts` (an approved whole-file write applied by the
+ *    runtime completes its row), `shared/subagent-rows.ts` (a stopped turn's
+ *    sub-agents CANCELLED); the Cursor boundary (`execute-cursor/
+ *    boundary-rows.ts`: the identity-token collapses, #205, #965, the
+ *    unattended stamp); the native settle (`execute-deep-agent/hitl.ts`: the
+ *    gate's unattended skips). A harness that amends says so in its settle's
+ *    header.
+ *  - The runtime alone writes the phase, `startedAt`, `completedAt`,
+ *    `error`, the terminal system rows, `streamingUsage`,
+ *    `fileChangeProgress`, the file-review ledger events and the change-set
+ *    stamp (`harness/capture.ts`, since #1096), and closes every streaming flag
+ *    once `runTurn` returns. An adapter never writes a phase or a terminal
+ *    copy: those are Temporal semantics the runtime owns once.
  */
 export interface TurnSink {
   /**
@@ -342,6 +366,24 @@ export interface TurnSink {
    */
   readonly status: AgentExecutionStatus;
 
+  /**
+   * The one transcript builder over `status`, constructed by the runtime
+   * per turn and already holding a reinvocation's seeded rows. The ONE way
+   * a transcript row is created: a harness translates its engine's events
+   * into `TranscriptEvent`s and `apply`s them; its post-stream facts (a
+   * gate parked by a boundary, a disclosure) go in as events too. Artifacts
+   * and write-backs a turn produces register here as well (`addArtifact`,
+   * `addWriteBack`, one dedupe rule each). Read `dirty` to decide a
+   * streaming persist and call `markPersisted()` as you request it; read
+   * `awaitingApproval` to learn a proposal was parked. The runtime calls
+   * `finalize()` once `runTurn` returns, on every path, so no streaming flag
+   * outlives a turn; a harness may call it earlier when it persists on the
+   * settled rows itself. A source-walking fence
+   * (`harness/__tests__/transcript-writers.test.ts`) refuses any other
+   * creator of a row.
+   */
+  readonly transcript: TranscriptBuilder;
+
   /**
    * The ONE way a turn is told to stop, whatever the cause: user pause,
    * worker shutdown, stall, cost cap, platform STOP. The runtime knows why
@@ -402,7 +444,7 @@ export interface TurnSink {
    * step only the adapter knows ("Initializing Cursor agent"). The runtime
    * reports its own resolution labels itself; the adapter reports the labels
    * of its setup steps exactly as the orchestrator did, so the UI's spinner
-   * copy is unchanged by the extraction (Q-S2-5). Resolves once the label is
+   * copy is unchanged by the extraction. Resolves once the label is
    * written; the write carries no phase, so it never advances the execution.
    */
   reportProgress(label: string): Promise<void>;
@@ -415,7 +457,7 @@ export interface TurnSink {
    * cleared, the agnostic quirk of `BuildUpdateStateStep`); the adapter may
    * set its own harness-specific `SessionSpec` fields on that record before
    * binding, one writer per field (`harnessStateId` the runtime's,
-   * `cursorMode` the adapter's; Q-S2-11). Called only by adapters whose
+   * `cursorMode` the adapter's). Called only by adapters whose
    * `capabilities.stateIdSource` is `"engine-minted"`, and before their first
    * `requestPersist`; a `deterministic` harness never calls it. Rejects when
    * the session write fails; the adapter then ends the turn `failed` with
@@ -448,7 +490,7 @@ export interface TurnSink {
  * Token counts for one engine turn, priced. The four counts are what the
  * Cursor loop reads from the SDK's `turn-ended` delta; `estimatedCostUsd` is
  * the adapter's price for them at its vendor's rates (the runtime cannot
- * price without the vendor's table and must not import it; Q-S2-12), and
+ * price without the vendor's table and must not import it), and
  * `model` / `requestedModelParams` name the basis it priced against, which
  * the runtime records into `streamingUsage` (`model` is the catalog-validated
  * id, `requestedModelParams` the JSON of the params sent — a string on the

package/src/harness/usage-accumulator.ts

@@ -4,7 +4,7 @@
  * the persist chokepoint writes before every status write, and the running
  * cost the `max_cost_usd` cap is enforced against.
  *
- * Who owns what (Q-S2-12): the ADAPTER prices, because only it has its
+ * Who owns what: the ADAPTER prices, because only it has its
  * vendor's rate table and variant semantics (`execute-cursor/usage-pricing.ts`
  * for Cursor); the RUNTIME accounts and enforces, because the cap and the
  * summary are the platform's, the same for every engine. A delta therefore
@@ -14,7 +14,7 @@
  * preferences (`TurnInput.model`), the audit trail that the account default
  * was never left in control (#357, #772).
  *
- * Moved from `activities/execute-cursor/usage-accumulator.ts` at S2 M3, the
+ * Moved from `activities/execute-cursor/usage-accumulator.ts` in #1070, the
  * pricing call split out; the sums, the snapshot shape and the empty
  * snapshot are unchanged, so `streamingUsage` is byte-for-byte what the
  * Cursor orchestrator wrote.

package/src/harness-adapters.ts

@@ -14,7 +14,7 @@
  * adapter's interceptors must patch `node:http2` before anything dials the
  * control plane, so it boots first. The native deep-agent adapter boots
  * second; its `boot` registers the deepagents harness profiles and loads
- * LangChain, both after the patch (S3 M2b, 2026-09-13; until then the roots
+ * LangChain, both after the patch (#1096, 2026-09-13; until then the roots
  * imported the native orchestrator directly beside this table).
  *
  * THIS MODULE'S STATIC GRAPH MUST STAY CONNECT- AND SDK-FREE. The roots
@@ -22,9 +22,10 @@
  * where `node:http2` is patched and `@cursor/sdk` first loaded; an adapter
  * factory that imported its SDK statically would defeat both. Every adapter
  * named here loads its vendor SDK inside `boot` (`execute-cursor/adapter.ts`
- * and `execute-deep-agent/adapter.ts` show the shape; each has a fence that
- * walks its static graph). `__tests__/harness-boot-order.test.ts` boots a
- * fresh process through this module — both rows — and fails if the graph
+ * and `execute-deep-agent/adapter.ts` show the shape; the native adapter's
+ * `__tests__/adapter-graph-is-sdk-free.test.ts` walks its static graph off
+ * the syntax tree). `__tests__/harness-boot-order.test.ts` boots a fresh
+ * process through this module — both rows — and fails if either graph
  * regresses.
  */
 

package/src/middleware/__tests__/cost-advisory.test.ts

@@ -3,9 +3,9 @@
  * running total the sub-agent views share, and warns the model ONCE at the
  * configured share of `max_cost_usd`. Nothing here caps: the enforcement is
  * the turn runtime's (`shared/__tests__/cost-guard.test.ts`,
- * `harness/__tests__/run-turn.test.ts`'s cost-cap arm). Until S3 M2b this
+ * `harness/__tests__/run-turn.test.ts`'s cost-cap arm). Until #1096 this
  * file was `cost-cap.test.ts` and also pinned the in-graph tool block and
- * the "exceeded" message — retired with that half (Q-S3-3, Q-M2b-9).
+ * the "exceeded" message — retired with that half.
  */
 
 import { describe, it, expect } from "vitest";

package/src/middleware/approval-gate.ts

@@ -24,6 +24,12 @@
  * unrecognized mutating built-in (e.g. `bash`, `overwrite_file`) is therefore
  * gated by what it does, not by whether someone remembered to list it.
  *
+ * The decision itself — `resolveToolApproval` — lives in
+ * `shared/approval-policy.ts` beside its provenance twin since #1097:
+ * the native translator reports the same answer on every
+ * `tool_started`, so the transcript row and this gate can never disagree
+ * about whether a call waits. This module is where the decision is ACTED on.
+ *
  * Gateway invariant (Phase 2): this middleware IS the in-process execution
  * gateway for the deep-agent harness — `handler(request)` is the side effect. A
  * side effect runs only with a backing authorization: either (a) the tool was
@@ -50,7 +56,7 @@ import {
   type MergedToolPolicy,
   type PolicySource,
   POLICY_ENGINE_VERSION,
-  resolveApprovalMessage,
+  resolveToolApproval,
   unattendedSkipMessage,
 } from "../shared/approval-policy.js";
 import { toolApprovalCategory, type ToolApprovalCategory } from "../shared/tool-kind.js";
@@ -164,16 +170,6 @@ interface ApprovalDecision {
   readonly comment?: string;
 }
 
-// Approval-message template per mutating category. Keyed by category (not raw
-// tool name) so every alias of a mutation renders one message; placeholders
-// resolve against the deep-agent stream arg shape (`path`/`command`). Mirrors
-// the Cursor side's CATEGORY_APPROVAL_MESSAGE.
-const CATEGORY_APPROVAL_MESSAGE: Record<ToolApprovalCategory, string> = {
-  write: "Write file: {{args.path}}",
-  delete: "Delete: {{args.path}}",
-  shell: "Execute command: {{args.command}}",
-};
-
 /**
  * The ToolMessage returned when a secret-like write is hard-blocked (DD-E /
  * DD-26 #2): the write is NEVER applied and the graph continues (this replaces
@@ -383,69 +379,6 @@ export function createApprovalGateMiddleware(
   };
 }
 
-interface ApprovalRequirement {
-  readonly requiresApproval: boolean;
-  readonly message: string;
-  /** Which policy layer determined this verdict — stamped on the shadow receipt. */
-  readonly source: PolicySource;
-}
-
-function resolveToolApproval(
-  toolName: string,
-  serverSlug: string,
-  args: Record<string, unknown>,
-  policies: ReadonlyMap<string, MergedToolPolicy>,
-  leasedCategories: ReadonlySet<ToolApprovalCategory>,
-): ApprovalRequirement {
-  if (serverSlug) {
-    // MCP tools stay governed by the connect-flow classifier + four-level policy
-    // chain. The policy map carries only the tools that REQUIRE approval, so an
-    // absent entry means the classifier already auto-approved it — fail-OPEN is
-    // correct here (a fail-closed default would re-gate everything the classifier
-    // cleared). This is deliberately NOT changed by the built-in fail-closed flip.
-    //
-    // A server-scoped lease surfaces here as an absent entry too: the leased
-    // server's tools are dropped from `policies` upstream (mergeApprovalPolicies),
-    // so a lease-cleared MCP tool takes this same auto-approve path. (Its shadow
-    // receipt therefore reads classifier_default rather than approval_lease; a
-    // faithful per-server lease provenance would need the lease set threaded here
-    // and is deferred with the rest of the persisted-receipt work.)
-    const key = `${serverSlug}/${toolName}`;
-    const policy = policies.get(key);
-    if (policy) {
-      return {
-        requiresApproval: policy.requiresApproval,
-        message: resolveApprovalMessage(policy.approvalMessage, toolName, args),
-        source: policy.source,
-      };
-    }
-    // Absent = cleared by the MCP four-level chain (classifier base) or by a
-    // server-scoped lease (dropped upstream).
-    return { requiresApproval: false, message: "", source: "classifier_default" };
-  }
-
-  // Built-in/platform tool: gate exactly the mutating categories via the shared
-  // classifier. Fail-CLOSED for the mutating set — any built-in classifyTool
-  // deems write/edit/delete/shell requires approval. Read-only and unclassified
-  // built-ins are not mutating, so they remain fail-open.
-  const category = toolApprovalCategory(toolName);
-  if (category) {
-    // Run-lifetime category lease: the user chose "approve all <category>"
-    // earlier in this run, so every built-in of that category is auto-approved
-    // for the rest of the run (the scoped successor to auto-approve-all).
-    if (leasedCategories.has(category)) {
-      return { requiresApproval: false, message: "", source: "approval_lease" };
-    }
-    return {
-      requiresApproval: true,
-      message: resolveApprovalMessage(CATEGORY_APPROVAL_MESSAGE[category], toolName, args),
-      source: "builtin_category",
-    };
-  }
-
-  return { requiresApproval: false, message: "", source: "builtin_category" };
-}
-
 /** Shared empty set so a config without leases allocates nothing per call. */
 const EMPTY_CATEGORY_SET: ReadonlySet<ToolApprovalCategory> = new Set();
 

package/src/middleware/cost-advisory.ts

@@ -11,17 +11,17 @@
  * shape `execution-budget.ts` already has beside LangGraph's `recursionLimit`:
  * the middleware warns inside the graph, the engine's own limit enforces.
  *
- * Until S3 M2b (Q-S3-3) this module was `cost-cap.ts` and did both: it also
+ * Until #1096 this module was `cost-cap.ts` and did both: it also
  * blocked every tool call once the running cost passed the cap and gave the
  * model one tool-free round to summarize. That second enforcement lived
  * inside the graph, where the runtime could not see it, and a platform STOP
  * had a sibling (`graceful-stop.ts`, deleted with it) that let the run spend
  * a summary round after the platform said stop. Both went when the runtime
- * became the one place a turn is stopped (harness runtime program, S3).
+ * became the one place a turn is stopped.
  *
  * afterModel — reads `usage_metadata` off the latest AIMessage, prices the
  *   call at the parent's rates (a sub-agent on its own model is priced the
- *   same way the enforcement prices it; per-sub-agent pricing is an S5 item),
+ *   same way the enforcement prices it; per-sub-agent pricing is #1121),
  *   accumulates the running total, and injects the warning SystemMessage once
  *   at `warningPct` of the cap.
  *

package/src/middleware/index.ts

@@ -21,7 +21,7 @@
  * Every middleware here either shapes the graph's tool surface or ADVISES
  * the model; none of them stops the run. A stop — the platform's, the
  * cost cap's, a stall's — is the turn runtime's, delivered to the graph
- * through its abort signal (harness runtime program, S3 Q-S3-3; until M2b a
+ * through its abort signal (since #1096; until then a
  * graceful-stop middleware and the cost cap's tool block were second stops
  * inside the graph that the runtime could not see).
  *

package/src/runner-manager.ts

@@ -701,7 +701,7 @@ export function mapManagerOptionsToConfig(
     // The manager's proxy credential is the minted runner token once adopted
     // (the control-plane token in lockstep before that), so it is this ref and
     // not `tokenRef`: binding `tokenRef` would keep sending the desktop's own
-    // Auth0 token as x-stigmer-auth after the mint (Q-S2-7).
+    // Auth0 token as x-stigmer-auth after the mint.
     proxyTokenRef: runnerTokenRef,
     cursorApiKey: proxyActive
       ? (options.cursorApiKey ?? "proxy-managed")