@eyeauras/insight-cli 0.1.0 → 0.2.1

package/references/agent-setup.md

@@ -0,0 +1,61 @@
+# Connect the toolbox to an agent
+
+npm installs the CLI and all declared skills. Native tool downloads are separate. A host needs
+shell access to `insight-cli`, skill discovery and execution access to the assigned profile.
+`insight-cli tools list --json` discovers shipped capabilities without profile configuration,
+native runtimes, credentials or IPC. `skill <name>` returns the instructions' ordinary path;
+it does not inject them into an agent automatically.
+
+## Codex: one project-local bundle
+
+The package prepares `skill-bundle`, containing an independent folder for every registered
+skill. `insight-cli skill --json` returns its `bundlePath`. References stay inside each skill;
+link the whole bundle once rather than connecting each tool separately. npm installation
+never edits agent settings or project RE instructions.
+
+With a global npm installation, run from the research project:
+
+```sh
+mkdir -p .agents/skills
+ln -s "$(npm root -g)/@eyeauras/insight-cli/skill-bundle" .agents/skills/insight-toolbox
+```
+
+`ln` refuses an existing destination: inspect it instead of overwriting another skill or
+connection. Local npm installations use the `bundlePath` from their actual CLI receipt.
+These machine-local links are not portable files to commit to a shared project. Start a fresh
+agent and verify all registered names/descriptions appear. The [official discovery contract](https://learn.chatgpt.com/docs/build-skills)
+supports project skills and symlinked directories; our actual host gate must still establish
+recursive discovery for this packaged bundle.
+
+An npm upgrade at the same global prefix replaces the bundle at the same path, including newly
+registered tool skills. Check its manifest/version and start a fresh host session after upgrade.
+A changed npm prefix needs reconnection. To disconnect, inspect `readlink .agents/skills/insight-toolbox`
+and remove only that owned symlink with `unlink .agents/skills/insight-toolbox`; preserve other
+entries and the package. No copied skills, per-tool installer or second agent configuration
+store is maintained. Other hosts may register this ordinary bundle through their own mechanism;
+Codex is the first concrete supported-host gate.
+
+## Execution access
+
+A skill link does not grant filesystem or IPC permissions. Allow the assigned profile's AppData
+and the CLI's `.runtime` directory, plus its exact local IPC endpoint. On macOS the application
+root is `~/Library/Application Support/insight-cli`; its Unix socket is `.runtime/host.sock`.
+Keep unrelated profiles outside the write scope and pass the assigned `--profile` explicitly.
+Do not grant broad external network access merely to reach a local socket.
+
+An inaccessible profile means readiness is unknown. Inspect access failures; stopping a shared
+owner does not grant access to it. Existing restricted-host evaluation has not established a
+complete facade workflow yet; a successful metadata call or filesystem grant alone is insufficient.
+
+## Behavioral acceptance
+
+Give a fresh agent an input and business question without commands/tool names. Verify startup
+metadata, implicit skill selection, intended public-tool use, correct findings, saved ordinary
+project files and cleanup. Ghidra edits additionally require merge and independent readback.
+Repeat cold-runtime and prepared-runtime cases; retain failures and distinguish an external-tool
+fallback from acceptance of the intended adapter. Package/skill existence is structural evidence,
+not proof that a model completed research.
+
+The project bundle is a symlink. A plain `find` does not follow it and can misleadingly
+show no files. Use the host skill inventory, a named `.../<skill>/SKILL.md` path, or
+`insight-cli skill <name>` to check availability; `find -L` follows the link if needed.

package/references/artifacts.md

@@ -24,6 +24,11 @@ files; byte count counts their contents. A file's SHA-256 hashes its bytes; a di
 SHA-256 hashes its canonical manifest of relative paths, kinds, file lengths and hashes.
 The manifest is stored beside the content, outside the returned directory.
 
+Before claiming a verified checkpoint, read the expected files at the returned `path` using
+ordinary file tools. Preserve that path verbatim in the handoff, alongside the receipt;
+profile and snapshot identifiers must not be reconstructed from memory. If access is denied,
+retain the actual receipt and state that readback remains unverified.
+
 The service copies and syncs data before publishing the completed snapshot. Failure does
 not return a successful receipt or expose a partial completed snapshot. Source edits made
 after a successful save do not change the copy. Treat saved copies as retained snapshots;

package/references/debugger.md

@@ -6,6 +6,12 @@ verified copy of the selected immutable input in an owned run directory. It acce
 `--args`, `--cwd`, a bounded launch timeout and the optional request ID. A second live process
 uses another session; it does not replace this context's current process.
 
+For local macOS `lldb`, `--stop-at-entry` launches stopped before normal program startup.
+The response verifies a live `STOPPED` target and reports `stoppedAtEntry: true`. This is
+useful for short programs: inspect/map/set breakpoints, then explicitly resume. Without the
+flag, the existing immediate-run behavior is unchanged. Other offers reject this flag before
+a CPU intent is reserved. An unknown stopped launch still requires ordinary request recovery.
+
 Read `debugger status`, `modules`, `registers`, `stack-trace` and `traces`. Address conversion
 uses `static-to-dynamic` and `dynamic-to-static`; memory and breakpoint commands take dynamic
 addresses. Lists are paged. Read results identify the logical context and current trace, and
@@ -38,3 +44,19 @@ directory are Factory profile settings. Native Windows/Linux acceptance remains
 
 Use generated help for exact flags. A retained static breakpoint bookmark may remain after its live trace placement is
 removed; `trace_location_count` distinguishes current placements from that static metadata.
+
+For a call observation, set the mapped function breakpoint **before** resuming from entry.
+After the stop, check the PC against that address, then capture arguments and stack before
+stepping. Step-out verifies return to the native caller in the same thread and stack;
+return registers are observed without being modified. A competing stop or unavailable caller
+does not count as a verified return. A requested step whose reply
+or observed completion is unknown remains journaled; do not issue another CPU action to
+try to recover a missing return. Retain its diagnostics and use request/status recovery.
+
+For another intentional run, close and reopen the same owned context first: this disconnects
+and retains the previous trace without relaunching it. Then launch with a distinct request ID
+and desired arguments. A connected debugger remains busy even after its subject has exited;
+selecting or reading its old trace is not a request to execute the subject again.
+Map the new process and explicitly set/check its live breakpoints before each resume from
+entry. Old static bookmarks do not establish new trace placements. Reopening restores each
+trace's saved snap/thread, including inactive traces; choose its returned ID with `--trace`.

package/references/ilspy.md

@@ -0,0 +1,33 @@
+# Static .NET research
+
+Use the project's preferred tools and evidence conventions. When ILSpy is appropriate,
+`insight-cli ilspy install` prepares its pinned CLI and private .NET runtime; a global SDK
+or dotnet installation is unnecessary. Lifecycle and archive options appear in `--help`.
+The ILSpy and runtime distributions come from our pinned GitHub Releases. For offline
+installation supply `--archive` and `--dotnet-archive`, or use an already verified cache.
+`--executable` selects a compatible external ilspycmd; uninstall preserves its files.
+
+```sh
+insight-cli ilspy types ./client.dll --json
+insight-cli ilspy decompile --target <returned-target> --type Example.Policy --output policy.cs --json
+insight-cli ilspy il --target <target> --type Example.Policy --json
+insight-cli ilspy resources --target <target> --json
+insight-cli ilspy resource --target <target> --name Example.settings.json --output extracted --json
+insight-cli ilspy project --target <target> --output recovered-project --json
+insight-cli ilspy metadata --target <target> --table MethodDef --json
+```
+
+Use either an input file or an existing target. Reusing the target associates Ghidra and
+ILSpy results with the same immutable bytes. No Ghidra context or merge is needed for a
+stateless ILSpy read. An optional `--session` associates an existing session; it does not
+create one. These calls require Update to capture input and run a tool.
+
+Text responses include `content`, input SHA, process ID, elapsed time and diagnostic paths.
+`--member` selects a metadata token or XML member ID for decompilation. Output paths must
+be new: text operations create one ordinary file, project/resource operations create a
+folder. Keep useful output in the project's chosen evidence location; `artifacts save`
+is an optional explicit checkpoint. Static decompilation does not execute an assembly.
+
+Use `tools processes --tool ilspy --all` for execution history and `tools processes show
+<process-id>` for retained diagnostics. A failed or interrupted export can leave partial
+files/staging; inspect them and choose a new output path for another intentional run.

package/references/managed-runtime.md

@@ -0,0 +1,157 @@
+# Managed Ghidra runtime
+
+Use `ghidra install` for a complete compatible installation. Node 24+ is the bootstrap dependency;
+no existing Java, Ghidra, Homebrew, Gradle, compiler or Python MCP bridge is required. Factory
+profiles, permissions and OS secret storage remain in use. Follow the project's tool rules when
+it specifies an external installation or server.
+
+```sh
+insight-cli profile create local
+insight-cli --profile local permissions grant Update
+insight-cli --profile local ghidra install
+insight-cli --profile local ghidra status
+insight-cli --profile local ghidra open ./client.exe --session new --json
+```
+
+`download` caches the complete pinned Ghidra/JDK archives, without selecting or starting a runtime.
+`install` uses that cache or downloads missing archives, unpacks to a new stage, checks JDK 21 and
+Ghidra 12.1.2, decompiles a known x86 function and starts a disposable local Ghidra Server. The
+server probe authenticates its identity and reader/publisher permissions. Selection changes only
+after all checks pass. The bridge and helper sources come from the version-matched npm package.
+A failed install preserves its stage/diagnostics and the old selection. Retrying uses a fresh stage;
+completed cached archives are reused. A later install/doctor/uninstall authenticates and stops
+any leftover disposable probe server before proceeding; an unverified live identity blocks recovery. Interrupted partial downloads are never used as complete files.
+
+`status` without scope is passive: selection, paths, missing components, installations, retained
+stages, recorded checks and live process receipts. It works before installation. It does not start
+Java or create a research workspace. `status --session S --target T` retains the scoped live health
+check. `server status` also works without an installed runtime and explains missing prerequisites.
+`doctor` explicitly runs disposable native decompiler/server probes and checks macOS LLDB Python.
+It never imports a research target or publishes research changes. Readiness recorded by a doctor
+run includes its runtime fingerprint; status identifies whether that record matches the selection.
+
+## Local archives and external installations
+
+```sh
+insight-cli --profile local ghidra download
+insight-cli --profile local ghidra install --offline
+insight-cli --profile local ghidra install --archive ./ghidra.zip
+insight-cli --profile local ghidra install --archive ./ghidra.zip \
+  --java-archive ./jdk.tar.gz --debugger-archive ./lldb-python.tar.gz --offline
+insight-cli --profile local ghidra install --executable /tools/ghidra/ghidraRun
+insight-cli --profile local ghidra install --executable /tools/ghidra \
+  --java /tools/jdk/bin/java --debugger-archive ./lldb-python.tar.gz --offline
+```
+
+`--executable` accepts the actual Ghidra launcher (`ghidraRun[.bat]`, or
+`support/analyzeHeadless[.bat]`) or installation directory. It needs the complete compatible
+installation, including host native components. A target EXE is not a Ghidra launcher.
+Common Homebrew launcher wrappers are resolved through the adjacent complete `libexec` tree.
+The external Ghidra tree is never modified or deleted. Java is delivered automatically unless
+`--java` or `--java-archive` is supplied. Legacy profile `java`/`ghidraHome` configuration still works
+when no explicit selection exists; an explicit selection takes precedence and never silently
+falls back to profile paths after failure or uninstall.
+
+Local archives are caller-selected inputs, consumed into owned hash-addressed copies before
+extraction so later source edits cannot change the installed bytes. Optional `--archive-sha256` and
+`--java-archive-sha256` and `--debugger-archive-sha256` check the expected bytes; the actual digests are recorded in the installation
+identity. `--offline` prohibits network acquisition: provide/cache every required archive. On macOS,
+an official Ghidra zip also needs the pinned prebuilt native archive in cache. The managed macOS
+distribution already includes these natives. Executable modes are preserved; paths, links and
+expanded sizes are checked during portable Node extraction. Downloads use exact assets retained
+in `iXab3r/insight-cli` GitHub Releases, with hashes and sizes pinned in the installed package.
+There is no runtime upstream/latest fallback; supplied archives and verified cache support offline use.
+No external unzip, tar or Python executable is needed for extraction.
+
+## Server, process and data ownership
+
+The Ghidra distribution includes Ghidra Server. It uses the selected JDK and immutable tool code;
+its repository, certificates, credentials and process settings are separate profile data.
+Ordinary `open` starts it automatically. `server start` explicitly starts/enables it, and
+`server stop` stops the identified owned server after all contexts are closed. It refuses to stop
+a server under live clients. A later open can start it again; explicit `disconnect` disables shared
+operations until `connect`/`start`. `server connect/disconnect` retain their connection-management API.
+An external server remains configured through profile server/repository/account fields and Factory
+secrets; `server stop` cannot stop that external service.
+
+Code/cache/installation receipts live under profile AppData `runtime/`; research remains under
+`workspace/`, and saved files under `materials/`. One selected immutable installation serves many
+isolated JVM contexts; each has its own projects, home, settings, cache/temp and authenticated
+endpoint. No per-agent copy of the Ghidra code distribution is required. This is process and data
+isolation; it does not restrict arbitrary user scripts to an OS security sandbox.
+
+Close scoped contexts and stop the owned server before selecting/reinstalling/removing a runtime.
+A live receipt conservatively blocks these operations; it never authorizes killing a PID.
+Download and doctor can run without switching the current runtime. Runtime commands serialize
+within the Factory owner. Changing a selected runtime invalidates cached backend handles, without
+removing saved research. There is no automatic version migration or floating upstream upgrade.
+
+```sh
+insight-cli --profile local ghidra close --session S --target T
+insight-cli --profile local ghidra server stop
+insight-cli --profile local permissions grant Destructive
+insight-cli --profile local ghidra uninstall
+# Optional cache deletion; research and external installations remain preserved:
+insight-cli --profile local ghidra uninstall --purge-cache
+```
+
+Uninstall removes only selected owned installation files. It preserves the selection as an
+uninstalled receipt, so later research reports a missing runtime instead of changing bindings.
+Archives remain reusable unless `--purge-cache` is selected. It removes recorded archives for
+this installation, preserving other tools' cache and unrecorded legacy entries. Reinstalling the same archives restores
+the same runtime identity. Sessions, private snapshots, unresolved publication journals, server
+repositories and artifacts survive. Uninstall does not resolve an uncertain merge or replay it.
+
+## Process inventory and recovery
+
+```sh
+insight-cli --profile local tools processes --tool ghidra
+insight-cli --profile local tools processes show <process-id>
+insight-cli --profile local tools processes stop <process-id>
+insight-cli --profile local tools processes kill <process-id>
+```
+
+These IDs describe executions, not new research selectors. Context records include the existing
+session/target; server, GUI, debugger and helper roles remain separate. `stop` saves a selected
+Ghidra context through its ordinary close path. Stopping a server requires closed contexts.
+`kill` requires Destructive and explicitly interrupts verified owned work; it does not prove a
+merge/save completed. Live debugger cleanup goes through the owning GUI so inferior termination
+can be verified. Research and unknown journals are retained.
+
+After an owner crash, inventory reconnects to authenticated owned endpoints without re-executing
+research. macOS process birth times alone cannot prove recovered ownership; an ambiguous process
+stays `unverified` and is not signalled. Original child handles and authenticated tool identities
+provide the supported stop/kill authority. This is lifecycle management, not an OS security sandbox.
+
+## Sources and host boundary
+
+The catalog pins Ghidra 12.1.2 and Temurin JDK 21.0.11+10. macOS uses public Homebrew-built Ghidra
+bottles with native components (macOS 14+, ARM64 or x64); no installed Homebrew is used. Linux x64
+and Windows x64 use the official Ghidra zip and Temurin archive. The installed `runtime/tool-catalog.json` pins mirror assets; repository
+`scripts/tool-distributions/` recipes retain upstream provenance. Published tool releases include
+original licenses/notices and required source/build companions, independent of CLI releases.
+Unsupported platforms fail explicitly and may use compatible external profile paths. Native
+acceptance for this delivery is macOS ARM64; catalog availability is not Windows/Linux native proof.
+
+The host provides Node/npm, OS frameworks, display/keychain access and debugger authorization.
+macOS LLDB and its embedded Python come from Apple's developer tools; they are OS prerequisites,
+not downloaded third-party Python dependencies. `doctor` reports a missing host debugger as a partial
+failure even when static analysis/server pass. No root installation, developer-tools installer,
+Gatekeeper disabling, shell-profile edit or global Java/Python selection is performed. Ghidra GUI
+agents receive private copies of the Ghidra SDK's pinned debugger Python wheels.
+
+## Managed debugger dependency
+
+On macOS 15+ ARM64, download/install also prepares pinned LLDB 23.1.3 with its own
+Python 3.15 and native library closure. It is a private Ghidra dependency; the separate
+`insight-cli lldb` application retains its own installation. `--debugger-archive` supplies
+the exact pinned debugger archive for offline installation, including an external Ghidra
+selection. Status reports this dependency and doctor probes its actual Python interpreter.
+GUI startup prepares it for legacy profiles as needed. The backend does not use Homebrew
+or Python from Apple developer tools. OS debugger authorization is still a host prerequisite.
+
+A GUI context pins the verified debugger receipt. Its supervisor verifies those code and
+library bytes again before launching LLDB. Close contexts and stop the local server before
+changing/removing the Ghidra runtime; uninstall removes this owned dependency while retaining
+research and external installations. Existing running GUI contexts must be closed/reopened
+to adopt a different backend. Other host debugger profiles retain their declared host requirements.

package/references/native/InsightPythonWheels.java

@@ -19,13 +19,294 @@ class InsightPythonWheels {
         }
       }
     }
+    // Never wait for remote futures while holding the batch-state mutex: completing
+    // a reply can require a callback which starts another batch. Also close model
+    // transactions/batches on exceptions; these adapters never repeat a CPU action.
+    Path traceClient=root.resolve("ghidratrace/client.py");String traceClientSource=Files.readString(traceClient);
+    String batchEndBefore="""
+        def end_batch(self) -> Optional[List[Any]]:
+            cb = None
+            with self._block:
+                cb = self.cur_batch
+                if cb is None:
+                    raise ValueError("No batch to end")
+                if 0 == cb.dec():
+                    self.cur_batch = None
+                    return cb.results()
+            return None
+    """;
+    String batchEndAfter="""
+        def end_batch(self) -> Optional[List[Any]]:
+            with self._block:
+                cb = self.cur_batch
+                if cb is None:
+                    raise ValueError("No batch to end")
+                if cb.dec() != 0:
+                    return None
+                self.cur_batch = None
+            return cb.results()
+    """;
+    String traceTxBefore="""
+        tx = self.start_tx(description, undoable)
+        yield tx
+        tx.commit()
+    """;
+    String traceTxAfter="""
+        tx = self.start_tx(description, undoable)
+        try:
+            yield tx
+        except BaseException:
+            tx.abort()
+            raise
+        else:
+            tx.commit()
+    """;
+    String batchBodyBefore="""
+        batch = self.start_batch()
+        yield batch
+        return self.end_batch()
+    """;
+    String batchBodyAfter="""
+        batch = self.start_batch()
+        try:
+            yield batch
+        finally:
+            results = self.end_batch()
+        return results
+    """;
+    String[][] tracePatches={{batchEndBefore,batchEndAfter},{traceTxBefore.indent(4),traceTxAfter.indent(4)},{batchBodyBefore.indent(4),batchBodyAfter.indent(4)}};
+    for(String[] patch:tracePatches){
+      if(traceClientSource.indexOf(patch[0])<0||traceClientSource.indexOf(patch[0])!=traceClientSource.lastIndexOf(patch[0]))throw new IllegalArgumentException("Unexpected pinned trace transaction/batch lifecycle");
+      traceClientSource=traceClientSource.replace(patch[0],patch[1]);
+    }
+    Files.writeString(traceClient,traceClientSource);
     // Ghidra 12.1.2's LLDB adapter calls a nonexistent SBProcess.write_memory method.
     // Adapt only the newly extracted owned copy; refuse a different upstream implementation.
     Path methods=root.resolve("ghidralldb/methods.py");String source=Files.readString(methods);
     String original="    proc.write_memory(offset, data)";
     if(source.indexOf(original)<0||source.indexOf(original)!=source.lastIndexOf(original))throw new IllegalArgumentException("Unexpected pinned LLDB memory writer");
     String replacement="    error = lldb.SBError()\n    written = proc.WriteMemory(offset, data, error)\n    if error.Fail() or written != len(data):\n        raise RuntimeError(\"LLDB memory write failed: \" + error.GetCString())";
-    Files.writeString(methods,source.replace(original,replacement),StandardOpenOption.TRUNCATE_EXISTING);
-    System.out.println("{\"state\":\"prepared\",\"lldb_memory_adapter\":\"insight-sbprocess-v1\"}");
+    source=source.replace(original,replacement);
+    String originalStep="    if thread is not None:\n        t = find_thread_by_obj(thread)\n        t.process.SetSelectedThread(t)\n    exec_convert_errors('thread step-out')";
+    if(source.indexOf(originalStep)<0||source.indexOf(originalStep)!=source.lastIndexOf(originalStep))throw new IllegalArgumentException("Unexpected pinned LLDB step-out adapter");
+    String step = """
+        if thread is None:
+            raise RuntimeError("A concrete live thread is required")
+        import json, os, uuid
+        t = find_thread_by_obj(thread)
+        proc = t.GetProcess()
+        if proc.GetState() != lldb.eStateStopped:
+            raise RuntimeError("Native target is not stopped")
+        frames = util.insight_frames(t)
+        caller = frames[1] if len(frames) > 1 else lldb.SBFrame()
+        if not caller.IsValid():
+            raise RuntimeError("No native caller frame")
+        return_pc, return_sp = caller.GetPC(), caller.GetSP()
+        if return_pc in (0, lldb.LLDB_INVALID_ADDRESS) or return_sp in (0, lldb.LLDB_INVALID_ADDRESS):
+            raise RuntimeError("Native caller location is unavailable")
+        root = os.path.dirname(os.path.dirname(__file__))
+        path = os.path.join(root, "caller-goal.json")
+        if os.path.exists(path):
+            with open(path) as source: prior = json.load(source)
+            observed_path = os.path.join(root, "caller-observation.json")
+            observed = {}
+            if os.path.exists(observed_path):
+                with open(observed_path) as source: observed = json.load(source)
+            if prior.get("pid") == proc.GetProcessID() and (observed.get("goal") != prior.get("id") or observed.get("state") != "verified"):
+                raise RuntimeError("An unverified caller intent is retained; close and reopen the context")
+        target = proc.GetTarget()
+        with commands.INSIGHT_BREAKPOINT_LOCK:
+            breakpoint = target.BreakpointCreateByAddress(return_pc)
+            commands.INSIGHT_TRANSIENT_BREAKPOINTS.add(breakpoint.GetID())
+        try:
+            if not breakpoint.IsValid():
+                raise RuntimeError("Cannot establish caller breakpoint")
+            breakpoint.SetThreadID(t.GetThreadID())
+            breakpoint.SetCondition("$sp == " + hex(return_sp))
+            breakpoint.SetOneShot(True)
+            if breakpoint.GetNumLocations() != 1:
+                raise RuntimeError("Caller breakpoint location is ambiguous")
+            goal = dict(schema=1, id=str(uuid.uuid4()), pid=proc.GetProcessID(), thread=str(t.GetThreadID()), pc=hex(return_pc), sp=hex(return_sp), stop=proc.GetStopID(), executable=target.GetExecutable().fullpath, breakpoint=breakpoint.GetID())
+            temporary = path + ".new-" + goal["id"]
+            fd = os.open(temporary, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)
+            try:
+                os.write(fd, json.dumps(goal).encode("utf-8"))
+                os.fsync(fd)
+            finally:
+                os.close(fd)
+            os.replace(temporary, path)
+            error = proc.Continue()
+            if error.Fail():
+                raise RuntimeError(error.GetCString())
+        except Exception:
+            target.BreakpointDelete(breakpoint.GetID())
+            raise
+    """;
+    boolean ownedCaller=System.getProperty("os.name").toLowerCase(Locale.ROOT).contains("mac");
+    if(ownedCaller)source=source.replace(originalStep,step.stripTrailing());
+    Files.writeString(methods,source,StandardOpenOption.TRUNCATE_EXISTING);
+    Path client=root.resolve("ghidratrace/client.py");String clientSource=Files.readString(client),call="        name = request.name\n        if not name in self._method_registry._methods:";
+    if(clientSource.indexOf(call)<0||clientSource.indexOf(call)!=clientSource.lastIndexOf(call))throw new IllegalArgumentException("Unexpected pinned TraceRmi method dispatcher");
+    String logPath="__import__('base64').b64decode('"+Base64.getEncoder().encodeToString(root.resolve("rpc-methods.log").toString().getBytes(java.nio.charset.StandardCharsets.UTF_8))+"').decode('utf-8')";
+    clientSource=clientSource.replace(call,"        name = request.name\n        import os as _insight_os\n        _insight_fd = _insight_os.open("+logPath+", _insight_os.O_CREAT | _insight_os.O_APPEND | _insight_os.O_WRONLY, 0o600)\n        try:\n            if _insight_os.fstat(_insight_fd).st_size < 65536:\n                _insight_os.write(_insight_fd, (name[:128] + '\\n').encode('utf-8'))\n        finally:\n            _insight_os.close(_insight_fd)\n        if not name in self._method_registry._methods:");
+    Path commands=root.resolve("ghidralldb/commands.py");String commandSource=Files.readString(commands);
+    String trackedTxBefore="""
+        with STATE.require_trace().open_tx(description) as tx:
+            STATE.tx = tx
+            yield tx
+        STATE.reset_tx()
+    """;
+    String trackedTxAfter="""
+        try:
+            with STATE.require_trace().open_tx(description) as tx:
+                STATE.tx = tx
+                yield tx
+        finally:
+            STATE.reset_tx()
+    """;
+    if(commandSource.indexOf(trackedTxBefore)<0||commandSource.indexOf(trackedTxBefore)!=commandSource.lastIndexOf(trackedTxBefore))throw new IllegalArgumentException("Unexpected pinned tracked transaction lifecycle");
+    commandSource=commandSource.replace(trackedTxBefore,trackedTxAfter);
+    int frameStart=commandSource.indexOf("def put_frames() -> None:"),frameEnd=commandSource.indexOf("@convert_errors\ndef ghidra_trace_put_frames",frameStart);
+    if(frameStart<0||frameEnd<frameStart)throw new IllegalArgumentException("Unexpected pinned LLDB frame exporter");
+    String frameBlock=commandSource.substring(frameStart,frameEnd),frameIndex="level=f.GetFrameID()";
+    int first=frameBlock.indexOf(frameIndex),second=frameBlock.indexOf(frameIndex,first+frameIndex.length());
+    if(first<0||second<0||frameBlock.indexOf(frameIndex,second+frameIndex.length())>=0)throw new IllegalArgumentException("Unexpected pinned LLDB frame identity");
+    if(ownedCaller){
+      if(!frameBlock.contains("mapper.map(proc, f.GetPC())")||!frameBlock.contains("str(f.GetFunctionName())")||!frameBlock.contains("util.get_description(f)"))throw new IllegalArgumentException("Unexpected pinned LLDB frame coordinates");
+      frameBlock=frameBlock.replace("for i in range(0, t.GetNumFrames()):", "frames = util.insight_frames(t)\n    for i in range(len(frames)):").replace("f = t.GetFrameAtIndex(i)", "f = frames[i]").replace("mapper.map(proc, f.GetPC())","mapper.map(proc, util.insight_frame_pc(f))").replace("str(f.GetFunctionName())","util.insight_frame_function(f)").replace("util.get_description(f)","util.insight_frame_description(f)");
+    }
+    commandSource=commandSource.substring(0,frameStart)+frameBlock.replace(frameIndex,"level=i")+commandSource.substring(frameEnd);
+    String single="def put_single_breakpoint(b: lldb.SBBreakpoint, proc: lldb.SBProcess) -> None:\n";
+    String list="        b = target.GetBreakpointAtIndex(i)\n        keys.append(BREAKPOINT_KEY_PATTERN.format(breaknum=b.GetID()))";
+    if(commandSource.indexOf(single)<0||commandSource.indexOf(single)!=commandSource.lastIndexOf(single)||commandSource.indexOf(list)<0||commandSource.indexOf(list)!=commandSource.lastIndexOf(list))throw new IllegalArgumentException("Unexpected pinned LLDB breakpoint exporter");
+    commandSource=commandSource.replace(single,"import threading as _insight_threading\nINSIGHT_BREAKPOINT_LOCK = _insight_threading.RLock()\nINSIGHT_TRANSIENT_BREAKPOINTS = set()\n\n"+single+"    with INSIGHT_BREAKPOINT_LOCK:\n        if b.GetID() in INSIGHT_TRANSIENT_BREAKPOINTS:\n            return\n");
+    commandSource=commandSource.replace(list,"        b = target.GetBreakpointAtIndex(i)\n        with INSIGHT_BREAKPOINT_LOCK:\n            if b.GetID() in INSIGHT_TRANSIENT_BREAKPOINTS:\n                continue\n        keys.append(BREAKPOINT_KEY_PATTERN.format(breaknum=b.GetID()))");
+    String registerFrame="frame.GetFrameID()";
+    if(commandSource.split(java.util.regex.Pattern.quote(registerFrame),-1).length!=5)throw new IllegalArgumentException("Unexpected pinned LLDB frame register paths");
+    commandSource=commandSource.replace(registerFrame,"util.insight_frame_level(frame)");
+    String dynamicRegister="bank.GetChildAtIndex(i, lldb.eDynamicCanRunTarget, True)";
+    if(commandSource.split(java.util.regex.Pattern.quote(dynamicRegister),-1).length!=3)throw new IllegalArgumentException("Unexpected pinned LLDB register reader");
+    commandSource=commandSource.replace(dynamicRegister,"bank.GetChildAtIndex(i, lldb.eDynamicDontRunTarget, True)");
+    Path util=root.resolve("ghidralldb/util.py");String utilSource=Files.readString(util);
+    String evaluation="def parse_and_eval(expr: str, signed: bool = False) -> int:\n    if signed is True:\n        return get_eval(expr).GetValueAsSigned()\n    return get_eval(expr).GetValueAsUnsigned()";
+    String readOnlyEvaluation="""
+    def parse_and_eval(expr: str, signed: bool = False) -> int:
+        if not signed and re.fullmatch(r'0[xX][0-9a-fA-F]+|0|[1-9][0-9]*', expr):
+            return int(expr, 16 if expr.lower().startswith('0x') else 10)
+        register = re.fullmatch(r'[$](pc|sp)([+-](?:0[xX][0-9a-fA-F]+|0|[1-9][0-9]*))?', expr)
+        if register:
+            frame = selected_frame()
+            value = frame.FindRegister(register.group(1))
+            if not frame.IsValid() or not value.IsValid() or value.GetError().Fail():
+                raise ValueError('Stopped native register is unavailable')
+            offset = register.group(2) or '0'
+            displacement = int(offset, 16 if 'x' in offset.lower() else 10)
+            bits = get_target().GetAddressByteSize() * 8
+            number = (value.GetValueAsUnsigned() + displacement) & ((1 << bits) - 1)
+            return number - (1 << bits) if signed and number >= (1 << (bits - 1)) else number
+        if signed is True:
+            return get_eval(expr).GetValueAsSigned()
+        return get_eval(expr).GetValueAsUnsigned()
+    """;
+    if(utilSource.indexOf(evaluation)<0||utilSource.indexOf(evaluation)!=utilSource.lastIndexOf(evaluation))throw new IllegalArgumentException("Unexpected pinned LLDB address evaluator");
+    utilSource=utilSource.replace(evaluation,readOnlyEvaluation.stripTrailing());
+    utilSource+="\n\nINSIGHT_NORMALIZE_PHYSICAL_STACK = "+(ownedCaller?"True":"False")+"\n";
+    utilSource+="""
+
+    def insight_frames(thread):
+        frames = [thread.GetFrameAtIndex(i) for i in range(thread.GetNumFrames())]
+        if not INSIGHT_NORMALIZE_PHYSICAL_STACK or not frames:
+            return frames
+        head = frames[0]
+        pc, sp = head.FindRegister('pc'), head.FindRegister('sp')
+        if not pc.IsValid() or not sp.IsValid() or pc.GetError().Fail() or sp.GetError().Fail():
+            return frames
+        live_pc, live_sp = pc.GetValueAsUnsigned(), sp.GetValueAsUnsigned()
+        for index in range(1, min(len(frames), 16)):
+            previous, candidate = frames[index - 1], frames[index]
+            if previous.IsInlined() or previous.IsArtificial() or previous.GetSP() != live_sp or previous.GetCFA() != live_sp:
+                break
+            if candidate.GetPC() == live_pc and candidate.GetSP() == live_sp and not candidate.IsInlined() and not candidate.IsArtificial():
+                return frames[index:]
+        return frames
+
+    def insight_frame_native_index(frame):
+        thread = frame.GetThread()
+        for index in range(thread.GetNumFrames()):
+            if thread.GetFrameAtIndex(index).GetFrameID() == frame.GetFrameID():
+                return index
+        raise RuntimeError('Native frame is no longer present')
+
+    def insight_frame_for_level(thread, level):
+        return thread.GetFrameAtIndex(0) if level == 0 else insight_frames(thread)[level]
+
+    def insight_frame_level(frame):
+        thread = frame.GetThread()
+        for index, candidate in enumerate(insight_frames(thread)):
+            if candidate.GetFrameID() == frame.GetFrameID():
+                return index
+        frames = insight_frames(thread)
+        if frames and insight_frame_native_index(frame) < insight_frame_native_index(frames[0]):
+            return 0
+        raise RuntimeError('Native frame is no longer in the current stack')
+    """;
+    utilSource+="""
+
+    def insight_frame_pc(frame):
+        if insight_frame_level(frame) != 0 or frame.IsInlined() or frame.IsArtificial():
+            return frame.GetPC()
+        value = frame.FindRegister('pc')
+        if not value.IsValid() or value.GetError().Fail():
+            raise RuntimeError('Native frame PC register is unavailable')
+        return value.GetValueAsUnsigned()
+
+    def insight_frame_function(frame):
+        target = frame.GetThread().GetProcess().GetTarget()
+        address = target.ResolveLoadAddress(insight_frame_pc(frame))
+        function, symbol = address.GetFunction(), address.GetSymbol()
+        return str(function.GetName() if function.IsValid() else symbol.GetName() if symbol.IsValid() else '<unknown>')
+
+    def insight_frame_description(frame):
+        return '#%d: %s %s' % (insight_frame_level(frame), hex(insight_frame_pc(frame)), insight_frame_function(frame))
+
+    def insight_thread_description(thread):
+        if thread.GetProcess().GetState() != lldb.eStateStopped:
+            return get_description(thread)
+        frames = insight_frames(thread)
+        if not frames:
+            return get_description(thread)
+        frame = frames[0]
+        return 'thread #%d: tid = %s, %s %s, stop reason = %s' % (thread.GetIndexID(), hex(thread.GetThreadID()), hex(insight_frame_pc(frame)), insight_frame_function(frame), thread.GetStopDescription(512))
+    """;
+    Files.writeString(util,utilSource,StandardOpenOption.TRUNCATE_EXISTING);
+    String selectFrame="f.thread.SetSelectedFrame(f.GetFrameID())";
+    if(source.split(java.util.regex.Pattern.quote(selectFrame),-1).length!=3)throw new IllegalArgumentException("Unexpected pinned LLDB frame selector");
+    source=source.replace(selectFrame,"f.thread.SetSelectedFrame(util.insight_frame_native_index(f))");
+    if(ownedCaller){
+      String lookup="    return thread.GetFrameAtIndex(level)";
+      if(source.indexOf(lookup)<0||source.indexOf(lookup)!=source.lastIndexOf(lookup))throw new IllegalArgumentException("Unexpected pinned LLDB frame lookup");
+      source=source.replace(lookup,"    return util.insight_frame_for_level(thread, level)");
+      String display="def compute_thread_display(t: lldb.SBThread) -> str:\n    return util.get_description(t)";
+      if(commandSource.indexOf(display)<0||commandSource.indexOf(display)!=commandSource.lastIndexOf(display))throw new IllegalArgumentException("Unexpected pinned LLDB thread display");
+      commandSource=commandSource.replace(display,"def compute_thread_display(t: lldb.SBThread) -> str:\n    return util.insight_thread_description(t)");
+    }
+    Files.writeString(methods,source,StandardOpenOption.TRUNCATE_EXISTING);
+    Files.writeString(commands,commandSource,StandardOpenOption.TRUNCATE_EXISTING);
+    Files.writeString(client,clientSource,StandardOpenOption.TRUNCATE_EXISTING);
+    Path architecture=root.resolve("ghidralldb/arch.py");String architectureSource=Files.readString(architecture);
+    String registerAliases="""
+
+    class InsightAarch64RegisterMapper(DefaultRegisterMapper):
+        def map_name(self, proc, name):
+            return {'fp': 'x29', 'lr': 'x30'}.get(name, super().map_name(proc, name))
+
+        def map_name_back(self, proc, name):
+            return {'x29': 'fp', 'x30': 'lr'}.get(name, super().map_name_back(proc, name))
+    """;
+    String mapper="def compute_register_mapper(lang: str) -> DefaultRegisterMapper:\n";
+    if(architectureSource.indexOf(mapper)<0||architectureSource.indexOf(mapper)!=architectureSource.lastIndexOf(mapper))throw new IllegalArgumentException("Unexpected pinned LLDB register mapper");
+    architectureSource=architectureSource.replace(mapper,mapper+"    if lang.startswith('AARCH64:'):\n        return InsightAarch64RegisterMapper('big' if ':BE:' in lang else 'little')\n")+registerAliases;
+    Files.writeString(architecture,architectureSource,StandardOpenOption.TRUNCATE_EXISTING);
+    System.out.println("{\"state\":\"prepared\",\"lldb_memory_adapter\":\"insight-sbprocess-v1\",\"lldb_step_adapter\":\"insight-caller-dispatch-v2\"}");
   }
 }

package/references/native/InsightRuntimeDoctor.java

@@ -0,0 +1,33 @@
+import ghidra.GhidraApplicationLayout;
+import ghidra.framework.*;
+import ghidra.program.database.ProgramDB;
+import ghidra.program.model.lang.LanguageID;
+import ghidra.program.util.DefaultLanguageService;
+import ghidra.program.flatapi.FlatProgramAPI;
+import ghidra.app.decompiler.DecompInterface;
+import ghidra.util.task.TaskMonitor;
+import java.io.ByteArrayInputStream;
+
+/** Disposable native probe: decode and decompile a known function using the selected installation. */
+class InsightRuntimeDoctor {
+ public static void main(String[] args) {
+  var out=System.out;System.setOut(System.err);
+  try {
+   Application.initializeApplication(new GhidraApplicationLayout(),new HeadlessGhidraApplicationConfiguration());
+   var language=DefaultLanguageService.getLanguageService().getLanguage(new LanguageID("x86:LE:32:default"));
+   var program=new ProgramDB("runtime-probe",language,language.getDefaultCompilerSpec(),new Object());
+   var consumer=new Object();program.addConsumer(consumer);
+   int tx=program.startTransaction("probe");
+   var start=program.getAddressFactory().getDefaultAddressSpace().getAddress(0x1000);
+   program.getMemory().createInitializedBlock(".text",start,new ByteArrayInputStream(new byte[]{(byte)0xb8,42,0,0,0,(byte)0xc3}),6,TaskMonitor.DUMMY,false);
+   var api=new FlatProgramAPI(program);api.disassemble(start);var function=api.createFunction(start,"runtime_probe");
+   program.endTransaction(tx,true);
+   var decompiler=new DecompInterface();
+   if(!decompiler.openProgram(program))throw new IllegalStateException("Decompiler did not open program");
+   var result=decompiler.decompileFunction(function,30,TaskMonitor.DUMMY);
+   if(!result.decompileCompleted()||result.getDecompiledFunction()==null||!result.getDecompiledFunction().getC().contains("0x2a"))throw new IllegalStateException("Native decompile did not produce the expected return value");
+   decompiler.dispose();program.release(consumer);
+   out.println("{\"state\":\"ready\",\"headless\":true,\"decompiler\":true,\"expectedReturn\":42}");System.exit(0);
+  } catch(Throwable failure){failure.printStackTrace(System.err);out.println("{\"state\":\"failed\"}");System.exit(1);}
+ }
+}