Skip to content

fix(cli): guard serve before launching a second runtime - #20546

Open
lifeodyssey wants to merge 1 commit into
stablyai:mainfrom
lifeodyssey:codex/guard-serve-runtime-access
Open

lifeodyssey wants to merge 1 commit into
stablyai:mainfrom
lifeodyssey:codex/guard-serve-runtime-access

Conversation

@lifeodyssey

Copy link
Copy Markdown
Contributor

ELI5

An agent can fail to reach a healthy Orca runtime, then try orca serve as 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

  • Add one bounded (250 ms) local endpoint probe before the initial serve launch, including --recipe-json.
  • Allow the existing launch path when metadata is absent or the published endpoint returns ENOENT / ECONNREFUSED. Reject unreadable/malformed discovery, denied access, unknown errors, early close, and timeout.
  • Preserve EPERM / EACCES as runtime_permission_denied; other refusals use runtime_serve_refused with an explicit reason. Every refusal preserves processState: unverifiable: an accepting listener is enough to prevent a duplicate, but does not authenticate a process owner.
  • Return exit 3 for preflight refusals, reusing the supervisor no-restart contract. Emit the existing CLI error envelope for --json; recipe refusals stay on stderr and leave recipe stdout empty.
  • Share the existing exit-code constant with startup. No PID signals, metadata deletion, RPC credentials, new transport, or remote wire change.

Why

The command-to-crash sequence is recorded in #14541 (comment): verification workers on Orca 1.4.200 tried serve after stale_bootstrap / restart guidance, produced short-lived _RegisterApplication SIGABRT 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

  • Manual rebuilt-CLI check against the existing runtime, with ORCA_APP_EXECUTABLE=/usr/bin/false substituted so accidental launch could not start Electron: sandbox access returned runtime_permission_denied / EPERM; host access returned runtime_serve_refused / endpoint_accepting. Both exited 3.
  • Automated regressions added: permission/read/parse failures, legacy transport metadata, real local listeners, disappeared endpoints, late error/close events, timeout, recipe stdout, and no spawn/PID signal after refusal.
  • pnpm lint, pnpm typecheck, changed-file code quality, and pnpm run build:cli passed on macOS. The optional development CLI symlink install was denied; the compiled CLI itself built and was invoked directly.
  • All 125 CLI test files / 1,233 tests passed with host access (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.
  • Regression control: temporarily restored upstream launch.ts while retaining the new tests; four launch-boundary cases failed with unexpected duplicate launch. Restoring the candidate passed all 62 focused tests. No Electron process was used in those fixtures.
  • An earlier restricted-context run and rerun timed out in the existing update-handoff supervisor test. Both the upstream-launcher control and final candidate passed that test with host access; the final complete CLI run also passed. This does not establish the precise cause of the earlier timeout.
  • Full repository tests and desktop/native build are left to CI; local validation covered the CLI build, complete CLI suite, startup single-instance tests, full lint, and all-project typecheck.

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

  • Not applicable: no skill sources, generated artifacts, or registry entries changed.

Notes

  • This is a refusal policy, not an ownership oracle: a foreign listener at the published path can also cause refusal. Inspect from the owning host; no destructive recovery is automated or prescribed.
  • It does not grant sandbox IPC access or restore heartbeat/worker_done delivery. Those remain in the linked transport issues.
  • Two calls racing on a genuinely empty profile can still both reach Electron. No pre-spawn reservation lock is added or claimed.
  • A first launch from a context without macOS Launch Services can still abort. The change prevents the observed recovery launches against existing/uncertain discovery, not every native startup failure.
  • The existing update-handoff supervisor and its replacement-launch policy are unchanged.
  • Remote/SSH: the probe examines only discovery belonging to the execution host. It never dials websocket metadata or substitutes local execution for an SSH target. It sends no wire frames and changes no remote protocol.
  • Desktop/native packaging and the full repository test suite are not claimed; local check results are recorded separately from CI and release status.

Author

GitHub: @lifeodyssey. X/Twitter: not provided.

Checklist

  • Focused on one bug path, with prior art and explicit scope.
  • ELI5, before/after behavior, and regression coverage included.
  • Cross-platform, SSH/remote, security, performance, and compatibility considered.
  • Local validation results and remaining CI/platform coverage recorded above.

@coderabbitai

coderabbitai Bot commented Sep 14, 2026

Copy link
Copy Markdown
Contributor

Review Change StackReview Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Advanced

Run ID: b3d78bd2-e016-4c5a-a1d3-d98234b8c86a

📥 Commits

Reviewing files that changed from the base of the PR and between 16d1ab8 and 97a6b3e.

📒 Files selected for processing (7)
  • src/cli/runtime/launch.test.ts
  • src/cli/runtime/launch.ts
  • src/cli/runtime/serve-runtime-listener.test.ts
  • src/cli/runtime/serve-runtime-preflight.test.ts
  • src/cli/runtime/serve-runtime-preflight.ts
  • src/main/startup/single-instance-lock.ts
  • src/shared/single-instance-exit-code.ts

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


📝 Walkthrough

Walkthrough

serveOrcaApp now checks runtime metadata and probes local Unix or named-pipe endpoints before spawning Orca. Active runtimes produce structured CLI errors and exit code 3; missing or inactive endpoints continue to launch. Project-root validation moved to serveOrcaApp, and the exit code is shared with startup locking. New tests cover metadata errors, connection outcomes, output channels, and real local listeners.

Priority: ⬇️ Low

Merge Risk: ⚪ Minimal · up to 97a6b

The preflight behavior and launch boundary are covered without an identified merge-blocking risk.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 10.00% which is insufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 10 functions across 7 files. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly and concisely describes the main change: preventing a second serve runtime from launching.
Description check ✅ Passed The description is complete and aligns with the template. It explains the change and rationale, links the related issue, documents behavior proof, testing, AI use, scope, cross-platform considerations…
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

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

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

@pullfrog pullfrog Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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.ts reads orca-runtime.json, extracts the first local transport, and dials it within 250 ms; ENOENT/ECONNREFUSED allow the launch, everything else refuses with processState: 'unverifiable'.
  • serveOrcaApp gate — 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_CODE moved to src/shared/single-instance-exit-code.ts; single-instance-lock.ts re-exports it.
  • Tests — preflight classification/launch-boundary cases, a real local-listener test, and a launch.test.ts preflight 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?

Pullfrog  | Fix all ➔ | Fix 👍s ➔ | View workflow run | Using DeepSeek Flash (free via Pullfrog for OSS) | 𝕏

Comment thread src/cli/runtime/launch.ts
if (args.recipeJson && !args.projectRoot) {
throw new RuntimeClientError('invalid_argument', 'Recipe JSON output requires --project-root.')
}
const preflight = preflightServeRuntime(getDefaultUserDataPath())

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant