## Summary
Electron already ships the Node runtime the backend needs. The Electron
package now launches the CodeNomad server through `process.execPath`
with `ELECTRON_RUN_AS_NODE=1` and keeps only npm (from the pinned
`.node-version` archive), dropping the redundant standalone `node.exe`
(~89 MiB on Windows). Tauri keeps its full bundled runtime unchanged.
## Changes
- **Launch**: `process-manager.ts` runs the backend with Electron's own
executable in run-as-Node mode; `managed-node.ts` is removed.
- **Resources**: `prepare-node-runtime.cjs` gains an npm-only layout
requested by `electron-app/scripts/prepare-resources.js`; Tauri keeps
the full Node + npm layout.
- **npm discovery**: `bundledNpm()` (`npm-runtime.ts`) finds npm in
Electron resources (Windows, Linux, macOS `.app/Contents/Resources`)
while preserving Node/Tauri layouts.
- **npm lifecycle scripts**: `@opencode/cli` runs `node
./postinstall.mjs`; installation (`shared-installation.ts`) and native
upgrades (`native-upgrade.ts`) get a private, scoped `node` command
pointing at the Electron executable, removed afterwards. The shared
OpenCode daemon never inherits `ELECTRON_RUN_AS_NODE`.
- **Checks/CI**: packaged-resource smoke, `verify-bundled-node`,
`build.js` and `build-and-upload.yml` separate the Electron (npm-only)
and Tauri contracts; `test-opencode-*-native.mjs` and the desktop setup
qualification can target the packaged Electron runtime without a system
Node on PATH.
- **Docs**: `dev-docs/RUNTIME_MAINTENANCE.md` (the Electron package
follows Electron's Node version), `dev-docs/OPENCODE_RUNTIME_SETUP.md`,
and `server.md` / `updates.md` help pages in all ten locales.
## Validation
- Electron 39.0.0 → Node 22.20.0; npm 11.19.0 (engines `^20.17.0 ||
>=22.9.0`).
- Packaged Windows ZIP and Linux (`linux-unpacked` + extracted DEB,
Ubuntu 24.04 VM): backend reaches ready, API answers 200, both backend
processes run as the app executable with `ELECTRON_RUN_AS_NODE=1`, no
Node in resources or on PATH, clean exit with no orphan and the
executable released.
- `test-opencode-install-native` (2.2.3), `test-opencode-upgrade-native`
(→ 2.2.5, isolated service PID kept) and
`test-opencode-legacy-replacement-native` (1.18.10 → 2.2.5) pass on
Windows and Linux with the packaged Electron runtime.
- Typechecks (server, Electron), resource tests 11/11, `opencode-update`
tests (Windows 66 pass / 1 POSIX skip; Linux 62 pass / 5 Windows skips),
help validation.
- The full Electron suite on Windows shows intermittent failures in
`process-stop.test.ts` and `native-service-start.test.ts` (PowerShell
capture timeout of 1.5 s); they reproduce identically on `dev`
(30527e58d) and the files are unchanged here.
## Size (same machine and options)
| | Before | After | Delta |
|---|---:|---:|---:|
| Windows `resources` | 344 274 218 B | 250 740 778 B | −89.20 MiB |
| Windows ZIP | 221 737 165 B | 188 286 779 B | −31.90 MiB |
| Linux `resources` | 377 016 175 B | 250 408 680 B | −120.74 MiB |
| Linux DEB | 138 393 810 B | 107 123 634 B | −29.82 MiB |
macOS was not exercised at runtime (path handling is covered by unit
tests; arm64/x64 builds run in CI).
## Résultat
Corrige le chargement des plugins CodeNomad avec OpenCode 2.0.27 et
établit cette version comme minimum pour les prochaines releases et les
prereleases dev. Aucun déploiement de l’application active ni
redémarrage du daemon partagé.
## Cause démontrée
- Le runtime natif passe d’Effect 4.0.0-rc.112 à 4.0.1. Le bundle
précédent reproduit `cache.stackFrame` sur une CLI 2.0.27 isolée.
- Embarquer Effect 4.0.1 ne préserve pas la 2.0.26 : échec inverse
`cache.scheduler`.
- Les schémas 2.0.27 consomment `Schema.isStartingWith`, absent du
moteur 2.0.26. Le plancher est fondé sur cette rupture mesurée, pas sur
une liste de versions testées.
## Implémentation
- Pins client/plugin synchronisés à 2.0.27 ; Effect et le SDK public des
plugins sont fournis par OpenCode, hors bundles natifs
pruning/Missions/automation.
- Réglages de build partagés et régression qui interdit une seconde
copie du runtime ; smoke natif ajouté à la matrice minimum/latest.
- Diagnostic `plugin_runtime` traduit dans les dix locales ; versions
futures et personnalisées conservent la reconnaissance authentifiée du
contrat.
- Adaptations du SDK : annulation des lectures projet, références de
credentials externes et connexion fournisseur externe avec formulaire
natif, sans fallback OAuth/API key ni rejeu.
- Le runtime OpenTunnel du backend reste isolé et inchangé. Aucun
tunnel, route ou identité distant n’est modifié.
## Validation locale
- Échec reproduit sur 2.0.26 et réussite sur 2.0.27 pour les variantes
de bundle comparées.
- Suites natives isolées automation,
pruning/historique/proxy/concurrence/redémarrage et Missions réussies
sur 2.0.27.
- Régressions ciblées de build, store/serveur et navigateur (diagnostic
du minimum, connexion externe et brouillon conservé) réussies ;
typechecks UI/serveur/Electron/OpenTunnel réussis.
- Suite serveur complète et CI multiplateforme encore en validation à
l’ouverture ; aucun résultat entièrement vert anticipé.
La revue gatekeeper indépendante sera publiée ici avant fusion. Les
anciennes preuves de qualification restent historiques, pas une promesse
de support des moteurs antérieurs au nouveau plancher.
## Summary
Retire the prerelease private OpenCode installation completely as an
executable source. Automatic selection now uses PATH and the
conventional shared user npm installation. Existing private files are
neither migrated nor deleted.
- Remove the private installer, receipt reader and fallback
introduced/retained by #756.
- Ignore saved private selections and reject validation/launch from
`~/.local/share/codenomad/opencode`, including private PATH entries.
Prevent installation into that retired prefix.
- Remove private-copy descriptions from all ten locales and update the
runtime policy documentation.
- Keep supported custom installations, native shared-service
ownership/authentication and explicit restart behavior.
## Reproduction and scope
The initial genuinely empty-profile test passed, but it did not match
the affected machine: that machine had no Git and retained a private
prerelease OpenCode copy.
On the exact installed `v0.20.0-dev-20260923-baf674fc` Tauri artifact,
seeding a valid private copy plus its `selected` receipt and `current`
marker makes setup report `state: ready`, `installationSource: legacy`,
and suppresses the missing-installation screen. The new desktop
regression fails against that release with `ready !== missing`.
With rebuilt server/UI resources in an isolated copy of the same Tauri
host, the identical private-copy scenario reports missing, offers
installation, installs the shared npm package, authenticates OpenCode
2.0.15 and resumes the requested folder without Git. This demonstrates
the missing-setup cause; it does not claim to explain every initially
reported startup slowdown.
## Validation
- 59 targeted server tests passed: discovery/install/update, retired
paths, binary selection, Windows/WSL spawn and binary validation routes.
- 13 real-component setup browser tests passed.
- 23 focused retirement/launch tests passed after the final network-path
preflight adjustment.
- UI TypeScript check passed; production server/UI/automation/pruning
build passed.
- Installed-release private-copy reproduction failed as expected;
corrected isolated Tauri acceptance passed.
- `git diff --check` passed.
Desktop qualification uses isolated profiles, services and databases.
The sole simulated installation side effect is HKCU PATH registration,
captured by a fixture preload; bundled npm installation, package
verification, native-parent service start and authenticated API checks
are real. The shared user daemon and installed application were not
replaced by the fix. Remote CI is pending.
## Maintenance notes
Existing oversized files touched: `packages/server/src/api-types.ts`
(~583 lines) and `packages/ui/src/lib/i18n/messages/*/settings.ts`
(~625–639 lines). No size-only refactor is included.
Prefer terminal PATH and a common user npm installation, migrate historical private and official npm copies, and retain explicit authority for custom and WSL executables. Preserve running daemon ownership and defer locked Windows updates. Align recovery and settings presentation across locales.\n\nReviewed through an independent gatekeeper loop (final zero-finding review on e33a6a16). Validated 34 targeted server tests, 13 browser scenarios, typechecks, isolated Windows npm installation and real historical migrations. Full CI browser job has unrelated existing system-message search failures reproduced locally; merge requested with administrator authority without waiting for CI.
Keep activation explicit after optional upgrades while reconnecting backend authority to the newly selected executable. Supported running daemons remain usable and new workspaces can open when restart is deferred. Recheck executable selection and execution-host eligibility before mutating the shared service.
Publish verified installations with immutable, exclusive version receipts. Concurrent older installs cannot downgrade a newer selection, and same-version Windows publishers no longer replace an open receipt. Continue reading previous current markers.
Cover the gatekeeper findings with real manager/shared-service ownership regressions, browser recovery tests, and concurrent installer tests. Extend native migration to beta and stable seeds, same-version Forms durability controls and historical provider connections. Provide the POSIX shell explicitly in the no-system-Node fixture, fixing Linux/macOS installation CI isolation.
Require stable OpenCode >=2.0.11 <3.0.0 from authenticated daemon metadata before functional clients and plugin provisioning. Keep bounded contract recognition, connection-generation fencing and native ownership checks while retiring old request, response and event conversions.
Unify missing and outdated runtime recovery with Preferences. Install exact stable releases through bundled Node/npm into a verified versioned user prefix, preserve custom and WSL selections, and separate installation from explicit shared-service restart through the native-parent starter. Fence stale setup responses, retain pending folder opening and never replay prompts.
Certify isolated 2.0.3-to-2.0.11 history migration with executable hashes, untouched seed storage, paginated messages, forks, compaction checkpoints, location moves and pending inbox data. Add minimum/latest cross-platform migration and installation gates, packaged npm closure checks, real Solid recovery regressions and supported-contract authority tests.
Validated server/UI types, focused unit and reducer suites, browser captures, actual packaging-prepared Node 24.20.0 installation without system Node, and native location, automation and pruning fixtures. Document packaged-desktop, WSL, broader historical-state and remote-CI evidence as remaining release gates.