fix(startup): avoid permission-sensitive service re-registration

[stephen-drew]

Summary

• Refresh an existing background manager through ocx service repair during self-update instead of re-registering it.
• Make Startup recovery, status, doctor and service diagnostics choose Start for a clean stopped service and Repair for an installed unhealthy service.
• Add ocx repair as a documented alias of ocx service repair; reserve Install for a missing, disabled or conflicting registration and explain the Windows administrator requirement.
• Keep the last known-good Startup health through routine cache revalidation and one transient probe failure.
• Document the lifecycle and update behaviour in the canonical guide and maintained translations.

Root cause

On Windows, an existing Task Scheduler registration can be owned by Administrators while the signed-in user is still allowed to run and stop it. Recovery paths that unconditionally suggested ocx service install invoked schtasks /create /f, so a repairable service failed with Access denied even though schtasks /run and /end were permitted.

User impact

Updates and ordinary recovery no longer overwrite an existing registration. A stopped service can be started, stale generated assets can be repaired without elevation, and a genuine re-registration still follows the explicit administrator-approved install path.

Verification

• Root suite: 7,949 passed and 6 skipped; the sole default-timeout failure was an unchanged native-model management test on this loaded Windows host. Its isolated rerun with a 15-second ceiling passed 8/8 in 2.74 seconds.
• The eight earlier environment/stale-assertion failures reran 116/116 after adding the bundled Bun directory to child-process PATH and updating the obsolete repair assertion.
• Dashboard package: 587 tests passed; lint, TypeScript and the production build passed.
• Privacy scan passed; changed-surface React Doctor scan found no issues.
• cd docs-site && bun install --frozen-lockfile && bun run build
• Windows live canary: ocx stop, then ocx repair; replacement PID served on 127.0.0.1:10100 and Startup read back protected, protection=service, diagnosticStale=false.

Source commits before the current dev rebase: 52ef5469 and 70d2066d.

Checklist

• Scope stays focused and avoids unrelated cleanup.
• Documentation was updated.
• No credential, authentication, global configuration or task-ACL boundary was widened.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: e253a3db-2122-4371-aee4-ea07fe07b614

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

_{Comment @coderabbitai help to get the list of available commands.}

[lidge-jun]

Confirmed as real and left open — not folded into the current review stack (#951–#973).

Two reasons. It touches a permission-sensitive path (service registration during self-update) across 30 files spanning CLI, GUI, and five docs locales, which is its own review with its own risk profile. And per AGENTS.md, install/service-lifecycle changes want deliberate maintainer attention rather than a ride on a bug stack.

The direction reads right to me — service repair for an installed-but-unhealthy registration, Install reserved for missing/disabled/conflicting — since re-registering to fix a health problem is what makes the permission prompt fire. Thanks for the writeup; the state table in the description is the part that makes it reviewable.

[lidge-jun]

Superseded by #980 (stack 7/7), commit e9c0bb3d1. Closing this one — reopening is one click.

Your diagnosis is correct and it is now fixed. ocx update stopped the proxy and then brought the service back with ocx service install, whose Windows scheduler path always reaches schtasks /create — elevation a normal updater does not have. Switching the post-update refresh to repair is the right fix and it shipped.

The safety question your PR did not answer, now verified. repairService() throws when the service is not installed, and the update path runs after ocx stop. If stopping deregistered anything, the substitution would throw exactly where install used to succeed. It does not, on any platform: macOS unloads the plist, Windows calls schtasks /end, Linux calls systemctl stop, and deletion lives only in the uninstall paths (src/service.ts:2204-2225).

Two things the reconstruction adds.

The Windows GUI worker never reached the command at all. src/update/job.ts:775 sets skipServiceInstall = true unconditionally when OCX_SERVICE=1 on Windows, and its own comment gives the reason: schtasks /create will UAC-fail. Repair never calls /create, so that justification does not survive the change — the skip is now narrowed to callers still passing install argv. Without this, the dashboard-triggered update (the most common Windows path, and the one closest to your report) keeps the bug while the CLI gets fixed. A pure argv swap would have missed it.

The stale-marker hole. bin/ocx.mjs infers "a service manages this proxy" from service-state.json merely existing, which can be stale — present while the registration is gone. Today install recreates the service from that marker; a blind repair substitution throws and the user silently loses their managed service. The fix could not be "catch the not-installed error", because repairService() throws plain Error for every failure mode and the launcher sees only an exit status. It now reads startup.serviceInstalled from the status --json subprocess it already spawns, and installs only when the service is genuinely absent. Installing after any repair failure would have resurrected the elevation prompt this change exists to remove.

Also carried: the advice strings that fire only for an already-installed service now say ocx service repair (cli/status, stale baked paths, stale scheduler assets, the WinSW missing-binary hint, and the launchd older-plist and not-loaded hints). First-install and missing-unit guidance stays install, since repair would be wrong advice there.

Six existing tests pinned the old install argv and were updated with reasons; a new guard proves the non-elevated Windows worker now receives service repair, and restoring the unconditional skip turns it red.

Thank you — the elevation analysis was the hard part and you got it right.