feat: add vmctl bridge for vmwin

CODEBASE_DOCUMENTATION.md

@@ -99,6 +99,10 @@ server/networkSecurityPolicy.js    - Bind-host/auth safety policy helpers (loopb
 server/processTelemetryBenchmarkService.js - Release benchmark metrics (onboarding/runtime/review), snapshot comparisons, release-note markdown generation
 server/projectTypeService.js       - Project taxonomy loader/validator for category→framework→template metadata (`config/project-types.json`)
 server/portRegistry.js             - Port assignment + live service scanner (`/api/ports/scan`)
+scripts/vm/vmctl.js               - SSH/PowerShell bridge for the `vmwin` Windows VM (status, exec, interactive shell)
+├─ Encoded-command transport: wraps remote PowerShell with `-EncodedCommand` to keep quoting stable across nested shells
+├─ Status probe: returns host/user/PowerShell/tool inventory as JSON or a concise summary
+└─ Environment overrides: `VMCTL_*` env vars tune host alias, timeouts, and remote executable selection
 ├─ Windows scan path: uses hidden `netstat`/`tasklist` probes so packaged Tauri builds do not flash console windows when Ports/Dashboard panels refresh
 └─ UI metadata: labels orchestrator-assigned ports, known dev servers, and custom user labels
 scripts/tauri/prepare-backend-resources.js - Tauri backend packager

package.json

@@ -17,6 +17,10 @@
     "prod": "concurrently \"npm run dev:server\" \"npm run dev:client\"",
     "dev:web": "concurrently \"npm run dev:server\" \"npm run dev:client\"",
     "dev:web:safe": "ORCHESTRATOR_PORT=4001 CLIENT_PORT=4100 npm run dev:web",
+    "vm": "node scripts/vm/vmctl.js",
+    "vm:info": "node scripts/vm/vmctl.js info",
+    "vm:exec": "node scripts/vm/vmctl.js exec",
+    "vm:shell": "node scripts/vm/vmctl.js shell",
     "site:preview": "node scripts/preview-site.js",
     "test": "npm run test:unit && npm run test:e2e",
     "test:unit": "jest",

scripts/README.md

@@ -60,6 +60,18 @@ chmod +x install-startup.sh start-orchestrator.sh
 
 Coming soon. For now, use Login Items in System Preferences.
 
+## Remote Windows VM Control
+
+Use the `vmctl` bridge when you need to talk to the Windows VM through the `vmwin` SSH alias:
+
+```bash
+node scripts/vm/vmctl.js info
+node scripts/vm/vmctl.js exec --command "Write-Output hello"
+node scripts/vm/vmctl.js shell
+```
+
+See [`scripts/vm/README.md`](./vm/README.md) for the full command list and environment overrides.
+
 ## Manual Setup
 
 If the installers don't work for your setup:

scripts/vm/README.md

@@ -0,0 +1,34 @@
+# VM Control
+
+`vmctl` is a small SSH-to-PowerShell bridge for the Windows VM exposed through the `vmwin` SSH alias.
+
+## Commands
+
+```bash
+node scripts/vm/vmctl.js info
+node scripts/vm/vmctl.js exec --command "Write-Output hello"
+node scripts/vm/vmctl.js exec --cwd "C:\Users\administrator" --command "Get-Location"
+node scripts/vm/vmctl.js shell
+```
+
+## What It Does
+
+- Uses SSH as the transport and PowerShell as the remote execution layer
+- Encodes remote commands with `-EncodedCommand` so quoting stays stable across nested shells
+- Adds a status probe that reports the VM host, current user, PowerShell version, working directory, and common tool availability
+- Supports an interactive PowerShell shell for manual work
+
+## Environment Variables
+
+- `VMCTL_HOST`
+- `VMCTL_REMOTE_EXE`
+- `VMCTL_CONNECT_TIMEOUT_MS`
+- `VMCTL_SERVER_ALIVE_INTERVAL`
+- `VMCTL_SERVER_ALIVE_COUNT_MAX`
+- `VMCTL_TIMEOUT_MS`
+
+## Notes
+
+- The default SSH alias is `vmwin`
+- `exec` is safe for multi-line PowerShell because the command body is encoded before transmission
+- `info --json` is convenient when another tool needs to parse the VM status