fix(cli): stop a sibling start from persisting its port into config.port

[lidge-jun]

Summary

• fix(cli): let an explicit different --port start a sibling (rebase of #3144) #3188 opened the sibling path: ocx start --port X beside a live proxy on the configured port starts a second instance instead of refusing. That instance goes through chooseListenPort with X as its hard-pinned preference, so shouldPersistSelectedPort(config.port, X, X) is true and config.port is rewritten to X under the still-running configured-port proxy.
• Observed on the maintainer dogfooding host: a probe session ran start --port 10198 a few times against the real home, exited, and left config.port=10198 behind. The next ocx stop + ocx service read config.port, baked --port 10198 into the launchd plist, and re-pointed Codex openai_base_url at 10198 — the service silently moved off 10100 with no start on 10198 in sight.
• A sibling is a second instance, not a new home for this config, so it must never persist its port. handleStart now records the sibling decision and passes { sibling: true } into both chooseListenPort call sites (initial pick and the EADDRINUSE re-pick); shouldPersistSelectedPort returns false for it. The ordinary first-start persist and the fallback-port non-persist are unchanged.

Verification

• bun run typecheck
• bun test tests/ports.test.ts tests/cli-dispatch.test.ts tests/update-notify.test.ts — 66 pass / 0 fail
  • new: shouldPersistSelectedPort sibling case ((10100, 10198, 10198, { sibling: true }) → false; same args without the flag → true)
  • new: source pin that both chooseListenPort call sites in handleStart carry sibling: siblingStart, so the re-pick path cannot silently regain the old behavior
• Live recovery on the affected host: ocx config set port 10100 + ocx service → plist --port 10100, /healthz on 10100, openai_base_url back on 10100.

Checklist

• Scope stays focused and avoids unrelated cleanup.
• Docs or release notes were updated when needed. (No user-facing doc describes the sibling persist; the warn text already says the sibling only takes over runtime records.)
• Security-sensitive changes were reviewed for secrets, auth, and unsafe defaults. (No auth/credential path touched.)

Summary by CodeRabbit

• Bug Fixes

  • Improved proxy startup when launching a second instance alongside an existing proxy.
  • Prevented the secondary instance’s selected port from replacing the configured port used by the primary proxy.
  • Preserved expected port selection behavior during startup retries.

• Tests

  • Added coverage for sibling proxy startup and port persistence scenarios.

[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: Team

Run ID: 24fdc090-3d48-479d-a3cc-f28eade8d765

📥 Commits

Reviewing files that changed from the base of the PR and between d23eab4 and 591364f.

📒 Files selected for processing (4)

• src/cli/index.ts
• src/server/ports.ts
• tests/cli-dispatch.test.ts
• tests/ports.test.ts

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

---

📝 Walkthrough

Walkthrough

handleStart now identifies sibling proxy launches and passes that state through both port-selection paths. shouldPersistSelectedPort skips configuration updates for siblings. Tests cover the persistence rule and both CLI call sites.

Changes

Sibling port persistence

Layer / File(s)	Summary
Add sibling persistence rule src/server/ports.ts, tests/ports.test.ts	shouldPersistSelectedPort accepts an optional sibling flag and returns false for sibling starts. Tests verify sibling and normal-start behavior.
Propagate sibling state through CLI port selection src/cli/index.ts, tests/cli-dispatch.test.ts	handleStart sets siblingStart when a live owner exists and passes it to both chooseListenPort calls. Tests verify both call sites and the assignment.

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

Merge Risk: ⚪ Minimal · up to 59136

This localized change prevents sibling starts from persisting a temporary port into the saved configuration; no actionable merge-blocking risk remains after normal checks and review.

Suggested reviewers: ingwannu

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 25.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 4 functions across 4 files.	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: preventing a sibling start from persisting its port to config.port.
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.

• Fix all pre-merge checks with AI

✨ 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 codex/sibling-start-no-port-persist

---

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

[lidge-jun]

리뷰 · 우선순위 74 / 80

이 PR은 #3188이 연 ocx start --port X 형제(sibling) 경로의 남은 구멍입니다. 이미 설정된 포트(예: 10100)에 프록시가 살아 있을 때 --port 10198 같은 다른 포트로 두 번째 인스턴스를 띄우는 동작은 그대로 둡니다. 문제는 그 형제 인스턴스가 chooseListenPort를 거치면서 shouldPersistSelectedPort(config.port, X, X)가 참이 되어, 아직 살아 있는 본 프록시 아래에서 config.port를 X로 바꿔 버리는 점이었습니다.

메인테이너 실기에서 재현됐습니다. 프로브로 start --port 10198을 몇 번 돌린 뒤 프로세스가 끝나면 config.port=10198이 남습니다. 그다음 ocx stop + ocx service가 config.port를 읽어 launchd plist에 --port 10198을 굽고, Codex openai_base_url도 10198로 돌립니다. 10198에 떠 있는 리스너가 없는데도 서비스가 10100에서 조용히 빠져 나간 상태입니다. 형제는 이 홈의 새 주인이 아니라 임시 두 번째 인스턴스이므로, 포트 영속화는 하면 안 됩니다.

고침은 작습니다. handleStart가 형제 결정을 siblingStart 플래그로 기록하고, 초기 포트 고르기와 EADDRINUSE 재고르기 두 chooseListenPort 호출 모두에 { sibling: siblingStart }를 넘깁니다. shouldPersistSelectedPort는 options.sibling이면 무조건 false입니다. 일반 첫 시작 persist와 fallback 포트 non-persist 규칙은 그대로입니다. 지금 dev(HEAD d23eab43a, package 2.40.0)의 src/cli/index.ts / src/server/ports.ts를 대조해 보면, 형제 경고 문구와 decideStartWithLiveOwner의 sibling 분기는 이미 있고, persist 가드만 빠져 있던 상태와 일치합니다.

테스트도 핵심만 짚습니다. tests/ports.test.ts는 (10100, 10198, 10198, { sibling: true }) → false, 플래그 없으면 같은 인자 → true를 고정합니다. tests/cli-dispatch.test.ts는 소스 핀으로 chooseListenPort 호출 두 곳이 모두 sibling: siblingStart를 실어 나르는지 확인합니다. 재고르기 경로만 빠지면 예전 버그가 조용히 돌아오기 때문에, 이 핀은 가치가 있습니다. types/config 분할과 무관한 좁은 버그 픽스라 닫을 대상이 아닙니다.

라인 src/server/ports.ts shouldPersistSelectedPort - sibling이면 즉시 false. 본문·실기 재현과 맞습니다. 일반 persist 조건은 그대로입니다.
라인 src/cli/index.ts siblingStart - 형제 분기에서만 true. service-stay-out / refuse 경로는 플래그를 건드리지 않습니다.
경로 chooseListenPort(..., { sibling }) 두 호출 사이트 - 초기 픽과 EADDRINUSE 재픽 모두 플래그를 넘깁니다. 소스 핀 테스트가 이 둘을 잠급니다.
경로 handleEnsure - 형제 persist 버그의 대상이 아닙니다. decideStartWithLiveOwner의 sibling은 handleStart 쪽입니다. 이 PR이 ensure를 안 건드린 것은 맞습니다.
잔여 위험(기존 #3188) - 형제가 떠 있는 동안 이 홈의 pid/runtime-port/Codex config를 가로채는 동작은 그대로입니다. 이번 PR은 config.port 영속화만 막습니다. CI는 대부분 통과, macos/macos-launchd만 아직 pending이라 merge 직전에 초록 확인이 필요합니다.

메인테이너의 판단이 필요한 지점

• 남은 CI(macos / macos-launchd)가 초록이 된 뒤 바로 머지할지.
• 이미 dogfood 호스트에서 config.port가 형제 포트로 남은 경우가 더 있는지(본문은 10100으로 복구한 한 건).
• fix(cli): let an explicit different --port start a sibling (rebase of #3144) #3188 형제의 pid/runtime/Codex config 가로채기 부작용을 후속 이슈로 남길지, 이번 범위 밖으로 둘지.

너의 추천
CI 초록 확인 후 dev에 바로 머지한다. 범위가 작고 실기 재현이 분명하며, 테스트가 persist 규칙과 두 호출 사이트를 함께 잠근다. types/config 분할과 무관하다. 머지 후 dogfood 호스트에서 ocx config get port / service plist가 다시 10100인지 한 번만 보면 충분하다.

이 댓글은 grok-bot이 작성했습니다