@eyeauras/insight-cli 0.2.0 → 0.2.2

package/references/managed-runtime.md

@@ -22,6 +22,11 @@ A failed install preserves its stage/diagnostics and the old selection. Retrying
 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.
 
+On Windows, long Ghidra Java classpaths use an owned per-execution argument file, retained with
+the process diagnostics. `javac` files use UTF-8; `java` launcher files use the Windows system
+code page. Java 21's launcher still requires paths representable in that code page. Unmappable
+characters fail before launch rather than selecting different files through lossy conversion.
+
 `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
@@ -37,10 +42,10 @@ 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 --offline
+  --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 --offline
+  --java /tools/jdk/bin/java --debugger-archive ./lldb-python.tar.gz --offline
 ```
 
 `--executable` accepts the actual Ghidra launcher (`ghidraRun[.bat]`, or
@@ -54,11 +59,13 @@ 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` check the expected bytes; the actual digests are recorded in the installation
+`--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 pinned SHA256 values.
+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
@@ -95,16 +102,39 @@ 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. Reinstalling the same archives restores
+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. All source URLs, hashes and license
-identities are in `src/runtime-catalog.ts`; downloaded distributions retain their license files.
+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.
 
@@ -114,3 +144,19 @@ not downloaded third-party Python dependencies. `doctor` reports a missing host
 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/InsightTraceState.java

@@ -17,6 +17,15 @@ import ghidra.trace.model.memory.TraceMemoryState;
 /** Save/restore trace databases independently of the program database and live execution. */
 public class InsightTraceState extends GhidraScript {
   static String string(JsonObject p,String key){return p.get(key).getAsString();}
+  static void activateAndWait(DebuggerTraceManagerService manager,ghidra.debug.api.tracemgr.DebuggerCoordinates coordinates)throws Exception{
+    var pending=new java.util.concurrent.atomic.AtomicReference<java.util.concurrent.CompletableFuture<Void>>();
+    Runnable activate=()->pending.set(manager.activateAndNotify(coordinates,DebuggerTraceManagerService.ActivationCause.USER));
+    if(SwingUtilities.isEventDispatchThread()){
+      activate.run();if(!pending.get().isDone())throw new IllegalStateException("Asynchronous trace navigation requires a background script");pending.get().join();
+    }else{SwingUtilities.invokeAndWait(activate);pending.get().get(30,java.util.concurrent.TimeUnit.SECONDS);}
+    if(manager.getCurrentTrace()!=coordinates.getTrace())throw new IllegalStateException("Trace selection did not settle");
+  }
+
   static void bind(Trace trace,JsonObject p,boolean create){
     var options=trace.getOptions("Insight");String target=options.getString("Target",null),context=options.getString("Context",null);
     if(target==null&&context==null&&create){int tx=trace.startTransaction("Bind owned trace");try{
@@ -82,31 +91,31 @@ public class InsightTraceState extends GhidraScript {
       var thread=manager.getCurrentThread();var object=thread==null?null:thread.getObject();
       if(object==null){var candidates=manager.getCurrentTrace().getObjectManager().getAllObjects().filter(item->item.getSchema().getName().toString().equals("Process")).toList();
         if(candidates.size()!=1)throw new IllegalStateException("Debugger process selection is ambiguous");object=candidates.get(0);}
-      var m=manager;final var selectedObject=object;Runnable focus=()->m.activateObject(selectedObject);
-      if(SwingUtilities.isEventDispatchThread())focus.run();else SwingUtilities.invokeAndWait(focus);
+      activateAndWait(manager,manager.resolveObject(object));
       println("INSIGHT_TRACE_STATE "+new Gson().toJson(Map.of("state","focused")));return;
     }
     if(operation.equals("restore")){
       var folder=data.getRootFolder().getFolder("__insight_traces");if(folder==null)folder=data.getRootFolder().createFolder("__insight_traces");
       for(var entry:p.getAsJsonArray("traces")){
         var saved=entry.getAsJsonObject();String id=string(saved,"id");if(!id.matches("trace_[a-f0-9-]{36}"))throw new IllegalArgumentException();
-        boolean present=false;for(var trace:manager.getOpenTraces())if(id.equals(trace.getOptions("Insight").getString("Trace ID",null)))present=true;
-        if(present)continue;
-        var file=folder.getFile(id);if(file==null)file=folder.createFile(id,Path.of(string(saved,"input")).toFile(),monitor);
-        Trace trace=manager.openTrace(file,-1);bind(trace,p,false);
-        if(!id.equals(trace.getOptions("Insight").getString("Trace ID",null)))throw new IllegalArgumentException("Restored trace identity changed");
+        Trace trace=null;for(var existing:manager.getOpenTraces())if(id.equals(existing.getOptions("Insight").getString("Trace ID",null)))trace=existing;
+        if(trace==null){var file=folder.getFile(id);if(file==null)file=folder.createFile(id,Path.of(string(saved,"input")).toFile(),monitor);trace=manager.openTrace(file,-1);}
+        bind(trace,p,false);if(!id.equals(trace.getOptions("Insight").getString("Trace ID",null)))throw new IllegalArgumentException("Restored trace identity changed");
         relocateMappings(trace,selected);
-        if(p.has("active")&&id.equals(string(p,"active"))){final var m=manager;Runnable activate=()->{
-          m.activateTrace(trace);m.activateSnap(Long.parseLong(string(saved,"snap")));
-          if(saved.has("thread")){var thread=trace.getThreadManager().getThread(Long.parseLong(string(saved,"thread")));if(thread!=null)m.activateThread(thread);}
-        };if(SwingUtilities.isEventDispatchThread())activate.run();else SwingUtilities.invokeAndWait(activate);}
+        var coordinates=manager.resolveTrace(trace).snap(Long.parseLong(string(saved,"snap")));
+        if(saved.has("thread")){var thread=trace.getThreadManager().getThread(Long.parseLong(string(saved,"thread")));if(thread!=null)coordinates=coordinates.thread(thread);}
+        activateAndWait(manager,coordinates);
+        if(manager.getCurrentSnap()!=Long.parseLong(string(saved,"snap")))throw new IllegalStateException("Saved trace snap did not restore");
+      }
+      if(p.has("active"))for(var trace:manager.getOpenTraces())if(string(p,"active").equals(trace.getOptions("Insight").getString("Trace ID",null))){
+        activateAndWait(manager,manager.resolveTrace(trace));
       }
       println("INSIGHT_TRACE_STATE "+new Gson().toJson(Map.of("state","restored")));return;
     }
     if(operation.equals("select")){
       String id=string(p,"id");for(var trace:manager.getOpenTraces()){
-        bind(trace,p,false);if(id.equals(trace.getOptions("Insight").getString("Trace ID",null))){final var m=manager;
-          if(SwingUtilities.isEventDispatchThread())m.activateTrace(trace);else SwingUtilities.invokeAndWait(()->m.activateTrace(trace));
+        bind(trace,p,false);if(id.equals(trace.getOptions("Insight").getString("Trace ID",null))){
+          activateAndWait(manager,manager.resolveTrace(trace));
           println("INSIGHT_TRACE_STATE "+new Gson().toJson(Map.of("state","selected","id",id)));return;}
       }
       throw new IllegalArgumentException("Trace not found");
@@ -114,15 +123,21 @@ public class InsightTraceState extends GhidraScript {
     if(!operation.equals("checkpoint"))throw new IllegalArgumentException();
     Path root=Path.of(string(p,"output")).toRealPath();List<Object> traces=new ArrayList<>();String active=null;
     if(manager.getOpenTraces().size()>64)throw new IllegalArgumentException("Trace count exceeds 64");
+    long lockDeadline=System.nanoTime()+java.util.concurrent.TimeUnit.SECONDS.toNanos(10);
     for(var trace:manager.getOpenTraces()){
       bind(trace,p,false);String id=trace.getOptions("Insight").getString("Trace ID",null);if(id==null||!id.matches("trace_[a-f0-9-]{36}"))throw new IllegalArgumentException();
       Path output=root.resolve(id+".gzf");if(Files.exists(output))throw new IllegalArgumentException();
+      while(!trace.lock("Insight consistent trace checkpoint")){
+        monitor.checkCancelled();if(System.nanoTime()>=lockDeadline)throw new IllegalStateException("Trace transaction did not release for checkpoint");Thread.sleep(25);
+      }
+      try{
       var coordinates=manager.getCurrentFor(trace);trace.saveToPackedFile(output.toFile(),monitor);
       Map<String,Object> row=new LinkedHashMap<>();row.put("id",id);row.put("name",trace.getName());row.put("snap",Long.toString(coordinates.getSnap()));
       row.put("modules",trace.getModuleManager().getAllModules().size());row.put("threads",trace.getThreadManager().getAllThreads().size());
       if(coordinates.getThread()!=null)row.put("thread",Long.toString(coordinates.getThread().getKey()));
       var targets=selected.getService(DebuggerTargetService.class);var live=targets==null?null:targets.getTarget(trace);row.put("connected",live!=null&&live.isValid());
       traces.add(row);if(manager.getCurrentTrace()==trace)active=id;
+      }finally{trace.unlock();}
     }
     Map<String,Object> result=new LinkedHashMap<>();result.put("traces",traces);if(active!=null)result.put("active",active);
     println("INSIGHT_TRACE_STATE "+new Gson().toJson(result));

package/references/native-workflows.md

@@ -44,6 +44,16 @@ loader IDs, supported language/compiler specifications and native option definit
 selects a loader explicitly. Primitive options, native address and HexLong options are converted
 and validated; unsupported complex option classes fail explicitly. One program belongs to a target.
 
+For a mixed managed/native or protected PE, first inspect the installed loader options. If the
+task needs its native view and CLI metadata parsing emits repeated warnings or prevents import,
+an explicit PE import may select `--loader <PE-loader-ID-from-discovery>` together with
+`--loader-options '{"Parse CLI headers (if present)":false}'`.
+This is a per-target analysis choice: record it with the findings. For an alternative managed
+import of the same bytes, use a separate disposable profile; targets within one profile reuse
+the same immutable input identity. An output-limit failure means import/analysis is incomplete; inspect
+the retained diagnostics and first-import recovery state before continuing. Do not treat warnings,
+a killed worker or a partial snapshot as a successful analysis or blindly repeat publication.
+
 `formats exporters` lists compatible native exporters and their options. `formats export
 --exporter 'Raw Bytes' --ranges '[{"start":"0x10001","end":"0x10003"}]'
 --output-directory <new-directory>` requires a format supporting restricted address sets.

package/references/setup.md

@@ -40,7 +40,8 @@ Native acceptance separates macOS GUI/LLDB workflows from selected headless Wind
 SDK, Version Tracking and FID/BSim workflows. Native Windows/Linux debugger/GUI acceptance
 remains deferred. The ordinary CI lane stays offline; disposable native CI is explicit.
 
-Debugger execution additionally needs a supported host debugger (local LLDB on macOS). Its
+On macOS 15+ ARM64, `ghidra install` delivers an owned LLDB/Python debugger backend;
+OS debugger authorization remains required. Other host profiles need their supported debugger. Its
 Ghidra Python dependencies are prepared from the installed SDK wheels into owned GUI storage.
 `debuggerPython` optionally configures a Python-backed offer; `windbgDir` configures the Windows
 debugger runtime directory when relevant. These are runtime profile settings, not research scope.

package/runtime/managed/insight-heap/Insight.Heap.csproj

@@ -0,0 +1 @@
+<Project Sdk="Microsoft.NET.Sdk"><PropertyGroup><TargetFramework>net10.0</TargetFramework><OutputType>Exe</OutputType><UseAppHost>false</UseAppHost><AssemblyName>Insight.Heap</AssemblyName><Nullable>enable</Nullable><ImplicitUsings>enable</ImplicitUsings><Deterministic>true</Deterministic><DebugType>none</DebugType><RestorePackagesWithLockFile>true</RestorePackagesWithLockFile></PropertyGroup><ItemGroup><PackageReference Include="Microsoft.Diagnostics.Runtime" Version="4.2.751201" /></ItemGroup></Project>