@eyeauras/insight-cli 0.0.0-stage → 0.1.0

package/dist/src/debugger-supervisor.js

@@ -0,0 +1,136 @@
+/** Internal LLDB child owner. It has no public command or independent product IPC host. */
+import { spawn } from 'node:child_process';
+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';
+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))
+        throw Error('Invalid GUI owner');
+    const token = process.env.GHIDRA_MCP_AUTH_TOKEN;
+    if (!token)
+        throw Error('Missing GUI authority');
+    const url = new URL(binding.endpoint);
+    if (url.hostname !== '127.0.0.1' || url.protocol !== 'http:' || !url.port)
+        throw Error('Invalid GUI endpoint');
+    const info = await new HttpBridge(binding.endpoint, fetch, undefined, token, 5000).instance();
+    if (info.pid !== binding.pid || info.tcp_port !== Number(url.port) || !String(info.project_path ?? '').startsWith(root + '/'))
+        throw Error('GUI identity changed');
+    const launch = JSON.parse(await readFile(join(root, 'debugger-run/current.json'), 'utf8'));
+    if (launch.context !== binding.context || launch.target !== binding.target || !String(launch.executable).startsWith(root + '/debugger-run/' + launch.request + '/'))
+        throw Error('Launch identity changed');
+    const directory = join(root, 'debugger-supervisors');
+    await mkdir(directory, { recursive: true, mode: 0o700 });
+    if (await realpath(directory) !== directory)
+        throw Error('Supervisor directory changed');
+    const id = randomUUID(), path = join(directory, id + '.json'), resultPath = join(directory, id + '.result.json');
+    const receipt = { schema: 1, id, root, guiPid: binding.pid, ownerToken: binding.tokenSecret, context: binding.context, target: binding.target, supervisorPid: process.pid, childPid: 0, state: 'starting', inferiorTerminated: false };
+    async function saved() { const temporary = path + '.new', file = await open(temporary, 'w', 0o600); try {
+        await file.writeFile(JSON.stringify(receipt));
+        await file.sync();
+    }
+    finally {
+        await file.close();
+    } await rename(temporary, path); const parent = await open(directory, 'r'); try {
+        await parent.sync();
+    }
+    finally {
+        await parent.close();
+    } }
+    await saved();
+    const environment = { ...process.env };
+    delete environment.GHIDRA_MCP_AUTH_TOKEN;
+    delete environment.GHIDRA_SERVER_PASSWORD;
+    // Ghidra's launcher prepends its source tree to PYTHONPATH. Restore the owned wheel
+    // copy first, including the pinned SBProcess compatibility adapter, before LLDB imports it.
+    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');
+    environment.PYTHONPATH = python + delimiter + (environment.PYTHONPATH ?? '');
+    delete environment.INSIGHT_DEBUGGER_PYTHON;
+    let closing = false, finished = 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(); }); });
+    void exited.catch(() => { });
+    receipt.childPid = child.pid ?? 0;
+    receipt.state = 'running';
+    let diagnostics = '';
+    const capture = (chunk) => { diagnostics = (diagnostics + chunk.toString()).slice(-65536); };
+    child.stdout.on('data', capture);
+    child.stderr.on('data', capture);
+    process.stdout.on('error', () => { });
+    process.stderr.on('error', () => { });
+    child.stdin.on('error', () => { });
+    child.stdout.pipe(process.stdout, { end: false });
+    child.stderr.pipe(process.stderr, { end: false });
+    process.stdin.on('data', data => { if (!closing)
+        child.stdin.write(data); });
+    const code = [
+        'import lldb,json,pathlib,os',
+        'p=lldb.debugger.GetSelectedTarget().GetProcess()',
+        'pid=p.GetProcessID() if p.IsValid() else 0',
+        'state=p.GetState() if p.IsValid() else lldb.eStateInvalid',
+        'done=state in (lldb.eStateInvalid,lldb.eStateUnloaded,lldb.eStateExited)',
+        'error=None',
+        'if not done:',
+        ' e=p.Kill()',
+        ' done=e.Success() and p.GetState()==lldb.eStateExited',
+        ' error=None if done else str(e)',
+        'path=pathlib.Path(' + JSON.stringify(resultPath) + ')',
+        'path.write_text(json.dumps({"id":' + JSON.stringify(id) + ',"pid":pid,"inferiorTerminated":done,"error":error}))',
+        'os.chmod(str(path),0o600)',
+    ].join('\n');
+    function close() {
+        if (closing || finished)
+            return;
+        closing = true;
+        process.stdin.pause();
+        child.stdout.unpipe(process.stdout);
+        child.stderr.unpipe(process.stderr);
+        child.stdout.resume();
+        child.stderr.resume();
+        const commands = 'script exec(' + JSON.stringify(code) + ')\nquit\n';
+        child.stdin.write(commands);
+        setTimeout(() => { if (!finished) {
+            child.kill('SIGINT');
+            child.stdin.write(commands);
+        } }, 3000).unref();
+    }
+    process.once('SIGINT', () => { if (!closing)
+        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);
+    try {
+        await saved();
+        await exited;
+        let result;
+        try {
+            result = JSON.parse(await readFile(resultPath, 'utf8'));
+        }
+        catch { }
+        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 saved();
+    }
+    finally {
+        clearInterval(monitor);
+        process.stdin.pause();
+    }
+    // Keep a failed child outcome observable; never claim that killing LLDB proves inferior exit.
+    process.exitCode = receipt.inferiorTerminated ? 0 : 1;
+}
+await main().catch(() => { process.stderr.write('Owned debugger supervision failed; its context is retained.\n'); process.exitCode = 1; });

package/dist/src/debugger.d.ts

@@ -0,0 +1,21 @@
+import { type CommandContext, type CommandDefinition } from '@eyeauras/cli-factory';
+import { Workspace, type Scope } from './workspace.js';
+import { Research, type ResearchBackend } from './research.js';
+export declare function debuggerWriteInputs(operation: string, p: Record<string, unknown>): void;
+export declare class Debugger {
+    private readonly workspace;
+    private readonly research;
+    private readonly backend;
+    constructor(workspace: Workspace, research: Research, backend: () => Promise<ResearchBackend>);
+    private prepared;
+    read(selected: Scope, operation: string, p: Record<string, unknown>, trace?: string): Promise<{
+        connectionState: string;
+        pendingChanges: number;
+        value: unknown;
+        trace?: string | undefined;
+        session: string;
+        target: string;
+    }>;
+    change(selected: Scope, operation: string, p: Record<string, unknown>, callerId?: string, trace?: string): Promise<unknown>;
+}
+export declare function debuggerCommands(service: (c: CommandContext) => Debugger): CommandDefinition[];

package/dist/src/debugger.js

@@ -0,0 +1,267 @@
+import { command, Permission } from '@eyeauras/cli-factory';
+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 { setTimeout as delay } from 'node:timers/promises';
+import { randomUUID } from 'node:crypto';
+const lists = ['launch_offers', 'modules', 'list_breakpoints', 'stack_trace'];
+const liveWrites = new Set(['write_memory', 'write_register']);
+function traceInteger(value) {
+    const encoded = text(String(value), 32);
+    if (!/^-?\d+$/.test(encoded))
+        fail('invalid', 'Trace positions require exact signed decimal integers.');
+    const n = BigInt(encoded);
+    if (n < -(1n << 63n) || n >= (1n << 63n))
+        fail('invalid', 'Trace position exceeds signed 64-bit range.');
+    return n.toString();
+}
+export function debuggerWriteInputs(operation, p) {
+    if (operation === 'write_memory') {
+        for (const key of ['expect_hex', 'bytes_hex'])
+            if (typeof p[key] !== 'string' || !/^(?:[a-f0-9]{2}){1,4096}$/i.test(p[key]))
+                fail('invalid', 'Live memory requires 1–4096 complete hex bytes.');
+        if (String(p.expect_hex).length !== String(p.bytes_hex).length)
+            fail('invalid', 'Live memory expected/replacement lengths must match.');
+    }
+    if (operation === 'write_register')
+        for (const key of ['expect_value', 'value'])
+            if (!/^(?:0x)?[a-f0-9]{1,128}$/i.test(String(p[key])))
+                fail('invalid', 'Register values must be exact unsigned hex integers.');
+}
+export class Debugger {
+    workspace;
+    research;
+    backend;
+    constructor(workspace, research, backend) {
+        this.workspace = workspace;
+        this.research = research;
+        this.backend = backend;
+    }
+    async prepared(selected, trace, reading = false) {
+        const backend = await this.backend(), unresolved = this.workspace.unresolved(selected);
+        if (!backend.debuggerCall || !backend.debuggerStart || !backend.debuggerSaved)
+            fail('configuration', 'Selected backend lacks debugger support.');
+        if (unresolved.length) {
+            if (!reading || unresolved.some(request => object(request.execution ?? {}).kind !== 'debugger'))
+                fail('blocked', 'Selected context retains an unresolved operation.');
+        }
+        else {
+            await backend.open(selected);
+            await backend.mode(selected, 'gui');
+            await backend.debuggerStart(selected);
+        }
+        if (trace) {
+            if (!backend.debuggerSelect || !this.workspace.context(selected).debugger?.traces.some(item => item.id === trace))
+                fail('notFound', 'Trace is not saved in the selected context.');
+            await backend.debuggerSelect(selected, trace);
+        }
+        return backend;
+    }
+    async read(selected, operation, p, trace) {
+        return this.research.ordered(selected, async () => {
+            const backend = await this.prepared(selected, trace, true);
+            let value;
+            if (operation !== 'traces')
+                value = debuggerResult(operation, p, await backend.debuggerCall(selected, operation, Object.fromEntries(Object.entries(p).filter(([key]) => !['limit', 'offset'].includes(key)))));
+            const saved = await backend.debuggerSaved(selected), current = this.workspace.context(selected), snapshot = await backend.saved(selected);
+            const changed = current.workingSnapshot && await metadata(backend, current.workingSnapshot) !== await metadata(backend, snapshot);
+            const complexChanges = changed ? [...current.complexChanges, 'debugger-metadata-' + randomUUID()] : current.complexChanges;
+            this.workspace.saveContext(selected, current.generation, { debugger: saved, workingSnapshot: snapshot, complexChanges });
+            if (operation === 'traces')
+                value = saved.traces.map(row => ({ trace: row.id, name: this.workspace.target(selected.target).name, current: row.id === saved.active, snap: row.snap, module_count: row.modules, thread_count: row.threads, connected: row.connected }));
+            if (operation === 'traces' || lists.includes(operation)) {
+                const rows = value, offset = Number(p.offset ?? 0), limit = Number(p.limit ?? 50);
+                value = { items: rows.slice(offset, offset + limit), total: rows.length, offset, limit, truncated: offset + limit < rows.length };
+            }
+            return { ...selected, ...(saved.active ? { trace: saved.active } : {}), connectionState: saved.connected ? 'connected' : saved.traces.length ? 'disconnected' : 'idle', pendingChanges: current.scalars.length + complexChanges.length, value };
+        });
+    }
+    async change(selected, operation, p, callerId, trace) {
+        const reserved = this.workspace.reserveRequest(selected, 'ghidra.debugger.' + operation, { ...p, ...(trace ? { trace } : {}) }, callerId);
+        return this.research.ordered(selected, async () => {
+            const request = this.workspace.request(reserved.request.id);
+            if (reserved.replay && request.state !== 'accepted') {
+                if (request.state === 'applied')
+                    return request.result;
+                const result = object(request.result ?? {});
+                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);
+                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);
+            }
+            const backend = await this.prepared(selected, trace), context = this.workspace.context(selected);
+            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);
+            }
+            const before = debuggerResult('status', {}, await backend.debuggerCall(selected, 'status'));
+            if (operation !== 'launch' && object(before).target_connected !== true) {
+                const result = { ...selected, state: 'not_started', reason: 'disconnected' };
+                this.workspace.recordRequest(request.id, 'failed', result);
+                fail('disconnected', 'Selected trace has no live target.', result);
+            }
+            const beforeMetadata = context.workingSnapshot ? await metadata(backend, context.workingSnapshot) : undefined;
+            this.workspace.startRequest(request.id, { kind: 'debugger', operation, generation: context.generation, before });
+            let saved, savedSnapshot, metadataChanged = false;
+            try {
+                let raw;
+                if (operation === 'launch') {
+                    if (!backend.debuggerLaunch)
+                        fail('configuration', 'Owned target staging is unavailable.');
+                    raw = await backend.debuggerLaunch(selected, p, request.id);
+                }
+                else
+                    raw = await backend.debuggerCall(selected, operation, p);
+                if (liveWrites.has(operation) && object(raw).status === 'rejected' && object(raw).target_effect_started === false) {
+                    const result = { ...selected, state: 'not_started', reason: 'native_precondition', value: raw };
+                    this.workspace.recordRequest(request.id, 'failed', result);
+                    fail('rejected', 'Native live preconditions rejected the write before target dispatch.', result);
+                }
+                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))) {
+                            observed = true;
+                            break;
+                        }
+                        await delay(100);
+                    }
+                    if (!observed)
+                        fail('partial', 'Debugger execution state did not settle after the action.');
+                }
+                if (operation === 'set_breakpoint' || operation === 'remove_breakpoint') {
+                    let observed = false;
+                    for (let attempt = 0; attempt < 50; attempt++) {
+                        const rows = debuggerResult('list_breakpoints', {}, await backend.debuggerCall(selected, 'list_breakpoints'));
+                        if (rows.some(row => address(row.address) === address(p.address) && Number(row.trace_location_count) > 0) === (operation === 'set_breakpoint')) {
+                            observed = true;
+                            break;
+                        }
+                        await delay(100);
+                    }
+                    if (!observed)
+                        fail('partial', 'Breakpoint inventory did not verify the action.');
+                }
+                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 };
+                this.workspace.completeSavedRequest(selected, request.id, context.generation, { debugger: saved, workingSnapshot: savedSnapshot, complexChanges }, result);
+                return result;
+            }
+            catch (error) {
+                if (this.workspace.request(request.id).state === 'failed')
+                    throw error;
+                try {
+                    saved ??= await backend.debuggerSaved(selected);
+                }
+                catch { }
+                try {
+                    savedSnapshot ??= await backend.saved(selected);
+                    metadataChanged = beforeMetadata !== undefined && beforeMetadata !== await metadata(backend, savedSnapshot);
+                }
+                catch { }
+                this.workspace.recordRequest(request.id, 'unknown', { ...selected, state: 'unknown', operation, ...(saved ? { savedDebugger: saved } : {}), ...(savedSnapshot ? { savedSnapshot, metadataChanged } : {}) });
+                throw error;
+            }
+        });
+    }
+}
+export function debuggerCommands(service) {
+    const leaves = [], request = { flags: '--request-id <id>', description: 'Retrieve the outcome without repeating execution' }, trace = { flags: '--trace <id>', description: 'Select a saved trace within this context' };
+    const operations = ['launch', 'launch_offers', 'status', 'traces', 'resume', 'interrupt', 'step', 'set_breakpoint', 'remove_breakpoint', 'list_breakpoints', 'registers', 'read_memory', 'stack_trace', 'modules', 'static_to_dynamic', 'dynamic_to_static', 'write_memory', 'write_register', 'timeline', 'objects', 'object_values', 'schedule'];
+    for (const operation of operations) {
+        const changing = ['launch', 'resume', 'interrupt', 'step', 'set_breakpoint', 'remove_breakpoint'].includes(operation) || liveWrites.has(operation), at = ['set_breakpoint', 'remove_breakpoint', 'read_memory', 'static_to_dynamic', 'dynamic_to_static', 'write_memory'].includes(operation), paged = operation === 'traces' || lists.includes(operation);
+        const options = [...selectedOptions, ...(operation === 'launch' ? [] : [trace]), ...(at ? [{ flags: '--address <address>', description: 'Explicit static or trace address', required: true }] : []),
+            ...(operation === 'read_memory' ? [{ flags: '--size <bytes>', description: 'Read 1–4096 bytes', defaultValue: 64 }] : []), ...(operation === 'stack_trace' ? [{ flags: '--depth <count>', description: 'Maximum frames 1–1000', defaultValue: 20 }] : []),
+            ...(operation === 'write_memory' ? [{ flags: '--expect-hex <hex>', description: 'Exact current bytes before stopped-target write', required: true }, { flags: '--bytes-hex <hex>', description: 'Equal-length replacement bytes, at most 4096', required: true }] : []),
+            ...(operation === 'write_register' ? [{ flags: '--register <name>', description: 'Exact target platform register', required: true }, { flags: '--expect-value <hex>', description: 'Exact current unsigned hex value', required: true }, { flags: '--value <hex>', description: 'Replacement unsigned hex value within native register width', required: true }] : []),
+            ...(['timeline', 'objects'].includes(operation) ? [{ flags: '--limit <count>', description: 'Maximum returned rows 1–1000', defaultValue: 100 }] : []),
+            ...(operation === 'timeline' ? [{ flags: '--before-snap <integer>', description: 'Latest included snapshot key; result gives next-before-snap' }] : []),
+            ...(operation === 'objects' ? [{ flags: '--path-prefix <text>', description: 'Literal canonical path prefix; @target hides the owned staging root', defaultValue: '' }, { flags: '--max-scan <count>', description: 'Maximum visited objects 1–200000', defaultValue: 10000 }] : []),
+            ...(['objects', 'object_values'].includes(operation) ? [{ flags: '--snap <integer>', description: 'Snapshot key (default selected time)' }] : []),
+            ...(operation === 'object_values' ? [{ flags: '--object-id <integer>', description: 'Object ID returned by objects; scoped to the selected trace', required: true }, { flags: '--key <name>', description: 'Exact native attribute/element key', required: true },
+                { flags: '--from-snap <integer>', description: 'Start of a bounded history range' }, { flags: '--to-snap <integer>', description: 'End of a range of at most 1000 snaps' }] : []),
+            ...(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)' },
+                { 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 = {};
+            if (at)
+                p.address = address(o.address);
+            if (paged) {
+                p.limit = number(o.limit, 100, 1);
+                p.offset = number(o.offset, 2147483647);
+            }
+            if (operation === 'read_memory')
+                p.size = number(o.size, 4096, 1);
+            if (operation === 'stack_trace')
+                p.depth = number(o.depth, 1000, 1);
+            if (operation === 'write_memory') {
+                p.expect_hex = text(o.expectHex, 8192);
+                p.bytes_hex = text(o.bytesHex, 8192);
+            }
+            if (operation === 'write_register') {
+                p.register = text(o.register, 128);
+                p.expect_value = text(o.expectValue, 130);
+                p.value = text(o.value, 130);
+            }
+            if (liveWrites.has(operation))
+                debuggerWriteInputs(operation, p);
+            for (const [key, publicKey] of [['snap', 'snap'], ['before_snap', 'beforeSnap'], ['from_snap', 'fromSnap'], ['to_snap', 'toSnap']])
+                if (o[publicKey] !== undefined)
+                    p[key] = traceInteger(o[publicKey]);
+            if (['timeline', 'objects'].includes(operation))
+                p.limit = number(o.limit, 1000, 1);
+            if (operation === 'objects') {
+                const prefix = typeof o.pathPrefix === 'string' ? o.pathPrefix : '';
+                if (prefix.length > 4096 || prefix.includes('\0'))
+                    fail('invalid', 'Trace path prefix exceeds its text bound.');
+                p.path_prefix = prefix;
+                p.max_scan = number(o.maxScan, 200000, 1);
+            }
+            if (operation === 'object_values') {
+                p.object_id = traceInteger(o.objectId);
+                if (BigInt(String(p.object_id)) < 0n)
+                    fail('invalid', 'Object ID must be nonnegative.');
+                p.key = text(o.key, 1024);
+                if (p.from_snap !== undefined && p.to_snap !== undefined && (BigInt(String(p.to_snap)) < BigInt(String(p.from_snap)) || BigInt(String(p.to_snap)) - BigInt(String(p.from_snap)) > 999n))
+                    fail('invalid', 'Trace value history is bounded to 1000 snaps.');
+            }
+            if (operation === 'schedule')
+                p.schedule = text(o.schedule, 4096);
+            if (operation === 'step') {
+                p.kind = text(o.kind);
+                if (!['into', 'over', 'out'].includes(String(p.kind)))
+                    fail('invalid', 'Step kind must be into, over or out.');
+            }
+            if (operation === 'launch') {
+                if (typeof o.args !== 'string' || o.args.length > 8192 || o.args.includes('\0'))
+                    fail('invalid', 'Arguments must be bounded text.');
+                p.args = o.args;
+                p.offer = text(o.offer, 512);
+                p.timeout_seconds = number(o.timeoutSeconds, 300, 1);
+                if (o.cwd) {
+                    p.cwd = resolve(c.cwd, text(o.cwd, 4096));
+                    if (/[\r\n\0]/.test(String(p.cwd)))
+                        fail('invalid', 'Debugger working directory must be a single filesystem path.');
+                }
+            }
+            const selected = scope(o), selectedTrace = o.trace === undefined ? undefined : id(o.trace);
+            return changing ? service(c).change(selected, operation, p, o.requestId === undefined ? undefined : id(o.requestId), selectedTrace) : service(c).read(selected, operation, p, selectedTrace);
+        }, { permission: operation === 'remove_breakpoint' || liveWrites.has(operation) ? 'Destructive' : changing ? Permission.Update : Permission.ReadOnly, options }));
+    }
+    return [command('debugger', 'Debug the selected immutable target in an owned GUI', leaves)];
+}

package/dist/src/documentation-effects.d.ts

@@ -0,0 +1,5 @@
+import type { ResearchBackend } from './research.js';
+import type { Artifact } from './artifacts.js';
+export declare function verifyDocumentation(backend: ResearchBackend, snapshot: Artifact, p: Record<string, unknown>): Promise<{
+    function: Record<string, unknown>;
+}>;

package/dist/src/documentation-effects.js

@@ -0,0 +1,56 @@
+import { address } from './research.js';
+import { object, fail } from './model.js';
+const equal = (actual, expected, label) => { if (actual !== expected)
+    fail('partial', `Saved documentation ${label} differs from the requested effect.`); };
+function offset(at, value) {
+    const normalized = address(at), parts = normalized.split(':'), hex = parts.pop(), distance = BigInt(String(value));
+    if (distance < 0n || distance > 0x7fffffffffffffffn)
+        fail('invalid', 'Documentation offsets must be nonnegative signed 64-bit integers.');
+    return (parts.length ? parts[0] + ':' : '') + (BigInt('0x' + hex) + distance).toString(16);
+}
+export async function verifyDocumentation(backend, snapshot, p) {
+    if (!backend.inspect)
+        fail('configuration', 'Documentation requires saved-state inspection.');
+    const document = object(p.json_body), at = address(document.target_address), inspect = (kind, parameters) => backend.inspect(snapshot, { kind, ...parameters });
+    const value = await inspect('function', { address: at });
+    equal(value.exists, true, 'function presence');
+    if (document.function_name)
+        equal(value.name, document.function_name, 'function name');
+    if (document.calling_convention)
+        equal(value.callingConvention, document.calling_convention, 'calling convention');
+    const checkType = async (actual, name) => { const wanted = await inspect('resolve_type', { name }); equal(wanted.exists, true, 'type presence'); equal(actual, object(wanted.type).name, 'type'); };
+    if (document.return_type)
+        await checkType(value.returnType, document.return_type);
+    if (document.plate_comment) {
+        const comments = await inspect('comments', { address: at });
+        equal(comments.plate, document.plate_comment, 'plate comment');
+    }
+    const requested = document.parameters ?? [];
+    if (!Array.isArray(requested) || !Array.isArray(value.parameters))
+        fail('partial', 'Documentation parameter inventory is absent.');
+    for (const raw of requested) {
+        const parameter = object(raw), ordinal = Number(parameter.ordinal);
+        if (!Number.isSafeInteger(ordinal) || ordinal < 0 || ordinal >= value.parameters.length)
+            fail('partial', 'Documentation parameter ordinal is absent.');
+        const saved = object(value.parameters[ordinal]);
+        if (parameter.name)
+            equal(saved.name, parameter.name, 'parameter name');
+        if (parameter.type)
+            await checkType(saved.type, parameter.type);
+    }
+    if (document.comments !== undefined && !Array.isArray(document.comments) || document.labels !== undefined && !Array.isArray(document.labels))
+        fail('invalid', 'Documentation comments and labels must be arrays.');
+    for (const raw of document.comments ?? []) {
+        const comment = object(raw), saved = await inspect('comments', { address: offset(at, comment.relative_offset) });
+        if (comment.eol_comment)
+            equal(saved.eol, comment.eol_comment, 'EOL comment');
+        if (comment.pre_comment)
+            equal(saved.pre, comment.pre_comment, 'PRE comment');
+    }
+    for (const raw of document.labels ?? []) {
+        const label = object(raw), saved = await inspect('symbols', { address: offset(at, label.relative_offset) });
+        if (!Array.isArray(saved.symbols) || !saved.symbols.some(symbol => object(symbol).name === label.name))
+            fail('partial', 'Documented label is absent from saved state.');
+    }
+    return { function: value };
+}

package/dist/src/extensions.d.ts

@@ -0,0 +1,64 @@
+import { type CommandDefinition } from '@eyeauras/cli-factory';
+interface ModuleFile {
+    name: string;
+    sha256: string;
+    size: number;
+}
+interface Extension {
+    name: string;
+    version: string;
+    sha256: string;
+    files: ModuleFile[];
+    enabled: boolean;
+}
+interface ExtensionState {
+    schema: 1;
+    modules: Extension[];
+}
+export declare function extensionState(directory: string): ExtensionState;
+export declare function inspectExtension(directory: string): Promise<Extension>;
+export declare function extensionDirectory(directory: string, module: Extension): string;
+/** Verify immutable owned copies; a changed input never joins an existing JVM's classpath. */
+export declare function managedExtensions(directory?: string): Promise<{
+    root: string;
+    name: string;
+    version: string;
+    sha256: string;
+    files: ModuleFile[];
+    enabled: boolean;
+}[]>;
+export declare class Extensions {
+    readonly directory: string;
+    constructor(directory: string);
+    list(): {
+        items: {
+            fileCount: number;
+            name: string;
+            version: string;
+            sha256: string;
+            enabled: boolean;
+        }[];
+        runtimeBoundary: string;
+    };
+    private write;
+    private ordered;
+    install(directory: string, expected: string): Promise<{
+        state: string;
+        name: string;
+        sha256: string;
+        enabled: boolean;
+        restartRequired: boolean;
+    }>;
+    private consume;
+    enable(name: string, enabled: boolean): Promise<{
+        state: string;
+        name: string;
+        sha256: string;
+        restartRequired: boolean;
+    }>;
+    private change;
+}
+export declare function extensionCommands(service: (c: import('@eyeauras/cli-factory').CommandContext) => Extensions): CommandDefinition[];
+export declare const extensionJvmArguments: (roots: string[]) => string[];
+export declare function extensionInventoryCommands(backend: (c: import('@eyeauras/cli-factory').CommandContext) => () => Promise<import('./research.js').ResearchBackend>): CommandDefinition[];
+export {};