@eyeauras/insight-cli 0.2.0 → 0.2.1

package/dist/src/tshark.js

@@ -0,0 +1,174 @@
+import { command, Permission } from '@eyeauras/cli-factory';
+import { join, resolve, dirname, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readFile, mkdir, copyFile, lstat, open, writeFile } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { ToolInstaller } from './tool-runtime/installer.js';
+import { defineTool, lifecycleCommands } from './tool-runtime/definition.js';
+import { catalogArtifact } from './tool-runtime/catalog.js';
+import { fileSha256, archiveName } from './tool-runtime/archives.js';
+import { runTool } from './tool-runtime/run.js';
+import { digest, fail, id, text } from './model.js';
+import { number } from './research.js';
+const archive = '90a4f106033c74eef38f52985fc168c99a293ae35c9d3d7d1b157558a94d5261', relativeExecutable = 'Wireshark.app/Contents/MacOS/tshark';
+const layout = JSON.parse(await readFile(fileURLToPath(new URL('../../runtime/native/tshark-layout.json', import.meta.url)), 'utf8'));
+function supported() { if (process.platform !== 'darwin' || process.arch !== 'arm64')
+    fail('unsupported', 'TShark currently requires native macOS ARM64, macOS 14+ for the owned deadline launcher. Offline PCAP analysis requires no live-capture privileges.'); }
+function externalRoot(executable) { if (basename(executable) !== 'tshark' || basename(dirname(executable)) !== 'MacOS' || basename(resolve(dirname(executable), '../..')) !== 'Wireshark.app')
+    fail('configuration', 'Select the pinned Wireshark.app/Contents/MacOS/tshark or our extracted console runtime.'); return resolve(dirname(executable), '../../..'); }
+async function verifyFamily(executable) { supported(); const root = externalRoot(executable); for (const entry of layout.entries) {
+    archiveName(entry.path);
+    const path = join(root, entry.path), info = await lstat(path);
+    if (!info.isFile() || info.size !== entry.size || await fileSha256(path) !== entry.sha256)
+        fail('binding', 'TShark runtime family differs from the pinned 4.6.9 console subset.', { component: entry.path });
+} return { runtimeFamily: digest(layout.entries) }; }
+const safeArguments = ['-n', '-o', 'capture.no_extcap:TRUE', '-o', 'nameres.maxmind_geoip:FALSE'];
+export function tsharkInstaller(c) { return new ToolInstaller(c, { id: 'tshark', primary: 'tshark', preparationId: 'console-subset-v1', components: () => { supported(); return { tshark: catalogArtifact(archive) }; }, launch: roots => ({ executable: join(roots.tshark, relativeExecutable), arguments: [], environment: {} }), externalInputs: verifyFamily, prepareExternal: async (executable, stage) => { const root = externalRoot(executable), owned = join(stage, 'execution'); for (const entry of layout.entries) {
+        const target = join(owned, entry.path);
+        await mkdir(dirname(target), { recursive: true, mode: 0o700 });
+        await copyFile(join(root, entry.path), target, constants.COPYFILE_EXCL);
+        if (await fileSha256(target) !== entry.sha256)
+            fail('binding', 'Copied TShark runtime differs.');
+    } return { executable: join(owned, relativeExecutable), arguments: [], environment: {} }; }, probe: async (launch, context) => { supported(); const result = await runTool(context, { tool: 'tshark', role: 'version', executable: launch.executable, arguments: ['--version'], maxOutputBytes: 65536, timeoutMs: 10000, nativeDeadline: true }); if (!/^TShark \(Wireshark\) 4\.6\.9\b/.test(result.stdout))
+        fail('configuration', 'Select TShark 4.6.9.'); return { version: '4.6.9', offlineCaptureOnly: true, privateSettings: true, consoleSubset: true, systemCaptureHelperRequired: false }; } }); }
+const fields = ['frame.number', 'frame.time_epoch', 'frame.len', 'frame.protocols', 'ip.src', 'ip.dst', 'ipv6.src', 'ipv6.dst', 'tcp.srcport', 'tcp.dstport', 'tcp.stream', 'udp.srcport', 'udp.dstport', 'udp.stream', '_ws.col.Protocol', 'http.request.method', 'http.request.full_uri', 'http.request.uri', 'http.response.code', 'dns.qry.name', 'tls.handshake.extensions_server_name'];
+export function tsharkRows(value) { let rows; try {
+    rows = JSON.parse(value);
+}
+catch {
+    fail('partial', 'TShark did not return a complete bounded JSON document.');
+} if (!Array.isArray(rows) || rows.length > 10001)
+    fail('partial', 'Unexpected bounded packet inventory.'); return rows.map(row => { const layers = row?._source?.layers; if (!layers || typeof layers !== 'object' || Array.isArray(layers))
+    fail('partial', 'Packet fields are unavailable.'); for (const [key, values] of Object.entries(layers)) {
+    if (key.length > 256 || !Array.isArray(values) || values.length > 65536 || values.some(v => typeof v !== 'string' || v.length > 65536))
+        fail('partial', 'Packet fields exceed their typed bounds.');
+} if (!/^\d+$/.test(layers['frame.number']?.[0] ?? ''))
+    fail('partial', 'Packet has no frame identity.'); return layers; }); }
+export function tsharkStreams(rows) { const streams = new Map(); for (const row of rows)
+    for (const transport of ['tcp', 'udp'])
+        for (const value of row[transport + '.stream'] ?? []) {
+            if (!/^\d+$/.test(value))
+                fail('partial', 'Invalid native stream identity.');
+            const key = transport + ':' + value, stream = streams.get(key) ?? { transport, stream: Number(value), frames: [], sources: new Set(), destinations: new Set() };
+            stream.frames.push(Number(row['frame.number'][0]));
+            for (const ip of [...(row['ip.src'] ?? []), ...(row['ipv6.src'] ?? [])])
+                stream.sources.add(ip);
+            for (const ip of [...(row['ip.dst'] ?? []), ...(row['ipv6.dst'] ?? [])])
+                stream.destinations.add(ip);
+            streams.set(key, stream);
+        } return [...streams.values()].map(v => ({ ...v, frames: [...new Set(v.frames)], sources: [...v.sources], destinations: [...v.destinations] })); }
+export function tsharkFollow(output, transport, stream) { const lines = output.trim().split(/\r?\n/), nodes = [], chunks = []; if (!lines.includes('Follow: ' + transport + ',raw') || !lines.includes('Filter: ' + transport + '.stream eq ' + stream))
+    fail('partial', 'Follow output does not match the selected native stream.'); for (const line of lines) {
+    const node = /^Node ([01]): (.*)$/.exec(line);
+    if (node) {
+        nodes[Number(node[1])] = node[2];
+        continue;
+    }
+    if (/^\t?[0-9a-f]+$/i.test(line)) {
+        const hex = line.trim();
+        if (hex.length % 2)
+            fail('partial', 'Follow output has an incomplete byte.');
+        chunks.push({ node: line.startsWith('\t') ? 1 : 0, hex, bytes: hex.length / 2 });
+    }
+} if (nodes.length !== 2)
+    fail('partial', 'Follow output has no endpoint pair.'); return { nodes, chunks, totalBytes: chunks.reduce((n, v) => n + v.bytes, 0) }; }
+export function tsharkCommands(workspace) {
+    const definition = defineTool({ id: 'tshark', description: 'Inspect an immutable offline capture, packet fields and reconstructed TCP/UDP streams', components: [{ id: 'tshark', version: '4.6.9', artifacts: [] }], lifecycle: { download: (o, c) => tsharkInstaller(c).download(Boolean(o.offline)), install: (o, c) => tsharkInstaller(c).install(o), status: (_o, c) => tsharkInstaller(c).status(), doctor: (_o, c) => tsharkInstaller(c).doctor(), uninstall: (o, c) => tsharkInstaller(c).uninstall(Boolean(o.purgeCache)) } });
+    return [command('tshark', definition.description, [...lifecycleCommands(definition), command('inspect [input]', 'Read bounded protocol evidence from a captured PCAP/PCAPNG', async ({ args, options: o }, c) => {
+                supported();
+                if (Boolean(args.input) === Boolean(o.target))
+                    fail('invalid', 'Supply one PCAP path or --target.');
+                const view = text(o.view ?? 'overview', 32);
+                if (!['overview', 'packets', 'packet', 'streams', 'follow'].includes(view))
+                    fail('invalid', 'Use overview, packets, packet, streams or follow.');
+                const limit = number(o.limit ?? 50, 1000, 1), offset = number(o.offset ?? 0, 1000000), frame = o.frame === undefined ? undefined : number(o.frame, 1000000, 1), filter = o.filter === undefined ? undefined : text(o.filter, 4096);
+                if ((view === 'packet') !== (frame !== undefined))
+                    fail('invalid', 'Only packet view requires --frame.');
+                if ((o.stream !== undefined || o.transport !== undefined) !== (view === 'follow'))
+                    fail('invalid', 'Only follow view requires --stream and --transport.');
+                if (view === 'packet' && filter)
+                    fail('invalid', 'Packet detail uses its exact --frame without a display filter.');
+                if (view === 'follow' && (o.stream === undefined || o.transport === undefined || filter))
+                    fail('invalid', 'Follow requires --stream and --transport, without --filter.');
+                const transport = view === 'follow' ? text(o.transport, 8) : undefined, stream = view === 'follow' ? number(o.stream, 1000000) : undefined;
+                if (transport && !['tcp', 'udp'].includes(transport))
+                    fail('invalid', 'Follow transport must be tcp or udp.');
+                const w = workspace(c), target = args.input ? await w.importTarget(resolve(c.cwd, text(args.input, 4096))) : w.target(id(o.target)), input = await w.artifacts.verify(target.input);
+                if (target.input.size > 64 * 1024 ** 2)
+                    fail('limit', 'Capture input exceeds 64 MiB.');
+                const file = await open(input, 'r'), header = Buffer.alloc(4);
+                try {
+                    await file.read(header, 0, 4, 0);
+                }
+                finally {
+                    await file.close();
+                }
+                if (!['d4c3b2a1', 'a1b2c3d4', '4d3cb2a1', 'a1b23c4d', '0a0d0d0a'].includes(header.toString('hex')))
+                    fail('unsupported', 'Input is not a PCAP/PCAPNG capture.');
+                const directory = join(c.appArguments.AppDataDirectory, 'runtime/tshark/queries', randomUUID()), home = join(directory, 'home');
+                await mkdir(home, { recursive: true, mode: 0o700 });
+                return tsharkInstaller(c).use(async (selected) => {
+                    const runs = [], run = async (arguments_, maxOutputBytes = 16 * 1024 ** 2, acceptedCodes = [0]) => { const r = await runTool(c, { tool: 'tshark', role: view, installation: selected.id, executable: selected.executable, arguments: [...safeArguments, '-r', input, ...arguments_], environment: { HOME: home, XDG_CONFIG_HOME: join(home, 'config'), XDG_DATA_HOME: join(home, 'data'), WIRESHARK_CONFIG_DIR: join(home, 'config/wireshark') }, target: target.id, nativeDeadline: true, timeoutMs: 60000, maxOutputBytes, acceptedCodes, metadata: { inputSha256: target.binarySha256, view } }); runs.push({ process: r.process, diagnostics: r.diagnostics, elapsedMs: r.elapsedMs, exitCode: r.exitCode, stderr: r.stderr }); return r; };
+                    let data, total, items, complete = true, scannedFrames;
+                    if (view === 'packet') {
+                        const r = await run(['-c', String(frame), '-Y', 'frame.number == ' + frame, '-T', 'json', '--no-duplicate-keys']);
+                        try {
+                            data = JSON.parse(r.stdout);
+                        }
+                        catch {
+                            fail('partial', 'Native packet detail is incomplete.', { diagnostics: r.diagnostics });
+                        }
+                        if (!Array.isArray(data) || data.length > 1)
+                            fail('partial', 'Packet detail did not preserve one frame identity.');
+                        if (!data.length)
+                            fail('notFound', 'Selected packet was not found before the capture ended.');
+                    }
+                    else {
+                        const r = await run(['-c', '10001', '-T', 'json', '--no-duplicate-keys', ...fields.flatMap(f => ['-e', f])], 16 * 1024 ** 2, [0, 2]), observed = tsharkRows(r.stdout);
+                        complete = r.exitCode === 0 && observed.length < 10001;
+                        const rows = observed.slice(0, 10000);
+                        scannedFrames = rows.length;
+                        let selectedRows = rows;
+                        if (filter) {
+                            const f = await run(['-c', '10000', '-Y', filter, '-T', 'fields', '-e', 'frame.number'], 1024 ** 2), matches = f.stdout.trim() ? f.stdout.trim().split(/\r?\n/) : [];
+                            if (matches.some(v => !/^\d+$/.test(v)))
+                                fail('partial', 'Filtered native frame identities are invalid.');
+                            const ids = new Set(matches);
+                            selectedRows = rows.filter(p => ids.has(p['frame.number'][0]));
+                        }
+                        if (view === 'follow') {
+                            if (!tsharkStreams(rows).some(s => s.transport === transport && s.stream === stream))
+                                fail(complete ? 'notFound' : 'partial', 'Selected stream is absent from the inspected capture prefix; no follow is fabricated.');
+                            const followed = await run(['-c', '10000', '-q', '-z', 'follow,' + transport + ',raw,' + stream], 2 * 1024 ** 2, [0, 2]);
+                            complete &&= followed.exitCode === 0;
+                            data = tsharkFollow(followed.stdout, transport, stream);
+                        }
+                        else if (view === 'packets')
+                            items = selectedRows;
+                        else if (view === 'streams')
+                            items = tsharkStreams(selectedRows);
+                        else {
+                            const protocols = {};
+                            for (const row of selectedRows) {
+                                const protocol = row['_ws.col.protocol']?.[0] ?? 'unknown';
+                                protocols[protocol] = (protocols[protocol] ?? 0) + 1;
+                            }
+                            data = { matchingFrames: selectedRows.length, protocols, streams: tsharkStreams(selectedRows).length, firstFrame: selectedRows[0]?.['frame.number']?.[0], lastFrame: selectedRows.at(-1)?.['frame.number']?.[0] };
+                        }
+                    }
+                    if (await fileSha256(input) !== target.binarySha256)
+                        fail('binding', 'Immutable capture changed during inspection.');
+                    if (items)
+                        total = items.length;
+                    const base = { state: complete ? 'completed' : 'partial', complete, target: target.id, inputSha256: target.binarySha256, view, filter, scannedFrames, coverage: view === 'packet' ? 'One selected frame; packet existence is verified, whole-capture coverage is not claimed.' : complete ? 'All frames reached EOF in the bounded inventory; native protocol evidence is limited by packet content and dissector behavior.' : 'Only the first 10000 frames or a readable prefix were inspected; later packets, missing streams and absent matches remain unknown.', runs, diagnostics: directory };
+                    if (o.output) {
+                        const output = resolve(c.cwd, text(o.output, 4096)), content = JSON.stringify({ ...base, ...(items ? { items, total } : { data }) }, null, 2) + '\n';
+                        await mkdir(dirname(output), { recursive: true, mode: 0o700 });
+                        await writeFile(output, content, { flag: 'wx', mode: 0o600 });
+                        return { ...base, output, bytes: Buffer.byteLength(content), total };
+                    }
+                    return { ...base, ...(items ? { items: items.slice(offset, offset + limit), total, limit, offset, truncated: offset + limit < items.length } : { data }) };
+                });
+            }, { permission: Permission.Update, options: [{ flags: '--target <id>', description: 'Reuse an immutable captured PCAP' }, { flags: '--view <kind>', description: 'overview, packets, packet, streams or follow', defaultValue: 'overview' }, { flags: '--filter <expression>', description: 'Native Wireshark display filter within the inspected prefix' }, { flags: '--frame <number>', description: 'Required for packet view; decimal frame number, up to one million' }, { flags: '--transport <kind>', description: 'Required for follow: tcp or udp' }, { flags: '--stream <index>', description: 'Required for follow: zero-based native stream ID' }, { flags: '--limit <count>', description: 'Return up to 1000 packet/stream rows', defaultValue: 50 }, { flags: '--offset <count>', description: 'Skip matching rows after filtering', defaultValue: 0 }, { flags: '--output <file>', description: 'Save the complete bounded view to a new ordinary JSON file' }] })])];
+}

package/dist/src/windbg.d.ts

@@ -0,0 +1,14 @@
+import { type CommandContext, type CommandDefinition } from '@eyeauras/cli-factory';
+import { ToolInstaller } from './tool-runtime/installer.js';
+import type { Workspace } from './workspace.js';
+export declare function windbgInstaller(c: CommandContext): ToolInstaller;
+export declare function windbgPlan(o: Record<string, unknown>, nonce: string): {
+    view: "modules" | "registers" | "memory" | "threads" | "overview" | "stack" | "disassembly";
+    commands: string;
+};
+export declare function windbgSnapshot(stdout: string, nonce: string): {
+    lines: string[];
+    complete: boolean;
+    warnings: string[];
+};
+export declare function windbgCommands(workspace: (c: CommandContext) => Workspace): CommandDefinition[];

package/dist/src/windbg.js

@@ -0,0 +1,119 @@
+import { command, Permission } from '@eyeauras/cli-factory';
+import { basename, dirname, join, resolve } from 'node:path';
+import { mkdir, writeFile, open, copyFile, readdir, rm } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { ToolInstaller } from './tool-runtime/installer.js';
+import { defineTool, lifecycleCommands } from './tool-runtime/definition.js';
+import { catalogArtifact } from './tool-runtime/catalog.js';
+import { runTool } from './tool-runtime/run.js';
+import { fileSha256, extractArchive } from './tool-runtime/archives.js';
+import { treeFingerprint } from './tool-runtime/store.js';
+import { fail, text, id } from './model.js';
+import { number } from './research.js';
+const bundleSha = '4662ae17bc0dc77db987b89cccea32c30058baa06268f861d09e0ab4e4f45c20';
+function supported() { if (process.platform !== 'win32' || process.arch !== 'x64')
+    fail('unsupported', 'This WinDbg facade requires Windows x64. It inspects Windows user-mode minidumps without launching or attaching their original process.'); }
+export function windbgInstaller(c) {
+    return new ToolInstaller(c, { id: 'windbg', primary: 'windbg', components: () => { supported(); return { windbg: catalogArtifact(bundleSha) }; }, prepare: async (roots, context) => {
+            const root = roots.windbg, inner = join(root, 'windbg_win-x64.msix');
+            if (await fileSha256(inner, context.signal) !== '959c4ec033e2d00f7ed75646e4d352cc7cff6de33f494fd5dccb83819fe64e7a')
+                fail('binding', 'WinDbg x64 nested package differs from the pinned distribution.');
+            await extractArchive(inner, join(root, 'payload'), 'zip', context.signal);
+            for (const name of await readdir(root))
+                if (name.endsWith('.msix'))
+                    await rm(join(root, name));
+        }, launch: roots => ({ executable: join(roots.windbg, 'payload/amd64/cdb.exe'), arguments: [], environment: {} }), externalInputs: async (executable) => {
+            supported();
+            if (basename(executable).toLowerCase() !== 'cdb.exe')
+                fail('configuration', 'Select the WinDbg bundle amd64/cdb.exe console executable.');
+            const root = dirname(executable);
+            for (const name of ['dbgeng.dll', 'dbghelp.dll', 'dbgmodel.dll'])
+                await fileSha256(join(root, name));
+            return { consoleFamily: await treeFingerprint(root) };
+        }, probe: async (launch, context) => { supported(); const r = await runTool(context, { tool: 'windbg', role: 'version', executable: launch.executable, arguments: ['-version'], maxOutputBytes: 65536, timeoutMs: 15000, nativeDeadline: true }); if (!/\b(?:cdb(?:\.exe)?|debugger)\s+(?:version\s+)?10\.[0-9.]+/i.test(r.stdout + '\n' + r.stderr))
+            fail('configuration', 'Select a compatible Microsoft CDB 10.x console debugger with its adjacent runtime.', { nativeVersion: (r.stdout + '\n' + r.stderr).trim(), diagnostics: r.diagnostics }); return { packageVersion: '1.2610.1001.0', consoleVersion: (r.stdout + '\n' + r.stderr).trim(), ownedJob: true, mode: 'read-only-user-minidump' }; } });
+}
+export function windbgPlan(o, nonce) {
+    const view = text(o.view ?? 'overview', 32), commands = [];
+    if (o.thread !== undefined)
+        commands.push('~' + number(o.thread, 65535) + 's');
+    switch (view) {
+        case 'overview':
+            commands.push('vertarget', '~', 'kp 0n' + number(o.frames ?? 32, 128, 1), 'r', 'lm');
+            break;
+        case 'stack':
+            commands.push('kp 0n' + number(o.frames ?? 32, 128, 1));
+            break;
+        case 'threads':
+            commands.push('~');
+            break;
+        case 'registers':
+            commands.push('r');
+            break;
+        case 'modules':
+            commands.push('lm');
+            break;
+        case 'memory':
+        case 'disassembly': {
+            const address = text(o.address, 32);
+            if (!/^0x[0-9a-fA-F]{1,16}$/.test(address))
+                fail('invalid', 'A hexadecimal runtime --address is required.');
+            const count = number(o.count ?? (view === 'memory' ? 64 : 16), view === 'memory' ? 4096 : 256, 1);
+            commands.push((view === 'memory' ? 'db ' : 'u ') + address + ' L0x' + count.toString(16));
+            break;
+        }
+        default: fail('invalid', 'Choose overview, stack, threads, registers, modules, memory or disassembly.');
+    }
+    if (!['memory', 'disassembly'].includes(view) && (o.address !== undefined || o.count !== undefined))
+        fail('invalid', '--address and --count require memory or disassembly.');
+    if (!['stack', 'overview'].includes(view) && o.frames !== undefined)
+        fail('invalid', '--frames requires stack or overview.');
+    return { view, commands: ['.echo INSIGHT_BEGIN_' + nonce, ...commands, '.echo INSIGHT_END_' + nonce, 'q'].join('; ') };
+}
+export function windbgSnapshot(stdout, nonce) {
+    const output = stdout.split(/\r?\n/), start = output.findIndex(line => line.trim() === 'INSIGHT_BEGIN_' + nonce), end = output.findIndex((line, index) => index > start && line.trim() === 'INSIGHT_END_' + nonce);
+    if (start < 0 || end < 0)
+        fail('partial', 'CDB did not complete the selected dump query; inspect retained diagnostics.');
+    const lines = output.slice(start + 1, end);
+    const diagnostics = stdout.split(/\r?\n/).filter(line => /error|warning|unable to|could not|not found|couldn't|memory access|\?{4,}|syntax error|invalid thread/i.test(line));
+    return { lines, complete: diagnostics.length === 0, warnings: diagnostics.slice(0, 100) };
+}
+export function windbgCommands(workspace) {
+    const definition = defineTool({ id: 'windbg', description: 'Inspect Windows native user-mode dump stacks, registers, modules and memory', vendorDirect: true, components: [{ id: 'windbg', version: '1.2610.1001.0', artifacts: [] }], lifecycle: { download: (o, c) => windbgInstaller(c).download(Boolean(o.offline), Boolean(o.vendorDirect)), install: (o, c) => windbgInstaller(c).install(o), uninstall: (o, c) => windbgInstaller(c).uninstall(Boolean(o.purgeCache)), doctor: (_o, c) => windbgInstaller(c).doctor(), status: (_o, c) => windbgInstaller(c).status() } });
+    return [command('windbg', definition.description, [...lifecycleCommands(definition), command('inspect [input]', 'Read a captured Windows minidump with bounded typed debugger queries', async ({ args, options: o }, c) => {
+                supported();
+                if (Boolean(args.input) === Boolean(o.target))
+                    fail('invalid', 'Supply exactly one dump path or --target.');
+                const nonce = randomUUID().replaceAll('-', ''), plan = windbgPlan(o, nonce), limit = number(o.limit ?? 200, 1000, 1), offset = number(o.offset ?? 0, 1000000), timeoutMs = number(o.timeoutSeconds ?? 30, 600, 1) * 1000;
+                const w = workspace(c), target = args.input ? await w.importTarget(resolve(c.cwd, text(args.input, 4096))) : w.target(id(o.target)), input = await w.artifacts.verify(target.input), header = Buffer.alloc(32), handle = await open(input, 'r');
+                try {
+                    const { bytesRead } = await handle.read(header, 0, 32, 0);
+                    if (bytesRead < 32 || header.subarray(0, 4).toString('ascii') !== 'MDMP')
+                        fail('unsupported', 'WinDbg inspect requires a Windows user-mode minidump (MDMP).');
+                }
+                finally {
+                    await handle.close();
+                }
+                const directory = join(c.appArguments.AppDataDirectory, 'runtime/windbg/queries', randomUUID()), symbolDirectory = join(directory, 'symbols');
+                await mkdir(symbolDirectory, { recursive: true, mode: 0o700 });
+                const symbols = o.symbols ? await w.artifacts.capture(resolve(c.cwd, text(o.symbols, 4096)), 'input') : undefined;
+                if (symbols) {
+                    const name = basename(text(o.symbols, 4096));
+                    if (!/^[a-zA-Z0-9_. -]+\.pdb$/i.test(name))
+                        fail('invalid', 'Symbol companion must have an ordinary .pdb filename.');
+                    await copyFile(await w.artifacts.verify(symbols), join(symbolDirectory, name), constants.COPYFILE_EXCL);
+                }
+                return windbgInstaller(c).use(async (selected) => {
+                    const result = await runTool(c, { tool: 'windbg', role: 'inspect', installation: selected.id, executable: selected.executable, arguments: ['-sins', '-noshell', '-nosqm', '-netsyms:no', '-failinc', '-y', symbolDirectory, '-z', input, '-c', plan.commands], cwd: directory, target: target.id, timeoutMs, nativeDeadline: true, metadata: { dumpSha256: target.binarySha256, view: plan.view, ...(symbols ? { symbolsSha256: symbols.sha256 } : {}) } }), snapshot = windbgSnapshot(result.stdout, nonce);
+                    const base = { state: snapshot.complete ? 'completed' : 'partial', complete: snapshot.complete, target: target.id, inputSha256: target.binarySha256, ...(symbols ? { symbolsSha256: symbols.sha256 } : {}), view: plan.view, process: result.process, elapsedMs: result.elapsedMs, diagnostics: result.diagnostics, stderr: result.stderr, warnings: snapshot.warnings, coverage: 'Read-only dump observation. Runtime addresses and thread indices belong to this dump; missing memory or symbols are unknown. Local matching PDB only; no symbol server. No original process is launched or attached.' };
+                    if (o.output) {
+                        const output = resolve(c.cwd, text(o.output, 4096)), content = JSON.stringify({ ...base, lines: snapshot.lines }, null, 2) + '\n';
+                        await mkdir(dirname(output), { recursive: true, mode: 0o700 });
+                        await writeFile(output, content, { flag: 'wx', mode: 0o600 });
+                        return { ...base, output, bytes: Buffer.byteLength(content), totalLines: snapshot.lines.length };
+                    }
+                    return { ...base, lines: snapshot.lines.slice(offset, offset + limit), offset, limit, totalLines: snapshot.lines.length, truncated: offset + limit < snapshot.lines.length };
+                });
+            }, { permission: Permission.Update, options: [{ flags: '--target <id>', description: 'Reuse a captured minidump target' }, { flags: '--view <kind>', description: 'overview, stack, threads, registers, modules, memory or disassembly', defaultValue: 'overview' }, { flags: '--thread <index>', description: 'Dump thread index (decimal)' }, { flags: '--frames <count>', description: 'Stack frames (1–128)' }, { flags: '--address <hex>', description: 'Required runtime 0x address for memory/disassembly' }, { flags: '--count <count>', description: 'Memory bytes (1–4096) or instructions (1–256)' }, { flags: '--symbols <file>', description: 'Capture a matching local PDB companion; network symbols are disabled' }, { flags: '--output <file>', description: 'Save the full bounded result to a new ordinary JSON file' }, { flags: '--limit <count>', description: 'Maximum native lines (1–1000)', defaultValue: 200 }, { flags: '--offset <count>', description: 'Skip native output lines', defaultValue: 0 }, { flags: '--timeout-seconds <seconds>', description: 'Owned debugger deadline (1–600)', defaultValue: 30 }] })])];
+}

package/dist/src/workspace.d.ts

@@ -138,6 +138,7 @@ export declare class Workspace {
     sessions(limit?: number, offset?: number): ResearchSession[];
     model(target: string): GhidraModel;
     context(scope: Scope): GhidraContext;
+    contextById(context: string): GhidraContext;
     contexts(session: string, limit?: number, offset?: number): GhidraContext[];
     private existingRequest;
     private insertRequest;

package/dist/src/workspace.js

@@ -183,6 +183,12 @@ export class Workspace {
             fail('notFound', 'No Ghidra context exists for this session and target; open it first.');
         return JSON.parse(String(row.data));
     }
+    contextById(context) {
+        const row = this.db.prepare('SELECT data FROM contexts WHERE id=?').get(id(context));
+        if (!row)
+            fail('notFound', 'Tool context was not found.');
+        return JSON.parse(String(row.data));
+    }
     contexts(session, limit = 100, offset = 0) {
         this.session(session);
         page(limit, offset);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eyeauras/insight-cli",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "type": "module",
   "description": "Agent-facing durable sessions and isolated Ghidra research contexts",
   "main": "./dist/src/index.js",
@@ -13,18 +13,19 @@
     "dist/src",
     "SKILL.md",
     "skills",
+    "skill-bundle",
     "references",
     "runtime",
     "LICENSE",
     ".cli-package-build.json"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.json && node ../../scripts/prepare-package.mjs",
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json && node ../../scripts/prepare-package.mjs",
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@eyeauras/cli-factory": "0.4.1",
-    "@eyeauras/cli-factory-ipc": "https://raw.githubusercontent.com/iXab3r/insight-cli/43f815a006711418bcffa47a7d99ef5c42424ca5/vendor/factory-ipc-a2094fb.tgz",
+    "@eyeauras/cli-factory": "https://raw.githubusercontent.com/iXab3r/insight-cli/73459aecc88da6f878988b64f71ab72b34a83c45/vendor/factory-core-74e7a64.tgz",
+    "@eyeauras/cli-factory-ipc": "https://raw.githubusercontent.com/iXab3r/insight-cli/f47f6d14e8aadc6b6778a6e3627bbb08909521d2/vendor/factory-ipc-7c403d8.tgz",
     "@modelcontextprotocol/sdk": "1.32.1",
     "tar": "7.5.22",
     "yauzl": "3.4.0"

package/references/agent-execution.md

@@ -0,0 +1,36 @@
+# Agent host execution permissions
+
+Keep the user/project host policy and the selected profile. A sandbox can deny writes
+to runtime AppData or access to the local IPC endpoint, including during local help.
+This is a host execution boundary, not evidence that the tool or its inputs are absent.
+
+First retry only `insight-cli --help`, `tools list`, `skill`, or the selected application's
+read-only `status` using the host's normal permission escalation. In Codex, use the
+execution tool's `sandbox_permissions: "require_escalated"` with a scoped explanation
+that the installed CLI needs its existing profile storage/local IPC. Automatic approval
+review or the user decides that request; do not disable the sandbox or approval policy.
+
+Do not work around this by changing HOME/AppData/profile paths, creating another host,
+deleting owner/endpoint files, killing unrelated processes or claiming a missing runtime.
+After the read-only probe succeeds, use the approved execution route for the intended
+public CLI commands. An access refusal explicitly stating **no command was sent** is
+known not dispatched; it is safe to submit that authorized command through the approved
+route. This includes a mutation refused before dispatch. Do not mistake that definite
+pre-dispatch refusal for an unknown execution outcome. Downloads still require their explicit
+network access.
+
+A lost mutation response is different from a denied startup probe: inspect retained
+request/status/recovery evidence and use its request ID when supported. Never blindly
+repeat a publication, script or program run whose outcome is unknown. External-tool
+fallback is allowed by project rules, but record that the intended facade was not used
+and do not invent a successful checkpoint or native result.
+
+## Wait for the original execution
+
+A tool operation may outlast the host execution tool's initial wait. A returned running
+session/cell ID means that command is still in progress, not that the CLI returned no data.
+Use the host's session poll/wait facility until terminal exit and consume stdout/stderr
+before issuing a dependent command. In Codex, an `exec_command` session is continued with
+`write_stdin`; a yielded execution cell uses that host's cell wait. Do not launch a second
+open/install or repeat a CPU action just because the first chunk was empty. If the execution
+really loses its terminal result, use the CLI's request/status recovery as described above.

package/references/agent-setup.md

@@ -0,0 +1,61 @@
+# Connect the toolbox to an agent
+
+npm installs the CLI and all declared skills. Native tool downloads are separate. A host needs
+shell access to `insight-cli`, skill discovery and execution access to the assigned profile.
+`insight-cli tools list --json` discovers shipped capabilities without profile configuration,
+native runtimes, credentials or IPC. `skill <name>` returns the instructions' ordinary path;
+it does not inject them into an agent automatically.
+
+## Codex: one project-local bundle
+
+The package prepares `skill-bundle`, containing an independent folder for every registered
+skill. `insight-cli skill --json` returns its `bundlePath`. References stay inside each skill;
+link the whole bundle once rather than connecting each tool separately. npm installation
+never edits agent settings or project RE instructions.
+
+With a global npm installation, run from the research project:
+
+```sh
+mkdir -p .agents/skills
+ln -s "$(npm root -g)/@eyeauras/insight-cli/skill-bundle" .agents/skills/insight-toolbox
+```
+
+`ln` refuses an existing destination: inspect it instead of overwriting another skill or
+connection. Local npm installations use the `bundlePath` from their actual CLI receipt.
+These machine-local links are not portable files to commit to a shared project. Start a fresh
+agent and verify all registered names/descriptions appear. The [official discovery contract](https://learn.chatgpt.com/docs/build-skills)
+supports project skills and symlinked directories; our actual host gate must still establish
+recursive discovery for this packaged bundle.
+
+An npm upgrade at the same global prefix replaces the bundle at the same path, including newly
+registered tool skills. Check its manifest/version and start a fresh host session after upgrade.
+A changed npm prefix needs reconnection. To disconnect, inspect `readlink .agents/skills/insight-toolbox`
+and remove only that owned symlink with `unlink .agents/skills/insight-toolbox`; preserve other
+entries and the package. No copied skills, per-tool installer or second agent configuration
+store is maintained. Other hosts may register this ordinary bundle through their own mechanism;
+Codex is the first concrete supported-host gate.
+
+## Execution access
+
+A skill link does not grant filesystem or IPC permissions. Allow the assigned profile's AppData
+and the CLI's `.runtime` directory, plus its exact local IPC endpoint. On macOS the application
+root is `~/Library/Application Support/insight-cli`; its Unix socket is `.runtime/host.sock`.
+Keep unrelated profiles outside the write scope and pass the assigned `--profile` explicitly.
+Do not grant broad external network access merely to reach a local socket.
+
+An inaccessible profile means readiness is unknown. Inspect access failures; stopping a shared
+owner does not grant access to it. Existing restricted-host evaluation has not established a
+complete facade workflow yet; a successful metadata call or filesystem grant alone is insufficient.
+
+## Behavioral acceptance
+
+Give a fresh agent an input and business question without commands/tool names. Verify startup
+metadata, implicit skill selection, intended public-tool use, correct findings, saved ordinary
+project files and cleanup. Ghidra edits additionally require merge and independent readback.
+Repeat cold-runtime and prepared-runtime cases; retain failures and distinguish an external-tool
+fallback from acceptance of the intended adapter. Package/skill existence is structural evidence,
+not proof that a model completed research.
+
+The project bundle is a symlink. A plain `find` does not follow it and can misleadingly
+show no files. Use the host skill inventory, a named `.../<skill>/SKILL.md` path, or
+`insight-cli skill <name>` to check availability; `find -L` follows the link if needed.

package/references/artifacts.md

@@ -24,6 +24,11 @@ files; byte count counts their contents. A file's SHA-256 hashes its bytes; a di
 SHA-256 hashes its canonical manifest of relative paths, kinds, file lengths and hashes.
 The manifest is stored beside the content, outside the returned directory.
 
+Before claiming a verified checkpoint, read the expected files at the returned `path` using
+ordinary file tools. Preserve that path verbatim in the handoff, alongside the receipt;
+profile and snapshot identifiers must not be reconstructed from memory. If access is denied,
+retain the actual receipt and state that readback remains unverified.
+
 The service copies and syncs data before publishing the completed snapshot. Failure does
 not return a successful receipt or expose a partial completed snapshot. Source edits made
 after a successful save do not change the copy. Treat saved copies as retained snapshots;

package/references/debugger.md

@@ -6,6 +6,12 @@ verified copy of the selected immutable input in an owned run directory. It acce
 `--args`, `--cwd`, a bounded launch timeout and the optional request ID. A second live process
 uses another session; it does not replace this context's current process.
 
+For local macOS `lldb`, `--stop-at-entry` launches stopped before normal program startup.
+The response verifies a live `STOPPED` target and reports `stoppedAtEntry: true`. This is
+useful for short programs: inspect/map/set breakpoints, then explicitly resume. Without the
+flag, the existing immediate-run behavior is unchanged. Other offers reject this flag before
+a CPU intent is reserved. An unknown stopped launch still requires ordinary request recovery.
+
 Read `debugger status`, `modules`, `registers`, `stack-trace` and `traces`. Address conversion
 uses `static-to-dynamic` and `dynamic-to-static`; memory and breakpoint commands take dynamic
 addresses. Lists are paged. Read results identify the logical context and current trace, and
@@ -38,3 +44,19 @@ directory are Factory profile settings. Native Windows/Linux acceptance remains
 
 Use generated help for exact flags. A retained static breakpoint bookmark may remain after its live trace placement is
 removed; `trace_location_count` distinguishes current placements from that static metadata.
+
+For a call observation, set the mapped function breakpoint **before** resuming from entry.
+After the stop, check the PC against that address, then capture arguments and stack before
+stepping. Step-out verifies return to the native caller in the same thread and stack;
+return registers are observed without being modified. A competing stop or unavailable caller
+does not count as a verified return. A requested step whose reply
+or observed completion is unknown remains journaled; do not issue another CPU action to
+try to recover a missing return. Retain its diagnostics and use request/status recovery.
+
+For another intentional run, close and reopen the same owned context first: this disconnects
+and retains the previous trace without relaunching it. Then launch with a distinct request ID
+and desired arguments. A connected debugger remains busy even after its subject has exited;
+selecting or reading its old trace is not a request to execute the subject again.
+Map the new process and explicitly set/check its live breakpoints before each resume from
+entry. Old static bookmarks do not establish new trace placements. Reopening restores each
+trace's saved snap/thread, including inactive traces; choose its returned ID with `--trace`.

package/references/ilspy.md

@@ -0,0 +1,33 @@
+# Static .NET research
+
+Use the project's preferred tools and evidence conventions. When ILSpy is appropriate,
+`insight-cli ilspy install` prepares its pinned CLI and private .NET runtime; a global SDK
+or dotnet installation is unnecessary. Lifecycle and archive options appear in `--help`.
+The ILSpy and runtime distributions come from our pinned GitHub Releases. For offline
+installation supply `--archive` and `--dotnet-archive`, or use an already verified cache.
+`--executable` selects a compatible external ilspycmd; uninstall preserves its files.
+
+```sh
+insight-cli ilspy types ./client.dll --json
+insight-cli ilspy decompile --target <returned-target> --type Example.Policy --output policy.cs --json
+insight-cli ilspy il --target <target> --type Example.Policy --json
+insight-cli ilspy resources --target <target> --json
+insight-cli ilspy resource --target <target> --name Example.settings.json --output extracted --json
+insight-cli ilspy project --target <target> --output recovered-project --json
+insight-cli ilspy metadata --target <target> --table MethodDef --json
+```
+
+Use either an input file or an existing target. Reusing the target associates Ghidra and
+ILSpy results with the same immutable bytes. No Ghidra context or merge is needed for a
+stateless ILSpy read. An optional `--session` associates an existing session; it does not
+create one. These calls require Update to capture input and run a tool.
+
+Text responses include `content`, input SHA, process ID, elapsed time and diagnostic paths.
+`--member` selects a metadata token or XML member ID for decompilation. Output paths must
+be new: text operations create one ordinary file, project/resource operations create a
+folder. Keep useful output in the project's chosen evidence location; `artifacts save`
+is an optional explicit checkpoint. Static decompilation does not execute an assembly.
+
+Use `tools processes --tool ilspy --all` for execution history and `tools processes show
+<process-id>` for retained diagnostics. A failed or interrupted export can leave partial
+files/staging; inspect them and choose a new output path for another intentional run.