## Problem
A process keeps the numeric ID of a parent that exited, and Windows
reuses that ID (Raymond Chen, [*Why is CreateToolhelp32Snapshot
returning incorrect parent process
IDs*](https://devblogs.microsoft.com/oldnewthing/20150403-00/?p=44313)).
A tree walk over parent IDs alone adopts unrelated processes. An
application an agent launched through a launcher that exited names the
launcher's PID; once a process being stopped receives that PID, the
application and its children are terminated with it. Observed: a Houdini
session died with exit code 1 (`TerminateProcess(…, 1)`), its `cmd`
parent 0.2 s earlier, two seconds after two `powershell.exe` started.
- `processTreeFromRows` (`electron/main/process-stop.ts`) walked parent
IDs only. The native and CIM Windows captures already filter children
older than their parent, but the shared walk relied on that, and the
Linux `/proc` scan and macOS `ps` listing are not atomic.
- `taskkill /T` walks recorded parent IDs the same way (see e.g.
openai/codex#36258, #58999). It was used by the server's foreign
OpenCode `--version` probe on timeout, by
`ui/src/lib/server-events-lifecycle.test.ts` and by two Windows desktop
fixtures.
## Change
- `packages/server/src/process-tree.ts` (Node built-ins only, shared by
Electron main, the server, tests and tsx-loaded scripts):
- `processTreeRows(rootPid, rows)`: a row is a child only when it
started **no earlier** than the process holding its parent ID; unknown
start times are left out; the first row of a PID wins.
- `stopWindowsProcessTree(rootPid, spawnedBy)`: one CIM listing, the
same walk, refusal when the root ID was reused after the spawn, then
`Stop-Process` through `Process` objects whose creation time is checked
after their handle is bound.
- Electron's `processTreeFromRows` uses `processTreeRows` with Windows
creation ticks, Linux boot clock ticks and macOS `lstart` seconds
(same-second children are kept).
- The foreign probe, the UI test and both desktop fixtures use
`stopWindowsProcessTree` instead of `taskkill /T`.
Checked and unchanged: Tauri (Windows Job Object with kill-on-close,
POSIX process groups: membership inherited at creation, no walk),
Electron POSIX `kill(-pid)` in `shell-environment.ts` (process group),
Electron force termination (already checks each member's creation
identity before `TerminateProcess`).
## Tests
- `process-stop.test.ts`: a recycled-parent table on Windows, Linux and
macOS leaves the orphan and its child out of the capture. **Fails on
`dev`** (`[100, 300, 301, 200, 201]` instead of `[100, 200, 201]`),
passes here; the 34 other tests pass.
- `server/src/process-tree.test.ts`: recycled parent, a cycle through a
recycled ID, unknown start times, duplicate rows, a missing root, reused
root ID refusal, CIM row parsing, a real Windows wrapper and its
descendant stopped.
- `legacy-installation.test.ts` (foreign probe kills the wrapper's
descendant on timeout) and `server-events-lifecycle.test.ts` pass;
server, Electron and UI `tsc` pass.
## Docs
`AGENTS.md` (never `taskkill /T` or a parent-ID-only walk), the desktop
conventions reference and `OPENCODE_RUNTIME_SETUP.md`. No user-visible
behaviour, so no help change.
## 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).
## 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.
Replace the arbitrary 2.0.11 floor with the 2.0.7 native step-timestamp boundary, keeping 2.0.11 as the separately recommended qualification target. Unlisted, prerelease and custom runtimes negotiate authenticated API requirements; preserve complete CLI labels so unknown builds neither fail solely by name nor enable unintended automatic upgrades.
Finish retiring pre-2.0.4 location/worktree/credential/Form serialization and obsolete catalog events while preserving internal identity, import/cursor authorization, pruning claims and connection fences. Remove the unused global package-manager installer and clean generated server output before packaging so deleted modules cannot survive incremental builds.
Distinguish missing setup, technical incompatibility and optional updates in the shared UI, including minimum rationale and optional restart wording. Retain a usable daemon through older discovery CLIs, check reload capability independently, and suppress installation when bundled npm is unavailable.
Validated 622 server tests, 7 browser scenarios, real reducers and fixture guards, production native suites on 2.0.7 and 2.0.10, and synthetic 2.0.3-to-2.0.7 history migration. Independent gatekeeper re-review closed the production version-parser finding. CI now qualifies the source-defined minimum and latest; rebuilt desktop acceptance is recorded separately.
Do not treat a newer CLI's stopped status as proof that its older shared daemon is absent. Resolve native service metadata read-only through the selected execution host, match the channel's credential/configuration unambiguously, and authenticate historical metadata routes before admitting the registered endpoint. Repeat discovery inside ensure before starting.
Fail closed for malformed or oversized records, ambiguous identity, authentication failures, timeouts and existing WSL registrations with forwarding errors. Distinguish fresh configuration with no native registration, preserve the shared loopback policy including 127.0.0.2, and translate mounted/aliased WSL metadata through the selected distro.
Add lifecycle regressions and bounded, isolated packaged desktop acceptance. Both rebuilt Electron and Tauri retain an actual 2.0.3 daemon through installation until explicit restart, then activate 2.0.11 and resume the pending folder. Normal installation/reload and all three WSL modes pass. Final gatekeeper review reports no actionable findings; full server suite passes 621 tests with two skips.