@stigmer/runner 3.0.9-dev.20260615153829 → 3.1.0

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

@@ -11,7 +11,7 @@ import { fileURLToPath } from "node:url";
 import { dirname, resolve } from "node:path";
 import { describe, it, expect } from "vitest";
 import { ToolKind } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
-import { classifyTool } from "../tool-kind.js";
+import { classifyTool, toolApprovalCategory } from "../tool-kind.js";
 
 const here = dirname(fileURLToPath(import.meta.url));
 // runner/src/shared/__tests__ -> repo root is five levels up.
@@ -56,3 +56,26 @@ describe("classifyTool", () => {
     expect(classifyTool("read", "planton")).toBe(ToolKind.FILE_READ);
   });
 });
+
+describe("toolApprovalCategory", () => {
+  it("collapses write AND edit (both taxonomies) onto 'write'", () => {
+    for (const name of ["write", "write_file", "Write", "edit", "edit_file", "StrReplace", "EditNotebook"]) {
+      expect(toolApprovalCategory(name)).toBe("write");
+    }
+  });
+
+  it("maps the delete and shell aliases to their category", () => {
+    for (const name of ["delete", "delete_file", "remove_file", "Delete"]) {
+      expect(toolApprovalCategory(name)).toBe("delete");
+    }
+    for (const name of ["shell", "bash", "execute", "execute_command", "run_command", "terminal", "Shell"]) {
+      expect(toolApprovalCategory(name)).toBe("shell");
+    }
+  });
+
+  it("returns undefined for read-only and unknown built-ins (not gated by category)", () => {
+    for (const name of ["read", "ls", "glob", "grep", "search", "think", "totally_unknown"]) {
+      expect(toolApprovalCategory(name)).toBeUndefined();
+    }
+  });
+});

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

@@ -0,0 +1,221 @@
+/**
+ * Unit tests for the shared tool-row file-review presentation helpers:
+ * `stampFileEditRow` (the observational-row stamp both harnesses apply to
+ * flowed file edits) and `hideToolCallRow`/`isToolCallRowHidden` (the collapse
+ * shape kept for denial twins and legacy pre-stamping sessions).
+ */
+
+import { describe, it, expect } from "vitest";
+import { create } from "@bufbuild/protobuf";
+import { AgentMessageSchema, ToolCallSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import { SubAgentExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/subagent_pb";
+import { ToolCallStatus } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+import { collectSubAgentToolCallIds, hideToolCallRow, isToolCallRowHidden, stampFileEditRow } from "../tool-row.js";
+
+describe("stampFileEditRow", () => {
+  it("stamps additively: content, status, and identity all survive", () => {
+    const tc = create(ToolCallSchema, {
+      id: "tc-1",
+      name: "edit",
+      status: ToolCallStatus.TOOL_CALL_COMPLETED,
+      result: '{"status":"completed","value":{"diffString":"+hi","linesAdded":1}}',
+      argsPreview: '{"path":"src/app.ts"}',
+      args: { path: "src/app.ts", old_string: "a", new_string: "b" },
+    });
+
+    stampFileEditRow(tc, "exec-1:0");
+
+    expect(tc.fileChangeSetId).toBe("exec-1:0");
+    // The row is an observational record: everything the streamed card rendered
+    // from stays in place (the diff renders from result/args, never argsPreview).
+    expect(tc.status).toBe(ToolCallStatus.TOOL_CALL_COMPLETED);
+    expect(tc.args).toEqual({ path: "src/app.ts", old_string: "a", new_string: "b" });
+    expect(tc.result).toContain("diffString");
+    expect(tc.argsPreview).toBe('{"path":"src/app.ts"}');
+  });
+
+  it("never overwrites an existing stamp (the cross-turn mis-attribution guard)", () => {
+    // A resume seeds prior turns' rows into the transcript; the turn-boundary
+    // pass re-walks all of them. The stamp must be first-writer-wins or turn N
+    // would claim turn N-1's rows.
+    const tc = create(ToolCallSchema, {
+      id: "tc-old",
+      name: "write",
+      status: ToolCallStatus.TOOL_CALL_COMPLETED,
+      args: { path: "notes.md", content: "x" },
+      fileChangeSetId: "exec-1:0",
+    });
+
+    stampFileEditRow(tc, "exec-1:1");
+
+    expect(tc.fileChangeSetId).toBe("exec-1:0");
+  });
+
+  it("withholds content for a secret-like TRACKED path but keeps the path visible (DD-12 D4)", () => {
+    // The hook denies secret-like gitignored writes before they flow, but a
+    // committed credentials file is outside its scope — the stamp is the last
+    // line of defense against persisting its bytes in the transcript.
+    const tc = create(ToolCallSchema, {
+      id: "tc-secret",
+      name: "write",
+      status: ToolCallStatus.TOOL_CALL_COMPLETED,
+      result: "wrote credentials.json",
+      argsPreview: '{"path":"config/credentials.json"}',
+      args: { path: "config/credentials.json", content: "TOKEN=super-secret" },
+    });
+
+    stampFileEditRow(tc, "exec-1:0");
+
+    expect(tc.fileChangeSetId).toBe("exec-1:0");
+    expect(tc.args).toEqual({ path: "config/credentials.json" }); // path only, no body
+    expect(tc.result).toBe("");
+    expect(tc.argsPreview).toBe("");
+    expect(tc.status).toBe(ToolCallStatus.TOOL_CALL_COMPLETED); // still visible
+  });
+
+  it("fail-closes when the path cannot be determined: content withheld", () => {
+    const tc = create(ToolCallSchema, {
+      id: "tc-weird",
+      name: "write",
+      status: ToolCallStatus.TOOL_CALL_COMPLETED,
+      result: "ok",
+      args: { unrecognized_shape: "payload" },
+    });
+
+    stampFileEditRow(tc, "exec-1:0");
+
+    expect(tc.fileChangeSetId).toBe("exec-1:0");
+    expect(tc.args).toBeUndefined();
+    expect(tc.result).toBe("");
+  });
+});
+
+describe("hideToolCallRow", () => {
+  it("collapses a completed file-edit row to the hidden shape", () => {
+    const tc = create(ToolCallSchema, {
+      id: "tc-1",
+      name: "write",
+      status: ToolCallStatus.TOOL_CALL_COMPLETED,
+      result: "wrote file",
+      argsPreview: "path=src/app.ts",
+      args: { file_path: "src/app.ts", content: "console.log('hi')" },
+      requiresApproval: true,
+      approvalMessage: "Write file",
+    });
+
+    hideToolCallRow(tc);
+
+    expect(tc.status).toBe(ToolCallStatus.TOOL_CALL_SKIPPED);
+    expect(tc.requiresApproval).toBe(false);
+    expect(tc.result).toBe("");
+    expect(tc.error).toBe("");
+    expect(tc.argsPreview).toBe("");
+    expect(tc.approvalMessage).toBe("");
+    expect(tc.completedAt).not.toBe("");
+    // Identity is preserved (append-only): id + name survive the collapse.
+    expect(tc.id).toBe("tc-1");
+    expect(tc.name).toBe("write");
+  });
+
+  it("scrubs args so a hidden row carries no content (design doc 12, D4)", () => {
+    // A file-mutating tool's args hold the full write body. For a secret-like
+    // path this content would otherwise persist into the transcript / Temporal
+    // history, defeating the never-persist-secret-contents contract. The hidden
+    // row is redundant with the file_change_set, so args must be dropped.
+    const tc = create(ToolCallSchema, {
+      id: "tc-secret",
+      name: "write",
+      status: ToolCallStatus.TOOL_CALL_COMPLETED,
+      args: { file_path: ".env", content: "API_KEY=super-secret-value" },
+    });
+
+    hideToolCallRow(tc);
+
+    expect(tc.args).toBeUndefined();
+    expect(isToolCallRowHidden(tc)).toBe(true);
+  });
+
+  it("is idempotent", () => {
+    const tc = create(ToolCallSchema, {
+      id: "tc-1",
+      name: "edit",
+      status: ToolCallStatus.TOOL_CALL_COMPLETED,
+      result: "ok",
+    });
+    hideToolCallRow(tc);
+    const firstCompletedAt = tc.completedAt;
+    hideToolCallRow(tc);
+    expect(isToolCallRowHidden(tc)).toBe(true);
+    expect(tc.completedAt).toBe(firstCompletedAt); // not overwritten
+  });
+});
+
+describe("isToolCallRowHidden", () => {
+  it("recognizes a hidden row", () => {
+    const tc = create(ToolCallSchema, { id: "x", name: "write", status: ToolCallStatus.TOOL_CALL_COMPLETED, result: "y" });
+    expect(isToolCallRowHidden(tc)).toBe(false);
+    hideToolCallRow(tc);
+    expect(isToolCallRowHidden(tc)).toBe(true);
+  });
+
+  it("does not treat a live WAITING_APPROVAL row as hidden", () => {
+    const tc = create(ToolCallSchema, {
+      id: "x",
+      name: "shell",
+      status: ToolCallStatus.TOOL_CALL_WAITING_APPROVAL,
+      requiresApproval: true,
+    });
+    expect(isToolCallRowHidden(tc)).toBe(false);
+  });
+
+  it("does not treat a SKIPPED row with lingering args as hidden", () => {
+    // A row collapsed by an older code path may still carry args; the predicate
+    // must report it as not-yet-hidden so it gets re-scrubbed rather than skipped.
+    const tc = create(ToolCallSchema, {
+      id: "x",
+      name: "write",
+      status: ToolCallStatus.TOOL_CALL_SKIPPED,
+      args: { file_path: ".env", content: "leftover" },
+    });
+    expect(isToolCallRowHidden(tc)).toBe(false);
+  });
+});
+
+describe("collectSubAgentToolCallIds", () => {
+  function subAgent(id: string, ...toolCallIds: string[]) {
+    return create(SubAgentExecutionSchema, {
+      id,
+      messages: [
+        create(AgentMessageSchema, {
+          type: 1, // MESSAGE_AI
+          toolCalls: toolCallIds.map((tcId) =>
+            create(ToolCallSchema, { id: tcId, name: "edit" }),
+          ),
+        }),
+      ],
+    });
+  }
+
+  it("returns an empty set for no sub-agents", () => {
+    expect(collectSubAgentToolCallIds([]).size).toBe(0);
+  });
+
+  it("flattens tool-call ids across sub-agents and messages", () => {
+    const ids = collectSubAgentToolCallIds([
+      subAgent("sa-1", "tc-a", "tc-b"),
+      subAgent("sa-2", "tc-c"),
+    ]);
+    expect([...ids].sort()).toEqual(["tc-a", "tc-b", "tc-c"]);
+  });
+
+  it("collects ids across multiple messages of one sub-agent", () => {
+    const sa = create(SubAgentExecutionSchema, {
+      id: "sa-1",
+      messages: [
+        create(AgentMessageSchema, { type: 1, toolCalls: [create(ToolCallSchema, { id: "tc-a", name: "edit" })] }),
+        create(AgentMessageSchema, { type: 1, toolCalls: [create(ToolCallSchema, { id: "tc-b", name: "write" })] }),
+      ],
+    });
+    expect([...collectSubAgentToolCallIds([sa]).values()].sort()).toEqual(["tc-a", "tc-b"]);
+  });
+});

package/src/shared/activity-input.ts

@@ -0,0 +1,57 @@
+/**
+ * Typed Temporal activity input shared by ExecuteCursor and ExecuteDeepAgent.
+ *
+ * The Go and Java control planes now invoke these activities with a single
+ * object carrying snake_case keys (mirroring the polyglot workflow-input
+ * convention) instead of positional string args. This ends the prior drift
+ * where Go sent (executionId, threadId) and Java sent
+ * (executionId, threadId, invokerIdentityAccountId) while this single runner
+ * read only the first two positionally.
+ *
+ * TRANSITIONAL DUAL-SHAPE: the activity is MaximumAttempts=1 (a failed activity
+ * fails the execution with no retry), and the control plane and this runner
+ * deploy separately. To make the rollout order-independent, the runner accepts
+ * BOTH the new object and the legacy positional args. Deploy the runner first,
+ * then the control planes; once both are everywhere, drop the positional branch
+ * (and the `string` arms below).
+ */
+export interface ExecuteActivityInput {
+  readonly execution_id: string;
+  readonly thread_id: string;
+  /** Carried for cross-edition parity; the runner hydrates the invoker from the DB. */
+  readonly invoker_identity_account_id?: string;
+  /**
+   * Monotonic HITL-cycle index within this execution: 0 on the first invocation,
+   * then the workflow's approvalCycle on each reinvocation. The Cursor producer
+   * mints its deterministic file-review change-set id ({@code executionId:turnSeq})
+   * from it. Absent on the legacy positional wire shape (defaults to 0).
+   */
+  readonly turn_seq?: number;
+}
+
+export interface NormalizedActivityInput {
+  readonly executionId: string;
+  readonly threadId: string;
+  /** HITL-cycle index for this invocation; 0 on the first turn / legacy wire shape. */
+  readonly turnSeq: number;
+}
+
+/**
+ * Normalizes either the new typed object or the legacy positional args into the
+ * `{ executionId, threadId, turnSeq }` the inner activity path consumes.
+ * `thread_id` is empty on a first invocation (new harness state) and `turn_seq`
+ * defaults to 0 (first turn, or the legacy positional shape that never carried it).
+ */
+export function normalizeActivityInput(
+  arg0: ExecuteActivityInput | string | undefined,
+  arg1?: string,
+): NormalizedActivityInput {
+  if (arg0 !== null && typeof arg0 === "object") {
+    return {
+      executionId: arg0.execution_id ?? "",
+      threadId: arg0.thread_id ?? "",
+      turnSeq: arg0.turn_seq ?? 0,
+    };
+  }
+  return { executionId: arg0 ?? "", threadId: arg1 ?? "", turnSeq: 0 };
+}

package/src/shared/approval-canonicalize.ts

@@ -0,0 +1,159 @@
+// Deterministic canonicalization of a tool action into a byte-stable form.
+// Domain: HITL approval. This is the cross-language contract the approval
+// fingerprint (Phase 2) will hash; Phase 1 *defines and computes* it without
+// hashing, so Go/Java/TS can be pinned to byte-identical output via the shared
+// vector corpus (apis/testdata/hitl/canonicalization/).
+//
+// Why this exists: the March 2026 dedup bug was caused by hashing divergent
+// representations of the same action (display args in one place, raw args in
+// another). The fix is a single, explicit normalization pass — applied at ONE
+// layer — that erases incidental differences (path separators, workspace
+// location, shell whitespace, MCP slug case, secret values) before any hash.
+
+import { createHash } from "node:crypto";
+import { posix } from "node:path";
+
+export interface ToolActionInput {
+  // Engine tool name (Cursor PascalCase or native snake_case). Identity is kept
+  // as-given (only trimmed) because ToolKind already normalizes cross-harness
+  // naming elsewhere; canonicalization must not silently merge distinct tools.
+  toolName: string;
+  // MCP server slug, or empty/undefined for built-in tools.
+  mcpServerSlug?: string;
+  // File paths the action targets (absolute or workspace-relative).
+  paths?: string[];
+  // Shell command line, when this is a shell action.
+  shellCommand?: string;
+  // Remaining structured arguments.
+  args?: Record<string, unknown>;
+  // Top-level keys within `args` whose values are secrets: replaced by a stable
+  // digest so the canonical form never carries cleartext.
+  secretKeys?: string[];
+  // Workspace root used to rewrite absolute paths to workspace-relative ones, so
+  // the same edit canonicalizes identically regardless of checkout location.
+  workspaceRoot?: string;
+}
+
+// The normalized action. Field order here is irrelevant — canonicalJson sorts
+// keys — but the shape is the contract Go/Java must reproduce.
+export interface CanonicalToolAction {
+  toolName: string;
+  mcpServerSlug: string;
+  paths: string[];
+  shellCommand: string;
+  args: Record<string, unknown>;
+}
+
+export function canonicalizeToolAction(input: ToolActionInput): CanonicalToolAction {
+  return {
+    toolName: input.toolName.trim(),
+    // Slugs are case-insensitive identity; lowercase so "GitHub" == "github".
+    mcpServerSlug: (input.mcpServerSlug ?? "").trim().toLowerCase(),
+    paths: normalizePaths(input.paths ?? [], input.workspaceRoot),
+    shellCommand: normalizeShellCommand(input.shellCommand ?? ""),
+    args: redactSecrets(input.args ?? {}, new Set(input.secretKeys ?? [])),
+  };
+}
+
+// canonicalToolActionJson is the single entry point: normalize, then serialize
+// to canonical JSON. The returned string is the byte-stable contract value.
+export function canonicalToolActionJson(input: ToolActionInput): string {
+  return canonicalJson(canonicalizeToolAction(input));
+}
+
+// canonicalJson serializes a value to RFC 8785-style canonical JSON: object keys
+// sorted by UTF-16 code unit, no insignificant whitespace, UTF-8 output.
+//
+// The input domain is deliberately constrained to strings, booleans, null,
+// integers, arrays, and plain objects — the shape of a normalized tool action.
+// Non-integer numbers are rejected rather than implementing RFC 8785's full
+// number-formatting algorithm, keeping this hand-rolled serializer small and
+// provably cross-language without a third-party dependency. Revisit if the
+// canonical domain ever needs floats.
+export function canonicalJson(value: unknown): string {
+  return serialize(value);
+}
+
+function serialize(v: unknown): string {
+  if (v === null) return "null";
+  switch (typeof v) {
+    case "boolean":
+      return v ? "true" : "false";
+    case "number":
+      if (!Number.isFinite(v)) throw new Error("canonicalJson: non-finite number");
+      if (!Number.isInteger(v)) {
+        throw new Error("canonicalJson: non-integer numbers are not part of the canonical contract");
+      }
+      return String(v);
+    case "string":
+      // JSON.stringify produces the same minimal escaping and raw UTF-8 for
+      // non-ASCII that RFC 8785 mandates for these inputs.
+      return JSON.stringify(v);
+    case "object":
+      if (Array.isArray(v)) return "[" + v.map(serialize).join(",") + "]";
+      return serializeObject(v as Record<string, unknown>);
+    default:
+      throw new Error(`canonicalJson: unsupported type ${typeof v}`);
+  }
+}
+
+function serializeObject(obj: Record<string, unknown>): string {
+  // `undefined`-valued keys are dropped (they have no JSON representation);
+  // remaining keys are sorted by UTF-16 code unit, which is JS's default string
+  // ordering and matches RFC 8785.
+  const keys = Object.keys(obj)
+    .filter((k) => obj[k] !== undefined)
+    .sort(compareUtf16);
+  const parts = keys.map((k) => JSON.stringify(k) + ":" + serialize(obj[k]));
+  return "{" + parts.join(",") + "}";
+}
+
+function compareUtf16(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+function normalizePaths(paths: string[], workspaceRoot?: string): string[] {
+  return paths.map((p) => normalizeOnePath(p, workspaceRoot)).sort(compareUtf16);
+}
+
+function normalizeOnePath(p: string, workspaceRoot?: string): string {
+  // Separator-normalize to forward slashes first so Windows and POSIX agree.
+  let s = p.replace(/\\/g, "/");
+  if (workspaceRoot) {
+    const root = workspaceRoot.replace(/\\/g, "/");
+    if (s === root) {
+      s = "";
+    } else if (s.startsWith(root + "/")) {
+      s = s.slice(root.length + 1);
+    }
+  }
+  // Collapse `.`/`..` segments deterministically. posix.normalize("") -> ".".
+  return s === "" ? "" : posix.normalize(s);
+}
+
+function normalizeShellCommand(cmd: string): string {
+  // Collapse runs of whitespace to a single space and trim. The argument VALUE
+  // (the command) is what matters; incidental spacing is not identity.
+  return cmd.replace(/\s+/g, " ").trim();
+}
+
+function redactSecrets(
+  args: Record<string, unknown>,
+  secretKeys: Set<string>,
+): Record<string, unknown> {
+  if (secretKeys.size === 0) return args;
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(args)) {
+    out[k] = secretKeys.has(k) ? redactValue(v) : v;
+  }
+  return out;
+}
+
+function redactValue(v: unknown): string {
+  // Redact-but-stable: a SHA-256 digest keeps the canonical form stable across
+  // runs without ever placing the secret in cleartext. This is NOT the approval
+  // fingerprint — that is an HMAC keyed on a Stigmer secret, introduced in
+  // Phase 2. This digest is unkeyed redaction only.
+  const material = typeof v === "string" ? v : canonicalJson(v);
+  return "sha256:" + createHash("sha256").update(material, "utf8").digest("hex");
+}

package/src/shared/approval-fingerprint.ts

@@ -0,0 +1,148 @@
+/**
+ * Approval fingerprint — the exact-match enforcement identity for the HITL Tool
+ * Execution Gateway (Phase 2).
+ *
+ * A fingerprint is `HMAC-SHA256(key, canonicalForm)` over a canonicalized tool
+ * action (see {@link file://./approval-canonicalize.ts}). It answers exactly one
+ * question at the moment of side effect: "is *this* action the one the user
+ * approved?" An approval is bound to the canonical identity of the action, not to
+ * the transient id of the proposing tool call, so a re-driven action that differs
+ * from what was approved is re-asked — never silently executed.
+ *
+ * Why HMAC and not a bare SHA-256 (binding canonical decision,
+ * design-decisions/approval-fingerprint-vs-march-rollback.md, Rule 4): the
+ * fingerprint is an authorization token, not a correlation key. Keying it under a
+ * Stigmer-held secret means a model (or a compromised workspace) cannot forge a
+ * value that the gateway will accept. In Phase 2 the fingerprint is
+ * recompute-and-compare at one trusted layer (no bearer token crosses a wire), so
+ * the anti-forgery property is forward-looking — it earns its keep when a lease
+ * later becomes a server-issued bearer token (Phase 7). We pay the small cost now
+ * to avoid a migration that re-keys every persisted approval later.
+ *
+ * Two fidelities share this one canonicalization core, because the two
+ * enforcement substrates differ (see the Phase-2 plan, "two enforcement
+ * substrates, not one"):
+ *
+ *  - FULL ({@link computeApprovalFingerprint}) — HMAC over the full canonical
+ *    action (tool + paths + shellCommand + args). Used by the in-process
+ *    deep-agent gateway, where approve-time and execute-time observe the same
+ *    arg shape (LangGraph checkpoint replay), so the action can be matched at
+ *    full fidelity.
+ *  - COARSE ({@link computeCoarseApprovalFingerprint}) — HMAC over
+ *    (category, salient) only. Used by the out-of-process Cursor deny-oracle
+ *    hook, whose stdin payload names the same action with a different taxonomy
+ *    (`Write` vs `edit`, `file_path` vs `path`) and cannot reproduce the full
+ *    args. The coarse projection is the documented, substrate-forced coarsening
+ *    that lets the hook-side and stream-side fingerprints agree; it is the
+ *    successor identity for execute-cursor's grant token.
+ *
+ * The fingerprint is enforcement-only and never a correlation key — correlation
+ * stays `approval_request_id` + `tool_call_id`.
+ */
+
+import { createHmac, type BinaryLike } from "node:crypto";
+import {
+  canonicalJson,
+  canonicalToolActionJson,
+  canonicalizeToolAction,
+  type ToolActionInput,
+} from "./approval-canonicalize.js";
+import { toolApprovalCategory } from "./tool-kind.js";
+
+/**
+ * Version tag prefixed to every fingerprint. Bumping it is the migration lever
+ * if the canonical form or the MAC primitive ever changes: an old lease and a
+ * new computation will not compare equal, so a version skew re-asks (safe) rather
+ * than silently mismatching. Keep in lockstep with the Go/Java editions.
+ */
+export const APPROVAL_FINGERPRINT_VERSION = "v1";
+
+/** The HMAC key. Raw bytes (Buffer) in production; a UTF-8 string in tests. */
+export type FingerprintKey = BinaryLike;
+
+/**
+ * Full-fidelity fingerprint for the in-process deep-agent gateway. Distinct
+ * actions (different tool, paths, command, or args) yield distinct fingerprints;
+ * the same action is byte-stable across re-invocations.
+ */
+export function computeApprovalFingerprint(key: FingerprintKey, input: ToolActionInput): string {
+  return tagged(hmacHex(key, canonicalToolActionJson(input)));
+}
+
+/**
+ * The substrate-coarsened identity of a tool action — the only fidelity the
+ * Cursor deny-oracle hook can reproduce from its stdin payload.
+ *
+ * Mirrors execute-cursor's `toolIdentity` so the two converge on one definition:
+ * - `tool` is the cross-taxonomy {@link toolApprovalCategory} (`write`/`delete`/
+ *   `shell`) for gated built-ins, the tool name for MCP tools (whose name is
+ *   stable across layers), or the trimmed tool name for non-gated built-ins
+ *   (never lease-matched, so the fallback is harmless).
+ * - `salient` is the single resource the action targets (a normalized path or the
+ *   shell command), reusing the full form's normalization so one rule governs
+ *   both fidelities. Empty for MCP tools, which are matched by `tool` alone.
+ */
+export interface CoarseToolIdentity {
+  tool: string;
+  mcpServerSlug: string;
+  salient: string;
+}
+
+export function coarseToolIdentity(input: ToolActionInput): CoarseToolIdentity {
+  const canonical = canonicalizeToolAction(input);
+  if (canonical.mcpServerSlug) {
+    return { tool: input.toolName.trim(), mcpServerSlug: canonical.mcpServerSlug, salient: "" };
+  }
+  const category = toolApprovalCategory(input.toolName);
+  return {
+    tool: category ?? input.toolName.trim(),
+    mcpServerSlug: "",
+    salient: canonical.paths[0] || canonical.shellCommand || "",
+  };
+}
+
+/**
+ * Fingerprint an already-reduced {@link CoarseToolIdentity}. Split out from
+ * {@link computeCoarseApprovalFingerprint} so a substrate that has *already*
+ * reduced a tool call to its (tool, mcpServerSlug, salient) identity — the Cursor
+ * harness, whose hook and stream both key on a raw, un-normalized salient that
+ * the bash hook can reproduce without a workspace root — can fingerprint that
+ * exact identity through the one shared HMAC+canonical-JSON path, instead of
+ * re-deriving the salient via {@link canonicalizeToolAction} (which normalizes
+ * paths and would diverge from the hook's raw value).
+ */
+export function fingerprintCoarseIdentity(key: FingerprintKey, identity: CoarseToolIdentity): string {
+  return tagged(hmacHex(key, canonicalJson(identity)));
+}
+
+/**
+ * Coarse fingerprint for the out-of-process Cursor hook. By construction, two
+ * actions that name the same operation in different taxonomies (`Write` vs
+ * `edit`) over the same resource collapse to one fingerprint — this is what makes
+ * the hook-side (deny/grant) and stream-side (reconciliation) values agree.
+ */
+export function computeCoarseApprovalFingerprint(key: FingerprintKey, input: ToolActionInput): string {
+  return fingerprintCoarseIdentity(key, coarseToolIdentity(input));
+}
+
+/**
+ * Derive the per-execution fingerprint key from a runner-held master secret.
+ *
+ * The key is scoped to one `execution_id`: stable across Temporal re-invocations
+ * of the same execution (the gateway approves on one invocation and enforces on
+ * the next), and isolated between executions so a fingerprint approved for one
+ * cannot be replayed against another. The master-secret source is wired when the
+ * gateway first consumes the fingerprint (Slices C/D); until then this is
+ * exercised only by tests against a fixed master secret.
+ */
+export function deriveExecutionFingerprintKey(masterSecret: FingerprintKey, executionId: string): Buffer {
+  return createHmac("sha256", masterSecret).update(executionId, "utf8").digest();
+}
+
+function hmacHex(key: FingerprintKey, canonical: string): string {
+  return createHmac("sha256", key).update(canonical, "utf8").digest("hex");
+}
+
+function tagged(mac: string): string {
+  return `${APPROVAL_FINGERPRINT_VERSION}:${mac}`;
+}