@eyeauras/insight-cli 0.3.1 → 0.4.0

package/skill-bundle/insight-ghidra/references/persistent-client.mjs

@@ -0,0 +1,125 @@
+import { spawn } from 'node:child_process';
+import { StringDecoder } from 'node:string_decoder';
+export class InsightCommandError extends Error {
+    rpc;
+    constructor(rpc) {
+        super(rpc.message);
+        this.rpc = rpc;
+        this.name = 'InsightCommandError';
+    }
+}
+export class InsightTransportError extends Error {
+    dispatched;
+    constructor(message, dispatched) {
+        super(message);
+        this.dispatched = dispatched;
+        this.name = 'InsightTransportError';
+    }
+}
+/** A thin client of Factory's existing stream, with no reconnect or command replay. */
+export async function connectInsight(options) {
+    const child = spawn(options.executable, [...(options.arguments ?? []), '--json-rpc'], { cwd: options.cwd, env: options.env, stdio: ['pipe', 'pipe', 'pipe'], shell: false });
+    const maximum = 4 * 1024 ** 2, decoder = new StringDecoder('utf8');
+    let buffer = '', bytes = 0, sequence = 0, accepting = true, failed = false, ended = false;
+    let closePromise, tail = Promise.resolve();
+    const pending = new Map();
+    // Drain diagnostics without retaining arbitrary stderr, paths, tokens or unbounded output.
+    child.stderr.resume();
+    const fail = (message) => {
+        if (failed)
+            return;
+        failed = true;
+        accepting = false;
+        for (const p of pending.values())
+            p.reject(new InsightTransportError(message, true));
+        pending.clear();
+        child.stdin.destroy();
+        child.stdout.destroy();
+    };
+    child.on('error', () => fail('Persistent CLI process failed.'));
+    child.stdout.on('error', () => fail('Persistent CLI output was lost.'));
+    child.stderr.on('error', () => fail('Persistent CLI diagnostic stream was lost.'));
+    child.stdin.on('error', () => fail('Persistent CLI input was lost; inspect request/status before retrying a changing command.'));
+    const exited = new Promise((resolve, reject) => {
+        child.once('close', (code, signal) => {
+            ended = true;
+            if (code !== 0 || signal || pending.size || buffer.trim()) {
+                fail('Persistent CLI closed without a complete acknowledged response.');
+                reject(new InsightTransportError('Persistent CLI transport ended unexpectedly.', false));
+            }
+            else if (failed)
+                reject(new InsightTransportError('Persistent CLI transport failed.', false));
+            else
+                resolve();
+        });
+    });
+    void exited.catch(() => { });
+    child.stdout.on('data', (chunk) => {
+        if (failed)
+            return;
+        buffer += decoder.write(chunk);
+        bytes += chunk.length;
+        if (bytes > maximum) {
+            fail('Persistent CLI response exceeded the bounded transport limit.');
+            return;
+        }
+        for (;;) {
+            const newline = buffer.indexOf('\n');
+            if (newline < 0)
+                break;
+            const line = buffer.slice(0, newline);
+            buffer = buffer.slice(newline + 1);
+            bytes = Buffer.byteLength(buffer);
+            if (!line.trim())
+                continue;
+            try {
+                const r = JSON.parse(line);
+                if (!r || r.jsonrpc !== '2.0' || typeof r.id !== 'number' || !pending.has(r.id) || Object.hasOwn(r, 'result') === Object.hasOwn(r, 'error'))
+                    throw Error();
+                const p = pending.get(r.id);
+                if (Object.hasOwn(r, 'error') && (!r.error || typeof r.error !== 'object' || typeof r.error.code !== 'number' || !Number.isInteger(r.error.code) || typeof r.error.message !== 'string'))
+                    throw Error();
+                pending.delete(r.id);
+                if (r.error)
+                    p.reject(new InsightCommandError(r.error));
+                else
+                    p.resolve(r.result);
+            }
+            catch {
+                fail('Persistent CLI returned a malformed or uncorrelated response.');
+                return;
+            }
+        }
+    });
+    await new Promise((resolve, reject) => { child.once('spawn', resolve); child.once('error', () => reject(new InsightTransportError('Could not start persistent CLI.', false))); });
+    return {
+        execute(argv) {
+            if (!Array.isArray(argv) || argv.length > 512 || argv.some(x => typeof x !== 'string' || x.includes('\0')) || Buffer.byteLength(JSON.stringify(argv)) > 1024 ** 2)
+                return Promise.reject(new TypeError('argv must be a bounded array of strings without NUL.'));
+            if (!accepting || failed || ended)
+                return Promise.reject(new InsightTransportError('Persistent CLI connection is closed.', false));
+            const args = [...argv];
+            const request = tail.then(() => {
+                if (failed || ended)
+                    throw new InsightTransportError('Persistent CLI connection was lost before dispatch.', false);
+                const id = ++sequence;
+                return new Promise((resolve, reject) => {
+                    pending.set(id, { resolve, reject });
+                    try {
+                        child.stdin.write(JSON.stringify({ jsonrpc: '2.0', id, method: 'cli.execute', params: { argv: args } }) + '\n');
+                    }
+                    catch {
+                        fail('Persistent CLI input was lost; inspect request/status before retrying a changing command.');
+                    }
+                });
+            });
+            tail = request.catch(() => { });
+            return request;
+        },
+        close() {
+            accepting = false;
+            return closePromise ??= tail.then(async () => { if (!failed && !ended)
+                child.stdin.end(); await exited; });
+        }
+    };
+}

package/skill-bundle/insight-ghidra/references/persistent.md

@@ -0,0 +1,50 @@
+# Persistent research calls
+
+For a sequence of CLI research calls, keep one `insight-cli --json-rpc` frontend alive in the
+agent's long-lived JavaScript runtime. The Factory owner and Ghidra processes have their own
+lifetime; retaining only the owner still makes a new frontend validate its installed build.
+
+The package exports a small stdio client, independent of the facade's eager imports:
+
+```js
+import {connectInsight, InsightCommandError, InsightTransportError}
+  from '@eyeauras/insight-cli/persistent';
+
+const cli = await connectInsight({executable: 'insight-cli', cwd: projectDirectory});
+const result = await cli.execute([
+  'ghidra', 'functions', 'inspect', '--session', session, '--target', target,
+  '--function', 'main', '--fields', 'entry_point', '--include-call-context', 'false'
+]);
+// Keep cli for subsequent calls in this investigation.
+```
+
+When package-name resolution is unavailable in the agent host, dynamically import the
+[`persistent-client.mjs`](persistent-client.mjs) beside this reference by its absolute file URL.
+It is generated from the same canonical package module. In a persistent REPL retain `cli` as a
+binding across tool invocations. A new Node process per query does not retain this connection.
+For an explicit installed bin, use `{executable: process.execPath, arguments: [installedBin], cwd}`.
+`env` optionally supplies the child environment. There is no shell or separate profile/config.
+Use existing `--profile` argv flags when selecting a profile explicitly.
+
+`execute(argv)` returns the CLI result unchanged, without a JSON-RPC envelope. Calls are queued
+in admission order. Native work can be long: await the original promise through the agent host's
+existing wait facility. This V1 client deliberately has no per-request timeout or automatic
+reconnect/retry. Factory permissions, command validation, IDs and native budgets remain authoritative.
+
+* `InsightCommandError.rpc` preserves the JSON-RPC error code, message and data, including typed
+  CLI error results. A command failure leaves a healthy connection usable for the next command.
+* `InsightTransportError.dispatched === true` means the request was handed to the stream and its
+  acknowledgment is unavailable; it does not prove execution. Changing commands require their
+  existing request-ID/status recovery. The client never resends them.
+* `dispatched === false` means this client did not send that request, including queued requests
+  after a transport failure. Reconnection is an explicit new connection, not an implicit replay.
+
+The client bounds each response line to four MiB, validates IDs and envelopes, and fails the
+connection on malformed, uncorrelated or oversized replies. It drains stderr without retaining
+arbitrary native diagnostics in memory. Read command-level diagnostics from their typed results
+and the existing profile diagnostic locations.
+
+Finish owned Ghidra contexts with the normal scoped commands, following the project's shared
+server policy. Then `await cli.close()` drains already admitted requests and ends this stdio
+connection. It does not issue `ipc-server stop`, close another agent's context or stop a server.
+Do not call close while expecting to admit more requests.

package/skill-bundle/insight-ghidra/references/query-semantics.md

@@ -51,6 +51,18 @@ finding. Narrow the query or raise its budget within the declared bound. Oversiz
 also stop a scan rather than silently claiming complete coverage. Returned string values are
 bounded; check truncation fields.
 
+`strings list` and `strings search` visit **defined data**, not every possible literal in memory.
+The visited-input budget includes non-string data. Zero matches with an incomplete scan means
+the searched prefix contains no matches; it does not establish absence. Increasing `--offset`
+only skips matching rows from that same scan and cannot reach a later unscanned string. These
+scans have no continuation cursor. Increase `--max-scan` up to 200000 when that covers the
+needed data. A narrower text filter alone does not skip earlier visited data or reach beyond
+that bound; use an explicitly addressed memory search when the needed region is known.
+For undefined ASCII/UTF-16 literals, encode the expected bytes and use
+`analysis search-byte-patterns --pattern <hex> --max-bytes <bytes>`; that separate initialized-
+memory search exposes `--scan-from`/`next_address` continuation. Byte matches still need
+interpretation and do not define string data or prove a stored xref exists.
+
 Bounded string/instruction regex search supports literals, escapes, anchors, character classes
 and at most one `.*` wildcard. Branching/nested repetition and unsupported patterns are rejected.
 Use the literal `strings search --contains` convenience when no regex is needed.

package/skill-bundle/insight-ghidra/references/recovery.md

@@ -24,11 +24,47 @@ establishes that the old owned bootstrap worker has ended, then uses an authorit
 probe. An absent canonical item permits private preparation; an existing first version requires
 independent readback. The old project, intent and original session/target remain preserved.
 
+## Interrupted save or close
+
+After restoring profile storage, inspect the selected session and target with
+`sessions status <session> --target <target>`. Retry the original save/close with the
+same `--request-id`. If the original command had no caller ID, use the generated
+`unresolvedRequests[].id` from status. This retrieves the original intent instead of
+creating another close. A verified stopped worker lets close report `state: closed`
+and retain the acknowledged private snapshot and pending changes; it sends no new save,
+open, close or publication. Reopen the same session/target afterward.
+
+If release cannot be proved, the command still fails with `coordinator.unknown`
+and gives scoped status/process inspection commands. An authenticated live worker is not
+closed again automatically. Retain its project and journals. After inspecting its retained
+work, an operator may terminate that exact owned headless worker through
+`tools processes kill <process>` with Destructive permission, accepting loss of any
+unacknowledged in-memory work. Do not kill by guessed PID/port or stop the shared server.
+Retrieve the same close request after that worker has ended. An unavailable endpoint or
+changed process receipt is not proof of release; preserve the binding for investigation.
+
 If a response was lost, inspect `sessions status <session> --target <target>`. Never infer
 `applied` from a connection failure. A changing command's optional request ID binds one effective
 intent inside the profile. Repeating the same ID/input retrieves its recorded outcome or
 unresolved state; changing input under that ID fails. Without an ID, calls are new intentions.
 
+For Java `scripts run-inline`, a versioned native executor records compilation, non-initializing
+class resolution, initialization, construction and framework execution separately. A correlated
+receipt proving `userCode: not_started` and `entrypointInvoked: false` before initialization
+produces `state: rejected` with a terminal failed request. The context remains available and
+its prior saved/pending work is unchanged. The CLI exits nonzero; the error result retains
+bounded compiler/load diagnostics. Repeating that request ID retrieves the same rejection;
+corrected source requires a new ID. Each attempt has isolated source/classes under profile
+analysis storage, with annotation processing disabled and no reuse of older inline classes.
+
+Initialization or constructor failure can have effects even when `run()` was never called.
+These failures, framework/runtime failures and missing/malformed/lost acknowledgements remain
+unknown. During framework execution `entrypointInvoked: null` means actual `run()` entry was
+not independently observed. Console text cannot establish non-execution. This is not a sandbox
+for adversarial same-JVM Java, and existing unknown script attempts are not reclassified from
+their exception strings or an unchanged program snapshot. File/Python scripts retain their
+existing conservative recovery semantics.
+
 An unknown or partial effect retains its request intent, snapshots and native stage. Open the
 same tuple to reconcile supported outcomes. A committed merge is verified against its recorded
 server version and complete saved buffers through independent read authority; it is never

package/skill-bundle/insight-ghidra/references/research.md

@@ -17,6 +17,13 @@ Open input with `insight-cli ghidra open ./client.exe --session new --json`. Sto
 `session` and `target` as the explicit scope for every later research call. Names are display
 labels; equal filenames or addresses in different inputs do not select the same object.
 
+If the database has missing strings/xrefs, one-byte function bodies or no Listing instructions,
+use [sparse navigation](sparse-navigation.md) before following the metadata-only route below.
+It distinguishes existing entries, undefined code and undefined literals. For raw literals,
+use `strings anchors --text Widget --encodings ascii,utf16le --scan-from START --scan-through END`,
+then explicit batched code references and function inspection. Candidate context remains
+separate from exact match addresses; coverage, decoding, caps and cursor are explained there.
+
 Use `ghidra strings search --contains config.json`, then `ghidra xrefs to --address <string>`.
 Reference results include a containing function address when available. Pass that address to
 `ghidra functions get` or `ghidra functions decompile`. Add the same session/target selectors and
@@ -105,6 +112,19 @@ native, a sanitized diagnostic of at most 500 Unicode characters. Reasons distin
 `function_not_found`, `native_function_failure`, `selector_mismatch`, `invalid_native_shape`,
 `missing_signature` and `missing_decompiler_text`. Missing definitions remain failures; reads
 never create functions or run analysis. JSON-RPC `cli.execute` preserves the same error data.
+If executable bytes are known but the function is absent, use the read-only `functions decode`
+command below at the explicit address. A containing function with a one-byte body and missing
+stored xrefs can also indicate sparse metadata. Decode reveals bounded local instruction flow;
+it does not repair function boundaries or establish whole-function callers/callees. Defining
+functions or disassembling the listing requires a separate explicit Update operation.
+For a known existing entry, try compact `functions inspect` first; use
+`functions force-decompile --function <entry>` to refresh stale/failed decompiler output.
+Its result is `value.decompiled`, and its pinned upstream work bound is not guaranteed.
+Successful transient decompilation can coexist with an empty Listing and missing stored xrefs.
+It does not create an absent function or repair its saved body. Avoid repeating it merely to
+populate `functions disassemble`; use bounded `decode` for local instruction corroboration.
+Per-item inspection failures retain the facade recovery message in `error` and the bounded
+native explanation separately in `nativeDiagnostic`; use stable `reason` for classification.
 
 The existing `functions inspect` accepts 1–20 distinct names/addresses. Existing `--fields`
 remain valid; unknown fields fail before dispatch. Decompiled text uses per-item
@@ -129,6 +149,32 @@ host, including through JSON-RPC; it is never silently a client-host path. An ex
 is rejected. A filesystem failure can leave a partial new directory without a completed manifest;
 retain it for inspection and choose a fresh directory for another explicit save.
 
+For sparse interior addresses, opt in to
+`functions inspect --functions <hex-addresses> --resolve-address containing-or-preceding --max-entry-distance 4096`.
+The distance is required (1–65536 bytes), applies only to fallback and is rejected without the
+mode. Names/address-space prefixes are not accepted in this mode. Exact entries and recorded
+body containment take precedence in valid default-space memory, including non-executable or
+uninitialized blocks. Otherwise the nearest previous known entry is considered only inside
+the same initialized executable memory block as the query.
+No byte search, analysis or function creation is performed.
+
+Every resolved row retains `entry_point` and `resolution`, even if `--fields` omits entry metadata
+or the function read fails. Kinds are `exact-entry`, `recorded-containing` and
+`preceding-entry-candidate`. `recordedBodyContainsAddress` is actual stored body membership,
+not semantic proof. `distanceBytes` is zero for exact entries and the positive offset for
+preceding candidates; it is omitted for recorded containment, whose body can precede its entry.
+`status: success` means the selected function was read, not that the query belongs to it.
+
+`--functions` preserves original selector spelling as keys, including hexadecimal aliases.
+Selected entries are deduplicated for native reads, but inline text is charged for every
+original row in selector order. Each saved row keeps its mapping; owner-save paths remain
+per-selector. `--function` retains the existing single-row result/error behavior. Policy misses
+are per-item `not_found` with `address_out_of_range`,
+`address_not_in_initialized_executable_block`, `no_preceding_entry`, `entry_outside_block` or
+`entry_distance_exceeded`; these do not claim that code or an unknown function is absent.
+The before/after guard covers both lookup and inspection, and native selector/entry mismatches
+fail. Existing view continuation/text hashes, text windows and result/file bounds still apply.
+
 `functions decode --address <address> --max-bytes 64 --max-instructions 16` uses Ghidra pseudo
 instructions without defining listing instructions, functions or xrefs, running analyzers or
 saving state. It requires initialized executable memory and currently supports x86 language
@@ -139,3 +185,44 @@ computed from instruction bytes, not proof of function membership or stored xref
 flow has no invented target. Decoding stops at terminal/unconditional flow, input/instruction
 bounds, undecodable/truncated bytes or unavailable context. Existing `disassemble-bytes` remains
 an Update operation with its original guards.
+
+## Navigation and lifecycle diagnostics
+
+`analysis navigation` uses the selected session/target and ReadOnly permission. It reports
+`initialAnalysis` (`none` or `requested`) as the original facade import policy, separately from
+the current metadata observations. Prior analysis history is unknown, including saved/imported
+databases. `ready` means the context opened; it does not establish analysis completeness.
+
+The diagnostic samples at most 128 functions, instructions, stored references and defined-data
+units per category, in address order, sharing `--max-scan` (default 10000, 1–200000) and a fixed
+five-second native deadline. Each category reports its own completion; top-level `scan` reports
+the visited sum, sample bound, completion and reason. Defined-string counts cover only sampled
+defined data. One-byte bodies together with missing entry instructions in at least 80% of the
+sample yield `sparse-metadata`; this is an explicit heuristic, not proof that a specific analysis
+pass failed. Normal instruction-bearing one-byte leaf functions alone do not trigger it.
+Follow [sparse navigation](sparse-navigation.md): known function entries can use compact inspection
+and cache refresh; executable bytes without an entry use bounded decode, undefined literals use
+byte search and explicit continuation. The diagnostic does
+not run analyzers, define data, repair boundaries, save a snapshot or certify semantic completeness.
+
+`diagnostics lifecycle` reads retained start/restore/stop events and the current process receipt
+without starting or probing Ghidra. At most the latest 128 observations are retained. A stopped
+receipt can identify `explicit_close`, `view_replaced`, `mode_changed`, `startup_failed` or
+`owner_dispose`; historical receipts without reasons remain `unknown`. Owner disposal does not
+establish whether Factory exited due to idle, explicit stop, a signal or another cause. A current
+receipt without a matching stop receipt reports `unobserved`, not a claim that the PID is live.
+
+Internal correlated timing diagnostics live under profile workspace `diagnostics/timings.jsonl`,
+with one previous segment and an eight-MiB rotation threshold. They contain operation names,
+timestamps, correlation/parent IDs, duration and success/failure, not argv, source, payloads or
+exception text. They are an internal troubleshooting format, not a public trace API. Nested spans
+must not be added to their parents. `facade.command` starts at the handler and ends before Factory
+serializes the response; client startup, IPC and response overhead are not separately measured.
+Tracing is best-effort and cannot change program outcomes. Empty runtime readiness checks still
+avoid creating a research workspace. The Factory idle policy remains unchanged.
+
+For sparse PE32+/AMD64 interior addresses, `functions inspect --resolve-address
+containing-or-pe-runtime --max-unwind-bytes 4194304` uses fully validated current mapped runtime
+regions and independent recorded-body facts. Conflicting or missing entries remain partial with
+evidence; incomplete/malformed/unavailable metadata prevents automatic selection. This is not
+semantic function reconstruction; see [sparse navigation](sparse-navigation.md).

package/skill-bundle/insight-ghidra/references/setup.md

@@ -11,7 +11,7 @@ external executable paths, status/doctor and safe removal. Existing Factory prof
 The package contains the verified GhidraMCP 7.0.0 bridge, its Apache-2.0 license/notice and
 artifact provenance. Its pinned functionality catalog is from source
 `57e37a8bf388b1279cff46378f85be1554548f61`, with SHA256
-`7084e2fda16dc779dd05398e48821ff3f9ace4d32757ea143b257b39689e5fbd`.
+`f4a9272e911466ed774c8cf73bc1adf1daef6009d895fda57aa0b28522fcdf32`.
 `mcpJar` optionally selects another copy of those exact verified bytes. Runtime startup needs no
 bridge/Factory source checkout or Python MCP bridge. Packaged native helper sources compile
 against the installed Ghidra/JDK.

package/skill-bundle/insight-ghidra/references/sparse-navigation.md

@@ -0,0 +1,173 @@
+# Navigate a sparse database
+
+Function counts and `ready` do not establish decoded bodies, strings or xrefs. A one-byte
+function entry without Listing instructions can still be useful to the decompiler. Choose
+the route from the actual observation before building a script or requesting broad analysis.
+
+All examples below need the same `--session S --target T --json`. Replace placeholder
+addresses with observed addresses in that input; symbols and offsets never transfer implicitly.
+Use generated help for exact flags.
+
+| Observation | Next command | What it establishes |
+|---|---|---|
+|Empty navigation results / suspicious body sizes|`analysis navigation`|Bounded metadata samples and coverage; no analysis is started|
+|Known function entries, even without Listing|`functions inspect --functions 0xENTRY_A,0xENTRY_B --fields decompiled_code,callees --include-call-context false`|Up to20 compact decompiler observations; inspect each status and truncation|
+|Interior code addresses with sparse saved bodies|`functions inspect --functions 0xCODE_A,0xCODE_B --resolve-address containing-or-preceding --max-entry-distance 4096 --fields entry_point,decompiled_code --include-call-context false`|One guarded lookup+inspection; a preceding entry is explicitly a candidate, not established containment|
+|Stale/failed decompilation at a known entry|`functions force-decompile --function 0xENTRY`|Fresh native decompiler output in `value.decompiled`; no function creation or Listing repair|
+|Known executable bytes, no function entry|`functions decode --address 0xCODE --max-bytes 64 --max-instructions 16`|Bounded local instructions/direct targets, input hash and stop reason; no persistent definitions|
+|Expected literal absent from defined strings|`strings anchors --text SPARSE --encodings ascii,utf16le --scan-from 0xREGION_START --scan-through 0xREGION_END`|Exact raw hits plus separate bounded NUL candidate context, explicit coverage and stateless cursor|
+
+## Follow existing entries first
+
+Start with a small set of independently known entries: exported symbols, retained project
+evidence for this exact build or direct targets from bounded decode. Check the function selector;
+an interior address is not automatically an entry. Compact inspection avoids unrelated metadata
+and supports mixed outcomes, text paging and owner-host saves. For large output, use
+`--save-owner-directory <new-absolute-directory>` and retain its hash manifest; see
+[research](research.md) for Unicode windows, view guards and native truncation.
+Empty `callees` or xrefs on a sparse database do not prove that the decompiled function
+has no calls. Keep decompiler observations distinct from stored-reference coverage.
+
+For known interior addresses, the explicit resolution mode avoids the separate name/prefix
+search. It accepts addresses only and requires the distance bound. Inspect `resolution.kind`
+for every result: `exact-entry`, `recorded-containing`, or `preceding-entry-candidate`.
+Recorded containment is a database fact, not validated source membership. The fallback may
+point into unrelated padding, split code or an incorrect prior function. It is not a repair.
+Exact/recorded containment take precedence; the distance limit applies only to fallback.
+See [research](research.md) for mixed outcomes, original selector keys and shared budgets.
+
+Use `force-decompile` when a fresh decompiler pass is needed. It does not accept the inspect
+text-window/save flags; its ordinary query response is capped at1MiB and reports the pinned
+upstream work bound as not guaranteed. Selecting one entry narrows the request but is not a
+hard instruction/CPU bound. A host running-session ID must be awaited, not retried as failure.
+No successful decompile is proof of complete control flow, correct types or valid function bounds.
+
+After transient decompilation, `functions disassemble`, instruction search and stored xrefs can
+remain empty. Repeating cache refresh does not populate them. Corroborate an important store,
+branch or call with bounded `decode` at its observed instruction address. Its direct targets are
+local decoded flow, not a complete call graph. Neither route runs the target program.
+
+## When entries or literals are absent
+
+An absent function stays absent after `force-decompile`. Use bounded decode, retaining its
+stop reason; do not silently create functions to make a read succeed. Decode stops at terminal
+or unconditional flow and has byte/instruction limits; it is not whole-function reconstruction.
+Persistent Listing/entry/body repair is a separate explicit Update operation in the owned
+context, followed by saved readback. Consult `functions create`, `functions disassemble-bytes`
+and their generated help rather than an unbounded all-function reconstruction script.
+
+For literal search, prefer `strings anchors` with explicit encodings and both inclusive bounds.
+It searches raw initialized bytes, merges adjacent initialized blocks, and never bridges a hole.
+Read `matchAddress` as the exact target; a nullable candidate `start` is a separate observation.
+NUL candidates are not semantic strings. `textFrom` is the preview address; `complete`,
+boundary evidence and `decoding` qualify it. Invalid or capped context keeps the raw hit.
+Continue using `value.cursor`; only page budgets can change. `scan.complete` refers to search
+coverage, not complete candidate text. Context/prefetch/rereads consume `max-bytes` (minimum
+32768), and the default payload cap is 1024 bytes. Retain all `(address,encoding)` pairs,
+including overlaps and UTF-16 at odd addresses. It performs no definitions, analysis or save.
+Then pass selected exact match addresses to one batched `analysis code-references`, and
+selected code addresses to `functions inspect` with the explicit resolution mode above.
+
+For arbitrary masked binary patterns, encode ASCII/UTF-16 as appropriate with the existing
+`analysis search-byte-patterns`; for example `--pattern '53 50 41 52 53 45'` is ASCII `SPARSE`.
+Quote spaced hex patterns. Read `complete`, `scanned_bytes`, `next_address` and the bounds;
+continue with `--scan-from <next_address>`. `--offset` on defined-string results does not
+advance memory coverage. A narrowed text filter does not skip earlier non-string defined data.
+Use `memory list` to identify initialized/executable blocks; do not assume a guessed block name
+or that the image-base address belongs to executable code.
+
+Byte matches are not validated code references. Existing xrefs describe saved DB metadata.
+For exact RIP-relative operands or direct CALL destinations, use the bounded ReadOnly candidate
+scanner below. Arbitrary scripts remain potential writes with saved-state/recovery costs;
+a compile/transport error must not be blindly replayed.
+
+## Raw-byte code-reference candidates (V1)
+
+```sh
+insight-cli ghidra analysis code-references --session S --target T \
+  --to 180080000,180080008 --forms call-rel32,lea-rip,mov-rip,call-rip-slot \
+  --scan-from 180000000 --scan-through 18002101f --limit 100 --json
+```
+
+`value.matches` contains instruction bytes, full length, operand index/width, exact target,
+form, native instruction text and boundary evidence. Example row:
+
+```json
+{"from":"180000060","to":"180080008","form":"call-rip-slot","bytes":"ff15a2ff0700","length":6,"operand_index":0,"operand_bits":64,"target_role":"pointer-slot","validation":"decoded","boundary":"unconfirmed","instruction":"CALL qword ptr [0x180080008]"}
+```
+
+Targets are
+1–64 distinct default-space unsigned 64-bit addresses, comma separated; they share one pass.
+Only x86 little-endian 64-bit languages with known 64-bit decode mode are supported. No code
+executes, and no Listing instructions, functions or xrefs are created. This does not follow
+register values, indirect callees, thunks, pointer contents or control flow.
+
+| Form | Supported encoding | Target role |
+|---|---|---|
+| `call-rel32` | E8 + signed rel32 | `direct-call-target` |
+| `lea-rip` | 8D, ModRM RIP-relative | `effective-address` |
+| `mov-rip` | GPR MOV 88/89/8A/8B, ModRM RIP-relative | `effective-address` |
+| `call-rip-slot` | FF /2, ModRM RIP-relative | `pointer-slot` |
+
+Forms default to all four; `--forms` restricts them. Legacy 66/26/2E/36/3E and REX prefixes
+are admitted only when the native full decode agrees with the constrained encoding/length.
+REX before a later legacy prefix is reset. Widths are explicit: `lea eax` and `lea rax` remain
+distinct. V1 excludes 67 address override, FS/GS, LOCK/REP, C6/C7 immediate MOV,
+MOVSX/MOVZX/MOVSXD and SIMD/VEX/EVEX **at that candidate start**. A later byte inside any
+instruction or immediate can independently decode as a supported candidate.
+
+Each byte offset is tested, including overlapping and prefix-alternative starts; advancement
+is one byte. `listing-confirmed` requires a matching stored instruction and compatible bytes,
+length and operand display. `listing-conflict` means overlap/disagreement with a stored
+instruction. `unconfirmed` means neither. Even listing-confirmed is not proof of execution,
+function membership or a complete call graph. LEA is an effective address, not a memory read.
+
+`--scan-through` is the inclusive final byte, and each match fits entirely inside the original
+range. Only initialized executable default-space memory is visited. Adjacent eligible blocks
+merge so an instruction may cross their boundary; holes, uninitialized blocks and non-executable
+memory never bridge. A complete scan only exhausts this declared eligible input/form set.
+
+`value.scan` reports `bytes_read` (including lookahead and rereads), `tested_starts`,
+`visited_candidates` (selected-form encoding prefilter hits, including target/decode rejects),
+`next_start` (first unchecked start), `complete`, `reason` and native `elapsed_ms`.
+The frontier can skip ineligible gaps; it does not assert that gap bytes were decoded.
+Reasons are `exhausted`, `byte_limit`, `candidate_limit`, `timeout` and `result_limit`.
+The native cooperative deadline is checked even in no-match regions. Compile/dispatch/view
+observation time is outside that deadline; it remains part of command wall time.
+
+Defaults: 4MiB bytes, 200000 candidates, 5 seconds and 100 matches. Maxima: 16MiB,
+1000000 candidates, 30 seconds and 1000 matches. Minimum byte budget is15, so a maximum-length
+x86 start can progress with its lookahead. No semantic completeness is implied by these limits.
+
+For an incomplete result, continue with the opaque stateless token:
+
+```sh
+insight-cli ghidra analysis code-references --session S --target T \
+  --cursor TOKEN --limit 1000 --max-bytes 8388608 --json
+```
+
+Cursor excludes `--to`, `--forms`, `--scan-from` and `--scan-through`; omitted controls inherit
+the previous page. It binds the normalized original query, frontier, algorithm version, selected
+context/snapshot/generation, native modification observation and process incarnation. Scope,
+format or version mismatch fails; view changes, including restoring the same snapshot in a new
+JVM, fail with `changed_view`. Start a new query after such a change. Before/after observations
+share the context's ordered action; a native modification guard additionally covers the scan.
+
+Tokens are unsigned, untrusted continuation parameters, not evidence that earlier offsets were
+scanned. There is no cursor registry, per-query snapshot or journal save. Retain page results
+if coverage evidence is needed. The trusted helper still uses the existing inline-script
+transport and incurs its compile/dispatch cost; arbitrary user scripts remain Update operations.
+
+## PE runtime regions for sparse function inspection
+
+Use `ghidra functions inspect --functions <addresses> --resolve-address containing-or-pe-runtime`
+when PE32+/AMD64 runtime metadata can replace manual preceding-entry checks.
+`--max-unwind-bytes` bounds returned header/table bytes across the batch (default4194304,
+1–16777216); lookup has a fixed5-second cooperative deadline. It reads current mapped headers
+at the actual image base and the whole declared Exception Directory, without a file fallback,
+section-name assumption, analysis or function creation. Unavailable/malformed/incomplete lookup
+blocks selection and retains DB facts; `boundary_conflict` and `runtime_entry_not_defined` retain
+validated bounds. A runtime region does not prove instruction boundaries, semantic membership
+or whole-function bounds; leaf routines may have no record. No preceding fallback is used.
+Batch unresolved rows are partial; a single unresolved selector returns a partial CLI error
+with lookup/view/evidence. Guards cover failed dispatch; existing text paging/save rules apply.

package/skill-bundle/insight-ghidra/references/storage.md

@@ -1,10 +1,19 @@
 # Analysis storage and migration
 
 `storage show --json` reports effective profile storage, availability, active file/byte usage,
-exact included trees and retained migration. The default is Factory profile AppData. No
-checkout, environment or automatic disk fallback changes it. The non-secret setting is
-`analysisDirectory` in Factory's profile (`profile show` also displays it). Use storage commands
-to change it safely.
+exact included trees, retained migration and installation default base. Before selecting a
+base, storage starts in Factory profile AppData. `configure` and `migrate` select that base
+for subsequent new/empty profiles as well as moving the current profile. Add `--profile-only`
+to keep the installation default unchanged. The effective root appends `insight-cli/<profile>`.
+Initialized profiles keep their existing locations when the default changes; profiles with
+ordinary AppData analysis trees stay there until explicitly migrated.
+
+The per-profile non-secret `analysisDirectory` setting remains in Factory's profile. The
+installation default is bound storage-control metadata beside Factory's profile store, paired
+with ownership metadata on the chosen base. It is not an environment or checkout setting.
+Missing/replaced storage fails before creating analysis data; there is no system-disk fallback.
+New profiles initialize on their first ordinary command, durably bind their own empty directory,
+and keep permanent compatibility paths. `storage show` remains passive.
 
 ```sh
 insight-cli permissions grant Update
@@ -29,7 +38,20 @@ user-selected outputs outside these trees keep their locations.
 
 Factory keeps profiles, permissions, IPC election/socket, migration-control metadata and
 application logs in current-user AppData. Secrets stay in the OS keyring. Credential/profile
-identities do not change. Updating/installing npm never migrates a profile automatically.
+identities do not change. Updating/installing npm preserves existing profile locations and does not select a disk on its own.
+
+## Select a default after an earlier migration
+
+For installations migrated with an older CLI, select their existing mounted base once:
+
+```sh
+insight-cli storage default --directory "/mnt/analysis volume" --json
+```
+
+This Update operation changes the installation default without moving existing data. Future
+profiles inherit it without repeating configuration. The base cannot be inside a profile data
+root or overlap Factory control storage. A base owned by another installation is rejected.
+A missing volume or replaced base/ownership marker is never adopted automatically.
 
 ## Move an existing profile
 
@@ -44,7 +66,7 @@ insight-cli storage migrate --directory "/mnt/analysis volume" --json
 insight-cli storage show --json
 ```
 
-Dry-run checks separation, destination contents, access, conservative capacity and quiescence
+Dry-run reports whether it would select the installation default and checks separation, destination contents, access, conservative capacity and quiescence
 without reserving/copying a migration. Source/destination/configuration roots cannot be equal
 or nested. Destination symlink roots, escaping source links, special files, unresolved links
 and inventories above one million entries or 128 directory levels are rejected. Internal
@@ -72,7 +94,9 @@ file, rechecks capacity and finishes the retained transaction. Source and destin
 anchor identities are bound durably. Missing/replaced volumes fail without creating a system-disk
 fallback; mount the original volume before resuming.
 
-Rollback restores retained source and the prior Factory setting. After activation it requires
+Rollback restores retained source and the prior Factory setting. The installation default stays
+selected because subsequent profiles may already use it; a resumed older migration cannot
+overwrite a newer default selection. After activation it requires
 an unchanged destination and a verified retained source. Native reopening or later findings can
 make rollback unsafe, in which case it refuses and preserves both copies. Use forward migration
 to another empty base after using the new location. A rolled-back destination remains for manual
@@ -97,3 +121,7 @@ before starting another. This release provides no nonempty-destination adoption,
 synchronization, live-DB snapshotting or network-filesystem guarantees. POSIX directory fsync
 is used. Windows has file fsync and rename/junction semantics; Node cannot fsync directories
 there, and internal symlinks can require OS privileges.
+
+Empty-profile initialization resumes automatically on its next command after interruption. Its
+retained source contains no analysis entries, so the CLI cleans only that owned empty backup
+automatically. Migration of existing data always retains its source for explicit cleanup.

package/skill-bundle/insight-ilspy/SKILL.md

@@ -3,7 +3,7 @@ name: insight-ilspy
 description: Recover C#, inspect IL/types/metadata, extract resources or export projects from managed .NET assemblies through insight-cli ILSpy. Choose native analysis for NativeAOT or ordinary PE machine code.
 ---
 
-# Insight ILSpy 0.3.1
+# Insight ILSpy 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

package/skill-bundle/insight-interop/SKILL.md

@@ -3,7 +3,7 @@ name: insight-interop
 description: Trace a .NET P/Invoke declaration to an explicitly supplied native library export and Ghidra function through insight-cli ilspy query, binary query and scoped ghidra APIs. Use for managed/native linkage evidence while keeping static correspondence separate from observed loading or execution.
 ---
 
-# Insight Interop 0.3.1
+# Insight Interop 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