@eyeauras/insight-cli 0.3.2 → 0.4.1

package/.cli-package-build.json

@@ -1 +1 @@
-{"version":1,"artifact":"0e495563091ce0b79877fc3050a2c51dca9631c45e07010a464f315bb3d56b58"}
+{"version":1,"artifact":"89b2f68ac98cf2bf71c2fc63c4af3a2014054f9b492eb3483ff41990092fb956"}

package/README.md

@@ -1,86 +1,58 @@
 # insight-cli
 
-CLI/API for reverse engineering with durable sessions, isolated Ghidra contexts,
-explicit merge/refresh and ordinary saved files. Agents choose the investigation.
+A CLI/API for reverse-engineering agents. Spend more time understanding a program and
+less time managing Ghidra processes or writing scripts around missing analysis metadata.
+
+- Search raw strings and code references, and inspect functions in sparse Ghidra databases.
+- Give each agent an isolated research context, with saved work and explicit merge/refresh.
+- Use structured JSON results and a persistent client for sequences of research calls.
 
 ## Install
 
-Use Node.js 24 or newer:
+Requires **Node.js 24+**:
 
 ```sh
 npm install --global @eyeauras/insight-cli
-insight-cli --help
-insight-cli skill insight-re
-```
-
-The executable is `insight-cli`. Its global npm executable directory must be on PATH.
-No source checkout, TypeScript build or separate Factory installation is required.
-The pinned Factory IPC runtime is a normal npm dependency fetched from an immutable
-GitHub tarball URL; installation therefore needs npm registry and GitHub access.
-Use `insight-cli ghidra install` to deliver the pinned Ghidra/JDK/native/server runtime.
-External Ghidra launchers and Java paths are also supported.
-`insight-cli ilspy install` delivers ILSpy and its private .NET runtime for managed-code
-research. Tool downloads use pinned assets retained in our GitHub Releases.
-Use `insight-cli tools processes` to inspect owned executions across tools.
-Help, skill discovery and saving ordinary files do not need Ghidra or Java.
-
-Downloading a tool does not expose it in an agent's tool list. Connect the packaged skills
-to your agent host, or explicitly give the agent the path returned by `insight-cli skill
-insight-re --json`. See [agent setup](references/agent-setup.md) for tested project-local
-Codex setup and a practical usability check. Installation leaves agent settings unchanged.
-
-## Discover the toolbox
-
-```sh
-insight-cli tools list --json
-insight-cli tools show die --json
-insight-cli skill insight-die --json
+insight-cli profile create local
+insight-cli profile set-default local
+insight-cli permissions grant Update
+insight-cli ghidra install
 ```
 
-The catalog describes the adapters and their packaged skills before any runtime is downloaded.
-Use each tool's `status` to check the selected profile, then follow its skill and generated help.
-The toolbox includes Ghidra, ILSpy, 7-Zip, LLVM utilities, DiE, LLDB, Frida, WinDbg, strace and .NET dump/stack/trace; platform
-and capability limits are explicit per tool. A partial classification or a failed native process
-is not a complete finding. Preserve useful output in ordinary project files and checkpoint it
-with `artifacts save` when useful. Existing project RE instructions retain precedence.
+The last command downloads and verifies compatible Ghidra and JDK runtimes. No source
+checkout or separate Java installation is needed. See [runtime setup](https://github.com/iXab3r/insight-cli/blob/main/skills/ghidra-coordinator/references/managed-runtime.md)
+for existing installations and offline setup.
 
-## Start
+For an AI agent, [connect the packaged skills](https://github.com/iXab3r/insight-cli/blob/main/skills/ghidra-coordinator/references/agent-setup.md).
+For repeated API calls, use the [persistent client](https://github.com/iXab3r/insight-cli/blob/main/skills/ghidra-coordinator/references/persistent.md).
 
-```sh
-insight-cli profile create local
-insight-cli --profile local permissions grant Update
-insight-cli --profile local ghidra install
-insight-cli --profile local ghidra status
-insight-cli --profile local ghidra open ./client.exe --session new --json
-```
+## Quick example
 
-Retain the returned `session` and `target` and supply both on research calls:
+Open a binary in a new private research context:
 
 ```sh
-insight-cli --profile local ghidra strings search --session <session> --target <target> --contains config.json --json
-insight-cli --profile local ghidra functions decompile --session <session> --target <target> --address <entry> --json
-insight-cli --profile local ghidra merge --session <session> --target <target> --json
+insight-cli ghidra open ./client.exe --session new --json
 ```
 
-Another agent uses `--session new` for its own context on the same input. It receives
-published changes with `ghidra refresh`; local work and conflicts remain explicit.
-Managed local startup needs no separately configured Ghidra Server.
-
-Save a completed project file or folder when a retained checkpoint is useful:
+Reuse the returned session and target IDs in place of `SESSION` and `TARGET`:
 
 ```sh
-insight-cli --profile local artifacts save ./analysis --json
+insight-cli ghidra strings anchors --session SESSION --target TARGET \
+  --text config --encodings ascii,utf16le --json
+insight-cli sessions status SESSION --target TARGET --json
 ```
 
-The response returns an ordinary saved path and digest. Follow existing project RE
-rules, formats and evidence locations; the packaged RE skill fills unspecified gaps.
-Installation does not register skills or change agent settings. Use `insight-cli skill`
-and `insight-cli skill insight-re` to locate packaged instructions and references.
+The search reads raw literal bytes, so it does not require defined Ghidra strings.
+Results include scan coverage and a continuation cursor when incomplete. New imports
+skip full automatic analysis by default; add `--analysis` to the first `open` to opt in.
+Continue with the [research guide](https://github.com/iXab3r/insight-cli/blob/main/skills/ghidra-coordinator/references/research.md).
 
-Full documentation and verification: [GitHub](https://github.com/iXab3r/insight-cli).
-License: MIT. The bundled GhidraMCP bridge has its own Apache-2.0 license and notice.
+## Benchmarks
 
-Runtime management, local archives and external paths: [managed runtime](references/managed-runtime.md).
-The host debugger and OS permissions are checked separately by `ghidra doctor`.
+In a fresh-agent PoE 2 investigation, installed insight-cli 0.4.0 with its persistent
+client finished in **16:35**, versus **19:43** through Ghidra MCP: **15.9% less wall time**,
+with comparable core findings. This is one adaptive research pair, not a general speed guarantee.
 
-Static .NET commands and ordinary output files: [ILSpy](references/ilspy.md).
+[Benchmarks](https://github.com/iXab3r/insight-cli/blob/main/BENCHMARKS.md) includes phases, earlier runs and comparison limits.
+[Development history and detailed reports](https://github.com/iXab3r/insight-cli/blob/main/docs/PROJECT-HISTORY.md) covers architecture,
+acceptance, other experiments and releases. See [Contributing](https://github.com/iXab3r/insight-cli/blob/main/CONTRIBUTING.md) for development.

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.1
 
 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 })]),
+    ];
+}