wowdump 0.3.9 → 0.3.11

package/README.md

@@ -1,6 +1,6 @@
 # wowdump
 
-Windows 下的 WoW 原生内存分析 CLI。用 CDB 运行时证据和 IDA Pro MCP / iced-x86 分析字段，生成 Reader 可读取的 build profile。
+Windows 下的 WoW 原生内存分析 CLI。原生内存引擎负责读取、页查询和段导出；IDA Pro MCP 优先，iced-x86 提供无需额外工具的局部 64 位反汇编。最终生成按 build 保存的 profile。
 
 ## 安装与更新
 
@@ -10,7 +10,7 @@ wowdump init
 wowdump --version
 ```
 
-安装会初始化 `~/.wowdump`，把包内完整 Skill 安装到 `~/.agents/skills/wowdump`。升级或 init 会同步 Skill，差异文件先备份到 `~/.wowdump/skill-backups/`；个人新增文件和 config.json 保留。iced-x86 随 npm 安装，CDB 从本机探测，不自动下载或修改环境变量。
+安装会初始化 `~/.wowdump`，把包内完整 Skill 安装到 `~/.agents/skills/wowdump`。升级或 init 会同步 Skill，差异文件先备份到 `~/.wowdump/skill-backups/`；个人新增文件和 config.json 保留。iced-x86 随 npm 安装，无需安装调试器或 CE。
 
 ## 使用流程
 
@@ -33,9 +33,9 @@ wowdump memory read --pid <pid> --build "<buildKey>" --profile "<character-stats
 wowdump memory regions --pid <pid> --start <startAddress> --end <endAddress> --max-regions 20000
 ```
 
-尖括号是待替换参数。已有匹配且适用的 profile 时直接 Reader 读取，无需重新 dump。CDB 诊断与断点不是必经步骤，执行前先查 Skill 的退出和超时限制。
+尖括号是待替换参数。已有匹配且适用的 profile 时直接 内存引擎 读取，无需重新 dump。不再提供实时调试、断点或任意调试命令。
 
-内存和 CDB 请求复用同一个管理员 broker：首次请求 UAC，空闲 20 分钟退出。所有调试请求需要 `--confirm`。
+内存读取与导出复用同一个管理员 broker：首次请求 UAC，空闲 20 分钟退出。运行时证据采集需要 `--confirm`。
 
 ## 数据放在哪里
 
@@ -44,18 +44,20 @@ wowdump memory regions --pid <pid> --start <startAddress> --end <endAddress> --m
 - `build.json`：目标身份。
 - `database/`：静态分析数据库位置和状态，不因任务重复创建。
 - `runtime/<session>/`：本轮证据、dump 和候选。
-- `profile/`：用户确认的 Reader 接口。
+- `profile/`：用户确认的 内存引擎 接口。
 
-Dump 默认导出 `.text/.rdata/.pdata`，`.data` 按需加入。Reader 默认选择当前 build 的 profile，也支持显式路径；它不读取 IDA 数据库或 dump 二进制。
+Dump 默认导出 `.text/.rdata/.pdata`，`.data` 按需加入。内存引擎 默认选择当前 build 的 profile，也支持显式路径；它不读取 IDA 数据库或 dump 二进制。
 
 ## 0.3.9 的读取与验证
 
+0.3.10 另修复请求超时计时器提前释放活动引用的问题，确保没有其他活动句柄时仍返回 REQUEST_TIMEOUT；broker 空闲退出策略不变。
+
 - verify 接受 candidate 或 reader_ready；普通 memory read 要求 reader_ready。
 - 输出 `validation.read: "passed"`，替代旧版 `verified:true`；fieldSemantics、rootSemantics、crossProcess 为 not_checked，需要独立证据。命令不自动认证语义、提升状态或保存 profile。
-- 新增 `root.lookup`：按动态键选择有界表项，核对对象键并检查读取期间变化，避免固化本轮哈希槽位。含 lookup 的 profile 需要 0.3.9 或更新版本；旧 Reader 可能忽略未知参数。
+- 新增 `root.lookup`：按动态键选择有界表项，核对对象键并检查读取期间变化，避免固化本轮哈希槽位。含 lookup 的 profile 需要 0.3.9 或更新版本；旧 内存引擎 可能忽略未知参数。
 - 校验目标 build 时，缺少 executableSha256 会报错。模块外根 RVA、空根、短读和不一致查表结果均返回结构化错误。
 
-详细用法由安装的 Skill 按需加载：[命令](skills/wowdump/references/commands.md)、[Profile 格式](skills/wowdump/references/profiles.md)、[字段挖掘方法与成功案例](skills/wowdump/references/character-stats-case.md)、[CDB 限制](skills/wowdump/references/windbg.md)。
+详细用法由安装的 Skill 按需加载：[命令](skills/wowdump/references/commands.md)、[Profile 格式](skills/wowdump/references/profiles.md)、[字段挖掘方法与成功案例](skills/wowdump/references/character-stats-case.md)、[内存引擎](skills/wowdump/references/memory.md)。
 
 ## 开发验证
 
@@ -66,3 +68,23 @@ npm test
 npm run package:verify
 npm run release:verify
 ```
+
+## 原生导出与离线分析
+
+`analyze runtime --kind dump` 使用 Windows API 分块写入 `.bin`，manifest v4 保留 RVA、读取缺口和哈希。每次创建新 session，超过限额报错；缺页不伪装成完整读取。`progress.json` 提供进度。运行时导出不是原子快照。
+
+```text
+wowdump analyze disassemble --file <section.bin> --rva <startRva> --offset <fileOffset> --size 4096 --max-instructions 256
+```
+
+该命令仅局部解码，不替代 IDA 的反编译与交叉引用。IDA 不可用时由 Agent 基于指令和内存证据分析。
+
+## 模块与命名
+
+- `src/memory/`：Memory Engine，Windows 内存访问、broker、导出与生命周期。
+- `src/analysis/`：PE 解析与 iced-x86 离线反汇编。
+- `src/core/profile-engine.ts`：profile 身份校验、RVA/指针链与字段解析。
+- `src/adapters/memory.ts`：profile 引擎到 broker 的适配。
+- `src/memory-main.ts`：管理员 broker 入口；不再发布旧 reader 入口。
+
+开发测试的自定义入口变量为 `WOWDUMP_MEMORY_COMMAND`，测试后端变量为 `WOWDUMP_USE_FAKE_MEMORY`。旧变量不再使用。升级后首次原生请求会认证关闭旧版 broker，然后启动新引擎；profile v1 的 `readerStatus` / `reader_ready` 保持兼容。

package/dist/adapters/{reader.js → memory.js}

@@ -1,8 +1,8 @@
 function record(value) {
     return value && typeof value === "object" && !Array.isArray(value) ? value : {};
 }
-/** Adapts the elevated reader broker to ProfileEngine's minimal memory API. */
-export class ReaderProfileAdapter {
+/** Adapts the elevated memory broker to ProfileEngine's minimal memory API. */
+export class MemoryProfileAdapter {
     invoke;
     constructor(invoke) {
         this.invoke = invoke;

package/dist/analysis/disassemble.js

@@ -0,0 +1,45 @@
+import { open } from "node:fs/promises";
+import { resolve } from "node:path";
+import { Decoder, DecoderOptions, Formatter, FormatterSyntax } from "iced-x86";
+export async function disassembleFile(input) {
+    if (!/^0x[0-9a-f]+$/i.test(input.rva) || BigInt(input.rva) > 0xffffffffn ||
+        !Number.isSafeInteger(input.offset) || input.offset < 0 || !Number.isSafeInteger(input.size) || input.size < 1 || input.size > 1024 * 1024 ||
+        !Number.isSafeInteger(input.maxInstructions) || input.maxInstructions < 1 || input.maxInstructions > 10000) {
+        throw Object.assign(new Error("invalid bounded disassembly range"), { code: "DISASSEMBLY_ARGUMENT_INVALID" });
+    }
+    const file = await open(resolve(input.file), "r");
+    let bytes;
+    try {
+        const buffer = Buffer.alloc(input.size);
+        const result = await file.read(buffer, 0, input.size, input.offset);
+        bytes = buffer.subarray(0, result.bytesRead);
+    }
+    finally {
+        await file.close();
+    }
+    if (!bytes.length)
+        throw Object.assign(new Error("no bytes in selected range"), { code: "DISASSEMBLY_EMPTY" });
+    const decoder = new Decoder(64, bytes, DecoderOptions.None);
+    decoder.ip = BigInt(input.rva);
+    const formatter = new Formatter(FormatterSyntax.Intel);
+    const instructions = [];
+    let decodedBytes = 0;
+    try {
+        while (decoder.canDecode && instructions.length < input.maxInstructions) {
+            const instruction = decoder.decode();
+            decodedBytes += instruction.length;
+            try {
+                instructions.push({ rva: `0x${instruction.ip.toString(16)}`, length: instruction.length, text: formatter.format(instruction), invalid: instruction.isInvalid,
+                    ...(instruction.isIpRelMemoryOperand ? { memoryRva: `0x${instruction.ipRelMemoryAddress.toString(16)}` } : {}) });
+            }
+            finally {
+                instruction.free();
+            }
+        }
+        return { ok: true, command: "analyze.disassemble", engine: "iced-x86", bitness: 64, file: resolve(input.file), offset: input.offset, rva: input.rva, bytesRead: bytes.length, decodedBytes, sourceShortRead: bytes.length < input.size, truncated: decoder.canDecode, instructions };
+    }
+    finally {
+        decoder.free();
+        formatter.free();
+    }
+}

package/dist/analysis/pe.js

@@ -0,0 +1,49 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+class PeError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+function hex(value) { return `0x${value.toString(16)}`; }
+function readU16(buffer, offset) { return buffer.readUInt16LE(offset); }
+function readU32(buffer, offset) { return buffer.readUInt32LE(offset); }
+export async function readPeLayout(file) {
+    const input = resolve(file);
+    const buffer = await readFile(input);
+    if (buffer.length < 0x100 || buffer.toString("ascii", 0, 2) !== "MZ")
+        throw new PeError("PE_INVALID", "Wow.exe has no DOS header");
+    const peOffset = readU32(buffer, 0x3c);
+    if (peOffset + 24 > buffer.length || buffer.toString("ascii", peOffset, peOffset + 4) !== "PE\0\0")
+        throw new PeError("PE_INVALID", "Wow.exe has no PE header");
+    const sections = readU16(buffer, peOffset + 6);
+    const optionalSize = readU16(buffer, peOffset + 20);
+    const optional = peOffset + 24;
+    if (optionalSize < 64 || optional + optionalSize > buffer.length)
+        throw new PeError("PE_INVALID", "truncated optional header");
+    const magic = readU16(buffer, optional);
+    if (![0x20b, 0x10b].includes(magic))
+        throw new PeError("PE_INVALID", "unsupported PE format");
+    const imageBase = magic === 0x20b ? buffer.readBigUInt64LE(optional + 24) : BigInt(readU32(buffer, optional + 28));
+    const sizeOfImage = readU32(buffer, optional + 56);
+    const table = optional + optionalSize;
+    if (sections > 96 || table + sections * 40 > buffer.length)
+        throw new PeError("PE_INVALID", "truncated section table");
+    const values = [];
+    for (let index = 0; index < sections; index += 1) {
+        const offset = table + index * 40;
+        if (offset + 40 > buffer.length)
+            break;
+        const name = buffer.subarray(offset, offset + 8).toString("ascii").replace(/\0+$/u, "");
+        const virtualSize = readU32(buffer, offset + 8);
+        const rva = readU32(buffer, offset + 12);
+        const rawSize = readU32(buffer, offset + 16);
+        const characteristics = readU32(buffer, offset + 36);
+        const protection = `${characteristics & 0x40000000 ? "r" : ""}${characteristics & 0x80000000 ? "w" : ""}${characteristics & 0x20000000 ? "x" : ""}`;
+        if (name && (virtualSize || rawSize))
+            values.push({ name, rva: hex(BigInt(rva)), virtualSize, rawSize, characteristics: hex(BigInt(characteristics)), protection });
+    }
+    return { imageBase: hex(imageBase), moduleSize: sizeOfImage, sections: values };
+}

package/dist/cli.js

@@ -1,4 +1,5 @@
 #!/usr/bin/env node
+import { disassembleFile } from "./analysis/disassemble.js";
 import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { existsSync, realpathSync, readFileSync } from "node:fs";
@@ -6,13 +7,12 @@ import { mkdir, open, readFile, readdir, writeFile } from "node:fs/promises";
 import { basename, dirname, extname, isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { Command } from "commander";
-import { WindowsBrokerManager } from "./reader/launcher.js";
+import { WindowsBrokerManager } from "./memory/launcher.js";
 import { initializeWowdumpHome, bootstrapToolchain, resolveToolchain } from "./toolchain.js";
-import { buildPaths, databaseStatus, ensureBuild, findReusableDump, readBuild, resolveWowdumpHome, safeBuildKey, sha256File } from "./core/build-store.js";
-import { readPeLayout } from "./debug/cdb.js";
+import { buildPaths, databaseStatus, ensureBuild, readBuild, resolveWowdumpHome, safeBuildKey, sha256File } from "./core/build-store.js";
 import { ProfileEngine } from "./core/profile-engine.js";
-import { ReaderProfileAdapter } from "./adapters/reader.js";
-import { enumerateWindowsProcesses } from "./reader/windows.js";
+import { MemoryProfileAdapter } from "./adapters/memory.js";
+import { enumerateWindowsProcesses } from "./memory/windows.js";
 export function parseBuildInfo(content, file) {
     const lines = content.split(/\r?\n/).filter(line => line.trim());
     const headers = lines[0]?.split("|") ?? [];
@@ -51,7 +51,7 @@ async function discoverWowTargets(selectedPid, elevatedModules) {
                 const modules = response && typeof response === "object" && Array.isArray(response.modules)
                     ? response.modules
                     : [];
-                const main = modules.find(module => /^Wow\.exe$/i.test(String(module.name ?? ""))) ?? modules[0];
+                const main = modules.find(module => /^Wow\.exe$/i.test(String(module.name ?? "")));
                 if (!path && typeof main?.path === "string" && main.path)
                     path = main.path;
                 if (!moduleBase && typeof main?.base === "string")
@@ -199,16 +199,16 @@ function writeJson(io, value) {
     io.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
 }
 function brokerCommandLine(env, packageDist) {
-    const configured = env.WOWDUMP_READER_COMMAND?.trim();
+    const configured = env.WOWDUMP_MEMORY_COMMAND?.trim();
     if (configured)
         return { file: configured, args: [] };
-    const candidate = join(packageDist, "reader-main.js");
+    const candidate = join(packageDist, "memory-main.js");
     return existsSync(candidate) ? { file: process.execPath, args: [candidate, "--request-stdio"] } : null;
 }
 async function defaultBroker(invocation, env, packageDist) {
     const command = brokerCommandLine(env, packageDist);
     if (!command) {
-        throw new CliError("BROKER_NOT_CONFIGURED", "reader broker entry was not found", { expected: join(packageDist, "reader-main.js"), environment: "WOWDUMP_READER_COMMAND" });
+        throw new CliError("BROKER_NOT_CONFIGURED", "memory broker entry was not found", { expected: join(packageDist, "memory-main.js"), environment: "WOWDUMP_MEMORY_COMMAND" });
     }
     const result = await new Promise(resolveResult => {
         const child = spawn(command.file, command.args, { shell: false, windowsHide: true, stdio: ["pipe", "pipe", "pipe"] });
@@ -223,15 +223,15 @@ async function defaultBroker(invocation, env, packageDist) {
         child.stdin?.end(`${JSON.stringify(invocation)}\n`);
     });
     if (result.exitCode !== 0)
-        throw new CliError("BROKER_FAILED", result.stderr.trim() || `reader broker exited with ${result.exitCode}`);
+        throw new CliError("BROKER_FAILED", result.stderr.trim() || `memory broker exited with ${result.exitCode}`);
     const line = result.stdout.split(/\r?\n/).find(value => value.trim());
     if (!line)
-        throw new CliError("BROKER_PROTOCOL_ERROR", "reader broker returned no JSON response");
+        throw new CliError("BROKER_PROTOCOL_ERROR", "memory broker returned no JSON response");
     try {
         return JSON.parse(line);
     }
     catch {
-        throw new CliError("BROKER_PROTOCOL_ERROR", "reader broker returned invalid JSON", { stdout: result.stdout });
+        throw new CliError("BROKER_PROTOCOL_ERROR", "memory broker returned invalid JSON", { stdout: result.stdout });
     }
 }
 const windowsBrokerManagers = new Map();
@@ -239,7 +239,7 @@ function persistentWindowsBroker(home, packageDist) {
     const key = resolve(home).toLowerCase();
     let manager = windowsBrokerManagers.get(key);
     if (!manager) {
-        manager = new WindowsBrokerManager({ home, readerEntry: join(packageDist, "reader-main.js") });
+        manager = new WindowsBrokerManager({ home, memoryEntry: join(packageDist, "memory-main.js") });
         windowsBrokerManagers.set(key, manager);
     }
     return manager;
@@ -285,7 +285,7 @@ function selected(source, keys) {
 function requireRuntimeConfirmation(options) {
     if (options.confirm === true)
         return;
-    throw new CliError("CONFIRMATION_REQUIRED", "debug analysis requires --confirm", {
+    throw new CliError("CONFIRMATION_REQUIRED", "runtime evidence collection requires --confirm", {
         pid: options.pid,
         buildKey: options.build,
         operation: "runtime",
@@ -337,7 +337,7 @@ export function createWowdumpCli(dependencies = {}) {
         ? (invocation => persistentWindowsBroker(home, packageDist).request(invocation))
         : (invocation => defaultBroker(invocation, env, packageDist)));
     const profileEngine = new ProfileEngine();
-    const profileAdapter = new ReaderProfileAdapter(broker);
+    const profileAdapter = new MemoryProfileAdapter(broker);
     const program = new Command()
         .name("wowdump")
         .description("Build-aware WoW native memory analysis CLI")
@@ -369,7 +369,7 @@ export function createWowdumpCli(dependencies = {}) {
         writeJson(io, { ...await databaseStatus(home, options.build), command: "database.status" });
     });
     program.command("target")
-        .description("Show target, reader broker, profile, monitor, and debugger state")
+        .description("Show target, memory broker, profile and monitor state")
         .option("--pid <pid>", "target process ID")
         .option("--build <buildKey>", "expected build key")
         .action(async (options) => {
@@ -499,22 +499,21 @@ export function createWowdumpCli(dependencies = {}) {
         .description("Stop a monitor and release its resources")
         .requiredOption("--id <watchId>", "monitor ID")
         .action(async (options) => writeJson(io, await broker({ command: "watch.stop", payload: { watchId: options.id } })));
-    const analyze = program.command("analyze").description("Run bounded WinDbg/CDB evidence operations");
+    const analyze = program.command("analyze").description("Collect memory evidence and disassemble local code");
     analyze.command("runtime")
-        .description("Dump PE sections with CDB or verify a profile through the reader broker")
+        .description("Dump PE sections using native memory reads or verify a profile")
         .requiredOption("--pid <pid>", "target process ID")
         .requiredOption("--build <buildKey>", "build key")
         .option("--build-key <buildKey>", "alias for --build")
         .option("--kind <kind>", "dump or verify", "dump")
-        .option("--profile <path>", "reader profile containing candidate RVAs (verify only)")
+        .option("--profile <path>", "memory profile containing candidate RVAs (verify only)")
         .option("--output-dir <path>", "directory for dump manifest and section binaries")
         .option("--sections <names...>", "sections to dump (default: .text .rdata .pdata)")
         .option("--max-section-bytes <bytes>", "per-section dump limit", "134217728")
         .option("--max-total-bytes <bytes>", "total dump limit", "268435456")
-        .option("--duration-ms <ms>", "CDB timeout", "30000")
-        .option("--cdb-args <json>", "JSON array of extra CDB arguments", "[]")
-        .option("--cdb-commands <json>", "JSON array of extra CDB commands", "[]")
-        .option("--confirm", "confirm the bounded debugger operation")
+        .option("--duration-ms <ms>", "native dump deadline", "30000")
+        .option("--chunk-bytes <bytes>", "native read block size (maximum 1 MiB)", "65536")
+        .option("--confirm", "confirm the bounded memory operation")
         .action(async (options) => {
         const normalized = {
             pid: positiveInteger(options.pid, "pid"),
@@ -544,96 +543,36 @@ export function createWowdumpCli(dependencies = {}) {
         const requestedSections = Array.isArray(options.sections) && options.sections.length > 0
             ? options.sections.map((value) => String(value).toLowerCase())
             : [".text", ".rdata", ".pdata"];
-        const cdbArgs = JSON.parse(options.cdbArgs);
-        const cdbCommands = JSON.parse(options.cdbCommands);
-        if (!Array.isArray(cdbArgs) || !Array.isArray(cdbCommands))
-            throw new CliError("ARGUMENT_INVALID", "cdb-args and cdb-commands must be JSON arrays");
-        const reusable = requestedSections.includes(".data")
-            ? null
-            : await findReusableDump(home, normalized.build, { executableSha256: buildRecord.executableSha256, sections: requestedSections, maxSectionBytes: normalized.maxSectionBytes, maxTotalBytes: normalized.maxTotalBytes, cdbArgs, commands: cdbCommands });
-        if (reusable) {
-            writeJson(io, { ok: true, command: "analyze.runtime.dump", reused: true, manifestFile: String(reusable.manifestFile ?? ""), manifest: reusable });
-            return;
-        }
         const moduleResponse = await broker({ command: "modules", payload: { pid: normalized.pid } });
         const modules = moduleResponse && typeof moduleResponse === "object" && Array.isArray(moduleResponse.modules) ? moduleResponse.modules : [];
-        const module = modules.find(item => /^Wow\.exe$/i.test(String(item.name ?? ""))) ?? modules[0];
+        const module = modules.find(item => /^Wow\.exe$/i.test(String(item.name ?? "")));
         if (!module || typeof module.base !== "string")
             throw new CliError("MODULE_NOT_FOUND", "Wow.exe module was not found", { modules });
-        const moduleBase = module.base;
-        const layout = await readPeLayout(buildRecord.executablePath);
         const sessionId = randomUUID();
         const sessionDirectory = join(buildPaths(home, normalized.build).runtime, sessionId);
         const outputDirectory = resolve(options.outputDir ?? join(sessionDirectory, "dump"));
         await mkdir(sessionDirectory, { recursive: true });
         await writeFile(join(sessionDirectory, "target.json"), `${JSON.stringify({ schema: "wowdump.runtime-target.v2", pid: normalized.pid, buildKey: normalized.build, executableSha256: buildRecord.executableSha256, sessionId, createdAt: new Date().toISOString() }, null, 2)}\n`, "utf8");
-        let total = 0;
-        const selectedSections = requestedSections.flatMap((name) => layout.sections.find((section) => section.name.toLowerCase() === name) ?? []);
-        const sections = selectedSections.map((section) => {
-            const requested = Math.min(Math.max(section.virtualSize, section.rawSize), normalized.maxSectionBytes, Math.max(0, normalized.maxTotalBytes - total));
-            total += requested;
-            return { ...section, runtimeAddress: `0x${(BigInt(moduleBase) + BigInt(section.rva)).toString(16)}`, readSize: requested, file: join(outputDirectory, `${section.name}.bin`) };
-        });
-        if (sections.length === 0)
-            throw new CliError("SECTION_NOT_FOUND", "no requested PE sections were found", { requestedSections, available: layout.sections.map(section => section.name) });
-        const raw = await broker({ command: "debug", payload: {
-                kind: "dump", pid: normalized.pid, buildKey: normalized.build, executablePath: buildRecord.executablePath,
-                executableSha256: buildRecord.executableSha256, moduleBase, preferredImageBase: buildRecord.preferredImageBase,
-                moduleSize: Number(module.size ?? buildRecord.moduleSize ?? layout.moduleSize), outputDir: outputDirectory, sections,
-                maxSectionBytes: normalized.maxSectionBytes, maxTotalBytes: normalized.maxTotalBytes, timeoutMs: normalized.durationMs,
-                cdbArgs, commands: cdbCommands
+        const raw = await broker({ command: "dump", payload: {
+                pid: normalized.pid, buildKey: normalized.build,
+                executableSha256: buildRecord.executableSha256, outputDir: outputDirectory, sections: requestedSections,
+                maxSectionBytes: normalized.maxSectionBytes, maxTotalBytes: normalized.maxTotalBytes, timeoutMs: normalized.durationMs, chunkBytes: positiveInteger(options.chunkBytes, "chunk-bytes")
             } });
         const value = raw && typeof raw === "object" ? raw : {};
         if (value.ok !== true)
-            throw new CliError(String(value.error?.code ?? "CDB_FAILED"), String(value.error?.message ?? "CDB dump failed"), value.error);
+            throw new CliError(String(value.error?.code ?? "DUMP_FAILED"), String(value.error?.message ?? "native dump failed"), value);
         writeJson(io, { ...value, command: "analyze.runtime.dump", sessionDirectory });
     });
-    analyze.command("debug")
-        .description("Run a bounded WinDbg/CDB command, breakpoint, or diagnostic session")
-        .requiredOption("--pid <pid>", "target process ID")
-        .requiredOption("--build <buildKey>", "build key")
-        .option("--kind <kind>", "breakpoint or command", "breakpoint")
-        .option("--rva <rva>", "single statically-confirmed RVA")
-        .option("--max-hits <count>", "breakpoint hit limit", "3")
-        .option("--duration-ms <ms>", "CDB timeout", "3000")
-        .option("--cdb-args <json>", "JSON array of extra CDB arguments", "[]")
-        .option("--cdb-commands <json>", "JSON array of explicit CDB commands", "[]")
-        .option("--output <path>", "debug evidence JSON path")
-        .option("--confirm", "confirm the bounded debugger operation")
-        .action(async (options) => {
-        const pid = positiveInteger(options.pid, "pid");
-        const build = String(options.build);
-        const durationMs = positiveInteger(options.durationMs, "duration-ms");
-        const kind = String(options.kind);
-        if (!["breakpoint", "command"].includes(kind))
-            throw new CliError("ARGUMENT_INVALID", "kind must be breakpoint or command");
-        requireRuntimeConfirmation({ pid, build, kind, durationMs, maxHits: options.maxHits, confirm: options.confirm === true });
-        const buildRecord = await readBuild(home, build);
-        if (!buildRecord)
-            throw new CliError("BUILD_NOT_FOUND", `build ${build} has not been discovered`);
-        const moduleResponse = await broker({ command: "modules", payload: { pid } });
-        const modules = moduleResponse && typeof moduleResponse === "object" && Array.isArray(moduleResponse.modules) ? moduleResponse.modules : [];
-        const module = modules.find(item => /^Wow\.exe$/i.test(String(item.name ?? ""))) ?? modules[0];
-        if (!module || typeof module.base !== "string")
-            throw new CliError("MODULE_NOT_FOUND", "Wow.exe module was not found");
-        const sessionDirectory = join(buildPaths(home, build).runtime, randomUUID());
-        await mkdir(sessionDirectory, { recursive: true });
-        const output = resolve(options.output ?? join(sessionDirectory, "debug.json"));
-        const parsedArgs = JSON.parse(options.cdbArgs);
-        const parsedCommands = JSON.parse(options.cdbCommands);
-        if (!Array.isArray(parsedArgs) || !Array.isArray(parsedCommands))
-            throw new CliError("ARGUMENT_INVALID", "cdb-args and cdb-commands must be JSON arrays");
-        const payload = kind === "command"
-            ? { kind, pid, buildKey: build, durationMs, outputFile: output, cdbArgs: parsedArgs, commands: parsedCommands }
-            : { kind: "breakpoint", pid, buildKey: build, rva: options.rva, moduleBase: module.base, maxHits: positiveInteger(options.maxHits, "max-hits"), durationMs, outputFile: output, cdbArgs: parsedArgs, commands: parsedCommands };
-        if (kind !== "command" && !options.rva)
-            throw new CliError("RVA_REQUIRED", "breakpoint requires --rva");
-        const raw = await broker({ command: "debug", payload });
-        const value = raw && typeof raw === "object" ? raw : {};
-        if (value.ok !== true)
-            throw new CliError(String(value.error?.code ?? "CDB_FAILED"), String(value.error?.message ?? "CDB debug failed"), value.error);
-        writeJson(io, { ...value, command: "analyze.debug", sessionDirectory });
-    });
+    analyze.command("disassemble")
+        .description("Decode a bounded local binary range with iced-x86 (64-bit)")
+        .requiredOption("--file <path>", "raw section binary")
+        .requiredOption("--rva <hex>", "RVA of the first decoded byte")
+        .option("--offset <bytes>", "file offset", "0")
+        .option("--size <bytes>", "maximum bytes", "4096")
+        .option("--max-instructions <count>", "instruction limit", "256")
+        .action(async (options) => writeJson(io, await disassembleFile({ file: options.file, rva: options.rva,
+        offset: nonNegativeInteger(options.offset, "offset"), size: positiveInteger(options.size, "size"),
+        maxInstructions: positiveInteger(options.maxInstructions, "max-instructions") })));
     program.command("init")
         .description("Initialize WOWDUMP_HOME without overwriting existing files")
         .option("--skip-toolchain-download", "kept for compatibility; no external toolchain is installed")

package/dist/core/build-store.js

@@ -1,6 +1,6 @@
 import { createHash } from "node:crypto";
 import { createReadStream } from "node:fs";
-import { mkdir, open, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
+import { mkdir, open, readFile, rm, stat, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join, normalize, resolve } from "node:path";
 export function resolveWowdumpHome(env = process.env, userHome = homedir()) {
@@ -144,23 +144,3 @@ export async function databaseStatus(home, buildKey) {
     }
     return { ok: true, buildKey: safeBuildKey(buildKey), buildDirectory: paths.build, databasePath: paths.databaseFile, exists: Boolean(database), locked: lock, build, database };
 }
-export async function findReusableDump(home, buildKey, criteria) {
-    const runtime = buildPaths(home, buildKey).runtime;
-    let sessions;
-    try {
-        sessions = await readdir(runtime, { withFileTypes: true });
-    }
-    catch (error) {
-        if (error.code === "ENOENT")
-            return null;
-        throw error;
-    }
-    for (const session of sessions.filter(item => item.isDirectory())) {
-        const manifestFile = join(runtime, session.name, "dump", "manifest.json");
-        const manifest = await readJson(manifestFile);
-        if (!manifest || typeof manifest.moduleBase !== "string" || JSON.stringify(manifest.dumpParameters ?? null) !== JSON.stringify(criteria))
-            continue;
-        return { ...manifest, manifestFile };
-    }
-    return null;
-}