fix(windows): stop service loop on missing install

[Ingwannu]

Summary

• verify the Task Scheduler wrapper's baked Bun runtime and CLI entry before every child start;
• log one actionable incomplete-install message and exit when either path is absent;
• preserve the existing five-second restart behavior for a proxy child that actually launched and then failed;
• document the recovery command and the reason this slice does not attempt an unsafe npm directory copy-back.

Partial fix for #1849: this closes the unbounded missing-file restart loop. Transactional npm package-and-shim rollback remains separate follow-up work.

Why this scope

A missing executable cannot become healthy inside the same wrapper process, so retrying it 1,009 times adds log churn without recovery. A generic crash ceiling would also stop legitimate recovery after unrelated intermittent runtime failures. The wrapper therefore treats only proven missing baked paths as terminal.

The current dev updater already has stop-first and registry-integrity preflight that were not present in the reported 2.13.0 build. It still does not have a verified transactional restore of both the npm package tree and global launchers. Copying a package directory alone would not safely restore shims, ownership, and lock state, so that broader design is intentionally not guessed in this PR.

Verification

• bun test tests/service.test.ts — 124 pass, 0 fail.
• bun run typecheck — passed.
• bun run privacy:scan — passed.
• cd docs-site && bun install --frozen-lockfile && bun run build — 385 pages built successfully.
• git diff --check — passed.

dev2-go

No separate Go-native counterpart exists for this behavior; the Windows service asset generator remains in the TypeScript lifecycle control plane.

Review notes

This is self-authored maintainer work, so I will not approve or merge it myself. Exact-head CI, the service-lifecycle workflow, and another maintainer review are required.

Summary by CodeRabbit

• Bug Fixes

  • Improved Windows service startup validation by detecting incomplete installations before launch.
  • Services now stop cleanly with an actionable message instead of repeatedly retrying when required files are missing.
  • Existing restart behavior remains available when a service starts successfully but later crashes.

• Documentation

  • Added guidance explaining how incomplete Windows service installations are handled and repaired.

[github-actions]

✅ Deterministic PR hygiene checks passed.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 89864c7d-aaf6-4c72-9461-d01385689b6c

📥 Commits

Reviewing files that changed from the base of the PR and between 9830ab1 and 1b9ba76.

📒 Files selected for processing (4)

• docs-site/src/content/docs/reference/cli/lifecycle.md
• src/service.ts
• structure/06_docs-and-release.md
• tests/service.test.ts

Included review availability: Your plan includes up to 10 reviews per rolling hour; 8 remain after this review.

---

📝 Walkthrough

Walkthrough

The Windows service wrapper now checks its bundled Bun executable and CLI entry before each launch. Missing files produce one repair message and exit code 3 without retrying. Tests cover both missing-file cases and retained retries after successful launches and crashes.

Changes

Windows service startup validation

Layer / File(s)	Summary
Startup preflight and regression coverage src/service.ts, tests/service.test.ts	The wrapper checks the bundled Bun runtime and CLI entry before spawning. It exits with code 3 when either file is missing. Tests verify both failure cases and retry-loop ordering.
Recovery behavior documentation docs-site/src/content/docs/reference/cli/lifecycle.md, structure/06_docs-and-release.md	Documentation describes the incomplete-installation message, exit behavior, preserved crash retries, and reinstall-and-repair procedure.

Estimated code review effort: 2 (Simple) | ~10 minutes

Merge Risk: ⚪ Minimal · up to 1b9ba

The change is merge-ready after normal checks and review; no actionable merge-blocking risk remains.

Possibly related issues

• [Bug][Windows] Failed ocx update leaves a file-less package skeleton; service wrapper restart-loops 1,009 times with no integrity check or backoff #1849 — The PR implements the issue’s proposed preflight checks for missing Bun and CLI files and prevents retrying an incomplete installation.

Possibly related PRs

• lidge-jun/opencodex#306 — Directly related Windows service-wrapper logic and regression tests in src/service.ts and tests/service.test.ts.
• lidge-jun/opencodex#980 — Related Windows service repair and startup behavior in the same implementation and test files.
• lidge-jun/opencodex#838 — Related handling of Windows service viability and missing on-disk service assets.

Suggested reviewers: lidge-jun

Sequence Diagram(s)

sequenceDiagram
  participant WindowsServiceWrapper
  participant BundledFiles
  participant ServiceProcess
  WindowsServiceWrapper->>BundledFiles: Check Bun executable and CLI entry
  BundledFiles-->>WindowsServiceWrapper: Return file availability
  alt Both files exist
    WindowsServiceWrapper->>ServiceProcess: Spawn service
  else A file is missing
    WindowsServiceWrapper-->>WindowsServiceWrapper: Log incomplete installation
    WindowsServiceWrapper-->>WindowsServiceWrapper: Exit with code 3
  end

Loading

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: stopping the Windows service loop when required installation files are missing.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch ingw/fix-windows-service-missing-install-1849

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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