@stigmer/runner 3.0.9-dev.20260615153829 → 3.1.0

package/src/activities/execute-cursor/__test-utils__/cursor-hook-harness.ts

@@ -0,0 +1,216 @@
+/**
+ * Test harness for the generated Cursor preToolUse bash hook.
+ *
+ * Runs the ACTUAL bash script the runner writes into the workspace, feeding it
+ * the REAL hook-input shapes captured from `@cursor/sdk`. It is the out-of-process
+ * deny-oracle's only honest test surface: write the runner-owned state file (with
+ * any approval grants), invoke the hook, and read back its allow/deny decision
+ * and the denial ledger.
+ *
+ * Extracted from `__tests__/hook-script.test.ts` so it is shared by both that
+ * behavior suite and the deny-oracle adapter in the gateway Contract Test Kit
+ * (`__test-utils__/gateway-substrate.ts`) — one harness, no drift.
+ *
+ * Each harness owns a throwaway workspace under the OS temp dir and self-cleans
+ * via `onTestFinished`, so it must be called from within a running test.
+ */
+
+import { onTestFinished } from "vitest";
+import { execFileSync, execSync } from "node:child_process";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, readFileSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { generateHookScript } from "../hook-script.js";
+import { buildApprovalState, type ApprovalGrant, type McpToolPolicyEntry } from "../approval-state.js";
+import type { MergedToolPolicy, ApprovalCategory } from "../approval-policy.js";
+import { readCasObservations, type CasObservations } from "../cas-observations.js";
+
+/**
+ * Whether `bash` is available on this machine. Hook tests must be skipped where
+ * it is not — use `const d = hasBash ? describe : describe.skip`.
+ */
+export const hasBash: boolean = (() => {
+  try {
+    execSync("bash -c 'exit 0'", { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+})();
+
+export interface CursorHookHarness {
+  /** The throwaway workspace root (git repo when capture mode is on). */
+  readonly root: string;
+  /** Run the hook against a single hook-input payload and report its decision. */
+  decide(input: object): { permission: string; raw: string };
+  /**
+   * The denial ledger entries the hook has appended this turn. `input` is the
+   * base64(JSON(tool_input)) the hook captures (decode + JSON.parse to inspect).
+   */
+  ledger(): Array<{ toolName: string; token: string; input?: string }>;
+  /** Truncate the denial ledger (a fresh turn). */
+  resetLedger(): void;
+  /**
+   * The cas-observations the hook staged this turn (captured gitignored writes +
+   * secret-blocked paths), read back through the real sidecar reader. Empty when
+   * captureIgnored is off / nothing was staged.
+   */
+  observations(): Promise<CasObservations>;
+}
+
+export interface CursorHookHarnessOptions {
+  /** Pre-armed spec.auto_approve_all (the whole-run global bypass). */
+  autoApproveAll?: boolean;
+  /** Built-in categories with a run-lifetime scoped lease. */
+  leasedCategories?: ApprovalCategory[];
+  grants?: ApprovalGrant[];
+  mcpPolicies?: Record<string, McpToolPolicyEntry>;
+  /** Omit the state file to exercise the fail-closed (deny) path. */
+  noStateFile?: boolean;
+  /**
+   * Process the hook treats as "the runner". Defaults to this test process,
+   * which is an ancestor of the bash child `execFileSync` spawns — so the scope
+   * guard sees the call as the runner's own agent and applies the gate. Pass a
+   * non-ancestor PID to exercise the foreign-client path (issue #173).
+   */
+  runnerPid?: number;
+  /**
+   * Capture mode (git workspaces): the hook ALLOWS write/edit/delete to flow,
+   * gating only gitignored paths, shell, and MCP. When set, the harness baked
+   * workspace root is the throwaway workspace so `git check-ignore` resolves.
+   */
+  captureMode?: boolean;
+  /**
+   * Initialize the throwaway workspace as a git repo with these gitignore
+   * patterns, so capture mode's `git check-ignore` has a real repo to consult.
+   */
+  gitignored?: string[];
+  /**
+   * CAS capture of gitignored writes (deep-agent parity). When true, the hook
+   * stages a non-secret gitignored write's before-bytes into the cas-observations
+   * sidecar and ALLOWS it, and hard-blocks a secret-like gitignored write —
+   * instead of denying every gitignored write. Requires a git repo (set via
+   * {@link captureMode} or {@link gitignored}).
+   */
+  captureIgnored?: boolean;
+  /**
+   * Whether the workspace is a git tree (Slice 2c). Default true. When false the
+   * throwaway workspace is NOT git-initialized and the state's `gitWorkspace` flag
+   * is false, so the hook CAS-stages EVERY write (not only gitignored ones) and
+   * skips the git-tracked flow arm.
+   */
+  gitWorkspace?: boolean;
+}
+
+/**
+ * Build a throwaway workspace, write the generated hook + (optionally) the
+ * approval state file, and return a driver for the real bash hook.
+ */
+export function setupCursorHookHarness(opts: CursorHookHarnessOptions = {}): CursorHookHarness {
+  const ws = mkdtempSync(join(tmpdir(), "hook-script-"));
+  onTestFinished(() => rmSync(ws, { recursive: true, force: true }));
+
+  // Capture-mode tests need a real git repo so `git check-ignore` resolves. A
+  // non-git test (gitWorkspace:false) deliberately leaves the workspace un-inited
+  // so the hook's substrate matches the state's gitWorkspace flag.
+  if ((opts.captureMode || opts.gitignored) && opts.gitWorkspace !== false) {
+    execSync("git init -q", { cwd: ws });
+    if (opts.gitignored && opts.gitignored.length > 0) {
+      writeFileSync(join(ws, ".gitignore"), opts.gitignored.join("\n") + "\n", "utf-8");
+    }
+  }
+
+  const dir = join(ws, ".cursor", "hooks");
+  mkdirSync(dir, { recursive: true });
+  const statePath = join(dir, "state.json");
+  const ledgerPath = join(dir, "denials.jsonl");
+  const pointerPath = join(dir, "active.json");
+  const scriptPath = join(dir, "hook.sh");
+  // The hook script is STABLE (no baked per-turn paths); it resolves the current
+  // turn's state/ledger/runner from the active-turn pointer it re-reads each call.
+  // The workspace root is baked so capture mode's gitignore check finds the repo.
+  writeFileSync(scriptPath, generateHookScript(pointerPath, ws), "utf-8");
+  writeFileSync(
+    pointerPath,
+    JSON.stringify({
+      stateFile: statePath,
+      ledgerFile: ledgerPath,
+      runnerPid: opts.runnerPid ?? process.pid,
+    }),
+    "utf-8",
+  );
+
+  if (!opts.noStateFile) {
+    const policies = new Map<string, MergedToolPolicy>(
+      Object.entries(opts.mcpPolicies ?? {}).map(([name, p]) => [
+        `srv/${name}`,
+        {
+          toolName: name,
+          mcpServerSlug: "srv",
+          requiresApproval: p.requiresApproval,
+          approvalMessage: p.message ?? "",
+          source: "classifier_default" as const,
+        },
+      ]),
+    );
+    const state = buildApprovalState(
+      policies,
+      opts.autoApproveAll ?? false,
+      new Set(opts.leasedCategories ?? []),
+      opts.grants,
+      opts.captureMode ?? false,
+      opts.captureIgnored ?? false,
+      opts.gitWorkspace ?? true,
+    );
+    writeFileSync(statePath, JSON.stringify(state), "utf-8");
+  }
+
+  return {
+    root: ws,
+    decide(input: object) {
+      const raw = execFileSync("bash", [scriptPath], { input: JSON.stringify(input) }).toString();
+      const permission = raw.includes('"permission":"deny"')
+        ? "deny"
+        : raw.includes('"permission":"allow"')
+          ? "allow"
+          : "?";
+      return { permission, raw };
+    },
+    ledger() {
+      if (!existsSync(ledgerPath)) return [];
+      return readFileSync(ledgerPath, "utf-8")
+        .split("\n")
+        .filter(Boolean)
+        .map((l) => JSON.parse(l));
+    },
+    resetLedger() {
+      writeFileSync(ledgerPath, "", "utf-8");
+    },
+    // The sidecar lives beside the state/ledger files (its `dir` is the harness's
+    // hitlDir analog), exactly as the runner derives it from dirname(STATE_FILE).
+    observations() {
+      return readCasObservations(dir);
+    },
+  };
+}
+
+// Real preToolUse hook-input shapes (PascalCase name, file_path/command in
+// tool_input). These omit hook_event_name on purpose: a payload with no event
+// must still take the built-in arm (the script only diverts to the MCP arm on an
+// explicit beforeMCPExecution).
+export const hookWrite = (filePath: string, content = "x") => ({ tool_name: "Write", tool_input: { file_path: filePath, content } });
+export const hookEdit = (filePath: string, oldString = "a", newString = "b") => ({ tool_name: "StrReplace", tool_input: { file_path: filePath, old_string: oldString, new_string: newString } });
+export const hookShell = (command: string) => ({ tool_name: "Shell", tool_input: { command, cwd: "/x", timeout: 30000 } });
+export const hookDelete = (filePath: string) => ({ tool_name: "Delete", tool_input: { file_path: filePath } });
+export const hookRead = (filePath: string) => ({ tool_name: "Read", tool_input: { file_path: filePath } });
+
+// Real beforeMCPExecution shape (captured live): bare tool_name, tool_input as a
+// JSON STRING, server identity, and the hook_event_name discriminator.
+export const hookMcp = (name: string, input: Record<string, unknown> = {}) => ({
+  tool_name: name,
+  tool_input: JSON.stringify(input),
+  mcp_server_name: "srv",
+  command: "npx -y srv mcp",
+  hook_event_name: "beforeMCPExecution",
+});

package/src/activities/execute-cursor/__test-utils__/gateway-substrate.ts

@@ -0,0 +1,148 @@
+/**
+ * Cursor deny-oracle adapter for the HITL gateway Contract Test Kit.
+ *
+ * Drives the REAL out-of-process gateway: the runner writes the approval state
+ * file (with any grants), then the generated bash preToolUse hook makes the
+ * allow/deny decision for the tool the agent would run inside cursor-agent. There
+ * is no in-process execution to observe, so `executed` means "the hook allowed
+ * it" and the substrate cannot count executions (`observesExecution: false`).
+ *
+ * Cross-taxonomy by construction: grants are minted from the STREAM-side identity
+ * (`edit`/`shell`/`delete`), while the hook is fed the HOOK-side payload
+ * (`Write`/`Shell`/`Delete`). So every approve drive exercises the category
+ * collapse that lets a stream-minted grant match a hook-named call. The grant
+ * token binds the exact resource, so this substrate enforces lease isolation
+ * (`enforcesExactResource: true`) and implements `authorizeAfterGrant`.
+ */
+
+import {
+  setupCursorHookHarness,
+  hasBash,
+  hookWrite,
+  hookShell,
+  hookDelete,
+  hookRead,
+  hookMcp,
+} from "./cursor-hook-harness.js";
+import { toolIdentity, type ApprovalGrant } from "../approval-state.js";
+import { contentDigest } from "../../../shared/file-tools.js";
+import type { ApprovalCategory } from "../approval-policy.js";
+import type {
+  GatewayDecision,
+  GatewayOutcome,
+  GatewaySubstrate,
+  ProposedAction,
+} from "../../../__test-utils__/approval-contract/types.js";
+
+/** Build the real preToolUse hook-input payload for an abstract action. */
+function hookInputFor(action: ProposedAction): object {
+  switch (action.kind) {
+    case "write":
+      return hookWrite(action.resource, action.content ?? "x");
+    case "shell":
+      return hookShell(action.resource);
+    case "delete":
+      return hookDelete(action.resource);
+    case "read":
+      return hookRead(action.resource);
+    case "mcp":
+      return hookMcp(action.mcpToolName ?? "mcp_tool");
+  }
+}
+
+// Stream-side (SDK) tool name per gated category — deliberately the OTHER
+// taxonomy from the hook input, so a grant minted here matches a hook-named call
+// only via the canonical category, not the raw name.
+const STREAM_NAME: Record<"write" | "shell" | "delete", string> = {
+  write: "edit",
+  shell: "shell",
+  delete: "delete",
+};
+
+/**
+ * Mint the approval grant for an action using its stream-side identity. Only the
+ * gated built-in categories are ever granted in the contract (read is never
+ * gated; the MCP cases under test are auto-approved, needing no grant).
+ */
+function grantFor(action: ProposedAction): ApprovalGrant {
+  if (action.kind === "read" || action.kind === "mcp") {
+    throw new Error(`grantFor: ${action.kind} actions are not granted in the contract`);
+  }
+  const streamName = STREAM_NAME[action.kind];
+  // Mirror hookInputFor: a write carries whole-file content (so its digest is
+  // content-exact and matches the hook's), a delete carries only a path (no
+  // content), and a shell carries its command (the salient is already exact).
+  const args: Record<string, unknown> =
+    action.kind === "shell"
+      ? { command: action.resource }
+      : action.kind === "delete"
+        ? { path: action.resource }
+        : { path: action.resource, content: action.content ?? "x" };
+  const identity = toolIdentity(streamName, "", args);
+  return {
+    toolName: streamName,
+    mcpServerSlug: "",
+    key: identity.key,
+    salient: identity.salient,
+    // Content-exact for a write (the sibling-isolation probe), coarse otherwise —
+    // matching how the runner grants from the authoritative captured args.
+    contentDigest: contentDigest(args),
+    sourceToolCallId: `consent-${action.kind}`,
+  };
+}
+
+async function decide(grants: ApprovalGrant[], action: ProposedAction): Promise<GatewayOutcome> {
+  // MCP cases under test are auto-approved: no policy entry, so the hook allows
+  // them. Built-ins are gated by the script's baked-in category set, not state.
+  const harness = setupCursorHookHarness({ grants });
+  const { permission } = harness.decide(hookInputFor(action));
+  const executed = permission === "allow";
+  return { executed, gated: !executed };
+}
+
+// A gated built-in's contract kind IS its approval category (write/shell/delete),
+// so it doubles as the leasedCategories entry the hook reads.
+function leaseCategoryOf(action: ProposedAction): ApprovalCategory {
+  if (action.kind === "read" || action.kind === "mcp") {
+    throw new Error(`leaseCategoryOf: ${action.kind} is not a leasable built-in class`);
+  }
+  return action.kind;
+}
+
+export function createCursorSubstrate(): GatewaySubstrate {
+  return {
+    name: "cursor",
+    available: hasBash,
+    capabilities: {
+      observesExecution: false,
+      enforcesExactResource: true,
+      // The grant binds (category, path, contentDigest), so a DIFFERENT edit to
+      // the same file re-gates — the sibling-hole fix.
+      enforcesExactContent: true,
+      appliesRunLifetimeLease: true,
+      // The Cursor hook's deny decision does not carry approval_policy_source;
+      // provenance is projected at message-reconstruction time (message-translator)
+      // and asserted by the corpus + resolveApprovalProvenance suites instead.
+      surfacesGatePolicySource: false,
+    },
+
+    async authorize(action: ProposedAction, decision: GatewayDecision): Promise<GatewayOutcome> {
+      const grants = decision === "approve" ? [grantFor(action)] : [];
+      return decide(grants, action);
+    },
+
+    async authorizeAfterGrant(granted: ProposedAction, probe: ProposedAction): Promise<GatewayOutcome> {
+      return decide([grantFor(granted)], probe);
+    },
+
+    async authorizeUnderClassLease(leased: ProposedAction, probe: ProposedAction): Promise<GatewayOutcome> {
+      // A run-lifetime category lease is carried in the state file (no per-call
+      // grant), exactly as the runner writes it after an APPROVE_ALL; the hook
+      // allows a probe iff its category is leased.
+      const harness = setupCursorHookHarness({ leasedCategories: [leaseCategoryOf(leased)] });
+      const { permission } = harness.decide(hookInputFor(probe));
+      const executed = permission === "allow";
+      return { executed, gated: !executed };
+    },
+  };
+}

package/src/activities/execute-cursor/__tests__/approval-gate.test.ts

@@ -1,4 +1,6 @@
 /**
+ * @regression file-hitl-phase0 — pins file-edit HITL fix #6 (see _projects/2026-06/20260630.01.file-change-hitl-redesign/tasks/T01_3_regression-manifest.md)
+ *
  * Unit tests for the Cursor-harness HITL approval gate logic.
  *
  * The crux this suite guards: the Cursor preToolUse hook and the SDK event
@@ -13,7 +15,7 @@
  */
 
 import { describe, it, expect } from "vitest";
-import { create } from "@bufbuild/protobuf";
+import { create, type MessageInitShape } from "@bufbuild/protobuf";
 import { PendingApprovalSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/approval_pb";
 import type { PendingApproval } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/approval_pb";
 import { ApprovalAction } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
@@ -35,7 +37,7 @@ import {
 } from "../approval-state.js";
 import { buildReinvocationPrompt } from "../prompt-builder.js";
 
-function pending(overrides: Partial<PendingApproval>): PendingApproval {
+function pending(overrides: MessageInitShape<typeof PendingApprovalSchema>): PendingApproval {
   return create(PendingApprovalSchema, {
     toolCallId: "call-1",
     toolName: "edit",
@@ -163,7 +165,17 @@ describe("buildApprovalGrants", () => {
       [pending({ toolCallId: "c1", toolName: "edit", argsPreview: JSON.stringify({ path: "/x/gated.txt" }) })],
       new Map([["c1", ApprovalAction.APPROVE]]),
     );
-    expect(grants).toEqual([{ toolName: "edit", mcpServerSlug: "", key: "write", salient: "/x/gated.txt" }]);
+    expect(grants).toEqual([{ toolName: "edit", mcpServerSlug: "", key: "write", salient: "/x/gated.txt", contentDigest: "", sourceToolCallId: "c1" }]);
+  });
+
+  it("binds an approved edit's grant to its content digest (sibling-isolation)", () => {
+    const digest = "abc123";
+    const grants = buildApprovalGrants(
+      [pending({ toolCallId: "c1", toolName: "edit", argsPreview: JSON.stringify({ path: "/x/gated.txt" }) })],
+      new Map([["c1", ApprovalAction.APPROVE]]),
+      new Map([["c1", digest]]),
+    );
+    expect(grants).toEqual([{ toolName: "edit", mcpServerSlug: "", key: "write", salient: "/x/gated.txt", contentDigest: digest, sourceToolCallId: "c1" }]);
   });
 
   it("creates a name-only grant for an approved MCP tool", () => {
@@ -171,7 +183,7 @@ describe("buildApprovalGrants", () => {
       [pending({ toolCallId: "c1", toolName: "apply_x", mcpServerSlug: "planton", argsPreview: JSON.stringify({ path: "ignored" }) })],
       new Map([["c1", ApprovalAction.APPROVE]]),
     );
-    expect(grants).toEqual([{ toolName: "apply_x", mcpServerSlug: "planton", key: "apply_x", salient: "" }]);
+    expect(grants).toEqual([{ toolName: "apply_x", mcpServerSlug: "planton", key: "apply_x", salient: "", contentDigest: "", sourceToolCallId: "c1" }]);
   });
 
   it("ignores skipped and rejected approvals", () => {
@@ -191,23 +203,43 @@ describe("buildApprovalGrants", () => {
 
 describe("buildApprovalState", () => {
   const mcpPolicies = new Map<string, MergedToolPolicy>([
-    ["planton/apply_x", { toolName: "apply_x", mcpServerSlug: "planton", requiresApproval: true, approvalMessage: "Apply X" }],
+    ["planton/apply_x", { toolName: "apply_x", mcpServerSlug: "planton", requiresApproval: true, approvalMessage: "Apply X", source: "classifier_default" }],
   ]);
 
   it("carries MCP policies and exact-resource grant tokens (gated set is baked into the hook, not the state)", () => {
-    const grants = [{ toolName: "edit", mcpServerSlug: "", key: "write", salient: "/x/gated.txt" }];
-    const state = buildApprovalState(mcpPolicies, false, grants);
+    const grants = [{ toolName: "edit", mcpServerSlug: "", key: "write", salient: "/x/gated.txt", contentDigest: "", sourceToolCallId: "consent-1" }];
+    const state = buildApprovalState(mcpPolicies, false, new Set(), grants);
 
     expect(state.autoApproveAll).toBe(false);
+    expect(state.leasedCategories).toEqual([]);
     expect(state.mcpToolPolicies.apply_x).toEqual({ requiresApproval: true, message: "Apply X" });
+    // No digest -> the primary token degrades to the coarse grant token.
     expect(state.approvedGrantTokens).toEqual([grantToken("write", "/x/gated.txt")]);
     // builtInGatedList is no longer part of the state file (baked into the hook).
-    expect((state as Record<string, unknown>).builtInGatedList).toBeUndefined();
+    expect((state as unknown as Record<string, unknown>).builtInGatedList).toBeUndefined();
+  });
+
+  it("emits the CONTENT token when a grant carries a content digest", () => {
+    const grants = [{ toolName: "edit", mcpServerSlug: "", key: "write", salient: "/x/gated.txt", contentDigest: "deadbeef", sourceToolCallId: "consent-1" }];
+    const state = buildApprovalState(mcpPolicies, false, new Set(), grants);
+    // A content-identified grant authorizes base64(key\nsalient\ndigest), so a
+    // DIFFERENT edit to the same path (different digest) does not match.
+    expect(state.approvedGrantTokens).toEqual([
+      Buffer.from("write\n/x/gated.txt\ndeadbeef", "utf-8").toString("base64"),
+    ]);
+    expect(state.approvedGrantTokens[0]).not.toBe(grantToken("write", "/x/gated.txt"));
+  });
+
+  it("writes leasedCategories for run-lifetime scoped leases", () => {
+    const state = buildApprovalState(mcpPolicies, false, new Set(["shell", "write"]));
+    expect(state.autoApproveAll).toBe(false);
+    expect(state.leasedCategories.sort()).toEqual(["shell", "write"]);
   });
 
   it("defaults grants to empty when none provided", () => {
-    const state = buildApprovalState(mcpPolicies, true);
+    const state = buildApprovalState(mcpPolicies, true, new Set());
     expect(state.autoApproveAll).toBe(true);
+    expect(state.leasedCategories).toEqual([]);
     expect(state.approvedGrants).toEqual([]);
     expect(state.approvedGrantTokens).toEqual([]);
   });