[diegosouzapw]

Summary

Fixes three defects in the same known bug class that together produce the reported symptom (a dashboard stuck reporting an old version while omniroute update claims "already up to date"): the update mechanism, not the reporter's specific environment, is what this PR proves and fixes — their exact install method / process manager was never confirmed (see "Pending live validation" below).

• bin/cli/commands/update.mjs — omniroute update --apply installs the new files (npm install -g) and re-reads package.json from disk to verify, but never restarted anything, and its old success message ("Run omniroute --version to verify.") implied the running process was already current. A later omniroute update then correctly says "already up to date" (the files are current) while the long-lived server process — which cached its require()d package.json at startup — keeps serving the old build. This is exactly the reported symptom pair.

  • Fix: detect whether a CLI-managed server is currently running (the same PID file stop.mjs/restart.mjs already trust) and print an explicit, prominent instruction — omniroute restart if one is running, omniroute serve otherwise — instead of implying the update is live. Deliberately does not auto-invoke restart.mjs's runRestartCommand(): it stops then re-spawns the server in the foreground, which can block the calling terminal — a materially bigger, riskier behavior change than warranted for an unattended --apply flow.

• src/app/api/system/version/route.ts (dashboard's own Update button, npm mode) — hardcoded pm2 restart omniroute at two near-identical branches (~264, ~347 pre-fix). When pm2 isn't the process manager it silently degraded to status: "skipped" while the install step still said "done" — reading like a completed live update. OmniRoute ships its own supervisor (omniroute serve/--daemon, PID-file managed) and plain npm run start as pm2 alternatives, so this was the common case, not the edge case.

  • Fix: new src/lib/system/processManagerRestart.ts::restartRunningServer() tries OmniRoute's own PID-file-managed supervisor first (SIGTERM only the supervised server child, never the supervisor — killing the supervisor sets its isShuttingDown flag and intentionally skips the respawn, per stop.mjs; killing the child lets the supervisor's own crash-recovery respawn it, which is the restart we want), then falls back to pm2, and returns an honest restart-required outcome instead of a silent skipped when neither applies. Both route.ts call sites now share one sendRestartStep() helper instead of duplicating the pm2-only logic a third time.

• src/lib/system/versionCheck.ts::getLatestVersionFromNpmCli() (backs the dashboard's "Update Available" banner) — ran npm info omniroute version --json without --prefer-online, the identical stale-npm-cache bug already fixed in the CLI's own getLatestVersion() for [BUG] Failed Update From Command omniroute update #4376, never mirrored here. Added --prefer-online plus an injectable execFn (matching the CLI's fix pattern) for testability.

Test plan (TDD — failing test written first for each defect, then the fix)

• tests/unit/system-version-check-prefer-online-11885.test.ts — proves getLatestVersionFromNpmCli passes --prefer-online and is exec-injectable.
• tests/unit/cli-update-restart-guidance-11885.test.ts — proves isServerProcessRunning/printPostApplyGuidance detect a live server via PID file and print omniroute restart guidance instead of implying the update is live.
• tests/unit/system-process-manager-restart-11885.test.ts — proves restartRunningServer() prefers the own-supervisor path (killing only the server pid, never pm2), falls back to pm2 when no supervisor is detected/stale, and returns an honest restart-required outcome when neither applies.
• Full targeted regression sweep (63 tests, 0 failures) across the touched files plus every existing neighbor test (cli-update-*, system-version-check-4100, system-version-cache-8278, auto-update*, home-update-error-render-5991).
• Node native mocks the process/exec boundary throughout — no real npm install, pm2, or process kill is ever executed by a test.

Pending live validation

Could not verify locally / no VPS access in this session:

• The reporter's own install method and process manager were never confirmed (npm global? Docker? source checkout? systemd/pm2/omniroute serve/plain terminal?) — this PR fixes the mechanism that produces the reported symptom class, not a confirmed root cause for that specific user's box.
• End-to-end live validation of restartRunningServer()'s own-supervisor path (SIGTERM to the server pid actually being respawned by a live ServerSupervisor) — unit-tested with injected killProcess/readPidFile/isPidRunning, never exercised against a real spawned supervisor process.
• End-to-end live validation of the dashboard's Update button end-to-end against a real pm2-managed install and a real omniroute serve --daemon install.
• omniroute update --apply against a real global npm install (only the pre-existing #9475 shadow-install test exercises the surrounding flow via a faked npm binary on PATH).

Both of the above need root@192.168.0.15 or an equivalent real install to run omniroute serve/omniroute serve --daemon/pm2 and observe an actual restart — not available in this session.

⚠️ base-red inherited: #11874 — Docs sync + fabricated-docs (strict)

Closes #11885