[Bug + fix] Windows: every npm_execpath-based script fails when pnpm is the standalone (@pnpm/exe) build

[banatic]

Summary

scripts/build.ts, scripts/run-gates.ts, scripts/run-web-snapshots.ts and scripts/coverage-partitions.ts all assume process.env.npm_execpath points at a JS entrypoint and spawn it as node <npm_execpath> ….

With pnpm 11 installed as the standalone build (@pnpm/exe, i.e. the default for the standalone script / winget / npm i -g @pnpm/exe installs), npm_execpath points at a native executable instead:

C:\Users\<user>\AppData\Local\pnpm\global\v11\...\node_modules\@pnpm\exe\pnpm.exe

Node then tries to ESM-load pnpm.exe and dies. pnpm run build fails immediately, and so does check:all / check:ci*, test:coverage:partitioned, and test:web:ci.

This is invisible on a JS-entrypoint install (Corepack, npm i -g pnpm), which is presumably what CI uses, the standalone build is the one the pnpm docs recommend first on Windows.

Repro

Environment:

• Windows 11
• Node v22.18.0
• pnpm 11.7.0, installed as the standalone @pnpm/exe build
• deepseek-harness @ dsh-v0.1.0-rc.8 (141eb6f)

pnpm install
pnpm run build

Result:

$ tsx scripts/build.ts
node:internal/modules/esm/get_format:219
  throw new ERR_UNKNOWN_FILE_EXTENSION(ext, filepath);
        ^

TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ".exe" for
  C:\Users\<user>\AppData\Local\pnpm\store\v11\links\@pnpm\exe\11.7.0\...\node_modules\@pnpm\exe\pnpm.exe
    at Object.getFileProtocolModuleFormat [as file:] (node:internal/modules/esm/get_format:219:9)
    ...
  code: 'ERR_UNKNOWN_FILE_EXTENSION'
}

Error: build: build:lib exited with 1
    at runScript (scripts/build.ts:28:11)

Confirming the environment variable directly (any package script, any directory):

$ pnpm run probe          # "probe": "node -e \"console.log(process.env.npm_execpath)\""
C:\Users\<user>\AppData\Local\pnpm\global\v11\...\node_modules\@pnpm\exe\pnpm.exe

Cause

scripts/build.ts:

const packageManager = process.env.npm_execpath
const result = spawnSync(process.execPath, [packageManager, 'run', script], { … })

node <pnpm.exe> run build:lib cannot work. The same assumption is repeated in three other places:

File	Code
scripts/build.ts	spawnSync(process.execPath, [packageManager, 'run', script], …)
scripts/run-gates.ts (pnpmInvocation)	{ command: process.execPath, args: [entrypoint, ...args] }
scripts/run-web-snapshots.ts	baseArgs = [pnpmEntrypoint, 'exec', 'vitest', …] → spawn(process.execPath, args)
scripts/coverage-partitions.ts	args: [this.pnpmEntrypoint, 'exec', 'vitest', …] → spawn(process.execPath, command.args, …)

The comment in run-gates.ts ("Windows cannot spawn the pnpm.cmd shim directly; the JavaScript entrypoint keeps every host shell-free") shows the intent — staying shell-free — and that intent still holds. It is only the "the entrypoint is always JavaScript" half that no longer does.

Suggested fix

Decide how to spawn based on the entrypoint's extension: wrap it in Node when it is .js/.cjs/.mjs, otherwise spawn the executable directly. Both branches stay shell-free, so the original Windows .cmd-shim problem is still avoided.

A shared helper, scripts/package-manager.ts:

/** Pair the invoking package manager with arguments so every host can spawn it without a shell. */

import { extname } from 'node:path'

/** A shell-free command and argument pair. */
export interface PackageManagerInvocation {
  /** Executable to spawn. */
  command: string
  /** Arguments passed to {@link PackageManagerInvocation.command}. */
  args: string[]
}

const JAVASCRIPT_ENTRYPOINTS = new Set(['.js', '.cjs', '.mjs'])

/** Pair one package manager entrypoint with its arguments. */
export function packageManagerInvocationFor(
  entrypoint: string,
  args: readonly string[],
): PackageManagerInvocation {
  // pnpm ships either a JavaScript entrypoint or a native executable; only the former can be loaded by Node.
  return JAVASCRIPT_ENTRYPOINTS.has(extname(entrypoint).toLowerCase())
    ? { command: process.execPath, args: [entrypoint, ...args] }
    : { command: entrypoint, args: [...args] }
}

/** Pair the package manager named by `npm_execpath` with its arguments. */
export function packageManagerInvocation(
  args: readonly string[],
  context: string,
): PackageManagerInvocation {
  const entrypoint = process.env.npm_execpath
  if (entrypoint === undefined || entrypoint === '') {
    throw new Error(`${context}: npm_execpath is unavailable; invoke the runner through a pnpm package script.`)
  }
  return packageManagerInvocationFor(entrypoint, args)
}

The four call sites then become one-liners, e.g. in scripts/build.ts:

const packageManager = packageManagerInvocation(['run', script], 'build')
const result = spawnSync(packageManager.command, packageManager.args, { … })

CoverageCommand needs one extra command: string field alongside its existing args, since runCoverageCommand currently hardcodes process.execPath. On a JS-entrypoint install every resolved command is byte-identical to today's, so CI behaviour is unchanged.

Verification

On the environment above, after the change:

• pnpm run build → passes, build: recorded 200 client artifact(s) with 1 public value(s)
• pnpm run typecheck:contracts-ready → passes
• oxlint scripts → clean
• vitest run scripts/coverage-partitions.spec.ts scripts/run-gates.spec.ts → 67 passed, 1 skipped

[denial123789]

I traced this against rc.8 (141eb6f) and current master. This is a source-build runner boundary: npm latest still resolves rc.7, while npm next and the GitHub release resolve rc.8. The immediate operator recovery is to use the repository-declared pnpm 11.7.0 through a JavaScript entrypoint (for example, explicit Corepack) and verify that npm_execpath ends in .js, .cjs, or .mjs before rerunning install/build/gates. An upstream repair should centralize entrypoint classification across build.ts, run-gates.ts, run-web-snapshots.ts, and coverage-partitions.ts: wrap JavaScript entrypoints with Node, spawn native .exe directly, and resolve .cmd/.bat without enabling a shell. I wrote up the diagnostic matrix, bounded recovery, unsafe shortcuts, and 12 regression gates here: https://sandbaseai.github.io/deepseek-harness-handbook/windows-standalone-pnpm.html

[leonardocampos19]

Hit this same crash on dsh-v0.1.0-rc.8 — pnpm run build with pnpm 11.7.0 installed as the standalone @pnpm/exe build:

TypeError [ERR_UNKNOWN_FILE_EXTENSION]: Unknown file extension ".exe" for ...\node_modules\@pnpm\exe\pnpm.exe

I patched around it locally in scripts/build.ts's runScript before finding this thread, checking specifically for a .exe npm_execpath and spawning it directly instead of wrapping it with node:

const isNativeExecutable = /\.exe$/i.test(packageManager)
const command = isNativeExecutable ? packageManager : process.execPath
const args = isNativeExecutable ? ['run', script] : [packageManager, 'run', script]

That's the same idea @banatic already laid out above, just narrower — a single-file, .exe-only patch rather than the whitelist-based packageManagerInvocationFor helper proposed here shared across build.ts, run-gates.ts, run-web-snapshots.ts, and coverage-partitions.ts. The whitelist approach (wrap only .js/.cjs/.mjs, spawn everything else directly) is the more correct fix since it also covers other native/script entrypoints, not just .exe. +1 to centralizing it that way rather than patching each call site separately.

[wojiushixiaobai]

Try

corepack enable

[ylwl1997]

Windows + standalone pnpm 时 npm_execpath 脚本全挂，这个坑很隐蔽（Electron/桌面发行版尤其容易踩）。

如果官方短期修不了，文档里写一句「Windows 请用 npm 发行的 pnpm 或把 npm_execpath 指到真实 node」能救一批人。社区插件如果在 postinstall/脚本里依赖这条路径，也会在目录实测里表现为 install-fail——我们遇到会标在插件备注里：https://dshbase.com/plugins/directory/