@stigmer/runner 3.0.9-dev.20260616060535 → 3.1.0

package/dist/workflows/connect-mcp-server.js

@@ -29,6 +29,115 @@ function classifyWithTimeout(numTools) {
     });
 }
 // ─────────────────────────────────────────────────────────────────────────────
+// Incremental classification planner (pure, deterministic, sandbox-safe)
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Canonical, order-stable signature of a single tool's definition.
+ *
+ * Mirrors the shape `toolsFingerprint` hashes (name + description + input_schema)
+ * so "unchanged" here means the same thing it means for the whole-server
+ * fingerprint. Uses only JSON — no `node:crypto` — so it is safe to call from
+ * inside the Temporal deterministic V8 isolate.
+ */
+function toolSignature(tool) {
+    return JSON.stringify({
+        name: tool.name,
+        description: tool.description,
+        input_schema: tool.inputSchema ?? null,
+    });
+}
+/**
+ * Partition the freshly discovered tools into those that must be classified and
+ * the prior approval decisions that can be carried forward verbatim.
+ *
+ * Reuse is **content-addressed**: a prior decision is kept only when a tool's
+ * name AND full definition are byte-identical to the previous connect. This is
+ * deliberately stricter than reusing by name alone — a tool can keep its name
+ * while its schema changes from benign to destructive, and such a tool MUST be
+ * re-evaluated rather than left with a stale "auto-approve". Tools that are
+ * unchanged are never re-classified (stable, deterministic, no LLM cost; no
+ * flapping for borderline tools), and a tool present last time but gone now is
+ * simply absent from both outputs (dropped).
+ *
+ * The previous approval list is a presence-set of *gated* tools (a tool in
+ * `previousToolApprovals` requires approval; a known tool absent from it was
+ * auto-approved). So a reused tool emits a carried-forward entry only when it
+ * was gated; reused auto-approved tools emit nothing, which correctly keeps them
+ * un-gated. `ClassifyToolApprovals` likewise returns only gated entries, so the
+ * union `[...carriedForward, ...classified]` is the complete gated set.
+ *
+ * Pure and free of Temporal APIs so it can be exhaustively unit-tested and is
+ * safe to evaluate inside the workflow sandbox.
+ */
+export function planIncrementalClassification(previousTools, previousToolApprovals, currentTools) {
+    const prevSigByName = new Map();
+    for (const tool of previousTools) {
+        prevSigByName.set(tool.name, toolSignature(tool));
+    }
+    const prevGatedByName = new Map();
+    for (const approval of previousToolApprovals) {
+        prevGatedByName.set(approval.toolName, approval);
+    }
+    const toolsToClassify = [];
+    const carriedForward = [];
+    for (const tool of currentTools) {
+        const prevSig = prevSigByName.get(tool.name);
+        const unchanged = prevSig !== undefined && prevSig === toolSignature(tool);
+        if (!unchanged) {
+            toolsToClassify.push(tool);
+            continue;
+        }
+        const gated = prevGatedByName.get(tool.name);
+        if (gated) {
+            carriedForward.push({
+                tool_name: gated.toolName,
+                requires_approval: true,
+                message: gated.message,
+            });
+        }
+        // An unchanged tool that was not gated stays auto-approved — emit nothing.
+    }
+    return { toolsToClassify, carriedForward };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// destructiveHint fail-closed tightener (pure, deterministic, sandbox-safe)
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Force-gate any tool whose live MCP annotation declares `destructiveHint:true`
+ * but that the classifier (or carry-forward) left un-gated.
+ *
+ * This is the ONLY way annotations influence policy, and it is deliberately
+ * one-directional. The MCP spec warns that clients must never make tool-use
+ * decisions on annotations from untrusted servers; trusting a server's
+ * "I am destructive" claim only ever ADDS an approval prompt (the safe
+ * direction), so it cannot be abused. The inverse — trusting `readOnlyHint` to
+ * AUTO-APPROVE — is exactly the unsafe direction the spec forbids, so a spoofed
+ * `readOnlyHint:true` on a destructive tool must never relax it. Read-only
+ * auto-approval authority lives solely with the trusted LLM classifier.
+ *
+ * Recomputed from live discovery on every connect, so it has zero coupling to
+ * `toolSignature`/incremental reuse and needs no persistence. Pure JS so it is
+ * safe to evaluate inside the Temporal deterministic isolate.
+ */
+export function applyDestructiveHintTightener(gated, currentTools) {
+    const gatedNames = new Set(gated.map((g) => g.tool_name));
+    const tightened = [...gated];
+    let addedCount = 0;
+    for (const tool of currentTools) {
+        if (tool.annotations?.destructiveHint === true && !gatedNames.has(tool.name)) {
+            tightened.push({
+                tool_name: tool.name,
+                requires_approval: true,
+                message: `Execute ${tool.name}`,
+                from_destructive_hint: true,
+            });
+            gatedNames.add(tool.name);
+            addedCount++;
+        }
+    }
+    return { tightened, addedCount };
+}
+// ─────────────────────────────────────────────────────────────────────────────
 // ConnectMcpServerWorkflow — primary connect flow
 // ─────────────────────────────────────────────────────────────────────────────
 export async function connectMcpServer(input) {
@@ -37,23 +146,22 @@ export async function connectMcpServer(input) {
         executionContextId: input.execution_context_id ?? null,
         invokerIdentityAccountId: input.invoker_identity_account_id ?? null,
     });
-    const canReusePreviousApprovals = discovery.newToolsFingerprint !== "" &&
-        discovery.newToolsFingerprint === discovery.previousToolsFingerprint &&
-        discovery.previousToolApprovals.length > 0;
+    // Content-addressed incremental classification: reuse prior decisions for
+    // tools whose definition is unchanged, and classify only the new or changed
+    // ones. Keeps decisions stable/deterministic across reconnects and avoids
+    // redundant LLM calls, while still re-evaluating a tool whose schema changed.
+    const { toolsToClassify, carriedForward } = planIncrementalClassification(discovery.previousTools, discovery.previousToolApprovals, discovery.tools);
     let toolApprovals;
-    if (canReusePreviousApprovals) {
-        log.info(`Tools unchanged for '${input.mcp_server_id}' ` +
-            `(fingerprint ${discovery.newToolsFingerprint.slice(0, 12)}) — ` +
-            `reusing ${discovery.previousToolApprovals.length} previous approval(s)`);
-        toolApprovals = discovery.previousToolApprovals.map((a) => ({
-            tool_name: a.toolName,
-            requires_approval: a.requiresApproval,
-            message: a.message,
-        }));
+    if (toolsToClassify.length === 0) {
+        log.info(`Tools unchanged for '${input.mcp_server_id}' — reusing ` +
+            `${carriedForward.length} previous approval(s), no classification needed`);
+        toolApprovals = carriedForward;
     }
     else {
+        log.info(`Classifying ${toolsToClassify.length} new/changed tool(s) for ` +
+            `'${input.mcp_server_id}', reusing ${carriedForward.length} prior decision(s)`);
         const classifyInput = {
-            tools: discovery.tools.map((t) => ({
+            tools: toolsToClassify.map((t) => ({
                 name: t.name,
                 description: t.description,
                 input_schema: t.inputSchema ?? null,
@@ -62,9 +170,22 @@ export async function connectMcpServer(input) {
             serverDescription: "",
             mcpServerId: input.mcp_server_id,
         };
-        const classify = classifyWithTimeout(discovery.tools.length);
-        toolApprovals = await classify.ClassifyToolApprovals(classifyInput);
+        const classify = classifyWithTimeout(toolsToClassify.length);
+        const classified = await classify.ClassifyToolApprovals(classifyInput);
+        toolApprovals = [...carriedForward, ...classified];
+    }
+    // Fail-closed tightener over the FULL live tool set: a tool the server's own
+    // annotation marks destructiveHint=true is force-gated if it slipped through
+    // un-gated. Runs on live discovery (not the reused/classified subset), so it
+    // also re-asserts gating for carried-forward tools whose server later flips a
+    // tool to destructive. We never trust readOnlyHint to relax — see the
+    // tightener's contract for the MCP untrusted-hints rationale.
+    const { tightened, addedCount } = applyDestructiveHintTightener(toolApprovals, discovery.tools);
+    if (addedCount > 0) {
+        log.info(`Force-gated ${addedCount} tool(s) via destructiveHint annotation for ` +
+            `'${input.mcp_server_id}'`);
     }
+    toolApprovals = tightened;
     return {
         tools: discovery.tools.map((t) => ({
             name: t.name,

package/dist/workflows/connect-mcp-server.js.map

@@ -1 +1 @@
-{"version":3,"file":"connect-mcp-server.js","sourceRoot":"","sources":["../../src/workflows/connect-mcp-server.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,eAAe,EAAE,GAAG,EAAE,MAAM,sBAAsB,CAAC;AAkB5D,MAAM,QAAQ,GAAG,eAAe,CAAqB;IACnD,mBAAmB,EAAE,MAAM;IAC3B,gBAAgB,EAAE,KAAK;IACvB,KAAK,EAAE,EAAE,eAAe,EAAE,CAAC,EAAE;CAC9B,CAAC,CAAC;AAEH,SAAS,mBAAmB,CAAC,QAAgB;IAC3C,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,QAAQ,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,CAAC,CAAC;IACvE,OAAO,eAAe,CAAqB;QACzC,mBAAmB,EAAE,GAAG,UAAU,GAAG;QACrC,KAAK,EAAE,EAAE,eAAe,EAAE,CAAC,EAAE;KAC9B,CAAC,CAAC;AACL,CAAC;AAED,gFAAgF;AAChF,kDAAkD;AAClD,gFAAgF;AAEhF,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,KAAoC;IAEpC,MAAM,SAAS,GAAG,MAAM,QAAQ,CAAC,6BAA6B,CAAC;QAC7D,WAAW,EAAE,KAAK,CAAC,aAAa;QAChC,kBAAkB,EAAE,KAAK,CAAC,oBAAoB,IAAI,IAAI;QACtD,wBAAwB,EAAE,KAAK,CAAC,2BAA2B,IAAI,IAAI;KACpE,CAAC,CAAC;IAEH,MAAM,yBAAyB,GAC7B,SAAS,CAAC,mBAAmB,KAAK,EAAE;QACpC,SAAS,CAAC,mBAAmB,KAAK,SAAS,CAAC,wBAAwB;QACpE,SAAS,CAAC,qBAAqB,CAAC,MAAM,GAAG,CAAC,CAAC;IAE7C,IAAI,aAIF,CAAC;IAEH,IAAI,yBAAyB,EAAE,CAAC;QAC9B,GAAG,CAAC,IAAI,CACN,wBAAwB,KAAK,CAAC,aAAa,IAAI;YAC7C,gBAAgB,SAAS,CAAC,mBAAmB,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM;YAChE,WAAW,SAAS,CAAC,qBAAqB,CAAC,MAAM,uBAAuB,CAC3E,CAAC;QAEF,aAAa,GAAG,SAAS,CAAC,qBAAqB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YAC1D,SAAS,EAAE,CAAC,CAAC,QAAQ;YACrB,iBAAiB,EAAE,CAAC,CAAC,gBAAgB;YACrC,OAAO,EAAE,CAAC,CAAC,OAAO;SACnB,CAAC,CAAC,CAAC;IACN,CAAC;SAAM,CAAC;QACN,MAAM,aAAa,GAAG;YACpB,KAAK,EAAE,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBACjC,IAAI,EAAE,CAAC,CAAC,IAAI;gBACZ,WAAW,EAAE,CAAC,CAAC,WAAW;gBAC1B,YAAY,EAAE,CAAC,CAAC,WAAW,IAAI,IAAI;aACpC,CAAC,CAAC;YACH,UAAU,EAAE,KAAK,CAAC,aAAa;YAC/B,iBAAiB,EAAE,EAAE;YACrB,WAAW,EAAE,KAAK,CAAC,aAAa;SACjC,CAAC;QAEF,MAAM,QAAQ,GAAG,mBAAmB,CAAC,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAC7D,aAAa,GAAG,MAAM,QAAQ,CAAC,qBAAqB,CAAC,aAAa,CAAC,CAAC;IACtE,CAAC;IAED,OAAO;QACL,KAAK,EAAE,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACjC,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,WAAW,EAAE,CAAC,CAAC,WAAW;YAC1B,YAAY,EAAE,CAAC,CAAC,WAAW,IAAI,IAAI;SACpC,CAAC,CAAC;QACH,kBAAkB,EAAE,SAAS,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;YAC3D,YAAY,EAAE,EAAE,CAAC,WAAW;YAC5B,IAAI,EAAE,EAAE,CAAC,IAAI;YACb,WAAW,EAAE,EAAE,CAAC,WAAW;YAC3B,SAAS,EAAE,EAAE,CAAC,QAAQ;SACvB,CAAC,CAAC;QACH,cAAc,EAAE,aAAa;KAC9B,CAAC;AACJ,CAAC;AAED,gFAAgF;AAChF,iEAAiE;AACjE,gFAAgF;AAEhF,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,KAAoC;IAEpC,MAAM,SAAS,GAAG,MAAM,QAAQ,CAAC,6BAA6B,CAAC;QAC7D,WAAW,EAAE,KAAK,CAAC,aAAa;QAChC,kBAAkB,EAAE,KAAK,CAAC,oBAAoB,IAAI,IAAI;QACtD,wBAAwB,EAAE,KAAK,CAAC,2BAA2B,IAAI,IAAI;KACpE,CAAC,CAAC;IAEH,OAAO;QACL,KAAK,EAAE,SAAS,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACjC,IAAI,EAAE,CAAC,CAAC,IAAI;YACZ,WAAW,EAAE,CAAC,CAAC,WAAW;YAC1B,YAAY,EAAE,CAAC,CAAC,WAAW,IAAI,IAAI;SACpC,CAAC,CAAC;QACH,kBAAkB,EAAE,SAAS,CAAC,iBAAiB,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;YAC3D,YAAY,EAAE,EAAE,CAAC,WAAW;YAC5B,IAAI,EAAE,EAAE,CAAC,IAAI;YACb,WAAW,EAAE,EAAE,CAAC,WAAW;YAC3B,SAAS,EAAE,EAAE,CAAC,QAAQ;SACvB,CAAC,CAAC;QACH,0BAA0B,EAAE,SAAS,CAAC,wBAAwB;QAC9D,uBAAuB,EAAE,SAAS,CAAC,qBAAqB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACnE,SAAS,EAAE,CAAC,CAAC,QAAQ;YACrB,iBAAiB,EAAE,CAAC,CAAC,gBAAgB;YACrC,OAAO,EAAE,CAAC,CAAC,OAAO;SACnB,CAAC,CAAC;QACH,qBAAqB,EAAE,SAAS,CAAC,mBAAmB;KACrD,CAAC;AACJ,CAAC"}
+{"version":3,"file":"connect-mcp-server.js","sourceRoot":"","sources":["../../src/workflows/connect-mcp-server.ts"],"names":[],"mappings":"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"}

package/dist/workflows/types.d.ts

@@ -36,6 +36,14 @@ export interface WireToolApproval {
     tool_name: string;
     requires_approval: boolean;
     message: string;
+    /**
+     * True when the connect-time destructiveHint tightener force-gated this tool
+     * (see applyDestructiveHintTightener). Persisted to
+     * ToolApprovalPolicy.from_destructive_hint so the runner attributes the gate to
+     * the annotation rather than the classifier. Omitted on classifier/pinned
+     * entries.
+     */
+    from_destructive_hint?: boolean;
 }
 export interface DiscoverMcpServerWorkflowOutput {
     tools: WireToolResult[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stigmer/runner",
-  "version": "3.0.9-dev.20260616060535",
+  "version": "3.1.0",
   "description": "Embeddable Temporal worker for the Stigmer AI agent platform — handles agent execution, workflow orchestration, and MCP server management",
   "license": "Apache-2.0",
   "type": "module",
@@ -86,7 +86,7 @@
     "@opentelemetry/resources": "^2.0.0",
     "@opentelemetry/sdk-trace-base": "^2.0.0",
     "@opentelemetry/sdk-trace-node": "^2.0.0",
-    "@stigmer/protos": "3.0.9-dev.20260616060535",
+    "@stigmer/protos": "3.1.0",
     "@temporalio/activity": "^1.11.0",
     "@temporalio/client": "^1.11.0",
     "@temporalio/common": "^1.11.0",

package/src/__test-utils__/approval-contract/contract.ts

@@ -0,0 +1,224 @@
+/**
+ * The HITL gateway P0 safety contract — the single authoritative statement of
+ * "these are THE tool-approval safety invariants, and every enforcement
+ * substrate must satisfy them."
+ *
+ * {@link describeGatewayContract} runs the invariants below against any
+ * {@link GatewaySubstrate}; {@link describeCrossSubstrateAgreement} proves the
+ * substrates reach the SAME decision for the SAME logical action. Both drive real
+ * production code through thin adapters, so reverting any P0 behavior fails here.
+ *
+ * ── Canonical P0 invariant catalog ──────────────────────────────────────────
+ *  1. No side effect without a backing authorization (the umbrella the rest serve).
+ *  2. approve            → executes exactly once (count asserted where observable).
+ *  3. reject             → never executes.
+ *  4. skip               → never executes.
+ *  5. unknown decision   → never executes (fail-closed on an unrecognized verdict).
+ *  6. mutating built-in, no explicit approval → gated (fail-closed BY CATEGORY,
+ *     so a brand-new mutating tool is gated by default, not allow-listed).
+ *  7. read-only / non-mutating built-in       → executes with no gate.
+ *  8. auto-approved MCP tool                   → executes with no gate.
+ *  9. cross-tool isolation: approving a write never authorizes a shell
+ *     (capability: enforcesExactResource).
+ * 10. exact-resource: approving write /a never authorizes write /b
+ *     (capability: enforcesExactResource).
+ * 11. class-lease isolation: APPROVE_ALL on class A auto-approves later class-A
+ *     actions but never class B (capability: appliesRunLifetimeLease).
+ *
+ * Capability-gated invariants (9, 10, 11) run only where the substrate supports
+ * the relevant lease; the "executes exactly once" count in (2) is asserted only
+ * where the substrate observes execution. Differences are gated, never forked —
+ * the same philosophy as the conformance suite's CapabilityFlags.
+ */
+
+import { describe, it, expect } from "vitest";
+import type { GatewayDecision, GatewaySubstrate, ProposedAction } from "./types.js";
+
+/** Representative actions shared by the per-substrate and cross-substrate suites. */
+const WRITE_A: ProposedAction = { kind: "write", resource: "/work/alpha.txt" };
+const WRITE_B: ProposedAction = { kind: "write", resource: "/work/beta.txt" };
+// Same file as WRITE_A, DIFFERENT content — the sibling-isolation probe (a
+// second distinct edit to an already-approved file must re-gate).
+const WRITE_A_V2: ProposedAction = { kind: "write", resource: "/work/alpha.txt", content: "a different body" };
+const SHELL: ProposedAction = { kind: "shell", resource: "rm -rf build" };
+const DELETE: ProposedAction = { kind: "delete", resource: "/work/gamma.txt" };
+const READ: ProposedAction = { kind: "read", resource: "/work/alpha.txt" };
+const MCP: ProposedAction = {
+  kind: "mcp",
+  resource: "",
+  mcpServerSlug: "github",
+  mcpToolName: "search_issues",
+};
+
+/**
+ * Register the P0 safety invariants against one substrate. The suite is skipped
+ * (not failed) when the substrate is unavailable in this environment.
+ */
+export function describeGatewayContract(substrate: GatewaySubstrate): void {
+  const suite = substrate.available ? describe : describe.skip;
+
+  suite(`gateway contract — ${substrate.name}`, () => {
+    // Invariants 1 + 6: a mutating built-in with no backing authorization is
+    // gated and does not execute (fail-closed by category, every category).
+    it("gates every mutating built-in with no backing authorization", async () => {
+      for (const action of [WRITE_A, SHELL, DELETE]) {
+        const outcome = await substrate.authorize(action, "none");
+        expect(outcome.gated, `${substrate.name}: ${action.kind} must be gated without an authorization`).toBe(true);
+        expect(outcome.executed, `${substrate.name}: ${action.kind} must NOT execute without an authorization`).toBe(false);
+      }
+    });
+
+    // Invariant 2: approve → executes exactly once (count asserted where observable).
+    it("executes a mutating built-in exactly once after approve", async () => {
+      const outcome = await substrate.authorize(WRITE_A, "approve");
+      expect(outcome.executed, `${substrate.name}: an approved write must execute`).toBe(true);
+      if (substrate.capabilities.observesExecution) {
+        expect(outcome.executionCount, `${substrate.name}: an approved write must execute exactly once`).toBe(1);
+      }
+    });
+
+    // Invariants 3, 4, 5: no non-approving verdict may execute.
+    for (const decision of ["reject", "skip", "unknown"] as const) {
+      it(`never executes after a ${decision} decision`, async () => {
+        const outcome = await substrate.authorize(WRITE_A, decision);
+        expect(outcome.executed, `${substrate.name}: a ${decision}-ed write must never execute`).toBe(false);
+      });
+    }
+
+    // Invariant 1 (provenance corollary): every side effect the gate withholds
+    // carries a non-UNSPECIFIED authorization provenance — so an authorized side
+    // effect is always auditable to the policy layer that governed it. Gated to
+    // substrates that decide the source at the gate (the deep-agent gate); the
+    // Cursor substrate projects provenance at reconstruction time and is covered
+    // by the message-translator + corpus suites.
+    if (substrate.capabilities.surfacesGatePolicySource) {
+      it("tags every gated side effect with a non-UNSPECIFIED policy source", async () => {
+        for (const action of [WRITE_A, SHELL, DELETE]) {
+          const outcome = await substrate.authorize(action, "none");
+          expect(outcome.gated, `${substrate.name}: ${action.kind} must be gated`).toBe(true);
+          expect(
+            outcome.policySource,
+            `${substrate.name}: a gated ${action.kind} must carry a policy source`,
+          ).toBeTruthy();
+          expect(
+            outcome.policySource,
+            `${substrate.name}: a gated ${action.kind}'s source must not be UNSPECIFIED`,
+          ).not.toBe("unspecified");
+        }
+      });
+    }
+
+    // Invariant 7: a non-mutating built-in runs without a gate.
+    it("executes a non-mutating built-in without a gate", async () => {
+      const outcome = await substrate.authorize(READ, "none");
+      expect(outcome.gated, `${substrate.name}: a read must not be gated`).toBe(false);
+      expect(outcome.executed, `${substrate.name}: a read must execute`).toBe(true);
+    });
+
+    // Invariant 8: an auto-approved MCP tool runs without a gate.
+    it("executes an auto-approved MCP tool without a gate", async () => {
+      const outcome = await substrate.authorize(MCP, "none");
+      expect(outcome.gated, `${substrate.name}: an auto-approved MCP tool must not be gated`).toBe(false);
+      expect(outcome.executed, `${substrate.name}: an auto-approved MCP tool must execute`).toBe(true);
+    });
+
+    // Invariants 9, 10: lease isolation — only meaningful where the substrate
+    // binds the exact resource. Gated honestly rather than asserted everywhere.
+    if (substrate.capabilities.enforcesExactResource && substrate.authorizeAfterGrant) {
+      const afterGrant = substrate.authorizeAfterGrant.bind(substrate);
+
+      it("honors a grant only for the exact approved resource (invariant 10)", async () => {
+        const sameResource = await afterGrant(WRITE_A, WRITE_A);
+        expect(sameResource.executed, `${substrate.name}: the exact granted resource must be allowed`).toBe(true);
+
+        const otherResource = await afterGrant(WRITE_A, WRITE_B);
+        expect(otherResource.executed, `${substrate.name}: a different resource must be re-gated, not allowed`).toBe(false);
+      });
+
+      it("never lets one tool's approval authorize another tool (invariant 9)", async () => {
+        const crossTool = await afterGrant(WRITE_A, SHELL);
+        expect(crossTool.executed, `${substrate.name}: approving a write must never authorize a shell`).toBe(false);
+      });
+    }
+
+    // Invariant 12: content-exact isolation — approving ONE edit to a file never
+    // authorizes a DIFFERENT edit to the SAME file (the deny-only "sibling hole").
+    // Only meaningful where the grant binds content; gated, never forked.
+    if (substrate.capabilities.enforcesExactContent && substrate.authorizeAfterGrant) {
+      const afterGrant = substrate.authorizeAfterGrant.bind(substrate);
+
+      it("honors a grant only for the exact approved content (invariant 12: sibling isolation)", async () => {
+        const sameContent = await afterGrant(WRITE_A, WRITE_A);
+        expect(sameContent.executed, `${substrate.name}: re-issuing the exact approved edit must be allowed`).toBe(true);
+
+        const otherContent = await afterGrant(WRITE_A, WRITE_A_V2);
+        expect(otherContent.executed, `${substrate.name}: a DIFFERENT edit to the same file must re-gate`).toBe(false);
+      });
+    }
+
+    // Invariant 11: a run-lifetime CLASS lease (APPROVE_ALL) auto-approves later
+    // actions of the SAME class but never a different class — the core Phase-7
+    // scoped-lease safety property, enforced independently on each substrate (the
+    // gate clears leased categories; the hook reads leasedCategories).
+    if (substrate.capabilities.appliesRunLifetimeLease && substrate.authorizeUnderClassLease) {
+      const underLease = substrate.authorizeUnderClassLease.bind(substrate);
+
+      it("a class lease auto-approves that class and ONLY that class (invariant 11)", async () => {
+        // Lease "write": a later write of a DIFFERENT resource runs ungated...
+        const sameClass = await underLease(WRITE_A, WRITE_B);
+        expect(sameClass.executed, `${substrate.name}: a write lease must auto-approve another write`).toBe(true);
+
+        // ...but later actions of OTHER classes are still gated, never leaked.
+        const shellUnderWrite = await underLease(WRITE_A, SHELL);
+        expect(shellUnderWrite.executed, `${substrate.name}: a write lease must NOT authorize a shell`).toBe(false);
+
+        const deleteUnderWrite = await underLease(WRITE_A, DELETE);
+        expect(deleteUnderWrite.executed, `${substrate.name}: a write lease must NOT authorize a delete`).toBe(false);
+
+        // Symmetry: a shell lease auto-approves shell but not write.
+        const shellUnderShell = await underLease(SHELL, { kind: "shell", resource: "make build" });
+        expect(shellUnderShell.executed, `${substrate.name}: a shell lease must auto-approve another shell`).toBe(true);
+
+        const writeUnderShell = await underLease(SHELL, WRITE_A);
+        expect(writeUnderShell.executed, `${substrate.name}: a shell lease must NOT authorize a write`).toBe(false);
+      });
+    }
+  });
+}
+
+/**
+ * Prove the substrates AGREE: the same logical action under the same decision
+ * yields the same execution outcome on every available substrate. This is the
+ * real consolidation win — one place that says "the in-process gate and the
+ * out-of-process deny-oracle enforce the same policy," including the cross-taxonomy
+ * collapse (a grant minted from the stream-side identity is honored by the
+ * hook-side for the same action).
+ *
+ * Only `executed` is compared: it is the safety-critical observable and is
+ * substrate-comparable, whereas `gated` carries a substrate-specific meaning on
+ * an approve (the in-process gate still "paused"; the deny-oracle did not "deny").
+ */
+export function describeCrossSubstrateAgreement(substrates: GatewaySubstrate[]): void {
+  const available = substrates.filter((s) => s.available);
+  const suite = available.length >= 2 ? describe : describe.skip;
+
+  suite("gateway contract — cross-substrate agreement", () => {
+    const cases: Array<{ label: string; action: ProposedAction; decision: GatewayDecision }> = [
+      { label: "a fresh write is withheld", action: WRITE_A, decision: "none" },
+      { label: "an approved write executes", action: WRITE_A, decision: "approve" },
+      { label: "a fresh shell is withheld", action: SHELL, decision: "none" },
+      { label: "a rejected write never executes", action: WRITE_A, decision: "reject" },
+      { label: "a read runs ungated", action: READ, decision: "none" },
+      { label: "an auto-approved MCP tool runs ungated", action: MCP, decision: "none" },
+    ];
+
+    for (const { label, action, decision } of cases) {
+      it(`both substrates agree: ${label}`, async () => {
+        const outcomes = await Promise.all(available.map((s) => s.authorize(action, decision)));
+        const executed = outcomes.map((o) => o.executed);
+        const detail = available.map((s, i) => `${s.name}=${executed[i]}`).join(", ");
+        expect(new Set(executed).size, `substrates disagree on "${label}" (executed): ${detail}`).toBe(1);
+      });
+    }
+  });
+}

package/src/__test-utils__/approval-contract/types.ts

@@ -0,0 +1,179 @@
+/**
+ * The substrate-agnostic seam for the HITL gateway Contract Test Kit.
+ *
+ * Stigmer enforces tool approval through two real substrates with very different
+ * mechanics:
+ * - the in-process deep-agent gate (a LangGraph middleware that IS the side
+ *   effect), and
+ * - the out-of-process Cursor deny-oracle (a bash preToolUse hook that allows or
+ *   denies a tool the agent runs inside cursor-agent).
+ *
+ * The safety invariants they must uphold are identical, so the contract describes
+ * them once and runs them against anything that implements {@link GatewaySubstrate}.
+ * A future substrate (e.g. the T04 TS server's runner) joins the safety net by
+ * implementing this one interface — it does not get to redefine the invariants.
+ *
+ * This seam intentionally does NOT carry raw, harness-specific tool names. The
+ * two substrates name the same operation differently (the Cursor hook says
+ * `Write`/`Shell`/`Delete`; the deep-agent stream says `edit`/`shell`/`delete`),
+ * so the contract speaks in the abstract {@link ProposedAction} and each adapter
+ * translates it into its own taxonomy. Keeping the contract taxonomy-free is what
+ * makes "both substrates agree on the same logical action" a meaningful assertion.
+ */
+
+/**
+ * A logical action a model proposes, expressed independently of any harness
+ * taxonomy. Each adapter maps it to its substrate's concrete tool name and args.
+ */
+export interface ProposedAction {
+  /**
+   * The action's approval-relevant kind. `write`/`shell`/`delete` are the gated
+   * mutating categories; `read` is any non-mutating built-in; `mcp` is an
+   * MCP-server tool.
+   */
+  readonly kind: "write" | "shell" | "delete" | "read" | "mcp";
+  /**
+   * The resource the action acts on — the absolute file path for file actions,
+   * the command string for shell. Empty for `mcp` (MCP identity is name-scoped).
+   * This is the "salient" value the exact-resource lease binds to.
+   */
+  readonly resource: string;
+  /**
+   * The edit content for a `write` action — the body whose digest the
+   * content-exact grant binds to. Two `write`s to the same `resource` with
+   * DIFFERENT `content` are distinct identities (the sibling-isolation probe);
+   * omitted, a substrate uses a fixed placeholder. Ignored for non-write kinds.
+   */
+  readonly content?: string;
+  /** MCP server slug — required for `kind: "mcp"`, ignored otherwise. */
+  readonly mcpServerSlug?: string;
+  /** MCP tool name — required for `kind: "mcp"`, ignored otherwise. */
+  readonly mcpToolName?: string;
+}
+
+/**
+ * The decision applied to a proposed action.
+ * - `none`   — no decision yet: run the action up to the gate and stop (the
+ *              "what happens with no backing authorization" probe).
+ * - `approve`— authorize THIS action.
+ * - `skip` / `reject` / `unknown` — every non-approving outcome; none may execute.
+ */
+export type GatewayDecision = "none" | "approve" | "skip" | "reject" | "unknown";
+
+/**
+ * The observable result of putting one proposed action through a substrate.
+ */
+export interface GatewayOutcome {
+  /**
+   * Whether the side effect ran (or, for an out-of-process substrate, whether
+   * the substrate ALLOWED it to run). This is the safety-critical observable and
+   * is comparable across substrates.
+   */
+  readonly executed: boolean;
+  /**
+   * Whether the substrate withheld the action pending approval. Note the precise
+   * meaning is substrate-specific (the in-process gate "paused at an interrupt";
+   * the deny-oracle "denied this call"), so it is only compared across substrates
+   * for `none`-decision probes, where both mean "withheld".
+   */
+  readonly gated: boolean;
+  /**
+   * Exact number of times the side effect ran. Populated only when
+   * {@link SubstrateCapabilities.observesExecution} is true (an in-process
+   * substrate can count; an out-of-process one cannot observe execution at all).
+   */
+  readonly executionCount?: number;
+  /**
+   * The authorization provenance the gate attached when it withheld the action —
+   * the PolicySource union string (e.g. "builtin_category", "agent_override").
+   * Populated only when {@link SubstrateCapabilities.surfacesGatePolicySource} is
+   * true; empty/undefined otherwise. Lets the contract assert every gated side
+   * effect is provenance-tagged.
+   */
+  readonly policySource?: string;
+}
+
+/**
+ * Capability flags for invariants that legitimately differ by substrate, gated
+ * rather than forked — mirroring the conformance suite's `CapabilityFlags`.
+ */
+export interface SubstrateCapabilities {
+  /**
+   * True when the runner executes the tool in-process and can therefore observe
+   * (and count) the side effect directly. The deep-agent gate is in-process
+   * (`true`); the Cursor hook authorizes a tool that runs in another process
+   * (`false`, receipts are best-effort).
+   */
+  readonly observesExecution: boolean;
+  /**
+   * True when an approval is bound to the exact resource it was granted for, so
+   * approving one resource never authorizes another. The Cursor grant token binds
+   * the resource (`true`); the deep-agent gate re-checks every distinct call and
+   * relies on checkpoint replay for sameness, so per-resource lease isolation is
+   * not a property of that gate (`false`).
+   */
+  readonly enforcesExactResource: boolean;
+  /**
+   * True when an approval is bound to the exact CONTENT of the action, not just
+   * its resource — so approving one edit to a file never authorizes a DIFFERENT
+   * edit to the SAME file. The Cursor grant binds (category, path, contentDigest)
+   * (`true`); the deep-agent gate relies on checkpoint replay for sameness, so
+   * content isolation is not a property of that gate (`false`).
+   */
+  readonly enforcesExactContent: boolean;
+  /**
+   * True when the substrate honors a run-lifetime CLASS lease: an APPROVE_ALL on
+   * one action auto-approves later actions of the SAME class (built-in category)
+   * for the rest of the run, while a DIFFERENT class stays gated. Both production
+   * substrates enforce this (the deep-agent gate clears leased categories; the
+   * Cursor hook reads `leasedCategories` from its state file), so both set `true`
+   * and implement {@link GatewaySubstrate.authorizeUnderClassLease}.
+   */
+  readonly appliesRunLifetimeLease: boolean;
+  /**
+   * True when the substrate attaches authorization provenance
+   * (approval_policy_source) at the gate, so a withheld action's
+   * {@link GatewayOutcome.policySource} is populated. The deep-agent gate decides
+   * and stamps the source at interrupt time (`true`); the Cursor substrate's
+   * provenance is a reconstruction-time projection over the persisted tool call,
+   * not a property of the hook's deny decision, so it is `false` here and is
+   * covered instead by the message-translator and corpus suites.
+   */
+  readonly surfacesGatePolicySource: boolean;
+}
+
+/**
+ * A real enforcement substrate, wired to its production code. Adapters translate
+ * abstract actions/decisions into substrate-specific drives and report a uniform
+ * {@link GatewayOutcome}; they never reimplement enforcement logic.
+ */
+export interface GatewaySubstrate {
+  /** Stable substrate name, used in suite titles and diagnostics. */
+  readonly name: string;
+  /** Honest per-substrate capability flags. */
+  readonly capabilities: SubstrateCapabilities;
+  /**
+   * Whether this substrate can run in the current environment (e.g. the Cursor
+   * deny-oracle needs `bash`). The contract skips its suite when `false`.
+   */
+  readonly available: boolean;
+  /**
+   * Put a single proposed action through the substrate under a decision and
+   * report what happened.
+   */
+  authorize(action: ProposedAction, decision: GatewayDecision): Promise<GatewayOutcome>;
+  /**
+   * Approve `granted`, then probe `probe` against that standing authorization —
+   * the lease-isolation drive. Implemented only when
+   * {@link SubstrateCapabilities.enforcesExactResource} is true.
+   */
+  authorizeAfterGrant?(granted: ProposedAction, probe: ProposedAction): Promise<GatewayOutcome>;
+  /**
+   * Grant a run-lifetime CLASS lease by choosing APPROVE_ALL on `leased`, then
+   * probe `probe` against that standing lease — the scoped-lease drive that
+   * proves "approving all of class A never auto-approves class B." `leased` must
+   * be a gated built-in (write/shell/delete). Implemented only when
+   * {@link SubstrateCapabilities.appliesRunLifetimeLease} is true.
+   */
+  authorizeUnderClassLease?(leased: ProposedAction, probe: ProposedAction): Promise<GatewayOutcome>;
+}