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

package/src/shared/args-preview.ts

@@ -8,9 +8,29 @@
  * JSON: the per-tool offload does not touch it, and the aggregate size backstop
  * would replace an oversized preview with an unparseable marker.
  *
- * This module is the single home for arg sanitization shared by both harnesses
- * (native re-exports {@link sanitizeArgsPreview} from its status builders; the
- * Cursor gate path uses {@link buildElidedArgsPreview}).
+ * ONE preview rule for every row (since #1097): the transcript builder
+ * stamps every tool row's preview through {@link buildElidedArgsPreview} over
+ * {@link SALIENT_ARG_FIELDS}, as `message.proto` promises — sanitized,
+ * redacted, at creation, for inline visibility. Until then there were two
+ * rules: native stamped a whole-string-truncating `sanitizeArgsPreview` on
+ * gated rows only (a preview that could truncate to invalid JSON, acceptable
+ * only because native's resume never re-parsed it), and Cursor's stream path
+ * stamped `JSON.stringify(args)` unredacted. Both are
+ * gone; this module holds the one builder and the one salient list.
+ *
+ * THE PREVIEW NEVER CARRIES A VALUE IT CANNOT CARRY WHOLE. A non-salient
+ * string over the per-value cap is left out of the preview — not replaced by
+ * an in-band marker. The marker this module wrote until #1097 (`"[381
+ * chars]"`) was a string no reader could tell from content: the approval gate
+ * rendered it as the file the user was asked to approve (stigmer#1107). An
+ * absent key is the out-of-band signal every reader already handles — a
+ * surface that needs the whole value reads the row's `args`, the way the
+ * gate does now; the codebase's precedent for "content not included" is a
+ * typed fact on the wire (file review's `FileReviewBlockReason`), never a
+ * display string, and the approval projection gaining such a fact is a
+ * follow-up of its own. The cost, named: the CLI's and ink's one-line preview
+ * loses the value's size, and Cursor's recovery digest reads `tool({})` for
+ * an MCP tool whose only argument is oversized.
  */
 
 /**
@@ -22,24 +42,27 @@ export const SENSITIVE_ARG_KEYS: ReadonlySet<string> = new Set([
   "credentials", "auth", "authorization",
 ]);
 
-/** Whole-preview length cap for {@link sanitizeArgsPreview} (native). */
-export const MAX_ARGS_PREVIEW_LENGTH = 500;
-
 /**
- * Sanitize args into a compact preview string (native harness behavior).
- *
- * Redacts sensitive keys, then truncates the whole JSON to a fixed length. The
- * truncation can yield invalid JSON, which is acceptable for the native harness
- * (its resume model keys on `tool_call_id`, never on a re-parsed preview). The
- * Cursor gate path must instead use {@link buildElidedArgsPreview}, which keeps
- * the JSON valid and preserves the salient identity fields.
+ * Top-level tool-argument fields, in priority order, that identify the specific
+ * resource a built-in tool acts on — the values a preview must carry VERBATIM,
+ * however long, because an identity is parsed back out of them. The list
+ * deliberately spans BOTH taxonomies' arg shapes: Cursor's hook input names a
+ * file `file_path` and its stream names it `path`; deepagents' file tools send
+ * `file_path`; both name a shell command `command`. Extracting the same
+ * resource VALUE on both sides (the absolute path / the command string) is
+ * what lets the Cursor hook-recorded denial token equal the stream-computed
+ * token. Authored here once (moved from `execute-cursor/approval-policy.ts`
+ * in #1097) and injected into the generated preToolUse hook script
+ * so the runner and the hook never disagree on which field to match.
  */
+export const SALIENT_ARG_FIELDS = ["file_path", "path", "target_notebook", "command"] as const;
+
 /**
  * Redact secret-keyed values (see {@link SENSITIVE_ARG_KEYS}), preserving every
- * other entry verbatim. The shared first step of both preview builders, and the
- * shape stamped as `args` on interrupt-placeholder tool calls (issue #754's
- * header fix): full enough for the UI's path/primary-arg extraction, never
- * carrying a secret value.
+ * other entry verbatim. The first step of the preview builder, and the shape
+ * stamped as `args` on a proposed row the harness recovered from its engine's
+ * state (issue #754's header fix): full enough for the UI's path/primary-arg
+ * extraction, never carrying a secret value.
  */
 export function redactSensitiveArgs(
   args: Record<string, unknown>,
@@ -51,18 +74,6 @@ export function redactSensitiveArgs(
   return redacted;
 }
 
-export function sanitizeArgsPreview(args: Record<string, unknown>): string {
-  const sanitized = redactSensitiveArgs(args);
-  try {
-    const json = JSON.stringify(sanitized);
-    return json.length > MAX_ARGS_PREVIEW_LENGTH
-      ? json.slice(0, MAX_ARGS_PREVIEW_LENGTH) + "…"
-      : json;
-  } catch {
-    return "";
-  }
-}
-
 /** Per-string-value cap for {@link buildElidedArgsPreview}. */
 const MAX_PREVIEW_VALUE_LENGTH = 200;
 
@@ -70,18 +81,19 @@ const MAX_PREVIEW_VALUE_LENGTH = 200;
  * Build a compact, ALWAYS-VALID `args_preview` from a tool call's full,
  * authoritative arguments.
  *
- * Unlike {@link sanitizeArgsPreview} (which truncates the whole string, possibly
- * to invalid JSON), this elides oversized string *values* in place — preserving
- * every key and the JSON structure. Two invariants make it safe for the Cursor
- * gate path:
+ * Leaves oversized string *values* out — every other key and the JSON
+ * structure kept — rather than truncating the whole string. Two invariants
+ * make it safe for the Cursor gate path:
  *  - It NEVER elides a salient field (the resume grant's identity — the file
  *    path or shell command — is parsed back out of this preview, so it must
  *    survive verbatim).
  *  - It redacts secret keys.
  *
+ * For short, secret-free args the output is exactly `JSON.stringify(args)`.
  * The heavy content (a whole-file body, a large diff) lives on `file_changes`
  * (offloaded to a ref when large) and `args` (bounded by the size backstop), so
- * the preview itself stays small even for a multi-MB write.
+ * the preview itself stays small even for a multi-MB write. Unserializable
+ * args (a cycle) yield `""`, never a thrown row.
  *
  * @param args the full tool arguments
  * @param salientFields keys whose values must be preserved verbatim (identity)
@@ -94,15 +106,12 @@ export function buildElidedArgsPreview(
   for (const [key, value] of Object.entries(args)) {
     if (SENSITIVE_ARG_KEYS.has(key.toLowerCase())) {
       out[key] = "[REDACTED]";
-    } else if (
-      !salientFields.includes(key) &&
-      typeof value === "string" &&
-      value.length > MAX_PREVIEW_VALUE_LENGTH
-    ) {
-      out[key] = `[${value.length} chars]`;
-    } else {
-      out[key] = value;
+      continue;
     }
+    const oversized = typeof value === "string" && value.length > MAX_PREVIEW_VALUE_LENGTH;
+    // An oversized non-salient value is left out, never marked (see the header).
+    if (oversized && !salientFields.includes(key)) continue;
+    out[key] = value;
   }
   try {
     return JSON.stringify(out);

package/src/shared/attachment-resolver.ts

@@ -24,7 +24,7 @@
  * written into the user's own tree would be committed to the session's
  * write-back branch on completion (`git add -A`), and every real producer —
  * the CLI's directory attachments, the approved plan the console mounts —
- * already stays inside `inputs/` (S3 M1, Q-M1-2; the proto's `/workspace/…`
+ * already stays inside `inputs/` (since #1096; the proto's `/workspace/…`
  * example is a doc issue). The prompt's `<input_files>` section and every
  * path-derived directive are built from the RESOLVED paths, so prompt and
  * filesystem can never disagree.
@@ -52,9 +52,9 @@
  * {@link AttachmentResolutionError}; an archive that fails its guards
  * aborts with the guard's own `AttachmentValidationError`.
  *
- * Until S3 M1 this resolver ignored `mountPath` and could not extract; the
- * native harness's `attachment-injector.ts` did both and was retired at S3
- * M2b for this one pipeline (Q-S3-14).
+ * Until #1096 this resolver ignored `mountPath` and could not extract; the
+ * native harness's `attachment-injector.ts` did both and was retired in that
+ * PR for this one pipeline.
  */
 
 import { mkdir, copyFile, readFile, stat, writeFile } from "node:fs/promises";

package/src/shared/attachment-vision.ts

@@ -118,7 +118,8 @@ export type VisionOutcome =
 /**
  * What a harness can actually display inline. The split exists because the
  * Cursor local transport re-sniffs magic bytes and recognizes ONLY PNG and
- * JPEG (verified against @cursor/sdk 1.0.13 dist — the declared mimeType is
+ * JPEG (verified against the @cursor/sdk dist at 1.0.13 and again at 1.0.31:
+ * the attachment sniff map is exactly JPEG and PNG; the declared mimeType is
  * discarded), while the LangChain providers accept all four types.
  */
 export interface VisionProfile {

package/src/shared/attachment-zip.ts

@@ -25,8 +25,8 @@
  * "the manifest promised a file extraction cannot find" is unrepresentable.
  * The WRITE of an extracted entry is the caller's: the attachment resolver
  * writes under the session's platform dir (`attachment-resolver.ts`), the
- * one caller since S3 M2b retired the native injector. Moved here from that
- * injector at S3 M1 (Q-S3-14) so the guards have one home.
+ * one caller since #1096 retired the native injector. Moved here from that
+ * injector in the same PR so the guards have one home.
  */
 
 import { createInflateRaw } from "node:zlib";

package/src/shared/cost-guard.ts

@@ -1,8 +1,8 @@
 /**
  * ExecutionConfig.max_cost_usd enforcement as a hard stop on a harness turn.
  *
- * Harness-agnostic: the Cursor activity is today's only caller and the turn
- * runtime takes it over in S2 M3. The rationale below is Cursor's, and it is
+ * Harness-agnostic: the Cursor activity was its only caller until the turn
+ * runtime took it over in #1070. The rationale below is Cursor's, and it is
  * why the module is shaped as a hard stop rather than a middleware.
  *
  * The native harness enforces the cap in middleware (cost-cap.ts): tools are

package/src/shared/exact-apply.ts

@@ -28,7 +28,7 @@
  *
  * SOURCE OF TRUTH — the approved whole-file bytes and target path are read from
  * the gated tool call's `args` (the authoritative proposed content the deny-gate
- * stamped from the hook input; see execute-cursor/message-translator.ts
+ * stamped from the hook input; see execute-cursor/boundary-rows.ts
  * `applyGateInput`). This is the single copy — there is no separate captured
  * `file_changes` mirror — so "what was shown == what is applied" holds by
  * construction. (Phase 5 Slice 4 removed the redundant `ToolCall.file_changes`

package/src/shared/execution-context.ts

@@ -15,8 +15,8 @@
  * `setInterceptorExecutionId`) is whichever turn set it last; this store is
  * what makes concurrent turns not overwrite each other's headers.
  *
- * Moved from `activities/execute-cursor/fetch-interceptor.ts` (S2 M3,
- * Q-M3-12) so `harness/run-turn.ts` can enter it without importing the
+ * Moved from `activities/execute-cursor/fetch-interceptor.ts` (#1070)
+ * so `harness/run-turn.ts` can enter it without importing the
  * adapter; the interceptors import it from here. No harness enters it: the
  * contract lists it among the things deliberately NOT on `TurnSink`.
  */

package/src/shared/extract-structured-output.ts

@@ -3,8 +3,8 @@
  *
  * Harness-agnostic, and called from one place: the turn runtime's epilogue
  * (`harness/run-turn.ts` `extractStructuredOutputFromText`), so both
- * harnesses have it — Cursor since S2 M3, native since S3 M2a (pinned by the
- * native hermetic `structured-output` tier-2 arm since M2b, Q-S3-7).
+ * harnesses have it — Cursor since #1070, native since #1096 (pinned by the
+ * native hermetic `structured-output` tier-2 arm).
  *
  * When tier-1 text extraction (shared/extract-json.ts) cannot find JSON in
  * the agent's free-text response, this tier asks an economy-tier LLM to

package/src/shared/filereview/__tests__/capture.test.ts

@@ -1,8 +1,12 @@
 /**
- * @regression file-hitl-phase0 — pins file-edit HITL fixes #7, #8, #9 (see _projects/2026-06/20260630.01.file-change-hitl-redesign/tasks/T01_3_regression-manifest.md)
+ * @regression file-hitl-phase0 — pins three rules of git capture mode: a
+ * no-commit tree-ref snapshot and restore with one card per changed file;
+ * edits stay applied through the WAITING-to-resume boundary and the resume
+ * reconciles to the pinned refs; a reject is a DISCARD that COMPLETES, snaps
+ * the tree back byte for byte, and partial decisions land only approved files.
  *
  * Tests the harness-agnostic capture orchestration directly, under one
- * harness id (since S3 M4 the runtime is the ONE caller for every harness,
+ * harness id (since #1096 the runtime is the ONE caller for every harness,
  * `harness/capture.ts`; until then each adapter called this seam and the
  * Cursor side had its own test, `execute-cursor/capture-flow.test.ts`, whose
  * three reconcile arms no other file carried moved here). Confirms that the
@@ -235,8 +239,8 @@ describe("capture orchestration — deep-agent harness", () => {
     // artifact mode. `ProxyArtifactStorage.exists()` reports true for ANY key
     // (the presign endpoint mints a URL regardless of object existence), so the
     // old reconcile "found" a CAS manifest that a git-only turn never wrote,
-    // downloaded it, and died on the R2 `NoSuchKey` 404 (see the ExecuteCursor
-    // crash in _cursor/error.md). The reconcile must decide "is this a CAS turn?"
+    // downloaded it, and died on the R2 `NoSuchKey` 404 (the ExecuteCursor
+    // crash `proxy-reconcile.test.ts` reproduces). The reconcile must decide "is this a CAS turn?"
     // from the change set's CANDIDATE snapshot — a git-only turn carries no cas
     // ref — so a lying `exists()` can no longer turn a git reconcile into a
     // doomed download.
@@ -335,7 +339,7 @@ function candidateCompleteness(status: AgentExecutionStatus): DiffCompleteness |
     : undefined;
 }
 
-describe("capture reconcile — the decision rules the resume enforces (moved from execute-cursor/capture-flow.test at S3 M4)", () => {
+describe("capture reconcile — the decision rules the resume enforces (moved from execute-cursor/capture-flow.test in #1096)", () => {
   async function captureTwoFileTurn(status: AgentExecutionStatus): Promise<void> {
     const baseline = await captureBaselineToLedger({ status, gitRoot: repo, executionId: EXEC_ID, changeSetId: CHANGE_SET_ID, harnessId: HARNESS });
     await write("notes.md", "planton notes\n");

package/src/shared/filereview/__tests__/git-substrate.test.ts

@@ -1,5 +1,8 @@
 /**
- * @regression file-hitl-phase0 — pins file-edit HITL fixes #7, #8 (see _projects/2026-06/20260630.01.file-change-hitl-redesign/tasks/T01_3_regression-manifest.md)
+ * @regression file-hitl-phase0 — pins git capture mode: a no-commit tree-ref
+ * snapshot and restore with one card per changed file; edits stay applied
+ * through the WAITING-to-resume boundary and the resume reconciles to the
+ * pinned refs.
  *
  * Unit tests for the git snapshot/restore capture substrate (the PRIMITIVES:
  * snapshot / capture / restore / apply / recompute / drop).

package/src/shared/filereview/__tests__/proxy-reconcile.test.ts

@@ -1,8 +1,8 @@
 /**
  * @regression file-hitl-proxy-reconcile — the file-review reconcile crash in
- * cloud/desktop (proxy) artifact mode (see _cursor/error.md: an ExecuteCursor
- * turn died on `Artifact download failed (HTTP 404) ... NoSuchKey` for a CAS
- * manifest a git-only turn never wrote).
+ * cloud/desktop (proxy) artifact mode: an ExecuteCursor turn died on
+ * `Artifact download failed (HTTP 404) ... NoSuchKey` for a CAS manifest a
+ * git-only turn never wrote.
  *
  * This exercises the REAL {@link ProxyArtifactStorage} end to end against a mock
  * proxy + object store, so the whole stack — presign, the ranged-GET existence

package/src/shared/filereview/cas-touched.ts

@@ -14,9 +14,9 @@
  * capture ({@link buildCasTurnCaptures}), which composes it into the
  * {@link CasPathCapture}s the CAS substrate stores.
  *
- * Until S3 M4 each harness carried its own copy of `buildCasTurnCaptures`
+ * Until #1096 each harness carried its own copy of `buildCasTurnCaptures`
  * beside its observation source; the copies were byte-near-identical
- * (F-M4-P6) and now live here once. The AFTER bytes are always re-read from
+ * and now live here once. The AFTER bytes are always re-read from
  * disk at composition time (the authoritative net result of the turn), so
  * many edits to one path collapse to one before/after.
  */

package/src/shared/heartbeat.ts

@@ -13,7 +13,7 @@
  * heartbeat subject — `@temporalio/activity/lib/index.js`
  * `Context.heartbeat`, `@temporalio/worker/lib/worker.js` the heartbeat
  * callback; the SDK's own doc: "Cancellation is not propagated from this
- * function"). Until S2 M3 this handle carried two flags for a throw that
+ * function"). Until #1070 this handle carried two flags for a throw that
  * cannot happen; a turn reads its interruption from the signal's reason
  * instead (`worker-shutdown.ts` `classifyTurnInterruption`).
  */

package/src/shared/llm-backend.ts

@@ -8,10 +8,6 @@
  * factories run `preflightLlmBackends` at startup, and `model-client.ts`
  * resolves the backend and translates model ids at construction time; see
  * `__tests__/vertex-seam.test.ts` for the pinned seam behavior.
- *
- * Design decision record: stigmer-cloud
- * `_projects/2026-08/20260809.01.multi-cloud-llm-provider-endpoints/`
- * `design-decisions/001-provider-backends.md`.
  */
 
 import type { LlmProvider } from "./llm-proxy.js";

package/src/shared/model-error.ts

@@ -14,8 +14,7 @@
  *    errors from the PLATFORM's provider account told customers to top up
  *    consoles they don't own. The cloud proxy rewrites those to a 503
  *    carrying PLATFORM_CAPACITY_SENTINEL (the contract lives in
- *    stigmer-cloud's PlatformProviderErrorClassifier and the DD at
- *    _projects/2026-08/20260801.02.provider-error-attribution/); this module
+ *    stigmer-cloud's PlatformProviderErrorClassifier); this module
  *    is the runner-side half that recognizes the sentinel and, in direct
  *    (BYO-key) mode, attributes billing errors to the user's own account
  *    with actionable wording.

package/src/shared/persist-decision.ts

@@ -3,10 +3,17 @@
  *
  * Harness-agnostic, and both adapters' stream loops read it
  * (`execute-cursor/turn-stream.ts`, `execute-deep-agent/turn-stream.ts`; the
- * native orchestrator's own copy of the rule retired with it at S3 M2b):
- * `shouldPersist = forceFlush || scheduler.shouldSendUpdate(eventCount)`.
- * Both harnesses thus share one cadence model — discrete state changes flush
- * immediately, high-frequency token deltas ride a bounded time cadence.
+ * native orchestrator's own copy of the rule retired with it in #1096):
+ * `shouldPersist = transcriptDirty || scheduler.shouldSendUpdate(eventCount)`.
+ * Both harnesses thus share one cadence model — a discrete state change
+ * flushes immediately, high-frequency token deltas ride a bounded time
+ * cadence.
+ *
+ * One flag, the transcript builder's `dirty` (since #1097). Until then the
+ * decision took three Cursor-named flags — the delta enricher's, the todo
+ * tracker's and the accumulator's — of which two were constant `false` on
+ * both loops once the one builder folded every discrete change; a shape
+ * that named writers which no longer existed.
  *
  * Extracted as a single pure function so the stream loop and its unit tests
  * exercise the same implementation and cannot drift.
@@ -14,43 +21,27 @@
 
 import type { StreamingUpdateScheduler } from "./streaming-scheduler.js";
 
-/**
- * Force-flush signals — discrete, user-visible state changes that must reach the
- * live stream immediately, independent of the scheduler's time cadence.
- */
-export interface ForceFlushSignals {
-  /** Shell/tool output text accumulated past the delta-enricher debounce. */
-  readonly deltaEnricherDirty: boolean;
-  /** The agent's todo list changed. */
-  readonly todosDirty: boolean;
-  /**
-   * A tool call started or reached a terminal status, or a sub-agent was
-   * delegated/updated (MessageAccumulator.isDirty).
-   */
-  readonly contentDirty: boolean;
-}
-
 /**
  * Decide whether to persist the streaming status after a stream event.
  *
- * - forceFlush: any discrete signal flushes now so the live trace (tool calls,
- *   sub-agents, todos, shell output) is never starved on short turns.
+ * - `transcriptDirty`: a discrete, user-visible change landed on the
+ *   transcript since the last persist (a row started or settled, a sub-agent
+ *   delegated, a todo written, an artifact registered) and must reach the
+ *   live stream now, so short turns are never starved.
  * - scheduler: the shared StreamingUpdateScheduler carries assistant text and
  *   model thinking on a bounded time cadence (500ms floor / 5s keepalive),
  *   avoiding a per-token persist storm.
  *
- * After a persist, the caller must call scheduler.markUpdateSent(eventCount) so
- * the cadence resets — matching the native harness.
+ * After a persist, the caller calls `scheduler.markUpdateSent(eventCount)` so
+ * the cadence resets, and clears the builder's flag as it requests the write.
  *
  * @param nowMs Injectable clock forwarded to the scheduler, for tests.
  */
 export function shouldPersistStreamingStatus(
-  signals: ForceFlushSignals,
+  transcriptDirty: boolean,
   scheduler: StreamingUpdateScheduler,
   eventCount: number,
   nowMs?: number,
 ): boolean {
-  const forceFlush =
-    signals.deltaEnricherDirty || signals.todosDirty || signals.contentDirty;
-  return forceFlush || scheduler.shouldSendUpdate(eventCount, nowMs);
+  return transcriptDirty || scheduler.shouldSendUpdate(eventCount, nowMs);
 }

package/src/shared/prompt-sections.ts

@@ -7,7 +7,7 @@
  * (`sender-identity.ts`, `declared-preferences.ts`, `recalled-memories.ts`,
  * `session-context.ts`, `context-bridge.ts`, `attachment-vision.ts`,
  * `attachment-download-urls.ts`). What the two prompt builders duplicated
- * until S3 M5 (Q-S3-10, Q-M2b-8) was the glue around those bodies: the order
+ * until #1096 was the glue around those bodies: the order
  * the five standing sections read in, with the same doctrine comments written
  * twice; the input-files bullet and disclosure lines; which skills a prompt
  * highlights when there are many. This module is that glue, written once.
@@ -169,10 +169,10 @@ export interface InputFileLines {
 /**
  * The input-files lines over the runtime's own `ResolvedAttachment` — one
  * type, one truth (a structural twin once lived in each builder; native's
- * silently dropped the size, Cursor's was deleted at S3 M5, Q-M5-5).
+ * silently dropped the size, Cursor's was deleted in #1096).
  *
  * Each bullet discloses the size (so the agent can weigh a read — the field's
- * own stated purpose; Cursor's line gained it at S3 M5, Q-M5-3), the original
+ * own stated purpose; Cursor's line gained it in #1096), the original
  * name of a duplicate-renamed file (`attachment-naming.ts`; so the agent can
  * connect "the two report.pdfs" in the user's message to distinct files on
  * disk), and the download URL when one was minted
@@ -224,7 +224,7 @@ export interface SkillSelection {
  * named, so the agent can still activate one on its own judgement (the Agent
  * Skills spec's progressive disclosure: metadata up front, instructions on
  * demand). The native harness calls this on every turn; the Cursor harness
- * lists every skill today and its adoption is S4's (Q-M5-4).
+ * lists every skill today; adopting the selection there is an open item.
  */
 export function selectSkillsForPrompt(userMessage: string, skills: readonly SkillMetadata[]): SkillSelection {
   const filter = filterSkills(

package/src/shared/skill-resolver.ts

@@ -12,9 +12,9 @@
  * the control plane, which only the runtime holds, and writes under the
  * platform dir the runtime owns; the harness renders the returned metadata
  * into its prompt in its own placement. Moved from
- * `activities/execute-cursor/` at S2 M3b; the native harness's twin
- * (`skill-writer.ts` `fetchSkillsByRefs` + `mountSkills`) retired at S3 M2b,
- * and the module itself at S3 M5 — the one renderer it kept is
+ * `activities/execute-cursor/` in #1070; the native harness's twin
+ * (`skill-writer.ts` `fetchSkillsByRefs` + `mountSkills`) retired in #1096,
+ * and the module itself with it — the one renderer it kept is
  * `shared/prompt-sections.ts` `alsoAvailableSkillsNote`. This is the one
  * skills path for every harness.
  *

package/src/shared/status-offload.ts

@@ -20,7 +20,7 @@
  *      Images are uploaded as their decoded bytes (so the UI can render an
  *      <img>); other large output is uploaded as text with a preview head.
  *      Idempotent and content-hash-deduped so the throttled, repeated persists
- *      (and result re-inflation by mergeToolCallEvent) upload each blob once.
+ *      (and result re-inflation by the builder's `tool_finished` upsert) upload each blob once.
  *
  *   2. offloadCandidateChangesToFit — an aggregate, storage-backed step for the
  *      file-review ledger: if the status still exceeds the soft cap after (1),
@@ -344,7 +344,7 @@ async function maybeOffloadToolCall(
   const hash = sha256(result);
 
   // Idempotent: the same content was already offloaded on a prior persist (or
-  // mergeToolCallEvent re-inflated `result` with identical bytes). Re-collapse
+  // the builder's finish upsert re-inflated `result` with identical bytes). Re-collapse
   // the inline copy without re-uploading.
   if (tc.outputRef && tc.outputRef.contentHash === hash) {
     tc.result = collapsedResultFor(tc.outputRef);

package/src/shared/streaming-scheduler.ts

@@ -19,13 +19,8 @@
  * the live stream cadence is identical across harnesses.
  */
 
-export enum UpdateReason {
-  TIME_THRESHOLD = "time_threshold",
-  BURST_PROTECTION = "burst_protection",
-  KEEPALIVE = "keepalive",
-  FIRST_UPDATE = "first_update",
-  NONE = "none",
-}
+/** Why the scheduler last said "send": the cadence rule that fired, or `none`. */
+export type UpdateReason = "time_threshold" | "burst_protection" | "keepalive" | "first_update" | "none";
 
 export interface StreamingConfig {
   /** Minimum time between updates (ms). Rate limit: max ~2 updates/second. */
@@ -95,7 +90,7 @@ export class StreamingUpdateScheduler {
 
   private lastUpdateTime: number;
   private lastUpdateEvents = 0;
-  private lastReason: UpdateReason = UpdateReason.NONE;
+  private lastReason: UpdateReason = "none";
   private firstCheck = true;
 
   /**
@@ -119,26 +114,26 @@ export class StreamingUpdateScheduler {
     const eventsSinceLast = eventsProcessed - this.lastUpdateEvents;
 
     if (this.firstCheck && eventsSinceLast >= 1) {
-      this.lastReason = UpdateReason.FIRST_UPDATE;
+      this.lastReason = "first_update";
       return true;
     }
 
     if (timeSinceLastMs >= this.config.minIntervalMs && eventsSinceLast >= 1) {
-      this.lastReason = UpdateReason.TIME_THRESHOLD;
+      this.lastReason = "time_threshold";
       return true;
     }
 
     if (eventsSinceLast >= this.config.burstThreshold) {
-      this.lastReason = UpdateReason.BURST_PROTECTION;
+      this.lastReason = "burst_protection";
       return true;
     }
 
     if (timeSinceLastMs >= this.config.maxIntervalMs) {
-      this.lastReason = UpdateReason.KEEPALIVE;
+      this.lastReason = "keepalive";
       return true;
     }
 
-    this.lastReason = UpdateReason.NONE;
+    this.lastReason = "none";
     return false;
   }
 

package/src/shared/subagent-rows.ts

@@ -7,9 +7,9 @@
  * infrastructure cancel), so the final snapshot has no permanent IN_PROGRESS
  * "zombie" delegation. Harness-agnostic (a `SubAgentExecution` is the
  * platform's row, not an engine's), read by the turn runtime's terminal
- * table and the Cursor accumulator's own finalize alike.
+ * table and the Cursor settle alike.
  *
- * Moved from `activities/execute-cursor/message-translator.ts` at S2 M3 so
+ * Moved from `activities/execute-cursor/message-translator.ts` in #1070 so
  * the runtime's catch can reach it; the body is unchanged.
  */
 

package/src/shared/todos.ts

@@ -1,12 +1,12 @@
 /**
- * Todo-list projection shared by every harness's status writer.
+ * Todo-list projection the one transcript builder applies for every harness.
  *
  * All harnesses expose an agent to-do tool — the Cursor SDK emits `TodoWrite`
  * (legacy) / `updateTodos` (current), the native deepagents harness emits
  * `write_todos` — and each writes the SAME `AgentExecutionStatus.todos` proto
  * map that the clients (React `TodoCard`, CLI) render. This module is the single
- * place that maps a raw tool payload into that map, so the Cursor `TodoTracker`
- * and the native v2/v3 status builders cannot drift in how they build todos.
+ * place that maps a raw tool payload into that map, so the one transcript builder
+ * (`harness/transcript/builder.ts`, both harnesses since #1097) has one mapping.
  *
  * The mapping is a superset of what any one harness emits: the Cursor SDK sends
  * per-item `id`/`created_at` and can send a `merge` flag and camelCase statuses;

package/src/shared/tool-row.ts

@@ -17,7 +17,7 @@
  * shape of legacy (pre-stamping) sessions whose flowed edit rows were hidden.
  */
 
-import { ToolCallStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { ApprovalAction, ToolCallStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 import type { AgentMessage, ToolCall } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
 import type { SubAgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/subagent_pb";
 import { extractFilePath } from "./file-tools.js";
@@ -80,7 +80,7 @@ export function stampFileEditRow(tc: ToolCall, changeSetId: string): void {
  *    (the Cursor deny-gate's ledger tokens; a status rule). Omit to stamp
  *    every write/delete row, the deep-agent posture where every such row flowed.
  *
- * One pass for every harness (S3 M4; until then each adapter carried a copy
+ * One pass for every harness (since #1096; until then each adapter carried a copy
  * differing only in the `flowed` predicate).
  */
 export function stampFlowedFileEditRows(
@@ -294,3 +294,39 @@ export function collectSettledToolCallIds(
   }
   return ids;
 }
+
+/**
+ * Whether the server has already adjudicated this row — the user decided its
+ * gate (`approval_action`, the server's field; the runner never writes it).
+ *
+ * Such a row belongs to a gate that is CLOSED: approved and executed, or
+ * declined, in an earlier invocation of this execution. No reconciliation of
+ * the CURRENT turn may rewrite it — not the denial overlay (a new denial of the
+ * same identity is a NEW act and gets its own row), not the twin collapse (the
+ * executed row is the transcript's record). Before this rule the overlay matched
+ * a denial to the FIRST same-identity row in the whole transcript, flipped a
+ * completed, approved row back to WAITING_APPROVAL with its APPROVE still on
+ * it, and the next invocation read that as the decision for the new, undecided
+ * proposal — an approval bleeding to a later identical act (found by the
+ * harness contract kit's invariant 3 against this adapter, #1070).
+ */
+export function isAdjudicatedRow(tc: ToolCall): boolean {
+  return tc.approvalAction !== ApprovalAction.UNSPECIFIED;
+}
+
+/** Adjudicated with a decision that does NOT execute: the user declined this gate. */
+export function isDeclinedRow(tc: ToolCall): boolean {
+  switch (tc.approvalAction) {
+    case ApprovalAction.SKIP:
+    case ApprovalAction.REJECT:
+      return true;
+    case ApprovalAction.UNSPECIFIED:
+    case ApprovalAction.APPROVE:
+    case ApprovalAction.APPROVE_ALL:
+      return false;
+    default: {
+      const exhaustive: never = tc.approvalAction;
+      throw new Error(`isDeclinedRow: unknown approval action ${String(exhaustive)}`);
+    }
+  }
+}

package/src/shared/worker-shutdown.ts

@@ -107,7 +107,7 @@ export type TurnInterruption = "worker-shutdown" | "pause" | "infrastructure" |
  * already aborted and nothing actually interrupted. Shutdown requires a
  * delivered cancellation alongside the signal.
  *
- * Until S2 M3 the evidence also carried two flags from the periodic
+ * Until #1070 the evidence also carried two flags from the periodic
  * heartbeat ("it threw `CancelledFailure`"), and a delivered cancellation
  * without them read as "none". `Context.heartbeat()` never throws in the
  * Temporal TypeScript SDK (it enqueues to the worker's heartbeat subject;