@eyeauras/insight-cli 0.2.0 → 0.2.1

package/dist/src/frida-worker.js

@@ -0,0 +1,125 @@
+// Internal bounded collector process, never a second public CLI or persistent service.
+import { pathToFileURL } from 'node:url';
+import { processIdentity } from './tool-runtime/identity.js';
+import { inheritedDeadlineEnvironment } from './tool-runtime/deadline.js';
+import { mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+async function main() {
+    let input = '';
+    for await (const chunk of process.stdin) {
+        input += chunk;
+        if (Buffer.byteLength(input) > 2 * 1024 ** 2)
+            throw Error('Collector request exceeds two MiB');
+    }
+    const config = JSON.parse(input);
+    // Set this after Node starts: only SDK helper execs load the constructor, not the target.
+    const receipts = join(process.env.HOME, 'native-deadlines');
+    await mkdir(receipts, { mode: 0o700 });
+    Object.assign(process.env, await inheritedDeadlineEnvironment(config.deadlineUnixSeconds, receipts));
+    // This import is intentionally isolated in an owned child; native addon faults cannot crash the owner.
+    const frida = await import(pathToFileURL(config.module).href);
+    const emit = (value) => process.stdout.write(JSON.stringify(value) + '\n');
+    if (config.mode === 'probe') {
+        const version = await frida.getLocalDevice();
+        emit({ kind: 'probe', protocol: 1, version: '17.24.0', device: version.type });
+        return;
+    }
+    const cancellable = new frida.Cancellable();
+    let session, script, detached = false, finished = false, error = false, unloaded = false, sessionDetached = false, loaded = false, interrupted = false, count = 0;
+    const duration = config.durationMs ?? 1000, deadline = setTimeout(() => cancellable.cancel(), duration + 5000);
+    let resolveDone;
+    const done = new Promise(ok => resolveDone = ok);
+    let observation;
+    const stop = () => { interrupted = true; error = true; emit({ kind: 'interrupted', signal: 'SIGTERM' }); resolveDone(); if (!loaded)
+        cancellable.cancel(); };
+    process.once('SIGTERM', stop);
+    try {
+        if (!config.pid || (await processIdentity(config.pid))?.birth !== config.expectedBirth)
+            throw Error('Target birth identity changed before attach');
+        session = await frida.attach(config.pid, {}, cancellable);
+        session.detached.connect((reason, crash) => { detached = true; if (!finished) {
+            error = true;
+            emit({ kind: 'detached', reason, crash: Boolean(crash) });
+            resolveDone();
+        } });
+        let source = config.source;
+        if (config.mode === 'modules')
+            source = 'send({kind:"modules",items:Process.enumerateModules().map(m=>({name:m.name,path:m.path,base:m.base.toString(),size:m.size}))});';
+        if (config.mode === 'exports')
+            source = 'send({kind:"exports",module:' + JSON.stringify(config.moduleName) + ',items:Process.getModuleByName(' + JSON.stringify(config.moduleName) + ').enumerateExports()});';
+        // Keep user source untouched (strict directives and source line numbers matter).
+        const bootstrap = await session.createScript('send(Frida.version);', {}, cancellable);
+        let versionTimer;
+        const version = new Promise((ok, bad) => { bootstrap.message.connect((message) => message.type === 'send' ? ok(message.payload) : bad(new Error('Frida runtime version probe failed'))); versionTimer = setTimeout(() => bad(new Error('Frida runtime version probe timed out')), 5000); });
+        void version.catch(() => { });
+        try {
+            await bootstrap.load(cancellable);
+            const actual = await version;
+            emit({ kind: 'runtime', version: actual });
+            if (actual !== '17.24.0')
+                throw Error('Frida runtime version differs from 17.24.0');
+        }
+        finally {
+            if (versionTimer)
+                clearTimeout(versionTimer);
+            await bootstrap.unload(cancellable);
+        }
+        script = await session.createScript(source, {}, cancellable);
+        script.message.connect((message, data) => {
+            if (++count > 10000) {
+                error = true;
+                if (count === 10001)
+                    emit({ kind: 'limit', message: 'Collector exceeded 10000 messages' });
+                resolveDone();
+                return;
+            }
+            if (message.type === 'error') {
+                error = true;
+                resolveDone();
+            }
+            emit({ kind: 'message', message, ...(data ? { binaryBase64: data.toString('base64') } : {}) });
+            if (config.mode !== 'observe' && message.type === 'send' && message.payload?.kind === config.mode)
+                resolveDone();
+        });
+        await script.load(cancellable);
+        loaded = true;
+        emit({ kind: 'loaded' });
+        observation = setTimeout(resolveDone, duration);
+        await done;
+    }
+    finally {
+        if (observation)
+            clearTimeout(observation);
+        finished = true;
+        const cleanup = new frida.Cancellable(), cleanupDeadline = setTimeout(() => cleanup.cancel(), 2000);
+        try {
+            if (script && !detached) {
+                await script.unload(cleanup);
+                unloaded = true;
+            }
+        }
+        catch (e) {
+            error = true;
+            emit({ kind: 'cleanup-error', message: String(e) });
+        }
+        try {
+            if (session && !detached) {
+                await session.detach(cleanup);
+                sessionDetached = true;
+            }
+        }
+        catch (e) {
+            error = true;
+            emit({ kind: 'cleanup-error', message: String(e) });
+        }
+        clearTimeout(cleanupDeadline);
+        cleanup.cancel();
+        clearTimeout(deadline);
+        cancellable.cancel();
+        process.off('SIGTERM', stop);
+    }
+    emit({ kind: 'completed', complete: !error && unloaded && sessionDetached, detached, scriptUnloaded: unloaded, sessionDetached });
+    if (interrupted)
+        process.exitCode = 130;
+}
+main().catch(error => { process.stderr.write(String(error) + '\n'); process.exitCode = 1; });

package/dist/src/frida.d.ts

@@ -0,0 +1,16 @@
+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 fridaInstaller(c: CommandContext): ToolInstaller;
+export declare function fridaEvents(stdout: string): {
+    events: Record<string, any>[];
+    summary: {
+        totalEvents: number;
+        sendMessages: number;
+        scriptErrors: number;
+        logMessages: number;
+    };
+    complete: boolean;
+    cleanup: Record<string, any>;
+};
+export declare function fridaCommands(workspace: (c: CommandContext) => Workspace): CommandDefinition[];

package/dist/src/frida.js

@@ -0,0 +1,125 @@
+import { command, Permission } from '@eyeauras/cli-factory';
+import { dirname, join, resolve } from 'node:path';
+import { release } from 'node:os';
+import { readFile, mkdir, writeFile, stat } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+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 { treeFingerprint } from './tool-runtime/store.js';
+import { processIdentity } from './tool-runtime/identity.js';
+import { fail, text } from './model.js';
+import { number } from './research.js';
+const worker = fileURLToPath(new URL('./frida-worker.js', import.meta.url)), moduleRoot = (entry) => dirname(dirname(dirname(entry)));
+function supported() { if (process.platform !== 'darwin' || process.arch !== 'arm64' || Number(release().split('.')[0]) < 23)
+    fail('unsupported', 'This Frida facade requires macOS 14+ ARM64 and an explicitly selected authorized local process.'); }
+async function entryMetadata(entry) {
+    if (!entry.endsWith(join('build', 'src', 'frida.js')))
+        fail('configuration', 'External Frida selection requires its Node entry module at .../frida/build/src/frida.js; use managed install by default.');
+    let metadata;
+    try {
+        const path = join(moduleRoot(entry), 'package.json');
+        if ((await stat(path)).size > 128 * 1024)
+            fail('configuration', 'Invalid external Frida metadata.');
+        metadata = JSON.parse(await readFile(path, 'utf8'));
+    }
+    catch {
+        fail('configuration', 'External Frida Node package metadata is missing or invalid.');
+    }
+    if (metadata.name !== 'frida' || metadata.version !== '17.24.0')
+        fail('configuration', 'Select the Frida 17.24.0 Node entry module with its native NAPI-v8 binding and runtime dependencies.');
+    return metadata;
+}
+export function fridaInstaller(c) {
+    return new ToolInstaller(c, { id: 'frida', primary: 'frida', components: () => { supported(); return { frida: catalogArtifact('26e9e7b9a8d9c68c87cb3da879c328edd096d587720039095de6a522d2c8765e') }; }, launch: roots => ({ executable: join(roots.frida, 'node_modules/frida/build/src/frida.js'), arguments: [], environment: {} }), externalInputs: async (entry) => {
+            supported();
+            await entryMetadata(entry);
+            const values = { frida: await treeFingerprint(moduleRoot(entry)) };
+            for (const name of ['bindings', 'file-uri-to-path', 'minimatch', 'brace-expansion', 'balanced-match']) {
+                let found = false;
+                for (const base of createRequire(entry).resolve.paths(name) ?? []) {
+                    try {
+                        const root = join(base, name), metadata = JSON.parse(await readFile(join(root, 'package.json'), 'utf8'));
+                        if (metadata.name !== name)
+                            fail('binding', 'External Frida dependency identity differs.');
+                        values[name] = await treeFingerprint(root);
+                        found = true;
+                        break;
+                    }
+                    catch (error) {
+                        if (error.code !== 'ENOENT')
+                            throw error;
+                    }
+                }
+                if (!found)
+                    fail('configuration', 'External Frida runtime dependency is missing: ' + name);
+            }
+            return values;
+        }, probe: async (launch, context) => {
+            supported();
+            const metadata = await entryMetadata(launch.executable);
+            const result = await runTool(context, { tool: 'frida', role: 'probe', executable: process.execPath, arguments: ['--no-warnings', worker], input: JSON.stringify({ mode: 'probe', module: launch.executable, deadlineUnixSeconds: Math.ceil(Date.now() / 1000) + 10 }), timeoutMs: 10000, nativeDeadline: true, nativeChildDeadlines: true, maxOutputBytes: 65536 });
+            const value = JSON.parse(result.stdout);
+            if (value.kind !== 'probe' || value.protocol !== 1 || value.device !== 'local')
+                fail('binding', 'Frida native binding did not provide a compatible local-device API.');
+            return { declaredVersion: metadata.version, node: process.version, entryKind: 'Node module', nativeApi: 'local device', pythonRequired: false };
+        } });
+}
+export function fridaEvents(stdout) {
+    const events = stdout.trim().split(/\r?\n/).filter(Boolean).map(line => { try {
+        return JSON.parse(line);
+    }
+    catch {
+        fail('binding', 'Frida collector returned malformed events; inspect retained native diagnostics.');
+    } });
+    const completed = events.at(-1);
+    if (completed?.kind !== 'completed' || typeof completed.complete !== 'boolean')
+        fail('partial', 'Frida did not acknowledge bounded capture and cleanup; inspect process diagnostics.');
+    const errors = events.some(e => ['detached', 'cleanup-error', 'limit'].includes(e.kind) || e.kind === 'message' && e.message?.type === 'error');
+    const summary = { totalEvents: events.length, sendMessages: events.filter(e => e.kind === 'message' && e.message?.type === 'send').length, scriptErrors: events.filter(e => e.kind === 'message' && e.message?.type === 'error').length, logMessages: events.filter(e => e.kind === 'message' && e.message?.type === 'log').length };
+    return { events, summary, complete: !errors && completed.complete === true && completed.scriptUnloaded === true && completed.sessionDetached === true && events.some(e => e.kind === 'runtime' && e.version === '17.24.0'), cleanup: completed };
+}
+export function fridaCommands(workspace) {
+    const definition = defineTool({ id: 'frida', description: 'Inspect modules/exports or collect bounded Frida script events from an explicit local PID', components: [{ id: 'frida', version: '17.24.0', artifacts: [] }], installOptions: [{ flags: '--archive <path>', description: 'Install a local Frida Node runtime archive' }, { flags: '--archive-sha256 <sha256>', description: 'Expected local archive hash' }, { flags: '--executable <path>', description: 'External Frida Node entry module: .../frida/build/src/frida.js' }, { flags: '--offline', description: 'Use verified local cache without network access' }], lifecycle: { download: (o, c) => fridaInstaller(c).download(Boolean(o.offline)), install: (o, c) => fridaInstaller(c).install(o), uninstall: (o, c) => fridaInstaller(c).uninstall(Boolean(o.purgeCache)), doctor: (_o, c) => fridaInstaller(c).doctor(), status: (_o, c) => fridaInstaller(c).status() } });
+    const options = [{ flags: '--pid <pid>', description: 'Explicit authorized local process; its lifetime remains external', required: true }, { flags: '--output <file>', description: 'Save all bounded collector events to a new JSON file' }, { flags: '--limit <count>', description: 'Maximum returned events (1–1000)', defaultValue: 100 }, { flags: '--offset <count>', description: 'Skip events', defaultValue: 0 }];
+    const collect = (mode) => command(mode, mode === 'observe' ? 'Load a captured Frida JavaScript file, observe for a bounded interval, unload and detach' : mode === 'modules' ? 'Inventory runtime modules in the selected local process' : 'Inventory exported addresses in one selected runtime module', async ({ options: o }, c) => {
+        supported();
+        const pid = number(o.pid, 2147483647, 1), before = await processIdentity(pid);
+        if (pid === process.pid || !before || ['unavailable', 'unverified'].includes(before.birth))
+            fail('binding', 'Select a different live process with an observable OS birth identity.');
+        const durationMs = mode === 'observe' ? number(o.durationSeconds ?? 2, 120, 1) * 1000 : 1000, limit = number(o.limit ?? 100, 1000, 1), offset = number(o.offset ?? 0, 1000000), moduleName = mode === 'exports' ? text(o.module, 4096) : undefined;
+        let source, scriptSha256;
+        if (mode === 'observe') {
+            const w = workspace(c), path = resolve(c.cwd, text(o.script, 4096)), metadata = await stat(path);
+            if (!metadata.isFile() || metadata.size > 256 * 1024)
+                fail('limit', 'Frida script must be a regular file of at most 256 KiB.');
+            const artifact = await w.artifacts.capture(path, 'input');
+            if (artifact.size > 256 * 1024)
+                fail('limit', 'Frida script exceeds 256 KiB.');
+            try {
+                source = new TextDecoder('utf-8', { fatal: true, ignoreBOM: true }).decode(await readFile(await w.artifacts.verify(artifact)));
+            }
+            catch {
+                fail('invalid', 'Frida JavaScript source must be valid UTF-8.');
+            }
+            scriptSha256 = artifact.sha256;
+        }
+        return fridaInstaller(c).use(async (selected) => {
+            const result = await runTool(c, { tool: 'frida', role: mode, installation: selected.id, metadata: { subjectPid: pid, subjectBirth: before.birth, durationMs, ...(scriptSha256 ? { scriptSha256 } : {}), ...(moduleName ? { moduleName } : {}) }, executable: process.execPath, arguments: ['--no-warnings', worker], input: JSON.stringify({ module: selected.executable, mode, pid, expectedBirth: before.birth, moduleName, source, durationMs, deadlineUnixSeconds: Math.ceil(Date.now() / 1000) + (durationMs + 10000) / 1000 }), timeoutMs: durationMs + 10000, nativeDeadline: true, nativeChildDeadlines: true }), capture = fridaEvents(result.stdout), after = await processIdentity(pid), sameProcess = after?.birth === before.birth, complete = capture.complete && sameProcess;
+            const records = mode === 'observe' ? undefined : capture.events.filter(e => e.kind === 'message' && e.message?.type === 'send' && e.message.payload?.kind === mode).flatMap(e => Array.isArray(e.message.payload.items) ? e.message.payload.items : []);
+            const base = { state: complete ? 'completed' : 'partial', complete, summary: capture.summary, subject: { pid, birth: before.birth, strongIdentity: before.strong, ownership: 'external', sameProcessAfterCapture: sameProcess }, ...(scriptSha256 ? { scriptSha256 } : {}), process: result.process, diagnostics: result.diagnostics, elapsedMs: result.elapsedMs, stderr: result.stderr, cleanup: capture.cleanup, coverage: 'Observed execution during this interval; static correspondence and unobserved paths require separate evidence. macOS birth identity is best effort. Collector stop/kill never signals the external target.' };
+            if (o.output) {
+                const output = resolve(c.cwd, text(o.output, 4096)), content = JSON.stringify({ ...base, events: capture.events }, 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), totalEvents: capture.events.length };
+            }
+            if (records)
+                return { ...base, records: records.slice(offset, offset + limit), offset, limit, totalRecords: records.length, truncated: offset + limit < records.length, events: capture.events.filter(e => !(e.kind === 'message' && e.message?.payload?.kind === mode)) };
+            return { ...base, events: capture.events.slice(offset, offset + limit), offset, limit, totalEvents: capture.events.length, truncated: offset + limit < capture.events.length };
+        });
+    }, { permission: Permission.Update, options: [...options, ...(mode === 'exports' ? [{ flags: '--module <name>', description: 'Exact runtime module name or path', required: true }] : mode === 'observe' ? [{ flags: '--script <file>', description: 'Frida JavaScript source file; captured immutably before attach', required: true }, { flags: '--duration-seconds <seconds>', description: 'Observation window after script load (1–120)', defaultValue: 2 }] : [])] });
+    return [command('frida', definition.description, [...lifecycleCommands(definition), collect('modules'), collect('exports'), collect('observe')])];
+}

package/dist/src/ghidra-debugger-runtime.d.ts

@@ -0,0 +1,7 @@
+/** Private Python-capable LLDB dependency. The public application remains `ghidra`. */
+import type { CommandContext } from '@eyeauras/cli-factory';
+import { ToolInstaller, type ToolLaunch } from './tool-runtime/installer.js';
+export declare const managedGhidraDebugger: () => boolean;
+export declare function ghidraDebuggerLaunch(root: string): ToolLaunch;
+export declare function ghidraDebuggerInstaller(c: CommandContext): ToolInstaller;
+export declare function prepareGhidraDebugger(c: CommandContext, o?: Record<string, unknown>): Promise<import("./tool-runtime/installer.js").SelectedTool>;

package/dist/src/ghidra-debugger-runtime.js

@@ -0,0 +1,31 @@
+import { join } from 'node:path';
+import { release } from 'node:os';
+import { ToolInstaller } from './tool-runtime/installer.js';
+import { catalogArtifact } from './tool-runtime/catalog.js';
+import { runTool } from './tool-runtime/run.js';
+import { fail } from './model.js';
+export const managedGhidraDebugger = () => process.platform === 'darwin' && process.arch === 'arm64' && Number(release().split('.')[0]) >= 24;
+export function ghidraDebuggerLaunch(root) {
+    const python = join(root, 'python@3.15/3.15.0/Frameworks/Python.framework/Versions/3.15');
+    return { executable: join(root, 'bin/lldb'), arguments: [], environment: { PYTHONHOME: python, PYTHONPATH: join(root, 'lldb/23.1.3_1/lib/python3.15/site-packages'), LLDB_PYTHON_LIBRARY: join(python, 'Python'), LLDB_DEBUGSERVER_PATH: join(root, 'bin/debugserver'), PYTHONNOUSERSITE: '1', PYTHONDONTWRITEBYTECODE: '1' } };
+}
+export function ghidraDebuggerInstaller(c) {
+    return new ToolInstaller(c, {
+        id: 'ghidra-debugger', primary: 'lldb', components: () => {
+            if (!managedGhidraDebugger())
+                fail('unsupported', 'The managed Ghidra LLDB/Python backend requires macOS 15+ ARM64.');
+            return { lldb: catalogArtifact('0f9e88490490fb2f487ad6f02d7aea774629a2839a10497fdcbaad9c6481c839') };
+        }, launch: roots => ghidraDebuggerLaunch(roots.lldb), probe: async (launch) => {
+            const result = await runTool(c, { tool: 'ghidra-debugger', role: 'doctor', executable: launch.executable, arguments: ['--no-lldbinit', '--batch', '-o', 'script import lldb,sys; print("INSIGHT_LLDB_PYTHON_OK",lldb.SBDebugger.GetVersionString(),sys.version_info[:2])'], environment: { ...launch.environment, PATH: '/usr/bin:/bin' }, timeoutMs: 30000, maxOutputBytes: 65536, nativeDeadline: true });
+            if (!result.stdout.includes('INSIGHT_LLDB_PYTHON_OK lldb version 23.1.3 (3, 15)'))
+                fail('configuration', 'The managed debugger must load LLDB 23.1.3 and its own Python 3.15.');
+            return { version: '23.1.3', python: '3.15', backend: 'managed-lldb', hostHomebrewRequired: false };
+        }
+    });
+}
+export async function prepareGhidraDebugger(c, o = {}) {
+    const installer = ghidraDebuggerInstaller(c);
+    if (o.archive || (await installer.status()).state !== 'installed')
+        await installer.install(o);
+    return installer.selected();
+}

package/dist/src/ghidra-processes.d.ts

@@ -0,0 +1,6 @@
+import type { CommandContext } from '@eyeauras/cli-factory';
+import { type ProcessRecord } from './tool-runtime/supervisor.js';
+import type { ToolProcessHooks } from './tool-runtime/commands.js';
+import type { Scope, Workspace } from './workspace.js';
+export declare function verifyGhidraProcess(r: ProcessRecord, c: CommandContext): Promise<boolean | undefined>;
+export declare function ghidraProcessHooks(workspace: (c: CommandContext) => Workspace, close: (scope: Scope, c: CommandContext) => Promise<unknown>): ToolProcessHooks;

package/dist/src/ghidra-processes.js

@@ -0,0 +1,121 @@
+import { runtimeSelection } from './runtime-selection.js';
+import { join, resolve, relative, sep } from 'node:path';
+import { readFile, readdir, realpath } from 'node:fs/promises';
+import { serverIdentity, stopLocalServer } from './server.js';
+import { HttpBridge } from './transport.js';
+import { registerExistingProcess } from './tool-runtime/supervisor.js';
+import { fail } from './model.js';
+async function ownedPath(c, path) {
+    if (typeof path !== 'string')
+        fail('binding', 'Tool resource moved outside this profile.');
+    const supplied = resolve(path), profile = resolve(c.appArguments.AppDataDirectory), canonical = await realpath(profile);
+    const base = supplied.startsWith(profile + sep) ? profile : supplied.startsWith(canonical + sep) ? canonical : undefined;
+    if (!base)
+        fail('binding', 'Tool resource moved outside this profile.');
+    // Keep Factory's raw AppData identity in process records, but compare native resources
+    // under its canonical profile. Accept the parent alias, never a replaced child link.
+    const expected = join(canonical, relative(base, supplied));
+    if (await realpath(supplied) !== expected)
+        fail('binding', 'Tool resource moved outside this profile.');
+    return expected;
+}
+export async function verifyGhidraProcess(r, c) {
+    try {
+        if (r.metadata?.serverDirectory) {
+            const directory = await ownedPath(c, r.metadata.serverDirectory), local = JSON.parse(await readFile(join(directory, 'server/local.json'), 'utf8'));
+            return Number((await serverIdentity(local, c)).pid) === r.pid;
+        }
+        if (r.metadata?.debuggerReceipt) {
+            const path = await ownedPath(c, r.metadata.debuggerReceipt), row = JSON.parse(await readFile(path, 'utf8')), root = await ownedPath(c, r.metadata.contextRoot), binding = JSON.parse(await readFile(join(root, 'process.json'), 'utf8'));
+            if (row.root !== root || row.ownerToken !== binding.tokenSecret || row.guiPid !== binding.pid || !Number.isSafeInteger(row.identityPort) || row.identityPort < 1 || row.identityPort > 65535)
+                return false;
+            const token = await c.secrets.require(binding.tokenSecret), response = await c.fetch('http://127.0.0.1:' + row.identityPort + '/identity', { redirect: 'error', signal: AbortSignal.timeout(1000), headers: { Authorization: 'Bearer ' + token } });
+            const body = await response.text();
+            if (!response.ok || body.length > 4096)
+                return false;
+            const info = JSON.parse(body);
+            return info.id === row.id && info.pid === row.supervisorPid && (r.role === 'debugger' ? info.childPid === r.pid : info.pid === r.pid);
+        }
+        if (r.metadata?.contextRoot) {
+            const root = await ownedPath(c, r.metadata.contextRoot), binding = JSON.parse(await readFile(join(root, 'process.json'), 'utf8'));
+            if (binding.root !== root || binding.pid !== r.pid || binding.runtimeFingerprint !== r.installation || binding.target !== r.target)
+                return false;
+            const token = await c.secrets.require(binding.tokenSecret), info = await new HttpBridge(binding.endpoint, c.fetch, undefined, token, 1500).instance();
+            return info.pid === r.pid && info.tcp_port === Number(new URL(binding.endpoint).port) && String(info.project_path ?? '').startsWith(root + sep);
+        }
+        return undefined;
+    }
+    catch {
+        return false;
+    }
+}
+export function ghidraProcessHooks(workspace, close) {
+    return {
+        verify: verifyGhidraProcess,
+        async discover(c) {
+            const directory = c.appArguments.AppDataDirectory, executable = runtimeSelection(directory)?.java ?? String(c.profile.values.java ?? 'unverified-legacy-executable');
+            async function walk(path, depth = 0) {
+                if (depth > 6)
+                    return;
+                let entries;
+                try {
+                    entries = await readdir(path, { withFileTypes: true });
+                }
+                catch (e) {
+                    if (e.code === 'ENOENT')
+                        return;
+                    throw e;
+                }
+                for (const entry of entries) {
+                    const at = join(path, entry.name);
+                    if (entry.isDirectory())
+                        await walk(at, depth + 1);
+                    else if (entry.name === 'process.json') {
+                        const b = JSON.parse(await readFile(at, 'utf8'));
+                        if (b.toolProcessId || !b.pid)
+                            continue;
+                        let session;
+                        if (b.context)
+                            session = workspace(c).contextById(b.context).session;
+                        try {
+                            await registerExistingProcess(directory, { tool: 'ghidra', role: b.mode === 'gui' ? 'gui' : b.kind, installation: b.runtimeFingerprint, target: b.target, session, metadata: { contextRoot: b.root } }, executable, b.pid, r => verifyGhidraProcess(r, c));
+                        }
+                        catch { }
+                    }
+                }
+            }
+            await walk(join(directory, 'workspace/ghidra-native'));
+            try {
+                const b = JSON.parse(await readFile(join(directory, 'workspace/server/local.json'), 'utf8'));
+                if (!b.toolProcessId && b.pid)
+                    await registerExistingProcess(directory, { tool: 'ghidra', role: 'server', installation: 'legacy', metadata: { serverDirectory: join(directory, 'workspace') } }, executable, b.pid, r => verifyGhidraProcess(r, c));
+            }
+            catch { }
+        },
+        async stop(r, c) {
+            if (r.metadata?.contextRoot) {
+                if (!r.session || !r.target)
+                    fail('busy', 'Internal Ghidra task is active; finish it before stopping its process.');
+                await close({ session: r.session, target: r.target }, c);
+            }
+            else if (r.role === 'server') {
+                const { runtimeProcesses } = await import('./runtime-manager.js');
+                if ((await runtimeProcesses(c.appArguments.AppDataDirectory)).some(p => p.kind !== 'server'))
+                    fail('busy', 'Close Ghidra contexts before stopping their server.');
+                await stopLocalServer(await ownedPath(c, r.metadata?.serverDirectory), c);
+            }
+        },
+        async beforeKill(r, c) {
+            // Save debugger traces and terminate the inferior through the existing authenticated GUI
+            // protocol. A generic signal to LLDB cannot establish that its debuggee has exited.
+            if (r.role === 'gui' && r.session && r.target) {
+                const scope = { session: r.session, target: r.target }, w = workspace(c), context = w.context(scope);
+                const debuggerActive = context.debugger?.connected || context.debugger?.traces.some(t => t.connected) || w.unresolved(scope).some(q => q.execution?.kind === 'debugger');
+                if (debuggerActive)
+                    await close(scope, c);
+            }
+            if (r.role.startsWith('debugger'))
+                fail('blocked', 'Close the owning GUI context to verify debugger and inferior cleanup.');
+        },
+    };
+}

package/dist/src/ghidra.js

@@ -1,6 +1,6 @@
-import { promisify } from 'node:util';
+import { runTool } from './tool-runtime/run.js';
+import { launchProcess } from './tool-runtime/supervisor.js';
 import { fileURLToPath } from 'node:url';
-import { spawn, execFile } from 'node:child_process';
 import { createHash, randomUUID } from 'node:crypto';
 import { mkdir, open, readFile, readdir, cp, realpath, stat } from 'node:fs/promises';
 import { join, delimiter, resolve, isAbsolute, sep } from 'node:path';
@@ -89,7 +89,7 @@ export class GhidraRuntime {
         if (bridgeSecret && bridgeToken)
             await this.context.secrets.set(bridgeSecret, bridgeToken);
         const log = await open(join(root, 'process.log'), 'a', 0o600);
-        const child = spawn(java, ['-Xmx768m', '-Djava.awt.headless=true', '-Dghidra.home=' + home, '-Dapplication.name=GhidraMCP', '-Duser.home=' + root, '-Djava.io.tmpdir=' + root, '-cp', jars.join(delimiter), 'com.xebyte.headless.GhidraMCPHeadlessServer', '--bind', '127.0.0.1', '--port', String(port)], {
+        const child = await launchProcess(this.context.appArguments.AppDataDirectory, { tool: 'ghidra', role: 'prototype-' + role, installation: expected }, java, ['-Xmx768m', '-Djava.awt.headless=true', '-Dghidra.home=' + home, '-Dapplication.name=GhidraMCP', '-Duser.home=' + root, '-Djava.io.tmpdir=' + root, '-cp', jars.join(delimiter), 'com.xebyte.headless.GhidraMCPHeadlessServer', '--bind', '127.0.0.1', '--port', String(port)], {
             cwd: root, detached: true, stdio: ['ignore', log.fd, log.fd], windowsHide: true,
             env: { PATH: this.context.environment.PATH ?? process.env.PATH, HOME: root, TMPDIR: root, XDG_RUNTIME_DIR: this.directory,
                 GHIDRA_SERVER_HOST: url.hostname, GHIDRA_SERVER_PORT: url.port || '13100', GHIDRA_SERVER_USER: user, GHIDRA_SERVER_PASSWORD: password,
@@ -295,9 +295,9 @@ export class GhidraRuntime {
         const script = fileURLToPath(new URL('../../references/InsightRepositoryProbe.java', import.meta.url));
         let stdout;
         try {
-            ({ stdout } = await promisify(execFile)(java, ['-Djava.awt.headless=true', '-Dghidra.home=' + home, '-Duser.home=' + root, '-Djava.io.tmpdir=' + root, '-cp', jars.join(delimiter), '--source', '21', script, t.repository, t.programPath, role], {
-                cwd: root, timeout: 30000, maxBuffer: 262144, signal: this.context.signal,
-                env: { PATH: process.env.PATH, HOME: root, TMPDIR: root, GHIDRA_SERVER_HOST: url.hostname, GHIDRA_SERVER_PORT: url.port || '13100', GHIDRA_SERVER_USER: text(values[role === 'reader' ? 'readerUser' : 'publisherUser']), GHIDRA_SERVER_PASSWORD: password }
+            ({ stdout } = await runTool(this.context, { tool: 'ghidra', role: 'prototype-authority', executable: java, arguments: ['-Djava.awt.headless=true', '-Dghidra.home=' + home, '-Duser.home=' + root, '-Djava.io.tmpdir=' + root, '-cp', jars.join(delimiter), '--source', '21', script, t.repository, t.programPath, role],
+                cwd: root, timeoutMs: 30000, maxOutputBytes: 262144,
+                environment: { PATH: process.env.PATH, HOME: root, TMPDIR: root, GHIDRA_SERVER_HOST: url.hostname, GHIDRA_SERVER_PORT: url.port || '13100', GHIDRA_SERVER_USER: text(values[role === 'reader' ? 'readerUser' : 'publisherUser']), GHIDRA_SERVER_PASSWORD: password }
             }));
         }
         catch {

package/dist/src/ilspy.d.ts

@@ -0,0 +1,7 @@
+import { type CommandContext, type CommandDefinition } from '@eyeauras/cli-factory';
+import { type ToolArtifact } from './tool-runtime/definition.js';
+import { ToolInstaller } from './tool-runtime/installer.js';
+import type { Workspace } from './workspace.js';
+export declare function ilspyComponents(platform?: string, architecture?: NodeJS.Architecture): Record<string, ToolArtifact>;
+export declare function ilspyInstaller(c: CommandContext): ToolInstaller;
+export declare function ilspyCommands(workspace: (c: CommandContext) => Workspace): CommandDefinition[];

package/dist/src/ilspy.js

@@ -0,0 +1,122 @@
+import { textWindow } from './text-window.js';
+import { number } from './research.js';
+import { managedMetadataCommands } from './managed-metadata.js';
+import { command, Permission } from '@eyeauras/cli-factory';
+import { join, resolve, dirname, relative, sep } from 'node:path';
+import { mkdir, writeFile, readdir, lstat, copyFile } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { defineTool, lifecycleCommands } from './tool-runtime/definition.js';
+import { ToolInstaller } from './tool-runtime/installer.js';
+import { catalogArtifact } from './tool-runtime/catalog.js';
+import { dotnetArtifact, dotnetLaunch } from './tool-runtime/dotnet.js';
+import { runTool } from './tool-runtime/run.js';
+import { fail, text, id } from './model.js';
+export function ilspyComponents(platform = process.platform, architecture = process.arch) {
+    return { ilspy: catalogArtifact('74c07facaf1850c78a779fc509031f756e1c0de24b1a536f3363d7ef81ce001f'), dotnet: dotnetArtifact(platform, architecture) };
+}
+export function ilspyInstaller(c) {
+    return new ToolInstaller(c, { id: 'ilspy', primary: 'ilspy', components: ilspyComponents,
+        launch: roots => dotnetLaunch(roots.dotnet, join(roots.ilspy, 'ilspycmd.dll')),
+        async probe(launch, context) {
+            const result = await runTool(context, { tool: 'ilspy', role: 'version', executable: launch.executable, arguments: [...launch.arguments, '--disable-updatecheck', '--version'], environment: launch.environment, timeoutMs: 30000, maxOutputBytes: 65536 });
+            if (!/^ilspycmd: 11\.1\.0\.9782\s*$/m.test(result.stdout))
+                fail('configuration', 'The selected executable must provide ilspycmd 11.1.0.9782.');
+            return { version: '11.1.0.9782', runtime: 'private .NET 10.0.13 for managed installations' };
+        },
+    });
+}
+async function exportDirectory(stage, output) {
+    const files = [];
+    let bytes = 0;
+    async function walk(path) {
+        for (const entry of await readdir(path)) {
+            const at = join(path, entry), info = await lstat(at);
+            if (info.isSymbolicLink() || !info.isFile() && !info.isDirectory())
+                fail('binding', 'Tool output contains an unsupported link or special file.');
+            if (files.length > 100000 || (bytes += info.isFile() ? info.size : 0) > 256 * 1024 ** 2)
+                fail('limit', 'ILSpy export exceeds its 100000-file/256-MiB bound.');
+            if (info.isDirectory())
+                await walk(at);
+            else
+                files.push({ name: relative(stage, at), size: info.size });
+        }
+    }
+    await walk(stage);
+    await mkdir(dirname(output), { recursive: true, mode: 0o700 });
+    await mkdir(output, { mode: 0o700 });
+    for (const file of files) {
+        const destination = join(output, file.name);
+        await mkdir(dirname(destination), { recursive: true, mode: 0o700 });
+        await copyFile(join(stage, file.name), destination, constants.COPYFILE_EXCL);
+    }
+    return { outputDirectory: output, files, bytes };
+}
+export function ilspyCommands(workspace) {
+    const installer = (c) => ilspyInstaller(c);
+    const common = [{ flags: '--limit-chars <count>', description: 'Returned Unicode text window (1–32768); file export retains the full bounded native text', defaultValue: 16000 }, { flags: '--offset-chars <count>', description: 'Skip Unicode characters in returned text', defaultValue: 0 }, { flags: '--target <id>', description: 'Reuse an immutable research target' }, { flags: '--session <id>', description: 'Associate an existing research session' },
+        { flags: '--output <path>', description: 'Write a new ordinary file (directory for project/resource)' },
+        { flags: '--timeout-seconds <seconds>', description: 'Execution deadline, from 1 to 1800 seconds', defaultValue: 120 }];
+    const run = (operation, options = []) => command(operation + ' [input]', 'Static .NET ' + operation, async ({ args, options: o }, c) => {
+        const limitChars = number(o.limitChars ?? 16000, 32768, 1), offsetChars = number(o.offsetChars ?? 0, 4 * 1024 ** 2);
+        if (Boolean(args.input) === Boolean(o.target))
+            fail('invalid', 'Supply exactly one input path or --target.');
+        if (o.type && o.member)
+            fail('invalid', 'Choose --type or --member.');
+        const timeout = Number(o.timeoutSeconds);
+        if (!Number.isSafeInteger(timeout) || timeout < 1 || timeout > 1800)
+            fail('invalid', 'timeout-seconds must be from 1 to 1800.');
+        const w = workspace(c), target = args.input ? await w.importTarget(resolve(c.cwd, text(args.input, 4096))) : w.target(id(o.target)), session = o.session === undefined ? undefined : w.session(id(o.session)).id, input = await w.artifacts.verify(target.input);
+        const directory = operation === 'project' || operation === 'resource';
+        if (directory && !o.output)
+            fail('invalid', 'This operation requires --output DIRECTORY.');
+        const stage = directory ? join(c.appArguments.AppDataDirectory, 'runtime/exports', randomUUID()) : undefined;
+        if (stage)
+            await mkdir(stage, { recursive: true, mode: 0o700 });
+        const parameters = ['--disable-updatecheck'];
+        if (operation === 'types') {
+            const kind = o.kind === undefined ? 'c,i,s,d,e' : text(o.kind, 32);
+            if (!/^[cisde](?:,[cisde])*$/.test(kind))
+                fail('invalid', 'kind must be c,i,s,d,e selections.');
+            parameters.push('--list', kind.replaceAll(',', ''));
+        }
+        if (o.type)
+            parameters.push('--type', text(o.type, 4096));
+        if (o.member)
+            parameters.push('--member', text(o.member, 4096));
+        if (operation === 'il')
+            parameters.push('--ilcode');
+        if (operation === 'resources')
+            parameters.push('--list-resources');
+        if (operation === 'resource')
+            parameters.push('--resource', text(o.name, 4096), '--outputdir', stage);
+        if (operation === 'project')
+            parameters.push('--project', '--outputdir', stage);
+        if (operation === 'metadata')
+            parameters.push('--dump-table', text(o.table, 128), '--json');
+        parameters.push(input);
+        return installer(c).use(async (selected) => {
+            const result = await runTool(c, { tool: 'ilspy', role: operation, installation: selected.id, executable: selected.executable, arguments: [...selected.arguments, ...parameters], environment: selected.environment, timeoutMs: timeout * 1000, target: target.id, session });
+            const base = { state: 'completed', target: target.id, inputSha256: target.binarySha256, session, process: result.process, elapsedMs: result.elapsedMs, diagnostics: result.diagnostics, truncated: result.truncated };
+            if (stage) {
+                const output = resolve(c.cwd, text(o.output, 4096));
+                if (output === stage || output.startsWith(stage + sep) || stage.startsWith(output + sep))
+                    fail('invalid', 'Output directory must be outside tool staging.');
+                return { ...base, ...await exportDirectory(stage, output) };
+            }
+            if (o.output) {
+                const output = resolve(c.cwd, text(o.output, 4096));
+                await mkdir(dirname(output), { recursive: true, mode: 0o700 });
+                await writeFile(output, result.stdout, { flag: 'wx', mode: 0o600 });
+                return { ...base, output, bytes: Buffer.byteLength(result.stdout) };
+            }
+            return { ...base, ...textWindow(result.stdout, limitChars, offsetChars, result.truncated) };
+        });
+    }, { permission: Permission.Update, options: [...common, ...options] });
+    const type = { flags: '--type <name>', description: 'Fully qualified type name' }, member = { flags: '--member <id>', description: 'XML member ID or metadata token' };
+    const definition = defineTool({ id: 'ilspy', description: 'Static .NET decompilation with a private runtime', components: [{ id: 'ilspy', version: '11.1.0.9782', artifacts: [], dependencies: ['dotnet'] }, { id: 'dotnet', version: '10.0.13', artifacts: [] }],
+        lifecycle: { download: (o, c) => installer(c).download(Boolean(o.offline)), install: (o, c) => installer(c).install(o), uninstall: (o, c) => installer(c).uninstall(Boolean(o.purgeCache)), doctor: (_o, c) => installer(c).doctor(), status: (_o, c) => installer(c).status() },
+        installOptions: [{ flags: '--archive <path>', description: 'Pinned ILSpy NuGet/zip archive' }, { flags: '--archive-sha256 <sha256>', description: 'Expected ILSpy archive SHA256' }, { flags: '--dotnet-archive <path>', description: 'Private .NET runtime tar.gz/zip' }, { flags: '--dotnet-archive-sha256 <sha256>', description: 'Expected .NET archive SHA256' }, { flags: '--executable <path>', description: 'External compatible ilspycmd executable; never removed' }, { flags: '--offline', description: 'Use only supplied archives and verified cache' }],
+    });
+    return [command('ilspy', definition.description, [...lifecycleCommands(definition), ...managedMetadataCommands(workspace, installer), run('types', [{ flags: '--kind <kinds>', description: 'Comma-separated c,i,s,d,e' }]), run('decompile', [type, member]), run('il', [type]), run('resources'), run('resource', [{ flags: '--name <name>', description: 'Resource name', required: true }]), run('project'), run('metadata', [{ flags: '--table <name>', description: 'Metadata table name or number', required: true }])])];
+}

package/dist/src/lldb.d.ts

@@ -0,0 +1,10 @@
+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 lldbInstaller(c: CommandContext): ToolInstaller;
+export declare function lldbPlan(o: Record<string, unknown>): string[];
+export declare function lldbSnapshot(stdout: string): {
+    inferiorPid: number;
+    lines: string[];
+};
+export declare function lldbCommands(workspace: (c: CommandContext) => Workspace): CommandDefinition[];