feat: expose background service lifecycle (#36895)

packages/cli/src/commands/handlers/service/restart.ts

@@ -9,7 +9,7 @@ export default Runtime.handler(
   Commands.commands.service.commands.restart,
   Effect.fn("cli.service.restart")(function* () {
     const options = yield* ServiceConfig.options()
-    yield* Service.stop(options)
+    yield* Service.stop(options, { targetVersion: options.version })
     const transport = yield* Service.start(options)
     process.stdout.write(transport.url + EOL)
   }),

packages/cli/src/commands/handlers/service/status.ts

@@ -8,7 +8,13 @@ import { ServiceConfig } from "../../../services/service-config"
 export default Runtime.handler(
   Commands.commands.service.commands.status,
   Effect.fn("cli.service.status")(function* () {
-    const found = yield* Service.discover(yield* ServiceConfig.options())
-    process.stdout.write((found ? found.url : "stopped") + EOL)
+    const options = yield* ServiceConfig.options()
+    const status = yield* Service.status(options)
+    if (status.type !== "ready") {
+      process.stdout.write(status.type + EOL)
+      return
+    }
+    const found = yield* Service.discover({ ...options, version: undefined })
+    process.stdout.write((found?.url ?? status.type) + EOL)
   }),
 )

packages/cli/src/server-process.ts

@@ -7,11 +7,10 @@ import { LayerNode } from "@opencode-ai/core/effect/layer-node"
 import { Global } from "@opencode-ai/core/global"
 import { InstallationVersion } from "@opencode-ai/core/installation/version"
 import { AppProcess } from "@opencode-ai/core/process"
-import { EffectFlock } from "@opencode-ai/core/util/effect-flock"
-import { start } from "@opencode-ai/server/process"
+import { ProcessLock } from "@opencode-ai/core/util/process-lock"
 import { randomBytes, randomUUID } from "node:crypto"
 import path from "node:path"
-import { Effect, Exit, FileSystem, Logger, Option, Redacted, Schedule, Schema, Scope } from "effect"
+import { Effect, FileSystem, Logger, Option, Redacted, Schedule, Schema } from "effect"
 import { HttpServer } from "effect/unstable/http"
 import { Env } from "./env"
 import { ServiceConfig } from "./services/service-config"
@@ -28,7 +27,7 @@ export type Options = {
 export const run = Effect.fn("cli.server-process.run")((options: Options) =>
   processEffect(options).pipe(
     Effect.provide(Updater.layer),
-    Effect.provide(AppNodeBuilder.build(LayerNode.group([Global.node, AppProcess.node, EffectFlock.node]))),
+    Effect.provide(AppNodeBuilder.build(LayerNode.group([Global.node, AppProcess.node]))),
     Effect.provide(NodeServices.layer),
   ),
 )
@@ -38,15 +37,15 @@ const processEffect = Effect.fnUntraced(function* (options: Options) {
   return yield* Effect.scoped(
     Effect.gen(function* () {
       const serviceOptions = options.mode === "service" ? yield* ServiceConfig.options() : undefined
-      const lockScope = serviceOptions === undefined ? undefined : yield* acquireServiceLock(serviceOptions.file)
-      if (
-        serviceOptions !== undefined &&
-        lockScope !== undefined &&
-        (yield* Service.discover(serviceOptions)) !== undefined
-      ) {
-        yield* Scope.close(lockScope, Exit.void)
-        return
+      if (serviceOptions !== undefined) {
+        const acquired = yield* ProcessLock.acquire(serviceOptions.file + ".lock").pipe(
+          Effect.as(true),
+          Effect.catchTag("ProcessLockHeldError", () => Effect.succeed(false)),
+        )
+        if (!acquired) return yield* Effect.void
+        if ((yield* Service.discover(serviceOptions)) !== undefined) return yield* Effect.void
       }
+      const { start } = yield* Effect.promise(() => import("@opencode-ai/server/process"))
       const environmentPassword = yield* Env.password
       // Keep the lease credential out of the environment inherited by tools.
       if (options.mode === "stdio") {
@@ -61,77 +60,82 @@ const processEffect = Effect.fnUntraced(function* (options: Options) {
             ? Redacted.value(environmentPassword)
             : randomBytes(32).toString("base64url")
       if (!password) return yield* Effect.fail(new Error("Missing server password"))
-      const address = yield* start({
+      const instanceID = randomUUID()
+      const server = yield* start({
         hostname: options.hostname ?? config.hostname ?? "127.0.0.1",
         port: Option.fromNullishOr(options.port ?? config.port),
         password,
-        restartContinuity: options.mode === "service",
+        instanceID,
+        service:
+          serviceOptions === undefined
+            ? undefined
+            : { onListen: (address) => register(address, password, instanceID, serviceOptions.file) },
       }).pipe(Effect.provide(Logger.layer([], { mergeWithExisting: false })))
-      if (lockScope !== undefined) {
-        yield* register(address, password)
-        yield* Scope.close(lockScope, Exit.void)
-      }
-      const url = HttpServer.formatAddress(address)
+      const url = HttpServer.formatAddress(server.address)
       console.log(options.mode === "stdio" ? JSON.stringify({ url }) : `server listening on ${url}`)
       if (options.mode === "default" && !environmentPassword) console.log(`server password ${password}`)
       const updater = yield* Updater.Service
       yield* updater.check().pipe(Effect.schedule(Schedule.spaced("10 minutes")), Effect.forkScoped)
-      return yield* options.mode === "stdio" ? waitForStdinClose() : Effect.never
+      return yield* options.mode === "service"
+        ? server.shutdown
+        : options.mode === "stdio"
+          ? waitForStdinClose()
+          : Effect.never
     }).pipe(Effect.annotateLogs({ role: "server" })),
   )
 })
 
-const acquireServiceLock = Effect.fnUntraced(function* (file: string) {
-  const flock = yield* EffectFlock.Service
-  const scope = yield* Scope.make()
-  yield* Effect.addFinalizer((exit) => Scope.close(scope, exit))
-  yield* flock
-    .acquire(`service:${file}`, undefined, { staleMs: 3_000, timeoutMs: 3_000 })
-    .pipe(Effect.provideService(Scope.Scope, scope))
-  return scope
-})
-
-// The latest atomic registration wins. A displaced process notices the new id,
-// exits, and cannot remove its successor's registration from its finalizer.
 const infoJson = Schema.fromJsonString(Service.Info)
 const encodeInfo = Schema.encodeEffect(infoJson)
 const decodeInfo = Schema.decodeUnknownEffect(infoJson)
 
-const register = Effect.fnUntraced(function* (address: HttpServer.Address, password: string) {
+const register = Effect.fnUntraced(function* (
+  address: HttpServer.Address,
+  password: string,
+  id: string,
+  file: string,
+) {
   const fs = yield* FileSystem.FileSystem
-  const options = yield* ServiceConfig.options()
-  const id = randomUUID()
-  const temp = options.file + "." + id + ".tmp"
-  yield* fs.makeDirectory(path.dirname(options.file), { recursive: true })
-  const encoded = yield* encodeInfo({
+  const temp = file + "." + id + ".tmp"
+  yield* fs.makeDirectory(path.dirname(file), { recursive: true })
+  const info = {
     id,
     version: InstallationVersion,
     url: HttpServer.formatAddress(address),
     pid: process.pid,
     password,
-  })
-  yield* fs.writeFileString(temp, encoded, { mode: 0o600 })
-  yield* fs.rename(temp, options.file)
-  const currentID = fs.readFileString(options.file).pipe(
+  }
+  const encoded = yield* encodeInfo(info)
+  const publish = fs.writeFileString(temp, encoded, { mode: 0o600 }).pipe(Effect.andThen(fs.rename(temp, file)))
+  yield* publish
+  const current = fs.readFileString(file).pipe(
     Effect.flatMap(decodeInfo),
-    Effect.map((info) => info.id),
     Effect.orElseSucceed(() => undefined),
   )
-  yield* currentID.pipe(
-    Effect.flatMap((current) =>
-      current === id
-        ? Effect.void
-        : Effect.try({ try: () => process.kill(process.pid, "SIGTERM"), catch: (cause) => cause }).pipe(Effect.ignore),
-    ),
-    Effect.repeat(Schedule.spaced("10 seconds")),
-    Effect.forkScoped,
-  )
+  const assertRegistration = Effect.gen(function* () {
+    const found = yield* current
+    if (
+      found !== undefined &&
+      found.id === info.id &&
+      found.version === info.version &&
+      found.url === info.url &&
+      found.pid === info.pid &&
+      found.password === info.password
+    )
+      return
+    yield* publish
+  })
   yield* Effect.addFinalizer(() =>
-    currentID.pipe(
-      Effect.flatMap((current) => (current === id ? fs.remove(options.file) : Effect.void)),
+    current.pipe(
+      Effect.flatMap((current) => (current?.id === id ? fs.remove(file) : Effect.void)),
       Effect.ignore,
     ),
   )
+  yield* assertRegistration.pipe(
+    Effect.catchCause((cause) => Effect.logWarning("failed to reassert service registration", { cause })),
+    Effect.repeat(Schedule.spaced("5 seconds")),
+    Effect.forkScoped,
+  )
 })
 
 function waitForStdinClose() {

packages/cli/src/services/server.ts

@@ -16,7 +16,7 @@ export type Args = {
 
 export type Resolved = {
   readonly endpoint: Service.Endpoint
-  readonly reconnect?: (attempt: number) => Promise<Service.Endpoint>
+  readonly reconnect?: (onStatus: (status: Service.Status) => void, signal: AbortSignal) => Promise<Service.Endpoint>
   readonly reload?: () => Promise<void>
 }
 
@@ -27,9 +27,7 @@ export const resolve = Effect.fn("cli.server.resolve")(function* (args: Args) {
     const password = yield* Env.password
     const endpoint = {
       url: args.server,
-      auth: password
-        ? { type: "basic" as const, username: "opencode", password: Redacted.value(password) }
-        : undefined,
+      auth: password ? { type: "basic" as const, username: "opencode", password: Redacted.value(password) } : undefined,
     } satisfies Service.Endpoint
     const client = OpenCode.make({ baseUrl: endpoint.url, headers: Service.headers(endpoint) })
     const health = yield* Effect.tryPromise({
@@ -51,19 +49,14 @@ export const resolve = Effect.fn("cli.server.resolve")(function* (args: Args) {
   const reconnectOptions = { ...options, version: undefined }
   return {
     endpoint,
-    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)),
-      ),
+    reconnect: (onStatus, signal) =>
+      Effect.runPromise(Service.start({ ...reconnectOptions, onStatus }).pipe(Effect.provide(NodeFileSystem.layer)), {
+        signal,
+      }),
     reload: () =>
       Effect.runPromise(
         Effect.gen(function* () {
-          yield* Service.stop(options)
+          yield* Service.stop(options, { targetVersion: options.version })
           yield* Service.start(options)
         }).pipe(Effect.provide(NodeFileSystem.layer)),
       ),
@@ -80,7 +73,8 @@ const resolveManaged = Effect.fnUntraced(function* (
   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"))
+  if (existing !== undefined)
+    return yield* Effect.fail(new Error("Background server version does not match this client"))
   return yield* Service.start(options)
 })
 

packages/cli/src/services/service-config.ts

@@ -1,7 +1,8 @@
 import { Global } from "@opencode-ai/core/global"
 import { InstallationChannel, InstallationVersion } from "@opencode-ai/core/installation/version"
+import { Hash } from "@opencode-ai/core/util/hash"
 import { Service } from "@opencode-ai/client/effect"
-import { Effect, FileSystem, Schema } from "effect"
+import { Effect, FileSystem, Option, Schema } from "effect"
 import { randomBytes } from "crypto"
 import path from "path"
 
@@ -20,25 +21,63 @@ const keys = ["hostname", "port", "password"] as const
 type Key = (typeof keys)[number]
 
 const decodeInfo = Schema.decodeUnknownEffect(Schema.fromJsonString(Info))
+const decodeRegistration = Schema.decodeUnknownEffect(Schema.fromJsonString(Service.Info))
+
+export function filename(channel = InstallationChannel) {
+  if (channel === "latest") return "service.json"
+  if (channel === "local") return "service-local.json"
+  return `service-${Hash.fast(channel)}.json`
+}
+
+export function versionBelongsToChannel(
+  version: string | undefined,
+  channel = InstallationChannel,
+  installedVersion = InstallationVersion,
+) {
+  if (version === undefined) return false
+  if (version === installedVersion) return true
+  const prefix = `0.0.0-${channel}-`
+  if (!version.startsWith(prefix)) return false
+  return /^\d+(?:\.\d+)?$/.test(version.slice(prefix.length))
+}
+
+export const migrateRegistration = Effect.fnUntraced(function* (
+  legacy: string,
+  file: string,
+  channel = InstallationChannel,
+  installedVersion = InstallationVersion,
+) {
+  if (channel === "latest" || channel === "local") return
+  const fs = yield* FileSystem.FileSystem
+  const text = yield* fs.readFileString(legacy).pipe(Effect.option)
+  if (Option.isNone(text)) return
+  const registration = yield* decodeRegistration(text.value).pipe(Effect.option)
+  if (Option.isNone(registration)) return
+  if (!versionBelongsToChannel(registration.value.version, channel, installedVersion)) return
+  yield* fs.writeFileString(file, text.value, { flag: "wx", mode: 0o600 }).pipe(Effect.ignore)
+})
 
 function configKey(key: string): Key {
-  if (keys.includes(key as Key)) return key as Key
+  if (key === "hostname" || key === "port" || key === "password") return key
   throw new Error(`Unknown service config key: ${key}`)
 }
 
-const env = Effect.gen(function* () {
+const paths = Effect.gen(function* () {
   const fs = yield* FileSystem.FileSystem
   const global = yield* Global.Service
-  const filename = InstallationChannel === "local" ? "service-local.json" : "service.json"
+  const name = filename()
+  const file = path.join(global.state, name)
   return {
     fs,
-    file: path.join(global.state, filename),
-    configFile: path.join(global.config, filename),
+    file,
+    legacyFile: path.join(global.state, "service.json"),
+    configFile: path.join(global.config, name),
   }
 })
 
 export const options = Effect.fnUntraced(function* () {
-  const { file } = yield* env
+  const { file, legacyFile } = yield* paths
+  yield* migrateRegistration(legacyFile, file)
   const compiled = path.basename(process.execPath).replace(/\.exe$/, "") !== "bun"
   const entrypoint = compiled ? undefined : process.argv[1]
   if (!compiled && entrypoint === undefined) return yield* Effect.fail(new Error("Failed to resolve CLI entrypoint"))
@@ -50,7 +89,7 @@ export const options = Effect.fnUntraced(function* () {
 })
 
 export const read = Effect.fn("cli.service-config.read")(function* () {
-  const { fs, configFile } = yield* env
+  const { fs, configFile } = yield* paths
   return yield* fs.readFileString(configFile).pipe(
     Effect.flatMap(decodeInfo),
     Effect.catch(() => Effect.succeed({} as Info)),
@@ -58,7 +97,7 @@ export const read = Effect.fn("cli.service-config.read")(function* () {
 })
 
 const write = Effect.fn("cli.service-config.write")(function* (value: Info) {
-  const { fs, configFile } = yield* env
+  const { fs, configFile } = yield* paths
   const temp = configFile + ".tmp"
   yield* fs.makeDirectory(path.dirname(configFile), { recursive: true })
   yield* fs.writeFileString(temp, JSON.stringify(value, null, 2) + "\n", { mode: 0o600 })
@@ -93,6 +132,7 @@ export const get = Effect.fn("cli.service-config.get")(function* (key?: string)
       return yield* password()
     }
   }
+  throw new Error(`Unknown service config key: ${key}`)
 })
 
 export const set = Effect.fn("cli.service-config.set")(function* (key: string, value: string) {