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

package/packages/shared-skills/skills/data-scientist/references/execution-surfaces.md

@@ -0,0 +1,91 @@
+# Execution surfaces
+
+How to run the engines on each surface, and when to escalate between them.
+
+## Persistent kernel, JavaScript (Bun)
+
+One-time setup per machine — the bundled script installs `@duckdb/node-api` into a user-level
+cache outside any repo and prints the absolute import path (its only stdout line):
+
+```bash
+bash scripts/ensure-js-deps.sh          # run from the skill directory
+```
+
+In the kernel — top-level `require` may not exist, dynamic import always works:
+
+```js
+const { DuckDBInstance } = await import("<printed path>");
+const db = await DuckDBInstance.create(":memory:");
+const conn = await db.connect();
+const reader = await conn.runAndReadAll("SELECT category, SUM(v) AS total FROM 'data.csv' GROUP BY 1");
+reader.getRowObjects();                  // array of plain row objects
+```
+
+- The connection and any tables created live across cells — connect once per session, reuse.
+- COUNT/SUM over integer columns return BigInt; convert (`Number(x)` or `String(x)`) before
+  `JSON.stringify`, which throws on BigInt.
+- Bun builtins cover ingest gaps with zero installs: `Bun.JSONL.parse`, `Bun.JSON5.parse`,
+  `Bun.XML.parse`, `Bun.TOML.parse`, `Bun.Archive` for tarballs.
+- nodejs-polars is NOT part of this skill's toolkit: its API lags the Python release by
+  major versions (option objects that work in Python throw napi type errors). Polars work
+  belongs to the Python kernel (below).
+
+## Persistent kernel, Python (the default Python surface)
+
+duckdb, numpy, and matplotlib are typically resident — import and use them directly.
+Polars and pyarrow rarely ship with a kernel, so inject them once per session (run from the
+skill directory; the script installs on first use, then just prints the path):
+
+```python
+import subprocess, sys
+site = subprocess.run(["bash", "scripts/ensure-py-deps.sh", sys.executable],
+                      capture_output=True, text=True, check=True).stdout.strip()
+sys.path.insert(0, site)
+import polars as pl
+import pyarrow
+```
+
+- The install goes to a user cache keyed to the kernel's interpreter version; the
+  interpreter itself is never mutated (it is frequently an externally-managed system
+  Python, and mutating it breaks other tools).
+- After injection the whole Python stack is resident: `duckdb.sql(...).pl()` hands off via
+  Arrow, `duckdb.register(name, df)` goes the other way, and Polars lazy pipelines run
+  in-kernel across cells.
+- `duckdb.sql("SELECT ... FROM 'data.csv'")` queries files in place; without the injection,
+  keep results in DuckDB or fetch plain Python values (`.fetchall()`).
+- matplotlib figures render natively in kernels that display rich output; also save a PNG so
+  the artifact survives the session.
+
+## uv lane (fallback and isolation)
+
+```bash
+uv run --with duckdb --with polars --with pyarrow --with numpy python -c "<code>"
+```
+
+- Reach for it when there is no kernel, or when a heavy, crash-prone one-shot should not
+  run inside (and possibly take down) the kernel.
+- Include exactly the packages the code imports, plus pyarrow whenever `.pl()` is used.
+- Each invocation pays process spawn plus imports (roughly 0.3s warm) and re-reads its inputs —
+  fine for one-shots, wasteful for exploration loops.
+- Past a few lines, a temp file beats `-c` quoting: write the script, `uv run script.py`.
+
+## No kernel at all
+
+Same engines, one process per batch of questions:
+
+```bash
+bun -e '<the JavaScript kernel pattern above>'         # DuckDB via @duckdb/node-api
+uv run --with duckdb python -c "<sql via duckdb.sql>"  # DuckDB via Python
+uv run scripts/quick-query.py data.csv "SELECT ..."    # zero-code CLI fallback
+```
+
+## Escalation rules
+
+Start on the resident kernel. Move a step down when a concrete need appears:
+
+- polars/pyarrow missing from the kernel — inject via `ensure-py-deps.sh` (above), not a
+  uv one-shot.
+- Crash-prone or memory-hungry one-shot that should not take the kernel down — uv lane.
+- No kernel on this harness — one-shot recipes above.
+- Data lives remotely or exceeds local RAM — read `placement.md` and move the query, not
+  the data.

package/packages/shared-skills/skills/data-scientist/references/placement.md

@@ -0,0 +1,74 @@
+# Placement: where should this computation live?
+
+Decide before touching the data. Wrong placement wastes minutes (re-scanning a file queried
+ten times) or kills the machine (loading a dataset larger than RAM and swapping).
+
+## The probe (run first, once)
+
+Three facts, one cell or script:
+
+```python
+import os, shutil, subprocess, sys
+size = os.path.getsize("data.csv")            # bytes on disk
+disk_free = shutil.disk_usage(".").free       # spill headroom
+if sys.platform == "darwin":
+    ram = int(subprocess.run(["sysctl", "-n", "hw.memsize"], capture_output=True, text=True).stdout)
+else:
+    ram = os.sysconf("SC_PAGE_SIZE") * os.sysconf("SC_PHYS_PAGES")
+# row estimate without loading (DuckDB streams the scan):
+# duckdb.sql("SELECT count(*) FROM 'data.csv'")
+```
+
+CSV typically expands 2-5x in memory (string columns dominate); Parquet expands less
+predictably — compressed columns can inflate 10x. Estimate the working set from the
+decompressed size of the columns the question actually touches, not the file size.
+
+## In memory — load once, iterate
+
+When the working set stays within roughly 25% of free RAM AND the session will run repeated
+queries: load once (`CREATE TABLE t AS SELECT ...` in DuckDB, or a collected DataFrame),
+then iterate. One scan up front converts every later query from a file re-scan into
+milliseconds. Prune at load time — select only the needed columns, filter obvious dross —
+so the resident table is the working set, not the raw file.
+
+## In place / streaming — single pass, or bigger than RAM
+
+- Single-pass questions: query the file directly (`FROM 'data.csv'`). Loading first is pure
+  waste.
+- Bigger than RAM, SQL-shaped: cap DuckDB and let it spill —
+
+  ```sql
+  SET memory_limit = '4GB';
+  SET temp_directory = '/tmp/duckdb_spill';
+  ```
+
+  Aggregations, sorts, and window functions run out-of-core: slower, but bounded.
+- Bigger than RAM, DataFrame-shaped: Polars streaming (`collect(engine="streaming")` on a
+  lazy plan) in the resident kernel — or a uv one-shot on kernel-less harnesses.
+- Manual chunked loops (read N rows, process, repeat) are the last resort — the engines'
+  own out-of-core paths are faster and simpler than hand-rolled chunking.
+
+## Remote, in place — move the query to the data
+
+- Files behind http(s)/S3: DuckDB's httpfs extension reads Parquet and CSV remotely with
+  projection and predicate pushdown —
+
+  ```sql
+  INSTALL httpfs; LOAD httpfs;   -- one-time per environment
+  SELECT region, SUM(amount) FROM 'https://example.com/sales.parquet'
+  WHERE sale_date >= '2026-01-01' GROUP BY region;
+  ```
+
+  Only matching row groups and referenced columns cross the network, not the file.
+- Data on another machine you can execute on (a remote worker with more RAM, a box closer
+  to the data): run the query there and return the aggregate. A group-by result is
+  kilobytes; the source is gigabytes.
+- Decision rule: result much smaller than data — move the query. Repeated local iteration
+  on one slice — move a pruned copy of that slice once, then work locally in memory.
+
+## Hardware notes
+
+- Both engines parallelize across all cores by default; leave that alone except on shared
+  machines (`SET threads = N` in DuckDB, `POLARS_MAX_THREADS` for Polars).
+- Sustained swapping is the failure mode to avoid on memory-tight machines: when the probe
+  says the working set is close to free RAM, choose streaming, not hope.

package/packages/shared-skills/skills/data-scientist/references/polars-lane.md

@@ -0,0 +1,95 @@
+# Polars lane (resident Python kernel)
+
+When the work is DataFrame-shaped, Polars is the right engine — and it runs in the resident
+Python kernel by default. Kernels rarely ship polars/pyarrow preinstalled, so inject them
+once per session; the install lands in a user cache keyed to the kernel's interpreter, and
+the interpreter itself is never mutated (run with the skill directory as cwd, or spell out
+the script's absolute path):
+
+```python
+import subprocess, sys
+site = subprocess.run(["bash", "scripts/ensure-py-deps.sh", sys.executable],
+                      capture_output=True, text=True, check=True).stdout.strip()
+sys.path.insert(0, site)
+import polars as pl
+```
+
+After this, Polars lives across cells like every other resident engine: lazy frames,
+intermediate results, and the DuckDB handoff all persist with no per-call process cost.
+
+## When Polars wins over DuckDB SQL
+
+- Expression-chain transforms: many derived columns, per-column conditional logic, string
+  pipelines — `with_columns` chains read and optimize better than nested SQL SELECTs.
+- Reshapes: `unpivot`/`pivot` beat SQL gymnastics.
+- Larger-than-RAM pipelines: the streaming engine executes lazy plans in chunks.
+- Window-heavy feature engineering with `over()`.
+
+SQL-shaped work (joins, aggregation, ad-hoc questions) stays in DuckDB; mixed pipelines hand
+off zero-copy (below) instead of forcing one engine to do everything.
+
+## Current API (1.x) — older spellings fail or warn
+
+Training data is full of the pre-1.0 API. Current names:
+
+| Use | Not |
+| --- | --- |
+| `pl.scan_csv` / `pl.scan_parquet` + `.collect()` | eager `read_*` on big files |
+| `.group_by(...)` | `.groupby(...)` |
+| `pl.len()` | `pl.count()` |
+| `.collect(engine="streaming")` | `.collect(streaming=True)` |
+| `.unpivot(...)` | `.melt(...)` |
+
+Lazy first: `scan_*` builds a plan, pushes filters and projections down to the file read, and
+executes once at `.collect()`. Eager `read_*` is for small files mutated interactively.
+
+```python
+out = (pl.scan_csv("data.csv")
+       .filter(pl.col("value") > 100)
+       .group_by("category")
+       .agg(pl.col("value").sum().alias("total"), pl.len().alias("n"))
+       .sort("total", descending=True)
+       .collect())
+```
+
+## Zero-copy handoff with DuckDB
+
+Both engines speak Arrow, so mixed pipelines pay no serialization cost — all in-kernel:
+
+```python
+import duckdb
+df = duckdb.sql("SELECT * FROM 'orders.csv' o JOIN 'items.csv' i USING (id)").pl()
+shaped = df.with_columns((pl.col("qty") * pl.col("price")).alias("rev"))
+duckdb.register("shaped", shaped)
+out = duckdb.sql("SELECT category, SUM(rev) AS total FROM shaped GROUP BY 1").pl()
+```
+
+- `.pl()` requires pyarrow — the injection above provides it; without it, it raises
+  `ModuleNotFoundError`.
+- Never `.df()`: it requires pandas (raising without it), and pandas is banned and absent.
+
+## Streaming past RAM
+
+```python
+out = (pl.scan_parquet("huge.parquet")
+       .filter(pl.col("status") == "active")
+       .group_by("region").agg(pl.len())
+       .collect(engine="streaming"))
+```
+
+Streaming executes lazy plans only — keep the plan lazy end-to-end, with no intermediate
+`.collect()` breaking it into eager pieces.
+
+## Kernel-less fallback (uv one-shot)
+
+On a harness with no persistent kernel, the same code runs as one-shots — batch several
+questions per process, since each invocation pays spawn plus imports:
+
+```bash
+uv run --with duckdb --with polars --with pyarrow python -c "
+import duckdb
+import polars as pl
+df = duckdb.sql(\"SELECT * FROM 'data.csv'\").pl()
+print(df.group_by('category').agg(pl.len()).sort('category'))
+"
+```

package/packages/shared-skills/skills/data-scientist/references/uv-setup.md

@@ -1,6 +1,6 @@
 # uv Setup — Per-Platform
 
-This skill runs every data operation through `uv run --with ...`. If `uv --version` fails, set uv up with the automated scripts or the manual commands below, then verify.
+This skill's uv lane (kernel-less harnesses, isolated one-shots) runs through `uv run --with ...`, and `scripts/ensure-py-deps.sh` uses uv as its installer. If `uv --version` fails, set uv up with the automated scripts or the manual commands below, then verify.
 
 ## Automated (recommended)
 

package/packages/shared-skills/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/packages/shared-skills/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/packages/shared-skills/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/packages/shared-skills/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/packages/shared-skills/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/packages/shared-skills/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/packages/shared-skills/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/packages/shared-skills/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/packages/shared-skills/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/packages/shared-skills/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/packages/shared-skills/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.