@eyeauras/insight-cli 0.3.2 → 0.4.0

package/.cli-package-build.json

@@ -1 +1 @@
-{"version":1,"artifact":"0e495563091ce0b79877fc3050a2c51dca9631c45e07010a464f315bb3d56b58"}
+{"version":1,"artifact":"034bd833a87d3a9c730b486252e2db09f67b3c6da2377c195389b894b26e12f7"}

package/SKILL.md

@@ -3,7 +3,7 @@ name: insight-cli
 description: Choose and prepare reverse-engineering capabilities from the insight-cli toolbox for binary, managed-code and runtime investigations. Use to discover the appropriate tool or its packaged skill before installing native runtimes.
 ---
 
-# insight-cli 0.3.2
+# insight-cli 0.4.0
 
 If local help/status reports AppData or IPC access denied, retry that **read-only probe**
 with the agent host's normal permission escalation, then use that route for later authorized
@@ -15,6 +15,9 @@ request/status recovery, never blind retry.
 Read the project's RE instructions and existing findings first. They own tool choices,
 evidence layout, formats and source of truth. These skills fill the remaining gaps.
 
+For repeated research calls, retain one [persistent CLI client](references/persistent.md)
+in the agent's long-lived runtime. Reuse it across calls to avoid repeated frontend startup.
+
 1. Run `insight-cli tools list --json` to discover the capabilities shipped in this version.
    The catalog works before profile configuration, downloads or IPC startup. A downloaded
    runtime is not needed to discover what a tool does.

package/dist/src/arguments.js

@@ -23,8 +23,10 @@ export function parsed(p, value) {
             fail('invalid', `${flag(p.name)} is outside its supported query range.`);
         if (p.name === 'timeout_seconds' && (result < 1 || result > 1800))
             fail('invalid', 'timeout-seconds must be between 1 and 1800.');
-        if (p.name === 'max_scan' && (result < 1 || result > 200000) || p.name === 'max_bytes' && (result < 1 || result > 16777216))
-            fail('invalid', `${flag(p.name)} is outside its supported work budget.`);
+        if (p.name === 'max_scan' && (result < 1 || result > 200000))
+            fail('invalid', 'max-scan must be between 1 and 200000 visited inputs; result offset does not advance scan coverage.');
+        if (p.name === 'max_bytes' && (result < 1 || result > 16777216))
+            fail('invalid', 'max-bytes must be between 1 and 16777216 bytes.');
         return result;
     }
     if (['json', 'object', 'array', 'any'].includes(p.type)) {
@@ -55,8 +57,11 @@ export function option(p) {
     const value = p.default;
     const defaultValue = value === undefined || value === '' && !p.allowEmpty ? undefined : parsed(p, value);
     return { flags: `--${flag(p.name)} <${p.type === 'json' ? 'json' : p.type}>`,
-        description: p.semantic === 'function_ref' ? 'Function name or explicit address' : p.semantic === 'address' ? 'Explicit hexadecimal address' :
-            `${flag(p.name)} (${p.type}${p.name === 'limit' ? ', 1–1000' : p.name === 'length' ? ', 1–65536 bytes' : ''})`,
+        description: p.name === 'max_scan' ? 'Maximum visited inputs, 1–200000; independent of result offset' :
+            p.name === 'max_bytes' ? 'Maximum searched bytes, 1–16777216' :
+                p.name === 'offset' && p.default !== '-1' ? 'Skip matching result rows; does not continue an incomplete scan' :
+                    p.semantic === 'function_ref' ? 'Function name or explicit address' : p.semantic === 'address' ? 'Explicit hexadecimal address' :
+                        `${flag(p.name)} (${p.type}${p.name === 'limit' ? ', 1–1000' : p.name === 'length' ? ', 1–65536 bytes' : ''})`,
         ...(p.required ? { required: true } : {}), ...(defaultValue === undefined ? {} : { defaultValue }),
         ...(['json', 'object', 'array', 'any'].includes(p.type) ? {} : { parse: (value) => parsed(p, value) }) };
 }

package/dist/src/cli.js

@@ -52,6 +52,11 @@ import { RuntimeManager, runtimeCommands, runtimeProcesses } from './runtime-man
 import { packageVersion } from './package-version.js';
 import { runtimeSelection } from './runtime-selection.js';
 import { AnalysisStorage, analysisDirectory } from './analysis-storage.js';
+import { codeReferenceCommands } from './code-references.js';
+import { stringAnchorCommands } from './string-anchors.js';
+import { contextDiagnosticCommands } from './context-diagnostics.js';
+import { traceCommand } from './internal-timing.js';
+import { timedBackend } from './timed-backend.js';
 import { readInitialProgress } from './initial-progress.js';
 const bindingFields = ['java', 'ghidraHome', 'mcpJar', 'mcpJarSha256', 'server', 'repository', 'readerUser', 'publisherUser', 'maxContexts', 'debuggerPython', 'windbgDir', 'archiveUrl'];
 class Owner {
@@ -109,7 +114,7 @@ class Owner {
             const result = await selected.backend;
             if (result instanceof GhidraContexts)
                 await managedExtensions(selected.workspace.directory);
-            return result instanceof GhidraContexts ? result.fork(c) : result;
+            return timedBackend(result instanceof GhidraContexts ? result.fork(c) : result);
         };
         const research = new Research(profile.workspace, backend, profile.tasks);
         return { workspace: profile.workspace, research, synchronization: new Synchronization(profile.workspace, research, async () => {
@@ -231,47 +236,50 @@ function scopedFailures(entry, owner, parents = []) {
     const path = [...parents, entry.name.split(' ')[0]], name = path.join(' ');
     const run = entry.run;
     return { ...entry, ...(entry.children ? { children: entry.children.map(child => scopedFailures(child, owner, path)) } : {}), ...(run ? { run: async (input, c) => {
-                try {
-                    let selected;
+                const execute = async () => {
                     try {
-                        selected = scope(input.options);
-                        if (selected.session === 'new')
-                            selected = undefined;
+                        let selected;
+                        try {
+                            selected = scope(input.options);
+                            if (selected.session === 'new')
+                                selected = undefined;
+                        }
+                        catch { }
+                        if (!selected)
+                            return await run(input, c);
+                        const services = owner.selected(c);
+                        // First open of an already known target reserves its context inside Research.open.
+                        // Existing contexts still use the command boundary to order automatic sync phases.
+                        if (path[1] === 'open')
+                            try {
+                                services.workspace.context(selected);
+                            }
+                            catch (error) {
+                                if (error instanceof CliError && error.code === 'coordinator.notFound')
+                                    return await run(input, c);
+                                throw error;
+                            }
+                        return await services.research.boundary(selected, async () => {
+                            const excluded = ['open', 'merge', 'refresh', 'sync-policy', 'close', 'changes', 'debugger', 'ui', 'version-tracking', 'archive', 'projects', 'repository', 'server', 'formats', 'libraries', 'plugins'];
+                            const eligible = entry.permission !== Permission.ReadOnly && entry.permission !== undefined && !excluded.includes(path[1]) && !['ghidra types archive-export', 'ghidra documentation transfer'].includes(name);
+                            return eligible ? services.synchronization.execute(selected, name, { ...input.options, commandArguments: input.args }, async (requestId) => run({ ...input, options: { ...input.options, ...(requestId ? { requestId } : {}) } }, c)) : run(input, c);
+                        });
                     }
-                    catch { }
-                    if (!selected)
-                        return await run(input, c);
-                    const services = owner.selected(c);
-                    // First open of an already known target reserves its context inside Research.open.
-                    // Existing contexts still use the command boundary to order automatic sync phases.
-                    if (path[1] === 'open')
+                    catch (error) {
+                        let selected;
                         try {
-                            services.workspace.context(selected);
+                            selected = scope(input.options);
                         }
-                        catch (error) {
-                            if (error instanceof CliError && error.code === 'coordinator.notFound')
-                                return await run(input, c);
+                        catch {
                             throw error;
                         }
-                    return await services.research.boundary(selected, async () => {
-                        const excluded = ['open', 'merge', 'refresh', 'sync-policy', 'close', 'changes', 'debugger', 'ui', 'version-tracking', 'archive', 'projects', 'repository', 'server', 'formats', 'libraries', 'plugins'];
-                        const eligible = entry.permission !== Permission.ReadOnly && entry.permission !== undefined && !excluded.includes(path[1]) && !['ghidra types archive-export', 'ghidra documentation transfer'].includes(name);
-                        return eligible ? services.synchronization.execute(selected, name, { ...input.options, commandArguments: input.args }, async (requestId) => run({ ...input, options: { ...input.options, ...(requestId ? { requestId } : {}) } }, c)) : run(input, c);
-                    });
-                }
-                catch (error) {
-                    let selected;
-                    try {
-                        selected = scope(input.options);
-                    }
-                    catch {
-                        throw error;
+                        if (!(error instanceof CliError))
+                            throw error;
+                        const result = error.result && typeof error.result === 'object' && !Array.isArray(error.result) ? error.result : {};
+                        throw new CliError(error.message, { code: error.code, exitCode: error.exitCode, next: error.next, result: { ...result, ...selected } });
                     }
-                    if (!(error instanceof CliError))
-                        throw error;
-                    const result = error.result && typeof error.result === 'object' && !Array.isArray(error.result) ? error.result : {};
-                    throw new CliError(error.message, { code: error.code, exitCode: error.exitCode, next: error.next, result: { ...result, ...selected } });
-                }
+                };
+                return path[1] === 'open' || input.options.session && input.options.target ? traceCommand(join(analysisDirectory(c), 'workspace'), name, execute) : execute();
             } } : {}) };
 }
 export function createDefinition(options = {}) {
@@ -424,7 +432,7 @@ export function createDefinition(options = {}) {
                         { flags: '--loader <name>', description: 'Explicit installed loader name/ID from formats loaders' },
                         { flags: '--loader-options <json>', description: 'Named primitive SDK loader options, requiring --loader' }] }),
                 command('strings', 'Read defined strings', [
-                    command('search', 'Find literal text and usable addresses', ({ options: o }, c) => owner.selected(c).research.strings(scope(o), text(o.contains, 4096), number(o.limit, 100, 1), number(o.offset, 2147483647)), { permission: Permission.ReadOnly, options: [...scoped, { flags: '--contains <text>', description: 'Literal case-insensitive substring', required: true }, ...paged] }),
+                    command('search', 'Find literal text in defined string data; undefined literals: analysis search-byte-patterns', ({ options: o }, c) => owner.selected(c).research.strings(scope(o), text(o.contains, 4096), number(o.limit, 100, 1), number(o.offset, 2147483647)), { permission: Permission.ReadOnly, options: [...scoped, { flags: '--contains <text>', description: 'Literal case-insensitive substring', required: true }, ...paged] }),
                 ]),
                 command('xrefs', 'Follow cross references', [
                     command('to', 'Find incoming references and their functions', ({ options: o }, c) => owner.selected(c).research.xrefs(scope(o), address(o.address), number(o.limit, 100, 1), number(o.offset, 2147483647)), { permission: Permission.ReadOnly, options: [...scoped, at, ...paged] }),
@@ -508,7 +516,7 @@ export function createDefinition(options = {}) {
         ],
     };
     const commands = definition.commands?.map(entry => entry.name === 'ghidra' ?
-        scopedFailures({ ...entry, children: extendQueries(extendQueries(extendQueries(entry.children ?? [], queryCommands(c => owner.selected(c).research)), mutationCommands(c => owner.selected(c).research)), [...sdkCommands(c => owner.selected(c).research), ...sdkFileCommands(c => owner.selected(c).sdkFiles), ...trackingCommands(c => owner.selected(c).tracking), ...crossCommands(c => owner.selected(c).research), ...administrationCommands(c => owner.selected(c).administration, options.backend ? undefined : async (c) => { const status = await new RuntimeManager(c).status(); return status.state === 'not_ready' ? { ...status.server, connected: false, state: 'runtime_not_ready', missing: status.missing } : undefined; }),
+        scopedFailures({ ...entry, children: extendQueries(extendQueries(extendQueries(entry.children ?? [], queryCommands(c => owner.selected(c).research)), mutationCommands(c => owner.selected(c).research)), [...codeReferenceCommands(c => owner.selected(c).research), ...stringAnchorCommands(c => owner.selected(c).research), ...contextDiagnosticCommands(c => owner.selected(c).research, c => owner.selected(c).workspace), ...sdkCommands(c => owner.selected(c).research), ...sdkFileCommands(c => owner.selected(c).sdkFiles), ...trackingCommands(c => owner.selected(c).tracking), ...crossCommands(c => owner.selected(c).research), ...administrationCommands(c => owner.selected(c).administration, options.backend ? undefined : async (c) => { const status = await new RuntimeManager(c).status(); return status.state === 'not_ready' ? { ...status.server, connected: false, state: 'runtime_not_ready', missing: status.missing } : undefined; }),
                 ...extensionCommands(c => new Extensions(join(analysisDirectory(c), 'workspace'))), ...extensionInventoryCommands(c => owner.selected(c).backend), ...pluginCommands(c => owner.selected(c).ui), ...synchronizationCommands(c => owner.selected(c).synchronization), ...utilityCommands(), ...runtimeCommands((c, action, quiescent) => owner.runtime(c, action, quiescent)), ...lifecycleCommands(c => owner.selected(c).lifecycle, c => new RuntimeManager(c).status()), ...projectCommands(c => owner.selected(c).projects), ...uiCommands(c => owner.selected(c).ui), ...debuggerCommands(c => owner.selected(c).debugger), ...archiveCommands(c => owner.selected(c).archive)]) }, owner) : entry);
     return { ...definition, commands: [...(commands ?? []).map(e => storage.wrap(e)), storage.commands()] };
 }

package/dist/src/code-references.d.ts

@@ -0,0 +1,48 @@
+import { type CommandContext } from '@eyeauras/cli-factory';
+import { type Research, type ResearchBackend } from './research.js';
+import type { Scope } from './workspace.js';
+export declare const referenceAlgorithm = "x86-64-code-reference-candidates-v1";
+export declare const referenceForms: readonly ["call-rel32", "lea-rip", "mov-rip", "call-rip-slot"];
+type Form = typeof referenceForms[number];
+export interface ReferenceQuery {
+    targets: string[];
+    forms: Form[];
+    start: string;
+    end: string;
+}
+export interface ReferenceBudgets {
+    max_bytes: number;
+    max_candidates: number;
+    timeout_seconds: number;
+    limit: number;
+}
+export interface ReferenceRequest {
+    query: ReferenceQuery;
+    from: string;
+    budgets: ReferenceBudgets;
+    expectedView?: string;
+}
+export declare function referenceRequest(o: Record<string, unknown>, who: Scope): ReferenceRequest;
+/** The deliberately small encoding contract, independently rechecked in the facade. */
+export declare function referenceEncoding(input: Buffer): {
+    form: "call-rel32" | "lea-rip" | "mov-rip" | "call-rip-slot";
+    length: number;
+    displacement: number;
+    operand: number;
+    bits: number;
+    delta: number;
+    role: string;
+} | undefined;
+export declare function referenceResult(raw: unknown, r: ReferenceRequest): Record<string, unknown>;
+export declare function inspectCodeReferences(backend: ResearchBackend, who: Scope, r: ReferenceRequest, view: string, observation: unknown): Promise<{
+    value: {
+        view: {
+            identity: string;
+        };
+        cursor: string | null;
+    };
+    session: string;
+    target: string;
+}>;
+export declare function codeReferenceCommands(research: (c: CommandContext) => Research): import("@eyeauras/cli-factory").CommandDefinition[];
+export {};

package/dist/src/code-references.js

@@ -0,0 +1,154 @@
+import { command, Permission } from '@eyeauras/cli-factory';
+import { scope, number, address } from './research.js';
+import { fail, object, digest, stable } from './model.js';
+import { parseDomainJson } from './json.js';
+import { selectedOptions } from './arguments.js';
+export const referenceAlgorithm = 'x86-64-code-reference-candidates-v1';
+export const referenceForms = ['call-rel32', 'lea-rip', 'mov-rip', 'call-rip-slot'];
+const defaults = { max_bytes: 4194304, max_candidates: 200000, timeout_seconds: 5, limit: 100 };
+const hex = (v) => { const s = address(v); if (!/^[a-f0-9]{1,16}$/.test(s))
+    fail('invalid', 'Code-reference V1 requires default-space unsigned 64-bit addresses.'); return s; };
+const big = (s) => BigInt('0x' + s);
+function query(v) {
+    const q = object(v);
+    if (!Array.isArray(q.targets) || q.targets.length < 1 || q.targets.length > 64 || !Array.isArray(q.forms) || !q.forms.length || q.forms.length > 4)
+        fail('invalid', 'Select 1–64 targets and 1–4 reference forms.');
+    const targets = q.targets.map(hex).sort((a, b) => big(a) < big(b) ? -1 : big(a) > big(b) ? 1 : 0), forms = referenceForms.filter(f => q.forms.includes(f));
+    if (new Set(targets).size !== targets.length || forms.length !== q.forms.length)
+        fail('invalid', 'Targets/forms must be distinct supported values.');
+    const start = hex(q.start), end = hex(q.end);
+    if (big(start) > big(end))
+        fail('invalid', 'scan-through must not precede scan-from.');
+    return { targets, forms, start, end };
+}
+function budgets(v, base = defaults) { return { max_bytes: number(v.maxBytes ?? base.max_bytes, 16777216, 15), max_candidates: number(v.maxCandidates ?? base.max_candidates, 1000000, 1), timeout_seconds: number(v.timeoutSeconds ?? base.timeout_seconds, 30, 1), limit: number(v.limit ?? base.limit, 1000, 1) }; }
+export function referenceRequest(o, who) {
+    if (o.cursor !== undefined) {
+        if (['to', 'forms', 'scanFrom', 'scanThrough'].some(k => o[k] !== undefined))
+            fail('invalid', 'Cursor continuation cannot change targets, forms or scan bounds.');
+        if (typeof o.cursor !== 'string' || o.cursor.length > 16384 || !/^cr1\.[A-Za-z0-9_-]+$/.test(o.cursor))
+            fail('invalid', 'Malformed code-reference cursor.');
+        let c;
+        try {
+            const encoded = o.cursor.slice(4), bytes = Buffer.from(encoded, 'base64url');
+            if (bytes.toString('base64url') !== encoded)
+                throw Error();
+            c = object(parseDomainJson(bytes.toString('utf8')));
+        }
+        catch {
+            fail('invalid', 'Malformed code-reference cursor.');
+        }
+        if (c.version !== 1 || c.algorithm !== referenceAlgorithm || stable(c.scope) !== stable(who) || typeof c.view !== 'string' || !/^[a-f0-9]{64}$/.test(c.view))
+            fail('invalid', 'Cursor version, scope or view is incompatible.');
+        const q = query(c.query), from = hex(c.next), b = object(c.budgets);
+        if (big(from) < big(q.start) || big(from) > big(q.end))
+            fail('invalid', 'Cursor frontier is outside its range.');
+        if (['max_bytes', 'max_candidates', 'timeout_seconds', 'limit'].some(k => !Number.isSafeInteger(b[k])))
+            fail('invalid', 'Malformed cursor budgets.');
+        const inherited = budgets({ maxBytes: b.max_bytes, maxCandidates: b.max_candidates, timeoutSeconds: b.timeout_seconds, limit: b.limit });
+        return { query: q, from, budgets: budgets(o, inherited), expectedView: c.view };
+    }
+    if (typeof o.to !== 'string' || typeof o.scanFrom !== 'string' || typeof o.scanThrough !== 'string')
+        fail('invalid', 'Supply --to, --scan-from and --scan-through, or --cursor.');
+    const q = query({ targets: o.to.split(',').map(x => x.trim()), forms: o.forms === undefined ? [...referenceForms] : String(o.forms).split(',').map(x => x.trim()), start: o.scanFrom, end: o.scanThrough });
+    return { query: q, from: q.start, budgets: budgets(o) };
+}
+/** The deliberately small encoding contract, independently rechecked in the facade. */
+export function referenceEncoding(input) {
+    let p = 0, rex = 0, word = false;
+    while (p < input.length && p < 15) {
+        const b = input[p];
+        if ([0x66, 0x26, 0x2e, 0x36, 0x3e].includes(b)) {
+            word ||= b === 0x66;
+            rex = 0;
+            p++;
+        }
+        else if (b >= 0x40 && b <= 0x4f) {
+            rex = b;
+            p++;
+        }
+        else
+            break;
+    }
+    const op = input[p], m = input[p + 1];
+    let form, displacement, length, operand, bits;
+    if (op === 0xe8) {
+        form = 'call-rel32';
+        length = p + 5;
+        displacement = p + 1;
+        operand = 0;
+        bits = 64;
+    }
+    else {
+        if (m === undefined || (m & 0xc7) !== 5)
+            return;
+        if (op === 0x8d) {
+            form = 'lea-rip';
+            operand = 1;
+        }
+        else if (op !== undefined && [0x88, 0x89, 0x8a, 0x8b].includes(op)) {
+            form = 'mov-rip';
+            operand = op === 0x88 || op === 0x89 ? 0 : 1;
+        }
+        else if (op === 0xff && ((m >> 3) & 7) === 2) {
+            form = 'call-rip-slot';
+            operand = 0;
+        }
+        else
+            return;
+        length = p + 6;
+        displacement = p + 2;
+        bits = form === 'call-rip-slot' ? 64 : op === 0x88 || op === 0x8a ? 8 : rex & 8 ? 64 : word ? 16 : 32;
+    }
+    if (length > 15 || input.length < length)
+        return;
+    return { form, length, displacement, operand, bits, delta: input.readInt32LE(displacement), role: form === 'call-rel32' ? 'direct-call-target' : form === 'call-rip-slot' ? 'pointer-slot' : 'effective-address' };
+}
+export function referenceResult(raw, r) {
+    const v = object(raw), s = object(v.scan), q = r.query, b = r.budgets;
+    if (v.algorithm !== referenceAlgorithm || typeof v.language !== 'string' || !v.language.startsWith('x86:LE:64:') || stable(v.forms) !== stable(q.forms) || !Array.isArray(v.matches) || v.matches.length > b.limit || object(v.read_only ?? {}).modification_unchanged !== true)
+        fail('partial', 'Malformed code-reference result.');
+    for (const k of ['bytes_read', 'tested_starts', 'visited_candidates'])
+        if (!Number.isSafeInteger(s[k]) || Number(s[k]) < 0)
+            fail('partial', 'Malformed reference scan counters.');
+    const complete = s.complete;
+    if (typeof complete !== 'boolean' || Number(s.bytes_read) > b.max_bytes || Number(s.tested_starts) > Number(s.bytes_read) || Number(s.visited_candidates) > b.max_candidates || Number(s.visited_candidates) < v.matches.length || Number(s.visited_candidates) > Number(s.tested_starts) || !['exhausted', 'byte_limit', 'candidate_limit', 'timeout', 'result_limit'].includes(String(s.reason)) || complete !== (s.reason === 'exhausted') || !Number.isFinite(s.elapsed_ms) || Number(s.elapsed_ms) < 0 || hex(s.from) !== r.from || hex(s.through) !== q.end)
+        fail('partial', 'Inconsistent code-reference coverage.');
+    const next = complete ? null : hex(s.next_start);
+    if (complete && s.next_start !== null || next !== null && (big(next) < big(r.from) || big(next) > big(q.end)) || next !== null && BigInt(Number(s.tested_starts)) > big(next) - big(r.from))
+        fail('partial', 'Reference frontier changed.');
+    let previous = -1n;
+    for (const rawRow of v.matches) {
+        const row = object(rawRow), from = hex(row.from), to = hex(row.to), bytes = row.bytes;
+        if (typeof bytes !== 'string' || !/^(?:[a-f0-9]{2}){1,15}$/.test(bytes))
+            fail('partial', 'Reference omitted its instruction bytes.');
+        const encoding = referenceEncoding(Buffer.from(bytes, 'hex'));
+        if (!encoding || row.form !== encoding.form || !q.forms.includes(encoding.form) || row.length !== encoding.length || bytes.length !== encoding.length * 2 || row.operand_index !== encoding.operand || row.operand_bits !== encoding.bits || row.target_role !== encoding.role || !q.targets.includes(to) || big(to) !== BigInt.asUintN(64, big(from) + BigInt(encoding.length + encoding.delta)) || big(from) <= previous || big(from) < big(r.from) || big(from) + BigInt(encoding.length - 1) > big(q.end) || next !== null && big(from) >= big(next) || !['listing-confirmed', 'listing-conflict', 'unconfirmed'].includes(String(row.boundary)) || row.validation !== 'decoded' || typeof row.instruction !== 'string' || row.instruction.length > 512)
+            fail('partial', 'Reference bytes, target, form or frontier are inconsistent.');
+        previous = big(from);
+    }
+    if (Buffer.byteLength(JSON.stringify(v)) > 1048576)
+        fail('limit', 'Code-reference response exceeds one MiB.');
+    return v;
+}
+export async function inspectCodeReferences(backend, who, r, view, observation) {
+    if (r.expectedView !== undefined && r.expectedView !== view)
+        fail('binding', 'Code-reference continuation view changed.', { reason: 'changed_view' });
+    const q = r.query, result = await backend.call(who, '/code_references', { targets: q.targets, forms: q.forms, scan_from: r.from, scan_through: q.end, ...r.budgets });
+    if (digest(observation) !== digest(await backend.observation(who)))
+        fail('binding', 'Native view changed during code-reference scan.', { reason: 'changed_view' });
+    const value = referenceResult(result, r), s = object(value.scan);
+    const cursor = s.complete ? null : 'cr1.' + Buffer.from(stable({ version: 1, algorithm: referenceAlgorithm, scope: who, query: q, next: hex(s.next_start), view, budgets: r.budgets })).toString('base64url');
+    return { ...who, value: { ...value, view: { identity: view }, cursor } };
+}
+export function codeReferenceCommands(research) {
+    return [command('analysis', 'Static analysis', [command('code-references', 'Find bounded x86-64 byte reference candidates without changing Listing or xrefs', ({ options: o }, c) => { const who = scope(o); return research(c).codeReferences(who, referenceRequest(o, who)); }, { permission: Permission.ReadOnly, options: [...selectedOptions,
+                    { flags: '--to <addresses>', description: '1–64 distinct exact default-space targets, comma separated' },
+                    { flags: '--forms <forms>', description: 'call-rel32,lea-rip,mov-rip,call-rip-slot; defaults to all four' },
+                    { flags: '--scan-from <address>', description: 'First candidate start (initial request)' }, { flags: '--scan-through <address>', description: 'Inclusive final byte; matches must fit completely' },
+                    { flags: '--cursor <token>', description: 'Stateless continuation; excludes targets/forms/range selectors' },
+                    { flags: '--max-bytes <count>', description: '15–16777216 bytes read including lookahead; default 4194304' },
+                    { flags: '--max-candidates <count>', description: '1–1000000 prefiltered starts including rejected candidates; default 200000' },
+                    { flags: '--timeout-seconds <count>', description: '1–30 second cooperative native scan deadline; default 5' },
+                    { flags: '--limit <count>', description: '1–1000 matches per call; default 100' }] })])];
+}

package/dist/src/context-diagnostics.d.ts

@@ -0,0 +1,25 @@
+import { type CommandContext, type CommandDefinition } from '@eyeauras/cli-factory';
+import { type Research } from './research.js';
+import type { Workspace, Scope } from './workspace.js';
+export type StopReason = 'explicit_close' | 'view_replaced' | 'mode_changed' | 'owner_dispose' | 'startup_failed' | 'temporary_complete' | 'legacy_cleanup' | 'unknown';
+type Event = {
+    at: string;
+    event: 'start' | 'restore' | 'stop';
+    reason: string;
+    pid: number;
+};
+export declare function recordLifecycle(workspace: Workspace, context: string, event: Event): Promise<void>;
+export declare function lifecycleDiagnostic(workspace: Workspace, selected: Scope): Promise<{
+    lifecycle: {
+        ownerShutdownCause: string;
+        coverage: string;
+        latest?: Record<string, unknown> | undefined;
+        events: Event[];
+        maximumEvents: number;
+    };
+    session: string;
+    target: string;
+}>;
+export declare function navigationResult(raw: unknown, maximum: number): Record<string, unknown>;
+export declare function contextDiagnosticCommands(research: (c: CommandContext) => Research, workspace: (c: CommandContext) => Workspace): CommandDefinition[];
+export {};

package/dist/src/context-diagnostics.js

@@ -0,0 +1,82 @@
+import { command, Permission } from '@eyeauras/cli-factory';
+import { mkdir, readFile, writeFile, rename, realpath } from 'node:fs/promises';
+import { join, resolve, sep } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { scope, number } from './research.js';
+import { object, fail, stable } from './model.js';
+import { selectedOptions } from './arguments.js';
+const writes = new Map();
+const journal = (workspace, context) => join(workspace.directory, 'diagnostics', 'lifecycle', context + '.json');
+const reasons = new Set(['explicit_close', 'view_replaced', 'mode_changed', 'owner_dispose', 'startup_failed', 'temporary_complete', 'legacy_cleanup', 'unknown', 'native_launch', 'saved_snapshot']);
+async function events(path) {
+    try {
+        const rows = JSON.parse(await readFile(path, 'utf8'));
+        if (!Array.isArray(rows) || rows.length > 128 || rows.some(row => !row || typeof row.at !== 'string' || row.at.length > 64 || !Number.isFinite(Date.parse(row.at)) || !['start', 'restore', 'stop'].includes(row.event) || !reasons.has(row.reason) || !Number.isSafeInteger(row.pid) || row.pid < 1))
+            fail('binding', 'Retained lifecycle observations are malformed.');
+        return rows.map(({ at, event, reason, pid }) => ({ at, event, reason, pid }));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw error;
+    }
+}
+export async function recordLifecycle(workspace, context, event) {
+    const path = journal(workspace, context), previous = writes.get(path) ?? Promise.resolve();
+    const pending = previous.catch(() => { }).then(async () => { const rows = [...await events(path), event].slice(-128), directory = join(workspace.directory, 'diagnostics', 'lifecycle'); await mkdir(directory, { recursive: true, mode: 0o700 }); const temporary = path + '.new-' + randomUUID(); await writeFile(temporary, JSON.stringify(rows) + '\n', { mode: 0o600, flag: 'wx' }); await rename(temporary, path); });
+    writes.set(path, pending);
+    try {
+        await pending;
+    }
+    catch { }
+    finally {
+        if (writes.get(path) === pending)
+            writes.delete(path);
+    }
+}
+export async function lifecycleDiagnostic(workspace, selected) {
+    const context = workspace.context(selected), root = join(workspace.directory, 'ghidra-native', 'context', context.id);
+    let latest;
+    try {
+        const binding = object(JSON.parse(await readFile(join(root, 'current.json'), 'utf8')));
+        if (binding.context !== context.id || binding.target !== selected.target || binding.session !== undefined && binding.session !== selected.session || typeof binding.root !== 'string' || !Number.isSafeInteger(binding.pid) || typeof binding.tokenSecret !== 'string')
+            fail('binding', 'Lifecycle receipt belongs to another context.');
+        const physical = await realpath(binding.root);
+        if (physical !== resolve(binding.root) || !physical.startsWith(resolve(root) + sep))
+            fail('binding', 'Lifecycle receipt moved outside its context.');
+        const persisted = object(JSON.parse(await readFile(join(physical, 'process.json'), 'utf8')));
+        if (stable(persisted) !== stable(binding))
+            fail('binding', 'Lifecycle process receipt changed.');
+        latest = { pid: binding.pid, state: 'unobserved', reason: 'unknown' };
+        try {
+            const stopped = object(JSON.parse(await readFile(join(physical, 'stopped.json'), 'utf8')));
+            if (stopped.pid === binding.pid && stopped.tokenSecret === binding.tokenSecret)
+                latest = { pid: binding.pid, state: 'stopped', reason: reasons.has(String(stopped.reason)) ? stopped.reason : 'unknown', ...(typeof stopped.at === 'string' ? { at: stopped.at } : {}) };
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    return { ...selected, lifecycle: { events: await events(journal(workspace, context.id)), maximumEvents: 128, ...(latest ? { latest } : {}), ownerShutdownCause: 'unknown', coverage: 'Retained facade observations, at most the latest 128 events; absent events and historical causes remain unknown. This read neither starts nor probes a native process.' } };
+}
+export function navigationResult(raw, maximum) {
+    const value = object(raw), scan = object(value.scan), functions = object(value.functions);
+    const samples = ['functions', 'instructions', 'references', 'definedData'].map(key => object(value[key]));
+    if (samples.some(row => !Number.isSafeInteger(row.sampled) || Number(row.sampled) < 0 || Number(row.sampled) > 128 || typeof row.complete !== 'boolean') ||
+        !Number.isSafeInteger(scan.visited) || Number(scan.visited) !== samples.reduce((n, row) => n + Number(row.sampled), 0) || Number(scan.visited) > maximum || scan.maximum !== maximum || scan.sampleLimitPerCategory !== 128 || typeof scan.complete !== 'boolean' || scan.complete !== samples.every(row => row.complete) || !['budget', 'sample_limit', 'exhausted'].includes(String(scan.reason)) ||
+        !Number.isSafeInteger(functions.oneByteBodies) || Number(functions.oneByteBodies) < 0 || Number(functions.oneByteBodies) > Number(functions.sampled) || !Number.isSafeInteger(functions.entriesWithInstructions) || Number(functions.entriesWithInstructions) < 0 || Number(functions.entriesWithInstructions) > Number(functions.sampled) || !Number.isSafeInteger(functions.bodyBytes) || Number(functions.bodyBytes) < 0 ||
+        !Number.isSafeInteger(samples[3].strings) || Number(samples[3].strings) < 0 || Number(samples[3].strings) > Number(samples[3].sampled) || !['sparse-metadata', 'no-code-observed', 'observed-metadata'].includes(String(value.assessment)) || !Array.isArray(value.recommendations) || value.recommendations.some(v => typeof v !== 'string') || object(value.read_only ?? {}).modification_unchanged !== true)
+        fail('partial', 'Malformed navigation diagnostic.');
+    return value;
+}
+export function contextDiagnosticCommands(research, workspace) {
+    return [
+        command('analysis', 'Analysis observations', [command('navigation', 'Inspect bounded navigation metadata; ready is not analysis completeness', ({ options: o }, c) => research(c).navigation(scope(o), number(o.maxScan ?? 10000, 200000, 1)), { permission: Permission.ReadOnly, options: [...selectedOptions, { flags: '--max-scan <count>', description: 'Maximum visited metadata inputs across all samples, 1–200000', defaultValue: 10000 }] })]),
+        command('diagnostics', 'Inspect retained context diagnostics', [command('lifecycle', 'Read retained start/restore/stop reasons without starting Ghidra', ({ options: o }, c) => lifecycleDiagnostic(workspace(c), scope(o)), { permission: Permission.ReadOnly, options: selectedOptions })]),
+    ];
+}

package/dist/src/contexts.d.ts

@@ -62,7 +62,19 @@ export declare class GhidraContexts {
     private privateCopy;
     open(scope: Scope, request?: string): Promise<GhidraContext>;
     private selected;
-    observation(scope: Scope): Promise<unknown>;
+    observation(scope: Scope): Promise<{
+        incarnation: string;
+    }>;
+    inspectObservation(scope: Scope): Promise<{
+        incarnation: string;
+        modification: string;
+        language: unknown;
+        compiler: unknown;
+    }>;
+    inlineScript(scope: Scope, parameters: Record<string, unknown>, requestId: string): Promise<{
+        response: Record<string, unknown>;
+        safe: boolean;
+    }>;
     call(scope: Scope, operation: string, parameters?: Record<string, unknown>): Promise<unknown>;
     saved(scope: Scope): Promise<Artifact>;
     scripts(scope: Scope, filter: string, limit: number, offset: number): Promise<import("./scripts.js").ScriptPage>;