@eyeauras/insight-cli 0.1.0 → 0.2.1

package/dist/src/cli.js

@@ -1,8 +1,27 @@
+import { captureCommands } from './capture.js';
+import { binaryCommands } from './binary.js';
+import { skillCommand, toolboxCommands } from './toolbox.js';
+import { listProcesses } from './tool-runtime/supervisor.js';
+import { diagnosticsCommands } from './dotnet-diagnostics.js';
+import { fridaCommands } from './frida.js';
+import { mitmproxyCommands } from './mitmproxy.js';
+import { tsharkCommands } from './tshark.js';
+import { dnspyCommands } from './dnspy.js';
+import { procmonCommands } from './procmon.js';
+import { straceCommands } from './strace.js';
+import { windbgCommands } from './windbg.js';
+import { lldbCommands } from './lldb.js';
+import { dieCommands } from './die.js';
+import { llvmCommands } from './llvm.js';
+import { sevenzipCommands } from './sevenzip.js';
+import { ilspyCommands } from './ilspy.js';
+import { toolProcessCommands } from './tool-runtime/commands.js';
+import { ghidraProcessHooks } from './ghidra-processes.js';
+import { withToolLock, toolProfileBusy } from './tool-runtime/store.js';
 import { command, createCli, Permission, CliError, ProfileStore } from '@eyeauras/cli-factory';
 import { join, resolve } from 'node:path';
 import { readFile, readdir } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
 import { Workspace } from './workspace.js';
 import { GhidraContexts } from './contexts.js';
 import { nativeInputs } from './native-inputs.js';
@@ -27,16 +46,47 @@ import { VersionTracking, trackingCommands } from './version-tracking.js';
 import { Extensions, extensionCommands, extensionState, extensionInventoryCommands, managedExtensions } from './extensions.js';
 import { Synchronization, synchronizationCommands } from './sync-policy.js';
 import { artifactsCommands } from './saved-materials.js';
+import { RuntimeManager, runtimeCommands, runtimeProcesses } from './runtime-manager.js';
+import { packageVersion } from './package-version.js';
+import { runtimeSelection } from './runtime-selection.js';
 const bindingFields = ['java', 'ghidraHome', 'mcpJar', 'mcpJarSha256', 'server', 'repository', 'readerUser', 'publisherUser', 'maxContexts', 'debuggerPython', 'windbgDir', 'archiveUrl'];
 class Owner {
     options;
     profiles = new Map();
+    runtimeChanging = new Set();
+    async runtime(c, action, quiescent = true) {
+        const directory = c.appArguments.AppDataDirectory;
+        if (this.runtimeChanging.has(directory))
+            fail('busy', 'Another runtime operation is in progress.');
+        const current = this.profiles.get(directory);
+        if (quiescent && current?.tasks.size)
+            fail('busy', 'Research operations are in progress; finish them before managing the runtime.');
+        this.runtimeChanging.add(directory);
+        try {
+            if (!quiescent)
+                return await action();
+            const processes = await runtimeProcesses(directory);
+            if (processes.length)
+                fail('busy', 'Close Ghidra contexts and stop the owned server before changing or checking the runtime.', { processes });
+            if (current) {
+                await (await current.backend)?.dispose();
+                current.workspace.close();
+                this.profiles.delete(directory);
+            }
+            return await withToolLock(directory, 'ghidra', action, c.signal);
+        }
+        finally {
+            this.runtimeChanging.delete(directory);
+        }
+    }
     constructor(options) {
         this.options = options;
     }
     selected(c) {
         const directory = c.appArguments.AppDataDirectory;
-        const configuration = digest({ profile: Object.fromEntries(bindingFields.map(key => [key, c.profile.values[key]])), extensions: extensionState(join(directory, 'workspace')).modules.filter(m => m.enabled).map(m => [m.name, m.sha256]) });
+        if (this.runtimeChanging.has(directory))
+            fail('busy', 'Runtime preparation is in progress.');
+        const configuration = digest({ runtime: runtimeSelection(directory), profile: Object.fromEntries(bindingFields.map(key => [key, c.profile.values[key]])), extensions: extensionState(join(directory, 'workspace')).modules.filter(m => m.enabled).map(m => [m.name, m.sha256]) });
         let profile = this.profiles.get(directory);
         if (!profile) {
             profile = { workspace: new Workspace(join(directory, 'workspace'), c.profile.name), tasks: new Map(), configuration };
@@ -48,7 +98,7 @@ class Owner {
         const backend = async () => {
             if (!selected.backend)
                 selected.backend = Promise.resolve(this.options.backend ?
-                    this.options.backend(selected.workspace, c) : nativeInputs(c.profile.values, selected.workspace.directory).then(inputs => new GhidraContexts(selected.workspace, inputs, c)))
+                    this.options.backend(selected.workspace, c) : nativeInputs(c.profile.values, selected.workspace.directory, c).then(inputs => new GhidraContexts(selected.workspace, inputs, c)))
                     .catch(error => { selected.backend = undefined; throw error; });
             const result = await selected.backend;
             if (result instanceof GhidraContexts)
@@ -64,6 +114,12 @@ class Owner {
     }
     async invalidateProfile(app) {
         const directory = app.AppDataDirectory, profile = this.profiles.get(directory);
+        if (this.runtimeChanging.has(directory))
+            fail('busy', 'Runtime preparation is in progress; finish it before changing or deleting the profile.');
+        if (toolProfileBusy(directory))
+            fail('busy', 'A tool operation is active.');
+        if ((await listProcesses(directory)).some(r => !['exited', 'failed'].includes(r.state)))
+            fail('busy', 'The profile has active or unverified tool processes.');
         const materials = await readdir(join(directory, 'materials')).catch(error => { if (error.code === 'ENOENT')
             return []; throw error; });
         if (existsSync(join(directory, 'workspace', 'workspace.sqlite')) || materials.length)
@@ -166,6 +222,17 @@ function scopedFailures(entry, owner, parents = []) {
                     if (!selected)
                         return await run(input, c);
                     const services = owner.selected(c);
+                    // First open of an already known target reserves its context inside Research.open.
+                    // Existing contexts still use the command boundary to order automatic sync phases.
+                    if (path[1] === 'open')
+                        try {
+                            services.workspace.context(selected);
+                        }
+                        catch (error) {
+                            if (error instanceof CliError && error.code === 'coordinator.notFound')
+                                return await run(input, c);
+                            throw error;
+                        }
                     return await services.research.boundary(selected, async () => {
                         const excluded = ['open', 'merge', 'refresh', 'sync-policy', 'close', 'changes', 'debugger', 'ui', 'version-tracking', 'archive', 'projects', 'repository', 'server', 'formats', 'libraries', 'plugins'];
                         const eligible = entry.permission !== Permission.ReadOnly && entry.permission !== undefined && !excluded.includes(path[1]) && !['ghidra types archive-export', 'ghidra documentation transfer'].includes(name);
@@ -190,7 +257,7 @@ function scopedFailures(entry, owner, parents = []) {
 export function createDefinition(options = {}) {
     const owner = new Owner(options);
     const definition = {
-        name: 'insight-cli', applicationId: 'insight-cli', version: '0.1.0', description: 'Isolated research contexts and coordinated Ghidra analysis',
+        name: 'insight-cli', applicationId: 'insight-cli', version: packageVersion, description: 'Isolated research contexts and coordinated Ghidra analysis',
         resources: [owner], permissions: { categories: [{ name: 'Destructive', description: 'Explicit deletion or replacement of retained research data', enabledByDefault: false }] }, ...(options.runtime ? { runtime: options.runtime } : {}),
         profile: { fields: fields.map(([name, flags, description]) => ({ name: name, flags: flags, description: description,
                 ...(name === 'maxContexts' ? { normalize: (value) => number(value, 16, 1) } : {}) })) },
@@ -245,15 +312,25 @@ export function createDefinition(options = {}) {
                 await c.secrets.delete('publisherPassword');
             },
         },
-        builtins: [command('skill [name]', 'Locate the installed insight-cli or insight-re skill', ({ args }) => {
-                const name = args.name === undefined ? 'insight-cli' : text(args.name);
-                if (!['insight-cli', 'insight-re'].includes(name))
-                    fail('notFound', 'Unknown skill; choose insight-cli or insight-re.');
-                return { version: '0.1.0', name, path: fileURLToPath(new URL(name === 'insight-re' ? '../../skills/insight-re/SKILL.md' : '../../SKILL.md', import.meta.url)),
-                    skills: ['insight-cli', 'insight-re'] };
-            })],
+        builtins: [skillCommand()],
         commands: [
             ...artifactsCommands(),
+            ...diagnosticsCommands(c => owner.selected(c).workspace),
+            ...llvmCommands(c => owner.selected(c).workspace),
+            ...dieCommands(c => owner.selected(c).workspace),
+            ...lldbCommands(c => owner.selected(c).workspace),
+            ...windbgCommands(c => owner.selected(c).workspace),
+            ...procmonCommands(),
+            ...dnspyCommands(c => owner.selected(c).workspace),
+            ...tsharkCommands(c => owner.selected(c).workspace),
+            ...mitmproxyCommands(c => owner.selected(c).workspace),
+            ...straceCommands(c => owner.selected(c).workspace),
+            ...fridaCommands(c => owner.selected(c).workspace),
+            ...sevenzipCommands(c => owner.selected(c).workspace),
+            ...ilspyCommands(c => owner.selected(c).workspace),
+            ...binaryCommands(c => owner.selected(c).workspace),
+            ...captureCommands(c => owner.selected(c).workspace),
+            ...toolProcessCommands({ ghidra: ghidraProcessHooks(c => owner.selected(c).workspace, (scope, c) => owner.selected(c).lifecycle.change(scope, 'close')) }, toolboxCommands()),
             command('targets', 'Inspect immutable inputs', [
                 command('add <input>', 'Consume input without starting a tool', async ({ args }, c) => targetView(await owner.selected(c).workspace.importTarget(resolve(c.cwd, text(args.input, 4096)))), { permission: Permission.Update }),
                 command('list', 'List known inputs', ({ options: o }, c) => {
@@ -360,7 +437,7 @@ export function createDefinition(options = {}) {
                     }, { permission: Permission.Update, options: [...scoped, at, { flags: '--prototype <signature>', description: 'Complete C prototype', required: true },
                             { flags: '--calling-convention <name>', description: 'Explicit convention supported by the selected compiler specification' }, request] }),
                     command('get', 'Read a function and entry comments', ({ options: o }, c) => owner.selected(c).research.function(scope(o), address(o.address)), { permission: Permission.ReadOnly, options: [...scoped, at] }),
-                    command('decompile', 'Read decompiled function text', ({ options: o }, c) => owner.selected(c).research.function(scope(o), address(o.address), true), { permission: Permission.ReadOnly, options: [...scoped, at] }),
+                    command('decompile', 'Read a bounded Unicode window of one decompiled function', ({ options: o }, c) => owner.selected(c).research.function(scope(o), address(o.address), true, { limit: number(o.limitChars ?? 16000, 32768, 1), offset: number(o.offsetChars ?? 0, 4 * 1024 ** 2) }), { permission: Permission.ReadOnly, options: [...scoped, at, { flags: '--limit-chars <count>', description: 'Return 1–32768 Unicode characters', defaultValue: 16000 }, { flags: '--offset-chars <count>', description: 'Skip Unicode characters in the returned native text', defaultValue: 0 }] }),
                     command('rename', 'Record a saved private name', ({ options: o }, c) => {
                         const name = text(o.name, 512);
                         if (name !== name.trim())
@@ -381,7 +458,7 @@ export function createDefinition(options = {}) {
         ],
     };
     return { ...definition, commands: definition.commands?.map(entry => entry.name === 'ghidra' ?
-            scopedFailures({ ...entry, children: extendQueries(extendQueries(extendQueries(entry.children ?? [], queryCommands(c => owner.selected(c).research)), mutationCommands(c => owner.selected(c).research)), [...sdkCommands(c => owner.selected(c).research), ...sdkFileCommands(c => owner.selected(c).sdkFiles), ...trackingCommands(c => owner.selected(c).tracking), ...crossCommands(c => owner.selected(c).research), ...administrationCommands(c => owner.selected(c).administration),
-                    ...extensionCommands(c => new Extensions(join(c.appArguments.AppDataDirectory, 'workspace'))), ...extensionInventoryCommands(c => owner.selected(c).backend), ...pluginCommands(c => owner.selected(c).ui), ...synchronizationCommands(c => owner.selected(c).synchronization), ...utilityCommands(), ...lifecycleCommands(c => owner.selected(c).lifecycle), ...projectCommands(c => owner.selected(c).projects), ...uiCommands(c => owner.selected(c).ui), ...debuggerCommands(c => owner.selected(c).debugger), ...archiveCommands(c => owner.selected(c).archive)]) }, owner) : entry) };
+            scopedFailures({ ...entry, children: extendQueries(extendQueries(extendQueries(entry.children ?? [], queryCommands(c => owner.selected(c).research)), mutationCommands(c => owner.selected(c).research)), [...sdkCommands(c => owner.selected(c).research), ...sdkFileCommands(c => owner.selected(c).sdkFiles), ...trackingCommands(c => owner.selected(c).tracking), ...crossCommands(c => owner.selected(c).research), ...administrationCommands(c => owner.selected(c).administration, options.backend ? undefined : async (c) => { const status = await new RuntimeManager(c).status(); return status.state === 'not_ready' ? { ...status.server, connected: false, state: 'runtime_not_ready', missing: status.missing } : undefined; }),
+                    ...extensionCommands(c => new Extensions(join(c.appArguments.AppDataDirectory, 'workspace'))), ...extensionInventoryCommands(c => owner.selected(c).backend), ...pluginCommands(c => owner.selected(c).ui), ...synchronizationCommands(c => owner.selected(c).synchronization), ...utilityCommands(), ...runtimeCommands((c, action, quiescent) => owner.runtime(c, action, quiescent)), ...lifecycleCommands(c => owner.selected(c).lifecycle, c => new RuntimeManager(c).status()), ...projectCommands(c => owner.selected(c).projects), ...uiCommands(c => owner.selected(c).ui), ...debuggerCommands(c => owner.selected(c).debugger), ...archiveCommands(c => owner.selected(c).archive)]) }, owner) : entry) };
 }
 export const createInsightCli = (options = {}) => createCli(createDefinition(options));

package/dist/src/contexts.d.ts

@@ -5,14 +5,19 @@ import { GhidraServer } from './server.js';
 import { Workspace, type Scope, type GhidraContext, type ScalarChange, type Publication, type DebuggerState } from './workspace.js';
 import { type Artifact } from './artifacts.js';
 import { HttpBridge } from './transport.js';
+import type { SelectedTool } from './tool-runtime/installer.js';
 export type ToolMode = 'headless' | 'gui';
 interface ProcessBinding {
+    toolProcessId?: string;
     pid: number;
     endpoint: string;
     root: string;
     target: string;
     context?: string;
+    session?: string;
     mode: ToolMode;
+    debuggerPython?: string;
+    debuggerRuntime?: SelectedTool;
     program: string;
     tokenSecret: string;
     runtimeFingerprint: string;

package/dist/src/contexts.js

@@ -1,8 +1,11 @@
-import { spawn } from 'node:child_process';
+import { launchProcess, terminateProcess } from './tool-runtime/supervisor.js';
+import { runTool } from './tool-runtime/run.js';
+import { verifyGhidraProcess } from './ghidra-processes.js';
+import { runtimeProcesses } from './runtime-manager.js';
 import { randomUUID, randomBytes } from 'node:crypto';
 import { mkdir, open, readFile, readdir, rename, link, realpath, copyFile, chmod, writeFile } from 'node:fs/promises';
 import { constants } from 'node:fs';
-import { join, delimiter, sep, resolve } from 'node:path';
+import { join, delimiter, sep, resolve, dirname } from 'node:path';
 import { createServer } from 'node:net';
 import { setTimeout as delay } from 'node:timers/promises';
 import { nativeHelpers, nativeInputs, nativeJvmDirectories, nativeExtensionArguments } from './native-inputs.js';
@@ -12,14 +15,14 @@ import { HttpBridge } from './transport.js';
 import { scriptInventory, scriptPath } from './scripts.js';
 import { logicalPrograms } from './cross-results.js';
 import { uiResult } from './ui-results.js';
-import { execFile } from 'node:child_process';
-import { promisify } from 'node:util';
 import { fileURLToPath } from 'node:url';
+import { readCallerGoal, awaitCaller } from './debugger-caller.js';
 import { debuggerProgramMetadata } from './debugger-results.js';
 import { nativeQueries } from './query-policy.js';
 import { nativeQuery } from './native-queries.js';
 import { sdkWrites } from './sdk-contracts.js';
 import { initialIntent, initializeModel } from './initial-model.js';
+import { managedGhidraDebugger, prepareGhidraDebugger } from './ghidra-debugger-runtime.js';
 const alive = (pid) => {
     try {
         process.kill(pid, 0);
@@ -73,7 +76,16 @@ export class GhidraContexts {
     fork(c) { return new GhidraContexts(this.workspace, this.inputs, c, this.running, this.modelTasks, this.ownedServer.fork(c), this.capacity); }
     directory() { return join(this.workspace.directory, 'ghidra-native'); }
     server() { return this.ownedServer; }
-    async administration(operation, parameters) { return this.server().administration(operation, parameters); }
+    async administration(operation, parameters) {
+        if (operation === 'stop') {
+            if (this.c.profile.values.server)
+                fail('authorization', 'External server lifecycle is owned by its operator. Use server disconnect.');
+            const processes = await runtimeProcesses(dirname(this.workspace.directory));
+            if (processes.some(p => p.kind !== 'server'))
+                fail('busy', 'Close active Ghidra contexts before stopping their server.');
+        }
+        return this.server().administration(operation, parameters);
+    }
     async sdkFile(operation, parameters) { return this.server().sdkFile(operation, parameters); }
     async prepareRoot(kind, target, context) {
         const root = join(this.directory(), kind, context ?? target, randomUUID());
@@ -81,16 +93,19 @@ export class GhidraContexts {
         return root;
     }
     async launch(root, target, kind, program, mode, context, credentials = {}) {
-        if ((await nativeInputs(this.c.profile.values, this.workspace.directory)).fingerprint !== this.inputs.fingerprint)
+        if ((await nativeInputs(this.c.profile.values, this.workspace.directory, this.c)).fingerprint !== this.inputs.fingerprint)
             fail('binding', 'Native runtime inputs changed; stop the owner before using a different build.');
         const endpointPort = await port(), tokenSecret = 'context-' + randomUUID(), token = randomBytes(32).toString('hex');
         await this.c.secrets.set(tokenSecret, token);
-        const classes = await nativeHelpers(this.workspace.directory, this.inputs);
-        let debuggerEnvironment = {};
+        const classes = await nativeHelpers(this.workspace.directory, this.inputs, this.c);
+        let debuggerEnvironment = {}, debuggerPython, debuggerRuntime;
         if (mode === 'gui') {
+            if (managedGhidraDebugger())
+                debuggerRuntime = await prepareGhidraDebugger(this.c);
             const python = join(root, 'debug-python-' + randomUUID());
             await mkdir(python, { mode: 0o700 });
-            const prepared = await promisify(execFile)(this.inputs.java, ['-cp', classes, 'InsightPythonWheels', python, ...this.inputs.debuggerWheels], { timeout: 30000, maxBuffer: 65536 });
+            debuggerPython = python;
+            const prepared = await runTool(this.c, { tool: 'ghidra', role: 'debugger-wheels', installation: this.inputs.fingerprint, executable: this.inputs.java, arguments: ['-cp', classes, 'InsightPythonWheels', python, ...this.inputs.debuggerWheels], timeoutMs: 30000, maxOutputBytes: 65536 });
             if (object(JSON.parse(prepared.stdout)).state !== 'prepared')
                 fail('configuration', 'Owned debugger Python dependencies could not be prepared.');
             debuggerEnvironment = { INSIGHT_DEBUGGER_PYTHON: python, PYTHONPATH: python, PYTHONNOUSERSITE: '1', PYTHONDONTWRITEBYTECODE: '1', PYTHONPYCACHEPREFIX: join(python, 'isolated-cache') };
@@ -107,19 +122,23 @@ export class GhidraContexts {
         const main = mode === 'gui' ? 'InsightGuiMain' : 'InsightHeadlessMain';
         const args = mode === 'gui' ? [root, 'view', String(endpointPort)] : ['--bind', '127.0.0.1', '--port', String(endpointPort)];
         const log = await open(join(root, 'runtime.log'), 'a', 0o600);
-        const child = spawn(this.inputs.java, ['-Xmx768m', '-Djava.awt.headless=' + String(mode !== 'gui'), '-Dghidra.home=' + this.inputs.ghidraHome,
+        let binding;
+        const child = await launchProcess(this.c.appArguments.AppDataDirectory, { tool: 'ghidra', role: mode === 'gui' ? 'gui' : kind, installation: this.inputs.fingerprint, target: target.id, session: context ? this.workspace.contextById(context).session : undefined, metadata: { contextRoot: root } }, this.inputs.java, ['-Xmx768m', '-Djava.awt.headless=' + String(mode !== 'gui'), '-Dghidra.home=' + this.inputs.ghidraHome,
             ...nativeJvmDirectories(root), ...nativeExtensionArguments(this.inputs), '-cp', classes + delimiter + this.inputs.classpath, main, ...args], { cwd: root, detached: true, windowsHide: true, stdio: ['ignore', log.fd, log.fd],
             env: { PATH: this.c.environment.PATH ?? process.env.PATH, HOME: root, TMPDIR: root, XDG_RUNTIME_DIR: root,
-                GHIDRA_MCP_AUTH_TOKEN: token, GHIDRA_MCP_FILE_ROOT: root, GHIDRA_MCP_SHARED_PROJECT_DIR: root,
-                GHIDRA_MCP_ALLOW_SCRIPTS: '1', ...debuggerEnvironment, ...credentials } });
+                INSIGHT_TOOL_APPDATA: this.c.appArguments.AppDataDirectory, GHIDRA_MCP_AUTH_TOKEN: token, GHIDRA_MCP_FILE_ROOT: root, GHIDRA_MCP_SHARED_PROJECT_DIR: root,
+                GHIDRA_MCP_ALLOW_SCRIPTS: '1', ...debuggerEnvironment, ...credentials } }, { signal: this.c.signal, onSpawn: async (spawned) => {
+                if (!spawned.pid)
+                    fail('launch', 'Owned context did not obtain a PID.');
+                binding = { toolProcessId: spawned.toolProcessId, pid: spawned.pid, endpoint: `http://127.0.0.1:${endpointPort}`, root, ...(debuggerPython ? { debuggerPython } : {}), ...(debuggerRuntime ? { debuggerRuntime } : {}), target: target.id,
+                    ...(context ? { context, session: this.workspace.contextById(context).session } : {}), kind, mode, program, tokenSecret, runtimeFingerprint: this.inputs.fingerprint };
+                await durable(join(root, 'process.json'), binding);
+            } });
         child.on('error', () => { });
         child.unref();
         await log.close();
         if (!child.pid)
             fail('launch', 'Owned Ghidra context could not be launched.');
-        const binding = { pid: child.pid, endpoint: `http://127.0.0.1:${endpointPort}`, root, target: target.id,
-            ...(context ? { context } : {}), kind, mode, program, tokenSecret, runtimeFingerprint: this.inputs.fingerprint };
-        await durable(join(root, 'process.json'), binding);
         const record = { binding, http: new HttpBridge(binding.endpoint, this.c.fetch, this.c.signal, token), child };
         this.running.set(root, record);
         const deadline = Date.now() + 90000;
@@ -182,7 +201,10 @@ export class GhidraContexts {
                 const token = await this.c.secrets.require(binding.tokenSecret), http = new HttpBridge(binding.endpoint, this.c.fetch, new AbortController().signal, token, 60000);
                 await this.debuggerHelperRecord({ ...record, http }, 'Stop', 'INSIGHT_DEBUGGER_STOPPED');
             }
-            process.kill(binding.pid, 'SIGTERM');
+            if (binding.toolProcessId)
+                await terminateProcess(this.c.appArguments.AppDataDirectory, binding.toolProcessId, false, r => verifyGhidraProcess(r, this.c));
+            else
+                process.kill(binding.pid, 'SIGTERM');
             for (let i = 0; i < 100 && alive(binding.pid); i++)
                 await delay(50);
             if (alive(binding.pid))
@@ -721,7 +743,20 @@ public class ${name} extends GhidraScript {
         if (operation === 'read_memory')
             await this.traceHelper(scope, { operation: 'read_memory', address: p.address, size: p.size });
         const token = await this.c.secrets.require(record.binding.tokenSecret), timeout = operation === 'launch' ? (Number(p.timeout_seconds ?? 60) + 90) * 1000 : 45000;
+        const callerPython = process.platform === 'darwin' && operation === 'step' && p.kind === 'out' ? record.binding.debuggerPython : undefined;
+        if (callerPython && (dirname(callerPython) !== record.binding.root || await realpath(callerPython) !== callerPython))
+            fail('binding', 'Native caller Python scope changed.');
+        const priorCaller = callerPython ? await readCallerGoal(callerPython) : undefined;
         const raw = await new HttpBridge(record.binding.endpoint, this.c.fetch, this.c.signal, token, timeout).call('/debugger/' + operation, { ...p, ...(['launch', 'launch_offers', 'static_to_dynamic'].includes(operation) ? { program: record.binding.program } : {}) });
+        if (callerPython) {
+            const goal = await readCallerGoal(callerPython);
+            if (goal && goal.id !== priorCaller?.id) {
+                const launch = object(JSON.parse(await readFile(join(record.binding.root, 'debugger-run', 'current.json'), 'utf8')));
+                if (goal.executable !== launch.executable || launch.context !== record.binding.context || launch.target !== scope.target)
+                    fail('binding', 'Native caller belongs to another launch.');
+                await awaitCaller(callerPython, goal, this.c.signal);
+            }
+        }
         const label = this.workspace.target(scope.target).name;
         if (operation === 'modules' && Array.isArray(raw))
             return raw.map(value => { const row = object(value), { path, ...rest } = row; return { ...rest, ...(typeof row.name === 'string' && (row.name.includes(record.binding.root) || ['image', 'image.exe'].includes(row.name)) ? { name: label } : {}) }; });
@@ -814,8 +849,9 @@ public class ${name} extends GhidraScript {
         const cwd = p.cwd === undefined ? root : text(p.cwd, 4096);
         if (/[\r\n\0]/.test(cwd))
             fail('invalid', 'Debugger working directory must be a single filesystem path.');
-        await durable(join(record.binding.root, 'debugger-run', 'current.json'), { request, target: scope.target, context: record.binding.context, executable, cwd });
-        return this.debuggerCall(scope, 'launch', { ...p, executable_path: executable, cwd,
+        await durable(join(record.binding.root, 'debugger-run', 'current.json'), { request, target: scope.target, context: record.binding.context, executable, cwd, ...(p.stop_at_entry === true ? { stopAtEntry: true } : {}) });
+        const { stop_at_entry, ...parameters } = p;
+        return this.debuggerCall(scope, 'launch', { ...parameters, executable_path: executable, cwd,
             ...(this.c.profile.values.debuggerPython ? { python_executable: text(this.c.profile.values.debuggerPython, 4096) } : {}),
             ...(this.c.profile.values.windbgDir ? { windbg_dir: text(this.c.profile.values.windbgDir, 4096) } : {}) });
     }

package/dist/src/debugger-caller.d.ts

@@ -0,0 +1,17 @@
+export interface CallerGoal {
+    schema: 1;
+    id: string;
+    pid: number;
+    thread: string;
+    pc: string;
+    sp: string;
+    stop: number;
+    executable: string;
+    breakpoint: number;
+}
+export declare function readCallerGoal(python: string): Promise<CallerGoal | undefined>;
+export declare function callerVerified(goal: CallerGoal, value: Record<string, unknown>): boolean;
+export declare function awaitCaller(python: string, goal: CallerGoal, signal?: AbortSignal, budgetMs?: number): Promise<void>;
+/** Runs from the owned LLDB CLI after the MCP action has returned and released its locks. */
+export declare function callerObservationCommand(python: string, goal: CallerGoal, sample: string): string;
+export declare function callerMonitor(python: string, send: (command: string) => void): () => Promise<void>;

package/dist/src/debugger-caller.js

@@ -0,0 +1,129 @@
+/** Private, profile-owned LLDB completion receipts. No CPU operation is retried. */
+import { lstat, open, readFile, realpath, rename } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { setTimeout as delay } from 'node:timers/promises';
+import { fail, object } from './model.js';
+const uuid = /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/;
+const hex = /^0x[a-fA-F0-9]{1,16}$/;
+async function json(path) {
+    try {
+        const stat = await lstat(path);
+        if (!stat.isFile() || stat.size > 16384 || await realpath(path) !== resolve(path))
+            fail('binding', 'Native caller receipt is not an owned regular file.');
+        return object(JSON.parse(await readFile(path, 'utf8')));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+}
+async function atomic(path, value) { const temporary = path + '.new-' + randomUUID(), file = await open(temporary, 'wx', 0o600); try {
+    await file.writeFile(JSON.stringify(value));
+    await file.sync();
+}
+finally {
+    await file.close();
+} await rename(temporary, path); }
+export async function readCallerGoal(python) {
+    const value = await json(join(python, 'caller-goal.json'));
+    if (!value)
+        return;
+    if (value.schema !== 1 || typeof value.id !== 'string' || !uuid.test(value.id) || !Number.isSafeInteger(value.pid) || Number(value.pid) <= 0 || typeof value.thread !== 'string' || !/^\d{1,20}$/.test(value.thread) || BigInt(value.thread) <= 0n || typeof value.pc !== 'string' || !hex.test(value.pc) || typeof value.sp !== 'string' || !hex.test(value.sp) || !Number.isSafeInteger(value.stop) || Number(value.stop) < 0 || typeof value.executable !== 'string' || !Number.isSafeInteger(value.breakpoint) || Number(value.breakpoint) <= 0)
+        fail('binding', 'Native caller goal is malformed.');
+    return value;
+}
+export function callerVerified(goal, value) {
+    return value.schema === 1 && value.goal === goal.id && value.state === 'verified' && value.pid === goal.pid && value.thread === goal.thread && typeof value.pc === 'string' && hex.test(value.pc) && BigInt(value.pc) === BigInt(goal.pc) && typeof value.sp === 'string' && hex.test(value.sp) && BigInt(value.sp) === BigInt(goal.sp) && Number.isSafeInteger(value.stop) && Number(value.stop) > goal.stop;
+}
+export async function awaitCaller(python, goal, signal, budgetMs = 12000) {
+    await atomic(join(python, 'caller-armed.json'), { schema: 1, id: goal.id });
+    const deadline = Date.now() + budgetMs;
+    while (Date.now() < deadline) {
+        signal?.throwIfAborted();
+        const value = await json(join(python, 'caller-observation.json'));
+        if (value?.goal === goal.id) {
+            if (callerVerified(goal, value))
+                return;
+            if (value.state === 'verified' || value.state === 'failed')
+                fail('partial', 'Native caller observation did not verify the requested return.', { goal: goal.id, observation: value });
+        }
+        await delay(Math.min(50, Math.max(1, deadline - Date.now())), undefined, { signal });
+    }
+    fail('partial', 'Native caller was not verified within the action budget; execution was not repeated.', { goal: goal.id });
+}
+/** Runs from the owned LLDB CLI after the MCP action has returned and released its locks. */
+export function callerObservationCommand(python, goal, sample) {
+    const code = [
+        'import lldb,json,os,pathlib',
+        'goal=json.loads(' + JSON.stringify(JSON.stringify(goal)) + ')',
+        'output=pathlib.Path(' + JSON.stringify(join(python, 'caller-observation.json')) + ')',
+        'value={"schema":1,"goal":goal["id"],"sample":' + JSON.stringify(sample) + ',"state":"pending"}',
+        'def inspect_caller():',
+        ' p=lldb.debugger.GetSelectedTarget().GetProcess()',
+        ' if p.GetProcessID()!=goal["pid"]: raise RuntimeError("Native process identity changed")',
+        ' state=p.GetState()',
+        ' if state in (lldb.eStateExited,lldb.eStateDetached,lldb.eStateInvalid): raise RuntimeError("Native target ended before caller verification")',
+        ' if state!=lldb.eStateStopped: return',
+        ' stop=p.GetStopID(); t=p.GetThreadByID(int(goal["thread"])); f=t.GetFrameAtIndex(0)',
+        ' if not f.IsValid(): return',
+        ' pc=f.FindRegister("pc"); sp=f.FindRegister("sp")',
+        ' if not pc.IsValid() or not sp.IsValid() or pc.GetError().Fail() or sp.GetError().Fail(): return',
+        ' value.update(pid=p.GetProcessID(),thread=str(t.GetThreadID()),pc=hex(pc.GetValueAsUnsigned()),sp=hex(sp.GetValueAsUnsigned()),frame_pc=hex(f.GetPC()),stop=stop)',
+        ' if stop<=goal["stop"] or pc.GetValueAsUnsigned()!=int(goal["pc"],16) or sp.GetValueAsUnsigned()!=int(goal["sp"],16) or p.GetState()!=lldb.eStateStopped or p.GetStopID()!=stop: return',
+        ' from ghidralldb import commands',
+        ' client=commands.STATE.require_client(); batch=client.cur_batch',
+        ' value.update(trace_batch_count=batch.count if batch is not None else 0,trace_batch_mutex=client._block.locked())',
+        ' if batch is not None or client._block.locked(): return',
+        ' result=lldb.SBCommandReturnObject()',
+        ' lldb.debugger.GetCommandInterpreter().HandleCommand("ghidra trace sync-synth-stopped",result)',
+        ' if not result.Succeeded(): raise RuntimeError("Native stopped trace could not be synchronized")',
+        ' batch=client.cur_batch',
+        ' value.update(trace_batch_count=batch.count if batch is not None else 0,trace_batch_mutex=client._block.locked())',
+        ' if batch is not None or client._block.locked(): return',
+        ' f=p.GetThreadByID(int(goal["thread"])).GetFrameAtIndex(0)',
+        ' pc=f.FindRegister("pc"); sp=f.FindRegister("sp")',
+        ' if p.GetState()==lldb.eStateStopped and p.GetStopID()==stop and f.IsValid() and pc.IsValid() and sp.IsValid() and pc.GetError().Success() and sp.GetError().Success() and pc.GetValueAsUnsigned()==int(goal["pc"],16) and sp.GetValueAsUnsigned()==int(goal["sp"],16): value["state"]="verified"',
+        'try: inspect_caller()',
+        'except Exception as error: value.update(state="failed",error=str(error)[:1024])',
+        'temporary=str(output)+".new-"+value["sample"]',
+        'fd=os.open(temporary,os.O_CREAT|os.O_EXCL|os.O_WRONLY,0o600)',
+        'try: os.write(fd,json.dumps(value).encode("utf-8")); os.fsync(fd)',
+        'finally: os.close(fd)',
+        'os.replace(temporary,output)',
+    ].join('\n');
+    return 'script exec(' + JSON.stringify(code) + ')\n';
+}
+export function callerMonitor(python, send) {
+    let goalId = '', sample = '', inflight = false, terminal = false, deadline = 0;
+    return async () => {
+        const armed = await json(join(python, 'caller-armed.json'));
+        if (!armed || typeof armed.id !== 'string' || !uuid.test(armed.id))
+            return;
+        const goal = await readCallerGoal(python);
+        if (!goal || goal.id !== armed.id)
+            return;
+        if (goalId !== goal.id) {
+            goalId = goal.id;
+            inflight = false;
+            terminal = false;
+            deadline = Date.now() + 15000;
+        }
+        if (terminal || Date.now() >= deadline)
+            return;
+        if (inflight) {
+            const value = await json(join(python, 'caller-observation.json'));
+            if (value?.goal !== goal.id || value.sample !== sample)
+                return;
+            inflight = false;
+            if (value.state === 'verified' || value.state === 'failed') {
+                terminal = true;
+                return;
+            }
+        }
+        sample = randomUUID();
+        inflight = true;
+        send(callerObservationCommand(python, goal, sample));
+    };
+}

package/dist/src/debugger-launch.d.ts

@@ -0,0 +1,2 @@
+/** Preserve the pinned Ghidra launcher except its one explicit local LLDB run command. */
+export declare function debuggerLaunchArguments(arguments_: readonly string[], stopAtEntry: boolean, ownedPython?: string): string[];

package/dist/src/debugger-launch.js

@@ -0,0 +1,17 @@
+/** Preserve the pinned Ghidra launcher except its one explicit local LLDB run command. */
+export function debuggerLaunchArguments(arguments_, stopAtEntry, ownedPython) {
+    const result = [...arguments_];
+    if (ownedPython) {
+        const imports = result.flatMap((value, index) => index > 0 && ['-o', '--one-line'].includes(result[index - 1]) && value === 'script import os, ghidralldb' ? [index] : []);
+        if (imports.length !== 1)
+            throw Error('Pinned LLDB launcher must supply exactly one adapter import');
+        result[imports[0]] = "script import sys,os; sys.path.insert(0," + JSON.stringify(ownedPython) + "); import ghidralldb,ghidralldb.methods; os._exit(253) if os.path.realpath(ghidralldb.methods.__file__) != " + JSON.stringify(ownedPython + '/ghidralldb/methods.py') + " else None; print('Insight owned LLDB adapter verified')";
+    }
+    if (!stopAtEntry)
+        return result;
+    const launches = result.flatMap((value, index) => index > 0 && ['-o', '--one-line'].includes(result[index - 1]) && value.startsWith('process launch') ? [index] : []);
+    if (launches.length !== 1 || !['process launch', 'process launch --stop-at-entry'].includes(result[launches[0]]))
+        throw Error('Pinned LLDB launcher must supply exactly one supported launch command');
+    result[launches[0]] = 'process launch --stop-at-entry';
+    return result;
+}

package/dist/src/debugger-results.d.ts

@@ -1,4 +1,5 @@
 import type { ResearchBackend } from './research.js';
 import type { Artifact } from './artifacts.js';
+export declare function debuggerExecutionSettled(operation: string, before: Record<string, unknown>, after: Record<string, unknown>): boolean;
 export declare function debuggerProgramMetadata(backend: Pick<ResearchBackend, 'inspect'>, snapshot: Artifact): Promise<string | undefined>;
 export declare function debuggerResult(operation: string, p: Record<string, unknown>, raw: unknown): Record<string, unknown> | Record<string, unknown>[];

package/dist/src/debugger-results.js

@@ -4,6 +4,14 @@ const array = (raw) => { if (!Array.isArray(raw))
     fail('partial', 'Debugger inventory is absent.'); return raw.map(object); };
 const count = (value) => { if (!Number.isSafeInteger(value) || Number(value) < 0)
     fail('partial', 'Debugger count is invalid.'); };
+export function debuggerExecutionSettled(operation, before, after) {
+    if (after.target_connected !== true)
+        return false;
+    const advanced = /^\d+$/.test(String(after.snap)) && /^\d+$/.test(String(before.snap)) && BigInt(String(after.snap)) > BigInt(String(before.snap));
+    if (operation === 'resume')
+        return after.execution_state === 'RUNNING' || after.execution_state === 'STOPPED' && advanced;
+    return after.execution_state === 'STOPPED' && (operation !== 'step' || advanced);
+}
 export async function debuggerProgramMetadata(backend, snapshot) {
     if (!backend.inspect)
         return undefined;