Skip to content

[WRONG BRANCH] docs(cli): clarify platform-specific service repair behavior #490

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
luvs01 wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

[WRONG BRANCH] docs(cli): clarify platform-specific service repair behavior #490

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions docs-site/src/content/docs/ko/reference/cli/lifecycle.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -250,8 +250,8 @@ Windows 작업 스케줄러로 설치하는 서비스는 보통 프로세스 우
| --- | --- |
| 없음 | 서비스가 없으면 설치하고 시작하며, 이미 있으면 `repair`를 수행합니다. 정상인 Windows 작업 스케줄러 정의는 재사용하지만, 오래된 정의는 다시 등록되어 관리자 권한 승인이 필요할 수 있습니다. |
| `install` | 서비스를 생성하고 시작합니다. |
| `repair` | 설치된 서비스를 제자리에서 새로 고치고, 바뀐 것이 있을 때만 관리자를 reload합니다. macOS에서 정상이고 변경이 없는 작업은 그대로 실행된 채 남으므로 repair가 장애가 되지 않습니다. 정상인 Windows 작업 스케줄러 정의는 재사용하지만, 오래된 정의는 다시 등록되어 관리자 권한 승인이 필요할 수 있습니다. |
| `restart` | 같은 갱신이지만 항상 재시작합니다. macOS에서 변경이 없고 이미 로드된 작업은 제자리에서 kickstart됩니다. `repair`의 별칭이 아닙니다. |
| `repair` | 설치된 서비스를 제자리에서 새로 고칩니다. macOS에서는 바뀐 것이 있을 때만 관리자를 reload하므로, 정상이고 변경이 없는 작업은 그대로 실행된 채 남아 repair가 장애가 되지 않습니다. Linux와 Windows에서는 서비스를 재시작합니다. 정상인 Windows 작업 스케줄러 정의는 재사용하지만, 오래된 정의는 다시 등록되어 관리자 권한 승인이 필요할 수 있습니다. |
| `restart` | 같은 갱신을 수행하며 모든 플랫폼에서 반드시 재시작합니다. macOS에서 변경이 없고 이미 로드된 작업은 제자리에서 kickstart됩니다. `repair`의 별칭이 아닙니다. |
| `start` | 설치된 서비스를 시작합니다. |
| `stop` | 서비스를 중지하고 기본 Codex를 복원합니다. |
| `status` | 서비스와 프록시 진단, 로그 경로를 보고합니다. |
Expand Down
10 changes: 5 additions & 5 deletions docs-site/src/content/docs/reference/cli/lifecycle.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -121,7 +121,7 @@ are left in place.

Status and `ocx doctor` compare this CLI's version with the running proxy. If the CLI is newer,
restart the proxy using the intended current installation; for a background service, run
`ocx service restart` — a version skew leaves the service definition byte-identical, so
`ocx service restart`. On macOS, a version skew leaves the service definition byte-identical, so
`ocx service repair` would reload nothing and keep the old process serving. If the proxy is newer, upgrade the CLI
or resolve `PATH` to the intended installation. These diagnostics do not repair the service or
change whether requests are allowed.
Expand Down Expand Up @@ -311,17 +311,17 @@ Definitions installed before this change still carry the old versioned paths and
themselves — once the old executable is deleted, no opencodex code runs to fix it. Run
`ocx service repair` once after upgrading; after that, each service start follows the launcher.
An already-running proxy is not replaced by an external upgrade: when the installed CLI is newer
than the running proxy, run `ocx service restart` so the new build serves. `repair` is not enough
there: the definition did not change, and a repair that changes nothing reloads nothing.
than the running proxy, run `ocx service restart` so the new build serves. On macOS, `repair` is not
enough there: the definition did not change, and a repair that changes nothing reloads nothing.
If the proxy is newer instead, check the CLI installation and `PATH` as described under
[`ocx status`](#ocx-status---json).

| Subcommand | Action |
| --- | --- |
| none | Install and start when absent; otherwise `repair` the existing service. A healthy Windows scheduler definition is reused; a stale definition may be re-registered and require elevation. |
| `install` | Create and start the service. Registers it, which on Windows needs elevation. |
| `repair` | Refresh an installed service in place, reloading the manager only when something changed — so on macOS a healthy, unchanged job keeps running and the repair is not an outage. A healthy Windows scheduler definition is reused; a stale definition may be re-registered and require elevation. |
| `restart` | The same refresh, but it always restarts. On macOS an unchanged, already-loaded job is kickstarted in place. Not an alias of `repair`. |
| `repair` | Refresh an installed service in place. On macOS, the manager is reloaded only when something changed, so a healthy, unchanged job keeps running and the repair is not an outage. On Linux and Windows, the service is restarted; a healthy Windows scheduler definition is reused, while a stale definition may be re-registered and require elevation. |
| `restart` | The same refresh and a guaranteed restart on every platform. On macOS an unchanged, already-loaded job is kickstarted in place. Not an alias of `repair`. |
Comment on lines +323 to +324

@chatgpt-codex-connector chatgpt-codex-connector Bot Sep 12, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Update every translated lifecycle table

This platform-specific correction was applied only to English and Korean, while the French, Japanese, Russian, Turkish, Simplified Chinese, and Traditional Chinese lifecycle tables still state that repair always restarts the service and that restart is its alias. On macOS, readers of those pages can therefore run repair after an upgrade expecting a restart and leave the old process serving; update the corresponding translated tables and version-skew guidance to match the new canonical behavior.

AGENTS.md reference: docs-site/AGENTS.md:L7-L10

Useful? React with 👍 / 👎.

| `start` | Start an installed service. |
| `stop` | Stop the service and restore native Codex. |
| `status` | Report service and proxy diagnostics plus log paths. |
Expand Down
Loading