@@ -12,6 +12,7 @@ import { PersistentPty } from "@opencode/schema/persistent-pty"
 import { HttpServer } from "effect/http"
 import { NetAddress } from "effect/net"
 import { Env } from "./env"
+import { PortOwner } from "./services/port-owner"
 import { ServiceConfig } from "./services/service-config"
 import { RetainedImage } from "./services/retained-image"
 import { ServiceRegistration } from "./services/service-registration"
@@ -76,7 +77,7 @@ const processEffect = Effect.fnUntraced(function* (options: Options) {
           : undefined
       if (findIncumbent !== undefined && (yield* findIncumbent) !== undefined) return
       // Desktop can launch the service directly without injecting its saved environment.
-      Object.assign(process.env, config.env)
+      Object.assign(process.env, ServiceConfig.processEnv(config.env))
       // Keep a package-manager or curl install replaceable while the service runs; Desktop updates its own copy.
       if (options.mode === "service" && process.platform === "win32" && RetainedImage.installed(global.home))
         yield* RetainedImage.retain(global.cache, "service")
@@ -174,9 +175,10 @@ const processEffect = Effect.fnUntraced(function* (options: Options) {
               const server = yield* launch.pipe(Effect.catchIf(addressInUse, () => Effect.void))
               if (server !== undefined) return server
             }
+            const owner = port === undefined ? undefined : yield* PortOwner.describe(port, hostname)
             return yield* Effect.fail(
               new Error(
-                `Managed service port ${port} on ${hostname} is already in use by another process. ` +
+                `Managed service port ${port} on ${hostname} is already in use by ${owner ?? "another process"}. ` +
                   "Configure another port with `opencode service set port <port>` and start the service again.",
                 { cause: error },
               ),
 
@@ -0,0 +1,48 @@
+import { AppProcess } from "@opencode/util/process"
+import { Effect } from "effect"
+import { ChildProcess } from "effect/process"
+import net from "node:net"
+
+export * as PortOwner from "./port-owner"
+
+// Best effort: names the process listening on a TCP port so a failed bind can say who holds it.
+// Windows has no cheap equivalent of lsof, so it keeps the generic message.
+export const describe = Effect.fnUntraced(function* (port: number, hostname?: string) {
+  if (process.platform === "win32") return undefined
+  const appProcess = yield* AppProcess.Service
+  const run = (command: string, args: ReadonlyArray<string>) =>
+    appProcess
+      .run(ChildProcess.make(command, args, { stdin: "ignore", killSignal: "SIGKILL" }), {
+        timeout: "1 second",
+        maxOutputBytes: 4096,
+      })
+      .pipe(
+        Effect.map((result) => (result.exitCode === 0 ? result.stdout.toString("utf8").trim() : "")),
+        Effect.orElseSucceed(() => ""),
+      )
+  const pid = listeners(yield* run("lsof", ["-nP", `-iTCP:${port}`, "-sTCP:LISTEN", "-Fpn"])).find((listener) =>
+    matches(listener.address, hostname),
+  )?.pid
+  if (pid === undefined) return undefined
+  const command = (yield* run("ps", ["-o", "command=", "-p", pid])).replace(/\s+/g, " ")
+  if (!command) return `PID ${pid}`
+  return `PID ${pid} (${command.length > 200 ? command.slice(0, 199) + "…" : command})`
+})
+
+function listeners(output: string) {
+  const found: { pid: string; address: string }[] = []
+  let pid: string | undefined
+  for (const line of output.split("\n")) {
+    if (line.startsWith("p")) pid = /^\d+$/.test(line.slice(1)) ? line.slice(1) : undefined
+    if (line.startsWith("n") && pid !== undefined)
+      found.push({ pid, address: line.slice(1, line.lastIndexOf(":")).replace(/^\[(.*)\]$/, "$1") })
+  }
+  return found
+}
+
+// lsof shows wildcard listeners as `*`; those also hold the port for any specific address.
+function matches(address: string, hostname: string | undefined) {
+  const host = hostname?.replace(/^\[(.*)\]$/, "$1")
+  if (host === undefined || net.isIP(host) === 0 || host === "0.0.0.0" || host === "::") return true
+  return address === "*" || address === host
+}
@@ -131,13 +131,22 @@ const paths = Effect.gen(function* () {
   }
 })
 
+// Clients find the service at its registration under XDG_STATE_HOME. A saved value would move the
+// registration away from them, and children of the service (tool shells, a relaunched Desktop) would
+// look for it in the wrong place, so the service keeps the state directory it was launched with.
+export function processEnv(env: Info["env"]) {
+  if (env === undefined) return undefined
+  const { XDG_STATE_HOME: _state, ...rest } = env
+  return rest
+}
+
 export const options = Effect.fnUntraced(function* (input: { readonly checkVersion?: boolean } = {}) {
   const { file, legacyRegistrationFiles } = yield* paths
   yield* Effect.forEach(legacyRegistrationFiles, (legacy) => migrateRegistration(legacy, file))
   return {
     file,
     version: input.checkVersion ? OPENCODE_VERSION : undefined,
-    env: (yield* read()).env,
+    env: processEnv((yield* read()).env),
     command: [
       ...selfCommand(),
       "serve",
 
@@ -116,7 +116,11 @@ serviceTest(
       () => undefined,
       (error: Error) => error.message,
     )
-    expect(conflict).toContain(`Managed service port ${home.port} on 127.0.0.1 is already in use by another process`)
+    expect(conflict).toContain(
+      `Managed service port ${home.port} on 127.0.0.1 is already in use by ${
+        process.platform !== "win32" && Bun.which("lsof") ? `PID ${process.pid} (` : "another process"
+      }`,
+    )
     expect(conflict).toContain("opencode service set port <port>")
     expect(await servers(home)).toEqual([])
     expect(await Bun.file(home.registration).exists()).toBe(false)
 
@@ -10,6 +10,9 @@ import { TestClock } from "effect/testing"
 import fs from "node:fs/promises"
 import os from "node:os"
 import path from "node:path"
+import { LayerNode } from "@opencode/util/effect/layer-node"
+import { AppProcess } from "@opencode/util/process"
+import { PortOwner } from "../src/services/port-owner"
 import { ServiceConfig } from "../src/services/service-config"
 import { ServiceRegistration } from "../src/services/service-registration"
 import { isolatedEnv, transpilerCache } from "./fixture/environment"
@@ -192,6 +195,72 @@ test("service config manages environment variables", async () => {
   }
 })
 
+test("saved service environment cannot move the registration's state directory", async () => {
+  expect(ServiceConfig.processEnv(undefined)).toBeUndefined()
+  expect(ServiceConfig.processEnv({ XDG_STATE_HOME: "/custom/state", XDG_DATA_HOME: "/custom/data", A: "1" })).toEqual({
+    XDG_DATA_HOME: "/custom/data",
+    A: "1",
+  })
+
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "opencode-service-env-state-"))
+  const layer = Global.layerWith({ config: path.join(root, "config"), state: path.join(root, "state") })
+  try {
+    await fs.mkdir(path.join(root, "config"), { recursive: true })
+    await Bun.write(
+      path.join(root, "config", ServiceConfig.filename()),
+      JSON.stringify({ env: { XDG_STATE_HOME: path.join(root, "elsewhere"), A: "1" } }),
+    )
+    const options = await Effect.runPromise(
+      ServiceConfig.options().pipe(Effect.provide(layer), Effect.provide(NodeFileSystem.layer)),
+    )
+    expect(options.env).toEqual({ A: "1" })
+    expect(options.file).toBe(path.join(root, "state", ServiceConfig.filename()))
+  } finally {
+    await fs.rm(root, { recursive: true, force: true })
+  }
+})
+
+test.skipIf(process.platform === "win32" || !Bun.which("lsof"))("port owner names the listening process", async () => {
+  using listener = Bun.serve({ hostname: "127.0.0.1", port: 0, fetch: () => new Response() })
+  using wildcard = Bun.serve({ hostname: "0.0.0.0", port: 0, fetch: () => new Response() })
+  const describe = (port: number | undefined, hostname?: string) =>
+    Effect.runPromise(PortOwner.describe(port ?? 0, hostname).pipe(Effect.provide(LayerNode.compile(AppProcess.node))))
+  expect(await describe(listener.port)).toStartWith(`PID ${process.pid} (`)
+  expect(await describe(listener.port, "127.0.0.1")).toStartWith(`PID ${process.pid} (`)
+  expect(await describe(listener.port, "localhost")).toStartWith(`PID ${process.pid} (`)
+  expect(await describe(listener.port, "127.0.0.2")).toBeUndefined()
+  expect(await describe(wildcard.port, "127.0.0.2")).toStartWith(`PID ${process.pid} (`)
+})
+
+test.skipIf(process.platform === "win32")("port owner gives up on a lookup that ignores SIGTERM", async () => {
+  const root = await fs.mkdtemp(path.join(os.tmpdir(), "opencode-port-owner-stuck-"))
+  const PATH = process.env.PATH
+  try {
+    await Bun.write(path.join(root, "lsof"), "#!/bin/sh\ntrap '' TERM\nsleep 10\n")
+    await fs.chmod(path.join(root, "lsof"), 0o755)
+    process.env.PATH = `${root}${path.delimiter}${PATH}`
+    const started = Date.now()
+    const owner = await Promise.race([
+      Effect.runPromise(PortOwner.describe(1).pipe(Effect.provide(LayerNode.compile(AppProcess.node)))),
+      Bun.sleep(4_000).then(() => "hung"),
+    ])
+    expect(owner).toBeUndefined()
+    expect(Date.now() - started).toBeLessThan(3_000)
+  } finally {
+    process.env.PATH = PATH
+    await fs.rm(root, { recursive: true, force: true })
+  }
+})
+
+test.skipIf(process.platform === "win32")("port owner is unknown for a free port", async () => {
+  const free = Bun.serve({ hostname: "127.0.0.1", port: 0, fetch: () => new Response() })
+  const port = free.port ?? 0
+  free.stop(true)
+  expect(
+    await Effect.runPromise(PortOwner.describe(port).pipe(Effect.provide(LayerNode.compile(AppProcess.node)))),
+  ).toBeUndefined()
+})
+
 test("service filenames share release channels and identify preview channels", () => {
   expect(ServiceConfig.filename("latest")).toBe("service.json")
   expect(ServiceConfig.filename("dev")).toBe("service.json")
@@ -548,7 +617,7 @@ test("unresponsive managed port occupancy reports a bounded conflict", async ()
   await fs.mkdir(path.dirname(registration), { recursive: true })
   await fs.writeFile(
     path.join(root, "config", "opencode", "service-local.json"),
-    JSON.stringify({ port: listener.port }),
+    JSON.stringify({ port: listener.port, env: { XDG_STATE_HOME: path.join(root, "elsewhere") } }),
   )
   const stale = {
     id: "stale",
@@ -558,8 +627,17 @@ test("unresponsive managed port occupancy reports a bounded conflict", async ()
     password: "stale",
   }
   await fs.writeFile(registration, JSON.stringify(stale))
+  // The port lookup is a child of the service, so it shows the state directory tools would inherit.
+  const lsof = process.platform === "win32" ? null : Bun.which("lsof")
+  if (lsof) {
+    await Bun.write(
+      path.join(root, "bin", "lsof"),
+      `#!/bin/sh\nprintf %s "$XDG_STATE_HOME" > "${path.join(root, "inherited-state")}"\nexec "${lsof}" "$@"\n`,
+    )
+    await fs.chmod(path.join(root, "bin", "lsof"), 0o755)
+  }
   const contender = Bun.spawn([process.execPath, path.join(import.meta.dir, "../src/index.ts"), "serve", "--service"], {
-    env: serviceEnv(root),
+    env: { ...serviceEnv(root), PATH: `${path.join(root, "bin")}${path.delimiter}${process.env.PATH}` },
     stderr: "pipe",
     stdout: "pipe",
   })
@@ -569,7 +647,12 @@ test("unresponsive managed port occupancy reports a bounded conflict", async ()
     const exitCode = await Promise.race([contender.exited, Bun.sleep(20_000).then(() => undefined)])
     expect(exitCode).toBe(1)
     const output = (await new Response(contender.stdout).text()) + (await new Response(contender.stderr).text())
-    expect(output).toContain(`Managed service port ${listener.port} on 127.0.0.1 is already in use by another process`)
+    expect(output).toContain(
+      `Managed service port ${listener.port} on 127.0.0.1 is already in use by ${
+        lsof ? `PID ${process.pid} (` : "another process"
+      }`,
+    )
+    if (lsof) expect(await Bun.file(path.join(root, "inherited-state")).text()).toBe(path.join(root, "state"))
     expect(await Bun.file(registration).json()).toEqual(stale)
   } finally {
     contender.kill("SIGTERM")