@vellumai/assistant 0.11.9-staging.2 → 0.11.9

package/src/runtime/routes/__tests__/avatar-state-routes.test.ts

@@ -18,6 +18,12 @@ import type { RouteHandlerArgs } from "../types.js";
 
 const VALID_TRAITS = { bodyShape: "round", eyeStyle: "happy", color: "blue" };
 
+/** A 4x4 PNG of one red (#c81e1e), so an accent can be read out of it. */
+const RED_PNG = Buffer.from(
+  "iVBORw0KGgoAAAANSUhEUgAAAAQAAAAECAYAAACp8Z5+AAAACXBIWXMAAAPoAAAD6AG1e1JrAAAAEklEQVQImWM4ISf3HxkzkC4AAEG4IDHG8wOiAAAAAElFTkSuQmCC",
+  "base64",
+);
+
 const IMAGE_FILENAME = "avatar-image.png";
 const TRAITS_FILENAME = "character-traits.json";
 const ASCII_FILENAME = "character-ascii.txt";
@@ -75,6 +81,7 @@ describe("GET /avatar/state", () => {
       traits: VALID_TRAITS,
       source: "builder",
       image: null,
+      accent: null,
     };
     writeManifest(state, avatarDir);
 
@@ -130,12 +137,9 @@ describe("GET /avatar/state", () => {
 
     chmodSync(avatarDir, 0o555);
     try {
-      let result: AvatarState | undefined;
-      expect(() => {
-        result = getStateHandler()({}) as AvatarState;
-      }).not.toThrow();
-      expect(result!.kind).toBe("character");
-      expect(result!.traits).toEqual(VALID_TRAITS);
+      const result = await getStateHandler()({});
+      expect(result.kind).toBe("character");
+      expect(result.traits).toEqual(VALID_TRAITS);
       // Persist failed, so no manifest was written.
       expect(existsSync(join(avatarDir, MANIFEST_FILENAME))).toBe(false);
     } finally {
@@ -145,21 +149,70 @@ describe("GET /avatar/state", () => {
   });
 
   test("returns kind:none WITHOUT persisting a manifest for an empty workspace (no throw, no 404)", async () => {
-    let result: AvatarState | undefined;
-    expect(() => {
-      result = getStateHandler()({}) as AvatarState;
-    }).not.toThrow();
+    const result = await getStateHandler()({});
     expect(result).toEqual({
       kind: "none",
       traits: null,
       source: null,
       image: null,
+      accent: null,
     });
 
     // `none` is deliberately NOT persisted — the workspace stays manifest-less
     // so a later legacy sidecar write is still picked up by the next self-heal.
     expect(existsSync(join(avatarDir, MANIFEST_FILENAME))).toBe(false);
   });
+
+  test("backfills the accent of an image manifest written before accents existed, and persists it", async () => {
+    writeFileSync(join(avatarDir, "avatar-image.png"), RED_PNG);
+    const state: AvatarState = {
+      kind: "image",
+      traits: null,
+      source: "upload",
+      image: { updatedAt: "2026-01-01T00:00:00.000Z", etag: "red-etag-1" },
+      accent: null,
+    };
+    writeManifest(state, avatarDir);
+
+    const result = await getStateHandler()({});
+    expect(result.accent).toEqual({ hex: "#c81e1e", source: "derived" });
+    const persisted = JSON.parse(
+      readFileSync(join(avatarDir, MANIFEST_FILENAME), "utf-8"),
+    ) as AvatarState;
+    expect(persisted).toEqual(result);
+  });
+
+  test("backfills a character's palette accent", async () => {
+    const state: AvatarState = {
+      kind: "character",
+      traits: { ...VALID_TRAITS, color: "orange" },
+      source: "builder",
+      image: null,
+      accent: null,
+    };
+    writeManifest(state, avatarDir);
+
+    const result = await getStateHandler()({});
+    expect(result.accent).toEqual({ hex: "#E9642F", source: "palette" });
+  });
+
+  test("leaves the accent null for an image that cannot be decoded, without failing the read", async () => {
+    writeFileSync(
+      join(avatarDir, "avatar-image.png"),
+      Buffer.from("not a png"),
+    );
+    const state: AvatarState = {
+      kind: "image",
+      traits: null,
+      source: "upload",
+      image: { updatedAt: "2026-01-01T00:00:00.000Z", etag: "bad-etag-1" },
+      accent: null,
+    };
+    writeManifest(state, avatarDir);
+
+    const result = await getStateHandler()({});
+    expect(result).toEqual(state);
+  });
 });
 
 /**
@@ -197,6 +250,7 @@ describe("avatar write/remove handlers", () => {
     traits: Record<string, unknown> | null;
     source: string | null;
     image: { updatedAt: string; etag: string } | null;
+    accent: { hex: string; source: string } | null;
   }
 
   const readManifestFile = (): ManifestShape | null => {
@@ -273,11 +327,11 @@ describe("avatar write/remove handlers", () => {
       expect(manifest!.image!.etag).toMatch(/^[0-9a-f]{16}$/);
     });
 
-    test("rejects an imagePath outside the workspace", () => {
+    test("rejects an imagePath outside the workspace", async () => {
       const handler = getHandler("avatar_set");
-      expect(() => handler({ body: { imagePath: "/etc/passwd" } })).toThrow(
-        /must resolve inside the workspace/,
-      );
+      await expect(
+        handler({ body: { imagePath: "/etc/passwd" } }),
+      ).rejects.toThrow(/must resolve inside the workspace/);
     });
   });
 
@@ -310,6 +364,17 @@ describe("avatar write/remove handlers", () => {
       expect(manifest!.traits).toBeNull();
       expect(manifest!.source).toBe("upload");
       expect(manifest!.image!.etag).toMatch(/^[0-9a-f]{16}$/);
+      // A signature with no pixels behind it has no colour to read.
+      expect(manifest!.accent).toBeNull();
+    });
+
+    test("reads the accent out of the uploaded image", async () => {
+      const handler = getHandler("avatar_upload_image");
+      await handler({ body: { content: RED_PNG.toString("base64") } });
+      expect(readManifestFile()!.accent).toEqual({
+        hex: "#c81e1e",
+        source: "derived",
+      });
     });
 
     test("accepts a base64 payload without an explicit encoding field", async () => {
@@ -321,41 +386,41 @@ describe("avatar write/remove handlers", () => {
       expect(readManifestFile()!.kind).toBe("image");
     });
 
-    test("rejects a missing content field with 400 and writes no manifest", () => {
+    test("rejects a missing content field with 400 and writes no manifest", async () => {
       const handler = getHandler("avatar_upload_image");
-      expect(() => handler({ body: {} })).toThrow(/content/);
+      await expect(handler({ body: {} })).rejects.toThrow(/content/);
       expect(readManifestFile()).toBeNull();
     });
 
-    test("rejects a non-base64 / non-image payload with 400", () => {
+    test("rejects a non-base64 / non-image payload with 400", async () => {
       const handler = getHandler("avatar_upload_image");
       // Valid base64 but decodes to plain text — not a supported image.
-      expect(() =>
+      await expect(
         handler({
           body: { content: Buffer.from("not an image").toString("base64") },
         }),
-      ).toThrow(/PNG|JPEG|GIF|WEBP|image/);
+      ).rejects.toThrow(/PNG|JPEG|GIF|WEBP|image/);
       expect(readManifestFile()).toBeNull();
     });
 
-    test("rejects an unsupported encoding with 400", () => {
+    test("rejects an unsupported encoding with 400", async () => {
       const handler = getHandler("avatar_upload_image");
-      expect(() =>
+      await expect(
         handler({
           body: { content: PNG_BYTES.toString("base64"), encoding: "hex" },
         }),
-      ).toThrow(/encoding/);
+      ).rejects.toThrow(/encoding/);
       expect(readManifestFile()).toBeNull();
     });
 
-    test("rejects malformed base64 (valid image prefix + illegal chars) with 400", () => {
+    test("rejects malformed base64 (valid image prefix + illegal chars) with 400", async () => {
       const handler = getHandler("avatar_upload_image");
       // A valid PNG prefix followed by characters outside the base64 alphabet.
       // Without strict validation, Buffer.from(.., "base64") would silently
       // drop the illegal suffix and decode a truncated-but-PNG-magic buffer,
       // accepting a corrupt avatar. Strict validation must reject it up front.
       const malformed = `${PNG_BYTES.toString("base64")}!!!@@@***`;
-      expect(() => handler({ body: { content: malformed } })).toThrow(
+      await expect(handler({ body: { content: malformed } })).rejects.toThrow(
         /valid base64/,
       );
       expect(existsSync(path(IMAGE_FILENAME))).toBe(false);
@@ -363,6 +428,56 @@ describe("avatar write/remove handlers", () => {
     });
   });
 
+  describe("POST /avatar/accent", () => {
+    const uploadRed = async () => {
+      await getHandler("avatar_upload_image")({
+        body: { content: RED_PNG.toString("base64") },
+      });
+    };
+
+    test("sets a custom accent over an image and returns the state as written", async () => {
+      await uploadRed();
+      const result = (await getHandler("avatar_set_accent")({
+        body: { hex: " #12AB34 " },
+      })) as AvatarState;
+      expect(result.kind).toBe("image");
+      expect(result.accent).toEqual({ hex: "#12ab34", source: "custom" });
+      expect(readManifestFile()!.accent).toEqual({
+        hex: "#12ab34",
+        source: "custom",
+      });
+      // Only the manifest changes; the image is untouched.
+      expect(readFileSync(path(IMAGE_FILENAME))).toEqual(RED_PNG);
+    });
+
+    test("null hands the accent back to the colour read out of the image", async () => {
+      await uploadRed();
+      await getHandler("avatar_set_accent")({ body: { hex: "#12ab34" } });
+      const result = (await getHandler("avatar_set_accent")({
+        body: { hex: null },
+      })) as AvatarState;
+      expect(result.accent).toEqual({ hex: "#c81e1e", source: "derived" });
+    });
+
+    test("rejects a hex that is not #rrggbb and leaves the manifest alone", async () => {
+      await uploadRed();
+      await expect(
+        getHandler("avatar_set_accent")({ body: { hex: "red" } }),
+      ).rejects.toThrow(/#rrggbb/);
+      expect(readManifestFile()!.accent).toEqual({
+        hex: "#c81e1e",
+        source: "derived",
+      });
+    });
+
+    test("rejects when there is no avatar to colour", async () => {
+      await expect(
+        getHandler("avatar_set_accent")({ body: { hex: "#12ab34" } }),
+      ).rejects.toThrow(/No avatar/);
+      expect(readManifestFile()).toBeNull();
+    });
+  });
+
   describe("POST /avatar/remove", () => {
     test("clears everything to kind:none (revert-to-character branch gone)", async () => {
       // Seed an image plus legacy character artifacts.
@@ -385,7 +500,7 @@ describe("avatar write/remove handlers", () => {
       // none == absence: the manifest is deleted, not written as kind:none.
       expect(readManifestFile()).toBeNull();
       // A subsequent read still derives kind:none for the empty workspace.
-      expect((getStateHandler()({}) as AvatarState).kind).toBe("none");
+      expect((await getStateHandler()({})).kind).toBe("none");
     });
 
     test("reports hadAvatar:true for a character-only workspace (traits, no PNG)", async () => {
@@ -397,6 +512,7 @@ describe("avatar write/remove handlers", () => {
         traits: VALID_TRAITS,
         source: "builder",
         image: null,
+        accent: null,
       };
       writeManifest(state, avatarDir);
       writeFileSync(path(TRAITS_FILENAME), JSON.stringify(VALID_TRAITS));
@@ -412,7 +528,7 @@ describe("avatar write/remove handlers", () => {
       expect(existsSync(path(TRAITS_FILENAME))).toBe(false);
       // none == absence: the manifest is deleted, and a read derives none.
       expect(readManifestFile()).toBeNull();
-      expect((getStateHandler()({}) as AvatarState).kind).toBe("none");
+      expect((await getStateHandler()({})).kind).toBe("none");
     });
 
     test("reports hadAvatar:false and leaves no manifest when nothing exists", async () => {
@@ -471,6 +587,7 @@ describe("GET /avatar/get (manifest-driven precedence)", () => {
       traits: null,
       source: "upload",
       image: { updatedAt: new Date().toISOString(), etag: "deadbeefdeadbeef" },
+      accent: null,
     };
     writeManifest(state, avatarDir);
 
@@ -486,6 +603,7 @@ describe("GET /avatar/get (manifest-driven precedence)", () => {
       traits: null,
       source: "upload",
       image: { updatedAt: new Date().toISOString(), etag: "deadbeefdeadbeef" },
+      accent: null,
     };
     writeManifest(state, avatarDir);
 
@@ -506,6 +624,7 @@ describe("GET /avatar/get (manifest-driven precedence)", () => {
       traits: VALID_TRAITS,
       source: "builder",
       image: null,
+      accent: null,
     };
     writeManifest(state, avatarDir);
 
@@ -524,6 +643,7 @@ describe("GET /avatar/get (manifest-driven precedence)", () => {
       traits: VALID_TRAITS,
       source: "builder",
       image: null,
+      accent: null,
     };
     writeManifest(state, avatarDir);
 
@@ -534,7 +654,7 @@ describe("GET /avatar/get (manifest-driven precedence)", () => {
 
   test("returns exists:false for a none manifest", async () => {
     writeManifest(
-      { kind: "none", traits: null, source: null, image: null },
+      { kind: "none", traits: null, source: null, image: null, accent: null },
       avatarDir,
     );
 

package/src/runtime/routes/avatar-routes.ts

@@ -2,7 +2,10 @@ import { existsSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 
 import { getCharacterComponents } from "@vellumai/avatar-catalog";
-import { AVATAR_TRAITS_FILENAME } from "@vellumai/avatar-manifest";
+import {
+  AVATAR_TRAITS_FILENAME,
+  normalizeAvatarAccentHex,
+} from "@vellumai/avatar-manifest";
 import { z } from "zod";
 
 import { renderCharacterAscii } from "../../avatar/ascii-renderer.js";
@@ -13,7 +16,9 @@ import {
   writeManifest,
 } from "../../avatar/avatar-manifest.js";
 import {
+  backfillAccent,
   clearAvatar,
+  setAccent,
   setCharacter,
   setImage,
 } from "../../avatar/avatar-store.js";
@@ -81,12 +86,38 @@ function readManifestSelfHealing(): AvatarState {
  * Return the authoritative avatar render state.
  *
  * Reads the manifest (`avatar.json`). When the manifest is absent it is
- * self-healed once from the legacy sidecar files and persisted. Never 404s —
- * an empty workspace yields `{ kind: "none", traits: null, source: null,
- * image: null }`.
+ * self-healed once from the legacy sidecar files and persisted, and a manifest
+ * written before accents existed has its accent filled in the same way. Never
+ * 404s: an empty workspace yields `{ kind: "none" }` with every other field
+ * null.
  */
 function handleGetAvatarState() {
-  return readManifestSelfHealing();
+  return backfillAccent(readManifestSelfHealing());
+}
+
+/**
+ * Set the accent over the current avatar, or hand it back to the automatic
+ * one. Returns the state as written so the caller can paint without a
+ * second read.
+ */
+async function handleSetAvatarAccent({ body, headers }: RouteHandlerArgs) {
+  const payload = body as Record<string, unknown> | undefined;
+  const raw = payload?.hex;
+  let hex: string | null = null;
+  if (raw !== null && raw !== undefined) {
+    hex = normalizeAvatarAccentHex(raw);
+    if (!hex) {
+      throw new BadRequestError("hex must be a #rrggbb colour, or null");
+    }
+  }
+
+  const state = await setAccent(hex);
+  if (!state) {
+    throw new BadRequestError("No avatar to set an accent on");
+  }
+
+  publishAvatarChanged(headers?.["x-vellum-client-id"]?.trim() || undefined);
+  return state;
 }
 
 function handleRenderFromTraits({ body, headers }: RouteHandlerArgs) {
@@ -147,7 +178,7 @@ async function handleGenerateAvatar({ body, headers }: RouteHandlerArgs) {
 
   // Route through the store: atomically writes the PNG, removes the now-stale
   // character sidecars (traits + ASCII), and records an AI-sourced manifest.
-  setImage(result.pngBuffer, "ai");
+  await setImage(result.pngBuffer, "ai");
 
   publishAvatarChanged(headers?.["x-vellum-client-id"]?.trim() || undefined);
   return { ok: true, message: result.content };
@@ -159,7 +190,7 @@ async function handleGenerateAvatar({ body, headers }: RouteHandlerArgs) {
  * single server-authoritative endpoint: the store atomically writes the PNG,
  * clears the character sidecars, and records an `image` manifest.
  */
-function handleUploadAvatarImage({ body, headers }: RouteHandlerArgs) {
+async function handleUploadAvatarImage({ body, headers }: RouteHandlerArgs) {
   const payload = body as Record<string, unknown> | undefined;
   const content = payload?.content;
   const encoding = payload?.encoding;
@@ -195,13 +226,13 @@ function handleUploadAvatarImage({ body, headers }: RouteHandlerArgs) {
 
   // Route through the store: atomically writes the PNG, removes the now-stale
   // character sidecars (traits + ASCII), and records an uploaded-image manifest.
-  setImage(buffer, "upload");
+  await setImage(buffer, "upload");
 
   publishAvatarChanged(headers?.["x-vellum-client-id"]?.trim() || undefined);
   return { ok: true };
 }
 
-function handleSetAvatar({ body, headers }: RouteHandlerArgs) {
+async function handleSetAvatar({ body, headers }: RouteHandlerArgs) {
   const imagePath = (body as Record<string, unknown>)?.imagePath as
     | string
     | undefined;
@@ -227,7 +258,7 @@ function handleSetAvatar({ body, headers }: RouteHandlerArgs) {
 
   // Route through the store so traits sidecars are cleared and the manifest is
   // recorded as an uploaded image atomically (no more stale both-files state).
-  setImage(readFileSync(normalized), "upload");
+  await setImage(readFileSync(normalized), "upload");
 
   publishAvatarChanged(headers?.["x-vellum-client-id"]?.trim() || undefined);
   return { ok: true };
@@ -333,6 +364,31 @@ function handleCharacterAscii({ queryParams, body }: RouteHandlerArgs) {
   return { ascii };
 }
 
+/** The wire shape of `avatar.json`, shared by every route that answers with it. */
+const avatarStateSchema = z.object({
+  kind: z.enum(["character", "image", "none"]),
+  traits: z
+    .object({
+      bodyShape: z.string(),
+      eyeStyle: z.string(),
+      color: z.string(),
+    })
+    .nullable(),
+  source: z.enum(["builder", "upload", "ai"]).nullable(),
+  image: z
+    .object({
+      updatedAt: z.string(),
+      etag: z.string(),
+    })
+    .nullable(),
+  accent: z
+    .object({
+      hex: z.string(),
+      source: z.enum(["palette", "derived", "custom"]),
+    })
+    .nullable(),
+});
+
 export const ROUTES: RouteDefinition[] = [
   {
     operationId: "avatar_character_components",
@@ -384,25 +440,25 @@ export const ROUTES: RouteDefinition[] = [
     handler: handleGetAvatarState,
     summary: "Get avatar state",
     description:
-      "Return the authoritative avatar render mode (character, image, or none).",
+      "Return the authoritative avatar render mode (character, image, or none) and its accent colour.",
     tags: ["avatar"],
-    responseBody: z.object({
-      kind: z.enum(["character", "image", "none"]),
-      traits: z
-        .object({
-          bodyShape: z.string(),
-          eyeStyle: z.string(),
-          color: z.string(),
-        })
-        .nullable(),
-      source: z.enum(["builder", "upload", "ai"]).nullable(),
-      image: z
-        .object({
-          updatedAt: z.string(),
-          etag: z.string(),
-        })
-        .nullable(),
-    }),
+    responseBody: avatarStateSchema,
+  },
+  {
+    operationId: "avatar_set_accent",
+    endpoint: "avatar/accent",
+    method: "POST",
+    policy: {
+      requiredScopes: ["settings.write"],
+      allowedPrincipalTypes: ACTOR_PRINCIPALS,
+    },
+    handler: handleSetAvatarAccent,
+    summary: "Set avatar accent",
+    description:
+      "Set the accent colour over the current avatar as #rrggbb, or null to return to the automatic one (the character's palette colour, or the colour read out of the uploaded image).",
+    tags: ["avatar"],
+    requestBody: z.object({ hex: z.string().nullable() }),
+    responseBody: avatarStateSchema,
   },
   {
     operationId: "avatar_render_from_traits",

package/src/runtime/routes/settings-routes.ts

@@ -117,7 +117,7 @@ async function handleGenerateAvatar({ body = {}, headers }: RouteHandlerArgs) {
 
     // Route through the store so traits sidecars are cleared and the manifest
     // is recorded as an AI-sourced image atomically.
-    setImage(result.pngBuffer, "ai");
+    await setImage(result.pngBuffer, "ai");
 
     const avatarPath = getAvatarImagePath();
 

package/src/tools/terminal/__tests__/safe-env.test.ts

@@ -1,4 +1,14 @@
-import { afterEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  afterAll,
+  afterEach,
+  beforeAll,
+  describe,
+  expect,
+  test,
+} from "bun:test";
 
 import {
   buildSanitizedEnv,
@@ -98,3 +108,52 @@ describe("safe-env Windows forwarding", () => {
     expect(windowsEnv.COMSPEC).toBe("C:\\Windows\\System32\\cmd.exe");
   });
 });
+
+describe("safe-env PATH scrubbing", () => {
+  let root: string;
+  let shimDir: string;
+  let realNodeDir: string;
+  let emptyDir: string;
+
+  beforeAll(() => {
+    // Directly under a temp root, so it matches the shape Bun synthesizes.
+    shimDir = mkdtempSync(join(tmpdir(), "bun-node-"));
+    root = mkdtempSync(join(tmpdir(), "safe-env-path-"));
+    realNodeDir = join(root, "real-bin");
+    emptyDir = join(root, "empty-bin");
+    mkdirSync(realNodeDir);
+    mkdirSync(emptyDir);
+    writeFileSync(join(realNodeDir, "node"), "", { mode: 0o755 });
+  });
+
+  afterAll(() => {
+    rmSync(shimDir, { recursive: true, force: true });
+    rmSync(root, { recursive: true, force: true });
+  });
+
+  test("drops Bun's synthesized node shim dir, keeping the rest in order", () => {
+    const env = buildSanitizedEnv("linux", {
+      PATH: `${shimDir}:${realNodeDir}:/usr/bin:/bin`,
+    });
+
+    expect(env.PATH).toBe(`${realNodeDir}:/usr/bin:/bin`);
+  });
+
+  test("keeps a similarly named directory outside the temp dir", () => {
+    const env = buildSanitizedEnv("linux", {
+      PATH: `${realNodeDir}:/home/assistant/bun-node-tools:/usr/bin`,
+    });
+
+    expect(env.PATH).toBe(
+      `${realNodeDir}:/home/assistant/bun-node-tools:/usr/bin`,
+    );
+  });
+
+  test("keeps the shim when it is the only node on PATH", () => {
+    const env = buildSanitizedEnv("linux", {
+      PATH: `${shimDir}:${emptyDir}`,
+    });
+
+    expect(env.PATH).toBe(`${shimDir}:${emptyDir}`);
+  });
+});

package/src/tools/terminal/safe-env.ts

@@ -5,7 +5,8 @@
  *
  * Shared by the sandbox bash tool and skill sandbox runner.
  */
-import { readdirSync } from "node:fs";
+import { readdirSync, statSync } from "node:fs";
+import { tmpdir } from "node:os";
 
 import { pathListDelimiter } from "@vellumai/environments/shell";
 
@@ -169,6 +170,69 @@ function kataPythonPaths(dataRoot: string): string[] {
   ];
 }
 
+// Bun synthesizes a `node` shim directory (<temp>/bun-node-<hash>/, holding
+// `node` and `bun` symlinks to itself) and prepends it to PATH whenever it
+// starts with no real Node on PATH. That `node` is Bun, which runs a Node CLI
+// under different semantics, so it must never shadow a real interpreter in a
+// sandbox subprocess. It stays when it is the only `node` there is: on a native
+// install (Bun only, no Node) removing it would break every `#!/usr/bin/env
+// node` CLI outright.
+function bunNodeShimParents(sourceEnv: NodeJS.ProcessEnv): string[] {
+  const roots = [
+    tmpdir(),
+    "/tmp",
+    sourceEnv.TMPDIR,
+    sourceEnv.TEMP,
+    sourceEnv.TMP,
+  ];
+  return roots
+    .filter((root): root is string => Boolean(root))
+    .map((root) => root.replace(/[\\/]+$/, ""));
+}
+
+function hasNodeExecutable(dir: string): boolean {
+  for (const name of ["node", "node.exe"]) {
+    try {
+      if (statSync(`${dir}/${name}`).isFile()) {
+        return true;
+      }
+    } catch {
+      // Entry missing or unreadable: not a Node interpreter we can use.
+    }
+  }
+  return false;
+}
+
+function stripBunNodeShimDirs(
+  value: string,
+  sourceEnv: NodeJS.ProcessEnv,
+): string {
+  const parents = bunNodeShimParents(sourceEnv);
+  const separator = pathListDelimiter();
+  const entries = value.split(separator);
+  const kept = entries.filter((entry) => {
+    const normalized = entry.replace(/[\\/]+$/, "");
+    const cut = Math.max(
+      normalized.lastIndexOf("/"),
+      normalized.lastIndexOf("\\"),
+    );
+    if (cut < 0) {
+      return true;
+    }
+    return !(
+      normalized.slice(cut + 1).startsWith("bun-node-") &&
+      parents.includes(normalized.slice(0, cut))
+    );
+  });
+  if (kept.length === entries.length) {
+    return value;
+  }
+  if (!kept.some(hasNodeExecutable)) {
+    return value;
+  }
+  return kept.join(separator);
+}
+
 /**
  * Keys that buildSanitizedEnv always injects into the returned env,
  * independent of what is present in process.env.
@@ -245,6 +309,11 @@ export function buildSanitizedEnv(
       );
     }
   }
+  // Runs after the kata entries are in place: a Node installed into the
+  // persistent apt chroot is what makes dropping Bun's shim safe there.
+  if (env.PATH != null) {
+    env.PATH = stripBunNodeShimDirs(env.PATH, sourceEnv);
+  }
   // Always inject an internal gateway base for local control-plane/API calls.
   const internalGatewayBase = getGatewayInternalBaseUrl();
   env.INTERNAL_GATEWAY_BASE_URL = internalGatewayBase;