oh-my-opencode 5.0.0-beta.21 → 5.0.0-beta.23

package/packages/omo-codex/plugin/skills/debugging/references/tools/frida.md

@@ -0,0 +1,193 @@
+# Frida — Hook a Live Process and See Real Values at Runtime
+
+**https://frida.re**
+
+Frida injects a JavaScript engine into a running process and lets you intercept function calls, read arguments, patch return values, and trace execution without touching the binary on disk. **When static analysis in Ghidra shows you *what* a function does, Frida shows you what it does *right now*, with real inputs.** The two compose naturally: use Ghidra to find the target function and its offset, then use Frida to hook it and watch live traffic.
+
+Choose Frida over Ghidra when you need runtime values (actual arguments, return codes, heap contents) or when the binary's control flow is too obfuscated for static analysis to resolve.
+
+---
+
+## Install
+
+```bash
+pip install frida-tools            # Python 3 required
+frida --version                    # verify
+```
+
+On macOS, attaching to another user's process needs root (`sudo frida ...`). SIP-protected system binaries (`/usr/bin/*`, `/usr/sbin/*`) are off-limits entirely. On Linux, you may need `ptrace` permissions: run as root or set `kernel.yama.ptrace_scope=0`.
+
+---
+
+## Target discovery with `frida-ps`
+
+```bash
+frida-ps                         # list local processes
+frida-ps -U                      # USB-connected device (iOS/Android)
+frida-ps | grep -i target        # find your target by name
+```
+
+---
+
+## `frida-trace` — zero-code entry point
+
+`frida-trace` auto-generates JavaScript handler stubs for every matched function. You don't write any code to start.
+
+```bash
+frida-trace -p <pid> -i "recv*"                               # trace exported functions by glob
+frida-trace -p <pid> -m "-[NSURLSession dataTaskWithRequest:*]"  # Objective-C method
+frida-trace -U -p <pid> -j "com.example.App!login*"             # Java method (Android)
+frida-trace -f ./target -i "open"                               # spawn + trace from start
+```
+
+Generated handler files land in `__handlers__/`. Each looks like:
+
+```js
+// __handlers__/libSystem.B.dylib/open.js
+{
+  onEnter(log, args, state) {
+    // args[0] is the first argument (a pointer)
+    log(`open("${args[0].readUtf8String()}")`);
+  },
+  onLeave(log, retval, state) {
+    log(`  => ${retval}`);
+  }
+}
+```
+
+Edit that file, save, and `frida-trace` hot-reloads it. This is the fastest path from "I wonder what this function receives" to a concrete answer.
+
+---
+
+## The JS agent API
+
+When `frida-trace` isn't enough, you write a JS agent and load it with `frida` or from a Python host script. These are the building blocks.
+
+### Find a function
+
+```js
+// By exported symbol name
+const openPtr = Module.getExportByName(null, "open");  // null = any module
+const sslWritePtr = Module.getExportByName("libssl.so", "SSL_write");
+
+// By offset in a stripped binary (get the offset from Ghidra)
+const base = Module.getBaseAddress("target");
+const funcPtr = base.add(0x1a3c);
+```
+
+### Intercept calls
+
+```js
+Interceptor.attach(openPtr, {
+  onEnter(args) {
+    // args[0], args[1], ... are NativePointer objects
+    const path = args[0].readUtf8String();
+    const flags = args[1].toInt32();
+    send({ event: "open", path: path, flags: flags });
+  },
+  onLeave(retval) {
+    // retval is the return value as a NativePointer
+    send({ event: "open_ret", fd: retval.toInt32() });
+  }
+});
+```
+
+### Read memory
+
+```js
+args[0].readUtf8String()          // read a UTF-8 C string from a pointer
+args[0].readCString()             // read a raw C string (stops at null)
+args[1].readByteArray(len)        // read len raw bytes (returns ArrayBuffer)
+```
+
+### Replace / stub a function
+
+```js
+// Force a function to always return 0 (e.g. bypass a license check)
+Interceptor.replace(checkLicensePtr, new NativeCallback(function () {
+  return 0;
+}, 'int', []));
+```
+
+Use `Interceptor.replace` sparingly. It changes program behavior, so always note in your journal that you patched something and why.
+
+---
+
+## Python host script
+
+A host script lets you load a JS agent, receive `send()` messages, and post-process results from the Python side.
+
+```python
+import frida, sys
+
+with open("agent.js") as f:
+    agent_source = f.read()
+
+def on_message(message, data):
+    if message["type"] == "send":
+        print(f"[*] {message['payload']}")
+    else:
+        print(f"[!] {message}")
+
+session = frida.attach(int(sys.argv[1]))
+script = session.create_script(agent_source)
+script.on("message", on_message)
+script.load()
+
+try:
+    sys.stdin.read()                 # block until Ctrl+C
+except KeyboardInterrupt:
+    session.detach()
+```
+
+The agent runs inside the target; the host script stays in your terminal and prints structured output.
+
+---
+
+## Output-budget discipline
+
+**Hooking a hot function (e.g. `malloc`, `read`) will flood your context with thousands of lines.** Don't print every call. Aggregate in the agent and report a summary.
+
+```js
+// Count calls, report every 1000
+let callCount = 0;
+Interceptor.attach(mallocPtr, {
+  onEnter(args) {
+    callCount++;
+    if (callCount % 1000 === 0) {
+      send({ event: "malloc_summary", total_calls: callCount });
+    }
+  }
+});
+```
+
+Alternatives: filter by argument value, only log calls from a specific caller module, or batch into an array and `send()` on a timer.
+
+---
+
+## ⚠️ Gotchas
+
+**Attach vs. spawn.** `frida -p <pid>` attaches to an already-running process. If you need to catch early initialization (constructors, `main` entry), spawn the process with `frida -f ./target`. Frida pauses it at startup. Resume with `%resume` in the REPL or by calling `device.resume(pid)` from Python.
+
+**Stripped binaries have no symbol names.** `Module.getExportByName` returns null for internal functions. You must find the function offset in Ghidra, then compute the address at runtime:
+
+```js
+const addr = Module.getBaseAddress("target").add(0x4a20);
+Interceptor.attach(addr, { /* ... */ });
+```
+
+**A crashing target kills your session.** If the target segfaults or aborts, Frida's agent dies with it. Script a respawn loop on the Python side if you expect crashes.
+
+**Thread safety.** `onEnter`/`onLeave` fire on multiple threads. Keep shared state to simple counters.
+
+---
+
+## Cleanup
+
+```bash
+kill <pid>                         # kill any process you spawned with -f
+rm -rf __handlers__/               # remove generated handler stubs
+rm -f agent.js host.py             # remove session-specific scripts
+```
+
+Always note in your journal which processes you attached to and whether you replaced any functions. A forgotten `Interceptor.replace` in a long-running target will cause confusing behavior later.

package/packages/omo-codex/plugin/test/aggregate-model-catalog.test.mjs

@@ -9,7 +9,7 @@ test("#given bundled model catalog #when inspected #then default verifier and wo
 	const catalog = JSON.parse(await readFile(join(root, "model-catalog.json"), "utf8"));
 
 	assert.equal(catalog.current.model, "gpt-5.6-sol");
-	assert.equal(catalog.current.model_context_window, 372000);
+	assert.equal(catalog.current.model_context_window, 650000);
 	assert.equal(catalog.current.model_reasoning_effort, "high");
 	assert.equal(catalog.current.plan_mode_reasoning_effort, "xhigh");
 	assert.deepEqual(catalog.roles.default, catalog.current);

package/packages/omo-codex/plugin/test/auto-update.test.mjs

@@ -279,7 +279,7 @@ test("#given active lock #when running check #then skips concurrent update", asy
 
 	assert.equal(result.started, false);
 	assert.equal(result.reason, "locked");
-	assert.match(await readFile(join(root, "codex-home", "config.toml"), "utf8"), /model_context_window = 372000/);
+	assert.match(await readFile(join(root, "codex-home", "config.toml"), "utf8"), /model_context_window = 650000/);
 });
 
 test("#given stale lock #when running check #then removes lock and runs update", async () => {
@@ -646,7 +646,7 @@ test("#given throttled updater and stale Codex config #when running check #then
 	assert.equal(result.started, false);
 	assert.equal(result.reason, "throttled");
 	assert.match(content, /model = "gpt-5\.6-sol"/);
-	assert.match(content, /model_context_window = 372000/);
+	assert.match(content, /model_context_window = 650000/);
 	assert.match(content, /model_reasoning_effort = "high"/);
 	assert.match(content, /plan_mode_reasoning_effort = "xhigh"/);
 	assert.doesNotMatch(content, /gpt-5\.2/);

package/packages/omo-codex/plugin/test/migrate-codex-config.test.mjs

@@ -55,7 +55,7 @@ test("#given stale root reasoning config #when ensuring config #then replaces st
 	assert.equal(result.match(/^model_reasoning_effort\s*=/gm)?.length, 1);
 	assert.equal(result.match(/^plan_mode_reasoning_effort\s*=/gm)?.length, 1);
 	assert.match(result, /model = "gpt-5\.6-sol"/);
-	assert.match(result, /model_context_window = 372000/);
+	assert.match(result, /model_context_window = 650000/);
 	assert.match(result, /model_reasoning_effort = "high"/);
 	assert.match(result, /plan_mode_reasoning_effort = "xhigh"/);
 	assert.doesNotMatch(result, /gpt-5\.2/);
@@ -80,7 +80,7 @@ test("#given section settings reuse managed root keys #when ensuring config #the
 	);
 
 	assert.match(result, /^model = "gpt-5\.6-sol"$/m);
-	assert.match(result, /^model_context_window = 372000$/m);
+	assert.match(result, /^model_context_window = 650000$/m);
 	assert.match(result, /\[model_providers\.openai\]\nmodel = "provider-scoped-value"\nmodel_context_window = 123456/);
 	assert.match(result, /\[profiles\.review\]\nmodel_reasoning_effort = "medium"\nplan_mode_reasoning_effort = "medium"/);
 });
@@ -162,7 +162,7 @@ test("#given global and project-local stale Codex configs #when migrating #then
 
 	assert.deepEqual(result.changed.sort(), [join(codexHome, "config.toml"), projectConfig].sort());
 	assert.match(await readFile(join(codexHome, "config.toml"), "utf8"), /model = "gpt-5\.6-sol"/);
-	assert.match(await readFile(projectConfig, "utf8"), /model_context_window = 372000/);
+	assert.match(await readFile(projectConfig, "utf8"), /model_context_window = 650000/);
 });
 
 test("#given model catalog is unavailable and stale 272k config #when migrating #then fallback catalog still upgrades it", async () => {
@@ -184,7 +184,7 @@ test("#given model catalog is unavailable and stale 272k config #when migrating
 	const content = await readFile(join(codexHome, "config.toml"), "utf8");
 	assert.deepEqual(result.changed, [join(codexHome, "config.toml")]);
 	assert.match(content, /model = "gpt-5\.6-sol"/);
-	assert.match(content, /model_context_window = 372000/);
+	assert.match(content, /model_context_window = 650000/);
 });
 
 test("#given model catalog is malformed and stale config #when migrating #then fallback catalog still upgrades it", async () => {
@@ -207,7 +207,7 @@ test("#given model catalog is malformed and stale config #when migrating #then f
 	const content = await readFile(join(codexHome, "config.toml"), "utf8");
 	assert.deepEqual(result.changed, [join(codexHome, "config.toml")]);
 	assert.match(content, /model = "gpt-5\.6-sol"/);
-	assert.match(content, /model_context_window = 372000/);
+	assert.match(content, /model_context_window = 650000/);
 });
 
 test("#given user-customized Codex model config #when migrating #then user values are preserved without root multi-agent mode", async () => {
@@ -262,7 +262,7 @@ test("#given managed config state is malformed #when migrating #then migration i
 	const content = await readFile(join(codexHome, "config.toml"), "utf8");
 	const state = JSON.parse(await readFile(statePath, "utf8"));
 	assert.deepEqual(result.changed, [join(codexHome, "config.toml")]);
-	assert.match(content, /model_context_window = 372000/);
+	assert.match(content, /model_context_window = 650000/);
 	assert.equal(state.files[join(codexHome, "config.toml")].managed, true);
 });
 
@@ -671,14 +671,14 @@ test("#given global config starts with inline-comment features table #when full
 	const parsed = parseTomlWithPython(content);
 	assert.equal("multi_agent_mode" in parsed, false);
 	assert.equal(parsed.model, "gpt-5.6-sol");
-	assert.equal(parsed.model_context_window, 372000);
+	assert.equal(parsed.model_context_window, 650000);
 	assert.equal(parsed.model_reasoning_effort, "high");
 	assert.equal(parsed.plan_mode_reasoning_effort, "xhigh");
 	assert.equal(parsed.features.plugins, true);
 	assert.equal("multi_agent_mode" in parsed.features, false);
 	assert.equal("model" in parsed.features, false);
 	assert.equal("model_context_window" in parsed.features, false);
-	assert.match(content, /^model = "gpt-5\.6-sol"\nmodel_context_window = 372000/m);
+	assert.match(content, /^model = "gpt-5\.6-sol"\nmodel_context_window = 650000/m);
 	assert.doesNotMatch(content, /^\s*multi_agent_mode\s*=/m);
 	assert.match(content, /\[features\] # keep comment\nplugins = true/);
 });

package/packages/omo-codex/scripts/install-config-reasoning.test.mjs

@@ -23,7 +23,7 @@ test("#given empty Codex config #when script installer updates config #then sets
 	// then
 	const content = await readFile(configPath, "utf8");
 	assert.match(content, /model = "gpt-5\.6-sol"/);
-	assert.match(content, /model_context_window = 372000/);
+	assert.match(content, /model_context_window = 650000/);
 	assert.match(content, /model_reasoning_effort = "high"/);
 	assert.match(content, /plan_mode_reasoning_effort = "xhigh"/);
 });
@@ -62,7 +62,7 @@ test("#given existing model and reasoning config #when script installer updates
 	assert.equal(content.match(/^model_reasoning_effort\s*=/gm)?.length, 1);
 	assert.equal(content.match(/^plan_mode_reasoning_effort\s*=/gm)?.length, 1);
 	assert.match(content, /model = "gpt-5\.6-sol"/);
-	assert.match(content, /model_context_window = 372000/);
+	assert.match(content, /model_context_window = 650000/);
 	assert.match(content, /model_reasoning_effort = "high"/);
 	assert.match(content, /plan_mode_reasoning_effort = "xhigh"/);
 	assert.doesNotMatch(content, /model = "gpt-5\.2"/);

package/packages/omo-codex/scripts/install-dist/install-local.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-// omo-codex-install:475155d5e39ca774e5cf86194fee97439fd9c4f3624a85e946a994d5493e4629:a81031b3fe18e3977f1f0ad2b0683290efaaaa1a0a05202aecf0b69725c05678
+// omo-codex-install:819e258f7485f9ccdcbb64a54ac0097bf81cd8e2980d7f907017f224b1f99b98:0211b93be64998d1b34d67c74053ea385a23fa560370b8d02016f46f492cfbe3
 var __defProp = Object.defineProperty;
 var __returnValue = (v) => v;
 function __exportSetter(name, newValue) {
@@ -47,9 +47,12 @@ import {
   fsyncSync,
   openSync,
   renameSync,
+  rmSync,
   unlinkSync,
   writeFileSync
 } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { dirname as dirname10 } from "node:path";
 function isToleratedFsyncError(error) {
   if (!(error instanceof Error))
     return false;
@@ -65,24 +68,36 @@ function tolerantFsyncSync(fileDescriptor, fsyncImpl) {
   }
 }
 function writeFileAtomically(filePath, content, options = {}) {
-  const tempPath = `${filePath}.tmp`;
-  writeFileSync(tempPath, content, "utf-8");
-  const tempFileDescriptor = openSync(tempPath, "r+");
-  try {
-    tolerantFsyncSync(tempFileDescriptor, options.fsyncSync ?? fsyncSync);
-  } finally {
-    closeSync(tempFileDescriptor);
-  }
+  const platform = options.platform ?? process.platform;
+  const fsyncImpl = options.fsyncSync ?? fsyncSync;
+  const tempPath = `${filePath}.${process.pid}.${randomUUID()}.tmp`;
   try {
-    renameSync(tempPath, filePath);
-  } catch (error) {
-    const isPermissionError = error instanceof Error && (error.message.includes("EPERM") || error.message.includes("EACCES"));
-    if ((options.platform ?? process.platform) === "win32" && isPermissionError) {
+    writeFileSync(tempPath, content, "utf-8");
+    const tempFileDescriptor = openSync(tempPath, "r+");
+    try {
+      tolerantFsyncSync(tempFileDescriptor, fsyncImpl);
+    } finally {
+      closeSync(tempFileDescriptor);
+    }
+    try {
+      renameSync(tempPath, filePath);
+    } catch (error) {
+      const isPermissionError = error instanceof Error && (error.message.includes("EPERM") || error.message.includes("EACCES"));
+      if (platform !== "win32" || !isPermissionError)
+        throw error;
       unlinkSync(filePath);
       renameSync(tempPath, filePath);
+    }
+    if (platform === "win32")
       return;
+    const directoryFileDescriptor = openSync(dirname10(filePath), "r");
+    try {
+      tolerantFsyncSync(directoryFileDescriptor, fsyncImpl);
+    } finally {
+      closeSync(directoryFileDescriptor);
     }
-    throw error;
+  } finally {
+    rmSync(tempPath, { force: true });
   }
 }
 var TOLERATED_FSYNC_CODES;
@@ -348,7 +363,7 @@ var init_env = __esm(() => {
 });
 
 // node_modules/.bun/posthog-node@5.51.1/node_modules/posthog-node/dist/extensions/error-tracking/modifiers/module.node.mjs
-import { dirname as dirname10, posix as posix2, sep as sep7 } from "node:path";
+import { dirname as dirname11, posix as posix2, sep as sep7 } from "node:path";
 function createModulerModifier() {
   const getModuleFromFileName = createGetModuleFromFilename();
   return async (frames) => {
@@ -357,7 +372,7 @@ function createModulerModifier() {
     return frames;
   };
 }
-function createGetModuleFromFilename(basePath = process.argv[1] ? dirname10(process.argv[1]) : process.cwd(), isWindows = sep7 === "\\") {
+function createGetModuleFromFilename(basePath = process.argv[1] ? dirname11(process.argv[1]) : process.cwd(), isWindows = sep7 === "\\") {
   const normalizedBase = isWindows ? normalizeWindowsPath(basePath) : basePath;
   return (filename) => {
     if (!filename)
@@ -7962,7 +7977,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "@oh-my-opencode/omo-codex",
-    version: "5.0.0-beta.21",
+    version: "5.0.0-beta.23",
     type: "module",
     private: true,
     description: "Codex harness adapter for oh-my-openagent. Vendored Codex plugin namespace (omo) + TypeScript installer + telemetry.",
@@ -8182,7 +8197,7 @@ var init_telemetry = __esm(() => {
 
 // packages/omo-codex/src/install/install-local-cli.ts
 import { readFile as readFile23 } from "node:fs/promises";
-import { dirname as dirname12, join as join40, resolve as resolve10 } from "node:path";
+import { dirname as dirname13, join as join40, resolve as resolve10 } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 
 // packages/utils/src/runtime/spawn.ts
@@ -11029,14 +11044,14 @@ import { join as join17 } from "node:path";
 var FALLBACK_CODEX_MODEL_CATALOG = {
   current: {
     model: "gpt-5.6-sol",
-    modelContextWindow: 372000,
+    modelContextWindow: 650000,
     modelReasoningEffort: "high",
     planModeReasoningEffort: "xhigh"
   },
   managedProfiles: [
     {
       model: "gpt-5.5",
-      modelContextWindow: 400000,
+      modelContextWindow: 650000,
       modelReasoningEffort: "high",
       planModeReasoningEffort: "xhigh"
     },
@@ -13540,7 +13555,7 @@ function shellQuote(value) {
 // packages/omo-codex/src/install/lazycodex-manual-update.ts
 import { spawn as spawn3, spawnSync as spawnSync3 } from "node:child_process";
 import { readFileSync as readFileSync4 } from "node:fs";
-import { dirname as dirname11, join as join38 } from "node:path";
+import { dirname as dirname12, join as join38 } from "node:path";
 import { createInterface as createInterface2 } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
 
@@ -13649,7 +13664,7 @@ function resolveArgs(env2) {
 function resolveCurrentVersion(env2) {
   if (env2.LAZYCODEX_CURRENT_VERSION?.trim())
     return env2.LAZYCODEX_CURRENT_VERSION.trim();
-  const pluginRoot = dirname11(dirname11(fileURLToPath(import.meta.url)));
+  const pluginRoot = dirname12(dirname12(fileURLToPath(import.meta.url)));
   return readVersionManifest(resolveInstalledVersionPath(env2, pluginRoot)) ?? readVersionManifest(join38(pluginRoot, "..", "..", "..", "package.json")) ?? readVersionManifest(join38(pluginRoot, ".codex-plugin", "plugin.json"));
 }
 function resolveLatestVersion(env2) {
@@ -13829,7 +13844,7 @@ async function installMarketplaceLocally(options = {}) {
   return runCodexInstaller(options);
 }
 function resolveDefaultRepoRootForEntrypoint(entrypointPath) {
-  return resolve10(dirname12(entrypointPath), "..", "..", "..");
+  return resolve10(dirname13(entrypointPath), "..", "..", "..");
 }
 function resolveDefaultRepoRoot() {
   return resolveDefaultRepoRootForEntrypoint(fileURLToPath2(import.meta.url));

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()`.