@eyeauras/insight-cli 0.3.1 → 0.4.0

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>;

package/dist/src/contexts.js

@@ -1,3 +1,4 @@
+import { recordLifecycle } from './context-diagnostics.js';
 import { ghidraBudget } from './budgets.js';
 import { launchProcess, terminateProcess } from './tool-runtime/supervisor.js';
 import { runTool } from './tool-runtime/run.js';
@@ -11,7 +12,7 @@ import { createServer } from 'node:net';
 import { setTimeout as delay } from 'node:timers/promises';
 import { nativeHelpers, nativeInputs, nativeJvmDirectories, nativeExtensionArguments } from './native-inputs.js';
 import { GhidraServer } from './server.js';
-import { object, fail, text, version, stable } from './model.js';
+import { object, fail, text, version, stable, digest } from './model.js';
 import { HttpBridge } from './transport.js';
 import { scriptInventory, scriptPath } from './scripts.js';
 import { logicalPrograms } from './cross-results.js';
@@ -21,6 +22,8 @@ import { readCallerGoal, awaitCaller } from './debugger-caller.js';
 import { debuggerProgramMetadata } from './debugger-results.js';
 import { nativeQueries } from './query-policy.js';
 import { nativeQuery } from './native-queries.js';
+import { runInline } from './inline-script.js';
+import { researchView } from './research-view.js';
 import { sdkWrites } from './sdk-contracts.js';
 import { initialIntent, initializeModel } from './initial-model.js';
 import { managedGhidraDebugger, prepareGhidraDebugger } from './ghidra-debugger-runtime.js';
@@ -149,6 +152,8 @@ export class GhidraContexts {
                     const info = await record.http.instance();
                     if (info.pid !== binding.pid || info.tcp_port !== endpointPort)
                         fail('binding', 'Context endpoint belongs to a different native process.');
+                    if (context)
+                        await recordLifecycle(this.workspace, context, { at: new Date().toISOString(), event: 'start', reason: 'native_launch', pid: binding.pid });
                     return record;
                 }
                 catch {
@@ -162,6 +167,11 @@ export class GhidraContexts {
                 child.kill('SIGTERM');
             for (let i = 0; i < 100 && child.exitCode === null && child.signalCode === null; i++)
                 await delay(50);
+            if (context && (child.exitCode !== null || child.signalCode !== null)) {
+                const at = new Date().toISOString();
+                await durable(join(root, 'stopped.json'), { pid: binding.pid, tokenSecret: binding.tokenSecret, at, reason: 'startup_failed' });
+                await recordLifecycle(this.workspace, context, { at, event: 'stop', reason: 'startup_failed', pid: binding.pid });
+            }
             this.running.delete(root);
             throw error;
         }
@@ -190,7 +200,7 @@ export class GhidraContexts {
             fail('binding', 'Opened native program does not match the target input bytes.');
         return object(await record.http.call('/get_metadata', { program: record.binding.program }));
     }
-    async stopRecord(record, ready = true, releaseCapacity = true) {
+    async stopRecord(record, ready = true, releaseCapacity = true, reason = 'temporary_complete') {
         const { binding, child } = record;
         const childFinished = child && child.pid === binding.pid && (child.exitCode !== null || child.signalCode !== null);
         if (!childFinished && alive(binding.pid)) {
@@ -213,7 +223,10 @@ export class GhidraContexts {
         }
         if (binding.mode === 'gui')
             await this.debuggerReleased(binding);
-        await durable(join(binding.root, 'stopped.json'), { pid: binding.pid, tokenSecret: binding.tokenSecret });
+        const at = new Date().toISOString();
+        await durable(join(binding.root, 'stopped.json'), { pid: binding.pid, tokenSecret: binding.tokenSecret, at, reason });
+        if (binding.context)
+            await recordLifecycle(this.workspace, binding.context, { at, event: 'stop', reason, pid: binding.pid });
         if (releaseCapacity && binding.context)
             this.capacity.slots.delete(binding.context);
         this.running.delete(binding.root);
@@ -378,11 +391,13 @@ export class GhidraContexts {
             record.binding.viewEpoch = context.viewEpoch ?? 0;
             await durable(join(root, 'process.json'), record.binding);
             await durable(join(this.directory(), 'context', context.id, 'current.json'), record.binding);
+            if (context.workingSnapshot)
+                await recordLifecycle(this.workspace, context.id, { at: new Date().toISOString(), event: 'restore', reason: 'saved_snapshot', pid: record.binding.pid });
             return record;
         }
         catch (error) {
             if (record)
-                await this.stopRecord(record, false);
+                await this.stopRecord(record, false, true, 'startup_failed');
             else
                 this.capacity.slots.delete(context.id);
             throw error;
@@ -413,7 +428,7 @@ export class GhidraContexts {
         }
         if (binding && !stopped && alive(binding.pid) && ((binding.viewEpoch ?? 0) !== (context.viewEpoch ?? 0) ||
             binding.baseRevision !== context.baseRevision && context.baseRevision !== undefined)) {
-            await this.stopRecord(await this.verified(binding, target), true, false);
+            await this.stopRecord(await this.verified(binding, target), true, false, 'view_replaced');
             stopped = true;
         }
         if (binding && !stopped && alive(binding.pid)) {
@@ -434,6 +449,8 @@ export class GhidraContexts {
         const snapshot = context.workingSnapshot ?? model.sharedSnapshot;
         if (!snapshot || !model.sharedRevision)
             fail('binding', 'Canonical target has no saved base.');
+        if (binding && !stopped && !alive(binding.pid))
+            await recordLifecycle(this.workspace, context.id, { at: new Date().toISOString(), event: 'stop', reason: 'unknown', pid: binding.pid });
         await this.privateCopy(context, snapshot);
         if (context.workingSnapshot)
             return this.workspace.saveContext(scope, context.generation, { state: 'ready' });
@@ -447,7 +464,19 @@ export class GhidraContexts {
             fail('binding', 'Context process binding changed.');
         return this.verified(binding, this.workspace.target(scope.target));
     }
-    async observation(scope) { return this.call(scope, '/research_view'); }
+    async observation(scope) {
+        const record = await this.selected(scope);
+        return { ...object(await this.call(scope, '/research_view')), incarnation: digest({ pid: record.binding.pid, root: record.binding.root }) };
+    }
+    async inspectObservation(scope) {
+        const record = await this.selected(scope);
+        const view = researchView(await record.http.call('/insight/research-view/v1', { program: record.binding.program }));
+        return { ...view, incarnation: digest({ pid: record.binding.pid, root: record.binding.root }) };
+    }
+    async inlineScript(scope, parameters, requestId) {
+        const record = await this.selected(scope);
+        return runInline(record.http, record.binding.program, record.binding.root, parameters, requestId);
+    }
     async call(scope, operation, parameters = {}) {
         if (Object.hasOwn(parameters, 'program'))
             fail('invalid', 'Program routing is owned by the session and target selectors.');
@@ -652,7 +681,7 @@ public class ${name} extends GhidraScript {
         const debuggerState = record.binding.mode === 'gui' && context.debugger?.traces.length ? await this.debuggerSaved(scope) : context.debugger;
         const complexChanges = await this.debuggerMetadataChanges(context, snapshot);
         this.workspace.saveContext(scope, context.generation, { workingSnapshot: snapshot, complexChanges, ...(debuggerState ? { debugger: { ...debuggerState, connected: false, traces: debuggerState.traces.map(trace => ({ ...trace, connected: false })) } } : {}) });
-        await this.stopRecord(record, true, false);
+        await this.stopRecord(record, true, false, 'mode_changed');
         if (mode === 'headless') {
             await this.privateCopy(this.workspace.context(scope), snapshot);
             return;
@@ -868,7 +897,7 @@ public class ${name} extends GhidraScript {
         const debuggerState = record.binding.mode === 'gui' && context.debugger?.traces.length ? await this.debuggerSaved(scope) : context.debugger;
         const complexChanges = await this.debuggerMetadataChanges(context, snapshot);
         this.workspace.saveContext(scope, context.generation, { state: 'stopped', workingSnapshot: snapshot, complexChanges, ...(debuggerState ? { debugger: { ...debuggerState, connected: false, traces: debuggerState.traces.map(trace => ({ ...trace, connected: false })) } } : {}) });
-        await this.stopRecord(record);
+        await this.stopRecord(record, true, true, 'explicit_close');
     }
     async closed(scope) {
         const context = this.workspace.context(scope), path = join(this.directory(), 'context', context.id, 'current.json');
@@ -1050,7 +1079,7 @@ public class ${name} extends GhidraScript {
         for (const record of [...this.running.values()]) {
             try {
                 // Original child handles also permit cleanup of a failed, unready owned stage.
-                await cleanup.stopRecord(record, !record.child);
+                await cleanup.stopRecord(record, !record.child, true, 'owner_dispose');
             }
             catch {
                 failures++;

package/dist/src/function-boundaries.d.ts

@@ -0,0 +1,9 @@
+import type { LocatedEntry } from './function-entries.js';
+/** Validate evidence and selection policy independently, before any function inspection/save. */
+export declare function locatedBoundaries(raw: unknown, request: {
+    addresses: string[];
+    unwindMaximum: number;
+}, modification: string): {
+    entries: Map<string, LocatedEntry>;
+    boundaryLookup: Record<string, unknown>;
+};