Repository navigation
fix(cli): guard serve before launching a second runtime - #20546
lifeodyssey wants to merge 1 commit into
Conversation
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Repository UI Review profile: CHILL Plan: Advanced Run ID: 📒 Files selected for processing (7)
Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review. 📝 WalkthroughWalkthrough
Priority: ⬇️ Low Merge Risk: ⚪ Minimal · up to The preflight behavior and launch boundary are covered without an identified merge-blocking risk. 🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
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. Comment |
There was a problem hiding this comment.
Important
The preflight runs before the interrupted serve-update handoff is read, so it can refuse and return the do-not-restart exit code during a supervised macOS update. Details inline.
Reviewed changes
- Pre-launch endpoint probe — new
serve-runtime-preflight.tsreadsorca-runtime.json, extracts the first local transport, and dials it within 250 ms;ENOENT/ECONNREFUSEDallow the launch, everything else refuses withprocessState: 'unverifiable'. serveOrcaAppgate — refuses before spawn, reports the CLI error envelope (recipe output stays a stdout-only channel), and returns the shared exit code 3.- Exit-code extraction —
SINGLE_INSTANCE_ALREADY_RUNNING_EXIT_CODEmoved tosrc/shared/single-instance-exit-code.ts;single-instance-lock.tsre-exports it. - Tests — preflight classification/launch-boundary cases, a real local-listener test, and a
launch.test.tspreflight mock.
ℹ️ Exit code 3 now covers "cannot verify", not just "another process owns this profile"
SINGLE_INSTANCE_ALREADY_RUNNING_EXIT_CODE is documented as the stable "another process owns this profile" contract that systemd RestartPreventExitStatus= keys off (#11935). This PR returns it for invalid_metadata, read_metadata_failed, connect_failed, timeout, and connection_closed as well, so a transient unreadable/corrupt metadata file or a hung probe now leaves the documented serve unit failed instead of retrying. If the fail-closed behavior is intended, the contract comment and docs/reference/headless-linux-server.md should say so; otherwise a distinct code preserves the #11935 semantics.
Technical details
# Broadened exit-3 contract
## Affected sites
- `src/cli/runtime/serve-runtime-preflight.ts` — every refusal path returns a `RuntimeClientError`.
- `src/cli/runtime/launch.ts:105` — all of them become `SINGLE_INSTANCE_ALREADY_RUNNING_EXIT_CODE`.
- `src/main/startup/single-instance-lock.ts:11` — comment still scopes the constant to "another process owns this profile".
- `docs/reference/headless-linux-server.md:223,242,948` — documents `RestartPreventExitStatus=3` as "stops the unit instead of retrying a launch".
## Required outcome
- Either document that exit 3 now also means "runtime state unverifiable" for the serve path, or split out a separate exit code so the systemd no-restart contract keeps its original meaning.
## Open questions for the human
- Is permanently stopping `orca-serve.service` on a transient `EIO`/timeout an accepted trade-off?DeepSeek Flash (free via Pullfrog for OSS) | 𝕏
| if (args.recipeJson && !args.projectRoot) { | ||
| throw new RuntimeClientError('invalid_argument', 'Recipe JSON output requires --project-root.') | ||
| } | ||
| const preflight = preflightServeRuntime(getDefaultUserDataPath()) |
There was a problem hiding this comment.
The preflight now runs before startOrcaServe, so it also gates the install-requested resume branch inside it. During a supervised macOS serve update the old child writes install-requested (before quitAndInstall) while still publishing an accepting orca-runtime.json; a supervisor restarted by launchd in that window gets refusal('endpoint_accepting'), returns exit 3, and never reads or resumes the handoff — and exit 3 is the do-not-restart contract, so the update is abandoned.
Technical details
# Preflight precedes the interrupted-handoff resume
## Affected sites
- `src/cli/runtime/launch.ts:97` — probe evaluated before `startOrcaServe`.
- `src/cli/runtime/launch.ts:154-165` — `resumeInterruptedServeUpdate` dispatch, only reached when the probe allows.
- `src/main/updater/updater-install-execution.ts:79` — handoff written before `quitAndInstall` (line 111); metadata is cleared only in will-quit teardown.
- `src/cli/runtime/serve-update-supervisor.ts:234` — comment asserts the LaunchAgent may restart the parent immediately.
- `src/cli/runtime/launch.test.ts:26` — preflight mock; the handoff tests never publish a live endpoint, so no test combines `install-requested` with an accepting endpoint.
## Required outcome
- A restarted supervisor that finds an `install-requested` handoff must still be able to resume it (waiting for the old owner to exit and the bundle to install) rather than refuse on the still-accepting old endpoint.
## Suggested approach (optional)
- Read the handoff first and skip the probe when `phase === 'install-requested'`, or move the preflight inside `startOrcaServe` after the handoff branch, so it only guards a genuinely fresh Electron spawn.
## Open questions for the human
- Confirm whether launchd can relaunch the CLI supervisor faster than the old child's disconnect-triggered quit teardown on macOS.
ELI5
An agent can fail to reach a healthy Orca runtime, then try
orca serveas recovery. Today that command starts another Electron process, which can abort inside macOS application registration before Orca's single-instance check runs. Refuse that launch before spawning when the published endpoint is accepting connections or its availability cannot be verified.What Changed
servelaunch, including--recipe-json.ENOENT/ECONNREFUSED. Reject unreadable/malformed discovery, denied access, unknown errors, early close, and timeout.EPERM/EACCESasruntime_permission_denied; other refusals useruntime_serve_refusedwith an explicit reason. Every refusal preservesprocessState: unverifiable: an accepting listener is enough to prevent a duplicate, but does not authenticate a process owner.--json; recipe refusals stay on stderr and leave recipe stdout empty.Why
The command-to-crash sequence is recorded in #14541 (comment): verification workers on Orca 1.4.200 tried
serveafterstale_bootstrap/ restart guidance, produced short-lived_RegisterApplicationSIGABRT children, then successfully contacted the pre-existing runtime. Separate recurrences were correlated at 01:10 and 10:25 on September 14 (UTC+08).This is a smaller alternative for the initial serve preflight portion of #14542 (thiagomsoares) and #14768 (Jinwoo-H), adapting their pre-spawn refusal and definitive endpoint-refusal approach. Both remained open at submission; #14768's last commit was August 15. This does not assert that either author has abandoned their work, and does not replace their broader launch diagnostics or concurrency work.
Differences from #14768: no RPC/PID liveness inference before the probe, no claim that denied/unknown access proves a running owner, no advice to stop an unverified PID or delete discovery metadata, and invalid metadata refuses rather than freeing the profile. Strict launch discovery is intentional: the existing CLI metadata readers discard errors or cast unchecked JSON, which is unsuitable for deciding whether to spawn. The existing metadata path helper and error formatter are reused.
Linked Issue
Addresses the duplicate-launch recovery path in #14541 (not an automatic closure of the underlying Electron startup issue).
Related: #12528, #19604, #13539, electron/electron#52815, lifeodyssey/animichi#1648. Complements #20487, which changes status/open diagnostics; this PR stands independently on main and does not require it.
Visual Proof
N/A — no rendered UI changes. Behavior proof and validation results are listed below. Raw logs, endpoints, credentials, and private session identifiers remain local.
Testing
ORCA_APP_EXECUTABLE=/usr/bin/falsesubstituted so accidental launch could not start Electron: sandbox access returnedruntime_permission_denied/EPERM; host access returnedruntime_serve_refused/endpoint_accepting. Both exited 3.pnpm lint,pnpm typecheck, changed-file code quality, andpnpm run build:clipassed on macOS. The optional development CLI symlink install was denied; the compiled CLI itself built and was invoked directly.ORCA_BACKGROUND_LAUNCH=1 node node_modules/vitest/vitest.mjs run --config config/vitest.config.ts src/cli). The focused set, including startup single-instance coverage, passed all 62 tests.launch.tswhile retaining the new tests; four launch-boundary cases failed withunexpected duplicate launch. Restoring the candidate passed all 62 focused tests. No Electron process was used in those fixtures.AI Disclosure
OpenAI Codex (GPT-6) assisted with incident correlation, implementation, testing, and self-review under the contributor's direction. The earlier contributions in #14542 and #14768 are credited above.
Review
Self-review only. Cross-platform: local Unix sockets / Windows named pipes, with portable error injection and a real-listener test using each platform's endpoint shape. Actual platform validation is macOS. The preflight sends no authentication token or RPC request, and error output omits raw OS messages and endpoint paths. Work is bounded to one file read and one short-lived connection per initial serve invocation. No UI, git-provider, workspace-type, or agent-provider policy changes.
Agent skill upstream boundary
Notes
Author
GitHub: @lifeodyssey. X/Twitter: not provided.
Checklist