@vellumai/assistant 0.11.4 → 0.11.5-staging.1

package/src/__tests__/image-conversion.test.ts

@@ -6,13 +6,16 @@
  * gated on darwin.
  */
 
-import { mkdtempSync, writeFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, mkdtempSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { beforeAll, describe, expect, test } from "bun:test";
 
 import {
   convertImageToJpeg,
+  hasValidJpegStructure,
+  isCompleteJpeg,
   isHeifImage,
   jpegFilenameFor,
   normalizeImageBase64,
@@ -131,6 +134,119 @@ describe("sniffImageMimeType", () => {
   });
 });
 
+describe("isCompleteJpeg", () => {
+  test("accepts SOI...EOI framed payloads", () => {
+    expect(
+      isCompleteJpeg(Buffer.from([0xff, 0xd8, 0xff, 0xe0, 0xff, 0xd9])),
+    ).toBe(true);
+  });
+
+  test("rejects empty, truncated, and non-JPEG payloads", () => {
+    expect(isCompleteJpeg(Buffer.alloc(0))).toBe(false);
+    // Valid head, torn tail: the poisoned-cache signature.
+    expect(isCompleteJpeg(Buffer.from([0xff, 0xd8, 0xff, 0xe0, 0x00]))).toBe(
+      false,
+    );
+    expect(isCompleteJpeg(PNG_1PX_BYTES)).toBe(false);
+  });
+});
+
+// Mirrors the converter's cache-key derivation so the test can plant a
+// poisoned entry at the exact path a conversion will consult.
+function cacheKeyFor(bytes: Uint8Array, quality: number): string {
+  const hash = createHash("sha256").update(bytes).digest("hex").slice(0, 16);
+  return `${hash}-full-q${quality}`;
+}
+
+// Minimal structurally valid JPEG: SOI, APP0 (len 4, 2 payload bytes),
+// SOF0 (len 5, 3 payload bytes), SOS (len 3, 1 payload byte), entropy data
+// with a stuffed FF, then EOI.
+function minimalJpeg(extra: {
+  trailing?: Uint8Array;
+  dropEoi?: boolean;
+}): Buffer {
+  const parts: Uint8Array[] = [
+    Buffer.from([0xff, 0xd8]), // SOI
+    Buffer.from([0xff, 0xe0, 0x00, 0x04, 0x4a, 0x46]), // APP0
+    Buffer.from([0xff, 0xc0, 0x00, 0x05, 0x08, 0x00, 0x01]), // SOF0
+    Buffer.from([0xff, 0xda, 0x00, 0x03, 0x01]), // SOS header
+    Buffer.from([0x12, 0xff, 0x00, 0x34]), // entropy data with stuffed FF
+  ];
+  if (!extra.dropEoi) {
+    parts.push(Buffer.from([0xff, 0xd9])); // EOI
+  }
+  if (extra.trailing) {
+    parts.push(extra.trailing);
+  }
+  return Buffer.concat(parts);
+}
+
+describe("hasValidJpegStructure", () => {
+  test("accepts a JPEG with trailing bytes after the EOI marker", () => {
+    // Some encoders append padding or metadata past the EOI; the structural
+    // walk tolerates it where isCompleteJpeg's exact tail framing does not.
+    const padded = minimalJpeg({ trailing: Buffer.from([0x00, 0x00]) });
+    expect(hasValidJpegStructure(padded)).toBe(true);
+    expect(isCompleteJpeg(padded)).toBe(false);
+  });
+
+  test("accepts restart markers inside entropy-coded data", () => {
+    const withRst = Buffer.concat([
+      Buffer.from([0xff, 0xd8]),
+      Buffer.from([0xff, 0xc0, 0x00, 0x05, 0x08, 0x00, 0x01]), // SOF0
+      Buffer.from([0xff, 0xda, 0x00, 0x03, 0x01]),
+      Buffer.from([0x12, 0xff, 0xd0, 0x34]), // RST0 continues the scan
+      Buffer.from([0xff, 0xd9]),
+    ]);
+    expect(hasValidJpegStructure(withRst)).toBe(true);
+  });
+
+  test("rejects a truncated JPEG whose metadata segment contains FF D9", () => {
+    // An EXIF-style APP1 payload can embed a complete thumbnail JPEG, so an
+    // FF D9 pair appears inside the segment while the main image is torn. A
+    // raw byte search would accept this; the marker walk skips the segment
+    // payload and reports the truncation.
+    const tornWithThumbnail = Buffer.concat([
+      Buffer.from([0xff, 0xd8]), // SOI
+      Buffer.from([0xff, 0xe1, 0x00, 0x08]), // APP1, length 8
+      Buffer.from([0x45, 0x78, 0xff, 0xd9, 0x00, 0x00]), // payload with FF D9
+      Buffer.from([0xff, 0xda, 0x00, 0x03, 0x01, 0x12, 0x34]), // torn scan
+    ]);
+    expect(hasValidJpegStructure(tornWithThumbnail)).toBe(false);
+  });
+
+  test("rejects truncated JPEGs and non-JPEG payloads", () => {
+    expect(hasValidJpegStructure(minimalJpeg({ dropEoi: true }))).toBe(false);
+    expect(
+      hasValidJpegStructure(Buffer.from([0xff, 0xd8, 0xff, 0xe0, 0x00])),
+    ).toBe(false);
+    expect(hasValidJpegStructure(Buffer.alloc(0))).toBe(false);
+    expect(hasValidJpegStructure(PNG_1PX_BYTES)).toBe(false);
+  });
+
+  test("rejects a top-level EOI with no frame or scan", () => {
+    // Bare SOI+EOI is structurally walkable but carries no image data;
+    // providers reject it, so the gate must too.
+    expect(hasValidJpegStructure(Buffer.from([0xff, 0xd8, 0xff, 0xd9]))).toBe(
+      false,
+    );
+    // A scan without a frame header is equally undecodable.
+    const scanNoFrame = Buffer.concat([
+      Buffer.from([0xff, 0xd8]),
+      Buffer.from([0xff, 0xda, 0x00, 0x03, 0x01, 0x12]),
+      Buffer.from([0xff, 0xd9]),
+    ]);
+    expect(hasValidJpegStructure(scanNoFrame)).toBe(false);
+  });
+
+  test("rejects a segment length that runs past the buffer", () => {
+    // A declared length larger than the remaining bytes is truncation, not a
+    // reason to scan beyond the buffer.
+    const overrun = Buffer.from([0xff, 0xd8, 0xff, 0xe0, 0xff, 0xff, 0x00]);
+    expect(hasValidJpegStructure(overrun)).toBe(false);
+  });
+});
+
 describe("normalizeImageBytes passthrough", () => {
   test("non-HEIF bytes pass through untouched", async () => {
     const result = await normalizeImageBytes("image/png", PNG_1PX_BYTES);
@@ -205,6 +321,9 @@ describe.skipIf(process.platform !== "darwin")(
       const converted = await convertImageToJpeg(heicBytes);
       expect(converted).not.toBeNull();
       expect(startsWithJpegMagic(converted!)).toBe(true);
+      // A real encoder's output must pass the structural walk, or the
+      // compactor gate would drop every legitimately converted image.
+      expect(hasValidJpegStructure(converted!)).toBe(true);
     });
 
     test("conversion options produce distinct outputs (cache key isolation)", async () => {
@@ -228,6 +347,29 @@ describe.skipIf(process.platform !== "darwin")(
       expect(first!.equals(second!)).toBe(true);
     });
 
+    test("a poisoned (truncated) cache entry is discarded, not returned", async () => {
+      // Distinct quality so this test owns its cache key.
+      const quality = 77;
+      const cacheDir = join(tmpdir(), "vellum-optimized-images");
+      mkdirSync(cacheDir, { recursive: true });
+      const poisonedPath = join(
+        cacheDir,
+        `${cacheKeyFor(heicBytes, quality)}.jpg`,
+      );
+      // A torn write: valid JPEG head, no EOI tail. readFromCache must
+      // discard it rather than return it as the converted image.
+      writeFileSync(poisonedPath, Buffer.from([0xff, 0xd8, 0xff, 0xe0, 0x00]));
+
+      const converted = await convertImageToJpeg(heicBytes, { quality });
+      expect(converted).not.toBeNull();
+      expect(isCompleteJpeg(converted!)).toBe(true);
+
+      // The poisoned entry was replaced by the re-converted result.
+      expect(existsSync(poisonedPath)).toBe(true);
+      const { readFileSync } = await import("node:fs");
+      expect(isCompleteJpeg(readFileSync(poisonedPath))).toBe(true);
+    });
+
     test("normalizeImageBytes converts to a JPEG master", async () => {
       const result = await normalizeImageBytes("image/heic", heicBytes);
       expect(result.converted).toBe(true);

package/src/__tests__/inline-skill-load-permissions.test.ts

@@ -26,6 +26,7 @@ process.env.GATEWAY_SECURITY_DIR = join(testDir, "protected");
 
 import {
   installIpcMock,
+  lastIpcParams,
   mockIpcResponse,
 } from "./helpers/gateway-classify-mock.js";
 installIpcMock();
@@ -33,6 +34,7 @@ mockIpcResponse("classify_risk", {
   risk: "low",
   reason: "skill_load",
   matchType: "unknown",
+  scopeOptions: [],
 });
 mockIpcResponse("get_global_thresholds", {
   interactive: "low",
@@ -42,8 +44,7 @@ mockIpcResponse("get_global_thresholds", {
 
 // ── Imports (after mocks) ─────────────────────────────────────────────────
 
-import { check, generateAllowlistOptions } from "../permissions/checker.js";
-import { clearRiskCache } from "../permissions/checker.js";
+import { check, classifyRisk } from "../permissions/checker.js";
 import { _clearGlobalCacheForTesting } from "../permissions/gateway-threshold-reader.js";
 import { setOverridesForTesting } from "./feature-flag-test-helpers.js";
 
@@ -82,13 +83,34 @@ function writeDynamicSkill(
   );
 }
 
+/**
+ * What the gateway skill classifier answers for a load whose params carry
+ * `hasInlineExpansions` (gateway/src/risk/skill-risk-classifier.ts): High,
+ * registry-matched. The daemon does not elevate locally; the gateway is the
+ * one place a dynamic load becomes High.
+ */
+function mockDynamicSkillClassification(): void {
+  mockIpcResponse("classify_risk", {
+    risk: "high",
+    reason:
+      "Skill load with inline command expansions (executes shell commands at load time)",
+    matchType: "registry",
+    scopeOptions: [],
+  });
+}
+
 // ── Tests ─────────────────────────────────────────────────────────────────
 
 describe("inline-command skill_load permissions", () => {
   beforeEach(() => {
-    clearRiskCache();
     _clearGlobalCacheForTesting();
     setOverridesForTesting({});
+    mockIpcResponse("classify_risk", {
+      risk: "low",
+      reason: "skill_load",
+      matchType: "unknown",
+      scopeOptions: [],
+    });
     mockIpcResponse("get_global_thresholds", {
       interactive: "low",
       autonomous: "medium",
@@ -116,6 +138,7 @@ describe("inline-command skill_load permissions", () => {
     test("an uncovered dynamic skill prompts below Full access", async () => {
       ensureSkillsDir();
       writeDynamicSkill("dynamic-prompt", "Dynamic Prompt Skill");
+      mockDynamicSkillClassification();
 
       // interactive threshold "low" (beforeEach) is below the High risk of an
       // inline-command load, so it prompts.
@@ -131,6 +154,7 @@ describe("inline-command skill_load permissions", () => {
     test("an uncovered dynamic skill runs at Full access (high threshold)", async () => {
       ensureSkillsDir();
       writeDynamicSkill("dynamic-full", "Dynamic Full Access Skill");
+      mockDynamicSkillClassification();
       mockIpcResponse("get_global_thresholds", {
         interactive: "high",
         autonomous: "high",
@@ -155,6 +179,7 @@ describe("inline-command skill_load permissions", () => {
         risk: "low",
         reason: "user rule: skill_load_dynamic:dynamic-covered",
         matchType: "user_rule",
+        scopeOptions: [],
       });
 
       const result = await check(
@@ -163,17 +188,12 @@ describe("inline-command skill_load permissions", () => {
         "/tmp",
       );
       expect(result.decision).toBe("allow");
-
-      mockIpcResponse("classify_risk", {
-        risk: "low",
-        reason: "skill_load",
-        matchType: "unknown",
-      });
     });
 
     test("dynamic skill prompts in strict mode (no matching rule)", async () => {
       ensureSkillsDir();
       writeDynamicSkill("dynamic-strict", "Dynamic Strict Skill");
+      mockDynamicSkillClassification();
       mockIpcResponse("get_global_thresholds", {
         interactive: "none",
         autonomous: "none",
@@ -211,43 +231,34 @@ describe("inline-command skill_load permissions", () => {
 
   // ── Allowlist options ────────────────────────────────────────────────
 
-  describe("allowlist options", () => {
-    test("dynamic skill allowlist options use skill_load_dynamic: namespace", async () => {
+  describe("skill metadata sent to the gateway", () => {
+    // The gateway picks the `skill_load_dynamic:` namespace off these flags,
+    // so what the daemon reads from disk decides which rule namespace a user
+    // can save into.
+    test("a skill with inline expansions is sent as dynamic", async () => {
       ensureSkillsDir();
       writeDynamicSkill("dynamic-opts", "Dynamic Opts Skill");
 
-      const options = await generateAllowlistOptions("skill_load", {
-        skill: "dynamic-opts",
-      });
+      await classifyRisk("skill_load", { skill: "dynamic-opts" });
 
-      expect(options.length).toBeGreaterThanOrEqual(1);
-      // All options should use skill_load_dynamic: prefix
-      for (const option of options) {
-        expect(option.pattern).toMatch(/^skill_load_dynamic:/);
-      }
-
-      // Should have an any-version option
-      const anyVersionOption = options.find(
-        (o) => o.pattern === "skill_load_dynamic:dynamic-opts",
-      );
-      expect(anyVersionOption).toBeDefined();
-      expect(anyVersionOption!.description).toBe("This skill (any version)");
+      const metadata = lastIpcParams("classify_risk")?.skillMetadata as
+        | { hasInlineExpansions: boolean; isDynamic: boolean }
+        | undefined;
+      expect(metadata?.hasInlineExpansions).toBe(true);
+      expect(metadata?.isDynamic).toBe(true);
     });
 
-    test("plain skill allowlist options use skill_load: namespace", async () => {
+    test("a plain skill is not sent as dynamic", async () => {
       ensureSkillsDir();
       writePlainSkill("plain-opts", "Plain Opts Skill");
 
-      const options = await generateAllowlistOptions("skill_load", {
-        skill: "plain-opts",
-      });
+      await classifyRisk("skill_load", { skill: "plain-opts" });
 
-      expect(options.length).toBeGreaterThanOrEqual(1);
-      // Should use skill_load: prefix, not skill_load_dynamic:
-      for (const option of options) {
-        expect(option.pattern).toMatch(/^skill_load:/);
-        expect(option.pattern).not.toMatch(/^skill_load_dynamic:/);
-      }
+      const metadata = lastIpcParams("classify_risk")?.skillMetadata as
+        | { hasInlineExpansions: boolean; isDynamic: boolean }
+        | undefined;
+      expect(metadata?.hasInlineExpansions).toBe(false);
+      expect(metadata?.isDynamic).toBe(false);
     });
   });
 });

package/src/__tests__/input-repairs.test.ts

@@ -0,0 +1,207 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, test } from "bun:test";
+
+import type { SkillToolEntry } from "../config/skills.js";
+import {
+  bundledToolInputAliases,
+  bundledToolInputRepairs,
+} from "../tools/shared/input-repairs.js";
+
+const TOOL = "scaffold_managed_skill";
+const FIND_TOOL = "find_similar_skills";
+
+/** The real manifest entries the repairs describe. */
+function manifestEntry(name: string): SkillToolEntry {
+  const manifest = JSON.parse(
+    readFileSync(
+      join(
+        import.meta.dir,
+        "../config/bundled-skills/skill-management/TOOLS.json",
+      ),
+      "utf-8",
+    ),
+  ) as { tools: SkillToolEntry[] };
+  const entry = manifest.tools.find((t) => t.name === name);
+  if (!entry) {
+    throw new Error(`${name} is missing from the skill-management TOOLS.json`);
+  }
+  return entry;
+}
+
+function declaredProperties(name: string): Record<string, { type?: string }> {
+  const schema = manifestEntry(name).input_schema as {
+    properties: Record<string, { type?: string }>;
+  };
+  return schema.properties;
+}
+
+describe("bundledToolInputRepairs: parameter aliases", () => {
+  test("reads `body` as the declared `body_markdown`", () => {
+    const result = bundledToolInputRepairs(TOOL, {
+      skill_id: "deploy",
+      body: "# Deploy\n",
+    });
+    expect(result).toEqual({ skill_id: "deploy", body_markdown: "# Deploy\n" });
+    expect("body" in result).toBe(false);
+  });
+
+  test("never overwrites a call that spells the parameter correctly", () => {
+    const input = { body: "alias", body_markdown: "declared" };
+    const result = bundledToolInputRepairs(TOOL, input);
+    expect(result).toBe(input);
+  });
+
+  test("leaves a tool with no alias table alone", () => {
+    const input = { body: "# Deploy\n" };
+    expect(bundledToolInputRepairs("file_write", input)).toBe(input);
+  });
+
+  test.each([TOOL, FIND_TOOL])(
+    "%s: no alias shadows a parameter the tool declares",
+    (tool) => {
+      const declared = declaredProperties(tool);
+      const aliases = bundledToolInputAliases(tool);
+      expect(aliases.length).toBeGreaterThan(0);
+      for (const alias of aliases) {
+        expect(declared[alias]).toBeUndefined();
+      }
+    },
+  );
+
+  test.each([TOOL, FIND_TOOL])(
+    "%s: every alias targets a parameter the tool declares",
+    (tool) => {
+      const declared = declaredProperties(tool);
+      for (const alias of bundledToolInputAliases(tool)) {
+        const result = bundledToolInputRepairs(tool, { [alias]: "value" });
+        const target = Object.keys(result).find((key) => key !== alias);
+        expect(target).toBeDefined();
+        expect(declared[target!]).toBeDefined();
+      }
+    },
+  );
+
+  test.each([
+    ["title", "name"],
+    ["summary", "description"],
+    ["content", "body_markdown"],
+  ])("reads `%s` as `%s`", (alias, canonical) => {
+    const result = bundledToolInputRepairs(TOOL, { [alias]: "value" });
+    expect(result).toEqual({ [canonical]: "value" });
+  });
+
+  test.each(["description", "query"])(
+    "find_similar_skills reads `%s` as `goal`",
+    (alias) => {
+      const result = bundledToolInputRepairs(FIND_TOOL, {
+        [alias]: "deploy staging",
+      });
+      expect(result).toEqual({ goal: "deploy staging" });
+    },
+  );
+});
+
+describe("bundledToolInputRepairs: files written as a path-keyed map", () => {
+  test("reads string values as each file's contents", () => {
+    const result = bundledToolInputRepairs(TOOL, {
+      files: {
+        "references/failure-modes.md": "The retry loop stalls.",
+        "scripts/run.sh": "echo hi",
+      },
+    });
+    expect(result.files).toEqual([
+      {
+        path: "references/failure-modes.md",
+        content: "The retry loop stalls.",
+      },
+      { path: "scripts/run.sh", content: "echo hi" },
+    ]);
+  });
+
+  test("reads an entry that names content or copy_from", () => {
+    const result = bundledToolInputRepairs(TOOL, {
+      files: {
+        "references/notes.md": { content: "hi" },
+        "scripts/run.sh": { copy_from: "/tmp/run.sh" },
+      },
+    });
+    expect(result.files).toEqual([
+      { path: "references/notes.md", content: "hi" },
+      { path: "scripts/run.sh", copy_from: "/tmp/run.sh" },
+    ]);
+  });
+
+  test("leaves one entry spelling out its own fields, which is a file not a map", () => {
+    const input = { files: { path: "references/notes.md", content: "hi" } };
+    expect(bundledToolInputRepairs(TOOL, input)).toBe(input);
+  });
+
+  test("leaves the whole value when any entry is unreadable", () => {
+    const input = {
+      files: {
+        "references/notes.md": "hi",
+        "scripts/run.sh": { mode: 755 },
+      },
+    };
+    expect(bundledToolInputRepairs(TOOL, input)).toBe(input);
+  });
+
+  test("leaves a map with a blank path", () => {
+    const input = { files: { "   ": "hi" } };
+    expect(bundledToolInputRepairs(TOOL, input)).toBe(input);
+  });
+
+  test("leaves an empty object", () => {
+    const input = { files: {} };
+    expect(bundledToolInputRepairs(TOOL, input)).toBe(input);
+  });
+
+  test("an entry spelling out every declared file property is read as one file", () => {
+    const schema = manifestEntry(TOOL).input_schema as {
+      properties: {
+        files: { items: { properties: Record<string, unknown> } };
+      };
+    };
+    const declared = Object.keys(schema.properties.files.items.properties);
+    expect(declared).toContain("path");
+    const entry = Object.fromEntries(declared.map((key) => [key, "value"]));
+
+    const input = { files: entry };
+    expect(bundledToolInputRepairs(TOOL, input)).toBe(input);
+  });
+
+  test("leaves files that already arrived as an array", () => {
+    const input = { files: [{ path: "references/notes.md", content: "hi" }] };
+    expect(bundledToolInputRepairs(TOOL, input)).toBe(input);
+  });
+});
+
+describe("bundledToolInputRepairs: purity", () => {
+  test("returns the same object when there is nothing to repair", () => {
+    const input = { skill_id: "deploy", body_markdown: "# Deploy\n" };
+    expect(bundledToolInputRepairs(TOOL, input)).toBe(input);
+  });
+
+  test("returns a new object and never mutates the original input", () => {
+    const input = {
+      body: "# Deploy\n",
+      files: { "references/notes.md": "hi" },
+    };
+    const snapshot = JSON.parse(JSON.stringify(input));
+    const result = bundledToolInputRepairs(TOOL, input);
+    expect(result).not.toBe(input);
+    expect(input).toEqual(snapshot);
+  });
+
+  test("repairs an alias and a files map in the same call", () => {
+    const result = bundledToolInputRepairs(TOOL, {
+      body: "# Deploy\n",
+      files: { "references/notes.md": "hi" },
+    });
+    expect(result).toEqual({
+      body_markdown: "# Deploy\n",
+      files: [{ path: "references/notes.md", content: "hi" }],
+    });
+  });
+});

package/src/__tests__/live-workspace-guard.test.ts

@@ -0,0 +1,75 @@
+/**
+ * Tests for the live-workspace guard in util/platform.ts: a test process must
+ * never resolve the workspace to a directory outside os.tmpdir().
+ */
+
+import { rmSync, symlinkSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, test } from "bun:test";
+
+import { getWorkspaceDir } from "../util/platform.js";
+
+const originalWorkspaceDir = process.env.VELLUM_WORKSPACE_DIR;
+const originalAllowReal = process.env.VELLUM_ALLOW_REAL_WORKSPACE_IN_TESTS;
+
+afterEach(() => {
+  process.env.VELLUM_WORKSPACE_DIR = originalWorkspaceDir;
+  if (originalAllowReal === undefined) {
+    delete process.env.VELLUM_ALLOW_REAL_WORKSPACE_IN_TESTS;
+  } else {
+    process.env.VELLUM_ALLOW_REAL_WORKSPACE_IN_TESTS = originalAllowReal;
+  }
+});
+
+describe("live-workspace guard", () => {
+  test("allows the preload's tmpdir workspace", () => {
+    expect(getWorkspaceDir()).toBe(process.env.VELLUM_WORKSPACE_DIR!);
+  });
+
+  test("allows a not-yet-created nested path under tmpdir", () => {
+    const dir = join(
+      tmpdir(),
+      "vellum-guard-nonexistent",
+      "nested",
+      "workspace",
+    );
+    process.env.VELLUM_WORKSPACE_DIR = dir;
+    expect(getWorkspaceDir()).toBe(dir);
+  });
+
+  test("refuses a non-tmpdir workspace in a test process", () => {
+    delete process.env.VELLUM_ALLOW_REAL_WORKSPACE_IN_TESTS;
+    process.env.VELLUM_WORKSPACE_DIR = join(homedir(), "vellum-guard-live");
+    expect(() => getWorkspaceDir()).toThrow(/Refusing to use/);
+  });
+
+  test("refuses a tmpdir symlink that resolves outside tmpdir", () => {
+    delete process.env.VELLUM_ALLOW_REAL_WORKSPACE_IN_TESTS;
+    const link = join(tmpdir(), `vellum-guard-escape-${process.pid}`);
+    rmSync(link, { force: true });
+    symlinkSync(homedir(), link);
+    try {
+      process.env.VELLUM_WORKSPACE_DIR = link;
+      expect(() => getWorkspaceDir()).toThrow(/Refusing to use/);
+    } finally {
+      rmSync(link, { force: true });
+    }
+  });
+
+  test("VELLUM_ALLOW_REAL_WORKSPACE_IN_TESTS=1 bypasses the guard", () => {
+    const dir = join(homedir(), "vellum-guard-live-optout");
+    process.env.VELLUM_WORKSPACE_DIR = dir;
+    process.env.VELLUM_ALLOW_REAL_WORKSPACE_IN_TESTS = "1";
+    expect(getWorkspaceDir()).toBe(dir);
+  });
+
+  test("opt-out is per-call, not cached: same dir throws once the var clears", () => {
+    const dir = join(homedir(), "vellum-guard-live-optout-cleared");
+    process.env.VELLUM_WORKSPACE_DIR = dir;
+    process.env.VELLUM_ALLOW_REAL_WORKSPACE_IN_TESTS = "1";
+    expect(getWorkspaceDir()).toBe(dir);
+    delete process.env.VELLUM_ALLOW_REAL_WORKSPACE_IN_TESTS;
+    expect(() => getWorkspaceDir()).toThrow(/Refusing to use/);
+  });
+});

package/src/__tests__/mcp-abort-signal.test.ts

@@ -12,7 +12,7 @@ mock.module("../config/env-registry.js", () => ({
   getIsContainerized: () => false,
   getIsPlatform: () => false,
   isPlatformRemote: () => false,
-  getWorkspaceDirOverride: () => undefined,
+  getWorkspaceDirOverride: () => process.env.VELLUM_WORKSPACE_DIR,
   getBackupDirOverride: () => undefined,
   getBackupKeyPathOverride: () => undefined,
   getCpuLimit: () => undefined,

package/src/__tests__/mcp-client-auth.test.ts

@@ -12,7 +12,7 @@ mock.module("../config/env-registry.js", () => ({
   getIsContainerized: () => false,
   getIsPlatform: () => false,
   isPlatformRemote: () => false,
-  getWorkspaceDirOverride: () => undefined,
+  getWorkspaceDirOverride: () => process.env.VELLUM_WORKSPACE_DIR,
   getBackupDirOverride: () => undefined,
   getBackupKeyPathOverride: () => undefined,
   getCpuLimit: () => undefined,

package/src/__tests__/mcp-tool-annotations-risk.test.ts

@@ -12,7 +12,7 @@ mock.module("../config/env-registry.js", () => ({
   getIsContainerized: () => false,
   getIsPlatform: () => false,
   isPlatformRemote: () => false,
-  getWorkspaceDirOverride: () => undefined,
+  getWorkspaceDirOverride: () => process.env.VELLUM_WORKSPACE_DIR,
   getBackupDirOverride: () => undefined,
   getBackupKeyPathOverride: () => undefined,
   getCpuLimit: () => undefined,