oh-my-opencode 5.0.0-beta.3 → 5.0.0-beta.30

package/dist/skills/data-scientist/references/visualization.md

@@ -0,0 +1,64 @@
+# Visualization
+
+A chart exists to answer a question at a glance. Render it with matplotlib (resident in most
+Python kernels; `uv run --with matplotlib` otherwise), then look at it before delivering —
+a chart nobody inspected is not evidence.
+
+## When to chart
+
+Chart when the user asked for one, and default to charting when the answer is a shape prose
+cannot carry: a trend over time, a distribution, a comparison across many categories, a
+relationship between variables. Skip the chart when a number or a five-row table answers the
+question — decoration dilutes the answer.
+
+## Chart type follows the question
+
+| Question shape | Chart |
+| --- | --- |
+| How did X change over time? | line, datetime x-axis |
+| Which categories are biggest? | horizontal bar, sorted by value |
+| How is X distributed? | histogram (tune bin count) or box plot per group |
+| Is X related to Y? | scatter; add a trend line only when it aids the eye |
+| Composition of a whole? | stacked or 100% bar — pie only for four or fewer slices |
+| Many series over time? | small multiples over one spaghetti chart |
+
+## Quality bar — every chart
+
+- Title states the finding ("Seoul overtook Busan in March"), not the dataset name.
+- Axis labels carry units. Tick density stays readable: `fig.autofmt_xdate()` for dates,
+  rotate or abbreviate long category names.
+- Size for the medium: inline chat reads well around `figsize=(10, 6)` at default dpi;
+  documents want `dpi=150` or more at export.
+- `tight_layout()` (or `constrained_layout=True`) before saving — clipped labels are the
+  most common chart defect.
+- Few series: label lines directly, or keep the legend inside empty plot space. Many
+  series: gray the context, color only the series that answers the question.
+- The default color cycle is fine; avoid rainbow palettes and 3D. Sort categorical bars by
+  value, never alphabetically.
+
+## CJK and other non-Latin text
+
+Matplotlib's default font renders CJK as empty boxes (tofu). Set a fallback before plotting
+whenever any label or title contains CJK:
+
+```python
+import platform
+import matplotlib
+cjk = {"Darwin": "AppleGothic", "Windows": "Malgun Gothic"}.get(platform.system(), "Noto Sans CJK KR")
+matplotlib.rcParams["font.family"] = [cjk, "DejaVu Sans"]
+matplotlib.rcParams["axes.unicode_minus"] = False   # keeps the minus sign rendering
+```
+
+## Output contract
+
+1. Save a PNG next to the work: `plt.savefig(path, dpi=150, bbox_inches="tight")`.
+2. Also render inline when the surface displays rich output (kernels usually do).
+3. Report the file path together with the answer.
+
+## Visual QA — mandatory
+
+Open the produced image — kernel display, or the harness's image-reading surface — and
+check four things: labels readable and unclipped, no tofu or mojibake, nothing overlapping,
+and the chart actually shows the finding the title claims. A failed check means fix and
+re-render, not ship with a caveat. This one pass catches nearly every chart defect;
+skipping it is how tofu titles reach users.

package/dist/skills/data-scientist/scripts/ensure-js-deps.sh

@@ -0,0 +1,28 @@
+#!/usr/bin/env bash
+# Install @duckdb/node-api into a user-level cache (outside any repo) and print the
+# absolute import path as the ONLY stdout line. Idempotent: re-runs reuse the install.
+set -euo pipefail
+
+log() { printf '[ensure-js-deps] %s\n' "$*" >&2; }
+
+CACHE_DIR="${OMO_DATA_SCIENTIST_CACHE:-$HOME/.cache/omo-data-scientist}"
+IMPORT_PATH="$CACHE_DIR/node_modules/@duckdb/node-api/lib/index.js"
+
+if ! command -v bun >/dev/null 2>&1; then
+  log "bun is required (https://bun.sh); install it, or use the uv lane instead."
+  exit 1
+fi
+
+if [ ! -f "$IMPORT_PATH" ]; then
+  log "installing @duckdb/node-api into $CACHE_DIR"
+  mkdir -p "$CACHE_DIR"
+  [ -f "$CACHE_DIR/package.json" ] || printf '{"name":"omo-data-scientist-cache","private":true}\n' > "$CACHE_DIR/package.json"
+  (cd "$CACHE_DIR" && bun add @duckdb/node-api 1>&2)
+fi
+
+if [ ! -f "$IMPORT_PATH" ]; then
+  log "install finished but $IMPORT_PATH is missing; inspect $CACHE_DIR"
+  exit 1
+fi
+
+printf '%s\n' "$IMPORT_PATH"

package/dist/skills/data-scientist/scripts/ensure-py-deps.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# Install polars + pyarrow for a given Python interpreter into a user-level cache
+# (never mutating the interpreter itself) and print the site directory as the ONLY
+# stdout line. Idempotent: re-runs reuse the install. arg1 = python executable
+# (default: python3); pass the kernel's sys.executable for kernel use.
+set -euo pipefail
+
+log() { printf '[ensure-py-deps] %s\n' "$*" >&2; }
+
+PYTHON_BIN="${1:-python3}"
+
+if ! command -v uv >/dev/null 2>&1; then
+  log "uv is required (see references/uv-setup.md); install it first."
+  exit 1
+fi
+if ! command -v "$PYTHON_BIN" >/dev/null 2>&1 && [ ! -x "$PYTHON_BIN" ]; then
+  log "python executable not found: $PYTHON_BIN"
+  exit 1
+fi
+
+TAG="$("$PYTHON_BIN" -c 'import sys; print(f"cp{sys.version_info[0]}{sys.version_info[1]}")')" \
+  || { log "not a working python interpreter: $PYTHON_BIN"; exit 1; }
+CACHE_DIR="${OMO_DATA_SCIENTIST_CACHE:-$HOME/.cache/omo-data-scientist}"
+SITE_DIR="$CACHE_DIR/py-$TAG"
+
+if [ ! -d "$SITE_DIR/polars" ] || [ ! -d "$SITE_DIR/pyarrow" ]; then
+  log "installing polars + pyarrow for $TAG into $SITE_DIR"
+  mkdir -p "$SITE_DIR"
+  uv pip install --python "$PYTHON_BIN" --target "$SITE_DIR" polars pyarrow 1>&2
+fi
+
+if [ ! -d "$SITE_DIR/polars" ]; then
+  log "install finished but $SITE_DIR/polars is missing; inspect $SITE_DIR"
+  exit 1
+fi
+
+printf '%s\n' "$SITE_DIR"

package/dist/skills/debugging/SKILL.md

@@ -53,6 +53,8 @@ These are not "optional extras". They are the correct tool in their domain, and
 | **Ghidra** | Any binary without trustworthy source — third-party closed libs, malware, vendored binaries whose behavior contradicts docs, CTF, firmware. **Use Ghidra's decompiler before `strings`/`objdump` guessing. It turns machine code into readable C.** | 📖 **[references/tools/ghidra.md](references/tools/ghidra.md)** |
 | **pwndbg** | Any native binary debugging session. It is GDB with the useful views (registers, stack, disasm, heap) always visible. **If you'd reach for plain `gdb`, reach for `pwndbg` instead — it is strictly a superset.** | 📖 **[references/tools/pwndbg.md](references/tools/pwndbg.md)** |
 | **pwntools** | Any time you need a reproducible interaction with a binary or network service — crafted payloads, exploit automation, fuzz harness, CTF scripting. | 📖 **[references/tools/pwntools.md](references/tools/pwntools.md)** |
+| **Frida** | Any running process you must instrument live without source or symbols — hook a function and print real argument values, trace calls, stub a return. Complements Ghidra: Ghidra reads the bytes, Frida watches them execute. **If Ghidra's static decompile has hit its limit, reach for Frida.** | 📖 **[references/tools/frida.md](references/tools/frida.md)** |
+| **DAP client (`dap.mjs`)** | Any time you would drive a debugger through a PTY and screen-scrape its text. Debuggers already speak the machine-readable Debug Adapter Protocol (debugpy, `dlv dap`, lldb-dap, js-debug); this bundled script drives it with bounded, monitorable output. **Prefer it over scraping `gdb`/`pdb` whenever the debugger speaks DAP.** Design modeled on oh-my-pi's `debug` tool (github.com/can1357/oh-my-pi). | 📖 **[references/tools/dap.md](references/tools/dap.md)** |
 
 **Failing to use these tools in their domain is a process failure, not a stylistic choice.** If the bug is in a browser and you did Phase 8 without Playwright, you are doing it wrong. If the bug is in a stripped binary and you read hex with `xxd`, you are doing it wrong. The references tell you how. Read them.
 

package/dist/skills/debugging/references/methodology/00-setup.md

@@ -35,6 +35,18 @@ The shape of the answers you need (commands in the runtime reference):
 | Is there an existing failing test or known repro? | Prefer amplifying an existing repro over inventing one. |
 | Are watchers (file watchers, hot reloaders, supervisors) going to restart the process mid-session? | If yes, turn them off before attaching. Restarts drop inspector connections and invalidate breakpoints. |
 
+### Output budget
+
+**Bound every inspection before you run it; unbounded output destroys the investigation's working context.**
+- Set a frame count, element count, or byte range for every query.
+- Prefer one targeted query over one broad dump: ask for the value that distinguishes hypotheses.
+- Page through more data only when the first bounded result says it is necessary; do not re-dump the whole object.
+- Treat any command whose output size you cannot predict as a command that needs a limit.
+- Before: GDB `bt` — After: GDB `bt 10` to inspect only the top ten frames.
+- Before: LLDB `memory read 0x1000` — After: `memory read 0x1000 -c 32` for a bounded byte range.
+- Before: LLDB `frame variable` — After: `frame variable --children-count 10 user` for one variable's children.
+- This is not presentation etiquette: a flooded context hides the decisive observation and can end the investigation.
+
 ### 4. Gate check
 
 If any answer is "I'm not sure", you are not ready for Phase 1. Investigate until certain. Guessing here cascades into false-positive hypotheses in Phase 2.

package/dist/skills/debugging/references/methodology/02-investigate.md

@@ -39,6 +39,27 @@ If two hypotheses have identical distinguishing evidence, they aren't actually d
 
 ## Phase 3 — Parallel Investigation
 
+### State freshness invariant
+
+**A debug session's state is a snapshot with a lifetime, not a fact you can carry forward indefinitely.**
+- Before any action that mutates the debuggee, re-observe the session's current state.
+- This includes continue, step, side-effecting evaluation, setting or removing breakpoints, and termination.
+- Record the current thread state and stop reason; those are the concrete tells for whether the old plan still applies.
+- An observation from an earlier turn may already be stale when the next action is issued.
+- Turns can be minutes apart while the debuggee runs at full speed, so this failure mode is normal, not exceptional.
+- If the thread state or stop reason has moved, re-observe the new state and do not replay the old plan.
+- Treat every mutation as conditional on the state you just observed, not on a remembered stop.
+
+### Failure-to-recovery taxonomy
+
+| Failure signature | Most likely cause | Next move |
+|---|---|---|
+| Adapter or debugger process failed to start | Wrong binary or missing installation | Verify the tool exists, then re-launch; do not retry blindly. |
+| Breakpoint accepted but never bound or verified | Source path mismatch, optimized-out code, or missing debug symbols | Check the binary was built with symbols and that the debugger-resolved path matches your file. |
+| Attach refused | Permissions, ptrace scope, SIP, or wrong PID | Fix the environment or target identity; a retry will not change it. |
+| No stop event within the expected window | Process is running, the breakpoint is unreachable, or the wait was too short | Pause and inspect threads rather than waiting longer. |
+| Session terminated unexpectedly | The debuggee crashed or exited | Capture the exit and crash evidence before restarting. |
+
 Branch depending on what's available.
 
 ### Path A: Team mode ENABLED

package/dist/skills/debugging/references/runtimes/go.md

@@ -42,10 +42,24 @@ dlv exec ./bin/myserver
 # Attach to a running process
 dlv attach $(pgrep myserver)
 
-# Headless mode (IDE / remote attach) — default port 2345
+# Delve's JSON-RPC API (IDE / remote attach) — default port 2345
 dlv debug --headless --listen=:2345 --api-version=2 ./cmd/server
 ```
 
+Delve exposes two distinct machine-readable interfaces:
+
+```bash
+# Debug Adapter Protocol: use this for editors and DAP-aware automation
+dlv dap --listen=127.0.0.1:2345
+
+# Delve's JSON-RPC API: use this for clients built directly against Delve's API
+dlv debug --headless --listen=127.0.0.1:2345 --api-version=2 ./cmd/server
+```
+
+Pick `dlv dap` when the client speaks DAP; pick headless JSON-RPC when you need Delve's
+native API or an existing JSON-RPC client. Both expose structured state, unlike scraping
+an interactive `(dlv)` session.
+
 ### Building a debuggable binary
 
 The compiler inlines and optimizes aggressively in normal builds, which makes stepping confusing. For serious debugging:

package/dist/skills/debugging/references/runtimes/native-binary.md

@@ -107,6 +107,24 @@ print(repr(data[max(0,pos-100):pos+200]))
 
 If you must keep using `strings`, lower the threshold: `strings -n 1 -t x ./target | rg ...`. The signal-to-noise drops sharply but short content is preserved.
 
+### Sanitizer build for a crashing C/C++ binary
+
+If the binary can be rebuilt from C/C++ sources, reproduce the crash with sanitizers before
+trying to infer the fault from stripped machine code. AddressSanitizer catches out-of-bounds
+accesses and use-after-free; UndefinedBehaviorSanitizer reports undefined operations.
+
+```bash
+# Rebuild with source locations and runtime checks enabled
+CFLAGS='-g -O1 -fsanitize=address,undefined' \
+CXXFLAGS='-g -O1 -fsanitize=address,undefined' \
+make clean all
+./target
+```
+
+The sanitizer report identifies the invalid access and its allocation/free or undefined
+operation stack, often making the root cause clear before dynamic analysis. For a binary
+that cannot be rebuilt, continue with the native tracing and debugger workflow below.
+
 Write the triage summary to the journal:
 
 ```markdown
@@ -229,6 +247,26 @@ lldb ./target
 (lldb) image dump symtab ./target
 ```
 
+### Data watchpoints — catch the corruption, not just the crash
+
+When a value is already wrong by the time execution reaches the crash, watch the memory
+address for writes and stop at the instruction that corrupts it. Use the address of the
+field or buffer identified from the static/dynamic hypothesis; see [tools/pwndbg.md](../tools/pwndbg.md)
+for the richer pwndbg watchpoint workflow rather than duplicating it here.
+
+```text
+# lldb: watch writes to an address (replace with a valid expression/address)
+(lldb) watchpoint set expression -- <addr>
+
+# gdb: stop on writes, or on reads when a read is the first observable symptom
+(gdb) watch *(<type> *)<addr>
+(gdb) rwatch *(<type> *)<addr>
+```
+
+A watchpoint is most useful after narrowing the suspect object: continue from its
+allocation or initialization, and inspect the backtrace and writer when it triggers.
+Hardware watchpoint slots are limited, so remove broad watchpoints before adding more.
+
 **Function interception via `DYLD_INSERT_LIBRARIES`** (macOS equivalent of `LD_PRELOAD`):
 
 ```bash

package/dist/skills/debugging/references/runtimes/node.md

@@ -98,6 +98,31 @@ bun test --inspect-brk                        # debug test runner
 
 **Critical**: Bun uses WebKit Inspector Protocol, not V8. `chrome://inspect` cannot connect directly. Use `debug.bun.sh` or the (currently buggy, per Bun docs) VS Code extension.
 
+### Scripted V8 inspector / CDP attach
+
+The inspector port also serves machine-readable HTTP discovery endpoints. `/json` lists
+inspectable targets; `/json/version` includes the WebSocket debugger URL. Connect that
+URL with the Chrome DevTools Protocol (CDP), rather than scraping `node inspect` text.
+`chrome-remote-interface` is the canonical scriptable npm client. When browser automation
+is already in play, use Playwright's `CDPSession` instead.
+
+```bash
+curl -s http://127.0.0.1:9229/json/version
+```
+
+```js
+const CDP = require('chrome-remote-interface');
+const version = await fetch('http://127.0.0.1:9229/json/version').then(r => r.json());
+const client = await CDP({ target: version.webSocketDebuggerUrl });
+await client.Runtime.enable();
+await client.Debugger.pause();
+```
+
+The same CDP commands can be sent through `chrome-remote-interface`; with Playwright,
+create a session with `await context.newCDPSession(page)` and call
+`await session.send('Runtime.enable')`. These V8/CDP examples do not apply to Bun's
+WebKit inspector protocol.
+
 ### Deno (native V8, Chrome DevTools / VS Code compatible)
 
 ```bash

package/dist/skills/debugging/references/runtimes/python.md

@@ -41,6 +41,19 @@ python -c 'import asyncio; print(asyncio.__version__)'
 | **post-mortem `pdb.pm()`** | Exception already happened, you want to inspect state | In an exception-caught REPL: `import pdb; pdb.pm()` after the exception propagates |
 | **debugpy (remote / IDE)** | IDE attach, remote host, containerized process | `python -m debugpy --listen 5678 --wait-for-client script.py` then attach from VS Code / PyCharm |
 
+`debugpy` is a Debug Adapter Protocol (DAP) adapter, not merely an IDE convenience.
+Its listener exposes a machine-readable protocol that an agent or other client can drive
+programmatically; it is a better boundary for automation than the human-oriented pdb REPL.
+
+```bash
+# Listen on the requested interface and wait before executing the script
+python -m debugpy --listen <host:port> --wait-for-client <script>
+```
+
+Use a DAP client to send structured requests and receive structured stopped/continued
+and stack/variable events. By contrast, `pdb` exposes prompt-oriented text: an agent
+using it must screen-scrape output and parse a human-facing REPL.
+
 ### Prefer `ipdb` or `pudb` over plain `pdb` when available
 
 - **ipdb** — drop-in replacement with tab completion, syntax highlighting. `pip install ipdb`, then `PYTHONBREAKPOINT=ipdb.set_trace` or use `import ipdb; ipdb.set_trace()`.

package/dist/skills/debugging/references/runtimes/rust.md

@@ -144,6 +144,47 @@ Rust symbols are mangled. Use either:
 
 ---
 
+## Sanitizers — memory and race bugs
+
+Nightly Rust exposes LLVM sanitizers through `-Z sanitizer`. Use them when a crash,
+data race, or leak is otherwise too timing- or state-dependent to explain from a
+backtrace; they replace guesswork with a report at the invalid operation.
+
+```bash
+# AddressSanitizer: out-of-bounds accesses and use-after-free
+cargo +nightly run -Z sanitizer=address
+
+# ThreadSanitizer: data races between threads
+cargo +nightly test -Z sanitizer=thread
+
+# LeakSanitizer: allocations that remain reachable at process exit
+cargo +nightly run -Z sanitizer=leak
+```
+
+`address` catches invalid memory access and use-after-free, `thread` catches unsynchronized
+concurrent accesses, and `leak` reports memory that was allocated but not released. Run
+the invocation that matches the suspected class; sanitizer diagnostics are especially
+useful before attaching a debugger to optimized or timing-sensitive code.
+
+---
+
+## rr — time-travel debugging
+
+On supported Linux systems, record the failure once, then replay it deterministically and
+run backwards from the failure with `reverse-continue` or `reverse-step`:
+
+```bash
+rr record ./target/debug/my_binary
+rr replay
+# (rr) reverse-continue
+# (rr) reverse-step
+```
+
+`rr` is Linux/x86-64 only. It does not apply on Apple Silicon, including arm64 macOS;
+use `rust-lldb` or a sanitizer there instead.
+
+---
+
 ## tokio-console — async task debugging
 
 For tokio-based async apps, this is essential when tasks are stuck or leaking.

package/dist/skills/debugging/references/scripts/dap.mjs

@@ -0,0 +1,267 @@
+#!/usr/bin/env node
+// Zero-dependency DAP REPL, modeled on oh-my-pi's debug tool. DAP framing is UTF-8 byte based.
+import { spawn } from "node:child_process";
+import { createConnection } from "node:net";
+import { createInterface } from "node:readline";
+import { stdin, stdout, stderr, env } from "node:process";
+
+export const MAX_ROWS = 100;
+export const MAX_OUTPUT_BYTES = 32 * 1024;
+
+export function isTcpAdapterSpec(spec) {
+  const separator = spec.lastIndexOf(":");
+  return separator > 0 &&
+    !spec.includes("/") &&
+    !spec.includes("\\") &&
+    /^\d+$/.test(spec.slice(separator + 1));
+}
+
+export class DapFrameParser {
+  constructor() { this.buffer = Buffer.alloc(0); }
+  push(chunk) {
+    this.buffer = Buffer.concat([this.buffer, Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)]);
+    const messages = [];
+    while (true) {
+      const marker = this.buffer.indexOf(Buffer.from("\r\n\r\n"));
+      if (marker < 0) break;
+      const header = this.buffer.subarray(0, marker).toString("ascii");
+      const match = header.match(/(?:^|\r\n)Content-Length:\s*(\d+)/i);
+      if (!match) { this.buffer = this.buffer.subarray(marker + 4); continue; }
+      const length = Number(match[1]);
+      const start = marker + 4;
+      if (this.buffer.length < start + length) break;
+      const body = this.buffer.subarray(start, start + length);
+      this.buffer = this.buffer.subarray(start + length);
+      try { messages.push(JSON.parse(body.toString("utf8"))); } catch { /* malformed frames are ignored */ }
+    }
+    return messages;
+  }
+}
+
+const timeoutMs = Number(env.DAP_TIMEOUT_MS || 15000);
+let transport = null;
+let parser = null;
+let nextSeq = 1;
+let initialized = false;
+let terminated = false;
+let currentStop = null;
+let topFrame = null;
+const pending = new Map();
+const breakpoints = new Map();
+// Event-driven waits. A tight `await setImmediate` busy-loop starves Bun's socket
+// data callbacks (the `initialized` event then never processes and launch deadlocks),
+// so every wait subscribes to the actual DAP event instead of polling state.
+const eventWaiters = new Map();
+function onEvent(name) {
+  return new Promise(resolve => {
+    const list = eventWaiters.get(name) || [];
+    list.push(resolve);
+    eventWaiters.set(name, list);
+  });
+}
+function emitEvent(name, value) {
+  const list = eventWaiters.get(name) || [];
+  eventWaiters.delete(name);
+  for (const resolve of list) resolve(value);
+}
+function sleep(ms) { return new Promise(resolve => setTimeout(resolve, ms)); }
+
+const debugTraffic = Boolean(env.DAP_DEBUG);
+function trace(direction, message) { if (debugTraffic) stderr.write(`DAP ${direction} ${JSON.stringify(message).slice(0, 300)}\n`); }
+function line(text) { stdout.write(`${text}\n`); }
+function error(kind, detail = "") { line(`ERR: ${kind}${detail ? ` ${detail}` : ""}`); }
+function send(message) {
+  trace(">", message);
+  const body = Buffer.from(JSON.stringify(message));
+  transport.write(Buffer.concat([Buffer.from(`Content-Length: ${body.length}\r\n\r\n`), body]));
+}
+function request(command, args = {}) {
+  if (!transport || terminated) return Promise.reject(new Error("no-session"));
+  const seq = nextSeq++;
+  send({ type: "request", seq, command, arguments: args });
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => { pending.delete(seq); reject(new Error("timeout")); }, timeoutMs);
+    pending.set(seq, { resolve: value => { clearTimeout(timer); resolve(value); }, reject: value => { clearTimeout(timer); reject(value); } });
+  });
+}
+function onMessage(message) {
+  trace("<", message);
+  if (message.type === "response") {
+    const wait = pending.get(message.request_seq);
+    if (!wait) return;
+    pending.delete(message.request_seq);
+    if (message.success === false) wait.reject(new Error("adapter-error")); else wait.resolve(message);
+  } else if (message.type === "event") {
+    if (message.event === "initialized") { initialized = true; emitEvent("initialized"); }
+    if (message.event === "stopped") { currentStop = message.body || {}; emitEvent("stopped", currentStop); }
+    if (message.event === "terminated" || message.event === "exited") { terminated = true; emitEvent("terminated"); }
+  }
+}
+function connectTransport(write, read, close = read) {
+  transport = { write: chunk => write.write(chunk), destroy: () => close.destroy?.() };
+  parser = new DapFrameParser();
+  read.on("data", chunk => { for (const message of parser.push(chunk)) onMessage(message); });
+  read.on("error", () => { if (!terminated) error("adapter-failed"); });
+  read.on("close", () => { if (!terminated) error("adapter-failed"); });
+}
+function connectSocket(socket) { connectTransport(socket, socket, socket); }
+async function startAdapter(spec) {
+  if (isTcpAdapterSpec(spec)) {
+    const separator = spec.lastIndexOf(":");
+    const socket = createConnection(Number(spec.slice(separator + 1)), spec.slice(0, separator));
+    connectSocket(socket);
+    await new Promise((resolve, reject) => { socket.once("connect", resolve); socket.once("error", reject); });
+  } else {
+    // A .mjs/.cjs/.ts adapter spec runs under the current Bun/Node runtime (e.g. the
+    // fixture adapter); any other spec is an adapter executable (lldb-dap, debugpy, dlv)
+    // spawned directly with its own argv.
+    const isScript = /\.(mjs|cjs|ts)$/.test(spec);
+    const [cmd, argv] = isScript ? [process.execPath, [spec]] : [spec, []];
+    const child = spawn(cmd, argv, { stdio: ["pipe", "pipe", "inherit"] });
+    connectTransport(child.stdin, child.stdout, child);
+    child.on("error", () => error("adapter-failed"));
+  }
+}
+// Waits for a stopped event. When `required` is false this is a best-effort grace
+// window (e.g. an optional stop-on-entry); it returns on the first stop OR on timeout
+// without failing, so adapters that run straight to a breakpoint are not broken.
+async function waitForStop(required = true, graceMs) {
+  if (currentStop || terminated) return Boolean(currentStop);
+  const budget = graceMs ?? timeoutMs;
+  await Promise.race([onEvent("stopped"), onEvent("terminated"), sleep(budget)]);
+  return Boolean(currentStop);
+}
+// Waits for the adapter's `initialized` event, event-driven (never a busy-loop).
+async function waitInitialized() {
+  if (initialized) return;
+  await Promise.race([onEvent("initialized"), sleep(timeoutMs)]);
+  if (!initialized) throw new Error("timeout");
+}
+// Adapters gate the `initialized` event on a recognized adapterID (debugpy withholds
+// it for unknown IDs, hanging the handshake). Infer a known ID from the adapter spec.
+function adapterIdFor(spec) {
+  const base = String(spec).split("/").pop().toLowerCase();
+  if (base.includes("debugpy") || base.includes("python")) return "debugpy";
+  if (base.includes("lldb")) return "lldb-dap";
+  if (base.includes("dlv") || base.includes("delve")) return "dlv";
+  if (base.includes("js-debug")) return "js-debug";
+  if (base.includes("gdb")) return "gdb";
+  return "omo";
+}
+async function launch(adapter, program, args) {
+  if (transport) return error("adapter-error", "session already exists");
+  try {
+    await startAdapter(adapter);
+    await request("initialize", { clientID: "omo-dap", adapterID: adapterIdFor(adapter), linesStartAt1: true, columnsStartAt1: true, pathFormat: "path" });
+    // Send launch BEFORE awaiting `initialized`: debugpy's adapter defers/flushes the
+    // initialized event until further client activity, so waiting for it first
+    // deadlocks the handshake. DAP allows launch any time after the initialize
+    // response; `initialized` is only required before configurationDone.
+    // stopOnEntry yields an initial stopped event with a real threadId, so the client
+    // can set breakpoints and inspect from a valid stopped state before continuing.
+    // `console: "internalConsole"` is REQUIRED by debugpy (without it the launch never
+    // spawns the debug server -> "Server is not available"); lldb-dap ignores it.
+    // lldb-dap reports the launch response success unreliably (false even when the
+    // process started and stopped); the process/stopped EVENTS are the real signal,
+    // so a non-success launch response is tolerated, not fatal.
+    await request("launch", { program, args, console: "internalConsole", justMyCode: false, stopOnEntry: true }).catch(() => null);
+    await waitInitialized();
+    await request("configurationDone").catch(() => null);
+    // Best-effort: lldb-dap stops at entry, other adapters run to the first breakpoint.
+    await waitForStop(false, 2000);
+    line("READY: launch");
+  } catch (e) { error(e.message === "timeout" ? "timeout" : e.message === "adapter-error" ? "adapter-error" : "adapter-failed"); }
+}
+async function snapshot() {
+  if (terminated) { line("EXIT: terminated"); return; }
+  try {
+    const response = await request("stackTrace", { threadId: currentStop?.threadId || 1, levels: 1 });
+    topFrame = response.body?.stackFrames?.[0];
+    const f = topFrame;
+    if (f) line(`STOP: stopped reason=${currentStop?.reason || "unknown"} threadId=${currentStop?.threadId || ""} ${f.name} at ${f.source?.path || "?"}:${f.line || 0}:${f.column || 0}`);
+    else line(`STOP: stopped reason=${currentStop?.reason || "unknown"} threadId=${currentStop?.threadId || ""} ? at ?:0:0`);
+  } catch (e) { error(e.message === "timeout" ? "timeout" : "adapter-error"); }
+}
+function boundedTable(header, rows) {
+  const all = rows.map(row => row.join("\t"));
+  const chosen = all.slice(0, MAX_ROWS);
+  const prefix = `${header.join("\t")}\n`;
+  let output = prefix;
+  let count = 0;
+  for (const row of chosen) {
+    const candidate = `${row}\n`;
+    if (Buffer.byteLength(output + candidate) > MAX_OUTPUT_BYTES) break;
+    output += candidate; count++;
+  }
+  stdout.write(output);
+  const rowDropped = all.length - count;
+  const byteDropped = Buffer.byteLength(all.slice(count).join("\n") + (all.length > count ? "\n" : ""));
+  if (rowDropped > 0 || byteDropped > 0) line(`TRUNCATED: rows dropped=${rowDropped} bytes dropped=${byteDropped}`);
+}
+async function command(input) {
+  const parts = input.trim().split(/\s+/);
+  const cmd = parts.shift();
+  if (!cmd) return;
+  if (cmd === "quit") { transport?.destroy?.(); process.exit(0); }
+  if (cmd === "launch") return launch(parts.shift(), parts.shift(), parts);
+  if (cmd === "attach") {
+    const [host, port] = (parts.shift() || "").split(":");
+    try {
+      await startAdapter(`${host}:${port}`);
+      await request("initialize", { clientID: "omo-dap", adapterID: "debugpy", linesStartAt1: true, columnsStartAt1: true, pathFormat: "path" });
+      await waitInitialized();
+      await request("attach", { justMyCode: false });
+      await request("configurationDone");
+      line("READY: attach");
+    } catch (e) { error(e.message === "timeout" ? "timeout" : "adapter-failed"); }
+    return;
+  }
+  if (!transport) return error("no-session");
+  try {
+    if (cmd === "break" || cmd === "rmbreak") {
+      const [file, lineNo] = (parts[0] || "").split(":");
+      if (!file || !lineNo) return error("invalid-args");
+      const set = breakpoints.get(file) || [];
+      const next = cmd === "break" ? [...set.filter(x => x.line !== Number(lineNo)), { line: Number(lineNo) }] : set.filter(x => x.line !== Number(lineNo));
+      const response = await request("setBreakpoints", { source: { path: file }, breakpoints: next });
+      breakpoints.set(file, next);
+      if (response.body?.breakpoints?.some(bp => bp.verified === false)) error("unverified-breakpoint"); else line(`BREAK: ${file}:${lineNo}`);
+    } else if (["continue", "step", "next", "stepin", "stepout", "pause"].includes(cmd)) {
+      const dapCmd = { step: "next", stepin: "stepIn", stepout: "stepOut" }[cmd] || cmd;
+      const threadId = currentStop?.threadId || 1;
+      currentStop = null;
+      await request(dapCmd, { threadId });
+      // Wait for the resulting stopped event (breakpoint hit / step completed) before
+      // snapshotting; without this the stack is read while the debuggee is still running.
+      await waitForStop();
+      await snapshot();
+    } else if (cmd === "stack") {
+      const r = await request("stackTrace", { threadId: currentStop?.threadId || 1, levels: Number(parts[0]) || 100 });
+      boundedTable(["FRAME", "NAME", "FILE", "LINE", "COLUMN"], (r.body?.stackFrames || []).map(f => [String(f.id), f.name, f.source?.path || "", String(f.line || ""), String(f.column || "")]));
+    } else if (cmd === "scopes") {
+      const r = await request("scopes", { frameId: topFrame?.id || 42 });
+      boundedTable(["NAME", "VARIABLES_REFERENCE"], (r.body?.scopes || []).map(s => [s.name, String(s.variablesReference)]));
+    } else if (cmd === "vars") {
+      if (!parts[0]) return error("invalid-args");
+      const r = await request("variables", { variablesReference: Number(parts[0]) });
+      boundedTable(["NAME", "VALUE"], (r.body?.variables || []).map(v => [v.name, v.value ?? ""]));
+    } else if (cmd === "eval") {
+      if (!parts.length) return error("invalid-args");
+      const r = await request("evaluate", { expression: parts.join(" "), frameId: topFrame?.id || 42 });
+      line(`EVAL\t${r.body?.result || ""}`);
+    } else if (cmd === "threads") {
+      const r = await request("threads"); boundedTable(["ID", "NAME"], (r.body?.threads || []).map(t => [String(t.id), t.name]));
+    } else if (cmd === "sessions") line("SESSION\tSTATE\n1\tactive");
+    else if (cmd === "terminate") { await request("terminate", { restart: false }); line("EXIT: terminated"); terminated = true; }
+    else error("invalid-args");
+  } catch (e) { error(e.message === "timeout" ? "timeout" : e.message === "adapter-error" ? "adapter-error" : "adapter-failed"); }
+}
+
+if (import.meta.main) {
+  // Serialize stdin commands: fire-and-forget (`void command(...)`) lets a `continue`
+  // race ahead of the launch handshake's configurationDone, and the adapter then
+  // drops or rejects the out-of-order request. Each line awaits the previous command.
+  let chain = Promise.resolve();
+  const rl = createInterface({ input: stdin, crlfDelay: Infinity });
+  rl.on("line", value => { chain = chain.then(() => command(value)).catch(() => {}); });
+}