@stigmer/runner 3.10.0 → 3.11.0

package/src/activities/execute-cursor/__tests__/attachment-resolver.test.ts

@@ -114,6 +114,59 @@ describe("resolveAttachments", () => {
     expect(readFileSync(join(platformDir, "inputs", "data.csv"), "utf-8")).toBe("a,b,c");
   });
 
+  it("uniquifies duplicate filenames on the storage branch — neither file's bytes are lost (issue #364)", async () => {
+    // Before the fix this branch had no collision check and the second write
+    // silently overwrote the first.
+    const { storage } = makeInMemoryArtifactStorage();
+    await storage.upload("attachments/01AAA/report.pdf", Buffer.from("first bytes"), "application/pdf");
+    await storage.upload("attachments/01BBB/report.pdf", Buffer.from("second bytes"), "application/pdf");
+
+    const result = await resolveAttachments(
+      [
+        makeAttachment({ filename: "report.pdf", storageKey: "attachments/01AAA/report.pdf" }),
+        makeAttachment({ filename: "report.pdf", storageKey: "attachments/01BBB/report.pdf" }),
+      ],
+      options({ storage }),
+    );
+
+    expect(result).toEqual([
+      { filename: "report.pdf", relativePath: ".stigmer/inputs/report.pdf" },
+      {
+        filename: "report-2.pdf",
+        relativePath: ".stigmer/inputs/report-2.pdf",
+        renamedFrom: "report.pdf",
+      },
+    ]);
+    expect(readFileSync(join(platformDir, "inputs", "report.pdf"), "utf-8")).toBe("first bytes");
+    expect(readFileSync(join(platformDir, "inputs", "report-2.pdf"), "utf-8")).toBe("second bytes");
+  });
+
+  it("uniquifies duplicate filenames across the local and storage branches (one shared taken-set)", async () => {
+    const srcPath = join(workspaceDir, "notes.md");
+    writeFileSync(srcPath, "local copy");
+    const { storage } = makeInMemoryArtifactStorage();
+    await storage.upload("attachments/01ABC/notes.md", Buffer.from("uploaded copy"), "text/markdown");
+
+    const result = await resolveAttachments(
+      [
+        makeAttachment({ filename: "notes.md", storageKey: "", localPath: srcPath }),
+        makeAttachment({ filename: "notes.md", storageKey: "attachments/01ABC/notes.md" }),
+      ],
+      options({ storage }),
+    );
+
+    expect(result).toEqual([
+      { filename: "notes.md", relativePath: ".stigmer/inputs/notes.md" },
+      {
+        filename: "notes-2.md",
+        relativePath: ".stigmer/inputs/notes-2.md",
+        renamedFrom: "notes.md",
+      },
+    ]);
+    expect(readFileSync(join(platformDir, "inputs", "notes.md"), "utf-8")).toBe("local copy");
+    expect(readFileSync(join(platformDir, "inputs", "notes-2.md"), "utf-8")).toBe("uploaded copy");
+  });
+
   it("ignores localPath in cloud mode and downloads by storage key", async () => {
     const { storage } = makeInMemoryArtifactStorage();
     await storage.upload("attachments/01ABC/plan.md", Buffer.from("from storage"), "text/markdown");

package/src/activities/execute-cursor/__tests__/build-prompt.test.ts

@@ -47,7 +47,7 @@ function input(overrides: Partial<BuildPromptInput>): BuildPromptInput {
     subAgents: [],
     workspaceDirs: ["/tmp/ws"],
     workspaceFileRefs: [],
-    attachmentPaths: [],
+    attachments: [],
     pendingApprovals: [],
     ...overrides,
   };
@@ -103,6 +103,10 @@ describe("buildPrompt", () => {
     expect(prompt).toContain("<available_datastores>");
     expect(prompt).toContain("- clinic");
     expect(prompt).toContain("describe_datastore");
+    // The standing failure-disclosure instruction (issue #325) is this
+    // harness's ONLY outage coverage: the Cursor SDK connects MCP itself,
+    // so the runner can never reconcile the live roster here.
+    expect(prompt).toContain("do not answer from memory");
   });
 
   it("omits the datastores section when the agent uses no datastores", () => {
@@ -269,7 +273,7 @@ describe("attachments on a resumed turn (T04 — the mid-session WhatsApp case)"
 
   it("announces this turn's attachments to a resumed agent (per-execution value, never inherited)", () => {
     const prompt = buildPrompt(
-      input({ ...RESUMED, attachmentPaths: [".stigmer/inputs/lease.pdf"] }),
+      input({ ...RESUMED, attachments: [{ path: ".stigmer/inputs/lease.pdf" }] }),
     );
     expect(prompt).toContain("<input_files>");
     expect(prompt).toContain("`.stigmer/inputs/lease.pdf`");
@@ -277,6 +281,23 @@ describe("attachments on a resumed turn (T04 — the mid-session WhatsApp case)"
     expect(prompt.endsWith(USER_MESSAGE)).toBe(true);
   });
 
+  it("discloses a duplicate-renamed attachment's original name (issue #364)", () => {
+    const prompt = buildPrompt(
+      input({
+        ...RESUMED,
+        attachments: [
+          { path: ".stigmer/inputs/report.pdf" },
+          { path: ".stigmer/inputs/report-2.pdf", renamedFrom: "report.pdf" },
+        ],
+      }),
+    );
+    expect(prompt).toContain(
+      "- `.stigmer/inputs/report-2.pdf` (renamed from duplicate 'report.pdf')",
+    );
+    // The first file keeps a clean entry — no disclosure noise.
+    expect(prompt).toContain("- `.stigmer/inputs/report.pdf`\n");
+  });
+
   it("keeps a resumed turn WITHOUT attachments byte-identical to the raw message (regression guard)", () => {
     const prompt = buildPrompt(input({ ...RESUMED }));
     expect(prompt).toBe(USER_MESSAGE);
@@ -286,7 +307,7 @@ describe("attachments on a resumed turn (T04 — the mid-session WhatsApp case)"
     const prompt = buildPrompt(
       input({
         ...RESUMED,
-        attachmentPaths: [".stigmer/inputs/photo.jpg"],
+        attachments: [{ path: ".stigmer/inputs/photo.jpg" }],
         conversationCatchup: "User also said hello on the channel.",
       }),
     );
@@ -300,7 +321,7 @@ describe("attachments on a resumed turn (T04 — the mid-session WhatsApp case)"
     const prompt = buildPrompt(
       input({
         ...RESUMED,
-        attachmentPaths: [".stigmer/inputs/a.jpg", ".stigmer/inputs/big.png"],
+        attachments: [{ path: ".stigmer/inputs/a.jpg" }, { path: ".stigmer/inputs/big.png" }],
         vision: {
           inlineFilenames: ["a.jpg"],
           notViewable: [{ path: ".stigmer/inputs/big.png", reason: "too_large" }],
@@ -316,7 +337,7 @@ describe("attachments on a resumed turn (T04 — the mid-session WhatsApp case)"
     const prompt = buildPrompt(
       input({
         resolution: resolution("local", "created_first_execution"),
-        attachmentPaths: [".stigmer/inputs/a.jpg"],
+        attachments: [{ path: ".stigmer/inputs/a.jpg" }],
         vision: { inlineFilenames: ["a.jpg"], notViewable: [] },
       }),
     );
@@ -336,7 +357,7 @@ describe("attachments on a resumed turn (T04 — the mid-session WhatsApp case)"
             message: "Write file: gated.txt",
           }),
         ],
-        attachmentPaths: [".stigmer/inputs/photo.jpg"],
+        attachments: [{ path: ".stigmer/inputs/photo.jpg" }],
         vision: { inlineFilenames: ["photo.jpg"], notViewable: [] },
       }),
     );
@@ -543,7 +564,10 @@ describe("formatImplementPlanSection", () => {
   const PLAN_PATH = ".stigmer/inputs/plan.md";
 
   it("wraps the attached-plan directive when the plan is among the attachments", () => {
-    const section = formatImplementPlanSection(true, [PLAN_PATH, ".stigmer/inputs/data.csv"]);
+    const section = formatImplementPlanSection(true, [
+      { path: PLAN_PATH },
+      { path: ".stigmer/inputs/data.csv" },
+    ]);
 
     expect(section).toBeDefined();
     expect(section!.startsWith("<implement_plan>")).toBe(true);
@@ -553,7 +577,9 @@ describe("formatImplementPlanSection", () => {
   });
 
   it("falls back to the conversation-plan directive when no plan attachment resolved", () => {
-    const section = formatImplementPlanSection(true, [".stigmer/inputs/data.csv"]);
+    const section = formatImplementPlanSection(true, [
+      { path: ".stigmer/inputs/data.csv" },
+    ]);
 
     expect(section).toBeDefined();
     expect(section).not.toContain("plan.md");
@@ -561,12 +587,12 @@ describe("formatImplementPlanSection", () => {
   });
 
   it("returns undefined for an ordinary (non-build) execution", () => {
-    expect(formatImplementPlanSection(false, [PLAN_PATH])).toBeUndefined();
-    expect(formatImplementPlanSection(undefined, [PLAN_PATH])).toBeUndefined();
+    expect(formatImplementPlanSection(false, [{ path: PLAN_PATH }])).toBeUndefined();
+    expect(formatImplementPlanSection(undefined, [{ path: PLAN_PATH }])).toBeUndefined();
   });
 
   it("carries the plan-derived progress-tracking instruction (Tier 3)", () => {
-    const section = formatImplementPlanSection(true, [PLAN_PATH]);
+    const section = formatImplementPlanSection(true, [{ path: PLAN_PATH }]);
 
     expect(section).toContain("to-do list");
     expect(section).toContain("break the plan into");
@@ -577,7 +603,7 @@ describe("formatImplementPlanSection", () => {
       input({
         resolution: resolution("local", "created_first_execution"),
         buildFromPlan: true,
-        attachmentPaths: [PLAN_PATH],
+        attachments: [{ path: PLAN_PATH }],
       }),
     );
 
@@ -593,7 +619,7 @@ describe("formatImplementPlanSection", () => {
       input({
         resolution: resolution("local", "resumed_successfully"),
         buildFromPlan: true,
-        attachmentPaths: [PLAN_PATH],
+        attachments: [{ path: PLAN_PATH }],
       }),
     );
 
@@ -611,7 +637,7 @@ describe("formatImplementPlanSection", () => {
       input({
         resolution: resolution("local", "resumed_successfully"),
         buildFromPlan: false,
-        attachmentPaths: [PLAN_PATH],
+        attachments: [{ path: PLAN_PATH }],
       }),
     );
 

package/src/activities/execute-cursor/__tests__/error-classifier-extraction.test.ts

@@ -0,0 +1,208 @@
+/**
+ * Tests for the shape-aware run.wait() error extraction (oss#299).
+ *
+ * A bare String() on a structured error value yields "[object Object]",
+ * which end users saw verbatim AND which shadowed every lower-priority
+ * classifier source (stream, rejection, conversation introspection) because
+ * classification stops at the first non-empty source. These tests pin:
+ *
+ * - the extractRunErrorSources shape matrix (strings, Errors, field objects,
+ *   hopeless values)
+ * - first-USABLE-candidate chain order (a hopeless object no longer hides a
+ *   usable string one field later; an empty string no longer short-circuits)
+ * - end-to-end: structured errors classify and re-enable fresh-agent retry;
+ *   hopeless extraction yields to the introspection sources
+ * - the "[object Object]" defense-in-depth guard in classifyFromSources
+ */
+
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import {
+  extractRunErrorSources,
+  synthesizeError,
+  shouldRetryWithFreshAgent,
+} from "../error-classifier.js";
+
+const FALLBACK = { model: "default", mode: "cloud", agentId: "agent-1" };
+
+function base() {
+  return {
+    sdkResultFields: undefined,
+    streamErrorMessage: undefined,
+    capturedRejection: undefined,
+    isResumedHandle: false,
+    fallbackContext: FALLBACK,
+  } as const;
+}
+
+/** A run.wait()-shaped error result carrying the given error-detail fields. */
+function errorResult(fields: Record<string, unknown>): unknown {
+  return { id: "run-1", status: "error", ...fields };
+}
+
+const NOTHING = { sdkError: undefined, sdkResultFields: undefined };
+
+describe("extractRunErrorSources shape matrix", () => {
+  it("routes a plain string to sdkResultFields", () => {
+    expect(extractRunErrorSources(errorResult({ result: "rate limit exceeded" })))
+      .toEqual({ sdkError: undefined, sdkResultFields: "rate limit exceeded" });
+  });
+
+  it("lifts an Error instance into the structured channel", () => {
+    expect(extractRunErrorSources(errorResult({ result: new Error("connection lost") })))
+      .toEqual({ sdkError: { message: "connection lost" }, sdkResultFields: undefined });
+  });
+
+  it("lifts an Error carrying a code (Node/SDK error shape)", () => {
+    const err = Object.assign(new Error("stream torn down"), { code: "unavailable" });
+    expect(extractRunErrorSources(errorResult({ result: err })))
+      .toEqual({ sdkError: { code: "unavailable", message: "stream torn down" }, sdkResultFields: undefined });
+  });
+
+  it("lifts { code, status, message } from a plain object", () => {
+    expect(extractRunErrorSources(errorResult({ error: { code: "unauthenticated", status: 401, message: "bad token" } })))
+      .toEqual({
+        sdkError: { code: "unauthenticated", status: 401, message: "bad token" },
+        sdkResultFields: undefined,
+      });
+  });
+
+  it("lifts a message-only object", () => {
+    expect(extractRunErrorSources(errorResult({ error: { message: "boom" } })))
+      .toEqual({ sdkError: { message: "boom" }, sdkResultFields: undefined });
+  });
+
+  it("lifts a code-only object", () => {
+    expect(extractRunErrorSources(errorResult({ error: { code: "resource_exhausted" } })))
+      .toEqual({ sdkError: { code: "resource_exhausted" }, sdkResultFields: undefined });
+  });
+
+  it("yields nothing for an object with no recognizable fields (no JSON.stringify junk)", () => {
+    expect(extractRunErrorSources(errorResult({ result: { weird: "shape" } }))).toEqual(NOTHING);
+  });
+
+  it("yields nothing for a circular object", () => {
+    const circular: Record<string, unknown> = {};
+    circular.self = circular;
+    expect(extractRunErrorSources(errorResult({ result: circular }))).toEqual(NOTHING);
+  });
+
+  it("refuses the '[object Object]' junk string itself", () => {
+    expect(extractRunErrorSources(errorResult({ result: "[object Object]" }))).toEqual(NOTHING);
+  });
+
+  it("stringifies non-string primitives losslessly", () => {
+    expect(extractRunErrorSources(errorResult({ result: 503 })))
+      .toEqual({ sdkError: undefined, sdkResultFields: "503" });
+  });
+
+  it("yields nothing when no candidate field is present", () => {
+    expect(extractRunErrorSources(errorResult({}))).toEqual(NOTHING);
+  });
+
+  it("yields nothing for non-object results", () => {
+    expect(extractRunErrorSources(undefined)).toEqual(NOTHING);
+    expect(extractRunErrorSources(null)).toEqual(NOTHING);
+    expect(extractRunErrorSources("not-a-result-object")).toEqual(NOTHING);
+  });
+});
+
+describe("extractRunErrorSources chain order (first USABLE candidate wins)", () => {
+  it("a hopeless object in result no longer hides a usable string in message", () => {
+    const extracted = extractRunErrorSources(
+      errorResult({ result: { weird: "shape" }, message: "the real reason" }),
+    );
+    expect(extracted).toEqual({ sdkError: undefined, sdkResultFields: "the real reason" });
+  });
+
+  it("an empty string in result no longer short-circuits the chain", () => {
+    const extracted = extractRunErrorSources(
+      errorResult({ result: "", reason: "torn down mid-stream" }),
+    );
+    expect(extracted).toEqual({ sdkError: undefined, sdkResultFields: "torn down mid-stream" });
+  });
+
+  it("respects the documented field order: result before error before message before reason", () => {
+    const extracted = extractRunErrorSources(
+      errorResult({ result: "from-result", error: "from-error", message: "from-message" }),
+    );
+    expect(extracted.sdkResultFields).toBe("from-result");
+  });
+
+  it("yields nothing when every candidate is hopeless", () => {
+    const extracted = extractRunErrorSources(
+      errorResult({ result: {}, error: "", message: "[object Object]" }),
+    );
+    expect(extracted).toEqual(NOTHING);
+  });
+});
+
+describe("end-to-end through synthesizeError", () => {
+  beforeEach(() => {
+    vi.spyOn(console, "log").mockImplementation(() => {});
+  });
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("a structured retryable error classifies and re-enables fresh-agent recovery", () => {
+    // The regression at the heart of oss#299: String() turned this into
+    // "[object Object]" -> category=unknown, retryable=false -> the
+    // poisoned-handle retry could never fire for a plain network flake.
+    const extracted = extractRunErrorSources(
+      errorResult({ error: { code: "unavailable", message: "upstream connect error" } }),
+    );
+    const classified = synthesizeError({ ...base(), ...extracted });
+
+    expect(classified.source).toBe("sdk");
+    expect(classified.category).toBe("network");
+    expect(classified.message).toBe("upstream connect error");
+    expect(classified.retryable).toBe(true);
+    expect(shouldRetryWithFreshAgent(classified)).toBe(true);
+  });
+
+  it("hopeless extraction yields to the conversation introspection source", () => {
+    const extracted = extractRunErrorSources(errorResult({ result: { weird: "shape" } }));
+    const classified = synthesizeError({
+      ...base(),
+      ...extracted,
+      conversationErrorText: "grpc-status 12: routing failure",
+    });
+
+    expect(classified.source).toBe("conversation");
+    expect(classified.message).toBe("grpc-status 12: routing failure");
+  });
+
+  it("hopeless extraction yields to the captured rejection source", () => {
+    const extracted = extractRunErrorSources(errorResult({ result: { weird: "shape" } }));
+    const classified = synthesizeError({
+      ...base(),
+      ...extracted,
+      capturedRejection: { code: "unavailable", message: "socket hang up", timestamp: Date.now() },
+    });
+
+    expect(classified.source).toBe("rejection");
+    expect(classified.message).toContain("socket hang up");
+  });
+});
+
+describe("classifyFromSources '[object Object]' defense-in-depth guard", () => {
+  beforeEach(() => {
+    vi.spyOn(console, "log").mockImplementation(() => {});
+  });
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("treats a leaked '[object Object]' sdkResultFields as absent", () => {
+    // Extraction never emits it, but any other producer of the junk string
+    // must not shadow the sources below it.
+    const classified = synthesizeError({
+      ...base(),
+      sdkResultFields: "[object Object]",
+      streamErrorMessage: "fetch failed",
+    });
+
+    expect(classified.source).toBe("stream");
+    expect(classified.category).toBe("network");
+  });
+});

package/src/activities/execute-cursor/__tests__/extract-structured-output.test.ts

@@ -0,0 +1,120 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import type { Config } from "../../../config.js";
+
+vi.mock("../../../shared/model-registry.js", () => ({
+  getEconomyModel: vi.fn().mockResolvedValue("gpt-4o-mini"),
+}));
+
+const mockInvoke = vi.fn();
+const mockWithStructuredOutput = vi.fn().mockReturnValue({ invoke: mockInvoke });
+
+vi.mock("../../../shared/model-client.js", () => ({
+  buildChatModel: vi.fn().mockResolvedValue({
+    model: { withStructuredOutput: (...args: unknown[]) => mockWithStructuredOutput(...args) },
+    provider: "openai",
+    apiModelId: "gpt-4o-mini",
+  }),
+}));
+
+// llm-backend.js and llm-proxy.js stay real: the pre-check behavior under
+// test IS their composition, and both are pure modules.
+
+const SCHEMA = { type: "object", properties: { answer: { type: "string" } } };
+
+function makeConfig(overrides: Partial<Config> = {}): Config {
+  return {
+    proxyEndpoint: null,
+    stigmerToken: null,
+    ...overrides,
+  } as Config;
+}
+
+describe("extractStructuredOutput", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    // Deterministic regardless of the developer's shell: blank reads as
+    // missing, and backend vars must not leak in from outside.
+    vi.stubEnv("OPENAI_API_KEY", "");
+    vi.stubEnv("ANTHROPIC_API_KEY", "");
+    vi.stubEnv("STIGMER_ANTHROPIC_BACKEND", "");
+    vi.stubEnv("STIGMER_OPENAI_BACKEND", "");
+  });
+
+  afterEach(() => {
+    vi.unstubAllEnvs();
+  });
+
+  it("direct mode with a key builds a direct-mode model (no endpoint threaded)", async () => {
+    vi.stubEnv("OPENAI_API_KEY", "sk-direct");
+    const { buildChatModel } = await import("../../../shared/model-client.js");
+    const { extractStructuredOutput } = await import("../extract-structured-output.js");
+    mockInvoke.mockResolvedValueOnce({ answer: "42" });
+
+    const result = await extractStructuredOutput("the answer is 42", SCHEMA, makeConfig(), "gpt-4.1");
+
+    expect(result).toEqual({ answer: "42" });
+    // The regression pin: the gRPC control-plane endpoint must never
+    // reappear here as a stand-in LLM proxy.
+    expect(buildChatModel).toHaveBeenCalledWith(
+      expect.objectContaining({ proxyEndpoint: undefined }),
+    );
+  });
+
+  it("throws the credential message before any construction when no path exists", async () => {
+    const { buildChatModel } = await import("../../../shared/model-client.js");
+    const { extractStructuredOutput } = await import("../extract-structured-output.js");
+
+    await expect(
+      extractStructuredOutput("text", SCHEMA, makeConfig(), "gpt-4.1"),
+    ).rejects.toThrow(/'gpt-4o-mini'.*OPENAI_API_KEY/s);
+    expect(buildChatModel).not.toHaveBeenCalled();
+    expect(mockInvoke).not.toHaveBeenCalled();
+  });
+
+  it("proxy mode threads the proxy endpoint and token, consulting no keys", async () => {
+    const { buildChatModel } = await import("../../../shared/model-client.js");
+    const { extractStructuredOutput } = await import("../extract-structured-output.js");
+    mockInvoke.mockResolvedValueOnce({ answer: "ok" });
+
+    const result = await extractStructuredOutput(
+      "text", SCHEMA,
+      makeConfig({ proxyEndpoint: "https://api.stigmer.ai", stigmerToken: "tok" }),
+      "gpt-4.1",
+    );
+
+    expect(result).toEqual({ answer: "ok" });
+    expect(buildChatModel).toHaveBeenCalledWith(
+      expect.objectContaining({
+        proxyEndpoint: "https://api.stigmer.ai",
+        stigmerToken: "tok",
+      }),
+    );
+  });
+
+  it("defers an un-inferable extraction model to buildChatModel's own error", async () => {
+    // The registry-empty fallback returns the primary model verbatim; when
+    // its provider can't be inferred the pre-check must not guess — the
+    // construction path owns the precise message.
+    const { getEconomyModel } = await import("../../../shared/model-registry.js");
+    vi.mocked(getEconomyModel).mockResolvedValueOnce("mystery-model");
+    const { buildChatModel } = await import("../../../shared/model-client.js");
+    const { extractStructuredOutput } = await import("../extract-structured-output.js");
+    mockInvoke.mockResolvedValueOnce({ answer: "ok" });
+
+    await extractStructuredOutput("text", SCHEMA, makeConfig(), "mystery-model");
+
+    expect(buildChatModel).toHaveBeenCalledWith(
+      expect.objectContaining({ modelName: "mystery-model" }),
+    );
+  });
+
+  it("normalizes an empty extraction result to null", async () => {
+    vi.stubEnv("OPENAI_API_KEY", "sk-direct");
+    const { extractStructuredOutput } = await import("../extract-structured-output.js");
+    mockInvoke.mockResolvedValueOnce(undefined);
+
+    const result = await extractStructuredOutput("text", SCHEMA, makeConfig(), "gpt-4.1");
+
+    expect(result).toBeNull();
+  });
+});

package/src/activities/execute-cursor/__tests__/hook-script.test.ts

@@ -245,6 +245,99 @@ d("generated approval hook (preToolUse + beforeMCPExecution)", () => {
     });
   });
 
+  // The enabled_tools capability manifest (issue #350): mcpServerEnabledTools
+  // holds ONLY restricted servers; the hook denies a listed server's
+  // non-listed tool with the non-pausing, permanent "disabled" kind — BEFORE
+  // autoApproveAll and the grant checks, because a manifest is not an
+  // approval gate (nothing may resurrect a disabled tool). hookMcp payloads
+  // carry mcp_server_name "srv".
+  describe("MCP enabled_tools manifest (beforeMCPExecution, issue #350)", () => {
+    it("denies a non-enabled tool with kind disabled (content-free, single record) and the manifest message", () => {
+      const h = setup({ mcpServerEnabledTools: { srv: ["list_apps"] } });
+
+      const res = h.decide(hookMcp("click", { app: "Slack" }));
+
+      expect(res.permission).toBe("deny");
+      // Permanent-denial framing, never the approval promise: the model must
+      // adapt, not wait for a resume that will never come.
+      expect(res.raw).toContain("not enabled for this agent");
+      expect(res.raw).not.toContain("submitted to the user for approval");
+      const ledger = h.ledger();
+      expect(ledger).toHaveLength(1);
+      expect(ledger[0].kind).toBe("disabled");
+      // Attributable under the MCP name-token (the identity the stream row
+      // computes), content-free like every non-approval kind.
+      expect(ledger[0].token).toBe(grantToken("click", ""));
+      expect(ledger[0]).not.toHaveProperty("input");
+    });
+
+    it("allows an enabled tool on a restricted server", () => {
+      const h = setup({ mcpServerEnabledTools: { srv: ["list_apps"] } });
+      expect(h.decide(hookMcp("list_apps")).permission).toBe("allow");
+      expect(h.ledger()).toEqual([]);
+    });
+
+    it("denies even under autoApproveAll (a manifest is not an approval gate)", () => {
+      const h = setup({
+        autoApproveAll: true,
+        mcpServerEnabledTools: { srv: ["list_apps"] },
+      });
+      const res = h.decide(hookMcp("click"));
+      expect(res.permission).toBe("deny");
+      expect(h.ledger()[0].kind).toBe("disabled");
+    });
+
+    it("denies even when the tool holds a reinvocation grant (no approval may resurrect it)", () => {
+      const h = setup({
+        mcpServerEnabledTools: { srv: ["list_apps"] },
+        grants: [{ toolName: "click", mcpServerSlug: "srv", key: "click", salient: "", contentDigest: "", sourceToolCallId: "consent-1" }],
+      });
+      const res = h.decide(hookMcp("click"));
+      expect(res.permission).toBe("deny");
+      expect(h.ledger()[0].kind).toBe("disabled");
+    });
+
+    it("stays kind disabled under unattended mode (mode-independent, like secret)", () => {
+      const h = setup({
+        unattendedSkip: true,
+        mcpServerEnabledTools: { srv: ["list_apps"] },
+      });
+      const res = h.decide(hookMcp("click"));
+      expect(res.permission).toBe("deny");
+      expect(h.ledger()[0].kind).toBe("disabled");
+    });
+
+    it("an enabled tool still flows into the normal approval arm (manifest and gate compose)", () => {
+      const h = setup({
+        mcpPolicies: { click: { requiresApproval: true, message: "Approve click?" } },
+        mcpServerEnabledTools: { srv: ["click"] },
+      });
+      const res = h.decide(hookMcp("click"));
+      expect(res.permission).toBe("deny");
+      expect(res.raw).toContain("Approve click?");
+      expect(h.ledger()[0].kind).toBe("approval");
+    });
+
+    it("a restriction on ANOTHER server never narrows this one (server-scoped matching)", () => {
+      const h = setup({ mcpServerEnabledTools: { other: ["something_else"] } });
+      expect(h.decide(hookMcp("click")).permission).toBe("allow");
+      expect(h.ledger()).toEqual([]);
+    });
+
+    it("quoted-name matching is exact — an enabled name never allows its prefix-sibling", () => {
+      const h = setup({ mcpServerEnabledTools: { srv: ["list_apps_extended"] } });
+      const res = h.decide(hookMcp("list_apps"));
+      expect(res.permission).toBe("deny");
+      expect(h.ledger()[0].kind).toBe("disabled");
+    });
+
+    it("never gates a preToolUse (built-in) payload — the manifest arm is MCP-event-scoped", () => {
+      const h = setup({ mcpServerEnabledTools: { srv: ["list_apps"] } });
+      expect(h.decide(hookRead("/x/a.txt")).permission).toBe("allow");
+      expect(h.ledger()).toEqual([]);
+    });
+  });
+
   // The hook captures the COMPLETE tool_input on every denial (base64(JSON)),
   // so the runner can overlay the proposed change onto the gated tool call for
   // the approval preview — the cursor analog of the native harness reading args