fix(frontend): enforce supported Node runtime

README.md

@@ -80,6 +80,11 @@ Works with 23+ CLI-based coding agents including Claude Code, OpenAI Codex, Curs
 | Git         | Any     | Latest      |
 | pnpm        | Any     | Latest      |
 
+The Electron frontend is currently developed and packaged on Node 20.x. Run
+`nvm use 20 || nvm install 20` before installing `frontend/` dependencies; its
+preinstall check rejects unsupported runtimes before they can leave Electron
+partially installed.
+
 **Optional:**
 
 - `tmux` (Darwin/Linux) - For Unix runtime

frontend/.nvmrc

@@ -0,0 +1 @@
+20

frontend/package.json

@@ -6,13 +6,17 @@
 	"description": "Electron + TypeScript frontend for the agent-orchestrator rewrite",
 	"author": "Agent Orchestrator",
 	"license": "MIT",
+	"engines": {
+		"node": "20.x"
+	},
 	"homepage": "https://github.com/aoagents/agent-orchestrator",
 	"main": ".vite/build/main.js",
 	"repository": {
 		"type": "git",
 		"url": "https://github.com/aoagents/agent-orchestrator"
 	},
 	"scripts": {
+		"preinstall": "node ./scripts/check-node-version.mjs",
 		"build:daemon": "node ./scripts/build-daemon.mjs",
 		"dev": "electron-forge start",
 		"dev:web": "VITE_NO_ELECTRON=1 vite --config vite.renderer.config.ts",

frontend/scripts/check-node-version.mjs

@@ -0,0 +1,22 @@
+const supportedMajor = 20;
+const currentMajor = Number.parseInt(process.versions.node.split(".")[0], 10);
+
+if (currentMajor !== supportedMajor) {
+	console.error(
+		[
+			`Unsupported Node.js runtime: ${process.versions.node}.`,
+			`The Electron frontend is currently supported on Node ${supportedMajor}.x only.`,
+			"",
+			"Why this is enforced:",
+			"- CI and desktop packaging run on Node 20.",
+			"- Newer runtimes can leave node_modules/electron partially installed,",
+			"  causing `npm run dev` to fail with `Electron failed to install correctly`.",
+			"",
+			"Switch to Node 20 and reinstall dependencies:",
+			"  nvm use 20 || nvm install 20",
+			"  rm -rf node_modules",
+			"  npm ci",
+		].join("\n"),
+	);
+	process.exit(1);
+}