@eyeauras/insight-cli 0.2.0 → 0.2.2

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,5 +1,7 @@
+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 { spawn } from 'node:child_process';
 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';
@@ -13,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);
@@ -91,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') };
@@ -117,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;
@@ -192,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))
@@ -731,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 } : {}) }; });
@@ -824,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;

package/dist/src/debugger-supervisor.js

@@ -1,9 +1,13 @@
 /** Internal LLDB child owner. It has no public command or independent product IPC host. */
-import { spawn } from 'node:child_process';
+import { launchProcess, registerExistingProcess } from './tool-runtime/supervisor.js';
+import { createServer } from 'node:http';
 import { readFile, writeFile, mkdir, open, rename, realpath } from 'node:fs/promises';
 import { join, resolve, delimiter } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { HttpBridge } from './transport.js';
+import { callerMonitor } from './debugger-caller.js';
+import { debuggerLaunchArguments } from './debugger-launch.js';
+import { verifyManagedInstallation } from './tool-runtime/installer.js';
 async function main() {
     const root = await realpath(process.argv[2]), binding = JSON.parse(await readFile(join(root, 'process.json'), 'utf8'));
     if (root !== resolve(root) || binding.root !== root || binding.mode !== 'gui' || !Number.isSafeInteger(binding.pid))
@@ -38,6 +42,23 @@ async function main() {
     finally {
         await parent.close();
     } }
+    const appData = process.env.INSIGHT_TOOL_APPDATA, canonicalAppData = appData ? await realpath(appData) : undefined;
+    if (!appData || !canonicalAppData || !root.startsWith(join(canonicalAppData, 'workspace', 'ghidra-native') + '/'))
+        throw Error('Invalid tool profile');
+    if (binding.debuggerRuntime)
+        await verifyManagedInstallation(appData, 'ghidra-debugger', binding.debuggerRuntime);
+    const authority = createServer((req, res) => { if (req.url !== '/identity' || req.headers.authorization !== 'Bearer ' + token) {
+        res.writeHead(403).end();
+        return;
+    } res.setHeader('Content-Type', 'application/json'); res.end(JSON.stringify({ id, pid: process.pid, childPid: receipt.childPid, state: receipt.state })); });
+    await new Promise(ok => authority.listen(0, '127.0.0.1', ok));
+    authority.unref();
+    const address = authority.address();
+    if (!address || typeof address === 'string')
+        throw Error('No debugger identity port');
+    Object.assign(receipt, { identityPort: address.port });
+    const processSpec = { tool: 'ghidra', installation: binding.runtimeFingerprint, target: binding.target, session: binding.session, metadata: { debuggerReceipt: path, debuggerDiagnostics: join(directory, id + '.diagnostic.log'), contextRoot: root, ...(binding.debuggerRuntime ? { debuggerInstallation: binding.debuggerRuntime.id, debuggerFingerprint: binding.debuggerRuntime.fingerprint } : {}) } };
+    const helperProcess = await registerExistingProcess(appData, { ...processSpec, role: 'debugger-supervisor' }, process.execPath, process.pid, async () => true);
     await saved();
     const environment = { ...process.env };
     delete environment.GHIDRA_MCP_AUTH_TOKEN;
@@ -47,14 +68,22 @@ async function main() {
     const python = await realpath(environment.INSIGHT_DEBUGGER_PYTHON ?? '');
     if (!python.startsWith(root + '/debug-python-') || python !== environment.INSIGHT_DEBUGGER_PYTHON)
         throw Error('Owned debugger Python identity changed');
+    let debuggerExecutable = '/usr/bin/lldb';
+    if (binding.debuggerRuntime) {
+        debuggerExecutable = binding.debuggerRuntime.executable;
+        Object.assign(environment, binding.debuggerRuntime.environment);
+        Object.assign(receipt, { debuggerInstallation: binding.debuggerRuntime.id, debuggerFingerprint: binding.debuggerRuntime.fingerprint });
+    }
     environment.PYTHONPATH = python + delimiter + (environment.PYTHONPATH ?? '');
     delete environment.INSIGHT_DEBUGGER_PYTHON;
-    let closing = false, finished = false;
+    let closing = false, finished = false, launchComplete = false;
     process.once('SIGHUP', close);
     process.once('SIGTERM', close);
     // A separate session keeps the GUI terminal's SIGHUP from bypassing our orderly kill.
-    const child = spawn('/usr/bin/lldb', ['--no-lldbinit', '-o', 'settings set auto-confirm true', ...process.argv.slice(3)], { env: environment, detached: true, stdio: ['pipe', 'pipe', 'pipe'] });
-    const exited = new Promise((ok, bad) => { child.once('error', bad); child.once('exit', () => { finished = true; ok(); }); });
+    const launchArguments = process.argv.slice(3), usesGhidra = launchArguments.includes('script import os, ghidralldb');
+    const child = await launchProcess(appData, { ...processSpec, role: 'debugger' }, debuggerExecutable, ['--no-lldbinit', '-o', 'settings set auto-confirm true', '-o', 'settings set target.detach-on-error false', ...debuggerLaunchArguments(launchArguments, launch.stopAtEntry === true, usesGhidra ? python : undefined)], { env: environment, detached: true, stdio: ['pipe', 'pipe', 'pipe'] });
+    launchComplete = true;
+    const exited = child.toolClosed.then(() => { finished = true; });
     void exited.catch(() => { });
     receipt.childPid = child.pid ?? 0;
     receipt.state = 'running';
@@ -87,6 +116,10 @@ async function main() {
     function close() {
         if (closing || finished)
             return;
+        if (!launchComplete) {
+            setTimeout(close, 10).unref();
+            return;
+        }
         closing = true;
         process.stdin.pause();
         child.stdout.unpipe(process.stdout);
@@ -104,13 +137,23 @@ async function main() {
         child.kill('SIGINT'); });
     process.stdin.once('end', close);
     process.stdin.once('error', close);
-    const monitor = setInterval(() => { try {
-        process.kill(binding.pid, 0);
-    }
-    catch (error) {
-        if (error.code === 'ESRCH')
-            close();
-    } }, 250);
+    const observeCaller = callerMonitor(python, command => { if (!closing && !finished)
+        child.stdin.write(command); });
+    let callerDiagnostic = false;
+    const monitor = setInterval(() => {
+        try {
+            process.kill(binding.pid, 0);
+        }
+        catch (error) {
+            if (error.code === 'ESRCH')
+                close();
+        }
+        if (!closing && !finished)
+            void observeCaller().catch(() => { if (!callerDiagnostic) {
+                callerDiagnostic = true;
+                process.stderr.write('Native caller observation failed; its request is retained.\n');
+            } });
+    }, 250);
     try {
         await saved();
         await exited;
@@ -122,13 +165,13 @@ async function main() {
         receipt.inferiorTerminated = result?.id === id && result.inferiorTerminated === true;
         receipt.state = receipt.inferiorTerminated ? 'closed' : 'failed';
         Object.assign(receipt, { exitCode: child.exitCode, signalCode: child.signalCode });
-        if (!receipt.inferiorTerminated)
-            await writeFile(join(directory, id + '.diagnostic.log'), diagnostics, { mode: 0o600 });
+        await writeFile(join(directory, id + '.diagnostic.log'), diagnostics, { mode: 0o600 });
         await saved();
     }
     finally {
         clearInterval(monitor);
         process.stdin.pause();
+        authority.close();
     }
     // Keep a failed child outcome observable; never claim that killing LLDB proves inferior exit.
     process.exitCode = receipt.inferiorTerminated ? 0 : 1;

package/dist/src/debugger.js

@@ -3,7 +3,7 @@ import { resolve } from 'node:path';
 import { scope, address, number } from './research.js';
 import { id, text, object, fail } from './model.js';
 import { selectedOptions } from './arguments.js';
-import { debuggerResult, debuggerProgramMetadata as metadata } from './debugger-results.js';
+import { debuggerResult, debuggerExecutionSettled, debuggerProgramMetadata as metadata } from './debugger-results.js';
 import { setTimeout as delay } from 'node:timers/promises';
 import { randomUUID } from 'node:crypto';
 const lists = ['launch_offers', 'modules', 'list_breakpoints', 'stack_trace'];
@@ -89,7 +89,7 @@ export class Debugger {
                 if (request.state === 'failed' && result.reason === 'disconnected')
                     fail('disconnected', 'Selected trace has no live target.', result);
                 if (request.state === 'failed' && result.reason === 'busy')
-                    fail('busy', 'This context already has a live debug target; use another session for another process.', result);
+                    fail('busy', 'This context still has a connected debugger; close/reopen it or use another session before a new launch.', result);
                 if (request.state === 'failed' && result.reason === 'native_precondition')
                     fail('rejected', 'The native live precondition failed; the target write was not started.', result);
                 fail('unknown', 'Debugger action is retained and is not repeated.', request.result);
@@ -98,7 +98,7 @@ export class Debugger {
             if (operation === 'launch' && (await backend.debuggerSaved(selected)).connected) {
                 const result = { ...selected, state: 'not_started', reason: 'busy' };
                 this.workspace.recordRequest(request.id, 'failed', result);
-                fail('busy', 'This context already has a live debug target; use another session for another process.', result);
+                fail('busy', 'This context still has a connected debugger; close/reopen it or use another session before a new launch.', result);
             }
             const before = debuggerResult('status', {}, await backend.debuggerCall(selected, 'status'));
             if (operation !== 'launch' && object(before).target_connected !== true) {
@@ -125,11 +125,10 @@ export class Debugger {
                 }
                 const value = debuggerResult(operation, p, raw);
                 if (['resume', 'interrupt', 'step'].includes(operation)) {
-                    const wanted = operation === 'resume' ? 'RUNNING' : 'STOPPED';
                     let observed = false;
                     for (let attempt = 0; attempt < 40; attempt++) {
                         const status = object(debuggerResult('status', {}, await backend.debuggerCall(selected, 'status')));
-                        if (status.execution_state === wanted || operation === 'resume' && status.execution_state === 'STOPPED' && BigInt(String(status.snap ?? 0)) > BigInt(String(object(before).snap ?? 0))) {
+                        if (debuggerExecutionSettled(operation, object(before), status)) {
                             observed = true;
                             break;
                         }
@@ -151,11 +150,16 @@ export class Debugger {
                     if (!observed)
                         fail('partial', 'Breakpoint inventory did not verify the action.');
                 }
+                if (operation === 'launch' && p.stop_at_entry === true) {
+                    const stopped = object(debuggerResult('status', {}, await backend.debuggerCall(selected, 'status')));
+                    if (stopped.target_connected !== true || stopped.execution_state !== 'STOPPED')
+                        fail('partial', 'Entry-stop launch did not verify a stopped live target.');
+                }
                 saved = await backend.debuggerSaved(selected);
                 savedSnapshot = await backend.saved(selected);
                 metadataChanged = beforeMetadata !== undefined && beforeMetadata !== await metadata(backend, savedSnapshot);
                 const complexChanges = metadataChanged ? [...context.complexChanges, request.id] : context.complexChanges;
-                const result = { ...selected, state: 'applied', ...(saved.active ? { trace: saved.active } : {}), pendingChanges: context.scalars.length + complexChanges.length, sharedState: context.scalars.length || complexChanges.length ? 'pending' : 'shared', value };
+                const result = { ...selected, state: 'applied', ...(operation === 'launch' && p.stop_at_entry === true ? { stoppedAtEntry: true } : {}), ...(saved.active ? { trace: saved.active } : {}), pendingChanges: context.scalars.length + complexChanges.length, sharedState: context.scalars.length || complexChanges.length ? 'pending' : 'shared', value };
                 this.workspace.completeSavedRequest(selected, request.id, context.generation, { debugger: saved, workingSnapshot: savedSnapshot, complexChanges }, result);
                 return result;
             }
@@ -195,7 +199,7 @@ export function debuggerCommands(service) {
             ...(operation === 'schedule' ? [{ flags: '--schedule <time>', description: 'Parse and validate a native time schedule without executing it', required: true }] : []),
             ...(paged ? [{ flags: '--limit <count>', description: 'Page size 1–100', defaultValue: 50 }, { flags: '--offset <count>', description: 'Page offset', defaultValue: 0 }] : []),
             ...(operation === 'step' ? [{ flags: '--kind <kind>', description: 'into, over or out', defaultValue: 'into' }] : []),
-            ...(operation === 'launch' ? [{ flags: '--args <text>', description: 'Target command-line arguments', defaultValue: '' }, { flags: '--cwd <directory>', description: 'Target working directory (default owned run folder)' },
+            ...(operation === 'launch' ? [{ flags: '--stop-at-entry', description: 'macOS local LLDB: launch stopped at entry for inspection before running' }, { flags: '--args <text>', description: 'Target command-line arguments', defaultValue: '' }, { flags: '--cwd <directory>', description: 'Target working directory (default owned run folder)' },
                 { flags: '--offer <name>', description: 'Launch offer title or configuration name', defaultValue: process.platform === 'win32' ? 'dbgeng' : process.platform === 'darwin' ? 'lldb' : 'gdb' }, { flags: '--timeout-seconds <count>', description: 'Launch wait 1–300 seconds', defaultValue: 60 }] : []), ...(changing ? [request] : [])];
         leaves.push(command(operation.replaceAll('_', '-'), 'Use the selected context debugger', ({ options: o }, c) => {
             const p = {};
@@ -248,6 +252,11 @@ export function debuggerCommands(service) {
                     fail('invalid', 'Step kind must be into, over or out.');
             }
             if (operation === 'launch') {
+                if (o.stopAtEntry === true) {
+                    if (process.platform !== 'darwin' || o.offer !== 'lldb')
+                        fail('unsupported', '--stop-at-entry requires the local macOS lldb offer.');
+                    p.stop_at_entry = true;
+                }
                 if (typeof o.args !== 'string' || o.args.length > 8192 || o.args.includes('\0'))
                     fail('invalid', 'Arguments must be bounded text.');
                 p.args = o.args;

package/dist/src/die.d.ts

@@ -0,0 +1,12 @@
+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 dieInstaller(c: CommandContext): ToolInstaller;
+/** Upstream may append signature errors after its JSON while exiting zero. Never discard them. */
+export declare function dieJson(stdout: string, stderr: string): {
+    data: Record<string, unknown>;
+    diagnostics: string[];
+    complete: boolean;
+};
+export declare function dieFindings(data: Record<string, unknown>): Record<string, string>[];
+export declare function dieCommands(workspace: (c: CommandContext) => Workspace): CommandDefinition[];