@stigmer/runner 3.0.9-dev.20260615153829 → 3.1.0

package/src/activities/execute-cursor/__tests__/workspace-setup.test.ts

@@ -27,6 +27,7 @@ import {
   buildMergedConfig,
 } from "../workspace-setup.js";
 import { buildApprovalState } from "../approval-state.js";
+import { getHitlGateDir } from "../../../shared/workspace/platform-dir.js";
 
 const tempDirs: string[] = [];
 afterEach(() => {
@@ -159,42 +160,117 @@ describe("buildMergedConfig", () => {
     // ...and never "fix" the user's file: restore their exact original bytes.
     expect(restoreTo).toBe(garbage);
   });
+
+  // ── H-G regression: the pre-#173 in-workspace hook ──────────────────────────
+  // The root cause of "approved tool still blocked": an older runner build wrote
+  // the gate INTO the repo as `.cursor/hooks/stigmer-approval.sh` (a relative
+  // command). The recognizer used to match only the current `/.stigmer/sessions/`
+  // path, so the merge treated this stale entry as a USER hook and preserved it —
+  // it then ran alongside the current gate and vetoed every gated tool, even
+  // approved ones. These pin that it is now recognized, stripped, and self-healed.
+
+  it("recognizes and strips the legacy in-workspace hook; deletes the entirely-leftover file", () => {
+    // The exact shape observed in a polluted repo.
+    const original = JSON.stringify({
+      version: 1,
+      hooks: {
+        preToolUse: [
+          { command: ".cursor/hooks/stigmer-approval.sh", timeout: 10, failClosed: true },
+        ],
+      },
+    });
+    const fresh = "/home/u/.stigmer/sessions/ses-9/hitl/stigmer-approval.sh";
+    const { merged, restoreTo } = buildMergedConfig(original, pre(fresh));
+
+    // The active config carries ONLY the current runner hook — the stale legacy
+    // entry is gone, so it can never run alongside (and veto) the live gate.
+    const m = JSON.parse(merged);
+    expect(m.hooks.preToolUse.map((e: any) => e.command)).toEqual([fresh]);
+
+    // The whole hooks.json was our own leftover (only version+hooks, no user
+    // hooks remain after stripping) → teardown deletes it, leaving the repo
+    // pristine rather than a `{hooks:{preToolUse:[]}}` husk.
+    expect(restoreTo).toBeNull();
+  });
+
+  it("strips the legacy hook but preserves a genuine user hook in the same array", () => {
+    const original = JSON.stringify({
+      version: 1,
+      hooks: {
+        preToolUse: [
+          { command: "./user.sh" },
+          { command: ".cursor/hooks/stigmer-approval.sh", timeout: 10, failClosed: true },
+        ],
+      },
+    });
+    const fresh = "/home/u/.stigmer/sessions/ses-9/hitl/stigmer-approval.sh";
+    const { merged, restoreTo } = buildMergedConfig(original, pre(fresh));
+
+    // No duplicate, stale legacy entry dropped, user hook kept ahead of ours.
+    expect(JSON.parse(merged).hooks.preToolUse.map((e: any) => e.command)).toEqual([
+      "./user.sh",
+      fresh,
+    ]);
+    // A real user hook remains → restore the cleaned form, not delete.
+    expect(JSON.parse(restoreTo!).hooks.preToolUse).toEqual([{ command: "./user.sh" }]);
+  });
 });
 
 describe("installHitlGate / removeHitlGate", () => {
-  const approvalState = buildApprovalState(new Map(), false);
+  const approvalState = buildApprovalState(new Map(), false, new Set());
+
+  // Sandbox HOME so the workspace-scoped gate dir (`~/.stigmer/hitl-gate/<hash>`)
+  // lands under the per-test temp root, asserted and cleaned with everything else.
+  const realHome = process.env.HOME;
+  afterEach(() => {
+    if (realHome === undefined) delete process.env.HOME;
+    else process.env.HOME = realHome;
+  });
 
   function dirs() {
     const root = freshRoot();
+    process.env.HOME = root;
     const workspaceRoot = join(root, "repo");
     const hitlDir = join(root, ".stigmer", "sessions", "ses-1", "hitl");
     mkdirSync(workspaceRoot, { recursive: true });
-    return { workspaceRoot, hitlDir };
+    // The stable hook script + active-turn pointer live in the workspace-scoped
+    // gate dir (outside the repo), not the per-session HITL dir.
+    const gateDir = getHitlGateDir(workspaceRoot);
+    return { workspaceRoot, hitlDir, gateDir };
   }
 
   it("writes artifacts OUTSIDE the workspace and a hooks.json with an absolute command", async () => {
-    const { workspaceRoot, hitlDir } = dirs();
+    const { workspaceRoot, hitlDir, gateDir } = dirs();
     await installHitlGate({ workspaceRoot, hitlDir, approvalState, runnerPid: process.pid });
 
-    // Gate artifacts live in the HITL dir, never in the repo.
-    expect(existsSync(join(hitlDir, "stigmer-approval.sh"))).toBe(true);
+    // Per-session hook input/output live in the HITL dir; the STABLE hook script
+    // and the active-turn pointer live in the workspace gate dir. Neither is in
+    // the repo.
     expect(existsSync(join(hitlDir, "approval-state.json"))).toBe(true);
     expect(existsSync(join(hitlDir, "denials.jsonl"))).toBe(true);
+    expect(existsSync(join(gateDir, "stigmer-approval.sh"))).toBe(true);
+    expect(existsSync(join(gateDir, "active.json"))).toBe(true);
     // The script is executable.
-    expect(statSync(join(hitlDir, "stigmer-approval.sh")).mode & 0o111).toBeTruthy();
+    expect(statSync(join(gateDir, "stigmer-approval.sh")).mode & 0o111).toBeTruthy();
+
+    // The pointer names THIS turn's per-session artifacts + runner PID.
+    const pointer = JSON.parse(readFileSync(join(gateDir, "active.json"), "utf-8"));
+    expect(pointer.stateFile).toBe(join(hitlDir, "approval-state.json"));
+    expect(pointer.ledgerFile).toBe(join(hitlDir, "denials.jsonl"));
+    expect(pointer.runnerPid).toBe(process.pid);
 
-    // The only in-repo file is hooks.json, pointing at the script by ABSOLUTE
-    // path (the relative path was the multi-root exit-127 bug).
+    // The only in-repo file is hooks.json, pointing at the STABLE script by
+    // ABSOLUTE path (the relative path was the multi-root exit-127 bug).
     const hooksJson = JSON.parse(
       readFileSync(join(workspaceRoot, ".cursor", "hooks.json"), "utf-8"),
     );
     const command = hooksJson.hooks.preToolUse[0].command;
-    expect(command).toBe(join(hitlDir, "stigmer-approval.sh"));
+    expect(command).toBe(join(gateDir, "stigmer-approval.sh"));
     expect(command.startsWith("/")).toBe(true);
     // The SAME script gates MCP via beforeMCPExecution (preToolUse does not
     // enforce MCP); the script branches internally on hook_event_name.
     expect(hooksJson.hooks.beforeMCPExecution[0].command).toBe(
-      join(hitlDir, "stigmer-approval.sh"),
+      join(gateDir, "stigmer-approval.sh"),
     );
     // The workspace holds no relocated artifacts.
     expect(existsSync(join(workspaceRoot, ".cursor", "hooks"))).toBe(false);
@@ -250,4 +326,108 @@ describe("installHitlGate / removeHitlGate", () => {
       expect(existsSync(join(workspaceRoot, ".cursor", "hooks.json"))).toBe(false);
     }
   });
+
+  it("installs the always-applied tool-approval rule and removes it on teardown", async () => {
+    const { workspaceRoot, hitlDir } = dirs();
+    const rulePath = join(workspaceRoot, ".cursor", "rules", "stigmer-tool-approval.mdc");
+
+    const handle = await installHitlGate({
+      workspaceRoot, hitlDir, approvalState, runnerPid: process.pid,
+    });
+    // During the turn the rule is present and carries the protocol.
+    expect(existsSync(rulePath)).toBe(true);
+    const ruleBody = readFileSync(rulePath, "utf-8");
+    expect(ruleBody).toContain("alwaysApply: true");
+    expect(ruleBody.toLowerCase()).toContain("blocked by a hook");
+
+    await removeHitlGate(handle);
+    // Teardown removes our rule and the now-empty rules dir (the repo had none).
+    expect(existsSync(rulePath)).toBe(false);
+    expect(existsSync(join(workspaceRoot, ".cursor", "rules"))).toBe(false);
+  });
+
+  it("heals a workspace polluted by a pre-#173 in-workspace gate (H-G end-to-end)", async () => {
+    const { workspaceRoot, hitlDir, gateDir } = dirs();
+    // Reconstruct exactly what a polluted repo looks like: a hooks.json pointing
+    // at a relative in-workspace script, plus the orphaned script/state/ledger
+    // files an older runner left in `.cursor/hooks/`.
+    const cursorDir = join(workspaceRoot, ".cursor");
+    const legacyHooksDir = join(cursorDir, "hooks");
+    mkdirSync(legacyHooksDir, { recursive: true });
+    writeFileSync(
+      join(cursorDir, "hooks.json"),
+      JSON.stringify({
+        version: 1,
+        hooks: {
+          preToolUse: [
+            { command: ".cursor/hooks/stigmer-approval.sh", timeout: 10, failClosed: true },
+          ],
+        },
+      }),
+      "utf-8",
+    );
+    writeFileSync(join(legacyHooksDir, "stigmer-approval.sh"), "#!/bin/bash\nexit 0\n", "utf-8");
+    writeFileSync(join(legacyHooksDir, "stigmer-approval-state.json"), "{}", "utf-8");
+    writeFileSync(join(legacyHooksDir, "stigmer-denials.jsonl"), "", "utf-8");
+
+    const handle = await installHitlGate({
+      workspaceRoot, hitlDir, approvalState, runnerPid: process.pid,
+    });
+
+    // The active gate is ONLY the current runner-owned hook (absolute, in the
+    // session dir). The stale relative entry that vetoed approved tools is gone.
+    const during = JSON.parse(readFileSync(join(cursorDir, "hooks.json"), "utf-8"));
+    expect(during.hooks.preToolUse.map((e: any) => e.command)).toEqual([
+      join(gateDir, "stigmer-approval.sh"),
+    ]);
+    // The orphaned legacy files are removed; the now-empty hooks dir is gone too.
+    expect(existsSync(join(legacyHooksDir, "stigmer-approval.sh"))).toBe(false);
+    expect(existsSync(join(legacyHooksDir, "stigmer-approval-state.json"))).toBe(false);
+    expect(existsSync(join(legacyHooksDir, "stigmer-denials.jsonl"))).toBe(false);
+    expect(existsSync(legacyHooksDir)).toBe(false);
+
+    await removeHitlGate(handle);
+    // The hooks.json was entirely our own leftover → teardown deletes it, leaving
+    // the repo pristine (no husk, no stale entry waiting to re-pollute).
+    expect(existsSync(join(cursorDir, "hooks.json"))).toBe(false);
+  });
+
+  it("removes only stigmer-* files from .cursor/hooks, preserving a user's own hook script", async () => {
+    const { workspaceRoot, hitlDir } = dirs();
+    const legacyHooksDir = join(workspaceRoot, ".cursor", "hooks");
+    mkdirSync(legacyHooksDir, { recursive: true });
+    writeFileSync(join(legacyHooksDir, "stigmer-approval.sh"), "#!/bin/bash\nexit 0\n", "utf-8");
+    writeFileSync(join(legacyHooksDir, "user-custom.sh"), "#!/bin/bash\necho hi\n", "utf-8");
+
+    const handle = await installHitlGate({
+      workspaceRoot, hitlDir, approvalState, runnerPid: process.pid,
+    });
+
+    // Our leftover is gone; the user's script and the dir they own remain.
+    expect(existsSync(join(legacyHooksDir, "stigmer-approval.sh"))).toBe(false);
+    expect(readFileSync(join(legacyHooksDir, "user-custom.sh"), "utf-8")).toBe(
+      "#!/bin/bash\necho hi\n",
+    );
+    expect(existsSync(legacyHooksDir)).toBe(true);
+
+    await removeHitlGate(handle);
+  });
+
+  it("preserves a user's own .cursor/rules and rules dir after teardown", async () => {
+    const { workspaceRoot, hitlDir } = dirs();
+    const rulesDir = join(workspaceRoot, ".cursor", "rules");
+    mkdirSync(rulesDir, { recursive: true });
+    const userRule = join(rulesDir, "user-rule.mdc");
+    writeFileSync(userRule, "---\nalwaysApply: false\n---\nmine\n", "utf-8");
+
+    const handle = await installHitlGate({
+      workspaceRoot, hitlDir, approvalState, runnerPid: process.pid,
+    });
+    await removeHitlGate(handle);
+
+    // Our rule is gone; the user's rule and the dir they owned remain untouched.
+    expect(existsSync(join(rulesDir, "stigmer-tool-approval.mdc"))).toBe(false);
+    expect(readFileSync(userRule, "utf-8")).toBe("---\nalwaysApply: false\n---\nmine\n");
+    expect(existsSync(rulesDir)).toBe(true);
+  });
 });

package/src/activities/execute-cursor/approval-policy.ts

@@ -16,21 +16,20 @@
  * a separate local policy applies.
  */
 
-import type { ToolApprovalPolicy } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/spec_pb";
-import type { ToolApprovalOverride } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/spec_pb";
-import { ToolKind } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
-import type { ResolvedMcpServer } from "./mcp-resolver.js";
-import { classifyTool } from "../../shared/tool-kind.js";
-
-/**
- * A single tool's merged approval decision after evaluating all policy layers.
- */
-export interface MergedToolPolicy {
-  toolName: string;
-  mcpServerSlug: string;
-  requiresApproval: boolean;
-  approvalMessage: string;
-}
+import { toolApprovalCategory, type ToolApprovalCategory } from "../../shared/tool-kind.js";
+
+// The four-level MCP policy merge is harness-agnostic and lives in exactly one
+// place (shared/approval-policy.ts) so the Cursor and native harnesses can never
+// diverge. Re-exported here so existing Cursor-harness imports
+// (`from "./approval-policy.js"`) keep working unchanged. This module now owns
+// only the Cursor-specific built-in-tool gating helpers below.
+export {
+  mergeApprovalPolicies,
+  lookupMcpToolPolicy,
+  resolveApprovalMessage,
+  POLICY_ENGINE_VERSION,
+} from "../../shared/approval-policy.js";
+export type { MergedToolPolicy, PolicySource } from "../../shared/approval-policy.js";
 
 /**
  * Built-in Cursor tools the preToolUse hook gates, named as the hook receives
@@ -53,36 +52,24 @@ const BUILT_IN_GATED: ReadonlySet<string> = new Set([
 ]);
 
 /**
- * Canonical approval category for a gated tool, derived from EITHER taxonomy's
- * name via the shared {@link classifyTool}.
+ * Canonical approval category for a gated tool.
  *
- * The hook (`Write`/`Shell`/`Delete`) and the stream (`edit`/`shell`/`delete`)
- * name the same operation differently, so neither raw name is a stable
- * cross-layer identity. The category collapses both onto one value so the denial
- * ledger (recorded by the hook) correlates to the streamed tool call (read by
- * the runner) and so an approval grant matches the agent's re-attempt on
- * reinvocation regardless of which taxonomy named it. `FILE_WRITE` and
- * `FILE_EDIT` both map to `write` because the Cursor hook reports every file
- * mutation — create or edit — as `Write`.
+ * This is the cross-substrate identity, and it lives in ONE place:
+ * {@link toolApprovalCategory} in shared/tool-kind.ts (shared with the deep-agent
+ * gateway). The names below are kept as the Cursor harness's public surface
+ * (`approvalCategory` / `ApprovalCategory`) so existing imports do not churn, but
+ * they are exact aliases — there is no second implementation to drift.
  *
- * Returns undefined for non-gated tools (read-only built-ins, MCP tools, and
- * anything `classifyTool` does not place in a mutating kind).
+ * Why this matters here: the hook (`Write`/`Shell`/`Delete`) and the stream
+ * (`edit`/`shell`/`delete`) name the same operation differently, so neither raw
+ * name is a stable cross-layer identity. The category collapses both onto one
+ * value so the denial ledger (recorded by the hook) correlates to the streamed
+ * tool call (read by the runner) and an approval grant matches the agent's
+ * re-attempt on reinvocation regardless of which taxonomy named it.
  */
-export type ApprovalCategory = "write" | "delete" | "shell";
+export type ApprovalCategory = ToolApprovalCategory;
 
-export function approvalCategory(toolName: string): ApprovalCategory | undefined {
-  switch (classifyTool(toolName)) {
-    case ToolKind.FILE_WRITE:
-    case ToolKind.FILE_EDIT:
-      return "write";
-    case ToolKind.FILE_DELETE:
-      return "delete";
-    case ToolKind.SHELL:
-      return "shell";
-    default:
-      return undefined;
-  }
-}
+export const approvalCategory = toolApprovalCategory;
 
 /**
  * Human-readable approval-message template per canonical category. Keyed by
@@ -186,121 +173,3 @@ export function extractArgKey(args: Record<string, unknown> | undefined): string
   return "";
 }
 
-/**
- * Merge approval policies from all four levels into a single lookup map.
- *
- * Keys are the raw tool name (e.g., "apply_cloud_resource"). Each MCP server
- * contributes its own set of policies, so the map is keyed by
- * "serverSlug/toolName" to avoid collisions between servers.
- *
- * Policy chain (each level overrides the previous):
- * 1. status.toolApprovals — presence means "requires approval"
- * 2. spec.pinnedToolApprovals — presence means "requires approval" (overrides)
- * 3. agent tool_approval_overrides — explicit boolean per tool
- * 4. auto_approve_all — bypasses everything
- *
- * When auto_approve_all is true, the returned map is empty (no tool
- * requires approval).
- */
-export function mergeApprovalPolicies(
-  resolvedServers: ResolvedMcpServer[],
-  agentOverrides: ToolApprovalOverride[],
-  autoApproveAll: boolean,
-): Map<string, MergedToolPolicy> {
-  const merged = new Map<string, MergedToolPolicy>();
-
-  if (autoApproveAll) return merged;
-
-  for (const server of resolvedServers) {
-    const serverPolicies = new Map<string, { requiresApproval: boolean; message: string }>();
-
-    // Layer 1: system-generated defaults (presence = requires approval)
-    for (const policy of server.toolApprovals) {
-      if (!policy.toolName) continue;
-      serverPolicies.set(policy.toolName, {
-        requiresApproval: true,
-        message: policy.message || `Execute tool: ${policy.toolName}`,
-      });
-    }
-
-    // Layer 2: manual overrides (presence = requires approval, overrides layer 1)
-    for (const pinned of server.pinnedToolApprovals) {
-      if (!pinned.toolName) continue;
-      serverPolicies.set(pinned.toolName, {
-        requiresApproval: true,
-        message: pinned.message || serverPolicies.get(pinned.toolName)?.message || `Execute tool: ${pinned.toolName}`,
-      });
-    }
-
-    // Layer 3: per-agent overrides (explicit boolean, can enable or disable)
-    for (const override of agentOverrides) {
-      if (!override.toolName) continue;
-      const existing = serverPolicies.get(override.toolName);
-      if (existing) {
-        existing.requiresApproval = override.requiresApproval;
-        if (override.message) {
-          existing.message = override.message;
-        }
-      } else if (override.requiresApproval) {
-        serverPolicies.set(override.toolName, {
-          requiresApproval: true,
-          message: override.message || `Execute tool: ${override.toolName}`,
-        });
-      }
-    }
-
-    // Write merged policies into the result map
-    for (const [toolName, policy] of serverPolicies) {
-      if (!policy.requiresApproval) continue;
-      const key = `${server.slug}/${toolName}`;
-      merged.set(key, {
-        toolName,
-        mcpServerSlug: server.slug,
-        requiresApproval: true,
-        approvalMessage: policy.message,
-      });
-    }
-  }
-
-  return merged;
-}
-
-/**
- * Look up whether an MCP tool requires approval.
- *
- * @param toolName - The actual MCP tool name (e.g., "apply_cloud_resource")
- * @param mcpServerSlug - The MCP server slug (e.g., "planton")
- * @param policies - The merged policy map from mergeApprovalPolicies()
- * @returns The policy if approval is required, undefined if auto-approved
- */
-export function lookupMcpToolPolicy(
-  toolName: string,
-  mcpServerSlug: string,
-  policies: Map<string, MergedToolPolicy>,
-): MergedToolPolicy | undefined {
-  return policies.get(`${mcpServerSlug}/${toolName}`);
-}
-
-/**
- * Resolve {{args.field}} placeholders in an approval message using the
- * tool's actual arguments.
- *
- * Placeholder syntax matches the proto-documented format:
- * - {{args.field_name}} — replaced with the argument value
- * - {{tool_name}} — replaced with the tool name
- * - Missing fields are replaced with "<unknown>"
- */
-export function resolveApprovalMessage(
-  template: string,
-  toolName: string,
-  args: Record<string, unknown>,
-): string {
-  return template
-    .replace(/\{\{tool_name\}\}/g, toolName)
-    .replace(/\{\{args\.(\w+)\}\}/g, (_match, field: string) => {
-      const value = args[field];
-      if (value === undefined || value === null) return "<unknown>";
-      if (typeof value === "string") return value;
-      return JSON.stringify(value);
-    });
-}