fix(node-host): clarify unusable node exec cwd failures (#97105)

clawSean · steipete · web-flow · commit b8c1b220e498 · 2026-07-09T11:34:25.000+01:00
* fix(node-host): clarify unusable exec cwd failures

* fix(node-host): tighten cwd failure diagnostics

* refactor(node-host): keep cwd handling localized

* chore: leave release changelog ownership centralized

---------

Co-authored-by: clawSean &lt;260045960+clawSean@users.noreply.github.com&gt;
Co-authored-by: Peter Steinberger &lt;steipete@gmail.com&gt;
diff --git a/src/node-host/invoke.run-command.test.ts b/src/node-host/invoke.run-command.test.ts
@@ -1,4 +1,7 @@
 import { EventEmitter } from "node:events";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
 import { afterEach, describe, expect, it, vi } from "vitest";
 import { testing } from "./invoke.js";
 
@@ -124,4 +127,93 @@ describe("runCommand", () => {
       error: null,
     });
   });
+
+  describe("working directory failures", () => {
+    const enoent = (message: string) =>
+      Object.assign(new Error(message), { code: "ENOENT" }) as NodeJS.ErrnoException;
+
+    it("blames a missing working directory instead of the shell", () => {
+      const cwd = path.join(os.tmpdir(), `node-exec-missing-${process.pid}-${Date.now()}`);
+      expect(testing.clarifyNodeExecCwdSpawnError(enoent("spawn /bin/sh ENOENT"), cwd)).toBe(
+        `node exec working directory does not exist on the node host: ${cwd} (os reported: spawn /bin/sh ENOENT)`,
+      );
+    });
+
+    it("flags a cwd that exists but is not a directory", () => {
+      const file = path.join(os.tmpdir(), `node-exec-file-${process.pid}-${Date.now()}.txt`);
+      fs.writeFileSync(file, "x");
+      try {
+        const error = Object.assign(new Error("spawn ENOTDIR"), {
+          code: "ENOTDIR",
+        }) as NodeJS.ErrnoException;
+        expect(testing.clarifyNodeExecCwdSpawnError(error, file)).toBe(
+          `node exec working directory is not a directory on the node host: ${file} (os reported: spawn ENOTDIR)`,
+        );
+      } finally {
+        fs.rmSync(file, { force: true });
+      }
+    });
+
+    it("clarifies an asynchronous spawn error for a missing cwd", async () => {
+      const child = createMockChild();
+      mockNextSpawn(child);
+      const cwd = path.join(os.tmpdir(), `node-exec-run-missing-${process.pid}-${Date.now()}`);
+
+      const resultPromise = testing.runCommand(["/bin/sh"], cwd, undefined, undefined);
+      child.emit("error", enoent("spawn /bin/sh ENOENT"));
+
+      await expect(resultPromise).resolves.toMatchObject({
+        success: false,
+        error: expect.stringContaining(
+          `node exec working directory does not exist on the node host: ${cwd}`,
+        ),
+      });
+    });
+
+    it("clarifies a synchronous spawn throw for a cwd that is a file", async () => {
+      const file = path.join(os.tmpdir(), `node-exec-run-file-${process.pid}-${Date.now()}.txt`);
+      fs.writeFileSync(file, "x");
+      vi.mocked(spawn).mockImplementationOnce(() => {
+        throw Object.assign(new Error("spawn ENOTDIR"), { code: "ENOTDIR" });
+      });
+      try {
+        await expect(
+          testing.runCommand(["/bin/sh"], file, undefined, undefined),
+        ).resolves.toMatchObject({
+          success: false,
+          error: expect.stringContaining(
+            `node exec working directory is not a directory on the node host: ${file}`,
+          ),
+        });
+      } finally {
+        fs.rmSync(file, { force: true });
+      }
+    });
+
+    it("preserves genuine executable and unrelated spawn errors", () => {
+      const missingExecutable = "spawn /usr/bin/does-not-exist ENOENT";
+      expect(testing.clarifyNodeExecCwdSpawnError(enoent(missingExecutable), os.tmpdir())).toBe(
+        missingExecutable,
+      );
+      expect(testing.clarifyNodeExecCwdSpawnError(enoent("spawn /bin/sh ENOENT"), undefined)).toBe(
+        "spawn /bin/sh ENOENT",
+      );
+      const denied = Object.assign(new Error("spawn EACCES"), {
+        code: "EACCES",
+      }) as NodeJS.ErrnoException;
+      expect(testing.clarifyNodeExecCwdSpawnError(denied, "/missing")).toBe("spawn EACCES");
+    });
+
+    it("preserves the spawn error when the cwd cannot be inspected", () => {
+      const message = "spawn /bin/sh ENOENT";
+      const stat = vi.spyOn(fs, "statSync").mockImplementationOnce(() => {
+        throw Object.assign(new Error("permission denied"), { code: "EACCES" });
+      });
+      try {
+        expect(testing.clarifyNodeExecCwdSpawnError(enoent(message), "/unreadable")).toBe(message);
+      } finally {
+        stat.mockRestore();
+      }
+    });
+  });
 });
diff --git a/src/node-host/invoke.ts b/src/node-host/invoke.ts
@@ -270,6 +270,39 @@ function requireExecApprovalsBaseHash(
   }
 }
 
+// libuv reports a failed pre-exec `chdir(cwd)` as `spawn <argv0> ENOENT`, which
+// blames the shell/command instead of the missing working directory (#85202).
+// When the spawn cwd is set but is not a usable directory, name the real cause.
+// Diagnostic only: the run still fails closed — the cwd is never dropped to fall
+// back to the node's default directory.
+function clarifyNodeExecCwdSpawnError(
+  error: NodeJS.ErrnoException,
+  cwd: string | undefined,
+): string {
+  const message = error.message;
+  if (!cwd || (error.code !== "ENOENT" && error.code !== "ENOTDIR")) {
+    return message;
+  }
+  let reason: "does not exist" | "is not a directory";
+  try {
+    const stats = fs.statSync(cwd);
+    // An existing directory means the cwd is fine and the ENOENT is about the
+    // executable itself; leave the original message untouched.
+    if (stats.isDirectory()) {
+      return message;
+    }
+    reason = "is not a directory";
+  } catch (statError) {
+    const statCode = (statError as NodeJS.ErrnoException).code;
+    if (statCode !== "ENOENT" && statCode !== "ENOTDIR") {
+      return message;
+    }
+    reason =
+      statCode === "ENOTDIR" || error.code === "ENOTDIR" ? "is not a directory" : "does not exist";
+  }
+  return `node exec working directory ${reason} on the node host: ${cwd} (os reported: ${message})`;
+}
+
 async function runCommand(
   argv: string[],
   cwd: string | undefined,
@@ -285,12 +318,29 @@ async function runCommand(
     let settled = false;
     const windowsEncoding = resolveWindowsConsoleEncoding();
 
-    const child = spawn(argv[0], argv.slice(1), {
-      cwd,
-      env,
-      stdio: ["ignore", "pipe", "pipe"],
-      windowsHide: true,
-    });
+    // A cwd that exists but is not a directory makes `spawn` throw ENOTDIR
+    // synchronously instead of emitting `error`. Keep that failure inside the
+    // node result because runner.ts intentionally dispatches invokes with `void`.
+    let child: ReturnType<typeof spawn>;
+    try {
+      child = spawn(argv[0], argv.slice(1), {
+        cwd,
+        env,
+        stdio: ["ignore", "pipe", "pipe"],
+        windowsHide: true,
+      });
+    } catch (err) {
+      resolve({
+        exitCode: undefined,
+        timedOut: false,
+        success: false,
+        stdout: "",
+        stderr: "",
+        error: clarifyNodeExecCwdSpawnError(err as NodeJS.ErrnoException, cwd),
+        truncated: false,
+      });
+      return;
+    }
 
     const onChunk = (chunk: Buffer, target: "stdout" | "stderr") => {
       if (outputLen >= OUTPUT_CAP) {
@@ -383,7 +433,7 @@ async function runCommand(
     child.stderr?.on("error", onStreamError);
     child.on("error", (err) => {
       if (!streamError) {
-        finalize(undefined, err.message);
+        finalize(undefined, clarifyNodeExecCwdSpawnError(err, cwd));
       }
     });
     child.on("exit", (code) => {
@@ -818,5 +868,6 @@ async function sendNodeEvent(client: GatewayClient, event: string, payload: unkn
 
 export const testing = {
   STREAM_ERROR_KILL_GRACE_MS,
+  clarifyNodeExecCwdSpawnError,
   runCommand,
 } as const;
