feat(cli): add debug heap-dump command (#58252)

Author: Hona

.opencode/skills/opencode-dev/SKILL.md

@@ -12,17 +12,18 @@ Workflow for interactively exercising the V2 CLI/TUI and server while developing
 opencode V2 is a client/server system, not a single monolithic process:
 
 - **Server process** runs the Effect HTTP API (`packages/server`) and owns all domain state: sessions, database, plugins, permissions, Location services. It's started by the `serve` command (`packages/cli/src/commands/handlers/serve.ts`).
-- **TUI process** is a separate process that runs no application logic itself — it's an HTTP/SSE client of the server via the generated SDK (`createOpencodeClient` / `sdk.client.v2`).
-- **Discovery**: CLI processes find the shared server through a JSON registration file at `~/.local/state/opencode/service.json` (or `service-local.json` for the local/dev channel) containing `{id, version, url, pid}`. A separate password file under `~/.config/opencode/service.json` provides HTTP Basic auth. Before reusing a registration, the client calls `GET /health` to confirm the server is alive, authenticated, and version-compatible.
+- **TUI process** is a separate process that runs no application logic itself — it's an HTTP/SSE client of the server via `@opencode/client` (`OpenCode.make`).
+- **Discovery**: CLI processes find the shared server through a JSON registration file at `~/.local/state/opencode/service.json` (or `service-local.json` for the local/dev channel) containing `{id, version, url, pid, password}`; the password is used for HTTP Basic auth. Before reusing a registration, the client calls `GET /api/info` to confirm the server is alive, is the registered PID, and is version-compatible. `opencode service status` prints the registered URL.
 - **Sharing**: because of this registration/health-check dance, many concurrent `opencode`/TUI invocations converge on one shared background daemon rather than each spawning their own. If no compatible healthy daemon is found, a new one is spawned detached (`serve --service`) and registers itself.
 - **`bun dev service start|status|stop|restart`** manages this shared background daemon's lifecycle directly — useful when you need to force a fresh server, confirm one is running, or kill a stuck one.
 - **Standalone mode** (`--standalone`) opts a single invocation out of the shared daemon: it spawns a private one-off `serve --stdio --port 0` child tied to that invocation's lifetime, with its own random password. Use this to isolate a debugging session from your other running opencode sessions.
 - Every log line is tagged `role=server` or `role=cli` and a per-process `run=<id>`, so you can distinguish server-side and client-side activity in one shared log file (see "Logs" below) even when both roles are interleaved from concurrent processes.
 
 ## Starting the dev TUI
 
-- This package is the V2 CLI adapter. Run its `dev` script when testing the TUI; do not use the repository-root `bun dev`, which launches the legacy `packages/opencode` CLI.
-- Run commands from `packages/cli`. Use `bun dev` for most debugging so the TUI starts with a private V2 server.
+- `packages/cli` is the CLI and TUI entrypoint. `bun dev` from `packages/cli` and the repository-root `bun dev` both run `packages/cli/src/index.ts`.
+- `bun dev` connects to the shared local-channel background service (`service-local.json`), starting it if needed. Every worktree on the machine shares that service. Add `--standalone` for a private server tied to this one process.
+- Use `bun run dev:live` from the repository root to run this worktree's TUI against the installed `opencode` background server and your real sessions.
 
 ## Interactive debugging with termctrl
 
@@ -57,7 +58,7 @@ termctrl resize opencode-v2-dev --cols 100 --rows 30
 termctrl show opencode-v2-dev
 ```
 
-- Source changes may require restarting the process. Use `termctrl restart opencode-v2-dev` rather than assuming the running TUI reloaded the change.
+- Source changes may require restarting the process. Use `termctrl restart opencode-v2-dev` rather than assuming the running TUI reloaded the change. Restarting the TUI does not restart the shared background service, so run `bun dev service restart` after server-side changes, or use `--standalone`.
 - To exercise background-service behavior, use `bun dev service start`, `bun dev service status`, and `bun dev service stop`.
 - Always clean up the Terminal Control session when the check is complete:
 
@@ -67,13 +68,13 @@ termctrl stop opencode-v2-dev
 
 ## Comparing V2 against the legacy TUI
 
-Run both versions in separate Terminal Control sessions and save PNG-only captures at equivalent states:
+The legacy V1 CLI is still published as `opencode-ai` on npm; V2 is `@opencode/cli`. Run both versions in separate Terminal Control sessions and save PNG-only captures at equivalent states:
 
 ```bash
 # From packages/cli: local V2 TUI
 termctrl start opencode-v2-dev --host opentui --cols 112 --rows 34 -- bun dev
 
-# Released legacy TUI behavior reference
+# Released legacy V1 TUI behavior reference
 termctrl start opencode-legacy --host opentui --cols 112 --rows 34 -- bunx opencode-ai@latest
 
 termctrl save opencode-v2-dev --format png --out /tmp/opencode/v2.png
@@ -90,7 +91,7 @@ termctrl save opencode-legacy --format png --out /tmp/opencode/legacy.png
 - `bun dev api` accepts either an OpenAPI operation ID or a raw HTTP method plus path:
 
 ```bash
-bun dev api get /health
+bun dev api get /api/info
 bun dev api get /openapi.json
 bun dev api <operationId> --param key=value
 ```
@@ -99,13 +100,13 @@ bun dev api <operationId> --param key=value
 - If no compatible background server is registered, `bun dev api` starts one through the daemon service. Use `bun dev service status`, `bun dev service restart`, and `bun dev service stop` when you need explicit lifecycle control.
 - Prefer raw method/path calls for quick server debugging and operation IDs when exercising documented OpenAPI routes with path or query parameters.
 
-## Auditing installed `opencode2` sessions
+## Auditing installed `opencode` sessions
 
-Installed next-channel sessions normally use `~/.local/share/opencode/opencode-next.db` and `~/.local/share/opencode/log/opencode.log`; `OPENCODE_DB` can override the database. Before calling `opencode2 api`, inspect `~/.local/state/opencode/service.json` because the command may start a daemon when none is healthy.
+Installed (released) sessions use `~/.local/share/opencode/opencode.db` and `~/.local/share/opencode/log/opencode.log`. A local/dev checkout uses `opencode-local.db` and `opencode-local.log` instead, and `OPENCODE_DB` overrides the database. Run `opencode service status` before `opencode api`, because `opencode api` starts a server when none is healthy.
 
 For a supplied `ses_...` ID, compare three sources:
 
-- `opencode2 api get /api/session/active` and the Session/message endpoints for live server state.
+- `opencode api get /api/session/active` and the Session/message endpoints for live server state.
 - The database's ordered `event` rows for durable history.
 - `packages/tui/src/context/data.tsx` and the relevant route for client projection and rendering.
 
@@ -141,16 +142,24 @@ grep 'role=server' ~/.local/share/opencode/log/opencode-local.log
 
 ## Heap snapshots
 
-The CLI installs a `SIGUSR1` listener on non-Windows processes in `packages/cli/src/heap.ts`. Use it to capture the installed `opencode2` server without restarting it or attaching an inspector.
+On every platform, including Windows, capture the running background server without restarting it or attaching an inspector:
+
+```bash
+opencode debug heap-dump
+```
+
+It discovers the already-running service (never starts or replaces one), calls `POST /api/debug/heap-dump`, waits until the file is complete, and prints its server-local path. Pass `--server <url>` (with `OPENCODE_PASSWORD`) for a server started with `serve`. A 404 means the running server predates the endpoint.
+
+The Unix `SIGUSR1` listener in `packages/cli/src/heap.ts` shares the same writer (`packages/util/src/heap-snapshot.ts`) and is still useful for a process that is not an HTTP server, such as a TUI client:
 
 1. Find the processes and inspect their roles and memory:
 
 ```bash
-pgrep -a -f 'opencode2\.exe|opencode2'
+pgrep -af opencode
 ps -o pid,ppid,rss,vsz,lstart,etime,cmd -p <pid>,<pid>
 ```
 
-2. Signal the process whose heap needs investigation. For shared-service memory, target the `opencode2.exe serve --service` child, not the short wrapper/TUI process:
+2. Signal the process whose heap needs investigation. For shared-service memory, target the `opencode serve --service` process, not a TUI process:
 
 ```bash
 kill -USR1 <server-pid>
@@ -189,13 +198,13 @@ Heap serialization itself can temporarily increase RSS and allocator high-water
 
 The CLI installs a `SIGPROF` listener on non-Windows processes in `packages/cli/src/cpu-profile.ts`. One signal starts a ten-second CPU profile and stops it automatically; additional signals are ignored while a profile is active. There is no CPU profile CLI flag or environment variable.
 
-1. Get the PID from the health endpoint. For shared-service performance, target the server PID returned here rather than the short wrapper or TUI process:
+1. Get the PID from the info endpoint. For shared-service performance, target the server PID returned here rather than a TUI process:
 
 ```bash
-opencode2 api get /api/health
+opencode api get /api/info
 ```
 
-Use `bun dev api get /api/health` instead when targeting the local/dev channel.
+Use `bun dev api get /api/info` instead when targeting the local/dev channel.
 
 2. Start the capture:
 

packages/cli/src/commands/commands.ts

@@ -117,6 +117,15 @@ const Root = Spec.make(typeof OPENCODE_CLI_NAME === "string" ? OPENCODE_CLI_NAME
       commands: [
         Spec.make("agents", { description: "List all agents" }),
         Spec.make("config", { description: "List configuration sources" }),
+        Spec.make("heap-dump", {
+          description: "Write a heap snapshot of the running server and print its path",
+          params: {
+            server: Flag.String("server").pipe(
+              Flag.withDescription("Connect to a server URL instead of the background service"),
+              Flag.optional,
+            ),
+          },
+        }),
         Spec.make("paths", {
           description: "Show global paths (data, config, cache, state)",
           params: {

packages/cli/src/commands/handlers/debug/heap-dump.ts

@@ -0,0 +1,50 @@
+import { ClientError, OpenCode } from "@opencode/client"
+import { Service } from "@opencode/client/effect/service"
+import { Effect, Option, Predicate } from "effect"
+import { EOL } from "node:os"
+import { Commands } from "../../commands"
+import { Runtime } from "../../../framework/runtime"
+import { ServerConnection } from "../../../services/server-connection"
+import { ServiceConfig } from "../../../services/service-config"
+import { errorMessage } from "../../../util/error"
+
+const handler = Effect.fn("cli.debug.heap-dump")(function* (
+  input: Runtime.Input<(typeof Commands.commands.debug.commands)["heap-dump"]>,
+) {
+  const endpoint = yield* running(Option.getOrUndefined(input.server))
+  const client = OpenCode.make({ baseUrl: endpoint.url, headers: Service.headers(endpoint) })
+  const snapshot = yield* Effect.tryPromise({
+    try: (signal) => client.debug.heapDump({ signal }),
+    catch: (cause) =>
+      cause instanceof ClientError &&
+      cause.reason === "UnexpectedStatus" &&
+      Predicate.hasProperty(cause.cause, "status") &&
+      cause.cause.status === 404
+        ? new Error(`The server at ${endpoint.url} does not support heap dumps. Update and restart it first.`)
+        : cause,
+  })
+  process.stdout.write(snapshot.path + EOL)
+})
+
+export default Runtime.handler(Commands.commands.debug.commands["heap-dump"], (input) =>
+  handler(input).pipe(
+    Effect.catch((error) =>
+      Effect.sync(() => {
+        process.stderr.write(errorMessage(error) + EOL)
+        process.exitCode = 1
+      }),
+    ),
+  ),
+)
+
+// A fresh server has nothing worth capturing, so only an already-running one is used: never start,
+// replace, or restart the background service.
+const running = Effect.fnUntraced(function* (server: string | undefined) {
+  if (server !== undefined) return (yield* ServerConnection.resolve({ server })).endpoint
+  const options = yield* ServiceConfig.options()
+  const endpoint = yield* Service.discover({ ...options, version: undefined })
+  if (endpoint) return endpoint
+  return yield* Effect.fail(
+    new Error("No background server is running. Pass --server <url> to capture a server started another way."),
+  )
+})

packages/cli/src/heap.ts

@@ -1,6 +1,6 @@
 import { Global } from "@opencode/util/global"
+import { HeapSnapshot } from "@opencode/util/heap-snapshot"
 import { Effect, Queue } from "effect"
-import path from "node:path"
 
 export const listen = Effect.gen(function* () {
   const global = yield* Global.Service
@@ -16,18 +16,9 @@ export const listen = Effect.gen(function* () {
   )
   yield* Queue.take(signals).pipe(
     Effect.andThen(
-      Effect.suspend(() => {
-        const file = path.join(
-          global.log,
-          `heap-${process.pid}-${new Date().toISOString().replace(/[:.]/g, "")}.heapsnapshot`,
-        )
-        return Effect.gen(function* () {
-          yield* Effect.logInfo("writing heap snapshot", { path: file })
-          const { writeHeapSnapshot } = yield* Effect.tryPromise(() => import("node:v8"))
-          yield* Effect.try(() => writeHeapSnapshot(file))
-          yield* Effect.logInfo("heap snapshot written", { path: file })
-        }).pipe(Effect.catchCause((cause) => Effect.logError("failed to write heap snapshot", { path: file, cause })))
-      }),
+      HeapSnapshot.write(global.log).pipe(
+        Effect.catchCause((cause) => Effect.logError("failed to write heap snapshot", { cause })),
+      ),
     ),
     Effect.forever,
     Effect.forkScoped({ startImmediately: true }),

packages/cli/src/index.ts

@@ -42,6 +42,7 @@ const Handlers = Runtime.handlers(Commands, {
   debug: {
     agents: () => import("./commands/handlers/debug/agents"),
     config: () => import("./commands/handlers/debug/config"),
+    "heap-dump": () => import("./commands/handlers/debug/heap-dump"),
     paths: () => import("./commands/handlers/debug/paths"),
   },
   mcp: {

packages/cli/test/debug-heap-dump.test.ts

@@ -0,0 +1,95 @@
+import { expect, test } from "bun:test"
+import fs from "node:fs/promises"
+import path from "node:path"
+import { ServiceConfig } from "../src/services/service-config"
+import { OPENCODE_VERSION } from "../src/version"
+import { isolatedEnv } from "./fixture/environment"
+import { tmpdir } from "./fixture/tmpdir"
+
+// The server owns the snapshot writer (packages/server/test/heap-dump.test.ts); these cover how the
+// command finds a server, what it prints, and that it never starts or replaces one.
+
+test("prints the snapshot path from the registered server without replacing it", async () => {
+  await using root = await tmpdir()
+  const requests: Array<{ method: string; path: string; authorization: string | null }> = []
+  using server = fake((request) => {
+    requests.push({
+      method: request.method,
+      path: new URL(request.url).pathname,
+      authorization: request.headers.get("authorization"),
+    })
+    return Response.json({ path: "/server/log/heap-1-2.heapsnapshot", pid: process.pid })
+  })
+  const registration = await register(root.path, server.url.href)
+
+  const result = await cli(root.path, ["debug", "heap-dump"])
+
+  expect({ code: result.code, stderr: result.stderr, stdout: result.stdout.trim() }).toEqual({
+    code: 0,
+    stderr: "",
+    stdout: "/server/log/heap-1-2.heapsnapshot",
+  })
+  expect(requests).toEqual([
+    { method: "POST", path: "/api/debug/heap-dump", authorization: `Basic ${btoa("opencode:secret")}` },
+  ])
+  expect(await Bun.file(registration.file).json()).toEqual(registration.info)
+})
+
+test("fails without starting a server when none is registered", async () => {
+  await using root = await tmpdir()
+
+  const result = await cli(root.path, ["debug", "heap-dump"])
+
+  expect(result.stderr).toContain("No background server is running")
+  expect(result.code).toBe(1)
+  expect(await Bun.file(path.join(root.path, "state", "opencode", ServiceConfig.filename())).exists()).toBe(false)
+})
+
+test("explains when the server predates heap dumps", async () => {
+  await using root = await tmpdir()
+  using server = fake(() => new Response(null, { status: 404 }))
+
+  const result = await cli(root.path, ["debug", "heap-dump", "--server", server.url.href], {
+    OPENCODE_PASSWORD: "secret",
+  })
+
+  expect(result.stderr.trim()).toBe(
+    `The server at ${server.url.href} does not support heap dumps. Update and restart it first.`,
+  )
+  expect(result.code).toBe(1)
+})
+
+// Answers the health probe like a ready V2 server and passes every other request to `handle`.
+function fake(handle: (request: Request) => Response) {
+  return Bun.serve({
+    hostname: "127.0.0.1",
+    port: 0,
+    fetch: (request) =>
+      new URL(request.url).pathname === "/api/info"
+        ? Response.json({ version: OPENCODE_VERSION, pid: process.pid, urls: [] })
+        : handle(request),
+  })
+}
+
+async function register(root: string, url: string) {
+  const file = path.join(root, "state", "opencode", ServiceConfig.filename())
+  const info = { version: OPENCODE_VERSION, url, pid: process.pid, password: "secret" }
+  await fs.mkdir(path.dirname(file), { recursive: true })
+  await fs.writeFile(file, JSON.stringify(info))
+  return { file, info }
+}
+
+async function cli(root: string, args: string[], env: Record<string, string> = {}) {
+  const child = Bun.spawn([process.execPath, "run", path.join(import.meta.dir, "../src/index.ts"), ...args], {
+    cwd: path.join(import.meta.dir, ".."),
+    env: isolatedEnv(root, env),
+    stdout: "pipe",
+    stderr: "pipe",
+  })
+  const [stdout, stderr, code] = await Promise.all([
+    new Response(child.stdout).text(),
+    new Response(child.stderr).text(),
+    child.exited,
+  ])
+  return { stdout, stderr, code }
+}

packages/client/src/effect/api/api.ts

@@ -2269,6 +2269,9 @@ export interface VcsApi<E = never> {
   readonly diff: VcsDiffOperation<E>
 }
 
+export type DebugHeapDumpOutput = { readonly path: string; readonly pid: number }
+export type DebugHeapDumpOperation<E = never> = () => Effect.Effect<DebugHeapDumpOutput, E>
+
 export type DebugLocationListOutput = ReadonlyArray<Location.PublicRef>
 export type DebugLocationListOperation<E = never> = () => Effect.Effect<DebugLocationListOutput, E>
 
@@ -2279,6 +2282,7 @@ export type DebugLocationEvictOperation<E = never> = (
 ) => Effect.Effect<DebugLocationEvictOutput, E>
 
 export interface DebugApi<E = never> {
+  readonly heapDump: DebugHeapDumpOperation<E>
   readonly location: { readonly list: DebugLocationListOperation<E>; readonly evict: DebugLocationEvictOperation<E> }
 }
 

packages/client/src/effect/generated/client.ts

@@ -266,6 +266,7 @@ import type {
   VcsBranchListOutput,
   VcsDiffInput,
   VcsDiffOutput,
+  DebugHeapDumpOutput,
   DebugLocationListOutput,
   DebugLocationEvictInput,
   DebugLocationEvictOutput,
@@ -1624,6 +1625,9 @@ const adaptGroupVcs = (raw: RawClient["server.vcs"]) => ({
   diff: EndpointVcsDiff(raw),
 })
 
+const EndpointDebugHeapDump = (raw: RawClient["server.debug"]) => () =>
+  preserveEffect<DebugHeapDumpOutput>()(raw["debug.heapDump"]({}).pipe(Effect.mapError(mapClientError)))
+
 const EndpointDebugLocationList = (raw: RawClient["server.debug"]) => () =>
   preserveEffect<DebugLocationListOutput>()(raw["debug.location"]({}).pipe(Effect.mapError(mapClientError)))
 
@@ -1633,6 +1637,7 @@ const EndpointDebugLocationEvict = (raw: RawClient["server.debug"]) => (input?:
   )
 
 const adaptGroupDebug = (raw: RawClient["server.debug"]) => ({
+  heapDump: EndpointDebugHeapDump(raw),
   location: { list: EndpointDebugLocationList(raw), evict: EndpointDebugLocationEvict(raw) },
 })