chore: merge train 260821 — land #2289 (service restart without re-registering)

[lidge-jun]

Summary

Fourth leg of the merge train: lands #2289 — fix(service): restart existing installations without re-registering (Closes #2287) plus a docs-sync hardening commit.

Review chain:

• Adversarial review (inherited model, Euclid) on head 2df92a2: GO-WITH-FIXES (blockers=0), one P2 — the English-source Windows fail-closed caveat paragraph was missing from all 7 translations
• Hardening commit 174f03b: caveat added to ko/ja/fr/ru/tr/zh-cn/zh-tw lifecycle.md per repo docs-sync rule
• Same reviewer re-verdict: PASS
• Review confirmed: bare ocx service idempotency is sound; unknown-state is pre-validated fail-closed with actionable guidance; the Windows: bare ocx service on an already-installed service fails with WINDOWS_SCHTASKS_CREATE_ACCESS_DENIED instead of repairing/restarting #2287 wedge is genuinely closed

Verification

• bun test tests/cli-help.test.ts tests/service.test.ts tests/winsw.test.ts — 174/174 pass (+ cli-help 13/13)
• bun run typecheck / privacy:scan — pass
• Full suite on lidge at train head: 14221 pass / 16 skip / 0 fail across 893 files, exit 0

Checklist

• Local CI green (full suite executed remotely on lidge at exact head)
• Branch includes the latest dev commit (train tracks origin/dev)
• No open Codex/CodeRabbit findings against this head
• Ready for review

Summary by CodeRabbit

• New Features

  • Added ocx service restart as an alias for repair.
  • Running ocx service now installs and starts missing services, or refreshes and restarts existing services without re-registering them.
  • Windows installation now refuses to proceed when service absence cannot be confirmed and recommends checking status.

• Documentation

  • Updated CLI help and lifecycle documentation across supported languages with the new commands and behavior.

• Tests

  • Added coverage for restart aliases, service detection, command planning, and safe handling of unknown installation states.

[github-actions]

✅ Deterministic PR hygiene checks passed.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 2143fa69-6997-45ed-af3d-dc37e61a5f16

📥 Commits

Reviewing files that changed from the base of the PR and between ec3d032 and 5bbca70.

📒 Files selected for processing (17)

• README.md
• devlog/_plan/260821_bug_merge_train/000_triage_matrix.md
• devlog/_plan/260821_bug_merge_train/050_merge_2289.md
• docs-site/src/content/docs/fr/reference/cli/lifecycle.md
• docs-site/src/content/docs/ja/reference/cli/lifecycle.md
• docs-site/src/content/docs/ko/reference/cli/lifecycle.md
• docs-site/src/content/docs/reference/cli/lifecycle.md
• docs-site/src/content/docs/ru/reference/cli/lifecycle.md
• docs-site/src/content/docs/tr/reference/cli/lifecycle.md
• docs-site/src/content/docs/zh-cn/reference/cli/lifecycle.md
• docs-site/src/content/docs/zh-tw/reference/cli/lifecycle.md
• src/cli/registry.ts
• src/service.ts
• structure/04_transports-and-sidecars.md
• tests/cli-help.test.ts
• tests/service.test.ts
• tests/winsw.test.ts

---

📝 Walkthrough

Walkthrough

The service CLI now supports restart as an alias for repair. Bare ocx service probes installation state, installs absent services, and repairs existing services without re-registration. Windows unknown states fail closed. Documentation and tests were updated.

Changes

Service lifecycle command

Layer / File(s)	Summary
Probe and command planning src/service.ts, src/cli/registry.ts	Installation probing now distinguishes installed, absent, and unknown states. Bare commands select install or repair. restart maps to repair. Validation occurs before execution.
Lifecycle behavior validation tests/service.test.ts, tests/winsw.test.ts, tests/cli-help.test.ts	Tests cover command planning, Windows probe results, unknown-state failures, restart parsing, and updated help output.
Lifecycle documentation README.md, docs-site/src/content/docs/..., structure/04-transports-and-sidecars.md	Documentation describes restart, bare-command install-or-repair behavior, and Windows fail-closed probing.
Merge-train records devlog/_plan/260821_bug_merge_train/...	The plan records the implementation scope, review result, validation gates, and train status for the service lifecycle change.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Sequence Diagram(s)

sequenceDiagram
  participant CLI
  participant serviceCommand
  participant planServiceCommand
  participant probeServiceInstallation
  CLI->>serviceCommand: Invoke service command
  serviceCommand->>planServiceCommand: Validate and plan arguments
  planServiceCommand->>probeServiceInstallation: Probe installation state
  probeServiceInstallation-->>planServiceCommand: Return installed, absent, or unknown
  planServiceCommand-->>serviceCommand: Return parsed command or error

Loading

Possibly related PRs

• lidge-jun/opencodex#991: Both changes modify src/service.ts and the service CLI’s repair behavior.

Suggested labels: bug

Suggested reviewers: ingwannu, wibias

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/merge-train-260821

---

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.}