fix(frontend): require node 20 for electron dev

README.md

@@ -110,10 +110,18 @@ The desktop supervisor lives under `frontend/` and is started separately:
 
 ```bash
 cd frontend
+nvm use 20 || nvm install 20
 npm install
 npm run dev   # electron-forge start
 ```
 
+The Electron frontend is currently developed and packaged on **Node 20.x**.
+Newer Node 24/26 runtimes currently hit upstream Electron / Electron Forge
+install bugs that can leave `node_modules/electron` half-installed and make
+`npm run dev` fail with `Electron failed to install correctly`. The frontend
+package fails fast on unsupported Node versions so contributors see the fix
+before a partial install corrupts `node_modules`.
+
 Heads-up: `npm run dev` does **not** start the daemon for you. Start it first
 (`ao start`, see above) — the renderer attaches to the running daemon over
 loopback (`127.0.0.1:3001` by default, the `AO_PORT` from the table below).

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,23 @@
+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 Node 24/26 releases currently hit upstream Electron/Forge install bugs",
+			"  that can leave node_modules/electron partially extracted and make",
+			"  `npm run dev` 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);
+}