@stigmer/runner 3.0.8-dev.20260613085218 → 3.0.9-dev.20260615145121

package/src/activities/execute-cursor/__tests__/message-translator.test.ts

@@ -58,6 +58,18 @@ function assistantEvent(
   };
 }
 
+function thinkingEvent(
+  runId: string,
+  text: string,
+): Extract<SDKMessage, { type: "thinking" }> {
+  return {
+    type: "thinking",
+    agent_id: "agent-1",
+    run_id: runId,
+    text,
+  };
+}
+
 function countToolCallsWithId(messages: AgentMessage[], callId: string): number {
   let count = 0;
   for (const msg of messages) {
@@ -237,9 +249,9 @@ describe("MessageAccumulator tool call status transitions", () => {
     expect(acc.subAgentExecutions[0].status).toBe(SubAgentStatus.SUB_AGENT_IN_PROGRESS);
   });
 
-  it("subAgentDirty starts false and is set when a sub-agent is created", () => {
+  it("isDirty starts false and is set when a sub-agent is created", () => {
     const acc = new MessageAccumulator([]);
-    expect(acc.subAgentDirty).toBe(false);
+    expect(acc.isDirty).toBe(false);
 
     acc.trackSubAgentExecution(
       toolCallEvent("tc-dirty1", "task", "running", "r1", {
@@ -247,10 +259,10 @@ describe("MessageAccumulator tool call status transitions", () => {
       }),
     );
 
-    expect(acc.subAgentDirty).toBe(true);
+    expect(acc.isDirty).toBe(true);
   });
 
-  it("markSubAgentPersisted clears the dirty flag, and an update re-marks it", () => {
+  it("markPersisted clears the dirty flag, and a sub-agent update re-marks it", () => {
     const acc = new MessageAccumulator([]);
 
     acc.trackSubAgentExecution(
@@ -258,17 +270,17 @@ describe("MessageAccumulator tool call status transitions", () => {
         args: { description: "Research", prompt: "Go" },
       }),
     );
-    expect(acc.subAgentDirty).toBe(true);
+    expect(acc.isDirty).toBe(true);
 
-    acc.markSubAgentPersisted();
-    expect(acc.subAgentDirty).toBe(false);
+    acc.markPersisted();
+    expect(acc.isDirty).toBe(false);
 
     // The completion transition (IN_PROGRESS -> COMPLETED) must re-mark dirty
     // so the terminal sub-agent state is persisted to the live stream.
     acc.trackSubAgentExecution(
       toolCallEvent("tc-dirty2", "task", "completed", "r1", { result: "Done" }),
     );
-    expect(acc.subAgentDirty).toBe(true);
+    expect(acc.isDirty).toBe(true);
     expect(acc.subAgentExecutions[0].status).toBe(SubAgentStatus.SUB_AGENT_COMPLETED);
   });
 
@@ -291,8 +303,8 @@ describe("MessageAccumulator tool call status transitions", () => {
       toolCallEvent("tc-done", "task", "completed", "r1", { result: "Found it" }),
     );
 
-    acc.markSubAgentPersisted();
-    expect(acc.subAgentDirty).toBe(false);
+    acc.markPersisted();
+    expect(acc.isDirty).toBe(false);
 
     acc.cancelInProgressSubAgents();
 
@@ -303,14 +315,14 @@ describe("MessageAccumulator tool call status transitions", () => {
     expect(running.completedAt).not.toBe("");
     expect(done.status).toBe(SubAgentStatus.SUB_AGENT_COMPLETED);
     // The transition must mark dirty so the cancellation is persisted.
-    expect(acc.subAgentDirty).toBe(true);
+    expect(acc.isDirty).toBe(true);
   });
 
   it("cancelInProgressSubAgents is a no-op when there are no running sub-agents", () => {
     const acc = new MessageAccumulator([]);
     acc.cancelInProgressSubAgents();
     expect(acc.subAgentExecutions).toHaveLength(0);
-    expect(acc.subAgentDirty).toBe(false);
+    expect(acc.isDirty).toBe(false);
   });
 
   it("sub-agent name extraction handles object subagentType", () => {
@@ -710,6 +722,106 @@ describe("MessageAccumulator tool call status transitions", () => {
     });
   });
 
+  // Issue #179: the live thinking/tool-call trace was starved because the Cursor
+  // loop's persist cadence had no force-flush for tool-call lifecycle. The
+  // accumulator's isDirty signal is now the force-flush source: it MUST fire on
+  // the discrete, user-visible events (tool start, tool finish, sub-agent
+  // delegation) and MUST NOT fire on high-frequency token deltas (assistant
+  // text, model thinking), which ride the StreamingUpdateScheduler time cadence.
+  describe("streaming force-flush signal (issue #179 cadence)", () => {
+    it("flags dirty the instant a tool call is created", () => {
+      const acc = new MessageAccumulator([]);
+      acc.processEvent(assistantEvent("r1", "Let me search."));
+      expect(acc.isDirty).toBe(false); // assistant text alone does not force-flush
+
+      acc.processEvent(toolCallEvent("tc-1", "Shell", "running", "r1"));
+      expect(acc.isDirty).toBe(true);
+    });
+
+    it("flags dirty when a tool call transitions to a terminal status", () => {
+      const acc = new MessageAccumulator([]);
+      acc.processEvent(assistantEvent("r1", "Running."));
+      acc.processEvent(toolCallEvent("tc-1", "Shell", "running", "r1"));
+      acc.markPersisted();
+      expect(acc.isDirty).toBe(false);
+
+      acc.processEvent(toolCallEvent("tc-1", "Shell", "completed", "r1", { result: "OK" }));
+      expect(acc.isDirty).toBe(true);
+    });
+
+    it("does NOT re-flag dirty on a redundant terminal re-emit", () => {
+      const acc = new MessageAccumulator([]);
+      acc.processEvent(assistantEvent("r1", "Running."));
+      acc.processEvent(toolCallEvent("tc-1", "read", "running", "r1"));
+      acc.processEvent(toolCallEvent("tc-1", "read", "completed", "r1", { result: "data" }));
+      acc.markPersisted();
+      expect(acc.isDirty).toBe(false);
+
+      // An already-terminal call re-emitting is noise, not a state change.
+      acc.processEvent(toolCallEvent("tc-1", "read", "completed", "r1", { result: "" }));
+      expect(acc.isDirty).toBe(false);
+    });
+
+    it("does NOT flag dirty on model thinking deltas (they ride the scheduler cadence)", () => {
+      const acc = new MessageAccumulator([]);
+      acc.processEvent(thinkingEvent("r1", "Let me reason about this"));
+      acc.processEvent(thinkingEvent("r1", " step by step..."));
+      expect(acc.isDirty).toBe(false);
+    });
+
+    it("does NOT flag dirty on assistant text deltas", () => {
+      const acc = new MessageAccumulator([]);
+      acc.processEvent(assistantEvent("r1", "Here is "));
+      acc.processEvent(assistantEvent("r1", "the answer."));
+      expect(acc.isDirty).toBe(false);
+    });
+
+    it("suppressed todo tools do NOT flag dirty (TodoTracker owns that signal)", () => {
+      const acc = new MessageAccumulator([]);
+      acc.processEvent(assistantEvent("r1", "Planning."));
+      acc.processEvent(toolCallEvent("tc-todo", "updateTodos", "running", "r1", {
+        args: { todos: [{ content: "Step 1", status: "pending" }] },
+      }));
+      expect(acc.isDirty).toBe(false);
+    });
+
+    it("markPersisted clears a tool-call dirty flag", () => {
+      const acc = new MessageAccumulator([]);
+      acc.processEvent(assistantEvent("r1", "Running."));
+      acc.processEvent(toolCallEvent("tc-1", "Shell", "running", "r1"));
+      expect(acc.isDirty).toBe(true);
+
+      acc.markPersisted();
+      expect(acc.isDirty).toBe(false);
+    });
+
+    // The user-facing symptom: a short thinking+tool turn (< 20 stream events).
+    // The old `eventCount % 20` gate never fired, so the whole trace landed only
+    // at the final persist. With the force-flush signal, the tool lifecycle is
+    // observable mid-turn — each discrete event leaves isDirty set for the loop.
+    it("a short thinking+tool turn produces force-flush points mid-turn", () => {
+      const acc = new MessageAccumulator([]);
+      const flushPoints: string[] = [];
+      const step = (label: string, ev: SDKMessage) => {
+        acc.processEvent(ev);
+        if (acc.isDirty) {
+          flushPoints.push(label);
+          acc.markPersisted();
+        }
+      };
+
+      step("thinking", thinkingEvent("r1", "Thinking about the task..."));
+      step("assistant", assistantEvent("r1", "I'll check the file."));
+      step("tool-start", toolCallEvent("tc-1", "read", "running", "r1"));
+      step("tool-done", toolCallEvent("tc-1", "read", "completed", "r1", { result: "contents" }));
+      step("assistant-2", assistantEvent("r1", "Done."));
+
+      // Tool start and tool completion are the discrete moments the live UI must
+      // see immediately; thinking/assistant deltas are carried by the scheduler.
+      expect(flushPoints).toEqual(["tool-start", "tool-done"]);
+    });
+  });
+
   describe("cancelInProgressSubAgentProtos standalone", () => {
     it("cancels IN_PROGRESS/PENDING protos in place and reports whether anything changed", () => {
       const running = create(SubAgentExecutionSchema, {

package/src/activities/execute-cursor/__tests__/persist-decision.test.ts

@@ -0,0 +1,99 @@
+/**
+ * Unit tests for the Cursor streaming persist decision (issue #179).
+ *
+ * Validates the converged cadence: discrete force-flush signals persist
+ * immediately, while high-frequency token deltas ride the shared
+ * StreamingUpdateScheduler's time cadence (rather than the old, time-blind
+ * `eventCount % 20` gate that starved short turns).
+ */
+
+import { describe, it, expect } from "vitest";
+import {
+  StreamingUpdateScheduler,
+  type StreamingConfig,
+} from "../../../shared/streaming-scheduler.js";
+import { shouldPersistStreamingStatus } from "../persist-decision.js";
+
+const CONFIG: StreamingConfig = {
+  minIntervalMs: 500,
+  maxIntervalMs: 5000,
+  burstThreshold: 50,
+};
+
+const NO_FORCE = {
+  deltaEnricherDirty: false,
+  todosDirty: false,
+  contentDirty: false,
+} as const;
+
+describe("shouldPersistStreamingStatus", () => {
+  it("persists on the first event via the scheduler (kills the opaque-wait at turn start)", () => {
+    const scheduler = new StreamingUpdateScheduler(CONFIG, 0);
+    expect(shouldPersistStreamingStatus(NO_FORCE, scheduler, 1, 0)).toBe(true);
+  });
+
+  it("does not persist a sub-500ms token delta with no force signal", () => {
+    const scheduler = new StreamingUpdateScheduler(CONFIG, 0);
+    scheduler.markUpdateSent(1, 0); // first flush already sent
+
+    // 100ms later, one more delta event — too soon for the time cadence.
+    expect(shouldPersistStreamingStatus(NO_FORCE, scheduler, 2, 100)).toBe(false);
+  });
+
+  it("persists a token delta once the 500ms cadence elapses", () => {
+    const scheduler = new StreamingUpdateScheduler(CONFIG, 0);
+    scheduler.markUpdateSent(1, 0);
+
+    expect(shouldPersistStreamingStatus(NO_FORCE, scheduler, 2, 500)).toBe(true);
+  });
+
+  it.each([
+    ["contentDirty (tool call / sub-agent)", { ...NO_FORCE, contentDirty: true }],
+    ["todosDirty", { ...NO_FORCE, todosDirty: true }],
+    ["deltaEnricherDirty (shell output)", { ...NO_FORCE, deltaEnricherDirty: true }],
+  ])("force-flushes immediately on %s, bypassing the time cadence", (_label, signals) => {
+    const scheduler = new StreamingUpdateScheduler(CONFIG, 0);
+    scheduler.markUpdateSent(1, 0);
+
+    // Only 1ms after the last flush: the scheduler alone would say no...
+    expect(shouldPersistStreamingStatus(NO_FORCE, scheduler, 2, 1)).toBe(false);
+    // ...but any discrete force signal flushes now.
+    expect(shouldPersistStreamingStatus(signals, scheduler, 2, 1)).toBe(true);
+  });
+
+  // The #179 starvation scenario: a short turn of < 20 events. Under the old
+  // `eventCount % 20` gate, a tool call appearing at event 3 (and completing at
+  // event 4) would never be persisted until the unconditional final flush. With
+  // the converged decision, the tool lifecycle force-flushes the instant it
+  // happens, regardless of how few events the turn has.
+  it("surfaces a tool call on a short (<20 event) turn", () => {
+    const scheduler = new StreamingUpdateScheduler(CONFIG, 0);
+    const flushes: number[] = [];
+    let clock = 0;
+
+    // Helper mirroring the loop: decide, then mark both clocks on a flush.
+    const tick = (eventCount: number, contentDirty: boolean) => {
+      const persist = shouldPersistStreamingStatus(
+        { ...NO_FORCE, contentDirty },
+        scheduler,
+        eventCount,
+        clock,
+      );
+      if (persist) {
+        flushes.push(eventCount);
+        scheduler.markUpdateSent(eventCount, clock);
+      }
+      clock += 50; // 50ms between events — well under the 500ms floor
+    };
+
+    tick(1, false); // assistant delta — first-event flush
+    tick(2, false); // thinking delta — within 500ms, no flush
+    tick(3, true);  // tool call starts — force-flush
+    tick(4, true);  // tool call completes — force-flush
+    tick(5, false); // closing assistant delta — within 500ms, no flush
+
+    // The tool lifecycle (events 3 and 4) is observed live; event 1 is the
+    // first-event flush. Events 2 and 5 correctly ride the cadence.
+    expect(flushes).toEqual([1, 3, 4]);
+  });
+});

package/src/activities/execute-cursor/__tests__/tool-result-image.test.ts

@@ -0,0 +1,244 @@
+/**
+ * Unit tests for Cursor MCP image-result normalization.
+ *
+ * The Cursor SDK wraps an MCP tool result as
+ *   { status, value: { content: [ { text:{text} }, { image:{ data, mimeType } } ] } }
+ * where image `data` is a Node Buffer-JSON ({ type:"Buffer", data:number[] }).
+ * The translator must re-emit that as the canonical top-level content-block
+ * array the shared persist-time offload consumes, so a screenshot lands as a
+ * renderable image ToolCallOutputRef instead of text/plain. These tests pin
+ * that normalization and confirm it flows end-to-end through the offload.
+ */
+
+import { describe, it, expect, vi } from "vitest";
+import { create } from "@bufbuild/protobuf";
+import { AgentExecutionStatusSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { AgentMessageSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+import type { SDKMessage } from "@cursor/sdk";
+import type { ArtifactStorage } from "../../../shared/artifact-storage.js";
+import {
+  offloadOversizedToolOutputs,
+  detectImagePayload,
+} from "../../../shared/status-offload.js";
+import {
+  toResultString,
+  canonicalizeImageResult,
+  buildToolCallProto,
+  MessageAccumulator,
+} from "../message-translator.js";
+import type { AgentMessage } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/message_pb";
+
+// PNG signature + a little payload, the way the Cursor SDK serializes bytes.
+const PNG_BYTES = [137, 80, 78, 71, 13, 10, 26, 10, 0, 0, 0, 13, 73, 72, 68, 82];
+const PNG_BASE64 = Buffer.from(PNG_BYTES).toString("base64");
+
+function cursorImageEnvelope(text = "App=com.example") {
+  return {
+    status: "success",
+    value: {
+      content: [
+        { text: { text } },
+        { image: { data: { type: "Buffer", data: PNG_BYTES }, mimeType: "image/png" } },
+      ],
+      isError: false,
+    },
+  };
+}
+
+describe("canonicalizeImageResult", () => {
+  it("converts a Cursor image envelope (Buffer-JSON) to the canonical array", () => {
+    const out = canonicalizeImageResult(cursorImageEnvelope("App=Slack"));
+    expect(out).toBeDefined();
+    expect(JSON.parse(out!)).toEqual([
+      { type: "text", text: "App=Slack" },
+      { type: "image", data: PNG_BASE64, mimeType: "image/png" },
+    ]);
+  });
+
+  it("handles a bare { content: [...] } envelope (no status/value wrapper)", () => {
+    const out = canonicalizeImageResult({
+      content: [{ image: { data: { type: "Buffer", data: PNG_BYTES }, mimeType: "image/png" } }],
+    });
+    expect(JSON.parse(out!)).toEqual([
+      { type: "image", data: PNG_BASE64, mimeType: "image/png" },
+    ]);
+  });
+
+  it("accepts an already-base64 image data string", () => {
+    const out = canonicalizeImageResult({
+      content: [{ image: { data: PNG_BASE64, mimeType: "image/png" } }],
+    });
+    expect(JSON.parse(out!)).toEqual([
+      { type: "image", data: PNG_BASE64, mimeType: "image/png" },
+    ]);
+  });
+
+  it("accepts a data: URL image data string", () => {
+    const out = canonicalizeImageResult({
+      content: [{ image: { data: `data:image/png;base64,${PNG_BASE64}`, mimeType: "image/png" } }],
+    });
+    expect(JSON.parse(out!)).toEqual([
+      { type: "image", data: PNG_BASE64, mimeType: "image/png" },
+    ]);
+  });
+
+  it("defaults mimeType to image/png when absent", () => {
+    const out = canonicalizeImageResult({
+      content: [{ image: { data: { type: "Buffer", data: PNG_BYTES } } }],
+    });
+    expect(JSON.parse(out!)[0]).toEqual({ type: "image", data: PNG_BASE64, mimeType: "image/png" });
+  });
+
+  it("returns undefined for a text-only envelope (no transformation)", () => {
+    expect(canonicalizeImageResult({ status: "success", value: { content: [{ text: { text: "hi" } }] } }))
+      .toBeUndefined();
+  });
+
+  it("returns undefined when there is no content array", () => {
+    expect(canonicalizeImageResult({ status: "success", value: { stdout: "ok" } })).toBeUndefined();
+    expect(canonicalizeImageResult("plain string")).toBeUndefined();
+    expect(canonicalizeImageResult(null)).toBeUndefined();
+  });
+});
+
+describe("toResultString", () => {
+  it("passes a string through unchanged", () => {
+    expect(toResultString("just logs")).toBe("just logs");
+  });
+
+  it("returns empty string for an absent result", () => {
+    expect(toResultString(null)).toBe("");
+    expect(toResultString(undefined)).toBe("");
+  });
+
+  it("JSON.stringifies a non-image object unchanged (text-only envelope)", () => {
+    const env = { status: "success", value: { content: [{ text: { text: "hi" } }] } };
+    expect(toResultString(env)).toBe(JSON.stringify(env));
+  });
+
+  it("normalizes an image envelope to the canonical array", () => {
+    const out = toResultString(cursorImageEnvelope("App=X"));
+    expect(JSON.parse(out)).toEqual([
+      { type: "text", text: "App=X" },
+      { type: "image", data: PNG_BASE64, mimeType: "image/png" },
+    ]);
+  });
+});
+
+describe("buildToolCallProto image normalization", () => {
+  it("produces a result the shared offload detector recognizes as an image", () => {
+    const event = {
+      type: "tool_call",
+      agent_id: "a1",
+      run_id: "r1",
+      call_id: "tc-img",
+      name: "mcp",
+      status: "completed",
+      args: { providerIdentifier: "open-computer-use", toolName: "get_app_state", args: {} },
+      result: cursorImageEnvelope(),
+    } as unknown as Extract<SDKMessage, { type: "tool_call" }>;
+
+    const tc = buildToolCallProto(event);
+    expect(tc.name).toBe("get_app_state");
+    const img = detectImagePayload(tc.result);
+    expect(img).not.toBeNull();
+    expect(img?.mimeType).toBe("image/png");
+    expect(img?.base64).toBe(PNG_BASE64);
+    // The bloated Buffer-JSON must not survive into the persisted result.
+    expect(tc.result).not.toContain('"Buffer"');
+  });
+});
+
+describe("cursor image flows through the persist-time offload", () => {
+  it("offloads the screenshot as an image ref with no inline bytes", async () => {
+    const uploads: { key: string; contentType?: string }[] = [];
+    const storage: ArtifactStorage = {
+      upload: vi.fn(async (key: string, _content: Buffer, contentType?: string) => {
+        uploads.push({ key, contentType });
+        return key;
+      }),
+      getDownloadUrl: vi.fn(async (key: string) => `https://artifacts.local/${key}`),
+      exists: vi.fn(async () => true),
+    };
+
+    const event = {
+      type: "tool_call",
+      agent_id: "a1",
+      run_id: "r1",
+      call_id: "tc-img",
+      name: "mcp",
+      status: "completed",
+      args: { providerIdentifier: "open-computer-use", toolName: "get_app_state", args: {} },
+      result: cursorImageEnvelope(),
+    } as unknown as Extract<SDKMessage, { type: "tool_call" }>;
+
+    const tc = buildToolCallProto(event);
+    const status = create(AgentExecutionStatusSchema, {
+      messages: [create(AgentMessageSchema, { toolCalls: [tc] })],
+    });
+
+    await offloadOversizedToolOutputs(status, { artifactStorage: storage, executionId: "exec-1" });
+
+    const out = status.messages[0].toolCalls[0];
+    expect(out.outputRef).toBeDefined();
+    expect(out.outputRef!.isImage).toBe(true);
+    expect(out.outputRef!.mimeType).toBe("image/png");
+    expect(out.outputRef!.storageKey.endsWith(".png")).toBe(true);
+    expect(uploads[0]?.contentType).toBe("image/png");
+    // Inline result is collapsed; no base64/Buffer bytes remain in the status.
+    expect(out.result).not.toContain(PNG_BASE64);
+    expect(out.result).not.toContain('"Buffer"');
+  });
+});
+
+describe("sub-agent image normalization (extractConversationSteps)", () => {
+  it("normalizes a screenshot returned inside a sub-agent toolCall step", () => {
+    const messages: AgentMessage[] = [];
+    const acc = new MessageAccumulator(messages);
+
+    const running = {
+      type: "tool_call",
+      agent_id: "a1",
+      run_id: "r1",
+      call_id: "tc-sub-img",
+      name: "task",
+      status: "running",
+      args: { description: "screenshot", prompt: "capture" },
+    } as unknown as Extract<SDKMessage, { type: "tool_call" }>;
+    acc.processEvent(running);
+    acc.trackSubAgentExecution(running);
+
+    const completed = {
+      type: "tool_call",
+      agent_id: "a1",
+      run_id: "r1",
+      call_id: "tc-sub-img",
+      name: "task",
+      status: "completed",
+      args: { description: "screenshot", prompt: "capture" },
+      result: {
+        status: "success",
+        value: {
+          conversationSteps: [
+            {
+              type: "toolCall",
+              message: {
+                type: "get_app_state",
+                args: {},
+                result: cursorImageEnvelope("App=SubAgent"),
+              },
+            },
+          ],
+        },
+      },
+    } as unknown as Extract<SDKMessage, { type: "tool_call" }>;
+
+    acc.processEvent(completed);
+    acc.trackSubAgentExecution(completed);
+
+    const sub = acc.subAgentExecutions[0];
+    const subToolResult = sub.messages[0].toolCalls[0].result;
+    const img = detectImagePayload(subToolResult);
+    expect(img?.base64).toBe(PNG_BASE64);
+  });
+});

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

@@ -43,9 +43,12 @@ function freshRoot(): string {
 const stigmerScript = (root: string) =>
   join(root, ".stigmer", "sessions", "ses-1", "hitl", "stigmer-approval.sh");
 
+// Single preToolUse registration — the common shape in these tests.
+const pre = (scriptPath: string) => [{ event: "preToolUse", scriptPath }];
+
 describe("buildMergedConfig", () => {
   it("writes a standalone config and restores by delete when no hooks.json exists", () => {
-    const { merged, restoreTo } = buildMergedConfig(null, "/abs/hitl/stigmer-approval.sh");
+    const { merged, restoreTo } = buildMergedConfig(null, pre("/abs/hitl/stigmer-approval.sh"));
     const parsed = JSON.parse(merged);
     expect(parsed.hooks.preToolUse).toHaveLength(1);
     expect(parsed.hooks.preToolUse[0].command).toBe("/abs/hitl/stigmer-approval.sh");
@@ -54,6 +57,47 @@ describe("buildMergedConfig", () => {
     expect(restoreTo).toBeNull();
   });
 
+  it("registers multiple events (preToolUse + beforeMCPExecution) and restores by delete", () => {
+    const { merged, restoreTo } = buildMergedConfig(null, [
+      { event: "preToolUse", scriptPath: "/abs/hitl/stigmer-approval.sh" },
+      { event: "beforeMCPExecution", scriptPath: "/abs/hitl/stigmer-mcp-capture.sh" },
+    ]);
+    const parsed = JSON.parse(merged);
+    expect(parsed.hooks.preToolUse[0].command).toBe("/abs/hitl/stigmer-approval.sh");
+    expect(parsed.hooks.beforeMCPExecution[0].command).toBe("/abs/hitl/stigmer-mcp-capture.sh");
+    expect(parsed.hooks.beforeMCPExecution[0].failClosed).toBe(true);
+    expect(restoreTo).toBeNull();
+  });
+
+  it("merges into both event arrays and strips stale Stigmer entries from each on restore", () => {
+    const root = "/abs";
+    const stalePre = join(root, ".stigmer", "sessions", "ses-1", "hitl", "stigmer-approval.sh");
+    const staleMcp = join(root, ".stigmer", "sessions", "ses-1", "hitl", "stigmer-mcp-capture.sh");
+    const original = JSON.stringify({
+      version: 1,
+      hooks: {
+        preToolUse: [{ command: "./user.sh" }, { command: stalePre, failClosed: true }],
+        beforeMCPExecution: [{ command: staleMcp, failClosed: true }],
+      },
+    });
+    const freshPre = join(root, ".stigmer", "sessions", "ses-2", "hitl", "stigmer-approval.sh");
+    const freshMcp = join(root, ".stigmer", "sessions", "ses-2", "hitl", "stigmer-mcp-capture.sh");
+
+    const { merged, restoreTo } = buildMergedConfig(original, [
+      { event: "preToolUse", scriptPath: freshPre },
+      { event: "beforeMCPExecution", scriptPath: freshMcp },
+    ]);
+
+    const m = JSON.parse(merged);
+    expect(m.hooks.preToolUse.map((e: any) => e.command)).toEqual(["./user.sh", freshPre]);
+    expect(m.hooks.beforeMCPExecution.map((e: any) => e.command)).toEqual([freshMcp]);
+
+    // Restore is self-healing: every stale Stigmer entry is removed from both.
+    const r = JSON.parse(restoreTo!);
+    expect(r.hooks.preToolUse).toEqual([{ command: "./user.sh" }]);
+    expect(r.hooks.beforeMCPExecution).toEqual([]);
+  });
+
   it("merges with a user's hooks.json and restores the original bytes verbatim", () => {
     const original = JSON.stringify(
       {
@@ -67,7 +111,7 @@ describe("buildMergedConfig", () => {
       2,
     );
     const script = "/abs/.stigmer/sessions/ses-1/hitl/stigmer-approval.sh";
-    const { merged, restoreTo } = buildMergedConfig(original, script);
+    const { merged, restoreTo } = buildMergedConfig(original, pre(script));
     const parsed = JSON.parse(merged);
 
     // Our entry is appended; the user's preToolUse hook is preserved...
@@ -93,7 +137,7 @@ describe("buildMergedConfig", () => {
       },
     });
     const fresh = join(root, ".stigmer", "sessions", "ses-2", "hitl", "stigmer-approval.sh");
-    const { merged, restoreTo } = buildMergedConfig(original, fresh);
+    const { merged, restoreTo } = buildMergedConfig(original, pre(fresh));
 
     const mergedParsed = JSON.parse(merged);
     // No duplicate: user entry + exactly one fresh Stigmer entry.
@@ -109,7 +153,7 @@ describe("buildMergedConfig", () => {
 
   it("replaces an unparseable hooks.json for the turn but restores its exact bytes", () => {
     const garbage = "{ this is not json ";
-    const { merged, restoreTo } = buildMergedConfig(garbage, "/abs/hitl/stigmer-approval.sh");
+    const { merged, restoreTo } = buildMergedConfig(garbage, pre("/abs/hitl/stigmer-approval.sh"));
     // We still install a working gate for the turn...
     expect(JSON.parse(merged).hooks.preToolUse).toHaveLength(1);
     // ...and never "fix" the user's file: restore their exact original bytes.
@@ -147,6 +191,11 @@ describe("installHitlGate / removeHitlGate", () => {
     const command = hooksJson.hooks.preToolUse[0].command;
     expect(command).toBe(join(hitlDir, "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"),
+    );
     // The workspace holds no relocated artifacts.
     expect(existsSync(join(workspaceRoot, ".cursor", "hooks"))).toBe(false);
   });