@eyeauras/insight-cli 0.3.2 → 0.4.1

package/skills/insight-re/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/skills/insight-re/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-sevenzip/SKILL.md

@@ -3,7 +3,7 @@ name: insight-sevenzip
 description: Inventory, integrity-check and recover files from archives and supported containers with insight-cli 7-Zip, then hand recovered binaries or configuration to the appropriate research tool.
 ---
 
-# Insight 7-Zip 0.3.2
+# Insight 7-Zip 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-strace/SKILL.md

@@ -3,7 +3,7 @@ name: insight-strace
 description: Observe actual file reads, writes, process creation and network syscalls in an authorized owned native Linux launch using insight-cli strace. Use when static inference needs concrete operating-system interaction evidence.
 ---
 
-# Insight strace 0.3.2
+# Insight strace 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-tshark/SKILL.md

@@ -3,7 +3,7 @@ name: insight-tshark
 description: Inspect an offline PCAP or PCAPNG with insight-cli tshark to identify protocols, HTTP/DNS/TLS fields, packet evidence and reconstructed TCP/UDP streams. Use for captured traffic questions; live acquisition and TLS decryption are separate tasks.
 ---
 
-# Insight TShark 0.3.2
+# Insight TShark 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-windbg/SKILL.md

@@ -3,7 +3,7 @@ name: insight-windbg
 description: Investigate Windows native user-mode minidumps using bounded stacks, threads, registers, modules, memory and disassembly through insight-cli windbg. Use on Windows x64 when a captured runtime state needs native debugger evidence.
 ---
 
-# Insight WinDbg 0.3.2
+# Insight WinDbg 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