fix(cli): preserve server startup failure cause

packages/cli/src/framework/startup-error.ts

@@ -0,0 +1,30 @@
+import { Service } from "@opencode-ai/client/effect"
+import { Cause, Effect } from "effect"
+
+const RED_BOLD = "\x1b[91m\x1b[1m"
+const BOLD = "\x1b[1m"
+const RESET = "\x1b[0m"
+
+export function handle(cause: Cause.Cause<unknown>, command: string) {
+  const error = Cause.squash(cause)
+  if (!(error instanceof Service.StartError)) return Effect.failCause(cause)
+  return Effect.gen(function* () {
+    yield* Effect.logError("background service startup failed", { cause: Cause.pretty(cause) })
+    yield* Effect.sync(() => {
+      process.stderr.write(render(error, command))
+      process.exitCode = 1
+    })
+  })
+}
+
+export function render(error: Service.StartError, command: string) {
+  const detail =
+    error.stage === "spawn"
+      ? "The service process could not be started."
+      : error.stage === "registration"
+        ? "The service exited or never became ready.\nThe expected registration file was not created."
+        : "The service started but did not become ready."
+  return `\n${RED_BOLD}OpenCode could not start its background service${RESET}\n\n${detail}\n\n${BOLD}Try:${RESET}\n  ${command} service restart\n  OPENCODE_LOG_LEVEL=DEBUG ${command}\n`
+}
+
+export * as StartupError from "./startup-error"

packages/cli/src/index.ts

@@ -11,6 +11,7 @@ import { AppNodeBuilder } from "@opencode-ai/core/effect/app-node-builder"
 import { LayerNode } from "@opencode-ai/core/effect/layer-node"
 import { Global } from "@opencode-ai/core/global"
 import { AppProcess } from "@opencode-ai/core/process"
+import { StartupError } from "./framework/startup-error"
 
 const Handlers = Runtime.handlers(Commands, {
   $: () => import("./commands/handlers/default"),
@@ -51,6 +52,7 @@ Effect.logInfo("cli starting", {
 }).pipe(
   Effect.flatMap(() => Runtime.run(Commands, Handlers, { version: InstallationVersion })),
   Effect.annotateLogs({ role: "cli" }),
+  Effect.catchCause((cause) => StartupError.handle(cause, Commands.name)),
   Effect.provide(Updater.layer),
   Effect.provide(AppNodeBuilder.build(LayerNode.group([Global.node, AppProcess.node]))),
   Effect.provide(Observability.layer),

packages/cli/test/service.test.ts

@@ -11,11 +11,72 @@ import { SessionV2 } from "@opencode-ai/core/session"
 import { SessionEvent } from "@opencode-ai/core/session/event"
 import { SessionTable } from "@opencode-ai/core/session/sql"
 import { expect, test } from "bun:test"
-import { Effect, Schedule, Schema } from "effect"
+import { Cause, Effect, Exit, Schedule, Schema } from "effect"
 import fs from "node:fs/promises"
 import os from "node:os"
 import path from "node:path"
 import { ServiceConfig } from "../src/services/service-config"
+import { StartupError } from "../src/framework/startup-error"
+
+const RED_BOLD = "\x1b[91m\x1b[1m"
+const BOLD = "\x1b[1m"
+const RESET = "\x1b[0m"
+
+test("renders a missing registration as an actionable startup failure", async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "opencode-service-start-"))
+  const registration = path.join(root, "server.json")
+  const script = path.join(root, "exit.ts")
+  await Bun.write(script, "process.exit(1)\n")
+
+  try {
+    const exit = await Service.start({ file: registration, command: [process.execPath, script] }).pipe(
+      Effect.provide(NodeFileSystem.layer),
+      Effect.exit,
+      Effect.runPromise,
+    )
+
+    expect(Exit.isFailure(exit)).toBe(true)
+    if (Exit.isFailure(exit)) {
+      const error = Cause.squash(exit.cause)
+      expect(error).toBeInstanceOf(Service.StartError)
+      if (error instanceof Service.StartError) {
+        expect(StartupError.render(error, "opencode2")).toBe(
+          `\n${RED_BOLD}OpenCode could not start its background service${RESET}\n\nThe service exited or never became ready.\nThe expected registration file was not created.\n\n${BOLD}Try:${RESET}\n  opencode2 service restart\n  OPENCODE_LOG_LEVEL=DEBUG opencode2\n`,
+        )
+      }
+      expect(Cause.pretty(exit.cause)).toContain(
+        `[cause]: PlatformError: NotFound: FileSystem.readFile (${registration})`,
+      )
+    }
+  } finally {
+    await fs.rm(root, { recursive: true, force: true })
+  }
+})
+
+test("reports a service spawn failure without losing its cause", async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "opencode-service-spawn-"))
+  const command = path.join(os.tmpdir(), "opencode-command-that-does-not-exist")
+  try {
+    const exit = await Service.start({ file: path.join(root, "server.json"), command: [command] }).pipe(
+      Effect.provide(NodeFileSystem.layer),
+      Effect.exit,
+      Effect.runPromise,
+    )
+
+    expect(Exit.isFailure(exit)).toBe(true)
+    if (Exit.isFailure(exit)) {
+      const error = Cause.squash(exit.cause)
+      expect(error).toBeInstanceOf(Service.StartError)
+      if (error instanceof Service.StartError) {
+        expect(error.stage).toBe("spawn")
+        expect(StartupError.render(error, "opencode2")).toContain("The service process could not be started.")
+      }
+      expect(Cause.pretty(exit.cause)).toContain(command)
+    }
+  } finally {
+    await fs.rm(root, { recursive: true, force: true })
+  }
+})
 
 test("local channel stores service config with the local service filename", async () => {
   const root = await fs.mkdtemp(path.join(os.tmpdir(), "opencode-service-"))