@eyeauras/insight-cli 0.2.0 → 0.2.1

package/skills/insight-dotnet-trace/references/agent-execution.md

@@ -0,0 +1,36 @@
+# Agent host execution permissions
+
+Keep the user/project host policy and the selected profile. A sandbox can deny writes
+to runtime AppData or access to the local IPC endpoint, including during local help.
+This is a host execution boundary, not evidence that the tool or its inputs are absent.
+
+First retry only `insight-cli --help`, `tools list`, `skill`, or the selected application's
+read-only `status` using the host's normal permission escalation. In Codex, use the
+execution tool's `sandbox_permissions: "require_escalated"` with a scoped explanation
+that the installed CLI needs its existing profile storage/local IPC. Automatic approval
+review or the user decides that request; do not disable the sandbox or approval policy.
+
+Do not work around this by changing HOME/AppData/profile paths, creating another host,
+deleting owner/endpoint files, killing unrelated processes or claiming a missing runtime.
+After the read-only probe succeeds, use the approved execution route for the intended
+public CLI commands. An access refusal explicitly stating **no command was sent** is
+known not dispatched; it is safe to submit that authorized command through the approved
+route. This includes a mutation refused before dispatch. Do not mistake that definite
+pre-dispatch refusal for an unknown execution outcome. Downloads still require their explicit
+network access.
+
+A lost mutation response is different from a denied startup probe: inspect retained
+request/status/recovery evidence and use its request ID when supported. Never blindly
+repeat a publication, script or program run whose outcome is unknown. External-tool
+fallback is allowed by project rules, but record that the intended facade was not used
+and do not invent a successful checkpoint or native result.
+
+## Wait for the original execution
+
+A tool operation may outlast the host execution tool's initial wait. A returned running
+session/cell ID means that command is still in progress, not that the CLI returned no data.
+Use the host's session poll/wait facility until terminal exit and consume stdout/stderr
+before issuing a dependent command. In Codex, an `exec_command` session is continued with
+`write_stdin`; a yielded execution cell uses that host's cell wait. Do not launch a second
+open/install or repeat a CPU action just because the first chunk was empty. If the execution
+really loses its terminal result, use the CLI's request/status recovery as described above.

package/skills/insight-frida/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: insight-frida
+description: Observe native call arguments/results or inspect runtime modules and exports in an explicitly selected authorized process with bounded Frida scripts. Use insight-cli frida to corroborate static findings with actual execution on macOS ARM64.
+---
+
+# Insight Frida 0.2.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
+CLI calls too. An explicit **no command was sent** denial is known undispatched and can be
+retried through that route. Keep HOME, profile and owner state; see
+[host execution permissions](references/agent-execution.md). A lost mutation reply needs
+request/status recovery, never blind retry.
+
+Follow existing project RE and evidence conventions. Frida instruments a running process;
+choose an explicitly authorized PID. This facade owns the collector, while the target stays
+with its original owner. Stopping the collector never signals that target.
+
+1. `insight-cli frida status --json` checks readiness. `frida install` obtains our pinned
+   Frida Node 17.24.0 bundle from GitHub Releases, including its NAPI-v8 binding, JavaScript
+   dependencies and full notices. It uses the CLI's Node runtime; Python is unnecessary.
+   Managed delivery requires macOS 14+ ARM64. `download`, `install --archive FILE --offline`,
+   `doctor` and `uninstall` use the shared lifecycle. An external compatible Node bundle can
+   be selected with `install --executable /path/to/frida/build/src/frida.js`; adjacent binding
+   and resolved runtime dependency families are fingerprinted and never deleted.
+2. `frida modules --pid PID --json` establishes runtime module names and load addresses.
+   `frida exports --pid PID --module NAME --json` narrows to one module. `--limit`/`--offset`
+   page records. Runtime pointers differ from static addresses under ASLR; establish module
+   and image correspondence before combining findings from Ghidra/LLVM with live evidence.
+3. Write a focused ordinary JavaScript file using the [Frida JavaScript API](https://frida.re/docs/javascript-api/).
+   For a known integer-valued exported function, an observation hook can be:
+
+   ```javascript
+   const at = Process.mainModule.getExportByName('quote_total');
+   Interceptor.attach(at, {
+     onEnter(args) { this.count = args[0].toInt32(); },
+     onLeave(value) { send({count: this.count, result: value.toInt32()}); }
+   });
+   ```
+
+   Match argument types, calling convention and module to the actual program. This example
+   is not a generic signature for every function. `frida observe --pid PID --script FILE
+   --duration-seconds 2 --output research/calls.json --json` captures the source bytes, loads
+   it, collects messages, requests unload and detaches. The output records the source hash,
+   runtime version, original PID/birth, native diagnostics and cleanup acknowledgment.
+4. Inspect `complete`, `state`, script errors and cleanup fields. Script errors or early
+   target detach produce partial evidence. No observed call does not prove absence. Ordinary
+   `send`/console/error messages and optional binary payloads are retained. `--limit`/`--offset`
+   page event messages; `--output` saves the full bounded envelope to a new ordinary file and
+   creates parents. Use `artifacts save` for a checkpoint when useful.
+   Both the response and saved envelope include `summary`: total protocol events and counts
+   of script send/error/log messages. A send message is not universally a call. Derive call
+   counts from the retained payload type selected by your hook; do not count runtime,
+   loaded or completed receipts as calls or estimate counts by reading a long event list.
+5. The observation window is 1–120 seconds; collector execution has a separate finite deadline
+   that survives owner loss. Native SDK helpers have their own inherited deadlines; status
+   remains `native_children_pending` and uninstall is blocked until they exit. Native output is bounded to 4 MiB and 10000 messages. Arbitrary
+   script patches or application side effects are not automatically rolled back by unload.
+   Avoid unnecessarily broad hooks and large payloads. `tools processes --tool frida --all`
+   shows owned collector history. A recovered live macOS PID may be unverified: wait for the
+   deadline and inspect retained evidence instead of replaying an injection blindly.
+
+The pinned backend has a known attach failure on a bare C process without CoreFoundation;
+our native probe reproduces it explicitly. A process already loading CoreFoundation worked.
+Report the failure and choose a suitable debugger/fixture; do not silently load frameworks
+into an unrelated process. macOS authorization/hardened targets can also prevent attach.
+An imported PE is not a runnable local macOS process. Generated help owns exact syntax.

package/skills/insight-frida/references/agent-execution.md

@@ -0,0 +1,36 @@
+# Agent host execution permissions
+
+Keep the user/project host policy and the selected profile. A sandbox can deny writes
+to runtime AppData or access to the local IPC endpoint, including during local help.
+This is a host execution boundary, not evidence that the tool or its inputs are absent.
+
+First retry only `insight-cli --help`, `tools list`, `skill`, or the selected application's
+read-only `status` using the host's normal permission escalation. In Codex, use the
+execution tool's `sandbox_permissions: "require_escalated"` with a scoped explanation
+that the installed CLI needs its existing profile storage/local IPC. Automatic approval
+review or the user decides that request; do not disable the sandbox or approval policy.
+
+Do not work around this by changing HOME/AppData/profile paths, creating another host,
+deleting owner/endpoint files, killing unrelated processes or claiming a missing runtime.
+After the read-only probe succeeds, use the approved execution route for the intended
+public CLI commands. An access refusal explicitly stating **no command was sent** is
+known not dispatched; it is safe to submit that authorized command through the approved
+route. This includes a mutation refused before dispatch. Do not mistake that definite
+pre-dispatch refusal for an unknown execution outcome. Downloads still require their explicit
+network access.
+
+A lost mutation response is different from a denied startup probe: inspect retained
+request/status/recovery evidence and use its request ID when supported. Never blindly
+repeat a publication, script or program run whose outcome is unknown. External-tool
+fallback is allowed by project rules, but record that the intended facade was not used
+and do not invent a successful checkpoint or native result.
+
+## Wait for the original execution
+
+A tool operation may outlast the host execution tool's initial wait. A returned running
+session/cell ID means that command is still in progress, not that the CLI returned no data.
+Use the host's session poll/wait facility until terminal exit and consume stdout/stderr
+before issuing a dependent command. In Codex, an `exec_command` session is continued with
+`write_stdin`; a yielded execution cell uses that host's cell wait. Do not launch a second
+open/install or repeat a CPU action just because the first chunk was empty. If the execution
+really loses its terminal result, use the CLI's request/status recovery as described above.

package/skills/insight-ghidra/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: insight-ghidra
+description: Inspect or edit native binaries with Ghidra through insight-cli; use isolated contexts, multi-agent merge/refresh, server, GUI or debugger workflows. Choose this for static native behavior and references, not C# recovery from managed IL.
+---
+
+# Insight Ghidra 0.2.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
+CLI calls too. An explicit **no command was sent** denial is known undispatched and can be
+retried through that route. Keep HOME, profile and owner state; see
+[host execution permissions](references/agent-execution.md). A lost mutation reply needs
+request/status recovery, never blind retry.
+
+Ghidra operations can exceed the host execution tool's first wait. If it returns a running
+session/cell ID, await that same execution with the host's wait/poll facility until terminal
+status and read its stdout/stderr. An empty first chunk is not a lost CLI response. Do not
+start another open or repeat a CPU mutation while the original command is still running.
+
+Use `ghidra status` to inspect runtime readiness; `ghidra install` delivers the pinned runtime.
+For static managed C#/IL research, locate `insight-cli skill insight-ilspy`.
+For owned process inventory use `tools processes`; `stop` saves Ghidra contexts, while
+`kill` explicitly interrupts verified owned work and preserves its journals.
+For archives, external launchers, server lifecycle or removal, read [managed runtime](references/managed-runtime.md).
+
+This skill and its executable helper are one npm package. Run `insight-cli skill insight-ghidra` to locate
+these installed resources. Use generated `--help` for syntax; read the references as needed.
+Follow applicable project RE rules for tools, source of truth, evidence layout and format;
+this package's walkthroughs fill gaps rather than replacing those conventions.
+
+For coordinating a reverse-engineering investigation with ordinary files, external tools
+and multiple agents, locate the RE workflow with `insight-cli skill insight-re`. When a retained checkpoint is useful, save
+a completed project file or folder with
+`insight-cli artifacts save <path>`; [save semantics](references/artifacts.md) describe the
+ordinary saved copy and its receipt. Neither operation requires a Ghidra installation.
+
+1. Select the configured runtime profile. Ordinary work uses a managed local server; an external
+   server is optional. See [setup](references/setup.md). Factory permissions authorize changes.
+2. Open the input with `ghidra open <input> --session new --json`. Retain the returned session and target.
+   Another agent chooses `new` independently; one session can open several inputs.
+3. Pass both `--session` and `--target` on research calls. Follow strings to xrefs and their
+   function addresses, then inspect/decompile. Decompilation defaults to a 16000-character
+   window; page with `--limit-chars`/`--offset-chars` and retain `textSha256`. Native
+   truncation remains explicit even at the end of the observed text. See [research](references/research.md).
+4. Rename functions or set/clear comments through ordinary commands. An `applied` result means
+   verified saved private work. Other sessions keep their own views; local edits remain unpublished in the default manual mode.
+5. By default, publish explicitly with `ghidra merge`; receive safe shared changes with `ghidra refresh`.
+   Resolve overlapping names/comments against an explicitly observed shared value. A conflict
+   prevents the whole selected merge and retains local work.
+6. Continue with `ghidra open --session <id> --target <id>`. For uncertain outcomes inspect
+   `sessions status <id> --target <id>` and [recovery](references/recovery.md). Supplying a stable
+   optional `--request-id` lets a repeated changing intent retrieve its outcome without rerunning.
+7. Finish by closing each context you own with scoped `ghidra close`, preserving private work.
+   If this profile's local server belongs exclusively to your investigation and all its contexts
+   are closed, use `ghidra server stop`, then verify `ghidra status` has no remaining processes.
+   `ipc-server stop` stops the CLI owner; it does **not** stop Ghidra's local server. Stop that
+   owner last when needed. For a shared profile/server, leave server shutdown to its coordinator;
+   an individual worker closes only its own contexts and never kills unrelated processes.
+
+The facade exposes the pinned static research/editing catalog, merge/refresh, project/server/GUI
+controls, debugger, archive exchange and supported recovery. Preserve private work
+and journals while an outcome is unresolved. The CLI supplies the investigation tools; agents
+choose research goals and interpret findings.
+Installing this package does not register this skill in an agent's configuration.
+
+For project files, program export/import and configured-server administration, read
+[administration](references/administration.md). These operations preserve separate research views;
+their external effects do not participate in program merge.
+
+For owned GUI execution, CPU state, breakpoints and retained traces, read
+[debugger](references/debugger.md). Execution side effects remain separate from program publication.
+
+For explicit external documentation exchange and retained submission outcomes, read
+[archive](references/archive.md).
+
+For selected native SDK extensions (VT, DB differences, byte/assembly edits, formats, GDT,
+FID/BSim, namespaces and typed IR), read [native workflows](references/native-workflows.md).
+
+For managed SDK extension modules, actual language/analyzer/plugin discovery and opt-in
+automatic synchronization, read [extensions and sync](references/extensions-and-sync.md).
+
+For authorized macOS local debugging, use `ghidra debugger launch --stop-at-entry`
+with the returned session/target and `--json`; then inspect status, registers and stack
+before resuming. The default launch runs immediately, so a short program may exit before
+an interrupt. Before resuming from entry, map the selected function and set a live breakpoint at the
+returned dynamic address. Resuming a short program without that breakpoint can run it to
+exit before any call is observed. At the breakpoint verify PC, then read arguments/stack
+and step out or over the call to inspect its actual return.
+Repeat mapping and live breakpoint setup for every new launch. A saved breakpoint bookmark
+does not prove placement in that new process; check its `trace_location_count` before resuming.
+Use `new` only when creating a session; subsequent calls take its actual returned ID.

package/skills/insight-ghidra/references/administration.md

@@ -0,0 +1,34 @@
+# Projects, files and server administration
+
+Research uses root session/target scope. `ghidra projects` manages separate projects inside the
+selected profile; these projects do not select or replace an agent's private context. Use an
+explicit `--project` for create/open/close/info/files and file operations. Closing releases the
+native handle and preserves files; deletion requires Destructive. File listings are paged.
+Moves select a source `--path` and an existing `--destination` folder. Existing names are preserved.
+
+`ghidra program export --session <id> --target <id> --output <file>` saves the selected private
+program as GZF without publishing. `ghidra program import --project <name> --input <gzf>
+--path /folder/program` adds that saved program to a managed project. Importing files does not
+change the immutable target's input identity. Export requires a new output file.
+
+`ghidra projects archive --project <name> --output <gar>` exports a native Ghidra project archive.
+`ghidra projects restore --project <new-name> --input <gar>` restores into a new independent owned
+project. Archive entries cannot escape their destination; restoration accepts at most 100,000
+entries and 4 GiB of declared uncompressed data. Research contexts and pending work remain separate.
+
+Changing operations accept `--request-id`. A verified native completion journal can recover a
+lost project response without executing that operation again. If no complete journal exists,
+changing that project stays blocked; read-only inspection remains available. Partial or different
+export output does not prove success and is preserved. Retain receipts for continuation.
+
+`ghidra server` operates on the configured local or external server. `status` reports connection
+state, including a missing runtime before installation; `start/stop` manage the owned local
+server (stop requires closed contexts). `connect` enables shared operations; `disconnect` releases the owned local server or the
+external connection. Reconnect preserves repositories. Repository/file/history/checkout commands
+require the explicit repository and relevant path. Admin actions require actual server authority
+alongside Factory permissions. Changing ACLs preserves other users and anonymous access.
+Facade reader/publisher authority and canonical publication checkouts remain protected.
+
+Unknown server administration outcomes are retained without blind replay. Server/file effects
+are independent of program merge. Use generated help for flags and Factory profile/secret commands
+for connection configuration.

package/skills/insight-ghidra/references/agent-execution.md

@@ -0,0 +1,36 @@
+# Agent host execution permissions
+
+Keep the user/project host policy and the selected profile. A sandbox can deny writes
+to runtime AppData or access to the local IPC endpoint, including during local help.
+This is a host execution boundary, not evidence that the tool or its inputs are absent.
+
+First retry only `insight-cli --help`, `tools list`, `skill`, or the selected application's
+read-only `status` using the host's normal permission escalation. In Codex, use the
+execution tool's `sandbox_permissions: "require_escalated"` with a scoped explanation
+that the installed CLI needs its existing profile storage/local IPC. Automatic approval
+review or the user decides that request; do not disable the sandbox or approval policy.
+
+Do not work around this by changing HOME/AppData/profile paths, creating another host,
+deleting owner/endpoint files, killing unrelated processes or claiming a missing runtime.
+After the read-only probe succeeds, use the approved execution route for the intended
+public CLI commands. An access refusal explicitly stating **no command was sent** is
+known not dispatched; it is safe to submit that authorized command through the approved
+route. This includes a mutation refused before dispatch. Do not mistake that definite
+pre-dispatch refusal for an unknown execution outcome. Downloads still require their explicit
+network access.
+
+A lost mutation response is different from a denied startup probe: inspect retained
+request/status/recovery evidence and use its request ID when supported. Never blindly
+repeat a publication, script or program run whose outcome is unknown. External-tool
+fallback is allowed by project rules, but record that the intended facade was not used
+and do not invent a successful checkpoint or native result.
+
+## Wait for the original execution
+
+A tool operation may outlast the host execution tool's initial wait. A returned running
+session/cell ID means that command is still in progress, not that the CLI returned no data.
+Use the host's session poll/wait facility until terminal exit and consume stdout/stderr
+before issuing a dependent command. In Codex, an `exec_command` session is continued with
+`write_stdin`; a yielded execution cell uses that host's cell wait. Do not launch a second
+open/install or repeat a CPU action just because the first chunk was empty. If the execution
+really loses its terminal result, use the CLI's request/status recovery as described above.

package/skills/insight-ghidra/references/archive.md

@@ -0,0 +1,32 @@
+# Exchange private documentation with an archive
+
+Archive exchange is disabled until the selected Factory profile has an explicit `archiveUrl`.
+Use HTTPS for a remote service; local HTTP is supported for local services. URLs cannot contain
+credentials, query parameters or fragments. An optional bearer token is stored with
+`auth login --role archive --password-stdin`; it is a Factory secret and is never passed to
+Ghidra or the debuggee. `auth logout` clears this token as well as external server credentials.
+
+Use `ghidra archive ingest-function --address <entry>` or `ingest-program`, with the usual
+`--session` and `--target`. Both export the selected private view. `--version-label` supplies
+the archive version; its default is `unknown`. Internal project directories are not used as
+version labels. Bulk selection skips default function names unless `--include-default-named`
+is set; `--limit` bounds visited functions. Zero selects all, subject to the documented bound.
+`--dry-run` validates payloads and returns would-be counts without a network request.
+
+The service contract is `POST <archiveUrl>/v1/doc_archive/upsert` with JSON and an optional
+`Authorization: Bearer ...` header. The payload matches the pinned GhidraMCP builder: binary
+name, explicit version, function address, run/tool identity, name/prototype, calling convention,
+flags, matching hash/shape metadata, tags, named locals and instruction comments when present.
+The binary name is the logical target name. Each successful JSON response must contain a
+boolean `created` and a nonnegative integer `conflicts_enqueued`. Redirects are refused.
+
+Results retain created, updated, conflict, skipped and error counts. Archive conflict counts
+describe the external service's decisions; they do not resolve program merge conflicts.
+Use an optional stable `--request-id` when a response might be lost. A repeated ID returns
+the saved successful result or the retained uncertain outcome, without sending again.
+Each outbound payload identity and the source snapshot are retained before dispatch. Unknown
+external outcomes stay observable and do not block unrelated private research. A new request ID
+expresses another explicit submission; the facade does not assume the service can deduplicate it.
+
+Archive requests do not publish the program or alter another session. Developing or deploying
+the external archive service is outside this package; acceptance uses an owned contract fixture.

package/skills/insight-ghidra/references/artifacts.md

@@ -0,0 +1,52 @@
+# Save ordinary research materials
+
+`insight-cli artifacts save <path> --json` saves a file or a settled directory tree in
+the selected profile's AppData. It needs Factory Update permission and does not require
+Ghidra, Java, authentication, target/session selectors or evidence metadata. Relative input
+paths resolve against the caller's working directory. Use `--help` for generated syntax.
+
+Save existing project files in their existing format; no `notes.md`, `finding.md` or
+`research/` layout is required. The saved copy is a checkpoint and does not replace the
+project's canonical evidence location or its source-of-truth rules.
+
+Write notes and useful external-tool outputs as ordinary files while investigating. When
+the selected files are no longer being edited, save one file, a completed worker subfolder
+or the relevant project folder. For a project without a prescribed layout, for example:
+
+```sh
+insight-cli artifacts save ./research --json
+```
+
+The receipt has `state: "saved"`, `path`, `kind` (`file` or `directory`), `files`, `bytes`
+and `sha256`. `path` points to an ordinary browsable copy with the source basename and
+relative layout. Empty files and empty directories are retained. File count counts regular
+files; byte count counts their contents. A file's SHA-256 hashes its bytes; a directory's
+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;
+edit the original research folder and save a new copy for another checkpoint. Each call
+creates a new saved copy, including a repeated call after a lost response.
+
+Keep a directory stable for the save: detected concurrent edits are rejected. Copying
+several files is not an atomic filesystem snapshot of a directory that other agents keep
+changing. Symbolic links and special files are rejected rather than followed or silently
+omitted. Select the actual intended regular file/directory. Do not save a directory that
+contains the destination materials store. Traversal supports at most 100,000 entries and
+128 levels to bound inventory memory and recursion. Disk/permission failures return nonzero.
+
+The saved bytes establish what was retained. Commands, tool versions and interpretations
+written in a note remain the author's statements, not execution attestations. No upload,
+tool execution or Ghidra publication is performed by saving materials.
+
+Profile deletion/configuration invalidation is blocked while retained materials exist,
+as with retained research work. Close tool contexts normally; preserve snapshots separately
+if retiring a profile. There is no automatic registration, cleanup policy, graph database
+or additional read API: read the receipt's path with normal file tools.

package/skills/insight-ghidra/references/debugger.md

@@ -0,0 +1,62 @@
+# Debug an input in its private context
+
+Use the same `--session` and `--target` as static research. `debugger launch-offers` lists
+available launchers and starts the owned GUI services when needed. `debugger launch` executes a
+verified copy of the selected immutable input in an owned run directory. It accepts `--offer`,
+`--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
+report whether the trace is connected or retained after disconnection. `--trace` selects a
+saved trace within this context; IDs from another context are rejected.
+
+Changing commands include interrupt, resume, step into/over/out and breakpoint set/remove.
+Their optional request ID retrieves the recorded result without executing again. A genuinely
+unknown CPU action remains uncertain; a later program counter alone does not prove how many
+instructions executed. Read-only observation remains available for uncertain debugger actions.
+Program merge does not roll back execution, debugger I/O or other process side effects.
+
+Trace databases are checkpointed separately from the private program and verified by independent
+packed-database readback before acknowledgment. Reopening after process replacement restores
+saved trace data as disconnected. It does not restart the debuggee or reconstruct CPU execution.
+Ordinary static program edits remain private and retain the usual merge/refresh behavior.
+Static breakpoint bookmarks created by debugger actions also count as pending program changes.
+They follow explicit merge/refresh and complex-change conflict rules; CPU execution does not
+wait for publication, and publishing a program never resumes another session's process.
+
+On macOS, launch enforces the selected working directory, including paths with spaces and
+quotes. A GUI backend crash ends the owned live debuggee through its debugger controller.
+Verified trace data retained before a lost action response is adopted on disconnected continuation,
+unless a later observation already saved a newer view. The CPU action itself remains uncertain.
+
+On macOS, use an installed local LLDB and an executable supported by that host. GUI startup
+prepares the Python wheels already supplied with Ghidra in owned storage; it does not install
+packages into system Python. A launcher's optional Python executable and Windows debugger
+directory are Factory profile settings. Native Windows/Linux acceptance remains deferred.
+
+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/skills/insight-ghidra/references/extensions-and-sync.md

@@ -0,0 +1,124 @@
+# Managed extensions and synchronization
+
+`insight-cli` keeps targets/sessions above tools. Both features below belong to the Ghidra
+context/runtime selected by the existing profile; they introduce no new agent/session objects.
+The Factory API uses the same command paths and options as these CLI examples.
+
+## Consume a ready-built SDK extension
+
+Use an unpacked standard Ghidra 12.1.2 extension module, with `Module.manifest` and
+`extension.properties` at its root. Directory basename and property `name` must agree.
+The module can contain compiled `lib/*.jar`, `data/languages` (including compiled Sleigh `.sla`,
+`.ldefs`, `.pspec`, `.cspec`) and `ghidra_scripts`. Build the extension with its own upstream
+SDK build before consumption. ZIP acquisition/extraction, dependency resolution, building a
+third-party extension and publishing extensions are outside this local management contract.
+
+```sh
+insight-cli ghidra extensions inspect --directory ./MyExtension --json
+insight-cli ghidra extensions install --directory ./MyExtension --sha256 <content-sha256> --json
+insight-cli ghidra extensions list --json
+```
+
+Inspect computes the content identity without executing extension code. Install requires the
+`Destructive` permission, consumes all regular files into profile storage and verifies the
+copy. It never edits the installed SDK or depends on the original directory after consumption.
+The identity covers sorted relative paths, SHA256 and size for every file; it is not a ZIP hash.
+Symlinks/special files, hidden/traversing paths and incompatible version metadata reject.
+Limits: 32 modules/profile, 8192 files and 256 MiB/module, 16 path components.
+A name stays pinned to one content identity; different builds use different module names or profiles.
+
+```sh
+insight-cli ghidra extensions disable --name MyExtension --json
+insight-cli ghidra extensions enable --name MyExtension --json
+```
+
+Stop the Factory IPC owner after changing the enabled set, then run the next ordinary command.
+A running owner refuses changed runtime configuration. Immutable module copies remain retained
+when disabled, so saved contexts can resume with their original language/type dependencies after
+re-enabling. Existing private work and unknown request/publication journals are preserved.
+Disabling the language required by a saved program does not convert that program to another language.
+Enablement/install are desired-state/content operations; repeating the same input is idempotent.
+No automatic extension updates or network/package-manager installation occur.
+
+Discover what the installed SDK actually provides:
+
+```sh
+insight-cli ghidra extensions capabilities --kind languages --filter MyProcessor --json
+insight-cli ghidra extensions capabilities --kind analyzers --filter MyExtension --json
+insight-cli ghidra extensions capabilities --kind plugins --filter MyExtension --json
+```
+
+These paged inventories return actual native IDs (and compiler IDs for languages); `managed`
+on analyzer/plugin classes identifies consumed modules. Select a language/compiler using
+`ghidra open --language <id> --compiler-spec <id>`. Use `analysis configure-analyzer --name <name>
+--enabled true` and `analysis reanalyze` in an explicit context. Program writes remain complex
+private changes and follow the existing saved-state verification/merge rules.
+Extension scripts have explicit inventory IDs such as `extension:MyExtension/Example.java`;
+run that ID through `scripts run`, never guess a process-global search path.
+
+For a GUI plugin, use `ghidra plugins set --plugin <class-id> --enabled true|false` with
+`--session` and `--target`. `plugins list` returns enabled managed plugins in that owned GUI tool.
+Only classes from enabled managed modules can be toggled. Enablement is read back immediately;
+its lifetime is the current GUI tool, rather than a promise to resurrect it after a crash.
+Plugin constructors/disposal may change program state: the operation saves a private snapshot
+and conservatively records a complex change. An uncertain effect is never replayed; close the
+owned context when its live effect cannot be established. Configuration dialogs, arbitrary
+plugin-specific option schemas, native libraries with platform installers and hot class unloading
+are not promised by this module contract; the explicit script API remains available.
+
+Extension code runs with the OS privileges of the owned JVM. Digest pinning establishes which
+code runs, not a security sandbox or a guarantee of third-party compatibility. Workers, GUI,
+inspection and publication helpers use the same verified enabled set. The storage-only local
+Ghidra Server continues to use the pinned base SDK and does not run managed analysis plugins.
+
+## Optional synchronization for one context
+
+The default remains explicit `merge` and `refresh`. Reads keep the private view. Configure an
+existing `(session, target, ghidra)` context explicitly:
+
+```sh
+insight-cli ghidra sync-policy get --session s_a --target t_exe --json
+insight-cli ghidra sync-policy set --session s_a --target t_exe \
+  --publish after-edit --refresh before-edit --json
+```
+
+| Setting | Behavior |
+| --- | --- |
+| `--publish manual` | Local edits and saves do not publish automatically. |
+| `--publish after-edit` | After a supported program edit has a verified saved acknowledgment, merge all pending work in that context. Also publishes pending work on explicit `ghidra save`. |
+| `--publish after-save` | Ordinary edits stay private; explicit scoped `ghidra save` merges all pending work after saving. |
+| `--refresh manual` | No automatic incoming update. |
+| `--refresh before-edit` | Refresh before a program-edit command; any returned conflict stops that edit before dispatch. Safe incoming changes from the refresh remain retained. |
+
+Supported program-edit commands include ordinary names/comments, types, bytes/assembly,
+analysis and scripts. Policy excludes control commands (`open`, `close`, `merge`, `refresh`,
+policy/discard), cross-target transfer, GUI/debugger, archive/project/server operations, file
+exports, library databases and Version Tracking. Session-wide `save-all` saves privately;
+use scoped `save` for automatic publication. Read-only queries never trigger refresh/publication.
+Automatic refresh/publication also requires the current Factory `Update` permission, including
+when the edit itself is gated by `Destructive`. Revocation prevents starting those automatic
+effects; retrieval of a completed workflow does not repeat them. No background timers, watchers
+or automatic semantic conflict resolution are introduced.
+
+A successful automatic edit includes its normal local result plus `automatic.refresh` and/or
+`automatic.publication`, final `pendingChanges` and `sharedState`. After a publication conflict,
+the command fails with `state: conflict`, `localApplied: true` and the retained `local` result.
+Nothing from that merge is published. An incoming conflict reports `phase: refresh` and
+`localApplied: false`; the requested edit was not started. Lost local replies may report
+`localOutcome: unknown`; they do not falsely assert that the local effect failed.
+
+Automatic merge uses exactly the manual contract: any conflict prevents the whole publication;
+only verified scalar categories combine after divergence; complex divergence retains both
+versions. Use explicit refresh, inspect/resolve scalar conflicts, or transfer complex changes
+onto a current base. A failed automatic workflow does not silently retry after resolution;
+use a new request or explicit merge for the new intention.
+
+Policy survives owner replacement. Optional request IDs (up to 128 characters) bind the local edit, incoming refresh and publication workflow. Repeating the same ID/input
+retrieves its result or reconciles the original publication; it never replays a check-in or
+uncertain script. The original workflow keeps its original policy even if policy changes later.
+Retrying an earlier manual edit does not retroactively publish it after enabling automatic mode.
+Without a request ID, a call is a new intention, as elsewhere in the facade.
+
+The caller ID reserves the complete automatic workflow in the common profile namespace, even
+when incoming conflicts prevent the local command from starting. It cannot be reused by an
+explicit merge, close, export or administration operation. Internal child effects have derived IDs.