fix(cli): unify server resolution

packages/cli/src/commands/commands.ts

@@ -37,6 +37,7 @@ export const Commands = Spec.make(typeof OPENCODE_CLI_NAME === "string" ? OPENCO
     Spec.make("api", {
       description: "Make a request to the running server",
       params: {
+        ...ServerParams,
         request: Argument.string("operation | method path").pipe(
           Argument.withDescription("OpenAPI operation ID, or an HTTP method followed by a path"),
           Argument.variadic({ min: 1, max: 2 }),

packages/cli/src/commands/handlers/api.ts

@@ -3,7 +3,7 @@ import { Effect, Option } from "effect"
 import { Commands } from "../commands"
 import { Runtime } from "../../framework/runtime"
 import { Service } from "@opencode-ai/client/effect"
-import { ServiceConfig } from "../../services/service-config"
+import { Server } from "../../services/server"
 
 const methods = new Set(["delete", "get", "head", "options", "patch", "post", "put"])
 
@@ -18,9 +18,12 @@ type OpenApi = {
 export default Runtime.handler(
   Commands.commands.api,
   Effect.fn("cli.api")(function* (input) {
-    const options = yield* ServiceConfig.options()
-    const found = yield* Service.discover(options)
-    const endpoint = found ?? (yield* Service.start(options))
+    const server = yield* Server.resolve({
+      server: Option.getOrUndefined(input.server),
+      standalone: input.standalone,
+      mismatch: "ignore",
+    })
+    const endpoint = server.endpoint
     const params = Option.getOrElse(input.param, () => ({}))
     const request = yield* resolveRequest(endpoint, input.request, params)
     const headers = new Headers(Service.headers(endpoint))

packages/cli/src/services/server.ts

@@ -10,11 +10,12 @@ import { Standalone } from "./standalone"
 export type Args = {
   readonly server?: string
   readonly standalone?: boolean
+  readonly mismatch?: "replace" | "ignore" | "error"
 }
 
 export type Resolved = {
   readonly endpoint: Service.Endpoint
-  readonly discover?: () => Promise<Service.Endpoint>
+  readonly reconnect?: (attempt: number) => Promise<Service.Endpoint>
   readonly reload?: () => Promise<void>
 }
 
@@ -45,11 +46,19 @@ export const resolve = Effect.fn("cli.server.resolve")(function* (args: Args) {
   }
 
   const options = yield* ServiceConfig.options()
-  const endpoint = yield* Service.start(options)
+  const endpoint = yield* resolveManaged(options, args.mismatch ?? "replace")
   const reconnectOptions = { ...options, version: undefined }
   return {
     endpoint,
-    discover: () => Effect.runPromise(Service.start(reconnectOptions).pipe(Effect.provide(NodeFileSystem.layer))),
+    reconnect: (attempt) =>
+      Effect.runPromise(
+        Effect.gen(function* () {
+          if (attempt > 3) return yield* Service.start(reconnectOptions)
+          const endpoint = yield* Service.discover(reconnectOptions)
+          if (endpoint !== undefined) return endpoint
+          return yield* Effect.fail(new Error("Background server is unavailable"))
+        }).pipe(Effect.provide(NodeFileSystem.layer)),
+      ),
     reload: () =>
       Effect.runPromise(
         Effect.gen(function* () {
@@ -60,6 +69,20 @@ export const resolve = Effect.fn("cli.server.resolve")(function* (args: Args) {
   } satisfies Resolved
 })
 
+const resolveManaged = Effect.fnUntraced(function* (
+  options: Service.Options,
+  mismatch: NonNullable<Args["mismatch"]>,
+) {
+  if (mismatch === "replace") return yield* Service.start(options)
+  if (mismatch === "ignore") return yield* Service.start({ ...options, version: undefined })
+
+  const compatible = yield* Service.discover(options)
+  if (compatible !== undefined) return compatible
+  const existing = yield* Service.discover({ ...options, version: undefined })
+  if (existing !== undefined) return yield* Effect.fail(new Error("Background server version does not match this client"))
+  return yield* Service.start(options)
+})
+
 function connectError(endpoint: Service.Endpoint, cause: unknown) {
   if (isUnauthorizedError(cause)) {
     return new Error(