Skip to content

fix(cli): preserve server startup failure cause#36478

Open
kitlangton wants to merge 1 commit into
v2from
startup-error-cause
Open

fix(cli): preserve server startup failure cause#36478
kitlangton wants to merge 1 commit into
v2from
startup-error-cause

Conversation

@kitlangton

@kitlangton kitlangton commented Jul 12, 2026

Copy link
Copy Markdown
Contributor

What

When the managed background service exits before registering, the CLI now explains what happened and what to do next instead of dumping a raw Effect error and bundled stack frames.

1. The background service does not register

OpenCode starts its normal managed-service flow, but the child exits before creating its registration.

Starting background server...

2. OpenCode presents the failure

The product output stays concise and uses the shipped CLI name for its recovery commands.

OpenCode could not start its background service

The service exited or never became ready.
The expected registration file was not created.

Try:
  opencode2 service restart
  OPENCODE_LOG_LEVEL=DEBUG opencode2

The default terminal no longer exposes /$bunfs/root paths or Effect frames. The complete typed cause remains in OpenCode's normal file log for debug diagnosis.

How

  • packages/client/src/effect/service.ts returns a typed Service.StartError with spawn, registration, or readiness stage information and preserves the original cause. Spawn completion now observes the child process's spawn/error events, so command launch failures are classified directly.
  • packages/cli/src/framework/startup-error.ts handles only Service.StartError at the CLI's top-level Effect boundary. It writes the user-facing presentation, records the full Effect cause through the existing observability layer, and leaves unrelated failures on the existing renderer.
  • The recovery command comes from Commands.name, which is injected as opencode2 in the compiled V2 binary and remains opencode for source runs.
  • packages/cli/test/service.test.ts covers a real child that exits before registration and a nonexistent spawn command. It asserts the exact rendered registration output and the retained nested cause.

Scope

This PR changes managed background-service startup failure classification and CLI presentation only. It does not change compatibility detection, service election, retry duration, or service-status behavior tracked by #36274.

Fixes #35158

Testing

  • bun run test from packages/cli: 27 passed, 0 failed across 7 files.
  • bun run test test/effect.test.ts test/contract-identity.test.ts test/import-boundaries.test.ts from packages/client: 9 passed, 0 failed.
  • bun typecheck from packages/cli: passed.
  • bun typecheck from packages/client: passed.
  • bunx prettier --check src/index.ts src/framework/startup-error.ts test/service.test.ts ../client/src/effect/service.ts from packages/cli: passed.
  • bun run build --single --skip-install from packages/cli: built the native opencode2 V2 binary.
  • Real-service terminal capture at 120x40: the compiled child exited before registration; default output contained no stack frames, while opencode.log retained ServiceStartError -> PlatformError -> ENOENT.
  • Push hook bun turbo typecheck --concurrency=3: 31 tasks passed.

Demo

Both screenshots use compiled V2 binaries, the same real managed-service failure, and identical 120x40 terminal dimensions.

Before (9ff7df07d6)

The CLI emits the generic raw failure, internal paths, and the complete Effect stack.

Before: raw startup failure and Effect stack

After (3b03692aef)

The CLI emits the actual user-facing startup failure presentation.

After: actionable background service startup failure

@kitlangton kitlangton force-pushed the startup-error-cause branch from fac667c to 18d0d52 Compare July 12, 2026 01:41
@kitlangton kitlangton changed the base branch from dev to v2 July 12, 2026 01:42
@kitlangton kitlangton force-pushed the startup-error-cause branch from 18d0d52 to 9ff7df0 Compare July 12, 2026 01:44
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

V2: critical startup failures should show actionable errors

1 participant