@eyeauras/insight-cli 0.2.0 → 0.2.1

package/dist/src/runtime-manager.d.ts

@@ -1,13 +1,14 @@
 import { type CommandContext, type CommandDefinition } from '@eyeauras/cli-factory';
-export declare function runtimeWrite(path: string, value: unknown): Promise<void>;
+import { atomicWrite } from './tool-runtime/store.js';
+export declare const runtimeWrite: typeof atomicWrite;
 /** Passive, conservative inventory: a reused PID blocks deletion; it never grants kill authority. */
 export declare function runtimeProcesses(directory: string): Promise<Record<string, unknown>[]>;
 export declare function externalGhidra(path: string): Promise<string>;
 export declare class RuntimeManager {
     private readonly c;
     readonly directory: string;
-    readonly root: string;
     constructor(c: CommandContext);
+    get root(): string;
     status(): Promise<{
         missing: string[];
         capabilities: {
@@ -16,11 +17,29 @@ export declare class RuntimeManager {
             gui: boolean;
             debugger: {
                 backend: string;
+                runtime: {
+                    retainedStages: string[];
+                    processes: import("./tool-runtime/supervisor.js").ProcessRecord[];
+                    tool: string;
+                    state: string;
+                    mode: string;
+                    installation: string | undefined;
+                    executable: string | undefined;
+                    components: Record<string, string>;
+                    lastProbe: Record<string, unknown> | undefined;
+                    recommended: string;
+                };
                 requires: string;
                 checkedBy: string;
+            } | {
+                backend: string;
+                requires: string;
+                checkedBy: string;
+                runtime?: undefined;
             } | {
                 backend: string;
                 checkedBy: string;
+                runtime?: undefined;
                 requires?: undefined;
             };
         };
@@ -66,7 +85,12 @@ export declare class RuntimeManager {
     private archive;
     private cleanupProbes;
     install(o: Record<string, unknown>): Promise<{
-        checks: string[];
+        debugger?: {
+            backend: string;
+            installation: string;
+            fingerprint: string;
+        } | undefined;
+        checks: unknown;
         schema: 1;
         mode: "managed" | "external";
         id?: string;

package/dist/src/runtime-manager.js

@@ -1,38 +1,19 @@
-import { command, Permission, CliError } from '@eyeauras/cli-factory';
-import { readFile, mkdir, rename, rm, open, realpath, readdir, stat, cp } from 'node:fs/promises';
-import { existsSync, constants } from 'node:fs';
+import { runTool } from './tool-runtime/run.js';
+import { readFile, mkdir, rename, rm, realpath, readdir, stat, cp } from 'node:fs/promises';
+import { existsSync, realpathSync } from 'node:fs';
 import { join, dirname, resolve, delimiter, basename } from 'node:path';
 import { randomUUID } from 'node:crypto';
-import { execFile } from 'node:child_process';
-import { promisify } from 'node:util';
 import { runtimeRoot, runtimeSelection, runtimeValues } from './runtime-selection.js';
 import { runtimeCatalog } from './runtime-catalog.js';
-import { cacheArtifact, extractArchive, fileSha256 } from './runtime-archives.js';
+import { cacheArtifact, extractArchive, consumeArchive } from './tool-runtime/archives.js';
 import { nativeInputs, nativeHelpers, nativeJvmDirectories, pinnedMcpJar } from './native-inputs.js';
 import { GhidraServer, stopLocalServer } from './server.js';
 import { fail, text, digest, object } from './model.js';
-const exec = promisify(execFile), suffix = process.platform === 'win32' ? '.exe' : '';
-export async function runtimeWrite(path, value) {
-    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
-    const temporary = path + '.new-' + randomUUID(), handle = await open(temporary, 'wx', 0o600);
-    try {
-        await handle.writeFile(JSON.stringify(value, null, 2) + '\n');
-        await handle.sync();
-    }
-    finally {
-        await handle.close();
-    }
-    await rename(temporary, path);
-    if (process.platform !== 'win32') {
-        const parent = await open(dirname(path), 'r');
-        try {
-            await parent.sync();
-        }
-        finally {
-            await parent.close();
-        }
-    }
-}
+import { atomicWrite, installationStage, removeInstallation, withToolLock, assertUnused } from './tool-runtime/store.js';
+import { lifecycleCommands as sharedLifecycle } from './tool-runtime/definition.js';
+import { managedGhidraDebugger, ghidraDebuggerInstaller, prepareGhidraDebugger } from './ghidra-debugger-runtime.js';
+const suffix = process.platform === 'win32' ? '.exe' : '';
+export const runtimeWrite = atomicWrite;
 const live = (pid) => { if (!Number.isSafeInteger(pid) || Number(pid) < 1)
     return false; try {
     process.kill(Number(pid), 0);
@@ -74,7 +55,7 @@ export async function runtimeProcesses(directory) {
                         throw error;
                 }
                 if (!stopped && live(p.pid))
-                    items.push({ kind: p.kind, pid: p.pid, sessionContext: p.context, target: p.target, mode: p.mode });
+                    items.push({ kind: p.kind, pid: p.pid, sessionContext: p.context, ...(typeof p.session === 'string' ? { session: p.session } : {}), target: p.target, mode: p.mode });
             }
         }
     }
@@ -117,12 +98,13 @@ async function findRoot(root, marker, depth = 0) {
 export class RuntimeManager {
     c;
     directory;
-    root;
     constructor(c) {
         this.c = c;
         this.directory = c.appArguments.AppDataDirectory;
-        this.root = runtimeRoot(this.directory);
     }
+    // Canonicalize storage once the profile exists, without creating it for passive status.
+    // Keep the Factory directory for shared process/lock identity and existing run receipts.
+    get root() { return runtimeRoot(existsSync(this.directory) ? realpathSync.native(this.directory) : this.directory); }
     async status() {
         const selected = runtimeSelection(this.directory), values = selected ? runtimeValuesForStatus(selected, this.c.profile.values) : this.c.profile.values;
         const java = typeof values.java === 'string' ? values.java : undefined, home = typeof values.ghidraHome === 'string' ? values.ghidraHome : undefined;
@@ -185,7 +167,7 @@ export class RuntimeManager {
         const processes = await runtimeProcesses(this.directory), server = processes.find(p => p.kind === 'server');
         return { state: missing.length ? 'not_ready' : 'installed', mode: selected?.mode ?? (home || java ? 'external' : 'unconfigured'), recommended: 'managed', ghidraVersion: version, java, ghidraHome: home,
             ...(selected ? { installation: selected.id, fingerprint: selected.fingerprint } : {}), missing, capabilities: { headless: !missing.length, decompiler: !missing.length, gui: !missing.length,
-                debugger: process.platform === 'darwin' ? { backend: 'system-lldb', requires: 'Apple developer tools and OS debugger authorization', checkedBy: 'ghidra doctor' } : { backend: 'host-debugger', checkedBy: 'ghidra doctor' } },
+                debugger: managedGhidraDebugger() ? { backend: 'managed-lldb', runtime: await ghidraDebuggerInstaller(this.c).status(), requires: 'OS debugger authorization', checkedBy: 'ghidra doctor' } : process.platform === 'darwin' ? { backend: 'system-lldb', requires: 'Apple developer tools and OS debugger authorization', checkedBy: 'ghidra doctor' } : { backend: 'host-debugger', checkedBy: 'ghidra doctor' } },
             server: { mode: this.c.profile.values.server ? 'external' : 'local', state: this.c.profile.values.server ? 'configured' : server ? 'running' : 'stopped', ...(server ? { pid: server.pid } : {}) }, processes, installations, retainedStages: stages, lastCheck: lastCheck ? { ...lastCheck, appliesToSelection: lastCheck.fingerprint === selected?.fingerprint && !selected?.uninstalledAt } : undefined,
             storage: { runtime: this.root, research: join(this.directory, 'workspace'), materials: join(this.directory, 'materials') } };
     }
@@ -195,48 +177,15 @@ export class RuntimeManager {
             const path = await cacheArtifact(artifact, cache, this.c.fetch, this.c.signal, offline);
             items.push({ name: artifact.name, path, sha256: artifact.sha256, license: artifact.license });
         }
+        if (managedGhidraDebugger())
+            for (const item of (await ghidraDebuggerInstaller(this.c).download(offline)).items)
+                items.push({ name: 'LLDB/Python', path: item.path, sha256: item.sha256, license: item.license });
         return { state: 'downloaded', ghidraVersion: catalog.ghidraVersion, javaVersion: catalog.javaVersion, items };
     }
     async archive(artifact, provided, checksum, offline) {
         if (provided === undefined)
             return { path: await cacheArtifact(artifact, join(this.root, 'cache'), this.c.fetch, this.c.signal, offline), artifact };
-        const path = await realpath(resolve(this.c.cwd, text(provided, 4096))), cache = join(this.root, 'cache');
-        await mkdir(cache, { recursive: true, mode: 0o700 });
-        const temporary = join(cache, 'local.partial-' + randomUUID());
-        const source = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
-        try {
-            const metadata = await source.stat();
-            if (!metadata.isFile() || metadata.size > 2 * 1024 ** 3)
-                fail('invalid', 'Local runtime archive must be a regular file no larger than two GiB.');
-            const target = await open(temporary, 'wx', 0o600);
-            let size = 0;
-            try {
-                for await (const chunk of source.createReadStream({ autoClose: false })) {
-                    if ((size += chunk.length) > 2 * 1024 ** 3)
-                        fail('limit', 'Local runtime archive grew beyond two GiB.');
-                    await target.writeFile(chunk);
-                }
-                await target.sync();
-            }
-            finally {
-                await target.close();
-            }
-            const hash = await fileSha256(temporary);
-            if (checksum !== undefined && hash !== text(checksum, 64).toLowerCase())
-                fail('binding', 'Local runtime archive differs from its expected SHA256.');
-            const format = (await readMagic(temporary)) === '504b' ? 'zip' : 'tgz', owned = join(cache, hash + '.' + format);
-            if (existsSync(owned)) {
-                if (await fileSha256(owned) !== hash)
-                    fail('binding', 'Existing local-archive cache entry is corrupt; remove it before retrying.');
-            }
-            else
-                await rename(temporary, owned);
-            return { path: owned, artifact: { ...artifact, sha256: hash, format } };
-        }
-        finally {
-            await source.close();
-            await rm(temporary, { force: true });
-        }
+        return consumeArchive(resolve(this.c.cwd, text(provided, 4096)), join(this.root, 'cache'), artifact, checksum === undefined ? undefined : text(checksum, 64), this.c.signal);
     }
     async cleanupProbes() {
         // A killed owner may leave a disposable validation server alive. Its authenticated
@@ -264,34 +213,29 @@ export class RuntimeManager {
         }
     }
     async install(o) {
-        await this.cleanupProbes();
-        if (o.executable && o.archive)
-            fail('invalid', 'Choose --executable or --archive.');
-        if (o.archiveSha256 && !o.archive || o.javaArchiveSha256 && !o.javaArchive)
-            fail('invalid', 'Archive checksum requires its archive path.');
-        const catalog = runtimeCatalog(), offline = Boolean(o.offline), external = o.executable ? await externalGhidra(resolve(this.c.cwd, text(o.executable, 4096))) : undefined;
-        const ghidra = external ? undefined : await this.archive(catalog.ghidra, o.archive, o.archiveSha256, offline);
-        const java = o.java ? await realpath(resolve(this.c.cwd, text(o.java, 4096))) : undefined;
-        if (java && o.javaArchive)
-            fail('invalid', 'Choose --java or --java-archive.');
-        const jdk = java ? undefined : await this.archive(catalog.java, o.javaArchive, o.javaArchiveSha256, offline);
-        const identity = digest({ schema: 1, platform: process.platform, architecture: process.arch, external, java, ghidra: ghidra?.artifact.sha256, jdk: jdk?.artifact.sha256, bridge: pinnedMcpJar });
-        const installation = join(this.root, 'installations', identity), temporary = join(this.root, 'stages', randomUUID());
-        await mkdir(temporary, { recursive: true, mode: 0o700 });
-        let selected, complete = false;
-        try {
-            let inputs;
-            if (existsSync(join(installation, 'ready.json'))) {
-                const receipt = object(JSON.parse(await readFile(join(installation, 'ready.json'), 'utf8')));
-                inputs = await nativeInputs({ ...this.c.profile.values, java: java ?? receipt.java, ghidraHome: external ?? join(installation, 'ghidra') });
-                if (inputs.fingerprint !== receipt.fingerprint)
-                    fail('binding', 'Installed runtime differs from its verified installation receipt.');
-            }
-            else {
-                let ghidraHome = external;
+        return withToolLock(this.directory, 'ghidra', async () => {
+            await assertUnused(this.directory, 'ghidra');
+            await this.cleanupProbes();
+            if (o.executable && o.archive)
+                fail('invalid', 'Choose --executable or --archive.');
+            if (o.archiveSha256 && !o.archive || o.javaArchiveSha256 && !o.javaArchive)
+                fail('invalid', 'Archive checksum requires its archive path.');
+            if (o.debuggerArchiveSha256 && !o.debuggerArchive)
+                fail('invalid', 'Debugger archive checksum requires its archive path.');
+            if ((o.debuggerArchive || o.debuggerArchiveSha256) && !managedGhidraDebugger())
+                fail('unsupported', 'A managed debugger archive requires macOS 15+ ARM64.');
+            const catalog = runtimeCatalog(), offline = Boolean(o.offline), external = o.executable ? await externalGhidra(resolve(this.c.cwd, text(o.executable, 4096))) : undefined;
+            const ghidra = external ? undefined : await this.archive(catalog.ghidra, o.archive, o.archiveSha256, offline);
+            const java = o.java ? await realpath(resolve(this.c.cwd, text(o.java, 4096))) : undefined;
+            if (java && o.javaArchive)
+                fail('invalid', 'Choose --java or --java-archive.');
+            const jdk = java ? undefined : await this.archive(catalog.java, o.javaArchive, o.javaArchiveSha256, offline);
+            const identity = digest({ schema: 1, platform: process.platform, architecture: process.arch, external, java, ghidra: ghidra?.artifact.sha256, jdk: jdk?.artifact.sha256, bridge: pinnedMcpJar });
+            const receipt = await installationStage(this.root, identity, async (temporary, installation) => {
+                let ghidraHome = external, nativeOverlay;
                 if (ghidra) {
                     const extracted = join(temporary, 'ghidra-extract');
-                    await extractArchive(ghidra.path, extracted, ghidra.artifact.format);
+                    await extractArchive(ghidra.path, extracted, ghidra.artifact.format, this.c.signal);
                     const found = await findRoot(extracted, 'Ghidra/application.properties');
                     if (!found)
                         fail('configuration', 'Archive omitted a complete Ghidra installation.');
@@ -301,7 +245,8 @@ export class RuntimeManager {
                     const host = process.arch === 'arm64' ? 'mac_arm_64' : 'mac_x86_64';
                     if (process.platform === 'darwin' && !existsSync(join(ghidraHome, 'Ghidra/Features/Decompiler/os', host, 'decompile'))) {
                         const bottle = await cacheArtifact(catalog.ghidra, join(this.root, 'cache'), this.c.fetch, this.c.signal, offline), nativeRoot = join(temporary, 'native-extract');
-                        await extractArchive(bottle, nativeRoot, 'tgz');
+                        nativeOverlay = catalog.ghidra;
+                        await extractArchive(bottle, nativeRoot, 'tgz', this.c.signal);
                         const nativeHome = join(nativeRoot, catalog.ghidra.root);
                         for (const module of ['Decompiler', 'FileFormats'])
                             await cp(join(nativeHome, 'Ghidra/Features', module, 'os', host), join(ghidraHome, 'Ghidra/Features', module, 'os', host), { recursive: true, errorOnExist: true });
@@ -311,7 +256,7 @@ export class RuntimeManager {
                 let javaPath = java;
                 if (jdk) {
                     const extracted = join(temporary, 'jdk-extract');
-                    await extractArchive(jdk.path, extracted, jdk.artifact.format);
+                    await extractArchive(jdk.path, extracted, jdk.artifact.format, this.c.signal);
                     const home = await findRoot(extracted, 'bin/java' + suffix);
                     if (!home)
                         fail('configuration', 'Java archive omitted a JDK.');
@@ -319,64 +264,56 @@ export class RuntimeManager {
                     await rm(extracted, { recursive: true, force: true });
                     javaPath = join(temporary, 'jdk/bin/java' + suffix);
                 }
-                inputs = await nativeInputs({ ...this.c.profile.values, java: javaPath, ghidraHome });
+                const inputs = await nativeInputs({ ...this.c.profile.values, java: javaPath, ghidraHome }, undefined, this.c);
                 await this.probe(inputs, join(temporary, 'validation'));
                 await rm(join(temporary, 'validation'), { recursive: true, force: true });
                 const receipt = { schema: 1, id: identity, ghidraVersion: inputs.ghidraVersion, fingerprint: inputs.fingerprint, java: java ?? join(installation, 'jdk/bin/java' + suffix), ghidraHome: external ?? join(installation, 'ghidra'),
-                    archives: [...(ghidra ? [{ sha256: ghidra.artifact.sha256, source: o.archive ? 'local' : catalog.ghidra.url }] : []), ...(jdk ? [{ sha256: jdk.artifact.sha256, source: o.javaArchive ? 'local' : catalog.java.url }] : [])], verifiedAt: new Date().toISOString(), checks: ['jdk', 'native-decompiler', 'local-server-reader-publisher-authority'] };
-                await runtimeWrite(join(temporary, 'ready.json'), receipt);
-                await mkdir(dirname(installation), { recursive: true, mode: 0o700 });
-                if (existsSync(installation))
-                    fail('binding', 'Incomplete installation directory is retained; inspect it before removing it.');
-                await rename(temporary, installation);
-                if (process.platform !== 'win32') {
-                    const parent = await open(dirname(installation), 'r');
-                    try {
-                        await parent.sync();
-                    }
-                    finally {
-                        await parent.close();
-                    }
-                }
-            }
-            selected = { schema: 1, mode: external ? 'external' : 'managed', id: identity, ghidraHome: external ?? join(installation, 'ghidra'), java: java ?? join(installation, 'jdk/bin/java' + suffix), fingerprint: inputs.fingerprint, selectedAt: new Date().toISOString() };
+                    archives: [...(nativeOverlay ? [{ sha256: nativeOverlay.sha256, source: nativeOverlay.url }] : []), ...(ghidra ? [{ sha256: ghidra.artifact.sha256, source: o.archive ? 'local' : catalog.ghidra.url }] : []), ...(jdk ? [{ sha256: jdk.artifact.sha256, source: o.javaArchive ? 'local' : catalog.java.url }] : [])], verifiedAt: new Date().toISOString(), checks: ['jdk', 'native-decompiler', 'local-server-reader-publisher-authority'] };
+                return receipt;
+            }, async (receipt) => {
+                const inputs = await nativeInputs({ ...this.c.profile.values, java: receipt.java, ghidraHome: receipt.ghidraHome }, undefined, this.c);
+                if (inputs.fingerprint !== receipt.fingerprint)
+                    fail('binding', 'Installed runtime differs from its verified installation receipt.');
+            }, this.c.signal);
+            const selected = { schema: 1, mode: external ? 'external' : 'managed', id: identity, ghidraHome: String(receipt.ghidraHome), java: String(receipt.java), fingerprint: String(receipt.fingerprint), selectedAt: new Date().toISOString() };
+            const debuggerRuntime = managedGhidraDebugger() ? await prepareGhidraDebugger(this.c, { archive: o.debuggerArchive, archiveSha256: o.debuggerArchiveSha256, offline: o.offline }) : undefined;
             await runtimeWrite(join(this.root, 'selection.json'), selected);
-            complete = true;
-            return { state: 'installed', ...selected, checks: ['jdk', 'native-decompiler', 'local-server-reader-publisher-authority'] };
-        }
-        catch (error) {
-            await runtimeWrite(join(temporary, 'failure.json'), { state: 'failed', code: error instanceof CliError ? error.code : 'installation', message: error instanceof Error ? error.message : 'Runtime installation failed' });
-            if (error instanceof CliError)
-                throw new CliError(error.message, { code: error.code, result: { ...(error.result && typeof error.result === 'object' ? error.result : {}), diagnostics: temporary } });
-            throw error;
-        }
-        finally {
-            if (complete)
-                await rm(temporary, { recursive: true, force: true });
-        }
+            return { state: 'installed', ...selected, checks: receipt.checks, ...(debuggerRuntime ? { debugger: { backend: 'managed-lldb', installation: debuggerRuntime.id, fingerprint: debuggerRuntime.fingerprint } } : {}) };
+        }, this.c.signal);
     }
     async uninstall(purgeCache = false) {
-        await this.cleanupProbes();
-        const selected = runtimeSelection(this.directory);
-        if (!selected)
-            fail('configuration', 'No managed selection exists; externally configured profile paths are never removed.');
-        if (selected.id) {
-            if (!/^[a-f0-9]{64}$/.test(selected.id))
-                fail('binding', 'Invalid installation identity.');
-            await rm(join(this.root, 'installations', selected.id), { recursive: true, force: true });
-        }
-        if (purgeCache)
-            await rm(join(this.root, 'cache'), { recursive: true, force: true });
-        await runtimeWrite(join(this.root, 'selection.json'), { ...selected, uninstalledAt: new Date().toISOString() });
-        // Retain the selection: an explicit external profile must never become an implicit fallback.
-        return { state: 'uninstalled', mode: selected.mode, externalInstallationPreserved: selected.mode === 'external', researchPreserved: true, materialsPreserved: true, cachePreserved: !purgeCache };
+        return withToolLock(this.directory, 'ghidra', async () => {
+            await assertUnused(this.directory, 'ghidra');
+            await this.cleanupProbes();
+            const selected = runtimeSelection(this.directory);
+            if (!selected)
+                fail('configuration', 'No managed selection exists; externally configured profile paths are never removed.');
+            if (purgeCache && selected.id) {
+                const receipt = object(JSON.parse(await readFile(join(this.root, 'installations', selected.id, 'ready.json'), 'utf8')));
+                for (const a of Array.isArray(receipt.archives) ? receipt.archives : []) {
+                    const sha = String(object(a).sha256);
+                    if (!/^[a-f0-9]{64}$/.test(sha))
+                        fail('binding', 'Invalid cached component identity.');
+                    for (const ext of ['zip', 'tgz'])
+                        await rm(join(this.root, 'cache', sha + '.' + ext), { force: true });
+                }
+            }
+            if (managedGhidraDebugger() && (await ghidraDebuggerInstaller(this.c).status()).state === 'installed')
+                await ghidraDebuggerInstaller(this.c).uninstall(purgeCache);
+            if (selected.id)
+                await removeInstallation(this.root, selected.id);
+            await runtimeWrite(join(this.root, 'selection.json'), { ...selected, uninstalledAt: new Date().toISOString() });
+            // Retain the selection: an explicit external profile must never become an implicit fallback.
+            return { state: 'uninstalled', mode: selected.mode, externalInstallationPreserved: selected.mode === 'external', researchPreserved: true, materialsPreserved: true, cachePreserved: !purgeCache };
+        }, this.c.signal);
     }
     async probe(inputs, root) {
         await mkdir(root, { recursive: true, mode: 0o700 });
-        const classes = await nativeHelpers(root, inputs), log = join(root, 'doctor.log');
+        const classes = await nativeHelpers(root, inputs, this.c), log = join(root, 'doctor.log');
         let output;
         try {
-            output = await exec(inputs.java, ['-Djava.awt.headless=true', '-Dghidra.home=' + inputs.ghidraHome, ...nativeJvmDirectories(root), '-cp', classes + delimiter + inputs.classpath, 'InsightRuntimeDoctor'], { cwd: root, env: { PATH: dirname(inputs.java), HOME: root, TMPDIR: root }, timeout: 90000, maxBuffer: 1024 * 1024, signal: this.c.signal });
+            output = await runTool(this.c, { tool: 'ghidra', role: 'doctor', installation: inputs.fingerprint, executable: inputs.java, arguments: ['-Djava.awt.headless=true', '-Dghidra.home=' + inputs.ghidraHome, ...nativeJvmDirectories(root), '-cp', classes + delimiter + inputs.classpath, 'InsightRuntimeDoctor'],
+                cwd: root, environment: { PATH: dirname(inputs.java), HOME: root, TMPDIR: root }, timeoutMs: 90000, maxOutputBytes: 1024 * 1024 });
         }
         catch (error) {
             await runtimeWrite(log, { failure: String(error.stderr ?? error) });
@@ -403,11 +340,19 @@ export class RuntimeManager {
     async doctor() {
         await this.cleanupProbes();
         const root = join(this.root, 'checks', randomUUID()), values = runtimeValues(this.directory, this.c.profile.values);
-        const inputs = await nativeInputs(values), native = await this.probe(inputs, root);
+        const inputs = await nativeInputs(values, undefined, this.c), native = await this.probe(inputs, root);
         let debuggerCheck = { state: 'host_specific' };
-        if (process.platform === 'darwin')
+        if (managedGhidraDebugger())
             try {
-                const checked = await exec('/usr/bin/lldb', ['--no-lldbinit', '--batch', '-o', 'script import lldb,sys; print("INSIGHT_LLDB_PYTHON_OK")'], { env: { PATH: '/usr/bin:/bin', HOME: root, TMPDIR: root }, timeout: 30000, maxBuffer: 65536 });
+                const selected = await ghidraDebuggerInstaller(this.c).selected();
+                debuggerCheck = { ...(await ghidraDebuggerInstaller(this.c).doctor()), backend: 'managed-lldb', installation: selected.id };
+            }
+            catch {
+                debuggerCheck = { state: 'missing', backend: 'managed-lldb', reason: 'Run insight-cli ghidra install to prepare or repair its LLDB/Python runtime' };
+            }
+        else if (process.platform === 'darwin')
+            try {
+                const checked = await runTool(this.c, { tool: 'ghidra', role: 'debugger-doctor', executable: '/usr/bin/lldb', arguments: ['--no-lldbinit', '--batch', '-o', 'script import lldb,sys; print("INSIGHT_LLDB_PYTHON_OK")'], environment: { PATH: '/usr/bin:/bin', HOME: root, TMPDIR: root }, timeoutMs: 30000, maxOutputBytes: 65536 });
                 debuggerCheck = { state: checked.stdout.includes('INSIGHT_LLDB_PYTHON_OK') ? 'ready' : 'missing', backend: 'system-lldb' };
             }
             catch {
@@ -421,24 +366,20 @@ export class RuntimeManager {
     }
 }
 function runtimeValuesForStatus(selection, values) { return { ...values, java: selection.java, ghidraHome: selection.ghidraHome }; }
-async function readMagic(path) { const handle = await open(path, 'r'); try {
-    const b = Buffer.alloc(2);
-    await handle.read(b, 0, 2, 0);
-    return b.toString('hex');
-}
-finally {
-    await handle.close();
-} }
 export function runtimeCommands(exclusive) {
     const source = [{ flags: '--archive <path>', description: 'Local Ghidra zip/tar.gz; missing dependencies are downloaded' },
+        { flags: '--debugger-archive <path>', description: 'Local pinned LLDB/Python runtime archive (macOS 15+ ARM64)' },
+        { flags: '--debugger-archive-sha256 <sha256>', description: 'Expected SHA256 for the supplied debugger runtime archive' },
         { flags: '--archive-sha256 <sha256>', description: 'Expected SHA256 for the supplied Ghidra archive' },
         { flags: '--java-archive <path>', description: 'Local Java 21 JDK zip/tar.gz' },
         { flags: '--java-archive-sha256 <sha256>', description: 'Expected SHA256 for the supplied JDK archive' },
         { flags: '--java <path>', description: 'Use an external Java 21 JDK executable' },
         { flags: '--executable <path>', description: 'Use an external Ghidra launcher or installation directory; never deleted' },
         { flags: '--offline', description: 'Use local archives/cache only; never access the network' }];
-    return [command('download', 'Cache the pinned complete Ghidra/JDK distribution without activation', ({ options: o }, c) => exclusive(c, () => new RuntimeManager(c).download(Boolean(o.offline)), false), { permission: Permission.Update, options: [source.at(-1)] }),
-        command('install', 'Prepare, verify and select a complete runtime, including Ghidra Server', ({ options: o }, c) => exclusive(c, () => new RuntimeManager(c).install(o)), { permission: Permission.Update, options: source }),
-        command('uninstall', 'Remove selected owned runtime files while preserving research and external installations', ({ options: o }, c) => exclusive(c, () => new RuntimeManager(c).uninstall(Boolean(o.purgeCache))), { permission: 'Destructive', options: [{ flags: '--purge-cache', description: 'Also remove owned downloaded archives' }] }),
-        command('doctor', 'Launch a disposable native decompiler and local server probe', (_input, c) => exclusive(c, () => new RuntimeManager(c).doctor(), false), { permission: Permission.Update })];
+    return sharedLifecycle({ id: 'ghidra', description: 'Complete Ghidra runtime', components: [], installOptions: source, lifecycle: {
+            download: (o, c) => exclusive(c, () => new RuntimeManager(c).download(Boolean(o.offline)), false),
+            install: (o, c) => exclusive(c, () => new RuntimeManager(c).install(o)),
+            uninstall: (o, c) => exclusive(c, () => new RuntimeManager(c).uninstall(Boolean(o.purgeCache))),
+            doctor: (_o, c) => exclusive(c, () => new RuntimeManager(c).doctor(), false),
+        } });
 }

package/dist/src/runtime-selection.js

@@ -1,5 +1,5 @@
-import { readFileSync, existsSync } from 'node:fs';
-import { join, isAbsolute } from 'node:path';
+import { readFileSync, existsSync, realpathSync } from 'node:fs';
+import { join, isAbsolute, resolve } from 'node:path';
 import { fail, object } from './model.js';
 export const runtimeRoot = (directory) => join(directory, 'runtime');
 export function runtimeSelection(directory) {
@@ -9,8 +9,25 @@ export function runtimeSelection(directory) {
     const value = object(JSON.parse(readFileSync(path, 'utf8')));
     if (value.schema !== 1 || !['managed', 'external'].includes(String(value.mode)) || typeof value.java !== 'string' || !isAbsolute(value.java) || typeof value.ghidraHome !== 'string' || !isAbsolute(value.ghidraHome) || !/^[a-f0-9]{64}$/.test(String(value.fingerprint)))
         fail('binding', 'Runtime selection receipt is invalid.');
-    if (value.mode === 'managed' && (!/^[a-f0-9]{64}$/.test(String(value.id)) || value.ghidraHome !== join(runtimeRoot(directory), 'installations', String(value.id), 'ghidra')))
-        fail('binding', 'Managed runtime moved outside its owned installation.');
+    if (value.mode === 'managed') {
+        const id = String(value.id), recordedProfile = resolve(value.ghidraHome, '../../../..');
+        if (!/^[a-f0-9]{64}$/.test(id) || value.ghidraHome !== join(runtimeRoot(recordedProfile), 'installations', id, 'ghidra'))
+            fail('binding', 'Managed runtime moved outside its owned installation.');
+        // Workspace resolves AppData physically; older install receipts can retain a profile
+        // alias such as /tmp -> /private/tmp. Accept that same profile, never an inner escape.
+        let profile, recorded, home;
+        try {
+            profile = realpathSync.native(directory);
+            recorded = realpathSync.native(recordedProfile);
+            if (existsSync(value.ghidraHome))
+                home = realpathSync.native(value.ghidraHome);
+        }
+        catch {
+            fail('binding', 'Managed runtime profile ownership could not be verified.');
+        }
+        if (recorded !== profile || home !== undefined && home !== join(runtimeRoot(profile), 'installations', id, 'ghidra'))
+            fail('binding', 'Managed runtime moved outside its owned installation.');
+    }
     return value;
 }
 export function runtimeValues(directory, values) {

package/dist/src/server.d.ts

@@ -10,6 +10,17 @@ export interface ServerBinding {
     readerSecret: string;
     publisherSecret: string;
 }
+interface LocalServer extends ServerBinding {
+    toolProcessId?: string;
+    mode: 'local';
+    instance: string;
+    port: number;
+    identityPort: number;
+    keySecret: string;
+    tokenSecret: string;
+    phase: 'seeded' | 'initialized' | 'running' | 'stopped';
+    pid?: number;
+}
 /** Own local startup; external profiles connect without taking ownership of their server. */
 export declare class GhidraServer {
     readonly directory: string;
@@ -42,5 +53,7 @@ export declare class GhidraServer {
     private identity;
     stop(): Promise<void>;
 }
+export declare function serverIdentity(local: LocalServer, c: CommandContext): Promise<Record<string, unknown>>;
 /** Stop only the authenticated owned server recorded below this workspace/probe root. */
 export declare function stopLocalServer(directory: string, c: CommandContext): Promise<void>;
+export {};

package/dist/src/server.js

@@ -1,5 +1,6 @@
+import { launchProcess, terminateProcess } from './tool-runtime/supervisor.js';
+import { runTool } from './tool-runtime/run.js';
 import { randomUUID, randomBytes, createHash } from 'node:crypto';
-import { spawn } from 'node:child_process';
 import { readFile, mkdir, open, rename, readdir, stat, chmod, realpath } from 'node:fs/promises';
 import { delimiter, dirname, join, resolve } from 'node:path';
 import { createServer } from 'node:net';
@@ -73,48 +74,19 @@ export class GhidraServer {
     async run(label, main, args, environment = {}, input, acceptedCodes = [0], timeoutMilliseconds = 120000) {
         const root = join(this.root(), 'calls', label + '-' + randomUUID());
         await mkdir(root, { recursive: true, mode: 0o700 });
-        const classes = await nativeHelpers(this.directory, this.inputs);
-        const log = await open(join(root, 'diagnostic.log'), 'a', 0o600);
-        const child = spawn(this.inputs.java, ['-Djava.awt.headless=true', '-Dghidra.home=' + this.inputs.ghidraHome,
-            ...nativeJvmDirectories(root), ...nativeExtensionArguments(this.inputs), '-cp', classes + delimiter + this.inputs.classpath, main, ...args], { cwd: root, windowsHide: true, env: { PATH: this.c.environment.PATH ?? process.env.PATH, HOME: root, TMPDIR: root, ...environment }, stdio: ['pipe', 'pipe', log.fd] });
-        const exited = new Promise((resolve, reject) => { child.once('error', reject); child.once('exit', resolve); });
-        exited.catch(() => { });
-        await log.close();
-        let output = '', overflow = false;
-        child.stdout.on('data', chunk => { if (!overflow)
-            output += chunk.toString(); if (Buffer.byteLength(output) > 1024 * 1024) {
-            overflow = true;
-            child.kill('SIGTERM');
-        } });
-        const abort = () => child.kill('SIGTERM');
-        this.c.signal.addEventListener('abort', abort, { once: true });
-        const timer = setTimeout(abort, timeoutMilliseconds);
-        const force = setTimeout(() => { if (child.exitCode === null && child.signalCode === null)
-            child.kill('SIGKILL'); }, timeoutMilliseconds + 5000);
+        const classes = await nativeHelpers(this.directory, this.inputs, this.c);
+        const output = await runTool(this.c, { tool: 'ghidra', role: label, installation: this.inputs.fingerprint, executable: this.inputs.java, arguments: ['-Djava.awt.headless=true', '-Dghidra.home=' + this.inputs.ghidraHome,
+                ...nativeJvmDirectories(root), ...nativeExtensionArguments(this.inputs), '-cp', classes + delimiter + this.inputs.classpath, main, ...args], cwd: root, environment, input, acceptedCodes, timeoutMs: timeoutMilliseconds, maxOutputBytes: 1024 * 1024 });
+        let result;
         try {
-            child.stdin.on('error', () => { });
-            child.stdin.end(input);
-            if (this.c.signal.aborted)
-                abort();
-            const code = await exited;
-            if (code === null || !acceptedCodes.includes(code) || overflow)
-                fail('authorization', 'Native server operation could not be verified; its owned diagnostic stage is retained.');
-            let result;
-            try {
-                result = object(parseDomainJson(output));
-            }
-            catch {
-                fail('malformed', 'Native server operation returned malformed content.');
-            }
-            if (result.error || result.state === 'failed')
-                fail('authorization', 'Native server operation did not establish its outcome.');
-            return result;
+            result = object(parseDomainJson(output.stdout));
         }
-        finally {
-            clearTimeout(timer);
-            clearTimeout(force);
-            this.c.signal.removeEventListener('abort', abort);
+        catch {
+            fail('malformed', 'Native server operation returned malformed content.');
         }
+        if (result.error || result.state === 'failed')
+            fail('authorization', 'Native server operation did not establish its outcome.');
+        return result;
     }
     async credentials(binding, role) {
         const url = new URL(binding.origin);
@@ -358,20 +330,21 @@ export class GhidraServer {
             await this.run('certificate', 'InsightKeytool', [keystore], { INSIGHT_KEYSTORE_PASSWORD: await this.c.secrets.require(local.keySecret) });
             await chmod(keystore, 0o600);
         }
-        const classes = await nativeHelpers(this.directory, this.inputs);
+        const classes = await nativeHelpers(this.directory, this.inputs, this.c);
         const processRoot = join(root, 'processes', randomUUID());
         await mkdir(processRoot, { recursive: true, mode: 0o700 });
         const log = await open(join(processRoot, 'runtime.log'), 'a', 0o600);
-        const child = spawn(this.inputs.java, ['-Djava.awt.headless=true', '-Dghidra.home=' + this.inputs.ghidraHome,
+        const child = await launchProcess(this.c.appArguments.AppDataDirectory, { tool: 'ghidra', role: 'server', installation: this.inputs.fingerprint, metadata: { serverDirectory: this.directory } }, this.inputs.java, ['-Djava.awt.headless=true', '-Dghidra.home=' + this.inputs.ghidraHome,
             ...nativeJvmDirectories(processRoot), '-cp', classes + delimiter + (this.inputs.serverClasspath ?? this.inputs.classpath),
             'InsightServerMain', data, String(local.port), String(local.identityPort), local.instance, keystore], { cwd: processRoot, detached: true, windowsHide: true, env: { PATH: this.c.environment.PATH ?? process.env.PATH, HOME: processRoot, TMPDIR: processRoot,
-                INSIGHT_KEYSTORE_PASSWORD: await this.c.secrets.require(local.keySecret), INSIGHT_SERVER_TOKEN: await this.c.secrets.require(local.tokenSecret) }, stdio: ['ignore', log.fd, log.fd] });
+                INSIGHT_KEYSTORE_PASSWORD: await this.c.secrets.require(local.keySecret), INSIGHT_SERVER_TOKEN: await this.c.secrets.require(local.tokenSecret) }, stdio: ['ignore', log.fd, log.fd] }, { signal: this.c.signal });
         child.on('error', () => { });
         child.unref();
         await log.close();
         if (!child.pid)
             fail('launch', 'Owned local Ghidra server could not be started.');
         this.state.child = child;
+        local.toolProcessId = child.toolProcessId;
         local.pid = child.pid;
         local.phase = 'running';
         await durable(saved, local);
@@ -401,7 +374,7 @@ export class GhidraServer {
     identity(local) { return serverIdentity(local, this.c); }
     async stop() { await stopLocalServer(this.directory, this.c); this.state.child = undefined; this.state.initializing = undefined; }
 }
-async function serverIdentity(local, c) {
+export async function serverIdentity(local, c) {
     const token = await c.secrets.require(local.tokenSecret);
     const response = await c.fetch(`http://127.0.0.1:${local.identityPort}/identity`, { redirect: 'error',
         signal: AbortSignal.timeout(1000), headers: { Authorization: 'Bearer ' + token } });
@@ -448,7 +421,10 @@ export async function stopLocalServer(directory, c) {
         return;
     if (live(local.pid)) {
         await serverIdentity(local, c);
-        process.kill(local.pid, 'SIGTERM');
+        if (local.toolProcessId)
+            await terminateProcess(c.appArguments.AppDataDirectory, local.toolProcessId, false, async (r) => Number((await serverIdentity(local, c)).pid) === r.pid);
+        else
+            process.kill(local.pid, 'SIGTERM');
         for (let i = 0; i < 100 && live(local.pid); i++)
             await delay(50);
         if (live(local.pid))