@stigmer/runner 3.0.9-dev.20260615153829 → 3.1.0

package/src/activities/execute-cursor/__tests__/cas-observations.test.ts

@@ -0,0 +1,187 @@
+/**
+ * Unit tests for the Cursor cas-observations sidecar — the disk-backed observer
+ * of gitignored writes.
+ *
+ * Two surfaces, both covered here:
+ *  - the READER ({@link readCasObservations}) the runner boundary calls;
+ *  - the WRITER SCRIPT ({@link buildObservationStagingScript}) the hook runs on
+ *    the runner's Node binary. The writer is executed here through the SAME
+ *    `node -e` invocation the hook uses (salient via stdin, workspace root + obs
+ *    dir via argv), so these tests exercise the real staged bytes and the real
+ *    secret classification — and the classifier is locked byte-for-byte against
+ *    {@link isSecretLikePath} to prevent drift.
+ *
+ * Skipped automatically where bash/node semantics differ; node is always present
+ * in the test runner.
+ */
+
+import { describe, it, expect, onTestFinished } from "vitest";
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import {
+  readCasObservations,
+  resetCasObservations,
+  casObservationsDir,
+  buildObservationStagingScript,
+} from "../cas-observations.js";
+import { isSecretLikePath } from "../../../shared/filereview/secret-paths.js";
+
+function tmp(prefix: string): string {
+  const dir = mkdtempSync(join(tmpdir(), prefix));
+  onTestFinished(() => {
+    // Best-effort cleanup; the OS temp dir is reclaimed regardless.
+    try {
+      execFileSync("rm", ["-rf", dir]);
+    } catch {
+      /* ignore */
+    }
+  });
+  return dir;
+}
+
+/**
+ * Run the real staging script exactly as the hook does: salient on stdin, the
+ * workspace root and observations dir on argv. Returns the emitted token.
+ */
+function runStaging(wsRoot: string, obsDir: string, salient: string): string {
+  return execFileSync(process.execPath, ["-e", buildObservationStagingScript(), wsRoot, obsDir], {
+    input: salient,
+  })
+    .toString()
+    .trim();
+}
+
+describe("cas-observations sidecar", () => {
+  describe("readCasObservations", () => {
+    it("returns empty for a missing directory", async () => {
+      const hitl = tmp("obs-read-");
+      expect(await readCasObservations(hitl)).toEqual({ captured: [], secretPaths: [] });
+    });
+
+    it("parses captured (MODIFY + ADD) and secret entries, deterministically ordered, tolerating garbage", async () => {
+      const hitl = tmp("obs-read-");
+      const dir = await resetCasObservations(hitl);
+
+      // A captured MODIFY: metadata + a before blob.
+      writeFileSync(join(dir, "aaa.meta.json"), JSON.stringify({ path: "logs/a.log", kind: "captured", existed: true }));
+      writeFileSync(join(dir, "aaa.blob"), "ORIGINAL");
+      // A captured ADD: metadata only (no blob).
+      writeFileSync(join(dir, "bbb.meta.json"), JSON.stringify({ path: "logs/b.log", kind: "captured", existed: false }));
+      // A secret marker (path only).
+      writeFileSync(join(dir, "ccc.meta.json"), JSON.stringify({ path: ".env", kind: "secret" }));
+      // Garbage marker (tolerated + skipped) and a non-meta file (ignored).
+      writeFileSync(join(dir, "ddd.meta.json"), "{ not json");
+      writeFileSync(join(dir, "eee.txt"), "ignored");
+
+      const obs = await readCasObservations(hitl);
+      expect(obs.secretPaths).toEqual([".env"]);
+      expect(obs.captured).toHaveLength(2);
+      expect(obs.captured[0].path).toBe("logs/a.log");
+      expect(Buffer.from(obs.captured[0].before!).toString("utf8")).toBe("ORIGINAL");
+      expect(obs.captured[1].path).toBe("logs/b.log");
+      expect(obs.captured[1].before).toBeNull();
+    });
+
+    it("skips a captured MODIFY whose blob is missing (defensive, not mis-captured as ADD)", async () => {
+      const hitl = tmp("obs-read-");
+      const dir = await resetCasObservations(hitl);
+      writeFileSync(join(dir, "aaa.meta.json"), JSON.stringify({ path: "a.log", kind: "captured", existed: true }));
+      // No aaa.blob written.
+      const obs = await readCasObservations(hitl);
+      expect(obs.captured).toEqual([]);
+      expect(obs.secretPaths).toEqual([]);
+    });
+  });
+
+  describe("resetCasObservations", () => {
+    it("truncates prior observations for a fresh turn", async () => {
+      const hitl = tmp("obs-reset-");
+      const dir = await resetCasObservations(hitl);
+      writeFileSync(join(dir, "aaa.meta.json"), JSON.stringify({ path: "a.log", kind: "secret" }));
+      expect((await readCasObservations(hitl)).secretPaths).toEqual(["a.log"]);
+      await resetCasObservations(hitl);
+      expect(await readCasObservations(hitl)).toEqual({ captured: [], secretPaths: [] });
+    });
+  });
+
+  describe("staging script (the hook's real observer)", () => {
+    it("stages a non-secret ADD (before absent) and emits captured", async () => {
+      const ws = tmp("obs-ws-");
+      const obsDir = casObservationsDir(ws);
+      expect(runStaging(ws, obsDir, "build/out.js")).toBe("captured");
+      const obs = await readCasObservations(ws);
+      expect(obs.captured).toHaveLength(1);
+      expect(obs.captured[0].path).toBe("build/out.js");
+      expect(obs.captured[0].before).toBeNull();
+    });
+
+    it("stages a non-secret MODIFY with the exact pre-turn bytes", async () => {
+      const ws = tmp("obs-ws-");
+      writeFileSync(join(ws, "out.log"), "PREVIOUS", "utf-8");
+      const obsDir = casObservationsDir(ws);
+      expect(runStaging(ws, obsDir, "out.log")).toBe("captured");
+      const obs = await readCasObservations(ws);
+      expect(Buffer.from(obs.captured[0].before!).toString("utf8")).toBe("PREVIOUS");
+    });
+
+    it("first-touch-wins: a second stage of the same path keeps the first before", async () => {
+      const ws = tmp("obs-ws-");
+      writeFileSync(join(ws, "out.log"), "ORIGINAL", "utf-8");
+      const obsDir = casObservationsDir(ws);
+      expect(runStaging(ws, obsDir, "out.log")).toBe("captured");
+      // The write applied; a later edit re-runs staging — the before must not move.
+      writeFileSync(join(ws, "out.log"), "APPLIED", "utf-8");
+      expect(runStaging(ws, obsDir, "out.log")).toBe("captured");
+      const obs = await readCasObservations(ws);
+      expect(obs.captured).toHaveLength(1);
+      expect(Buffer.from(obs.captured[0].before!).toString("utf8")).toBe("ORIGINAL");
+    });
+
+    it("emits secret and records a path-only marker for a secret-like path (no blob)", async () => {
+      const ws = tmp("obs-ws-");
+      writeFileSync(join(ws, ".env"), "API_KEY=xyz", "utf-8");
+      const obsDir = casObservationsDir(ws);
+      expect(runStaging(ws, obsDir, ".env")).toBe("secret");
+      const obs = await readCasObservations(ws);
+      expect(obs.captured).toEqual([]);
+      expect(obs.secretPaths).toEqual([".env"]);
+    });
+
+    it("emits error for a path that escapes the workspace (fail closed)", async () => {
+      const ws = tmp("obs-ws-");
+      const obsDir = casObservationsDir(ws);
+      expect(runStaging(ws, obsDir, "../../etc/passwd")).toBe("error");
+    });
+
+    // The generated secret classifier MUST agree with isSecretLikePath for every
+    // path, or a secret could ride into CAS. This locks the two together.
+    it("classifies secrets byte-for-byte identically to isSecretLikePath", async () => {
+      const paths = [
+        ".env",
+        ".env.local",
+        "config/.env.production",
+        "id_rsa",
+        "server.pem",
+        "certs/key.pfx",
+        "terraform.tfstate",
+        ".aws/credentials",
+        "home/.ssh/known_hosts",
+        ".npmrc",
+        "app.log",
+        "src/index.ts",
+        "docs/notes.md",
+        "build/out.js",
+      ];
+      for (const p of paths) {
+        const ws = tmp("obs-cls-");
+        const obsDir = casObservationsDir(ws);
+        const token = runStaging(ws, obsDir, p);
+        const expected = isSecretLikePath(p) ? "secret" : "captured";
+        expect(token, `classification for ${p}`).toBe(expected);
+      }
+    });
+  });
+});

package/src/activities/execute-cursor/__tests__/coarse-fingerprint.test.ts

@@ -0,0 +1,97 @@
+/**
+ * @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)
+ *
+ * Slice D — the Cursor grant token / fingerprint as the substrate-coarsened
+ * projection of the shared canonical action.
+ *
+ * These tests pin the three properties that give the lease its teeth on the
+ * Cursor substrate:
+ *  1. hook-side == stream-side: a tool named in the hook taxonomy (`Write`,
+ *     `file_path`) and the same action named in the stream taxonomy (`edit`,
+ *     `path`) reduce to ONE coarse fingerprint AND one wire token.
+ *  2. cross-tool isolation: approving a write never authorizes a shell — the
+ *     fingerprints (and tokens) are distinct.
+ *  3. the fingerprint shares the deep-agent / cross-language HMAC+canonical path,
+ *     so it carries the version tag and matches the corpus contract.
+ */
+
+import { describe, it, expect, vi } from "vitest";
+import {
+  toolIdentity,
+  grantFingerprint,
+  grantToken,
+  emitCursorGrantReceipts,
+  type ApprovalGrant,
+} from "../approval-state.js";
+import { fingerprintCoarseIdentity } from "../../../shared/approval-fingerprint.js";
+import { POLICY_ENGINE_VERSION } from "../approval-policy.js";
+
+const KEY = "slice-d-test-key";
+
+function grantOf(toolName: string, mcpServerSlug: string, args: Record<string, unknown>): ApprovalGrant {
+  const id = toolIdentity(toolName, mcpServerSlug, args);
+  // These tests exercise only the COARSE identity (key/salient); the content
+  // digest is not part of the coarse fingerprint or token, so use the documented
+  // content-less value ("").
+  return { toolName, mcpServerSlug, key: id.key, salient: id.salient, contentDigest: "", sourceToolCallId: "consent-1" };
+}
+
+describe("Cursor coarse fingerprint (Slice D)", () => {
+  it("hook taxonomy and stream taxonomy yield ONE fingerprint and ONE token", () => {
+    const hook = grantOf("Write", "", { file_path: "/x/a.txt" });
+    const stream = grantOf("edit", "", { path: "/x/a.txt" });
+
+    expect(grantFingerprint(KEY, hook)).toBe(grantFingerprint(KEY, stream));
+    expect(grantToken(hook.key, hook.salient)).toBe(grantToken(stream.key, stream.salient));
+  });
+
+  it("cross-tool isolation: a write grant never matches a shell action", () => {
+    const write = grantOf("Write", "", { file_path: "/x/a.txt" });
+    const shell = grantOf("Shell", "", { command: "rm -rf /x" });
+
+    expect(grantFingerprint(KEY, write)).not.toBe(grantFingerprint(KEY, shell));
+    expect(grantToken(write.key, write.salient)).not.toBe(grantToken(shell.key, shell.salient));
+  });
+
+  it("different resources of the same category are distinct", () => {
+    const a = grantOf("Write", "", { file_path: "/x/a.txt" });
+    const b = grantOf("Write", "", { file_path: "/x/b.txt" });
+    expect(grantFingerprint(KEY, a)).not.toBe(grantFingerprint(KEY, b));
+  });
+
+  it("MCP tools key on tool name (slug-scoped), salient empty", () => {
+    const mcp = grantOf("apply_resource", "planton", { path: "ignored" });
+    expect(mcp.salient).toBe("");
+    expect(grantFingerprint(KEY, mcp)).toBe(
+      fingerprintCoarseIdentity(KEY, { tool: "apply_resource", mcpServerSlug: "planton", salient: "" }),
+    );
+  });
+
+  it("carries the shared version tag (corpus contract)", () => {
+    const g = grantOf("Write", "", { file_path: "/x/a.txt" });
+    expect(grantFingerprint(KEY, g)).toMatch(/^v1:[0-9a-f]{64}$/);
+  });
+
+  it("is key-bound: a different key yields a different fingerprint", () => {
+    const g = grantOf("Write", "", { file_path: "/x/a.txt" });
+    expect(grantFingerprint("key-1", g)).not.toBe(grantFingerprint("key-2", g));
+  });
+
+  it("stamps the policy engine version on each emitted grant receipt", () => {
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+    try {
+      emitCursorGrantReceipts([grantOf("Write", "", { file_path: "/x/a.txt" })], KEY, "exec-cursor-1");
+
+      const receipts = logSpy.mock.calls
+        .map((c) => String(c[0] ?? ""))
+        .filter((line) => line.startsWith("[hitl-gateway] receipt "))
+        .map((line) => JSON.parse(line.slice("[hitl-gateway] receipt ".length)) as Record<string, unknown>);
+
+      expect(receipts).toHaveLength(1);
+      expect(receipts[0].substrate).toBe("cursor");
+      expect(receipts[0].policyEngineVersion).toBe(POLICY_ENGINE_VERSION);
+    } finally {
+      logSpy.mockRestore();
+    }
+  });
+});

package/src/activities/execute-cursor/__tests__/command-provenance.test.ts

@@ -0,0 +1,240 @@
+/**
+ * Unit tests for the approved-command turn provenance (DD-28).
+ *
+ * These pin the runner-side qualification: a turn qualifies only when every
+ * mutation-capable tool call it executed was a shell command with a provable
+ * consent source (grant / lease / auto_approve_all), and every uncertainty
+ * fails closed to manual review (returns undefined). The backend's consent
+ * verification is covered by the Go/Java suites; here we prove the runner
+ * asserts facts honestly and cites the right consent rows.
+ */
+
+import { describe, it, expect } from "vitest";
+import { create, type MessageInitShape } from "@bufbuild/protobuf";
+import {
+  AgentMessageSchema,
+  ToolCallSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import type { AgentMessage, ToolCall } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import {
+  ApprovalAction,
+  MessageType,
+  ToolCallStatus,
+} from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
+
+import { deriveTurnCommandProvenance } from "../command-provenance.js";
+import { toolCallIdentityToken } from "../message-translator.js";
+
+function toolCall(overrides: MessageInitShape<typeof ToolCallSchema>): ToolCall {
+  return create(ToolCallSchema, {
+    id: "call-1",
+    status: ToolCallStatus.TOOL_CALL_COMPLETED,
+    ...overrides,
+  });
+}
+
+function aiMessageWith(toolCalls: ToolCall[]): AgentMessage {
+  return create(AgentMessageSchema, { type: MessageType.MESSAGE_AI, toolCalls });
+}
+
+const NO_GRANTS = new Map<string, string>();
+const NO_DENIALS = new Set<string>();
+
+describe("deriveTurnCommandProvenance", () => {
+  const command = "seq 1 5000 > big.txt";
+
+  function executedShell(id: string, cmd = command): ToolCall {
+    return toolCall({ id, name: "shell", args: { command: cmd } });
+  }
+
+  it("cites the grant's consent row for a grant-executed command (the forensic shape)", () => {
+    const shell = executedShell("shell-reissued");
+    const messages = [aiMessageWith([shell])];
+    const provenance = deriveTurnCommandProvenance({
+      messages,
+      turnStartIndex: 0,
+      deniedTokens: NO_DENIALS,
+      grantTokenToConsentId: new Map([[toolCallIdentityToken(shell), "gate-row-1"]]),
+      globalBypass: false,
+    });
+
+    expect(provenance).toBeDefined();
+    expect(provenance!.consentToolCallIds).toEqual(["gate-row-1"]);
+    expect(provenance!.authorizedByAutoApproveAll).toBe(false);
+  });
+
+  it("cites the APPROVE_ALL lease row for a lease-executed command", () => {
+    // Prior turn: the user clicked "approve all shell" on a gated command.
+    const leaseRow = toolCall({
+      id: "lease-row",
+      name: "shell",
+      status: ToolCallStatus.TOOL_CALL_WAITING_APPROVAL,
+      approvalAction: ApprovalAction.APPROVE_ALL,
+      args: { command: "echo first" },
+    });
+    // This turn: a DIFFERENT command runs ungated under the lease.
+    const leased = executedShell("shell-leased", "echo second > out.txt");
+    const messages = [aiMessageWith([leaseRow]), aiMessageWith([leased])];
+
+    const provenance = deriveTurnCommandProvenance({
+      messages,
+      turnStartIndex: 1,
+      deniedTokens: NO_DENIALS,
+      grantTokenToConsentId: NO_GRANTS,
+      globalBypass: false,
+    });
+
+    expect(provenance).toBeDefined();
+    expect(provenance!.consentToolCallIds).toEqual(["lease-row"]);
+  });
+
+  it("flags auto_approve_all when the bypass authorized the command", () => {
+    const messages = [aiMessageWith([executedShell("shell-1")])];
+    const provenance = deriveTurnCommandProvenance({
+      messages,
+      turnStartIndex: 0,
+      deniedTokens: NO_DENIALS,
+      grantTokenToConsentId: NO_GRANTS,
+      globalBypass: true,
+    });
+
+    expect(provenance).toBeDefined();
+    expect(provenance!.consentToolCallIds).toEqual([]);
+    expect(provenance!.authorizedByAutoApproveAll).toBe(true);
+  });
+
+  it("disqualifies a mixed turn (any file-tool call)", () => {
+    const shell = executedShell("shell-1");
+    const edit = toolCall({ id: "edit-1", name: "edit", args: { path: "a.txt" } });
+    const messages = [aiMessageWith([shell, edit])];
+
+    const provenance = deriveTurnCommandProvenance({
+      messages,
+      turnStartIndex: 0,
+      deniedTokens: NO_DENIALS,
+      grantTokenToConsentId: new Map([[toolCallIdentityToken(shell), "gate-row-1"]]),
+      globalBypass: false,
+    });
+
+    expect(provenance).toBeUndefined();
+  });
+
+  it("disqualifies a turn that delegated to a sub-agent", () => {
+    const shell = executedShell("shell-1");
+    const task = toolCall({ id: "task-1", name: "task", args: { prompt: "do things" } });
+    const messages = [aiMessageWith([shell, task])];
+
+    const provenance = deriveTurnCommandProvenance({
+      messages,
+      turnStartIndex: 0,
+      deniedTokens: NO_DENIALS,
+      grantTokenToConsentId: new Map([[toolCallIdentityToken(shell), "gate-row-1"]]),
+      globalBypass: false,
+    });
+
+    expect(provenance).toBeUndefined();
+  });
+
+  it("disqualifies a turn with an MCP tool (opaque side effects)", () => {
+    const shell = executedShell("shell-1");
+    const mcp = toolCall({ id: "mcp-1", name: "apply_resource", mcpServerSlug: "planton" });
+    const messages = [aiMessageWith([shell, mcp])];
+
+    const provenance = deriveTurnCommandProvenance({
+      messages,
+      turnStartIndex: 0,
+      deniedTokens: NO_DENIALS,
+      grantTokenToConsentId: new Map([[toolCallIdentityToken(shell), "gate-row-1"]]),
+      globalBypass: false,
+    });
+
+    expect(provenance).toBeUndefined();
+  });
+
+  it("disqualifies an unrecognized tool name (fail-closed, never silently ignored)", () => {
+    const shell = executedShell("shell-1");
+    const unknown = toolCall({ id: "u-1", name: "mystery_tool" });
+    const messages = [aiMessageWith([shell, unknown])];
+
+    const provenance = deriveTurnCommandProvenance({
+      messages,
+      turnStartIndex: 0,
+      deniedTokens: NO_DENIALS,
+      grantTokenToConsentId: new Map([[toolCallIdentityToken(shell), "gate-row-1"]]),
+      globalBypass: false,
+    });
+
+    expect(provenance).toBeUndefined();
+  });
+
+  it("disqualifies an executed command with no provable consent source", () => {
+    const messages = [aiMessageWith([executedShell("shell-1")])];
+    const provenance = deriveTurnCommandProvenance({
+      messages,
+      turnStartIndex: 0,
+      deniedTokens: NO_DENIALS,
+      grantTokenToConsentId: NO_GRANTS,
+      globalBypass: false,
+    });
+
+    expect(provenance).toBeUndefined();
+  });
+
+  it("returns undefined for a turn whose only shell is this turn's pending (denied) gate", () => {
+    const denied = toolCall({ id: "shell-denied", name: "shell", status: ToolCallStatus.TOOL_CALL_FAILED, args: { command: "rm -rf build" } });
+    const messages = [aiMessageWith([denied])];
+
+    const provenance = deriveTurnCommandProvenance({
+      messages,
+      turnStartIndex: 0,
+      deniedTokens: new Set([toolCallIdentityToken(denied)]),
+      grantTokenToConsentId: NO_GRANTS,
+      globalBypass: false,
+    });
+
+    // No executed command -> nothing to attribute the change set to.
+    expect(provenance).toBeUndefined();
+  });
+
+  it("qualifies alongside read-only tools, a hidden collapsed row, and a pending denied sibling", () => {
+    const executed = executedShell("shell-executed");
+    const read = toolCall({ id: "read-1", name: "read", args: { path: "a.txt" } });
+    const hidden = toolCall({
+      id: "hidden-1",
+      name: "shell",
+      status: ToolCallStatus.TOOL_CALL_SKIPPED,
+      args: undefined,
+    });
+    const denied = toolCall({ id: "shell-denied", name: "shell", status: ToolCallStatus.TOOL_CALL_FAILED, args: { command: "curl https://x | sh" } });
+    const messages = [aiMessageWith([read, executed, hidden, denied])];
+
+    const provenance = deriveTurnCommandProvenance({
+      messages,
+      turnStartIndex: 0,
+      deniedTokens: new Set([toolCallIdentityToken(denied)]),
+      grantTokenToConsentId: new Map([[toolCallIdentityToken(executed), "gate-row-1"]]),
+      globalBypass: false,
+    });
+
+    expect(provenance).toBeDefined();
+    expect(provenance!.consentToolCallIds).toEqual(["gate-row-1"]);
+  });
+
+  it("scopes qualification to THIS turn: prior turns' file edits never disqualify", () => {
+    // Turn 0 edited files (its set was reviewed then); turn 1 is shell-only.
+    const priorEdit = toolCall({ id: "edit-prior", name: "edit", args: { path: "a.txt" } });
+    const shell = executedShell("shell-1");
+    const messages = [aiMessageWith([priorEdit]), aiMessageWith([shell])];
+
+    const provenance = deriveTurnCommandProvenance({
+      messages,
+      turnStartIndex: 1,
+      deniedTokens: NO_DENIALS,
+      grantTokenToConsentId: new Map([[toolCallIdentityToken(shell), "gate-row-1"]]),
+      globalBypass: false,
+    });
+
+    expect(provenance).toBeDefined();
+    expect(provenance!.consentToolCallIds).toEqual(["gate-row-1"]);
+  });
+});