@eyeauras/insight-cli 0.3.2 → 0.4.1

package/skills/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/skills/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/skills/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/skills/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/skills/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/skills/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.2
+# Insight ILSpy 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

package/skills/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.2
+# Insight Interop 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

package/skills/insight-lldb/SKILL.md

@@ -3,7 +3,7 @@ name: insight-lldb
 description: Observe native runtime arguments, return values, registers, stacks and bounded memory at a selected breakpoint using an owned LLDB launch. Use insight-cli lldb on macOS ARM64 when static findings need a concrete execution check.
 ---
 
-# Insight LLDB 0.3.2
+# Insight LLDB 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

package/skills/insight-llvm/SKILL.md

@@ -3,7 +3,7 @@ name: insight-llvm
 description: Inspect PE, ELF and Mach-O headers, dependencies, exports and symbols; query PDB debug information or a small instruction window with insight-cli LLVM utilities before opening a full analysis project.
 ---
 
-# Insight LLVM 0.3.2
+# Insight LLVM 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

package/skills/insight-managed-heap/SKILL.md

@@ -3,7 +3,7 @@ name: insight-managed-heap
 description: Query structured .NET heap objects, primitive fields and managed stacks from a retained CoreCLR dump through insight-cli dotnet-dump query. Use for bounded offline dump investigation with an explicit matching DAC, preserving uncertainty and immutable input identity.
 ---
 
-# Insight Managed Heap 0.3.2
+# Insight Managed Heap 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

package/skills/insight-managed-metadata/SKILL.md

@@ -3,7 +3,7 @@ name: insight-managed-metadata
 description: Query managed assembly metadata, MethodDef tokens, P/Invoke declarations and bounded IL, or compare two C#/.NET assemblies through insight-cli ilspy query/compare. Use for structured static evidence and changed-method research without executing the target.
 ---
 
-# Insight Managed Metadata 0.3.2
+# Insight Managed Metadata 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

package/skills/insight-mitmproxy/SKILL.md

@@ -3,7 +3,7 @@ name: insight-mitmproxy
 description: Record, inspect and compare HTTP request/response evidence with insight-cli mitmproxy. Use when an owned client can explicitly use a loopback proxy; read native flow archives or HAR without replaying traffic. System interception and global certificate trust are outside this facade.
 ---
 
-# Insight mitmproxy 0.3.2
+# Insight mitmproxy 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

package/skills/insight-overview/SKILL.md

@@ -3,7 +3,7 @@ name: insight-overview
 description: Choose bounded tool overviews and focused drilldown through insight-cli without flooding agent context with whole-program code, traces or dumps. Use for tool discovery, scoped evidence paging and keeping native partial coverage separate from complete results.
 ---
 
-# Insight Overview 0.3.2
+# Insight Overview 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

package/skills/insight-procmon/SKILL.md

@@ -3,7 +3,7 @@ name: insight-procmon
 description: Observe actual file and registry access by an authorized running Windows process through insight-cli procmon. Use when static paths or configuration guesses need runtime evidence; inspect retained captures without collecting again.
 ---
 
-# Insight ProcMon 0.3.2
+# Insight ProcMon 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

package/skills/insight-re/SKILL.md

@@ -3,7 +3,7 @@ name: insight-re
 description: Investigate shipped programs and binary artifacts with insight-cli and other available tools; retain ordinary research files, coordinate independent agents and publish Ghidra annotations. Use for reverse engineering behavior, not ordinary source-repository browsing.
 ---
 
-# Insight RE 0.3.2
+# Insight RE 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
@@ -14,6 +14,9 @@ request/status recovery, never blind retry.
 
 Answer the user's research question with inspectable materials. Agents choose the
 investigation; insight-cli supplies applications such as `ghidra` and `artifacts`.
+
+For repeated facade queries, retain one [persistent client](references/persistent.md) in the
+agent runtime across calls. Follow its typed command errors and uncertain-transport recovery.
 External tools need no insight-cli adapter. Installing this package does not register
 the skill or change agent settings. `insight-cli skill insight-re` locates this file.
 

package/skills/insight-re/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; });
+        }
+    };
+}