@stigmer/runner 3.15.3-dev.20260914121148 → 3.16.0

package/src/shared/__tests__/persist-decision.test.ts

@@ -1,12 +1,13 @@
 /**
  * Unit tests for the streaming persist decision (issue #179), the shared
- * cadence rule the Cursor stream loop calls today and the turn runtime
- * takes over in S2 M3.
+ * cadence rule both adapters' stream loops read.
  *
- * Validates the converged cadence: discrete force-flush signals persist
+ * Validates the converged cadence: a discrete transcript change persists
  * immediately, while high-frequency token deltas ride the shared
  * StreamingUpdateScheduler's time cadence (rather than the old, time-blind
- * `eventCount % 20` gate that starved short turns).
+ * `eventCount % 20` gate that starved short turns). The signal is the one
+ * transcript builder's `dirty` flag (since #1097); until then three
+ * Cursor-named flags, two of them constant `false` on both loops.
  */
 
 import { describe, it, expect } from "vitest";
@@ -22,65 +23,50 @@ const CONFIG: StreamingConfig = {
   burstThreshold: 50,
 };
 
-const NO_FORCE = {
-  deltaEnricherDirty: false,
-  todosDirty: false,
-  contentDirty: false,
-} as const;
-
 describe("shouldPersistStreamingStatus", () => {
   it("persists on the first event via the scheduler (kills the opaque-wait at turn start)", () => {
     const scheduler = new StreamingUpdateScheduler(CONFIG, 0);
-    expect(shouldPersistStreamingStatus(NO_FORCE, scheduler, 1, 0)).toBe(true);
+    expect(shouldPersistStreamingStatus(false, scheduler, 1, 0)).toBe(true);
   });
 
-  it("does not persist a sub-500ms token delta with no force signal", () => {
+  it("does not persist a sub-500ms token delta while the transcript is clean", () => {
     const scheduler = new StreamingUpdateScheduler(CONFIG, 0);
     scheduler.markUpdateSent(1, 0); // first flush already sent
 
     // 100ms later, one more delta event — too soon for the time cadence.
-    expect(shouldPersistStreamingStatus(NO_FORCE, scheduler, 2, 100)).toBe(false);
+    expect(shouldPersistStreamingStatus(false, scheduler, 2, 100)).toBe(false);
   });
 
   it("persists a token delta once the 500ms cadence elapses", () => {
     const scheduler = new StreamingUpdateScheduler(CONFIG, 0);
     scheduler.markUpdateSent(1, 0);
 
-    expect(shouldPersistStreamingStatus(NO_FORCE, scheduler, 2, 500)).toBe(true);
+    expect(shouldPersistStreamingStatus(false, scheduler, 2, 500)).toBe(true);
   });
 
-  it.each([
-    ["contentDirty (tool call / sub-agent)", { ...NO_FORCE, contentDirty: true }],
-    ["todosDirty", { ...NO_FORCE, todosDirty: true }],
-    ["deltaEnricherDirty (shell output)", { ...NO_FORCE, deltaEnricherDirty: true }],
-  ])("force-flushes immediately on %s, bypassing the time cadence", (_label, signals) => {
+  it("flushes immediately when the transcript is dirty, bypassing the time cadence", () => {
     const scheduler = new StreamingUpdateScheduler(CONFIG, 0);
     scheduler.markUpdateSent(1, 0);
 
     // Only 1ms after the last flush: the scheduler alone would say no...
-    expect(shouldPersistStreamingStatus(NO_FORCE, scheduler, 2, 1)).toBe(false);
-    // ...but any discrete force signal flushes now.
-    expect(shouldPersistStreamingStatus(signals, scheduler, 2, 1)).toBe(true);
+    expect(shouldPersistStreamingStatus(false, scheduler, 2, 1)).toBe(false);
+    // ...but a discrete transcript change flushes now.
+    expect(shouldPersistStreamingStatus(true, scheduler, 2, 1)).toBe(true);
   });
 
   // The #179 starvation scenario: a short turn of < 20 events. Under the old
   // `eventCount % 20` gate, a tool call appearing at event 3 (and completing at
   // event 4) would never be persisted until the unconditional final flush. With
-  // the converged decision, the tool lifecycle force-flushes the instant it
-  // happens, regardless of how few events the turn has.
+  // the converged decision, the tool lifecycle flushes the instant it happens,
+  // regardless of how few events the turn has.
   it("surfaces a tool call on a short (<20 event) turn", () => {
     const scheduler = new StreamingUpdateScheduler(CONFIG, 0);
     const flushes: number[] = [];
     let clock = 0;
 
     // Helper mirroring the loop: decide, then mark both clocks on a flush.
-    const tick = (eventCount: number, contentDirty: boolean) => {
-      const persist = shouldPersistStreamingStatus(
-        { ...NO_FORCE, contentDirty },
-        scheduler,
-        eventCount,
-        clock,
-      );
+    const tick = (eventCount: number, transcriptDirty: boolean) => {
+      const persist = shouldPersistStreamingStatus(transcriptDirty, scheduler, eventCount, clock);
       if (persist) {
         flushes.push(eventCount);
         scheduler.markUpdateSent(eventCount, clock);
@@ -90,8 +76,8 @@ describe("shouldPersistStreamingStatus", () => {
 
     tick(1, false); // assistant delta — first-event flush
     tick(2, false); // thinking delta — within 500ms, no flush
-    tick(3, true);  // tool call starts — force-flush
-    tick(4, true);  // tool call completes — force-flush
+    tick(3, true);  // tool call starts — the transcript is dirty, flush
+    tick(4, true);  // tool call completes — dirty again, flush
     tick(5, false); // closing assistant delta — within 500ms, no flush
 
     // The tool lifecycle (events 3 and 4) is observed live; event 1 is the

package/src/shared/__tests__/prompt-sections.test.ts

@@ -2,7 +2,7 @@
  * The shared prompt glue (`shared/prompt-sections.ts`): the standing order,
  * the input-files lines, the skill selection and the also-available sentence
  * (the sentence's arms came from `skill-writer.test.ts`, retired with its
- * module at S3 M5). What each harness renders AROUND these is pinned whole by
+ * module in #1096). What each harness renders AROUND these is pinned whole by
  * the two builders' prompt goldens (`execute-deep-agent/__tests__/
  * prompt-goldens.test.ts`, `execute-cursor/__tests__/prompt-goldens.test.ts`);
  * this file pins the glue's own contract, harness-free.

package/src/shared/__tests__/run-credential.test.ts

@@ -0,0 +1,111 @@
+/**
+ * The run credential's wire reader and its store (`run-credential.ts`,
+ * `run-credential-store.ts`).
+ *
+ * The property that matters is the last arm: two activities whose awaits
+ * interleave in one process each see their own credential and never the
+ * other's. That is what lets one shared `StigmerClient` — one per worker for
+ * the turn activities — present the right run's credential per request.
+ */
+
+import { describe, expect, it } from "vitest";
+
+import {
+  RUN_CREDENTIAL_HEADER,
+  RUN_CREDENTIAL_INPUT_KEY,
+  readRunCredentialFromInput,
+} from "../run-credential.js";
+import {
+  currentRunCredential,
+  withRunCredential,
+} from "../run-credential-store.js";
+
+describe("readRunCredentialFromInput", () => {
+  it("reads a non-empty string under the wire key", () => {
+    expect(
+      readRunCredentialFromInput({ [RUN_CREDENTIAL_INPUT_KEY]: "cred-1" }),
+    ).toBe("cred-1");
+  });
+
+  it("answers undefined for the positional string shape the turn activities also accept", () => {
+    expect(readRunCredentialFromInput("aex_123")).toBeUndefined();
+  });
+
+  it("answers undefined for a credential-less object — an older server's dispatch", () => {
+    expect(
+      readRunCredentialFromInput({ execution_id: "aex_123", thread_id: "" }),
+    ).toBeUndefined();
+  });
+
+  it("answers undefined for an empty string, null, undefined and a non-string value", () => {
+    expect(
+      readRunCredentialFromInput({ [RUN_CREDENTIAL_INPUT_KEY]: "" }),
+    ).toBeUndefined();
+    expect(readRunCredentialFromInput(null)).toBeUndefined();
+    expect(readRunCredentialFromInput(undefined)).toBeUndefined();
+    expect(
+      readRunCredentialFromInput({ [RUN_CREDENTIAL_INPUT_KEY]: 42 }),
+    ).toBeUndefined();
+  });
+
+  it("does not read the connect lane's camelCase per-call token", () => {
+    expect(
+      readRunCredentialFromInput({ executionContextToken: "connect-token" }),
+    ).toBeUndefined();
+  });
+
+  it("pins the wire vocabulary as bytes", () => {
+    expect(RUN_CREDENTIAL_INPUT_KEY).toBe("execution_context_token");
+    expect(RUN_CREDENTIAL_HEADER).toBe("stigmer-run-credential");
+  });
+});
+
+describe("run-credential store", () => {
+  it("is empty outside any activity", () => {
+    expect(currentRunCredential()).toBeUndefined();
+  });
+
+  it("is visible to everything the wrapped function awaits, and gone after", async () => {
+    let inner: string | undefined;
+    await withRunCredential("cred-a", async () => {
+      await Promise.resolve();
+      inner = await (async () => currentRunCredential())();
+    });
+    expect(inner).toBe("cred-a");
+    expect(currentRunCredential()).toBeUndefined();
+  });
+
+  it("is inherited by a promise created inside the scope and settled after it", async () => {
+    let detached: Promise<string | undefined> | undefined;
+    await withRunCredential("cred-b", async () => {
+      detached = new Promise((resolve) =>
+        setTimeout(() => resolve(currentRunCredential()), 5),
+      );
+    });
+    expect(await detached).toBe("cred-b");
+  });
+
+  it("never crosses between two activities whose awaits interleave", async () => {
+    const seen: Array<[string, string | undefined]> = [];
+    const activity = async (name: string, ticks: number) => {
+      for (let i = 0; i < ticks; i++) {
+        await new Promise((resolve) => setTimeout(resolve, 1));
+        seen.push([name, currentRunCredential()]);
+      }
+    };
+    await Promise.all([
+      withRunCredential("cred-1", () => activity("one", 4)),
+      withRunCredential("cred-2", () => activity("two", 4)),
+      activity("none", 4),
+    ]);
+    expect(seen.filter(([name]) => name === "one").map(([, c]) => c)).toEqual(
+      Array(4).fill("cred-1"),
+    );
+    expect(seen.filter(([name]) => name === "two").map(([, c]) => c)).toEqual(
+      Array(4).fill("cred-2"),
+    );
+    expect(seen.filter(([name]) => name === "none").map(([, c]) => c)).toEqual(
+      Array(4).fill(undefined),
+    );
+  });
+});

package/src/shared/__tests__/stamp-flowed-rows.test.ts

@@ -1,7 +1,7 @@
 /**
  * Unit tests for the shared turn-boundary flowed-row stamping
  * (`shared/tool-row.ts` `stampFlowedFileEditRows` /
- * `stampFlowedSubAgentFileEditRows`; the deep-agent's copy until S3 M4), with
+ * `stampFlowedSubAgentFileEditRows`; the deep-agent's copy until #1096), with
  * emphasis on the sub-agent path added by the DD-24 follow-up: sub-agent edit
  * rows fold into the parent turn's change set, so they carry the parent change
  * set id, scoped to this turn by tool-call-id novelty (they lack the

package/src/shared/__tests__/status-offload.test.ts

@@ -342,7 +342,7 @@ describe("offloadOversizedToolOutputs", () => {
     await offloadOversizedToolOutputs(status, ctx);
     expect(uploads).toHaveLength(1);
 
-    // Simulate mergeToolCallEvent re-inflating the inline result with the SAME
+    // Simulate the builder's finish upsert re-inflating the inline result with the SAME
     // bytes on a subsequent persist; the ref's content hash still matches.
     status.messages[0].toolCalls[0].result = result;
     await offloadOversizedToolOutputs(status, ctx);

package/src/shared/__tests__/streaming-scheduler.test.ts

@@ -1,7 +1,6 @@
 import { describe, it, expect, vi, afterEach } from "vitest";
 import {
   StreamingUpdateScheduler,
-  UpdateReason,
   loadStreamingConfig,
   type StreamingConfig,
 } from "../streaming-scheduler.js";
@@ -17,7 +16,7 @@ describe("StreamingUpdateScheduler", () => {
     it("always sends on first event", () => {
       const s = new StreamingUpdateScheduler(BASE_CONFIG, 0);
       expect(s.shouldSendUpdate(1, 0)).toBe(true);
-      expect(s.updateReason).toBe(UpdateReason.FIRST_UPDATE);
+      expect(s.updateReason).toBe("first_update");
     });
 
     it("does not send if zero events processed", () => {
@@ -32,7 +31,7 @@ describe("StreamingUpdateScheduler", () => {
       s.markUpdateSent(0, 0);
 
       expect(s.shouldSendUpdate(1, 500)).toBe(true);
-      expect(s.updateReason).toBe(UpdateReason.TIME_THRESHOLD);
+      expect(s.updateReason).toBe("time_threshold");
     });
 
     it("does not send before minInterval", () => {
@@ -40,7 +39,7 @@ describe("StreamingUpdateScheduler", () => {
       s.markUpdateSent(0, 0);
 
       expect(s.shouldSendUpdate(1, 499)).toBe(false);
-      expect(s.updateReason).toBe(UpdateReason.NONE);
+      expect(s.updateReason).toBe("none");
     });
 
     it("does not send after minInterval with zero new events", () => {
@@ -57,7 +56,7 @@ describe("StreamingUpdateScheduler", () => {
       s.markUpdateSent(0, 0);
 
       expect(s.shouldSendUpdate(50, 100)).toBe(true);
-      expect(s.updateReason).toBe(UpdateReason.BURST_PROTECTION);
+      expect(s.updateReason).toBe("burst_protection");
     });
 
     it("does not send at threshold - 1", () => {
@@ -74,7 +73,7 @@ describe("StreamingUpdateScheduler", () => {
       s.markUpdateSent(10, 0);
 
       expect(s.shouldSendUpdate(10, 5000)).toBe(true);
-      expect(s.updateReason).toBe(UpdateReason.KEEPALIVE);
+      expect(s.updateReason).toBe("keepalive");
     });
 
     it("does not send keepalive before maxInterval", () => {
@@ -91,7 +90,7 @@ describe("StreamingUpdateScheduler", () => {
       s.markUpdateSent(10, 1000);
 
       expect(s.shouldSendUpdate(11, 1500)).toBe(true);
-      expect(s.updateReason).toBe(UpdateReason.TIME_THRESHOLD);
+      expect(s.updateReason).toBe("time_threshold");
 
       s.markUpdateSent(11, 1500);
 
@@ -125,7 +124,7 @@ describe("StreamingUpdateScheduler", () => {
       const s = new StreamingUpdateScheduler(BASE_CONFIG, 0);
       // First check with event and enough time — should be FIRST_UPDATE, not TIME_THRESHOLD
       expect(s.shouldSendUpdate(1, 600)).toBe(true);
-      expect(s.updateReason).toBe(UpdateReason.FIRST_UPDATE);
+      expect(s.updateReason).toBe("first_update");
     });
 
     it("time_threshold takes priority over burst_protection", () => {
@@ -134,7 +133,7 @@ describe("StreamingUpdateScheduler", () => {
 
       // Both time and burst conditions met — time wins
       expect(s.shouldSendUpdate(50, 500)).toBe(true);
-      expect(s.updateReason).toBe(UpdateReason.TIME_THRESHOLD);
+      expect(s.updateReason).toBe("time_threshold");
     });
   });
 });

package/src/shared/__tests__/todos.test.ts

@@ -1,6 +1,6 @@
 /**
  * Unit tests for applyTodoUpdate — the harness-agnostic to-do map projection
- * shared by the Cursor TodoTracker and the native v2/v3 status builders.
+ * the one transcript builder projects a todo write through, for both harnesses.
  *
  * These pin the exact mapping contract (status coercion, id synthesis,
  * created_at preservation, merge vs. full-replace, clear-on-empty, defensive

package/src/shared/__tests__/tool-row.test.ts

@@ -382,7 +382,7 @@ describe("collectSettledToolCallIds", () => {
     // scoping them as this-turn would mis-attribute a dead call to the
     // resuming turn's change set. (The Cursor monotonic guard makes the
     // opposite call for the same status so a replayed event can still advance
-    // the row; see isTerminalToolStatus in message-translator.ts.)
+    // the row; see isSettled in harness/transcript/builder.ts.)
     const ids = collectSettledToolCallIds([
       msgWith("tc-interrupted", ToolCallStatus.TOOL_CALL_INTERRUPTED),
     ]);

package/src/shared/activity-input.ts

@@ -15,6 +15,9 @@
  * then the control planes; once both are everywhere, drop the positional branch
  * (and the `string` arms below).
  */
+
+import type { RUN_CREDENTIAL_INPUT_KEY } from "./run-credential.js";
+
 export interface ExecuteActivityInput {
   readonly execution_id: string;
   readonly thread_id: string;
@@ -27,8 +30,26 @@ export interface ExecuteActivityInput {
    * from it. Absent on the legacy positional wire shape (defaults to 0).
    */
   readonly turn_seq?: number;
+  /**
+   * The run credential the server minted for this execution at dispatch,
+   * handed on from the workflow input; absent when the dispatch carried none
+   * (an older server; the cloud). Not normalized here and never read by an
+   * activity: the activity boundary enters it into the run-credential store
+   * before the activity runs (`interceptors/run-credential-activity.ts`), and
+   * the control-plane client presents it per request (`run-credential.ts`).
+   */
+  readonly execution_context_token?: string;
 }
 
+/**
+ * Compile-time fence: the key the boundary reads
+ * (`RUN_CREDENTIAL_INPUT_KEY`) is a key of this input. The type keeps the
+ * literal so the wire shape stays readable; this line fails to type-check the
+ * day the two disagree.
+ */
+type _RunCredentialKeyIsOnTheWire =
+  ExecuteActivityInput[typeof RUN_CREDENTIAL_INPUT_KEY];
+
 export interface NormalizedActivityInput {
   readonly executionId: string;
   readonly threadId: string;

package/src/shared/approval-policy.ts

@@ -466,3 +466,98 @@ export function resolveApprovalMessage(
       return JSON.stringify(value);
     });
 }
+
+// ── The gate's decision ─────────────────────────────────────────────
+
+/**
+ * THE approval-message template per mutating built-in category — the one
+ * table both harnesses word their approval cards from (since #1097).
+ * Keyed by category (not raw tool name) so every alias of a mutation renders
+ * one message; placeholders resolve against the stream arg shape
+ * (`path`/`command`; `resolveApprovalMessage`). The native gate decides with
+ * it (`resolveToolApproval`), the Cursor translator words its `gate` from it
+ * (`execute-cursor/approval-policy.ts` `getBuiltInApprovalMessage`), and the
+ * Cursor boundary resolves a denied call's message through the same path.
+ *
+ * Until then the Cursor harness carried a table of its own and the two differed
+ * by a word — `shell` read "Run command" there and "Execute command" here.
+ * Unified on the plainer word: a user reads "Run command" and knows
+ * what is being asked. Known and deliberately left (#1112):
+ * `write` resolves `{{args.path}}`, while deepagents' file tools send
+ * `file_path`, so a gated native write reads "Write file: <unknown>".
+ */
+export const CATEGORY_APPROVAL_MESSAGE: Record<ToolApprovalCategory, string> = {
+  write: "Write file: {{args.path}}",
+  delete: "Delete: {{args.path}}",
+  shell: "Run command: {{args.command}}",
+};
+
+/** What the gate decides for one call: whether it waits, the message the card shows, and which layer said so. */
+export interface ApprovalRequirement {
+  readonly requiresApproval: boolean;
+  readonly message: string;
+  /** Which policy layer determined this verdict — stamped on the shadow receipt. */
+  readonly source: PolicySource;
+}
+
+/**
+ * THE approval decision for one tool call — the same function the native gate
+ * (`middleware/approval-gate.ts`) interrupts on and the native translator
+ * reports as `tool_started.gate`, so the row can never disagree with the gate
+ * about whether a call waits (since #1097; until then the transcript
+ * builder carried its own weaker copy that gated MCP tools only). Its
+ * read-side twin is {@link resolveApprovalProvenance}, which answers "which
+ * layer governs this call" for EVERY call, gated or not.
+ *
+ * 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). A server-scoped lease surfaces as an absent entry too: the leased
+ * server's tools are dropped from `policies` upstream (`mergeApprovalPolicies`),
+ * so a lease-cleared MCP tool takes the same auto-approve path (its 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).
+ *
+ * Built-in/platform tools: gate exactly the mutating categories through the
+ * shared classifier — fail-CLOSED for the mutating set (write/edit/delete/shell
+ * require approval), fail-open for read-only and unclassified built-ins. A
+ * run-lifetime category lease (the user chose "approve all <category>" earlier
+ * in this run) auto-approves every built-in of that category for the rest of
+ * the run — the scoped successor to auto-approve-all.
+ */
+export function resolveToolApproval(
+  toolName: string,
+  serverSlug: string,
+  args: Record<string, unknown>,
+  policies: ReadonlyMap<string, MergedToolPolicy>,
+  leasedCategories: ReadonlySet<ToolApprovalCategory>,
+): ApprovalRequirement {
+  if (serverSlug) {
+    const key = `${serverSlug}/${toolName}`;
+    const policy = policies.get(key);
+    if (policy) {
+      return {
+        requiresApproval: policy.requiresApproval,
+        message: resolveApprovalMessage(policy.approvalMessage, toolName, args),
+        source: policy.source,
+      };
+    }
+    return { requiresApproval: false, message: "", source: "classifier_default" };
+  }
+
+  const category = toolApprovalCategory(toolName);
+  if (category) {
+    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" };
+}

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-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";