feat(desktop): capture app and server heap snapshots into one folder - #58259

A desktop command palette command, Capture heap snapshots, writes snapshots of the desktop app and its local server into one folder. To get the server's snapshot there without moving a large file, opencode debug heap-dump and its endpoint now take an optional directory.

Palette	Done

CLI: --directory

$ opencode debug heap-dump --directory ./snapshots
/home/me/project/snapshots/heap-30616-2026-10-22T234311651Z.heapsnapshot

• Default unchanged. Without the flag, the server writes into its log directory, the same place as SIGUSR1.
• Created when missing. The server creates the directory, nested levels included.
• Relative paths resolve against the shell running the CLI. An absolute path passes through untouched, so a POSIX path for a remote --server stays intact on Windows.
• Query parameter, not a body. POST /api/debug/heap-dump?directory=…. A request without it, like opencode api post /api/debug/heap-dump or the previous CLI, works as before. A relative directory is rejected with InvalidRequestError (400).
• Failures say why. A directory the server cannot create or write into returns the filesystem's reason, e.g. Failed to write heap snapshot: EEXIST: file already exists, mkdir '/home/me/snapshots', instead of only pointing at the server log.
• Older servers ignore the parameter and write to their log directory. The CLI notices and warns: The server ignored --directory. Update and restart it to choose where snapshots go.

Desktop: one folder for the whole app

~/Downloads/opencode-heap-2026-10-22T234211397Z/
  heap-17116-2026-10-22T234211405Z.heapsnapshot   desktop's own server, written here by the server
  window-1-21984.heapsnapshot                     one per app window
  main-21448.heapsnapshot                         Electron main
  manifest.json                                   written last

sequenceDiagram
  participant W as window (debug renderer)
  participant M as main (debug/main.ts)
  participant S as desktop server (sidecar)
  W->>M: HeapSnapshots.write()
  M->>M: mkdir folder (0700)
  par
    M->>S: POST /api/debug/heap-dump?directory=folder
    S-->>M: { path, pid } once the file is complete
  and
    M->>W: webContents.takeHeapSnapshot(file), one window at a time
  end
  M->>M: v8.writeHeapSnapshot(main), last
  M->>M: manifest.json
  M-->>W: { directory, complete }

• Local server only. Always the desktop's own server (sidecar). Remote servers (SSH, WSL, paired machines) get no request; use opencode debug heap-dump there.
• Nothing large is moved or copied. The server writes straight into the folder, which main creates before asking. An older server that ignores directory keeps the file in its log directory, and the manifest records that path.
• Order. The server serializes while the windows do, since it is a separate process. Windows go one at a time, because a snapshot can double a process's memory and a leaking app may not have room for all of them at once. Main goes last, because writing its own heap blocks the loop that receives the window snapshots.
• Failures don't stop the capture. Each process gets a file, path or error entry in the manifest, and the toast says when something failed.
• Manifest. App and runtime versions, the snapshots with PIDs, app.getAppMetrics() (metricsMemoryUnit: "KiB"), and main's process.memoryUsage(). A process that grows while its JS heap does not leaks native memory.
• Private. The folder is created 0700 and the manifest 0600. Downloads is created when missing.
• Not included. Browser tabs (third-party page content; the agent's browser.heap tool covers them) and Web Workers.
• Lives in the debug GUI extension. New HeapSnapshots Ipc and a main entry. The command registers through createKeyed(ctx.uses.heap, …), so it shows only while main answers, never on the web. One capture runs at a time.

// manifest.json
{
  "snapshots": [
    { "process": "server", "pid": 17116, "file": "heap-17116-2026-10-22T234211405Z.heapsnapshot" },
    { "process": "window", "pid": 21984, "window": 1, "file": "window-1-21984.heapsnapshot" },
    { "process": "main", "pid": 21448, "file": "main-21448.heapsnapshot" }
  ],
  "metrics": [{ "pid": 21448, "type": "Browser", "memory": { "privateBytes": 137452 } }, "…"],
  "metricsMemoryUnit": "KiB"
}

New copy is English only; translations land separately. The OpenAPI documents include only the heap-dump change; unrelated drift from dev is left out. Docs: troubleshooting.mdx and cli/commands.mdx cover --directory and the desktop command, and the opencode-dev skill explains both.

Added by the opencode bot (AI-generated).

Related: #56058, #36677

Public API: adds an optional directory query parameter to POST /api/debug/heap-dump, --directory to opencode debug heap-dump, and { directory } to the clients' debug.heapDump() (backwards compatible)